@variance-authority/tribunal 0.1.0

package/dist/node/bin.js

@@ -0,0 +1,337 @@
+#!/usr/bin/env node
+import { realpathSync } from 'node:fs';
+import { userInfo } from 'node:os';
+import { resolve } from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+import { createDirectoryBucket } from './bucket.js';
+import { openDatabase } from './database.js';
+import { serveTribunal } from './serve.js';
+import { createTribunal } from '../worker.js';
+/**
+ * `variance-authority-tribunal` — the thing the operator runs.
+ *
+ * A process, a port, a file, a directory and two tokens. The same review
+ * service a Cloudflare deployment serves, with SQLite where D1 was and a
+ * directory where R2 was; every route, every refusal and every status code is
+ * the same code.
+ *
+ * Configuration is environment variables rather than flags, matching
+ * [`server`](../../../server/src/bin.ts) — a service is started by a supervisor,
+ * a unit file or a container, and all three pass an environment.
+ *
+ * ## The three things this refuses
+ *
+ * **No tokens, no service.** Inherited from `createTribunal` rather than
+ * re-implemented: two bearer tokens, sixteen characters each, and not the same
+ * string. The refusal is the constructor's and it is quoted straight to stderr.
+ *
+ * **A project, named.** There is no default. An invented one puts two
+ * repositories' baselines in one namespace and the first symptom is a mass
+ * `changed` — the argument is the package's, and `worker-entry` only falls back
+ * to `default` because a Worker environment has nobody to ask. A person typing a
+ * command does.
+ *
+ * **Loopback unless somebody typed otherwise.** Exposure is a decision, not an
+ * accident of a bind address. And on a non-loopback bind the **review surface is
+ * not served at all** — see {@link authorizeFor}, which is the one piece of
+ * policy this file owns.
+ */
+export const PORT_VARIABLE = 'VARIANCE_TRIBUNAL_PORT';
+export const HOST_VARIABLE = 'VARIANCE_TRIBUNAL_HOST';
+export const DATABASE_VARIABLE = 'VARIANCE_TRIBUNAL_DB';
+export const STORAGE_VARIABLE = 'VARIANCE_TRIBUNAL_STORAGE';
+export const PROJECT_VARIABLE = 'VARIANCE_TRIBUNAL_PROJECT';
+export const INGEST_TOKEN_VARIABLE = 'VARIANCE_TRIBUNAL_INGEST_TOKEN';
+export const REVIEW_TOKEN_VARIABLE = 'VARIANCE_TRIBUNAL_REVIEW_TOKEN';
+export const RETENTION_VARIABLE = 'VARIANCE_TRIBUNAL_RETENTION_DAYS';
+export const REVIEWER_VARIABLE = 'VARIANCE_TRIBUNAL_REVIEWER';
+export const TRUST_NETWORK_VARIABLE = 'VARIANCE_TRIBUNAL_TRUST_NETWORK';
+const DEFAULT_PORT = 7789;
+const DEFAULT_HOST = '127.0.0.1';
+const DEFAULT_DATABASE = 'variance-tribunal.db';
+const DEFAULT_STORAGE = 'variance-tribunal-objects';
+/** Addresses that can only be reached from the machine the process is on. */
+const LOOPBACK = new Set(['127.0.0.1', 'localhost', '::1']);
+/**
+ * Read the configuration, or explain exactly which variable is wrong.
+ *
+ * Pure and exported, so every refusal below is testable without binding a port.
+ * A rule that can only be exercised by starting a process is a rule that gets
+ * tested once, by hand, before it is weakened.
+ */
+export function readConfig(env) {
+    const project = (env[PROJECT_VARIABLE] ?? '').trim();
+    if (project === '') {
+        throw new Error(`${PROJECT_VARIABLE} is not set. It scopes every row and every object key, so one ` +
+            'deployment can serve several repositories without their `story:card` colliding. There ' +
+            'is no default on purpose: an invented one puts two projects\' baselines in one ' +
+            'namespace, and the first symptom is every subject reporting `changed` at once.');
+    }
+    const host = orDefault(env[HOST_VARIABLE], DEFAULT_HOST);
+    const loopback = LOOPBACK.has(host);
+    if (!loopback && orDefault(env[TRUST_NETWORK_VARIABLE], '') === '') {
+        throw new Error(`${HOST_VARIABLE} is "${host}", which is reachable from outside this machine, and ` +
+            `${TRUST_NETWORK_VARIABLE} is not set. This service has bearer tokens and no accounts, ` +
+            'no TLS and no rate limit, so a network bind is a decision somebody should have typed. ' +
+            `Set ${TRUST_NETWORK_VARIABLE}=1 to confirm it — and read what it costs: the review ` +
+            'surface is not served on a network bind, because there would be nothing between it and ' +
+            'an approve button on the internet. Put the Next.js adapter behind your own sign-in ' +
+            'instead, or leave this on loopback behind a reverse proxy that authenticates.');
+    }
+    const rawPort = env[PORT_VARIABLE];
+    const port = rawPort === undefined || rawPort === '' ? DEFAULT_PORT : Number(rawPort);
+    if (!Number.isInteger(port) || port < 0 || port > 65_535) {
+        throw new Error(`${PORT_VARIABLE} must be a whole number between 0 and 65535; received "${rawPort ?? ''}"`);
+    }
+    const rawRetention = env[RETENTION_VARIABLE];
+    const retentionDays = rawRetention === undefined || rawRetention === '' ? undefined : Number(rawRetention);
+    if (retentionDays !== undefined && (!Number.isFinite(retentionDays) || retentionDays <= 0)) {
+        throw new Error(`${RETENTION_VARIABLE} must be a positive number of days; received "${rawRetention ?? ''}". ` +
+            'Leave it unset for the package default rather than passing zero, which would sweep ' +
+            'every build the first time anyone asked.');
+    }
+    return {
+        port,
+        host,
+        loopback,
+        database: resolve(orDefault(env[DATABASE_VARIABLE], DEFAULT_DATABASE)),
+        storage: resolve(orDefault(env[STORAGE_VARIABLE], DEFAULT_STORAGE)),
+        project,
+        // Passed through unvalidated: `createTribunal` refuses a short token and two
+        // identical ones, and a second copy of that rule here is a second place for
+        // it to be relaxed.
+        ingestToken: env[INGEST_TOKEN_VARIABLE] ?? '',
+        reviewToken: env[REVIEW_TOKEN_VARIABLE] ?? '',
+        ...(retentionDays === undefined ? {} : { retentionDays }),
+        reviewer: orDefault(env[REVIEWER_VARIABLE], defaultReviewer()),
+    };
+}
+/**
+ * The one piece of policy this file owns: who is allowed what.
+ *
+ * `createTribunalRoutes` requires an `authorize` and gives it no default, on the
+ * grounds that returning `'review'` for every request would publish an approve
+ * button. This is a host writing that function in its own file, where the next
+ * person can read it — which is exactly what that refusal asks for.
+ *
+ * Three rules, in order:
+ *
+ * 1. **A caller holding a token gets what the token is for.** CI posts with the
+ *    ingest token from wherever CI runs. The mount replaces the header before the
+ *    Worker sees it, so this is the only place the caller's own bearer is read.
+ * 2. **On a loopback bind, a caller with no token reviews.** The socket is the
+ *    gate: only this machine can reach it, and the person at this machine is the
+ *    reviewer. This is what lets the served page work with no credential in it.
+ * 3. **On a network bind, no token is no capability** — and the surface is not
+ *    served at all, so there is no page to be tricked into carrying one.
+ */
+export function authorizeFor(config) {
+    return (request) => {
+        const bearer = bearerOf(request);
+        if (bearer !== null) {
+            if (bearer === config.ingestToken)
+                return 'ingest';
+            if (bearer === config.reviewToken)
+                return 'review';
+            return null;
+        }
+        return config.loopback ? 'review' : null;
+    };
+}
+function bearerOf(request) {
+    const header = request.headers.get('authorization');
+    if (header === null)
+        return null;
+    const match = /^Bearer\s+(.+)$/i.exec(header.trim());
+    return match === null ? null : match[1];
+}
+/**
+ * Open the file, make the directory, bind the port, and say what was done.
+ *
+ * The startup line names the absolute database path, the absolute object
+ * directory, the project, the schema version and the bind address, and names
+ * neither token. Everything an operator needs to confirm they configured the
+ * right thing, and nothing that turns a shipped log into a credential.
+ */
+export async function start(env, write = (line) => process.stdout.write(line)) {
+    const config = readConfig(env);
+    const database = await openDatabase(config.database);
+    let service;
+    try {
+        const tribunal = createTribunal({
+            db: database,
+            bucket: createDirectoryBucket(config.storage),
+            project: config.project,
+            ingestToken: config.ingestToken,
+            reviewToken: config.reviewToken,
+            ...(config.retentionDays === undefined ? {} : { retentionDays: config.retentionDays }),
+        });
+        service = await serveTribunal({
+            tribunal,
+            host: config.host,
+            port: config.port,
+            authorize: authorizeFor(config),
+            tokens: { ingest: config.ingestToken, review: config.reviewToken },
+            ui: config.loopback,
+            reviewer: config.reviewer,
+        });
+    }
+    catch (error) {
+        // A refused token or a taken port leaves the database open otherwise, holding
+        // its lock against the process the operator is about to start instead.
+        database.close();
+        throw error;
+    }
+    write(`variance-authority tribunal listening on ${service.url}\n` +
+        `  project:  ${config.project}\n` +
+        `  database: ${config.database} (schema version ${database.version})\n` +
+        `  objects:  ${config.storage}\n` +
+        `  review:   ${config.loopback
+            ? `served at ${service.url} — this bind is reachable only from this machine`
+            : `not served: ${HOST_VARIABLE} is a network address. The JSON API is up and wants a bearer token`}\n` +
+        `  auth:     bearer tokens from ${INGEST_TOKEN_VARIABLE} and ${REVIEW_TOKEN_VARIABLE}\n`);
+    return {
+        ...service,
+        database,
+        async close() {
+            await service.close();
+            database.close();
+        },
+    };
+}
+function orDefault(value, fallback) {
+    return value === undefined || value.trim() === '' ? fallback : value.trim();
+}
+/**
+ * Who a decision is recorded as when nobody said.
+ *
+ * There are no accounts here — a decision carries a name, and the name should be
+ * a person rather than the word "reviewer". The OS knows one; `userInfo` throws
+ * on a host with no passwd entry, which some containers are.
+ */
+function defaultReviewer() {
+    try {
+        return userInfo().username;
+    }
+    catch {
+        return 'reviewer';
+    }
+}
+/**
+ * A flag is not a way to configure this, and saying so is the whole point.
+ *
+ * `process.argv` was read by nothing here, which is defensible — configuration
+ * is an environment, for the reason on the module — and silently accepting the
+ * arguments of the configuration this *is not* is not. `--database ./x.db` on a
+ * process that only reads {@link DATABASE_VARIABLE} starts a service against a
+ * fresh empty file in the working directory, reports success, and prints a
+ * startup line that reads as confirmation because it is honestly reporting what
+ * the process did. The operator's next move is to ask why their builds are
+ * gone.
+ *
+ * So: refuse, and name the variable the flag was reaching for. Returning the
+ * usage text rather than writing it keeps this pure — the refusals above are
+ * testable without binding a port and this one is no different.
+ */
+export function readArguments(argv) {
+    if (argv.length === 0)
+        return null;
+    if (argv.includes('--help') || argv.includes('-h'))
+        return USAGE;
+    const given = argv[0];
+    const flag = given.split('=')[0];
+    const variable = AS_VARIABLE[flag];
+    throw new Error(variable === undefined
+        ? `this service takes no arguments and received \`${given}\`. It is configured by ` +
+            `environment, because a service is started by a supervisor, a unit file or a ` +
+            `container, and all three pass one.\n\n${USAGE}`
+        : `\`${flag}\` is ${variable}, and this service is configured by environment rather ` +
+            `than by flags. Accepting the flag and ignoring it would start the service against ` +
+            `the default instead — for ${DATABASE_VARIABLE}, an empty database in the working ` +
+            `directory, reported as a successful start.\n\n${USAGE}`);
+}
+/** The flags somebody reaches for, and what each one actually is. */
+const AS_VARIABLE = {
+    '--db': DATABASE_VARIABLE,
+    '--database': DATABASE_VARIABLE,
+    '--objects': STORAGE_VARIABLE,
+    '--storage': STORAGE_VARIABLE,
+    '--port': PORT_VARIABLE,
+    '--host': HOST_VARIABLE,
+    '--project': PROJECT_VARIABLE,
+    '--retention': RETENTION_VARIABLE,
+    '--reviewer': REVIEWER_VARIABLE,
+};
+/** Every variable, in the order somebody sets them. */
+const VARIABLES = [
+    [PROJECT_VARIABLE, 'required — scopes every row and every object key'],
+    [INGEST_TOKEN_VARIABLE, 'required — what CI pushes with'],
+    [REVIEW_TOKEN_VARIABLE, 'required — what a person decides with'],
+    [DATABASE_VARIABLE, `the SQLite file (default ${DEFAULT_DATABASE})`],
+    [STORAGE_VARIABLE, `where images are kept (default ${DEFAULT_STORAGE})`],
+    [PORT_VARIABLE, `default ${DEFAULT_PORT}`],
+    [HOST_VARIABLE, `default ${DEFAULT_HOST}; a network bind serves no review page`],
+    [TRUST_NETWORK_VARIABLE, 'confirms a network bind was meant'],
+    [RETENTION_VARIABLE, 'days after which a build is swept'],
+    [REVIEWER_VARIABLE, 'the name a decision is recorded under'],
+];
+/**
+ * Built rather than typed out, and padded from the names themselves: a
+ * hand-aligned block goes crooked the first time one of them is renamed.
+ */
+const USAGE = ((widest) => [
+    'variance-authority-tribunal — a process, a port, a file and two tokens.',
+    '',
+    'Configured by environment. There are no flags.',
+    '',
+    ...VARIABLES.map(([name, what]) => `  ${name.padEnd(widest)}  ${what}`),
+    '',
+].join('\n'))(Math.max(...VARIABLES.map(([name]) => name.length)));
+async function main() {
+    let service;
+    try {
+        const usage = readArguments(process.argv.slice(2));
+        if (usage !== null) {
+            process.stdout.write(usage);
+            return;
+        }
+        service = await start(process.env);
+    }
+    catch (error) {
+        process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+        process.exit(1);
+        return;
+    }
+    // Both signals close the database rather than letting the process die with a
+    // write in flight. SQLite recovers from that, but an operator reading a WAL
+    // recovery message has no way to know nothing was lost.
+    for (const signal of ['SIGINT', 'SIGTERM']) {
+        process.once(signal, () => {
+            void service.close().then(() => process.exit(0), (error) => {
+                process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+                process.exit(1);
+            });
+        });
+    }
+}
+/**
+ * Whether `entry` names this file, following links on both sides.
+ *
+ * A package manager installs a bin as a symlink — `node_modules/.bin/variance-authority-tribunal`
+ * pointing here — so `process.argv[1]` is the link and `import.meta.url` is its
+ * target. Compared as written they never match, and the guard below would then
+ * skip `main` and let the process exit 0 without serving anything.
+ */
+function isProgram(entry) {
+    try {
+        return realpathSync(entry) === realpathSync(fileURLToPath(import.meta.url));
+    }
+    catch {
+        return false;
+    }
+}
+if (process.argv[1] !== undefined && isProgram(process.argv[1])) {
+    await main();
+}
+//# sourceMappingURL=bin.js.map

