@zmdb/web 1.0.0-beta.1

package/src/contract/index.ts

@@ -0,0 +1,266 @@
+// @zmdb/web/contract — inert HTTP declarations and the serialisable contract IR.
+//
+// This runtime entry deliberately imports only types. The compiler-backed collector
+// lives at ./compiler so an application that only registers an already-compiled
+// contract never reaches TypeScript, the filesystem, or a reflection session.
+
+import { type JsonValue as SchemaJsonValue, type TypeIR } from '@zmdb/schema/ir';
+
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+export type JsonValue = SchemaJsonValue;
+
+/** A controller class recorded by a declaration and instantiated by the application. */
+export type HttpController = abstract new (...args: never[]) => object;
+
+export interface HttpOperationTypes {
+  readonly path?: Readonly<Record<string, unknown>>;
+  readonly query?: Readonly<Record<string, unknown>>;
+  readonly headers?: Readonly<Record<string, unknown>>;
+  readonly cookies?: Readonly<Record<string, unknown>>;
+  readonly body?: unknown;
+  readonly responses: Readonly<
+    Record<number, { readonly body: unknown; readonly headers?: Readonly<Record<string, unknown>> }>
+  >;
+}
+
+type PropertiesAt<
+  Types extends HttpOperationTypes,
+  Location extends 'path' | 'query' | 'headers' | 'cookies',
+> = keyof NonNullable<Types[Location]> & string;
+
+export type HttpParameterDeclaration<Types extends HttpOperationTypes = HttpOperationTypes> =
+  | {
+      readonly in: 'path';
+      readonly property: PropertiesAt<Types, 'path'>;
+      readonly name: string;
+    }
+  | {
+      readonly in: 'query';
+      readonly property: PropertiesAt<Types, 'query'>;
+      readonly name: string;
+    }
+  | {
+      readonly in: 'header';
+      readonly property: PropertiesAt<Types, 'headers'>;
+      readonly name: string;
+    }
+  | {
+      readonly in: 'cookie';
+      readonly property: PropertiesAt<Types, 'cookies'>;
+      readonly name: string;
+    };
+
+export type HttpBodyDeclaration =
+  | { readonly kind: 'json'; readonly mediaType: string }
+  | { readonly kind: 'text' | 'bytes' | 'stream'; readonly mediaType: string }
+  | { readonly kind: 'empty' };
+
+export type HttpRequestBodyDeclaration = Exclude<HttpBodyDeclaration, { readonly kind: 'empty' }> & {
+  readonly required: boolean;
+};
+
+export interface HttpResponseHeaderDeclaration {
+  readonly property: string;
+  readonly name: string;
+  readonly description?: string;
+}
+
+export interface HttpResponseDeclaration {
+  readonly description: string;
+  readonly headers?: readonly HttpResponseHeaderDeclaration[];
+  readonly body: HttpBodyDeclaration;
+  /** Per-version response bodies for media-type versioning. */
+  readonly versions?: Readonly<Record<string, HttpBodyDeclaration>>;
+}
+
+export type HttpVersionDeclaration =
+  | { readonly kind: 'none' }
+  | { readonly kind: 'neutral' }
+  | { readonly kind: 'path'; readonly value: string }
+  | {
+      readonly kind: 'header';
+      readonly name: string;
+      readonly values: readonly string[];
+      readonly default: string;
+    }
+  | {
+      readonly kind: 'media-type';
+      readonly key: string;
+      readonly values: readonly string[];
+      readonly default: string;
+    };
+
+export type SecurityRequirement = Readonly<Record<string, readonly string[]>>;
+
+export interface OAuthFlow {
+  readonly refreshUrl?: string;
+  readonly scopes: Readonly<Record<string, string>>;
+}
+
+export interface ImplicitFlow extends OAuthFlow {
+  readonly authorizationUrl: string;
+}
+
+export interface PasswordFlow extends OAuthFlow {
+  readonly tokenUrl: string;
+}
+
+export interface ClientCredentialsFlow extends OAuthFlow {
+  readonly tokenUrl: string;
+}
+
+export interface AuthorizationCodeFlow extends OAuthFlow {
+  readonly authorizationUrl: string;
+  readonly tokenUrl: string;
+}
+
+interface AllOAuthFlows {
+  readonly implicit?: ImplicitFlow;
+  readonly password?: PasswordFlow;
+  readonly clientCredentials?: ClientCredentialsFlow;
+  readonly authorizationCode?: AuthorizationCodeFlow;
+}
+
+export type OAuthFlows =
+  | (AllOAuthFlows & { readonly implicit: ImplicitFlow })
+  | (AllOAuthFlows & { readonly password: PasswordFlow })
+  | (AllOAuthFlows & { readonly clientCredentials: ClientCredentialsFlow })
+  | (AllOAuthFlows & { readonly authorizationCode: AuthorizationCodeFlow });
+
+export type SecurityScheme =
+  | { readonly type: 'http'; readonly scheme: 'bearer'; readonly bearerFormat?: string; readonly description?: string }
+  | { readonly type: 'http'; readonly scheme: 'basic'; readonly description?: string }
+  | {
+      readonly type: 'apiKey';
+      readonly in: 'header' | 'query' | 'cookie';
+      readonly name: string;
+      readonly description?: string;
+    }
+  | { readonly type: 'mutualTLS'; readonly description?: string }
+  | { readonly type: 'oauth2'; readonly flows: OAuthFlows; readonly description?: string }
+  | { readonly type: 'openIdConnect'; readonly openIdConnectUrl: string; readonly description?: string };
+
+export interface HttpOperationDeclaration<
+  Types extends HttpOperationTypes = HttpOperationTypes,
+  Controller extends HttpController = HttpController,
+  Handler extends string = string,
+> {
+  readonly controller: Controller;
+  readonly handler: Handler;
+  readonly method: HttpMethod;
+  readonly path: string;
+  readonly parameters: readonly HttpParameterDeclaration<Types>[];
+  readonly requestBody?: HttpRequestBodyDeclaration;
+  readonly responses: Readonly<Record<keyof Types['responses'] & number, HttpResponseDeclaration>>;
+  readonly security: readonly SecurityRequirement[];
+  readonly version: HttpVersionDeclaration;
+  readonly deprecated: boolean;
+}
+
+export interface HttpContractDeclaration<
+  Operations extends Readonly<Record<string, HttpOperationDeclaration>> = Readonly<
+    Record<string, HttpOperationDeclaration>
+  >,
+> {
+  readonly operations: Operations;
+  readonly securitySchemes: Readonly<Record<string, SecurityScheme>>;
+}
+
+/**
+ * Record one operation without registering a route or retaining its generic type.
+ *
+ * The generic argument is recovered only by the build-time compiler subpath.
+ */
+export function httpOperation<Types extends HttpOperationTypes>(
+  declaration: HttpOperationDeclaration<Types>,
+): HttpOperationDeclaration<Types> {
+  return Object.freeze(declaration);
+}
+
+/** Define one inert contract module. The object keys are the public operation IDs. */
+export function defineHttpContract<const Operations extends Readonly<Record<string, HttpOperationDeclaration>>>(
+  declaration: HttpContractDeclaration<Operations>,
+): HttpContractDeclaration<Operations> {
+  return Object.freeze({
+    operations: Object.freeze({ ...declaration.operations }),
+    securitySchemes: Object.freeze({ ...declaration.securitySchemes }),
+  });
+}
+
+export interface HttpTypeIR {
+  readonly type: TypeIR;
+  readonly openApi: Readonly<Record<string, JsonValue>>;
+}
+
+export interface HttpContractIR {
+  readonly format: 1;
+  readonly types: Readonly<Record<string, HttpTypeIR>>;
+  readonly operations: readonly HttpOperationIR[];
+  readonly securitySchemes: Readonly<Record<string, SecurityScheme>>;
+}
+
+export interface HttpOperationIR {
+  readonly operationId: string;
+  readonly controller: string;
+  readonly handler: string;
+  readonly method: HttpMethod;
+  readonly path: string;
+  readonly parameters: readonly HttpParameterIR[];
+  readonly requestBody?: HttpRequestBodyIR;
+  readonly responses: readonly HttpResponseIR[];
+  readonly security: readonly SecurityRequirement[];
+  readonly version: HttpVersionIR;
+  readonly deprecated: boolean;
+}
+
+export interface HttpParameterIR {
+  readonly property: string;
+  readonly name: string;
+  readonly in: 'path' | 'query' | 'header' | 'cookie';
+  readonly required: boolean;
+  readonly typeId: string;
+}
+
+export type HttpBodyKind = 'json' | 'text' | 'bytes' | 'stream' | 'empty';
+
+export type HttpBodyIR =
+  | { readonly kind: 'json'; readonly mediaType: string; readonly typeId: string }
+  | { readonly kind: 'text' | 'bytes' | 'stream'; readonly mediaType: string }
+  | { readonly kind: 'empty' };
+
+export type HttpRequestBodyIR = Exclude<HttpBodyIR, { readonly kind: 'empty' }> & {
+  readonly required: boolean;
+};
+
+export interface HttpResponseIR {
+  readonly status: number;
+  readonly description: string;
+  readonly headers: readonly HttpResponseHeaderIR[];
+  readonly body: HttpBodyIR;
+  readonly versions?: Readonly<Record<string, HttpBodyIR>>;
+}
+
+export interface HttpResponseHeaderIR {
+  readonly property: string;
+  readonly name: string;
+  readonly description?: string;
+  readonly required: boolean;
+  readonly typeId: string;
+}
+
+export type HttpVersionIR = HttpVersionDeclaration;
+
+/** Runtime binding kept separate from the serialisable IR. */
+export interface CompiledHttpOperation {
+  readonly operation: HttpOperationIR;
+  readonly controller: HttpController;
+  readonly handler: string;
+}
+
+/** One compilation result shared by runtime routing and later artifact emitters. */
+export interface CompiledHttpContract {
+  readonly ir: HttpContractIR;
+  readonly operations: readonly CompiledHttpOperation[];
+  /** Project-source inputs whose changes can alter this compilation. */
+  readonly dependencies: readonly string[];
+}

