@stackwright-pro/auth 0.2.0-alpha.3 → 0.2.0-alpha.5

package/LICENSE

@@ -0,0 +1,21 @@
+PROPRIETARY SOFTWARE LICENSE
+
+Copyright (c) 2024-2026 Per Aspera LLC. All Rights Reserved.
+
+This software and associated documentation files (the "Software") are the
+proprietary and confidential property of Per Aspera LLC ("Company").
+
+RESTRICTIONS: You may not use, copy, modify, merge, publish, distribute,
+sublicense, sell, or otherwise exploit this Software or any portion thereof
+without the express prior written consent of the Company.
+
+GOVERNMENT USE: Use, duplication, or disclosure by the U.S. Government is
+subject to restrictions as set forth in FAR 52.227-19 (Commercial Computer
+Software - Restricted Rights) and DFARS 252.227-7013 (Rights in Technical
+Data and Computer Software), as applicable.
+
+THE SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED. IN NO EVENT SHALL THE COMPANY BE LIABLE FOR ANY CLAIM, DAMAGES, OR
+OTHER LIABILITY ARISING FROM THE USE OF THE SOFTWARE.
+
+For licensing inquiries: legal@peraspera.com

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { AuthProvider as AuthProvider$1, PKIConfig, AuthContext as AuthContext$1, AuthUser, AuthSession, OIDCConfig, RBACConfig, ComponentAuthConfig } from '@stackwright-pro/types';
-export { AuthConfig, AuthSession, AuthUser, ComponentAuthConfig, OIDCConfig, PKIConfig, RBACConfig, authConfigSchema, authSessionSchema, authUserSchema, componentAuthSchema, oidcConfigSchema, pkiConfigSchema, rbacConfigSchema } from '@stackwright-pro/types';
+import { AuthProvider as AuthProvider$1, PKIConfig, AuthContext as AuthContext$1, AuthUser, AuthSession, OIDCConfig, RBACConfig, ComponentAuthConfig, CertRevocationConfig } from '@stackwright-pro/types';
+export { AuthConfig, AuthSession, AuthUser, CertRevocationConfig, ComponentAuthConfig, OIDCConfig, PKIConfig, RBACConfig, authConfigSchema, authSessionSchema, authUserSchema, componentAuthSchema, oidcConfigSchema, pkiConfigSchema, rbacConfigSchema } from '@stackwright-pro/types';
 import { X509Certificate } from '@peculiar/x509';
 import * as React from 'react';
 import React__default, { ReactNode, ReactElement } from 'react';
