@cosmicdrift/kumiko-framework 0.328.0 → 0.328.1

package/dist/derivatives/derivatives-context.js

@@ -0,0 +1,212 @@
+import { fetchOne } from "../bun-db/query.js";
+import { EXT_DERIVATIVE_OVERLAY_RESOLVER, EXT_DERIVATIVE_RENDERER, } from "../engine/extension-names.js";
+import { InternalError, NotFoundError } from "../errors/index.js";
+import { fileRefsTable } from "../files/file-ref-table.js";
+import { assertSafeStorageKey, normalizeMimeType } from "../files/types.js";
+import { variantSuffix } from "./variant-key.js";
+// extension-usage `options` is engine-payload (unknown) — structurally validate
+// instead of casting blind, same pattern as isFileProviderPlugin.
+function isDerivativeRendererPlugin(o) {
+    return typeof o === "object" && o !== null && "render" in o && typeof o.render === "function";
+}
+export function resolveRenderer(registry, mimeType) {
+    const normalized = normalizeMimeType(mimeType);
+    const usages = registry.getExtensionUsages(EXT_DERIVATIVE_RENDERER);
+    const exact = usages.find((u) => u.entityName === normalized);
+    if (exact) {
+        if (!isDerivativeRendererPlugin(exact.options))
+            throw new Error(`derivatives.resolveRenderer: "${exact.entityName}" registered without a render(input, spec, sourceMimeType) — extension options must be a DerivativeRendererPlugin.`);
+        return exact.options;
+    }
+    const wildcard = usages.find((u) => u.entityName === `${normalized.split("/")[0]}/*`);
+    if (wildcard) {
+        if (!isDerivativeRendererPlugin(wildcard.options))
+            throw new Error(`derivatives.resolveRenderer: "${wildcard.entityName}" registered without a render(input, spec, sourceMimeType) — extension options must be a DerivativeRendererPlugin.`);
+        return wildcard.options;
+    }
+    return undefined;
+}
+// extension-usage `options` is engine-payload (unknown) — structurally validate
+// instead of casting blind, same pattern as isDerivativeRendererPlugin.
+function isOverlayResolverPlugin(o) {
+    return typeof o === "object" && o !== null && "resolve" in o && typeof o.resolve === "function";
+}
+function isFileRefRow(row) {
+    return (typeof row["storageKey"] === "string" &&
+        typeof row["mimeType"] === "string" &&
+        (row["entityType"] === null || typeof row["entityType"] === "string") &&
+        (row["entityId"] === null || typeof row["entityId"] === "string") &&
+        (row["fieldName"] === null || typeof row["fieldName"] === "string"));
+}
+function hasFieldIdentity(row) {
+    return row.entityType !== null && row.entityId !== null && row.fieldName !== null;
+}
+// Looks up the entityType's resolver once per variant() call (not once per
+// qr layer) and fails before any layer is touched — a spec with 3 qr layers
+// and no registration throws once, not on the first layer only.
+function resolveQrOverlayContext(row, registry) {
+    if (!hasFieldIdentity(row)) {
+        throw new InternalError({
+            message: "derivatives.variant: a qr overlay requires the FileRef's entityType/entityId/fieldName, but at least one is missing.",
+            details: { entityType: row.entityType, entityId: row.entityId, fieldName: row.fieldName },
+        });
+    }
+    const usage = registry
+        .getExtensionUsages(EXT_DERIVATIVE_OVERLAY_RESOLVER)
+        .find((u) => u.entityName === row.entityType);
+    if (!usage) {
+        throw new InternalError({
+            message: `derivatives.variant: no ${EXT_DERIVATIVE_OVERLAY_RESOLVER} registered for entityType "${row.entityType}".`,
+            details: { entityType: row.entityType },
+        });
+    }
+    if (!isOverlayResolverPlugin(usage.options)) {
+        throw new Error(`derivatives.variant: "${usage.entityName}" registered ${EXT_DERIVATIVE_OVERLAY_RESOLVER} without a resolve(args) — extension options must be an OverlayResolverPlugin.`);
+    }
+    return { row, plugin: usage.options };
+}
+async function resolveQrLayer(layer, context, tenantId) {
+    const { dataToken, ...placement } = layer;
+    const data = await context.plugin.resolve({
+        entityId: context.row.entityId,
+        tenantId,
+        fieldName: context.row.fieldName,
+        dataToken,
+    });
+    if (!data) {
+        throw new InternalError({
+            message: `derivatives.variant: ${EXT_DERIVATIVE_OVERLAY_RESOLVER} resolved dataToken "${dataToken}" to an empty value for entityType "${context.row.entityType}".`,
+            details: { entityType: context.row.entityType, dataToken },
+        });
+    }
+    return { ...placement, data };
+}
+// A non-qr layer is already ResolvedOverlayLayer-shaped (see
+// ResolvedOverlayLayer's `image` member) — this only exists because TS can't
+// derive that from `layer.kind !== "qr"` across a Promise.all/map boundary.
+function resolveOverlayLayer(layer, qrContext, tenantId) {
+    if (layer.kind !== "qr")
+        return layer;
+    if (!qrContext) {
+        throw new Error("derivatives.variant: unreachable — resolveOverlaySpec only omits a qr context when the spec has no qr layer.");
+    }
+    return resolveQrLayer(layer, qrContext, tenantId);
+}
+// Resolves every `qr` layer's dataToken to a concrete value and moves the
+// whole overlay list to `resolvedOverlays` — BEFORE variantSuffix() hashes
+// the spec, so a resolver whose target changes (e.g. a base-URL rotation)
+// invalidates the cache instead of serving a stale target under the old key.
+async function resolveOverlaySpec(spec, row, registry, tenantId) {
+    if (!spec.overlays || spec.overlays.length === 0)
+        return spec;
+    const qrContext = spec.overlays.some((layer) => layer.kind === "qr")
+        ? resolveQrOverlayContext(row, registry)
+        : undefined;
+    const resolvedOverlays = await Promise.all(spec.overlays.map((layer) => resolveOverlayLayer(layer, qrContext, tenantId)));
+    return { ...spec, overlays: undefined, resolvedOverlays };
+}
+// sourceMimeType is client-controlled (it's `file.type` off the upload — see
+// file-routes.ts's "a field without `accept` lets a client upload anything")
+// and, when spec.format is unset, a renderer is documented to preserve the
+// source's own format (DerivativeRendererPlugin's doc comment) — so the
+// bytes really are in this format, but the STRING itself must still be
+// allowlisted before it becomes a response Content-Type or storage-provider
+// metadata. Otherwise an app whose renderer wildcard is broad enough (e.g.
+// `image/*`) would let a client-declared `image/svg+xml` ride straight
+// through as an honestly-declared (non-sniffed) active-content type (#2021).
+const KNOWN_SAFE_VARIANT_MIME_TYPES = new Set([
+    "image/jpeg",
+    "image/png",
+    "image/webp",
+    "image/avif",
+    "image/gif",
+]);
+// The spec — not the renderer — determines the output mimeType, so it's the
+// single source of truth for both what gets written to storage and what the
+// caller receives; a cache hit never runs the renderer, so there's nothing
+// else to derive it from.
+function outputMimeType(spec, sourceMimeType) {
+    switch (spec.format) {
+        case "webp":
+            return "image/webp";
+        case "avif":
+            return "image/avif";
+        case "jpeg":
+            return "image/jpeg";
+        default: {
+            const normalized = normalizeMimeType(sourceMimeType);
+            return KNOWN_SAFE_VARIANT_MIME_TYPES.has(normalized)
+                ? normalized
+                : "application/octet-stream";
+        }
+    }
+}
+// `deps.db` is whatever the caller passes through — in the write-handler
+// pipeline (dispatch-shared.ts) that's the handler's open DbTx. `variant()`
+// then holds that transaction open across a full render (decode/resize/
+// encode) plus the storage read+write, not just the fetchOne/exists checks.
+// On a later rollback in the same handler, a variant already written to
+// storage is orphaned there (row never committed, bytes never cleaned up).
+// Prefer this context from the job/MSP path, where `deps.db` isn't tied to
+// an in-flight write transaction; a synchronous write handler rendering a
+// large image should hand off to a job instead of calling `variant()` inline.
+export function createDerivativesContext(deps) {
+    return {
+        variant: async (fileRefId, spec, name) => {
+            const row = await fetchOne(deps.db, fileRefsTable, {
+                id: fileRefId,
+                tenantId: deps.tenantId,
+                isDeleted: false,
+            });
+            if (!row) {
+                throw new NotFoundError("fileRef", fileRefId);
+            }
+            if (!isFileRefRow(row)) {
+                throw new NotFoundError("fileRef", fileRefId);
+            }
+            const renderer = resolveRenderer(deps.registry, row.mimeType);
+            if (!renderer) {
+                const known = deps.registry
+                    .getExtensionUsages(EXT_DERIVATIVE_RENDERER)
+                    .map((u) => u.entityName)
+                    .join(", ") || "<none>";
+                throw new InternalError({
+                    message: `derivatives.variant: no renderer registered for mimeType "${row.mimeType}".`,
+                    details: { knownRenderers: known },
+                });
+            }
+            // Resolves qr dataTokens to concrete values BEFORE the spec is hashed
+            // — see resolveOverlaySpec.
+            const resolvedSpec = await resolveOverlaySpec(spec, row, deps.registry, deps.tenantId);
+            const src = deps.files.ref(row.storageKey);
+            // ponytail: derived key keeps the source extension regardless of the
+            // spec's format — widen deriveKey if a storage backend ever routes on
+            // extension.
+            const target = src.derive(variantSuffix(name, resolvedSpec));
+            // Belt-and-suspenders: variantSuffix already rejects an unsafe name,
+            // this catches a traversal segment reaching the key through any other
+            // path (e.g. a future deriveKey change).
+            assertSafeStorageKey(target.key);
+            const mimeType = outputMimeType(resolvedSpec, row.mimeType);
+            // ponytail: exists→render→write is a TOCTOU window under concurrent
+            // requests for the same variant (duplicate render + write). Ceiling:
+            // non-atomic providers can briefly expose a half-written object as a
+            // cache hit. Upgrade: write to a temp key then atomic rename/copy.
+            if (await target.exists()) {
+                return {
+                    storageKey: target.key,
+                    mimeType,
+                    rendered: false,
+                };
+            }
+            const original = await src.read();
+            const result = await renderer.render(original, resolvedSpec, row.mimeType);
+            await target.write(result, mimeType);
+            return {
+                storageKey: target.key,
+                mimeType,
+                rendered: true,
+            };
+        },
+    };
+}

