@actuate-media/cms-core 0.13.0 → 0.14.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() {
@@ -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,
@@ -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({
@@ -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,6 +1434,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 +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 },
@@ -1686,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);
@@ -2218,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) => {
@@ -3667,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) {
@@ -3683,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);
@@ -4463,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.
@@ -4535,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);
             }
@@ -4568,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') {
@@ -4593,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') {