@coffre/vault 0.9.0 → 0.10.1

package/src/store.ts

@@ -1,7 +1,7 @@
 import { EVERYWHERE, ownsInstance, type InstanceRole, type Scope } from '@coffre/core/access';
 import type { Author, StoredEntry } from '@coffre/core/audit';
 import { ACCESS_ACTIONS, type SecretRef, type WrappedKey } from '@coffre/core/vault';
-import { tablesOf, type Queryable, type Transaction } from '@coffre/db';
+import { prepared, tablesOf, type Queryable, type Transaction } from '@coffre/db';
 import { clockMillis, engineOf, forUpdate, tombstone, truth } from '@coffre/db/dialect';
 import { readGrants, roleColumns, storedRole, type GrantRow } from '@coffre/db/grants';
 import { entryColumns, withinBytes } from '@coffre/db/log';
@@ -61,11 +61,12 @@ export async function boundLockWaits(tx: Transaction, ms: number): Promise<void>
 
 /** The database's clock, now. */
 export async function now(db: Queryable): Promise<number> {
-  const { auditChainHead } = tablesOf(db);
-  const [{ at }] = await db.select({ at: clockMillis(db) }).from(auditChainHead);
+  const [{ at }] = await clock(db);
   return at;
 }
 
+const clock = prepared((db) => db.select({ at: clockMillis(db) }).from(tablesOf(db).auditChainHead));
+
 // --- members --------------------------------------------------------------------
 
 function memberColumns(db: Queryable) {
@@ -101,11 +102,15 @@ function storedChange(change: Partial<Omit<Member, 'principal'>>): Record<string
 }
 
 export async function member(db: Queryable, principal: string): Promise<Member | undefined> {
-  const { vaultMembers } = tablesOf(db);
-  const [row] = await db.select(memberColumns(db)).from(vaultMembers).where(eq(vaultMembers.principal, principal));
+  const [row] = await memberRow(db, { principal });
   return row === undefined ? undefined : memberOf(row as StoredMember);
 }
 