package/dist/derivatives/field-variants.d.ts

@@ -0,0 +1,3 @@
+import type { VariantSpec } from "@cosmicdrift/kumiko-types/derivatives-types";
+import type { Registry } from "../engine/types/index.js";
+export declare function resolveFieldVariant(registry: Registry, entityType: string | null, fieldName: string | null, name: string): VariantSpec | undefined;

package/dist/derivatives/field-variants.js

@@ -0,0 +1,16 @@
+// The field definition IS the whitelist: a request carries a variant NAME,
+// never a spec, so no caller can drive an arbitrary render. `hasOwn` and not
+// a plain index — `name` comes off a URL segment, and `__proto__` would
+// otherwise resolve to something truthy that is not a VariantSpec.
+export function resolveFieldVariant(registry, entityType, fieldName, name) {
+    if (entityType === null || fieldName === null)
+        return undefined;
+    const field = registry.getEntity(entityType)?.fields[fieldName];
+    if (field === undefined)
+        return undefined;
+    if (field.type !== "image" && field.type !== "images")
+        return undefined;
+    if (field.variants === undefined || !Object.hasOwn(field.variants, name))
+        return undefined;
+    return field.variants[name];
+}

package/dist/derivatives/index.d.ts

@@ -0,0 +1,6 @@
+export type { StoredFileStore } from "./delete-stored-file.js";
+export { deleteStoredFileAndDerivatives, listDerivativeKeys } from "./delete-stored-file.js";
+export type { DerivativesContextDeps } from "./derivatives-context.js";
+export { createDerivativesContext, resolveRenderer } from "./derivatives-context.js";
+export { resolveFieldVariant } from "./field-variants.js";
+export { canonicalJson, derivativeListPrefix, isDerivativeKeyOf, parseDerivativeKey, specHash, VARIANT_NAME_PATTERN, variantSuffix, } from "./variant-key.js";

