ppoppo-token 0.3.0

JWT (RFC 9068, EdDSA) issuance + verification engine for the Ppoppo ecosystem. Single deep module with a small interface (issue, verify) hiding RFC 8725 mitigations M01-M45, JWKS handling, and substrate ports (epoch, session, replay).
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101

//! Verified claim payload returned by the JWT engine after `verify`.
//!
//! Surface discipline (Phase 2 Decision 1, extended Phase 4):
//!
//! - **Hidden** — claims the engine fully resolves with no caller
//!   participation:
//!     - `aud` (M20-M22 validates against `cfg.audience`)
//!     - `cat` (M29 validates against `cfg.expected_cat`)
//!     - `dlg_depth` (M43 validates ≤ 4)
//!     - `sv` (Phase 5 cache compares against `sv:{sub}`)
//! - **Surfaced** — claims callers legitimately need post-verify:
//!     - `client_id` (M28a — audit logs, per-client rate limits)
//!     - `account_type` (M40 — admin gate code reads it)
//!     - `caps`, `scopes` (M41/M42 — capability check is post-verify)
//!     - `delegator` (Token Exchange audit logs)
//!     - `cid` (forensic / selective-session-kill)
//!     - `active_ppnum` (UI display)
//!     - `admin` (admin RPC handlers gate on it)
//!
//! Surfacing wrongly is a forward-compat tax (every caller must handle
//! the new field). Hiding wrongly leaves callers without info they need.
//! When in doubt, hide — adding later is cheap; removing later is a
//! breaking change.

#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Claims {
    pub iss: String,
    pub sub: String,
    pub exp: i64,
    pub iat: i64,
    pub nbf: Option<i64>,
    pub jti: String,
    pub client_id: String,

    // ── Phase 4 surfaced domain claims (M40+) ───────────────────────────
    /// `account_type` (M40) — `"human"` | `"ai_agent"` | `"programmable"` |
    /// `None` (legacy admit). Whitelist enforced verifier-side; arbitrary
    /// strings are rejected with `AuthError::AccountTypeInvalid` before this
    /// struct is constructed. `"programmable"` = External Developer app
    /// client_credentials token.
    pub account_type: Option<String>,

    /// `caps` (M41) — capability list. Empty when absent or empty-array
    /// on the wire (the engine collapses both to the same surface so
    /// callers' default-deny check is `caps.contains(&"x")`). Wire-shape
    /// validation (must be a JSON array of strings) lives in
    /// `engine::check_domain`; semantic interpretation of each
    /// capability string is per-surface (PAS, PCS, RCW each own their
    /// vocabulary).
    pub caps: Vec<String>,

    /// `scopes` (M42) — OAuth scope list. Empty when absent or empty-
    /// array (same collapse as `caps`). Engine bounds the array length
    /// at ≤ 256; entries beyond that are a forgery / misconfiguration
    /// signal that pessimizes per-request scope checks. Conceptually
    /// distinct from `caps` (scopes are externally granted via OAuth;
    /// caps are internally minted by PAS), so the surfacing is duplicated
    /// rather than unified — collapsing them would force callers to
    /// untangle two authorization vectors at every check site.
    pub scopes: Vec<String>,

    /// `admin` (M44) — token claims admin authority. **Admin authority
    /// is DB-determined** (STANDARDS_AUTH_PPOPPO §3.2: `is_admin = TRUE
    /// AND lifecycle_state = 'active'` AND active passkey ≥ 1). This
    /// claim is the *fast pre-flight signal* — when `admin == true`,
    /// the engine has already proven `active_ppnum` falls in the admin
    /// band (defense in depth against stolen-signing-key forgeries).
    /// Callers MUST still call the DB-side `is_admin` invariant — this
    /// flag tells them whether to even bother.
    pub admin: bool,
    /// `active_ppnum` (M44 + UI display) — the digit-form ppnum the
    /// session is currently active under. UI surfaces render this;
    /// `sub` (ULID) is the immutable authorization axis. Engine reads
    /// it for the M44 admin-band check and surfaces it unchanged.
    pub active_ppnum: Option<String>,

    /// `delegator` — Token Exchange chain's delegating principal
    /// `ppnum_id`. Surfaced for audit logs (which human authorized the
    /// delegated session). `None` for tokens that aren't part of a
    /// chain. Wire name is `delegator` (the matrix's earlier `actor`
    /// was retired — RFC 8693 reserves `actor` for token-exchange
    /// chain semantics that don't apply here).
    pub delegator: Option<String>,

    /// `cid` — WebAuthn credential id that authenticated this session
    /// (passkey path only). Surfaces for forensic provenance and
    /// future selective-session-kill flows. `None` on every non-
    /// passkey path so audit logs distinguish authentication methods
    /// without a per-row lookup.
    pub cid: Option<String>,

    /// `sid` (M36) — session row id (`user_sessions.session_id`). When
    /// present, the engine queries the substrate via
    /// `cfg.session_revocation.is_active(sub, sid)` and refuses if the
    /// row is absent (STANDARDS_JWT_DETAILS_MITIGATION §E "row deletion
    /// = revocation"). `None` on machine tokens / AI-agent flows that
    /// have no session row to check; engine short-circuits the gate
    /// when `None` so non-session-bound tokens admit (legacy /
    /// pre-Phase-5 tokens included).
    pub sid: Option<String>,
}