payload-live-preview 1.8.0 → 2.0.0-beta.0

package/dist/adapters/astro/PreviewBoundary.astro

@@ -0,0 +1,66 @@
+---
+/**
+ * A stable anchor for a field that may be empty.
+ *
+ * The runtime can only patch elements that exist. A template that renders a
+ * binding only when the field is non-empty leaves the editor with nothing to
+ * see when they fill a previously empty field. `PreviewBoundary` renders the
+ * wrapper always: with content when the value is present, and as an empty,
+ * `hidden` element otherwise — out of layout and out of the accessibility
+ * tree, so a public visitor and a screen reader see exactly what they would
+ * have seen without live preview. When an update fills the field, the
+ * runtime removes `hidden`; when it empties it, the runtime hides the
+ * wrapper again.
+ *
+ * Usage:
+ *
+ * ```astro
+ * ---
+ * import PreviewBoundary from 'payload-live-preview/astro/PreviewBoundary.astro';
+ * ---
+ * <PreviewBoundary field="subtitle" value={page.subtitle} as="p" class="lede">
+ *   {page.subtitle}
+ * </PreviewBoundary>
+ * ```
+ *
+ * `data-payload-strategy="patch"` is written explicitly: the wrapper is a
+ * patch target, and markup that needs the future fragment strategy says so
+ * with a different value.
+ */
+
+interface Props {
+  /** Payload field path to bind, e.g. `"subtitle"` or `"hero.caption"`. */
+  field: string;
+  /** The field's value, used only to decide whether the anchor starts hidden. */
+  value: unknown;
+  /** Wrapper tag. Default `div`. */
+  as?: string;
+  /** Renderer to force (`data-payload-type`), e.g. `richText`. */
+  type?: string;
+  /** Additional attributes are forwarded to the wrapper. */
+  [attribute: string]: unknown;
+}
+
+const { field, value, as = 'div', type, ...rest } = Astro.props as Props;
+
+function isEmpty(candidate: unknown): boolean {
+  if (candidate === null || candidate === undefined) return true;
+  if (typeof candidate === 'string') return candidate.trim().length === 0;
+  if (Array.isArray(candidate)) return candidate.length === 0;
+  return false;
+}
+
+const Tag = as;
+const empty = isEmpty(value);
+---
+
+<Tag
+  {...rest}
+  data-payload-field={field}
+  data-payload-type={type}
+  data-payload-boundary=""
+  data-payload-strategy="patch"
+  hidden={empty ? true : undefined}
+>
+  <slot />
+</Tag>

package/dist/adapters/astro/RichText.astro

@@ -28,6 +28,12 @@
  * imported by your page before this component renders. Registrations
  * are module/realm-local and do not automatically configure the
  * prebuilt inline runtime.
+ *
+ * Their output is yours to escape here. The built-in renderers escape
+ * every value they interpolate, but the sanitizer that would catch a
+ * custom renderer's mistake needs a DOM, and there is none during SSR
+ * unless the project supplied one with `setSanitizerDocument()`. See
+ * docs/security.md §3.
  */
 // Self-referencing import so the shipped copy in dist/ resolves
 // through the package exports map in consumer projects.

package/dist/adapters/astro/index.d.ts

