blendsdk 5.33.0

package/dist/webafx-auth/abstract-auth-provider.js

@@ -0,0 +1,240 @@
+/**
+ * Abstract base class for all authentication provider implementations.
+ *
+ * Provides the common authentication lifecycle (extract token → validate → return
+ * identity) and a configurable token extraction chain. Each concrete provider
+ * implements only the `validate()` method — everything else is shared.
+ *
+ * Design principles:
+ * - Application-wide singleton (not per-request)
+ * - Configurable token extraction chain (header, cookie, query, custom)
+ * - Silent failure pattern: invalid tokens return `undefined`, not throw
+ * - Infrastructure errors (network, DNS) are the only thrown exceptions
+ * - Claims mapping is pluggable via `mapClaims` config option
+ *
+ * @packageDocumentation
+ */
+import { DEFAULT_COOKIE_NAME, DEFAULT_QUERY_PARAM_NAME, DEFAULT_SERVICE_NAME, DEFAULT_TOKEN_SOURCES, } from "./types.js";
+/**
+ * Abstract base class for authentication providers.
+ *
+ * All auth backends (JWT, Introspection, OIDC, Tenant, Memory) derive from
+ * this class. Provides a configurable token extraction chain and a standard
+ * `authenticate()` lifecycle that concrete providers inherit without changes.
+ *
+ * Usage through concrete implementations:
+ * ```typescript
+ * const provider = new JwtAuthProvider({ secret: 'my-secret' });
+ * const result = await provider.authenticate(req);
+ * // result is AuthResult | undefined
+ * ```
+ */
+export class AuthProvider {
+    /** Service name for WebAFX service container registration */
+    _serviceName;
+    /**
+     * Ordered chain of token extractor functions.
+     * Built from the `tokenSources` config at construction time.
+     * Each function tries to extract a token from a different request location.
+     */
+    tokenExtractors;
+    /** Claims mapping function — transforms raw claims into AuthResult */
+    claimsMapper;
+    /** Cookie name used by the 'cookie' token source */
+    cookieName;
+    /** Query parameter name used by the 'query' token source */
+    queryParamName;
+    /**
+     * Initialize the auth provider with base configuration.
+     *
+     * Builds the token extraction chain from `tokenSources` config and
+     * sets up the claims mapper (custom or default).
+     *
+     * @param config - Base configuration with token sources, cookie name, etc.
+     */
+    constructor(config = {}) {
+        this._serviceName = config.serviceName ?? DEFAULT_SERVICE_NAME;
+        this.cookieName = config.cookieName ?? DEFAULT_COOKIE_NAME;
+        this.queryParamName = config.queryParamName ?? DEFAULT_QUERY_PARAM_NAME;
+        // Use custom claims mapper if provided, otherwise fall back to the default.
+        // The default mapper handles common JWT/OAuth2 claim formats (sub, exp, scope).
+        this.claimsMapper = config.mapClaims ?? this.defaultClaimsMapper;
+        // Build the ordered token extraction chain from config.
+        // Each source becomes a function that tries one extraction strategy.
+        this.tokenExtractors = this.buildExtractors(config.tokenSources ?? DEFAULT_TOKEN_SOURCES);
+    }
+    // -----------------------------------------------------------------------
+    // Public Accessors
+    // -----------------------------------------------------------------------
+    /** Get the service name used for WebAFX service container registration */
+    get serviceName() {
+        return this._serviceName;
+    }
+    // -----------------------------------------------------------------------
+    // Token Extraction (public — used by TenantAuthProvider and tests)
+    // -----------------------------------------------------------------------
+    /**
+     * Extract a raw token string from the request.
+     *
+     * Tries each configured token source in order (header → cookie → query → custom).
+     * Returns the first non-empty match, or `undefined` if no token is found.
+     * This is NOT an error — unauthenticated requests are normal for public routes.
+     *
+     * @param req - Express request object
+     * @returns The extracted token string, or undefined if no token found
+     */
+    extractToken(req) {
+        // Walk the extraction chain in priority order — first match wins.
+        // This allows applications to configure fallback strategies
+        // (e.g., try header first, then fall back to cookie for browser clients).
+        for (const extractor of this.tokenExtractors) {
+            const token = extractor(req);
+            if (token) {
+                return token;
+            }
+        }
+        return undefined;
+    }
+    // -----------------------------------------------------------------------
+    // Authentication Lifecycle (public — called by plugin middleware)
+    // -----------------------------------------------------------------------
+    /**
+     * Complete authentication flow: extract → validate → return result.
+     *
+     * This is the main entry point called by the plugin middleware on every
+     * request. It is implemented once in the base class and works for all
+     * providers — concrete providers only need to implement `validate()`.
+     *
+     * Returns `undefined` if:
+     * - No token found in the request (unauthenticated, not an error)
+     * - Token is invalid or expired (silent failure)
+     *
+     * Throws only on infrastructure failures (network errors, DNS failures).
+     *
+     * @param req - Express request object
+     * @returns AuthResult if authenticated, undefined otherwise
+     */
+    async authenticate(req) {
+        const token = this.extractToken(req);
+        if (!token) {
+            return undefined;
+        }
+        return this.validate(token);
+    }
+    // -----------------------------------------------------------------------
+    // Protected Helpers (used by concrete providers)
+    // -----------------------------------------------------------------------
+    /**
+     * Default claims mapper: extracts sub, exp, and scopes from raw claims.
+     *
+     * Handles multiple common claim formats:
+     * - `sub` or `subject` for the subject identifier
+     * - `exp` for expiration (numeric seconds since epoch)
+     * - `scope` (space-separated string) or `scopes` (array) for permissions
+     *
+     * Providers can override this by passing `mapClaims` in config.
+     *
+     * @param token - Original raw token string
+     * @param rawClaims - Raw claims object from token validation
+     * @returns Standardized AuthResult
+     */
+    defaultClaimsMapper(token, rawClaims) {
+        // Extract subject — try 'sub' first (OAuth2/JWT standard), then 'subject'
+        const sub = String(rawClaims.sub ?? rawClaims.subject ?? "unknown");
+        // Extract expiration — must be a numeric timestamp (seconds since epoch)
+        const exp = typeof rawClaims.exp === "number" ? rawClaims.exp : undefined;
+        // Extract scopes from various claim formats:
+        // - OAuth2 standard: "scope" as space-separated string (RFC 6749)
+        // - Some providers: "scopes" as array
+        // - Some providers: "scope" as array
+        let scopes;
+        if (typeof rawClaims.scope === "string") {
+            scopes = rawClaims.scope.split(" ").filter(Boolean);
+        }
+        else if (Array.isArray(rawClaims.scopes)) {
+            scopes = rawClaims.scopes.map(String);
+        }
+        else if (Array.isArray(rawClaims.scope)) {
+            scopes = rawClaims.scope.map(String);
+        }
+        return { sub, claims: rawClaims, token, exp, scopes };
+    }
+    // -----------------------------------------------------------------------
+    // Private Helpers (token extraction chain construction)
+    // -----------------------------------------------------------------------
+    /**
+     * Build the ordered token extractor chain from configuration.
+     *
+     * Each configured source becomes a function that attempts to extract
+     * a token from a specific request location. The resulting array is
+     * walked in order by `extractToken()`.
+     *
+     * @param sources - Configured token sources in priority order
+     * @returns Array of extractor functions
+     * @throws Error if an unknown token source type is provided
+     */
+    buildExtractors(sources) {
+        return sources.map((source) => {
+            if (source === "header") {
+                return (req) => this.extractFromHeader(req);
+            }
+            if (source === "cookie") {
+                return (req) => this.extractFromCookie(req);
+            }
+            if (source === "query") {
+                return (req) => this.extractFromQuery(req);
+            }
+            if (typeof source === "object" && source.extractor) {
+                return source.extractor;
+            }
+            throw new Error(`Unknown token source: ${JSON.stringify(source)}. ` +
+                `Supported: "header", "cookie", "query", or { extractor: fn }`);
+        });
+    }
+    /**
+     * Extract Bearer token from the Authorization header.
+     *
+     * Expects the format: `Authorization: Bearer <token>`
+     * Returns undefined if the header is missing or doesn't start with "Bearer ".
+     *
+     * @param req - Express request object
+     * @returns The token string without the "Bearer " prefix, or undefined
+     */
+    extractFromHeader(req) {
+        const authHeader = req.headers.authorization;
+        if (authHeader?.startsWith("Bearer ")) {
+            return authHeader.substring(7);
+        }
+        return undefined;
+    }
+    /**
+     * Extract token from a named cookie.
+     *
+     * Requires cookie-parser middleware to be installed (already built into
+     * WebAFX's core middleware). The cookie name is configured via `cookieName`
+     * (default: `'auth_token'`).
+     *
+     * @param req - Express request object
+     * @returns The cookie value as a string, or undefined
+     */
+    extractFromCookie(req) {
+        // req.cookies is populated by cookie-parser middleware.
+        // If cookie-parser is not installed, req.cookies will be undefined.
+        return req.cookies?.[this.cookieName];
+    }
+    /**
+     * Extract token from a query parameter.
+     *
+     * Useful for webhook callbacks, email verification links, and SSE endpoints
+     * where headers can't be set. The parameter name is configured via
+     * `queryParamName` (default: `'token'`).
+     *
+     * @param req - Express request object
+     * @returns The query parameter value as a string, or undefined
+     */
+    extractFromQuery(req) {
+        const value = req.query?.[this.queryParamName];
+        return typeof value === "string" ? value : undefined;
+    }
+}
+//# sourceMappingURL=abstract-auth-provider.js.map

