@agent-native/core 0.96.0 → 0.98.0

package/corpus/core/src/server/realtime-voice.ts

@@ -26,6 +26,7 @@ import {
 } from "./credential-provider.js";
 import { getH3App } from "./framework-request-handler.js";
 import { runWithRequestContext } from "./request-context.js";
+import { isSameOriginRequest } from "./request-origin.js";
 
 export const REALTIME_VOICE_SESSION_PATH =
   "/_agent-native/realtime-voice/session";
@@ -33,6 +34,9 @@ export const REALTIME_VOICE_TOOL_PATH = "/_agent-native/realtime-voice/tool";
 export const REALTIME_VOICE_MAX_SDP_BYTES = 64 * 1024;
 export const REALTIME_VOICE_MAX_TOOL_BODY_BYTES = 64 * 1024;
 export const REALTIME_VOICE_MAX_TOOL_OUTPUT_CHARS = 16_000;
+export const REALTIME_VOICE_MAX_TOOLS = 32;
+export const REALTIME_VOICE_MAX_TOOL_SCHEMA_BYTES = 32_000;
+export const REALTIME_VOICE_MAX_SESSION_BYTES = 64_000;
 
 const OPENAI_REALTIME_CALLS_URL = "https://api.openai.com/v1/realtime/calls";
 const DEFAULT_MODEL = "gpt-realtime-2.1";
@@ -41,7 +45,6 @@ const DEFAULT_INSTRUCTIONS =
   "You are the live voice interface for this Agent Native app. Speak naturally, briefly, and conversationally. Use the available function tools when the user asks you to navigate or take an action. Never claim an action succeeded until its tool result confirms success. If a tool requires approval, explain that the user must approve it in chat.";
 const MAX_INSTRUCTIONS_CHARS = 16_000;
 const MAX_TOOL_DESCRIPTION_CHARS = 2_000;
-const MAX_TOOL_SCHEMA_CHARS = 64 * 1024;
 const MAX_APPROVAL_KEY_CHARS = 1_024;
 const REALTIME_TOOL_NAME = /^[A-Za-z0-9_-]{1,64}$/;
 const CALL_ID = /^[A-Za-z0-9_-]{1,256}$/;
