@digilogiclabs/platform-core 1.9.0 → 1.11.0

package/dist/auth.d.mts

@@ -1,5 +1,5 @@
-import { R as RateLimitStore, a as RateLimitRule, b as RateLimitOptions } from './env-DHPZR3Lv.mjs';
-export { al as AllowlistConfig, A as ApiError, d as ApiErrorCode, f as ApiErrorCodeType, h as ApiPaginatedResponse, Q as ApiSecurityConfig, V as ApiSecurityContext, g as ApiSuccessResponse, aD as AuditRequest, H as AuthCookiesConfig, N as AuthMethod, aL as BetaClientConfig, C as CommonApiErrors, ar as CommonRateLimits, ac as DateRangeInput, a6 as DateRangeSchema, ag as DeploymentStage, aa as EmailInput, $ as EmailSchema, E as EnvValidationConfig, p as EnvValidationResult, ai as FlagDefinition, aj as FlagDefinitions, ah as FlagValue, r as KEYCLOAK_DEFAULT_ROLES, F as KeycloakCallbacksConfig, K as KeycloakConfig, G as KeycloakJwtFields, q as KeycloakTokenSet, ae as LoginInput, a8 as LoginSchema, ay as OpsAuditActor, aA as OpsAuditEvent, aC as OpsAuditLoggerOptions, aB as OpsAuditRecord, az as OpsAuditResource, ab as PaginationInput, a5 as PaginationSchema, a0 as PasswordSchema, a3 as PersonNameSchema, a2 as PhoneSchema, aq as RateLimitCheckResult, P as RateLimitPreset, J as RedirectCallbackConfig, ak as ResolvedFlags, O as RouteAuditConfig, ad as SearchQueryInput, a7 as SearchQuerySchema, U as SecuritySession, af as SignupInput, a9 as SignupSchema, a1 as SlugSchema, aF as StandardAuditActionType, aE as StandardAuditActions, S as StandardRateLimitPresets, T as TokenRefreshResult, _ as WrapperPresets, ao as buildAllowlist, I as buildAuthCookies, Z as buildErrorBody, M as buildKeycloakCallbacks, e as buildPagination, Y as buildRateLimitHeaders, aw as buildRateLimitResponseHeaders, L as buildRedirectCallback, y as buildTokenRefreshParams, n as checkEnvVars, at as checkRateLimit, c as classifyError, aR as clearStoredBetaCode, aJ as createAuditActor, aK as createAuditLogger, aM as createBetaClient, an as createFeatureFlags, as as createMemoryRateLimitStore, a4 as createSafeTextSchema, am as detectStage, aG as extractAuditIp, aI as extractAuditRequestId, aH as extractAuditUserAgent, X as extractClientIp, aN as fetchBetaSettings, l as getBoolEnv, B as getEndSessionEndpoint, o as getEnvSummary, m as getIntEnv, k as getOptionalEnv, au as getRateLimitStatus, j as getRequiredEnv, aQ as getStoredBetaCode, z as getTokenEndpoint, w as hasAllRoles, u as hasAnyRole, t as hasRole, ap as isAllowlisted, i as isApiError, x as isTokenExpired, s as parseKeycloakRoles, D as refreshKeycloakToken, av as resetRateLimitForKey, ax as resolveIdentifier, W as resolveRateLimitIdentifier, aP as storeBetaCode, aO as validateBetaCode, v as validateEnvVars } from './env-DHPZR3Lv.mjs';
+import { R as RateLimitStore, a as RateLimitRule, b as RateLimitOptions } from './env-CYKVNpLl.mjs';
+export { al as AllowlistConfig, A as ApiError, d as ApiErrorCode, f as ApiErrorCodeType, h as ApiPaginatedResponse, Q as ApiSecurityConfig, V as ApiSecurityContext, g as ApiSuccessResponse, aD as AuditRequest, H as AuthCookiesConfig, N as AuthMethod, aL as BetaClientConfig, C as CommonApiErrors, ar as CommonRateLimits, ac as DateRangeInput, a6 as DateRangeSchema, ag as DeploymentStage, aa as EmailInput, $ as EmailSchema, E as EnvValidationConfig, p as EnvValidationResult, ai as FlagDefinition, aj as FlagDefinitions, ah as FlagValue, r as KEYCLOAK_DEFAULT_ROLES, F as KeycloakCallbacksConfig, K as KeycloakConfig, G as KeycloakJwtFields, q as KeycloakTokenSet, ae as LoginInput, a8 as LoginSchema, ay as OpsAuditActor, aA as OpsAuditEvent, aC as OpsAuditLoggerOptions, aB as OpsAuditRecord, az as OpsAuditResource, ab as PaginationInput, a5 as PaginationSchema, a0 as PasswordSchema, a3 as PersonNameSchema, a2 as PhoneSchema, aq as RateLimitCheckResult, P as RateLimitPreset, J as RedirectCallbackConfig, ak as ResolvedFlags, O as RouteAuditConfig, ad as SearchQueryInput, a7 as SearchQuerySchema, U as SecuritySession, af as SignupInput, a9 as SignupSchema, a1 as SlugSchema, aF as StandardAuditActionType, aE as StandardAuditActions, S as StandardRateLimitPresets, T as TokenRefreshResult, _ as WrapperPresets, ao as buildAllowlist, I as buildAuthCookies, Z as buildErrorBody, M as buildKeycloakCallbacks, e as buildPagination, Y as buildRateLimitHeaders, aw as buildRateLimitResponseHeaders, L as buildRedirectCallback, y as buildTokenRefreshParams, n as checkEnvVars, at as checkRateLimit, c as classifyError, aR as clearStoredBetaCode, aJ as createAuditActor, aK as createAuditLogger, aM as createBetaClient, an as createFeatureFlags, as as createMemoryRateLimitStore, a4 as createSafeTextSchema, am as detectStage, aG as extractAuditIp, aI as extractAuditRequestId, aH as extractAuditUserAgent, X as extractClientIp, aN as fetchBetaSettings, l as getBoolEnv, B as getEndSessionEndpoint, o as getEnvSummary, m as getIntEnv, k as getOptionalEnv, au as getRateLimitStatus, j as getRequiredEnv, aQ as getStoredBetaCode, z as getTokenEndpoint, w as hasAllRoles, u as hasAnyRole, t as hasRole, ap as isAllowlisted, i as isApiError, x as isTokenExpired, s as parseKeycloakRoles, D as refreshKeycloakToken, av as resetRateLimitForKey, ax as resolveIdentifier, W as resolveRateLimitIdentifier, aP as storeBetaCode, aO as validateBetaCode, v as validateEnvVars } from './env-CYKVNpLl.mjs';
 export { c as constantTimeEqual, b as containsHtml, a as containsUrls, e as escapeHtml, g as getCorrelationId, d as sanitizeApiError, s as stripHtml } from './security-BvLXaQkv.mjs';
 import 'zod';
 