package/dist/webafx-auth/abstract-auth-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"abstract-auth-provider.js","sourceRoot":"","sources":["../src/abstract-auth-provider.ts"],"names":[],"mappings":"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"}

package/dist/webafx-auth/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @blendsdk/webafx-auth — Token validation and authentication plugin for WebAFX
+ *
+ * Provides an abstract AuthProvider base class with a configurable token
+ * extraction chain and five concrete provider implementations:
+ *
+ * **Providers:**
+ * - AuthProvider (abstract) — base class with extract → validate → authenticate lifecycle
+ * - JwtAuthProvider — local JWT verification (HMAC/RSA via oauth4webapi)
+ * - IntrospectionAuthProvider — OAuth2 token introspection (RFC 7662) with cache
+ * - OidcAuthProvider — OIDC JWT validation with JWKS discovery (openid-client)
+ * - TenantAuthProvider — multi-tenant delegation with per-tenant providers
+ * - MemoryAuthProvider — testing mock with pre-configured valid tokens
+ *
+ * **Plugin integration:**
+ * - createAuthPlugin() — generic plugin from any AuthProvider
+ * - jwtAuthPlugin(), introspectionAuthPlugin(), oidcAuthPlugin(), etc.
+ * - createAuthProvider() — environment-based factory
+ *
+ * @packageDocumentation
+ */
+export type { AuthResult, AuthProviderConfig, JwtAuthConfig, IntrospectionAuthConfig, OidcAuthConfig, TenantAuthConfig, MemoryAuthConfig, AuthFactoryConfig, TokenSource, TokenExtractor, ClaimsMapper, TenantResolver, TenantProviderFactory, AuthProviderLike, } from "./types.js";
+export { DEFAULT_SERVICE_NAME, DEFAULT_PLUGIN_PRIORITY, DEFAULT_COOKIE_NAME, DEFAULT_QUERY_PARAM_NAME, DEFAULT_TOKEN_SOURCES, } from "./types.js";
+export { AuthProvider } from "./abstract-auth-provider.js";
+export { MemoryAuthProvider } from "./memory-auth-provider.js";
+export { JwtAuthProvider } from "./jwt-auth-provider.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/webafx-auth/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAKH,YAAY,EACR,UAAU,EACV,kBAAkB,EAClB,aAAa,EACb,uBAAuB,EACvB,cAAc,EACd,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,EACjB,WAAW,EACX,cAAc,EACd,YAAY,EACZ,cAAc,EACd,qBAAqB,EACrB,gBAAgB,GACnB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACH,oBAAoB,EACpB,uBAAuB,EACvB,mBAAmB,EACnB,wBAAwB,EACxB,qBAAqB,GACxB,MAAM,YAAY,CAAC;AAKpB,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAK3D,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/webafx-auth/index.js

