@coffre/core 0.0.0 → 0.1.0

package/dist/schemas.d.ts

@@ -0,0 +1,18 @@
+import { z } from "zod";
+//#region src/schemas.d.ts
+export declare const slug: z.ZodString;
+export declare const displayName: z.ZodString;
+export declare const secretKey: z.ZodString;
+export declare const principalType: z.ZodEnum<{
+  user: "user";
+  service: "service";
+}>;
+export declare const principalId: z.ZodString;
+export declare const instanceRole: z.ZodEnum<{
+  user: "user";
+  owner: "owner";
+}>;
+export declare const grantId: z.ZodString;
+export declare const emailAddress: z.ZodString;
+export declare const syncId: z.ZodString;
+//#endregion

package/dist/schemas.js

@@ -0,0 +1,13 @@
+import { z } from "zod";
+//#region src/schemas.ts
+const slug = z.string().regex(/^[a-z0-9][a-z0-9-]{0,62}$/);
+const displayName = z.string().trim().min(1).max(120);
+const secretKey = z.string().regex(/^[A-Za-z_][A-Za-z0-9_]{0,127}$/);
+const principalType = z.enum(["user", "service"]);
+const principalId = z.string().trim().min(1).max(320);
+const instanceRole = z.enum(["user", "owner"]);
+const grantId = z.string().uuid();
+const emailAddress = z.string().email().max(320);
+const syncId = z.string().uuid();
+//#endregion
+export { displayName, emailAddress, grantId, instanceRole, principalId, principalType, secretKey, slug, syncId };

package/dist/types-Mi7-Tzj9.js

@@ -0,0 +1,57 @@
+//#region src/context.ts
+/**
+* Version prefix for the AAD encoding. If the encoding ever changes, this
+* changes with it, and old ciphertexts keep decrypting under the old rule.
+*/
+const AAD_VERSION = "coffre.aad.v1";
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+function assertUuid(value, field) {
+	if (typeof value !== "string" || !UUID_RE.test(value)) throw new Error(`context.${field} must be a lowercase UUID, got: ${String(value)}`);
+}
+/** Throw unless every field is a lowercase UUID. */
+function checkContext(ctx) {
+	assertUuid(ctx.projectId, "projectId");
+	assertUuid(ctx.environmentId, "environmentId");
+	assertUuid(ctx.secretId, "secretId");
+}
+/**
+* Encode a context into AAD bytes.
+*
+* Every field is validated as a UUID first, which is what makes joining with
+* `|` unambiguous: a UUID cannot contain the separator, so no two distinct
+* contexts can encode to the same bytes.
+*/
+function encodeAad(ctx) {
+	checkContext(ctx);
+	return Buffer.from(`${AAD_VERSION}|${ctx.projectId}|${ctx.environmentId}|${ctx.secretId}`, "utf8");
+}
+//#endregion
+//#region src/kek/types.ts
+/** Length of the data encryption keys we generate, in bytes (AES-256). */
+const DEK_BYTES = 32;
+/**
+* The key service could not answer: it is down, throttling past the
+* retries, or refusing coffre's own credentials. Nothing is known about the
+* wrapped key, so the vault fails the call instead of refusing it.
+*/
+var KekUnavailableError = class extends Error {
+	name = "KekUnavailableError";
+	uncertain;
+	constructor(message, uncertain = false) {
+		super(message);
+		this.uncertain = uncertain;
+	}
+};
+/** No more work may start. A request already sent may have been accepted by KMS. */
+var KekCancelledError = class extends KekUnavailableError {
+	name = "KekCancelledError";
+	constructor(uncertain = false) {
+		super("key operation was cancelled", uncertain);
+	}
+};
+/** The ciphertext does not open under the claimed key and context. */
+var KekBadClaimError = class extends Error {
+	name = "KekBadClaimError";
+};
+//#endregion
+export { AAD_VERSION as a, KekUnavailableError as i, KekBadClaimError as n, checkContext as o, KekCancelledError as r, encodeAad as s, DEK_BYTES as t };

package/dist/vault.d.ts

