This is the decision record as it was written, grilled and shipped. It’s copied from our repository unedited, apart from customer, partner and bank names, which read [redacted]. It was written for the people and agents building the product, so expect internal shorthand, and the mistakes are left in.
ADR-821: External machine identity and institution connections
Status: Shipped — 2026-09-30
The platform half of ADR-694, carved out so that two series can stand on it without either waiting for the other: the corporate banking stream (statement ingest, ADR-694) and the cards stream (the processor seam, ADR-820).
Outcome
External systems now authenticate as machine principals registered on the platform, and each tenant configures institution connections that pin which client may act for it; the gateway resolves a machine token to a tenant and connection frame, and refuses /api/auth/* (F-1566, landed earlier and kept). Outside development the machine path refuses every bearer until the Entra issuer and audience are configured, and one authored test is skipped because a settings command’s four-eyes action is settings.publish.
Context
The Problem
Two ADRs need the same three things and neither is built. ADR-694 D13 declares an
InstitutionConnection settings row for every institution we exchange with; D18 chooses OAuth2
client credentials as the first machine-to-machine identity, the pattern every later external
system inherits; and its bite 14 adds IExternallyAuthenticatedCommand, the marker that keeps a
machine’s command out of four-eyes. ADR-820 reuses all three for a card processor and, as
written, waits on ADR-694’s fourteen bites for the two it needs.
ADR-694 also left one gap that both consumers hit: it keeps the OAuth client id on the per-tenant connection row, but an inbound token has to resolve its tenant before any tenant settings can be read. Nothing says how a client id maps to a tenant (F-1562).
The platform has no machine identity of any kind today. Every endpoint is user-authenticated
through the gateway (ADR-067, ADR-376 D9) or [PublicEndpoint]. The one unattended caller,
provisioning, carries a service token minted with the System identity and no tenant.
What Already Exists
- Identity crosses the gateway signed. The gateway mints a short-lived token carrying
tenant_id,sub,email,external_id,rolesand the platform role, signed with a key the API validates (ADR-376 D9,IdentityTokenIssuer,IdentityToken). The API reads identity from that token and nothing else. - A person is resolved before a tenant is chosen. The gateway posts the Entra identity to
/api/auth/resolve; the platform-levelUserinLedgerTM.Identityanswers with the tenants the person may enter. A machine principal needs the same step with a different subject. - Entra ID is the IdP (ADR-067). It issues client-credentials tokens to registered applications; the token carries the application id, not a user.
- Four-eyes eligibility is derived (ADR-197):
ICommand && !ISystemCommand && !IFourEyesControlCommand.ISystemCommandmeans dispatched asUserId.System, which a machine caller is not. - The identity frame names an actor and an origin (
IdentityFrame.SystemActingAs, ADR-728), and the day-end lock reads the origin (ADR-142). - ADR-694’s design for the row (D13), the identity (D18), the marker (bite 14), the
connection settings commands and their
connectivity.*keys (D21), and the plan’sInstitutionConnectionrecord shape.
Scope
This ADR covers:
InstitutionConnectionas tenant settings vocabulary: the generic row, and the rule that a feature attaches its own facet keyed by the connection.- The machine principal: a platform-level record binding an IdP client id to one tenant and one connection, registered by a platform administrator, never in tenant settings or YAML.
- The gateway path for a client-credentials token: validate, resolve the principal, mint the identity token with the tenant and the connection.
- The API side: the connection identity frame, the tenant binding, the day-end lock rule.
IExternallyAuthenticatedCommandand its term in the four-eyes and grantability derivations, with the architecture tests and the catalogue convention.- A whoami endpoint so the whole path is demonstrable with no feature above it.
Out of scope: any statement ingest (ADR-694 keeps the delivery, the doors, the readers and the provisional ledger); any card contract (ADR-820); mTLS (layerable at the gateway later, as ADR-694 D18 says); rotation of the IdP secret (the IdP’s).
Decisions
1. InstitutionConnection is a tenant settings row with a generic core, and features attach facets keyed by it
The row is ADR-694 D13’s, moved here: key, institution name, BIC, and transport (a name and
whether it can stream). Nothing about statements, feeds or cards is on it, and the IdP client id
is not on it either: which application speaks for a connection is the machine principal’s fact
(Decision 2), and a second copy on the row would be two answers to one question. The list query
shows the enabled principals beside each row instead. A feature that needs more declares its own settings row
keyed by InstitutionConnectionId: ADR-694’s feed authority, intraday style and formats become a
statement facet it owns; ADR-820’s processor kind, environment, base address and decision budget
are already such a facet.
Why a core and facets, not one wide row. The cards ADR and the statements ADR each add
fields the other never reads. One wide row is a bool per product on a shared type, the
signal CLAUDE.md names for a shared concept about to drift.
Commands are ADR-694 D21’s, moved here with their keys: AddInstitutionConnectionCommand,
AmendInstitutionConnectionCommand, RemoveInstitutionConnectionCommand, each
ISettingsCommand<InstitutionConnectionSettings> under connectivity.*.
Removal is refused while anything names the connection, by the validator. The settings
handler cannot see the facets, which live in other feature projects, so each feature registers an
IInstitutionConnectionFacet naming the facet it holds for a connection, and the remove
command’s validator asks every one, and asks IMachinePrincipalReader whether an enabled
principal still speaks for the connection, because a token minted with a connection claim that
no settings row explains is a claim an auditor cannot resolve. It is a validator rule and not a
handler check because the settings commands are four-eyes eligible: a handler check would
refuse only after a checker approved, while a validator refuses the maker at once and re-runs at
approval (ADR-780 D9). The settings page lists facets and principals under each connection.
2. A machine principal is a platform record binding one client id to one tenant and one connection
The IdP authenticates the caller and says only which application it is. Which tenant that
application may enter, and which connection it speaks for, is ours to say, and it must be
answerable before any tenant settings are read. So it is a platform-level record beside the
platform User: MachinePrincipal in LedgerTM.Identity on the platform store, keyed by the
IdP client id, holding the tenant, the connection key, and whether it is enabled.
One principal, one tenant, one connection. A processor serving two of our tenants is two registered applications at the IdP and two principals here. Registering a client id that is already registered, for any tenant, is refused. The alternative, one principal with a list of tenants, needs the token to say which tenant it means on each call, and a stolen credential then reaches every tenant on the list. ADR-694 D18 bounded a credential’s blast radius to one institution’s accounts; this bounds it to one tenant first.
A principal holds no grants, and it holds an actor. What a connection may dispatch is derived
from the catalogue (Decision 5), never stored on the principal. What it does hold, beside the
client id, the tenant and the connection, is a UserId minted at registration, the way a platform
User holds one, so that every event a connection causes is attributed to an actor the audit
trail can name without a machine masquerading as a person or as the system. Two events:
MachinePrincipalRegistered, MachinePrincipalRevoked. Revocation is soft: the record is listed
as revoked, and registering the same client id for the same tenant and connection again
re-enables it with a second registration event. Registering an enabled principal for the same
binding is a no-op; registering a client id bound to any other tenant or connection is refused,
revoked or not, because rebinding would put two tenants on one principal’s history.
Registered through platform endpoints under the platform role, never by tenant settings and
never by YAML. The binding is a security decision about who may enter a tenant, the same class
as onboarding a person, and it is taken by the role that onboards people. Register, revoke,
resolve and the two list endpoints are minimal APIs beside /api/auth/resolve and the
provisioning endpoints, gated by IPlatformAuthority against platform.administer, taking
request records and writing the platform store through its own session as the User aggregate
does. They are not Wolverine commands, for the reason the resolve endpoint already records: the
platform store is not integrated with Wolverine, a Wolverine chain needs a tenant frame a
platform administrator does not have, and a tenant catalogue key would let a tenant’s own
administrator grant themselves the right to register a machine. No new catalogue keys, no
four-eyes question, because four-eyes captures tenant commands and these are neither. There is
no screen in this ADR, because there is no platform administration screen for anything yet.
The development and simulation principals are one idempotent seed step. It runs in the
simulation seed phase beside SeedDevMember, registers a per-tenant client id for the
sim-processor connection only where the tenant’s settings hold that row, and is safe to run
again. Deleting a tenant revokes its principals, so a re-provisioned tenant does not meet its own
stale binding.
Platform-level four-eyes is a recorded gap. A second pair of eyes on who may enter a tenant is worth an ADR once a second platform-level mutation appears; until then the platform role and the two events are the controls, deferred and dated in §Notes rather than pretended.
Every resolution attempt is recorded, refused ones included. The resolve endpoint writes a
MachineResolutionAttempt document on the platform store for every call: the client id, the
outcome (Resolved, UnknownClient, Revoked), and when. It returns the outcome and never
throws, because a thrown refusal would roll the attempt back with it. A client id probing the
endpoint leaves a trail the platform role can list; a refused caller has no tenant, so no
tenant-scoped audit could hold it. The gateway does not proxy /api/auth/* from outside: those
are its own server-side calls, and exposing them would let any signed-in person resolve any
client id. That also closes the same exposure on the existing person resolve.
3. The gateway resolves a client-credentials token exactly as it resolves a person, and mints the same token
A request arriving with an IdP client-credentials bearer token is validated against the IdP
(ADR-067’s discovery document, the same authority). The gateway posts the application id to
/api/auth/resolve-machine; the API answers from the MachinePrincipal, or refuses. On success
the gateway mints the identity token with tenant_id set to the principal’s tenant, sub set
to the actor the principal holds (Decision 2), email set to the client id, and a new
connection claim naming the connection key; the principal id derives from the client id. The API reads
identity from that token and nothing else, as ADR-376 D9 requires; no new header, no new
signing key.
The gateway caches a resolved principal per client id for sixty seconds. A processor asks for an authorisation many times a second and a revocation happens once a year; resolving on every call would spend a share of ADR-820’s decision budget on a question whose answer does not change. A revoke therefore takes effect within a minute, which is shorter than the IdP token’s own life. The cache holds refusals for the same sixty seconds, so a probing client id costs one resolve a minute.
A development machine-token endpoint stands in for the IdP, and only there. The gateway issues a client-credentials-shaped token for a registered development or simulation principal when the environment is Development or Testing, and refuses the endpoint anywhere else, the same check ADR-376 put on the dev login. It stands in for token issuance only: the request still goes through resolve-machine, the cache and the mint, so the whole path runs in development and in the gateway tests.
The machine path runs first, and validates what a bank’s security team expects. The machine
middleware reads the bearer before the gateway strips inbound authorisation headers and before
either person middleware, and short-circuits: a bearer is a machine, a cookie is a person, and a
request carrying both is a machine. The issuer is pinned to our own Entra directory and the
audience to the API’s application id, so an application in any other directory cannot present a
token; the client id is read from the v2 azp claim, falling back to v1 appid. A development
token is signed with the gateway’s own identity signing key under a distinct audience, so the
API refuses it as an identity token, and it is accepted only where the development login is, so
it never validates against the discovery document and never exists outside Development and
Testing. The cache is in memory per gateway instance; there is one
instance today, and a second would each hold a revocation for at most sixty seconds.
Why resolve through the API rather than the gateway holding the map. The gateway holds no data of its own today; the person path already resolves through the API, and a second store in the gateway would be a second answer to “who may enter this tenant”.
4. On the API the caller is a connection, and the lock lets it through
The identity frame gains an origin, Person, System or External; the existing
SystemOriginated flag becomes derived from it so nothing that reads the flag changes.
IdentityFrame.ForConnection(tenant, actor, principal, connection) has origin External, its
actor is the UserId the principal holds (Decision 2), its email is the client id, and it carries
the principal and the connection, which ICurrentConnection exposes to a handler that needs
them. A message that implements IConnectionScoped and names a different connection than the
frame’s is refused before its handler; a frame with no connection binds nothing, so a person
or the system may dispatch a connection-scoped message. ADR-694 D18’s rule that a connection
may report only on its own institution’s accounts is the first instance. Whoami answers from the
frame, never from settings: the connection key from the claim, its id derived, the client id
from the frame’s email.
The connection frame holds for the first hop only. A message the API publishes is dequeued
into a system frame, so a cascade runs as the system and ICurrentConnection is empty there.
This ADR states that and stops; whether origin and connection travel as envelope headers is
ADR-694’s and ADR-820’s to decide when a cascade needs them.
The day-end lock lets an external origin through. ADR-142 refuses a person’s mutation while
day-end runs and passes a system-originated one. An external system cannot wait for our
day-end: a processor’s authorisation must be answered now, and a bank’s push arrives when the
bank sends it. So the lock passes System and External, and the receiving feature decides
what an external act may touch during day-end. ADR-694 holds a pushed entry provisional; ADR-820
writes to a stream day-end does not hold. Refusing at the lock would turn every day-end into a
processor outage.
5. What a connection may dispatch is derived from the catalogue, and no human can be granted it
IExternallyAuthenticatedCommand marks a command dispatched by an authenticated non-human
principal. Eligibility becomes ICommand && !ISystemCommand && !IFourEyesControlCommand && !INotFourEyesGated && !IExternallyAuthenticatedCommand: neither ISystemCommand, which means UserId.System, nor
eligible, because a bank’s push or a processor’s authorisation cannot wait for an approver.
The catalogue carries the kind, so queries are covered too. Every permission key is still
catalogued (ADR-118), and a key has a kind: Human, SystemInternal or
ExternallyAuthenticated, held as a second set beside the existing system-internal one. The
kind is data, so the grant handler reads it: UserGroup.GrantPermissions refuses an externally
authenticated key for a human role, and the whoami query, which carries no command marker, is
refused the same way by its kind.
One rule answers what a frame may hold, and both permission paths call it. A connection frame is permitted every externally authenticated key and no other; a person frame is permitted no externally authenticated key, even a tenant administrator who otherwise holds everything. That rule is one static function over the origin and the kind, called by the HTTP permission middleware and by the bus authorisation middleware before either consults a person’s grants, because a principal has no member record to hold grants and a person’s wildcard must not reach a machine’s key. Deny-by-default holds in both directions with nothing stored on the principal.
A marked command in a person frame is refused before its handler; in a system frame it runs,
because a cascade after the first hop is a system frame (Decision 4) and refusing there would
refuse every marked command’s own follow-on work. The architecture tests
gain three checks: every command carrying the marker has a catalogue key of the matching kind,
every key of that kind names a type carrying the marker or an IQuery<T> pinned to that key,
and the four-eyes derivation carries the fifth term (the fourth, INotFourEyesGated, is
ADR-780’s).
6. The path is demonstrable with nothing above it
GET /api/connections/whoami, a query under connectivity.whoami of the externally
authenticated kind, answers the tenant, the principal and the connection the caller resolved
to. A registered simulation principal, a token from the development machine-token endpoint,
and that endpoint are a two-minute demo.
Proof runs on both sides, and the rules with no production subject are proven as rules. The
component suite proves the API side by minting the identity token with the signing key, the
service-token precedent, and calling the API: the frame, the whoami answer, the grant refusal.
The lock rule, the marker rule and the other-connection refusal have no production command in
this ADR to carry them, and a query passes the lock before identity is read, so they are proven
as unit tests over the middleware with a stubbed frame and message. The gateway suite in
LedgerTM.Tests/Gateway proves the gateway side through the development machine-token endpoint:
resolve, the sixty-second cache with a fake clock, the mint, a revoke taking effect after the
cache expires, and the proxy refusal. Every later external system inherits these tests.
Contracts
Ids — InstitutionConnectionId (slug-derived, ADR-422), MachinePrincipalId
(name-derived from the client id).
Contract types — all in LedgerTM.Infrastructure.Contracts, because the identity frame and
the middlewares live there and LedgerTM.Contracts depends on it, not the reverse. Namespace
LedgerTM.Contracts.Connectivity (the precedent is LedgerTM.Contracts.Authorisations, already
in that project): InstitutionConnection (key, name, BIC, transport), ConnectionTransport
(name, streaming capable), IInstitutionConnectionFacet, IInstitutionConnectionReader,
IMachinePrincipalReader (enabled principals, and the actor a connection frame runs as),
IConnectionScoped. Namespace LedgerTM.Infrastructure.Contracts.AccessControl:
IExternallyAuthenticatedCommand, PermissionKind, IdentityOrigin,
IdentityFrame.ForConnection, ICurrentConnection, PermissionCatalog.PermitsFrame, the
connection token claim.
Settings — InstitutionConnectionSettings (tenant vocabulary, in LedgerTM.Infrastructure).
Commands — AddInstitutionConnectionCommand, AmendInstitutionConnectionCommand,
RemoveInstitutionConnectionCommand — ISettingsCommand<InstitutionConnectionSettings>, keys
connectivity.add-institution-connection, connectivity.amend-institution-connection,
connectivity.remove-institution-connection.
Platform endpoints (minimal APIs in LedgerTM.Identity, gated by IPlatformAuthority
against platform.administer; not commands) — register a machine principal, revoke one, list
them, list resolution attempts; and POST /api/auth/resolve-machine, unauthenticated like its
person sibling, answering an outcome and never throwing.
Events — MachinePrincipalRegistered, MachinePrincipalRevoked (on the MachinePrincipal
aggregate in LedgerTM.Identity, platform store).
Read documents — MachineResolutionAttempt (platform store: client id, outcome Resolved |
UnknownClient | Revoked, when).
Queries — ListInstitutionConnectionsQuery (key connectivity.list-institution-connections;
rows with attached facets and enabled principals), ConnectionWhoAmIQuery (key
connectivity.whoami, kind ExternallyAuthenticated; answers tenant, principal id and client
id, connection id and key), ListPermissionsQuery gains the kind.
Consumed — IdentityToken and IdentityTokenIssuer (ADR-376 D9), IPlatformAuthority,
FourEyesEligibility, PermissionCatalog, SystemLockMiddleware (ADR-142),
AuthorizationMiddleware, HttpPermissionMiddleware, UserGroup.GrantPermissions.
Changed — FourEyesEligibility.IsEligible gains the fifth term; IdentityToken gains the
connection claim; IdentityTokenIssuer.Mint gains the connection; IdentityFrame gains
Origin, Principal and Connection with SystemOriginated derived; PermissionCatalog gains
ExternallyAuthenticatedKeys, KindOf and PermitsFrame, and IsGrantable reads the kind;
UserGroup.GrantPermissions refuses an externally authenticated key; HttpPermissionMiddleware
and AuthorizationMiddleware call PermitsFrame; the gateway refuses to proxy /api/auth/*;
ForbiddenException gains a constructor taking the key and a message, so a refusal can name the
marker or both connections; ISystemCommand’s summary names PermissionCatalog.KindOf.
Removed — none. ADR-694 D13, D18, D21 and bite 14’s marker are superseded by reference: its plan shrinks to the statement facet, the push door and the readers.
Prior art
python3 scripts/adr/prior_art.py --concept "external machine identity client credentials institution connection tenant resolution client id" returned no ADR title and three proposal
documents. The candidates below come from ADR-694, ADR-376 and the AccessControl folder.
| Declared | Search returned | Verdict |
|---|---|---|
InstitutionConnection, InstitutionConnectionId, ConnectionTransport, InstitutionConnectionSettings, AddInstitutionConnectionCommand, AmendInstitutionConnectionCommand, RemoveInstitutionConnectionCommand, ListInstitutionConnectionsQuery |
ADR-694 D13, D21 and its plan’s record shape, Proposed, unbuilt | reuse, moved — the generic core keeps ADR-694’s names; feed authority, intraday style and formats leave for a statement facet ADR-694 owns |
IExternallyAuthenticatedCommand |
ADR-694 bite 14 (F2); IUnauthenticatedCommand means the opposite (no principal at all); ISystemCommand means UserId.System |
reuse, moved — the same marker, decided once here |
MachinePrincipal, MachinePrincipalId, MachinePrincipalRegistered, MachinePrincipalRevoked, the register and revoke endpoints |
the platform User aggregate in LedgerTM.Identity with UserExternalLookup (a person keyed by IdP identity); ServiceTokenIssuer (ADR-376 D9, the System identity for provisioning); ProvisioningEndpoints and ApproverCredentialEndpoints (minimal APIs on the platform store under IPlatformAuthority) |
genuinely new for the principal, reuse the pattern for the endpoints — a non-human principal bound to one tenant and one connection; a User is a person with memberships, and the service token has no tenant by design |
/api/auth/resolve-machine |
/api/auth/resolve for a person, a minimal API because the platform store is conditionally registered and Wolverine.HTTP code-gen would fail |
extend the pattern — same step, same shape of endpoint, a different subject; its own endpoint because the answer differs (one tenant, never a list) |
IdentityFrame.ForConnection, External origin, ICurrentConnection |
IdentityFrame.ForUser, IdentityFrame.SystemActingAs (ADR-728), ICurrentUser |
extend — a third frame kind; the lock’s origin rule gains one value |
connection token claim |
tenant_id, sub, platformRole claims on IdentityToken |
extend — one claim; no new header, no new key |
FourEyesEligibility (the fifth term) |
IFourEyesGate, FourEyesChainScope, INotFourEyesGated (ADR-780: a command a checker cannot read) |
extend — one more term in the existing derivation; INotFourEyesGated answers a different question (reviewable or not), and a machine’s command is excluded for who dispatches it, not for what a checker could read |
ISystemLockState (the External origin) |
SystemLockMiddleware, ISystemLockExempt, SystemLockedException (ADR-142) |
extend — the lock already reads an origin and already exempts the system; External is one more value it passes, and ISystemLockExempt per command was rejected because every externally authenticated command would carry it |
IdentityTokenIssuer (the connection claim) |
IdentityToken (ADR-376 D9: the claims the gateway mints) |
extend — one claim on the same token, same key, same audience |
IInstitutionConnectionFacet, IInstitutionConnectionReader, IMachinePrincipalReader |
IAuthorisationApprover (ADR-728), IApproverViewReader (ADR-780): Contracts seams a feature implements so another may ask it |
reuse the pattern — the settings handler asks every feature what names a connection, without referencing any |
IdentityOrigin |
IdentityFrame.SystemOriginated (a boolean; ADR-728 reads it, SystemLockMiddleware reads it) |
extend — three values replace a boolean; the boolean stays, derived, so no reader changes |
PermissionKind, PermissionCatalog.PermitsFrame |
SystemInternalKeys, IsSystemInternal, IsGrantable (ADR-197); PermissionService.HasAsync read by both middlewares |
extend — a second key set and KindOf over both; PermitsFrame is one static rule both middlewares call before a person’s grants are consulted, so the wildcard never reaches a machine’s key |
MachineResolutionAttempt |
RecordAccessSessionStartedCommand (ADR-340: a person’s session on the tenant store) |
genuinely new — a refused caller has no tenant, so the attempt lives on the platform store; the person’s access audit cannot hold it |
ConnectionWhoAmIQuery |
MyProfileEndpoint, MeFeatures (a person’s view of themselves) |
genuinely new — a machine’s view of what it resolved to |
Relies on
| Symbol | What it does today | What this ADR assumes |
|---|---|---|
IdentityTokenIssuer.Mint |
Mints the gateway’s signed token for a person | Gains a connection claim; the same key and audience |
OidcService (ADR-067) |
Reads the IdP’s discovery document | Validates a client-credentials token against the same authority |
/api/auth/resolve |
Resolves a person to the tenants they may enter | The machine resolve step is its sibling |
FourEyesEligibility.IsEligible |
Four-term derivation (ADR-197, ADR-780) | Gains the fifth term |
IPermissionCatalog and PermissionCatalogTests |
Every command’s key is declared by its module (ADR-1200) | The marker sets the key’s kind |
SystemLockMiddleware (ADR-142) |
Passes a frame whose SystemOriginated is true |
Passes origins System and External |
UserGroup.GrantPermissions (ADR-118) |
Grants catalogue keys to a role | Refuses a key whose catalogue kind is externally authenticated |
ISettingsCommand<T> and SettingsCommandMiddleware |
Loads and saves a settings root around a handler | The three connection commands |
IPlatformAuthority and RequirePlatformAuthority (ADR-376 D1) |
Gates a minimal API on platform.administer |
The five platform endpoints |
HttpPermissionMiddleware and AuthorizationMiddleware |
Consult a person’s grants through PermissionService |
Both call PermitsFrame first |
SeedDevMember |
Registers a development person at provisioning | Registers the development and simulation principals the same way |
Worked example
Fixture: the za-retail tenant (package retail-bank), simulation on; a connection
sim-processor in its InstitutionConnectionSettings with transport ProcessorApi; a machine
principal registered by the platform administrator binding IdP client id app-sim-za to tenant
za-retail and connection sim-processor; the test IdP double issuing client-credentials tokens.
| Row | Before | After |
|---|---|---|
Register principal app-sim-za → za-retail / sim-processor |
none | MachinePrincipalRegistered; the platform lists it enabled |
Token for app-sim-za calls whoami |
— | tenant za-retail; principal id and client id app-sim-za; connection id and key sim-processor |
| A tenant administrator holding every role calls whoami | — | refused: a person frame is permitted no externally authenticated key |
Token for app-sim-za calls whoami during day-end on za-retail |
lock held | answered; the lock passed the External origin |
| Token for an unregistered client id calls whoami | — | refused at resolve; nothing minted; a resolution attempt records the client id with outcome UnknownClient |
Revoke app-sim-za, then call whoami within sixty seconds |
enabled | answered from the cache |
| Call whoami again after the cache expires | revoked | refused at resolve; the attempt records outcome Revoked |
A person holding every role tries to grant connectivity.whoami to a role |
— | refused: the key is externally authenticated and not grantable to a human |
A command marked IExternallyAuthenticatedCommand is dispatched by a person’s frame |
— | refused before the handler: the marker requires a connection frame |
Remove sim-processor while a facet (ADR-820’s processor settings) still names it |
facet attached | refused naming the facet |
Remove sim-processor with no facet, while principal app-sim-za is enabled for it |
principal enabled | refused naming the principal; removable once it is revoked |
Model
Generated from docs/model/model.json (ADR-773 D8): the shape the model knows today, <<new>> for what
## Contracts declares and the model does not know, relies-on for ## Relies on. Regenerate with
python3 scripts/model/adr_model.py ADR-NNN --write; frozen at Shipped.
classDiagram
class User {
<<aggregate>>
String Email
String ExternalId
UserId Id
Boolean IsActive
String Name
}
class UserGroup {
<<aggregate>>
UserGroupId Id
String Name
String Permissions
String RoleKey
TenantId TenantId
GrantPermissions() «relies-on»
}
UserGroup ..> UserGroupPermissionsGranted : GrantPermissions
class UserGroupPermissionsGranted {
<<event>>
}
class Connection {
<<new>>
}
UserGroup ..> Connection : declared
class ExternallyAuthenticated {
<<new>>
}
UserGroup ..> ExternallyAuthenticated : declared
class ExternallyAuthenticatedKeys {
<<new>>
}
UserGroup ..> ExternallyAuthenticatedKeys : declared
class IsGrantable {
<<new>>
}
UserGroup ..> IsGrantable : declared
class KindOf {
<<new>>
}
UserGroup ..> KindOf : declared
class Origin {
<<new>>
}
UserGroup ..> Origin : declared
class PermitsFrame {
<<new>>
}
UserGroup ..> PermitsFrame : declared
class Principal {
<<new>>
}
UserGroup ..> Principal : declared
class Resolved {
<<new>>
}
UserGroup ..> Resolved : declared
class Revoked {
<<new>>
}
UserGroup ..> Revoked : declared
class SystemOriginated {
<<new>>
}
UserGroup ..> SystemOriginated : declared
class UnknownClient {
<<new>>
}
UserGroup ..> UnknownClient : declared
class FourEyesEligibility {
<<relies-on>>
}
class HttpPermissionMiddleware {
<<relies-on>>
}
class IPlatformAuthority {
<<relies-on>>
}
class IdentityTokenIssuer {
<<relies-on>>
}
class OidcService {
<<relies-on>>
}
class PermissionCatalog {
<<relies-on>>
}
class SeedDevMember {
<<relies-on>>
}
class SettingsCommandMiddleware {
<<relies-on>>
}
class SystemLockMiddleware {
<<relies-on>>
}
Consequences
Positive
- ADR-694 and ADR-820 depend on three bites here and not on each other; the corporate and cards streams can be built in either order.
- One answer to “who may enter this tenant”, for people and machines alike, in the place that already answers it for people.
- F-1562 is closed by design rather than discovered at ADR-694’s bite 14.
- Every later external system (the FX venue, a second processor, the deposit system) is a registered principal and a connection row, with no identity work of its own.
Negative / Trade-offs
- ADR-694’s plan must be reconciled: bite 9’s row shrinks to the statement facet, bite 14 loses the marker and the identity, and D13, D18 and D21 point here. That reconciliation is a note on ADR-694 now and a plan edit when ADR-694 is next touched; it is not done here because ADR-694’s plan is its own.
- The gateway gains its first non-person path. It is the same shape as the person path, but it is new surface on the component that terminates trust.
- The development machine-token endpoint is new attack surface on the gateway, bounded by the same environment check as the dev login.
- Register and revoke are not four-eyes gated, because no platform-level change set exists. The platform role and the two events are the controls until platform four-eyes is designed.
The cheaper option, and why not
Leave all of this in ADR-694 and build ADR-694 first. No new ADR, no reconciliation. Refused because the cards series would wait on twelve bites of statement ingest for two of platform identity, and because the client-id-to-tenant gap would be found again at ADR-694’s bite 14 rather than decided now.
Neutral
- No standards row: OAuth2 client credentials (RFC 6749 §4.4) is the IdP’s compliance, not ours.
reseed: truefor the connection rows in theretail-bankand[redacted]templates and the development principals registered at provisioning.
Implementation Plan
Four bites, one land. Bites, acceptance criteria, files touched, interfaces, scenarios and status live in ADR-821-plan.md.
Notes
- ADR-694 reconciliation. Its D13, D18 and D21 and bite 14’s marker now live here; its bite 9 keeps the statement facet (feed authority, intraday style, formats) keyed by the connection, and its bite 14 keeps the push door and the retry rule. A note on ADR-694 records this; its plan is edited when it is next touched. F-1562 closes when this ADR ships.
- ADR-820 depends on bites 1, 2 and 4 here, not on ADR-694.
- Deferred, dated: platform-level four-eyes. Register and revoke of a machine principal are platform endpoints outside the four-eyes derivation, because no change set exists outside a tenant. A second pair of eyes on who may enter a tenant is worth an ADR of its own once a second platform-level mutation appears; until then the platform role and the two events are the controls. Raised 2026-09-30; revisit when the next platform command is designed.
- Deferred, dated: a platform administration screen. Principals and resolution attempts are API-only here. The first prospect who asks to see them in a screen decides the ADR.
- Proof. Component tests mint the identity token with the signing key and prove the API side; the gateway tests drive the development machine-token endpoint and prove the gateway side, with the cache expired by a fake clock. Issuer and audience pinning against a real discovery document is proven only in staging. No real Entra application is needed until then.
- Model page.
model_required.pyis run at the grill. No page covers connections or machine identity; if the script says a page is due, it isdocs/business/models/external-connection.md.
Changed during the grill
Grilled 2026-09-30 against the code, the same day as drafting. What the draft said, what it says now, and why.
- The lock rule became buildable. The draft added an
Externalorigin to a lock that reads a boolean. The identity frame now carries an origin with three values and the boolean is derived, soSystemLockMiddlewareand ADR-728’s readers change nothing. Decision 4. - The facet removal guard gained its seam. The draft had the settings handler refusing
removal while a facet exists, which it cannot see across feature projects. Each feature
registers
IInstitutionConnectionFacet; the handler asks every one. Decision 1. - Removal is also refused while an enabled principal speaks for the connection, through
IMachinePrincipalReader, because a token carrying aconnectionclaim no settings row explains is a claim an auditor cannot resolve. Decision 1, one scenario. - A principal holds no grants. The draft said a key is “held by the connection’s principal” and gave the principal no field for it. What a connection may dispatch is derived from the catalogue kind; nothing is stored. Decisions 2 and 5.
- The catalogue entry gained a kind, so queries are covered. The draft refused grants by the
command marker, which a query cannot carry, and then refused a grant of the whoami query in
its own worked example.
PermissionKindon the entry is what the grant handler reads;SystemInternalKeysfolds into it. Decision 5. - Register and revoke are
INotFourEyesGated, with the gap named. The draft left them eligible by the derivation and gave them no approver view. No change set exists outside a tenant; the compensating controls are the platform role and the two events; platform four-eyes is a dated deferral. Decision 2, §Notes. - Refused resolutions are recorded. The draft logged them. A refused caller has no tenant, so
a platform-store
MachineResolutionAttemptholds every attempt with its outcome, and the platform role can list a probing client id. Decisions 2 and 3. - Registration is API-only, guarded by the platform role, because no platform administration screen exists for anything; the development and simulation principals are registered at provisioning by the service token. Decision 2.
- The gateway caches a resolution for sixty seconds, chosen over a resolve per call because a processor’s authorisation budget is two seconds and a revocation happens once a year. A revoke lands within a minute; the gateway test forces the expiry. Decisions 3 and 6.
- The IdP double became a development machine-token endpoint on the gateway, refused outside Development and Testing like the dev login, standing in for token issuance only so the resolve, cache and mint still run. Decision 3.
- Proof was split by side. Component tests mint the identity token and prove the API; the existing gateway suite proves the gateway. The draft named a test IdP double that does not exist. Decision 6.
- Whoami is a query, permitted by its catalogue kind, not a marked command. Decision 6.
Pressed and held without change: the row’s generic core with feature facets; one principal
per client id per tenant per connection, with a second tenant refused; resolving through the
API rather than a map in the gateway; the same identity token with one added claim; the lock
passing an external origin; IExternallyAuthenticatedCommand as the fourth term; the
out-of-scope list, with mTLS and secret rotation held as the IdP’s and the gateway’s.
Contradiction press: 6 pairs, resolved as listed above. Run by a fresh agent given the decisions and the worked example only. Its returned block, condensed:
- A principal “holds” keys but has no field or event for grants — resolved: derived from the catalogue kind; nothing stored.
- The whoami query’s grant is refused by a rule that fires only on a command marker — resolved: the catalogue kind covers queries.
- A connection can be removed while a principal still speaks for it — resolved: refused through
IMachinePrincipalReader. - The revoke-within-sixty-seconds claim has no test on either side — resolved: the gateway test forces cache expiry; the dev endpoint runs the real resolve.
- Register and revoke are four-eyes eligible by the derivation with no approver view — resolved:
INotFourEyesGatedwith the reason; platform four-eyes deferred and dated. - A refused resolve leaves no record — resolved:
MachineResolutionAttempton the platform store.
Changed during the plan grill
Plan grill 2026-09-30 (phase A questions from the test author, then a fresh reader over the signatures). What the ADR said after the design grill, what it says now, and why.
- Register, revoke, resolve and the two lists are platform minimal APIs, not Wolverine
commands. The platform store is not integrated with Wolverine, so a handler returning events
would append them to the tenant store; a Wolverine chain needs a tenant frame a platform
administrator does not have; and a tenant catalogue key would let a tenant’s own administrator
grant themselves the right to register a machine. They follow
/api/auth/resolveand the provisioning endpoints underIPlatformAuthority.INotFourEyesGatedand theidentity.*keys are gone with them. Decision 2, contracts. - Every connectivity type lives in
LedgerTM.Infrastructure.Contracts. The identity frame and both middlewares live there and must name the connection id, andLedgerTM.Contractsdepends on that project, not the reverse. Contracts. - The client id left the connection row. The row and the principal both said which application speaks for a connection; the principal is the authority. Decision 1.
- The frame holds a principal and a minted actor. A principal now holds a
UserIdminted at registration, as a platform user does, so a machine’s events are attributed to an actor that is neither a person nor the system. Decisions 2 and 4. - One static rule decides what a frame may hold, called by both permission paths. A principal has no member record to hold grants, and a tenant administrator’s wildcard would otherwise reach a machine’s key. Decision 5.
- The removal guard is a validator rule, not a handler check, because the settings commands are four-eyes eligible and a handler check would refuse only after approval. Decision 1.
- The connection frame holds for the first hop only. A dequeued message re-enters a system frame; carrying the connection on the envelope is ADR-694’s and ADR-820’s to decide. Decision 4.
- The gateway refuses to proxy
/api/auth/*, closing an enumeration path this ADR would have widened and the person resolve already had. Decision 2. - The lock, marker and other-connection rules are proven as unit tests over the middleware, because no production command in this ADR carries the marker and a query passes the lock before identity is read. Decision 6.
- Re-registration is idempotent for the same binding and refused for any other, revoked or not. Decision 2.
- The gateway pipeline order, issuer and audience pinning, the client-id claim, the development token’s signing and the cookie-plus-bearer rule are stated. Decision 3.
- “Fourth term” corrected to fifth;
INotFourEyesGatedwas already the fourth. - Phase B corrections (the test authors, 2026-09-30):
subcarries the actor, not the principal id (Decision 3 had contradicted Decision 4); the development token carries a distinct audience so the API cannot mistake it for an identity token; a marked command in a system frame runs, because a cascade is a system frame; a frame with no connection binds nothing; whoami answers from the frame, never from settings; Decision 5’s formula names all five terms. - Extended for ADR-820 (2026-09-30, before any lane):
IInstitutionConnectionReaderandIMachinePrincipalReader.ActorForAsync, both additive, so a feature project can read a connection row and run as its principal without referencingLedgerTM.InfrastructureorLedgerTM.Identity.