@bugmole/cli 0.5.0 → 0.6.0

package/src/registry-worker/feature-flags/admin.ts

@@ -0,0 +1,300 @@
+// Platform-operator routes: per-workspace feature overrides, beta opt-ins and
+// contract (Enterprise) plans. They are for Bugmole staff only, called with
+// `scripts/bugmole-admin.mjs`, and never proxied by the dashboard.
+//
+// Auth is a single bearer secret, PLATFORM_ADMIN_TOKEN (wrangler secret put).
+// Unset, every route answers 503; a missing or wrong token answers 401. Every
+// change is written to the workspace's audit log as actor system:platform_admin
+// with the operator named in x-bugmole-operator.
+import {
+  type PlanId,
+  type PlanOverrides,
+  entitlementsFor,
+  isPlanId,
+} from "../../billing/plan-catalog.js";
+import { type Env, constantTimeEqual, requestJson, response } from "../core.js";
+import { type LimitKey, loadOverrides, overrideActive } from "../feature-access.js";
+import { FEATURE_DEFS, featureForPlanKey, isFeature, type Feature } from "../flags.js";
+import { planChangedHooks } from "../hooks.js";
+import { applyProjectLimit } from "../billing/subscriptions.js";
+import { getWorkspacePlan } from "../billing/entitlements.js";
+import { recordAudit, type AuditActor } from "../org/audit.js";
+import { matchPath, registerPublicRoutes, type RouteContext } from "../routes/index.js";
+import { workspaceFeatures } from "./routes.js";
+
+const PREFIX = "/api/platform/";
+const ACTOR: AuditActor = { type: "system", id: "platform_admin" };
+/** Plans an operator may put a workspace on; Team and Business come from checkout. */
+const CONTRACT_PLANS: PlanId[] = ["enterprise", "free"];
+const MAX_LIMIT = 100_000_000;
+
+async function digest(value: string): Promise<string> {
+  const bytes = new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(value)));
+  return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
+/** Null when the caller holds the platform token; otherwise the response to return. */
+export async function platformAuth(request: Request, env: Env): Promise<Response | null> {
+  const expected = env.PLATFORM_ADMIN_TOKEN?.trim();
+  if (!expected) return response({ error: "Platform administration is not configured" }, 503);
+  const header = request.headers.get("authorization") ?? "";
+  const presented = header.startsWith("Bearer ") ? header.slice(7).trim() : "";
+  // Hashing first makes the comparison constant-time regardless of length.
+  if (!presented || !constantTimeEqual(await digest(presented), await digest(expected))) {
+    return response({ error: "Platform token required" }, 401);
+  }
+  return null;
+}
+
+function operatorOf(request: Request): string {
+  const raw = request.headers.get("x-bugmole-operator") ?? "";
+  const cleaned = raw.replace(/[^\w.@+:-]/g, "").slice(0, 120);
+  return cleaned || "unknown";
+}
+
+async function workspaceExists(env: Env, workspaceId: string): Promise<boolean> {
+  return Boolean(await env.DB.prepare("SELECT id FROM workspaces WHERE id = ?").bind(workspaceId).first());
+}
+
+function parseExpiry(value: unknown, now = new Date()): { expiresAt: string | null } | { error: string } {
+  if (value === undefined || value === null || value === "") return { expiresAt: null };
+  if (typeof value !== "string") return { error: "expiresAt must be an ISO date or date-time" };
+  // A bare date means the end of that day, UTC.
+  const iso = /^\d{4}-\d{2}-\d{2}$/.test(value) ? `${value}T23:59:59.999Z` : value;
+  const at = Date.parse(iso);
+  if (Number.isNaN(at)) return { error: "expiresAt must be an ISO date or date-time" };
+  if (at <= now.getTime()) return { error: "expiresAt must be in the future" };
+  return { expiresAt: new Date(at).toISOString() };
+}
+
+function noteOf(value: unknown): string | null {
+  return typeof value === "string" && value.trim() ? value.trim().slice(0, 500) : null;
+}
+
+async function workspaceDetail(env: Env, workspaceId: string): Promise<Response> {
+  const body = await workspaceFeatures(env, workspaceId);
+  const plan = await getWorkspacePlan(env, workspaceId);
+  const betaRows = await env.DB.prepare("SELECT flag, enabled, updated_at AS updatedAt FROM workspace_flags WHERE workspace_id = ? ORDER BY flag")
+    .bind(workspaceId).all<{ flag: string; enabled: number; updatedAt: string }>();
+  const now = new Date();
+  return response({
+    ...body,
+    contract: { plan: plan.plan, overrides: plan.overrides, provider: plan.provider, periodEnd: plan.periodEnd },
+    overrides: (await loadOverrides(env, workspaceId)).map((row) => ({ ...row, active: overrideActive(row, now) })),
+    betaOptIns: betaRows.results.map((row) => ({ feature: row.flag, enabled: row.enabled === 1, updatedAt: row.updatedAt })),
+  });
+}
+
+async function listOverrides(env: Env): Promise<Response> {
+  const rows = await env.DB.prepare(`
+    SELECT workspace_id AS workspaceId, feature, enabled, expires_at AS expiresAt, reason, set_by AS setBy, updated_at AS updatedAt
+    FROM workspace_feature_overrides ORDER BY workspace_id, feature
+  `).all<{ workspaceId: string; feature: string; enabled: number; expiresAt: string | null; reason: string | null; setBy: string; updatedAt: string }>();
+  const now = new Date();
+  return response({
+    overrides: rows.results.map((row) => ({ ...row, enabled: row.enabled === 1, active: overrideActive(row, now) })),
+  });
+}
+
+async function setOverride(context: RouteContext, workspaceId: string, feature: Feature): Promise<Response> {
+  const { env, request } = context;
+  const body = await requestJson(request);
+  if (!body || typeof body.enabled !== "boolean") return response({ error: "enabled must be true or false" }, 422);
+  const expiry = parseExpiry(body.expiresAt);
+  if ("error" in expiry) return response({ error: expiry.error }, 422);
+  const reason = noteOf(body.reason);
+  const operator = operatorOf(request);
+  const before = (await loadOverrides(env, workspaceId)).find((row) => row.feature === feature) ?? null;
+  await env.DB.prepare(`
+    INSERT INTO workspace_feature_overrides (workspace_id, feature, enabled, expires_at, reason, set_by)
+    VALUES (?, ?, ?, ?, ?, ?)
+    ON CONFLICT(workspace_id, feature) DO UPDATE SET
+      enabled = excluded.enabled, expires_at = excluded.expires_at, reason = excluded.reason,
+      set_by = excluded.set_by, updated_at = CURRENT_TIMESTAMP
+  `).bind(workspaceId, feature, body.enabled ? 1 : 0, expiry.expiresAt, reason, operator).run();
+  await recordAudit(env, ACTOR, {
+    workspaceId,
+    action: "platform.feature_override_set",
+    targetType: "feature",
+    targetId: feature,
+    data: {
+      operator,
+      enabled: body.enabled,
+      expiresAt: expiry.expiresAt,
+      reason,
+      previous: before ? { enabled: before.enabled, expiresAt: before.expiresAt } : null,
+    },
+  }, request);
+  return workspaceDetail(env, workspaceId);
+}
+
+async function clearOverride(context: RouteContext, workspaceId: string, feature: Feature): Promise<Response> {
+  const { env, request } = context;
+  const deleted = await env.DB.prepare("DELETE FROM workspace_feature_overrides WHERE workspace_id = ? AND feature = ?")
+    .bind(workspaceId, feature).run();
+  if ((deleted.meta?.changes ?? 0) === 0) return response({ error: "No override for that feature" }, 404);
+  await recordAudit(env, ACTOR, {
+    workspaceId, action: "platform.feature_override_cleared", targetType: "feature", targetId: feature, data: { operator: operatorOf(request) },
+  }, request);
+  return workspaceDetail(env, workspaceId);
+}
+
+async function setBeta(context: RouteContext, workspaceId: string, feature: Feature): Promise<Response> {
+  const { env, request } = context;
+  let enabled = false;
+  if (request.method === "PUT") {
+    const body = await requestJson(request);
+    if (!body || typeof body.enabled !== "boolean") return response({ error: "enabled must be true or false" }, 422);
+    enabled = body.enabled;
+    await env.DB.prepare(`
+      INSERT INTO workspace_flags (workspace_id, flag, enabled) VALUES (?, ?, ?)
+      ON CONFLICT(workspace_id, flag) DO UPDATE SET enabled = excluded.enabled, updated_at = CURRENT_TIMESTAMP
+    `).bind(workspaceId, feature, enabled ? 1 : 0).run();
+  } else {
+    await env.DB.prepare("DELETE FROM workspace_flags WHERE workspace_id = ? AND flag = ?").bind(workspaceId, feature).run();
+  }
+  await recordAudit(env, ACTOR, {
+    workspaceId,
+    action: request.method === "PUT" ? "platform.beta_opt_in_set" : "platform.beta_opt_in_cleared",
+    targetType: "feature",
+    targetId: feature,
+    data: { operator: operatorOf(request), ...(request.method === "PUT" ? { enabled } : {}) },
+  }, request);
+  return workspaceDetail(env, workspaceId);
+}
+
+const LIMIT_FIELDS: Array<[string, LimitKey]> = [
+  ["projects", "projects"],
+  ["historyDays", "historyDays"],
+  ["cloudMinutes", "cloudMinutes"],
+  ["aiCredits", "aiCredits"],
+  ["parallel", "parallel"],
+  ["retentionDays", "historyDays"],
+];
+
+/** Validates contract limits and features into the PlanOverrides stored on workspace_plans. */
+export function parseContract(body: Record<string, unknown>): { overrides: PlanOverrides } | { error: string } {
+  const overrides: PlanOverrides = {};
+  const limits = body.limits ?? {};
+  if (typeof limits !== "object" || limits === null || Array.isArray(limits)) return { error: "limits must be an object" };
+  for (const key of Object.keys(limits)) {
+    if (!LIMIT_FIELDS.some(([name]) => name === key)) return { error: `Unknown limit: ${key}` };
+  }
+  for (const [name, key] of LIMIT_FIELDS) {
+    if (!(name in limits)) continue;
+    const value = (limits as Record<string, unknown>)[name];
+    // null means no fixed limit.
+    if (value !== null && (typeof value !== "number" || !Number.isInteger(value) || value < 0 || value > MAX_LIMIT)) {
+      return { error: `${name} must be a whole number from 0 to ${MAX_LIMIT}, or null for unlimited` };
+    }
+    overrides[key] = value as number | null;
+  }
+  const features = body.features ?? {};
+  if (typeof features !== "object" || features === null || Array.isArray(features)) return { error: "features must be an object" };
+  for (const [key, value] of Object.entries(features)) {
+    const feature = isFeature(key) ? key : featureForPlanKey(key);
+    const planKey = feature ? FEATURE_DEFS[feature].planFeature : undefined;
+    if (!planKey) return { error: `${key} isn't a plan feature` };
+    if (typeof value !== "boolean") return { error: `features.${key} must be true or false` };
+    overrides.features = { ...overrides.features, [planKey]: value };
+  }
+  return { overrides };
+}
+
+async function setPlan(context: RouteContext, workspaceId: string): Promise<Response> {
+  const { env, request } = context;
+  const body = await requestJson(request);
+  if (!body) return response({ error: "Expected a JSON body" }, 422);
+  if (!isPlanId(body.plan) || !CONTRACT_PLANS.includes(body.plan)) {
+    return response({ error: `plan must be one of ${CONTRACT_PLANS.join(", ")}; Team and Business are bought through checkout` }, 422);
+  }
+  const plan = body.plan;
+  const parsed = plan === "free" ? { overrides: {} } : parseContract(body);
+  if ("error" in parsed) return response({ error: parsed.error }, 422);
+  const periodEnd = parseExpiry(body.periodEnd);
+  if ("error" in periodEnd) return response({ error: periodEnd.error.replace("expiresAt", "periodEnd") }, 422);
+  const note = noteOf(body.note);
+
+  const existing = await env.DB.prepare("SELECT plan, status, provider, overrides_json AS overrides FROM workspace_plans WHERE workspace_id = ?")
+    .bind(workspaceId).first<{ plan: string; status: string; provider: string | null; overrides: string | null }>();
+  if (existing?.provider && existing.status !== "canceled") {
+    return response({
+      error: `This workspace pays through ${existing.provider}. Cancel that subscription before putting it on a contract plan.`,
+      code: "subscription_active",
+    }, 409);
+  }
+  const from = (await getWorkspacePlan(env, workspaceId)).plan;
+  const overridesJson = Object.keys(parsed.overrides).length ? JSON.stringify(parsed.overrides) : null;
+  const now = new Date().toISOString();
+  await env.DB.prepare(`
+    INSERT INTO workspace_plans (workspace_id, plan, status, overrides_json, current_period_start, current_period_end)
+    VALUES (?, ?, 'active', ?, ?, ?)
+    ON CONFLICT(workspace_id) DO UPDATE SET
+      plan = excluded.plan, status = 'active', overrides_json = excluded.overrides_json,
+      billing_interval = NULL, provider = NULL, provider_subscription_id = NULL,
+      pending_plan = NULL, grace_until = NULL,
+      current_period_start = excluded.current_period_start, current_period_end = excluded.current_period_end,
+      updated_at = CURRENT_TIMESTAMP
+  `).bind(workspaceId, plan, overridesJson, plan === "free" ? null : now, periodEnd.expiresAt).run();
+  const { locked } = await applyProjectLimit(env, workspaceId, entitlementsFor(plan, parsed.overrides));
+  await recordAudit(env, ACTOR, {
+    workspaceId,
+    action: "platform.plan_set",
+    targetType: "workspace",
+    targetId: workspaceId,
+    data: {
+      operator: operatorOf(request),
+      from,
+      to: plan,
+      overrides: parsed.overrides,
+      previousOverrides: existing?.overrides ? JSON.parse(existing.overrides) : null,
+      periodEnd: periodEnd.expiresAt,
+      note,
+      lockedProjects: locked,
+    },
+  }, request);
+  // Always, even Enterprise → Enterprise: contract features (SSO, SCIM) may have changed.
+  for (const hook of planChangedHooks) {
+    try {
+      await hook(env, { workspaceId, from, to: plan });
+    } catch (error) {
+      console.error("[platform] plan change hook failed", error);
+    }
+  }
+  return workspaceDetail(env, workspaceId);
+}
+
+async function route(context: RouteContext): Promise<Response | null> {
+  const { request, env, url } = context;
+  if (!url.pathname.startsWith(PREFIX)) return null;
+  const denied = await platformAuth(request, env);
+  if (denied) return denied;
+  const path = url.pathname;
+  const method = request.method;
+
+  if (path === "/api/platform/feature-overrides" && method === "GET") return listOverrides(env);
+
+  let params = matchPath(path, "/api/platform/workspaces/:workspaceId/features");
+  if (params && method === "GET") {
+    if (!(await workspaceExists(env, params.workspaceId))) return response({ error: "Workspace not found" }, 404);
+    return workspaceDetail(env, params.workspaceId);
+  }
+  params = matchPath(path, "/api/platform/workspaces/:workspaceId/features/:feature")
+    ?? matchPath(path, "/api/platform/workspaces/:workspaceId/beta/:feature");
+  if (params && (method === "PUT" || method === "DELETE")) {
+    if (!isFeature(params.feature)) return response({ error: `Unknown feature: ${params.feature}` }, 404);
+    if (!(await workspaceExists(env, params.workspaceId))) return response({ error: "Workspace not found" }, 404);
+    if (path.includes("/beta/")) return setBeta(context, params.workspaceId, params.feature);
+    return method === "PUT"
+      ? setOverride(context, params.workspaceId, params.feature)
+      : clearOverride(context, params.workspaceId, params.feature);
+  }
+  params = matchPath(path, "/api/platform/workspaces/:workspaceId/plan");
+  if (params && method === "PUT") {
+    if (!(await workspaceExists(env, params.workspaceId))) return response({ error: "Workspace not found" }, 404);
+    return setPlan(context, params.workspaceId);
+  }
+  return response({ error: "Not found" }, 404);
+}
+
+registerPublicRoutes(route);

