@agilesyndrome/cf-genai-base 5.0.0 → 5.0.1

package/CLI.md

@@ -0,0 +1,121 @@
+# `cf-genai` command
+
+The `cf-genai` executable is published by `@agilesyndrome/cf-genai-base` and
+provides safe operational commands for Cloudflare Worker repositories using
+Wrangler and D1. The refresh command surface contains only local and staging
+targets.
+
+Projects that previously installed `@agilesyndrome/cf-genai-cli` should remove
+that dependency. Installing `@agilesyndrome/cf-genai-base` now installs the
+same `cf-genai` executable.
+
+Automation can import the command runner from
+`@agilesyndrome/cf-genai-base/cli`. The migrated helper modules remain
+available through subpaths such as `@agilesyndrome/cf-genai-base/cli/d1` and
+`@agilesyndrome/cf-genai-base/cli/project`.
+
+It also provides shared project automation so dependent repositories do not
+need to duplicate their build and release logic:
+
+```sh
+cf-genai check
+cf-genai lint data-access
+cf-genai test
+cf-genai ci
+cf-genai dev
+cf-genai upgrade base latest
+cf-genai upgrade auth latest
+cf-genai upgrade llm 5.0.0
+cf-genai upgrade messaging latest
+cf-genai release --confirm
+cf-genai release --first --confirm
+cf-genai release --add-trust --confirm
+cf-genai release --dry-run
+cf-genai release --version 4.1 --confirm
+cf-genai release-status
+cf-genai release-status --wait 3 --json
+cf-genai version
+  cf-genai status
+  cf-genai status --json
+```
+
+`dev` runs through `op run --env-file=.env.dev --`, using the repository's
+`npm run dev` script when present, otherwise starting `wrangler dev`. This
+loads all `.env.dev` variables and resolves any `op://` values automatically.
+`check` also rejects direct `env.DB.prepare(...)` and `DB.prepare(...)` calls
+in `cf-genai-*` application source; domain code must use the scoped data reader
+provided by `cf-genai-base`. Tests and migrations are excluded from this lint.
+`release` owns versioning, tagging, and pushing the release trigger used by
+GitHub Actions. `version` shows the installed CLI version and the latest npm
+version, with an upgrade command when one is available.
+
+For the initial npm publication, use `cf-genai release --first --confirm`.
+It checks npm authentication, publishes the current package once with public
+access and provenance disabled, and then creates the matching npm Trusted
+Publisher rule for `.github/workflows/publish.yml`. npm 11.15.0 or newer and
+account-level 2FA are required for the trust step. If the package is already
+published, use `cf-genai release --add-trust --confirm`.
+Subsequent releases use the normal tag-triggered workflow.
+
+```sh
+cf-genai d1 refresh local
+cf-genai d1 refresh staging --yes
+cf-genai d1 migrate local
+cf-genai d1 migrate staging
+cf-genai d1 migrate production --confirm-production
+cf-genai d1 status staging
+cf-genai d1 check production
+cf-genai config check
+```
+
+`refresh local` exports production data, applies local migrations, clears local
+application tables, and imports the data. `refresh staging` does the same for a
+remote staging environment. Both exclude Wrangler's migration ledger and
+internal tables. The default D1 binding is `DB`; override it with `--database`.
+
+Credential loading stays outside the CLI, so repositories can use their normal
+wrapper:
+
+```sh
+op run --env-file=.env.op -- cf-genai d1 refresh local
+```
+
+Production migration requires `--confirm-production`. Remote staging refresh
+requires `--yes`. Releases require `--confirm` (or can be inspected
+with `--dry-run`); the CLI verifies a
+clean checkout on `main`, fetches and compares `origin/main`, pushes and
+verifies the release commit before creating the tag, and only then pushes the
+tag that triggers npm publishing. The release tag publishes the package through GitHub Actions with provenance. `config check` runs a Wrangler deploy dry-run. Production refresh remains intentionally unavailable; backups and restores are available with explicit file paths.
+
+`upgrade PACKAGE VERSION` upgrades the first-party `base`, `auth`, `llm`, or
+`messaging` package with npm and vendors package migrations not already represented in the repository's
+`migrations/` directory. The generated files are ordinary committed Wrangler
+migrations, so the same schema change is applied consistently to local,
+staging, and production D1 databases. Review and commit the package files,
+`package.json`, `package-lock.json`, and generated migrations together.
+Operational status can be read directly from the current site directory through Wrangler (no CLI login prompt):
+  cf-genai healthcheck:list --env local
+  cf-genai healthcheck:list --env staging
+  cf-genai circuit-breaker:list --env prod
+  cf-genai circuit-breaker:set llm:openai-models on --env staging
+The standardized admin surface mirrors cf-genai-base and uses Wrangler authentication from the current machine:
+  cf-genai admin status --env staging
+  cf-genai admin features --env staging
+  cf-genai admin users --env staging
+  cf-genai admin tenants --env staging
+  cf-genai admin scopes --env staging
+  cf-genai admin groups --env staging
+  cf-genai admin healthchecks --env staging
+  cf-genai admin circuit-breakers --env staging
+  cf-genai tenant list --env staging
+  cf-genai tenant get easley-family --env staging
+  cf-genai tenant create acme --name "Acme Corporation" --env staging
+  cf-genai tenant update acme --name "Acme Inc." --env staging
+  cf-genai user get someone@example.com --env staging
+  cf-genai user update someone@example.com --tenants easley-family,acme --env staging
+  cf-genai healthchecks set llm:provider red --env staging
+  cf-genai circuit-breakers set llm:provider tripped --env staging
+Back up and restore a complete D1 database with explicit files:
+  cf-genai d1 backup production --output ./backup.sql --confirm-production
+  cf-genai d1 restore staging --file ./backup.sql --yes
+`release` creates the version commit and tag; the tag-triggered workflow publishes to npm. `release-status` verifies a clean, pushed workspace, the remote release tag, successful GitHub Actions runs for that tag, npm publication, and whether the declared `cf-genai-base` version is current. An older base version is shown in yellow with an upgrade command. `--wait` is one total timeout in minutes shared by GitHub Actions and npm polling; the default is five minutes. Use `release --version MAJOR.MINOR` to explicitly jump to a version such as `5.0`; the CLI assigns patch `0`, accepts an equal prepared manifest version when its tag and npm version do not exist, rejects older versions, and refuses any version already present on npm or GitHub. This is useful for synchronizing packages onto a common release line.

