@beignet/core 0.0.3 → 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,12 +1,16 @@
-import { AuthUnauthorizedError } from "../../ports";
-import type { HttpRequestLike, RouteHook } 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>;
 
 /**
  * Arguments passed to auth route-hook callbacks.
  */
-export type AuthHookArgs<Ctx> = {
+export type AuthHookArgs<
+  Ctx,
+  HeadersSchema extends StandardSchema | undefined = undefined,
+> = {
   /**
    * Framework-neutral request.
    */
@@ -30,9 +34,16 @@ export type AuthHookArgs<Ctx> = {
    */
   query: unknown;
   /**
-   * Parsed request headers.
+   * 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: unknown;
+  headers: HeadersSchema extends StandardSchema
+    ? InferOutput<HeadersSchema>
+    : Record<string, string>;
   /**
    * Parsed request body.
    */
@@ -41,25 +52,44 @@ export type AuthHookArgs<Ctx> = {
 
 /**
  * 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, AddedCtx extends object> = {
+export type AuthHooksOptions<
+  Ctx,
+  AddedCtx extends object & { gate?: never },
+  HeadersSchema extends StandardSchema | undefined = undefined,
+> = {
   /**
    * Hook name prefix used in diagnostics.
    */
   name?: string;
+  /**
+   * 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.
+   */
+  headers?: HeadersSchema;
   /**
    * 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>;
+  resolve: (
+    args: AuthHookArgs<Ctx, HeadersSchema>,
+  ) => MaybePromise<AddedCtx | null>;
 };
 
 /**
  * Route-scoped auth hook set.
  */
-export type AuthRouteHooks<Ctx, AddedCtx extends object> = {
+export type AuthRouteHooks<Ctx, AddedCtx extends object & { gate?: never }> = {
   /**
    * Mark a route as intentionally public.
    */
@@ -74,59 +104,119 @@ export type AuthRouteHooks<Ctx, AddedCtx extends object> = {
   required: () => RouteHook<Ctx, AddedCtx>;
 };
 
-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 rawRequestHeaders(req: HttpRequestLike): Record<string, string> {
+  const record: Record<string, string> = {};
+  req.headers.forEach((value, key) => {
+    record[key.toLowerCase()] = value;
+  });
+  return record;
+}
+
+type ParsedAuthHeaders = { ok: true; headers: unknown } | { ok: false };
+
+async function parseAuthHeaders(
+  schema: StandardSchema | undefined,
+  req: HttpRequestLike,
+): Promise<ParsedAuthHeaders> {
+  const raw = rawRequestHeaders(req);
+  if (!schema) {
+    return { ok: true, headers: raw };
+  }
+
+  const result = await schema["~standard"].validate(raw);
+  if (result.issues) {
+    return { ok: false };
+  }
+
+  return { ok: true, headers: result.value };
 }
 
 /**
  * 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.
  *
- * @param options - Auth resolution callback and optional diagnostic name.
- * @returns Public, optional, and required route-hook factories.
+ * 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.
+ *
+ * @returns A function that takes auth options and 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";
-
-  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();
-        }
-
-        return additions;
-      },
-    }),
+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: 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.