@coffre/vault 0.14.4 → 0.15.0

package/src/node.ts

@@ -1,10 +1,11 @@
 /**
  * The vault on Node, one of two ways, each over the database the server
- * uses, through the vault's own login:
+ * uses, through the vault's own login and its uses' (`hotDatabase`), with
+ * the checkpointer that seals its log in the same process (`checkpointer`):
  *
- * - in the server's own process: `vault: await localVault({ database, ...keys })`;
+ * - in the server's own process: `vault: await localVault({ database, hotDatabase, checkpointer, ...keys })`;
  * - as a process of its own, which the server reaches over a Unix socket:
- *   `serveVault({ socket, database, ...keys })` there, and
+ *   `serveVault({ socket, database, hotDatabase, checkpointer, ...keys })` there, and
  *   `vault: connectVault(socket)` in the server.
  *
  * The second keeps every key out of the process that faces the network. The
@@ -19,8 +20,9 @@ import { Agent, createServer, request as httpRequest, type IncomingMessage } fro
 
 import type { Vault } from '@coffre/core/vault';
 import type { Database } from '@coffre/db';
-import { openDatabase } from '@coffre/db/connect';
+import { engineOfUrl, openDatabase } from '@coffre/db/connect';
 
+import { keepCheckpointer } from './checkpointer-node.ts';
 import { resolveVaultConfig, type VaultConfig } from './config.ts';
 import { failureOf } from './failure.ts';
 import { METHODS, openLocalVault, type LocalVault } from './local.ts';
@@ -29,6 +31,13 @@ import type { VaultOptions } from './vault.ts';
 export type { Vault, VaultConfig };
 export * from './index.ts';
 export type { LocalVault, VaultOptions };
+/** 0.15's checkpointer on Node (docs/design/audit-tree.md), which `localVault` runs in the vault's process. */
+export { fileMemory, keepCheckpointer, runCheckpointer, type KeptCheckpointer, type RunningCheckpointer } from './checkpointer-node.ts';
+/**
+ * 0.15's log replayed as stored: what each use decides on the log, which every live answer must be (R53). For the
+ * suites only: it reads the whole log into memory, every use ever made. Plan PR 8's verifier walks it a stretch at a time.
+ */
+export { replayStored } from './log-replay.ts';
 
 export type NodeVaultConfig = VaultConfig & {
   /**
@@ -37,17 +46,72 @@ export type NodeVaultConfig = VaultConfig & {
    * development. Or one already open, which the vault leaves open.
    */
   database: string | Database;
+  /**
+   * 0.15's uses (docs/design/0.15-plan.md, PR 5): the same database as
+   * `coffre_vault_hot`, whose lock and statement timeouts bound a use, or
+   * one already open; on SQLite, the same `file:` URL. Required.
+   */
+  hotDatabase?: string | Database;
+  /**
+   * 0.15's checkpointer, which this process runs: `memory`, the file it
+   * keeps the newest pair it signed in, where no database writer reaches,
+   * such as `/var/lib/coffre/checkpointer-memory`, writable by the vault's
+   * user alone (its alarms go beside it, in `<memory>.alarms`). Required,
+   * unless the caller seals through a checkpointer of its own
+   * (`VaultOptions.sealThrough` and `heldOutside`).
+   */
+  checkpointer?: { memory: string };
 };
 
