@coffre/vault 0.1.1 → 0.1.3

package/src/config.ts

@@ -1,3 +1,5 @@
+import { hkdfSync } from 'node:crypto';
+
 import { KekRegistry, LocalKekProvider, type KekProvider } from '@coffre/core/kek';
 
 /** At most `count` data keys unwrapped per principal in any `windowMs`. */
@@ -15,8 +17,12 @@ 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;
+  /**
+   * The seeds of the vault's own keys, which MAC its log entries, seal member
+   * rows and sign checkpoints: the first signs; every one verifies what it
+   * signed, so a rotation leaves earlier records verifying.
+   */
+  signingKeys: readonly Uint8Array[];
   bulkLimit: BulkLimit;
 };
 
@@ -32,20 +38,28 @@ export type Kek = { id: string; key: string } | KekProvider;
  *
  *   {
  *     kek: awsKms({ keyArn: env.KMS_KEY_ARN, credentials: { … } }),
- *     previousKeks: [{ id: 'kek-2025-01', key: env.KEK_2025_01 }],
+ *     previousKeks: [{ id: 'vault-2025-01-10-k7q2xm', key: env.OLD_VAULT_KEY }],
  *     rootAdmins: ['admin@acme.example'],
- *     signingKey: env.SIGNING_KEY,
+ *     signingKey: env.SIGNING_KEY, // required with a key service; derived from a local KEK otherwise
  *   }
  */
 export type VaultConfig = {
   /** Wraps every new data key. */
   kek: Kek;
-  /** Older KEKs, still unwrapping what they wrapped until a rewrap moves it on. */
+  /**
+   * Older KEKs, still unwrapping what they wrapped until a rewrap moves it
+   * on, and verifying what the vault wrote under them before the rotation.
+   */
   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;
+  /**
+   * 32 random bytes, base64: the seed of the vault's own keys, which MAC its
+   * log entries, seal member rows and sign checkpoints. Leave it out with a
+   * local KEK, and the vault derives it from the KEK. Required when a key
+   * service holds the KEK, as AWS KMS does: the vault never sees that key.
+   */
+  signingKey?: string;
   /** At most `count` data keys unwrapped per principal in any `windowMinutes`; 1000 in 15 unless set. */
   bulkLimit?: { count: number; windowMinutes: number };
 };
@@ -61,39 +75,74 @@ 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 {
+/** The label no other use of a KEK shares: a local KEK is otherwise only ever an AES-256-GCM key. */
+const SIGNING_KEY_LABEL = 'coffre.vault.signing-key.v1';
+
+/** The signing key a local KEK stands for, when the vault is given none: HKDF-SHA-256 of the KEK. */
+export function derivedSigningKey(kek: Uint8Array): Buffer {
+  return Buffer.from(hkdfSync('sha256', kek, new Uint8Array(0), SIGNING_KEY_LABEL, 32));
+}
+
+/** A KEK as the registry takes it, and the signing key it stands for when it is one the vault holds. */
+function kek(entry: Kek): { provider: KekProvider; signingKey: Buffer | null } {
   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);
+    if (!KEK_ID.test(id)) throw new Error(`the vault key's ID "${id}" (kek.id) must be 1-64 letters, digits, dots, dashes or underscores`);
+    const raw = key32(key, `the vault key ${id}`);
+    return { provider: new LocalKekProvider(raw, id), signingKey: derivedSigningKey(raw) };
   }
   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)}"`);
+    throw new Error(`a key service's name (kek.provider) 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`);
+    throw new Error(`vault key ${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()`);
+    throw new Error(`vault key ${provider}:${keyId} needs wrap() and unwrap()`);
   }
-  return entry;
+  return { provider: entry, signingKey: null };
 }
 
 /** 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 keks = [config.kek, ...(config.previousKeks ?? [])].map(kek);
+  const [current, ...previous] = keks.map((entry) => entry.provider);
   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}`);
+  if (twice !== undefined) throw new Error(`two vault keys share an id: ${twice}`);
   return {
     keks: new KekRegistry(current, previous),
     rootAdmins: checkRootAdmins(config.rootAdmins),
-    signingKey: key32(config.signingKey, 'the signing key'),
+    signingKeys: signingKeys(config.signingKey, keks),
     bulkLimit: config.bulkLimit === undefined ? DEFAULT_BULK_LIMIT : checkBulkLimit(config.bulkLimit),
   };
 }
 
+/**
+ * The key the vault signs with, then every other it verifies with. It signs
+ * with `signingKey` when it is given one, and otherwise with the key the
+ * primary KEK stands for. It verifies with the keys every local KEK stands
+ * for too, the previous ones included: a KEK rotation changes the derived
+ * signing key, and what the old one signed before the rotation must still
+ * verify, for as long as the old KEK stays configured. Nothing after it does
+ * (`#settle` in vault.ts).
+ */
+function signingKeys(given: string | undefined, keks: { provider: KekProvider; signingKey: Buffer | null }[]): Buffer[] {
+  const derived = keks.flatMap((entry) => (entry.signingKey === null ? [] : [entry.signingKey]));
+  let signing: Buffer;
+  if (given !== undefined) signing = key32(given, 'the signing key');
+  else if (keks[0].signingKey !== null) signing = keks[0].signingKey;
+  else {
+    const { provider, keyId } = keks[0].provider;
+    throw new Error(
+      `signingKey is required with the ${provider} vault key ${keyId}: the vault derives its signing key only from a vault key it holds, ` +
+        'and a key service never hands its key over. Set signingKey to 32 random bytes, base64 (openssl rand -base64 32), and keep it with the vault key.',
+    );
+  }
+  return [signing, ...derived].filter((key, i, all) => all.findIndex((other) => other.equals(key)) === i);
+}
+
 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');

