forked from EduCraft/curriculum-project-hub
222 lines
10 KiB
Lean4
222 lines
10 KiB
Lean4
import Spec.Prelude
|
||
|
||
/-!
|
||
# PlatformAdministration —— 平台管理员身份、会话与审计边界(ADR-0023)
|
||
|
||
平台控制面可以创建 org、写入连接凭据并制动全平台工作负载,因此不得借用客户
|
||
`User`、`OrganizationMembership` 或 project role。ADR-0023 决定独立平台飞书 issuer、
|
||
单一平级管理员角色、绑定身份的 invitation、可撤销服务端 session、mutation 与平台审计
|
||
同成同败、最后管理员保护,以及无常驻账号的双因子离线恢复。
|
||
|
||
本模块只钉死这些会导致安全边界分歧的语义。cookie 属性、token hash、具体 TTL、审计
|
||
字段表示/保留期、recovery key 介质和 CLI/SQL 机制仍为 `OPEN`,由对应实现决策承载。
|
||
-/
|
||
|
||
namespace Spec.System
|
||
|
||
variable (I : Identifiers)
|
||
|
||
/-- 平台管理员的已验证外部身份(`PINNED`, ADR-0023):issuer 必须是专用
|
||
Platform-owned Feishu Application;该身份与客户 `User`/org membership/project grant
|
||
是不同的授权根,即使现实中是同一个人也不自动传播权限。 -/
|
||
structure PlatformIdentity where
|
||
/-- 平台身份自身标识(`OPEN` 表示,ADR-0023)。 -/
|
||
id : I.PlatformIdentityId
|
||
/-- 验证该身份的平台自有飞书应用(`PINNED`, ADR-0023)。 -/
|
||
application : I.PlatformFeishuApplicationId
|
||
/-- 在该平台应用作用域内验证的外部飞书用户(`PINNED` 作用域,表示 `OPEN`)。 -/
|
||
externalUser : I.PlatformExternalUserId
|
||
|
||
/-- 平台身份来自当前唯一受信 platform-owned app iff identity 的 issuer 与配置的
|
||
平台应用相同(`PINNED`, ADR-0023);不能把客户 org app 的 identity 当平台身份。 -/
|
||
def PlatformIdentity.FromPlatformApplication
|
||
(identity : PlatformIdentity I)
|
||
(platformApplication : I.PlatformFeishuApplicationId) : Prop :=
|
||
identity.application = platformApplication
|
||
|
||
/-- 初始平台控制面的 standing role(`PINNED` 封闭, ADR-0023):只有一个平级
|
||
administrator;不存在 Platform Owner/Super Admin/Teacher 层级。 -/
|
||
inductive PlatformRole where
|
||
| administrator
|
||
|
||
/-- Standing Platform Administrator grant 的生命周期(`PINNED`, ADR-0023)。 -/
|
||
inductive StandingPlatformAdminGrantState where
|
||
| active
|
||
| revoked
|
||
|
||
/-- 一个普通、长期存在的 Platform Administrator grant(`PINNED`, ADR-0023)。 -/
|
||
structure StandingPlatformAdminGrant where
|
||
/-- 被授予平台管理员权力的独立平台身份(`PINNED`, ADR-0023)。 -/
|
||
identity : I.PlatformIdentityId
|
||
/-- standing role;当前封闭集合只有 administrator(`PINNED`, ADR-0023)。 -/
|
||
role : PlatformRole
|
||
/-- grant 当前是否仍有效(`PINNED`, ADR-0023)。 -/
|
||
state : StandingPlatformAdminGrantState
|
||
|
||
/-- Standing grant 仅在 active 状态有效(`PINNED`, ADR-0023)。 -/
|
||
def StandingPlatformAdminGrant.Active
|
||
(grant : StandingPlatformAdminGrant I) : Prop :=
|
||
grant.state = .active
|
||
|
||
/-- 首位平台管理员 bootstrap 的前置条件(`PINNED`, ADR-0023):只有 standing admin
|
||
集合为空时才允许;bootstrap 身份验证、审计与事务机制见 ADR,具体脚本表示 `OPEN`。 -/
|
||
def CanBootstrapPlatformAdmin
|
||
(activeStandingAdmins : List I.PlatformIdentityId) : Prop :=
|
||
activeStandingAdmins = []
|
||
|
||
/-- 撤销 standing Platform Administrator 的最后管理员保护(`PINNED`, ADR-0023):
|
||
target 必须当前有效,且列表中必须另有一个不同的有效管理员。Emergency grant 不计入
|
||
standing admin 集合,不能用来绕过最后管理员保护。 -/
|
||
def CanRevokePlatformAdmin
|
||
(activeStandingAdmins : List I.PlatformIdentityId)
|
||
(target : I.PlatformIdentityId) : Prop :=
|
||
target ∈ activeStandingAdmins ∧
|
||
∃ other, other ∈ activeStandingAdmins ∧ other ≠ target
|
||
|
||
/-- Platform Administrator invitation 的生命周期(`PINNED`, ADR-0023):accepted/
|
||
expired/revoked 都是终态,所以邀请只能成功领取一次。 -/
|
||
inductive PlatformAdminInvitationState where
|
||
| pending
|
||
| accepted
|
||
| expired
|
||
| revoked
|
||
|
||
/-- 一个短期、单次且绑定具体平台飞书账号的管理员邀请(`PINNED`, ADR-0023)。 -/
|
||
structure PlatformAdminInvitation where
|
||
/-- invitation 标识(`OPEN` 表示,ADR-0023)。 -/
|
||
id : I.PlatformInvitationId
|
||
/-- 预期账号必须来自这个平台自有飞书应用(`PINNED`, ADR-0023)。 -/
|
||
application : I.PlatformFeishuApplicationId
|
||
/-- 只有这个预期飞书账号可领取;链接本身不是 bearer admin 权力(`PINNED`)。 -/
|
||
expectedExternalUser : I.PlatformExternalUserId
|
||
/-- 邀请过期的逻辑时刻(`PINNED` 有限寿命,数值单位/上限 `OPEN`)。 -/
|
||
expiresAt : Nat
|
||
/-- 邀请当前状态(`PINNED`, ADR-0023)。 -/
|
||
state : PlatformAdminInvitationState
|
||
|
||
/-- 邀请可领取 iff 尚 pending、未过期且已验证 identity 与邀请绑定的 app+用户一致
|
||
(`PINNED`, ADR-0023)。 -/
|
||
def PlatformAdminInvitation.CanAccept
|
||
(invitation : PlatformAdminInvitation I)
|
||
(identity : PlatformIdentity I)
|
||
(now : Nat) : Prop :=
|
||
invitation.state = .pending ∧
|
||
now < invitation.expiresAt ∧
|
||
identity.application = invitation.application ∧
|
||
identity.externalUser = invitation.expectedExternalUser
|
||
|
||
/-- 邀请状态转换(`PINNED`, ADR-0023):pending 只能结束为 accepted/expired/revoked;
|
||
任何终态都不能回到 pending 或再次 accepted。 -/
|
||
def PlatformAdminInvitation.ValidTransition :
|
||
PlatformAdminInvitationState → PlatformAdminInvitationState → Prop
|
||
| .pending, .accepted | .pending, .expired | .pending, .revoked => True
|
||
| _, _ => False
|
||
|
||
/-- 服务端 Platform Session 的生命周期(`PINNED`, ADR-0023)。 -/
|
||
inductive PlatformSessionState where
|
||
| active
|
||
| revoked
|
||
| expired
|
||
|
||
/-- 独立平台会话(`PINNED`, ADR-0023):只绑定 Platform Identity,不携带 org/project
|
||
权力;opaque cookie/token、hash 与 TTL 表示为 `OPEN`。 -/
|
||
structure PlatformSession where
|
||
/-- 平台会话标识(`OPEN` 表示,ADR-0023)。 -/
|
||
id : I.PlatformSessionId
|
||
/-- 会话认证的独立平台身份(`PINNED`, ADR-0023)。 -/
|
||
identity : I.PlatformIdentityId
|
||
/-- 服务端可立即撤销/过期的状态(`PINNED`, ADR-0023)。 -/
|
||
state : PlatformSessionState
|
||
|
||
/-- 双因子离线恢复授权(`PINNED`, ADR-0023):受控主机权限、主机外 recovery key 与
|
||
已声明 incident 三项都存在才是受支持的 recovery;具体因子实现与保管介质 `OPEN`。 -/
|
||
structure PlatformRecoveryAuthorization where
|
||
/-- 已验证受控生产主机权限(`PINNED`, ADR-0023)。 -/
|
||
hostControl : Bool
|
||
/-- 已验证独立的主机外 recovery key(`PINNED`, ADR-0023)。 -/
|
||
offlineRecoveryKey : Bool
|
||
/-- 操作绑定了 incident id 与原因(`PINNED`, ADR-0023)。 -/
|
||
incidentDeclared : Bool
|
||
|
||
/-- Recovery authorization 只有三项因子均为真时有效(`PINNED`, ADR-0023)。 -/
|
||
def PlatformRecoveryAuthorization.Valid
|
||
(authorization : PlatformRecoveryAuthorization) : Prop :=
|
||
authorization.hostControl = true ∧
|
||
authorization.offlineRecoveryKey = true ∧
|
||
authorization.incidentDeclared = true
|
||
|
||
/-- 只有有效双因子 recovery authorization 才能签发 Emergency Platform Grant
|
||
(`PINNED`, ADR-0023);不存在普通 web session 直接创建 break-glass 权力的路径。 -/
|
||
def CanIssueEmergencyPlatformGrant
|
||
(authorization : PlatformRecoveryAuthorization) : Prop :=
|
||
authorization.Valid
|
||
|
||
/-- 无常驻 break-glass 账号的短期紧急授权(`PINNED`, ADR-0023)。它不属于 standing
|
||
role,必须绑定已声明 incident,自动过期且可在恢复完成时提前关闭。 -/
|
||
structure EmergencyPlatformGrant where
|
||
/-- 获得临时平台权力的已验证 Platform Identity(`PINNED`, ADR-0023)。 -/
|
||
identity : I.PlatformIdentityId
|
||
/-- 触发该授权的 incident(`PINNED`, ADR-0023)。 -/
|
||
incident : I.PlatformIncidentId
|
||
/-- 自动过期的逻辑时刻(`PINNED` 有限寿命,数值单位/上限 `OPEN`)。 -/
|
||
expiresAt : Nat
|
||
/-- 恢复完成后是否已显式关闭(`PINNED`, ADR-0023)。 -/
|
||
closed : Bool
|
||
|
||
/-- Emergency grant 仅在未关闭且未到期时有效(`PINNED`, ADR-0023)。 -/
|
||
def EmergencyPlatformGrant.Active
|
||
(grant : EmergencyPlatformGrant I) (now : Nat) : Prop :=
|
||
grant.closed = false ∧ now < grant.expiresAt
|
||
|
||
/-- 每次平台请求的授权条件(`PINNED`, ADR-0023):session 必须仍为 active,且请求时
|
||
重新解析到 active standing grant 或同 identity 的未关闭、未过期 emergency grant。
|
||
cookie 内曾经出现过 role claim 不能代替这次解析。 -/
|
||
def PlatformSession.Authorized
|
||
(session : PlatformSession I)
|
||
(standingGrants : List (StandingPlatformAdminGrant I))
|
||
(emergencyGrants : List (EmergencyPlatformGrant I))
|
||
(now : Nat) : Prop :=
|
||
session.state = .active ∧
|
||
((∃ grant, grant ∈ standingGrants ∧
|
||
grant.identity = session.identity ∧
|
||
StandingPlatformAdminGrant.Active I grant) ∨
|
||
∃ grant, grant ∈ emergencyGrants ∧
|
||
grant.identity = session.identity ∧
|
||
EmergencyPlatformGrant.Active I grant now)
|
||
|
||
/-- 必须做近期 OAuth step-up 的平台敏感操作集合(`PINNED`, ADR-0023;未来新增敏感
|
||
操作时可扩):管理员生命周期、飞书连接、platform-managed provider 凭据、org 生命周期、
|
||
workload brake 与 emergency grant 都不能只凭旧 session。 -/
|
||
inductive PlatformSensitiveAction where
|
||
| administratorLifecycle
|
||
| feishuConnection
|
||
| platformManagedProviderCredential
|
||
| organizationLifecycle
|
||
| workloadBrake
|
||
| emergencyGrant
|
||
|
||
/-- 敏感操作授权必须提供"近期重新认证"事实(`PINNED`, ADR-0023);具体时间窗 `OPEN`,
|
||
由 browser/session 决策给出受检上限。 -/
|
||
def PlatformSensitiveAction.Authorized
|
||
(_action : PlatformSensitiveAction)
|
||
(recentAuthentication : Prop) : Prop :=
|
||
recentAuthentication
|
||
|
||
/-- 一个成功平台 mutation 与其独立 Platform Audit Entry 的原子提交事实(`PINNED`,
|
||
ADR-0023):没有 audit entry 就不存在合法成功 commit;具体数据库事务机制 `OPEN`。 -/
|
||
structure PlatformMutationCommit where
|
||
/-- 成功的平台 mutation(`PINNED`, ADR-0023)。 -/
|
||
mutation : I.PlatformMutationId
|
||
/-- 与 mutation 同成同败的 append-only 平台审计条目(`PINNED`, ADR-0023)。 -/
|
||
auditEntry : I.PlatformAuditEntryId
|
||
|
||
/-- Organization 管理员可读的平台审计脱敏投影(`PINNED`, ADR-0023):只关联影响该
|
||
Organization 的 entry;完整平台审计和其他 org entry 不经此投影暴露。 -/
|
||
structure OrganizationPlatformAuditProjection where
|
||
/-- 被投影的平台审计条目(`PINNED`, ADR-0023)。 -/
|
||
auditEntry : I.PlatformAuditEntryId
|
||
/-- 唯一可见该投影的受影响 Organization(`PINNED`, ADR-0023)。 -/
|
||
organization : I.OrganizationId
|
||
|
||
end Spec.System
|