@promptbook/cli 0.112.0-99 → 0.113.0-0

package/apps/agents-server/src/app/api/federated-agents/route.ts

@@ -24,7 +24,7 @@ export async function GET() {
             });
         }
 
-        const federatedServers = await getFederatedServers({ excludeHiddenCoreServer: true });
+        const federatedServers = await getFederatedServers();
 
         return NextResponse.json({
             federatedServers,

package/apps/agents-server/src/app/api/health/route.ts

@@ -0,0 +1,18 @@
+import { NextResponse } from 'next/server';
+
+/**
+ * Ensures the readiness route runs in the same runtime as the standalone server.
+ */
+export const runtime = 'nodejs';
+
+/**
+ * Prevents a cached response from hiding readiness failures during deployment handoff.
+ */
+export const dynamic = 'force-dynamic';
+
+/**
+ * Lightweight readiness endpoint used by standalone VPS pm2/nginx handoffs.
+ */
+export async function GET() {
+    return NextResponse.json({ status: 'ok' });
+}

package/apps/agents-server/src/app/api/images/[filename]/route.ts

@@ -1,15 +1,61 @@
 import { serializeError, computeHash } from '@promptbook-local/utils';
 import { NextRequest, NextResponse } from 'next/server';
+import { spaceTrim } from 'spacetrim';
 import { assertsError } from '../../../../../../../src/errors/assertsError';
 import type { LlmExecutionTools } from '../../../../../../../src/execution/LlmExecutionTools';
 import { getSingleLlmExecutionTools } from '../../../../../../../src/llm-providers/_multiple/getSingleLlmExecutionTools';
 import type { ImageGenerationModelRequirements } from '../../../../../../../src/types/ModelRequirements';
 import { string_url } from '../../../../../../../src/types/typeAliases';
-import { $provideCdnForServer } from '../../../../tools/$provideCdnForServer';
+import { $provideCdnForServer, resolveCdnPublicUrlForServer } from '../../../../tools/$provideCdnForServer';
 import { $provideExecutionToolsForServer } from '../../../../tools/$provideExecutionToolsForServer';
+import { $provideServer } from '../../../../tools/$provideServer';
 import { getGeneratedImageCdnKey } from '../../../../utils/cdn/utils/getGeneratedImageCdnKey';
 import { ensureGeneratedImage } from '../../../../utils/imageGeneration/ensureGeneratedImage';
 import { filenameToPrompt } from '../../../../utils/normalization/filenameToPrompt';
+import { guardPaidApiRequest } from '../../../../utils/paidApiRequestGuard';
+
+/**
+ * Allowlist of image generation models that may be requested by the caller.
+ *
+ * Image generation is one of the most expensive paid AI operations, so we
+ * reject any unknown model id before forwarding to the upstream provider.
+ */
+const ALLOWED_IMAGE_GENERATION_MODELS = new Set<string>([
+    'dall-e-3',
+    'dall-e-2',
+    'gpt-image-1',
+    'gemini-3-pro-image-preview',
+    'gemini-2.0-flash-preview-image-generation',
+]);
+
+/**
+ * Allowlist of image sizes accepted from the caller.
+ *
+ * Larger sizes cost more on every supported provider, so callers must pick a
+ * value from this fixed list instead of supplying arbitrary `${number}x${number}`
+ * strings.
+ */
+const ALLOWED_IMAGE_GENERATION_SIZES = new Set<NonNullable<ImageGenerationModelRequirements['size']>>([
+    '1024x1024',
+    '1792x1024',
+    '1024x1792',
+]);
+
+/**
+ * Allowlist of image quality values accepted from the caller.
+ */
+const ALLOWED_IMAGE_GENERATION_QUALITIES = new Set<NonNullable<ImageGenerationModelRequirements['quality']>>([
+    'standard',
+    'hd',
+]);
+
+/**
+ * Allowlist of image style values accepted from the caller.
+ */
+const ALLOWED_IMAGE_GENERATION_STYLES = new Set<NonNullable<ImageGenerationModelRequirements['style']>>([
+    'vivid',
+    'natural',
+]);
 
 /**
  * Chooses default image model from current provider metadata.
@@ -36,6 +82,63 @@ export async function GET(request: NextRequest, { params }: { params: Promise<{
             return NextResponse.json({ error: 'Filename is required' }, { status: 400 });
         }
 
+        const guard = await guardPaidApiRequest(request, 'IMAGE_GENERATION');
+        if (!guard.ok) {
+            return guard.response;
+        }
+
+        if (modelName !== null && !ALLOWED_IMAGE_GENERATION_MODELS.has(modelName)) {
+            return NextResponse.json(
+                {
+                    error: spaceTrim(`
+                        Requested image generation \`modelName\` is not allowed.
+
+                        **Allowed models:** ${Array.from(ALLOWED_IMAGE_GENERATION_MODELS).join(', ')}
+                    `),
+                },
+                { status: 400 },
+            );
+        }
+
+        if (size !== null && !ALLOWED_IMAGE_GENERATION_SIZES.has(size as never)) {
+            return NextResponse.json(
+                {
+                    error: spaceTrim(`
+                        Requested image \`size\` is not allowed.
+
+                        **Allowed sizes:** ${Array.from(ALLOWED_IMAGE_GENERATION_SIZES).join(', ')}
+                    `),
+                },
+                { status: 400 },
+            );
+        }
+
+        if (quality !== null && !ALLOWED_IMAGE_GENERATION_QUALITIES.has(quality as never)) {
+            return NextResponse.json(
+                {
+                    error: spaceTrim(`
+                        Requested image \`quality\` is not allowed.
+
+                        **Allowed values:** ${Array.from(ALLOWED_IMAGE_GENERATION_QUALITIES).join(', ')}
+                    `),
+                },
+                { status: 400 },
+            );
+        }
+
+        if (style !== null && !ALLOWED_IMAGE_GENERATION_STYLES.has(style as never)) {
+            return NextResponse.json(
+                {
+                    error: spaceTrim(`
+                        Requested image \`style\` is not allowed.
+
+                        **Allowed values:** ${Array.from(ALLOWED_IMAGE_GENERATION_STYLES).join(', ')}
+                    `),
+                },
+                { status: 400 },
+            );
+        }
+
         let attachments: unknown[] | undefined;
         if (attachmentsRaw) {
             try {
@@ -47,6 +150,7 @@ export async function GET(request: NextRequest, { params }: { params: Promise<{
 
         const prompt = filenameToPrompt(filename);
         const executionTools = await $provideExecutionToolsForServer();
+        const providedServer = await $provideServer();
         const llmTools = getSingleLlmExecutionTools(executionTools.llm) as LlmExecutionTools;
 
         if (!llmTools.callImageGenerationModel) {
@@ -89,7 +193,9 @@ export async function GET(request: NextRequest, { params }: { params: Promise<{
                 const imageBuffer = await imageResponse.arrayBuffer();
                 const buffer = Buffer.from(imageBuffer);
 
-                const cdn = $provideCdnForServer();
+                const cdn = $provideCdnForServer({
+                    cdnPublicUrl: resolveCdnPublicUrlForServer(providedServer.publicUrl),
+                });
                 const cdnKey = getGeneratedImageCdnKey({ filename, pathPrefix: cdn.pathPrefix });
                 await cdn.setItem(cdnKey, {
                     type: 'image/png',

package/apps/agents-server/src/app/api/internal/agent-runner-limits/route.ts

@@ -0,0 +1,52 @@
+import { NextResponse } from 'next/server';
+import { isTimingSafeEqualString } from '../../../../../../../src/utils/isTimingSafeEqualString';
+import { resolveUserChatWorkerInternalToken } from '@/src/utils/userChat';
+import { getLocalAgentRunnerLimits } from '@/src/utils/serverLimits';
+
+/**
+ * Loads local agent-runner limits for the foreground CLI worker.
+ */
+export async function GET(request: Request) {
+    return handleAgentRunnerLimitsRequest(request);
+}
+
+/**
+ * Loads local agent-runner limits for the foreground CLI worker.
+ */
+export async function POST(request: Request) {
+    return handleAgentRunnerLimitsRequest(request);
+}
+
+/**
+ * Validates authorization and returns the current local runner limits.
+ *
+ * @param request - Incoming route request.
+ * @returns Local runner limits response.
+ */
+async function handleAgentRunnerLimitsRequest(request: Request) {
+    if (!isAuthorizedInternalWorkerRequest(request)) {
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+    }
+
+    try {
+        return NextResponse.json(await getLocalAgentRunnerLimits());
+    } catch (error) {
+        return NextResponse.json(
+            {
+                error: error instanceof Error ? error.message : 'Failed to load local agent runner limits.',
+            },
+            { status: 500 },
+        );
+    }
+}
+
+/**
+ * Validates the shared internal worker token.
+ *
+ * @param request - Incoming route request.
+ * @returns `true` when the internal worker token matches.
+ */
+function isAuthorizedInternalWorkerRequest(request: Request): boolean {
+    const token = request.headers.get('x-user-chat-worker-token');
+    return isTimingSafeEqualString(token, resolveUserChatWorkerInternalToken());
+}

package/apps/agents-server/src/app/api/internal/user-chat-jobs/run/route.ts

@@ -1,10 +1,11 @@
-import { processNextLocalUserChatJob } from '@/src/utils/localChatRunner';
+import { processNextLocalUserChatJob, type ProcessLocalUserChatJobResult } from '@/src/utils/localChatRunner';
 import {
     recoverExpiredRunningUserChatJobs,
     resolveUserChatWorkerInternalToken,
     triggerUserChatJobWorker,
 } from '@/src/utils/userChat';
 import { after, NextResponse } from 'next/server';
+import { isTimingSafeEqualString } from '../../../../../../../../src/utils/isTimingSafeEqualString';
 
 /**
  * Allows one worker invocation to run for the platform maximum.
@@ -51,13 +52,13 @@ async function handleUserChatJobWorkerRequest(request: Request) {
         await recoverExpiredRunningUserChatJobs();
 
         const processedJob = await processNextLocalUserChatJob({ preferredJobId });
-        if (!processedJob) {
+        if (!processedJob || !shouldRequeueUserChatJobWorker(processedJob)) {
             return new Response(null, { status: 204 });
         }
 
         after(() =>
             triggerUserChatJobWorker({ origin }).catch((error) =>
-                console.error('[user-chat-job] requeue failed', error),
+                console.warn('[user-chat-job] requeue failed', error),
             ),
         );
 
@@ -73,6 +74,18 @@ async function handleUserChatJobWorkerRequest(request: Request) {
     }
 }
 
+/**
+ * Decides whether one worker outcome should immediately schedule another worker tick.
+ *
+ * Mutating outcomes may have exposed more queued work, while non-mutating `waiting`
+ * outcomes need the foreground fallback poll instead of a tight self-requeue loop.
+ *
+ * @private route helper
+ */
+function shouldRequeueUserChatJobWorker(processedJob: ProcessLocalUserChatJobResult): boolean {
+    return processedJob.didMutate;
+}
+
 /**
  * Validates the internal worker token.
  *
@@ -89,5 +102,5 @@ function isAuthorizedUserChatWorkerRequest(request: Request): boolean {
  */
 function isAuthorizedInternalWorkerRequest(request: Request): boolean {
     const token = request.headers.get('x-user-chat-worker-token');
-    return token === resolveUserChatWorkerInternalToken();
+    return isTimingSafeEqualString(token, resolveUserChatWorkerInternalToken());
 }

package/apps/agents-server/src/app/api/metadata/export/route.ts

@@ -0,0 +1,34 @@
+import { NextResponse } from 'next/server';
+import { createMetadataConfigurationExport } from '../../../../utils/metadataConfigurationTransfer';
+import { isUserAdmin } from '../../../../utils/isUserAdmin';
+
+/**
+ * This route is always dynamic because it depends on live DB state and auth.
+ */
+export const dynamic = 'force-dynamic';
+
+/**
+ * Serves the standalone server metadata JSON export.
+ *
+ * Returns `401` for non-admin callers.
+ */
+export async function GET() {
+    if (!(await isUserAdmin())) {
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+    }
+
+    try {
+        const { filename, payload } = await createMetadataConfigurationExport();
+
+        return new NextResponse(`${JSON.stringify(payload, null, 4)}\n`, {
+            headers: {
+                'Content-Type': 'application/json; charset=utf-8',
+                'Content-Disposition': `attachment; filename="${filename}"`,
+                'Cache-Control': 'no-store',
+            },
+        });
+    } catch (error) {
+        console.error('Metadata export error:', error);
+        return NextResponse.json({ error: 'Failed to export metadata.' }, { status: 500 });
+    }
+}

package/apps/agents-server/src/app/api/metadata/import/route.ts

@@ -0,0 +1,47 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { DatabaseError } from '../../../../../../../src/errors/DatabaseError';
+import { ParseError } from '../../../../../../../src/errors/ParseError';
+import { importMetadataConfigurationPayload } from '../../../../utils/metadataConfigurationTransfer';
+import { isUserAdmin } from '../../../../utils/isUserAdmin';
+
+/**
+ * This route is always dynamic because it depends on live DB state and auth.
+ */
+export const dynamic = 'force-dynamic';
+
+/**
+ * Imports standalone server metadata JSON.
+ *
+ * Returns `401` for non-admin callers.
+ */
+export async function POST(request: NextRequest) {
+    if (!(await isUserAdmin())) {
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+    }
+
+    let payload: unknown;
+
+    try {
+        payload = await request.json();
+    } catch {
+        return NextResponse.json({ error: 'Metadata import must be valid JSON.' }, { status: 400 });
+    }
+
+    try {
+        const isDefaultResetSkipped = request.nextUrl.searchParams.get('isDefaultResetSkipped') === 'true';
+        const importSummary = await importMetadataConfigurationPayload(payload, { isDefaultResetSkipped });
+        return NextResponse.json(importSummary);
+    } catch (error) {
+        if (error instanceof ParseError) {
+            return NextResponse.json({ error: error.message }, { status: 400 });
+        }
+
+        if (error instanceof DatabaseError) {
+            console.error('Metadata import database error:', error);
+            return NextResponse.json({ error: error.message }, { status: 500 });
+        }
+
+        console.error('Metadata import error:', error);
+        return NextResponse.json({ error: 'Failed to import metadata.' }, { status: 500 });
+    }
+}

package/apps/agents-server/src/app/api/metadata/route.ts

@@ -2,6 +2,7 @@ import { NextRequest, NextResponse } from 'next/server';
 import { keepUnused } from '../../../../../../src/utils/organization/keepUnused';
 import { $getTableName } from '../../../database/$getTableName';
 import { $provideSupabase } from '../../../database/$provideSupabase';
+import { invalidateMetadataCache } from '../../../database/getMetadata';
 import { validateMetadataValue } from '../../../database/metadataDefaults';
 import { isUserAdmin } from '../../../utils/isUserAdmin';
 
@@ -121,6 +122,7 @@ export async function POST(request: NextRequest) {
         return NextResponse.json({ error: error.message }, { status: 500 });
     }
 
+    invalidateMetadataCache();
     return NextResponse.json(data);
 }
 
@@ -152,6 +154,7 @@ export async function PUT(request: NextRequest) {
         return NextResponse.json({ error: error.message }, { status: 500 });
     }
 
+    invalidateMetadataCache();
     return NextResponse.json(data);
 }
 
