@jini-ai/cms 0.5.5 → 0.5.7

package/dist/consent/html/render.d.ts

@@ -0,0 +1,27 @@
+import { type ConsentConfig, type ConsentRecord, type ConsentRegionMode } from '../types.js';
+/** Refuse executable/data/protocol-relative privacy links; local pages are the common case.
+ * @complexity O(url length). */
+export declare function consentPolicyHref({ url }: {
+    url: string;
+}, _options?: {}): string | null;
+/** Render one accessible progressive form. Config text is always text, never trusted HTML.
+ * Necessary cookies/default rejection work without JS. @complexity O(config text length). */
+export declare function renderConsentUi({ config, record, regionMode, gpc, endpoint }: {
+    config: ConsentConfig;
+    record: ConsentRecord | null;
+    regionMode: ConsentRegionMode;
+    gpc: boolean;
+    endpoint: string;
+}, _options?: {}): string;
+/** Bootstrap must be inserted before every site script; JSON cannot terminate its script element.
+ * @complexity O(config text length). */
+export declare function renderConsentHead({ record, gpc, regionMode }: {
+    record: ConsentRecord | null;
+    gpc: boolean;
+    regionMode?: ConsentRegionMode;
+}, { nonce, runtimeToken, resourceOrigins }?: {
+    nonce?: string;
+    runtimeToken?: string;
+    resourceOrigins?: readonly string[];
+}): string;
+//# sourceMappingURL=render.d.ts.map

package/dist/consent/html/render.js