package/dist/derivatives/index.js

@@ -0,0 +1,4 @@
+export { deleteStoredFileAndDerivatives, listDerivativeKeys } from "./delete-stored-file.js";
+export { createDerivativesContext, resolveRenderer } from "./derivatives-context.js";
+export { resolveFieldVariant } from "./field-variants.js";
+export { canonicalJson, derivativeListPrefix, isDerivativeKeyOf, parseDerivativeKey, specHash, VARIANT_NAME_PATTERN, variantSuffix, } from "./variant-key.js";

package/dist/derivatives/variant-key.d.ts

@@ -0,0 +1,10 @@
+import type { VariantSpec } from "@cosmicdrift/kumiko-types/derivatives-types";
+export declare function canonicalJson(value: unknown): string;
+export declare function specHash(spec: VariantSpec): string;
+export declare const VARIANT_NAME_PATTERN: RegExp;
+export declare function variantSuffix(name: string, spec: VariantSpec): string;
+export declare function derivativeListPrefix(originalKey: string): string;
+export declare function isDerivativeKeyOf(originalKey: string, candidateKey: string): boolean;
+export declare function parseDerivativeKey(candidateKey: string): {
+    readonly originalKey: string;
+} | null;

package/dist/derivatives/variant-key.js

@@ -0,0 +1,100 @@
+import { createHash } from "node:crypto";
+// Deterministic JSON: object keys sorted (recursively), `undefined` values
+// dropped, arrays keep their order. Two specs that are semantically equal
+// (same keys, different insertion order; explicit `undefined` vs. omitted)
+// serialize identically.
+export function canonicalJson(value) {
+    if (Array.isArray(value)) {
+        return `[${value.map((entry) => canonicalJson(entry)).join(",")}]`;
+    }
+    if (value !== null && typeof value === "object") {
+        const entries = Object.entries(value)
+            .filter(([, v]) => v !== undefined)
+            .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+        return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${canonicalJson(v)}`).join(",")}}`;
+    }
+    return JSON.stringify(value) ?? "null";
+}
+// A key built from the variant name alone would keep serving stale pixels
+// forever after a spec change; hashing the spec into the key means a
+// changed spec is automatically a new URL.
+export function specHash(spec) {
+    return createHash("sha256").update(canonicalJson(spec)).digest("hex").slice(0, 16);
+}
+export const VARIANT_NAME_PATTERN = /^[a-z0-9][a-z0-9-]{0,31}$/i;
+export function variantSuffix(name, spec) {
+    // `name` ends up in a storage key (see deriveKey) — an unvalidated value
+    // like "../../other-tenant/x" would escape the tenant prefix the key is
+    // built under.
+    if (!VARIANT_NAME_PATTERN.test(name)) {
+        throw new Error(`derivatives: variant name must match ${VARIANT_NAME_PATTERN.source} (letters, digits, hyphens; max 32 chars), got "${name}"`);
+    }
+    return `${name}-${specHash(spec)}`;
+}
+// A full derivative-suffix segment is `<name>-<16 hex chars>` — mirrors
+// VARIANT_NAME_PATTERN (name grammar) + specHash's fixed 16-char slice.
+// Keep in sync with both if either changes.
+const DERIVATIVE_SUFFIX_PATTERN = /^[a-z0-9][a-z0-9-]{0,31}-[0-9a-f]{16}$/i;
+// Mirrors deriveKey's own split so callers get the exact same base/ext this
+// key's derivatives were built from.
+function splitKey(key) {
+    const lastSlash = key.lastIndexOf("/");
+    const lastSegment = lastSlash === -1 ? key : key.slice(lastSlash + 1);
+    const lastDot = lastSegment.lastIndexOf(".");
+    if (lastDot === -1)
+        return { base: key, ext: "" };
+    const base = key.slice(0, key.length - lastSegment.length + lastDot);
+    return { base, ext: lastSegment.slice(lastDot) };
+}
+// List-prefix that covers every derivative deriveKey() can produce for
+// `originalKey` — pass to FileStorageProvider.list() to enumerate candidates,
+// then filter with isDerivativeKeyOf before deleting any of them.
+export function derivativeListPrefix(originalKey) {
+    return `${splitKey(originalKey).base}.`;
+}
+// True when `candidateKey` is a derivative deriveKey() could have produced
+// for `originalKey` — anchored to originalKey's own basename AND extension.
+// Without the extension anchor, a same-directory sibling original with a
+// different extension (a different file, possibly another user's) would
+// match on prefix alone and get swept into a forget/tenant-destroy delete.
+export function isDerivativeKeyOf(originalKey, candidateKey) {
+    const { base, ext } = splitKey(originalKey);
+    const prefix = `${base}.`;
+    if (!candidateKey.startsWith(prefix) || !candidateKey.endsWith(ext))
+        return false;
+    const middle = candidateKey.slice(prefix.length, candidateKey.length - ext.length);
+    return DERIVATIVE_SUFFIX_PATTERN.test(middle);
+}
+// buildStorageKey (files/types.ts) always produces exactly 5 "/"-segments
+// ending in "<uniqueId>.<ext>" — a single dot, non-empty on both sides.
+// Anchoring parseDerivativeKey's reconstructed candidate to this shape
+// rejects lookalikes that were never written by buildStorageKey (a GDPR
+// export bundle, a local-provider `*.tmp` write-in-progress file) even when
+// their last segment happens to contain a "name-16hex"-shaped middle token.
+const BUILT_STORAGE_KEY_LAST_SEGMENT_PATTERN = /^[^./]+\.[^./]+$/;
+function looksLikeBuiltStorageKey(key) {
+    const segments = key.split("/");
+    if (segments.length !== 5)
+        return false;
+    return BUILT_STORAGE_KEY_LAST_SEGMENT_PATTERN.test(segments[4] ?? "");
+}
+// Reverse of deriveKey: given a key found on a full storage listing, guesses
+// the original key it would be a derivative of. Used by the orphaned-
+// derivative backfill/GC sweep, which has no audit trail of past forgets to
+// work from — only the deterministic key grammar itself. Returns null for
+// anything that isn't derivative-shaped (including a plain original, which
+// splits with no second dot) or whose reconstructed original doesn't match
+// buildStorageKey's own shape.
+export function parseDerivativeKey(candidateKey) {
+    const { base: withSuffix, ext } = splitKey(candidateKey);
+    const { base: outerBase, ext: suffixExt } = splitKey(withSuffix);
+    if (suffixExt === "")
+        return null;
+    const suffixCandidate = suffixExt.slice(1);
+    if (!DERIVATIVE_SUFFIX_PATTERN.test(suffixCandidate))
+        return null;
+    const originalKey = `${outerBase}${ext}`;
+    if (!looksLikeBuiltStorageKey(originalKey))
+        return null;
+    return { originalKey };
+}

