ppoppo-identity 0.31.0

//! **NOT a stable public API.** Engine-tier identity vocabulary — published
//! to crates.io only because the SDK closure requires it on the registry;
//! 3rd parties never name this crate. They meet these types through an SDK
//! product facade or a wire contract, never here.
//!
//! # Principal identity — the `scaccounts.ppnums` vocabularies
//!
//! The identifier pair, three value-sets, and one predicate over them — all
//! owned by the `scaccounts.ppnums` table (or, for [`Scope`], by the OAuth
//! catalog PAS mints from it) and all read by *more than one* organ, so none
//! of them can live in either organ. The rows first:
//!
//! | Type | Column / fact | Binding |
//! |---|---|---|
//! | [`Ppnum`] | `ppnum` | `ck_ppnums_format` — named on [`Ppnum::CONSTRAINT`] |
//! | [`PpnumId`] | `id` | the 26-char ULID PK / FK / `sub` |
//! | [`EntityType`] | `entity_type` | `ck_ppnums_entity_type_enum` |
//! | [`LifecycleState`] | `lifecycle_state` (+ 2 audit columns) | `ck_ppnums_lifecycle_state_enum`, `ck_ppnum_lifecycle_events_{from,to}_state_enum` |
//! | [`Scope`] | the `scopes` claim / `scopes_supported` | [`SCOPE_TABLE`] + const gates in each organ |
//!
//! They are here for one reason, applied five times: **a value consumed
//! across the organ boundary collapses into one vocabulary** rather than
//! being mirrored and then bound. `EntityType` arrived by `RFC_202607252223`,
//! `LifecycleState` by `RFC_202607251658` P1 — and the second move is also
//! what finally makes the *cross-fact* between them stateable exactly once
//! ([`LifecycleState::can_transition_for_entity`], the
//! `ck_ppnums_expired_only_mask` rule). `Ppnum`, `PpnumId` and `Scope`
//! followed on 2026-08-29 (the ADR named in this crate's CHANGELOG), each
//! for the same reason the first two moved: the rule already had several
//! homes and at least two of them disagreed.
//!
//! ## `Ppnum` / `PpnumId` — the identifier pair
//!
//! **The number, and the id that names its row.** Consumers store the two
//! *paired*; both are immutable for a human. Before this crate the format rule
//! behind [`Ppnum`] was restated six times across the SDKs, PCS and PAS — and
//! PCS's two copies said `== 11` while the column, PAS and the SDKs said
//! `≥ 11`, so every 15-digit dependent-agent ppnum PAS minted was un-addable
//! as a PCS contact. The rule is stated once here ([`Ppnum::MIN_LEN`], the
//! `ck_ppnums_format` regex), the two renderings that every organ needs
//! (wire digits, hyphen-grouped display) are stated once, and the ladder PAS
//! mints on (`11 + 4·depth`) is deliberately **not** here — it is issuance
//! policy PCS never reads.
//!
//! [`PpnumId`] was the same ULID under three names (`PpnumAccountId` in PAS,
//! `PpnumId` in PCS and the SDK). A value that crosses the organ boundary
//! under one name in the database has one name in Rust.
//!
//! ## `Scope` — the one OAuth scope vocabulary
//!
//! **Every scope PAS mints**, with the two attributes both organs decide on:
//! its [`ScopeTier`] (reach) and its [`ScopeEnforcer`] (which organ's
//! perimeter matches it). Before this crate the catalog was a PAS string list,
//! a PAS `plims:*` const module, a 15-member PCS enum with three parallel
//! lists, and bare string atoms in the SDK's tiers — held together by three
//! dev-dependency tests that compiled the other organ to compare strings. Now
//! a scope the SDK requests *is* a scope PAS mints, by type, and the K8
//! inclusions (`DIRECTION_COUPLING_PASPCS` §6 I10) are const gates in
//! `chat-core`: every `Pcs`-enforced scope backs a gate, every gate is keyed
//! on a `Pcs`-enforced scope, and a mislabel fails to compile.
//!
//! What stays in PAS is what only PAS reads: `registerable` (the `/oauth/apps`
//! form's allow-list) and the consent-screen glyph, in a PAS policy table
//! keyed by [`Scope`] and const-gated to [`Scope::ALL`]'s order.
//!
//! ## `EntityType` — the one entity vocabulary
//!
//! **What kind of entity a ppnum is.** One type, one name, one value-set,
//! shared by the token engine and both services. Before this crate the same
//! fact was reified four times — `accounts_core::EntityType` (6 variants),
//! `chat_core::port::EntityClass` (5, a hand-maintained mirror),
//! `ppoppo_token::EntityType` (3), and the `ppnum.EntityType` proto enum —
//! and two of those disagreed about whether `delegated` was a member.
//!
//! ### The axis this crate is NOT
//!
//! `EntityType` answers *what the principal is*. It does **not** answer *who
//! is currently acting for it* — that is the RFC 8693 §4.1 `act` claim, and
//! keeping the two apart is the entire point.
//!
//! **There is deliberately no `Delegated` variant.** A human identity driven
//! by an agent is `Human` **plus** `act` — two facts, two fields. Compressing
//! them into one string field is the mistake
//! `STS_AUTH_PPOPPO` §4.2.1 already rejected for the retired `role`
//! claim; that rule was never applied to its two siblings
//! (`EntityType::Delegated`, `SenderBadge::Delegated`), and this crate is
//! where it finally is. Recovering "is this delegated?" from a *single* value
//! is impossible by construction here.
//!
//! ### Why an engine-tier crate with no IO or transport dependency
//!
//! The type must be reachable from three places at once, and the crate
//! lattice leaves exactly one option:
//!
//! - `ppoppo-token` needs it for the `entity_type` claim — and `engine →
//!   shared` is **forbidden** (`xtask::policy::rules::taxonomy`), so a
//!   `crates/shared/*` home is illegal. Engine tier it is.
//! - `chat-core` needs it, and bans IO/transport crates (Constitution
//!   Principle I). `std` plus the ULID codec both cores already carry is the
//!   only shape it can accept — the same stance that already lets it depend
//!   on `ppoppo-clock`.
//!
//! Sharing one type also **removes a value-set mirror**: `EntityClass`
//! existed only to restate `scaccounts.ppnums.entity_type` inside PCS, and
//! `DIRECTION_COUPLING_PASPCS` §4 **K5** records that mirror as a gap
//! (PCS's drift test scopes `nspname='scchat'` and structurally cannot see
//! `scaccounts`). With one type there is nothing left to drift.
//!
//! ### Table, not scattered predicates
//!
//! [`TABLE`] is the SSOT of per-variant *attributes*. Each fact previously
//! lived somewhere else — the wire string in an `as_str` match,
//! credential-eligibility in a PAS use-case, the AI-disclosure obligation in
//! a doc comment. The enum is retained because exhaustive `match` is
//! load-bearing: a sixth variant must fail to compile rather than default
//! into a claim.
//!
//! Attributes that belong to **one** owner stay with that owner and are
//! deliberately absent here — notably `number_class` (people/infra/
//! ephemeral), a `GENERATED` column in `scaccounts` that PCS never reads.
//! A shared table is not a dumping ground.
//!
//! ## `LifecycleState` — the one lifecycle vocabulary
//!
//! **What state a ppnum is in**, plus the legal transitions between states.
//! Arrived by `RFC_202607251658` P1 for two reasons, and it carries the
//! *transition lattice* as well as the value-set because of the second:
//!
//! - **PCS reads the value-set.** `chat-core` classifies
//!   `scaccounts.ppnums.lifecycle_state` on its liveness path, and did so
//!   through a hand-maintained 8-variant copy. Same unguardable shape as
//!   `EntityClass` above — PCS's drift test is schema-scoped to `scchat` and
//!   structurally cannot see a `scaccounts` `CHECK`
//!   (`DIRECTION_COUPLING_PASPCS` §4 **K5** / §6 **I7**).
//! - **[`can_transition_for_entity`](LifecycleState::can_transition_for_entity)
//!   is a cross-fact.** It layers `ck_ppnums_expired_only_mask` — only
//!   [`EntityType::Mask`] may reach [`LifecycleState::Expired`] — which is a
//!   statement about *both* value-sets. Rust's orphan rule means whichever crate
//!   does not own the type cannot say it as an inherent method, so leaving the
//!   state machine in `accounts-core` would have required an extension trait:
//!   the invariant expressible in two places again.
//!
//! This is not the dumping ground the paragraph above rules out. PAS keeps what
//! only PAS reads — the column, the business triggers that drive transitions,
//! and the audit trail. What moved is the fact neither organ could own alone.
//!
//! ## `effective_admin` — the one admin predicate
//!
//! **Not a value-set: a decision.** [`effective_admin`] answers "is this
//! principal an effective admin" from three facts — the `is_admin` grant, the
//! [`LifecycleState`] it is (or is not) in effect under, and how many active
//! passkeys the principal holds. It arrived by `RFC_202608241353` T-01, and it
//! arrived because the two organs had **stopped agreeing**:
//!
//! | Premise | PAS `/admin` | PCS admin RPCs (before) |
//! |---|---|---|
//! | `is_admin = TRUE` | checked | checked |
//! | `lifecycle_state = 'active'` | checked | **not checked** |
//! | at least one active passkey | checked, bounded | **not checked** |
//!
//! A deactivated account whose grant was never revoked was refused by one organ
//! and admitted by the other. Roles persisting across lifecycle state is
//! deliberate (`GUIDE_ADMIN_PAS` §4.8), which is exactly what made the missing
//! term reachable rather than theoretical.
//!
//! The collapse is the same one the two value-sets above took, applied to a
//! predicate: **one declaration, two callers.** Each organ's adapter gathers the
//! premises from its own tier — PAS from `accounts-database`, PCS from its
//! cross-schema read into `scaccounts` — and both hand them to the same
//! function. Duplicating the conjunction in `chat-core` was the fast path and is
//! rejected in the RFC's §8: a second declaration of a security predicate is the
//! shape **K5** exists to forbid.
//!
//! Two things travel with the predicate rather than with its callers, because a
//! caller-local copy of either would let the organs diverge again while both
//! "used the shared function": the Layer-2 budget
//! ([`ADMIN_PASSKEY_CHECK_TIMEOUT`]) and the *unknown* premise
//! ([`ActivePasskeys::Unknown`]) that a blown budget produces. Protocol mapping
//! — which status code, which page, which gRPC metadata — stays at each
//! caller's edge, exactly as with everything else here.