@@ -1,36 +1,12 @@
-import { L as LivePreviewAstroOptions } from '../../middleware-DD4Hwomt.js';
-export { a as LivePreviewMiddleware, N as NONCE_LOCALS_KEY, c as createLivePreviewMiddleware } from '../../middleware-DD4Hwomt.js';
+import { L as LivePreviewAstroOptions } from '../../middleware-CEPsY1P7.js';
+export { a as LivePreviewMiddleware, c as createLivePreviewMiddleware } from '../../middleware-CEPsY1P7.js';
+import { P as PreviewAuthorizationRequest, A as AuthorizedPreviewScope, a as AuthorizedPreviewContext } from '../../options-CEzzfHJu.js';
+export { b as PreviewAdapterOptions, c as PreviewRequestLike, d as PreviewRequestOptions, h as hasPreviewIntent } from '../../options-CEzzfHJu.js';
 
 /**
- * Astro integration for Payload Live Preview.
- *
- * Drop into `astro.config.mjs`:
- *
- * ```ts
- * import { defineConfig } from 'astro/config';
- * import { livePreview } from 'payload-live-preview/astro';
- *
- * export default defineConfig({
- *   integrations: [livePreview({ allowedOrigins: ['https://admin.example.com'] })],
- * });
- * ```
- *
- * Two injection modes:
- *
- *   - **`mode: 'inline'`** (default) — `injectScript('head-inline', …)`
- *     bakes the runtime into every page at build time. Right choice
- *     for `output: 'static'`, where no middleware runs at request
- *     time. The runtime stays inert outside the admin iframe.
- *   - **`mode: 'middleware'`** — registers the preview middleware via
- *     `addMiddleware()`: the runtime is injected at request time into
- *     requests carrying preview intent, and `frame-ancestors` CSP is
- *     managed. This is a delivery gate, not authentication. For
- *     authorization-gated response changes, register
- *     `createLivePreviewMiddleware()` manually after the application's
- *     server-side verifier. (`shouldInject` is not supported in this
- *     mode: options travel through a serialized virtual module.)
- *
- * @module @adapters/astro/integration
+ * The Astro integration for `astro.config.mjs`: `livePreview({ ... })`.
+ * Inline and loader modes deliver at build time; middleware mode registers
+ * the request-time middleware through a serialized options module.
  */
 
 type ScriptStage = 'head-inline' | 'page' | 'before-hydration' | 'page-ssr';
@@ -41,7 +17,6 @@ interface VitePluginLike {
     readonly configureServer?: (server: ViteDevServerLike) => void;
     readonly generateBundle?: (this: RollupEmitContext) => void;
 }
