ppoppo-identity 0.31.0

//! Effective admin — the authorization *predicate* both organs decide with.
//! Private module; every item is re-exported at the crate root, which is the
//! only public path. **Why it lives in this crate rather than in either
//! service: see the crate docs, §`effective_admin`.**
//!
//! This module is deliberately shaped as *premises in, verdict out*. It reads
//! nothing, awaits nothing, and cannot fail: each organ's adapter gathers the
//! three facts from its own tier and hands them over, and the rule that turns
//! them into an outcome is stated exactly once — here.

use core::time::Duration;

use crate::LifecycleState;

/// Budget for the Layer-2 active-passkey read, on **both** organs.
///
/// A shared number because a shared verdict depends on it: the whole point of
/// [`ActivePasskeys::Unknown`] is that "the read did not answer in time" is a
/// distinct premise, and two organs disagreeing about when that happens would
/// make the same account effectively-admin on one face and not the other. The
/// value caps the admin tail under a slow passkey read; expiry is not a denial
/// (see [`AdminVerdict::CheckTimeout`]).
pub const ADMIN_PASSKEY_CHECK_TIMEOUT: Duration = Duration::from_millis(500);

// ── Operator access-record retention ───────────────────────────────────

/// The statutory floor for retaining an operator's access record, in days.
///
/// An operator acting on an admin surface is a **개인정보취급자**, and
/// 개인정보의 안전성 확보조치 기준 requires their 접속기록 — including
/// 접속지 정보 — to be retained. The floor is one year, and **two** years for a
/// processor handling 고유식별정보 / 민감정보 or the personal data of 50,000+
/// 정보주체.
///
/// This is stated as a *value* rather than as prose in a guide because
/// [`ACCESS_RECORD_RETENTION_DAYS`] is checked against it at build time. A
/// floor that lives only in a document cannot fail a build.
pub const ACCESS_RECORD_RETENTION_FLOOR_DAYS: i64 = 730;

/// How long `admin_audit_logs` keeps the request forensics on a row, in days.
///
/// **A shared number because a shared obligation depends on it** — the same
/// reasoning as [`ADMIN_PASSKEY_CHECK_TIMEOUT`] above, and with a sharper edge:
/// two organs disagreeing about a *verdict* produces an inconsistent
/// authorization, while two organs disagreeing about *this* produces one organ
/// quietly out of compliance, with both still sweeping and nothing erroring.
/// Both `scaccounts.admin_audit_logs` and `scchat.admin_audit_logs` record the
/// same class of actor doing the same class of thing, so they answer to one
/// number.
///
/// Set to the **two-year** tier deliberately, which satisfies both tiers of the
/// rule at once. The alternative — one year now, two later — makes compliance
/// depend on noticing a user-count threshold being crossed, which is precisely
/// the kind of thing nobody notices.
///
/// # What expires is the origin, not the row
///
/// This is a **redaction** period, not a deletion period. After it elapses the
/// `ip_address` and `user_agent` columns are nulled and the row itself is kept.
/// The two duties pull in opposite directions and only this shape satisfies
/// both: 접속기록 sets a *minimum* retention, so deleting early breaches the very
/// rule that justifies storing an address; while 개인정보보호법 §21 requires
/// personal data to be destroyed once its purpose is achieved, so keeping it
/// forever breaches minimisation. The rest of the row — who, what, when — is
/// accountability evidence whose value does not expire, and destroying it to
/// satisfy a duty that applies to two columns would be the wrong trade.
pub const ACCESS_RECORD_RETENTION_DAYS: i64 = 730;

const _: () = {
    // The number someone tunes down during an incident ("the table is huge,
    // make it 30 days") in a one-line diff that reads as an ops change. Here
    // that diff does not compile.
    assert!(
        ACCESS_RECORD_RETENTION_DAYS >= ACCESS_RECORD_RETENTION_FLOOR_DAYS,
        "admin audit retention is below the 접속기록 statutory floor",
    );
    // A floor below one year would mean the constant above was edited rather
    // than the law changing; catch that too.
    assert!(
        ACCESS_RECORD_RETENTION_FLOOR_DAYS >= 365,
        "the 접속기록 floor is at least one year",
    );
};