@@ -32,6 +32,8 @@ declare enum AuditEventType {
     PKI_CERT_VALIDATED = "pki.cert.validated",
     PKI_CERT_REJECTED = "pki.cert.rejected",
     PKI_HEADER_SIG_FAILED = "pki.header_sig.failed",
+    PKI_CERT_REVOKED = "pki.cert.revoked",
+    PKI_REVOCATION_CHECK_FAILED = "pki.revocation_check.failed",
     OIDC_STATE_MISMATCH = "oidc.state_mismatch",
     OIDC_TOKEN_EXCHANGE = "oidc.token_exchange",
     OIDC_NONCE_MISMATCH = "oidc.nonce_mismatch"
@@ -108,6 +110,7 @@ declare function createAuditEvent(type: AuditEventType, outcome: 'success' | 'fa
 declare class PKIProvider implements AuthProvider$1 {
     private config;
     private auditLogger?;
+    private revocationChecker;
     constructor(config: PKIConfig, auditLogger?: AuditLogger);
     authenticate(context: AuthContext$1): Promise<AuthUser | null>;
     validate(session: AuthSession): Promise<boolean>;
@@ -903,6 +906,131 @@ declare function verifyCertHeaders(headers: Record<string, string | undefined>,
     reason?: string;
 };
 
+/**
+ * Certificate Revocation Checking
+ *
+ * Pluggable OCSP and CRL revocation checking for X.509 certificates.
+ * Designed for government/DoD deployments requiring IL-4 compliance.
+ *
+ * Architecture:
+ * - CertRevocationChecker interface — all strategies implement this
+ * - OCSPRevocationChecker — queries an OCSP responder via HTTP GET
+ * - CRLRevocationChecker  — fetches and parses a CRL distribution point
+ * - CompositeRevocationChecker — OCSP with CRL fallback
+ * - SkipRevocationChecker — passthrough (document that gateway handles it)
+ * - RevocationCache — simple TTL cache keyed by serial number
+ *
+ * Note on gateway_headers source:
+ * When PKI source is 'gateway_headers', the application only receives parsed
+ * certificate fields — not the raw PEM. OCSP CertID construction requires
+ * the issuer's public key hash (issuerKeyHash), which is not available from
+ * headers alone. For OCSP with gateway_headers, you MUST configure
+ * ocspResponderUrl AND the checker will construct a simplified GET request
+ * using the serial number. For full RFC-6960 compliance with direct_tls,
+ * the certPem is used to extract AIA and construct the proper CertID.
+ */
+
+interface RevocationInput {
+    /** Certificate serial number (hex string, e.g. '1234ABCDEF') */
+    serialNumber: string;
+    /** Issuer common name if known (from parsed cert) */
+    issuerName?: string;
+    /** Full certificate PEM — available for direct_tls source only */
+    certPem?: string;
+}
+type RevocationStatus = {
+    revoked: false;
+} | {
+    revoked: true;
+    reason?: string;
+    revokedAt?: Date;
+} | {
+    revoked: false;
+    skipped: true;
+    reason: string;
+};
+interface CertRevocationChecker {
+    /**
+     * Check whether a certificate has been revoked.
+     * @returns RevocationStatus — { revoked: true } means reject the cert.
+     * @throws May throw if hardFail is true and the check cannot be completed.
+     */
+    check(input: RevocationInput): Promise<RevocationStatus>;
+}
+declare class RevocationCache {
+    private readonly store;
+    private readonly maxAgeMs;
+    constructor(cacheMaxAgeSecs?: number);
+    get(serialNumber: string): RevocationStatus | null;
+    set(serialNumber: string, status: RevocationStatus): void;
+    /** Invalidate a single entry (e.g. after a forced re-check) */
+    invalidate(serialNumber: string): void;
+    /** Number of cached entries (for testing/monitoring) */
+    get size(): number;
+}
+declare class SkipRevocationChecker implements CertRevocationChecker {
+    private readonly reason;
+    constructor(reason?: string);
+    check(_input: RevocationInput): Promise<RevocationStatus>;
+}
+/**
+ * CRL revocation checker.
+ *
+ * Fetches a Certificate Revocation List from a distribution point URL
+ * and checks whether the certificate serial number appears in it.
+ *
+ * CRL format: DER-encoded X.509 CRL (RFC 5280). The revoked certificate
+ * list is an ASN.1 SEQUENCE of TBSCertList entries, each containing a
+ * serial number as an ASN.1 INTEGER.
+ *
+ * This implementation parses just the serial numbers from the DER blob
+ * using manual ASN.1 traversal — no additional dependencies needed.
+ */
+declare class CRLRevocationChecker implements CertRevocationChecker {
+    private readonly cache;
+    private readonly config;
+    constructor(config: CertRevocationConfig);
+    check(input: RevocationInput): Promise<RevocationStatus>;
+    /** Exposed for testing */
+    get _cache(): RevocationCache;
+}
+/**
+ * OCSP revocation checker (RFC 6960).
+ *
+ * Constructs and sends an OCSP GET request to the configured responder.
+ * Uses SHA-1 for CertID hashing (per RFC 6960 — SHA-1 is mandated for
+ * CertID even though it's deprecated for other uses).
+ *
+ * For gateway_headers source: requires ocspResponderUrl in config.
+ * The serial number is included in the request; issuerNameHash and
+ * issuerKeyHash are derived from the CA chain if provided, or zeroed
+ * (some OCSP responders accept this for simple serial lookups).
+ *
+ * For direct_tls source: certPem in RevocationInput enables full
+ * CertID construction per RFC 6960.
+ */
+declare class OCSPRevocationChecker implements CertRevocationChecker {
+    private readonly cache;
+    private readonly config;
+    constructor(config: CertRevocationConfig);
+    check(input: RevocationInput): Promise<RevocationStatus>;
+    /** Exposed for testing */
+    get _cache(): RevocationCache;
+}
+declare class CompositeRevocationChecker implements CertRevocationChecker {
+    private readonly ocsp;
+    private readonly crl;
+    constructor(config: CertRevocationConfig);
+    check(input: RevocationInput): Promise<RevocationStatus>;
+}
+declare function createRevocationChecker(config: CertRevocationConfig): CertRevocationChecker;
+/**
+ * Normalize a certificate serial number to uppercase hex without leading zeros
+ * for consistent comparison.
+ * Handles formats: '1234abcd', '12:34:ab:cd', '0x1234abcd'
+ */
+declare function normalizeSerial(serial: string): string;
+
 /**
  * DoD CAC Profile Configuration
  *
@@ -1050,4 +1178,4 @@ declare function hasAuthConfig(item: any): item is {
     auth: ComponentAuthConfig;
 };
 
-export { type AuditEvent, AuditEventType, type AuditLogger, AuthContext, type AuthContextValue, AuthProvider, type AuthProviderProps, type AuthorizationRequest, type BuildAuthorizationUrlOptions, type ComponentProps, CompositeAuditLogger, ConsoleAuditLogger, type CookieOptions, DOD_CAC_PROFILE, type HeaderSigningConfig, InMemoryRevocationStore, KeycloakAdapter, NoopAuditLogger, type OIDCMetadata, OIDCProvider, PKIProvider, type ParsedCertificate, RBACEngine, type RevocationStore, SessionManager, type SessionManagerConfig, type TokenSet, buildAuthorizationUrl, clearCookie, createAuditEvent, createDoDCACConfig, createDoDCACDevConfig, decryptToken, deriveEncryptionKey, discoverOIDC, encryptToken, exchangeCodeForTokens, extractEDIPI, generateCodeChallenge, generateCodeVerifier, generateJti, generateNonce, generateState, getAuthDecorator, hasAuthConfig, maybeWrapWithAuth, parseCertFromHeaders, parseCertificate, parseCookies, refreshAccessToken, registerAuthDecorator, serializeCookie, signCertHeaders, useAuth, useRequireAuth, validateDoDCAC, validateIdToken, verifyCertHeaders, verifyState, withAuth, withAuthFallback };
+export { type AuditEvent, AuditEventType, type AuditLogger, AuthContext, type AuthContextValue, AuthProvider, type AuthProviderProps, type AuthorizationRequest, type BuildAuthorizationUrlOptions, CRLRevocationChecker, type CertRevocationChecker, type ComponentProps, CompositeAuditLogger, CompositeRevocationChecker, ConsoleAuditLogger, type CookieOptions, DOD_CAC_PROFILE, type HeaderSigningConfig, InMemoryRevocationStore, KeycloakAdapter, NoopAuditLogger, OCSPRevocationChecker, type OIDCMetadata, OIDCProvider, PKIProvider, type ParsedCertificate, RBACEngine, RevocationCache, type RevocationInput, type RevocationStatus, type RevocationStore, SessionManager, type SessionManagerConfig, SkipRevocationChecker, type TokenSet, buildAuthorizationUrl, clearCookie, createAuditEvent, createDoDCACConfig, createDoDCACDevConfig, createRevocationChecker, decryptToken, deriveEncryptionKey, discoverOIDC, encryptToken, exchangeCodeForTokens, extractEDIPI, generateCodeChallenge, generateCodeVerifier, generateJti, generateNonce, generateState, getAuthDecorator, hasAuthConfig, maybeWrapWithAuth, normalizeSerial, parseCertFromHeaders, parseCertificate, parseCookies, refreshAccessToken, registerAuthDecorator, serializeCookie, signCertHeaders, useAuth, useRequireAuth, validateDoDCAC, validateIdToken, verifyCertHeaders, verifyState, withAuth, withAuthFallback };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { AuthProvider as AuthProvider$1, PKIConfig, AuthContext as AuthContext$1, AuthUser, AuthSession, OIDCConfig, RBACConfig, ComponentAuthConfig } from '@stackwright-pro/types';
-export { AuthConfig, AuthSession, AuthUser, ComponentAuthConfig, OIDCConfig, PKIConfig, RBACConfig, authConfigSchema, authSessionSchema, authUserSchema, componentAuthSchema, oidcConfigSchema, pkiConfigSchema, rbacConfigSchema } from '@stackwright-pro/types';
+import { AuthProvider as AuthProvider$1, PKIConfig, AuthContext as AuthContext$1, AuthUser, AuthSession, OIDCConfig, RBACConfig, ComponentAuthConfig, CertRevocationConfig } from '@stackwright-pro/types';
+export { AuthConfig, AuthSession, AuthUser, CertRevocationConfig, ComponentAuthConfig, OIDCConfig, PKIConfig, RBACConfig, authConfigSchema, authSessionSchema, authUserSchema, componentAuthSchema, oidcConfigSchema, pkiConfigSchema, rbacConfigSchema } from '@stackwright-pro/types';
 import { X509Certificate } from '@peculiar/x509';
 import * as React from 'react';
 import React__default, { ReactNode, ReactElement } from 'react';
@@ -32,6 +32,8 @@ declare enum AuditEventType {
     PKI_CERT_VALIDATED = "pki.cert.validated",
     PKI_CERT_REJECTED = "pki.cert.rejected",
     PKI_HEADER_SIG_FAILED = "pki.header_sig.failed",
+    PKI_CERT_REVOKED = "pki.cert.revoked",
+    PKI_REVOCATION_CHECK_FAILED = "pki.revocation_check.failed",
     OIDC_STATE_MISMATCH = "oidc.state_mismatch",
     OIDC_TOKEN_EXCHANGE = "oidc.token_exchange",
     OIDC_NONCE_MISMATCH = "oidc.nonce_mismatch"
@@ -108,6 +110,7 @@ declare function createAuditEvent(type: AuditEventType, outcome: 'success' | 'fa
 declare class PKIProvider implements AuthProvider$1 {
     private config;
     private auditLogger?;
+    private revocationChecker;
     constructor(config: PKIConfig, auditLogger?: AuditLogger);
     authenticate(context: AuthContext$1): Promise<AuthUser | null>;
     validate(session: AuthSession): Promise<boolean>;
@@ -903,6 +906,131 @@ declare function verifyCertHeaders(headers: Record<string, string | undefined>,
     reason?: string;
 };
 
+/**
+ * Certificate Revocation Checking
+ *
+ * Pluggable OCSP and CRL revocation checking for X.509 certificates.
+ * Designed for government/DoD deployments requiring IL-4 compliance.
+ *
+ * Architecture:
+ * - CertRevocationChecker interface — all strategies implement this
+ * - OCSPRevocationChecker — queries an OCSP responder via HTTP GET
+ * - CRLRevocationChecker  — fetches and parses a CRL distribution point
+ * - CompositeRevocationChecker — OCSP with CRL fallback
+ * - SkipRevocationChecker — passthrough (document that gateway handles it)
+ * - RevocationCache — simple TTL cache keyed by serial number
+ *
+ * Note on gateway_headers source:
+ * When PKI source is 'gateway_headers', the application only receives parsed
+ * certificate fields — not the raw PEM. OCSP CertID construction requires
+ * the issuer's public key hash (issuerKeyHash), which is not available from
+ * headers alone. For OCSP with gateway_headers, you MUST configure
+ * ocspResponderUrl AND the checker will construct a simplified GET request
+ * using the serial number. For full RFC-6960 compliance with direct_tls,
+ * the certPem is used to extract AIA and construct the proper CertID.
+ */
+
+interface RevocationInput {
+    /** Certificate serial number (hex string, e.g. '1234ABCDEF') */
+    serialNumber: string;
+    /** Issuer common name if known (from parsed cert) */
+    issuerName?: string;
+    /** Full certificate PEM — available for direct_tls source only */
+    certPem?: string;
+}
+type RevocationStatus = {
+    revoked: false;
+} | {
+    revoked: true;
+    reason?: string;
+    revokedAt?: Date;
+} | {
+    revoked: false;
+    skipped: true;
+    reason: string;
+};
+interface CertRevocationChecker {
+    /**
+     * Check whether a certificate has been revoked.
+     * @returns RevocationStatus — { revoked: true } means reject the cert.
+     * @throws May throw if hardFail is true and the check cannot be completed.
+     */
+    check(input: RevocationInput): Promise<RevocationStatus>;
+}
+declare class RevocationCache {
+    private readonly store;
+    private readonly maxAgeMs;
+    constructor(cacheMaxAgeSecs?: number);
+    get(serialNumber: string): RevocationStatus | null;
+    set(serialNumber: string, status: RevocationStatus): void;
+    /** Invalidate a single entry (e.g. after a forced re-check) */
+    invalidate(serialNumber: string): void;
+    /** Number of cached entries (for testing/monitoring) */
+    get size(): number;
+}
+declare class SkipRevocationChecker implements CertRevocationChecker {
+    private readonly reason;
+    constructor(reason?: string);
+    check(_input: RevocationInput): Promise<RevocationStatus>;
+}
+/**
+ * CRL revocation checker.
+ *
+ * Fetches a Certificate Revocation List from a distribution point URL
+ * and checks whether the certificate serial number appears in it.
+ *
+ * CRL format: DER-encoded X.509 CRL (RFC 5280). The revoked certificate
+ * list is an ASN.1 SEQUENCE of TBSCertList entries, each containing a
+ * serial number as an ASN.1 INTEGER.
+ *
+ * This implementation parses just the serial numbers from the DER blob
+ * using manual ASN.1 traversal — no additional dependencies needed.
+ */
+declare class CRLRevocationChecker implements CertRevocationChecker {
+    private readonly cache;
+    private readonly config;
+    constructor(config: CertRevocationConfig);
+    check(input: RevocationInput): Promise<RevocationStatus>;
+    /** Exposed for testing */
+    get _cache(): RevocationCache;
+}
+/**
+ * OCSP revocation checker (RFC 6960).
+ *
+ * Constructs and sends an OCSP GET request to the configured responder.
+ * Uses SHA-1 for CertID hashing (per RFC 6960 — SHA-1 is mandated for
+ * CertID even though it's deprecated for other uses).
+ *
+ * For gateway_headers source: requires ocspResponderUrl in config.
+ * The serial number is included in the request; issuerNameHash and
+ * issuerKeyHash are derived from the CA chain if provided, or zeroed
+ * (some OCSP responders accept this for simple serial lookups).
+ *
+ * For direct_tls source: certPem in RevocationInput enables full
+ * CertID construction per RFC 6960.
+ */
+declare class OCSPRevocationChecker implements CertRevocationChecker {
+    private readonly cache;
+    private readonly config;
+    constructor(config: CertRevocationConfig);
+    check(input: RevocationInput): Promise<RevocationStatus>;
+    /** Exposed for testing */
+    get _cache(): RevocationCache;
+}
+declare class CompositeRevocationChecker implements CertRevocationChecker {
+    private readonly ocsp;
+    private readonly crl;
+    constructor(config: CertRevocationConfig);
+    check(input: RevocationInput): Promise<RevocationStatus>;
+}
+declare function createRevocationChecker(config: CertRevocationConfig): CertRevocationChecker;
+/**
+ * Normalize a certificate serial number to uppercase hex without leading zeros
+ * for consistent comparison.
+ * Handles formats: '1234abcd', '12:34:ab:cd', '0x1234abcd'
+ */
+declare function normalizeSerial(serial: string): string;
+
 /**
  * DoD CAC Profile Configuration
  *
@@ -1050,4 +1178,4 @@ declare function hasAuthConfig(item: any): item is {
     auth: ComponentAuthConfig;
 };
 
-export { type AuditEvent, AuditEventType, type AuditLogger, AuthContext, type AuthContextValue, AuthProvider, type AuthProviderProps, type AuthorizationRequest, type BuildAuthorizationUrlOptions, type ComponentProps, CompositeAuditLogger, ConsoleAuditLogger, type CookieOptions, DOD_CAC_PROFILE, type HeaderSigningConfig, InMemoryRevocationStore, KeycloakAdapter, NoopAuditLogger, type OIDCMetadata, OIDCProvider, PKIProvider, type ParsedCertificate, RBACEngine, type RevocationStore, SessionManager, type SessionManagerConfig, type TokenSet, buildAuthorizationUrl, clearCookie, createAuditEvent, createDoDCACConfig, createDoDCACDevConfig, decryptToken, deriveEncryptionKey, discoverOIDC, encryptToken, exchangeCodeForTokens, extractEDIPI, generateCodeChallenge, generateCodeVerifier, generateJti, generateNonce, generateState, getAuthDecorator, hasAuthConfig, maybeWrapWithAuth, parseCertFromHeaders, parseCertificate, parseCookies, refreshAccessToken, registerAuthDecorator, serializeCookie, signCertHeaders, useAuth, useRequireAuth, validateDoDCAC, validateIdToken, verifyCertHeaders, verifyState, withAuth, withAuthFallback };
+export { type AuditEvent, AuditEventType, type AuditLogger, AuthContext, type AuthContextValue, AuthProvider, type AuthProviderProps, type AuthorizationRequest, type BuildAuthorizationUrlOptions, CRLRevocationChecker, type CertRevocationChecker, type ComponentProps, CompositeAuditLogger, CompositeRevocationChecker, ConsoleAuditLogger, type CookieOptions, DOD_CAC_PROFILE, type HeaderSigningConfig, InMemoryRevocationStore, KeycloakAdapter, NoopAuditLogger, OCSPRevocationChecker, type OIDCMetadata, OIDCProvider, PKIProvider, type ParsedCertificate, RBACEngine, RevocationCache, type RevocationInput, type RevocationStatus, type RevocationStore, SessionManager, type SessionManagerConfig, SkipRevocationChecker, type TokenSet, buildAuthorizationUrl, clearCookie, createAuditEvent, createDoDCACConfig, createDoDCACDevConfig, createRevocationChecker, decryptToken, deriveEncryptionKey, discoverOIDC, encryptToken, exchangeCodeForTokens, extractEDIPI, generateCodeChallenge, generateCodeVerifier, generateJti, generateNonce, generateState, getAuthDecorator, hasAuthConfig, maybeWrapWithAuth, normalizeSerial, parseCertFromHeaders, parseCertificate, parseCookies, refreshAccessToken, registerAuthDecorator, serializeCookie, signCertHeaders, useAuth, useRequireAuth, validateDoDCAC, validateIdToken, verifyCertHeaders, verifyState, withAuth, withAuthFallback };