pas_external/

lib.rs

#![doc = include_str!("../README.md")]

pub mod audit;
// Clock port re-export — External Developer consumers can use
// `pas_external::clock::ArcClock` / `pas_external::clock::FrozenClock`
// without a separate `ppoppo-clock` dep in their Cargo.toml.
pub mod clock {
    pub use ::ppoppo_clock::*;
}
// Perimeter Bearer-auth Layer kit — Phase A Slice 4 lifted the kit to
// `ppoppo_sdk_core::bearer::*`. pas-external 0.11.0 re-exports the
// kit at `pas_external::bearer::*` (audit decision D — 1-level
// role-named module, no `oidc::axum::*` nesting) for 3rd-party
// consumers (RCW/CTW). 1st-party services (chat-auth) import direct
// from sdk-core (audit decision B). The framework-dep visibility
// (axum / tower) is signalled by the `axum` feature gate, not by a
// nested `pas_external::oidc::axum::*` namespace.
#[cfg(feature = "axum")]
pub mod bearer {
    pub use ::ppoppo_sdk_core::bearer::*;
}
// `epoch` re-exports the engine `EpochRevocation` port + ships the
// canonical adapter set (Phase 11.Z, RFC_2026-05-09 §3.5). Gated on
// `well-known-fetch` because the engine port itself needs `token` and
// the original `UserinfoFetcher` (deleted in 0.10.0) required the HTTP
// client (`oauth`) — both implied by the `well-known-fetch` flag.
// `SharedCacheCache` (0.10.0, RFC_2026-05-08 §4.1) requires the
// additional `shared-cache` feature for the `ppoppo-infra` adapter dep.
#[cfg(feature = "well-known-fetch")]
pub mod epoch;
pub mod error;
// `oauth` is two-tiered: the `TokenResponse` wire DTO compiles at the
// `oauth` tier (consumed by `pas_port` / `session_liveness`), while the
// `OAuthConfig` + `AuthClient` HTTP adapter is gated inside the module on
// `well-known-fetch` — the tier of its sole constructor,
// `oidc::RelyingParty::new`. As of 0.8.0 the module is `pub(crate)`:
// consumers reach the OIDC RP composition root (`oidc::RelyingParty<S>`)
// and never the raw OAuth surface. See `oidc::RefreshOutcome` for the
// boundary type at `RelyingParty::refresh`.
#[cfg(feature = "oauth")]
pub(crate) mod oauth;
#[cfg(feature = "token")]
pub mod oidc;
// Native-app OAuth composition root (RFC 8252) — the non-OIDC sibling of
// `oidc::RelyingParty<S>`. Separate rather than a relaxation: the RP is
// welded to OIDC in three places (an `openid` scope marker, an
// unconditional `nonce`, a verified id_token) and a native resource client
// breaks all three. See the module docs.
#[cfg(feature = "native")]
pub mod native;
#[cfg(feature = "oauth")]
pub mod pas_port;
// Renewing `TokenSource` (G3 / RTR) — `RefreshTokenSource` + `TokenStore`.
// For native / CLI clients (CNC) that hold a durable refresh token and feed a
// `ppoppo_sdk_core::TokenCache`; depends on the `PasAuthPort` port (`oauth`)
// and sdk-core's `token-cache` (the `TokenSource` trait it implements).
#[cfg(feature = "refresh-source")]
pub mod refresh_source;
// `pkce` primitives (`generate_state`, `generate_code_verifier`,
// `generate_code_challenge`) are SDK plumbing — `oidc::RelyingParty::start`
// is the sole consumer, so the module is gated on `well-known-fetch`
// (the RP's tier) rather than the lower `oauth` tier, which would orphan
// it under the default feature set. `pub(crate)` since 0.8.0.
#[cfg(feature = "well-known-fetch")]
pub(crate) mod pkce;
// Granted-vs-requested scope validation (RFC 6749 §5.1). Ungated and
// dependency-free — it reads only a `&str` echo and a `ConsentScopes`
// marker, and every leg that receives a token response uses the same
// function, so the RFC's absence-and-containment semantics are decided in
// exactly one place.
pub mod scope_grant;
// `session_liveness` is intentionally ungated at module level — the
// 0.10.0 `SessionLiveness` port has no AES / OAuth deps and ships
// regardless of feature configuration so the verifier slot
// (`PasJwtVerifier::with_session_liveness`) can reference it under
// just `feature = "well-known-fetch"`. Internal sub-modules
// (`cipher`, `liveness`) remain gated on `feature = "session-liveness"`
// for the AES wrapper + PAS refresh-token check.
pub mod session_liveness;
pub mod types;

// Test-support helpers. `FakePasServer` is the SDK-owned wiremock-wrapped
// fake PAS Authorization Server, replacing the 0.7.x
// `RelyingParty::for_test_with_parts` escape hatch. Consumer integration
// tests construct a real `RelyingParty::new(...)` against
// `FakePasServer.issuer_url()` so production and test go through the same
// public interface.
#[cfg(feature = "test-support")]
pub mod test_support;