@@ -0,0 +1,375 @@
+import { Role } from "./access.js";
+//#region src/access-fault.d.ts
+/**
+ * Why the vault's members and grants do not follow from its log, as facts
+ * rather than a sentence. The vault knows only ids; the app knows what the
+ * people and places are called, so it words the same fault with names.
+ */
+type AccessFault =
+/** An entry changes someone the log never admitted. */
+{
+  kind: 'unadmitted-change';
+  seq: number;
+  principal: string;
+} |
+/** The store has a member the log never admitted. */
+{
+  kind: 'unlogged-member';
+  principal: string;
+} |
+/** The log admits someone the store does not have. */
+{
+  kind: 'missing-member';
+  principal: string;
+} |
+/** The store's row for someone differs from the log's in these fields. */
+{
+  kind: 'member-differs';
+  principal: string;
+  fields: string[];
+} |
+/** The store holds a grant the log never gave. */
+{
+  kind: 'unlogged-grant';
+  grant: FaultGrant;
+} |
+/** The log gives a grant the store does not hold. */
+{
+  kind: 'missing-grant';
+  grant: FaultGrant;
+} |
+/**
+ * The store's row for someone fails the vault's integrity check: changed
+ * outside the vault (`mac`), or put back from before the log's last change
+ * to them (`stale`).
+ */
+{
+  kind: 'tampered-member';
+  principal: string;
+  why: 'mac' | 'stale';
+};
+type FaultGrant = {
+  principal: string;
+  projectId: string;
+  environmentId: string | null;
+  role: string;
+};
+/** How to name a principal (`user:ada@…`) and a place; ids by default. */
+type FaultNames = {
+  principal?: (principal: string) => string;
+  place?: (projectId: string, environmentId: string | null) => string;
+};
+/** The fault in a sentence, with whatever names the caller can give. */
+export declare function describeAccessFault(fault: AccessFault, names?: FaultNames): string;
+//#endregion
+//#region src/checkpoint.d.ts
+/** What a checkpoint's signature covers: the prefix of the log up to entry `seq`, and when. */
+export declare function checkpointMessage(checkpoint: Omit<Checkpoint, 'signature' | 'keyId'>): Uint8Array<ArrayBuffer>;
+/** Whether `checkpoint` was signed by the key whose raw public half is `publicKey`. */
+export declare function verifyCheckpoint(checkpoint: Checkpoint, publicKey: string): Promise<boolean>;
+//#endregion
+//#region src/vault.d.ts
+/**
+ * The vault as the app sees it: the contract between `@coffre/server` and
+ * `@coffre/vault`, kept in core so that neither side owns it. Every argument
+ * and result is plain JSON: strings, numbers, booleans, arrays and objects,
+ * never a Buffer, a Date, a class or a function. So it crosses a Workers RPC
+ * boundary, or a process boundary later, as it is, and the in-process
+ * transport proves it by round-tripping everything through JSON.
+ *
+ * The app says who is asking and the vault decides. The app never holds a
+ * key: it encrypts a value under a fresh data key, has the vault wrap that
+ * key, and stores the result; to read, it names stored versions and the
+ * vault loads their keys itself.
+ *
+ * Decisions come back as values: `{ ok: false, refusal }` for a refusal, which
+ * the vault has already logged. Only a fault (a bug, the store down) throws.
+ */
+export interface Vault {
+  /** Unwrap data keys for `principal`: all of them, or none. */
+  unwrap(input: UnwrapInput): Promise<Outcome<{
+    keys: string[];
+  }>>;
+  /**
+   * Wrap fresh data keys for new versions `principal` writes: all, or none.
+   * `seqs` are the `key.wrap` entries, one per key, which the app's
+   * `secret.write` entries name as related.
+   */
+  wrap(input: WrapInput): Promise<Outcome<{
+    wrapped: WrappedKey[];
+    seqs: number[];
+  }>>;
+  /**
+   * Wrap existing data keys again for new versions of the same secrets,
+   * under the current key: restoring an old value. It needs a write grant,
+   * not a read one, since the key never leaves the vault.
+   */
+  rewrap(input: RewrapInput): Promise<Outcome<{
+    wrapped: WrappedKey[];
+    seqs: number[];
+  }>>;
+  /**
+   * What one principal holds right now: the app asks once per request. A
+   * decision, its rows checked: lists of who holds what read the rows
+   * themselves, and need not ask.
+   */
+  access(principal: string): Promise<Access>;
+  /** Set roles at several places for one principal: all of it, or none. */
+  setAccess(input: SetAccessInput): Promise<Outcome<{
+    changes: AccessChange[];
+  }>>;
+  /**
+   * Add a member, bring back a removed one, or change whether they are an
+   * owner. `generation` is theirs now: sessions and tokens of an earlier
+   * one are dead.
+   */
+  admit(input: AdmitInput): Promise<Outcome<{
+    created: boolean;
+    owner: boolean;
+    generation: number;
+  }>>;
+  /** Remove a member: revoke every grant and refuse them until admitted again, from `generation` on. */
+  remove(input: RemoveInput): Promise<Outcome<{
+    revoked: Grant[];
+    generation: number;
+  }>>;
+  /**
+   * Sign the log up to its last entry, in an `audit.checkpoint` entry of
+   * the vault's, if the whole chain recomputes from its first entry, the
+   * vault's entries by their MACs, and the prefix the last checkpoint signed
+   * is still there. The vault reads the log itself: it takes nobody's word
+   * for where it ends, or for what came before. It checks every
+   * member's row too, as `access` would, and logs a `vault.tampered` for
+   * each one changed around it: lists read rows without asking the vault.
+   */
+  checkpoint(): Promise<Outcome<{
+    checkpoint: Checkpoint;
+  }>>;
+  /**
+   * What only the vault's configuration says, which the app shows: the key
+   * its checkpoints verify under, and the root admins, as principals.
+   */
+  about(): Promise<{
+    publicKey: string;
+    rootAdmins: string[];
+  }>;
+  /**
+   * Check the whole log: rehash it from the first entry, the vault's
+   * entries by their MACs, every checkpoint against the prefix it signed,
+   * and replay it to see that who is a member, and what they hold, follow
+   * from it. A verdict and nothing else, so anyone may ask; the app asks
+   * for owners.
+   */
+  verifyLog(input: VerifyLogInput): Promise<LogVerification>;
+}
+/**
+ * The vault's entries that change what a member holds: what their row's
+ * `access_seq` names, and what a finding about them is newer than while it
+ * stands.
+ */
+export declare const ACCESS_ACTIONS: readonly ["member.add", "member.restore", "member.owner", "member.remove", "access.grant", "access.revoke"];
+/** A refusal, already logged by the time the app sees it. */
+export type Refusal = {
+  code: RefusalCode;
+  message: string;
+};
+export type RefusalCode =
+/** The principal was removed; only `admit` brings them back. */
+'removed' |
+/** The principal was never admitted. */
+'not_a_member' |
+/** No grant covers the place for what was asked. */
+'no_grant' |
+/** A grant covered it, but has expired. */
+'expired' |
+/** Too many unwraps in the window; see `BulkLimit`. */
+'bulk_limit' |
+/** The wrapped key does not belong to the secret it was presented as. */
+'bad_claim' |
+/** Not allowed to manage access, members or the log. */
+'not_allowed' |
+/** Root admins come from the vault's configuration and cannot be changed. */
+'root_admin' |
+/** Well-formed, but not something the rules allow: a project role on an environment, an owner token. */
+'invalid' |
+/** The vault's own log no longer carries the head the last checkpoint signed, or does not rehash since. */
+'log_broken' |
+/**
+ * A KEK the vault is given does not open what it wrapped: a restore with
+ * the wrong key, or a key mistyped under the right id. Every key
+ * operation is refused until the vault restarts with the right one.
+ */
+'wrong_kek' |
+/**
+ * The member's row or grants were changed outside the vault, or put back
+ * from before a later change: it refuses them until an owner removes them,
+ * which starts their access over from the log.
+ */
+'tampered';
+export type Outcome<T> = ({
+  ok: true;
+} & T) | {
+  ok: false;
+  refusal: Refusal;
+};
+/**
+ * A proposed version the app will store. The ids bind its key, and `path`
+ * is the app's label for the write's log. Reads name stored version ids
+ * instead, so the vault reads the binding and wrapped key itself.
+ */
+export type SecretRef = {
+  projectId: string;
+  environmentId: string;
+  secretId: string;
+  version: number;
+  /** `market/prod/DATABASE_URL`. */
+  path: string;
+};
+/** A wrapped data key and the key encryption key that wrapped it; `bytes` is base64. */
+export type WrappedKey = {
+  kekProvider: string;
+  kekId: string;
+  kekVersion: string;
+  bytes: string;
+};
+/** Why someone reads: shown in the log, and the same rules apply to each. */
+export type Purpose = 'reveal' | 'run' | 'compare' | 'sync';
+/** Ties the vault's entries to the app's request and audit rows. */
+type Correlation = {
+  requestId?: string | null;
+  /**
+   * The one action the call is part of, the app's id for it: a reveal's
+   * reads, a write's versions, an access change. Its entries share it.
+   */
+  operationId?: string | null;
+};
+export type UnwrapInput = Correlation & {
+  principal: string;
+  purpose: Purpose;
+  items: {
+    secretVersionId: string;
+  }[];
+};
+export type WrapInput = Correlation & {
+  principal: string;
+  /** `key` is a fresh 32-byte data key, base64. */
+  items: {
+    secret: SecretRef;
+    key: string;
+  }[];
+};
+export type RewrapInput = Correlation & {
+  principal: string;
+  /** `secret` is the proposed new version; `secretVersionId` is the stored source. */
+  items: {
+    secret: SecretRef;
+    secretVersionId: string;
+  }[];
+};
+export type Grant = {
+  projectId: string;
+  /** Null for the whole project. */
+  environmentId: string | null;
+  role: Role;
+  /** ISO 8601, or null for no end. */
+  expiresAt: string | null;
+  grantedAt: string;
+  grantedBy: string;
+};
+export type Access = {
+  principal: string;
+  /**
+   * `unknown` for someone never admitted, `tampered` for a member whose row
+   * fails the vault's integrity check: refused everything, as `removed` is.
+   * Root admins are always active.
+   */
+  status: 'active' | 'removed' | 'unknown' | 'tampered';
+  /** Advanced by removal, even if the app cannot commit its credential revocations. */
+  generation: number;
+  isRootAdmin: boolean;
+  /** Root admins and users admitted as owners, while active. */
+  isOwner: boolean;
+  /** Live grants only, and none unless active. */
+  grants: Grant[];
+  /** When the status last changed, and who changed it; null for root admins and strangers. */
+  since: string | null;
+  by: string | null;
+};
+/** One place: a role to hold there, with an optional end, or null for none. */
+export type GrantChange = {
+  projectId: string;
+  environmentId: string | null;
+  role: Role | null;
+  expiresAt: string | null;
+};
+export type AccessChange = 'created' | 'updated' | 'revoked' | 'unchanged';
+export type SetAccessInput = Correlation & {
+  actor: string;
+  principal: string;
+  changes: GrantChange[];
+};
+export type AdmitInput = Correlation & {
+  actor: string;
+  principal: string;
+  /** Left out, an existing member keeps their role and a new one is not an owner. */
+  owner?: boolean;
+};
+export type RemoveInput = Correlation & {
+  actor: string;
+  principal: string;
+  /**
+   * For a sync: the environment it pushes from. Whoever may manage it there
+   * may stop the sync, also once its grant there is revoked and only the
+   * one on its credential is left.
+   */
+  source?: {
+    projectId: string;
+    environmentId: string;
+  };
+};
+/**
+ * A prefix of the log the vault signed: every entry up to `seq`, the last
+ * of which has `hash`, which pins every byte before it. Kept as the vault's
+ * `audit.checkpoint` entry, just after the prefix it signs.
+ */
+export type Checkpoint = {
+  seq: number;
+  /** The hash of entry `seq`, hex. */
+  hash: string;
+  signedAt: string;
+  keyId: string;
+  /** Ed25519 over `checkpointMessage(...)`, base64. */
+  signature: string;
+};
+/** An entry of the vault's log, and so the chain up to it. */
+export type LogHead = {
+  seq: number;
+  hash: string;
+};
+export type VerifyLogInput = {
+  /**
+   * The last entry the app verified, its own entries by its key: the vault
+   * checks the log still holds it, so between them both authors' entries
+   * are authenticated over the same prefix.
+   */
+  upTo?: LogHead | null;
+};
+/**
+ * Whether the vault's log holds, with the number of entries in it. On a
+ * failure, the entry where it breaks, or null when the chain holds but the
+ * members and grants do not follow from it. Then `fault` says which, as
+ * facts the app can word with names: `reason` has only ids.
+ * Full checks report live key batches in `pending`; overdue ones fail.
+ */
+export type LogVerification = {
+  ok: true;
+  entries: number;
+  pending?: number;
+} | {
+  ok: false;
+  failedAtSeq: number | null;
+  reason: string;
+  fault?: AccessFault;
+};
+//#endregion
+export type { AccessFault, FaultGrant, FaultNames };