package/dist/node/bin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.js","sourceRoot":"","sources":["../../src/node/bin.ts"],"names":[],"mappings":"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","sourcesContent":["#!/usr/bin/env node\nimport { realpathSync } from 'node:fs';\nimport { userInfo } from 'node:os';\nimport { resolve } from 'node:path';\nimport process from 'node:process';\nimport { fileURLToPath } from 'node:url';\nimport { createDirectoryBucket } from './bucket.js';\nimport { openDatabase, type TribunalDatabase } from './database.js';\nimport { serveTribunal, type TribunalService } from './serve.js';\nimport { createTribunal } from '../worker.js';\n\n/**\n * `variance-authority-tribunal` — the thing the operator runs.\n *\n * A process, a port, a file, a directory and two tokens. The same review\n * service a Cloudflare deployment serves, with SQLite where D1 was and a\n * directory where R2 was; every route, every refusal and every status code is\n * the same code.\n *\n * Configuration is environment variables rather than flags, matching\n * [`server`](../../../server/src/bin.ts) — a service is started by a supervisor,\n * a unit file or a container, and all three pass an environment.\n *\n * ## The three things this refuses\n *\n * **No tokens, no service.** Inherited from `createTribunal` rather than\n * re-implemented: two bearer tokens, sixteen characters each, and not the same\n * string. The refusal is the constructor's and it is quoted straight to stderr.\n *\n * **A project, named.** There is no default. An invented one puts two\n * repositories' baselines in one namespace and the first symptom is a mass\n * `changed` — the argument is the package's, and `worker-entry` only falls back\n * to `default` because a Worker environment has nobody to ask. A person typing a\n * command does.\n *\n * **Loopback unless somebody typed otherwise.** Exposure is a decision, not an\n * accident of a bind address. And on a non-loopback bind the **review surface is\n * not served at all** — see {@link authorizeFor}, which is the one piece of\n * policy this file owns.\n */\n\nexport const PORT_VARIABLE = 'VARIANCE_TRIBUNAL_PORT';\nexport const HOST_VARIABLE = 'VARIANCE_TRIBUNAL_HOST';\nexport const DATABASE_VARIABLE = 'VARIANCE_TRIBUNAL_DB';\nexport const STORAGE_VARIABLE = 'VARIANCE_TRIBUNAL_STORAGE';\nexport const PROJECT_VARIABLE = 'VARIANCE_TRIBUNAL_PROJECT';\nexport const INGEST_TOKEN_VARIABLE = 'VARIANCE_TRIBUNAL_INGEST_TOKEN';\nexport const REVIEW_TOKEN_VARIABLE = 'VARIANCE_TRIBUNAL_REVIEW_TOKEN';\nexport const RETENTION_VARIABLE = 'VARIANCE_TRIBUNAL_RETENTION_DAYS';\nexport const REVIEWER_VARIABLE = 'VARIANCE_TRIBUNAL_REVIEWER';\nexport const TRUST_NETWORK_VARIABLE = 'VARIANCE_TRIBUNAL_TRUST_NETWORK';\n\nconst DEFAULT_PORT = 7789;\nconst DEFAULT_HOST = '127.0.0.1';\nconst DEFAULT_DATABASE = 'variance-tribunal.db';\nconst DEFAULT_STORAGE = 'variance-tribunal-objects';\n\n/** Addresses that can only be reached from the machine the process is on. */\nconst LOOPBACK = new Set(['127.0.0.1', 'localhost', '::1']);\n\nexport interface TribunalConfig {\n  readonly port: number;\n  readonly host: string;\n  /** Absolute, so the startup line names the file rather than a guess. */\n  readonly database: string;\n  /** Absolute, for the same reason. */\n  readonly storage: string;\n  readonly project: string;\n  readonly ingestToken: string;\n  readonly reviewToken: string;\n  readonly retentionDays?: number;\n  readonly reviewer: string;\n  /**\n   * Whether the socket is reachable only from this machine.\n   *\n   * Derived rather than configured: it is a fact about the bind address, and a\n   * setting that could disagree with the address would be a setting that lies.\n   */\n  readonly loopback: boolean;\n}\n\n/**\n * Read the configuration, or explain exactly which variable is wrong.\n *\n * Pure and exported, so every refusal below is testable without binding a port.\n * A rule that can only be exercised by starting a process is a rule that gets\n * tested once, by hand, before it is weakened.\n */\nexport function readConfig(env: Readonly<Record<string, string | undefined>>): TribunalConfig {\n  const project = (env[PROJECT_VARIABLE] ?? '').trim();\n  if (project === '') {\n    throw new Error(\n      `${PROJECT_VARIABLE} is not set. It scopes every row and every object key, so one ` +\n        'deployment can serve several repositories without their `story:card` colliding. There ' +\n        'is no default on purpose: an invented one puts two projects\\' baselines in one ' +\n        'namespace, and the first symptom is every subject reporting `changed` at once.',\n    );\n  }\n\n  const host = orDefault(env[HOST_VARIABLE], DEFAULT_HOST);\n  const loopback = LOOPBACK.has(host);\n  if (!loopback && orDefault(env[TRUST_NETWORK_VARIABLE], '') === '') {\n    throw new Error(\n      `${HOST_VARIABLE} is \"${host}\", which is reachable from outside this machine, and ` +\n        `${TRUST_NETWORK_VARIABLE} is not set. This service has bearer tokens and no accounts, ` +\n        'no TLS and no rate limit, so a network bind is a decision somebody should have typed. ' +\n        `Set ${TRUST_NETWORK_VARIABLE}=1 to confirm it — and read what it costs: the review ` +\n        'surface is not served on a network bind, because there would be nothing between it and ' +\n        'an approve button on the internet. Put the Next.js adapter behind your own sign-in ' +\n        'instead, or leave this on loopback behind a reverse proxy that authenticates.',\n    );\n  }\n\n  const rawPort = env[PORT_VARIABLE];\n  const port = rawPort === undefined || rawPort === '' ? DEFAULT_PORT : Number(rawPort);\n  if (!Number.isInteger(port) || port < 0 || port > 65_535) {\n    throw new Error(\n      `${PORT_VARIABLE} must be a whole number between 0 and 65535; received \"${rawPort ?? ''}\"`,\n    );\n  }\n\n  const rawRetention = env[RETENTION_VARIABLE];\n  const retentionDays = rawRetention === undefined || rawRetention === '' ? undefined : Number(rawRetention);\n  if (retentionDays !== undefined && (!Number.isFinite(retentionDays) || retentionDays <= 0)) {\n    throw new Error(\n      `${RETENTION_VARIABLE} must be a positive number of days; received \"${rawRetention ?? ''}\". ` +\n        'Leave it unset for the package default rather than passing zero, which would sweep ' +\n        'every build the first time anyone asked.',\n    );\n  }\n\n  return {\n    port,\n    host,\n    loopback,\n    database: resolve(orDefault(env[DATABASE_VARIABLE], DEFAULT_DATABASE)),\n    storage: resolve(orDefault(env[STORAGE_VARIABLE], DEFAULT_STORAGE)),\n    project,\n    // Passed through unvalidated: `createTribunal` refuses a short token and two\n    // identical ones, and a second copy of that rule here is a second place for\n    // it to be relaxed.\n    ingestToken: env[INGEST_TOKEN_VARIABLE] ?? '',\n    reviewToken: env[REVIEW_TOKEN_VARIABLE] ?? '',\n    ...(retentionDays === undefined ? {} : { retentionDays }),\n    reviewer: orDefault(env[REVIEWER_VARIABLE], defaultReviewer()),\n  };\n}\n\n/**\n * The one piece of policy this file owns: who is allowed what.\n *\n * `createTribunalRoutes` requires an `authorize` and gives it no default, on the\n * grounds that returning `'review'` for every request would publish an approve\n * button. This is a host writing that function in its own file, where the next\n * person can read it — which is exactly what that refusal asks for.\n *\n * Three rules, in order:\n *\n * 1. **A caller holding a token gets what the token is for.** CI posts with the\n *    ingest token from wherever CI runs. The mount replaces the header before the\n *    Worker sees it, so this is the only place the caller's own bearer is read.\n * 2. **On a loopback bind, a caller with no token reviews.** The socket is the\n *    gate: only this machine can reach it, and the person at this machine is the\n *    reviewer. This is what lets the served page work with no credential in it.\n * 3. **On a network bind, no token is no capability** — and the surface is not\n *    served at all, so there is no page to be tricked into carrying one.\n */\nexport function authorizeFor(config: TribunalConfig): (request: Request) => 'ingest' | 'review' | null {\n  return (request: Request) => {\n    const bearer = bearerOf(request);\n    if (bearer !== null) {\n      if (bearer === config.ingestToken) return 'ingest';\n      if (bearer === config.reviewToken) return 'review';\n      return null;\n    }\n    return config.loopback ? 'review' : null;\n  };\n}\n\nfunction bearerOf(request: Request): string | null {\n  const header = request.headers.get('authorization');\n  if (header === null) return null;\n  const match = /^Bearer\\s+(.+)$/i.exec(header.trim());\n  return match === null ? null : (match[1] as string);\n}\n\nexport interface RunningTribunal extends TribunalService {\n  readonly database: TribunalDatabase;\n}\n\n/**\n * Open the file, make the directory, bind the port, and say what was done.\n *\n * The startup line names the absolute database path, the absolute object\n * directory, the project, the schema version and the bind address, and names\n * neither token. Everything an operator needs to confirm they configured the\n * right thing, and nothing that turns a shipped log into a credential.\n */\nexport async function start(\n  env: Readonly<Record<string, string | undefined>>,\n  write: (line: string) => void = (line) => process.stdout.write(line),\n): Promise<RunningTribunal> {\n  const config = readConfig(env);\n  const database = await openDatabase(config.database);\n\n  let service: TribunalService;\n  try {\n    const tribunal = createTribunal({\n      db: database,\n      bucket: createDirectoryBucket(config.storage),\n      project: config.project,\n      ingestToken: config.ingestToken,\n      reviewToken: config.reviewToken,\n      ...(config.retentionDays === undefined ? {} : { retentionDays: config.retentionDays }),\n    });\n\n    service = await serveTribunal({\n      tribunal,\n      host: config.host,\n      port: config.port,\n      authorize: authorizeFor(config),\n      tokens: { ingest: config.ingestToken, review: config.reviewToken },\n      ui: config.loopback,\n      reviewer: config.reviewer,\n    });\n  } catch (error) {\n    // A refused token or a taken port leaves the database open otherwise, holding\n    // its lock against the process the operator is about to start instead.\n    database.close();\n    throw error;\n  }\n\n  write(\n    `variance-authority tribunal listening on ${service.url}\\n` +\n      `  project:  ${config.project}\\n` +\n      `  database: ${config.database} (schema version ${database.version})\\n` +\n      `  objects:  ${config.storage}\\n` +\n      `  review:   ${\n        config.loopback\n          ? `served at ${service.url} — this bind is reachable only from this machine`\n          : `not served: ${HOST_VARIABLE} is a network address. The JSON API is up and wants a bearer token`\n      }\\n` +\n      `  auth:     bearer tokens from ${INGEST_TOKEN_VARIABLE} and ${REVIEW_TOKEN_VARIABLE}\\n`,\n  );\n\n  return {\n    ...service,\n    database,\n    async close(): Promise<void> {\n      await service.close();\n      database.close();\n    },\n  };\n}\n\nfunction orDefault(value: string | undefined, fallback: string): string {\n  return value === undefined || value.trim() === '' ? fallback : value.trim();\n}\n\n/**\n * Who a decision is recorded as when nobody said.\n *\n * There are no accounts here — a decision carries a name, and the name should be\n * a person rather than the word \"reviewer\". The OS knows one; `userInfo` throws\n * on a host with no passwd entry, which some containers are.\n */\nfunction defaultReviewer(): string {\n  try {\n    return userInfo().username;\n  } catch {\n    return 'reviewer';\n  }\n}\n\n/**\n * A flag is not a way to configure this, and saying so is the whole point.\n *\n * `process.argv` was read by nothing here, which is defensible — configuration\n * is an environment, for the reason on the module — and silently accepting the\n * arguments of the configuration this *is not* is not. `--database ./x.db` on a\n * process that only reads {@link DATABASE_VARIABLE} starts a service against a\n * fresh empty file in the working directory, reports success, and prints a\n * startup line that reads as confirmation because it is honestly reporting what\n * the process did. The operator's next move is to ask why their builds are\n * gone.\n *\n * So: refuse, and name the variable the flag was reaching for. Returning the\n * usage text rather than writing it keeps this pure — the refusals above are\n * testable without binding a port and this one is no different.\n */\nexport function readArguments(argv: readonly string[]): string | null {\n  if (argv.length === 0) return null;\n  if (argv.includes('--help') || argv.includes('-h')) return USAGE;\n\n  const given = argv[0] as string;\n  const flag = given.split('=')[0] as string;\n  const variable = AS_VARIABLE[flag];\n\n  throw new Error(\n    variable === undefined\n      ? `this service takes no arguments and received \\`${given}\\`. It is configured by ` +\n          `environment, because a service is started by a supervisor, a unit file or a ` +\n          `container, and all three pass one.\\n\\n${USAGE}`\n      : `\\`${flag}\\` is ${variable}, and this service is configured by environment rather ` +\n          `than by flags. Accepting the flag and ignoring it would start the service against ` +\n          `the default instead — for ${DATABASE_VARIABLE}, an empty database in the working ` +\n          `directory, reported as a successful start.\\n\\n${USAGE}`,\n  );\n}\n\n/** The flags somebody reaches for, and what each one actually is. */\nconst AS_VARIABLE: Readonly<Record<string, string>> = {\n  '--db': DATABASE_VARIABLE,\n  '--database': DATABASE_VARIABLE,\n  '--objects': STORAGE_VARIABLE,\n  '--storage': STORAGE_VARIABLE,\n  '--port': PORT_VARIABLE,\n  '--host': HOST_VARIABLE,\n  '--project': PROJECT_VARIABLE,\n  '--retention': RETENTION_VARIABLE,\n  '--reviewer': REVIEWER_VARIABLE,\n};\n\n/** Every variable, in the order somebody sets them. */\nconst VARIABLES: readonly (readonly [string, string])[] = [\n  [PROJECT_VARIABLE, 'required — scopes every row and every object key'],\n  [INGEST_TOKEN_VARIABLE, 'required — what CI pushes with'],\n  [REVIEW_TOKEN_VARIABLE, 'required — what a person decides with'],\n  [DATABASE_VARIABLE, `the SQLite file (default ${DEFAULT_DATABASE})`],\n  [STORAGE_VARIABLE, `where images are kept (default ${DEFAULT_STORAGE})`],\n  [PORT_VARIABLE, `default ${DEFAULT_PORT}`],\n  [HOST_VARIABLE, `default ${DEFAULT_HOST}; a network bind serves no review page`],\n  [TRUST_NETWORK_VARIABLE, 'confirms a network bind was meant'],\n  [RETENTION_VARIABLE, 'days after which a build is swept'],\n  [REVIEWER_VARIABLE, 'the name a decision is recorded under'],\n];\n\n/**\n * Built rather than typed out, and padded from the names themselves: a\n * hand-aligned block goes crooked the first time one of them is renamed.\n */\nconst USAGE = ((widest: number) =>\n  [\n    'variance-authority-tribunal — a process, a port, a file and two tokens.',\n    '',\n    'Configured by environment. There are no flags.',\n    '',\n    ...VARIABLES.map(([name, what]) => `  ${name.padEnd(widest)}  ${what}`),\n    '',\n  ].join('\\n'))(Math.max(...VARIABLES.map(([name]) => name.length)));\n\nasync function main(): Promise<void> {\n  let service: RunningTribunal;\n  try {\n    const usage = readArguments(process.argv.slice(2));\n    if (usage !== null) {\n      process.stdout.write(usage);\n      return;\n    }\n    service = await start(process.env);\n  } catch (error) {\n    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\\n`);\n    process.exit(1);\n    return;\n  }\n\n  // Both signals close the database rather than letting the process die with a\n  // write in flight. SQLite recovers from that, but an operator reading a WAL\n  // recovery message has no way to know nothing was lost.\n  for (const signal of ['SIGINT', 'SIGTERM'] as const) {\n    process.once(signal, () => {\n      void service.close().then(\n        () => process.exit(0),\n        (error: unknown) => {\n          process.stderr.write(`${error instanceof Error ? error.message : String(error)}\\n`);\n          process.exit(1);\n        },\n      );\n    });\n  }\n}\n\n/**\n * Whether `entry` names this file, following links on both sides.\n *\n * A package manager installs a bin as a symlink — `node_modules/.bin/variance-authority-tribunal`\n * pointing here — so `process.argv[1]` is the link and `import.meta.url` is its\n * target. Compared as written they never match, and the guard below would then\n * skip `main` and let the process exit 0 without serving anything.\n */\nfunction isProgram(entry: string): boolean {\n  try {\n    return realpathSync(entry) === realpathSync(fileURLToPath(import.meta.url));\n  } catch {\n    return false;\n  }\n}\n\nif (process.argv[1] !== undefined && isProgram(process.argv[1])) {\n  await main();\n}\n"]}

