registrystack / registrystack/registry-stack

bregctl dev docs: contract for tools running beside a dev session and the dev issuer token shape

Open
#1,083 0 comments 0 reactions 0 assignees View on GitHub
area:breg area:docs criticality:p3 documentation
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.