fontdue-js 3.0.6 → 3.1.0

package/dist/next/tenant.js

@@ -29,6 +29,7 @@ import { notFound, unstable_rethrow } from 'next/navigation';
 import { cookies, draftMode } from 'next/headers';
 import { setFontdueServerConfig } from '../relay/serverConfig.js';
 import { PREVIEW_TOKEN_COOKIE, previewAuthHeaders } from '../preview/index.js';
+import { NODE_ACCESS_COOKIE, NODE_ACCESS_HEADER } from '../nodeAccess.js';
 export const isMultiTenant = process.env.FONTDUE_MULTI_TENANT === '1';
 export const singleTenantUrl = process.env.NEXT_PUBLIC_FONTDUE_URL;
 const internalOrigin = process.env.FONTDUE_ORIGIN;
@@ -155,6 +156,30 @@ export async function __prepareFontdueRender(props) {
   return endpointForDomain(domain);
 }
 
+// The visitor's per-collection node-access header for the current request, or {}
+// when they haven't unlocked anything. Reads the first-party cookie the password
+// form set and returns it as `{ 'fontdue-node-access': <tokens> }`, ready to
+// spread into a GraphQL fetch's headers so the unlocked collection resolves.
+//
+// Reading cookies() opts the route into dynamic rendering, so call this only
+// when it's actually needed — after a public fetch comes back
+// password-protected — to keep non-protected font pages static/cacheable. The
+// catch mirrors readPreviewHeaders: re-throw Next's control-flow bailout so a
+// protected page renders dynamically instead of being prerendered cookie-blind
+// (which would serve the locked form to a visitor who has unlocked it).
+export async function nodeAccessHeaders() {
+  try {
+    var _await$cookies$get;
+    const value = (_await$cookies$get = (await cookies()).get(NODE_ACCESS_COOKIE)) === null || _await$cookies$get === void 0 ? void 0 : _await$cookies$get.value;
+    return value ? {
+      [NODE_ACCESS_HEADER]: value
+    } : {};
+  } catch (error) {
+    unstable_rethrow(error);
+    return {};
+  }
+}
+
 // The admin preview token for this render, as Authorization headers, or
 // undefined when not previewing. Draft mode gates it: reading draftMode().
 // isEnabled is static-safe (it returns false during static generation and only
