@agilesyndrome/cf-genai-base 2.0.1 → 2.1.2

package/CONTRACT.md

@@ -18,7 +18,7 @@ is optional and must use `ctx.waitUntil` for background work.
 - `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. `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 `GET /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 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.
 - Public APIs must be explicitly listed in provider-specific auth configuration.
 - Mutating `/api/*` requests require a same-origin `Origin` header.
 
@@ -61,9 +61,11 @@ must remain in the application router rather than in the shared auth package.
 manifest through `feature.dataResources`. Each resource must declare a safe
 name, table, explicit columns, and one scope: `user`, `tenant`, or `system`.
 Resources may also declare allowed operations (`read`, `create`, `update`, and
-`delete`); reads support bounded cursor pagination through `reader.page()`.
-Anonymous tenant reads require an explicit worker `publicTenantId` and a
-resource-level `publicRead: true` declaration.
+`delete`); reads support bounded native pagination through
+`reader.page({ limit, offset })` and `reader.count()`, plus safe filtered
+updates and deletes. Anonymous tenant reads require an explicit worker
+`publicTenantId` and a resource-level `publicRead` declaration; object form
+adds a row visibility predicate.
 Request handlers receive `state.data`, whose scope-specific readers apply the
 validated user or tenant predicate. Domain handlers must not use unrestricted
 `env.DB` for registered resources. Base cannot provide row-level security to

package/README.md

@@ -78,12 +78,27 @@ 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`;
-the reader applies ownership predicates, supports bounded cursor pagination via
-`.page()`, and never accepts raw SQL. Resources can explicitly restrict their
-operations to `read`, `create`, `update`, and `delete`.
-
-Anonymous tenant reads require both `publicTenantId` on `createWorker` and
-`publicRead: true` on the resource; they never grant anonymous system access.
+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
+their operations to read, create, update, and delete.
+
+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.
+
+Applications may pass subscriptionManifest to createWorker to register their
+own subscription IDs and entitlement values. Base exposes
+requireSubscription and requireEntitlement but does not know any
+product-specific subscription such as VIP. Authenticated users can inspect
+their validated active tenant at GET /api/tenant.
+
+Administrators can start a short-lived, HttpOnly impersonation session with
+POST /api/admin/users/:id/impersonate and clear it with
+POST /api/admin/impersonate/clear. Impersonation affects scoped data context
+only and does not grant the target user administrator permissions.
 
 For example, a tenant-owned resource registers its `tenant_id` column with
 base, while feature code calls `state.data.tenant.list("recipes")` without

package/migrations/0004_tenants.sql

@@ -35,11 +35,5 @@ CREATE INDEX IF NOT EXISTS auth_user_tenants_tenant_idx
 INSERT OR IGNORE INTO auth_tenants (id, name)
 VALUES ('easley-family', 'Easley Family');
 
-INSERT OR IGNORE INTO auth_subscriptions (id, name)
-VALUES ('vip', 'VIP');
-
-INSERT OR IGNORE INTO auth_tenant_subscriptions (tenant_id, subscription_id)
-VALUES ('easley-family', 'vip');
-
 INSERT OR IGNORE INTO auth_user_tenants (user_id, tenant_id)
 SELECT id, 'easley-family' FROM auth_users;

package/migrations/0005_subscription_entitlements.sql

@@ -0,0 +1,13 @@
+-- Application-defined subscription capabilities. Base stores the contract;
+-- applications decide which subscriptions and entitlement keys they expose.
+CREATE TABLE IF NOT EXISTS auth_subscription_entitlements (
+  subscription_id TEXT NOT NULL REFERENCES auth_subscriptions(id) ON DELETE CASCADE,
+  entitlement TEXT NOT NULL,
+  value_json TEXT NOT NULL DEFAULT 'true',
+  created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  updated_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  PRIMARY KEY (subscription_id, entitlement)
+);
+
+CREATE INDEX IF NOT EXISTS auth_subscription_entitlements_key_idx
+  ON auth_subscription_entitlements(entitlement);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agilesyndrome/cf-genai-base",
-  "version": "2.0.1",
+  "version": "2.1.2",
   "type": "module",
   "exports": {
     ".": "./src/index.js",

package/src/authorization.js

@@ -5,8 +5,10 @@ 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 const DEFAULT_SUBSCRIPTION_ID = "vip";
-export const DEFAULT_SUBSCRIPTION_NAME = "VIP";
+
+export class SubscriptionError extends Error {
+  constructor(message) { super(message); this.name = "SubscriptionError"; }
+}
 
 export function normalizeScopes(scopes = []) {
   return scopes.map((scope) => typeof scope === "string" ? { name: scope, label: scope, description: "", system: false } : scope)
@@ -44,8 +46,6 @@ export async function ensureUser(env, user, { who = "system:read" } = {}) {
 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_subscriptions (id,name) VALUES (?,?)").bind(DEFAULT_SUBSCRIPTION_ID, DEFAULT_SUBSCRIPTION_NAME),
-    db.prepare("INSERT OR IGNORE INTO auth_tenant_subscriptions (tenant_id,subscription_id) VALUES (?,?)").bind(DEFAULT_TENANT_ID, DEFAULT_SUBSCRIPTION_ID),
     db.prepare("INSERT OR IGNORE INTO auth_user_tenants (user_id,tenant_id) VALUES (?,?)").bind(userId, DEFAULT_TENANT_ID)
   ]);
 }
@@ -59,7 +59,70 @@ export async function listUserTenants(env, userId, { who = "system:read" } = {})
 export async function listTenantSubscriptions(env, tenantId, { who = "system:read" } = {}) {
   const db = createD1(env, { who });
   const { results } = await db.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 results || [];
+  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 db = createD1(env, { who });
+  const { results } = await db.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" } = {}) {
+  const db = createD1(env, { who });
+  return Boolean(await db.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 db = createD1(env, { who });
+  const rows = await db.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;
+}
+
+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; }
 }
 
 export async function hasScope(env, user, scope, { who = "system:read" } = {}) {
@@ -77,6 +140,11 @@ export async function listAuthorizationUsers(env, { who = "system:read" } = {})
   return Promise.all(results.map(async (user) => ({ ...user, scopes: (await listUserGrants(env, user.id, { who })).map((grant) => grant.scope_name) })));
 }
 
+export async function getAuthorizationUser(env, userId, { who = "system:read" } = {}) {
+  const db = createD1(env, { who });
+  return db.prepare(`SELECT id,email,display_name,provider,subject,is_admin,created_at,updated_at FROM ${AUTH_USER_TABLE} WHERE id=?`).bind(userId).first();
+}
+
 export async function listAuthorizationScopes(env, { who = "system:read" } = {}) {
   const db = createD1(env, { who });
   const { results } = await db.prepare(`SELECT name,label,description,system FROM ${AUTH_SCOPE_TABLE} ORDER BY name`).all();
@@ -110,3 +178,10 @@ 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);
 }
+
+function parseJsonValue(value) { try { return JSON.parse(value); } catch { return value; } }
+function deepEqual(left, right) { return JSON.stringify(left) === JSON.stringify(right); }
+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)); }
+function base64url(bytes) { return btoa(String.fromCharCode(...bytes)).replaceAll("+", "-").replaceAll("/", "_").replaceAll("=", ""); }
+function base64urlDecode(value) { const padded = value.replaceAll("-", "+").replaceAll("_", "/") + "=".repeat((4 - value.length % 4) % 4); return Uint8Array.from(atob(padded), (char) => char.charCodeAt(0)); }
+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/data.js

@@ -1,5 +1,5 @@
 import { auditLog, createD1 } from "./core.js";
-import { ensureUser, listUserTenants } from "./authorization.js";
+import { ensureUser, getAuthorizationUser, listUserGrants, listUserTenants, verifyImpersonationToken } from "./authorization.js";
 
 export const DATA_SCOPES = ["user", "tenant", "system"];
 export const DATA_OPERATIONS = ["read", "create", "update", "delete"];
@@ -34,9 +34,13 @@ export function normalizeDataResources(resources = []) {
     for (const column of [...filterableColumns, ...orderableColumns]) if (!columns.includes(column)) throw new TypeError(`Data resource ${resource.name} references an unselected column`);
     const writableColumns = [...new Set((resource.writableColumns || []).map(String))].filter((column) => column !== ownerColumn && column !== tenantColumn);
     if (writableColumns.some((column) => !columns.includes(column))) throw new TypeError(`Data resource ${resource.name} references an unwritable column`);
+    const columnScopes = Object.fromEntries(Object.entries(resource.columnScopes || {}).map(([column, scopes]) => [String(column), Array.isArray(scopes) ? scopes.map(String) : [String(scopes)]]));
+    if (Object.keys(columnScopes).some((column) => !columns.includes(column) || columnScopes[column].some((scope) => !/^[a-z0-9]+(?::[a-z0-9-]+)+$/.test(scope)))) throw new TypeError(`Data resource ${resource.name} has invalid column scopes`);
     const operations = [...new Set((resource.operations || ["read", ...(writableColumns.length ? ["create", "update", "delete"] : [])]).map((operation) => String(operation).toLowerCase()))];
     if (!operations.length || operations.some((operation) => !DATA_OPERATIONS.includes(operation)) || !operations.includes("read")) throw new TypeError(`Data resource ${name} has invalid operations`);
-    return { ...resource, name, table: String(resource.table), scope, columns, idColumn, ownerColumn, tenantColumn, filterableColumns, orderableColumns, writableColumns, operations, publicRead: Boolean(resource.publicRead) };
+    const publicRead = resource.publicRead && typeof resource.publicRead === "object" ? { column: String(resource.publicRead.column || ""), value: resource.publicRead.value } : Boolean(resource.publicRead);
+    if (publicRead && typeof publicRead === "object" && (!/^[a-z][a-z0-9_]*$/.test(publicRead.column) || !columns.includes(publicRead.column))) throw new TypeError(`Public resource ${resource.name} requires a selected visibility column`);
+    return { ...resource, name, table: String(resource.table), scope, columns, idColumn, ownerColumn, tenantColumn, filterableColumns, orderableColumns, writableColumns, columnScopes, operations, publicRead };
   });
 }
 
@@ -46,17 +50,20 @@ export function createDataReader(env, { resources = [], context } = {}) {
   const scope = (requestedScope) => ({
     list: (name, options) => readList(name, requestedScope, options),
     page: (name, options) => readPage(name, requestedScope, options),
+    count: (name, options) => readCount(name, requestedScope, options),
     get: async (name, id) => (await readList(name, requestedScope, { where: { [registry.get(name)?.idColumn || "id"]: id }, limit: 1 }))[0] || null,
     insert: (name, values) => writeInsert(name, requestedScope, values),
     update: (name, id, changes) => writeUpdate(name, requestedScope, id, changes),
+    updateWhere: (name, where, changes) => writeUpdateWhere(name, requestedScope, where, changes),
     delete: (name, id) => writeDelete(name, requestedScope, id),
+    deleteWhere: (name, where) => writeDeleteWhere(name, requestedScope, where),
   });
 
-  async function readList(name, requestedScope, { where = {}, limit = 100, orderBy } = {}) {
-    return (await readPage(name, requestedScope, { where, limit, orderBy })).rows;
+  async function readList(name, requestedScope, { where = {}, limit = 100, orderBy, offset = 0 } = {}) {
+    return (await readPage(name, requestedScope, { where, limit, orderBy, offset })).rows;
   }
 
-  async function readPage(name, requestedScope, { where = {}, limit = 100, orderBy, cursor } = {}) {
+  async function readPage(name, requestedScope, { where = {}, limit = 100, orderBy, cursor, offset = 0 } = {}) {
     const resource = getResource(name);
     const actor = await getContext();
     if (!isAllowed(resource, requestedScope, actor, "read")) return { rows: [], nextCursor: null };
@@ -66,7 +73,8 @@ export function createDataReader(env, { resources = [], context } = {}) {
     addFilters(resource, where, predicates, bindings);
     if (cursor !== undefined && cursor !== null) { predicates.push(`${quote(resource.idColumn)}>?`); bindings.push(cursor); }
     const safeLimit = Math.min(Math.max(Number(limit) || 100, 1), 1000);
-    let sql = `SELECT ${resource.columns.map(quote).join(",")} FROM ${quote(resource.table)}${predicates.length ? ` WHERE ${predicates.join(" AND ")}` : ""} LIMIT ${safeLimit}`;
+    const safeOffset = Math.max(Number(offset) || 0, 0);
+    let sql = `SELECT ${resource.columns.map(quote).join(",")} FROM ${quote(resource.table)}${predicates.length ? ` WHERE ${predicates.join(" AND ")}` : ""} LIMIT ${safeLimit} OFFSET ${safeOffset}`;
     if (orderBy) {
       const [column, direction = "ASC"] = String(orderBy).split(/\s+/, 2);
       if (!resource.orderableColumns.includes(column)) throw new TypeError(`Column ${column} cannot order ${resource.name}`);
@@ -77,16 +85,30 @@ export function createDataReader(env, { resources = [], context } = {}) {
     return { rows, nextCursor: rows.length === safeLimit ? rows[rows.length - 1][resource.idColumn] : null };
   }
 
+  async function readCount(name, requestedScope, { where = {} } = {}) {
+    const resource = getResource(name);
+    const actor = await getContext();
+    if (!isAllowed(resource, requestedScope, actor, "read")) return 0;
+    const predicates = [];
+    const bindings = [];
+    addScopePredicate(resource, requestedScope, actor, predicates, bindings);
+    addFilters(resource, where, predicates, bindings);
+    const result = await createD1(env, { who: actorLabel(actor) }).prepare(`SELECT COUNT(*) AS count FROM ${quote(resource.table)}${predicates.length ? ` WHERE ${predicates.join(" AND ")}` : ""}`).bind(...bindings).first();
+    return Number(result?.count || 0);
+  }
+
   async function writeInsert(name, requestedScope, values = {}) {
     const resource = getResource(name);
     const actor = await getContext();
     assertWritable(resource, requestedScope, actor, "create");
     const data = cleanWritableValues(resource, values, { includeId: true, includeOwnership: requestedScope === "system" });
+    assertColumnScopes(resource, actor, Object.keys(data));
     addOwnedValue(resource, requestedScope, actor, data);
     const columns = Object.keys(data);
     if (!columns.length) throw new TypeError(`No writable values supplied for ${resource.name}`);
-    await createD1(env, { who: actorLabel(actor) }).prepare(`INSERT INTO ${quote(resource.table)} (${columns.map(quote).join(",")}) VALUES (${columns.map(() => "?").join(",")})`).bind(...columns.map((column) => data[column])).run();
-    return data[resource.idColumn] === undefined ? data : (await readList(name, requestedScope, { where: { [resource.idColumn]: data[resource.idColumn] }, limit: 1 }))[0] || data;
+    const result = await createD1(env, { who: actorLabel(actor) }).prepare(`INSERT INTO ${quote(resource.table)} (${columns.map(quote).join(",")}) VALUES (${columns.map(() => "?").join(",")})`).bind(...columns.map((column) => data[column])).run();
+    const insertedId = data[resource.idColumn] === undefined ? result?.meta?.last_row_id : data[resource.idColumn];
+    return insertedId === undefined ? data : (await readList(name, requestedScope, { where: { [resource.idColumn]: insertedId }, limit: 1 }))[0] || { ...data, [resource.idColumn]: insertedId };
   }
 
   async function writeUpdate(name, requestedScope, id, changes = {}) {
@@ -94,6 +116,7 @@ export function createDataReader(env, { resources = [], context } = {}) {
     const actor = await getContext();
     assertWritable(resource, requestedScope, actor, "update");
     const data = cleanWritableValues(resource, changes, { includeOwnership: requestedScope === "system" });
+    assertColumnScopes(resource, actor, Object.keys(data));
     const columns = Object.keys(data);
     if (!columns.length) throw new TypeError(`No writable values supplied for ${resource.name}`);
     const predicates = [`${quote(resource.idColumn)}=?`];
@@ -113,27 +136,60 @@ export function createDataReader(env, { resources = [], context } = {}) {
     return createD1(env, { who: actorLabel(actor) }).prepare(`DELETE FROM ${quote(resource.table)} WHERE ${predicates.join(" AND ")}`).bind(...bindings).run();
   }
 
+  async function writeUpdateWhere(name, requestedScope, where, changes) {
+    const resource = getResource(name);
+    const actor = await getContext();
+    assertWritable(resource, requestedScope, actor, "update");
+    const data = cleanWritableValues(resource, changes, { includeOwnership: requestedScope === "system" });
+    assertColumnScopes(resource, actor, Object.keys(data));
+    const columns = Object.keys(data);
+    if (!columns.length) throw new TypeError(`No writable values supplied for ${resource.name}`);
+    const predicates = [];
+    const bindings = [];
+    addScopePredicate(resource, requestedScope, actor, predicates, bindings);
+    addFilters(resource, where, predicates, bindings);
+    await createD1(env, { who: actorLabel(actor) }).prepare(`UPDATE ${quote(resource.table)} SET ${columns.map((column) => `${quote(column)}=?`).join(",")} WHERE ${predicates.join(" AND ")}`).bind(...columns.map((column) => data[column]), ...bindings).run();
+    return readCount(name, requestedScope, { where });
+  }
+
+  async function writeDeleteWhere(name, requestedScope, where) {
+    const resource = getResource(name);
+    const actor = await getContext();
+    assertWritable(resource, requestedScope, actor, "delete");
+    const predicates = [];
+    const bindings = [];
+    addScopePredicate(resource, requestedScope, actor, predicates, bindings);
+    addFilters(resource, where, predicates, bindings);
+    return createD1(env, { who: actorLabel(actor) }).prepare(`DELETE FROM ${quote(resource.table)} WHERE ${predicates.join(" AND ")}`).bind(...bindings).run();
+  }
+
   function getResource(name) {
     const resource = registry.get(String(name));
     if (!resource) throw new TypeError(`Unknown data resource: ${name}`);
     return resource;
   }
 
-  return { user: scope("user"), tenant: scope("tenant"), system: scope("system"), resources: [...registry.values()] };
+  return { user: scope("user"), tenant: scope("tenant"), system: scope("system"), context: getContext, resources: [...registry.values()] };
 }
 
 export async function requestDataContext(env, { state = {}, request, publicTenantId = null } = {}) {
-  const authUser = state.authUser || (state.user ? await ensureUser(env, state.user, { who: `user:${state.user.sub || "unknown"}` }) : null);
+  let authUser = state.authUser || (state.user ? await ensureUser(env, state.user, { who: `user:${state.user.sub || "unknown"}` }) : null);
   const system = Boolean(state.user?.auth_strategy === "http_basic" || (authUser && authUser.is_admin));
   if (!authUser) return { userId: null, tenantId: publicTenantId, public: Boolean(publicTenantId), system: false };
-  const tenants = await listUserTenants(env, authUser.id, { who: `user:${authUser.id}` });
+  const impersonation = system ? await verifyImpersonationToken(request?.headers?.get("X-CF-GenAI-Impersonation") || readCookie(request, "__Host-cfgenai_impersonation"), env) : null;
+  if (impersonation) {
+    const targetUser = await getAuthorizationUser(env, impersonation.targetUserId, { who: `user:${impersonation.adminUserId}` });
+    if (targetUser) authUser = targetUser;
+  }
+  const who = `user:${authUser.id}`;
+  const [tenants, grants] = await Promise.all([listUserTenants(env, authUser.id, { who }), listUserGrants(env, authUser.id, { who })]);
   const requestedTenant = state.tenantId || request?.headers?.get("X-Tenant-ID") || null;
   const tenant = requestedTenant ? tenants.find((item) => item.id === requestedTenant) : tenants.length === 1 ? tenants[0] : null;
-  return { userId: authUser.id, tenantId: tenant?.id || null, public: false, system, tenants };
+  return { userId: authUser.id, tenantId: tenant?.id || null, public: false, system, scopes: grants.map((grant) => grant.scope_name), tenants, invalidTenant: Boolean(requestedTenant && !tenant), impersonated: Boolean(impersonation), impersonatedBy: impersonation?.adminUserId || null };
 }
 
 function isAllowed(resource, requestedScope, actor, operation) {
-  const allowed = requestedScope === "system" ? Boolean(actor.system) : requestedScope === resource.scope && (requestedScope === "user" ? Boolean(actor.userId) : Boolean(actor.tenantId && (actor.userId || (actor.public && resource.publicRead))));
+    const allowed = requestedScope === "system" ? Boolean(actor.system) : requestedScope === resource.scope && (requestedScope === "user" ? Boolean(actor.userId) : Boolean(actor.tenantId && (actor.userId || (actor.public && resource.publicRead))));
   if (!allowed || !resource.operations.includes(operation)) {
     auditLog({ who: actorLabel(actor), operation: "deny", resource: `data:${resource.name}:${requestedScope}:${operation}` });
     return false;
@@ -145,9 +201,17 @@ function assertWritable(resource, requestedScope, actor, operation) {
   if (!isAllowed(resource, requestedScope, actor, operation)) throw new DataScopeError(`Data scope ${requestedScope} cannot ${operation} resource ${resource.name}`);
 }
 
+function assertColumnScopes(resource, actor, columns) {
+  if (actor.system) return;
+  for (const column of columns) {
+    const required = resource.columnScopes[column] || [];
+    if (required.some((scope) => !actor.scopes?.includes(scope))) throw new DataScopeError(`Missing scope to write ${resource.name}.${column}`);
+  }
+}
+
 function addScopePredicate(resource, requestedScope, actor, predicates, bindings) {
   if (requestedScope === "user") { predicates.push(`${quote(resource.ownerColumn)}=?`); bindings.push(actor.userId); }
-  if (requestedScope === "tenant") { predicates.push(`${quote(resource.tenantColumn)}=?`); bindings.push(actor.tenantId); }
+  if (requestedScope === "tenant") { predicates.push(`${quote(resource.tenantColumn)}=?`); bindings.push(actor.tenantId); if (actor.public && resource.publicRead && typeof resource.publicRead === "object") { predicates.push(`${quote(resource.publicRead.column)}=?`); bindings.push(resource.publicRead.value); } }
 }
 
 function addFilters(resource, where, predicates, bindings) {
@@ -169,3 +233,4 @@ function addOwnedValue(resource, requestedScope, actor, data) {
 
 function actorLabel(actor) { return actor.system ? "system:data" : `user:${actor.userId || "unknown"}`; }
 function quote(identifier) { return `"${identifier}"`; }
+function readCookie(request, name) { const value = request?.headers?.get("Cookie") || ""; return value.split(";").map((part) => part.trim()).find((part) => part.startsWith(`${name}=`))?.slice(name.length + 1) || ""; }

package/src/index.js

@@ -2,12 +2,13 @@
  * Lean, opinionated Worker composition for Cloudflare sites.
  * Site code owns domain routes and data; this owns lifecycle and edge concerns.
  */
