[MWG-Logan]

Summary

Spec #63 end to end: Signal9 gets its own authorization server, tenant-scoped RBAC over a tenant tree of any depth, and certificate-bound agent identity. Built as 43 ticket commits, a 17-commit code-review fix pass, a 10-commit core-principles fix pass a migration squash and a CodeQL fix: 72 commits, linear on dev.

flowchart LR
    Browser -->|"__Host- cookie, CSRF header"| web["web (BFF, Fluent UI v5 WASM)"]
    web -->|"mTLS-bound tokens via YARP"| api
    web -->|"OIDC + PKCE"| auth["auth (OpenIddict server)"]
    auth -->|"OIDC, amr=mfa"| Entra
    Agent -->|"enrollment token, then self_signed_tls_client_auth"| auth
    Agent -->|"mTLS REST + doorbell hub"| api["api (resource server)"]
    api --> pg[("PostgreSQL 18")]
    auth --> pg

Loading

OSI.Signal9.Auth/         # authorization server: Entra sign-in, consent, invitations, session checks, front-channel logout
OSI.Signal9.API/          # resource server: tenants, transfers, RBAC, users, API applications, agents, devices, audit, hubs
OSI.Signal9.Server/       # shared data (EF Core + Npgsql, one InitialCreate), TenantScope filter, OpenIddict stores, keys
OSI.Signal9.Web(.Client)/ # BFF host + Fluent UI v5 dashboard (built from scratch, steamrolling the old UI)
OSI.Signal9.Agent/        # enrollment, mTLS identity and rotation, hardware identifiers, doorbell; per-OS platforms (Windows, Linux; macOS stubbed), version paired to api
OSI.Signal9.*Tests/       # IntegrationTests (Testcontainers), Web.Tests (bUnit), Agent.Tests

Every request is filtered by the caller's live tenant scope (closure table); a filter bypass must declare [Audited] or [NotAudited(reason)]. Tokens carry identity only, and access is read per request (ADR-0007).

Evidence

• Before: dev @ e7cd902: the API is anonymous, there's no tenant tree or RBAC, agents authenticate with nothing, the dashboard has no sign-in.
  After: integration/63-auth-tenancy @ 1347d04: Release build clean with warnings as errors, dotnet format --verify-no-changes clean, and 943/943 tests pass (IntegrationTests on PostgreSQL via Testcontainers, Web.Tests in bUnit, Agent.Tests).
• The final code review (standards and spec axes, by Astra) found 16 distinct issues (10 standards, 8 spec, 2 found by both). All are fixed with failing-first regression tests, except the two deferred to Spec: deployment, releases and first-run setup #77 and one optional page-boilerplate cleanup. A second review against the OSI tenets and security/API practice (Astra and Opus) found 27 more; both fix passes are merged (items 131–147 below). For example:

test Forwarded_headers_are_ignored_when_no_proxy_network_is_configured
  given  ForwardedHeaders:KnownNetworks = []          # the shipped default
  when   a request sends X-Forwarded-For: 203.0.113.9
  then   RemoteIpAddress is the socket peer           # before: 203.0.113.9 (spoofable)

test Superadministrator_comes_only_from_the_deploying_directorys_session
  given  one home account signed in through the deploying directory and as a guest elsewhere
  when   the hourly Entra check runs
  then   only the deploying directory's session is a Superadministrator
                                                      # before: the guest session inherited the flag

Merge Danger

Door: one-way

The schema is replaced (one new InitialCreate on PostgreSQL), the old UI and anonymous API are removed, and agents enroll with a new protocol. Pre-1.0 and steamrolled by decision, so there's no data or client to migrate, but nothing built on dev's old shapes survives.

Blast Radius: everything

Every endpoint now needs a token and tenant scope; agents and API clients written against dev stop working; operators must configure Entra (deploying directory, auth_time optional claim, a Conditional Access MFA policy, front-channel logout URL), trusted proxy networks and real-time hosting. Live paths not exercised by tests: Azure SignalR Service (no emulator for default mode) and real Entra (the deployed proofs are still open).

Requires human maintainer review

The review items of #100, #101, #102, #103, #104, #106, #109, #137 and #143 were accepted during the build and aren't repeated here. The one exception is #106's Data Protection key-encryption decision (item 1). 🔒 marks items that affect security.

Already decided by the maintainer (recorded here, no answer needed)

• Tenant depth is zero-indexed. The root is depth 0, depth is the closure distance from the root, MaxDepth 20 allows depth ≤ 20, and MaxDepth may be 0 (roots only).
• Agents: a machine can run several independent agent instances, one per (deployment, root tenant tree). Within one root tree a machine is one device with at most one active agent.
• Real-time hosting: on Azure the hubs always use Azure SignalR Service. Redis serves only self-hosted scale-out, so Azure Managed Redis isn't wired.
• Certificate-bound tokens over mTLS #108: a custom HeaderConverter reads Container Apps' X-Forwarded-Client-Cert (Cert only; a header with more than one element is refused). The built-in converter can't parse that format.
• Root-wide identification with fresh-OS auto-resolve. This replaces Agent identification #131's subtree-only candidates. Candidates span the whole root tree, and different root trees never match. An OS installed less than 24 h before enrollment, with exactly one match, rebinds automatically. The safeguard the coordinator added on top is item 107.
• Core-principles review (2026-10-26): pair agent and api versions now, with a defined refusal for unsupported agents; add per-OS seams and the multi-OS fixes now; set default rate limits on three endpoints (token, enrollment, invitation redemption); squash the branch's migrations into one InitialCreate.

Hosting and operations

