@coffre/vault 0.0.0 → 0.1.0

package/src/node.ts

@@ -0,0 +1,141 @@
+/**
+ * The vault on Node, one of two ways, each over the database the server
+ * uses, through the vault's own login:
+ *
+ * - in the server's own process: `vault: await localVault({ database, ...keys })`;
+ * - as a process of its own, which the server reaches over a Unix socket:
+ *   `serveVault({ socket, database, ...keys })` there, and
+ *   `vault: connectVault(socket)` in the server.
+ *
+ * The second keeps every key out of the process that faces the network. The
+ * socket is the whole of its authentication: a file only the vault's user
+ * and the group it shares with the server may open, so no port to reach and
+ * no shared secret to leak. Each call is one HTTP POST over it, `/<method>`
+ * with the arguments as a JSON array, and refusals come back as values, as
+ * from any vault; only a failure is an error.
+ */
+import { chmodSync, existsSync, lstatSync, rmSync } from 'node:fs';
+import { Agent, createServer, request as httpRequest, type IncomingMessage } from 'node:http';
+
+import type { Vault } from '@coffre/core/vault';
+import type { Database } from '@coffre/db';
+import { openDatabase } from '@coffre/db/connect';
+
+import { resolveVaultConfig, type VaultConfig } from './config.ts';
+import { METHODS, openLocalVault, type LocalVault } from './local.ts';
+import type { VaultOptions } from './vault.ts';
+
+export type { Vault, VaultConfig };
+export * from './index.ts';
+export type { LocalVault, VaultOptions };
+
+export type NodeVaultConfig = VaultConfig & {
+  /**
+   * The database the server uses, as the vault's own login:
+   * `postgres://coffre_vault_runtime:…@…/coffre`, or a `file:` URL for local
+   * development. Or one already open, which the vault leaves open.
+   */
+  database: string | Database;
+};
+
+/** The vault in this process. */
+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) => {
+    await close();
+    throw error;
+  });
+}
+
+const METHOD_NAMES = new Set<string>(METHODS);
+const MAX_BODY = 8 * 1024 * 1024;
+
+export type VaultServer = { socket: string; close(): Promise<void> };
+
+/**
+ * The vault as a process of its own, answering on a Unix socket. The socket
+ * is made `0660`: put it in a directory the server's user can reach through
+ * a shared group, e.g. `/run/coffre/vault.sock`.
+ */
+export async function serveVault(config: NodeVaultConfig & { socket: string }): Promise<VaultServer> {
+  const vault = await localVault(config);
+  const server = createServer(async (req, res) => {
+    const name = (req.url ?? '').slice(1);
+    const reply = (status: number, body: unknown) => {
+      res.writeHead(status, { 'content-type': 'application/json' });
+      res.end(JSON.stringify(body));
+    };
+    if (req.method !== 'POST' || !METHOD_NAMES.has(name)) return reply(404, { error: 'not a vault call' });
+    try {
+      const args = JSON.parse(await readBody(req)) as unknown;
+      if (!Array.isArray(args)) return reply(400, { error: 'the arguments must be a JSON array' });
+      const result = await (vault[name as keyof Vault] as (...args: unknown[]) => Promise<unknown>)(...args);
+      reply(200, result === undefined ? {} : { result });
+    } catch (error) {
+      console.error(`vault ${name} failed`, error);
+      reply(500, { error: error instanceof Error ? error.message : 'the vault failed' });
+    }
+  });
+
+  // A socket file left by a vault that did not stop cleanly would make
+  // listen fail; anything else at that path is not ours to remove.
+  if (existsSync(config.socket)) {
+    if (!lstatSync(config.socket).isSocket()) throw new Error(`${config.socket} exists and is not a socket`);
+    rmSync(config.socket);
+  }
+  await new Promise<void>((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(config.socket, () => resolve());
+  });
+  chmodSync(config.socket, 0o660);
+
+  return {
+    socket: config.socket,
+    close: () =>
+      new Promise<void>((resolve) => {
+        server.close(() => void vault.close().then(resolve));
+        server.closeAllConnections();
+      }),
+  };
+}
+
+/** The vault that `serveVault` runs, from the server's side of its socket. */
+export function connectVault(socket: string): Vault {
+  const agent = new Agent({ keepAlive: true });
+  const call = (name: string) => (...args: unknown[]) =>
+    new Promise<unknown>((resolve, reject) => {
+      const body = JSON.stringify(args);
+      const req = httpRequest(
+        {
+          socketPath: socket,
+          agent,
+          method: 'POST',
+          path: `/${name}`,
+          headers: { 'content-type': 'application/json', 'content-length': Buffer.byteLength(body) },
+        },
+        (res) => {
+          readBody(res).then((text) => {
+            const payload = JSON.parse(text) as { result?: unknown; error?: string };
+            if (res.statusCode === 200) resolve(payload.result);
+            else reject(new Error(`vault ${name}: ${payload.error ?? `status ${res.statusCode}`}`));
+          }, reject);
+        },
+      );
+      req.on('error', (error) => reject(new Error(`the vault at ${socket} is unreachable: ${error.message}`)));
+      req.end(body);
+    });
+  return Object.fromEntries(METHODS.map((name) => [name, call(name)])) as unknown as Vault;
+}
+
+async function readBody(stream: IncomingMessage): Promise<string> {
+  const chunks: Buffer[] = [];
+  let size = 0;
+  for await (const chunk of stream) {
+    size += (chunk as Buffer).length;
+    if (size > MAX_BODY) throw new Error('the message is too large');
+    chunks.push(chunk as Buffer);
+  }
+  return Buffer.concat(chunks).toString('utf8');
+}

