@variance-authority/tribunal 0.1.0

package/dist/worker-auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-auth.js","sourceRoot":"","sources":["../src/worker-auth.ts"],"names":[],"mappings":"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","sourcesContent":["import { Forbidden } from './worker-http.js';\n\n/**\n * Which of the two secrets a request presented, whether the deployment has two of\n * them at all, and whether the one presented may do what was asked.\n *\n * Apart from the router because none of it is about routes. Read together it is\n * the whole authentication story — the check that runs before anything is parsed,\n * the comparison that must not leak, the length below which a shared secret is a\n * public one, and the capability rule that runs *after* a route is chosen. The\n * argument for why there are two tokens rather than one lives in\n * [`worker.ts`](./worker.ts), where an operator configuring a deployment meets it\n * first.\n */\n\n/** Which of the two secrets a request presented, or nothing at all. */\nexport type Granted = 'ingest' | 'review';\n\n/** The shortest token this will start with. A short shared secret is a public one. */\nconst MIN_TOKEN = 16;\n\n/**\n * The one sentence a caller holding neither token ever gets.\n *\n * Identical for a missing token, a wrong token, and a path that does not exist.\n * Any variation between those three is an oracle.\n */\nexport const UNAUTHENTICATED = 'a valid bearer token is required';\n\n/**\n * The two secrets, and nothing else this file has any business reading.\n *\n * Structural rather than `TribunalOptions` on purpose: authentication cannot be\n * made to depend on a project name or a retention window by a later edit, because\n * it cannot see them.\n */\ninterface Secrets {\n  readonly ingestToken: string;\n  readonly reviewToken: string;\n}\n\n/**\n * Which token was presented, compared in constant time.\n *\n * Both are hashed to a fixed 32 bytes before comparison and the comparison never\n * exits early. `===` on strings leaks the length of the common prefix through\n * timing; comparing raw strings of different lengths leaks the token's length. A\n * digest makes every comparison the same shape whatever arrives.\n *\n * Both candidates are always checked, even after the first one matches, so that\n * \"which token is this\" costs the same either way.\n */\nexport async function grant(request: Request, secrets: Secrets): Promise<Granted | null> {\n  const header = request.headers.get('authorization');\n  if (header === null) return null;\n\n  const match = /^Bearer (.+)$/i.exec(header.trim());\n  const presented = match?.[1];\n  if (presented === undefined) return null;\n\n  const digest = await fingerprint(presented);\n  const isIngest = equal(digest, await fingerprint(secrets.ingestToken));\n  const isReview = equal(digest, await fingerprint(secrets.reviewToken));\n\n  return isIngest ? 'ingest' : isReview ? 'review' : null;\n}\n\nasync function fingerprint(token: string): Promise<Uint8Array> {\n  return new Uint8Array(await crypto.subtle.digest('SHA-256', new TextEncoder().encode(token)));\n}\n\nfunction equal(left: Uint8Array, right: Uint8Array): boolean {\n  if (left.length !== right.length) return false;\n  let difference = 0;\n  for (let index = 0; index < left.length; index += 1) {\n    difference |= (left[index] ?? 0) ^ (right[index] ?? 0);\n  }\n  return difference === 0;\n}\n\nexport function refuseWeakTokens(secrets: Secrets): void {\n  for (const [name, token] of [\n    ['ingestToken', secrets.ingestToken],\n    ['reviewToken', secrets.reviewToken],\n  ] as const) {\n    if (token.trim().length < MIN_TOKEN) {\n      throw new Error(\n        `\\`${name}\\` is shorter than ${MIN_TOKEN} characters. This deployment holds every ` +\n          'baseline and every observation a project has produced, and it can promote one; a ' +\n          'guessable shared secret in front of that is not a configuration mistake anybody ' +\n          'notices until it matters',\n      );\n    }\n  }\n\n  if (secrets.ingestToken === secrets.reviewToken) {\n    throw new Error(\n      'the ingest token and the review token are the same value, so this deployment has one ' +\n        'secret and not two. The separation is the whole point: the ingest token lives in CI ' +\n        'configuration, and approving promotes a baseline — anything that can read a build log ' +\n        'would be able to approve a regression',\n    );\n  }\n}\n\nexport function requires(granted: Granted, needed: Granted, path: string): void {\n  if (granted === needed) return;\n  throw new Forbidden(\n    `${path} is served to the ${needed} token and this request presented the ${granted} one. ` +\n      (needed === 'review'\n        ? 'Deciding promotes a baseline, so it is not something a build log can do'\n        : 'Writing to this deployment is something CI does, not something a reviewer does'),\n  );\n}\n"]}