package/src/index.ts

@@ -4,3 +4,5 @@ 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';
+/** 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/log.ts

@@ -24,12 +24,14 @@ export function vaultLogKey(signingKey: Uint8Array): LogKey {
 /**
  * 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.
+ * 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 };
+export type Anchor = { nextSeq: bigint; hash: Buffer; vaultEntries: number; vaultKeys: readonly string[] };
 
 /** Before the first entry: nothing verified yet. */
-export const UNVERIFIED: Anchor = { nextSeq: 0n, hash: GENESIS_HASH, vaultEntries: 0 };
+export const UNVERIFIED: Anchor = { nextSeq: 0n, hash: GENESIS_HASH, vaultEntries: 0, vaultKeys: [] };
 
 /** The further of two anchors, when two calls verified at once. */
 export function further(a: Anchor, b: Anchor): Anchor {
@@ -57,15 +59,15 @@ type Verified = { verification: LogVerification; anchor: Anchor };
  */
 export async function verifyChain(
   db: Queryable,
-  key: LogKey,
+  logKeys: readonly LogKey[],
   shown: readonly StoredEntry[],
   anchor: Anchor,
 ): Promise<Verified> {
   const broken = (failedAtSeq: bigint, reason: string): Verified => ({
-    verification: { ok: false, failedAtSeq: Number(failedAtSeq), reason },
+    verification: { ok: false, failedAtSeq: Number(failedAtSeq), reason: withCause(reason) },
     anchor,
   });
-  const keys = { keys: [key], chainOnly: ['app' as const] };
+  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 });
@@ -82,12 +84,57 @@ export async function verifyChain(
     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 };
+    const moved = forward(batch, verified.vaultKeys, logKeys[0].keyId);
+    if ('failedAtSeq' in moved) return broken(moved.failedAtSeq, moved.reason);
+    verified = {
+      nextSeq: result.nextSeq,
+      hash: result.head,
+      vaultEntries: verified.vaultEntries + result.authenticated,
+      vaultKeys: moved.keys,
+    };
     if (batch.length < VERIFY_BATCH) break;
   }
   return { verification: { ok: true, entries: verified.vaultEntries }, anchor: verified };
 }
 
+/**
+ * The vault's keys only move forward. Once its entries move from one key to
+ * the next, the one before writes no more; once they reach `current`, the
+ * key it writes with now, no other key writes again. So a key it replaced,
+ * even one that leaked, verifies what came before the rotation, and nothing
+ * after it.
+ */
+function forward(
+  entries: readonly StoredEntry[],
+  keys: readonly string[],
+  current: string,
+): { keys: readonly string[] } | { failedAtSeq: bigint; reason: string } {
+  let moved = keys;
+  for (const entry of entries) {
+    const last = moved.at(-1);
+    if (entry.author !== 'vault' || entry.keyId === last) continue;
+    if (last === current || moved.includes(entry.keyId)) {
+      return {
+        failedAtSeq: entry.seq,
+        reason: `written under ${entry.keyId} after the vault moved to ${last}: a key it replaced verifies only what came before`,
+      };
+    }
+    moved = [...moved, entry.keyId];
+  }
+  return { keys: moved };
+}
+
+/**
+ * A vault entry under a key the vault does not hold is a forgery, or one
+ * written under a key it was configured with then: its keys come from its
+ * signing key, or from its KEK when it has none. The second is the one an
+ * operator can fix.
+ */
+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`;
+}
+
 /**
  * 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

package/src/store.ts

@@ -306,6 +306,22 @@ export async function vaultPage(db: Queryable, before: bigint | undefined, limit
   return stored(rows);
 }
 
+/**
+ * The seq of the vault's first entry under `keyId`, or undefined. No index
+ * serves it: it reads the log from its start up to that entry, which for
+ * the key a log began under is among its first.
+ */
+export async function firstVaultEntryUnder(db: Queryable, keyId: string): Promise<bigint | undefined> {
+  const { auditLog } = tablesOf(db);
+  const [row] = await db
+    .select({ seq: auditLog.seq })
+    .from(auditLog)
+    .where(and(eq(auditLog.author, 'vault' satisfies Author), eq(auditLog.keyId, keyId)))
+    .orderBy(asc(auditLog.seq))
+    .limit(1);
+  return row?.seq;
+}
+
 /** 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);