@@ -179,5 +182,6 @@ export async function DELETE(request: NextRequest) {
         return NextResponse.json({ error: error.message }, { status: 500 });
     }
 
+    invalidateMetadataCache();
     return NextResponse.json({ success: true });
 }

package/apps/agents-server/src/app/api/openai/v1/audio/transcriptions/route.ts

@@ -1,6 +1,8 @@
 import { NextRequest, NextResponse } from 'next/server';
 import OpenAI from 'openai';
+import { spaceTrim } from 'spacetrim';
 import { getMetadata } from '@/src/database/getMetadata';
+import { guardPaidApiRequest } from '@/src/utils/paidApiRequestGuard';
 
 /**
  * Fallback file name used when the uploaded blob does not carry one.
@@ -12,6 +14,38 @@ const DEFAULT_AUDIO_TRANSCRIPTION_FILE_NAME = 'speech-recording.webm';
  */
 const DEFAULT_AUDIO_TRANSCRIPTION_MODEL_PRIORITY = ['gpt-4o-transcribe', 'gpt-4o-mini-transcribe', 'whisper-1'] as const;
 
+/**
+ * Allowlist of model identifiers accepted from the caller.
+ *
+ * Caller-supplied model names are forwarded to the paid OpenAI API, so we
+ * validate them against a fixed allowlist to prevent attackers from forcing
+ * the server to call expensive or experimental models that are not part of
+ * the supported transcription stack.
+ */
+const ALLOWED_AUDIO_TRANSCRIPTION_MODELS = new Set<string>(DEFAULT_AUDIO_TRANSCRIPTION_MODEL_PRIORITY);
+
+/**
+ * Maximum upload size that will be forwarded to OpenAI transcription.
+ *
+ * OpenAI's own limit is 25 MB; mirroring it here ensures we fail fast with a
+ * clear error before paying for an upload that the provider would reject.
+ */
+const MAX_AUDIO_TRANSCRIPTION_FILE_SIZE_BYTES = 25 * 1024 * 1024;
+
+/**
+ * Pattern matching ISO-639-1 language codes that OpenAI transcription accepts.
+ */
+const ISO_639_1_LANGUAGE_CODE_PATTERN = /^[a-z]{2}$/u;
+
+/**
+ * Maximum prompt length forwarded as transcription context.
+ *
+ * OpenAI rejects prompts longer than 224 tokens; we keep a conservative
+ * character cap that comfortably stays under that limit while preventing
+ * attackers from inflating request size.
+ */
+const MAX_AUDIO_TRANSCRIPTION_PROMPT_LENGTH = 800;
+
 /**
  * Proxy endpoint for OpenAI audio transcription
  *
@@ -33,17 +67,55 @@ export async function POST(request: NextRequest): Promise<NextResponse> {
             );
         }
 
+        const guard = await guardPaidApiRequest(request, 'AUDIO_TRANSCRIPTION');
+        if (!guard.ok) {
+            return guard.response;
+        }
+
         const formData = await request.formData();
         const file = formData.get('file') as File;
         const requestedModel = normalizeFormDataStringValue(formData.get('model'));
-        const language = normalizeFormDataStringValue(formData.get('language'));
-        const prompt = normalizeFormDataStringValue(formData.get('prompt'));
+        const language = resolveAudioTranscriptionLanguage(formData.get('language'));
+        const prompt = resolveAudioTranscriptionPrompt(formData.get('prompt'));
         const temperature = resolveAudioTranscriptionTemperature(formData.get('temperature'));
 
         if (!file) {
             return NextResponse.json({ error: { message: 'No file provided' } }, { status: 400 });
         }
 
+        if (file.size > MAX_AUDIO_TRANSCRIPTION_FILE_SIZE_BYTES) {
+            return NextResponse.json(
+                {
+                    error: {
+                        message: spaceTrim(`
+                            Uploaded audio file is too large.
+
+                            **Maximum allowed size:** ${Math.round(
+                                MAX_AUDIO_TRANSCRIPTION_FILE_SIZE_BYTES / (1024 * 1024),
+                            )} MB
+                            **Received:** ${(file.size / (1024 * 1024)).toFixed(2)} MB
+                        `),
+                    },
+                },
+                { status: 413 },
+            );
+        }
+
+        if (requestedModel !== undefined && !ALLOWED_AUDIO_TRANSCRIPTION_MODELS.has(requestedModel)) {
+            return NextResponse.json(
+                {
+                    error: {
+                        message: spaceTrim(`
+                            Requested transcription model is not allowed.
+
+                            **Allowed models:** ${Array.from(ALLOWED_AUDIO_TRANSCRIPTION_MODELS).join(', ')}
+                        `),
+                    },
+                },
+                { status: 400 },
+            );
+        }
+
         const openai = new OpenAI({
             apiKey: openAiApiKey,
         });
@@ -108,6 +180,43 @@ function normalizeFormDataStringValue(value: FormDataEntryValue | null): string
     return normalizedValue;
 }
 
+/**
+ * Validates the caller-supplied language hint against ISO-639-1.
+ *
+ * Forwarding arbitrary `language` strings to OpenAI is harmless cost-wise but
+ * widens the attack surface — invalid values can trigger model retries that
+ * silently inflate the bill. We mirror the documented constraint and drop
+ * anything that does not match.
+ */
+function resolveAudioTranscriptionLanguage(value: FormDataEntryValue | null): string | undefined {
+    const normalizedValue = normalizeFormDataStringValue(value);
+    if (!normalizedValue) {
+        return undefined;
+    }
+
+    if (!ISO_639_1_LANGUAGE_CODE_PATTERN.test(normalizedValue)) {
+        return undefined;
+    }
+
+    return normalizedValue.toLowerCase();
+}
+
+/**
+ * Validates and truncates the optional transcription prompt before sending it to OpenAI.
+ */
+function resolveAudioTranscriptionPrompt(value: FormDataEntryValue | null): string | undefined {
+    const normalizedValue = normalizeFormDataStringValue(value);
+    if (!normalizedValue) {
+        return undefined;
+    }
+
+    if (normalizedValue.length <= MAX_AUDIO_TRANSCRIPTION_PROMPT_LENGTH) {
+        return normalizedValue;
+    }
+
+    return normalizedValue.slice(0, MAX_AUDIO_TRANSCRIPTION_PROMPT_LENGTH);
+}
+
 /**
  * Parses optional transcription temperature from multipart form data.
  */

