@web-ts-toolkit/express-oidc-vault 0.51.0 → 0.52.0

package/index.d.mts

@@ -1,6 +1,8 @@
 import { Request, Response, RequestHandler, Router } from 'express';
 import { KeyObject } from 'node:crypto';
 import { JWK } from 'jose';
+import { OidcVaultUserProfile, OidcVaultTokenIssueResult, OidcVaultSessionTransport } from './wire.mjs';
+export { OidcVaultExchangeResult, OidcVaultLoginInitiationInput, OidcVaultLoginInitiationResult, OidcVaultLogoutResult } from './wire.mjs';
 
 type OidcVaultRouteName = 'login' | 'callback' | 'exchange' | 'refresh' | 'logout' | 'backchannel-logout';
 /** Enabling the option defaults to `optional`; omitting it keeps bearer behavior. */
@@ -114,13 +116,6 @@ interface OidcVaultApiDeviceBindingOptions extends OidcVaultDeviceBindingOptions
     /** Epoch-millisecond clock for proof age/nonce/replay; default Date.now. Shared instances need synchronized clocks. */
     now?: () => number;
 }
-interface OidcVaultUserProfile {
-    sub: string;
-    email?: string;
-    name?: string;
-    preferredUsername?: string;
-    [key: string]: unknown;
-}
 /**
  * Stored session identity. Exchange, refresh, and logout compare each defined
  * field verbatim against resolved middleware config before use. Opt-in/guarded
@@ -515,19 +510,6 @@ interface IssueTokenInput {
      */
     deviceBinding?: Readonly<OidcVaultVerifiedDpopBinding>;
 }
-/**
- * Local application credentials returned by `OidcVaultTokenIssuer.issue`.
- * Runtime validation copies only these fields into a fresh result; additional
- * properties are ignored and cannot override the response's session ID/user.
- */
-interface OidcVaultTokenIssueResult {
-    /** Nonempty opaque token for unbound issuance; bound issuance requires a compact signed JWT with matching `cnf.jkt`. */
-    accessToken: string;
-    /** Token lifetime in seconds: a finite, nonnegative safe integer (zero is valid). */
-    expiresIn: number;
-    /** Exact `DPoP` is required when bound. Unbound permits only `Bearer` or omission; omitted/undefined stays absent in JSON. */
-    tokenType?: 'Bearer' | 'DPoP';
-}
 /**
  * Trusted application token issuer for exchange and refresh. Return a non-null,
  * non-array object satisfying `OidcVaultTokenIssueResult`; only its declared
@@ -554,7 +536,7 @@ interface OidcVaultAccessTokenValidationResult {
     /** Verified sender constraint. Legacy adapters may omit it only for genuinely unbound credentials. */
     confirmation?: OidcVaultAccessTokenConfirmation | null;
 }
-/** Canonical RFC 7638 SHA-256 thumbprint derived from verified token/introspection data, never from a proof alone. */
+/** Exact one-field confirmation: canonical RFC 7638 SHA-256 thumbprint from verified token/introspection data, never from a proof alone. */
 interface OidcVaultAccessTokenConfirmation {
     jkt: string;
 }
