@ultimat3/http 0.0.1

package/README.md

@@ -0,0 +1,70 @@
+# @ultimat3/http 🌐
+
+A thin, **owned** layer over `Bun.serve`. Not a framework-agnostic HTTP kit — the
+lifecycle belongs to us so ALS context, tracing, locale/tz and authz are impossible
+to skip.
+
+## What it owns
+
+| Concern | Module |
+|---|---|
+| server lifecycle, drain, `/healthz` + `/readyz` | `server.ts` |
+| route table, matcher, `describeRoutes()` | `router.ts` |
+| the ordered request lifecycle | `pipeline.ts` |
+| typed request (params, query, body) | `request.ts` |
+| response constructors + `problem()` | `response.ts` |
+| code → status, `factsOf()` | `error-map.ts` |
+| token-bucket limiting | `rate-limit.ts` |
+| CORS, CSP/HSTS | `cors.ts`, `security-headers.ts` |
+| dev error overlay | `overlay.ts` |
+
+## The pipeline is the guarantee
+
+```
+request-id → trace → context → locale → auth → rate-limit → body → authz
+           → handler → cache-headers → (error-map) → response
+```
+
+Exported as `PIPELINE_STAGES`, each entry carrying a `why`. `pipeline.test.ts`
+asserts the order; `/_x` renders it. Ordering rules worth restating:
+
+| Rule | Reason |
+|---|---|
+| auth before rate-limit | limiter keys per actor/tenant, not per NAT address |
+| rate-limit before body | a limited request never allocates its payload |
+| body before authz | policies take parsed input as their subject |
+| cache-headers before response | a directive can never drop a security header |
+
+## Routing
+
+Precedence is structural, not declaration-ordered: **static > param > wildcard**,
+depth-first with backtracking. A tie is `X_ROUTE_CONFLICT` at startup, never a coin
+flip. `HEAD` falls back to the `GET` route. `meta.auth` is **required** — a route
+cannot forget to declare its auth posture.
+
+```ts
+const handle = createServer({
+  routes: [{ method: 'GET', path: '/posts/:id', meta: { name: 'posts.show', auth: 'public' },
+             handler: (req) => json({ id: req.param('id') }) }],
+  config: defineHttpConfig({ port: 3000 }),
+  role: 'web',
+}).start();
+```
+
+Static paths are registered in Bun's native `routes` table; param/wildcard paths fall
+through to `fetch`. Method resolution stays ours so a 405 still carries problem+json.
+
+## Errors
+
+`X_ROUTE_NOT_FOUND` · `X_METHOD_NOT_ALLOWED` · `X_BODY_INVALID` · `X_UNAUTHENTICATED`
+· `X_FORBIDDEN` · `X_RATE_LIMITED` · `X_BUILD_SKEW` · `X_ROUTE_CONFLICT`
+
+One `factsOf()` feeds three renderings — terminal, `application/problem+json`, dev
+overlay — so the `code`/`cause`/`fix` strings can never diverge.
+
+## Boundaries
+
+Tier 2. Imports `@ultimat3/core` and `@ultimat3/schema` only. Authentication and
+policy evaluation arrive through `ServerHooks`, declared structurally, because
+`@ultimat3/policy` is a sibling tier. There is no plugin API: `Middleware` wraps a
+handler, the pipeline is everything else.

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@ultimat3/http",
+  "version": "0.0.1",
+  "description": "Owned request lifecycle over Bun.serve: router, ordered pipeline, problem+json errors",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/developerz-ai/ultimate.git",
+    "directory": "packages/http"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@ultimat3/core": "^0.0.1",
+    "@ultimat3/schema": "^0.0.1"
+  }
+}

package/src/config.ts