package/src/registry-worker/feature-flags/feature-flags.test.ts

@@ -0,0 +1,270 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { PLANS, type PlanFeatures } from "../../billing/plan-catalog.js";
+import { freePlan, type WorkspacePlan } from "../billing/entitlements.js";
+import { blockedBy, evaluateFeatures, featureState, requiredPlanFor, type FeatureOverride } from "../feature-access.js";
+import { FEATURES, FEATURE_DEFS, OPERATIONAL_FEATURES, type Feature } from "../flags.js";
+import { call, createTestEnv, seedProject } from "../testing/harness.js";
+
+const ADMIN_TOKEN = "platform-test-token";
+const ALL_ON = Object.fromEntries(FEATURES.map((feature) => [`FEATURE_${feature.toUpperCase()}`, "on"]));
+
+function planOf(plan: WorkspacePlan["plan"], overrides: WorkspacePlan["overrides"] = {}): WorkspacePlan {
+  return { ...freePlan("acme"), plan, overrides };
+}
+
+function override(feature: Feature, enabled: boolean, expiresAt: string | null = null): FeatureOverride {
+  return { feature, enabled, expiresAt, reason: null, setBy: "ops", updatedAt: "2026-09-30T00:00:00Z" };
+}
+
+const NOW = new Date("2026-09-30T12:00:00Z");
+
+test("every catalog feature has exactly one flag, and every flag is a catalog feature or listed as operational", () => {
+  const catalogKeys = Object.keys(PLANS.free.features) as Array<keyof PlanFeatures>;
+  const mapped = FEATURES.map((feature) => FEATURE_DEFS[feature].planFeature).filter(Boolean);
+  for (const key of catalogKeys) {
+    assert.equal(mapped.filter((value) => value === key).length, 1, `catalog feature ${key} needs exactly one FEATURE_DEFS entry`);
+  }
+  for (const feature of FEATURES) {
+    const key = FEATURE_DEFS[feature].planFeature;
+    if (key) assert.ok(catalogKeys.includes(key), `${feature} maps to ${key}, which isn't in the catalog`);
+    else assert.ok((OPERATIONAL_FEATURES as readonly string[]).includes(feature), `${feature} has no catalog key and isn't listed as operational`);
+  }
+  for (const feature of OPERATIONAL_FEATURES) assert.equal(FEATURE_DEFS[feature].planFeature, undefined);
+});
+
+test("the required plan is the cheapest plan that includes a feature", () => {
+  assert.equal(requiredPlanFor("pr_checks"), "team");
+  assert.equal(requiredPlanFor("device_clouds"), "business");
+  assert.equal(requiredPlanFor("scim"), "enterprise");
+  assert.equal(requiredPlanFor("self_hosted_workers"), "enterprise");
+  assert.equal(requiredPlanFor("feedback"), undefined);
+  assert.equal(requiredPlanFor("ai_failure_analysis"), "free", "all-plans features are on for Free");
+});
+
+test("precedence: kill switch, then beta opt-in, then workspace override, then plan", () => {
+  const evaluate = (env: Record<string, string>, options: { plan?: WorkspacePlan; beta?: Feature[]; overrides?: FeatureOverride[] } = {}) =>
+    evaluateFeatures({
+      env,
+      plan: options.plan ?? planOf("free"),
+      betaOptIns: new Set(options.beta ?? []),
+      overrides: options.overrides ?? [],
+      now: NOW,
+    });
+
+  // Plan only.
+  let result = evaluate(ALL_ON, { plan: planOf("team") });
+  assert.deepEqual([result.pr_checks.enabled, result.pr_checks.reason], [true, "plan"]);
+  assert.deepEqual([result.sso.enabled, result.sso.reason, result.sso.requiredPlan], [false, "plan", "business"]);
+  assert.deepEqual([result.feedback.enabled, result.feedback.reason, result.feedback.requiredPlan], [true, "plan", undefined]);
+
+  // A workspace override beats the plan both ways.
+  result = evaluate(ALL_ON, { plan: planOf("team"), overrides: [override("sso", true), override("pr_checks", false)] });
+  assert.deepEqual([result.sso.enabled, result.sso.reason], [true, "workspace_override"]);
+  assert.deepEqual([result.pr_checks.enabled, result.pr_checks.reason], [false, "workspace_override"]);
+
+  // The kill switch beats an override and the plan; shadow counts as off for access.
+  result = evaluate({ ...ALL_ON, FEATURE_SSO: "off", FEATURE_PR_CHECKS: "shadow" }, { plan: planOf("business"), overrides: [override("sso", true)] });
+  assert.deepEqual([result.sso.enabled, result.sso.reason], [false, "flag_off"]);
+  assert.deepEqual([result.pr_checks.enabled, result.pr_checks.reason], [false, "flag_off"]);
+
+  // Beta needs an opt-in before an override or the plan is consulted.
+  result = evaluate({ ...ALL_ON, FEATURE_SLACK: "beta" }, { plan: planOf("business"), overrides: [override("slack", true)] });
+  assert.deepEqual([result.slack.enabled, result.slack.reason], [false, "beta_not_enabled"]);
+  result = evaluate({ ...ALL_ON, FEATURE_SLACK: "beta" }, { plan: planOf("business"), beta: ["slack"], overrides: [override("slack", false)] });
+  assert.deepEqual([result.slack.enabled, result.slack.reason], [false, "workspace_override"]);
+  result = evaluate({ ...ALL_ON, FEATURE_SLACK: "beta" }, { plan: planOf("free"), beta: ["slack"] });
+  assert.deepEqual([result.slack.enabled, result.slack.reason, result.slack.requiredPlan], [false, "plan", "team"]);
+
+  // Blocked-by classifies what a gate should answer.
+  assert.equal(blockedBy(result.slack), "plan");
+  assert.equal(blockedBy(evaluate({ FEATURE_SLACK: "off" }).slack), "rollout");
+  assert.equal(blockedBy(evaluate(ALL_ON, { plan: planOf("team"), overrides: [override("pr_checks", false)] }).pr_checks), "rollout");
+});
+
+test("unset vars: launch flags default to beta, plan features default to on", () => {
+  const result = evaluateFeatures({ env: {}, plan: planOf("enterprise"), betaOptIns: new Set(["mcp"]), overrides: [], now: NOW });
+  assert.equal(result.sso.reason, "beta_not_enabled");
+  assert.equal(result.mcp.enabled, true);
+  assert.deepEqual([result.scim.enabled, result.scim.mode], [true, "on"]);
+  assert.deepEqual([result.ai_fixes.enabled, result.audit_export.enabled], [true, true]);
+});
+
+test("an expired override stops counting", () => {
+  const overrides = [override("device_clouds", true, "2026-09-30T11:59:59Z"), override("sso", true, "2026-10-01T00:00:00Z")];
+  const result = evaluateFeatures({ env: ALL_ON, plan: planOf("free"), betaOptIns: new Set(), overrides, now: NOW });
+  assert.deepEqual([result.device_clouds.enabled, result.device_clouds.reason], [false, "plan"]);
+  assert.deepEqual([result.sso.enabled, result.sso.reason, result.sso.overrideExpiresAt], [true, "workspace_override", "2026-10-01T00:00:00Z"]);
+});
+
+test("contract overrides on an Enterprise plan report enterprise_override", () => {
+  const plan = planOf("enterprise", { projects: 200, features: { scim: false, selfHostedWorkers: true } });
+  const result = evaluateFeatures({ env: ALL_ON, plan, betaOptIns: new Set(), overrides: [], now: NOW });
+  assert.deepEqual([result.scim.enabled, result.scim.reason], [false, "enterprise_override"]);
+  assert.deepEqual([result.self_hosted_workers.enabled, result.self_hosted_workers.reason], [true, "enterprise_override"]);
+  assert.deepEqual([result.sso.enabled, result.sso.reason], [true, "plan"]);
+  assert.equal(blockedBy(result.scim), "plan");
+});
+
+test("beta opt-ins come from workspace_flags", async () => {
+  const { env, db } = createTestEnv({ ...ALL_ON, FEATURE_CLOUD_RUNNERS: "beta" });
+  const { workspaceId } = await seedProject(env);
+  assert.equal((await featureState(env, workspaceId, "cloud_runners")).reason, "beta_not_enabled");
+  db.db.prepare("INSERT INTO workspace_flags (workspace_id, flag, enabled) VALUES (?, 'cloud_runners', 0)").run(workspaceId);
+  assert.equal((await featureState(env, workspaceId, "cloud_runners")).enabled, false, "a disabled row isn't an opt-in");
+  db.db.prepare("UPDATE workspace_flags SET enabled = 1 WHERE workspace_id = ?").run(workspaceId);
+  assert.equal((await featureState(env, workspaceId, "cloud_runners")).enabled, true);
+});
+
+test("members read the evaluated features and limits; strangers can't", async () => {
+  const { env } = createTestEnv(ALL_ON);
+  const { workspaceId, owner } = await seedProject(env);
+  const read = await call(env, "GET", `/api/workspaces/${workspaceId}/features`, { as: owner });
+  assert.equal(read.status, 200);
+  assert.deepEqual(read.json.plan, { id: "free", name: "Free", status: "active" });
+  assert.equal(read.json.source, "default");
+  assert.equal(read.json.features.pr_checks.enabled, false);
+  assert.equal(read.json.features.pr_checks.requiredPlan, "team");
+  assert.equal(read.json.features.pr_checks.planFeature, "prChecks");
+  assert.deepEqual(
+    { enabled: read.json.planFeatures.deviceClouds.enabled, requiredPlan: read.json.planFeatures.deviceClouds.requiredPlan },
+    { enabled: false, requiredPlan: "business" },
+  );
+  assert.equal(read.json.features.feedback.requiredPlan, null);
+  assert.deepEqual(read.json.limits.projects, { limit: 1, unlimited: false, used: 1 });
+  assert.deepEqual(read.json.limits.cloudMinutes, { limit: 300, unlimited: false, used: 0 });
+  assert.deepEqual(read.json.limits.parallel, { limit: 2, unlimited: false });
+  assert.equal(read.json.limitsEnforced, "enforce");
+  assert.equal((await call(env, "GET", `/api/workspaces/${workspaceId}/features`, { as: "user_stranger" })).status, 403);
+});
+
+test("platform routes: 503 without the secret, 401 without or with a wrong token", async () => {
+  const unset = createTestEnv(ALL_ON);
+  await seedProject(unset.env);
+  assert.equal((await call(unset.env, "GET", "/api/platform/workspaces/acme/features", { token: "anything" })).status, 503);
+
+  const { env } = createTestEnv({ ...ALL_ON, PLATFORM_ADMIN_TOKEN: ADMIN_TOKEN });
+  const { owner } = await seedProject(env);
+  assert.equal((await call(env, "GET", "/api/platform/workspaces/acme/features")).status, 401);
+  assert.equal((await call(env, "GET", "/api/platform/workspaces/acme/features", { token: "wrong" })).status, 401);
+  assert.equal((await call(env, "GET", "/api/platform/workspaces/acme/features", { token: `${ADMIN_TOKEN}x` })).status, 401);
+  assert.equal((await call(env, "GET", "/api/platform/workspaces/acme/features", { as: owner })).status, 401, "a dashboard session isn't a platform token");
+  assert.equal((await call(env, "PUT", "/api/platform/workspaces/acme/plan", { as: owner, body: { plan: "enterprise" } })).status, 401);
+  assert.equal((await call(env, "GET", "/api/platform/workspaces/acme/features", { token: ADMIN_TOKEN })).status, 200);
+  assert.equal((await call(env, "GET", "/api/platform/workspaces/nope/features", { token: ADMIN_TOKEN })).status, 404);
+  assert.equal((await call(env, "PUT", "/api/platform/workspaces/acme/features/bogus", { token: ADMIN_TOKEN, body: { enabled: true } })).status, 404);
+});
+
+test("an operator override turns a plan feature on for a trial, is audited, and lapses", async () => {
+  const { env, db } = createTestEnv({ ...ALL_ON, PLATFORM_ADMIN_TOKEN: ADMIN_TOKEN });
+  const { workspaceId, owner } = await seedProject(env);
+  const admin = { token: ADMIN_TOKEN, headers: { "x-bugmole-operator": "ops@bugmole.test" } };
+
+  assert.equal((await call(env, "PUT", `/api/platform/workspaces/${workspaceId}/features/sso`, { ...admin, body: { enabled: true, expiresAt: "2020-01-01" } })).status, 422);
+  assert.equal((await call(env, "PUT", `/api/platform/workspaces/${workspaceId}/features/sso`, { ...admin, body: { enabled: "yes" } })).status, 422);
+
+  const set = await call(env, "PUT", `/api/platform/workspaces/${workspaceId}/features/device_clouds`, {
+    ...admin, body: { enabled: true, expiresAt: "2099-01-31", reason: "Trial for Acme" },
+  });
+  assert.equal(set.status, 200);
+  assert.equal(set.json.features.device_clouds.enabled, true);
+  assert.equal(set.json.features.device_clouds.reason, "workspace_override");
+  assert.equal(set.json.features.device_clouds.expiresAt, "2099-01-31T23:59:59.999Z");
+  assert.equal(set.json.overrides[0].setBy, "ops@bugmole.test");
+
+  // The member endpoint and the server gate agree.
+  const member = await call(env, "GET", `/api/workspaces/${workspaceId}/features`, { as: owner });
+  assert.equal(member.json.features.device_clouds.enabled, true);
+  assert.equal(member.json.features.device_clouds.expiresAt, "2099-01-31T23:59:59.999Z");
+  const clouds = await call(env, "GET", `/api/workspaces/${workspaceId}/device-clouds`, { as: owner });
+  assert.equal(clouds.json.available, true);
+
+  const audit = db.db.prepare("SELECT actor_type AS actorType, actor_id AS actorId, action, target_id AS target, data_json AS data FROM audit_log WHERE action LIKE 'platform.%'").all() as Array<Record<string, string>>;
+  assert.equal(audit.length, 1);
+  assert.deepEqual([audit[0].actorType, audit[0].actorId, audit[0].action, audit[0].target], ["system", "platform_admin", "platform.feature_override_set", "device_clouds"]);
+  assert.equal(JSON.parse(audit[0].data).operator, "ops@bugmole.test");
+  assert.equal(JSON.parse(audit[0].data).reason, "Trial for Acme");
+
+  // Past its expiry, the plan decides again.
+  db.db.prepare("UPDATE workspace_feature_overrides SET expires_at = ? WHERE workspace_id = ?").run("2026-01-01T00:00:00.000Z", workspaceId);
+  assert.equal((await call(env, "GET", `/api/workspaces/${workspaceId}/device-clouds`, { as: owner })).json.available, false);
+
+  // Clearing it is audited too; clearing twice is a 404.
+  assert.equal((await call(env, "DELETE", `/api/platform/workspaces/${workspaceId}/features/device_clouds`, admin)).status, 200);
+  assert.equal((await call(env, "DELETE", `/api/platform/workspaces/${workspaceId}/features/device_clouds`, admin)).status, 404);
+  const list = await call(env, "GET", "/api/platform/feature-overrides", admin);
+  assert.deepEqual(list.json.overrides, []);
+});
+
+test("an incident override turns a feature off even on a plan that includes it", async () => {
+  const { env, db } = createTestEnv({ ...ALL_ON, PLATFORM_ADMIN_TOKEN: ADMIN_TOKEN });
+  const { workspaceId, owner } = await seedProject(env);
+  db.db.prepare("INSERT INTO workspace_plans (workspace_id, plan) VALUES (?, 'team')").run(workspaceId);
+  await call(env, "PUT", `/api/platform/workspaces/${workspaceId}/features/ai_fixes`, { token: ADMIN_TOKEN, body: { enabled: false } });
+  const state = await featureState(env, workspaceId, "ai_fixes");
+  assert.deepEqual([state.enabled, state.reason], [false, "workspace_override"]);
+  const read = await call(env, "GET", `/api/workspaces/${workspaceId}/features`, { as: owner });
+  assert.equal(read.json.planFeatures.aiFixes.enabled, false);
+});
+
+test("beta opt-ins are set through the platform routes", async () => {
+  const { env } = createTestEnv({ ...ALL_ON, FEATURE_CLOUD_RUNNERS: "beta", PLATFORM_ADMIN_TOKEN: ADMIN_TOKEN });
+  const { workspaceId } = await seedProject(env);
+  const on = await call(env, "PUT", `/api/platform/workspaces/${workspaceId}/beta/cloud_runners`, { token: ADMIN_TOKEN, body: { enabled: true } });
+  assert.equal(on.status, 200);
+  assert.equal(on.json.features.cloud_runners.enabled, true);
+  assert.deepEqual(on.json.betaOptIns.map((row: { feature: string; enabled: boolean }) => [row.feature, row.enabled]), [["cloud_runners", true]]);
+  const off = await call(env, "DELETE", `/api/platform/workspaces/${workspaceId}/beta/cloud_runners`, { token: ADMIN_TOKEN });
+  assert.equal(off.json.features.cloud_runners.reason, "beta_not_enabled");
+});
+
+test("an operator puts a workspace on an Enterprise contract and back to Free", async () => {
+  const { env, db } = createTestEnv({ ...ALL_ON, PLATFORM_ADMIN_TOKEN: ADMIN_TOKEN });
+  const { workspaceId, owner } = await seedProject(env);
+  const admin = { token: ADMIN_TOKEN, headers: { "x-bugmole-operator": "ops" } };
+
+  assert.equal((await call(env, "PUT", `/api/platform/workspaces/${workspaceId}/plan`, { ...admin, body: { plan: "team" } })).status, 422);
+  assert.equal((await call(env, "PUT", `/api/platform/workspaces/${workspaceId}/plan`, { ...admin, body: { plan: "enterprise", limits: { projects: -1 } } })).status, 422);
+  assert.equal((await call(env, "PUT", `/api/platform/workspaces/${workspaceId}/plan`, { ...admin, body: { plan: "enterprise", limits: { seats: 3 } } })).status, 422);
+  assert.equal((await call(env, "PUT", `/api/platform/workspaces/${workspaceId}/plan`, { ...admin, body: { plan: "enterprise", features: { teleport: true } } })).status, 422);
+  assert.equal((await call(env, "PUT", `/api/platform/workspaces/${workspaceId}/plan`, { ...admin, body: { plan: "enterprise", features: { feedback: true } } })).status, 422, "operational flags aren't contract features");
+
+  const set = await call(env, "PUT", `/api/platform/workspaces/${workspaceId}/plan`, {
+    ...admin,
+    body: {
+      plan: "enterprise",
+      limits: { projects: 40, cloudMinutes: 50_000, aiCredits: 20_000, parallel: 60, retentionDays: 400 },
+      features: { scim: false, self_hosted_workers: true },
+      note: "Contract C-17",
+    },
+  });
+  assert.equal(set.status, 200);
+  assert.equal(set.json.plan.id, "enterprise");
+  assert.equal(set.json.source, "contract");
+  assert.deepEqual(set.json.limits.projects, { limit: 40, unlimited: false, used: 1 });
+  assert.equal(set.json.limits.historyDays.limit, 400);
+  assert.equal(set.json.features.scim.reason, "enterprise_override");
+  assert.equal(set.json.features.scim.enabled, false);
+  assert.equal(set.json.features.sso.enabled, true);
+
+  const usage = await call(env, "GET", `/api/workspaces/${workspaceId}/usage`, { as: owner });
+  assert.equal(usage.json.usage.lines.browser_minute.included, 50_000, "enforcement reads the same contract");
+  assert.equal(usage.json.limits.parallel, 60);
+
+  const [audit] = db.db.prepare("SELECT data_json AS data FROM audit_log WHERE action = 'platform.plan_set'").all() as Array<{ data: string }>;
+  const data = JSON.parse(audit.data);
+  assert.deepEqual([data.from, data.to, data.note, data.overrides.historyDays], ["free", "enterprise", "Contract C-17", 400]);
+
+  const back = await call(env, "PUT", `/api/platform/workspaces/${workspaceId}/plan`, { ...admin, body: { plan: "free" } });
+  assert.equal(back.json.plan.id, "free");
+  assert.equal(back.json.limits.projects.limit, 1);
+});
+
+test("a workspace paying through PayPal can't be put on a contract", async () => {
+  const { env, db } = createTestEnv({ ...ALL_ON, PLATFORM_ADMIN_TOKEN: ADMIN_TOKEN });
+  const { workspaceId } = await seedProject(env);
+  db.db.prepare("INSERT INTO workspace_plans (workspace_id, plan, provider, provider_subscription_id) VALUES (?, 'business', 'paypal', 'I-1')").run(workspaceId);
+  const refused = await call(env, "PUT", `/api/platform/workspaces/${workspaceId}/plan`, { token: ADMIN_TOKEN, body: { plan: "enterprise" } });
+  assert.equal(refused.status, 409);
+  assert.equal(refused.json.code, "subscription_active");
+});