@agilesyndrome/cf-genai-base 4.1.2 → 5.0.0

package/src/auth/subscriptions.js

@@ -0,0 +1,25 @@
+import { createD1 } from "../core/d1.js";
+import { deepEqual, parseJsonValue } from "./encoding.js";
+import { SubscriptionError } from "./constants.js";
+
+export async function listTenantSubscriptions(env, tenantId, { who = "system:read" } = {}) {
+  const { results } = await createD1(env, { who }).prepare("SELECT s.id,s.name,s.created_at,s.updated_at FROM auth_subscriptions s JOIN auth_tenant_subscriptions ts ON ts.subscription_id=s.id WHERE ts.tenant_id=? ORDER BY s.name COLLATE NOCASE").bind(tenantId).all();
+  return Promise.all((results || []).map(async (subscription) => ({ ...subscription, entitlements: await listSubscriptionEntitlements(env, subscription.id, { who }) })));
+}
+
+export async function listSubscriptionEntitlements(env, subscriptionId, { who = "system:read" } = {}) {
+  const { results } = await createD1(env, { who }).prepare("SELECT entitlement,value_json FROM auth_subscription_entitlements WHERE subscription_id=? ORDER BY entitlement").bind(subscriptionId).all();
+  return (results || []).map((row) => ({ entitlement: row.entitlement, value: parseJsonValue(row.value_json) }));
+}
+
+export function normalizeSubscriptionManifest(manifest = []) { return manifest.map((subscription) => ({ id: String(subscription?.id || "").trim(), name: String(subscription?.name || subscription?.id || "").trim(), entitlements: Object.fromEntries(Object.entries(subscription?.entitlements || {}).map(([key, value]) => [String(key), value])) })).filter((subscription) => /^[a-z0-9][a-z0-9_-]*$/.test(subscription.id) && subscription.name); }
+
+export async function ensureSubscriptionManifest(env, manifest = [], { who = "system:update" } = {}) {
+  if (!env?.DB) return; const db = createD1(env, { who });
+  for (const subscription of normalizeSubscriptionManifest(manifest)) { await db.prepare("INSERT INTO auth_subscriptions (id,name) VALUES (?,?) ON CONFLICT(id) DO UPDATE SET name=excluded.name,updated_at=CURRENT_TIMESTAMP").bind(subscription.id, subscription.name).run(); for (const [entitlement, value] of Object.entries(subscription.entitlements)) await db.prepare("INSERT INTO auth_subscription_entitlements (subscription_id,entitlement,value_json) VALUES (?,?,?) ON CONFLICT(subscription_id,entitlement) DO UPDATE SET value_json=excluded.value_json,updated_at=CURRENT_TIMESTAMP").bind(subscription.id, entitlement, JSON.stringify(value)).run(); }
+}
+
+export async function hasSubscription(env, tenantId, subscriptionId, { who = "system:read" } = {}) { return Boolean(await createD1(env, { who }).prepare("SELECT 1 FROM auth_tenant_subscriptions WHERE tenant_id=? AND subscription_id=?").bind(tenantId, subscriptionId).first()); }
+export async function requireSubscription(env, tenantId, subscriptionId, { who = "system:read" } = {}) { if (!await hasSubscription(env, tenantId, subscriptionId, { who })) throw new SubscriptionError("Required subscription is not active for this tenant."); return true; }
+export async function hasEntitlement(env, tenantId, entitlement, expectedValue, { who = "system:read" } = {}) { const rows = await createD1(env, { who }).prepare("SELECT e.value_json FROM auth_subscription_entitlements e JOIN auth_tenant_subscriptions ts ON ts.subscription_id=e.subscription_id WHERE ts.tenant_id=? AND e.entitlement=?").bind(tenantId, entitlement).all(); return (rows.results || []).some((row) => expectedValue === undefined || deepEqual(parseJsonValue(row.value_json), expectedValue)); }
+export async function requireEntitlement(env, tenantId, entitlement, expectedValue, { who = "system:read" } = {}) { if (!await hasEntitlement(env, tenantId, entitlement, expectedValue, { who })) throw new SubscriptionError(`Required entitlement is not active: ${entitlement}.`); return true; }

package/src/auth/tenants.js