-/** The vault in this process. */
+/**
+ * The vault in this process, and under 0.15's log, the default, its
+ * checkpointer, opened before the vault serves, so that no call meets a log
+ * with no checkpoint yet. A configuration without what 0.15 needs is refused.
+ */
 export async function localVault(config: NodeVaultConfig, options: VaultOptions = {}): Promise<LocalVault> {
   const resolved = resolveVaultConfig(config);
-  if (typeof config.database !== 'string') return openLocalVault(config.database, resolved, options);
-  const { db, close } = await openDatabase(config.database);
-  return openLocalVault(db, resolved, options, close).catch(async (error: unknown) => {
+  const log015 = (options.log ?? '0.15') === '0.15';
+  const own = log015 && options.sealThrough === undefined;
+  if (log015 && config.hotDatabase === undefined) {
+    throw new Error("the vault's uses run as a login of their own: set hotDatabase in the vault's configuration, the database as coffre_vault_hot (HOT_DATABASE_URL)");
+  }
+  if (own && config.checkpointer?.memory === undefined) {
+    throw new Error("the vault answers a change once its checkpointer has sealed it: set checkpointer: { memory } in the vault's configuration, the file its signer remembers in (CHECKPOINTER_MEMORY)");
+  }
+  const opened: (() => Promise<void>)[] = [];
+  const open = async (database: string | Database) => {
+    if (typeof database !== 'string') return database;
+    const { db, close } = await openDatabase(database);
+    opened.push(close);
+    return db;
+  };
+  let checkpointer: { stop(): Promise<void> } | null = null;
+  // The checkpointer stopped first, its tick in flight ended, then the databases closed.
+  const close = async () => {
+    await checkpointer?.stop();
+    await Promise.all(opened.map((done) => done()));
+  };
+  try {
+    const db = await open(config.database);
+    // The same URL is the same connection: on SQLite, where it is the same file, two would wait on each other's
+    // writes, a use's and the checkpointer's, past the busy timeout.
+    const hot = config.hotDatabase === undefined ? undefined : config.hotDatabase === config.database ? db : await open(config.hotDatabase);
+    // A use holds one of the hot pool's connections from its call to its answer: at most that many in flight.
+    const connections = (hot as { $client?: { options?: { max?: number } } } | undefined)?.$client?.options?.max;
+    const uses = { ...(connections === undefined ? {} : { connections }), ...options.uses };
+    if (own) {
+      // On Postgres, a connection of its own, which it cuts once it stalls (T169): what a stalled tick awaits holds none of
+      // the vault's. On SQLite, the vault's one: two to one file wait on each other's writes.
+      const url = typeof config.database === 'string' && engineOfUrl(config.database) === 'postgres' ? config.database : null;
+      const where = url === null ? { database: db } : { connect: () => openDatabase(url, { max: 2 }) };
+      const kept = (checkpointer = await keepCheckpointer({ ...where, seed: resolved.signingKeys[0]!, memory: config.checkpointer!.memory }));
+      options = { ...options, sealThrough: kept.sealThrough, heldOutside: kept.heldOutside, sealing: kept.sealing };
+    }
+    return await openLocalVault(db, resolved, { ...options, uses }, close, hot);
+  } catch (error) {
     await close();
     throw error;
-  });
+  }
 }
 
 const METHOD_NAMES = new Set<string>(METHODS);

package/src/objects.ts

