@coffre/db 0.3.0 → 0.4.1

package/src/schema.ts

@@ -26,6 +26,22 @@ const bytea = customType<{ data: Buffer }>({
 
 const createdAt = () => timestamp('created_at', { withTimezone: true }).notNull().defaultNow();
 
+/**
+ * A project's or environment's slug: `market`, or once deleted, its
+ * tombstone's, `market~deleted-2026-10-05`. No live slug holds a `~`, so a
+ * tombstone frees its slug and is never mistaken for what takes it next.
+ */
+const PLACE_SLUG = sql.raw(`'^[a-z0-9][a-z0-9-]{0,62}(~[a-z0-9-]{1,40})?$'`);
+
+/**
+ * The folder a project or a secret is listed in: a folder lists rows
+ * together and does nothing else; it grants, hides and renames nothing. A
+ * name, not a row of its own: 1 to 64 characters, no `/`, no control
+ * character, no space at either end. Null is no folder.
+ */
+const folderCheck = (name: string, column: AnyPgColumn) =>
+  check(name, sql`${column} IS NULL OR (char_length(${column}) BETWEEN 1 AND 64 AND ${column} !~ '[/[:cntrl:]]' AND ${column} = btrim(${column}))`);
+
 export const projects = pgTable(
   'projects',
   {
@@ -34,10 +50,12 @@ export const projects = pgTable(
     name: text().notNull(),
     createdAt: createdAt(),
     archivedAt: timestamp('archived_at', { withTimezone: true }),
+    folder: text(),
   },
   (table) => [
     unique('projects_slug_key').on(table.slug),
-    check('projects_slug_check', sql`${table.slug} ~ '^[a-z0-9][a-z0-9-]{0,62}$'`),
+    check('projects_slug_check', sql`${table.slug} ~ ${PLACE_SLUG}`),
+    folderCheck('projects_folder_check', table.folder),
   ],
 );
 
@@ -54,7 +72,7 @@ export const environments = pgTable(
   (table) => [
     unique('environments_project_id_slug_key').on(table.projectId, table.slug),
     unique('environments_project_scoped').on(table.id, table.projectId),
-    check('environments_slug_check', sql`${table.slug} ~ '^[a-z0-9][a-z0-9-]{0,62}$'`),
+    check('environments_slug_check', sql`${table.slug} ~ ${PLACE_SLUG}`),
     foreignKey({
       name: 'environments_project_id_fkey',
       columns: [table.projectId],
@@ -80,6 +98,8 @@ export const secrets = pgTable(
     // append, so it is also the highest: the next one is this plus one.
     currentVersion: integer('current_version').notNull().default(0),
     archivedAt: timestamp('archived_at', { withTimezone: true }),
+    // Within its environment: the same key elsewhere has its own.
+    folder: text(),
   },
   (table) => [
     unique('secrets_project_id_environment_id_key_key').on(
@@ -88,6 +108,7 @@ export const secrets = pgTable(
       table.key,
     ),
     check('secrets_key_check', sql`${table.key} ~ '^[A-Za-z_][A-Za-z0-9_]{0,127}$'`),
+    folderCheck('secrets_folder_check', table.folder),
     foreignKey({
       name: 'secrets_project_id_fkey',
       columns: [table.projectId],
@@ -138,6 +159,34 @@ export const secretVersions = pgTable(
   ],
 );
 
+/**
+ * Keys an environment is missing, which its team decided it does not need:
+ * the project's other environments have them, and its missing-keys list
+ * leaves them out until someone restores them (docs/design/environments.md).
+ * One row per environment and key, updated in place: restoring sets
+ * `restored_at`, dismissing again clears it.
+ */
+export const dismissedKeys = pgTable(
+  'dismissed_keys',
+  {
+    environmentId: uuid('environment_id').notNull(),
+    key: text().notNull(),
+    dismissedAt: timestamp('dismissed_at', { withTimezone: true }).notNull().defaultNow(),
+    dismissedBy: text('dismissed_by').notNull(),
+    restoredAt: timestamp('restored_at', { withTimezone: true }),
+    restoredBy: text('restored_by'),
+  },
+  (table) => [
+    primaryKey({ name: 'dismissed_keys_pkey', columns: [table.environmentId, table.key] }),
+    check('dismissed_keys_key_check', sql`${table.key} ~ '^[A-Za-z_][A-Za-z0-9_]{0,127}$'`),
+    foreignKey({
+      name: 'dismissed_keys_environment_id_fkey',
+      columns: [table.environmentId],
+      foreignColumns: [environments.id],
+    }).onDelete('restrict'),
+  ],
+);
+
 /** The role catalogue, as SQL: every role, and those an environment may be granted. */
 const ROLES = sql.raw(ROLE_NAMES.map((role) => `'${role}'`).join(', '));
 const ENVIRONMENT_ROLES = sql.raw(ROLE_NAMES.filter(assignableToEnvironment).map((role) => `'${role}'`).join(', '));
@@ -146,7 +195,7 @@ const ENVIRONMENT_ROLES = sql.raw(ROLE_NAMES.filter(assignableToEnvironment).map
  * The vault's member directory: everyone it has admitted, written by the
  * vault alone, read by both. A principal with no row is no member.
  * Principals are the strings coffre uses at its edges: `user:<email>`,
- * `token:<id>`, `sync:<id>`. Times are milliseconds since the epoch, each
+ * `token:<id>`. Times are milliseconds since the epoch, each
  * the time of the vault's log entry that set it, so the log replays to
  * these rows exactly.
  */
@@ -174,7 +223,7 @@ export const vaultMembers = pgTable(
   },
   (table) => [
     check('vault_members_mac_check', sql`octet_length(${table.mac}) = 32`),
-    check('vault_members_principal_check', sql`${table.principal} ~ '^(user|token|sync):[^[:space:]:][^[:space:]]*$'`),
+    check('vault_members_principal_check', sql`${table.principal} ~ '^(user|token):[^[:space:]:][^[:space:]]*$'`),
     // A person is their email address, lowercased, as in sign-in.
     check('vault_members_user_lowercase', sql`${table.principal} NOT LIKE 'user:%' OR ${table.principal} = lower(${table.principal})`),
     check('vault_members_status_check', sql`${table.status} IN ('active', 'removed')`),
@@ -184,9 +233,11 @@ export const vaultMembers = pgTable(
 );
 
 /**
- * One role per member per place: a project, or one of its environments,
- * never both. A revoked grant is deleted; an expired one stays until its
- * place is granted again, so the members page can say it lapsed.
+ * One role per member per place: a project, one of its environments, every
+ * project (`*`, neither id), or the environment of one slug in every project
+ * (neither id, and `environment_slug`). A revoked grant is deleted; an
+ * expired one stays until its place is granted again, so the members page
+ * can say it lapsed.
  */
 export const vaultGrants = pgTable(
   'vault_grants',
@@ -194,17 +245,29 @@ export const vaultGrants = pgTable(
     principal: text().notNull(),
     projectId: uuid('project_id'),
     environmentId: uuid('environment_id'),
+    environmentSlug: text('environment_slug'),
     role: text().notNull(),
     expiresAt: bigint('expires_at', { mode: 'number' }),
     grantedAt: bigint('granted_at', { mode: 'number' }).notNull(),
     grantedBy: text('granted_by').notNull(),
   },
   (table) => [
-    check('vault_grants_one_place', sql`(${table.projectId} IS NULL) <> (${table.environmentId} IS NULL)`),
+    check(
+      'vault_grants_one_place',
+      sql`((${table.projectId} IS NULL) <> (${table.environmentId} IS NULL) AND ${table.environmentSlug} IS NULL) OR (${table.projectId} IS NULL AND ${table.environmentId} IS NULL)`,
+    ),
+    check('vault_grants_environment_slug_check', sql`${table.environmentSlug} IS NULL OR ${table.environmentSlug} ~ '^[a-z0-9][a-z0-9-]{0,62}$'`),
     check('vault_grants_role_check', sql`${table.role} IN (${ROLES})`),
-    check('vault_grants_environment_role_check', sql`${table.environmentId} IS NULL OR ${table.role} IN (${ENVIRONMENT_ROLES})`),
+    check(
+      'vault_grants_environment_role_check',
+      sql`(${table.environmentId} IS NULL AND ${table.environmentSlug} IS NULL) OR ${table.role} IN (${ENVIRONMENT_ROLES})`,
+    ),
     unique('vault_grants_on_project').on(table.principal, table.projectId),
     unique('vault_grants_on_environment').on(table.principal, table.environmentId),
+    unique('vault_grants_on_environment_slug').on(table.principal, table.environmentSlug),
+    uniqueIndex('vault_grants_on_every_project')
+      .on(table.principal)
+      .where(sql`${table.projectId} IS NULL AND ${table.environmentId} IS NULL AND ${table.environmentSlug} IS NULL`),
     foreignKey({
       name: 'vault_grants_principal_fkey',
       columns: [table.principal],
@@ -234,7 +297,7 @@ export const auditLog = pgTable(
     // Milliseconds since the epoch, from the database's clock, read after the
     // append took the head's lock.
     occurredAt: bigint('occurred_at', { mode: 'number' }).notNull(),
-    // Who acted: `user:<email>`, `token:<id>`, `sync:<id>` or `system:<name>`.
+    // Who acted: `user:<email>`, `token:<id>` or `system:<name>`.
     actor: text().notNull(),
     action: text().notNull(),
     decision: text().notNull(),
@@ -258,7 +321,7 @@ export const auditLog = pgTable(
   },
   (table) => [
     check('audit_log_author_check', sql`${table.author} IN ('app', 'vault')`),
-    check('audit_log_actor_check', sql`${table.actor} ~ '^(user|token|sync|system):.+$'`),
+    check('audit_log_actor_check', sql`${table.actor} ~ '^(user|token|system):.+$'`),
     check('audit_log_decision_check', sql`${table.decision} IN ('allow', 'deny')`),
     check('audit_log_metadata_check', sql`${table.metadata}::jsonb IS NOT NULL`),
     check('audit_log_prev_hash_check', sql`octet_length(${table.prevHash}) = 32`),
@@ -308,6 +371,72 @@ export const auditLog = pgTable(
     index('audit_log_exchange_idx')
       .on(sql`((${table.metadata})::jsonb ->> 'credentialId')`)
       .where(sql`${table.author} = 'app' AND ${table.action} = 'token.exchange' AND ${table.decision} = 'allow'`),
+    // Whether a reference has ended: the vault's `reference.end` naming its creation.
+    index('audit_log_reference_end_idx')
+      .on(table.relatedSeq)
+      .where(sql`${table.author} = 'vault' AND ${table.action} = 'reference.end' AND ${table.decision} = 'allow'`),
+    // An entry about a reference names the other side, `also` in its
+    // metadata, so that it is in both projects' logs: a read through
+    // billing's reference is market's read, and billing's too.
+    index('audit_log_also_project_idx')
+      .on(sql`(((${table.metadata})::jsonb -> 'also') ->> 'projectId')`, table.seq)
+      .where(sql`((${table.metadata})::jsonb -> 'also') IS NOT NULL`),
+    index('audit_log_also_environment_idx')
+      .on(sql`(((${table.metadata})::jsonb -> 'also') ->> 'environmentId')`, table.seq)
+      .where(sql`((${table.metadata})::jsonb -> 'also') IS NOT NULL`),
+    index('audit_log_also_secret_idx')
+      .on(sql`(((${table.metadata})::jsonb -> 'also') ->> 'secretId')`, table.seq)
+      .where(sql`((${table.metadata})::jsonb -> 'also') IS NOT NULL`),
+  ],
+);
+
+/**
+ * A reference: a secret whose value is another's, read live through it by
+ * whoever reads the holder's environment (docs/design/environments.md).
+ * The row only points: the reference is the vault's `reference.create`
+ * entry at `created_seq`, which the vault checks at every read, and a
+ * `reference.end` naming that entry ends it, whatever this table says. So
+ * rows are only ever added.
+ */
+export const secretReferences = pgTable(
+  'secret_references',
+  {
+    id: uuid().primaryKey(),
+    // The holder: billing/prod/DATABASE_URL.
+    projectId: uuid('project_id').notNull(),
+    environmentId: uuid('environment_id').notNull(),
+    secretId: uuid('secret_id').notNull(),
+    // The source: market/prod/DATABASE_URL.
+    sourceProjectId: uuid('source_project_id').notNull(),
+    sourceEnvironmentId: uuid('source_environment_id').notNull(),
+    sourceSecretId: uuid('source_secret_id').notNull(),
+    createdSeq: bigint('created_seq', { mode: 'bigint' }).notNull(),
+    createdAt: createdAt(),
+    createdBy: text('created_by').notNull(),
+  },
+  (table) => [
+    unique('secret_references_created_seq_key').on(table.createdSeq),
+    foreignKey({
+      name: 'secret_references_secret_id_fkey',
+      columns: [table.secretId],
+      foreignColumns: [secrets.id],
+    }).onDelete('restrict'),
+    foreignKey({
+      name: 'secret_references_source_secret_id_fkey',
+      columns: [table.sourceSecretId],
+      foreignColumns: [secrets.id],
+    }).onDelete('restrict'),
+    foreignKey({
+      name: 'secret_references_created_seq_fkey',
+      columns: [table.createdSeq],
+      foreignColumns: [auditLog.seq],
+    }).onDelete('restrict'),
+    // A holder's newest reference; what reads its source; what a project lends; what someone made.
+    index('secret_references_holder_idx').on(table.secretId, table.createdSeq),
+    index('secret_references_source_idx').on(table.sourceSecretId),
+    index('secret_references_project_idx').on(table.projectId),
+    index('secret_references_source_project_idx').on(table.sourceProjectId),
+    index('secret_references_created_by_idx').on(table.createdBy),
   ],
 );
 
@@ -430,6 +559,129 @@ export const consumedTokens = pgTable(
   (table) => [check('consumed_tokens_hash_check', sql`octet_length(${table.hash}) = 32`)],
 );
 
+/**
+ * MCP clients that registered themselves (RFC 7591), the fallback to Client
+ * ID Metadata Documents, which need no row. The ID is the client's
+ * `client_id`. Its redirects are under its MAC: a database writer cannot add
+ * one of their own to a client people have approved.
+ */
+export const oauthClients = pgTable(
+  'oauth_clients',
+  {
+    id: uuid().primaryKey(),
+    authMac: bytea('auth_mac').notNull(),
+    // Its own claim, shown as unverified.
+    name: text().notNull(),
+    // JSON: a list of HTTPS or loopback URLs.
+    redirectUris: text('redirect_uris').notNull(),
+    createdAt: createdAt(),
+    createdIp: text('created_ip'),
+    revokedAt: timestamp('revoked_at', { withTimezone: true }),
+  },
+  (table) => [
+    check('oauth_clients_auth_mac_check', sql`octet_length(${table.authMac}) = 32`),
+    check('oauth_clients_redirect_uris_check', sql`${table.redirectUris}::jsonb IS NOT NULL`),
+  ],
+);
+
+/**
+ * One MCP client a person connected: one approved authorization, its
+ * scopes, its code until the client redeems it, and the refresh token it
+ * holds since. Access tokens have no row: each names its connection under a
+ * MAC, and every request checks this row. Revoking it ends them all.
+ */
+export const mcpConnections = pgTable(
+  'mcp_connections',
+  {
+    id: uuid().primaryKey(),
+    authMac: bytea('auth_mac').notNull(),
+    // The person it acts as, `user:<email>`, under the generation they approved it in.
+    principal: text().notNull(),
+    generation: integer().notNull(),
+    // A metadata document's URL, or a registration's ID.
+    clientId: text('client_id').notNull(),
+    // As the consent page showed them: display only.
+    clientName: text('client_name').notNull(),
+    clientHost: text('client_host'),
+    registration: text().notNull(),
+    // Space-separated, in catalogue order: `browse write`.
+    scopes: text().notNull(),
+    redirectUri: text('redirect_uri').notNull(),
+    // Until the client redeems it: its SHA-256, its PKCE challenge, and 60 seconds.
+    codeHash: bytea('code_hash'),
+    codeChallenge: text('code_challenge'),
+    codeExpiresAt: timestamp('code_expires_at', { withTimezone: true }),
+    // From then on: the refresh token's SHA-256, and the one it replaced, whose reuse ends the connection.
+    refreshHash: bytea('refresh_hash'),
+    refreshPreviousHash: bytea('refresh_previous_hash'),
+    expiresAt: timestamp('expires_at', { withTimezone: true }).notNull(),
+    createdAt: createdAt(),
+    lastUsedAt: timestamp('last_used_at', { withTimezone: true }),
+    lastUsedIp: text('last_used_ip'),
+    revokedAt: timestamp('revoked_at', { withTimezone: true }),
+    revokedBy: text('revoked_by'),
+  },
+  (table) => [
+    check('mcp_connections_principal_check', sql`${table.principal} LIKE 'user:%'`),
+    check('mcp_connections_registration_check', sql`${table.registration} IN ('cimd', 'dcr')`),
+    check('mcp_connections_auth_mac_check', sql`octet_length(${table.authMac}) = 32`),
+    check('mcp_connections_code_hash_check', sql`${table.codeHash} IS NULL OR octet_length(${table.codeHash}) = 32`),
+    check('mcp_connections_refresh_hash_check', sql`${table.refreshHash} IS NULL OR octet_length(${table.refreshHash}) = 32`),
+    foreignKey({
+      name: 'mcp_connections_principal_fkey',
+      columns: [table.principal],
+      foreignColumns: [vaultMembers.principal],
+    }).onDelete('restrict'),
+    unique('mcp_connections_code_hash_key').on(table.codeHash),
+    unique('mcp_connections_refresh_hash_key').on(table.refreshHash),
+    index('mcp_connections_refresh_previous_idx').on(table.refreshPreviousHash),
+    // A person's live connections: Connected apps, and the limit on how many.
+    index('mcp_connections_live_idx').on(table.principal, table.expiresAt).where(sql`${table.revokedAt} IS NULL`),
+  ],
+);
+
+/**
+ * A change an MCP client asked for, waiting for its person on coffre's own
+ * page (docs/design/mcp.md, section 7). It holds the tool and its arguments,
+ * never a value: the page shows what they would do and, on Approve, does it,
+ * once, as the person, through the connection. Its digest is of the tool
+ * and arguments, which the page sends back with the decision, so what runs
+ * is what the person read. Not MACed: a row changes nothing by itself.
+ */
+export const mcpApprovals = pgTable(
+  'mcp_approvals',
+  {
+    id: uuid().primaryKey(),
+    connectionId: uuid('connection_id').notNull(),
+    tool: text().notNull(),
+    // JSON: the tool's arguments, as checked when it was called.
+    arguments: text().notNull(),
+    // SHA-256 of the canonical JSON of the tool and its arguments.
+    digest: bytea().notNull(),
+    // pending, approved, denied, cancelled or failed; a pending one past its expiry has expired.
+    status: text().notNull().default('pending'),
+    // JSON: what the change answered, or why it failed. Never a value.
+    outcome: text(),
+    createdAt: createdAt(),
+    expiresAt: timestamp('expires_at', { withTimezone: true }).notNull(),
+    decidedAt: timestamp('decided_at', { withTimezone: true }),
+    // When the client read the outcome: an identical call after that asks again.
+    reportedAt: timestamp('reported_at', { withTimezone: true }),
+  },
+  (table) => [
+    check('mcp_approvals_status_check', sql`${table.status} IN ('pending', 'approved', 'denied', 'cancelled', 'failed')`),
+    check('mcp_approvals_digest_check', sql`octet_length(${table.digest}) = 32`),
+    check('mcp_approvals_arguments_check', sql`${table.arguments}::jsonb IS NOT NULL`),
+    foreignKey({
+      name: 'mcp_approvals_connection_fkey',
+      columns: [table.connectionId],
+      foreignColumns: [mcpConnections.id],
+    }).onDelete('restrict'),
+    // A connection's approvals its client has not yet heard the end of: the ones a call rejoins, and the five it may wait on.
+    index('mcp_approvals_open_idx').on(table.connectionId, table.digest).where(sql`${table.reportedAt} IS NULL`),
+  ],
+);
+
 /**
  * Bearer credentials coffre issues itself: browser sessions, CLI sessions and
  * service tokens.

package/dist/migrations/postgres/0001_remove_syncs.sql

@@ -1,13 +0,0 @@
--- Stop old app instances before upgrading. Never silently discard a configured
--- destination, including archived ones. Keep the audit and sealed legacy rows.
-LOCK TABLE syncs, sync_keys IN ACCESS EXCLUSIVE MODE;
---> statement-breakpoint
-DO $$ BEGIN
-  IF EXISTS (SELECT 1 FROM syncs) OR EXISTS (SELECT 1 FROM sync_keys) THEN
-    RAISE EXCEPTION 'syncs are removed: migrate destinations to service tokens, back up and clear syncs and sync_keys before upgrading';
-  END IF;
-END $$;
---> statement-breakpoint
-DROP TABLE sync_keys;
---> statement-breakpoint
-DROP TABLE syncs;

package/dist/migrations/postgres/0002_service_bindings.sql

@@ -1,28 +0,0 @@
-CREATE TABLE "service_bindings" (
-	"id" uuid PRIMARY KEY NOT NULL,
-	"auth_mac" "bytea" NOT NULL,
-	"principal" text NOT NULL,
-	"generation" integer NOT NULL,
-	"profile" text NOT NULL,
-	"issuer" text NOT NULL,
-	"jwks_uri" text NOT NULL,
-	"claims" text NOT NULL,
-	"label" text,
-	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
-	"created_by" text NOT NULL,
-	"last_used_at" timestamp with time zone,
-	"revoked_at" timestamp with time zone,
-	"revoked_by" text,
-	CONSTRAINT "service_bindings_principal_check" CHECK ("service_bindings"."principal" LIKE 'token:%'),
-	CONSTRAINT "service_bindings_auth_mac_check" CHECK (octet_length("service_bindings"."auth_mac") = 32),
-	CONSTRAINT "service_bindings_claims_check" CHECK ("service_bindings"."claims"::jsonb IS NOT NULL)
-);
---> statement-breakpoint
-ALTER TABLE "service_bindings" ADD CONSTRAINT "service_bindings_principal_fkey" FOREIGN KEY ("principal") REFERENCES "public"."vault_members"("principal") ON DELETE restrict ON UPDATE no action;--> statement-breakpoint
-CREATE INDEX "service_bindings_principal_idx" ON "service_bindings" USING btree ("principal","issuer");--> statement-breakpoint
-CREATE INDEX "audit_log_unbind_idx" ON "audit_log" USING btree ((("metadata")::jsonb ->> 'bindingId')) WHERE "audit_log"."author" = 'app' AND "audit_log"."action" = 'token.unbind' AND "audit_log"."decision" = 'allow';--> statement-breakpoint
--- The app reads and adds bindings, and changes only what the MAC allows to
--- change in place: its label, its last use, and its revocation (with the
--- MAC that covers it). A binding's policy is never updated, nor deleted.
-GRANT SELECT, INSERT ON service_bindings TO coffre_app;--> statement-breakpoint
-GRANT UPDATE (label, last_used_at, revoked_at, revoked_by, auth_mac) ON service_bindings TO coffre_app;

package/dist/migrations/postgres/0003_exchanges.sql

@@ -1,10 +0,0 @@
-CREATE TABLE "consumed_tokens" (
-	"hash" "bytea" PRIMARY KEY NOT NULL,
-	"consumed_at" timestamp with time zone DEFAULT now() NOT NULL,
-	CONSTRAINT "consumed_tokens_hash_check" CHECK (octet_length("consumed_tokens"."hash") = 32)
-);
---> statement-breakpoint
-CREATE INDEX "audit_log_exchange_idx" ON "audit_log" USING btree ((("metadata")::jsonb ->> 'credentialId')) WHERE "audit_log"."author" = 'app' AND "audit_log"."action" = 'token.exchange' AND "audit_log"."decision" = 'allow';--> statement-breakpoint
--- The app records each token it exchanges, and reads whether one was; it
--- never changes or deletes a record, so a token stays spent.
-GRANT SELECT, INSERT ON consumed_tokens TO coffre_app;

package/dist/migrations/postgres/0004_live_indexes.sql

@@ -1,3 +0,0 @@
-CREATE INDEX "credentials_live_idx" ON "credentials" USING btree ("principal","expires_at") WHERE "credentials"."revoked_at" IS NULL;--> statement-breakpoint
-CREATE INDEX "credentials_issued_by_idx" ON "credentials" USING btree ("principal","created_by","created_at");--> statement-breakpoint
-CREATE INDEX "service_bindings_live_idx" ON "service_bindings" USING btree ("principal","issuer","generation","created_at","id") WHERE "service_bindings"."revoked_at" IS NULL;