package/dist/node/bucket.d.ts

@@ -0,0 +1,58 @@
+import type { R2Like } from '../bindings.js';
+/**
+ * R2, as a directory somebody owns.
+ *
+ * Four methods, and every one of them is a file operation. What makes this worth
+ * a file of its own is not the I/O — it is that an object key is a *string this
+ * package composed*, and a filesystem path is a thing an operating system
+ * resolves. Between those two sits every traversal bug ever written, so the
+ * mapping is checked rather than concatenated.
+ *
+ * ## Keys, and what may become a path
+ *
+ * The keys are built in [`store.ts`](../store.ts) and
+ * [`review-write.ts`](../review-write.ts) and have three shapes:
+ *
+ * ```
+ * <project>/baselines/<identityDigest>/<encoded subject>.png
+ * <project>/cache/<identityDigest>/<documentDigest>.png
+ * <project>/builds/<encoded build>/<encoded subject>-after.png
+ * ```
+ *
+ * Every volatile segment is already `encodeURIComponent`'d, which removes `/`
+ * and leaves `.` — so `..` is reachable only through `project`, which is an
+ * operator's own string and is the one segment nothing encodes. Rather than
+ * trusting that, every segment is checked here: this is the layer that owns the
+ * filesystem, and a rule enforced where the risk is cannot be dropped by a
+ * caller that forgets it exists.
+ *
+ * ## The hazard that is documented rather than solved
+ *
+ * **A case-insensitive filesystem folds two subjects into one.** macOS's default
+ * APFS and Windows both do; `story:Card` and `story:card` are two baselines, two
+ * rows, and one file. The consequence is a comparison against the wrong image,
+ * which is the failure this project exists to refuse — so it is said here rather
+ * than left for somebody to find.
+ *
+ * It is not solved by escaping, because escaping does not help: any encoding
+ * that survives a case-folding filesystem has to fold case itself, which loses
+ * the name. The plain-directory backend in
+ * [`@variance-authority/store`](../../../store) makes the same trade with the
+ * same layout, and the honest mitigation is the same one: on a case-insensitive
+ * volume, a project whose subject ids differ only by case needs a different
+ * volume. Case collisions are detected on `put` (below) rather than merged
+ * silently.
+ */
+export interface DirectoryBucket extends R2Like {
+    /** Where objects land, absolute. Printed at startup so the bytes can be found. */
+    readonly root: string;
+}
+/**
+ * Objects under `root`, one file per key, directories made on demand.
+ *
+ * `root` is created if it does not exist. It is not emptied, checked for
+ * foreign files, or claimed: an operator pointing two projects at one directory
+ * gets two project-prefixed trees, which is what the key layout is for.
+ */
+export declare function createDirectoryBucket(root: string): DirectoryBucket;
+//# sourceMappingURL=bucket.d.ts.map

