docs(render): state the seal's guarantees, residuals and operator steps after review

- docs(render): state how the bounded reader's guarantee is established
  SECURITY-MATRIX row 27 now says the reader's agreement with
  hayro-syntax 0.7.2 rests on a reading of that version's source, with
  one regression test for each difference found, rather than exhaustive
  or fuzzed proof, and that the pin makes any new version repeat that
  reading. The signature check is said to see every object the
  cross-reference table lists, which is what the stream refusals give.

- docs(render): state the seal's outside calls and the serving clients in the concept
  The removed Definition of Done carried two rules the concept did not: the
  seal route's calls beyond OIDC (the Transit signing proxy and the timestamp
  authority, from the serving process only), and the serving clients, which
  call the HTTP routes and hold no rendering code. The concept now states
  both, and no longer lists a client crate as outside version 1.

  The example bundles' PDF/A note now names the bundles it covers, since the
  seal fixture's veraPDF runs are recorded in EVIDENCE.md.

- docs(render): state the seal's remaining accepted residuals in the matrix
  The security matrix is Render's security document, so each accepted
  residual the seal work leaves is stated there: a worker with code
  execution can signal the serving process; reading a local-jwk key file
  leaves two copies of key text in dependencies that Render does not erase;
  and /ready is unauthenticated, so any caller who reaches the listener reads
  seal readiness and can make a not-ready Transit seal probe once at a time.
  The timestamp authority's unpinned identity was already stated.

- docs(render): say what the serve suite and the two-OS golden job establish
  Both named the removed Definition of Done as their purpose. The serve
  suite's module comment now lists what it covers, and the golden record
  says what identical hashes on macOS and Linux prove.

- docs(render): close the operator gaps a real OpenBao seal run found
  An end-to-end run against OpenBao 2.7.2 passed every step, but each of
  these needed knowledge the operate page did not give:

  - Where the Transit key, its policy and the proxy come from: the Evidence
    Transit tutorial's, since Render makes the same key read and prehashed
    sha2-256 sign with the pinned key_version.
  - How Render finds the issuer's keys: discovery, or jwksSource as a URI or
    a static key set held as a secret.
  - What turns the test seal's signing block into a working seal: the
    authentication block, `seal: ministry` in the manifest and a new
    package, and a caller token with render:seal from an allowed client.
  - Why a secret file is refused: a file secret must be a regular file the
    serving user owns, mode 0400 or 0600, with one link.
  - What readiness reads for Transit: the signer's last known state, so a
    seal turns signer-not-ready only once a sign call fails.

Signed-off-by: Jeremi Joslin <jeremi@joslin.fr>

Author: jeremi

crates/registry-render/tests/serve.rs

@@ -1,7 +1,9 @@
 //! End-to-end serve tests: the real `registry-render` binary serving real
 //! requests, spawning real supervised workers, writing a real audit file
-//! through the platform audit writer. These tests are the DoD's serve-mode
-//! acceptance coverage.
+//! through the platform audit writer. They cover the render route end to end:
+//! authentication, the PDF and JSON answers, the paired audit entries,
+//! package verification at startup and per render, body limits, bounded
+//! problems and pathological renders.
 
 use std::collections::{BTreeMap, BTreeSet};
 use std::fs::File;

docs/site/src/content/docs/operate/registry-render.mdx

@@ -117,6 +117,10 @@ These rules are not in the tables:
 - `secret:file/<name>` resolves under `secretProviders.file.root`. `secret:env/<NAME>` works only
   when `secretProviders.environment: {}` is declared. A reference to an undeclared provider is
   refused.
+- A file a `secret:file/` reference names (the API key, an OIDC key set, a seal key, a CA bundle)
+  is a regular file owned by the user serve runs as, with mode `0400` or `0600` and a single link.
+  Serve follows no symbolic link to one, and refuses any other file at startup with
+  `runtime-invalid` and the message `the referenced secret file is unsafe`.
 - A string value may come from the environment as `${VAR}`, `${VAR:-default}`, or
   `${VAR:?message}`, except in `apiKeyRef` and under `secretProviders`.
 - `audit.destination: stdout` hands entries to your collector and takes no `path`.
@@ -266,7 +270,14 @@ certificate, its issuer, and how you hold the key.
 You need an OIDC deployment (a seal never works with the legacy API key), a seal certificate chain
 in a PEM file with the seal certificate first, and the seal key in Vault or OpenBao Transit: an
 `ecdsa-p256` key created non-exportable, reached through a Transit signing proxy on a Unix socket
