ppoppo_token/issue_request.rs
1//! Per-issuance request payload.
2//!
3//! Phase 3 carved out the registered-claim core (`sub`, `client_id`, `ttl`,
4//! `jti`); Phase 4 (this expansion) adds 9 domain claim fields that the
5//! verifier's `engine/check_domain` mirrors. Every claim that varies per
6//! token lives here, every claim that's stable across many tokens lives on
7//! `IssueConfig`.
8//!
9//! Fields are `pub` rather than enclosed by accessors. The struct is a
10//! data carrier (mirrors `Claims` on the verify side); a builder for one
11//! optional field would be ceremony without payoff. Callers that adopt
12//! struct-literal syntax (none today) will get compile errors when later
13//! phases add fields, which is the right failure mode (silent defaulting
14//! hides intent).
15//!
16//! ── Default-deny invariant ───────────────────────────────────────────────
17//!
18//! `admin`, `caps`, `dlg_depth`, `scopes` all default to "deny / empty / 0".
19//! Callers MUST opt in explicitly via `.with_admin(true)` / `.with_caps(...)`
20//! / etc. No issuance path can accidentally mint an admin token by
21//! forgetting to set a flag — the absent default is the safe default.
22
23use std::time::Duration;
24use ulid::Ulid;
25
26#[derive(Debug, Clone)]
27pub struct IssueRequest {
28 /// Subject — the principal the token is about (RFC 7519 §4.1.2).
29 /// PAS-issued human tokens carry `ppnum_id` (ULID); AI-agent tokens
30 /// carry the agent's ULID. Never empty.
31 pub sub: String,
32
33 /// `client_id` — the OAuth client whose credentials authorized this
34 /// token (RFC 9068 §2.2). 1st-party flows use `"ppoppo-internal"`;
35 /// External Developer flows use the registered OAuth client_id.
36 pub client_id: String,
37
38 /// Time-to-live from now. The engine computes `exp = iat + ttl` and
39 /// emits both. Per-profile cap (24h access / 200d refresh) is
40 /// enforced via M19 on the verify side.
41 pub ttl: Duration,
42
43 /// Optional caller-supplied `jti`. When `None`, `engine::encode::issue`
44 /// generates a fresh ULID at issuance time. Tests pin a known ULID
45 /// so assertions can match by exact value.
46 pub jti: Option<Ulid>,
47
48 // ── Phase 4 domain claims (M39–M45) ──────────────────────────────────
49 /// `account_type` — principal class (M40). Whitelist `{human, ai_agent}`
50 /// enforced verifier-side; absent for legacy tokens. PAS sets `"human"`
51 /// on user-facing flows and `"ai_agent"` on client_credentials.
52 pub account_type: Option<String>,
53
54 /// `admin` — issue-time admin gate flag (M44). When `true`, the
55 /// verifier additionally requires `active_ppnum` (or `sub` band
56 /// fallback) to fall in an admin-allocated band — defense in depth
57 /// against forged tokens with a stolen signing key.
58 pub admin: bool,
59
60 /// `caps` — capability list (M41). Default `[]` is the default-deny
61 /// surface contract: a token with no capabilities cannot perform any
62 /// privileged operation. Engine validates only that the wire shape
63 /// is an array of strings; semantic enforcement is per-surface.
64 pub caps: Vec<String>,
65
66 /// `delegator` — delegating principal's `ppnum_id` (M40-adjacent).
67 /// Set on tokens minted via Token Exchange flows to record who
68 /// authorized the delegated session. Audit logs key off this field.
69 /// (Wire name: `delegator`; the earlier `actor` name was retired —
70 /// RFC 8693 reserves `actor` for token-exchange chain semantics that
71 /// don't apply here.)
72 pub delegator: Option<String>,
73
74 /// `dlg_depth` — delegation chain depth (M43). 0 = original principal,
75 /// each Token Exchange step increments by 1. Engine rejects > 4 to
76 /// bound the audit-trail explosion of arbitrarily deep delegation.
77 /// `u8` is intentional: there is no scenario where depth ≥ 256.
78 pub dlg_depth: u8,
79
80 /// `cid` — WebAuthn credential id that authenticated this session
81 /// (passkey path only). Enables session-to-credential provenance for
82 /// forensic analysis and selective-session-kill flows. Absent on
83 /// every non-passkey path so audit logs distinguish authentication
84 /// methods without a per-row lookup.
85 pub cid: Option<String>,
86
87 /// `sv` — per-account `session_version` snapshot (Human path only).
88 /// Validators compare `token.sv >= cached(sv:{sub})` and reject
89 /// stale tokens; the counter bumps inside the break-glass TX,
90 /// invalidating all prior tokens within the consumer cache TTL.
91 /// Absent on AI-agent and delegated tokens (no break-glass mechanism).
92 pub sv: Option<u64>,
93
94 /// `active_ppnum` — display ppnum (e.g. `123-1234-5678`). UI surfaces
95 /// render this; `sub` is the immutable ULID and is the authorization
96 /// axis. Absent on tokens that don't represent a human-facing
97 /// session (raw machine tokens).
98 pub active_ppnum: Option<String>,
99
100 /// `scopes` — OAuth scope list (M42). Engine bounds the array to ≤ 256
101 /// entries (RFC 8725-adjacent — bound the per-token audit surface).
102 /// Default `[]` is "no externally-granted scope"; 1st-party flows
103 /// emit a non-empty list (`profile`, `email`, etc).
104 pub scopes: Vec<String>,
105
106 /// `sid` — session row id (M36, Phase 5). When set, the verifier's
107 /// `cfg.session_revocation::is_active(sub, sid)` query gates token
108 /// admission against `user_sessions(sub, sid)` row liveness — row
109 /// deletion = revocation per STANDARDS_JWT_DETAILS_MITIGATION §E.
110 /// PAS issuance sets this on every Human-path token bound to a
111 /// session row; AI-agent / machine flows leave it unset and the
112 /// verifier short-circuits the gate. Wire shape: ULID string when
113 /// present (matches `user_sessions.session_id` PK).
114 pub sid: Option<String>,
115}
116
117impl IssueRequest {
118 /// Construct a new request with the required fields. Domain claim
119 /// fields default to "absent / empty / 0 / false" — every emission
120 /// is opt-in via a `with_*` builder, so a caller who forgets to set
121 /// `admin` cannot accidentally mint an admin token.
122 pub fn new(sub: impl Into<String>, client_id: impl Into<String>, ttl: Duration) -> Self {
123 Self {
124 sub: sub.into(),
125 client_id: client_id.into(),
126 ttl,
127 jti: None,
128 account_type: None,
129 admin: false,
130 caps: Vec::new(),
131 delegator: None,
132 dlg_depth: 0,
133 cid: None,
134 sv: None,
135 active_ppnum: None,
136 scopes: Vec::new(),
137 sid: None,
138 }
139 }
140
141 /// Pin a specific `jti` instead of letting the engine generate one.
142 /// Test-only escape hatch — production paths should never override.
143 #[must_use]
144 pub fn with_jti(mut self, jti: Ulid) -> Self {
145 self.jti = Some(jti);
146 self
147 }
148
149 /// Set `account_type` (M40). PAS issuance paths pass `"human"` or
150 /// `"ai_agent"`; the verifier's whitelist (Phase 4 commit 4.2)
151 /// rejects anything else.
152 #[must_use]
153 pub fn with_account_type(mut self, account_type: impl Into<String>) -> Self {
154 self.account_type = Some(account_type.into());
155 self
156 }
157
158 /// Set the admin gate flag (M44). Combined with `active_ppnum` band
159 /// check on the verify side, this is the issue-time half of the
160 /// admin-token defense in depth.
161 #[must_use]
162 pub fn with_admin(mut self, admin: bool) -> Self {
163 self.admin = admin;
164 self
165 }
166
167 /// Set the capability list (M41). An empty list (the default) means
168 /// no privileged capabilities; surface code MUST positive-check.
169 #[must_use]
170 pub fn with_caps(mut self, caps: Vec<String>) -> Self {
171 self.caps = caps;
172 self
173 }
174
175 /// Set the delegating principal's `ppnum_id` (M40-adjacent). Token
176 /// Exchange flows record the human authorizer here.
177 #[must_use]
178 pub fn with_delegator(mut self, delegator: impl Into<String>) -> Self {
179 self.delegator = Some(delegator.into());
180 self
181 }
182
183 /// Set the delegation chain depth (M43). 0 = direct, increments by 1
184 /// per Token Exchange step; engine bounds at 4.
185 #[must_use]
186 pub fn with_dlg_depth(mut self, dlg_depth: u8) -> Self {
187 self.dlg_depth = dlg_depth;
188 self
189 }
190
191 /// Set the WebAuthn credential id (`cid`). Call this only on the
192 /// passkey issuance path; other paths MUST leave it unset so audit
193 /// logs distinguish authentication methods without a per-row lookup.
194 #[must_use]
195 pub fn with_credential_id(mut self, credential_id: impl Into<String>) -> Self {
196 self.cid = Some(credential_id.into());
197 self
198 }
199
200 /// Set the per-account `session_version` (Human entity path only).
201 /// AI-agent and delegated paths MUST leave it unset — they have no
202 /// break-glass mechanism, and emitting `sv = 0` would lock those
203 /// tokens out the moment the human originator break-glasses.
204 #[must_use]
205 pub fn with_session_version(mut self, sv: u64) -> Self {
206 self.sv = Some(sv);
207 self
208 }
209
210 /// Set the display ppnum (`active_ppnum`). UI surfaces render this;
211 /// `sub` remains the immutable ULID for authorization decisions.
212 #[must_use]
213 pub fn with_active_ppnum(mut self, active_ppnum: impl Into<String>) -> Self {
214 self.active_ppnum = Some(active_ppnum.into());
215 self
216 }
217
218 /// Set the OAuth scope list (M42). Engine bounds the array to ≤ 256
219 /// entries on the verify side.
220 #[must_use]
221 pub fn with_scopes(mut self, scopes: Vec<String>) -> Self {
222 self.scopes = scopes;
223 self
224 }
225
226 /// Set the session row id (`sid` claim, M36 — Phase 5). Call this
227 /// only on issuance paths bound to a `user_sessions` row (Human
228 /// magic-link / passkey / refresh-cycle); AI-agent and machine
229 /// paths MUST leave it unset so the verifier short-circuits the
230 /// session-revocation gate. The verifier compares `(sub, sid)`
231 /// against the substrate; row deletion = revocation per
232 /// STANDARDS_JWT_DETAILS_MITIGATION §E.
233 #[must_use]
234 pub fn with_sid(mut self, sid: impl Into<String>) -> Self {
235 self.sid = Some(sid.into());
236 self
237 }
238}