package/CONTRACT.md

@@ -90,8 +90,8 @@ them explicitly. Base cannot provide row-level security to
 direct D1 calls, so applications must keep raw database access out of domain
 features. The cookbook migration must add and backfill `tenant_id` on recipe
 tables, register recipes as tenant-scoped, replace direct D1 reads/writes with
-`state.data.tenant`, and add cross-tenant isolation tests. The companion
-`cf-genai-cli` should lint `cf-genai-*` working folders for direct
+`state.data.tenant`, and add cross-tenant isolation tests. The bundled
+`cf-genai` command lints `cf-genai-*` working folders for direct
 `env.DB.prepare(` usage as a follow-up enforcement check.
 Scoped write violations are returned as a generic 403 response; the detailed
 scope/resource identity is retained in the audit log only.

package/README.md

@@ -2,6 +2,10 @@
 
 Opinionated startup boilerplate for small Cloudflare Workers.
 
+The package also ships the `cf-genai` command. Runtime, administration, D1,
+project automation, and release tooling are versioned and published together;
+there is no separate CLI dependency.
+
 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.
@@ -32,6 +36,51 @@ 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.
 
+## Command-line tools
+
+Install base in a project (or globally) and use the bundled executable:
+
+```sh
+npm install @agilesyndrome/cf-genai-base
+npx cf-genai version
+
+cf-genai check
+cf-genai test
+cf-genai ci
+cf-genai dev
+cf-genai upgrade base latest
+cf-genai release --confirm
+cf-genai release-status --wait 3
+```
+
+Projects upgrading from the standalone package should remove
+`@agilesyndrome/cf-genai-cli`; their existing base dependency now supplies the
+same `cf-genai` executable.
+
+The CLI includes all commands formerly published by
+`@agilesyndrome/cf-genai-cli`: project checks and releases, scoped-data linting,
+package upgrades with migration vendoring, D1 refresh/backup/restore/migration,
+site status, and user, tenant, healthcheck, circuit-breaker, and platform admin
+operations.
+
+```sh
+cf-genai status --env staging
+cf-genai d1 refresh local
+cf-genai d1 migrate production --confirm-production
+cf-genai d1 backup production --output ./backup.sql --confirm-production
+cf-genai admin features --env staging
+cf-genai admin users --env staging
+cf-genai tenant list --env staging
+cf-genai user get someone@example.com --env staging
+cf-genai healthchecks set llm:provider red --env staging
+cf-genai circuit-breakers set llm:provider tripped --env staging
+```
+
+See [CLI.md](CLI.md) or run `cf-genai --help` for the complete command grammar. Credential loading
+stays outside the command, so a repository can continue to wrap it with
+`op run --env-file=.env.op --`. Destructive remote operations retain their
+existing explicit confirmation flags.
+
 ## Shared platform helpers
 
 `createWorker` can own `/health` and `/api/health`, and run a boot validator

package/bin/cf-genai.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+
+import { main } from "../src/cli/cli.js";
+
+try {
+  const result = await main(process.argv.slice(2));
+  if (result?.ok === false) process.exitCode = 1;
+} catch (error) {
+  console.error(`Error: ${error.message}`);
+  process.exitCode = 1;
+}