-/** The one Rollup facility this needs: publishing a file into the output. */
 interface RollupEmitContext {
     emitFile: (file: {
         type: 'asset';
@@ -49,7 +24,6 @@ interface RollupEmitContext {
         source: string;
     }) => void;
 }
-/** Just enough of Vite's dev server to serve one file. */
 interface ViteDevServerLike {
     readonly middlewares: {
         use: (handler: (req: DevRequest, res: DevResponse, next: () => void) => void) => void;
@@ -85,124 +59,181 @@ interface AstroIntegrationLike {
         readonly 'astro:config:setup': (ctx: AstroConfigSetupContext) => void;
     };
 }
-/**
- * Build the Astro integration. The injected script auto-detects the
- * browser preview context and stays inert on ordinary top-level pages.
- * Browser-context detection does not authorize HTTP response changes.
- */
+/** Build the integration. The injected runtime stays inert outside the admin's preview iframe. */
 declare function livePreview(options?: LivePreviewAstroOptions): AstroIntegrationLike;
 
+/** What a decision publishes for templates on `locals` (Astro, SvelteKit) or `event.context` (Nuxt). */
+
+/** The request-scoped nonce, for templates that nonce their own scripts. */
+declare const NONCE_LOCALS_KEY = "livePreviewNonce";
+/** The verified `AuthorizedPreviewContext`; absent unless `authorizePreview` authorized. */
+declare const AUTHORIZATION_LOCALS_KEY = "livePreviewAuthorization";
+/** The hook's `PreviewAuthorizationOutcome`; absent when no hook ran. */
+declare const AUTHORIZATION_OUTCOME_LOCALS_KEY = "livePreviewAuthorizationOutcome";
+
 /**
- * Helpers for embedding the live preview manually in `.astro` templates.
- *
- * Most consumers should prefer the `livePreview()` integration which
- * auto-injects the script. This module exists for advanced cases where
- * the script needs to live inside a specific layout or behind a
- * conditional.
- *
- * Usage in a `.astro` file:
- *
- * ```astro
- * ---
- * import { renderLivePreviewScript } from 'payload-live-preview/astro';
- * const script = renderLivePreviewScript({
- *   allowedOrigins: ['https://admin.example.com'],
- *   nonce: Astro.locals.livePreviewNonce,
- * });
- * ---
- * <Fragment set:html={script} />
- * ```
- *
- * @module @adapters/astro/component
+ * Manual embedding for `.astro` templates, for the cases the integration's
+ * automatic injection does not fit (one layout, a conditional).
  */
 
 interface RenderScriptOptions extends LivePreviewAstroOptions {
-    /**
-     * CSP nonce to set on the `<script>` tag. Read from
-     * `Astro.locals.livePreviewNonce` after registering the live-preview
-     * middleware.
-     */
+    /** CSP nonce for the tag; read it from `Astro.locals.livePreviewNonce`. */
     readonly nonce?: string;
 }
-/**
- * Render the full `<script>` tag (wrapped with attributes) for embedding
- * in a `.astro` layout. The result is a single string suitable for
- * `set:html={…}`.
- */
+/** The complete `<script>` tag, for `<Fragment set:html={renderLivePreviewScript(...)} />`. */
 declare function renderLivePreviewScript(options?: RenderScriptOptions): string;
 
 /**
- * Server-side preview-intent detection.
- *
- * The live-preview runtime only ever activates inside the Payload
- * admin's iframe, but the *server* still has to decide whether a
- * request expresses preview intent before doing optional preview
- * work. Adapters use this predicate as a delivery optimisation, and
- * consumers with hand-rolled middleware can import it directly.
- *
- * IMPORTANT: every signal inspected here is controlled or triggerable
- * by the client. A positive result is never proof of identity,
- * authentication, or permission to read drafts. Before forwarding
- * credentials, fetching draft data, bypassing caches, changing CSP,
- * or injecting the runtime, verify the request with an application-
- * owned server session or a short-lived signed authorization. Use the
- * same verified decision for all of those effects.
- *
- * Preview intent is present when any of these hold:
- *
- *   1. A preview query parameter is present (`?preview=true`,
- *      `?draft=true`, `?livePreview=true` — configurable).
- *   2. `Sec-Fetch-Dest: iframe` — the document is being loaded as an
- *      iframe, which is exactly how the Payload admin embeds it.
- *      (Sent by all evergreen browsers; absence never *excludes* a
- *      request, presence includes it.)
- *   3. The `Referer` points at one of the given admin origins.
- *
- * @module @adapters/shared/preview-request
+ * The `payload-session` strategy: forward exactly one named cookie to
+ * `GET <serverURL>/api/<usersSlug>/me` and authorize when a user comes back.
  */
-/** The individual signals the predicate can consider. */
-type PreviewSignal = 'query' | 'fetch-dest' | 'referer';
-interface PreviewRequestOptions {
-    /**
-     * Which signals count as preview intent. Default: all three.
-     * Restricting this to `['query']` reduces accidental activation, but
-     * an explicit `?preview=true` is still client-controlled and must not
-     * authorize response changes or privileged data access by itself.
-     */
-    readonly signals?: readonly PreviewSignal[];
-    /**
-     * Query parameters (with values `true` or `1`) that signal preview
-     * intent. Default: `['preview', 'draft', 'livePreview']`.
-     */
-    readonly queryParams?: readonly string[];
-    /**
-     * Treat `Sec-Fetch-Dest: iframe` as a preview-intent signal. Default `true`.
-     * Legacy alias for excluding `'fetch-dest'` from `signals`.
-     */
-    readonly checkFetchDest?: boolean;
-    /**
-     * Admin origins whose `Referer` signals preview intent, e.g.
-     * `['https://cms.example.com']`. Referer matching is not HTTP-request
-     * authentication.
-     */
-    readonly adminOrigins?: readonly string[];
+
+/** A `fetch`-compatible function, injectable for tests. */
+type FetchLike = (input: string, init: {
+    readonly headers: Record<string, string>;
+    readonly signal: AbortSignal;
+}) => Promise<{
+    readonly ok: boolean;
+    readonly status: number;
+    json(): Promise<unknown>;
+}>;
+interface PayloadSessionStrategy {
+    readonly type: 'payload-session';
+    /** Payload server origin, e.g. `https://cms.example.com`. */
+    readonly serverURL: string;
+    /** Auth collection slug; `users` unless the project renamed it. */
+    readonly usersSlug?: string;
+    /** Cookie name; Payload's default is `payload-token`. */
+    readonly cookieName?: string;
+    /** Upper bound for the `/me` round trip. Below 250 ms is raised to 250 ms; default 3000. */
+    readonly timeoutMs?: number;
+    /** Longest cookie value accepted; longer ones are refused as `invalid`. Default 4096. */
+    readonly maxCookieLength?: number;
+    readonly fetch?: FetchLike;
+    /** Clock, Unix milliseconds. Injectable for tests. */
+    readonly now?: () => number;
 }
+
 /**
- * The minimal request surface the predicate needs. The standard
- * `Request` satisfies it structurally, and server frameworks without
- * fetch-style requests (e.g. Nitro/H3) can supply a tiny shim.
+ * The `signed-token` strategy: a short-lived HMAC-SHA256 token minted by the
+ * Payload side and verified by the site. Format and bindings: ADR 0006 §3.
  */
-interface PreviewRequestLike {
-    readonly url: string;
-    readonly headers: {
-        get(name: string): string | null;
+
+/** The subset of Web Crypto the token strategy needs, injectable for environments that expose it elsewhere. */
+interface SubtleCryptoLike {
+    readonly subtle: {
+        importKey(format: 'raw', keyData: Uint8Array, algorithm: {
+            readonly name: 'HMAC';
+            readonly hash: 'SHA-256';
+        }, extractable: false, keyUsages: readonly ('sign' | 'verify')[]): Promise<CryptoKey>;
+        sign(algorithm: 'HMAC', key: CryptoKey, data: Uint8Array): Promise<ArrayBuffer>;
+        verify(algorithm: 'HMAC', key: CryptoKey, signature: Uint8Array, data: Uint8Array): Promise<boolean>;
     };
+    getRandomValues<T extends Uint8Array>(array: T): T;
 }
+/** Where a signed token is read from on the request. */
+type PreviewTokenTransport = {
+    readonly kind: 'query';
+    readonly param?: string;
+} | {
+    readonly kind: 'header';
+    readonly name?: string;
+};
 /**
- * Detect whether `request` carries live-preview intent. See the module
- * docblock for the exact signals and the required authorization
- * boundary. This compatibility name does not imply authentication.
+ * Optional replay store. Not shipped: a per-process memory is useless behind
+ * a load balancer, so the store is a deployment decision.
  */
-declare function isPreviewRequest(request: PreviewRequestLike, options?: PreviewRequestOptions): boolean;
+interface PreviewTokenReplayStore {
+    isUsed(id: string): Promise<boolean> | boolean;
+    markUsed(id: string, expiresAt: number): Promise<void> | void;
+}
+interface SignedTokenStrategy {
+    readonly type: 'signed-token';
+    /** Shared secret, at least 32 bytes; shorter ones are refused on first use. */
+    readonly secret: string | Uint8Array;
+    /** The site origin tokens must name, e.g. `https://www.example.com`. */
+    readonly audience: string;
+    /** Purpose string tokens must carry. Default `live-preview`. */
+    readonly purpose?: string;
+    /** Default: query parameter `previewToken`. */
+    readonly transport?: PreviewTokenTransport;
+    /** Resolve the request's locale for the `loc` binding. Unset: tokens with `loc` are refused as `wrong-locale`. */
+    readonly locale?: (request: PreviewAuthorizationRequest) => string | undefined;
+    readonly replay?: PreviewTokenReplayStore;
+    readonly crypto?: SubtleCryptoLike;
+    readonly now?: () => number;
+}
+
+/**
+ * Authorized preview context: the one verdict every privileged preview
+ * decision is keyed on. Intent (`?preview=true`, an iframe destination, a
+ * referer) is client-chosen; this turns a session, a signed token or the
+ * application's own verifier into a branded context. Threat model: ADR 0006.
+ */
+
+/** Claims a consumer verifier returns for a request it accepts. */
+interface PreviewVerifierClaims {
+    readonly subject?: string;
+    readonly expiresAt?: number;
+    readonly scope?: AuthorizedPreviewScope;
+    readonly payloadHeaders?: Readonly<Record<string, string>>;
+}
+/** The application's own verification: claims authorize, `null` refuses, a throw is `unavailable`. */
+interface VerifierStrategy {
+    readonly type: 'verifier';
+    readonly verify: (request: PreviewAuthorizationRequest) => Promise<PreviewVerifierClaims | null> | PreviewVerifierClaims | null;
+    readonly now?: () => number;
+}
+type PreviewAuthorizationStrategy = PayloadSessionStrategy | SignedTokenStrategy | VerifierStrategy;
+
+/**
+ * The Astro fragment endpoint (ADR 0011): renders a registered component
+ * boundary from unsaved form state for an authorized preview, and nothing
+ * else. The browser names a registry id; the server decides what it renders.
+ */
+
+/** Everything a registry entry may use to compute its props. */
+interface FragmentRenderInput {
+    readonly id: string;
+    readonly key: string | undefined;
+    readonly revision: number;
+    readonly fields: Readonly<Record<string, unknown>>;
+    readonly locale: string | undefined;
+    readonly collectionSlug: string | undefined;
+    readonly globalSlug: string | undefined;
+    readonly route: string;
+    readonly authorization: AuthorizedPreviewContext;
+    readonly request: Request;
+}
+/** An Astro component as `import Hero from './Hero.astro'` yields it. */
+type AstroComponentLike = object;
+interface FragmentRegistryEntry<Props extends Record<string, unknown> = Record<string, unknown>> {
+    readonly component: AstroComponentLike;
+    /** Props for the component, computed from the input; never from request-controlled code. */
+    readonly props: (input: FragmentRenderInput) => Props | Promise<Props>;
+}
+type FragmentRegistry = Readonly<Record<string, FragmentRegistryEntry>>;
+/** Renders a component with props to HTML; the default uses Astro's container API. */
+type FragmentRenderer = (component: AstroComponentLike, props: Record<string, unknown>, input: FragmentRenderInput) => Promise<string>;
+interface FragmentEndpointOptions {
+    /** The only things this endpoint can render. */
+    readonly registry: FragmentRegistry;
+    /** How a preview request is authorized; the same strategies as `authorizePreviewRequest()`. */
+    readonly authorize: PreviewAuthorizationStrategy;
+    /** Override the renderer (tests, other component systems). Default: Astro container. */
+    readonly render?: FragmentRenderer;
+    /** Origins besides the page's own that may call the endpoint. Default: none. */
+    readonly allowedOrigins?: readonly string[];
+    readonly limits?: {
+        /** Largest request body. Default 64 KiB. */
+        readonly bodyBytes?: number;
+        /** Render timeout. Default 5000 ms. */
+        readonly timeoutMs?: number;
+    };
+}
+/** Build the endpoint; export it as the `POST` of a non-prerendered Astro API route. */
+declare function createFragmentEndpoint(options: FragmentEndpointOptions): (context: {
+    readonly request: Request;
+}) => Promise<Response>;
 
-export { type AstroIntegrationLike, LivePreviewAstroOptions, type PreviewRequestLike, type PreviewRequestOptions, type RenderScriptOptions, isPreviewRequest, livePreview, renderLivePreviewScript };
+export { AUTHORIZATION_LOCALS_KEY, AUTHORIZATION_OUTCOME_LOCALS_KEY, type AstroComponentLike, type AstroIntegrationLike, type FragmentEndpointOptions, type FragmentRegistry, type FragmentRegistryEntry, type FragmentRenderInput, type FragmentRenderer, LivePreviewAstroOptions, NONCE_LOCALS_KEY, type RenderScriptOptions, createFragmentEndpoint, livePreview, renderLivePreviewScript };