package/dist/engine/access.d.ts

@@ -0,0 +1,2 @@
+import type { AccessRule, SessionUser } from "./types/index.js";
+export declare function hasAccess(user: Pick<SessionUser, "roles">, access: AccessRule | undefined): boolean;

package/dist/engine/access.js

@@ -0,0 +1,25 @@
+import { ANONYMOUS_ROLE } from "./system-user.js";
+import { isOpenToAllGranted } from "./types/index.js";
+// Default-deny: a handler without an explicit AccessRule is unreachable. To
+// grant access a handler must either list allowed roles or opt into
+// openToAll. Leaving access undefined now returns false (previously true) —
+// the registry boot-validator additionally refuses to register handlers that
+// don't declare one.
+//
+// `openToAll` means "any authenticated user, regardless of role". Anonymous
+// callers are explicitly excluded — apps that want a public endpoint must
+// list `anonymous` in `roles` (e.g. `roles: ["anonymous", "customer"]`).
+// Without this guard, enabling `anonymousAccess` on the server would silently
+// turn every existing `openToAll: true` handler into a public endpoint.
+export function hasAccess(user, access) {
+    if (!access)
+        return false;
+    if ("openToAll" in access) {
+        if (!isOpenToAllGranted(access))
+            return false;
+        return !user.roles.includes(ANONYMOUS_ROLE);
+    }
+    if (access.roles.length === 0)
+        return false;
+    return access.roles.some((role) => user.roles.includes(role));
+}