package/changelog.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## Unreleased
+
+- Fold the complete `cf-genai` operational CLI into this package so Worker,
+  admin, healthcheck, circuit-breaker, D1, project, and release tooling share a
+  single version and installation.
+- Publish the `cf-genai` executable and the programmatic `/cli` entrypoint from
+  `@agilesyndrome/cf-genai-base`.
+- Make base CI validate the bundled CLI directly instead of downloading the
+  retired `@agilesyndrome/cf-genai-cli` package.
+
 ## 5.0.0
 
 - Replace `@agilesyndrome/cf-genai-base/authorization` imports with `/auth`.

package/package.json

@@ -1,7 +1,10 @@
 {
   "name": "@agilesyndrome/cf-genai-base",
-  "version": "5.0.0",
+  "version": "5.0.1",
   "type": "module",
+  "bin": {
+    "cf-genai": "bin/cf-genai.js"
+  },
   "exports": {
     ".": "./src/index.js",
     "./auth": "./src/auth/index.js",
@@ -14,9 +17,14 @@
     "./core": "./src/core/index.js",
     "./ui": "./src/ui/index.js",
     "./ui/react": "./src/ui/react/index.jsx",
-    "./ui/styles.css": "./src/ui/styles.css"
+    "./ui/styles.css": "./src/ui/styles.css",
+    "./cli": "./src/cli/cli.js",
+    "./cli/*": "./src/cli/*.js"
+  },
+  "description": "Cloudflare Worker lifecycle, security, administration, and operational CLI helpers.",
+  "engines": {
+    "node": ">=20"
   },
-  "description": "Lean Worker lifecycle and security helpers for Cloudflare sites.",
   "license": "MIT",
   "peerDependencies": {
     "react": "^19.0.0"
@@ -26,9 +34,11 @@
     "provenance": true
   },
   "files": [
+    "bin",
     "src",
     "migrations",
     "README.md",
+    "CLI.md",
     "changelog.md",
     "CONTRACT.md",
     "LICENSE"
@@ -39,7 +49,7 @@
   },
   "homepage": "https://github.com/agilesyndrome/cf-genai-base#readme",
   "scripts": {
-    "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",
+    "check": "node --check bin/cf-genai.js && 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/auth/oauth-single.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 && node --check src/cli/cli.js && node --check src/cli/d1.js && node --check src/cli/operations.js && node --check src/cli/project.js && node --check src/cli/status.js && node --check src/cli/tenants.js && node --check src/cli/users.js && node --check src/cli/version.js",
     "test": "node --test tests/*.test.mjs",
     "build": "npm run check && npm test && npm pack --dry-run"
   }

package/src/auth/index.js

@@ -5,3 +5,4 @@ export * from "./tenants.js";
 export * from "./groups.js";
 export * from "./subscriptions.js";
 export * from "./impersonation.js";
+export * from "./oauth-single.js";

package/src/auth/oauth-single.js

@@ -0,0 +1,193 @@
+import { sameOrigin, secureJson, secureText } from "../core/security.js";
+import { ensureUser } from "./users.js";
+
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+const configurationCache = new Map();
+const configurationRequests = new Map();
+const jwksCache = new Map();
+const jwksRequests = new Map();
+const OIDC_CACHE_MS = 15 * 60 * 1000;
+const OIDC_TIMEOUT_MS = 10_000;
+export const OAUTH_SINGLE = "OAUTH_SINGLE";
+export const PACKAGE_NAME = "@agilesyndrome/cf-genai-base";
+export const VERSION = "5.0.0";
+
+export const authRepositoryDefinitions = [
+  { name: "users", resource: "auth_users", scope: "system", resourceDefinition: { name: "auth_users", table: "auth_users", scope: "system", columns: ["id", "provider", "subject", "email", "display_name", "is_admin", "created_at", "updated_at"], readableColumns: ["id", "provider", "subject", "email", "display_name", "is_admin", "created_at", "updated_at"], orderableColumns: ["id", "email", "created_at"], writableColumns: ["display_name", "is_admin"] } },
+  { name: "groups", resource: "auth_groups", scope: "system", resourceDefinition: { name: "auth_groups", table: "auth_groups", scope: "system", columns: ["name", "display_name", "description", "created_at", "updated_at"], idColumn: "name", readableColumns: ["name", "display_name", "description", "created_at", "updated_at"], orderableColumns: ["name", "created_at"], writableColumns: ["name", "display_name", "description"] } },
+];
+
+/**
+ * Generic OIDC auth for Workers. It uses Authorization Code + PKCE and a
+ * signed, host-only cookie, so a site needs no auth service of its own.
+ * Site-specific roles can be derived from `claims` in `onLogin`.
+ */
+export function createAuth(options = {}) {
+  const prefix = options.cookiePrefix || "__Host-cfgenai";
+  if (!/^(?:__Host-)?[A-Za-z0-9_-]+$/.test(prefix)) throw new Error("cookiePrefix contains invalid characters");
+  const names = { state: options.stateCookieName || `${prefix}_state`, session: options.sessionCookieName || `${prefix}_session` };
+  const publicPaths = options.publicPaths || ["/auth/", "/favicon.svg", "/robots.txt", "/health"];
+  const protectedPath = options.protectedPath || (() => true);
+  const envName = (key, fallback) => options.env?.[key] || fallback;
+
+  return {
+    name: "auth", displayName: options.displayName || "Authentication", packageName: PACKAGE_NAME, version: VERSION, strategy: OAUTH_SINGLE, repositories: options.repositories || authRepositoryDefinitions,
+    dataResources: options.dataResources || [], routes: options.routes || [],
+    healthchecks: options.healthchecks || [], circuitBreakers: options.circuitBreakers || [],
+    async handle(request, env) {
+      const url = new URL(request.url);
+      if (url.pathname === "/auth/login") return login(request, env);
+      if (url.pathname === "/auth/callback") return callback(request, env);
+      if (url.pathname === "/auth/logout") {
+        if (request.method !== "POST") return new Response("Method Not Allowed", { status: 405, headers: { Allow: "POST", "Cache-Control": "no-store" } });
+        const originResponse = checkOrigin(request, options.allowedOrigins);
+        if (originResponse) return originResponse;
+        return logout(request, env, names.session, options);
+      }
+      if (url.pathname === "/api/me") return secureJson({ user: publicUser(await resolveUser(request, env)) });
+      if (!protectedPath(url.pathname) || publicPaths.some((path) => path === "/" ? url.pathname === "/" : url.pathname.startsWith(path))) return null;
+      if (isMutation(request)) { const originResponse = checkOrigin(request, options.allowedOrigins); if (originResponse) return originResponse; }
+      const user = await resolveUser(request, env);
+      if (user && options.authorize && !(await options.authorize({ request, url, user, env }))) {
+        return url.pathname.startsWith("/api/") ? Response.json({ error: "Administrator access is required." }, { status: 403, headers: { "Cache-Control": "no-store" } }) : authError("Administrator access is required.", 403);
+      }
+      if (user) return null;
+      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);
+    },
+    getUser: (request, env) => resolveUser(request, env),
+    healthcheck: async (env) => ({ feature: "auth", component: "configuration", displayName: "Authentication configuration", state: Boolean(env?.DB) && [envName("issuer", "OIDC_ISSUER"), envName("clientId", "OIDC_CLIENT_ID"), envName("clientSecret", "OIDC_CLIENT_SECRET"), envName("sessionSecret", "AUTH_SESSION_SECRET")].every((key) => env?.[key] && !String(env[key]).startsWith("replace-with-")) ? "green" : "red" }),
+    middleware(request, env, ctx, next, state) {
+      return this.handle(request, env, ctx).then((response) => response || next(request, env, ctx, state));
+    },
+  };
+
+  async function login(request, env) {
+    if (options.getSession && await resolveUser(request, env)) {
+      const target = safeReturnTo(new URL(request.url).searchParams.get("return_to") || "/");
+      return redirect(new URL(request.url).origin + target, [clearCookie(names.state)]);
+    }
+    const config = await configuration(env, options);
+    const state = random();
+    const verifier = random();
+    const nonce = random();
+    const challenge = base64url(new Uint8Array(await crypto.subtle.digest("SHA-256", encoder.encode(verifier))));
+    const returnTo = safeReturnTo(new URL(request.url).searchParams.get("return_to") || "/");
+    const stateValue = `${state}.${verifier}.${nonce}.${base64url(encoder.encode(returnTo))}`;
+    const authorize = new URL(config.authorization_endpoint);
+    authorize.search = new URLSearchParams({ client_id: required(env, envName("clientId", "OIDC_CLIENT_ID")), response_type: "code", redirect_uri: callbackUrl(request, env, options), scope: options.scope || "openid profile email", state, code_challenge: challenge, code_challenge_method: "S256", nonce }).toString();
+    return redirect(authorize, [cookie(names.state, stateValue, 600)]);
+  }
+
+  async function callback(request, env) {
+    const url = new URL(request.url);
+    const value = cookies(request)[names.state] || "";
+    const [state, verifier, nonce, encodedReturn] = value.split(".");
+    if (!state || !constantTimeEqual(state, url.searchParams.get("state") || "") || !verifier) {
+      if (options.getSession && await resolveUser(request, env)) return redirect(new URL(request.url).origin, [clearCookie(names.state)]);
+      return authError("The sign-in state was invalid or expired.", 400);
+    }
+    const config = await configuration(env, options);
+    const clientId = required(env, envName("clientId", "OIDC_CLIENT_ID"));
+    const token = await fetchWithTimeout(config.token_endpoint, { method: "POST", headers: { "Content-Type": "application/x-www-form-urlencoded" }, body: new URLSearchParams({ client_id: clientId, client_secret: required(env, envName("clientSecret", "OIDC_CLIENT_SECRET")), grant_type: "authorization_code", code: url.searchParams.get("code") || "", redirect_uri: callbackUrl(request, env, options), code_verifier: verifier }) }).then((response) => response.ok ? response.json() : Promise.reject(new Error("OIDC token exchange failed")));
+    const claims = await verify(token.id_token, config, clientId, nonce);
+    if (!claims.sub) return authError("The identity provider returned no subject.", 502);
+    const user = await resolveLoginUser({ ...(await (options.onLogin ? options.onLogin(claims, env) : normalizeUser(claims))), email_verified: claims.email_verified === true }, env, request);
+    const identity = sessionIdentity(user);
+    const signed = options.createSession ? await options.createSession(identity, env, request) : await sign(JSON.stringify({ ...identity, exp: Math.floor(Date.now() / 1000) + (options.sessionSeconds || 28800) }), env, envName("sessionSecret", "AUTH_SESSION_SECRET"));
+    await env.event?.("auth.login.succeeded", "auth", { userId: user.authUser.id });
+    return redirect(`${url.origin}${decodeReturn(encodedReturn)}`, [cookie(names.session, signed, options.sessionSeconds || 28800), clearCookie(names.state)]);
+  }
+  async function resolveUser(request, env) {
+    const user = await hydrateUser(await getUser(request, env, envName("sessionSecret", "AUTH_SESSION_SECRET"), names.session, options), env);
+    if (user && options.sessionAuthorize && !(await options.sessionAuthorize({ user, request, env }))) return null;
+    return user;
+  }
+
+  async function resolveLoginUser(user, env, request) {
+    const hydrated = await hydrateUser(user, env);
+    if (options.loginAuthorize && !(await options.loginAuthorize({ user: hydrated, request, env }))) throw authError("Authentication is not currently permitted.", 403);
+    return hydrated;
+  }
+}
+
+async function hydrateUser(user, env) {
+  if (!user) return user;
+  if (!env?.DB) throw new Error("OAUTH_SINGLE requires the base DB binding for canonical users");
+  const authUser = await ensureUser(env, user, { who: `user:${user.sub || "unknown"}` });
+  return { ...user, authUser };
+}
+
+async function getUser(request, env, secretName = "AUTH_SESSION_SECRET", sessionName = "__Host-cfgenai_session", options = {}) {
+  const token = cookies(request)[sessionName];
+  if (!token) return null;
+  if (options.getSession) return (await options.getSession(token, env, request)) || null;
+  const [payload, signature] = token.split(".");
+  if (!payload || !signature || !constantTimeEqual(signature, await sign(payload, env, secretName, false))) return null;
+  try { const user = JSON.parse(decoder.decode(decode(payload))); return typeof user.exp === "number" && user.exp > Date.now() / 1000 ? user : null; } catch { return null; }
+}
+
+async function configuration(env, options = {}) {
+  const discoveryName = envNameFor(options, "discoveryUrl", "OIDC_DISCOVERY_URL");
+  const configuredDiscovery = env[discoveryName];
+  const discoveryUrl = configuredDiscovery ? (String(configuredDiscovery).endsWith("/.well-known/openid-configuration") ? configuredDiscovery : String(configuredDiscovery).replace(/\/+$/, "") + "/.well-known/openid-configuration") : normalizeIssuer(required(env, envNameFor(options, "issuer", "OIDC_ISSUER"))).slice(0, -1) + "/.well-known/openid-configuration";
+  if (new URL(discoveryUrl).protocol !== "https:") throw new Error("OIDC discovery URL must use HTTPS");
+
+  const cached = configurationCache.get(discoveryUrl); if (cached && cached.exp > Date.now()) return cached.value;
+  const existing = configurationRequests.get(discoveryUrl); if (existing) return existing;
+  const request = fetchWithTimeout(discoveryUrl).then(async (response) => {
+    if (!response.ok) throw new Error("Unable to load OIDC configuration");
+    const value = await response.json();
+    if (!value.issuer || new URL(value.issuer).protocol !== "https:") throw new Error("OIDC configuration returned an invalid issuer");
+    if (!value.jwks_uri || new URL(value.jwks_uri).protocol !== "https:") throw new Error("OIDC configuration returned an invalid JWKS URL");
+    configurationCache.set(discoveryUrl, { value, exp: Date.now() + OIDC_CACHE_MS }); return value;
+  }).finally(() => configurationRequests.delete(discoveryUrl));
+  configurationRequests.set(discoveryUrl, request); return request;
+}
+async function verify(token, config, clientId, expectedNonce) {
+  const [head, body, signature] = String(token || "").split("."); if (!head || !body || !signature) throw new Error("Malformed ID token");
+  const header = JSON.parse(decoder.decode(decode(head))); if (header.alg !== "RS256" || !header.kid) throw new Error("Unsupported ID token signature"); const keys = await getJwks(config.jwks_uri); const jwk = keys.keys.find((key) => key.kid === header.kid); if (!jwk) throw new Error("ID token signing key was not found");
+  const key = await crypto.subtle.importKey("jwk", jwk, { name: "RSASSA-PKCS1-v1_5", hash: "SHA-256" }, false, ["verify"]);
+  if (!await crypto.subtle.verify("RSASSA-PKCS1-v1_5", key, decode(signature), encoder.encode(`${head}.${body}`))) throw new Error("Invalid ID token");
+  const claims = JSON.parse(decoder.decode(decode(body))); const aud = Array.isArray(claims.aud) ? claims.aud : [claims.aud]; const validAzp = !Array.isArray(claims.aud) || claims.aud.length < 2 || claims.azp === clientId;
+  if (normalizeIssuer(claims.iss || "") !== normalizeIssuer(config.issuer || "") || !aud.includes(clientId) || !validAzp || claims.exp <= Date.now() / 1000 || claims.nonce !== expectedNonce || !claims.sub) throw new Error("Invalid ID token claims"); return claims;
+}
+async function getJwks(uri) {
+  const cached = jwksCache.get(uri); if (cached && cached.exp > Date.now()) return cached.value;
+  const existing = jwksRequests.get(uri); if (existing) return existing;
+  const request = fetchWithTimeout(uri).then(async (response) => { if (!response.ok) throw new Error("Unable to load OIDC signing keys"); const value = await response.json(); jwksCache.set(uri, { value, exp: Date.now() + OIDC_CACHE_MS }); return value; }).finally(() => jwksRequests.delete(uri));
+  jwksRequests.set(uri, request); return request;
+}
+async function fetchWithTimeout(input, init = {}) { return fetch(input, { ...init, signal: AbortSignal.timeout(OIDC_TIMEOUT_MS) }); }
+function normalizeIssuer(value) { return String(value).replace(/\/+$/, "") + "/"; }
+function isMutation(request) { return ["POST", "PUT", "PATCH", "DELETE"].includes(request.method); }
+function checkOrigin(request, allowedOrigins = []) {
+  let requestOrigin;
+  try { requestOrigin = new URL(request.url).origin; } catch { return authError("This request did not pass the same-origin check.", 403); }
+  return sameOrigin(request, [requestOrigin, ...allowedOrigins]) ? null : authError("A same-origin request is required.", 403);
+}
+async function sign(value, env, name, encoded = true) { const secret = required(env, name); if (name === "AUTH_SESSION_SECRET" && secret.length < 32) throw new Error("AUTH_SESSION_SECRET must be at least 32 characters"); const data = encoded ? base64url(encoder.encode(value)) : value; const key = await crypto.subtle.importKey("raw", encoder.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]); const sig = base64url(new Uint8Array(await crypto.subtle.sign("HMAC", key, encoder.encode(data)))); return encoded ? `${data}.${sig}` : sig; }
+function normalizeUser(claims) { return { sub: claims.sub, email: String(claims.email || "").toLowerCase(), name: claims.name || claims.email || claims.sub, email_verified: claims.email_verified === true, auth_strategy: OAUTH_SINGLE }; }
+function envNameFor(options, key, fallback) { return options.env?.[key] || fallback; }
+function required(env, key) { if (!env[key] || String(env[key]).startsWith("replace-with-")) throw new Error(`${key} is not configured`); return String(env[key]); }
+function random() { const bytes = new Uint8Array(32); crypto.getRandomValues(bytes); return base64url(bytes); }
+function base64url(bytes) { let s = ""; for (const b of bytes) s += String.fromCharCode(b); return btoa(s).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, ""); }
+function decode(value) { return Uint8Array.from(atob(value.replace(/-/g, "+").replace(/_/g, "/") + "=".repeat((4 - value.length % 4) % 4)), (c) => c.charCodeAt(0)); }
+function cookies(request) { return Object.fromEntries((request.headers.get("Cookie") || "").split(";").flatMap((part) => { const i = part.indexOf("="); return i < 0 ? [] : [[part.slice(0, i).trim(), part.slice(i + 1).trim()]]; })); }
+function cookie(name, value, age) { return `${name}=${value}; Max-Age=${age}; Path=/; HttpOnly; Secure; SameSite=Lax`; }
+function clearCookie(name) { return `${name}=; Max-Age=0; Path=/; HttpOnly; Secure; SameSite=Lax`; }
+function redirect(location, setCookies) { const response = new Response(null, { status: 302, headers: { Location: String(location), "Cache-Control": "no-store" } }); for (const value of setCookies) response.headers.append("Set-Cookie", value); return response; }
+async function logout(request, env, name, options = {}) {
+  const token = cookies(request)[name];
+  if (token && options.revokeSession) await options.revokeSession(token, env, request);
+  await env.event?.("auth.logout", "auth");
+  return redirect(new URL(request.url).origin + "/", [clearCookie(name)]);
+}
+function authError(message, status) { return secureText(message, status); }
+function callbackUrl(request, env, options) { const configuredOrigin = env[envNameFor(options, "publicOrigin", "PUBLIC_ORIGIN")]; return (configuredOrigin ? new URL(String(configuredOrigin)).origin : new URL(request.url).origin) + "/auth/callback"; }
+function safeReturnTo(value) { return value?.startsWith("/") && !value.startsWith("//") && !value.startsWith("/auth/") ? value : "/"; }
+function decodeReturn(value) { try { return safeReturnTo(decoder.decode(decode(value))); } catch { return "/"; } }
+function constantTimeEqual(a, b) { const aa = encoder.encode(a), bb = encoder.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; }
+function sessionIdentity(user) { const { authUser: _authUser, exp: _exp, ...identity } = user || {}; return identity; }
+function publicUser(user) { return user ? { id: user.authUser.id, email: user.email || user.authUser.email, name: user.name || user.authUser.display_name, isAdmin: Boolean(user.authUser.is_admin) } : null; }

