Render and sign — end-to-end

Last updated Jun 14, 2026

A tier_3 agent renders + signs a Matter document in three calls. Each returns 202 Accepted immediately; terminal outcomes arrive via the WebhookOutbox in strict per-entity sequence order.

POST /v1/templates/{template_id}/render
POST /v1/signing_envelopes
POST /v1/signing_envelopes/{id}/send

Step 1 — render

POST /templates/{template_id}/render does seven things atomically:

1. Authenticate + budget. Resolve token, check it's not revoked, check per-(orgId, mode) render budget (default 200 fresh fingerprints per hour; restricted-classification renders cost 5×). Per-token cap: 50/hour. Over-budget → 429 render_budget_exhausted with Retry-After.

2. Resolve revision + jurisdiction. Defaults to latest ga revision and the entity's formation_jurisdiction. The caller may pin either via query parameters.

3. Load + compose overlays. Four-layer composition (platform → variant → org → entity) with the three-position grammar guard.

4. Validate parameters. Zod .strict() against fields.schema.json; rejected unknown keys with 422 additional_properties_not_permitted.

5. Classify. Compute Document.classification as the max of classifications across present parameters. Per-classification tier check: restricted requires tier_3 + PKCE consent nonce. The classification is immutable post-creation; subsequent reclassification of a field in a new revision doesn't retro-bump this Document.

6. Compute render_fingerprint. SHA-256 over (template_revision_id ∥ overlay_hash ∥ canonical_json(parameters) ∥ mode ∥ classification). For confidential / restricted, the orgId is folded in — cross-org cache collisions are impossible by construction.

7. Queue the job. Inserts TemplateRenderJob + BackgroundJob + WebhookOutbox rows in one transaction. Cache lookup: if a Document with the same render_fingerprint already exists for this org, return its id; queue-collapse is org-scoped.

Returns 202 Accepted with { request_id, render_fingerprint }.

The render worker (driven by the existing apps/api/app/cron/process-background-jobs/route.ts poller, NOT Inngest) drains the queue. Concurrency caps via Upstash Redis token bucket: 16 react-pdf + 4 Playwright per region. Backpressure hysteresis: queue depth >= 500 → API returns 429 until depth drops below 250.

When the render completes, the worker writes a Document row, publishes the rendered PDF to Vercel Blob at renders/<render_fingerprint>.pdf (restricted lands in renders-restricted/ with 60-second signed-URL TTLs), and emits document.rendered_from_template via the WebhookOutbox.

Step 2 — envelope

POST /signing_envelopes wraps the Document in a signing envelope:

POST /v1/signing_envelopes
{
  "document_ids": ["doc_..."],
  "signers": [
    {
      "role": "sole_director",
      "stakeholder_id": "stk_..."
    }
  ]
}

The envelope captures at create time:

• ESRA disclosure packet hash (the version of the disclosure the signer is consenting to)
• Intent text
• Disclosure version pin (so a later disclosure-text rewrite doesn't retroactively change the consent the signer gave)

Per-signer consent records are minted at this step, NOT at signer- portal time. This matters for round-2 finding F15: deferring consent capture to portal time would weaken the legal_basis: esra_consent signatures.

Step 3 — send

POST /signing_envelopes/{id}/send dispatches signing invitations (email via Resend; SMS where supported). Signers complete via the SigningSession portal at https://sign.mattermode.com/{session_id}.

The portal:

• Verifies the signer's identity (email OTP or Clerk OAuth).
• Renders the document with the test-mode watermark if applicable.
• Surfaces the Trust card for forks ( "This document is customized by ...").
• Captures the signature with signing_key_fingerprint, signature_method, IP, user-agent, and timestamp.
• Records the ESRA consent against the version captured at envelope create.

Archive on final signature

When the final signer signs, the archive worker:

1. Snapshots the MCTF directory of template_revision_id into a tar with inlined font binaries (byte-deterministic re-render in 2033).
2. Fetches RFC 3161 timestamps from DigiCert + FreeTSA in parallel.
3. Wraps restricted parameters in per-data-subject AES-256-GCM envelopes (key in KMS).
4. Builds the audit-chain segment with KMS Ed25519 signatures plus the public Rekor anchor records that cover the segment.
5. Writes the bundle to S3 Object Lock with 7-year Compliance retention.
6. Sets Document.archive_uri. Emits document.archived via the WebhookOutbox.

Webhook ordering

Every webhook flows through WebhookOutbox, which guarantees strict per-(entityId) sequence ordering:

template_render_job.queued
template_render_job.succeeded
document.rendered_from_template
signing_envelope.created
signing_envelope.sent
document.sent
signing_envelope.completed
document.executed
document.archived

The dispatcher is single-instance and drains in (entityId, sequenceNumber) order. A stuck retry on one entity does not block events for unrelated entities; per-entity advisory locks serialize allocations without cross-entity contention.

See also

• MCTF format — the seven-file directory shape.
• Customization — overlay grammar.
• Test-mode safety — three-layer defense.
• Evidence bundle — what the archived bundle contains and how a court verifies it.