registrystack / registrystack/registry-stack

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

Open
#1,097 0 comments 0 reactions 0 assignees View on GitHub
area:breg area:docs documentation
Dominant language
Rust
Stars
2
Forks
0
Avg merge
2h 57m
Merged PRs (30d)
128

Description

## 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.

Contributor guide

Open the contributing guide

Research direction

Start with docs/site/src/content/docs/operate/breg.mdx and the referenced runtime_config.rs bounds, then inspect the client entry points taskAssertionEndpoint(), task_assertion_endpoint(), and CaseworkTaskAssertionSource. Check the v0.32.0 Casework changelog for context. Done means the site documents assertion issuer pairing and refusals, the RFC 8693 request and response wire form, and the stated JWKS cache bounds beside its default.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, markdown, python, rust
Domain
api, authentication, documentation, security
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
78/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.