@coffre/vault 0.1.14 → 0.1.16

package/dist/cloudflare.js

@@ -1,5 +1,5 @@
 import { a as verifyCheckpoint, i as checkpointMessage, n as KekUnavailableError, o as derivedSigningKey, r as awsKms, s as resolveVaultConfig, t as KekBadClaimError } from "./src-1yVV2L0_.js";
-import { n as prepareVault, t as openVault } from "./vault-3O-ynZPg.js";
+import { n as prepareVault, t as openVault } from "./vault-BexBMpZL.js";
 import { createDatabase } from "@coffre/db";
 import { HyperdrivePool, postgres } from "@coffre/db/hyperdrive";
 import { WorkerEntrypoint } from "cloudflare:workers";

package/dist/node.js

@@ -1,5 +1,5 @@
 import { a as verifyCheckpoint, i as checkpointMessage, n as KekUnavailableError, o as derivedSigningKey, r as awsKms, s as resolveVaultConfig, t as KekBadClaimError } from "./src-1yVV2L0_.js";
-import { n as prepareVault, t as openVault } from "./vault-3O-ynZPg.js";
+import { n as prepareVault, t as openVault } from "./vault-BexBMpZL.js";
 import { chmodSync, existsSync, lstatSync, rmSync } from "node:fs";
 import { Agent, createServer, request } from "node:http";
 import { openDatabase } from "@coffre/db/connect";

package/dist/{vault-3O-ynZPg.js → vault-BexBMpZL.js}

@@ -7,7 +7,7 @@ import { GENESIS_HASH, deriveLogKey, verifyEntries } from "@coffre/core/audit";
 import { checkContext } from "@coffre/core/envelope";
 import { SNAPSHOT, clockMillis, engineOf, forUpdate, isUniqueViolation } from "@coffre/db/dialect";
 import { appendEntries, lockLogHead } from "@coffre/db/log";
