@beignet/core 0.0.1 → 0.0.3

package/src/server/hooks/auth.ts

@@ -1,147 +1,132 @@
-import {
-  type AuthPort,
-  type AuthSession,
-  AuthUnauthorizedError,
-} from "../../ports";
-import type { HttpRequestLike, HttpResponse, ServerHook } from "../types";
+import { AuthUnauthorizedError } from "../../ports";
+import type { HttpRequestLike, RouteHook } from "../types";
 
 type MaybePromise<T> = T | Promise<T>;
 
-export type AuthHookMode = "public" | "optional" | "required";
-export type AuthHookModeInput = AuthHookMode | boolean | null | undefined;
-
-export type CtxWithAuthPort = {
-  ports: {
-    auth: AuthPort;
-  };
-};
-
+/**
+ * Arguments passed to auth route-hook callbacks.
+ */
 export type AuthHookArgs<Ctx> = {
+  /**
+   * Framework-neutral request.
+   */
   req: HttpRequestLike;
+  /**
+   * Current route handler context.
+   */
   ctx: Ctx;
+  /**
+   * Matched contract metadata and schemas.
+   */
   contract: {
     metadata?: Record<string, unknown>;
   };
+  /**
+   * Parsed path parameters.
+   */
   path: unknown;
+  /**
+   * Parsed query parameters.
+   */
   query: unknown;
+  /**
+   * Parsed request headers.
+   */
   headers: unknown;
+  /**
+   * Parsed request body.
+   */
   body: unknown;
 };
 