@@ -172,5 +172,219 @@ declare function isValidBearerToken(request: {
         get(name: string): string | null;
     };
 }, secret: string | undefined): boolean;
+/**
+ * Verify cron/sync endpoint authentication using a bearer token.
+ *
+ * Extracts the Bearer token from the Authorization header and compares
+ * it against `CRON_SECRET` (or a custom secret) using timing-safe comparison.
+ * Returns a 401/500 Response on failure, or `null` on success.
+ *
+ * @param request - Incoming request (must have headers.get)
+ * @param secret - Custom secret to compare against. Defaults to `process.env.CRON_SECRET`.
+ * @returns `null` if authorized, or a JSON Response (401/500) if not.
+ *
+ * @example
+ * ```typescript
+ * export async function POST(request: NextRequest) {
+ *   const authError = verifyCronAuth(request)
+ *   if (authError) return authError
+ *   // ... handle cron job
+ * }
+ * ```
+ */
+declare function verifyCronAuth(request: {
+    headers: {
+        get(name: string): string | null;
+    };
+}, secret?: string): Response | null;
+/**
+ * Extract the client IP address from a request, checking proxy headers.
+ *
+ * Checks in order:
+ * 1. `cf-connecting-ip` (Cloudflare)
+ * 2. `x-real-ip` (Nginx)
+ * 3. `x-forwarded-for` (first IP from comma-separated list)
+ * 4. Falls back to `'unknown'`
+ *
+ * @example
+ * ```typescript
+ * const ip = getClientIp(request)
+ * await auditLog({ action: 'login', ip })
+ * ```
+ */
+declare function getClientIp(request: {
+    headers: {
+        get(name: string): string | null;
+    };
+}): string;
+/** Shape expected by rate limit response helpers. */
+interface RateLimitResult {
+    limit: number;
+    remaining: number;
+    resetMs: number;
+}
+/**
+ * Create a 429 "Too Many Requests" response with RFC-compliant rate limit headers.
+ *
+ * @example
+ * ```typescript
+ * if (!result.allowed) {
+ *   return rateLimitResponse(result)
+ * }
+ * ```
+ */
+declare function rateLimitResponse(result: RateLimitResult): Response;
+/**
+ * Add rate limit headers to an existing response.
+ *
+ * Use this to attach rate limit info to successful responses so clients
+ * can see their remaining quota.
+ *
+ * @example
+ * ```typescript
+ * const response = new Response(JSON.stringify(data), { status: 200 })
+ * return addRateLimitHeaders(response, result)
+ * ```
+ */
+declare function addRateLimitHeaders(response: Response, result: RateLimitResult): Response;
+/**
+ * Safe Zod validation — returns { success, data?, errors? } without throwing.
+ * Useful for API routes where you want to return validation errors as JSON.
+ *
+ * Uses structural typing for the schema parameter so platform-core
+ * doesn't depend on Zod directly.
+ *
+ * @example
+ * ```typescript
+ * const result = safeValidate(MySchema, await request.json())
+ * if (!result.success) {
+ *   return new Response(JSON.stringify({ errors: result.errors }), { status: 400 })
+ * }
+ * const data = result.data // fully typed
+ * ```
+ */
+declare function safeValidate<T>(schema: {
+    safeParse: (data: unknown) => {
+        success: boolean;
+        data?: T;
+        error?: {
+            issues: Array<{
+                path: (string | number)[];
+                message: string;
+            }>;
+        };
+    };
+}, data: unknown): {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    errors: Array<{
+        field: string;
+        message: string;
+    }>;
+};
+
+/**
+ * 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 { RateLimitOptions, RateLimitRule, RateLimitStore, type RedisRateLimitClient, type RedisRateLimitStoreOptions, createRedisRateLimitStore, enforceRateLimit, errorResponse, extractBearerToken, isValidBearerToken, zodErrorResponse };
+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

@@ -1,5 +1,5 @@
-import { R as RateLimitStore, a as RateLimitRule, b as RateLimitOptions } from './env-DHPZR3Lv.js';
-export { al as AllowlistConfig, A as ApiError, d as ApiErrorCode, f as ApiErrorCodeType, h as ApiPaginatedResponse, Q as ApiSecurityConfig, V as ApiSecurityContext, g as ApiSuccessResponse, aD as AuditRequest, H as AuthCookiesConfig, N as AuthMethod, aL as BetaClientConfig, C as CommonApiErrors, ar as CommonRateLimits, ac as DateRangeInput, a6 as DateRangeSchema, ag as DeploymentStage, aa as EmailInput, $ as EmailSchema, E as EnvValidationConfig, p as EnvValidationResult, ai as FlagDefinition, aj as FlagDefinitions, ah as FlagValue, r as KEYCLOAK_DEFAULT_ROLES, F as KeycloakCallbacksConfig, K as KeycloakConfig, G as KeycloakJwtFields, q as KeycloakTokenSet, ae as LoginInput, a8 as LoginSchema, ay as OpsAuditActor, aA as OpsAuditEvent, aC as OpsAuditLoggerOptions, aB as OpsAuditRecord, az as OpsAuditResource, ab as PaginationInput, a5 as PaginationSchema, a0 as PasswordSchema, a3 as PersonNameSchema, a2 as PhoneSchema, aq as RateLimitCheckResult, P as RateLimitPreset, J as RedirectCallbackConfig, ak as ResolvedFlags, O as RouteAuditConfig, ad as SearchQueryInput, a7 as SearchQuerySchema, U as SecuritySession, af as SignupInput, a9 as SignupSchema, a1 as SlugSchema, aF as StandardAuditActionType, aE as StandardAuditActions, S as StandardRateLimitPresets, T as TokenRefreshResult, _ as WrapperPresets, ao as buildAllowlist, I as buildAuthCookies, Z as buildErrorBody, M as buildKeycloakCallbacks, e as buildPagination, Y as buildRateLimitHeaders, aw as buildRateLimitResponseHeaders, L as buildRedirectCallback, y as buildTokenRefreshParams, n as checkEnvVars, at as checkRateLimit, c as classifyError, aR as clearStoredBetaCode, aJ as createAuditActor, aK as createAuditLogger, aM as createBetaClient, an as createFeatureFlags, as as createMemoryRateLimitStore, a4 as createSafeTextSchema, am as detectStage, aG as extractAuditIp, aI as extractAuditRequestId, aH as extractAuditUserAgent, X as extractClientIp, aN as fetchBetaSettings, l as getBoolEnv, B as getEndSessionEndpoint, o as getEnvSummary, m as getIntEnv, k as getOptionalEnv, au as getRateLimitStatus, j as getRequiredEnv, aQ as getStoredBetaCode, z as getTokenEndpoint, w as hasAllRoles, u as hasAnyRole, t as hasRole, ap as isAllowlisted, i as isApiError, x as isTokenExpired, s as parseKeycloakRoles, D as refreshKeycloakToken, av as resetRateLimitForKey, ax as resolveIdentifier, W as resolveRateLimitIdentifier, aP as storeBetaCode, aO as validateBetaCode, v as validateEnvVars } from './env-DHPZR3Lv.js';
+import { R as RateLimitStore, a as RateLimitRule, b as RateLimitOptions } from './env-CYKVNpLl.js';
+export { al as AllowlistConfig, A as ApiError, d as ApiErrorCode, f as ApiErrorCodeType, h as ApiPaginatedResponse, Q as ApiSecurityConfig, V as ApiSecurityContext, g as ApiSuccessResponse, aD as AuditRequest, H as AuthCookiesConfig, N as AuthMethod, aL as BetaClientConfig, C as CommonApiErrors, ar as CommonRateLimits, ac as DateRangeInput, a6 as DateRangeSchema, ag as DeploymentStage, aa as EmailInput, $ as EmailSchema, E as EnvValidationConfig, p as EnvValidationResult, ai as FlagDefinition, aj as FlagDefinitions, ah as FlagValue, r as KEYCLOAK_DEFAULT_ROLES, F as KeycloakCallbacksConfig, K as KeycloakConfig, G as KeycloakJwtFields, q as KeycloakTokenSet, ae as LoginInput, a8 as LoginSchema, ay as OpsAuditActor, aA as OpsAuditEvent, aC as OpsAuditLoggerOptions, aB as OpsAuditRecord, az as OpsAuditResource, ab as PaginationInput, a5 as PaginationSchema, a0 as PasswordSchema, a3 as PersonNameSchema, a2 as PhoneSchema, aq as RateLimitCheckResult, P as RateLimitPreset, J as RedirectCallbackConfig, ak as ResolvedFlags, O as RouteAuditConfig, ad as SearchQueryInput, a7 as SearchQuerySchema, U as SecuritySession, af as SignupInput, a9 as SignupSchema, a1 as SlugSchema, aF as StandardAuditActionType, aE as StandardAuditActions, S as StandardRateLimitPresets, T as TokenRefreshResult, _ as WrapperPresets, ao as buildAllowlist, I as buildAuthCookies, Z as buildErrorBody, M as buildKeycloakCallbacks, e as buildPagination, Y as buildRateLimitHeaders, aw as buildRateLimitResponseHeaders, L as buildRedirectCallback, y as buildTokenRefreshParams, n as checkEnvVars, at as checkRateLimit, c as classifyError, aR as clearStoredBetaCode, aJ as createAuditActor, aK as createAuditLogger, aM as createBetaClient, an as createFeatureFlags, as as createMemoryRateLimitStore, a4 as createSafeTextSchema, am as detectStage, aG as extractAuditIp, aI as extractAuditRequestId, aH as extractAuditUserAgent, X as extractClientIp, aN as fetchBetaSettings, l as getBoolEnv, B as getEndSessionEndpoint, o as getEnvSummary, m as getIntEnv, k as getOptionalEnv, au as getRateLimitStatus, j as getRequiredEnv, aQ as getStoredBetaCode, z as getTokenEndpoint, w as hasAllRoles, u as hasAnyRole, t as hasRole, ap as isAllowlisted, i as isApiError, x as isTokenExpired, s as parseKeycloakRoles, D as refreshKeycloakToken, av as resetRateLimitForKey, ax as resolveIdentifier, W as resolveRateLimitIdentifier, aP as storeBetaCode, aO as validateBetaCode, v as validateEnvVars } from './env-CYKVNpLl.js';
 export { c as constantTimeEqual, b as containsHtml, a as containsUrls, e as escapeHtml, g as getCorrelationId, d as sanitizeApiError, s as stripHtml } from './security-BvLXaQkv.js';
 import 'zod';
 
@@ -172,5 +172,219 @@ declare function isValidBearerToken(request: {
         get(name: string): string | null;
     };
 }, secret: string | undefined): boolean;
+/**
+ * Verify cron/sync endpoint authentication using a bearer token.
+ *
+ * Extracts the Bearer token from the Authorization header and compares
+ * it against `CRON_SECRET` (or a custom secret) using timing-safe comparison.
+ * Returns a 401/500 Response on failure, or `null` on success.
+ *
+ * @param request - Incoming request (must have headers.get)
+ * @param secret - Custom secret to compare against. Defaults to `process.env.CRON_SECRET`.
+ * @returns `null` if authorized, or a JSON Response (401/500) if not.
+ *
+ * @example
+ * ```typescript
+ * export async function POST(request: NextRequest) {
+ *   const authError = verifyCronAuth(request)
+ *   if (authError) return authError
+ *   // ... handle cron job
+ * }
+ * ```
+ */
+declare function verifyCronAuth(request: {
+    headers: {
+        get(name: string): string | null;
+    };
+}, secret?: string): Response | null;
+/**
+ * Extract the client IP address from a request, checking proxy headers.
+ *
+ * Checks in order:
+ * 1. `cf-connecting-ip` (Cloudflare)
+ * 2. `x-real-ip` (Nginx)
+ * 3. `x-forwarded-for` (first IP from comma-separated list)
+ * 4. Falls back to `'unknown'`
+ *
+ * @example
+ * ```typescript
+ * const ip = getClientIp(request)
+ * await auditLog({ action: 'login', ip })
+ * ```
+ */
+declare function getClientIp(request: {
+    headers: {
+        get(name: string): string | null;
+    };
+}): string;
+/** Shape expected by rate limit response helpers. */
+interface RateLimitResult {
+    limit: number;
+    remaining: number;
+    resetMs: number;
+}
+/**
+ * Create a 429 "Too Many Requests" response with RFC-compliant rate limit headers.
+ *
+ * @example
+ * ```typescript
+ * if (!result.allowed) {
+ *   return rateLimitResponse(result)
+ * }
+ * ```
+ */
+declare function rateLimitResponse(result: RateLimitResult): Response;
+/**
+ * Add rate limit headers to an existing response.
+ *
+ * Use this to attach rate limit info to successful responses so clients
+ * can see their remaining quota.
+ *
+ * @example
+ * ```typescript
+ * const response = new Response(JSON.stringify(data), { status: 200 })
+ * return addRateLimitHeaders(response, result)
+ * ```
+ */
+declare function addRateLimitHeaders(response: Response, result: RateLimitResult): Response;
+/**
+ * Safe Zod validation — returns { success, data?, errors? } without throwing.
+ * Useful for API routes where you want to return validation errors as JSON.
+ *
+ * Uses structural typing for the schema parameter so platform-core
+ * doesn't depend on Zod directly.
+ *
+ * @example
+ * ```typescript
+ * const result = safeValidate(MySchema, await request.json())
+ * if (!result.success) {
+ *   return new Response(JSON.stringify({ errors: result.errors }), { status: 400 })
+ * }
+ * const data = result.data // fully typed
+ * ```
+ */
+declare function safeValidate<T>(schema: {
+    safeParse: (data: unknown) => {
+        success: boolean;
+        data?: T;
+        error?: {
+            issues: Array<{
+                path: (string | number)[];
+                message: string;
+            }>;
+        };
+    };
+}, data: unknown): {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    errors: Array<{
+        field: string;
+        message: string;
+    }>;
+};
+
+/**
+ * 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 { RateLimitOptions, RateLimitRule, RateLimitStore, type RedisRateLimitClient, type RedisRateLimitStoreOptions, createRedisRateLimitStore, enforceRateLimit, errorResponse, extractBearerToken, isValidBearerToken, zodErrorResponse };
+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 };