@serialsubscriptions/platform-integration 0.0.8-5.1

package/lib/auth.server.d.ts

@@ -0,0 +1,212 @@
+import { SSIStorage } from "./storage/SSIStorage";
+import type { AuthConfigInput } from "./requestConfig";
+export declare const scopes: {
+    readonly defaultScopes: "openid profile email view_project create_project delete_project update_project view_subscribed_plan view_subscribed_feature view_subscribed_limit access_subscription_usage";
+};
+/**
+ * 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.
+ */
+export declare function isJwtExpired(jwt: string, bufferSeconds?: number): boolean;
+/**
+ * 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.
+ */
+export declare function getJwtExpirySeconds(jwt: string): number | null;
+export type AuthConfig = {
+    issuerBaseUrl?: string;
+    authorizationEndpoint?: string;
+    tokenEndpoint?: string;
+    logoutEndpoint?: string;
+    jwksUri?: string;
+    jwksPath?: string;
+    jwks?: {
+        keys: Array<{
+            kty: string;
+            n: string;
+            e: string;
+            kid?: string;
+        }>;
+    };
+    clientId?: string;
+    clientSecret?: string;
+    redirectUri?: string;
+    scopes?: string | string[];
+    audience?: string;
+    storage?: SSIStorage;
+};
+export type LoginUrlOptions = {
+    stateKey?: string;
+    extraParams?: Record<string, string>;
+    stateTtlSeconds?: number;
+};
+export type CallbackParams = {
+    code?: string | null;
+    state?: string | null;
+};
+export type TokenResponse = {
+    access_token?: string;
+    id_token?: string;
+    token_type?: string;
+    refresh_token?: string;
+    expires_in?: number;
+    scope?: string;
+    raw: any;
+    id_claims?: Record<string, unknown>;
+    access_claims?: Record<string, unknown>;
+};
+export declare class AuthServer {
+    private cfg;
+    private stateStorage;
+    private jwksCache;
+    private lastTokens?;
+    /** Accepts AuthConfig or SSIRequestConfig (e.g. from getRequestConfig(req)). */
+    constructor(config?: AuthConfigInput);
+    /**
+     * Build the authorization URL and persist a CSRF state for the callback.
+     * Returns: { url, stateKey, stateValue }
+     */
+    getLoginUrl(opts?: LoginUrlOptions): Promise<{
+        url: string;
+        stateKey: string;
+        stateValue: `${string}-${string}-${string}-${string}-${string}`;
+    }>;
+    /**
+     * Build the logout URL for RP-initiated logout.
+     * Common params: id_token_hint, post_logout_redirect_uri
+     */
+    getLogoutUrl(opts?: {
+        idTokenHint?: string;
+        postLogoutRedirectUri?: string;
+        extraParams?: Record<string, string>;
+    }): {
+        url: string;
+    };
+    /**
+     * Handle the OAuth callback: validates state and exchanges the code for tokens.
+     * Returns TokenResponse (and includes raw for debugging).
+     */
+    handleCallback(params: CallbackParams): Promise<TokenResponse>;
+    /**
+     * 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
+     */
+    refreshTokens(refreshToken: string, options?: {
+        scope?: string;
+        useAuthHeader?: boolean;
+    }): Promise<TokenResponse>;
+    /**
+     * Fetch and cache JWKS from the remote endpoint.
+     * Uses SSICache to cache the JWKS response.
+     * @private
+     */
+    private fetchAndCacheJWKS;
+    /**
+     * Verify JWT signature and claims using jose library.
+     * Handles JWKS fetching, caching, kid selection, and algorithm validation.
+     * @private
+     */
+    private verifyWithIssuer;
+    /**
+     * Public method to verify a JWT.
+     * Use this in middleware or anywhere you need to validate tokens.
+     */
+    verifyJwt<T = unknown>(jwt: string): Promise<T>;
+    /**
+     * 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.
+     */
+    verifyAndDecodeJwt<T = unknown>(jwt?: string): Promise<T>;
+    /**
+     * 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
+     */
+    autoRefreshTokens(refreshToken: string, options?: {
+        bufferSeconds?: number;
+        scope?: string;
+        useAuthHeader?: boolean;
+    }): Promise<TokenResponse | null>;
+    /**
+     * 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?: number): boolean;
+    /**
+     * Get the time until the current access token expires.
+     *
+     * @returns number - Seconds until expiry, or 0 if no token or expired
+     */
+    getTokenExpirySeconds(): number;
+    /** Returns the last TokenResponse produced by handleCallback/refreshTokens in this instance */
+    getLastTokenResponse(): TokenResponse | undefined;
+}
+/**
+ * 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...
+ * }
+ */