@beignet/core 0.0.2 → 0.0.4

package/src/server/context.ts

@@ -0,0 +1,224 @@
+import type { HttpContractConfig } from "../contracts/index.js";
+import type {
+  AnyPorts,
+  BoundGate,
+  GatePort,
+  PolicyDefinition,
+} from "../ports/index.js";
+import type { TraceContext } from "../tracing/index.js";
+import type { HttpRequestLike, MaybePromise } from "./http.js";
+
+/**
+ * Arguments passed to the `context.request` factory after a route is matched.
+ */
+export type RequestContextArgs<Ports extends AnyPorts = AnyPorts> = {
+  /**
+   * Framework-neutral request.
+   */
+  req: HttpRequestLike;
+  /**
+   * Final app ports, including ports contributed by providers.
+   */
+  ports: Ports;
+  /**
+   * Matched contract, when the request resolved to a registered route.
+   */
+  contract?: HttpContractConfig;
+  /**
+   * Request correlation ID resolved by the server from the configured request
+   * ID header, or generated when the request did not send one.
+   */
+  requestId: string;
+  /**
+   * W3C trace context resolved by the server from the incoming `traceparent`
+   * header, or generated when the request did not send one. Spread this into
+   * the context (`...trace`) to correlate downstream activity.
+   */
+  trace: TraceContext;
+};
+
+/**
+ * Arguments passed to the `context.service` factory.
+ */
+export type ServiceContextArgs<
+  Ports extends AnyPorts = AnyPorts,
+  ServiceInput = void,
+> = {
+  /**
+   * Final app ports, including ports contributed by providers.
+   */
+  ports: Ports;
+  /**
+   * Caller-provided input such as the service actor or tenant.
+   */
+  input: ServiceInput;
+  /**
+   * Fresh correlation ID generated for this service context.
+   */
+  requestId: string;
+  /**
+   * Fresh W3C trace context generated for this service context. Spread this
+   * into the context (`...trace`) to correlate downstream activity.
+   */
+  trace: TraceContext;
+};
+
+/**
+ * App context without its `gate` property.
+ *
+ * Context factories return seeds; the server attaches the gate declared by
+ * the blueprint's `gate` selector, so hand-binding `gate` in a factory is a
+ * type error.
+ */
+export type ContextSeed<Ctx> = Omit<Ctx, "gate"> & { gate?: never };
+
+type ContextGateOption<Ctx, Ports extends AnyPorts> = [Ctx] extends [
+  { gate: BoundGate<infer TPolicies extends readonly PolicyDefinition[]> },
+]
+  ? {
+      /**
+       * Select the gate port the server attaches to every context it builds.
+       */
+      gate: (ports: Ports) => GatePort<ContextSeed<Ctx>, TPolicies>;
+    }
+  : {
+      /**
+       * Gate selection is only available when the context type declares a
+       * `gate` property.
+       */
+      gate?: never;
+    };
+
+/**
+ * Context blueprint accepted by `createServer(...)`.
+ *
+ * The server owns context assembly: `request` and `service` return context
+ * seeds, and the server attaches the gate declared by `gate` so identity
+ * changes can never authorize against a stale context.
+ */
+export type ServerContextOptions<
+  Ctx,
+  Ports extends AnyPorts = AnyPorts,
+  ServiceInput = void,
+> = {
+  /**
+   * Build the per-request context seed.
+   */
+  request: (args: RequestContextArgs<Ports>) => MaybePromise<ContextSeed<Ctx>>;
+  /**
+   * Build a service context seed for schedules, outbox drains, tasks, and
+   * background work. Required before `server.createServiceContext(...)` can
+   * be called.
+   */
+  service?: (
+    args: ServiceContextArgs<Ports, ServiceInput>,
+  ) => MaybePromise<ContextSeed<Ctx>>;
+} & ContextGateOption<Ctx, Ports>;
+
+/**
+ * Context configuration accepted by `createServer(...)`.
+ *
+ * Contexts without a `gate` property may use the plain request-factory
+ * shorthand. Contexts with a `gate` must use the blueprint form so the server
+ * owns gate attachment.
+ */
+export type ServerContextConfig<
+  Ctx,
+  Ports extends AnyPorts = AnyPorts,
+  ServiceInput = void,
+> = [Ctx] extends [{ gate: unknown }]
+  ? ServerContextOptions<Ctx, Ports, ServiceInput>
+  :
+      | ((args: RequestContextArgs<Ports>) => MaybePromise<Ctx>)
+      | ServerContextOptions<Ctx, Ports, ServiceInput>;
+
+/**
+ * Argument tuple for `createServiceContext(...)`.
+ *
+ * Servers without a declared service input are callable with no arguments;
+ * optional inputs stay optional at the call site.
+ */
+export type ServiceContextInputArgs<ServiceInput> = [ServiceInput] extends [
+  // biome-ignore lint/suspicious/noConfusingVoidType: void marks "no declared service input" here
+  void,
+]
+  ? []
+  : undefined extends ServiceInput
+    ? [input?: ServiceInput]
+    : [input: ServiceInput];
+
+type AnyGateSelector<Ports extends AnyPorts> = (
+  ports: Ports,
+) => Pick<GatePort<unknown>, "attach">;
+
+/**
+ * Normalized runtime view of a server context configuration.
+ */
+export type ResolvedServerContext<Ctx, Ports extends AnyPorts, ServiceInput> = {
+  request: (
+    args: RequestContextArgs<Ports>,
+  ) => MaybePromise<ContextSeed<Ctx> | Ctx>;
+  service?: (
+    args: ServiceContextArgs<Ports, ServiceInput>,
+  ) => MaybePromise<ContextSeed<Ctx>>;
+  gate?: AnyGateSelector<Ports>;
+};
+
+/**
+ * Normalize a server context configuration into its runtime parts.
+ */
+export function resolveServerContext<Ctx, Ports extends AnyPorts, ServiceInput>(
+  config: ServerContextConfig<Ctx, Ports, ServiceInput>,
+): ResolvedServerContext<Ctx, Ports, ServiceInput> {
+  const value = config as
+    | ((args: RequestContextArgs<Ports>) => MaybePromise<Ctx>)
+    | (ResolvedServerContext<Ctx, Ports, ServiceInput> & {
+        gate?: AnyGateSelector<Ports>;
+      });
+
+  if (typeof value === "function") {
+    return { request: value };
+  }
+
+  return {
+    request: value.request,
+    service: value.service,
+    gate: value.gate,
+  };
+}
+
+/**
+ * Create the context finalizer for a resolved server context.
+ *
+ * When the blueprint declares a gate, the finalizer strips hand-assigned
+ * `gate` values from seeds and attaches the live gate. Without a gate
+ * declaration the seed is the context.
+ */
+export function createContextFinalizer<
+  Ctx,
+  Ports extends AnyPorts,
+  ServiceInput,
+>(
+  resolved: ResolvedServerContext<Ctx, Ports, ServiceInput>,
+  getPorts: () => Ports,
+): (seed: ContextSeed<Ctx> | Ctx) => Ctx {
+  const gateSelector = resolved.gate;
+  if (!gateSelector) {
+    return (seed) => seed as Ctx;
+  }
+
+  return (seed) => {
+    const target = seed as object;
+    const existing = Object.getOwnPropertyDescriptor(target, "gate");
+    if (existing && existing.get === undefined) {
+      if (process.env.NODE_ENV !== "production") {
+        console.warn(
+          "[beignet] Ignoring a hand-assigned ctx.gate value. The server context blueprint owns gate attachment; remove `gate` from context factories and hook additions.",
+        );
+      }
+      delete (target as { gate?: unknown }).gate;
+    }
+
+    return gateSelector(getPorts()).attach(target) as Ctx;
+  };
+}

