@bugmole/cli 0.4.0

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

@@ -0,0 +1,60 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { call, createTestEnv, runScheduled, seedPlan, seedProject } from "./testing/harness.js";
+
+test("a queued run is claimed once and finishes with its target results", async () => {
+  const { env, coordinator } = createTestEnv();
+  const { owner, projectId } = await seedProject(env);
+  await seedPlan(env, projectId, owner);
+
+  const created = await call(env, "POST", `/api/projects/${projectId}/runs`, {
+    as: owner,
+    body: { planId: "checkout", idempotencyKey: "k1", targets: [{ browser: "chromium" }] },
+  });
+  assert.equal(created.status, 201);
+  const runId = created.json.run.id;
+  assert.deepEqual(coordinator.broadcasts.map((b) => (b.event as { type: string }).type), ["job_queued"]);
+
+  const again = await call(env, "POST", `/api/projects/${projectId}/runs`, {
+    as: owner,
+    body: { planId: "checkout", idempotencyKey: "k1" },
+  });
+  assert.equal(again.status, 200);
+  assert.equal(again.json.run.id, runId);
+
+  const claim = await call(env, "POST", `/api/runs/${runId}/claim`, { as: owner, body: { workerId: "w1" } });
+  assert.equal(claim.status, 200);
+  const second = await call(env, "POST", `/api/runs/${runId}/claim`, { as: owner, body: { workerId: "w2" } });
+  assert.equal(second.status, 409);
+
+  const done = await call(env, "POST", `/api/runs/${runId}`, {
+    as: owner,
+    body: { workerId: "w1", status: "success", stepsPassed: 3, stepsFailed: 0, targetResults: [{ targetId: "chromium", status: "passed" }] },
+  });
+  assert.equal(done.status, 200);
+  const fetched = await call(env, "GET", `/api/runs/${runId}`, { as: owner });
+  assert.equal(fetched.json.run.status, "success");
+  assert.equal(fetched.json.run.targetResults[0].status, "passed");
+
+  const reopened = await call(env, "POST", `/api/runs/${runId}`, { as: owner, body: { workerId: "w1", status: "running" } });
+  assert.equal(reopened.status, 409);
+});
+
+test("someone outside the project cannot see or create its runs", async () => {
+  const { env } = createTestEnv();
+  const { owner, projectId } = await seedProject(env);
+  await seedPlan(env, projectId, owner);
+  const denied = await call(env, "POST", `/api/projects/${projectId}/runs`, {
+    as: "user_stranger",
+    body: { planId: "checkout", idempotencyKey: "k1" },
+  });
+  assert.equal(denied.status, 403);
+  const unauthenticated = await call(env, "GET", `/api/projects/${projectId}/runs`);
+  assert.equal(unauthenticated.status, 401);
+});
+
+test("scheduled ticks run without registered jobs", async () => {
+  const { env } = createTestEnv();
+  await runScheduled(env, "* * * * *");
+  await runScheduled(env, "17 3 * * *");
+});

package/src/registry-worker/signup/policy.ts