@@ -0,0 +1,89 @@
+// The HTTP slice of `app.config.ts`. One resolver, so a value is either a locked
+// default or an explicit override — never "whatever the first caller passed".
+import { type CorsConfig, DEFAULT_CORS } from './cors';
+import {
+  DEFAULT_LOCALE_CONFIG,
+  DEFAULT_TZ_CONFIG,
+  type LocaleConfig,
+  type TimeZoneConfig,
+} from './locale';
+import { DEFAULT_RATE_LIMIT, type RateLimitConfig } from './rate-limit';
+import { DEFAULT_SECURITY, type SecurityConfig } from './security-headers';
+
+export interface HttpConfig {
+  readonly port: number;
+  readonly hostname: string;
+  /** Mounted prefix, stripped before matching. `'/'` means no prefix. */
+  readonly basePath: string;
+  /** Build id this process serves; `null` disables skew detection (dev). */
+  readonly buildId: string | null;
+  readonly buildIdHeader: string;
+  readonly dev: boolean;
+  /** Read `x-forwarded-for` / `x-forwarded-proto`. Only safe behind our own proxy. */
+  readonly trustProxy: boolean;
+  readonly bodyLimitBytes: number;
+  /** How long SIGTERM waits for in-flight requests before hard-stopping. */
+  readonly drainTimeoutMs: number;
+  readonly locale: LocaleConfig;
+  readonly tz: TimeZoneConfig;
+  readonly cors: CorsConfig;
+  readonly security: SecurityConfig;
+  readonly rateLimit: RateLimitConfig;
+}
+
+export interface HttpConfigInput {
+  readonly port?: number;
+  readonly hostname?: string;
+  readonly basePath?: string;
+  readonly buildId?: string | null;
+  readonly buildIdHeader?: string;
+  readonly dev?: boolean;
+  readonly trustProxy?: boolean;
+  readonly bodyLimitBytes?: number;
+  readonly drainTimeoutMs?: number;
+  readonly locale?: Partial<LocaleConfig>;
+  readonly tz?: Partial<TimeZoneConfig>;
+  readonly cors?: Partial<CorsConfig>;
+  readonly security?: Partial<Omit<SecurityConfig, 'csp'>> & {
+    readonly csp?: Partial<SecurityConfig['csp']>;
+  };
+  readonly rateLimit?: Partial<RateLimitConfig>;
+}
+
+/** `basePath` is stripped before matching so route paths never encode the mount point. */
+export const stripBasePath = (pathname: string, basePath: string): string => {
+  if (basePath === '/' || basePath === '') return pathname;
+  const prefix = basePath.endsWith('/') ? basePath.slice(0, -1) : basePath;
+  if (!pathname.startsWith(prefix)) return pathname;
+  const rest = pathname.slice(prefix.length);
+  return rest.length === 0 ? '/' : rest;
+};
+
+const env = (name: string): string | undefined => {
+  const value = Bun.env[name];
+  return typeof value === 'string' && value.length > 0 ? value : undefined;
+};
+
+export const defineHttpConfig = (input: HttpConfigInput = {}): HttpConfig => {
+  const dev = input.dev ?? env('NODE_ENV') !== 'production';
+  return {
+    port: input.port ?? Number.parseInt(env('PORT') ?? '3000', 10),
+    hostname: input.hostname ?? env('HOSTNAME') ?? '0.0.0.0',
+    basePath: input.basePath ?? '/',
+    buildId: input.buildId ?? env('BUILD_ID') ?? null,
+    buildIdHeader: input.buildIdHeader ?? 'x-ultimate-build',
+    dev,
+    trustProxy: input.trustProxy ?? true,
+    bodyLimitBytes: input.bodyLimitBytes ?? 1_048_576,
+    drainTimeoutMs: input.drainTimeoutMs ?? 15_000,
+    locale: { ...DEFAULT_LOCALE_CONFIG, ...input.locale },
+    tz: { ...DEFAULT_TZ_CONFIG, ...input.tz },
+    cors: { ...DEFAULT_CORS, ...input.cors },
+    security: {
+      ...DEFAULT_SECURITY,
+      ...input.security,
+      csp: { ...DEFAULT_SECURITY.csp, reportOnly: dev, ...input.security?.csp },
+    },
+    rateLimit: { ...DEFAULT_RATE_LIMIT, ...input.rateLimit },
+  };
+};

package/src/context.ts