package/src/csrf/index.ts

@@ -0,0 +1,264 @@
+// @zmdb/web — session-bound CSRF tokens (epic #564, spec ./SPEC.md).
+//
+// The application supplies the session lookup, allowed browser origins and
+// signing secret. Tokens are stateless: this module keeps no session or token
+// store, and two instances using the same secret can verify each other's tokens.
+
+import { ChainError, type AnyCtx, type Guard } from '../middleware/index.js';
+
+export interface CsrfOptions {
+  readonly secret: Uint8Array<ArrayBuffer>;
+  readonly sessionOf: (ctx: AnyCtx) => string | undefined;
+  readonly allowedOrigins: readonly string[];
+  readonly headerName?: string;
+}
+
+export interface Csrf {
+  issue(ctx: AnyCtx): Promise<string>;
+  verify(ctx: AnyCtx): Promise<void>;
+  guard(): Guard;
+}
+
+const SAFE_METHODS = new Set(['GET', 'HEAD', 'OPTIONS', 'TRACE']);
+const DEFAULT_HEADER = 'x-csrf-token';
+const FORBIDDEN = 'forbidden';
+const HMAC = { name: 'HMAC', hash: 'SHA-256' } as const;
+const NONCE_BYTES = 16;
+const MAC_BYTES = 32;
+const MASK_BYTES = 16;
+const NONCE_TEXT_LENGTH = 22;
+const MAC_TEXT_LENGTH = 43;
+const TOKEN_TEXT_LENGTH = NONCE_TEXT_LENGTH + 1 + MAC_TEXT_LENGTH;
+const MASK_TEXT_LENGTH = 22;
+const MASKED_TEXT_LENGTH = 88;
+const BASE64URL = /^[A-Za-z0-9_-]+$/;
+const HEADER_NAME = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+const encoder = new TextEncoder();
+const decoder = new TextDecoder('utf-8', { fatal: true });
+
+function randomBytes(length: number): Uint8Array<ArrayBuffer> {
+  return globalThis.crypto.getRandomValues(new Uint8Array(length));
+}
+
+async function importHmacKey(secret: Uint8Array<ArrayBuffer>): Promise<CryptoKey> {
+  return globalThis.crypto.subtle.importKey('raw', secret, HMAC, false, ['sign']);
+}
+
+async function sign(key: CryptoKey, value: Uint8Array<ArrayBuffer>): Promise<Uint8Array<ArrayBuffer>> {
+  return new Uint8Array(await globalThis.crypto.subtle.sign('HMAC', key, value));
+}
+
+function encodeBase64Url(value: Uint8Array<ArrayBuffer>): string {
+  return value.toBase64({ alphabet: 'base64url', omitPadding: true });
+}
+
+function decodeBase64Url(value: string): Uint8Array<ArrayBuffer> | undefined {
+  if (value.length === 0 || !BASE64URL.test(value)) {
+    return undefined;
+  }
+  try {
+    const decoded = Uint8Array.fromBase64(value, { alphabet: 'base64url' });
+    return encodeBase64Url(decoded) === value ? decoded : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function xorMask(value: Uint8Array<ArrayBuffer>, mask: Uint8Array<ArrayBuffer>): Uint8Array<ArrayBuffer> {
+  const result = new Uint8Array(value.length);
+  for (let index = 0; index < value.length; index += 1) {
+    result[index] = (value[index] ?? 0) ^ (mask[index % mask.length] ?? 0);
+  }
+  return result;
+}
+
+function normaliseOrigins(origins: readonly string[]): ReadonlySet<string> {
+  if (!Array.isArray(origins) || origins.length === 0) {
+    throw new TypeError('allowedOrigins must contain at least one explicit HTTP(S) origin');
+  }
+  const normalised = new Set<string>();
+  for (const candidate of origins) {
+    if (typeof candidate !== 'string' || candidate.includes('*')) {
+      throw new TypeError('allowedOrigins must contain explicit HTTP(S) origins');
+    }
+    let url: URL;
+    try {
+      url = new URL(candidate);
+    } catch {
+      throw new TypeError('allowedOrigins must contain valid absolute URLs');
+    }
+    if (
+      (url.protocol !== 'http:' && url.protocol !== 'https:') ||
+      url.origin === 'null' ||
+      url.username !== '' ||
+      url.password !== '' ||
+      (url.pathname !== '' && url.pathname !== '/') ||
+      url.search !== '' ||
+      url.hash !== ''
+    ) {
+      throw new TypeError('allowedOrigins entries must be origins, not URL patterns or paths');
+    }
+    normalised.add(url.origin);
+  }
+  return normalised;
+}
+
+function normaliseHeaderName(name: string | undefined): string {
+  const normalised = name ?? DEFAULT_HEADER;
+  if (normalised.length === 0 || !HEADER_NAME.test(normalised)) {
+    throw new TypeError('headerName must be a valid HTTP field name');
+  }
+  return normalised.toLowerCase();
+}
+
+function header(headers: Readonly<Record<string, string>>, wanted: string): string | undefined {
+  const direct = headers[wanted];
+  if (direct !== undefined) {
+    return direct;
+  }
+  for (const name of Object.keys(headers)) {
+    if (name.toLowerCase() === wanted) {
+      return headers[name];
+    }
+  }
+  return undefined;
+}
+
+function requestOrigin(ctx: AnyCtx): string | undefined {
+  const candidate = header(ctx.headers, 'origin') ?? header(ctx.headers, 'referer');
+  if (candidate === undefined) {
+    return undefined;
+  }
+  try {
+    const parsed = new URL(candidate);
+    return parsed.origin === 'null' ? undefined : parsed.origin;
+  } catch {
+    return undefined;
+  }
+}
+
+function sessionFor(ctx: AnyCtx, sessionOf: CsrfOptions['sessionOf']): string {
+  const session = sessionOf(ctx);
+  if (session === undefined) {
+    throw new Error('CSRF protection requires a cookie-backed session');
+  }
+  return session;
+}
+
+function rejectRequest(): never {
+  throw new ChainError(403, FORBIDDEN);
+}
+
+async function equalAfterMac(
+  key: CryptoKey,
+  expected: Uint8Array<ArrayBuffer>,
+  provided: Uint8Array<ArrayBuffer>,
+): Promise<boolean> {
+  const [expectedDigest, providedDigest] = await Promise.all([sign(key, expected), sign(key, provided)]);
+  return encodeBase64Url(expectedDigest) === encodeBase64Url(providedDigest);
+}
+
+interface ParsedToken {
+  readonly nonce: string;
+  readonly mac: Uint8Array<ArrayBuffer>;
+}
+
+function parseToken(token: string): ParsedToken | undefined {
+  const segments = token.split('.');
+  if (segments.length !== 2 || segments[0]?.length !== MASK_TEXT_LENGTH || segments[1]?.length !== MASKED_TEXT_LENGTH) {
+    return undefined;
+  }
+  const mask = decodeBase64Url(segments[0]);
+  const masked = decodeBase64Url(segments[1]);
+  if (mask?.byteLength !== MASK_BYTES || masked?.byteLength !== TOKEN_TEXT_LENGTH) {
+    return undefined;
+  }
+
+  let raw: string;
+  try {
+    raw = decoder.decode(xorMask(masked, mask));
+  } catch {
+    return undefined;
+  }
+  const tokenParts = raw.split('.');
+  if (
+    tokenParts.length !== 2 ||
+    tokenParts[0]?.length !== NONCE_TEXT_LENGTH ||
+    tokenParts[1]?.length !== MAC_TEXT_LENGTH
+  ) {
+    return undefined;
+  }
+  const nonceBytes = decodeBase64Url(tokenParts[0]);
+  const mac = decodeBase64Url(tokenParts[1]);
+  if (nonceBytes?.byteLength !== NONCE_BYTES || mac?.byteLength !== MAC_BYTES) {
+    return undefined;
+  }
+  return { nonce: tokenParts[0], mac };
+}
+
+/** Create stateless CSRF protection for a cookie-authenticated application. */
+export async function createCsrf(options: CsrfOptions): Promise<Csrf> {
+  if (typeof options !== 'object' || options === null) {
+    throw new TypeError('CSRF options are required');
+  }
+  if (!(options.secret instanceof Uint8Array) || options.secret.byteLength === 0) {
+    throw new TypeError('secret must be a non-empty Uint8Array');
+  }
+  if (typeof options.sessionOf !== 'function') {
+    throw new TypeError('sessionOf is required');
+  }
+
+  const allowedOrigins = normaliseOrigins(options.allowedOrigins);
+  const headerName = normaliseHeaderName(options.headerName);
+  const sessionOf = options.sessionOf;
+  const signingKey = await importHmacKey(options.secret.slice());
+  const comparisonKey = await importHmacKey(randomBytes(MAC_BYTES));
+
+  const issue = async (ctx: AnyCtx): Promise<string> => {
+    const session = sessionFor(ctx, sessionOf);
+    const nonce = encodeBase64Url(randomBytes(NONCE_BYTES));
+    const mac = await sign(signingKey, encoder.encode(`${session}.${nonce}`));
+    const raw = encoder.encode(`${nonce}.${encodeBase64Url(mac)}`);
+    const mask = randomBytes(MASK_BYTES);
+    return `${encodeBase64Url(mask)}.${encodeBase64Url(xorMask(raw, mask))}`;
+  };
+
+  const verify = async (ctx: AnyCtx): Promise<void> => {
+    const session = sessionFor(ctx, sessionOf);
+    if (SAFE_METHODS.has(ctx.method)) {
+      return;
+    }
+
+    const origin = requestOrigin(ctx);
+    if (origin === undefined || !allowedOrigins.has(origin)) {
+      rejectRequest();
+    }
+
+    const supplied = header(ctx.headers, headerName);
+    const parsed = supplied === undefined ? undefined : parseToken(supplied);
+    if (parsed === undefined) {
+      rejectRequest();
+    }
+
+    const expected = await sign(signingKey, encoder.encode(`${session}.${parsed.nonce}`));
+    if (!(await equalAfterMac(comparisonKey, expected, parsed.mac))) {
+      rejectRequest();
+    }
+  };
+
+  const guard = (): Guard => ({
+    async canActivate(ctx: AnyCtx): Promise<boolean> {
+      try {
+        await verify(ctx);
+        return true;
+      } catch (error) {
+        if (error instanceof ChainError && error.status === 403) {
+          return false;
+        }
+        throw error;
+      }
+    },
+  });
+
+  return Object.freeze({ issue, verify, guard });
+}

package/src/data/index.ts

@@ -0,0 +1,65 @@
+// @zmdb/web — HTTP data-boundary adapters (epic #277, spec ./SPEC.md).
+// Repository injection is app-owned; this module converts wire values and
+// adapts validators for the request pipeline.
+//
+// "No runtime parser" still holds with `wireDecoder` here: it converts the two column
+// types JSON cannot carry (a `timestamp`, a `bigint`) into the values the app layer holds,
+// and it accepts and rejects nothing. Validation remains the consumer's AOT `assert`.
+
+import { type CoreSchema } from '@zmdb/schema';
+import { decodeWire, encodeWire, type CodecRegistry, type Variant } from '@zmdb/schema/ir';
+
+/**
+ * Adapt a validator into a pipeline `validateBody` hook. Pass any function that
+ * returns the validated value or throws — e.g. `@zmdb/validator`'s
+ * `assert<CreateDTO<T>>`. The framework embeds no parser of its own.
+ */
+export function validateWith<T>(validator: (raw: unknown) => T): (raw: unknown) => T {
+  return validator;
+}
+
+/** A JSON object body — not an array, which is a valid JSON document and not a payload. */
+function isBody(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/**
+ * The wire→app decode, at the boundary and nowhere else (plan D3).
+ *
+ * A column has three types, and two of them meet here: JSON carries a `timestamp` as an
+ * ISO-8601 string and a `bigint` as a decimal one, while a handler, a `CreateDTO<T>` and
+ * the repository all hold a `Date` and a `bigint`. Something has to convert, and if it is
+ * not one function at the edge then it is every handler, differently — which is the state
+ * in which nobody noticed that the repository accepted both and the DDL was wrong.
+ *
+ * Put it *before* validation in the chain: it decodes, the validator then checks the app
+ * type. It converts and never rejects — a string that is not a date survives as a string,
+ * so the validator reports it rather than the handler receiving `Invalid Date`.
+ *
+ * ```ts
+ * dtoChain({ decode: wireDecoder(OrderSchema, 'create'), validate: assert<CreateDTO<Order>> })
+ * ```
+ */
+export function wireDecoder(
+  schema: CoreSchema<string>,
+  variant: Variant = 'create',
+  codecs: CodecRegistry = {},
+): (raw: unknown) => unknown {
+  const ir = schema.ir;
+  return (raw: unknown) => (isBody(raw) ? decodeWire(ir, variant, raw, codecs) : raw);
+}
+
+/**
+ * The app→wire encode, for a response: the same crossing in the other direction.
+ *
+ * A `Date` does not survive `JSON.stringify` as anything the published document describes
+ * — it becomes an ISO string, which happens to be right — and a `bigint` does not survive
+ * it at all (`TypeError`). Both are the wire type of a column, so both come from here.
+ */
+export function wireEncoder(schema: CoreSchema<string>, codecs: CodecRegistry = {}): (result: unknown) => unknown {
+  const ir = schema.ir;
+  return (result: unknown) => {
+    if (Array.isArray(result)) return result.map(row => (isBody(row) ? encodeWire(ir, row, codecs) : row));
+    return isBody(result) ? encodeWire(ir, result, codecs) : result;
+  };
+}