@coffre/vault 0.2.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coffre/vault",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "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.2.0",
-    "@coffre/db": "0.2.0"
+    "@coffre/core": "0.4.0",
+    "@coffre/db": "0.4.0"
   },
   "devDependencies": {
     "@types/node": "26.1.1",
@@ -45,7 +45,7 @@
     "pg": "8.16.3",
     "tsdown": "0.23.0",
     "typescript": "5.9.3",
-    "wrangler": "4.118.0"
+    "wrangler": "4.142.0"
   },
   "scripts": {
     "build": "tsdown",

package/src/cloudflare.ts

@@ -18,6 +18,8 @@
 import type {
   AdmitInput,
   RemoveInput,
+  ReferenceInput,
+  EndReferencesInput,
   RewrapInput,
   SetAccessInput,
   UnwrapInput,
@@ -83,6 +85,8 @@ export class VaultEntrypoint extends WorkerEntrypoint implements Vault {
   async unwrap(input: UnwrapInput) { return this.#call((vault) => vault.unwrap(input)); }
   async wrap(input: WrapInput) { return this.#call((vault) => vault.wrap(input)); }
   async rewrap(input: RewrapInput) { return this.#call((vault) => vault.rewrap(input)); }
+  async reference(input: ReferenceInput) { return this.#call((vault) => vault.reference(input)); }
+  async endReferences(input: EndReferencesInput) { return this.#call((vault) => vault.endReferences(input)); }
   async access(principal: string) { return this.#call((vault) => vault.access(principal)); }
   async setAccess(input: SetAccessInput) { return this.#call((vault) => vault.setAccess(input)); }
   async admit(input: AdmitInput) { return this.#call((vault) => vault.admit(input)); }

package/src/local.ts

@@ -9,6 +9,8 @@ export const METHODS = [
   'unwrap',
   'wrap',
   'rewrap',
+  'reference',
+  'endReferences',
   'access',
   'setAccess',
   'admit',

package/src/replay.ts

@@ -1,3 +1,4 @@
+import { everyProjectPath } from '@coffre/core/access';
 import type { StoredEntry } from '@coffre/core/audit';
 import type { AccessFault, FaultGrant } from '@coffre/core/vault';
 
@@ -51,7 +52,7 @@ export type Replayed = { members: Map<string, LoggedMember>; held: Map<string, M
 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 place = placeOf(row, detail);
   const grantsOf = state.held.get(principal) ?? new Map<string, GrantRow>();
   state.held.set(principal, grantsOf);
   const before = state.members.get(principal);
@@ -114,9 +115,21 @@ const MEMBER_FIELDS = [
   ['accessSeq', 'access_seq'],
 ] as const satisfies readonly (readonly [keyof LoggedMember, string])[];
 
-/** A grant's place: its environment, or its project when it has none. */
+/**
+ * The place an access entry is about: its project and environment, or, with
+ * neither, every project, which it names as a path (`*`, or `*` and a slug).
+ */
+function placeOf(row: StoredEntry, detail: Record<string, unknown>): Place {
+  if (row.projectId !== null || row.environmentId !== null) {
+    return { projectId: row.projectId, environmentId: row.environmentId, environmentSlug: null };
+  }
+  const slug = typeof detail.place === 'string' ? detail.place.split('/')[1] : undefined;
+  return { projectId: null, environmentId: null, environmentSlug: slug ?? null };
+}
+
+/** A grant's place: its environment, or its project when it has none, or every project's path. */
 function placeKey(place: Place): string {
-  return place.environmentId ?? place.projectId;
+  return place.environmentId ?? place.projectId ?? everyProjectPath(place.environmentSlug);
 }
 
 function grantKey(grant: GrantRow): string {
@@ -124,6 +137,7 @@ function grantKey(grant: GrantRow): string {
     grant.principal,
     grant.projectId,
     grant.environmentId,
+    grant.environmentSlug,
     grant.role,
     grant.expiresAt,
     grant.grantedAt,
@@ -132,6 +146,6 @@ function grantKey(grant: GrantRow): string {
 }
 
 function faultGrant(key: string): FaultGrant {
-  const [principal, projectId, environmentId, role] = JSON.parse(key) as [string, string, string | null, string];
-  return { principal, projectId, environmentId, role };
+  const [principal, projectId, environmentId, environmentSlug, role] = JSON.parse(key) as [string, string | null, string | null, string | null, string];
+  return { principal, projectId, environmentId, environmentSlug, role };
 }

package/src/rows.ts

@@ -21,12 +21,18 @@ 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. */
+/**
+ * A member's grants as the MAC covers them: each one's place, role, end and
+ * grant, as a sorted set. A grant is kept by what its row names first: its
+ * environment, its project, or neither, which is a grant on every project,
+ * with the slug it covers, or null. A member who holds none of those has the
+ * set, and so the MAC, they had before there were any.
+ */
 export function grantSet(grants: readonly GrantRow[]): string[] {
   return grants
     .map((grant) => [
-      grant.environmentId === null ? 'project' : 'environment',
-      grant.environmentId ?? grant.projectId,
+      grant.environmentId !== null ? 'environment' : grant.projectId !== null ? 'project' : 'every-project',
+      grant.environmentId ?? grant.projectId ?? grant.environmentSlug,
       grant.role,
       grant.expiresAt,
       grant.grantedAt,

package/src/store.ts

@@ -1,8 +1,10 @@
+import type { GrantPlace } from '@coffre/core/access';
 import type { Author, StoredEntry } from '@coffre/core/audit';
 import { ACCESS_ACTIONS, type SecretRef, type WrappedKey } from '@coffre/core/vault';
 import { tablesOf, type Queryable, type Transaction } from '@coffre/db';
-import { clockMillis, engineOf, forUpdate } from '@coffre/db/dialect';
-import { and, asc, count, desc, eq, gt, gte, inArray, isNull, lt, lte, sql } from 'drizzle-orm';
+import { clockMillis, engineOf, forUpdate, tombstone, truth } from '@coffre/db/dialect';
+import { readGrants, type GrantRow } from '@coffre/db/grants';
+import { and, asc, count, desc, eq, gt, gte, inArray, isNull, lt, lte, or, sql, type SQL, type SQLWrapper } from 'drizzle-orm';
 
 /**
  * Every query the vault makes, and the only code in it that holds them.
@@ -33,16 +35,16 @@ export type Member = {
 /** Every entry that changes who is a member or what they hold. */
 export { ACCESS_ACTIONS };
 
-/** Where a grant applies: a project (`environmentId` null), or one of its environments. */
-export type Place = { projectId: string; environmentId: string | null };
+/**
+ * Where a grant applies: a project, one of its environments (with its
+ * project, which its row finds through `environments`), every project, or
+ * one environment slug in every project.
+ */
+export type Place = GrantPlace;
 
-export type GrantRow = Place & {
-  principal: string;
-  role: string;
-  expiresAt: number | null;
-  grantedAt: number;
-  grantedBy: string;
-};
+/** A grant as stored, which `@coffre/db/grants` reads and writes. */
+export type { GrantRow };
+export { insertGrant } from '@coffre/db/grants';
 
 /**
  * On Postgres, fail a lock wait in this transaction after `ms`, rather than
@@ -129,37 +131,48 @@ export async function updateMember(
 // --- grants ---------------------------------------------------------------------
 
 /** Grants, lapsed ones too, each with its project, which an environment's grant finds through `environments`. */
-export async function grants(db: Queryable, principal?: string): Promise<GrantRow[]> {
-  const { vaultGrants, environments } = tablesOf(db);
-  return db
-    .select({
-      principal: vaultGrants.principal,
-      projectId: sql<string>`coalesce(${vaultGrants.projectId}, ${environments.projectId})`,
-      environmentId: vaultGrants.environmentId,
-      role: vaultGrants.role,
-      expiresAt: vaultGrants.expiresAt,
-      grantedAt: vaultGrants.grantedAt,
-      grantedBy: vaultGrants.grantedBy,
-    })
-    .from(vaultGrants)
-    .leftJoin(environments, eq(environments.id, vaultGrants.environmentId))
-    .where(principal === undefined ? undefined : eq(vaultGrants.principal, principal));
+export function grants(db: Queryable, principal?: string): Promise<GrantRow[]> {
+  return readGrants(db, principal === undefined ? {} : { principal });
 }
 
-/** A grant names its environment, or its project when it has none: exactly one. */
+/**
+ * A grant's row names its environment, or its project when it has none, or
+ * neither on every project, with the slug it covers there, if any.
+ */
 function at(db: Queryable, place: Place) {
   const { vaultGrants } = tablesOf(db);
-  return place.environmentId === null
-    ? and(eq(vaultGrants.projectId, place.projectId), isNull(vaultGrants.environmentId))
-    : eq(vaultGrants.environmentId, place.environmentId);
+  if (place.environmentId !== null) return eq(vaultGrants.environmentId, place.environmentId);
+  if (place.projectId !== null) return and(eq(vaultGrants.projectId, place.projectId), isNull(vaultGrants.environmentId));
+  return and(
+    isNull(vaultGrants.projectId),
+    isNull(vaultGrants.environmentId),
+    place.environmentSlug === null ? isNull(vaultGrants.environmentSlug) : eq(vaultGrants.environmentSlug, place.environmentSlug),
+  );
 }
 
-export async function insertGrant(tx: Transaction, grant: GrantRow): Promise<void> {
-  const { vaultGrants } = tablesOf(tx);
-  await tx.insert(vaultGrants).values({
-    ...grant,
-    projectId: grant.environmentId === null ? grant.projectId : null,
-  });
+/**
+ * Each of these environments that exists, by id, with its project, its
+ * slug, what grants on one slug in every project match, and whether it was
+ * deleted, alone or with its project: then no key under it opens, or is
+ * wrapped, whatever grant would cover it.
+ */
+export async function environmentsById(
+  db: Queryable,
+  ids: readonly string[],
+): Promise<Map<string, { projectId: string; slug: string; deleted: boolean }>> {
+  if (ids.length === 0) return new Map();
+  const { environments, projects } = tablesOf(db);
+  const rows = await db
+    .select({
+      id: environments.id,
+      projectId: environments.projectId,
+      slug: environments.slug,
+      deleted: truth(or(tombstone(environments.slug), tombstone(projects.slug))!),
+    })
+    .from(environments)
+    .innerJoin(projects, eq(projects.id, environments.projectId))
+    .where(inArray(environments.id, [...new Set(ids)]));
+  return new Map(rows.map(({ id, ...environment }) => [id, environment]));
 }
 
 export async function deleteGrant(tx: Transaction, principal: string, place: Place): Promise<void> {
@@ -192,7 +205,7 @@ export async function wrappedUnder(db: Queryable, provider: string, keyId: strin
     })
     .from(secretVersions)
     .innerJoin(secrets, eq(secrets.id, secretVersions.secretId))
-    .where(and(eq(secretVersions.kekProvider, provider), eq(secretVersions.kekId, keyId)))
+    .where(and(eq(secretVersions.kekProvider, provider), eq(secretVersions.kekId, keyId), sealed(secretVersions.wrappedDek)))
     .orderBy(desc(secretVersions.createdAt))
     .limit(limit);
   return rows.map((row) => ({ ...row, bytes: Buffer.from(row.bytes) }));
@@ -203,20 +216,25 @@ export async function places(
   db: Queryable,
   projectIds: readonly string[],
   environmentIds: readonly string[],
-): Promise<{ projects: Set<string>; environments: Map<string, string> }> {
+): Promise<{ projects: Set<string>; environments: Map<string, string>; deleted: Set<string> }> {
   const { projects, environments } = tablesOf(db);
   const [foundProjects, foundEnvironments] = await Promise.all([
-    projectIds.length === 0 ? [] : db.select({ id: projects.id }).from(projects).where(inArray(projects.id, [...projectIds])),
+    projectIds.length === 0
+      ? []
+      : db.select({ id: projects.id, deleted: truth(tombstone(projects.slug)) }).from(projects).where(inArray(projects.id, [...projectIds])),
     environmentIds.length === 0
       ? []
       : db
-          .select({ id: environments.id, projectId: environments.projectId })
+          .select({ id: environments.id, projectId: environments.projectId, deleted: truth(or(tombstone(environments.slug), tombstone(projects.slug))!) })
           .from(environments)
+          .innerJoin(projects, eq(projects.id, environments.projectId))
           .where(inArray(environments.id, [...environmentIds])),
   ]);
   return {
     projects: new Set(foundProjects.map((row) => row.id)),
     environments: new Map(foundEnvironments.map((row) => [row.id, row.projectId])),
+    // The projects and environments among them that were deleted, alone or with their project.
+    deleted: new Set([...foundProjects, ...foundEnvironments].filter((row) => row.deleted).map((row) => row.id)),
   };
 }
 
@@ -362,6 +380,61 @@ export async function firstVaultEntryUnder(db: Queryable, keyId: string): Promis
   return row?.seq;
 }
 
+/** The entries at these seqs, any author, by seq: what a reference names as its seal. */
+export async function entriesAt(db: Queryable, seqs: readonly bigint[]): Promise<Map<bigint, StoredEntry>> {
+  if (seqs.length === 0) return new Map();
+  const { auditLog } = tablesOf(db);
+  const rows = stored(await db.select(entryColumns(db)).from(auditLog).where(inArray(auditLog.seq, [...new Set(seqs)])));
+  return new Map(rows.map((row) => [row.seq, row]));
+}
+
+/**
+ * Which of these `reference.create` entries a `reference.end` of the
+ * vault's names, allowed: one read through `audit_log_reference_end_idx`.
+ * An end that fails its MAC still ends: putting a reference back takes
+ * more than a forged end can undo, and refusing is the safe side.
+ */
+export async function endedReferences(db: Queryable, seqs: readonly bigint[]): Promise<Set<bigint>> {
+  if (seqs.length === 0) return new Set();
+  const { auditLog } = tablesOf(db);
+  const rows = await db
+    .select({ relatedSeq: auditLog.relatedSeq })
+    .from(auditLog)
+    .where(and(eq(auditLog.author, 'vault'), eq(auditLog.action, 'reference.end'), eq(auditLog.decision, 'allow'), inArray(auditLog.relatedSeq, [...new Set(seqs)])));
+  return new Set(rows.map((row) => row.relatedSeq!));
+}
+
+/** The project each environment is in: a holder's ids, checked against each other. */
+export async function projectsOfEnvironments(db: Queryable, ids: readonly string[]): Promise<Map<string, string>> {
+  if (ids.length === 0) return new Map();
+  const { environments } = tablesOf(db);
+  const rows = await db.select({ id: environments.id, projectId: environments.projectId }).from(environments).where(inArray(environments.id, [...new Set(ids)]));
+  return new Map(rows.map((row) => [row.id, row.projectId]));
+}
+
+/** A secret as the vault reads it to make a reference to it: where it is, its path, and its current version. */
+export type SecretPlace = { secretId: string; projectId: string; environmentId: string; path: string; currentVersionId: string | null };
+
+export async function secretsByIds(db: Queryable, ids: readonly string[]): Promise<Map<string, SecretPlace>> {
+  if (ids.length === 0) return new Map();
+  const { secrets, environments, projects } = tablesOf(db);
+  const rows = await db
+    .select({
+      secretId: secrets.id,
+      projectId: secrets.projectId,
+      environmentId: secrets.environmentId,
+      project: projects.slug,
+      environment: environments.slug,
+      key: secrets.key,
+      currentVersionId: secrets.currentVersionId,
+    })
+    .from(secrets)
+    .innerJoin(environments, eq(environments.id, secrets.environmentId))
+    .innerJoin(projects, eq(projects.id, secrets.projectId))
+    .where(inArray(secrets.id, [...new Set(ids)]));
+  return new Map(rows.map(({ project, environment, key, ...row }) => [row.secretId, { ...row, path: `${project}/${environment}/${key}` }]));
+}
+
 /** The vault's newest entry of any of these actions, allowed, or undefined. */
 export async function latestVaultEntry(db: Queryable, actions: readonly string[]): Promise<StoredEntry | undefined> {
   const { auditLog } = tablesOf(db);
@@ -431,8 +504,22 @@ export async function vaultEntriesOf(
   return stored(rows);
 }
 
-/** A stored version and the binding and key the vault reads for itself. */
-export type SecretVersion = { id: string; secret: SecretRef; wrapped: WrappedKey };
+/**
+ * A version that still holds its wrapped key. A deleted place's versions are
+ * erased, their keys emptied: there is nothing left to open, or to try a
+ * vault key on.
+ */
+function sealed(wrappedDek: SQLWrapper): SQL {
+  return sql`length(${wrappedDek}) > 0`;
+}
+
+/**
+ * A stored version and the binding and key the vault reads for itself;
+ * whether its place was deleted, and whether it is its secret's current
+ * one, as a read through a reference needs. An erased version outside a
+ * deleted place is no version.
+ */
+export type SecretVersion = { id: string; secret: SecretRef; wrapped: WrappedKey; deleted: boolean; current: boolean };
 
 export async function versions(db: Queryable, ids: readonly string[]): Promise<SecretVersion[]> {
   if (ids.length === 0) return [];
@@ -451,14 +538,19 @@ export async function versions(db: Queryable, ids: readonly string[]): Promise<S
       kekId: secretVersions.kekId,
       kekVersion: secretVersions.kekVersion,
       wrappedDek: secretVersions.wrappedDek,
+      deleted: truth(or(tombstone(environments.slug), tombstone(projects.slug))!),
+      currentVersionId: secrets.currentVersionId,
+      // The newest by the versions' own order: the app may write `current_version_id`, never a version.
+      newest: sql<number | string>`(SELECT max(newest.version) FROM secret_versions newest WHERE newest.secret_id = ${secretVersions.secretId})`,
     })
     .from(secretVersions)
     .innerJoin(secrets, eq(secrets.id, secretVersions.secretId))
     .innerJoin(environments, eq(environments.id, secrets.environmentId))
     .innerJoin(projects, eq(projects.id, secrets.projectId))
-    .where(inArray(secretVersions.id, [...new Set(ids)]));
+    .where(and(inArray(secretVersions.id, [...new Set(ids)]), or(sealed(secretVersions.wrappedDek), tombstone(environments.slug), tombstone(projects.slug))));
   return rows.map((row) => ({
     id: row.id,
+    deleted: row.deleted,
     secret: {
       projectId: row.projectId,
       environmentId: row.environmentId,
@@ -472,5 +564,6 @@ export async function versions(db: Queryable, ids: readonly string[]): Promise<S
       kekVersion: row.kekVersion,
       bytes: row.wrappedDek.toString('base64'),
     },
+    current: row.currentVersionId === row.id && Number(row.newest) === row.version,
   }));
 }