@@ -0,0 +1,57 @@
+// Keeps the Free plan a trial of the product rather than a source of free
+// compute: one Free workspace per person, and cloud minutes only for people
+// whose email Aegis confirmed.
+import type { Env, Principal } from "../core.js";
+import { response } from "../core.js";
+import { entitlementMode } from "../billing/enforcement.js";
+import { getWorkspacePlan } from "../billing/entitlements.js";
+import { flagMode } from "../flags.js";
+
+/** The Free workspaces this person owns (their own, or any under the same verified email). */
+export async function ownedFreeWorkspaces(env: Env, principal: Pick<Principal, "aegisId" | "email">): Promise<string[]> {
+  const rows = await env.DB.prepare(`
+    SELECT DISTINCT wm.workspace_id AS workspaceId
+    FROM workspace_memberships wm
+    LEFT JOIN aegis_users u ON u.id = wm.aegis_id
+    LEFT JOIN workspace_plans wp ON wp.workspace_id = wm.workspace_id
+    WHERE wm.role = 'owner' AND wm.status = 'active'
+      AND (wm.aegis_id = ? OR (? IS NOT NULL AND u.email = ? AND u.email_verified = 1))
+      AND (wp.plan IS NULL OR wp.plan = 'free')
+  `).bind(principal.aegisId, principal.email ?? null, principal.email ?? null).all<{ workspaceId: string }>();
+  return rows.results.map((row) => row.workspaceId);
+}
+
+/** Refuses a second Free workspace once plan limits are enforced for everyone. */
+export async function freeWorkspaceLimit(env: Env, principal: Principal): Promise<Response | null> {
+  if (flagMode(env, "entitlements") !== "on") return null;
+  const owned = await ownedFreeWorkspaces(env, principal);
+  if (!owned.length) return null;
+  return response({
+    error: "You already have a Free workspace. Upgrade it, or ask a teammate to invite you to theirs.",
+    code: "free_workspace_exists",
+    workspaceId: owned[0],
+    upgradeUrl: "/billing",
+  }, 402);
+}
+
+async function emailVerified(env: Env, aegisId: string): Promise<boolean> {
+  const row = await env.DB.prepare("SELECT email_verified AS verified FROM aegis_users WHERE id = ?")
+    .bind(aegisId).first<{ verified: number }>();
+  return row?.verified === 1;
+}
+
+/**
+ * Free cloud minutes need a confirmed email. The check follows the person
+ * behind the request: the signed-in user, or whoever created the API key.
+ */
+export async function cloudAccountError(env: Env, principal: Principal, workspaceId: string): Promise<Response | null> {
+  if (principal.runner) return null;
+  if ((await entitlementMode(env, workspaceId)) !== "enforce") return null;
+  const plan = await getWorkspacePlan(env, workspaceId);
+  if (plan.plan !== "free") return null;
+  if (principal.emailVerified || (await emailVerified(env, principal.aegisId))) return null;
+  return response({
+    error: "Confirm your email to use Bugmole Cloud on the Free plan: sign out, then sign in with the emailed link.",
+    code: "email_unverified",
+  }, 403);
+}

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

