@universalcms/connect 0.1.0 → 0.13.1

package/dist/publication.d.mts

@@ -0,0 +1,31 @@
+export type PublicationRoute = Readonly<{ path: string; kind: string; slug: string; locale: string }>;
+export type PublicationConfiguration = Readonly<{
+  version: 1; apiOrigin: string; siteId: string; environmentId: string; websiteOrigin: string;
+  routes: readonly PublicationRoute[];
+}>;
+export type PublicationResult = Readonly<{ state: 'published' | 'missing' | 'unmanaged' | 'unavailable'; status: 200 | 404 | 503 }>;
+export type PublishedDocument = { schemaVersion: 1; title: string; excerpt: string; blocks: Array<{ id: string; type: string; version: 1; text: string; data?: Record<string, unknown>; style?: Record<string, unknown> }>; fields?: Record<string, unknown>; taxonomy?: { categories?: string[]; tags?: string[] } };
+export type PublishedDocumentEntry = Readonly<{ id: string; kind: string; slug: string; locale: string; version: number; revisionId?: string; publishedAt: string; document: PublishedDocument }>;
+export type PublishedDocumentResult = Readonly<{ state: 'published'; status: 200; entry: PublishedDocumentEntry }> | Readonly<{ state: 'missing' | 'unmanaged' | 'unavailable'; status: 200 | 404 | 503; entry?: never }>;
+export type PublicationReaderOptions = {
+  configuration: PublicationConfiguration; env?: Record<string, string | undefined>; fetcher?: typeof fetch;
+  timeoutMs?: number; maxResponseBytes?: number; maxConcurrent?: number;
+};
+export const PUBLICATION_TIMEOUT_MS: 10000;
+export const PUBLICATION_MAX_RESPONSE_BYTES: number;
+export const PUBLICATION_MAX_CONCURRENT: 16;
+export const PUBLICATION_MAX_ROUTES: 1000;
+/** Pathname only. Throws on invalid/ambiguous encodings; normalizes one trailing slash. */
+export function normalizePublicationPath(pathname: string): string;
+/** Native private/system/assets paths remain outside public page ownership. */
+export function isExcludedPublicationPath(pathname: string): boolean;
+export function validatePublicationConfig(value: unknown): PublicationConfiguration;
+/** Throws on invalid paths. Unmanaged, well-formed paths return null. */
+export function resolvePublicationRoute(configuration: PublicationConfiguration, pathname: string): PublicationRoute | null;
+export function createPublicationChecker(options: PublicationReaderOptions): (pathname: string) => Promise<PublicationResult>;
+/** Private server read. Only a validated published response includes an entry. */
+export function createPublishedDocumentReader(options: PublicationReaderOptions): (pathname: string) => Promise<PublishedDocumentResult>;
+export function publicationRevision(entry: Pick<PublishedDocumentEntry, 'id' | 'version' | 'revisionId'>): string;
+/** Removes custom fields, unknown properties and private form destinations. */
+export function publicPublishedEntry(entry: PublishedDocumentEntry): PublishedDocumentEntry;
+export function publicationErrorHtml(status: number): string;

package/dist/publication.mjs

