@coffre/db 0.10.2 → 0.12.0

package/dist/schema.js

@@ -6,10 +6,12 @@ import { bigint, boolean, check, customType, foreignKey, index, integer, pgTable
 var schema_exports = /* @__PURE__ */ __exportAll({
 	auditChainHead: () => auditChainHead,
 	auditLog: () => auditLog,
+	cappedAlerts: () => cappedAlerts,
 	consumedTokens: () => consumedTokens,
 	credentials: () => credentials,
 	deviceAuthorizations: () => deviceAuthorizations,
 	dismissedKeys: () => dismissedKeys,
+	enrollments: () => enrollments,
 	environments: () => environments,
 	environmentsRelations: () => environmentsRelations,
 	identities: () => identities,
@@ -302,6 +304,8 @@ const auditLog = pgTable("audit_log", {
 	index("audit_log_releases_idx").on(table.author, table.actor, table.action, table.decision, table.occurredAt),
 	index("audit_log_subject_idx").on(table.author, table.subjectPrincipal, table.seq),
 	index("audit_log_unbind_idx").on(sql`((${table.metadata})::jsonb ->> 'bindingId')`).where(sql`${table.author} = 'app' AND ${table.action} = 'token.unbind' AND ${table.decision} = 'allow'`),
+	index("audit_log_freeze_idx").on(sql`((${table.metadata})::jsonb ->> 'target')`, table.seq.desc()).where(sql`${table.author} = 'app' AND ${table.action} IN ('workload.freeze', 'workload.unfreeze') AND ${table.decision} = 'allow'`),
+	index("audit_log_supersede_idx").on(sql`((${table.metadata})::jsonb ->> 'enrollmentId')`).where(sql`${table.author} = 'app' AND ${table.action} = 'enrollment.supersede' AND ${table.decision} = 'allow'`),
 	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'`),
 	index("audit_log_token_create_idx").on(sql`((${table.metadata})::jsonb ->> 'targetCredentialId')`).where(sql`${table.author} = 'app' AND ${table.action} = 'token.create' AND ${table.decision} = 'allow'`),
 	index("audit_log_reference_end_idx").on(table.relatedSeq).where(sql`${table.author} = 'vault' AND ${table.action} = 'reference.end' AND ${table.decision} = 'allow'`),
@@ -414,6 +418,7 @@ const serviceBindings = pgTable("service_bindings", {
 	jwks: text(),
 	claims: text().notNull(),
 	scope: text(),
+	policy: text(),
 	label: text(),
 	createdAt: createdAt(),
 	createdBy: text("created_by").notNull(),
@@ -443,6 +448,22 @@ const consumedTokens = pgTable("consumed_tokens", {
 	consumedAt: timestamp("consumed_at", { withTimezone: true }).notNull().defaultNow()
 }, (table) => [check("consumed_tokens_hash_check", sql`octet_length(${table.hash}) = 32`)]);
 /**
+* When a service's capped alert was last raised, by kind: the refusal of a
+* token signed by a key its uploaded keys lack (`unknown_key`) alerts once
+* an hour, however many isolates see it. One conditional write per refusal
+* decides (`claimAlert`), so that the many it caps never reach the log's
+* head. Only a request that a binding of the service on the token's issuer
+* gets as far as its keys writes here: a row per service, at most, per kind.
+*/
+const cappedAlerts = pgTable("capped_alerts", {
+	service: text().notNull(),
+	kind: text().notNull(),
+	raisedAt: timestamp("raised_at", { withTimezone: true }).notNull()
+}, (table) => [primaryKey({
+	name: "capped_alerts_pkey",
+	columns: [table.service, table.kind]
+})]);
+/**
 * 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
@@ -533,6 +554,37 @@ const mcpApprovals = pgTable("mcp_approvals", {
 	index("mcp_approvals_open_idx").on(table.connectionId, table.digest).where(sql`${table.reportedAt} IS NULL`)
 ]);
 /**
+* Enrollment codes (docs/design/workload-access.md, section 4.4): what CI
+* mints for a platform that signs no identity, and the app exchanges for a
+* workload's session at `/api/auth/workload`. Never a credential itself, and
+* only ever added: the log says which code a promote superseded. Its scope,
+* fixed at minting, is the binding's within what the minter held; the MAC
+* covers everything but its hint and creation time (auth-rows.ts in the server).
+*/
+const enrollments = pgTable("enrollments", {
+	id: uuid().primaryKey(),
+	authMac: bytea("auth_mac").notNull(),
+	bindingId: uuid("binding_id").notNull(),
+	codeHash: bytea("code_hash").notNull(),
+	codeHint: text("code_hint").notNull(),
+	scope: text().notNull(),
+	createdAt: createdAt(),
+	createdBy: text("created_by").notNull(),
+	createdWith: uuid("created_with"),
+	expiresAt: timestamp("expires_at", { withTimezone: true }).notNull()
+}, (table) => [
+	unique("enrollments_code_hash_key").on(table.codeHash),
+	check("enrollments_auth_mac_check", sql`octet_length(${table.authMac}) = 32`),
+	check("enrollments_code_hash_check", sql`octet_length(${table.codeHash}) = 32`),
+	check("enrollments_scope_check", sql`${table.scope}::jsonb IS NOT NULL`),
+	foreignKey({
+		name: "enrollments_binding_id_fkey",
+		columns: [table.bindingId],
+		foreignColumns: [serviceBindings.id]
+	}).onDelete("restrict"),
+	index("enrollments_binding_idx").on(table.bindingId, table.createdAt.desc())
+]);
+/**
 * Bearer credentials coffre issues itself: browser sessions, CLI sessions and
 * service tokens.
 *
@@ -558,12 +610,20 @@ const credentials = pgTable("credentials", {
 	lastUsedAt: timestamp("last_used_at", { withTimezone: true }),
 	lastUsedIp: text("last_used_ip"),
 	revokedAt: timestamp("revoked_at", { withTimezone: true }),
-	revokedBy: text("revoked_by")
+	revokedBy: text("revoked_by"),
+	jkt: text(),
+	notAfter: timestamp("not_after", { withTimezone: true }),
+	ancestors: text(),
+	constraints: text(),
+	enrollmentId: uuid("enrollment_id"),
+	approvedAt: timestamp("approved_at", { withTimezone: true }),
+	approvedBy: text("approved_by")
 }, (table) => [
 	unique("credentials_token_hash_key").on(table.tokenHash),
-	check("credentials_kind_check", sql`${table.kind} IN ('browser', 'cli', 'service', 'personal', 'handle')`),
+	check("credentials_kind_check", sql`${table.kind} IN ('browser', 'cli', 'service', 'personal', 'handle', 'workload')`),
 	check("credentials_principal_check", sql`${table.principal} LIKE 'user:%' OR ${table.principal} LIKE 'token:%'`),
-	check("credentials_kind_matches_principal", sql`(${table.kind} = 'service') = (${table.principal} LIKE 'token:%')`),
+	check("credentials_kind_matches_principal", sql`(${table.kind} IN ('service', 'workload')) = (${table.principal} LIKE 'token:%')`),
+	check("credentials_workload_jkt_check", sql`${table.kind} <> 'workload' OR ${table.jkt} IS NOT NULL`),
 	check("credentials_token_hash_check", sql`octet_length(${table.tokenHash}) = 32`),
 	check("credentials_auth_mac_check", sql`octet_length(${table.authMac}) = 32`),
 	foreignKey({
@@ -586,7 +646,13 @@ const credentials = pgTable("credentials", {
 	}).onDelete("restrict"),
 	index("credentials_principal_idx").on(table.principal, table.generation),
 	index("credentials_live_idx").on(table.principal, table.expiresAt).where(sql`${table.revokedAt} IS NULL`),
-	index("credentials_issued_by_idx").on(table.principal, table.createdBy, table.createdAt)
+	index("credentials_issued_by_idx").on(table.principal, table.createdBy, table.createdAt),
+	foreignKey({
+		name: "credentials_enrollment_id_fkey",
+		columns: [table.enrollmentId],
+		foreignColumns: [enrollments.id]
+	}).onDelete("restrict"),
+	index("credentials_enrollment_roots_idx").on(table.enrollmentId, table.createdAt).where(sql`${table.kind} = 'workload' AND ${table.ancestors} IS NULL`)
 ]);
 /**
 * A CLI asking to be signed in from a browser (RFC 8628, device flow).
@@ -632,4 +698,4 @@ const { environmentsRelations, secretsRelations } = relationsOf({
 	secretVersions
 });
 //#endregion
-export { auditChainHead, auditLog, consumedTokens, credentials, deviceAuthorizations, dismissedKeys, environments, environmentsRelations, identities, mcpApprovals, mcpConnections, oauthClients, projects, secretReferences, secretVersions, secrets, secretsRelations, serviceBindings, schema_exports as t, vaultGrants, vaultMembers };
+export { auditChainHead, auditLog, cappedAlerts, consumedTokens, credentials, deviceAuthorizations, dismissedKeys, enrollments, environments, environmentsRelations, identities, mcpApprovals, mcpConnections, oauthClients, projects, secretReferences, secretVersions, secrets, secretsRelations, serviceBindings, schema_exports as t, vaultGrants, vaultMembers };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coffre/db",
-  "version": "0.10.2",
+  "version": "0.12.0",
   "description": "coffre's database: the schema, its migrations and the connections, on Postgres or SQLite.",
   "license": "MIT",
   "repository": {
@@ -79,7 +79,7 @@
     "drizzle-orm": "0.45.2",
     "pg": "8.16.3",
     "pg-connection-string": "2.14.0",
-    "@coffre/core": "0.10.2"
+    "@coffre/core": "0.12.0"
   },
   "devDependencies": {
     "@types/node": "26.1.1",

package/src/grants.ts

@@ -205,35 +205,44 @@ export async function everyProjectPreview(db: Queryable, at: number): Promise<Ev
   });
 }
 
-/** A service token or trust binding of 0.4, which carries no scope of its own yet. */
-export type Unsealed = { kind: 'token' | 'binding'; id: string; principal: string };
+/**
+ * A service token or trust binding whose scope this release has not sealed
+ * yet: none of its own, as 0.4 made it (`scope` null), or one that does not
+ * say where it reads sensitive values, as a release before 0.11 made it. By
+ * whom it was issued, `createdBy`, a person's email.
+ */
+export type Unsealed = { kind: 'token' | 'binding'; id: string; principal: string; createdBy: string; scope: string | null };
 
 /**
  * The live service tokens and trust bindings of active service accounts
- * that carry no scope yet, as 0.4 made them: what the app seals with each
- * account's grants once a process (`sealScopes`), and what `coffre migrate`
- * says it will. A credential a binding issued carries its binding's.
+ * whose scope is not sealed yet (`Unsealed`): what the app seals once a
+ * process (`sealScopes`), and what `coffre migrate` says it will. A
+ * credential a binding issued carries its binding's.
  */
 export async function unsealedCredentials(db: Queryable, at: Date): Promise<Unsealed[]> {
   const { credentials, serviceBindings, vaultMembers } = tablesOf(db);
+  // Every scope this release writes for a service says, at each place it names, whether it reads the sensitive values
+  // there; one that names none, sealed while its account held nothing, is sealed (`unsealedScope` in @coffre/server).
+  const unsealed = (scope: typeof credentials.scope | typeof serviceBindings.scope) =>
+    or(isNull(scope), and(like(scope, '%"projectId"%'), sql`${scope} NOT LIKE '%"sensitive":%'`));
   const [tokens, bindings] = await Promise.all([
     db
-      .select({ id: credentials.id, principal: credentials.principal })
+      .select({ id: credentials.id, principal: credentials.principal, createdBy: credentials.createdBy, scope: credentials.scope })
       .from(credentials)
       .innerJoin(vaultMembers, and(eq(vaultMembers.principal, credentials.principal), eq(vaultMembers.generation, credentials.generation)))
       .where(and(
         eq(credentials.kind, 'service'),
-        isNull(credentials.scope),
+        unsealed(credentials.scope),
         sql`${credentials.createdBy} NOT LIKE 'binding:%'`,
         isNull(credentials.revokedAt),
         gt(credentials.expiresAt, at),
         eq(vaultMembers.status, 'active'),
       )),
     db
-      .select({ id: serviceBindings.id, principal: serviceBindings.principal })
+      .select({ id: serviceBindings.id, principal: serviceBindings.principal, createdBy: serviceBindings.createdBy, scope: serviceBindings.scope })
       .from(serviceBindings)
       .innerJoin(vaultMembers, and(eq(vaultMembers.principal, serviceBindings.principal), eq(vaultMembers.generation, serviceBindings.generation)))
-      .where(and(isNull(serviceBindings.scope), isNull(serviceBindings.revokedAt), eq(vaultMembers.status, 'active'))),
+      .where(and(unsealed(serviceBindings.scope), isNull(serviceBindings.revokedAt), eq(vaultMembers.status, 'active'))),
   ]);
   return [
     ...tokens.map((row) => ({ kind: 'token' as const, ...row })),

package/src/hyperdrive.ts

@@ -48,16 +48,26 @@ export class HyperdrivePool implements Exclude<PoolLike, pg.Pool> {
   #busy = 0;
   /** What waits for the client to be idle: `end`. */
   readonly #idle: (() => void)[] = [];
+  /** How long the client may sit idle before it closes, or null: closed by `end` alone. */
+  readonly #closeIdleMs: number | null;
+  #idleTimer: ReturnType<typeof setTimeout> | undefined;
 
-  constructor(connectionString: string) {
+  /**
+   * `closeIdleMs`: for what outlives a call, a Durable Object, which queries
+   * now and then: the client closes once it has been idle that long, and
+   * the next query connects again.
+   */
+  constructor(connectionString: string, options: { closeIdleMs?: number } = {}) {
     if (connectionString.trim().length === 0) {
       throw new Error('Hyperdrive returned an empty connection string');
     }
     this.#connectionString = connectionString;
+    this.#closeIdleMs = options.closeIdleMs ?? null;
   }
 
   readonly query: pg.Pool['query'] = (async (...args: unknown[]) => {
     this.#busy += 1;
+    clearTimeout(this.#idleTimer);
     try {
       const client = await this.#connected();
       return await new Promise((resolve, reject) => {
@@ -72,6 +82,7 @@ export class HyperdrivePool implements Exclude<PoolLike, pg.Pool> {
   /** The client, for a transaction: held from now until `release`. */
   async connect(): Promise<Pick<pg.PoolClient, 'query'> & { release: () => void }> {
     this.#busy += 1;
+    clearTimeout(this.#idleTimer);
     let client: pg.Client;
     try {
       client = await this.#connected();
@@ -100,6 +111,7 @@ export class HyperdrivePool implements Exclude<PoolLike, pg.Pool> {
 
   /** Close the client once nothing waits on it: what a Worker hands `waitUntil` when the call is done. */
   async end(): Promise<void> {
+    clearTimeout(this.#idleTimer);
     while (this.#busy > 0) {
       await new Promise<void>((resolve) => this.#idle.push(resolve));
     }
@@ -123,7 +135,9 @@ export class HyperdrivePool implements Exclude<PoolLike, pg.Pool> {
   /** One query or transaction done: once none is left, what waits for the client to be idle goes on. */
   #done(): void {
     this.#busy -= 1;
-    if (this.#busy === 0) for (const resolve of this.#idle.splice(0)) resolve();
+    if (this.#busy > 0) return;
+    for (const resolve of this.#idle.splice(0)) resolve();
+    if (this.#closeIdleMs !== null && this.#client !== null) this.#idleTimer = setTimeout(() => void this.end(), this.#closeIdleMs);
   }
 
   /** The call's client, connecting it the first time. One that fails is dropped: the next query connects again. */

package/src/migrations/postgres/0015_workload_access.sql

@@ -0,0 +1,43 @@
+-- Workload access (docs/design/workload-access.md, section 11): key-bound sessions, their enrollment codes, and bindings' policies. It only adds: the release before neither reads nor writes any of it, and every check is only looser for its rows, so it serves on this schema unchanged.
+CREATE TABLE "enrollments" (
+	"id" uuid PRIMARY KEY NOT NULL,
+	"auth_mac" "bytea" NOT NULL,
+	"binding_id" uuid NOT NULL,
+	"code_hash" "bytea" NOT NULL,
+	"code_hint" text NOT NULL,
+	"scope" text NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"created_by" text NOT NULL,
+	"created_with" uuid,
+	"expires_at" timestamp with time zone NOT NULL,
+	CONSTRAINT "enrollments_code_hash_key" UNIQUE("code_hash"),
+	CONSTRAINT "enrollments_auth_mac_check" CHECK (octet_length("enrollments"."auth_mac") = 32),
+	CONSTRAINT "enrollments_code_hash_check" CHECK (octet_length("enrollments"."code_hash") = 32),
+	CONSTRAINT "enrollments_scope_check" CHECK ("enrollments"."scope"::jsonb IS NOT NULL)
+);
+--> statement-breakpoint
+-- The checks widen to a workload's session, a service's credential like a service token; a session carries the key it is bound to.
+ALTER TABLE "credentials" DROP CONSTRAINT "credentials_kind_check";--> statement-breakpoint
+ALTER TABLE "credentials" DROP CONSTRAINT "credentials_kind_matches_principal";--> statement-breakpoint
+ALTER TABLE "credentials" ADD COLUMN "jkt" text;--> statement-breakpoint
+ALTER TABLE "credentials" ADD COLUMN "not_after" timestamp with time zone;--> statement-breakpoint
+ALTER TABLE "credentials" ADD COLUMN "ancestors" text;--> statement-breakpoint
+ALTER TABLE "credentials" ADD COLUMN "constraints" text;--> statement-breakpoint
+ALTER TABLE "credentials" ADD COLUMN "enrollment_id" uuid;--> statement-breakpoint
+ALTER TABLE "credentials" ADD COLUMN "approved_at" timestamp with time zone;--> statement-breakpoint
+ALTER TABLE "credentials" ADD COLUMN "approved_by" text;--> statement-breakpoint
+-- A binding's policy, inserted with it under the table-wide INSERT, and named by no UPDATE grant: as immutable as the rest of it.
+ALTER TABLE "service_bindings" ADD COLUMN "policy" text;--> statement-breakpoint
+ALTER TABLE "enrollments" ADD CONSTRAINT "enrollments_binding_id_fkey" FOREIGN KEY ("binding_id") REFERENCES "public"."service_bindings"("id") ON DELETE restrict ON UPDATE no action;--> statement-breakpoint
+CREATE INDEX "enrollments_binding_idx" ON "enrollments" USING btree ("binding_id","created_at" DESC NULLS LAST);--> statement-breakpoint
+ALTER TABLE "credentials" ADD CONSTRAINT "credentials_enrollment_id_fkey" FOREIGN KEY ("enrollment_id") REFERENCES "public"."enrollments"("id") ON DELETE restrict ON UPDATE no action;--> statement-breakpoint
+-- Freezes are the log's: a target's newest allowed freeze or lift, and a code's supersession, its tombstone.
+CREATE INDEX "audit_log_freeze_idx" ON "audit_log" USING btree ((("metadata")::jsonb ->> 'target'),"seq" DESC NULLS LAST) WHERE "audit_log"."author" = 'app' AND "audit_log"."action" IN ('workload.freeze', 'workload.unfreeze') AND "audit_log"."decision" = 'allow';--> statement-breakpoint
+CREATE INDEX "audit_log_supersede_idx" ON "audit_log" USING btree ((("metadata")::jsonb ->> 'enrollmentId')) WHERE "audit_log"."author" = 'app' AND "audit_log"."action" = 'enrollment.supersede' AND "audit_log"."decision" = 'allow';--> statement-breakpoint
+CREATE INDEX "credentials_enrollment_roots_idx" ON "credentials" USING btree ("enrollment_id","created_at") WHERE "credentials"."kind" = 'workload' AND "credentials"."ancestors" IS NULL;--> statement-breakpoint
+ALTER TABLE "credentials" ADD CONSTRAINT "credentials_workload_jkt_check" CHECK ("credentials"."kind" <> 'workload' OR "credentials"."jkt" IS NOT NULL);--> statement-breakpoint
+ALTER TABLE "credentials" ADD CONSTRAINT "credentials_kind_check" CHECK ("credentials"."kind" IN ('browser', 'cli', 'service', 'personal', 'handle', 'workload'));--> statement-breakpoint
+ALTER TABLE "credentials" ADD CONSTRAINT "credentials_kind_matches_principal" CHECK (("credentials"."kind" IN ('service', 'workload')) = ("credentials"."principal" LIKE 'token:%'));--> statement-breakpoint
+-- The app makes codes and never changes one; a session's key, hard end, ancestors, limits and code are set when it is made, and never after: renewal moves its expiry, and an approval is the one other change.
+GRANT SELECT, INSERT ON enrollments TO coffre_app;--> statement-breakpoint
+GRANT UPDATE (expires_at, approved_at, approved_by) ON credentials TO coffre_app;

package/src/migrations/postgres/0016_spent_tokens.sql

@@ -0,0 +1,12 @@
+-- Spent tokens (W157): a token's record goes once no exchange could take the token again. An exchange refuses one issued over an hour ago (MAX_TOKEN_AGE_SECONDS, 30 s of clock tolerance), so two hours after it was spent its record guards nothing. The runtime login still deletes no row itself: it asks this function, which deletes only such records, at most at_most a call. The release before never calls it.
+CREATE FUNCTION prune_consumed_tokens(at_most integer) RETURNS integer
+    LANGUAGE sql SECURITY DEFINER SET search_path = pg_catalog, pg_temp AS $$
+    WITH pruned AS (
+        DELETE FROM public.consumed_tokens
+         WHERE hash IN (SELECT hash FROM public.consumed_tokens WHERE consumed_at < now() - interval '2 hours' LIMIT at_most)
+        RETURNING 1
+    )
+    SELECT count(*)::integer FROM pruned;
+$$;--> statement-breakpoint
+REVOKE ALL ON FUNCTION prune_consumed_tokens(integer) FROM PUBLIC;--> statement-breakpoint
+GRANT EXECUTE ON FUNCTION prune_consumed_tokens(integer) TO coffre_app;

package/src/migrations/postgres/0017_capped_alerts.sql

@@ -0,0 +1,10 @@
+-- Capped alerts (T98): when a service's sign-in was last refused `unknown_key` with an alert, so that the next alerts an hour later at the soonest, whichever isolate sees it. It only adds: the release before neither reads nor writes it.
+CREATE TABLE "capped_alerts" (
+	"service" text NOT NULL,
+	"kind" text NOT NULL,
+	"raised_at" timestamp with time zone NOT NULL,
+	CONSTRAINT "capped_alerts_pkey" PRIMARY KEY("service","kind")
+);
+--> statement-breakpoint
+-- The app moves a row's time on, and deletes none.
+GRANT SELECT, INSERT, UPDATE (raised_at) ON capped_alerts TO coffre_app;