@@ -0,0 +1,106 @@
+// First-run setup for someone who signed up on the website: a Free
+// workspace, a project on Bugmole storage that runs in the cloud, and the
+// site to test, in one step.
+import type { Env, Principal } from "../core.js";
+import { newId, response, requestJson } from "../core.js";
+import { recordAudit, actorOf } from "../org/audit.js";
+import { matchPath, registerRoutes } from "../routes/index.js";
+import { ownedFreeWorkspaces } from "./policy.js";
+
+const MAX_NAME = 80;
+
+export function slugify(value: string, fallback: string): string {
+  const slug = value.toLowerCase().normalize("NFKD").replace(/[\u0300-\u036f]/g, "").replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 32);
+  return slug || fallback;
+}
+
+function suffix(): string {
+  return newId("x").slice(-6).toLowerCase().replace(/[^a-z0-9]/g, "0");
+}
+
+export function normalizeSiteUrl(value: unknown): string | null | undefined {
+  if (value === undefined || value === null || value === "") return undefined;
+  if (typeof value !== "string") return null;
+  try {
+    const url = new URL(value.trim());
+    if (url.protocol !== "https:" && url.protocol !== "http:") return null;
+    if (url.username || url.password) return null;
+    return url.toString();
+  } catch {
+    return null;
+  }
+}
+
+async function onboard(env: Env, principal: Principal, request: Request): Promise<Response> {
+  // Only a person signed in on the dashboard, never an API key or runner.
+  if (principal.apiKeyId || principal.runner || !principal.scopes.includes("*")) {
+    return response({ error: "Sign in on the dashboard to set up a workspace" }, 403);
+  }
+  if (!principal.email || !principal.emailVerified) {
+    return response({ error: "Confirm your email first: sign in with the link Aegis emails you.", code: "email_unverified" }, 403);
+  }
+  const body = await requestJson(request);
+  const workspaceName = typeof body?.workspaceName === "string" ? body.workspaceName.trim().slice(0, MAX_NAME) : "";
+  const projectName = typeof body?.projectName === "string" ? body.projectName.trim().slice(0, MAX_NAME) : "";
+  const siteUrl = normalizeSiteUrl(body?.siteUrl);
+  if (!workspaceName || !projectName) return response({ error: "workspaceName and projectName are required" }, 422);
+  if (siteUrl === null) return response({ error: "siteUrl must be an http(s) address" }, 422);
+
+  const owned = await ownedFreeWorkspaces(env, principal);
+  if (owned.length) {
+    return response({ error: "You already have a Free workspace.", code: "free_workspace_exists", workspaceId: owned[0] }, 409);
+  }
+
+  const workspaceId = `${slugify(workspaceName, "workspace")}-${suffix()}`;
+  const projectId = `${slugify(projectName, "project")}-${suffix()}`;
+  const environment = siteUrl ? { id: "production", name: "Production", baseUrl: siteUrl } : null;
+  const statements = [
+    env.DB.prepare(`
+      INSERT INTO aegis_users (id, email, email_verified) VALUES (?, ?, 1)
+      ON CONFLICT(id) DO UPDATE SET email = excluded.email, email_verified = 1
+    `).bind(principal.aegisId, principal.email),
+    env.DB.prepare("INSERT INTO workspaces (id, name, created_by) VALUES (?, ?, ?)").bind(workspaceId, workspaceName, principal.aegisId),
+    env.DB.prepare("INSERT INTO workspace_memberships (workspace_id, aegis_id, role, status) VALUES (?, ?, 'owner', 'active')")
+      .bind(workspaceId, principal.aegisId),
+    env.DB.prepare(`
+      INSERT INTO projects (id, workspace_id, tenant_id, name, environment, storage_provider, storage_mode, default_execution_mode, created_at)
+      VALUES (?, ?, ?, ?, ?, 'bugmole', 'managed', 'cloud', CURRENT_TIMESTAMP)
+    `).bind(projectId, workspaceId, workspaceId, projectName, environment?.id ?? "production"),
+    env.DB.prepare("INSERT INTO project_apps (id, project_id, name, type, is_default) VALUES ('default', ?, ?, 'web', 1)")
+      .bind(projectId, projectName),
+  ];
+  if (environment) {
+    statements.push(env.DB.prepare(`
+      INSERT INTO project_environments (id, project_id, app_id, name, base_url, is_default)
+      VALUES (?, ?, 'default', ?, ?, 1)
+    `).bind(environment.id, projectId, environment.name, environment.baseUrl));
+  }
+  await env.DB.batch(statements);
+  const actor = actorOf(principal);
+  await recordAudit(env, actor, { workspaceId, action: "workspace.created", targetType: "workspace", targetId: workspaceId, data: { via: "signup" } }, request);
+  await recordAudit(env, actor, { workspaceId, projectId, action: "project.created", targetType: "project", targetId: projectId }, request);
+  return response({
+    workspace: { id: workspaceId, name: workspaceName, plan: "free" },
+    project: { id: projectId, name: projectName, workspaceId, storageMode: "managed", defaultExecutionMode: "cloud" },
+    environment,
+  }, 201);
+}
+
+async function status(env: Env, principal: Principal): Promise<Response> {
+  const workspaces = await env.DB.prepare(`
+    SELECT workspace_id AS workspaceId, role FROM workspace_memberships
+    WHERE aegis_id = ? AND status = 'active'
+  `).bind(principal.aegisId).all<{ workspaceId: string; role: string }>();
+  return response({
+    emailVerified: principal.emailVerified === true,
+    workspaces: workspaces.results,
+    freeWorkspaces: await ownedFreeWorkspaces(env, principal),
+  });
+}
+
+registerRoutes(async ({ request, env, principal, url }) => {
+  if (!matchPath(url.pathname, "/api/onboarding")) return null;
+  if (request.method === "POST") return onboard(env, principal, request);
+  if (request.method === "GET") return status(env, principal);
+  return null;
+});

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

