@agilesyndrome/cf-genai-base 4.1.2 → 5.0.0

package/src/core/jobs.js

@@ -0,0 +1,185 @@
+import { Event, emitEvent } from "./events.js";
+import { createD1 } from "./d1.js";
+
+export const JOB_STATUSES = Object.freeze(["queued", "running", "succeeded", "failed", "cancelled"]);
+const JOB_STATUS_SET = new Set(JOB_STATUSES);
+const TERMINAL_STATUSES = new Set(["succeeded", "failed", "cancelled"]);
+
+export async function createJob(env, definition = {}, { who = "system:update", ctx } = {}) {
+  const id = String(definition.id || crypto.randomUUID());
+  const type = required(definition.type, "Job type");
+  const status = normalizeStatus(definition.status || "queued");
+  const now = new Date().toISOString();
+  const db = createD1(env, { who });
+  await db.prepare(`
+    INSERT INTO core_jobs
+      (id, type, status, owner_id, tenant_id, resource_type, resource_id,
+       input_json, result_json, error_json, progress_json, created_at, updated_at, expires_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, '{}', NULL, ?, ?, ?, ?)
+  `).bind(
+    id,
+    type,
+    status,
+    nullable(definition.ownerId),
+    nullable(definition.tenantId),
+    nullable(definition.resourceType),
+    nullable(definition.resourceId),
+    encode(definition.input),
+    encode(definition.progress),
+    now,
+    now,
+    nullable(definition.expiresAt),
+  ).run();
+  const job = await getJob(env, id, { who });
+  await publishJobEvent(env, job, "job.created", who, ctx);
+  return job;
+}
+
+export async function getJob(env, id, { who = "system:read" } = {}) {
+  const row = await createD1(env, { who }).prepare("SELECT * FROM core_jobs WHERE id = ?").bind(String(id)).first();
+  return row ? normalizeJob(row) : null;
+}
+
+export async function listJobs(env, filters = {}, { who = "system:read" } = {}) {
+  const clauses = [];
+  const values = [];
+  if (filters.ownerId !== undefined) { clauses.push("owner_id = ?"); values.push(nullable(filters.ownerId)); }
+  if (filters.tenantId !== undefined) { clauses.push("tenant_id = ?"); values.push(nullable(filters.tenantId)); }
+  if (filters.type) { clauses.push("type = ?"); values.push(String(filters.type)); }
+  if (filters.status) { clauses.push("status = ?"); values.push(normalizeStatus(filters.status)); }
+  if (filters.resourceType) { clauses.push("resource_type = ?"); values.push(String(filters.resourceType)); }
+  if (filters.resourceId) { clauses.push("resource_id = ?"); values.push(String(filters.resourceId)); }
+  const limit = boundedLimit(filters.limit);
+  const sql = `SELECT * FROM core_jobs${clauses.length ? ` WHERE ${clauses.join(" AND ")}` : ""} ORDER BY updated_at DESC LIMIT ?`;
+  const result = await createD1(env, { who }).prepare(sql).bind(...values, limit).all();
+  return (result?.results || []).map(normalizeJob);
+}
+
+export async function listJobEvents(env, jobId, { who = "system:read", limit = 100 } = {}) {
+  const result = await createD1(env, { who }).prepare("SELECT * FROM core_job_events WHERE job_id = ? ORDER BY created_at ASC LIMIT ?").bind(String(jobId), boundedLimit(limit, 500)).all();
+  return (result?.results || []).map(normalizeJobEvent);
+}
+
+export async function startJob(env, id, options = {}) {
+  return updateJob(env, id, { status: "running", startedAt: new Date().toISOString() }, options);
+}
+
+export async function updateJobProgress(env, id, progress, options = {}) {
+  return updateJob(env, id, { progress }, options);
+}
+
+export async function completeJob(env, id, result = {}, options = {}) {
+  return updateJob(env, id, { status: "succeeded", result, finishedAt: new Date().toISOString() }, options);
+}
+
+export async function failJob(env, id, error, options = {}) {
+  const details = error instanceof Error ? { name: error.name, message: error.message, code: error.code || null } : error;
+  return updateJob(env, id, { status: "failed", error: details, finishedAt: new Date().toISOString() }, options);
+}
+
+export async function cancelJob(env, id, options = {}) {
+  return updateJob(env, id, { status: "cancelled", finishedAt: new Date().toISOString() }, options);
+}
+
+export async function dispatchJob(env, definition, { workflow, params = {}, retention, who = "system:update", ctx } = {}) {
+  if (!workflow || typeof workflow.create !== "function") throw new TypeError("A Workflow binding is required to dispatch a job");
+  const job = await createJob(env, definition, { who, ctx });
+  try {
+    await workflow.create({
+      id: job.id,
+      params: { ...params, jobId: job.id },
+      ...(retention ? { retention } : {}),
+    });
+    return job;
+  } catch (error) {
+    await failJob(env, job.id, error, { who, ctx });
+    throw error;
+  }
+}
+
+export async function executeJob(env, id, execute, { who = "system:update", ctx, toJobResult = identity } = {}) {
+  if (typeof execute !== "function") throw new TypeError("Job executor must be a function");
+  const running = await startJob(env, id, { who, ctx });
+  if (!running) throw new TypeError(`Unknown job: ${id}`);
+  const report = (progress) => updateJobProgress(env, id, progress, { who, ctx });
+  try {
+    const value = await execute({ job: running, report });
+    const result = await toJobResult(value);
+    const job = await completeJob(env, id, result === undefined ? {} : result, { who, ctx });
+    return { job, value };
+  } catch (error) {
+    await failJob(env, id, error, { who, ctx });
+    throw error;
+  }
+}
+
+export async function runJob(env, definition, execute, options = {}) {
+  const job = await createJob(env, definition, options);
+  return executeJob(env, job.id, execute, options);
+}
+
+export async function updateJob(env, id, patch = {}, { who = "system:update", ctx } = {}) {
+  const current = await getJob(env, id, { who });
+  if (!current) return null;
+  const nextStatus = patch.status === undefined ? current.status : normalizeStatus(patch.status);
+  const values = [];
+  const assignments = [];
+  const fields = [
+    ["status", nextStatus],
+    ["result_json", patch.result === undefined ? undefined : encode(patch.result)],
+    ["error_json", patch.error === undefined ? undefined : (patch.error == null ? null : encode(patch.error))],
+    ["progress_json", patch.progress === undefined ? undefined : encode(patch.progress)],
+    ["started_at", patch.startedAt === undefined ? undefined : nullable(patch.startedAt)],
+    ["finished_at", patch.finishedAt === undefined ? undefined : nullable(patch.finishedAt)],
+    ["expires_at", patch.expiresAt === undefined ? undefined : nullable(patch.expiresAt)],
+  ];
+  if (nextStatus === "running" && !current.startedAt && patch.startedAt === undefined) fields[4] = ["started_at", new Date().toISOString()];
+  if (TERMINAL_STATUSES.has(nextStatus) && !current.finishedAt && patch.finishedAt === undefined) fields[5] = ["finished_at", new Date().toISOString()];
+  for (const [column, value] of fields) { if (value !== undefined) { assignments.push(`${column} = ?`); values.push(value); } }
+  assignments.push("updated_at = ?"); values.push(new Date().toISOString(), String(id));
+  await createD1(env, { who }).prepare(`UPDATE core_jobs SET ${assignments.join(", ")} WHERE id = ?`).bind(...values).run();
+  const job = await getJob(env, id, { who });
+  await publishJobEvent(env, job, patch.progress !== undefined && patch.status === undefined ? "job.progress" : `job.${nextStatus}`, who, ctx);
+  return job;
+}
+
+export function normalizeJob(row) {
+  return {
+    id: String(row.id),
+    type: String(row.type),
+    status: String(row.status),
+    ownerId: row.owner_id || null,
+    tenantId: row.tenant_id || null,
+    resourceType: row.resource_type || null,
+    resourceId: row.resource_id || null,
+    input: decode(row.input_json),
+    result: decode(row.result_json),
+    error: decode(row.error_json),
+    progress: decode(row.progress_json),
+    createdAt: row.created_at || null,
+    startedAt: row.started_at || null,
+    finishedAt: row.finished_at || null,
+    updatedAt: row.updated_at || null,
+    expiresAt: row.expires_at || null,
+  };
+}
+
+export function normalizeJobEvent(row) {
+  return { id: String(row.id), jobId: String(row.job_id), type: String(row.type), payload: decode(row.payload_json), createdAt: row.created_at || null };
+}
+
+async function publishJobEvent(env, job, type, who, ctx) {
+  const payload = { jobId: job.id, type: job.type, status: job.status, ownerId: job.ownerId, tenantId: job.tenantId, resource: job.resourceType && job.resourceId ? { type: job.resourceType, id: job.resourceId } : null, progress: job.progress, result: type === "job.succeeded" ? job.result : undefined, error: type === "job.failed" ? job.error : undefined };
+  const event = Event(who, type, "job", new Date(), { ...payload, audience: { userId: job.ownerId, tenantId: job.tenantId } });
+  const db = createD1(env, { who });
+  await db.prepare("INSERT INTO core_job_events (id, job_id, type, payload_json) VALUES (?, ?, ?, ?)").bind(event.id, job.id, type, encode(payload)).run();
+  await emitEvent(env, event, ctx);
+}
+
+function normalizeStatus(status) { const value = String(status).toLowerCase(); if (!JOB_STATUS_SET.has(value)) throw new TypeError(`Unsupported job status: ${status}`); return value; }
+function required(value, label) { const normalized = String(value || "").trim(); if (!normalized) throw new TypeError(`${label} is required`); return normalized; }
+function nullable(value) { return value === undefined || value === null || value === "" ? null : String(value); }
+function encode(value) { return JSON.stringify(value === undefined ? {} : value); }
+function decode(value) { if (value == null || value === "") return null; try { return JSON.parse(value); } catch { return null; } }
+function boundedLimit(value, maximum = 100) { const normalized = Number(value); return Number.isFinite(normalized) && normalized > 0 ? Math.min(Math.floor(normalized), maximum) : Math.min(50, maximum); }
+function identity(value) { return value; }