@@ -182,9 +207,9 @@ export async function __prepareFontdueRender(props) {
 //      so unstable_rethrow is a no-op and we fall through to "not previewing".
 async function readPreviewHeaders() {
   try {
-    var _await$cookies$get;
+    var _await$cookies$get2;
     if (!(await draftMode()).isEnabled) return undefined;
-    const token = (_await$cookies$get = (await cookies()).get(PREVIEW_TOKEN_COOKIE)) === null || _await$cookies$get === void 0 ? void 0 : _await$cookies$get.value;
+    const token = (_await$cookies$get2 = (await cookies()).get(PREVIEW_TOKEN_COOKIE)) === null || _await$cookies$get2 === void 0 ? void 0 : _await$cookies$get2.value;
     return token ? previewAuthHeaders(token) : undefined;
   } catch (error) {
     unstable_rethrow(error);

package/dist/nodeAccess.d.ts

@@ -0,0 +1,18 @@
+export declare const NODE_ACCESS_COOKIE = "fontdue_node_access";
+export declare const NODE_ACCESS_HEADER = "fontdue-node-access";
+/** The node-access cookie value from a Cookie header string, or undefined. */
+export declare function readNodeAccessCookie(cookieHeader: string | null | undefined): string | undefined;
+/**
+ * The node-access forwarding header for a Cookie header string, or {} when the
+ * cookie is absent. Spread into a server-side GraphQL fetch's headers so a
+ * collection the visitor unlocked resolves for them. Returns {} for public
+ * (no-cookie) requests, leaving them untouched and cacheable.
+ */
+export declare function nodeAccessHeadersFromCookie(cookieHeader: string | null | undefined): Record<string, string>;
+/**
+ * Remember a freshly minted access token in the browser's node-access cookie,
+ * preserving any collections already unlocked. First-party and JS-readable on
+ * purpose (see the module note); SameSite=Lax so it rides top-level navigations,
+ * Secure only on https so it still persists in local dev. No-op off the browser.
+ */
+export declare function rememberNodeAccessToken(token: string | null | undefined): void;

package/dist/nodeAccess.js

@@ -0,0 +1,84 @@
+// Per-collection node-access contract.
+//
+// When a visitor unlocks a password-protected collection (the `accessNode`
+// mutation), the server returns a signed token. The browser remembers it in a
+// first-party cookie, and a server-rendered storefront forwards that cookie to
+// GraphQL as a request header so the collection keeps resolving for this visitor.
+//
+// This mirrors the admin-preview token contract (see ./preview/constants), with
+// one deliberate difference: the node-access token is low sensitivity — it only
+// re-grants access the visitor already earned by entering the password — so it is
+// a plain, JS-readable first-party cookie the form sets directly in the browser,
+// not an httpOnly cookie brokered through a server route. That keeps the
+// template surface tiny: no `/api/...` route to mount, just the form plus the
+// transport every framework already runs for preview.
+//
+// Kept free of Web/Node APIs (only `document`, behind a guard) so it can be
+// imported from both server transport and the client component.
+
+// First-party cookie the browser carries after unlocking. Value is a
+// comma-separated list of signed tokens, one per unlocked collection.
+export const NODE_ACCESS_COOKIE = 'fontdue_node_access';
+
+// Request header a server-rendered storefront forwards the cookie value as, read
+// back by the Fontdue GraphQL server (see FontageWeb.Schema.Context).
+export const NODE_ACCESS_HEADER = 'fontdue-node-access';
+
+// ~30 days, matching the token's `max_age` on the server (Fontage.Token
+// `:node_access`). The cookie and the token expire together.
+const NODE_ACCESS_MAX_AGE_SECONDS = 60 * 60 * 24 * 30;
+
+// Cap on how many unlock tokens the cookie carries. The value is a
+// comma-separated list of ~150-byte signed tokens, so an unbounded list would
+// eventually pass the browser's ~4 KB per-cookie limit and be dropped whole —
+// silently losing every unlock. We keep the most recent few (oldest are also
+// the closest to their 30-day expiry, so the server would drop them anyway) and
+// evict from the front. A visitor unlocking more than this many collections is
+// well outside the intended "share a handful of drafts" use.
+const MAX_NODE_ACCESS_TOKENS = 16;
+
+/** The node-access cookie value from a Cookie header string, or undefined. */
+export function readNodeAccessCookie(cookieHeader) {
+  if (!cookieHeader) return undefined;
+  for (const part of cookieHeader.split(';')) {
+    const idx = part.indexOf('=');
+    if (idx === -1) continue;
+    if (part.slice(0, idx).trim() !== NODE_ACCESS_COOKIE) continue;
+    const value = part.slice(idx + 1).trim();
+    return value === '' ? undefined : value;
+  }
+  return undefined;
+}
+
+/**
+ * The node-access forwarding header for a Cookie header string, or {} when the
+ * cookie is absent. Spread into a server-side GraphQL fetch's headers so a
+ * collection the visitor unlocked resolves for them. Returns {} for public
+ * (no-cookie) requests, leaving them untouched and cacheable.
+ */
+export function nodeAccessHeadersFromCookie(cookieHeader) {
+  const value = readNodeAccessCookie(cookieHeader);
+  return value ? {
+    [NODE_ACCESS_HEADER]: value
+  } : {};
+}
+
+/**
+ * Remember a freshly minted access token in the browser's node-access cookie,
+ * preserving any collections already unlocked. First-party and JS-readable on
+ * purpose (see the module note); SameSite=Lax so it rides top-level navigations,
+ * Secure only on https so it still persists in local dev. No-op off the browser.
+ */
+export function rememberNodeAccessToken(token) {
+  if (typeof document === 'undefined' || !token) return;
+  const existing = readNodeAccessCookie(document.cookie);
+  const tokens = existing ? existing.split(',').filter(Boolean) : [];
+  if (!tokens.includes(token)) tokens.push(token);
+  // Keep the list bounded so it can't grow past the browser's cookie-size limit
+  // and get dropped wholesale; the newest unlock is always retained.
+  if (tokens.length > MAX_NODE_ACCESS_TOKENS) {
+    tokens.splice(0, tokens.length - MAX_NODE_ACCESS_TOKENS);
+  }
+  const secure = typeof location !== 'undefined' && location.protocol === 'https:' ? '; Secure' : '';
+  document.cookie = `${NODE_ACCESS_COOKIE}=${tokens.join(',')}; Path=/; SameSite=Lax${secure}; Max-Age=${NODE_ACCESS_MAX_AGE_SECONDS}`;
+}

package/dist/preview/server.d.ts

@@ -1,20 +1 @@
-/** Whether the current async context is an admin preview. */
-export declare function isPreviewing(): boolean;
-/**
- * Preview auth headers for the current async context, or {} when not previewing.
- * Spread into a hand-rolled fetch you make inside `runWithPreview`; the
- * fontdue-js fetch/preload helpers pick these up automatically and don't need
- * it.
- */
-export declare function ambientPreviewHeaders(): Record<string, string>;
-/**
- * Run `next` (your framework's render/loader chain) with the request's preview
- * token in ambient context, then return its Response. When the request is
- * previewing, the response's cache headers are rewritten so it is never stored
- * in a shared/CDN cache. Public (no-token) requests pass through untouched and
- * stay fully cacheable.
- *
- * `next` is your middleware's continuation — `next` in Astro, `next` in a React
- * Router 7 middleware. It must return (a promise of) the Response.
- */
-export declare function runWithPreview(request: Request, next: () => Response | Promise<Response>): Promise<Response>;
+export { runWithPreview, isPreviewing, ambientHeaders as ambientPreviewHeaders, } from '../server/middleware.js';

package/dist/preview/server.js

@@ -1,89 +1,20 @@
-// Ambient (request-scoped) preview for non-RSC server frameworks.
+// Ambient (request-scoped) admin preview for non-RSC server frameworks.
 //
-// fontdue-js/preview gives you the cookie contract and an explicit option:
-// read the token per request and thread `previewAuthHeaders(token)` into every
-// GraphQL fetch and preload helper. That's portable but easy to get wrong — miss
-// one preload and that island silently renders the public view.
+// The ambient-context machinery moved to ../server/middleware, because it is
+// shared by admin preview and the per-collection password unlock (and a
+// storefront usually wants both). This module re-exports the preview-facing
+// pieces so existing `fontdue-js/preview/server` imports keep working:
 //
-// This module removes the threading. `runWithPreview` establishes an
-// AsyncLocalStorage context for the duration of a request; while it's active,
-// every fontdue-js server fetch (createFontdueFetch and all the preload helpers)
-// automatically forwards the admin preview token, with no per-call plumbing —
-// the same ergonomics RSC gets from React.cache, and the same mechanism Next's
-// own headers()/draftMode() use under the hood. Install it once in your
-// framework's middleware:
+//   - runWithPreview — forward only the admin preview token (reveals
+//     unpublished fonts). Mount it in your framework's request middleware.
+//   - isPreviewing / ambientPreviewHeaders — read the current ambient state.
 //
-//   // Astro: src/middleware.ts
-//   export const onRequest = (ctx, next) => runWithPreview(ctx.request, next);
-//
-//   // React Router 7 (root route, with future.v8_middleware):
-//   export const middleware = [({ request }, next) => runWithPreview(request, next)];
-//
-// runWithPreview also binds the cache guarantee to the same call: when a request
-// is previewing, the response is forced out of any shared/CDN cache. Because the
-// context and the no-cache rule are set in one place, you can't be ambiently
-// previewing without the response being uncacheable — so an admin render is never
-// served to the public.
-//
-// Requirements & fallback: AsyncLocalStorage must propagate from the install
-// point into the render. That holds for in-process middleware — Node (Netlify
-// Functions, the default SSR target), Deno (Netlify Edge), Bun. It does NOT hold
-// when middleware runs in a separate runtime from the render (e.g. Astro with
-// `edgeMiddleware: true`, where locals cross the boundary as a serialized
-// header). In that case fall back to the explicit path: read the token in
-// middleware and thread `previewAuthHeaders(token)` via the `headers` option on
-// fetches/preloads. The explicit `headers` option always overrides the ambient
-// context, so the two compose.
-
-import { AsyncLocalStorage } from 'node:async_hooks';
-import { readPreviewToken, previewAuthHeaders } from './index.js';
-import { registerAmbientConfigResolver } from '../relay/serverConfig.js';
-const previewStore = new AsyncLocalStorage();
-
-// Feed the ambient token into fontdue-js's server config resolution. Returns
-// undefined outside a preview context, so non-preview requests are untouched.
-registerAmbientConfigResolver(() => {
-  const store = previewStore.getStore();
-  return store ? {
-    headers: store.headers
-  } : undefined;
-});
-
-/** Whether the current async context is an admin preview. */
-export function isPreviewing() {
-  return previewStore.getStore() != null;
-}
-
-/**
- * Preview auth headers for the current async context, or {} when not previewing.
- * Spread into a hand-rolled fetch you make inside `runWithPreview`; the
- * fontdue-js fetch/preload helpers pick these up automatically and don't need
- * it.
- */
-export function ambientPreviewHeaders() {
-  var _previewStore$getStor;
-  return ((_previewStore$getStor = previewStore.getStore()) === null || _previewStore$getStor === void 0 ? void 0 : _previewStore$getStor.headers) ?? {};
-}
-const NO_STORE = 'private, no-store';
+// To also forward a visitor's password-unlock token, mount the precomposed
+// `runWithFontdue` from `fontdue-js/server/middleware` in place of
+// runWithPreview (or compose runWithPreview with runWithNodeAccess yourself).
+// See the password-protected collections guide.
 
-/**
- * Run `next` (your framework's render/loader chain) with the request's preview
- * token in ambient context, then return its Response. When the request is
- * previewing, the response's cache headers are rewritten so it is never stored
- * in a shared/CDN cache. Public (no-token) requests pass through untouched and
- * stay fully cacheable.
- *
- * `next` is your middleware's continuation — `next` in Astro, `next` in a React
- * Router 7 middleware. It must return (a promise of) the Response.
- */
-export async function runWithPreview(request, next) {
-  const token = readPreviewToken(request.headers.get('cookie'));
-  if (!token) return next();
-  const response = await previewStore.run({
-    headers: previewAuthHeaders(token)
-  }, next);
-  response.headers.set('Cache-Control', NO_STORE);
-  response.headers.delete('Netlify-CDN-Cache-Control');
-  response.headers.delete('CDN-Cache-Control');
-  return response;
-}
+export { runWithPreview, isPreviewing,
+// Historical name kept for back-compat; returns the full ambient header set
+// (preview and/or node-access), so it works under runWithFontdue too.
+ambientHeaders as ambientPreviewHeaders } from '../server/middleware.js';

package/dist/relay/environment.js

@@ -2,12 +2,13 @@ import { Environment, Network, RecordSource, Store, QueryResponseCache } from 'r
 import { handlePossibleCorsError } from '../corsError.js';
 import { resolveFontdueServerConfig } from './serverConfig.js';
 import { PREVIEW_HEADER, hasPreviewMarkerCookie } from '../preview/constants.js';
+import { NODE_ACCESS_HEADER } from '../nodeAccess.js';
 
 // `__FONTDUE_JS_VERSION__` is replaced by an inline babel plugin
 // (defineVersionPlugin in .babelrc.cjs) with the literal package.json#version.
 // Exported so UI (the admin toolbar) can surface it without re-reading the
 // build-time global in a 'use client' module.
-export const version = "3.0.6";
+export const version = "3.1.0";
 const IS_SERVER = typeof window === typeof undefined;
 
 // Opt server fetches into Next's data cache only in production; dev stays
@@ -91,6 +92,11 @@ export function createNetworkFetch(options) {
     const previewing = IS_SERVER ? headers.authorization != null || headers.Authorization != null : hasPreviewMarkerCookie();
     headers[PREVIEW_HEADER] = previewing ? 'true' : 'false';
 
+    // A forwarded node-access token (a collection this visitor unlocked) makes
+    // the server response per-visitor just like preview, so it must never be
+    // written to or served from the shared data cache.
+    const perVisitor = previewing || IS_SERVER && headers[NODE_ACCESS_HEADER] != null;
+
     // Public server fetches are all site content (per-session data is fetched
     // client-side only), so opt them into Next's data cache — without this,
     // Next 15 treats them as no-store and silently makes every page fully
@@ -113,7 +119,7 @@ export function createNetworkFetch(options) {
         variables
       })
     };
-    if (IS_SERVER && (previewing || !cacheInProduction())) {
+    if (IS_SERVER && (perVisitor || !cacheInProduction())) {
       init.cache = 'no-store';
     } else if (IS_SERVER) {
       init.cache = 'force-cache';

package/dist/relay/serverConfig.d.ts

@@ -8,7 +8,10 @@ export interface FontdueServerConfig {
 }
 type MaybePromise<T> = T | Promise<T>;
 type AmbientConfigResolver = () => MaybePromise<FontdueServerConfig | undefined>;
+type NodeAccessRecovery = () => MaybePromise<Record<string, string>>;
 export declare function setFontdueServerConfig(config: FontdueServerConfig): void;
 export declare function registerAmbientConfigResolver(resolver: AmbientConfigResolver): void;
+export declare function registerNodeAccessRecovery(recovery: NodeAccessRecovery): void;
+export declare function resolveNodeAccessRecovery(): NodeAccessRecovery | undefined;
 export declare function resolveFontdueServerConfig(): Promise<FontdueServerConfig | undefined>;
 export {};

package/dist/relay/serverConfig.js

@@ -26,6 +26,9 @@
 
 import * as React from 'react';
 
+// Recovers a visitor's per-collection node-access headers when a server fetch
+// comes back `password_protected` — see registerNodeAccessRecovery below.
+
 // This module owns two pieces of cross-cutting state — the render-scoped slot
 // and the ambient resolver — and both must be shared by every server-side
 // fetch in a render. The catch: a Next.js server build can bundle this same
@@ -58,7 +61,8 @@ function store() {
       })) : () => ({
         current: undefined
       }),
-      ambientResolver: undefined
+      ambientResolver: undefined,
+      nodeAccessRecovery: undefined
     };
     g[STORE_KEY] = s;
   }