@@ -0,0 +1,32 @@
+/**
+ * @blendsdk/webafx-auth — Token validation and authentication plugin for WebAFX
+ *
+ * Provides an abstract AuthProvider base class with a configurable token
+ * extraction chain and five concrete provider implementations:
+ *
+ * **Providers:**
+ * - AuthProvider (abstract) — base class with extract → validate → authenticate lifecycle
+ * - JwtAuthProvider — local JWT verification (HMAC/RSA via oauth4webapi)
+ * - IntrospectionAuthProvider — OAuth2 token introspection (RFC 7662) with cache
+ * - OidcAuthProvider — OIDC JWT validation with JWKS discovery (openid-client)
+ * - TenantAuthProvider — multi-tenant delegation with per-tenant providers
+ * - MemoryAuthProvider — testing mock with pre-configured valid tokens
+ *
+ * **Plugin integration:**
+ * - createAuthPlugin() — generic plugin from any AuthProvider
+ * - jwtAuthPlugin(), introspectionAuthPlugin(), oidcAuthPlugin(), etc.
+ * - createAuthProvider() — environment-based factory
+ *
+ * @packageDocumentation
+ */
+export { DEFAULT_SERVICE_NAME, DEFAULT_PLUGIN_PRIORITY, DEFAULT_COOKIE_NAME, DEFAULT_QUERY_PARAM_NAME, DEFAULT_TOKEN_SOURCES, } from "./types.js";
+// ---------------------------------------------------------------------------
+// Abstract Base Class
+// ---------------------------------------------------------------------------
+export { AuthProvider } from "./abstract-auth-provider.js";
+// ---------------------------------------------------------------------------
+// Concrete Providers
+// ---------------------------------------------------------------------------
+export { MemoryAuthProvider } from "./memory-auth-provider.js";
+export { JwtAuthProvider } from "./jwt-auth-provider.js";
+//# sourceMappingURL=index.js.map