package/dist/worker-entry.d.ts

@@ -0,0 +1,58 @@
+import type { D1Like, R2Like } from './bindings.js';
+/**
+ * The deployable Worker: the twenty lines that were missing between a package and
+ * a running service.
+ *
+ * Everything below this file is platform-free by design — `worker.ts` composes
+ * routes over a `D1Like` and an `R2Like` and names no Cloudflare type. That is
+ * why the package is testable without a Workers runtime, and it is also why it
+ * had **no entry point at all**: `createTribunal` returns an object with a
+ * `fetch` method, and a Worker needs a module whose default export has one. The
+ * two are one adapter apart, and until now the adapter did not exist, so the
+ * surface shipped and could not be deployed.
+ *
+ * This file is the only one in the package that reads an environment.
+ *
+ * ## Why the instance is memoised
+ *
+ * `createTribunal` validates the secrets and builds the routing table. An isolate
+ * serves many requests, and rebuilding per request would re-run the token checks
+ * on every call — which is not a correctness problem and is a pointless one. The
+ * cache is keyed on the `env` object identity rather than held unconditionally,
+ * so a different environment cannot be served by an instance built from another.
+ *
+ * ## Why a bad environment answers 500 rather than throwing at import
+ *
+ * A Worker that throws while constructing its module fails deployment-wide with a
+ * platform error the operator has to go and find. Every refusal in this package
+ * is a sentence, and the one an operator most needs — *your token is too short*,
+ * *your two tokens are the same* — is worth more than an exception trace. So the
+ * construction happens inside `fetch` and its message is the body.
+ */
+export interface TribunalEnv {
+    /** D1 binding. Provisioned by `wrangler.jsonc`; the schema is in `migrations/`. */
+    readonly DB: D1Like;
+    /** R2 binding. Holds baseline and candidate bytes; never a row. */
+    readonly BUCKET: R2Like;
+    /** Written into CI. Writes builds, baselines and history. 16 characters or more. */
+    readonly INGEST_TOKEN: string;
+    /** Held by people. Reads the review surface and decides. 16 characters or more. */
+    readonly REVIEW_TOKEN: string;
+    /**
+     * Scopes every row and object.
+     *
+     * A deployment setting today, which is exactly what
+     * [spec 0014](../../../docs/specs/0014-hosted-who-the-caller-is-and-what-the-bill-counts.md)
+     * says has to change before a second tenant exists: the credential should
+     * establish the project, and no route should accept one. Harmless while a
+     * deployment serves one project, and the whole of the problem at two.
+     */
+    readonly PROJECT?: string;
+    /** Days of builds `POST /review/sweep` keeps. Absent means the package default. */
+    readonly RETENTION_DAYS?: string;
+}
+declare const _default: {
+    fetch(request: Request, env: TribunalEnv): Promise<Response>;
+};
+export default _default;
+//# sourceMappingURL=worker-entry.d.ts.map

package/dist/worker-entry.js

@@ -0,0 +1,36 @@
+import { createTribunal } from './worker.js';
+const built = new WeakMap();
+function tribunalFor(env) {
+    const found = built.get(env);
+    if (found !== undefined)
+        return found;
+    const retentionDays = Number(env.RETENTION_DAYS);
+    const made = createTribunal({
+        db: env.DB,
+        bucket: env.BUCKET,
+        project: env.PROJECT ?? 'default',
+        ingestToken: env.INGEST_TOKEN ?? '',
+        reviewToken: env.REVIEW_TOKEN ?? '',
+        // `Number(undefined)` is NaN and `Number('')` is 0, and a retention of zero
+        // days would sweep every build the first time anyone asked. Both fall back.
+        ...(Number.isFinite(retentionDays) && retentionDays > 0 ? { retentionDays } : {}),
+    });
+    built.set(env, made);
+    return made;
+}
+export default {
+    async fetch(request, env) {
+        try {
+            return await tribunalFor(env).fetch(request);
+        }
+        catch (error) {
+            // Only construction failures reach here — `Tribunal.fetch` answers with a
+            // status rather than throwing. The message is the operator's, and it names
+            // the setting rather than the stack.
+            return new Response(JSON.stringify({
+                error: error instanceof Error ? error.message : 'this deployment is misconfigured',
+            }), { status: 500, headers: { 'content-type': 'application/json' } });
+        }
+    },
+};
+//# sourceMappingURL=worker-entry.js.map