package/src/replay.ts

@@ -0,0 +1,150 @@
+import type { StoredEntry } from '@coffre/core/audit';
+import type { AccessFault, FaultGrant } from '@coffre/core/vault';
+import type { Queryable } from '@coffre/db';
+
+import { ACCESS_ACTIONS, allMembers, grants, vaultEntriesOf, type GrantRow, type Member, type Place } from './store.ts';
+
+export { ACCESS_ACTIONS };
+
+const BATCH = 1000;
+
+/**
+ * Why the members and grants in the database do not follow from the
+ * vault's entries, or null when they do; `describeAccessFault` words it.
+ * Every change to either is logged in the transaction that makes it, with
+ * the row's times taken from its entry, so replaying the allowed ones from
+ * the first gives the tables back, and a row the log does not explain was
+ * written around the vault: a grant inserted with the database's own login,
+ * a removal undone.
+ *
+ * Call it after the chain is verified, in the same snapshot, so every entry
+ * it replays carries the vault's MAC.
+ *
+ * Grants are compared as they are live at `at`. Clearing one that has
+ * lapsed changes nothing anyone holds, so it is not logged.
+ */
+export async function replay(db: Queryable, at: number): Promise<AccessFault | null> {
+  const state: Replayed = { members: new Map(), held: new Map() };
+  for (let after = -1n; ; ) {
+    const batch = await vaultEntriesOf(db, ACCESS_ACTIONS, after, BATCH);
+    for (const row of batch) {
+      const fault = apply(state, row);
+      if (fault !== null) return fault;
+    }
+    if (batch.length < BATCH) break;
+    after = batch[batch.length - 1].seq;
+  }
+  const { members, held } = state;
+  const stored = new Map((await allMembers(db)).map((member) => [member.principal, member]));
+  for (const principal of [...new Set([...stored.keys(), ...members.keys()])].sort()) {
+    const [inStore, inLog] = [stored.get(principal), members.get(principal)];
+    if (inLog === undefined) return { kind: 'unlogged-member', principal };
+    if (inStore === undefined) return { kind: 'missing-member', principal };
+    const fields = MEMBER_FIELDS.filter(([field]) => inStore[field] !== inLog[field]).map(([, column]) => column);
+    if (fields.length > 0) return { kind: 'member-differs', principal, fields };
+  }
+
+  const live = (grant: GrantRow) => grant.expiresAt === null || grant.expiresAt > at;
+  const logged = new Set([...held.values()].flatMap((grantsOf) => [...grantsOf.values()]).filter(live).map(grantKey));
+  const inStore = new Set((await grants(db)).filter(live).map(grantKey));
+  const extra = [...inStore].sort().find((grant) => !logged.has(grant));
+  if (extra !== undefined) return { kind: 'unlogged-grant', grant: faultGrant(extra) };
+  const missing = [...logged].sort().find((grant) => !inStore.has(grant));
+  if (missing !== undefined) return { kind: 'missing-grant', grant: faultGrant(missing) };
+  return null;
+}
+
+/** A member as the log says they are: their row, but for the MAC, which only the store has. */
+export type LoggedMember = Omit<Member, 'mac'>;
+
+/** Who the log says is a member, and what each holds, as far as it has been replayed. */
+export type Replayed = { members: Map<string, LoggedMember>; held: Map<string, Map<string, GrantRow>> };
+
+/** One access entry, authenticated, applied to `state`; a fault when it changes someone never admitted. */
+export function apply(state: Replayed, row: StoredEntry): AccessFault | null {
+  const principal = row.subjectPrincipal!;
+  const detail = JSON.parse(row.metadata) as Record<string, unknown>;
+  const place: Place = { projectId: row.projectId!, environmentId: row.environmentId };
+  const grantsOf = state.held.get(principal) ?? new Map<string, GrantRow>();
+  state.held.set(principal, grantsOf);
+  const before = state.members.get(principal);
+  const changed = { statusChangedAt: row.occurredAt, statusChangedBy: row.actor };
+  switch (row.action) {
+    case 'member.add':
+    case 'member.restore':
+      state.members.set(principal, {
+        principal,
+        status: 'active',
+        owner: detail.owner === true,
+        generation: before?.generation ?? 0,
+        createdAt: before?.createdAt ?? row.occurredAt,
+        createdBy: before?.createdBy ?? row.actor,
+        accessSeq: row.seq,
+        ...changed,
+      });
+      return null;
+    case 'member.owner':
+      if (before === undefined) return { kind: 'unadmitted-change', seq: Number(row.seq), principal };
+      state.members.set(principal, { ...before, owner: detail.owner === true, accessSeq: row.seq });
+      return null;
+    case 'member.remove': {
+      if (before === undefined) return { kind: 'unadmitted-change', seq: Number(row.seq), principal };
+      // A removal names the generation it moved to; one before this format
+      // was always the next.
+      const generation = typeof detail.generation === 'number' ? detail.generation : before.generation + 1;
+      state.members.set(principal, { ...before, status: 'removed', owner: false, generation, accessSeq: row.seq, ...changed });
+      grantsOf.clear();
+      return null;
+    }
+    case 'access.grant':
+      grantsOf.set(placeKey(place), {
+        principal,
+        ...place,
+        role: detail.role as string,
+        expiresAt: detail.expiresAt === null ? null : Date.parse(detail.expiresAt as string),
+        grantedAt: row.occurredAt,
+        grantedBy: row.actor,
+      });
+      if (before !== undefined) state.members.set(principal, { ...before, accessSeq: row.seq });
+      return null;
+    case 'access.revoke':
+      grantsOf.delete(placeKey(place));
+      if (before !== undefined) state.members.set(principal, { ...before, accessSeq: row.seq });
+      return null;
+  }
+  return null;
+}
+
+/** A member's fields, and the columns a fault names them by. */
+const MEMBER_FIELDS = [
+  ['status', 'status'],
+  ['owner', 'owner'],
+  ['generation', 'generation'],
+  ['createdAt', 'created_at'],
+  ['createdBy', 'created_by'],
+  ['statusChangedAt', 'status_changed_at'],
+  ['statusChangedBy', 'status_changed_by'],
+  ['accessSeq', 'access_seq'],
+] as const satisfies readonly (readonly [keyof LoggedMember, string])[];
+
+/** A grant's place: its environment, or its project when it has none. */
+function placeKey(place: Place): string {
+  return place.environmentId ?? place.projectId;
+}
+
+function grantKey(grant: GrantRow): string {
+  return JSON.stringify([
+    grant.principal,
+    grant.projectId,
+    grant.environmentId,
+    grant.role,
+    grant.expiresAt,
+    grant.grantedAt,
+    grant.grantedBy,
+  ]);
+}
+
+function faultGrant(key: string): FaultGrant {
+  const [principal, projectId, environmentId, role] = JSON.parse(key) as [string, string, string | null, string];
+  return { principal, projectId, environmentId, role };
+}