@@ -0,0 +1,105 @@
+// The per-request context. It is created by the pipeline before any user code runs
+// and published through core's ALS, which is why nothing in the framework has to
+// thread a request object by hand — and why nothing can accidentally skip it.
+import { type Actor, type Ctx, type Role, useContext, uuid } from '@ultimat3/core';
+import type { HttpConfig } from './config';
+import type { AuthzDecision } from './hooks';
+import type { RateLimitDecision } from './rate-limit';
+import type { CacheHint } from './response';
+import type { Route, RouteParams } from './router';
+
+export interface RequestContext {
+  /** `performance.now()` at accept time; used for the server-timing header. */
+  readonly startedAt: number;
+  readonly url: URL;
+  readonly method: string;
+  readonly role: Role;
+  readonly config: HttpConfig;
+  readonly ip: string | null;
+  readonly https: boolean;
+  /** Response headers accumulated by stages before a Response exists. */
+  readonly headers: Headers;
+
+  // Mutable slots, each filled by exactly one pipeline stage. Kept mutable (and
+  // documented) rather than rebuilt per stage so a stage list stays a flat array.
+  /** Set by the `request-id` stage; seeded so a crash before it still correlates. */
+  requestId: string;
+  /** Set by the `trace` stage from an inbound `traceparent`, if any. */
+  traceId: string;
+  parentSpanId: string | null;
+  params: RouteParams;
+  route: Route | undefined;
+  actor: Actor | null;
+  locale: string;
+  tz: string;
+  buildId: string | null;
+  input: unknown;
+  authz: AuthzDecision | undefined;
+  rateLimit: RateLimitDecision | undefined;
+  cache: CacheHint | undefined;
+  response: Response | undefined;
+  error: unknown;
+}
+
+export interface RequestContextInit {
+  readonly url: URL;
+  readonly method: string;
+  readonly role: Role;
+  readonly config: HttpConfig;
+  readonly requestId?: string;
+  readonly traceId?: string;
+  readonly ip?: string | null;
+  readonly https?: boolean;
+}
+
+export const createRequestContext = (init: RequestContextInit): RequestContext => ({
+  requestId: init.requestId ?? uuid(),
+  traceId: init.traceId ?? uuid(),
+  startedAt: performance.now(),
+  url: init.url,
+  method: init.method.toUpperCase(),
+  role: init.role,
+  config: init.config,
+  ip: init.ip ?? null,
+  https: init.https ?? init.url.protocol === 'https:',
+  headers: new Headers(),
+  parentSpanId: null,
+  params: {},
+  route: undefined,
+  actor: null,
+  locale: init.config.locale.default,
+  tz: init.config.tz.default,
+  buildId: null,
+  input: undefined,
+  authz: undefined,
+  rateLimit: undefined,
+  cache: undefined,
+  response: undefined,
+  error: undefined,
+});
+
+/**
+ * `Ctx` is owned by `@ultimat3/core` and grows service handles by module
+ * augmentation. This is the single adapter between the HTTP request context and
+ * core's ALS payload, so a change to `Ctx` touches one line of this package.
+ */
+export const asCtx = (ctx: RequestContext): Ctx => ctx as unknown as Ctx;
+
+/** Read the ambient request context. Throws outside a request via core's ALS. */
+export const useRequestContext = (): RequestContext => useContext() as unknown as RequestContext;
+
+export const elapsedMs = (ctx: RequestContext): number =>
+  Math.round((performance.now() - ctx.startedAt) * 100) / 100;
+
+/**
+ * The fields the HTTP layer reads off an actor. `Actor` is owned by
+ * `@ultimat3/core` and extended by the auth adapter, so this narrow view is the
+ * only place that assumes anything about its shape.
+ */
+export interface ActorView {
+  readonly id: string;
+  readonly orgId?: string | null;
+}
+
+export const actorView = (actor: Actor | null): ActorView | null =>
+  actor === null ? null : (actor as unknown as ActorView);

package/src/cors.ts

@@ -0,0 +1,61 @@
+// CORS with a locked default: same-origin only. Cross-origin access is a decision
+// the app makes in app.config.ts, never something a route can quietly opt into.
+
+export interface CorsConfig {
+  /** Exact origins. `'*'` is allowed only when `credentials` is false. */
+  readonly origins: readonly string[];
+  readonly methods: readonly string[];
+  readonly allowHeaders: readonly string[];
+  readonly exposeHeaders: readonly string[];
+  readonly credentials: boolean;
+  readonly maxAgeSeconds: number;
+}
+
+export const DEFAULT_CORS: CorsConfig = {
+  origins: [],
+  methods: ['GET', 'HEAD', 'POST', 'PUT', 'PATCH', 'DELETE'],
+  allowHeaders: ['content-type', 'authorization', 'x-ultimate-build', 'x-request-id'],
+  exposeHeaders: ['x-request-id', 'x-ultimate-build', 'retry-after'],
+  credentials: true,
+  maxAgeSeconds: 600,
+};
+
+const allowedOrigin = (config: CorsConfig, origin: string | null): string | null => {
+  if (origin === null) return null;
+  if (config.origins.includes('*')) return config.credentials ? null : '*';
+  return config.origins.includes(origin) ? origin : null;
+};
+
+/** Headers to merge into every response, preflight or not. */
+export const corsHeaders = (config: CorsConfig, origin: string | null): Record<string, string> => {
+  const allow = allowedOrigin(config, origin);
+  if (allow === null) return {};
+  const headers: Record<string, string> = {
+    'access-control-allow-origin': allow,
+    // Caches must not serve one origin's response to another.
+    vary: 'origin',
+  };
+  if (config.credentials) headers['access-control-allow-credentials'] = 'true';
+  if (config.exposeHeaders.length > 0) {
+    headers['access-control-expose-headers'] = config.exposeHeaders.join(', ');
+  }
+  return headers;
+};
+
+/**
+ * Answers an OPTIONS preflight. Returns `undefined` when the request is not a
+ * preflight so the caller can fall through to the normal pipeline.
+ */
+export const preflight = (request: Request, config: CorsConfig): Response | undefined => {
+  if (request.method !== 'OPTIONS') return undefined;
+  const requested = request.headers.get('access-control-request-method');
+  if (requested === null) return undefined;
+  const origin = request.headers.get('origin');
+  const allow = allowedOrigin(config, origin);
+  if (allow === null) return new Response(null, { status: 403 });
+  const headers = new Headers(corsHeaders(config, origin));
+  headers.set('access-control-allow-methods', config.methods.join(', '));
+  headers.set('access-control-allow-headers', config.allowHeaders.join(', '));
+  headers.set('access-control-max-age', String(config.maxAgeSeconds));
+  return new Response(null, { status: 204, headers });
+};