package/src/core/security.js

@@ -0,0 +1,71 @@
+export function sameOrigin(request, allowedOrigins = []) {
+  const origin = request?.headers?.get("Origin");
+  if (!origin) return false;
+  const requestOrigin = (() => { try { return new URL(request.url).origin; } catch { return ""; } })();
+  const allowed = new Set((Array.isArray(allowedOrigins) ? allowedOrigins : [allowedOrigins]).filter(Boolean).map(String));
+  if (!allowed.size && requestOrigin) allowed.add(requestOrigin);
+  const fetchSite = request.headers.get("Sec-Fetch-Site");
+  return allowed.has(origin) && (!fetchSite || fetchSite === "same-origin");
+}
+
+export async function readJsonClone(request, maxBytes = 64 * 1024) {
+  if (!(request.headers.get("Content-Type") || "").toLowerCase().startsWith("application/json")) return { error: secureJson({ error: "JSON request required" }, 415) };
+  const declared = Number(request.headers.get("Content-Length"));
+  if (Number.isFinite(declared) && declared > maxBytes) return { error: secureJson({ error: "Request body is too large" }, 413) };
+  try {
+    const value = await request.clone().json();
+    if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("Object required");
+    if (new TextEncoder().encode(JSON.stringify(value)).byteLength > maxBytes) return { error: secureJson({ error: "Request body is too large" }, 413) };
+    return { value };
+  } catch {
+    return { error: secureJson({ error: "Invalid JSON object request" }, 400) };
+  }
+}
+
+export async function readJson(request, maxBytes = 64 * 1024) {
+  if (!(request.headers.get("Content-Type") || "").toLowerCase().startsWith("application/json")) throw Object.assign(new Error("JSON request required"), { status: 415 });
+  const declared = Number(request.headers.get("Content-Length"));
+  if (Number.isFinite(declared) && declared > maxBytes) throw Object.assign(new Error("Request body is too large"), { status: 413 });
+  if (!request.body) throw Object.assign(new Error("Request body required"), { status: 400 });
+  try {
+    const value = await request.clone().json();
+    if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("Object required");
+    if (new TextEncoder().encode(JSON.stringify(value)).byteLength > maxBytes) throw Object.assign(new Error("Request body is too large"), { status: 413 });
+    return value;
+  } catch (error) {
+    if (error?.status) throw error;
+    throw Object.assign(new Error("Invalid JSON object request"), { status: 400 });
+  }
+}
+
+export function secureJson(payload, status = 200, headers = {}) {
+  return secureResponse(Response.json(payload, { status, headers: { "Cache-Control": "no-store", ...headers } }));
+}
+
+export function json(payload, status = 200, cache = "no-store") {
+  return secureJson(payload, status, { "Cache-Control": cache });
+}
+
+export function secureText(text, status = 200, cache = "no-store") {
+  return secureResponse(new Response(text, { status, headers: { "Content-Type": "text/plain; charset=utf-8", "Cache-Control": cache } }));
+}
+
+export function secureResponse(response) {
+  const headers = new Headers(response.headers);
+  headers.set("Content-Security-Policy", "default-src 'self'; script-src 'self'; worker-src 'self' blob: data:; style-src 'self' 'unsafe-inline'; img-src 'self' https: data:; connect-src 'self'; font-src 'self'; object-src 'none'; base-uri 'none'; form-action 'self'; frame-ancestors 'none'; upgrade-insecure-requests");
+  headers.set("X-Content-Type-Options", "nosniff");
+  headers.set("X-Frame-Options", "DENY");
+  headers.set("Referrer-Policy", "strict-origin-when-cross-origin");
+  headers.set("Permissions-Policy", "camera=(), microphone=(), geolocation=(), payment=(), usb=()");
+  headers.set("Cross-Origin-Opener-Policy", "same-origin");
+  headers.set("Strict-Transport-Security", "max-age=31536000");
+  return new Response(response.body, { status: response.status, statusText: response.statusText, headers });
+}
+
+export function requireUser(identity, response = secureJson({ error: "Authentication is required." }, 401)) {
+  return identity ? null : response;
+}
+
+export function requireAdmin(identity, response = secureJson({ error: "Administrator access is required." }, 403)) {
+  return identity?.is_admin || identity?.isAdmin ? null : response;
+}