@@ -0,0 +1,62 @@
+import { escapeHtml } from '@jini-ai/core/text';
+import { DENIED_CHOICES } from '../types.js';
+import { googleConsentSignals, resolveConsentChoices } from '../policy.js';
+import { CONSENT_CLIENT } from './client.js';
+import { CONSENT_CSS } from './styles.js';
+/** Refuse executable/data/protocol-relative privacy links; local pages are the common case.
+ * @complexity O(url length). */
+export function consentPolicyHref({ url }, _options = {}) {
+    if (/^\/(?!\/)/.test(url) && !/[\\\x00-\x20]/.test(url))
+        return url;
+    try {
+        const parsed = new URL(url);
+        return parsed.protocol === 'https:' && !parsed.username && !parsed.password ? parsed.href : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Render one accessible progressive form. Config text is always text, never trusted HTML.
+ * Necessary cookies/default rejection work without JS. @complexity O(config text length). */
+export function renderConsentUi({ config, record, regionMode, gpc, endpoint }, _options = {}) {
+    const e = (text) => escapeHtml({ text });
+    const choices = resolveConsentChoices({ choices: record?.choices, gpc, regionMode });
+    const href = consentPolicyHref({ url: config.privacyPolicyUrl });
+    const categories = ['necessary', 'functional', 'analytics', 'marketing'].map(category => {
+        const locked = category === 'necessary' || (gpc && (category === 'analytics' || category === 'marketing'));
+        return `<label class="jini-consent-category"><input type="checkbox" name="${category}"${choices[category] ? ' checked' : ''}${locked ? ' disabled' : ''}>${category[0].toUpperCase() + category.slice(1)}${category === 'necessary' ? ' (always on)' : ''}</label>`;
+    }).join('');
+    return `<section id="jini-consent" class="jini-consent" data-has-record="${record !== null}" aria-label="Cookie preferences">
+<div class="jini-consent-initial"><h2>${e(config.title)}</h2><p>${e(config.message)}</p>
+<p>${regionMode === 'opt-out' ? 'You may opt out of optional cookies at any time.' : 'Optional cookies and scripts stay paused until you agree.'}</p></div>
+${href ? `<a href="${e(href)}">Privacy policy</a> · ` : ''}<a href="#jini-consent-preferences" data-jini-do-not-sell>Do Not Sell or Share</a>
+<p data-jini-gpc-note${gpc ? '' : ' hidden'}>Global Privacy Control is on. Analytics and marketing are disabled.</p>
+<form method="post" action="${e(endpoint)}"><input type="hidden" name="policyVersion" value="${e(config.policyVersion)}"><input type="hidden" name="gpc" value="${gpc ? '1' : '0'}">
+<p role="alert" data-jini-consent-error hidden></p>
+<div class="jini-consent-actions jini-consent-initial"><button name="action" value="reject">${e(config.rejectLabel)}</button><button name="action" value="accept">${e(config.acceptLabel)}</button></div>
+<button id="jini-consent-do-not-sell" name="action" value="do-not-sell" data-jini-do-not-sell-button>Do Not Sell or Share</button>
+<details id="jini-consent-preferences"><summary>${e(config.preferencesLabel)}</summary><fieldset><legend>Cookie categories</legend>${categories}</fieldset>
+<div class="jini-consent-actions"><button name="action" value="save">Save preferences</button><button name="action" value="reject">${e(config.rejectLabel)}</button></div></details></form></section>`;
+}
+/** Bootstrap must be inserted before every site script; JSON cannot terminate its script element.
+ * @complexity O(config text length). */
+export function renderConsentHead({ record, gpc, regionMode = 'opt-in' }, { nonce, runtimeToken, resourceOrigins = [] } = {}) {
+    const choices = resolveConsentChoices({ choices: record?.choices, gpc, regionMode });
+    const gpcChoices = resolveConsentChoices({ choices: record?.choices, gpc: true, regionMode });
+    // Origins are a host contract, never extracted from authored resource URLs.
+    const origins = resourceOrigins.map(value => {
+        const url = new URL(value);
+        if (!['http:', 'https:'].includes(url.protocol) || url.origin !== value)
+            throw new Error('Consent resource origins must be HTTP(S) origins.');
+        return url.origin;
+    });
+    const sources = ["'self'", ...origins].join(' ');
+    const preConsentPolicy = `style-src ${sources} 'unsafe-inline'; font-src ${sources} data:; img-src ${sources} data: blob:; media-src ${sources}; frame-src ${sources}; connect-src ${sources}`;
+    const state = JSON.stringify({ resourcePolicy: preConsentPolicy, choices, gpcChoices, signals: googleConsentSignals({ choices }), gpcSignals: googleConsentSignals({ choices: gpcChoices }), deniedSignals: googleConsentSignals({ choices: DENIED_CHOICES }), hasRecord: record !== null, optOut: regionMode === 'opt-out', gpc }).replace(/</g, '\\u003c');
+    // A local stylesheet can import remote CSS/fonts that HTML traversal cannot see.
+    // Each choice reloads, so restrictive policy can be removed only after a saved grant.
+    const resourcePolicy = choices.marketing ? '' : `<meta http-equiv="Content-Security-Policy" content="${escapeHtml({ text: preConsentPolicy })}">`;
+    const nonceAttr = nonce === undefined ? '' : ` nonce="${escapeHtml({ text: nonce })}"`;
+    return `${resourcePolicy}<style data-jini-consent-style${nonceAttr}>${CONSENT_CSS}</style><script type="application/json" id="jini-consent-config"${nonceAttr}>${state}</script><script data-jini-consent-runtime="${escapeHtml({ text: runtimeToken ?? '' })}"${nonceAttr}>${CONSENT_CLIENT}</script>`;
+}
+//# sourceMappingURL=render.js.map

package/dist/consent/html/static.d.ts

@@ -0,0 +1,7 @@
+/** Static exports keep optional content inert, without forms posting to a nonexistent server.
+ * The same parse5 owner supplies source locations; no competing HTML parsing lifecycle.
+ * @complexity O(n + s log s) time/O(n) space for n bytes and s removed runtime elements. */
+export declare function stripConsentRuntime({ html }: {
+    html: string;
+}, _options?: {}): string;
+//# sourceMappingURL=static.d.ts.map

package/dist/consent/html/static.js

@@ -0,0 +1,25 @@
+import { parse } from 'parse5';
+/** Static exports keep optional content inert, without forms posting to a nonexistent server.
+ * The same parse5 owner supplies source locations; no competing HTML parsing lifecycle.
+ * @complexity O(n + s log s) time/O(n) space for n bytes and s removed runtime elements. */
+export function stripConsentRuntime({ html }, _options = {}) {
+    const stack = [...parse(html, { sourceCodeLocationInfo: true, scriptingEnabled: false }).childNodes];
+    const edits = [];
+    while (stack.length) {
+        const node = stack.pop();
+        if (!('tagName' in node))
+            continue;
+        const attrs = new Map(node.attrs.map(attr => [attr.name, attr.value]));
+        const location = node.sourceCodeLocation;
+        if (location && (attrs.get('id') === 'jini-consent' || attrs.get('id') === 'jini-consent-config' || attrs.has('data-jini-consent-runtime') || attrs.has('data-jini-consent-style'))) {
+            edits.push({ start: location.startOffset, end: location.endOffset });
+            continue;
+        }
+        if (node.tagName !== 'template')
+            stack.push(...node.childNodes);
+    }
+    for (const edit of edits.sort((a, b) => b.start - a.start))
+        html = html.slice(0, edit.start) + html.slice(edit.end);
+    return html;
+}
+//# sourceMappingURL=static.js.map

package/dist/consent/html/styles.d.ts

@@ -0,0 +1,3 @@
+/** Scoped fallback styles use inherited theme typography and overridable jini tokens. */
+export declare const CONSENT_CSS = "\n.jini-consent{position:fixed;inset:auto 1rem 1rem;z-index:2147483000;margin:auto;max-width:46rem;max-height:85dvh;overflow:auto;padding:1.25rem;border:1px solid var(--jini-border,var(--border,#d4d4d4));border-radius:var(--jini-radius,12px);background:var(--jini-surface,var(--bg,#fff));color:var(--jini-text,var(--fg,#222));box-shadow:0 8px 32px #0002;font:inherit;line-height:1.5;text-align:start;box-sizing:border-box}\n.jini-consent *, .jini-consent *::before, .jini-consent *::after{box-sizing:border-box}\n.jini-consent h2{font:inherit;font-weight:650;margin:0 0 .5rem;color:inherit}\n.jini-consent p{margin:.5rem 0;color:inherit}\n.jini-consent-actions{display:flex;gap:.5rem;flex-wrap:wrap;margin-top:1rem}\n.jini-consent button,.jini-consent summary{font:inherit;cursor:pointer;min-height:44px}\n.jini-consent button{padding:.55rem .85rem;border:1px solid currentColor;border-radius:var(--jini-radius,8px);background:transparent;color:inherit}\n.jini-consent button:disabled{cursor:default;opacity:.65}\n.jini-consent a{color:inherit;text-decoration:underline}\n.jini-consent :focus-visible{outline:2px solid currentColor;outline-offset:3px}\n.jini-consent details{margin-top:.75rem}\n.jini-consent summary{padding:.5rem 0}\n.jini-consent-category{display:flex;align-items:center;gap:.6rem;padding:.35rem 0;min-height:44px}\n.jini-consent-category input{width:1.15rem;height:1.15rem;accent-color:var(--jini-accent,#333)}\n.jini-consent[data-has-record=\"true\"]{position:static;box-shadow:none;margin:1rem auto;max-height:none}\n.jini-consent[data-has-record=\"true\"] .jini-consent-initial{display:none}\n.jini-consent [hidden]{display:none!important}\n@media(max-width:480px){.jini-consent{inset:auto .5rem .5rem;padding:1rem;max-height:80dvh}.jini-consent-actions button{flex:1 1 auto}.jini-consent[data-has-record=\"true\"]{margin:1rem .5rem}}\n";
+//# sourceMappingURL=styles.d.ts.map

package/dist/consent/html/styles.js

@@ -0,0 +1,22 @@
+/** Scoped fallback styles use inherited theme typography and overridable jini tokens. */
+export const CONSENT_CSS = `
+.jini-consent{position:fixed;inset:auto 1rem 1rem;z-index:2147483000;margin:auto;max-width:46rem;max-height:85dvh;overflow:auto;padding:1.25rem;border:1px solid var(--jini-border,var(--border,#d4d4d4));border-radius:var(--jini-radius,12px);background:var(--jini-surface,var(--bg,#fff));color:var(--jini-text,var(--fg,#222));box-shadow:0 8px 32px #0002;font:inherit;line-height:1.5;text-align:start;box-sizing:border-box}
+.jini-consent *, .jini-consent *::before, .jini-consent *::after{box-sizing:border-box}
+.jini-consent h2{font:inherit;font-weight:650;margin:0 0 .5rem;color:inherit}
+.jini-consent p{margin:.5rem 0;color:inherit}
+.jini-consent-actions{display:flex;gap:.5rem;flex-wrap:wrap;margin-top:1rem}
+.jini-consent button,.jini-consent summary{font:inherit;cursor:pointer;min-height:44px}
+.jini-consent button{padding:.55rem .85rem;border:1px solid currentColor;border-radius:var(--jini-radius,8px);background:transparent;color:inherit}
+.jini-consent button:disabled{cursor:default;opacity:.65}
+.jini-consent a{color:inherit;text-decoration:underline}
+.jini-consent :focus-visible{outline:2px solid currentColor;outline-offset:3px}
+.jini-consent details{margin-top:.75rem}
+.jini-consent summary{padding:.5rem 0}
+.jini-consent-category{display:flex;align-items:center;gap:.6rem;padding:.35rem 0;min-height:44px}
+.jini-consent-category input{width:1.15rem;height:1.15rem;accent-color:var(--jini-accent,#333)}
+.jini-consent[data-has-record="true"]{position:static;box-shadow:none;margin:1rem auto;max-height:none}
+.jini-consent[data-has-record="true"] .jini-consent-initial{display:none}
+.jini-consent [hidden]{display:none!important}
+@media(max-width:480px){.jini-consent{inset:auto .5rem .5rem;padding:1rem;max-height:80dvh}.jini-consent-actions button{flex:1 1 auto}.jini-consent[data-has-record="true"]{margin:1rem .5rem}}
+`;
+//# sourceMappingURL=styles.js.map

package/dist/consent/index.d.ts

@@ -0,0 +1,3 @@
+export * from './types.js';
+export * from './policy.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/consent/index.js

@@ -0,0 +1,3 @@
+export * from './types.js';
+export * from './policy.js';
+//# sourceMappingURL=index.js.map

package/dist/consent/node/index.d.ts

@@ -0,0 +1,47 @@
+import * as fs from 'node:fs/promises';
+import { type ConsentRecord, type ConsentRecordPort } from '../types.js';
+/** Atomic writer owns flush/rename/permissions; the host binds its installed platform writer. */
+export interface ConsentFilePorts {
+    readText(required: {
+        filePath: string;
+    }, optional?: Record<string, never>): Promise<string | null>;
+    writeJson(required: {
+        filePath: string;
+        record: ConsentRecord;
+    }, optional?: Record<string, never>): Promise<void>;
+}
+/** Host injects the existing platform/fs writer rather than copying its durability lifecycle. */
+export type ConsentAtomicWriter = (required: {
+    filePath: string;
+    data: unknown;
+}, optional: {
+    createParent: boolean;
+    mode: number;
+    refuseSymlink: boolean;
+}) => Promise<void>;
+/** Publish a flushed staging file with an exclusive hard link, then flush the directory.
+ * Filesystem/link failures propagate. No reader ever sees a partially-written proof file.
+ * @complexity Startup O(r log r) time/O(r) space; subsequent writes amortized O(1) plus bounded receipt I/O. */
+export declare function createNodeConsentFiles({ atomicWrite }: {
+    atomicWrite: ConsentAtomicWriter;
+}, { filesystem, uniqueId, maximumRecords, retentionMs, nowMs }?: {
+    filesystem?: Pick<typeof fs, 'link' | 'unlink' | 'open' | 'readdir' | 'stat'>;
+    uniqueId?: () => string;
+    maximumRecords?: number;
+    retentionMs?: number;
+    nowMs?: () => number;
+}): ConsentFilePorts;
+/** Per-site opaque filenames; IDs cannot navigate out of the configured proof directory.
+ * One immutable file per choice keeps historic policy versions without schema changes.
+ * @complexity O(1) record lookup; publication uses the injected writer's cached capacity/retention inventory.
+ * @throws Invalid ID, filesystem and malformed JSON errors; only absence returns null. */
+export declare function createConsentFileRecords({ directory, files }: {
+    directory: string;
+    files: ConsentFilePorts;
+}, _options?: {}): ConsentRecordPort;
+/** Group temporary IPv6 addresses by /64 using native address validation; mapped IPv4 keeps
+ * its IPv4 budget. The host still owns trusted-proxy address selection. @complexity O(1). */
+export declare function consentRateLimitKey({ address }: {
+    address: string;
+}, _options?: {}): string;
+//# sourceMappingURL=index.d.ts.map

package/dist/consent/node/index.js

@@ -0,0 +1,169 @@
+import path from 'node:path';
+import * as fs from 'node:fs/promises';
+import { isIP } from 'node:net';
+import { randomUUID } from 'node:crypto';
+import { CONSENT_MAX_AGE_MS } from '../types.js';
+/** Publish a flushed staging file with an exclusive hard link, then flush the directory.
+ * Filesystem/link failures propagate. No reader ever sees a partially-written proof file.
+ * @complexity Startup O(r log r) time/O(r) space; subsequent writes amortized O(1) plus bounded receipt I/O. */
+export function createNodeConsentFiles({ atomicWrite }, { filesystem = fs, uniqueId = randomUUID, maximumRecords = 10000, retentionMs = CONSENT_MAX_AGE_MS, nowMs = Date.now } = {}) {
+    if (!Number.isSafeInteger(maximumRecords) || maximumRecords < 1)
+        throw new Error('Consent receipt capacity must be a positive integer.');
+    if (!Number.isFinite(retentionMs) || retentionMs < 0)
+        throw new Error('Consent receipt retention must be nonnegative.');
+    const writes = new Map();
+    const inventories = new Map();
+    /** Serialize capacity checks/publication in this adapter. The host selects proof retention;
+     * cookie expiry is not a legal proof-erasure policy. This bounded default is configurable,
+     * and capacity eviction may shorten it; hosts needing longer proof retention must size accordingly.
+     * Scan once at startup, then maintain an oldest-first inventory rather than stat every save.
+     * @complexity Initial O(r log r); cached lookup O(1), pruning amortized O(1) per receipt. */
+    async function inventory({ directory }, _options = {}) {
+        const cached = inventories.get(directory);
+        if (cached)
+            return cached;
+        let names;
+        try {
+            names = await filesystem.readdir(directory);
+        }
+        catch (error) {
+            if (error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT')
+                names = [];
+            else
+                throw error;
+        }
+        const entries = [];
+        for (const name of names) {
+            if (/^[a-zA-Z0-9_-]{16,128}\.json$/.test(name))
+                entries.push([name, (await filesystem.stat(path.join(directory, name))).mtimeMs]);
+        }
+        entries.sort((left, right) => left[1] - right[1]);
+        const retained = new Map(entries);
+        inventories.set(directory, retained);
+        return retained;
+    }
+    /** Expiry and capacity remove only owned receipts; unrelated files stay intact. */
+    async function capacity({ directory, retained }, _options = {}) {
+        const cutoff = nowMs() - retentionMs;
+        for (const [name, timestamp] of retained) {
+            if (retained.size < maximumRecords && timestamp >= cutoff)
+                break;
+            try {
+                await filesystem.unlink(path.join(directory, name));
+            }
+            catch (error) {
+                if (!(error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT'))
+                    throw error;
+            }
+            retained.delete(name);
+        }
+    }
+    return {
+        async readText({ filePath }) {
+            try {
+                const handle = await filesystem.open(filePath, 'r');
+                try {
+                    if ((await handle.stat()).size > 4096)
+                        throw new Error('Consent receipt exceeds 4096 bytes.');
+                    return await handle.readFile('utf8');
+                }
+                finally {
+                    await handle.close();
+                }
+            }
+            catch (error) {
+                if (typeof error === 'object' && error !== null && 'code' in error && error.code === 'ENOENT')
+                    return null;
+                throw error;
+            }
+        },
+        async writeJson({ filePath, record }) {
+            const directoryPath = path.dirname(filePath);
+            const pending = (writes.get(directoryPath) ?? Promise.resolve()).catch(() => undefined).then(async () => {
+                if (JSON.stringify(record).length > 4096)
+                    throw new Error('Consent receipt exceeds 4096 bytes.');
+                const retained = await inventory({ directory: directoryPath });
+                if (retained.has(path.basename(filePath)))
+                    throw new Error('Consent receipt ID already exists.');
+                const staging = path.join(path.dirname(filePath), `.${path.basename(filePath)}.${uniqueId()}.pending`);
+                await atomicWrite({ filePath: staging, data: record }, { createParent: true, mode: 0o600, refuseSymlink: true });
+                try {
+                    await capacity({ directory: directoryPath, retained });
+                    await filesystem.link(staging, filePath);
+                    retained.set(path.basename(filePath), nowMs());
+                    const directory = await filesystem.open(path.dirname(filePath), 'r');
+                    try {
+                        await directory.sync();
+                    }
+                    finally {
+                        await directory.close();
+                    }
+                }
+                finally {
+                    await filesystem.unlink(staging);
+                }
+            });
+            writes.set(directoryPath, pending);
+            try {
+                await pending;
+            }
+            catch (error) {
+                inventories.delete(directoryPath);
+                throw error;
+            }
+            finally {
+                if (writes.get(directoryPath) === pending)
+                    writes.delete(directoryPath);
+            }
+        },
+    };
+}
+/** Per-site opaque filenames; IDs cannot navigate out of the configured proof directory.
+ * One immutable file per choice keeps historic policy versions without schema changes.
+ * @complexity O(1) record lookup; publication uses the injected writer's cached capacity/retention inventory.
+ * @throws Invalid ID, filesystem and malformed JSON errors; only absence returns null. */
+export function createConsentFileRecords({ directory, files }, _options = {}) {
+    const filePath = (id) => {
+        if (!/^[a-zA-Z0-9_-]{16,128}$/.test(id))
+            throw new Error('Invalid consent receipt ID.');
+        return path.join(directory, `${id}.json`);
+    };
+    return {
+        async read({ id }) {
+            const text = await files.readText({ filePath: filePath(id) });
+            if (text === null)
+                return null;
+            if (text.length > 4096)
+                throw new Error('Consent receipt exceeds 4096 bytes.');
+            return JSON.parse(text);
+        },
+        async save({ record }) {
+            const destination = filePath(record.id);
+            // The injected writer must also enforce exclusive publication against concurrent collisions.
+            if (await files.readText({ filePath: destination }) !== null)
+                throw new Error('Consent receipt ID already exists.');
+            await files.writeJson({ filePath: destination, record });
+        },
+    };
+}
+/** Group temporary IPv6 addresses by /64 using native address validation; mapped IPv4 keeps
+ * its IPv4 budget. The host still owns trusted-proxy address selection. @complexity O(1). */
+export function consentRateLimitKey({ address }, _options = {}) {
+    if (isIP(address) !== 6)
+        return address;
+    let normalized = address.split('%')[0];
+    if (normalized.includes('.')) {
+        const at = normalized.lastIndexOf(':');
+        const octets = normalized.slice(at + 1).split('.').map(Number);
+        normalized = normalized.slice(0, at + 1) + ((octets[0] << 8) + octets[1]).toString(16) + ':' + ((octets[2] << 8) + octets[3]).toString(16);
+    }
+    const [left = '', right = ''] = normalized.toLowerCase().split('::');
+    const before = left ? left.split(':') : [];
+    const after = right ? right.split(':') : [];
+    const groups = normalized.includes('::') ? [...before, ...Array(8 - before.length - after.length).fill('0'), ...after] : before;
+    const values = groups.map(group => parseInt(group, 16));
+    if (values.slice(0, 5).every(value => value === 0) && values[5] === 65535)
+        return `${values[6] >> 8}.${values[6] & 255}.${values[7] >> 8}.${values[7] & 255}`;
+    return values.slice(0, 4).map(value => value.toString(16)).join(':') + '::/64';
+}
+//# sourceMappingURL=index.js.map

package/dist/consent/policy.d.ts

@@ -0,0 +1,47 @@
+import { type ConsentChoices, type ConsentConfig, type ConsentRecord, type ConsentRegionMode } from './types.js';
+/** Only California has opt-out defaults; missing/unrecognized regions use opt-in.
+ * The host supplies a trusted header value, never a paid geo dependency. @complexity O(1). */
+export declare function resolveConsentRegion({ configuredMode, region }: {
+    configuredMode: ConsentConfig['regionMode'];
+    region: string | null;
+}, _options?: {}): ConsentRegionMode;
+/** GPC wins over stored or new grants. Conservative analytics denial covers tags that share data.
+ * Opt-out regions allow optional categories until refusal; GPC still takes precedence. @complexity O(1). */
+export declare function resolveConsentChoices({ choices, gpc, regionMode }: {
+    choices?: ConsentChoices | undefined;
+    gpc: boolean;
+    regionMode?: ConsentRegionMode;
+}, _options?: {}): ConsentChoices;
+/** Validate stored evidence at the trust boundary; invalid, stale, or future evidence is absent.
+ * @complexity O(1); receipt size is bounded by storage/HTTP adapters. */
+export declare function readConsentRecord({ value, policyVersion, nowMs }: {
+    value: unknown;
+    policyVersion: string;
+    nowMs: number;
+}, { maxAgeMs }?: {
+    maxAgeMs?: number;
+}): ConsentRecord | null;
+/** Parse form fields without truthy coercion; reject invalid actions and policy races.
+ * @throws Error with an actionable input message. @complexity O(1). */
+export declare function createConsentRecord({ fields, config, id, timestamp, regionMode, gpc }: {
+    fields: Record<string, unknown>;
+    config: ConsentConfig;
+    id: string;
+    timestamp: string;
+    regionMode: ConsentRegionMode;
+    gpc: boolean;
+}, _options?: {}): ConsentRecord;
+/** All v2 advertising signals map to marketing; this enqueues signals, never loads a Google tag.
+ * @complexity O(1). */
+export declare function googleConsentSignals({ choices }: {
+    choices: ConsentChoices;
+}, _options?: {}): {
+    ad_storage: string;
+    ad_user_data: string;
+    ad_personalization: string;
+    analytics_storage: string;
+    functionality_storage: string;
+    personalization_storage: string;
+    security_storage: string;
+};
+//# sourceMappingURL=policy.d.ts.map

package/dist/consent/policy.js

@@ -0,0 +1,62 @@
+import { CONSENT_MAX_AGE_MS, DENIED_CHOICES } from './types.js';
+/** Only California has opt-out defaults; missing/unrecognized regions use opt-in.
+ * The host supplies a trusted header value, never a paid geo dependency. @complexity O(1). */
+export function resolveConsentRegion({ configuredMode, region }, _options = {}) {
+    if (configuredMode !== 'auto')
+        return configuredMode;
+    return region?.trim().toUpperCase() === 'US-CA' ? 'opt-out' : 'opt-in';
+}
+/** GPC wins over stored or new grants. Conservative analytics denial covers tags that share data.
+ * Opt-out regions allow optional categories until refusal; GPC still takes precedence. @complexity O(1). */
+export function resolveConsentChoices({ choices, gpc, regionMode = 'opt-in' }, _options = {}) {
+    const effective = { ...(choices ?? (regionMode === 'opt-out' ? { necessary: true, functional: true, analytics: true, marketing: true } : DENIED_CHOICES)), necessary: true };
+    if (gpc)
+        return { ...effective, analytics: false, marketing: false };
+    return effective;
+}
+/** Validate stored evidence at the trust boundary; invalid, stale, or future evidence is absent.
+ * @complexity O(1); receipt size is bounded by storage/HTTP adapters. */
+export function readConsentRecord({ value, policyVersion, nowMs }, { maxAgeMs = CONSENT_MAX_AGE_MS } = {}) {
+    if (!value || typeof value !== 'object')
+        return null;
+    const record = value;
+    if (typeof record.id !== 'string' || !/^[a-zA-Z0-9_-]{16,128}$/.test(record.id))
+        return null;
+    if (record.policyVersion !== policyVersion || typeof record.timestamp !== 'string')
+        return null;
+    const time = Date.parse(record.timestamp);
+    if (!Number.isFinite(time) || time > nowMs || nowMs - time > maxAgeMs)
+        return null;
+    if (record.regionMode !== 'opt-in' && record.regionMode !== 'opt-out')
+        return null;
+    if (typeof record.gpc !== 'boolean' || !['accept', 'reject', 'save', 'do-not-sell'].includes(record.action ?? ''))
+        return null;
+    const choices = record.choices;
+    if (!choices || choices.necessary !== true || ['functional', 'analytics', 'marketing'].some(key => typeof choices[key] !== 'boolean'))
+        return null;
+    return { id: record.id, timestamp: record.timestamp, policyVersion, regionMode: record.regionMode, gpc: record.gpc, action: record.action, choices: resolveConsentChoices({ choices, gpc: record.gpc }) };
+}
+/** Parse form fields without truthy coercion; reject invalid actions and policy races.
+ * @throws Error with an actionable input message. @complexity O(1). */
+export function createConsentRecord({ fields, config, id, timestamp, regionMode, gpc }, _options = {}) {
+    if (fields.policyVersion !== config.policyVersion)
+        throw new Error('The privacy policy changed. Reload this page and choose again.');
+    const action = fields.action;
+    if (typeof action !== 'string' || !['accept', 'reject', 'save', 'do-not-sell'].includes(action))
+        throw new Error('Choose accept, reject, save, or do-not-sell.');
+    let choices = { ...DENIED_CHOICES };
+    if (action === 'accept')
+        choices = { necessary: true, functional: true, analytics: true, marketing: true };
+    if (action === 'do-not-sell')
+        choices = { necessary: true, functional: fields.functional === 'on', analytics: false, marketing: false };
+    if (action === 'save')
+        choices = { necessary: true, functional: fields.functional === 'on', analytics: fields.analytics === 'on', marketing: fields.marketing === 'on' };
+    return { id, timestamp, policyVersion: config.policyVersion, regionMode, gpc, action: action, choices: resolveConsentChoices({ choices, gpc }) };
+}
+/** All v2 advertising signals map to marketing; this enqueues signals, never loads a Google tag.
+ * @complexity O(1). */
+export function googleConsentSignals({ choices }, _options = {}) {
+    const marketing = choices.marketing ? 'granted' : 'denied';
+    return { ad_storage: marketing, ad_user_data: marketing, ad_personalization: marketing, analytics_storage: choices.analytics ? 'granted' : 'denied', functionality_storage: choices.functional ? 'granted' : 'denied', personalization_storage: marketing, security_storage: 'granted' };
+}
+//# sourceMappingURL=policy.js.map

package/dist/consent/types.d.ts

@@ -0,0 +1,40 @@
+/** Optional scripts require a stored visitor choice; necessary is never optional. */
+export declare const CONSENT_CATEGORIES: readonly ["necessary", "functional", "analytics", "marketing"];
+export type ConsentCategory = typeof CONSENT_CATEGORIES[number];
+export type ConsentChoices = Record<ConsentCategory, boolean>;
+export type ConsentRegionMode = 'opt-in' | 'opt-out';
+export type ConsentAction = 'accept' | 'reject' | 'save' | 'do-not-sell';
+/** Text/policy content belongs to the host, not the mechanism. */
+export interface ConsentConfig {
+    enabled: boolean;
+    regionMode: 'auto' | ConsentRegionMode;
+    policyVersion: string;
+    privacyPolicyUrl: string;
+    title: string;
+    message: string;
+    acceptLabel: string;
+    rejectLabel: string;
+    preferencesLabel: string;
+}
+/** Immutable evidence; no IP, user-agent, or principal identity is collected. */
+export interface ConsentRecord {
+    id: string;
+    timestamp: string;
+    policyVersion: string;
+    choices: ConsentChoices;
+    regionMode: ConsentRegionMode;
+    gpc: boolean;
+    action: ConsentAction;
+}
+/** save must be durable before resolving, and must not overwrite an existing ID. */
+export interface ConsentRecordPort {
+    read(required: {
+        id: string;
+    }, optional?: Record<string, never>): Promise<unknown>;
+    save(required: {
+        record: ConsentRecord;
+    }, optional?: Record<string, never>): Promise<void>;
+}
+export declare const CONSENT_MAX_AGE_MS: number;
+export declare const DENIED_CHOICES: Readonly<ConsentChoices>;
+//# sourceMappingURL=types.d.ts.map

package/dist/consent/types.js

@@ -0,0 +1,5 @@
+/** Optional scripts require a stored visitor choice; necessary is never optional. */
+export const CONSENT_CATEGORIES = ['necessary', 'functional', 'analytics', 'marketing'];
+export const CONSENT_MAX_AGE_MS = 180 * 24 * 60 * 60 * 1000;
+export const DENIED_CHOICES = Object.freeze({ necessary: true, functional: false, analytics: false, marketing: false });
+//# sourceMappingURL=types.js.map

package/dist/content-types/agent-tools.js

@@ -140,7 +140,7 @@ export const contentTypesAgentToolCatalog = [
                 key: {
                     type: "string",
                     pattern: IDENTIFIER_GRAMMAR_PATTERN,
-                    description: "Permanent identifier for the content type. Cannot be changed later. 'post' and 'page' are permanently reserved and will be rejected.",
+                    description: "Permanent identifier for the content type. Cannot be changed later. 'post' and 'page' are permanently reserved and will be rejected. Host-reserved route keys (such as 'admin' or 'api') are also rejected when configured.",
                 },
                 label: { type: "string", description: "Human-readable display name shown in the admin UI." },
                 fields: FIELDS_SCHEMA,

package/dist/content-types/tool-registrations.d.ts

@@ -52,6 +52,8 @@ export interface ContentTypesToolDeps {
     outbox: OutboxPort;
     contentTypeRepo: ContentTypeRepoPort & ContentTypeListPort;
     contentTypeIndexProvisioner: IndexProvisionerPort & TeardownIndexProvisionerPort;
+    /** The same host route policy applied to direct content-type registration. */
+    reservedContentTypeKeys?: ReadonlySet<string>;
 }
 /**
  * This wiring layer's OWN risk classification, authored from what each handler below actually

package/dist/content-types/tool-registrations.js

@@ -87,6 +87,7 @@ function contentTypesDeps(routeDeps) {
         authorize: adaptLegacyAuthorize({ authorize: routeDeps.authorize }),
         outbox: routeDeps.outbox,
         indexProvisioner: routeDeps.contentTypeIndexProvisioner,
+        ...(routeDeps.reservedContentTypeKeys !== undefined ? { reservedKeys: routeDeps.reservedContentTypeKeys } : {}),
     };
 }
 export function buildContentTypesRegistrations(routeDeps) {

package/dist/content-types/write-service.d.ts

@@ -109,6 +109,8 @@ export interface ContentTypeWriteServiceDeps {
     indexProvisioner: IndexProvisionerPort;
     outbox: OutboxPort;
     watermark?: WatermarkPort;
+    /** Host-owned public route segments which a collection key cannot claim. */
+    reservedKeys?: ReadonlySet<string>;
 }
 export interface RegisterContentTypeRequired {
     deps: ContentTypeWriteServiceDeps;

package/dist/content-types/write-service.js

@@ -66,6 +66,9 @@ export async function registerContentType(required) {
     if (RESERVED_CONTENT_TYPE_KEYS.has(input.key)) {
         return { ok: false, error: new ReservedContentTypeKeyError({ message: `key '${input.key}' is permanently reserved for the legacy 'posts' table` }) };
     }
+    if (deps.reservedKeys?.has(input.key.toLowerCase())) {
+        return { ok: false, error: new ReservedContentTypeKeyError({ message: `key '${input.key}' is reserved for a host route` }) };
+    }
     // Guard 3: field-name grammar, then uniqueness (every field, before any kind/cap check).
     const nameErrorOnRegister = fieldNameError(input.fields);
     if (nameErrorOnRegister)

package/dist/forms/descriptor-rules.d.ts

@@ -0,0 +1,9 @@
+/** Definition constraints beyond the original four-type schema; every invalid definition fails closed. */
+import type { FieldDescriptor } from "./types.js";
+import type { FieldError } from "./forms.js";
+/** Collect definition errors without coercing an untrusted descriptor into a valid one.
+ * @complexity O(k + o) for descriptor keys and at most 100 options. */
+export declare function commonDescriptorErrors({ field }: {
+    field: FieldDescriptor;
+}, _optional?: {}): FieldError[];
+//# sourceMappingURL=descriptor-rules.d.ts.map