ADR 0023: Platform Administrator Identity And Audit Boundary

Status

Accepted.

Context

ADR-0021 separated /admin/platform from Organization administration but left the exact platform identity store and audit schema open. That choice must be settled before exposing the panel: customer Feishu identities are scoped by their customer-owned applications, Organization membership must not confer platform authority, and a platform operator can create tenants, change connections, rotate credentials, or stop workloads across tenant boundaries.

The current implementation is not the accepted platform model. PlatformRoleAssignment points at the customer-side User, includes a legacy TEACHER value, and has no platform login or guard. The current browser session is a seven-day stateless customer cookie, while AuditEntry is Project/Run oriented and deliberately best-effort. Reusing any of these would couple the two control planes and make immediate revocation or fail-closed privileged audit impossible.

Decision

Identity issuer and authority

Platform Administrators authenticate only through one dedicated Platform-owned Feishu Application. It is separate from every Organization's Customer-owned Feishu Application and cannot grant Organization membership or Project permission.

A PlatformIdentity is scoped by that platform application and its verified external Feishu user identity. It is not a customer User. The same person may also have customer identities, but there is no implicit link, shared session, or authority propagation between them.

The initial platform control plane has exactly one standing role: Platform Administrator. There is no Platform Owner, Super Admin, or Teacher hierarchy. The first administrator has no permanent special authority after another administrator is active.

Bootstrap, invitation, and revocation

The first Platform Administrator is granted through a checked-in, versioned, idempotent and transactional bootstrap database procedure. It accepts only a verified Platform Identity, refuses to run while any standing Platform Administrator is active, and atomically writes the grant plus its Platform Audit Entry. Ad-hoc manual INSERT statements and permanent environment allowlists are not supported bootstrap paths.

Later administrators join through short-lived, single-use invitation links created by an active Platform Administrator. An invitation is bound to one specific Feishu account in the Platform-owned Feishu Application; possessing a link without authenticating as that account is insufficient. The invitation records its inviter and reason and becomes terminal after acceptance, expiry, or revocation. One active Platform Administrator approval is sufficient for the initial service.

All standing Platform Administrators are peers. An administrator may invite or revoke another administrator, but the last active standing administrator cannot be revoked. Revocation immediately invalidates all Platform Sessions and all unclaimed invitations belonging to the revoked identity.

Platform Session and step-up authentication

Platform Session is a separate, server-side, revocable session with a distinct cookie/token namespace. The browser receives an opaque random token; persistence stores only its hash and binds the session to a Platform Identity. Every request reloads the session and active grant. The session carries no Organization, membership, Project, or customer Feishu authority.

Administrator lifecycle changes, platform or customer Feishu connection changes, platform-managed Provider credential changes, Organization lifecycle changes, workload-brake changes, and Emergency Platform Grant changes require recent Feishu OAuth reauthentication. Exact session/idle/step-up durations, CSRF, cookie and proxy/TLS mechanics belong to the production browser/session boundary decision; they must be configurable under checked maximums rather than silently inheriting the current seven-day customer cookie.

Platform audit

Platform Audit Entry is a separate append-only record from customer Project and Agent Run audit. Every successful platform mutation and its audit entry commit in the same database transaction. If the audit entry cannot be written, the mutation fails. Platform audit is durable business evidence, not best-effort telemetry.

An entry identifies the Platform Identity and Platform Session, action, target kind and identifier, affected Organization when applicable, mandatory reason for security-sensitive actions, request/correlation identity, outcome, time, and redacted before/after facts. It never stores credential, token, recovery-key or other plaintext secret material. The normal service path can append and read but cannot update or delete history.

Platform Administrators can read the complete redacted platform audit. Organization Administrators can read a customer-safe projection of entries affecting their Organization, including Organization lifecycle, Feishu/provider connection, and workload-brake changes; they cannot read other Organizations, platform administrator lifecycle, recovery material, or internal security events.

Offline recovery and break-glass

There is no standing break-glass web account or shared emergency password. Recovery uses a checked-in offline command from a controlled production-host console. The supported procedure requires both privileged host access and a recovery key held outside the host, environment file, and ordinary backup set. It also requires an incident identifier, reason, and one explicit recovery action.

Recovery may revoke Platform Sessions, repair the Platform-owned Feishu connection, or issue an Emergency Platform Grant to a verified Platform Identity. An emergency grant is time-bounded, automatically expires, is not a standing role, and must be explicitly closed when recovery finishes. Every recovery action is represented in the append-only Platform Audit. Two factors are mandatory for the initial service; two separate human approvers are not.

Consequences

Platform identity, invitation, standing grant, server-side session, platform audit, and emergency-grant persistence must be distinct from customer User, OrganizationMembership, Project permission, and Project/Run audit.
requirePlatformAdmin must resolve the dedicated session and an active standing or unexpired emergency grant on every request. It is never an Organization-role override.
The legacy PlatformRoleAssignment/TEACHER schema is not a compatible shortcut and must be migrated or replaced before the platform panel ships.
Bootstrap and recovery remain direct database/control-plane operations, but only through versioned, asserted, auditable procedures rather than arbitrary SQL.
Exact numeric invitation/session/step-up/emergency durations, audit retention and export policy, recovery-key custody rotation, and future multi-party approval remain follow-on operational decisions. They may not weaken the identity separation, last-administrator protection, fail-closed audit, or two-factor recovery invariants fixed here.

7.0 KiB Raw Blame History