What
Three parts of the BReg token verification contract are configured, enforced, and absent from the documentation site.
assertionIssuers pairs each client with the assertion issuers it may present. It is a runtime setting with its own schema constraints and refusals, and it does not appear on any configure or operate page. The only mention on the site is one changelog line.
- The RFC 8693 token exchange used for task-grant-bound access is undocumented as a wire form. Nothing on the site shows the exchange request or the response shape, so an integrator has to read the client source to build the call.
- The operate guide states the
jwksCache.cacheTtlSeconds default of 600 seconds but never states its accepted range. The runtime clamps it to 1 to 86400 and refuses outside that, which a reader discovers only from a refusal.
Evidence
rg assertionIssuers docs/site/src/content matches docs/site/src/content/docs/changelog.mdx alone. The runtime side is crates/registry-breg/src/runtime_config.rs lines 1169, 1199 to 1219 and the schema pointers at 2327, 2629, 2648 and 2656, plus crates/registry-casework/src/config.rs and crates/registry-evidence/src/config.rs.
rg token-exchange docs/site/src/content returns nothing. The exchange surface exists in the clients: taskAssertionEndpoint() in crates/registry-stack-client-node/casework/client.d.ts, task_assertion_endpoint() in the Python client, and CaseworkTaskAssertionSource in the Rust client, all listed in the v0.32.0 entry of products/casework/CHANGELOG.md.
docs/site/src/content/docs/operate/breg.mdx line 411 gives the 600 second default. crates/registry-breg/src/runtime_config.rs line 1618 clamps it: cache_ttl: seconds_bounded(raw.cache_ttl_seconds, 1, 86_400)?. The same function bounds outage_tolerance to 0 to 86400 (line 1623), also unstated.
Proposed fix
Add an assertionIssuers row to the operate guide's token table or to the verifier configuration section, saying what pairing it enforces and what a mismatch refuses. Document the token exchange request and response wire form once, in reference, with the grant type, the required parameters and the returned token's audience and lifetime. State the accepted range beside every JWKS cache default in the operate guide, not only the default.
Found while
Extracting reusable App Kit skills against Registry Stack v0.32.0.
What
Three parts of the BReg token verification contract are configured, enforced, and absent from the documentation site.
assertionIssuerspairs each client with the assertion issuers it may present. It is a runtime setting with its own schema constraints and refusals, and it does not appear on any configure or operate page. The only mention on the site is one changelog line.jwksCache.cacheTtlSecondsdefault of 600 seconds but never states its accepted range. The runtime clamps it to 1 to 86400 and refuses outside that, which a reader discovers only from a refusal.Evidence
rg assertionIssuers docs/site/src/contentmatchesdocs/site/src/content/docs/changelog.mdxalone. The runtime side iscrates/registry-breg/src/runtime_config.rslines 1169, 1199 to 1219 and the schema pointers at 2327, 2629, 2648 and 2656, pluscrates/registry-casework/src/config.rsandcrates/registry-evidence/src/config.rs.rg token-exchange docs/site/src/contentreturns nothing. The exchange surface exists in the clients:taskAssertionEndpoint()incrates/registry-stack-client-node/casework/client.d.ts,task_assertion_endpoint()in the Python client, andCaseworkTaskAssertionSourcein the Rust client, all listed in the v0.32.0 entry ofproducts/casework/CHANGELOG.md.docs/site/src/content/docs/operate/breg.mdxline 411 gives the 600 second default.crates/registry-breg/src/runtime_config.rsline 1618 clamps it:cache_ttl: seconds_bounded(raw.cache_ttl_seconds, 1, 86_400)?. The same function boundsoutage_toleranceto 0 to 86400 (line 1623), also unstated.Proposed fix
Add an
assertionIssuersrow to the operate guide's token table or to the verifier configuration section, saying what pairing it enforces and what a mismatch refuses. Document the token exchange request and response wire form once, in reference, with the grant type, the required parameters and the returned token's audience and lifetime. State the accepted range beside every JWKS cache default in the operate guide, not only the default.Found while
Extracting reusable App Kit skills against Registry Stack v0.32.0.