@digilogiclabs/platform-core 1.10.0 → 1.11.0

package/dist/auth.d.mts

@@ -285,4 +285,106 @@ declare function safeValidate<T>(schema: {
     }>;
 };
 
-export { RateLimitOptions, type RateLimitResult, RateLimitRule, RateLimitStore, type RedisRateLimitClient, type RedisRateLimitStoreOptions, addRateLimitHeaders, createRedisRateLimitStore, enforceRateLimit, errorResponse, extractBearerToken, getClientIp, isValidBearerToken, rateLimitResponse, safeValidate, verifyCronAuth, zodErrorResponse };
+/**
+ * Federated Logout Handler for Keycloak + Auth.js
+ *
+ * Builds a Next.js route handler that:
+ * 1. Revokes the refresh token with Keycloak
+ * 2. Returns an HTML page that clears all auth cookies
+ * 3. Auto-redirects to Keycloak's OIDC logout endpoint
+ *
+ * Uses HTML 200 (not 307 redirect) because browsers may not reliably
+ * process Set-Cookie headers on redirect responses through CDN proxies.
+ *
+ * Edge-runtime compatible.
+ *
+ * @example
+ * ```typescript
+ * // app/api/auth/federated-logout/route.ts
+ * import { buildFederatedLogoutHandler } from '@digilogiclabs/platform-core/auth'
+ * import { auth } from '@/auth'
+ *
+ * export const dynamic = 'force-dynamic'
+ *
+ * export const GET = buildFederatedLogoutHandler({
+ *   auth,
+ *   domain: '.digilogiclabs.com',
+ *   baseUrlFallback: 'https://digilogiclabs.com',
+ * })
+ * ```
+ */
+interface FederatedLogoutConfig {
+    /**
+     * Auth.js `auth()` function — used to get the session's idToken.
+     * Must return an object with an optional `idToken` field.
+     */
+    auth: () => Promise<{
+        idToken?: string;
+    } | null>;
+    /**
+     * Production cookie domain (e.g. '.digilogiclabs.com').
+     * Used to clear cookies scoped to the root domain.
+     */
+    domain: string;
+    /**
+     * Fallback base URL when NEXTAUTH_URL/AUTH_URL are not set.
+     * e.g. 'https://digilogiclabs.com'
+     */
+    baseUrlFallback: string;
+    /**
+     * Additional cookie names to clear beyond the standard Auth.js set.
+     * e.g. ['admin-session']
+     */
+    extraCookies?: string[];
+    /**
+     * Optional error reporter. Called on missing issuer and token revocation failures.
+     * If not provided, errors are silently ignored.
+     */
+    onError?: (message: string, error?: unknown) => void;
+}
+/**
+ * Build a Next.js route handler for federated logout with Keycloak.
+ *
+ * The returned handler:
+ * - Validates the callbackUrl against an allowlist (open redirect protection)
+ * - Revokes the Keycloak refresh token
+ * - Clears all Auth.js cookies (both standard and __Secure- prefixed)
+ * - Returns an HTML page that auto-redirects to Keycloak's OIDC logout
+ */
+declare function buildFederatedLogoutHandler(config: FederatedLogoutConfig): (request: Request) => Promise<Response>;
+
+/**
+ * Lazy Rate Limit Store
+ *
+ * Creates a singleton rate limit store backed by Redis with automatic
+ * fallback to in-memory when Redis is unavailable.
+ *
+ * @example
+ * ```typescript
+ * // lib/rate-limit-store.ts
+ * import { createLazyRateLimitStore } from '@digilogiclabs/platform-core/auth'
+ * import { getRedisClient } from './redis'
+ *
+ * export const getRateLimitStore = createLazyRateLimitStore(getRedisClient)
+ * ```
+ */
+
+interface LazyRateLimitStoreOptions {
+    /** Redis key prefix for rate limit keys (default: 'rl:') */
+    keyPrefix?: string;
+}
+/**
+ * Create a lazy singleton rate limit store factory.
+ *
+ * Returns a getter function that:
+ * - On first call, attempts to get a Redis client and create a Redis-backed store
+ * - If Redis is unavailable, returns undefined (enforceRateLimit falls back to in-memory)
+ * - Caches the result for subsequent calls
+ *
+ * @param getRedis - Function that returns a Redis client (or null/undefined if unavailable)
+ * @param options - Optional configuration
+ * @returns A getter function that returns the RateLimitStore or undefined
+ */
+declare function createLazyRateLimitStore(getRedis: () => RedisRateLimitClient | null | undefined, options?: LazyRateLimitStoreOptions): () => RateLimitStore | undefined;
+
+export { type FederatedLogoutConfig, type LazyRateLimitStoreOptions, RateLimitOptions, type RateLimitResult, RateLimitRule, RateLimitStore, type RedisRateLimitClient, type RedisRateLimitStoreOptions, addRateLimitHeaders, buildFederatedLogoutHandler, createLazyRateLimitStore, createRedisRateLimitStore, enforceRateLimit, errorResponse, extractBearerToken, getClientIp, isValidBearerToken, rateLimitResponse, safeValidate, verifyCronAuth, zodErrorResponse };