package/dist/node/bucket.js

@@ -0,0 +1,142 @@
+import { mkdir, readFile, readdir, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { isAbsolute, join, resolve, sep } from 'node:path';
+/**
+ * Objects under `root`, one file per key, directories made on demand.
+ *
+ * `root` is created if it does not exist. It is not emptied, checked for
+ * foreign files, or claimed: an operator pointing two projects at one directory
+ * gets two project-prefixed trees, which is what the key layout is for.
+ */
+export function createDirectoryBucket(root) {
+    const base = resolve(root);
+    const pathOf = (key) => {
+        const full = join(base, ...segmentsOf(key));
+        // The check that is not redundant with `segmentsOf`: a symlink inside the
+        // tree can point out of it, and only the resolved path knows. Cheap, and it
+        // is the last line before an `unlink`.
+        if (full !== base && !full.startsWith(base + sep)) {
+            throw new Error(`the object key ${JSON.stringify(key)} resolves outside ${base}`);
+        }
+        return full;
+    };
+    return {
+        root: base,
+        async get(key) {
+            const bytes = await readFile(pathOf(key)).catch(absentAsNull);
+            if (bytes === null)
+                return null;
+            return {
+                arrayBuffer: async () => bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength),
+            };
+        },
+        /**
+         * Existence without the bytes — a `stat`, which is what R2's `head` is.
+         *
+         * `describe` spends one of these per subject to confirm a sidecar row's
+         * object is still there, so it is on the hot path of every run and must not
+         * read a megabyte to answer a boolean.
+         */
+        async head(key) {
+            const found = await stat(pathOf(key)).catch(absentAsNull);
+            return found === null || !found.isFile() ? null : { key, size: found.size };
+        },
+        /**
+         * Write, and make the write atomic.
+         *
+         * A baseline half on disk is worse than a baseline absent: `find` would
+         * return a truncated PNG, the decoder would fail, and the failure would
+         * arrive as a comparison error rather than as the disk-full it is. So the
+         * bytes land beside the target and are renamed onto it, which is atomic
+         * within a filesystem — and the temporary name carries the process id so two
+         * services sharing a directory cannot rename each other's half-written file
+         * into place.
+         */
+        async put(key, value) {
+            const target = pathOf(key);
+            await mkdir(join(target, '..'), { recursive: true });
+            const existing = await stat(target).catch(absentAsNull);
+            if (existing !== null)
+                await refuseCaseFold(target, key);
+            const staging = `${target}.${process.pid}.${writes++}.part`;
+            try {
+                await writeFile(staging, new Uint8Array(value));
+                await rename(staging, target);
+            }
+            catch (error) {
+                await rm(staging, { force: true });
+                throw error;
+            }
+            return { key };
+        },
+        async delete(keys) {
+            for (const key of typeof keys === 'string' ? [keys] : keys) {
+                await rm(pathOf(key), { force: true });
+            }
+            return undefined;
+        },
+    };
+}
+/** Distinguishes "no such object" from "the disk said no", which are not the same answer. */
+function absentAsNull(error) {
+    if (error.code === 'ENOENT' || error.code === 'ENOTDIR')
+        return null;
+    throw error;
+}
+/**
+ * Split a key into path segments, refusing every one that is not a file name.
+ *
+ * `.` and `..` are the traversal; the empty segment is a doubled slash, which
+ * `join` would swallow and which would silently address a different object than
+ * the key names. A backslash is refused because Windows treats it as a
+ * separator and POSIX does not, and a store whose key space depends on the
+ * host's opinion of one character is a store whose keys change when it moves.
+ */
+function segmentsOf(key) {
+    if (key === '' || isAbsolute(key)) {
+        throw new Error(`the object key ${JSON.stringify(key)} is not a relative key`);
+    }
+    const segments = key.split('/');
+    for (const segment of segments) {
+        if (segment === '' || segment === '.' || segment === '..' || /[\\\0]/.test(segment)) {
+            throw new Error(`the object key ${JSON.stringify(key)} has a segment (${JSON.stringify(segment)}) that ` +
+                'is not a file name. Keys are composed by this package from the project name and ' +
+                'percent-encoded ids; a project name containing a slash, a dot on its own, or a ' +
+                'backslash is the way this happens');
+        }
+    }
+    return segments;
+}
+/**
+ * Refuse a write that a case-folding volume would land on another key's object.
+ *
+ * Only reachable when the target already exists, and that is the whole subtlety:
+ * "this object is being rewritten" and "a different key just folded onto this
+ * one" are the same `stat` result, and only the directory listing tells them
+ * apart. If the exact file name is present, the volume is not folding and the
+ * write is an ordinary overwrite. If it is absent while the path resolves, the
+ * volume folded — and the bytes about to be written belong to a different
+ * subject than the ones already there.
+ *
+ * The opposite check — refusing on a case-*sensitive* volume because two
+ * variants exist — would be wrong: there, they are two objects, correctly, and
+ * refusing the second one would break a project whose subject ids differ by case
+ * on exactly the filesystem that handles them properly.
+ */
+async function refuseCaseFold(target, key) {
+    const directory = join(target, '..');
+    const name = target.slice(directory.length + 1);
+    const entries = await readdir(directory).catch(() => []);
+    if (entries.includes(name))
+        return;
+    const folded = entries.find((entry) => entry.toLowerCase() === name.toLowerCase());
+    if (folded === undefined)
+        return;
+    throw new Error(`the object key ${JSON.stringify(key)} resolves to an object stored under a different name ` +
+        `(${JSON.stringify(folded)}) that differs from it only by case. This volume folds the two ` +
+        'into one file, so writing here would replace another subject\'s image and every later ' +
+        'comparison would run against the wrong one. Put the object store on a case-sensitive ' +
+        'filesystem, or give the two subjects ids that differ by more than case');
+}
+/** Distinguishes two staging files written in the same millisecond by one process. */
+let writes = 0;
+//# sourceMappingURL=bucket.js.map