+const memberRow = prepared((db) => {
+  const { vaultMembers } = tablesOf(db);
+  return db.select(memberColumns(db)).from(vaultMembers).where(eq(vaultMembers.principal, sql.placeholder('principal')));
+});
+
 export async function allMembers(db: Queryable): Promise<Member[]> {
   const { vaultMembers } = tablesOf(db);
   return ((await db.select(memberColumns(db)).from(vaultMembers).orderBy(asc(vaultMembers.principal))) as StoredMember[]).map(memberOf);
@@ -312,24 +317,28 @@ export const RELEASE = 'secret.read';
  * several (`secrets`), a read logged once per place.
  */
 export async function releasesSince(db: Queryable, principal: string, after: number): Promise<number> {
+  const [{ n }] = await released(db, { principal, after });
+  return Number(n ?? 0);
+}
+
+const released = prepared((db) => {
   const { auditLog } = tablesOf(db);
   const listed = engineOf(db) === 'postgres'
     ? sql`jsonb_array_length((${auditLog.metadata})::jsonb -> 'secrets')`
     : sql`json_array_length(${auditLog.metadata}, '$.secrets')`;
-  const [{ n }] = await db
+  return db
     .select({ n: sql<string | number | null>`SUM(COALESCE(${listed}, 1))` })
     .from(auditLog)
     .where(
       and(
         eq(auditLog.author, 'vault'),
-        eq(auditLog.actor, principal),
+        eq(auditLog.actor, sql.placeholder('principal')),
         eq(auditLog.action, RELEASE),
         eq(auditLog.decision, 'allow'),
-        gt(auditLog.occurredAt, after),
+        gt(auditLog.occurredAt, sql.placeholder('after')),
       ),
     );
-  return Number(n ?? 0);
-}
+});
 
 /** Rows of the log as the chain's codec reads them: `author` and `decision` are checked by the table. */
 function stored(rows: object[]): StoredEntry[] {
@@ -380,17 +389,6 @@ export async function hashesAt(db: Queryable, seqs: readonly bigint[]): Promise<
 /** How many entries' hashes one query asks for: a checkpoint every five minutes is tens of thousands of a year. */
 const HASHES_AT_ONCE = 5000;
 
-/**
- * Whether every entry from the first through `seq` is there. Seqs are the
- * primary key, so the count is `seq + 1` exactly when none is missing: one
- * pass over the key's index, never the entries.
- */
-export async function complete(db: Queryable, seq: bigint): Promise<boolean> {
-  const { auditLog } = tablesOf(db);
-  const [{ n }] = await db.select({ n: count() }).from(auditLog).where(and(gte(auditLog.seq, 0n), lte(auditLog.seq, seq)));
-  return BigInt(n) === seq + 1n;
-}
-
 /** The entry at `seq`'s hash, or undefined when there is none. */
 export async function hashAt(db: Queryable, seq: bigint): Promise<Buffer | undefined> {
   const { auditLog } = tablesOf(db);
@@ -451,6 +449,13 @@ export async function endedReferences(db: Queryable, seqs: readonly bigint[]): P
 }
 
 /** The project each environment is in: a holder's ids, checked against each other. */
+/** Whether a project of this id is there, and not deleted. */
+export async function projectLive(db: Queryable, id: string): Promise<boolean> {
+  const { projects } = tablesOf(db);
+  const rows = await db.select({ deleted: truth(tombstone(projects.slug)) }).from(projects).where(eq(projects.id, id));
+  return rows.length > 0 && !rows[0]!.deleted;
+}
+
 export async function projectsOfEnvironments(db: Queryable, ids: readonly string[]): Promise<Map<string, string>> {
   if (ids.length === 0) return new Map();
   const { environments } = tablesOf(db);
@@ -481,6 +486,43 @@ export async function secretsByIds(db: Queryable, ids: readonly string[]): Promi
   return new Map(rows.map(({ project, environment, key, ...row }) => [row.secretId, { ...row, path: `${project}/${environment}/${key}` }]));
 }
 
+/**
+ * Each secret's nature, as its current version has it: plain where its
+ * value is stored as it is, sensitive where it is bound so, and otherwise
+ * secret, as is one with no value of its own.
+ */
+export async function natures(db: Queryable, secretIds: readonly string[]): Promise<Map<string, 'plain' | 'secret' | 'sensitive'>> {
+  if (secretIds.length === 0) return new Map();
+  const { secrets, secretVersions } = tablesOf(db);
+  const rows = await db
+    .select({ id: secrets.id, sensitive: secretVersions.sensitive, plain: truth(isNotNull(secretVersions.plaintext)) })
+    .from(secrets)
+    .innerJoin(secretVersions, eq(secretVersions.id, secrets.currentVersionId))
+    .where(inArray(secrets.id, [...new Set(secretIds)]));
+  return new Map(rows.map((row) => [row.id, Boolean(row.sensitive) ? 'sensitive' : Boolean(row.plain) ? 'plain' : 'secret']));
+}
+
+/**
+ * For each version a rewrap would bring back into its secret, its nature
+ * as stored when it is an old value, not the secret's current one; null
+ * for the current one, which a mark wraps again with no value changing.
+ */
+export async function restoredNatures(
+  db: Queryable,
+  items: readonly { secretId: string; from: string }[],
+): Promise<('plain' | 'secret' | 'sensitive' | null)[]> {
+  if (items.length === 0) return [];
+  const { secrets, secretVersions } = tablesOf(db);
+  const [current, versions] = await Promise.all([
+    db.select({ id: secrets.id, version: secrets.currentVersionId }).from(secrets).where(inArray(secrets.id, [...new Set(items.map((item) => item.secretId))])),
+    db.select({ id: secretVersions.id, sensitive: secretVersions.sensitive, plain: truth(isNotNull(secretVersions.plaintext)) }).from(secretVersions)
+      .where(inArray(secretVersions.id, [...new Set(items.map((item) => item.from))])),
+  ]);
+  const currentOf = new Map(current.map((row) => [row.id, row.version]));
+  const natureOf = new Map(versions.map((row) => [row.id, Boolean(row.sensitive) ? 'sensitive' as const : Boolean(row.plain) ? 'plain' as const : 'secret' as const]));
+  return items.map(({ secretId, from }) => (currentOf.get(secretId) === from ? null : natureOf.get(from) ?? 'secret'));
+}
+
 /** The vault's newest entry of any of these actions, allowed, or undefined. */
 export async function latestVaultEntry(db: Queryable, actions: readonly string[]): Promise<StoredEntry | undefined> {
   const { auditLog } = tablesOf(db);
@@ -493,6 +535,82 @@ export async function latestVaultEntry(db: Queryable, actions: readonly string[]
   return row === undefined ? undefined : stored([row])[0];
 }
 
+/**
+ * The vault's newest checkpoint that keeps a tally, allowed, or undefined:
+ * one written since 0.10.1, which names the last entry of the prefix it
+ * signs as related (`related_seq`); those before name none.
+ */
+export async function latestTallied(db: Queryable): Promise<StoredEntry | undefined> {
+  const { auditLog } = tablesOf(db);
+  const [row] = await db
+    .select(entryColumns(db))
+    .from(auditLog)
+    .where(and(eq(auditLog.author, 'vault'), eq(auditLog.action, 'audit.checkpoint'), eq(auditLog.decision, 'allow'), isNotNull(auditLog.relatedSeq)))
+    .orderBy(desc(auditLog.seq))
+    .limit(1);
+  return row === undefined ? undefined : stored([row])[0];
+}
+
+/** The vault's newest `audit.checkpoint` entry, signed or refused, or undefined. */
+export async function newestCheckpointEntry(db: Queryable): Promise<StoredEntry | undefined> {
+  const { auditLog } = tablesOf(db);
+  const [row] = await db
+    .select(entryColumns(db))
+    .from(auditLog)
+    .where(and(eq(auditLog.author, 'vault'), eq(auditLog.action, 'audit.checkpoint')))
+    .orderBy(desc(auditLog.seq))
+    .limit(1);
+  return row === undefined ? undefined : stored([row])[0];
+}
+
+/**
+ * The vault's checkpoints that keep a tally after entry `after` and through
+ * `through`, oldest first, whole: as many as `BATCH_BYTES` of what they say
+ * holds, but always one. A reader asks again after the last.
+ */
+export async function talliedWithin(db: Queryable, after: bigint, through: bigint, limit: number): Promise<StoredEntry[]> {
+  const { auditLog } = tablesOf(db);
+  const tallied = and(
+    eq(auditLog.author, 'vault'), eq(auditLog.action, 'audit.checkpoint'), eq(auditLog.decision, 'allow'), isNotNull(auditLog.relatedSeq),
+    gt(auditLog.seq, after), lte(auditLog.seq, through),
+  );
+  const batch = await withinBytes(db, tallied, limit);
+  if (batch === null) return [];
+  const rows = await db.select(entryColumns(db)).from(auditLog)
+    .where(and(tallied, gte(auditLog.seq, batch.from), lte(auditLog.seq, batch.to))).orderBy(asc(auditLog.seq));
+  return stored(rows);
+}
+
+/** The vault's newest refusal of `action` with `code` after entry `after`, or undefined: one range of the (author, action, seq) index. */
+export async function newestRefusal(db: Queryable, action: string, code: string, after: bigint): Promise<StoredEntry | undefined> {
+  const { auditLog } = tablesOf(db);
+  const [row] = await db
+    .select(entryColumns(db))
+    .from(auditLog)
+    .where(and(eq(auditLog.author, 'vault'), eq(auditLog.action, action), gt(auditLog.seq, after), eq(auditLog.decision, 'deny'), eq(auditLog.code, code)))
+    .orderBy(desc(auditLog.seq))
+    .limit(1);
+  return row === undefined ? undefined : stored([row])[0];
+}
+
+/** Up to `limit` of the vault's checkpoints that keep a tally after entry `after`, oldest first: each one's entry, and the last entry it signs. */
+export async function talliedAfter(db: Queryable, after: bigint, limit: number): Promise<{ seq: bigint; signs: bigint }[]> {
+  const { auditLog } = tablesOf(db);
+  const rows = await db
+    .select({ seq: auditLog.seq, signs: auditLog.relatedSeq })
+    .from(auditLog)
+    .where(and(
+      eq(auditLog.author, 'vault'),
+      eq(auditLog.action, 'audit.checkpoint'),
+      eq(auditLog.decision, 'allow'),
+      isNotNull(auditLog.relatedSeq),
+      gt(auditLog.seq, after),
+    ))
+    .orderBy(asc(auditLog.seq))
+    .limit(limit);
+  return rows.map(({ seq, signs }) => ({ seq, signs: signs! }));
+}
+
 /** The vault's newest allowed access entry about each member who has one. */
 export async function newestAccessEntries(db: Queryable): Promise<Map<string, StoredEntry>> {
   const { auditLog } = tablesOf(db);
@@ -531,6 +649,31 @@ export async function vaultEntriesOf(
   return stored(rows);
 }
 
+/** Which of these secrets' newest versions are sensitive, by the versions' own order. */
+export async function newestSensitive(db: Queryable, secretIds: readonly string[]): Promise<Set<string>> {
+  if (secretIds.length === 0) return new Set();
+  const { secretVersions } = tablesOf(db);
+  const rows = await db
+    .select({ secretId: secretVersions.secretId })
+    .from(secretVersions)
+    .where(and(
+      inArray(secretVersions.secretId, [...new Set(secretIds)]),
+      eq(secretVersions.sensitive, true),
+      sql`${secretVersions.version} = (SELECT max(newest.version) FROM secret_versions newest WHERE newest.secret_id = ${secretVersions.secretId})`,
+    ));
+  return new Set(rows.map((row) => row.secretId));
+}
+
+/** How many grants name `role`: all of them, or those on environments. */
+export async function grantsNaming(db: Queryable, role: string, filter: { onEnvironments?: boolean } = {}): Promise<number> {
+  const { vaultGrants } = tablesOf(db);
+  const rows = await db
+    .select({ count: sql<number | string>`count(*)` })
+    .from(vaultGrants)
+    .where(and(eq(vaultGrants.role, role), filter.onEnvironments === true ? or(isNotNull(vaultGrants.environmentId), isNotNull(vaultGrants.environmentSlug)) : undefined));
+  return Number(rows[0]?.count ?? 0);
+}
+
 /**
  * A version that still holds its wrapped key. A deleted place's versions are
  * erased, their keys emptied: there is nothing left to open, or to try a
@@ -546,7 +689,16 @@ function sealed(wrappedDek: SQLWrapper): SQL {
  * one, as a read through a reference needs. An erased version outside a
  * deleted place is no version.
  */
-export type SecretVersion = { id: string; secret: SecretRef; wrapped: WrappedKey; deleted: boolean; current: boolean };
+export type SecretVersion = {
+  id: string;
+  /** Its secret, `sensitive` as the version was written. */
+  secret: SecretRef;
+  wrapped: WrappedKey;
+  deleted: boolean;
+  current: boolean;
+  /** Whether its secret's newest version is sensitive: what a rewrap of it may not loosen. */
+  newestSensitive: boolean;
+};
 
 export async function versions(db: Queryable, ids: readonly string[]): Promise<SecretVersion[]> {
   if (ids.length === 0) return [];
@@ -567,8 +719,10 @@ export async function versions(db: Queryable, ids: readonly string[]): Promise<S
       wrappedDek: secretVersions.wrappedDek,
       deleted: truth(or(tombstone(environments.slug), tombstone(projects.slug))!),
       currentVersionId: secrets.currentVersionId,
+      sensitive: secretVersions.sensitive,
       // The newest by the versions' own order: the app may write `current_version_id`, never a version.
       newest: sql<number | string>`(SELECT max(newest.version) FROM secret_versions newest WHERE newest.secret_id = ${secretVersions.secretId})`,
+      newestSensitive: sql<boolean | number>`(SELECT newest.sensitive FROM secret_versions newest WHERE newest.secret_id = ${secretVersions.secretId} ORDER BY newest.version DESC LIMIT 1)`,
     })
     .from(secretVersions)
     .innerJoin(secrets, eq(secrets.id, secretVersions.secretId))
@@ -584,6 +738,7 @@ export async function versions(db: Queryable, ids: readonly string[]): Promise<S
       secretId: row.secretId,
       version: row.version,
       path: `${row.project}/${row.environment}/${row.key}`,
+      sensitive: row.sensitive,
     },
     wrapped: {
       kekProvider: row.kekProvider,
@@ -592,5 +747,7 @@ export async function versions(db: Queryable, ids: readonly string[]): Promise<S
       bytes: row.wrappedDek.toString('base64'),
     },
     current: row.currentVersionId === row.id && Number(row.newest) === row.version,
+    // SQLite answers a subquery's boolean as a number.
+    newestSensitive: Boolean(row.newestSensitive),
   }));
 }