@@ -628,13 +610,18 @@ interface OidcVaultAccessTokenMiddlewareOptions {
 interface OidcVaultAuthenticatedRequest extends Request {
     auth?: OidcVaultAuthContext;
 }
-/** Local JWT verification options, independent of the asymmetric DPoP proof policy; captured at construction. */
+/**
+ * Local JWT verification options, independent of the asymmetric DPoP proof
+ * policy; captured at construction. JWTs with cnf require the supported exact
+ * jkt profile and a nonnegative safe-integer exp with safe milliseconds in both
+ * validator methods. Unbound JWTs retain JOSE's optional-exp behavior.
+ */
 interface OidcVaultJwtAccessTokenValidatorOptions {
     key: CryptoKey | KeyObject | JWK | Uint8Array;
     issuer?: string;
     audience?: string | string[];
     algorithms?: string[];
-    /** Verified cnf is snapshotted before this mapper; mapper-supplied confirmation/deviceBinding is ignored. */
+    /** JOSE verification and bound-JWT profile/expiry checks precede this mapper. Original cnf is snapshotted; mapper-supplied confirmation/deviceBinding is ignored. */
     mapClaims?(claims: Record<string, unknown>): OidcVaultAccessTokenValidationResult;
 }
 declare module 'express-serve-static-core' {
@@ -666,50 +653,10 @@ interface OidcVaultConfig {
     clientSecret?: string;
     scopes?: string;
 }
-interface OidcVaultLogoutResult {
-    /**
-     * Successful logout commits revocation before upstream work and clears the
-     * session cookie under cookie transport. Built-in live handles and unexpired
-     * aliases authenticate the surviving lineage's provider/original binding;
-     * wrong identity, missing/wrong/stale/replayed proof, or disabled acceptance
-     * of a bound lineage fails without deleting or clearing. No currently live
-     * target is idempotent success without deletion or proof reservation. Aliases
-     * grant revocation only, not refresh authentication or upstream redirects.
-     * Old custom bearer stores without revocation context retain legacy alias
-     * deletion behavior. Stateless application access tokens are not invalidated.
-     * Local-only logout (`redirect` unset or `false`) never contacts the provider.
-     * Redirected logout (`redirect: true`)
-     * treats the upstream end-session redirect as best-effort: when provider
-     * discovery fails or no `endSessionEndpoint` is available, the route still
-     * returns this local success. Discovery errors reach `onError` without
-     * undoing revocation or skipping the live session's `onLogout` notification.
-     */
-    loggedOut: true;
-}
 interface OidcVaultBackchannelLogoutResult {
     loggedOut: true;
     revokedSessions: number;
 }
-interface OidcVaultExchangeResult extends Partial<OidcVaultTokenIssueResult> {
-    /** Authoritative vault handle in body transport; omitted from cookie-transport JSON. */
-    sessionId?: string;
-    /** Session profile; extra token-issuer result properties cannot override it. */
-    user?: OidcVaultUserProfile;
-}
-/** JSON body for opt-in `POST <basePath>/login`; proof/key and recognition signals belong in their configured headers, not the body. */
-interface OidcVaultLoginInitiationInput {
-    /** Optional destination on the configured frontend origin. Query-string returnTo is ignored by POST login. */
-    returnTo?: string;
-}
-/**
- * Exact successful POST-login JSON. Navigate to this URL after storing a proof
- * key when DPoP is enabled. Use credentials: 'include' even with body session
- * transport: initiation sets a temporary HttpOnly transaction cookie.
- */
-interface OidcVaultLoginInitiationResult {
-    authorizationUrl: string;
-}
-type OidcVaultSessionTransport = 'body' | 'cookie';
 type OidcVaultCookieDeploymentMode = 'same-origin' | 'same-site' | 'cross-site';
 type OidcVaultCookieSameSite = 'lax' | 'strict' | 'none';
 /**
@@ -971,6 +918,10 @@ declare function createOidcVaultAccessTokenMiddleware(options: OidcVaultAccessTo
  * the sender constraint. The request-aware result always has confirmation
  * (null only for genuinely unbound JWTs). Legacy unbound results omit it;
  * bound results report it so binding-disabled vault middleware refuses downgrade.
+ * Bound JWTs additionally require canonical compact encoding and a nonnegative
+ * safe-integer exp with safe milliseconds, checked before mapClaims in both
+ * methods. JOSE verifies signature/expiry and configured issuer/audience first. Unbound
+ * JWTs retain JOSE's generic optional-exp contract.
  * Proof/target/ath/nonce/replay enforcement belongs to the API middleware.
  * Construction captures options and copies secret/JWK/allowlist containers.
  */
@@ -1017,4 +968,4 @@ declare function normalizeOidcVaultBasePath(value?: string): string;
  */
 declare function createOidcVaultMiddleware(options: OidcVaultOptions): Router;
 
-export { type AuthorizationTransaction, type AuthorizationTransactionInput, type ConsumeAuthorizationTransactionIfMatchesInput, type ConsumeBackchannelLogoutTokenJtiInput, type ConsumeExchangeCodeIfMatchesInput, DEFAULT_AUTHORIZATION_TRANSACTION_TTL_MS, DEFAULT_EXCHANGE_CODE_TTL_MS, DEFAULT_OIDC_SCOPES, DEFAULT_OIDC_VAULT_BASE_PATH, DEFAULT_OIDC_VAULT_REQUEST_BODY_LIMIT, type DeleteSessionsByLogicalSessionIdInput, type DeleteSessionsByProviderSessionIdInput, type DeleteSessionsBySubjectInput, type ExchangeCodeRecord, type ExchangeCodeRecordInput, type IssueTokenInput, OIDC_VAULT_ROUTE_PATHS, OIDC_VAULT_URL_ENCODED_PARAMETER_LIMIT, type OidcVaultAccessTokenConfirmation, type OidcVaultAccessTokenMiddlewareErrorContext, type OidcVaultAccessTokenMiddlewareOptions, type OidcVaultAccessTokenRequestInput, type OidcVaultAccessTokenValidationResult, type OidcVaultAccessTokenValidator, type OidcVaultApiDeviceBindingOptions, type OidcVaultAuthContext, type OidcVaultAuthenticatedRequest, type OidcVaultBackchannelLogoutResult, type OidcVaultConfig, type OidcVaultConfigMode, type OidcVaultCookieDeploymentMode, type OidcVaultCookieOptions, type OidcVaultCookieSameSite, type OidcVaultDeviceBindingMode, type OidcVaultDeviceBindingOptions, type OidcVaultDeviceBindingStoreProvider, type OidcVaultDpopAlgorithm, type OidcVaultDpopBinding, type OidcVaultDpopNonceOptions, type OidcVaultDpopProofOptions, OidcVaultDpopReplayCapacityError, type OidcVaultDpopReplayStore, type OidcVaultEnv, type OidcVaultErrorContext, type OidcVaultExchangeResult, type OidcVaultFingerprintRecognitionOptions, type OidcVaultHookContext, type OidcVaultHooks, type OidcVaultJwtAccessTokenValidatorOptions, type OidcVaultLoginInitiationInput, type OidcVaultLoginInitiationResult, type OidcVaultLogoutResult, type OidcVaultOptions, type OidcVaultProviderMetadata, type OidcVaultRecordBindingMatch, type OidcVaultRequestAwareAccessTokenValidationResult, type OidcVaultRequestAwareAccessTokenValidator, type OidcVaultResolvedConfig, type OidcVaultRouteName, type OidcVaultSession, type OidcVaultSessionInput, type OidcVaultSessionRevocationContext, type OidcVaultSessionTransport, OidcVaultStoreConflictError, type OidcVaultStoreProvider, type OidcVaultTokenIssueResult, type OidcVaultTokenIssuer, type OidcVaultTransactionCookieOptions, type OidcVaultUserProfile, type OidcVaultVerifiedDpopBinding, type ReserveDpopProofInput, type RotateSessionInput, createOidcVaultAccessTokenMiddleware, createOidcVaultJwtAccessTokenValidator, createOidcVaultMiddleware, normalizeOidcVaultBasePath, resolveOidcVaultConfig, resolveOidcVaultConfigFromEnv };
+export { type AuthorizationTransaction, type AuthorizationTransactionInput, type ConsumeAuthorizationTransactionIfMatchesInput, type ConsumeBackchannelLogoutTokenJtiInput, type ConsumeExchangeCodeIfMatchesInput, DEFAULT_AUTHORIZATION_TRANSACTION_TTL_MS, DEFAULT_EXCHANGE_CODE_TTL_MS, DEFAULT_OIDC_SCOPES, DEFAULT_OIDC_VAULT_BASE_PATH, DEFAULT_OIDC_VAULT_REQUEST_BODY_LIMIT, type DeleteSessionsByLogicalSessionIdInput, type DeleteSessionsByProviderSessionIdInput, type DeleteSessionsBySubjectInput, type ExchangeCodeRecord, type ExchangeCodeRecordInput, type IssueTokenInput, OIDC_VAULT_ROUTE_PATHS, OIDC_VAULT_URL_ENCODED_PARAMETER_LIMIT, type OidcVaultAccessTokenConfirmation, type OidcVaultAccessTokenMiddlewareErrorContext, type OidcVaultAccessTokenMiddlewareOptions, type OidcVaultAccessTokenRequestInput, type OidcVaultAccessTokenValidationResult, type OidcVaultAccessTokenValidator, type OidcVaultApiDeviceBindingOptions, type OidcVaultAuthContext, type OidcVaultAuthenticatedRequest, type OidcVaultBackchannelLogoutResult, type OidcVaultConfig, type OidcVaultConfigMode, type OidcVaultCookieDeploymentMode, type OidcVaultCookieOptions, type OidcVaultCookieSameSite, type OidcVaultDeviceBindingMode, type OidcVaultDeviceBindingOptions, type OidcVaultDeviceBindingStoreProvider, type OidcVaultDpopAlgorithm, type OidcVaultDpopBinding, type OidcVaultDpopNonceOptions, type OidcVaultDpopProofOptions, OidcVaultDpopReplayCapacityError, type OidcVaultDpopReplayStore, type OidcVaultEnv, type OidcVaultErrorContext, type OidcVaultFingerprintRecognitionOptions, type OidcVaultHookContext, type OidcVaultHooks, type OidcVaultJwtAccessTokenValidatorOptions, type OidcVaultOptions, type OidcVaultProviderMetadata, type OidcVaultRecordBindingMatch, type OidcVaultRequestAwareAccessTokenValidationResult, type OidcVaultRequestAwareAccessTokenValidator, type OidcVaultResolvedConfig, type OidcVaultRouteName, type OidcVaultSession, type OidcVaultSessionInput, type OidcVaultSessionRevocationContext, OidcVaultSessionTransport, OidcVaultStoreConflictError, type OidcVaultStoreProvider, OidcVaultTokenIssueResult, type OidcVaultTokenIssuer, type OidcVaultTransactionCookieOptions, OidcVaultUserProfile, type OidcVaultVerifiedDpopBinding, type ReserveDpopProofInput, type RotateSessionInput, createOidcVaultAccessTokenMiddleware, createOidcVaultJwtAccessTokenValidator, createOidcVaultMiddleware, normalizeOidcVaultBasePath, resolveOidcVaultConfig, resolveOidcVaultConfigFromEnv };

package/index.d.ts

@@ -1,6 +1,8 @@
 import { Request, Response, RequestHandler, Router } from 'express';
 import { KeyObject } from 'node:crypto';
 import { JWK } from 'jose';
+import { OidcVaultUserProfile, OidcVaultTokenIssueResult, OidcVaultSessionTransport } from './wire.js';
+export { OidcVaultExchangeResult, OidcVaultLoginInitiationInput, OidcVaultLoginInitiationResult, OidcVaultLogoutResult } from './wire.js';
 
 type OidcVaultRouteName = 'login' | 'callback' | 'exchange' | 'refresh' | 'logout' | 'backchannel-logout';
 /** Enabling the option defaults to `optional`; omitting it keeps bearer behavior. */
@@ -114,13 +116,6 @@ interface OidcVaultApiDeviceBindingOptions extends OidcVaultDeviceBindingOptions
     /** Epoch-millisecond clock for proof age/nonce/replay; default Date.now. Shared instances need synchronized clocks. */
     now?: () => number;
 }
-interface OidcVaultUserProfile {
-    sub: string;
-    email?: string;
-    name?: string;
-    preferredUsername?: string;
-    [key: string]: unknown;
-}
 /**
  * Stored session identity. Exchange, refresh, and logout compare each defined
  * field verbatim against resolved middleware config before use. Opt-in/guarded
@@ -515,19 +510,6 @@ interface IssueTokenInput {
      */
     deviceBinding?: Readonly<OidcVaultVerifiedDpopBinding>;
 }