package/apps/agents-server/src/app/api/page-preview/check/route.ts

@@ -0,0 +1,49 @@
+import type { NextRequest } from 'next/server';
+import { NextResponse } from 'next/server';
+import { assertsError } from '../../../../../../../src/errors/assertsError';
+import { assertSafeUrl } from '../../../../utils/assertSafeUrl';
+import { getCurrentUser } from '../../../../utils/getCurrentUser';
+import { checkIfUrlCanBeEmbedded } from '../../../../utils/iframe/checkIfUrlCanBeEmbedded';
+
+/**
+ * Checks whether a given URL can be embedded in an iframe by inspecting
+ * `X-Frame-Options` and `Content-Security-Policy` `frame-ancestors` headers.
+ *
+ * Query parameters:
+ * - `url` — the fully-qualified HTTP(S) URL to check
+ *
+ * Returns `{ canEmbed: boolean }`.
+ *
+ * Requires authentication to prevent unauthenticated SSRF abuse.
+ * The destination URL is validated against private/internal IP ranges before fetching.
+ */
+export async function GET(request: NextRequest): Promise<NextResponse> {
+    const currentUser = await getCurrentUser();
+    if (!currentUser) {
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+    }
+
+    const url = request.nextUrl.searchParams.get('url');
+
+    if (!url) {
+        return NextResponse.json({ error: 'Missing required query parameter: url' }, { status: 400 });
+    }
+
+    // Guard against SSRF: reject private/internal IPs and non-HTTP(S) schemes
+    try {
+        assertSafeUrl(url);
+    } catch (error) {
+        assertsError(error);
+        return NextResponse.json({ error: error.message }, { status: 400 });
+    }
+
+    try {
+        const canEmbed = await checkIfUrlCanBeEmbedded(url);
+        return NextResponse.json({ canEmbed });
+    } catch (error) {
+        assertsError(error);
+        console.warn('Failed to check if URL can be embedded:', error.message);
+        // When the check fails, allow the iframe to try — the browser will handle it
+        return NextResponse.json({ canEmbed: true });
+    }
+}