/// Layer-2 premise: how many active passkeys the principal has, **or the
/// admission that the bounded read did not answer**.
///
/// The second case is a first-class member rather than an error the caller
/// handles, and that is the load-bearing decision of this module. A timeout is
/// not "zero passkeys": zero routes a user to passkey enrolment, unknown routes
/// them to *retry*. Modelling the unknown as a premise is what lets
/// [`effective_admin`] own the fail-closed rule instead of each organ owning a
/// timeout branch that must agree with the other by hand.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ActivePasskeys {
    /// The read answered. `0` is a definitive "no active passkey".
    Counted(i64),
    /// The read did not answer inside [`ADMIN_PASSKEY_CHECK_TIMEOUT`], or its
    /// substrate failed in a way the adapter could not turn into a count.
    /// **Never** collapse this into `Counted(0)`.
    Unknown,
}

/// The two premises that are cheap enough to cache — one row of
/// `scaccounts.ppnums`, read by whichever organ is deciding.
///
/// A type of its own because it is exactly what the 60-second Layer-1 cache
/// stores (`is_admin:` in `STS_SHARED_CACHE` §2.1). Before this crate that
/// cache held a `bool`, which is the same collapse [`effective_admin`] exists
/// to undo: a `false` could not distinguish *not an admin* from *an admin whose
/// account is suspended*, and the second is the case PCS was admitting.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct AdminLayer1 {
    /// `scaccounts.ppnums.is_admin` — the *grant*. Survives lifecycle changes
    /// by design, which is precisely why the state below must be checked too.
    pub is_admin: bool,
    /// `scaccounts.ppnums.lifecycle_state` — the *effect*. Only
    /// [`LifecycleState::Active`] carries admin authority.
    pub lifecycle_state: LifecycleState,
}

impl AdminLayer1 {
    /// The premises a principal with no `ppnums` row presents: no grant, and a
    /// state that can never be [`Active`](LifecycleState::Active).
    ///
    /// Named rather than left to each caller's `unwrap_or_default`, because
    /// "the row is missing" is a real case on a cross-schema read and the wrong
    /// default there is an authorization bug. [`LifecycleState::Tombstoned`] is
    /// the terminal state, so it is the honest stand-in for *absent*.
    #[must_use]
    pub const fn absent() -> Self {
        Self {
            is_admin: false,
            lifecycle_state: LifecycleState::Tombstoned,
        }
    }

    /// **The two-term Layer-1 AND — the only statement of it.** Is there a
    /// grant, and is it currently in effect?
    ///
    /// Public because several callers legitimately need Layer 1 *alone*: the
    /// FR-016 "an effective admin may not revoke their last passkey" rule and
    /// the admin-only branch of an email change are asking about authority, not
    /// about possession, and forcing a passkey read on them would buy nothing.
    /// What they must not do is re-spell `is_admin && state == Active`
    /// themselves — that is the collapse this crate exists to prevent, and the
    /// reason this is a method rather than a comment telling callers to be
    /// careful.
    #[must_use]
    pub const fn is_in_effect(self) -> bool {
        self.is_admin && matches!(self.lifecycle_state, LifecycleState::Active)
    }

    /// Complete the premise set with the Layer-2 fact.
    #[must_use]
    pub const fn with_passkeys(self, passkeys: ActivePasskeys) -> AdminFacts {
        AdminFacts {
            layer1: self,
            passkeys,
        }
    }
}

/// The complete premise set of the effective-admin gate.
///
/// Nested rather than flat so the cacheable half has a name of its own: the two
/// layers have different freshness contracts (Layer 1 cached for 60s and
/// explicitly invalidated on grant/revoke; Layer 2 uncached so a passkey revoke
/// lands on the very next request), and a type that hides that asymmetry would
/// invite caching the whole thing.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct AdminFacts {
    /// The cached pair — grant and lifecycle state.
    pub layer1: AdminLayer1,
    /// The uncached count, or [`ActivePasskeys::Unknown`].
    pub passkeys: ActivePasskeys,
}

/// The outcome of [`effective_admin`]. Each variant maps to a distinct
/// protocol-specific response **at the caller's edge** — a gRPC `Status` with
/// `error-code` metadata, or an HTTP status plus a rendered page. This crate
/// never speaks either protocol.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum AdminVerdict {
    /// Every premise holds. The caller is an effective admin.
    Authorized,
    /// No grant, or the grant is not in effect (non-`Active` lifecycle state,
    /// including an absent row). A definitive denial — 403-class.
    NotAdmin,
    /// Granted and in effect, but zero active passkeys. A definitive denial
    /// with a *different* affordance: the principal can fix it by enrolling a
    /// passkey, so callers route here to enrolment, not to retry. 403-class.
    NoActivePasskey,
    /// Granted and in effect, and the passkey premise is **unknown**. Not a
    /// denial of authority — a refusal to decide. Fail-closed on the direction
    /// axis (access is withheld) while staying honest on the visibility axis
    /// (503-class + retry, never the enrolment path, never a 403).
    CheckTimeout,
}