#![deny(rust_2018_idioms)]
#![warn(missing_debug_implementations)]

use core::fmt;

mod admin;
mod lifecycle;
mod ppnum;
mod scope;

pub use admin::{
    ACCESS_RECORD_RETENTION_DAYS, ACCESS_RECORD_RETENTION_FLOOR_DAYS, ADMIN_PASSKEY_CHECK_TIMEOUT,
    ADMIN_PREMISE_COLUMNS, ActivePasskeys, AdminFacts, AdminLayer1, AdminPremiseColumn,
    AdminVerdict, effective_admin,
};
pub use lifecycle::LifecycleState;
pub use ppnum::{Ppnum, PpnumError, PpnumId};
pub use scope::{SCOPE_TABLE, Scope, ScopeEnforcer, ScopeFacts, ScopeTier};

/// What kind of entity a ppnum is.
///
/// Members are exactly the storable values of
/// `scaccounts.ppnums.entity_type` (`ck_ppnums_entity_type_enum`) — bound to
/// that constraint by the enrollment directly below, so the constraint name
/// lives *on the fact*.
///
/// There is **no `non_stored` list**, and that is the point: every member of
/// this vocabulary is a real, storable entity kind. The render-only
/// `Delegated` that the retired PAS enum had to declare as an exception is not
/// an exception here — it is simply not an entity type. See the module docs.
///
/// The `serde` impls are **feature-gated and off by default** (PCS caches
/// `PpnumAccount` as JSON in KVRocks and needs them; the only other consumer is
/// PAS's [`AdminLayer1`] cache value, which carries a [`LifecycleState`]). The
/// wire form is `rename_all = "snake_case"` — byte-identical to
/// [`as_str`](Self::as_str), and not by coincidence: `snake_case` of each
/// variant *is* the canonical string, so the derive cannot drift from
/// [`TABLE`]. If a variant ever needs a form `snake_case` does not produce,
/// delete the derive and write a manual impl that delegates to `as_str` — a
/// second spelling of the wire strings is precisely the mirror this crate
/// exists to remove.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[cfg_attr(feature = "serde", serde(rename_all = "snake_case"))]
pub enum EntityType {
    /// Natural person. Also the class of a token whose `sub` is a human
    /// being driven by an agent (ppnum lending) — the agent is `act`, not a
    /// different entity type.
    Human,
    /// Business or organization.
    Enterprise,
    /// LLM-backed agent holding its own ppnum.
    AiAgent,
    /// Developer-programmable number (template / auto-reply). Infra class.
    Programmable,
    /// Ephemeral privacy-mediation proxy number with a TTL. Industry
    /// analogue: Twilio Masking Numbers / 안심번호.
    Mask,
}

