registrystack / registrystack/registry-stack

bregctl dev docs: issuer section constraints are only discoverable from refusals

Open
#1,082 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

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

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.