package/dist/vault.js

@@ -0,0 +1,45 @@
+//#region src/checkpoint.ts
+/** What a checkpoint's signature covers: the prefix of the log up to entry `seq`, and when. */
+function checkpointMessage(checkpoint) {
+	const { seq, hash, signedAt } = checkpoint;
+	return new Uint8Array(new TextEncoder().encode(`coffre.checkpoint.v3|${seq}|${hash}|${signedAt}`));
+}
+/** Whether `checkpoint` was signed by the key whose raw public half is `publicKey`. */
+async function verifyCheckpoint(checkpoint, publicKey) {
+	const key = await crypto.subtle.importKey("raw", new Uint8Array(Buffer.from(publicKey, "base64")), { name: "Ed25519" }, false, ["verify"]);
+	return crypto.subtle.verify("Ed25519", key, new Uint8Array(Buffer.from(checkpoint.signature, "base64")), checkpointMessage(checkpoint));
+}
+//#endregion
+//#region src/access-fault.ts
+/** The fault in a sentence, with whatever names the caller can give. */
+function describeAccessFault(fault, names = {}) {
+	const who = names.principal ?? ((principal) => principal);
+	const where = names.place ?? ((projectId, environmentId) => environmentId === null ? projectId : `${projectId}/${environmentId}`);
+	const grant = ({ principal, projectId, environmentId, role }) => `${who(principal)} as ${role} on ${where(projectId, environmentId)}`;
+	switch (fault.kind) {
+		case "unadmitted-change": return `entry ${fault.seq} changes ${who(fault.principal)}, whom the log never admitted`;
+		case "unlogged-member": return `the store has ${who(fault.principal)} as a member, whom the log never admitted`;
+		case "missing-member": return `the log admits ${who(fault.principal)}, whom the store does not have`;
+		case "member-differs": return `the store's ${who(fault.principal)} differs from the log's in ${fault.fields.join(", ")}`;
+		case "unlogged-grant": return `the store holds a grant the log never gave: ${grant(fault.grant)}`;
+		case "missing-grant": return `the log gives a grant the store does not hold: ${grant(fault.grant)}`;
+		case "tampered-member": return fault.why === "mac" ? `the store's ${who(fault.principal)}, or their grants, were changed outside the vault` : `the store's ${who(fault.principal)} is older than the log's last change to them: it was put back`;
+	}
+}
+//#endregion
+//#region src/vault.ts
+/**
+* The vault's entries that change what a member holds: what their row's
+* `access_seq` names, and what a finding about them is newer than while it
+* stands.
+*/
+const ACCESS_ACTIONS = [
+	"member.add",
+	"member.restore",
+	"member.owner",
+	"member.remove",
+	"access.grant",
+	"access.revoke"
+];
+//#endregion
+export { ACCESS_ACTIONS, checkpointMessage, describeAccessFault, verifyCheckpoint };

