@bugmole/cli 0.4.0 → 0.6.0

package/src/registry-worker/roles/routes.ts

@@ -0,0 +1,141 @@
+// Roles are who a test journey is run as: a guest, a signed-in member, an
+// admin. Bugmole suggests them (an agent through bugmole_role_propose or
+// `bugmole roles suggest`, from sign-in walls, role-gated routes and menus,
+// spec/roles.yaml and discovered journeys); a person confirms, renames or
+// rejects each one. Only confirmed roles are used for test cases and runs.
+//
+// - Anyone who can write to the project may suggest a role. A person who can
+//   manage the project may add one directly, and it is confirmed.
+// - Only a person who can manage the project decides — never an API key or
+//   a runner, or an agent could confirm its own suggestion.
+// - Suggesting a role a person already decided on changes nothing: a
+//   rejected role stays rejected however often it is proposed again.
+import type { AuthedRouteContext } from "../routes/index.js";
+import { matchPath, registerRoutes } from "../routes/index.js";
+import { memberOfProject, newId, requestJson, response, type Principal } from "../core.js";
+import { auditProject } from "../org/audit.js";
+import {
+  ROLE_DESCRIPTION_MAX, ROLE_EVIDENCE_MAX, normalizeRoleName, roleSourceOf, roleStatusOf,
+  type RoleSource, type RoleStatus,
+} from "../../registry/roles.js";
+
+type RoleRow = {
+  id: string; name: string; description: string; status: RoleStatus; source: RoleSource; evidence: string | null;
+  suggestedBy: string; decidedBy: string | null; decidedAt: string | null; createdAt: string; updatedAt: string;
+};
+
+const roleSelect = `
+  SELECT id, name, description, status, source, evidence, suggested_by AS suggestedBy,
+         decided_by AS decidedBy, decided_at AS decidedAt, created_at AS createdAt, updated_at AS updatedAt
+  FROM project_roles`;
+
+const isPerson = (principal: Principal) => !principal.apiKeyId && !principal.runner;
+const who = (principal: Principal) => principal.email || principal.aegisId;
+
+function text(value: unknown, max: number): string {
+  return typeof value === "string" ? value.trim().slice(0, max) : "";
+}
+
+async function listRoles({ env, principal, url }: AuthedRouteContext, projectId: string): Promise<Response> {
+  if (!(await memberOfProject(env, principal, projectId))) return response({ error: "Project scope is not allowed" }, 403);
+  const status = roleStatusOf(url.searchParams.get("status"));
+  const rows = await env.DB.prepare(`
+    ${roleSelect} WHERE project_id = ? AND (? IS NULL OR status = ?)
+    ORDER BY CASE status WHEN 'suggested' THEN 0 WHEN 'confirmed' THEN 1 ELSE 2 END, name
+  `).bind(projectId, status, status).all<RoleRow>();
+  return response({ roles: rows.results });
+}
+
+async function proposeRole({ env, principal, request }: AuthedRouteContext, projectId: string): Promise<Response> {
+  if (!(await memberOfProject(env, principal, projectId, "project.write"))) return response({ error: "Project scope is not allowed" }, 403);
+  const body = await requestJson(request);
+  const name = normalizeRoleName(body?.name);
+  if (!name) return response({ error: "name is required: letters, numbers and underscores, up to 60 characters" }, 422);
+  const description = text(body?.description, ROLE_DESCRIPTION_MAX);
+  const evidence = text(body?.evidence, ROLE_EVIDENCE_MAX) || null;
+  // A person with management rights adding a role is choosing it; anything
+  // else (an agent, the CLI, a member) is a suggestion for someone to decide.
+  const manager = isPerson(principal) && (await memberOfProject(env, principal, projectId, "project.manage"));
+  const requestedSource = roleSourceOf(body?.source);
+  const source: RoleSource = manager && (!requestedSource || requestedSource === "person") ? "person" : requestedSource && requestedSource !== "person" ? requestedSource : "agent";
+  const status: RoleStatus = source === "person" ? "confirmed" : "suggested";
+  if (source !== "person" && !evidence) return response({ error: "Say what points at this role in evidence (a sign-in wall, a gated route or menu, a spec entry)" }, 422);
+
+  const existing = await env.DB.prepare(`${roleSelect} WHERE project_id = ? AND name = ?`).bind(projectId, name).first<RoleRow>();
+  if (existing) {
+    // Suggesting again only refreshes a suggestion's evidence; a person's
+    // decision (confirmed or rejected) stands.
+    if (existing.status === "suggested" && status === "suggested") {
+      await env.DB.prepare("UPDATE project_roles SET evidence = ?, description = CASE WHEN description = '' THEN ? ELSE description END, updated_at = CURRENT_TIMESTAMP WHERE id = ?")
+        .bind(evidence, description, existing.id).run();
+    } else if (existing.status !== "confirmed" && status === "confirmed") {
+      await env.DB.prepare("UPDATE project_roles SET status = 'confirmed', decided_by = ?, decided_at = CURRENT_TIMESTAMP, updated_at = CURRENT_TIMESTAMP WHERE id = ?")
+        .bind(who(principal), existing.id).run();
+      await auditProject(env, principal, projectId, { action: "role.confirmed", targetType: "role", targetId: existing.id, data: { name } }, request);
+    }
+    const role = await env.DB.prepare(`${roleSelect} WHERE id = ?`).bind(existing.id).first<RoleRow>();
+    return response({ role, alreadyDecided: existing.status !== "suggested" && status === "suggested" }, 200);
+  }
+  if (!description) return response({ error: `description is required, up to ${ROLE_DESCRIPTION_MAX} characters` }, 422);
+  const id = newId("role");
+  await env.DB.prepare(`
+    INSERT INTO project_roles (id, project_id, name, description, status, source, evidence, suggested_by, decided_by, decided_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, CASE WHEN ? = 'confirmed' THEN CURRENT_TIMESTAMP ELSE NULL END)
+  `).bind(id, projectId, name, description, status, source, evidence, who(principal), status === "confirmed" ? who(principal) : null, status).run();
+  await auditProject(env, principal, projectId, { action: status === "confirmed" ? "role.created" : "role.suggested", targetType: "role", targetId: id, data: { name, source } }, request);
+  return response({ role: await env.DB.prepare(`${roleSelect} WHERE id = ?`).bind(id).first<RoleRow>() }, 201);
+}
+
+async function decideRole({ env, principal, request }: AuthedRouteContext, projectId: string, roleId: string): Promise<Response> {
+  if (!(await memberOfProject(env, principal, projectId))) return response({ error: "Project scope is not allowed" }, 403);
+  if (!isPerson(principal) || !(await memberOfProject(env, principal, projectId, "project.manage"))) {
+    return response({ error: "Only a person who manages the project can confirm, rename or reject roles" }, 403);
+  }
+  const role = await env.DB.prepare(`${roleSelect} WHERE id = ? AND project_id = ?`).bind(roleId, projectId).first<RoleRow>();
+  if (!role) return response({ error: "Not found" }, 404);
+  if (request.method === "DELETE") {
+    await env.DB.prepare("DELETE FROM project_roles WHERE id = ? AND project_id = ?").bind(roleId, projectId).run();
+    await auditProject(env, principal, projectId, { action: "role.deleted", targetType: "role", targetId: roleId, data: { name: role.name } }, request);
+    return response({ deleted: true });
+  }
+  const body = await requestJson(request);
+  const action = body?.action === "confirm" || body?.action === "reject" ? body.action : body?.action === undefined || body?.action === "edit" ? "edit" : null;
+  if (!action) return response({ error: "action must be confirm, reject or edit" }, 422);
+  let name = role.name;
+  if (body?.name !== undefined) {
+    const renamed = normalizeRoleName(body.name);
+    if (!renamed) return response({ error: "name must be letters, numbers and underscores, up to 60 characters" }, 422);
+    name = renamed;
+  }
+  const description = body?.description !== undefined ? text(body.description, ROLE_DESCRIPTION_MAX) : role.description;
+  if (!description) return response({ error: `description is required, up to ${ROLE_DESCRIPTION_MAX} characters` }, 422);
+  const status: RoleStatus = action === "confirm" ? "confirmed" : action === "reject" ? "rejected" : role.status;
+  const decided = action !== "edit";
+  try {
+    await env.DB.prepare(`
+      UPDATE project_roles SET name = ?, description = ?, status = ?,
+        decided_by = CASE WHEN ? THEN ? ELSE decided_by END,
+        decided_at = CASE WHEN ? THEN CURRENT_TIMESTAMP ELSE decided_at END,
+        updated_at = CURRENT_TIMESTAMP
+      WHERE id = ? AND project_id = ?
+    `).bind(name, description, status, decided ? 1 : 0, who(principal), decided ? 1 : 0, roleId, projectId).run();
+  } catch {
+    return response({ error: "A role with that name already exists" }, 409);
+  }
+  const auditAction = action === "confirm" ? "role.confirmed" : action === "reject" ? "role.rejected" : "role.updated";
+  await auditProject(env, principal, projectId, {
+    action: auditAction, targetType: "role", targetId: roleId,
+    data: { name, ...(name !== role.name ? { renamedFrom: role.name } : {}) },
+  }, request);
+  return response({ role: await env.DB.prepare(`${roleSelect} WHERE id = ?`).bind(roleId).first<RoleRow>() });
+}
+
+registerRoutes(async (context) => {
+  const { url, request } = context;
+  let params = matchPath(url.pathname, "/api/projects/:projectId/roles");
+  if (params && request.method === "GET") return listRoles(context, params.projectId);
+  if (params && request.method === "POST") return proposeRole(context, params.projectId);
+  params = matchPath(url.pathname, "/api/projects/:projectId/roles/:roleId");
+  if (params && (request.method === "PATCH" || request.method === "DELETE")) return decideRole(context, params.projectId, params.roleId);
+  return null;
+});

