docs: define platform admin identity boundary

2026-07-10 13:36:35 +08:00
parent 913a7ae5c0
commit 420c1c40bc
16 changed files with 484 additions and 15 deletions
@@ -8,4 +8,7 @@ Status: open
 What same-origin/CSRF, proxy/TLS, security-header, session lifetime,
 revocation, secret rotation, and request-timeout contract should the initial
 org-admin web surface enforce, and which parts require server-side session state
-rather than the current seven-day stateless cookie?
+rather than the current seven-day stateless cookie? Apply the same browser
+boundary to ADR-0023's separate server-side Platform Session while preserving
+its distinct cookie/token namespace, immediate revocation, per-request grant
+reload, and bounded recent-authentication requirement.
@@ -11,3 +11,6 @@ structured messages, and operational recovery events without weakening
 `Spec.System.Audit`'s pinned AuditEntry-to-run relation. Decide durability,
 failure, retention, and query semantics; then enforce referential integrity and
 observable/recoverable writes instead of silently swallowing lost evidence.
+Do not merge these customer Project/Run records with ADR-0023's already-decided
+separate, append-only, fail-closed Platform Audit; decide only any shared
+retention/export infrastructure without weakening either semantic boundary.
@@ -16,3 +16,7 @@ production-shaped staging, and archive evidence that detection, mitigation,
 reconciliation, verification, escalation, and alert clearing all work. Include
 database/workspace backup failure, failed migration, full-host restore and
 cutover, duplicate/gap review, fallback, and achieved RPO/RTO evidence.
+Also drill ADR-0023 platform-administrator lockout and Platform-owned Feishu
+Application credential loss through the dual-factor offline recovery command,
+expiring Emergency Platform Grant, session revocation, immutable Platform Audit,
+and explicit recovery closeout; never introduce a standing break-glass account.
@@ -1,7 +1,7 @@
 # Decide the platform-administrator identity and audit boundary

 Type: grilling
-Status: open
+Status: resolved

 ## Question

@@ -11,3 +11,44 @@ append-only audit contract will authenticate Platform Administrators for the
 initial service? The decision must keep `/admin/platform` private, make every
 Organization/connection/workload-control mutation attributable, and define a
 reviewable break-glass path without treating platform staff as customer members.
+
+## Answer
+
+Platform Administrators authenticate only through a dedicated Platform-owned
+Feishu Application and a separate, server-side Platform Session. Platform
+Identity, standing grant, invitation, session, audit and emergency grant are
+independent of customer `User`, `OrganizationMembership`, Project permission
+and Project/Run audit. The initial control plane has one peer role only.
+
+The first administrator is created by a versioned, idempotent, transactional
+database bootstrap procedure that runs only when no standing administrator is
+active and atomically records the Platform Audit Entry. Later administrators
+receive short-lived, single-use invitations bound to a specific platform
+Feishu account. The last active standing administrator cannot be revoked;
+revocation immediately invalidates that identity's sessions and invitations.
+
+Every platform request reloads the revocable session and current standing or
+unexpired emergency grant. Administrator, connection/credential,
+Organization-lifecycle, workload-brake and emergency-grant actions require
+recent Feishu OAuth step-up.
+
+Every successful platform mutation commits with a separate append-only
+Platform Audit Entry or fails. Organization Administrators receive a redacted
+projection of platform actions affecting their own Organization. No standing
+break-glass account exists: offline recovery requires controlled host access,
+an off-host recovery key, an incident and reason, and issues only an expiring
+Emergency Platform Grant.
+
+The complete accepted decision and implementation divergences are in
+[ADR-0023](../../../docs/adr/0023-platform-administrator-identity-and-audit.md).
+The pinned semantic invariants are in
+[`Spec.System.PlatformAdministration`](../../../spec/Spec/System/PlatformAdministration.lean),
+and the canonical terms are in [`CONTEXT.md`](../../../CONTEXT.md).
+
+Exact numeric session/invitation/step-up limits and browser mechanics remain
+with [Design the production browser and session boundary](20-design-production-web-session-boundary.md).
+Customer Project/Run audit retention remains with
+[Reconcile the audit and run-history contract](27-reconcile-audit-history-contract.md),
+without reopening Platform Audit's separate fail-closed boundary. Implementation
+is owned by [Build the private platform-administrator control plane](45-build-private-platform-admin-control-plane.md),
+and recovery rehearsal by [Write and drill production incident recovery runbooks](31-write-and-drill-incident-runbooks.md).
@@ -11,7 +11,15 @@ Implement authenticated `requirePlatformAdmin` APIs and a private
 Organizations, bootstrap their OWNER, view/change lifecycle state, configure
 and test each customer-owned Feishu Application, configure the Organization's
 distinct platform-managed Provider Connection, and manage platform-admin
-allowlisting. Prove anonymous users, ordinary members, and Organization admins
-cannot load either page data or mutations; every sensitive action is validated,
-redacted, audited, observable, and covered by browser-level critical-journey
-tests. Emergency workload controls remain integrated through ticket 37.
+invitations and revocations. Implement ADR-0023's separate Platform Identity,
+single standing role, guarded bootstrap procedure, identity-bound single-use
+invitations, revocable server-side Platform Session, recent-authentication
+step-up, last-administrator protection, fail-closed append-only Platform Audit,
+Organization-safe audit projection, and dual-factor offline recovery with
+expiring Emergency Platform Grants. Replace rather than reuse the legacy
+customer-`User`-bound `PlatformRoleAssignment`/`TEACHER` model. Prove anonymous
+users, ordinary members, and Organization admins cannot load either page data
+or mutations; every sensitive action is validated, redacted, audited,
+observable, and covered by browser-level critical-journey tests. Emergency
+workload controls remain integrated through
+[Add audited emergency workload brakes](37-emergency-workload-brakes.md).
@@ -42,6 +42,7 @@ rollback and recovery, and no known critical security or data-integrity gaps.
 - [Define initial abuse and capacity controls](issues/05-define-abuse-capacity-controls.md) — require layered fail-closed limits, durable Organization-fair admission, explicit backpressure, bounded files/storage/runs, soft usage alerts, and audited emergency workload brakes; calibrate numerical ceilings under production-like load.
 - [Audit backup, migration, and disaster recovery safety](issues/06-audit-backup-migration-recovery.md) — separate persistent state from releases, define a database/workspace checkpoint and recovery objectives, make migrations compatibility-gated, and prove complete off-host backup sets through isolated restore and cutover drills.
 - [Audit the accepted product surface for production completeness](issues/07-audit-product-surface-completeness.md) — retain the guarded Organization APIs and single-app Feishu vertical slice, but require explicit Organization-scoped Feishu/provider connections and external-identity namespaces, private platform and Organization admin control planes, and the full ADR-0022 capacity surface before release.
+- [Decide the platform-administrator identity and audit boundary](issues/42-decide-platform-admin-identity-audit.md) — use a dedicated platform Feishu issuer, one peer administrator role, guarded bootstrap and identity-bound invitations, revocable server-side sessions, atomic append-only Platform Audit, and dual-factor offline recovery without a standing break-glass account.

 ## Fog