@coffre/vault 0.9.0 → 0.10.1

package/package.json

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

package/src/accounting.ts

@@ -7,19 +7,48 @@ type Item = { item: number; secretId: string; version: number; subject: string }
 type ParsedIntent = { intentId: string; operation: string; expiresAt: number; keys: Item[] };
 /** An outcome entry: one item of its intent, or several, for a read logged once per place. */
 type ParsedOutcome = { intentId: string; relatedSeq: bigint; items: Item[] };
-type Intent = ParsedIntent & { entry: StoredEntry; seen: Set<number> };
+type Intent = ParsedIntent & { seq: bigint; actor: string; seen: Set<number> };
 type Accounting = { ok: true; pending: number } | Extract<LogVerification, { ok: false }>;
+type Broken = Extract<Accounting, { ok: false }>;
+
+/** A key batch still under way, as a checkpoint keeps it: its intent's entry, and the items whose outcomes are logged. */
+export type OpenIntent = { seq: number; intentId: string; operation: string; expiresAt: number; actor: string; keys: Item[]; seen: number[] };
+
+/** Where the accounting stands, as a checkpoint keeps it: the batches still open, and the first fault, once found. */
+export type AccountingState = { intents: OpenIntent[]; fault: { failedAtSeq: number; reason: string } | null };
 
 /**
  * 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
+ * first, as a walk 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.
+ *
+ * A walk resumes from a checkpoint's `state()`: the batches open there, and
+ * nothing of those that closed. So an intent's identity is checked against
+ * those still open and those since, not every one the log ever held: a
+ * closed batch takes no more outcomes in any case, since each names its
+ * intent's entry.
  */
 export class KeyAccounting {
   readonly #intents = new Map<bigint, Intent>();
   readonly #ids = new Set<string>();
-  #fault: Extract<Accounting, { ok: false }> | null = null;
+  #fault: Broken | null = null;
+
+  constructor(from: AccountingState = { intents: [], fault: null }) {
+    for (const { seq, seen, ...open } of from.intents) {
+      this.#intents.set(BigInt(seq), { ...open, seq: BigInt(seq), seen: new Set(seen) });
+      this.#ids.add(open.intentId);
+    }
+    this.#fault = from.fault === null ? null : { ok: false, ...from.fault };
+  }
+
+  /** Where it stands, to resume from: the batches open, oldest first. */
+  state(): AccountingState {
+    const intents = [...this.#intents.values()]
+      .sort((a, b) => (a.seq < b.seq ? -1 : 1))
+      .map(({ seq, seen, ...open }) => ({ ...open, seq: Number(seq), seen: [...seen].sort((a, b) => a - b) }));
+    return { intents, fault: this.#fault === null ? null : { failedAtSeq: this.#fault.failedAtSeq!, reason: this.#fault.reason } };
+  }
 
   add(entry: StoredEntry): void {
     if (this.#fault !== null || entry.author !== 'vault') return;
@@ -31,7 +60,7 @@ export class KeyAccounting {
       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() });
+      if (parsed.keys.length > 0) this.#intents.set(entry.seq, { ...parsed, seq: entry.seq, actor: entry.actor, 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);
@@ -42,7 +71,7 @@ export class KeyAccounting {
         if (intent === undefined || key === undefined || intent.seen.has(outcome.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) {
+        if (parsed.intentId !== intent.intentId || entry.actor !== intent.actor || entry.action !== intent.operation) {
           return broken('key outcome belongs to another operation');
         }
         if (outcome.secretId !== key.secretId || outcome.version !== key.version || outcome.subject !== key.subject) {
@@ -51,7 +80,7 @@ export class KeyAccounting {
         intent.seen.add(outcome.item);
       }
       // Completed batches need no state, and another outcome for one is a duplicate.
-      if (intent !== undefined && intent.seen.size === intent.keys.length) this.#intents.delete(intent.entry.seq);
+      if (intent !== undefined && intent.seen.size === intent.keys.length) this.#intents.delete(intent.seq);
     }
   }
 
@@ -65,7 +94,7 @@ export class KeyAccounting {
       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 };
+    return { ok: false, failedAtSeq: Number(overdue[0]!.seq), reason };
   }
 }
 

package/src/cloudflare.ts

@@ -23,6 +23,7 @@ import type {
   RewrapInput,
   SetAccessInput,
   SetSettingsInput,
+  ChangePolicyInput,
   UnwrapInput,
   Vault,
   VerifyLogInput,
@@ -94,6 +95,8 @@ export class VaultEntrypoint extends WorkerEntrypoint implements Vault {
   async remove(input: RemoveInput) { return this.#call((vault) => vault.remove(input)); }
   async settings() { return this.#call((vault) => vault.settings()); }
   async setSettings(input: SetSettingsInput) { return this.#call((vault) => vault.setSettings(input)); }
+  async policy() { return this.#call((vault) => vault.policy()); }
+  async changePolicy(input: ChangePolicyInput) { return this.#call((vault) => vault.changePolicy(input)); }
   async checkpoint() { return this.#call((vault) => vault.checkpoint()); }
   async about() { return this.#call((vault) => vault.about()); }
   async keyChecks() { return this.#call((vault) => vault.keyChecks()); }

package/src/config.ts

@@ -28,20 +28,8 @@ export type ResolvedVaultConfig = {
    */
   signingKeys: readonly Uint8Array[];
   bulkLimit: BulkLimit;
-  /** `values` when left out. */
-  people?: People;
 };
 
-/**
- * What a person's reads open (docs/design/credential-proxy.md): `values`,
- * as any member's; or `stand-ins`, where a person, on any credential of
- * theirs (a session, a personal token, an MCP connection), opens values
- * only for coffre to use for them, never to be handed back: the credential
- * proxy injects them, and the deployment's `expose` list names the few it
- * may pass on. Service accounts read values either way.
- */
-export type People = 'values' | 'stand-ins';
-
 /**
  * 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, … })`.
@@ -76,8 +64,12 @@ export type VaultConfig = {
   signingKey?: string;
   /** At most `count` data keys unwrapped per principal in any `windowMinutes`; 1000 in 15 unless set. */
   bulkLimit?: { count: number; windowMinutes: number };
-  /** What a person's reads open (`People`): `values` unless set. */
-  people?: People;
+  /**
+   * @deprecated Gone in 0.10, and refused: each key says who sees it now. Mark
+   * those no person may read sensitive (`coffre mark <env> sensitive`), and
+   * give people read through their roles where they should see values.
+   */
+  people?: 'gone in 0.10: mark keys sensitive (coffre mark <env> sensitive), and let roles say who reads the rest';
 } & Owners;
 
 /**
@@ -146,6 +138,12 @@ function kek(entry: Kek): { provider: KekProvider; signingKey: Buffer | null } {
 
 /** Check a deployment's vault configuration, failing on the first problem. */
 export function resolveVaultConfig(config: VaultConfig): ResolvedVaultConfig {
+  if ('people' in config && config.people !== undefined) {
+    throw new Error(
+      `people is gone in 0.10 (it was ${JSON.stringify(config.people)}): each key says who sees it now. Remove people, mark the keys no person may read sensitive ` +
+        '(coffre mark <env> sensitive, or coffre set <env>/<KEY> --sensitive), and let roles say who reads the rest (docs/design/credential-proxy.md)',
+    );
+  }
   const keks = [config.kek, ...(config.previousKeks ?? [])].map(kek);
   const [current, ...previous] = keks.map((entry) => entry.provider);
   const refs = [current, ...previous].map(({ provider, keyId }) => `${provider}:${keyId}`);
@@ -156,7 +154,6 @@ export function resolveVaultConfig(config: VaultConfig): ResolvedVaultConfig {
     owners: checkOwners(config.owners ?? config.bootstrapOwners ?? config.rootAdmins ?? []),
     signingKeys: signingKeys(config.signingKey, keks),
     bulkLimit: config.bulkLimit === undefined ? DEFAULT_BULK_LIMIT : checkBulkLimit(config.bulkLimit),
-    people: checkPeople(config.people ?? 'values'),
   };
 }
 
@@ -184,10 +181,6 @@ function signingKeys(given: string | undefined, keks: { provider: KekProvider; s
   return [signing, ...derived].filter((key, i, all) => all.findIndex((other) => other.equals(key)) === i);
 }
 
-function checkPeople(people: People): People {
-  if (people !== 'values' && people !== 'stand-ins') throw new Error(`people is 'values' or 'stand-ins'; got ${JSON.stringify(people)}`);
-  return people;
-}
 
 function checkBulkLimit({ count, windowMinutes }: { count: number; windowMinutes: number }): BulkLimit {
   if (!Number.isInteger(count) || count < 1 || !(windowMinutes > 0)) {

package/src/index.ts

@@ -3,6 +3,6 @@ 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, People, VaultConfig } from './config.ts';
+export type { Kek, VaultConfig } from './config.ts';
 /** The signing key a local KEK stands for, for tools that check the vault's records from outside. */
 export { derivedSigningKey } from './config.ts';

package/src/local.ts

@@ -17,6 +17,8 @@ export const METHODS = [
   'remove',
   'settings',
   'setSettings',
+  'policy',
+  'changePolicy',
   'checkpoint',
   'about',
   'keyChecks',

package/src/log.ts

@@ -2,7 +2,8 @@ import { deriveLogKey, GENESIS_HASH, verifyEntries, type LogKey, type StoredEntr
 import type { LogHead, LogVerification } from '@coffre/core/vault';
 import type { Queryable } from '@coffre/db';
 
-import { entriesFrom, hashAt } from './store.ts';
+import { entriesFrom, hashAt, vaultEntriesAfter } from './store.ts';
+import type { Walk } from './tally.ts';
 
 /**
  * The vault's half of the one audit log: its entries are the ones it
@@ -21,83 +22,113 @@ 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, written under `vaultKeys`, in the order the log moved
- * through them (`forward`). In memory only: the database cannot vouch for
- * itself.
- */
-export type Anchor = { nextSeq: bigint; hash: Buffer; vaultEntries: number; vaultKeys: readonly string[] };
+/** Where a walk of the log stands: the last entry it covered, -1 before the first, and that entry's hash. */
+export type Position = { seq: bigint; hash: Buffer };
 
-/** Before the first entry: nothing verified yet. */
-export const UNVERIFIED: Anchor = { nextSeq: 0n, hash: GENESIS_HASH, vaultEntries: 0, vaultKeys: [] };
+/** Before the first entry. */
+export const START: Position = { seq: -1n, hash: GENESIS_HASH };
 
-/** 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;
+/** The further of two positions, when two calls walked at once. */
+export function further(a: Position, b: Position): Position {
+  return b.seq > a.seq ? b : a;
 }
 
 /** Entries read at once, at most, and no more than `BATCH_BYTES` of what they say: 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 };
+type Broken = Extract<LogVerification, { ok: false }>;
 
 /**
- * Check the chain, a batch in memory at a time, and return where it is now
- * verified to. Three parts:
+ * Walk the chain on from `from`, a batch in memory at a time, through `to`
+ * or the log's last entry, and no more than `limit` entries: every link and
+ * hash recomputed, each of the vault's entries by its MAC, its keys moving
+ * only forward, and each fed to `walk`. Where it got to, and whether that
+ * is as far as it was to go: a walk cut short by `limit` goes on from there
+ * another time.
  *
- * - `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. `onBatch` sees
- * each batch once it has verified, for checks that read the same entries.
+ * It takes `from` as given: whether the log still holds it is the caller's
+ * to check, with the other heads it must hold, in one read.
  */
-export async function verifyChain(
+export async function rehash(
   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) },
-    anchor,
-  });
-  const keys = { keys: logKeys, 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);
+  from: Position,
+  walk: Walk,
+  { to, limit = Infinity }: { to?: bigint; limit?: number },
+): Promise<{ ok: true; at: Position; done: boolean } | Broken> {
+  let at = from;
+  for (let left = limit; ; ) {
+    if (to !== undefined && at.seq >= to) return { ok: true, at, done: true };
+    // Out of entries to walk, it is done if there are none left to: a walk that ends at its budget's last read one more.
+    if (left <= 0) return { ok: true, at, done: !(await entriesFrom(db, at.seq + 1n, 1)).some((entry) => to === undefined || entry.seq <= to) };
+    let batch = await entriesFrom(db, at.seq + 1n, Math.min(VERIFY_BATCH, left));
+    if (to !== undefined) batch = batch.filter((entry) => entry.seq <= to);
+    if (batch.length === 0) return { ok: true, at, done: to === undefined };
+    const result = verifyEntries(batch, { keys: logKeys, chainOnly: ['app'], startSeq: at.seq + 1n, startPrevHash: at.hash });
+    if (!result.ok) return { ok: false, failedAtSeq: Number(result.failedAtSeq), reason: withCause(result.reason) };
+    for (const entry of batch) {
+      const moved = entry.author === 'vault' ? walk.add(entry, logKeys[0]!.keyId) : null;
+      if (moved !== null) return { ok: false, failedAtSeq: Number(moved.failedAtSeq), reason: moved.reason };
+    }
+    at = { seq: result.nextSeq - 1n, hash: result.head };
+    left -= batch.length;
   }
+}
 
-  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');
+/**
+ * The chain again from `from`, through `to` and no more than `limit`
+ * entries: each hash recomputed from its entry and each link checked, and
+ * nothing else, so a stretch costs a hash an entry. What a checkpoint does
+ * in the background to the prefixes signed before (`#scrub` in vault.ts):
+ * each entry's MAC was checked when it was signed over, and its hash pins
+ * it since, so all that can change behind a signed prefix and keep the
+ * chain is an entry edited in place, its stored hash left, which its hash
+ * finds.
+ */
+export async function relink(db: Queryable, from: Position, to: bigint, limit: number): Promise<{ ok: true; at: Position } | Broken> {
+  let at = from;
+  while (at.seq < to && limit > 0) {
+    const batch = (await entriesFrom(db, at.seq + 1n, Math.min(VERIFY_BATCH, limit))).filter((entry) => entry.seq <= to);
+    if (batch.length === 0) break;
+    const result = verifyEntries(batch, { keys: [], chainOnly: ['app', 'vault'], startSeq: at.seq + 1n, startPrevHash: at.hash });
+    if (!result.ok) return { ok: false, failedAtSeq: Number(result.failedAtSeq), reason: result.reason };
+    at = { seq: result.nextSeq - 1n, hash: result.head };
+    limit -= batch.length;
   }
+  return { ok: true, at };
+}
 
-  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);
-    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,
-      vaultEntries: verified.vaultEntries + result.authenticated,
-      vaultKeys: moved.keys,
-    };
+/**
+ * The vault's own entries after `after`, through `to` or its last, no more
+ * than `limit` of them, oldest first: each against its own hash, and by its
+ * MAC, over the link it names, its keys moving only forward, each fed to
+ * `walk`. The links between entries are the caller's to recompute, as the
+ * app does over the same stretch. The last it read, and whether that is as
+ * far as it was to go.
+ */
+export async function ownEntries(
+  db: Queryable,
+  logKeys: readonly LogKey[],
+  after: bigint,
+  walk: Walk,
+  { to, limit = Infinity }: { to?: bigint; limit?: number },
+): Promise<{ ok: true; at: bigint; done: boolean } | Broken> {
+  for (let left = limit; ; ) {
+    if (left <= 0) return { ok: true, at: after, done: !(await vaultEntriesAfter(db, after, 1)).some((entry) => to === undefined || entry.seq <= to) };
+    let batch = await vaultEntriesAfter(db, after, Math.min(VERIFY_BATCH, left));
+    if (to !== undefined) batch = batch.filter((entry) => entry.seq <= to);
+    if (batch.length === 0) return { ok: true, at: after, done: true };
+    for (const entry of batch) {
+      const result = verifyEntries([entry], { startSeq: entry.seq, startPrevHash: entry.prevHash, keys: logKeys });
+      if (!result.ok) return { ok: false, failedAtSeq: Number(result.failedAtSeq), reason: withCause(result.reason) };
+    }
+    for (const entry of batch) {
+      const moved = walk.add(entry, logKeys[0]!.keyId);
+      if (moved !== null) return { ok: false, failedAtSeq: Number(moved.failedAtSeq), reason: moved.reason };
+    }
+    after = batch[batch.length - 1]!.seq;
+    left -= batch.length;
   }
-  return { verification: { ok: true, entries: verified.vaultEntries }, anchor: verified };
 }
 
 /**

package/src/replay.ts

@@ -141,7 +141,7 @@ function placeOf(row: StoredEntry, detail: Record<string, unknown>): Place {
 }
 
 /** A grant's place: its environment, or its project when it has none, or every project's path. */
-function placeKey(place: Place): string {
+export function placeKey(place: Place): string {
   return place.environmentId ?? place.projectId ?? (place.environmentSlug === null ? '*' : `*/${place.environmentSlug}`);
 }