package/src/registry-worker/runner/dispatch.ts

@@ -115,6 +115,7 @@ async function queuedJobs(env: Env, nowIso: string): Promise<QueuedJob[]> {
     FROM ${JOB_TABLE[kind]}
     WHERE execution_mode = 'cloud' AND status = 'queued' AND workspace_id IS NOT NULL
       AND (next_dispatch_at IS NULL OR next_dispatch_at <= ?)
+      ${kind === "task" ? "AND approved_at IS NOT NULL" : ""}
     ORDER BY requested_at ASC LIMIT 500
   `).bind(nowIso).all<QueuedJob>();
   const [runs, tasks] = await Promise.all([select("run"), select("task")]);

package/src/registry-worker/runner/routes.ts

@@ -10,6 +10,10 @@ import { cloudRunMaxMinutes } from "./policy.js";
 import { cloudWorkerId } from "./jobs.js";
 import "./dispatch.js";
 import "./metering.js";
+import { approvalModeOf } from "../../registry/task-scheduling.js";
+import { signInFlowOf } from "../secrets/routes.js";
+import { getEntitlements } from "../billing/entitlements.js";
+import { entitlementsFor } from "../../billing/plan-catalog.js";
 
 /** A Worker request body is capped at 100 MB; stay under it. */
 export const MAX_UPLOAD_BYTES = 95 * 1024 * 1024;
@@ -38,7 +42,7 @@ async function bundle(env: Env, principal: Principal, runId: string): Promise<Re
     SELECT r.id, r.project_id AS projectId, r.workspace_id AS workspaceId, r.plan_id AS planId,
            r.journey_id AS journeyId, r.status, r.worker_id AS workerId, r.execution_mode AS executionMode,
            r.targets_json AS targetsJson, r.environment_base_url AS environmentBaseUrl, r.fix_from_json AS fixFromJson,
-           p.name AS projectName
+           r.case_scope_json AS caseScopeJson, p.name AS projectName
     FROM runs r JOIN projects p ON p.id = r.project_id
     WHERE r.id = ?
   `).bind(runId).first<Record<string, string | null>>();