1. 🔒 Signing and encryption keys stored in the database, wrapped by the key-encryption key #106 Data Protection key encryption. Chosen: keep the custom KEK envelope on Data Protection's IXmlEncryptor extension point (AES-256-GCM data key per key, RSA-OAEP-256 wrap, Key Vault kid pinned), and fail closed (no auto-generated key) when no stored key decrypts on this host. Alternatives: the built-in ProtectKeysWithCertificate/ProtectKeysWithAzureKeyVault. Why: the built-ins use PKCS#1 v1.5 or OAEP-SHA-1, and AES-CBC with no MAC (AES-128 for Key Vault), with no kid pinning, which is below the standards floor.
2. Signing and encryption keys stored in the database, wrapped by the key-encryption key #106 ring unreadable at start. Chosen: if the database is unreachable or not migrated at host start, keep Data Protection's default (it generates keys) and log a warning. Alternative: fail closed there too. Why: hosts can start before migrations run. Residual risk: a host with the wrong KEK that starts during an outage can add a key once the database returns.
3. Key rotation and reload without restart #107 key retention. Chosen: retired signing and encryption keys are kept for 90 days (the absolute refresh-token cap), then deleted. Each host reloads keys on a timer computed from the stored keys. Alternatives: 14-day retention; keep keys flagged; poll the table or use LISTEN/NOTIFY. Why: the bound holds for any configured token lifetime, and a deterministic schedule adds no moving parts.
4. Hardening baseline for the hosts #105 health probes. Chosen: /alive and /health are served only on a separate HealthProbes:Port, matched by local port and placed ahead of HSTS, rate limiting and authentication. The AppHost assigns the port. Alternative: probes on the public ports. Why: probes stay off the public surface and outside the limiters.
5. Hardening baseline for the hosts #105 HSTS. Chosen: max-age=63072000; includeSubDomains; preload on every host except in Development. Alternative: a shorter max-age, or no preload. Why: these are hstspreload.org's requirements, and Microsoft advises against HSTS in development.
6. Certificate-bound tokens over mTLS #108 TLS client certificates. Chosen: Kestrel on api allows but doesn't require client certificates, and OpenIddict validates them. Trusted CAs for tls_client_auth are a server-wide PEM list (Identity:TlsClientCertificateAuthorities); with none set, the method is off. Alternatives: RequireCertificate; a PEM file path or Key Vault. Why: callers without certificates keep working, and OpenIddict accepts trusted roots only globally.
7. Certificate-bound tokens over mTLS #108 proof-of-possession seam. Chosen: one class (ProofOfPossession) configures the accepted proofs and token binding, and enforcement is OpenIddict's built-in ValidateProofOfPossession. Alternative: wrap OpenIddict's handler in custom code. Why: no custom PoP code (ADR-0004), and DPoP can be added in the same place later.
8. Superadministrator from the Entra app role #113 deploying directory setting. Chosen: auth refuses to start without a valid Entra:DeployingTenantId. Alternative: make it optional and fail closed, so nobody is a Superadministrator. Why: a misconfiguration fails loudly at startup instead of silently.
9. Recent-MFA step-up #120 Entra configuration for operators. Chosen: sign-ins without the auth_time optional claim are refused, and the README tells operators to add a Conditional Access policy that requires MFA at every sign-in. Alternative: fall back to the time auth received the sign-in. Why: Entra SSO can return an old MFA, so the time of receipt would overstate freshness.
10. New dependencies (all MIT). Fluent UI Blazor 5.0.1, bUnit 2.12.5, Yarp.ReverseProxy 2.3.0 and Microsoft.AspNetCore.Authentication.OpenIdConnect 10.0.13 (Web host becomes the backend-for-frontend #112); Microsoft.Azure.SignalR 1.33.1, SignalR.StackExchangeRedis 10.0.13, Aspire.Hosting.Azure.SignalR/Redis 13.6.3 and Testcontainers.Redis 4.16.0 (Real-time hosting chosen by configuration #133); Scalar.AspNetCore 2.18.3 (Public API reference with Scalar #135).

Dashboard host (web)

11. Web host becomes the backend-for-frontend #112 web's shape. Chosen: a Blazor Web App host plus a WebAssembly client, WebAssembly render mode only, no prerendering. The server renders only the document. Alternatives: standalone WASM served with MapFallbackToFile; Auto or Server render modes. Why: this is Microsoft's BFF shape, and the import map comes from endpoint metadata, so its CSP hash is exact.
12. 🔒 Web host becomes the backend-for-frontend #112 web's tokens and client certificate. Chosen: web redeems codes at api's mTLS alias with self_signed_tls_client_auth, so its tokens are certificate-bound and it has no secret. Its certificate is a StoredKey (new use WebClient, RSA-3072, rotated every 90 days). web registers its own OpenIddict client at startup. Alternatives: a client secret; a separate certificate table; seeding the client from the migration service.
13. Web host becomes the backend-for-frontend #112 session storage. Chosen: the __Host- cookie holds only an encrypted ticket with sub and a session ID. Tokens live in a DashboardSessions table, protected per session, so any replica can serve the session and deleting the row defeats a replayed cookie. Alternative: an ITicketStore that holds the whole ticket. Why: same effect with fewer moving parts.
14. Web host becomes the backend-for-frontend #112 CSRF. Chosen: every state-changing request to web must carry X-CSRF: 1, otherwise 403 problem+json. Blazor's antiforgery is off. Alternatives: 400 (ASP.NET antiforgery's choice) or 401 (Duende's). Why: the request is understood but refused (RFC 9110 §15.5.4).
15. Web host becomes the backend-for-frontend #112 CSP. Chosen: a strict policy (style-src-elem 'self', 'unsafe-inline' only on style-src-attr, img-src 'self' data:). Fluent UI's FluentLayout inline <style> is blocked, and app.css repeats its mobile rules. Alternatives: 'unsafe-inline' on style-src-elem, or dropping FluentLayout. Why: keeps the standards floor.
16. Web host becomes the backend-for-frontend #112 proxy allow-list and CORS. Chosen: YARP forwards only /api/** and /hubs/dashboard/** (with the person's token) and the docs document (anonymous). It strips cookies, Authorization, CSRF and forwarding headers. There's no CORS on any host. Authorization responses use response_mode=query, and PAR is off for web. Alternative: keep CORS for direct dashboard-to-api calls. Why: the browser never holds a token.
17. Web host becomes the backend-for-frontend #112 certificate chain time. Chosen: client-certificate chains are checked on the hosts' TimeProvider (a cloned OpenIddict chain policy). Alternative: the real clock. Why: makes rotation testable. Production behaviour is unchanged.

Data and tenancy

18. Tenant filter over the closure table #111 tenant filter design. Chosen: an EF Core named query filter that runs EXISTS over the closure table. Device-owned rows (agents, commands, telemetry) are scoped through their device, so a device transfer rewrites nothing. Alternatives: a mapped table-valued function; copying the tenant onto every device-owned row. Why: plain LINQ, proven on PostgreSQL, and history follows transfers for free.
19. 🔒 Tenant filter over the closure table #111 bypass mechanism. Chosen: bypasses are values of a TenantScopeBypass enum, used only through IgnoreTenantScope(reason) and tagged into the SQL. An IL-scanning architecture test fails on any other IgnoreQueryFilters. Hosts default to no assigned tenants. Alternatives: a Roslyn analyzer; a source-text scan; unfiltered until RBAC. Why: fails closed and keeps every bypass enumerable.
20. 🔒 Tenant-scoped RBAC core #114 per-endpoint tenant filter. Chosen: the filter admits only tenants where the caller's role grants the endpoint's scope and the token carries it. Everything else reads as missing (404 for items, 400 for body references), so a Viewer gets 404, not 403, on PATCH. Alternatives: filter by every assignment and check the scope per action (403); 403 when the scope is granted nowhere. Why: central and fails closed.
21. Tenant-scoped RBAC core #114 role assignment cache. Chosen: role assignments are read once per request, with no cross-request cache. Alternative: a short timed cache. Why: revocation takes effect on the next request, and no invalidation across replicas is needed.
22. Tenant-scoped RBAC core #114 references outside reach. Chosen: a parent tenant outside the caller's reach on POST /tenants is 400, as if it were missing (Device transfer between tenants #123 does the same for a device transfer's destination). Alternative: 404, as the Superadministrator from the Entra app role #113 handoff suggested. Why: /tenants exists, and a different answer would reveal that the tenant exists.
23. Tenant-scoped RBAC core #114 roles are deployment-wide. Chosen: GET/PATCH/DELETE /roles need the scope from a role at some tenant. PATCH and DELETE exist and answer 409 for built-in roles. Role ETags hash the role's content. Alternative: no write methods until custom roles. Why: the refusal for built-in roles is observable, and the API shape is ready for custom roles.
24. 🔒 Tenant-scoped RBAC core #114 user identity uniqueness. Chosen: one User per Entra (tid, oid) globally, 409 on a duplicate. This reveals that the identity is a user somewhere. Assigning a role needs the user to be visible to the caller. Alternative: allow a user per tenant. Why: one person, one user record. Users owned elsewhere join through invitations.
25. Tenant-scoped RBAC core #114 cascades. Chosen: deleting a tenant cascades its users and their role assignments, deleting a user cascades their assignments, and roles are Restrict. Alternative: block or soft-delete. Why: matches the spec's tenant deletion.
26. Tenant-scoped RBAC core #114 person or application token. Chosen: a token names a person when its sub is {tid}:{oid} and differs from client_id (PersonSubject, shared by auth and api). Alternative: a dedicated claim. Why: works with the existing token contents (ADR-0007).
27. 🔒 Superadministrator from the Entra app role #113 Superadministrator re-read. Chosen: auth's session is marked fresh only straight after Entra, and each token issuance consumes that mark, so the next issuance sends the person back to Entra's SSO. The hourly check (Session checks, sign-out and Entra front-channel logout #119) also re-reads the role. Alternatives: trust the cookie for its lifetime; read Graph at each issuance; force an MSAL refresh. Why: meets story 59 with no new permissions.
28. Superadministrator from the Entra app role #113 how a Superadministrator meets the filter. Chosen: IAssignedTenants.IsSuperadministrator makes TenantScope keep every row, and this isn't a bypass. Only a Superadministrator creates root tenants (403 otherwise). Alternatives: return every root as "assigned"; a named bypass. Why: a Superadministrator's normal view is every tree, not an exception.
29. Superadministrator from the Entra app role #113 deployment.*. Chosen: deployment.* scopes count only for a Superadministrator, enforced in RequireScopeHandler. A token that has the scope but no Superadministrator gets a plain 403 without insufficient_scope. Alternative: rely on role scopes alone. Why: asking for the scope again can't help (RFC 6750 §3.1).
30. 🔒 Role assignment management and Administrator protections #116, Invitations #121, App-only API applications #124 anti-escalation. Chosen: you can grant a role, invite to it or give it to an API application only if its scopes fit your role scopes at the tenant ∩ your token's scopes. Superadministrators skip the check. Alternative: compare with role scopes only. Why: the spec defines effective access as token ∩ role ∩ subtree, and role-only checks could never refuse anything with the built-in roles.
31. Role assignment management and Administrator protections #116 immutable role assignments. Chosen: no PATCH (405). A downgrade is a revoke plus a grant. Alternative: merge-patch roleId with the same guards. Why: KISS, and Azure RBAC's shape (ADR-0010).
32. 🔒 Role assignment management and Administrator protections #116 Administrator protections. Chosen: revoking a peer's Administrator assignment needs an Administrator at a strict ancestor (403). "Last Administrator" (409) means no other Administrator at the tenant or above. A Superadministrator may remove the last one. Revoking your own is allowed unless you're the last. Alternative: refuse everyone, Superadministrators included. Why: the same rule as the tenant-deletion guard.
33. Role assignment management and Administrator protections #116 [RequireAncestorAdministrator] semantics. Chosen: a tenant outside the caller's reach passes the requirement, so the tenant filter answers 404 instead of a 403 that reveals the tenant exists. The requirement fails closed when the route names no tenant, and its refusal is a plain 403. Alternative: 403 everywhere. Why: avoids revealing that a tenant exists.
34. Role assignment management and Administrator protections #116, Device transfer between tenants #123, Tenant deletion #134, fix: one global tenant-tree lock. Chosen: role-assignment revocation, device transfers and the tenant-deletion guard run under TenantTree.LockKey inside EF's execution strategy (retries on). Enrollment takes the lock shared, plus one advisory lock per (root tree, hardware identifier). Alternatives: per-root locks; disabling EF retries. Why: simplest way to stop races with tree moves. Revisit if it becomes a bottleneck.
35. 🔒 Users management #117 user edits. Chosen: only displayName is editable, and the Entra identity and owning tenant are read-only (400). Editing a user who holds role assignments needs roleassignments.write at every tenant where they hold one, out-of-reach tenants included. Alternative: allow re-linking the Entra identity. Why: re-linking would hand that person the user's assignments, which is account takeover.
36. Agent approval hold and agent status #130 approval hold. Chosen: holdsNewAgentsForApproval is a tenant field (PATCH, tenants.write). The DTO shows the effective value plus approvalHoldInherited. Turning it off where an ancestor holds is 409, and sending back the inherited value is a no-op. Alternatives: a sub-resource or :hold/:release actions; accepting the change silently. Why: it's a setting, not a lifecycle state.
37. Tenant transfers #122 tenant transfer API shape. Chosen: /tenants/{id}/transfers/{transferId} with :accept, :decline and :cancel, and a tenant view filtered by direction, status and includeDescendants. States are Pending, Accepted, Declined and Cancelled, with no separate Completed state. Alternatives: a top-level /tenant-transfers; separate incoming and outgoing collections; a Completed state. Why: transfers nest under their permanent owner, and accept-and-complete is atomic.
38. Tenant transfers #122 :cancel added. Chosen: the proposing side can withdraw a pending transfer, though the ticket doesn't list it. Alternative: no withdrawal. Why: one pending transfer per tenant (partial unique index) would otherwise block the tenant until the receiver declines.
39. Tenant transfers #122 who sees a transfer. Chosen: anyone who reaches the transferred tenant, its parent when proposed, or the new parent. Both sides see the live names of the tenant and the new parent through a not-audited bypass. The former parent is shown by ID only. Alternatives: IDs only; names snapshotted at proposal. Why: the receiver must know what it's accepting.
40. Tenant transfers #122, Device transfer between tenants #123 one device per machine per root tree on transfers. Chosen: checked only for moves that change root tree, under the lock: at acceptance for tenant transfers (the 409 lists device ID pairs only), and for device transfers (409 that never names the other device). Alternatives: check every move, or also at proposal. Why: a move within one tree brings no new machine, and Keep both may legitimately leave duplicates.
41. 🔒 Device transfer between tenants #123 the hardware check can reveal that a machine exists. Chosen: the device-transfer check reads the whole destination root tree past the filter, so a refused caller learns that some device for that machine exists there, even in parts of the tree they can't see. Alternative: check only devices the caller can see, which would allow duplicates. Why: the rule can't be enforced otherwise.
42. 🔒 Tenant transfers #122, Device transfer between tenants #123 no recent MFA on transfers. Chosen: tenant transfers need [RequireAncestorAdministrator] but no recent MFA. Device transfers need only devices.transfer, which Technicians hold, with neither recent MFA nor an ancestor Administrator. Alternative: [RequireRecentMfa] on propose/accept and on device transfer, as one-way actions. Why: the spec reserves recent MFA for tenant deletion, scripts and terminal.
43. Tenant transfers #122 same person on both sides. Chosen: someone with authority on both sides can propose and accept their own transfer. Alternative: require a different person to accept. Why: nothing in the spec asks for two people.
44. Tenant transfers #122 transfer foreign keys. Chosen: a transfer is deleted with the tenant it moves or with its new parent. The former parent may be deleted after acceptance (set to null). Alternative: keep transfer rows. Why: the audit trail survives either way.
45. Device transfer between tenants #123 other device-transfer conflicts. Chosen: transferring to the device's own tenant, or into a tenant at its MaxDevices, is 409. Alternative: 200 no-op for the same tenant. Why: a transition the state doesn't allow is 409, and a no-op would write audit entries for nothing.
46. Tenant deletion #134 deletion preview. Chosen: GET /tenants/{id}:preview-delete (a GET custom method, AIP-136), with tenants.delete and [RequireAncestorAdministrator] but no recent MFA. It lists child tenants, devices, outside role assignments and tenants that would be left without an Administrator. The 409s carry the same lists as extension members. Alternatives: ?validateOnly=true on DELETE; a /deletion-preview sub-resource.
47. 🔒 Tenant deletion #134 outside role assignments in the preview. Chosen: the preview shows the deleting Administrator the assignments that the deleted tenant's users hold elsewhere, even in other trees, as IDs only. Alternative: show only assignments within the caller's reach. Why: the spec requires showing what the cascade removes, and "whoever controls a user's owning tenant controls that user".
48. Tenant deletion #134 deleted tenants' audit trail. Chosen: a DeletedTenants table (no FKs, never exposed) stores the ancestor chain frozen at deletion, and the audit filter uses it. The deleted tenant's name isn't resolved. Alternative: also follow the surviving ancestors' current ancestry. Why: the spec says "the ancestor chain it had at that moment".
49. 🔒 Tenant deletion #134 cascade and sessions. Chosen: each cascaded removal is audited where it was, with detail tenant-deleted, plus a new user.deleted. Pending transfers go by FK cascade with no entries. Deleted users lose every session and token after the commit, and those session.revoked entries are deployment-level. Alternative: end sessions before the commit. Why: a refused deletion must not end anyone's session.
50. Tenant deletion #134 "live devices". Chosen: every device blocks deletion until anonymous device records arrive (Spec: monitors, alerts and telemetry retention #89). Agents awaiting identification don't block and are deleted with their OAuth clients. Alternative: define liveness by last check-in now. Why: the anonymous-record concept isn't built yet.
51. Align tenant updates and the agent executor with AGENTS.md conventions #144 tenant lifecycle. Chosen: :suspend (from Active), :activate (from Suspended or Cancelled) and :cancel (from Active or Suspended), with anything else 409. All need tenants.write. Alternatives: Cancelled as terminal; :resume/:reactivate; a scope per transition. Why: a reversible Cancelled closes no doors, and ADR-0010 has five fixed verbs.
52. Align tenant updates and the agent executor with AGENTS.md conventions #144 strict merge patch. Chosen: patches naming non-editable or unknown members (status, parentTenantId, wrong casing) are 400, for tenants and devices alike. Alternative: silently ignore output-only fields (AIP-203). Why: never return 200 for a failure, and the error points clients at the actions.

Identity, sessions and MFA

53. Dashboard session refresh and session caps #118 web's 12-hour session. Chosen: web's refresh tokens get a fixed 12 hours, set per token for signal9-web only, while global sliding expiry stays on. Idle is judged server-side to the minute (LastSeenAt), and web's cookie ticket is a fixed 12 hours. Alternatives: global DisableSlidingRefreshTokenExpiration; a per-application setting; a 1-hour sliding cookie. Why: API applications need sliding expiry, and ASP.NET's sliding cookie really ends after 30–60 minutes.
54. 🔒 Dashboard session refresh and session caps #118 idle at auth. Chosen: auth's own cookie is 1 hour sliding, plus a 12-hour cap from the Entra sign-in, which is how story 49 is met. auth doesn't refuse an idle dashboard refresh itself; web enforces idle and revokes. Alternative: auth also refuses a dashboard refresh token whose last rotation is over 1 hour old. Why: the spec gives idle enforcement to web.
55. Dashboard session refresh and session caps #118 refresh mechanics. Chosen: a SELECT … FOR UPDATE lock on the session row serializes refreshes across replicas. Refresh happens 1 minute before expiry, with a 15-second timeout that isn't cancelled by the browser leaving. Every api 401 is held back, refreshed once and retried (bodies buffered). Alternatives: an advisory lock; optimistic concurrency. Why: avoids double rotation, and a lost rotated token would sign the person out.
56. Dashboard session refresh and session caps #118 sessions at deploy. Chosen: the LastSeenAt migration defaults to 0001-01-01, so sessions open at deploy end at once. Alternative: backfill the current time. Why: those sessions have no refresh token anyway.
57. 🔒 Fix: durable sign-out revocation. Chosen: ended dashboard sessions stay as rows (EndedAt, RevocationDueAt, RevocationAttempts), ignored by every read, until auth confirms revocation with a 2xx. Retries back off from 1 to 30 minutes on a leased claim, and give up 12 h 10 min after sign-in with an error log. Alternatives: a separate pending table; revoke before deleting, which blocks sign-out while auth is down; retry forever.
58. Session checks, sign-out and Entra front-channel logout #119 a session is one ad-hoc authorization per code. Chosen: each issued code gets its own OpenIddict authorization plus a SignInSessions row. A consented API application's permanent authorization records only the consent. Alternative: keep tokens on the permanent authorization. Why: logout by sid must not delete consent, and revoking a shared consent would end every session.
59. Session checks, sign-out and Entra front-channel logout #119 hourly Entra check. Chosen: a background job on auth (every 5 minutes, a session is due 55 minutes after Entra last vouched). The MSAL token cache moves to the database, encrypted. The forced refresh asks only for openid profile offline_access. Alternatives: check inside the refresh at api; Graph User.Read. Why: keeps Entra's credential on auth only, and needs no extra permission.
60. 🔒 Session checks, sign-out and Entra front-channel logout #119 what ends a session. Chosen: MSAL finding no refresh token counts as fatal (fail closed). Ended Entra sessions are timestamped and kept 90 days. Every refresh checks that the session exists, its Entra session hasn't ended, and the person holds a role assignment (or is a Superadministrator). Removing the last assignment revokes sessions at once. Alternative: treat a missing cache entry as transient.
61. 🔒 Session checks, sign-out and Entra front-channel logout #119 explicit sign-out leaves auth's cookie. Chosen: signing out revokes every token but doesn't end auth's own sign-in cookie (≤ 1 h idle) or Entra's session, so signing in again within the hour skips Entra. Alternative: OIDC RP-initiated logout from web to an end-session endpoint on auth and on to Entra. Why: the spec asks for token revocation, and Entra's SSO would behave the same.
62. 🔒 Session checks, sign-out and Entra front-channel logout #119 front-channel logout requires iss. Chosen: a request without iss is refused (400, logged), because a sid is unique only per issuer. Alternatives: match sid across all directories (weaker); drop front-channel logout and rely on the hourly check. Why: Microsoft documents that Entra sends iss, though community reports say it doesn't. Deployed proof #1 decides this.
63. 🔒 Fix: Entra answering for someone else. Chosen: if the refreshed ID token's subject doesn't match the session, the session ends (audited, "Entra answered for someone else"). Sessions are grouped by home account and sign-in directory. Alternatives: treat it as unavailable and retry; ignore it. Why: retrying could keep an unconfirmed person signed in indefinitely, and the mismatch isn't transient.
64. Fix: session-check ordering. Chosen: the hourly check ends sessions before recording the Entra session as ended. Alternative: the reverse order. Why: the refresh in between then reports the check's reason. Either order is safe, because the per-refresh check catches a session started meanwhile.
65. Fix: ID2079 revocation race. Chosen: Signal9's handler runs before OpenIddict's. It revokes the authorization and its tokens, then re-reads the token row through EF (ReloadAsync) so OpenIddict's own revocation succeeds. Alternatives: replace OpenIddict's RevokeToken handler; rewrite ID2079 to 200 in a response handler. Why: keeps OpenIddict's handler, but relies on the EF store tracking the token entity within the request.
66. 🔒 Recent-MFA step-up #120, App-only API applications #124, fix: MFA-gated actions for applications. Chosen: an application acting as itself passes [RequireRecentMfa] (DELETE /tenants, RunScript) only with an MFA-approved live grant of the scope and non-secret authentication, otherwise a plain 403. RunScript also needs terminal.execute from the role (Scope catalogue and scope-annotated endpoints #110, Tenant-scoped RBAC core #114). Alternative: let app-only tokens through. Why: ADR-0010 and fail-closed.
67. Recent-MFA step-up #120 the BFF doesn't re-check auth_time. Chosen: web doesn't compare the ID token's auth_time with the max_age it asked for. auth enforces max_age before issuing the code, and api checks recency on every request. Alternative: add the OIDC Core §3.1.2.1 SHOULD check in web. Why: already enforced twice, and easy to add.
68. Invitations #121 invitation scopes. Chosen: invitations use roleassignments.read/write and the grant anti-escalation rule, with no invitations.* scopes and no users.write needed. Alternative: a new invitations family in the catalogue. Why: an invitation is a role assignment granted in advance, and ADR-0010 has no invitations noun.
69. Invitations #121 redemption flow and codes. Chosen: GET shows the offer and POST (with antiforgery) accepts it. Unknown is 404; used, expired or revoked is 410 before sign-in; another directory or person is 403; a role already held is 409. No refusal uses the invitation up. Revoking an expired invitation is allowed. Alternative: redeem on GET after sign-in. Why: link scanners and prefetchers can't use the link up.
70. 🔒 Invitations #121 redemption reuses an existing auth session. Chosen: if the browser already has a sign-in at auth, redemption uses it; only otherwise does it go to Entra. The page names the account before Accept. Alternative: always send the person to Entra, optionally with prompt=login. Why: KISS and consistent with authorize and consent. Risk: on a shared browser the wrong account can accept.
71. 🔒 Invitations #121 creator's access isn't re-checked at redemption. Chosen: an invitation stands once made, until it's revoked or expires (72 h), even if its creator has lost the access that allowed it. Alternative: re-check the creator's role scopes at redemption. Why: KISS. Revoking the creator doesn't withdraw their open invitations.
72. Invitations #121 ownership on redemption. Chosen: a new user is owned by the invitation's tenant. An existing user keeps their owning tenant and just gains the assignment. The display name comes from Entra's name claim. Alternative: move the user to the inviting tenant. Why: ownership changes only by user transfer (Spec: user transfer between owning tenants #93).

API applications

73. App-only API applications #124 data model. Chosen: an ApiApplication row (tenant, role, granted scopes, fixed auth method) plus an OpenIddict client (client_id = row ID) whose Properties hold the credentials and RFC 8705 subject metadata (Certificate-bound tokens over mTLS #108). Alternatives: a separate credentials table; a subject column; OpenIddict's single ClientSecret. Why: one source of truth per concern, and rotation with overlap.
74. App-only API applications #124 role plus explicit scopes. Chosen: an app-only application has a role (its upper bound) and an explicit scope list within it. The scope list is what "granting an MFA-gated scope" means. Alternative: role only, with MFA-gated scopes implicitly excluded. Why: makes each grant explicit, auditable and refusable per scope.
75. 🔒 App-only API applications #124 fixed authentication method. Chosen: token_endpoint_auth_method is set at registration and can't change. A handler refuses client_assertion from applications not registered for private_key_jwt. Alternative: any registered credential authenticates. Why: a secret application can never hold MFA-gated scopes, and mTLS applications always get bound tokens.
76. App-only API applications #124 MFA-gated scopes. Chosen: scripts.execute, terminal.execute and tenants.delete. Granting one needs a person with MFA in the last 15 minutes (401 RFC 9470), is 403 for an application caller, and 400 for a secret-authenticated application. Alternative: 409 for the secret case. Why: the method can't change, so the conflict can't be resolved.
77. App-only API applications #124 secrets and keys. Chosen: server-generated 256-bit secrets, shown once, default 180 days, maximum 365, several live at once. Keys accepted: RSA ≥ 2048 and EC P-256/384/521; a duplicate is 409. Alternatives: client-chosen secrets; no maximum. Why: follows Microsoft Entra's guidance (< 12 months).
78. Delegated API applications with consent #125 application kind is fixed. Chosen: app-only (role, client credentials) or delegated (no role, redirect URIs, code + refresh + optional PAR), set at registration. Existing rows are backfilled as app-only. Alternatives: one application allowed both grants; a delegated application with a role cap. Why: the spec describes them separately, and KISS.
79. 🔒 Delegated API applications with consent #125 PKCE off requires nonce. Chosen: requirePkce: false is accepted only with requireNonce: true, and every such request must be OIDC with a nonce, enforced server-side. All API applications are confidential. Alternative: a single replayProtection field. Why: RFC 9700 §2.1.1. The dashboard form (fix 16) offers only valid combinations.
80. 🔒 Delegated API applications with consent #125 delegated scopes. Chosen: a delegated application can be granted any catalogue scope except agent, with no anti-escalation check against whoever registers it. Alternative: limit it to the registering Administrator's own scopes. Why: a delegated token never exceeds the signed-in person, which is checked on every request, and no scope is first-party only.
81. Delegated API applications with consent #125, fix 7: delegated access and Superadministrators. Chosen: a delegated token gets the person's assignments confined to the application's subtree and narrowed to its live scopes. Someone assigned at or above the application's tenant counts as assigned at it (an Administrator there, for a Superadministrator), but deployment.* still works. Alternatives: let them act at the application's own tenant; refuse deployment.* unless the application is registered at a root tenant.
82. Delegated API applications with consent #125 consent. Chosen: every API application uses OpenIddict's explicit consent with no admin consent, and web is implicit. A single permanent authorization per person and application grows in place (API application refresh caps and connected apps #126). prompt=none answers consent_required. Only grants are audited. Alternatives: admin consent; a new authorization per consent. Why: one connection is one row.
83. Delegated API applications with consent #125 consent screen and marker. Chosen: a server-rendered page with no script or style, a strict CSP, antiforgery and no-store. It's unstyled for now. The fresh-sign-in marker is consumed when a code is issued or refused. Alternative: consume it on first read. Why: a Superadministrator answering consent isn't looped back to Entra.
84. Delegated API applications with consent #125 PAR. Chosen: PAR is at connect/par on auth only, optional, and limited by the global limiter only. mTLS-authenticated applications can't use it. Alternative: a PAR endpoint at the mTLS alias. Why: the coordinator default; those clients use the plain authorization request.
85. Delegated API applications with consent #125 refresh caps. Chosen: every client except web gets 14-day idle refresh tokens capped at 90 days by a private claim. Chains issued before this change end at their next use. Alternative: let old chains run on. Why: fail closed.
86. Delegated API applications with consent #125 scope error. Chosen: a scope the client may not use is left as OpenIddict answers it (invalid_request, ID2051, on an error page). Alternative: a handler that rewrites it to RFC 6749's invalid_scope redirect.
87. API application refresh caps and connected apps #126 connections API. Chosen: /tenants/{t}/api-applications/{a}/connections/{id} (the OpenIddict authorization ID), a subtree view, and a new /api/v1/me/connections pattern. Revocation is DELETE (204). Alternatives: nest under /users/{id} (a Superadministrator may have no user); top-level /connections; POST :revoke. Why: a revoked consent stops being a connection. /me is new to the API.
88. API application refresh caps and connected apps #126 connection authority. Chosen: apiapplications.read/write with no new scope. For your own connections only the token counts (a Viewer can manage theirs). An Administrator reaches connections to applications registered in their subtree, so a client admin below an MSP-registered application can't. There's no bulk revoke (delete the application instead). Alternatives: a connections.* noun; a bulk :revoke action.
89. 🔒 Fix 15: Administrator applications and the lockout guards. Chosen: app-only applications holding the Administrator role don't count toward the last-Administrator guards (revocation and tenant deletion). Alternative: count them, which would also refuse deleting the last Administrator application. Why: the guard keeps a person able to manage the tree, and an application can't sign in or step up, and its credentials may belong to a vendor.
90. 🔒 Fix 15: peer protection for Administrator applications. Chosen: deleting, re-roling or narrowing an Administrator application needs someone above its tenant (or a Superadministrator, or the application itself). Credential changes aren't peer-protected. So an Administrator at T can't undo an Administrator application they registered at T. Alternative: route credential removal through the peer rule. Why: rotation is routine upkeep.

Agents and devices

91. Agent enrollment and mTLS authentication #128 enrollment takes a self-signed certificate, not a CSR. Chosen: the agent sends its own self-signed certificate (strictly validated: clientAuth, not a CA, P-256/384/521 or RSA ≥ 3072, ≤ 398 days). Alternatives: a CSR with public-key-only matching (deviates from RFC 8705 §2.2); a Signal9 agent CA (contradicts ADR-0004). Why: under self_signed_tls_client_auth the self-signature proves possession like a CSR. This deviates from the AC's wording.
92. 🔒 Agent enrollment and mTLS authentication #128 one self_signed_tls_client_auth check. Chosen: one custom check in Signal9ApplicationManager for agents and API applications. The certificate must be byte-for-byte the first x5c of a registered JWK, its key must match the JWK, and its chain is built trusting only itself, on TimeProvider. OpenIddict's base check is never called. Alternative: add every registered certificate to OpenIddict's trust store. Why: stricter, with one EC path.
93. 🔒 Agent enrollment and mTLS authentication #128 agent identity from the token. Chosen: a token counts as an agent's only with the agent scope, cnf, sub == client_id and a GUID subject. Naming another agent in the URL is 403 (audited). A command result for a device the caller isn't the active agent of is 404. Alternative: identify the agent by URL. Why: ADR-0005.
94. Agent enrollment and mTLS authentication #128 enrollment endpoint. Chosen: anonymous POST /api/v1/agents with the token in the body, 201 with Location. An unknown, revoked, expired or used-up token is one 400 message, and an inactive tenant or device limit is 409. A refused enrollment uses nothing up. The audit actor is anonymous plus IP. Alternative: 401 for a bad token. Why: by analogy with OAuth invalid_grant.
95. Agent enrollment and mTLS authentication #128 enrollment extras. Chosen: GET /tenants/{id}/agents is the "recently enrolled" view. EnrollmentTokenStatus.UsedUp is added (precedence Revoked > Expired > UsedUp > Active). The EnrollmentToken rate-limit policy is keyed by the secret's hash and acquired in the action. Alternative: a dedicated /recently-enrolled resource. Why: follows AGENTS.md's tenant-view convention.
96. 🔒 Agent enrollment and mTLS authentication #128 agent key storage. Chosen: on Windows, a non-exportable CNG machine key (TPM, falling back to the software KSP). On other OSes enrollment fails rather than using an exportable key. Alternative: a software key on Linux/macOS. Why: the standards floor. The cost is no Linux or macOS enrollment yet, though multi-OS agents are a tenet (see the follow-ups).
97. Agent enrollment and mTLS authentication #128 agent runtime config. Chosen: Agent:InstanceId scopes the key name and state folder, and Agent:TenantId is replaced by Agent:EnrollmentToken. The agent builds its own HttpClients per certificate instead of the factory's resilience handler. A refused agent keeps retrying with backoff until Spec: agent installers and lifecycle #76. Alternative: HttpClientFactory with resilience. Why: the certificate goes in the TLS handshake.
98. Enrollment tokens #127 enrollment token design. Chosen: single use is maxUses: 1 (no flag). Rotation keeps the resource and replaces only the secret, with no grace period. There's no DELETE or PATCH, and revoked tokens stay listed. Secrets carry the prefix s9e_ (invitations use s9i_). Alternatives: a singleUse flag; new token on rotation or an overlap window; DELETE. Why: retire leaked installers fast, and secret scanners can recognise the prefix.
99. Agent revocation and key rotation #129 agent_revoked. Chosen: a revoked agent gets a 400 OAuth error agent_revoked from the token endpoint, only after it authenticates. Alternatives: invalid_client (401); deleting the client. Why: the agent can tell revocation from a bad certificate, and nobody can probe whether an agent is revoked.
100. Agent revocation and key rotation #129 revocation model. Chosen: POST /agents/{id}:revoke with devices.write (Technicians). The device's active agent is cleared (the device goes Offline), and the device gets RequiresAgentApproval for its next agent. Alternatives: devices.delete; keep a revoked agent as active with a Revoked status. Why: story 101 says Technician, and a revoked agent isn't active.
101. 🔒 Agent revocation and key rotation #129 key rotation. Chosen: PUT /agents/{id}/certificate (agent only; GET with devices.read). The old certificate, its tokens and its hub connection are cut off at once. The agent rotates 120 days before its 365-day expiry, using a two-slot key store that survives a lost response. Alternatives: a :rotate action; let old tokens run 10 minutes. Why: a rotation after a suspected leak must take effect at once.
102. Agent approval hold and agent status #130 approval. Chosen: AgentStatus (Active, Revoked, AwaitingApproval, plus Agent identification #131's NeedsDecision). POST /agents/{id}:approve needs devices.write. Held agents heartbeat (no work), see empty pending commands, get 409 on results, and may connect to the hub. Alternatives: an agents.approve scope; refuse the hub until approved. Why: ADR-0010 has five verbs, and the hub lets approval ring the agent promptly.
103. Agent identification #131 an agent awaiting a decision has no device. Chosen: the agent has DeviceId = null and a PendingIdentification row, and the device is created or chosen only on decision (AgentDto.DeviceId is nullable). It counts toward no device limit, and telemetry is 409. Alternative: a provisional device merged on Reinstalled. Why: avoids phantom devices, moved history and audit entries pointing at deleted devices.
104. Agent identification #131 identification API. Chosen: POST /agents/{id}:identify {decision: Reinstalled | KeepBoth, deviceId?} and GET /agents/{id}/candidate-devices. The queue is ?status=NeedsDecision. Reinstalled onto a device whose agent is active revokes that agent. Alternatives: :rebind and :keep-both verbs; a separate flag or resource. Why: one transition named after the glossary term.
105. Agent identification #131 matching rules. Chosen: auto-match only on exactly one candidate with a revoked and no active agent. A match is SMBIOS UUID, or manufacturer and serial together. Junk identifiers are dropped server-side. Identifiers are indexed but not unique, and a match refreshes the device's facts. Alternatives: a serial alone; a unique constraint. Why: Keep both legitimately leaves duplicates.
106. Fix: root-wide identification details. Chosen: candidates are shown per the caller's tenant filter (a West-only admin sees none in East), and Reinstalled accepts only visible candidates. A rebound agent belongs to the device's tenant even outside the token's subtree. Keep both creates the device in the token's tenant. Alternative: options A/B/C from the fix pass. Why: carries out the maintainer's decision without exposing devices the caller can't see.
107. 🔒 Fix: fresh-OS claims are held for approval. Chosen: a fresh-OS single match joins as a held claim, always Awaiting approval. The old agent and the device's facts are untouched until a person approves at the device's tenant, which revokes the old agent. Revoking the claim leaves everything as it was. Alternative: rebind at once. Why: OsInstalledAt and the hardware IDs can be forged with a leaked installer.
108. 🔒 Fix: fresh-OS signal and residual risk. Chosen: the install time is read from the registry InstallDate on Windows and statx birth time on Linux, never .NET's creation time. A time unknown, in the future, or ≥ 24 h old isn't fresh. Residual risks: a person can still approve a forged claim, several claims can coexist, and Windows feature updates reset InstallDate (harmless, since claims are held). Alternative: no auto-resolve.
109. Device transfer between tenants #123 approval state across transfers. Chosen: an active agent keeps its approval state when its device moves into a tenant that holds new agents. Alternative: put it back on hold. Why: the hold is for new agents (story 96), and the person moved the device deliberately.

Real-time

110. 🔒 Dashboard hub scoped to the caller's subtree #132, Real-time hosting chosen by configuration #133 closing hub connections changed elsewhere. Chosen: api re-checks every open dashboard and agent hub connection every 10 s by default (token liveness, live access, groups). So sign-out, logout, Entra refusal, connection revocation and changes on another replica take effect within about 10 s, not at once. Alternatives: LISTEN/NOTIFY; Azure's CloseConnectionAsync; per-event checks. Why: auth and web share only the database, and the check also covers scale-out.
111. Dashboard hub scoped to the caller's subtree #132 dashboard groups. Chosen: a connection joins only its top-most granting tenants, and Superadministrators join one deployment group. Events go to the owner's group and every ancestor's, read live, so transfers need no group change. A caller with no hub scope at any tenant passes negotiate and is closed at start. Alternatives: join every assigned tenant (duplicates); 403 at negotiate.
112. Dashboard hub scoped to the caller's subtree #132 notice shape (public). Chosen: DeviceChanged/DeviceDeleted({deviceId, url}), CommandChanged({deviceId, commandId, url}) and TelemetryReceived({deviceId, sampleId, url}), with no tenant. Device transfers send DeviceChanged to both sides. Alternatives: one generic Changed({kind, url}); DeviceDeleted to the former side. Why: small notices, with details fetched through the BFF (ADR-0009).
113. 🔒 Dashboard hub scoped to the caller's subtree #132 Origin check on web. Chosen: WebSocket handshakes to /hubs/dashboard* must carry web's exact origin, and any hub request that carries Origin must match. Requests without one pass only if they aren't handshakes. Mismatches get 403. Alternative: require Origin on every hub request. Why: the cookie risk exists only at the BFF, and requiring it would break same-origin long polling and SSE.
114. Real-time hosting chosen by configuration #133 stateless negotiation for self-hosted scale-out. Chosen: with more than one replica, api answers negotiate itself with a stateless WebSockets-only response and drops the id, so clients stay unaware of the hosting mode. Alternatives: clients set SkipNegotiation (they'd need to know the mode); sticky sessions. Why: no client or contract change. The cost is emulating SignalR's negotiate response.
115. Real-time hosting chosen by configuration #133 web proxies the service for the dashboard. Chosen: web rewrites api's Azure SignalR redirect to {web}/hubs/dashboard/service/client/... and forwards only that path to the service. Agents connect to the service directly. Alternatives: two SDK endpoints with a custom router; allow the service origin in web's CSP. Why: keeps the no-third-party-origin CSP. ADR-0009 rejects proxying through api only.
116. 🔒 Real-time hosting chosen by configuration #133 service tokens. Chosen: service tokens carry only sub, client_id, cnf, oi_tkn_id, the hub scopes and the Superadministrator role, with a default lifetime of 2 minutes (30 s–10 min). The browser can read this token. Alternative: the SDK default of 1 hour. Why: it's used only to open the connection, and reconnects negotiate again.
117. Real-time hosting chosen by configuration #133 hosting configuration. Chosen: Realtime:Hosting is AzureSignalR (publish default) or SelfHosted (run default). Realtime:ApiReplicas > 1 adds a Redis container and replicas. On Azure SignalR, api refuses direct hub connections (404) except negotiate. Alternative: allow direct connections. Why: a client on api's local connection would never hear a doorbell.

API shape and HTTP

118. Hardening baseline for the hosts #105 rate limiting. Chosen: the token policy is keyed on client_id and IP together. A Global per-IP policy can cover every request, including OpenIddict's own endpoints (revocation and introspection get only Global), but it applies no limit until PermitLimit is configured; only the three defaults in item 141 are on out of the box. Fixed window, with no queueing and 429 plus Retry-After. Alternatives: chained per-client and per-IP limits; placeholder endpoints; sliding window or token bucket. Why: the literal reading of the spec, and simplest.
119. Scope catalogue and scope-annotated endpoints #110 [RequireScope]. Chosen: a small custom attribute on IAuthorizationRequirementData. Several scopes in one attribute mean any one, several attributes must all hold. A 403 carries RFC 6750 insufficient_scope. Alternatives: Microsoft.Identity.Web [RequiredScope] (reads Entra's scp); one policy per scope (can't say "or"). Why: the dashboard hub needs any-of, and the RBAC filter reuses the requirement.
120. Scope catalogue and scope-annotated endpoints #110 scope mapping. Chosen: everything an agent does about itself needs agent. GET /agents/{id} needs devices.read (there's no agents family), cancelling a command needs commands.execute, and RunScript also needs terminal.execute. Alternative: an agents scope family. Why: agents are part of a device's record.
121. Scope catalogue and scope-annotated endpoints #110 OpenAPI and catalogue. Chosen: the OpenAPI document is public and anonymous in every environment. The scope catalogue is registered with OpenIddict, so only catalogue scopes are issued, and it lives in Server, not Contracts. Alternatives: Development only; catalogue in Contracts. Why: story 132 makes the document public. The catalogue's location limits the dashboard (item 128).
122. Public API reference with Scalar #135 docs hosting. Chosen: web hosts Scalar at /docs and proxies only /docs/openapi/** to api. The document moves to /docs/openapi/v1.json with no redirect, and its server is the relative /. Alternative: api serves Scalar and web proxies the page. Why: the page lives under web's CSP, api serves no HTML, and "Try it" uses whichever host served the document.
123. Public API reference with Scalar #135 docs CSP and "Try it". Chosen: /docs adds a per-request nonce to script-src and style-src-elem only. "Try it" sends web's CSRF header through a same-origin customFetch, and tokens typed into Scalar are dropped. Alternatives: hashes (nothing stable to hash); 'unsafe-inline'. Why: CSP3's strict-CSP pattern. Scalar's toasts render unstyled.

Audit

124. 🔒 Audit log #115 bypass audit policy (coordinator). Chosen: every TenantScopeBypass value declares [Audited] or [NotAudited(reason)], enforced by a test. Audited bypasses write a deployment-level tenant-scope.bypassed entry per use; request-time bypasses confined to the caller or guarding an audited action aren't audited. Alternative: audit every bypass once per request (an entry per heartbeat). Why: story 70 names background jobs.
125. 🔒 New not-audited bypasses. Chosen: all of these are [NotAudited]: AgentSelfService, CallerRoleAssignments, CallerApiApplication, AuditPlacement, AdministratorLockoutGuard, UserRoleAssignmentGuard, SessionCheck, InvitationRedemption, Enrollment, TenantTransferParties, TenantTransferMove, TenantTransferDuplicateDevices, DeviceTransferHardwareCheck, CallerConnections, InheritedTenantSettings, TenantDeletion, RoleAssignmentHolder, HeldClaimFacts. All 18 values are not audited; no audited bypass exists yet. Alternative: audit any of them. Why: each reads only the caller's own data or yes/no, and the action it serves is audited.
126. Audit log #115 audit log shape. Chosen: top-level GET /audit-entries (+ /{id}), read-only, no filters yet. One table with no FKs, ordered by a database sequence and append-only by trigger (future pruning needs a migration). Names resolve at read time through the reader's filter. Client IP is stored. Alternatives: a tenant view; append-only by convention. Why: entries outlive what they mention. IP retention is undecided.
127. 🔒 Audit log #115, Tenant transfers #122, Device transfer between tenants #123, API application refresh caps and connected apps #126, Agent identification #131 what is recorded and where. Chosen: only 403 denials (filter 404s would reveal probes); Superadministrator writes but not reads; repeated failures counted per IP in memory per instance. Transfers record at both sides, not the moving tenant. Identification records its outcome, never identifiers. Alternatives: audit reads; a shared database count. Why: no flooding and no leaks.

Dashboard

128. Fix 16 delegated-application scopes. Chosen: the register dialog offers delegated applications only the OIDC scopes and scopes some role grants, so deployment.* stays API-only. Alternatives: move the catalogue into Contracts; add a scopes endpoint. Why: the full catalogue is in Server, which the WASM client can't reference.
129. New dashboard pages. Chosen: role assignments, users, invitations (link shown once, copy by navigator.clipboard.writeText), tenant transfers (new parent entered as a tenant ID), device transfer dialog, agent approvals, connections, and live Devices updates. Every tenant or user picker lists only the first 100 (paging TODO). Alternative: paged pickers now. Why: KISS for this spec.
130. Enrollment tokens #127, Align tenant updates and the agent executor with AGENTS.md conventions #144 small UI choices. Chosen: token expiry is entered as "Expires after (days)", not a date picker. Tenant status uses per-row Suspend, Activate and Cancel buttons, and Cancel has no confirmation because it's reversible. Alternative: a date picker; confirm Cancel. Why: KISS and testable.

Core-principles review

131. Agent version refusal: 400 with problem+json (minimumVersion/maximumVersion), and OAuth unsupported_agent_version at the token endpoint. Alternatives: 426 (for switching protocols, needs Upgrade); 403 (reserved for insufficient_scope); 409. Why: RFC 9110 §15.5.1; Azure answers an unsupported api-version the same way.
132. Agent version problem type URI: the repo's docs/agent-protocol.md#unsupported-agent-version on GitHub. Alternatives: a tag: URI; a future docs domain. Why: RFC 9457 wants a resolvable type, and it's one constant in AgentProtocol.
133. Default supported agent range. Chosen: api's major.minor.0 up to api's own version, inclusive, configurable with AgentVersions:Minimum/Maximum. Alternatives: exact match (any api patch strands every agent until Spec: agent installers and lifecycle #76's updater exists); no maximum. Why: API changes drive supportability.
134. A refused agent idles. Chosen: the agent logs the refusal and its version range, stops talking to the API, and keeps the process running. Alternative: exit. Why: exiting lets SCM recovery or systemd Restart= retry in a loop; Spec: agent installers and lifecycle #76's updater builds on this state.
135. 🔒 Fresh sign-in is server-side and single-use. Chosen: Entra sign-in writes a FreshSignIns row; the cookie holds only its ID, and the authorization endpoint deletes the row on use, issuing a Superadministrator's or re-authenticated code only if that delete wins. Unused rows expire after 10 minutes (the cookie flag lasted 12 hours). Alternatives: a server-side ticket store; keep the replayable cookie flag.
136. 🔒 OIDC prompt and max_age. Chosen: prompt=none never redirects (login_required); prompt=login re-authenticates at Entra, proved by a random attempt ID carried through Entra, and refused (access_denied, audited NotFresh) if Entra's auth_time predates the request by over 1 minute. Alternatives: forward prompt=none to Entra; a clock tolerance on max_age. Why: OIDC Core §3.1.2.1/§3.1.2.6; fixes max_age=0.
137. 🔒 Token encryption algorithm (decision needed). Stays JOSE RSA-OAEP (SHA-1) + A256CBC-HS512: IdentityModel 8.19.2 (used by OpenIddict 7.7.2) has no RSA-OAEP-256. Nothing weakened; RFC 7518 §4.3 rates it Recommended+, but it differs from item 1. Options: (a) accept until IdentityModel adds it; (b) a custom ICryptoProvider with OAEP-SHA-256 (custom crypto to own); (c) symmetric A256KW shared by Signal9's hosts (new key management).
138. 🔒 One self_signed_tls_client_auth certificate policy for agents and API applications: self-signed, not a CA, digitalSignature + clientAuth, ECDSA P-256/384/521 or RSA ≥ 3072, SHA-2, valid now, ≤ 398 days, self-signature verified (the old check never verified it). Alternative: also enforce key size and lifetime at authentication. Nothing shipped, so no registration is affected.
139. web's 401 challenge. Chosen: WWW-Authenticate: Cookie realm="signal9", login="/bff/login" on both of web's 401s. Alternatives: Bearer (wrong, the browser holds no bearer token); an ADR recording a deviation. Why: RFC 9110 §15.5.2 makes the header a MUST, and no registered scheme fits cookie sessions.
140. Preconditions on creates. Chosen: a create's preconditions are evaluated against the collection, so If-None-Match: * is 412 and If-Match: * goes ahead, including the POST-only enrollment and telemetry targets. Alternative: treat POST-only targets as having no current representation, like the heartbeat. Why: RFC 9110 §9.3.3 and §13.1, one rule for clients. It supersedes ETag and If-Match concurrency for resources #137's "If-Match on a create always fails".
141. Rate-limit defaults. Chosen: Token 300/min per (client_id, IP), Enrollment 60/min per IP, InvitationRedemption 30/min per IP, fixed windows. Alternatives: lower values (web refreshes every person's tokens as one client); Token per IP alone (one bucket for the dashboard and a NAT'd site's agents). Gap: rotating client_id from one address gets fresh buckets until Global is configured.
142. Hubs: one registry and one sweeper. A revoked agent's connections are found by scanning the replica's open connections; one sweeper re-checks both hubs; config key Hubs:AccessCheckInterval. Alternatives: an agent-keyed index; one sweeper per hub.
143. A span per background job run. Chosen: PeriodicJob starts an Activity (source OSI.Signal9.BackgroundJobs) around each run, and tests wait on it. Alternatives: poll outcomes on the real clock; a test-only hook. Why: it's a test seam an operator can also use.
144. Entra session check survives resilience timeouts. EntraRefresh.ForceAsync treats any failure but host shutdown as "ask again next run"; a Polly timeout used to abort the whole run, leaving later accounts unchecked for an hour. Found by the fake-clock tests.
145. The fixture's Superadministrator is a real person session, so it shows in sign-in audit entries and session checks; global counts now filter by person. Alternative: an app-only API application (can't create roots or cross trees).
146. Removed scaffold fields: RestartMachine/RestartService, CommandPriority, SubscriptionPlan/Tenant.Plan, Device.MaintenanceMode, IsMutualTls; the GLOSSARY's "Maintenance mode" stays. RunScript stays: it carries terminal.execute and its step-up, covered by Spec: auth, tenancy and agent identity target #63's tests. Alternatives: keep Plan with Basic; drop the glossary entry; remove RunScript until Spec: command reliability, scripts and signing #82.
147. Migrations squashed. Chosen: one generated InitialCreate, with the audit log's append-only trigger carried over by hand. The old closure backfill and clean-up deletes are dropped, because they only served databases older than this branch. Why: nothing has shipped; your decision.

Deferred / follow-up tickets needed

• User deletion (Users management #117): not built. The spec says users.write covers it, which needs the story-27 session cut-off and the story-16 rule.
• Spec: deployment, releases and first-run setup #77 deployment work: Azure PostgreSQL grants (runtime hosts are still Entra administrators; ADR-0011 wants only the migration service) and the AddPostgres branch for self-hosted (Compose) publishing. Also: Container Apps ingress clientCertificateMode (api accept, auth ignore; Certificate-bound tokens over mTLS #108), the Key Vault KEK and wrap/unwrap grant (Signing and encryption keys stored in the database, wrapped by the key-encryption key #106), auth's managed identity and federated credential (Entra sign-in at the auth host #109), writing Entra:DeployingTenantId (Superadministrator from the Entra app role #113), and the migration service.
• Deployed proofs still open: #1, whether Entra sends sid (and iss) in front-channel logout and ID tokens for multi-tenant sign-ins (decides item 62). Dev #5, whether Container Apps ingress replaces a client-supplied X-Forwarded-Client-Cert, its Cert encoding, and the peer IP for ForwardedHeaders:KnownNetworks.
• Standards finding Bump Azure.Extensions.AspNetCore.Configuration.Secrets and 10 others #10 skipped: shared dashboard page boilerplate (mutation and error handling, tenant pickers). It isn't trivial across the pages' different secret and link lifecycles.
• Spec: agent installers and lifecycle #76 agent: stop on agent_revoked instead of retrying, side-by-side installation, the "Update required" status, and re-enrollment.
• Agent key storage on Linux and macOS: non-exportable keys need their own ticket. macOS also has no hardware-identifier reader yet (Agent enrollment and mTLS authentication #128, Agent identification #131).
• Spec: command reliability, scripts and signing #82: command statuses and restructuring or removing RunScript (Separate devices from agents #102, Scope catalogue and scope-annotated endpoints #110).
• Spec: monitors, alerts and telemetry retention #89: the monitors, alerts and webhooks scopes, and anonymous device records (exclude them from the deletion block and add them to the cascade; Tenant deletion #134).
• Spec: reports, schedules and hardware inventory #90: the reportschedules scope.
• Spec: user transfer between owning tenants #93: user transfer (users.transfer is in the catalogue).
• OIDC back-channel logout: waits for OpenIddict 8.
• Audit follow-ups (Audit log #115): a per-tenant view and filters, a retention policy for stored client IPs and pruning (the trigger makes that a deliberate migration), and a proposed glossary term "Audit entry".
• Consent screen design pass (Delegated API applications with consent #125) and public docs on client assertions (typ: client-authentication+jwt, aud = issuer; App-only API applications #124).
• Possibly still open (Hardening baseline for the hosts #105): a host that starts before migrations caches its failed stored-key load and returns 500 until restarted. The suggested fix was a readiness check that loads the keys, or not caching the failure.
• Tests: other tests still use fixed Task.Delays (AgentDoorbellTests, AgentApprovalTests, TenantTreeTests), noted out of scope in the fix pass.
• Azure SignalR live behavioural test: needs a real Azure SignalR resource; only the wiring is tested.
• OpenAPI PATCH bodies are documented as untyped JsonElement, so clients can't discover the editable fields of UpdateTenantRequest and UpdateDeviceRequest.
• Small leftovers: LiveSession.TokenIds has no production reader, and the agent's 409 comment on command results ("or already reported") now applies only to a different report.
• Intermittent failures seen only under heavy load (none in the final runs): an ObjectDisposedException from RSAOpenSsl in StoredKeys.Load, and one 100 s stall in TenantTransferTests.A_decided_transfer_cant_be_decided_again.

Closes #63 Closes #100 Closes #101 Closes #102 Closes #103 Closes #104 Closes #105 Closes #106 Closes #107 Closes #108 Closes #109 Closes #110 Closes #111 Closes #112 Closes #113 Closes #114 Closes #115 Closes #116 Closes #117 Closes #118 Closes #119 Closes #120 Closes #121 Closes #122 Closes #123 Closes #124 Closes #125 Closes #126 Closes #127 Closes #128 Closes #129 Closes #130 Closes #131 Closes #132 Closes #133 Closes #134 Closes #135 Closes #137 Closes #143 Closes #144

🤖 Generated with Claude Code

[github-actions]

Test suites

Suite	Tests	Passed	Failed	Skipped	Other	Duration
OSI.Signal9.Web.Tests	96	96	0	0	0	10.2s
OSI.Signal9.IntegrationTests	783	783	0	0	0	17m 36s
OSI.Signal9.Agent.Tests	64	64	0	0	0	492ms

Total: 943 tests — 943 passed, 0 failed, 0 skipped.

Github Test Reporter by CTRF 💚

🔄 This comment has been updated