ppoppo_token/access_token/
claims.rs

1//! Verified claim payload returned by the JWT engine after `verify`.
2//!
3//! Surface discipline (Phase 2 Decision 1, extended Phase 4):
4//!
5//! - **Hidden** — claims the engine fully resolves with no caller
6//!   participation:
7//!     - `aud` (M20-M22 validates against `cfg.audience`)
8//!     - `cat` (M29 validates against `cfg.expected_cat`)
9//!     - `dlg_depth` (M43 validates ≤ 4)
10//!     - `sv` (Phase 5 cache compares against `sv:{sub}`)
11//! - **Surfaced** — claims callers legitimately need post-verify:
12//!     - `client_id` (M28a — audit logs, per-client rate limits)
13//!     - `account_type` (M40 — admin gate code reads it)
14//!     - `caps`, `scopes` (M41/M42 — capability check is post-verify)
15//!     - `delegator` (Token Exchange audit logs)
16//!     - `cid` (forensic / selective-session-kill)
17//!     - `active_ppnum` (UI display)
18//!     - `admin` (admin RPC handlers gate on it)
19//!
20//! Surfacing wrongly is a forward-compat tax (every caller must handle
21//! the new field). Hiding wrongly leaves callers without info they need.
22//! When in doubt, hide — adding later is cheap; removing later is a
23//! breaking change.
24
25#[derive(Debug, Clone, PartialEq, Eq)]
26pub struct Claims {
27    pub iss: String,
28    pub sub: String,
29    pub exp: i64,
30    pub iat: i64,
31    pub nbf: Option<i64>,
32    pub jti: String,
33    pub client_id: String,
34
35    // ── Phase 4 surfaced domain claims (M40+) ───────────────────────────
36    /// `account_type` (M40) — `"human"` | `"ai_agent"` | `None` (legacy
37    /// admit). Whitelist enforced verifier-side; arbitrary strings are
38    /// rejected with `AuthError::AccountTypeInvalid` before this struct
39    /// is constructed.
40    pub account_type: Option<String>,
41
42    /// `caps` (M41) — capability list. Empty when absent or empty-array
43    /// on the wire (the engine collapses both to the same surface so
44    /// callers' default-deny check is `caps.contains(&"x")`). Wire-shape
45    /// validation (must be a JSON array of strings) lives in
46    /// `engine::check_domain`; semantic interpretation of each
47    /// capability string is per-surface (PAS, PCS, RCW each own their
48    /// vocabulary).
49    pub caps: Vec<String>,
50
51    /// `scopes` (M42) — OAuth scope list. Empty when absent or empty-
52    /// array (same collapse as `caps`). Engine bounds the array length
53    /// at ≤ 256; entries beyond that are a forgery / misconfiguration
54    /// signal that pessimizes per-request scope checks. Conceptually
55    /// distinct from `caps` (scopes are externally granted via OAuth;
56    /// caps are internally minted by PAS), so the surfacing is duplicated
57    /// rather than unified — collapsing them would force callers to
58    /// untangle two authorization vectors at every check site.
59    pub scopes: Vec<String>,
60
61    /// `admin` (M44) — token claims admin authority. **Admin authority
62    /// is DB-determined** (STANDARDS_AUTH_PPOPPO §3.2: `is_admin = TRUE
63    /// AND lifecycle_state = 'active'` AND active passkey ≥ 1). This
64    /// claim is the *fast pre-flight signal* — when `admin == true`,
65    /// the engine has already proven `active_ppnum` falls in the admin
66    /// band (defense in depth against stolen-signing-key forgeries).
67    /// Callers MUST still call the DB-side `is_admin` invariant — this
68    /// flag tells them whether to even bother.
69    pub admin: bool,
70    /// `active_ppnum` (M44 + UI display) — the digit-form ppnum the
71    /// session is currently active under. UI surfaces render this;
72    /// `sub` (ULID) is the immutable authorization axis. Engine reads
73    /// it for the M44 admin-band check and surfaces it unchanged.
74    pub active_ppnum: Option<String>,
75
76    /// `delegator` — Token Exchange chain's delegating principal
77    /// `ppnum_id`. Surfaced for audit logs (which human authorized the
78    /// delegated session). `None` for tokens that aren't part of a
79    /// chain. Wire name is `delegator` (the matrix's earlier `actor`
80    /// was retired — RFC 8693 reserves `actor` for token-exchange
81    /// chain semantics that don't apply here).
82    pub delegator: Option<String>,
83
84    /// `cid` — WebAuthn credential id that authenticated this session
85    /// (passkey path only). Surfaces for forensic provenance and
86    /// future selective-session-kill flows. `None` on every non-
87    /// passkey path so audit logs distinguish authentication methods
88    /// without a per-row lookup.
89    pub cid: Option<String>,
90
91    /// `sid` (M36) — session row id (`user_sessions.session_id`). When
92    /// present, the engine queries the substrate via
93    /// `cfg.session_revocation.is_active(sub, sid)` and refuses if the
94    /// row is absent (STANDARDS_JWT_DETAILS_MITIGATION §E "row deletion
95    /// = revocation"). `None` on machine tokens / AI-agent flows that
96    /// have no session row to check; engine short-circuits the gate
97    /// when `None` so non-session-bound tokens admit (legacy /
98    /// pre-Phase-5 tokens included).
99    pub sid: Option<String>,
100}
ppoppo_token/access_token/claims.rs

ppoppo_token/access_token/
claims.rs
