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