package/src/data/context.js

@@ -0,0 +1,16 @@
+import { ensureUser, getAuthorizationUser, listUserGrants, listUserTenants, verifyImpersonationToken } from "../auth/index.js";
+
+export async function requestDataContext(env, { state = {}, request, publicTenantId = 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, publicTenantId, public: Boolean(publicTenantId), system: false };
+  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, publicTenantId, public: false, system, scopes: grants.map((grant) => grant.scope_name), tenants, invalidTenant: Boolean(requestedTenant && !tenant), impersonated: Boolean(impersonation), impersonatedBy: impersonation?.adminUserId || null };
+}
+
+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/data/index.js

@@ -0,0 +1,3 @@
+export * from "./resources.js";
+export * from "./reader.js";
+export * from "./context.js";

package/src/data/reader.js

@@ -0,0 +1,63 @@
+import { auditLog, createD1 } from "../core/index.js";
+import { DataScopeError, normalizeDataResources } from "./resources.js";
+
+export function createDataReader(env, { resources = [], context } = {}) {
+  const registry = new Map(normalizeDataResources(resources).map((resource) => [resource.name, resource]));
+  const getContext = typeof context === "function" ? context : async () => 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, offset = 0 } = {}) { return (await readPage(name, requestedScope, { where, limit, orderBy, offset })).rows; }
+
+  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 };
+    const predicates = []; const bindings = []; addScopePredicate(resource, requestedScope, actor, predicates, bindings); 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); const safeOffset = Math.max(Number(offset) || 0, 0);
+    let sql = `SELECT ${resource.readableColumns.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}`); sql = sql.replace(` LIMIT ${safeLimit}`, ` ORDER BY ${quote(column)} ${direction.toUpperCase() === "DESC" ? "DESC" : "ASC"} LIMIT ${safeLimit}`); }
+    const result = await createD1(env, { who: actorLabel(actor) }).prepare(sql).bind(...bindings).all(); const rows = result.results || [];
+    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}`);
+    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 = {}) {
+    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 = [`${quote(resource.idColumn)}=?`]; const bindings = [id]; addScopePredicate(resource, requestedScope, actor, 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 (await readList(name, requestedScope, { where: { [resource.idColumn]: id }, limit: 1 }))[0] || null;
+  }
+
+  async function writeDelete(name, requestedScope, id) { const resource = getResource(name); const actor = await getContext(); assertWritable(resource, requestedScope, actor, "delete"); const predicates = [`${quote(resource.idColumn)}=?`]; const bindings = [id]; addScopePredicate(resource, requestedScope, actor, predicates, bindings); 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"), public: scope("public"), system: scope("system"), context: getContext, resources: [...registry.values()] };
+}
+
+function isAllowed(resource, requestedScope, actor, operation) {
+  const allowed = requestedScope === "system" ? Boolean(actor.system) : requestedScope === resource.scope && (requestedScope === "user" ? Boolean(actor.userId) : requestedScope === "public" ? Boolean(actor.publicTenantId && operation === "read") : 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; }
+  return true;
+}
+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 === "public") { predicates.push(`${quote(resource.tenantColumn)}=?`); bindings.push(actor.publicTenantId); } 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) { for (const [column, value] of Object.entries(where || {})) { if (!resource.filterableColumns.includes(column)) throw new TypeError(`Column ${column} cannot filter ${resource.name}`); if (value === null) predicates.push(`${quote(column)} IS NULL`); else { predicates.push(`${quote(column)}=?`); bindings.push(value); } } }
+function cleanWritableValues(resource, values, { includeId = false, includeOwnership = false } = {}) { return Object.fromEntries(Object.entries(values || {}).filter(([column]) => (resource.writableColumns.includes(column) || (includeOwnership && [resource.ownerColumn, resource.tenantColumn].includes(column))) && (includeId || column !== resource.idColumn))); }
+function addOwnedValue(resource, requestedScope, actor, data) { if (requestedScope === "user") data[resource.ownerColumn] = actor.userId; if (requestedScope === "tenant") data[resource.tenantColumn] = actor.tenantId; }
+function actorLabel(actor) { return actor.system ? "system:data" : `user:${actor.userId || "unknown"}`; }
+function quote(identifier) { return `"${identifier}"`; }

package/src/data/resources.js

@@ -0,0 +1,42 @@
+export const DATA_SCOPES = ["user", "tenant", "public", "system"];
+export const DATA_OPERATIONS = ["read", "create", "update", "delete"];
+
+export class DataScopeError extends Error {
+  constructor(message) { super(message); this.name = "DataScopeError"; }
+}
+
+export function normalizeDataResources(resources = []) {
+  const names = new Set();
+  return resources.map((resource) => {
+    if (!resource || !/^[a-z][a-z0-9_-]*$/.test(String(resource.name || ""))) throw new TypeError("Data resources require a safe name");
+    if (!/^[a-z][a-z0-9_]*$/.test(String(resource.table || ""))) throw new TypeError(`Data resource ${resource.name} requires a safe table name`);
+    const name = String(resource.name);
+    if (names.has(name)) throw new TypeError(`Duplicate data resource: ${name}`);
+    names.add(name);
+    const scope = String(resource.scope || "").toLowerCase();
+    if (!DATA_SCOPES.includes(scope)) throw new TypeError(`Data resource ${resource.name} requires scope user, tenant, public, or system`);
+    const columns = [...new Set((resource.columns || []).map(String))];
+    if (!columns.length || columns.some((column) => !/^[a-z][a-z0-9_]*$/.test(column))) throw new TypeError(`Data resource ${resource.name} requires safe columns`);
+    const idColumn = String(resource.idColumn || "id");
+    if (!columns.includes(idColumn)) throw new TypeError(`Data resource ${resource.name} must include ${idColumn}`);
+    const ownerColumn = resource.ownerColumn ? String(resource.ownerColumn) : "user_id";
+    const tenantColumn = resource.tenantColumn ? String(resource.tenantColumn) : "tenant_id";
+    if (scope === "user" && !columns.includes(ownerColumn)) throw new TypeError(`User resource ${resource.name} must include ${ownerColumn}`);
+    if (["tenant", "public"].includes(scope) && !columns.includes(tenantColumn)) throw new TypeError(`${scope} resource ${resource.name} must include ${tenantColumn}`);
+    const filterableColumns = [...new Set((resource.filterableColumns || columns).map(String))];
+    const orderableColumns = [...new Set((resource.orderableColumns || columns).map(String))];
+    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`);
+    if (!Array.isArray(resource.readableColumns) || !resource.readableColumns.length) throw new TypeError(`Data resource ${resource.name} requires explicit readableColumns`);
+    const readableColumns = [...new Set(resource.readableColumns.map(String))];
+    if (readableColumns.some((column) => !columns.includes(column))) throw new TypeError(`Data resource ${resource.name} references an unreadable column`);
+    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`);
+    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, readableColumns, idColumn, ownerColumn, tenantColumn, filterableColumns, orderableColumns, writableColumns, columnScopes, operations, publicRead };
+  });
+}