package/dist/node/bucket.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bucket.js","sourceRoot":"","sources":["../../src/node/bucket.ts"],"names":[],"mappings":"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","sourcesContent":["import { mkdir, readFile, readdir, rename, rm, stat, writeFile } from 'node:fs/promises';\nimport { isAbsolute, join, resolve, sep } from 'node:path';\nimport type { R2Like, R2ObjectLike } from '../bindings.js';\n\n/**\n * R2, as a directory somebody owns.\n *\n * Four methods, and every one of them is a file operation. What makes this worth\n * a file of its own is not the I/O — it is that an object key is a *string this\n * package composed*, and a filesystem path is a thing an operating system\n * resolves. Between those two sits every traversal bug ever written, so the\n * mapping is checked rather than concatenated.\n *\n * ## Keys, and what may become a path\n *\n * The keys are built in [`store.ts`](../store.ts) and\n * [`review-write.ts`](../review-write.ts) and have three shapes:\n *\n * ```\n * <project>/baselines/<identityDigest>/<encoded subject>.png\n * <project>/cache/<identityDigest>/<documentDigest>.png\n * <project>/builds/<encoded build>/<encoded subject>-after.png\n * ```\n *\n * Every volatile segment is already `encodeURIComponent`'d, which removes `/`\n * and leaves `.` — so `..` is reachable only through `project`, which is an\n * operator's own string and is the one segment nothing encodes. Rather than\n * trusting that, every segment is checked here: this is the layer that owns the\n * filesystem, and a rule enforced where the risk is cannot be dropped by a\n * caller that forgets it exists.\n *\n * ## The hazard that is documented rather than solved\n *\n * **A case-insensitive filesystem folds two subjects into one.** macOS's default\n * APFS and Windows both do; `story:Card` and `story:card` are two baselines, two\n * rows, and one file. The consequence is a comparison against the wrong image,\n * which is the failure this project exists to refuse — so it is said here rather\n * than left for somebody to find.\n *\n * It is not solved by escaping, because escaping does not help: any encoding\n * that survives a case-folding filesystem has to fold case itself, which loses\n * the name. The plain-directory backend in\n * [`@variance-authority/store`](../../../store) makes the same trade with the\n * same layout, and the honest mitigation is the same one: on a case-insensitive\n * volume, a project whose subject ids differ only by case needs a different\n * volume. Case collisions are detected on `put` (below) rather than merged\n * silently.\n */\n\nexport interface DirectoryBucket extends R2Like {\n  /** Where objects land, absolute. Printed at startup so the bytes can be found. */\n  readonly root: string;\n}\n\n/**\n * Objects under `root`, one file per key, directories made on demand.\n *\n * `root` is created if it does not exist. It is not emptied, checked for\n * foreign files, or claimed: an operator pointing two projects at one directory\n * gets two project-prefixed trees, which is what the key layout is for.\n */\nexport function createDirectoryBucket(root: string): DirectoryBucket {\n  const base = resolve(root);\n\n  const pathOf = (key: string): string => {\n    const full = join(base, ...segmentsOf(key));\n\n    // The check that is not redundant with `segmentsOf`: a symlink inside the\n    // tree can point out of it, and only the resolved path knows. Cheap, and it\n    // is the last line before an `unlink`.\n    if (full !== base && !full.startsWith(base + sep)) {\n      throw new Error(`the object key ${JSON.stringify(key)} resolves outside ${base}`);\n    }\n    return full;\n  };\n\n  return {\n    root: base,\n\n    async get(key: string): Promise<R2ObjectLike | null> {\n      const bytes = await readFile(pathOf(key)).catch(absentAsNull);\n      if (bytes === null) return null;\n      return {\n        arrayBuffer: async (): Promise<ArrayBuffer> =>\n          bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength) as ArrayBuffer,\n      };\n    },\n\n    /**\n     * Existence without the bytes — a `stat`, which is what R2's `head` is.\n     *\n     * `describe` spends one of these per subject to confirm a sidecar row's\n     * object is still there, so it is on the hot path of every run and must not\n     * read a megabyte to answer a boolean.\n     */\n    async head(key: string): Promise<unknown | null> {\n      const found = await stat(pathOf(key)).catch(absentAsNull);\n      return found === null || !found.isFile() ? null : { key, size: found.size };\n    },\n\n    /**\n     * Write, and make the write atomic.\n     *\n     * A baseline half on disk is worse than a baseline absent: `find` would\n     * return a truncated PNG, the decoder would fail, and the failure would\n     * arrive as a comparison error rather than as the disk-full it is. So the\n     * bytes land beside the target and are renamed onto it, which is atomic\n     * within a filesystem — and the temporary name carries the process id so two\n     * services sharing a directory cannot rename each other's half-written file\n     * into place.\n     */\n    async put(key: string, value: ArrayBuffer): Promise<unknown> {\n      const target = pathOf(key);\n      await mkdir(join(target, '..'), { recursive: true });\n\n      const existing = await stat(target).catch(absentAsNull);\n      if (existing !== null) await refuseCaseFold(target, key);\n\n      const staging = `${target}.${process.pid}.${writes++}.part`;\n      try {\n        await writeFile(staging, new Uint8Array(value));\n        await rename(staging, target);\n      } catch (error) {\n        await rm(staging, { force: true });\n        throw error;\n      }\n      return { key };\n    },\n\n    async delete(keys: string | readonly string[]): Promise<unknown> {\n      for (const key of typeof keys === 'string' ? [keys] : keys) {\n        await rm(pathOf(key), { force: true });\n      }\n      return undefined;\n    },\n  };\n}\n\n/** Distinguishes \"no such object\" from \"the disk said no\", which are not the same answer. */\nfunction absentAsNull(error: NodeJS.ErrnoException): null {\n  if (error.code === 'ENOENT' || error.code === 'ENOTDIR') return null;\n  throw error;\n}\n\n/**\n * Split a key into path segments, refusing every one that is not a file name.\n *\n * `.` and `..` are the traversal; the empty segment is a doubled slash, which\n * `join` would swallow and which would silently address a different object than\n * the key names. A backslash is refused because Windows treats it as a\n * separator and POSIX does not, and a store whose key space depends on the\n * host's opinion of one character is a store whose keys change when it moves.\n */\nfunction segmentsOf(key: string): readonly string[] {\n  if (key === '' || isAbsolute(key)) {\n    throw new Error(`the object key ${JSON.stringify(key)} is not a relative key`);\n  }\n\n  const segments = key.split('/');\n  for (const segment of segments) {\n    if (segment === '' || segment === '.' || segment === '..' || /[\\\\\\0]/.test(segment)) {\n      throw new Error(\n        `the object key ${JSON.stringify(key)} has a segment (${JSON.stringify(segment)}) that ` +\n          'is not a file name. Keys are composed by this package from the project name and ' +\n          'percent-encoded ids; a project name containing a slash, a dot on its own, or a ' +\n          'backslash is the way this happens',\n      );\n    }\n  }\n  return segments;\n}\n\n/**\n * Refuse a write that a case-folding volume would land on another key's object.\n *\n * Only reachable when the target already exists, and that is the whole subtlety:\n * \"this object is being rewritten\" and \"a different key just folded onto this\n * one\" are the same `stat` result, and only the directory listing tells them\n * apart. If the exact file name is present, the volume is not folding and the\n * write is an ordinary overwrite. If it is absent while the path resolves, the\n * volume folded — and the bytes about to be written belong to a different\n * subject than the ones already there.\n *\n * The opposite check — refusing on a case-*sensitive* volume because two\n * variants exist — would be wrong: there, they are two objects, correctly, and\n * refusing the second one would break a project whose subject ids differ by case\n * on exactly the filesystem that handles them properly.\n */\nasync function refuseCaseFold(target: string, key: string): Promise<void> {\n  const directory = join(target, '..');\n  const name = target.slice(directory.length + 1);\n  const entries = await readdir(directory).catch(() => [] as string[]);\n  if (entries.includes(name)) return;\n\n  const folded = entries.find((entry) => entry.toLowerCase() === name.toLowerCase());\n  if (folded === undefined) return;\n\n  throw new Error(\n    `the object key ${JSON.stringify(key)} resolves to an object stored under a different name ` +\n      `(${JSON.stringify(folded)}) that differs from it only by case. This volume folds the two ` +\n      'into one file, so writing here would replace another subject\\'s image and every later ' +\n      'comparison would run against the wrong one. Put the object store on a case-sensitive ' +\n      'filesystem, or give the two subjects ids that differ by more than case',\n  );\n}\n\n/** Distinguishes two staging files written in the same millisecond by one process. */\nlet writes = 0;\n"]}