impl AdminVerdict {
    /// The one question a perimeter actually asks. Present so a caller cannot
    /// accidentally treat [`CheckTimeout`](Self::CheckTimeout) as a pass by
    /// matching only the two 403 variants.
    #[must_use]
    pub const fn is_authorized(self) -> bool {
        matches!(self, Self::Authorized)
    }
}

/// **The database facts this rule is a function of** — AP-9's "name on the fact"
/// ([STS_AUTHZ_PREMISE_PPOPPO] §4).
///
/// `effective_admin` is a pure function, so nothing about it can go stale. What
/// *can* go stale is the SQL each organ writes to gather its arguments: a column
/// renamed in a migration, or a `WHERE` clause quietly dropped, changes the
/// premises without changing the predicate — and the predicate keeps returning a
/// confident verdict about facts it was no longer given.
///
/// So the columns are declared here, beside the rule, and **each organ ships a
/// drift test that scans its own premise SQL against this list**
/// (`accounts-api/tests/admin_premise_drift.rs`,
/// `chat-api/tests/admin_premise_drift.rs`). One declaration, two scanners: an
/// engine crate cannot read service sources without inverting the lattice, and a
/// list maintained twice is the drift it exists to catch.
///
/// The pairing with the other guard is deliberate and the two are not
/// redundant: `effective_admin` being the only conjunction is checked at the
/// *decision*, and this is checked at the *premises*. The RFC §6 defect was the
/// former; a migration renaming `lifecycle_state` would be the latter.
///
/// [STS_AUTHZ_PREMISE_PPOPPO]: https://github.com/ppoppo/ppoppo/blob/main/0context/STS_AUTHZ_PREMISE_PPOPPO.md
pub const ADMIN_PREMISE_COLUMNS: &[AdminPremiseColumn] = &[
    AdminPremiseColumn {
        table: "ppnums",
        column: "is_admin",
        supplies: "AdminLayer1::is_admin",
    },
    AdminPremiseColumn {
        table: "ppnums",
        column: "lifecycle_state",
        supplies: "AdminLayer1::lifecycle_state",
    },
    AdminPremiseColumn {
        table: "passkey_credentials",
        column: "ppnum_id",
        supplies: "ActivePasskeys — the count is scoped to one account",
    },
    AdminPremiseColumn {
        table: "passkey_credentials",
        column: "revoked_at",
        supplies: "ActivePasskeys — a revoked credential is not possession",
    },
];

/// One column the admin rule depends on, and which argument it supplies.
///
/// `supplies` is not decoration: a drift test can only report "column absent",
/// while this says which premise silently became a guess.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct AdminPremiseColumn {
    /// Unqualified table name, in `scaccounts`. Unqualified because PCS must
    /// schema-qualify (`scaccounts.ppnums`) and PAS need not, so requiring the
    /// prefix here would make one organ's compliant SQL look non-compliant.
    pub table: &'static str,
    /// Column name as it appears in the schema.
    pub column: &'static str,
    /// The `AdminFacts` field this column feeds.
    pub supplies: &'static str,
}

/// **The effective-admin conjunction — the only statement of it.**
///
/// ```text
/// Authorized  ⟺  is_admin ∧ lifecycle_state = Active ∧ passkeys = Counted(n > 0)
/// ```
///
/// Two properties are as load-bearing as the conjunction itself, and both are
/// about *which* denial a caller is handed:
///
/// 1. **Layer 1 is evaluated before Layer 2.** A principal who is not an
///    effective admin gets [`NotAdmin`](AdminVerdict::NotAdmin) even when the
///    passkey premise is [`Unknown`](ActivePasskeys::Unknown). Otherwise an
///    unauthorized caller could convert a flat denial into a retry-shaped 503
///    by making the passkey read slow — an authorization decision leaking a
///    substrate signal.
/// 2. **Unknown never becomes zero.** `Unknown` yields
///    [`CheckTimeout`](AdminVerdict::CheckTimeout), so no caller can mistake a
///    slow read for a definitive absence and route an admin into passkey
///    recovery.
#[must_use]
pub const fn effective_admin(facts: &AdminFacts) -> AdminVerdict {
    // Layer 1 — the grant, and whether it is currently in effect. Ordered
    // first on purpose; see property 1 above. Delegated rather than re-spelled
    // so the two-term AND has one home even inside this function.
    if !facts.layer1.is_in_effect() {
        return AdminVerdict::NotAdmin;
    }

    // Layer 2 — the possession factor.
    match facts.passkeys {
        ActivePasskeys::Unknown => AdminVerdict::CheckTimeout,
        ActivePasskeys::Counted(n) if n > 0 => AdminVerdict::Authorized,
        ActivePasskeys::Counted(_) => AdminVerdict::NoActivePasskey,
    }
}