package/src/error-map.ts

@@ -0,0 +1,124 @@
+// The one place a framework error code becomes an HTTP status. A table, not a
+// switch chain: adding a code elsewhere in the framework means adding a row here,
+// and a missing row is a loud 500 rather than a silently wrong 200.
+import { HTTP_ERROR_TITLES } from './errors';
+
+/**
+ * code -> status. Codes owned by other packages are listed here on purpose: HTTP
+ * is the only layer that knows what a status means, so no other package should
+ * ever hardcode one.
+ */
+export const ERROR_STATUS: Readonly<Record<string, number>> = {
+  // @ultimat3/http
+  X_ROUTE_NOT_FOUND: 404,
+  X_METHOD_NOT_ALLOWED: 405,
+  X_BODY_INVALID: 422,
+  X_UNAUTHENTICATED: 401,
+  X_FORBIDDEN: 403,
+  X_RATE_LIMITED: 429,
+  X_BUILD_SKEW: 409,
+  X_ROUTE_CONFLICT: 500,
+  X_SERVER_NOT_STARTED: 500,
+  X_PIPELINE_NO_RESPONSE: 500,
+  // @ultimat3/entity
+  X_NOT_FOUND: 404,
+  X_ENTITY_DUPLICATE: 409,
+  X_INVARIANT_VIOLATED: 422,
+  X_TENANCY_UNSCOPED: 500,
+  X_DB_DRIFT: 500,
+  // @ultimat3/policy
+  X_POLICY_MISSING: 500,
+  X_PERMISSION_UNKNOWN: 500,
+  // @ultimat3/core
+  X_NOT_IMPLEMENTED: 501,
+  X_TIMEOUT: 504,
+  X_ABORTED: 499,
+  X_INTERNAL: 500,
+};
+
+export const DEFAULT_STATUS = 500;
+
+export const statusFor = (code: string): number => ERROR_STATUS[code] ?? DEFAULT_STATUS;
+
+/** Everything a renderer (problem+json, overlay, terminal) needs from a throwable. */
+export interface ErrorFacts {
+  readonly code: string;
+  readonly title: string;
+  readonly cause: string;
+  readonly fix: string;
+  readonly docs: string;
+  readonly status: number;
+  /** Present only when the process is in dev mode; never sent to a client in prod. */
+  readonly stack: string | undefined;
+}
+
+const str = (source: Record<string, unknown>, key: string): string | undefined => {
+  const value = source[key];
+  return typeof value === 'string' && value.length > 0 ? value : undefined;
+};
+
+const asRecord = (value: unknown): Record<string, unknown> =>
+  typeof value === 'object' && value !== null ? (value as Record<string, unknown>) : {};
+
+/**
+ * Normalises any throwable into the framework's error contract. Non-Ultimate
+ * throwables still get a code and a fix, because "errors are instructions" has to
+ * hold for the accidental `TypeError` too.
+ */
+export const factsOf = (error: unknown): ErrorFacts => {
+  const record = asRecord(error);
+  const code = str(record, 'code') ?? 'X_INTERNAL';
+  const title =
+    HTTP_ERROR_TITLES[code as keyof typeof HTTP_ERROR_TITLES] ??
+    str(record, 'message') ??
+    'unhandled server error';
+  const cause = str(record, 'cause') ?? str(record, 'message') ?? String(error);
+  return {
+    code,
+    title,
+    cause,
+    fix: str(record, 'fix') ?? 'x logs tail --json   # then fix the throwing call site',
+    docs: str(record, 'docs') ?? `https://ultimate.dev/errors/${code}`,
+    status: statusFor(code),
+    stack: str(record, 'stack'),
+  };
+};
+
+/** RFC-9457 problem document. `code`/`cause`/`fix`/`docs` are our extensions. */
+export interface ProblemDocument {
+  readonly type: string;
+  readonly title: string;
+  readonly status: number;
+  readonly detail: string;
+  readonly instance: string | undefined;
+  readonly code: string;
+  readonly cause: string;
+  readonly fix: string;
+  readonly docs: string;
+  readonly requestId: string | undefined;
+}
+
+export const toProblem = (
+  error: unknown,
+  meta: { instance?: string; requestId?: string } = {},
+): ProblemDocument => {
+  const facts = factsOf(error);
+  return {
+    type: facts.docs,
+    title: facts.title,
+    status: facts.status,
+    detail: facts.cause,
+    instance: meta.instance,
+    code: facts.code,
+    cause: facts.cause,
+    fix: facts.fix,
+    docs: facts.docs,
+    requestId: meta.requestId,
+  };
+};
+
+/** The exact three lines the terminal prints, reused by the overlay and `--json`. */
+export const renderErrorLines = (error: unknown): string => {
+  const facts = factsOf(error);
+  return `${facts.code}: ${facts.title}\n  cause: ${facts.cause}\n  fix:   ${facts.fix}`;
+};