-/**
- * Local application credentials returned by `OidcVaultTokenIssuer.issue`.
- * Runtime validation copies only these fields into a fresh result; additional
- * properties are ignored and cannot override the response's session ID/user.
- */
-interface OidcVaultTokenIssueResult {
-    /** Nonempty opaque token for unbound issuance; bound issuance requires a compact signed JWT with matching `cnf.jkt`. */
-    accessToken: string;
-    /** Token lifetime in seconds: a finite, nonnegative safe integer (zero is valid). */
-    expiresIn: number;
-    /** Exact `DPoP` is required when bound. Unbound permits only `Bearer` or omission; omitted/undefined stays absent in JSON. */
-    tokenType?: 'Bearer' | 'DPoP';
-}
 /**
  * Trusted application token issuer for exchange and refresh. Return a non-null,
  * non-array object satisfying `OidcVaultTokenIssueResult`; only its declared
@@ -554,7 +536,7 @@ interface OidcVaultAccessTokenValidationResult {
     /** Verified sender constraint. Legacy adapters may omit it only for genuinely unbound credentials. */
     confirmation?: OidcVaultAccessTokenConfirmation | null;
 }
-/** Canonical RFC 7638 SHA-256 thumbprint derived from verified token/introspection data, never from a proof alone. */
+/** Exact one-field confirmation: canonical RFC 7638 SHA-256 thumbprint from verified token/introspection data, never from a proof alone. */
 interface OidcVaultAccessTokenConfirmation {
     jkt: string;
 }
