@serialsubscriptions/platform-integration 0.0.8-5.1

package/lib/auth.server.js

@@ -0,0 +1,624 @@
+"use strict";
+// packages/platform-integration/src/auth.server.ts
+// Production-grade JWT verification using jose library
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AuthServer = exports.scopes = void 0;
+exports.isJwtExpired = isJwtExpired;
+exports.getJwtExpirySeconds = getJwtExpirySeconds;
+const crypto = __importStar(require("crypto"));
+const jose_1 = require("jose");
+const stateStore_1 = require("./stateStore");
+const SSICache_1 = require("./cache/SSICache");
+const constants_1 = require("./cache/constants");
+const requestConfig_1 = require("./requestConfig");
+exports.scopes = {
+    defaultScopes: "openid profile email view_project create_project delete_project update_project view_subscribed_plan view_subscribed_feature view_subscribed_limit access_subscription_usage"
+};
+// Helper to normalize issuer URLs by removing trailing slashes
+function normalizeIssuer(url) {
+    return url.replace(/\/+$/, "");
+}
+/**
+ * Check if a JWT is expired (or within bufferSeconds of expiry) by decoding its payload.
+ * Does not verify the signature — use only for expiry checks (e.g. "should I refresh?").
+ * For authorization, use AuthServer.verifyJwt() or verifyAndDecodeJwt().
+ *
+ * @param jwt - The JWT string (e.g. access_token or id_token from session).
+ * @param bufferSeconds - If provided, treat the token as "expired" when it would expire within this many seconds (default: 0).
+ * @returns true if the token is expired (or expiring within bufferSeconds), or if the JWT is missing/invalid; false otherwise.
+ */
+function isJwtExpired(jwt, bufferSeconds = 0) {
+    try {
+        const payload = (0, jose_1.decodeJwt)(jwt);
+        const exp = payload.exp;
+        if (typeof exp !== "number")
+            return false; // no exp claim → not expired
+        const now = Math.floor(Date.now() / 1000);
+        return exp <= now + bufferSeconds;
+    }
+    catch {
+        return true; // malformed or missing → treat as expired
+    }
+}
+/**
+ * Get the number of seconds until a JWT expires, by decoding its payload.
+ * Does not verify the signature. For authorization use AuthServer.verifyJwt().
+ *
+ * @param jwt - The JWT string.
+ * @returns Seconds until expiry (0 if already expired), or null if the JWT has no exp claim or is invalid.
+ */
+function getJwtExpirySeconds(jwt) {
+    try {
+        const payload = (0, jose_1.decodeJwt)(jwt);
+        const exp = payload.exp;
+        if (typeof exp !== "number")
+            return null;
+        const now = Math.floor(Date.now() / 1000);
+        return Math.max(0, exp - now);
+    }
+    catch {
+        return null;
+    }
+}
+class AuthServer {
+    /** Accepts AuthConfig or SSIRequestConfig (e.g. from getRequestConfig(req)). */
+    constructor(config) {
+        const cfg = (0, requestConfig_1.normalizeAuthConfig)(config) ?? {};
+        let scopesString;
+        if (cfg.scopes === undefined || cfg.scopes === null) {
+            scopesString = exports.scopes.defaultScopes;
+        }
+        else if (Array.isArray(cfg.scopes)) {
+            scopesString = cfg.scopes.length > 0 ? cfg.scopes.join(" ") : exports.scopes.defaultScopes;
+        }
+        else {
+            scopesString = cfg.scopes.trim() || exports.scopes.defaultScopes;
+        }
+        // Get values from config or fall back to environment variables
+        const issuerBaseUrlRaw = cfg.issuerBaseUrl ?? process.env.SSI_ISSUER_BASE_URL ?? "";
+        const clientId = cfg.clientId ?? process.env.SSI_CLIENT_ID ?? "";
+        const clientSecret = cfg.clientSecret ?? process.env.SSI_CLIENT_SECRET ?? "";
+        const redirectUriRaw = cfg.redirectUri ?? process.env.SSI_REDIRECT_URI ?? "";
+        const jwksPath = cfg.jwksPath ?? process.env.SSI_ISSUER_JWKS_PATH ?? "/.well-known/jwks.json";
+        // Validate required values
+        if (!issuerBaseUrlRaw) {
+            throw new Error("issuerBaseUrl is required. Provide it in config or set SSI_ISSUER_BASE_URL environment variable.");
+        }
+        if (!clientId) {
+            throw new Error("clientId is required. Provide it in config or set SSI_CLIENT_ID environment variable.");
+        }
+        // Create both normalized forms (with and without trailing slash)
+        // This allows JWT validation to succeed regardless of how the issuer formats their iss claim
+        const issuerNoSlash = normalizeIssuer(issuerBaseUrlRaw);
+        const issuerWithSlash = issuerNoSlash + "/";
+        const issuerAccepted = [issuerNoSlash, issuerWithSlash];
+        // Normalize redirectUri using URL class
+        const redirectUri = redirectUriRaw ? new URL(redirectUriRaw).toString() : "";
+        // Normalize jwksUri if provided, otherwise construct it
+        const jwksUri = cfg.jwksUri
+            ? (cfg.jwksUri.startsWith('http://') || cfg.jwksUri.startsWith('https://'))
+                ? new URL(cfg.jwksUri).toString()
+                : new URL(cfg.jwksUri, issuerNoSlash).toString()
+            : `${issuerNoSlash}${jwksPath.startsWith("/") ? jwksPath : `/${jwksPath}`}`;
+        // Resolve logout endpoint: config > full URL env > issuer + path env > default /user/logout
+        const logoutPathEnv = process.env.SSI_ISSUER_LOGOUT_PATH?.trim();
+        const logoutEndpointEnv = process.env.SSI_LOGOUT_ENDPOINT?.trim();
+        const resolvedLogoutEndpointRaw = cfg.logoutEndpoint
+            ?? (logoutEndpointEnv || `${issuerNoSlash}${logoutPathEnv ? (logoutPathEnv.startsWith('/') ? logoutPathEnv : `/${logoutPathEnv}`) : '/user/logout'}`);
+        // Normalize logout endpoint using URL class (handle relative paths by constructing relative to issuer)
+        const resolvedLogoutEndpoint = resolvedLogoutEndpointRaw
+            ? (resolvedLogoutEndpointRaw.startsWith('http://') || resolvedLogoutEndpointRaw.startsWith('https://'))
+                ? new URL(resolvedLogoutEndpointRaw).toString()
+                : new URL(resolvedLogoutEndpointRaw, issuerNoSlash).toString()
+            : "";
+        // Normalize authorization and token endpoints if provided, otherwise construct them
+        const authorizationEndpoint = cfg.authorizationEndpoint
+            ? (cfg.authorizationEndpoint.startsWith('http://') || cfg.authorizationEndpoint.startsWith('https://'))
+                ? new URL(cfg.authorizationEndpoint).toString()
+                : new URL(cfg.authorizationEndpoint, issuerNoSlash).toString()
+            : `${issuerNoSlash}/oauth/authorize`;
+        const tokenEndpoint = cfg.tokenEndpoint
+            ? (cfg.tokenEndpoint.startsWith('http://') || cfg.tokenEndpoint.startsWith('https://'))
+                ? new URL(cfg.tokenEndpoint).toString()
+                : new URL(cfg.tokenEndpoint, issuerNoSlash).toString()
+            : `${issuerNoSlash}/oauth/token`;
+        this.cfg = {
+            issuerBaseUrl: issuerBaseUrlRaw, // keep as provided for URLs we build
+            authorizationEndpoint,
+            tokenEndpoint,
+            logoutEndpoint: resolvedLogoutEndpoint,
+            jwksUri,
+            jwks: cfg.jwks,
+            clientId,
+            clientSecret,
+            redirectUri,
+            audience: cfg.audience ?? "",
+            scopes: scopesString,
+            issuerAccepted, // Both forms accepted for JWT validation
+        };
+        // Initialize state storage: use provided storage or default from environment
+        this.stateStorage = cfg.storage
+            ? cfg.storage.withClass('state')
+            : stateStore_1.stateStorage;
+        // Initialize JWKS cache with "jwks" prefix
+        this.jwksCache = SSICache_1.SSICache.fromEnv().withPrefix('jwks');
+    }
+    /**
+     * Build the authorization URL and persist a CSRF state for the callback.
+     * Returns: { url, stateKey, stateValue }
+     */
+    async getLoginUrl(opts = {}) {
+        const stateKey = opts.stateKey ?? crypto.randomUUID();
+        const stateValue = crypto.randomUUID(); // CSRF token value
+        await this.stateStorage.set(stateKey, 'value', stateValue, opts.stateTtlSeconds ?? 600);
+        const u = new URL(this.cfg.authorizationEndpoint);
+        u.searchParams.set("response_type", "code");
+        u.searchParams.set("client_id", this.cfg.clientId);
+        u.searchParams.set("redirect_uri", this.cfg.redirectUri);
+        u.searchParams.set("scope", this.cfg.scopes);
+        u.searchParams.set("state", `${stateKey}:${stateValue}`);
+        if (this.cfg.audience)
+            u.searchParams.set("audience", this.cfg.audience);
+        if (opts.extraParams) {
+            for (const [k, v] of Object.entries(opts.extraParams))
+                u.searchParams.set(k, v);
+        }
+        return { url: u.toString(), stateKey, stateValue };
+    }
+    /**
+     * Build the logout URL for RP-initiated logout.
+     * Common params: id_token_hint, post_logout_redirect_uri
+     */
+    getLogoutUrl(opts = {}) {
+        // Ensure logout URL uses the same origin as the authorization endpoint
+        const authOrigin = new URL(this.cfg.authorizationEndpoint).origin;
+        const configured = this.cfg.logoutEndpoint;
+        let u;
+        if (configured && /^https?:\/\//i.test(configured)) {
+            const tmp = new URL(configured);
+            u = new URL(tmp.pathname + tmp.search, authOrigin);
+        }
+        else {
+            const path = configured && configured.length > 0
+                ? (configured.startsWith('/') ? configured : `/${configured}`)
+                : '/user/logout';
+            u = new URL(path, authOrigin);
+        }
+        if (opts.idTokenHint)
+            u.searchParams.set('id_token_hint', opts.idTokenHint);
+        // Use provided postLogoutRedirectUri, or default to NEXT_PUBLIC_APP_URL if available
+        const postLogoutRedirectUriRaw = opts.postLogoutRedirectUri ?? process.env.NEXT_PUBLIC_APP_URL;
+        if (postLogoutRedirectUriRaw) {
+            // Normalize the URL using URL class
+            const normalizedPostLogoutUri = new URL(postLogoutRedirectUriRaw).toString();
+            u.searchParams.set('post_logout_redirect_uri', normalizedPostLogoutUri);
+        }
+        if (opts.extraParams) {
+            for (const [k, v] of Object.entries(opts.extraParams))
+                u.searchParams.set(k, v);
+        }
+        return { url: u.toString() };
+    }
+    /**
+     * Handle the OAuth callback: validates state and exchanges the code for tokens.
+     * Returns TokenResponse (and includes raw for debugging).
+     */
+    async handleCallback(params) {
+        const code = params.code ?? "";
+        const state = params.state ?? "";
+        if (!code || !state) {
+            throw new Error("Missing code or state.");
+        }
+        // State validation
+        // Expect state to be `${stateKey}:${stateValue}`
+        // Use split(":", 2) to only split on the first colon, in case stateValue somehow contains colons
+        const parts = state.split(":", 2);
+        if (parts.length !== 2 || !parts[0] || !parts[1]) {
+            throw new Error(`Invalid state format. Expected "stateKey:stateValue", got: ${state.substring(0, 100)}`);
+        }
+        const [stateKey, stateValue] = parts;
+        const storedValue = await this.stateStorage.get(stateKey, 'value');
+        const expected = storedValue === null ? undefined : storedValue;
+        if (!expected) {
+            throw new Error(`Invalid or expired state. State key "${stateKey}" not found in store. This usually means the state has expired or was never stored.`);
+        }
+        if (expected !== stateValue) {
+            throw new Error(`Invalid state. State value mismatch for key "${stateKey}". Expected "${expected}", got "${stateValue}".`);
+        }
+        await this.stateStorage.del(stateKey, 'value');
+        // Token exchange (authorization_code)
+        const body = new URLSearchParams({
+            grant_type: "authorization_code",
+            code,
+            redirect_uri: this.cfg.redirectUri,
+            client_id: this.cfg.clientId,
+        });
+        // Confidential client uses client_secret_post for PoC
+        if (this.cfg.clientSecret) {
+            body.set("client_secret", this.cfg.clientSecret);
+        }
+        const resp = await fetch(this.cfg.tokenEndpoint, {
+            method: "POST",
+            headers: { "content-type": "application/x-www-form-urlencoded" },
+            body,
+        });
+        if (!resp.ok) {
+            const txt = await resp.text().catch(() => "");
+            throw new Error(`Token endpoint error (${resp.status}): ${txt}`);
+        }
+        const json = await resp.json();
+        // Verify ID token if present
+        let idClaims;
+        if (json.id_token) {
+            idClaims = await this.verifyWithIssuer(json.id_token);
+        }
+        // Verify access token if it's a JWT (3 parts)
+        let accessClaims;
+        if (json.access_token && json.access_token.split(".").length === 3) {
+            try {
+                accessClaims = await this.verifyWithIssuer(json.access_token);
+            }
+            catch {
+                // opaque or differently signed; ignore for now
+            }
+        }
+        const out = {
+            access_token: json.access_token,
+            id_token: json.id_token,
+            token_type: json.token_type,
+            refresh_token: json.refresh_token,
+            expires_in: json.expires_in,
+            scope: json.scope,
+            raw: json,
+            id_claims: idClaims,
+            access_claims: accessClaims,
+        };
+        this.lastTokens = out;
+        return out;
+    }
+    /**
+     * Exchange a refresh_token for new tokens.
+     * Verifies any returned JWTs and returns a TokenResponse.
+     *
+     * @param refreshToken - The refresh token to exchange for new tokens
+     * @param options - Optional parameters for the refresh request
+     * @param options.scope - Optional scope parameter (cannot exceed originally granted scope)
+     * @param options.useAuthHeader - Use Authorization header instead of client_secret in body
+     * @returns Promise<TokenResponse> - New tokens with verified claims
+     */
+    async refreshTokens(refreshToken, options = {}) {
+        if (!refreshToken)
+            throw new Error("Missing refresh_token");
+        const body = new URLSearchParams({
+            grant_type: "refresh_token",
+            refresh_token: refreshToken,
+            client_id: this.cfg.clientId,
+        });
+        // Add scope if provided
+        if (options.scope) {
+            body.set("scope", options.scope);
+        }
+        // Prepare headers
+        const headers = {
+            "content-type": "application/x-www-form-urlencoded"
+        };
+        // Handle client authentication
+        if (this.cfg.clientSecret) {
+            if (options.useAuthHeader) {
+                // Use Authorization header (Basic auth with base64 encoded client_id:client_secret)
+                const credentials = Buffer.from(`${this.cfg.clientId}:${this.cfg.clientSecret}`).toString('base64');
+                headers["authorization"] = `Basic ${credentials}`;
+            }
+            else {
+                // Use client_secret in body (default behavior)
+                body.set("client_secret", this.cfg.clientSecret);
+            }
+        }
+        const resp = await fetch(this.cfg.tokenEndpoint, {
+            method: "POST",
+            headers,
+            body,
+        });
+        if (!resp.ok) {
+            const txt = await resp.text().catch(() => "");
+            let errorMessage = `Token endpoint error (${resp.status}): ${txt}`;
+            // Try to parse OAuth error response for better error messages
+            try {
+                const errorJson = JSON.parse(txt);
+                if (errorJson.error) {
+                    errorMessage = `OAuth error (${errorJson.error}): ${errorJson.error_description || errorJson.error}`;
+                    // Handle specific OAuth errors
+                    if (errorJson.error === "invalid_grant") {
+                        errorMessage += " - The refresh token is invalid or expired. User needs to re-authenticate.";
+                    }
+                    else if (errorJson.error === "invalid_client") {
+                        errorMessage += " - Client authentication failed. Check client_id and client_secret.";
+                    }
+                    else if (errorJson.error === "invalid_scope") {
+                        errorMessage += " - The requested scope is invalid or exceeds the originally granted scope.";
+                    }
+                }
+            }
+            catch {
+                // If JSON parsing fails, use the original error message
+            }
+            throw new Error(errorMessage);
+        }
+        const json = await resp.json();
+        // Verify ID token if present
+        let idClaims;
+        if (json.id_token) {
+            try {
+                idClaims = await this.verifyWithIssuer(json.id_token);
+            }
+            catch (error) {
+                throw new Error(`ID token verification failed: ${error instanceof Error ? error.message : 'Unknown error'}`);
+            }
+        }
+        // Verify access token if it's a JWT (3 parts)
+        let accessClaims;
+        if (json.access_token && json.access_token.split(".").length === 3) {
+            try {
+                accessClaims = await this.verifyWithIssuer(json.access_token);
+            }
+            catch (error) {
+                // Log warning but don't fail - access token might be opaque
+                console.warn(`Access token verification failed (may be opaque): ${error instanceof Error ? error.message : 'Unknown error'}`);
+            }
+        }
+        const out = {
+            access_token: json.access_token,
+            id_token: json.id_token,
+            token_type: json.token_type,
+            refresh_token: json.refresh_token,
+            expires_in: json.expires_in,
+            scope: json.scope,
+            raw: json,
+            id_claims: idClaims,
+            access_claims: accessClaims,
+        };
+        this.lastTokens = out;
+        return out;
+    }
+    /**
+     * Fetch and cache JWKS from the remote endpoint.
+     * Uses SSICache to cache the JWKS response.
+     * @private
+     */
+    async fetchAndCacheJWKS() {
+        const cacheKey = this.cfg.jwksUri;
+        // Use remember to get from cache or fetch and cache
+        const jwks = await this.jwksCache.remember(cacheKey, constants_1.TTL_JWKS, async () => {
+            // Fetch JWKS from remote endpoint
+            const response = await fetch(this.cfg.jwksUri);
+            if (!response.ok) {
+                throw new Error(`Failed to fetch JWKS from ${this.cfg.jwksUri}: ${response.status} ${response.statusText}`);
+            }
+            const jwksData = await response.json();
+            // Validate JWKS structure
+            if (!jwksData || !Array.isArray(jwksData.keys)) {
+                throw new Error(`Invalid JWKS structure from ${this.cfg.jwksUri}`);
+            }
+            return jwksData;
+        });
+        return jwks;
+    }
+    /**
+     * Verify JWT signature and claims using jose library.
+     * Handles JWKS fetching, caching, kid selection, and algorithm validation.
+     * @private
+     */
+    async verifyWithIssuer(jwt) {
+        // If static JWKS provided, use jose's importJWK for each key
+        if (this.cfg.jwks && Array.isArray(this.cfg.jwks.keys)) {
+            // For static JWKS, we need to import and try each key
+            for (const key of this.cfg.jwks.keys) {
+                try {
+                    const publicKey = await (0, jose_1.importJWK)(key, "RS256");
+                    const { payload } = await (0, jose_1.jwtVerify)(jwt, publicKey, {
+                        issuer: this.cfg.issuerAccepted,
+                        audience: this.cfg.clientId,
+                        algorithms: ["RS256"],
+                    });
+                    return payload;
+                }
+                catch {
+                    // Try next key
+                    continue;
+                }
+            }
+            throw new Error("No valid JWK found in static JWKS");
+        }
+        // Fetch and cache JWKS from remote endpoint
+        const jwks = await this.fetchAndCacheJWKS();
+        // Try each key in the JWKS
+        for (const key of jwks.keys) {
+            try {
+                const publicKey = await (0, jose_1.importJWK)(key, "RS256");
+                const { payload } = await (0, jose_1.jwtVerify)(jwt, publicKey, {
+                    issuer: this.cfg.issuerAccepted,
+                    audience: this.cfg.clientId,
+                    algorithms: ["RS256"],
+                });
+                return payload;
+            }
+            catch {
+                // Try next key
+                continue;
+            }
+        }
+        throw new Error("No valid JWK found in JWKS to verify the JWT");
+    }
+    /**
+     * Public method to verify a JWT.
+     * Use this in middleware or anywhere you need to validate tokens.
+     */
+    async verifyJwt(jwt) {
+        const claims = await this.verifyWithIssuer(jwt);
+        return claims;
+    }
+    /**
+     * Verify and decode a JWT before returning its claims.
+     * Throws if the JWT is invalid, expired, or fails signature verification.
+     *
+     * This method is safe to use in middleware or debugging contexts when you
+     * simply need the decoded, verified claims from a JWT string.
+     */
+    async verifyAndDecodeJwt(jwt) {
+        if (!jwt)
+            throw new Error("Missing JWT");
+        const parts = jwt.split(".");
+        if (parts.length !== 3)
+            throw new Error("Invalid JWT format");
+        // Reuse the same cryptographic verification logic
+        const claims = await this.verifyWithIssuer(jwt);
+        // If verifyWithIssuer() throws, this will never return
+        return claims;
+    }
+    /**
+     * Automatically refresh tokens if they are expired or about to expire.
+     * This is a convenience method that handles the refresh logic automatically.
+     *
+     * @param refreshToken - The refresh token to use for refreshing
+     * @param options - Optional parameters for the refresh request
+     * @param options.bufferSeconds - How many seconds before expiry to consider tokens as "about to expire" (default: 60)
+     * @param options.scope - Optional scope parameter
+     * @param options.useAuthHeader - Use Authorization header instead of client_secret in body
+     * @returns Promise<TokenResponse | null> - New tokens if refreshed, null if not needed
+     */
+    async autoRefreshTokens(refreshToken, options = {}) {
+        const bufferSeconds = options.bufferSeconds ?? 60;
+        // Check if we have current tokens and if they need refreshing
+        if (this.lastTokens?.access_token && this.lastTokens?.expires_in) {
+            const now = Math.floor(Date.now() / 1000);
+            const expiresAt = now + this.lastTokens.expires_in;
+            const refreshThreshold = now + bufferSeconds;
+            // If tokens are still valid for more than bufferSeconds, no need to refresh
+            if (expiresAt > refreshThreshold) {
+                return null;
+            }
+        }
+        try {
+            return await this.refreshTokens(refreshToken, {
+                scope: options.scope,
+                useAuthHeader: options.useAuthHeader
+            });
+        }
+        catch (error) {
+            // If refresh fails, clear the last tokens as they're likely invalid
+            this.lastTokens = undefined;
+            throw error;
+        }
+    }
+    /**
+     * Check if the current tokens are expired or about to expire.
+     *
+     * @param bufferSeconds - How many seconds before expiry to consider tokens as "about to expire" (default: 60)
+     * @returns boolean - true if tokens need refreshing, false otherwise
+     */
+    needsTokenRefresh(bufferSeconds = 60) {
+        if (!this.lastTokens?.access_token || !this.lastTokens?.expires_in) {
+            return true; // No tokens or missing expiry info
+        }
+        const now = Math.floor(Date.now() / 1000);
+        const expiresAt = now + this.lastTokens.expires_in;
+        const refreshThreshold = now + bufferSeconds;
+        return expiresAt <= refreshThreshold;
+    }
+    /**
+     * Get the time until the current access token expires.
+     *
+     * @returns number - Seconds until expiry, or 0 if no token or expired
+     */
+    getTokenExpirySeconds() {
+        if (!this.lastTokens?.expires_in) {
+            return 0;
+        }
+        const now = Math.floor(Date.now() / 1000);
+        const expiresAt = now + this.lastTokens.expires_in;
+        const timeLeft = expiresAt - now;
+        return Math.max(0, timeLeft);
+    }
+    /** Returns the last TokenResponse produced by handleCallback/refreshTokens in this instance */
+    getLastTokenResponse() {
+        return this.lastTokens;
+    }
+}
+exports.AuthServer = AuthServer;
+/**
+ * USAGE EXAMPLES
+ *
+ * // Basic token refresh
+ * const auth = new AuthServer(config);
+ * const newTokens = await auth.refreshTokens(refreshToken);
+ *
+ * // Refresh with Authorization header instead of client_secret in body
+ * const newTokens = await auth.refreshTokens(refreshToken, {
+ *   useAuthHeader: true
+ * });
+ *
+ * // Refresh with specific scope (cannot exceed originally granted scope)
+ * const newTokens = await auth.refreshTokens(refreshToken, {
+ *   scope: "openid profile email offline_access"
+ * });
+ *
+ * // Automatic refresh - only refreshes if tokens are expired or about to expire
+ * const newTokens = await auth.autoRefreshTokens(refreshToken, {
+ *   bufferSeconds: 120, // Refresh if expires within 2 minutes
+ *   useAuthHeader: true
+ * });
+ *
+ * // Check if tokens need refreshing
+ * if (auth.needsTokenRefresh(60)) {
+ *   const newTokens = await auth.refreshTokens(refreshToken);
+ * }
+ *
+ * // Get time until token expires
+ * const secondsUntilExpiry = auth.getTokenExpirySeconds();
+ * console.log(`Token expires in ${secondsUntilExpiry} seconds`);
+ *
+ * // Error handling
+ * try {
+ *   const newTokens = await auth.refreshTokens(refreshToken);
+ *   // Use new tokens...
+ * } catch (error) {
+ *   if (error.message.includes('invalid_grant')) {
+ *     // Refresh token is invalid/expired - redirect to login
+ *     return Response.redirect('/login');
+ *   }
+ *   // Handle other errors...
+ * }
+ */

