@coffre/vault 0.5.0 → 0.6.0

package/package.json

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

package/src/cloudflare.ts

@@ -9,7 +9,7 @@
  *   export default vault((env: Env) => ({
  *     database: postgres(env.HYPERDRIVE),
  *     kek: { id: env.VAULT_KEY_ID, key: env.VAULT_KEY }, // or awsKms({ keyArn, credentials }), with a signingKey
- *     rootAdmins: ['admin@acme.example'],
+ *     owners: ['admin@acme.example'],
  *   }));
  *
  * Any number of isolates run it side by side: every decision locks what it

package/src/config.ts

@@ -15,8 +15,12 @@ export const DEFAULT_BULK_LIMIT: BulkLimit = { count: 1000, windowMs: 15 * 60_00
 /** The vault as it runs: keys decoded, emails checked. */
 export type ResolvedVaultConfig = {
   keks: KekRegistry;
-  /** Emails, lowercased: always active, always owners, never changed through the API. */
-  rootAdmins: readonly string[];
+  /**
+   * Emails, lowercased: the Owners of the whole instance its deployment
+   * names, made one at each start and at sign-in (`#declare` in vault.ts),
+   * and never demoted or removed while named.
+   */
+  owners: readonly string[];
   /**
    * The seeds of the vault's own keys, which MAC its log entries, seal member
    * rows and sign checkpoints: the first signs; every one verifies what it
@@ -33,13 +37,13 @@ export type ResolvedVaultConfig = {
 export type Kek = { id: string; key: string } | KekProvider;
 
 /**
- * What a deployment writes: every key coffre has, and who may always get
- * in. The app holds none of it.
+ * What a deployment writes: every key coffre has, and who owns the
+ * instance whatever its database says. The app holds none of it.
  *
  *   {
  *     kek: awsKms({ keyArn: env.KMS_KEY_ARN, credentials: { … } }),
  *     previousKeks: [{ id: 'vault-2025-01-10-k7q2xm', key: env.OLD_VAULT_KEY }],
- *     rootAdmins: ['admin@acme.example'],
+ *     owners: ['admin@acme.example'],
  *     signingKey: env.SIGNING_KEY, // required with a key service; derived from a local KEK otherwise
  *   }
  */
@@ -51,8 +55,6 @@ export type VaultConfig = {
    * on, and verifying what the vault wrote under them before the rotation.
    */
   previousKeks?: readonly Kek[];
-  /** At least one email: the only way into a fresh instance, and the only members nobody can remove. */
-  rootAdmins: readonly string[];
   /**
    * 32 random bytes, base64: the seed of the vault's own keys, which MAC its
    * log entries, seal member rows and sign checkpoints. Leave it out with a
@@ -62,7 +64,31 @@ export type VaultConfig = {
   signingKey?: string;
   /** At most `count` data keys unwrapped per principal in any `windowMinutes`; 1000 in 15 unless set. */
   bulkLimit?: { count: number; windowMinutes: number };
-};
+} & Owners;
+
+/**
+ * At least one email, each an Owner of the whole instance: made one when
+ * the vault starts, and when they sign in, whatever their row says, and
+ * refused to anyone who would demote or remove them, themselves included.
+ * The way into a fresh instance, and back into one whose Owners are all
+ * locked out: add an email, deploy, sign in. Taking an email off makes
+ * them an Owner like any other, whom an Owner may demote. `rootAdmins`, as
+ * 0.5 named it, and `bootstrapOwners` are read until 0.7.
+ */
+type Owners =
+  | { owners: readonly string[]; bootstrapOwners?: never; rootAdmins?: never }
+  | {
+      /** @deprecated `owners`, read until 0.7. */
+      bootstrapOwners: readonly string[];
+      owners?: never;
+      rootAdmins?: never;
+    }
+  | {
+      /** @deprecated 0.5's name for `owners`, read until 0.7: a root admin is an Owner now. */
+      rootAdmins: readonly string[];
+      owners?: never;
+      bootstrapOwners?: never;
+    };
 
 function key32(value: string, what: string): Buffer {
   const raw = Buffer.from(value, 'base64');
@@ -113,7 +139,7 @@ export function resolveVaultConfig(config: VaultConfig): ResolvedVaultConfig {
   if (twice !== undefined) throw new Error(`two vault keys share an id: ${twice}`);
   return {
     keks: new KekRegistry(current, previous),
-    rootAdmins: checkRootAdmins(config.rootAdmins),
+    owners: checkOwners(config.owners ?? config.bootstrapOwners ?? config.rootAdmins ?? []),
     signingKeys: signingKeys(config.signingKey, keks),
     bulkLimit: config.bulkLimit === undefined ? DEFAULT_BULK_LIMIT : checkBulkLimit(config.bulkLimit),
   };
@@ -178,18 +204,18 @@ function isHumanEmail(value: string): boolean {
 }
 
 /**
- * Root admins, lowercased the way they are compared. At least one, in every
- * mode: they are the only way into a fresh instance, and the only members
- * nobody can remove.
+ * The Owners the deployment names, lowercased the way they are compared.
+ * At least one, in every mode: they are the only way into a fresh
+ * instance, and back into one whose Owners are locked out.
  */
-export function checkRootAdmins(emails: readonly string[]): string[] {
-  const rootAdmins = [...new Set(emails.map((entry) => entry.trim()).filter((entry) => entry.length > 0))];
-  if (rootAdmins.length === 0) {
-    throw new Error('rootAdmins must name at least one email, or nobody can manage coffre');
+export function checkOwners(emails: readonly string[]): string[] {
+  const owners = [...new Set(emails.map((entry) => entry.trim()).filter((entry) => entry.length > 0))];
+  if (owners.length === 0) {
+    throw new Error('owners must name at least one email, or nobody can manage coffre');
   }
-  const invalid = rootAdmins.find((entry) => !isHumanEmail(entry));
+  const invalid = owners.find((entry) => !isHumanEmail(entry));
   if (invalid) {
-    throw new Error(`rootAdmins must be human email identities; invalid: ${invalid}`);
+    throw new Error(`owners must be human email identities; invalid: ${invalid}`);
   }
-  return rootAdmins.map((entry) => entry.toLowerCase());
+  return [...new Set(owners.map((entry) => entry.toLowerCase()))];
 }

package/src/store.ts

@@ -1,11 +1,11 @@
-import { EVERYWHERE, type InstanceRole, type Scope } from '@coffre/core/access';
+import { EVERYWHERE, ownsInstance, 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, 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';
+import { and, asc, count, desc, eq, gt, gte, inArray, isNull, like, 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.
@@ -48,7 +48,8 @@ export type Place = Pick<GrantRow, 'projectId' | 'environmentId' | 'environmentS
 
 /** A grant as stored, which `@coffre/db/grants` reads and writes. */
 export type { GrantRow };
-export { accessEntriesAbout, insertGrant } from '@coffre/db/grants';
+export { accessEntriesAbout, insertGrant, liveProjects } from '@coffre/db/grants';
+export { newestVaultEntries } from '@coffre/db/log';
 
 /**
  * On Postgres, fail a lock wait in this transaction after `ms`, rather than
@@ -110,6 +111,22 @@ export async function allMembers(db: Queryable): Promise<Member[]> {
   return ((await db.select(memberColumns(db)).from(vaultMembers).orderBy(asc(vaultMembers.principal))) as StoredMember[]).map(memberOf);
 }
 
+/**
+ * The rows that say their member is an active Owner of the whole instance
+ * (`ownsInstance` in @coffre/core/access), as stored: a row changed around
+ * the vault says so too, which the caller checks. The scope is read as the
+ * row's MAC reads it, parsed: any way of writing everywhere is everywhere.
+ */
+export async function instanceOwners(db: Queryable): Promise<Member[]> {
+  const { vaultMembers } = tablesOf(db);
+  const rows = await db
+    .select(memberColumns(db))
+    .from(vaultMembers)
+    .where(and(eq(vaultMembers.status, 'active'), eq(vaultMembers.role, 'owner')))
+    .orderBy(asc(vaultMembers.principal));
+  return (rows as StoredMember[]).map(memberOf).filter(ownsInstance);
+}
+
 /**
  * Lock these members' rows for the rest of the transaction, in one order
  * everywhere, and read them: those that have none are not in the map. Every
@@ -258,19 +275,6 @@ export async function places(
   };
 }
 
-/** 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);
@@ -464,25 +468,6 @@ export async function latestVaultEntry(db: Queryable, actions: readonly string[]
   return row === undefined ? undefined : stored([row])[0];
 }
 
-/** 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))
-    .from(auditLog)
-    .where(
-      and(
-        eq(auditLog.author, 'vault'),
-        eq(auditLog.action, action),
-        eq(auditLog.decision, 'allow'),
-        before === undefined ? undefined : lt(auditLog.seq, before),
-      ),
-    )
-    .orderBy(desc(auditLog.seq))
-    .limit(limit);
-  return stored(rows);
-}
-
 /** The vault's newest allowed access entry about each member who has one. */
 export async function newestAccessEntries(db: Queryable): Promise<Map<string, StoredEntry>> {
   const { auditLog } = tablesOf(db);