@avocadostudio-ai/site-sdk 0.1.0 → 0.2.0

package/README.md

@@ -17,8 +17,9 @@ npm install @avocadostudio-ai/site-sdk
 import { createSitePage } from "@avocadostudio-ai/site-sdk/page"
 import { getPage, getSlugs, getSiteConfig } from "../../lib/my-cms"
 
-const { Page, generateStaticParams } = createSitePage({
+const { Page, generateStaticParams, generateMetadata } = createSitePage({
   siteId: "my-site",
+  siteName: "My Site", // optional, used for og:site_name
   getPage,       // (slug: string) => Promise<PageDoc | null>
   getSlugs,      // () => Promise<string[]>
   getSiteConfig, // () => Promise<SiteConfig>  (optional)
@@ -29,9 +30,14 @@ const { Page, generateStaticParams } = createSitePage({
 })
 
 export default Page
-export { generateStaticParams }
+export { generateStaticParams, generateMetadata }
 ```
 
+Export `generateMetadata` too, or every page inherits the root layout's
+`<title>` with no description and no social card. The factory derives all three
+from the page and calls `notFound()` for an unknown slug, so add an
+`app/not-found.tsx` if you want your own chrome around the 404.
+
 ### 3. Create the editor API route
 
 ```tsx
@@ -101,6 +107,208 @@ Your site exposes these endpoints via `createEditorApiHandler`:
 | `/api/editor/pages` | GET | Return all published pages |
 | `/api/editor/publish` | POST | Receive pages from editor, persist to CMS |
 
+## Library mode needs a credential
+
+`createOrchestrator()` mounts on your own domain and can edit and publish your
+content, so it needs to know who is calling. There are three ways to tell it,
+in precedence order.
+
+**1. Reuse the auth your app already has.** The hook receives the `Request` and
+returns a boolean, or an object to attach context:
+
+```ts
+export const { GET, POST, OPTIONS } = createOrchestrator({
+  auth: async (request) => {
+    const session = await getSession(request)   // your own session, your own rules
+    return session?.role === "editor"
+  }
+})
+```
+
+Throwing counts as a refusal, so a hook that awaits a session lookup does not
+have to catch its own errors.
+
+**2. Use the built-in token gate.** Set either variable and it turns on:
+
+```bash
+# a password the editor prompts for; store the SHA-256, never the password
+ACCESS_PASSWORD_HASH=$(printf '%s' 'your-password' | shasum -a 256 | cut -d' ' -f1)
+# and/or a static token for scripts, CI, and MCP clients
+ORCHESTRATOR_ACCESS_TOKEN=…
+```
+
+`POST /auth/verify` exchanges the password for a 12-hour token; every other
+route then requires it as `x-access-token`, `Authorization: Bearer`, or
+`?accessToken=` (the last because `EventSource` cannot send headers). This is
+the same gate the standalone orchestrator enforces, so one editor build talks to
+both.
+
+**3. Neither — and then production is closed.** With no hook and no credential,
+the mount is open in development and **refuses every request** under
+`NODE_ENV=production`. Not a warning: a 401. An unauthenticated publish endpoint
+on a customer's domain is not something anyone should reach by forgetting a step.
+
+To run open in production on purpose, say so in one line — `auth: () => true`.
+
+Two paths stay reachable whatever the gate says, because a caller cannot hold a
+credential yet or at all: `/auth/status` and `/auth/verify` (the exchange that
+produces one), and `GET /generated-images/*` (an `<img>` tag on your rendered
+page cannot attach a header).
+
+### CORS
+
+`corsOrigins` unset means *reflect the caller's origin* in development and *send
+no CORS headers* in production — same-origin works, cross-origin has to be named:
+
+```ts
+createOrchestrator({ corsOrigins: ["https://editor.example.com"] })
+```
+
+Pass `"*"` to reflect deliberately, or `null` to turn the SDK's CORS handling off
+and let Next middleware own it.
+
+## Library mode needs `better-sqlite3`
+
+`createOrchestrator()` keeps draft pages, undo stacks and the version log in
+SQLite, so the app that mounts it must be able to load the driver:
+
+```bash
+npm install better-sqlite3
+```
+
+It is an **optional** peer dependency: a site that only renders published content
+never touches it. Mount the orchestrator without it and every edit still applies
+— to memory alone, lost on the next restart or instance recycle, after which the
+session silently re-seeds from your CMS. `GET /status/planner` reports
+`persistence: { ok: false, reason }` when that is the situation, and every `/ops`
+response carries `persisted: false` with the cause.
+
+A workspace link to `@avocadostudio-ai/orchestrator-core` is **not** enough. A
+linked package's own dependencies are never materialised in the host's tree, and
+a native module has to be resolvable from there.
+
+## Telling the orchestrator where your site is
+
+An agent's only way to see what it just edited is `POST /preview/screenshot`,
+which needs two things a site knows about itself and the orchestrator does not:
+
+```ts
+createOrchestrator({
+  adapter,
+  previewUrl: "http://localhost:3000",  // where this site is reachable
+  draftPath: "/preview-draft"            // the route that renders drafts
+})
+```
+
+`draftPath` is either a prefix the page slug is appended to (`/avocado` →
+`/avocado/de/events`) or a template naming where the slug goes
+(`/preview/{slug}/draft`). It defaults to `/preview-draft`, which is what
+`create-ai-site-editor` scaffolds — **if you wired Avocado into a site you
+already had, set this**, or every draft screenshot comes back a cheerful 200 and
+a picture of your 404 page.
+
+Both can also be set at runtime with `POST /sites/register` (the MCP
+`avocado-register-site` tool), which wins over the values above. `GET /sites`
+reports the one site the process serves either way.
+
+## Publishing back to a real CMS
+
+`onPublish(pages, config)` reads as "here are the pages, store them". That works
+when the CMS shape *is* the editor shape — a JSON file — and not otherwise.
+Every real CMS read is a projection: an asset reference flattened to a URL
+string, a document reference resolved to one language's href, rich text
+flattened to markdown. Writing the projection back replaces the reference with
+the flattening and destroys the document.
+
+So publish a **diff**, not a snapshot. `@ai-site-editor/site-sdk/publish` owns
+the walk:
+
+```ts
+import { diffPage, groupPatches, describeUnsupported } from "@ai-site-editor/site-sdk/publish"
+
+const diff = diffPage({
+  page,
+  ctx: { lang },
+  locate: (block) => {
+    const source = block.props.__source        // what the CMS held when you read it
+    if (!source) return null                   // a block the editor added — reported, not guessed
+    return {
+      documentId: page.id,
+      prefix: `pageBuilder[_key=="${block.id}"].`,
+      source,
+      specs: {
+        heading: { rehydrate: (props) => props.heading },
+        image: {
+          // `before` is the stored value, so an inversion can be partial: keep
+          // the asset reference the projection dropped, replace only the alt.
+          rehydrate: (props, before) => ({ ...before, alt: props.imageAlt }),
+          write: ({ before, after, path, emit, reject }) => {
+            if (before?.alt !== after.alt) emit(`${path}.alt`, after.alt)
+            if (before?.url !== after.url) {
+              reject("the image was replaced", "Upload it as an asset first.")
+            }
+          }
+        }
+      }
+    }
+  }
+})
+
+for (const { documentId, set } of groupPatches(diff.patches)) {
+  await client.patch(documentId).set(set).commit()
+}
+return { ok: true, unsupported: describeUnsupported(diff.unsupported) }
+```
+
+Two things worth knowing before you write one.
+
+**List items match on their own key, not their position.** An index-addressed
+patch lands on the wrong row the moment anything reorders the array upstream.
+`sanityPaths` (the default) addresses `field[_key=="…"]`; `indexPaths` exists for
+stores with no element identity and is only correct when your publish is the
+only writer.
+
+**Refusing is a result, not an error.** Four things a field diff cannot express
+— a replaced image, a retyped link, a list item added or removed, a new block —
+are reported through `unsupported` and returned to the caller. A publisher that
+drops them silently reports success for content the site will never show; one
+that guesses writes a URL where a reference belongs.
+
+If you did not embed your own source snapshot in block props, `onPublish`'s
+third argument carries `context.published` — the pages as your adapter last
+reported them. It is the copy taken at bootstrap, not a fresh read, so it is
+absent after a restart that reloaded the draft from storage. Treat `undefined`
+as "no baseline available", never as "the site was empty": publishing every
+field on that assumption is the overwrite all of this exists to prevent.
+
+## Telling the orchestrator which blocks you render
+
+Importing anything from `@avocadostudio-ai/shared` registers Avocado's 18
+built-in block types, transitively and unavoidably — that is how the block
+library works. A site that brought its own blocks therefore advertises both
+sets, and an agent reading `/blocks/manifest` can add a `Hero` that applies
+cleanly and renders nothing.
+
+If you render Avocado's blocks (a scaffolded site does), skip this. If your site
+brought its own, declare them:
+
+```ts
+export const { GET, POST } = createOrchestrator({
+  adapter,
+  blockTypes: ["acme_hero", "acme_splitSection", "acme_pricing"]
+})
+```
+
+The declaration is exclusive. The manifest narrows to it, the planner is only
+told about those types, and `add_block` refuses anything outside it with a
+message naming what the site does render. Nothing is removed from the registry,
+so stored content of an excluded type keeps validating and rendering — it simply
+is not offered for insertion.
+
+Declaring a type you never registered is not silently dropped: it has no schema
+to describe, so it cannot reach the manifest, and the orchestrator logs a warning
+naming it the first time the manifest is served.
+
 ## Environment Variables
 
 | Variable | Required | Description |
@@ -109,6 +317,8 @@ Your site exposes these endpoints via `createEditorApiHandler`:
 | `DRAFT_MODE_SECRET` | Yes | Secret for enabling Next.js draft mode. Must match editor's `VITE_SITE_DRAFT_SECRET`. |
 | `PUBLISH_TOKEN` | No | If set, publish requests must include this token in `x-publish-token` header. |
 | `EDITOR_CORS_ORIGINS` | No | Comma-separated origins allowed for editor API CORS. Defaults to `http://localhost:4100`. |
+| `ACCESS_PASSWORD_HASH` | No | SHA-256 of the editor password. Turns on the built-in gate; `POST /auth/verify` exchanges the password for a token. |
+| `ORCHESTRATOR_ACCESS_TOKEN` | No | Static token for callers that cannot complete a password exchange (CI, scripts, MCP clients). |
 
 ## Types
 

package/dist/create-site-page.d.ts

@@ -2,6 +2,7 @@ import type { JSX } from "react";
 import type { BlockInstance } from "./types.ts";
 import type { SiteConfig } from "@avocadostudio-ai/shared";
 import type { PageDoc } from "@avocadostudio-ai/shared";
+import { type PageMetadata } from "./page-metadata.ts";
 /**
  * Configuration for creating a site page component.
  *
@@ -18,7 +19,7 @@ import type { PageDoc } from "@avocadostudio-ai/shared";
  * import { createSitePage } from "@avocadostudio-ai/site-sdk/page"
  * import { getPage, getSlugs, getSiteConfig } from "../../lib/my-cms"
  *
- * const { Page, generateStaticParams } = createSitePage({
+ * const { Page, generateStaticParams, generateMetadata } = createSitePage({
  *   siteId: "my-site",
  *   getPage,
  *   getSlugs,
@@ -26,7 +27,7 @@ import type { PageDoc } from "@avocadostudio-ai/shared";
  * })
  *
  * export default Page
- * export { generateStaticParams }
+ * export { generateStaticParams, generateMetadata }
  * ```
  *
  * @example Split-route setup — fully static published path + dynamic preview path
@@ -36,14 +37,15 @@ import type { PageDoc } from "@avocadostudio-ai/shared";
  * export const { middleware, config } = createEditorMiddleware()
  *
  * // app/[[...slug]]/page.tsx (statically generated)
- * const { Page, generateStaticParams } = createSitePage({ mode: "static", ... })
+ * const { Page, generateStaticParams, generateMetadata } = createSitePage({ mode: "static", ... })
  * export default Page
- * export { generateStaticParams }
+ * export { generateStaticParams, generateMetadata }
  *
  * // app/preview-draft/[[...slug]]/page.tsx (dynamic editor route)
  * export const dynamic = "force-dynamic"
- * const { Page } = createSitePage({ mode: "preview", ... })
+ * const { Page, generateMetadata } = createSitePage({ mode: "preview", ... })
  * export default Page
+ * export { generateMetadata }
  * ```
  */
 export type SitePageConfig = {
@@ -63,12 +65,31 @@ export type SitePageConfig = {
     footer?: BlockInstance;
     /** Render site header/footer chrome. Set false when the host layout provides its own. Defaults to true. */
     chrome?: boolean;
+    /**
+     * Site name for `og:site_name`. A plain string rather than a lookup on
+     * `getSiteConfig` deliberately: `generateMetadata` runs as a separate pass
+     * from the render, so reading it from the CMS would double every request's
+     * config fetch to decorate one Open Graph field.
+     */
+    siteName?: string;
+    /**
+     * Last word on a page's metadata. Receives what the SDK derived and the page
+     * it derived it from (`null` when the slug has no page), and returns what to
+     * emit. Use it for canonical URLs, per-section title templates, or anything
+     * that needs host knowledge the SDK does not have.
+     */
+    metadata?: (derived: PageMetadata, page: PageDoc | null) => PageMetadata;
     /**
      * Rendering mode. Defaults to `"auto"`.
      *
-     * - `"auto"`: single-route — handles published and editor modes in one file. Works without middleware.
-     * - `"static"`: published-only — no searchParams, no editor logic, fully static. Pair with `createEditorMiddleware()` and a separate `mode: "preview"` route.
-     * - `"preview"`: editor-only — always reads searchParams + draft content. Set `export const dynamic = "force-dynamic"` on the route file.
+     * - `"auto"`: single-route — handles published and editor modes in one file, and works without middleware or a proxy. **Not statically rendered:** deciding
+     *   between the two modes means reading `searchParams` and draft mode, which
+     *   opts the route into dynamic rendering for every visitor, not just the
+     *   editor. `generateStaticParams` is still returned, and still useless here.
+     *   Convenient for getting started; `"static"` + `"preview"` is what a
+     *   production site wants.
+     * - `"static"`: published-only — no searchParams, no editor logic, genuinely static. Pair with `createEditorProxy()` (Next 16) or `createEditorMiddleware()` (Next 15) and a separate `mode: "preview"` route.
+     * - `"preview"`: editor-only — always reads searchParams + draft content, and always `noindex`. Set `export const dynamic = "force-dynamic"` on the route file.
      */
     mode?: "auto" | "static" | "preview";
 };
@@ -80,6 +101,14 @@ type StaticPageProps = {
 type DynamicPageProps = StaticPageProps & {
     searchParams: Promise<Record<string, string | string[] | undefined>>;
 };
+/**
+ * Next passes `searchParams` to `generateMetadata` for dynamic routes and omits
+ * it for static ones, so the parameter is optional here rather than split
+ * across two signatures.
+ */
+type MetadataProps = StaticPageProps & {
+    searchParams?: Promise<Record<string, string | string[] | undefined>>;
+};
 /**
  * Create a Next.js page component with full editor integration.
  *
@@ -91,5 +120,6 @@ export declare function createSitePage(config: SitePageConfig): {
     generateStaticParams: () => Promise<{
         slug: string[] | undefined;
     }[]>;
+    generateMetadata: ({ params, searchParams }: MetadataProps) => Promise<PageMetadata>;
 };
 export {};

package/dist/create-site-page.js

@@ -1,11 +1,13 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
-import { unstable_noStore as noStore } from "next/cache";
 import { draftMode } from "next/headers";
+import { connection } from "next/server";
+import { notFound } from "next/navigation";
 import { SharedBlockRenderer, BlocksHydrator } from "@avocadostudio-ai/blocks";
 import { buildSlug } from "./index.js";
 import { resolveEditorContext, fetchEditorPage, fetchEditorSlugs } from "./draft.js";
 import { renderBlocks, EditorOverlay } from "./editor.js";
 import { buildNavItems, buildSiteHeaderBlock } from "./navigation.js";
+import { buildPageMetadata } from "./page-metadata.js";
 function resolve(config) {
     return {
         siteId: config.siteId,
@@ -16,6 +18,8 @@ function resolve(config) {
         defaultLogo: config.defaultLogo ?? "/logo.svg",
         footer: config.footer,
         chrome: config.chrome ?? true,
+        siteName: config.siteName,
+        metadata: config.metadata,
     };
 }
 function makeGenerateStaticParams(cmsGetSlugs) {
@@ -32,6 +36,17 @@ async function renderStatic(slug, c) {
         c.cmsGetSlugs(),
         c.cmsGetSiteConfig ? c.cmsGetSiteConfig() : Promise.resolve({}),
     ]);
+    /*
+     * `notFound()`, not a rendered 404 body. The previous version returned an
+     * <h1>404</h1> with HTTP 200, which is a soft 404: crawlers index it as a
+     * real page, and the host app's own `not-found.tsx` never runs. Consumers who
+     * want the site chrome around their 404 get it by adding `app/not-found.tsx`,
+     * which is where Next puts that and where a layout can wrap it.
+     *
+     * Before building the nav, since none of it survives the throw.
+     */
+    if (!page)
+        notFound();
     const { navItems, siteName, siteLogo } = buildNavItems({
         navSlugs,
         currentSlug: slug,
@@ -41,13 +56,48 @@ async function renderStatic(slug, c) {
         defaultLogo: c.defaultLogo,
     });
     const chromeHeader = buildSiteHeaderBlock({ navItems, siteName, siteLogo, activePath: slug });
-    if (!page) {
-        return (_jsxs(_Fragment, { children: [c.chrome && _jsx(SharedBlockRenderer, { block: chromeHeader }), _jsxs("main", { style: { padding: "4rem", textAlign: "center" }, children: [_jsx("h1", { children: "404" }), _jsx("p", { children: "Page not found." })] }), c.chrome && c.footer ? _jsx(SharedBlockRenderer, { block: c.footer }) : null] }));
-    }
     return (_jsxs(_Fragment, { children: [c.chrome && _jsx(SharedBlockRenderer, { block: chromeHeader }), _jsxs("main", { children: [renderBlocks(page.blocks), _jsx(BlocksHydrator, {})] }), c.chrome && c.footer ? _jsx(SharedBlockRenderer, { block: c.footer }) : null] }));
 }
+/**
+ * Metadata for a page, mirroring the render's own choice of source.
+ *
+ * Editor and draft-mode requests get `noindex` and nothing else: a preview URL
+ * that leaks into an index is a bug, and the draft fetch that would produce a
+ * better title belongs to the render pass, not to a second round-trip here.
+ */
+const NOINDEX = { robots: { index: false, follow: false } };
+function makeGenerateMetadata(c, mode) {
+    const decorate = (derived, page) => c.metadata ? c.metadata(derived, page) : derived;
+    return async function generateMetadata({ params, searchParams }) {
+        const { slug: slugParts } = await params;
+        const slug = buildSlug(slugParts);
+        // Every response from a preview route is draft content, by definition.
+        if (mode === "preview")
+            return decorate(NOINDEX, null);
+        if (mode === "auto") {
+            const search = searchParams ? await searchParams : {};
+            const editorCtx = await resolveEditorContext(search, {
+                defaultSession: c.defaultSession,
+                defaultSiteId: c.siteId,
+            });
+            const draft = await draftMode();
+            if (draft.isEnabled || editorCtx)
+                return decorate(NOINDEX, null);
+        }
+        const page = await c.cmsGetPage(slug);
+        if (!page)
+            return decorate({}, null);
+        return decorate(buildPageMetadata(page, { siteName: c.siteName }), page);
+    };
+}
 async function renderPreview(slug, search, c) {
-    noStore();
+    /*
+     * `connection()`, not `unstable_noStore()`. Same effect — this render depends
+     * on a live request and must never be prerendered or cached — but it is the
+     * stable primitive Next ships for saying so, and the SDK had exactly one
+     * `unstable_*` import left in it.
+     */
+    await connection();
     const editorCtx = await resolveEditorContext(search, {
         defaultSession: c.defaultSession,
         defaultSiteId: c.siteId,
@@ -102,13 +152,14 @@ export function createSitePage(config) {
     const c = resolve(config);
     const mode = config.mode ?? "auto";
     const generateStaticParams = makeGenerateStaticParams(c.cmsGetSlugs);
+    const generateMetadata = makeGenerateMetadata(c, mode);
     if (mode === "static") {
         async function Page({ params }) {
             const { slug: slugParts } = await params;
             const slug = buildSlug(slugParts);
             return renderStatic(slug, c);
         }
-        return { Page, generateStaticParams };
+        return { Page, generateStaticParams, generateMetadata };
     }
     if (mode === "preview") {
         async function Page({ params, searchParams }) {
@@ -116,12 +167,12 @@ export function createSitePage(config) {
             const slug = buildSlug(slugParts);
             return renderPreview(slug, search, c);
         }
-        return { Page, generateStaticParams };
+        return { Page, generateStaticParams, generateMetadata };
     }
     async function Page({ params, searchParams }) {
         const [{ slug: slugParts }, search] = await Promise.all([params, searchParams]);
         const slug = buildSlug(slugParts);
         return renderAuto(slug, search, c);
     }
-    return { Page, generateStaticParams };
+    return { Page, generateStaticParams, generateMetadata };
 }

package/dist/draft-common.d.ts

@@ -2,3 +2,35 @@ export declare const DRAFT_SESSION_COOKIE = "editor_draft_session";
 export declare const DRAFT_SITE_COOKIE = "editor_draft_site_id";
 export declare const EDITOR_ORIGIN_COOKIE = "editor_origin";
 export declare function normalizeOrigin(value: string | null | undefined): string | undefined;
+/**
+ * Editor origins this site will talk to.
+ *
+ * `normalizeOrigin` above answers "is this a syntactically valid http(s)
+ * origin", which is a parsing question, not a trust question — every attacker's
+ * origin passes it. The editor origin becomes the `targetOrigin` of the
+ * postMessage bridge and the frame allowed to drive inline edits, so it has to
+ * come from configuration the site's operator controls, not from the URL that
+ * asked for the page.
+ *
+ * Configured via AVOCADO_EDITOR_ORIGINS (comma-separated) and
+ * NEXT_PUBLIC_EDITOR_ORIGIN. Both are read at call time rather than at module
+ * load so a test, or a host that assigns env late, sees the current value.
+ */
+export declare function editorOriginAllowlist(env?: Record<string, string | undefined>, extra?: string): string[];
+/** True for a loopback origin on any port — the shape a local editor takes. */
+export declare function isLoopbackOrigin(origin: string): boolean;
+/**
+ * Decide which editor origin to trust for this request.
+ *
+ * A caller-supplied origin is honoured only when the operator listed it. In
+ * development any loopback origin passes, because the editor's port moves
+ * around and a page served from your own machine is not the threat here.
+ * Anything else falls back to the configured default, so a request carrying a
+ * hostile origin degrades to "no bridge" rather than "bridge to the attacker".
+ */
+export declare function resolveTrustedEditorOrigin(options: {
+    candidate: string | undefined;
+    fallback: string;
+    isDev: boolean;
+    env?: Record<string, string | undefined>;
+}): string;

package/dist/draft-common.js

@@ -15,3 +15,61 @@ export function normalizeOrigin(value) {
         return undefined;
     }
 }
+/**
+ * Editor origins this site will talk to.
+ *
+ * `normalizeOrigin` above answers "is this a syntactically valid http(s)
+ * origin", which is a parsing question, not a trust question — every attacker's
+ * origin passes it. The editor origin becomes the `targetOrigin` of the
+ * postMessage bridge and the frame allowed to drive inline edits, so it has to
+ * come from configuration the site's operator controls, not from the URL that
+ * asked for the page.
+ *
+ * Configured via AVOCADO_EDITOR_ORIGINS (comma-separated) and
+ * NEXT_PUBLIC_EDITOR_ORIGIN. Both are read at call time rather than at module
+ * load so a test, or a host that assigns env late, sees the current value.
+ */
+export function editorOriginAllowlist(env = process.env, extra) {
+    const raw = [
+        ...(env.AVOCADO_EDITOR_ORIGINS ?? "").split(","),
+        ...(env.NEXT_PUBLIC_EDITOR_ORIGIN ?? "").split(","),
+        extra ?? ""
+    ];
+    const out = [];
+    for (const candidate of raw) {
+        const origin = normalizeOrigin(candidate);
+        if (origin && !out.includes(origin))
+            out.push(origin);
+    }
+    return out;
+}
+/** True for a loopback origin on any port — the shape a local editor takes. */
+export function isLoopbackOrigin(origin) {
+    try {
+        const { hostname } = new URL(origin);
+        return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "[::1]" || hostname === "::1";
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Decide which editor origin to trust for this request.
+ *
+ * A caller-supplied origin is honoured only when the operator listed it. In
+ * development any loopback origin passes, because the editor's port moves
+ * around and a page served from your own machine is not the threat here.
+ * Anything else falls back to the configured default, so a request carrying a
+ * hostile origin degrades to "no bridge" rather than "bridge to the attacker".
+ */
+export function resolveTrustedEditorOrigin(options) {
+    const { candidate, fallback, isDev, env } = options;
+    if (!candidate)
+        return fallback;
+    const allowed = editorOriginAllowlist(env ?? process.env, fallback);
+    if (allowed.includes(candidate))
+        return candidate;
+    if (isDev && isLoopbackOrigin(candidate))
+        return candidate;
+    return fallback;
+}

package/dist/draft-context-core.js

@@ -1,10 +1,34 @@
-import { DRAFT_SESSION_COOKIE, DRAFT_SITE_COOKIE, EDITOR_ORIGIN_COOKIE, normalizeOrigin } from "./draft-common.js";
+import { validateDraftSecret } from "@avocadostudio-ai/shared";
+import { DRAFT_SESSION_COOKIE, DRAFT_SITE_COOKIE, EDITOR_ORIGIN_COOKIE, normalizeOrigin, resolveTrustedEditorOrigin } from "./draft-common.js";
 import { single } from "./draft-context.js";
 export { single } from "./draft-context.js";
 export async function resolveDraftContextCore(searchParams, adapter, options) {
     const isDev = process.env.NODE_ENV !== "production";
-    const isEditorParam = single(searchParams.__editor) === "1";
-    const isContentStoreEnabled = isDev || adapter.isDraftMode || isEditorParam;
+    /*
+     * What proves this request may see unpublished content.
+     *
+     * `__editor=1` used to be enough on its own, in production, on the customer's
+     * own domain. It is a routing hint the middleware puts in the URL — no
+     * secret, no cookie — so one GET to a live site rendered another session's
+     * drafts and mounted the editing bridge. The parameter still selects the
+     * preview route; it no longer authorizes anything.
+     *
+     * Two things authorize in production. Draft mode being already enabled means
+     * the secret-gated /api/draft handler was passed and set the cookie. A valid
+     * `secret` on the request itself covers the case that handler cannot: the
+     * editor renders the site in a cross-origin iframe, where the draft cookie is
+     * frequently blocked outright, and a credential in the URL is what remains.
+     *
+     * That credential is a long-lived shared secret travelling in a query string.
+     * It is weaker than a signed, short-lived token and should become one — but
+     * it is the credential this stack already has, it is what /api/draft checks,
+     * and requiring it is the difference between "an attacker needs a secret" and
+     * "an attacker needs a URL".
+     *
+     * Development is unchanged: the parameter alone still works.
+     */
+    const hasValidSecret = validateDraftSecret(single(searchParams.secret), process.env).ok;
+    const isContentStoreEnabled = isDev || adapter.isDraftMode || hasValidSecret;
     if (!isContentStoreEnabled)
         return null;
     const defaultSession = options?.defaultSession ?? process.env.DRAFT_DEFAULT_SESSION?.trim() ?? "dev";
@@ -19,8 +43,17 @@ export async function resolveDraftContextCore(searchParams, adapter, options) {
     if (!siteId)
         return null;
     const session = single(searchParams.session) ?? adapter.getCookie(DRAFT_SESSION_COOKIE)?.trim() ?? defaultSession;
-    const editorOrigin = normalizeOrigin(single(searchParams.editorOrigin))
-        ?? normalizeOrigin(adapter.getCookie(EDITOR_ORIGIN_COOKIE))
-        ?? defaultEditorOrigin;
+    /*
+     * The editor origin becomes the postMessage `targetOrigin` and the frame
+     * permitted to drive inline edits, so it cannot simply be whatever the URL
+     * says. A candidate is honoured only when the operator listed it; anything
+     * else degrades to the configured default.
+     */
+    const candidateOrigin = normalizeOrigin(single(searchParams.editorOrigin)) ?? normalizeOrigin(adapter.getCookie(EDITOR_ORIGIN_COOKIE));
+    const editorOrigin = resolveTrustedEditorOrigin({
+        candidate: candidateOrigin,
+        fallback: defaultEditorOrigin,
+        isDev
+    });
     return { session, siteId, editorOrigin };
 }

package/dist/draft-context-core.test.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Who may see unpublished content, and which frame may drive the editor.
+ *
+ * Both questions used to be answered by the query string. `?__editor=1` alone
+ * turned on the draft content store — in production, on the customer's own
+ * domain — and `editorOrigin` was accepted from the same URL after a check that
+ * only asked whether it parsed as http(s). One GET rendered another session's
+ * drafts and pointed the postMessage bridge wherever the caller said.
+ */
+export {};