package/dist/engine/active-membership.d.ts

@@ -0,0 +1,26 @@
+import type { DbConnection } from "../db/connection.js";
+import type { TenantId } from "./types/identifiers.js";
+export type PrincipalStatus = "active" | "blocked" | "unknown";
+export type PrincipalProfile = {
+    readonly globalRoles: readonly string[];
+    readonly timezone?: string;
+    readonly locale?: string;
+};
+export type PrincipalStatusPlugin = {
+    readonly resolveStatus: (userId: string, deps: {
+        readonly db: DbConnection;
+    }) => Promise<PrincipalStatus>;
+    readonly resolveProfile: (userId: string, deps: {
+        readonly db: DbConnection;
+    }) => Promise<PrincipalProfile | null>;
+};
+export type TenantLifecycleStatusPlugin = {
+    readonly resolveStatus: (tenantId: TenantId, deps: {
+        readonly db: DbConnection;
+    }) => Promise<{
+        readonly status: string;
+    } | null>;
+};
+export declare function isPrincipalStatusPlugin(v: unknown): v is PrincipalStatusPlugin;
+export declare function isTenantLifecycleStatusPlugin(v: unknown): v is TenantLifecycleStatusPlugin;
+export declare const TENANT_TEARDOWN_STATUSES: ReadonlySet<string>;

