@agilesyndrome/cf-genai-base 0.1.5 → 1.0.0

package/CONTRACT.md

@@ -4,7 +4,7 @@ Every site built from this foundation follows the same edge contract.
 
 ## Worker entrypoint
 
-`createWorker({ fetch, features?, middleware?, auth?, scheduled?, security? })` owns the Worker lifecycle. Features run in declaration order and may call `next()` or return a response. The site router owns pages, APIs, D1 queries, and R2 object keys. `scheduled`
+`createWorker({ fetch, features?, middleware?, auth?, authorize?, scheduled?, security? })` owns the Worker lifecycle and reserved admin boundary. Features run in declaration order and may call `next()` or return a response. The site router owns pages, APIs, D1 queries, and R2 object keys. `scheduled`
 is optional and must use `ctx.waitUntil` for background work.
 
 ## Routes
@@ -12,7 +12,12 @@ is optional and must use `ctx.waitUntil` for background work.
 - `GET /health` returns `{ ok, version, build_number }` and is cache-disabled.
 - `GET /api/me` returns `{ user: null | { sub, email, name, ...roles } }`.
 - `/auth/login`, `/auth/callback`, and `/auth/logout` are reserved for auth.
-- Public APIs must be explicitly listed in auth configuration.
+- `/admin` and `/admin/*` are browser admin routes; `/api/admin` and `/api/admin/*` are admin API routes.
+- Admin routes use `AUTH_STRATEGY`; omitted or empty means `http_basic`. Basic auth accepts username `admin` and the value of `ADMIN_TOKEN` (with `admin_token` supported for compatibility). Missing token means all admin routes return 401.
+- `AUTH_STRATEGY=oauth` delegates identity establishment to the configured auth provider and uses `authorize` for admin policy.
+- `scopes` registers an application scope manifest. `scopeRoutes` associates route prefixes or match functions with required scopes.
+- Base provides `/api/admin/users`, `/api/admin/scopes`, and `/api/admin/users/:id/scopes` for platform administrators when the authorization migration is installed.
+- Public APIs must be explicitly listed in provider-specific auth configuration.
 - Mutating `/api/*` requests require a same-origin `Origin` header.
 
 ## Environment and bindings
@@ -32,6 +37,10 @@ Standard bindings:
 
 Build metadata is optional: `BUILD_SHA` and `BUILD_NUMBER`.
 
+The package includes `migrations/0001_authorization.sql`; each site must apply
+the equivalent migration to its own D1 database before enabling the generic
+user/scope APIs.
+
 D1 migrations are committed with the site, applied by Wrangler, and are the
 source of truth for schema changes. R2 stores binary data; metadata and access
 control remain in D1.

package/README.md

@@ -2,11 +2,17 @@
 
 Opinionated startup boilerplate for small Cloudflare Workers.
 
-The base is deliberately small: a site still owns its router, HTML, D1
-queries, R2 keys, and scheduled jobs. `createWorker` composes ordered feature middleware, normalizes uncaught failures, and applies baseline response headers.
+The base owns the shared security boundary as well as Worker lifecycle concerns. It reserves `/admin` and `/api/admin` routes, authenticates them using `AUTH_STRATEGY` (default `http_basic`, or `oauth` when an auth provider is supplied), and applies the optional `authorize` policy. Sites still own their router, HTML, D1 queries, R2 keys, and scheduled jobs.
 Use D1 bindings for durable application data and R2 bindings for binary assets;
 do not put either into module-level state.
 
