Crate ppoppo_sdk_core 

NOT a stable public API. Engine-tier substrate of the ppoppo SDK family — 3rd parties depend on the crates/sdk products (pas-external, pas-plims, pcs-external), which re-export everything integrations need; this crate’s surface moves with the family, semver-coordinated across it, and is never promised on its own.

Ppoppo SDK shared primitives — internal mechanism for the Ppoppo SDK family (pas-external, future pas-plims, pcs-external).

Stability — not a stable public API

This crate is published to crates.io as a transitive dependency of the SDK family above (cargo enforces “all transitive deps of a published crate must themselves be published”). It is not a stable public API; it carries no SemVer guarantees beyond the current minor and may rearrange shapes between minors. Consume the SDK crates that re-export from it (pas-external::*, eventually pas-plims::* / pcs-external::*); do not depend on ppoppo-sdk-core directly from a 3rd-party application.

Phase A foundation (RFC RFC_2026-05-08_app-credential-collapse.md) — collapses the verifier port + audit trait + session-liveness port + discovery primitive + perimeter Bearer-auth Layer kit + identity types out of pas-external so multiple SDK crates and 1st-party services (chat-auth, chat-api) all consume the same primitives.

Surface (Slice 1a)

• error::SdkCoreError — narrow error type for sdk-core primitives.
• types::{Ppnum, PpnumId, SessionId, UserId, KeyId} — SDK-shared identity types. Ppnum::TryFrom<String> is the validated boundary.
• audit::* — AuditSink trait + AuditEvent + VerifyErrorKind + IdTokenFailureKind + RateLimiter trait + RateLimitKey + compose_source_id + compose_id_token_source_id. Plus the in-tree utility impls (NoopAuditSink, MemoryAuditSink, MemoryRateLimiter, RateLimitedAuditSink) — utility impls live here too because the audit module is one cohesive unit.
• session_liveness::{SessionLiveness, SessionLivenessError} — per-request L2 row liveness port. Wired into the verifier slot. Trait-only (no cipher/liveness AES wrapper code — that stays in pas-external as a feature-gated submodule).

Surface (Slice 1b — populated when verifier cohesive group lands)

• verifier::* — BearerVerifier trait + JwtVerifier impl + MemoryBearerVerifier + VerifiedClaims + VerifyConfig + VerifyError + JwksCache. Audit decision E (cohesive group — no trait/impl split across crates).

Surface (Slice 2 — populated)

• discovery::{Discovery, DiscoveryError, fetch_discovery} — OIDC discovery document fetch (<issuer>/.well-known/openid-configuration). RFC 8414 §3.3 issuer-mismatch defense lives here. Gated on well-known-fetch (HTTP fetch + URL types).

Surface (Slice 4 — populated)

• bearer::* — perimeter Bearer-auth Layer kit. AuthProvider<S> port + BearerAuthLayer<Sess, P> tower::Layer + BearerAuthConfig + VerifyError + MemoryAuthProvider<S> (test-support). Gated on axum feature. 1st-party services (chat-auth) import direct from ppoppo_sdk_core::bearer::* (audit decision B); 3rd-party consumers (RCW/CTW) reach the same kit through pas_external::bearer::* re-export (audit decision D).

Surface (Phase E — populated)