package/dist/engine/active-membership.js

@@ -0,0 +1,25 @@
+// principalStatus / tenantLifecycleStatus contracts consumed by
+// pipeline/active-membership.ts. Kept in engine/ (extension-registry surface), same split as tier-resolver-extension.ts.
+// extension-usage `options` is engine-payload (unknown) — structurally
+// validate instead of casting blind, same pattern as isFileProviderPlugin.
+function hasResolveStatusFn(v) {
+    return (typeof v === "object" &&
+        v !== null &&
+        "resolveStatus" in v &&
+        typeof v.resolveStatus === "function");
+}
+export function isPrincipalStatusPlugin(v) {
+    return hasResolveStatusFn(v) && "resolveProfile" in v && typeof v.resolveProfile === "function";
+}
+export function isTenantLifecycleStatusPlugin(v) {
+    return hasResolveStatusFn(v);
+}
+// Same values auth-middleware.ts used to keep as its own private
+// TENANT_LIFECYCLE_BLOCKED set — moved here so the framework's active-
+// membership check and the request-level 410 gate can't drift apart.
+export const TENANT_TEARDOWN_STATUSES = new Set([
+    "destroyRequested",
+    "destroying",
+    "destroyFailed",
+    "destroyed",
+]);

package/dist/engine/boot-validator/access-declarations.d.ts

@@ -0,0 +1,2 @@
+import type { FeatureDefinition } from "../types/index.js";
+export declare function validateAccessDeclarations(feature: FeatureDefinition): void;

package/dist/engine/boot-validator/access-declarations.js