// SSOT binding: the vocabulary must equal `ck_ppnums_entity_type_enum`.
//
// The enrollment lives here, next to the enum, rather than in PAS — which is
// what `RFC_202607252223` T-03's tier move bought. While it sat in
// `accounts-core` the DB binding could not follow the type up the lattice, so
// a second PAS-local enum had to stay alive purely to hold it, and every
// textual analysis of this vocabulary was ambiguous between the two.
//
// PAS still owns the *column* (and `number_class`, which is a `GENERATED`
// column PCS never reads); this crate owns the *value-set*. Verification is
// unchanged — `accounts-api/tests/schema_check_drift.rs` reads the
// materialized `CHECK` via `pg_get_constraintdef` and asserts set-equality.
ppoppo_schema_constrained::impl_schema_constrained!(EntityType via as_str {
    all: [Human, Enterprise, AiAgent, Programmable, Mask],
    constraints: ["ck_ppnums_entity_type_enum"],
});

/// One row of [`TABLE`] — every attribute of one entity type.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct EntityFacts {
    /// The variant this row describes. Present so the row is self-describing
    /// and the table↔enum wiring is checkable at compile time.
    pub entity: EntityType,
    /// Canonical wire/DB string. The value in `ppnums.entity_type`, in the
    /// `entity_type` JWT claim, and on every wire that names an entity type.
    pub wire: &'static str,
    /// May this entity hold a minted credential (OAuth `client_credentials`)?
    ///
    /// **This is a policy, not an identity fact** — which is why it lives in
    /// a table column rather than in the type. `false` means *no
    /// credential-issuing flow exists today*, not *never will*: the External
    /// Developer / enterprise lane is designed and unbuilt
    /// (`STS_AUTH_PPOPPO` §6.4).
    ///
    /// Load-bearing in two places that must agree — the mint refuses a
    /// principal with `false`, and the engine's M40 gate refuses such a
    /// value on the wire. One declaration, two enforcement points, which is
    /// what lets the K8 reachability guard assert an *equality* rather than
    /// an inclusion.
    pub can_hold_credential: bool,
    /// Does a message from this entity carry a mandatory AI-disclosure
    /// obligation? (EU AI Act Art.50 / KR AI기본법.)
    ///
    /// Note this is keyed on the *entity*, so it does **not** cover a human
    /// ppnum driven by an agent — that case is `Human` + `act`, and the
    /// obligation there follows from the delegation, not from this column.
    pub requires_ai_disclosure: bool,
}

