Files
pages/docs/design/campus-admin-revocation.md
T
Anya Tokugawa c1175d389f Implement Knowledge City platform, organizer and DAV integration
Capture accumulated application, UI, CLI, regression tests and design documentation changes, including task project mapping and default CalDAV list naming.

Keep deployment data, backups, local credentials and build artifacts out of Git. Move the Compose enrollment token to an ignored local environment file.
2026-09-27 14:44:43 +09:00

100 lines
5.7 KiB
Markdown

# Campus administrator inheritance: revocation and provenance
Implemented: 2026-09-14. This note supersedes the former insert-only Campus
projection described in `authorization-groups.md`. Cross-instance Domain-pair
PSK synchronization is still a separate, unimplemented protocol.
## Authority and data ownership
`campus_admin_grants` is the authoritative set of independent and inherited
grants for the built-in `campus_admin` group only. Its key is
`(group_uuid, membership_uuid, source)`. An independent grant uses `local`,
`migration`, or an existing non-Campus source identifier. Derived grants use
`campus_admin_inherit:<origin group UUID>`.
`group_members` remains the public/effective membership table. The strongest
remaining role wins (`owner > manager > member`), with a direct source winning
ties. A weaker local grant is kept in provenance, not overwritten by a stronger
inherited role, and becomes effective again when that inherited role expires.
Ordinary groups and `domain_admin` retain their existing storage and behavior.
Projection roots must have an active source group, active principal, active
source Domain membership, enabled source Domain, and enabled inheritance flag.
The target must be an enabled Domain in the same Campus with an active built-in
group. Only independent grants are roots. Derived rows cannot retransmit
authority, become new roots, or keep one another alive in a cycle. Multiple
independent origins are recorded separately; removing one does not remove the
others. Changing a principal to readonly also withdraws inherited administrator
membership; changing it back to active can restore the projection but does not
revive revoked sessions.
## Transaction boundary
The following write paths reconcile within the same SQLite transaction:
- enabling/disabling Campus inheritance;
- adding, changing, or removing an independent Campus group member;
- changing a principal's state and revoking its sessions;
- updating/deleting a Domain, including moves between Campuses;
- applying a managed-Campus topology snapshot or deleting a managed Campus;
- built-in group creation/bootstrap migration.
The projection rebuilds the effective Campus group membership from authoritative
grants. Any SQL failure rolls back both the source mutation and the projection.
No asynchronous queue or stale authorization cache sits between revocation and
the next authorization decision. Direct SQL administration must explicitly run
`ProjectCampusAdminMemberships`; deleting only the materialized `group_members`
row is not a revocation API. Future LDAP/OIDC mappings and PSK importers must
write provenance and reconcile in their own transaction, not edit the cache.
Inherited-only members cannot be removed at a destination: revoke their origin
or disable its inheritance. Removing an independent owner requires another
independent owner at that source; an owner inherited from somewhere else is
not sufficient. Bootstrap migration records each migrated source binding once
in `campus_admin_migrations`, so a later explicit Campus-group removal is not
undone by a restart or the creation of another Domain.
## Domain membership and session cleanup
`campus_admin_membership_origins` records exactly which Domain memberships the
projector created. After the last derived grant disappears, a provenance-owned
membership with no other group membership or role binding is removed and that
principal's sessions in that Domain are revoked atomically.
Existing local memberships are never reactivated, relabeled as inherited, or
deleted by projection. Adding an independent group grant adopts an inherited
membership as local. An independent role binding likewise prevents cleanup and
preserves its session. No role binding or capability grant is deleted: the old
Campus projection never created `auth_role_bindings`, and revocation of a group
membership already removes access through that group's permission profiles.
Independent `domain_admin` and direct role capabilities remain unchanged.
## Upgrade behavior and limits
Older installations recorded only one source per effective group member and
did not record the origin of a Domain membership. On the first schema upgrade,
only stored non-inherited Campus group memberships seed authoritative grants;
old inherited chains are discarded and regenerated from those roots. A legacy
Domain membership with ambiguous origin is retained, while its inherited group
authority is revoked normally. Do not guess that an untagged membership belongs
to the projector and delete a potentially independent local identity record.
An old local grant previously overwritten or mislabeled by the single-source
implementation cannot be reconstructed; an administrator must explicitly grant
that local role again if needed. Newly recorded grants do not have this loss.
Reconciliation is set-based and limited to Campus administrator memberships;
it runs on administrative changes, not on ordinary reads or session lookups.
It currently recomputes all Campus administrator projections in one transaction.
Incremental Campus-scoped reconciliation and sequenced cross-instance deltas are
future scaling work; do not advertise distributed revocation guarantees before
the PSK protocol and its source-disappearance policy exist.
## Regression coverage
`groups_inheritance_test.go` covers disable/re-enable, repeated reconciliation,
source removal, suspension/quarantine/readonly, removed/disabled/moved source
Domains, multiple roots, prevention of transitive amplification, weaker local
role restoration, independent role/session preservation, legacy-chain cleanup,
restart-safe bootstrap removal, and injected mid-transaction failures for
disable/remove/suspend. Existing concurrent owner-integrity tests remain green.