-import { and, asc, count, desc, eq, gt, gte, inArray, isNull, lt, sql } from "drizzle-orm";
+import { and, asc, count, desc, eq, gt, gte, inArray, isNull, lt, lte, sql } from "drizzle-orm";
 //#region src/accounting.ts
 const KEY_ACTIONS = /* @__PURE__ */ new Set([
 	"secret.read",
@@ -356,6 +356,16 @@ async function hashesAt(db, seqs) {
 }
 /** How many entries' hashes one query asks for: a checkpoint every five minutes is tens of thousands of a year. */
 const HASHES_AT_ONCE = 5e3;
+/**
+* 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.
+*/
+async function complete(db, seq) {
+	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. */
 async function hashAt(db, seq) {
 	const { auditLog } = tablesOf(db);
@@ -856,6 +866,12 @@ const TAMPERED_SUBJECT = "this member's record failed the vault's integrity chec
 const CHECKPOINT = "audit.checkpoint";
 /** Who asks for checkpoints: the app's scheduled job. */
 const SCHEDULER = "system:coffre-scheduler";
+/**
+* How often a checkpoint recomputes the chain from its first entry: the
+* first of each hour, by the vault's clock. The others resume from the
+* prefix the last one signed (`#recompute`).
+*/
+const FULL_RECOMPUTE_MS = 36e5;
 /** A refusal and the entries that record it. */
 var Refused = class {
 	refusal;
@@ -898,6 +914,10 @@ const MESSAGES = {
 	wrong_kek: "this vault's key does not open the data it holds",
 	tampered: "this member's record failed the vault's integrity check"
 };
+/** The credential a CI run's request came in on, as its entries record it: copied, never decided on. */
+function traced(correlation) {
+	return correlation.credentialId == null ? {} : { credentialId: correlation.credentialId };
+}
 /**
 * The one implementation of `Vault`. Every decision is one transaction on
 * the shared database: it locks the rows of the members it is about, reads
@@ -1319,7 +1339,8 @@ var VaultService = class {
 				requestId: input.requestId,
 				metadata: JSON.stringify({
 					...detail,
-					secretVersionId: id
+					secretVersionId: id,
+					...traced(input)
 				})
 			};
 			return {
@@ -1408,6 +1429,7 @@ var VaultService = class {
 						operation: action,
 						expiresAt: at + this.#prepared.options.keyBudgetMs + 2 * LOCK_TIMEOUT_MS,
 						...call.input.purpose === void 0 ? {} : { purpose: call.input.purpose },
+						...traced(call.input),
 						keys: secrets.map((secret, item) => ({
 							item,
 							subject: secret.path,
@@ -2008,16 +2030,53 @@ var VaultService = class {
 		const row = await latestVaultEntry(db, [CHECKPOINT]);
 		return row === void 0 ? null : {
 			checkpoint: JSON.parse(row.metadata),
-			seq: row.seq
+			seq: row.seq,
+			keyId: row.keyId
 		};
 	}
+	/**
+	* The chain recomputed to its last entry, for a checkpoint to sign: from
+	* its first entry at the first checkpoint of each hour, and otherwise from
+	* the prefix the last checkpoint signed, if that one was signed this hour.
+	*
+	* Resuming never signs what the vault did not recompute. The vault
+	* recomputed the last checkpoint's prefix itself, from entry 0 at the
+	* hour's first checkpoint and onward at each one since, and the entry
+	* that holds it is the first one checked again, by its MAC. The next
+	* signature extends that same chain.
+	*
+	* What resuming does not do is recompute the rows of that prefix again.
+	* They can change while the hash stored at its end stays, so it first
+	* checks the two things that are cheap: that hash is still there, which a
+	* prefix rewritten and chained again changes, and every entry of the
+	* prefix is, which a cut changes. Either failing, it recomputes from entry
+	* 0, which names what broke. An entry edited in place, its hash left as
+	* it was, is the one change left to the next full pass, within the hour.
+	*
+	* It resumes only from a checkpoint under the key the vault writes with
+	* now: once the log reaches that key, no other writes again (`forward`).
+	* After a rotation, the next pass is full.
+	*/
+	async #recompute(tx) {
+		const { logKeys } = this.#prepared;
+		const latest = await this.#latest(tx);
+		const hour = (ms) => Math.floor(ms / FULL_RECOMPUTE_MS);
+		if (!(latest !== null && latest.keyId === logKeys[0].keyId && latest.seq === BigInt(latest.checkpoint.seq) + 1n && hour(Date.parse(latest.checkpoint.signedAt)) === hour(await this.#now(tx)) && await carries(tx, latest.checkpoint) && await complete(tx, BigInt(latest.checkpoint.seq)))) return verifyChain(tx, logKeys, [], UNVERIFIED);
+		const { seq, hash } = latest.checkpoint;
+		return verifyChain(tx, logKeys, [], {
+			nextSeq: BigInt(seq) + 1n,
+			hash: Buffer.from(hash, "hex"),
+			vaultEntries: 0,
+			vaultKeys: [logKeys[0].keyId]
+		});
+	}
 	async checkpoint() {
 		await this.#settled();
 		const { wrongKek } = this.#prepared;
 		const found = [];
 		const whole = await this.#db.transaction(async (tx) => {
 			await this.#sweep(tx, found);
-			return verifyChain(tx, this.#prepared.logKeys, [], UNVERIFIED);
+			return this.#recompute(tx);
 		}, SNAPSHOT);
 		return this.#decide([], async (d) => {
 			for (const entry of found) if (!d.reports.includes(entry)) d.reports.push(entry);
@@ -2339,6 +2398,7 @@ const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
 function validateCorrelation(input) {
 	if (input.requestId != null) validateText(input.requestId);
 	if (input.operationId != null && (typeof input.operationId !== "string" || !UUID.test(input.operationId))) throw new Error(`operationId must be a lowercase UUID, got: ${String(input.operationId)}`);
+	if (input.credentialId != null && (typeof input.credentialId !== "string" || !UUID.test(input.credentialId))) throw new Error(`credentialId must be a lowercase UUID, got: ${String(input.credentialId)}`);
 }
 /** Validate the entire batch before any provider sees a key. */
 function validateItems(items, field) {
@@ -2399,7 +2459,8 @@ function keyEntry(action, principal, secret, decision, code, correlation, detail
 			subject: secret.path,
 			...action === "key.wrap" ? { secretId: secret.secretId } : {},
 			version: secret.version,
-			...detail
+			...detail,
+			...traced(correlation)
 		})
 	};
 }
@@ -2417,9 +2478,13 @@ function accessEntry(actor, action, principal, decision, correlation, detail, co
 		subjectPrincipal: PRINCIPAL.test(principal) ? principal : null,
 		operationId: correlation.operationId ?? null,
 		requestId: correlation.requestId ?? null,
-		metadata: JSON.stringify(PRINCIPAL.test(principal) ? detail : {
+		metadata: JSON.stringify(PRINCIPAL.test(principal) ? {
+			...detail,
+			...traced(correlation)
+		} : {
 			subject: principal,
-			...detail
+			...detail,
+			...traced(correlation)
 		})
 	};
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coffre/vault",
-  "version": "0.1.14",
+  "version": "0.1.16",
   "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/core": "0.1.14",
-    "@coffre/db": "0.1.14"
+    "@coffre/core": "0.1.16",
+    "@coffre/db": "0.1.16"
   },
   "devDependencies": {
     "@types/node": "26.1.1",

package/src/store.ts

@@ -2,7 +2,7 @@ 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 { clockMillis, engineOf, forUpdate } from '@coffre/db/dialect';
-import { and, asc, count, desc, eq, gt, gte, inArray, isNull, lt, sql } from 'drizzle-orm';
+import { and, asc, count, desc, eq, gt, gte, inArray, isNull, lt, lte, sql } from 'drizzle-orm';
 
 /**
  * Every query the vault makes, and the only code in it that holds them.
@@ -316,6 +316,17 @@ 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);

package/src/vault.ts

@@ -179,6 +179,13 @@ const CHECKPOINT = 'audit.checkpoint';
 /** Who asks for checkpoints: the app's scheduled job. */
 const SCHEDULER = 'system:coffre-scheduler';
 
+/**
+ * How often a checkpoint recomputes the chain from its first entry: the
+ * first of each hour, by the vault's clock. The others resume from the
+ * prefix the last one signed (`#recompute`).
+ */
+const FULL_RECOMPUTE_MS = 60 * 60 * 1000;
+
 /** A refusal and the entries that record it. */
 class Refused {
   readonly refusal: Refusal;
@@ -258,7 +265,12 @@ type Decision = {
 type KeyAction = 'secret.read' | 'key.wrap' | 'key.rewrap';
 
 /** What ties an entry to the app's request, and to the one action it is part of. */
-type Correlation = { requestId?: string | null; operationId?: string | null };
+type Correlation = { requestId?: string | null; operationId?: string | null; credentialId?: string | null };
+
+/** The credential a CI run's request came in on, as its entries record it: copied, never decided on. */
+function traced(correlation: Correlation): { credentialId?: string } {
+  return correlation.credentialId == null ? {} : { credentialId: correlation.credentialId };
+}
 
 /** Why a member's row is not the one the vault last wrote; rows.ts. */
 type Fault = 'mac' | 'stale';
@@ -707,7 +719,7 @@ class VaultService implements Vault {
         if (version === undefined) return {
           actor: input.principal, action, decision: 'deny', code: 'bad_claim',
           operationId: input.operationId, requestId: input.requestId,
-          metadata: JSON.stringify({ ...detail, secretVersionId: id }),
+          metadata: JSON.stringify({ ...detail, secretVersionId: id, ...traced(input) }),
         };
         return { ...keyEntry(action, input.principal, version.secret, 'deny', 'bad_claim', input, detail), secretVersionId: id };
       }));
@@ -817,6 +829,7 @@ class VaultService implements Vault {
             // Member and outcome locks can each wait before accounting is overdue.
             expiresAt: at + this.#prepared.options.keyBudgetMs + 2 * LOCK_TIMEOUT_MS,
             ...(call.input.purpose === undefined ? {} : { purpose: call.input.purpose }),
+            ...traced(call.input),
             keys: secrets.map((secret, item) => ({ item, subject: secret.path, secretId: secret.secretId, version: secret.version })),
           }),
         }]);
@@ -1374,9 +1387,49 @@ class VaultService implements Vault {
   // --- checkpoints and the log --------------------------------------------------
 
   /** The last checkpoint the vault signed, and the entry that holds it: its newest allowed `audit.checkpoint`. */
-  async #latest(db: Queryable): Promise<{ checkpoint: Checkpoint; seq: bigint } | null> {
+  async #latest(db: Queryable): Promise<{ checkpoint: Checkpoint; seq: bigint; keyId: string } | null> {
     const row = await store.latestVaultEntry(db, [CHECKPOINT]);
-    return row === undefined ? null : { checkpoint: JSON.parse(row.metadata) as Checkpoint, seq: row.seq };
+    return row === undefined ? null : { checkpoint: JSON.parse(row.metadata) as Checkpoint, seq: row.seq, keyId: row.keyId };
+  }
+
+  /**
+   * The chain recomputed to its last entry, for a checkpoint to sign: from
+   * its first entry at the first checkpoint of each hour, and otherwise from
+   * the prefix the last checkpoint signed, if that one was signed this hour.
+   *
+   * Resuming never signs what the vault did not recompute. The vault
+   * recomputed the last checkpoint's prefix itself, from entry 0 at the
+   * hour's first checkpoint and onward at each one since, and the entry
+   * that holds it is the first one checked again, by its MAC. The next
+   * signature extends that same chain.
+   *
+   * What resuming does not do is recompute the rows of that prefix again.
+   * They can change while the hash stored at its end stays, so it first
+   * checks the two things that are cheap: that hash is still there, which a
+   * prefix rewritten and chained again changes, and every entry of the
+   * prefix is, which a cut changes. Either failing, it recomputes from entry
+   * 0, which names what broke. An entry edited in place, its hash left as
+   * it was, is the one change left to the next full pass, within the hour.
+   *
+   * It resumes only from a checkpoint under the key the vault writes with
+   * now: once the log reaches that key, no other writes again (`forward`).
+   * After a rotation, the next pass is full.
+   */
+  async #recompute(tx: Queryable): Promise<{ verification: LogVerification; anchor: Anchor }> {
+    const { logKeys } = this.#prepared;
+    const latest = await this.#latest(tx);
+    const hour = (ms: number) => Math.floor(ms / FULL_RECOMPUTE_MS);
+    const resumable =
+      latest !== null &&
+      latest.keyId === logKeys[0].keyId &&
+      latest.seq === BigInt(latest.checkpoint.seq) + 1n &&
+      hour(Date.parse(latest.checkpoint.signedAt)) === hour(await this.#now(tx)) &&
+      (await carries(tx, latest.checkpoint)) &&
+      (await store.complete(tx, BigInt(latest.checkpoint.seq)));
+    if (!resumable) return verifyChain(tx, logKeys, [], UNVERIFIED);
+    const { seq, hash } = latest.checkpoint;
+    const signed: Anchor = { nextSeq: BigInt(seq) + 1n, hash: Buffer.from(hash, 'hex'), vaultEntries: 0, vaultKeys: [logKeys[0].keyId] };
+    return verifyChain(tx, logKeys, [], signed);
   }
 
   async checkpoint(): Promise<Outcome<{ checkpoint: Checkpoint }>> {
@@ -1386,14 +1439,14 @@ class VaultService implements Vault {
     const { wrongKek } = this.#prepared;
     // Then, in one snapshot and without the log's lock, so that no append
     // waits on it: every member's row checked, since rows changed around the
-    // vault write nothing to the log; and the whole chain recomputed from its
-    // first entry, every hash from content and every vault entry by its MAC,
-    // since an entry cut from the middle leaves the hashes around a later
-    // checkpoint as they were.
+    // vault write nothing to the log; and the chain recomputed, every hash
+    // from content and every vault entry by its MAC, from the first entry
+    // once an hour, since an entry cut from the middle leaves the hashes
+    // around a later checkpoint as they were (`#recompute`).
     const found: NewEntry[] = [];
     const whole = await this.#db.transaction(async (tx) => {
       await this.#sweep(tx, found);
-      return verifyChain(tx, this.#prepared.logKeys, [], UNVERIFIED);
+      return this.#recompute(tx);
     }, SNAPSHOT);
     return this.#decide([], async (d) => {
       for (const entry of found) if (!d.reports.includes(entry)) d.reports.push(entry);
@@ -1665,6 +1718,9 @@ function validateCorrelation(input: Correlation): void {
   if (input.operationId != null && (typeof input.operationId !== 'string' || !UUID.test(input.operationId))) {
     throw new Error(`operationId must be a lowercase UUID, got: ${String(input.operationId)}`);
   }
+  if (input.credentialId != null && (typeof input.credentialId !== 'string' || !UUID.test(input.credentialId))) {
+    throw new Error(`credentialId must be a lowercase UUID, got: ${String(input.credentialId)}`);
+  }
 }
 
 /** Validate the entire batch before any provider sees a key. */
@@ -1733,6 +1789,7 @@ function keyEntry(
       ...(action === 'key.wrap' ? { secretId: secret.secretId } : {}),
       version: secret.version,
       ...detail,
+      ...traced(correlation),
     }),
   };
 }
@@ -1766,7 +1823,7 @@ function accessEntry(
     subjectPrincipal: PRINCIPAL.test(principal) ? principal : null,
     operationId: correlation.operationId ?? null,
     requestId: correlation.requestId ?? null,
-    metadata: JSON.stringify(PRINCIPAL.test(principal) ? detail : { subject: principal, ...detail }),
+    metadata: JSON.stringify(PRINCIPAL.test(principal) ? { ...detail, ...traced(correlation) } : { subject: principal, ...detail, ...traced(correlation) }),
   };
 }