@@ -628,13 +610,18 @@ interface OidcVaultAccessTokenMiddlewareOptions {
 interface OidcVaultAuthenticatedRequest extends Request {
     auth?: OidcVaultAuthContext;
 }
-/** Local JWT verification options, independent of the asymmetric DPoP proof policy; captured at construction. */
+/**
+ * Local JWT verification options, independent of the asymmetric DPoP proof
+ * policy; captured at construction. JWTs with cnf require the supported exact
+ * jkt profile and a nonnegative safe-integer exp with safe milliseconds in both
+ * validator methods. Unbound JWTs retain JOSE's optional-exp behavior.
+ */
 interface OidcVaultJwtAccessTokenValidatorOptions {
     key: CryptoKey | KeyObject | JWK | Uint8Array;
     issuer?: string;
     audience?: string | string[];
     algorithms?: string[];
-    /** Verified cnf is snapshotted before this mapper; mapper-supplied confirmation/deviceBinding is ignored. */
+    /** JOSE verification and bound-JWT profile/expiry checks precede this mapper. Original cnf is snapshotted; mapper-supplied confirmation/deviceBinding is ignored. */
     mapClaims?(claims: Record<string, unknown>): OidcVaultAccessTokenValidationResult;
 }
 declare module 'express-serve-static-core' {
@@ -666,50 +653,10 @@ interface OidcVaultConfig {
     clientSecret?: string;
     scopes?: string;
 }
-interface OidcVaultLogoutResult {
-    /**
-     * Successful logout commits revocation before upstream work and clears the
-     * session cookie under cookie transport. Built-in live handles and unexpired
-     * aliases authenticate the surviving lineage's provider/original binding;
-     * wrong identity, missing/wrong/stale/replayed proof, or disabled acceptance
-     * of a bound lineage fails without deleting or clearing. No currently live
-     * target is idempotent success without deletion or proof reservation. Aliases
-     * grant revocation only, not refresh authentication or upstream redirects.
-     * Old custom bearer stores without revocation context retain legacy alias
-     * deletion behavior. Stateless application access tokens are not invalidated.
-     * Local-only logout (`redirect` unset or `false`) never contacts the provider.
-     * Redirected logout (`redirect: true`)
-     * treats the upstream end-session redirect as best-effort: when provider
-     * discovery fails or no `endSessionEndpoint` is available, the route still
-     * returns this local success. Discovery errors reach `onError` without
-     * undoing revocation or skipping the live session's `onLogout` notification.
-     */
-    loggedOut: true;
-}
 interface OidcVaultBackchannelLogoutResult {
     loggedOut: true;
     revokedSessions: number;
 }
-interface OidcVaultExchangeResult extends Partial<OidcVaultTokenIssueResult> {
-    /** Authoritative vault handle in body transport; omitted from cookie-transport JSON. */
-    sessionId?: string;
-    /** Session profile; extra token-issuer result properties cannot override it. */
-    user?: OidcVaultUserProfile;
-}
-/** JSON body for opt-in `POST <basePath>/login`; proof/key and recognition signals belong in their configured headers, not the body. */
-interface OidcVaultLoginInitiationInput {
-    /** Optional destination on the configured frontend origin. Query-string returnTo is ignored by POST login. */
-    returnTo?: string;
-}
-/**
- * Exact successful POST-login JSON. Navigate to this URL after storing a proof
- * key when DPoP is enabled. Use credentials: 'include' even with body session
- * transport: initiation sets a temporary HttpOnly transaction cookie.
- */
-interface OidcVaultLoginInitiationResult {
-    authorizationUrl: string;
-}
-type OidcVaultSessionTransport = 'body' | 'cookie';
 type OidcVaultCookieDeploymentMode = 'same-origin' | 'same-site' | 'cross-site';
 type OidcVaultCookieSameSite = 'lax' | 'strict' | 'none';
 /**
@@ -971,6 +918,10 @@ declare function createOidcVaultAccessTokenMiddleware(options: OidcVaultAccessTo
  * the sender constraint. The request-aware result always has confirmation
  * (null only for genuinely unbound JWTs). Legacy unbound results omit it;
  * bound results report it so binding-disabled vault middleware refuses downgrade.
+ * Bound JWTs additionally require canonical compact encoding and a nonnegative
+ * safe-integer exp with safe milliseconds, checked before mapClaims in both
+ * methods. JOSE verifies signature/expiry and configured issuer/audience first. Unbound
+ * JWTs retain JOSE's generic optional-exp contract.
  * Proof/target/ath/nonce/replay enforcement belongs to the API middleware.
  * Construction captures options and copies secret/JWK/allowlist containers.
  */
@@ -1017,4 +968,4 @@ declare function normalizeOidcVaultBasePath(value?: string): string;
  */
 declare function createOidcVaultMiddleware(options: OidcVaultOptions): Router;
 
-export { type AuthorizationTransaction, type AuthorizationTransactionInput, type ConsumeAuthorizationTransactionIfMatchesInput, type ConsumeBackchannelLogoutTokenJtiInput, type ConsumeExchangeCodeIfMatchesInput, DEFAULT_AUTHORIZATION_TRANSACTION_TTL_MS, DEFAULT_EXCHANGE_CODE_TTL_MS, DEFAULT_OIDC_SCOPES, DEFAULT_OIDC_VAULT_BASE_PATH, DEFAULT_OIDC_VAULT_REQUEST_BODY_LIMIT, type DeleteSessionsByLogicalSessionIdInput, type DeleteSessionsByProviderSessionIdInput, type DeleteSessionsBySubjectInput, type ExchangeCodeRecord, type ExchangeCodeRecordInput, type IssueTokenInput, OIDC_VAULT_ROUTE_PATHS, OIDC_VAULT_URL_ENCODED_PARAMETER_LIMIT, type OidcVaultAccessTokenConfirmation, type OidcVaultAccessTokenMiddlewareErrorContext, type OidcVaultAccessTokenMiddlewareOptions, type OidcVaultAccessTokenRequestInput, type OidcVaultAccessTokenValidationResult, type OidcVaultAccessTokenValidator, type OidcVaultApiDeviceBindingOptions, type OidcVaultAuthContext, type OidcVaultAuthenticatedRequest, type OidcVaultBackchannelLogoutResult, type OidcVaultConfig, type OidcVaultConfigMode, type OidcVaultCookieDeploymentMode, type OidcVaultCookieOptions, type OidcVaultCookieSameSite, type OidcVaultDeviceBindingMode, type OidcVaultDeviceBindingOptions, type OidcVaultDeviceBindingStoreProvider, type OidcVaultDpopAlgorithm, type OidcVaultDpopBinding, type OidcVaultDpopNonceOptions, type OidcVaultDpopProofOptions, OidcVaultDpopReplayCapacityError, type OidcVaultDpopReplayStore, type OidcVaultEnv, type OidcVaultErrorContext, type OidcVaultExchangeResult, type OidcVaultFingerprintRecognitionOptions, type OidcVaultHookContext, type OidcVaultHooks, type OidcVaultJwtAccessTokenValidatorOptions, type OidcVaultLoginInitiationInput, type OidcVaultLoginInitiationResult, type OidcVaultLogoutResult, type OidcVaultOptions, type OidcVaultProviderMetadata, type OidcVaultRecordBindingMatch, type OidcVaultRequestAwareAccessTokenValidationResult, type OidcVaultRequestAwareAccessTokenValidator, type OidcVaultResolvedConfig, type OidcVaultRouteName, type OidcVaultSession, type OidcVaultSessionInput, type OidcVaultSessionRevocationContext, type OidcVaultSessionTransport, OidcVaultStoreConflictError, type OidcVaultStoreProvider, type OidcVaultTokenIssueResult, type OidcVaultTokenIssuer, type OidcVaultTransactionCookieOptions, type OidcVaultUserProfile, type OidcVaultVerifiedDpopBinding, type ReserveDpopProofInput, type RotateSessionInput, createOidcVaultAccessTokenMiddleware, createOidcVaultJwtAccessTokenValidator, createOidcVaultMiddleware, normalizeOidcVaultBasePath, resolveOidcVaultConfig, resolveOidcVaultConfigFromEnv };
+export { type AuthorizationTransaction, type AuthorizationTransactionInput, type ConsumeAuthorizationTransactionIfMatchesInput, type ConsumeBackchannelLogoutTokenJtiInput, type ConsumeExchangeCodeIfMatchesInput, DEFAULT_AUTHORIZATION_TRANSACTION_TTL_MS, DEFAULT_EXCHANGE_CODE_TTL_MS, DEFAULT_OIDC_SCOPES, DEFAULT_OIDC_VAULT_BASE_PATH, DEFAULT_OIDC_VAULT_REQUEST_BODY_LIMIT, type DeleteSessionsByLogicalSessionIdInput, type DeleteSessionsByProviderSessionIdInput, type DeleteSessionsBySubjectInput, type ExchangeCodeRecord, type ExchangeCodeRecordInput, type IssueTokenInput, OIDC_VAULT_ROUTE_PATHS, OIDC_VAULT_URL_ENCODED_PARAMETER_LIMIT, type OidcVaultAccessTokenConfirmation, type OidcVaultAccessTokenMiddlewareErrorContext, type OidcVaultAccessTokenMiddlewareOptions, type OidcVaultAccessTokenRequestInput, type OidcVaultAccessTokenValidationResult, type OidcVaultAccessTokenValidator, type OidcVaultApiDeviceBindingOptions, type OidcVaultAuthContext, type OidcVaultAuthenticatedRequest, type OidcVaultBackchannelLogoutResult, type OidcVaultConfig, type OidcVaultConfigMode, type OidcVaultCookieDeploymentMode, type OidcVaultCookieOptions, type OidcVaultCookieSameSite, type OidcVaultDeviceBindingMode, type OidcVaultDeviceBindingOptions, type OidcVaultDeviceBindingStoreProvider, type OidcVaultDpopAlgorithm, type OidcVaultDpopBinding, type OidcVaultDpopNonceOptions, type OidcVaultDpopProofOptions, OidcVaultDpopReplayCapacityError, type OidcVaultDpopReplayStore, type OidcVaultEnv, type OidcVaultErrorContext, type OidcVaultFingerprintRecognitionOptions, type OidcVaultHookContext, type OidcVaultHooks, type OidcVaultJwtAccessTokenValidatorOptions, type OidcVaultOptions, type OidcVaultProviderMetadata, type OidcVaultRecordBindingMatch, type OidcVaultRequestAwareAccessTokenValidationResult, type OidcVaultRequestAwareAccessTokenValidator, type OidcVaultResolvedConfig, type OidcVaultRouteName, type OidcVaultSession, type OidcVaultSessionInput, type OidcVaultSessionRevocationContext, OidcVaultSessionTransport, OidcVaultStoreConflictError, type OidcVaultStoreProvider, OidcVaultTokenIssueResult, type OidcVaultTokenIssuer, type OidcVaultTransactionCookieOptions, OidcVaultUserProfile, type OidcVaultVerifiedDpopBinding, type ReserveDpopProofInput, type RotateSessionInput, createOidcVaultAccessTokenMiddleware, createOidcVaultJwtAccessTokenValidator, createOidcVaultMiddleware, normalizeOidcVaultBasePath, resolveOidcVaultConfig, resolveOidcVaultConfigFromEnv };

package/index.js

@@ -1833,6 +1833,35 @@ async function fetchUserInfo(metadata, accessToken, options = {}) {
 // src/token-issuance.ts
 var import_jose3 = require("jose");
 
+// src/access-token-confirmation.ts
+var invalidAccessToken = (diagnostic) => new OidcVaultHttpError(401, "OIDC_VAULT_INVALID_ACCESS_TOKEN", diagnostic, "Access token validation failed.");
+var snapshotJkt = (value, invalid = invalidAccessToken) => {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw invalid("Access token confirmation must be a plain jkt object.");
+  }
+  const prototype = Object.getPrototypeOf(value);
+  const keys = Reflect.ownKeys(value);
+  if (prototype !== Object.prototype && prototype !== null || keys.length !== 1 || keys[0] !== "jkt") {
+    throw invalid("Access token confirmation contains unsupported fields.");
+  }
+  const { jkt } = value;
+  if (!isCanonicalDpopJkt(jkt)) throw invalid("Access token confirmation is not a canonical SHA-256 thumbprint.");
+  return Object.freeze({ jkt });
+};
+var isCompactSignedJwt = (token) => {
+  const parts = token.split(".");
+  return parts.length === 3 && parts.every(
+    (part) => /^[A-Za-z0-9_-]+$/.test(part) ? Buffer.from(part, "base64url").toString("base64url") === part : false
+  );
+};
+var readJwtExpirationMs = (exp) => {
+  if (typeof exp !== "number" || !Number.isSafeInteger(exp) || exp < 0) return void 0;
+  const milliseconds = exp * 1e3;
+  return Number.isSafeInteger(milliseconds) ? milliseconds : void 0;
+};
+var snapshotVerifiedJwtConfirmation = (claims) => Object.hasOwn(claims, "cnf") ? snapshotJkt(claims.cnf) : null;
+var snapshotAccessTokenConfirmation = (value) => value === null ? null : snapshotJkt(value);
+
 // src/vault-session.ts
 var invalidVaultSession = () => new OidcVaultHttpError(401, "OIDC_VAULT_INVALID_SESSION", "Session is missing or expired.");
 var invalidExchangeCode = () => new OidcVaultHttpError(400, "OIDC_VAULT_INVALID_EXCHANGE_CODE", "Exchange code is invalid or expired.");
@@ -1977,13 +2006,7 @@ var createExchangeResponse = (options, session, issuedToken) => ({
   expiresIn: issuedToken.expiresIn,
   tokenType: issuedToken.tokenType
 });
-var isCompactSignedJwt = (token) => {
-  const parts = token.split(".");
-  return parts.length === 3 && parts.every(
-    (part) => /^[A-Za-z0-9_-]+$/.test(part) ? Buffer.from(part, "base64url").toString("base64url") === part : false
-  );
-};
-var assertIssuedTokenConfirmation = (accessToken, jkt) => {
+var assertIssuedBoundJwt = (accessToken, jkt) => {
   if (!isCompactSignedJwt(accessToken)) {
     throw new TypeError("tokenIssuer.issue accessToken must be a compact signed JWT for bound issuance.");
   }
@@ -1998,10 +2021,16 @@ var assertIssuedTokenConfirmation = (accessToken, jkt) => {
   if (typeof header.alg !== "string" || header.alg.length === 0 || header.alg === "none" || header.b64 === false) {
     throw new TypeError("tokenIssuer.issue accessToken must use a signed JWT algorithm for bound issuance.");
   }
-  const cnf = claims.cnf;
-  if (typeof cnf !== "object" || cnf === null || Array.isArray(cnf) || cnf.jkt !== jkt) {
+  const confirmation = snapshotJkt(
+    claims.cnf,
+    (diagnostic) => new TypeError(`tokenIssuer.issue accessToken cnf.jkt is invalid. ${diagnostic}`)
+  );
+  if (confirmation.jkt !== jkt) {
     throw new TypeError("tokenIssuer.issue accessToken cnf.jkt must match the verified device binding.");
   }
+  if (readJwtExpirationMs(claims.exp) === void 0) {
+    throw new TypeError("tokenIssuer.issue accessToken exp must be a nonnegative safe integer with safe milliseconds.");
+  }
 };
 var withIssuedToken = async (req, res, options, session, verifiedBinding) => {
   const binding = resolveVerifiedDeviceBinding(options.deviceBinding, session.deviceBinding, verifiedBinding);
@@ -2034,7 +2063,10 @@ var withIssuedToken = async (req, res, options, session, verifiedBinding) => {
       }
     } else {
       if (tokenType !== "DPoP") throw new TypeError("tokenIssuer.issue tokenType must be DPoP for bound issuance.");
-      assertIssuedTokenConfirmation(accessToken, binding.jkt);
+      if (!Number.isSafeInteger(expiresIn * 1e3)) {
+        throw new TypeError("tokenIssuer.issue expiresIn must have safe milliseconds for bound issuance.");
+      }
+      assertIssuedBoundJwt(accessToken, binding.jkt);
     }
     return { accessToken, expiresIn, ...tokenType === void 0 ? {} : { tokenType } };
   } catch (error) {
@@ -2046,27 +2078,6 @@ var withIssuedToken = async (req, res, options, session, verifiedBinding) => {
 
 // src/token-validation.ts
 var import_jose4 = require("jose");
-
-// src/access-token-confirmation.ts
-var invalidAccessToken = (diagnostic) => new OidcVaultHttpError(401, "OIDC_VAULT_INVALID_ACCESS_TOKEN", diagnostic, "Access token validation failed.");
-var snapshotJkt = (value) => {
-  if (typeof value !== "object" || value === null || Array.isArray(value)) {
-    throw invalidAccessToken("Access token confirmation must be a plain jkt object.");
-  }
-  const prototype = Object.getPrototypeOf(value);
-  const keys = Reflect.ownKeys(value);
-  if (prototype !== Object.prototype && prototype !== null || keys.length !== 1 || keys[0] !== "jkt") {
-    throw invalidAccessToken("Access token confirmation contains unsupported fields.");
-  }
-  const { jkt } = value;
-  if (!isCanonicalDpopJkt(jkt))
-    throw invalidAccessToken("Access token confirmation is not a canonical SHA-256 thumbprint.");
-  return Object.freeze({ jkt });
-};
-var snapshotVerifiedJwtConfirmation = (claims) => Object.hasOwn(claims, "cnf") ? snapshotJkt(claims.cnf) : null;
-var snapshotAccessTokenConfirmation = (value) => value === null ? null : snapshotJkt(value);
-
-// src/token-validation.ts
 var BACKCHANNEL_LOGOUT_EVENT_CLAIM = "http://schemas.openid.net/event/backchannel-logout";
 var validateBackchannelLogoutTokenTyp = (typ) => {
   if (typ !== void 0 && (typeof typ !== "string" || typ.toLowerCase() !== "logout+jwt")) {
@@ -2228,6 +2239,14 @@ function createOidcVaultJwtAccessTokenValidator(options) {
     const result = await (0, import_jose4.jwtVerify)(token, key, { issuer, audience, algorithms });
     const claims = result.payload;
     const confirmation = snapshotVerifiedJwtConfirmation(claims);
+    if (confirmation !== null) {
+      if (!isCompactSignedJwt(token)) {
+        throw invalidAccessToken("Bound JWT must use canonical compact signed encoding.");
+      }
+      if (readJwtExpirationMs(claims.exp) === void 0) {
+        throw invalidAccessToken("Bound JWT exp must be a nonnegative safe integer with safe milliseconds.");
+      }
+    }
     const mapped = mapClaims ? mapClaims(claims) : defaultJwtClaimsMapper(claims);
     const { subject, sessionId, scope, claims: mappedClaims } = mapped;
     return { subject, sessionId, scope, claims: mappedClaims, confirmation };

package/index.mjs

@@ -1785,6 +1785,35 @@ async function fetchUserInfo(metadata, accessToken, options = {}) {
 // src/token-issuance.ts
 import { decodeJwt, decodeProtectedHeader } from "jose";
 
+// src/access-token-confirmation.ts
+var invalidAccessToken = (diagnostic) => new OidcVaultHttpError(401, "OIDC_VAULT_INVALID_ACCESS_TOKEN", diagnostic, "Access token validation failed.");
+var snapshotJkt = (value, invalid = invalidAccessToken) => {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw invalid("Access token confirmation must be a plain jkt object.");
+  }
+  const prototype = Object.getPrototypeOf(value);
+  const keys = Reflect.ownKeys(value);
+  if (prototype !== Object.prototype && prototype !== null || keys.length !== 1 || keys[0] !== "jkt") {
+    throw invalid("Access token confirmation contains unsupported fields.");
+  }
+  const { jkt } = value;
+  if (!isCanonicalDpopJkt(jkt)) throw invalid("Access token confirmation is not a canonical SHA-256 thumbprint.");
+  return Object.freeze({ jkt });
+};
+var isCompactSignedJwt = (token) => {
+  const parts = token.split(".");
+  return parts.length === 3 && parts.every(
+    (part) => /^[A-Za-z0-9_-]+$/.test(part) ? Buffer.from(part, "base64url").toString("base64url") === part : false
+  );
+};
+var readJwtExpirationMs = (exp) => {
+  if (typeof exp !== "number" || !Number.isSafeInteger(exp) || exp < 0) return void 0;
+  const milliseconds = exp * 1e3;
+  return Number.isSafeInteger(milliseconds) ? milliseconds : void 0;
+};
+var snapshotVerifiedJwtConfirmation = (claims) => Object.hasOwn(claims, "cnf") ? snapshotJkt(claims.cnf) : null;
+var snapshotAccessTokenConfirmation = (value) => value === null ? null : snapshotJkt(value);
+
 // src/vault-session.ts
 var invalidVaultSession = () => new OidcVaultHttpError(401, "OIDC_VAULT_INVALID_SESSION", "Session is missing or expired.");
 var invalidExchangeCode = () => new OidcVaultHttpError(400, "OIDC_VAULT_INVALID_EXCHANGE_CODE", "Exchange code is invalid or expired.");
@@ -1929,13 +1958,7 @@ var createExchangeResponse = (options, session, issuedToken) => ({
   expiresIn: issuedToken.expiresIn,
   tokenType: issuedToken.tokenType
 });
-var isCompactSignedJwt = (token) => {
-  const parts = token.split(".");
-  return parts.length === 3 && parts.every(
-    (part) => /^[A-Za-z0-9_-]+$/.test(part) ? Buffer.from(part, "base64url").toString("base64url") === part : false
-  );
-};
-var assertIssuedTokenConfirmation = (accessToken, jkt) => {
+var assertIssuedBoundJwt = (accessToken, jkt) => {
   if (!isCompactSignedJwt(accessToken)) {
     throw new TypeError("tokenIssuer.issue accessToken must be a compact signed JWT for bound issuance.");
   }
@@ -1950,10 +1973,16 @@ var assertIssuedTokenConfirmation = (accessToken, jkt) => {
   if (typeof header.alg !== "string" || header.alg.length === 0 || header.alg === "none" || header.b64 === false) {
     throw new TypeError("tokenIssuer.issue accessToken must use a signed JWT algorithm for bound issuance.");
   }
-  const cnf = claims.cnf;
-  if (typeof cnf !== "object" || cnf === null || Array.isArray(cnf) || cnf.jkt !== jkt) {
+  const confirmation = snapshotJkt(
+    claims.cnf,
+    (diagnostic) => new TypeError(`tokenIssuer.issue accessToken cnf.jkt is invalid. ${diagnostic}`)
+  );
+  if (confirmation.jkt !== jkt) {
     throw new TypeError("tokenIssuer.issue accessToken cnf.jkt must match the verified device binding.");
   }
+  if (readJwtExpirationMs(claims.exp) === void 0) {
+    throw new TypeError("tokenIssuer.issue accessToken exp must be a nonnegative safe integer with safe milliseconds.");
+  }
 };
 var withIssuedToken = async (req, res, options, session, verifiedBinding) => {
   const binding = resolveVerifiedDeviceBinding(options.deviceBinding, session.deviceBinding, verifiedBinding);
@@ -1986,7 +2015,10 @@ var withIssuedToken = async (req, res, options, session, verifiedBinding) => {
       }
     } else {
       if (tokenType !== "DPoP") throw new TypeError("tokenIssuer.issue tokenType must be DPoP for bound issuance.");
-      assertIssuedTokenConfirmation(accessToken, binding.jkt);
+      if (!Number.isSafeInteger(expiresIn * 1e3)) {
+        throw new TypeError("tokenIssuer.issue expiresIn must have safe milliseconds for bound issuance.");
+      }
+      assertIssuedBoundJwt(accessToken, binding.jkt);
     }
     return { accessToken, expiresIn, ...tokenType === void 0 ? {} : { tokenType } };
   } catch (error) {
@@ -1998,27 +2030,6 @@ var withIssuedToken = async (req, res, options, session, verifiedBinding) => {
 
 // src/token-validation.ts
 import { jwtVerify } from "jose";
-
-// src/access-token-confirmation.ts
-var invalidAccessToken = (diagnostic) => new OidcVaultHttpError(401, "OIDC_VAULT_INVALID_ACCESS_TOKEN", diagnostic, "Access token validation failed.");
-var snapshotJkt = (value) => {
-  if (typeof value !== "object" || value === null || Array.isArray(value)) {
-    throw invalidAccessToken("Access token confirmation must be a plain jkt object.");
-  }
-  const prototype = Object.getPrototypeOf(value);
-  const keys = Reflect.ownKeys(value);
-  if (prototype !== Object.prototype && prototype !== null || keys.length !== 1 || keys[0] !== "jkt") {
-    throw invalidAccessToken("Access token confirmation contains unsupported fields.");
-  }
-  const { jkt } = value;
-  if (!isCanonicalDpopJkt(jkt))
-    throw invalidAccessToken("Access token confirmation is not a canonical SHA-256 thumbprint.");
-  return Object.freeze({ jkt });
-};
-var snapshotVerifiedJwtConfirmation = (claims) => Object.hasOwn(claims, "cnf") ? snapshotJkt(claims.cnf) : null;
-var snapshotAccessTokenConfirmation = (value) => value === null ? null : snapshotJkt(value);
-
-// src/token-validation.ts
 var BACKCHANNEL_LOGOUT_EVENT_CLAIM = "http://schemas.openid.net/event/backchannel-logout";
 var validateBackchannelLogoutTokenTyp = (typ) => {
   if (typ !== void 0 && (typeof typ !== "string" || typ.toLowerCase() !== "logout+jwt")) {
@@ -2180,6 +2191,14 @@ function createOidcVaultJwtAccessTokenValidator(options) {
     const result = await jwtVerify(token, key, { issuer, audience, algorithms });
     const claims = result.payload;
     const confirmation = snapshotVerifiedJwtConfirmation(claims);
+    if (confirmation !== null) {
+      if (!isCompactSignedJwt(token)) {
+        throw invalidAccessToken("Bound JWT must use canonical compact signed encoding.");
+      }
+      if (readJwtExpirationMs(claims.exp) === void 0) {
+        throw invalidAccessToken("Bound JWT exp must be a nonnegative safe integer with safe milliseconds.");
+      }
+    }
     const mapped = mapClaims ? mapClaims(claims) : defaultJwtClaimsMapper(claims);
     const { subject, sessionId, scope, claims: mappedClaims } = mapped;
     return { subject, sessionId, scope, claims: mappedClaims, confirmation };

package/package.json

@@ -2,7 +2,7 @@
   "name": "@web-ts-toolkit/express-oidc-vault",
   "description": "Express OIDC sessions with body or cookie transport, optional DPoP-bound local JWTs, and pluggable vault stores",
   "homepage": "https://web-ts-toolkit.pages.dev/docs/packages/express-oidc-vault",
-  "version": "0.51.0",
+  "version": "0.52.0",
   "sideEffects": false,
   "keywords": [
     "express",
@@ -26,6 +26,16 @@
       "import": "./index.mjs",
       "require": "./index.js",
       "default": "./index.js"
+    },
+    "./wire": {
+      "types": {
+        "import": "./wire.d.mts",
+        "require": "./wire.d.ts",
+        "default": "./wire.d.ts"
+      },
+      "import": "./wire.mjs",
+      "require": "./wire.js",
+      "default": "./wire.js"
     }
   },
   "engines": {

package/wire.d.mts

@@ -0,0 +1,76 @@
+/** Public JSON profile returned by exchange/refresh. */
+interface OidcVaultUserProfile {
+    sub: string;
+    email?: string;
+    name?: string;
+    preferredUsername?: string;
+    [key: string]: unknown;
+}
+/**
+ * Local application credentials returned by `OidcVaultTokenIssuer.issue`.
+ * Runtime validation copies only these fields into a fresh result; additional
+ * properties are ignored and cannot override the response's session ID/user.
+ */
+interface OidcVaultTokenIssueResult {
+    /**
+     * Nonempty opaque token for unbound issuance. Bound issuance requires a
+     * compact signed JWT (canonical unpadded base64url), exactly one cnf field
+     * `{ jkt }` matching the verified canonical SHA-256 thumbprint, and a
+     * nonnegative safe-integer exp in seconds with safe exp * 1000 milliseconds.
+     * Core checks the output shape; APIs independently authenticate the JWT.
+     */
+    accessToken: string;
+    /**
+     * Token lifetime in seconds: a finite nonnegative safe integer; bound
+     * issuance also requires safe expiresIn * 1000. Zero is valid and may carry
+     * a rotated session handle, but supplies no live reusable API credential.
+     */
+    expiresIn: number;
+    /** Exact `DPoP` is required when bound. Unbound permits only `Bearer` or omission; omitted/undefined stays absent in JSON. */
+    tokenType?: 'Bearer' | 'DPoP';
+}
+/** Exchange/refresh JSON. Local token fields are absent when no token issuer is configured. */
+interface OidcVaultExchangeResult extends Partial<OidcVaultTokenIssueResult> {
+    /** Authoritative vault handle in body transport; omitted from cookie-transport JSON. */
+    sessionId?: string;
+    /** Session profile; extra token-issuer result properties cannot override it. */
+    user?: OidcVaultUserProfile;
+}
+/** JSON body for opt-in `POST <basePath>/login`; proof/key and recognition signals belong in their configured headers, not the body. */
+interface OidcVaultLoginInitiationInput {
+    /** Optional destination on the configured frontend origin. Query-string returnTo is ignored by POST login. */
+    returnTo?: string;
+}
+/**
+ * Exact successful POST-login JSON. Navigate to this URL after storing a proof
+ * key when DPoP is enabled. Use credentials: 'include' even with body session
+ * transport: initiation sets a temporary HttpOnly transaction cookie.
+ */
+interface OidcVaultLoginInitiationResult {
+    authorizationUrl: string;
+}
+/** Successful local logout; stateless application JWTs require separate revocation or expiry. */
+interface OidcVaultLogoutResult {
+    /**
+     * Successful logout commits revocation before upstream work and clears the
+     * session cookie under cookie transport. Built-in live handles and unexpired
+     * aliases authenticate the surviving lineage's provider/original binding;
+     * wrong identity, missing/wrong/stale/replayed proof, or disabled acceptance
+     * of a bound lineage fails without deleting or clearing. No currently live
+     * target is idempotent success without deletion or proof reservation. Aliases
+     * grant revocation only, not refresh authentication or upstream redirects.
+     * Old custom bearer stores without revocation context retain legacy alias
+     * deletion behavior. Stateless application access tokens are not invalidated.
+     * Local-only logout (`redirect` unset or `false`) never contacts the provider.
+     * Redirected logout (`redirect: true`)
+     * treats the upstream end-session redirect as best-effort: when provider
+     * discovery fails or no `endSessionEndpoint` is available, the route still
+     * returns this local success. Discovery errors reach `onError` without
+     * undoing revocation or skipping the live session's `onLogout` notification.
+     */
+    loggedOut: true;
+}
+/** Vault handle transport; independent of DPoP mode. Default: body. */
+type OidcVaultSessionTransport = 'body' | 'cookie';
+
+export type { OidcVaultExchangeResult, OidcVaultLoginInitiationInput, OidcVaultLoginInitiationResult, OidcVaultLogoutResult, OidcVaultSessionTransport, OidcVaultTokenIssueResult, OidcVaultUserProfile };