-import { ensureScopes, ensureUser, hasScope, listAuthorizationScopes, listAuthorizationUsers, listGroups, listUserGroups, listUserGrants, replaceUserGroups, replaceUserGrants } from "./authorization.js";
+import { createImpersonationToken, ensureScopes, ensureSubscriptionManifest, ensureUser, getAuthorizationUser, hasScope, listAuthorizationScopes, listAuthorizationUsers, listGroups, listTenantSubscriptions, listUserGroups, listUserGrants, replaceUserGroups, replaceUserGrants, SubscriptionError } from "./authorization.js";
 import { getCircuitBreaker, evaluateCircuitBreaker, listCircuitBreakers, listHealthchecks, listFeatureCatalog, listFeatureHealth, registerFeatureManifests, requestActor, setCircuitBreaker, updateHealthcheck } from "./core.js";
 import { createDataReader, DataScopeError, normalizeDataResources, requestDataContext } from "./data.js";
 export * from "./core.js";
 export * from "./data.js";
-export function createWorker({ fetch, scheduled, auth, authorize, scopes = [], scopeRoutes = [], middleware = [], features = [], dataResources = [], publicTenantId = null, health, boot, metrics, security = true, adminPage, siteAdminPage }) {
+export * from "./authorization.js";
+export function createWorker({ fetch, scheduled, auth, authorize, scopes = [], subscriptionManifest = [], scopeRoutes = [], middleware = [], features = [], dataResources = [], publicTenantId = null, health, boot, metrics, security = true, adminPage, siteAdminPage }) {
   if (typeof fetch !== "function") throw new TypeError("createWorker requires a fetch handler");
   const provider = auth || features.find((feature) => typeof feature?.getUser === "function");
   const registeredDataResources = normalizeDataResources([...dataResources, ...features.flatMap((feature) => Array.isArray(feature?.dataResources) ? feature.dataResources : [])]);
@@ -21,8 +22,10 @@ export function createWorker({ fetch, scheduled, auth, authorize, scopes = [], s
     async fetch(request, env, ctx) {
       try {
         if (boot) await boot(env, { request, ctx });
+        if (subscriptionManifest.length) await ensureSubscriptionManifest(env, subscriptionManifest, { who: "system:update" });
         const url = new URL(request.url);
         const state = Object.create(null);
+        if (provider?.getUser) state.user = await provider.getUser(request, env).catch(() => null);
         state.data = createDataReader(env, { resources: registeredDataResources, context: () => requestDataContext(env, { state, request, publicTenantId }) });
         if (env?.DB && features.some((feature) => typeof feature?.healthcheck === "function" || feature?.healthchecks?.length || feature?.healthChecks?.length || feature?.circuitBreakers?.length || feature?.circuit_breakers?.length)) ctx?.waitUntil?.(registerFeatureManifests(env, features, { who: "system:update" }).then(() => listCircuitBreakers(env, { who: "system:update" }).then((breakers) => Promise.all(breakers.filter(Boolean).map((breaker) => evaluateCircuitBreaker(env, breaker.id, { who: "system:update" }))))).catch((error) => console.error("[EventLog] feature manifest registration failed", error)));
         const dispatch = async (index, currentRequest = request) => {
@@ -33,6 +36,12 @@ export function createWorker({ fetch, scheduled, auth, authorize, scopes = [], s
               const featureHealth = env?.DB ? await listFeatureHealth(env, { who: "system:read" }).catch(() => []) : [];
               return healthResponse(env, featureHealth.length ? { ...details, features: featureHealth } : details);
             }
+            if (url.pathname === "/api/tenant" && currentRequest.method === "GET") {
+              const context = await state.data.context();
+              if (!context.userId) return Response.json({ error: "Authentication is required." }, { status: 401 });
+              if (context.invalidTenant) return Response.json({ error: "The requested tenant is not available." }, { status: 400 });
+              return Response.json({ tenant: context.tenantId ? { id: context.tenantId, name: context.tenants?.find((tenant) => tenant.id === context.tenantId)?.name || null } : null, tenants: context.tenants || [] });
+            }
             return fetch(currentRequest, env, ctx, state);
           }
           if (typeof layer !== "function") throw new TypeError("Worker middleware must be a function");
@@ -43,7 +52,7 @@ export function createWorker({ fetch, scheduled, auth, authorize, scopes = [], s
         return security ? secureResponse(response) : response;
       } catch (error) {
         console.error("[worker] request failed", error);
-        if (error instanceof DataScopeError) return secureResponse(Response.json({ error: "Data access is not permitted." }, { status: 403, headers: { "Cache-Control": "no-store" } }));
+        if (error instanceof DataScopeError || error instanceof SubscriptionError) return secureResponse(Response.json({ error: error.message }, { status: 403, headers: { "Cache-Control": "no-store" } }));
         return secureResponse(Response.json({ error: "Internal server error" }, { status: 500, headers: { "Cache-Control": "no-store" } }));
       }
     },
@@ -108,10 +117,19 @@ function requiredScopeFor(pathname, routes) {
 
 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/scopes" || url.pathname === "/api/admin/groups" || url.pathname.startsWith("/api/admin/users/") || 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);
+  const platformPath = url.pathname === "/api/admin/users" || 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" } });
+  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: requestActor(state) }) });
+  const impersonateMatch = url.pathname.match(/^\/api\/admin\/users\/([^/]+)\/impersonate$/);
+  if (impersonateMatch && request.method === "POST") {
+    const target = decodeURIComponent(impersonateMatch[1]);
+    const targetUser = await getAuthorizationUser(env, target, { who: requestActor(state) });
+    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: requestActor(state) }) });
   if (url.pathname === "/api/admin/status" && request.method === "GET") return Response.json({ features: await listFeatureHealth(env, { who: requestActor(state) }) });
   if (url.pathname === "/api/admin/features" && request.method === "GET") return Response.json({ features: await listFeatureCatalog(env, features, { who: requestActor(state) }) });