forked from EduCraft/curriculum-project-hub
hongjr03
3f9b60f692
The spec/ Lean semantic master had no conformance gate, no codegen, and no CI tie to implementations — alignment was carried entirely by human review, the same mechanism that carries the ADRs. In practice the ADRs plus greppable code comments were already the load-bearing artifacts, so spec/ was the most expensive kind of stale documentation. - delete spec/ and the spec-check CI workflow - README: constitution rewritten around ADRs as decision truth - AGENTS.md/CLAUDE.md: discipline re-anchored (new decisions -> new ADR, never rewrite ADR history; supersede instead) - code comments: re-anchor 'Mirrors Spec.X' invariants to ADR numbers (cph-diag, cph-check, cph-model, hub runner/capacity/org, prisma) - leave ADR bodies and .scratch audit snapshots untouched (history); fix live references in open readiness tickets
53 lines
2.9 KiB
Markdown
53 lines
2.9 KiB
Markdown
# Decide the platform-administrator identity and audit boundary
|
|
|
|
Type: grilling
|
|
Status: resolved
|
|
|
|
## Question
|
|
|
|
Which identity issuer, bootstrap and recovery procedure, invite/allowlist model,
|
|
session claims, role lifecycle, separation from Organization membership, and
|
|
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),
|
|
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).
|