@coffre/vault 0.0.0 → 0.1.0

package/package.json

@@ -1,8 +1,54 @@
 {
   "name": "@coffre/vault",
-  "version": "0.0.0",
-  "description": "Reserved for coffre, a self-hosted secrets manager. The first release replaces this placeholder.",
+  "version": "0.1.0",
+  "description": "coffre's vault: keys, grants and members, in the database the app uses, as a Cloudflare Worker or on Node.",
   "license": "MIT",
-  "homepage": "https://github.com/erwinkn/coffre",
-  "repository": { "type": "git", "url": "git+https://github.com/erwinkn/coffre.git", "directory": "packages/vault" }
-}
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/erwinkn/coffre.git",
+    "directory": "packages/vault"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "exports": {
+    ".": {
+      "coffre:source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./cloudflare": {
+      "coffre:source": "./src/cloudflare.ts",
+      "types": "./dist/cloudflare.d.ts",
+      "default": "./dist/cloudflare.js"
+    },
+    "./node": {
+      "coffre:source": "./src/node.ts",
+      "types": "./dist/node.d.ts",
+      "default": "./dist/node.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "drizzle-orm": "0.45.2",
+    "@coffre/core": "0.1.0",
+    "@coffre/db": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "26.1.1",
+    "@types/pg": "8.20.0",
+    "pg": "8.16.3",
+    "tsdown": "0.23.0",
+    "typescript": "5.9.3"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "test": "node --conditions=coffre:source --test"
+  }
+}

package/src/accounting.ts

@@ -0,0 +1,110 @@
+import type { StoredEntry } from '@coffre/core/audit';
+import type { LogVerification } from '@coffre/core/vault';
+import type { Queryable } from '@coffre/db';
+
+import { VERIFY_BATCH } from './log.ts';
+import { entriesFrom } from './store.ts';
+
+const KEY_ACTIONS = new Set(['secret.read', 'key.wrap', 'key.rewrap']);
+
+type Item = { item: number; secretId: string; version: number; subject: string };
+type ParsedIntent = { intentId: string; operation: string; expiresAt: number; keys: Item[] };
+type ParsedOutcome = Item & { intentId: string; relatedSeq: bigint };
+type Intent = ParsedIntent & { entry: StoredEntry; seen: Set<number> };
+type Accounting = { ok: true; pending: number } | Extract<LogVerification, { ok: false }>;
+
+/** The chain can hold while a process died between an intent and its outcomes. */
+export async function verifyAccounting(db: Queryable, at: number): Promise<Accounting> {
+  const intents = new Map<bigint, Intent>();
+  const ids = new Set<string>();
+  const broken = (entry: StoredEntry, reason: string): Accounting => ({ ok: false, failedAtSeq: Number(entry.seq), reason });
+  let next = 0n;
+  for (;;) {
+    const batch = await entriesFrom(db, next, VERIFY_BATCH);
+    if (batch.length === 0) break;
+    for (const entry of batch) {
+      if (entry.author !== 'vault') continue;
+      if (entry.action === 'key.intent') {
+        const parsed = parseIntent(entry);
+        if (typeof parsed === 'string') return broken(entry, parsed);
+        if (ids.has(parsed.intentId)) return broken(entry, 'key intent repeats an operation identity');
+        ids.add(parsed.intentId);
+        if (parsed.keys.length > 0) intents.set(entry.seq, { ...parsed, entry, seen: new Set() });
+      } else if (KEY_ACTIONS.has(entry.action) && entry.relatedSeq !== null) {
+        // An outcome names its intent; a key released with no service to call has none.
+        const parsed = parseOutcome(entry);
+        if (typeof parsed === 'string') return broken(entry, parsed);
+        const intent = intents.get(parsed.relatedSeq);
+        const key = intent?.keys[parsed.item];
+        if (intent === undefined || key === undefined || intent.seen.has(parsed.item)) {
+          return broken(entry, 'key outcome does not identify one item of its intent');
+        }
+        if (parsed.intentId !== intent.intentId || entry.actor !== intent.entry.actor || entry.action !== intent.operation) {
+          return broken(entry, 'key outcome belongs to another operation');
+        }
+        if (parsed.secretId !== key.secretId || parsed.version !== key.version || parsed.subject !== key.subject) {
+          return broken(entry, 'key outcome does not match its intended secret');
+        }
+        intent.seen.add(parsed.item);
+        // Completed batches need no state, and another outcome for one is a duplicate.
+        if (intent.seen.size === intent.keys.length) intents.delete(intent.entry.seq);
+      }
+    }
+    next = batch[batch.length - 1].seq + 1n;
+    if (batch.length < VERIFY_BATCH) break;
+  }
+  // Live calls can finish after this snapshot. Only a missed deadline is a fault.
+  const overdue = [...intents.values()].filter((intent) => intent.expiresAt <= at).sort((a, b) => a.expiresAt - b.expiresAt);
+  if (overdue.length === 0) return { ok: true, pending: intents.size };
+  const reason = overdue.map((intent) => {
+    const missing = intent.keys.length - intent.seen.size;
+    return `key intent ${intent.intentId} is overdue: ${missing} of ${intent.keys.length} outcomes missing`;
+  }).join('; ');
+  return broken(overdue[0].entry, reason);
+}
+
+function parseIntent(entry: StoredEntry): ParsedIntent | string {
+  const detail = payload(entry.metadata);
+  if (detail === null) return 'key intent has no valid accounting payload';
+  const { intent, operation, expiresAt } = detail;
+  if (typeof intent !== 'string') return 'key intent has no operation identity';
+  if (typeof operation !== 'string' || !KEY_ACTIONS.has(operation)) return 'key intent has an invalid operation';
+  if (typeof expiresAt !== 'number' || !Number.isSafeInteger(expiresAt) || expiresAt < entry.occurredAt) {
+    return 'key intent has no valid deadline';
+  }
+  if (!Array.isArray(detail.keys)) return 'key intent has no valid item list';
+  const keys: Item[] = [];
+  for (const [index, value] of detail.keys.entries()) {
+    const key = record(value);
+    if (key === null || key.item !== index) return 'key intent items are not numbered in order';
+    const { secretId, version, subject } = key;
+    if (typeof secretId !== 'string' || typeof subject !== 'string') return 'key intent item has no secret identity';
+    if (typeof version !== 'number' || !Number.isSafeInteger(version) || version < 1) return 'key intent item has no valid version';
+    keys.push({ item: index, secretId, version, subject });
+  }
+  return { intentId: intent, operation, expiresAt, keys };
+}
+
+function parseOutcome(entry: StoredEntry): ParsedOutcome | string {
+  const detail = payload(entry.metadata);
+  if (detail === null) return 'key outcome has no valid accounting payload';
+  const { intent, item, version, subject } = detail;
+  if (typeof intent !== 'string' || entry.relatedSeq === null) return 'key outcome has no intent identity';
+  if (typeof item !== 'number' || !Number.isSafeInteger(item) || item < 0) return 'key outcome has no valid item number';
+  const secretId = entry.secretId ?? detail.secretId;
+  if (typeof secretId !== 'string' || typeof subject !== 'string') return 'key outcome has no secret identity';
+  if (typeof version !== 'number' || !Number.isSafeInteger(version) || version < 1) return 'key outcome has no valid version';
+  return { intentId: intent, relatedSeq: entry.relatedSeq, item, secretId, version, subject };
+}
+
+function payload(text: string): Record<string, unknown> | null {
+  try {
+    return record(JSON.parse(text));
+  } catch {
+    return null;
+  }
+}
+
+function record(value: unknown): Record<string, unknown> | null {
+  return value !== null && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : null;
+}

package/src/checkpoint.ts

@@ -0,0 +1,25 @@
+const PKCS8_ED25519 = [0x30, 0x2e, 0x02, 0x01, 0x00, 0x30, 0x05, 0x06, 0x03, 0x2b, 0x65, 0x70, 0x04, 0x22, 0x04, 0x20];
+
+export type Signer = {
+  /** The raw Ed25519 public key, base64. */
+  publicKey: string;
+  /** The first 16 hex digits of the public key's SHA-256. */
+  keyId: string;
+  sign(message: Uint8Array<ArrayBuffer>): Promise<string>;
+};
+
+/** An Ed25519 signer from a 32-byte seed, over WebCrypto so it runs in Node and in workerd alike. */
+export async function signer(seed: Uint8Array): Promise<Signer> {
+  const pkcs8 = new Uint8Array([...PKCS8_ED25519, ...seed]);
+  const privateKey = await crypto.subtle.importKey('pkcs8', pkcs8, { name: 'Ed25519' }, true, ['sign']);
+  // A private JWK carries its public half, `x`; the raw private key does not export it.
+  const { x } = (await crypto.subtle.exportKey('jwk', privateKey)) as JsonWebKey;
+  const publicKey = Buffer.from(x!, 'base64url');
+  const digest = Buffer.from(await crypto.subtle.digest('SHA-256', publicKey));
+  return {
+    publicKey: publicKey.toString('base64'),
+    keyId: digest.toString('hex').slice(0, 16),
+    sign: async (message) =>
+      Buffer.from(await crypto.subtle.sign('Ed25519', privateKey, message)).toString('base64'),
+  };
+}

package/src/cloudflare-workers.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The one thing the vault takes from the Workers runtime, declared here so
+ * that its Worker typechecks with the rest of the package, under Node's
+ * types, as the server's does. Workers' own types would shadow Node's
+ * `Buffer` in every module the Worker imports: the store, the log, Drizzle.
+ * A deployment that builds the Worker brings the real ones.
+ */
+declare module 'cloudflare:workers' {
+  export abstract class WorkerEntrypoint<Env = unknown> {
+    protected env: Env;
+    protected ctx: { waitUntil(promise: Promise<unknown>): void };
+    constructor(ctx: unknown, env: Env);
+  }
+}

package/src/cloudflare.ts

@@ -0,0 +1,89 @@
+/**
+ * The vault as a Worker, behind an entrypoint the app's `VAULT` service
+ * binding calls over RPC. It has no route and no HTTP surface. It decides
+ * in the database the app uses, through a Hyperdrive binding of its own,
+ * whose login is the vault's:
+ *
+ *   import { postgres, vault } from '@coffre/vault/cloudflare';
+ *
+ *   export default vault((env: Env) => ({
+ *     database: postgres(env.HYPERDRIVE),
+ *     kek: { id: 'kek-1', key: env.KEK }, // or awsKms({ keyArn, credentials })
+ *     rootAdmins: ['admin@acme.example'],
+ *     signingKey: env.SIGNING_KEY,
+ *   }));
+ *
+ * Any number of isolates run it side by side: every decision locks what it
+ * is about in the database, so they share one log and one bulk limit.
+ */
+import type {
+  AdmitInput,
+  RemoveInput,
+  RewrapInput,
+  SetAccessInput,
+  UnwrapInput,
+  Vault,
+  VerifyLogInput,
+  WrapInput,
+} from '@coffre/core/vault';
+import { createDatabase } from '@coffre/db';
+import { HyperdrivePool, type PostgresDatabase } from '@coffre/db/hyperdrive';
+import { WorkerEntrypoint } from 'cloudflare:workers';
+
+import { resolveVaultConfig, type VaultConfig } from './config.ts';
+import { openVault, prepareVault, type PreparedVault } from './vault.ts';
+
+export type { Vault, VaultConfig };
+export { postgres, type PostgresDatabase } from '@coffre/db/hyperdrive';
+export * from './index.ts';
+
+/** What the vault Worker's `vault(env => …)` returns. */
+export type WorkersVaultConfig = VaultConfig & { database: PostgresDatabase };
+
+/** Set when the Worker's module runs `vault(…)`, before any call comes in. */
+let configure: ((env: never) => WorkersVaultConfig) | null = null;
+
+/** The configuration, checked and made ready once per `env`, which the isolate keeps. */
+const ready = new WeakMap<object, Promise<{ database: PostgresDatabase; prepared: PreparedVault }>>();
+
+/**
+ * What the app's `VAULT` service binding calls. Each call gets a database of
+ * its own, since a Worker's connections belong to the call that made them.
+ */
+export class VaultEntrypoint extends WorkerEntrypoint implements Vault {
+  async #vault(): Promise<Vault> {
+    const env = this.env as object;
+    let entry = ready.get(env);
+    if (entry === undefined) {
+      if (configure === null) throw new Error('the vault Worker must export default vault(…)');
+      const config = configure(env as never);
+      entry = prepareVault(resolveVaultConfig(config)).then((prepared) => ({ database: config.database, prepared }));
+      ready.set(env, entry);
+      entry.catch(() => ready.delete(env));
+    }
+    const { database, prepared } = await entry;
+    return openVault(createDatabase(new HyperdrivePool(database.hyperdrive.connectionString)), prepared);
+  }
+
+  async unwrap(input: UnwrapInput) { return (await this.#vault()).unwrap(input); }
+  async wrap(input: WrapInput) { return (await this.#vault()).wrap(input); }
+  async rewrap(input: RewrapInput) { return (await this.#vault()).rewrap(input); }
+  async access(principal: string) { return (await this.#vault()).access(principal); }
+  async setAccess(input: SetAccessInput) { return (await this.#vault()).setAccess(input); }
+  async admit(input: AdmitInput) { return (await this.#vault()).admit(input); }
+  async remove(input: RemoveInput) { return (await this.#vault()).remove(input); }
+  async checkpoint() { return (await this.#vault()).checkpoint(); }
+  async about() { return (await this.#vault()).about(); }
+  async verifyLog(input: VerifyLogInput) { return (await this.#vault()).verifyLog(input); }
+
+  /** No HTTP surface: only the app's service binding reaches the vault. */
+  fetch() {
+    return new Response('not found', { status: 404 });
+  }
+}
+
+/** The vault Worker's default export, `VaultEntrypoint`, configured from its `env`. */
+export function vault<Env>(configure_: (env: Env) => WorkersVaultConfig): typeof VaultEntrypoint {
+  configure = configure_ as (env: never) => WorkersVaultConfig;
+  return VaultEntrypoint;
+}

package/src/config.ts

@@ -0,0 +1,146 @@
+import { KekRegistry, LocalKekProvider, type KekProvider } from '@coffre/core/kek';
+
+/** At most `count` data keys unwrapped per principal in any `windowMs`. */
+export type BulkLimit = { count: number; windowMs: number };
+
+/**
+ * 1000 keys in 15 minutes: twenty `coffre run`s of a 50-key environment
+ * back to back, which no person or deploy pipeline does, while a script
+ * pulling every secret it can reach stops within a few seconds.
+ */
+export const DEFAULT_BULK_LIMIT: BulkLimit = { count: 1000, windowMs: 15 * 60_000 };
+
+/** The vault as it runs: keys decoded, emails checked. */
+export type ResolvedVaultConfig = {
+  keks: KekRegistry;
+  /** Emails, lowercased: always active, always owners, never changed through the API. */
+  rootAdmins: readonly string[];
+  /** The Ed25519 seed checkpoints are signed with. */
+  signingKey: Uint8Array;
+  bulkLimit: BulkLimit;
+};
+
+/**
+ * A key-encryption key: 32 random bytes, base64, and the id envelopes record
+ * it under; or one a key service holds, such as `awsKms({ keyArn, … })`.
+ */
+export type Kek = { id: string; key: string } | KekProvider;
+
+/**
+ * What a deployment writes: every key coffre has, and who may always get
+ * in. The app holds none of it.
+ *
+ *   {
+ *     kek: awsKms({ keyArn: env.KMS_KEY_ARN, credentials: { … } }),
+ *     previousKeks: [{ id: 'kek-2025-01', key: env.KEK_2025_01 }],
+ *     rootAdmins: ['admin@acme.example'],
+ *     signingKey: env.SIGNING_KEY,
+ *   }
+ */
+export type VaultConfig = {
+  /** Wraps every new data key. */
+  kek: Kek;
+  /** Older KEKs, still unwrapping what they wrapped until a rewrap moves it on. */
+  previousKeks?: readonly Kek[];
+  /** At least one email: the only way into a fresh instance, and the only members nobody can remove. */
+  rootAdmins: readonly string[];
+  /** 32 random bytes, base64: the Ed25519 seed audit checkpoints are signed with. */
+  signingKey: string;
+  /** At most `count` data keys unwrapped per principal in any `windowMinutes`; 1000 in 15 unless set. */
+  bulkLimit?: { count: number; windowMinutes: number };
+};
+
+function key32(value: string, what: string): Buffer {
+  const raw = Buffer.from(value, 'base64');
+  if (raw.length !== 32) throw new Error(`${what} must be 32 bytes, base64; got ${raw.length} bytes`);
+  return raw;
+}
+
+const KEK_ID = /^[A-Za-z0-9._-]{1,64}$/;
+const KEK_PROVIDER = /^[a-z0-9][a-z0-9-]{0,31}$/;
+/** Every row records it, and `provider:keyId` finds the KEK again: visible ASCII, bounded. */
+const KEK_NAME = /^[\x21-\x7e]{1,255}$/;
+
+function kek(entry: Kek): KekProvider {
+  if (!('wrap' in entry)) {
+    const { id, key } = entry;
+    if (!KEK_ID.test(id)) throw new Error(`KEK id "${id}" must be 1-64 letters, digits, dots, dashes or underscores`);
+    return new LocalKekProvider(key32(key, `KEK ${id}`), id);
+  }
+  const { provider, keyId, keyVersion } = entry;
+  if (typeof provider !== 'string' || !KEK_PROVIDER.test(provider)) {
+    throw new Error(`a KEK provider's name must be 1-32 lowercase letters, digits or dashes; got "${String(provider)}"`);
+  }
+  if (typeof keyId !== 'string' || !KEK_NAME.test(keyId) || typeof keyVersion !== 'string' || !KEK_NAME.test(keyVersion)) {
+    throw new Error(`KEK ${provider}: keyId and keyVersion must be 1-255 visible ASCII characters`);
+  }
+  if (typeof entry.wrap !== 'function' || typeof entry.unwrap !== 'function') {
+    throw new Error(`KEK ${provider}:${keyId} needs wrap() and unwrap()`);
+  }
+  return entry;
+}
+
+/** Check a deployment's vault configuration, failing on the first problem. */
+export function resolveVaultConfig(config: VaultConfig): ResolvedVaultConfig {
+  const [current, ...previous] = [config.kek, ...(config.previousKeks ?? [])].map(kek);
+  const refs = [current, ...previous].map(({ provider, keyId }) => `${provider}:${keyId}`);
+  const twice = refs.find((ref, i) => refs.indexOf(ref) !== i);
+  if (twice !== undefined) throw new Error(`two KEKs share an id: ${twice}`);
+  return {
+    keks: new KekRegistry(current, previous),
+    rootAdmins: checkRootAdmins(config.rootAdmins),
+    signingKey: key32(config.signingKey, 'the signing key'),
+    bulkLimit: config.bulkLimit === undefined ? DEFAULT_BULK_LIMIT : checkBulkLimit(config.bulkLimit),
+  };
+}
+
+function checkBulkLimit({ count, windowMinutes }: { count: number; windowMinutes: number }): BulkLimit {
+  if (!Number.isInteger(count) || count < 1 || !(windowMinutes > 0)) {
+    throw new Error('bulkLimit needs a whole count of at least 1 and a window above 0 minutes');
+  }
+  return { count, windowMs: windowMinutes * 60_000 };
+}
+
+function isHumanEmail(value: string): boolean {
+  if (value.length > 254) return false;
+
+  const parts = value.split('@');
+  if (parts.length !== 2) return false;
+  const [local, domain] = parts;
+  if (
+    local.length === 0 ||
+    local.length > 64 ||
+    local.startsWith('.') ||
+    local.endsWith('.') ||
+    local.includes('..') ||
+    !/^[A-Za-z0-9.!#$%&'*+/=?^_`{|}~-]+$/.test(local)
+  ) {
+    return false;
+  }
+
+  const labels = domain.split('.');
+  if (labels.length < 2) return false;
+  return labels.every(
+    (label) =>
+      label.length > 0 &&
+      label.length <= 63 &&
+      /^[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?$/.test(label),
+  );
+}
+
+/**
+ * Root admins, lowercased the way they are compared. At least one, in every
+ * mode: they are the only way into a fresh instance, and the only members
+ * nobody can remove.
+ */
+export function checkRootAdmins(emails: readonly string[]): string[] {
+  const rootAdmins = [...new Set(emails.map((entry) => entry.trim()).filter((entry) => entry.length > 0))];
+  if (rootAdmins.length === 0) {
+    throw new Error('rootAdmins must name at least one email, or nobody can manage coffre');
+  }
+  const invalid = rootAdmins.find((entry) => !isHumanEmail(entry));
+  if (invalid) {
+    throw new Error(`rootAdmins must be human email identities; invalid: ${invalid}`);
+  }
+  return rootAdmins.map((entry) => entry.toLowerCase());
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export type * from '@coffre/core/vault';
+export { checkpointMessage, verifyCheckpoint } from '@coffre/core/vault';
+export type { SecretContext } from '@coffre/core/envelope';
+export { awsKms, KekBadClaimError, KekUnavailableError } from '@coffre/core/kek';
+export type { AwsCredentials, AwsKmsOptions, KekProvider, WrappedDek } from '@coffre/core/kek';
+export type { Kek, VaultConfig } from './config.ts';

package/src/local.ts

@@ -0,0 +1,48 @@
+import type { Vault } from '@coffre/core/vault';
+import type { Database } from '@coffre/db';
+
+import type { ResolvedVaultConfig } from './config.ts';
+import { openVault, prepareVault, type VaultOptions } from './vault.ts';
+
+/** Every call the vault answers, in the order of the `Vault` interface. */
+export const METHODS = [
+  'unwrap',
+  'wrap',
+  'rewrap',
+  'access',
+  'setAccess',
+  'admit',
+  'remove',
+  'checkpoint',
+  'about',
+  'verifyLog',
+] as const satisfies readonly (keyof Vault)[];
+
+export type LocalVault = Vault & { close(): Promise<void> };
+
+/**
+ * The vault in this process, over `db`. Every argument and result goes
+ * through JSON on the way, as it would over RPC or a socket, so what works
+ * here does not rely on sharing objects with the caller. `close` is
+ * whatever lets go of the database, when the vault opened it.
+ */
+export async function openLocalVault(
+  db: Database,
+  config: ResolvedVaultConfig,
+  options: VaultOptions = {},
+  close: () => Promise<void> = async () => {},
+): Promise<LocalVault> {
+  const vault = openVault(db, await prepareVault(config, options));
+  const local = Object.fromEntries(
+    METHODS.map((name) => [
+      name,
+      async (...args: unknown[]) =>
+        json(await (vault[name] as (...args: unknown[]) => Promise<unknown>)(...(json(args) as unknown[]))),
+    ]),
+  ) as unknown as Vault;
+  return Object.assign(local, { close });
+}
+
+function json(value: unknown): unknown {
+  return value === undefined ? undefined : JSON.parse(JSON.stringify(value));
+}

package/src/log.ts

@@ -0,0 +1,140 @@
+import { deriveLogKey, GENESIS_HASH, verifyEntries, type LogKey, type StoredEntry } from '@coffre/core/audit';
+import type { LogHead, LogVerification } from '@coffre/core/vault';
+import type { Queryable } from '@coffre/db';
+
+import { entriesFrom, hashAt } from './store.ts';
+
+/**
+ * The vault's half of the one audit log: its entries are the ones it
+ * writes, `author = 'vault'`, each under its MAC, in the chain the app's
+ * entries share (@coffre/core/audit says what an entry covers). The app
+ * checks its own entries by its key; this checks the vault's by the vault's,
+ * and the app's only for their place in the chain.
+ */
+
+/**
+ * The vault's log key, derived from its signing key, so that it is one more
+ * secret to hold, not one more to keep. Whoever can write the database but
+ * does not hold the vault's configuration cannot write an entry it accepts.
+ */
+export function vaultLogKey(signingKey: Uint8Array): LogKey {
+  return deriveLogKey('vault', signingKey);
+}
+
+/**
+ * How far this process has verified the chain: every entry before
+ * `nextSeq`, the last of which has `hash`, with `vaultEntries` of the
+ * vault's among them. In memory only: the database cannot vouch for itself.
+ */
+export type Anchor = { nextSeq: bigint; hash: Buffer; vaultEntries: number };
+
+/** Before the first entry: nothing verified yet. */
+export const UNVERIFIED: Anchor = { nextSeq: 0n, hash: GENESIS_HASH, vaultEntries: 0 };
+
+/** The further of two anchors, when two calls verified at once. */
+export function further(a: Anchor, b: Anchor): Anchor {
+  return b.nextSeq > a.nextSeq ? b : a;
+}
+
+export const VERIFY_BATCH = 1000;
+
+type Verified = { verification: LogVerification; anchor: Anchor };
+
+/**
+ * Check the chain, a batch in memory at a time, and return where it is now
+ * verified to. Three parts:
+ *
+ * - `shown`, the page a reader is looking at: each entry against its own
+ *   hash and MAC;
+ * - `anchor`, the head at the last check: still there, unchanged. A rewrite
+ *   of anything before it, chained again to hide, changes its hash;
+ * - every entry after the anchor, or from the first.
+ *
+ * So a view rehashes only what is new since the last one. What it leaves
+ * out is an entry before the anchor edited in place, not chained again, and
+ * not on the page: a full check, which starts from `UNVERIFIED`, finds that,
+ * as does the first view after a start, which has no anchor.
+ */
+export async function verifyChain(
+  db: Queryable,
+  key: LogKey,
+  shown: readonly StoredEntry[],
+  anchor: Anchor,
+): Promise<Verified> {
+  const broken = (failedAtSeq: bigint, reason: string): Verified => ({
+    verification: { ok: false, failedAtSeq: Number(failedAtSeq), reason },
+    anchor,
+  });
+  const keys = { keys: [key], chainOnly: ['app' as const] };
+
+  for (const row of [...shown].sort((a, b) => (a.seq < b.seq ? -1 : 1))) {
+    const result = verifyEntries([row], { ...keys, startSeq: row.seq, startPrevHash: row.prevHash });
+    if (!result.ok) return broken(result.failedAtSeq, result.reason);
+  }
+
+  if (anchor.nextSeq > 0n && !(await hashAt(db, anchor.nextSeq - 1n))?.equals(anchor.hash)) {
+    return broken(anchor.nextSeq - 1n, 'changed since the vault last verified it');
+  }
+
+  let verified = anchor;
+  for (;;) {
+    const batch = await entriesFrom(db, verified.nextSeq, VERIFY_BATCH);
+    if (batch.length === 0) break;
+    const result = verifyEntries(batch, { ...keys, startSeq: verified.nextSeq, startPrevHash: verified.hash });
+    if (!result.ok) return broken(result.failedAtSeq, result.reason);
+    verified = { nextSeq: result.nextSeq, hash: result.head, vaultEntries: verified.vaultEntries + result.authenticated };
+    if (batch.length < VERIFY_BATCH) break;
+  }
+  return { verification: { ok: true, entries: verified.vaultEntries }, anchor: verified };
+}
+
+/**
+ * Whether the log still holds `head` where it was: not rewritten, nor cut
+ * back before it. A head of 64 zeros is before the first entry, which any
+ * log holds.
+ */
+export async function carries(db: Queryable, head: LogHead): Promise<boolean> {
+  if (head.hash === GENESIS_HASH.toString('hex')) return true;
+  return (await hashAt(db, BigInt(head.seq)))?.toString('hex') === head.hash;
+}
+
+/** One of the vault's entries, as its tests read them. */
+export type LogEntry = {
+  seq: number;
+  at: string;
+  actor: string;
+  action: string;
+  outcome: 'allow' | 'refuse';
+  code: string | null;
+  subject: string | null;
+  detail: Record<string, unknown>;
+  hash: string;
+};
+
+/**
+ * An entry as the vault log's readers see it. `subject` is the member an
+ * access change is about, or what else the entry names: a secret's path,
+ * the audit log, the vault's own.
+ */
+export function entryView(row: StoredEntry): LogEntry {
+  const { subject, ...detail } = JSON.parse(row.metadata) as Record<string, unknown>;
+  const ids = {
+    projectId: row.projectId,
+    environmentId: row.environmentId,
+    secretId: row.secretId,
+    requestId: row.requestId,
+    operationId: row.operationId,
+    relatedSeq: row.relatedSeq === null ? null : row.relatedSeq.toString(),
+  };
+  return {
+    seq: Number(row.seq),
+    at: new Date(row.occurredAt).toISOString(),
+    actor: row.actor,
+    action: row.action,
+    outcome: row.decision === 'allow' ? 'allow' : 'refuse',
+    code: row.code,
+    subject: row.subjectPrincipal ?? (typeof subject === 'string' ? subject : null),
+    detail: { ...Object.fromEntries(Object.entries(ids).filter(([, value]) => value !== null)), ...detail },
+    hash: row.hash.toString('hex'),
+  };
+}