/// **The lookup table — SSOT of every per-variant attribute.**
///
/// Ordered identically to [`EntityType::ALL`]; the const gate below proves
/// it, so the two can never be read out of step.
pub const TABLE: [EntityFacts; 5] = [
    EntityFacts {
        entity: EntityType::Human,
        wire: "human",
        can_hold_credential: true,
        requires_ai_disclosure: false,
    },
    EntityFacts {
        entity: EntityType::Enterprise,
        wire: "enterprise",
        // No credential-issuing flow. AUTH §6.4 records the lane as
        // designed-but-unbuilt; opening it flips this cell, and the K8
        // guard fails until the mint path moves with it.
        can_hold_credential: false,
        requires_ai_disclosure: false,
    },
    EntityFacts {
        entity: EntityType::AiAgent,
        wire: "ai_agent",
        can_hold_credential: true,
        requires_ai_disclosure: true,
    },
    EntityFacts {
        entity: EntityType::Programmable,
        wire: "programmable",
        can_hold_credential: true,
        // Infra class — a template/auto-reply number is not an AI system.
        requires_ai_disclosure: false,
    },
    EntityFacts {
        entity: EntityType::Mask,
        wire: "mask",
        // A mask is a presentation alias for someone else; it does not
        // authenticate as itself.
        can_hold_credential: false,
        requires_ai_disclosure: false,
    },
];

