@bugmole/cli 0.4.0 → 0.6.0

package/src/registry-worker/feature-access.ts

@@ -0,0 +1,165 @@
+// The one answer to "may this workspace use feature X?". Every layer is
+// evaluated in a fixed order, and the first one that decides wins:
+//
+//   1. Global kill switch   FEATURE_<NAME>=off (or shadow)       → off, "flag_off"
+//   2. Beta rollout         FEATURE_<NAME>=beta needs a workspace_flags opt-in,
+//                           otherwise off, "beta_not_enabled"
+//   3. Workspace override   an unexpired workspace_feature_overrides row forces
+//                           it on or off (trials, comps, incidents), "workspace_override"
+//   4. Plan                 the plan's catalog features, "plan"; changed by the
+//                           contract overrides on workspace_plans, "enterprise_override"
+//
+// Features with no plan gate are on for every plan once the rollout allows
+// them (reason "plan"). See docs/feature-flags.md.
+import { LIMIT_KEYS, PLANS, PLAN_IDS, entitlementsFor, type LimitKey, type PlanId } from "../billing/plan-catalog.js";
+import type { Env } from "./core.js";
+import { FEATURES, FEATURE_DEFS, flagMode, type Feature, type FlagMode } from "./flags.js";
+import { freePlan, getWorkspacePlan, type WorkspacePlan } from "./billing/entitlements.js";
+
+export type FeatureReason = "plan" | "flag_off" | "beta_not_enabled" | "workspace_override" | "enterprise_override";
+
+export type FeatureState = {
+  feature: Feature;
+  enabled: boolean;
+  reason: FeatureReason;
+  /** The cheapest plan that includes it, for plan-gated features (null when no self-serve plan does). */
+  requiredPlan?: PlanId;
+  /** The global rollout mode it was evaluated under. */
+  mode: FlagMode;
+  /** When a workspace override decided, when it lapses (null: until cleared). */
+  overrideExpiresAt?: string | null;
+};
+
+export type FeatureOverride = { feature: Feature; enabled: boolean; expiresAt: string | null; reason: string | null; setBy: string; updatedAt: string };
+
+export type FeatureInputs = {
+  env: Omit<Env, "DB"> | Record<string, unknown>;
+  plan: WorkspacePlan;
+  /** Features this workspace opted into while they are in beta. */
+  betaOptIns: ReadonlySet<Feature>;
+  overrides: readonly FeatureOverride[];
+  now?: Date;
+};
+
+/** The cheapest plan whose catalog features include this one. */
+export function requiredPlanFor(feature: Feature): PlanId | undefined {
+  const key = FEATURE_DEFS[feature].planFeature;
+  if (!key) return undefined;
+  return PLAN_IDS.find((plan) => PLANS[plan].features[key]);
+}
+
+export function overrideActive(override: Pick<FeatureOverride, "expiresAt">, now = new Date()): boolean {
+  return !override.expiresAt || Date.parse(override.expiresAt) > now.getTime();
+}
+
+/** Pure evaluation of every feature; the async loaders below feed it. */
+export function evaluateFeatures(inputs: FeatureInputs): Record<Feature, FeatureState> {
+  const now = inputs.now ?? new Date();
+  const entitlements = entitlementsFor(inputs.plan.plan, inputs.plan.overrides);
+  const contract = inputs.plan.overrides.features ?? {};
+  const result = {} as Record<Feature, FeatureState>;
+  for (const feature of FEATURES) {
+    const def = FEATURE_DEFS[feature];
+    const mode = flagMode(inputs.env as Parameters<typeof flagMode>[0], feature);
+    const requiredPlan = requiredPlanFor(feature);
+    const base = { feature, mode, ...(def.planFeature ? { requiredPlan } : {}) } as Pick<FeatureState, "feature" | "mode" | "requiredPlan">;
+    if (mode === "off" || mode === "shadow") {
+      result[feature] = { ...base, enabled: false, reason: "flag_off" };
+      continue;
+    }
+    if (mode === "beta" && !inputs.betaOptIns.has(feature)) {
+      result[feature] = { ...base, enabled: false, reason: "beta_not_enabled" };
+      continue;
+    }
+    const override = inputs.overrides.find((row) => row.feature === feature && overrideActive(row, now));
+    if (override) {
+      result[feature] = { ...base, enabled: override.enabled, reason: "workspace_override", overrideExpiresAt: override.expiresAt };
+      continue;
+    }
+    if (!def.planFeature) {
+      result[feature] = { ...base, enabled: true, reason: "plan" };
+      continue;
+    }
+    const contractSet = contract[def.planFeature] !== undefined;
+    result[feature] = { ...base, enabled: entitlements.features[def.planFeature], reason: contractSet ? "enterprise_override" : "plan" };
+  }
+  return result;
+}
+
+async function betaOptIns(env: Env, workspaceId: string): Promise<Set<Feature>> {
+  const rows = await env.DB.prepare("SELECT flag FROM workspace_flags WHERE workspace_id = ? AND enabled = 1")
+    .bind(workspaceId).all<{ flag: string }>();
+  return new Set(rows.results.map((row) => row.flag).filter((flag): flag is Feature => (FEATURES as readonly string[]).includes(flag)));
+}
+
+/** Override rows for a workspace, expired ones included. Tolerates a registry not yet migrated. */
+export async function loadOverrides(env: Env, workspaceId: string): Promise<FeatureOverride[]> {
+  try {
+    const rows = await env.DB.prepare(`
+      SELECT feature, enabled, expires_at AS expiresAt, reason, set_by AS setBy, updated_at AS updatedAt
+      FROM workspace_feature_overrides WHERE workspace_id = ?
+    `).bind(workspaceId).all<{ feature: string; enabled: number; expiresAt: string | null; reason: string | null; setBy: string; updatedAt: string }>();
+    return rows.results
+      .filter((row) => (FEATURES as readonly string[]).includes(row.feature))
+      .map((row) => ({ ...row, feature: row.feature as Feature, enabled: row.enabled === 1 }));
+  } catch (error) {
+    console.error("[features] workspace_feature_overrides unavailable; is migration 0043 applied?", error);
+    return [];
+  }
+}
+
+export type EffectiveFeatures = {
+  plan: WorkspacePlan;
+  features: Record<Feature, FeatureState>;
+};
+
+/** Every feature for one workspace (three small reads). A null workspace is a Free workspace with no opt-ins. */
+export async function effectiveFeatures(env: Env, workspaceId: string | null | undefined, now = new Date()): Promise<EffectiveFeatures> {
+  if (!workspaceId) {
+    const plan = freePlan("");
+    return { plan, features: evaluateFeatures({ env, plan, betaOptIns: new Set(), overrides: [], now }) };
+  }
+  const [plan, optIns, overrides] = await Promise.all([
+    getWorkspacePlan(env, workspaceId),
+    betaOptIns(env, workspaceId),
+    loadOverrides(env, workspaceId),
+  ]);
+  return { plan, features: evaluateFeatures({ env, plan, betaOptIns: optIns, overrides, now }) };
+}
+
+export async function featureState(env: Env, workspaceId: string | null | undefined, feature: Feature): Promise<FeatureState> {
+  return (await effectiveFeatures(env, workspaceId)).features[feature];
+}
+
+export async function featureEnabled(env: Env, workspaceId: string | null | undefined, feature: Feature): Promise<boolean> {
+  return (await featureState(env, workspaceId, feature)).enabled;
+}
+
+/**
+ * Why a feature is off, in the terms gates answer with: "rollout" (not
+ * available to this workspace yet, or switched off for it) or "plan" (an
+ * upgrade would unlock it, so a 402). Null when it is on.
+ */
+export function blockedBy(state: FeatureState): "rollout" | "plan" | null {
+  if (state.enabled) return null;
+  return state.reason === "plan" || state.reason === "enterprise_override" ? "plan" : "rollout";
+}
+
+export type { LimitKey };
+/** A catalog limit (LIMIT_KEYS). Enforcement reads the same entitlementsFor() values. */
+export type LimitState = { limit: number | null; unlimited: boolean; used?: number };
+
+/** A workspace's limits: its plan's catalog limits with contract overrides applied. */
+export function limitsFor(plan: WorkspacePlan): Record<LimitKey, LimitState> {
+  const entitlements = entitlementsFor(plan.plan, plan.overrides);
+  return Object.fromEntries(LIMIT_KEYS.map((key) => {
+    const limit = entitlements[key];
+    return [key, { limit, unlimited: limit === null }];
+  })) as Record<LimitKey, LimitState>;
+}
+
+/** Where a workspace's plan comes from, for ops and the dashboard. */
+export function planSource(plan: WorkspacePlan): "default" | "subscription" | "contract" {
+  if (plan.provider) return "subscription";
+  return plan.plan === "free" ? "default" : "contract";
+}

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);