@beignet/core 0.0.2 → 0.0.3

package/src/server/hooks/auth.ts

@@ -1,205 +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>;
 
 /**
- * Authentication mode for one matched contract.
- */
-export type AuthHookMode = "public" | "optional" | "required";
-
-/**
- * Input accepted when resolving auth mode from contract metadata or options.
- *
- * `true` maps to `"required"`; `false`, `null`, and `undefined` map to
- * `"public"`.
- */
-export type AuthHookModeInput = AuthHookMode | boolean | null | undefined;
-
-/**
- * Minimal context shape required when `createAuthHooks(...)` reads
- * `ctx.ports.auth`.
- */
-export type CtxWithAuthPort = {
-  ports: {
-    auth: AuthPort;
-  };
-};
-
-/**
- * Arguments passed to auth hook callbacks.
+ * 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;
 };
 
 /**
- * Arguments passed to the auth `assign` callback.
- */
-export type AuthHookAssignArgs<Ctx, Session> = AuthHookArgs<Ctx> & {
-  session: Session | null;
-};
-
-/**
- * Arguments passed to the auth `unauthorized` callback.
+ * Options for route-scoped auth hooks.
  */
-export type AuthHookUnauthorizedArgs<Ctx, Session> = AuthHookArgs<Ctx> & {
-  session: Session | null;
-};
-
-/**
- * Options for `createAuthHooks(...)`.
- */
-export type AuthHooksOptions<Ctx, Session> = {
+export type AuthHooksOptions<Ctx, AddedCtx extends object> = {
   /**
-   * Hook name used in diagnostics.
+   * Hook name prefix used in diagnostics.
    */
   name?: string;
   /**
-   * Resolve whether the current contract is public, optional-auth, or required-auth.
-   */
-  mode?: (args: AuthHookArgs<Ctx>) => MaybePromise<AuthHookModeInput>;
-  /**
-   * Custom session lookup. Required when context does not expose
-   * `ctx.ports.auth`.
+   * 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.
    */
-  getSession?: (args: AuthHookArgs<Ctx>) => MaybePromise<Session | null>;
+  resolve: (args: AuthHookArgs<Ctx>) => MaybePromise<AddedCtx | null>;
+};
+
+/**
+ * Route-scoped auth hook set.
+ */
+export type AuthRouteHooks<Ctx, AddedCtx extends object> = {
   /**
-   * Decide whether a resolved session counts as authenticated.
+   * Mark a route as intentionally public.
    */
-  isAuthenticated?: (session: Session | null) => boolean;
+  public: () => RouteHook<Ctx, Record<string, never>>;
   /**
-   * Return an updated context with auth/session fields attached.
+   * Resolve auth when present and add optional auth fields to the handler ctx.
    */
-  assign?: (args: AuthHookAssignArgs<Ctx, Session>) => MaybePromise<Ctx>;
+  optional: () => RouteHook<Ctx, Partial<AddedCtx>>;
   /**
-   * Return a custom unauthorized response for required-auth routes.
+   * Require auth and add authenticated fields to the handler ctx.
    */
-  unauthorized?: (
-    args: AuthHookUnauthorizedArgs<Ctx, Session>,
-  ) => MaybePromise<HttpResponse>;
+  required: () => RouteHook<Ctx, AddedCtx>;
 };
 
-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.",
-    );
-  }
-
-  return auth.getSession(args.req);
-}
-
-function defaultIsAuthenticated<Session>(session: Session | null): boolean {
-  return session !== null;
+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,
+  };
 }
 
 /**
- * Create metadata-driven authentication hooks.
+ * Create route-scoped authentication hooks.
  *
- * By default the hook reads `contract.metadata.auth`: `"required"` or `true`
- * requires an authenticated session, `"optional"` attaches a session when one
- * exists, and missing/false metadata treats the route as public. The hook
- * identifies a user; business authorization still belongs in policies or use
- * cases.
+ * 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 - Optional auth mode, session lookup, context assignment, and
- * unauthorized response customization.
- * @returns A server hook that runs before route handlers.
+ * @param options - Auth resolution callback and optional diagnostic name.
+ * @returns Public, optional, and required route-hook factories.
  */
-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);
+export function createAuthHooks<Ctx, AddedCtx extends object>(
+  options: AuthHooksOptions<Ctx, AddedCtx>,
+): AuthRouteHooks<Ctx, AddedCtx> {
+  const name = options.name ?? "auth";
 
-      if (mode === "required" && !isAuthenticated) {
-        if (options.unauthorized) {
-          return {
-            ctx,
-            response: await options.unauthorized({ ...args, session }),
-          };
+  return {
+    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/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 {

package/src/server/http.ts

@@ -168,6 +168,85 @@ export type Handler<Ctx, C extends HttpContractConfig> = (
  */
 export type MaybePromise<T> = T | Promise<T>;
 
+/**
+ * Arguments passed to a route-scoped hook after request parsing and context
+ * creation.
+ */
+export type RouteHookArgs<
+  Ctx,
+  C extends HttpContractConfig = HttpContractConfig,
+> = HandlerArgs<Ctx, C>;
+
+/**
+ * Hook that runs only for the route or route group where it is attached.
+ *
+ * Route hooks are for scoped policy and context enrichment such as
+ * authentication, tenant resolution, feature gates, and idempotency. They add
+ * fields to the handler context instead of replacing the app context.
+ */
+export interface RouteHook<
+  Ctx,
+  AddedCtx extends object = Record<string, never>,
+> {
+  /**
+   * Optional name used in diagnostics and devtools.
+   */
+  name?: string;
+  /**
+   * Resolve additional context for this route or throw to stop handling.
+   */
+  resolve: (args: RouteHookArgs<Ctx>) => MaybePromise<AddedCtx | undefined>;
+}
+
+/**
+ * Builder for route-scoped hooks.
+ */
+export type RouteHookBuilder<Ctx> = {
+  /**
+   * Assign a diagnostic name to the hook.
+   */
+  name: (name: string) => RouteHookNamedBuilder<Ctx>;
+  /**
+   * Define the hook resolver.
+   */
+  resolve: <AddedCtx extends object>(
+    resolve: RouteHook<Ctx, AddedCtx>["resolve"],
+  ) => RouteHook<Ctx, AddedCtx>;
+};
+
+/**
+ * Named builder for route-scoped hooks.
+ */
+export type RouteHookNamedBuilder<Ctx> = {
+  /**
+   * Define the hook resolver.
+   */
+  resolve: <AddedCtx extends object>(
+    resolve: RouteHook<Ctx, AddedCtx>["resolve"],
+  ) => RouteHook<Ctx, AddedCtx>;
+};
+
+/**
+ * Define a route-scoped hook.
+ *
+ * Route hooks enrich handler context for one route or route group. They should
+ * throw application/framework errors for denials instead of returning HTTP
+ * responses directly.
+ */
+export function defineRouteHook<Ctx>(): RouteHookBuilder<Ctx> {
+  return {
+    name: (name) => ({
+      resolve: (resolve) => ({
+        name,
+        resolve,
+      }),
+    }),
+    resolve: (resolve) => ({
+      resolve,
+    }),
+  };
+}
+
 /**
  * Hook that runs after a route is matched but before request parsing and
  * context creation.

package/src/server/index.ts

@@ -46,6 +46,7 @@ export type {
 export {
   contractsFromRoutes,
   createServer,
+  defineRoute,
   defineRouteGroup,
   defineRoutes,
 } from "./server";