This is the build plan for this decision record, bite by bite, as it was grilled and built. 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 — Implementation Plan

Findings for the ADR

Files touched

Bite 1 — the contract types, the marker, the kind, the derivations, the grant refusal, the architecture tests

Bite 2 — the connection settings, commands, validator, list query, template rows and page

Bite 3 — the machine principal, the platform endpoints, attempts, the seed step

Bite 4 — the gateway path, the connection frame, the permission rule, the lock rule, whoami

Prior art

Re-run over ## Contracts after the plan grill. Beyond the ADR’s table:

Declared Search returned Verdict
IConnectionScoped (F3) IAuthorisationSubject, ICreatesItsTarget (AccessControl): marker interfaces a middleware reads off a message reuse the pattern — one property the authorisation middleware compares to the frame
PermissionCatalog.KindOf, ExternallyAuthenticatedKeys, PermitsFrame (F4) SystemInternalKeys, IsSystemInternal, IsGrantable; PermissionService.HasAsync extend — a second set, one function over both, one frame rule both middlewares call
MachinePrincipalEndpoints ProvisioningEndpoints (/api/admin/tenants/* under RequirePlatformAuthority), ApproverCredentialEndpoints (minimal APIs on IPlatformStore), AuthEndpoints.MapAuthResolveEndpoint reuse the pattern — minimal APIs on the platform store under the platform role
MachineResolution (gateway DTO) ResolveResult in Gateway/Auth/AuthEndpoints.cs reuse the pattern — the gateway’s own wire shape; the gateway does not reference Identity
SeedSimulationPrincipal SeedDevMember (simulation phase) reuse the pattern — a sibling step, not a second path through ProvisioningEndpoints.Post

Interfaces

// src/LedgerTM.Infrastructure.Contracts/AccessControl/IExternallyAuthenticatedCommand.cs
public interface IExternallyAuthenticatedCommand;

// src/LedgerTM.Infrastructure.Contracts/AccessControl/PermissionKind.cs
public enum PermissionKind { Human, SystemInternal, ExternallyAuthenticated }

// src/LedgerTM.Infrastructure.Contracts/AccessControl/IdentityOrigin.cs
public enum IdentityOrigin { Person, System, External }

// src/LedgerTM.Infrastructure.Contracts/AccessControl/MachinePrincipalId.cs
public readonly record struct MachinePrincipalId(string Value) : IStrongId<MachinePrincipalId>
{
    public override string ToString() => Value;
    public static MachinePrincipalId FromClientId(string clientId) => new(StrongId.UrnFor<MachinePrincipalId>(clientId));
}

// src/LedgerTM.Infrastructure.Contracts/AccessControl/PermissionCatalog.cs (additions; the class stays static)
public static class PermissionCatalog
{
    public static IReadOnlySet<string> ExternallyAuthenticatedKeys { get; }
    public static PermissionKind KindOf(string key);
    // Keys.Contains(key) && KindOf(key) == PermissionKind.Human
    public static bool IsGrantable(string key);
    // External: only ExternallyAuthenticated keys. Person: any key except ExternallyAuthenticated.
    // System: everything (unchanged).
    public static bool PermitsFrame(string key, IdentityOrigin origin);
}

// src/LedgerTM.Infrastructure.Contracts/AccessControl/FourEyesEligibility.cs
public static class FourEyesEligibility
{
    // ICommand && !ISystemCommand && !IFourEyesControlCommand && !INotFourEyesGated
    //          && !IExternallyAuthenticatedCommand
    public static bool IsEligible(Type? messageType);
}

// src/LedgerTM.Infrastructure.Contracts/AccessControl/IdentityFrame.cs (additions)
public sealed record IdentityFrame
{
    public IdentityOrigin Origin { get; }
    public MachinePrincipalId? Principal { get; }
    public InstitutionConnectionId? Connection { get; }
    public bool SystemOriginated => Origin != IdentityOrigin.Person;
    // actor: the UserId the principal holds; email: the client id.
    public static IdentityFrame ForConnection(
        TenantId tenant, UserId actor, MachinePrincipalId principal, InstitutionConnectionId connection, string clientId);
}

// src/LedgerTM.Infrastructure.Contracts/AccessControl/ICurrentConnection.cs
public interface ICurrentConnection
{
    // Both null outside a connection frame, and on every hop after the first.
    MachinePrincipalId? Principal { get; }
    InstitutionConnectionId? Connection { get; }
}

// src/LedgerTM.Infrastructure.Contracts/AccessControl/IdentityToken.cs (addition)
public const string ConnectionClaim = "connection";   // carries the connection key

// src/LedgerTM.Infrastructure.Contracts/Connectivity/InstitutionConnectionId.cs   (namespace LedgerTM.Contracts.Connectivity)
public readonly record struct InstitutionConnectionId(string Value) : IStrongId<InstitutionConnectionId>
{
    public override string ToString() => Value;
    public static InstitutionConnectionId FromKey(string key) => new(StrongId.SlugFor<InstitutionConnectionId>(key));
}

// src/LedgerTM.Infrastructure.Contracts/Connectivity/ConnectionTransport.cs
public sealed record ConnectionTransport(string Name, bool StreamingCapable);

// src/LedgerTM.Infrastructure.Contracts/Connectivity/InstitutionConnection.cs — the settings row (ADR-422: id derived)
public sealed record InstitutionConnection(string Key, string InstitutionName, string? Bic, ConnectionTransport Transport)
{
    public InstitutionConnectionId Id { get => InstitutionConnectionId.FromKey(Key); init { } }
}

// src/LedgerTM.Infrastructure.Contracts/Connectivity/IInstitutionConnectionFacet.cs — one registration per feature
public interface IInstitutionConnectionFacet
{
    string FacetName { get; }
    Task<bool> IsAttachedAsync(TenantId tenant, InstitutionConnectionId connection, CancellationToken ct = default);
}

// src/LedgerTM.Infrastructure.Contracts/Connectivity/IMachinePrincipalReader.cs — implemented in LedgerTM.Identity
public interface IMachinePrincipalReader
{
    Task<IReadOnlyList<MachinePrincipalId>> EnabledForAsync(
        TenantId tenant, InstitutionConnectionId connection, CancellationToken ct = default);
    // Added for ADR-820: the actor and client id a connection frame needs. Null when no enabled principal.
    Task<(UserId Actor, string ClientId)?> ActorForAsync(
        TenantId tenant, InstitutionConnectionId connection, CancellationToken ct = default);
}

// src/LedgerTM.Infrastructure.Contracts/Connectivity/IInstitutionConnectionReader.cs — added for ADR-820; implemented in LedgerTM.Infrastructure
public interface IInstitutionConnectionReader
{
    Task<InstitutionConnection?> FindAsync(InstitutionConnectionId id, CancellationToken ct = default);
}

// src/LedgerTM.Infrastructure.Contracts/Connectivity/IConnectionScoped.cs (F3)
public interface IConnectionScoped
{
    InstitutionConnectionId Connection { get; }
}

// src/LedgerTM.Infrastructure/Connectivity/InstitutionConnectionSettings.cs
public class InstitutionConnectionSettings : Settings
{
    public List<InstitutionConnection> Connections { get; set; } = [];
    public InstitutionConnection? Find(InstitutionConnectionId id) => Connections.FirstOrDefault(c => c.Id == id);
}

// src/LedgerTM.Infrastructure/Connectivity/Application/Settings/AddInstitutionConnection.cs
// POST /api/settings/institution-connections/add
[PermissionKey("connectivity.add-institution-connection")]
public record AddInstitutionConnectionCommand(string Key, string InstitutionName, string? Bic, ConnectionTransport Transport)
    : ISettingsCommand<InstitutionConnectionSettings>;
// Validator: Key matches VocabularyKey.Pattern and is unique; Bic, when present, is 8 or 11 characters.

// src/LedgerTM.Infrastructure/Connectivity/Application/Settings/AmendInstitutionConnection.cs
// POST /api/settings/institution-connections/amend
[PermissionKey("connectivity.amend-institution-connection")]
public record AmendInstitutionConnectionCommand(InstitutionConnectionId Id, string InstitutionName, string? Bic, ConnectionTransport Transport)
    : ISettingsCommand<InstitutionConnectionSettings>;

// src/LedgerTM.Infrastructure/Connectivity/Application/Settings/RemoveInstitutionConnection.cs
// POST /api/settings/institution-connections/remove
[PermissionKey("connectivity.remove-institution-connection")]
public record RemoveInstitutionConnectionCommand(InstitutionConnectionId Id)
    : ISettingsCommand<InstitutionConnectionSettings>;
// Async validator (re-runs at approval, ADR-780 D9): refuses with CONNECTION_HAS_FACET naming the facet,
// or CONNECTION_HAS_PRINCIPAL naming the principal; the handler only removes.

// src/LedgerTM.Infrastructure/Connectivity/Application/Queries/ListInstitutionConnections.cs
// GET /api/settings/institution-connections
public record InstitutionConnectionRow(
    InstitutionConnectionId Id, string Key, string InstitutionName, string? Bic, ConnectionTransport Transport,
    IReadOnlyList<string> AttachedFacets, IReadOnlyList<MachinePrincipalId> EnabledPrincipals);
[PermissionKey("connectivity.list-institution-connections")]
public record ListInstitutionConnectionsQuery : IQuery<IReadOnlyList<InstitutionConnectionRow>>;

// src/LedgerTM.Infrastructure/Connectivity/Application/Queries/ConnectionWhoAmI.cs
// GET /api/connections/whoami — record and key in bite 1, handler and endpoint in bite 4
public record ConnectionIdentity(
    TenantId Tenant, MachinePrincipalId Principal, string ClientId, InstitutionConnectionId Connection, string ConnectionKey);
[PermissionKey("connectivity.whoami")]   // kind ExternallyAuthenticated
public record ConnectionWhoAmIQuery : IQuery<ConnectionIdentity>;

// src/LedgerTM.Infrastructure/AccessControl/Application/Queries/ListPermissionsQuery.cs (change)
// the permission row gains: PermissionKind Kind

// src/LedgerTM.Identity/Domain/MachinePrincipal.cs — platform store aggregate
public sealed class MachinePrincipal : EventSourcedAggregate
{
    public MachinePrincipalId Id { get; private set; }
    public string ClientId { get; private set; }
    public UserId Actor { get; private set; }
    public TenantId Tenant { get; private set; }
    public InstitutionConnectionId Connection { get; private set; }
    public bool IsEnabled { get; private set; }
    public static MachinePrincipal Register(string clientId, TenantId tenant, InstitutionConnectionId connection, UserId registeredBy);
    // Same binding: re-enables with a second MachinePrincipalRegistered; any other binding throws
    // MACHINE_PRINCIPAL_BOUND_ELSEWHERE. Enabled and same binding: no event.
    public void Reregister(TenantId tenant, InstitutionConnectionId connection, UserId registeredBy);
    public void Revoke(UserId revokedBy);   // MACHINE_PRINCIPAL_ALREADY_REVOKED when already revoked
    public void Apply(MachinePrincipalRegistered e);
    public void Apply(MachinePrincipalRevoked e);
}

// src/LedgerTM.Identity/Domain/MachinePrincipal.Events.cs
public record MachinePrincipalRegistered(
    MachinePrincipalId Id, string ClientId, UserId Actor, TenantId Tenant, InstitutionConnectionId Connection, UserId RegisteredBy) : DomainEvent;
public record MachinePrincipalRevoked(MachinePrincipalId Id, UserId RevokedBy) : DomainEvent;

// src/LedgerTM.Identity/Domain/MachineResolutionAttempt.cs — platform document, one per call
public enum MachineResolutionOutcome { Resolved, UnknownClient, Revoked }
public sealed record MachineResolutionAttempt(Guid Id, string ClientId, MachineResolutionOutcome Outcome, DateTimeOffset At);

// src/LedgerTM.Identity/Application/Api/MachinePrincipalEndpoints.cs — minimal APIs, IPlatformStore, RequirePlatformAuthority
// POST /api/admin/machine-principals            RegisterMachinePrincipalRequest(string ClientId, string Tenant, string Connection)
//   → 200 MachinePrincipalRow; 409 MACHINE_PRINCIPAL_BOUND_ELSEWHERE; 404 TENANT_UNKNOWN / CONNECTION_UNKNOWN
// POST /api/admin/machine-principals/{id}/revoke → 200; 404; 409 MACHINE_PRINCIPAL_ALREADY_REVOKED
// GET  /api/admin/machine-principals             → MachinePrincipalRow[]
// GET  /api/admin/machine-principals/attempts?from=&to=&clientId=   → MachineResolutionAttempt[] (UTC days)
// POST /api/auth/resolve-machine                 ResolveMachineRequest(string ClientId) → 200 MachineResolutionResult, always
public record MachinePrincipalRow(MachinePrincipalId Id, string ClientId, UserId Actor, TenantId Tenant, InstitutionConnectionId Connection, bool IsEnabled);
public record MachineResolutionResult(
    MachineResolutionOutcome Outcome, MachinePrincipalId? Principal, UserId? Actor, TenantId? Tenant,
    InstitutionConnectionId? Connection, string? ConnectionKey);

// src/LedgerTM.Gateway/Auth/MachineResolution.cs — the gateway's own wire DTO for the result above
public sealed record MachineResolution(string Outcome, string? Principal, string? Actor, string? Tenant, string? Connection, string? ConnectionKey);

// src/LedgerTM.Gateway/Auth/MachinePrincipalResolver.cs
public interface IMachinePrincipalResolver
{
    // Cached per client id for MachineAuthOptions.CacheTtl (default 60s) on TimeProvider; refusals cached too.
    Task<MachineResolution> ResolveAsync(string clientId, CancellationToken ct = default);
}
public sealed class MachineAuthOptions
{
    public TimeSpan CacheTtl { get; set; } = TimeSpan.FromSeconds(60);
    public string? Issuer { get; set; }        // pinned to EntraId tenant; required outside Development/Testing
    public string? Audience { get; set; }      // the API application id URI
}

// src/LedgerTM.Gateway/Auth/MachineTokenValidator.cs
public interface IMachineTokenValidator
{
    // The client id (azp, then appid) or null. A development token is signed with the identity key
    // and accepted only when the development login key is configured.
    Task<string?> ValidateAsync(string bearer, CancellationToken ct = default);
}

// src/LedgerTM.Gateway/Auth/AuthEndpoints.cs (addition, Development/Testing only)
// POST /auth/dev/machine-token  DevMachineTokenRequest(string ClientId) → { token } for any client id;
// registration is checked at resolve, not here, so the unregistered-client scenario can be driven.
// The token's audience is "ledgertm-machine-dev", never IdentityToken.Audience, so the API refuses it as an identity token.

// LedgerTM.Testing.Infrastructure/TestingEnvironment.cs (ShippedApiHost, both public)
public string MintPlatformRoleToken(string tenant, string user, string email, string platformRole);
public string MintConnectionToken(string tenant, UserId actor, string clientId, string connectionKey);

// src/LedgerTM.Identity/Application/Api — the register request carries the tenant slug and the connection key;
// the revoke route parameter is the raw client id; a blank client id on resolve is 400, any other string 200.
// Re-registration keeps the actor. Two client ids may speak for one connection.

// src/LedgerTM.Gateway/Auth/IdentityTokenIssuer.cs (change)
public interface IIdentityTokenIssuer
{
    string Mint(string? tenantId, string? userId, string? email, string? externalId, string? platformRole, string? connection = null);
}

Bites

Bite Description Acceptance criterion Status
1 Every contract type in LedgerTM.Infrastructure.Contracts, IExternallyAuthenticatedCommand, the fifth term in FourEyesEligibility, PermissionKind with ExternallyAuthenticatedKeys, KindOf and PermitsFrame, the whoami query record and key, the grant refusal in UserGroup, the kind on the permissions list, and the architecture tests A command marked as externally authenticated is never four-eyes eligible; An externally authenticated permission key cannot be granted to a person; A connection frame is permitted only externally authenticated keys and a person frame none of them Pending
2 InstitutionConnectionSettings, the three settings commands with keys and validators, ListInstitutionConnectionsQuery, the removal validator over IInstitutionConnectionFacet, template rows for retail-bank and structured-finance, the test facet, and the settings page. Guide: the institution connections article A tenant declares the institutions it exchanges with; A connection with a facet attached cannot be removed until the facet is; The templates provision the connection document with conformant keys Pending
3 MachinePrincipal aggregate with register, re-register and revoke, the platform endpoints under platform.administer, resolve-machine writing MachineResolutionAttempt, MachinePrincipalReader, the simulation seed step, and tenant deletion revoking A platform administrator binds a client id to one tenant and one connection; A revoked principal no longer resolves, and can be registered again for the same binding only; Every resolution attempt is recorded, refused ones included; A connection an enabled principal speaks for cannot be removed; The simulation seed step registers one principal per tenant and is idempotent Pending
4 Gateway: the machine middleware before the header strip, pinned validation, the development machine-token endpoint, the resolver with a sixty-second cache on TimeProvider, the connection claim, the proxy refusal on /api/auth/*; API: IdentityFrame.ForConnection with origin, principal and actor, ICurrentConnection, PermitsFrame in both permission middlewares, the lock and other-connection rules; the whoami handler A client-credentials token resolves to its tenant and connection; A person cannot ask who a connection is; An unregistered client id is refused before anything is minted; A revoke takes effect once the gateway’s cache expires; The development machine-token endpoint is mapped only where the development login is; The lock passes an external origin and refuses a person; A marked command in a person frame is refused before its handler; A message naming another connection is refused before its handler; The gateway does not proxy the auth resolve endpoints Shrunk

Scenarios

Feature: An external system enters one tenant as a named connection, and its commands need no approver

# Bite 1
Scenario: A command marked as externally authenticated is never four-eyes eligible
  Given a mutating command that carries the externally-authenticated marker
  When four-eyes eligibility is derived for it
  Then it is not eligible
  And a mutating command without the marker, the system marker, the control marker or the not-gated marker is still eligible
  # Seen at: none

# Bite 1
Scenario: An externally authenticated permission key cannot be granted to a person
  Given a catalogue key of the externally authenticated kind, whether it names a command or a query
  When an operator with every role tries to grant that key to a human role
  Then the grant is refused naming the key and its kind
  And the group's permissions page lists the key with its kind and offers no grant control for it
  # Seen at: route:/settings/access-control/groups/{id}

# Bite 1
Scenario: A connection frame is permitted only externally authenticated keys and a person frame none of them
  Given a key of the externally authenticated kind and a key of the human kind
  When the frame rule is asked for an external origin
  Then the externally authenticated key is permitted and the human key is not
  And when it is asked for a person origin the human key is permitted and the externally authenticated key is not
  And when it is asked for a system origin both are permitted
  # Seen at: none

# Bite 2
Scenario: A tenant declares the institutions it exchanges with
  Given the za-retail tenant
  When an operator adds a connection with key other-bank, institution name Other Bank, and transport ProcessorApi that can stream
  Then the connection is listed with its key, name and transport, with no facets and no principals attached
  And adding a second connection with key other-bank is refused as a duplicate
  And on a tenant with no connections, adding a connection with key Other Bank is refused because a key is kebab-case
  # Seen at: route:/settings/institution-connections

# Bite 2
Scenario: The templates provision the connection document with conformant keys
  Given the retail-bank and structured-finance packages
  When a tenant is provisioned from each
  Then the retail-bank tenant holds connection sim-processor with transport ProcessorApi and the structured-finance tenant holds an empty list
  And every seeded key is kebab-case and unique
  And the document survives an export and re-import
  # Seen at: route:/settings/institution-connections

# Bite 2
Scenario: A connection with a facet attached cannot be removed until the facet is
  Given connection sim-processor in za-retail with a feature's facet attached to it
  When an operator removes sim-processor
  Then the removal is refused naming the facet
  And after the facet is detached the connection can be removed
  # Seen at: route:/settings/institution-connections

# Bite 3
Scenario: A platform administrator binds a client id to one tenant and one connection
  Given no principal exists for client id app-sim-za
  And connection sim-processor exists in za-retail's settings
  When the platform administrator registers app-sim-za for tenant za-retail and connection sim-processor
  Then the platform lists the principal as enabled with an actor of its own
  And registering app-sim-za for tenant za-retail and connection sim-processor again changes nothing
  And registering app-sim-za for any other tenant or connection is refused as bound elsewhere
  And registering a client id for a connection that is not in that tenant's settings is refused
  And a tenant administrator without the platform role cannot register a principal
  # Seen at: none

# Bite 3
Scenario: A revoked principal no longer resolves, and can be registered again for the same binding only
  Given principal app-sim-za is enabled for za-retail and sim-processor
  When the platform role revokes it
  Then resolving app-sim-za answers revoked
  And the principal is listed as revoked, not deleted
  And revoking it again is refused as already revoked
  And registering app-sim-za for another tenant while revoked is refused as bound elsewhere
  And registering app-sim-za again for za-retail and sim-processor re-enables the same principal with the same actor
  # Seen at: none

# Bite 3
Scenario: Every resolution attempt is recorded, refused ones included
  Given no principal exists for client id app-unknown
  When app-unknown is resolved
  Then the answer is unknown client, and it is an answer rather than an error
  And the platform lists an attempt for app-unknown with outcome unknown client and when it happened
  And resolving a revoked client id lists an attempt with outcome revoked
  And resolving an enabled client id lists an attempt with outcome resolved
  # Seen at: none

# Bite 3
Scenario: The simulation seed step registers one principal per tenant and is idempotent
  Given za-retail's settings hold connection sim-processor and another tenant's settings do not
  When the simulation seed step runs twice
  Then exactly one enabled principal with client id sim-za-retail speaks for sim-processor in za-retail
  And the other tenant has no principal
  And a revoked sim-za-retail is re-enabled by the next run
  # Seen at: none

# Bite 3
Scenario: A connection an enabled principal speaks for cannot be removed
  Given connection sim-processor in za-retail with no facet attached
  And an enabled machine principal registered for tenant za-retail and connection sim-processor
  When an operator removes sim-processor
  Then the removal is refused naming the principal
  And after the principal is revoked the connection can be removed
  # Seen at: route:/settings/institution-connections

# Bite 4
Scenario: A client-credentials token resolves to its tenant and connection
  Given principal app-sim-za is enabled for tenant za-retail and connection sim-processor
  And a client-credentials token for app-sim-za
  When that token asks who it is
  Then the answer names tenant za-retail, client id app-sim-za and connection key sim-processor, with the principal's and the connection's ids
  # Seen at: none

# Bite 4
Scenario: A person cannot ask who a connection is
  Given a tenant administrator of za-retail holding every role
  When they ask who a connection is
  Then the request is refused, because a person frame is permitted no externally authenticated key
  # Seen at: none

# Bite 4
Scenario: An unregistered client id is refused before anything is minted
  Given no principal exists for client id app-unknown
  And a client-credentials token for app-unknown
  When that token asks who it is
  Then the request is refused at the gateway
  And no request reached the API other than the resolution itself
  And an attempt for app-unknown is recorded
  # Seen at: none

# Bite 4
Scenario: A revoke takes effect once the gateway's cache expires
  Given principal app-sim-za is enabled and has just been resolved
  When the platform role revokes app-sim-za
  And a token for app-sim-za asks who it is within sixty seconds
  Then it is answered from the cached resolution and no new attempt is recorded
  And once sixty seconds have passed the same token is refused
  # Seen at: none

# Bite 4
Scenario: The development machine-token endpoint is mapped only where the development login is
  Given the development login key is configured
  When the development machine-token endpoint is asked for a token for app-sim-za
  Then a token is issued and it resolves through the same path as a production token
  And when the development login key is not configured no token is issued
  # Seen at: none

# Bite 4
Scenario: The lock passes an external origin and refuses a person
  Given a tenant whose day-end lock is held
  When a mutating message arrives in a frame with an external origin
  Then the lock passes it
  And the same message in a frame with a person origin is refused by the lock
  # Seen at: none

# Bite 4
Scenario: A marked command in a person frame is refused before its handler
  Given a command carrying the externally-authenticated marker
  When it is dispatched in a frame with a person origin
  Then it is refused before its handler runs, naming the marker
  And dispatched in a frame with an external origin it reaches its handler
  And dispatched in a frame with a system origin it reaches its handler
  # Seen at: none

# Bite 4
Scenario: A message naming another connection is refused before its handler
  Given a frame for connection sim-processor
  When a message scoped to connection other-bank is dispatched in it
  Then it is refused before its handler runs, naming both connections
  And a message scoped to sim-processor reaches its handler
  And in a frame with no connection a connection-scoped message is not held to any connection
  # Seen at: none

# Bite 4
Scenario: The gateway does not proxy the auth resolve endpoints
  Given a signed-in person
  When they call the API's machine resolve endpoint or the person resolve endpoint through the gateway
  Then the gateway refuses the request without forwarding it
  # Seen at: none

Scenario → test

Scenario Bite Project Class Method Probe
A command marked as externally authenticated is never four-eyes eligible 1 LedgerTM.Tests.Unit FourEyesEligibilityTests a_marked_command_is_never_eligible — derivation, nothing to look at
An externally authenticated permission key cannot be granted to a person 1 LedgerTM.Tests.Component ExternallyAuthenticatedGrantTests granting_an_externally_authenticated_key_to_a_group_is_refused — refusal; the page reads the kind
A connection frame is permitted only externally authenticated keys and a person frame none of them 1 LedgerTM.Tests.Unit PermitsFrameTests the_frame_rule_permits_by_origin_and_kind — rule, nothing to look at
A tenant declares the institutions it exchanges with 2 LedgerTM.Tests.Component InstitutionConnectionSettingsTests adding_a_connection_lists_it_and_refuses_a_duplicate_or_non_kebab_key adr-821-server-probe.ts
A connection with a facet attached cannot be removed until the facet is 2 LedgerTM.Tests.Component InstitutionConnectionSettingsTests removing_a_connection_a_facet_names_is_refused_until_detached — refusal, nothing to look at
The templates provision the connection document with conformant keys 2 LedgerTM.Tests.Component InstitutionConnectionProvisioningTests the_templates_provision_the_connection_document — provisioning, seen on the settings page
A platform administrator binds a client id to one tenant and one connection 3 LedgerTM.Tests.Component MachinePrincipalTests registering_binds_one_client_id_to_one_tenant_and_connection adr-821-server-probe.ts
A revoked principal no longer resolves, and can be registered again for the same binding only 3 LedgerTM.Tests.Component MachinePrincipalTests revoking_stops_resolution_and_re_registering_re_enables_the_same_binding_only — refusal and re-enable, no surface
Every resolution attempt is recorded, refused ones included 3 LedgerTM.Tests.Component MachinePrincipalTests every_resolution_attempt_is_recorded_with_its_outcome adr-821-server-probe.ts
The simulation seed step registers one principal per tenant and is idempotent 3 LedgerTM.Tests.Component SimulationPrincipalSeedTests (under Seeding/, runs the step through SeedRunner) the_simulation_seed_step_registers_one_principal_per_tenant_and_is_idempotent — seeding, no surface
A connection an enabled principal speaks for cannot be removed 3 LedgerTM.Tests.Component InstitutionConnectionSettingsTests removing_a_connection_a_principal_speaks_for_is_refused_until_revoked — refusal, nothing to look at
A client-credentials token resolves to its tenant and connection 4 LedgerTM.Tests.Component ConnectionFrameTests a_connection_token_answers_whoami adr-821-server-probe.ts
A person cannot ask who a connection is 4 LedgerTM.Tests.Component ConnectionFrameTests a_person_is_refused_whoami_whatever_they_hold — refusal, nothing to look at
An unregistered client id is refused before anything is minted 4 LedgerTM.Tests MachineTokenTests an_unregistered_client_id_is_refused_and_nothing_is_minted — refusal, nothing to look at
A revoke takes effect once the gateway’s cache expires 4 LedgerTM.Tests MachineTokenTests a_revoke_takes_effect_after_the_cache_expires — timing, no surface
The development machine-token endpoint is mapped only where the development login is 4 LedgerTM.Tests MachineTokenTests the_dev_machine_token_endpoint_follows_the_dev_login_key — mapping, no surface
The lock passes an external origin and refuses a person 4 LedgerTM.Tests.Unit SystemLockMiddlewareTests an_external_origin_passes_the_lock_and_a_person_does_not — rule, no surface
A marked command in a person frame is refused before its handler 4 LedgerTM.Tests.Unit AuthorizationMiddlewareTests a_marked_command_in_a_person_frame_is_refused_before_its_handler — rule, no surface
A message naming another connection is refused before its handler 4 LedgerTM.Tests.Unit AuthorizationMiddlewareTests a_message_naming_another_connection_is_refused_before_its_handler — rule, no surface
The gateway does not proxy the auth resolve endpoints 4 LedgerTM.Tests MachineTokenTests the_gateway_does_not_proxy_auth_resolve — refusal, nothing to look at

UI-surface sweep

Swept src/ui for institution-connection, InstitutionConnection, connectivity., machine-principal, MachinePrincipal, whoami, resolve-machine, settings/institution, IsSystemInternal: hits only in lib/api.ts and the two access-control pages for the existing system-internal flag. What this ADR adds or changes in the UI:

No existing UI surface is deleted, renamed or repointed. The platform endpoints have no UI.

Footprint

Feature projects touched: 9 — LedgerTM.Api, LedgerTM.Gateway, LedgerTM.Hosting, LedgerTM.Identity, LedgerTM.Infrastructure, LedgerTM.Infrastructure.Contracts, LedgerTM.Seeding, LedgerTM.Seeding.Provisioning, ui

Contracts types: 42 named, 41 changed by this ADR

Files reading each changed type: 41 types

Domain events touched: 3 — MachinePrincipal, MachinePrincipalRegistered, MachinePrincipalRevoked Aggregates touched: 1

Methods at CRAP 30+ in changed files: 3 (unit coverage, cached at main 0c8f70f8b)

Warnings

At land: 100 files touched, 96 predicted, 21 unplanned. LedgerTM.Tests.Architecture/HttpEndpointTests.cs, LedgerTM.Tests.Architecture/ShapeGate/stored-shapes.tsv, LedgerTM.Tests.Architecture/TenantSettingsFolderTests.cs, LedgerTM.Tests.Architecture/UnitOfWorkTests.cs, LedgerTM.Tests.Component/Connectivity/InstitutionConnectionReaderTests.cs, LedgerTM.Tests.Unit/Seeding/preset-snapshots.txt, LedgerTM.Tests/Gateway/MachineTokenClockTests.cs, src/LedgerTM.Hosting/event-identity.tsv, src/LedgerTM.Identity/Application/MachinePrincipalRevocation.cs, src/LedgerTM.Identity/Application/Projections/MachinePrincipalReadModel.cs, src/LedgerTM.Infrastructure.Contracts/Exceptions/ForbiddenException.cs, src/LedgerTM.Infrastructure/AccessControl/FrameCurrentConnection.cs, src/LedgerTM.Infrastructure/Configuration/ConfigureServices.cs, src/LedgerTM.Infrastructure/Connectivity/InstitutionConnectionRules.cs, src/LedgerTM.Infrastructure/Connectivity/NullMachinePrincipalReader.cs, src/LedgerTM.Seeding.ZaRetail.Samples/Bootstrapper.cs, src/LedgerTM.Seeding/Api/ProvisioningEndpoints.cs, src/ui/src/__tests__/standard-table-rowhref-guard.test.ts, src/ui/src/features/settings/category-taxonomy.ts, src/ui/src/features/settings/forms/institution-connection-form.tsx, src/ui/src/features/settings/hooks/institution-connections.ts

Land batches

One land — the whole ADR. Reseed once at the land (reseed: true: new permission keys, a new settings document in two packages, the simulation principals from the seed step). ADR-820 and ADR-694 depend on this ADR’s contract types and land after it in their own lanes, which is a dependency between lands, not a reason to split this one.

Notes

Changed during the plan grill

Phase A (the test author’s question pass) and a fresh reader over the signatures, 2026-09-30.

Landing notes

(appended by /ltm-partition and by lanes)