// ── Compile-time gates ──────────────────────────────────────────────────
//
// The four canonical rows of the truth table, settled at build time. The
// exhaustive cross-product lives in the tests below; these four are the ones
// whose inversion would be a security incident rather than a bug, so they are
// asserted where no test run is needed to notice.
const _: () = {
    const fn verdict(
        is_admin: bool,
        state: LifecycleState,
        passkeys: ActivePasskeys,
    ) -> AdminVerdict {
        effective_admin(
            &AdminLayer1 {
                is_admin,
                lifecycle_state: state,
            }
            .with_passkeys(passkeys),
        )
    }

    // The only row that admits.
    assert!(matches!(
        verdict(true, LifecycleState::Active, ActivePasskeys::Counted(1)),
        AdminVerdict::Authorized
    ));
    // The row RFC_202608241353 §6 found admitted on the PCS face: the grant
    // survived, the account did not.
    assert!(matches!(
        verdict(
            true,
            LifecycleState::Deactivated,
            ActivePasskeys::Counted(1)
        ),
        AdminVerdict::NotAdmin
    ));
    // A definitive absence is a denial, not a retry.
    assert!(matches!(
        verdict(true, LifecycleState::Active, ActivePasskeys::Counted(0)),
        AdminVerdict::NoActivePasskey
    ));
    // An unknown premise is a refusal to decide, not a denial of authority.
    assert!(matches!(
        verdict(true, LifecycleState::Active, ActivePasskeys::Unknown),
        AdminVerdict::CheckTimeout
    ));
    // Property 1 — Layer 1 first: a non-admin with an unknown passkey count is
    // denied flatly, never handed the retry-shaped outcome.
    assert!(matches!(
        verdict(false, LifecycleState::Active, ActivePasskeys::Unknown),
        AdminVerdict::NotAdmin
    ));
};

#[cfg(test)]
#[allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
mod tests {
    use super::*;

    /// Every premise combination the type system admits, checked against the
    /// rule written a **second, different way**. Two spellings of one rule is
    /// normally the thing to avoid; in a test of a decision function it is the
    /// only way the assertion carries information — comparing the function to
    /// itself would pass no matter what it decided.
    #[test]
    fn the_whole_input_space_decides_as_specified() {
        let mut authorized_rows = 0;
        for is_admin in [true, false] {
            for state in LifecycleState::ALL {
                for passkeys in [
                    ActivePasskeys::Counted(-1),
                    ActivePasskeys::Counted(0),
                    ActivePasskeys::Counted(1),
                    ActivePasskeys::Counted(i64::MAX),
                    ActivePasskeys::Unknown,
                ] {
                    let facts = AdminLayer1 {
                        is_admin,
                        lifecycle_state: state,
                    }
                    .with_passkeys(passkeys);

                    let in_effect = is_admin && state == LifecycleState::Active;
                    let expected = if !in_effect {
                        AdminVerdict::NotAdmin
                    } else {
                        match passkeys {
                            ActivePasskeys::Unknown => AdminVerdict::CheckTimeout,
                            ActivePasskeys::Counted(n) if n > 0 => AdminVerdict::Authorized,
                            ActivePasskeys::Counted(_) => AdminVerdict::NoActivePasskey,
                        }
                    };

                    assert_eq!(
                        effective_admin(&facts),
                        expected,
                        "premises {facts:?} decided against the specification",
                    );
                    if expected == AdminVerdict::Authorized {
                        authorized_rows += 1;
                    }
                }
            }
        }
        // Independently measured, not copied from the brief: one `is_admin`
        // value × one state × two positive counts is the entire admitting
        // region of a 2 × 8 × 5 space. If a future variant widens it, this
        // number moves and someone has to say why.
        assert_eq!(
            authorized_rows, 2,
            "the admitting region of the premise space changed",
        );
    }