package/src/server/contract-like.ts

@@ -5,4 +5,4 @@ export {
   type ContractLike,
   type ResolveContract,
   resolveContract,
-} from "../contracts";
+} from "../contracts/index.js";

package/src/server/health.ts

@@ -3,8 +3,8 @@
  * Health check handler for Beignet server adapters.
  */
 
-import type { AnyPorts } from "../ports";
-import type { HttpRequestLike, HttpResponseLike } from "./types";
+import type { AnyPorts } from "../ports/index.js";
+import type { HttpRequestLike, HttpResponseLike } from "./types.js";
 
 /**
  * Health check result returned by health handlers.

package/src/server/hooks/auth.ts

@@ -1,205 +1,222 @@
-import {
-  type AuthPort,
-  type AuthSession,
-  AuthUnauthorizedError,
-} from "../../ports";
-import type { HttpRequestLike, HttpResponse, ServerHook } from "../types";
+import type { InferOutput, StandardSchema } from "../../contracts/index.js";
+import { AuthUnauthorizedError } from "../../ports/index.js";
+import type { HttpRequestLike, RouteHook } from "../types.js";
 
 type MaybePromise<T> = T | Promise<T>;
 
 /**
- * Authentication mode for one matched contract.
+ * Arguments passed to auth route-hook callbacks.
  */
