@actuate-media/cms-core 0.13.0 → 0.15.0

package/dist/api/handlers.js

@@ -33,6 +33,7 @@ import { validateMimeType, checkMagicBytes } from '../security/upload.js';
 import { sanitizeHtml } from '../security/sanitize.js';
 import { getActuateConfig, getActuateCoreVersion } from '../config/runtime.js';
 import { validateEnvShape } from '../diagnostics/env.js';
+import { generateApiKey, hashApiKey, looksLikeApiKey, validateApiKeyScope, validateApiKeyGlobalScope, validateApiKeyMediaScope, validateApiKeyPageBuilderScope, validateApiKeyIp, } from '../security/api-key-enhanced.js';
 // Opaque dynamic import so Turbopack/webpack won't statically analyze the specifier.
 // Returns { put, del, ... } from @vercel/blob when available.
 async function importBlobStorage() {
@@ -176,6 +177,79 @@ function modelNotAvailable(name) {
         'Run `actuate db:init` for new schemas, or carefully update the existing Actuate block, create/apply a Prisma migration, then regenerate Prisma Client. ' +
         'See https://actuatecms.dev/docs/database-setup for required models.', 501);
 }
+/**
+ * XML-escape a value for safe inclusion in sitemap content. Sitemaps reject
+ * unescaped ampersands and angle brackets; URLs frequently contain `&` query
+ * separators, so this is non-optional.
+ */
+function escapeXml(value) {
+    return value
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&apos;');
+}
+/**
+ * Renders a 1200x630 SVG suitable for og:image. We don't pull in Satori/resvg
+ * because most integrators don't need PNG — major crawlers (Facebook, Twitter,
+ * LinkedIn, Slack, Discord) handle image/svg+xml correctly. Sites that
+ * specifically need PNG can override with their own /og endpoint via
+ * @vercel/og and point `seo.defaultOgImage` at it.
+ */
+function renderOgSvg(opts) {
+    const { title, description, siteName, bg, fg, muted } = opts;
+    // Naive line wrapping at ~22 chars (large font). Good enough for an OG card;
+    // anything longer than ~3 lines gets truncated with an ellipsis.
+    const wrap = (text, maxChars, maxLines) => {
+        const words = text.split(/\s+/);
+        const lines = [];
+        let current = '';
+        for (const w of words) {
+            if (lines.length >= maxLines)
+                break;
+            const next = current ? `${current} ${w}` : w;
+            if (next.length > maxChars) {
+                if (current)
+                    lines.push(current);
+                current = w;
+                if (lines.length === maxLines - 1 && words.indexOf(w) < words.length - 1) {
+                    lines.push(current.length > maxChars ? current.slice(0, maxChars - 1) + '…' : current + '…');
+                    current = '';
+                    break;
+                }
+            }
+            else {
+                current = next;
+            }
+        }
+        if (current && lines.length < maxLines)
+            lines.push(current);
+        return lines;
+    };
+    const escapeSvg = (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+    const titleLines = wrap(title, 28, 3);
+    const descLines = description ? wrap(description, 60, 2) : [];
+    const titleEls = titleLines
+        .map((line, i) => `<tspan x="60" dy="${i === 0 ? 0 : 78}">${escapeSvg(line)}</tspan>`)
+        .join('');
+    const descEls = descLines
+        .map((line, i) => `<tspan x="60" dy="${i === 0 ? 0 : 36}">${escapeSvg(line)}</tspan>`)
+        .join('');
+    // Layout: site name top-left, title bottom-left, description below title.
+    // Coordinates are roughly aligned to the 1200x630 spec used by every major
+    // social platform.
+    const titleY = descLines.length > 0 ? 360 : 420;
+    const descY = titleY + 80 * titleLines.length;
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="630" viewBox="0 0 1200 630">
+  <rect width="1200" height="630" fill="${bg}"/>
+  ${siteName ? `<text x="60" y="100" font-family="system-ui, -apple-system, Segoe UI, Arial, sans-serif" font-size="28" font-weight="500" fill="${muted}">${escapeSvg(siteName)}</text>` : ''}
+  <text x="60" y="${titleY}" font-family="system-ui, -apple-system, Segoe UI, Arial, sans-serif" font-size="68" font-weight="700" fill="${fg}">${titleEls}</text>
+  ${descLines.length > 0 ? `<text x="60" y="${descY}" font-family="system-ui, -apple-system, Segoe UI, Arial, sans-serif" font-size="30" fill="${muted}">${descEls}</text>` : ''}
+  <rect x="60" y="560" width="60" height="6" fill="${fg}" rx="3"/>
+</svg>`;
+}
 async function safeCount(model, where) {
     try {
         if (!model || typeof model !== 'object')
@@ -293,6 +367,49 @@ async function extractSession(request) {
     }
     if (!token)
         return null;
+    // API key path. Keys are recognized by the `act_sk_` prefix and looked up
+    // by SHA-256 hash. We never JWT-verify these tokens — they are opaque
+    // random secrets stored as hashes in `actuate_api_keys`.
+    if (looksLikeApiKey(token)) {
+        try {
+            const d = getDB();
+            if (!hasModel(d, 'apiKey'))
+                return null;
+            const hash = await hashApiKey(token);
+            const apiKey = await d.apiKey.findUnique({ where: { keyHash: hash } });
+            if (!apiKey)
+                return null;
+            if (apiKey.revokedAt)
+                return null;
+            if (apiKey.expiresAt && new Date(apiKey.expiresAt).getTime() < Date.now())
+                return null;
+            const ipRestrictions = Array.isArray(apiKey.ipRestrictions)
+                ? apiKey.ipRestrictions
+                : apiKey.ipRestrictions
+                    ? (apiKey.ipRestrictions.allow ?? null)
+                    : null;
+            if (ipRestrictions && ipRestrictions.length > 0) {
+                const ip = getClientIp(request);
+                if (!validateApiKeyIp(ipRestrictions, ip))
+                    return null;
+            }
+            const scopes = apiKey.scopes ?? {};
+            // Fire-and-forget lastUsedAt update; never block the request on it.
+            void d.apiKey
+                .update({ where: { id: apiKey.id }, data: { lastUsedAt: new Date() } })
+                .catch(() => { });
+            return {
+                userId: apiKey.userId,
+                role: scopes.admin ? 'ADMIN' : 'API_KEY',
+                sessionId: apiKey.id,
+                apiKey: { id: apiKey.id, scopes },
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+    // Session JWT path.
     try {
         const payload = await verifySession(token, { secret: getSessionSecret() });
         const d = getDB();
@@ -365,6 +482,57 @@ async function requireAuth(request) {
     }
     return { session };
 }
+/**
+ * Check that the request's auth context permits `action` on `collection`.
+ * - Session-authenticated requests fall through to `requireRole` semantics:
+ *   write actions require WRITE_ROLES.
+ * - API-key-authenticated requests must have an explicit scope match.
+ */
+function requireCollectionScope(session, collection, action) {
+    if (session.apiKey) {
+        if (!validateApiKeyScope(session.apiKey.scopes, collection, action)) {
+            return errorResponse(`API key does not have permission to ${action} on collection "${collection}"`, 403);
+        }
+        return null;
+    }
+    if (action === 'read')
+        return null;
+    return requireRole(session.role, WRITE_ROLES);
+}
+function requireGlobalScope(session, slug) {
+    if (session.apiKey) {
+        if (!validateApiKeyGlobalScope(session.apiKey.scopes, slug)) {
+            return errorResponse(`API key does not have permission for global "${slug}"`, 403);
+        }
+    }
+    return null;
+}
+function requireMediaScope(session) {
+    if (session.apiKey) {
+        if (!validateApiKeyMediaScope(session.apiKey.scopes)) {
+            return errorResponse('API key does not have media scope', 403);
+        }
+    }
+    return null;
+}
+function requirePageBuilderScope(session) {
+    if (session.apiKey) {
+        if (!validateApiKeyPageBuilderScope(session.apiKey.scopes)) {
+            return errorResponse('API key does not have pageBuilder scope', 403);
+        }
+        return null;
+    }
+    return requireRole(session.role, ADMIN_ROLES);
+}
+function requireAdminScope(session) {
+    if (session.apiKey) {
+        if (!session.apiKey.scopes.admin) {
+            return errorResponse('API key does not have admin scope', 403);
+        }
+        return null;
+    }
+    return requireRole(session.role, ADMIN_ROLES);
+}
 function buildActionContext(session, db, locale) {
     return {
         userId: session.userId,
@@ -1118,6 +1286,9 @@ export function registerCMSRoutes(router) {
             const auth = await requireAuth(request);
             if (auth.error)
                 return auth.error;
+            const scopeErr = requireCollectionScope(auth.session, params.slug, 'read');
+            if (scopeErr)
+                return scopeErr;
             const url = new URL(request.url);
             const ctx = buildActionContext(auth.session, db(), url.searchParams.get('locale') ?? undefined);
             const result = await listDocuments({
@@ -1155,6 +1326,9 @@ export function registerCMSRoutes(router) {
             const auth = await requireAuth(request);
             if (auth.error)
                 return auth.error;
+            const scopeErr = requireCollectionScope(auth.session, params.slug, 'read');
+            if (scopeErr)
+                return scopeErr;
             const ctx = buildActionContext(auth.session, db());
             const doc = await getDocument(params.slug, params.id, ctx);
             if (!doc) {
@@ -1175,9 +1349,9 @@ export function registerCMSRoutes(router) {
             const auth = await requireAuth(request);
             if (auth.error)
                 return auth.error;
-            const roleErr = requireRole(auth.session.role, WRITE_ROLES);
-            if (roleErr)
-                return roleErr;
+            const scopeErr = requireCollectionScope(auth.session, params.slug, 'create');
+            if (scopeErr)
+                return scopeErr;
             const body = (await request.json());
             const ctx = buildActionContext(auth.session, db());
             const doc = await createDocument(params.slug, body, ctx);
@@ -1197,9 +1371,9 @@ export function registerCMSRoutes(router) {
             const auth = await requireAuth(request);
             if (auth.error)
                 return auth.error;
-            const roleErr = requireRole(auth.session.role, WRITE_ROLES);
-            if (roleErr)
-                return roleErr;
+            const scopeErr = requireCollectionScope(auth.session, params.slug, 'update');
+            if (scopeErr)
+                return scopeErr;
             const body = (await request.json());
             const ctx = buildActionContext(auth.session, db());
             const doc = await updateDocument(params.slug, params.id, body, ctx);
@@ -1219,9 +1393,9 @@ export function registerCMSRoutes(router) {
             const auth = await requireAuth(request);
             if (auth.error)
                 return auth.error;
-            const roleErr = requireRole(auth.session.role, WRITE_ROLES);
-            if (roleErr)
-                return roleErr;
+            const scopeErr = requireCollectionScope(auth.session, params.slug, 'delete');
+            if (scopeErr)
+                return scopeErr;
             const ctx = buildActionContext(auth.session, db());
             await deleteDocument(params.slug, params.id, ctx);
             await logEvent({
@@ -1286,6 +1460,9 @@ export function registerCMSRoutes(router) {
             const auth = await requireAuth(request);
             if (auth.error)
                 return auth.error;
+            const scopeErr = requireMediaScope(auth.session);
+            if (scopeErr)
+                return scopeErr;
             const body = (await request.json());
             if (!body.filename || !body.contentType) {
                 return errorResponse('filename and contentType are required', 400);
@@ -1330,6 +1507,9 @@ export function registerCMSRoutes(router) {
             const auth = await requireAuth(request);
             if (auth.error)
                 return auth.error;
+            const scopeErr = requireMediaScope(auth.session);
+            if (scopeErr)
+                return scopeErr;
             // Reject *before* buffering the body. We require a valid content-length
             // header so that chunked / no-length requests (which would otherwise
             // bypass this gate and allow `request.formData()` to buffer unbounded
@@ -1661,9 +1841,14 @@ export function registerCMSRoutes(router) {
             const auth = await requireAuth(request);
             if (auth.error)
                 return auth.error;
-            const roleErr = requireRole(auth.session.role, WRITE_ROLES);
-            if (roleErr)
-                return roleErr;
+            const scopeErr = requireMediaScope(auth.session);
+            if (scopeErr)
+                return scopeErr;
+            if (!auth.session.apiKey) {
+                const roleErr = requireRole(auth.session.role, WRITE_ROLES);
+                if (roleErr)
+                    return roleErr;
+            }
             const body = (await request.json());
             const updated = await db().media.update({
                 where: { id: params.id },
@@ -1686,9 +1871,14 @@ export function registerCMSRoutes(router) {
             const auth = await requireAuth(request);
             if (auth.error)
                 return auth.error;
-            const roleErr = requireRole(auth.session.role, WRITE_ROLES);
-            if (roleErr)
-                return roleErr;
+            const scopeErr = requireMediaScope(auth.session);
+            if (scopeErr)
+                return scopeErr;
+            if (!auth.session.apiKey) {
+                const roleErr = requireRole(auth.session.role, WRITE_ROLES);
+                if (roleErr)
+                    return roleErr;
+            }
             const media = await db().media.findUnique({ where: { id: params.id } });
             if (!media) {
                 return errorResponse('Media not found', 404);
@@ -2218,6 +2408,163 @@ export function registerCMSRoutes(router) {
         }
     });
     // ---------------------------------------------------------------------------
+    // API key management (admin-only). Keys are created here, hashed in the DB,
+    // and shown to the caller exactly once. They authenticate programmatic
+    // clients (AI agents, CI, integrations) against the same REST surface as a
+    // user session, but skip CSRF and use scope-based authorization.
+    // ---------------------------------------------------------------------------
+    router.get('/api-keys', async (request) => {
+        try {
+            const auth = await requireAuth(request);
+            if (auth.error)
+                return auth.error;
+            const adminErr = requireAdminScope(auth.session);
+            if (adminErr)
+                return adminErr;
+            const d = db();
+            if (!hasModel(d, 'apiKey'))
+                return json({ data: [] });
+            const keys = await d.apiKey.findMany({
+                orderBy: { createdAt: 'desc' },
+                select: {
+                    id: true,
+                    name: true,
+                    keyPrefix: true,
+                    scopes: true,
+                    ipRestrictions: true,
+                    expiresAt: true,
+                    lastUsedAt: true,
+                    revokedAt: true,
+                    createdAt: true,
+                    user: { select: { id: true, name: true, email: true } },
+                },
+            });
+            return json({ data: keys });
+        }
+        catch (err) {
+            return internalError(err, 'api-keys/list');
+        }
+    });
+    router.post('/api-keys', async (request) => {
+        try {
+            const auth = await requireAuth(request);
+            if (auth.error)
+                return auth.error;
+            const adminErr = requireAdminScope(auth.session);
+            if (adminErr)
+                return adminErr;
+            // Issuing a new credential is a sensitive action — require reauth for
+            // session-authenticated callers. API-key-authenticated requests are
+            // already proving possession of a long-lived credential.
+            if (!auth.session.apiKey) {
+                const reauthErr = await requirePasswordReauth(request, auth.session.userId);
+                if (reauthErr)
+                    return reauthErr;
+            }
+            const body = (await request.json());
+            if (!body.name || typeof body.name !== 'string' || body.name.trim().length === 0) {
+                return errorResponse('name is required', 400);
+            }
+            if (body.name.length > 100) {
+                return errorResponse('name must be 100 characters or fewer', 400);
+            }
+            const scopes = body.scopes ?? {};
+            // Sanity check the scope shape so we don't store garbage that fails
+            // every authorization check at runtime.
+            if (!scopes.admin &&
+                !scopes.media &&
+                !scopes.pageBuilder &&
+                (!scopes.collections || scopes.collections.length === 0) &&
+                (!scopes.globals || scopes.globals.length === 0)) {
+                return errorResponse('scopes must grant at least one capability (admin, media, pageBuilder, collections, or globals)', 400);
+            }
+            let expiresAt;
+            if (body.expiresAt) {
+                const parsed = new Date(body.expiresAt);
+                if (isNaN(parsed.getTime()))
+                    return errorResponse('Invalid expiresAt date', 400);
+                if (parsed.getTime() < Date.now())
+                    return errorResponse('expiresAt must be in the future', 400);
+                expiresAt = parsed;
+            }
+            const { key, keyHash, keyPrefix } = await generateApiKey({
+                prefix: 'act_sk',
+                scopes,
+                expiresAt,
+            });
+            const d = db();
+            const record = await d.apiKey.create({
+                data: {
+                    name: body.name.trim(),
+                    keyHash,
+                    keyPrefix,
+                    userId: auth.session.userId,
+                    scopes: scopes,
+                    ipRestrictions: body.ipRestrictions?.length ? body.ipRestrictions : null,
+                    expiresAt: expiresAt ?? null,
+                },
+                select: {
+                    id: true,
+                    name: true,
+                    keyPrefix: true,
+                    scopes: true,
+                    ipRestrictions: true,
+                    expiresAt: true,
+                    createdAt: true,
+                },
+            });
+            await logEvent({
+                event: 'api_key_created',
+                userId: auth.session.userId,
+                ipAddress: clientIp(request),
+                userAgent: request.headers.get('user-agent') ?? undefined,
+                details: { apiKeyId: record.id, name: record.name, scopes },
+            });
+            // The raw `key` is the only thing the caller will ever see; we never
+            // store it in plaintext. Document this in the response shape.
+            return json({ data: { ...record, key } }, 201);
+        }
+        catch (err) {
+            return internalError(err, 'api-keys/create');
+        }
+    });
+    router.delete('/api-keys/:id', async (request, params) => {
+        try {
+            const auth = await requireAuth(request);
+            if (auth.error)
+                return auth.error;
+            const adminErr = requireAdminScope(auth.session);
+            if (adminErr)
+                return adminErr;
+            // Same reauth gate as creation — revocation is irreversible and
+            // affects every dependent client.
+            if (!auth.session.apiKey) {
+                const reauthErr = await requirePasswordReauth(request, auth.session.userId);
+                if (reauthErr)
+                    return reauthErr;
+            }
+            const d = db();
+            const existing = await d.apiKey.findUnique({ where: { id: params.id } });
+            if (!existing)
+                return errorResponse('API key not found', 404);
+            await d.apiKey.update({
+                where: { id: params.id },
+                data: { revokedAt: new Date() },
+            });
+            await logEvent({
+                event: 'api_key_revoked',
+                userId: auth.session.userId,
+                ipAddress: clientIp(request),
+                userAgent: request.headers.get('user-agent') ?? undefined,
+                details: { apiKeyId: existing.id, name: existing.name },
+            });
+            return json({ data: { revoked: true } });
+        }
+        catch (err) {
+            return internalError(err, 'api-keys/revoke');
+        }
+    });
+    // ---------------------------------------------------------------------------
     // Users route
     // ---------------------------------------------------------------------------
     router.get('/users', async (request) => {
@@ -2844,6 +3191,237 @@ export function registerCMSRoutes(router) {
             return internalError(err, 'llms.txt');
         }
     });
+    // ---------------------------------------------------------------------------
+    // Public SEO surfaces: sitemap.xml, per-collection sitemaps, robots.txt,
+    // and the dynamic /og.png OG-image endpoint. These are unauthenticated by
+    // design — search engines and social crawlers will fetch them.
+    // ---------------------------------------------------------------------------
+    function siteUrlFromRequest(request) {
+        const cfg = getActuateConfig()?.seo;
+        if (cfg?.siteUrl)
+            return cfg.siteUrl.replace(/\/+$/, '');
+        // Fall back to the request origin so the routes work on preview deploys
+        // before the integrator has configured siteUrl.
+        try {
+            const u = new URL(request.url);
+            return `${u.protocol}//${u.host}`;
+        }
+        catch {
+            return '';
+        }
+    }
+    function sitemapEligibleCollections() {
+        const cfg = getActuateConfig();
+        if (!cfg)
+            return [];
+        const excluded = new Set(cfg.seo?.sitemap?.excludeCollections ?? []);
+        const out = [];
+        for (const [slug, col] of Object.entries(cfg.collections ?? {})) {
+            if (excluded.has(slug))
+                continue;
+            if (col.seo?.excludeFromSitemap)
+                continue;
+            out.push({ slug, urlPrefix: col.urlPrefix, type: col.type, seo: col.seo });
+        }
+        return out;
+    }
+    router.get('/sitemap.xml', async (request) => {
+        try {
+            const cfg = getActuateConfig();
+            if (cfg?.seo?.sitemap?.disabled)
+                return errorResponse('Sitemap disabled', 404);
+            const base = siteUrlFromRequest(request);
+            const cols = sitemapEligibleCollections();
+            // Sitemap index points at /sitemaps/:slug.xml for each collection.
+            const sitemaps = cols
+                .map((c) => [
+                '  <sitemap>',
+                `    <loc>${base}/api/cms/sitemaps/${c.slug}.xml</loc>`,
+                `    <lastmod>${new Date().toISOString()}</lastmod>`,
+                '  </sitemap>',
+            ].join('\n'))
+                .join('\n');
+            const xml = [
+                '<?xml version="1.0" encoding="UTF-8"?>',
+                '<sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">',
+                sitemaps,
+                '</sitemapindex>',
+            ].join('\n');
+            return new Response(xml, {
+                status: 200,
+                headers: {
+                    'Content-Type': 'application/xml; charset=utf-8',
+                    'Cache-Control': 'public, max-age=300, s-maxage=600',
+                },
+            });
+        }
+        catch (err) {
+            return internalError(err, 'sitemap.xml');
+        }
+    });
+    // The router's path-param syntax (`:name`) greedily matches everything up
+    // to the next `/`, so registering as `/sitemaps/:slug.xml` would capture
+    // `slug.xml` into a single param. We register `/sitemaps/:slug` instead and
+    // require the `.xml` suffix in the handler.
+    router.get('/sitemaps/:slug', async (request, params) => {
+        try {
+            const cfg = getActuateConfig();
+            if (cfg?.seo?.sitemap?.disabled)
+                return errorResponse('Sitemap disabled', 404);
+            const slugParam = params.slug ?? '';
+            if (!/\.xml$/i.test(slugParam))
+                return errorResponse('Sitemap not found', 404);
+            const rawSlug = slugParam.replace(/\.xml$/i, '');
+            const collection = cfg?.collections?.[rawSlug];
+            if (!collection)
+                return errorResponse('Collection not found', 404);
+            if (collection.seo?.excludeFromSitemap)
+                return errorResponse('Collection excluded from sitemap', 404);
+            const base = siteUrlFromRequest(request);
+            const docs = await db().document.findMany({
+                where: { collection: rawSlug, deletedAt: null, status: 'PUBLISHED' },
+                select: { slug: true, updatedAt: true, data: true },
+                orderBy: { updatedAt: 'desc' },
+                take: 5000,
+            });
+            const prefix = (collection.urlPrefix ?? '').replace(/^\/|\/$/g, '');
+            const defaultPriority = collection.seo?.sitemapPriority ??
+                cfg?.seo?.sitemap?.defaultPriority ??
+                (collection.type === 'page' ? 0.8 : 0.6);
+            const changefreq = collection.seo?.sitemapChangeFreq ?? cfg?.seo?.sitemap?.defaultChangeFreq ?? 'weekly';
+            const urls = [];
+            // Archive page first (e.g. /blog) for post-type collections.
+            if (collection.seo?.archivePath && collection.type === 'post') {
+                const archive = collection.seo.archivePath.startsWith('http')
+                    ? collection.seo.archivePath
+                    : `${base}${collection.seo.archivePath}`;
+                urls.push([
+                    '  <url>',
+                    `    <loc>${escapeXml(archive)}</loc>`,
+                    `    <lastmod>${new Date().toISOString()}</lastmod>`,
+                    `    <changefreq>${changefreq}</changefreq>`,
+                    '    <priority>0.6</priority>',
+                    '  </url>',
+                ].join('\n'));
+            }
+            for (const d of docs) {
+                const data = d.data || {};
+                const slug = d.slug ?? data.slug;
+                if (!slug)
+                    continue;
+                const loc = prefix ? `${base}/${prefix}/${slug}` : `${base}/${slug}`;
+                urls.push([
+                    '  <url>',
+                    `    <loc>${escapeXml(loc)}</loc>`,
+                    `    <lastmod>${d.updatedAt?.toISOString() ?? new Date().toISOString()}</lastmod>`,
+                    `    <changefreq>${changefreq}</changefreq>`,
+                    `    <priority>${defaultPriority.toFixed(1)}</priority>`,
+                    '  </url>',
+                ].join('\n'));
+            }
+            const xml = [
+                '<?xml version="1.0" encoding="UTF-8"?>',
+                '<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">',
+                urls.join('\n'),
+                '</urlset>',
+            ].join('\n');
+            return new Response(xml, {
+                status: 200,
+                headers: {
+                    'Content-Type': 'application/xml; charset=utf-8',
+                    'Cache-Control': 'public, max-age=300, s-maxage=600',
+                },
+            });
+        }
+        catch (err) {
+            return internalError(err, 'sitemaps/:slug.xml');
+        }
+    });
+    router.get('/robots.txt', async (request) => {
+        try {
+            const cfg = getActuateConfig();
+            const seo = cfg?.seo;
+            if (seo?.robots?.disabled)
+                return errorResponse('robots.txt disabled', 404);
+            const base = siteUrlFromRequest(request);
+            const sitemapUrl = seo?.sitemap?.disabled ? undefined : `${base}/api/cms/sitemap.xml`;
+            const lines = [
+                'User-agent: *',
+                'Allow: /',
+                'Disallow: /admin',
+                'Disallow: /api/',
+                '',
+            ];
+            for (const rule of seo?.robots?.additionalRules ?? []) {
+                lines.push(`User-agent: ${rule.userAgent}`);
+                for (const allow of rule.allow ?? [])
+                    lines.push(`Allow: ${allow}`);
+                for (const dis of rule.disallow ?? [])
+                    lines.push(`Disallow: ${dis}`);
+                lines.push('');
+            }
+            if (seo?.robots?.blockAIBots) {
+                const bots = [
+                    'GPTBot',
+                    'ChatGPT-User',
+                    'ClaudeBot',
+                    'Claude-Web',
+                    'anthropic-ai',
+                    'Bytespider',
+                    'CCBot',
+                    'Google-Extended',
+                ];
+                for (const bot of bots) {
+                    lines.push(`User-agent: ${bot}`);
+                    lines.push('Disallow: /');
+                    lines.push('');
+                }
+            }
+            if (sitemapUrl)
+                lines.push(`Sitemap: ${sitemapUrl}`, '');
+            return new Response(lines.join('\n'), {
+                status: 200,
+                headers: {
+                    'Content-Type': 'text/plain; charset=utf-8',
+                    'Cache-Control': 'public, max-age=3600, s-maxage=3600',
+                },
+            });
+        }
+        catch (err) {
+            return internalError(err, 'robots.txt');
+        }
+    });
+    router.get('/og.png', async (request) => {
+        try {
+            const cfg = getActuateConfig();
+            if (cfg?.seo?.ogImage?.disabled)
+                return errorResponse('og.png disabled', 404);
+            const url = new URL(request.url);
+            const title = url.searchParams.get('title') ?? cfg?.seo?.siteName ?? 'Untitled';
+            const description = url.searchParams.get('description') ?? undefined;
+            const siteName = url.searchParams.get('siteName') ?? cfg?.seo?.siteName;
+            const theme = url.searchParams.get('theme') ?? cfg?.seo?.ogImage?.theme ?? 'light';
+            const bg = theme === 'dark' ? '#0a0a0a' : '#ffffff';
+            const fg = theme === 'dark' ? '#fafafa' : '#0a0a0a';
+            const muted = theme === 'dark' ? '#a1a1aa' : '#71717a';
+            // SVG OG image. Crawlers (Facebook, Twitter/X, LinkedIn, Slack, Discord)
+            // all accept image/svg+xml when served with the right Content-Type. We
+            // chose SVG over PNG to avoid forcing a Satori/resvg dependency on
+            // every integrator; sites that need PNG can override with `og:image`
+            // pointing at their own /og endpoint built with @vercel/og.
+            const svg = renderOgSvg({ title, description, siteName, theme, bg, fg, muted });
+            return new Response(svg, {
+                status: 200,
+                headers: {
+                    'Content-Type': 'image/svg+xml; charset=utf-8',
+                    'Cache-Control': 'public, max-age=86400, s-maxage=86400',
+                },
+            });
+        }
+        catch (err) {
+            return internalError(err, 'og.png');
+        }
+    });
     router.get('/seo/schema/:documentId', async (request, params) => {
         try {
             const auth = await requireAuth(request);
@@ -3180,6 +3758,28 @@ export function registerCMSRoutes(router) {
             const docData = doc.data && typeof doc.data === 'object' ? doc.data : {};
             const layout = await resolveLayout(pathParam, docData, matchedCollection);
             const { _layout: _omit, ...cleanData } = docData;
+            // Compose page meta + JSON-LD up front so client renderers (Next.js
+            // generateMetadata, plain SSR, MCP agents) don't have to re-derive
+            // schema, OG tags, and canonical URLs from raw doc data. Reads the
+            // collection's SEO config and the site-wide SEO defaults.
+            const cfg = getActuateConfig();
+            const collectionDef = cfg?.collections?.[matchedCollection] ?? null;
+            const { composePageMeta } = await import('../seo/page-meta.js');
+            const composed = composePageMeta({
+                doc: {
+                    id: doc.id,
+                    collection: doc.collection,
+                    slug: doc.slug ?? cleanData.slug ?? null,
+                    data: cleanData,
+                    publishedAt: doc.publishedAt,
+                    updatedAt: doc.updatedAt,
+                    structuredData: doc.structuredData ?? null,
+                    pageSettings: cleanData.pageSettings ?? null,
+                },
+                collection: collectionDef,
+                config: cfg ?? null,
+                siteUrl: siteUrlFromRequest(request),
+            });
             return json({
                 data: {
                     id: doc.id,
@@ -3187,8 +3787,18 @@ export function registerCMSRoutes(router) {
                     data: cleanData,
                     status: doc.status,
                     publishedAt: doc.publishedAt,
-                    structuredData: doc.structuredData,
+                    structuredData: composed.jsonLd ?? doc.structuredData,
+                },
+                meta: {
+                    title: composed.title,
+                    description: composed.description,
+                    canonical: composed.canonical,
+                    url: composed.url,
+                    tags: composed.meta,
+                    html: composed.metaHtml,
                 },
+                jsonLd: composed.jsonLd,
+                jsonLdHtml: composed.jsonLdHtml,
                 ...(Object.keys(layout).length > 0 ? { layout } : {}),
             });
         }
@@ -3667,6 +4277,9 @@ export function registerCMSRoutes(router) {
             const auth = await requireAuth(request);
             if (auth.error)
                 return auth.error;
+            const scopeErr = requireGlobalScope(auth.session, params.slug);
+            if (scopeErr)
+                return scopeErr;
             const ctx = buildActionContext(auth.session, db());
             const global = await getGlobal(params.slug, ctx);
             if (!global) {
@@ -3683,9 +4296,14 @@ export function registerCMSRoutes(router) {
             const auth = await requireAuth(request);
             if (auth.error)
                 return auth.error;
-            const roleErr = requireRole(auth.session.role, ADMIN_ROLES);
-            if (roleErr)
-                return roleErr;
+            const scopeErr = requireGlobalScope(auth.session, params.slug);
+            if (scopeErr)
+                return scopeErr;
+            if (!auth.session.apiKey) {
+                const roleErr = requireRole(auth.session.role, ADMIN_ROLES);
+                if (roleErr)
+                    return roleErr;
+            }
             const body = (await request.json());
             const ctx = buildActionContext(auth.session, db());
             const global = await updateGlobal(params.slug, body, ctx);
@@ -4463,9 +5081,9 @@ export function registerCMSRoutes(router) {
             const auth = await requireAuth(request);
             if (auth.error)
                 return auth.error;
-            const roleErr = requireRole(auth.session.role, ADMIN_ROLES);
-            if (roleErr)
-                return roleErr;
+            const scopeErr = requirePageBuilderScope(auth.session);
+            if (scopeErr)
+                return scopeErr;
             // Per-user rate limit. AI generation is the single most expensive
             // operation in the CMS — without this, a compromised admin account
             // can drain a provider key in minutes.
@@ -4535,9 +5153,9 @@ export function registerCMSRoutes(router) {
             const auth = await requireAuth(request);
             if (auth.error)
                 return auth.error;
-            const roleErr = requireRole(auth.session.role, ADMIN_ROLES);
-            if (roleErr)
-                return roleErr;
+            const scopeErr = requirePageBuilderScope(auth.session);
+            if (scopeErr)
+                return scopeErr;
             if (!(await checkRateLimitAsync(aiGenerateLimiter, `ai-block:${auth.session.userId}`))) {
                 return errorResponse('AI generation rate limit reached. Try again in an hour.', 429);
             }
@@ -4568,14 +5186,129 @@ export function registerCMSRoutes(router) {
             return internalError(err, 'page-builder generate-block');
         }
     });
+    /**
+     * One-shot page creation: run the AI page generator and persist the result
+     * as a new document in a single call. Designed for AI agents that want to
+     * create a complete page from a prompt without orchestrating two requests
+     * (generate, then create). Defaults to status=DRAFT so the human reviewer
+     * can polish before publishing.
+     */
+    router.post('/page-builder/create', async (request) => {
+        try {
+            const auth = await requireAuth(request);
+            if (auth.error)
+                return auth.error;
+            const scopeErr = requirePageBuilderScope(auth.session);
+            if (scopeErr)
+                return scopeErr;
+            // The create path also writes to a collection, so the API key must hold
+            // create scope on the destination collection (defaults to 'pages').
+            const body = (await request.json());
+            const targetCollection = body.collection ?? 'pages';
+            const collectionScopeErr = requireCollectionScope(auth.session, targetCollection, 'create');
+            if (collectionScopeErr)
+                return collectionScopeErr;
+            if (!body.prompt || typeof body.prompt !== 'string') {
+                return errorResponse('prompt is required', 400);
+            }
+            if (body.prompt.length > AI_PROMPT_MAX_CHARS) {
+                return errorResponse(`prompt exceeds ${AI_PROMPT_MAX_CHARS} character limit`, 400);
+            }
+            // Same rate-limit bucket as /generate — one create == one expensive LLM
+            // run, so it should count against the same hourly cap.
+            if (!(await checkRateLimitAsync(aiGenerateLimiter, `ai-gen:${auth.session.userId}`))) {
+                return errorResponse('AI generation rate limit reached. Try again in an hour.', 429);
+            }
+            const steps = Array.isArray(body.steps) && body.steps.length > 0
+                ? body.steps
+                : ['structure', 'content', 'seo', 'accessibility'];
+            const validSteps = ['structure', 'content', 'seo', 'accessibility'];
+            for (const s of steps) {
+                if (!validSteps.includes(s)) {
+                    return errorResponse(`Invalid step: ${s}. Valid steps: ${validSteps.join(', ')}`, 400);
+                }
+            }
+            let generatePage = null;
+            try {
+                const aiModule = await importAIPlugin();
+                generatePage = aiModule.generatePage;
+            }
+            catch {
+                return errorResponse('AI plugin is not installed. Install @actuate-media/plugin-ai to use page generation.', 501);
+            }
+            const result = await generatePage({
+                prompt: body.prompt,
+                template: body.template,
+                context: body.context,
+                steps,
+                tone: body.tone,
+            });
+            const tree = result?.tree;
+            if (!tree) {
+                return errorResponse('Page generation returned no tree', 502);
+            }
+            // Pull SEO metadata out of the generator output so we can store it on
+            // the document alongside the layout tree.
+            const seoStep = (result?.steps ?? []).find((s) => s.step === 'seo');
+            const meta = seoStep?.data ?? {};
+            const title = body.title ?? meta.title ?? meta.metaTitle ?? 'Untitled';
+            const slug = body.slug ??
+                title
+                    .toLowerCase()
+                    .replace(/[^a-z0-9]+/g, '-')
+                    .replace(/^-|-$/g, '');
+            // Determine final status — explicit body.status wins, then publish: true,
+            // then DRAFT.
+            const status = body.status === 'PUBLISHED' || body.publish === true ? 'PUBLISHED' : 'DRAFT';
+            const docPayload = {
+                title,
+                slug,
+                status,
+                layout: tree,
+                pageSettings: {
+                    metaTitle: meta.metaTitle ?? meta.title ?? title,
+                    metaDescription: meta.metaDescription ?? meta.description ?? '',
+                    ...(meta.canonical ? { canonical: meta.canonical } : {}),
+                    ...(meta.schemaType ? { schemaType: meta.schemaType } : {}),
+                },
+            };
+            const ctx = buildActionContext(auth.session, db());
+            const doc = await createDocument(targetCollection, docPayload, ctx);
+            await logEvent({
+                event: 'settings_changed',
+                userId: auth.session.userId,
+                details: {
+                    action: 'page_create_from_prompt',
+                    collection: targetCollection,
+                    documentId: doc?.id,
+                    prompt: redactSecrets(body.prompt).slice(0, 500),
+                    totalTokensUsed: result.totalTokensUsed,
+                    totalDurationMs: result.totalDurationMs,
+                },
+            });
+            return json({
+                data: {
+                    document: doc,
+                    generation: {
+                        steps: result.steps,
+                        totalTokensUsed: result.totalTokensUsed,
+                        totalDurationMs: result.totalDurationMs,
+                    },
+                },
+            }, 201);
+        }
+        catch (err) {
+            return internalError(err, 'page-builder create');
+        }
+    });
     router.post('/page-builder/audit-a11y', async (request) => {
         try {
             const auth = await requireAuth(request);
             if (auth.error)
                 return auth.error;
-            const roleErr = requireRole(auth.session.role, ADMIN_ROLES);
-            if (roleErr)
-                return roleErr;
+            const scopeErr = requirePageBuilderScope(auth.session);
+            if (scopeErr)
+                return scopeErr;
             const body = await request.json();
             const tree = body.tree;
             if (!tree || tree.type !== 'page') {
@@ -4593,9 +5326,9 @@ export function registerCMSRoutes(router) {
             const auth = await requireAuth(request);
             if (auth.error)
                 return auth.error;
-            const roleErr = requireRole(auth.session.role, ADMIN_ROLES);
-            if (roleErr)
-                return roleErr;
+            const scopeErr = requirePageBuilderScope(auth.session);
+            if (scopeErr)
+                return scopeErr;
             const body = await request.json();
             const tree = body.tree;
             if (!tree || tree.type !== 'page') {