package/dist/webafx-auth/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAsBH,OAAO,EACH,oBAAoB,EACpB,uBAAuB,EACvB,mBAAmB,EACnB,wBAAwB,EACxB,qBAAqB,GACxB,MAAM,YAAY,CAAC;AAEpB,8EAA8E;AAC9E,sBAAsB;AACtB,8EAA8E;AAC9E,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAE3D,8EAA8E;AAC9E,qBAAqB;AACrB,8EAA8E;AAC9E,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/webafx-auth/jwt-auth-provider.d.ts

@@ -0,0 +1,100 @@
+/**
+ * JWT authentication provider for self-issued token verification.
+ *
+ * Validates JWTs locally using HMAC or RSA/EC keys via the `jose` library.
+ * No network calls required — verification is a pure cryptographic operation.
+ *
+ * Supports:
+ * - **HMAC** (HS256, HS384, HS512) — string secrets
+ * - **RSA/EC** (RS256, ES256, etc.) — CryptoKey public keys
+ * - Issuer validation (`iss` claim)
+ * - Audience validation (`aud` claim)
+ * - Clock tolerance for `exp`/`nbf` checks
+ *
+ * @example
+ * ```typescript
+ * const provider = new JwtAuthProvider({
+ *     secret: 'my-256-bit-secret',
+ *     algorithms: ['HS256'],
+ *     issuer: 'https://api.example.com',
+ *     audience: 'my-client-id',
+ *     clockTolerance: 5,
+ * });
+ *
+ * const result = await provider.authenticate(req);
+ * // result is AuthResult if JWT is valid, undefined otherwise
+ * ```
+ *
+ * @packageDocumentation
+ */
+import { AuthProvider } from "./abstract-auth-provider.js";
+import type { AuthResult, JwtAuthConfig } from "./types.js";
+/**
+ * JWT authentication provider using the `jose` library.
+ *
+ * Verifies JWT signatures locally — no network calls needed. Supports both
+ * symmetric (HMAC) and asymmetric (RSA, EC) algorithms. The signing key is
+ * lazily converted to the format `jose` expects on first use.
+ *
+ * Invalid or expired tokens silently return `undefined` (not throw).
+ * Only truly unexpected errors (e.g., corrupt CryptoKey) propagate as exceptions.
+ */
+export declare class JwtAuthProvider extends AuthProvider {
+    /** Provider configuration */
+    protected config: JwtAuthConfig;
+    /**
+     * Cached key in the format jose expects.
+     * For string secrets (HMAC): encoded as Uint8Array.
+     * For CryptoKey (RSA/EC): used directly.
+     * Lazy-initialized on first validate() call.
+     */
+    protected resolvedKey: CryptoKey | Uint8Array | null;
+    /**
+     * Create a new JWT auth provider.
+     *
+     * @param config - JWT configuration with secret/key, algorithms, issuer, audience
+     */
+    constructor(config: JwtAuthConfig);
+    /**
+     * Validate a JWT by verifying its signature, expiration, and claims.
+     *
+     * Uses `jose.jwtVerify()` which checks:
+     * - Signature against the configured secret/key
+     * - `exp` claim (token not expired, with clock tolerance)
+     * - `nbf` claim (token not used before valid time)
+     * - `iss` claim (if issuer is configured)
+     * - `aud` claim (if audience is configured)
+     *
+     * @param token - Raw JWT string (header.payload.signature)
+     * @returns AuthResult if valid, undefined if invalid/expired
+     */
+    validate(token: string): Promise<AuthResult | undefined>;
+    /**
+     * Health check — verifies that the signing secret/key is configured.
+     *
+     * JWT verification is a local CPU operation with no external dependencies,
+     * so health only checks that the key material is present.
+     *
+     * @returns true if a secret or key is configured
+     */
+    health(): Promise<boolean>;
+    /**
+     * Graceful shutdown — releases the cached CryptoKey.
+     *
+     * After shutdown, the key will be re-created on next `validate()` call.
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Get or create the signing key in jose-compatible format.
+     *
+     * For string secrets (HMAC): encodes to Uint8Array using TextEncoder.
+     * For CryptoKey (RSA/EC): uses the key directly as-is.
+     *
+     * The result is cached for the lifetime of the provider to avoid
+     * repeated encoding on every request.
+     *
+     * @returns The key in a format jose's jwtVerify() accepts
+     */
+    protected getOrCreateKey(): CryptoKey | Uint8Array;
+}
+//# sourceMappingURL=jwt-auth-provider.d.ts.map

