@agilesyndrome/cf-genai-base 4.1.3 → 5.0.1

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,8 @@
+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";
+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/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;
+}

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/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 };