• token_cache::{TokenCache, TokenCacheConfig, TokenSource, TokenCacheError, ClientCredentialsSource} — JWT retention layer with single-flight refresh. TokenCache owns a Box<dyn TokenSource>; the built-in ClientCredentialsSource covers the OAuth2 client_credentials grant. Gated on token-cache (cache+trait) and client-credentials (HTTP source).
• interceptor::{AuthInterceptor, BearerCredential} — tonic sync Interceptor that attaches Authorization: Bearer <token> per outgoing gRPC call. Constructed from a pre-fetched BearerCredential (one instance per call). Gated on tonic-interceptor.
• retry::retry_after — extract retry-after integer-seconds hint from a tonic::Status’s metadata. Counterpart of chat-api’s resource_exhausted_with_retry_after producer. Gated on tonic-interceptor (shares the tonic dep — no extra transitive weight for crates that already enable the interceptor). RFC 2026-05-12 D5.
• grpc::{PathPrefixChannel, Error, classify_status} — the two remaining gRPC-client legs shared by the gRPC SDK family (pas-plims, pcs-external): the GKE Ingress path-prefix channel + the shared Status→Error classifier (the family retry taxonomy, one home). Both SDKs re-export grpc::Error as their public error type. Gated on grpc-client (adds tonic transport/TLS + http + tower-service on top of the interceptor/token-cache/retry legs). Reached via the grpc:: path — grpc::Error is deliberately NOT flat-re-exported: a root-level Error would misread as sdk-core’s own error::SdkCoreError (a semantic-clarity choice — the names differ, so not a real clash; same module-path convention as bearer/verifier).

Surface (scope contract — populated)

• scopes::{ConsentScopes, ScopedTokenSource} — the SDK family’s OAuth2 scope-request contract. ConsentScopes is the open parent of each face SDK’s own sealed scope-set family (pcs_session’s PcsSessionScopeSet, etc.), naming the atoms a marker requests at consent so the crate running the authorization leg can read a marker owned by a crate it does not depend on. Executes the slot this list previously reserved as “sealed-trait family parent”; it ships open, the only workable reading — a sealed parent could not be implemented by any SDK, and sealing the children is unaffected either way. ConsentScopes is unconditional (both consumers reach it with default-features = false); ScopedTokenSource is gated on token-cache, the feature owning its TokenSource supertrait. Reached by module path — see the flat-re-export budget below.

Re-exports

pub use error::SdkCoreError;

pub use types::KeyId;

pub use types::Ppnum;

pub use types::PpnumId;

pub use types::SessionId;

pub use types::UserId;

pub use session_liveness::SessionLiveness;

pub use session_liveness::SessionLivenessError;

pub use audit::AuditEvent;

pub use audit::AuditSink;

pub use audit::IdTokenFailureKind;

pub use audit::MemoryRateLimiter;

pub use audit::NoopAuditSink;

pub use audit::RateLimitKey;

pub use audit::RateLimitedAuditSink;

pub use audit::RateLimiter;

pub use audit::VerifyErrorKind;

pub use audit::compose_id_token_source_id;

pub use audit::compose_source_id;

pub use audit::MemoryAuditSink;

pub use verifier::BearerVerifier;

pub use verifier::VerifiedClaims;

pub use verifier::VerifyConfig;

pub use verifier::VerifyError;

pub use verifier::JwksCache;

pub use verifier::JwtVerifier;

pub use verifier::MemoryBearerVerifier;

pub use discovery::Discovery;

pub use discovery::DiscoveryError;

pub use discovery::fetch_discovery;

Modules

audit

M48 + M49 — verify-failure audit emission port + per-source rate limiter (RFC_2026-05-04_jwt-full-adoption Phase 9).

bearer

Edge authentication layer — the SDK’s perimeter for Bearer-token authenticated HTTP traffic.

discovery

OIDC discovery primitive — fetches <issuer>/.well-known/openid-configuration.

error

sdk-core’s local error type.

grpc

The gRPC-client mechanical arc shared by the Ppoppo gRPC SDK family (pas-plims, pcs-external).

interceptor

Tonic request interceptor that attaches Authorization: Bearer <token> to every outgoing gRPC call.

retry

retry-after metadata extraction for tonic gRPC responses.

scopes

The SDK family’s OAuth2 scope-request contract.

session_liveness

SessionLiveness port — per-request session-row liveness check.

token_cache

JWT/token retention layer for Ppoppo client SDKs.

types

verifier

γ port-and-adapter SDK boundary for bearer-token verification.