@@ -180,7 +183,13 @@ function normalizeToolSchema(
 ): Record<string, unknown> | null {
   try {
     const serialized = JSON.stringify(inputSchema);
-    if (!serialized || serialized.length > MAX_TOOL_SCHEMA_CHARS) return null;
+    if (
+      !serialized ||
+      Buffer.byteLength(serialized, "utf8") >
+        REALTIME_VOICE_MAX_TOOL_SCHEMA_BYTES
+    ) {
+      return null;
+    }
     const parsed = JSON.parse(serialized) as unknown;
     if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
       return null;
@@ -212,6 +221,28 @@ function buildRealtimeTools(
   return tools;
 }
 
+function packRealtimeTools(
+  session: Record<string, unknown>,
+  eligibleTools: RealtimeFunctionTool[],
+): RealtimeFunctionTool[] {
+  const packed: RealtimeFunctionTool[] = [];
+  for (const tool of eligibleTools.slice(0, REALTIME_VOICE_MAX_TOOLS)) {
+    const candidate = [...packed, tool];
+    const candidateSession = {
+      ...session,
+      tools: candidate,
+      tool_choice: "auto",
+    };
+    if (
+      Buffer.byteLength(JSON.stringify(candidateSession), "utf8") <=
+      REALTIME_VOICE_MAX_SESSION_BYTES
+    ) {
+      packed.push(tool);
+    }
+  }
+  return packed;
+}
+
 function declaredBodyBytes(event: H3Event): number | undefined {
   const raw = readSafeHeader(event, "content-length");
   if (!raw) return undefined;
@@ -301,6 +332,10 @@ function createSessionHandler(
 ) {
   return defineEventHandler(async (event: H3Event) => {
     if (getMethod(event) !== "POST") return invalidMethod(event);
+    if (!isSameOriginRequest(event)) {
+      setResponseStatus(event, 403);
+      return { error: "Cross-origin request rejected" };
+    }
     setResponseHeader(event, "Cache-Control", "no-store");
 
     const auth = await authenticateVoiceRequest(event, options);
@@ -359,7 +394,7 @@ function createSessionHandler(
         }
 
         const instructions = await buildInstructions(auth, options);
-        const session = {
+        const sessionBase = {
           type: "realtime",
           model: configuredIdentifier(options.model, DEFAULT_MODEL),
           instructions,
@@ -378,7 +413,10 @@ function createSessionHandler(
               voice: configuredIdentifier(options.voice, DEFAULT_VOICE),
             },
           },
-          tools,
+        };
+        const session = {
+          ...sessionBase,
+          tools: packRealtimeTools(sessionBase, tools),
           tool_choice: "auto",
         };
 
@@ -529,6 +567,10 @@ function createToolHandler(
 ) {
   return defineEventHandler(async (event: H3Event) => {
     if (getMethod(event) !== "POST") return invalidMethod(event);
+    if (!isSameOriginRequest(event)) {
+      setResponseStatus(event, 403);
+      return { error: "Cross-origin request rejected" };
+    }
     setResponseHeader(event, "Cache-Control", "no-store");
 
     const auth = await authenticateVoiceRequest(event, options);
@@ -623,7 +665,9 @@ export function mountRealtimeVoiceRoutes(
   }
 
   const tools = buildRealtimeTools(actions);
-  const allowedToolNames = new Set(tools.map((tool) => tool.name));
+  const allowedToolNames = new Set(
+    tools.slice(0, REALTIME_VOICE_MAX_TOOLS).map((tool) => tool.name),
+  );
   const app = getH3App(nitroApp);
   app.use(REALTIME_VOICE_SESSION_PATH, createSessionHandler(tools, options));
   app.use(

package/corpus/core/src/server/request-origin.ts

@@ -0,0 +1,67 @@
+import { getRequestHeader, type H3Event } from "h3";
+
+function isLoopbackHost(host: string): boolean {
+  return host.startsWith("localhost:") || host.startsWith("127.0.0.1:");
+}
+
+/**
+ * Reject cross-site POSTs. Cookies are `SameSite=None; Secure` over HTTPS so
+ * the browser would otherwise attach the session to a forged form submission
+ * from evil.com, causing us to spend provider credits on the user's behalf.
+ * Same-origin browsers always send `Origin` on POST; if it's missing we fall
+ * back to `Sec-Fetch-Site` so Safari's fetch-spec behavior still works.
+ */
+export function isSameOriginRequest(event: H3Event): boolean {
+  // Fetch metadata is browser-controlled and describes the relationship
+  // before a reverse proxy rewrites Host (dev-lazy maps :8080 to :8088).
+  // Reject an explicit cross-site signal before consulting forgeable headers.
+  const fetchSite = getRequestHeader(event, "sec-fetch-site");
+  if (fetchSite) return fetchSite === "same-origin" || fetchSite === "none";
+
+  const host = getRequestHeader(event, "host");
+  const origin = getRequestHeader(event, "origin");
+  if (origin && host) {
+    try {
+      const parsed = new URL(origin);
+      const forwardedProto = getRequestHeader(event, "x-forwarded-proto");
+      const forwardedProtocol =
+        forwardedProto === "https" || forwardedProto === "http"
+          ? `${forwardedProto}:`
+          : null;
+      const matchesScheme = forwardedProtocol
+        ? parsed.protocol === forwardedProtocol
+        : parsed.protocol === "https:" ||
+          (parsed.protocol === "http:" && isLoopbackHost(host));
+      if (parsed.host === host && matchesScheme) return true;
+      // Tauri desktop dev serves the tray WebView from localhost:1420 while
+      // the app server lives on the template dev port. Production Tauri
+      // WebViews can also send a tauri://localhost origin. Trust that custom
+      // scheme, while limiting the web-scheme desktop origins below to a
+      // loopback app server so arbitrary websites still fail the CSRF check.
+      if (parsed.protocol === "tauri:" && parsed.hostname === "localhost") {
+        return true;
+      }
+      if (
+        (parsed.protocol === "http:" || parsed.protocol === "https:") &&
+        parsed.hostname === "tauri.localhost" &&
+        isLoopbackHost(host)
+      ) {
+        return true;
+      }
+      if (
+        parsed.protocol === "http:" &&
+        (parsed.hostname === "localhost" || parsed.hostname === "127.0.0.1") &&
+        parsed.port === "1420" &&
+        isLoopbackHost(host)
+      ) {
+        return true;
+      }
+      return false;
+    } catch {
+      return false;
+    }
+  }
+  // No Origin and no Sec-Fetch-Site: likely a non-browser client (curl,
+  // server-side) — safe to allow, CSRF requires a browser with ambient cookies.
+  return true;
+}

package/corpus/core/src/server/ssr-handler.ts

@@ -98,6 +98,22 @@ function requestWithPathname(
   return new Request(url, init);
 }
 
+function requestForAnonymousSsr(request: Request): Request {
+  const headers = new Headers(request.headers);
+  headers.delete("cookie");
+  headers.delete("authorization");
+  const init: RequestInit & { duplex?: "half" } = {
+    method: request.method,
+    headers,
+    signal: request.signal,
+  };
+  if (request.body && !["GET", "HEAD"].includes(request.method.toUpperCase())) {
+    init.body = request.body;
+    init.duplex = "half";
+  }
+  return new Request(request.url, init);
+}
+
 function prefixMountedPath(path: string, basePath: string): string {
   if (!basePath || !path.startsWith("/") || path.startsWith("//")) return path;
   if (path === basePath || path.startsWith(`${basePath}/`)) return path;
@@ -106,7 +122,7 @@ function prefixMountedPath(path: string, basePath: string): string {
 
 function prefixMountedHtml(html: string, basePath: string): string {
   if (!basePath) return html;
-  return html
+  const prefixedHtml = html
     .replace(
       /\b(href|src|action|formaction|poster)=(["'])(\/(?!\/)[^"']*)\2/g,
       (_match, attr: string, quote: string, path: string) =>
@@ -116,6 +132,20 @@ function prefixMountedHtml(html: string, basePath: string): string {
       const q = quote || "";
       return `url(${q}${prefixMountedPath(path, basePath)}${q})`;
     });
+
+  // React Router serializes the server-side basename into its hydration
+  // context. The request above is deliberately rendered mount-relative, so
+  // that value is normally "/" even though the browser URL is mounted at a
+  // workspace prefix such as "/analytics". If the client hydrates that
+  // context unchanged, the mounted pathname no longer matches the route tree:
+  // index redirects can stall and child pages can fall through to the 404.
+  // Keep the serialized router state consistent with the URLs we just
+  // prefixed. Template entry clients also set this defensively for older
+  // responses, but the initial hydration state must be correct at the source.
+  return prefixedHtml.replace(
+    /(window\.__reactRouterContext\s*=\s*\{\s*"basename"\s*:\s*)"(?:\\.|[^"\\])*"/,
+    `$1${JSON.stringify(basePath)}`,
+  );
 }
 
 function injectHeadScript(html: string, script: string | null): string {
@@ -219,6 +249,27 @@ function applyDefaultSsrCacheHeader(
 ) {
   if (!isSsrHtmlOrDataResponse(headers, status, pathname)) return;
 
+  // A public shell must never set a viewer cookie or vary by credentials.
+  // Preserve harmless content-negotiation dimensions such as Accept-Encoding.
+  headers.delete("set-cookie");
+  const vary = headers.get("vary");
+  if (vary) {
+    const publicVary = vary
+      .split(",")
+      .map((value) => value.trim())
+      .filter((value) => {
+        const normalized = value.toLowerCase();
+        return (
+          normalized &&
+          normalized !== "*" &&
+          normalized !== "cookie" &&
+          normalized !== "authorization"
+        );
+      });
+    if (publicVary.length > 0) headers.set("vary", publicVary.join(", "));
+    else headers.delete("vary");
+  }
+
   // Netlify Functions/proxies are not cached by default. Set all three cache
   // headers: Cache-Control for browsers, CDN-Cache-Control for generic CDNs,
   // and Netlify-CDN-Cache-Control (with durable) so Netlify's shared cache
@@ -347,7 +398,9 @@ export function createH3SSRHandler(getBuild: () => Promise<unknown> | unknown) {
       return new Response(null, { status: 404 });
     }
     try {
-      const request = requestWithPathname(event.req as Request, p, basePath);
+      const request = requestForAnonymousSsr(
+        requestWithPathname(event.req as Request, p, basePath),
+      );
       // SSR renders an IMPERSONAL public shell — we deliberately do NOT read the
       // request's session/cookies here, and pin an explicitly anonymous request
       // context. That keeps the SSR HTML/.data identical for every visitor so it

package/corpus/core/src/server/transcribe-voice.ts

@@ -20,7 +20,6 @@
 import {
   defineEventHandler,
   getMethod,
-  getRequestHeader,
   readMultipartFormData,
   setResponseStatus,
   type H3Event,
@@ -43,6 +42,7 @@ import {
   resolveSecret,
 } from "./credential-provider.js";
 import { runWithRequestContext } from "./request-context.js";
+import { isSameOriginRequest } from "./request-origin.js";
 
 const WHISPER_URL = "https://api.openai.com/v1/audio/transcriptions";
 const GROQ_URL = "https://api.groq.com/openai/v1/audio/transcriptions";
@@ -75,55 +75,6 @@ const BUILDER_GEMINI_TRANSCRIPTION_MODEL = "gemini-3-1-flash-lite";
 const GEMINI_MODEL = "gemini-2.0-flash-lite";
 const GEMINI_URL = `https://generativelanguage.googleapis.com/v1beta/models/${GEMINI_MODEL}:generateContent`;
 
-/**
- * Reject cross-site POSTs. Cookies are `SameSite=None; Secure` over HTTPS so
- * the browser would otherwise attach the session to a forged form submission
- * from evil.com, causing us to spend OpenAI credits on the user's behalf.
- * Same-origin browsers always send `Origin` on POST; if it's missing we fall
- * back to `Sec-Fetch-Site` so Safari's fetch-spec behavior still works.
- */
-function isSameOriginRequest(event: H3Event): boolean {
-  const host = getRequestHeader(event, "host");
-  const origin = getRequestHeader(event, "origin");
-  if (origin && host) {
-    try {
-      const parsed = new URL(origin);
-      if (parsed.host === host) return true;
-      // Tauri desktop dev serves the tray WebView from localhost:1420 while
-      // the app server lives on the template dev port. Production Tauri
-      // WebViews can also send a tauri://localhost origin. Treat only those
-      // desktop origins as trusted cross-origin callers; arbitrary websites
-      // still fail the CSRF check.
-      if (parsed.protocol === "tauri:" && parsed.hostname === "localhost") {
-        return true;
-      }
-      if (
-        (parsed.protocol === "http:" || parsed.protocol === "https:") &&
-        parsed.hostname === "tauri.localhost" &&
-        (host.startsWith("localhost:") || host.startsWith("127.0.0.1:"))
-      ) {
-        return true;
-      }
-      if (
-        parsed.protocol === "http:" &&
-        (parsed.hostname === "localhost" || parsed.hostname === "127.0.0.1") &&
-        parsed.port === "1420" &&
-        (host.startsWith("localhost:") || host.startsWith("127.0.0.1:"))
-      ) {
-        return true;
-      }
-      return false;
-    } catch {
-      return false;
-    }
-  }
-  const fetchSite = getRequestHeader(event, "sec-fetch-site");
-  if (fetchSite) return fetchSite === "same-origin" || fetchSite === "none";
-  // No Origin and no Sec-Fetch-Site: likely a non-browser client (curl,
-  // server-side) — safe to allow, CSRF requires a browser with ambient cookies.
-  return true;
-}
-
 /**
  * Derive an AbortSignal that fires when the client disconnects mid-request
  * (e.g. the desktop client's own 8s ceiling firing before a provider call's

package/corpus/core/src/sharing/access.ts

@@ -24,7 +24,7 @@ import {
   requireShareableResource,
   type ShareableResourceRegistration,
 } from "./registry.js";
-import { ROLE_RANK, type ShareRole } from "./schema.js";
+import { ROLE_RANK, type ShareRole, type Visibility } from "./schema.js";
 
 /**
  * Find a registration by its drizzle table identity. Used to look up
@@ -233,6 +233,49 @@ export interface ResolvedAccess {
   resource: any;
 }
 
+/**
+ * Minimal resource shape returned when a caller opts into a projected access
+ * load via `{ skipResourceBody: true }`. Contains exactly the columns the
+ * access-decision logic itself reads — identity, ownership, org scope, and
+ * visibility — never a resource type's heavy body columns (`data`,
+ * `content`, and similar blobs).
+ */
+export interface AccessProjectedResource {
+  id: string;
+  ownerEmail: string;
+  orgId: string | null;
+  visibility: Visibility;
+}
+
+export interface ResolvedAccessProjected {
+  /** Effective role: 'owner' for the resource owner, or the share role. */
+  role: "owner" | ShareRole;
+  /** Only the access-decision columns — not the full resource row. */
+  resource: AccessProjectedResource;
+}
+
+export interface ResolveAccessOptions {
+  /**
+   * When true, load only the columns the access decision itself needs
+   * (`id`, `ownerEmail`, `orgId`, `visibility`) instead of the full resource
+   * row. Use this when the caller only needs the access decision — not the
+   * resource body — and wants to skip fetching heavy type-specific columns
+   * (e.g. `data`/`content` blobs) on every `assertAccess`/`resolveAccess`
+   * call.
+   *
+   * Silently ignored (falls back to a full row load) for any resource type
+   * registered with a `publicAccessRole` *function* resolver, since that
+   * callback can read arbitrary resource fields the projection would have
+   * omitted — see `hasDynamicPublicAccessRoleResolver` below.
+   *
+   * Default: `false` — the full row is loaded, matching historical behavior.
+   * Callers that need resource body fields (most call sites today — for
+   * many resource types `resolveAccess().resource` doubles as the action's
+   * primary data read) must NOT pass this.
+   */
+  skipResourceBody?: boolean;
+}
+
 async function publicAccessRoleForResource(
   reg: ShareableResourceRegistration,
   resource: any,
@@ -278,12 +321,12 @@ function missingColumnName(err: unknown): string | null {
   return null;
 }
 
-function selectAllExistingResourceColumns(
-  resourceTable: any,
+function selectExistingColumns(
+  columns: Record<string, unknown>,
   omittedColumnNames: Set<string>,
 ): Record<string, unknown> {
   const selection: Record<string, unknown> = {};
-  for (const [key, column] of Object.entries(resourceTable)) {
+  for (const [key, column] of Object.entries(columns)) {
     const name = columnName(column);
     if (!name || omittedColumnNames.has(name)) continue;
     selection[key] = column;
@@ -291,21 +334,61 @@ function selectAllExistingResourceColumns(
   return selection;
 }
 
+/**
+ * The fixed column set the access-decision logic in `resolveAccess` itself
+ * reads: identity (`id`), ownership (`ownerEmail`, `orgId`), and the coarse
+ * `visibility` flag. This is intentionally NOT caller-configurable — an
+ * arbitrary caller-supplied column list could omit a column the access
+ * checks below depend on and silently break authorization. Every ownable
+ * resource table has these columns (`ownableColumns()` + a primary key
+ * named `id`), so this projection is safe for any registration that
+ * doesn't also read the row through a dynamic resolver (see below).
+ */
+function projectedAccessColumns(resourceTable: any): Record<string, unknown> {
+  return {
+    id: resourceTable.id,
+    ownerEmail: resourceTable.ownerEmail,
+    orgId: resourceTable.orgId,
+    visibility: resourceTable.visibility,
+  };
+}
+
+/**
+ * True when this registration's `publicAccessRole` is a callback rather than
+ * a fixed role string. Callbacks receive the loaded `resource` and may read
+ * arbitrary fields on it (see e.g. `templates/design`'s
+ * `publicDesignAccessRole`, which inspects design-specific data). The
+ * projected access load must never be used for these registrations — always
+ * fall back to a full row load so the resolver sees the complete resource.
+ */
+function hasDynamicPublicAccessRoleResolver(
+  reg: ShareableResourceRegistration,
+): boolean {
+  return typeof reg.publicAccessRole === "function";
+}
+
 async function loadResourceForAccess(
   reg: ShareableResourceRegistration,
   resourceId: string,
+  options: ResolveAccessOptions = {},
 ): Promise<any | null> {
   const db = reg.getDb() as any;
+  const useProjection =
+    options.skipResourceBody === true &&
+    !hasDynamicPublicAccessRoleResolver(reg);
+  const projectedColumns = useProjection
+    ? projectedAccessColumns(reg.resourceTable)
+    : null;
   const omittedColumnNames = new Set<string>();
 
   for (let attempt = 0; attempt < 12; attempt++) {
     try {
       const query =
-        omittedColumnNames.size === 0
+        !projectedColumns && omittedColumnNames.size === 0
           ? db.select()
           : db.select(
-              selectAllExistingResourceColumns(
-                reg.resourceTable,
+              selectExistingColumns(
+                projectedColumns ?? reg.resourceTable,
                 omittedColumnNames,
               ),
             );
@@ -331,16 +414,53 @@ async function loadResourceForAccess(
 /**
  * Return the effective role the current user has on a specific resource, or
  * null if they have no access. Loads the resource and relevant share rows.
+ *
+ * By default the full resource row is loaded (unchanged historical
+ * behavior — for most resource types `.resource` here doubles as the
+ * action's primary data read). Pass `{ skipResourceBody: true }` when the
+ * caller only needs the access decision to load just the access-decision
+ * columns instead — see `ResolveAccessOptions`.
  */
 export async function resolveAccess(
+  resourceType: string,
+  resourceId: string,
+  rawCtx?: AccessContext,
+  options?: { skipResourceBody?: false },
+): Promise<ResolvedAccess | null>;
+export async function resolveAccess(
+  resourceType: string,
+  resourceId: string,
+  rawCtx: AccessContext | undefined,
+  options: { skipResourceBody: true },
+): Promise<ResolvedAccessProjected | null>;
+export async function resolveAccess(
+  resourceType: string,
+  resourceId: string,
+  rawCtx: AccessContext = currentAccess(),
+  options: ResolveAccessOptions = {},
+): Promise<ResolvedAccess | ResolvedAccessProjected | null> {
+  return resolveAccessImpl(resourceType, resourceId, rawCtx, options);
+}
+
+/**
+ * Un-overloaded implementation shared by the `resolveAccess` overloads and
+ * called directly by `assertAccess` below. Kept separate from the exported
+ * `resolveAccess` so internal callers passing a widened
+ * `ResolveAccessOptions` (rather than a `{ skipResourceBody: true }` /
+ * `{ skipResourceBody?: false }` literal) don't have to satisfy TypeScript's
+ * overload resolution, which only matches against the declared overload
+ * signatures, not the implementation signature.
+ */
+async function resolveAccessImpl(
   resourceType: string,
   resourceId: string,
   rawCtx: AccessContext = currentAccess(),
-): Promise<ResolvedAccess | null> {
+  options: ResolveAccessOptions = {},
+): Promise<ResolvedAccess | ResolvedAccessProjected | null> {
   const reg = requireShareableResource(resourceType);
   const ctx = resolveRegisteredAccessContext(reg, rawCtx);
 
-  const resource = await loadResourceForAccess(reg, resourceId);
+  const resource = await loadResourceForAccess(reg, resourceId, options);
   if (!resource) return null;
 
   const { userEmail, orgId } = ctx;
@@ -421,14 +541,38 @@ async function highestShareRole(
 /**
  * Throw ForbiddenError if the current user can't act on this resource with at
  * least the given role. Used at the top of update/delete actions.
+ *
+ * By default the full resource row is loaded (unchanged historical
+ * behavior). Pass `{ skipResourceBody: true }` as the fifth argument when
+ * the caller only needs the access decision — see `ResolveAccessOptions`.
  */
+export async function assertAccess(
+  resourceType: string,
+  resourceId: string,
+  minRole?: ShareRole | "owner",
+  ctx?: AccessContext,
+  options?: { skipResourceBody?: false },
+): Promise<ResolvedAccess>;
+export async function assertAccess(
+  resourceType: string,
+  resourceId: string,
+  minRole: ShareRole | "owner" | undefined,
+  ctx: AccessContext | undefined,
+  options: { skipResourceBody: true },
+): Promise<ResolvedAccessProjected>;
 export async function assertAccess(
   resourceType: string,
   resourceId: string,
   minRole: ShareRole | "owner" = "viewer",
   ctx: AccessContext = currentAccess(),
-): Promise<ResolvedAccess> {
-  const access = await resolveAccess(resourceType, resourceId, ctx);
+  options: ResolveAccessOptions = {},
+): Promise<ResolvedAccess | ResolvedAccessProjected> {
+  const access = await resolveAccessImpl(
+    resourceType,
+    resourceId,
+    ctx,
+    options,
+  );
   if (!access) {
     throw new ForbiddenError(`No access to ${resourceType} ${resourceId}`);
   }

package/corpus/core/src/sharing/registry.ts

@@ -61,6 +61,13 @@ export interface ShareableResourceRegistration {
    * this so public visibility remains viewer-only. Use narrowly for local or
    * otherwise constrained resources where the resource owner intentionally wants
    * unauthenticated link holders to do more than view.
+   *
+   * When this is a function, it may read arbitrary fields on the resource row
+   * (not just the ownership/visibility columns). Because of that,
+   * `resolveAccess`/`assertAccess`'s opt-in `{ skipResourceBody: true }`
+   * projected load (see `access.ts`) is automatically ignored for this
+   * registration and always loads the full row instead — a fixed role string
+   * has no such requirement and is compatible with the projection.
    */
   publicAccessRole?:
     | "viewer"