@@ -0,0 +1,81 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { call, createTestEnv, seedPlan, seedProject } from "../testing/harness.js";
+import { normalizeSiteUrl, slugify } from "./routes.js";
+
+const verified = { "x-aegis-email": "ada@shop.test", "x-aegis-email-verified": "true" };
+
+test("site addresses and names are cleaned up for new workspaces", () => {
+  assert.equal(slugify("Ada's Shöp & Co.", "w"), "ada-s-shop-co");
+  assert.equal(slugify("!!!", "workspace"), "workspace");
+  assert.equal(normalizeSiteUrl("https://shop.test/app"), "https://shop.test/app");
+  assert.equal(normalizeSiteUrl(""), undefined);
+  assert.equal(normalizeSiteUrl("javascript:alert(1)"), null);
+  assert.equal(normalizeSiteUrl("https://user:pass@shop.test"), null);
+  assert.equal(normalizeSiteUrl(42), null);
+});
+
+test("sign-up creates one Free workspace with a cloud-ready project", async () => {
+  const { env } = createTestEnv();
+  const body = { workspaceName: "Ada's Shop", projectName: "Storefront", siteUrl: "https://shop.test" };
+  const unverified = await call(env, "POST", "/api/onboarding", { as: "user_ada", body, headers: { "x-aegis-email": "ada@shop.test" } });
+  assert.equal(unverified.status, 403);
+  assert.equal(unverified.json.code, "email_unverified");
+
+  const created = await call(env, "POST", "/api/onboarding", { as: "user_ada", body, headers: verified });
+  assert.equal(created.status, 201, JSON.stringify(created.json));
+  const { workspace, project } = created.json;
+  assert.match(workspace.id, /^ada-s-shop-[a-z0-9]{6}$/);
+  assert.equal(workspace.plan, "free");
+
+  const listed = await call(env, "GET", "/api/projects", { as: "user_ada" });
+  const saved = listed.json.projects[0];
+  assert.equal(saved.id, project.id);
+  assert.equal(saved.storageMode, "managed");
+  assert.equal(saved.defaultExecutionMode, "cloud");
+  assert.deepEqual(saved.environments.map((item: { baseUrl: string; isDefault: boolean }) => [item.baseUrl, item.isDefault]), [["https://shop.test/", true]]);
+
+  const again = await call(env, "POST", "/api/onboarding", { as: "user_ada", body, headers: verified });
+  assert.equal(again.status, 409);
+  assert.equal(again.json.workspaceId, workspace.id);
+  // The same verified email under a second Aegis account doesn't get another one.
+  const twin = await call(env, "POST", "/api/onboarding", { as: "user_ada_2", body, headers: verified });
+  assert.equal(twin.status, 409);
+
+  const state = await call(env, "GET", "/api/onboarding", { as: "user_ada", headers: verified });
+  assert.deepEqual(state.json.freeWorkspaces, [workspace.id]);
+  assert.equal(state.json.emailVerified, true);
+});
+
+test("API keys can't run sign-up", async () => {
+  const { env } = createTestEnv();
+  const { owner, projectId } = await seedProject(env);
+  const key = await call(env, "POST", "/api/api-keys", { as: owner, body: { name: "ci", projectIds: [projectId] } });
+  const attempt = await call(env, "POST", "/api/onboarding", { token: key.json.token, body: { workspaceName: "x", projectName: "y" } });
+  assert.equal(attempt.status, 403);
+});
+
+test("with limits on, a person keeps one Free workspace and needs a confirmed email for cloud minutes", async () => {
+  const { env } = createTestEnv({ FEATURE_ENTITLEMENTS: "on", FEATURE_CLOUD_RUNNERS: "on" });
+  const { owner, projectId } = await seedProject(env, { storageProvider: "bugmole" });
+  await seedPlan(env, projectId, owner);
+  const second = await call(env, "POST", "/api/workspaces", { as: owner, body: { id: "side", name: "Side project" } });
+  assert.equal(second.status, 402);
+  assert.equal(second.json.code, "free_workspace_exists");
+
+  const cloud = (key: string, headers: Record<string, string>) => call(env, "POST", `/api/projects/${projectId}/runs`, {
+    as: owner, headers, body: { planId: "checkout", idempotencyKey: key, executionMode: "cloud" },
+  });
+  const blocked = await cloud("u1", { "x-aegis-email": "owner@acme.test", "x-aegis-email-verified": "false" });
+  assert.equal(blocked.status, 403);
+  assert.equal(blocked.json.code, "email_unverified");
+  const allowed = await cloud("v1", { "x-aegis-email": "owner@acme.test", "x-aegis-email-verified": "true" });
+  assert.equal(allowed.status, 201);
+
+  // A key the confirmed person created works from CI too.
+  const key = await call(env, "POST", "/api/api-keys", { as: owner, body: { name: "ci", projectIds: [projectId] } });
+  const fromCi = await call(env, "POST", `/api/projects/${projectId}/runs`, {
+    token: key.json.token, body: { planId: "checkout", idempotencyKey: "k1", executionMode: "cloud" },
+  });
+  assert.equal(fromCi.status, 201);
+});