impl EntityType {
    /// Every variant. Ordered as [`TABLE`].
    pub const ALL: [EntityType; 5] = [
        Self::Human,
        Self::Enterprise,
        Self::AiAgent,
        Self::Programmable,
        Self::Mask,
    ];

    /// Stable position in [`ALL`](Self::ALL) / [`TABLE`].
    ///
    /// The exhaustive `match` is the compile-time gate: a sixth variant
    /// fails to build here, so it cannot reach a claim by defaulting.
    #[must_use]
    pub const fn index(self) -> usize {
        match self {
            Self::Human => 0,
            Self::Enterprise => 1,
            Self::AiAgent => 2,
            Self::Programmable => 3,
            Self::Mask => 4,
        }
    }

    /// This variant's row. Every attribute accessor below reads through it,
    /// so [`TABLE`] is the only place an attribute is stated.
    #[must_use]
    pub const fn facts(self) -> &'static EntityFacts {
        &TABLE[self.index()]
    }

    /// Canonical wire/DB string.
    #[must_use]
    pub const fn as_str(self) -> &'static str {
        self.facts().wire
    }

    /// May this entity hold a minted credential? See
    /// [`EntityFacts::can_hold_credential`].
    #[must_use]
    pub const fn can_hold_credential(self) -> bool {
        self.facts().can_hold_credential
    }

    /// Does this entity carry an AI-disclosure obligation? See
    /// [`EntityFacts::requires_ai_disclosure`].
    #[must_use]
    pub const fn requires_ai_disclosure(self) -> bool {
        self.facts().requires_ai_disclosure
    }

    /// Parse a canonical wire string. Exact inverse of
    /// [`as_str`](Self::as_str).
    ///
    /// `None` for anything outside the vocabulary — notably `"delegated"`,
    /// which is a *session mode* and never an entity type. Callers on a
    /// verify path MUST treat `None` as a forgery signal, not as an
    /// unknown-but-tolerable value.
    #[must_use]
    pub fn parse(s: &str) -> Option<Self> {
        Self::ALL.into_iter().find(|e| e.as_str() == s)
    }
}

impl fmt::Display for EntityType {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str(self.as_str())
    }
}

