@coffre/vault 0.1.11 → 0.1.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coffre/vault",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "description": "coffre's vault: keys, grants and members, in the database the app uses, as a Cloudflare Worker or on Node.",
   "license": "MIT",
   "repository": {
@@ -36,8 +36,8 @@
   },
   "dependencies": {
     "drizzle-orm": "0.45.2",
-    "@coffre/db": "0.1.11",
-    "@coffre/core": "0.1.11"
+    "@coffre/core": "0.1.13",
+    "@coffre/db": "0.1.13"
   },
   "devDependencies": {
     "@types/node": "26.1.1",

package/src/accounting.ts

@@ -1,9 +1,5 @@
 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']);
 
@@ -13,54 +9,61 @@ 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);
+/**
+ * Every key operation's intent and its outcomes, entry by entry, oldest
+ * first, as the full check reads the vault's entries (`add`); then what is
+ * still open (`result`). The chain can hold while a process died between an
+ * intent and its outcomes: only a missed deadline is a fault.
+ */
+export class KeyAccounting {
+  readonly #intents = new Map<bigint, Intent>();
+  readonly #ids = new Set<string>();
+  #fault: Extract<Accounting, { ok: false }> | null = null;
+
+  add(entry: StoredEntry): void {
+    if (this.#fault !== null || entry.author !== 'vault') return;
+    const broken = (reason: string) => {
+      this.#fault = { ok: false, failedAtSeq: Number(entry.seq), reason };
+    };
+    if (entry.action === 'key.intent') {
+      const parsed = parseIntent(entry);
+      if (typeof parsed === 'string') return broken(parsed);
+      if (this.#ids.has(parsed.intentId)) return broken('key intent repeats an operation identity');
+      this.#ids.add(parsed.intentId);
+      if (parsed.keys.length > 0) this.#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(parsed);
+      const intent = this.#intents.get(parsed.relatedSeq);
+      const key = intent?.keys[parsed.item];
+      if (intent === undefined || key === undefined || intent.seen.has(parsed.item)) {
+        return broken('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('key outcome belongs to another operation');
       }
+      if (parsed.secretId !== key.secretId || parsed.version !== key.version || parsed.subject !== key.subject) {
+        return broken('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) this.#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);
+
+  /** The first fault, or the batches still under way at `at`: live calls can finish after the snapshot. */
+  result(at: number): Accounting {
+    if (this.#fault !== null) return this.#fault;
+    const intents = [...this.#intents.values()];
+    const overdue = intents.filter((intent) => intent.expiresAt <= at).sort((a, b) => a.expiresAt - b.expiresAt);
+    if (overdue.length === 0) return { ok: true, pending: intents.length };
+    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 { ok: false, failedAtSeq: Number(overdue[0]!.entry.seq), reason };
+  }
 }
 
 function parseIntent(entry: StoredEntry): ParsedIntent | string {

package/src/log.ts

@@ -38,7 +38,8 @@ export function further(a: Anchor, b: Anchor): Anchor {
   return b.nextSeq > a.nextSeq ? b : a;
 }
 
-export const VERIFY_BATCH = 1000;
+/** Entries read at once: a few megabytes, well within a Worker's memory, and a fifth of the round trips of 1000. */
+export const VERIFY_BATCH = 5000;
 
 type Verified = { verification: LogVerification; anchor: Anchor };
 
@@ -55,13 +56,15 @@ type Verified = { verification: LogVerification; anchor: Anchor };
  * 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.
+ * as does the first view after a start, which has no anchor. `onBatch` sees
+ * each batch once it has verified, for checks that read the same entries.
  */
 export async function verifyChain(
   db: Queryable,
   logKeys: readonly LogKey[],
   shown: readonly StoredEntry[],
   anchor: Anchor,
+  onBatch: (batch: readonly StoredEntry[]) => void = () => {},
 ): Promise<Verified> {
   const broken = (failedAtSeq: bigint, reason: string): Verified => ({
     verification: { ok: false, failedAtSeq: Number(failedAtSeq), reason: withCause(reason) },
@@ -86,6 +89,7 @@ export async function verifyChain(
     if (!result.ok) return broken(result.failedAtSeq, result.reason);
     const moved = forward(batch, verified.vaultKeys, logKeys[0].keyId);
     if ('failedAtSeq' in moved) return broken(moved.failedAtSeq, moved.reason);
+    onBatch(batch);
     verified = {
       nextSeq: result.nextSeq,
       hash: result.head,
@@ -104,7 +108,7 @@ export async function verifyChain(
  * even one that leaked, verifies what came before the rotation, and nothing
  * after it.
  */
-function forward(
+export function forward(
   entries: readonly StoredEntry[],
   keys: readonly string[],
   current: string,
@@ -130,7 +134,7 @@ function forward(
  * signing key, or from its KEK when it has none. The second is the one an
  * operator can fix.
  */
-function withCause(reason: string): string {
+export function withCause(reason: string): string {
   if (!/^written under vault:\S+, a key this verifier does not hold$/.test(reason)) return reason;
   return `${reason}: either it is forged, or the vault wrote it under another vault key or signing key, which must stay configured: a vault key that was replaced stays in the vault's config, in previousKeks`;
 }

package/src/replay.ts

@@ -1,13 +1,10 @@
 import type { StoredEntry } from '@coffre/core/audit';
 import type { AccessFault, FaultGrant } from '@coffre/core/vault';
-import type { Queryable } from '@coffre/db';
 
-import { ACCESS_ACTIONS, allMembers, grants, vaultEntriesOf, type GrantRow, type Member, type Place } from './store.ts';
+import { ACCESS_ACTIONS, type GrantRow, type Member, type Place } from './store.ts';
 
 export { ACCESS_ACTIONS };
 
-const BATCH = 1000;
-
 /**
  * Why the members and grants in the database do not follow from the
  * vault's entries, or null when they do; `describeAccessFault` words it.
@@ -17,25 +14,15 @@ const BATCH = 1000;
  * written around the vault: a grant inserted with the database's own login,
  * a removal undone.
  *
- * Call it after the chain is verified, in the same snapshot, so every entry
- * it replays carries the vault's MAC.
+ * `state` is the allowed access entries replayed (`apply`), each after its
+ * MAC was checked, in the snapshot `rows` and `stored` were read in.
  *
  * Grants are compared as they are live at `at`. Clearing one that has
  * lapsed changes nothing anyone holds, so it is not logged.
  */
-export async function replay(db: Queryable, at: number): Promise<AccessFault | null> {
-  const state: Replayed = { members: new Map(), held: new Map() };
-  for (let after = -1n; ; ) {
-    const batch = await vaultEntriesOf(db, ACCESS_ACTIONS, after, BATCH);
-    for (const row of batch) {
-      const fault = apply(state, row);
-      if (fault !== null) return fault;
-    }
-    if (batch.length < BATCH) break;
-    after = batch[batch.length - 1].seq;
-  }
+export function replayFault(state: Replayed, rows: readonly Member[], storedGrants: readonly GrantRow[], at: number): AccessFault | null {
   const { members, held } = state;
-  const stored = new Map((await allMembers(db)).map((member) => [member.principal, member]));
+  const stored = new Map(rows.map((member) => [member.principal, member]));
   for (const principal of [...new Set([...stored.keys(), ...members.keys()])].sort()) {
     const [inStore, inLog] = [stored.get(principal), members.get(principal)];
     if (inLog === undefined) return { kind: 'unlogged-member', principal };
@@ -46,7 +33,7 @@ export async function replay(db: Queryable, at: number): Promise<AccessFault | n
 
   const live = (grant: GrantRow) => grant.expiresAt === null || grant.expiresAt > at;
   const logged = new Set([...held.values()].flatMap((grantsOf) => [...grantsOf.values()]).filter(live).map(grantKey));
-  const inStore = new Set((await grants(db)).filter(live).map(grantKey));
+  const inStore = new Set(storedGrants.filter(live).map(grantKey));
   const extra = [...inStore].sort().find((grant) => !logged.has(grant));
   if (extra !== undefined) return { kind: 'unlogged-grant', grant: faultGrant(extra) };
   const missing = [...logged].sort().find((grant) => !inStore.has(grant));

package/src/store.ts

@@ -287,6 +287,35 @@ export async function entriesFrom(db: Queryable, fromSeq: bigint, limit: number)
   return stored(rows);
 }
 
+/** Up to `limit` of the vault's entries after `afterSeq`, oldest first: every one, whatever its action or decision. */
+export async function vaultEntriesAfter(db: Queryable, afterSeq: bigint, limit: number): Promise<StoredEntry[]> {
+  const { auditLog } = tablesOf(db);
+  const rows = await db
+    .select(entryColumns(db))
+    .from(auditLog)
+    .where(and(eq(auditLog.author, 'vault' satisfies Author), gt(auditLog.seq, afterSeq)))
+    .orderBy(asc(auditLog.seq))
+    .limit(limit);
+  return stored(rows);
+}
+
+/** The hash of the entry at each of `seqs` the log holds, by seq. */
+export async function hashesAt(db: Queryable, seqs: readonly bigint[]): Promise<Map<bigint, Buffer>> {
+  const { auditLog } = tablesOf(db);
+  const hashes = new Map<bigint, Buffer>();
+  for (let from = 0; from < seqs.length; from += HASHES_AT_ONCE) {
+    const rows = await db
+      .select({ seq: auditLog.seq, hash: auditLog.hash })
+      .from(auditLog)
+      .where(inArray(auditLog.seq, seqs.slice(from, from + HASHES_AT_ONCE)));
+    for (const { seq, hash } of rows) hashes.set(seq, hash);
+  }
+  return hashes;
+}
+
+/** 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;
+
 /** 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);