registrystack / registrystack/registry-stack
bregctl dev docs: contract for tools running beside a dev session and the dev issuer token shape
- Dominant language
- Rust
- Stars
- 2
- Forks
- 0
- Avg merge
- 2h 57m
- Merged PRs (30d)
- 128
Description
## Use Case
A tool runs beside a `bregctl dev` session instead of inside it: a host launcher that starts `bregctl dev start`, then supervises its own Casework and web host against that session's BREG and issuer, and scripted tests that sign in synthetic users.
## What we hit
Building such a launcher required reading source and probing the running issuer for each of these. None are documented as stable, so any of them can change without notice.
**Session report and lifecycle**
1. `bregctl dev start --format json` fields a launcher needs: `audience`, `issuer`, `clientAssertionAudience`, `tokenEndpoint`, and `clients[]` with `id`, `accessProfiles`, `scopes`, `clientIdFile` and `assertionKeyFile`. Client assertion keys are EC P-256 JWKs with `alg: ES256`.
2. The BREG audience is a random `urn:breg:dev:` per session. A host cannot keep a fixed audience across `dev stop --remove`.
3. Liveness: BREG runs as a child of `bregctl __dev-supervisor`, not of the caller. The only signals are `/ready` and the status in the private `state.json`, so wrappers read an internal file or poll.
4. `bregctl dev stop` for a project whose session never started refuses with `MISSING_SESSION`, so a cleanup path must check first or treat that code as success.
5. Log locations under the dev root, and that setting `REGISTRY_THUNDERID_TOOLING_DIAGNOSTICS` prints a bounded stderr tail for issuer bootstrap commands whose output is otherwise withheld.
**Tokens from the dev issuer (stock ThunderID)**
6. Access tokens are `typ: at+jwt` with exactly one `aud`; the client is in `client_id`, not `azp`. A host that calls BREG and Casework with one session token must configure both services with that same audience.
7. Requested scopes the user or application is not granted are dropped silently, not refused.
8. Application `tokenAttributes` are copied from user attributes into token claims.
9. The JWKS holds both RSA (RS256) and EC (ES256) keys.
10. `private_key_jwt` against this issuer needs the assertion `aud` to be the issuer origin (not the token endpoint URL), and the token request must carry `resource` and `scope`. Casework's `BregBinding` fields for this are documented in `RUNTIME-CONFIG.md`; the issuer-side rule is not stated in the BREG dev docs.
11. `/oauth2/authorize` requires `resource` and PKCE; the password grant is not supported. Without PKCE the issuer redirects back to the application with `error=invalid_request` rather than showing an error page.
## Proposed Behavior
- Add a "Run tools beside a dev session" section to `products/breg/DEV.md`: the report fields that are a supported contract, the audience and client-key shape, how to wait for and detect a stopped session, cleanup semantics, diagnostics.
- Add a short token-shape note for the dev issuer (points 6 to 11) that hosts and services can rely on.
- Consider a stable `bregctl dev status --format json` so wrappers stop reading `state.json`.
## Boundaries
- Documentation plus, at most, a read-only status command. No new lifecycle behavior.
Related: #874 (stop without a session).
Scripted synthetic-user tokens: #1084.
Contributor guide
Research direction
Start with products/breg/DEV.md and compare its existing guidance with the fields from bregctl dev start --format json. Read RUNTIME-CONFIG.md for the existing BregBinding terminology, then document the supported session, token, key, lifecycle, cleanup, and diagnostics behavior described here. Done means the beside-session workflow and dev issuer token rules are captured without adding lifecycle behavior; a read-only status command is optional.
Written by the indexing model from the issue text.
Assessment
- Domain
- authentication, cli, documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 72/100