@@ -0,0 +1,34 @@
+import { createD1 } from "../core/d1.js";
+
+export async function listUserTenants(env, userId, { who = "system:read" } = {}) {
+  const { results } = await createD1(env, { who }).prepare("SELECT t.id,t.name,t.created_at,t.updated_at FROM auth_tenants t JOIN auth_user_tenants ut ON ut.tenant_id=t.id WHERE ut.user_id=? ORDER BY t.name COLLATE NOCASE").bind(userId).all();
+  return results || [];
+}
+
+export async function listAuthorizationTenants(env, { who = "system:read" } = {}) {
+  const { results } = await createD1(env, { who }).prepare("SELECT t.id,t.name,t.created_at,t.updated_at,COUNT(ut.user_id) AS user_count FROM auth_tenants t LEFT JOIN auth_user_tenants ut ON ut.tenant_id=t.id GROUP BY t.id ORDER BY t.name COLLATE NOCASE").all();
+  return results || [];
+}
+
+export async function getAuthorizationTenant(env, tenantId, { who = "system:read" } = {}) { return createD1(env, { who }).prepare("SELECT id,name,created_at,updated_at FROM auth_tenants WHERE id=?").bind(String(tenantId)).first(); }
+
+export async function createAuthorizationTenant(env, tenantId, name, { who = "system:update" } = {}) {
+  const id = String(tenantId || "").trim(); const tenantName = String(name || "").trim();
+  if (!/^[a-z0-9][a-z0-9_-]*$/.test(id)) throw new Error("Tenant id must contain lowercase letters, numbers, hyphens, or underscores.");
+  if (!tenantName) throw new Error("Tenant name is required.");
+  await createD1(env, { who }).prepare("INSERT INTO auth_tenants (id,name) VALUES (?,?)").bind(id, tenantName).run();
+  return getAuthorizationTenant(env, id, { who });
+}
+
+export async function updateAuthorizationTenant(env, tenantId, name, { who = "system:update" } = {}) {
+  const tenantName = String(name || "").trim(); if (!tenantName) throw new Error("Tenant name is required.");
+  await createD1(env, { who }).prepare("UPDATE auth_tenants SET name=?,updated_at=CURRENT_TIMESTAMP WHERE id=?").bind(tenantName, String(tenantId)).run();
+  return getAuthorizationTenant(env, tenantId, { who });
+}
+
+export async function replaceUserTenants(env, userId, tenantIds, { who = "system:update" } = {}) {
+  const db = createD1(env, { who }); const requested = [...new Set((tenantIds || []).map((id) => String(id).trim()).filter(Boolean))];
+  if (requested.length) { const placeholders = requested.map(() => "?").join(","); const { results } = await db.prepare(`SELECT id FROM auth_tenants WHERE id IN (${placeholders})`).bind(...requested).all(); const found = new Set((results || []).map((row) => row.id)); if (found.size !== requested.length) throw new Error("One or more tenants do not exist."); }
+  await db.batch([db.prepare("DELETE FROM auth_user_tenants WHERE user_id=?").bind(userId), ...requested.map((tenantId) => db.prepare("INSERT INTO auth_user_tenants (user_id,tenant_id) VALUES (?,?)").bind(userId, tenantId))]);
+  return listUserTenants(env, userId, { who });
+}

package/src/auth/users.js

@@ -0,0 +1,31 @@
+import { createD1 } from "../core/d1.js";
+import { AUTH_GRANT_TABLE, AUTH_USER_TABLE, DEFAULT_TENANT_ID, DEFAULT_TENANT_NAME } from "./constants.js";
+import { listUserGrants } from "./scopes.js";
+import { listUserTenants } from "./tenants.js";
+
+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();
+  if (existing) { await db.prepare(`UPDATE ${AUTH_USER_TABLE} SET email=?,display_name=?,updated_at=CURRENT_TIMESTAMP WHERE id=?`).bind(email, String(user.name || email || subject), existing.id).run(); await ensureDefaultTenantMembership(db, existing.id); return { ...existing, email, display_name: String(user.name || email || subject), is_admin: Boolean(existing.is_admin) }; }
+  const id = await stableId(`${provider}:${subject}`);
+  await db.prepare(`INSERT INTO ${AUTH_USER_TABLE} (id,provider,subject,email,display_name,is_admin) VALUES (?,?,?,?,?,0) ON CONFLICT(provider,subject) DO NOTHING`).bind(id, provider, subject, email, String(user.name || email || subject)).run();
+  await ensureDefaultTenantMembership(db, id);
+  return db.prepare(`SELECT * FROM ${AUTH_USER_TABLE} WHERE id=?`).bind(id).first();
+}
+
+async function ensureDefaultTenantMembership(db, userId) { await db.batch([db.prepare("INSERT OR IGNORE INTO auth_tenants (id,name) VALUES (?,?)").bind(DEFAULT_TENANT_ID, DEFAULT_TENANT_NAME), db.prepare("INSERT OR IGNORE INTO auth_user_tenants (user_id,tenant_id) VALUES (?,?)").bind(userId, DEFAULT_TENANT_ID)]); }
+
+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 = user?.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 { results } = await createD1(env, { who }).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), tenants: await listUserTenants(env, user.id, { who }) })));
+}
+
+export async function getAuthorizationUser(env, userId, { who = "system:read" } = {}) { return createD1(env, { who }).prepare(`SELECT id,email,display_name,provider,subject,is_admin,created_at,updated_at FROM ${AUTH_USER_TABLE} WHERE id=?`).bind(userId).first(); }
+
+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 → core/circuits.js}

