@agilesyndrome/cf-genai-base 4.1.2 → 5.0.0

package/CONTRACT.md

@@ -2,6 +2,19 @@
 
 Every site built from this foundation follows the same edge contract.
 
+## API, UI, and repositories
+
+`defineRoute({ method, path, auth, scope, csrf, handler })` defines a route
+contract. Applications pass contracts through `createWorker({ apiRoutes })`;
+base enforces authentication, administrator status, same-origin mutation
+rules, and scope checks before invoking the handler. `@agilesyndrome/cf-genai-base/api`
+also exposes `apiFetch` and `apiJson` for browser clients.
+
+`createRepositories(env, definitions)` creates named application or feature
+repositories over the request-scoped data reader. Definitions may declare
+relations to other repositories. Repositories must not expose raw D1 or accept
+unvalidated table, column, or SQL fragments from callers.
+
 ## Worker entrypoint
 
 `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. A feature may also declare `{ routes: [{ match, handle }] }`; matching handlers receive `{ request, env, ctx, state, next }` and run before the site handler. The site router owns pages, APIs, D1 queries, and R2 object keys. `scheduled`
@@ -13,14 +26,15 @@ is optional and must use `ctx.waitUntil` for background work.
 - `GET /api/me` returns `{ user: null | { sub, email, name, ...roles } }`.
 - `/auth/login`, `/auth/callback`, and `/auth/logout` are reserved for auth.
 - `/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.
+- Admin routes use `AUTH_STRATEGY`; omitted or empty means `http_basic`. Basic auth accepts username `admin` and the value of `ADMIN_TOKEN`. 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.
-- `adminPage` optionally renders the authorized platform admin browser pages so a site can keep the shared system menu and its own visual shell consistent.
-- `siteAdminPage` optionally renders site-owned pages below `/admin/site/*`, keeping them separate from the reserved platform page paths.
-- Base provides `/api/admin/users`, `/api/admin/scopes`, `/api/admin/groups`, `/api/admin/status`, `/api/admin/features`, `/api/admin/healthchecks`, `/api/admin/circuit-breakers`, and `/api/admin/users/:id/scopes|groups` for platform administrators when the authorization and core migrations are installed. It also provides short-lived `/api/admin/users/:id/impersonate` and `/api/admin/impersonate/clear` controls. `GET /api/tenant` returns the authenticated active tenant and validated memberships; invalid `X-Tenant-ID` values return 400. `GET /api/admin/features` returns the installed runtime feature manifests, package names and versions, per-feature health rollups, healthchecks, and circuit breakers. The browser route `/admin/features` renders that catalog. Feature manifests may provide `name`, `displayName`, `packageName`, and `version`. The exported UI includes users, scopes, groups, healthchecks, and circuit-breaker catalogs.
+- Base protects `/admin` and `/api/admin`; browser pages are React applications that consume the JSON admin APIs. Import `AdminShell` and the platform catalogs from `@agilesyndrome/cf-genai-base/ui` and apply the application's theme around them.
+- Base provides `/api/admin/users`, `/api/admin/scopes`, `/api/admin/groups`, `/api/admin/status`, `/api/admin/features`, `/api/admin/healthchecks`, `/api/admin/circuit-breakers`, and `/api/admin/users/:id/scopes|groups` for platform administrators when the authorization and core migrations are installed. It also provides short-lived `/api/admin/users/:id/impersonate` and `/api/admin/impersonate/clear` controls. `GET /api/tenant` returns the authenticated active tenant and validated memberships; invalid `X-Tenant-ID` values return 400. `GET /api/admin/features` returns the installed runtime feature manifests, package names and versions, per-feature health rollups, healthchecks, and circuit breakers. React platform components consume these JSON APIs. Feature manifests may provide `name`, `displayName`, `packageName`, and `version`.
 - Public APIs must be explicitly listed in provider-specific auth configuration.
 - Mutating `/api/*` requests require a same-origin `Origin` header.
+- `createWorker` supplies request-scoped `data`, `user`, `authUser`, `userId`, `context`, `event`, and audited D1 access to route handlers. `Event(who, what, where, when, details)` creates normalized events; installed features may consume them through `eventHandler`.
+- `migrations/0006_jobs.sql` adds generic durable jobs and job events. Features create and update jobs with the exported lifecycle helpers; `GET /api/jobs`, `GET /api/jobs/:id`, and `GET /api/jobs/:id/events` expose only the authenticated owner's records. `GET /api/events` is an optional authenticated WebSocket stream backed by the configured `EVENT_HUB` Durable Object.
 
 ## Environment and bindings
 
@@ -40,8 +54,9 @@ Standard bindings:
 Build metadata is optional: `BUILD_SHA` and `BUILD_NUMBER`.
 
 The package includes ordered migrations. Each site must apply