package/src/registry-worker/sso/aegis.ts

@@ -0,0 +1,141 @@
+// Client for Aegis's organization API (SSO connections, domains, SCIM tokens),
+// using Bugmole's own client-credentials token with organizations:manage.
+
+export type AegisOrgEnv = {
+  /** Aegis issuer; the token endpoint is `${AEGIS_ISSUER}/token`. */
+  AEGIS_ISSUER?: string;
+  /** Where Aegis serves /organizations (defaults to the issuer). */
+  AEGIS_MANAGEMENT_URL?: string;
+  /** Client with client_credentials + organizations:manage; defaults to the Bugmole client (AEGIS_CLIENT_ID). */
+  AEGIS_ORG_CLIENT_ID?: string;
+  AEGIS_ORG_CLIENT_SECRET?: string;
+  AEGIS_CLIENT_ID?: string;
+  AEGIS_CLIENT_SECRET?: string;
+  /** Shared with Aegis's ORG_EVENTS_SECRET; signs deprovisioning events. */
+  AEGIS_EVENTS_SECRET?: string;
+  /** Test seam. */
+  AEGIS_FETCH?: typeof fetch;
+};
+
+export class AegisError extends Error {
+  constructor(readonly status: number, readonly body: Record<string, unknown>) {
+    super(typeof body.message === "string" ? body.message : typeof body.error === "string" ? body.error : `Aegis returned ${status}`);
+  }
+}
+
+const DEFAULT_ISSUER = "https://id.theaiinc.com";
+const trim = (value: string) => value.replace(/\/+$/, "");
+
+function orgClient(env: AegisOrgEnv): { id: string; secret: string } | null {
+  const id = env.AEGIS_ORG_CLIENT_ID || env.AEGIS_CLIENT_ID;
+  const secret = env.AEGIS_ORG_CLIENT_ID ? env.AEGIS_ORG_CLIENT_SECRET : env.AEGIS_CLIENT_SECRET;
+  return id && secret ? { id, secret } : null;
+}
+
+export function aegisOrgConfigured(env: AegisOrgEnv): boolean {
+  return Boolean(orgClient(env) && env.AEGIS_EVENTS_SECRET);
+}
+
+let cachedToken: { key: string; token: string; expiresAt: number } | null = null;
+
+/** Test seam: forget the cached token. */
+export function resetAegisTokenCache(): void {
+  cachedToken = null;
+}
+
+async function accessToken(env: AegisOrgEnv): Promise<string> {
+  const issuer = trim(env.AEGIS_ISSUER || DEFAULT_ISSUER);
+  const client = orgClient(env);
+  if (!client) throw new AegisError(503, { error: "sso_unavailable" });
+  const key = `${issuer}|${client.id}`;
+  if (cachedToken && cachedToken.key === key && cachedToken.expiresAt > Date.now() + 30_000) return cachedToken.token;
+  const basic = btoa(`${encodeURIComponent(client.id)}:${encodeURIComponent(client.secret)}`);
+  const res = await (env.AEGIS_FETCH ?? fetch)(`${issuer}/token`, {
+    method: "POST",
+    headers: { "content-type": "application/x-www-form-urlencoded", authorization: `Basic ${basic}` },
+    body: new URLSearchParams({ grant_type: "client_credentials", scope: "organizations:manage" }),
+  });
+  const body = await res.json().catch(() => ({})) as { access_token?: string; expires_in?: number };
+  if (!res.ok || !body.access_token) throw new AegisError(res.status || 502, { error: "aegis_token_failed" });
+  cachedToken = { key, token: body.access_token, expiresAt: Date.now() + (body.expires_in ?? 300) * 1000 };
+  return body.access_token;
+}
+
+export async function aegisOrgRequest<T = Record<string, unknown>>(
+  env: AegisOrgEnv,
+  method: string,
+  path: string,
+  body?: unknown,
+): Promise<T> {
+  if (!aegisOrgConfigured(env)) throw new AegisError(503, { error: "sso_unavailable", message: "Single sign-on isn't available yet." });
+  const base = trim(env.AEGIS_MANAGEMENT_URL || env.AEGIS_ISSUER || DEFAULT_ISSUER);
+  const send = async (token: string) => (env.AEGIS_FETCH ?? fetch)(`${base}${path}`, {
+    method,
+    headers: {
+      authorization: `Bearer ${token}`,
+      ...(body === undefined ? {} : { "content-type": "application/json" }),
+    },
+    body: body === undefined ? undefined : JSON.stringify(body),
+  });
+  let res = await send(await accessToken(env));
+  if (res.status === 401) {
+    // The cached token may have been revoked or rotated; try once with a fresh one.
+    cachedToken = null;
+    res = await send(await accessToken(env));
+  }
+  if (res.status === 204) return undefined as T;
+  const text = await res.text();
+  let parsed: Record<string, unknown> = {};
+  try {
+    parsed = text ? JSON.parse(text) as Record<string, unknown> : {};
+  } catch {
+    parsed = { error: "aegis_unreadable_response" };
+  }
+  if (!res.ok) throw new AegisError(res.status, parsed);
+  return parsed as T;
+}
+
+export type AegisOrganization = {
+  id: string;
+  name: string;
+  externalRef: string | null;
+  entitlements: { sso: boolean; scim: boolean };
+  ssoRequired: boolean;
+};
+
+export type AegisOrganizationDetail = AegisOrganization & {
+  domains: Array<{ id: string; domain: string; status: string; txtRecord: { name: string; value: string } }>;
+  connections: Array<Record<string, unknown> & { id: string; protocol: string; enabled: boolean }>;
+  scimTokens: Array<{ id: string; name: string; prefix: string; lastUsedAt: string | null }>;
+  scimBaseUrl: string;
+  memberCount: number;
+  groupCount: number;
+};
+
+export function ensureOrganization(
+  env: AegisOrgEnv,
+  input: { name: string; externalRef: string; eventsUrl: string | null },
+): Promise<AegisOrganization> {
+  return aegisOrgRequest<AegisOrganization>(env, "POST", "/organizations", input);
+}
+
+export function setOrganizationEntitlements(env: AegisOrgEnv, orgId: string, entitlements: { sso: boolean; scim: boolean }) {
+  return aegisOrgRequest<AegisOrganization>(env, "PUT", `/organizations/${encodeURIComponent(orgId)}/entitlements`, entitlements);
+}
+
+export function getOrganization(env: AegisOrgEnv, orgId: string) {
+  return aegisOrgRequest<AegisOrganizationDetail>(env, "GET", `/organizations/${encodeURIComponent(orgId)}`);
+}
+
+export async function verifyAegisEvent(secret: string, header: string | null, body: string, now = Date.now()): Promise<boolean> {
+  const match = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(header ?? "");
+  if (!match) return false;
+  const timestamp = Number(match[1]);
+  if (Math.abs(now / 1000 - timestamp) > 300) return false;
+  const key = await crypto.subtle.importKey("raw", new TextEncoder().encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+  const mac = new Uint8Array(await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(`${timestamp}.${body}`)));
+  const expected = [...mac].map((b) => b.toString(16).padStart(2, "0")).join("");
+  let diff = expected.length ^ match[2].length;
+  for (let i = 0; i < expected.length; i++) diff |= expected.charCodeAt(i) ^ match[2].charCodeAt(i);
+  return diff === 0;
+}