    /// The seven non-`Active` states all deny, and they deny *flatly* — this is
    /// the term the PCS admin perimeter was missing entirely
    /// (`RFC_202608241353` §6), so it gets its own named assertion rather than
    /// living only inside the cross-product above.
    #[test]
    fn a_granted_admin_outside_active_is_denied() {
        for state in LifecycleState::ALL {
            if state == LifecycleState::Active {
                continue;
            }
            let facts = AdminLayer1 {
                is_admin: true,
                lifecycle_state: state,
            }
            .with_passkeys(ActivePasskeys::Counted(3));
            assert_eq!(
                effective_admin(&facts),
                AdminVerdict::NotAdmin,
                "a granted admin in {state:?} must not be effective",
            );
        }
    }

    /// An absent row is not an admin, whichever Layer-2 fact accompanies it.
    #[test]
    fn absent_premises_never_authorize() {
        for passkeys in [
            ActivePasskeys::Counted(0),
            ActivePasskeys::Counted(9),
            ActivePasskeys::Unknown,
        ] {
            assert_eq!(
                effective_admin(&AdminLayer1::absent().with_passkeys(passkeys)),
                AdminVerdict::NotAdmin,
            );
        }
    }

    /// `is_in_effect` is the Layer-1 half of the predicate and is consumed on
    /// its own by callers that ask about authority without possession. It must
    /// therefore agree with [`effective_admin`] on every Layer-1 row: whenever
    /// it is `false`, the full verdict is `NotAdmin` regardless of Layer 2.
    #[test]
    fn layer1_alone_agrees_with_the_full_verdict() {
        for is_admin in [true, false] {
            for state in LifecycleState::ALL {
                let layer1 = AdminLayer1 {
                    is_admin,
                    lifecycle_state: state,
                };
                for passkeys in [
                    ActivePasskeys::Counted(0),
                    ActivePasskeys::Counted(7),
                    ActivePasskeys::Unknown,
                ] {
                    let verdict = effective_admin(&layer1.with_passkeys(passkeys));
                    if layer1.is_in_effect() {
                        assert_ne!(
                            verdict,
                            AdminVerdict::NotAdmin,
                            "Layer 1 holds for {layer1:?} but the verdict denies on Layer 1",
                        );
                    } else {
                        assert_eq!(
                            verdict,
                            AdminVerdict::NotAdmin,
                            "Layer 1 fails for {layer1:?} but the verdict did not deny",
                        );
                    }
                }
            }
        }
        assert!(
            AdminLayer1 {
                is_admin: true,
                lifecycle_state: LifecycleState::Active,
            }
            .is_in_effect(),
            "the one row that holds must hold",
        );
        assert!(!AdminLayer1::absent().is_in_effect());
    }

    /// `is_authorized` must agree with the verdict it reads, including on the
    /// variant that is easiest to mishandle.
    #[test]
    fn is_authorized_admits_exactly_one_verdict() {
        assert!(AdminVerdict::Authorized.is_authorized());
        for v in [
            AdminVerdict::NotAdmin,
            AdminVerdict::NoActivePasskey,
            AdminVerdict::CheckTimeout,
        ] {
            assert!(!v.is_authorized(), "{v:?} must not read as authorized");
        }
    }

    /// The cache value must round-trip: the Layer-1 pair is stored as JSON in
    /// KVRocks, and a shape change that silently re-encodes would make every
    /// live entry unreadable rather than merely stale.
    #[cfg(feature = "serde")]
    #[test]
    fn layer1_round_trips_as_json() {
        let facts = AdminLayer1 {
            is_admin: true,
            lifecycle_state: LifecycleState::Active,
        };
        let json = serde_json::to_string(&facts).expect("serialize");
        assert_eq!(json, r#"{"is_admin":true,"lifecycle_state":"active"}"#);
        assert_eq!(
            serde_json::from_str::<AdminLayer1>(&json).expect("deserialize"),
            facts,
        );
    }

    /// A `bool` — the shape this cache key held before the premise pair — must
    /// **fail** to deserialize rather than decode into something plausible, so
    /// entries written by an older pod fall through to the database instead of
    /// authorizing on a guess. Same discipline the `mbr:` tri-state migration
    /// relied on (`STS_SHARED_CACHE` §2.2).
    #[cfg(feature = "serde")]
    #[test]
    fn a_stale_bool_cache_entry_does_not_decode() {
        assert!(serde_json::from_str::<AdminLayer1>("true").is_err());
        assert!(serde_json::from_str::<AdminLayer1>("false").is_err());
    }
}