-`migrations/0001_authorization.sql` before enabling the generic user/scope APIs
-and `migrations/0004_tenants.sql` for tenant membership and subscriptions.
+`migrations/0001_authorization.sql` before enabling the generic user/scope APIs,
+`migrations/0004_tenants.sql` for tenant membership and subscriptions, and
+`migrations/0006_jobs.sql` before creating or reading durable jobs.
 The tenant migration seeds the `Easley Family` tenant and `VIP` subscription,
 and migrates existing authorization users into that tenant.
 
@@ -59,7 +74,9 @@ must remain in the application router rather than in the shared auth package.
 
 `createWorker` accepts `dataResources`, and features may expose the same
 manifest through `feature.dataResources`. Each resource must declare a safe
-name, table, explicit columns, and one scope: `user`, `tenant`, or `system`.
+name, table, explicit columns, and one scope: `user`, `tenant`, `public`, or
+`system`. Public resources are read-only and predicate on the worker's
+`publicTenantId`, including for authenticated users.
 Resources may also declare allowed operations (`read`, `create`, `update`, and
 `delete`); reads support bounded native pagination through
 `reader.page({ limit, offset })` and `reader.count()`, plus safe filtered

package/README.md

@@ -7,7 +7,7 @@ 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
+through `@agilesyndrome/cf-genai-base/auth` 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
@@ -27,34 +27,31 @@ export default createWorker({
 
 Features expose `middleware(request, env, ctx, next, state)` and may short-circuit reserved routes, attach request state, or call `next()`.
 
-Sites may provide `adminPage({ request, env, url, state, features })` to render
-the shared platform pages (`/admin/users`, `/admin/scopes`, `/admin/groups`,
-`/admin/features`, `/admin/healthchecks`, and `/admin/circuit-breakers`) inside
-their own shell. The callback runs after the shared authorization boundary and
-must return a `Response` or `null`.
-
-Sites may separately provide `siteAdminPage({ request, env, url, state,
-features })` for a `/admin/site/*` namespace. This is useful when a site wants
-its own admin pages to have an explicit boundary beside the shared platform
-pages.
-
-The shared `<cf-admin-shell>` accepts an optional `cookbook-links` attribute
-containing semicolon-separated `Label|URL|active-key` entries. This lets a site
-replace the default Cookbook links while keeping the System links consistent.
+Base protects `/admin` and `/api/admin`; the React UI package owns the browser
+pages. Import `AdminShell` and the platform catalogs from
+`@agilesyndrome/cf-genai-base/ui`. Sites provide their own application links and
+theme while the base components consume the shared JSON admin APIs.
 
 ## Shared platform helpers
 
-`createWorker` can own `/health` and `/api/health`, run a boot validator before
-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.
+`createWorker` can own `/health` and `/api/health`, and run a boot validator
+before requests. 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.
+The package is organized by responsibility: `runtime` composes Workers,
+`core` owns request/event/security/D1 primitives, `auth` owns authorization
+data access, `api` owns route contracts and the browser client, `admin` owns
+platform administration, and `ui` owns shared browser components. Each
+responsibility has a canonical folder entrypoint; import from `core`, `auth`,
+`data`, `api`, `admin`, or `ui` as appropriate.
 
-Admin APIs are `GET /api/admin/healthchecks`, `PUT /api/admin/healthchecks/:id`, `GET /api/admin/circuit-breakers`, `GET|PUT /api/admin/circuit-breakers/:id`, and `GET /api/admin/features`. The browser route `/admin/features` renders the same feature catalog for administrators. The catalog lists each installed runtime feature, its `packageName` and `version`, its most severe healthcheck state, all feature healthchecks, and its circuit breakers (including the feature roll-up breaker). Feature manifests may expose `healthchecks` and `circuitBreakers`; add `displayName`, `packageName`, and `version` to make the installation identity explicit. Use `createD1(env, { who })` for downstream D1 calls; it emits EventLog and AuditLog console records with the requesting actor.
+Apply `migrations/0002_core.sql` and `migrations/0006_jobs.sql` after the authorization migration. The package exports `registerHealthcheck`, `updateHealthcheck`, `registerCircuitBreaker`, `setCircuitBreaker`, `evaluateCircuitBreaker`, and generic job lifecycle helpers 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`, and `GET /api/admin/features`. React platform components consume these JSON responses. The catalog lists each installed runtime feature, its `packageName` and `version`, its most severe healthcheck state, all feature healthchecks, and its circuit breakers (including the feature roll-up breaker). Feature manifests may expose `healthchecks` and `circuitBreakers`; add `displayName`, `packageName`, and `version` to make the installation identity explicit. Use `createD1(env, { who })` for downstream D1 calls; it emits EventLog and AuditLog console records with the requesting actor.
 
 
 ## User administration
@@ -70,14 +67,15 @@ Use the selected D1 target (local by default) to inspect and update users:
     cf-genai user get someone.com --target staging
     cf-genai user update someone.com --roles admin --target production
 
-`user:get` also reports scopes and groups. The user update command resolves an email, subject, or internal id and supports `admin` or `none` roles. Production commands should be run through the repository credentials wrapper and reviewed as an administrative change.
+`user:get` also reports scopes, groups, and tenant memberships. The shared admin user page displays each user’s tenant memberships and lets an administrator attach or detach tenants. The admin API exposes `GET|POST /api/admin/tenants`, `GET|PUT /api/admin/tenants/:id`, and `GET|PUT /api/admin/users/:id/tenants`. Production commands should be run through the repository credentials wrapper and reviewed as an administrative change.
 
 ## Scoped data access
 
 Features may register D1 resources with `dataResources` and receive the
 scoped reader on the request state as `state.data`. Resources declare `user`,
-`tenant`, or `system` scope, their physical table, and an explicit column
-allowlist. Use `state.data.tenant`, `state.data.user`, or `state.data.system`;
+`tenant`, `public`, or `system` scope, their physical table, and an explicit column
+allowlist. Use `state.data.tenant`, `state.data.public`, `state.data.user`, or
+`state.data.system`;
 the reader applies ownership predicates, supports bounded native pagination via
 page with limit/offset, count, and safe bulk updateWhere/deleteWhere
 operations, and never accepts raw SQL. Resources can explicitly restrict
@@ -87,7 +85,9 @@ Anonymous tenant reads require both publicTenantId on createWorker and a
 resource-level publicRead declaration. Use publicRead true only when the
 whole resource is public; for opt-in rows use a publicRead column/value
 declaration such as visibility=public. Anonymous reads never grant anonymous
-system access.
+system access. A `public` resource is read-only and always predicates on the
+worker's `publicTenantId`, including authenticated users; use it for shared
+catalog data such as GTA's `gta-public` tenant.
 
 Applications may pass subscriptionManifest to createWorker to register their
 own subscription IDs and entitlement values. Base exposes
@@ -108,3 +108,37 @@ resource used with the wrong scope returns no rows; writes fail closed.
 Applications using scoped data must stop passing unrestricted `env.DB` to
 domain features. Their migrations still add and backfill ownership columns,
 and their resources must be registered with base.
+
+Request handlers receive a request-scoped environment containing `data`,
+`user`, `authUser`, `userId`, `context`, `event`, and an audited D1 binding.
+Call `await env.event("thing.happened", "domain", details)` to emit a
+normalized event. Features may provide `eventHandler(event, { env, ctx })`;
+this is the extension point for feature integrations.
+
+Long-running features can call `dispatchJob` with a Cloudflare Workflow binding;
+base creates the durable record first and passes its ID to the Workflow as
+`params.jobId`. Workflow code calls `executeJob`, which supplies a progress
+reporter and completes or fails the record. `runJob` is the same lifecycle for
+work already executing in the current invocation. Lower-level features may call
+`createJob`, `startJob`, `updateJobProgress`, `completeJob`, `failJob`, and
+`cancelJob` directly. Every lifecycle change is stored in `core_job_events` and emitted
+to the owning user's live event room. Configure the optional live transport by
+exporting `EventHub` from `@agilesyndrome/cf-genai-base/event-hub` and binding
+an `EVENT_HUB` Durable Object in the application Worker. The React package's
+`LiveEventsProvider`, `useJob`, `useJobs`, and `JobNotificationList` handle
+reconnects and refreshes; the feature remains responsible for its own Workflow,
+job type, executor, and result UI.
+
+The exported `Event`, `emitEvent`, `requestContext`, `userId`, `sameOrigin`,
+`readJson`, `secureJson`, `featureCircuit`, and `requireFeatureCircuit` helpers
+are the shared identity, request, security, and feature-gating contracts.
+
+The layered web surface is React-first: `/api` exports route contracts, scoped
+repositories, the browser `apiFetch`/`apiJson` client, and job/event endpoints;
+`/ui` exports React admin primitives, live event hooks, and durable job
+notifications. Repositories are registered with
+`createWorker({ repositories })`, can be supplied by applications or features,
+and may declare links to other repositories while remaining behind the scoped
+data reader. `GET /api/jobs` and `GET /api/jobs/:id` expose an authenticated
+user's durable job records. `GET /api/events` upgrades to the authenticated live
+event stream when the optional `EVENT_HUB` Durable Object binding is configured.

package/changelog.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## 5.0.0
+
+- Replace `@agilesyndrome/cf-genai-base/authorization` imports with `/auth`.
+- Replace direct `src/core.js` imports with `src/core/index.js` or the package `/core` entrypoint.
+- Replace direct `src/data.js` imports with `src/data/index.js` or the package `/data` entrypoint.
+- Replace direct `src/api/router.js` imports with `src/api/contracts.js` for route definitions and dispatch.
+- Update internal imports to the canonical folder modules; the old facade files are removed.
+- Update package consumers and lockfiles to version `5.0.0`.
+- Replace server-rendered admin HTML and custom elements with the React UI entrypoint; apps own the shell and theme around base's admin components.
+- Apply `migrations/0006_jobs.sql`; features now use generic durable job helpers and `GET /api/jobs` instead of inventing job tables and status endpoints.
+- Configure an `EVENT_HUB` Durable Object and export `EventHub` from `@agilesyndrome/cf-genai-base/event-hub` to enable authenticated live job events over WebSockets.
+- Dispatch long-running work through a Cloudflare Workflow with `dispatchJob`; execute its durable lifecycle with `executeJob` instead of relying on request-lifetime background work.
+- Remove the lowercase `admin_token` environment alias; use `ADMIN_TOKEN` only.

package/migrations/0006_jobs.sql

@@ -0,0 +1,38 @@
+CREATE TABLE IF NOT EXISTS core_jobs (
+  id TEXT PRIMARY KEY,
+  type TEXT NOT NULL,
+  status TEXT NOT NULL DEFAULT 'queued' CHECK (status IN ('queued', 'running', 'succeeded', 'failed', 'cancelled')),
+  owner_id TEXT,
+  tenant_id TEXT,
+  resource_type TEXT,
+  resource_id TEXT,
+  input_json TEXT NOT NULL DEFAULT '{}',
+  result_json TEXT NOT NULL DEFAULT '{}',
+  error_json TEXT,
+  progress_json TEXT NOT NULL DEFAULT '{}',
+  created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  started_at TEXT,
+  finished_at TEXT,
+  updated_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  expires_at TEXT
+);
+
+CREATE INDEX IF NOT EXISTS core_jobs_owner_status_idx
+  ON core_jobs(owner_id, status, updated_at DESC);
+
+CREATE INDEX IF NOT EXISTS core_jobs_type_status_idx
+  ON core_jobs(type, status, updated_at DESC);
+
+CREATE INDEX IF NOT EXISTS core_jobs_resource_idx
+  ON core_jobs(resource_type, resource_id, updated_at DESC);
+
+CREATE TABLE IF NOT EXISTS core_job_events (
+  id TEXT PRIMARY KEY,
+  job_id TEXT NOT NULL REFERENCES core_jobs(id) ON DELETE CASCADE,
+  type TEXT NOT NULL,
+  payload_json TEXT NOT NULL DEFAULT '{}',
+  created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE INDEX IF NOT EXISTS core_job_events_job_created_idx
+  ON core_job_events(job_id, created_at DESC);

package/package.json

@@ -1,17 +1,26 @@
 {
   "name": "@agilesyndrome/cf-genai-base",
-  "version": "4.1.2",
+  "version": "5.0.0",
   "type": "module",
   "exports": {
     ".": "./src/index.js",
-    "./authorization": "./src/authorization.js",
-    "./data": "./src/data.js",
-    "./core": "./src/core.js",
+    "./auth": "./src/auth/index.js",
+    "./data": "./src/data/index.js",
+    "./api": "./src/api/index.js",
+    "./event-hub": "./src/core/event-hub.js",
+    "./repository": "./src/repository.js",
+    "./app": "./src/app.js",
+    "./admin": "./src/admin/index.js",
+    "./core": "./src/core/index.js",
     "./ui": "./src/ui/index.js",
+    "./ui/react": "./src/ui/react/index.jsx",
     "./ui/styles.css": "./src/ui/styles.css"
   },
   "description": "Lean Worker lifecycle and security helpers for Cloudflare sites.",
   "license": "MIT",
+  "peerDependencies": {
+    "react": "^19.0.0"
+  },
   "publishConfig": {
     "access": "public",
     "provenance": true
@@ -20,6 +29,7 @@
     "src",
     "migrations",
     "README.md",
+    "changelog.md",
     "CONTRACT.md",
     "LICENSE"
   ],
@@ -29,7 +39,7 @@
   },
   "homepage": "https://github.com/agilesyndrome/cf-genai-base#readme",
   "scripts": {
-    "check": "node --check src/index.js && node --check src/core.js && node --check src/authorization.js && node --check src/data.js",
+    "check": "node --check src/index.js && node --check src/core/index.js && node --check src/core/jobs.js && node --check src/core/event-hub.js && node --check src/auth/index.js && node --check src/runtime/worker.js && node --check src/runtime/features.js && node --check src/runtime/health.js && node --check src/admin/index.js && node --check src/admin/routes.js && node --check src/data/index.js && node --check src/data/resources.js && node --check src/data/reader.js && node --check src/data/context.js && node --check src/api/index.js && node --check src/api/contracts.js && node --check src/api/client.js && node --check src/api/jobs.js && node --check src/ui/index.js",
     "test": "node --test tests/*.test.mjs",
     "build": "npm run check && npm test && npm pack --dry-run"
   }

package/src/admin/index.js

@@ -0,0 +1 @@
+export * from "./routes.js";

package/src/admin/routes.js

@@ -0,0 +1,64 @@
+import { createAuthorizationTenant, createImpersonationToken, ensureScopes, ensureUser, getAuthorizationTenant, getAuthorizationUser, hasScope, listAuthorizationScopes, listAuthorizationTenants, listAuthorizationUsers, listGroups, listUserGroups, listUserGrants, listUserTenants, replaceUserGroups, replaceUserTenants, replaceUserGrants, updateAuthorizationTenant } from "../auth/index.js";
+import { getCircuitBreaker, listCircuitBreakers, listFeatureCatalog, listFeatureHealth, listHealthchecks, requestActor, setCircuitBreaker, updateHealthcheck } from "../core/index.js";
+
+export async function adminBoundary(request, env, ctx, next, state, { provider, authorize, scopes, scopeRoutes, features }) {
+  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" } });
+  if (["POST", "PUT", "PATCH", "DELETE"].includes(request.method) && url.pathname.startsWith("/api/")) { const origin = request.headers.get("Origin"); if (!origin || (() => { try { return new URL(origin).origin !== url.origin; } catch { return true; } })()) return Response.json({ error: "A same-origin request is required." }, { status: 403, headers: { "Cache-Control": "no-store" } }); }
+  const who = state.user?.auth_strategy === "http_basic" ? "user:admin" : `user:${state.user?.sub || "unknown"}`;
+  await ensureScopes(env, scopes, { who });
+  state.authUser = state.user?.authUser || await ensureUser(env, state.user, { who }); 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, features); if (platformResponse) return platformResponse;
+  return next(request);
+}
+
+async function authorizationApi(request, env, url, state, features = []) {
+  const grantsMatch = url.pathname.match(/\/api\/admin\/users\/([^/]+)\/scopes$/);
+  const platformPath = url.pathname === "/api/admin/users" || url.pathname === "/api/admin/tenants" || url.pathname.startsWith("/api/admin/tenants/") || url.pathname === "/api/admin/scopes" || url.pathname === "/api/admin/groups" || url.pathname.startsWith("/api/admin/users/") || url.pathname.startsWith("/api/admin/impersonate") || url.pathname === "/api/admin/status" || url.pathname === "/api/admin/features" || 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" } });
+  const who = { who: requestActor(state) };
+  if (url.pathname === "/api/admin/impersonate/clear" && request.method === "POST") return new Response(JSON.stringify({ ok: true }), { headers: { "content-type": "application/json; charset=utf-8", "Set-Cookie": "__Host-cfgenai_impersonation=; Max-Age=0; Path=/; Secure; HttpOnly; SameSite=Lax" } });
+  if (url.pathname === "/api/admin/users" && request.method === "GET") return Response.json({ users: await listAuthorizationUsers(env, who) });
+  if (url.pathname === "/api/admin/tenants" && request.method === "GET") return Response.json({ tenants: await listAuthorizationTenants(env, who) });
+  if (url.pathname === "/api/admin/tenants" && request.method === "POST") { const body = await request.json().catch(() => null); if (!body?.id || !body?.name) return Response.json({ error: "id and name are required" }, { status: 400 }); try { return Response.json({ tenant: await createAuthorizationTenant(env, body.id, body.name, who) }, { status: 201 }); } catch (error) { return Response.json({ error: error.message }, { status: 400 }); } }
+  const tenantMatch = url.pathname.match(/^\/api\/admin\/tenants\/([^/]+)$/);
+  if (tenantMatch && request.method === "GET") return Response.json({ tenant: await getAuthorizationTenant(env, decodeURIComponent(tenantMatch[1]), who) });
+  if (tenantMatch && request.method === "PUT") { const body = await request.json().catch(() => null); if (!body?.name) return Response.json({ error: "name is required" }, { status: 400 }); return Response.json({ tenant: await updateAuthorizationTenant(env, decodeURIComponent(tenantMatch[1]), body.name, who) }); }
+  const impersonateMatch = url.pathname.match(/^\/api\/admin\/users\/([^/]+)\/impersonate$/);
+  if (impersonateMatch && request.method === "POST") { const targetUser = await getAuthorizationUser(env, decodeURIComponent(impersonateMatch[1]), who); if (!targetUser) return Response.json({ error: "User not found." }, { status: 404 }); const token = await createImpersonationToken(env, state.authUser?.id || state.user?.sub || "admin", targetUser.id); return new Response(JSON.stringify({ ok: true, user: { id: targetUser.id, email: targetUser.email, display_name: targetUser.display_name }, expires_in: 900 }), { headers: { "content-type": "application/json; charset=utf-8", "Set-Cookie": `__Host-cfgenai_impersonation=${token}; Max-Age=900; Path=/; Secure; HttpOnly; SameSite=Lax` } }); }
+  if (url.pathname === "/api/admin/scopes" && request.method === "GET") return Response.json({ scopes: await listAuthorizationScopes(env, who) });
+  if (url.pathname === "/api/admin/status" && request.method === "GET") return Response.json({ features: await listFeatureHealth(env, who) });
+  if (url.pathname === "/api/admin/features" && request.method === "GET") return Response.json({ features: await listFeatureCatalog(env, features, who) });
+  if (url.pathname === "/api/admin/groups" && request.method === "GET") return Response.json({ groups: await listGroups(env, who) });
+  if (url.pathname === "/api/admin/healthchecks" && request.method === "GET") return Response.json({ healthchecks: await listHealthchecks(env, who) });
+  if (url.pathname === "/api/admin/circuit-breakers" && request.method === "GET") return Response.json({ circuit_breakers: await listCircuitBreakers(env, who) });
+  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); 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) });
+  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); return breaker ? Response.json({ circuit_breaker: breaker }) : Response.json({ error: "Circuit breaker not found" }, { status: 404 }); }
+  const groupsMatch = url.pathname.match(/\/api\/admin\/users\/([^/]+)\/groups$/);
+  if (groupsMatch && request.method === "GET") return Response.json({ groups: await listUserGroups(env, decodeURIComponent(groupsMatch[1]), who) });
+  if (groupsMatch && request.method === "PUT") { const body = await request.json().catch(() => null); if (!body || !Array.isArray(body.groups)) return Response.json({ error: "groups must be an array" }, { status: 400 }); return Response.json({ groups: await replaceUserGroups(env, decodeURIComponent(groupsMatch[1]), body.groups, state.authUser && state.authUser.id, who) }); }
+  const tenantsMatch = url.pathname.match(/\/api\/admin\/users\/([^/]+)\/tenants$/);
+  if (tenantsMatch && request.method === "GET") return Response.json({ tenants: await listUserTenants(env, decodeURIComponent(tenantsMatch[1]), who) });
+  if (tenantsMatch && request.method === "PUT") { const body = await request.json().catch(() => null); if (!body || !Array.isArray(body.tenants)) return Response.json({ error: "tenants must be an array" }, { status: 400 }); return Response.json({ tenants: await replaceUserTenants(env, decodeURIComponent(tenantsMatch[1]), body.tenants, who) }); }
+  if (grantsMatch && request.method === "GET") return Response.json({ grants: await listUserGrants(env, decodeURIComponent(grantsMatch[1]), who) });
+  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); return Response.json({ grants }); }
+  return null;
+}
+
+function isAdminPath(pathname) { return pathname === "/admin" || pathname.startsWith("/admin/") || pathname === "/api/admin" || pathname.startsWith("/api/admin/"); }
+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; }
+function basicUser(request, env) { const token = String(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 || !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; }

package/src/api/client.js

@@ -0,0 +1,8 @@
+export async function apiFetch(input, options = {}) {
+  const response = await fetch(input, { credentials: "same-origin", headers: { Accept: "application/json", ...(options.body ? { "Content-Type": "application/json" } : {}), ...(options.headers || {}) }, ...options });
+  const payload = await response.clone().json().catch(() => null);
+  if (!response.ok) { const error = new Error(payload?.error || `Request failed (${response.status})`); error.status = response.status; error.requestId = response.headers.get("X-Request-ID") || payload?.request_id || null; throw error; }
+  return payload === null ? response : payload;
+}
+
+export function apiJson(input, payload, options = {}) { return apiFetch(input, { ...options, method: options.method || "POST", body: JSON.stringify(payload) }); }

package/src/api/contracts.js

@@ -0,0 +1,24 @@
+import { json, requestIdentity, sameOrigin } from "../core/index.js";
+import { hasScope } from "../auth/index.js";
+
+export function defineRoute({ method = "GET", path, auth = "public", scope = null, csrf = false, handler } = {}) {
+  if (!path || typeof handler !== "function") throw new TypeError("API routes require path and handler");
+  return { method: String(method).toUpperCase(), path: String(path), auth, scope, csrf, handler };
+}
+
+export function matchRoute(request, route) {
+  const url = new URL(request.url); const methods = Array.isArray(route.method) ? route.method : [route.method];
+  return methods.map((method) => String(method).toUpperCase()).includes(request.method.toUpperCase()) && (typeof route.path === "function" ? route.path(url.pathname, request) : route.path === url.pathname);
+}
+
+export async function dispatchRoutes(request, env, ctx, state, routes = []) {
+  for (const route of routes) if (matchRoute(request, route)) {
+    const identity = requestIdentity(state);
+    if (route.auth === "user" && !identity.isAuthenticated) return json({ error: "Authentication is required." }, 401);
+    if (route.auth === "admin" && !identity.isAdmin) return json({ error: "Administrator access is required." }, 403);
+    if (route.csrf && !sameOrigin(request)) return json({ error: "A same-origin request is required." }, 403);
+    if (route.scope && !(await hasScope(env, state?.user || state?.authUser, route.scope, { who: identity.who }))) return json({ error: "Required scope is missing." }, 403);
+    return route.handler({ request, env, ctx, state, route, identity });
+  }
+  return null;
+}

package/src/api/index.js

@@ -0,0 +1,7 @@
+export { Event, emitEvent, json, readJson, readJsonClone, requireAdmin, requireFeatureCircuit, requireUser, sameOrigin, secureJson, secureText, userId, requestContext, requestIdentity } from "../core/index.js";
+export { defineRepository, createRepositories, RepositoryError } from "../repository.js";
+export { defineRoute, matchRoute, dispatchRoutes } from "./contracts.js";
+export { apiFetch, apiJson } from "./client.js";
+export { jobResponse, liveEventsResponse } from "./jobs.js";
+export { defineApp } from "../app.js";
+export { assertSecurityHeaders, assertJsonError } from "./testing.js";

package/src/api/jobs.js

@@ -0,0 +1,37 @@
+import { getJob, listJobEvents, listJobs } from "../core/jobs.js";
+import { requestIdentity } from "../core/identity.js";
+import { secureJson } from "../core/security.js";
+
+export async function jobResponse(request, env, state) {
+  const pathname = new URL(request.url).pathname;
+  if (pathname !== "/api/jobs" && !pathname.startsWith("/api/jobs/")) return null;
+  if (request.method !== "GET") return secureJson({ error: "Method not allowed" }, 405, { Allow: "GET" });
+  const identity = requestIdentity(state);
+  const ownerId = identity.authUser?.id || state?.user?.sub || (state?.user?.auth_strategy === "http_basic" ? "basic:admin" : null);
+  if (!ownerId) return secureJson({ error: "Authentication is required." }, 401);
+  const url = new URL(request.url);
+  const match = url.pathname.match(/^\/api\/jobs\/([^/]+)(?:\/events)?$/);
+  const isEvents = url.pathname.endsWith("/events");
+  if (!match) {
+    const jobs = await listJobs(env, { ownerId, type: url.searchParams.get("type") || undefined, status: url.searchParams.get("status") || undefined, limit: url.searchParams.get("limit") || 50 }, { who: identity.who });
+    return secureJson({ jobs });
+  }
+  const job = await getJob(env, decodeURIComponent(match[1]), { who: identity.who });
+  if (!job || (job.ownerId !== ownerId && !identity.isAdmin)) return secureJson({ error: "Job not found" }, 404);
+  if (isEvents) return secureJson({ events: await listJobEvents(env, job.id, { who: identity.who }) });
+  return secureJson({ job });
+}
+
+export async function liveEventsResponse(request, env, state, bindingName = "EVENT_HUB") {
+  const url = new URL(request.url);
+  if (url.pathname !== "/api/events") return null;
+  const identity = requestIdentity(state);
+  const ownerId = identity.authUser?.id || state?.user?.sub || (state?.user?.auth_strategy === "http_basic" ? "basic:admin" : null);
+  if (!ownerId) return secureJson({ error: "Authentication is required." }, 401);
+  const namespace = env?.[bindingName];
+  if (!namespace || typeof namespace.idFromName !== "function") return secureJson({ error: "Live events are not configured." }, 501);
+  if (request.headers.get("Upgrade")?.toLowerCase() !== "websocket") return secureJson({ error: "WebSocket upgrade required." }, 426, { Upgrade: "websocket" });
+  const room = `user:${ownerId}`;
+  const stub = namespace.get(namespace.idFromName(room));
+  return stub.fetch("https://cf-genai-event-hub/connect", { headers: { Upgrade: "websocket" } });
+}

package/src/api/testing.js

@@ -0,0 +1,13 @@
+export function assertSecurityHeaders(response) {
+  for (const header of ["Content-Security-Policy", "X-Content-Type-Options", "X-Frame-Options", "Referrer-Policy", "Permissions-Policy", "Strict-Transport-Security"]) {
+    if (!response?.headers?.get(header)) throw new Error(`Missing security header: ${header}`);
+  }
+  return response;
+}
+
+export async function assertJsonError(response, status) {
+  if (response.status !== status) throw new Error(`Expected ${status}, received ${response.status}`);
+  const payload = await response.clone().json();
+  if (!payload?.error) throw new Error("Expected a JSON error envelope");
+  return payload;
+}

package/src/app.js

@@ -0,0 +1,5 @@
+export function defineApp({ name, ui = true, api = true, admin = true, features = [], repositories = [] } = {}) {
+  if (!/^[a-z][a-z0-9-]*$/.test(String(name || ""))) throw new TypeError("Apps require a safe name");
+  if (!ui && !api) throw new TypeError("An app must expose ui or api");
+  return { name: String(name), ui: Boolean(ui), api: Boolean(api), admin: Boolean(admin), features: [...features], repositories: [...repositories] };
+}

package/src/auth/constants.js

@@ -0,0 +1,9 @@
+export const AUTH_USER_TABLE = "auth_users";
+export const AUTH_SCOPE_TABLE = "auth_scopes";
+export const AUTH_GRANT_TABLE = "auth_user_scopes";
+export const DEFAULT_TENANT_ID = "easley-family";
+export const DEFAULT_TENANT_NAME = "Easley Family";
+
+export class SubscriptionError extends Error {
+  constructor(message) { super(message); this.name = "SubscriptionError"; }
+}

package/src/auth/encoding.js

@@ -0,0 +1,6 @@
+export function parseJsonValue(value) { try { return JSON.parse(value); } catch { return value; } }
+export function deepEqual(left, right) { return JSON.stringify(left) === JSON.stringify(right); }
+export async function signValue(value, secret) { const key = await crypto.subtle.importKey("raw", new TextEncoder().encode(String(secret)), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]); const signature = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(value)); return base64url(new Uint8Array(signature)); }
+export function base64url(bytes) { return btoa(String.fromCharCode(...bytes)).replaceAll("+", "-").replaceAll("/", "_").replaceAll("=", ""); }
+export function base64urlDecode(value) { const padded = value.replaceAll("-", "+").replaceAll("_", "/") + "=".repeat((4 - value.length % 4) % 4); return Uint8Array.from(atob(padded), (char) => char.charCodeAt(0)); }
+export function constantTimeEqual(left, right) { const a = new TextEncoder().encode(String(left)), b = new TextEncoder().encode(String(right)); let result = a.length ^ b.length; for (let index = 0; index < Math.max(a.length, b.length); index += 1) result |= (a[index] || 0) ^ (b[index] || 0); return result === 0; }

package/src/auth/groups.js

@@ -0,0 +1,5 @@
+import { createD1 } from "../core/d1.js";
+
+export async function listGroups(env, { who = "system:read" } = {}) { const result = await createD1(env, { who }).prepare("SELECT name,display_name,description,created_at,updated_at FROM auth_groups ORDER BY display_name COLLATE NOCASE").all(); return result.results || []; }
+export async function listUserGroups(env, userId, { who = "system:read" } = {}) { const result = await createD1(env, { who }).prepare("SELECT group_name,granted_at FROM auth_user_groups WHERE user_id=? ORDER BY group_name").bind(userId).all(); return result.results || []; }
+export async function replaceUserGroups(env, userId, groups, grantedBy, { who = "system:read" } = {}) { const db = createD1(env, { who }); await db.batch([db.prepare("DELETE FROM auth_user_groups WHERE user_id=?").bind(userId), ...[...new Set(groups)].map((group) => db.prepare("INSERT INTO auth_user_groups (user_id,group_name,granted_by) VALUES (?,?,?)").bind(userId, group, grantedBy || null))]); return listUserGroups(env, userId, { who }); }

package/src/auth/impersonation.js

@@ -0,0 +1,15 @@
+import { base64url, base64urlDecode, constantTimeEqual, signValue } from "./encoding.js";
+
+export async function createImpersonationToken(env, adminUserId, targetUserId, { ttlSeconds = 900 } = {}) {
+  if (!env?.AUTH_SESSION_SECRET) throw new Error("AUTH_SESSION_SECRET is required for impersonation.");
+  const payload = { adminUserId: String(adminUserId || "admin"), targetUserId: String(targetUserId), exp: Math.floor(Date.now() / 1000) + Math.min(Math.max(Number(ttlSeconds) || 900, 60), 3600) };
+  const encoded = base64url(new TextEncoder().encode(JSON.stringify(payload)));
+  return `${encoded}.${await signValue(encoded, env?.AUTH_SESSION_SECRET || "")}`;
+}
+
+export async function verifyImpersonationToken(token, env) {
+  if (!env?.AUTH_SESSION_SECRET) return null;
+  const [encoded, signature] = String(token || "").split(".");
+  if (!encoded || !signature || !constantTimeEqual(signature, await signValue(encoded, env?.AUTH_SESSION_SECRET || ""))) return null;
+  try { const payload = JSON.parse(new TextDecoder().decode(base64urlDecode(encoded))); return payload.exp > Date.now() / 1000 && payload.targetUserId ? payload : null; } catch { return null; }
+}

package/src/auth/index.js

@@ -0,0 +1,7 @@
+export * from "./constants.js";
+export * from "./scopes.js";
+export * from "./users.js";
+export * from "./tenants.js";
+export * from "./groups.js";
+export * from "./subscriptions.js";
+export * from "./impersonation.js";

package/src/auth/scopes.js

@@ -0,0 +1,32 @@
+import { createD1 } from "../core/d1.js";
+import { AUTH_GRANT_TABLE, AUTH_SCOPE_TABLE } from "./constants.js";
+
+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 listAuthorizationScopes(env, { who = "system:read" } = {}) {
+  const { results } = await createD1(env, { who }).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 { results } = await createD1(env, { who }).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;
+}