@@ -0,0 +1,320 @@
+/** Server-side availability checks for explicitly reviewed original website routes.
+ * No delivery payload or credential is returned to website/browser adapters.
+ */
+export const PUBLICATION_TIMEOUT_MS = 10_000;
+export const PUBLICATION_MAX_RESPONSE_BYTES = 8 * 1024 * 1024;
+export const PUBLICATION_MAX_CONCURRENT = 16;
+export const PUBLICATION_MAX_ROUTES = 1000;
+
+const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+// The two UUIDs identify the organization and key, not the website/environment.
+const keyPattern = /^cms_server\.[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\.[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\.[A-Za-z0-9_-]{43}$/;
+const slugPattern = /^[a-z0-9]+(?:[-/][a-z0-9]+)*$/;
+const object = value => value !== null && typeof value === 'object' && !Array.isArray(value) && [Object.prototype, null].includes(Object.getPrototypeOf(value));
+const own = (value, key) => Object.hasOwn(value, key);
+const fail = () => { throw new Error('Invalid website publication configuration or request.'); };
+const boundedString = (value, max) => typeof value === 'string' && value.length <= max;
+const integer = (value, min, max) => Number.isSafeInteger(value) && value >= min && value <= max;
+const exactKeys = (value, keys) => object(value) && Object.keys(value).length === keys.length && Object.keys(value).every(key => keys.includes(key));
+const secretPattern = /cms_server\.|sk-[A-Za-z0-9_-]{12,}|AIza[A-Za-z0-9_-]{20,}/i;
+const privateSegments = new Set(['api', 'admin', 'account', 'auth', 'login', 'logout', 'signin', 'signout', 'sign-in', 'sign-out', 'signup', 'sign-up', 'register', 'dashboard', 'profile', 'settings', 'billing', 'checkout', 'cart', 'orders', 'portal', 'patient', 'patients', 'patient-vault', 'vault', 'records', 'medical-records', 'health-records', 'preview', 'draft-preview', 'cms-preview', '_next', '_nuxt', '__vite', 'node_modules', 'src', 'public', 'assets', 'static']);
+// Match the source collector's exclusions, including private compound names.
+// An occurrence inside an ordinary public name such as about-account is not a match.
+const protectedSegment = /^(?:admin|account|dashboard|profile|auth|login|register|checkout|orders|settings|billing|portal|patient|patients|vault|records)(?:-|$)|(?:^|-)vault$|^(?:medical|health)-records(?:-|$)/;
+const privateSegment = value => privateSegments.has(value.toLowerCase()) || protectedSegment.test(value.toLowerCase());
+
+function origin(value) {
+  try {
+    if (!boundedString(value, 2048) || /[\s\\]/.test(value) || secretPattern.test(value)) return fail();
+    const url = new URL(value);
+    if (url.username || url.password || url.search || url.hash || url.pathname !== '/' ||
+      !(url.protocol === 'https:' || url.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname))) return fail();
+    return url.origin;
+  } catch { return fail(); }
+}
+
+function canonicalLocale(value) {
+  try {
+    if (!boundedString(value, 35) || !value) return fail();
+    const locales = Intl.getCanonicalLocales(value);
+    if (locales.length !== 1) return fail();
+    return locales[0];
+  } catch { return fail(); }
+}
+
+/** Accept a pathname, never a URL/query. Reject ambiguous separators before decoding.
+ * One trailing slash and percent-encoded ASCII route characters resolve identically.
+ * Framework adapters must call this before a URL parser can erase dot segments.
+ */
+export function normalizePublicationPath(value) {
+  if (!boundedString(value, 1500) || !value.startsWith('/') || value.startsWith('//') || /[\\\s?#\u0000-\u001f\u007f]/.test(value) || /%(?![0-9a-f]{2})|%(?:2f|5c|2e|25|3f|23|0[0-9a-f]|1[0-9a-f]|7f)/i.test(value)) return fail();
+  let decoded;
+  try { decoded = decodeURIComponent(value); } catch { return fail(); }
+  if (decoded.length > 500 || !/^\/(?:[A-Za-z0-9_.@-]+(?:\/[A-Za-z0-9_.@-]+)*\/?)?$/.test(decoded) || decoded.split('/').some(segment => segment === '.' || segment === '..')) return fail();
+  return decoded.length > 1 && decoded.endsWith('/') ? decoded.slice(0, -1) : decoded;
+}
+
+/** Paths outside public page ownership. Adapters keep their native access policy.
+ * HTML files are not classified as assets: /index.html must use the home gate.
+ */
+export function isExcludedPublicationPath(pathname) {
+  const path = normalizePublicationPath(pathname);
+  return path.split('/').some(segment => privateSegment(segment) || segment.startsWith('.') || segment.startsWith('@')) ||
+    /\.(?:avif|bmp|css|csv|eot|gif|ico|jpe?g|js|json|map|mjs|mp3|mp4|ogg|otf|pdf|png|svg|ttf|txt|wasm|webm|webp|woff2?|xml)$/i.test(path);
+}
+
+/** Strict public configuration. No secret, caller-controlled origin or implicit route inference. */
+export function validatePublicationConfig(value) {
+  try {
+    if (!exactKeys(value, ['version', 'apiOrigin', 'siteId', 'environmentId', 'websiteOrigin', 'routes']) || value.version !== 1 ||
+      typeof value.siteId !== 'string' || !uuid.test(value.siteId) || typeof value.environmentId !== 'string' || !uuid.test(value.environmentId) ||
+      !Array.isArray(value.routes) || !integer(value.routes.length, 1, PUBLICATION_MAX_ROUTES)) return fail();
+    const seen = new Set();
+    const routes = value.routes.map(route => {
+      if (!exactKeys(route, ['path', 'kind', 'slug', 'locale']) || !boundedString(route.path, 500) || !/^\/(?:[A-Za-z0-9_-]+(?:\/[A-Za-z0-9_-]+)*)?$/.test(route.path) || normalizePublicationPath(route.path) !== route.path ||
+        route.path.includes('%') || route.path.split('/').some(privateSegment) ||
+        !boundedString(route.kind, 40) || !/^[a-z][a-z0-9_-]*$/.test(route.kind) ||
+        !boundedString(route.slug, 160) || !slugPattern.test(route.slug) || secretPattern.test(route.path + route.kind + route.slug) || seen.has(route.path)) return fail();
+      seen.add(route.path);
+      return Object.freeze({ path: route.path, kind: route.kind, slug: route.slug, locale: canonicalLocale(route.locale) });
+    });
+    return Object.freeze({ version: 1, apiOrigin: origin(value.apiOrigin), siteId: value.siteId.toLowerCase(), environmentId: value.environmentId.toLowerCase(), websiteOrigin: origin(value.websiteOrigin), routes: Object.freeze(routes) });
+  } catch { return fail(); }
+}
+
+/** Throws on malformed paths, returns null only for a well-formed unmanaged route. */
+export function resolvePublicationRoute(configuration, pathname) {
+  const path = normalizePublicationPath(pathname);
+  return validatePublicationConfig(configuration).routes.find(route => route.path === path) ?? null;
+}
+
+const textTypes = new Set(['paragraph', 'heading', 'quote', 'list', 'code']);
+const leafTypes = new Set([...textTypes, 'image', 'gallery', 'button', 'divider', 'spacer', 'faq', 'table', 'embed', 'form']);
+const styleValues = {
+  align: ['left', 'center', 'right'], size: ['small', 'normal', 'large'], tone: ['default', 'muted', 'accent', 'inverse'],
+  spaceAbove: ['none', 'small', 'medium', 'large'], spaceBelow: ['none', 'small', 'medium', 'large'],
+};
+const optionalEnum = (value, key, choices) => !own(value, key) || choices.includes(value[key]);
+const optionalString = (value, key, max) => !own(value, key) || boundedString(value[key], max);
+const optionalBoolean = (value, key) => !own(value, key) || typeof value[key] === 'boolean';
+const optionalInteger = (value, key, min, max) => !own(value, key) || integer(value[key], min, max);
+function publicUrl(value, { internal = false, secure = false } = {}) {
+  if (!boundedString(value, 2048) || /[\\\u0000-\u001f\u007f]/.test(value)) return false;
+  if (internal && value.startsWith('/') && !value.startsWith('//')) return true;
+  try { const url = new URL(value); return !url.username && !url.password && (secure ? url.protocol === 'https:' : ['https:', 'http:'].includes(url.protocol)); }
+  catch { return false; }
+}
+function imageData(value) {
+  return object(value) && publicUrl(value.url) && boundedString(value.alt, 300) && optionalInteger(value, 'width', 1, 20000) && optionalInteger(value, 'height', 1, 20000) &&
+    (!own(value, 'srcset') || boundedString(value.srcset, 4000) && value.srcset.split(',').every(candidate => {
+      const [url, width, ...rest] = candidate.trim().split(/\s+/); return !rest.length && publicUrl(url) && /^[1-9]\d{0,4}w$/.test(width ?? '');
+    }));
+}
+function leafData(block) {
+  const d = block.data;
+  if (textTypes.has(block.type)) return block.type !== 'heading' || d === undefined || object(d) && [2, 3, 4].includes(d.level);
+  if (block.type === 'divider') return d === undefined || object(d);
+  if (!object(d)) return false;
+  switch (block.type) {
+    case 'image': return imageData(d) && optionalEnum(d, 'align', ['left', 'center', 'right', 'full']) && (!own(d, 'link') || publicUrl(d.link, { internal: true }));
+    case 'gallery': return Array.isArray(d.images) && integer(d.images.length, 1, 30) && d.images.every(image => imageData(image) && uuid.test(image.id)) && optionalEnum(d, 'columns', [2, 3, 4]);
+    case 'button': return publicUrl(d.url, { internal: true }) && optionalEnum(d, 'style', ['primary', 'secondary', 'link']) && optionalEnum(d, 'align', ['left', 'center', 'right']) && optionalBoolean(d, 'newTab');
+    case 'spacer': return optionalInteger(d, 'height', 8, 400);
+    case 'faq': return Array.isArray(d.items) && integer(d.items.length, 1, 50) && d.items.every(item => object(item) && uuid.test(item.id) && boundedString(item.question, 500) && boundedString(item.answer, 5000));
+    case 'table': return optionalBoolean(d, 'header') && Array.isArray(d.rows) && integer(d.rows.length, 1, 100) && d.rows.every(row => Array.isArray(row) && integer(row.length, 1, 12) && row.length === d.rows[0].length && row.every(cell => boundedString(cell, 2000)));
+    case 'embed': return publicUrl(d.url, { secure: true }) && optionalEnum(d, 'provider', ['youtube', 'vimeo', 'iframe']) && optionalEnum(d, 'aspect', ['16:9', '4:3', '1:1']);
+    case 'form': return boundedString(d.formKey, 60) && /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(d.formKey) &&
+      Array.isArray(d.fields) && integer(d.fields.length, 1, 20) && new Set(d.fields.map(field => field?.name)).size === d.fields.length &&
+      d.fields.every(field => object(field) && uuid.test(field.id) && boundedString(field.name, 40) && /^[a-z][a-z0-9_]*$/.test(field.name) && boundedString(field.label, 120) && ['text', 'email', 'phone', 'textarea', 'select', 'checkbox'].includes(field.type) && optionalBoolean(field, 'required') && optionalString(field, 'placeholder', 120) && (!own(field, 'options') || Array.isArray(field.options) && field.options.length <= 30 && field.options.every(option => boundedString(option, 80)))) &&
+      optionalString(d, 'submitLabel', 60) && optionalString(d, 'successMessage', 500) && optionalString(d, 'consentText', 300) && optionalString(d, 'notifyEmail', 200) && optionalBoolean(d, 'subscribe');
+    default: return false;
+  }
+}
+/** Validate the version-1 document without rendering it or exposing its fields.
+ * Validation is deliberately local to the integration; API authorization remains authoritative.
+ */
+function validDocument(document) {
+  if (!object(document) || document.schemaVersion !== 1 || !boundedString(document.title, 200) || !document.title.trim() ||
+    !boundedString(document.excerpt, 1000) || !Array.isArray(document.blocks) || document.blocks.length > 200) return false;
+  const ids = new Set();
+  function blocks(values, level, max) {
+    if (!Array.isArray(values) || values.length > max) return false;
+    return values.every(block => {
+      if (!object(block) || !uuid.test(block.id) || ids.has(block.id) || ids.size >= 400 || block.version !== 1 || !boundedString(block.text, 30000)) return false;
+      ids.add(block.id);
+      if (block.style !== undefined && (!object(block.style) || Object.entries(styleValues).some(([key, values]) => !optionalEnum(block.style, key, values)) ||
+        !optionalBoolean(block.style, 'hideOnMobile') || !optionalBoolean(block.style, 'hideOnDesktop') ||
+        own(block.style, 'anchor') && (!boundedString(block.style.anchor, 80) || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(block.style.anchor)))) return false;
+      if (leafTypes.has(block.type)) return leafData(block);
+      const d = block.data;
+      if (!object(d)) return false;
+      if (block.type === 'section' && level === 0) return optionalEnum(d, 'background', ['none', 'muted', 'accent', 'dark']) && optionalEnum(d, 'padding', ['none', 'small', 'medium', 'large']) && optionalEnum(d, 'width', ['normal', 'wide', 'full']) && blocks(d.blocks, 1, 100);
+      if (block.type === 'columns' && level < 2) return optionalEnum(d, 'layout', ['1-1', '1-2', '2-1', '1-1-1', '1-1-1-1']) && optionalEnum(d, 'gap', ['small', 'medium', 'large']) && optionalBoolean(d, 'stackOnMobile') &&
+        Array.isArray(d.columns) && d.columns.length === (d.layout ?? '1-1').split('-').length && d.columns.every(column => blocks(column, 2, 50));
+      return false;
+    });
+  }
+  if (!blocks(document.blocks, 0, 200)) return false;
+  if (own(document, 'fields') && (!object(document.fields) || Object.keys(document.fields).length > 60 || Object.keys(document.fields).some(key => key.length > 40))) return false;
+  if (own(document, 'taxonomy')) {
+    if (!object(document.taxonomy)) return false;
+    for (const [key, max] of [['categories', 20], ['tags', 50]]) {
+      const values = document.taxonomy[key] ?? [];
+      if (!Array.isArray(values) || values.length > max || new Set(values).size !== values.length || values.some(value => !boundedString(value, 80) || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(value))) return false;
+    }
+  }
+  return true;
+}
+
+function publicationEntry(raw, route, config) {
+  const envelope = JSON.parse(raw), data = envelope?.data;
+  if (!object(envelope) || !object(data) || own(envelope, 'preview') || own(data, 'preview') || !Array.isArray(data.items) || !integer(data.total, 0, 1) || data.items.length !== data.total) return fail();
+  if (data.total === 0) return null;
+  const entry = data.items[0];
+  if (!object(entry) || !uuid.test(entry.id) || entry.kind !== route.kind || entry.slug !== route.slug || canonicalLocale(entry.locale) !== route.locale ||
+    !integer(entry.version, 0, Number.MAX_SAFE_INTEGER) || !boundedString(entry.publishedAt, 64) || !Number.isFinite(Date.parse(entry.publishedAt)) ||
+    own(entry, 'preview') || own(entry, 'status') && entry.status !== 'published' || own(entry, 'revisionId') && !uuid.test(entry.revisionId) ||
+    own(entry, 'siteId') && entry.siteId !== config.siteId || own(entry, 'environmentId') && entry.environmentId !== config.environmentId || !validDocument(entry.document)) return fail();
+  // Keep the private reader contract independent of delivery metadata and never
+  // reflect unknown envelope/entry properties into a website response.
+  return Object.freeze({ id: entry.id, kind: entry.kind, slug: entry.slug, locale: canonicalLocale(entry.locale), version: entry.version,
+    ...(entry.revisionId ? { revisionId: entry.revisionId } : {}), publishedAt: entry.publishedAt, document: entry.document });
+}
+
+/** Public opaque identity of the immutable publication, never the mutable draft. */
+export function publicationRevision(entry) {
+  if (!object(entry) || !uuid.test(entry.id) || !integer(entry.version, 0, Number.MAX_SAFE_INTEGER) || own(entry, 'revisionId') && !uuid.test(entry.revisionId)) return fail();
+  return `${entry.id}:${entry.version}${entry.revisionId ? `:${entry.revisionId}` : ''}`;
+}
+
+const pick = (value, keys) => Object.fromEntries(keys.filter(key => own(value, key)).map(key => [key, value[key]]));
+const dataKeys = {
+  heading: ['level'], image: ['url', 'alt', 'width', 'height', 'srcset', 'align', 'link'], gallery: ['columns'],
+  button: ['url', 'style', 'align', 'newTab'], spacer: ['height'], faq: [], table: ['header', 'rows'], embed: ['url', 'provider', 'aspect'],
+  form: ['formKey', 'submitLabel', 'successMessage', 'consentText'], section: ['background', 'padding', 'width'], columns: ['layout', 'gap', 'stackOnMobile'],
+};
+function publicBlock(block) {
+  const result = pick(block, ['id', 'type', 'version', 'text']);
+  if (object(block.style)) result.style = pick(block.style, [...Object.keys(styleValues), 'hideOnMobile', 'hideOnDesktop', 'anchor']);
+  if (object(block.data)) {
+    const data = pick(block.data, dataKeys[block.type] ?? []);
+    if (block.type === 'gallery') data.images = block.data.images.map(image => pick(image, ['id', 'url', 'alt', 'width', 'height', 'srcset']));
+    if (block.type === 'faq') data.items = block.data.items.map(item => pick(item, ['id', 'question', 'answer']));
+    if (block.type === 'form') data.fields = block.data.fields.map(field => pick(field, ['id', 'name', 'label', 'type', 'required', 'placeholder', 'options']));
+    if (block.type === 'section') data.blocks = block.data.blocks.map(publicBlock);
+    if (block.type === 'columns') data.columns = block.data.columns.map(column => column.map(publicBlock));
+    result.data = data;
+  }
+  return result;
+}
+
+/** Browser projection contains renderer fields only, never custom fields or form destinations. */
+export function publicPublishedEntry(entry) {
+  publicationRevision(entry);
+  if (!validDocument(entry.document)) return fail();
+  const document = { schemaVersion: 1, title: entry.document.title, excerpt: entry.document.excerpt, blocks: entry.document.blocks.map(publicBlock) };
+  if (entry.document.taxonomy) document.taxonomy = pick(entry.document.taxonomy, ['categories', 'tags']);
+  return { ...pick(entry, ['id', 'kind', 'slug', 'locale', 'version', 'revisionId', 'publishedAt']), document };
+}
+
+function untilAborted(pending, signal) {
+  return new Promise((resolve, reject) => {
+    const cancel = () => reject(new Error('Publication check unavailable.'));
+    signal.addEventListener('abort', cancel, { once: true });
+    if (signal.aborted) cancel();
+    Promise.resolve(pending).then(value => { signal.removeEventListener('abort', cancel); resolve(value); }, error => { signal.removeEventListener('abort', cancel); reject(error); });
+  });
+}
+function cancelBody(response) {
+  try { if (response?.body && !response.body.locked) void response.body.cancel().catch(() => {}); } catch { /* Safe cleanup only. */ }
+}
+async function boundedBody(response, limit, signal, deadline) {
+  const declared = response.headers.get('content-length');
+  if (declared !== null && (!/^\d+$/.test(declared) || Number(declared) > limit) || !response.body) return fail();
+  const reader = response.body.getReader(), decoder = new TextDecoder('utf-8', { fatal: true });
+  let bytes = 0, text = '';
+  try {
+    for (;;) {
+      const chunk = await untilAborted(reader.read(), signal);
+      if (Date.now() >= deadline || signal.aborted) return fail();
+      if (chunk.done) break;
+      if (!(chunk.value instanceof Uint8Array) || (bytes += chunk.value.byteLength) > limit) return fail();
+      text += decoder.decode(chunk.value, { stream: true });
+    }
+    return text + decoder.decode();
+  } finally {
+    void reader.cancel().catch(() => {});
+    reader.releaseLock();
+  }
+}
+const outcome = (state, reason) => {
+  const result = { state, status: state === 'missing' ? 404 : state === 'unavailable' ? 503 : 200 };
+  if (reason) Object.defineProperty(result, 'reason', { value: reason, enumerable: false, configurable: true });
+  return Object.freeze(result);
+};
+
+/** Create once per server runtime. Every managed request rechecks publication;
+ * no cross-request response cache, retry, visitor credentials or arbitrary URL.
+ */
+export function createPublishedDocumentReader({ configuration, env = process.env, fetcher = globalThis.fetch, timeoutMs = PUBLICATION_TIMEOUT_MS, maxResponseBytes = PUBLICATION_MAX_RESPONSE_BYTES, maxConcurrent = PUBLICATION_MAX_CONCURRENT } = {}) {
+  if (typeof window !== 'undefined') throw new Error('Website publication checks require a private server runtime.');
+  const config = validatePublicationConfig(configuration);
+  if (typeof fetcher !== 'function' || !integer(timeoutMs, 1, PUBLICATION_TIMEOUT_MS) || !integer(maxResponseBytes, 1, PUBLICATION_MAX_RESPONSE_BYTES) || !integer(maxConcurrent, 1, PUBLICATION_MAX_CONCURRENT)) return fail();
+  const routes = new Map(config.routes.map(route => [route.path, route]));
+  let active = 0;
+  return async function check(pathname) {
+    let route, apiOrigin, key;
+    try {
+      if (typeof window !== 'undefined') return outcome('unavailable');
+      route = routes.get(normalizePublicationPath(pathname));
+      if (!route) return outcome('unmanaged');
+      if (!env || typeof env !== 'object' || Array.isArray(env) || typeof (key = env.CMS_API_KEY) !== 'string' || !keyPattern.test(key) ||
+        env.CMS_SITE_ID !== undefined && String(env.CMS_SITE_ID).toLowerCase() !== config.siteId ||
+        env.CMS_ENVIRONMENT_ID !== undefined && String(env.CMS_ENVIRONMENT_ID).toLowerCase() !== config.environmentId ||
+        env.CMS_WEBSITE_ORIGIN !== undefined && origin(env.CMS_WEBSITE_ORIGIN) !== config.websiteOrigin || active >= maxConcurrent) {
+        if (!key || typeof key !== 'string' || !keyPattern.test(key)) {
+          console.warn('[UniversalCMS] Publication delivery check failed: CMS_API_KEY is missing or invalid in private environment.');
+          return outcome('unavailable', 'missing_or_invalid_key');
+        }
+        return outcome('unavailable');
+      }
+      apiOrigin = env.CMS_API_BASE_URL === undefined ? config.apiOrigin : origin(env.CMS_API_BASE_URL);
+    } catch { return outcome('unavailable'); }
+    const url = new URL(`/api/v1/delivery/sites/${config.siteId}/content`, apiOrigin);
+    url.search = new URLSearchParams({ environmentId: config.environmentId, kind: route.kind, slug: route.slug, locale: route.locale, limit: '2' }).toString();
+    const controller = new AbortController(), deadline = Date.now() + timeoutMs;
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    let response;
+    active++;
+    try {
+      const pending = Promise.resolve(fetcher(url, {
+        method: 'GET', headers: { Authorization: `Bearer ${key}`, Accept: 'application/json' },
+        credentials: 'omit', redirect: 'error', cache: 'no-store', referrerPolicy: 'no-referrer', signal: controller.signal,
+      })).then(value => { if (controller.signal.aborted) cancelBody(value); return value; });
+      response = await untilAborted(pending, controller.signal);
+      if (response && [401, 403].includes(response.status)) {
+        console.warn(`[UniversalCMS] Delivery API rejected CMS_API_KEY (HTTP ${response.status} Unauthorized) for site ${config.siteId} and environment ${config.environmentId}. Verify private server key in .env.local.`);
+        return outcome('unavailable', 'unauthorized');
+      }
+      if (controller.signal.aborted || Date.now() >= deadline || !(response instanceof Response) || response.status !== 200 || response.redirected ||
+        ['opaque', 'opaqueredirect'].includes(response.type) || response.url && response.url !== url.href ||
+        response.headers.get('content-type')?.split(';')[0]?.trim().toLowerCase() !== 'application/json') return outcome('unavailable');
+      const entry = publicationEntry(await boundedBody(response, maxResponseBytes, controller.signal, deadline), route, config);
+      if (controller.signal.aborted || Date.now() >= deadline) return outcome('unavailable');
+      return entry ? Object.freeze({ ...outcome('published'), entry }) : outcome('missing');
+    } catch { return outcome('unavailable'); }
+    finally { active--; clearTimeout(timer); controller.abort(); cancelBody(response); }
+  };
+}
+
+/** Availability-only compatibility API. Content never escapes through this result. */
+export function createPublicationChecker(options) {
+  const read = createPublishedDocumentReader(options);
+  return async pathname => outcome((await read(pathname)).state);
+}
+
+/** Constant HTML only: no website, API, route, body or exception text is reflected. */
+export function publicationErrorHtml(status) {
+  const missing = status === 404;
+  return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><meta name="robots" content="noindex,nofollow"><title>${missing ? '404 — Page not found' : 'Content temporarily unavailable'}</title></head><body><main><h1>${missing ? '404' : 'Content temporarily unavailable'}</h1><p>${missing ? 'Page not found.' : 'Please try again later.'}</p></main></body></html>`;
+}

package/dist/react-publication.d.mts

@@ -0,0 +1,22 @@
+import type { ReactNode } from 'react';
+import type { PublishedDocument, PublishedDocumentEntry } from './publication.mjs';
+export type Inventory = { publicSource?: 1; fingerprints?: { title: string; excerpt: string; blocks: Record<string,string> };
+  identity: { kind: string; slug: string; locale: string };
+  baseline: PublishedDocument;
+  titleBlockId?: string;
+  excerptBlockId?: string;
+  bindings: Record<string, { variants: { values: Array<string | number | boolean | null>; id: string }[] }>;
+};
+export function PublishedDocumentProvider(props: { initialEntry?: PublishedDocumentEntry; pathname: string; route: Inventory; children: ReactNode; formEndpoint?: string }): ReactNode;
+/** Internal composition boundary: website settings supply head metadata. */
+export function PublicationMetadataOwner(props: { children: ReactNode }): ReactNode;
+export function CmsBound(props: { slot: string; selector: Array<string | number | boolean | null>; children: ReactNode }): ReactNode;
+/** includeUnbound also renders baseline blocks that have no native binding. */
+export function CmsAdditionalContent(props?: { includeUnbound?: boolean }): ReactNode;
+/** Render all current published blocks with the shared safe block/form policy. */
+export function CmsPublishedDocument(): ReactNode;
+/** The current validated public snapshot for reviewed native component mappings. */
+export function usePublishedDocument(): { entry: PublishedDocumentEntry; route: Inventory; blocks: ReadonlyMap<string, PublishedDocument['blocks'][number]> };
+/** Search current published labels while keeping native row IDs and handlers. */
+export function useCmsSearchText(): (selector: Array<string | number | boolean | null>) => string;
+export function validateEntry(value: unknown, identity: { kind: string; slug: string; locale: string }): PublishedDocumentEntry;