package/src/registry-worker/sso/membership.ts

@@ -0,0 +1,157 @@
+// Workspace membership for people who sign in through a workspace's identity
+// provider: roles follow their IdP groups, and the IdP can remove them.
+import { type Env, type WorkspaceRole, isWorkspaceRole } from "../core.js";
+import { flagOn } from "../flags.js";
+import { type AuditActor, recordAudit } from "../org/audit.js";
+
+/** Roles an IdP group may grant. Ownership is only ever given by a person. */
+export const SSO_ROLES = ["admin", "member", "billing"] as const satisfies readonly WorkspaceRole[];
+export type SsoRole = (typeof SSO_ROLES)[number];
+const RANK: Record<SsoRole, number> = { admin: 3, member: 2, billing: 1 };
+
+export function isSsoRole(value: unknown): value is SsoRole {
+  return typeof value === "string" && (SSO_ROLES as readonly string[]).includes(value);
+}
+
+export type OrgIdentity = { id: string; groups: string[] };
+
+const SCIM_ACTOR: AuditActor = { type: "scim", id: "aegis" };
+
+/** The most privileged role any of the person's groups maps to, else the workspace default. */
+export function pickRole(
+  mappings: Array<{ group: string; role: string }>,
+  groups: string[],
+  defaultRole: string,
+): SsoRole | null {
+  const member = new Set(groups);
+  let best: SsoRole | null = null;
+  for (const { group, role } of mappings) {
+    if (!member.has(group) || !isSsoRole(role)) continue;
+    if (!best || RANK[role] > RANK[best]) best = role;
+  }
+  if (best) return best;
+  return isSsoRole(defaultRole) ? defaultRole : null;
+}
+
+export async function groupRoleMappings(env: Env, workspaceId: string): Promise<Array<{ group: string; role: string }>> {
+  const rows = await env.DB.prepare(
+    "SELECT group_name AS \"group\", role FROM workspace_group_roles WHERE workspace_id = ? ORDER BY group_name",
+  ).bind(workspaceId).all<{ group: string; role: string }>();
+  return rows.results;
+}
+
+type LinkedWorkspace = { id: string; defaultRole: string };
+
+async function workspaceForOrg(env: Env, orgId: string): Promise<LinkedWorkspace | null> {
+  return env.DB.prepare(
+    "SELECT id, sso_default_role AS defaultRole FROM workspaces WHERE aegis_org_id = ?",
+  ).bind(orgId).first<LinkedWorkspace>();
+}
+
+export async function isDeprovisioned(env: Env, aegisId: string): Promise<boolean> {
+  const row = await env.DB.prepare("SELECT deprovisioned_at AS at FROM aegis_users WHERE id = ?")
+    .bind(aegisId).first<{ at: string | null }>();
+  return Boolean(row?.at);
+}
+
+/**
+ * Brings an SSO member's workspace membership in line with their groups.
+ * Memberships people granted by invitation are left alone.
+ */
+export async function applyOrgMembership(
+  env: Env,
+  identity: { aegisId: string; email?: string },
+  org: OrgIdentity,
+  actor: AuditActor = { type: "user", id: identity.aegisId },
+): Promise<void> {
+  const workspace = await workspaceForOrg(env, org.id);
+  if (!workspace || !(await flagOn(env, workspace.id, "sso"))) return;
+  const role = pickRole(await groupRoleMappings(env, workspace.id), org.groups, workspace.defaultRole);
+  const existing = await env.DB.prepare(
+    "SELECT role, status, source FROM workspace_memberships WHERE workspace_id = ? AND aegis_id = ?",
+  ).bind(workspace.id, identity.aegisId).first<{ role: string; status: string; source: string }>();
+  if (existing && existing.source !== "sso") return;
+
+  if (!role) {
+    if (existing) {
+      await env.DB.prepare("DELETE FROM workspace_memberships WHERE workspace_id = ? AND aegis_id = ?")
+        .bind(workspace.id, identity.aegisId).run();
+      await recordAudit(env, actor, {
+        workspaceId: workspace.id,
+        action: "sso.member.removed",
+        targetType: "member",
+        targetId: identity.aegisId,
+        data: { reason: "no_matching_group" },
+      });
+    }
+    return;
+  }
+  if (existing && existing.role === role && existing.status === "active") return;
+
+  await env.DB.prepare("INSERT OR IGNORE INTO aegis_users (id, email) VALUES (?, ?)")
+    .bind(identity.aegisId, identity.email ?? null).run();
+  await env.DB.prepare(`
+    INSERT INTO workspace_memberships (workspace_id, aegis_id, role, status, invited_by, created_at, source)
+    VALUES (?, ?, ?, 'active', 'sso', ?, 'sso')
+    ON CONFLICT(workspace_id, aegis_id) DO UPDATE SET role = excluded.role, status = 'active'
+    WHERE workspace_memberships.source = 'sso'
+  `).bind(workspace.id, identity.aegisId, role, new Date().toISOString()).run();
+  await recordAudit(env, actor, {
+    workspaceId: workspace.id,
+    action: existing ? "sso.member.role_changed" : "sso.member.added",
+    targetType: "member",
+    targetId: identity.aegisId,
+    data: { role, ...(existing ? { from: existing.role } : {}) },
+  });
+}
+
+/**
+ * Removes someone the IdP deprovisioned: their access to the workspace, and
+ * every API key they hold (an organization identity belongs to that
+ * organization alone).
+ */
+export async function deprovisionMember(env: Env, workspaceId: string, aegisId: string, email?: string): Promise<void> {
+  const now = new Date().toISOString();
+  const owner = await env.DB.prepare(
+    "SELECT role FROM workspace_memberships WHERE workspace_id = ? AND aegis_id = ? AND status = 'active'",
+  ).bind(workspaceId, aegisId).first<{ role: string }>();
+  await env.DB.batch([
+    env.DB.prepare(`
+      INSERT INTO aegis_users (id, email, deprovisioned_at) VALUES (?, ?, ?)
+      ON CONFLICT(id) DO UPDATE SET deprovisioned_at = excluded.deprovisioned_at
+    `).bind(aegisId, email ?? null, now),
+    env.DB.prepare("DELETE FROM workspace_memberships WHERE workspace_id = ? AND aegis_id = ?").bind(workspaceId, aegisId),
+    env.DB.prepare(`
+      DELETE FROM project_memberships
+      WHERE aegis_id = ? AND project_id IN (SELECT id FROM projects WHERE workspace_id = ?)
+    `).bind(aegisId, workspaceId),
+    env.DB.prepare("UPDATE api_keys SET revoked_at = ? WHERE aegis_id = ? AND revoked_at IS NULL").bind(now, aegisId),
+  ]);
+  const owners = await env.DB.prepare(
+    "SELECT COUNT(*) AS n FROM workspace_memberships WHERE workspace_id = ? AND role = 'owner' AND status = 'active'",
+  ).bind(workspaceId).first<{ n: number }>();
+  await recordAudit(env, SCIM_ACTOR, {
+    workspaceId,
+    action: "sso.member.deprovisioned",
+    targetType: "member",
+    targetId: aegisId,
+    data: {
+      ...(isWorkspaceRole(owner?.role) ? { role: owner.role } : {}),
+      ...((owners?.n ?? 0) === 0 ? { warning: "workspace_has_no_owner" } : {}),
+    },
+  });
+}
+
+export async function reactivateMember(env: Env, workspaceId: string, aegisId: string): Promise<void> {
+  const result = await env.DB.prepare("UPDATE aegis_users SET deprovisioned_at = NULL WHERE id = ? AND deprovisioned_at IS NOT NULL")
+    .bind(aegisId).run();
+  if (result.meta.changes) {
+    await recordAudit(env, SCIM_ACTOR, { workspaceId, action: "sso.member.reactivated", targetType: "member", targetId: aegisId });
+  }
+}
+
+export async function linkedWorkspace(env: Env, orgId: string, externalRef: unknown): Promise<LinkedWorkspace | null> {
+  const workspace = await workspaceForOrg(env, orgId);
+  // The organization was created for exactly this workspace.
+  return workspace && externalRef === workspace.id ? workspace : null;
+}