+Base also provides provider-neutral authorization helpers and browser components
+through `@agilesyndrome/cf-genai-base/authorization` and
+`@agilesyndrome/cf-genai-base/ui`. Applications declare their scope manifest,
+while base owns the user, scope, and grant records plus the generic user-access
+API. The UI components are themeable with CSS custom properties and do not
+contain application-specific components.
+
 ```js
 import { createWorker, healthResponse } from "@agilesyndrome/cf-genai-base";
 
@@ -27,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/0001_authorization.sql

@@ -0,0 +1,32 @@
+CREATE TABLE IF NOT EXISTS auth_users (
+  id TEXT PRIMARY KEY,
+  provider TEXT NOT NULL,
+  subject TEXT NOT NULL,
+  email TEXT NOT NULL DEFAULT '',
+  display_name TEXT NOT NULL DEFAULT '',
+  is_admin INTEGER NOT NULL DEFAULT 0 CHECK (is_admin IN (0,1)),
+  created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  updated_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  UNIQUE(provider, subject)
+);
+
+CREATE INDEX IF NOT EXISTS auth_users_email_idx ON auth_users(email COLLATE NOCASE);
+
+CREATE TABLE IF NOT EXISTS auth_scopes (
+  name TEXT PRIMARY KEY,
+  label TEXT NOT NULL,
+  description TEXT NOT NULL DEFAULT '',
+  system INTEGER NOT NULL DEFAULT 0 CHECK (system IN (0,1)),
+  created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  updated_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE TABLE IF NOT EXISTS auth_user_scopes (
+  user_id TEXT NOT NULL REFERENCES auth_users(id) ON DELETE CASCADE,
+  scope_name TEXT NOT NULL REFERENCES auth_scopes(name) ON DELETE CASCADE,
+  granted_by TEXT,
+  granted_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  PRIMARY KEY (user_id, scope_name)
+);
+
+CREATE INDEX IF NOT EXISTS auth_user_scopes_scope_idx ON auth_user_scopes(scope_name);

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,9 +1,13 @@
 {
   "name": "@agilesyndrome/cf-genai-base",
-  "version": "0.1.5",
+  "version": "1.0.0",
   "type": "module",
   "exports": {
-    ".": "./src/index.js"
+    ".": "./src/index.js",
+    "./authorization": "./src/authorization.js",
+    "./core": "./src/core.js",
+    "./ui": "./src/ui/index.js",
+    "./ui/styles.css": "./src/ui/styles.css"
   },
   "description": "Lean Worker lifecycle and security helpers for Cloudflare sites.",
   "license": "MIT",
@@ -13,6 +17,7 @@
   },
   "files": [
     "src",
+    "migrations",
     "README.md",
     "CONTRACT.md",
     "LICENSE"
@@ -24,7 +29,7 @@
   "homepage": "https://github.com/agilesyndrome/cf-genai-base#readme",
   "scripts": {
     "check": "node --check src/index.js",
-    "test": "node --check src/index.js",
+    "test": "node --test tests/*.test.mjs",
     "build": "npm run check && npm test && npm pack --dry-run"
   }
 }

package/src/authorization.js

@@ -0,0 +1,79 @@
+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";
+
+export function normalizeScopes(scopes = []) {
+  return scopes.map((scope) => typeof scope === "string" ? { name: scope, label: scope, description: "", system: false } : scope)
+    .filter((scope) => scope && /^[a-z0-9]+(?::[a-z0-9-]+)+$/.test(String(scope.name || "")))
+    .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 = [], { who = "system:read" } = {}) {
+  if (!env?.DB) return;
+  const db = createD1(env, { who });
+  for (const scope of normalizeScopes(scopes)) {
+    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, { 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 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 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 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, { who = "system:read" } = {}) {
+  const db = createD1(env, { who });
+  if (user?.auth_strategy === "http_basic") return true;
+  const authUser = await ensureUser(env, user, { who });
+  if (!authUser) return false;
+  if (Boolean(authUser.is_admin)) return true;
+  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, { 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, { 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, { 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, { 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 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;
+}
+
+async function stableId(value) {
+  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(value));
+  return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, "0")).join("").slice(0, 32);
+}

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 db.batch(statements);
+    },
+  };
+}
+
+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

@@ -2,9 +2,14 @@
  * Lean, opinionated Worker composition for Cloudflare sites.
  * Site code owns domain routes and data; this owns lifecycle and edge concerns.
  */
-export function createWorker({ fetch, scheduled, auth, middleware = [], features = [], health, boot, metrics, security = true }) {
+import { ensureScopes, ensureUser, hasScope, listAuthorizationScopes, listAuthorizationUsers, listUserGrants, replaceUserGrants } from "./authorization.js";
+import { getCircuitBreaker, 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");
   const chain = [
+    (request, env, ctx, next, state) => adminBoundary(request, env, ctx, next, state, { provider, authorize, scopes, scopeRoutes }),
     ...features.flatMap((feature) => feature?.middleware ? [feature.middleware.bind(feature)] : []),
     ...middleware,
     ...(auth ? [(request, env, ctx, next) => auth(request, env, ctx, next)] : []),
@@ -15,12 +20,14 @@ export function createWorker({ fetch, scheduled, auth, middleware = [], features
         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" }).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);
           }
@@ -39,6 +46,94 @@ export function createWorker({ fetch, scheduled, auth, middleware = [], features
   };
 }
 
+
+async function adminBoundary(request, env, ctx, next, state, { provider, authorize, scopes, scopeRoutes }) {
+  const url = new URL(request.url);
+  if (!isAdminPath(url.pathname)) return next(request);
+  const strategy = String(env?.AUTH_STRATEGY || "http_basic").trim().toLowerCase();
+  if (strategy === "http_basic") {
+    const user = basicUser(request, env);
+    if (!user) return adminUnauthorized(request);
+    state.user = user;
+  } else if (strategy === "oauth") {
+    const user = provider?.getUser ? await provider.getUser(request, env) : null;
+    if (!user) return oauthUnauthorized(request, url);
+    state.user = user;
+  } else {
+    return new Response("Unsupported AUTH_STRATEGY", { status: 500, headers: { "Cache-Control": "no-store" } });
+  }
+  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, { 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" } });
+  }
+  const platformResponse = await authorizationApi(request, env, url, state);
+  return platformResponse || next(request);
+}
+
+function requiredScopeFor(pathname, routes) {
+  const route = routes.find((entry) => typeof entry.match === "function" ? entry.match(pathname) : pathname === entry.path || pathname.startsWith(String(entry.path || "") + "/"));
+  return route && route.scope ? route.scope : null;
+}
+
+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" || 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, { 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, { who: requestActor(state) });
+    return Response.json({ grants });
+  }
+  return null;
+}
+
+function isAdminPath(pathname) {
+  return pathname === "/admin" || pathname.startsWith("/admin/") || pathname === "/api/admin" || pathname.startsWith("/api/admin/");
+}
+
+function basicUser(request, env) {
+  const token = String(env?.ADMIN_TOKEN || env?.admin_token || "");
+  if (!token) return null;
+  const header = request.headers.get("Authorization") || "";
+  if (!header.toLowerCase().startsWith("basic ")) return null;
+  let decoded;
+  try { decoded = atob(header.slice(6).trim()); } catch { return null; }
+  const separator = decoded.indexOf(":");
+  if (separator < 0) return null;
+  if (!constantTimeEqual(decoded.slice(0, separator), "admin") || !constantTimeEqual(decoded.slice(separator + 1), token)) return null;
+  return { sub: "basic:admin", email: "", name: "admin", roles: ["admin"], auth_strategy: "http_basic" };
+}
+
+function adminUnauthorized(request) {
+  const headers = { "Cache-Control": "no-store", "WWW-Authenticate": "Basic realm=\"admin\", charset=\"UTF-8\"" };
+  return new URL(request.url).pathname.startsWith("/api/") ? Response.json({ error: "Authentication is required." }, { status: 401, headers }) : new Response("Authentication is required.", { status: 401, headers });
+}
+
+function oauthUnauthorized(request, url) {
+  if (url.pathname.startsWith("/api/")) return Response.json({ error: "Authentication is required." }, { status: 401, headers: { "Cache-Control": "no-store" } });
+  return Response.redirect(url.origin + "/auth/login?return_to=" + encodeURIComponent(safeReturnTo(url.pathname + url.search)), 302);
+}
+
+function safeReturnTo(value) { return value?.startsWith("/") && !value.startsWith("//") && !value.startsWith("/auth/") ? value : "/"; }
+function constantTimeEqual(a, b) { const aa = new TextEncoder().encode(a), bb = new TextEncoder().encode(b); let n = aa.length ^ bb.length; for (let i = 0; i < Math.max(aa.length, bb.length); i++) n |= (aa[i] || 0) ^ (bb[i] || 0); return n === 0; }
+
 export function validateBoot(env, { bindings = [], required = [] } = {}) {
   const missingBindings = bindings.filter((name) => !env?.[name]);
   const missingValues = required.filter((name) => !env?.[name] || String(env[name]).startsWith("replace-with-"));

package/src/ui/index.js

@@ -0,0 +1,62 @@
+const styles = `:host { --cf-ui-bg:#fff; --cf-ui-surface:#f7f7f5; --cf-ui-text:#20231f; --cf-ui-muted:#687067; --cf-ui-border:#d8ddd5; --cf-ui-primary:#2f6f52; color:var(--cf-ui-text); font:15px/1.45 system-ui,sans-serif } *,*::before,*::after{box-sizing:border-box}.shell{display:grid;gap:1rem}.nav{display:flex;flex-wrap:wrap;gap:.5rem;border-bottom:1px solid var(--cf-ui-border);padding-bottom:.75rem}.nav a{color:var(--cf-ui-text);padding:.45rem .7rem;border-radius:.4rem;text-decoration:none}.nav a:hover,.nav a[aria-current=page]{background:var(--cf-ui-surface);color:var(--cf-ui-primary)}.card{background:var(--cf-ui-bg);border:1px solid var(--cf-ui-border);border-radius:.6rem;padding:1rem;overflow:auto}table{width:100%;border-collapse:collapse}th,td{padding:.65rem;border-bottom:1px solid var(--cf-ui-border);text-align:left;vertical-align:top}th{color:var(--cf-ui-muted);font-size:.8rem;text-transform:uppercase;letter-spacing:.04em}button{border:1px solid var(--cf-ui-border);border-radius:.4rem;background:var(--cf-ui-bg);color:inherit;padding:.45rem .65rem;cursor:pointer}.scope-list{display:grid;gap:.3rem;min-width:14rem}.scope-list label{display:flex;gap:.4rem;align-items:center}.status{color:var(--cf-ui-muted);min-height:1.4em}`;
+
+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><a href="/admin/healthchecks">Healthchecks</a><a href="/admin/circuit-breakers">Circuit breakers</a></nav><slot></slot></div>`;
+  }
+}
+
+export class CfScopeBadge extends HTMLElement {
+  connectedCallback() { this.attachShadow({ mode: "open" }).innerHTML = `<style>${styles}.badge{display:inline-block;border:1px solid var(--cf-ui-border);border-radius:999px;padding:.15rem .5rem;color:var(--cf-ui-primary);background:var(--cf-ui-surface);font-size:.85rem}</style><span class="badge" part="badge"></span>`; this.shadowRoot.querySelector(".badge").textContent = this.getAttribute("scope") || this.textContent || ""; }
+}
+
+export class CfUserManagement extends HTMLElement {
+  async connectedCallback() { this.attachShadow({ mode: "open" }).innerHTML = `<style>${styles}</style><section class="card" part="panel"><h2>User access</h2><p class="status" part="status">Loading users and scopes…</p><table hidden part="table"><thead><tr><th>User</th><th>Scopes</th><th>Save</th></tr></thead><tbody></tbody></table></section>`; try { await this.load(); } catch (error) { this.status.textContent = error.message || "Unable to load access data."; } }
+  get status() { return this.shadowRoot.querySelector(".status"); }
+  async load() { const [usersResponse, scopesResponse] = await Promise.all([fetch("/api/admin/users", { credentials: "same-origin" }), fetch("/api/admin/scopes", { credentials: "same-origin" })]); if (!usersResponse.ok || !scopesResponse.ok) throw new Error("Unable to load user access."); const users = (await usersResponse.json()).users || []; const scopes = (await scopesResponse.json()).scopes || []; const body = this.shadowRoot.querySelector("tbody"); body.replaceChildren(...users.map((user) => this.row(user, scopes))); this.shadowRoot.querySelector("table").hidden = false; this.status.textContent = `${users.length} user${users.length === 1 ? "" : "s"}`; }
+  row(user, scopes) { const row = document.createElement("tr"); const identity = document.createElement("td"); identity.textContent = `${user.display_name || user.email || "Unnamed user"} (${user.email || "no email"})`; const grants = document.createElement("td"); const list = document.createElement("div"); list.className = "scope-list"; for (const scope of scopes) { const label = document.createElement("label"); const input = document.createElement("input"); input.type = "checkbox"; input.value = scope.name; input.checked = Boolean((user.scopes || []).includes(scope.name)); label.append(input, document.createTextNode(scope.label || scope.name)); list.append(label); } grants.append(list); const action = document.createElement("td"); const button = document.createElement("button"); button.textContent = "Save"; button.addEventListener("click", async () => { button.disabled = true; const selected = [...list.querySelectorAll("input:checked")].map((input) => input.value); const response = await fetch(`/api/admin/users/${encodeURIComponent(user.id)}/scopes`, { method: "PUT", credentials: "same-origin", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ scopes: selected }) }); button.disabled = false; this.status.textContent = response.ok ? "Access saved." : "Unable to save access."; }); action.append(button); row.append(identity, grants, action); return row; }
+}
+
+if (!customElements.get("cf-admin-shell")) customElements.define("cf-admin-shell", CfAdminShell);
+if (!customElements.get("cf-scope-badge")) customElements.define("cf-scope-badge", CfScopeBadge);
+if (!customElements.get("cf-user-management")) customElements.define("cf-user-management", CfUserManagement);
+
+export class CfScopeCatalog extends HTMLElement {
+  async connectedCallback() {
+    this.attachShadow({ mode: "open" }).innerHTML = `<style>${styles}</style><section class="card" part="panel"><h2>Available scopes</h2><p class="status" part="status">Loading scopes…</p><div class="scope-list" hidden part="list"></div></section>`;
+    try {
+      const response = await fetch("/api/admin/scopes", { credentials: "same-origin" });
+      if (!response.ok) throw new Error("Unable to load scopes.");
+      const scopes = (await response.json()).scopes || [];
+      const list = this.shadowRoot.querySelector(".scope-list");
+      list.replaceChildren(...scopes.map((scope) => {
+        const item = document.createElement("div");
+        const badge = document.createElement("cf-scope-badge");
+        badge.setAttribute("scope", scope.name);
+        const description = document.createElement("span");
+        description.textContent = scope.description || scope.label || scope.name;
+        item.append(badge, description);
+        return item;
+      }));
+      list.hidden = false;
+      this.shadowRoot.querySelector(".status").textContent = `${scopes.length} scope${scopes.length === 1 ? "" : "s"}`;
+    } catch (error) {
+      this.shadowRoot.querySelector(".status").textContent = error.message || "Unable to load scopes.";
+    }
+  }
+}
+
+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);

package/src/ui/styles.css

@@ -0,0 +1,9 @@
+:root {
+  --cf-ui-bg: #ffffff;
+  --cf-ui-surface: #f7f7f5;
+  --cf-ui-text: #20231f;
+  --cf-ui-muted: #687067;
+  --cf-ui-border: #d8ddd5;
+  --cf-ui-primary: #2f6f52;
+  --cf-ui-danger: #a33b32;
+}