@digilogiclabs/platform-core 1.12.0 → 1.14.0

package/dist/auth.d.mts

@@ -142,7 +142,7 @@ declare function errorResponse(error: unknown, options?: {
  */
 declare function zodErrorResponse(error: {
     issues: Array<{
-        path: (string | number)[];
+        path: PropertyKey[];
         message: string;
     }>;
 }): Response;
@@ -387,4 +387,189 @@ interface LazyRateLimitStoreOptions {
  */
 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 };
+/**
+ * Composable Secure API Handler Factory
+ *
+ * A generic, dependency-injected version of DLL's `withAuthenticatedApi` pattern.
+ * Apps provide their own auth, rate limiting, audit, and logger implementations
+ * via `createSecureHandlerFactory()`, then use the returned wrappers.
+ *
+ * This avoids coupling to any specific auth library (Auth.js, Keycloak, etc.)
+ * while providing consistent security middleware across all apps.
+ *
+ * @example
+ * ```typescript
+ * // lib/api-security.ts — app-level setup (once per app)
+ * import { createSecureHandlerFactory } from '@digilogiclabs/platform-core/auth'
+ * import { auth } from '@/auth'
+ *
+ * export const { withPublicApi, withAuthenticatedApi, withAdminApi } =
+ *   createSecureHandlerFactory({
+ *     getSession: () => auth(),
+ *     isAdmin: (session) => session?.user?.roles?.includes('admin') ?? false,
+ *     rateLimiter: { enforce: enforceRateLimit, presets: MY_PRESETS },
+ *     classifyError,
+ *   })
+ *
+ * // app/api/items/route.ts — per-route usage
+ * export const POST = withAuthenticatedApi({
+ *   rateLimit: 'mutation',
+ *   validate: CreateItemSchema,
+ * }, async (request, { session, validated }) => {
+ *   return Response.json({ created: true })
+ * })
+ * ```
+ */
+/** Minimal session shape — apps extend this with their own session type */
+interface SecureSession {
+    user?: {
+        id?: string;
+        email?: string | null;
+        name?: string | null;
+        roles?: string[];
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+}
+/** Result from a rate limit check */
+interface SecureRateLimitResult {
+    allowed: boolean;
+    limit: number;
+    remaining: number;
+    current?: number;
+    resetMs?: number;
+}
+/** Minimal logger interface */
+interface SecureLogger {
+    info(message: string, meta?: Record<string, unknown>): void;
+    warn(message: string, meta?: Record<string, unknown>): void;
+    error(message: string, meta?: Record<string, unknown>): void;
+}
+/** Configuration for the secure handler factory */
+interface SecureHandlerFactoryConfig<TSession extends SecureSession = SecureSession, TPresetKey extends string = string> {
+    /** Get the current authenticated session (e.g. from Auth.js) */
+    getSession: () => Promise<TSession | null>;
+    /** Check if a session has admin privileges */
+    isAdmin: (session: TSession | null) => boolean;
+    /** Check if a session has any of the required roles */
+    hasAnyRole?: (session: TSession | null, roles: string[]) => boolean;
+    /** Rate limiting integration */
+    rateLimiter?: {
+        /** Check and enforce rate limit — return response if blocked, null if allowed */
+        enforce: (request: Request, operation: string, preset: TPresetKey, userId?: string) => Promise<Response | null>;
+        /** Default preset for public APIs */
+        publicDefault?: TPresetKey;
+        /** Default preset for authenticated APIs */
+        authDefault?: TPresetKey;
+        /** Default preset for admin APIs */
+        adminDefault?: TPresetKey;
+    };
+    /** Optional: legacy admin token secret (Bearer token auth) */
+    adminSecret?: string;
+    /** Optional: audit logging */
+    auditLog?: (entry: {
+        actor: {
+            id: string;
+            type: string;
+            email?: string;
+        };
+        action: string;
+        resource?: {
+            type: string;
+            id: string;
+        };
+        outcome: "success" | "failure" | "blocked";
+        reason?: string;
+        metadata?: Record<string, unknown>;
+    }) => Promise<void>;
+    /** Optional: create a request-scoped logger */
+    createLogger?: (request: Request, operation: string) => SecureLogger;
+    /** Optional: error classifier (defaults to platform-core classifyError) */
+    classifyError?: (error: unknown, isDev: boolean) => {
+        status: number;
+        body: {
+            error: string;
+            code?: string;
+        };
+    };
+    /** Is the app running in development mode (default: NODE_ENV check) */
+    isDevelopment?: boolean;
+}
+/** Per-route config */
+interface SecureRouteConfig<TValidated = unknown, TPresetKey extends string = string> {
+    /** Rate limit preset key */
+    rateLimit?: TPresetKey;
+    /** Skip rate limiting */
+    skipRateLimit?: boolean;
+    /** Zod schema for input validation (POST/PUT body, GET query params) */
+    validate?: {
+        safeParse: (data: unknown) => {
+            success: boolean;
+            data?: TValidated;
+            error?: {
+                issues: Array<{
+                    path: PropertyKey[];
+                    message: string;
+                }>;
+                flatten?: () => {
+                    fieldErrors: Record<string, string[]>;
+                };
+            };
+        };
+    };
+    /** Audit action name */
+    audit?: string;
+    /** Audit resource type */
+    auditResource?: string;
+    /** Custom operation name for logging */
+    operation?: string;
+}
+/** Context passed to route handlers */
+interface SecureRouteContext<TSession extends SecureSession = SecureSession, TValidated = unknown, TParams = Record<string, string>> {
+    /** Authenticated session (null for public APIs) */
+    session: TSession | null;
+    /** Whether request was authenticated via legacy token */
+    isLegacyToken: boolean;
+    /** Whether the user has admin privileges */
+    isAdmin: boolean;
+    /** Validated input data */
+    validated: TValidated;
+    /** Request-scoped logger */
+    logger: SecureLogger;
+    /** Request correlation ID */
+    requestId: string;
+    /** Resolved route params */
+    params: TParams;
+}
+/** Route handler function */
+type SecureRouteHandler<TSession extends SecureSession = SecureSession, TValidated = unknown, TParams = Record<string, string>> = (request: Request, context: SecureRouteContext<TSession, TValidated, TParams>) => Promise<Response>;
+/**
+ * Create a set of composable API security wrappers for your app.
+ *
+ * Returns `withPublicApi`, `withAuthenticatedApi`, `withAdminApi`,
+ * and `createSecureHandler` for custom auth requirements.
+ */
+declare function createSecureHandlerFactory<TSession extends SecureSession = SecureSession, TPresetKey extends string = string>(factoryConfig: SecureHandlerFactoryConfig<TSession, TPresetKey>): {
+    createSecureHandler: <TValidated = unknown, TParams = Record<string, string>>(routeConfig: SecureRouteConfig<TValidated, TPresetKey> & {
+        requireAuth?: boolean;
+        requireAdmin?: boolean;
+        requireRoles?: string[];
+        allowLegacyToken?: boolean;
+    }, handler: SecureRouteHandler<TSession, TValidated, TParams>) => (request: Request, routeContext: {
+        params: Promise<TParams>;
+    }) => Promise<Response>;
+    withPublicApi: <TValidated = unknown, TParams = Record<string, string>>(config: SecureRouteConfig<TValidated, TPresetKey>, handler: SecureRouteHandler<TSession, TValidated, TParams>) => (request: Request, routeContext: {
+        params: Promise<TParams>;
+    }) => Promise<Response>;
+    withAuthenticatedApi: <TValidated = unknown, TParams = Record<string, string>>(config: SecureRouteConfig<TValidated, TPresetKey>, handler: SecureRouteHandler<TSession, TValidated, TParams>) => (request: Request, routeContext: {
+        params: Promise<TParams>;
+    }) => Promise<Response>;
+    withAdminApi: <TValidated = unknown, TParams = Record<string, string>>(config: SecureRouteConfig<TValidated, TPresetKey>, handler: SecureRouteHandler<TSession, TValidated, TParams>) => (request: Request, routeContext: {
+        params: Promise<TParams>;
+    }) => Promise<Response>;
+    withLegacyAdminApi: <TValidated = unknown, TParams = Record<string, string>>(config: SecureRouteConfig<TValidated, TPresetKey>, handler: SecureRouteHandler<TSession, TValidated, TParams>) => (request: Request, routeContext: {
+        params: Promise<TParams>;
+    }) => Promise<Response>;
+};
+
+export { type FederatedLogoutConfig, type LazyRateLimitStoreOptions, RateLimitOptions, type RateLimitResult, RateLimitRule, RateLimitStore, type RedisRateLimitClient, type RedisRateLimitStoreOptions, type SecureHandlerFactoryConfig, type SecureLogger, type SecureRateLimitResult, type SecureRouteConfig, type SecureRouteContext, type SecureRouteHandler, type SecureSession, addRateLimitHeaders, buildFederatedLogoutHandler, createLazyRateLimitStore, createRedisRateLimitStore, createSecureHandlerFactory, enforceRateLimit, errorResponse, extractBearerToken, getClientIp, isValidBearerToken, rateLimitResponse, safeValidate, verifyCronAuth, zodErrorResponse };

package/dist/auth.d.ts

@@ -142,7 +142,7 @@ declare function errorResponse(error: unknown, options?: {
  */
 declare function zodErrorResponse(error: {
     issues: Array<{
-        path: (string | number)[];
+        path: PropertyKey[];
         message: string;
     }>;
 }): Response;
@@ -387,4 +387,189 @@ interface LazyRateLimitStoreOptions {
  */
 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 };
+/**
+ * Composable Secure API Handler Factory
+ *
+ * A generic, dependency-injected version of DLL's `withAuthenticatedApi` pattern.
+ * Apps provide their own auth, rate limiting, audit, and logger implementations
+ * via `createSecureHandlerFactory()`, then use the returned wrappers.
+ *
+ * This avoids coupling to any specific auth library (Auth.js, Keycloak, etc.)
+ * while providing consistent security middleware across all apps.
+ *
+ * @example
+ * ```typescript
+ * // lib/api-security.ts — app-level setup (once per app)
+ * import { createSecureHandlerFactory } from '@digilogiclabs/platform-core/auth'
+ * import { auth } from '@/auth'
+ *
+ * export const { withPublicApi, withAuthenticatedApi, withAdminApi } =
+ *   createSecureHandlerFactory({
+ *     getSession: () => auth(),
+ *     isAdmin: (session) => session?.user?.roles?.includes('admin') ?? false,
+ *     rateLimiter: { enforce: enforceRateLimit, presets: MY_PRESETS },
+ *     classifyError,
+ *   })
+ *
+ * // app/api/items/route.ts — per-route usage
+ * export const POST = withAuthenticatedApi({
+ *   rateLimit: 'mutation',
+ *   validate: CreateItemSchema,
+ * }, async (request, { session, validated }) => {
+ *   return Response.json({ created: true })
+ * })
+ * ```
+ */
+/** Minimal session shape — apps extend this with their own session type */
+interface SecureSession {
+    user?: {
+        id?: string;
+        email?: string | null;
+        name?: string | null;
+        roles?: string[];
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+}
+/** Result from a rate limit check */
+interface SecureRateLimitResult {
+    allowed: boolean;
+    limit: number;
+    remaining: number;
+    current?: number;
+    resetMs?: number;
+}
+/** Minimal logger interface */
+interface SecureLogger {
+    info(message: string, meta?: Record<string, unknown>): void;
+    warn(message: string, meta?: Record<string, unknown>): void;
+    error(message: string, meta?: Record<string, unknown>): void;
+}
+/** Configuration for the secure handler factory */
+interface SecureHandlerFactoryConfig<TSession extends SecureSession = SecureSession, TPresetKey extends string = string> {
+    /** Get the current authenticated session (e.g. from Auth.js) */
+    getSession: () => Promise<TSession | null>;
+    /** Check if a session has admin privileges */
+    isAdmin: (session: TSession | null) => boolean;
+    /** Check if a session has any of the required roles */
+    hasAnyRole?: (session: TSession | null, roles: string[]) => boolean;
+    /** Rate limiting integration */
+    rateLimiter?: {
+        /** Check and enforce rate limit — return response if blocked, null if allowed */
+        enforce: (request: Request, operation: string, preset: TPresetKey, userId?: string) => Promise<Response | null>;
+        /** Default preset for public APIs */
+        publicDefault?: TPresetKey;
+        /** Default preset for authenticated APIs */
+        authDefault?: TPresetKey;
+        /** Default preset for admin APIs */
+        adminDefault?: TPresetKey;
+    };
+    /** Optional: legacy admin token secret (Bearer token auth) */
+    adminSecret?: string;
+    /** Optional: audit logging */
+    auditLog?: (entry: {
+        actor: {
+            id: string;
+            type: string;
+            email?: string;
+        };
+        action: string;
+        resource?: {
+            type: string;
+            id: string;
+        };
+        outcome: "success" | "failure" | "blocked";
+        reason?: string;
+        metadata?: Record<string, unknown>;
+    }) => Promise<void>;
+    /** Optional: create a request-scoped logger */
+    createLogger?: (request: Request, operation: string) => SecureLogger;
+    /** Optional: error classifier (defaults to platform-core classifyError) */
+    classifyError?: (error: unknown, isDev: boolean) => {
+        status: number;
+        body: {
+            error: string;
+            code?: string;
+        };
+    };
+    /** Is the app running in development mode (default: NODE_ENV check) */
+    isDevelopment?: boolean;
+}
+/** Per-route config */
+interface SecureRouteConfig<TValidated = unknown, TPresetKey extends string = string> {
+    /** Rate limit preset key */
+    rateLimit?: TPresetKey;
+    /** Skip rate limiting */
+    skipRateLimit?: boolean;
+    /** Zod schema for input validation (POST/PUT body, GET query params) */
+    validate?: {
+        safeParse: (data: unknown) => {
+            success: boolean;
+            data?: TValidated;
+            error?: {
+                issues: Array<{
+                    path: PropertyKey[];
+                    message: string;
+                }>;
+                flatten?: () => {
+                    fieldErrors: Record<string, string[]>;
+                };
+            };
+        };
+    };
+    /** Audit action name */
+    audit?: string;
+    /** Audit resource type */
+    auditResource?: string;
+    /** Custom operation name for logging */
+    operation?: string;
+}
+/** Context passed to route handlers */
+interface SecureRouteContext<TSession extends SecureSession = SecureSession, TValidated = unknown, TParams = Record<string, string>> {
+    /** Authenticated session (null for public APIs) */
+    session: TSession | null;
+    /** Whether request was authenticated via legacy token */
+    isLegacyToken: boolean;
+    /** Whether the user has admin privileges */
+    isAdmin: boolean;
+    /** Validated input data */
+    validated: TValidated;
+    /** Request-scoped logger */
+    logger: SecureLogger;
+    /** Request correlation ID */
+    requestId: string;
+    /** Resolved route params */
+    params: TParams;
+}
+/** Route handler function */
+type SecureRouteHandler<TSession extends SecureSession = SecureSession, TValidated = unknown, TParams = Record<string, string>> = (request: Request, context: SecureRouteContext<TSession, TValidated, TParams>) => Promise<Response>;
+/**
+ * Create a set of composable API security wrappers for your app.
+ *
+ * Returns `withPublicApi`, `withAuthenticatedApi`, `withAdminApi`,
+ * and `createSecureHandler` for custom auth requirements.
+ */
+declare function createSecureHandlerFactory<TSession extends SecureSession = SecureSession, TPresetKey extends string = string>(factoryConfig: SecureHandlerFactoryConfig<TSession, TPresetKey>): {
+    createSecureHandler: <TValidated = unknown, TParams = Record<string, string>>(routeConfig: SecureRouteConfig<TValidated, TPresetKey> & {
+        requireAuth?: boolean;
+        requireAdmin?: boolean;
+        requireRoles?: string[];
+        allowLegacyToken?: boolean;
+    }, handler: SecureRouteHandler<TSession, TValidated, TParams>) => (request: Request, routeContext: {
+        params: Promise<TParams>;
+    }) => Promise<Response>;
+    withPublicApi: <TValidated = unknown, TParams = Record<string, string>>(config: SecureRouteConfig<TValidated, TPresetKey>, handler: SecureRouteHandler<TSession, TValidated, TParams>) => (request: Request, routeContext: {
+        params: Promise<TParams>;
+    }) => Promise<Response>;
+    withAuthenticatedApi: <TValidated = unknown, TParams = Record<string, string>>(config: SecureRouteConfig<TValidated, TPresetKey>, handler: SecureRouteHandler<TSession, TValidated, TParams>) => (request: Request, routeContext: {
+        params: Promise<TParams>;
+    }) => Promise<Response>;
+    withAdminApi: <TValidated = unknown, TParams = Record<string, string>>(config: SecureRouteConfig<TValidated, TPresetKey>, handler: SecureRouteHandler<TSession, TValidated, TParams>) => (request: Request, routeContext: {
+        params: Promise<TParams>;
+    }) => Promise<Response>;
+    withLegacyAdminApi: <TValidated = unknown, TParams = Record<string, string>>(config: SecureRouteConfig<TValidated, TPresetKey>, handler: SecureRouteHandler<TSession, TValidated, TParams>) => (request: Request, routeContext: {
+        params: Promise<TParams>;
+    }) => Promise<Response>;
+};
+
+export { type FederatedLogoutConfig, type LazyRateLimitStoreOptions, RateLimitOptions, type RateLimitResult, RateLimitRule, RateLimitStore, type RedisRateLimitClient, type RedisRateLimitStoreOptions, type SecureHandlerFactoryConfig, type SecureLogger, type SecureRateLimitResult, type SecureRouteConfig, type SecureRouteContext, type SecureRouteHandler, type SecureSession, addRateLimitHeaders, buildFederatedLogoutHandler, createLazyRateLimitStore, createRedisRateLimitStore, createSecureHandlerFactory, enforceRateLimit, errorResponse, extractBearerToken, getClientIp, isValidBearerToken, rateLimitResponse, safeValidate, verifyCronAuth, zodErrorResponse };

package/dist/auth.js

@@ -64,6 +64,7 @@ __export(auth_exports, {
   createMemoryRateLimitStore: () => createMemoryRateLimitStore,
   createRedisRateLimitStore: () => createRedisRateLimitStore,
   createSafeTextSchema: () => createSafeTextSchema,
+  createSecureHandlerFactory: () => createSecureHandlerFactory,
   detectStage: () => detectStage,
   enforceRateLimit: () => enforceRateLimit,
   errorResponse: () => errorResponse,
@@ -1561,6 +1562,209 @@ function createLazyRateLimitStore(getRedis, options = {}) {
   };
 }
 
+// src/auth/secure-handler.ts
+function defaultLogger2(_request, operation) {
+  const prefix = `[${operation}]`;
+  return {
+    info: (msg, meta) => console.log(prefix, msg, meta ? JSON.stringify(meta) : ""),
+    warn: (msg, meta) => console.warn(prefix, msg, meta ? JSON.stringify(meta) : ""),
+    error: (msg, meta) => console.error(prefix, msg, meta ? JSON.stringify(meta) : "")
+  };
+}
+function createSecureHandlerFactory(factoryConfig) {
+  const isDev = factoryConfig.isDevelopment ?? process.env.NODE_ENV === "development";
+  const classify = factoryConfig.classifyError ?? classifyError;
+  const makeLogger = factoryConfig.createLogger ?? defaultLogger2;
+  function getRequestId(request) {
+    const headers = request.headers;
+    return headers.get("x-request-id") || headers.get("x-correlation-id") || crypto.randomUUID();
+  }
+  function checkLegacyToken(request) {
+    if (!factoryConfig.adminSecret) return false;
+    const auth = request.headers.get("authorization");
+    if (!auth?.startsWith("Bearer ")) return false;
+    return constantTimeEqual(auth.slice(7).trim(), factoryConfig.adminSecret);
+  }
+  function createSecureHandler(routeConfig, handler) {
+    return async (request, routeContext) => {
+      const requestId = getRequestId(request);
+      const operation = routeConfig.operation || `${request.method} ${new URL(request.url).pathname}`;
+      const log = makeLogger(request, operation);
+      const params = await routeContext.params;
+      let session = null;
+      let isAdmin = false;
+      let isLegacyToken = false;
+      try {
+        if (routeConfig.requireAuth || routeConfig.requireAdmin || routeConfig.requireRoles?.length) {
+          session = await factoryConfig.getSession();
+          if (session?.user) {
+            isAdmin = factoryConfig.isAdmin(session);
+          } else if (routeConfig.allowLegacyToken && checkLegacyToken(request)) {
+            isLegacyToken = true;
+            isAdmin = true;
+          } else {
+            log.warn("Unauthorized access attempt");
+            return Response.json(
+              { error: "Unauthorized" },
+              { status: 401, headers: { "X-Request-ID": requestId } }
+            );
+          }
+        }
+        if (routeConfig.requireAdmin && !isLegacyToken && !isAdmin) {
+          log.warn("Admin access denied");
+          return Response.json(
+            { error: "Forbidden: Admin access required" },
+            { status: 403, headers: { "X-Request-ID": requestId } }
+          );
+        }
+        if (routeConfig.requireRoles?.length && !isLegacyToken) {
+          const hasRole2 = factoryConfig.hasAnyRole ? factoryConfig.hasAnyRole(session, routeConfig.requireRoles) : routeConfig.requireRoles.some(
+            (r) => session?.user?.roles?.includes(r)
+          );
+          if (!hasRole2) {
+            log.warn("Role-based access denied");
+            return Response.json(
+              { error: "Forbidden: Insufficient permissions" },
+              { status: 403, headers: { "X-Request-ID": requestId } }
+            );
+          }
+        }
+        if (!routeConfig.skipRateLimit && routeConfig.rateLimit && factoryConfig.rateLimiter) {
+          const userId = session?.user?.id ?? void 0;
+          const blocked = await factoryConfig.rateLimiter.enforce(
+            request,
+            operation,
+            routeConfig.rateLimit,
+            userId
+          );
+          if (blocked) return blocked;
+        }
+        let validated = {};
+        if (routeConfig.validate) {
+          let input;
+          if (request.method === "GET") {
+            const url = new URL(request.url);
+            const qs = {};
+            url.searchParams.forEach((v, k) => qs[k] = v);
+            input = qs;
+          } else {
+            const ct = request.headers.get("content-type");
+            input = ct?.includes("application/json") ? await request.json() : {};
+          }
+          const result = routeConfig.validate.safeParse(input);
+          if (!result.success) {
+            const fieldErrors = result.error?.flatten ? result.error.flatten().fieldErrors : void 0;
+            return Response.json(
+              { error: "Validation error", errors: fieldErrors },
+              { status: 400, headers: { "X-Request-ID": requestId } }
+            );
+          }
+          validated = result.data;
+        }
+        const ctx = {
+          session,
+          isLegacyToken,
+          isAdmin,
+          validated,
+          logger: log,
+          requestId,
+          params
+        };
+        const response = await handler(request, ctx);
+        response.headers.set("X-Request-ID", requestId);
+        if (routeConfig.audit && factoryConfig.auditLog) {
+          const actorId = isLegacyToken ? "admin_token" : session?.user?.id || "anonymous";
+          await factoryConfig.auditLog({
+            actor: {
+              id: actorId,
+              type: isLegacyToken ? "admin" : "user",
+              email: session?.user?.email ?? void 0
+            },
+            action: routeConfig.audit,
+            resource: routeConfig.auditResource ? { type: routeConfig.auditResource, id: "unknown" } : void 0,
+            outcome: "success"
+          }).catch(() => {
+          });
+        }
+        return response;
+      } catch (error) {
+        log.error("Request handler error", {
+          error: error instanceof Error ? error.message : String(error)
+        });
+        if (routeConfig.audit && factoryConfig.auditLog) {
+          await factoryConfig.auditLog({
+            actor: {
+              id: session?.user?.id || "unknown",
+              type: "user"
+            },
+            action: routeConfig.audit,
+            outcome: "failure",
+            reason: error instanceof Error ? error.message : "Unknown error"
+          }).catch(() => {
+          });
+        }
+        const { status, body } = classify(error, isDev);
+        return Response.json(
+          { error: body.error, code: body.code },
+          { status, headers: { "X-Request-ID": requestId } }
+        );
+      }
+    };
+  }
+  function withPublicApi(config, handler) {
+    return createSecureHandler(
+      {
+        rateLimit: factoryConfig.rateLimiter?.publicDefault,
+        ...config,
+        requireAuth: false,
+        requireAdmin: false
+      },
+      handler
+    );
+  }
+  function withAuthenticatedApi(config, handler) {
+    return createSecureHandler(
+      {
+        rateLimit: factoryConfig.rateLimiter?.authDefault,
+        ...config,
+        requireAuth: true,
+        requireAdmin: false
+      },
+      handler
+    );
+  }
+  function withAdminApi(config, handler) {
+    return createSecureHandler(
+      {
+        rateLimit: factoryConfig.rateLimiter?.adminDefault,
+        ...config,
+        requireAuth: true,
+        requireAdmin: true
+      },
+      handler
+    );
+  }
+  function withLegacyAdminApi(config, handler) {
+    return createSecureHandler(
+      {
+        rateLimit: factoryConfig.rateLimiter?.adminDefault,
+        ...config,
+        requireAuth: true,
+        requireAdmin: true,
+        allowLegacyToken: true
+      },
+      handler
+    );
+  }
+  return {
+    createSecureHandler,
+    withPublicApi,
+    withAuthenticatedApi,
+    withAdminApi,
+    withLegacyAdminApi
+  };
+}
+
 // src/env.ts
 function getRequiredEnv(key) {
   const value = process.env[key];
@@ -1697,6 +1901,7 @@ function getEnvSummary(keys) {
   createMemoryRateLimitStore,
   createRedisRateLimitStore,
   createSafeTextSchema,
+  createSecureHandlerFactory,
   detectStage,
   enforceRateLimit,
   errorResponse,