@@ -1,54 +1,46 @@
-export const HEALTHCHECK_STATES = ["red", "yellow", "green"];
-export const CIRCUIT_BREAKER_STATES = ["off", "tripped", "on"];
-export const HEALTHCHECK_MODES = ["any", "all"];
-export const BASE_PACKAGE_NAME = "@agilesyndrome/cf-genai-base";
-export const BASE_VERSION = "4.1.1";
-
-export function eventLog(level, event, details = {}) {
-  const method = ["debug", "info", "warn", "error"].includes(level) ? level : "info";
-  console[method](`[EventLog] ${event}`, details);
+import { auditLog, eventLog } from "./events.js";
+import { createD1 } from "./d1.js";
+import { secureJson } from "./security.js";
+import { BASE_PACKAGE_NAME, BASE_VERSION, CIRCUIT_BREAKER_STATES, HEALTHCHECK_MODES, HEALTHCHECK_STATES } from "./constants.js";
+
+export async function featureCircuit(env, id, who = "system:read") {
+  return getCircuitBreaker(env, id, { who }).catch((error) => {
+    eventLog("error", "feature.circuit.read.failed", { breaker: id, errorName: error?.name || "Error", errorMessage: String(error?.message || "Unknown circuit breaker error").slice(0, 300) });
+    void env?.event?.("feature.circuit.read.failed", "feature", { breaker: id, who, errorName: error?.name || "Error" });
+    return null;
+  });
 }
 
-export function auditLog({ who = "system", operation, resource, details = {} }) {
-  console.info(`[AuditLog] ${who}:${operation} ${resource}`, details);
-}
+export async function featureAvailable(env, id, who = "system:read") { return (await featureCircuit(env, id, who))?.state === "on"; }
 
-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 async function requireFeatureCircuit(env, { feature, breakerId, operation, requestId, who, message = "The requested feature is unavailable." }) {
+  const breaker = await featureCircuit(env, breakerId, who || "system:read");
+  if (breaker?.state === "on") return breaker;
+  const details = { feature, breaker: breakerId, state: breaker?.state || "missing", operation, requestId: requestId || null };
+  eventLog("warn", "feature.request.blocked", details);
+  auditLog({ who: who || "system:read", operation: "blocked", resource: `feature:${feature}`, details });
+  await env?.event?.("feature.request.blocked", "feature", { ...details, who: who || "system:read" });
+  throw Object.assign(new Error(message), { status: 503, code: "feature_circuit_unavailable", feature, breakerId, circuitState: breaker?.state || "missing" });
 }
 
-export function createD1(env, { who = "system:read" } = {}) {
-  if (!env?.DB) throw new Error("A DB binding is required");
-  const db = env.DB;
+export function createAvailabilityFeature({ name = "base", breakerId = `${name}:site-available`, displayName = "Site availability", publicPaths = ["/health", "/api/health"] } = {}) {
   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()));
+    name,
+    packageName: BASE_PACKAGE_NAME,
+    version: BASE_VERSION,
+    healthcheck: async () => ({ feature: name, component: "site-available", displayName, state: "green", metadata: { endpoint: "/health", expectedStatus: 200 } }),
+    circuitBreakers: [{ id: breakerId, name: "site-available", displayName, state: "on", allowSelfHealing: false, healthchecks: [`${name}:site-available`] }],
+    async middleware(request, env, ctx, next) {
+      const pathname = new URL(request.url).pathname;
+      if (publicPaths.some((path) => pathname === path || pathname.startsWith(`${path}/`))) return next(request);
+      const breaker = await featureCircuit(env, breakerId, "system:read");
+      if (breaker?.state === "on") return next(request);
+      await env.event?.("feature.maintenance", "availability", { feature: name, breaker: breakerId, state: breaker?.state || "missing", pathname, method: request.method });
+      return secureJson({ error: "The site is temporarily unavailable." }, 503);
     },
   };
 }
 
