@coffre/vault 0.10.1 → 0.10.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coffre/vault",
-  "version": "0.10.1",
+  "version": "0.10.2",
   "description": "coffre's vault: keys, grants and members, in the database the app uses, as a Cloudflare Worker or on Node.",
   "license": "MIT",
   "repository": {
@@ -36,8 +36,8 @@
   },
   "dependencies": {
     "drizzle-orm": "0.45.2",
-    "@coffre/core": "0.10.1",
-    "@coffre/db": "0.10.1"
+    "@coffre/core": "0.10.2",
+    "@coffre/db": "0.10.2"
   },
   "devDependencies": {
     "@types/node": "26.1.1",

package/src/config.ts

@@ -2,13 +2,14 @@ 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`. */
+/** At most `count` distinct data keys unwrapped per principal in any `windowMs`. */
 export type BulkLimit = { count: number; windowMs: number };
 
 /**
- * 1000 keys in 15 minutes: twenty `coffre run`s of a 50-key environment
- * back to back, which no person or deploy pipeline does, while a script
- * pulling every secret it can reach stops within a few seconds.
+ * 1000 different keys in 15 minutes, which no person or deploy pipeline
+ * reads, while a script pulling every secret it can reach stops within a
+ * few seconds. A key read again counts once: a 50-key `coffre run` is 50
+ * however often it runs.
  */
 export const DEFAULT_BULK_LIMIT: BulkLimit = { count: 1000, windowMs: 15 * 60_000 };
 
@@ -62,7 +63,7 @@ export type VaultConfig = {
    * 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. */
+  /** At most `count` distinct data keys unwrapped per principal in any `windowMinutes`; 1000 in 15 unless set. */
   bulkLimit?: { count: number; windowMinutes: number };
   /**
    * @deprecated Gone in 0.10, and refused: each key says who sees it now. Mark

package/src/snapshot.postgres.ts

@@ -0,0 +1,97 @@
+import { TOMBSTONE } from '@coffre/core/schemas';
+import { ACCESS_ACTIONS } from '@coffre/core/vault';
+import { sql, type SQL } from 'drizzle-orm';
+
+import type { Asked } from './snapshot.ts';
+
+/** An entry of `audit_log` aliased `e`, as JSON (`RawEntry`): whole numbers past 2^53 as text, bytes as hex. */
+const ENTRY = sql.raw(`json_build_object(
+  'seq', e.seq::text, 'author', e.author, 'keyId', e.key_id, 'occurredAt', e.occurred_at, 'actor', e.actor, 'action', e.action,
+  'decision', e.decision, 'code', e.code, 'subjectPrincipal', e.subject_principal, 'projectId', e.project_id,
+  'environmentId', e.environment_id, 'secretId', e.secret_id, 'secretVersionId', e.secret_version_id,
+  'operationId', e.operation_id, 'requestId', e.request_id, 'sourceIp', e.source_ip, 'relatedSeq', e.related_seq::text,
+  'metadata', e.metadata, 'prevHash', encode(e.prev_hash, 'hex'), 'mac', encode(e.mac, 'hex'), 'hash', encode(e.hash, 'hex'))`);
+
+const NOW = sql.raw('(extract(epoch from clock_timestamp()) * 1000)::bigint');
+
+/** `snapshot`'s statement on Postgres: one row, one JSON column. Each part reads one index range. */
+export function snapshotQuery(asked: Asked): SQL {
+  const principals = sql`${sql.param([...asked.principals])}::text[]`;
+  const environments = sql`${sql.param([...(asked.environments ?? [])])}::uuid[]`;
+  const references = sql`${sql.param((asked.references ?? []).map(String))}::bigint[]`;
+  const actions = sql`${sql.param([...ACCESS_ACTIONS])}::text[]`;
+  const tomb = `%${TOMBSTONE}%`;
+  const released = asked.released;
+  // The head only if nobody holds it: a statement never waits for it, so all it reads is as of when it took it (`snapshot`).
+  const head = asked.head === true
+    ? sql`, head AS (SELECT next_seq, head_hash FROM audit_chain_head WHERE only_row FOR UPDATE SKIP LOCKED)`
+    : sql``;
+  return sql`
+    WITH policy AS (
+      SELECT * FROM audit_log WHERE author = 'vault' AND action = 'policy.change' AND decision = 'allow' ORDER BY seq DESC LIMIT 1
+    )${head}
+    SELECT json_build_object(
+      'at', ${NOW},
+      'head', ${asked.head === true ? sql`(SELECT json_build_object('nextSeq', next_seq::text, 'hash', encode(head_hash, 'hex')) FROM head)` : sql`NULL`},
+      'last', ${asked.head === true ? sql`(SELECT json_build_object('seq', seq::text, 'hash', encode(hash, 'hex')) FROM audit_log ORDER BY seq DESC LIMIT 1)` : sql`NULL`},
+      'rotation', ${asked.head === true
+        ? sql`(SELECT ${ENTRY} FROM audit_log e WHERE author = 'vault' AND action = 'key.rotate' AND decision = 'allow' ORDER BY seq DESC LIMIT 1)`
+        : sql`NULL`},
+      'members', ${asked.members === true
+        ? sql`(SELECT coalesce(json_agg(json_build_object(
+            'principal', principal, 'status', status, 'owner', owner, 'role', role, 'scope', scope, 'generation', generation,
+            'createdAt', created_at, 'createdBy', created_by, 'statusChangedAt', status_changed_at, 'statusChangedBy', status_changed_by,
+            'accessSeq', access_seq::text, 'mac', encode(mac, 'hex'))), '[]') FROM vault_members WHERE principal = ANY(${principals}))`
+        : sql`'[]'::json`},
+      'grants', (
+        SELECT coalesce(json_agg(json_build_object(
+          'principal', g.principal, 'projectId', coalesce(g.project_id, env.project_id), 'environmentId', g.environment_id,
+          'environmentSlug', g.environment_slug, 'role', g.role, 'expiresAt', g.expires_at, 'grantedAt', g.granted_at, 'grantedBy', g.granted_by)), '[]')
+        FROM vault_grants g LEFT JOIN environments env ON env.id = g.environment_id
+        WHERE g.principal = ANY(${principals})
+      ),
+      'access', (
+        SELECT coalesce(json_agg(${ENTRY}), '[]')
+        FROM unnest(${principals}) AS asked (principal)
+        CROSS JOIN LATERAL (
+          SELECT * FROM audit_log
+          WHERE author = 'vault' AND subject_principal = asked.principal AND action = ANY(${actions}) AND decision = 'allow'
+          ORDER BY seq DESC LIMIT 1
+        ) e
+      ),
+      'policy', (SELECT ${ENTRY} FROM policy e),
+      'environments', (
+        SELECT coalesce(json_agg(json_build_object(
+          'id', env.id, 'projectId', env.project_id, 'slug', env.slug, 'owner', env.owner, 'parentId', env.parent_id,
+          'deleted', env.slug LIKE ${tomb} OR project.slug LIKE ${tomb},
+          'archived', env.archived_at IS NOT NULL OR project.archived_at IS NOT NULL)), '[]')
+        FROM environments env JOIN projects project ON project.id = env.project_id
+        -- One list of ids, each found by the primary key.
+        WHERE env.id = ANY(ARRAY(
+          SELECT unnest(${environments})
+          UNION SELECT parent_id FROM environments WHERE id = ANY(${environments}) AND owner IS NOT NULL
+          -- What the newest policy protects, by the ids its JSON names; one that is no UUID names nothing.
+          UNION SELECT (place #>> '{}')::uuid FROM policy, jsonb_path_query(policy.metadata::jsonb, '$.policy.protected[*].environmentId') AS place
+          WHERE (place #>> '{}') ~* '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
+        ))
+      ),
+      'ended', (
+        SELECT coalesce(json_agg(related_seq::text), '[]') FROM audit_log
+        WHERE author = 'vault' AND action = 'reference.end' AND decision = 'allow' AND related_seq = ANY(${references})
+      ),
+      'released', ${released === undefined
+        ? sql`0`
+        : sql`(
+          SELECT count(DISTINCT key) FROM (
+            -- A read of one key names it; of several at one place, lists them (readsByPlace, vault.ts). An entry, or an
+            -- item of its list, that names no key, which only a forged entry is, counts as one key of its own.
+            SELECT coalesce(e.secret_id::text, CASE jsonb_typeof(one -> 'secretId') WHEN 'string' THEN one ->> 'secretId' END, 'entry:' || e.seq) FROM audit_log e
+            -- Each item of a list, never what lax paths would make of an object; silent, as strict paths fail on what is missing.
+            LEFT JOIN LATERAL jsonb_path_query(CASE WHEN e.secret_id IS NULL THEN e.metadata::jsonb END, 'strict $.secrets ? (@.type() == "array")[*]', '{}', true) AS one ON true
+            WHERE e.author = 'vault' AND e.actor = ${released.principal} AND e.action = 'secret.read' AND e.decision = 'allow'
+              AND e.occurred_at > ${NOW} + ${released.clockOffsetMs} - ${released.windowMs}
+            UNION ALL SELECT unnest(${sql.param([...released.keys])}::text[])
+          ) AS released (key)
+        )`}
+    ) AS snapshot`;
+}

package/src/snapshot.sqlite.ts

@@ -0,0 +1,103 @@
+import { TOMBSTONE } from '@coffre/core/schemas';
+import { ACCESS_ACTIONS } from '@coffre/core/vault';
+import { sql, type SQL } from 'drizzle-orm';
+
+import type { Asked } from './snapshot.ts';
+
+/**
+ * An entry of `audit_log` aliased `e`, as JSON (`RawEntry`), bytes as hex.
+ * A JSON value loses its type leaving a subquery, so whoever takes one
+ * from a subquery wraps it in `json(…)`.
+ */
+const ENTRY = sql.raw(`json_object(
+  'seq', e.seq, 'author', e.author, 'keyId', e.key_id, 'occurredAt', e.occurred_at, 'actor', e.actor, 'action', e.action,
+  'decision', e.decision, 'code', e.code, 'subjectPrincipal', e.subject_principal, 'projectId', e.project_id,
+  'environmentId', e.environment_id, 'secretId', e.secret_id, 'secretVersionId', e.secret_version_id,
+  'operationId', e.operation_id, 'requestId', e.request_id, 'sourceIp', e.source_ip, 'relatedSeq', e.related_seq,
+  'metadata', e.metadata, 'prevHash', hex(e.prev_hash), 'mac', hex(e.mac), 'hash', hex(e.hash))`);
+
+const NOW = sql.raw(`CAST(unixepoch('subsec') * 1000 AS INTEGER)`);
+
+/**
+ * `snapshot`'s statement on SQLite, the same as on Postgres. Nothing is
+ * locked: one transaction runs at a time (connect.ts), so the head is the
+ * last entry's.
+ */
+export function snapshotQuery(asked: Asked): SQL {
+  const principals = JSON.stringify(asked.principals);
+  const environments = JSON.stringify(asked.environments ?? []);
+  const references = JSON.stringify((asked.references ?? []).map(Number));
+  const actions = JSON.stringify(ACCESS_ACTIONS);
+  const tomb = `%${TOMBSTONE}%`;
+  const released = asked.released;
+  const head = asked.head === true;
+  return sql`
+    WITH policy AS (
+      SELECT * FROM audit_log WHERE author = 'vault' AND action = 'policy.change' AND decision = 'allow' ORDER BY seq DESC LIMIT 1
+    )
+    SELECT json_object(
+      'at', ${NOW},
+      'head', ${head ? sql`json((SELECT json_object('nextSeq', next_seq, 'hash', hex(head_hash)) FROM audit_chain_head WHERE only_row))` : sql`NULL`},
+      'last', ${head ? sql`json((SELECT json_object('seq', seq, 'hash', hex(hash)) FROM audit_log ORDER BY seq DESC LIMIT 1))` : sql`NULL`},
+      'rotation', ${head
+        ? sql`json((SELECT ${ENTRY} FROM audit_log e WHERE author = 'vault' AND action = 'key.rotate' AND decision = 'allow' ORDER BY seq DESC LIMIT 1))`
+        : sql`NULL`},
+      'members', json(${asked.members === true
+        ? sql`(SELECT json_group_array(json_object(
+            'principal', principal, 'status', status, 'owner', owner, 'role', role, 'scope', scope, 'generation', generation,
+            'createdAt', created_at, 'createdBy', created_by, 'statusChangedAt', status_changed_at, 'statusChangedBy', status_changed_by,
+            'accessSeq', access_seq, 'mac', hex(mac))) FROM vault_members WHERE principal IN (SELECT value FROM json_each(${principals})))`
+        : sql`'[]'`}),
+      'grants', json((
+        SELECT json_group_array(json_object(
+          'principal', g.principal, 'projectId', coalesce(g.project_id, env.project_id), 'environmentId', g.environment_id,
+          'environmentSlug', g.environment_slug, 'role', g.role, 'expiresAt', g.expires_at, 'grantedAt', g.granted_at, 'grantedBy', g.granted_by))
+        FROM vault_grants g LEFT JOIN environments env ON env.id = g.environment_id
+        WHERE g.principal IN (SELECT value FROM json_each(${principals}))
+      )),
+      'access', json((
+        SELECT json_group_array(json(newest)) FROM (
+          SELECT (
+            SELECT ${ENTRY} FROM audit_log e
+            WHERE author = 'vault' AND subject_principal = asked.value AND action IN (SELECT value FROM json_each(${actions})) AND decision = 'allow'
+            ORDER BY seq DESC LIMIT 1
+          ) AS newest
+          FROM json_each(${principals}) AS asked
+        ) WHERE newest IS NOT NULL
+      )),
+      'policy', json((SELECT ${ENTRY} FROM policy e)),
+      'environments', json((
+        SELECT json_group_array(json_object(
+          'id', env.id, 'projectId', env.project_id, 'slug', env.slug, 'owner', env.owner, 'parentId', env.parent_id,
+          'deleted', env.slug LIKE ${tomb} OR project.slug LIKE ${tomb},
+          'archived', env.archived_at IS NOT NULL OR project.archived_at IS NOT NULL))
+        FROM environments env JOIN projects project ON project.id = env.project_id
+        WHERE env.id IN (SELECT value FROM json_each(${environments}))
+          OR env.id IN (SELECT parent_id FROM environments WHERE id IN (SELECT value FROM json_each(${environments})) AND owner IS NOT NULL)
+          OR env.id IN (
+            SELECT json_extract(place.value, '$.environmentId')
+            FROM policy, json_each(policy.metadata, '$.policy.protected') AS place
+            -- Of a forged entry's, an element that is no object names nothing: json_extract would fail on a string.
+            WHERE json_valid(policy.metadata) AND json_type(policy.metadata, '$.policy.protected') = 'array' AND place.type = 'object'
+          )
+      )),
+      'ended', json((
+        SELECT json_group_array(related_seq) FROM audit_log
+        WHERE author = 'vault' AND action = 'reference.end' AND decision = 'allow' AND related_seq IN (SELECT value FROM json_each(${references}))
+      )),
+      'released', ${released === undefined
+        ? sql`0`
+        : sql`(
+          SELECT count(DISTINCT key) FROM (
+            -- A read of one key names it; of several at one place, lists them (readsByPlace, vault.ts). An entry, or an
+            -- item of its list, that names no key, which only a forged entry is, counts as one key of its own.
+            SELECT coalesce(e.secret_id, CASE WHEN one.type = 'object' AND json_type(one.value, '$.secretId') = 'text' THEN json_extract(one.value, '$.secretId') END, 'entry:' || e.seq) AS key
+            FROM audit_log e
+            LEFT JOIN json_each(CASE WHEN e.secret_id IS NULL AND json_type(e.metadata, '$.secrets') = 'array' THEN e.metadata END, '$.secrets') AS one
+            WHERE e.author = 'vault' AND e.actor = ${released.principal} AND e.action = 'secret.read' AND e.decision = 'allow'
+              AND e.occurred_at > ${NOW} + ${released.clockOffsetMs} - ${released.windowMs}
+            UNION ALL SELECT value FROM json_each(${JSON.stringify(released.keys)})
+          )
+        )`}
+    ) AS snapshot`;
+}

package/src/snapshot.ts

@@ -0,0 +1,191 @@
+import type { StoredEntry } from '@coffre/core/audit';
+import type { Queryable, Transaction } from '@coffre/db';
+import { LogHeadMismatch, lockLogHead } from '@coffre/db/log';
+import { engineOf, rowsOf } from '@coffre/db/dialect';
+import type { GrantRow } from '@coffre/db/grants';
+
+import { snapshotQuery as postgres } from './snapshot.postgres.ts';
+import { snapshotQuery as sqlite } from './snapshot.sqlite.ts';
+import * as store from './store.ts';
+import type { EnvironmentRow, Member } from './store.ts';
+
+/**
+ * What a decision reads, or `access`, in one statement: one round trip, and
+ * one snapshot of the database, so its parts agree with each other.
+ *
+ * In a decision, the same statement locks the log's head, but only if it
+ * is free (`SKIP LOCKED`). Postgres takes a statement's snapshot when it
+ * starts, so one that waited for the lock would have read everything but
+ * the head as it was before the wait: a policy changed, a place deleted, a
+ * grant written around the vault while it waited would be missed. A
+ * statement that never waits reads all of it as of the lock. When another
+ * transaction holds the head, the decision waits for it in a statement of
+ * its own, then reads again, holding it. The read checks that the head names
+ * the last entry it saw, too (`current`): one taken between the snapshot and
+ * the lock, by an append that committed in that instant, is read again. That
+ * check sees a commit only through the head it moved, which holds because
+ * every change a decision reads commits with an entry under the head: the
+ * vault's own decisions, and the app's writes to places, each `audited`
+ * with its entry.
+ */
+export type Snapshot = {
+  /** The database's clock, milliseconds since the epoch. */
+  at: number;
+  /** The rows of `asked.members`, by principal; those with none are not in the map. */
+  members: Map<string, Member>;
+  /** Every grant of each asked principal, lapsed ones too. */
+  grants: Map<string, GrantRow[]>;
+  /** The newest allowed access entry in the vault's name about each asked principal, unchecked. */
+  newestAccess: Map<string, StoredEntry>;
+  /** The newest allowed `policy.change` in the vault's name, unchecked. */
+  newestPolicy: StoredEntry | null;
+  /**
+   * The asked environments, the environments each personal config among
+   * them is a config of, and those the newest `policy.change` names, by id.
+   */
+  environments: Map<string, EnvironmentRow>;
+  /** Of the asked `reference.create` entries, those a `reference.end` of the vault's names, allowed. */
+  ended: Set<bigint>;
+  /**
+   * How many distinct keys `asked.released.principal` holds released within
+   * its window once it is given `asked.released.keys` too: a key released
+   * again, or asked for again, counts once.
+   */
+  released: number;
+  /** The log's head, locked, with the last entry and the newest `key.rotate`; null unless asked, or held by another. */
+  head: LockedHead | null;
+};
+
+export type LockedHead = {
+  nextSeq: bigint;
+  headHash: Buffer;
+  /** The log's last entry, as this statement's snapshot has it. */
+  last: { seq: bigint; hash: Buffer } | null;
+  /** The vault's newest `key.rotate`, allowed, unchecked. */
+  rotation: StoredEntry | null;
+};
+
+/** What to read. */
+export type Asked = {
+  /** Whose grants and newest access entry; with `members`, their rows too, unlocked. */
+  principals: readonly string[];
+  members?: boolean;
+  environments?: readonly string[];
+  references?: readonly bigint[];
+  /**
+   * One principal's releases within the last `windowMs` of the clock, moved
+   * on by `clockOffsetMs` as the vault's is, with `keys`, secret ids, besides.
+   */
+  released?: { principal: string; keys: readonly string[]; windowMs: number; clockOffsetMs: number };
+  /** Lock the log's head first. */
+  head?: boolean;
+};
+
+/** One statement's read, as `Snapshot` says; with the head, two more when another holds it. */
+export async function snapshot(tx: Transaction, asked: Asked): Promise<Snapshot>;
+export async function snapshot(db: Queryable, asked: Asked & { head?: false }): Promise<Snapshot>;
+export async function snapshot(db: Queryable, asked: Asked): Promise<Snapshot> {
+  const read = () => readOnce(db, asked);
+  const first = await read();
+  if (asked.head !== true || (first.head !== null && current(first.head))) return first;
+  // Held by another, or moved in the instant before the lock: everything again, once the head is this transaction's.
+  // Asked for the head, `db` is a transaction (the overloads above).
+  if (first.head === null) await lockLogHead(db as Transaction);
+  const again = await read();
+  if (again.head === null) throw new Error("the log's head, held by this transaction, was read as held by another");
+  // Held, nothing appends: a head that names another last entry was moved, or the log written, around it (`appendEntries`).
+  if (!current(again.head)) {
+    throw new LogHeadMismatch(`the log's head says entry ${again.head.nextSeq} comes next, but the log ends ${again.head.last === null ? 'empty' : `at entry ${again.head.last.seq}`}, or with another hash`);
+  }
+  return again;
+}
+
+/** Whether the head names the last entry the same statement saw: nothing was appended between its snapshot and its lock. */
+export function current(head: LockedHead): boolean {
+  if (head.last === null) return head.nextSeq === 0n;
+  return head.nextSeq === head.last.seq + 1n && head.headHash.equals(head.last.hash);
+}
+
+async function readOnce(db: Queryable, asked: Asked): Promise<Snapshot> {
+  const query = (engineOf(db) === 'postgres' ? postgres : sqlite)(asked);
+  const [row] = await rowsOf<{ snapshot: string | Raw }>(db, query);
+  const raw: Raw = typeof row!.snapshot === 'string' ? (JSON.parse(row!.snapshot) as Raw) : row!.snapshot;
+  return {
+    at: Number(raw.at),
+    members: new Map(raw.members.map((member) => [member.principal, memberOf(member)])),
+    grants: new Map(asked.principals.map((principal) => [principal, raw.grants.filter((grant) => grant.principal === principal).map(grantOf)])),
+    newestAccess: new Map(raw.access.map((entry) => [entry.subjectPrincipal!, entryOf(entry)])),
+    newestPolicy: raw.policy === null ? null : entryOf(raw.policy),
+    environments: new Map(raw.environments.map(({ id, ...environment }) => [id, {
+      ...environment,
+      deleted: Boolean(environment.deleted),
+      archived: Boolean(environment.archived),
+    }])),
+    ended: new Set(raw.ended.map((seq) => BigInt(seq))),
+    released: Number(raw.released ?? 0),
+    head: raw.head === null ? null : {
+      nextSeq: BigInt(raw.head.nextSeq),
+      headHash: Buffer.from(raw.head.hash, 'hex'),
+      last: raw.last === null ? null : { seq: BigInt(raw.last.seq), hash: Buffer.from(raw.last.hash, 'hex') },
+      rotation: raw.rotation === null ? null : entryOf(raw.rotation),
+    },
+  };
+}
+
+/** Whole numbers come as JSON numbers or text, bytes as hex, as each dialect's query writes them. */
+type Int = number | string;
+
+/** An entry's columns, as both dialects' queries write them (`entryJson`). */
+export type RawEntry = {
+  seq: Int; author: string; keyId: string; occurredAt: Int; actor: string; action: string; decision: string; code: string | null;
+  subjectPrincipal: string | null; projectId: string | null; environmentId: string | null; secretId: string | null;
+  secretVersionId: string | null; operationId: string | null; requestId: string | null; sourceIp: string | null;
+  relatedSeq: Int | null; metadata: string; prevHash: string; mac: string; hash: string;
+};
+
+type Raw = {
+  at: Int;
+  head: { nextSeq: Int; hash: string } | null;
+  last: { seq: Int; hash: string } | null;
+  rotation: RawEntry | null;
+  members: {
+    principal: string; status: 'active' | 'removed'; owner: boolean | number; role: string | null; scope: string | null; generation: Int;
+    createdAt: Int; createdBy: string; statusChangedAt: Int; statusChangedBy: string; accessSeq: Int; mac: string;
+  }[];
+  grants: { principal: string; projectId: string | null; environmentId: string | null; environmentSlug: string | null; role: string; expiresAt: Int | null; grantedAt: Int; grantedBy: string }[];
+  access: RawEntry[];
+  policy: RawEntry | null;
+  environments: { id: string; projectId: string; slug: string; owner: string | null; parentId: string | null; deleted: boolean | number; archived: boolean | number }[];
+  ended: Int[];
+  released: Int | null;
+};
+
+/** An entry as the chain's codec reads it, from what `entryJson` wrote. */
+export function entryOf(raw: RawEntry): StoredEntry {
+  return {
+    ...raw,
+    seq: BigInt(raw.seq),
+    author: raw.author as StoredEntry['author'],
+    occurredAt: Number(raw.occurredAt),
+    relatedSeq: raw.relatedSeq === null ? null : BigInt(raw.relatedSeq),
+    prevHash: Buffer.from(raw.prevHash, 'hex'),
+    mac: Buffer.from(raw.mac, 'hex'),
+    hash: Buffer.from(raw.hash, 'hex'),
+  };
+}
+
+function grantOf(raw: Raw['grants'][number]): GrantRow {
+  return { ...raw, expiresAt: raw.expiresAt === null ? null : Number(raw.expiresAt), grantedAt: Number(raw.grantedAt) };
+}
+
+function memberOf({ owner, ...raw }: Raw['members'][number]): Member {
+  return store.memberOf({
+    ...raw,
+    owner: owner === true || owner === 1,
+    generation: Number(raw.generation),
+    createdAt: Number(raw.createdAt),
+    statusChangedAt: Number(raw.statusChangedAt),
+    accessSeq: BigInt(raw.accessSeq),
+    mac: Buffer.from(raw.mac, 'hex'),
+  });
+}

package/src/store.ts

@@ -88,10 +88,10 @@ function memberColumns(db: Queryable) {
 }
 
 /** A row as stored: `role` and `scope` as their columns hold them. */
-type StoredMember = Omit<Member, 'role' | 'scope'> & { owner: boolean; role: string | null; scope: string | null };
+export type StoredMember = Omit<Member, 'role' | 'scope'> & { owner: boolean; role: string | null; scope: string | null };
 
 /** A member as their row says (`storedRole`). */
-function memberOf({ owner, role, scope, ...row }: StoredMember): Member {
+export function memberOf({ owner, role, scope, ...row }: StoredMember): Member {
   return { ...row, ...storedRole({ owner, role, scope }) };
 }
 
@@ -308,38 +308,6 @@ export async function everyProjectHolders(db: Queryable): Promise<string[]> {
 
 // --- the log --------------------------------------------------------------------
 
-/** The action of an entry that releases a key, which the bulk limit counts. */
-export const RELEASE = 'secret.read';
-
-/**
- * How many keys the vault has released to `principal` since `after`: one
- * for an entry about one secret, and as many as it lists for one about
- * several (`secrets`), a read logged once per place.
- */
-export async function releasesSince(db: Queryable, principal: string, after: number): Promise<number> {
-  const [{ n }] = await released(db, { principal, after });
-  return Number(n ?? 0);
-}
-
-const released = prepared((db) => {
-  const { auditLog } = tablesOf(db);
-  const listed = engineOf(db) === 'postgres'
-    ? sql`jsonb_array_length((${auditLog.metadata})::jsonb -> 'secrets')`
-    : sql`json_array_length(${auditLog.metadata}, '$.secrets')`;
-  return db
-    .select({ n: sql<string | number | null>`SUM(COALESCE(${listed}, 1))` })
-    .from(auditLog)
-    .where(
-      and(
-        eq(auditLog.author, 'vault'),
-        eq(auditLog.actor, sql.placeholder('principal')),
-        eq(auditLog.action, RELEASE),
-        eq(auditLog.decision, 'allow'),
-        gt(auditLog.occurredAt, sql.placeholder('after')),
-      ),
-    );
-});
-
 /** Rows of the log as the chain's codec reads them: `author` and `decision` are checked by the table. */
 function stored(rows: object[]): StoredEntry[] {
   return rows as StoredEntry[];