ppoppo-token 0.28.0

//! Per-issuance request payload.
//!
//! Phase 3 carved out the registered-claim core (`sub`, `client_id`, `ttl`,
//! `jti`); Phase 4 (this expansion) adds 9 domain claim fields that the
//! verifier's `engine/check_domain` mirrors. Every claim that varies per
//! token lives here, every claim that's stable across many tokens lives on
//! `IssueConfig`.
//!
//! Fields are `pub` rather than enclosed by accessors. The struct is a
//! data carrier (mirrors `Claims` on the verify side); a builder for one
//! optional field would be ceremony without payoff. Callers that adopt
//! struct-literal syntax (none today) will get compile errors when later
//! phases add fields, which is the right failure mode (silent defaulting
//! hides intent).
//!
//! ── Default-deny invariant ───────────────────────────────────────────────
//!
//! `admin`, `caps`, `act`, `scopes` all default to "deny / empty / absent".
//! Callers MUST opt in explicitly via `.with_admin(true)` / `.with_caps(...)`
//! / etc. No issuance path can accidentally mint an admin token by
//! forgetting to set a flag — the absent default is the safe default.

use std::time::Duration;
use ulid::Ulid;

use super::{Act, EntityType};

#[derive(Debug, Clone)]
pub struct IssueRequest {
    /// Subject — the principal the token is about (RFC 7519 §4.1.2).
    /// PAS-issued human tokens carry `ppnum_id` (ULID); AI-agent tokens
    /// carry the agent's ULID. Never empty.
    pub sub: String,

    /// `client_id` — the OAuth client whose credentials authorized this
    /// token (RFC 9068 §2.2). 1st-party flows use `"ppoppo-internal"`;
    /// External Developer flows use the registered OAuth client_id.
    pub client_id: String,

    /// Time-to-live from now. The engine computes `exp = iat + ttl` and
    /// emits both. Per-profile cap (24h access / 200d refresh) is
    /// enforced via M19 on the verify side.
    pub ttl: Duration,

    /// Optional caller-supplied `jti`. When `None`, `engine::encode::issue`
    /// generates a fresh ULID at issuance time. Tests pin a known ULID
    /// so assertions can match by exact value.
    pub jti: Option<Ulid>,

    // ── Phase 4 domain claims (M39–M45) ──────────────────────────────────
    /// `entity_type` — identity class of `sub` (M40). Absent on
    /// 1st-party OTP/passkey flows. Typed, so a mint site cannot emit a
    /// value this crate's own verifier would reject as forgery — the
    /// emitter⊆admitted half of the K8 reachability invariant is held
    /// by the type rather than by review.
    pub entity_type: Option<EntityType>,

    /// `admin` — issue-time admin gate flag (M44). When `true`, the
    /// verifier additionally requires `active_ppnum` (or `sub` band
    /// fallback) to fall in an admin-allocated band — defense in depth
    /// against forged tokens with a stolen signing key.
    pub admin: bool,

    /// `caps` — capability list (M41). Default `[]` is the default-deny
    /// surface contract: a token with no capabilities cannot perform any
    /// privileged operation. Engine validates only that the wire shape
    /// is an array of strings; semantic enforcement is per-surface.
    pub caps: Vec<String>,

    /// `act` (RFC 8693 §4.1) — the acting party, set on tokens minted via
    /// Token Exchange flows to record who is driving this session. Audit
    /// logs key off it, and it is half of the delegation predicate
    /// (`entity_type == Human && act.is_some()`).
    ///
    /// Chain depth is the nesting depth — there is no separate depth
    /// claim to keep in step with it, and the engine bounds that nesting
    /// (M43) on verify.
    pub act: Option<Act>,

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

    /// `sv` — per-account `session_version` epoch snapshot. Validators
    /// compare `token.sv >= cached(sv:{sub})` and reject stale tokens; the
    /// counter (on `ppnums.session_version`) bumps inside a revocation TX
    /// (break-glass / LogoutAll / agent disconnect), invalidating all prior
    /// tokens within the consumer cache TTL. Carried by Human session
    /// tokens AND by AI-agent client_credentials tokens minted via PAS's
    /// `AgentService.IssueToken` (the AI-agent kill-switch). Absent on
    /// Token-Exchange (delegated / exchange) tokens — deferred slices — so
    /// the engine `check_epoch` gate short-circuits for those.
    pub sv: Option<u64>,

    /// `active_ppnum` — display ppnum (e.g. `123-1234-5678`). UI surfaces
    /// render this; `sub` is the immutable ULID and is the authorization
    /// axis. Absent on tokens that don't represent a human-facing
    /// session (raw machine tokens).
    pub active_ppnum: Option<String>,

    /// `scopes` — OAuth scope list (M42). Engine bounds the array to ≤ 256
    /// entries (RFC 8725-adjacent — bound the per-token audit surface).
    /// Default `[]` is "no externally-granted scope"; 1st-party flows
    /// emit a non-empty list (`profile`, `email`, etc).
    pub scopes: Vec<String>,