package/dist/auth.d.ts

@@ -285,4 +285,106 @@ declare function safeValidate<T>(schema: {
     }>;
 };
 
-export { RateLimitOptions, type RateLimitResult, RateLimitRule, RateLimitStore, type RedisRateLimitClient, type RedisRateLimitStoreOptions, addRateLimitHeaders, createRedisRateLimitStore, enforceRateLimit, errorResponse, extractBearerToken, getClientIp, isValidBearerToken, rateLimitResponse, safeValidate, verifyCronAuth, zodErrorResponse };
+/**
+ * Federated Logout Handler for Keycloak + Auth.js
+ *
+ * Builds a Next.js route handler that:
+ * 1. Revokes the refresh token with Keycloak
+ * 2. Returns an HTML page that clears all auth cookies
+ * 3. Auto-redirects to Keycloak's OIDC logout endpoint
+ *
+ * Uses HTML 200 (not 307 redirect) because browsers may not reliably
+ * process Set-Cookie headers on redirect responses through CDN proxies.
+ *
+ * Edge-runtime compatible.
+ *
+ * @example
+ * ```typescript
+ * // app/api/auth/federated-logout/route.ts
+ * import { buildFederatedLogoutHandler } from '@digilogiclabs/platform-core/auth'
+ * import { auth } from '@/auth'
+ *
+ * export const dynamic = 'force-dynamic'
+ *
+ * export const GET = buildFederatedLogoutHandler({
+ *   auth,
+ *   domain: '.digilogiclabs.com',
+ *   baseUrlFallback: 'https://digilogiclabs.com',
+ * })
+ * ```
+ */
+interface FederatedLogoutConfig {
+    /**
+     * Auth.js `auth()` function — used to get the session's idToken.
+     * Must return an object with an optional `idToken` field.
+     */
+    auth: () => Promise<{
+        idToken?: string;
+    } | null>;
+    /**
+     * Production cookie domain (e.g. '.digilogiclabs.com').
+     * Used to clear cookies scoped to the root domain.
+     */
+    domain: string;
+    /**
+     * Fallback base URL when NEXTAUTH_URL/AUTH_URL are not set.
+     * e.g. 'https://digilogiclabs.com'
+     */
+    baseUrlFallback: string;
+    /**
+     * Additional cookie names to clear beyond the standard Auth.js set.
+     * e.g. ['admin-session']
+     */
+    extraCookies?: string[];
+    /**
+     * Optional error reporter. Called on missing issuer and token revocation failures.
+     * If not provided, errors are silently ignored.
+     */
+    onError?: (message: string, error?: unknown) => void;
+}
+/**
+ * Build a Next.js route handler for federated logout with Keycloak.
+ *
+ * The returned handler:
+ * - Validates the callbackUrl against an allowlist (open redirect protection)
+ * - Revokes the Keycloak refresh token
+ * - Clears all Auth.js cookies (both standard and __Secure- prefixed)
+ * - Returns an HTML page that auto-redirects to Keycloak's OIDC logout
+ */
+declare function buildFederatedLogoutHandler(config: FederatedLogoutConfig): (request: Request) => Promise<Response>;
+
+/**
+ * Lazy Rate Limit Store
+ *
+ * Creates a singleton rate limit store backed by Redis with automatic
+ * fallback to in-memory when Redis is unavailable.
+ *
+ * @example
+ * ```typescript
+ * // lib/rate-limit-store.ts
+ * import { createLazyRateLimitStore } from '@digilogiclabs/platform-core/auth'
+ * import { getRedisClient } from './redis'
+ *
+ * export const getRateLimitStore = createLazyRateLimitStore(getRedisClient)
+ * ```
+ */
+
+interface LazyRateLimitStoreOptions {
+    /** Redis key prefix for rate limit keys (default: 'rl:') */
+    keyPrefix?: string;
+}
+/**
+ * Create a lazy singleton rate limit store factory.
+ *
+ * Returns a getter function that:
+ * - On first call, attempts to get a Redis client and create a Redis-backed store
+ * - If Redis is unavailable, returns undefined (enforceRateLimit falls back to in-memory)
+ * - Caches the result for subsequent calls
+ *
+ * @param getRedis - Function that returns a Redis client (or null/undefined if unavailable)
+ * @param options - Optional configuration
+ * @returns A getter function that returns the RateLimitStore or undefined
+ */
+declare function createLazyRateLimitStore(getRedis: () => RedisRateLimitClient | null | undefined, options?: LazyRateLimitStoreOptions): () => RateLimitStore | undefined;
+
+export { type FederatedLogoutConfig, type LazyRateLimitStoreOptions, RateLimitOptions, type RateLimitResult, RateLimitRule, RateLimitStore, type RedisRateLimitClient, type RedisRateLimitStoreOptions, addRateLimitHeaders, buildFederatedLogoutHandler, createLazyRateLimitStore, createRedisRateLimitStore, enforceRateLimit, errorResponse, extractBearerToken, getClientIp, isValidBearerToken, rateLimitResponse, safeValidate, verifyCronAuth, zodErrorResponse };

