@coffre/vault 0.14.4 → 0.15.0

package/src/inputs.ts

@@ -0,0 +1,499 @@
+import { createHmac, hkdfSync, timingSafeEqual } from 'node:crypto';
+
+import { INSTANCE_ROLES, normalDefinition, ROLES, type CallerKind, type CredentialScope, type InstanceRole, type RoleDefinition, type Scope } from '@coffre/core/access';
+import type { WrappedKey } from '@coffre/core/vault';
+import { logObject } from '@coffre/db/log';
+
+import { MAX_BULK_WINDOW_MINUTES, type BulkLimit } from './config.ts';
+
+/**
+ * Every input a decision reads, as one object of the log, sealed (0.15,
+ * docs/design/sealed-inputs.md). Nothing calls this yet: it is the pure
+ * code that the change path, the use path and the verifier will share.
+ *
+ * - **principal:** a member, their instance role and its scope, and every
+ *   grant they hold, lapsed ones included.
+ * - **credential:** a session, token or binding: whose it is, what kind,
+ *   its scope, its end, and whether it was revoked.
+ * - **connection:** an MCP client a person connected (T147): whose, at
+ *   which generation, its end, and whether it was revoked. A use through
+ *   it weighs it as a person's credential of no scope.
+ * - **secret:** a key's current version: where it is, its nature, its
+ *   wrapped data key or a plain value's digest, or, for a reference, its
+ *   source while its reference stands.
+ * - **environment:** its project and slug, whether it is protected, a
+ *   fork's parent, a personal config's owner, whether it was deleted, and
+ *   whether it or its project is archived.
+ * - **roles:** the role tables, as an Owner edited them.
+ * - **policy:** what the deployment set that every decision reads: the
+ *   bulk cap's count and window (R52).
+ *
+ * Each object's row carries its **seal**, the vault's HMAC-SHA256 over it
+ * cut to 16 bytes, and each change records the seal it leaves. A row is
+ * `tampered` if its seal is not the vault's over it, and `stale` if it is
+ * not the seal of its object's newest change: a row put back from before a
+ * revoke, validly sealed once, is refused.
+ */
+
+/** A principal's grant, as its object holds it: where, which role, and until when (null: for good). */
+export type InputGrant = {
+  projectId: string | null;
+  environmentId: string | null;
+  /** A grant on every project of 0.4: the one environment slug it covers in each, if any. */
+  environmentSlug: string | null;
+  role: string;
+  expiresAt: number | null;
+};
+
+export type PrincipalInput = {
+  kind: 'principal';
+  principal: string;
+  status: 'active' | 'removed';
+  /**
+   * Moved on by each removal (`member.remove`), kept by a restore: a
+   * credential issued at an earlier one is no longer its account's, before
+   * the removal's sweep revokes it (formal/Credentials.tla,
+   * UseDecidesGeneration).
+   */
+  generation: number;
+  role: InstanceRole;
+  scope: Scope;
+  grants: readonly InputGrant[];
+};
+
+export type CredentialInput = {
+  kind: 'credential';
+  id: string;
+  principal: string;
+  caller: CallerKind;
+  /** Past which nothing reaches; null for a session's. */
+  scope: CredentialScope | null;
+  expiresAt: number | null;
+  revoked: boolean;
+  /** Its account's generation when it was issued: it reaches only while the account's is the same. */
+  generation: number;
+};
+
+/**
+ * An MCP connection (T147): the way in of every call its client makes as
+ * its person, which a use weighs as it weighs a person's session, a
+ * credential of no scope. Its row's other columns, its tokens' hashes and
+ * its last use, which a refresh moves, are no part of it.
+ */
+export type ConnectionInput = {
+  kind: 'connection';
+  id: string;
+  principal: string;
+  /** Its account's generation when its person approved it: it reaches only while the account's is the same. */
+  generation: number;
+  expiresAt: number;
+  revoked: boolean;
+};
+
+/**
+ * A trust binding (T149, PR 3a; D148): what a sign-in through it decides on,
+ * which the vault seals when a manager of its account makes it, and takes
+ * no other. Its keys by `jwksUri`: the issuer's discovered URL, or, for keys
+ * uploaded with it, `sha256:<hex>` of them, so its seal covers them too.
+ * Its claims and policy as their canonical JSON, as the row keeps them.
+ */
+export type BindingInput = {
+  kind: 'binding';
+  id: string;
+  principal: string;
+  /** Its account's generation when it was made: it signs in nobody of a later one. */
+  generation: number;
+  profile: string;
+  issuer: string;
+  /** The instance's public URL it was made on: its base audience (PR 3b). */
+  origin: string;
+  jwksUri: string;
+  claims: string;
+  scope: CredentialScope | null;
+  policy: string | null;
+  revoked: boolean;
+};
+
+export type Nature = 'plain' | 'secret' | 'sensitive';
+
+export type SecretInput = {
+  kind: 'secret';
+  id: string;
+  projectId: string;
+  environmentId: string;
+  /** Its current version. */
+  version: string;
+  nature: Nature;
+  /** The version's data key, wrapped; null for a plain value, which the vault never opens, and for a reference. */
+  key: WrappedKey | null;
+  /**
+   * A plain value's text, SHA-256, base64: what binds it, as a key binds a
+   * ciphertext (a writer who edits the text leaves a row its seal does not
+   * cover). Null for any other.
+   */
+  digest: string | null;
+  /**
+   * A reference's source, by its key's id: its value and nature are the
+   * source's now (R23). Null for a key with a value, and for a reference
+   * that has ended (no version and no source: `ended`).
+   */
+  source: string | null;
+  /**
+   * The reference row it reads its source through (`secret_references.id`):
+   * what an end decides on, under the seal, never the rows alone, which a
+   * writer may rename or plant (formal/SealedObjects.tla, ReferenceInObject).
+   * Null when `source` is.
+   */
+  reference: string | null;
+};
+
+export type EnvironmentInput = {
+  kind: 'environment';
+  id: string;
+  projectId: string;
+  slug: string;
+  /** A personal config's owner (`<env>@me`). */
+  owner: string | null;
+  /** A fork's or a personal config's parent. */
+  parentId: string | null;
+  protected: boolean;
+  deleted: boolean;
+  /** Its own archival. */
+  archived: boolean;
+  /**
+   * Its project's, apart: 0.14 takes it as archived when either is. One
+   * bit for both would let a writer clear the environment's own while its
+   * project is archived, under a valid seal, for the project's restore to
+   * seal in (formal/SealedObjects.tla, ArchivedApart).
+   */
+  projectArchived: boolean;
+};
+
+/**
+ * An Owner's edits of the roles, and the roles they made: only what differs
+ * from the release's own tables, which a decision merges them over
+ * (`readerOf`), as 0.14's `livePolicy` does. A release that changes a role
+ * as it ships changes it wherever nobody edited it, and the log, which
+ * never held the shipped tables, replays the same under any release.
+ */
+export type RolesInput = {
+  kind: 'roles';
+  roles: Readonly<Record<string, RoleDefinition>>;
+  instanceRoles: Readonly<Partial<Record<InstanceRole, RoleDefinition>>>;
+};
+
+export type PolicyInput = { kind: 'policy'; bulk: BulkLimit };
+
+export type Input = PrincipalInput | CredentialInput | ConnectionInput | BindingInput | SecretInput | EnvironmentInput | RolesInput | PolicyInput;
+export type Kind = Input['kind'];
+
+/** An object of the log: its kind and its id (the instance's own for the roles and the policy, of which there is one each). */
+export type Ref = { kind: Kind; id: string };
+
+export const ROLES_REF: Ref = { kind: 'roles', id: 'instance' };
+export const POLICY_REF: Ref = { kind: 'policy', id: 'instance' };
+
+export function refOf(input: Input): Ref {
+  switch (input.kind) {
+    case 'principal': return { kind: 'principal', id: input.principal };
+    case 'roles': return ROLES_REF;
+    case 'policy': return POLICY_REF;
+    default: return { kind: input.kind, id: input.id };
+  }
+}
+
+/**
+ * An object's key in the log: the first 16 bytes of SHA-256 over its kind
+ * and id, as a uuid. Fixed-width, so a probe of the changes by object is
+ * about a fifth cheaper than on the text it names (W211, #366), and the same for every kind of id: a principal is text,
+ * the others uuids. Anyone computes it: SQL with `sha256()`.
+ */
+export function objectKey(ref: Ref): string {
+  return logObject(ref.kind, ref.id);
+}
+
+/** `objectKey` for any kind, the log's own included (`log_object` in SQL): a retention change's is ('log', 'retention'). */
+export { logObject };
+
+/** The keys seals are made under, derived from the vault's signing keys, the first sealing and every one checking. */
+export type SealKeys = readonly Buffer[];
+
+export function sealKey(signingKey: Uint8Array): Buffer {
+  return Buffer.from(hkdfSync('sha256', signingKey, new Uint8Array(0), 'coffre.vault.seals.v1', 32));
+}
+
+/** A seal's length: HMAC-SHA256 cut to 128 bits (R53), as truncation guidance allows. */
+export const SEAL_BYTES = 16;
+
+/**
+ * An object's seal: HMAC-SHA256 over the object it is filed under, kind
+ * and id, and its canonical encoding, cut to 16 bytes. The id is the
+ * key's, not the row's, so a row filed under another object's key is not
+ * that object's, however valid its seal is over itself.
+ */
+export function sealOf(key: Buffer, ref: Ref, input: Input): Buffer {
+  return createHmac('sha256', key).update(`coffre.seal.v1\0${ref.kind}\0${ref.id}\0`).update(canonical(normalized(input))).digest().subarray(0, SEAL_BYTES);
+}
+
+/** Whether `seal` is the vault's over `input`, filed under `ref`, by any of its keys. */
+export function sealed(keys: SealKeys, ref: Ref, input: Input, seal: Buffer | null): boolean {
+  if (seal === null || seal.length !== SEAL_BYTES) return false;
+  return keys.some((key) => timingSafeEqual(sealOf(key, ref, input), seal));
+}
+
+/**
+ * `sealed`, each answer kept for the calls of one batch of uses (T167), where every key's rows build the shared
+ * objects (the way in, the account, the roles, the policy, the places) alike; a key's own, its secret's, as `sealed`: by the object's kind and id, the seal,
+ * and the object's JSON as it was built. Equal JSON is an equal object, so an equal canonical encoding and seal: the
+ * answer is the one `sealed` gives, at the cost of one `JSON.stringify` where it was the encoding and an HMAC.
+ */
+export function sealedOnce(): typeof sealed {
+  const kept = new Map<string, boolean>();
+  return (keys, ref, input, seal) => {
+    // A key's own object (its secret, a reference's source) is no other key's: checked as it is, its JSON not built.
+    if (seal === null || ref.kind === 'secret') return sealed(keys, ref, input, seal);
+    const at = `${ref.kind}\0${ref.id}\0${seal.toString('hex')}\0${JSON.stringify(input)}`;
+    let answer = kept.get(at);
+    if (answer === undefined) kept.set(at, (answer = sealed(keys, ref, input, seal)));
+    return answer;
+  };
+}
+
+/**
+ * An object as its seal covers it: a principal's grants as a set, in one
+ * order whatever order the rows come back in. Everything else is kept as
+ * written: a credential's scope is a list it was issued with.
+ */
+function normalized(input: Input): Input {
+  if (input.kind !== 'principal') return input;
+  const grants = input.grants.map((grant) => [grant, canonical(grant)] as const).sort(([, a], [, b]) => (a < b ? -1 : a > b ? 1 : 0));
+  return { ...input, grants: grants.map(([grant]) => grant) };
+}
+
+/**
+ * JSON with every object's keys sorted, and undefined fields left out:
+ * one encoding for one value, whichever way its row was read back.
+ */
+export function canonical(value: unknown): string {
+  return JSON.stringify(value, (_, v: unknown) => (
+    v !== null && typeof v === 'object' && !Array.isArray(v)
+      ? Object.fromEntries(Object.entries(v).filter(([, x]) => x !== undefined).sort(([a], [b]) => (a < b ? -1 : 1)))
+      : v
+  ));
+}
+
+// --- changes ------------------------------------------------------------------
+
+/** Where a grant is, as a revoke names it. */
+export type GrantPlace = Pick<InputGrant, 'projectId' | 'environmentId' | 'environmentSlug'>;
+
+/**
+ * What a change does to its object, as logged and as the change path
+ * applies it (PR 4's `change_input`). `genesis` writes a whole object as a
+ * row has it: the cutover's, once per object, and each adoption of a late
+ * 0.14 write (plan, PR 9). Every change to the policy carries the whole
+ * policy as its `value`, genesis or `bulk.limit`, so a use's statement reads
+ * the cap from the newest one at one path (`value.bulk`, schema 0022's
+ * `use_credential`: the spec's `CapSealed`).
+ */
+export type Op =
+  | { op: 'genesis'; value: Input }
+  | { op: 'member.add'; role: InstanceRole; scope: Scope }
+  | { op: 'member.role'; role: InstanceRole; scope: Scope }
+  | { op: 'member.remove' }
+  | { op: 'member.restore'; role: InstanceRole; scope: Scope }
+  | { op: 'access.grant'; grant: InputGrant }
+  | { op: 'access.revoke'; place: GrantPlace }
+  | { op: 'credential.issue'; principal: string; caller: CallerKind; scope: CredentialScope | null; expiresAt: number | null; generation: number }
+  | { op: 'credential.revoke' }
+  /** An MCP connection approved by its person (T147): its whole object. */
+  | { op: 'connection.make'; value: ConnectionInput }
+  /** An MCP connection ended: disconnected, superseded, its token replayed, or its account removed. */
+  | { op: 'connection.revoke' }
+  /** A binding made (PR 3a): its whole object, which the vault weighed its maker on. */
+  | { op: 'binding.make'; value: BindingInput }
+  /** A binding ended: unbound, or replaced by another. */
+  | { op: 'binding.revoke' }
+  /** A live credential's end moved: a workload's session renewed (never past its hard end, the app's to hold). */
+  | { op: 'credential.renew'; expiresAt: number | null }
+  /** A live credential's scope written: a token of 0.4's, which carried none, sealed to what its account held (`token.seal`). */
+  | { op: 'credential.scope'; scope: CredentialScope | null }
+  | { op: 'secret.write'; projectId: string; environmentId: string; version: string; nature: Nature; key: WrappedKey | null; digest: string | null; source: string | null; reference: string | null }
+  | { op: 'secret.delete' }
+  | { op: 'environment.create'; projectId: string; slug: string; owner: string | null; parentId: string | null; protected: boolean }
+  | { op: 'environment.protect'; protected: boolean }
+  | { op: 'environment.rename'; slug: string }
+  | { op: 'environment.archive'; archived: boolean }
+  /** Its project archived or restored: a change of each of the project's environments. */
+  | { op: 'project.archive'; archived: boolean }
+  | { op: 'environment.delete' }
+  | { op: 'role.define'; table: 'roles' | 'instanceRoles'; role: string; definition: RoleDefinition | null }
+  | { op: 'bulk.limit'; value: PolicyInput };
+
+/** Every object, by its key: the rows a decision reads, as the log has them. */
+export type State = Map<string, Input>;
+
+export function lookup<K extends Kind>(state: ReadonlyMap<string, Input>, kind: K, id: string): Extract<Input, { kind: K }> | null {
+  const input = state.get(objectKey({ kind, id }));
+  return input?.kind === kind ? (input as Extract<Input, { kind: K }>) : null;
+}
+
+/**
+ * A change applied to its object: what the object is after it (null: gone),
+ * or `undefined` if it does nothing, which the change path never logs: a
+ * create of something that exists, a change to something that does not, an
+ * op of another kind's, or a limit R52 does not allow.
+ */
+export function applyOp(before: Input | null, ref: Ref, op: Op): Input | null | undefined {
+  // The object, if it is of the kind the change is about: what every change but a create works on.
+  const of = <K extends Kind>(kind: K) => (ref.kind === kind && before?.kind === kind ? (before as Extract<Input, { kind: K }>) : null);
+  const created = (kind: Kind) => ref.kind === kind && before === null;
+  // The roles and the policy are one object each: a change to another of their kind does nothing.
+  if ((ref.kind === 'roles' || ref.kind === 'policy') && ref.id !== ROLES_REF.id) return undefined;
+  switch (op.op) {
+    case 'genesis': {
+      // A whole object, held to what the ops that make one hold it to.
+      const id = refOf(op.value);
+      if (id.kind !== ref.kind || id.id !== ref.id) return undefined;
+      if (op.value.kind === 'policy' && !allowedLimit(op.value.bulk)) return undefined;
+      if (op.value.kind === 'credential' && !callerFits(op.value)) return undefined;
+      // A connection is a person's: a client acts as its person, never as a service.
+      if (op.value.kind === 'connection' && !op.value.principal.startsWith('user:')) return undefined;
+      return op.value;
+    }
+    case 'member.add':
+      return created('principal') ? { kind: 'principal', principal: ref.id, status: 'active', generation: 0, role: op.role, scope: op.scope, grants: [] } : undefined;
+    case 'member.role': {
+      const member = of('principal');
+      return member?.status === 'active' ? { ...member, role: op.role, scope: op.scope } : undefined;
+    }
+    case 'member.remove': {
+      const member = of('principal');
+      return member?.status === 'active' ? { ...member, status: 'removed', generation: member.generation + 1 } : undefined;
+    }
+    case 'member.restore': {
+      const member = of('principal');
+      return member?.status === 'removed' ? { ...member, status: 'active', role: op.role, scope: op.scope } : undefined;
+    }
+    case 'access.grant': {
+      const member = of('principal');
+      return member === null ? undefined : { ...member, grants: [...member.grants.filter((grant) => !samePlace(grant, op.grant)), op.grant] };
+    }
+    case 'access.revoke': {
+      const member = of('principal');
+      if (member === null || !member.grants.some((grant) => samePlace(grant, op.place))) return undefined;
+      return { ...member, grants: member.grants.filter((grant) => !samePlace(grant, op.place)) };
+    }
+    case 'credential.issue':
+      return created('credential') && callerFits(op)
+        ? { kind: 'credential', id: ref.id, principal: op.principal, caller: op.caller, scope: op.scope, expiresAt: op.expiresAt, revoked: false, generation: op.generation }
+        : undefined;
+    case 'credential.revoke': {
+      const credential = of('credential');
+      return credential !== null && !credential.revoked ? { ...credential, revoked: true } : undefined;
+    }
+    case 'connection.make':
+      return created('connection') && op.value.kind === 'connection' && op.value.id === ref.id && !op.value.revoked && op.value.principal.startsWith('user:') ? op.value : undefined;
+    case 'connection.revoke': {
+      const connection = of('connection');
+      return connection !== null && !connection.revoked ? { ...connection, revoked: true } : undefined;
+    }
+    case 'binding.make':
+      return created('binding') && op.value.id === ref.id && !op.value.revoked ? op.value : undefined;
+    case 'binding.revoke': {
+      const binding = of('binding');
+      return binding !== null && !binding.revoked ? { ...binding, revoked: true } : undefined;
+    }
+    case 'credential.renew': {
+      const credential = of('credential');
+      return credential !== null && !credential.revoked ? { ...credential, expiresAt: op.expiresAt } : undefined;
+    }
+    case 'credential.scope': {
+      const credential = of('credential');
+      const scoped = credential === null || credential.revoked ? null : { ...credential, scope: op.scope };
+      return scoped !== null && callerFits(scoped) ? scoped : undefined;
+    }
+    case 'secret.write': {
+      const secret = of('secret');
+      if (!created('secret') && secret === null) return undefined;
+      // A key stays where it was made: a write elsewhere is another key.
+      if (secret !== null && (secret.projectId !== op.projectId || secret.environmentId !== op.environmentId)) return undefined;
+      const { projectId, environmentId, version, nature, key, digest, source, reference } = op;
+      return { kind: 'secret', id: ref.id, projectId, environmentId, version, nature, key, digest, source, reference };
+    }
+    case 'secret.delete':
+      return of('secret') === null ? undefined : null;
+    case 'environment.create':
+      return created('environment')
+        ? { kind: 'environment', id: ref.id, projectId: op.projectId, slug: op.slug, owner: op.owner, parentId: op.parentId, protected: op.protected, deleted: false, archived: false, projectArchived: false }
+        : undefined;
+    case 'environment.protect': case 'environment.rename': case 'environment.archive': case 'project.archive': case 'environment.delete': {
+      const environment = of('environment');
+      if (environment === null || environment.deleted) return undefined;
+      if (op.op === 'environment.protect') return { ...environment, protected: op.protected };
+      // A scoped role's filters read the slug: a rename is a change like any other (0.14's `environment.update`).
+      if (op.op === 'environment.rename') return { ...environment, slug: op.slug };
+      if (op.op === 'project.archive') return { ...environment, projectArchived: op.archived };
+      // Deleted, it holds no project's archival (objects.ts).
+      return op.op === 'environment.archive' ? { ...environment, archived: op.archived } : { ...environment, deleted: true, projectArchived: false };
+    }
+    case 'role.define': {
+      const edits = of('roles') ?? (created('roles') ? noEdits() : null);
+      if (edits === null) return undefined;
+      // A table with no prototype: a role named `__proto__` is a role like another, never the object's prototype.
+      const table: Record<string, RoleDefinition> = Object.assign(Object.create(null) as Record<string, RoleDefinition>, edits[op.table]);
+      const shipped: Readonly<Record<string, RoleDefinition>> = op.table === 'roles' ? ROLES : INSTANCE_ROLES;
+      const same = op.definition !== null && Object.hasOwn(shipped, op.role) && canonical(normalDefinition(shipped[op.role]!)) === canonical(normalDefinition(op.definition));
+      // No definition, or the one it ships with: no edit, so the release's own decides.
+      if (op.definition === null || same) delete table[op.role];
+      else table[op.role] = op.definition;
+      return { ...edits, [op.table]: { ...table } };
+    }
+    case 'bulk.limit':
+      return (created('policy') || of('policy') !== null) && op.value.kind === 'policy' && allowedLimit(op.value.bulk)
+        ? { kind: 'policy', bulk: { count: op.value.bulk.count, windowMs: op.value.bulk.windowMs } }
+        : undefined;
+  }
+}
+
+/** No edits: the roles object of a log no Owner edited a role in. */
+export function noEdits(): RolesInput {
+  return { kind: 'roles', roles: {}, instanceRoles: {} };
+}
+
+/** A cap R52 allows: a whole count of at least one, a window above nothing and at most a day (`checkBulkLimit` in config.ts). */
+function allowedLimit({ count, windowMs }: BulkLimit): boolean {
+  return Number.isSafeInteger(count) && count >= 1 && Number.isSafeInteger(windowMs) && windowMs > 0 && windowMs <= MAX_BULK_WINDOW_MINUTES * 60_000;
+}
+
+/**
+ * A credential its principal can hold (`through` in vault.ts): a person's
+ * for a `user:`, a bearer's or a workload's for a `token:`, and a
+ * workload's with the scope that lists what it reads.
+ */
+function callerFits({ principal, caller, scope }: { principal: string; caller: CallerKind; scope: CredentialScope | null }): boolean {
+  if (caller === 'person') return principal.startsWith('user:');
+  return principal.startsWith('token:') && (caller === 'bearer' || scope !== null);
+}
+
+function samePlace(a: GrantPlace, b: GrantPlace): boolean {
+  return a.projectId === b.projectId && a.environmentId === b.environmentId && a.environmentSlug === b.environmentSlug;
+}
+
+/**
+ * The change a vault starting with `configured` writes before it serves a
+ * use, if any: the cap is the deployment's code, while decisions, live and
+ * replayed, read the log's, so the two meet here (plan, PR 3). Null when
+ * the log already says the same.
+ */
+export function limitChange(policy: PolicyInput | null, configured: BulkLimit): Op | null {
+  // One no change would apply (a window of a fraction of a millisecond) must stop the start, not leave the log policy-less.
+  if (!allowedLimit(configured)) throw new Error(`bulkLimit must be a whole count of at least 1 and a whole number of milliseconds up to a day, got ${JSON.stringify(configured)}`);
+  if (policy !== null && policy.bulk.count === configured.count && policy.bulk.windowMs === configured.windowMs) return null;
+  return limitOp(configured);
+}
+
+/** The change that sets the bulk cap: the whole policy, as its `value`. */
+export function limitOp(bulk: BulkLimit): Op {
+  return { op: 'bulk.limit', value: { kind: 'policy', bulk: { count: bulk.count, windowMs: bulk.windowMs } } };
+}