// ── Compile-time gates ──────────────────────────────────────────────────
//
// `TABLE` and `ALL` are two orderings of one fact; nothing at runtime would
// notice them diverging, so it is settled at build time.
const _: () = {
    assert!(TABLE.len() == EntityType::ALL.len());

    // Row i describes variant i — a mis-ordered table cannot compile.
    let mut i = 0;
    while i < EntityType::ALL.len() {
        assert!(TABLE[i].entity.index() == EntityType::ALL[i].index());
        i += 1;
    }

    // `facts()` resolves each variant to its OWN row (a copy-paste slip in
    // the `index()` match would otherwise hand back a neighbour's
    // attributes — including `can_hold_credential`, a security gate).
    let mut i = 0;
    while i < EntityType::ALL.len() {
        assert!(EntityType::ALL[i].facts().entity.index() == EntityType::ALL[i].index());
        i += 1;
    }
};

#[cfg(test)]
// Outer, not the usual inner `#![allow(..)]`: ARCH-BOUNDARY pins the exact
// inner-attribute block of a published-tier `lib.rs` and scans every line,
// so an indented inner attribute inside this module trips it too.
#[allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
mod tests {
    use super::*;

    #[test]
    fn parse_is_the_inverse_of_as_str() {
        for e in EntityType::ALL {
            assert_eq!(EntityType::parse(e.as_str()), Some(e));
        }
    }

    /// The value this crate exists to make unspellable. `"delegated"` is a
    /// session mode carried by `act`; it was never an entity type and must
    /// not become one again.
    #[test]
    fn delegated_is_not_an_entity_type() {
        assert_eq!(EntityType::parse("delegated"), None);
    }

    #[test]
    fn unknown_strings_do_not_parse() {
        for s in ["", "HUMAN", "human ", "user", "bot", "service", "virtual"] {
            assert_eq!(EntityType::parse(s), None, "{s:?} must not parse");
        }
    }

    /// Pins the credential-eligible set. This is the M40 admitted set and a
    /// security boundary — widening it is a deliberate act, so it should
    /// require editing an assertion that says so.
    #[test]
    fn credential_eligible_set_is_pinned() {
        let eligible: Vec<_> = EntityType::ALL
            .into_iter()
            .filter(|e| e.can_hold_credential())
            .collect();
        assert_eq!(
            eligible,
            vec![
                EntityType::Human,
                EntityType::AiAgent,
                EntityType::Programmable
            ],
            "the credential-eligible set changed — this is the M40 admitted \
             set (a forgery gate). Widening it must move the mint path in the \
             same change, or the K8 reachability guard will fail."
        );
    }

    /// **The `serde` derive must encode exactly `as_str`.**
    ///
    /// Load-bearing beyond tidiness: PCS caches `PpnumAccount` as JSON in
    /// KVRocks and `get_typed` propagates a deserialize failure rather than
    /// treating it as a miss, so an encoding change would turn every cached
    /// account into a hard error until the TTL expired. The retired
    /// `chat_core::port::EntityClass` encoded via `rename_all = "snake_case"`
    /// over the same five variants; this pins that the replacement is
    /// byte-identical, so live cache entries written before the collapse still
    /// read back.
    ///
    /// It also pins the claim in the type's doc comment that `snake_case`
    /// *is* the canonical string — asserted over `ALL`, so a variant whose
    /// `snake_case` diverges from its `TABLE` row fails here instead of
    /// silently minting a second wire spelling.
    #[cfg(feature = "serde")]
    #[test]
    fn serde_encoding_is_exactly_as_str() {
        for e in EntityType::ALL {
            let json = serde_json::to_string(&e).expect("serialize");
            assert_eq!(
                json,
                format!("\"{}\"", e.as_str()),
                "the serde derive drifted from `as_str` for {e:?} — this breaks \
                 every JSON-cached PpnumAccount and mints a second spelling of \
                 the wire strings"
            );
            assert_eq!(
                serde_json::from_str::<EntityType>(&json).expect("deserialize"),
                e,
            );
        }
    }

    /// AI disclosure is an entity property; delegation is not covered here
    /// (a human driven by an agent is `Human` + `act`).
    #[test]
    fn ai_disclosure_is_agent_only() {
        for e in EntityType::ALL {
            assert_eq!(e.requires_ai_disclosure(), e == EntityType::AiAgent);
        }
    }
}