package/dist/auth.js

@@ -42,6 +42,7 @@ __export(auth_exports, {
   buildAllowlist: () => buildAllowlist,
   buildAuthCookies: () => buildAuthCookies,
   buildErrorBody: () => buildErrorBody,
+  buildFederatedLogoutHandler: () => buildFederatedLogoutHandler,
   buildKeycloakCallbacks: () => buildKeycloakCallbacks,
   buildPagination: () => buildPagination,
   buildRateLimitHeaders: () => buildRateLimitHeaders,
@@ -59,6 +60,7 @@ __export(auth_exports, {
   createAuditLogger: () => createAuditLogger,
   createBetaClient: () => createBetaClient,
   createFeatureFlags: () => createFeatureFlags,
+  createLazyRateLimitStore: () => createLazyRateLimitStore,
   createMemoryRateLimitStore: () => createMemoryRateLimitStore,
   createRedisRateLimitStore: () => createRedisRateLimitStore,
   createSafeTextSchema: () => createSafeTextSchema,
@@ -1223,10 +1225,10 @@ function isValidBearerToken(request, secret) {
 function verifyCronAuth(request, secret) {
   const authHeader = request.headers.get("authorization");
   if (!authHeader?.startsWith("Bearer ")) {
-    return new Response(
-      JSON.stringify({ error: "Missing authorization" }),
-      { status: 401, headers: { "Content-Type": "application/json" } }
-    );
+    return new Response(JSON.stringify({ error: "Missing authorization" }), {
+      status: 401,
+      headers: { "Content-Type": "application/json" }
+    });
   }
   const token = authHeader.slice(7);
   const expectedSecret = secret ?? process.env.CRON_SECRET;
@@ -1238,10 +1240,10 @@ function verifyCronAuth(request, secret) {
     );
   }
   if (!constantTimeEqual(token, expectedSecret)) {
-    return new Response(
-      JSON.stringify({ error: "Invalid authorization" }),
-      { status: 401, headers: { "Content-Type": "application/json" } }
-    );
+    return new Response(JSON.stringify({ error: "Invalid authorization" }), {
+      status: 401,
+      headers: { "Content-Type": "application/json" }
+    });
   }
   return null;
 }
@@ -1393,6 +1395,172 @@ function clearStoredBetaCode(config = {}) {
   }
 }
 
+// src/auth/federated-logout.ts
+function expireCookie(name, options) {
+  const parts = [
+    `${name}=`,
+    "Path=/",
+    "Expires=Thu, 01 Jan 1970 00:00:00 GMT",
+    "Max-Age=0",
+    "SameSite=Lax"
+  ];
+  if (options?.hostPrefix) {
+    parts.push("Secure");
+  } else {
+    parts.push("HttpOnly");
+    if (options?.domain) parts.push(`Domain=${options.domain}`);
+    if (options?.secure) parts.push("Secure");
+  }
+  return parts.join("; ");
+}
+function isAllowedCallbackUrl(url, baseUrl) {
+  if (url.startsWith("/") && !url.startsWith("//")) return true;
+  try {
+    const parsed = new URL(url);
+    const base = new URL(baseUrl);
+    const allowedHosts = [base.hostname, `www.${base.hostname}`];
+    if (base.hostname.startsWith("www.")) {
+      allowedHosts.push(base.hostname.slice(4));
+    }
+    return allowedHosts.includes(parsed.hostname);
+  } catch {
+    return false;
+  }
+}
+var AUTH_COOKIE_NAMES = [
+  "authjs.session-token",
+  "__Secure-authjs.session-token",
+  "authjs.callback-url",
+  "__Secure-authjs.callback-url",
+  "authjs.csrf-token",
+  "__Secure-authjs.csrf-token",
+  "authjs.pkce.code_verifier",
+  "__Secure-authjs.pkce.code_verifier",
+  "authjs.state",
+  "__Secure-authjs.state",
+  // Legacy next-auth names
+  "next-auth.session-token",
+  "__Secure-next-auth.session-token",
+  "next-auth.callback-url",
+  "__Secure-next-auth.callback-url",
+  "next-auth.csrf-token",
+  "__Secure-next-auth.csrf-token"
+];
+var HOST_COOKIES = [
+  "__Host-authjs.csrf-token",
+  "__Host-next-auth.csrf-token"
+];
+function buildFederatedLogoutHandler(config) {
+  const { auth, domain, baseUrlFallback, extraCookies = [], onError } = config;
+  return async function GET(request) {
+    const session = await auth();
+    const url = new URL(request.url);
+    const rawCallbackUrl = url.searchParams.get("callbackUrl") || "/";
+    const queryIdToken = url.searchParams.get("id_token_hint");
+    const baseUrl = process.env.NEXTAUTH_URL || process.env.AUTH_URL || baseUrlFallback;
+    const callbackUrl = isAllowedCallbackUrl(rawCallbackUrl, baseUrl) ? rawCallbackUrl : "/";
+    const postLogoutRedirectUri = callbackUrl.startsWith("http") ? callbackUrl : `${baseUrl}${callbackUrl}`;
+    const keycloakIssuer = process.env.AUTH_KEYCLOAK_ISSUER;
+    if (!keycloakIssuer) {
+      onError?.("Missing AUTH_KEYCLOAK_ISSUER");
+      return Response.redirect(
+        new URL(
+          "/api/auth/signout?callbackUrl=" + encodeURIComponent(callbackUrl),
+          request.url
+        ).toString()
+      );
+    }
+    const refreshToken = session?.refreshToken;
+    if (refreshToken) {
+      try {
+        const revokeUrl = `${keycloakIssuer}/protocol/openid-connect/revoke`;
+        const clientId2 = process.env.AUTH_KEYCLOAK_ID;
+        const clientSecret = process.env.AUTH_KEYCLOAK_SECRET;
+        await fetch(revokeUrl, {
+          method: "POST",
+          headers: { "Content-Type": "application/x-www-form-urlencoded" },
+          body: new URLSearchParams({
+            token: refreshToken,
+            token_type_hint: "refresh_token",
+            ...clientId2 && { client_id: clientId2 },
+            ...clientSecret && { client_secret: clientSecret }
+          })
+        });
+      } catch (err) {
+        onError?.("Token revocation failed", err);
+      }
+    }
+    const keycloakLogoutUrl = new URL(
+      `${keycloakIssuer}/protocol/openid-connect/logout`
+    );
+    keycloakLogoutUrl.searchParams.set(
+      "post_logout_redirect_uri",
+      postLogoutRedirectUri
+    );
+    const clientId = process.env.AUTH_KEYCLOAK_ID;
+    if (clientId) keycloakLogoutUrl.searchParams.set("client_id", clientId);
+    const idToken = session?.idToken || queryIdToken;
+    if (idToken) keycloakLogoutUrl.searchParams.set("id_token_hint", idToken);
+    const escapedUrl = keycloakLogoutUrl.toString().replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+    const html = `<!DOCTYPE html>
+<html><head>
+<meta charset="utf-8">
+<meta http-equiv="refresh" content="0;url=${escapedUrl}">
+<title>Signing out...</title>
+<style>body{display:flex;align-items:center;justify-content:center;min-height:100vh;margin:0;font-family:system-ui,sans-serif;background:#0a0a0a;color:#fff}p{font-size:1.1rem;opacity:0.7}</style>
+</head><body>
+<p>Signing out&hellip;</p>
+<script>window.location.replace(${JSON.stringify(keycloakLogoutUrl.toString()).replace(/</g, "\\u003c")});</script>
+</body></html>`;
+    const response = new Response(html, {
+      status: 200,
+      headers: {
+        "Content-Type": "text/html; charset=utf-8",
+        "Cache-Control": "no-store, no-cache, must-revalidate",
+        Pragma: "no-cache"
+      }
+    });
+    const isProduction = process.env.NODE_ENV === "production";
+    const isSecure = isProduction;
+    const allCookieNames = [...AUTH_COOKIE_NAMES, ...extraCookies];
+    for (const name of allCookieNames) {
+      const needsSecure = isSecure || name.startsWith("__Secure-");
+      response.headers.append(
+        "Set-Cookie",
+        expireCookie(name, { secure: needsSecure })
+      );
+      if (isProduction) {
+        response.headers.append(
+          "Set-Cookie",
+          expireCookie(name, { domain, secure: needsSecure })
+        );
+      }
+    }
+    for (const name of HOST_COOKIES) {
+      response.headers.append(
+        "Set-Cookie",
+        expireCookie(name, { hostPrefix: true })
+      );
+    }
+    return response;
+  };
+}
+
+// src/auth/lazy-rate-limit-store.ts
+function createLazyRateLimitStore(getRedis, options = {}) {
+  const { keyPrefix = "rl:" } = options;
+  let store;
+  let initialized = false;
+  return function getRateLimitStore() {
+    if (initialized) return store;
+    initialized = true;
+    const redis = getRedis();
+    if (!redis) return void 0;
+    store = createRedisRateLimitStore(redis, { keyPrefix });
+    return store;
+  };
+}
+
 // src/env.ts
 function getRequiredEnv(key) {
   const value = process.env[key];
@@ -1507,6 +1675,7 @@ function getEnvSummary(keys) {
   buildAllowlist,
   buildAuthCookies,
   buildErrorBody,
+  buildFederatedLogoutHandler,
   buildKeycloakCallbacks,
   buildPagination,
   buildRateLimitHeaders,
@@ -1524,6 +1693,7 @@ function getEnvSummary(keys) {
   createAuditLogger,
   createBetaClient,
   createFeatureFlags,
+  createLazyRateLimitStore,
   createMemoryRateLimitStore,
   createRedisRateLimitStore,
   createSafeTextSchema,