// Re-exports for convenient access
pub use audit::{
    AuditEvent, AuditSink, IdTokenFailureKind, MemoryRateLimiter, NoopAuditSink, RateLimitKey,
    RateLimitedAuditSink, RateLimiter, VerifyErrorKind, compose_id_token_source_id,
    compose_source_id,
};
#[cfg(any(test, feature = "test-support"))]
pub use audit::MemoryAuditSink;
pub use error::{Error, TokenError};
// 0.10.0 — ungated L2 verifier-slot port (RFC_2026-05-08 §4.2 lock).
pub use session_liveness::{SessionLiveness, SessionLivenessError};
#[cfg(feature = "session-liveness")]
pub use session_liveness::{
    CipherError, EncryptedRefreshToken, LivenessFailure, LivenessOutcome, RevokeCause,
    TokenCipher, TransientCause, attempt_liveness_refresh,
};
// γ port-and-adapter — Phase 6.1 (D-04 = γ, locked 2026-05-05).
// Phase A (RFC `RFC_2026-05-08_app-credential-collapse.md`, audit
// decisions E + G) lifted the cohesive verifier group to
// `ppoppo_sdk_core::verifier::*`. pas-external re-exports at top level
// (no `token::` namespace — audit decision E) so consumer code
// reaches `pas_external::{BearerVerifier, JwtVerifier, ...}`. Renames:
// `PasJwtVerifier` → `JwtVerifier`; `Expectations` → `VerifyConfig`;
// `AuthSession` → `VerifiedClaims`. The `crypto-side` `VerifyError`
// re-exports as `TokenVerifyError` (BREAKING) to make space for the
// Layer-side `VerifyError` from `pas_external::bearer::*` (Slice 4
// migration). Phase A 0.11.0 ships clean — no transitional alias.
#[cfg(feature = "token")]
pub use ::ppoppo_sdk_core::verifier::{
    BearerVerifier, VerifiedClaims, VerifyConfig, VerifyError as TokenVerifyError,
};
#[cfg(feature = "well-known-fetch")]
pub use ::ppoppo_sdk_core::verifier::{EpochEnforcement, JwksCache, JwtVerifier};
#[cfg(all(feature = "token", any(test, feature = "test-support")))]
pub use ::ppoppo_sdk_core::verifier::MemoryBearerVerifier;
// OIDC RP surface — composition root + post-verify shapes + ports.
// `RelyingParty<S>` is the consumer-facing entry point; `RefreshOutcome`
// is the typed boundary return for `RelyingParty::refresh` (replaces
// the 0.7.x `oauth::TokenResponse` re-export).
#[cfg(feature = "token")]
pub use oidc::{Address, IdAssertion, IdTokenVerifier, IdVerifyError, Nonce, ScopePiiReader};
#[cfg(all(feature = "token", any(test, feature = "test-support")))]
pub use oidc::MemoryIdTokenVerifier;
pub use types::{KeyId, Ppnum, PpnumId, SessionId, UserId};
// The SDK-family scope contract. Re-exported (facade rule: every type in a
// public signature is reachable from this crate's root) because
// `NativeAuthFlow<S: ConsentScopes>` and the sources it yields put both
// names on the public surface. A 3rd party must never have to name the
// engine crate — `pcs-session` re-exports the same two, so an integration
// spells `pcs_session::scopes::Notify` and nothing else.
pub use ::ppoppo_sdk_core::scopes::ConsentScopes;
#[cfg(feature = "refresh-source")]
pub use ::ppoppo_sdk_core::scopes::ScopedTokenSource;
pub use scope_grant::{ScopeNotCovered, ensure_covers};
// Native-app OAuth surface (RFC 8252).
#[cfg(feature = "native")]
pub use native::{CallbackError, NativeAuthFlow, NativeAuthInitError, NativeConfig};
// `AuthClient` — nameable, deliberately NOT constructible.
//
// It appears as a generic argument in what `NativeAuthFlow::{complete,
// token_source}` return (`RefreshTokenSource<AuthClient, T, S>`), and a native
// app holds that source in its application state — which means writing the
// type down. Without this re-export the signature names a `pub(crate)`
// internal and the surface is unusable from outside, while the crate still
// compiles cleanly: `private_interfaces` does not fire on a private type in
// generic-argument position. `tests/native_auth_flow_boundary.rs` names the
// type from outside precisely because no lint will.
//
// Constructing one still requires `OAuthConfig`, which stays unexported — so
// 0.8.0's decision (consumers reach OAuth through a composition root, never
// the raw client) is intact. Nameable is not the same as constructible, and
// only the first is needed here.
#[cfg(feature = "well-known-fetch")]
pub use oauth::AuthClient;

// Renewing TokenSource (G3 / RTR).
#[cfg(feature = "refresh-source")]
pub use refresh_source::{MemoryTokenStore, RefreshTokenSource, TokenStore, TokenStoreError};
// `Url` is consumer-facing via `Config::new(client_id, redirect_uri: Url, ...)`
// and `Discovery::for_test`. Re-exported so consumers reach the same `url`
// crate version the SDK uses without separately tracking it in their
// Cargo.toml.
#[cfg(feature = "oauth")]
pub use url::Url;