package/dist/webafx-auth/jwt-auth-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jwt-auth-provider.d.ts","sourceRoot":"","sources":["../src/jwt-auth-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAKH,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAC3D,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE5D;;;;;;;;;GASG;AACH,qBAAa,eAAgB,SAAQ,YAAY;IAC7C,6BAA6B;IAC7B,SAAS,CAAC,MAAM,EAAE,aAAa,CAAC;IAEhC;;;;;OAKG;IACH,SAAS,CAAC,WAAW,EAAE,SAAS,GAAG,UAAU,GAAG,IAAI,CAAQ;IAE5D;;;;OAIG;gBACS,MAAM,EAAE,aAAa;IASjC;;;;;;;;;;;;OAYG;IACG,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC;IAsC9D;;;;;;;OAOG;IACG,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC;IAIhC;;;;OAIG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ/B;;;;;;;;;;OAUG;IACH,SAAS,CAAC,cAAc,IAAI,SAAS,GAAG,UAAU;CAkBrD"}

package/dist/webafx-auth/jwt-auth-provider.js

@@ -0,0 +1,154 @@
+/**
+ * JWT authentication provider for self-issued token verification.
+ *
+ * Validates JWTs locally using HMAC or RSA/EC keys via the `jose` library.
+ * No network calls required — verification is a pure cryptographic operation.
+ *
+ * Supports:
+ * - **HMAC** (HS256, HS384, HS512) — string secrets
+ * - **RSA/EC** (RS256, ES256, etc.) — CryptoKey public keys
+ * - Issuer validation (`iss` claim)
+ * - Audience validation (`aud` claim)
+ * - Clock tolerance for `exp`/`nbf` checks
+ *
+ * @example
+ * ```typescript
+ * const provider = new JwtAuthProvider({
+ *     secret: 'my-256-bit-secret',
+ *     algorithms: ['HS256'],
+ *     issuer: 'https://api.example.com',
+ *     audience: 'my-client-id',
+ *     clockTolerance: 5,
+ * });
+ *
+ * const result = await provider.authenticate(req);
+ * // result is AuthResult if JWT is valid, undefined otherwise
+ * ```
+ *
+ * @packageDocumentation
+ */
+import { jwtVerify } from "jose";
+import { AuthProvider } from "./abstract-auth-provider.js";
+/**
+ * JWT authentication provider using the `jose` library.
+ *
+ * Verifies JWT signatures locally — no network calls needed. Supports both
+ * symmetric (HMAC) and asymmetric (RSA, EC) algorithms. The signing key is
+ * lazily converted to the format `jose` expects on first use.
+ *
+ * Invalid or expired tokens silently return `undefined` (not throw).
+ * Only truly unexpected errors (e.g., corrupt CryptoKey) propagate as exceptions.
+ */
+export class JwtAuthProvider extends AuthProvider {
+    /** Provider configuration */
+    config;
+    /**
+     * Cached key in the format jose expects.
+     * For string secrets (HMAC): encoded as Uint8Array.
+     * For CryptoKey (RSA/EC): used directly.
+     * Lazy-initialized on first validate() call.
+     */
+    resolvedKey = null;
+    /**
+     * Create a new JWT auth provider.
+     *
+     * @param config - JWT configuration with secret/key, algorithms, issuer, audience
+     */
+    constructor(config) {
+        super(config);
+        this.config = config;
+    }
+    // -----------------------------------------------------------------------
+    // Abstract Method Implementations
+    // -----------------------------------------------------------------------
+    /**
+     * Validate a JWT by verifying its signature, expiration, and claims.
+     *
+     * Uses `jose.jwtVerify()` which checks:
+     * - Signature against the configured secret/key
+     * - `exp` claim (token not expired, with clock tolerance)
+     * - `nbf` claim (token not used before valid time)
+     * - `iss` claim (if issuer is configured)
+     * - `aud` claim (if audience is configured)
+     *
+     * @param token - Raw JWT string (header.payload.signature)
+     * @returns AuthResult if valid, undefined if invalid/expired
+     */
+    async validate(token) {
+        try {
+            const key = this.getOrCreateKey();
+            // Build verification options from config.
+            // jose uses these to validate standard JWT claims after
+            // signature verification succeeds.
+            const options = {
+                algorithms: this.config.algorithms ?? ["HS256"],
+                clockTolerance: this.config.clockTolerance ?? 0,
+            };
+            // Only set issuer/audience if configured — undefined means "don't check"
+            if (this.config.issuer) {
+                options.issuer = this.config.issuer;
+            }
+            if (this.config.audience) {
+                options.audience = this.config.audience;
+            }
+            const result = await jwtVerify(token, key, options);
+            // Map the verified JWT payload to our standardized AuthResult format
+            return this.claimsMapper(token, result.payload);
+        }
+        catch {
+            // Any verification failure (bad signature, expired, wrong issuer, malformed)
+            // returns undefined — the silent failure pattern.
+            return undefined;
+        }
+    }
+    /**
+     * Health check — verifies that the signing secret/key is configured.
+     *
+     * JWT verification is a local CPU operation with no external dependencies,
+     * so health only checks that the key material is present.
+     *
+     * @returns true if a secret or key is configured
+     */
+    async health() {
+        return this.config.secret !== undefined && this.config.secret !== null;
+    }
+    /**
+     * Graceful shutdown — releases the cached CryptoKey.
+     *
+     * After shutdown, the key will be re-created on next `validate()` call.
+     */
+    async shutdown() {
+        this.resolvedKey = null;
+    }
+    // -----------------------------------------------------------------------
+    // Protected Helpers
+    // -----------------------------------------------------------------------
+    /**
+     * Get or create the signing key in jose-compatible format.
+     *
+     * For string secrets (HMAC): encodes to Uint8Array using TextEncoder.
+     * For CryptoKey (RSA/EC): uses the key directly as-is.
+     *
+     * The result is cached for the lifetime of the provider to avoid
+     * repeated encoding on every request.
+     *
+     * @returns The key in a format jose's jwtVerify() accepts
+     */
+    getOrCreateKey() {
+        if (this.resolvedKey) {
+            return this.resolvedKey;
+        }
+        const { secret } = this.config;
+        if (typeof secret === "string") {
+            // HMAC secrets: encode the string to bytes for jose.
+            // jose accepts Uint8Array for symmetric algorithms (HS256/384/512).
+            this.resolvedKey = new TextEncoder().encode(secret);
+        }
+        else {
+            // CryptoKey: use directly for asymmetric algorithms (RS256, ES256, etc.)
+            this.resolvedKey = secret;
+        }
+        return this.resolvedKey;
+    }
+}
+//# sourceMappingURL=jwt-auth-provider.js.map