-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");
@@ -66,19 +58,15 @@ export function normalizeCircuitBreaker(input = {}) {
 }
 
 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}`);
+  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();
+  const item = await getHealthcheck(env, id, { who }); if (!item) return null;
+  await createD1(env, { who }).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 });
 }
@@ -87,22 +75,18 @@ export async function getHealthcheck(env, id, { who = "system:read" } = {}) { re
 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}`);
+  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 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;
+  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();
@@ -111,27 +95,18 @@ export async function setCircuitBreaker(env, id, state, { who = "system:read", a
 }
 
 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 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)));
+  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 = [];
+    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 });
@@ -139,43 +114,21 @@ export async function registerFeatureManifests(env, features = [], { who = "syst
 }
 
 export async function listFeatureHealth(env, { who = "system:read" } = {}) {
-  const checks = await listHealthchecks(env, { who });
-  const severity = { green: 0, yellow: 1, red: 2 };
-  const features = {};
+  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));
 }
 
-
 export function normalizeFeatureManifest(feature = {}) {
-  const source = feature && typeof feature === "object" ? feature : {};
-  const manifest = source.manifest && typeof source.manifest === "object" ? source.manifest : source;
-  const name = String(source.name || source.id || manifest.name || "feature");
-  const packageName = source.packageName || source.package_name || source.package || manifest.packageName || manifest.package_name || manifest.package;
-  const version = source.version || source.packageVersion || source.package_version || manifest.version;
-  return {
-    feature: name,
-    display_name: String(source.displayName || source.display_name || manifest.displayName || manifest.display_name || name),
-    package_name: packageName ? String(packageName) : null,
-    version: version ? String(version) : null,
-  };
+  const source = feature && typeof feature === "object" ? feature : {}; const manifest = source.manifest && typeof source.manifest === "object" ? source.manifest : source; const name = String(source.name || source.id || manifest.name || "feature"); const packageName = source.packageName || source.package_name || source.package || manifest.packageName || manifest.package_name || manifest.package; const version = source.version || source.packageVersion || source.package_version || manifest.version;
+  return { feature: name, display_name: String(source.displayName || source.display_name || manifest.displayName || manifest.display_name || name), package_name: packageName ? String(packageName) : null, version: version ? String(version) : null };
 }
 
 export async function listFeatureCatalog(env, features = [], { who = "system:read" } = {}) {
-  const [healthchecks, circuitBreakers] = await Promise.all([listHealthchecks(env, { who }), listCircuitBreakers(env, { who })]);
-  const manifests = new Map([["base", { feature: "base", display_name: "Base platform", package_name: BASE_PACKAGE_NAME, version: BASE_VERSION }]]);
-  for (const feature of features) {
-    const manifest = normalizeFeatureManifest(feature);
-    manifests.set(manifest.feature, manifest);
-  }
+  const [healthchecks, circuitBreakers] = await Promise.all([listHealthchecks(env, { who }), listCircuitBreakers(env, { who })]); const manifests = new Map([["base", { feature: "base", display_name: "Base platform", package_name: BASE_PACKAGE_NAME, version: BASE_VERSION }]]);
+  for (const feature of features) { const manifest = normalizeFeatureManifest(feature); manifests.set(manifest.feature, manifest); }
   for (const item of healthchecks) if (!manifests.has(item.feature)) manifests.set(item.feature, normalizeFeatureManifest({ name: item.feature }));
   for (const item of circuitBreakers) if (!manifests.has(item.feature)) manifests.set(item.feature, normalizeFeatureManifest({ name: item.feature }));
-  const severity = { green: 0, yellow: 1, red: 2 };
-  const state = (items) => items.reduce((current, item) => severity[item.state] > severity[current] ? item.state : current, "green");
-  return [...manifests.values()].sort((a, b) => a.feature.localeCompare(b.feature)).map((manifest) => {
-    const featureHealthchecks = healthchecks.filter((item) => item.feature === manifest.feature);
-    const featureBreakers = circuitBreakers.filter((item) => item.feature === manifest.feature);
-    const rollup = featureBreakers.find((item) => item.name === "rollup") || null;
-    return { ...manifest, health: featureHealthchecks.length ? state(featureHealthchecks) : "yellow", healthchecks: featureHealthchecks, circuit_breakers: featureBreakers, circuit_breaker: rollup };
-  });
+  const severity = { green: 0, yellow: 1, red: 2 }; const state = (items) => items.reduce((current, item) => severity[item.state] > severity[current] ? item.state : current, "green");
+  return [...manifests.values()].sort((a, b) => a.feature.localeCompare(b.feature)).map((manifest) => { const featureHealthchecks = healthchecks.filter((item) => item.feature === manifest.feature); const featureBreakers = circuitBreakers.filter((item) => item.feature === manifest.feature); const rollup = featureBreakers.find((item) => item.name === "rollup") || null; return { ...manifest, health: featureHealthchecks.length ? state(featureHealthchecks) : "yellow", healthchecks: featureHealthchecks, circuit_breakers: featureBreakers, circuit_breaker: rollup }; });
 }