-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.
- */
-export type AuthHookArgs<Ctx> = {
+export type AuthHookArgs<
+  Ctx,
+  HeadersSchema extends StandardSchema | undefined = undefined,
+> = {
+  /**
+   * 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;
-  headers: unknown;
+  /**
+   * Hook-owned request headers.
+   *
+   * When the auth hooks declare a `headers` schema, this is that schema's
+   * output parsed from the raw lowercase request header record. Without a
+   * schema it is the raw lowercase header record itself, so auth resolution
+   * never depends on each route's contract header schema.
+   */
+  headers: HeadersSchema extends StandardSchema
+    ? InferOutput<HeadersSchema>
+    : Record<string, string>;
+  /**
+   * 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.
- */
-export type AuthHookUnauthorizedArgs<Ctx, Session> = AuthHookArgs<Ctx> & {
-  session: Session | null;
-};
-
-/**
- * Options for `createAuthHooks(...)`.
+ * Options for route-scoped auth hooks.
+ *
+ * Auth additions must not include `gate`: the server re-attaches the gate
+ * declared by the context blueprint after every hook, so elevated identities
+ * are authorized against the updated context automatically.
  */
-export type AuthHooksOptions<Ctx, Session> = {
+export type AuthHooksOptions<
+  Ctx,
+  AddedCtx extends object & { gate?: never },
+  HeadersSchema extends StandardSchema | undefined = undefined,
+> = {
   /**
-   * 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.
+   * Optional Standard Schema for the credential headers this hook reads.
+   *
+   * The schema is validated against the raw lowercase request header record
+   * before `resolve` runs. On `required()` hooks a schema failure rejects the
+   * request with a framework-owned 401; on `optional()` hooks a schema failure
+   * skips auth resolution; `public()` hooks never parse headers.
    */
-  mode?: (args: AuthHookArgs<Ctx>) => MaybePromise<AuthHookModeInput>;
+  headers?: HeadersSchema;
   /**
-   * 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, HeadersSchema>,
+  ) => MaybePromise<AddedCtx | null>;
+};
+
+/**
+ * Route-scoped auth hook set.
+ */
+export type AuthRouteHooks<Ctx, AddedCtx extends object & { gate?: never }> = {
   /**
-   * 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 rawRequestHeaders(req: HttpRequestLike): Record<string, string> {
+  const record: Record<string, string> = {};
+  req.headers.forEach((value, key) => {
+    record[key.toLowerCase()] = value;
+  });
+  return record;
 }
 
-function defaultMode<Ctx>(args: AuthHookArgs<Ctx>): AuthHookMode {
-  return modeFromInput(args.contract.metadata?.auth as AuthHookModeInput);
-}
+type ParsedAuthHeaders = { ok: true; headers: unknown } | { ok: false };
 
-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.",
-    );
+async function parseAuthHeaders(
+  schema: StandardSchema | undefined,
+  req: HttpRequestLike,
+): Promise<ParsedAuthHeaders> {
+  const raw = rawRequestHeaders(req);
+  if (!schema) {
+    return { ok: true, headers: raw };
   }
 
-  return auth.getSession(args.req);
-}
+  const result = await schema["~standard"].validate(raw);
+  if (result.issues) {
+    return { ok: false };
+  }
 
-function defaultIsAuthenticated<Session>(session: Session | null): boolean {
-  return session !== null;
+  return { ok: true, headers: result.value };
 }
 
 /**
- * Create metadata-driven authentication hooks.
+ * Create route-scoped authentication hooks.
+ *
+ * The outer call binds the app context; the inner call takes auth options and
+ * infers the added context from `resolve`:
+ *
+ * ```ts
+ * const auth = createAuthHooks<AppContext>()({
+ *   resolve: ({ ctx }) => (ctx.auth ? { user: ctx.auth.user } : null),
+ * });
+ * ```
+ *
+ * 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.
  *
- * 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.
+ * Declare a `headers` schema when credentials live in request headers. The
+ * hook validates the raw lowercase header record itself, so `resolve` receives
+ * typed headers without contract casts and a `required()` hook rejects
+ * missing or malformed credentials with a framework-owned 401.
  *
- * @param options - Optional auth mode, session lookup, context assignment, and
- * unauthorized response customization.
- * @returns A server hook that runs before route handlers.
+ * @returns A function that takes auth options and 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,
+export function createAuthHooks<Ctx>() {
+  return <
+    AddedCtx extends object & { gate?: never },
+    HeadersSchema extends StandardSchema | undefined = undefined,
+  >(
+    options: AuthHooksOptions<Ctx, AddedCtx, HeadersSchema>,
+  ): AuthRouteHooks<Ctx, AddedCtx> => {
+    const name = options.name ?? "auth";
+
+    const toAuthArgs = (
+      args: Parameters<RouteHook<Ctx, object>["resolve"]>[0],
+      headers: unknown,
+    ): AuthHookArgs<Ctx, HeadersSchema> =>
+      ({
+        req: args.req,
+        ctx: args.ctx,
+        contract: args.contract,
+        path: args.path,
+        query: args.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 }),
-          };
-        }
-
-        throw new AuthUnauthorizedError();
-      }
-
-      if (!options.assign) {
-        return undefined;
-      }
-
-      return {
-        ctx: await options.assign({ ...args, session }),
-      };
-    },
+        body: args.body,
+      }) as AuthHookArgs<Ctx, HeadersSchema>;
+
+    return {
+      public: () => ({
+        name: `${name}.public`,
+        resolve: () => undefined,
+      }),
+      optional: () => ({
+        name: `${name}.optional`,
+        resolve: async (args) => {
+          const parsed = await parseAuthHeaders(options.headers, args.req);
+          if (!parsed.ok) {
+            return undefined;
+          }
+
+          const additions = await options.resolve(
+            toAuthArgs(args, parsed.headers),
+          );
+
+          return additions ?? undefined;
+        },
+      }),
+      required: () => ({
+        name: `${name}.required`,
+        resolve: async (args) => {
+          const parsed = await parseAuthHeaders(options.headers, args.req);
+          if (!parsed.ok) {
+            throw new AuthUnauthorizedError();
+          }
+
+          const additions = await options.resolve(
+            toAuthArgs(args, parsed.headers),
+          );
+          if (!additions) {
+            throw new AuthUnauthorizedError();
+          }
+
+          return additions;
+        },
+      }),
+    };
   };
 }

package/src/server/hooks/cors.ts

@@ -2,7 +2,7 @@
  * CORS hook utilities for @beignet/core/server
  */
 
-import type { HttpRequestLike, ServerHook } from "../types";
+import type { HttpRequestLike, ServerHook } from "../types.js";
 
 /**
  * CORS configuration for `createCorsHooks(...)`.

package/src/server/hooks/errors.ts

@@ -2,14 +2,17 @@
  * Framework-agnostic error mapping utilities for @beignet/core/server
  */
 
-import { createErrorResponseBody, type ErrorResponseBody } from "../../errors";
-import type { AppEnvironment } from "../health";
-import { getRequestIdFromContext } from "./utils";
+import {
+  createErrorResponseBody,
+  type ErrorResponseBody,
+} from "../../errors/index.js";
+import type { AppEnvironment } from "../health.js";
+import { getRequestIdFromContext } from "./utils.js";
 
 /**
  * Re-export `AppEnvironment` for convenience.
  */
-export type { AppEnvironment } from "../health";
+export type { AppEnvironment } from "../health.js";
 
 /**
  * Framework-neutral response produced by an error mapper.