package/lib/cache/SSICache.d.ts

@@ -0,0 +1,40 @@
+import type { CacheInitOpts } from './types';
+export declare class SSICache {
+    private backend;
+    private container;
+    private prefix?;
+    private static __shared?;
+    private constructor();
+    static fromEnv(): SSICache;
+    static init(opts: CacheInitOpts): SSICache;
+    /**
+     * Returns a cache instance pinned to a prefix ("jwks", "oidc", "rl", etc.).
+     */
+    withPrefix(prefix?: string): SSICache;
+    private k;
+    get<T = unknown>(key: string): Promise<T | null>;
+    set<T = unknown>(key: string, value: T, ttlSec: number): Promise<void>;
+    del(key: string): Promise<void>;
+    mget<T = unknown>(keys: string[]): Promise<(T | null)[]>;
+    mset<T = unknown>(entries: Array<{
+        key: string;
+        value: T;
+        ttlSec: number;
+    }>): Promise<void>;
+    incrby(key: string, by?: number, ttlSec?: number): Promise<number>;
+    ttl(key: string): Promise<number | null>;
+    /**
+     * compute-if-absent: get from cache or compute and cache the value
+     */
+    remember<T>(key: string, ttlSec: number, loader: () => Promise<T>): Promise<T>;
+    /**
+     * Simple distributed lock (best-effort): returns lock token if acquired
+     * Only works properly with Redis backend; memory backend returns a naive token
+     */
+    acquireLock(key: string, ttlMs: number): Promise<string | null>;
+    /**
+     * Release a lock acquired via acquireLock
+     */
+    releaseLock(key: string, token: string): Promise<void>;
+    close(): Promise<void>;
+}