diff --git a/docs/site/astro.config.mjs b/docs/site/astro.config.mjs index 96fa465d0..3517f9043 100644 --- a/docs/site/astro.config.mjs +++ b/docs/site/astro.config.mjs @@ -144,10 +144,11 @@ export default defineConfig({ // Retired first-call and source-review routes enter the supported local path. '/start/your-first-call/': internalRedirect('/tutorials/publish-spreadsheet-secured-registry-api/'), '/start/test-current-source-revision/': internalRedirect('/start/quickstart/'), - // The retired hosted lab tutorial lands on a chooser that distinguishes - // that flow from the supported local beginner path. Solmara Lab keeps its - // own route: it is where the two doors are shown working together. + // Retired lab tutorials land on the current chooser or Evidence Gateway + // overview. The historical Solmara workflow used an obsolete Relay source + // path and is no longer published as current guidance. '/tutorials/first-run-with-registry-lab/': internalRedirect('/start/quickstart/'), + '/tutorials/first-run-with-solmara-lab/': internalRedirect('/start/evidence-quickstart/'), '/tutorials/review-a-dhis2-evidence-source/': internalRedirect('/tutorials/issue-immunization-evidence-from-dhis2/'), // Retired monorepo lab tutorials redirect to the current integration guidance. // Retired advanced tutorials land on current task, explanation, or @@ -208,7 +209,7 @@ export default defineConfig({ }), starlight({ title: 'Registry stack docs', - description: 'Documentation for Registry Stack: Registry Relay and Evidence, the runtime services that publish protected registry data and answer bounded questions with signed, minimum-disclosure assertions.', + description: 'Documentation for Registry Stack: Registry Relay and Evidence Gateway, the runtime services that publish protected registry data and answer bounded questions with signed, minimum-disclosure assertions.', // Historical archives keep their sealed search posture. A new released // archive is built once on the release runner and carries its exact // Pagefind output into production. @@ -223,7 +224,7 @@ export default defineConfig({ // Released archives carry their machine-readable corpus into the // canonical root. Historical archives retain their sealed output. ...(isHistoricalArchiveBuild ? [] : [starlightLlmsTxt({ - description: 'Documentation for Registry Stack: tutorials, product docs, explanation, and API reference for Registry Relay and Evidence.', + description: 'Documentation for Registry Stack: tutorials, product docs, explanation, and API reference for Registry Relay and Evidence Gateway.', details: DISCOVERY_HEADER, exclude: ['reference/apis/**'], promote: ['index*', 'explanation/**'], @@ -245,7 +246,7 @@ export default defineConfig({ { base: 'reference/apis/evidence', schema: './openapi/registry-evidence.openapi.json', - sidebar: { label: 'Evidence API operations', collapsed: true }, + sidebar: { label: 'Evidence Gateway API operations', collapsed: true }, }, ]), ], @@ -285,35 +286,70 @@ export default defineConfig({ items: [ { label: 'Overview', link: '/' }, { label: 'When Registry Stack fits', slug: 'start/when-to-use' }, - { label: 'Evaluate Evidence', slug: 'start/evaluate-evidence' }, + { label: 'Evaluate Evidence Gateway', slug: 'start/evaluate-evidence' }, ], }, { - label: 'Answer with Evidence', + label: 'Answer with Evidence Gateway', items: [ { label: 'Overview', slug: 'start/evidence-quickstart' }, - { label: 'Get your first assertion', slug: 'tutorials/first-evidence-assertion' }, - { label: 'Return a governed value', slug: 'tutorials/return-a-governed-value' }, - { label: 'Control caller access', slug: 'tutorials/control-who-can-request-evidence' }, - { label: 'Bind a relationship', slug: 'tutorials/assert-a-role-bound-relationship' }, - { label: 'Issue parent evidence from OpenCRVS', slug: 'tutorials/verify-a-registered-parent-with-opencrvs' }, - { label: 'Request a birth certificate SD-JWT VC', slug: 'tutorials/issue-a-birth-certificate-vc-from-opencrvs' }, - { label: 'Issue DHIS2 immunization evidence', slug: 'tutorials/issue-immunization-evidence-from-dhis2' }, - { label: 'See safe refusals', slug: 'tutorials/refuse-unsafe-evidence-requests' }, - { label: 'Draft an institution source', slug: 'tutorials/connect-an-institution-source' }, - { label: 'Prove a project', slug: 'tutorials/prove-an-evidence-project' }, - { label: 'Build and deploy a project', slug: 'tutorials/build-and-deploy-evidence-project' }, - { label: 'Issue access tokens with Mint', slug: 'tutorials/issue-evidence-access-tokens-with-registry-mint' }, - { label: 'Integrate a candidate with Compose', slug: 'tutorials/integrate-evidence-candidate-with-docker-compose' }, - { label: 'Verify as a consumer', slug: 'tutorials/verify-an-assertion-as-a-consumer' }, - { label: 'Manage verifier trust', slug: 'tutorials/manage-evidence-verifier-trust' }, - { label: 'Request SD-JWT VC', slug: 'tutorials/request-evidence-as-sd-jwt-vc' }, - { label: 'Configure Evidence', slug: 'configure/evidence' }, - { label: 'Configure Registry Mint', slug: 'configure/mint' }, - { label: 'Request a token from your own code', slug: 'configure/request-an-access-token' }, - { label: 'Rotate signing keys', slug: 'tutorials/move-evidence-to-production-signing' }, - { label: 'Verify the audit chain', slug: 'operate/evidence-audit' }, - { label: 'See it over a Relay API', slug: 'tutorials/first-run-with-solmara-lab' }, + { + label: 'Learn locally', + collapsed: true, + items: [ + { label: 'Get your first assertion', slug: 'tutorials/first-evidence-assertion' }, + { label: 'Return a governed value', slug: 'tutorials/return-a-governed-value' }, + { label: 'Control caller access', slug: 'tutorials/control-who-can-request-evidence' }, + { label: 'See safe refusals', slug: 'tutorials/refuse-unsafe-evidence-requests' }, + { label: 'Model a two-subject relationship', slug: 'tutorials/assert-a-role-bound-relationship' }, + ], + }, + { + label: 'Connect a source', + collapsed: true, + items: [ + { label: 'Create a source from OpenAPI', slug: 'tutorials/connect-an-institution-source' }, + { label: 'OpenCRVS: registered parent', slug: 'tutorials/verify-a-registered-parent-with-opencrvs' }, + { label: 'OpenCRVS: birth certificate SD-JWT VC', slug: 'tutorials/issue-a-birth-certificate-vc-from-opencrvs' }, + { label: 'DHIS2: immunization summary (under review)', slug: 'tutorials/issue-immunization-evidence-from-dhis2' }, + ], + }, + { + label: 'Prepare and deploy', + collapsed: true, + items: [ + { label: 'Test with fixtures', slug: 'tutorials/prove-an-evidence-project' }, + { label: 'Configure Evidence Gateway', slug: 'configure/evidence' }, + { label: 'Build a production candidate', slug: 'tutorials/build-and-deploy-evidence-project' }, + { label: 'Deploy with Docker Compose', slug: 'tutorials/integrate-evidence-candidate-with-docker-compose' }, + ], + }, + { + label: 'Authenticate callers', + collapsed: true, + items: [ + { label: 'Add Mint to Evidence Gateway', slug: 'tutorials/issue-evidence-access-tokens-with-registry-mint' }, + { label: 'Configure Registry Mint', slug: 'configure/mint' }, + { label: 'Call Mint from application code', slug: 'configure/request-an-access-token' }, + ], + }, + { + label: 'Verify and trust', + collapsed: true, + items: [ + { label: 'Verify and retain an assertion', slug: 'tutorials/verify-an-assertion-as-a-consumer' }, + { label: 'Enable SD-JWT VC', slug: 'tutorials/request-evidence-as-sd-jwt-vc' }, + { label: 'Manage verifier trust', slug: 'tutorials/manage-evidence-verifier-trust' }, + ], + }, + { + label: 'Operate Evidence Gateway', + collapsed: true, + items: [ + { label: 'Rotate signing keys', slug: 'tutorials/move-evidence-to-production-signing' }, + { label: 'Verify the audit chain', slug: 'operate/evidence-audit' }, + ], + }, ], }, { @@ -350,7 +386,7 @@ export default defineConfig({ collapsed: true, items: [ { label: 'Overview', slug: 'security' }, - { label: 'Evidence security model', slug: 'security/evidence' }, + { label: 'Evidence Gateway security model', slug: 'security/evidence' }, { label: 'Report a vulnerability', slug: 'security/report-a-vulnerability' }, { label: 'Security support window', slug: 'security/support-window' }, { label: 'Release trust', slug: 'security/openssf-evidence' }, @@ -372,13 +408,13 @@ export default defineConfig({ items: [ { label: 'Overview', slug: 'reference/apis' }, { label: 'Relay (narrative)', slug: 'reference/apis/registry-relay' }, - { label: 'Evidence (narrative)', slug: 'reference/apis/registry-evidence' }, + { label: 'Evidence Gateway (narrative)', slug: 'reference/apis/registry-evidence' }, // Generated operation pages for each schema (theme-aware, searchable). ...openAPISidebarGroups, ], }, { label: 'Errors and status codes', slug: 'reference/errors' }, - { label: 'Evidence problems', slug: 'reference/evidence-problems' }, + { label: 'Evidence Gateway problems', slug: 'reference/evidence-problems' }, { label: 'Registry Mint', slug: 'reference/mint' }, { label: 'Diagnostic catalogs', @@ -404,17 +440,17 @@ export default defineConfig({ collapsed: true, items: generatedProduct('Manifest').items, }, - // Evidence entered the product docset after every archived + // Evidence Gateway entered the product docset after every archived // docset was sealed, so its group is optional: absent when an - // archived docset's generated sidebar has no Evidence product. + // archived docset's generated sidebar has no Evidence Gateway product. // generate-sidebar.test.mjs pins its presence for the current // docset, keeping the loud-failure property there. - ...(optionalGeneratedProduct('Evidence') + ...(optionalGeneratedProduct('Evidence Gateway') ? [ { - label: 'Registry Evidence', + label: 'Evidence Gateway', collapsed: true, - items: generatedProduct('Evidence').items, + items: generatedProduct('Evidence Gateway').items, }, ] : []), @@ -449,7 +485,7 @@ export default defineConfig({ { label: 'RS-DOC · Documentation framework', slug: 'spec/rs-doc' }, { label: 'RS-TERMS · Terms', slug: 'spec/rs-terms' }, { label: 'RS-ARC-G · Architecture', slug: 'spec/rs-arc-g' }, - { label: 'RS-PR-EVIDENCE · Evidence protocol', slug: 'spec/rs-pr-evidence' }, + { label: 'RS-PR-EVIDENCE · Evidence Gateway protocol', slug: 'spec/rs-pr-evidence' }, { label: 'RS-PR-REGISTRYCTL · registryctl contract', slug: 'spec/rs-pr-registryctl' }, { label: 'RS-PR-RELAY · Relay protocol', slug: 'spec/rs-pr-relay' }, { label: 'RS-SEC-G · Security model', slug: 'spec/rs-sec-g' }, diff --git a/docs/site/docs/style-guide.md b/docs/site/docs/style-guide.md index 00c5b84a0..a50d89d1c 100644 --- a/docs/site/docs/style-guide.md +++ b/docs/site/docs/style-guide.md @@ -97,10 +97,11 @@ Preferred terms. | Domain | Preferred | | --------------------- | ---------------------------------------------------- | | Product family | `registry stack` (lowercase) for the concept; `Registry Docs` for the site and repo | -| Formal product names | `Registry Platform`, `Registry Manifest`, `Registry Relay` (Title Case), and `Evidence` (a proper noun, no `Registry` prefix); `Registry Mint` is a supporting service, not one of the four | +| Formal product names | `Registry Platform`, `Registry Manifest`, `Registry Relay`, and `Evidence Gateway` (Title Case); `Registry Mint` is a supporting service, not one of the four | | Retired product | `Registry Notary` keeps its Title Case name, but only where the page says in the same block that it is retired | | External adopter demo | `Solmara Lab` (Title Case); not a formal Registry Stack product | | Repo slugs | `registry-platform`, `registry-manifest`, `registry-relay`, `registry-evidence`, and `registry-mint`; `solmara-lab` for the external adopter demo (monospace) | +| Legacy identifiers | `registry-evidence-gateway-pdp/v1` is a Relay PDP profile identifier. It does not name or connect to the Evidence Gateway product. | | Legacy repo paths | `registry_relay` and `decentralized-evidence-demo` appear only in historical pages or `rename_status` fields. Never in prose on a `current` page without explicit rename context. | | Standards | Use the official acronym after spelling on first use. `DCAT`, `SHACL`, `OGC API Records`, `SD-JWT VC`, `CCCEV`. Never translate. | @@ -110,7 +111,7 @@ Preferred terms. - All items start with a capital letter. - Parallel structure. All items are noun phrases, or all are imperative verbs. Do not mix. - No period if every item is a fragment. Period on every item if any item is a complete sentence. -- Use the Oxford comma in prose: `Manifest, Relay, and Evidence`. +- Use the Oxford comma in prose: `Manifest, Relay, and Evidence Gateway`. - Do not use bold inside list items for keywords. Reserve bold for UI labels. ## Code, commands, paths diff --git a/docs/site/public/images/registry-architecture-flow.svg b/docs/site/public/images/registry-architecture-flow.svg index 501da3ef8..dadeb03a9 100644 --- a/docs/site/public/images/registry-architecture-flow.svg +++ b/docs/site/public/images/registry-architecture-flow.svg @@ -2,7 +2,7 @@ font-family="'Public Sans', system-ui, -apple-system, BlinkMacSystemFont, sans-serif" text-rendering="geometricPrecision"> Registry architecture flow - Registry Platform provides shared primitives to both runtime services. Registry Manifest produces portable metadata contracts describing what a registry exposes. Registry Relay binds those descriptions to real sources and serves protected read-only APIs and typed consultations. Evidence answers one bounded question about one subject and returns a signed assertion carrying the answer and not the record; it reads a Relay API as one ordinary fixed HTTP source. Registry Mint is a supporting service that issues the short-lived access tokens Evidence verifies, for deployments with no identity provider. The external Solmara Lab adopter demo runs Relay, Evidence, and Mint together in a demo topology. + Registry Platform provides shared primitives to both runtime services. Registry Manifest produces portable metadata contracts describing what a registry exposes. Registry Relay binds those descriptions to real sources and serves protected read-only APIs and typed consultations. Evidence Gateway independently answers one bounded question about one subject from its own configured authoritative HTTP sources and returns a signed assertion carrying the answer and not the record. Registry Mint is a supporting service that issues the short-lived access tokens Evidence Gateway verifies, for deployments with no identity provider. The external Solmara Lab adopter demo provides synthetic registry data. SHARED PRIMITIVES @@ -54,13 +54,7 @@ consultations. - - - - - read as one fixed HTTP source - - Evidence + Evidence Gateway registry-evidence @@ -80,9 +74,9 @@ font-family="'IBM Plex Mono', ui-monospace, SFMono-Regular, monospace">solmara-lab External adopter demo - running Relay, Evidence, - and Mint together in a - demo topology. + with generated synthetic + registry data and demo + configuration. @@ -93,7 +87,7 @@ registry-mint - Issues the short-lived access tokens Evidence verifies, + Issues the short-lived access tokens Evidence Gateway verifies, for deployments with no identity provider. diff --git a/docs/site/public/images/registry-country-evidence-mesh.svg b/docs/site/public/images/registry-country-evidence-mesh.svg index 4beb15ba1..54470e7ea 100644 --- a/docs/site/public/images/registry-country-evidence-mesh.svg +++ b/docs/site/public/images/registry-country-evidence-mesh.svg @@ -2,7 +2,7 @@ font-family="'Public Sans', system-ui, -apple-system, BlinkMacSystemFont, sans-serif" text-rendering="geometricPrecision"> Country evidence mesh - At country scale several authorities each keep custody of their own data. Clinical health systems expose bounded outputs through a reviewed FHIR integration, public-health programme systems such as DHIS2 through a reviewed Rhai script, and civil registration, social protection, agriculture, and education systems keep their own authoritative stores. Two bounded surfaces sit over them: Registry Relay keeps source credentials and returns only reviewed typed outputs, and Evidence returns only the values a reviewed requirement declares. Consuming systems such as a social-protection management information system receive those answers and do not become raw-record readers. + At country scale several authorities each keep custody of their own data. Clinical health systems expose bounded outputs through a reviewed FHIR integration, public-health programme systems such as DHIS2 through a reviewed Rhai script, and civil registration, social protection, agriculture, and education systems keep their own authoritative stores. Two independent bounded surfaces sit over them: Registry Relay keeps its source credentials and returns only reviewed typed outputs, and Evidence Gateway uses its own configured sources and returns only the values a reviewed requirement declares. Consuming systems such as a social-protection management information system receive those answers and do not become raw-record readers. AUTHORITIES @@ -50,7 +50,7 @@ Registry Relay - Evidence + Evidence Gateway diff --git a/docs/site/public/images/registry-family-map.svg b/docs/site/public/images/registry-family-map.svg index 7a4e8dacb..bc2ed82a3 100644 --- a/docs/site/public/images/registry-family-map.svg +++ b/docs/site/public/images/registry-family-map.svg @@ -2,7 +2,7 @@ font-family="'Public Sans', system-ui, -apple-system, BlinkMacSystemFont, sans-serif" text-rendering="geometricPrecision"> Registry family map - The four formal Registry Stack products, arranged left to right by structural role, followed by Registry Mint as a supporting service and the external Solmara Lab adopter demo. Registry Platform provides shared primitives; Registry Manifest defines portable metadata contracts; Registry Relay and Evidence are the runtime services, Relay serving protected read-only APIs over sensitive registry sources and Evidence answering one bounded question about one subject with a signed assertion. Registry Mint issues the short-lived access tokens Evidence verifies, for deployments with no identity provider. Solmara Lab runs Relay, Evidence, and Mint together in a demo topology. + The four formal Registry Stack products, arranged left to right by structural role, followed by Registry Mint as a supporting service and the external Solmara Lab adopter demo. Registry Platform provides shared primitives; Registry Manifest defines portable metadata contracts; Registry Relay and Evidence Gateway are independent runtime services, Relay serving protected read-only APIs over sensitive registry sources and Evidence Gateway answering one bounded question about one subject with a signed assertion. Registry Mint issues the short-lived access tokens Evidence Gateway verifies, for deployments with no identity provider. Solmara Lab provides synthetic registry data and demo configuration. @@ -35,7 +35,7 @@ Registry Platform Registry Manifest Registry Relay - Evidence + Evidence Gateway Issues the short-lived access tokens - Evidence verifies. + Evidence Gateway verifies. - External adopter demo running Relay, - Evidence, and Mint together. + External adopter demo with synthetic + registry data and configuration. diff --git a/docs/site/public/images/registry-trust-boundaries.svg b/docs/site/public/images/registry-trust-boundaries.svg index 0711fe87b..e2fbfc51a 100644 --- a/docs/site/public/images/registry-trust-boundaries.svg +++ b/docs/site/public/images/registry-trust-boundaries.svg @@ -2,7 +2,7 @@ font-family="'Public Sans', system-ui, -apple-system, BlinkMacSystemFont, sans-serif" text-rendering="geometricPrecision"> Registry Stack trust boundaries - A single request path runs downward from Registry Mint, which issues a short-lived access token, to the Caller, to Evidence, to a Registry Relay protected read API, to the registry sources Relay reads in place. Dashed rules mark the service edge in front of Evidence and in front of Relay, where every record- or assertion-bearing route is authenticated before responding. Caller to Evidence carries a bearer token, a declared purpose, a named requirement revision, and selector values, and returns the answer rather than the record. Evidence to its fixed sources is fixed by trusted configuration and executed only by the core, one request per evaluation. The Relay-protected source composition is two independent authorization decisions, neither widening the other. Registry Mint to Evidence runs one way: Evidence verifies tokens as an ordinary resource server and does not depend on Registry Mint. Relay to registry sources is fixed by a compiled integration. A separate lane runs operator to signing key material to Evidence to the published key set to the verifier, which pins that key set out of band. The footnote lists the unauthenticated operational and discovery routes at the Evidence edge. + One request path runs downward from Registry Mint, which issues a short-lived access token, to the caller, to Evidence Gateway, and to Evidence Gateway's configured authoritative HTTP source. Registry Relay has a separate protected-read path to its own registry sources. Dashed rules mark authenticated service edges. Caller to Evidence Gateway carries a bearer token, a declared purpose, a named requirement revision, and selector values, and returns the answer rather than the record. Evidence Gateway source access is fixed by trusted configuration and executed only by the core, one request per evaluation. Registry Mint to Evidence Gateway runs one way: Evidence Gateway verifies tokens as an ordinary resource server and does not depend on Registry Mint. A separate lane runs operator to signing key material to Evidence Gateway to the published key set to the verifier, which pins that key set out of band. The footnote lists the unauthenticated operational and discovery routes at the Evidence Gateway edge. TRUST BOUNDARIES @@ -18,23 +18,22 @@ Registry Mint Caller - Evidence - Registry Relay - Registry sources + Evidence Gateway + Authoritative source + Registry Relay registry-mint registry-evidence - registry-relay + registry-relay the client asking the question one bounded question - protected read API - read in place + fixed HTTP source @@ -44,8 +43,6 @@ - - @@ -65,20 +62,20 @@ revision, selectors one fixed HTTP request per evaluation - deny-by-default read + separate product path - REGISTRY MINT TO EVIDENCE - CALLER TO EVIDENCE + REGISTRY MINT TO EVIDENCE GATEWAY + CALLER TO EVIDENCE GATEWAY THE SERVICE EDGE (AUTHENTICATION) EVIDENCE TO ITS FIXED SOURCES - THE RELAY-PROTECTED SOURCE COMPOSITION - RELAY TO REGISTRY SOURCES + PRODUCT BOUNDARIES STAY SEPARATE + RELAY'S SEPARATE SOURCE BOUNDARY - One way. Registry Mint issues the token; Evidence verifies it as + One way. Registry Mint issues the token; Evidence Gateway verifies it as an ordinary resource server, knowing it as an issuer URL and a key set. A deployment with an identity provider does not run Mint at all. @@ -88,7 +85,7 @@ binds the whole tuple, and possession is never authority. Every record- or assertion-bearing route is authenticated before - responding. Evidence runs one OIDC bearer profile, one trusted + responding. Evidence Gateway runs one OIDC bearer profile, one trusted issuer, one principal claim, and no trust in proxy identity headers. Origin, method, path, headers, credential, TLS, projection, redirect @@ -96,10 +93,10 @@ configuration and executed only by the core. Lookup collapses to match, no match, or ambiguous; raw responses are never logged. - A common deployment makes the fixed source a Relay-protected read - API. Read it as two independent authorization decisions: neither - widens the other. Evidence holds a Relay client credential, custodied - as key material. Relay authenticates the workload, not the caller. + Evidence Gateway and Relay use independently configured sources. + Neither product calls or authorizes the other. Each keeps its own + source credentials, authorization decisions, audit trail, and + readiness checks. Relay owns its own source boundary: a compiled integration fixes the origin, credential interface, method and path authority, and limits. @@ -111,27 +108,27 @@ - + Operator - Evidence + Evidence Gateway Verifier - - - + + + key file - public JWKS + public JWKS @@ -145,7 +142,7 @@ - Unauthenticated at the Evidence edge: /health, /ready, /openapi.json, /.well-known/evidence/jwks.json, + Unauthenticated at the Evidence Gateway edge: /health, /ready, /openapi.json, /.well-known/evidence/jwks.json, /.well-known/jwt-vc-issuer. None reveals which evidence definitions are enabled or which requesters may invoke them. diff --git a/docs/site/public/images/solmara-lab-topology.svg b/docs/site/public/images/solmara-lab-topology.svg index 12e210e14..3e729ae3d 100644 --- a/docs/site/public/images/solmara-lab-topology.svg +++ b/docs/site/public/images/solmara-lab-topology.svg @@ -1,10 +1,10 @@ - Solmara Lab compose topology, the Evidence path - The five hops this tutorial makes. One, your shell signs a request with the demo caller's own key and sends it to Registry Mint on host port 4341. Two, Mint returns a short-lived access token. Three, your shell presents that token to Registry Evidence on host port 4343 and asks one question: is this subject an adult. Four, Evidence reads two fields of one row, uin and birth_date, from the Civil Registration Authority's records Relay on host port 4342, under the recorded purpose adult-status-verification. Five, Evidence returns a signed answer carrying true or false and no record. Below, a strip lists the rest of the lab that just up-evidence also starts: six authority Relay instances on host ports 4311 to 4316, the citizen portal on 4300, the Visitor's Center on 4301, static metadata on 4331, Postgres on 54329, and the consultation Relay instances, workload identity agents, and journey services behind them. Forty-one long-running services in all. + Historical Solmara Lab compose topology, the Evidence Gateway path + The retired five-hop demo topology. One, your shell signs a request with the demo caller's own key and sends it to Registry Mint on host port 4341. Two, Mint returns a short-lived access token. Three, your shell presents that token to Evidence Gateway on host port 4343 and asks one question: is this subject an adult. Four, the historical Evidence Gateway deployment reads two fields of one row, uin and birth_date, from the Civil Registration Authority's records Relay on host port 4342, under the recorded purpose adult-status-verification. Five, Evidence Gateway returns a signed answer carrying true or false and no record. Current Evidence Gateway deployments no longer use Registry Relay as a source. - SOLMARA LAB — THE EVIDENCE PATH + HISTORICAL SOLMARA LAB · EVIDENCE GATEWAY PATH @@ -25,7 +25,7 @@ font-family="'IBM Plex Mono', ui-monospace, SFMono-Regular, monospace">:4341 Registry Mint - + :4343 - Registry Evidence: + Evidence Gateway: is this subject an adult? @@ -70,7 +70,7 @@ 3 - + diff --git a/docs/site/scripts/check-evidence-tutorials.sh b/docs/site/scripts/check-evidence-tutorials.sh index b78fa0935..8727e97bc 100755 --- a/docs/site/scripts/check-evidence-tutorials.sh +++ b/docs/site/scripts/check-evidence-tutorials.sh @@ -70,8 +70,8 @@ load_spec() { "background:3" "wait-http:http://127.0.0.1:8000/openapi.json" "run:4-5" - "save:Create the Evidence project|yaml|1|questions/adult-status.yaml" - "save:Create the Evidence project|rhai|1|derivations/adult-status.rhai" + "save:Create the Evidence Gateway project|yaml|1|questions/adult-status.yaml" + "save:Create the Evidence Gateway project|rhai|1|derivations/adult-status.rhai" "run:6-13" ) SPEC_LITERALS=( @@ -131,8 +131,8 @@ load_spec() { "background:2" "wait-http:http://127.0.0.1:8002/openapi.json" "run:3" - "save:Create the Evidence project|yaml|1|questions/parent-relationship.yaml" - "save:Create the Evidence project|rhai|1|derivations/parent-relationship.rhai" + "save:Create the Evidence Gateway project|yaml|1|questions/parent-relationship.yaml" + "save:Create the Evidence Gateway project|rhai|1|derivations/parent-relationship.rhai" "run:4-9" ) SPEC_LITERALS=( diff --git a/docs/site/scripts/check-tutorial.sh b/docs/site/scripts/check-tutorial.sh index 3175b0374..d7e92f49d 100755 --- a/docs/site/scripts/check-tutorial.sh +++ b/docs/site/scripts/check-tutorial.sh @@ -2,10 +2,9 @@ # # check-tutorial.sh # -# Verify that src/content/docs/tutorials/first-run-with-solmara-lab.mdx still -# matches reality by extracting its shell commands from the "## Steps" and -# "## Verify" sections and executing them, in order, against a Solmara Lab -# checkout. +# Historical checker for the unpublished Solmara Lab tutorial. The tutorial +# documents the former Evidence Gateway-over-Relay topology. Keep the executable +# path for archaeology against its pinned lab source. # # Also applies the cheap drift pre-gate to the registryctl tutorials by # extracting every `sh` fence and asserting the command-line count. The @@ -18,8 +17,8 @@ # scripts/check-tutorial.sh --dry-run extract + print only (no Docker) # # CI policy: -# npm run check calls check:tutorial:dry-run, which guarantees extraction and -# drift detection only. check:tutorial executes the Solmara tutorial manually. +# npm run check runs only this checker's dry-run extraction and drift checks. +# check:tutorial executes the archived Solmara workflow manually when asked. # The registryctl-tutorials CI job executes the registryctl tutorials through # check-registryctl-tutorials.sh after this cheaper command-count pre-gate. # diff --git a/docs/site/scripts/evidence-gateway-docs.test.mjs b/docs/site/scripts/evidence-gateway-docs.test.mjs new file mode 100644 index 000000000..ee0a497ec --- /dev/null +++ b/docs/site/scripts/evidence-gateway-docs.test.mjs @@ -0,0 +1,85 @@ +import assert from 'node:assert/strict'; +import { readdirSync, readFileSync } from 'node:fs'; +import { join, relative, resolve } from 'node:path'; +import { test } from 'node:test'; +import YAML from 'yaml'; + +const siteRoot = resolve(import.meta.dirname, '..'); +const docsRoot = resolve(siteRoot, 'src/content/docs'); + +function walk(dir) { + return readdirSync(dir, { withFileTypes: true }).flatMap((entry) => { + const path = join(dir, entry.name); + return entry.isDirectory() ? walk(path) : [path]; + }); +} + +function publishedHandAuthoredDocs() { + return walk(docsRoot) + .filter((path) => path.endsWith('.mdx')) + .filter((path) => !path.includes(`${join('content', 'docs', 'products')}/`)) + .filter((path) => !path.endsWith(`${join('docs', 'changelog.mdx')}`)) + .map((path) => ({ path, source: readFileSync(path, 'utf8') })) + .filter(({ source }) => !/^draft: true$/m.test(source) && !/^status: historical$/m.test(source)); +} + +function visibleProse(source) { + return source + .replace(/\{\/\*[\s\S]*?\*\/\}/g, '') + .replace(/```[\s\S]*?```/g, '') + .replace(/~~~[\s\S]*?~~~/g, '') + .replace(/`[^`]*`/g, ''); +} + +test('uses Evidence Gateway as the public product display name', () => { + const projects = YAML.parse(readFileSync(resolve(siteRoot, 'src/data/projects.yaml'), 'utf8')); + assert.equal(projects.find((project) => project.id === 'registry-evidence')?.name, 'Evidence Gateway'); + + const styleGuide = readFileSync(resolve(siteRoot, 'docs/style-guide.md'), 'utf8'); + assert.match(styleGuide, /formal product names.*Evidence Gateway/i); + + const staleProductName = /\b(?:Registry Evidence|Evidence (?:API|binary|product|runtime|server|service|toolset|Version))\b/; + for (const { path, source } of publishedHandAuthoredDocs()) { + assert.doesNotMatch( + visibleProse(source), + staleProductName, + `${relative(siteRoot, path)} uses an obsolete public product name`, + ); + } +}); + +test('keeps Relay outside the Evidence Gateway product boundary', () => { + const architecture = readFileSync( + resolve(docsRoot, 'explanation/architecture.mdx'), + 'utf8', + ); + assert.match(architecture, /Relay-protected API as a fixed HTTP source/); + + const boundaryViolations = [ + /Evidence Gateway (?:requires|depends on) Registry Relay/i, + /Evidence Gateway inherits Relay authorization/i, + /Registry Relay is part of the Evidence Gateway product boundary/i, + ]; + + for (const { path, source } of publishedHandAuthoredDocs()) { + const prose = visibleProse(source); + for (const pattern of boundaryViolations) { + assert.doesNotMatch( + prose, + pattern, + `${relative(siteRoot, path)} merges the Relay and Evidence Gateway product boundaries`, + ); + } + } +}); + +test('labels the old evidence-gateway PDP id as a legacy Relay identifier', () => { + const paths = publishedHandAuthoredDocs() + .filter(({ source }) => source.includes('registry-evidence-gateway-pdp/v1')); + assert.ok(paths.length > 0, 'expected the legacy Relay identifier to remain documented'); + + for (const { path, source } of paths) { + assert.match(source, /Relay/i, `${relative(siteRoot, path)} must identify the owner as Relay`); + assert.match(source, /legacy/i, `${relative(siteRoot, path)} must mark the identifier legacy`); + } +}); diff --git a/docs/site/scripts/evidence-production-build-docs.test.mjs b/docs/site/scripts/evidence-production-build-docs.test.mjs index b600206ab..98ab002d0 100644 --- a/docs/site/scripts/evidence-production-build-docs.test.mjs +++ b/docs/site/scripts/evidence-production-build-docs.test.mjs @@ -24,7 +24,7 @@ test('production Evidence tutorials keep the build, optional Mint, and Compose b assert.match(build, /install -m 600 \/dev\/null ""/u); assert.match(build, /Authorization: Bearer /u); assert.match(build, /\/mint\.yaml"/u); assert.match(mint, /memory-only/u); assert.match(mint, /umask 077\nmint token/u); diff --git a/docs/site/scripts/generate-sidebar.mjs b/docs/site/scripts/generate-sidebar.mjs index 3d4c4ef43..6a9c6a067 100644 --- a/docs/site/scripts/generate-sidebar.mjs +++ b/docs/site/scripts/generate-sidebar.mjs @@ -95,7 +95,7 @@ export function buildProductSidebar(manifest, opts = {}) { for (const entry of [...rest].sort(byNavOrder)) items.push(leaf(entry)); } - groups.push({ label: productLabel(repoId), collapsed: true, items }); + groups.push({ label: repo.label ?? productLabel(repoId), collapsed: true, items }); } return groups; diff --git a/docs/site/scripts/generate-sidebar.test.mjs b/docs/site/scripts/generate-sidebar.test.mjs index e6c346a37..9f1072d16 100644 --- a/docs/site/scripts/generate-sidebar.test.mjs +++ b/docs/site/scripts/generate-sidebar.test.mjs @@ -94,6 +94,18 @@ test('small product (<= threshold) stays flat, Overview first, ordered by nav_or ]); }); +test('a manifest label overrides the derived product group label', () => { + const [group] = buildProductSidebar({ + repos: { + 'registry-evidence': { + label: 'Evidence Gateway', + docs: [doc('products/registry-evidence/index', 'explanation', 0, 'Evidence Gateway')], + }, + }, + }); + assert.equal(group.label, 'Evidence Gateway'); +}); + test('equal nav orders use host-independent English collation', () => { const labels = ['README', 'notary', 'alpha', '-dash', '_meta']; const [group] = buildProductSidebar({ @@ -156,7 +168,7 @@ test('product group labels drop the shared "Registry" prefix', () => { `no group label should start with "Registry": ${labels.join(', ')}`, ); assert.ok( - labels.includes('Relay') && labels.includes('Evidence') && !labels.includes('Notary'), + labels.includes('Relay') && labels.includes('Evidence Gateway') && !labels.includes('Notary'), labels.join(', '), ); }); diff --git a/docs/site/scripts/information-architecture.test.mjs b/docs/site/scripts/information-architecture.test.mjs index e0edb34a3..8202890f2 100644 --- a/docs/site/scripts/information-architecture.test.mjs +++ b/docs/site/scripts/information-architecture.test.mjs @@ -52,7 +52,7 @@ function assertOrdered(source, expectations, label) { test('uses the adopter-first top-level flow in its published order', () => { assert.deepEqual(topLevelLabels(sidebarSource), [ 'Start', - 'Answer with Evidence', + 'Answer with Evidence Gateway', 'Connect an existing registry', 'Operate', 'Security', @@ -63,7 +63,7 @@ test('uses the adopter-first top-level flow in its published order', () => { test('publishes one overview route for every task-flow section', () => { for (const [label, route] of [ ['Start', "link: '/'"], - ['Answer with Evidence', "slug: 'start/evidence-quickstart'"], + ['Answer with Evidence Gateway', "slug: 'start/evidence-quickstart'"], ['Connect an existing registry', "slug: 'configure'"], ['Operate', "slug: 'operate'"], ['Security', "slug: 'security'"], @@ -109,7 +109,7 @@ test('groups Relay tutorials under existing registries', () => { assert.doesNotMatch(quickstartSource, /tutorials\/verify-claim-registry-api/); }); -test('gives Evidence a lane on both front doors without a retired Notary path', () => { +test('gives Evidence Gateway a lane on both front doors without a retired Notary path', () => { assert.match(homepageSource, /\]\(start\/evidence-quickstart\/\)/); assert.match(quickstartSource, /\]\(\.\.\/evidence-quickstart\/\)/); assert.match(homepageSource, /tutorials\/first-evidence-assertion/); @@ -118,27 +118,26 @@ test('gives Evidence a lane on both front doors without a retired Notary path', assert.doesNotMatch(quickstartSource, /Expose Notary|verify-claim-registry-api/); }); -test('ends the onboarding spine on Evidence answering over a Relay-protected API', () => { - // The two doors are only shown working together in one place: the composed - // lab, where Evidence answers over a Relay API rather than a local fixture. - // The chooser has to close there, and that page has to be published rather - // than redirected back to the chooser. +test('organizes Evidence Gateway tasks without publishing the obsolete Relay composition', () => { + const evidence = topLevelSection(sidebarSource, 'Answer with Evidence Gateway'); assertOrdered( - quickstartSource, + evidence, [ - 'evidence-quickstart/', - 'tutorials/first-evidence-assertion/', - 'tutorials/first-run-with-solmara-lab/', + "label: 'Learn locally'", + "label: 'Connect a source'", + "label: 'Prepare and deploy'", + "label: 'Authenticate callers'", + "label: 'Verify and trust'", + "label: 'Operate Evidence Gateway'", ], - 'quickstart lane', + 'Evidence Gateway task group', ); - assert.doesNotMatch(configSource, /'\/tutorials\/first-run-with-solmara-lab\/':/); - assert.ok( - hasDocForSlug('tutorials/first-run-with-solmara-lab'), - 'the composed lab tutorial is still a draft', + assert.doesNotMatch(evidence, /first-run-with-solmara-lab|Relay-protected|over a Relay/); + assert.equal(hasDocForSlug('tutorials/first-run-with-solmara-lab'), false); + assert.match( + configSource, + /'\/tutorials\/first-run-with-solmara-lab\/': internalRedirect\('\/start\/evidence-quickstart\/'\)/, ); - const evidence = topLevelSection(sidebarSource, 'Answer with Evidence'); - assert.match(evidence, /slug: 'tutorials\/first-run-with-solmara-lab'/); }); test('keeps validation on offline test and nested development commands', () => { diff --git a/docs/site/scripts/notary-retirement.test.mjs b/docs/site/scripts/notary-retirement.test.mjs index 2b6fb7c0b..e7f6f7952 100644 --- a/docs/site/scripts/notary-retirement.test.mjs +++ b/docs/site/scripts/notary-retirement.test.mjs @@ -91,8 +91,8 @@ test('removes authored Notary pages but publishes the retirement decision', () = assert.doesNotMatch(retirement, /^draft: true$/m); }); -test('redirects every removed current Notary route to Evidence or the retirement decision', () => { - const allowedTarget = /^(?:\/decisions\/notary-retirement-2026-08-03\/|\/(?:configure\/evidence|reference\/apis\/(?:evidence|registry-evidence)|tutorials\/(?:first-run-with-solmara-lab|move-evidence-to-production-signing))\/)$/; +test('redirects every removed current Notary route to Evidence Gateway or the retirement decision', () => { + const allowedTarget = /^(?:\/decisions\/notary-retirement-2026-08-03\/|\/(?:start\/evidence-quickstart|configure\/evidence|reference\/apis\/(?:evidence|registry-evidence)|tutorials\/move-evidence-to-production-signing)\/)$/; for (const route of [...authoredNotaryRoutes, ...mirroredNotaryRoutes]) { const target = redirects[route]; @@ -111,8 +111,8 @@ test('redirects every removed current Notary route to Evidence or the retirement assert.match(configSource, /\.\.\.buildNotaryRetirementRedirects\(currentDocsetRedirect\)/); }); -test('presents Relay and Evidence in the current site descriptions and API navigation', () => { - assert.match(configSource, /description: 'Documentation for Registry Stack: Registry Relay and Evidence/); +test('presents Relay and Evidence Gateway in the current site descriptions and API navigation', () => { + assert.match(configSource, /description: 'Documentation for Registry Stack: Registry Relay and Evidence Gateway/); assert.doesNotMatch(configSource, /description: '[^']*Registry Notary/); assert.doesNotMatch(configSource, /label: 'Notary \(narrative\)'/); assert.doesNotMatch(configSource, /label: 'Registry Notary'/); diff --git a/docs/site/scripts/replay-protection-contract.test.mjs b/docs/site/scripts/replay-protection-contract.test.mjs index f31c08c19..3bbb1cf2a 100644 --- a/docs/site/scripts/replay-protection-contract.test.mjs +++ b/docs/site/scripts/replay-protection-contract.test.mjs @@ -31,8 +31,8 @@ test('RS-SEC-G keeps the exact product replay matrix', () => { // Evidence has no replay subsystem, and the page must not imply that the echoed // request nonce is one. -test('RS-SEC-G states that Evidence holds no replay state', () => { - assert.match(replaySection, /Evidence holds no replay state at all/); +test('RS-SEC-G states that Evidence Gateway holds no replay state', () => { + assert.match(replaySection, /Evidence Gateway holds no replay state at all/); assert.match(replaySection, /never stored, uniqueness-checked, or exposed/); }); diff --git a/docs/site/scripts/sync-repo-docs.mjs b/docs/site/scripts/sync-repo-docs.mjs index e69617e35..f4ecff7ed 100644 --- a/docs/site/scripts/sync-repo-docs.mjs +++ b/docs/site/scripts/sync-repo-docs.mjs @@ -151,6 +151,72 @@ export function stripPageTypeBanner(md) { return lines.slice(end).join('\n'); } +// Product sources keep their implementation-era name, while the public docs +// use the approved display name. Rewrite prose only. Technical identifiers in +// code spans and fences stay byte-for-byte unchanged, as do CCCEV and OOTS +// terms in which "Evidence" is part of a standards-defined name. +export function applyRepoDisplayName(md, repoId) { + if (repoId !== 'registry-evidence') return md; + + const protectedTerms = [ + 'Evidence Type', + 'Evidence Broker', + 'Evidence Provider', + 'Evidence Exchange', + 'Evidence Request', + 'Evidence Response', + 'Evidence Vocabulary', + ]; + const placeholders = new Map( + protectedTerms.map((term, index) => [`\u0000EVIDENCE_TERM_${index}\u0000`, term]), + ); + + let fence = null; + return md + .split('\n') + .map((line) => { + const fenceMatch = line.match(/^\s*(```+|~~~+)/); + if (fenceMatch) { + const marker = fenceMatch[1][0]; + fence = fence === marker ? null : marker; + return line; + } + if (fence) return line; + + let displayLine = line + .replace(/^### Evidence\s*$/, '### Assertion evidence') + .replace(/^## Discover available Evidence\s*$/, '## Discover available Evidence Gateway definitions') + .replace(/^## Request Evidence\s*$/, '## Request an assertion from Evidence Gateway'); + + const segments = displayLine.split(/(`+[^`]*`+)/g); + displayLine = segments + .map((segment, index) => { + if (index % 2 === 1) return segment; + let prose = segment; + const linkTargets = []; + prose = prose.replace(/(!?\[[^\]]*\]\()([^)]*)(\))/g, (_whole, prefix, target, suffix) => { + const placeholder = `\u0000EVIDENCE_LINK_TARGET_${linkTargets.length}\u0000`; + linkTargets.push(target); + return `${prefix}${placeholder}${suffix}`; + }); + for (const [placeholder, term] of placeholders) { + prose = prose.replaceAll(term, placeholder); + } + prose = prose.replace(/\bEvidence\b(?! Gateway\b)/g, 'Evidence Gateway'); + for (const [placeholder, term] of placeholders) { + prose = prose.replaceAll(placeholder, term); + } + for (const [index, target] of linkTargets.entries()) { + prose = prose.replaceAll(`\u0000EVIDENCE_LINK_TARGET_${index}\u0000`, target); + } + return prose; + }) + .join(''); + return displayLine; + }) + .join('\n'); +} + // The site route for a destination slug, as an absolute path (used for the // final segment / browser navigation). Trailing slash matches the site config. function siteRoute(destSlug) { @@ -467,15 +533,18 @@ async function syncEntry(repoId, repo, entry, source, destIndex, knownStandards) const outFile = resolve(docsDir, `${entry.dest}.mdx`); const assetsToCopy = []; - const body = rewriteLinks(bodyBase, { - repo: { ...repo, id: repoId }, - entry, - destIndex, - sourceFileDir: dirname(sourceFile), - repoRoot: source.path, - assetsToCopy, - outFile, - }); + const body = applyRepoDisplayName( + rewriteLinks(bodyBase, { + repo: { ...repo, id: repoId }, + entry, + destIndex, + sourceFileDir: dirname(sourceFile), + repoRoot: source.path, + assetsToCopy, + outFile, + }), + repoId, + ); const description = entry.description || deriveDescription(stripped, `${title} for ${repoId}.`); const standards_referenced = validateStandardsReferenced( diff --git a/docs/site/scripts/sync-repo-docs.test.mjs b/docs/site/scripts/sync-repo-docs.test.mjs index f5663d9b3..343872551 100644 --- a/docs/site/scripts/sync-repo-docs.test.mjs +++ b/docs/site/scripts/sync-repo-docs.test.mjs @@ -8,6 +8,7 @@ import { test } from 'node:test'; import { applyDocsetMetadataOverrides, + applyRepoDisplayName, frontmatterBlock, stripPageTypeBanner, validateLastReviewed, @@ -24,6 +25,42 @@ const docsets = { ], }; +test('uses the Evidence Gateway display name in generated product prose', () => { + const md = [ + 'Evidence is the product. Evidence Gateway is already current.', + 'Evidence Type and Core Criterion and Core Evidence Vocabulary keep their formal names.', + 'OOTS uses an Evidence Broker and an Evidence Provider.', + 'Inline `Evidence` and `registry-evidence` are technical identifiers.', + '[Evidence guidance](https://example.com/Evidence+Exchange) keeps its link target.', + '', + '```json', + '{ "type": "Evidence" }', + '```', + '', + '### Evidence', + '## Request Evidence', + ].join('\n'); + + const transformed = applyRepoDisplayName(md, 'registry-evidence'); + assert.match(transformed, /Evidence Gateway is the product/); + assert.doesNotMatch(transformed, /Evidence Gateway Gateway/); + assert.match(transformed, /Evidence Type and Core Criterion and Core Evidence Vocabulary/); + assert.match(transformed, /Evidence Broker and an Evidence Provider/); + assert.match(transformed, /Inline `Evidence` and `registry-evidence`/); + assert.match( + transformed, + /\[Evidence Gateway guidance\]\(https:\/\/example\.com\/Evidence\+Exchange\)/, + ); + assert.match(transformed, /\{ "type": "Evidence" \}/); + assert.match(transformed, /### Assertion evidence/); + assert.match(transformed, /## Request an assertion from Evidence Gateway/); +}); + +test('leaves other product documentation unchanged', () => { + const md = 'Evidence is a generic noun here.'; + assert.equal(applyRepoDisplayName(md, 'registry-relay'), md); +}); + test('strips a leading Page-type banner and its trailing blank line', () => { const md = [ '> **Page type:** Reference · **Product:** Registry Notary · **Audience:** operator', diff --git a/docs/site/src/content/docs/configure/evidence.mdx b/docs/site/src/content/docs/configure/evidence.mdx index 25a13282f..18f730eed 100644 --- a/docs/site/src/content/docs/configure/evidence.mdx +++ b/docs/site/src/content/docs/configure/evidence.mdx @@ -1,6 +1,6 @@ --- -title: Configure Evidence -description: Shape an Evidence deployment project's runtime file, governed bundle, key material, immutability, and validation with evidence check. +title: Configure Evidence Gateway +description: Shape an Evidence Gateway deployment project's runtime file, governed bundle, key material, immutability, and validation with evidence check. status: current owner: registry-docs source_repos: @@ -11,9 +11,9 @@ locale: en standards_referenced: [] --- -Configuring Evidence means assembling one deployment project: a governed `bundle/` of YAML, +Configuring Evidence Gateway means assembling one deployment project: a governed `bundle/` of YAML, Rhai scripts, schemas, and fixtures, plus a process-local `runtime.yaml` that binds it to a -listener, a secret root, and audit storage. Both are trusted, startup-only artifacts. Evidence +listener, a secret root, and audit storage. Both are trusted, startup-only artifacts. Evidence Gateway loads them once, compiles and validates them together, and refuses to reload, merge, or partially serve a later change. `evidence check` is the gate every edit to the project must pass before `evidence serve` runs it. @@ -48,7 +48,7 @@ Mint configuration, README, production target, or deployable bundle. Add `--gene signing and HMAC material. `evidencectl source suggest --project ` drafts one source and its editable artifacts from the retained contract. After you add a question, `evidencectl dev` compiles the authoring objects into a private local runtime and delegates validation to the real -Evidence loader. +Evidence Gateway loader. ## The runtime file @@ -63,14 +63,14 @@ Top-level required fields: | --- | --- | | `version` | Fixed at `1`. | | `bundleDirectory` | Absolute path to the governed `bundle/` directory. | -| `listener` | `bindHost` (loopback, private IPv4, or unique-local IPv6 only), `port`, `tlsTermination` (fixed at `operator-controlled-upstream`: TLS terminates ahead of Evidence), `trustProxyIdentityHeaders` (fixed `false`: proxy-supplied identity is never trusted), plus request-size, concurrency, timeout, and shutdown-grace bounds. | +| `listener` | `bindHost` (loopback, private IPv4, or unique-local IPv6 only), `port`, `tlsTermination` (fixed at `operator-controlled-upstream`: TLS terminates ahead of Evidence Gateway), `trustProxyIdentityHeaders` (fixed `false`: proxy-supplied identity is never trusted), plus request-size, concurrency, timeout, and shutdown-grace bounds. | | `secretProviders.file.root` | The owner-only directory the file secret provider resolves every `secret:file/` reference beneath. | | `auditStorage` | `path` for the active audit segment and `maximumFileBytes`, a per-segment rotation threshold. | | `outboundTls` | `systemRoots` (fixed `true`) plus named `trustProfiles`, each a local id bound to one CA bundle file a source can select through `tlsTrustProfile`. | An optional `metricsListener` (`bindHost`, `port`) serves `GET /metrics` on a second private binding; absent by default, it is documented in `products/evidence/OPERATOR-CONTRACT.md` under -Metrics reference rather than in the public Evidence contract. +Metrics reference rather than in the public Evidence Gateway contract. `runtime.yaml` cannot override anything the bundle governs. The schema's `ownership` block closes the allowed set to the bundle directory, listener binding and process limits, the optional @@ -80,7 +80,7 @@ authority, sources, disclosure, and signing policy, belongs to the bundle alone. ## The bundle -`bundle/evidence.yaml` is the single governed contract Evidence compiles and validates as one +`bundle/evidence.yaml` is the single governed contract Evidence Gateway compiles and validates as one atomic revision (`products/evidence/contracts/bundle.schema.yaml`). Its top-level sections: | Section | Declares | @@ -103,7 +103,7 @@ the exact bundle bytes; there is no partial edit, hot reload, or fallback `derivations/`, `schemas/`, `codelists/`, `fixtures/`, and `public-keys/`; symlinks and any file outside them fail startup (`bundle.schema.yaml`, `bundle_layout`). -Evidence's four coequal acceptance definitions are adult status, residence region, professional +Evidence Gateway's four coequal acceptance definitions are adult status, residence region, professional licence status, and legal-parent relationship (`products/evidence/README.md`, `products/evidence/OPERATOR-CONTRACT.md`). You shape each as an ordinary `requirements` entry with its own source, derivation script, and fixtures. The four are presented as coequal, and none @@ -163,27 +163,27 @@ evidencectl keygen secret --out "/subject-binding-hmac-key" ### `signing-ed25519-private-jwk` and `signing-ed25519-public.jwk.json` -Evidence signs assertions with the private Ed25519 JSON Web Key (JWK). Verifiers use the public +Evidence Gateway signs assertions with the private Ed25519 JSON Web Key (JWK). Verifiers use the public JWK to check the signature without receiving the private key. The key identifier must match `signing.activeKeyId` in `bundle/evidence.yaml`. ### `audit-hmac-key` -Evidence uses this random secret to authenticate the audit chain. A changed, removed, or +Evidence Gateway uses this random secret to authenticate the audit chain. A changed, removed, or reordered audit entry then fails chain verification. ### `subject-binding-hmac-key` -Evidence uses this random secret to derive audience-scoped subject references from authorized +Evidence Gateway uses this random secret to derive audience-scoped subject references from authorized selector values. The references let an assertion identify its subject without disclosing the selector values or creating one identifier that every audience can reuse. ## Immutability -Evidence refuses to start from a deployment input it could write to, and reports a +Evidence Gateway refuses to start from a deployment input it could write to, and reports a non-immutable-input error rather than starting on it (`products/evidence/OPERATOR-CONTRACT.md`). Version 1 permits no reload, merge, mutation, governed-field override, or fallback bundle or -runtime file: a project is either the exact bytes Evidence loaded at startup, or it is a different +runtime file: a project is either the exact bytes Evidence Gateway loaded at startup, or it is a different revision that requires a restart. Freeze the project before validating or serving it: @@ -193,7 +193,7 @@ chmod -R a-w bundle && chmod 444 runtime.yaml ``` The bundle directory and every file beneath it carry no write bits, `runtime.yaml` is mode `444`, -and the secret root stays owner-only at mode `0700` with mode `0600` secret files. Evidence +and the secret root stays owner-only at mode `0700` with mode `0600` secret files. Evidence Gateway Version 1 supports Unix targets only because these invariants rely on owner, mode, no-follow, link-count, and open-file-identity checks the platform provides (`products/evidence/contracts/runtime.schema.yaml`, `platform`). To edit the project again, @@ -238,8 +238,8 @@ deployment-targets/ `governance.yaml` supplies the production-owned bundle fields, including service, issuer, authentication, audit, subject binding, rate limits, signing, response formats, and authority profiles. It cannot override selectors, sources, or requirements. Each production question adds -stable concept identifiers and a `governance` block with its requirement, frameworks, Evidence -Type, validity, observation timezone, fixture, and disclosure families. +stable concept identifiers and a `governance` block with its requirement, frameworks, Evidence Type, +validity, observation timezone, fixture, and disclosure families. `runtime.yaml` remains the ordinary runtime document. It names the final absolute bundle, private listener, secret root, audit path, and any private CA files for one target. It is copied @@ -259,6 +259,6 @@ secret values, source responses, local request state, or audit records. The comp the resulting bundle with the `evidence` binary and every referenced fixture before publishing. It does not contact an identity provider, Mint, or a source endpoint. -Use [Build and deploy an Evidence project](../../tutorials/build-and-deploy-evidence-project/) +Use [Build and deploy an Evidence Gateway project](../../tutorials/build-and-deploy-evidence-project/) for the full handoff, and [Evidencectl command reference](../../reference/evidencectl/) for the command contract. diff --git a/docs/site/src/content/docs/configure/mint.mdx b/docs/site/src/content/docs/configure/mint.mdx index 6e38eb51c..b8ae50f76 100644 --- a/docs/site/src/content/docs/configure/mint.mdx +++ b/docs/site/src/content/docs/configure/mint.mdx @@ -17,7 +17,7 @@ set of registered machine clients and has no identity provider to issue them. ## When to use Registry Mint Registry Mint is a supporting service, not a product pattern of its own. Use it when a resource -server such as Evidence needs signed, expiring, audience-bound tokens and standing up a +server such as Evidence Gateway needs signed, expiring, audience-bound tokens and standing up a general-purpose identity provider is not an option for the deployment. Version 1 runs one active Mint process. Its client-assertion replay cache is memory-only and @@ -33,12 +33,12 @@ the client it claims to be, then writes the authority from the registry, never f For the whole round trip in one picture, from a client holding only its own private key to a signed assertion, see -[how a client, Registry Mint, and Evidence interact](../../reference/mint/#how-a-client-registry-mint-and-evidence-interact). +[how a client, Registry Mint, and Evidence Gateway interact](../../reference/mint/#how-a-client-registry-mint-and-evidence-gateway-interact). ## When not to use Registry Mint Skip Registry Mint when an identity provider already issues client-credentials tokens for the -deployment. Registry Mint exists only for the case where none does; pointing Evidence at an +deployment. Registry Mint exists only for the case where none does; pointing Evidence Gateway at an existing IdP's token endpoint and JWKS does not require Registry Mint at all. Registry Mint is also not a place to route caller identity for people. It authenticates @@ -63,11 +63,11 @@ You need: - An owner-only directory on durable storage for the keyed Mint audit chain. Plan its capacity, backup, and retention because Registry Mint rotates segments but never deletes or compacts them. -- The claim names the resource server (Evidence, for example) reads its principal, requester +- The claim names the resource server (Evidence Gateway, for example) reads its principal, requester tags, evidence audience, and grant pair from, so Registry Mint's `accessTokens.claims` can be set to match them exactly. - TLS in front of Registry Mint. Registry Mint serves plain HTTP and expects TLS termination it - does not manage; Evidence in turn requires the token issuer and its key set to be HTTPS, with + does not manage; Evidence Gateway in turn requires the token issuer and its key set to be HTTPS, with no exception for loopback (`crates/registry-mint/demo/README.md`). ## Configure the deployment @@ -248,5 +248,5 @@ records were corrupted or reordered. | `mint serve` refuses to start over audit | The audit key, directory, chain, or lock file is unsafe, another writer holds the chain, or retained records do not verify. | Check owner-only permissions, run one writer per `audit.path`, then run `mint verify-audit` before deciding whether recovery is needed. Do not discard the chain to make startup pass. | | `mint check` refuses the configuration over audit | The audit hash key file is missing, is not owner-only, or is too short. `check` does not open the chain, so it never reports a running writer as a fault. | Restore the key file with owner-only permissions. Use `mint verify-audit` for the chain itself. | | The token request fails with `500 server_error` and readiness changes to `503` | Mint could not durably append the audit decision and permanently poisoned the writer for this process. | Stop traffic, restore writable durable storage, preserve and verify the retained chain, then restart Mint. The failed request did not receive an access token. | -| Evidence rejects a token that Registry Mint minted | `accessTokens.claims` on Registry Mint and the resource server's own claim-name configuration name different claims for the same authority field. | Align every claim name (`principal`, `requesterTags`, `evidenceAudience`, `grantId`, `grantAuthority`, and `actor` where used) between the two configurations. | +| Evidence Gateway rejects a token that Registry Mint minted | `accessTokens.claims` on Registry Mint and the resource server's own claim-name configuration name different claims for the same authority field. | Align every claim name (`principal`, `requesterTags`, `evidenceAudience`, `grantId`, `grantAuthority`, and `actor` where used) between the two configurations. | | `GET /ready` returns `503` | No client is currently registered, the client registry directory failed to load, or the audit writer is poisoned. | Check the startup or reload log and the audit storage. Add a valid client or restore and verify audit storage as indicated. | diff --git a/docs/site/src/content/docs/configure/request-an-access-token.mdx b/docs/site/src/content/docs/configure/request-an-access-token.mdx index 69b89ccf1..e663ecbc8 100644 --- a/docs/site/src/content/docs/configure/request-an-access-token.mdx +++ b/docs/site/src/content/docs/configure/request-an-access-token.mdx @@ -17,7 +17,7 @@ than the `mint token` command. ## When to use this Use this page when you are integrating a registered client into an application and need an access -token to present to a resource server such as Evidence. If you only need a token at a terminal, +token to present to a resource server such as Evidence Gateway. If you only need a token at a terminal, `mint token` already does all of this; see [Obtain a token](../mint/#obtain-a-token). @@ -242,10 +242,10 @@ those five things went wrong, so check them in order locally. | `401 invalid_client` after a working period | The assertion's `exp` exceeds `clientAssertion.maximumLifetimeSeconds`, or the client clock has drifted beyond the tolerated skew. | | `400 invalid_request` | A required form field is missing or duplicated, or `client_assertion_type` is not the exact `jwt-bearer` URN. A missing `grant_type` lands here too. | | `400 unsupported_grant_type` | `grant_type` is present but is not exactly `client_credentials`. | -| The resource server rejects a token Registry Mint issued | The two deployments name different claims for the same authority field. See [How Evidence verifies these tokens](../../reference/mint/#how-evidence-verifies-these-tokens). | +| The resource server rejects a token Registry Mint issued | The two deployments name different claims for the same authority field. See [How Evidence Gateway verifies these tokens](../../reference/mint/#how-evidence-gateway-verifies-these-tokens). | ## Next -- [How a client, Registry Mint, and Evidence interact](../../reference/mint/#how-a-client-registry-mint-and-evidence-interact) +- [How a client, Registry Mint, and Evidence Gateway interact](../../reference/mint/#how-a-client-registry-mint-and-evidence-gateway-interact) - [Configure Registry Mint](../mint/) - [Registry Mint reference](../../reference/mint/) diff --git a/docs/site/src/content/docs/decisions/notary-retirement-2026-08-03.mdx b/docs/site/src/content/docs/decisions/notary-retirement-2026-08-03.mdx index 04d8a082f..da9bd7688 100644 --- a/docs/site/src/content/docs/decisions/notary-retirement-2026-08-03.mdx +++ b/docs/site/src/content/docs/decisions/notary-retirement-2026-08-03.mdx @@ -1,6 +1,6 @@ --- title: Registry Notary retirement decision -description: Record of the decision to retire Registry Notary and direct current adoption to Registry Relay and Evidence. +description: Record of the decision to retire Registry Notary and direct current adoption to Registry Relay and Evidence Gateway. status: current owner: registry-docs source_repos: @@ -12,7 +12,7 @@ standards_referenced: [] --- Registry Stack decided on 2026-08-03 to retire Registry Notary and direct -current adopters to Registry Relay and Evidence. +current adopters to Registry Relay and Evidence Gateway. ## Decision @@ -22,7 +22,7 @@ current adopters to Registry Relay and Evidence. Retire Registry Notary from the current product surface, source workspace, release train, and continuous integration gates. -Keep Registry Relay as the protected read product and Evidence as the +Keep Registry Relay as the protected read product and Evidence Gateway as the minimum-disclosure assertion product. Registry Mint remains a supporting token issuer for deployments without an identity provider. @@ -30,37 +30,36 @@ identity provider. Present two paths to adopters: - Use Registry Relay when another system must read specific, authorized data. -- Use Evidence when another system must learn only a fact. +- Use Evidence Gateway when another system must learn only a fact. -Evidence can consume a Relay-protected API as a fixed source. -This composition does not make Evidence a Notary mode or a continuation of -the Notary credential lifecycle. +Evidence Gateway owns its source access independently of Registry Relay. +It is not a Notary mode or a continuation of the Notary credential lifecycle. ## Context Registry Notary combined claim evaluation, credential issuance, disclosure policy, replay handling, and audit provenance. -Evidence defines a smaller, stateless assertion boundary with its own frozen +Evidence Gateway defines a smaller, stateless assertion boundary with its own frozen Version 1 contracts. Keeping both products on the current surface would give adopters overlapping entry points while preserving two different product models. The retirement narrows the supported surface without changing Registry -Relay's role or Evidence's name, contracts, or independence. +Relay's role or Evidence Gateway's name, contracts, or independence. ## Consequences - Completing the retirement removes Registry Notary from workspace components, new release manifests, continuous integration gates, and current product documentation. -- Registry Relay and Evidence remain separate products with separate runtime +- Registry Relay and Evidence Gateway remain separate products with separate runtime and configuration boundaries. -- Evidence Version 1 wire identifiers and production behavior remain +- Evidence Gateway Version 1 wire identifiers and production behavior remain unchanged. - Historical changelogs, decision records, release manifests, and archived documentation retain Registry Notary references. - Publishing this decision redirects current Notary documentation URLs to the - corresponding Evidence guidance or to this decision record. + corresponding Evidence Gateway guidance or to this decision record. - Archiving retired Notary source and product material is deferred to a separate decision. diff --git a/docs/site/src/content/docs/explanation/architecture.mdx b/docs/site/src/content/docs/explanation/architecture.mdx index 303bf2a9e..753173f37 100644 --- a/docs/site/src/content/docs/explanation/architecture.mdx +++ b/docs/site/src/content/docs/explanation/architecture.mdx @@ -25,32 +25,32 @@ standards_referenced: --- The formal registry stack has four products: Registry Platform, Registry Manifest, Registry Relay, -and Evidence. +and Evidence Gateway. The stack is organized around two layers: a portable metadata layer and a runtime services layer. The metadata layer (Registry Manifest) compiles and renders discovery artifacts that describe what a registry exposes, without touching production sources. -The runtime services layer (Registry Relay, Evidence) binds those descriptions to real data, enforces -access control, and answers bounded questions with signed assertions. +The runtime services layer enforces access against real data. Registry Relay binds Registry Manifest +descriptions to protected reads. Evidence Gateway uses its own governed bundle and authoritative HTTP +sources to answer bounded questions with signed assertions. Registry Platform provides shared Rust primitives consumed by both runtime services. Registry Mint is a supporting service rather than a fifth product: it issues the short-lived access -tokens a resource server such as Evidence verifies, for deployments that have callers and no identity +tokens a resource server such as Evidence Gateway verifies, for deployments that have callers and no identity provider. -Solmara Lab is a separate adopter project that runs Relay, Evidence, and Mint together in local and -hosted demo -topologies. It is not a formal Registry Stack product. +Solmara Lab is a separate adopter project built around synthetic registry data. It is not a formal +Registry Stack product or a production integration reference. At runtime, Registry Stack exposes source data through two patterns: - Protected registry APIs: controlled read-only interfaces over existing registry sources. Registry Relay implements this runtime surface. - Minimum-disclosure assertions: one bounded question about one subject, answered with a signed - assertion that carries the answer and not the record. Evidence implements this runtime surface. + assertion that carries the answer and not the record. Evidence Gateway implements this runtime surface. -The two patterns compose without either service depending on the other. Evidence treats a -Relay-protected API as one ordinary fixed HTTP JSON source, which is the only source shape Evidence -has. -{/* Evidence: contract registry.evidence.fixed-http-json-source/v1, - products/evidence/contracts/source-contract.yaml (frozen). */} +The two patterns are independent. Evidence Gateway contacts its configured authoritative HTTP +sources directly. It does not require Registry Relay or inherit Relay authorization. A deployment +can configure a Relay-protected API as a fixed HTTP source, but Relay remains an ordinary source +rather than part of the Evidence Gateway product boundary. The retired Solmara workflow is not a +current integration path. This split matters because it separates the obligation to describe (what a registry declares it can expose and under what policy) from the obligation to enforce (what a running service will actually return to an @@ -63,25 +63,26 @@ updated policy documents without touching deployment config. Architecture flow: Registry Platform provides shared primitives to both runtime services. Registry Manifest compiles portable metadata contracts. Registry Relay binds those - descriptions to real sources and serves protected read-only APIs. Evidence answers one + descriptions to real sources and serves protected read-only APIs. Evidence Gateway answers one bounded question about one subject and returns a signed assertion carrying the answer and - not the record, reading a Relay API as one fixed HTTP source. Registry Mint is a - supporting service issuing the short-lived access tokens Evidence verifies. The separate - Solmara Lab adopter project wires Relay, Evidence, and Mint into demo topologies. + not the record, using its own configured authoritative HTTP sources. Registry Mint is a + supporting service issuing the short-lived access tokens Evidence Gateway verifies. The separate + Solmara Lab adopter project provides synthetic registry data for demonstrations." /> -## Evidence and decision ownership +## Evidence Gateway and decision ownership The following responsibility flow is normative for 1.0 project authoring: 1. A source system owns its operational data and any decisions made inside that source. -2. Registry Relay owns source-specific acquisition, source-access policy, and typed normalization. +2. Registry Relay owns source-specific acquisition, source-access policy, and typed normalization + for Relay's protected read APIs. Relay returns only the declared consultation outcome and typed outputs. It does not assign a consumer consequence to those outputs. -3. Evidence owns the bounded assertion plus the authorization and disclosure policy for evaluating +3. Evidence Gateway owns the bounded assertion plus the authorization and disclosure policy for evaluating and releasing it. The requirement is the unit of disclosure: purpose, audience, and requester entitlement decide whether a requirement may be invoked at all, and never narrow the answer it - returns. Evidence does not turn the assertion into a consumer rule. + returns. Evidence Gateway does not turn the assertion into a consumer rule. 4. An assertion consumer determines how the returned assertion is used. The accountable decision owner retains responsibility for requirements, eligibility, qualification, prioritization, approval, routing, payment, workflow, and action policy. @@ -90,17 +91,17 @@ The following responsibility flow is normative for 1.0 project authoring: entitlement decide whether a requirement may be invoked at all; they never narrow the answer it returns", products/evidence/CONCEPT.md section 5.2, restated in products/evidence/OPERATOR-CONTRACT.md, "Purpose does not narrow disclosure". The consumer - boundary is the Version 1 non-goal list: Evidence is not a workflow, orchestration, or + boundary is the Version 1 non-goal list: Evidence Gateway is not a workflow, orchestration, or case-management engine and not a runtime policy engine or general PDP. */} -These are three different policy categories: Relay source-access and adaptation policy, Evidence +These are three different policy categories: Relay source-access and adaptation policy, Evidence Gateway authorization and disclosure policy, and consumer use, decision, and action policy. Project authors must keep them separate even when one deployment operates every component. The caller, assertion consumer, and decision owner can be the same component or separate components. An assertion consumer can be a social-protection programme, admissions service, licensing authority, healthcare workflow, lender, insurer, or relying verifier. The caller is the -technical client that invokes Evidence, which may be a portal, intermediary, or workflow connector +technical client that invokes Evidence Gateway, which may be a portal, intermediary, or workflow connector acting for the consumer. | Context | Caller | Assertion consumer | Decision owner | @@ -113,7 +114,7 @@ acting for the consumer. An assertion may describe a property, classification, eligibility decision, status, or relationship. When the configured source returns the final fact, the requirement carries the `source-derived` -acquisition posture and Evidence reports what the source decided rather than recomputing it. The +acquisition posture and Evidence Gateway reports what the source decided rather than recomputing it. The requirement identifier and its review documentation must identify that fact as a source-owned decision. {/* Evidence: acquisition postures source-derived, field-projected, and record-transformed, @@ -135,24 +136,24 @@ decision. 5. Registry Relay executes compiler-pinned consultations. Its product-neutral `http`, `script`, and `snapshot` capabilities adapt reviewed source contracts and return only declared typed outputs. -6. Evidence evaluates one predefined, versioned requirement per request, aligned with CCCEV through +6. Evidence Gateway evaluates one predefined, versioned requirement per request, aligned with CCCEV through its frozen field mapping. Rust owns authentication, authorization, the one fixed bounded HTTP JSON source request, output validation, assertion construction, signing, and audit; trusted Rhai scripts prepare that request and extract typed facts. Caller identity and authorization details - can authorize or parameterize a request but cannot supply facts. A Relay-protected API can be the - configured source. -7. Evidence returns the assertion as a flattened JWS JSON response (`application/jose+json`) by + can authorize or parameterize a request but cannot supply facts. Its fixed HTTP source is configured + directly for the authoritative system. +7. Evidence Gateway returns the assertion as a flattened JWS JSON response (`application/jose+json`) by default. Where the immutable bundle and the one matched authority grant both permit it, the same stateless assertion may instead be serialized as a visibly unsigned JSON envelope or as an SD-JWT VC (`application/dc+sd-jwt`) under the frozen Version 1 profile. That serialization adds a response format, never a credential lifecycle: no issuance session, holder binding ceremony, status list, revocation, or presentation verification. 8. Where a deployment has callers and no identity provider, Registry Mint issues the short-lived - access tokens Evidence verifies. The dependency runs one way: `registry-mint` carries - `registry-evidence` as a development dependency so its tests drive Evidence's authenticator, and + access tokens Evidence Gateway verifies. The dependency runs one way: `registry-mint` carries + `registry-evidence` as a development dependency so its tests drive Evidence Gateway's authenticator, and `registry-evidence` depends on no other product crate. 9. A consumer receives the returned assertion. The decision owner applies any - consumer-specific requirement, decision, workflow, or action rules outside Relay and Evidence. + consumer-specific requirement, decision, workflow, or action rules outside Relay and Evidence Gateway. For what each project does and does not own, refer to the product overview pages linked in the capabilities table. {/* Evidence: response formats and the SD-JWT VC profile, @@ -165,8 +166,8 @@ For what each project does and does not own, refer to the product overview pages ## Capabilities at a glance -The two-layer design supports one capability sequence: describe what the registry can provide, -expose protected registry APIs, then answer a bounded question with a signed assertion that matches +The two-layer design supports complementary capabilities: describe what a registry can provide, +expose protected registry APIs, or answer a bounded question with a signed assertion that matches the purpose and policy of the request. A caller cannot safely use a registry until its fields, schemas, services, policies, and evidence offerings are inspectable, so metadata comes first. @@ -175,19 +176,17 @@ offerings are inspectable, so metadata comes first. | --- | --- | --- | | Describe registries | Other teams need to inspect fields, schemas, policies, services, and evidence offerings before integration. | [Registry Manifest](../../map/boundaries-and-map/) | | Protected registry APIs | A file, extract, database, or legacy registry needs a governed read-only API without replacing the source. | [Registry Relay](../../products/registry-relay/) | -| Minimum-disclosure assertions | A caller needs one bounded fact about one subject, signed and audience-scoped, instead of access to the record behind it. | [Evidence](../../products/registry-evidence/) | +| Minimum-disclosure assertions | A caller needs one bounded fact about one subject, signed and audience-scoped, instead of access to the record behind it. | [Evidence Gateway](../../products/registry-evidence/) | -Shared audit and operational behavior makes Registry Relay and Evidence reviewable: +Shared audit and operational behavior makes Registry Relay and Evidence Gateway reviewable: Registry Platform supplies the shared primitives for authentication, OIDC verification, HTTP security, audit envelopes, and cryptography that both runtime services compose, and the shared -SD-JWT serialization crate that Evidence composes for its credential-format response. The external -[Solmara Lab](https://github.com/registrystack/solmara-lab/tree/00cd51a2be4a405ef75d337ddcede0f9de134b1f) -adopter project gives reviewers runnable demo topologies without becoming part of the formal stack. +SD-JWT serialization crate that Evidence Gateway composes for its credential-format response. ## Next -- [Evidence quickstart](../../start/evidence-quickstart/) maps what Evidence answers and the current +- [Evidence Gateway quickstart](../../start/evidence-quickstart/) maps what Evidence Gateway answers and the current authoring, operation, and verification material. -- [Evidence security model](../../security/evidence/) states the invariants the runtime enforces and +- [Evidence Gateway security model](../../security/evidence/) states the invariants the runtime enforces and the duties that remain with the operator. - [Boundaries and map](../../map/boundaries-and-map/) records what each product owns and does not own. diff --git a/docs/site/src/content/docs/explanation/data-minimization-and-purpose-limitation.mdx b/docs/site/src/content/docs/explanation/data-minimization-and-purpose-limitation.mdx index 693d8c37e..3afde947c 100644 --- a/docs/site/src/content/docs/explanation/data-minimization-and-purpose-limitation.mdx +++ b/docs/site/src/content/docs/explanation/data-minimization-and-purpose-limitation.mdx @@ -35,7 +35,7 @@ minimized typed outputs one protected read route may return. *Minimized evidence* means a response shaped by data minimization or selective disclosure; a *purpose-bound request* is a request that carries or is evaluated against a stated purpose. -Two runtime patterns carry these principles, Registry Relay and Evidence, and each enforces them +Two runtime patterns carry these principles, Registry Relay and Evidence Gateway, and each enforces them at its own boundary rather than in one chain. ## How the requirement model limits collection at the source @@ -47,7 +47,7 @@ asked. The design treats the narrow question, not the record, as the thing to be answered. That principle is enforced at two separate boundaries. A Relay integration declares closed -request inputs and minimized typed outputs. An Evidence requirement reads a fixed, bounded source +request inputs and minimized typed outputs. An Evidence Gateway requirement reads a fixed, bounded source request whose origin, method, path, headers, and client-side response projection are all set by reviewed configuration, and it discloses only the concepts it declares. Callers cannot choose a source destination, credential, selector field, adapter capability, or @@ -59,7 +59,7 @@ from the question it was asked. ## Purpose limitation as an enforced gate, not a label -Purpose limitation in this design is more than a field written into a log. In Evidence, the +Purpose limitation in this design is more than a field written into a log. In Evidence Gateway, the purpose a caller states is one dimension of a single authorization decision that also binds the requester, the requirement revision, every subject role and selector profile, the subject authority, and the audience. The match must be exact and complete, and it happens before audit, @@ -79,7 +79,7 @@ lists them. ## Minimization at the output: closed value forms -Minimization also applies to what leaves the boundary. Evidence has no caller-selectable +Minimization also applies to what leaves the boundary. Evidence Gateway has no caller-selectable disclosure at all, so there is no request-time negotiation to review. Instead, a requirement declares one to sixteen *concepts*, and each concept fixes the exact *value @@ -103,9 +103,9 @@ present a subset. A value uses one disclosure by default. A governed structured place each direct field in a separate disclosure while keeping nested field values atomic. Two limits matter to a reviewer. The issuer appends every disclosure, so the response the caller receives reveals the same set as the signed JWS, and holder-side omission is outside this version. -Evidence also performs no presentation-side verification, no key-binding JWT validation, and no +Evidence Gateway also performs no presentation-side verification, no key-binding JWT validation, and no wallet interaction, and the profile excludes OID4VCI in every part. A caller may supply a holder -public key that Evidence echoes into the `cnf` claim for a relying party to check itself. +public key that Evidence Gateway echoes into the `cnf` claim for a relying party to check itself. A further minimization detail guards against a subtler leak. No match, ambiguity, a missing required fact, and an unresolved derivation input all collapse into @@ -145,7 +145,7 @@ Every request that returns person-level records or an assertion must be recorded the caller principal, the scopes exercised, a request identifier, and the purpose value where one was supplied, and a deployment can run audit fail-closed so that a request whose audit record cannot be written does not succeed. -Evidence takes that further and is fail-closed by construction rather than by configuration: it +Evidence Gateway takes that further and is fail-closed by construction rather than by configuration: it writes an access record before it contacts any source and a release record after signing and before release, and an audit failure fails the request. Selector, source, and disclosed values never appear in those records or in logs, and raw source responses are never persisted. @@ -185,7 +185,7 @@ design, for each one. The main conditional control is the authored projection. A runtime can stop a caller from reaching past the reviewed contract, but it cannot decide which values an institution has a lawful reason to expose. Project reviewers must confirm the source authority, selector inputs, output projection, -purpose, requirements, and declared value forms together, and Evidence expects the complete +purpose, requirements, and declared value forms together, and Evidence Gateway expects the complete simultaneously enabled configuration to be reviewed as one disclosure surface, since two answers that are each defensible alone can reconstruct a protected value between them. Operators must then bind only the reviewed source and workload credentials to the generated product inputs. diff --git a/docs/site/src/content/docs/explanation/disclosure-modes-and-computed-answers.mdx b/docs/site/src/content/docs/explanation/disclosure-modes-and-computed-answers.mdx index 6b64cbeea..e2ad779b1 100644 --- a/docs/site/src/content/docs/explanation/disclosure-modes-and-computed-answers.mdx +++ b/docs/site/src/content/docs/explanation/disclosure-modes-and-computed-answers.mdx @@ -1,6 +1,6 @@ --- title: Disclosure modes and computed answers -description: Why Evidence answers a question about a subject with a computed value whose shape is fixed in advance, instead of handing back the source record. +description: Why Evidence Gateway answers a question about a subject with a computed value whose shape is fixed in advance, instead of handing back the source record. status: draft owner: registry-docs source_repos: @@ -25,10 +25,10 @@ A requirement is deliberately narrow and reusable. A requirement that returned a over-collect, and a requirement that embedded one consumer's eligibility or action rules could not be reused as neutral evidence. -## Evidence has no caller-selectable disclosure modes +## Evidence Gateway has no caller-selectable disclosure modes The most important difference is a subtraction. -An Evidence request carries four required members: a per-request nonce, the requirement identifier, +An Evidence Gateway request carries four required members: a per-request nonce, the requirement identifier, the purpose, and one selector per declared subject role. The only optional member is a holder public key, which is echoed into the SD-JWT VC `cnf` claim and never reaches authorization, selectors, scripts, source requests, or audit. The request schema is closed and rejects anything @@ -36,7 +36,7 @@ else (`products/evidence/contracts/request.schema.yaml`). There is no disclosure mode, no redaction field list, no allowed set, and no downgrade policy, because there is nothing for a caller to choose. -Evidence answers a predefined requirement and returns that requirement's answer. +Evidence Gateway answers a predefined requirement and returns that requirement's answer. It does not run a disclosure policy engine over an arbitrary record, and it has no notion of "the same answer, revealed at three levels of detail." How much a requirement reveals is fixed when the requirement is authored and reviewed, and it is @@ -78,7 +78,7 @@ serialized value budget of 65536 bytes. ## Four questions, four answer shapes -Four acceptance definitions carry equal weight in the Evidence contract. None is privileged, none +Four acceptance definitions carry equal weight in the Evidence Gateway contract. None is privileged, none is a built-in type, and none has a special route (`AGENTS.md`, `products/evidence/CONCEPT.md`). They are worth reading together because they show the same mechanism producing four differently shaped answers. @@ -99,10 +99,10 @@ shaped answers. The fixtures for all four are in `products/evidence/fixtures/acceptance/`. -## Evidence is not a consumer decision +## Evidence Gateway is not a consumer decision Registry Relay source-access and adaptation policy controls how an authoritative source is read -and normalized. Evidence authorization and requirement policy control which requirement is +and normalized. Evidence Gateway authorization and requirement policy control which requirement is evaluated, who can request it, for what purpose, and exactly which values leave the service. The evidence consumer determines how the evidence is used, while the decision owner remains accountable for requirements, decisions, and actions. @@ -116,16 +116,16 @@ is required. ## There is no redacted answer -Evidence cannot return an answer that carries neither a value nor a satisfaction outcome, and this +Evidence Gateway cannot return an answer that carries neither a value nor a satisfaction outcome, and this is structural rather than an omission: an assertion must carry at least one supported value, so an assertion with nothing in it cannot be produced (`products/evidence/contracts/evidence.schema.yaml`). -An Evidence request that cannot be answered does not return an empty assertion. It returns an +An Evidence Gateway request that cannot be answered does not return an empty assertion. It returns an `application/problem+json` document with a closed member set, and no assertion is produced at all (`products/evidence/contracts/problem-contract.yaml`). -What used to be modelled as a redacted answer is modelled in Evidence as a different requirement, +What used to be modelled as a redacted answer is modelled in Evidence Gateway as a different requirement, or as a coarser value form on the same requirement, and is reviewed as such. ## A refusal is not an existence oracle @@ -176,7 +176,7 @@ can match on. ## Response formats are not disclosure levels -Evidence can serialize the same assertion in up to three formats: a signed flattened JWS, an +Evidence Gateway can serialize the same assertion in up to three formats: a signed flattened JWS, an SD-JWT VC under a frozen local profile, and a separately typed unsigned envelope. `signed-jws` is mandatory in every bundle and is the default (`products/evidence/contracts/bundle.schema.yaml`). @@ -220,7 +220,7 @@ A few boundaries matter when you evaluate this design: every purpose authorized to invoke it. Purpose gates whether a caller may ask; a purpose that justifies a coarser answer needs its own requirement. - The caller cannot inject a value, but matching strictness is configured: the computed answer rests - on Evidence deriving it from one reviewed source consultation. A lookup resolves to exactly one + on Evidence Gateway deriving it from one reviewed source consultation. A lookup resolves to exactly one match, no match, or ambiguity, and matching is only as strict as that reviewed source contract. - This is not zero-knowledge: a boolean answer is computed inside the service from data the service read, and SD-JWT selective disclosure is digest omission. Neither is a zero-knowledge proof. @@ -236,7 +236,7 @@ the full inventory. ## Related - [Security overview](../../security/): the full posture this fits into -- [Evidence security model](../../security/evidence/): the invariants named on this page +- [Evidence Gateway security model](../../security/evidence/): the invariants named on this page - [Known limitations and non-guarantees](../known-limitations/): where the edges are - [Records stay home](../records-stay-home/): what stays inside the institution and what crosses out - How a requirement and its disclosure are defined: diff --git a/docs/site/src/content/docs/explanation/dpi-safeguards-alignment.mdx b/docs/site/src/content/docs/explanation/dpi-safeguards-alignment.mdx index b46d01277..42aa23ece 100644 --- a/docs/site/src/content/docs/explanation/dpi-safeguards-alignment.mdx +++ b/docs/site/src/content/docs/explanation/dpi-safeguards-alignment.mdx @@ -70,11 +70,11 @@ framework. | Safeguards question | Stack evidence | Boundary | | --- | --- | --- | | What does the registry expose? | Registry Manifest renders portable catalog, schema, service, policy, and evidence-offering metadata. | Metadata describes a surface. It does not authorize access. | -| Who can read protected data? | Relay authenticates protected source routes. Evidence independently authenticates the assertion caller against one configured OIDC issuer and matches one complete entitlement before it contacts any source. | Deployment policy decides who receives scopes, grants, and workload authority. | +| Who can read protected data? | Relay authenticates protected source routes. Evidence Gateway independently authenticates the assertion caller against one configured OIDC issuer and matches one complete entitlement before it contacts any source. | Deployment policy decides who receives scopes, grants, and workload authority. | | Is the exchange purpose-bound? | Governed runtime routes can require purpose and trusted context, then fail closed with stable [`pdp.*` denial codes](../../reference/errors/). | Static policy metadata is not enforcement until a runtime service binds it. | -| Is data minimized? | Relay exposes configured fields, relationships, and aggregates. Evidence returns only the concepts a predefined requirement declares, each in one of eleven closed [value forms](../disclosure-modes-and-computed-answers/). | The operator still chooses the fields, the requirements, and how coarse each declared value form is. | -| Can the exchange be reviewed later? | Relay audit events and Policy Decision Point (PDP) provenance, Evidence keyed audit records written at two durable gates, package and configuration digests, and Selective Disclosure JWT Verifiable Credentials (SD-JWT VC) provide review evidence. | Audit records support accountability. They are not accountability by themselves. | -| Can other systems interoperate? | Manifest emits standards-shaped metadata; Relay and Evidence publish OpenAPI; Evidence can serialize one assertion as an SD-JWT VC under a frozen local profile. | These are scoped adoption claims, not blanket conformance to every named standard. The SD-JWT VC profile is a second encoding of one response, and it excludes OpenID for Verifiable Credential Issuance (OID4VCI) in every part. | +| Is data minimized? | Relay exposes configured fields, relationships, and aggregates. Evidence Gateway returns only the concepts a predefined requirement declares, each in one of eleven closed [value forms](../disclosure-modes-and-computed-answers/). | The operator still chooses the fields, the requirements, and how coarse each declared value form is. | +| Can the exchange be reviewed later? | Relay audit events and Policy Decision Point (PDP) provenance, Evidence Gateway keyed audit records written at two durable gates, package and configuration digests, and Selective Disclosure JWT Verifiable Credentials (SD-JWT VC) provide review evidence. | Audit records support accountability. They are not accountability by themselves. | +| Can other systems interoperate? | Manifest emits standards-shaped metadata; Relay and Evidence Gateway publish OpenAPI; Evidence Gateway can serialize one assertion as an SD-JWT VC under a frozen local profile. | These are scoped adoption claims, not blanket conformance to every named standard. The SD-JWT VC profile is a second encoding of one response, and it excludes OpenID for Verifiable Credential Issuance (OID4VCI) in every part. | ## Project roles @@ -82,8 +82,8 @@ framework. | --- | --- | --- | | [Registry Manifest](../../products/registry-manifest/) | Validates `metadata.yaml`, rejects known runtime-only keys, and renders standards-shaped metadata: Data Catalog Vocabulary (DCAT), BRegDCAT-AP, Core Public Service Vocabulary Application Profile (CPSV-AP), Shapes Constraint Language (SHACL), JSON Schema, Open Digital Rights Language (ODRL), Core Criterion and Core Evidence Vocabulary (CCCEV), Open Geospatial Consortium (OGC) API Records, evidence offerings, and SKOS-shaped codelists. | Manifest does not serve HTTP, read production data, authorize callers, or evaluate claims. See the [Registry Manifest data model](../../spec/rs-dm-manifest/). | | [Registry Relay](../../products/registry-relay/) | Exposes protected, read-only, domain-oriented registry routes for records, relationships, schemas, aggregates, scoped metadata, and governed PDP reads, plus emitted audit events. | Relay does not mutate source data, expose arbitrary SQL, evaluate claims, issue credentials, host issuer DID documents, or put admin routes on the public API. See the [Registry Relay protocol](../../spec/rs-pr-relay/). | -| [Evidence](../../products/registry-evidence/) | Evaluates predefined, versioned requirements against fixed, bounded source requests; authenticates the caller and matches one complete entitlement as a single decision before any source access; derives the declared concept values through bounded scripts; and returns a signed flattened JWS or SD-JWT VC assertion with keyed audit. | Evidence does not accept caller-provided facts, run a general policy engine, decide eligibility, run a wallet, verify presentations, certify source truth, or federate. It has no application database and persists no selector, source, or response data. See the [Evidence protocol](../../spec/rs-pr-evidence/). | -| Registry Platform | Supplies shared primitives for authentication, OpenID Connect (OIDC), audit envelopes, HTTP security, outbound HTTP policy, cryptography, PDP behavior, and SD-JWT VC support. | Platform provides primitives. Relay and Evidence configure and enforce their own route behavior, and they do not share one authorization model. See [RS-SEC-G](../../spec/rs-sec-g/). | +| [Evidence Gateway](../../products/registry-evidence/) | Evaluates predefined, versioned requirements against fixed, bounded source requests; authenticates the caller and matches one complete entitlement as a single decision before any source access; derives the declared concept values through bounded scripts; and returns a signed flattened JWS or SD-JWT VC assertion with keyed audit. | Evidence Gateway does not accept caller-provided facts, run a general policy engine, decide eligibility, run a wallet, verify presentations, certify source truth, or federate. It has no application database and persists no selector, source, or response data. See the [Evidence Gateway protocol](../../spec/rs-pr-evidence/). | +| Registry Platform | Supplies shared primitives for authentication, OpenID Connect (OIDC), audit envelopes, HTTP security, outbound HTTP policy, cryptography, PDP behavior, and SD-JWT VC support. | Platform provides primitives. Relay and Evidence Gateway configure and enforce their own route behavior, and they do not share one authorization model. See [RS-SEC-G](../../spec/rs-sec-g/). | ## Principle alignment @@ -101,7 +101,7 @@ principles; the remaining principles are governance and institutional work outsi | Transparency and accountability (F4) | Portable metadata, runtime metadata, OpenAPI references, stable error codes, audit records, signed assertions carrying the configuration revision they were produced under, and the [standards register](../../reference/standards/) make behavior reviewable. | Public governance, remedies, procurement discipline, and independent accountability mechanisms are institutional controls. | | Evolve with evidence (O2) | [ITB and SEMIC validation evidence](../../reference/itb-semic-evidence/), the [security self-assessment](../../security/self-assessment/), and [OpenSSF status and release verification evidence](../../security/openssf-evidence/) give assessors material they can re-run and re-check. | Independent assessments, audits, engagement with affected people, and acting on findings remain program and institutional responsibilities. | | Build and share open assets (O9) | The stack emits or uses open, standards-shaped artifacts and documented HTTP contracts rather than one-off integration agreements. | External conformance and certification require separate validation against each standard or program rule. | -| Autonomy and agency (F6) | An Evidence subject appears only as an audience-scoped opaque binding, so two relying parties asking about the same person cannot join their assertions into a profile. A caller may supply a holder public key that Evidence echoes into the SD-JWT VC `cnf` claim for the relying party to check. | Evidence never validates a presentation or a key-binding JWT, and the stack does not provide a wallet, consent journey, opt-out path, appeal process, or assisted service channel. | +| Autonomy and agency (F6) | An Evidence Gateway subject appears only as an audience-scoped opaque binding, so two relying parties asking about the same person cannot join their assertions into a profile. A caller may supply a holder public key that Evidence Gateway echoes into the SD-JWT VC `cnf` claim for the relying party to check. | Evidence Gateway never validates a presentation or a key-binding JWT, and the stack does not provide a wallet, consent journey, opt-out path, appeal process, or assisted service channel. | | Inclusion and non-discrimination (F2, F3, O6) | Metadata, audit, and assertion records can help reviewers inspect what a service exposes and how it behaves. | Accessibility, language access, community participation, gender or disability inclusion, and non-digital alternatives are not solved by these components. | ## Fit boundaries @@ -112,7 +112,7 @@ can be returned, and which project owns the behavior. The stack does not hide governance decisions inside software. Manifest metadata and Relay metadata do not grant access. -Evidence assertions do not decide benefits. +Evidence Gateway assertions do not decide benefits. Audit events do not replace remedy, supervision, or public accountability. ## Next diff --git a/docs/site/src/content/docs/explanation/integration-patterns.mdx b/docs/site/src/content/docs/explanation/integration-patterns.mdx index 36b706be3..1bb854290 100644 --- a/docs/site/src/content/docs/explanation/integration-patterns.mdx +++ b/docs/site/src/content/docs/explanation/integration-patterns.mdx @@ -36,11 +36,11 @@ For how the registry family relates to the wider ecosystem, see the [ecosystem page](https://registrystack.org/ecosystem/). Two runtime surfaces can appear in an integration path. Registry Relay publishes protected, scoped, -read-only APIs over sources an institution already holds. Evidence answers one predefined +read-only APIs over sources an institution already holds. Evidence Gateway answers one predefined requirement about one set of subjects with a signed assertion carrying the answer rather than the record. Registry Mint is a supporting service that issues the short-lived access tokens either surface verifies when a deployment has no identity provider. -The patterns below describe Relay and Evidence. +The patterns below describe Relay and Evidence Gateway. ## Country evidence mesh @@ -50,7 +50,7 @@ public-health program systems such as DHIS2 can use Relay's product-neutral, rev capability, and social protection, agriculture, education, and civil registration systems can keep their own authoritative stores. Each authority keeps custody of its own data. Relay keeps source credentials and returns only -reviewed typed outputs, and Evidence returns only the values a reviewed requirement declares. +reviewed typed outputs, and Evidence Gateway returns only the values a reviewed requirement declares. Consuming systems such as a social-protection management information system do not become raw-record readers. @@ -61,7 +61,7 @@ raw-record readers. (DHIS2) uses a reviewed Rhai script, and civil registration, social protection, agriculture, and education keep their own authoritative stores. Two bounded surfaces sit over them: Registry Relay keeps source credentials and returns only reviewed typed - outputs, and Evidence returns only the values a reviewed requirement declares. A + outputs, and Evidence Gateway returns only the values a reviewed requirement declares. A social-protection management information system and other consumers receive the answers these surfaces return, and do not become raw-record readers." /> @@ -69,19 +69,19 @@ raw-record readers. Snapshot remains an authored integration capability, not a public template or separate runtime architecture. -{/* TODO[evidence]: registryctl cannot express an Evidence deployment at all, so this page cannot +{/* TODO[evidence]: registryctl cannot express an Evidence Gateway deployment at all, so this page cannot yet describe a selectable topology. An authored service is only consultation_api or records_api (enum ServiceKind in crates/registryctl/src/project_authoring/model.rs), a kind: evidence service is rejected as an unknown variant (test retired_evidence_service_kind_is_rejected in the same file), and the environment deployment block is closed around profile and relay with no evidence key (crates/registryctl/schemas/project-authoring/environment.schema.json). Every compiled project is therefore relay-only. Restore a topology paragraph here once registryctl - gains an Evidence deployment path. */} + gains an Evidence Gateway deployment path. */} -## Evidence-to-action boundary +## Evidence Gateway to action boundary Every combined integration follows the same ownership boundary. Registry Relay owns -source-specific acquisition, source-access policy, and typed normalization. Evidence owns the +source-specific acquisition, source-access policy, and typed normalization. Evidence Gateway owns the predefined requirement, evidence authorization, and the declared disclosure that requirement carries. The evidence consumer determines how the evidence is used, and the decision owner remains accountable for requirements, decisions, workflow, and action. @@ -90,12 +90,12 @@ The maintained DHIS2 health-evidence reference project makes that boundary visib DHIS2 remains the system of record. Relay uses its product-neutral script capability to perform bounded, same-origin acquisition and normalize the existing health outputs. -Evidence exposes bounded facts as reusable requirements: that project reads two Tracker programmes +Evidence Gateway exposes bounded facts as reusable requirements: that project reads two Tracker programmes for two independent requirements, adult status and professional licence status, and a caller authorized for one learns nothing about the other. In this example, a public-health programme is both the evidence consumer and the decision owner. It can compute an outreach or follow-up priority without moving either decision into Relay or -Evidence. +Evidence Gateway. The reviewed contract keeps a positive fact, its negative, an absent value, no match, ambiguity, and source failure distinct. Missing evidence is not a negative fact. Offline synthetic fixtures @@ -105,9 +105,9 @@ compatibility runner. An operator can exercise a deployed API with a standard HTTP client and owner-maintained credentials as separate interoperability evidence. -Evidence has no general policy engine and no eligibility or workflow engine. A requirement whose +Evidence Gateway has no general policy engine and no eligibility or workflow engine. A requirement whose answer restates a decision an authoritative source already made must say so in its review -documentation, and Evidence does not recompute that decision. +documentation, and Evidence Gateway does not recompute that decision. {/* Evidence: products/evidence/reference/request-adapter/deployment-projects/dhis2-tracker-evidence/ and products/evidence/contracts/README.md. */} @@ -153,12 +153,12 @@ Each component is bounded and canonicalized under the compiled consultation cont Up to sixteen total inputs may also include bounded parameters that are not selector components. Relay reports no match, one match, or ambiguity instead of choosing between duplicate records. -Evidence keeps the same discipline and adds no batch envelope over it. +Evidence Gateway keeps the same discipline and adds no batch envelope over it. One request names one requirement and carries one selector per declared subject role, at most eight roles, and an evaluation performs exactly one evidence-data request against its one fixed source. Version 1 has no batch API and no multi-source fulfillment, so a caller that needs several answers issues several independently authorized requests. -A lookup resolves to exactly one match, no match, or ambiguity, and Evidence never surfaces or +A lookup resolves to exactly one match, no match, or ambiguity, and Evidence Gateway never surfaces or chooses between candidates. {/* Evidence: crates/registry-relay/src/api/consultation.rs, @@ -206,37 +206,23 @@ URL outside Registry Stack's control. crates/registry-relay/src/consultation/executor.rs, and crates/registry-relay/src/consultation/response.rs. */} -## Evidence over a Relay-protected API +## Evidence Gateway with a fixed authoritative source -This is the composed pattern, and it is the one to reach for when an institution wants both a -governed read path and a minimum-disclosure answer over the same data. +Use this pattern when an institution wants a minimum-disclosure answer over data in an +authoritative system. Evidence Gateway calls that system through its own fixed HTTP source +contract. The reviewed bundle fixes the origin, path authority, method, authentication, +projection, schemas, and bounded scripts. The caller cannot select or redirect the source. -Evidence treats a Relay-protected API as an ordinary fixed HTTP source. Nothing in an Evidence -bundle names Relay or depends on it: the requirement is authored against a protected, scoped, -read-only HTTP JSON endpoint, and any protected read with those three properties fits. The -reference deployment project for this shape answers one requirement, residence region as a coarse -controlled code, over exactly that kind of source. The register's own region code never leaves the -service, because a reviewed codelist maps several register codes onto each disclosed region, and a -register code with no reviewed mapping leaves the requirement unresolved rather than guessing. +The caller's access token and the source credential serve different boundaries: -Two token hops make the arrangement work, and they are separate: - -- The caller holds a short-lived access token for Evidence, from the deployment's identity provider - or from Registry Mint when there is none. See the +- The caller holds a short-lived access token for Evidence Gateway, from the deployment's identity + provider or from Registry Mint when there is none. See the [Registry Mint reference](../../reference/mint/). -- Evidence holds its own compiled source credential for the Relay API. The caller never sees it, - and cannot influence which credential is resolved. - -The dependency runs one way. Evidence verifies tokens a Mint-shaped issuer produces; it does not -depend on Registry Mint, and a deployment with its own identity provider omits Mint entirely. - -[First run with Solmara Lab](../../tutorials/first-run-with-solmara-lab/) runs the whole -arrangement on a laptop, with Mint, Relay, and Evidence on separate ports, if you would rather see -it than read about it. +- Evidence Gateway holds its own compiled credential for the authoritative source. The caller never + sees it and cannot influence which credential is resolved. -{/* Evidence: - products/evidence/reference/request-adapter/deployment-projects/relay-protected-read-evidence/ - and products/evidence/contracts/source-contract.yaml. */} +Registry Relay is not part of this request path. If the institution also operates Relay, it is a +separate protected-read product with its own sources, callers, authorization, and audit trail. ## Workflow engines @@ -300,15 +286,15 @@ authoritative list of claim levels and per-project evidence. | --- | --- | | Static catalog and service discovery (Registry Manifest) | DCAT, BRegDCAT-AP, CPSV-AP, OGC API Records, SHACL, JSON Schema, ODRL, SKOS-shaped codelists | | Scoped runtime metadata and protected data routes (Registry Relay) | OpenAPI, DCAT, BRegDCAT-AP, SHACL, JSON Schema, ODRL, OGC API Records, OGC API Features, OGC API EDR, SP-DCI, GovStack Digital Registries | -| Minimum-disclosure assertions (Evidence) | OpenAPI, CCCEV, SD-JWT VC, JSON Schema | +| Minimum-disclosure assertions (Evidence Gateway) | OpenAPI, CCCEV, SD-JWT VC, JSON Schema | {/* TODO[evidence]: the standards register in src/data/standards.yaml has no registry-evidence - entries, so the Evidence row above is not backed by a per-project claim level there. This is + entries, so the Evidence Gateway row above is not backed by a per-project claim level there. This is blocked, not merely pending: every evidence_docs URL in that file is pinned to commit d45761a0, which is reachable from origin/main, and neither crates/registry-evidence nor crates/registry-mint exists at any commit on pushed main (git cat-file -e origin/main:crates/registry-evidence fails). Repo policy forbids citing an unpushed session - commit in a durable artifact, so the Evidence entries can only be pinned once this work + commit in a durable artifact, so the Evidence Gateway entries can only be pinned once this work reaches main. */} ## Next diff --git a/docs/site/src/content/docs/explanation/known-limitations.mdx b/docs/site/src/content/docs/explanation/known-limitations.mdx index 6a636529c..4d20acfe9 100644 --- a/docs/site/src/content/docs/explanation/known-limitations.mdx +++ b/docs/site/src/content/docs/explanation/known-limitations.mdx @@ -58,11 +58,11 @@ Second, aligning with an external standard is not the same as conforming to it: of OIDC, OAuth 2.0, SD-JWT VC, CCCEV, or the rest does not certify conformance to any of them. The [standards register](../../reference/standards/) records how each one is actually adopted. -## Evidence limits +## Evidence Gateway limits -Evidence releases one stateless assertion per request under a frozen Version 1 contract. -Read the full context in the [Evidence protocol](../../spec/rs-pr-evidence/) and the -[Evidence security model](../../security/evidence/). +Evidence Gateway releases one stateless assertion per request under a frozen Version 1 contract. +Read the full context in the [Evidence Gateway protocol](../../spec/rs-pr-evidence/) and the +[Evidence Gateway security model](../../security/evidence/). - A serialization, not a credential lifecycle: enabling the SD-JWT VC response format adds an encoding of the same assertion. There is no issuance session, holder binding ceremony, status @@ -70,12 +70,12 @@ Read the full context in the [Evidence protocol](../../spec/rs-pr-evidence/) and per-requester or per-requirement information. A released assertion stays verifiable until its declared validity expires; nothing recalls it. - The holder key is unverified: a request may carry an optional `holderKey` that is echoed into the - `cnf` member. Evidence issues no holder key, binds none, and verifies none, so `cnf` is a + `cnf` member. Evidence Gateway issues no holder key, binds none, and verifies none, so `cnf` is a caller-supplied convenience for whatever presentation layer the operator runs elsewhere. - Assertions are audience-scoped, not multi-verifier: the subject identifier is an audience-scoped pseudonym, so the same person requested for a different audience yields a different identifier. Purpose is an input to every subject binding and audit pseudonym as well, so one subject is not - linkable across purposes. This is deliberate, and it means an Evidence assertion is not a + linkable across purposes. This is deliberate, and it means an Evidence Gateway assertion is not a general-purpose credential a holder presents to several verifiers. - The request nonce is not replay protection: every request carries one canonical 32-byte random nonce that is echoed into the payload and never stored, uniqueness-checked, or exposed to @@ -88,13 +88,13 @@ Read the full context in the [Evidence protocol](../../spec/rs-pr-evidence/) and the strict verifier rejects it. Treat it as transport-authenticated convenience, never as something a third party can verify later. - CCCEV is an alignment, not conformance: the payload field names map to CCCEV 2.2.0 as a frozen - semantic reference with Evidence-specific extensions. No JSON-LD envelope is emitted and no + semantic reference with Evidence Gateway-specific extensions. No JSON-LD envelope is emitted and no conformance to CCCEV is claimed. - Disclosure families are an attestation, not a classifier: the runtime rejects two simultaneously enabled requirements that declare the same `disclosureGuard` family, but a declared family is a reviewed operator assertion. Nothing detects that two differently labelled families are semantically equivalent, so the combined-bundle disclosure review stays an operator duty. -- No cumulative disclosure budget: Evidence has no application database and persists no selector, +- No cumulative disclosure budget: Evidence Gateway has no application database and persists no selector, source, evidence, or response data, so nothing tracks cumulative disclosure across repeated or overlapping requests. Native rate controls are uniform per principal, tracked per process in in-process memory, bounded at 100,000 tracked keys, multiplied by replica count, and reset to @@ -104,8 +104,8 @@ Read the full context in the [Evidence protocol](../../spec/rs-pr-evidence/) and the same authority under different claim names, require a second deployment with its own bundle, signer, and audit boundary. - Bearer tokens only: a token carrying a proof-of-possession confirmation claim is denied rather - than accepted as an ordinary bearer, because Evidence validates no sender proof. An authorization - server that binds tokens to DPoP keys or client certificates must issue Evidence clients unbound + than accepted as an ordinary bearer, because Evidence Gateway validates no sender proof. An authorization + server that binds tokens to DPoP keys or client certificates must issue Evidence Gateway clients unbound tokens. - No hot reload, no admin surface, Unix targets only: there is no runtime upload, editor, approval API, hot reload, merge, mutation, governed-field override, or fallback path. Any change is a new @@ -123,7 +123,7 @@ Read the full context in the [Evidence protocol](../../spec/rs-pr-evidence/) and ## Registry Mint limits -Registry Mint issues the short-lived access tokens a resource server such as Evidence verifies, +Registry Mint issues the short-lived access tokens a resource server such as Evidence Gateway verifies, for deployments with no identity provider. A deployment that already has an identity provider does not run it. Read the full surface in the [Registry Mint reference](../../reference/mint/). @@ -150,7 +150,7 @@ not run it. Read the full surface in the [Registry Mint reference](../../referen These boundaries cut across components. - No source mutation, no event stream: Registry Relay does not write back to or otherwise mutate - source registry data, and it has no event-stream backend. Evidence reads its fixed sources + source registry data, and it has no event-stream backend. Evidence Gateway reads its fixed sources read-only as well, and persists nothing it read. - Aggregate routes are not a privacy budget: Relay aggregate routes return the configured statistical observations, but provide no built-in longitudinal privacy budget and do not track @@ -189,7 +189,8 @@ Its boundaries are covered in depth in the [Registry Relay protocol](../../spec/ Relay only serves and scopes compiled artifacts. - Governed enforcement is one PDP profile, not full interoperability: Governed runtime policy enforcement covers only the supported PDP profile - (`registry-evidence-gateway-pdp/v1`, the single PDP profile this build recognizes). + (`registry-evidence-gateway-pdp/v1`, the legacy Relay PDP profile identifier and the single + profile this build recognizes). The identifier does not name or connect to Evidence Gateway. It is not dynamic external policy discovery, and not enforcement of [ODRL](../../reference/standards/) terms outside the supported set. diff --git a/docs/site/src/content/docs/explanation/records-stay-home.mdx b/docs/site/src/content/docs/explanation/records-stay-home.mdx index 827e8583c..83d7322a6 100644 --- a/docs/site/src/content/docs/explanation/records-stay-home.mdx +++ b/docs/site/src/content/docs/explanation/records-stay-home.mdx @@ -25,12 +25,13 @@ guarantee. ## A question goes in, an answer comes out -The combined Relay and Evidence mental model is one sentence: **a bounded question crosses -into the institution, Relay reads and normalizes the source, Evidence returns one signed +The Evidence Gateway mental model is one sentence: **a bounded question crosses into the +institution, Evidence Gateway reads its configured authoritative source and returns one signed assertion carrying the answer, an evidence consumer uses it, and the decision owner remains -accountable for what happens next.** +accountable for what happens next.** Registry Relay offers a separate protected-read path and is +not part of the Evidence Gateway request. -An Evidence caller never sends the value it is asking about and never receives the +An Evidence Gateway caller never sends the value it is asking about and never receives the underlying record as the answer. It sends the identifier of a *predefined requirement* at an exact revision, the purpose it acts under, one selector per declared subject role, and a per-request nonce. That is the @@ -40,7 +41,7 @@ It receives one signed assertion carrying the values the requirement declares, a else (`products/evidence/contracts/evidence.schema.yaml`). The source record the answer was computed from stays behind. -Four questions carry equal weight in the Evidence contract, and none of them is the +Four questions carry equal weight in the Evidence Gateway contract, and none of them is the canonical one: adult status, residence region, professional licence status, and legal-parent relationship. All four run the same path, and none is a built-in type or a special route (`products/evidence/README.md`, `products/evidence/CONCEPT.md`). The @@ -54,13 +55,14 @@ answer is one boolean. The register's list of that child's parents never travels ```mermaid flowchart LR subgraph inst["Institution: data stays here"] - src[("Source registry\nCSV · XLSX · Parquet · PostgreSQL")] + relaySrc[("Relay source\nfile · database · HTTP")] + evidenceSrc[("Evidence Gateway source\nauthoritative HTTP API")] relay["Registry Relay\nprotected read API"] - evidence["Evidence\nevaluate · minimize · sign"] + evidence["Evidence Gateway\nevaluate · minimize · sign"] key>"Signing key\n(private half never leaves)"] audit[("Audit log")] - src -- read in place --> relay - relay -- one fixed protected read --> evidence + relaySrc -- read in place --> relay + evidenceSrc -- one fixed request --> evidence evidence -. records .-> audit key -. signs .-> evidence end @@ -72,7 +74,7 @@ flowchart LR classDef inside fill:#eef,stroke:#334,stroke-width:1px; classDef outside fill:#f7f7f7,stroke:#777,stroke-dasharray:3 3; - class src,relay,evidence,key,audit inside; + class relaySrc,evidenceSrc,relay,evidence,key,audit inside; class caller outside; ``` @@ -80,20 +82,20 @@ flowchart LR database table into a read-only, access-controlled API without replacing the source. Its scoped record routes can return source records to authorized callers that hold the dataset's row-read permission. -Evidence answers one predefined requirement about one set of subjects and returns a signed +Evidence Gateway answers one predefined requirement about one set of subjects and returns a signed assertion; it is the only component that evaluates a requirement, minimizes the result, and -signs it. -Evidence is the stronger minimization surface. +signs it. It contacts its own configured authoritative HTTP source rather than calling Relay. +Evidence Gateway is the stronger minimization surface. Relay record reads are scoped and audited, not open data. The policy boundary remains separate across the two products and their consumers. Relay -owns source access and adaptation policy. Evidence owns evidence authorization and the +owns source access and adaptation policy. Evidence Gateway owns evidence authorization and the declared disclosure of each requirement. The evidence consumer determines how evidence is used, and the decision owner remains accountable for requirements, eligibility, qualification, prioritization, approval, routing, payment, workflow, and action policy. Purpose-bound authorization can restrict an evidence request without changing which -component owns the consumer decision. The caller that invokes Evidence can be the evidence +component owns the consumer decision. The caller that invokes Evidence Gateway can be the evidence consumer or a technical intermediary acting for it. ## What stays home @@ -111,7 +113,7 @@ consumer or a technical intermediary acting for it. - The institution keeps custody: The design premise is *distributed custody*: each authority retains control of its own registry data, and the stack does not aggregate records into a central system. It provides the exchange surface, not a data lake. -- Evidence keeps no copy of what it read: Version 1 has no application database and +- Evidence Gateway keeps no copy of what it read: Version 1 has no application database and persists no selector, source, evidence, or response data. Raw source responses are never persisted or logged, and selector, source, and disclosed values never reach logs or the native audit record (`products/evidence/OPERATOR-CONTRACT.md`, invariants `V1-I14` and @@ -127,11 +129,11 @@ What crosses depends on the surface. Registry Relay can return scoped source records to an authorized caller through a governed, audited read bounded by the caller's per-dataset row scope and the dataset's configured filters and limits. -Evidence returns the values a requirement declares rather than the source row; keeping that +Evidence Gateway returns the values a requirement declares rather than the source row; keeping that answer narrow is a modelling discipline, because a well-modelled requirement declares the coarsest value form that still answers the question. -An Evidence assertion is a closed document. It carries the requirement it supports, the +An Evidence Gateway assertion is a closed document. It carries the requirement it supports, the evidence type it conforms to, the named issuer and the technical provider, the observation and validity timestamps, the purpose, the audience, the configuration revision it was produced under, one opaque binding per subject role, and one to sixteen declared values @@ -174,7 +176,7 @@ status or that the source is correct (invariant `V1-I24`). The "stays home" property rests on a few enforced rules, covered in depth in the Trust & Security material: -- One authorization decision, before any source read: Evidence resolves a single decision +- One authorization decision, before any source read: Evidence Gateway resolves a single decision binding the requester, the requirement revision, the purpose, the audience, the authority path, and every subject role's profile and value origin, and denies before it resolves a source credential or contacts a source. Permissions are never unioned across grants @@ -184,7 +186,7 @@ Security material: supply thresholds, expressions, scripts, paths, headers, source fields, or response projections. Every one of those is fixed by reviewed configuration that is immutable for the life of the process (invariants `V1-I02` and `V1-I18`). -- Every request is audited, at two gates: Evidence durably accepts an access-attempt record +- Every request is audited, at two gates: Evidence Gateway durably accepts an access-attempt record after authorization and before it touches a source, and a disclosure-release record after the final response bytes exist and before those exact bytes are released. A sink failure blocks the step rather than releasing unaudited evidence (invariants `V1-I13` and @@ -214,7 +216,7 @@ Security material: is reviewed as one disclosure surface, and that review is an operator duty rather than something the runtime can decide (invariant `V1-I03`). - Correctness depends on the source: Relay reports what the reviewed source consultation says, - and Evidence derives its answer from what the source returned. Neither product + and Evidence Gateway derives its answer from what the source returned. Neither product independently vouches for whether the source is correct or current. - Signed is the default, unsigned is not evidence: The signed flattened JWS is mandatory and the default result. A separately typed unsigned envelope exists only when both the @@ -222,14 +224,14 @@ Security material: is never later-verifiable evidence, and is never produced as a fallback from a signing failure (invariants `V1-I21` and `V1-I22`). - Matching is only as strict as the lookup contract: A lookup resolves to exactly one - match, no match, or ambiguity. Evidence never surfaces or chooses between candidates, and + match, no match, or ambiguity. Evidence Gateway never surfaces or chooses between candidates, and emits no candidate count, score, or comparison (invariant `V1-I10`). - Missing evidence is not a negative fact: A source value of `false`, an absent value, no match, ambiguity, and source failure have different reviewed meanings. A derivation must not collapse an absent value, an unresolved lookup, or a failure into `false`. Existence may be disclosed only as a separately authorized declared value, never as error detail (`products/evidence/contracts/problem-contract.yaml`). -- Evidence is not a consumer decision engine: Evidence returns governed evidence. The +- Evidence Gateway is not a consumer decision engine: Evidence Gateway returns governed evidence. The evidence consumer determines how that evidence is used, and the decision owner remains accountable for requirements, decisions, workflow, and actions. - This is not zero-knowledge: A boolean answer is a value computed inside the service from @@ -245,6 +247,6 @@ the underlying specifications. Weigh those alongside the limits in this section; - The security model and protocol contracts: [RS-SEC-G](../../spec/rs-sec-g/), [RS-PR-RELAY](../../spec/rs-pr-relay/), [RS-PR-EVIDENCE](../../spec/rs-pr-evidence/) -- [Evidence security model](../../security/evidence/) +- [Evidence Gateway security model](../../security/evidence/) - [Disclosure modes and computed answers](../disclosure-modes-and-computed-answers/) - [Threat model](../threat-model/) diff --git a/docs/site/src/content/docs/explanation/threat-model.mdx b/docs/site/src/content/docs/explanation/threat-model.mdx index 1d6372807..848cfd382 100644 --- a/docs/site/src/content/docs/explanation/threat-model.mdx +++ b/docs/site/src/content/docs/explanation/threat-model.mdx @@ -24,8 +24,8 @@ properties it claims: which threats does the architecture consider, what does it mitigate, and where do the residual risks lie?** It is deliberately a map of boundaries and limits, not a runbook. Hardening procedures belong to the [hardening checklist](../../security/hardening-checklist/), -and the invariant-by-invariant statement of what the Evidence runtime enforces belongs to the -[Evidence security model](../../security/evidence/). +and the invariant-by-invariant statement of what the Evidence Gateway runtime enforces belongs to the +[Evidence Gateway security model](../../security/evidence/). Here the goal is a defensible threat model: the boundaries the design draws, the threats it places in and out of scope, and the residual risks. @@ -53,19 +53,19 @@ beside them. A separate adopter demo sits outside the production trust boundary: - Registry Manifest: the offline metadata producer. No production data, no auth, no secrets. It lives entirely on the describe side of the primary boundary. - Registry Relay: a read-only consultation gateway over sources. -- Evidence: a minimum-disclosure assertion service. It answers one bounded, predefined +- Evidence Gateway: a minimum-disclosure assertion service. It answers one bounded, predefined question about one subject with a signed assertion carrying the answer and not the record. - Registry Platform: the shared security primitives that the runtime services build on. - Registry Mint: a supporting service, not a pattern of its own. It issues the short-lived - access tokens a resource server such as Evidence verifies, for a deployment with no - identity provider. The dependency runs one way: Evidence does not depend on Registry Mint. + access tokens a resource server such as Evidence Gateway verifies, for a deployment with no + identity provider. The dependency runs one way: Evidence Gateway does not depend on Registry Mint. - Solmara Lab: a separate adopter demo, running on synthetic data and demo configuration. Treat Solmara Lab as out of scope for production trust. Its demo and template integrations are integration examples, not a production freshness or replay-protection profile, and a team copying them into production must add request freshness, expiry, or nonce checks itself. This model has no credential-issuance or peer-federation boundary, because no product here has -one: Evidence issues no credential lifecycle and evaluates nothing on a peer's behalf. +one: Evidence Gateway issues no credential lifecycle and evaluates nothing on a peer's behalf. Security-critical primitives are concentrated in Registry Platform so that the behavior is identical across services and reviewable in one place. This is a deliberate attack-surface @@ -77,46 +77,45 @@ auditing separately. {/* SVG diagram. Every boundary label is restated in the sections that follow. */}
The Registry Stack trust boundaries in one map. A request path runs downward from - Registry Mint, which issues a short-lived access token, to the Caller, to Evidence, to - a Registry Relay protected read API, to the registry sources Relay reads in place. - Dashed rules mark the service edge in front of Evidence and in front of Relay, where - every record- or assertion-bearing route is authenticated before responding: Evidence + alt= + /.well-known/jwt-vc-issuer are unauthenticated at the Evidence Gateway edge." />
**The service edge (authentication).** Authentication is the trust boundary at the service edge, and each service authenticates every record- or assertion-bearing route before responding. Registry Relay runs exactly one authentication mode, either static-credential -fingerprint or OIDC. Evidence runs one reviewed OIDC bearer profile with exactly one trusted +fingerprint or OIDC. Evidence Gateway runs one reviewed OIDC bearer profile with exactly one trusted issuer and exact audience, token type, and algorithm allowlists, and one configured principal claim with no `client_id`, `azp`, header, or request fallback: missing data denies rather than -falling back to another claim (`V1-I04`). Evidence's unauthenticated surfaces are operational +falling back to another claim (`V1-I04`). Evidence Gateway's unauthenticated surfaces are operational and discovery only: `/health`, `/ready`, `/openapi.json`, `/.well-known/evidence/jwks.json`, and `/.well-known/jwt-vc-issuer`. None of them reveals -which evidence definitions are enabled or which requesters may invoke them. Evidence never +which evidence definitions are enabled or which requesters may invoke them. Evidence Gateway never trusts a proxy-supplied identity header, whatever the gateway in front of it asserts. -**Caller to Evidence.** This is the boundary the whole product exists to draw. The caller +**Caller to Evidence Gateway.** This is the boundary the whole product exists to draw. The caller crosses it with a bearer access token, a declared purpose, a named requirement revision, and selector values for the subject roles that requirement declares; what comes back is the answer, not the record. Four properties hold it: @@ -143,7 +142,7 @@ A reviewer should still read a declared purpose as the caller's authorized selec granted set rather than an identity-provider attestation, unless the operator has issued a distinct requester tag per purpose. -**Evidence to its fixed sources.** Evidence's outbound edge is deliberately not +**Evidence Gateway to its fixed sources.** Evidence Gateway's outbound edge is deliberately not general-purpose. Source calls are fixed by trusted bundle configuration and executed only by the core, which owns origin, method, fixed or selector-bound path, fixed headers, authentication, TLS, projection, redirect denial, proxy denial, limits, and a one-request @@ -152,44 +151,24 @@ ceiling; this is what closes SSRF, credential forwarding, and script-directed ne validates that output before a credential is resolved. Every source declares a response schema that Rust validates the projected response against before any extraction script runs, so a response outside its reviewed shape is a source-protocol failure rather than an input to fact -construction. Lookup collapses to `match`, `no_match`, or `ambiguous`: Evidence never fetches +construction. Lookup collapses to `match`, `no_match`, or `ambiguous`: Evidence Gateway never fetches broad candidate sets, follows pages, scores candidates, or exposes counts (`V1-I10`). Raw source responses are never persisted or logged (`V1-I14`). Hostname and fixed-origin verification stay mandatory, there is no trust-all mode, and ambient `HTTP_PROXY`-family variables are ignored. -**The Relay-protected source composition.** A common deployment makes the fixed source a -Relay-protected read API, reached with OAuth 2.0 client-credentials authentication, which is -one of the source authentication kinds the Evidence bundle schema admits. That composition is -a real boundary with real failure modes, and a reviewer should treat it as two independent -authorization decisions rather than one: - -- Evidence matches its own complete entitlement before it resolves a credential or contacts - Relay, and Relay then applies its own scope-based, deny-by-default workload authorization - before source work. Neither decision widens the other. -- The composition is only as narrow as the Relay route it reads. Evidence records this - honestly as an acquisition posture per source: `source-derived` and `field-projected` claim - acquisition minimization, while `record-transformed` claims disclosure minimization only. - A Relay route that returns a whole record makes the integration `record-transformed` even - though Evidence's own projection and derivation emit one narrow fact, and the operator must - not describe it as full lifecycle minimization. -- Evidence holds a client credential for Relay. Its disclosure gives an attacker Relay reach - at that client's scope, independent of every Evidence-side control, so it is custodied as - key material rather than as configuration. -- Relay authenticates the Evidence workload, not the caller that asked Evidence. Bundle-fixed - headers cannot set authentication, routing, cookie, framing, forwarding, proxy, or tracing - fields, so no caller correlation identifier crosses into the source request. Joining the two - audit trails for one request is therefore an operator procedure over two records, not - something either service does for you. -- Readiness performs a bounded token bootstrap against the configured token endpoint, so a - token-endpoint outage surfaces as a failed readiness check rather than as a first failed - request. It never sends an evidence-data request or probes a source data endpoint. - -**Registry Mint to Evidence.** Registry Mint issues access tokens; Evidence verifies them as -an ordinary resource server. The dependency runs one way, and Evidence's only knowledge of +**Registry Relay and Evidence Gateway remain separate.** A deployment may operate both products, +but no request path joins them. Evidence Gateway contacts its own configured authoritative HTTP +sources; Relay contacts the sources compiled for its protected-read APIs. Each product owns its own +credentials, authorization decision, audit trail, and readiness checks. A reviewer should reject a +deployment description that treats Relay authorization as Evidence Gateway authorization, or that +describes Relay as an Evidence Gateway source hop. + +**Registry Mint to Evidence Gateway.** Registry Mint issues access tokens; Evidence Gateway verifies them as +an ordinary resource server. The dependency runs one way, and Evidence Gateway's only knowledge of Registry Mint is an issuer URL and a key set: it reads every claim by the name in its own `authentication` block, so any issuer writing those claims serves equally well. Registry -Mint's tests drive Evidence's authenticator, and Evidence does not depend on Registry Mint. +Mint's tests drive Evidence Gateway's authenticator, and Evidence Gateway does not depend on Registry Mint. What a reviewer checks depends on which of the two shapes the deployment runs: - **With Registry Mint.** The client registry becomes part of the trust boundary. Registry @@ -198,14 +177,14 @@ What a reviewer checks depends on which of the two shapes the deployment runs: consequence is that whoever can write a registration file into `clients.directory` can mint a token carrying any requester tags, and the running process re-reads that directory on `SIGHUP` without a restart. Treat the registry directory as sensitive as the signing key. - Registry Mint serves plain HTTP behind operator-terminated TLS, while Evidence requires an + Registry Mint serves plain HTTP behind operator-terminated TLS, while Evidence Gateway requires an HTTPS issuer and key set with no loopback exception, so the TLS terminator is load-bearing. - **Without Registry Mint.** A deployment that already has an identity provider does not run - Registry Mint at all; Evidence points at the provider's issuer and JWKS directly. Tag - issuance, client lifecycle, and revocation move entirely to that provider, and Evidence's + Registry Mint at all; Evidence Gateway points at the provider's issuer and JWKS directly. Tag + issuance, client lifecycle, and revocation move entirely to that provider, and Evidence Gateway's residual exposure is its trust in one issuer's key set. -Both shapes share one property worth stating plainly: Evidence has no token revocation. A +Both shapes share one property worth stating plainly: Evidence Gateway has no token revocation. A minted or issued token is accepted until it expires, which is why token lifetime is bounded short. If the issuer's key set becomes unreachable, an already-retrieved key set keeps being accepted for a bounded allowance and then every request is rejected with the same closed `401` @@ -263,12 +242,12 @@ data leakage, and privacy regressions that expose raw subject identifiers. verification against the configured issuer JWKS, plus issuer, audience, token type, and algorithm checks. The service still owns its route scopes and grants regardless of what the token asserts. -- A sender-constrained token replayed as a bearer token: Evidence denies an access token +- A sender-constrained token replayed as a bearer token: Evidence Gateway denies an access token carrying an RFC 7800 proof-of-possession confirmation claim rather than accepting it as an ordinary bearer, because it validates no sender proof and accepting one would silently discard the constraint the token was issued under (`V1-I32`). - Privilege escalation or over-reach: Authorization is deny-by-default. Relay refuses - unauthorized callers before source work; Evidence requires exactly one complete entitlement + unauthorized callers before source work; Evidence Gateway requires exactly one complete entitlement match before audit, credential resolution, or source access. Reach is never widened at request time. - An existence or matching oracle: No-match, ambiguous, missing-fact, and @@ -310,9 +289,9 @@ data leakage, and privacy regressions that expose raw subject identifiers. - SSRF and uncontrolled egress: Registry Stack project authoring accepts exact HTTPS source origins. Relay's compiled plan fixes the destination, method, path authority, safe headers, and cumulative call budgets before the runtime resolves a credential or sends a request, and - Evidence's fixed executor does the same for its own sources. Scripts on either side control + Evidence Gateway's fixed executor does the same for its own sources. Scripts on either side control ordinary request flow only inside that host-enforced authority. -- A hostile or defective reviewed script: Evidence's script engine has no filesystem, +- A hostile or defective reviewed script: Evidence Gateway's script engine has no filesystem, environment, network, process, or module access, no ambient clock or randomness, and a normative operation ceiling that terminates a runaway invocation with a closed, value-free error. @@ -321,7 +300,7 @@ data leakage, and privacy regressions that expose raw subject identifiers. receive a PDP permit or fail closed with a stable `pdp.*` code rather than falling back to an ungoverned read. -**Audit as a control.** Evidence writes two mandatory records per request: an access-attempt +**Audit as a control.** Evidence Gateway writes two mandatory records per request: an access-attempt event that must be durably accepted before the first source read, and a disclosure-release event that must be durably accepted after signing and before the response is released. Either failure blocks the corresponding action. The chain is keyed and hash-linked, has no severity @@ -334,7 +313,7 @@ replaces each exact-value trust scope with a field-bound `registry:trust::hmac-sha256:` handle under the deployment audit key, which supports investigation and same-key correlation without disclosing the trusted value. -Three caveats for the auditor. First, exactly one Evidence process may write a given audit +Three caveats for the auditor. First, exactly one Evidence Gateway process may write a given audit path: the sink takes an exclusive advisory lock, because the chain head lives in process memory and two writers would interleave records and destroy tamper evidence. That makes the supported shape one replica per audit path, active/passive rather than active/active. Second, @@ -355,7 +334,7 @@ These are the risks the design does *not* close: - Key custody is not certified by health checks: Readiness, liveness, and offline validation confirm that key material parses and that its file ownership and mode are what the contract - requires. They do not certify production-grade custody. Evidence Version 1 has one secret + requires. They do not certify production-grade custody. Evidence Gateway Version 1 has one secret provider, the file provider, and no hardware-module option, so a deployment using demo-generated or long-lived software keys can be reachable and internally consistent yet not production-secure. Custody, rotation, and provider approval remain operator responsibilities. @@ -375,7 +354,7 @@ These are the risks the design does *not* close: running N instances behind a load balancer multiplies every limit by N and a restart resets each budget to full. This matters most for the failed-selector budget, because that budget, not throughput, is the selector-enumeration defense. -- A released assertion cannot be recalled: Evidence has no revocation, status list, or +- A released assertion cannot be recalled: Evidence Gateway has no revocation, status list, or presentation-time check. The only levers over a released assertion are its declared validity window and signing-key rotation, and rotation does not invalidate assertions a retained public key still verifies. @@ -396,7 +375,7 @@ These are the risks the design does *not* close: institution selected the correct source fields, lawful purpose, derivation rule, or disclosure default. Those decisions require project review and fixture evidence. - Admin reload is not a capability: Relay's admin surface is documented in its own generated - OpenAPI, and Evidence has no admin listener, reload route, or configuration apply path at + OpenAPI, and Evidence Gateway has no admin listener, reload route, or configuration apply path at all. A configuration change is a new reviewed revision and a restart, in both cases. ## What is explicitly out of scope @@ -404,7 +383,7 @@ These are the risks the design does *not* close: These are non-goals for this version. None of them should be read into a Registry Stack conformance claim: -- A credential lifecycle: Evidence's SD-JWT VC output is a second serialization of the same +- A credential lifecycle: Evidence Gateway's SD-JWT VC output is a second serialization of the same stateless assertion under a frozen profile. There is no issuance session, holder binding ceremony, status list, revocation, presentation verification, or persisted credential state, and an optional caller-supplied holder key is echoed unverified into a confirmation claim @@ -412,12 +391,13 @@ conformance claim: - Delegated or federated evaluation between peers: no service in this model evaluates a question on another deployment's behalf, and there is no trust-chain discovery, peer registry, or cross-institution evaluation route. -- Identity resolution: lookup is match, no-match, or ambiguous. Evidence is not an +- Identity resolution: lookup is match, no-match, or ambiguous. Evidence Gateway is not an identity-resolution or record-linkage engine and returns no candidate material. - Cross-verifier credential use: the subject binding is audience-scoped, so an assertion is meaningful to one relying party and correlatable across none. - Full external-policy interoperability: governed Relay PDP enforcement covers only the one - supported PDP profile (`registry-evidence-gateway-pdp/v1`). It is not dynamic external policy + supported PDP profile (`registry-evidence-gateway-pdp/v1`). This legacy identifier belongs to + Relay and does not name or connect to Evidence Gateway. It is not dynamic external policy discovery and not enforcement of ODRL terms outside that profile. Unsupported terms or invalid policy identity fail closed. - Certified standards compliance: Aligning with a standard is not conforming to it. Speaking @@ -427,7 +407,7 @@ conformance claim: Features, Records, and EDR adapters and SP DCI sync) are feature-gated and mount only when the build is configured with the matching Cargo feature. Do not infer their presence from the route catalog of a different build. -- Non-Unix targets: Evidence Version 1 supports Unix targets only, because its secret and +- Non-Unix targets: Evidence Gateway Version 1 supports Unix targets only, because its secret and audit invariants depend on owner, mode, no-follow, link-count, and open-file identity checks. ## Related @@ -436,6 +416,6 @@ conformance claim: - [RS-PR-EVIDENCE](../../spec/rs-pr-evidence/), [RS-PR-RELAY](../../spec/rs-pr-relay/): protocol contracts - [RS-ARC-G](../../spec/rs-arc-g/): the two-layer architecture -- [Evidence security model](../../security/evidence/): the invariant matrix and its tests +- [Evidence Gateway security model](../../security/evidence/): the invariant matrix and its tests - [Harden a production deployment](../../security/hardening-checklist/): hardening procedures - [Data minimization and purpose limitation](../data-minimization-and-purpose-limitation/) diff --git a/docs/site/src/content/docs/explanation/trusted-context-constraints.mdx b/docs/site/src/content/docs/explanation/trusted-context-constraints.mdx index 3689f5acc..21fcf6a29 100644 --- a/docs/site/src/content/docs/explanation/trusted-context-constraints.mdx +++ b/docs/site/src/content/docs/explanation/trusted-context-constraints.mdx @@ -1,6 +1,6 @@ --- title: Trusted context constraints -description: How Registry Relay and Evidence each preserve policy facts such as legal basis, consent, jurisdiction, assurance, and source freshness at their own separate boundaries. +description: How Registry Relay and Evidence Gateway each preserve policy facts such as legal basis, consent, jurisdiction, assurance, and source freshness at their own separate boundaries. status: current owner: registry-docs source_repos: @@ -18,10 +18,9 @@ caller, the product that answers the caller, and the source registry behind it. supplies shared types and redacted reporting conventions to the products that use them. Each product still owns the decision made at its own boundary. -Read one thing before the rest: Registry Relay and Evidence do not share an authorization model. -No service in this stack authorizes a caller and then consults another service on its behalf. -Evidence enforces its own boundary, and when it reads a Relay-protected API it does so as an -ordinary fixed HTTP source, no differently from any other client of that API. +Read one thing before the rest: Registry Relay and Evidence Gateway do not share an authorization model +or a source path. No service in this stack authorizes a caller and then consults another service on +its behalf. Each product enforces its own boundary against its own configured sources. ## The shared vocabulary @@ -34,7 +33,7 @@ Registry Platform's policy vocabulary covers five families: - Source freshness limits the accepted age of an observation. That vocabulary lives in `registry-platform-pdp` and is reported through `registry-config-report`. -Registry Relay uses it. Evidence does not: Evidence enforces its own constraints under its own +Registry Relay uses it. Evidence Gateway does not: Evidence Gateway enforces its own constraints under its own frozen contract names, which are described below and specified in `products/evidence/contracts/`. @@ -55,14 +54,14 @@ declares that meaning and its fixtures prove it. If the observation-time contract is not proven, diagnostics must report it as unknown. They must not reinterpret a domain date as source freshness. -## Evidence owns its own boundary +## Evidence Gateway owns its own boundary -Evidence authenticates the caller itself. It validates the bearer token against exactly one +Evidence Gateway authenticates the caller itself. It validates the bearer token against exactly one configured issuer with exact audience, token type, and algorithm allowlists, and it reads the principal from one configured claim with no `client_id`, `azp`, header, or request fallback. Unsigned headers and caller request fields never substitute for authenticated authority, even behind a gateway (invariant `V1-I04`, -[Evidence operator contract](../../products/registry-evidence/operator-contract/)). +[Evidence Gateway operator contract](../../products/registry-evidence/operator-contract/)). Authorization is a single decision, not a series of separately satisfied checks. One exact entitlement match binds requester, optional actor, requirement revision, purpose, every @@ -80,24 +79,22 @@ authorization is most often assumed rather than enforced: identifiers are accepted only from authenticated context and must be bound to the complete entitlement (invariant `V1-I07`). -Evidence does not pin a Relay consultation by contract hash, and it has no notion of a compiled -evidence mode selecting one. It declares an HTTP source with a fixed origin, method, fixed or +Evidence Gateway has no notion of a Relay consultation or a compiled evidence mode selecting one. It +declares an HTTP source with a fixed origin, method, fixed or selector-bound path, fixed non-secret headers, denied redirects, and client-side response -projection, all executed by the core rather than by a script (invariant `V1-I09`). If that origin -happens to be a Relay-protected API, Relay evaluates its own policy against the request Evidence -makes, under the credentials Evidence was configured with. Neither product sees the other's -authorization decision. +projection, all executed by the core rather than by a script (invariant `V1-I09`). The source +boundary belongs entirely to Evidence Gateway and its authoritative source. -## Freshness has no Evidence counterpart +## Freshness has no Evidence Gateway counterpart -An assertion carries `observedAt`, which is when Evidence evaluated the requirement. It is not a -source-declared observation time, and Evidence Version 1 has no source freshness family: there is +An assertion carries `observedAt`, which is when Evidence Gateway evaluated the requirement. It is not a +source-declared observation time, and Evidence Gateway Version 1 has no source freshness family: there is no maximum accepted observation age, no freshness field, and no configuration for one. The request nonce is uninterpreted correlation data and is explicitly not a freshness proof (`products/evidence/contracts/cccev-field-mapping.yaml`). -A deployment that needs an age bound on the underlying record has to obtain it from the source -contract on the Relay side. An assertion on its own does not carry one. +A deployment that needs an age bound on the underlying record has to define and enforce it in the +authoritative source contract. An assertion on its own does not carry one. ## Reports and audit evidence @@ -117,10 +114,10 @@ distinct from an assurance value asserted in authorization context. ## Review questions - Is source freshness derived from a proven Relay observation contract rather than a domain date? -- Does Evidence deny an unauthorized request before it contacts any source? -- Is every dimension of the Evidence entitlement matched as one decision rather than one at a time? -- Where Evidence reads a Relay-protected API, is Relay's own policy still evaluated for the - credentials Evidence presents? +- Does Evidence Gateway deny an unauthorized request before it contacts any source? +- Is every dimension of the Evidence Gateway entitlement matched as one decision rather than one at a time? +- Are Registry Relay and Evidence Gateway sources, credentials, authorization decisions, and audit + trails kept separate? - Are reports bounded and redacted at both product boundaries? ## Related pages diff --git a/docs/site/src/content/docs/index.mdx b/docs/site/src/content/docs/index.mdx index ecf0a0a27..ba7432002 100644 --- a/docs/site/src/content/docs/index.mdx +++ b/docs/site/src/content/docs/index.mdx @@ -1,6 +1,6 @@ --- title: Registry Stack documentation -description: Answer a bounded question with Evidence, start a registry from a spreadsheet, or connect an existing registry. +description: Answer a bounded question with Evidence Gateway, start a registry from a spreadsheet, or connect an existing registry. status: current owner: registry-docs source_repos: @@ -13,24 +13,24 @@ standards_referenced: [] --- Registry Stack helps an institution answer questions about data it already -holds without giving callers direct access to the source. Two doors: Evidence +holds without giving callers direct access to the source. Two doors: Evidence Gateway signs the answer to one bounded question, and Registry Relay exposes selected records through a protected read-only API. -## Answer a bounded question with Evidence +## Answer a bounded question with Evidence Gateway -Use Evidence when the caller needs to learn only a fact, not to read a record. +Use Evidence Gateway when the caller needs to learn only a fact, not to read a record. It answers one bounded question about one subject and signs the answer, releasing the answer rather than the row behind it. Adult status, residence region, professional licence status, and legal-parent relationship are coequal acceptance definitions; you author whichever one your institution needs, the same way. -[Evidence overview](start/evidence-quickstart/) explains the source, assertion, +[Evidence Gateway overview](start/evidence-quickstart/) explains the source, assertion, verification, and audit boundaries. Continue with -[your first Evidence assertion](tutorials/first-evidence-assertion/) to see the +[your first Evidence Gateway assertion](tutorials/first-evidence-assertion/) to see the boundary in one verified request. When local authoring is complete, -[build and deploy an Evidence project](tutorials/build-and-deploy-evidence-project/) creates a +[build and deploy an Evidence Gateway project](tutorials/build-and-deploy-evidence-project/) creates a reviewed candidate without promoting local development state. Registry Mint remains an optional token issuer for deployments without a suitable identity provider. @@ -62,17 +62,17 @@ the source requires authentication or response normalization. ## Keep the product boundaries clear Registry Relay owns source access and protected record surfaces. -Evidence owns bounded question answering, signing, and minimum disclosure, and -runs independently of Relay; it can read a Relay API as one fixed HTTP source. +Evidence Gateway owns bounded question answering, signing, and minimum disclosure, and +runs independently of Relay against its own configured authoritative HTTP sources. The caller receives only the output authorized for that service. Both registryctl paths, spreadsheet and HTTP, use the same authoring, offline test, disposable development, and build commands. The 1.0 project-local workbook path stops there. A governed deployment starts after an operator-managed HTTP source is bound, then continues through independent -approval and package generation. Evidence is not one of those paths: Evidence +approval and package generation. Evidence Gateway is not one of those paths: Evidence Gateway has its own toolset and deployment project shape, covered by the -[Evidence overview](start/evidence-quickstart/). +[Evidence Gateway overview](start/evidence-quickstart/). ## Move beyond the first run diff --git a/docs/site/src/content/docs/map/boundaries-and-map.mdx b/docs/site/src/content/docs/map/boundaries-and-map.mdx index cd2facd32..1e2726c7f 100644 --- a/docs/site/src/content/docs/map/boundaries-and-map.mdx +++ b/docs/site/src/content/docs/map/boundaries-and-map.mdx @@ -27,7 +27,7 @@ standards_referenced: import ProjectMap from '../../../components/ProjectMap.astro'; The formal Registry Stack has four products with distinct responsibilities: Registry Platform, -Registry Manifest, Registry Relay, and Evidence. +Registry Manifest, Registry Relay, and Evidence Gateway. Registry Mint is a supporting service beside them, issuing short-lived access tokens for deployments that have callers and no identity provider. Solmara Lab is a separate adopter project that demonstrates the products together. @@ -40,9 +40,9 @@ and to understand how the products and the external demo connect at runtime. separate Solmara Lab adopter demo. Registry Platform provides shared auth, audit, HTTP, crypto, SD-JWT, and test crates. Registry Manifest provides portable metadata contracts, validation, and renderers. Registry Relay serves protected read-only APIs over sensitive - registry sources. Evidence answers one bounded question about one subject with a signed - assertion. Registry Mint issues the short-lived access tokens Evidence verifies. Solmara - Lab runs Relay, Evidence, and Mint together." /> + registry sources. Evidence Gateway answers one bounded question about one subject with a signed + assertion. Registry Mint issues the short-lived access tokens Evidence Gateway verifies. Solmara + Solmara Lab is an external synthetic-data adopter demo." /> @@ -62,7 +62,7 @@ For how the products connect at runtime and how Solmara Lab demonstrates them, s | Which shared Rust crate owns auth helpers, OIDC verification, audit envelopes, HTTP security, outbound HTTP policy, crypto, SD-JWT VC helpers, or test fixtures? | [Registry Platform](https://github.com/registrystack/registry-stack) | | How is a CSV, XLSX, Parquet, or PostgreSQL source exposed as authorized entity routes? | [Registry Relay](../../products/registry-relay/) | | How is `metadata.yaml` validated or rendered into standards-facing artifacts? | [Registry Manifest](https://github.com/registrystack/registry-stack) | -| How is one bounded question about one subject answered with a signed assertion that carries the answer and not the record? | [Evidence](../../products/registry-evidence/) | +| How is one bounded question about one subject answered with a signed assertion that carries the answer and not the record? | [Evidence Gateway](../../products/registry-evidence/) | | How does a deployment with callers and no identity provider issue access tokens? | [Registry Mint](../../reference/mint/) | | How do the services run together in a local demo? | [Solmara Lab](https://github.com/registrystack/solmara-lab/blob/00cd51a2be4a405ef75d337ddcede0f9de134b1f/README.md) | @@ -78,7 +78,7 @@ Registry Platform is a shared crate workspace. It does not run a service or deci - Registry Relay route behavior, runtime source binding, metadata publication, or Relay-specific scope semantics. -- Evidence requirement definitions, authorization grants, disclosure decisions, service routes, +- Evidence Gateway requirement definitions, authorization grants, disclosure decisions, service routes, assertion construction, or signing policy. {/* Evidence: Rust in registry-evidence owns authentication, authorization, fixed source execution, output validation, evidence construction, signing, and audit; the platform @@ -106,7 +106,7 @@ Registry Manifest is a pure library and CLI with no runtime data dependencies. - Production source configuration. Source paths, table IDs, scopes, cache paths, and backend runtime details belong in Registry Relay configuration, not in portable manifests. {/* Evidence: contracts.yaml, registry-manifest.metadata-yaml consumer note. */} -- Evidence deployment configuration. An Evidence process loads one immutable governed bundle and +- Evidence Gateway deployment configuration. An Evidence Gateway process loads one immutable governed bundle and one closed runtime file mounted read-only at startup, and reads no portable manifest. {/* Evidence: "Governed bundle and operator runtime", products/evidence/OPERATOR-CONTRACT.md. */} @@ -125,9 +125,9 @@ Registry Relay exposes protected read-only APIs over registry sources. It does n them for callers, but the schema is defined and versioned in Registry Manifest. {/* Evidence: crates/registry-manifest-core/README.md:7-9 at tag v0.9.0 (schema ownership); registry-relay evidence packet, metadata publication section. */} -- Assertion evaluation, disclosure, and signing owned by Evidence. Registry Relay can declare - evidence offerings and route clients onward, but requirement evaluation, disclosure form, and - signing run in Evidence, which reads a Relay API as one ordinary fixed HTTP source. +- Assertion evaluation, disclosure, and signing owned by Evidence Gateway. Registry Relay can declare + evidence offerings, but requirement evaluation, disclosure form, source access, and signing run + independently in Evidence Gateway. {/* Evidence: registry-relay evidence packet, evidence offering verification section; contract registry.evidence.fixed-http-json-source/v1, products/evidence/contracts/source-contract.yaml. */} @@ -142,9 +142,9 @@ Registry Relay exposes protected read-only APIs over registry sources. It does n Registry Relay is not an open-data portal. It publishes restricted consultation APIs for authorized systems only. {/* Evidence: crates/registry-relay/README.md:16 at tag v0.9.0. */} -## Evidence +## Evidence Gateway -Evidence answers one bounded question about one subject and returns a signed assertion carrying the +Evidence Gateway answers one bounded question about one subject and returns a signed assertion carrying the answer rather than the record. It does not own: - Source access as a general capability. Each evaluation makes exactly one fixed, bounded HTTP JSON @@ -153,22 +153,22 @@ answer rather than the record. It does not own: fulfillment, and source-planning scripts are outside the Version 1 contract. {/* Evidence: contract registry.evidence.fixed-http-json-source/v1, products/evidence/contracts/source-contract.yaml (frozen). */} -- Record lookup and identity resolution. The authoritative provider owns lookup. Evidence accepts +- Record lookup and identity resolution. The authoritative provider owns lookup. Evidence Gateway accepts only `match`, `no_match`, or `ambiguous`, and does not score candidates, choose a provider record, or expose counts, near-match hints, or per-field diagnostics. {/* Evidence: "Source and selector controls", products/evidence/OPERATOR-CONTRACT.md. */} -- Portable metadata renderers owned by Registry Manifest. Evidence produces no DCAT, SHACL, +- Portable metadata renderers owned by Registry Manifest. Evidence Gateway produces no DCAT, SHACL, BRegDCAT-AP, or OGC Records artifacts and consumes no manifest. - Shared auth, OIDC, audit, HTTP security, crypto, SD-JWT, and testing primitives owned by Registry - Platform. Evidence owns the assertion behavior that composes those primitives. + Platform. Evidence Gateway owns the assertion behavior that composes those primitives. {/* Evidence: crates/registry-evidence/Cargo.toml depends on registry-platform-audit, -crypto, -httpsec, -httputil, -oidc, and -sdjwt, and on no other product crate. */} -- Token issuance and identity proofing. Evidence verifies access tokens under one reviewed OIDC +- Token issuance and identity proofing. Evidence Gateway verifies access tokens under one reviewed OIDC profile with exactly one trusted issuer; it issues none. Registry Mint issues them for a deployment with no identity provider. {/* Evidence: "Supported deployment", products/evidence/OPERATOR-CONTRACT.md. */} - Consumer decisions. Requirements, eligibility, ranking, approval, routing, payment, workflow, and - action policy stay with the accountable decision owner. Evidence is not a workflow, orchestration, + action policy stay with the accountable decision owner. Evidence Gateway is not a workflow, orchestration, or case-management engine and not a runtime policy engine or general PDP. {/* Evidence: Version 1 non-goals, products/evidence/CONCEPT.md section 4. */} - A credential lifecycle. Version 1 has no issuance session, holder binding ceremony, status list, @@ -176,7 +176,7 @@ answer rather than the record. It does not own: {/* Evidence: Version 1 non-goals, products/evidence/CONCEPT.md section 4; "Response formats", products/evidence/OPERATOR-CONTRACT.md. */} -The default Evidence response is a flattened JWS JSON assertion (`application/jose+json`), not a W3C +The default Evidence Gateway response is a flattened JWS JSON assertion (`application/jose+json`), not a W3C Verifiable Credentials Data Model JSON-LD envelope. An SD-JWT VC serialization (`application/dc+sd-jwt`) of the same stateless assertion is releasable only where the immutable bundle and the one matched authority grant both name that format, under the frozen profile in @@ -192,7 +192,7 @@ identity provider still has one. It does not own: machine clients through `private_key_jwt`, not people. - Caller-declared authority. Token authority is written from the client registry and never from the caller's own request. -- Evidence authorization. Evidence independently verifies the token and re-authorizes every request +- Evidence Gateway authorization. Evidence Gateway independently verifies the token and re-authorizes every request against its own bundle and authority grants. {/* Evidence: contract status and stable properties, docs/site/src/content/docs/reference/mint.mdx, @@ -202,7 +202,7 @@ identity provider still has one. It does not own: ## Solmara Lab Solmara Lab is a separately maintained adopter demo for the fictional Republic of Solmara. -It runs Relay, Evidence, and Mint together in local and hosted topologies, but it is not a formal +It uses generated synthetic data, but it is not a formal Registry Stack product. It does not own: - Production deployment guidance. The demo uses generated synthetic data and demo configuration. diff --git a/docs/site/src/content/docs/operate/advanced/inspect-and-diagnose.mdx b/docs/site/src/content/docs/operate/advanced/inspect-and-diagnose.mdx index ea3485b38..a5f50d8ad 100644 --- a/docs/site/src/content/docs/operate/advanced/inspect-and-diagnose.mdx +++ b/docs/site/src/content/docs/operate/advanced/inspect-and-diagnose.mdx @@ -1,6 +1,6 @@ --- title: Inspect and diagnose a running deployment -description: Inspect Relay, Evidence, and Registry Mint runtime posture, audit, health, readiness, and API shape, then classify failures with stable diagnostics. +description: Inspect Relay, Evidence Gateway, and Registry Mint runtime posture, audit, health, readiness, and API shape, then classify failures with stable diagnostics. status: current owner: registry-docs source_repos: @@ -15,7 +15,7 @@ locale: en standards_referenced: [] --- -Use this procedure to inspect a running Relay, Evidence, or Registry Mint instance and diagnose +Use this procedure to inspect a running Relay, Evidence Gateway, or Registry Mint instance and diagnose source denial, policy denial, ambiguity, stale materialization, bundle rejection, or capability mismatch without collecting source rows or secret values. @@ -23,7 +23,7 @@ mismatch without collecting source rows or secret values. - Use the protected operator network and a least-privilege posture or API credential. - Know the active product, environment, stream, instance, and expected bundle sequence for Relay, - and the deployment revision for Evidence and Registry Mint. + and the deployment revision for Evidence Gateway and Registry Mint. - Keep public problem responses, operator diagnostics, restricted posture, and protected audit records in separate access classes. - Reproduce with synthetic identifiers unless separate authority permits another probe. @@ -34,8 +34,8 @@ Public problem details give callers stable, minimized classifications. The default posture tier is redacted for operational sharing. Restricted posture can contain per-resource or provider detail and belongs only to trusted operators. -Relay, Evidence, and Registry Mint each write their own audit or operational records and keep -their own keys separate: Relay's redacted posture and audit sink, Evidence's keyed JSONL audit +Relay, Evidence Gateway, and Registry Mint each write their own audit or operational records and keep +their own keys separate: Relay's redacted posture and audit sink, Evidence Gateway's keyed JSONL audit chain (`products/evidence/OPERATOR-CONTRACT.md`, Audit and operational data), and Registry Mint's keyed JSONL token-decision chain. @@ -58,12 +58,12 @@ Inspect each surface for its own purpose: | Surface | Use | Boundary | | --- | --- | --- | -| `GET /healthz` (Relay) or `GET /health` (Evidence, Registry Mint) | Process liveness | Does not check all dependencies or data freshness; Evidence's `/health` answers 200 even when a source credential is missing | -| `GET /ready` | Current traffic-admission readiness | Does not prove backup freshness or country approval; Evidence checks its signing, audit, subject-binding, and source credentials, while Mint checks that clients exist and its audit writer is healthy | -| `GET /admin/v1/posture` (Relay only) | Redacted deployment and control observations | Default and restricted tiers expose different detail; Evidence and Registry Mint have no equivalent admin posture endpoint | -| Product audit records | Security and request evidence | Retained chain integrity does not prove complete off-host receipt; use `evidence verify-audit` for Evidence and `mint verify-audit` for Mint | -| `GET /openapi.json` | Concrete API shape for the running instance | Relay's document is configuration and authentication dependent; Evidence's is the released generated artifact, unauthenticated and independent of the deployed bundle | -| Evidence `GET /metrics` (only when `metricsListener` is configured) | Request-boundary counts and latency by route, method, status, and problem code | Absent unless configured; never serves evidence routes and reveals no request content | +| `GET /healthz` (Relay) or `GET /health` (Evidence Gateway, Registry Mint) | Process liveness | Does not check all dependencies or data freshness; Evidence Gateway's `/health` answers 200 even when a source credential is missing | +| `GET /ready` | Current traffic-admission readiness | Does not prove backup freshness or country approval; Evidence Gateway checks its signing, audit, subject-binding, and source credentials, while Mint checks that clients exist and its audit writer is healthy | +| `GET /admin/v1/posture` (Relay only) | Redacted deployment and control observations | Default and restricted tiers expose different detail; Evidence Gateway and Registry Mint have no equivalent admin posture endpoint | +| Product audit records | Security and request evidence | Retained chain integrity does not prove complete off-host receipt; use `evidence verify-audit` for Evidence Gateway and `mint verify-audit` for Mint | +| `GET /openapi.json` | Concrete API shape for the running instance | Relay's document is configuration and authentication dependent; Evidence Gateway's is the released generated artifact, unauthenticated and independent of the deployed bundle | +| Evidence Gateway `GET /metrics` (only when `metricsListener` is configured) | Request-boundary counts and latency by route, method, status, and problem code | Absent unless configured; never serves evidence routes and reveals no request content | Query health and readiness through the same network path used by traffic admission: @@ -87,10 +87,10 @@ curl -fsS \ Fetch the concrete Relay instance OpenAPI only through its configured authenticated route, and compare it with the reviewed generated input and the [Relay API reference](../../../reference/apis/registry-relay/). -Evidence's `GET /openapi.json` needs no credential, because it always serves the same released +Evidence Gateway's `GET /openapi.json` needs no credential, because it always serves the same released generated artifact rather than a deployment-specific document (`products/evidence/OPERATOR-CONTRACT.md`, Startup and readiness); compare it with the -[Evidence API reference](../../../reference/apis/registry-evidence/). +[Evidence Gateway API reference](../../../reference/apis/registry-evidence/). An OpenAPI match does not prove authorization, source behavior, or claim semantics. ## Load the stable diagnostic catalogs @@ -110,8 +110,8 @@ Branch on the exact code and response status. Do not parse error prose, paths, or type URI segments. These catalogs cover Relay, `registryctl`, and shared platform operations; they do not enumerate -Evidence or Registry Mint failures. Evidence's closed problem-code catalog is the -[Evidence errors and problems reference](../../../reference/evidence-problems/) instead, and it +Evidence Gateway or Registry Mint failures. Evidence Gateway's closed problem-code catalog is the +[Evidence Gateway errors and problems reference](../../../reference/evidence-problems/) instead, and it needs no separate CLI catalog because the codes are fixed by the frozen public contract. ## Diagnose the failure class @@ -125,11 +125,11 @@ boundary: Relay could not activate the source-credential capability its consulta needs at startup. Offline fixture failures such as `source.status_rejected`, `source.unavailable`, and `authorization.denied` classify synthetic Relay source behavior. -Evidence collapses every source-boundary failure (unreachable, timed out, wrong credential, wrong +Evidence Gateway collapses every source-boundary failure (unreachable, timed out, wrong credential, wrong media type, an oversized response, malformed JSON, or an error envelope) into the single `dependency_unavailable` problem (`crates/registry-evidence/src/runtime.rs`, `source_failure_problem`; see the -[Evidence errors and problems reference](../../../reference/evidence-problems/)). +[Evidence Gateway errors and problems reference](../../../reference/evidence-problems/)). Confirm which boundary denied access before changing a credential or policy. Do not widen a source path or caller scope to clear a source credential failure. @@ -139,7 +139,7 @@ Do not widen a source path or caller scope to clear a source credential failure. Stable `pdp.*` codes identify Relay policy decisions such as `pdp.purpose_not_permitted`, `pdp.assurance_insufficient`, and `pdp.evidence_stale`; despite the shared word, `pdp.evidence_stale` is Relay's policy-decision-point code for stale source data -(`crates/registry-platform-pdp/src/lib.rs`) and is unrelated to the Evidence product. +(`crates/registry-platform-pdp/src/lib.rs`) and is unrelated to the Evidence Gateway product. Use the policy id, hash, checked rule ids, and other redacted audit evidence available to the authorized operator. Do not turn a policy denial into source unavailability or bypass the rule during diagnosis. @@ -152,11 +152,11 @@ The result carries no selected output map, and Relay must not choose a source re Reproduce the selector and cardinality with synthetic fixtures. Use `source.cardinality_violation` only when the source behavior violates the declared fixture or decoder contract. -Evidence applies the same discipline to a `POST /v1/evidence` request: an ambiguous match is one +Evidence Gateway applies the same discipline to a `POST /v1/evidence` request: an ambiguous match is one of the conditions the `evidence_not_available` problem collapses into a single value-free response, so timing and status code do not reveal which condition occurred (`products/evidence/OPERATOR-CONTRACT.md`, Source and selector controls; see the -[Evidence errors and problems reference](../../../reference/evidence-problems/)). +[Evidence Gateway errors and problems reference](../../../reference/evidence-problems/)). ### Stale materialization @@ -178,9 +178,9 @@ Relay's startup codes include: - `relay.startup.bundle_validation_rejected` - `relay.startup.bundle_rollback_rejected` -Evidence and Registry Mint have no equivalent stable startup-rejection codes: `evidence check` and +Evidence Gateway and Registry Mint have no equivalent stable startup-rejection codes: `evidence check` and `mint check` fail with a descriptive message instead, covered in -[Rotate Evidence signing keys](../../../tutorials/move-evidence-to-production-signing/#validate-and-coordinate-consumer-approval) +[Rotate Evidence Gateway signing keys](../../../tutorials/move-evidence-to-production-signing/#validate-and-coordinate-consumer-approval) and [Configure Registry Mint](../../../configure/mint/#troubleshooting). Correct the signer, binding, closed file set, product validation, or sequence. @@ -206,7 +206,7 @@ Retain: - Default redacted posture and restricted fields only in the protected operator record. - Stable public, operator, fixture, or authoring diagnostic codes. - Product, environment, stream, instance, and bundle sequence for Relay. -- Evidence's `operation` identifier from the problem response or `X-Request-Id` header, and the +- Evidence Gateway's `operation` identifier from the problem response or `X-Request-Id` header, and the output of `evidence verify-audit` when a signing or audit failure is suspected. - Registry Mint's operation identifier from its local log and the output of `mint verify-audit` when a token-decision audit failure is suspected. Do not retain the assertion or access token. @@ -233,7 +233,7 @@ After a higher sequence or new correctness-state write, use a reviewed higher-se path unless the release documents safe rollback. For ambiguity, fix or narrow the reviewed selector or source data. -Do not select a record manually inside Relay or Evidence. +Do not select a record manually inside Relay or Evidence Gateway. For stale materialization, follow the materialization recovery procedure without enabling live fallback. @@ -251,4 +251,4 @@ anti-rollback state or runtime schemas. - [Refresh and recover a materialization](../refresh-and-recover-materialization/) - [Recover, upgrade, migrate, and roll back](../recover-upgrade-migrate-and-rollback/) - [Review the error and status code reference](../../../reference/errors/) -- [Evidence errors and problems reference](../../../reference/evidence-problems/) +- [Evidence Gateway errors and problems reference](../../../reference/evidence-problems/) diff --git a/docs/site/src/content/docs/operate/advanced/rotate-credentials-and-trust.mdx b/docs/site/src/content/docs/operate/advanced/rotate-credentials-and-trust.mdx index 08e4cf654..9fa3c33c7 100644 --- a/docs/site/src/content/docs/operate/advanced/rotate-credentials-and-trust.mdx +++ b/docs/site/src/content/docs/operate/advanced/rotate-credentials-and-trust.mdx @@ -1,6 +1,6 @@ --- title: Rotate credentials, keys, certificates, and trust -description: Rotate Registry Relay, Evidence, and Registry Mint credentials, signing keys, and trust material without exposing secret material or widening authority. +description: Rotate Registry Relay, Evidence Gateway, and Registry Mint credentials, signing keys, and trust material without exposing secret material or widening authority. status: current owner: registry-docs source_repos: @@ -16,15 +16,15 @@ standards_referenced: [] --- Use this procedure to rotate a Relay source credential, Relay caller key, Relay certificate or -trust anchor, an Evidence signing key, or a Registry Mint signing key or client key, without +trust anchor, an Evidence Gateway signing key, or a Registry Mint signing key or client key, without exposing secret material and without widening authority. ## Prerequisites - Identify the material, every consumer, its current secret or trust reference, and its expiry. - Preserve a verified recovery set for the current Relay product configuration, and keep the - prior Evidence bundle revision and Registry Mint configuration file each rotation replaces. -- Keep caller traffic outside the staged Relay instance until its checks pass; restart Evidence + prior Evidence Gateway bundle revision and Registry Mint configuration file each rotation replaces. +- Keep caller traffic outside the staged Relay instance until its checks pass; restart Evidence Gateway and Registry Mint only after their own offline checks pass first. - Use synthetic or institution-approved canaries. Do not use personal data for a rotation probe. @@ -32,7 +32,7 @@ exposing secret material and without widening authority. Registry Relay owns source destinations, source credentials, private certification authority material, mutual TLS keys, source protocol credentials, and Relay caller keys. -Evidence owns its signing key, audit hash secret, and subject-binding secret, each resolved +Evidence Gateway owns its signing key, audit hash secret, and subject-binding secret, each resolved through its own owner-only secret root (`products/evidence/OPERATOR-CONTRACT.md`, Secrets and keys). Registry Mint owns its own signing key and its client registry: one public key and one granted @@ -43,8 +43,8 @@ admission, and revocation. Configuration signing keys and trust anchors are product-specific. Relay's two lanes, `relay-public` and `relay-consultation`, have separate signatures, anchors, anti-rollback state, and activation events, built and verified through `registryctl`. -Evidence and Registry Mint have no `registryctl`-governed bundle or trust-anchor system of their -own: Evidence validates its governed bundle and runtime file with `evidence check`, and Registry +Evidence Gateway and Registry Mint have no `registryctl`-governed bundle or trust-anchor system of their +own: Evidence Gateway validates its governed bundle and runtime file with `evidence check`, and Registry Mint validates its configuration with `mint check`, and neither participates in Relay's approved-set or anti-rollback lineage. @@ -65,13 +65,13 @@ approved-set or anti-rollback lineage. A secret-plane change retains the reviewed reference and replaces the value through the secret provider. For Relay, a governed change produces a reviewed product configuration and a new signed - product bundle through `registryctl`. For Evidence and Registry Mint, a governed change edits + product bundle through `registryctl`. For Evidence Gateway and Registry Mint, a governed change edits the bundle or configuration file directly, then runs `evidence check` or `mint check` before the next restart. The [Relay operations runbook](../../../products/registry-relay/ops/) defines Relay API-key and runtime-secret rotation. -[Evidence security model](../../../security/evidence/) traces Evidence's secret and signing-key +[Evidence Gateway security model](../../../security/evidence/) traces Evidence Gateway's secret and signing-key invariants to their tests, and `products/evidence/OPERATOR-CONTRACT.md` defines the incident boundary for a suspected key or audit-secret exposure. @@ -102,7 +102,7 @@ boundary for a suspected key or audit-secret exposure. window closes. Private CA and mutual TLS changes stay in Relay. -Do not copy source certificates, keys, or destinations into the Evidence bundle: Evidence sources +Do not copy source certificates, keys, or destinations into the Evidence Gateway bundle: Evidence Gateway sources declare their own `tlsTrustProfile` bound to a separate PEM file in `runtime.yaml` (`docs/site/src/content/docs/configure/evidence.mdx`), and mixing the two namespaces will not take effect where you expect. @@ -131,7 +131,7 @@ Remove the old registration only after every client has moved to the new key. Rotating Registry Mint's own signing key is a configuration change, not a client-registry reload: update `signing.activeKeyId` and `signing.activeKeyFile` in Registry Mint's configuration and restart the process. -Evidence does not need reconfiguring for this: it fetches Registry Mint's JWKS from the configured +Evidence Gateway does not need reconfiguring for this: it fetches Registry Mint's JWKS from the configured `jwksUri` on its own cache lifecycle and picks up the new key once Registry Mint restarts, provided both processes already agree on `issuer` and `accessTokens.claims` (`products/evidence/OPERATOR-CONTRACT.md`, Startup and readiness). @@ -238,13 +238,13 @@ provided both processes already agree on `issuer` and `accessTokens.claims` Repeat this workflow independently for each Relay lane when both signers change. Do not interpret two successful verifications as atomic project activation. -## Rotate Evidence and Registry Mint signing material +## Rotate Evidence Gateway and Registry Mint signing material -Evidence's signing key rotation is a rehearsed procedure, not new material for this page: +Evidence Gateway's signing key rotation is a rehearsed procedure, not new material for this page: generate the replacement Ed25519 key, reassemble the JWKS with the new public key and every retired public key still inside its validity window, update `signing.activeKeyId` in the reviewed bundle, then run `evidence check` and restart. -[Rotate Evidence signing keys](../../../tutorials/move-evidence-to-production-signing/#stage-a-new-keypair) +[Rotate Evidence Gateway signing keys](../../../tutorials/move-evidence-to-production-signing/#stage-a-new-keypair) walks through each step, and `products/evidence/OPERATOR-CONTRACT.md` (Secrets and keys) is the binding contract behind it. Missing or failed signing is fail-closed: a rotation mistake surfaces as refused requests, never @@ -263,13 +263,13 @@ Retain: - The redacted check and `review compare` reports for Relay. - The verified product bundle report and product-specific sequence for Relay. -- The `evidence check` output and the readiness result for a rotated Evidence signing key. +- The `evidence check` output and the readiness result for a rotated Evidence Gateway signing key. - The `mint check` output for a rotated Registry Mint signing key or client registration. - Health, readiness, audit-write, and redacted posture results from the staged instance. - A synthetic or authorized bounded canary result. - The old-material retirement time and the approved overlap window. -Evidence records may contain key ids, product ids, scopes, and certificate metadata. +Evidence Gateway records may contain key ids, product ids, scopes, and certificate metadata. They must not contain raw keys, fingerprints, private certificates, tokens, environment values, or full configuration dumps. @@ -281,7 +281,7 @@ environment does not widen the authored contract, and the generated product inpu file-closure checks for Relay. `evidence check` and `mint check` prove their own deployment's key material and configuration are internally consistent before a restart; neither proves the other product's trust lineage, because -Relay, Evidence, and Registry Mint share no signing or activation system. +Relay, Evidence Gateway, and Registry Mint share no signing or activation system. The generated product `preview-state` services prove that the later candidate can extend the existing accepted Relay lineage without persisting acceptance. The generated `accept-state` services commit the authenticated transition only after the locked @@ -301,11 +301,11 @@ Issue a reviewed higher-sequence recovery bundle. When the accepted lineage cannot be recovered, establish a new explicitly governed instance identity and state lineage instead of bypassing anti-rollback controls. -Keep old Evidence public verification keys published in the JWKS while assertions signed by those +Keep old Evidence Gateway public verification keys published in the JWKS while assertions signed by those keys can still be verified: at least the maximum assertion validity plus allowed clock skew (`products/evidence/OPERATOR-CONTRACT.md`, Secrets and keys). -Keep Registry Mint staged and Evidence's traffic blocked when Registry Mint's issuer, audience, or -claim names do not exactly match Evidence's configured authentication profile: a mismatch fails +Keep Registry Mint staged and Evidence Gateway's traffic blocked when Registry Mint's issuer, audience, or +claim names do not exactly match Evidence Gateway's configured authentication profile: a mismatch fails closed as `authentication_failed` rather than granting the wrong authority (`docs/site/src/content/docs/configure/mint.mdx`, Troubleshooting). @@ -313,7 +313,7 @@ closed as `authentication_failed` rather than granting the wrong authority Escalate to the product security owner when material may be exposed, a private key or token reaches logs, the available configuration signer keys fall below the current threshold, trust -cannot overlap safely, a certificate changes source identity, an old Evidence public key cannot +cannot overlap safely, a certificate changes source identity, an old Evidence Gateway public key cannot remain published for its required retention window, anti-rollback state is missing, or a canary requires live country data. @@ -322,5 +322,5 @@ requires live country data. - [Compare a baseline and reapprove a source change](../compare-and-reapprove-source-change/) - [Inspect and diagnose a running deployment](../inspect-and-diagnose/) - [Back up and restore state](../../backup-and-restore/) -- [Move Evidence to production signing](../../../tutorials/move-evidence-to-production-signing/) +- [Move Evidence Gateway to production signing](../../../tutorials/move-evidence-to-production-signing/) - [Configure Registry Mint](../../../configure/mint/) diff --git a/docs/site/src/content/docs/operate/approve-initial-baseline.mdx b/docs/site/src/content/docs/operate/approve-initial-baseline.mdx index 509d9d445..3d72924c3 100644 --- a/docs/site/src/content/docs/operate/approve-initial-baseline.mdx +++ b/docs/site/src/content/docs/operate/approve-initial-baseline.mdx @@ -27,13 +27,13 @@ The public Relay and consultation Relay lanes keep separate anchors, signing key and approval decisions. The approved-set owner assembles verified lane outputs but does not sign on behalf of a lane. -Evidence and Registry Mint +Evidence Gateway and Registry Mint are not registryctl-generated products and do not participate in this trust-anchor and approved-set pipeline at all: each validates its own deployment inputs directly, with `evidence check` and `mint check`. The current `evidencectl new` command starts an incomplete -OpenAPI authoring workspace; it does not create Evidence deployment inputs. For a complete -Evidence project, `evidencectl fixtures run` drives the offline fixture checks. See -[Configure Evidence](../../configure/evidence/) and [Configure Registry Mint](../../configure/mint/) +OpenAPI authoring workspace; it does not create Evidence Gateway deployment inputs. For a complete +Evidence Gateway project, `evidencectl fixtures run` drives the offline fixture checks. See +[Configure Evidence Gateway](../../configure/evidence/) and [Configure Registry Mint](../../configure/mint/) for those procedures. ## Before you start diff --git a/docs/site/src/content/docs/operate/evidence-audit.mdx b/docs/site/src/content/docs/operate/evidence-audit.mdx index 225b238c8..bd906de46 100644 --- a/docs/site/src/content/docs/operate/evidence-audit.mdx +++ b/docs/site/src/content/docs/operate/evidence-audit.mdx @@ -1,6 +1,6 @@ --- -title: Verify and interpret the Evidence audit chain -description: Prove the integrity of retained Evidence audit history, understand what each phase establishes, and keep the subject-correlation boundary explicit. +title: Verify and interpret the Evidence Gateway audit chain +description: Prove the integrity of retained Evidence Gateway audit history, understand what each phase establishes, and keep the subject-correlation boundary explicit. status: current owner: registry-docs source_repos: @@ -13,7 +13,7 @@ locale: en standards_referenced: [] --- -Evidence writes a keyed, append-only audit chain. The chain is useful for proving which governed +Evidence Gateway writes a keyed, append-only audit chain. The chain is useful for proving which governed operation was admitted, what concept was released, and whether retained records were modified. It does not repeat source values or automatically provide a citizen-facing access history. @@ -40,7 +40,7 @@ The runtime file supplies the audit directory and hash-key reference. The comman on the command line, which prevents an operator from accidentally verifying a different chain or key than the deployment uses. -If Evidence is still running, the writer keeps the active segment locked. Verification proves the +If Evidence Gateway is still running, the writer keeps the active segment locked. Verification proves the sealed history and reports: ```text @@ -62,7 +62,7 @@ For an admitted request, the native chain uses closed phases: | `disclosure-release` with `released` | The named concepts were serialized and durably recorded before the exact response bytes were released. | The source fact was true or the caller used the answer correctly. | | `denial` or `transient-failure` | An admitted operation later failed in one closed, value-free class. | The protected selector, source value, or credential that triggered it. | -Failures that happen before Evidence has enough privacy-safe context, such as authentication +Failures that happen before Evidence Gateway has enough privacy-safe context, such as authentication failure or an invalid selector, do not fabricate a native subject event. Do not expect every HTTP request to produce two audit records. @@ -113,13 +113,13 @@ governed operator process. ## Protect the chain -- Allow one Evidence writer per audit path. +- Allow one Evidence Gateway writer per audit path. - Put the path on durable storage and monitor capacity before a fail-closed write stops release. - Back up every sealed segment and the active segment as one history. - Retain the matching audit hash key for as long as the history must remain verifiable. - Restrict event access separately from ordinary service operations. - Record retention, deletion, recovery, and requester-identity mapping responsibilities outside the - Evidence bundle. + Evidence Gateway bundle. Continue with [Retention and persistent state](../retention-and-persistent-state/) and [Backup and restore](../backup-and-restore/) for the surrounding operator procedures. diff --git a/docs/site/src/content/docs/operate/retention-and-persistent-state.mdx b/docs/site/src/content/docs/operate/retention-and-persistent-state.mdx index 64f726a07..b01643695 100644 --- a/docs/site/src/content/docs/operate/retention-and-persistent-state.mdx +++ b/docs/site/src/content/docs/operate/retention-and-persistent-state.mdx @@ -1,6 +1,6 @@ --- title: Retention and persistent state -description: What Registry Relay, Evidence, and Registry Mint retain, what expires, and what operators must preserve or ship off host. +description: What Registry Relay, Evidence Gateway, and Registry Mint retain, what expires, and what operators must preserve or ship off host. status: draft owner: registry-docs source_repos: @@ -15,7 +15,7 @@ standards_referenced: [] Use this page to decide which Registry Stack state needs backup, off-host shipping, expiry, or deletion policy outside the products. -It documents current Registry Relay, Evidence, and Registry Mint behavior. +It documents current Registry Relay, Evidence Gateway, and Registry Mint behavior. Retention enforcement, record-level erasure, and data-subject-rights workflows are outside the 1.0 product boundary. @@ -40,20 +40,20 @@ Two consequences follow from that boundary: | Store | What it can contain | Expiry or rotation | Operator control | |---|---|---|---| | Relay audit sink | Chained audit envelopes with timestamps, event bodies, hashes, and HMAC-pseudonymized sensitive handles when configured. Operational metadata can still identify actors or actions. | The file sink defaults to `100 MB` and `14` retained files. `stdout` and `syslog` retention belongs to the collector. | Configure `audit.sink`, file path, rotation, `audit.hash_secret_env`, and off-host shipping. | -| Evidence audit chain | A keyed, hash-chained JSONL log of the access-attempt event before every source read and the disclosure-release event before every response. Audit carries reviewed identifiers and decision categories, never raw selector values, source values, credentials, tokens, or raw subject identifiers. | `auditStorage.maximumFileBytes` is a per-segment rotation threshold, not a total ceiling. When an append would exceed it, the runtime seals the active segment as `.` and opens a new active segment online, with no operator action. Nothing in the runtime deletes or compacts a sealed segment; total retention is entirely operator-owned. | Set `auditStorage.path`, `auditStorage.maximumFileBytes`, and the hash secret in `runtime.yaml`. Archive sealed segments to cold storage oldest sequence first, never touch the active segment while the service runs, and run `evidence verify-audit` on the cadence the deployment's audit policy requires. | +| Evidence Gateway audit chain | A keyed, hash-chained JSONL log of the access-attempt event before every source read and the disclosure-release event before every response. Audit carries reviewed identifiers and decision categories, never raw selector values, source values, credentials, tokens, or raw subject identifiers. | `auditStorage.maximumFileBytes` is a per-segment rotation threshold, not a total ceiling. When an append would exceed it, the runtime seals the active segment as `.` and opens a new active segment online, with no operator action. Nothing in the runtime deletes or compacts a sealed segment; total retention is entirely operator-owned. | Set `auditStorage.path`, `auditStorage.maximumFileBytes`, and the hash secret in `runtime.yaml`. Archive sealed segments to cold storage oldest sequence first, never touch the active segment while the service runs, and run `evidence verify-audit` on the cadence the deployment's audit policy requires. | | Mint audit chain | A keyed, hash-chained JSONL log of token releases and denials. Records use keyed pseudonyms and omit raw assertions, access tokens, client ids, principals, authority values, actors, and subject values. | `audit.maximumFileBytes` is a per-segment threshold, not a total ceiling. Registry Mint seals full segments as `.` online and never deletes or compacts them. | Set `audit.path`, `audit.maximumFileBytes`, and the hash key in `mint.yaml`. Archive sealed segments oldest first, never touch the active segment while Registry Mint runs, and run `mint verify-audit` on the deployment's verification cadence. | | Relay audit shipper cursor | Local `registry.audit.ack_cursor.v1` state with the acknowledgement time and last acknowledged chain hash, plus an optional shipper identifier. | The shipper atomically replaces the file after each successful hand-off. Relay does not expire or rewrite it. | Mount the file read-only for the Relay process, keep it on local storage and at or below 16 KiB, and configure `deployment.evidence.audit_ack_cursor_path`. | | Relay ingest cache | Normalized Parquet snapshots under `server.cache_dir`. These snapshots can contain full source rows from configured registries. | No time TTL. For audited SnapshotExact, the authored `retain_generations` value keeps between `1` and `16` completed cache generations, including the active generation, after successful publication. Ordinary sources keep the built-in current and previous generations. Older snapshots are removed best effort. | Place `server.cache_dir` on writable storage with the same data classification as the source rows. Treat authored retention as a bounded recovery set, not an API for selecting arbitrary rollback targets. | | Config-trust anti-rollback state | The last accepted sequence, config and bundle hashes, root version, and optional break-glass pin metadata. Operator names, approval references, and reasons can be sensitive. | The state file is rewritten atomically and has no normal TTL. Break-glass overrides require expiry, and consumed override files are renamed. | Preserve `antirollback_state_path` across upgrades and protect break-glass override files with local root controls. | | Relay consultation correctness state | Durable consultation audit, attempts and completions, dispatch permits, quota buckets, materialization publication history, batch-child replay bindings, serving-fence state, and audit-pseudonym keyring metadata. Pseudonymous handles and operational metadata can remain linkable. | Batch-child replay rows expire after `15 minutes` and are pruned on later reservations. Other Relay consultation tables have no general time-based pruning. Keyring retention controls when retired pseudonym key metadata can leave the retained set; it does not delete durable audit rows. | Back up the complete Relay database at a quiesced or coordinated recovery point. Preserve role bindings and key material, and keep any potentially stale restore offline until acknowledged writes are reconciled. | -| Operator-owned config, source, and secret paths | Runtime configuration, signed Relay bundles and trust anchors, Evidence's governed bundle and runtime document, Registry Mint's signing key and client registry, metadata manifests, source files, and secret references. Source files can contain personal data. | Registry Stack does not expire these files, except through the specific audit, cache, replay, and break-glass mechanics above. | Mount source data read-only where possible; back up config, trust anchors, anti-rollback state, and secrets through your platform controls. | +| Operator-owned config, source, and secret paths | Runtime configuration, signed Relay bundles and trust anchors, Evidence Gateway's governed bundle and runtime document, Registry Mint's signing key and client registry, metadata manifests, source files, and secret references. Source files can contain personal data. | Registry Stack does not expire these files, except through the specific audit, cache, replay, and break-glass mechanics above. | Mount source data read-only where possible; back up config, trust anchors, anti-rollback state, and secrets through your platform controls. | ## Process-local caches and client-held state | Store | What it can contain | Expiry or rotation | Operator control | |---|---|---|---| | Relay OIDC JWKS cache | Issuer signing keys and negative lookup entries, not subject records. | In process only. Default positive cache TTL is `600` seconds and default negative cache TTL is `60` seconds. | Configure Relay OIDC `jwks_cache_ttl` where exposed. Restart clears the cache. | -| Evidence OIDC JWKS cache | Issuer signing keys and negative lookup entries for the configured `authentication.jwksUri`, not subject records. | In process only. Evidence exposes no product-level override, so the shared platform defaults apply: `600` second positive cache TTL and `60` second negative cache TTL. | Restart clears the cache. An unreachable key set is retried and reported at a bounded interval rather than silently ignored. | +| Evidence Gateway OIDC JWKS cache | Issuer signing keys and negative lookup entries for the configured `authentication.jwksUri`, not subject records. | In process only. Evidence Gateway exposes no product-level override, so the shared platform defaults apply: `600` second positive cache TTL and `60` second negative cache TTL. | Restart clears the cache. An unreachable key set is retried and reported at a bounded interval rather than silently ignored. | | Relay auth-failure throttle | Process-local counters keyed by resolved client address. Client IP addresses can be personal data. | Fixed window when enabled; defaults are disabled, `20` failures, and `60` seconds. Restart clears counters. | Configure `auth.failure_throttle.*` and `server.trust_proxy` correctly behind proxies. | | Relay response headers | No Relay-owned response/result cache was found. Client and proxy caching follow HTTP headers. | Metadata and default release responses are `no-store`; successful release responses can opt into private max-age. | Configure release-profile response max age only when private client caching is acceptable. | | Relay pagination cursors | Client-held signed cursor payloads can include query context, filters, principal ID, ingest version, and position. | Not stored server-side and no product TTL. Cursors become invalid when signer, principal, query, config, or ingest version changes. | Treat cursor tokens as client-held request context and avoid logging them unnecessarily. | @@ -91,13 +91,13 @@ Never truncate, rewrite, or reserialize audit files as part of cleanup. Back them up as files, keep old hash secrets for the audit retention period, and rotate hash secrets only as an intentional key-lifecycle event. -## Evidence and Registry Mint retention +## Evidence Gateway and Registry Mint retention -Evidence has no application database and persists no selector, source, evidence, or response +Evidence Gateway has no application database and persists no selector, source, evidence, or response data. Its only durable state is the operator-configured signing key material and the audit chain described in [Durable state and externally retained records](#durable-state-and-externally-retained-records). -An external durable audit service may own its own storage, but Evidence itself does not maintain +An external durable audit service may own its own storage, but Evidence Gateway itself does not maintain one. Run `evidence verify-audit` against the runtime document's configured audit path to check chain diff --git a/docs/site/src/content/docs/operate/single-node-compose-behind-proxy.mdx b/docs/site/src/content/docs/operate/single-node-compose-behind-proxy.mdx index c7c8538b2..50f51b1e5 100644 --- a/docs/site/src/content/docs/operate/single-node-compose-behind-proxy.mdx +++ b/docs/site/src/content/docs/operate/single-node-compose-behind-proxy.mdx @@ -1,6 +1,6 @@ --- title: Run the generated single-node Compose package -description: Generate, verify, initialize, and run the governed Relay package, then include Evidence and Registry Mint under explicit operator ownership when needed. +description: Generate, verify, initialize, and run the governed Relay package, then include Evidence Gateway and Registry Mint under explicit operator ownership when needed. status: current owner: registry-docs source_repos: @@ -15,7 +15,7 @@ standards_referenced: [] --- Use this guide to hand independently approved Registry Relay bundles to a single-node Docker -Compose deployment, then include Evidence and Registry Mint in that same application under +Compose deployment, then include Evidence Gateway and Registry Mint in that same application under explicit operator ownership when the deployment needs them. The generated package remains portable after handoff and can run with Docker Compose without Registryctl. @@ -29,9 +29,9 @@ Use the generated package when: - Docker Compose 2.35.0 or later is available - Each Relay lane has an independently signed bundle and trust anchor -Registryctl generates a package for the Relay lanes only. Evidence and Registry Mint are not +Registryctl generates a package for the Relay lanes only. Evidence Gateway and Registry Mint are not registryctl-generated products: an operator adds them as ordinary services in the same -application, following [Add Evidence and Registry Mint to the application](#add-evidence-and-registry-mint-to-the-application). +application, following [Add Evidence Gateway and Registry Mint to the application](#add-evidence-gateway-and-registry-mint-to-the-application). The package does not provide high availability, Kubernetes, an external database, or direct non-loopback host publishing. @@ -46,7 +46,7 @@ You need: - The released Registryctl installation whose signed release lock authorizes the images - Operator-owned environment, signing, workload-credential, and PostgreSQL TLS files - Durable storage for PostgreSQL and each product's anti-rollback state -- An operator-owned `runtime.yaml` (and referenced secret files) for each Evidence deployment the +- An operator-owned `runtime.yaml` (and referenced secret files) for each Evidence Gateway deployment the application will include, and an operator-owned `mint.yaml` for Registry Mint when the deployment has no identity provider @@ -263,31 +263,31 @@ Security (TLS), hostnames, edge request admission, network access, and compatibi generated package. The package verification result does not extend to the application model. -## Add Evidence and Registry Mint to the application +## Add Evidence Gateway and Registry Mint to the application -Evidence and Registry Mint are not lanes Registryctl generates, verifies, or initializes. An +Evidence Gateway and Registry Mint are not lanes Registryctl generates, verifies, or initializes. An operator runs each as an ordinary service in the same application `compose.yaml` that includes the generated Relay package, alongside it rather than inside it. Each service needs its own operator-owned, startup-only configuration document mounted read-only: -a `runtime.yaml` for every Evidence deployment (naming its immutable bundle directory, listener, +a `runtime.yaml` for every Evidence Gateway deployment (naming its immutable bundle directory, listener, secret root, and audit path) and, when the deployment has no identity provider to issue access tokens, a `mint.yaml` for Registry Mint (naming its signing key and client registry directory). -[Configure Evidence](../../configure/evidence/) and +[Configure Evidence Gateway](../../configure/evidence/) and [Configure Registry Mint](../../configure/mint/) cover both documents field by field. -For an approved Evidence candidate, use -[Integrate an Evidence candidate with Docker Compose](../../tutorials/integrate-evidence-candidate-with-docker-compose/). +For an approved Evidence Gateway candidate, use +[Integrate an Evidence Gateway candidate with Docker Compose](../../tutorials/integrate-evidence-candidate-with-docker-compose/). That guide keeps the candidate bundle, container runtime, secret root, and audit storage separate. -Every listener either binary opens, including Evidence's optional `metricsListener`, must bind to +Every listener either binary opens, including Evidence Gateway's optional `metricsListener`, must bind to a loopback, RFC 1918 private IPv4, or RFC 4193 unique-local address; a wildcard or public bind is refused at startup. Binding to the container's own loopback address makes a service reachable only from inside that same container, so a reverse proxy or gateway container that needs to reach -Evidence or Registry Mint over the Compose network binds them to a private address on that network +Evidence Gateway or Registry Mint over the Compose network binds them to a private address on that network instead, never to `0.0.0.0`. TLS termination stays an operator concern here exactly as it does for -the generated Relay package: Evidence's `listener.tlsTermination` is fixed to +the generated Relay package: Evidence Gateway's `listener.tlsTermination` is fixed to `operator-controlled-upstream`, so the same reverse proxy that terminates TLS for Relay can sit in -front of Evidence and Registry Mint. +front of Evidence Gateway and Registry Mint. Validate each configuration before opening a socket, then start the service: @@ -300,10 +300,9 @@ mint serve --config /etc/mint/mint.yaml Use `GET /health` and `GET /ready` on each service's own listener for a Compose health check, the same way the generated Relay package uses `up --wait` for its own health conditions. -[First run with Solmara Lab](../../tutorials/first-run-with-solmara-lab/) walks through Registry -Mint, Relay, and Evidence composed behind one TLS-terminating gateway end to end; that tutorial is -a lab environment, not a production posture, but the shape of the composition, one gateway in -front of independently configured services with no host port of their own, carries over. +Registry Relay, Evidence Gateway, and Registry Mint can share an operator-managed TLS termination +layer, but they remain independently configured services. Sharing ingress does not create a source +or authorization path between Relay and Evidence Gateway. ## Customize the generated package @@ -338,4 +337,4 @@ invalid, not an adaptation. | Verification reports `invalid` | A hard product, secret, state, network, or privilege invariant failed. | Restore the generated boundary. Do not downgrade the failure to an override. | | Ordinary startup reports missing state | The one-time initialization was not completed or durable state was lost. | Complete first installation, or restore the exact recovery consistency group. Do not reinitialize an existing identity. | | An including application cannot reach a public service | The operator-owned include graph or network wiring is incomplete. | Correct the application model and rerun the application's Compose validation. | -| Evidence or Registry Mint refuses to start with a listener bind error | `listener.bindHost` (or `metricsListener.bindHost`) is a wildcard, public, or unspecified address. | Bind to loopback for same-container access, or to a private address on the Compose network for the proxy to reach. | +| Evidence Gateway or Registry Mint refuses to start with a listener bind error | `listener.bindHost` (or `metricsListener.bindHost`) is a wildcard, public, or unspecified address. | Bind to loopback for same-container access, or to a private address on the Compose network for the proxy to reach. | diff --git a/docs/site/src/content/docs/reference/api-stability.mdx b/docs/site/src/content/docs/reference/api-stability.mdx index e2224023d..e4b17a1ff 100644 --- a/docs/site/src/content/docs/reference/api-stability.mdx +++ b/docs/site/src/content/docs/reference/api-stability.mdx @@ -45,9 +45,9 @@ The enforcement column names the repository CI checks so the mechanism is audita | Surface | Contract artifact | Enforcement today | | --- | --- | --- | | Registry Relay HTTP API (approved stable public and admin listener surface) | Committed OpenAPI document `crates/registry-relay/openapi/registry-relay.openapi.json`, scoped by the [authoritative 1.0 support roster](../apis/registry-relay/) | `just openapi-contract` checks byte-for-byte generation, filters only roster entries declared `included_unstable`, then runs `oasdiff breaking` against the base ref | -| Evidence HTTP API and its Version 1 contracts | The frozen Version 1 source contracts under `products/evidence/contracts/`, indexed by `products/evidence/contracts/README.md`, and the artifacts generated from them under `products/evidence/generated/`, including `registry-evidence.openapi.json` | Root CI's `evidence-contracts` job runs `products/evidence/scripts/check-contracts.sh`, which regenerates every contract artifact and fails on any byte difference from the committed copies, and `products/evidence/scripts/check-source-neutrality.sh` | -| Error contract and stable identifiers | RFC 9457 problem shape with the stable `code` member, the [error registry](../errors/), the `pdp.*` denial codes, and the `https://id.registrystack.org/` identifier space. Evidence's closed problem set has its own frozen contract, `products/evidence/contracts/problem-contract.yaml`, documented at [Evidence problem types](../evidence-problems/) | `release/scripts/check-stable-surface-compatibility.py` permits additions and rejects removal or changed meaning; product tests pin runtime rendering and status mappings; the `evidence-contracts` job byte-diffs the generated Evidence problem schema | -| Configuration formats and documented environment variables | The committed Draft 2020-12 schema `schemas/registry-relay.config.schema.json`, the frozen Evidence schemas `products/evidence/contracts/runtime.schema.yaml` and `products/evidence/contracts/bundle.schema.yaml`, plus the [environment variable reference](../environment-variables/) | Relay's `config-schema-check` command reproduces its schema from the typed config graph; Evidence's config parser is tested against the frozen contract schemas (`crates/registry-evidence/src/config.rs`); strict parsers and the deprecated-field guard reject unknown or retired fields | +| Evidence Gateway HTTP API and its Version 1 contracts | The frozen Version 1 source contracts under `products/evidence/contracts/`, indexed by `products/evidence/contracts/README.md`, and the artifacts generated from them under `products/evidence/generated/`, including `registry-evidence.openapi.json` | Root CI's `evidence-contracts` job runs `products/evidence/scripts/check-contracts.sh`, which regenerates every contract artifact and fails on any byte difference from the committed copies, and `products/evidence/scripts/check-source-neutrality.sh` | +| Error contract and stable identifiers | RFC 9457 problem shape with the stable `code` member, the [error registry](../errors/), the `pdp.*` denial codes, and the `https://id.registrystack.org/` identifier space. Evidence Gateway's closed problem set has its own frozen contract, `products/evidence/contracts/problem-contract.yaml`, documented at [Evidence Gateway problem types](../evidence-problems/) | `release/scripts/check-stable-surface-compatibility.py` permits additions and rejects removal or changed meaning; product tests pin runtime rendering and status mappings; the `evidence-contracts` job byte-diffs the generated Evidence Gateway problem schema | +| Configuration formats and documented environment variables | The committed Draft 2020-12 schema `schemas/registry-relay.config.schema.json`, the frozen Evidence Gateway schemas `products/evidence/contracts/runtime.schema.yaml` and `products/evidence/contracts/bundle.schema.yaml`, plus the [environment variable reference](../environment-variables/) | Relay's `config-schema-check` command reproduces its schema from the typed config graph; Evidence Gateway's config parser is tested against the frozen contract schemas (`crates/registry-evidence/src/config.rs`); strict parsers and the deprecated-field guard reject unknown or retired fields | | Signed config bundle format and verification semantics | `registry.platform.config_bundle.v1` manifests, `registry.platform.config_bundle_signatures.v1` signature envelopes, and `registry.platform.config_trust_anchor.v1` trust anchors. Normal signed verification requires a valid, non-empty trust anchor and checks signature acceptance, file closure, product/environment/stream binding, optional instance pinning, and anti-rollback sequence. The hash-pinned `registry.platform.config_break_glass.v1` `accept_rollback` mode keeps signature, binding, closure, hash, and product checks but waives the monotonic sequence rejection for a signed bundle whose config hash matches the override. Its `accept_unsigned` mode skips signature, binding, and sequence checks while retaining exact hash pinning and product config validation. | Shared verifier tests in `registry-platform-config`; break-glass consumption, restart-pin, and sequence tests in `registry-platform-ops`; product CLI coverage in `crates/registry-relay/tests/config_verify_bundle_cli.rs` | | Registry Manifest schema and rendered artifacts | `registry-manifest/v1` and the rendered artifact schema versions, governed by [RS-DM-MANIFEST](../../spec/rs-dm-manifest/) | `validate_manifest` accepts only `registry-manifest/v1`; REQ-DM-MANIFEST-013 requires strict unknown-key rejection at parse time | | Source-adaptation integration surfaces | Registry Relay's compiled `http`, `script`, and `snapshot` consultation plans, including the Rhai `consult(ctx)` host API and versioned protocol helpers | Registry Stack project-authoring schemas and fixtures; Relay source-plan compiler and consultation contract tests | @@ -116,11 +116,11 @@ Every release documents a forward state path from its immediate predecessor. An upgrade that skips releases follows each sequential hop unless the target release explicitly certifies a direct path. -The reverse is not promised. Registry Relay, Evidence, and Registry Mint all parse config with +The reverse is not promised. Registry Relay, Evidence Gateway, and Registry Mint all parse config with `deny_unknown_fields`, so a config file that uses keys introduced in a newer release fails to load on an older binary. Pin your config to the release you deploy. -Evidence and Registry Mint have no migrated state to upgrade. Evidence persists the append-only +Evidence Gateway and Registry Mint have no migrated state to upgrade. Evidence Gateway persists the append-only audit log named by `auditStorage` in its runtime file. Registry Mint persists its client registry and the keyed append-only chain named by `audit.path`, while its client-assertion replay cache remains in memory. A newer binary must be checked against these retained audit formats before @@ -145,7 +145,7 @@ The following are not covered by the compatibility promise, at any version: is not a covered surface. - Adopter tooling that wraps a covered surface rather than defining one, including `evidencectl`, which generates key material and project scaffolds and shells out to the `evidence` binary for - every Evidence semantic decision. + every Evidence Gateway semantic decision. - The layout of the repository, the `products/` export trees, the docs site internals, and the lab tooling. - Descriptions, summaries, and ordering inside generated OpenAPI documents. The contract is @@ -158,10 +158,10 @@ The HTTP surface carries several independent version prefixes: `/v1` (data plane (Relay standards adapters). Each namespace versions independently; a `/v2` in one namespace does not imply a `/v2` in another. -Evidence's two versioned routes, `POST /v1/evidence` and `GET /v1/evidence-definitions`, are the +Evidence Gateway's two versioned routes, `POST /v1/evidence` and `GET /v1/evidence-definitions`, are the whole of its evidence surface under the frozen Version 1 contract. Its remaining routes are operational or discovery routes and are unversioned by convention: `/health`, `/ready`, -`/openapi.json`, `/.well-known/evidence/jwks.json`, and `/.well-known/jwt-vc-issuer`. Evidence +`/openapi.json`, `/.well-known/evidence/jwks.json`, and `/.well-known/jwt-vc-issuer`. Evidence Gateway serves `/metrics` on a separate listener when one is configured, never on the request listener. Registry Mint's routes are unversioned by protocol convention rather than by promise: the fixed, @@ -178,7 +178,7 @@ The promise is machine-checked where a checker exists: document from the reference config, requires a byte-for-byte match with the committed file, removes only the aggregate representations marked `included_unstable` by the authoritative Relay roster, and runs `oasdiff breaking` against the base ref. -- Evidence: root CI's `evidence-contracts` job regenerates every contract artifact from the code +- Evidence Gateway: root CI's `evidence-contracts` job regenerates every contract artifact from the code with `products/evidence/scripts/check-contracts.sh` and fails on any byte difference from the committed copies, so the OpenAPI document, the problem schema, and the request and response schemas cannot drift from a released binary. @@ -186,7 +186,7 @@ The promise is machine-checked where a checker exists: released registry and selected metric contract against the base reference while permitting additions. - Config: Registry Relay reproduces its committed schema from its typed config graph, and - Evidence's config parser is tested against the frozen contract schemas rather than a schema + Evidence Gateway's config parser is tested against the frozen contract schemas rather than a schema generated from it; `registry-platform-config` rejects removed or renamed keys with a pointer to the migration note instead of silently ignoring them. diff --git a/docs/site/src/content/docs/reference/apis/index.mdx b/docs/site/src/content/docs/reference/apis/index.mdx index f81d1fc63..d6619cd05 100644 --- a/docs/site/src/content/docs/reference/apis/index.mdx +++ b/docs/site/src/content/docs/reference/apis/index.mdx @@ -1,6 +1,6 @@ --- title: API references -description: Generated API reference pages for Registry Relay and Evidence, built from pinned OpenAPI artifacts. +description: Generated API reference pages for Registry Relay and Evidence Gateway, built from pinned OpenAPI artifacts. wide: true status: current owner: registry-docs @@ -16,7 +16,7 @@ standards_referenced: import OpenApiSourcesTable from '../../../../components/OpenApiSourcesTable.astro'; -Use this section to browse the HTTP API for Registry Relay or Evidence. Each +Use this section to browse the HTTP API for Registry Relay or Evidence Gateway. Each page is built from a pinned OpenAPI artifact owned by the project it describes. {/* Do not duplicate endpoint reference content in narrative pages. */} @@ -32,7 +32,7 @@ The table is generated from `src/data/openapi-sources.yaml`. - [Registry Relay API](./registry-relay/) documents the Protected Registry Data API, metadata API, evidence offering discovery, health and readiness endpoints, and optional standards adapters. -- [Registry Evidence API](./registry-evidence/) documents the assertion, requester-scoped +- [Evidence Gateway API](./registry-evidence/) documents the assertion, requester-scoped definition discovery, health, readiness, served-contract, and key discovery endpoints. ## Provenance and freshness @@ -45,8 +45,8 @@ The contract lives in `registry-relay/openapi/registry-relay.openapi.json`. Feature-gated surfaces (OGC API Features, OGC API Records, OGC API EDR, and SP DCI) are included with notes in each tag description explaining the build feature that mounts them. For the instance-specific shape of `{dataset_id}` and `{entity}` in a given deployment, fetch `GET /openapi.json` from that gateway. Runtime deployments gate that route by default unless `openapi_requires_auth` is disabled for demos or controlled tooling. -[Evidence](../../products/registry-evidence/) generates its OpenAPI document with the other -Evidence contract artifacts: +[Evidence Gateway](../../products/registry-evidence/) generates its OpenAPI document with the other +Evidence Gateway contract artifacts: ```sh cargo run -p registry-evidence --example evidence-contracts -- --output "" @@ -54,5 +54,5 @@ cargo run -p registry-evidence --example evidence-contracts -- --output "`, enforced by `SecretRef::parse` in `crates/registry-evidence/src/config.rs`, and resolves to an owner-only regular file under the `secretProviders.file.root` directory named in `runtime.yaml` (`crates/registry-evidence/src/secrets.rs`). Neither the runtime file nor the governed bundle can name an environment variable to read a credential from. See [Configure Evidence](../../configure/evidence/) for the runtime file and the bundle it binds. +Evidence Gateway reads no secret from an environment variable. A configured secret reference uses one grammar, `secret:file/`, enforced by `SecretRef::parse` in `crates/registry-evidence/src/config.rs`, and resolves to an owner-only regular file under the `secretProviders.file.root` directory named in `runtime.yaml` (`crates/registry-evidence/src/secrets.rs`). Neither the runtime file nor the governed bundle can name an environment variable to read a credential from. See [Configure Evidence Gateway](../../configure/evidence/) for the runtime file and the bundle it binds. ## Registry Mint @@ -91,4 +91,4 @@ any effect. Setting them is harmless and does nothing. ## Source -The fixed variable names above are transcribed from the binaries and the registryctl source, at the paths given here. For the canonical definitions, read the Evidence binary entry point `crates/registry-evidence/src/main.rs` (the `Cli` struct and `install_operational_logging`), the Registry Mint binary entry point `crates/registry-mint/src/main.rs` (the `Command` enum and `main`), the Registry Relay binary entry point `crates/registry-relay/src/main.rs` (`default_config_path_from_env`, `default_env_file_from_env`, `default_bind_from_env`, `OperationalLogFormat::from_env`, and `init_tracing`), the Relay Postgres connector at `crates/registry-relay/src/connector/mod.rs`, and for registryctl `crates/registryctl/src/main.rs` (`resolve_environment`) together with `crates/registryctl/install.sh`. The operator-named secret variables are documented in the [Registry Relay configuration reference](../../products/registry-relay/configuration/). +The fixed variable names above are transcribed from the binaries and the registryctl source, at the paths given here. For the canonical definitions, read the Evidence Gateway binary entry point `crates/registry-evidence/src/main.rs` (the `Cli` struct and `install_operational_logging`), the Registry Mint binary entry point `crates/registry-mint/src/main.rs` (the `Command` enum and `main`), the Registry Relay binary entry point `crates/registry-relay/src/main.rs` (`default_config_path_from_env`, `default_env_file_from_env`, `default_bind_from_env`, `OperationalLogFormat::from_env`, and `init_tracing`), the Relay Postgres connector at `crates/registry-relay/src/connector/mod.rs`, and for registryctl `crates/registryctl/src/main.rs` (`resolve_environment`) together with `crates/registryctl/install.sh`. The operator-named secret variables are documented in the [Registry Relay configuration reference](../../products/registry-relay/configuration/). diff --git a/docs/site/src/content/docs/reference/errors.mdx b/docs/site/src/content/docs/reference/errors.mdx index 3de944da4..5085abfd7 100644 --- a/docs/site/src/content/docs/reference/errors.mdx +++ b/docs/site/src/content/docs/reference/errors.mdx @@ -1,6 +1,6 @@ --- title: Error and status code reference -description: RFC 9457 problem codes returned by Registry Relay, with their meaning and usual cause, and where the Evidence and Registry Mint error contracts are documented. +description: RFC 9457 problem codes returned by Registry Relay, with their meaning and usual cause, and where the Evidence Gateway and Registry Mint error contracts are documented. status: current owner: registry-docs source_repos: @@ -28,22 +28,22 @@ use `code` for the stack-wide meaning. The additive compatibility gate uses this reference as the error-code registry and the committed OpenAPI documents for operation mappings they enumerate. -## Evidence +## Evidence Gateway -Evidence has its own closed problem set, documented at -[Evidence problem types](../evidence-problems/). That page is the single place the set is written +Evidence Gateway has its own closed problem set, documented at +[Evidence Gateway problem types](../evidence-problems/). That page is the single place the set is written down, because the set is frozen in `products/evidence/contracts/problem-contract.yaml` and CI byte-diffs the generated schema against it; a second copy of the table here would drift without a gate to catch it. -Two structural differences are worth knowing before reading the Evidence page. Evidence problem +Two structural differences are worth knowing before reading the Evidence Gateway page. Evidence Gateway problem type URIs are `https://registrystack.org/problems/evidence/` rather than the -`https://id.registrystack.org/problems/...` form used elsewhere in the stack. And an Evidence +`https://id.registrystack.org/problems/...` form used elsewhere in the stack. And an Evidence Gateway problem body carries exactly five members (`type`, `title`, `status`, `code`, and `operation`, the request's ULID), with no `detail` member and no other extension, so the failure never carries subject data or source diagnostics back to the caller. -Evidence answers with one of that closed set for every failure, including transport-level ones: a +Evidence Gateway answers with one of that closed set for every failure, including transport-level ones: a request body over the configured limit is refused as `malformed_request` rather than with a shared-middleware problem type (`crates/registry-evidence/src/server.rs`). @@ -277,6 +277,6 @@ The startup-only runtime binding codes are raised by `crates/registry-relay/src/ The codes this page points at rather than repeating are transcribed on their own pages from `crates/registry-evidence/src/problem.rs` with `products/evidence/contracts/problem-contract.yaml` -(Evidence) and `crates/registry-mint/src/error.rs` (Registry Mint). +(Evidence Gateway) and `crates/registry-mint/src/error.rs` (Registry Mint). The release compatibility gate compares this registry to its base reference and verifies that every listed code remains anchored in Rust or OpenAPI source. diff --git a/docs/site/src/content/docs/reference/evidence-problems.mdx b/docs/site/src/content/docs/reference/evidence-problems.mdx index 3dd20fd8f..a6e794bfc 100644 --- a/docs/site/src/content/docs/reference/evidence-problems.mdx +++ b/docs/site/src/content/docs/reference/evidence-problems.mdx @@ -1,6 +1,6 @@ --- -title: Evidence errors and problems reference -description: What each application/problem+json response from the Evidence assertion service means and how to respond to it. +title: Evidence Gateway errors and problems reference +description: What each application/problem+json response from the Evidence Gateway assertion service means and how to respond to it. status: current owner: registry-docs source_repos: [registry-stack] @@ -10,13 +10,13 @@ locale: en standards_referenced: [] --- -Evidence returns errors as problem details with the media type `application/problem+json`. The closed set of problem types, their HTTP status, and their exact body shape are frozen in `products/evidence/contracts/problem-contract.yaml` (contract `registry.evidence.public-problem/v1`) and generated into `products/evidence/generated/problem-v1.schema.json`; both files are the source of truth for this page. The `evidence-contracts` CI job byte-diffs a freshly regenerated copy of both files against the committed copies on every change (`products/evidence/scripts/check-contracts.sh`, wired into `.github/workflows/ci.yml`), so this reference cannot drift from a released Evidence binary without the build failing. +Evidence Gateway returns errors as problem details with the media type `application/problem+json`. The closed set of problem types, their HTTP status, and their exact body shape are frozen in `products/evidence/contracts/problem-contract.yaml` (contract `registry.evidence.public-problem/v1`) and generated into `products/evidence/generated/problem-v1.schema.json`; both files are the source of truth for this page. The `evidence-contracts` CI job byte-diffs a freshly regenerated copy of both files against the committed copies on every change (`products/evidence/scripts/check-contracts.sh`, wired into `.github/workflows/ci.yml`), so this reference cannot drift from a released Evidence Gateway binary without the build failing. `POST /v1/evidence` can return any problem documented on this page. `GET /v1/evidence-definitions` returns a narrower subset: `malformed_request`, `authentication_failed`, `rate_limited`, and `service_unavailable`. ## Reading a problem response -A problem body carries exactly five members: `type`, `title`, `status`, `code`, and `operation`, and no others. There is no `detail` member. Evidence's contract closes the body with `additionalProperties: false` and explicitly excludes request bodies or selector values, principal or credential inputs, source URLs or responses, script input or output, and any candidate count, score, hint, or comparison detail. Branch client code on the stable `code` member; `type` follows the fixed pattern `https://registrystack.org/problems/evidence/`. +A problem body carries exactly five members: `type`, `title`, `status`, `code`, and `operation`, and no others. There is no `detail` member. Evidence Gateway's contract closes the body with `additionalProperties: false` and explicitly excludes request bodies or selector values, principal or credential inputs, source URLs or responses, script input or output, and any candidate count, score, hint, or comparison detail. Branch client code on the stable `code` member; `type` follows the fixed pattern `https://registrystack.org/problems/evidence/`. ```json { @@ -28,7 +28,7 @@ A problem body carries exactly five members: `type`, `title`, `status`, `code`, } ``` -The `operation` member is a ULID-shaped opaque identifier (pattern `^[0-9A-HJKMNP-TV-Z]{26}$`) that Evidence generates for the request; it is never taken from the caller. It matches the `X-Request-Id` response header on both successful and failing responses, and it is the identifier to quote to a deployment operator for support correlation. +The `operation` member is a ULID-shaped opaque identifier (pattern `^[0-9A-HJKMNP-TV-Z]{26}$`) that Evidence Gateway generates for the request; it is never taken from the caller. It matches the `X-Request-Id` response header on both successful and failing responses, and it is the identifier to quote to a deployment operator for support correlation. ## Caller request problems @@ -38,27 +38,27 @@ These problem types indicate something about the request itself. Correct the req | --- | --- | --- | --- | --- | | `malformed_request` | 400 | The request body is not valid JSON, or it does not match the documented `EvidenceRequest` schema: an unknown field, a wrong type, or a structurally invalid request nonce or holder key. | No | Validate the request body against the schema published at `/openapi.json`, and remove any field the schema does not declare. | | `invalid_selector` | 400 | The request's selector does not match any of the configured alternative profiles for the requested requirement. | No | Fetch `/v1/evidence-definitions` and match the request's selector to one of the profiles listed there for the requirement. | -| `authentication_failed` | 401 | No credential was supplied, more than one was supplied, the credential could not be parsed, or the bearer token did not verify. Evidence returns a `WWW-Authenticate: Bearer` header alongside this problem. | No | Supply exactly one `Authorization: Bearer` token, and confirm it has not expired and was issued for this deployment. | +| `authentication_failed` | 401 | No credential was supplied, more than one was supplied, the credential could not be parsed, or the bearer token did not verify. Evidence Gateway returns a `WWW-Authenticate: Bearer` header alongside this problem. | No | Supply exactly one `Authorization: Bearer` token, and confirm it has not expired and was issued for this deployment. | | `response_format_not_acceptable` | 406 | The `Accept` header fell outside the closed negotiation matrix: a duplicate, a combination of types, a quality parameter, or an unrecognized value. Missing `Accept`, `*/*`, and exactly `application/jose+json` all select the default signed response and do not trigger this problem. | No | Send at most one recognized media type in `Accept`: `application/jose+json`, `application/vnd.registrystack.evidence-unsigned+json`, or `application/dc+sd-jwt`, with no quality parameter and no combination with another type. | | `rate_limited` | 429 | The caller exceeded the configured per-principal request rate, or the separate per-principal-authority failed-selector rate (`crates/registry-evidence/src/rate_limit.rs`). | Yes, after backoff | Wait for the duration in the `Retry-After` header (this deployment sends `1` second) before retrying. | -## Requests Evidence cannot satisfy +## Requests Evidence Gateway cannot satisfy -A well-formed, authenticated request can still fail to produce evidence. Both problem types below intentionally withhold the specific reason: Evidence collapses several internal conditions into one public shape so that a response cannot be used to learn whether a record, grant, or requirement exists. +A well-formed, authenticated request can still fail to produce evidence. Both problem types below intentionally withhold the specific reason: Evidence Gateway collapses several internal conditions into one public shape so that a response cannot be used to learn whether a record, grant, or requirement exists. | Code | Status | Meaning | Retry helps | What to do | | --- | --- | --- | --- | --- | -| `not_authorized` | 403 | The authenticated caller's grant does not permit this requirement, this subject binding, or the negotiated response format, or the requirement identifier is unknown. Evidence does not reveal which of these applied, and an unknown requirement identifier is indistinguishable from a real one the caller is not authorized for. | No, without a grant change | Confirm the requirement identifier against `/v1/evidence-definitions` for the authenticated caller. If it is present there, ask the deployment operator to verify the grant covers this requirement, subject binding, and response format. | -| `evidence_not_available` | 422 | The source produced no unique matching record, the match was ambiguous, a required fact was missing, or a derivation input could not be resolved. Evidence collapses all four conditions into this one code and applies uniform, bounded processing so response timing does not indicate which condition occurred. | No, not by resubmitting the same request unchanged | Confirm with the subject that the requested fact exists in the source system. Report a persistent, unexpected result to the deployment operator with the `operation` value; Evidence does not reveal which internal condition produced it. | +| `not_authorized` | 403 | The authenticated caller's grant does not permit this requirement, this subject binding, or the negotiated response format, or the requirement identifier is unknown. Evidence Gateway does not reveal which of these applied, and an unknown requirement identifier is indistinguishable from a real one the caller is not authorized for. | No, without a grant change | Confirm the requirement identifier against `/v1/evidence-definitions` for the authenticated caller. If it is present there, ask the deployment operator to verify the grant covers this requirement, subject binding, and response format. | +| `evidence_not_available` | 422 | The source produced no unique matching record, the match was ambiguous, a required fact was missing, or a derivation input could not be resolved. Evidence Gateway collapses all four conditions into this one code and applies uniform, bounded processing so response timing does not indicate which condition occurred. | No, not by resubmitting the same request unchanged | Confirm with the subject that the requested fact exists in the source system. Report a persistent, unexpected result to the deployment operator with the `operation` value; Evidence Gateway does not reveal which internal condition produced it. | ## Source and deployment availability -Both problem types below are transient 503 responses. Evidence assigns them by where the failure occurred, not by how long it lasted. +Both problem types below are transient 503 responses. Evidence Gateway assigns them by where the failure occurred, not by how long it lasted. | Code | Status | Meaning | Retry helps | What to do | | --- | --- | --- | --- | --- | -| `dependency_unavailable` | 503 | The configured external source did not respond usably: unreachable, timed out, wrong credential, wrong media type, an oversized response, malformed JSON, or an error envelope. Evidence maps every source-boundary failure to this one code (`crates/registry-evidence/src/runtime.rs`, `source_failure_problem`). | Yes, after backoff | Retry with backoff. If it persists, report it to the deployment operator with the `operation` value: the connected source system is unavailable, not the request. | -| `service_unavailable` | 503 | A transient failure inside the Evidence deployment itself: script execution, signing, audit-log writes, or discovery and configuration lookups. This code is also returned by the unauthenticated `/openapi.json` and `/ready` endpoints when the document or readiness state cannot be produced. | Yes, after backoff | Retry with backoff. If it persists, report it to the deployment operator with the `operation` value. | +| `dependency_unavailable` | 503 | The configured external source did not respond usably: unreachable, timed out, wrong credential, wrong media type, an oversized response, malformed JSON, or an error envelope. Evidence Gateway maps every source-boundary failure to this one code (`crates/registry-evidence/src/runtime.rs`, `source_failure_problem`). | Yes, after backoff | Retry with backoff. If it persists, report it to the deployment operator with the `operation` value: the connected source system is unavailable, not the request. | +| `service_unavailable` | 503 | A transient failure inside the Evidence Gateway deployment itself: script execution, signing, audit-log writes, or discovery and configuration lookups. This code is also returned by the unauthenticated `/openapi.json` and `/ready` endpoints when the document or readiness state cannot be produced. | Yes, after backoff | Retry with backoff. If it persists, report it to the deployment operator with the `operation` value. | ## Source diff --git a/docs/site/src/content/docs/reference/evidencectl.mdx b/docs/site/src/content/docs/reference/evidencectl.mdx index 429555691..986a265dd 100644 --- a/docs/site/src/content/docs/reference/evidencectl.mdx +++ b/docs/site/src/content/docs/reference/evidencectl.mdx @@ -1,6 +1,6 @@ --- title: Evidencectl command reference -description: Reference for Evidence authoring, production build, deployment inspection, fixture, and local-development commands. +description: Reference for Evidence Gateway authoring, production build, deployment inspection, fixture, and local-development commands. status: current owner: registry-docs source_repos: @@ -11,14 +11,14 @@ locale: en standards_referenced: [] --- -`evidencectl` is Evidence adopter tooling. It creates key material and editable projects, compiles -production candidates, and invokes the `evidence` binary for Evidence semantic decisions. It does +`evidencectl` is Evidence Gateway adopter tooling. It creates key material and editable projects, compiles +production candidates, and invokes the `evidence` binary for Evidence Gateway semantic decisions. It does not approve, deploy, promote, register production clients, or write production secret values. Its client registration commands manage local development only. ## Contract status -Evidencectl is outside the frozen Evidence Version 1 runtime contract. Its command line can change +Evidencectl is outside the frozen Evidence Gateway Version 1 runtime contract. Its command line can change before a compatibility promise covers it. The `evidence` runtime remains the authority for bundle compilation, fixture evaluation, secret validation, and startup acceptance. @@ -58,13 +58,13 @@ by the final target-host `evidence check`. `evidencectl new --profile local` and `evidencectl dev` are local-authoring commands. Nothing under `.evidence/dev` is a production build input. `new` creates no source policy, question, fixture content, production target, Mint configuration, or deployable bundle. `--generate-keys` creates -disposable, unbound Evidence key material only. +disposable, unbound Evidence Gateway key material only. `evidencectl access` manages caller access for one local project: | Command | State | Result | | --- | --- | --- | -| `evidencectl access policy add --question ` | Creates `access/policies/.yaml` | Defines one or more repeated `--question` values for the next Evidence generation | +| `evidencectl access policy add --question ` | Creates `access/policies/.yaml` | Defines one or more repeated `--question` values for the next Evidence Gateway generation | | `evidencectl access policy list` | Reads `access/policies/` | Lists the governed local policies and their questions | | `evidencectl access client add --policy --generate-local-key` | Creates `access/clients/.yaml` and `.evidence/clients//private.jwk` | Registers a local client for repeated `--policy` values with non-overlapping question sets | | `evidencectl access client list` | Reads `access/clients/` | Lists local client status and policy membership | @@ -75,9 +75,9 @@ live only under `.evidence/clients/`. Generated Registry Mint registrations unde `.evidence/dev/generated/clients/` are disposable and contain public keys only. Client add and revoke request a Registry Mint reload only when `evidencectl dev` has a ready local -session. They do not restart or reload Evidence. Registry Mint does not acknowledge completion of +session. They do not restart or reload Evidence Gateway. Registry Mint does not acknowledge completion of the reload, so the next token exchange provides the functional check. A policy change requires a -new Evidence generation. +new Evidence Gateway generation. The local access commands do not define production authority or production clients. Production authority profiles remain in the deployment target's governed `governance.yaml`. Production client @@ -90,6 +90,6 @@ production candidate input. ## Related reference -- [Configure Evidence](../../configure/evidence/) +- [Configure Evidence Gateway](../../configure/evidence/) - [Registry Mint reference](../mint/) -- [Build and deploy an Evidence project](../../tutorials/build-and-deploy-evidence-project/) +- [Build and deploy an Evidence Gateway project](../../tutorials/build-and-deploy-evidence-project/) diff --git a/docs/site/src/content/docs/reference/glossary.mdx b/docs/site/src/content/docs/reference/glossary.mdx index ee7c70712..f39750f05 100644 --- a/docs/site/src/content/docs/reference/glossary.mdx +++ b/docs/site/src/content/docs/reference/glossary.mdx @@ -40,31 +40,31 @@ Product names are always in English, including on future translated pages.
acceptance definition
-
One complete authored answer path in an Evidence deployment project: a source with its request and response schema, the extraction script, the fact schema and any codelist, the derivation, the requirement with its concept and disclosure guard, the authority grant that permits it, and the synthetic fixture cases that prove it before anything is served. Evidence Version 1 freezes four coequal acceptance definitions: adult status, residence region, professional licence status, and legal-parent relationship. None is privileged in the runtime, so there is no domain type, built-in operation, or special route for any of them.
+
One complete authored answer path in an Evidence Gateway deployment project: a source with its request and response schema, the extraction script, the fact schema and any codelist, the derivation, the requirement with its concept and disclosure guard, the authority grant that permits it, and the synthetic fixture cases that prove it before anything is served. Evidence Gateway Version 1 freezes four coequal acceptance definitions: adult status, residence region, professional licence status, and legal-parent relationship. None is privileged in the runtime, so there is no domain type, built-in operation, or special route for any of them.
access token
-
The bearer credential a caller presents to Evidence. Evidence runs one authentication kind, `oidc-access-token`, whose issuer, audiences, accepted token types, algorithms, JWKS URI, and claim names are fixed in the immutable bundle, and it reads authority only from those configured claim names. Registry Mint issues such tokens for deployments with no identity provider; any issuer that writes the same claims serves equally well.
+
The bearer credential a caller presents to Evidence Gateway. Evidence Gateway runs one authentication kind, `oidc-access-token`, whose issuer, audiences, accepted token types, algorithms, JWKS URI, and claim names are fixed in the immutable bundle, and it reads authority only from those configured claim names. Registry Mint issues such tokens for deployments with no identity provider; any issuer that writes the same claims serves equally well.
assertion
-
Evidence's output: one stateless signed payload that answers a requirement and carries no source record. Its member set is closed by `products/evidence/contracts/evidence.schema.yaml`: the requirement it supports, the Evidence Type it conforms to, issuer and provider, issue, observation, and validity instants, purpose, audience, configuration revision, role-bound subject bindings, and the supported values. Signed flattened JSON Web Signature (JWS) is the default serialization; the SD-JWT VC serialization carries the same assertion and adds no credential lifecycle.
+
Evidence Gateway's output: one stateless signed payload that answers a requirement and carries no source record. Its member set is closed by `products/evidence/contracts/evidence.schema.yaml`: the requirement it supports, the Evidence Type it conforms to, issuer and provider, issue, observation, and validity instants, purpose, audience, configuration revision, role-bound subject bindings, and the supported values. Signed flattened JSON Web Signature (JWS) is the default serialization; the SD-JWT VC serialization carries the same assertion and adds no credential lifecycle.
BRegDCAT-AP
SEMIC profile of DCAT-AP for base registries. Registry Relay and Registry Manifest emit BRegDCAT-AP-shaped registry and data-service metadata.
CCCEV
-
Core Criterion and Core Evidence Vocabulary. Registry Manifest emits CCCEV-shaped requirement, evidence type, and evidence type list metadata. Evidence maps its assertion payload onto CCCEV terms under the frozen mapping in `products/evidence/contracts/cccev-field-mapping.yaml`, with named Evidence extensions where CCCEV has no counterpart.
+
Core Criterion and Core Evidence Vocabulary. Registry Manifest emits CCCEV-shaped requirement, evidence type, and evidence type list metadata. Evidence Gateway maps its assertion payload onto CCCEV terms under the frozen mapping in `products/evidence/contracts/cccev-field-mapping.yaml`, with named Evidence Gateway extensions where CCCEV has no counterpart.
caller
-
The technical client that invokes Registry Relay or Evidence. A caller can be the evidence consumer or an intermediary, portal, or workflow connector acting for it.
+
The technical client that invokes Registry Relay or Evidence Gateway. A caller can be the evidence consumer or an intermediary, portal, or workflow connector acting for it.
claim level
The evidence discipline these docs use for standards claims: `implements`, `emits`, `maps_to`, `aligns_with`, `inspired_by`, or `compares_against`.
consultation
-
A named, purpose-aware use of one Registry Relay integration. Relay resolves the consultation's pinned source plan, performs the minimized source acquisition, and returns the declared typed outputs. Evidence can be a consumer of one by treating a Relay route as an ordinary fixed HTTP source, which carries no special status in an Evidence bundle. Implemented in `crates/registry-relay/src/consultation/`.
+
A named, purpose-aware use of one Registry Relay integration. Relay resolves the consultation's pinned source plan, performs the minimized source acquisition, and returns the declared typed outputs. Consultations belong to Relay and are not an Evidence Gateway source contract. Implemented in `crates/registry-relay/src/consultation/`.
consumer decision
-
An eligibility, qualification, prioritization, approval, routing, payment, workflow, or other outcome determined outside Registry Relay and Evidence by or for an evidence consumer. The decision owner remains accountable for its rules and consequences.
+
An eligibility, qualification, prioritization, approval, routing, payment, workflow, or other outcome determined outside Registry Relay and Evidence Gateway by or for an evidence consumer. The decision owner remains accountable for its rules and consequences.
DCAT
Data Catalog Vocabulary. W3C recommendation. Registry Relay and Registry Manifest emit DCAT-shaped JSON-LD catalogs. Spell out on first use per page: "Data Catalog Vocabulary (DCAT)".
@@ -76,13 +76,13 @@ Product names are always in English, including on future translated pages.
The Relay feature that maps source field names and values to canonical domain terms using configured CEL expressions. Replaces the former `cel-mapping` name. Enabled by the `crosswalk-runtime` Cargo feature and the `standards-cel-mapping` feature alias. Config key: `crosswalk`.
deployment bundle
-
A deferred project-root packaging concept tracked by registry-stack issue #361. Current source does not generate, sign, verify, or activate a project-root bundle. Each product instead uses its own product-owned bundle, and no Registry Stack coordinator binds or atomically activates them. Not the same thing as an Evidence deployment project's governed bundle, which is one product's immutable startup input.
+
A deferred project-root packaging concept tracked by registry-stack issue #361. Current source does not generate, sign, verify, or activate a project-root bundle. Each product instead uses its own product-owned bundle, and no Registry Stack coordinator binds or atomically activates them. Not the same thing as an Evidence Gateway deployment project's governed bundle, which is one product's immutable startup input.
deployment
-
An operated set of Registry Relay or Evidence product instances. A combined topology stages each product's separately verified configuration and admits traffic only after both products are ready; this is not atomic project activation.
+
An operated set of Registry Relay or Evidence Gateway product instances. Each product stages and activates its own separately verified configuration; there is no cross-product activation coordinator, and this is not atomic project activation.
deployment project
-
The directory an Evidence operator mounts: a `runtime.yaml` file holding process-local bindings, and a `bundle/` directory holding the governed configuration, scripts, schemas, codelists, and fixtures. `evidencectl new` starts a local OpenAPI authoring workspace with reusable selector and source objects, questions, derivations, scripts, schemas, fixtures, and optional disposable Evidence keys. `evidencectl build` compiles that workspace and one explicit target into a new production candidate. Evidence loads a completed bundle read-only at startup; a new revision is a new deployment, not a live change.
+
The directory an Evidence Gateway operator mounts: a `runtime.yaml` file holding process-local bindings, and a `bundle/` directory holding the governed configuration, scripts, schemas, codelists, and fixtures. `evidencectl new` starts a local OpenAPI authoring workspace with reusable selector and source objects, questions, derivations, scripts, schemas, fixtures, and optional disposable Evidence Gateway keys. `evidencectl build` compiles that workspace and one explicit target into a new production candidate. Evidence Gateway loads a completed bundle read-only at startup; a new revision is a new deployment, not a live change.
decision owner
The institution accountable for the requirements, rules, decisions, and actions that use evidence. The decision owner can operate the evidence consumer directly or rely on a separate caller or intermediary.
@@ -91,7 +91,7 @@ Product names are always in English, including on future translated pages.
Digital Public Infrastructure. Shared, interoperable digital systems (identity, payments, data exchange) deployed at population scale to support public service delivery. These projects cover the registry-consultation slice of a DPI deployment.
DID
-
Decentralized Identifier. W3C DID Core 1.0. Registry Relay no longer publishes a `did:web` document, and no current service in the stack resolves, publishes, or issues DIDs. Evidence accepts an optional holder public key as a bare JSON Web Key, not as a DID.
+
Decentralized Identifier. W3C DID Core 1.0. Registry Relay no longer publishes a `did:web` document, and no current service in the stack resolves, publishes, or issues DIDs. Evidence Gateway accepts an optional holder public key as a bare JSON Web Key, not as a DID.
distributed custody
The architectural premise that each authority retains control of its own registry data. The registry stack provides the API surface for lawful exchange between authorities; it does not aggregate data into a central system. Equivalent terms include data sovereignty (Gaia-X, IDS, EU dataspaces vocabulary), subsidiarity (governance literature), and federated custody.
@@ -105,14 +105,14 @@ Product names are always in English, including on future translated pages.
environment
Private bindings and operational settings for one Registry Stack project deployment target. An environment does not change the project's stable intent.
-
Evidence (product)
-
The minimum-disclosure assertion service in this monorepo. Crate: `crates/registry-evidence`; product material: `products/evidence/`. Given authenticated authority, an authorized purpose, and a predefined requirement, Evidence serves a signed assertion that answers the requirement, not the source record, plus an SD-JWT VC serialization of that same stateless assertion under a frozen Version 1 profile. The SD-JWT VC format is never a credential lifecycle: no issuance session, holder-binding ceremony, status list, or revocation. Evidence is a separate greenfield product, not a reduced configuration of anything that came before it.
+
Evidence Gateway (product)
+
The minimum-disclosure assertion service in this monorepo. Crate: `crates/registry-evidence`; product material: `products/evidence/`. Given authenticated authority, an authorized purpose, and a predefined requirement, Evidence Gateway serves a signed assertion that answers the requirement, not the source record, plus an SD-JWT VC serialization of that same stateless assertion under a frozen Version 1 profile. The SD-JWT VC format is never a credential lifecycle: no issuance session, holder-binding ceremony, status list, or revocation. Evidence Gateway is a separate greenfield product, not a reduced configuration of anything that came before it.
-
Evidence toolset
-
The three released binaries `evidence`, `evidencectl`, and `mint`. Releases that include the toolset publish reproducible binaries alongside a cosign-signed `SHA256SUMS` file, and the installer installs all three together or not at all after verifying every asset. `evidencectl` shells out to `evidence` for every Evidence semantic decision and never re-implements evaluation, signing, or verification. `mint`, built from the `registry-mint` crate, issues the access tokens `evidence` verifies.
+
Evidence Gateway toolset
+
The three released binaries `evidence`, `evidencectl`, and `mint`. Releases that include the toolset publish reproducible binaries alongside a cosign-signed `SHA256SUMS` file, and the installer installs all three together or not at all after verifying every asset. `evidencectl` shells out to `evidence` for every Evidence Gateway semantic decision and never re-implements evaluation, signing, or verification. `mint`, built from the `registry-mint` crate, issues the access tokens `evidence` verifies.
-
Evidence Gateway
-
Registry Relay's governed runtime path: a Relay read or consultation passes trusted request and source context through the shared policy decision point, which permits, redacts, or denies before a response is returned. The name also survives in the ODRL enforcement profile identifier `registry-evidence-gateway-pdp/v1`. This is not Evidence (product), which is a separate service with its own authorization and disclosure contracts and no policy decision point.
+
Governed Relay PDP profile
+
Registry Relay's governed runtime path: a Relay read or consultation passes trusted request and source context through the shared policy decision point, which permits, redacts, or denies before a response is returned. The legacy ODRL enforcement profile identifier is `registry-evidence-gateway-pdp/v1`. The identifier does not name or connect to the Evidence Gateway product.
evidence consumer
A service or process that uses returned evidence. Examples include a social-protection programme, admissions service, licensing authority, healthcare workflow, lender, insurer, or credential verifier. The evidence consumer, caller, and decision owner can be the same component or separate components.
@@ -121,7 +121,7 @@ Product names are always in English, including on future translated pages.
Manifest-level binding that connects an external ecosystem profile or governed evidence pack to a Registry Stack runtime surface. A governed evidence ecosystem binding names the evidence pack metadata and policy identity a runtime service can use for PDP enforcement.
eSignet
-
Open-source identity and authentication service (part of MOSIP). No current Registry Stack service integrates with it. Evidence authenticates callers against one configured OIDC issuer and key set named in its immutable bundle, and names no specific identity product.
+
Open-source identity and authentication service (part of MOSIP). No current Registry Stack service integrates with it. Evidence Gateway authenticates callers against one configured OIDC issuer and key set named in its immutable bundle, and names no specific identity product.
evidence offering
Metadata entry in a Registry Manifest dataset that describes a verification capability and the access path a client uses to reach it (schema versions `registry-manifest-evidence-offering/v1` and `registry-manifest-evidence-offerings/v1`). Registry Manifest compiles and publishes offerings and Registry Relay serves them in its metadata; the offering is a pointer, and Relay does not evaluate the capability behind it.
@@ -133,13 +133,13 @@ Product names are always in English, including on future translated pages.
Registry Stack product term for runtime-enforced safeguards: scoped routes, disclosure policy, audit events, machine-readable metadata, and other policy enforcement point behavior that can be checked by software.
governed evidence
-
Evidence metadata and runtime behavior bound to a `governed-evidence` ecosystem binding. Manifest validation requires pack identity, evidence metadata, required PDP gates, allowed outputs, policy id/hash binding, and the `registry-evidence-gateway-pdp/v1` ODRL enforcement profile, while some evidence metadata fields remain opaque JSON.
+
Governed evidence metadata and runtime behavior bound to a `governed-evidence` ecosystem binding. Manifest validation requires pack identity, evidence metadata, required PDP gates, allowed outputs, policy id/hash binding, and the legacy `registry-evidence-gateway-pdp/v1` ODRL enforcement profile, while some evidence metadata fields remain opaque JSON.
historical docs
Older specs, implementation reviews, or pre-rename documents that remain useful evidence but are not current user guidance.
holder
-
In Evidence, the party whose public key a caller may supply as `holderKey` on a request. Evidence echoes it into the SD-JWT VC `cnf` claim and does nothing else with it: there is no holder-binding ceremony, no presentation verification, and no key-binding JWT. The key never reaches authorization, selectors, scripts, source requests, or audit (`products/evidence/contracts/request.schema.yaml`, `products/evidence/contracts/sd-jwt-vc-profile.yaml`).
+
In Evidence Gateway, the party whose public key a caller may supply as `holderKey` on a request. Evidence Gateway echoes it into the SD-JWT VC `cnf` claim and does nothing else with it: there is no holder-binding ceremony, no presentation verification, and no key-binding JWT. The key never reaches authorization, selectors, scripts, source requests, or audit (`products/evidence/contracts/request.schema.yaml`, `products/evidence/contracts/sd-jwt-vc-profile.yaml`).
interoperability
Commitment that every registry in the stack publishes its catalog, schemas, services, and policies in standards-shaped form (DCAT, BRegDCAT-AP, CPSV-AP, CCCEV, SHACL, JSON Schema, ODRL, OpenAPI, OGC Records, SKOS-shaped codelists, SD-JWT VC), so downstream systems integrate against stable contracts rather than per-deployment ones.
@@ -163,13 +163,13 @@ Product names are always in English, including on future translated pages.
Registry Stack product term for an evidence response shaped by data minimization, selective disclosure, or verifiable attestation. The response can be narrower than the full source record when the configured use case supports that pattern.
minimum disclosure
-
Evidence's design rule: one response carries the smallest sufficient answer to one requirement, never the source record. The assertion payload is closed and rejects additional properties, subject selector profiles and selector values never appear in it, the output gate admits only the exact declared concept identifiers and value forms, and purpose does not narrow disclosure, so a purpose that justifies a coarser answer needs its own requirement. See RS-PR-EVIDENCE Section 6.
+
Evidence Gateway's design rule: one response carries the smallest sufficient answer to one requirement, never the source record. The assertion payload is closed and rejects additional properties, subject selector profiles and selector values never appear in it, the output gate admits only the exact declared concept identifiers and value forms, and purpose does not narrow disclosure, so a purpose that justifies a coarser answer needs its own requirement. See RS-PR-EVIDENCE Section 6.
ODRL
Open Digital Rights Language. W3C recommendation. Relay and Manifest emit ODRL Offer documents for dataset-scoped descriptive policies. Relay governed runtime PDP enforcement currently uses `odrl:purpose`; publishing an ODRL document alone is not enforcement.
ODRL enforcement profile
-
Governed Evidence Gateway profile vocabulary for ODRL terms. The current profile is `registry-evidence-gateway-pdp/v1`; Relay currently enforces `odrl:purpose` and denies terms such as `odrl:spatial` fail-closed rather than treating them as enforced.
+
Governed Relay PDP profile vocabulary for ODRL terms. The legacy technical identifier is `registry-evidence-gateway-pdp/v1`; Relay currently enforces `odrl:purpose` and denies terms such as `odrl:spatial` fail-closed rather than treating them as enforced.
observations
The array of data rows returned in the `AggregateResult.observations` field for a Registry Relay aggregate query. Each observation is an object keyed by dimension and measure identifiers. The field replaces the former `data` name from the SDMX-refactor rename.
@@ -184,7 +184,7 @@ Product names are always in English, including on future translated pages.
Open Geospatial Consortium API specification for Environmental Data Retrieval. Registry Relay exposes profiled area queries over configured spatial aggregates behind the `ogcapi-edr` feature flag.
OID4VCI
-
OpenID for Verifiable Credential Issuance. No current Registry Stack service implements it, and OID4VCI in any part is a frozen Evidence Version 1 non-goal, so the SD-JWT VC serialization has no offer, pre-authorized code, token or nonce endpoint, or wallet grant.
+
OpenID for Verifiable Credential Issuance. No current Registry Stack service implements it, and OID4VCI in any part is a frozen Evidence Gateway Version 1 non-goal, so the SD-JWT VC serialization has no offer, pre-authorized code, token or nonce endpoint, or wallet grant.
PROV-O
W3C Provenance Ontology. Currently listed as design influence (`inspired_by`). Provenance-shaped concepts appear in audit fields, but no PROV-O vocabulary terms are emitted as JSON-LD at reviewed commits.
@@ -208,10 +208,10 @@ Product names are always in English, including on future translated pages.
Registry Stack runtime pattern for exposing existing registry source data through scoped, read-only HTTP routes with authentication, authorization, metadata, and audit. Registry Relay implements this pattern.
registry stack
-
The formal stack products: Registry Platform, Registry Relay, Registry Manifest, and Evidence, with Registry Mint as supporting token issuance. Use lowercase when referring to the concept.
+
The formal stack products: Registry Platform, Registry Relay, Registry Manifest, and Evidence Gateway, with Registry Mint as supporting token issuance. Use lowercase when referring to the concept.
purpose
-
The authorized reason a caller gives for one Evidence request. A purpose is a configured code drawn from the requirement's declared `purposes` list and from the caller's grant, never caller-defined prose. It is part of the single authorization decision, is echoed into the assertion, and does not narrow disclosure. A declared purpose is an authorized selection from the granted set, not an identity-provider attestation.
+
The authorized reason a caller gives for one Evidence Gateway request. A purpose is a configured code drawn from the requirement's declared `purposes` list and from the caller's grant, never caller-defined prose. It is part of the single authorization decision, is echoed into the assertion, and does not narrow disclosure. A declared purpose is an authorized selection from the granted set, not an identity-provider attestation.
purpose-bound request
Registry Stack product term for a request that carries or is evaluated against purpose limitation, policy-based access control, or context-aware authorization. Relay records the `Data-Purpose` header in audit records where present.
@@ -229,7 +229,7 @@ Product names are always in English, including on future translated pages.
Rust workspace for modeling, validating, and rendering standards-facing service, registry, form, and policy metadata without running Registry Relay. Provides a library (`registry-manifest-core`) and a CLI (`registry-manifest-cli`). Repo slug: `registry-manifest`.
Registry Mint
-
Small supporting service, not a fourth registry stack pattern, that issues short-lived, audience-bound access tokens to registered machine clients using the `client_credentials` grant with `private_key_jwt` client authentication, so a resource server such as Evidence can require signed tokens without standing up a general-purpose identity provider. The client registry binds each client id to its own keys and to the authority Registry Mint asserts for it. Registry Mint's tests drive Evidence's authenticator; the dependency runs one way only, and Evidence does not depend on Registry Mint. Crate: `crates/registry-mint`; binary: `mint`.
+
Small supporting service, not a fourth registry stack pattern, that issues short-lived, audience-bound access tokens to registered machine clients using the `client_credentials` grant with `private_key_jwt` client authentication, so a resource server such as Evidence Gateway can require signed tokens without standing up a general-purpose identity provider. The client registry binds each client id to its own keys and to the authority Registry Mint asserts for it. Registry Mint's tests drive Evidence Gateway's authenticator; the dependency runs one way only, and Evidence Gateway does not depend on Registry Mint. Crate: `crates/registry-mint`; binary: `mint`.
Registry Platform
Shared Rust workspace for registry security and operational primitives, including auth helpers, OIDC verification, audit envelopes, HTTP security, outbound HTTP policy, crypto, SD-JWT VC helpers, and test fixtures. Repo slug: `registry-platform`.
@@ -238,7 +238,7 @@ Product names are always in English, including on future translated pages.
Config-driven Rust service that owns registry source access, product-neutral HTTP and script adaptation, immutable snapshot lookups, and protected read-only consultation APIs. Repo slug: `registry-relay`.
Registry Stack project
-
The authored root for one registry trust domain, compiled by `registryctl` into separate product configuration inputs. It is not a deployment bundle or an activation coordinator. A project describes a Registry Relay deployment and declares Relay lanes only. An Evidence deployment is authored separately, as a deployment project.
+
The authored root for one registry trust domain, compiled by `registryctl` into separate product configuration inputs. It is not a deployment bundle or an activation coordinator. A project describes a Registry Relay deployment and declares Relay lanes only. An Evidence Gateway deployment is authored separately, as a deployment project.
Registry Stack project workspace
The local directory containing one Registry Stack project's authored YAML, scripts, fixtures, and generated review and build outputs.
@@ -247,7 +247,7 @@ Product names are always in English, including on future translated pages.
A Registry Relay-owned records API exposure of an entity, with its own access, purpose, projection, filter, and pagination policy.
requirement
-
The predefined, versioned question one Evidence request names. A requirement is declared in the immutable bundle with its identifier, kind, source, authorized purposes, subject roles and selector profiles, reference frameworks, Evidence Type, validity, derivation script, concepts, fixtures, and disclosure guard (`products/evidence/contracts/bundle.schema.yaml`). Only predefined requirements can be evaluated, and to a caller lacking authorization an unknown identifier is indistinguishable from an unauthorized one. The word is CCCEV's, adopted for the same idea.
+
The predefined, versioned question one Evidence Gateway request names. A requirement is declared in the immutable bundle with its identifier, kind, source, authorized purposes, subject roles and selector profiles, reference frameworks, Evidence Type, validity, derivation script, concepts, fixtures, and disclosure guard (`products/evidence/contracts/bundle.schema.yaml`). Only predefined requirements can be evaluated, and to a caller lacking authorization an unknown identifier is indistinguishable from an unauthorized one. The word is CCCEV's, adopted for the same idea.
service
An authored, purpose-bound public capability in a Registry Stack project. Use the specific term records service when the distinction matters. A service is the authored intent, not the Registry Relay process that serves it.
@@ -256,7 +256,7 @@ Product names are always in English, including on future translated pages.
The purpose, legal basis, consent, caller access, and disclosure rules governing one service.
source
-
The one logical registry data interface available to Registry Relay, when present, inside a project trust domain. An OAuth or JSON Web Key Set endpoint used by a protocol is not another data source. Evidence uses the same word for its own configured provider, whose origin, method, path, headers, authentication, transport trust, timeout, and byte limits are fixed in the bundle and executed only by the Rust core.
+
The one logical registry data interface available to Registry Relay, when present, inside a project trust domain. An OAuth or JSON Web Key Set endpoint used by a protocol is not another data source. Evidence Gateway uses the same word for its own configured provider, whose origin, method, path, headers, authentication, transport trust, timeout, and byte limits are fixed in the bundle and executed only by the Rust core.
source-owned decision
A decision already made and owned by an authoritative source system. A registry stack service may disclose that fact only when the requirement and its review documentation identify it as source-owned; no service recomputes the decision or claims ownership of its policy.
@@ -265,7 +265,7 @@ Product names are always in English, including on future translated pages.
Schema version string for portable metadata manifests.
reviewability
-
Commitment that every promise the stack makes is backed by an artifact a third party can inspect without trusting the operator's word. Examples include the published DCAT catalog, the SHACL shapes, the ODRL policy documents, the audit envelope schema, the JWKS public key endpoint, and the Evidence security invariant matrix with its test traceability.
+
Commitment that every promise the stack makes is backed by an artifact a third party can inspect without trusting the operator's word. Examples include the published DCAT catalog, the SHACL shapes, the ODRL policy documents, the audit envelope schema, the JWKS public key endpoint, and the Evidence Gateway security invariant matrix with its test traceability.
runtime binding
Relay configuration that connects logical manifest concepts to actual files, database tables, scopes, and backend credentials. Lives in Relay config, not in the manifest.
@@ -277,7 +277,7 @@ Product names are always in English, including on future translated pages.
Commitment that every exchange the stack mediates is authorized, scoped, and audited. Concretely: authentication by API key or OIDC; scope-checked routes; disclosure limited to what a service declares in advance; no source-registry data mutation through Relay; audit envelopes for every request that touches person-level data.
SD-JWT VC
-
Selective Disclosure JWT Verifiable Credential (IETF draft). Evidence serializes the same stateless assertion as an SD-JWT VC under the frozen profile in `products/evidence/contracts/sd-jwt-vc-profile.yaml`, when the immutable bundle and the one matched grant both permit that response format. The subject binding stays audience-scoped, so the credential is meaningful only to the relying party named in the assertion's audience. Media type: `application/dc+sd-jwt`.
+
Selective Disclosure JWT Verifiable Credential (IETF draft). Evidence Gateway serializes the same stateless assertion as an SD-JWT VC under the frozen profile in `products/evidence/contracts/sd-jwt-vc-profile.yaml`, when the immutable bundle and the one matched grant both permit that response format. The subject binding stays audience-scoped, so the credential is meaningful only to the relying party named in the assertion's audience. Media type: `application/dc+sd-jwt`.
signed response credentials
Removed Registry Relay feature that attached a W3C VCDM 2.0 VC-JWT signed credential to entity record and aggregate responses. Registry Relay no longer accepts `provenance` or entity `publicschema` credential mapping config, no longer serves `/.well-known/did.json`, `/schemas/{claim_type}/{version}`, or `/contexts/{vocab}/{version}`, and no longer returns `application/vc+jwt`. No current stack service issues W3C VCDM credentials.
@@ -310,15 +310,15 @@ Product names are always in English, including on future translated pages.
Trusted facts supplied to the PDP for a governed decision. The context can include the authenticated principal, checked scopes, requested purpose, route identity, source binding, requested fact or disclosure, jurisdiction, assurance, legal basis, consent, and source freshness. Caller-supplied facts count only when backed by trusted assertion scopes or trusted source metadata.
trust domain
-
The institutional boundary whose operators, runtime identities, policy, and deployment approval govern one Registry Stack project. A country can contain several trust domains, and a trust domain does not need to represent a country. One Evidence serving process serves exactly one operator-controlled trust domain.
+
The institutional boundary whose operators, runtime identities, policy, and deployment approval govern one Registry Stack project. A country can contain several trust domains, and a trust domain does not need to represent a country. One Evidence Gateway serving process serves exactly one operator-controlled trust domain.
wallet
-
Holder-owned application that stores credentials and presents them to verifiers. No current Registry Stack service integrates with one, and wallet onboarding, wallet attestation, and presentation verification are frozen Evidence Version 1 non-goals.
+
Holder-owned application that stores credentials and presents them to verifiers. No current Registry Stack service integrates with one, and wallet onboarding, wallet attestation, and presentation verification are frozen Evidence Gateway Version 1 non-goals.
## Style notes -- Formal product names (Registry Platform, Registry Relay, Registry Manifest, Registry Mint) and the adopter demo name (Solmara Lab) are always title case. The assertion product's name is Evidence, capitalized as a proper noun. +- Formal product names (Registry Platform, Registry Relay, Registry Manifest, Registry Mint) and the adopter demo name (Solmara Lab) are always title case. The assertion product's name is Evidence Gateway, capitalized as a proper noun. - Repo slugs and crate names (`registry-platform`, `registry-relay`, `registry-manifest`, `registry-evidence`, `registry-mint`, `solmara-lab`) are always lowercase and monospace. A retired product's slug, such as `registry-notary` where a shipped schema or image name still spells it, follows the same rule. - Legacy underscore forms (`registry_relay`) and old repo names (`decentralized-evidence-demo`) appear only in historical pages or `rename_status` fields. - The glossary provides a reference for standards acronyms but does not replace per-page first-use expansion. diff --git a/docs/site/src/content/docs/reference/itb-semic-evidence.mdx b/docs/site/src/content/docs/reference/itb-semic-evidence.mdx index 29234a512..d85cdd3a4 100644 --- a/docs/site/src/content/docs/reference/itb-semic-evidence.mdx +++ b/docs/site/src/content/docs/reference/itb-semic-evidence.mdx @@ -20,7 +20,7 @@ standards_referenced: This page summarizes selected external validation evidence for Registry Manifest. It is not a certification statement, and it does not claim every generated artifact or every runtime deployment has been tested. -Registry Relay and Evidence have no external ITB or SEMIC evidence recorded yet. +Registry Relay and Evidence Gateway have no external ITB or SEMIC evidence recorded yet. ## Summary diff --git a/docs/site/src/content/docs/reference/mint.mdx b/docs/site/src/content/docs/reference/mint.mdx index db53271cb..4185d4227 100644 --- a/docs/site/src/content/docs/reference/mint.mdx +++ b/docs/site/src/content/docs/reference/mint.mdx @@ -1,6 +1,6 @@ --- title: Registry Mint reference -description: Configuration fields, the token endpoint contract, and the Evidence verification path for the Registry Mint token issuer. +description: Configuration fields, the token endpoint contract, and the Evidence Gateway verification path for the Registry Mint token issuer. status: current owner: registry-docs source_repos: @@ -219,7 +219,7 @@ Every response body is `{"error": ""}`, from | `GET /health` | Liveness. | | `GET /ready` | Readiness. Returns `503` while no client is registered or after an audit write failure poisons the writer. | -## How a client, Registry Mint, and Evidence interact +## How a client, Registry Mint, and Evidence Gateway interact One round trip, from a client that holds only its own private key to a signed assertion. Every label in this diagram is stated in the prose and tables on this page; the diagram is a summary of @@ -230,10 +230,10 @@ sequenceDiagram autonumber participant C as Registered client participant M as Registry Mint - participant E as Evidence + participant E as Evidence Gateway participant S as Source - Note over C,E: Set up once, before any request: the client's public JWK
sits in Mint's client registry, and Evidence's
authentication block names Mint's issuer and key set. + Note over C,E: Set up once, before any request: the client's public JWK
sits in Mint's client registry, and Evidence Gateway's
authentication block names Mint's issuer and key set. C->>C: Sign an assertion with
the client's own private key C->>M: POST /token
client_credentials + assertion @@ -251,30 +251,30 @@ sequenceDiagram ``` Everything through the access-token return is the whole of Registry Mint's job. It never sees the -source, the acceptance definition, or the assertion. The remaining exchanges are Evidence's, and -Evidence's only knowledge of Registry Mint is a URL and a key set: it reads the token by the claim +source, the acceptance definition, or the assertion. The remaining exchanges are Evidence Gateway's, and +Evidence Gateway's only knowledge of Registry Mint is a URL and a key set: it reads the token by the claim names in its own configuration, so any issuer writing those claims would serve equally well. The exact wire shapes the diagram abbreviates are given in full below: [Token endpoint contract](#token-endpoint-contract) for the assertion and token, [Other endpoints](#other-endpoints) for the key set path, and -[How Evidence verifies these tokens](#how-evidence-verifies-these-tokens) for the claim names. +[How Evidence Gateway verifies these tokens](#how-evidence-gateway-verifies-these-tokens) for the claim names. Two failures collapse deliberately and are worth reading beside the diagram. A client authentication failure returns `401 invalid_client` whatever went wrong, so the token endpoint cannot be used to probe which client ids are registered. A key-set retrieval failure prevents -Evidence from verifying a token: with no key set ever retrieved, every request is rejected until +Evidence Gateway from verifying a token: with no key set ever retrieved, every request is rejected until one can be, and with a key set already held, that held set keeps being accepted only until its -allowance runs out. Evidence names the outage in either case rather than failing silently. +allowance runs out. Evidence Gateway names the outage in either case rather than failing silently. -## How Evidence verifies these tokens +## How Evidence Gateway verifies these tokens -Evidence's own `authentication` configuration block, defined in +Evidence Gateway's own `authentication` configuration block, defined in `crates/registry-evidence/src/config.rs` (`AuthenticationConfig`), names the same claims Registry Mint writes: `principalClaim`, `requesterTagsClaim`, `evidenceAudienceClaim`, `grantIdClaim`, `grantAuthorityClaim`, and an optional `actorClaim`, alongside `issuer`, `audiences`, -`tokenTypes`, `algorithms`, and `jwksUri`. Evidence verifies a presented token against that +`tokenTypes`, `algorithms`, and `jwksUri`. Evidence Gateway verifies a presented token against that configuration in `crates/registry-evidence/src/auth.rs` (`Authenticator`), reading each claim by the name configured there rather than any hardcoded name. Setting `authentication.issuer` and `authentication.jwksUri` to Registry Mint's own `issuer` and published key set, and setting each @@ -283,11 +283,11 @@ the two. This is proven by tests, not only by matching configuration. `registry-mint`'s `tests/evidence_compatibility.rs` drives the real Registry Mint router over a real on-disk -deployment and feeds the minted token to Evidence's own authenticator; +deployment and feeds the minted token to Evidence Gateway's own authenticator; `tests/delegated_subject_binding.rs` does the same for delegated, subject-bound tokens, running -Evidence's own entitlement match and selector resolution over a token minted by the real Registry -Mint router. The dependency runs one way only: Registry Mint's tests exercise Evidence's -authenticator, and Evidence does not depend on Registry Mint. +Evidence Gateway's own entitlement match and selector resolution over a token minted by the real Registry +Mint router. The dependency runs one way only: Registry Mint's tests exercise Evidence Gateway's +authenticator, and Evidence Gateway does not depend on Registry Mint. ## Next diff --git a/docs/site/src/content/docs/reference/standards.mdx b/docs/site/src/content/docs/reference/standards.mdx index d49be6fdd..5fd59af89 100644 --- a/docs/site/src/content/docs/reference/standards.mdx +++ b/docs/site/src/content/docs/reference/standards.mdx @@ -103,7 +103,7 @@ What these levels mean for integrators: - **Claim level** uses the six levels defined above. - **Surface** names the specific output or endpoint that the claim applies to. - **Profile and notes** identifies the version or profile in use and any boundary conditions. -- **Evidence** links to the source code, fixture, or document that supports the claim. +- **Evidence Gateway** links to the source code, fixture, or document that supports the claim. ## Gaps diff --git a/docs/site/src/content/docs/security/evidence.mdx b/docs/site/src/content/docs/security/evidence.mdx index 23cef0700..77f11e22c 100644 --- a/docs/site/src/content/docs/security/evidence.mdx +++ b/docs/site/src/content/docs/security/evidence.mdx @@ -1,6 +1,6 @@ --- -title: Evidence security model -description: "The security invariants Evidence enforces, how each traces to a named test, and the duties that remain with the operator." +title: Evidence Gateway security model +description: "The security invariants Evidence Gateway enforces, how each traces to a named test, and the duties that remain with the operator." status: current owner: registry-docs source_repos: @@ -11,7 +11,7 @@ locale: en standards_referenced: [] --- -Evidence's security model is contract-driven. The invariant matrix in +Evidence Gateway's security model is contract-driven. The invariant matrix in `products/evidence/contracts/security-invariant-matrix.yaml` is the source of truth for what the runtime guarantees, `products/evidence/contracts/security-test-traceability.yaml` binds every invariant to the named tests that prove it, and continuous @@ -29,7 +29,7 @@ is the complete, normative text. ### Closed request and requirement scope -Evidence evaluates only predefined, versioned requirement revisions +Evidence Gateway evaluates only predefined, versioned requirement revisions (`V1-I01`). The request schema is closed, so callers cannot supply thresholds, expressions, scripts, paths, headers, source fields, relationship types, adapter parameters, or response projections (`V1-I02`). Because a @@ -56,7 +56,7 @@ exact field set (`V1-I08`). Source calls are fixed by trusted configuration and executed only by the core, closing off SSRF, credential forwarding, and script-directed networking (`V1-I09`). Provider lookup exposes only `match`, `no_match`, or -`ambiguous`; Evidence never surfaces or chooses candidates (`V1-I10`). Rhai +`ambiguous`; Evidence Gateway never surfaces or chooses candidates (`V1-I10`). Rhai scripts return one closed lookup result and declared typed concept values only (`V1-I11`), and the core rejects undeclared concepts, extra fields, and any value that violates its type, codelist, cardinality, precision, or size @@ -101,7 +101,7 @@ integrity; it does not assert legal-signature status or source truth ### Discovery, nonce handling, and response-format authorization -Evidence-definition discovery is authenticated and requester-scoped; it never +Evidence Gateway definition discovery is authenticated and requester-scoped; it never creates authority or exposes deployment internals such as selectors, source plans, or credentials (`V1-I26`). Every request carries one canonical 32-byte random nonce that is echoed into the evidence payload but never @@ -124,7 +124,7 @@ unique role-bound subject bindings, and the expected concept identifiers, forms, and cardinalities, and returns one generic policy-mismatch error rather than revealing which comparison failed (`V1-I31`). An access token carrying a proof-of-possession confirmation claim is denied rather than -accepted as an ordinary bearer token, because Evidence validates no sender +accepted as an ordinary bearer token, because Evidence Gateway validates no sender proof and accepting one would discard the constraint the token was issued under (`V1-I32`). @@ -215,7 +215,7 @@ merge, mutation, governed-field override, or fallback bundle or runtime file: a new revision is a new deployment, not a live change. Secret handling. Source credentials and private signing material reach -Evidence only through the secret-reference mechanism and must not appear in +Evidence Gateway only through the secret-reference mechanism and must not appear in YAML values, Rhai, command arguments, environment dumps, logs, audit, errors, snapshots, or generated contracts. The operator configures exactly one active signing key, whose `kid` matches `signing.activeKeyId`, and @@ -224,7 +224,7 @@ maximum assertion validity plus allowed clock skew. ## Report a vulnerability -Suspected Evidence vulnerabilities, including credential disclosure, +Suspected Evidence Gateway vulnerabilities, including credential disclosure, authentication bypass, audit redaction failure, source connector data leakage, and signing-key handling bugs, go through the private disclosure process in [SECURITY.md](https://github.com/registrystack/registry-stack/blob/main/SECURITY.md), diff --git a/docs/site/src/content/docs/security/hardening-checklist.mdx b/docs/site/src/content/docs/security/hardening-checklist.mdx index 5b2811aec..e056f976d 100644 --- a/docs/site/src/content/docs/security/hardening-checklist.mdx +++ b/docs/site/src/content/docs/security/hardening-checklist.mdx @@ -26,10 +26,10 @@ production-ready. ## When to use this Use this checklist before a deployment serving real data goes live, and again after any change to -signing keys, audit sinks, network placement, the governed Evidence bundle, or Relay's declared +signing keys, audit sinks, network placement, the governed Evidence Gateway bundle, or Relay's declared deployment profile. It assumes you have already configured your services per the [Registry Relay configuration reference](../../products/registry-relay/configuration/) and, for -Evidence, [Configure Evidence](../../configure/evidence/). +Evidence Gateway, [Configure Evidence Gateway](../../configure/evidence/). ## Before you start @@ -39,7 +39,7 @@ Evidence, [Configure Evidence](../../configure/evidence/). profile is never inferred from hostname or network position; you declare it. - Have your Relay startup logs and `registry-relay doctor` output available to check gate findings as you work through each Relay item. -- Have `evidence check` runnable against the exact revision you intend to serve. Evidence has no +- Have `evidence check` runnable against the exact revision you intend to serve. Evidence Gateway has no posture endpoint, no profile declaration, and no admin surface: its equivalent of a gate finding is a startup or readiness failure, so the offline commands are where you find problems first. - When the deployment runs Registry Mint, have `mint check` and `mint verify-audit` runnable @@ -47,31 +47,31 @@ Evidence, [Configure Evidence](../../configure/evidence/). ## Keys and custody -- Evidence: configure exactly one active signing key, an Ed25519 private JWK whose `kid` matches +- Evidence Gateway: configure exactly one active signing key, an Ed25519 private JWK whose `kid` matches `signing.activeKeyId` in the governed bundle. `evidence check` refuses a deployment whose signing material startup would refuse, including a `kid` mismatch. -- Evidence: supply every private key and source credential through a `secret:file/` +- Evidence Gateway: supply every private key and source credential through a `secret:file/` reference resolved under `secretProviders.file.root`, never as a YAML value, a command argument, or an environment dump. The file provider reads only regular, non-symlink files below that root, each owned by the service identity at mode `0600`, and it checks owner, mode, no-follow, link count, and open-file identity. Keep the secret root itself operator-only. -- Evidence: give the audit hash key and the subject-binding key independently generated raw key +- Evidence Gateway: give the audit hash key and the subject-binding key independently generated raw key material of at least 32 bytes each. The file provider does not base64-decode them, so write raw bytes rather than an encoded string. -- Evidence: rotate a signing key by starting a new revision with the new active key and keeping +- Evidence Gateway: rotate a signing key by starting a new revision with the new active key and keeping the retired public JWK published for at least the maximum assertion validity plus the allowed clock skew. Do not remove a public key a stored assertion still needs. -- Evidence Version 1 has exactly one secret provider, the file provider. There is no +- Evidence Gateway Version 1 has exactly one secret provider, the file provider. There is no hardware-security-module or PKCS#11 option, so key custody is a property of the host, its disk, its backups, and its operators. Treat that as a deployment control you own, not one the runtime - provides. See [Move Evidence to production signing](../../tutorials/move-evidence-to-production-signing/). + provides. See [Move Evidence Gateway to production signing](../../tutorials/move-evidence-to-production-signing/). - Relay: confirm every env-backed `fingerprint.name` referenced in config exists in the runtime environment, and that no raw key, fingerprint, private JWK, or full environment dump reaches a log line; see the production checklist in the [Registry Relay configuration reference](../../products/registry-relay/configuration/). - Relay: keep the OIDC algorithm allowlist to what the deployment actually uses. `HS*` and `none` are absent from the configuration type entirely; the default allowlist is RS256, ES256, and - EdDSA. Evidence's own access-token allowlist is configured per bundle from the same three, while + EdDSA. Evidence Gateway's own access-token allowlist is configured per bundle from the same three, while its assertion signing is EdDSA only and not configurable. - Registry Mint, when the deployment runs it: hold Registry Mint's private JWK in an owner-only, non-symlink file, and treat `clients.directory` as key material rather than configuration. Any @@ -81,10 +81,10 @@ Evidence, [Configure Evidence](../../configure/evidence/). 32 bytes of random material, and keep it in a separate owner-only, non-symlink file. Retain the key for as long as its audit chain must remain verifiable. -## Freeze the Evidence deployment project +## Freeze the Evidence Gateway deployment project - Mount the governed `bundle/` directory, `runtime.yaml`, and every captured artifact read-only - and non-writable to the service process. Evidence reports a non-immutable-input error and + and non-writable to the service process. Evidence Gateway reports a non-immutable-input error and refuses to start rather than serving from an input it could write to. - Freeze the project before validating or serving it, then validate the frozen bytes: @@ -109,20 +109,20 @@ Evidence, [Configure Evidence](../../configure/evidence/). ## Audit sink and retention -- Evidence: put `auditStorage.path` on storage whose append durability, permissions, capacity, +- Evidence Gateway: put `auditStorage.path` on storage whose append durability, permissions, capacity, backup, restore, and retention you own. Both audit events are fail-closed by contract: the access-attempt event must be durably accepted before the first source read and the disclosure-release event before the response is released, so an unwritable sink stops the service returning success rather than degrading quietly. -- Evidence: run exactly one process per audit path. The sink takes an exclusive advisory lock on +- Evidence Gateway: run exactly one process per audit path. The sink takes an exclusive advisory lock on `.lock` at startup, and a second process pointed at the same path fails to start. The supported shape is one replica per audit path, active/passive, recovered with a readiness probe and restart-on-failure rather than with a second concurrent writer. -- Evidence: treat `auditStorage.maximumFileBytes` as a per-segment rotation threshold, not a +- Evidence Gateway: treat `auditStorage.maximumFileBytes` as a per-segment rotation threshold, not a ceiling on the chain. Rotation happens online with no operator action, nothing in the runtime deletes or compacts a sealed segment, and total disk consumption is therefore unbounded until your retention process acts. -- Evidence: run `evidence verify-audit` over the whole audit directory during backup, restore, and +- Evidence Gateway: run `evidence verify-audit` over the whole audit directory during backup, restore, and incident procedures, and on whatever cadence your retention policy requires. Startup verifies only the active segment, so this pass is what proves sealed history was not tampered with. - Registry Mint: put `audit.path` on durable storage whose permissions, capacity, backup, restore, @@ -171,17 +171,17 @@ Evidence, [Configure Evidence](../../configure/evidence/). before exposing a service beyond the host. - Terminate TLS and manage certificates at your reverse proxy or load balancer; RS-SEC-G Section 9 leaves transport termination and certificate management to the operator. -- Evidence: bind the listener to loopback, a private IPv4 address, or a unique-local IPv6 address. +- Evidence Gateway: bind the listener to loopback, a private IPv4 address, or a unique-local IPv6 address. The runtime schema admits nothing else, fixes `tlsTermination` at `operator-controlled-upstream`, and fixes `trustProxyIdentityHeaders` at `false`. A gateway may - add publication, routing, and extra rate controls, but Evidence still validates its own token + add publication, routing, and extra rate controls, but Evidence Gateway still validates its own token profile and never accepts a proxy-supplied identity header. -- Evidence: leave `metricsListener` unset unless you need it. When set, it must bind an address +- Evidence Gateway: leave `metricsListener` unset unless you need it. When set, it must bind an address distinct from the evidence listener and subject to the same private-address rule, it serves only `GET /metrics`, and the evidence listener never serves metrics. Reach it from your own network only: per-route request rates are operational information even though no label carries caller content. -- Evidence: size `rateLimits` knowing they are per process and in memory. Running N replicas +- Evidence Gateway: size `rateLimits` knowing they are per process and in memory. Running N replicas multiplies every configured limit by N and a restart resets each budget to full. Set the failed-selector budget deliberately, because it is the selector-enumeration defense rather than a throughput knob, and put per-client quotas in the gateway. @@ -199,10 +199,9 @@ Evidence, [Configure Evidence](../../configure/evidence/). - Relay: enforce ingress rate limiting at your gateway or edge, then either declare `deployment.evidence.ingress_rate_limit: true` or accept the `relay.ingress.rate_limit_missing` finding it otherwise raises. The flag defaults to `false`. -- When Evidence reads a Relay-protected API as a fixed source, keep that hop on a private network, - publish no port for it, and give Evidence its own client credential scoped to exactly the routes - the bundle reads. Relay authenticates the Evidence workload, not the caller that asked Evidence, - so joining the two audit trails for one request is a procedure you own. +- Keep every Evidence Gateway source hop on a private network where possible, publish no unnecessary + source port, and give Evidence Gateway a dedicated source credential scoped to exactly the operation + the bundle performs. Source authorization and audit remain independently operated controls. - Require every project-authored Relay source destination to be an exact HTTPS origin. The project validator rejects origins with user information, paths, queries, or fragments. - For Postgres sources, require `sslmode=require` on the connection string and use read-only @@ -210,12 +209,12 @@ Evidence, [Configure Evidence](../../configure/evidence/). table or view. - Apply Registry Platform HTTP-security response headers and outbound HTTP policy to product egress. Confirm that Relay source calls remain inside the compiler-pinned destination, method, - path, and cumulative budget (REQ-SEC-G-012), and that every Evidence source keeps hostname and - fixed-origin verification on. Evidence ignores `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, and + path, and cumulative budget (REQ-SEC-G-012), and that every Evidence Gateway source keeps hostname and + fixed-origin verification on. Evidence Gateway ignores `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, and `NO_PROXY` and has no application-level proxy, so an ambient proxy variable will not silently redirect a source call. - Registry Mint, when the deployment runs it: put TLS in front of it. Registry Mint serves plain - HTTP and expects termination it does not manage, while Evidence requires the token issuer and + HTTP and expects termination it does not manage, while Evidence Gateway requires the token issuer and its key set to be HTTPS with no loopback exception. Keep `accessTokens.lifetimeSeconds` short inside its `60..=3600` bound, because a minted token is accepted until it expires and no service in this stack revokes one. @@ -238,12 +237,12 @@ Evidence, [Configure Evidence](../../configure/evidence/). - Relay: use `deployment.evidence.*` flags (for example `ingress_rate_limit`, `api_key_rotation`) only to assert controls that live outside the process and cannot be observed by it. Each flag defaults to `false`. -- Evidence has no equivalent declaration and no posture route, by design. Its posture is the exact +- Evidence Gateway has no equivalent declaration and no posture route, by design. Its posture is the exact bytes it loaded: one governed bundle and one closed runtime file, each with its own content digest, mounted read-only, with no reload, merge, mutation, governed-field override, or fallback path. Record the bundle revision you deployed, because that identifier plus the digests is the only description of what the process is enforcing. -- Evidence serves one operator-controlled trust domain per process. Mutually distrustful issuers +- Evidence Gateway serves one operator-controlled trust domain per process. Mutually distrustful issuers or customers, or one issuer whose clients carry the same authority under different claim names, require a second deployment with its own bundle, signer, and audit boundary. @@ -251,19 +250,19 @@ Evidence, [Configure Evidence](../../configure/evidence/). - Know your private disclosure channel before you need it: see [Report a vulnerability](../report-a-vulnerability/). -- Rotate a compromised Evidence signing key by deploying a new revision with a new active key, +- Rotate a compromised Evidence Gateway signing key by deploying a new revision with a new active key, keeping the compromised public key published only as long as stored assertions must still - verify, then removing it. Evidence defines no revocation, status list, or presentation-time + verify, then removing it. Evidence Gateway defines no revocation, status list, or presentation-time check, so a released assertion stays verifiable until its declared validity expires. Plan the incident response around short validity windows rather than around recall. - Rotate a compromised source credential or Registry Mint client key at the credential's own source and restart the affected process. Neither service reloads secret material in place. -- Preserve the audit trail for post-incident review. For Evidence, take the whole audit directory +- Preserve the audit trail for post-incident review. For Evidence Gateway, take the whole audit directory including sealed segments and run `evidence verify-audit` over it before and after moving it; for Relay, hash-chained, fail-closed audit records are the record a deployment reconstructs a request timeline from (REQ-SEC-G-008, REQ-SEC-G-009). For Registry Mint, preserve the chain and matching HMAC key, then run `mint verify-audit` before and after moving it. -- Expect a `403` from Evidence to tell you nothing. Every authorization refusal collapses to one +- Expect a `403` from Evidence Gateway to tell you nothing. Every authorization refusal collapses to one generic `not_authorized` problem, deliberately, so it is not an oracle for which check failed. Debug it from trusted local state in this order: the bearer principal is in the deployed bundle's audience; a grant matches the requested requirement, purpose, and subject roles; the @@ -279,7 +278,7 @@ Evidence, [Configure Evidence](../../configure/evidence/). matches what you declared, and that no unwaived finding at or above your profile's threshold is outstanding. Validate the response as [RS-OP-POSTURE](../../spec/rs-op-posture/) before an automated check acts on it. -- Evidence: confirm `GET /ready` succeeds, which rechecks the subject-binding key, the signing +- Evidence Gateway: confirm `GET /ready` succeeds, which rechecks the subject-binding key, the signing provider, the pinned audit sink, and every source credential, including a bounded OAuth token bootstrap where a source uses client credentials. Readiness sends no evidence-data request and probes no source data endpoint, so a passing probe is not proof that a source returns data. @@ -288,7 +287,7 @@ Evidence, [Configure Evidence](../../configure/evidence/). retained chain. A passing readiness probe does not prove off-host receipt or retention. - Send a request that should be audited and confirm a corresponding record lands in your configured sink, not only `stdout`. -- Evidence: request an assertion and verify the stored response offline with +- Evidence Gateway: request an assertion and verify the stored response offline with `evidence verify --jws --jwks --policy `, using expectations you retained independently rather than values read back out of the response. - Attempt an admin-listener request to Relay from outside the private network it is meant to be @@ -301,16 +300,16 @@ Evidence, [Configure Evidence](../../configure/evidence/). | Relay refuses to start after declaring `production` or `evidence_grade` | A `startup_fail` gate tripped, for example a missing audit sink or unsigned config | Check the posture or startup log for the finding id, then fix the underlying condition; `startup_fail` gates cannot be waived | | Relay startup reports `deployment.profile_undeclared` | No `deployment.profile` is set | Declare the actual profile explicitly before restarting; an omitted profile is not the same as `local` | | Relay posture reports `deployment.waiver_expired` | A waiver's `expires` date passed | Re-review the finding and either fix it or issue a new waiver with a new expiry | -| Evidence refuses to start on a non-immutable input | The bundle directory, `runtime.yaml`, or a captured artifact is writable by the service process | Re-freeze the project (`chmod -R a-w bundle && chmod 444 runtime.yaml`) and restart | -| A second Evidence process fails at startup with a sink-locked error | Two processes point at the same `auditStorage.path` | Run one writer per audit path; use active/passive with restart-on-failure rather than a second replica | +| Evidence Gateway refuses to start on a non-immutable input | The bundle directory, `runtime.yaml`, or a captured artifact is writable by the service process | Re-freeze the project (`chmod -R a-w bundle && chmod 444 runtime.yaml`) and restart | +| A second Evidence Gateway process fails at startup with a sink-locked error | Two processes point at the same `auditStorage.path` | Run one writer per audit path; use active/passive with restart-on-failure rather than a second replica | | A second Registry Mint process fails to start, or `mint verify-audit` rejects its chain | Another writer holds `audit.path`, or retained records were changed, reordered, or written with another key | Run one writer per path and restore the matching retained chain and HMAC key; do not delete audit records to make startup pass | | Registry Mint returns `500 server_error` and then fails readiness | The process could not durably append a token decision and poisoned its audit writer | Stop traffic, preserve and verify the chain, restore writable durable storage, and restart Mint; the failed request did not receive a token | -| Evidence returns `403 not_authorized` for a request you expected to work | Any one of the audience, grant, authority, or response-format checks failed; the response never says which | Work through the ordered checks in [Incident response](#incident-response) against local configuration, then read the refusal phase from the audit chain | +| Evidence Gateway returns `403 not_authorized` for a request you expected to work | Any one of the audience, grant, authority, or response-format checks failed; the response never says which | Work through the ordered checks in [Incident response](#incident-response) against local configuration, then read the refusal phase from the audit chain | ## Next - [Security overview](../) -- [Evidence security model](../evidence/) +- [Evidence Gateway security model](../evidence/) - [Report a vulnerability](../report-a-vulnerability/) -- [Configure Evidence](../../configure/evidence/) +- [Configure Evidence Gateway](../../configure/evidence/) - [Known limitations and non-guarantees](../../explanation/known-limitations/) diff --git a/docs/site/src/content/docs/security/index.mdx b/docs/site/src/content/docs/security/index.mdx index 572cd6405..ea04677b3 100644 --- a/docs/site/src/content/docs/security/index.mdx +++ b/docs/site/src/content/docs/security/index.mdx @@ -68,23 +68,23 @@ authenticate, authorize, serve, audit. Every route that returns person-level records or an evidence assertion requires authentication. Operational probes, public verification keys, issuer metadata, and docs or OpenAPI when configured may be public because they carry no person-level data. -Evidence exempts only its probes, its OpenAPI document, its issuer JWKS, and its issuer metadata +Evidence Gateway exempts only its probes, its OpenAPI document, its issuer JWKS, and its issuer metadata document; both its assertion route and its evidence-definition discovery route require a verified access token (REQ-SEC-G-006). Issuers sign with asymmetric keys and publish only the public half, so any verifier can check a signed artifact without holding a credential of its own (REQ-SEC-G-007). -Evidence can serialize the same signed assertion as an SD-JWT VC, where the signed body carries +Evidence Gateway can serialize the same signed assertion as an SD-JWT VC, where the signed body carries hashes of each disclosable field rather than the values. That is a second encoding of one response, not a credential lifecycle: there is no issuance session, holder-binding ceremony, status list, revocation, or presentation verification. -A request may carry an optional `holderKey`, echoed into the `cnf` claim; Evidence issues no +A request may carry an optional `holderKey`, echoed into the `cnf` claim; Evidence Gateway issues no key-binding JWT, requires none, and verifies none, so `cnf` is an unverified caller-supplied convenience for whatever presentation layer the operator runs elsewhere. The subject identifier stays an audience-scoped pseudonym, so the same person requested for a different audience yields a different identifier. -Where a deployment has no identity provider, Registry Mint issues the access tokens Evidence +Where a deployment has no identity provider, Registry Mint issues the access tokens Evidence Gateway verifies. Mint authenticates each registered client with an asymmetric client assertion, checked only against the keys registered for the client the assertion names, and reads the minted token's authority from its own server-side client registry rather than from the assertion. Its token @@ -123,7 +123,7 @@ the deployment's actual state is inspectable rather than asserted. The default t metadata. The gate catalogs are documented in the [Registry Relay configuration reference](../products/registry-relay/configuration/). -Evidence states its own operator obligations in its operator contract rather than through this +Evidence Gateway states its own operator obligations in its operator contract rather than through this posture block. ## What stays with the operator @@ -137,7 +137,7 @@ primitives; the operator provisions, configures, and operates them. Record those responsibilities in the [operator handoff checklist](../operate/) before activation. -## Evidence for reviewers +## Evidence Gateway for reviewers Public, checkable evidence, from most to least formal: diff --git a/docs/site/src/content/docs/security/self-assessment.mdx b/docs/site/src/content/docs/security/self-assessment.mdx index 702cddb39..15499b113 100644 --- a/docs/site/src/content/docs/security/self-assessment.mdx +++ b/docs/site/src/content/docs/security/self-assessment.mdx @@ -31,7 +31,7 @@ against that public guide. Registry Stack helps operators publish governed registry-facing services over data they already hold. The two main runtime patterns are protected registry APIs through Registry Relay and signed minimum-disclosure assertions through -Evidence. +Evidence Gateway. The public architecture, boundary model, and product roles are documented in [Architecture](../../explanation/architecture/) and @@ -57,8 +57,8 @@ Software guarantees include: governed evidence evaluation. - Disclosure controls that can return narrower evidence instead of source records. -- Signed, stateless Evidence assertions, serialized as a flattened JWS or, under - Evidence's frozen profile, as an SD-JWT VC response. +- Signed, stateless Evidence Gateway assertions, serialized as a flattened JWS or, under + Evidence Gateway's frozen profile, as an SD-JWT VC response. - Hash-chained audit records emitted by runtime services. - Release workflow support for an authenticated checksum chain, exact image digests, a consolidated SPDX SBOM, image-specific SBOM and Grype evidence, @@ -120,7 +120,7 @@ Primary public evidence: - [RS-SEC-G](../../spec/rs-sec-g/) - [Contracts](../../reference/contracts/) - [OpenSSF evidence](../openssf-evidence/) -- [Evidence API reference](../../reference/apis/registry-evidence/) +- [Evidence Gateway API reference](../../reference/apis/registry-evidence/) - [Registry Relay API reference](../../reference/apis/registry-relay/) - GitHub Release assets, with signed checksums, consolidated SPDX SBOM, security evidence, image lock, release manifest, and candidate attestations diff --git a/docs/site/src/content/docs/spec/rs-arc-g.mdx b/docs/site/src/content/docs/spec/rs-arc-g.mdx index df7b3cc86..91bd3a3ec 100644 --- a/docs/site/src/content/docs/spec/rs-arc-g.mdx +++ b/docs/site/src/content/docs/spec/rs-arc-g.mdx @@ -51,12 +51,12 @@ For a narrative explanation with worked examples, see the [architecture overview | --- | --- | --- | --- | | 0.1.0 | 2026-06-13 | draft | Initial architecture, distilled from the current architecture overview and boundary map. | | 0.2.0 | 2026-06-13 | draft | Added REQ-ARC-G-010: the portable metadata layer describes but does not authorize, enforce, or assert facts about live data. | -| 0.3.0 | 2026-06-20 | draft | Clarified governed runtime PDP enforcement for the supported Evidence Gateway profile while preserving the descriptive metadata boundary. | +| 0.3.0 | 2026-06-20 | draft | Clarified governed runtime PDP enforcement for the supported Relay profile while preserving the descriptive metadata boundary. | | 0.3.1 | 2026-06-22 | draft | Clarified static-peer delegated evaluation as distinct from delegated subject access. | | 0.4.0 | 2026-07-07 | draft | Clarified REQ-ARC-G-009's replay storage scope: shared within a deployment's own replicas, never across a federation trust boundary. Reframed Registry Lab as a non-normative demonstration topology. | | 0.4.1 | 2026-07-07 | draft | Stated plainly in REQ-ARC-G-009 that the per-peer replay storage isolation is deployment topology and that Registry Notary enforces no runtime gate for it. REQ-ARC-G-009 is retired as of 0.6.0. | | 0.5.0 | 2026-07-16 | draft | Defined four formal Registry Stack products and moved the non-normative demo boundary to the separate Solmara Lab adopter project. | -| 0.6.0 | 2026-08-03 | draft | Registry Notary is retired. Removed its component section, its federation flow step, and REQ-ARC-G-008, REQ-ARC-G-009, REQ-ARC-G-012, and REQ-ARC-G-013. Restated REQ-ARC-G-007 with Evidence as the owner of requirement evaluation. Added Evidence and Registry Mint as components and added REQ-ARC-G-014, REQ-ARC-G-015, and REQ-ARC-G-016. | +| 0.6.0 | 2026-08-03 | draft | Registry Notary is retired. Removed its component section, its federation flow step, and REQ-ARC-G-008, REQ-ARC-G-009, REQ-ARC-G-012, and REQ-ARC-G-013. Restated REQ-ARC-G-007 with Evidence Gateway as the owner of requirement evaluation. Added Evidence Gateway and Registry Mint as components and added REQ-ARC-G-014, REQ-ARC-G-015, and REQ-ARC-G-016. | ## 1. Scope and audience @@ -93,7 +93,7 @@ flowchart TD subgraph runtime["Runtime services layer"] relay["Registry Relay
(registry-relay)
Binds manifest artifacts to data sources;
enforces read-only access control
and governed PDP policy"] - evidence["Evidence
(registry-evidence)
Evaluates one predefined requirement;
returns one signed minimum-disclosure assertion"] + evidence["Evidence Gateway
(registry-evidence)
Evaluates one predefined requirement;
returns one signed minimum-disclosure assertion"] end subgraph support["Supporting components"] @@ -119,8 +119,8 @@ demo. This section restates the essential relationships as text: Registry Manifest produces a static discovery bundle consumed by Registry Relay, static publishers, and clients that inspect the metadata offline. Registry Platform supplies shared primitives to the runtime services. Registry Relay owns registry source access and -product-neutral adaptation. Evidence answers one bounded question about one subject from its own -configured sources. Registry Mint issues the access tokens a resource server such as Evidence +product-neutral adaptation. Evidence Gateway answers one bounded question about one subject from its own +configured sources. Registry Mint issues the access tokens a resource server such as Evidence Gateway verifies, and that dependency runs one way only. Solmara Lab consumes published stack images in runnable local and hosted demo topologies, but it is not a formal Registry Stack product. @@ -139,19 +139,19 @@ Registry Manifest (`registry-manifest`) is a pure Rust library and command-line Registry Relay (`registry-relay`) is a config-driven Rust service that turns sensitive government tabular files and database tables into protected, read-only, domain-oriented consultation APIs. At startup it reads runtime configuration that binds the manifest's logical datasets and entities to actual data sources (CSV, XLSX, Parquet, PostgreSQL). It exposes entity routes, metadata routes, evidence-offering endpoints, and (behind feature flags) OGC API Records, OGC API Features, OGC API EDR, SP DCI, and SDMX-JSON aggregate surfaces. -Registry Relay is not an open-data portal; it serves restricted consultation APIs for authorized systems only. Source-registry data mutation is out of scope for v1. On governed runtime routes, Relay can enforce the supported Evidence Gateway PDP profile (`registry-evidence-gateway-pdp/v1`) for access, freshness, and redaction decisions using runtime configuration, compiled policy metadata, and trusted per-request context. That profile identifier names Relay's own configured policy surface; it is not the Evidence service described in the next section, and Evidence neither publishes nor consumes it. This is runtime policy enforcement for the configured gateway surface; it is not requirement evaluation, assertion signing, full Evidence Gateway interoperability, or full OID4VCI behavior. Registry Relay does not own the manifest schema, requirement evaluation, assertion signing, or the shared primitives supplied by Registry Platform. +Registry Relay is not an open-data portal; it serves restricted consultation APIs for authorized systems only. Source-registry data mutation is out of scope for v1. On governed runtime routes, Relay can enforce the supported Relay PDP profile (`registry-evidence-gateway-pdp/v1`) for access, freshness, and redaction decisions using runtime configuration, compiled policy metadata, and trusted per-request context. The legacy profile identifier names Relay's configured policy surface; it does not name or connect to Evidence Gateway. This is runtime policy enforcement for the configured Relay surface; it is not requirement evaluation, assertion signing, interoperability with Evidence Gateway, or full OID4VCI behavior. Registry Relay does not own the manifest schema, requirement evaluation, assertion signing, or the shared primitives supplied by Registry Platform. -### Evidence +### Evidence Gateway -Evidence (`registry-evidence`) is a single-crate Rust service and the `evidence` binary. It answers one bounded question about one subject with one signed assertion that carries the answer and not the record. It loads one reviewed governed bundle and one closed operator runtime file at startup, treats both as immutable for the process lifetime, and holds no application database: it persists no selector, no source payload, no evidence value, and no response body. It authenticates callers with strict OIDC bearer tokens against exactly one trusted issuer, matches exactly one authority path per request, calls the fixed bounded HTTP JSON sources its bundle declares, and releases the assertion as a flattened JWS JSON document by default. Where the bundle and the matched grant both enable it, the same assertion can also be serialized as an SD-JWT VC (`application/dc+sd-jwt`) or as a visibly unsigned envelope for local diagnosis. +Evidence Gateway (`registry-evidence`) is a single-crate Rust service and the `evidence` binary. It answers one bounded question about one subject with one signed assertion that carries the answer and not the record. It loads one reviewed governed bundle and one closed operator runtime file at startup, treats both as immutable for the process lifetime, and holds no application database: it persists no selector, no source payload, no evidence value, and no response body. It authenticates callers with strict OIDC bearer tokens against exactly one trusted issuer, matches exactly one authority path per request, calls the fixed bounded HTTP JSON sources its bundle declares, and releases the assertion as a flattened JWS JSON document by default. Where the bundle and the matched grant both enable it, the same assertion can also be serialized as an SD-JWT VC (`application/dc+sd-jwt`) or as a visibly unsigned envelope for local diagnosis. -Evidence Version 1 has no credential issuance lifecycle, no OID4VCI surface, no holder binding, no status list or revocation, no delegated or federated evaluation between peers, no policy decision point, no replay subsystem, and no worker or document subsystem. It does not depend on Registry Relay, does not consult it, and does not read the metadata manifest. +Evidence Gateway Version 1 has no credential issuance lifecycle, no OID4VCI surface, no holder binding, no status list or revocation, no delegated or federated evaluation between peers, no policy decision point, no replay subsystem, and no worker or document subsystem. It does not depend on Registry Relay, does not consult it, and does not read the metadata manifest. ### Registry Mint Registry Mint (`registry-mint`) is a supporting service rather than a fourth runtime pattern: it is a minimal OAuth 2.0 token issuer and the `mint` binary, for deployments that have no identity provider of their own. A registered client authenticates with an RFC 7523 `private_key_jwt` client assertion, which is verified only against the keys registered for the client the assertion names. The authority claims carried by the minted access token are read from the server-side client registry and never from the assertion. Issuer identity, signing keys, listener, and token policy are startup-only and immutable for the process lifetime; the client registry is reloadable, so onboarding, offboarding, and client key rotation do not require restarting a resource server. Registry Mint evaluates no requirement, reads no registry source, and issues no assertion. -The dependency runs one way. A resource server such as Evidence verifies a Mint-issued token as an ordinary OIDC access token, and Evidence carries no dependency on Registry Mint. In the workspace, `registry-mint` takes `registry-evidence` as a development dependency so that Mint's tests drive the Evidence authenticator against real tokens. +The dependency runs one way. A resource server such as Evidence Gateway verifies a Mint-issued token as an ordinary OIDC access token, and Evidence Gateway carries no dependency on Registry Mint. In the workspace, `registry-mint` takes `registry-evidence` as a development dependency so that Mint's tests drive the Evidence Gateway authenticator against real tokens. ### Solmara Lab @@ -175,11 +175,11 @@ The following ordered flow describes how a request moves through the stack from 3. **Compilation and bundle rendering.** Registry Manifest validates the manifest and renders a static discovery bundle. The bundle contains the catalog, DCAT and BRegDCAT-AP JSON-LD, CPSV-AP JSON-LD, SHACL node shapes, JSON Schema documents, OGC API Records item collection, ODRL policy documents, CCCEV metadata, evidence-offering metadata, embedded SKOS-shaped codelist metadata, and an `index.json`. The bundle can be hosted as static files without running any runtime service. -4. **Runtime binding and access control.** Registry Relay starts with runtime configuration that binds the manifest's logical datasets and entities to actual data sources. Clients reach entity routes, metadata routes, and evidence-offering endpoints through configured authentication. Relay records a `Data-Purpose` header in audit envelopes where present. On governed runtime routes, Relay evaluates the supported Evidence Gateway PDP profile before disclosure and applies redaction when the decision permits only a minimized response. +4. **Runtime binding and access control.** Registry Relay starts with runtime configuration that binds the manifest's logical datasets and entities to actual data sources. Clients reach entity routes, metadata routes, and evidence-offering endpoints through configured authentication. Relay records a `Data-Purpose` header in audit envelopes where present. On governed runtime routes, Relay evaluates the supported Relay PDP profile before disclosure and applies redaction when the decision permits only a minimized response. 5. **Access-token issuance.** Where a deployment has no identity provider of its own, Registry Mint issues the short-lived access token the caller presents. A registered client authenticates with a `private_key_jwt` client assertion, and Mint reads the token's authority claims from its server-side client registry. A deployment that already runs an identity provider skips this step entirely. -6. **Assertion.** Evidence authenticates the caller's access token against its one trusted issuer, matches exactly one authority path, evaluates one predefined requirement over its own fixed bounded sources, and returns one signed minimum-disclosure assertion. Caller identity and authorization details may authorize or parameterize the request, but do not become evidence. The response carries the answer the requirement defines, not the source record behind it. +6. **Assertion.** Evidence Gateway authenticates the caller's access token against its one trusted issuer, matches exactly one authority path, evaluates one predefined requirement over its own fixed bounded sources, and returns one signed minimum-disclosure assertion. Caller identity and authorization details may authorize or parameterize the request, but do not become evidence. The response carries the answer the requirement defines, not the source record behind it. ## 5. Architectural invariants @@ -191,23 +191,23 @@ REQ-ARC-G-002: A metadata manifest (schema `registry-manifest/v1`) MUST NOT incl REQ-ARC-G-003: In v1, runtime services MUST NOT expose source-registry data mutation routes. Consultation APIs are read-only. -REQ-ARC-G-004: Every request that touches person-level data MUST be audited. Registry Platform provides the audit envelope primitives, verified to exist in the shared crate; Registry Relay and Evidence MUST compose those primitives on routes that return person-level records or evidence assertions. This requirement states an invariant a conforming deployment meets; it is not a claim that every route in a given build has been individually audited. +REQ-ARC-G-004: Every request that touches person-level data MUST be audited. Registry Platform provides the audit envelope primitives, verified to exist in the shared crate; Registry Relay and Evidence Gateway MUST compose those primitives on routes that return person-level records or evidence assertions. This requirement states an invariant a conforming deployment meets; it is not a claim that every route in a given build has been individually audited. -REQ-ARC-G-005: A primitive that must behave identically across runtime services (authentication, OIDC, audit, HTTP security, outbound HTTP policy, cryptography, SD-JWT VC helpers) SHOULD be sourced from Registry Platform rather than reimplemented in Registry Relay, Evidence, or Registry Mint. This keeps cross-service security behavior consistent and auditable in one place. +REQ-ARC-G-005: A primitive that must behave identically across runtime services (authentication, OIDC, audit, HTTP security, outbound HTTP policy, cryptography, SD-JWT VC helpers) SHOULD be sourced from Registry Platform rather than reimplemented in Registry Relay, Evidence Gateway, or Registry Mint. This keeps cross-service security behavior consistent and auditable in one place. REQ-ARC-G-006: Registry Relay MUST own the runtime binding between manifest logical concepts and data sources. The manifest schema and its renderers are owned by Registry Manifest; Registry Relay MUST NOT define or version the manifest format. -REQ-ARC-G-007: Evidence MUST own requirement evaluation, disclosure shape, and assertion signing. Registry Relay MUST NOT evaluate a requirement or sign an evidence assertion. This boundary does not prohibit Registry Relay from enforcing runtime access, freshness, and redaction policy for its own governed consultation routes. +REQ-ARC-G-007: Evidence Gateway MUST own requirement evaluation, disclosure shape, and assertion signing. Registry Relay MUST NOT evaluate a requirement or sign an evidence assertion. This boundary does not prohibit Registry Relay from enforcing runtime access, freshness, and redaction policy for its own governed consultation routes. REQ-ARC-G-010: The portable metadata layer describes; it does not authorize and it does not assert facts about live data. Publishing a dataset, schema, policy, evidence offering, ecosystem binding, or federation relationship in a discovery artifact MUST NOT be construed as granting access to it, as enforcing it, or as asserting that any particular record exists or satisfies it. Access control, governed PDP enforcement, and the existence or value of a record are determined only by an authorized runtime read under runtime configuration and trusted request or source context. A published ODRL policy is descriptive until a runtime service explicitly binds it into an enforced, supported profile. A conformance claim against a metadata artifact MUST NOT imply a runtime guarantee that the runtime layer has not made. -REQ-ARC-G-011: Where Registry Relay exposes governed runtime routes, it MUST enforce only the supported Evidence Gateway PDP profile (`registry-evidence-gateway-pdp/v1`) as implemented by the runtime stack. A conformance claim against this specification MUST NOT imply full Evidence Gateway interoperability, full OID4VCI issuer behavior, dynamic external policy discovery, or enforcement of ODRL terms outside the supported profile. +REQ-ARC-G-011: Where Registry Relay exposes governed runtime routes, it MUST enforce only the supported Relay PDP profile (`registry-evidence-gateway-pdp/v1`) as implemented by the runtime stack. A conformance claim against this specification MUST NOT imply interoperability with Evidence Gateway, full OID4VCI issuer behavior, dynamic external policy discovery, or enforcement of ODRL terms outside the supported profile. -REQ-ARC-G-014: Evidence MUST return only the answer its predefined requirement defines, never the source record behind that answer. The response MUST be constructed by the service core after the complete declared concept set has been produced and validated; configured bundle logic MUST NOT construct a response envelope, a subject identifier, or any claim outside that declared set. +REQ-ARC-G-014: Evidence Gateway MUST return only the answer its predefined requirement defines, never the source record behind that answer. The response MUST be constructed by the service core after the complete declared concept set has been produced and validated; configured bundle logic MUST NOT construct a response envelope, a subject identifier, or any claim outside that declared set. -REQ-ARC-G-015: A signed Evidence response MUST be a flattened JWS JSON document over the exact evidence payload, and a signing failure MUST fail closed rather than release unsigned output. Where a deployment enables the SD-JWT VC serialization (`application/dc+sd-jwt`), that serialization MUST project the identical payload and MUST NOT be read as a credential lifecycle: Evidence Version 1 defines no issuance session, no holder-binding ceremony, no status list, no revocation, and no presentation verification. +REQ-ARC-G-015: A signed Evidence Gateway response MUST be a flattened JWS JSON document over the exact evidence payload, and a signing failure MUST fail closed rather than release unsigned output. Where a deployment enables the SD-JWT VC serialization (`application/dc+sd-jwt`), that serialization MUST project the identical payload and MUST NOT be read as a credential lifecycle: Evidence Gateway Version 1 defines no issuance session, no holder-binding ceremony, no status list, no revocation, and no presentation verification. -REQ-ARC-G-016: The dependency between Registry Mint and a resource server MUST run one way. Registry Mint issues an access token that a resource server such as Evidence verifies as an ordinary OIDC access token; Evidence MUST NOT depend on Registry Mint, and a deployment that already operates an identity provider MUST be able to run Evidence without Registry Mint. +REQ-ARC-G-016: The dependency between Registry Mint and a resource server MUST run one way. Registry Mint issues an access token that a resource server such as Evidence Gateway verifies as an ordinary OIDC access token; Evidence Gateway MUST NOT depend on Registry Mint, and a deployment that already operates an identity provider MUST be able to run Evidence Gateway without Registry Mint. REQ-ARC-G-008, REQ-ARC-G-009, REQ-ARC-G-012, and REQ-ARC-G-013 are retired. Each constrained the retired `registry-notary` component's credential format, federation topology, issuance provenance, or state ownership, so no component in this stack implements them. Per RS-DOC REQ-DOC-008 the identifiers are not reused and are not reassigned to the requirements added in this version. @@ -219,7 +219,7 @@ The two-layer design supports one natural capability sequence: describe what the **Expose.** Registry Relay binds the manifest artifacts to actual data sources and exposes protected, read-only consultation APIs. A file, an extract, a database, or a legacy registry gains a governed API without replacing the source. -**Assert.** Evidence evaluates one predefined requirement over its own configured sources and returns +**Assert.** Evidence Gateway evaluates one predefined requirement over its own configured sources and returns one signed assertion a caller can present to a verifier. The assertion is narrower than the source record by construction: it carries the answer the requirement defines and nothing else. @@ -240,22 +240,22 @@ An implementation conforms to this specification when it respects the following - REQ-ARC-G-004: every request touching person-level data produces an audit record. - REQ-ARC-G-005: shared security primitives that must behave identically across services are sourced from Registry Platform (recommended). - REQ-ARC-G-006: Registry Relay owns runtime binding; the manifest format is owned by Registry Manifest. -- REQ-ARC-G-007: requirement evaluation and assertion signing are owned by Evidence. +- REQ-ARC-G-007: requirement evaluation and assertion signing are owned by Evidence Gateway. - REQ-ARC-G-010: discovery artifacts are treated as description, not as authorization, enforcement, or proof that a record exists. -- REQ-ARC-G-011: governed Relay runtime routes enforce only the supported Evidence Gateway PDP profile and do not imply broader interoperability. -- REQ-ARC-G-014: an Evidence response carries the defined answer and not the source record behind it. +- REQ-ARC-G-011: governed Relay runtime routes enforce only the supported Relay PDP profile and do not imply broader interoperability. +- REQ-ARC-G-014: an Evidence Gateway response carries the defined answer and not the source record behind it. - REQ-ARC-G-015: a signed response is a flattened JWS JSON document, signing failure fails closed, and the SD-JWT VC serialization projects the same payload without adding a credential lifecycle. -- REQ-ARC-G-016: the Registry Mint dependency runs one way, and Evidence runs without Registry Mint where an identity provider already exists. +- REQ-ARC-G-016: the Registry Mint dependency runs one way, and Evidence Gateway runs without Registry Mint where an identity provider already exists. Conformance to this specification does not imply conformance to any external standard cited in the `standards_referenced` frontmatter field. Each standard's adoption mode and scope are documented in the [standards register](../../reference/standards/). -## Evidence +## Evidence Gateway This specification is `verified`: it is distilled from published artifacts a reader can inspect, per RS-DOC REQ-DOC-014. - The [boundary map](../../map/boundaries-and-map/) records each component's boundaries with their source citations. It is the primary distillation source for the components (Section 3) and the invariants (Section 5). - The [architecture overview](../../explanation/architecture/) gives the narrative data and contract flow that Section 4 makes precise. -- The [Registry Relay](../../reference/apis/registry-relay/) and [Evidence](../../reference/apis/registry-evidence/) API references show the runtime surfaces named in Section 3. +- The [Registry Relay](../../reference/apis/registry-relay/) and [Evidence Gateway](../../reference/apis/registry-evidence/) API references show the runtime surfaces named in Section 3. - The [Registry Mint reference](../../reference/mint/) records the token issuer described in Section 3. - The [standards register](../../reference/standards/) records the adoption mode for each standard listed in `standards_referenced`. @@ -264,4 +264,4 @@ This specification is `verified`: it is distilled from published artifacts a rea - [RS-DOC](../rs-doc/) defines the documentation framework this specification conforms to. - [RS-TERMS](../rs-terms/) defines the shared vocabulary the other specifications use. - [Architecture overview](../../explanation/architecture/) is the narrative explanation with a worked data flow and capability table. -- [RS-PR-EVIDENCE](../rs-pr-evidence/) defines the protocol surface of the Evidence service this architecture places. +- [RS-PR-EVIDENCE](../rs-pr-evidence/) defines the protocol surface of the Evidence Gateway service this architecture places. diff --git a/docs/site/src/content/docs/spec/rs-dm-manifest.mdx b/docs/site/src/content/docs/spec/rs-dm-manifest.mdx index 01ba6cc36..102733b59 100644 --- a/docs/site/src/content/docs/spec/rs-dm-manifest.mdx +++ b/docs/site/src/content/docs/spec/rs-dm-manifest.mdx @@ -55,7 +55,7 @@ This specification covers the structure and invariants of a portable metadata ma - The catalog and the top-level collections that describe a registry. - Reference integrity and identifier and vocabulary constraints. - Requirements and grouped evidence. -- Governed evidence pack metadata and the Evidence Gateway PDP binding surface. +- Governed evidence pack metadata and the Relay PDP binding surface. - Evidence-offering access discovery metadata. - The standards-shaped render set and the static discovery bundle. - Compatibility and evolution. @@ -77,7 +77,7 @@ flowchart TD manifest["metadata.yaml
schema_version: registry-manifest/v1"] catalog["Catalog
id · base_url · title · publisher"] describe["Description
datasets · entities · fields · requirements
evidence types · services · forms · policies · codelists"] - offerings["Evidence offerings
access.kind · endpoint · discovery · ruleset"] + offerings["Evidence Gateway offerings
access.kind · endpoint · discovery · ruleset"] render["Validate, then render
(pure · deterministic · no data sources)"] bundle["Discovery bundle
DCAT · BRegDCAT-AP · CPSV-AP · SHACL
JSON Schema · OGC Records · ODRL · CCCEV
embedded SKOS-shaped codelists"] index["index.json
source_manifest_digest · package_digest · per-artifact sha256"] @@ -118,13 +118,13 @@ REQ-DM-MANIFEST-006: An evidence type MUST prove at least one requirement define ## 6. Governed evidence gateway metadata -A manifest can publish governed evidence metadata for an Evidence Gateway runtime to select a policy decision point (PDP) policy. This is still metadata: Registry Manifest validates the pack shape, policy identity, hash binding, supported ODRL enforcement terms, and required evidence-pack declarations, while runtime enforcement remains with Registry Relay's governed PDP path. +A manifest can publish governed evidence metadata for a Relay runtime to select a policy decision point (PDP) policy. This is still metadata: Registry Manifest validates the pack shape, policy identity, hash binding, supported ODRL enforcement terms, and required evidence-pack declarations, while runtime enforcement remains with Registry Relay's governed PDP path. REQ-DM-MANIFEST-007: Where an `ecosystem_bindings` entry declares `type: governed-evidence`, it MUST carry `id` and `version` values whose `(id, version)` pair is unique among the manifest's ecosystem bindings, a non-empty `profile`, and `evidence_pack` metadata. The evidence pack MUST declare `pack_id`, `pack_version`, `source_basis`, `semantic_profile`, `evidence_envelope`, `required_gates`, `allowed_outputs`, `policy_id`, `policy_hash`, and `odrl_enforcement`. `source_basis`, `semantic_profile`, `evidence_envelope`, `source_mapping`, `policy`, fixtures, and synthetic data remain JSON metadata values where the manifest validates presence and object shape where implemented; this requirement MUST NOT be read as a fully typed evidence-pack metadata model. REQ-DM-MANIFEST-008: A governed evidence pack MUST bind runtime policy selection to a policy identity and digest: `policy_id` MUST be non-empty, `policy_hash` MUST be a lowercase `sha256:` digest, and, when an inline `policy` object is present, Registry Manifest MUST verify `policy_hash` against the canonical JSON form of that inline policy. `required_gates` MUST include the gateway gates Registry Manifest requires for governed evidence, including source freshness, source binding, route scope, requester and subject identity, assurance, legal basis, consent, jurisdiction, requested disclosure, credential format, authority basis, and subject relationship. `allowed_outputs` MUST include `minimized_json`. -REQ-DM-MANIFEST-009: A governed evidence pack MUST declare `odrl_enforcement.profile: registry-evidence-gateway-pdp/v1`, and its `constraint_terms` MUST contain at least one unique term from the profile vocabulary: `odrl:purpose` and `odrl:spatial`. The wider manifest policy renderer MAY publish broader Open Digital Rights Language (ODRL) metadata, but a governed evidence pack MUST NOT claim PDP enforcement for ODRL terms outside this profile vocabulary. A runtime service MAY support only a subset of the profile vocabulary; Registry Relay currently enforces `odrl:purpose` and denies `odrl:spatial` fail-closed. +REQ-DM-MANIFEST-009: A governed evidence pack MUST declare `odrl_enforcement.profile: registry-evidence-gateway-pdp/v1`, and its `constraint_terms` MUST contain at least one unique term from the profile vocabulary: `odrl:purpose` and `odrl:spatial`. This legacy identifier names a Relay PDP profile and has no connection to the Evidence Gateway product. The wider manifest policy renderer MAY publish broader Open Digital Rights Language (ODRL) metadata, but a governed evidence pack MUST NOT claim PDP enforcement for ODRL terms outside this profile vocabulary. A runtime service MAY support only a subset of the profile vocabulary; Registry Relay currently enforces `odrl:purpose` and denies `odrl:spatial` fail-closed. ## 7. Evidence-offering access discovery metadata @@ -169,7 +169,7 @@ These constraints are stated so a reader does not infer an invariant the reviewe - **Library callers own untrusted-input resource limits.** The command-line path may impose its own input limits, but callers that embed Registry Manifest as a library and accept manifests from untrusted parties still need request size, nesting, collection-count, and time limits appropriate to their service boundary. Manifest validation is not a general resource sandbox. - **The access checks are keyed to one access kind and validate shape, not reachability.** They apply only where the manifest declares `access.kind: registry-evidence`. A `conforms_to` value or a well-formed HTTPS URL alone must not be treated by consumers as proof that an endpoint is live, that it returns the named profile, or that the endpoint set is safe to trust. Manifest validation does not fetch either URL. - **Publication provenance depends on a clean destination.** The `package_digest` pins the artifact inventory it sees. It is not proof that every file was created by the current publish invocation if the output directory already contained local files. -- **Evidence pack metadata remains partly opaque.** Governed evidence packs require key metadata and validate selected object shapes, supported gate names, supported output names, policy digest shape, inline-policy digest binding, and supported ODRL enforcement terms. The implementation still represents several fields as JSON values rather than a fully typed external evidence-pack schema (REQ-DM-MANIFEST-007 through REQ-DM-MANIFEST-009). +- **Evidence Gateway pack metadata remains partly opaque.** Governed evidence packs require key metadata and validate selected object shapes, supported gate names, supported output names, policy digest shape, inline-policy digest binding, and supported ODRL enforcement terms. The implementation still represents several fields as JSON values rather than a fully typed external evidence-pack schema (REQ-DM-MANIFEST-007 through REQ-DM-MANIFEST-009). - **Profile fixtures are non-normative.** The example profiles shipped with Registry Manifest are illustrative until reviewed against official artifacts; they are not authoritative profiles for any named external system (see the [profile fixtures guide](../../products/registry-manifest/profile-fixtures/)). ## Conformance @@ -190,7 +190,7 @@ A metadata manifest, and the Registry Manifest tooling that validates and render Conformance to this specification does not imply conformance to any external standard cited in the `standards_referenced` frontmatter field. Each standard's adoption mode and scope are documented in the [standards register](../../reference/standards/). -## Evidence +## Evidence Gateway This specification is `verified`: every requirement describes shipped behavior a reader can inspect, per RS-DOC REQ-DOC-014. diff --git a/docs/site/src/content/docs/spec/rs-doc.mdx b/docs/site/src/content/docs/spec/rs-doc.mdx index 1bdccb307..7984f26f3 100644 --- a/docs/site/src/content/docs/spec/rs-doc.mdx +++ b/docs/site/src/content/docs/spec/rs-doc.mdx @@ -90,7 +90,7 @@ A specification's canonical metadata is its frontmatter. The register surfaces i - `normative` defines required behavior. Its MUST and SHOULD statements bind. - `informative` explains, motivates, or illustrates. It binds nothing. -**Evidence** is how true the document is against shipped code: +**Evidence Gateway** is how true the document is against shipped code: - `verified` is backed by code, tests, fixtures, or generated artifacts that a reader can inspect. A `verified` document carries evidence references to those artifacts (REQ-DOC-014); a claim a reader cannot trace to one is not `verified`. - `partial` mixes shipped behavior with target behavior. The document marks which sections are which. @@ -152,7 +152,7 @@ REQ-DOC-013: When a specification is superseded, its `status` becomes `historica A document conforms to RS-DOC when it: is a distilled public contract, not copied internal evidence (REQ-DOC-001); carries a unique, well-formed `doc_id` and the `category` and `evidence` axes (REQ-DOC-004, REQ-DOC-006); states its evidence honestly, including the unbuilt case (REQ-DOC-007); backs a `verified` evidence level with evidence references (REQ-DOC-014); carries a version-history table that records normative changes (REQ-DOC-012); and interprets normative keywords per Section 2. The frontmatter check enforces the mechanical requirements; the rest is a review responsibility. -## Evidence +## Evidence Gateway This specification is `verified`: the mechanisms it defines exist and run, and a reader can inspect them. diff --git a/docs/site/src/content/docs/spec/rs-op-posture.mdx b/docs/site/src/content/docs/spec/rs-op-posture.mdx index ca18d05df..b9e51e2a1 100644 --- a/docs/site/src/content/docs/spec/rs-op-posture.mdx +++ b/docs/site/src/content/docs/spec/rs-op-posture.mdx @@ -52,7 +52,7 @@ semantic producer validation, and evolution rules that JSON Schema alone does no | 0.1.2 | 2026-07-20 | draft | Replaced waiver reason text with validated operator references and optional summaries before the 1.0 schema freeze. | | 0.1.3 | 2026-07-23 | draft | Reserved credential-shaped waiver-reference prefixes before the 1.0 schema freeze. | | 0.1.4 | 2026-07-24 | draft | Separated portable waiver-schema checks from contextual semantic validation before the 1.0 schema freeze. | -| 0.1.5 | 2026-08-03 | draft | Recorded that Registry Notary is retired and that no supported deployment produces a `registry-notary` document, while the frozen v1 shape and the consumer validation path for one are unchanged. Stated that Evidence and Registry Mint expose no posture endpoint. | +| 0.1.5 | 2026-08-03 | draft | Recorded that Registry Notary is retired and that no supported deployment produces a `registry-notary` document, while the frozen v1 shape and the consumer validation path for one are unchanged. Stated that Evidence Gateway and Registry Mint expose no posture endpoint. | ## 1. Scope and surface @@ -68,9 +68,9 @@ contract also models a second, retired component: no supported deployment emits `registry-notary` document, and the shape is kept only so a consumer can still validate one it has retained. -Evidence and Registry Mint expose no `/admin/v1/posture` route and emit no posture document. An -operator observes an Evidence process through its unauthenticated liveness and readiness probes -and, where the deployment enables it, through the optional metrics listener that Evidence binds +Evidence Gateway and Registry Mint expose no `/admin/v1/posture` route and emit no posture document. An +operator observes an Evidence Gateway process through its unauthenticated liveness and readiness probes +and, where the deployment enables it, through the optional metrics listener that Evidence Gateway binds to a private address and that serves only `GET /metrics`. Registry Mint likewise exposes liveness and readiness probes only. Neither service is in scope for the requirements in this specification. @@ -295,7 +295,7 @@ A consumer conforms when it validates and dispatches by schema, enforces compone handles omissions as unreported, and does not elevate posture observations into proof or authority (REQ-OP-POSTURE-002, REQ-OP-POSTURE-003, REQ-OP-POSTURE-007, and REQ-OP-POSTURE-009). -## Evidence +## Evidence Gateway This specification is `verified`: its document shape, examples, component pairing, and tier filter are shipped in Registry Platform and exercised by contract tests. @@ -310,7 +310,7 @@ filter are shipped in Registry Platform and exercised by contract tests. - The [Registry Relay admin handler](https://github.com/registrystack/registry-stack/blob/c84b1b9288b925e7c9cc89c47c33cc1f50753d8c/crates/registry-relay/src/api/admin.rs) selects the requested tier and returns the shared posture document (Sections 1, 4, and 6). It is the only producer this specification recognizes. -- The Evidence and Registry Mint routers (`crates/registry-evidence/src/server.rs` and +- The Evidence Gateway and Registry Mint routers (`crates/registry-evidence/src/server.rs` and `crates/registry-mint/src/server.rs`) expose liveness and readiness probes and no posture route, which Section 1 states. @@ -319,7 +319,7 @@ filter are shipped in Registry Platform and exercised by contract tests. - [Harden a production deployment](../../security/hardening-checklist/) explains how an operator uses posture findings while preparing a deployment. - [Registry Relay protocol](../rs-pr-relay/) defines the Relay admin-surface boundary. -- [RS-PR-EVIDENCE](../rs-pr-evidence/) defines the Evidence service surface, which carries no +- [RS-PR-EVIDENCE](../rs-pr-evidence/) defines the Evidence Gateway service surface, which carries no posture endpoint. - [RS-SEC-G](../rs-sec-g/) defines the security model and the operator boundary this observation helps inspect. diff --git a/docs/site/src/content/docs/spec/rs-pr-evidence.mdx b/docs/site/src/content/docs/spec/rs-pr-evidence.mdx index 4cdcdc191..6739f3cf2 100644 --- a/docs/site/src/content/docs/spec/rs-pr-evidence.mdx +++ b/docs/site/src/content/docs/spec/rs-pr-evidence.mdx @@ -1,6 +1,6 @@ --- -title: "RS-PR-EVIDENCE: Evidence protocol" -description: "The normative HTTP protocol contract for Evidence: discovery, authentication, assurance profiles, the closed request contract, acceptance definitions, minimum disclosure, response formats, problem reporting, audit gates, and immutable deployment input." +title: "RS-PR-EVIDENCE: Evidence Gateway protocol" +description: "The normative HTTP protocol contract for Evidence Gateway: discovery, authentication, assurance profiles, the closed request contract, acceptance definitions, minimum disclosure, response formats, problem reporting, audit gates, and immutable deployment input." status: draft owner: registry-docs source_repos: @@ -24,11 +24,11 @@ audience: - specification editor --- -This document defines the HTTP protocol contract that Evidence exposes: how a caller authenticates, +This document defines the HTTP protocol contract that Evidence Gateway exposes: how a caller authenticates, discovers the request shapes it may invoke, submits one closed request against a predefined requirement, and receives the smallest sufficient assertion in an authorized response format, plus the problem, audit, and configuration-immutability behavior every request carries. -Evidence is a minimum-disclosure assertion service over data institutions already hold. +Evidence Gateway is a minimum-disclosure assertion service over data institutions already hold. It returns the answer a requirement asks for, not the record behind it. Every requirement statement in this document restates a frozen Version 1 contract that lives in the @@ -37,20 +37,20 @@ The contract files are the source of truth; this document is their protocol-leve Where a contract carries a numeric limit, a field name, or an enumerated value, this document points at the file rather than copying the value, so the two cannot drift apart. -Evidence is a separate product from Registry Relay. -It is the Evidence counterpart to [RS-PR-RELAY](../rs-pr-relay/), and it is not a Registry Relay +Evidence Gateway is a separate product from Registry Relay. +It is the Evidence Gateway counterpart to [RS-PR-RELAY](../rs-pr-relay/), and it is not a Registry Relay mode, rewrite, or reduced configuration (`products/evidence/README.md`). The key words in this document are interpreted per [RS-DOC](../rs-doc/) Section 2. Defined terms are used per [RS-TERMS](../rs-terms/). -{/* RS-ARC-G 0.6.0 places Evidence in the architecture as its own component and states its +{/* RS-ARC-G 0.6.0 places Evidence Gateway in the architecture as its own component and states its boundary in REQ-ARC-G-007, REQ-ARC-G-014, and REQ-ARC-G-015. This document still does not claim to refine a numbered RS-ARC-G requirement; adding that mapping is a separate normative decision. */} {/* TODO[evidence]: src/data/standards.yaml records sd-jwt-vc, cccev, openapi, and json-schema - without listing registry-evidence under `used_by`. The register entries need an Evidence row + without listing registry-evidence under `used_by`. The register entries need an Evidence Gateway row before this page's standards claims are traceable from the register itself. */} ## Version history @@ -58,12 +58,12 @@ Defined terms are used per [RS-TERMS](../rs-terms/). | Version | Date | Status | Change | | --- | --- | --- | --- | | 0.1.0 | 2026-08-03 | draft | Initial profile derived from the frozen V1 contracts. | -| 0.2.0 | 2026-08-04 | draft | Registry Notary is retired. Removed the RS-PR-NOTARY relationship statements and the `registry-notary*` dependency prohibition, and recorded that RS-ARC-G 0.6.0 now places Evidence in the architecture. | +| 0.2.0 | 2026-08-04 | draft | Registry Notary is retired. Removed the RS-PR-NOTARY relationship statements and the `registry-notary*` dependency prohibition, and recorded that RS-ARC-G 0.6.0 now places Evidence Gateway in the architecture. | | 0.3.0 | 2026-08-05 | draft | Added the governed assurance-profile boundary, corrected the evaluation pipeline and three-format response surface, and specified bounded startup verification plus complete out-of-band verification for segmented audit history. | ## 1. Scope and references -This specification covers Evidence's externally observable protocol behavior: +This specification covers Evidence Gateway's externally observable protocol behavior: - The service surface, the generated OpenAPI document, and requester-scoped definition discovery. - Authentication of callers and the single authorization decision that gates a request. @@ -92,7 +92,7 @@ This specification does not define: - Verifier procedure: The relying-party policy document and the offline `evidence verify` command are specified by `products/evidence/contracts/verification-policy.schema.yaml`. -Evidence Version 1 has explicit non-goals, recorded in +Evidence Gateway Version 1 has explicit non-goals, recorded in `products/evidence/contracts/README.md` and `products/evidence/README.md`. It stops before documents, credential issuance protocols and credential lifecycle, status lists and revocation, OpenID for Verifiable Credential Issuance (OID4VCI) in any part, presentation-side @@ -101,12 +101,12 @@ challenges, federation, delegated agents, workflow, public or federated catalogs mutation, source planning, multi-source fulfillment, and an application database. The SD-JWT VC output is a second encoding of one stateless assertion under a frozen profile; it is never a credential lifecycle. -Registry Relay's protocol is specified by RS-PR-RELAY; it does not govern Evidence, and Evidence +Registry Relay's protocol is specified by RS-PR-RELAY; it does not govern Evidence Gateway, and Evidence Gateway inherits no requirement from it. ## 2. Service surface and discovery -Evidence is one `registry-evidence` crate, one `evidence` binary, one serving process, and one +Evidence Gateway is one `registry-evidence` crate, one `evidence` binary, one serving process, and one operator-controlled trust domain (`products/evidence/README.md`). REQ-PR-EVIDENCE-001: The reachable HTTP surface MUST be exactly the operations declared in @@ -135,7 +135,7 @@ governed verifier configuration (`products/evidence/contracts/jws-profile.yaml`, ## 3. Authentication and authorization -Evidence runs one authentication kind, `oidc-access-token`, whose issuer, audiences, accepted token +Evidence Gateway runs one authentication kind, `oidc-access-token`, whose issuer, audiences, accepted token types, algorithms, JWKS URI, and claim paths are fixed in the immutable bundle (`products/evidence/contracts/bundle.schema.yaml`). @@ -195,7 +195,7 @@ Preparation, extraction, derivation, source transport, and concept projection ar REQ-PR-EVIDENCE-014: Every request MUST carry one request nonce in the canonical form fixed by `products/evidence/contracts/request.schema.yaml`, generated independently per request by a cryptographically secure random source. -Evidence MUST echo it into the assertion payload and cover it by the signature, and MUST NOT store +Evidence Gateway MUST echo it into the assertion payload and cover it by the signature, and MUST NOT store it, uniqueness-check it, or expose it to authorization, rate limits, scripts, source requests, logs, metrics, traces, or native audit (invariant `V1-I27`). Nonce reuse is not rejected, so the nonce is transaction binding only for a relying party that @@ -252,7 +252,7 @@ configuration and executed only by the core REQ-PR-EVIDENCE-019: Provider lookup MUST return only the closed union of match, no-match, and ambiguous outcomes, and only a match MAY carry facts. -Evidence MUST NOT expose or choose candidates, and MUST NOT emit candidate counts, scores, +Evidence Gateway MUST NOT expose or choose candidates, and MUST NOT emit candidate counts, scores, confidence, hints, diagnostics, or comparisons (`products/evidence/contracts/rhai-abi.yaml`, invariant `V1-I10`). @@ -307,7 +307,7 @@ combined disclosure review (`products/evidence/OPERATOR-CONTRACT.md`). ## 7. Response formats and signing -Evidence releases one stateless assertion. +Evidence Gateway releases one stateless assertion. The bundle-level and grant-level `responseFormats` permission decides which serializations may carry it (`products/evidence/contracts/bundle.schema.yaml`). @@ -393,7 +393,7 @@ before serialization. The issuer MUST NOT append a key-binding JWT. REQ-PR-EVIDENCE-040: A holder confirmation claim MUST be present only when the caller supplied a -holder public key in the request, and Evidence MUST NOT validate a presentation. +holder public key in the request, and Evidence Gateway MUST NOT validate a presentation. The accepted key type and the prohibited private members are fixed by `products/evidence/contracts/request.schema.yaml` and `products/evidence/contracts/sd-jwt-vc-profile.yaml`; a key carrying any private member, a @@ -433,7 +433,7 @@ source content. ## 9. Audit behavior -REQ-PR-EVIDENCE-046: Evidence MUST durably accept an access-attempt event after authorization and +REQ-PR-EVIDENCE-046: Evidence Gateway MUST durably accept an access-attempt event after authorization and before credential acquisition or source access, and a disclosure-release event after the final immutable response bytes are serialized and before those exact bytes are released. A sink failure MUST block the applicable step @@ -456,11 +456,11 @@ and comparisons, and script inputs, outputs, or signing material. Identity MUST travel only as domain-separated keyed pseudonyms (invariant `V1-I15`). REQ-PR-EVIDENCE-050: Authentication, unmatched-authority, and invalid-selector failures occur before -a privacy-safe authority and complete selector bundle exist, so Evidence MUST NOT fabricate a native +a privacy-safe authority and complete selector bundle exist, so Evidence Gateway MUST NOT fabricate a native event from that untrusted or protected request material (`products/evidence/contracts/audit-event.schema.yaml`). -REQ-PR-EVIDENCE-051: At startup and after restart, Evidence MUST recover the prior chain head from +REQ-PR-EVIDENCE-051: At startup and after restart, Evidence Gateway MUST recover the prior chain head from the newest sealed segment, when one exists, and MUST verify the complete active segment from that head before serving. Startup and readiness MUST NOT rescan sealed history. @@ -476,7 +476,7 @@ serving-process startup or readiness ## 10. Immutability of deployment input REQ-PR-EVIDENCE-052: Configuration MUST be immutable for the serving process lifetime. -Evidence MUST load one read-only atomic governed bundle and one separately digested closed runtime +Evidence Gateway MUST load one read-only atomic governed bundle and one separately digested closed runtime file at startup; runtime override, reload, merge, fallback, and mutation paths MUST NOT exist (invariant `V1-I18`, `products/evidence/contracts/runtime.schema.yaml`). @@ -548,7 +548,7 @@ credential format that the frozen Version 1 contracts do not provide. never a fallback from a signed-path failure (REQ-PR-EVIDENCE-036). - Signature meaning: Provider authentication and payload integrity only, not legal-signature status, source truth, or holder possession (REQ-PR-EVIDENCE-035). -- Identity resolution: Lookup is match, no-match, or ambiguous. Evidence is not an +- Identity resolution: Lookup is match, no-match, or ambiguous. Evidence Gateway is not an identity-resolution engine and returns no candidate material (REQ-PR-EVIDENCE-019). - Purpose attestation: A declared purpose is an authorized selection from the granted set, not an identity-provider attestation, unless the operator issues a distinct requester tag per purpose @@ -571,14 +571,14 @@ credential format that the frozen Version 1 contracts do not provide. - Platform: Version 1 supports Unix targets only, because its secret and audit invariants require owner, mode, no-follow, link-count, and file-identity guarantees (`products/evidence/contracts/runtime.schema.yaml`). -- Standards claims: The CCCEV alignment is a documented mapping with explicit Evidence extensions, +- Standards claims: The CCCEV alignment is a documented mapping with explicit Evidence Gateway extensions, and the SD-JWT VC output follows a frozen local profile (`products/evidence/contracts/cccev-field-mapping.yaml`, `products/evidence/contracts/sd-jwt-vc-profile.yaml`). ## Conformance -An Evidence deployment conforms to this specification when it: +An Evidence Gateway deployment conforms to this specification when it: - exposes only the generated OpenAPI surface, keeps definition discovery authenticated and requester-scoped, grants no authority through discovery, and publishes key material as @@ -637,7 +637,7 @@ Conformance to this specification does not imply conformance to any external sta Each standard's adoption mode and scope are documented in the [standards register](../../reference/standards/). -## Evidence +## Evidence Gateway This specification is `verified`: its requirements cite inspectable frozen contracts, generated artifacts, implementation tests, or operator material, per RS-DOC REQ-DOC-014. @@ -671,7 +671,7 @@ that evidence gap remains marked with an author comment in the source of this pa ## Next -- [Registry Evidence API reference](../../reference/apis/registry-evidence/) is the route-level +- [Evidence Gateway API reference](../../reference/apis/registry-evidence/) is the route-level reference and the link to the generated OpenAPI document. - [RS-ARC-G](../rs-arc-g/) places the registry stack services in one architecture. - [RS-SEC-G](../rs-sec-g/) holds the cross-product security model this protocol sits inside. diff --git a/docs/site/src/content/docs/spec/rs-pr-registryctl.mdx b/docs/site/src/content/docs/spec/rs-pr-registryctl.mdx index 863c61572..a034725fd 100644 --- a/docs/site/src/content/docs/spec/rs-pr-registryctl.mdx +++ b/docs/site/src/content/docs/spec/rs-pr-registryctl.mdx @@ -294,7 +294,7 @@ A Registryctl release conforms to this specification when it: - Preserves authorization-before-source and refuses non-Relay claim evidence (REQ-PR-REGISTRYCTL-030 and REQ-PR-REGISTRYCTL-031). -## Evidence +## Evidence Gateway This specification is `verified`: the requirements describe implemented behavior with automated tests. diff --git a/docs/site/src/content/docs/spec/rs-pr-relay.mdx b/docs/site/src/content/docs/spec/rs-pr-relay.mdx index 95e54d64e..319493613 100644 --- a/docs/site/src/content/docs/spec/rs-pr-relay.mdx +++ b/docs/site/src/content/docs/spec/rs-pr-relay.mdx @@ -32,7 +32,7 @@ audience: - specification editor --- -This document defines the HTTP protocol contract that Registry Relay exposes: the configuration-driven service model that fixes a gateway's surface, how a caller authenticates and is scoped per dataset, how governed Evidence Gateway PDP enforcement applies to configured read routes, the consultation and aggregate routes that read configured sources, the scope-filtered metadata publication, the evidence-offering descriptors, the boundary that keeps credential issuance out of Relay, and the audit and error behavior every request carries. It is the precise, citable version of the behavior the [Registry Relay API reference](../../reference/apis/registry-relay/) describes narratively. +This document defines the HTTP protocol contract that Registry Relay exposes: the configuration-driven service model that fixes a gateway's surface, how a caller authenticates and is scoped per dataset, how governed Relay PDP enforcement applies to configured read routes, the consultation and aggregate routes that read configured sources, the scope-filtered metadata publication, the evidence-offering descriptors, the boundary that keeps credential issuance out of Relay, and the audit and error behavior every request carries. It is the precise, citable version of the behavior the [Registry Relay API reference](../../reference/apis/registry-relay/) describes narratively. It refines the Registry Relay component defined in [RS-ARC-G](../rs-arc-g/) Section 3 (specifically REQ-ARC-G-003, REQ-ARC-G-004, REQ-ARC-G-006, and REQ-ARC-G-007) one level of detail down, from architectural boundary to wire behavior. Where this document and RS-ARC-G state the same constraint, RS-ARC-G is the general invariant and this document is its protocol-level form. @@ -43,7 +43,7 @@ The key words in this document are interpreted per [RS-DOC](../rs-doc/) Section | Version | Date | Status | Change | | --- | --- | --- | --- | | 0.1.0 | 2026-06-13 | draft | Initial protocol contract, distilled from the Registry Relay API reference, the publishing-pipeline explanation, the boundary map, and the generated OpenAPI document. | -| 0.1.1 | 2026-06-20 | draft | Document governed Evidence Gateway PDP enforcement, aggregate authorization ordering, metadata filtering boundaries, and PDP audit provenance. | +| 0.1.1 | 2026-06-20 | draft | Document governed Relay PDP enforcement, aggregate authorization ordering, metadata filtering boundaries, and PDP audit provenance. | | 0.1.2 | 2026-06-21 | draft | Clarified aggregate disclosure limits and privacy-budget boundaries. | | 0.2.0 | 2026-07-07 | draft | Corrected REQ-PR-RELAY-020's trust-context header names to the actual wire names, and clarified that the signed response credential surfaces of Section 8 are gated by runtime configuration (the `provenance` key), not a Cargo feature, distinguishing them from the genuinely feature-gated OGC and SP DCI adapters. | | 0.2.1 | 2026-07-07 | draft | Documented additional request-context headers alongside REQ-PR-RELAY-020, noting they are not currently wired to any Relay policy decision. | @@ -58,7 +58,7 @@ This specification covers Registry Relay's externally observable protocol behavi - The configuration-driven service model and its fail-closed startup. - Authentication and per-dataset scope enforcement, including the purpose header. -- Governed Evidence Gateway PDP enforcement for configured read routes. +- Governed Relay PDP enforcement for configured read routes. - The consultation data routes (entities, records, relationships, schemas) and the aggregate routes. - Scope-filtered metadata publication at `/metadata/*`. - Evidence-offering descriptors and the boundary they draw around Relay. @@ -108,7 +108,7 @@ REQ-PR-RELAY-006: Access MUST be scope-checked per dataset: a caller MUST hold t REQ-PR-RELAY-007: Where an entity or aggregate source sets `api.require_purpose_header: true`, a request that omits the `Data-Purpose` header MUST be rejected with `400 auth.purpose_required`. Where the header is present, it MUST be recorded in the request's audit record. -Governed Evidence Gateway policy enforcement is an additional runtime decision, not a replacement for authentication or dataset scopes. Relay uses the supported PDP profile when runtime configuration selects a governed ecosystem binding or declares a governed policy for an entity or aggregate source. The supported profile covers policy identity and hash, supported ODRL purpose and spatial terms, purpose, jurisdiction, assurance allow-list and minimum assurance, source freshness, required legal basis and consent, redaction, requested fact and disclosure, source binding, route identity, and checked scope. Unsupported ODRL terms or invalid policy identity fail closed. +Governed Relay PDP policy enforcement is an additional runtime decision, not a replacement for authentication or dataset scopes. Relay uses the supported PDP profile when runtime configuration selects a governed ecosystem binding or declares a governed policy for an entity or aggregate source. The supported profile covers policy identity and hash, supported ODRL purpose and spatial terms, purpose, jurisdiction, assurance allow-list and minimum assurance, source freshness, required legal basis and consent, redaction, requested fact and disclosure, source binding, route identity, and checked scope. Unsupported ODRL terms or invalid policy identity fail closed. REQ-PR-RELAY-019: A governed Relay read MUST receive a PDP permit before returning entity-backed data or aggregate data. If the PDP denies the request, Relay MUST fail closed and return a stable `pdp.*` problem code rather than falling back to an ungoverned read. The stable denial codes include `pdp.purpose_not_permitted`, `pdp.assurance_insufficient`, `pdp.evidence_stale`, `pdp.legal_basis_required`, `pdp.consent_required`, `pdp.jurisdiction_not_permitted`, `pdp.unsupported_policy_term`, `pdp.policy_id_required`, and `pdp.policy_hash_invalid`. @@ -146,17 +146,17 @@ REQ-PR-RELAY-011: Registry Relay MUST NOT define or version the metadata manifes REQ-PR-RELAY-023: Metadata publication MUST remain an authorization-filtered publication surface. Relay MUST NOT treat publication of scoped ODRL, catalog, schema, or evidence-offering metadata as a PDP permit for a later data read, and MUST NOT treat a data-read PDP permit as authorization to publish metadata outside the caller's metadata scopes. -## 7. Evidence offerings +## 7. Evidence Gateway offerings Registry Relay publishes evidence-offering metadata describing where a caller reaches a separate evidence service. Relay routes the caller there; it does not perform the evaluation or the verification. REQ-PR-RELAY-012: Registry Relay MAY publish evidence-offering metadata at `GET /metadata/evidence-offerings` and `GET /metadata/evidence-offerings/{offering_id}`, naming the external endpoint, the offered claim ids, and the supported disclosure modes and formats for an offering. Registry Relay MUST NOT evaluate an offering or issue credentials itself. This is the protocol-level form of REQ-ARC-G-007. -Relay's evidence-offering surface still carries a retired product's vocabulary: runtime binding validation accepts an offering only when `access.kind` is `registry-notary`, and it rejects the configuration otherwise. An operator therefore cannot publish an offering that points at an Evidence deployment without that access kind being widened first. Treat this section as describing published surface with no maintained destination behind it. +Relay's evidence-offering surface still carries a retired product's vocabulary: runtime binding validation accepts an offering only when `access.kind` is `registry-notary`, and it rejects the configuration otherwise. An operator therefore cannot publish an offering that points at an Evidence Gateway deployment without that access kind being widened first. Treat this section as describing published surface with no maintained destination behind it. ## 8. Credential issuance boundary -Registry Relay does not issue credentials, host issuer DID documents, or manage issuer signing keys. Signing belongs to a separate evidence service; the product that used to own it is retired, and Evidence now signs its own assertions under its own contract. +Registry Relay does not issue credentials, host issuer DID documents, or manage issuer signing keys. Signing belongs to a separate evidence service; the product that used to own it is retired, and Evidence Gateway now signs its own assertions under its own contract. REQ-PR-RELAY-013: Registry Relay MUST NOT issue response credentials, MUST NOT accept the legacy `provenance` configuration key, and MUST NOT accept entity-level `publicschema` credential mapping configuration. It MUST NOT serve the former credential-support routes `/.well-known/did.json`, `/schemas/{claim_type}/{version}`, or `/contexts/{vocab}/{version}`. @@ -196,7 +196,7 @@ A Registry Relay deployment conforms to this specification when it: - exposes no source-registry mutation route and never widens a caller's reach at request time (REQ-PR-RELAY-001, REQ-PR-RELAY-002); - fails closed at startup on manifest or binding errors, and keeps storage internals out of the public surface (REQ-PR-RELAY-003, REQ-PR-RELAY-004); - runs a single auth mode, scope-checks per dataset, leaves probes unauthenticated, and enforces the purpose header where configured (REQ-PR-RELAY-005, REQ-PR-RELAY-006, REQ-PR-RELAY-007); -- enforces the supported Evidence Gateway PDP profile for governed reads, filters trust metadata by principal scope, preserves aggregate authorization ordering, and audits PDP provenance (REQ-PR-RELAY-019, REQ-PR-RELAY-020, REQ-PR-RELAY-021, REQ-PR-RELAY-022); +- enforces the supported Relay PDP profile for governed reads, filters trust metadata by principal scope, preserves aggregate authorization ordering, and audits PDP provenance (REQ-PR-RELAY-019, REQ-PR-RELAY-020, REQ-PR-RELAY-021, REQ-PR-RELAY-022); - serves only the bound entities, fields, and relationships as read-only routes (REQ-PR-RELAY-008); - returns aggregate observations computed from configured measures, in both native and SDMX-JSON serializations (REQ-PR-RELAY-009); - scope-filters the metadata it serves, does not own the manifest format, and keeps metadata publication separate from runtime PDP authorization (REQ-PR-RELAY-010, REQ-PR-RELAY-011, REQ-PR-RELAY-023); @@ -207,7 +207,7 @@ A Registry Relay deployment conforms to this specification when it: Conformance to this specification does not imply conformance to any external standard cited in the `standards_referenced` frontmatter field. Each standard's adoption mode and scope are documented in the [standards register](../../reference/standards/). -## Evidence +## Evidence Gateway This specification is `verified`: every requirement describes shipped behavior a reader can inspect, per RS-DOC REQ-DOC-014. @@ -219,7 +219,7 @@ This specification is `verified`: every requirement describes shipped behavior a ## Next -- [RS-PR-EVIDENCE](../rs-pr-evidence/) specifies Evidence, the separate runtime that returns signed, minimum-disclosure assertions. +- [RS-PR-EVIDENCE](../rs-pr-evidence/) specifies Evidence Gateway, the separate runtime that returns signed, minimum-disclosure assertions. - [RS-ARC-G](../rs-arc-g/) places Registry Relay in the registry stack architecture. - [RS-TERMS](../rs-terms/) defines the consultation, metadata, and credential vocabulary used here. - [Registry Relay API reference](../../reference/apis/registry-relay/) is the route-level reference and the link to the generated OpenAPI document. diff --git a/docs/site/src/content/docs/spec/rs-sec-g.mdx b/docs/site/src/content/docs/spec/rs-sec-g.mdx index 930943839..fe6998e37 100644 --- a/docs/site/src/content/docs/spec/rs-sec-g.mdx +++ b/docs/site/src/content/docs/spec/rs-sec-g.mdx @@ -38,7 +38,7 @@ The key words in this document are interpreted per [RS-DOC](../rs-doc/) Section | 0.2.0 | 2026-07-07 | draft | Enumerated the full unauthenticated surface in REQ-SEC-G-006 and anchored the evidence section to the enforcing code. | | 0.3.0 | 2026-07-13 | draft | Assigned registry source access to Relay and restated Notary authorization and federation gates in terms of compiler-pinned Relay consultations. Those Notary gates are retired as of 0.5.0. | | 0.4.0 | 2026-07-19 | draft | Defined the product-owned Relay and Notary replay-protection boundaries, retention references, failure posture, and stale-recovery invariant. The Notary boundary is retired as of 0.5.0. | -| 0.5.0 | 2026-08-03 | draft | Registry Notary is retired. Removed Section 7 (federation trust) and REQ-SEC-G-010, renumbered the following sections, restated REQ-SEC-G-002, REQ-SEC-G-005, REQ-SEC-G-006, REQ-SEC-G-011, REQ-SEC-G-014, and REQ-SEC-G-015 for Registry Relay, Evidence, and Registry Mint, and added REQ-SEC-G-016 and REQ-SEC-G-017. | +| 0.5.0 | 2026-08-03 | draft | Registry Notary is retired. Removed Section 7 (federation trust) and REQ-SEC-G-010, renumbered the following sections, restated REQ-SEC-G-002, REQ-SEC-G-005, REQ-SEC-G-006, REQ-SEC-G-011, REQ-SEC-G-014, and REQ-SEC-G-015 for Registry Relay, Evidence Gateway, and Registry Mint, and added REQ-SEC-G-016 and REQ-SEC-G-017. | ## 1. Scope and references @@ -55,16 +55,16 @@ This specification covers the security model that holds across the runtime servi This specification does not define: -- **Exact configuration schemas, algorithms, and parameters.** Concrete signing algorithms and key sizes, configurable token and cache windows, entropy floors, the precise security-header set, and the precise outbound allow and deny rules are configuration and operational detail, not contract data. Section 7 states the fixed Relay batch-child replay retention that is part of the product contract. For the configurable surface, see [Configure Evidence](../../configure/evidence/), [Configure Registry Mint](../../configure/mint/), and the [Registry Relay client integration](../../products/registry-relay/client-integration/) guide. +- **Exact configuration schemas, algorithms, and parameters.** Concrete signing algorithms and key sizes, configurable token and cache windows, entropy floors, the precise security-header set, and the precise outbound allow and deny rules are configuration and operational detail, not contract data. Section 7 states the fixed Relay batch-child replay retention that is part of the product contract. For the configurable surface, see [Configure Evidence Gateway](../../configure/evidence/), [Configure Registry Mint](../../configure/mint/), and the [Registry Relay client integration](../../products/registry-relay/client-integration/) guide. - **Surface-specific protocol behavior.** How each service applies this model to its own routes, request shapes, and error codes belongs to [RS-PR-EVIDENCE](../rs-pr-evidence/) and [RS-PR-RELAY](../rs-pr-relay/). - **Key custody and secret provisioning.** How private keys and credentials are stored, injected, and rotated in a deployment (environment, file, hardware module) is an operator responsibility, addressed in Section 9. - **Deeper service-internal security mechanisms.** The internal structure of credential fingerprints, the audit envelope, and product replay tables beyond the authority, binding, retention, transaction, failure, and recovery behavior stated here is reserved for product specifications and operator guidance. -For the components named here and their boundaries, see [RS-ARC-G](../rs-arc-g/) Section 3 and the [boundary map](../../map/boundaries-and-map/). For the narrative security context, see the [architecture overview](../../explanation/architecture/) and the [Evidence security model](../../security/evidence/). +For the components named here and their boundaries, see [RS-ARC-G](../rs-arc-g/) Section 3 and the [boundary map](../../map/boundaries-and-map/). For the narrative security context, see the [architecture overview](../../explanation/architecture/) and the [Evidence Gateway security model](../../security/evidence/). ## 2. Shared security primitives -The registry stack concentrates its security-critical behavior in Registry Platform so that it behaves identically across services and can be reviewed in one place. Registry Platform supplies authentication helpers, OpenID Connect (OIDC) verification, audit envelopes, HTTP security, outbound HTTP policy, cryptography, and Selective Disclosure JWT Verifiable Credential (SD-JWT VC) helpers. Registry Relay, Evidence, and Registry Mint own how those primitives are configured and enforced on their own routes. +The registry stack concentrates its security-critical behavior in Registry Platform so that it behaves identically across services and can be reviewed in one place. Registry Platform supplies authentication helpers, OpenID Connect (OIDC) verification, audit envelopes, HTTP security, outbound HTTP policy, cryptography, and Selective Disclosure JWT Verifiable Credential (SD-JWT VC) helpers. Registry Relay, Evidence Gateway, and Registry Mint own how those primitives are configured and enforced on their own routes. REQ-SEC-G-001: A security-critical primitive that must behave identically across runtime services (authentication, OIDC verification, audit envelopes, HTTP security, outbound HTTP policy, cryptography, and SD-JWT VC helpers) SHOULD be sourced from Registry Platform rather than reimplemented per service. This is the security-model form of REQ-ARC-G-005, and it keeps cross-service security behavior consistent and auditable in one place. @@ -77,7 +77,7 @@ flowchart LR caller["Caller"] authn["Authenticate (one mode):
static fingerprint (sha256, constant-time)
OR OIDC (issuer · audience · algorithm · JWKS)"] authz["Authorize:
before source or evaluation work
deny-by-default"] - serve["Serve:
Relay source read · Evidence assertion"] + serve["Serve:
Relay source read · Evidence Gateway assertion"] audit["Audit:
Platform envelope · fail-closed
principal · scopes · request_id · purpose"] caller --> authn --> authz --> serve --> audit keys["Verification keys:
issuer JWKS
(public half only)"] -.-> authn @@ -86,11 +86,11 @@ flowchart LR The diagram restates the model: a caller authenticates in the instance's single mode, the request is authorized against the scope its target requires before source or evaluation work, the service serves the configured surface, and the request is recorded. Verification keys are published so a verifier can check issued artifacts. Where a deployment has no identity provider, Registry Mint issues the access token the caller presents, and the resource server verifies it as an ordinary OIDC token. -REQ-SEC-G-002: A runtime service MUST run exactly one caller-authentication mode, fixed by configuration at startup, and MUST authenticate every route that returns person-level records or evidence assertions before it produces a response. Registry Relay runs either static credentials or OIDC; Evidence runs OIDC only, against exactly one trusted issuer. +REQ-SEC-G-002: A runtime service MUST run exactly one caller-authentication mode, fixed by configuration at startup, and MUST authenticate every route that returns person-level records or evidence assertions before it produces a response. Registry Relay runs either static credentials or OIDC; Evidence Gateway runs OIDC only, against exactly one trusted issuer. REQ-SEC-G-003: In static-credential mode, the configured trust material MUST be a credential fingerprint (`sha256:<...>`), not the raw secret, and the service MUST compare the presented token against the configured fingerprints in constant time, so neither the stored configuration nor the comparison timing discloses the secret. -REQ-SEC-G-004: In OIDC mode, the service MUST delegate token verification to the Registry Platform OIDC primitive. A token MUST be trusted only after its signature is verified against the configured issuer's JSON Web Key Set (JWKS) and its issuer, an accepted audience, and a permitted signing algorithm are checked. The service still owns the scopes its routes require (Section 4). Evidence derives the caller's identity only from the verified token and never from a proxy-supplied identity header. +REQ-SEC-G-004: In OIDC mode, the service MUST delegate token verification to the Registry Platform OIDC primitive. A token MUST be trusted only after its signature is verified against the configured issuer's JSON Web Key Set (JWKS) and its issuer, an accepted audience, and a permitted signing algorithm are checked. The service still owns the scopes its routes require (Section 4). Evidence Gateway derives the caller's identity only from the verified token and never from a proxy-supplied identity header. REQ-SEC-G-016: A token issuer that mints access tokens for registered clients MUST authenticate each client with an asymmetric client assertion, verified only against the keys registered for the client the assertion names. The authority the minted token carries MUST be read from the issuer's server-side client registry and MUST NOT be read from the assertion. The issuer MUST enforce single use of the assertion identifier (Section 7) and MUST NOT distinguish an unknown client, a bad signature, a replayed identifier, and an expired assertion in its public error response, so the token endpoint cannot be used to probe the client registry. @@ -98,7 +98,7 @@ REQ-SEC-G-016: A token issuer that mints access tokens for registered clients MU Authorization is scope-based and deny-by-default: a caller reaches only what its scopes grant, and the grant is fixed by configuration rather than widened at request time. -REQ-SEC-G-005: Authorization MUST be scope-based and deny-by-default. A caller MUST hold the scope a route requires. Relay MUST enforce that scope before source work. Evidence MUST match exactly one configured authority path and MUST enforce the grant it carries before any source read. A caller that lacks a required scope is refused before a protected effect, not after. +REQ-SEC-G-005: Authorization MUST be scope-based and deny-by-default. A caller MUST hold the scope a route requires. Relay MUST enforce that scope before source work. Evidence Gateway MUST match exactly one configured authority path and MUST enforce the grant it carries before any source read. A caller that lacks a required scope is refused before a protected effect, not after. REQ-SEC-G-006: A service MUST NOT widen a caller's reach at request time beyond what configuration grants. Every route that returns person-level records or evidence assertions MUST require authentication, and the unauthenticated surface MUST be limited to routes that carry no person-level data: @@ -107,15 +107,15 @@ REQ-SEC-G-006: A service MUST NOT widen a caller's reach at request time beyond - served documentation and discovery metadata: documentation routes, well-known discovery documents, and published JSON Schemas and JSON-LD contexts; - the token endpoint of a token issuer, which accepts no anonymous request even though it carries no bearer token of its own. -The OpenAPI document requires authentication unless the deployment opts out. A route exempt from bearer authentication MAY still enforce a stronger check of its own: the token endpoint admits only a client whose assertion REQ-SEC-G-016 has verified. Evidence exempts only its probes, its OpenAPI document, its issuer JWKS, and its issuer metadata document; the assertion route and the evidence-definition discovery route both require a verified access token. +The OpenAPI document requires authentication unless the deployment opts out. A route exempt from bearer authentication MAY still enforce a stronger check of its own: the token endpoint admits only a client whose assertion REQ-SEC-G-016 has verified. Evidence Gateway exempts only its probes, its OpenAPI document, its issuer JWKS, and its issuer metadata document; the assertion route and the evidence-definition discovery route both require a verified access token. ## 5. Verification-key publication A verifier needs the issuer's public key to check a signed artifact, and it needs that key without holding a credential of its own. The model therefore separates the published public half from the private signing material, which never leaves the issuer. -REQ-SEC-G-007: An issuer MUST sign with an asymmetric key and MUST publish only the public half through the issuer JWKS. Private key material MUST NOT be published and MUST NOT be required by a verifier. A key that is being rotated out MAY remain published for verification while artifacts it signed are still within their validity, so a verifier can check previously signed artifacts across a rotation. Evidence signs with exactly one active key and retains a retired public key for at least the maximum assertion validity plus the accepted clock skew. +REQ-SEC-G-007: An issuer MUST sign with an asymmetric key and MUST publish only the public half through the issuer JWKS. Private key material MUST NOT be published and MUST NOT be required by a verifier. A key that is being rotated out MAY remain published for verification while artifacts it signed are still within their validity, so a verifier can check previously signed artifacts across a rotation. Evidence Gateway signs with exactly one active key and retains a retired public key for at least the maximum assertion validity plus the accepted clock skew. -The custody mechanism for the private key (environment, file, or hardware module) is a deployment choice, described in [Move Evidence to production signing](../../tutorials/move-evidence-to-production-signing/) and out of scope here (Section 9). +The custody mechanism for the private key (environment, file, or hardware module) is a deployment choice, described in [Move Evidence Gateway to production signing](../../tutorials/move-evidence-to-production-signing/) and out of scope here (Section 9). Readiness, liveness, and protocol conformance checks show that a service has loaded configuration and can serve the expected protocol surface. They do not certify production-grade private-key custody. A deployment that uses software keys, local JWK files, or demo-generated keys can still be reachable and internally consistent; production custody, rotation, and approval of a key provider remain operator responsibilities under Section 9. @@ -125,7 +125,7 @@ Every request that touches person-level data is recorded. Audit is a security co REQ-SEC-G-008: Every request that returns person-level records or evidence assertions MUST be recorded in a Registry Platform audit envelope, capturing at least the caller principal, the scopes exercised, a request identifier, and the `Data-Purpose` value where the caller supplied one. This is the security-model form of REQ-ARC-G-004; it states an invariant a conforming deployment meets, not a claim that every route in a given build has been individually audited. -REQ-SEC-G-009: A deployment MUST be able to run audit fail-closed, so that a request whose audit record cannot be written does not return a successful result. A service MUST NOT silently drop an audit record on the success path. In Evidence the fail-closed posture is not configurable: the access-attempt record is durable before the first source read, the disclosure-release record is durable after signing and before the response is released, and an audit write that cannot be completed fails the request. +REQ-SEC-G-009: A deployment MUST be able to run audit fail-closed, so that a request whose audit record cannot be written does not return a successful result. A service MUST NOT silently drop an audit record on the success path. In Evidence Gateway the fail-closed posture is not configurable: the access-attempt record is durable before the first source read, the disclosure-release record is durable after signing and before the response is released, and an audit write that cannot be completed fails the request. ## 7. Replay-protection authority @@ -141,9 +141,9 @@ defines the complete product retention inventory, and the | Registry Relay | Batch-child idempotent consultation execution. | A high-entropy batch-child identity selects the replay row and binds the exact canonical request to the authenticated consultation workload. The same child and request can replay the terminal result; a different binding conflicts. | `15 minutes` from reservation or terminal publication. | | Registry Mint | Single use of a client assertion identifier at the token endpoint. | The assertion's `jti` is remembered once its signature has been verified against the named client's registered keys, so a captured assertion cannot be spent twice inside its own lifetime. | The assertion's own expiry, bounded by the configured maximum assertion lifetime, in a per-process cache with a configured entry ceiling. | -Evidence holds no replay state at all. Its request nonce is echoed in the response so a caller can +Evidence Gateway holds no replay state at all. Its request nonce is echoed in the response so a caller can correlate its own request, and it is never stored, uniqueness-checked, or exposed elsewhere. -Evidence Version 1 therefore makes no single-use or freshness guarantee of its own, and a +Evidence Gateway Version 1 therefore makes no single-use or freshness guarantee of its own, and a deployment MUST NOT present the echoed nonce as one. REQ-SEC-G-014: Where a product persists replay decisions across restart, a @@ -213,23 +213,23 @@ REQ-SEC-G-010 is retired. It required delegated evaluation to be static-peer onl Conformance to this specification does not imply conformance to any external standard cited in the `standards_referenced` frontmatter field, nor to OpenID Connect, OAuth 2.0, or any other authentication or authorization framework named in prose. Each cited standard's adoption mode and scope are documented in the [standards register](../../reference/standards/). -## Evidence +## Evidence Gateway This specification is `verified`: every requirement describes shipped behavior a reader can inspect, per RS-DOC REQ-DOC-014. - The [boundary map](../../map/boundaries-and-map/) records that the security primitives (authentication, OIDC, audit envelopes, HTTP security, outbound HTTP policy, cryptography, SD-JWT VC helpers) are owned by Registry Platform and that secret provisioning, audit retention, tenant isolation, deployment configuration, and incident response are operator responsibilities, which Sections 2 and 9 make precise. -- The [Evidence API reference](../../reference/apis/registry-evidence/), the [Registry Relay API reference](../../reference/apis/registry-relay/), and the [Registry Mint reference](../../reference/mint/) describe the caller authentication modes, the constant-time fingerprint comparison, the OIDC trust inputs, the per-dataset and per-grant scopes, and the unauthenticated probes that Sections 3 and 4 state normatively. -- The [Evidence security model](../../security/evidence/) and [Configure Evidence](../../configure/evidence/) describe JWKS publication, the public/private key boundary, and rotation, which Section 5 states normatively. +- The [Evidence Gateway API reference](../../reference/apis/registry-evidence/), the [Registry Relay API reference](../../reference/apis/registry-relay/), and the [Registry Mint reference](../../reference/mint/) describe the caller authentication modes, the constant-time fingerprint comparison, the OIDC trust inputs, the per-dataset and per-grant scopes, and the unauthenticated probes that Sections 3 and 4 state normatively. +- The [Evidence Gateway security model](../../security/evidence/) and [Configure Evidence Gateway](../../configure/evidence/) describe JWKS publication, the public/private key boundary, and rotation, which Section 5 states normatively. - [RS-PR-EVIDENCE](../rs-pr-evidence/) and [RS-PR-RELAY](../rs-pr-relay/) carry the surface-level form of the authentication, authorization, key-publication, audit, and error requirements this document generalizes. - [RS-ARC-G](../rs-arc-g/) Section 5 holds the architectural invariants (REQ-ARC-G-004, REQ-ARC-G-005) that Sections 2 and 6 refine. - The [retention and persistent-state reference](../../operate/retention-and-persistent-state/) and [backup and restore procedure](../../operate/backup-and-restore/) define the product-owned PostgreSQL retention and stale-recovery behavior that Section 7 states normatively. - The [standards register](../../reference/standards/) records the adoption mode for the standards listed in `standards_referenced`. -- The enforcing code is inspectable in the workspace: the constant-time fingerprint comparison in `crates/registry-platform-authcommon` (REQ-SEC-G-003); OIDC verification in `crates/registry-platform-oidc` and the Evidence authenticator in `crates/registry-evidence/src/auth.rs` (REQ-SEC-G-004); client-assertion verification and the client registry in `crates/registry-mint/src/assertion.rs` and `crates/registry-mint/src/clients.rs` (REQ-SEC-G-016); authority matching before source work in `crates/registry-evidence` and the Registry Relay route handlers (REQ-SEC-G-005); the unauthenticated-surface allow-lists in Registry Relay's router assembly (`crates/registry-relay/src/server.rs`) and the Evidence router (`crates/registry-evidence/src/server.rs`) (REQ-SEC-G-006); the audit envelope in `crates/registry-platform-audit` and the services' fail-closed audit paths (REQ-SEC-G-008, REQ-SEC-G-009); Relay's batch-child binding and PostgreSQL reservation functions in `crates/registry-relay/src/consultation` and `crates/registry-relay/src/state_plane` (REQ-SEC-G-014, REQ-SEC-G-015); Registry Mint's bounded assertion cache in `crates/registry-mint/src/replay.rs` (REQ-SEC-G-017); and the secret-material rejection lists in `crates/registry-manifest-core` (REQ-SEC-G-013). -- The frozen Evidence Version 1 security invariant matrix (`products/evidence/contracts/security-invariant-matrix.yaml`) records the Evidence-specific form of the audit-ordering, fail-closed, transport-identity, and nonce invariants that Sections 3, 6, and 7 state at stack level. +- The enforcing code is inspectable in the workspace: the constant-time fingerprint comparison in `crates/registry-platform-authcommon` (REQ-SEC-G-003); OIDC verification in `crates/registry-platform-oidc` and the Evidence Gateway authenticator in `crates/registry-evidence/src/auth.rs` (REQ-SEC-G-004); client-assertion verification and the client registry in `crates/registry-mint/src/assertion.rs` and `crates/registry-mint/src/clients.rs` (REQ-SEC-G-016); authority matching before source work in `crates/registry-evidence` and the Registry Relay route handlers (REQ-SEC-G-005); the unauthenticated-surface allow-lists in Registry Relay's router assembly (`crates/registry-relay/src/server.rs`) and the Evidence Gateway router (`crates/registry-evidence/src/server.rs`) (REQ-SEC-G-006); the audit envelope in `crates/registry-platform-audit` and the services' fail-closed audit paths (REQ-SEC-G-008, REQ-SEC-G-009); Relay's batch-child binding and PostgreSQL reservation functions in `crates/registry-relay/src/consultation` and `crates/registry-relay/src/state_plane` (REQ-SEC-G-014, REQ-SEC-G-015); Registry Mint's bounded assertion cache in `crates/registry-mint/src/replay.rs` (REQ-SEC-G-017); and the secret-material rejection lists in `crates/registry-manifest-core` (REQ-SEC-G-013). +- The frozen Evidence Gateway Version 1 security invariant matrix (`products/evidence/contracts/security-invariant-matrix.yaml`) records the Evidence Gateway-specific form of the audit-ordering, fail-closed, transport-identity, and nonce invariants that Sections 3, 6, and 7 state at stack level. ## Next - [RS-ARC-G](../rs-arc-g/) places the security model in the registry stack architecture. - [RS-PR-EVIDENCE](../rs-pr-evidence/) and [RS-PR-RELAY](../rs-pr-relay/) apply this model to each service's protocol surface. - [RS-TERMS](../rs-terms/) defines the security and disclosure vocabulary used here. -- The [Evidence security model](../../security/evidence/) is the narrative explanation of authentication, minimum disclosure, and audit. +- The [Evidence Gateway security model](../../security/evidence/) is the narrative explanation of authentication, minimum disclosure, and audit. diff --git a/docs/site/src/content/docs/spec/rs-terms.mdx b/docs/site/src/content/docs/spec/rs-terms.mdx index 0e0ca6682..6845d9fe5 100644 --- a/docs/site/src/content/docs/spec/rs-terms.mdx +++ b/docs/site/src/content/docs/spec/rs-terms.mdx @@ -53,7 +53,7 @@ The key words in this document are interpreted per [RS-DOC](../rs-doc/) Section | --- | --- | --- | --- | | 0.1.0 | 2026-06-13 | draft | Initial terms, distilled from the documentation glossary. | | 0.2.0 | 2026-06-13 | draft | Added the adoption mode term (Section 3) and the documentation declaration terms, layer and audience (Section 6). | -| 0.3.0 | 2026-06-20 | draft | Added governed Evidence Gateway and PDP enforcement terms. | +| 0.3.0 | 2026-06-20 | draft | Added governed Relay PDP and PDP enforcement terms. | | 0.3.1 | 2026-06-20 | draft | Added PDP, PEP, trust context, source binding, route identity, checked scope, ecosystem binding, ODRL enforcement profile, audit provenance, and fail-closed definitions. | | 0.3.2 | 2026-06-22 | draft | Added delegated subject access and clarified direct subject access. | | 0.4.0 | 2026-07-07 | draft | Renamed the static discovery bundle consistently, added the DID issuer-mode security qualifier, corrected signed response credential gating and disclosure profile casing, added SDMX and eight vocabulary entries (matching policy, claim definition, credential profile, source connector, source adapter sidecar, static-peer federation, issuer mode, JWKS), extended `standards_referenced`, and aligned subject access terminology with the then-current Registry Notary product specification, since retired. | @@ -62,7 +62,7 @@ The key words in this document are interpreted per [RS-DOC](../rs-doc/) Section | 0.6.1 | 2026-07-14 | draft | Added the complete Registry Stack project-authoring vocabulary and clarified compiler-derived credential membership. | | 0.7.0 | 2026-07-16 | draft | Defined the formal stack as four products and classified Solmara Lab as a separate adopter demo. | | 0.8.0 | 2026-07-19 | draft | Defined the registry-backed, issuer-initiated OID4VCI profile and its algorithm, transaction-code, and non-conformance boundaries. | -| 0.9.0 | 2026-08-03 | draft | Reseated the vocabulary on Registry Relay, Evidence, and Registry Mint, added the Evidence assertion terms, and marked the retired Registry Notary terms as retired. | +| 0.9.0 | 2026-08-03 | draft | Reseated the vocabulary on Registry Relay, Evidence Gateway, and Registry Mint, added the Evidence Gateway assertion terms, and marked the retired Registry Notary terms as retired. | ## 1. Products @@ -74,39 +74,39 @@ The registry stack comprises four formal products. Product names are Title Case. **Registry Manifest** (`registry-manifest`): Rust workspace for modeling, validating, and rendering standards-facing service, registry, form, and policy metadata without running Registry Relay. Provides a library (`registry-manifest-core`) and a command-line interface (`registry-manifest-cli`). -**Evidence** (`registry-evidence`): Single-crate minimum-disclosure assertion service and its `evidence` binary. Given authenticated authority, an authorized purpose, and a predefined requirement, it returns a signed assertion that answers the requirement rather than the source record. Evidence has no credential issuance lifecycle. +**Evidence Gateway** (`registry-evidence`): Single-crate minimum-disclosure assertion service and its `evidence` binary. Given authenticated authority, an authorized purpose, and a predefined requirement, it returns a signed assertion that answers the requirement rather than the source record. Evidence Gateway has no credential issuance lifecycle. -**Registry Mint** (`registry-mint`): Supporting service, not a fifth product pattern. It issues short-lived, audience-bound access tokens to registered machine clients so a resource server such as Evidence can require signed tokens without a general-purpose identity provider. The dependency runs one way only: Registry Mint's tests drive Evidence's authenticator, and Evidence does not depend on Registry Mint. +**Registry Mint** (`registry-mint`): Supporting service, not a fifth product pattern. It issues short-lived, audience-bound access tokens to registered machine clients so a resource server such as Evidence Gateway can require signed tokens without a general-purpose identity provider. The dependency runs one way only: Registry Mint's tests drive Evidence Gateway's authenticator, and Evidence Gateway does not depend on Registry Mint. **Solmara Lab** (`solmara-lab`): Separately maintained adopter demo for the fictional Republic of Solmara. It runs published Registry Stack images in local and hosted topologies. Solmara Lab is not a formal Registry Stack product and has no conformance weight in the Registry Stack specifications. ## 2. Assertion and credential terms -**assertion**: The stateless signed payload Evidence returns for one request. It answers a requirement and carries no source record. Its member set is closed by the frozen contract `products/evidence/contracts/evidence.schema.yaml`, which names the supported requirement, the conformant Evidence Type, issuer and provider, issue, observation, and validity instants, purpose, audience, configuration revision, role-bound subject bindings, and supported values. An assertion has no lifecycle: there is no issuance session, no status list, and no revocation. Registry Stack product term. +**assertion**: The stateless signed payload Evidence Gateway returns for one request. It answers a requirement and carries no source record. Its member set is closed by the frozen contract `products/evidence/contracts/evidence.schema.yaml`, which names the supported requirement, the conformant Evidence Type, issuer and provider, issue, observation, and validity instants, purpose, audience, configuration revision, role-bound subject bindings, and supported values. An assertion has no lifecycle: there is no issuance session, no status list, and no revocation. Registry Stack product term. -**acceptance definition**: One complete authored answer path in an Evidence deployment project: a source with its request and response schema, the extraction script, the fact schema and any codelist, the derivation, the requirement with its concept and disclosure guard, the authority grant that permits it, and the synthetic fixture cases that prove it. Evidence Version 1 freezes four coequal acceptance definitions: adult status, residence region, professional licence status, and legal-parent relationship. No acceptance definition is privileged in the runtime, so none of them MUST become a Rust domain type, a built-in operation, or a special route. Registry Stack product term. +**acceptance definition**: One complete authored answer path in an Evidence Gateway deployment project: a source with its request and response schema, the extraction script, the fact schema and any codelist, the derivation, the requirement with its concept and disclosure guard, the authority grant that permits it, and the synthetic fixture cases that prove it. Evidence Gateway Version 1 freezes four coequal acceptance definitions: adult status, residence region, professional licence status, and legal-parent relationship. No acceptance definition is privileged in the runtime, so none of them MUST become a Rust domain type, a built-in operation, or a special route. Registry Stack product term. -**requirement**: The predefined, versioned question one Evidence request names, declared in the immutable bundle with its identifier, kind, source, authorized purposes, subject roles and selector profiles, reference frameworks, Evidence Type, validity, derivation, concepts, fixtures, and disclosure guard. Only predefined, versioned requirements can be evaluated, and to a caller lacking authorization an unknown requirement MUST be indistinguishable from an unauthorized one. The CCCEV term is adopted for the same idea. +**requirement**: The predefined, versioned question one Evidence Gateway request names, declared in the immutable bundle with its identifier, kind, source, authorized purposes, subject roles and selector profiles, reference frameworks, Evidence Type, validity, derivation, concepts, fixtures, and disclosure guard. Only predefined, versioned requirements can be evaluated, and to a caller lacking authorization an unknown requirement MUST be indistinguishable from an unauthorized one. The CCCEV term is adopted for the same idea. -**purpose**: The authorized reason a caller gives for one Evidence request. A purpose is a configured code drawn from the requirement's declared purposes and from the caller's grant, never caller-defined prose, and it forms part of the single authorization decision. It is echoed into the assertion and MUST NOT narrow disclosure: a use case that justifies a coarser answer needs its own requirement. Registry Stack product term. +**purpose**: The authorized reason a caller gives for one Evidence Gateway request. A purpose is a configured code drawn from the requirement's declared purposes and from the caller's grant, never caller-defined prose, and it forms part of the single authorization decision. It is echoed into the assertion and MUST NOT narrow disclosure: a use case that justifies a coarser answer needs its own requirement. Registry Stack product term. -**minimum disclosure**: The rule that one Evidence response carries the smallest sufficient answer to one requirement and never the source record. The assertion payload is closed against additional properties, subject selector profiles and selector values MUST NOT appear in it, and the output gate admits only the exact concept identifiers and value forms the requirement declares. Registry Stack product term. +**minimum disclosure**: The rule that one Evidence Gateway response carries the smallest sufficient answer to one requirement and never the source record. The assertion payload is closed against additional properties, subject selector profiles and selector values MUST NOT appear in it, and the output gate admits only the exact concept identifiers and value forms the requirement declares. Registry Stack product term. -**access token**: The bearer credential a caller presents to Evidence. Evidence accepts one authentication kind whose issuer, audiences, accepted token types, algorithms, key set location, and claim names are fixed in the immutable bundle, and it reads authority only from those configured claim names. Registry Mint issues such tokens; any issuer writing the same claims serves equally well. Caller-supplied data outside the verified token MUST NOT create authority. +**access token**: The bearer credential a caller presents to Evidence Gateway. Evidence Gateway accepts one authentication kind whose issuer, audiences, accepted token types, algorithms, key set location, and claim names are fixed in the immutable bundle, and it reads authority only from those configured claim names. Registry Mint issues such tokens; any issuer writing the same claims serves equally well. Caller-supplied data outside the verified token MUST NOT create authority. -**holder**: The party whose public key a caller may supply on an Evidence request. Evidence echoes that key into the SD-JWT VC `cnf` claim and does nothing else with it: there is no holder-binding ceremony, no key-binding JWT, and no presentation verification. The key MUST NOT reach authorization, selectors, scripts, source requests, or audit. +**holder**: The party whose public key a caller may supply on an Evidence Gateway request. Evidence Gateway echoes that key into the SD-JWT VC `cnf` claim and does nothing else with it: there is no holder-binding ceremony, no key-binding JWT, and no presentation verification. The key MUST NOT reach authorization, selectors, scripts, source requests, or audit. -**SD-JWT VC**: Selective Disclosure JWT Verifiable Credential (IETF draft). Evidence serializes the same stateless assertion as an SD-JWT VC under the frozen profile `products/evidence/contracts/sd-jwt-vc-profile.yaml`, when the immutable bundle and the matched grant both permit that response format. The subject binding stays audience-scoped, so the serialization is meaningful only to the relying party the assertion names. This is a second encoding of one response, not a credential lifecycle. Media type: `application/dc+sd-jwt`. +**SD-JWT VC**: Selective Disclosure JWT Verifiable Credential (IETF draft). Evidence Gateway serializes the same stateless assertion as an SD-JWT VC under the frozen profile `products/evidence/contracts/sd-jwt-vc-profile.yaml`, when the immutable bundle and the matched grant both permit that response format. The subject binding stays audience-scoped, so the serialization is meaningful only to the relying party the assertion names. This is a second encoding of one response, not a credential lifecycle. Media type: `application/dc+sd-jwt`. -**DID**: Decentralized Identifier. W3C DID Core 1.0. Registry Relay no longer publishes a DID document, and no current stack service resolves, publishes, or issues DIDs. Evidence accepts an optional holder public key as a bare JSON Web Key, not as a DID. +**DID**: Decentralized Identifier. W3C DID Core 1.0. Registry Relay no longer publishes a DID document, and no current stack service resolves, publishes, or issues DIDs. Evidence Gateway accepts an optional holder public key as a bare JSON Web Key, not as a DID. **signed response credentials**: Removed Registry Relay feature that attached a W3C Verifiable Credentials Data Model (VCDM) 2.0 VC-JWT signed credential to entity record and aggregate responses. Registry Relay no longer accepts the legacy `provenance` configuration key, no longer serves `/.well-known/did.json`, `/schemas/{claim_type}/{version}`, or `/contexts/{vocab}/{version}`, and no longer returns `application/vc+jwt`. No current stack service issues W3C VCDM credentials. -**wallet**: A holder-owned application that stores credentials and presents them to verifiers. No current stack service integrates with one, and wallet onboarding, wallet attestation, and presentation verification are frozen Evidence Version 1 non-goals. +**wallet**: A holder-owned application that stores credentials and presents them to verifiers. No current stack service integrates with one, and wallet onboarding, wallet attestation, and presentation verification are frozen Evidence Gateway Version 1 non-goals. -**OID4VCI**: OpenID for Verifiable Credential Issuance. No current stack service implements it, and OID4VCI in any part is a frozen Evidence Version 1 non-goal, so the SD-JWT VC serialization has no credential offer, pre-authorized code, token endpoint, nonce endpoint, or wallet grant. +**OID4VCI**: OpenID for Verifiable Credential Issuance. No current stack service implements it, and OID4VCI in any part is a frozen Evidence Gateway Version 1 non-goal, so the SD-JWT VC serialization has no credential offer, pre-authorized code, token endpoint, nonce endpoint, or wallet grant. -**eSignet**: Open-source identity and authentication service (part of MOSIP). No current stack service integrates with it. Evidence authenticates callers against one configured OIDC issuer and key set named in its immutable bundle and names no specific identity product. Not a Registry Stack product term. +**eSignet**: Open-source identity and authentication service (part of MOSIP). No current stack service integrates with it. Evidence Gateway authenticates callers against one configured OIDC issuer and key set named in its immutable bundle and names no specific identity product. Not a Registry Stack product term. ## 3. Metadata and standards terms @@ -130,20 +130,20 @@ The registry stack comprises four formal products. Product names are Title Case. **evidence type list**: A Core Criterion and Core Evidence Vocabulary (CCCEV) list of evidence types that satisfy a requirement. In Registry Manifest, one list is one grouped option; multiple lists on the same requirement are alternatives. The CCCEV term is adopted directly. -**deployment project**: The directory an Evidence operator authors and mounts: a `runtime.yaml` file holding process-local bindings, and a `bundle/` directory holding the governed configuration, scripts, schemas, codelists, and fixtures. The bundle is loaded read-only at startup, so a new revision is a new deployment rather than a live change. Registry Stack product term. +**deployment project**: The directory an Evidence Gateway operator authors and mounts: a `runtime.yaml` file holding process-local bindings, and a `bundle/` directory holding the governed configuration, scripts, schemas, codelists, and fixtures. The bundle is loaded read-only at startup, so a new revision is a new deployment rather than a live change. Registry Stack product term. -**JWKS**: JSON Web Key Set. Evidence publishes its signing keys at `GET /.well-known/evidence/jwks.json` and Registry Mint publishes its own at a configured path, default `/.well-known/jwks.json`. Both are served without authentication so a verifier can obtain the public key without holding a credential. +**JWKS**: JSON Web Key Set. Evidence Gateway publishes its signing keys at `GET /.well-known/evidence/jwks.json` and Registry Mint publishes its own at a configured path, default `/.well-known/jwks.json`. Both are served without authentication so a verifier can obtain the public key without holding a credential. -**Registry Stack project**: The authored root for one registry trust domain, compiled by `registryctl` into separate product configuration inputs for the selected topology. A project describes a Registry Relay deployment and declares Relay lanes only. An Evidence deployment is authored separately as a deployment project. Registry Stack product term. +**Registry Stack project**: The authored root for one registry trust domain, compiled by `registryctl` into separate product configuration inputs for the selected topology. A project describes a Registry Relay deployment and declares Relay lanes only. An Evidence Gateway deployment is authored separately as a deployment project. Registry Stack product term. **trust domain**: The institutional boundary whose operators, runtime identities, policy, and deployment approval govern one Registry Stack project. A geographic jurisdiction can contain -several trust domains, and a trust domain does not need to represent a country. One Evidence +several trust domains, and a trust domain does not need to represent a country. One Evidence Gateway serving process serves exactly one operator-controlled trust domain. Registry Stack product term. **source**: The one logical registry data interface available to Registry Relay, when present, inside the project trust domain. An OAuth or JSON Web Key Set endpoint used by a protocol is not -another data source. Evidence uses the same word for its own configured provider, whose origin, +another data source. Evidence Gateway uses the same word for its own configured provider, whose origin, method, path, headers, authentication, transport trust, timeout, and byte limits are fixed in the bundle and executed only by the Rust core. Registry Stack product term. @@ -167,8 +167,8 @@ governing one service. Registry Stack product term. **consultation**: A named, purpose-aware use of one Registry Relay integration. Relay resolves the pinned source plan, performs the minimized source acquisition, and returns the declared typed -outputs. Evidence can consume one by treating a Relay route as an ordinary fixed HTTP source, -which carries no special status in an Evidence bundle. Registry Stack product term. +outputs. Consultations belong to Relay and are not an Evidence Gateway source contract. Registry +Stack product term. **output**: A typed, minimized scalar returned by Registry Relay on a matching consultation. Registry Stack product term. @@ -179,12 +179,12 @@ deployment target, without changing stable project intent. Registry Stack produc **deployment bundle**: A deferred project-root packaging concept. The current authoring command emits unsigned per-product inputs, no signed project-root bundle is generated, verified, or activated, and no coordinator binds one product's configuration to another's. Not the same thing -as an Evidence deployment project's governed bundle, which is one product's immutable startup +as an Evidence Gateway deployment project's governed bundle, which is one product's immutable startup input. Registry Stack product term. -**deployment**: An operated set of Registry Relay or Evidence product instances. A combined -topology stages each product's separately verified configuration and admits traffic only after -both products are ready; this is not atomic project activation. Registry Stack product term. +**deployment**: An operated set of Registry Relay or Evidence Gateway product instances. Each product +stages and activates its own separately verified configuration; there is no cross-product activation +coordinator, and this is not atomic project activation. Registry Stack product term. **issuer mode**: Removed Registry Relay signed response credentials configuration axis. Registry Relay no longer signs under a gateway DID or a delegated ministry DID, and no current stack service exposes an issuer-mode configuration axis. Registry Stack product term. @@ -194,11 +194,11 @@ both products are ready; this is not atomic project activation. Registry Stack p **CPSV-AP**: Core Public Service Vocabulary Application Profile. Registry Manifest emits CPSV-AP service catalogue JSON-LD. -**CCCEV**: Core Criterion and Core Evidence Vocabulary. Registry Manifest emits CCCEV-shaped requirement, evidence type, and evidence type list metadata. Evidence maps its assertion payload onto CCCEV terms under the frozen mapping `products/evidence/contracts/cccev-field-mapping.yaml`, with named Evidence extensions where CCCEV has no counterpart. +**CCCEV**: Core Criterion and Core Evidence Vocabulary. Registry Manifest emits CCCEV-shaped requirement, evidence type, and evidence type list metadata. Evidence Gateway maps its assertion payload onto CCCEV terms under the frozen mapping `products/evidence/contracts/cccev-field-mapping.yaml`, with named Evidence Gateway extensions where CCCEV has no counterpart. **SHACL**: Shapes Constraint Language. W3C recommendation. Registry Relay and Registry Manifest emit SHACL node shapes for entity validation. -**ODRL**: Open Digital Rights Language. W3C recommendation. Registry Relay and Registry Manifest emit ODRL Offer documents for dataset-scoped descriptive policies. Governed Evidence Gateway runtime enforcement uses only the supported ODRL enforcement terms declared by the `registry-evidence-gateway-pdp/v1` profile; publishing an ODRL policy document is not itself runtime enforcement. +**ODRL**: Open Digital Rights Language. W3C recommendation. Registry Relay and Registry Manifest emit ODRL Offer documents for dataset-scoped descriptive policies. Governed Relay PDP runtime enforcement uses only the supported ODRL enforcement terms declared by the `registry-evidence-gateway-pdp/v1` profile; publishing an ODRL policy document is not itself runtime enforcement. **JSON-LD**: JSON-based linked data format. W3C recommendation (JSON-LD 1.1). Used for catalog and policy render output. @@ -222,9 +222,9 @@ both products are ready; this is not atomic project activation. Registry Stack p ## 4. Governance and safeguards terms -**Evidence Gateway**: Registry Stack product term for Registry Relay's governed runtime path, which selects an evidence pack or policy and asks the shared PDP to permit, redact, or deny a Relay read or consultation. The name also survives in the ODRL enforcement profile identifier `registry-evidence-gateway-pdp/v1`. It does not name Evidence (the product), which is a separate service with its own authorization and disclosure contracts and no policy decision point. +**governed Relay PDP profile**: Registry Stack term for Registry Relay's governed runtime path, which selects an evidence pack or policy and asks the shared PDP to permit, redact, or deny a Relay read or consultation. Its legacy ODRL enforcement profile identifier is `registry-evidence-gateway-pdp/v1`. The identifier does not name or connect to the Evidence Gateway product. -**PDP**: Policy decision point. In Registry Stack, the shared Registry Platform primitive that evaluates a governed policy against trusted request and source context and returns permit, permit with redaction, or deny with stable `pdp.*` provenance. Evidence does not use a PDP: its authorization is one decision over the verified token, the requirement, and the matched grant. Registry Stack product term. +**PDP**: Policy decision point. In Registry Stack, the shared Registry Platform primitive that evaluates a governed policy against trusted request and source context and returns permit, permit with redaction, or deny with stable `pdp.*` provenance. Evidence Gateway does not use a PDP: its authorization is one decision over the verified token, the requirement, and the matched grant. Registry Stack product term. **PEP**: Policy enforcement point. The runtime service surface, such as a Registry Relay governed read or consultation, that calls the PDP and enforces the resulting permit, redaction, or deny decision. Registry Stack product term. @@ -232,7 +232,7 @@ both products are ready; this is not atomic project activation. Registry Stack p **ecosystem binding**: Manifest-level binding that connects an external ecosystem profile or governed evidence pack to a Registry Stack runtime surface. A governed evidence ecosystem binding names the evidence-pack metadata and policy identity a runtime service can use for PDP enforcement. Registry Stack product term. -**ODRL enforcement profile**: Registry Stack product term for the governed Evidence Gateway profile vocabulary for Open Digital Rights Language (ODRL) terms. The current profile is `registry-evidence-gateway-pdp/v1`; the profile vocabulary includes `odrl:purpose` and `odrl:spatial`, but runtime services can support a subset. Registry Relay currently enforces `odrl:purpose` and denies `odrl:spatial` fail-closed. +**ODRL enforcement profile**: Registry Stack product term for the governed Relay PDP profile vocabulary for Open Digital Rights Language (ODRL) terms. The current profile is `registry-evidence-gateway-pdp/v1`; the profile vocabulary includes `odrl:purpose` and `odrl:spatial`, but runtime services can support a subset. Registry Relay currently enforces `odrl:purpose` and denies `odrl:spatial` fail-closed. **PDP gate**: A named policy decision point check evaluated by the shared Registry PDP, such as policy identity, ODRL terms, purpose, jurisdiction, assurance, source freshness, legal basis, consent, requested disclosure, source binding, route identity, checked scope, and redaction. PDP gates produce evaluated rule IDs in audit records. @@ -260,7 +260,7 @@ both products are ready; this is not atomic project activation. Registry Stack p **minimized evidence**: An evidence response shaped by data minimization, selective disclosure, or verifiable attestation. The response can be narrower than the full source record when the configured use case supports that pattern. Registry Stack product term. -**reviewability**: Commitment that every promise the stack makes is backed by an artifact a third party can inspect without trusting the operator's word. Examples include the published DCAT catalog, the SHACL shapes, the ODRL policy documents, the audit envelope schema, the JWKS public key endpoint, and the Evidence security invariant matrix with its test traceability. Registry Stack product term. +**reviewability**: Commitment that every promise the stack makes is backed by an artifact a third party can inspect without trusting the operator's word. Examples include the published DCAT catalog, the SHACL shapes, the ODRL policy documents, the audit envelope schema, the JWKS public key endpoint, and the Evidence Gateway security invariant matrix with its test traceability. Registry Stack product term. **interoperability**: Commitment that every registry in the stack publishes its catalog, schemas, services, and policies in standards-shaped form (DCAT, BRegDCAT-AP, CPSV-AP, CCCEV, SHACL, JSON Schema, ODRL, OpenAPI, OGC Records, SKOS-shaped codelists, SD-JWT VC), so downstream systems integrate against stable contracts rather than per-deployment ones. Registry Stack product term. @@ -307,7 +307,7 @@ These terms classify a documentation page so a reader, human or AI agent, can te - **metadata**: the portable metadata layer (Registry Manifest and the static discovery bundle). - **consultation**: Registry Relay's protected, read-only consultation APIs. -- **evaluation**: Evidence requirement evaluation and assertion issuance. +- **evaluation**: Evidence Gateway requirement evaluation and assertion issuance. - **credential**: retired. It named a retired product's credential issuance, direct and over OID4VCI; no current page should declare it. - **federation**: retired. It named a retired product's delegated (static-peer) evaluation; no current page should declare it. - **administration**: operator administration surfaces, including configuration and the key and reload boundaries. @@ -319,14 +319,14 @@ These terms classify a documentation page so a reader, human or AI agent, can te **audience**: The reader role or roles a page serves. The defined values are `integrator` (a developer integrating against a stack surface), `operator` (an operator configuring or running a deployment), `maintainer` (a contributor to a stack component), `specification editor` (an author of this formal layer), and `tooling` (an AI coding agent or other automated reader that consumes the page as input). -## Evidence +## Evidence Gateway This specification is `verified`: the definitions are distilled from published reference material a reader can inspect, per RS-DOC REQ-DOC-014. - The [glossary](../../reference/glossary/) is the friendlier reference form of this vocabulary and the source these definitions distill. RS-TERMS is authoritative where the two disagree. - The [standards register](../../reference/standards/) records each external standard mapped in Section 3, with its adoption mode and the products that use it. - The architecture specification [RS-ARC-G](../rs-arc-g/) is the referent for the layer vocabulary in Section 6: each layer names a component or surface defined there. -- The Evidence terms in Section 2 are distilled from the frozen Version 1 contracts under `products/evidence/contracts/` and are stated normatively in [RS-PR-EVIDENCE](../rs-pr-evidence/). +- The Evidence Gateway terms in Section 2 are distilled from the frozen Version 1 contracts under `products/evidence/contracts/` and are stated normatively in [RS-PR-EVIDENCE](../rs-pr-evidence/). ## Next diff --git a/docs/site/src/content/docs/start/evaluate-evidence.mdx b/docs/site/src/content/docs/start/evaluate-evidence.mdx index 4b44510c0..cb0b99876 100644 --- a/docs/site/src/content/docs/start/evaluate-evidence.mdx +++ b/docs/site/src/content/docs/start/evaluate-evidence.mdx @@ -1,6 +1,6 @@ --- -title: Evaluate Evidence -description: A cost accounting of running Evidence, what it needs to start, what it does not depend on, how it deploys today, and what operating it demands, for someone deciding whether to commit to it. +title: Evaluate Evidence Gateway +description: A cost accounting of running Evidence Gateway, what it needs to start, what it does not depend on, how it deploys today, and what operating it demands, for someone deciding whether to commit to it. status: current owner: registry-docs source_repos: @@ -11,14 +11,14 @@ locale: en standards_referenced: [] --- -This page is for someone sizing up Evidence before committing infrastructure, +This page is for someone sizing up Evidence Gateway before committing infrastructure, security review, and operational capacity to it. It assumes the fit question from [When Registry Stack fits](../when-to-use/) is already settled and asks the next one: what does running it actually cost. ## Runtime footprint -Evidence is one crate, `registry-evidence`, and one binary, `evidence` +Evidence Gateway is one crate, `registry-evidence`, and one binary, `evidence` (`crates/registry-evidence/Cargo.toml`). There is no separate control plane, worker process, or sidecar: one process serves one operator-controlled trust domain (`products/evidence/README.md`). @@ -63,12 +63,12 @@ private local runtime layout shown here (`crates/registry-evidencectl/src/scaffo ## Dependencies -Evidence does not run against a database. `products/evidence/OPERATOR-CONTRACT.md` -states it directly: "Evidence Version 1 has no application database and +Evidence Gateway does not run against a database. `products/evidence/OPERATOR-CONTRACT.md` +states it directly: "Evidence Gateway Version 1 has no application database and persists no selector, source, evidence, or response data." The one place -Evidence writes durable state is the audit trail, and that is a keyed JSONL +Evidence Gateway writes durable state is the audit trail, and that is a keyed JSONL hash chain on local storage, not a database table. The module that implements -it says so in its own header comment: "Fail-closed native Evidence audit with +it says so in its own header comment: "Fail-closed native Evidence Gateway audit with a durable keyed JSONL chain" (`crates/registry-evidence/src/audit.rs`). An external durable audit service may own that storage instead, but nothing in the runtime requires a database engine to reach it. @@ -79,19 +79,19 @@ states the infrastructure implication for the native deployment target directly: "It does not require Kubernetes, a message broker, a database, OPA, or a service mesh." -Two dependencies remain real, even though neither ships with Evidence: +Two dependencies remain real, even though neither ships with Evidence Gateway: -- An identity provider. Evidence verifies bearer tokens against one +- An identity provider. Evidence Gateway verifies bearer tokens against one configured OIDC issuer; it does not issue tokens itself. Where no identity provider exists, Registry Mint fills that gap: it "issues the access - tokens a resource server such as Evidence verifies, for deployments with no + tokens a resource server such as Evidence Gateway verifies, for deployments with no identity provider." The dependency runs one way: "Mint's tests drive - Evidence's authenticator; Evidence does not depend on Mint" (root + Evidence Gateway's authenticator; Evidence Gateway does not depend on Mint" (root `AGENTS.md`). -- The authoritative source system each requirement calls. Evidence executes +- The authoritative source system each requirement calls. Evidence Gateway executes one fixed, bounded HTTP JSON request per source and never fans out to additional systems; it depends on that source answering within its - configured timeout and concurrency limit, not on any data store Evidence + configured timeout and concurrency limit, not on any data store Evidence Gateway itself owns. ## Deployment options today @@ -113,17 +113,17 @@ instead (`docker/README.md`). These images are explicitly not release evidence. The released Relay image comes from a separate, byte-reproducible path (`release/docker/`, built -outside Docker); if Mint or Evidence images become release artifacts, they +outside Docker); if Mint or Evidence Gateway images become release artifacts, they will follow that path, not this one. An operator may use Docker Compose as an adapter for an approved candidate, but Compose is not generated by `evidencectl build`. The adapter mounts the reviewed bundle unchanged, then mounts a separate container runtime, secret -root, and persistent audit volume. It binds Evidence to a private +root, and persistent audit volume. It binds Evidence Gateway to a private Compose-network address and puts operator-controlled TLS in front. Only the runtime revision changes when container paths or listener bindings change; the bundle revision remains the assertion `configurationRevision`. -The [Evidence candidate Compose guide](../../tutorials/integrate-evidence-candidate-with-docker-compose/) +The [Evidence Gateway candidate Compose guide](../../tutorials/integrate-evidence-candidate-with-docker-compose/) covers that shape. Registry Mint remains optional when the deployment has no suitable OIDC issuer. @@ -142,7 +142,7 @@ older cached assertion will fail to check it ### Deployment inputs Both `runtime.yaml` and the bundle directory must be non-writable before -Evidence will start; a read-only mount is preferred. An operator can remove +Evidence Gateway will start; a read-only mount is preferred. An operator can remove write bits with `chmod -R a-w bundle` and `chmod 444 runtime.yaml` before running `evidence check`. Editing either input means restoring write access, making the change, removing write access again, and rerunning the check @@ -152,7 +152,7 @@ layer, or runtime mutation API. ### Audit trail The audit sink takes an exclusive OS advisory lock on its path at startup, -so exactly one Evidence process may write a given audit path at a time; +so exactly one Evidence Gateway process may write a given audit path at a time; scaling horizontally means N processes with N distinct audit paths, run active/passive rather than active/active. Segment rotation (`auditStorage.maximumFileBytes`) happens online with no operator action, but @@ -186,7 +186,7 @@ it is a Version 1 contract. There is no throughput commitment to evaluate against, only kept measurements. The cost that shapes throughput comes from durability, not from the HTTP or -scripting layers. Evidence must durably accept the access-attempt audit +scripting layers. Evidence Gateway must durably accept the access-attempt audit record before reading a source and the disclosure-release record before returning a response, so every successful request pays two durable audit appends. The audit sink commits appends in groups: writes that arrive while @@ -223,13 +223,13 @@ times the throughput. The sustained-rate measurement reproduces with ## Support window and stability Registry Stack overall is pre-1.0: "APIs and deployment contracts may -change" (root `AGENTS.md`). Evidence does not carry a separate, more +change" (root `AGENTS.md`). Evidence Gateway does not carry a separate, more permissive statement. -Within that, Evidence's Version 1 assertion contract is treated as +Within that, Evidence Gateway's Version 1 assertion contract is treated as implemented rather than exploratory. `products/evidence/README.md` gives its status as "implemented Version 1 contracts, runtime, reference deployments, -and reproducible Evidence-specific verification gates," and +and reproducible Evidence Gateway-specific verification gates," and `products/evidence/OPERATOR-CONTRACT.md` carries the matching "Implemented Version 1 operator contract" status. Four assertion cases, adult status, residence region, professional licence status, and legal-parent @@ -253,5 +253,5 @@ upgrade continuity. */} ## Next - [When Registry Stack fits](../when-to-use/) -- [Configure Evidence](../../configure/evidence/) -- [Evidence API reference](../../reference/apis/registry-evidence/) +- [Configure Evidence Gateway](../../configure/evidence/) +- [Evidence Gateway API reference](../../reference/apis/registry-evidence/) diff --git a/docs/site/src/content/docs/start/evidence-quickstart.mdx b/docs/site/src/content/docs/start/evidence-quickstart.mdx index b14b97c63..2713644a9 100644 --- a/docs/site/src/content/docs/start/evidence-quickstart.mdx +++ b/docs/site/src/content/docs/start/evidence-quickstart.mdx @@ -1,6 +1,6 @@ --- -title: Evidence overview -description: Understand how Evidence returns a verified minimum answer and choose the path for your role. +title: Evidence Gateway overview +description: Understand how Evidence Gateway returns a verified minimum answer and choose the path for your role. status: current owner: registry-docs source_repos: @@ -11,14 +11,14 @@ locale: en standards_referenced: [] --- -Evidence answers one predefined question about one or more subjects and returns a signed minimum +Evidence Gateway answers one predefined question about one or more subjects and returns a signed minimum answer. The caller receives the answer needed for an authorized purpose, not the authoritative record that settled the answer. ```mermaid sequenceDiagram participant C as Caller - participant E as Evidence + participant E as Evidence Gateway participant A as Durable audit participant R as Authoritative registry @@ -33,7 +33,7 @@ sequenceDiagram C->>C: Verify before using the answer ``` -The authoritative registry remains the source of truth. Evidence makes the fixed request defined +The authoritative registry remains the source of truth. Evidence Gateway makes the fixed request defined by the provider, derives only the reviewed answer, and does not return the source response to the caller. The caller verifies the signature and retained transaction expectations before using the answer. @@ -42,20 +42,20 @@ The audit trail records the authorized access and the released disclosure. The a not repeat the source record, prove that the source fact was true, or automatically provide a complete citizen-facing history of registry access. -## Make your first Evidence request +## Make your first Evidence Gateway request -[Get your first Evidence assertion](../../tutorials/first-evidence-assertion/) starts a small +[Get your first Evidence Gateway assertion](../../tutorials/first-evidence-assertion/) starts a small Python registry that you control. You use its OpenAPI description to author an adult-status question, send a real HTTP request with `curl`, and verify a signed boolean answer. The source response contains a name and date of birth; the verified assertion contains neither. The tutorial uses disposable local trust and synthetic data. The local profile keeps -authentication, bounded source access, signing, verification, and audit active while the Evidence +authentication, bounded source access, signing, verification, and audit active while the Evidence Gateway tooling handles development process orchestration. ## Choose your role -### Provide Evidence +### Provide Evidence Gateway Start with the first assertion, then adapt the same workflow to your institution's OpenAPI source. The provider decides the authorized purpose, subject mapping, derivation, and permitted answer. @@ -65,54 +65,54 @@ OpenAPI describes transport and data shapes but cannot make those governed decis local project with a non-boolean answer. The second tutorial demonstrates that minimum disclosure depends on the purpose and can return a reviewed value when a boolean is insufficient. -[See Evidence refuse unsafe changes](../../tutorials/refuse-unsafe-evidence-requests/) then tests +[See Evidence Gateway refuse unsafe changes](../../tutorials/refuse-unsafe-evidence-requests/) then tests the same boundary with an unauthorized purpose and a modified signed response. -When you are ready to use your own system, [draft an Evidence source from +When you are ready to use your own system, [draft an Evidence Gateway source from OpenAPI](../../tutorials/connect-an-institution-source/), then add only the [project-specific fixtures](../../tutorials/prove-an-evidence-project/) your reviewers need. Build a reviewed candidate only after that local work is complete. Registry Mint is optional when the deployment has no suitable OIDC issuer. -### Consume Evidence +### Consume Evidence Gateway Retain the request expectations and trusted issuer keys before the response arrives. Verify the stored response against that independent context, then expose the verified answer to application logic. -[Verify Evidence as a consumer](../../tutorials/verify-an-assertion-as-a-consumer/) continues the +[Verify Evidence Gateway as a consumer](../../tutorials/verify-an-assertion-as-a-consumer/) continues the local journey with every service stopped. Then [manage verifier trust](../../tutorials/manage-evidence-verifier-trust/) through an independent onboarding and rotation process. [SD-JWT VC](../../tutorials/request-evidence-as-sd-jwt-vc/) is an optional second serialization of the same assertion. -### Operate Evidence +### Operate Evidence Gateway Bind the provider-approved definition to production identity, source trust, signing keys, and durable audit storage. The operator owns readiness, key rotation, audit-chain verification, retention, backup, and recovery. -[Verify and interpret the Evidence audit chain](../../operate/evidence-audit/) covers the integrity +[Verify and interpret the Evidence Gateway audit chain](../../operate/evidence-audit/) covers the integrity proof, event phases, privacy-preserving pseudonyms, and the current lack of a supported citizen history query. ## Keep the product boundary visible -Evidence does not decide whether an institution has legal authority to use a source, whether a +Evidence Gateway does not decide whether an institution has legal authority to use a source, whether a purpose is legitimate, or whether a source record is true. Those decisions and assurances come from governance, authorization, and the authoritative institution. A valid signature proves who signed the exact assertion bytes and whether the assertion matches the retained verification expectations. -Evidence is separate from Registry Relay. Registry Relay exposes protected, selected records. -Evidence can use a Relay API as one fixed source, but Evidence retains its own authorization, +Evidence Gateway is separate from Registry Relay. Registry Relay exposes protected, selected records. +Evidence Gateway contacts its own configured authoritative HTTP sources and retains its own authorization, derivation, signing, verification, and audit boundaries. Registry Mint is optional supporting infrastructure that supplies short-lived caller tokens when a deployment has no identity provider. ## Next -- [Get your first Evidence assertion](../../tutorials/first-evidence-assertion/) -- [Build and deploy an Evidence project](../../tutorials/build-and-deploy-evidence-project/) +- [Get your first Evidence Gateway assertion](../../tutorials/first-evidence-assertion/) +- [Build and deploy an Evidence Gateway project](../../tutorials/build-and-deploy-evidence-project/) - [Decide when Registry Stack fits](../when-to-use/) -- [Evaluate Evidence's operating requirements](../evaluate-evidence/) -- [Review the Evidence security model](../../security/evidence/) +- [Evaluate Evidence Gateway's operating requirements](../evaluate-evidence/) +- [Review the Evidence Gateway security model](../../security/evidence/) diff --git a/docs/site/src/content/docs/start/quickstart.mdx b/docs/site/src/content/docs/start/quickstart.mdx index c77bf4c08..92fec9724 100644 --- a/docs/site/src/content/docs/start/quickstart.mdx +++ b/docs/site/src/content/docs/start/quickstart.mdx @@ -1,6 +1,6 @@ --- title: Start with Registry Stack 1.0 -description: Answer a bounded question with Evidence, or publish protected records with Registry Relay, then adapt the source or the definition. +description: Answer a bounded question with Evidence Gateway, or publish protected records with Registry Relay, then adapt the source or the definition. status: current owner: registry-docs source_repos: @@ -13,18 +13,18 @@ standards_referenced: [] --- Pick the door that matches what your caller needs. To learn only a fact about -one subject, start with Evidence. To read specific records or fields, start +one subject, start with Evidence Gateway. To read specific records or fields, start with Registry Relay over the maintained spreadsheet registry. Both first runs use one terminal and synthetic data. Neither needs a source checkout, production keys, or a deployment package. -## Answer a bounded question with Evidence +## Answer a bounded question with Evidence Gateway -Evidence signs the answer to one bounded question about one subject without +Evidence Gateway signs the answer to one bounded question about one subject without releasing the record behind it. -[Evidence overview](../evidence-quickstart/) explains the source, assertion, +[Evidence Gateway overview](../evidence-quickstart/) explains the source, assertion, verification, and audit boundaries. -[Get your first Evidence assertion](../../tutorials/first-evidence-assertion/) +[Get your first Evidence Gateway assertion](../../tutorials/first-evidence-assertion/) then connects a visible Python registry, sends a real request, and verifies the minimum answer before reading the answer. @@ -55,19 +55,12 @@ Continue with: - [The OpenCRVS Events API case study](../../tutorials/verify-opencrvs-claims/) for a synthetic example of that generic integration path -## See both doors working together +## Keep the two doors separate -The two doors are not alternatives an institution has to choose between once -and for all. One institution can publish records through Registry Relay and -answer bounded questions through Evidence over those same records, because -Evidence treats a Relay API as an ordinary fixed HTTP source. +An institution can operate Registry Relay and Evidence Gateway, but they are +independent products with separate sources, authorization, configuration, and +audit boundaries. Evidence Gateway does not use Relay as its source path. -[First run with Solmara Lab](../../tutorials/first-run-with-solmara-lab/) is -where that arrangement is visible end to end. It brings up a whole fictional -country's registry services on a laptop, then asks Evidence one question about -one person: is this subject an adult? The answer comes back signed, carrying -`true` and neither the identifier nor the date of birth that settled it, while -the record stays with the authority that holds it. - -Run it after the spreadsheet or HTTP tutorial above. It needs Docker and -about 30 minutes. +Choose the tutorial for the result you need. Start with the Evidence Gateway +tutorial for a signed, minimum-disclosure answer, or use the spreadsheet and +HTTP tutorials for a protected record API. diff --git a/docs/site/src/content/docs/start/when-to-use.mdx b/docs/site/src/content/docs/start/when-to-use.mdx index 7f6b03f2a..b887fd7a5 100644 --- a/docs/site/src/content/docs/start/when-to-use.mdx +++ b/docs/site/src/content/docs/start/when-to-use.mdx @@ -31,21 +31,19 @@ system that owns the data. | Caller needs | Use | Result | | --- | --- | --- | | To read specific data | Registry Relay | A protected, read-only API response | -| To learn only a fact | Evidence | A signed assertion carrying the answer, not the source record | +| To learn only a fact | Evidence Gateway | A signed assertion carrying the answer, not the source record | -Registry Relay and Evidence can work together: an institution publishes -records through Registry Relay, and Evidence answers a bounded question over -those same records by treating the Relay API as a fixed HTTP source. Registry -Mint issues the short-lived access tokens either service needs when a -deployment has no identity provider; see the +Registry Relay and Evidence Gateway are separate product choices. They can be +operated by the same institution, but each has its own source, authorization, +configuration, and audit boundary. Evidence Gateway does not use Relay as its +source path. Registry Mint can issue short-lived access tokens to either +service when a deployment has no identity provider; see the [Registry Mint reference](../../reference/mint/). -[First run with Solmara Lab](../../tutorials/first-run-with-solmara-lab/) runs -that combination on a laptop if you would rather see it than read about it. ### Who does what - The assertion provider is an institution that answers requests with signed - facts through Evidence. + facts through Evidence Gateway. - The data publisher is an institution that exposes records through Registry Relay. - The consumer or verifier is a relying service that calls either door and @@ -81,6 +79,6 @@ approval. - [Start a registry from a spreadsheet](../../tutorials/publish-spreadsheet-secured-registry-api/) - [Connect an existing HTTP registry](../../tutorials/author-registry-project/) -- [Evaluate Evidence](../evaluate-evidence/) +- [Evaluate Evidence Gateway](../evaluate-evidence/) - [Read the architecture overview](../../explanation/architecture/) - [Review the security boundaries](../../security/) diff --git a/docs/site/src/content/docs/tutorials/assert-a-role-bound-relationship.mdx b/docs/site/src/content/docs/tutorials/assert-a-role-bound-relationship.mdx index c6726bfa3..f6076b7fc 100644 --- a/docs/site/src/content/docs/tutorials/assert-a-role-bound-relationship.mdx +++ b/docs/site/src/content/docs/tutorials/assert-a-role-bound-relationship.mdx @@ -16,16 +16,16 @@ standards_referenced: [] import QuickstartMeta from '../../../components/QuickstartMeta.astro'; Answer, "Is this candidate registered as a parent of this child?" Unlike -[your first Evidence assertion](../first-evidence-assertion/) and the +[your first Evidence Gateway assertion](../first-evidence-assertion/) and the [governed-value follow-up](../return-a-governed-value/), this standalone tutorial binds two people -in distinct roles. Evidence must not let a caller omit a role, repeat one role, or swap its +in distinct roles. Evidence Gateway must not let a caller omit a role, repeat one role, or swap its selector field. ## Start a relationship registry @@ -106,7 +106,7 @@ The synthetic registry knows three people and one registered relationship. Its e only the relationship decision for a known pair. A production source would need governance that defines what "registered parent" means and who can maintain that relationship. -## Create the Evidence project +## Create the Evidence Gateway project In another terminal, create an editable project from the registry's OpenAPI description: @@ -164,7 +164,7 @@ fn answer(facts, selectors, context) { ``` This source already owns the reviewed relationship decision, so the derivation maps that fact to -the one governed answer. Evidence still validates the source response, answer form, disclosure, +the one governed answer. Evidence Gateway still validates the source response, answer form, disclosure, and both subject bindings before signing. ## Start the project @@ -174,7 +174,7 @@ evidencectl dev --detach ``` ```text -Evidence ready at http://127.0.0.1:8080 +Evidence Gateway ready at http://127.0.0.1:8080 Mint ready at http://127.0.0.1:8081 ``` @@ -252,5 +252,5 @@ Return to the registry terminal and press `Ctrl+C`. - [Issue registered-parent evidence from OpenCRVS](../verify-a-registered-parent-with-opencrvs/) - [Issue immunization evidence from DHIS2](../issue-immunization-evidence-from-dhis2/) -- [See Evidence refuse unsafe requests](../refuse-unsafe-evidence-requests/) -- [Configure Evidence](../../configure/evidence/) +- [See Evidence Gateway refuse unsafe requests](../refuse-unsafe-evidence-requests/) +- [Configure Evidence Gateway](../../configure/evidence/) diff --git a/docs/site/src/content/docs/tutorials/build-and-deploy-evidence-project.mdx b/docs/site/src/content/docs/tutorials/build-and-deploy-evidence-project.mdx index ae85b21c4..e2b10d504 100644 --- a/docs/site/src/content/docs/tutorials/build-and-deploy-evidence-project.mdx +++ b/docs/site/src/content/docs/tutorials/build-and-deploy-evidence-project.mdx @@ -1,6 +1,6 @@ --- -title: Build and deploy an Evidence project -description: Compile one editable Evidence project into a reviewed candidate and hand it to an operator without copying local development state. +title: Build and deploy an Evidence Gateway project +description: Compile one editable Evidence Gateway project into a reviewed candidate and hand it to an operator without copying local development state. status: current owner: registry-docs source_repos: @@ -16,25 +16,25 @@ standards_referenced: [] import QuickstartMeta from '../../../components/QuickstartMeta.astro'; -Complete [Prove an Evidence project](../prove-an-evidence-project/) and its review before starting +Complete [Prove an Evidence Gateway project](../prove-an-evidence-project/) and its review before starting this tutorial. You will turn that editable project into one reviewed production candidate, then bind its secrets and runtime paths on the target host. This tutorial uses released `evidence` and `evidencectl` binaries. It does not copy `.evidence/dev`, generate a key, register a caller, or deploy a service for you. ## Before you start -You need a released Evidence toolset on `PATH`, an editable project that runs locally, and an +You need a released Evidence Gateway toolset on `PATH`, an editable project that runs locally, and an operator who can provision owner-only secrets and a private listener on the target host. Use Registry Mint only when no suitable OpenID Connect (OIDC) issuer exists. An existing OIDC -issuer and Mint are equivalent choices from Evidence's perspective. +issuer and Mint are equivalent choices from Evidence Gateway's perspective. Confirm the released binaries before changing the project: @@ -91,7 +91,7 @@ institution-evidence/ limits, signing, optional response formats, and authority profiles. Secret references use `secret:file/` only. Do not place secret values or absolute secret paths in this file. -`runtime.yaml` is the ordinary Evidence runtime document. It binds the final absolute candidate +`runtime.yaml` is the ordinary Evidence Gateway runtime document. It binds the final absolute candidate bundle path, private listener, secret root, audit path, and optional private certificate authority files. The build copies its bytes unchanged, so the target host remains the authority for path, ownership, permission, secret, and trust validation. @@ -130,9 +130,9 @@ source endpoint. Record the printed bundle revision with the approved candidate ## Provision the target host -Transfer the exact candidate. The operator independently provisions the Evidence signing key, +Transfer the exact candidate. The operator independently provisions the Evidence Gateway signing key, audit HMAC key, subject-binding HMAC key, and source credentials beneath the runtime secret root. -Make the candidate runtime and bundle non-writable to the Evidence service identity. +Make the candidate runtime and bundle non-writable to the Evidence Gateway service identity. Run the grouped offline ceremony once after the candidate, runtime bindings, trust files, and secrets are in place: @@ -142,7 +142,7 @@ evidencectl doctor --project "" evidencectl fixtures run --project "" ``` -Start Evidence only after both commands pass: +Start Evidence Gateway only after both commands pass: ```sh evidence --runtime "/runtime.yaml" serve @@ -211,6 +211,6 @@ rm -f "" ## Next -- [Issue Evidence access tokens with Registry Mint](../issue-evidence-access-tokens-with-registry-mint/) -- [Integrate an Evidence candidate with Docker Compose](../integrate-evidence-candidate-with-docker-compose/) -- [Manage Evidence verifier trust](../manage-evidence-verifier-trust/) +- [Issue Evidence Gateway access tokens with Registry Mint](../issue-evidence-access-tokens-with-registry-mint/) +- [Integrate an Evidence Gateway candidate with Docker Compose](../integrate-evidence-candidate-with-docker-compose/) +- [Manage Evidence Gateway verifier trust](../manage-evidence-verifier-trust/) diff --git a/docs/site/src/content/docs/tutorials/connect-an-institution-source.mdx b/docs/site/src/content/docs/tutorials/connect-an-institution-source.mdx index d0e78970d..7ebccdc08 100644 --- a/docs/site/src/content/docs/tutorials/connect-an-institution-source.mdx +++ b/docs/site/src/content/docs/tutorials/connect-an-institution-source.mdx @@ -1,6 +1,6 @@ --- title: Connect an institution source from OpenAPI -description: Retain an institution API contract, draft one bounded Evidence source, add a governed question, and run the editable project locally. +description: Retain an institution API contract, draft one bounded Evidence Gateway source, add a governed question, and run the editable project locally. status: current owner: registry-docs source_repos: @@ -13,8 +13,8 @@ locale: en standards_referenced: [] --- -If this is your first Evidence project, complete -[Get your first Evidence assertion](../first-evidence-assertion/) before adapting an institution +If this is your first Evidence Gateway project, complete +[Get your first Evidence Gateway assertion](../first-evidence-assertion/) before adapting an institution source. You will build one editable project from an institution's OpenAPI document and use the same retained contract for source drafting and local execution. You do not assemble a deployment bundle or copy a reference deployment. @@ -22,7 +22,7 @@ or copy a reference deployment. ## Before you start You need an OpenAPI 3.0 or 3.1 document for an operation that performs one bounded lookup. The -operation must let Evidence distinguish no match, one match, and several matches without paging +operation must let Evidence Gateway distinguish no match, one match, and several matches without paging through a registry. Keep credentials, real responses, and personal data outside the tracked project. Use a sanitized @@ -30,7 +30,7 @@ response sample only when the OpenAPI document omits a bound that a reviewer can ## Create the authoring project -Retain the OpenAPI document and create disposable local Evidence keys: +Retain the OpenAPI document and create disposable local Evidence Gateway keys: ```sh evidencectl new institution-evidence \ @@ -164,7 +164,7 @@ install -m 600 /dev/null secrets/registry-password ``` Open each file in your editor and enter one credential value. `secret:file/...` values are logical -references resolved beneath the project's owner-only `secrets` directory. Evidence does not read +references resolved beneath the project's owner-only `secrets` directory. Evidence Gateway does not read credentials from the source YAML, a command argument, a request, or a log. ## Finish extraction and facts @@ -210,12 +210,12 @@ fn answer(facts, selectors, context) { ``` The question governs purpose, subject, concepts, derivation, and disclosure. The source governs -how Evidence obtains the fixed facts. This separation lets another question reuse `people` +how Evidence Gateway obtains the fixed facts. This separation lets another question reuse `people` without copying its transport or credential policy. ## Run the authored project -Start the local Evidence and Registry Mint pair: +Start the local Evidence Gateway and Registry Mint pair: ```sh evidencectl dev --detach @@ -226,5 +226,5 @@ creates one private local generation, and runs the real `evidence check` gate be missing artifact, unresolved draft marker, invalid secret reference, unbounded schema, or inconsistent selector binding stops the generation. -Continue with [Build and deploy an Evidence project](../build-and-deploy-evidence-project/) after the +Continue with [Build and deploy an Evidence Gateway project](../build-and-deploy-evidence-project/) after the project's source, derivation, and synthetic acceptance cases have been independently reviewed. diff --git a/docs/site/src/content/docs/tutorials/control-who-can-request-evidence.mdx b/docs/site/src/content/docs/tutorials/control-who-can-request-evidence.mdx index a934e675a..0c71eeb26 100644 --- a/docs/site/src/content/docs/tutorials/control-who-can-request-evidence.mdx +++ b/docs/site/src/content/docs/tutorials/control-who-can-request-evidence.mdx @@ -1,6 +1,6 @@ --- -title: Control who can request Evidence -description: Define access policies, add a client without restarting Evidence, and observe allowed and refused access. +title: Control who can request Evidence Gateway +description: Define access policies, add a client without restarting Evidence Gateway, and observe allowed and refused access. status: current owner: registry-docs source_repos: @@ -16,7 +16,7 @@ standards_referenced: [] import QuickstartMeta from '../../../components/QuickstartMeta.astro'; Complete [Return a governed value](../return-a-governed-value/) before starting this tutorial. -You will give two applications different access to that Evidence service, add one while the service +You will give two applications different access to that Evidence Gateway service, add one while the service is running, and prove that a valid access token does not let its client ask every configured question. @@ -37,26 +37,26 @@ question. This tutorial manages access for machine applications, not accounts for people. Registry Mint authenticates each application from its own key and issues a short-lived access -token. Evidence then checks whether the application's access policy includes the configured +token. Evidence Gateway then checks whether the application's access policy includes the configured question. These are separate decisions: | Decision | Example | Owner | | --- | --- | --- | | Which application is calling? | `age-checker` | Registry Mint client registration | -| What may it ask? | The `age-checks` policy includes `adult-status` | Evidence access policy | -| May Evidence read its source? | `GET /people/{person_id}` | Evidence source configuration | +| What may it ask? | The `age-checks` policy includes `adult-status` | Evidence Gateway access policy | +| May Evidence Gateway read its source? | `GET /people/{person_id}` | Evidence Gateway source configuration | | May a consumer trust the result? | Expected issuer, audience, and signing key | Consumer verification policy | The first two rows are the access-management boundary you will configure. Source credentials and consumer trust remain independent. -Access policies are part of Evidence's immutable governed configuration. Client membership is +Access policies are part of Evidence Gateway's immutable governed configuration. Client membership is part of Registry Mint's reloadable registry: | Change | Runtime effect | | --- | --- | -| Add or revoke a client | Registry Mint receives a reload request; Evidence does not restart | -| Add a question or change an access policy | Start a new Evidence generation | +| Add or revoke a client | Registry Mint receives a reload request; Evidence Gateway does not restart | +| Add a question or change an access policy | Start a new Evidence Gateway generation | A client change affects tokens issued after Registry Mint reloads. A token issued before a client is revoked remains valid for up to 300 seconds. @@ -100,7 +100,7 @@ Added access policy age-checks for adult-status. Added access policy service-routing for age-bracket. ``` -Review the governed policies before starting Evidence: +Review the governed policies before starting Evidence Gateway: ```sh evidencectl access policy list @@ -117,7 +117,7 @@ The commands write the reviewable policy documents to `access/policies/age-check Many clients can share one policy. A client can also belong to several policies when their question sets do not overlap. `evidencectl` rejects overlapping policy assignments because they would make the access decision ambiguous. Adding a question to either policy later changes the governed -authorization boundary and requires a new Evidence generation. +authorization boundary and requires a new Evidence Gateway generation. ## Register the first local application @@ -141,18 +141,18 @@ key. ## Start the protected service -Compile the questions and both access policies, then start Evidence and Registry Mint: +Compile the questions and both access policies, then start Evidence Gateway and Registry Mint: ```sh evidencectl dev --detach ``` ```text -Evidence ready at http://127.0.0.1:8080 +Evidence Gateway ready at http://127.0.0.1:8080 Mint ready at http://127.0.0.1:8081 ``` -Registry Mint recognizes `age-checker`. Evidence has both access policies available, even though +Registry Mint recognizes `age-checker`. Evidence Gateway has both access policies available, even though no client belongs to `service-routing` yet. ## Make an allowed request @@ -171,7 +171,7 @@ Preparation signs a one-time client assertion with the local application key, ex short-lived access token, and writes the request and verification expectations before any source access occurs. -Send the request across the Evidence HTTP boundary: +Send the request across the Evidence Gateway HTTP boundary: ```sh curl --silent --show-error --fail-with-body \ @@ -201,12 +201,12 @@ evidencectl verify age-checker-allowed.jws.json \ VERIFIED ``` -The application was authenticated, its `age-checks` policy matched the request, and Evidence +The application was authenticated, its `age-checks` policy matched the request, and Evidence Gateway called the registry only after both checks passed. ## Add an application without restarting -Keep Evidence and Registry Mint running. Register `service-router` under the existing +Keep Evidence Gateway and Registry Mint running. Register `service-router` under the existing `service-routing` policy: ```sh @@ -223,7 +223,7 @@ Registry Mint reload requested. The command writes the public registration to `access/clients/service-router.yaml`, keeps the private key under `.evidence/clients/`, and asks Registry Mint to reload its complete client registry. The message confirms that the reload was requested, not that Registry Mint accepted the -new registry. The next token exchange provides that functional proof. Evidence does not restart +new registry. The next token exchange provides that functional proof. Evidence Gateway does not restart because both access policies were already part of its governed configuration. Review the active client assignments: @@ -251,7 +251,7 @@ evidencectl request prepare age-bracket \ ``` The command can prepare the request because `age-bracket` is a valid project question and -`age-checker` is a registered client. The Evidence service, not the request-building tool, makes +`age-checker` is a registered client. The Evidence Gateway service, not the request-building tool, makes the authorization decision. Send the request: @@ -290,7 +290,7 @@ python3 -m json.tool age-checker-refused.json The access token is valid, but the client's `age-checks` policy does not authorize the `age-bracket` question. The registry terminal shows no new `GET /people/person-456`, because -Evidence refuses the request before source access. The response does not reveal which application, +Evidence Gateway refuses the request before source access. The response does not reveal which application, question, or policy caused the refusal. ## Use the application assigned the policy @@ -345,7 +345,7 @@ Registry Mint reload requested. ``` The command updates `access/clients/age-checker.yaml` and requests another Registry Mint reload -without restarting Evidence. Revocation cannot erase a stateless access token already issued to +without restarting Evidence Gateway. Revocation cannot erase a stateless access token already issued to the application. That token remains valid for up to 300 seconds. Try to prepare a fresh request as the revoked client: @@ -382,8 +382,8 @@ DISCLOSURE RELEASED age_bracket The audit distinguishes requester pseudonyms without writing client identifiers, tokens, subject selectors, or returned values. The earlier authorization refusal is not retained in the durable -Evidence audit. Evidence currently returns that refusal before appending an access-attempt event. -The revoked-client preparation also has no Evidence audit event because no HTTP request was sent. +Evidence Gateway audit. Evidence Gateway currently returns that refusal before appending an access-attempt event. +The revoked-client preparation also has no Evidence Gateway audit event because no HTTP request was sent. ## Clean up @@ -399,21 +399,21 @@ Return to the registry terminal and press `Ctrl+C`. ## What you proved - Authentication identifies the calling application but grants no question by itself. -- Many applications can share a governed access policy without client-specific Evidence config. -- A client added while the services run can obtain a token without restarting Evidence or +- Many applications can share a governed access policy without client-specific Evidence Gateway config. +- A client added while the services run can obtain a token without restarting Evidence Gateway or Registry Mint. - Each application receives only the questions included in its assigned policies. -- Evidence refuses unauthorized questions before reading the source. +- Evidence Gateway refuses unauthorized questions before reading the source. - Revoking a local client requests a Registry Mint reload and prevents new local request preparation. - Client membership changes affect new tokens while existing tokens remain valid for up to 300 seconds. -- Adding a question or changing an access policy requires a new Evidence generation. +- Adding a question or changing an access policy requires a new Evidence Gateway generation. - Source authentication and consumer trust remain separate from caller access. ## Next -- [See Evidence refuse unsafe requests](../refuse-unsafe-evidence-requests/) +- [See Evidence Gateway refuse unsafe requests](../refuse-unsafe-evidence-requests/) - [Configure Registry Mint](../../configure/mint/) - [Request an access token from application code](../../configure/request-an-access-token/) -- [Manage Evidence verifier trust](../manage-evidence-verifier-trust/) +- [Manage Evidence Gateway verifier trust](../manage-evidence-verifier-trust/) diff --git a/docs/site/src/content/docs/tutorials/deploy-standalone-with-own-data.mdx b/docs/site/src/content/docs/tutorials/deploy-standalone-with-own-data.mdx index c4d82bc43..a44a07fa1 100644 --- a/docs/site/src/content/docs/tutorials/deploy-standalone-with-own-data.mdx +++ b/docs/site/src/content/docs/tutorials/deploy-standalone-with-own-data.mdx @@ -85,9 +85,9 @@ Do not add a source-free, self-attested, delegated-attestation, or caller-define If an answer has no reviewed source, keep it out of the service. A caller that needs a signed, minimum-disclosure assertion rather than a protected read calls -[Evidence](../../products/registry-evidence/) directly. -Evidence can consume this Relay-protected API through its ordinary fixed HTTP source contract; it -does not inherit Relay's authorization or policy model. +[Evidence Gateway](../../products/registry-evidence/) directly. +Evidence Gateway does not consume this Relay-protected API. It uses its own configured authoritative +HTTP source and does not inherit Relay's authorization or policy model. ## Prove the source contract offline diff --git a/docs/site/src/content/docs/tutorials/first-evidence-assertion.mdx b/docs/site/src/content/docs/tutorials/first-evidence-assertion.mdx index 0d0bbbd2f..8b60efec0 100644 --- a/docs/site/src/content/docs/tutorials/first-evidence-assertion.mdx +++ b/docs/site/src/content/docs/tutorials/first-evidence-assertion.mdx @@ -1,5 +1,5 @@ --- -title: Get your first Evidence assertion +title: Get your first Evidence Gateway assertion description: Run a local registry and verify a signed adult-status answer without copying the source record. status: current owner: registry-docs @@ -15,7 +15,7 @@ standards_referenced: [] import QuickstartMeta from '../../../components/QuickstartMeta.astro'; -Evidence reads an authorized source record, answers a preconfigured question, and signs only the +Evidence Gateway reads an authorized source record, answers a preconfigured question, and signs only the governed answer. In this tutorial, you will ask "Is this person an adult?" without returning the person's name or date of birth. @@ -32,7 +32,7 @@ person's name or date of birth. %%{init: {"sequence": {"mirrorActors": false}}}%% sequenceDiagram participant C as Tutorial caller - participant E as Evidence + participant E as Evidence Gateway participant R as Tutorial registry C->>E: Authorized request
adult-status, person_id=person-123 @@ -44,19 +44,19 @@ sequenceDiagram ``` Before the request, Registry Mint gives the tutorial caller short-lived local authorization. -Evidence and the registry process the identifier and date of birth to answer the question, but the +Evidence Gateway and the registry process the identifier and date of birth to answer the question, but the released assertion contains only the governed answer and an opaque subject binding. -## Install Evidence +## Install Evidence Gateway -Install the latest Evidence toolset: +Install the latest Evidence Gateway toolset: ```sh curl -fsSL https://github.com/registrystack/registry-stack/releases/latest/download/evidencectl-install.sh | bash evidencectl --version ``` -The installer provides `evidencectl` and the local Evidence and Registry Mint runtimes used later +The installer provides `evidencectl` and the local Evidence Gateway and Registry Mint runtimes used later in the tutorial. ## Start a small registry @@ -144,11 +144,11 @@ print("Registry listening on http://127.0.0.1:8000", flush=True) ThreadingHTTPServer(("127.0.0.1", 8000), Registry).serve_forever() ``` -You do not need to understand every line of the server. Three details connect it to Evidence: +You do not need to understand every line of the server. Three details connect it to Evidence Gateway: - `/people/{person_id}` returns a complete person record. - `/openapi.json` describes that endpoint and its response. -- `getPerson` is the OpenAPI operation that the Evidence question will select. +- `getPerson` is the OpenAPI operation that the Evidence Gateway question will select. In one terminal, start the registry and leave it running: @@ -178,7 +178,7 @@ curl -s http://127.0.0.1:8000/people/person-123 | python3 -m json.tool The registry returns an identifier, a name, and a date of birth. The verified assertion will contain none of those source values. -## Create the Evidence project +## Create the Evidence Gateway project Create a local project from the registry's OpenAPI description: @@ -254,7 +254,7 @@ matching the purpose declared here. ### `derivations/adult-status.rhai` Open `derivations/adult-status.rhai` in your editor and add the answer logic. Rhai is the bounded -scripting language Evidence uses for requirement-specific derivations: +scripting language Evidence Gateway uses for requirement-specific derivations: ```rhai fn answer(facts, selectors, context) { @@ -268,13 +268,13 @@ The derivation performs four operations: 1. Require and parse the selected date of birth. 2. Calculate the eighteenth birthday using calendar arithmetic. -3. Compare it with `context.legal_local_date`, which Evidence derives from the observation instant +3. Compare it with `context.legal_local_date`, which Evidence Gateway derives from the observation instant in the configured timezone. 4. Return a map containing exactly the declared `is_adult` answer. -Evidence validates the returned name and boolean form before signing. +Evidence Gateway validates the returned name and boolean form before signing. -Start Evidence and Registry Mint: +Start Evidence Gateway and Registry Mint: ```sh evidencectl dev --detach @@ -285,7 +285,7 @@ Evidence ready at http://127.0.0.1:8080 Mint ready at http://127.0.0.1:8081 ``` -This command starts Evidence and Mint only. The Python registry remains the process you started in +This command starts Evidence Gateway and Mint only. The Python registry remains the process you started in the first terminal. ## Request an assertion @@ -300,7 +300,7 @@ evidencectl request prepare adult-status \ ``` Preparation asks the local Mint for short-lived authorization and records the verification -expectations before a response exists. It does not send the request to Evidence or contact the +expectations before a response exists. It does not send the request to Evidence Gateway or contact the registry. It creates exactly these owner-only artifacts: ```text @@ -333,7 +333,7 @@ curl --silent --show-error --fail-with-body \ HTTP 200 ``` -`curl` called Evidence, Evidence called the registry, and the HTTP response is a signed flattened +`curl` called Evidence Gateway, Evidence Gateway called the registry, and the HTTP response is a signed flattened JSON Web Signature (JWS). A successful HTTP response is not yet a trusted assertion. ## Verify before reading @@ -389,13 +389,13 @@ answers the authored question without becoming another copy of the registry reco The owner-only `request.json` still records that this transaction concerned `person-123`, while `verification.json` records the expected opaque subject binding and request nonce. Retain those -files with the signed response when you need to [verify Evidence later as a +files with the signed response when you need to [verify Evidence Gateway later as a consumer](../verify-an-assertion-as-a-consumer/). The identifier cannot be recovered from the assertion alone. ## Stop the local services -Stop Evidence and Mint before reading the completed audit chain: +Stop Evidence Gateway and Mint before reading the completed audit chain: ```sh evidencectl dev stop @@ -424,7 +424,7 @@ record or access token. ## Clean up -Remove the stopped local generation, including the sealed bundle that Evidence used: +Remove the stopped local generation, including the sealed bundle that Evidence Gateway used: ```sh evidencectl dev clean @@ -452,8 +452,8 @@ Choose two different unused ports when you start the local services: evidencectl dev --detach --evidence-port 8180 --mint-port 8181 ``` -Evidence uses the selected ports consistently in its runtime, Mint authorization, readiness -checks, and generated request artifacts. Send the assertion request to the selected Evidence port, +Evidence Gateway uses the selected ports consistently in its runtime, Mint authorization, readiness +checks, and generated request artifacts. Send the assertion request to the selected Evidence Gateway port, such as `http://127.0.0.1:8180/v1/evidence`. The development profile binds both services to loopback in the environment where the command @@ -465,5 +465,5 @@ loopback. - [Return a governed value](../return-a-governed-value/) - [Bind two people to one relationship assertion](../assert-a-role-bound-relationship/) -- [Review the Evidence overview](../../start/evidence-quickstart/) -- [Evaluate Evidence's operating requirements](../../start/evaluate-evidence/) +- [Review the Evidence Gateway overview](../../start/evidence-quickstart/) +- [Evaluate Evidence Gateway's operating requirements](../../start/evaluate-evidence/) diff --git a/docs/site/src/content/docs/tutorials/first-run-with-solmara-lab.mdx b/docs/site/src/content/docs/tutorials/first-run-with-solmara-lab.mdx index 4f98f349e..877ea542a 100644 --- a/docs/site/src/content/docs/tutorials/first-run-with-solmara-lab.mdx +++ b/docs/site/src/content/docs/tutorials/first-run-with-solmara-lab.mdx @@ -1,7 +1,8 @@ --- -title: First run with Solmara Lab -description: Bring up the Solmara Lab compose demo on a laptop, verify it with the smoke suites, and ask Registry Evidence one question over a Relay-protected API. -status: current +title: First run with Solmara Lab (historical) +description: Historical Solmara Lab workflow that asked Evidence Gateway one question over a Relay-protected API. +status: historical +draft: true owner: registry-docs source_repos: - solmara-lab @@ -22,16 +23,20 @@ standards_referenced: import QuickstartMeta from '../../../components/QuickstartMeta.astro'; import { Steps } from '@astrojs/starlight/components'; +This unpublished page records a retired demo topology. Evidence Gateway no longer uses Registry +Relay as a source. Use the [Evidence Gateway quickstart](../../start/evidence-quickstart/) for the +current architecture and workflow. + Solmara Lab is a standalone Registry Stack adopter demo for the fictional Republic of Solmara: a whole country's worth of registry services over generated synthetic data, with a citizen portal and a public Visitor's Center in front of them. This tutorial brings that topology up with the lab's `just` recipes, verifies it with the smoke suites, and then asks -[Registry Evidence](../../products/registry-evidence/) one question by hand: is this person an +[Evidence Gateway](../../products/registry-evidence/) one question by hand: is this person an adult? The answer comes back signed, and the date of birth behind it never leaves the Civil Registration Authority. ## Before you start @@ -44,16 +44,16 @@ The Compose service mounts four independently owned paths: ```text candidate/bundle -> /etc/registry-evidence/bundle read-only runtime.docker.yaml -> /etc/registry-evidence/runtime.yaml read-only -Evidence secret root -> /run/secrets/registry-evidence read-only -Evidence audit volume -> /var/lib/registry-evidence writable +Evidence Gateway secret root -> /run/secrets/registry-evidence read-only +Evidence Gateway audit volume -> /var/lib/registry-evidence writable ``` Keep the bundle and runtime read-only. A read-only mount establishes their immutability, but does -not waive secret ownership or mode validation. The maintained Evidence image runs as UID and GID +not waive secret ownership or mode validation. The maintained Evidence Gateway image runs as UID and GID `65532`; pin that identity in the Compose file and make every secret file acceptable to it with the required owner-only permissions. A different reviewed image requires an explicitly reviewed UID and matching ownership. -Prepare the persistent audit volume for that same identity before startup. Do not run Evidence as +Prepare the persistent audit volume for that same identity before startup. Do not run Evidence Gateway as root to compensate for an audit volume with the wrong owner. ```yaml @@ -69,7 +69,7 @@ services: - evidence-audit:/var/lib/registry-evidence ``` -Bind Evidence to a private Compose-network address. Put TLS termination and public routing in an +Bind Evidence Gateway to a private Compose-network address. Put TLS termination and public routing in an operator-controlled service ahead of that listener. ## Validate in the container context @@ -100,7 +100,7 @@ audit contents. ## Add optional Mint When the same application uses Mint, run Mint as a separate private service. Mint retains its public -HTTPS issuer and JWKS URI, while internal routing or split DNS resolves that identity. Evidence must +HTTPS issuer and JWKS URI, while internal routing or split DNS resolves that identity. Evidence Gateway must continue to use the public HTTPS issuer and JWKS URI, not an internal plain-HTTP service name. ## Stop without deleting the audit history @@ -114,6 +114,6 @@ docker compose down ## Next -- [Build and deploy an Evidence project](../build-and-deploy-evidence-project/) -- [Issue Evidence access tokens with Registry Mint](../issue-evidence-access-tokens-with-registry-mint/) -- [Configure Evidence](../../configure/evidence/) +- [Build and deploy an Evidence Gateway project](../build-and-deploy-evidence-project/) +- [Issue Evidence Gateway access tokens with Registry Mint](../issue-evidence-access-tokens-with-registry-mint/) +- [Configure Evidence Gateway](../../configure/evidence/) diff --git a/docs/site/src/content/docs/tutorials/issue-a-birth-certificate-vc-from-opencrvs.mdx b/docs/site/src/content/docs/tutorials/issue-a-birth-certificate-vc-from-opencrvs.mdx index 510039846..d9a8895eb 100644 --- a/docs/site/src/content/docs/tutorials/issue-a-birth-certificate-vc-from-opencrvs.mdx +++ b/docs/site/src/content/docs/tutorials/issue-a-birth-certificate-vc-from-opencrvs.mdx @@ -2,7 +2,7 @@ title: Request a birth certificate SD-JWT VC from OpenCRVS description: >- Map a synthetic OpenCRVS birth into a governed structured value, request it as SD-JWT VC, and - verify the credential across the Evidence HTTP boundary. + verify the credential across the Evidence Gateway HTTP boundary. status: current owner: registry-docs source_repos: @@ -30,7 +30,7 @@ Credential (SD-JWT VC). The credential exposes `givenName`, `familyName`, `dateO prerequisites={[ 'The completed OpenCRVS registered-parent tutorial project', 'A Record Search client for the public OpenCRVS demo', - 'The Evidence toolset', + 'The Evidence Gateway toolset', 'curl and an editor', ]} /> @@ -44,7 +44,7 @@ accounts, and integrations. The example is informed by the European Union Once-Only Technical System [birth-evidence sample](https://code.europa.eu/oots/tdd/tdd_chapters/-/raw/master/OOTS-EDM/xml/Request-Response%20Samples/4.5.4%20-%20OOTS-EDM%20XML%20Examples%20of%20the%20Evidence%20Exchange/2%20Example%20for%20requesting%20a%20Birth%20Certificate%20-%20natural%20person/Evidence%20Samples/BirthEvidence.xml?ref_type=heads), but this tutorial does not implement that exchange protocol. -Evidence produces a governed extract from a registered birth: +Evidence Gateway produces a governed extract from a registered birth: ```json { @@ -60,7 +60,7 @@ Evidence produces a governed extract from a registered birth: ``` The deployment's law and governance determine whether that extract is accepted as a birth -certificate. Evidence proves which provider signed the configured assertion. It does not grant +certificate. Evidence Gateway proves which provider signed the configured assertion. It does not grant legal status to the document. Each direct child of `birthCertificate` has its own SD-JWT disclosure. `placeOfBirth` is one atomic @@ -360,7 +360,7 @@ disclosure: allow: [birth_certificate] ``` -`birthCertificate` is a configured JSON claim name. Evidence has no built-in birth-certificate +`birthCertificate` is a configured JSON claim name. Evidence Gateway has no built-in birth-certificate type. The same mechanism can project any reviewed structured value under another non-reserved claim name. @@ -387,7 +387,7 @@ fn answer(facts, selectors, context) { } ``` -Evidence validates the complete value against the schema before mapping any field to an SD-JWT +Evidence Gateway validates the complete value against the schema before mapping any field to an SD-JWT disclosure. A derivation cannot add undeclared certificate fields. ## Start and prepare the SD-JWT request @@ -415,7 +415,7 @@ OpenCRVS. ## Request the credential over HTTP -Send the retained request across the real Evidence boundary: +Send the retained request across the real Evidence Gateway boundary: ```sh curl -fsS \ @@ -428,7 +428,7 @@ curl -fsS \ --output opencrvs-birth-certificate.sd-jwt ``` -Evidence authenticates the caller, authorizes the exact question and purpose, obtains an OpenCRVS +Evidence Gateway authenticates the caller, authorizes the exact question and purpose, obtains an OpenCRVS token, performs the fixed birth search, validates and derives the value, signs the SD-JWT VC, and durably records the disclosure release before returning the bytes. @@ -446,13 +446,13 @@ evidencectl verify opencrvs-birth-certificate.sd-jwt \ VERIFIED ``` -Inspect the verified Evidence payload: +Inspect the verified Evidence Gateway payload: ```sh python3 -m json.tool opencrvs-birth-certificate.verified.json ``` -The supported value retains the governed Evidence form: +The supported value retains the governed evidence form: ```json { @@ -483,7 +483,7 @@ awk -F '~' '{print "disclosures:", NF - 2}' opencrvs-birth-certificate.sd-jwt disclosures: 4 ``` -Evidence's V1 verifier checks the complete stored SD-JWT VC response. Wallet presentation, omission of +Evidence Gateway's V1 verifier checks the complete stored SD-JWT VC response. Wallet presentation, omission of selected disclosures, and key-binding JWT validation remain outside this profile. ## Inspect the audit and clean up @@ -505,6 +505,6 @@ you no longer need the project. ## Next -- [Request another Evidence assertion as SD-JWT VC](../request-evidence-as-sd-jwt-vc/) -- [Prove an Evidence project](../prove-an-evidence-project/) +- [Request another Evidence Gateway assertion as SD-JWT VC](../request-evidence-as-sd-jwt-vc/) +- [Prove an Evidence Gateway project](../prove-an-evidence-project/) - [Verify an assertion as a consumer](../verify-an-assertion-as-a-consumer/) diff --git a/docs/site/src/content/docs/tutorials/issue-evidence-access-tokens-with-registry-mint.mdx b/docs/site/src/content/docs/tutorials/issue-evidence-access-tokens-with-registry-mint.mdx index 75681c21e..26ceafe22 100644 --- a/docs/site/src/content/docs/tutorials/issue-evidence-access-tokens-with-registry-mint.mdx +++ b/docs/site/src/content/docs/tutorials/issue-evidence-access-tokens-with-registry-mint.mdx @@ -1,6 +1,6 @@ --- -title: Issue Evidence access tokens with Registry Mint -description: Configure Registry Mint as an optional OIDC issuer for a completed Evidence candidate when the deployment has no suitable identity provider. +title: Issue Evidence Gateway access tokens with Registry Mint +description: Configure Registry Mint as an optional OIDC issuer for a completed Evidence Gateway candidate when the deployment has no suitable identity provider. status: current owner: registry-docs source_repos: @@ -17,31 +17,31 @@ standards_referenced: [] import QuickstartMeta from '../../../components/QuickstartMeta.astro'; Start with the completed candidate from -[Build and deploy an Evidence project](../build-and-deploy-evidence-project/). Use Registry Mint -when that deployment has no suitable OpenID Connect (OIDC) issuer for Evidence. Mint is a separate -supporting service. Evidence does not require Mint, and an external HTTPS OIDC issuer follows the -same Evidence authentication contract. +[Build and deploy an Evidence Gateway project](../build-and-deploy-evidence-project/). Use Registry Mint +when that deployment has no suitable OpenID Connect (OIDC) issuer for Evidence Gateway. Mint is a separate +supporting service. Evidence Gateway does not require Mint, and an external HTTPS OIDC issuer follows the +same Evidence Gateway authentication contract. ## Before you start -You need a completed Evidence candidate, a public HTTPS issuer name for Mint, a registered machine +You need a completed Evidence Gateway candidate, a public HTTPS issuer name for Mint, a registered machine caller, and released `mint` and `evidencectl` binaries. Mint serves one active process in Version 1. Its client-assertion replay cache is memory-only and clears when the process restarts. Do not make a high-availability or durable replay-protection claim for this deployment shape. -Generate Mint's signing key independently from Evidence's signing key. Keep it owner-only outside -the Evidence candidate. +Generate Mint's signing key independently from Evidence Gateway's signing key. Keep it owner-only outside +the Evidence Gateway candidate. ## Author Mint separately -Create a Mint directory beside, not inside, the Evidence candidate: +Create a Mint directory beside, not inside, the Evidence Gateway candidate: ```text mint/ @@ -54,9 +54,9 @@ mint/ Set Mint's `issuer` to its public HTTPS identity. Configure its listener on a private address and let operator-controlled routing or split DNS resolve the public HTTPS issuer inside the private -network. Do not replace Evidence's issuer or JWKS URI with an internal plain-HTTP service name. +network. Do not replace Evidence Gateway's issuer or JWKS URI with an internal plain-HTTP service name. -Register each client with its public JWK, reviewed principal, requester tags, Evidence audience, +Register each client with its public JWK, reviewed principal, requester tags, evidence audience, and optional grant. Mint writes authority from this registration, never from the client's request. ## Check the two configurations @@ -67,7 +67,7 @@ Validate Mint without opening a listener: mint check --config "/mint.yaml" ``` -Then compare the completed Evidence candidate with Mint. This check is read-only and does not copy +Then compare the completed Evidence Gateway candidate with Mint. This check is read-only and does not copy or modify either project: ```sh @@ -77,7 +77,7 @@ evidencectl doctor \ ``` The paired check compares issuer, JWKS URI, audiences, admitted algorithm and token type, plus the -principal, requester-tags, Evidence-audience, grant-id, grant-authority, and optional actor claim +principal, requester-tags, evidence audience, grant-id, grant-authority, and optional actor claim names. It does not decide whether a client has legal authority, create an authority profile, or register a client. @@ -101,14 +101,14 @@ mint token \ --key "" > "" ``` -Send the token to Evidence through its real HTTPS boundary using the owner-only Curl configuration -described in [Build and deploy an Evidence project](../build-and-deploy-evidence-project/). +Send the token to Evidence Gateway through its real HTTPS boundary using the owner-only Curl configuration +described in [Build and deploy an Evidence Gateway project](../build-and-deploy-evidence-project/). That request proves the selected client-to-grant path. The paired doctor check does not. ## Expected result -Mint accepts the reviewed client assertion and Evidence accepts the resulting `at+jwt` access token -over its HTTPS boundary. Retain the Evidence response and audit verification result, not the token. +Mint accepts the reviewed client assertion and Evidence Gateway accepts the resulting `at+jwt` access token +over its HTTPS boundary. Retain the Evidence Gateway response and audit verification result, not the token. ## Clean up the token file @@ -121,6 +121,6 @@ rm -f "" ## Next -- [Build and deploy an Evidence project](../build-and-deploy-evidence-project/) +- [Build and deploy an Evidence Gateway project](../build-and-deploy-evidence-project/) - [Configure Registry Mint](../../configure/mint/) - [Registry Mint reference](../../reference/mint/) diff --git a/docs/site/src/content/docs/tutorials/issue-immunization-evidence-from-dhis2.mdx b/docs/site/src/content/docs/tutorials/issue-immunization-evidence-from-dhis2.mdx index 994cbcb74..5871a0732 100644 --- a/docs/site/src/content/docs/tutorials/issue-immunization-evidence-from-dhis2.mdx +++ b/docs/site/src/content/docs/tutorials/issue-immunization-evidence-from-dhis2.mdx @@ -17,7 +17,7 @@ import QuickstartMeta from '../../../components/QuickstartMeta.astro'; Complete [Return a governed value](../return-a-governed-value/) before starting this tutorial. You will apply that pattern to the public DHIS2 Tracker demo, combine two immunization events into -one governed answer, and verify the signed assertion returned across the Evidence HTTP boundary. +one governed answer, and verify the signed assertion returned across the Evidence Gateway HTTP boundary. {/* Target tutorial for evidencectl UX2, UX3, UX5, and UX10. Keep status draft until the commands and authoring shapes on this page pass the tutorial gate. */} @@ -28,7 +28,7 @@ one governed answer, and verify the signed assertion returned across the Evidenc level="Institution source with synthetic data" prerequisites={[ 'The completed governed-value tutorial', - 'The Evidence toolset', + 'The Evidence Gateway toolset', 'Access to the public DHIS2 demo', 'curl and an editor', ]} @@ -62,7 +62,7 @@ The source adapter also applies two conservative readings: - An absent source value does not become `false` or `0`. - Two different values for the same concept make the source record inconsistent. -In either case, Evidence returns no assertion. +In either case, Evidence Gateway returns no assertion. ## Choose a synthetic child @@ -80,7 +80,7 @@ immunization fields contain values. Note its tracked entity identifier and keep it out of tracked files. The identifier selects the source record. -It will be used for the DHIS2 read and the Evidence request, but it will not appear in the signed +It will be used for the DHIS2 read and the Evidence Gateway request, but it will not appear in the signed assertion. ## See the DHIS2 boundary @@ -108,7 +108,7 @@ export DHIS2_PROGRAM_ID='IpHINAT79UW' export DHIS2_TRACKED_ENTITY_ID='' ``` -Read the same bounded fields that Evidence will use: +Read the same bounded fields that Evidence Gateway will use: ```sh curl --silent --show-error --fail \ @@ -123,7 +123,7 @@ curl --silent --show-error --fail \ The response contains the tracked entity, its programme enrollment, the two events, and their data values. Some event data values are unrelated to the five concepts. -Evidence will receive the bounded response, discard unrelated values during extraction, and +Evidence Gateway will receive the bounded response, discard unrelated values during extraction, and release only the five declared concepts. This distinction is deliberate. @@ -151,7 +151,7 @@ cd dhis2-immunization `evidencectl new` retains the OpenAPI document and creates empty `selectors/`, `sources/`, `adapters/`, `schemas/`, `questions/`, `derivations/`, and `fixtures/` directories. -It generates only disposable local Evidence signing, audit, and subject-binding material. +It generates only disposable local Evidence Gateway signing, audit, and subject-binding material. It does not invent the source policy or the answer. ## Draft the DHIS2 source @@ -310,7 +310,7 @@ It cannot read the source credential, the caller identity, the purpose, or the s ## Close the response bounds -Evidence validates the projected response before extraction runs, and every array in a schema +Evidence Gateway validates the projected response before extraction runs, and every array in a schema must state its bound. Replace `schemas/child-tracker-response.schema.yaml` with: @@ -462,7 +462,7 @@ properties: ``` A missing immunization reading now fails the fact contract. -Evidence does not convert absence into a negative answer. +Evidence Gateway does not convert absence into a negative answer. ## Author the multi-concept question @@ -530,12 +530,12 @@ fn answer(facts, selectors, context) { The first comparison prevents a response for another tracked entity from being evaluated. The returned map must contain exactly the aliases declared under `answers`. -Evidence validates every value against its declared form before signing. +Evidence Gateway validates every value against its declared form before signing. ## Start the project Compile the editable source and question into one immutable local generation, then start Registry -Mint and Evidence: +Mint and Evidence Gateway: ```sh evidencectl dev --detach @@ -565,7 +565,7 @@ evidencectl request prepare immunization-summary \ Use this only with the public synthetic record. In a real deployment, selectors need an input path that does not expose identifiers in shell history or process arguments. -Send that request across the Evidence HTTP boundary: +Send that request across the Evidence Gateway HTTP boundary: ```sh curl --silent --show-error --fail-with-body \ @@ -578,8 +578,8 @@ curl --silent --show-error --fail-with-body \ --output immunization-summary.jws.json ``` -The caller contacts Evidence. -Evidence authenticates and authorizes the caller, performs one bounded authenticated DHIS2 read, +The caller contacts Evidence Gateway. +Evidence Gateway authenticates and authorizes the caller, performs one bounded authenticated DHIS2 read, derives the five concepts, audits the disclosure, and returns a signed flattened JSON Web Signature (JWS). @@ -659,6 +659,6 @@ service account, review the source acquisition posture, and build a reviewed pro ## Next -- [See Evidence refuse unsafe requests](../refuse-unsafe-evidence-requests/) -- [Build and deploy an Evidence project](../build-and-deploy-evidence-project/) +- [See Evidence Gateway refuse unsafe requests](../refuse-unsafe-evidence-requests/) +- [Build and deploy an Evidence Gateway project](../build-and-deploy-evidence-project/) - [Verify an assertion as a consumer](../verify-an-assertion-as-a-consumer/) diff --git a/docs/site/src/content/docs/tutorials/manage-evidence-verifier-trust.mdx b/docs/site/src/content/docs/tutorials/manage-evidence-verifier-trust.mdx index 817b2753c..24a710c0e 100644 --- a/docs/site/src/content/docs/tutorials/manage-evidence-verifier-trust.mdx +++ b/docs/site/src/content/docs/tutorials/manage-evidence-verifier-trust.mdx @@ -1,5 +1,5 @@ --- -title: Manage Evidence verifier trust +title: Manage Evidence Gateway verifier trust description: Pin provider identity and public keys independently, then approve signing-key rotation without trusting the response being verified. status: current owner: registry-docs @@ -16,7 +16,7 @@ standards_referenced: [] A valid signature proves control of a private key. Your consumer still decides which provider, issuer, key set, algorithm, audience, requirement, and configuration revision it trusts. -Keep that decision outside the Evidence response. Discovery helps you find candidate metadata; it +Keep that decision outside the Evidence Gateway response. Discovery helps you find candidate metadata; it does not make the candidate trusted. ## Establish trust before the first request @@ -24,7 +24,7 @@ does not make the candidate trusted. Through your organization's provider-onboarding process, verify and retain: - the legal issuer and technical provider identifiers; -- the expected Evidence service and JWKS endpoints; +- the expected Evidence Gateway service and JWKS endpoints; - the Ed25519 public keys and their `kid` values; - the audience that identifies your relying party; - the requirements, evidence types, purposes, concepts, and configuration revisions you accept; @@ -85,6 +85,6 @@ Remove a retiring key from current verification only after: Never make verification fetch a missing key automatically. An unknown `kid` is a trust-change signal and must fail closed until your organization approves the change. -Provider operators use [Rotate Evidence signing keys](../move-evidence-to-production-signing/) +Provider operators use [Rotate Evidence Gateway signing keys](../move-evidence-to-production-signing/) for the other side of this rotation. Consumers remain independent and do not inherit trust merely because the provider published a key. diff --git a/docs/site/src/content/docs/tutorials/move-evidence-to-production-signing.mdx b/docs/site/src/content/docs/tutorials/move-evidence-to-production-signing.mdx index 793294f59..9272cb0b6 100644 --- a/docs/site/src/content/docs/tutorials/move-evidence-to-production-signing.mdx +++ b/docs/site/src/content/docs/tutorials/move-evidence-to-production-signing.mdx @@ -1,6 +1,6 @@ --- -title: Rotate Evidence signing keys -description: Stage a new Evidence signing key, publish an overlap set through the runtime JWKS endpoint, and retire the old key after consumers can verify both generations. +title: Rotate Evidence Gateway signing keys +description: Stage a new Evidence Gateway signing key, publish an overlap set through the runtime JWKS endpoint, and retire the old key after consumers can verify both generations. status: current owner: registry-docs source_repos: @@ -13,9 +13,9 @@ locale: en standards_referenced: [] --- -Use this procedure after [Build and deploy an Evidence project](../build-and-deploy-evidence-project/). +Use this procedure after [Build and deploy an Evidence Gateway project](../build-and-deploy-evidence-project/). Coordinate the rotation with consumers through -[Manage Evidence verifier trust](../manage-evidence-verifier-trust/) before activation. Evidence +[Manage Evidence Gateway verifier trust](../manage-evidence-verifier-trust/) before activation. Evidence Gateway signs with one active Ed25519 key. Rotation is a reviewed, startup-only configuration change. There is no hot-rotation endpoint or standby-key field. Publishing a new public key makes it discoverable; it does not make independently operated consumers trust it. @@ -34,7 +34,7 @@ evidencectl keygen signing \ The command writes a private and public JWK without printing private bytes. Provision the private JWK into the deployment's secret root under a new logical filename. Keep the public JWK as a separately approved distribution artifact for consumers. The active public key does not need -to be copied into the closed bundle because Evidence derives it from the active private JWK. +to be copied into the closed bundle because Evidence Gateway derives it from the active private JWK. Do not overwrite the active private key in place. A candidate revision must be complete and checkable before it becomes active. @@ -58,7 +58,7 @@ signing: ``` `activeKeyId` must exactly match the private JWK's `kid`. Each retired file contains public material -only. Evidence assembles its JWKS endpoint from the active private key's public half and the +only. Evidence Gateway assembles its JWKS endpoint from the active private key's public half and the configured retired public files. You do not publish a separate operator-built JWKS beside it. ## Validate and coordinate consumer approval @@ -80,7 +80,7 @@ the rotation. ## Activate and observe -Deploy the exact checked revision and restart Evidence. Confirm readiness, then inspect the public +Deploy the exact checked revision and restart Evidence Gateway. Confirm readiness, then inspect the public endpoint: ```sh @@ -92,7 +92,7 @@ The JWKS contains the new active public key and the old retired public key, with members. Send one authorized synthetic request and verify its `kid` with the consumer's approved overlap set. -Missing, unreadable, or mismatched signing material fails closed. Evidence never falls back to an +Missing, unreadable, or mismatched signing material fails closed. Evidence Gateway never falls back to an unsigned success. ## Retire the old public key @@ -110,11 +110,11 @@ Remove the retired public file and its `retiredPublicJwkFiles` entry only in a l revision. Run fixtures and `evidence check` again, coordinate consumer removal, deploy, and confirm the JWKS no longer carries the old key. -Removing a verification key is not selective assertion revocation. Evidence has no credential +Removing a verification key is not selective assertion revocation. Evidence Gateway has no credential status or revocation lifecycle. It only changes which signatures a current trust set can verify. ## Related guidance -- [Build and deploy an Evidence project](../build-and-deploy-evidence-project/) -- [Evidence security model](../../security/evidence/) -- [Configure Evidence](../../configure/evidence/) +- [Build and deploy an Evidence Gateway project](../build-and-deploy-evidence-project/) +- [Evidence Gateway security model](../../security/evidence/) +- [Configure Evidence Gateway](../../configure/evidence/) diff --git a/docs/site/src/content/docs/tutorials/prove-an-evidence-project.mdx b/docs/site/src/content/docs/tutorials/prove-an-evidence-project.mdx index fc3e13fca..29cc2b6ee 100644 --- a/docs/site/src/content/docs/tutorials/prove-an-evidence-project.mdx +++ b/docs/site/src/content/docs/tutorials/prove-an-evidence-project.mdx @@ -1,6 +1,6 @@ --- -title: Prove an Evidence project -description: Add fixtures that describe your own requirement and run them through the Evidence evaluator before a production build. +title: Prove an Evidence Gateway project +description: Add fixtures that describe your own requirement and run them through the Evidence Gateway evaluator before a production build. status: current owner: registry-docs source_repos: @@ -16,7 +16,7 @@ standards_referenced: [] Start with a reviewed editable project. If you need to create one, [connect an institution source from OpenAPI](../connect-an-institution-source/) before adding -fixtures. Fixtures are executable claims about your own Evidence project. They are not sample data +fixtures. Fixtures are executable claims about your own Evidence Gateway project. They are not sample data for a first run and they must not be generated from an unrelated domain. Use them when your source, requirement, and derivation are ready for review. Local assurance may @@ -101,11 +101,11 @@ Build and hand off only when these facts are recorded together: Keep the governed bundle unchanged across environments where practical. Bind environment-specific paths, secret roots, audit storage, listener settings, and trust files through each environment's -runtime file. [Build and deploy an Evidence project](../build-and-deploy-evidence-project/) covers +runtime file. [Build and deploy an Evidence Gateway project](../build-and-deploy-evidence-project/) covers the target-host ceremony. ## Next - [Verify an assertion as a consumer](../verify-an-assertion-as-a-consumer/) -- [Rotate Evidence signing keys](../move-evidence-to-production-signing/) -- [Build and deploy an Evidence project](../build-and-deploy-evidence-project/) +- [Rotate Evidence Gateway signing keys](../move-evidence-to-production-signing/) +- [Build and deploy an Evidence Gateway project](../build-and-deploy-evidence-project/) diff --git a/docs/site/src/content/docs/tutorials/publish-spreadsheet-secured-registry-api.mdx b/docs/site/src/content/docs/tutorials/publish-spreadsheet-secured-registry-api.mdx index 65517ac29..14e417fce 100644 --- a/docs/site/src/content/docs/tutorials/publish-spreadsheet-secured-registry-api.mdx +++ b/docs/site/src/content/docs/tutorials/publish-spreadsheet-secured-registry-api.mdx @@ -366,8 +366,8 @@ You turned a spreadsheet into two deliberately different surfaces: ## Next -- [See Evidence answer over a Relay API](../first-run-with-solmara-lab/) in the - composed Solmara Lab demo. +- [Get your first Evidence Gateway assertion](../first-evidence-assertion/) when a caller needs + a signed, minimum-disclosure answer instead of record access. - [Use your own spreadsheet](../use-your-spreadsheet/) after the sample path works. - [Connect an existing HTTP registry](../author-registry-project/) when the diff --git a/docs/site/src/content/docs/tutorials/refuse-unsafe-evidence-requests.mdx b/docs/site/src/content/docs/tutorials/refuse-unsafe-evidence-requests.mdx index eca81bc97..753234e1d 100644 --- a/docs/site/src/content/docs/tutorials/refuse-unsafe-evidence-requests.mdx +++ b/docs/site/src/content/docs/tutorials/refuse-unsafe-evidence-requests.mdx @@ -1,5 +1,5 @@ --- -title: See Evidence refuse unsafe requests +title: See Evidence Gateway refuse unsafe requests description: Cross the HTTP boundary with an unauthorized request, then prove that a modified assertion cannot be trusted. status: current owner: registry-docs @@ -17,7 +17,7 @@ standards_referenced: [] import QuickstartMeta from '../../../components/QuickstartMeta.astro'; Complete [Return a governed value](../return-a-governed-value/) before starting this tutorial. -You will reuse that project to observe two boundaries: Evidence denies a purpose the provider did +You will reuse that project to observe two boundaries: Evidence Gateway denies a purpose the provider did not authorize, and the verifier rejects a response changed after signing. @@ -48,7 +48,7 @@ evidencectl dev --detach ``` ```text -Evidence ready at http://127.0.0.1:8080 +Evidence Gateway ready at http://127.0.0.1:8080 Mint ready at http://127.0.0.1:8081 ``` @@ -175,7 +175,7 @@ echo 'TAMPER REFUSED' ``` ```text -evidencectl: Evidence response verification failed +evidencectl: Evidence Gateway response verification failed TAMPER REFUSED ``` @@ -202,5 +202,5 @@ Return to the registry terminal and press `Ctrl+C`. ## Next - [Connect an institution source](../connect-an-institution-source/) -- [Configure Evidence](../../configure/evidence/) -- [Review the Evidence security model](../../security/evidence/) +- [Configure Evidence Gateway](../../configure/evidence/) +- [Review the Evidence Gateway security model](../../security/evidence/) diff --git a/docs/site/src/content/docs/tutorials/request-evidence-as-sd-jwt-vc.mdx b/docs/site/src/content/docs/tutorials/request-evidence-as-sd-jwt-vc.mdx index c00c40d08..4ebe18124 100644 --- a/docs/site/src/content/docs/tutorials/request-evidence-as-sd-jwt-vc.mdx +++ b/docs/site/src/content/docs/tutorials/request-evidence-as-sd-jwt-vc.mdx @@ -1,6 +1,6 @@ --- -title: Request Evidence as SD-JWT VC -description: Enable SD-JWT VC on one governed Evidence grant, request the second serialization over HTTP, and verify the stored credential offline. +title: Request Evidence Gateway as SD-JWT VC +description: Enable SD-JWT VC on one governed Evidence Gateway grant, request the second serialization over HTTP, and verify the stored credential offline. status: current owner: registry-docs source_repos: @@ -16,7 +16,7 @@ standards_referenced: [] Start with a complete governed project. If you need to create and validate one, [connect an institution source from OpenAPI](../connect-an-institution-source/), then -[prove the Evidence project](../prove-an-evidence-project/). Evidence can serialize the same +[prove the Evidence Gateway project](../prove-an-evidence-project/). Evidence Gateway can serialize the same stateless assertion as signed JWS or SD-JWT VC. The question, source access, derivation, supported values, subject binding, purpose, audience, signing key, and audit boundaries remain the same. @@ -34,7 +34,7 @@ answers: disclosure: top-level ``` -`birthCertificate` is adopter configuration, not a built-in Evidence claim. The `top-level` mode +`birthCertificate` is adopter configuration, not a built-in Evidence Gateway claim. The `top-level` mode makes each direct field independently disclosable. A nested value, such as `placeOfBirth`, remains one atomic disclosure. @@ -119,7 +119,7 @@ set for the run, and `verification-policy.json` comes from the consumer's reques records, not from the credential. An unprojected value has one root disclosure. A configured structured value has one disclosure for -each direct field. Evidence's current verifier checks the complete stored credential. It does not +each direct field. Evidence Gateway's current verifier checks the complete stored credential. It does not verify a selectively disclosed presentation from a wallet. ## Keep the boundary explicit @@ -137,7 +137,7 @@ outside this minimum path. Provider metadata is published at `/.well-known/jwt-vc-issuer`, and signing keys remain at `/.well-known/evidence/jwks.json`. Both are discovery. Approve trust independently through -[Manage Evidence verifier trust](../manage-evidence-verifier-trust/). +[Manage Evidence Gateway verifier trust](../manage-evidence-verifier-trust/). For deterministic source-tree proof of the full format and tamper refusals, see the [maintained SD-JWT VC demo](https://github.com/registrystack/registry-stack/blob/main/products/evidence/SD-JWT-VC-DEMO.md). diff --git a/docs/site/src/content/docs/tutorials/return-a-governed-value.mdx b/docs/site/src/content/docs/tutorials/return-a-governed-value.mdx index 782da8bac..50b51649d 100644 --- a/docs/site/src/content/docs/tutorials/return-a-governed-value.mdx +++ b/docs/site/src/content/docs/tutorials/return-a-governed-value.mdx @@ -1,6 +1,6 @@ --- title: Return a governed value -description: Add a controlled non-boolean answer to the first Evidence project and verify the signed result. +description: Add a controlled non-boolean answer to the first Evidence Gateway project and verify the signed result. status: current owner: registry-docs source_repos: @@ -15,7 +15,7 @@ standards_referenced: [] import QuickstartMeta from '../../../components/QuickstartMeta.astro'; -Complete [Get your first Evidence assertion](../first-evidence-assertion/) before starting this +Complete [Get your first Evidence Gateway assertion](../first-evidence-assertion/) before starting this tutorial. You will add a governed age-bracket question to that project while keeping its adult status question. The same date of birth can then answer either question without disclosing the date or exact age. @@ -25,7 +25,7 @@ date or exact age. time="About 10 minutes" level="Local development with synthetic data" prerequisites={[ - 'The completed first Evidence assertion tutorial', + 'The completed first Evidence Gateway assertion tutorial', 'Its adult-status project and registry.py', 'Python 3', 'A shell with curl', @@ -98,7 +98,7 @@ disclosure: The new question uses the same OpenAPI operation, projected fact, and subject mapping as adult status. `values` defines the complete category list. The local compiler turns that list into the -codelist enforced by the Evidence runtime. +codelist enforced by the Evidence Gateway runtime. ### `derivations/age-bracket.rhai` @@ -119,7 +119,7 @@ fn answer(facts, selectors, context) { } ``` -The script chooses one category from the reviewed list. Evidence rejects any other return value +The script chooses one category from the reviewed list. Evidence Gateway rejects any other return value before constructing or signing an assertion. ## Start the updated project @@ -131,11 +131,11 @@ evidencectl dev --detach ``` ```text -Evidence ready at http://127.0.0.1:8080 +Evidence Gateway ready at http://127.0.0.1:8080 Mint ready at http://127.0.0.1:8081 ``` -The command compiles both files in `questions/` into the same local Evidence service. The adult +The command compiles both files in `questions/` into the same local Evidence Gateway service. The adult status question remains available. Authentication, source bounds, signing, verification, and audit apply to both questions. @@ -194,12 +194,12 @@ The source value `2012-05-20` is currently in the `under-18` category. The verif does not include the date of birth, exact age, name, or `person_id`. Minimum disclosure is relative to the authorized purpose. A boolean was enough for the first -question. A controlled category is enough for this service-path decision. Evidence protects both +question. A controlled category is enough for this service-path decision. Evidence Gateway protects both without treating boolean answers as the only minimized form. ## Inspect the audit and clean up -Stop the local Evidence services: +Stop the local Evidence Gateway services: ```sh evidencectl dev stop @@ -228,8 +228,8 @@ Return to the registry terminal and press `Ctrl+C`. ## Next -- [Control which applications can request Evidence](../control-who-can-request-evidence/) -- [See Evidence refuse unsafe requests](../refuse-unsafe-evidence-requests/) +- [Control which applications can request Evidence Gateway](../control-who-can-request-evidence/) +- [See Evidence Gateway refuse unsafe requests](../refuse-unsafe-evidence-requests/) - [Bind two people to one relationship assertion](../assert-a-role-bound-relationship/) -- [Configure Evidence](../../configure/evidence/) -- [Review the Evidence security model](../../security/evidence/) +- [Configure Evidence Gateway](../../configure/evidence/) +- [Review the Evidence Gateway security model](../../security/evidence/) diff --git a/docs/site/src/content/docs/tutorials/verify-a-registered-parent-with-opencrvs.mdx b/docs/site/src/content/docs/tutorials/verify-a-registered-parent-with-opencrvs.mdx index b49143665..88c313115 100644 --- a/docs/site/src/content/docs/tutorials/verify-a-registered-parent-with-opencrvs.mdx +++ b/docs/site/src/content/docs/tutorials/verify-a-registered-parent-with-opencrvs.mdx @@ -1,7 +1,7 @@ --- title: Issue registered-parent evidence from OpenCRVS description: >- - Connect Evidence to the public OpenCRVS demo, verify a registered-parent relationship, and + Connect Evidence Gateway to the public OpenCRVS demo, verify a registered-parent relationship, and return governed parent identifiers when the use case requires them. status: current owner: registry-docs @@ -29,7 +29,7 @@ receive them. level="Institution source with synthetic data" prerequisites={[ 'The completed role-bound relationship tutorial', - 'The Evidence toolset', + 'The Evidence Gateway toolset', 'Access to the public OpenCRVS demo', 'curl and an editor', ]} @@ -120,7 +120,7 @@ OpenCRVS does not publish this bounded subset at a stable URL. Registry Stack ma the tutorial and records its upstream review revision in the file. Review it against the target deployment before production use. -Create an editable Evidence project and disposable local keys: +Create an editable Evidence Gateway project and disposable local keys: ```sh evidencectl new registered-parent \ @@ -239,7 +239,7 @@ extractScript: adapters/opencrvs-birth-parents-extract.rhai factSchema: schemas/opencrvs-birth-parents-facts.schema.yaml ``` -`record-transformed` states that OpenCRVS returns a bounded birth record and Evidence reduces it +`record-transformed` states that OpenCRVS returns a bounded birth record and Evidence Gateway reduces it before disclosure. The fixed event type and status prevent the caller from turning this source into a general search proxy. A two-result ceiling lets extraction distinguish one match from an ambiguous national ID without paging through the registry. @@ -269,7 +269,7 @@ unset OPENCRVS_CLIENT_SECRET Paste each value copied from OpenCRVS at its prompt and press Enter. The generated `.gitignore` excludes the `secrets` directory. -Evidence resolves these logical secret references beneath that directory. It does not read the +Evidence Gateway resolves these logical secret references beneath that directory. It does not read the credentials from source YAML, requests, command arguments, or logs. ## Prepare the fixed birth search @@ -593,12 +593,12 @@ fn answer(facts, selectors, context) { } ``` -Evidence validates the returned object against the reviewed schema before signing it. The +Evidence Gateway validates the returned object against the reviewed schema before signing it. The derivation cannot add names, dates, addresses, or any other birth-registration field. ## Start the project -Compile the editable artifacts into a private local generation and start Evidence with Registry +Compile the editable artifacts into a private local generation and start Evidence Gateway with Registry Mint: ```sh @@ -606,14 +606,14 @@ evidencectl dev --detach ``` ```text -Evidence ready at http://127.0.0.1:8080 +Evidence Gateway ready at http://127.0.0.1:8080 Mint ready at http://127.0.0.1:8081 ``` -`dev` runs the real Evidence configuration check before either service becomes ready. Unresolved +`dev` runs the real Evidence Gateway configuration check before either service becomes ready. Unresolved draft markers, invalid schemas, inconsistent roles, or missing credentials stop the start. -## Send a real Evidence request +## Send a real Evidence Gateway request Read the mother's national ID without leaving its value in shell history: @@ -640,7 +640,7 @@ path that does not expose identifiers in shell history or process arguments. Preparation obtains short-lived local authorization and records verification expectations before a response exists. It does not contact OpenCRVS. -Send the request across the Evidence HTTP boundary: +Send the request across the Evidence Gateway HTTP boundary: ```sh curl -fsS \ @@ -653,7 +653,7 @@ curl -fsS \ --output opencrvs-parent.jws.json ``` -Evidence exchanges its client credentials for an OpenCRVS token, performs the fixed child search, +Evidence Gateway exchanges its client credentials for an OpenCRVS token, performs the fixed child search, projects the bounded parent fields, derives the relationship, and returns a signed flattened JWS. The caller cannot alter the event type, status, projection, or parent verification rule. @@ -785,5 +785,5 @@ files when you finish. - [Request a birth certificate SD-JWT VC from OpenCRVS](../issue-a-birth-certificate-vc-from-opencrvs/) - [Issue an immunization summary from DHIS2](../issue-immunization-evidence-from-dhis2/) - [Draft another institution source from OpenAPI](../connect-an-institution-source/) -- [Build and deploy an Evidence project](../build-and-deploy-evidence-project/) +- [Build and deploy an Evidence Gateway project](../build-and-deploy-evidence-project/) - [Verify an assertion as a consumer](../verify-an-assertion-as-a-consumer/) diff --git a/docs/site/src/content/docs/tutorials/verify-an-assertion-as-a-consumer.mdx b/docs/site/src/content/docs/tutorials/verify-an-assertion-as-a-consumer.mdx index 92dc2cae0..8c8a97859 100644 --- a/docs/site/src/content/docs/tutorials/verify-an-assertion-as-a-consumer.mdx +++ b/docs/site/src/content/docs/tutorials/verify-an-assertion-as-a-consumer.mdx @@ -1,5 +1,5 @@ --- -title: Verify Evidence as a consumer +title: Verify Evidence Gateway as a consumer description: Separate a stored response from independently retained trust and request expectations, then re-verify the decision offline. status: current owner: registry-docs @@ -15,17 +15,17 @@ standards_referenced: [] import QuickstartMeta from '../../../components/QuickstartMeta.astro'; -Complete [Get your first Evidence assertion](../first-evidence-assertion/) before starting this -tutorial. You will reuse that assertion to show why an application must not trust an Evidence +Complete [Get your first Evidence Gateway assertion](../first-evidence-assertion/) before starting this +tutorial. You will reuse that assertion to show why an application must not trust an Evidence Gateway payload because it arrived over HTTPS or because it can be decoded, and how independently retained trust and request expectations support later offline review.