package/apps/agents-server/src/app/api/page-preview/screenshot/route.ts

@@ -0,0 +1,64 @@
+import { $provideBrowserForServer } from '@/src/tools/$provideBrowserForServer';
+import { serializeError } from '@promptbook-local/utils';
+import type { NextRequest } from 'next/server';
+import { NextResponse } from 'next/server';
+import { assertsError } from '../../../../../../../src/errors/assertsError';
+import { assertSafeUrl } from '../../../../utils/assertSafeUrl';
+import { getCurrentUser } from '../../../../utils/getCurrentUser';
+
+/**
+ * Takes a screenshot of the given URL using a headless browser.
+ *
+ * Query parameters:
+ * - `url` — the fully-qualified HTTP(S) URL to screenshot
+ *
+ * Returns a PNG image.
+ *
+ * Requires authentication to prevent unauthenticated SSRF abuse.
+ * The destination URL is validated against private/internal IP ranges before fetching.
+ */
+export async function GET(request: NextRequest): Promise<NextResponse> {
+    const currentUser = await getCurrentUser();
+    if (!currentUser) {
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+    }
+
+    const url = request.nextUrl.searchParams.get('url');
+
+    if (!url) {
+        return NextResponse.json({ error: 'Missing required query parameter: url' }, { status: 400 });
+    }
+
+    // Guard against SSRF: reject private/internal IPs and non-HTTP(S) schemes
+    try {
+        assertSafeUrl(url);
+    } catch (error) {
+        assertsError(error);
+        return NextResponse.json({ error: error.message }, { status: 400 });
+    }
+
+    try {
+        const browserContext = await $provideBrowserForServer();
+        const page = await browserContext.newPage();
+
+        try {
+            await page.setViewportSize({ width: 1280, height: 800 });
+            await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 30_000 });
+            const screenshotBuffer = await page.screenshot({ type: 'png' });
+
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            return new NextResponse(new Blob([screenshotBuffer as any]), {
+                headers: {
+                    'Content-Type': 'image/png',
+                    'Cache-Control': 'public, max-age=300',
+                },
+            });
+        } finally {
+            await page.close().catch(() => {});
+        }
+    } catch (error) {
+        assertsError(error);
+        console.error('Error taking page screenshot:', error);
+        return NextResponse.json({ error: serializeError(error) }, { status: 500 });
+    }
+}