@@ -0,0 +1,141 @@
+import { createHash } from 'node:crypto';
+
+import { isCredentialScope, type CallerKind, type CredentialScope, type InstanceRole, type Scope } from '@coffre/core/access';
+import { TOMBSTONE } from '@coffre/core/schemas';
+import type { BindingColumns, ConnectionColumns, CredentialColumns, EnvironmentColumns, SecretColumns, VersionColumns } from '@coffre/core/vault';
+import { storedRole } from '@coffre/db/grants';
+
+import type { BindingInput, ConnectionInput, CredentialInput, EnvironmentInput, Input, InputGrant, Nature, PrincipalInput, SecretInput } from './inputs.ts';
+
+/**
+ * The tables' rows as the objects of the 0.15 log (inputs.ts): what a seal
+ * covers, made from a row's columns alone. One mapping for every reader and
+ * writer of a row, the use path's statement (use.ts) and the change path
+ * (plan, PR 4) alike, so that what one seals the other checks. A row's other
+ * columns, bookkeeping the app updates outside any change (a credential's
+ * `last_used_at`), are no part of its object (docs/design/sealed-inputs.md).
+ *
+ * Each function takes the columns as plain values, whichever query read
+ * them: times in ms since the epoch, uuids as text. Each object is made
+ * from its own rows: an environment is deleted when its own slug is a
+ * tombstone, not its project's (a project's deletion writes its
+ * environments' changes, plan PR 4b). The one column of another row an
+ * object holds is an environment's project's archival, which 0.14 decides
+ * on, kept apart from its own; a project's archive changes each of its
+ * environments. A key's source is its newest reference row's while that
+ * row has not ended.
+ */
+
+/** A credential's columns: `credentials` (a session, a token, a workload's session), as the app sends them too (`prepare`). */
+export type { CredentialColumns };
+
+/**
+ * A credential: a person's on a `user:` principal, a workload's session, or
+ * a bearer's token. A scope that does not parse as one reaches nothing.
+ */
+export function credentialObject(row: CredentialColumns): CredentialInput {
+  const caller: CallerKind = row.principal.startsWith('user:') ? 'person' : row.kind === 'workload' ? 'workload' : 'bearer';
+  return { kind: 'credential', id: row.id, principal: row.principal, caller, scope: scopeOf(row.scope), expiresAt: row.expiresAt, revoked: row.revoked, generation: row.generation };
+}
+
+/** An MCP connection's columns (`mcp_connections`), as the app sends them too. */
+export type { ConnectionColumns };
+
+/** An MCP connection (T147): its columns as the row keeps them. */
+export function connectionObject(row: ConnectionColumns): ConnectionInput {
+  return { kind: 'connection', id: row.id, principal: row.principal, generation: row.generation, expiresAt: row.expiresAt, revoked: row.revoked };
+}
+
+/** A trust binding (PR 3a): its columns as the row keeps them, its scope read as a credential's is. */
+export function bindingObject(row: BindingColumns): BindingInput {
+  return {
+    kind: 'binding', id: row.id, principal: row.principal, generation: row.generation, profile: row.profile, issuer: row.issuer,
+    origin: row.origin, jwksUri: row.jwksUri, claims: row.claims, scope: scopeOf(row.scope), policy: row.policy, revoked: row.revoked,
+  };
+}
+
+function scopeOf(stored: string | null): CredentialScope | null {
+  if (stored === null) return null;
+  let parsed: unknown = null;
+  try {
+    parsed = JSON.parse(stored);
+  } catch {}
+  return isCredentialScope(parsed) ? parsed : [];
+}
+
+/** A member's grant as its object holds it, from its row (`vault_grants`): an environment's with that environment's project. */
+type GrantColumns = Pick<InputGrant, 'projectId' | 'environmentId' | 'environmentSlug' | 'role' | 'expiresAt'>;
+
+/** A member's object, from their row (its role and scope as `storedRole` reads them) and their grants, lapsed ones too. */
+export function principalObject(member: { principal: string; status: string; generation: number; role: InstanceRole; scope: Scope }, grants: readonly GrantColumns[]): PrincipalInput {
+  return {
+    kind: 'principal',
+    principal: member.principal,
+    status: member.status === 'active' ? 'active' : 'removed',
+    generation: member.generation,
+    role: member.role,
+    scope: member.scope,
+    grants: grants.map(({ projectId, environmentId, environmentSlug, role, expiresAt }) => ({ projectId, environmentId, environmentSlug, role, expiresAt })),
+  };
+}
+
+/** A member's role and scope as stored (`owner`, `role`, `scope`), as their object holds them. */
+export function memberStanding(row: { owner: boolean; role: string | null; scope: string | null }): { role: InstanceRole; scope: Scope } {
+  return storedRole(row);
+}
+
+/**
+ * A key's columns (`secrets`, its version's in `secret_versions`),
+ * unarchived: an archived key is no object (`VersionColumns`,
+ * `SecretColumns`: @coffre/core/vault, the app sends them too).
+ */
+export type { SecretColumns, VersionColumns };
+
+/**
+ * A key: its current version, nature and wrapped data key, or a plain
+ * one's digest; or, for a reference, its source, whose value and nature
+ * are its own (R23): a reference holds no version, and is a secret by
+ * itself. A reference that has ended holds neither (`ended`).
+ */
+export function secretObject(row: SecretColumns): SecretInput {
+  const { id, projectId, environmentId, source, version } = row;
+  if (source !== null || version === null) {
+    return { kind: 'secret', id, projectId, environmentId, version: '', nature: 'secret', key: null, digest: null, source, reference: source === null ? null : row.reference };
+  }
+  const nature: Nature = version.sensitive ? 'sensitive' : version.plaintext !== null ? 'plain' : 'secret';
+  const key = nature === 'plain' ? null : { kekProvider: version.kekProvider, kekId: version.kekId, kekVersion: version.kekVersion, bytes: version.wrappedDek };
+  const digest = nature === 'plain' ? plainDigest(version.plaintext!) : null;
+  return { kind: 'secret', id, projectId, environmentId, version: version.id, nature, key, digest, source: null, reference: null };
+}
+
+/** A plain value's digest, as its object holds it: SHA-256 of its UTF-8 text, base64. */
+export function plainDigest(text: string): string {
+  return createHash('sha256').update(text, 'utf8').digest('base64');
+}
+
+/** An environment's columns (`environments`), as the app sends them too (@coffre/core/vault). */
+export type { EnvironmentColumns };
+
+/**
+ * An environment: its slug, as it was before any tombstone, whether it was
+ * deleted, and its own archival and its project's, apart. A deleted one
+ * holds no project's archival: it reads nothing, and its project archived
+ * or restored after changes nothing of it.
+ */
+export function environmentObject(row: EnvironmentColumns): EnvironmentInput {
+  const tomb = row.slug.indexOf(TOMBSTONE);
+  return {
+    kind: 'environment', id: row.id, projectId: row.projectId, slug: tomb < 0 ? row.slug : row.slug.slice(0, tomb),
+    owner: row.owner, parentId: row.parentId, protected: row.protected === true, deleted: tomb >= 0, archived: row.archived, projectArchived: tomb < 0 && row.projectArchived,
+  };
+}
+
+/**
+ * The roles and the policy: each one `log_config` row whose value is the
+ * object as the change that made it wrote it (0022's `change_input`:
+ * genesis's `value`), read whole. A value that is not that object fails
+ * its seal.
+ */
+export function configObject(value: string): Input {
+  return JSON.parse(value) as Input;
+}