package/dist/webafx-auth/jwt-auth-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jwt-auth-provider.js","sourceRoot":"","sources":["../src/jwt-auth-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,MAAM,CAAC;AAGjC,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAG3D;;;;;;;;;GASG;AACH,MAAM,OAAO,eAAgB,SAAQ,YAAY;IAC7C,6BAA6B;IACnB,MAAM,CAAgB;IAEhC;;;;;OAKG;IACO,WAAW,GAAkC,IAAI,CAAC;IAE5D;;;;OAIG;IACH,YAAY,MAAqB;QAC7B,KAAK,CAAC,MAAM,CAAC,CAAC;QACd,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACzB,CAAC;IAED,0EAA0E;IAC1E,kCAAkC;IAClC,0EAA0E;IAE1E;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,QAAQ,CAAC,KAAa;QACxB,IAAI,CAAC;YACD,MAAM,GAAG,GAAG,IAAI,CAAC,cAAc,EAAE,CAAC;YAElC,0CAA0C;YAC1C,wDAAwD;YACxD,mCAAmC;YACnC,MAAM,OAAO,GAAoC;gBAC7C,UAAU,EAAE,IAAI,CAAC,MAAM,CAAC,UAAU,IAAI,CAAC,OAAO,CAAC;gBAC/C,cAAc,EAAE,IAAI,CAAC,MAAM,CAAC,cAAc,IAAI,CAAC;aAClD,CAAC;YAEF,yEAAyE;YACzE,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;gBACrB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC;YACxC,CAAC;YACD,IAAI,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC;gBACvB,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC;YAC5C,CAAC;YAED,MAAM,MAAM,GAAoB,MAAM,SAAS,CAC3C,KAAK,EACL,GAAG,EACH,OAAO,CACV,CAAC;YAEF,qEAAqE;YACrE,OAAO,IAAI,CAAC,YAAY,CACpB,KAAK,EACL,MAAM,CAAC,OAAkC,CAC5C,CAAC;QACN,CAAC;QAAC,MAAM,CAAC;YACL,6EAA6E;YAC7E,kDAAkD;YAClD,OAAO,SAAS,CAAC;QACrB,CAAC;IACL,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,MAAM;QACR,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,KAAK,SAAS,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,KAAK,IAAI,CAAC;IAC3E,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,QAAQ;QACV,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC;IAC5B,CAAC;IAED,0EAA0E;IAC1E,oBAAoB;IACpB,0EAA0E;IAE1E;;;;;;;;;;OAUG;IACO,cAAc;QACpB,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;YACnB,OAAO,IAAI,CAAC,WAAW,CAAC;QAC5B,CAAC;QAED,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC;QAE/B,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;YAC7B,qDAAqD;YACrD,oEAAoE;YACpE,IAAI,CAAC,WAAW,GAAG,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QACxD,CAAC;aAAM,CAAC;YACJ,yEAAyE;YACzE,IAAI,CAAC,WAAW,GAAG,MAAM,CAAC;QAC9B,CAAC;QAED,OAAO,IAAI,CAAC,WAAW,CAAC;IAC5B,CAAC;CACJ"}