package/src/core/constants.js

@@ -0,0 +1,5 @@
+export const HEALTHCHECK_STATES = ["red", "yellow", "green"];
+export const CIRCUIT_BREAKER_STATES = ["off", "tripped", "on"];
+export const HEALTHCHECK_MODES = ["any", "all"];
+export const BASE_PACKAGE_NAME = "@agilesyndrome/cf-genai-base";
+export const BASE_VERSION = "4.1.3";

package/src/core/d1.js

@@ -0,0 +1,54 @@
+import { auditLog, eventLog } from "./events.js";
+
+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()));
+    },
+  };
+}
+
+export function auditedD1(db, who = "system:read") {
+  if (!db) return db;
+  return new Proxy(db, {
+    get(target, property) {
+      const value = target[property];
+      if (property === "prepare") return (sql) => {
+        const statement = value.call(target, sql);
+        return new Proxy(statement, {
+          get(statementTarget, statementProperty) {
+            const method = statementTarget[statementProperty];
+            if (!["run", "first", "all", "raw"].includes(statementProperty) || typeof method !== "function") return typeof method === "function" ? method.bind(statementTarget) : method;
+            return async (...args) => { auditD1(who, sql); return method.apply(statementTarget, args); };
+          },
+        });
+      };
+      if (property === "batch") return (statements) => { auditD1(who, "BATCH"); return typeof value === "function" ? value.call(target, statements) : Promise.all(statements.map((statement) => statement.run())); };
+      return typeof value === "function" ? value.bind(target) : value;
+    },
+  });
+}
+
+export function auditedEnv(env, who = "system:read") {
+  if (!env?.DB) return env;
+  const result = Object.create(env);
+  result.DB = auditedD1(env.DB, who);
+  return result;
+}
+
+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" });
+}

package/src/core/event-hub.js

@@ -0,0 +1,29 @@
+import { DurableObject } from "cloudflare:workers";
+
+export class EventHub extends DurableObject {
+  async fetch(request) {
+    const url = new URL(request.url);
+    if (request.method === "POST" && url.pathname === "/publish") {
+      if (request.headers.get("X-CF-GenAI-Event") !== "1") return new Response("Not found", { status: 404 });
+      const event = await request.json().catch(() => null);
+      if (!event?.id || !event?.what) return Response.json({ error: "Invalid event" }, { status: 400 });
+      const message = JSON.stringify({ type: "event", event });
+      for (const socket of this.ctx.getWebSockets()) {
+        try { socket.send(message); } catch { socket.close(1011, "Event delivery failed"); }
+      }
+      return Response.json({ ok: true });
+    }
+    if (request.method !== "GET" || request.headers.get("Upgrade")?.toLowerCase() !== "websocket") return new Response("WebSocket upgrade required", { status: 426 });
+    const pair = new WebSocketPair();
+    const [client, server] = Object.values(pair);
+    this.ctx.acceptWebSocket(server);
+    return new Response(null, { status: 101, webSocket: client });
+  }
+
+  webSocketMessage(socket, message) {
+    if (message === "ping") socket.send(JSON.stringify({ type: "pong" }));
+  }
+
+  webSocketClose() {}
+  webSocketError() {}
+}