@@ -57,6 +61,7 @@ async function bundle(env: Env, principal: Principal, runId: string): Promise<Re
       environmentBaseUrl: run.environmentBaseUrl,
       targets: parseJson(run.targetsJson),
       fixFrom: parseJson(run.fixFromJson),
+      caseScope: parseJson(run.caseScopeJson),
     },
     project: { id: run.projectId, name: run.projectName, workspaceId: run.workspaceId },
     workerId: run.workerId,
@@ -76,7 +81,13 @@ async function taskBundle(env: Env, principal: Principal, taskId: string): Promi
   if (task.status !== "running" || task.workerId !== cloudWorkerId({ kind: "task", id: taskId })) {
     return response({ error: "This task isn't assigned to a cloud runner", status: task.status }, 409);
   }
+  // Cloud exploration signs in with this first; its secrets come from /secrets.
+  const signInFlow = await signInFlowOf(env, String(task.projectId));
+  // How far exploration goes is part of the workspace's plan.
+  const { discovery } = task.workspaceId ? await getEntitlements(env, String(task.workspaceId)) : entitlementsFor("free");
   return response({
+    signInFlow: signInFlow?.content ?? null,
+    discovery,
     task: {
       id: task.id,
       projectId: task.projectId,
@@ -148,11 +159,17 @@ async function deletePrefix({ env, principal, url, request }: AuthedRouteContext
 async function updateSettings({ env, principal, request }: AuthedRouteContext, projectId: string): Promise<Response> {
   if (!(await memberOfProject(env, principal, projectId, "project.manage"))) return response({ error: "Project scope is not allowed" }, 403);
   const body = await requestJson(request);
+  // Either setting may be sent alone; each is checked only when present.
   const mode = body?.defaultExecutionMode;
-  if (mode !== "self" && mode !== "cloud") return response({ error: "defaultExecutionMode must be self or cloud" }, 422);
-  await env.DB.prepare("UPDATE projects SET default_execution_mode = ? WHERE id = ?").bind(mode, projectId).run();
-  await auditProject(env, principal, projectId, { action: "project.settings_updated", targetType: "project", targetId: projectId, data: { defaultExecutionMode: mode } }, request);
-  return response({ project: { id: projectId, defaultExecutionMode: mode } });
+  const approval = body?.taskApprovalMode;
+  if (mode === undefined && approval === undefined) return response({ error: "Send defaultExecutionMode or taskApprovalMode" }, 422);
+  if (mode !== undefined && mode !== "self" && mode !== "cloud") return response({ error: "defaultExecutionMode must be self or cloud" }, 422);
+  if (approval !== undefined && !approvalModeOf(approval)) return response({ error: "taskApprovalMode must be manual, auto or extreme" }, 422);
+  if (mode !== undefined) await env.DB.prepare("UPDATE projects SET default_execution_mode = ? WHERE id = ?").bind(mode, projectId).run();
+  if (approval !== undefined) await env.DB.prepare("UPDATE projects SET task_approval_mode = ? WHERE id = ?").bind(approval, projectId).run();
+  const changed = { ...(mode !== undefined ? { defaultExecutionMode: mode } : {}), ...(approval !== undefined ? { taskApprovalMode: approval } : {}) };
+  await auditProject(env, principal, projectId, { action: "project.settings_updated", targetType: "project", targetId: projectId, data: changed }, request);
+  return response({ project: { id: projectId, ...changed } });
 }
 
 registerRoutes(async (context) => {

package/src/registry-worker/runner/runner.test.ts

@@ -58,6 +58,9 @@ test("runner tokens name one run, can't be altered and expire", async () => {
   assert.equal(allowed("PUT", "/api/projects/shop/artifacts/object?key=projects/shop/plans/a.yaml"), false);
   assert.equal(allowed("PUT", "/api/projects/shop/artifacts/object?key=projects/shop/runs/run_1/video.webm"), true);
   assert.equal(allowed("PUT", "/api/projects/shop/artifacts/object?key=projects/shop/runs/run_10/video.webm"), false);
+  assert.equal(allowed("PUT", "/api/projects/shop/artifacts/object?key=projects/shop/journeys/graph.json"), true, "a passing run promotes the journey it proved");
+  assert.equal(allowed("PUT", "/api/projects/shop/artifacts/object?key=projects/shop/journeys/other.json"), false);
+  assert.equal(allowed("PUT", "/api/projects/other/artifacts/object?key=projects/other/journeys/graph.json"), false);
   assert.equal(allowed("GET", "/api/projects/other/artifacts"), false);
   assert.equal(allowed("GET", "/api/projects"), false);
   assert.equal(allowed("POST", "/api/tasks/run_1"), false);
@@ -148,6 +151,7 @@ test("discovery runs in the cloud too, publishes what it finds, and is billed",
     assert.equal(bundle.status, 200);
     assert.equal(bundle.json.task.description, "Explore https://shop.test");
     assert.equal(bundle.json.workerId, `cloud:task:${taskId}`);
+    assert.deepEqual(bundle.json.discovery, { maxPages: 12, maxDepth: 2 }, "exploration is bounded by the workspace's plan");
     assert.equal((await call(env, "GET", `/api/runner/runs/${taskId}/bundle`, { token })).status, 403);
 
     const flowKey = `projects/${projectId}/spec/flows/discovered/home.yaml`;
@@ -214,6 +218,61 @@ test("a discovered URL fills a project's empty default environment but never ove
   }
 });
 
+test("a discovered URL makes an existing environment the default instead of adding a second Production", async () => {
+  const launcher = fakeLauncher();
+  try {
+    const { env, db, projectId, owner } = await cloudProject();
+    db.db.prepare(`
+      INSERT INTO project_environments (id, project_id, app_id, name, base_url, status, is_default)
+      VALUES ('production', ?, 'default', 'Production', '', 'active', 0)
+    `).run(projectId);
+    const created = await call(env, "POST", `/api/projects/${projectId}/tasks`, {
+      as: owner,
+      body: { title: "Explore https://shop.test", description: "Explore https://shop.test", taskType: "discovery", idempotencyKey: "d1", executionMode: "cloud" },
+    });
+    const taskId = created.json.task.id;
+    const { token } = launcher.launches[0];
+    await call(env, "POST", `/api/tasks/${taskId}`, { token, body: { workerId: `cloud:task:${taskId}`, status: "completed", completionSummary: "Explored 1 page" } });
+    const environments = db.db.prepare("SELECT id, base_url AS baseUrl, is_default AS isDefault FROM project_environments WHERE project_id = ?").all(projectId).map((row: any) => ({ ...row }));
+    assert.deepEqual(environments, [{ id: "production", baseUrl: "https://shop.test", isDefault: 1 }]);
+  } finally {
+    launcher.restore();
+  }
+});
+
+test("an app can't have two environments with the same name", async () => {
+  const { env, projectId, owner } = await cloudProject();
+  const create = (id: string, name: string) => call(env, "POST", `/api/projects/${projectId}/environments`, {
+    as: owner,
+    body: { id, name, baseUrl: "https://shop.test" },
+  });
+  assert.equal((await create("production", "Production")).status, 201);
+  const twin = await create("prod-2", " production ");
+  assert.equal(twin.status, 409);
+  assert.match(twin.json.error, /already has an environment named "production" \(production\)/);
+  assert.equal((await create("staging", "Staging")).status, 201);
+});
+
+test("a cloud exploration waiting for approval starts a runner only once it's approved", async () => {
+  const launcher = fakeLauncher();
+  try {
+    const { env, projectId, owner } = await cloudProject();
+    assert.equal((await call(env, "PATCH", `/api/projects/${projectId}/settings`, { as: owner, body: { taskApprovalMode: "manual" } })).status, 200);
+    const created = await call(env, "POST", `/api/projects/${projectId}/tasks`, {
+      as: owner,
+      body: { title: "Explore https://shop.test", description: "Explore https://shop.test", taskType: "discovery", idempotencyKey: "d1", executionMode: "cloud" },
+    });
+    assert.equal(created.status, 201, JSON.stringify(created.json));
+    assert.equal(created.json.task.approvedAt, null);
+    await runScheduled(env, "* * * * *");
+    assert.equal(launcher.launches.length, 0, "neither queuing nor the dispatcher starts it");
+    assert.equal((await call(env, "POST", `/api/tasks/${created.json.task.id}/approve`, { as: owner })).status, 200);
+    assert.equal(launcher.launches.length, 1, "approving hands it to a runner");
+  } finally {
+    launcher.restore();
+  }
+});
+
 test("runs and discovery share the workspace's parallel slots", async () => {
   const launcher = fakeLauncher();
   try {

package/src/registry-worker/runner/tokens.ts

@@ -72,19 +72,30 @@ export function runnerMayCall(identity: RunnerIdentity, method: string, url: URL
   const key = url.searchParams.get(path.endsWith("/object") ? "key" : "prefix") ?? "";
   if (identity.kind === "run") {
     if (path === `/api/runner/runs/${id}/bundle`) return method === "GET";
+    // The project's sign-in secrets, for this run only (secrets/routes.ts).
+    if (path === `/api/runner/runs/${id}/secrets`) return method === "GET";
+    // A token its project's own cloud trusts, to read the project's vault (identity/oidc.ts).
+    if (path === `/api/runner/runs/${id}/identity-token`) return method === "GET";
     if (path === `/api/runs/${id}`) return method === "GET" || method === "POST";
     if (path === `/api/runs/${id}/device-access`) return method === "GET";
     if (path === `/api/runs/${id}/device-sessions`) return method === "POST";
     if (path.startsWith(`/api/runs/${id}/device-sessions/`)) return method === "GET" || method === "POST";
     if (artifacts) {
       if (method === "GET") return true;
-      return (method === "PUT" || method === "DELETE") && key.startsWith(`projects/${project}/runs/${id}/`);
+      if ((method === "PUT" || method === "DELETE") && key.startsWith(`projects/${project}/runs/${id}/`)) return true;
+      // A passing run promotes the draft journey it proved (run-job.ts), so
+      // it may rewrite the graph, and only the graph, of its own project.
+      return method === "PUT" && key === `projects/${project}/journeys/graph.json`;
     }
     return false;
   }
   if (path === `/api/runner/tasks/${id}/bundle`) return method === "GET";
+  if (path === `/api/runner/tasks/${id}/secrets`) return method === "GET";
+  if (path === `/api/runner/tasks/${id}/identity-token`) return method === "GET";
   if (path === `/api/tasks/${id}`) return method === "POST";
   if (path === `/api/projects/${project}/plans`) return method === "POST";
+  // An exploration that meets a sign-in wall suggests roles; a person confirms them.
+  if (path === `/api/projects/${project}/roles`) return method === "POST";
   if (artifacts) {
     if (method === "GET") return true;
     return method === "PUT" && ["spec", "plans", "journeys"].some((folder) => key.startsWith(`projects/${project}/${folder}/`));

package/src/registry-worker/secrets/crypto.ts

@@ -0,0 +1,135 @@
+// Encryption for project secrets (sign-in passwords a cloud run types).
+//
+// One registry secret, PROJECT_SECRETS_KEY (32 random bytes, base64), is the
+// root. Each project gets its own AES-256-GCM key from it with HKDF-SHA256
+// (info "bugmole:project-secret:<projectId>"), and every value is sealed with
+// additional data "<projectId>|<environmentId>|<name>", so a ciphertext copied
+// to another project, environment or name fails to decrypt instead of being
+// typed somewhere it was never meant to go.
+//
+// Rotation: set the new key as PROJECT_SECRETS_KEY with a higher
+// PROJECT_SECRETS_KEY_VERSION, and keep the old one as
+// PROJECT_SECRETS_KEY_PREVIOUS (+ _PREVIOUS_VERSION) until no row still has
+// the old key_version. Rows are re-sealed with the current key when they are
+// next read or replaced.
+import { base64, fromBase64 } from "../core.js";
+
+export type SecretKeyEnv = {
+  PROJECT_SECRETS_KEY?: string;
+  PROJECT_SECRETS_KEY_VERSION?: string;
+  PROJECT_SECRETS_KEY_PREVIOUS?: string;
+  PROJECT_SECRETS_KEY_PREVIOUS_VERSION?: string;
+};
+
+export type SealedSecret = { ciphertext: string; iv: string; keyVersion: number };
+export type SecretScope = { projectId: string; environmentId: string | null; name: string };
+
+export const PROJECT_SECRETS_UNCONFIGURED =
+  "Project secrets are turned off: this registry has no PROJECT_SECRETS_KEY. Nothing was stored.";
+
+const encoder = new TextEncoder();
+
+function decodeKey(value: string): Uint8Array | null {
+  try {
+    const bytes = fromBase64(value.trim());
+    return bytes.length === 32 ? bytes : null;
+  } catch {
+    return null;
+  }
+}
+
+function versionOf(value: string | undefined, fallback: number): number {
+  const parsed = Number(value);
+  return Number.isInteger(parsed) && parsed > 0 ? parsed : fallback;
+}
+
+type RootKey = { version: number; bytes: Uint8Array };
+
+/** The keys this registry can use: the current one first. Empty when the feature is off. */
+export function rootKeys(env: SecretKeyEnv): RootKey[] {
+  const current = env.PROJECT_SECRETS_KEY ? decodeKey(env.PROJECT_SECRETS_KEY) : null;
+  if (!current) return [];
+  const version = versionOf(env.PROJECT_SECRETS_KEY_VERSION, 1);
+  const keys: RootKey[] = [{ version, bytes: current }];
+  const previous = env.PROJECT_SECRETS_KEY_PREVIOUS ? decodeKey(env.PROJECT_SECRETS_KEY_PREVIOUS) : null;
+  const previousVersion = versionOf(env.PROJECT_SECRETS_KEY_PREVIOUS_VERSION, version - 1);
+  if (previous && previousVersion !== version) keys.push({ version: previousVersion, bytes: previous });
+  return keys;
+}
+
+/** Whether project secrets can be stored and read on this registry. */
+export function secretsConfigured(env: SecretKeyEnv): boolean {
+  return rootKeys(env).length > 0;
+}
+
+async function derivedKey(root: Uint8Array, info: string, usage: "encrypt" | "decrypt"): Promise<CryptoKey> {
+  const material = await crypto.subtle.importKey("raw", root, "HKDF", false, ["deriveKey"]);
+  return crypto.subtle.deriveKey(
+    { name: "HKDF", hash: "SHA-256", salt: new Uint8Array(0), info: encoder.encode(info) },
+    material,
+    { name: "AES-GCM", length: 256 },
+    false,
+    [usage],
+  );
+}
+
+/**
+ * Where a sealed value belongs: `info` picks the derived key (one per project
+ * and purpose), `aad` binds the ciphertext to the exact row and field it was
+ * written for. Other features (the Jira integration) seal their credentials
+ * under the same root key with their own `info`, so a project secret and a
+ * Jira token never share a key.
+ */
+export type SealContext = { info: string; aad: string };
+
+/** The additional data that binds a value to where it belongs. */
+export function secretAad(scope: SecretScope): Uint8Array {
+  return encoder.encode(`${scope.projectId}|${scope.environmentId ?? ""}|${scope.name}`);
+}
+
+function projectSecretContext(scope: SecretScope): SealContext {
+  return { info: `bugmole:project-secret:${scope.projectId}`, aad: new TextDecoder().decode(secretAad(scope)) };
+}
+
+/** Seals a value with the current key under `context`. Throws when the feature is off. */
+export async function sealInContext(env: SecretKeyEnv, context: SealContext, value: string): Promise<SealedSecret> {
+  const [current] = rootKeys(env);
+  if (!current) throw new Error(PROJECT_SECRETS_UNCONFIGURED);
+  const iv = crypto.getRandomValues(new Uint8Array(12));
+  const sealed = await crypto.subtle.encrypt(
+    { name: "AES-GCM", iv, additionalData: encoder.encode(context.aad) },
+    await derivedKey(current.bytes, context.info, "encrypt"),
+    encoder.encode(value),
+  );
+  return { ciphertext: base64(new Uint8Array(sealed)), iv: base64(iv), keyVersion: current.version };
+}
+
+/** Opens a value sealed under `context`. Throws on an unknown key version or any mismatch. */
+export async function openInContext(env: SecretKeyEnv, context: SealContext, sealed: SealedSecret): Promise<string> {
+  const root = rootKeys(env).find((key) => key.version === sealed.keyVersion);
+  if (!root) throw new Error(`No PROJECT_SECRETS_KEY for key version ${sealed.keyVersion}`);
+  const opened = await crypto.subtle.decrypt(
+    { name: "AES-GCM", iv: fromBase64(sealed.iv), additionalData: encoder.encode(context.aad) },
+    await derivedKey(root.bytes, context.info, "decrypt"),
+    fromBase64(sealed.ciphertext),
+  );
+  return new TextDecoder().decode(opened);
+}
+
+/** Seals a value with the current key. Throws when the feature is off. */
+export async function sealSecret(env: SecretKeyEnv, scope: SecretScope, value: string): Promise<SealedSecret> {
+  return sealInContext(env, projectSecretContext(scope), value);
+}
+
+/**
+ * Opens a sealed value. Throws when the key version is unknown, or when the
+ * ciphertext, project, environment or name don't match what was sealed.
+ */
+export async function openSecret(env: SecretKeyEnv, scope: SecretScope, sealed: SealedSecret): Promise<string> {
+  return openInContext(env, projectSecretContext(scope), sealed);
+}
+
+/** The key version new values are sealed with, or null when the feature is off. */
+export function currentKeyVersion(env: SecretKeyEnv): number | null {
+  return rootKeys(env)[0]?.version ?? null;
+}