-export type AuthHookAssignArgs<Ctx, Session> = AuthHookArgs<Ctx> & {
-  session: Session | null;
-};
-
-export type AuthHookUnauthorizedArgs<Ctx, Session> = AuthHookArgs<Ctx> & {
-  session: Session | null;
-};
-
-export type AuthHooksOptions<Ctx, Session> = {
+/**
+ * Options for route-scoped auth hooks.
+ */
+export type AuthHooksOptions<Ctx, AddedCtx extends object> = {
+  /**
+   * Hook name prefix used in diagnostics.
+   */
   name?: string;
-  mode?: (args: AuthHookArgs<Ctx>) => MaybePromise<AuthHookModeInput>;
-  getSession?: (args: AuthHookArgs<Ctx>) => MaybePromise<Session | null>;
-  isAuthenticated?: (session: Session | null) => boolean;
-  assign?: (args: AuthHookAssignArgs<Ctx, Session>) => MaybePromise<Ctx>;
-  unauthorized?: (
-    args: AuthHookUnauthorizedArgs<Ctx, Session>,
-  ) => MaybePromise<HttpResponse>;
+  /**
+   * Resolve authenticated context additions for the current request.
+   *
+   * Return `null` when the request is unauthenticated. Required hooks will
+   * reject that request; optional hooks will add no auth context.
+   */
+  resolve: (args: AuthHookArgs<Ctx>) => MaybePromise<AddedCtx | null>;
 };
 
-type InferAuthSession<TAuth> =
-  TAuth extends AuthPort<infer User, infer SessionMetadata>
-    ? AuthSession<User, SessionMetadata>
-    : unknown;
-
-function modeFromInput(input: AuthHookModeInput): AuthHookMode {
-  if (input === true || input === "required") return "required";
-  if (input === "optional") return "optional";
-  return "public";
-}
-
-function defaultMode<Ctx>(args: AuthHookArgs<Ctx>): AuthHookMode {
-  return modeFromInput(args.contract.metadata?.auth as AuthHookModeInput);
-}
-
-async function defaultGetSession<Ctx>(
-  args: AuthHookArgs<Ctx>,
-): Promise<unknown | null> {
-  const auth = (args.ctx as { ports?: { auth?: AuthPort } }).ports?.auth;
-  if (!auth) {
-    throw new Error(
-      "createAuthHooks requires ctx.ports.auth or an explicit getSession option.",
-    );
-  }
+/**
+ * Route-scoped auth hook set.
+ */
+export type AuthRouteHooks<Ctx, AddedCtx extends object> = {
+  /**
+   * Mark a route as intentionally public.
+   */
+  public: () => RouteHook<Ctx, Record<string, never>>;
+  /**
+   * Resolve auth when present and add optional auth fields to the handler ctx.
+   */
+  optional: () => RouteHook<Ctx, Partial<AddedCtx>>;
+  /**
+   * Require auth and add authenticated fields to the handler ctx.
+   */
+  required: () => RouteHook<Ctx, AddedCtx>;
+};
 
-  return auth.getSession(args.req);
+function toAuthArgs<Ctx>(
+  args: Parameters<RouteHook<Ctx, object>["resolve"]>[0],
+): AuthHookArgs<Ctx> {
+  return {
+    req: args.req,
+    ctx: args.ctx,
+    contract: args.contract,
+    path: args.path,
+    query: args.query,
+    headers: args.headers,
+    body: args.body,
+  };
 }
 
-function defaultIsAuthenticated<Session>(session: Session | null): boolean {
-  return session !== null;
-}
+/**
+ * Create route-scoped authentication hooks.
+ *
+ * Use `auth.required()` on routes that require an authenticated actor and
+ * `auth.optional()` where handlers can use auth when present. The returned
+ * route hooks enrich handler `ctx`; business authorization still belongs in
+ * feature policies or use cases.
+ *
+ * @param options - Auth resolution callback and optional diagnostic name.
+ * @returns Public, optional, and required route-hook factories.
+ */
+export function createAuthHooks<Ctx, AddedCtx extends object>(
+  options: AuthHooksOptions<Ctx, AddedCtx>,
+): AuthRouteHooks<Ctx, AddedCtx> {
+  const name = options.name ?? "auth";
 
-export function createAuthHooks<Ctx extends CtxWithAuthPort>(
-  options?: AuthHooksOptions<Ctx, InferAuthSession<Ctx["ports"]["auth"]>>,
-): ServerHook<Ctx, Ctx["ports"]>;
-export function createAuthHooks<Ctx, Session>(
-  options: AuthHooksOptions<Ctx, Session> & {
-    getSession: (args: AuthHookArgs<Ctx>) => MaybePromise<Session | null>;
-  },
-): ServerHook<Ctx>;
-export function createAuthHooks<Ctx, Session>(
-  options: AuthHooksOptions<Ctx, Session> = {},
-): ServerHook<Ctx> {
   return {
-    name: options.name ?? "auth",
-    beforeHandle: async ({
-      req,
-      ctx,
-      contract,
-      path,
-      query,
-      headers,
-      body,
-    }) => {
-      const args: AuthHookArgs<Ctx> = {
-        req,
-        ctx,
-        contract,
-        path,
-        query,
-        headers,
-        body,
-      };
-      const mode = modeFromInput(
-        options.mode ? await options.mode(args) : defaultMode(args),
-      );
-
-      if (mode === "public") {
-        return undefined;
-      }
-
-      const session = options.getSession
-        ? await options.getSession(args)
-        : ((await defaultGetSession(args)) as Session | null);
-      const isAuthenticated =
-        options.isAuthenticated?.(session) ?? defaultIsAuthenticated(session);
-
-      if (mode === "required" && !isAuthenticated) {
-        if (options.unauthorized) {
-          return {
-            ctx,
-            response: await options.unauthorized({ ...args, session }),
-          };
+    public: () => ({
+      name: `${name}.public`,
+      resolve: () => undefined,
+    }),
+    optional: () => ({
+      name: `${name}.optional`,
+      resolve: async (args) => {
+        const additions = await options.resolve(toAuthArgs(args));
+
+        return additions ?? undefined;
+      },
+    }),
+    required: () => ({
+      name: `${name}.required`,
+      resolve: async (args) => {
+        const additions = await options.resolve(toAuthArgs(args));
+        if (!additions) {
+          throw new AuthUnauthorizedError();
         }
 
-        throw new AuthUnauthorizedError();
-      }
-
-      if (!options.assign) {
-        return undefined;
-      }
-
-      return {
-        ctx: await options.assign({ ...args, session }),
-      };
-    },
+        return additions;
+      },
+    }),
   };
 }

package/src/server/hooks/cors.ts

@@ -4,10 +4,25 @@
 
 import type { HttpRequestLike, ServerHook } from "../types";
 
+/**
+ * CORS configuration for `createCorsHooks(...)`.
+ */
 export interface CorsConfig {
+  /**
+   * Allowed origins. Use `"*"` to allow any origin.
+   */
   origins?: string[] | "*";
+  /**
+   * Allowed HTTP methods.
+   */
   methods?: string[];
+  /**
+   * Allowed request headers.
+   */
   headers?: string[];
+  /**
+   * Whether credentialed requests are allowed.
+   */
   credentials?: boolean;
 }
 
@@ -28,6 +43,12 @@ function appendVaryOrigin(headers: Record<string, string>): void {
   headers[varyKey] = current ? `${current}, Origin` : "Origin";
 }
 
+/**
+ * Apply CORS response headers to a mutable header record.
+ *
+ * When credentials are enabled with wildcard origins, the request origin is
+ * reflected and `Vary: Origin` is appended.
+ */
 export function applyCorsHeaders(
   headers: Record<string, string>,
   req: HttpRequestLike,
@@ -62,6 +83,12 @@ export function applyCorsHeaders(
   }
 }
 
+/**
+ * Create CORS hooks for preflight and regular responses.
+ *
+ * `OPTIONS` requests short-circuit with a 204 response. All other responses are
+ * decorated in `beforeSend`.
+ */
 export function createCorsHooks<Ctx>(config: CorsConfig): ServerHook<Ctx> {
   return {
     name: "cors",

package/src/server/hooks/errors.ts

@@ -7,30 +7,39 @@ import type { AppEnvironment } from "../health";
 import { getRequestIdFromContext } from "./utils";
 
 /**
- * Re-export AppEnvironment for convenience
+ * Re-export `AppEnvironment` for convenience.
  */
 export type { AppEnvironment } from "../health";
 
 /**
- * Error mapping result
+ * Framework-neutral response produced by an error mapper.
  */
 export interface ErrorMappingResult {
+  /**
+   * HTTP status code.
+   */
   status: number;
+  /**
+   * Response body.
+   */
   body: unknown;
+  /**
+   * Response headers.
+   */
   headers?: Record<string, string>;
 }
 
 /**
- * Error mapping configuration
+ * Error mapping configuration.
  */
 export interface ErrorMappingConfig<Ctx> {
-  /** Custom error mapper function */
+  /** Custom error mapper function. */
   mapErrorToResponse?: (err: unknown, ctx: Ctx) => ErrorMappingResult;
 
-  /** Include stack traces in error responses (default: true in dev/test, false in production) */
+  /** Include stack traces in error responses. Defaults to true in dev/test. */
   includeStackInResponse?: boolean;
 
-  /** Application environment */
+  /** Application environment. */
   env?: AppEnvironment;
 }
 

package/src/server/hooks/index.ts

@@ -7,12 +7,8 @@ import type { ServerHook } from "../http";
 
 export {
   type AuthHookArgs,
-  type AuthHookAssignArgs,
-  type AuthHookMode,
-  type AuthHookModeInput,
   type AuthHooksOptions,
-  type AuthHookUnauthorizedArgs,
-  type CtxWithAuthPort,
+  type AuthRouteHooks,
   createAuthHooks,
 } from "./auth";
 export {
@@ -36,6 +32,9 @@ export {
   type RateLimitOptions,
 } from "./rate-limit";
 
+/**
+ * Flatten hook arrays into a single hook list.
+ */
 export function composeHooks<Ctx, Ports extends AnyPorts = AnyPorts>(
   ...hooks: (ServerHook<Ctx, Ports> | readonly ServerHook<Ctx, Ports>[])[]
 ): ServerHook<Ctx, Ports>[] {

package/src/server/hooks/logging.ts

@@ -6,21 +6,51 @@ import type { HttpContractConfig } from "../../contracts";
 import type { HttpRequestLike, ServerHook } from "../types";
 import { getRequestIdFromContext } from "./utils";
 
+/**
+ * Minimal logger shape accepted by `createLoggingHooks(...)`.
+ */
 export interface Logger {
+  /**
+   * Log an informational event.
+   */
   info: (...args: unknown[]) => void;
+  /**
+   * Log an error event.
+   */
   error: (...args: unknown[]) => void;
+  /**
+   * Log a warning event.
+   */
   warn?: (...args: unknown[]) => void;
+  /**
+   * Log a debug event.
+   */
   debug?: (...args: unknown[]) => void;
 }
 
+/**
+ * Logging hook configuration.
+ */
 export interface LoggingConfig<Ctx> {
+  /**
+   * Logger used when custom lifecycle callbacks are not provided.
+   */
   logger?: Logger;
+  /**
+   * Response header name used to expose `ctx.requestId` when present.
+   */
   requestIdHeader?: string;
+  /**
+   * Custom request-start observer.
+   */
   onRequestStart?: (args: {
     ctx?: Ctx;
     req: HttpRequestLike;
     contract?: HttpContractConfig;
   }) => void;
+  /**
+   * Custom request-end observer.
+   */
   onRequestEnd?: (args: {
     ctx?: Ctx;
     req: HttpRequestLike;
@@ -31,6 +61,12 @@ export interface LoggingConfig<Ctx> {
   }) => void;
 }
 
+/**
+ * Create request logging hooks.
+ *
+ * Logging observer errors are intentionally ignored so logging cannot break
+ * request handling.
+ */
 export function createLoggingHooks<Ctx>(
   config: LoggingConfig<Ctx>,
 ): ServerHook<Ctx> {

package/src/server/hooks/rate-limit.ts

@@ -7,10 +7,16 @@ import { AppError, httpErrors } from "../../errors";
 import type { ActivityActor, RateLimitPort } from "../../ports";
 import type { HttpRequestLike, ServerHook } from "../types";
 
+/**
+ * Ports required by rate-limit hooks.
+ */
 export type RateLimitPorts = {
   rateLimit: RateLimitPort;
 };
 
+/**
+ * Minimal context shape required for user-scoped rate limits.
+ */
 export type CtxWithRateLimit = {
   ports: RateLimitPorts;
   actor?: ActivityActor;
@@ -18,16 +24,32 @@ export type CtxWithRateLimit = {
 
 type EarlyRateLimitScope = Exclude<RateLimitScope, "user">;
 
+/**
+ * Options for `createRateLimitHooks(...)`.
+ */
 export interface RateLimitOptions<Ctx> {
+  /**
+   * Build a rate-limit key after context exists.
+   *
+   * This is used for user-scoped limits and any late key strategy.
+   */
   key?: (args: {
     ctx: Ctx;
     req: HttpRequestLike;
     scope: RateLimitScope;
   }) => string;
+  /**
+   * Build a rate-limit key before request parsing and context creation.
+   *
+   * This is used for global and IP-scoped limits.
+   */
   earlyKey?: (args: {
     req: HttpRequestLike;
     scope: EarlyRateLimitScope;
   }) => string;
+  /**
+   * Resolve a client IP from the raw request.
+   */
   getClientIp?: (req: HttpRequestLike) => string | undefined;
 }
 
@@ -112,6 +134,17 @@ async function enforceRateLimit(
   );
 }
 
+/**
+ * Create metadata-driven rate-limit hooks.
+ *
+ * The hook reads `contract.metadata.rateLimit`. Global and IP-scoped limits run
+ * in `onRequest` before context creation; user-scoped limits run in
+ * `beforeHandle` after `ctx.actor` is available. Exceeded limits throw the
+ * framework `TooManyRequests` app error.
+ *
+ * @param options - Optional key builders and client-IP resolver.
+ * @returns A server hook backed by `ctx.ports.rateLimit`.
+ */
 export function createRateLimitHooks<Ctx extends CtxWithRateLimit>(
   options: RateLimitOptions<Ctx> = {},
 ): ServerHook<Ctx, RateLimitPorts> {