package/package.json

@@ -1,8 +1,78 @@
 {
   "name": "@coffre/core",
-  "version": "0.0.0",
-  "description": "Reserved for coffre, a self-hosted secrets manager. The first release replaces this placeholder.",
+  "version": "0.1.0",
+  "description": "What coffre's packages share: roles, envelopes, identity, the audit chain and the vault's contract.",
   "license": "MIT",
-  "homepage": "https://github.com/erwinkn/coffre",
-  "repository": { "type": "git", "url": "git+https://github.com/erwinkn/coffre.git", "directory": "packages/core" }
-}
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/erwinkn/coffre.git",
+    "directory": "packages/core"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "exports": {
+    "./access": {
+      "coffre:source": "./src/access.ts",
+      "types": "./dist/access.d.ts",
+      "default": "./dist/access.js"
+    },
+    "./audit": {
+      "coffre:source": "./src/audit/chain.ts",
+      "types": "./dist/audit.d.ts",
+      "default": "./dist/audit.js"
+    },
+    "./dotenv": {
+      "coffre:source": "./src/dotenv.ts",
+      "types": "./dist/dotenv.d.ts",
+      "default": "./dist/dotenv.js"
+    },
+    "./envelope": {
+      "coffre:source": "./src/envelope.ts",
+      "types": "./dist/envelope.d.ts",
+      "default": "./dist/envelope.js"
+    },
+    "./identity": {
+      "coffre:source": "./src/identity/index.ts",
+      "types": "./dist/identity.d.ts",
+      "default": "./dist/identity.js"
+    },
+    "./kek": {
+      "coffre:source": "./src/kek/index.ts",
+      "types": "./dist/kek.d.ts",
+      "default": "./dist/kek.js"
+    },
+    "./schemas": {
+      "coffre:source": "./src/schemas.ts",
+      "types": "./dist/schemas.d.ts",
+      "default": "./dist/schemas.js"
+    },
+    "./vault": {
+      "coffre:source": "./src/vault.ts",
+      "types": "./dist/vault.d.ts",
+      "default": "./dist/vault.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "jose": "6.2.3",
+    "oauth4webapi": "3.8.8",
+    "zod": "4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "26.1.1",
+    "tsdown": "0.23.0",
+    "typescript": "5.9.3",
+    "@coffre/conformance": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "test": "node --conditions=coffre:source --test"
+  }
+}