package/src/core/events.js

@@ -0,0 +1,63 @@
+export function Event(who, what, where, when = new Date(), details = {}) {
+  return {
+    id: crypto.randomUUID(),
+    who: String(who || "system"),
+    what: String(what || "event"),
+    where: String(where || "application"),
+    when: when instanceof Date ? when.toISOString() : new Date(when || Date.now()).toISOString(),
+    details: details && typeof details === "object" ? details : { value: details },
+  };
+}
+
+export function createEventHandler(features = [], { eventHubBinding = "EVENT_HUB" } = {}) {
+  const handlers = features.flatMap((feature) => {
+    const handler = feature?.eventHandler || feature?.event_handler;
+    return typeof handler === "function" ? [handler.bind(feature)] : [];
+  });
+  return async (event, env, ctx) => {
+    if (!event) return null;
+    eventLog("info", event.what, { who: event.who, where: event.where, when: event.when, ...event.details });
+    await Promise.all([
+      ...handlers.map((handler) => Promise.resolve(handler(event, { env, ctx }))),
+      publishLiveEvent(env, event, eventHubBinding),
+    ]);
+    return event;
+  };
+}
+
+export function eventRooms(event) {
+  const audience = event?.details?.audience || {};
+  const rooms = [];
+  if (audience.userId) rooms.push(`user:${audience.userId}`);
+  if (audience.tenantId) rooms.push(`tenant:${audience.tenantId}`);
+  if (!rooms.length && String(event?.who || "").startsWith("user:")) rooms.push(String(event.who));
+  return [...new Set(rooms)];
+}
+
+async function publishLiveEvent(env, event, bindingName) {
+  const namespace = bindingName && env?.[bindingName];
+  if (!namespace || typeof namespace.idFromName !== "function") return;
+  for (const room of eventRooms(event)) {
+    try {
+      const stub = namespace.get(namespace.idFromName(room));
+      await stub.fetch("https://cf-genai-event-hub/publish", { method: "POST", headers: { "X-CF-GenAI-Event": "1", "Content-Type": "application/json" }, body: JSON.stringify(event) });
+    } catch (error) {
+      eventLog("warn", "live.event.publish.failed", { room, error: error?.message || String(error) });
+    }
+  }
+}
+
+export async function emitEvent(env, event, ctx) {
+  if (typeof env?.eventHandler === "function") return env.eventHandler(event, env, ctx);
+  if (event) eventLog("info", event.what, { who: event.who, where: event.where, when: event.when, ...event.details });
+  return event;
+}
+
+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);
+}

package/src/core/identity.js

@@ -0,0 +1,39 @@
+import { Event, emitEvent } from "./events.js";
+
+export function requestActor(state = {}) {
+  if (state.requestedBy) return String(state.requestedBy);
+  const canonical = authUser(state);
+  if (canonical?.id) return `user:${canonical.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 authUser(value) {
+  return value?.authUser || value?.user?.authUser || value?.state?.authUser || value?.state?.user?.authUser || (value?.id && value?.provider && value?.subject ? value : null) || null;
+}
+
+export function userId(value) {
+  return authUser(value)?.id || value?.userId || value?.sub || value?.email || null;
+}
+
+export function requestIdentity(state = {}) {
+  const canonical = authUser(state);
+  return {
+    user: state.user || null,
+    authUser: canonical,
+    userId: canonical?.id || null,
+    who: requestActor(state),
+    isAuthenticated: Boolean(canonical || state.user),
+    isAdmin: Boolean(state.user?.auth_strategy === "http_basic" || canonical?.is_admin),
+  };
+}
+
+export function requestContext({ request, env, ctx, state, data } = {}) {
+  const identity = requestIdentity(state);
+  return {
+    request, env, ctx, state, data: data || state?.data,
+    ...identity,
+    event: (what, where = "application", details = {}, when = new Date()) => emitEvent(env, Event(identity.who, what, where, when, details), ctx),
+  };
+}

package/src/core/index.js

@@ -0,0 +1,7 @@
+export * from "./constants.js";
+export * from "./events.js";
+export * from "./identity.js";
+export * from "./security.js";
+export * from "./d1.js";
+export * from "./circuits.js";
+export * from "./jobs.js";