-on the Render host. The proxy holds the Transit token; Render sends none. With the proxy running,
+on the Render host. The proxy holds the Transit token; Render sends none. Create the key and its
+least-privilege policy as
+[Configure Transit signing for Registry Evidence](../../tutorials/move-evidence-to-production-signing/#create-the-transit-key-and-its-policy)
+does, and run the proxy
+[with a forced token](../../tutorials/move-evidence-to-production-signing/#run-the-proxy-with-a-forced-token),
+its socket group admitting the Render service. Render makes the same calls, a read of the key and a
+prehashed `sha2-256` sign with the pinned `key_version`, so that policy works with your key name and
+version in place of Evidence's. With the proxy running,
 `registry-render keygen --csr <file> --common-name <seal name> --transit-unix-socket-path
 <socket> --transit-mount <mount> --transit-key-name <key> --transit-key-version <version>` reads
 the key version's public key and has Transit sign the certificate request your certificate
@@ -301,6 +312,11 @@ signing:
       trust: production
 ```
 
+Render reads the issuer's signing keys from its OpenID Connect discovery document, or from
+`authentication.oidc.jwksSource`: a key set URL (`type: uri`) or a key set held as a secret
+(`type: static` with `documentRef`, such as `secret:file/jwks.json`).
+[Connect an OIDC issuer](../advanced/connect-an-oidc-issuer/) covers each choice.
+
 - `trust` is required. `production` marks an official seal, and it signs through `transit` only:
   Render refuses a production seal with a key file
   (`render.runtime.seal-signer-assurance-mismatch`). `test-only` marks a test seal; see
@@ -442,8 +458,12 @@ signing:
       trust: test-only
 ```
 
-Then run `check --environment` and `serve` as above. `test-root.key` can issue certificates: keep
-it out of every deployment, and never trust the test root outside development.
+Put this `signing` block in a runtime file that has the `authentication` block from
+[Enable a seal](#enable-a-seal). Name the seal in the document type's `manifest.yaml` entry with
+`seal: ministry`, and run `registry-render package` again. Then run `check --environment` and
+`serve` as above. Callers need a token from your issuer that carries `render:seal`, issued to a
+client the seal's `allowedClients` names. `test-root.key` can issue certificates: keep it out of
+every deployment, and never trust the test root outside development.
 
 ### Renew the certificate
 
@@ -467,8 +487,10 @@ When seals are configured, `/ready` adds a `signing` member with one entry per s
 `certificate-expired`, `certificate-not-yet-valid`, or `signer-not-ready`. A seal never changes
 the status code: Render stays ready for plain rendering while a seal cannot sign, and a seal
 request answers `signing-unavailable` or `seal-certificate-invalid` (503) until it can. Readiness
-reads the certificate validity and the key provider; it never calls the timestamp authority, so a
-ready seal can still fail with `timestamp-failed`.
+reads the certificate validity and the signer's last known state; it never calls the timestamp
+authority, so a ready seal can still fail with `timestamp-failed`. A Transit seal turns
+`signer-not-ready` only after a sign call fails, so after its proxy stops, `/ready` reports it
+ready until a seal request fails.
 
 A Transit seal whose proxy stops answering fails the seal request in progress with
 `signing-unavailable` and turns `signer-not-ready`. Each `/ready` call and each seal request then

products/render/CONCEPT.md

@@ -11,7 +11,10 @@ APIs. It is a pure rendering function (bundle + validated data in,
 byte-stable PDF + hashes out), a governed template package as its
 content unit, and a value-free audit log as its issuance record.
 No database or rendering-path network calls, and no engine changes in any other
-product. Only the optional HTTP adapter uses OIDC discovery/JWKS networking.
+product. Only the optional HTTP adapter makes outside calls: OIDC discovery and
+JWKS, and for an optional seal, the Transit signing proxy on a host Unix socket
+and the timestamp authority, both from the serving process, never the render
+worker.
 
 ## Document families
 
@@ -31,9 +34,9 @@ record through an app-owned public check route and an Evidence-backed relying
 service. The app owns the bounded answer and its disclosure policy; Render
 mints nothing and does nothing at scan time.
 
-Version 1 has no batch or multi-document request, client crate, TLS
-termination, per-tenant rate limiting, metrics route, or hot reload or runtime
-bundle editing, and no document-type-specific behavior in production code.
+Version 1 has no batch or multi-document request, TLS termination, per-tenant
+rate limiting, metrics route, or hot reload or runtime bundle editing, and no
+document-type-specific behavior in production code.
 
 ## Sealing
 
@@ -111,7 +114,10 @@ house product anatomy: `init`/`check`/`validate`/`package`/`compile`/`serve`/
 runtime configuration loader) for deployment-local bindings; the
 `registry-platform-*` primitives (config loader and secrets, httpsec layers and
 problems, the shared audit writer, authcommon key handling, buildinfo, canonical
-JSON) reused rather than reinvented.
+JSON) reused rather than reinvented. The serving clients,
+`registry-render-client` in Rust with its Node and Python bindings
+(`registry-render-client-node`, `registry-render-client-py`), call the HTTP
+routes and hold no rendering code.
 
 The rendering engine is Typst in library mode, pinned at 0.15.1 with a
 lockfile matched to the Typst release — including the deflate stack,

products/render/EVIDENCE.md

@@ -294,8 +294,8 @@ cargo test -p registry-render --test golden   # fails with the drift first
 ```
 
 The two-OS CI job (see `.github/workflows/render-golden.yml`) runs the
-golden test on macOS and Linux; identical hashes across both are the
-cross-machine byte-stability proof the DoD requires.
+golden test on macOS and Linux; identical hashes across both prove that
+the same inputs give the same bytes on both operating systems.
 
 **Regenerated 2026-09-17, example corpus made generic.** The three example
 bundles named one real programme, its institution, its jurisdiction and its

products/render/README.md

@@ -50,9 +50,9 @@ Latin font set. Scripts beyond Latin (Arabic, Hebrew, …) need a bundle font
   the golden-hash record.
 - `bundles/` — three immutable packaged examples: a bilingual RTL receipt, a
   PDF/A-4 certificate, and an ID-1 duplex card with a photo. Formal PDF/A
-  conformance validation (for example veraPDF) is not run; the evidence
-  records only that the `pdfaid:part` marker is present. Use them with
-  `check`, `compile`, or `serve`; start editable source with
+  conformance validation (for example veraPDF) is not run on these bundles;
+  the evidence records only that the `pdfaid:part` marker is present. Use
+  them with `check`, `compile`, or `serve`; start editable source with
   `registry-render init`.
 - `integrations/` — the OpenFn job and App Kit wiring sketches.
 - `schemas/`: JSON Schemas for `manifest.yaml`, `labels/<locale>.yaml`, and