package/src/tally.ts

@@ -0,0 +1,241 @@
+import { createHash } from 'node:crypto';
+
+import type { StoredEntry } from '@coffre/core/audit';
+import type { AccessFault, Checkpoint, LogHead } from '@coffre/core/vault';
+
+import { KeyAccounting, type AccountingState } from './accounting.ts';
+import { forward } from './log.ts';
+import { apply, placeKey, type LoggedMember, type Replayed } from './replay.ts';
+import { ACCESS_ACTIONS, type GrantRow } from './store.ts';
+
+/**
+ * What a walk of the vault's entries from the first has gathered by some
+ * entry: all a walk from there needs to go on as if it had started at the
+ * first. A checkpoint keeps the tally of the prefix it signs, so that the
+ * next checkpoint, and every verification, start from it and read only the
+ * entries since (docs/architecture.md, "The tally").
+ *
+ * - `entries`: the vault's entries so far;
+ * - `keys`: the vault's log keys, in the order its entries moved through
+ *   them, which only moves forward (`forward` in log.ts);
+ * - `accounting`: the key batches still under way, and the first fault in
+ *   their entries;
+ * - `access`: who the log says is a member, what each holds, and each one's
+ *   newest access entry, which their row must name;
+ * - `replayFault`: the first access entry about someone never admitted.
+ *
+ * The faults are kept, once found, as a walk from the first entry would
+ * find them again each time.
+ */
+export type Tally = {
+  entries: number;
+  keys: string[];
+  accounting: AccountingState;
+  access: AccessTally;
+  replayFault: AccessFault | null;
+};
+
+/** Members and grants as the log says they are, and each member's newest access entry, as plain JSON. */
+export type AccessTally = {
+  members: (Omit<LoggedMember, 'accessSeq'> & { accessSeq: number })[];
+  grants: GrantRow[];
+  newest: [principal: string, seq: number][];
+};
+
+/**
+ * A tally as a checkpoint's entry holds it. Members and grants change far
+ * less often than every five minutes, so `access` is written whole only
+ * when it changed since the tally resumed from; otherwise the entry names
+ * the checkpoint entry that holds it (`at`). Either way with its digest.
+ */
+export type StoredTally = Omit<Tally, 'access'> & { v: typeof TALLY_VERSION; access: { digest: string } & ({ at: number } | AccessTally) };
+
+/**
+ * What a tally keeps, as 0.10.1 wrote it. A release that keeps more, or
+ * less, writes another version, and compares a tally of this one on what
+ * this one kept: a walk from the first entry passes every tally ever
+ * written, and an honest one must still match. A release rolled back to
+ * reads no tally newer than its own, and refuses the checkpoints that
+ * keep one: going back across a version is not a way back.
+ */
+export const TALLY_VERSION = 1;
+
+/**
+ * A checkpoint as the vault's entry holds it: the signed prefix, its
+ * tally, and the lap of the rehash of the past under way (`scrub`): the
+ * prefix it rehashes to, signed when the lap began, and the last entry it
+ * rehashed. Null between laps.
+ */
+export type TalliedCheckpoint = Checkpoint & { tally: StoredTally; scrub: { at: LogHead; end: LogHead } | null };
+
+/** Before the first entry. */
+export const EMPTY_TALLY: Tally = {
+  entries: 0,
+  keys: [],
+  accounting: { intents: [], fault: null },
+  access: { members: [], grants: [], newest: [] },
+  replayFault: null,
+};
+
+/** The digest of what `access` says, over its canonical form. */
+export function accessDigest(access: AccessTally): string {
+  return createHash('sha256').update(canonical(access)).digest('hex');
+}
+
+/**
+ * What two tallies are compared by, so that they match whatever order
+ * their maps were built in: the members and grants by their digest, which
+ * a stretch passing many checkpoints computes once a change; and a fault by
+ * where it was found, since the words for it may change from one release
+ * to the next.
+ */
+function tallyKey({ accounting, entries, keys, replayFault }: Omit<Tally, 'access'>, digest: string): string {
+  return canonical({ entries, keys, replayFault, accounting: { ...accounting, fault: accounting.fault?.failedAtSeq ?? null }, access: digest });
+}
+
+/**
+ * A tally a walk must come to: the one a checkpoint keeps, `entry`, of the
+ * prefix through `through`; or why that checkpoint's tally cannot be read.
+ */
+export type Expected = { entry: bigint; through: bigint; key: string } | { entry: bigint; through: bigint; unreadable: string };
+
+/**
+ * What a walk must come to at a checkpoint, from the tally it keeps: its
+ * members and grants by the digest it keeps of them, never read.
+ */
+export function expectedKey(stored: StoredTally): string {
+  return tallyKey(stored, stored.access.digest);
+}
+
+/**
+ * The vault's entries walked, oldest first, each after its MAC was checked,
+ * gathered into what the checks after the walk need: the tally it started
+ * from, carried on.
+ */
+export class Walk {
+  readonly accounting: KeyAccounting;
+  readonly replayed: Replayed;
+  /** Each member's newest allowed access entry, by seq. */
+  readonly newestAccess: Map<string, bigint>;
+  /** The first access entry the replay could not apply. */
+  replayFault: AccessFault | null;
+  /** The vault's entries so far, those before the walk included. */
+  entries: number;
+  /** The vault's log keys, as the log moved through them. */
+  keys: readonly string[];
+  /** The checkpoints walked, each to be checked against its signature and the prefix it signed once the walk ends: what it signed, and nothing it keeps beside. */
+  readonly checkpoints: { entry: { seq: bigint; keyId: string; relatedSeq: bigint | null }; checkpoint: Checkpoint }[] = [];
+
+  /** The tallies the walk must come to as it passes them, oldest first (`expect`). */
+  #expected: Expected[] = [];
+  /** The first it did not come to, and why. */
+  mismatch: { entry: bigint; reason: string } | null = null;
+  /** The digest of the members and grants as the walk has them, until an access entry changes them. */
+  #digest: string | null = null;
+
+  /** The digest of the members and grants as the walk has them: the tally's it started from, until an access entry. */
+  digest(): string {
+    return (this.#digest ??= accessDigest(this.tally().access));
+  }
+
+  /** The tally but for its members and grants, which `digest` stands for. */
+  #unaccessed(): Omit<Tally, 'access'> {
+    return { entries: this.entries, keys: [...this.keys], accounting: this.accounting.state(), replayFault: this.replayFault };
+  }
+
+  /** `digest` is that of `from`'s members and grants, when the caller has it: a beat with no access entry hashes none. */
+  constructor(from: Tally, digest?: string) {
+    this.#digest = digest ?? null;
+    this.accounting = new KeyAccounting(from.accounting);
+    this.replayed = {
+      members: new Map(from.access.members.map((member) => [member.principal, { ...member, accessSeq: BigInt(member.accessSeq) }])),
+      held: new Map(),
+    };
+    for (const grant of from.access.grants) {
+      const held = this.replayed.held.get(grant.principal) ?? new Map<string, GrantRow>();
+      this.replayed.held.set(grant.principal, held);
+      held.set(placeKey(grant), { ...grant });
+    }
+    this.newestAccess = new Map(from.access.newest.map(([principal, seq]) => [principal, BigInt(seq)]));
+    this.replayFault = from.replayFault;
+    this.entries = from.entries;
+    this.keys = from.keys;
+  }
+
+  /**
+   * Hold the walk to these tallies, each as the walk stands once it has
+   * read every entry through the prefix's end: before the vault's next
+   * entry, since only the vault's change a tally, or at `finish`.
+   */
+  expect(expected: readonly Expected[]): void {
+    this.#expected = [...expected].sort((a, b) => (a.through < b.through ? -1 : 1));
+  }
+
+  /** The tallies expected through `through`, held to the walk. */
+  finish(through: bigint): void {
+    this.#reach(through + 1n);
+  }
+
+  #reach(before: bigint): void {
+    while (this.#expected.length > 0 && this.#expected[0]!.through < before) {
+      const expected = this.#expected.shift()!;
+      if (this.mismatch !== null) continue;
+      if ('unreadable' in expected) this.mismatch = { entry: expected.entry, reason: expected.unreadable };
+      else if (tallyKey(this.#unaccessed(), this.digest()) !== expected.key) {
+        this.mismatch = { entry: expected.entry, reason: 'the tally this checkpoint keeps does not follow from the log before it' };
+      }
+    }
+  }
+
+  /**
+   * One of the vault's entries, its MAC checked, in the log's order: a
+   * fault when it is under a key the vault had moved past (`forward`).
+   */
+  add(entry: StoredEntry, current: string): { failedAtSeq: bigint; reason: string } | null {
+    this.#reach(entry.seq);
+    const moved = forward([entry], this.keys, current);
+    if ('failedAtSeq' in moved) return moved;
+    this.keys = moved.keys;
+    this.entries += 1;
+    this.accounting.add(entry);
+    if (entry.decision !== 'allow') return null;
+    if (ACCESS.has(entry.action)) {
+      this.#digest = null;
+      this.replayFault ??= apply(this.replayed, entry);
+      if (entry.subjectPrincipal !== null) this.newestAccess.set(entry.subjectPrincipal, entry.seq);
+    } else if (entry.action === CHECKPOINT) {
+      const { seq, hash, signedAt, keyId, signature } = JSON.parse(entry.metadata) as Checkpoint;
+      this.checkpoints.push({ entry: { seq: entry.seq, keyId: entry.keyId, relatedSeq: entry.relatedSeq }, checkpoint: { seq, hash, signedAt, keyId, signature } });
+    }
+    return null;
+  }
+
+  /** Where the walk stands, to resume from. */
+  tally(): Tally {
+    const byPrincipal = <T>(entries: Iterable<[string, T]>) => [...entries].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    return {
+      entries: this.entries,
+      keys: [...this.keys],
+      accounting: this.accounting.state(),
+      access: {
+        members: byPrincipal(this.replayed.members).map(([, member]) => ({ ...member, accessSeq: Number(member.accessSeq) })),
+        grants: byPrincipal(this.replayed.held).flatMap(([, held]) => byPrincipal(held).map(([, grant]) => grant)),
+        newest: byPrincipal(this.newestAccess).map(([principal, seq]) => [principal, Number(seq)]),
+      },
+      replayFault: this.replayFault,
+    };
+  }
+}
+
+/** The action of the vault's entry that signs a prefix of the log. */
+export const CHECKPOINT = 'audit.checkpoint';
+
+const ACCESS = new Set<string>(ACCESS_ACTIONS);
+
+/** JSON with every object's keys sorted: one text for one value, however it was built. */
+function canonical(value: unknown): string {
+  return JSON.stringify(value, (_, inner: unknown) =>
+    inner !== null && typeof inner === 'object' && !Array.isArray(inner)
+      ? Object.fromEntries(Object.entries(inner).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)))
+      : inner);
+}