package/src/cli/cli.js

@@ -0,0 +1,133 @@
+import { backupD1, checkConfig, checkD1, migrateD1, refreshLocalD1, refreshStagingD1, restoreD1, statusD1 } from "./d1.js";
+import { runUserCommand } from "./users.js";
+import { runTenantCommand } from "./tenants.js";
+import { runOperationalCommand } from "./operations.js";
+import { runProjectCommand } from "./project.js";
+import { runVersionCommand } from "./version.js";
+import { siteStatus } from "./status.js";
+
+const usage = `Usage:
+  cf-genai check|test|build|ci|ci:lint
+  cf-genai lint data-access
+  cf-genai dev [options]
+  cf-genai upgrade <base|auth|llm|messaging> <latest|VERSION>
+  cf-genai release [--confirm] [--first] [--add-trust] [--dry-run] [--bypass-lint] [--type patch|minor|major] [--version MAJOR.MINOR]
+  cf-genai release-status [--wait MINUTES] [--json]
+    cf-genai status [--env local|staging|production] [--json]
+  cf-genai version
+  cf-genai d1 refresh|backup|restore|migrate|status|check local|staging|production [options]
+  cf-genai admin status|features|users|tenants|scopes|groups|healthchecks|circuit-breakers [options]
+  cf-genai config check [options]
+  cf-genai user list|get|update [username] [options]
+  cf-genai tenant list|get|create|update [tenant-id] [options]
+
+Options:
+  --database NAME             D1 binding or database name (default: DB)
+  --production-database NAME  Production D1 binding or database name
+  --production-env NAME       Wrangler production environment (default: none)
+  --staging-env NAME          Wrangler staging environment (default: staging)
+  --config PATH               Wrangler config path (default: wrangler.jsonc)
+  --env VALUE                 Environment alias: local, staging, or prod
+  --output PATH               Backup output file
+  --file PATH                 Restore input file
+  --wrangler COMMAND          Wrangler command (default: npx wrangler)
+  --yes                       Confirm a remote staging refresh
+  --confirm-production        Explicitly permit production migration or breaker changes
+  --confirm                    Confirm a destructive or release operation
+  --dry-run                    Show release checks without changing Git or npm
+  --version MAJOR.MINOR        Explicit release target; patch is assigned as .0
+  --bypass-lint                Skip the release preflight lint (use sparingly)
+  --json                      Return machine-readable output
+  --help                      Show this help
+`;
+
+function splitCommand(value = "npx wrangler") {
+  return value.match(/(?:[^\s"']+|"[^"]*"|'[^']*')+/g)?.map((part) => part.replace(/^(["'])(.*)\1$/, "$2")) ?? ["npx", "wrangler"];
+}
+
+function parseOptions(args, env = process.env) {
+  const options = {
+    config: env.CF_GENAI_WRANGLER_CONFIG || "wrangler.jsonc",
+    database: env.CF_GENAI_DATABASE || "DB",
+    productionEnv: env.CF_GENAI_PRODUCTION_ENV || "",
+    stagingEnv: env.CF_GENAI_STAGING_ENV || "staging",
+    wranglerCommand: splitCommand(env.CF_GENAI_WRANGLER || "npx wrangler"),
+    yes: false,
+    confirmProduction: false,
+    target: env.CF_GENAI_TARGET || "local",
+    roles: undefined,
+    scopes: undefined,
+    groups: undefined,
+    tenants: undefined,
+    name: undefined,
+    json: false,
+  };
+  const positional = [];
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--help" || arg === "-h") return { ...options, help: true, positional };
+    if (arg === "--yes") options.yes = true;
+    else if (arg === "--json") options.json = true
+    else if (arg === "--confirm-production") options.confirmProduction = true;
+    else if (arg.startsWith("--")) {
+      const [key, inline] = arg.slice(2).split("=", 2);
+      const names = {
+        database: "database", "production-database": "productionDatabase",
+        "production-env": "productionEnv", "staging-env": "stagingEnv",
+        config: "config", wrangler: "wrangler", target: "target", env: "target", roles: "roles", scopes: "scopes", groups: "groups", tenants: "tenants", name: "name", output: "output", file: "file",
+      };
+      const optionName = names[key];
+      if (!optionName) throw new Error(`Unknown option: ${arg}`);
+      const value = inline ?? args[++index];
+      if (value === undefined) throw new Error(`Missing value for ${arg}.`);
+      if (optionName === "wrangler") options.wranglerCommand = splitCommand(value);
+      else options[optionName] = value;
+    } else positional.push(arg);
+  }
+  return { ...options, positional, productionDatabase: options.productionDatabase || options.database };
+}
+
+export async function main(args = process.argv.slice(2), env = process.env) {
+  if (args[0]?.includes(":")) { const [domain, action] = args[0].split(":", 2); if (["user", "tenant", "healthcheck", "healthchecks", "circuit-breaker", "circuit-breakers", "circuit"].includes(domain)) args = [domain, action, ...args.slice(1)]; }
+  if (args[0] === "version") return runVersionCommand();
+  const projectCommand = args[0];
+  if (["check", "test", "build", "ci", "ci:lint", "lint", "dev", "upgrade", "release", "release-status"].includes(projectCommand)) {
+    const result = runProjectCommand(projectCommand, args.slice(1));
+    if (result === null) throw new Error(`Unknown command.\n\n${usage}`);
+    return result;
+  }
+  const options = parseOptions(args, env);
+  if (options.positional[0] === "status") return siteStatus(options);
+  if (options.help || options.positional.length === 0) {
+    console.log(usage);
+    return;
+  }
+  let [domain, action, target] = options.positional;
+  if (domain === "admin") { const adminAction = { user: "users", tenant: "tenants", healthcheck: "healthchecks", "circuit-breaker": "circuit-breakers", circuit: "circuit-breakers" }[action] || action; if (["local", "staging", "prod", "production"].includes(target)) options.target = target === "prod" ? "production" : target; if (adminAction === "tenants") return runTenantCommand({ action: options.positional[2] || "list", identifier: options.positional[3], name: options.name, options }); if (["healthchecks", "circuit-breakers"].includes(adminAction)) return runOperationalCommand({ domain: adminAction, action: options.positional[2] || "list", identifier: options.positional[3], value: options.positional[4], options }); return runOperationalCommand({ domain: "admin", action: adminAction, identifier: options.positional[3], value: options.positional[4], options }); }
+  if (domain === "backup" || domain === "restore") { target = action || options.target; action = domain; return runD1FileCommand(action, target, options); }
+  if (domain === "user") return runUserCommand({ action, username: target, options });
+  if (domain === "tenant") return runTenantCommand({ action, identifier: target, name: options.name, options });
+  if (["healthcheck", "healthchecks", "circuit-breaker", "circuit-breakers", "circuit"].includes(domain)) return runOperationalCommand({ domain, action, identifier: target, value: options.positional[3], options });
+  if (domain === "config" && action === "check") return checkConfig(options);
+  if (domain !== "d1" || !["refresh", "backup", "restore", "migrate", "status", "check"].includes(action)) throw new Error(`Unknown command.\n\n${usage}`);
+  target = target === "prod" ? "production" : target;
+  if (!["local", "staging", "production"].includes(target)) throw new Error("Target must be local, staging, or production.");
+  if (action === "backup" || action === "restore") return runD1FileCommand(action, target, options);
+  if (action === "refresh") {
+    if (target === "staging" && !options.yes) throw new Error("Staging refresh replaces remote data; rerun with --yes.");
+    if (target === "local") return refreshLocalD1({ database: options.database, productionDatabase: options.productionDatabase, options });
+    if (target === "staging") return refreshStagingD1({ database: options.database, productionDatabase: options.productionDatabase, options });
+    throw new Error(`Unknown command.\n\n${usage}`);
+  }
+  if (action === "migrate" && target === "production" && !options.confirmProduction) throw new Error("Production migration requires --confirm-production.");
+  if (action === "migrate") return migrateD1({ target, database: options.database, options });
+  if (action === "status") return statusD1({ target, database: options.database, options });
+  return checkD1({ target, database: options.database, options });
+}
+
+function runD1FileCommand(action, target, options) {
+  if (action === "backup") return backupD1({ target, database: options.database, options });
+  return restoreD1({ target, database: options.database, options });
+}
+
+export { parseOptions, usage };