package/src/errors.ts

@@ -0,0 +1,122 @@
+// The HTTP layer's stable error codes. Every throw in this package goes through a
+// factory here so a code, a cause and an exact fix always travel together — the
+// terminal, the dev overlay and `--json` all render the same three strings.
+import { UltimateError } from '@ultimat3/core';
+
+export const HTTP_ERROR_CODES = [
+  'X_ROUTE_NOT_FOUND',
+  'X_METHOD_NOT_ALLOWED',
+  'X_BODY_INVALID',
+  'X_UNAUTHENTICATED',
+  'X_FORBIDDEN',
+  'X_RATE_LIMITED',
+  'X_BUILD_SKEW',
+  'X_ROUTE_CONFLICT',
+  'X_SERVER_NOT_STARTED',
+  'X_PIPELINE_NO_RESPONSE',
+] as const;
+
+export type HttpErrorCode = (typeof HTTP_ERROR_CODES)[number];
+
+/** Human title per code. Kept next to the codes so one edit updates every surface. */
+export const HTTP_ERROR_TITLES: Readonly<Record<HttpErrorCode, string>> = {
+  X_ROUTE_NOT_FOUND: 'no route matches this request',
+  X_METHOD_NOT_ALLOWED: 'route exists but not for this method',
+  X_BODY_INVALID: 'request body failed its schema',
+  X_UNAUTHENTICATED: 'route requires an authenticated actor',
+  X_FORBIDDEN: 'policy denied this actor',
+  X_RATE_LIMITED: 'rate limit exhausted for this key',
+  X_BUILD_SKEW: 'client build id does not match the server build id',
+  X_ROUTE_CONFLICT: 'two routes claim the same path',
+  X_SERVER_NOT_STARTED: 'server handle used before start()',
+  X_PIPELINE_NO_RESPONSE: 'a pipeline stage produced no response',
+};
+
+const docsFor = (code: HttpErrorCode): string => `https://ultimate.dev/errors/${code}`;
+
+/** Base class for every error this package throws. Never throw a bare `Error`. */
+export class HttpError extends UltimateError {
+  constructor(init: { code: HttpErrorCode; cause: string; fix: string }) {
+    super({
+      code: init.code,
+      cause: init.cause,
+      fix: init.fix,
+      docs: docsFor(init.code),
+    });
+    this.name = 'HttpError';
+  }
+}
+
+export const routeNotFound = (method: string, pathname: string): HttpError =>
+  new HttpError({
+    code: 'X_ROUTE_NOT_FOUND',
+    cause: `no route registered for ${method} ${pathname}`,
+    fix: `x routes list --json   # then: x g route ${pathname}`,
+  });
+
+export const methodNotAllowed = (
+  method: string,
+  pathname: string,
+  allow: readonly string[],
+): HttpError =>
+  new HttpError({
+    code: 'X_METHOD_NOT_ALLOWED',
+    cause: `${pathname} accepts ${allow.join(', ')} but the request used ${method}`,
+    fix: `add a ${method} route for ${pathname} or call it with ${allow[0] ?? 'GET'}`,
+  });
+
+export const bodyInvalid = (pathname: string, issues: readonly string[]): HttpError =>
+  new HttpError({
+    code: 'X_BODY_INVALID',
+    cause: `${pathname} body rejected: ${issues.join('; ')}`,
+    fix: `x schema show ${pathname} --json   # then send a body matching the input schema`,
+  });
+
+export const unauthenticated = (pathname: string): HttpError =>
+  new HttpError({
+    code: 'X_UNAUTHENTICATED',
+    cause: `${pathname} declares auth: 'required' and no actor was resolved`,
+    fix: "send a session cookie or Authorization header, or set meta.auth to 'public'",
+  });
+
+export const forbidden = (pathname: string, reason: string): HttpError =>
+  new HttpError({
+    code: 'X_FORBIDDEN',
+    cause: `${pathname} denied: ${reason}`,
+    fix: `x policy explain ${pathname} --json   # shows which clause denied`,
+  });
+
+export const rateLimited = (key: string, retryAfterSeconds: number): HttpError =>
+  new HttpError({
+    code: 'X_RATE_LIMITED',
+    cause: `bucket for ${key} is empty; refills in ${retryAfterSeconds}s`,
+    fix: 'retry after the Retry-After header, or raise rateLimit.buckets in app.config.ts',
+  });
+
+export const buildSkew = (clientBuildId: string, serverBuildId: string): HttpError =>
+  new HttpError({
+    code: 'X_BUILD_SKEW',
+    cause: `client sent build ${clientBuildId}, server is running ${serverBuildId}`,
+    fix: 'reload the page — the service worker will fetch the new build manifest',
+  });
+
+export const serverNotStarted = (member: string): HttpError =>
+  new HttpError({
+    code: 'X_SERVER_NOT_STARTED',
+    cause: `${member} was read before start() bound a socket`,
+    fix: 'call createServer({ ... }).start() before reading url()',
+  });
+
+export const pipelineNoResponse = (stage: string): HttpError =>
+  new HttpError({
+    code: 'X_PIPELINE_NO_RESPONSE',
+    cause: `the pipeline finished at stage "${stage}" without a response`,
+    fix: 'return a Response from the route handler, or a Response from the stage that short-circuits',
+  });
+
+export const routeConflict = (path: string, detail: string): HttpError =>
+  new HttpError({
+    code: 'X_ROUTE_CONFLICT',
+    cause: `${path} conflicts with an already registered route: ${detail}`,
+    fix: `x routes list --json   # remove or rename one of the two routes at ${path}`,
+  });

