@agilesyndrome/cf-genai-base 0.2.5 → 1.0.1

package/README.md

@@ -33,3 +33,10 @@ Features expose `middleware(request, env, ctx, next, state)` and may short-circu
 requests, and optionally deliver server-side PostHog events. Use
 `assertBoot(env, { bindings: ["DB"], required: ["AUTH_SESSION_SECRET"] })` in a
 site initializer to fail closed when its Cloudflare configuration is incomplete.
+
+
+## Core operational services
+
+Apply `migrations/0002_core.sql` after the authorization migration. The package exports `registerHealthcheck`, `updateHealthcheck`, `registerCircuitBreaker`, `setCircuitBreaker`, and `evaluateCircuitBreaker` from `/cf-genai-base`. Healthchecks use `red`, `yellow` (unknown/transient), or `green`; breakers use `off`, `tripped`, or `on`, with `any` or `all` healthcheck evaluation. Automated evaluation may only move `on` to `tripped`, or self-healing `tripped` to `on`; admin API writes are the human control plane for the `off` state.
+
+Admin APIs are `GET /api/admin/healthchecks`, `PUT /api/admin/healthchecks/:id`, `GET /api/admin/circuit-breakers`, `GET|PUT /api/admin/circuit-breakers/:id`. Feature manifests may expose `healthchecks` and `circuitBreakers`. Use `createD1(env, { who })` for downstream D1 calls; it emits EventLog and AuditLog console records with the requesting actor.

package/migrations/0002_core.sql

@@ -0,0 +1,45 @@
+CREATE TABLE IF NOT EXISTS core_healthchecks (
+  id TEXT PRIMARY KEY,
+  feature TEXT NOT NULL,
+  component TEXT NOT NULL,
+  display_name TEXT NOT NULL,
+  state TEXT NOT NULL DEFAULT 'yellow' CHECK (state IN ('red', 'yellow', 'green')),
+  metadata_json TEXT NOT NULL DEFAULT '{}',
+  created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  updated_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  UNIQUE(feature, component)
+);
+
+CREATE INDEX IF NOT EXISTS core_healthchecks_state_idx ON core_healthchecks(state);
+
+CREATE TABLE IF NOT EXISTS core_circuit_breakers (
+  id TEXT PRIMARY KEY,
+  feature TEXT NOT NULL,
+  name TEXT NOT NULL,
+  display_name TEXT NOT NULL,
+  state TEXT NOT NULL DEFAULT 'off' CHECK (state IN ('off', 'tripped', 'on')),
+  healthcheck_mode TEXT NOT NULL DEFAULT 'any' CHECK (healthcheck_mode IN ('any', 'all')),
+  allow_self_healing INTEGER NOT NULL DEFAULT 0 CHECK (allow_self_healing IN (0, 1)),
+  metadata_json TEXT NOT NULL DEFAULT '{}',
+  created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  updated_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  UNIQUE(feature, name)
+);
+
+CREATE TABLE IF NOT EXISTS core_circuit_breaker_healthchecks (
+  circuit_breaker_id TEXT NOT NULL REFERENCES core_circuit_breakers(id) ON DELETE CASCADE,
+  healthcheck_id TEXT NOT NULL REFERENCES core_healthchecks(id) ON DELETE CASCADE,
+  PRIMARY KEY(circuit_breaker_id, healthcheck_id)
+);
+
+CREATE INDEX IF NOT EXISTS core_circuit_breaker_healthchecks_healthcheck_idx
+  ON core_circuit_breaker_healthchecks(healthcheck_id);
+
+CREATE TABLE IF NOT EXISTS core_circuit_breaker_dependencies (
+  circuit_breaker_id TEXT NOT NULL REFERENCES core_circuit_breakers(id) ON DELETE CASCADE,
+  dependency_id TEXT NOT NULL REFERENCES core_circuit_breakers(id) ON DELETE CASCADE,
+  PRIMARY KEY(circuit_breaker_id, dependency_id)
+);
+
+CREATE INDEX IF NOT EXISTS core_circuit_breaker_dependencies_dependency_idx
+  ON core_circuit_breaker_dependencies(dependency_id);

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@agilesyndrome/cf-genai-base",
-  "version": "0.2.5",
+  "version": "1.0.1",
   "type": "module",
   "exports": {
     ".": "./src/index.js",
     "./authorization": "./src/authorization.js",
+    "./core": "./src/core.js",
     "./ui": "./src/ui/index.js",
     "./ui/styles.css": "./src/ui/styles.css"
   },

package/src/authorization.js

@@ -1,3 +1,5 @@
+import { createD1 } from "./core.js";
+
 export const AUTH_USER_TABLE = "auth_users";
 export const AUTH_SCOPE_TABLE = "auth_scopes";
 export const AUTH_GRANT_TABLE = "auth_user_scopes";
