docs: write down the four decisions an integration has to make

[42-v]

docs: write down the four decisions an integration has to make

Merging this publishes nothing. vault42 releases are cut by pushing the annotated tag.

Why

The BeOn3 gap analysis produced 8 cutover blockers. Four were code and are being closed (#68 email claim, #71 role grants, plus the role-claim one that turned out to need no vault42 change). The other four are not bugs and not features — they are places where what vault42 does and what a relying party expects differ for a reason.

Undocumented, each gets rediscovered during a cutover, which is the worst possible time to be deciding it. docs/relying-parties.md decides them.

The four

Two audiences, one validator. A minted token must not carry vault42's own audience, or the holder of the mint scope turns "assert a subject downstream" into "act as that subject here." The audience rule and the token_type: mint claim are two independent controls saying the same thing, so collapsing them removes one. The relying party accepts an audience set — and if eleven services each hand-roll their own validation, that is an argument for the shared wrapper rather than against the plural.

Service-to-service identity stays with the platform. vault42 is the authority on who a user is, not on whether your notifications service may call your payments service. Routing that through a signing oracle buys central configuration and costs a runtime dependency on vault42 for every internal call, on a path with no user in it. If it must be centralised anyway, the honest shape is a /client/token carrying a role set rather than one role — small, and it weakens nothing, because those tokens already carry client_id and already sit in vault42's own audience. Ask for that rather than working around it by minting an admin-ish subject.

Revocation is bounded, not immediate. Per-request introspection is precisely the cost self-contained tokens exist to avoid, and it would move vault42 from the login path onto every path with the availability requirements that implies. So the guarantee is stated instead: a ban stops renewal immediately and stops access within the access-token TTL — fifteen minutes by default. The doc says that number out loud and lists the three ways to shrink the window, with per-call introspection explicitly not among them.

Minted tokens stay short. The ceiling is the only bound on a leaked assertion, because vault42 keeps no record of a minted token beyond the audit event — so it is a control, not a default. Raising it to 60 minutes would quadruple the exposure of every leaked assertion to buy a scheduling convenience. The caller re-mints: 60/min per client against one mint per user per fifteen minutes is ~900 concurrent users, and a service minting per request rather than per session hits it far sooner. That is the intended pressure.

Also stated

The two things vault42 will not assert, because both are read the other way from outside: a minted email is the caller's word about a subject vault42 never looked up, and X-Vault-App is routing and branding, not tenancy.

Verification

Every figure is taken from the source rather than remembered:

VAULT_ACCESS_TOKEN_TTL default 15m   internal/config/config.go:108
60/min per client_id, fail-closed    docs/api.md:3156
AR-16 (no client-to-subject policy)  docs/security.md:326
tenancy statement                    docs/spec.md section 0.8
900 concurrent users                 60 × 15, stated so it can be checked

go test ./tests/spec/         ok
go test ./tests/compliance/   ok

docs/README.md says "Adding a document means adding a row here", so it has one.