package/src/rows.ts

@@ -0,0 +1,67 @@
+import { createHmac, hkdfSync, timingSafeEqual } from 'node:crypto';
+
+import type { GrantRow, Member } from './store.ts';
+
+/**
+ * The MAC over each member's row and grants: what makes a row written
+ * around the vault, by anyone who can write the database but does not hold
+ * its signing key, one the vault refuses rather than trusts.
+ *
+ * One MAC per member, over the row and the member's grants as a sorted set,
+ * lapsed ones included, rather than one per row: a grant deleted fails it as
+ * surely as one added or edited. `access_seq` is in it too, so a genuine row
+ * put back from before a later change still names the older entry, which the
+ * log has moved past (vault.ts, `#integrity`).
+ *
+ * A change to what is covered is a new version of the tuple, never an edit.
+ */
+
+/** The key member rows are sealed under, derived from the signing key: one more secret to hold, not one more to keep. */
+export function rowKey(signingKey: Uint8Array): Buffer {
+  return Buffer.from(hkdfSync('sha256', signingKey, new Uint8Array(0), 'coffre.vault.rows.v1', 32));
+}
+
+/** A member's grants as the MAC covers them: each one's place, role, end and grant, as a sorted set. */
+export function grantSet(grants: readonly GrantRow[]): string[] {
+  return grants
+    .map((grant) => [
+      grant.environmentId === null ? 'project' : 'environment',
+      grant.environmentId ?? grant.projectId,
+      grant.role,
+      grant.expiresAt,
+      grant.grantedAt,
+      grant.grantedBy,
+    ])
+    .map((tuple) => JSON.stringify(tuple))
+    .sort();
+}
+
+/** Whether two reads of a member's grants are the same set, as the MAC sees them. */
+export function sameGrants(a: readonly GrantRow[], b: readonly GrantRow[]): boolean {
+  const [x, y] = [grantSet(a), grantSet(b)];
+  return x.length === y.length && x.every((tuple, i) => tuple === y[i]);
+}
+
+export function memberMac(key: Buffer, member: Omit<Member, 'mac'>, grants: readonly GrantRow[]): Buffer {
+  const held = grantSet(grants);
+  const tuple = [
+    'coffre.vault.member.v1',
+    member.principal,
+    member.status,
+    member.owner,
+    member.generation,
+    member.accessSeq.toString(),
+    member.createdAt,
+    member.createdBy,
+    member.statusChangedAt,
+    member.statusChangedBy,
+    held,
+  ];
+  return createHmac('sha256', key).update(JSON.stringify(tuple)).digest();
+}
+
+/** Whether `member`'s MAC is the vault's, over this row and these grants. */
+export function sealed(key: Buffer, member: Member, grants: readonly GrantRow[]): boolean {
+  const expected = memberMac(key, member, grants);
+  return member.mac.length === expected.length && timingSafeEqual(member.mac, expected);
+}