package/dist/worker-entry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-entry.js","sourceRoot":"","sources":["../src/worker-entry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAiB,MAAM,aAAa,CAAC;AAyD5D,MAAM,KAAK,GAAG,IAAI,OAAO,EAAoB,CAAC;AAE9C,SAAS,WAAW,CAAC,GAAgB;IACnC,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC7B,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IAEtC,MAAM,aAAa,GAAG,MAAM,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IACjD,MAAM,IAAI,GAAG,cAAc,CAAC;QAC1B,EAAE,EAAE,GAAG,CAAC,EAAE;QACV,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,OAAO,EAAE,GAAG,CAAC,OAAO,IAAI,SAAS;QACjC,WAAW,EAAE,GAAG,CAAC,YAAY,IAAI,EAAE;QACnC,WAAW,EAAE,GAAG,CAAC,YAAY,IAAI,EAAE;QACnC,4EAA4E;QAC5E,4EAA4E;QAC5E,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,aAAa,CAAC,IAAI,aAAa,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAClF,CAAC,CAAC;IAEH,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IACrB,OAAO,IAAI,CAAC;AACd,CAAC;AAED,eAAe;IACb,KAAK,CAAC,KAAK,CAAC,OAAgB,EAAE,GAAgB;QAC5C,IAAI,CAAC;YACH,OAAO,MAAM,WAAW,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QAC/C,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,0EAA0E;YAC1E,2EAA2E;YAC3E,qCAAqC;YACrC,OAAO,IAAI,QAAQ,CACjB,IAAI,CAAC,SAAS,CAAC;gBACb,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,kCAAkC;aACnF,CAAC,EACF,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE,EAAE,CACjE,CAAC;QACJ,CAAC;IACH,CAAC;CACF,CAAC","sourcesContent":["import { createTribunal, type Tribunal } from './worker.js';\nimport type { D1Like, R2Like } from './bindings.js';\n\n/**\n * The deployable Worker: the twenty lines that were missing between a package and\n * a running service.\n *\n * Everything below this file is platform-free by design — `worker.ts` composes\n * routes over a `D1Like` and an `R2Like` and names no Cloudflare type. That is\n * why the package is testable without a Workers runtime, and it is also why it\n * had **no entry point at all**: `createTribunal` returns an object with a\n * `fetch` method, and a Worker needs a module whose default export has one. The\n * two are one adapter apart, and until now the adapter did not exist, so the\n * surface shipped and could not be deployed.\n *\n * This file is the only one in the package that reads an environment.\n *\n * ## Why the instance is memoised\n *\n * `createTribunal` validates the secrets and builds the routing table. An isolate\n * serves many requests, and rebuilding per request would re-run the token checks\n * on every call — which is not a correctness problem and is a pointless one. The\n * cache is keyed on the `env` object identity rather than held unconditionally,\n * so a different environment cannot be served by an instance built from another.\n *\n * ## Why a bad environment answers 500 rather than throwing at import\n *\n * A Worker that throws while constructing its module fails deployment-wide with a\n * platform error the operator has to go and find. Every refusal in this package\n * is a sentence, and the one an operator most needs — *your token is too short*,\n * *your two tokens are the same* — is worth more than an exception trace. So the\n * construction happens inside `fetch` and its message is the body.\n */\n\nexport interface TribunalEnv {\n  /** D1 binding. Provisioned by `wrangler.jsonc`; the schema is in `migrations/`. */\n  readonly DB: D1Like;\n  /** R2 binding. Holds baseline and candidate bytes; never a row. */\n  readonly BUCKET: R2Like;\n  /** Written into CI. Writes builds, baselines and history. 16 characters or more. */\n  readonly INGEST_TOKEN: string;\n  /** Held by people. Reads the review surface and decides. 16 characters or more. */\n  readonly REVIEW_TOKEN: string;\n  /**\n   * Scopes every row and object.\n   *\n   * A deployment setting today, which is exactly what\n   * [spec 0014](../../../docs/specs/0014-hosted-who-the-caller-is-and-what-the-bill-counts.md)\n   * says has to change before a second tenant exists: the credential should\n   * establish the project, and no route should accept one. Harmless while a\n   * deployment serves one project, and the whole of the problem at two.\n   */\n  readonly PROJECT?: string;\n  /** Days of builds `POST /review/sweep` keeps. Absent means the package default. */\n  readonly RETENTION_DAYS?: string;\n}\n\nconst built = new WeakMap<object, Tribunal>();\n\nfunction tribunalFor(env: TribunalEnv): Tribunal {\n  const found = built.get(env);\n  if (found !== undefined) return found;\n\n  const retentionDays = Number(env.RETENTION_DAYS);\n  const made = createTribunal({\n    db: env.DB,\n    bucket: env.BUCKET,\n    project: env.PROJECT ?? 'default',\n    ingestToken: env.INGEST_TOKEN ?? '',\n    reviewToken: env.REVIEW_TOKEN ?? '',\n    // `Number(undefined)` is NaN and `Number('')` is 0, and a retention of zero\n    // days would sweep every build the first time anyone asked. Both fall back.\n    ...(Number.isFinite(retentionDays) && retentionDays > 0 ? { retentionDays } : {}),\n  });\n\n  built.set(env, made);\n  return made;\n}\n\nexport default {\n  async fetch(request: Request, env: TribunalEnv): Promise<Response> {\n    try {\n      return await tribunalFor(env).fetch(request);\n    } catch (error) {\n      // Only construction failures reach here — `Tribunal.fetch` answers with a\n      // status rather than throwing. The message is the operator's, and it names\n      // the setting rather than the stack.\n      return new Response(\n        JSON.stringify({\n          error: error instanceof Error ? error.message : 'this deployment is misconfigured',\n        }),\n        { status: 500, headers: { 'content-type': 'application/json' } },\n      );\n    }\n  },\n};\n"]}

package/dist/worker-http.d.ts

@@ -0,0 +1,39 @@
+/**
+ * What a request is refused with, how one is read, and how an answer is written.
+ *
+ * Apart from the routing so that a route reads as a route. The three classes here
+ * *are* the status codes — [`worker.ts`](./worker.ts) is the only place they
+ * become numbers, and the only place that decides whether a failure was the
+ * caller's or the platform's — and the readers below are the vocabulary every
+ * route validates in.
+ *
+ * Each reader refuses rather than defaults, which is not politeness about input.
+ * Everything this deployment accepts ends up in D1 or R2, and a row that got in
+ * stays in: a field that looked close enough becomes a stored fact that every
+ * later query answers confidently and wrongly.
+ */
+export declare class BadRequest extends Error {
+    readonly name = "BadRequest";
+}
+/** A valid token that is not the one this route wants. Never a 401 and never a 404. */
+export declare class Forbidden extends Error {
+    readonly name = "Forbidden";
+}
+export declare class MethodNotAllowed extends Error {
+    readonly allow: string;
+    readonly name = "MethodNotAllowed";
+    constructor(message: string, allow: string);
+}
+export declare function requireMethod(request: Request, method: string): void;
+export declare function json(status: number, body: unknown, headers?: Record<string, string>): Response;
+export declare function asRecordBody(request: Request): Promise<Readonly<Record<string, unknown>>>;
+export declare function record(value: unknown, what: string): Readonly<Record<string, unknown>>;
+export declare function string(source: Readonly<Record<string, unknown>>, key: string, what: string): string;
+export declare function required(url: URL, name: string): string;
+export declare function optional(url: URL, name: string): string | undefined;
+export declare function count(value: string): number;
+export declare function array(value: unknown, what: string): readonly unknown[];
+export declare function instant(source: Readonly<Record<string, unknown>>, key: string, what: string): string;
+export declare function flag(source: Readonly<Record<string, unknown>>, key: string, what: string): boolean;
+export declare function describe(value: unknown): string;
+//# sourceMappingURL=worker-http.d.ts.map

package/dist/worker-http.js

@@ -0,0 +1,111 @@
+/**
+ * What a request is refused with, how one is read, and how an answer is written.
+ *
+ * Apart from the routing so that a route reads as a route. The three classes here
+ * *are* the status codes — [`worker.ts`](./worker.ts) is the only place they
+ * become numbers, and the only place that decides whether a failure was the
+ * caller's or the platform's — and the readers below are the vocabulary every
+ * route validates in.
+ *
+ * Each reader refuses rather than defaults, which is not politeness about input.
+ * Everything this deployment accepts ends up in D1 or R2, and a row that got in
+ * stays in: a field that looked close enough becomes a stored fact that every
+ * later query answers confidently and wrongly.
+ */
+export class BadRequest extends Error {
+    name = 'BadRequest';
+}
+/** A valid token that is not the one this route wants. Never a 401 and never a 404. */
+export class Forbidden extends Error {
+    name = 'Forbidden';
+}
+export class MethodNotAllowed extends Error {
+    allow;
+    name = 'MethodNotAllowed';
+    constructor(message, allow) {
+        super(message);
+        this.allow = allow;
+    }
+}
+export function requireMethod(request, method) {
+    if (request.method === method)
+        return;
+    throw new MethodNotAllowed(`this path is answered over ${method}, not ${request.method}`, method);
+}
+export function json(status, body, headers = {}) {
+    return new Response(JSON.stringify(body), {
+        status,
+        headers: { 'content-type': 'application/json; charset=utf-8', ...headers },
+    });
+}
+export async function asRecordBody(request) {
+    let parsed;
+    try {
+        parsed = await request.json();
+    }
+    catch (error) {
+        throw new BadRequest(`the request body is not JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return record(parsed, 'the request body');
+}
+export function record(value, what) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new BadRequest(`${what} must be an object; received ${describe(value)}`);
+    }
+    return value;
+}
+export function string(source, key, what) {
+    const value = source[key];
+    if (typeof value !== 'string' || value === '') {
+        throw new BadRequest(`${what}.${key} must be a non-empty string; received ${describe(value)}`);
+    }
+    return value;
+}
+export function required(url, name) {
+    const value = url.searchParams.get(name);
+    if (value === null || value === '') {
+        throw new BadRequest(`\`${name}\` is required on ${url.pathname}`);
+    }
+    return value;
+}
+export function optional(url, name) {
+    const value = url.searchParams.get(name);
+    return value === null || value === '' ? undefined : value;
+}
+export function count(value) {
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed < 0) {
+        throw new BadRequest(`a count must be a whole number of at least 0; received "${value}"`);
+    }
+    return parsed;
+}
+export function array(value, what) {
+    if (!Array.isArray(value)) {
+        throw new BadRequest(`${what} must be an array; received ${describe(value)}`);
+    }
+    return value;
+}
+export function instant(source, key, what) {
+    const value = string(source, key, what);
+    if (Number.isNaN(Date.parse(value))) {
+        throw new BadRequest(`${what}.${key} must be an ISO-8601 instant; received "${value}". A row whose time cannot ` +
+            'be parsed orders a journey wrongly, and a journey read backwards is a confident sentence ' +
+            'that is exactly reversed');
+    }
+    return value;
+}
+export function flag(source, key, what) {
+    const value = source[key];
+    if (typeof value !== 'boolean') {
+        throw new BadRequest(`${what}.${key} must be a boolean; received ${describe(value)}`);
+    }
+    return value;
+}
+export function describe(value) {
+    if (value === undefined)
+        return 'nothing';
+    if (value === null)
+        return 'null';
+    return `${typeof value} (${String(value).slice(0, 60)})`;
+}
+//# sourceMappingURL=worker-http.js.map

package/dist/worker-http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-http.js","sourceRoot":"","sources":["../src/worker-http.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * What a request is refused with, how one is read, and how an answer is written.\n *\n * Apart from the routing so that a route reads as a route. The three classes here\n * *are* the status codes — [`worker.ts`](./worker.ts) is the only place they\n * become numbers, and the only place that decides whether a failure was the\n * caller's or the platform's — and the readers below are the vocabulary every\n * route validates in.\n *\n * Each reader refuses rather than defaults, which is not politeness about input.\n * Everything this deployment accepts ends up in D1 or R2, and a row that got in\n * stays in: a field that looked close enough becomes a stored fact that every\n * later query answers confidently and wrongly.\n */\n\nexport class BadRequest extends Error {\n  override readonly name = 'BadRequest';\n}\n\n/** A valid token that is not the one this route wants. Never a 401 and never a 404. */\nexport class Forbidden extends Error {\n  override readonly name = 'Forbidden';\n}\n\nexport class MethodNotAllowed extends Error {\n  override readonly name = 'MethodNotAllowed';\n  constructor(\n    message: string,\n    readonly allow: string,\n  ) {\n    super(message);\n  }\n}\n\nexport function requireMethod(request: Request, method: string): void {\n  if (request.method === method) return;\n  throw new MethodNotAllowed(\n    `this path is answered over ${method}, not ${request.method}`,\n    method,\n  );\n}\n\nexport function json(status: number, body: unknown, headers: Record<string, string> = {}): Response {\n  return new Response(JSON.stringify(body), {\n    status,\n    headers: { 'content-type': 'application/json; charset=utf-8', ...headers },\n  });\n}\n\nexport async function asRecordBody(request: Request): Promise<Readonly<Record<string, unknown>>> {\n  let parsed: unknown;\n  try {\n    parsed = await request.json();\n  } catch (error) {\n    throw new BadRequest(\n      `the request body is not JSON: ${error instanceof Error ? error.message : String(error)}`,\n    );\n  }\n  return record(parsed, 'the request body');\n}\n\nexport function record(value: unknown, what: string): Readonly<Record<string, unknown>> {\n  if (typeof value !== 'object' || value === null || Array.isArray(value)) {\n    throw new BadRequest(`${what} must be an object; received ${describe(value)}`);\n  }\n  return value as Readonly<Record<string, unknown>>;\n}\n\nexport function string(\n  source: Readonly<Record<string, unknown>>,\n  key: string,\n  what: string,\n): string {\n  const value = source[key];\n  if (typeof value !== 'string' || value === '') {\n    throw new BadRequest(`${what}.${key} must be a non-empty string; received ${describe(value)}`);\n  }\n  return value;\n}\n\nexport function required(url: URL, name: string): string {\n  const value = url.searchParams.get(name);\n  if (value === null || value === '') {\n    throw new BadRequest(`\\`${name}\\` is required on ${url.pathname}`);\n  }\n  return value;\n}\n\nexport function optional(url: URL, name: string): string | undefined {\n  const value = url.searchParams.get(name);\n  return value === null || value === '' ? undefined : value;\n}\n\nexport function count(value: string): number {\n  const parsed = Number(value);\n  if (!Number.isInteger(parsed) || parsed < 0) {\n    throw new BadRequest(`a count must be a whole number of at least 0; received \"${value}\"`);\n  }\n  return parsed;\n}\n\nexport function array(value: unknown, what: string): readonly unknown[] {\n  if (!Array.isArray(value)) {\n    throw new BadRequest(`${what} must be an array; received ${describe(value)}`);\n  }\n  return value as readonly unknown[];\n}\n\nexport function instant(\n  source: Readonly<Record<string, unknown>>,\n  key: string,\n  what: string,\n): string {\n  const value = string(source, key, what);\n  if (Number.isNaN(Date.parse(value))) {\n    throw new BadRequest(\n      `${what}.${key} must be an ISO-8601 instant; received \"${value}\". A row whose time cannot ` +\n        'be parsed orders a journey wrongly, and a journey read backwards is a confident sentence ' +\n        'that is exactly reversed',\n    );\n  }\n  return value;\n}\n\nexport function flag(\n  source: Readonly<Record<string, unknown>>,\n  key: string,\n  what: string,\n): boolean {\n  const value = source[key];\n  if (typeof value !== 'boolean') {\n    throw new BadRequest(`${what}.${key} must be a boolean; received ${describe(value)}`);\n  }\n  return value;\n}\n\nexport function describe(value: unknown): string {\n  if (value === undefined) return 'nothing';\n  if (value === null) return 'null';\n  return `${typeof value} (${String(value).slice(0, 60)})`;\n}\n"]}

package/dist/worker-input.d.ts

@@ -0,0 +1,81 @@
+import { type Approval, type Band, type Instability, type Observation, type RunRecord, type TokenValue, type Window } from '@variance-authority/history';
+import { identityFrom } from '@variance-authority/raster';
+import type { BuildIngest, Decision } from './review-types.js';
+/**
+ * Every request body and query string this deployment accepts, checked before any
+ * of it reaches a store.
+ *
+ * One file because these share a deadline rather than a subject. The baseline
+ * routes, the history routes and the build ingest all write to something that
+ * does not forget, and each function below is the last moment its route can still
+ * refuse — the history record is append-only, a promoted baseline is what the
+ * next run compares against, and a build row outlives the request that made it.
+ * What each one checks differs, and the argument for it sits on the function.
+ *
+ * Reading a *response* is a different job with a different consequence and is not
+ * here: `identityFrom` and `rasterFrom` come from `@variance-authority/raster`
+ * because a misread response becomes a verdict, while everything below becomes a
+ * 4xx nobody mistakes for an answer.
+ */
+export declare function asKey(value: unknown): {
+    readonly subject: string;
+    readonly label?: string;
+};
+export declare function asIdentity(value: unknown): ReturnType<typeof identityFrom> & object;
+export declare function asDecision(value: unknown): Decision;
+/**
+ * A build, checked before any of it is stored.
+ *
+ * The report itself is handed to `review.ingest` as-is rather than rebuilt field
+ * by field, and that is a deliberate asymmetry with the baseline routes. A
+ * misread *response* becomes a verdict; a misread *request* becomes a 4xx nobody
+ * mistakes for an answer. What is checked here is what the store would otherwise
+ * crash on or silently mis-record — the version, and the shape of the wrapper.
+ */
+export declare function asBuildIngest(request: Request): Promise<BuildIngest>;
+/**
+ * The window, validated before it can quietly select nothing.
+ *
+ * An unparseable `since` would reach the query as `NaN`, bind as NULL, match no
+ * row, and answer a churn of zero over zero runs — indistinguishable from a
+ * component that has never changed. A limit of zero is refused for the same
+ * reason: it asks for an answer computed over nothing, dressed as an answer.
+ */
+export declare function windowOf(url: URL): Window;
+/**
+ * A write, validated completely before any of it is appended.
+ *
+ * The history store is append-only, so this is the last moment anything can be
+ * refused. A row with an unknown band or an unparseable instant that gets in
+ * stays in, and every later query over that window either throws or silently
+ * misorders — so the strictness here is not politeness about input, it is the
+ * only place the invariant can still be enforced.
+ */
+export declare function asRecordRequest(request: Request): Promise<{
+    readonly run: RunRecord;
+    readonly observations: readonly Observation[];
+    readonly tokens: readonly TokenValue[];
+    readonly instabilities: readonly Instability[];
+}>;
+/**
+ * An acceptance, and who made it when the surface that recorded it knows.
+ *
+ * The route this parses is how churn learns that anything shipped. Every
+ * observation is written unapproved — a run has not been reviewed at the moment
+ * it writes — so a deployment that could not take approvals answers *this
+ * component has never changed* about a component that changed forty times.
+ */
+export declare function asApprovals(request: Request): Promise<readonly Approval[]>;
+/**
+ * The subject list a run asks about before it writes.
+ *
+ * The only validation here that refuses a request for being *large* rather than
+ * malformed, and the reason is that the answer cannot be trimmed: a `previous`
+ * set with a hole in it is a change that did not happen, appended to a store that
+ * does not forget. So a caller naming more than one request may carry is told the
+ * cap rather than answered with the first {@link MAX_CURRENT_SUBJECTS} and left
+ * looking successful.
+ */
+export declare function asCurrentRequest(request: Request): Promise<readonly string[]>;
+export declare function asBand(value: unknown, what: string): Band;
+//# sourceMappingURL=worker-input.d.ts.map