registrystack / registrystack/registry-stack
bregctl dev docs: issuer section constraints are only discoverable from refusals
- Dominant language
- Rust
- Stars
- 2
- Forks
- 0
- Avg merge
- 2h 57m
- Merged PRs (30d)
- 128
Description
## Use Case
An adopter composes one local issuer for a browser host, synthetic users and several products in `dev-clients.yaml`, following "Compose one local issuer" in `products/breg/DEV.md`.
## What we hit
The section documents the shape well, but these rules were only discoverable from refusals or from `crates/registry-thunderid-tooling/src/description.rs` and `crates/registry-bregctl/src/dev/config.rs`:
1. Limits: at most 8 resource servers, 8 interactive applications, 8 redirect URIs per application, 32 synthetic users, 8 exchange issuers, 32 clients and 16 token attributes per exchange issuer, 16 token attributes per application.
2. Synthetic users require at least one interactive application, and each user's `grants` must be non-empty and name scopes some resource actually offers. A user who needs no registry scope still needs a grant.
3. A human-only scope (for example a Casework administrator role) can be granted to a user only if some resource declares it. Declaring it under `issuer.resources` works; otherwise adopters invent a stand-in machine client just to make the scope exist.
4. `audience: null` in a grant resolves to the owner's default BREG audience, and its scope set is the union of the scopes of clients not mapped under `clientResources`.
5. `allowHumanFixture` on a client must be `true` exactly when its claims carry `registry_actor_kind: human`.
6. Application `origin` and `redirectUris` must be `http://127.0.0.1:` URLs: `localhost` and HTTPS origins are refused. This rules out a local HTTPS rehearsal against the dev issuer.
7. `eventDestinations` origins must be exactly `http://127.0.0.1:`, the HMAC key must be at least 32 bytes with no NUL, and compiled destination IDs must be bound all or none. The key is referenced as `secret:file/webhook-` in the rendered runtime.
8. `clientIdFile` and `assertionKeyFile` are both or neither, absolute, with a canonical private parent directory.
9. Every name in an application's `tokenAttributes` must be an attribute of at least one synthetic user, because the rendered user schema is the union of user attributes (see #1036 for the validation gap).
10. `--issuer-project` and `--issuer-image` semantics for a shared issuer beyond the example: what a borrower may declare, what is copied, what a restart of the owner means for a borrower.
Several refusals also group fields, for example `local browser application identity, audience, redirect or attributes are invalid`, so the adopter cannot tell which of the four failed.
## Proposed Behavior
- Add a reference table for the issuer section to `DEV.md` (field, type, constraint, default) covering the points above.
- Name the failing field and constraint in each refusal.
## Boundaries
- No change to the accepted shape or limits.
Contributor guide
Research direction
Start with the issuer section in products/breg/DEV.md, then compare its documented shape with the validation and refusal paths in crates/registry-thunderid-tooling/src/description.rs and crates/registry-bregctl/src/dev/config.rs. Add the requested field, type, constraint, and default reference details, and make refusals identify the failing field and constraint. Done means the accepted shape and limits are unchanged and the listed issuer rules are discoverable without relying on refusals.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 64/100