package/src/hooks.ts

@@ -0,0 +1,32 @@
+// The two seams the HTTP layer cannot own itself: who the actor is (auth lives in
+// `@ultimat3/auth`, tier 3) and whether a policy allows the call (`@ultimat3/policy`
+// is a sibling tier, so it cannot be imported here). Both are declared structurally,
+// which keeps the import boundary intact and keeps the pipeline testable.
+import type { Actor } from '@ultimat3/core';
+import type { RequestContext } from './context';
+import type { UltimateRequest } from './request';
+import type { Route } from './router';
+
+/**
+ * Structurally identical to `PolicyDecision` in `@ultimat3/policy`. Tier 3 passes
+ * that package's `evaluate()` straight through — no adapter, no second authz model.
+ */
+export type AuthzDecision =
+  | { readonly allowed: true }
+  | { readonly allowed: false; readonly reason: string; readonly code?: string };
+
+export interface ServerHooks {
+  /** Resolve the actor from cookies/headers. Returning `null` means anonymous. */
+  readonly authenticate?: (
+    request: UltimateRequest,
+    ctx: RequestContext,
+  ) => Promise<Actor | null> | Actor | null;
+  /** Evaluate `route.meta.policy`. Required for any route that declares one. */
+  readonly authorize?: (
+    route: Route,
+    request: UltimateRequest,
+    ctx: RequestContext,
+  ) => Promise<AuthzDecision> | AuthzDecision;
+  /** Observability sink; the pipeline still maps the error to a response itself. */
+  readonly onError?: (error: unknown, ctx: RequestContext) => void;
+}