@coffre/vault 0.4.6 → 0.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coffre/vault",
-  "version": "0.4.6",
+  "version": "0.5.1",
   "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.4.6",
-    "@coffre/db": "0.4.6"
+    "@coffre/db": "0.5.1",
+    "@coffre/core": "0.5.1"
   },
   "devDependencies": {
     "@types/node": "26.1.1",

package/src/cloudflare.ts

@@ -22,6 +22,7 @@ import type {
   EndReferencesInput,
   RewrapInput,
   SetAccessInput,
+  SetSettingsInput,
   UnwrapInput,
   Vault,
   VerifyLogInput,
@@ -91,6 +92,8 @@ export class VaultEntrypoint extends WorkerEntrypoint implements Vault {
   async setAccess(input: SetAccessInput) { return this.#call((vault) => vault.setAccess(input)); }
   async admit(input: AdmitInput) { return this.#call((vault) => vault.admit(input)); }
   async remove(input: RemoveInput) { return this.#call((vault) => vault.remove(input)); }
+  async settings() { return this.#call((vault) => vault.settings()); }
+  async setSettings(input: SetSettingsInput) { return this.#call((vault) => vault.setSettings(input)); }
   async checkpoint() { return this.#call((vault) => vault.checkpoint()); }
   async about() { return this.#call((vault) => vault.about()); }
   async keyChecks() { return this.#call((vault) => vault.keyChecks()); }

package/src/local.ts

@@ -15,6 +15,8 @@ export const METHODS = [
   'setAccess',
   'admit',
   'remove',
+  'settings',
+  'setSettings',
   'checkpoint',
   'about',
   'keyChecks',

package/src/replay.ts

@@ -1,4 +1,4 @@
-import { everyProjectPath } from '@coffre/core/access';
+import { EVERYWHERE, isInstanceRole, isScope, normalScope, type InstanceRole, type Scope } from '@coffre/core/access';
 import type { StoredEntry } from '@coffre/core/audit';
 import type { AccessFault, FaultGrant } from '@coffre/core/vault';
 
@@ -28,7 +28,8 @@ export function replayFault(state: Replayed, rows: readonly Member[], storedGran
     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);
+    const same = (field: keyof LoggedMember) => (field === 'scope' ? JSON.stringify(inStore.scope) === JSON.stringify(inLog.scope) : inStore[field] === inLog[field]);
+    const fields = MEMBER_FIELDS.filter(([field]) => !same(field)).map(([, column]) => column);
     if (fields.length > 0) return { kind: 'member-differs', principal, fields };
   }
 
@@ -63,7 +64,7 @@ export function apply(state: Replayed, row: StoredEntry): AccessFault | null {
       state.members.set(principal, {
         principal,
         status: 'active',
-        owner: detail.owner === true,
+        ...standingIn(detail),
         generation: before?.generation ?? 0,
         createdAt: before?.createdAt ?? row.occurredAt,
         createdBy: before?.createdBy ?? row.actor,
@@ -72,15 +73,16 @@ export function apply(state: Replayed, row: StoredEntry): AccessFault | null {
       });
       return null;
     case 'member.owner':
+    case 'member.role':
       if (before === undefined) return { kind: 'unadmitted-change', seq: Number(row.seq), principal };
-      state.members.set(principal, { ...before, owner: detail.owner === true, accessSeq: row.seq });
+      state.members.set(principal, { ...before, ...standingIn(detail), 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 });
+      state.members.set(principal, { ...before, status: 'removed', role: 'member', scope: EVERYWHERE, generation, accessSeq: row.seq, ...changed });
       grantsOf.clear();
       return null;
     }
@@ -103,10 +105,21 @@ export function apply(state: Replayed, row: StoredEntry): AccessFault | null {
   return null;
 }
 
+/**
+ * The instance role an entry gives: its `role` and `scope`, or, in one
+ * 0.4 wrote, whether it made them an owner, an Admin everywhere.
+ */
+function standingIn(detail: Record<string, unknown>): { role: InstanceRole; scope: Scope } {
+  if (typeof detail.role !== 'string') return { role: detail.owner === true ? 'admin' : 'member', scope: EVERYWHERE };
+  const role = isInstanceRole(detail.role) ? detail.role : 'member';
+  return { role, scope: role !== 'member' && isScope(detail.scope) ? normalScope(detail.scope) : EVERYWHERE };
+}
+
 /** A member's fields, and the columns a fault names them by. */
 const MEMBER_FIELDS = [
   ['status', 'status'],
-  ['owner', 'owner'],
+  ['role', 'role'],
+  ['scope', 'scope'],
   ['generation', 'generation'],
   ['createdAt', 'created_at'],
   ['createdBy', 'created_by'],
@@ -129,7 +142,7 @@ function placeOf(row: StoredEntry, detail: Record<string, unknown>): Place {
 
 /** 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 ?? everyProjectPath(place.environmentSlug);
+  return place.environmentId ?? place.projectId ?? (place.environmentSlug === null ? '*' : `*/${place.environmentSlug}`);
 }
 
 function grantKey(grant: GrantRow): string {

package/src/rows.ts

@@ -1,5 +1,7 @@
 import { createHmac, hkdfSync, timingSafeEqual } from 'node:crypto';
 
+import { normalScope, unscoped } from '@coffre/core/access';
+
 import type { GrantRow, Member } from './store.ts';
 
 /**
@@ -24,8 +26,8 @@ export function rowKey(signingKey: Uint8Array): Buffer {
 /**
  * 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
+ * environment, its project, or neither, which is a grant on every project
+ * of 0.4, with the slug it covers, or null, until the vault replaces it. 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[] {
@@ -48,13 +50,25 @@ export function sameGrants(a: readonly GrantRow[], b: readonly GrantRow[]): bool
   return x.length === y.length && x.every((tuple, i) => tuple === y[i]);
 }
 
+/**
+ * A member's instance role and its scope, as the MAC covers them: as 0.4
+ * did, whether they are an owner, for a Member or an Admin everywhere, so
+ * that every row 0.4 sealed holds as it is; otherwise the role and the
+ * scope, which no row of 0.4 can match.
+ */
+export function standing(member: Pick<Member, 'role' | 'scope'>): boolean | [string, unknown] {
+  const scope = normalScope(member.scope);
+  if (unscoped(scope) && (member.role === 'member' || member.role === 'admin')) return member.role === 'admin';
+  return [member.role, scope];
+}
+
 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,
+    standing(member),
     member.generation,
     member.accessSeq.toString(),
     member.createdAt,

package/src/store.ts

@@ -1,9 +1,10 @@
-import type { GrantPlace } from '@coffre/core/access';
+import { EVERYWHERE, type InstanceRole, type Scope } 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, tombstone, truth } from '@coffre/db/dialect';
-import { readGrants, type GrantRow } from '@coffre/db/grants';
+import { readGrants, roleColumns, storedRole, type GrantRow } from '@coffre/db/grants';
+import { entryColumns } from '@coffre/db/log';
 import { and, asc, count, desc, eq, gt, gte, inArray, isNull, lt, lte, or, sql, type SQL, type SQLWrapper } from 'drizzle-orm';
 
 /**
@@ -20,7 +21,9 @@ import { and, asc, count, desc, eq, gt, gte, inArray, isNull, lt, lte, or, sql,
 export type Member = {
   principal: string;
   status: 'active' | 'removed';
-  owner: boolean;
+  /** A person's instance role and its scope; `member` everywhere for anyone else (`memberOf`). */
+  role: InstanceRole;
+  scope: Scope;
   generation: number;
   createdAt: number;
   createdBy: string;
@@ -36,15 +39,16 @@ export type Member = {
 export { ACCESS_ACTIONS };
 
 /**
- * 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.
+ * Where a grant applies: a project, or one of its environments (with its
+ * project, which its row finds through `environments`); or, for a grant on
+ * every project of 0.4, until the vault replaces it, neither, with the one
+ * environment slug it covers in each, if any.
  */
-export type Place = GrantPlace;
+export type Place = Pick<GrantRow, 'projectId' | 'environmentId' | 'environmentSlug'>;
 
 /** A grant as stored, which `@coffre/db/grants` reads and writes. */
 export type { GrantRow };
-export { insertGrant } from '@coffre/db/grants';
+export { accessEntriesAbout, insertGrant } from '@coffre/db/grants';
 
 /**
  * On Postgres, fail a lock wait in this transaction after `ms`, rather than
@@ -69,6 +73,8 @@ function memberColumns(db: Queryable) {
     principal: vaultMembers.principal,
     status: vaultMembers.status,
     owner: vaultMembers.owner,
+    role: vaultMembers.role,
+    scope: vaultMembers.scope,
     generation: vaultMembers.generation,
     createdAt: vaultMembers.createdAt,
     createdBy: vaultMembers.createdBy,
@@ -79,15 +85,29 @@ 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 };
+
+/** A member as their row says (`storedRole`). */
+function memberOf({ owner, role, scope, ...row }: StoredMember): Member {
+  return { ...row, ...storedRole({ owner, role, scope }) };
+}
+
+function storedChange(change: Partial<Omit<Member, 'principal'>>): Record<string, unknown> {
+  const { role, scope, ...rest } = change;
+  if (role === undefined) return rest;
+  return { ...rest, ...roleColumns(role, scope ?? EVERYWHERE) };
+}
+
 export async function member(db: Queryable, principal: string): Promise<Member | undefined> {
   const { vaultMembers } = tablesOf(db);
   const [row] = await db.select(memberColumns(db)).from(vaultMembers).where(eq(vaultMembers.principal, principal));
-  return row as Member | undefined;
+  return row === undefined ? undefined : memberOf(row as StoredMember);
 }
 
 export async function allMembers(db: Queryable): Promise<Member[]> {
   const { vaultMembers } = tablesOf(db);
-  return (await db.select(memberColumns(db)).from(vaultMembers).orderBy(asc(vaultMembers.principal))) as Member[];
+  return ((await db.select(memberColumns(db)).from(vaultMembers).orderBy(asc(vaultMembers.principal))) as StoredMember[]).map(memberOf);
 }
 
 /**
@@ -107,7 +127,7 @@ export async function lockMembers(tx: Transaction, principals: readonly string[]
       .orderBy(asc(vaultMembers.principal)),
     'no key update',
   );
-  return new Map((rows as Member[]).map((row) => [row.principal, row]));
+  return new Map((rows as StoredMember[]).map((row) => [row.principal, memberOf(row)]));
 }
 
 /**
@@ -116,7 +136,7 @@ export async function lockMembers(tx: Transaction, principals: readonly string[]
  */
 export async function insertMember(tx: Transaction, row: Member): Promise<void> {
   const { vaultMembers } = tablesOf(tx);
-  await tx.insert(vaultMembers).values(row);
+  await tx.insert(vaultMembers).values(storedChange(row) as typeof vaultMembers.$inferInsert);
 }
 
 export async function updateMember(
@@ -125,7 +145,7 @@ export async function updateMember(
   change: Partial<Omit<Member, 'principal'>>,
 ): Promise<void> {
   const { vaultMembers } = tablesOf(tx);
-  await tx.update(vaultMembers).set(change).where(eq(vaultMembers.principal, principal));
+  await tx.update(vaultMembers).set(storedChange(change)).where(eq(vaultMembers.principal, principal));
 }
 
 // --- grants ---------------------------------------------------------------------
@@ -211,12 +231,12 @@ export async function wrappedUnder(db: Queryable, provider: string, keyId: strin
   return rows.map((row) => ({ ...row, bytes: Buffer.from(row.bytes) }));
 }
 
-/** Of these projects and environments, the ones that exist, each environment with its project. */
+/** Of these projects and environments, the ones that exist, each environment with its project and slug. */
 export async function places(
   db: Queryable,
   projectIds: readonly string[],
   environmentIds: readonly string[],
-): Promise<{ projects: Set<string>; environments: Map<string, string>; deleted: Set<string> }> {
+): Promise<{ projects: Set<string>; environments: Map<string, { projectId: string; slug: string }>; deleted: Set<string> }> {
   const { projects, environments } = tablesOf(db);
   const [foundProjects, foundEnvironments] = await Promise.all([
     projectIds.length === 0
@@ -225,19 +245,43 @@ export async function places(
     environmentIds.length === 0
       ? []
       : db
-          .select({ id: environments.id, projectId: environments.projectId, deleted: truth(or(tombstone(environments.slug), tombstone(projects.slug))!) })
+          .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, [...environmentIds])),
   ]);
   return {
     projects: new Set(foundProjects.map((row) => row.id)),
-    environments: new Map(foundEnvironments.map((row) => [row.id, row.projectId])),
+    environments: new Map(foundEnvironments.map((row) => [row.id, { projectId: row.projectId, slug: row.slug }])),
     // 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)),
   };
 }
 
+/** Every project not deleted, with its environments not deleted: what a grant on every project of 0.4 reached. */
+export async function liveProjects(db: Queryable): Promise<{ id: string; environments: { id: string; slug: string }[] }[]> {
+  const { projects, environments } = tablesOf(db);
+  const [found, inside] = await Promise.all([
+    db.select({ id: projects.id, deleted: truth(tombstone(projects.slug)) }).from(projects).orderBy(asc(projects.id)),
+    db.select({ id: environments.id, projectId: environments.projectId, slug: environments.slug, deleted: truth(tombstone(environments.slug)) }).from(environments).orderBy(asc(environments.id)),
+  ]);
+  return found.filter((project) => !project.deleted).map((project) => ({
+    id: project.id,
+    environments: inside.filter((environment) => environment.projectId === project.id && !environment.deleted).map(({ id, slug }) => ({ id, slug })),
+  }));
+}
+
+/** Who holds a grant on every project of 0.4, lapsed or not, which the vault replaces (`#convert`). */
+export async function everyProjectHolders(db: Queryable): Promise<string[]> {
+  const { vaultGrants } = tablesOf(db);
+  const rows = await db
+    .selectDistinct({ principal: vaultGrants.principal })
+    .from(vaultGrants)
+    .where(and(isNull(vaultGrants.projectId), isNull(vaultGrants.environmentId)))
+    .orderBy(asc(vaultGrants.principal));
+  return rows.map((row) => row.principal);
+}
+
 // --- the log --------------------------------------------------------------------
 
 /** The action of an entry that releases a key, which the bulk limit counts. */
@@ -261,33 +305,6 @@ export async function releasesSince(db: Queryable, principal: string, after: num
   return Number(n);
 }
 
-function entryColumns(db: Queryable) {
-  const { auditLog } = tablesOf(db);
-  return {
-    seq: auditLog.seq,
-    author: auditLog.author,
-    keyId: auditLog.keyId,
-    occurredAt: auditLog.occurredAt,
-    actor: auditLog.actor,
-    action: auditLog.action,
-    decision: auditLog.decision,
-    code: auditLog.code,
-    subjectPrincipal: auditLog.subjectPrincipal,
-    projectId: auditLog.projectId,
-    environmentId: auditLog.environmentId,
-    secretId: auditLog.secretId,
-    secretVersionId: auditLog.secretVersionId,
-    operationId: auditLog.operationId,
-    requestId: auditLog.requestId,
-    sourceIp: auditLog.sourceIp,
-    relatedSeq: auditLog.relatedSeq,
-    metadata: auditLog.metadata,
-    prevHash: auditLog.prevHash,
-    mac: auditLog.mac,
-    hash: auditLog.hash,
-  };
-}
-
 /** 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[];
@@ -447,8 +464,8 @@ export async function latestVaultEntry(db: Queryable, actions: readonly string[]
   return row === undefined ? undefined : stored([row])[0];
 }
 
-/** Up to `limit` of the vault's allowed access entries about `principal`, newest first. */
-export async function accessEntriesAbout(db: Queryable, principal: string, limit: number): Promise<StoredEntry[]> {
+/** Up to `limit` of the vault's allowed entries of `action` before `before` (the newest when undefined), newest first. */
+export async function newestVaultEntries(db: Queryable, action: string, limit: number, before?: bigint): Promise<StoredEntry[]> {
   const { auditLog } = tablesOf(db);
   const rows = await db
     .select(entryColumns(db))
@@ -456,9 +473,9 @@ export async function accessEntriesAbout(db: Queryable, principal: string, limit
     .where(
       and(
         eq(auditLog.author, 'vault'),
-        eq(auditLog.subjectPrincipal, principal),
-        inArray(auditLog.action, [...ACCESS_ACTIONS]),
+        eq(auditLog.action, action),
         eq(auditLog.decision, 'allow'),
+        before === undefined ? undefined : lt(auditLog.seq, before),
       ),
     )
     .orderBy(desc(auditLog.seq))