package/src/local.ts

@@ -23,12 +23,27 @@ export const METHODS = [
   'about',
   'keyChecks',
   'verifyLog',
+  'use',
+  'useNamed',
+  'useMany',
+  'prepare',
+  'waitSealed',
+  'signIn',
+  'revokeCredential',
+  'issueToken',
+  'changeBindings',
+  'cutover',
+  'verifyTrees',
+  'verifyReads',
+  'vouch',
+  'sealing',
 ] as const satisfies readonly (keyof Vault)[];
 
-export type LocalVault = Vault & { close(): Promise<void> };
+export type LocalVault = Vault & { use: NonNullable<Vault['use']>; close(): Promise<void> };
 
 /**
- * The vault in this process, over `db`. Every argument and result goes
+ * The vault in this process, over `db`, and `hot` for 0.15's uses (vault.ts,
+ * `openVault`). Every argument and result goes
  * through JSON on the way, as it would over RPC or a socket, so what works
  * here does not rely on sharing objects with the caller. `close` is
  * whatever lets go of the database, when the vault opened it.
@@ -38,15 +53,16 @@ export async function openLocalVault(
   config: ResolvedVaultConfig,
   options: VaultOptions = {},
   close: () => Promise<void> = async () => {},
+  hot?: Database,
 ): Promise<LocalVault> {
-  const vault = openVault(db, await prepareVault(config, options));
+  const vault = openVault(db, await prepareVault(config, options), hot);
   const local = Object.fromEntries(
     METHODS.map((name) => [
       name,
       async (...args: unknown[]) =>
         json(await (vault[name] as (...args: unknown[]) => Promise<unknown>)(...(json(args) as unknown[]))),
     ]),
-  ) as unknown as Vault;
+  ) as unknown as Omit<LocalVault, 'close'>;
   return Object.assign(local, { close });
 }
 

package/src/log-checkpointer.ts

@@ -0,0 +1,116 @@
+import { pairSigners } from '@coffre/core/merkle';
+
+import { Checkpointer, FenceClosed, logOrigin, type Alarm, type CheckpointStore, type Fence, type Memory, type Witness } from './checkpointer.ts';
+import { authentic, logMacKey } from './log-entry.ts';
+import type { LogStore } from './log-store.ts';
+import { DAY_MS, dayOf, retain } from './retention.ts';
+
+/**
+ * The checkpointer as a host runs it, on Node (`runCheckpointer`) or in its
+ * Durable Object (`CheckpointerObject`): the trees' keys and the MAC key
+ * from the vault's signing seed, the log's origin from that key, and every
+ * alarm handed to `record` as well as returned by `alarms`, where whoever
+ * watches the log reads them (R40's plugin): refused ticks, changes answered
+ * unwitnessed (R51), a memory found behind the database.
+ */
+export type HostOptions = {
+  store: CheckpointStore;
+  /** The vault's signing seed: the first of `signingKeys`. */
+  seed: Uint8Array;
+  memory: Memory;
+  witnesses?: readonly Witness[];
+  /** Where each alarm is kept; it is also logged. */
+  record?: (alarm: Alarm) => void | Promise<void>;
+  now?: () => number;
+  /** What closes it for good, when its host bounds the open (T169); `TICK_BOUND_MS` otherwise, for the tests. */
+  fence?: Fence;
+  tickBoundMs?: number;
+};
+
+export async function openLogCheckpointer(options: HostOptions): Promise<Checkpointer> {
+  const signers = await pairSigners(await logOrigin(options.seed), options.seed);
+  const now = options.now ?? Date.now;
+  return Checkpointer.open(options.store, signers, {
+    memory: options.memory,
+    witnesses: options.witnesses,
+    authentic: authentic(logMacKey(options.seed)),
+    now,
+    ...(options.fence === undefined ? {} : { fence: options.fence }),
+    ...(options.tickBoundMs === undefined ? {} : { tickBoundMs: options.tickBoundMs }),
+    alert: (message) => {
+      console.warn(`coffre audit: ${message}`);
+      void Promise.resolve(options.record?.({ at: now(), message })).catch((error: Error) => console.warn(`coffre audit: the alarm could not be kept: ${error.message}`));
+    },
+  });
+}
+
+/** How often the checkpointer seals (R51, R54): a change waits at most about this long for a tick, and seals sooner if it asks. */
+export const TICK_MS = 500;
+
+/** An error as an alarm says it: the database's own reason, when a query wrapped it, rather than the query's text. */
+export function reasonOf(error: unknown): string {
+  const e = error as Error & { cause?: unknown };
+  return e?.cause instanceof Error ? e.cause.message : (e?.message ?? String(error));
+}
+
+/** Days of uses made ahead of today's (and yesterday's, for a new database): uses stamped in a day with no partition fail. */
+export const DAYS_AHEAD = 3;
+/** How often retention runs: hourly, so that a day goes within the hour it is due, and a run that waits tries again. */
+export const RETAIN_EVERY_MS = 3_600_000;
+/** How often the bulk cap's old rows are pruned, at most `PRUNED` a time (R52's window, in `prune_bulk`). */
+export const PRUNE_EVERY_MS = 60_000;
+const PRUNED = 10_000;
+
+/** How long retention may wait on one lock (a reader holding the uses, say) before that is an alarm. */
+export const WAITING_ALARM_MS = DAY_MS;
+
+/** The days of uses a host makes ahead at `t`: yesterday's (a new database), today's, and `DAYS_AHEAD` more. */
+export const daysAround = (t: number) => Array.from({ length: DAYS_AHEAD + 2 }, (_, i) => dayOf(t + (i - 1) * DAY_MS));
+
+/**
+ * What a host runs after each tick (plan PR 7): the next days' partitions
+ * made once a day, retention once an hour when `keepDays` is set, the bulk
+ * cap's old rows pruned once a minute. A failure is an alarm, said once while
+ * it stands; retention waiting is none, but for a lock: one that has kept a
+ * day waiting longer than `WAITING_ALARM_MS`. A quiet log, whose pairs do not
+ * pass a day's end until something is logged, waits with no alarm.
+ */
+export function upkeep(cp: Checkpointer, store: LogStore, options: { keepDays: number | null; seed: Uint8Array; now?: () => number; alert: (message: string) => void }): () => Promise<void> {
+  const now = options.now ?? Date.now;
+  const macKey = logMacKey(options.seed);
+  let madeFor: string | null = null;
+  let retained = -Infinity;
+  let pruned = -Infinity;
+  let failed: string | null = null;
+  // The day retention waits on, and since when.
+  let waiting: { day: string; since: number } | null = null;
+  return async () => {
+    const t = now();
+    try {
+      if (madeFor !== dayOf(t)) {
+        await store.makeDays(daysAround(t));
+        madeFor = dayOf(t);
+      }
+      if (t - pruned >= PRUNE_EVERY_MS) {
+        pruned = t;
+        await store.pruneBulk(PRUNED);
+      }
+      if (options.keepDays !== null && t - retained >= RETAIN_EVERY_MS) {
+        retained = t;
+        const run = await retain(cp, store, { keepDays: options.keepDays, macKey, now });
+        const day = run.waiting?.lock ? (run.waiting.day ?? 'the tiles') : null;
+        if (day === null) waiting = null;
+        else if (waiting?.day !== day) waiting = { day, since: t };
+        else if (t - waiting.since >= WAITING_ALARM_MS) throw new Error(`retention has waited on ${day} since ${new Date(waiting.since).toISOString()}: ${run.waiting!.reason}`);
+      }
+      failed = null;
+    } catch (error) {
+      // Its checkpointer closed under it, given up on or replaced: the next one's upkeep does the work, and this is no
+      // alarm (review by Fable).
+      if (error instanceof FenceClosed || (error as { cause?: unknown })?.cause instanceof FenceClosed) return;
+      const message = `the log's upkeep failed: ${reasonOf(error)}`;
+      if (message !== failed) options.alert(message);
+      failed = message;
+    }
+  };
+}