@@ -0,0 +1,148 @@
+import { accessAllowsAnonymous, declaredPersonalData, personalFieldNames, } from "../personal-data-fields.js";
+import { ANONYMOUS_ROLE } from "../system-user.js";
+import { collectZodObjectKeys } from "./zod-shape.js";
+// escapeHatch and r.systemScope() can write around the entity's write map
+// (db.global(), systemDb, SYSTEM identity), so the map no longer vouches for the row.
+function canWriteAroundExecutor(feature, handler) {
+    return handler.escapeHatch !== undefined || feature.systemScope;
+}
+// Owner binding counts only for a handler mapped to one entity.
+function candidatePersonalFieldNames(feature, handlerName, handler, honorOwnerBindingOverride) {
+    const mappedEntityName = feature.handlerEntityMappings?.[handlerName];
+    const entities = feature.entities ?? {};
+    if (mappedEntityName) {
+        const entity = entities[mappedEntityName];
+        const honorOwnerBinding = honorOwnerBindingOverride ?? !canWriteAroundExecutor(feature, handler);
+        return entity ? personalFieldNames(entity, honorOwnerBinding) : new Set();
+    }
+    const names = new Set();
+    for (const entity of Object.values(entities)) {
+        for (const name of personalFieldNames(entity, false))
+            names.add(name);
+    }
+    return names;
+}
+// Not an object with a non-empty string `reason` (incl. deprecated `openToAll: true`) counts as "empty".
+function openToAllReasonIsEmpty(access) {
+    if (!("openToAll" in access))
+        return false;
+    const openToAll = access.openToAll;
+    if (typeof openToAll !== "object" || openToAll === null)
+        return true;
+    if (!("reason" in openToAll) || typeof openToAll.reason !== "string")
+        return true;
+    return openToAll.reason.trim().length === 0;
+}
+function hasOpenToAll(access) {
+    return "openToAll" in access;
+}
+function declaresTenantMembersPersonalData(access) {
+    return declaredPersonalData(access) === "tenant-members";
+}
+function validateOpenToAllReason(feature, kind, handlerName, access) {
+    // skip: reason is well-formed, nothing to validate
+    if (!openToAllReasonIsEmpty(access))
+        return;
+    throw new Error(`[Feature ${feature.name}] ${kind} handler "${handlerName}" declares an invalid ` +
+        '{ openToAll: ... } — must be { reason: "<non-empty explanation>" } for why any ' +
+        "authenticated user may call this handler. `{ openToAll: true }` is no longer accepted.");
+}
+function validateEscapeHatchReason(feature, kind, handlerName, escapeHatch) {
+    // skip: no escapeHatch declared, or its reason is already non-empty
+    if (!escapeHatch || escapeHatch.reason.trim().length > 0)
+        return;
+    throw new Error(`[Feature ${feature.name}] ${kind} handler "${handlerName}" declares ` +
+        `{ escapeHatch: { reason: "" } } — the reason must be a non-empty string ` +
+        "explaining why this handler needs db.global() write access or a SYSTEM identity switch.");
+}
+function validatePersonalDataOnlyOnWrite(feature, kind, handlerName, access) {
+    // skip: write handlers may declare personalData, or it wasn't declared here
+    if (kind === "write" || declaredPersonalData(access) === undefined)
+        return;
+    const property = "openToAll" in access ? "openToAll.personalData" : "access.personalData";
+    throw new Error(`[Feature ${feature.name}] ${kind} handler "${handlerName}" declares ` +
+        `${property} — it only applies to write handlers, whose input is ` +
+        "checked for personal-data fields.");
+}
+function validatePersonalDataValue(feature, handlerName, access) {
+    const declared = declaredPersonalData(access);
+    // skip: nothing declared
+    if (declared === undefined)
+        return;
+    if ("openToAll" in access) {
+        // skip: the one supported value on openToAll
+        if (declared === "tenant-members")
+            return;
+        throw new Error(`[Feature ${feature.name}] write handler "${handlerName}" declares an unknown ` +
+            `openToAll.personalData ${JSON.stringify(declared)} — the only supported value is "tenant-members".`);
+    }
+    if (declared !== "public-intake") {
+        throw new Error(`[Feature ${feature.name}] write handler "${handlerName}" declares an unknown ` +
+            `access.personalData ${JSON.stringify(declared)} — the only supported value is "public-intake".`);
+    }
+    // skip: roles include "anonymous", which personalData: "public-intake" requires
+    if (Array.isArray(access.roles) && access.roles.includes(ANONYMOUS_ROLE))
+        return;
+    throw new Error(`[Feature ${feature.name}] write handler "${handlerName}" declares ` +
+        'access.personalData: "public-intake" but its roles do not include ' +
+        `"${ANONYMOUS_ROLE}" — personalData: "public-intake" only applies to handlers ` +
+        "that allow anonymous callers.");
+}
+function validateOpenToAllPersonalData(feature, handlerName, handler) {
+    const access = handler.access;
+    // skip: no openToAll declared, or the handler declares tenant members may write personal data
+    if (!hasOpenToAll(access) || declaresTenantMembersPersonalData(access))
+        return;
+    const inputKeys = collectZodObjectKeys(handler.schema);
+    const personalNames = candidatePersonalFieldNames(feature, handlerName, handler);
+    const offending = [...inputKeys].filter((key) => personalNames.has(key));
+    // skip: no personal-data fields in the handler's input
+    if (offending.length === 0)
+        return;
+    throw new Error(`[Feature ${feature.name}] write handler "${handlerName}" declares openToAll and ` +
+        `accepts personal-data field(s) ${offending.map((f) => `"${f}"`).join(", ")} that are ` +
+        "not bound to the caller. Choose one: (1) bind rows to the caller — every role in the " +
+        'entity\'s access.write is from("user:id", "<ownerField>") for a personal: { of: "<ownerField>" } ' +
+        'field, or from("user:id", "id") for a personal: "self" field, with no escapeHatch on the ' +
+        "handler and no r.systemScope() on its feature; (2) restrict access to roles; (3) declare " +
+        '{ openToAll: { reason: "<why any signed-in tenant member may write this personal data>", ' +
+        'personalData: "tenant-members" } }.');
+}
+// Anonymous callers all share one user.id, so honorOwnerBindingOverride is always false here.
+function validateAnonymousPersonalData(feature, handlerName, handler) {
+    const access = handler.access;
+    // skip: not reachable by an anonymous caller, or already declares public-intake
+    if (!accessAllowsAnonymous(access) || declaredPersonalData(access) === "public-intake")
+        return;
+    const inputKeys = collectZodObjectKeys(handler.schema);
+    const personalNames = candidatePersonalFieldNames(feature, handlerName, handler, false);
+    const offending = [...inputKeys].filter((key) => personalNames.has(key));
+    // skip: no personal-data fields in the handler's input
+    if (offending.length === 0)
+        return;
+    throw new Error(`[Feature ${feature.name}] write handler "${handlerName}" allows anonymous callers ` +
+        `("${ANONYMOUS_ROLE}" in access.roles) and accepts personal-data field(s) ` +
+        `${offending.map((f) => `"${f}"`).join(", ")}. Declare ` +
+        'access: { roles: [..., "anonymous"], personalData: "public-intake" } — every anonymous ' +
+        'request shares one caller identity, so owner-binding via from("user:id", ...) does not ' +
+        "vouch for it; protection comes from the handler's required rateLimit (per ip).");
+}
+export function validateAccessDeclarations(feature) {
+    for (const [handlerName, handler] of Object.entries(feature.writeHandlers)) {
+        validateOpenToAllReason(feature, "write", handlerName, handler.access);
+        validateEscapeHatchReason(feature, "write", handlerName, handler.escapeHatch);
+        validatePersonalDataValue(feature, handlerName, handler.access);
+        validateOpenToAllPersonalData(feature, handlerName, handler);
+        validateAnonymousPersonalData(feature, handlerName, handler);
+    }
+    for (const [handlerName, handler] of Object.entries(feature.queryHandlers)) {
+        validateOpenToAllReason(feature, "query", handlerName, handler.access);
+        validateEscapeHatchReason(feature, "query", handlerName, handler.escapeHatch);
+        validatePersonalDataOnlyOnWrite(feature, "query", handlerName, handler.access);
+    }
+    for (const [handlerName, handler] of Object.entries(feature.streamHandlers)) {
+        validateOpenToAllReason(feature, "stream", handlerName, handler.access);
+        validateEscapeHatchReason(feature, "stream", handlerName, handler.escapeHatch);
+        validatePersonalDataOnlyOnWrite(feature, "stream", handlerName, handler.access);
+    }
+}

package/dist/engine/boot-validator/access-roles.d.ts

@@ -0,0 +1,2 @@
+import type { FeatureDefinition } from "../types/index.js";
+export declare function warnOnUniqueAccessRoles(features: readonly FeatureDefinition[]): void;