@@ -84,6 +88,23 @@ export function registerAmbientConfigResolver(resolver) {
   store().ambientResolver = resolver;
 }
 
+// Node-access recovery — the seam that lets the browser-safe transport recover
+// from a `password_protected` error without importing a framework's request
+// APIs. The Next adapter registers a recovery that reads the visitor's
+// node-access cookie (via next/headers); createFontdueFetch calls it when a
+// fetch comes back locked, folds the returned headers into the per-render config
+// so the page fetch AND the embedded server components' own preloads resolve,
+// then retries once (see ../server/index.ts). Returns {} when the visitor hasn't
+// unlocked the collection. Unregistered (non-Next, or frameworks that forward
+// the token ambiently up-front via runWithNodeAccess) → no recovery, the error
+// propagates so the page can render the password form.
+export function registerNodeAccessRecovery(recovery) {
+  store().nodeAccessRecovery = recovery;
+}
+export function resolveNodeAccessRecovery() {
+  return store().nodeAccessRecovery;
+}
+
 // Merge an ambient config under the RSC slot: the slot wins for scalar fields;
 // headers merge with the slot overriding.
 function mergeServerConfig(ambient, slot) {

package/dist/server/index.d.ts

@@ -2,6 +2,14 @@ export declare class FontdueNotFoundError extends Error {
     readonly queryName: string;
     constructor(queryName: string);
 }
+export declare class FontdueGraphqlError extends Error {
+    readonly code: string | undefined;
+    readonly queryName: string;
+    constructor(message: string, code: string | undefined, queryName: string);
+}
+export declare class FontduePasswordProtectedError extends FontdueGraphqlError {
+    constructor(message: string, queryName: string);
+}
 export interface CreateFontdueFetchOptions {
     /**
      * GraphQL base URL (without the trailing /graphql), e.g.

package/dist/server/index.js

@@ -45,7 +45,7 @@
 // The Next fetch hints are inert in other runtimes: Node's fetch accepts and
 // ignores the cache mode, and `next` is just an unknown init property.
 
-import { resolveFontdueServerConfig } from '../relay/serverConfig.js';
+import { resolveFontdueServerConfig, setFontdueServerConfig, resolveNodeAccessRecovery } from '../relay/serverConfig.js';
 import { PREVIEW_HEADER } from '../preview/constants.js';
 function readEnv(name) {
   if (typeof process !== 'undefined' && process.env) {
@@ -87,6 +87,30 @@ export class FontdueNotFoundError extends Error {
     this.name = 'FontdueNotFoundError';
   }
 }
+
+// Thrown when a GraphQL response carries an `errors` entry. Subclasses Error so
+// existing `catch`/rethrow keeps working, but also exposes the machine-readable
+// `code` from the first error (e.g. "password_protected") so callers can branch
+// on a specific failure instead of string-matching the message.
+export class FontdueGraphqlError extends Error {
+  constructor(message, code, queryName) {
+    super(message);
+    this.code = code;
+    this.queryName = queryName;
+    this.name = 'FontdueGraphqlError';
+  }
+}
+
+// Thrown when the requested collection is password-protected and the visitor
+// hasn't unlocked it. Catch it to render a <NodePasswordForm> instead of a 404:
+// the collection exists, it's just gated. The matching server signal is the
+// GraphQL error code "password_protected" (see the Fontdue slug resolver).
+export class FontduePasswordProtectedError extends FontdueGraphqlError {
+  constructor(message, queryName) {
+    super(message, 'password_protected', queryName);
+    this.name = 'FontduePasswordProtectedError';
+  }
+}
 /**
  * Build a server-side GraphQL fetcher bound to a base URL and a set of headers.
  * The returned function takes the operation name, the query text (load it from
@@ -94,8 +118,10 @@ export class FontdueNotFoundError extends Error {
  */
 export function createFontdueFetch() {
   let options = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
-  return async function fetchGraphql(queryName, query, variables) {
-    var _json$errors, _json$errors$;
+  async function runOnce(queryName, query, variables) {
+    let {
+      forceUncached = false
+    } = arguments.length > 3 && arguments[3] !== undefined ? arguments[3] : {};
     // Per-render config (a runWithPreview AsyncLocalStorage store, the Next
     // render-scoped slot, or the Next single-tenant ambient resolver). Awaited
     // per call so a single module-level fetcher picks up the current request's
@@ -111,7 +137,9 @@ export function createFontdueFetch() {
     // Cache tags: explicit option wins, else the per-render config's. A
     // non-empty list opts the fetch into Next's data cache (inert elsewhere);
     // an empty/absent list leaves it uncached (preview + CDN-cached frameworks).
-    const cacheTags = options.cacheTags ?? (config === null || config === void 0 ? void 0 : config.cacheTags);
+    // A forced-uncached retry (an unlocked, per-visitor render) drops them
+    // entirely so nothing tags the response into the shared cache.
+    const cacheTags = forceUncached ? undefined : options.cacheTags ?? (config === null || config === void 0 ? void 0 : config.cacheTags);
 
     // Ambient headers (e.g. tenant + preview token), overridden by any explicit
     // per-fetcher headers.
@@ -151,10 +179,65 @@ export function createFontdueFetch() {
       throw new Error(`Fontdue request failed: ${response.status}`);
     }
     const json = await response.json();
-    const errorMessage = (_json$errors = json.errors) === null || _json$errors === void 0 ? void 0 : (_json$errors$ = _json$errors[0]) === null || _json$errors$ === void 0 ? void 0 : _json$errors$.message;
-    if (errorMessage) {
-      throw new Error(`Fontdue GraphQL error: ${errorMessage}`);
+    const errors = json.errors ?? [];
+    if (errors.length > 0) {
+      // Absinthe puts a resolver's error `code` on the error itself; some errors
+      // carry it under `extensions` instead — check both.
+      const codeOf = e => {
+        var _e$extensions;
+        return e.code ?? ((_e$extensions = e.extensions) === null || _e$extensions === void 0 ? void 0 : _e$extensions.code);
+      };
+      // Look across every error, not just the first: a query that touches a
+      // locked collection alongside another failing field can return
+      // `password_protected` in any position, and the recovery + the app's
+      // `instanceof FontduePasswordProtectedError` catch both depend on it being
+      // recognized regardless of order.
+      const locked = errors.find(e => codeOf(e) === 'password_protected');
+      if (locked) {
+        throw new FontduePasswordProtectedError(`Fontdue GraphQL error: ${locked.message}`, queryName);
+      }
+      const first = errors[0];
+      throw new FontdueGraphqlError(`Fontdue GraphQL error: ${first.message}`, codeOf(first), queryName);
     }
     return json.data;
+  }
+  return async function fetchGraphql(queryName, query, variables) {
+    try {
+      return await runOnce(queryName, query, variables);
+    } catch (error) {
+      // A password-protected collection comes back as a `password_protected`
+      // error. In a server render, recover transparently: a registered recovery
+      // (the Next adapter) reads the visitor's node-access cookie. If they've
+      // unlocked it, fold the token into the per-render config — so this fetch
+      // AND the page's embedded server components' own (Suspense) preloads
+      // resolve, not just this one call — and retry once. Reading the cookie is
+      // deferred to here (only when a fetch is actually gated) so non-protected
+      // pages stay static/cacheable; the retry runs `forceUncached` so the
+      // unlocked, per-visitor render is never written to the shared cache.
+      // Frameworks that forward the token ambiently up-front (runWithNodeAccess)
+      // never reach this path. With no recovery registered, or no token, the
+      // error propagates so the page can render the password form.
+      if (error instanceof FontduePasswordProtectedError) {
+        const recover = resolveNodeAccessRecovery();
+        if (recover) {
+          const nodeAccess = await recover();
+          if (Object.keys(nodeAccess).length > 0) {
+            const config = (await resolveFontdueServerConfig()) ?? {};
+            setFontdueServerConfig({
+              ...config,
+              headers: {
+                ...config.headers,
+                ...nodeAccess
+              },
+              cacheTags: undefined
+            });
+            return await runOnce(queryName, query, variables, {
+              forceUncached: true
+            });
+          }
+        }
+      }
+      throw error;
+    }
   };
 }

package/dist/server/middleware.d.ts

@@ -0,0 +1,37 @@
+/** Whether the current async context is an admin preview. */
+export declare function isPreviewing(): boolean;
+/**
+ * Request-scoped Fontdue headers for the current async context (admin preview
+ * and/or the visitor's node-access token), or {} when there are none. Spread
+ * into a hand-rolled fetch you make inside a runWith* middleware; the fontdue-js
+ * fetch/preload helpers pick these up automatically and don't need it.
+ */
+export declare function ambientHeaders(): Record<string, string>;
+/**
+ * Run `next` (your framework's render/loader chain) with the request's admin
+ * preview token in ambient scope, then return its Response. While active, every
+ * fontdue-js server fetch forwards the token (reveals unpublished fonts) with no
+ * per-call plumbing; when previewing, the response is forced out of any
+ * shared/CDN cache. Public requests (no preview cookie) pass through untouched
+ * and stay fully cacheable. For the visitor password-unlock token use
+ * runWithNodeAccess; for both, runWithFontdue.
+ */
+export declare function runWithPreview(request: Request, next: () => Response | Promise<Response>): Promise<Response>;
+/**
+ * Run `next` with the visitor's per-collection node-access token in ambient
+ * scope, then return its Response. The token is read from the first-party cookie
+ * the password form set; while active, every fontdue-js server fetch forwards it
+ * so a collection the visitor unlocked resolves for them. A request carrying an
+ * unlock is per-visitor, so its response is forced out of any shared/CDN cache —
+ * an unlocked render is never served to someone who hasn't unlocked. Requests
+ * with no node-access cookie pass through untouched and stay cacheable.
+ */
+export declare function runWithNodeAccess(request: Request, next: () => Response | Promise<Response>): Promise<Response>;
+/**
+ * The precomposed middleware most storefronts want: forwards the admin preview
+ * token AND the visitor's node-access token, each handled by its own
+ * single-responsibility middleware. Equivalent to nesting
+ * `runWithPreview(request, () => runWithNodeAccess(request, next))` — mount this
+ * in place of runWithPreview to get the password-unlock forwarding too.
+ */
+export declare function runWithFontdue(request: Request, next: () => Response | Promise<Response>): Promise<Response>;