    /// `sid` — the issuer's session identifier (M36, Phase 5). When set,
    /// the verifier's `cfg.session_revocation::is_active(sub, sid)` query
    /// gates token admission against that session's liveness — deletion
    /// = revocation per STS_JWT_DETAILS_MITIGATION §E. PAS issuance sets
    /// this to the refresh-token `family_id` on every 1st-party session
    /// path; AI-agent / machine / OAuth flows leave it unset and the
    /// verifier short-circuits the gate. Wire shape: ULID string when
    /// present.
    pub sid: Option<String>,
}

impl IssueRequest {
    /// Construct a new request with the required fields. Domain claim
    /// fields default to "absent / empty / 0 / false" — every emission
    /// is opt-in via a `with_*` builder, so a caller who forgets to set
    /// `admin` cannot accidentally mint an admin token.
    pub fn new(sub: impl Into<String>, client_id: impl Into<String>, ttl: Duration) -> Self {
        Self {
            sub: sub.into(),
            client_id: client_id.into(),
            ttl,
            jti: None,
            entity_type: None,
            admin: false,
            caps: Vec::new(),
            act: None,
            cid: None,
            sv: None,
            active_ppnum: None,
            scopes: Vec::new(),
            sid: None,
        }
    }

    /// Pin a specific `jti` instead of letting the engine generate one.
    /// Test-only escape hatch — production paths should never override.
    #[must_use]
    pub fn with_jti(mut self, jti: Ulid) -> Self {
        self.jti = Some(jti);
        self
    }

    /// Set `entity_type` (M40).
    ///
    /// Takes [`EntityType`], not a string: the verifier rejects any
    /// value outside the whitelist as forgery, so a mint site that
    /// could name one would be building a token this crate refuses.
    /// Callers holding a wider domain enum (PAS's 5-value
    /// `ppnums.entity_type`) must map it explicitly and decide what to
    /// do with the values that have no credential flow — the compiler
    /// will not let that mapping be silently total.
    #[must_use]
    pub fn with_entity_type(mut self, entity_type: EntityType) -> Self {
        self.entity_type = Some(entity_type);
        self
    }

    /// Set the admin gate flag (M44). Combined with `active_ppnum` band
    /// check on the verify side, this is the issue-time half of the
    /// admin-token defense in depth.
    #[must_use]
    pub fn with_admin(mut self, admin: bool) -> Self {
        self.admin = admin;
        self
    }

    /// Set the capability list (M41). An empty list (the default) means
    /// no privileged capabilities; surface code MUST positive-check.
    #[must_use]
    pub fn with_caps(mut self, caps: Vec<String>) -> Self {
        self.caps = caps;
        self
    }

    /// Set the acting party (`act`, RFC 8693 §4.1). Token Exchange flows
    /// record here who is driving the session.
    ///
    /// Takes [`Act`] rather than a bare identifier so a mint site cannot
    /// express "delegation happened" without naming the actor — the two
    /// were separable while the claim was a flat string plus a depth
    /// counter, and that separability is what made the chain length
    /// forgeable.
    #[must_use]
    pub fn with_act(mut self, act: Act) -> Self {
        self.act = Some(act);
        self
    }

    /// Set the WebAuthn credential id (`cid`). Call this only on the
    /// passkey issuance path; other paths MUST leave it unset so audit
    /// logs distinguish authentication methods without a per-row lookup.
    #[must_use]
    pub fn with_credential_id(mut self, credential_id: impl Into<String>) -> Self {
        self.cid = Some(credential_id.into());
        self
    }

    /// Set the per-account `session_version` epoch snapshot. Called by the
    /// Human session path and by PAS's `AgentService.IssueToken` (ai_agent
    /// client_credentials), reading `ppnums.session_version`. Token-Exchange
    /// (delegated / exchange) paths leave it unset — deferred slices — and
    /// the verifier's `check_epoch` gate short-circuits on absent `sv`.
    #[must_use]
    pub fn with_session_version(mut self, sv: u64) -> Self {
        self.sv = Some(sv);
        self
    }

    /// Set the display ppnum (`active_ppnum`). UI surfaces render this;
    /// `sub` remains the immutable ULID for authorization decisions.
    #[must_use]
    pub fn with_active_ppnum(mut self, active_ppnum: impl Into<String>) -> Self {
        self.active_ppnum = Some(active_ppnum.into());
        self
    }

    /// Set the OAuth scope list (M42). Engine bounds the array to ≤ 256
    /// entries on the verify side.
    #[must_use]
    pub fn with_scopes(mut self, scopes: Vec<String>) -> Self {
        self.scopes = scopes;
        self
    }

    /// Set the issuer's session id (`sid` claim, M36 — Phase 5). Call
    /// this only on issuance paths bound to a session (in PAS: the
    /// 1st-party Human paths that own a refresh-token family — CLI
    /// handoff / magic-link / passkey / refresh-cycle, where the value
    /// is that `family_id`); AI-agent, machine and OAuth paths MUST
    /// leave it unset so the verifier short-circuits the
    /// session-revocation gate. The verifier compares `(sub, sid)`
    /// against the substrate; deletion = revocation per
    /// STS_JWT_DETAILS_MITIGATION §E.
    #[must_use]
    pub fn with_sid(mut self, sid: impl Into<String>) -> Self {
        self.sid = Some(sid.into());
        self
    }
}