@@ -8,58 +10,65 @@ export function normalizeScopes(scopes = []) {
     .map((scope) => ({ name: String(scope.name), label: String(scope.label || scope.name), description: String(scope.description || ""), system: Boolean(scope.system) }));
 }
 
-export async function ensureScopes(env, scopes = []) {
+export async function ensureScopes(env, scopes = [], { who = "system:read" } = {}) {
   if (!env?.DB) return;
+  const db = createD1(env, { who });
   for (const scope of normalizeScopes(scopes)) {
-    await env.DB.prepare(`INSERT INTO ${AUTH_SCOPE_TABLE} (name,label,description,system) VALUES (?,?,?,?) ON CONFLICT(name) DO UPDATE SET label=excluded.label,description=excluded.description,system=excluded.system`).bind(scope.name, scope.label, scope.description, scope.system ? 1 : 0).run();
+    await db.prepare(`INSERT INTO ${AUTH_SCOPE_TABLE} (name,label,description,system) VALUES (?,?,?,?) ON CONFLICT(name) DO UPDATE SET label=excluded.label,description=excluded.description,system=excluded.system`).bind(scope.name, scope.label, scope.description, scope.system ? 1 : 0).run();
   }
 }
 
-export async function ensureUser(env, user) {
+export async function ensureUser(env, user, { who = "system:read" } = {}) {
   if (!env?.DB || !user?.sub) return null;
+  const db = createD1(env, { who });
   const provider = String(user.auth_strategy || "oauth");
   const subject = String(user.sub);
   const email = String(user.email || "").trim().toLowerCase();
-  const existing = await env.DB.prepare(`SELECT * FROM ${AUTH_USER_TABLE} WHERE provider=? AND subject=?`).bind(provider, subject).first();
+  const existing = await db.prepare(`SELECT * FROM ${AUTH_USER_TABLE} WHERE provider=? AND subject=?`).bind(provider, subject).first();
   const bootstrap = new Set(String(env.AUTH_ADMIN_EMAILS || env.ADMIN_EMAILS || "").split(",").map((value) => value.trim().toLowerCase()).filter(Boolean));
   if (existing) {
-    await env.DB.prepare(`UPDATE ${AUTH_USER_TABLE} SET email=?,display_name=?,is_admin=CASE WHEN is_admin=1 OR ? THEN 1 ELSE 0 END,updated_at=CURRENT_TIMESTAMP WHERE id=?`).bind(email, String(user.name || email || subject), bootstrap.has(email) ? 1 : 0, existing.id).run();
+    await db.prepare(`UPDATE ${AUTH_USER_TABLE} SET email=?,display_name=?,is_admin=CASE WHEN is_admin=1 OR ? THEN 1 ELSE 0 END,updated_at=CURRENT_TIMESTAMP WHERE id=?`).bind(email, String(user.name || email || subject), bootstrap.has(email) ? 1 : 0, existing.id).run();
     return { ...existing, email, display_name: String(user.name || email || subject), is_admin: Boolean(existing.is_admin || bootstrap.has(email)) };
   }
   const id = await stableId(`${provider}:${subject}`);
-  await env.DB.prepare(`INSERT INTO ${AUTH_USER_TABLE} (id,provider,subject,email,display_name,is_admin) VALUES (?,?,?,?,?,?) ON CONFLICT(provider,subject) DO NOTHING`).bind(id, provider, subject, email, String(user.name || email || subject), bootstrap.has(email) ? 1 : 0).run();
-  return await env.DB.prepare(`SELECT * FROM ${AUTH_USER_TABLE} WHERE id=?`).bind(id).first();
+  await db.prepare(`INSERT INTO ${AUTH_USER_TABLE} (id,provider,subject,email,display_name,is_admin) VALUES (?,?,?,?,?,?) ON CONFLICT(provider,subject) DO NOTHING`).bind(id, provider, subject, email, String(user.name || email || subject), bootstrap.has(email) ? 1 : 0).run();
+  return await db.prepare(`SELECT * FROM ${AUTH_USER_TABLE} WHERE id=?`).bind(id).first();
 }
 
-export async function hasScope(env, user, scope) {
+export async function hasScope(env, user, scope, { who = "system:read" } = {}) {
+  const db = createD1(env, { who });
   if (user?.auth_strategy === "http_basic") return true;
-  const authUser = await ensureUser(env, user);
+  const authUser = await ensureUser(env, user, { who });
   if (!authUser) return false;
   if (Boolean(authUser.is_admin)) return true;
-  return Boolean(await env.DB.prepare(`SELECT 1 FROM ${AUTH_GRANT_TABLE} WHERE user_id=? AND scope_name=?`).bind(authUser.id, scope).first());
+  return Boolean(await db.prepare(`SELECT 1 FROM ${AUTH_GRANT_TABLE} WHERE user_id=? AND scope_name=?`).bind(authUser.id, scope).first());
 }
 
-export async function listAuthorizationUsers(env) {
-  const { results } = await env.DB.prepare(`SELECT id,email,display_name,provider,subject,is_admin,created_at,updated_at FROM ${AUTH_USER_TABLE} ORDER BY email COLLATE NOCASE`).all();
-  return Promise.all(results.map(async (user) => ({ ...user, scopes: (await listUserGrants(env, user.id)).map((grant) => grant.scope_name) })));
+export async function listAuthorizationUsers(env, { who = "system:read" } = {}) {
+  const db = createD1(env, { who });
+  const { results } = await db.prepare(`SELECT id,email,display_name,provider,subject,is_admin,created_at,updated_at FROM ${AUTH_USER_TABLE} ORDER BY email COLLATE NOCASE`).all();
+  return Promise.all(results.map(async (user) => ({ ...user, scopes: (await listUserGrants(env, user.id, { who })).map((grant) => grant.scope_name) })));
 }
 
-export async function listAuthorizationScopes(env) {
-  const { results } = await env.DB.prepare(`SELECT name,label,description,system FROM ${AUTH_SCOPE_TABLE} ORDER BY name`).all();
+export async function listAuthorizationScopes(env, { who = "system:read" } = {}) {
+  const db = createD1(env, { who });
+  const { results } = await db.prepare(`SELECT name,label,description,system FROM ${AUTH_SCOPE_TABLE} ORDER BY name`).all();
   return results;
 }
 
-export async function listUserGrants(env, userId) {
-  const { results } = await env.DB.prepare(`SELECT scope_name,granted_at FROM ${AUTH_GRANT_TABLE} WHERE user_id=? ORDER BY scope_name`).bind(userId).all();
+export async function listUserGrants(env, userId, { who = "system:read" } = {}) {
+  const db = createD1(env, { who });
+  const { results } = await db.prepare(`SELECT scope_name,granted_at FROM ${AUTH_GRANT_TABLE} WHERE user_id=? ORDER BY scope_name`).bind(userId).all();
   return results;
 }
 
-export async function replaceUserGrants(env, userId, scopes, grantedBy) {
-  const valid = new Set((await listAuthorizationScopes(env)).map((scope) => scope.name));
+export async function replaceUserGrants(env, userId, scopes, grantedBy, { who = "system:read" } = {}) {
+  const valid = new Set((await listAuthorizationScopes(env, { who })).map((scope) => scope.name));
+  const db = createD1(env, { who });
   const requested = [...new Set(scopes)].filter((scope) => valid.has(scope));
-  await env.DB.batch([
-    env.DB.prepare(`DELETE FROM ${AUTH_GRANT_TABLE} WHERE user_id=?`).bind(userId),
-    ...requested.map((scope) => env.DB.prepare(`INSERT INTO ${AUTH_GRANT_TABLE} (user_id,scope_name,granted_by) VALUES (?,?,?)`).bind(userId, scope, grantedBy || null))
+  await db.batch([
+    db.prepare(`DELETE FROM ${AUTH_GRANT_TABLE} WHERE user_id=?`).bind(userId),
+    ...requested.map((scope) => db.prepare(`INSERT INTO ${AUTH_GRANT_TABLE} (user_id,scope_name,granted_by) VALUES (?,?,?)`).bind(userId, scope, grantedBy || null))
   ]);
   return requested;
 }

package/src/core.js

@@ -0,0 +1,145 @@
+export const HEALTHCHECK_STATES = ["red", "yellow", "green"];
+export const CIRCUIT_BREAKER_STATES = ["off", "tripped", "on"];
+export const HEALTHCHECK_MODES = ["any", "all"];
+
+export function eventLog(level, event, details = {}) {
+  const method = ["debug", "info", "warn", "error"].includes(level) ? level : "info";
+  console[method](`[EventLog] ${event}`, details);
+}
+
+export function auditLog({ who = "system", operation, resource, details = {} }) {
+  console.info(`[AuditLog] ${who}:${operation} ${resource}`, details);
+}
+
+export function requestActor(state = {}) {
+  if (state.requestedBy) return String(state.requestedBy);
+  if (state.authUser?.id) return `user:${state.authUser.id}`;
+  if (state.user?.auth_strategy === "http_basic") return "user:admin";
+  if (state.user?.sub) return `user:${state.user.sub}`;
+  return "system:read";
+}
+
+export function createD1(env, { who = "system:read" } = {}) {
+  if (!env?.DB) throw new Error("A DB binding is required");
+  const db = env.DB;
+  return {
+    prepare(sql) {
+      const statement = db.prepare(sql);
+      return new Proxy(statement, { get(target, property) {
+        const value = target[property];
+        if (typeof value !== "function" || !["run", "first", "all", "raw"].includes(property)) return typeof value === "function" ? value.bind(target) : value;
+        return async (...args) => {
+          auditD1(who, sql);
+          return value.apply(target, args);
+        };
+      }});
+    },
+    async batch(statements) {
+      auditD1(who, "BATCH");
+      return typeof db.batch === "function" ? db.batch(statements) : Promise.all(statements.map((statement) => statement.run()));
+    },
+  };
+}
+
+function auditD1(who, sql) {
+  const operation = String(sql).trim().match(/^(SELECT|INSERT|UPDATE|DELETE|REPLACE|WITH)/i)?.[1]?.toLowerCase() || "execute";
+  eventLog("debug", "d1.operation", { who, operation });
+  auditLog({ who, operation, resource: "d1" });
+}
+
+export function normalizeHealthcheck(input = {}) {
+  const state = String(input.state || "yellow").toLowerCase();
+  if (!HEALTHCHECK_STATES.includes(state)) throw new Error("Healthcheck state must be red, yellow, or green");
+  if (!input.feature || !input.component || !input.displayName) throw new Error("Healthchecks require feature, component, and displayName");
+  return { feature: String(input.feature), component: String(input.component), displayName: String(input.displayName), state, metadata: input.metadata || {} };
+}
+
+export function normalizeCircuitBreaker(input = {}) {
+  const state = String(input.state || "off").toLowerCase();
+  const healthcheckMode = String(input.healthcheckMode || "any").toLowerCase();
+  if (!CIRCUIT_BREAKER_STATES.includes(state)) throw new Error("Circuit breaker state must be off, tripped, or on");
+  if (!HEALTHCHECK_MODES.includes(healthcheckMode)) throw new Error("Circuit breaker healthcheckMode must be any or all");
+  if (!input.feature || !input.name || !input.displayName) throw new Error("Circuit breakers require feature, name, and displayName");
+  return { feature: String(input.feature), name: String(input.name), displayName: String(input.displayName), state, healthcheckMode, allowSelfHealing: Boolean(input.allowSelfHealing), healthchecks: Array.isArray(input.healthchecks) ? input.healthchecks.map(String) : [], dependsOnCircuitBreakers: Array.isArray(input.dependsOnCircuitBreakers || input.dependencies) ? (input.dependsOnCircuitBreakers || input.dependencies).map(String) : [], metadata: input.metadata || {} };
+}
+
+export async function registerHealthcheck(env, input, { who = "system:read" } = {}) {
+  const item = normalizeHealthcheck(input);
+  const db = createD1(env, { who });
+  const id = String(input.id || `${item.feature}:${item.component}`);
+  await db.prepare(`INSERT INTO core_healthchecks (id,feature,component,display_name,state,metadata_json) VALUES (?,?,?,?,?,?) ON CONFLICT(feature,component) DO UPDATE SET display_name=excluded.display_name,metadata_json=excluded.metadata_json,updated_at=CURRENT_TIMESTAMP`).bind(id, item.feature, item.component, item.displayName, item.state, JSON.stringify(item.metadata)).run();
+  return getHealthcheck(env, id, { who });
+}
+
+export async function updateHealthcheck(env, id, state, { who = "system:read" } = {}) {
+  if (!HEALTHCHECK_STATES.includes(String(state).toLowerCase())) throw new Error("Healthcheck state must be red, yellow, or green");
+  const item = await getHealthcheck(env, id, { who });
+  if (!item) return null;
+  const db = createD1(env, { who });
+  await db.prepare("UPDATE core_healthchecks SET state=?,updated_at=CURRENT_TIMESTAMP WHERE id=?").bind(String(state).toLowerCase(), id).run();
+  auditLog({ who, operation: "update", resource: `feature:${item.feature} component:${item.component} ${String(state).toLowerCase()}` });
+  return getHealthcheck(env, id, { who });
+}
+
+export async function getHealthcheck(env, id, { who = "system:read" } = {}) { return (await createD1(env, { who }).prepare("SELECT * FROM core_healthchecks WHERE id=?").bind(id).first()) || null; }
+export async function listHealthchecks(env, { who = "system:read" } = {}) { return (await createD1(env, { who }).prepare("SELECT * FROM core_healthchecks ORDER BY feature,component").bind().all()).results || []; }
+
+export async function registerCircuitBreaker(env, input, { who = "system:read" } = {}) {
+  const item = normalizeCircuitBreaker(input);
+  const db = createD1(env, { who });
+  const id = String(input.id || `${item.feature}:${item.name}`);
+  await db.prepare(`INSERT INTO core_circuit_breakers (id,feature,name,display_name,state,healthcheck_mode,allow_self_healing,metadata_json) VALUES (?,?,?,?,?,?,?,?) ON CONFLICT(feature,name) DO UPDATE SET display_name=excluded.display_name,healthcheck_mode=excluded.healthcheck_mode,allow_self_healing=excluded.allow_self_healing,metadata_json=excluded.metadata_json,updated_at=CURRENT_TIMESTAMP`).bind(id, item.feature, item.name, item.displayName, item.state, item.healthcheckMode, item.allowSelfHealing ? 1 : 0, JSON.stringify(item.metadata)).run();
+  await db.batch([db.prepare("DELETE FROM core_circuit_breaker_healthchecks WHERE circuit_breaker_id=?").bind(id), db.prepare("DELETE FROM core_circuit_breaker_dependencies WHERE circuit_breaker_id=?").bind(id), ...item.healthchecks.map((healthcheckId) => db.prepare("INSERT OR IGNORE INTO core_circuit_breaker_healthchecks (circuit_breaker_id,healthcheck_id) VALUES (?,?)").bind(id, healthcheckId)), ...item.dependsOnCircuitBreakers.map((dependencyId) => db.prepare("INSERT OR IGNORE INTO core_circuit_breaker_dependencies (circuit_breaker_id,dependency_id) VALUES (?,?)").bind(id, dependencyId))]);
+  return getCircuitBreaker(env, id, { who });
+}
+
+export async function getCircuitBreaker(env, id, { who = "system:read" } = {}) { const db = createD1(env, { who }); const breaker = await db.prepare("SELECT * FROM core_circuit_breakers WHERE id=?").bind(id).first(); if (!breaker) return null; breaker.healthchecks = (await db.prepare("SELECT healthcheck_id FROM core_circuit_breaker_healthchecks WHERE circuit_breaker_id=?").bind(id).all()).results.map((row) => row.healthcheck_id) ; breaker.depends_on_circuit_breakers = (await db.prepare("SELECT dependency_id FROM core_circuit_breaker_dependencies WHERE circuit_breaker_id=?").bind(id).all()).results.map((row) => row.dependency_id); return breaker; }
+export async function listCircuitBreakers(env, { who = "system:read" } = {}) { const rows = (await createD1(env, { who }).prepare("SELECT * FROM core_circuit_breakers ORDER BY feature,name").bind().all()).results || []; return Promise.all(rows.map((row) => getCircuitBreaker(env, row.id, { who }))); }
+
+export async function setCircuitBreaker(env, id, state, { who = "system:read", automated = false } = {}) {
+  const next = String(state).toLowerCase();
+  if (!CIRCUIT_BREAKER_STATES.includes(next)) throw new Error("Circuit breaker state must be off, tripped, or on");
+  const current = await getCircuitBreaker(env, id, { who });
+  if (!current) return null;
+  if (automated && !((current.state === "on" && next === "tripped") || (current.state === "tripped" && next === "on" && Boolean(current.allow_self_healing)))) return current;
+  if (automated && next === "off") return current;
+  await createD1(env, { who }).prepare("UPDATE core_circuit_breakers SET state=?,updated_at=CURRENT_TIMESTAMP WHERE id=?").bind(next, id).run();
+  auditLog({ who, operation: "update", resource: `feature:${current.feature} circuit_breaker:${current.name} ${next}` });
+  return getCircuitBreaker(env, id, { who });
+}
+
+export async function evaluateCircuitBreaker(env, id, { who = "system:read" } = {}) {
+  const breaker = await getCircuitBreaker(env, id, { who });
+  if (!breaker) return null;
+  const db = createD1(env, { who });
+  const rows = (await db.prepare("SELECT h.state FROM core_healthchecks h JOIN core_circuit_breaker_healthchecks b ON b.healthcheck_id=h.id WHERE b.circuit_breaker_id=?").bind(id).all()).results || [];
+  const failing = rows.map((row) => row.state === "red");
+  const dependencies = (await db.prepare("SELECT b.state FROM core_circuit_breakers b JOIN core_circuit_breaker_dependencies d ON d.dependency_id=b.id WHERE d.circuit_breaker_id=?").bind(id).all()).results || [];
+  const dependencyFailed = dependencies.some((row) => row.state === "tripped");
+  const shouldTrip = dependencyFailed || (failing.length > 0 &&  (breaker.healthcheck_mode === "all" ? failing.every(Boolean) : failing.some(Boolean)));
+  if (breaker.state === "on" && shouldTrip) return setCircuitBreaker(env, id, "tripped", { who, automated: true });
+  if (breaker.state === "tripped" && !shouldTrip && breaker.allow_self_healing) return setCircuitBreaker(env, id, "on", { who, automated: true });
+  return breaker;
+}
+
+
+export async function registerFeatureManifests(env, features = [], { who = "system:read" } = {}) {
+  for (const feature of features) {
+    const name = String(feature?.name || feature?.id || "feature");
+    const declaredResult = typeof feature?.healthcheck === "function" ? await feature.healthcheck(env, { who }) : (feature?.healthchecks || feature?.healthChecks || []);
+    const declaredHealthchecks = Array.isArray(declaredResult) ? declaredResult : [declaredResult];
+    const healthchecks = [];
+    const breakers = [];
+    for (const healthcheck of declaredHealthchecks) healthchecks.push(await registerHealthcheck(env, { ...healthcheck, feature: healthcheck.feature || name }, { who }));
+    for (const breaker of feature?.circuitBreakers || feature?.circuit_breakers || []) breakers.push(await registerCircuitBreaker(env, { ...breaker, feature: breaker.feature || name }, { who }));
+    await registerCircuitBreaker(env, { id: `${name}:rollup`, feature: name, name: "rollup", displayName: `${name} feature`, state: "on", allowSelfHealing: true, healthchecks: healthchecks.filter(Boolean).map((item) => item.id), dependsOnCircuitBreakers: breakers.filter(Boolean).map((item) => item.id) }, { who });
+  }
+}
+
+export async function listFeatureHealth(env, { who = "system:read" } = {}) {
+  const checks = await listHealthchecks(env, { who });
+  const severity = { green: 0, yellow: 1, red: 2 };
+  const features = {};
+  for (const check of checks) { const name = check.feature; if (!features[name] || severity[check.state] > severity[features[name].state]) features[name] = { feature: name, state: check.state, healthchecks: 0 }; features[name].healthchecks += 1; }
+  return Object.values(features).sort((a, b) => a.feature.localeCompare(b.feature));
+}

package/src/index.js

@@ -3,6 +3,8 @@
  * Site code owns domain routes and data; this owns lifecycle and edge concerns.
  */
 import { ensureScopes, ensureUser, hasScope, listAuthorizationScopes, listAuthorizationUsers, listUserGrants, replaceUserGrants } from "./authorization.js";
+import { getCircuitBreaker, evaluateCircuitBreaker, listCircuitBreakers, listHealthchecks, listFeatureHealth, registerFeatureManifests, requestActor, setCircuitBreaker, updateHealthcheck } from "./core.js";
+export * from "./core.js";
 export function createWorker({ fetch, scheduled, auth, authorize, scopes = [], scopeRoutes = [], middleware = [], features = [], health, boot, metrics, security = true }) {
   if (typeof fetch !== "function") throw new TypeError("createWorker requires a fetch handler");
   const provider = auth || features.find((feature) => typeof feature?.getUser === "function");
@@ -18,12 +20,14 @@ export function createWorker({ fetch, scheduled, auth, authorize, scopes = [], s
         if (boot) await boot(env, { request, ctx });
         const url = new URL(request.url);
         const state = Object.create(null);
+        if (env?.DB && features.some((feature) => typeof feature?.healthcheck === "function" || feature?.healthchecks?.length || feature?.healthChecks?.length || feature?.circuitBreakers?.length || feature?.circuit_breakers?.length)) ctx?.waitUntil?.(registerFeatureManifests(env, features, { who: "system:update" }).then(() => listCircuitBreakers(env, { who: "system:update" }).then((breakers) => Promise.all(breakers.filter(Boolean).map((breaker) => evaluateCircuitBreaker(env, breaker.id, { who: "system:update" }))))).catch((error) => console.error("[EventLog] feature manifest registration failed", error)));
         const dispatch = async (index, currentRequest = request) => {
           const layer = chain[index];
           if (!layer) {
             if (url.pathname === "/health" || url.pathname === "/api/health") {
               const details = health ? await health(env, { request: currentRequest, ctx, state }) : {};
-              return healthResponse(env, details);
+              const featureHealth = env?.DB ? await listFeatureHealth(env, { who: "system:read" }).catch(() => []) : [];
+              return healthResponse(env, featureHealth.length ? { ...details, features: featureHealth } : details);
             }
             return fetch(currentRequest, env, ctx, state);
           }
@@ -58,10 +62,11 @@ async function adminBoundary(request, env, ctx, next, state, { provider, authori
   } else {
     return new Response("Unsupported AUTH_STRATEGY", { status: 500, headers: { "Cache-Control": "no-store" } });
   }
-  await ensureScopes(env, scopes);
-  state.authUser = await ensureUser(env, state.user);
+  await ensureScopes(env, scopes, { who: state.user?.auth_strategy === "http_basic" ? "user:admin" : `user:${state.user?.sub || "unknown"}` });
+  state.authUser = await ensureUser(env, state.user, { who: state.user?.auth_strategy === "http_basic" ? "user:admin" : `user:${state.user?.sub || "unknown"}` });
+  state.requestedBy = requestActor(state);
   const requiredScope = requiredScopeFor(url.pathname, scopeRoutes);
-  const scopeAllowed = !requiredScope || await hasScope(env, state.user, requiredScope);
+  const scopeAllowed = !requiredScope || await hasScope(env, state.user, requiredScope, { who: requestActor(state) });
   if (!scopeAllowed || (authorize && state.user.auth_strategy !== "http_basic" && !(await authorize({ request, url, user: state.user, env, ctx, state })))) {
     return url.pathname.startsWith("/api/") ? Response.json({ error: "Administrator access is required." }, { status: 403, headers: { "Cache-Control": "no-store" } }) : new Response("Administrator access is required.", { status: 403, headers: { "Cache-Control": "no-store" } });
   }
@@ -76,16 +81,24 @@ function requiredScopeFor(pathname, routes) {
 
 async function authorizationApi(request, env, url, state) {
   const grantsMatch = url.pathname.match(/\/api\/admin\/users\/([^/]+)\/scopes$/);
-  const platformPath = url.pathname === "/api/admin/users" || url.pathname === "/api/admin/scopes" || Boolean(grantsMatch);
+  const platformPath = url.pathname === "/api/admin/users" || url.pathname === "/api/admin/scopes" || url.pathname === "/api/admin/status" || url.pathname === "/api/admin/healthchecks" || url.pathname === "/api/admin/circuit-breakers" || url.pathname.startsWith("/api/admin/healthchecks/") || url.pathname.startsWith("/api/admin/circuit-breakers/") || Boolean(grantsMatch);
   if (!platformPath) return null;
   if (!(state.user.auth_strategy === "http_basic" || (state.authUser && state.authUser.is_admin))) return Response.json({ error: "Administrator access is required." }, { status: 403, headers: { "Cache-Control": "no-store" } });
-  if (url.pathname === "/api/admin/users" && request.method === "GET") return Response.json({ users: await listAuthorizationUsers(env) });
-  if (url.pathname === "/api/admin/scopes" && request.method === "GET") return Response.json({ scopes: await listAuthorizationScopes(env) });
-  if (grantsMatch && request.method === "GET") return Response.json({ grants: await listUserGrants(env, decodeURIComponent(grantsMatch[1])) });
+  if (url.pathname === "/api/admin/users" && request.method === "GET") return Response.json({ users: await listAuthorizationUsers(env, { who: requestActor(state) }) });
+  if (url.pathname === "/api/admin/scopes" && request.method === "GET") return Response.json({ scopes: await listAuthorizationScopes(env, { who: requestActor(state) }) });
+  if (url.pathname === "/api/admin/status" && request.method === "GET") return Response.json({ features: await listFeatureHealth(env, { who: requestActor(state) }) });
+  if (url.pathname === "/api/admin/healthchecks" && request.method === "GET") return Response.json({ healthchecks: await listHealthchecks(env, { who: requestActor(state) }) });
+  if (url.pathname === "/api/admin/circuit-breakers" && request.method === "GET") return Response.json({ circuit_breakers: await listCircuitBreakers(env, { who: requestActor(state) }) });
+  const healthcheckMatch = url.pathname.match(/\/api\/admin\/healthchecks\/([^/]+)$/);
+  if (healthcheckMatch && request.method === "PUT") { const body = await request.json().catch(() => null); if (!body?.state) return Response.json({ error: "state is required" }, { status: 400 }); const healthcheck = await updateHealthcheck(env, decodeURIComponent(healthcheckMatch[1]), body.state, { who: requestActor(state) }); return healthcheck ? Response.json({ healthcheck }) : Response.json({ error: "Healthcheck not found" }, { status: 404 }); }
+  const breakerMatch = url.pathname.match(/\/api\/admin\/circuit-breakers\/([^/]+)$/);
+  if (breakerMatch && request.method === "GET") return Response.json({ circuit_breaker: await getCircuitBreaker(env, decodeURIComponent(breakerMatch[1]), { who: requestActor(state) }) });
+  if (breakerMatch && request.method === "PUT") { const body = await request.json().catch(() => null); if (!body?.state) return Response.json({ error: "state is required" }, { status: 400 }); const breaker = await setCircuitBreaker(env, decodeURIComponent(breakerMatch[1]), body.state, { who: requestActor(state) }); return breaker ? Response.json({ circuit_breaker: breaker }) : Response.json({ error: "Circuit breaker not found" }, { status: 404 }); }
+  if (grantsMatch && request.method === "GET") return Response.json({ grants: await listUserGrants(env, decodeURIComponent(grantsMatch[1]), { who: requestActor(state) }) });
   if (grantsMatch && request.method === "PUT") {
     const body = await request.json().catch(() => null);
     if (!body || !Array.isArray(body.scopes)) return Response.json({ error: "scopes must be an array" }, { status: 400 });
-    const grants = await replaceUserGrants(env, decodeURIComponent(grantsMatch[1]), body.scopes, state.authUser && state.authUser.id);
+    const grants = await replaceUserGrants(env, decodeURIComponent(grantsMatch[1]), body.scopes, state.authUser && state.authUser.id, { who: requestActor(state) });
     return Response.json({ grants });
   }
   return null;

package/src/ui/index.js

@@ -3,7 +3,7 @@ const styles = `:host { --cf-ui-bg:#fff; --cf-ui-surface:#f7f7f5; --cf-ui-text:#
 export class CfAdminShell extends HTMLElement {
   connectedCallback() {
     const active = this.getAttribute("active") || "";
-    this.attachShadow({ mode: "open" }).innerHTML = `<style>${styles}</style><div class="shell"><nav class="nav" part="navigation"><a href="/admin" ${active === "home" ? 'aria-current="page"' : ""}>Admin</a><a href="/admin/users" ${active === "users" ? 'aria-current="page"' : ""}>Users</a><a href="/admin/scopes" ${active === "scopes" ? 'aria-current="page"' : ""}>Scopes</a></nav><slot></slot></div>`;
+    this.attachShadow({ mode: "open" }).innerHTML = `<style>${styles}</style><div class="shell"><nav class="nav" part="navigation"><a href="/admin" ${active === "home" ? 'aria-current="page"' : ""}>Admin</a><a href="/admin/users" ${active === "users" ? 'aria-current="page"' : ""}>Users</a><a href="/admin/scopes" ${active === "scopes" ? 'aria-current="page"' : ""}>Scopes</a><a href="/admin/healthchecks">Healthchecks</a><a href="/admin/circuit-breakers">Circuit breakers</a></nav><slot></slot></div>`;
   }
 }
 
@@ -49,3 +49,14 @@ export class CfScopeCatalog extends HTMLElement {
 
 if (!customElements.get("cf-scope-catalog")) customElements.define("cf-scope-catalog", CfScopeCatalog);
 if (!customElements.get("cf-scope-catalog")) customElements.define("cf-scope-catalog", CfScopeCatalog);
+
+export class CfHealthcheckCatalog extends HTMLElement {
+  async connectedCallback() { this.attachShadow({ mode: "open" }).innerHTML = `<style>${styles}</style><section class="card"><h2>Healthchecks</h2><p class="status">Loading…</p><div class="list" hidden></div></section>`; try { const response = await fetch("/api/admin/healthchecks", { credentials: "same-origin" }); if (!response.ok) throw new Error("Unable to load healthchecks."); const items = (await response.json()).healthchecks || []; const list = this.shadowRoot.querySelector(".list"); list.replaceChildren(...items.map((item) => { const row = document.createElement("div"); row.textContent = `${item.display_name} — ${item.feature}/${item.component}: ${item.state}`; list.append(row); return row; })); list.hidden = false; this.shadowRoot.querySelector(".status").textContent = `${items.length} healthcheck${items.length === 1 ? "" : "s"}`; } catch (error) { this.shadowRoot.querySelector(".status").textContent = error.message; } }
+}
+
+export class CfCircuitBreakerCatalog extends HTMLElement {
+  async connectedCallback() { this.attachShadow({ mode: "open" }).innerHTML = `<style>${styles}</style><section class="card"><h2>Circuit breakers</h2><p class="status">Loading…</p><div class="list" hidden></div></section>`; try { const response = await fetch("/api/admin/circuit-breakers", { credentials: "same-origin" }); if (!response.ok) throw new Error("Unable to load circuit breakers."); const items = (await response.json()).circuit_breakers || []; const list = this.shadowRoot.querySelector(".list"); list.replaceChildren(...items.map((item) => { const row = document.createElement("div"); row.textContent = `${item.display_name} — ${item.feature}/${item.name}: ${item.state}`; list.append(row); return row; })); list.hidden = false; this.shadowRoot.querySelector(".status").textContent = `${items.length} circuit breaker${items.length === 1 ? "" : "s"}`; } catch (error) { this.shadowRoot.querySelector(".status").textContent = error.message; } }
+}
+
+if (!customElements.get("cf-healthcheck-catalog")) customElements.define("cf-healthcheck-catalog", CfHealthcheckCatalog);
+if (!customElements.get("cf-circuit-breaker-catalog")) customElements.define("cf-circuit-breaker-catalog", CfCircuitBreakerCatalog);