package/src/access-fault.ts

@@ -0,0 +1,61 @@
+/**
+ * Why the vault's members and grants do not follow from its log, as facts
+ * rather than a sentence. The vault knows only ids; the app knows what the
+ * people and places are called, so it words the same fault with names.
+ */
+export type AccessFault =
+  /** An entry changes someone the log never admitted. */
+  | { kind: 'unadmitted-change'; seq: number; principal: string }
+  /** The store has a member the log never admitted. */
+  | { kind: 'unlogged-member'; principal: string }
+  /** The log admits someone the store does not have. */
+  | { kind: 'missing-member'; principal: string }
+  /** The store's row for someone differs from the log's in these fields. */
+  | { kind: 'member-differs'; principal: string; fields: string[] }
+  /** The store holds a grant the log never gave. */
+  | { kind: 'unlogged-grant'; grant: FaultGrant }
+  /** The log gives a grant the store does not hold. */
+  | { kind: 'missing-grant'; grant: FaultGrant }
+  /**
+   * The store's row for someone fails the vault's integrity check: changed
+   * outside the vault (`mac`), or put back from before the log's last change
+   * to them (`stale`).
+   */
+  | { kind: 'tampered-member'; principal: string; why: 'mac' | 'stale' };
+
+export type FaultGrant = { principal: string; projectId: string; environmentId: string | null; role: string };
+
+/** How to name a principal (`user:ada@…`) and a place; ids by default. */
+export type FaultNames = {
+  principal?: (principal: string) => string;
+  place?: (projectId: string, environmentId: string | null) => string;
+};
+
+/** The fault in a sentence, with whatever names the caller can give. */
+export function describeAccessFault(fault: AccessFault, names: FaultNames = {}): string {
+  const who = names.principal ?? ((principal: string) => principal);
+  const where =
+    names.place ??
+    ((projectId: string, environmentId: string | null) =>
+      environmentId === null ? projectId : `${projectId}/${environmentId}`);
+  const grant = ({ principal, projectId, environmentId, role }: FaultGrant) =>
+    `${who(principal)} as ${role} on ${where(projectId, environmentId)}`;
+  switch (fault.kind) {
+    case 'unadmitted-change':
+      return `entry ${fault.seq} changes ${who(fault.principal)}, whom the log never admitted`;
+    case 'unlogged-member':
+      return `the store has ${who(fault.principal)} as a member, whom the log never admitted`;
+    case 'missing-member':
+      return `the log admits ${who(fault.principal)}, whom the store does not have`;
+    case 'member-differs':
+      return `the store's ${who(fault.principal)} differs from the log's in ${fault.fields.join(', ')}`;
+    case 'unlogged-grant':
+      return `the store holds a grant the log never gave: ${grant(fault.grant)}`;
+    case 'missing-grant':
+      return `the log gives a grant the store does not hold: ${grant(fault.grant)}`;
+    case 'tampered-member':
+      return fault.why === 'mac'
+        ? `the store's ${who(fault.principal)}, or their grants, were changed outside the vault`
+        : `the store's ${who(fault.principal)} is older than the log's last change to them: it was put back`;
+  }
+}