@actuate-media/cms-core 0.12.0 → 0.14.0

package/dist/api/handlers.js

@@ -31,6 +31,9 @@ import { enforceSessionLimits } from '../security/session-limits.js';
 import { verifyReauth } from '../security/reauth.js';
 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() {
@@ -244,9 +247,7 @@ const ALLOWED_SORT_FIELDS = new Set([
 let _secretMissing = false;
 let _secretWarningLogged = false;
 function getSessionSecret() {
-    const secret = process.env.CMS_SECRET ??
-        process.env.CMS_SESSION_SECRET ??
-        globalThis.__actuateConfig?.secret;
+    const secret = process.env.CMS_SECRET ?? process.env.CMS_SESSION_SECRET ?? getActuateConfig()?.secret;
     if (!secret) {
         _secretMissing = true;
         if (!_secretWarningLogged) {
@@ -293,6 +294,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 +409,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,
@@ -417,9 +512,9 @@ const MAX_CONCURRENT_SESSIONS = 5;
 async function enforceSessionLimitsForUser(d, userId) {
     if (!hasModel(d, 'session'))
         return;
-    const config = globalThis.__actuateConfig?.auth ?? {};
-    const max = typeof config.maxConcurrentSessions === 'number' && config.maxConcurrentSessions > 0
-        ? config.maxConcurrentSessions
+    const auth = getActuateConfig()?.auth;
+    const max = typeof auth?.maxConcurrentSessions === 'number' && auth.maxConcurrentSessions > 0
+        ? auth.maxConcurrentSessions
         : MAX_CONCURRENT_SESSIONS;
     const active = await d.session.findMany({
         where: { userId, revokedAt: null, expiresAt: { gt: new Date() } },
@@ -434,7 +529,7 @@ async function enforceSessionLimitsForUser(d, userId) {
     }
 }
 function getAdminPath() {
-    return (process.env.ACTUATE_ADMIN_PATH ?? globalThis.__actuateConfig?.admin?.path ?? '/admin');
+    return process.env.ACTUATE_ADMIN_PATH ?? getActuateConfig()?.admin?.path ?? '/admin';
 }
 class ModelNotAvailableError extends Error {
     model;
@@ -505,7 +600,7 @@ export function registerCMSRoutes(router) {
     // OpenAPI spec
     // ---------------------------------------------------------------------------
     router.get('/openapi.json', async () => {
-        const config = globalThis.__actuateConfig;
+        const config = getActuateConfig();
         if (!config)
             return errorResponse('CMS not configured', 500);
         const spec = generateOpenAPISpec(config);
@@ -696,7 +791,7 @@ export function registerCMSRoutes(router) {
             if (!hasModel(d, 'user'))
                 return modelNotAvailable('user');
             const siteUrl = process.env.NEXT_PUBLIC_SITE_URL ?? new URL(request.url).origin;
-            const cmsConfig = globalThis.__actuateConfig;
+            const cmsConfig = getActuateConfig();
             await createPasswordReset(d, email.toLowerCase().trim(), {
                 siteUrl,
                 platform: cmsConfig?.platform,
@@ -1077,7 +1172,7 @@ export function registerCMSRoutes(router) {
             };
             const cookies = parseCookieHeader(request.headers.get('cookie') ?? '');
             const expectedNonce = cookies['actuate_oauth_nonce'] ?? null;
-            const cmsConfig = globalThis.__actuateConfig;
+            const cmsConfig = getActuateConfig();
             const allowSelfSignup = cmsConfig?.auth?.oauth?.allowSelfSignup === true;
             const result = await handleOAuthCallback(provider, code, stateToken, oauthProviders, secret, db(), { expectedNonce, allowSelfSignup });
             const isProduction = process.env.NODE_ENV === 'production';
@@ -1118,6 +1213,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({
@@ -1130,7 +1228,7 @@ export function registerCMSRoutes(router) {
                 locale: url.searchParams.get('locale') ?? undefined,
                 folderId: url.searchParams.get('folderId') ?? undefined,
             }, ctx);
-            const collectionConfig = globalThis.__actuateConfig?.collections?.[params.slug];
+            const collectionConfig = getActuateConfig()?.collections?.[params.slug];
             const fields = collectionConfig?.fields;
             if (fields && result.docs.length > 0) {
                 const user = { id: auth.session.userId, role: auth.session.role };
@@ -1155,6 +1253,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 +1276,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 +1298,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 +1320,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 +1387,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,7 +1434,24 @@ export function registerCMSRoutes(router) {
             const auth = await requireAuth(request);
             if (auth.error)
                 return auth.error;
-            const contentLength = parseInt(request.headers.get('content-length') ?? '0', 10);
+            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
+            // memory) are rejected up front. The multipart envelope is always
+            // larger than the underlying file, so checking against MAX_UPLOAD_BYTES
+            // here is a safe upper bound — a 50 MB file cannot fit inside a 50 MB
+            // request body.
+            const contentLengthHeader = request.headers.get('content-length');
+            if (!contentLengthHeader) {
+                return errorResponse('Content-Length header is required for uploads (chunked encoding is not supported)', 411);
+            }
+            const contentLength = parseInt(contentLengthHeader, 10);
+            if (!Number.isFinite(contentLength) || contentLength <= 0) {
+                return errorResponse('Invalid Content-Length header', 400);
+            }
             if (contentLength > MAX_UPLOAD_BYTES) {
                 return errorResponse('File exceeds maximum size of 50MB', 413);
             }
@@ -1343,7 +1464,11 @@ export function registerCMSRoutes(router) {
             const originalFilename = file.name;
             const contentType = file.type;
             const originalSize = file.size;
-            if (originalSize > 50 * 1024 * 1024) {
+            // Belt-and-braces: even with the header check above, re-validate the
+            // *actual* file size after parsing in case the multipart envelope
+            // disagreed with the header. This must come BEFORE any further
+            // processing (magic byte read, SVG sanitization, blob upload).
+            if (originalSize > MAX_UPLOAD_BYTES) {
                 return errorResponse('File exceeds maximum size of 50MB', 413);
             }
             // 1. Block file types that aren't on our allowlist outright.
@@ -1643,9 +1768,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 },
@@ -1668,9 +1798,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);
@@ -1728,7 +1863,7 @@ export function registerCMSRoutes(router) {
             const session = await extractSession(request);
             if (!session)
                 return errorResponse('Unauthorized', 401);
-            const coreVersion = globalThis.__actuateCoreVersion ?? '0.1.0';
+            const coreVersion = getActuateCoreVersion() ?? '0.1.0';
             const info = await checkForUpdates(coreVersion);
             const saved = await getUpdateConfig();
             return json({
@@ -1831,7 +1966,7 @@ export function registerCMSRoutes(router) {
             if (!owner || !repo) {
                 return errorResponse('GitHub repository not configured. Go to Settings > Updates to add one.', 400);
             }
-            const coreVersion = globalThis.__actuateCoreVersion ?? '0.1.0';
+            const coreVersion = getActuateCoreVersion() ?? '0.1.0';
             const result = await createUpgradePR({
                 owner,
                 repo,
@@ -1916,8 +2051,43 @@ export function registerCMSRoutes(router) {
         'webhookDeliveryLog',
     ];
     router.get('/health', async () => {
-        const cmsVersion = globalThis.__actuateCoreVersion ?? '0.0.0';
+        const cmsVersion = getActuateCoreVersion() ?? '0.0.0';
         const models = {};
+        // M6: validate the *shape* of every well-known env var, not just presence.
+        // A 31-char CMS_SECRET or a placeholder CMS_ENCRYPTION_KEY now reports as
+        // a hard error here instead of crashing at the first runtime use.
+        //
+        // Bugbot review (PR #43): CMS_SECRET has *three* legitimate sources —
+        // `process.env.CMS_SECRET`, the legacy `process.env.CMS_SESSION_SECRET`,
+        // and `getActuateConfig()?.secret` (config-file path documented in the
+        // missing-secret warning message itself). `getSessionSecret()` checks all
+        // three; `isSecretMissing()` consequently returns false when any of them
+        // is set. If `validateEnvShape()` only inspected `process.env.CMS_SECRET`,
+        // a config-file deploy would get `secretConfigured: true` AND
+        // `status: "unhealthy"` simultaneously — a contradiction that would trip
+        // monitoring / load-balancer health probes for no real fault. We pass a
+        // wrapped `EnvSource` so the validator sees what the runtime would
+        // actually resolve.
+        const env = validateEnvShape({
+            get(name) {
+                if (name === 'CMS_SECRET') {
+                    return (process.env.CMS_SECRET ?? process.env.CMS_SESSION_SECRET ?? getActuateConfig()?.secret);
+                }
+                return process.env[name];
+            },
+        });
+        // Derive overall status from env validation + model availability + DB
+        // connection. `env.errorCount > 0` outranks every model/DB issue because
+        // it represents a *deployment* misconfig the operator must fix before any
+        // request will succeed — pretending the deploy is "degraded" when secrets
+        // are malformed defeats the M6 goal of catching that at /health time.
+        function deriveStatus(dbConnected, allModelsAvailable) {
+            if (env.errorCount > 0)
+                return 'unhealthy';
+            if (allModelsAvailable && dbConnected)
+                return 'healthy';
+            return 'degraded';
+        }
         let d;
         try {
             d = db();
@@ -1927,9 +2097,10 @@ export function registerCMSRoutes(router) {
                 models[m] = false;
             return json({
                 data: {
-                    status: 'degraded',
+                    status: deriveStatus(false, false),
                     version: cmsVersion,
                     secretConfigured: !isSecretMissing(),
+                    env,
                     models,
                     databaseConnected: false,
                 },
@@ -1955,11 +2126,13 @@ export function registerCMSRoutes(router) {
             }
         }
         const allAvailable = Object.values(models).every(Boolean);
+        const status = deriveStatus(dbConnected, allAvailable);
         return json({
             data: {
-                status: allAvailable ? 'healthy' : 'degraded',
+                status,
                 version: cmsVersion,
                 secretConfigured: !isSecretMissing(),
+                env,
                 models,
                 databaseConnected: dbConnected,
             },
@@ -2162,6 +2335,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) => {
@@ -2330,9 +2660,9 @@ export function registerCMSRoutes(router) {
             });
             (async () => {
                 try {
-                    const config = globalThis.__actuateConfig;
-                    const hooks = [...(config?.plugins?.forms?.hooks ?? []), ...(config?._pluginHooks ?? [])];
-                    const formHooks = hooks.filter((h) => h.event === 'afterCreate:form-submissions');
+                    const config = getActuateConfig();
+                    const hooks = (config?._pluginHooks ?? []);
+                    const formHooks = hooks.filter((h) => h?.event === 'afterCreate:form-submissions');
                     for (const hook of formHooks) {
                         await hook.handler({ formId, data: body.fields });
                     }
@@ -2405,7 +2735,7 @@ export function registerCMSRoutes(router) {
                 if (!['http:', 'https:'].includes(destUrl.protocol)) {
                     return errorResponse('Invalid destination URL', 400);
                 }
-                const cmsConfig = globalThis.__actuateConfig;
+                const cmsConfig = getActuateConfig();
                 const allowed = new Set([
                     ...(Array.isArray(cmsConfig?.redirects?.allowedExternalHosts)
                         ? cmsConfig.redirects.allowedExternalHosts.map((h) => h.toLowerCase())
@@ -2967,7 +3297,7 @@ export function registerCMSRoutes(router) {
     // ---------------------------------------------------------------------------
     const MAX_RESOLVE_DEPTH = 10;
     async function resolveLayout(path, docData, matchedCollection) {
-        const config = globalThis.__actuateConfig;
+        const config = getActuateConfig();
         const layoutConfig = config?.layout;
         if (!layoutConfig?.regions)
             return {};
@@ -3063,7 +3393,7 @@ export function registerCMSRoutes(router) {
                 .replace(/^\/|\/$/g, '')
                 .split('/')
                 .filter(Boolean);
-            const configCollections = globalThis.__actuateConfig?.collections ?? {};
+            const configCollections = getActuateConfig()?.collections ?? {};
             const collectionDefs = Object.values(configCollections);
             let matchedCollection = null;
             let docSlug = null;
@@ -3579,7 +3909,7 @@ export function registerCMSRoutes(router) {
     router.get('/public/globals/:slug', async (_request, params) => {
         try {
             const slug = params.slug;
-            const globalConfig = globalThis.__actuateConfig?.globals?.[slug];
+            const globalConfig = getActuateConfig()?.globals?.[slug];
             if (!globalConfig) {
                 return errorResponse('Global not found', 404);
             }
@@ -3611,6 +3941,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) {
@@ -3627,9 +3960,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);
@@ -4407,9 +4745,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.
@@ -4479,9 +4817,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);
             }
@@ -4512,14 +4850,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') {
@@ -4537,9 +4990,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') {