@avocadostudio-ai/site-sdk 0.1.0 → 0.2.1

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/cli/register.js

@@ -67,6 +67,10 @@ function parseArgs(argv) {
             case "--preview-url":
                 out.previewUrl = next();
                 break;
+            case "--token":
+            case "--access-token":
+                out.token = next();
+                break;
             case "-h":
             case "--help":
                 out.help = true;
@@ -98,6 +102,9 @@ OPTIONAL
   --session <string>        Orchestrator session (default: dev)
   --purpose <string>        One-line site description for AI context
   --preview-url <url>       Preview URL (default: http://localhost:<port>)
+  --token <string>          Orchestrator access token (default: $ORCHESTRATOR_ACCESS_TOKEN).
+                            Required by any orchestrator that is credentialed —
+                            which a library-mode mount must be in production.
   --cwd <path>              Project directory (default: current working directory)
   -h, --help                Show this help
 
@@ -218,6 +225,13 @@ async function main() {
     const port = args.port ?? detectPortFromPackageJson(pkg) ?? 3000;
     // Resolve orchestrator URL
     const orchestrator = (args.orchestrator ?? process.env.ORCHESTRATOR_URL ?? "http://localhost:4200").replace(/\/+$/, "");
+    /*
+     * A credentialed orchestrator refuses `/sites/register` like any other route,
+     * and this CLI had no way to present a token — so the documented path for
+     * "wire up your site with your own coding agent" ended at a 401 for exactly
+     * the deployments the docs insist on securing.
+     */
+    const accessToken = (args.token ?? process.env.ORCHESTRATOR_ACCESS_TOKEN ?? "").trim();
     // Resolve / generate the draft secret
     const envPath = join(cwd, ".env.local");
     const existingEnv = existsSync(envPath) ? parseEnvFile(readFileSync(envPath, "utf-8")) : {};
@@ -246,7 +260,10 @@ async function main() {
     try {
         response = await fetch(`${orchestrator}/sites/register`, {
             method: "POST",
-            headers: { "content-type": "application/json" },
+            headers: {
+                "content-type": "application/json",
+                ...(accessToken ? { "x-access-token": accessToken } : {}),
+            },
             body: JSON.stringify({
                 siteId,
                 name,
@@ -272,6 +289,11 @@ async function main() {
     if (!response.ok) {
         const text = await response.text();
         process.stderr.write(`\nOrchestrator responded ${response.status}:\n  ${text}\n`);
+        if (response.status === 401 || response.status === 403) {
+            process.stderr.write(accessToken
+                ? `\nA token was sent and rejected. Check it matches ORCHESTRATOR_ACCESS_TOKEN\non the orchestrator, or the password behind ACCESS_PASSWORD_HASH.\n`
+                : `\nThis orchestrator is credentialed and no token was sent.\nPass --token <value>, or set ORCHESTRATOR_ACCESS_TOKEN.\n`);
+        }
         process.exit(1);
     }
     const result = (await response.json());

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;
+}