Skip to content

BReg docs: assertionIssuers, the token exchange wire form, and the JWKS cache bounds are undocumented #1097

Description

@jeremi

What

Three parts of the BReg token verification contract are configured, enforced, and absent from the documentation site.

  1. 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.
  2. 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.
  3. 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.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:bregBReg ownership.area:docsDocumentation site ownership.documentationImprovements or additions to documentation

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions