@promptbook/cli 0.112.0-134 → 0.112.0-136

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

@@ -1,9 +1,38 @@
 import { createOpenAiExecutionTools } from '@promptbook-local/openai';
+import { NextResponse } from 'next/server';
+import { spaceTrim } from 'spacetrim';
+
+/**
+ * Whether this development-only OpenAI smoke test endpoint is reachable.
+ *
+ * The route exists to verify that the configured `OPENAI_API_KEY` actually
+ * talks to OpenAI, so it must never be exposed in production where it would
+ * let any anonymous client drain the server's paid OpenAI credit by repeatedly
+ * calling this unauthenticated `GET` with attacker-controlled `message`.
+ *
+ * @private internal helper of `/api/chat`
+ */
+const IS_DEVELOPMENT_CHAT_TEST_ENDPOINT_ENABLED = process.env.NODE_ENV !== 'production';
 
 /**
  * Handles get.
  */
 export async function GET(request: Request) {
+    if (!IS_DEVELOPMENT_CHAT_TEST_ENDPOINT_ENABLED) {
+        return NextResponse.json(
+            {
+                error: {
+                    message: spaceTrim(`
+                        Endpoint \`/api/chat\` is a development-only OpenAI smoke test
+                        and is disabled in production.
+                    `),
+                    type: 'not_available_in_production',
+                },
+            },
+            { status: 404 },
+        );
+    }
+
     const { searchParams } = new URL(request.url);
     const message = searchParams.get('message') || 'Hello, who are you?';
 
@@ -21,13 +50,6 @@ export async function GET(request: Request) {
         content: message,
     });
 
-    /*
-    return new Response(JSON.stringify(response, null, 4), {
-        status: 200,
-        headers: { 'Content-Type': 'application/json' },
-    });
-    */
-
     return new Response(response.content, {
         status: 200,
         headers: { 'Content-Type': 'text/markdown' },

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

@@ -2,7 +2,7 @@ import { NextRequest, NextResponse } from 'next/server';
 import { $getTableName } from '../../../../database/$getTableName';
 import { $provideSupabase } from '../../../../database/$provideSupabase';
 import { convertToCsv } from '../../../../utils/convertToCsv';
-import { getCurrentUser } from '../../../../utils/getCurrentUser';
+import { isUserAdmin } from '../../../../utils/isUserAdmin';
 
 /**
  * Export chat feedback as CSV.
@@ -11,7 +11,7 @@ import { getCurrentUser } from '../../../../utils/getCurrentUser';
  * - agentName: filter by agent name (optional)
  */
 export async function GET(request: NextRequest) {
-    if (!(await getCurrentUser())) {
+    if (!(await isUserAdmin())) {
         return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
     }
 

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

@@ -1,7 +1,7 @@
 import { NextRequest, NextResponse } from 'next/server';
 import { $getTableName } from '../../../database/$getTableName';
 import { $provideSupabase } from '../../../database/$provideSupabase';
-import { getCurrentUser } from '../../../utils/getCurrentUser';
+import { isUserAdmin } from '../../../utils/isUserAdmin';
 
 /**
  * Size of default page.
@@ -58,7 +58,7 @@ function parseSortOrder(value: string | null): SortOrder {
  * - sortOrder: asc | desc (default: desc)
  */
 export async function GET(request: NextRequest) {
-    if (!(await getCurrentUser())) {
+    if (!(await isUserAdmin())) {
         return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
     }
 
@@ -145,7 +145,7 @@ export async function GET(request: NextRequest) {
  * - agentName: name of the agent whose feedback should be removed
  */
 export async function DELETE(request: NextRequest) {
-    if (!(await getCurrentUser())) {
+    if (!(await isUserAdmin())) {
         return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
     }
 

package/apps/agents-server/src/app/api/chat-history/[id]/route.ts

@@ -1,13 +1,13 @@
 import { NextRequest, NextResponse } from 'next/server';
 import { $getTableName } from '../../../../database/$getTableName';
 import { $provideSupabase } from '../../../../database/$provideSupabase';
-import { getCurrentUser } from '../../../../utils/getCurrentUser';
+import { isUserAdmin } from '../../../../utils/isUserAdmin';
 
 /**
  * Delete a single chat history entry by ID.
  */
 export async function DELETE(request: NextRequest, context: { params: Promise<{ id: string }> }) {
-    if (!(await getCurrentUser())) {
+    if (!(await isUserAdmin())) {
         return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
     }
 

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

@@ -2,7 +2,7 @@ import { NextRequest, NextResponse } from 'next/server';
 import { $getTableName } from '../../../../database/$getTableName';
 import { $provideSupabase } from '../../../../database/$provideSupabase';
 import { convertToCsv } from '../../../../utils/convertToCsv';
-import { getCurrentUser } from '../../../../utils/getCurrentUser';
+import { isUserAdmin } from '../../../../utils/isUserAdmin';
 
 /**
  * Export chat history as CSV.
@@ -11,7 +11,7 @@ import { getCurrentUser } from '../../../../utils/getCurrentUser';
  * - agentName: filter by agent name (optional)
  */
 export async function GET(request: NextRequest) {
-    if (!(await getCurrentUser())) {
+    if (!(await isUserAdmin())) {
         return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
     }
 

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

@@ -1,7 +1,7 @@
 import { NextRequest, NextResponse } from 'next/server';
 import { $getTableName } from '../../../database/$getTableName';
 import { $provideSupabase } from '../../../database/$provideSupabase';
-import { getCurrentUser } from '../../../utils/getCurrentUser';
+import { isUserAdmin } from '../../../utils/isUserAdmin';
 
 /**
  * Size of default page.
@@ -58,7 +58,7 @@ function parseSortOrder(value: string | null): SortOrder {
  * - sortOrder: asc | desc (default: desc)
  */
 export async function GET(request: NextRequest) {
-    if (!(await getCurrentUser())) {
+    if (!(await isUserAdmin())) {
         return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
     }
 
@@ -135,7 +135,7 @@ export async function GET(request: NextRequest) {
  * - agentName: name of the agent whose history should be removed
  */
 export async function DELETE(request: NextRequest) {
-    if (!(await getCurrentUser())) {
+    if (!(await isUserAdmin())) {
         return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
     }
 

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

@@ -1,10 +1,39 @@
+import { NextResponse } from 'next/server';
 import { OpenAI } from 'openai';
+import { spaceTrim } from 'spacetrim';
 import { forTime } from 'waitasecond';
 
+/**
+ * Whether this development-only OpenAI streaming smoke test endpoint is reachable.
+ *
+ * The route exists to verify that streaming chat completions work end-to-end,
+ * so it must never be exposed in production where it would let any anonymous
+ * client drain the server's paid OpenAI credit by repeatedly calling this
+ * unauthenticated `GET` with attacker-controlled `message`.
+ *
+ * @private internal helper of `/api/chat-streaming`
+ */
+const IS_DEVELOPMENT_CHAT_STREAMING_TEST_ENDPOINT_ENABLED = process.env.NODE_ENV !== 'production';
+
 /**
  * Handles get.
  */
 export async function GET(request: Request) {
+    if (!IS_DEVELOPMENT_CHAT_STREAMING_TEST_ENDPOINT_ENABLED) {
+        return NextResponse.json(
+            {
+                error: {
+                    message: spaceTrim(`
+                        Endpoint \`/api/chat-streaming\` is a development-only OpenAI smoke test
+                        and is disabled in production.
+                    `),
+                    type: 'not_available_in_production',
+                },
+            },
+            { status: 404 },
+        );
+    }
+
     const { searchParams } = new URL(request.url);
     const message = searchParams.get('message') || 'Hello, who are you?';
 

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

@@ -1,5 +1,8 @@
+import { NextRequest } from 'next/server';
+import { spaceTrim } from 'spacetrim';
 import { respondIfClientVersionIsOutdated } from '../../../../utils/clientVersionGuard';
 import { getMetadata } from '@/src/database/getMetadata';
+import { guardPaidApiRequest } from '@/src/utils/paidApiRequestGuard';
 import { textToSpeechText } from '../../../../utils/textToSpeechText';
 
 /**
@@ -37,6 +40,19 @@ const ELEVEN_LABS_API_KEY = process.env.ELEVEN_LABS_API_KEY;
  */
 const MAX_ELEVEN_LABS_TEXT_LENGTH = 4500;
 
+/**
+ * Pattern matching valid ElevenLabs voice identifiers.
+ *
+ * ElevenLabs voice IDs are 20-character alphanumeric strings (e.g.
+ * `21m00Tcm4TlvDq8ikWAM`). Validating with a strict allowlist prevents an
+ * attacker from injecting arbitrary path segments into the upstream URL
+ * (which is built by string interpolation below) and stops requests for
+ * unknown ids that would still bill our ElevenLabs account.
+ *
+ * @private
+ */
+const ELEVEN_LABS_VOICE_ID_PATTERN = /^[A-Za-z0-9]{15,40}$/u;
+
 /**
  * Handles the OPTIONS request from the chat for CORS / preflight.
  *
@@ -59,7 +75,7 @@ export function OPTIONS() {
  *
  * @private
  */
-export async function POST(request: Request) {
+export async function POST(request: NextRequest) {
     const versionMismatchResponse = respondIfClientVersionIsOutdated(request, 'json');
     if (versionMismatchResponse) {
         return versionMismatchResponse;
@@ -87,10 +103,31 @@ export async function POST(request: Request) {
         );
     }
 
+    const guard = await guardPaidApiRequest(request, 'TEXT_TO_SPEECH');
+    if (!guard.ok) {
+        return guard.response;
+    }
+
     const payload = (await request.json().catch(() => null)) as { text?: string; voiceId?: string } | null;
     const rawText = (payload?.text?.toString() ?? '').trim();
     const requestedVoiceId = payload?.voiceId?.toString().trim();
-    const voiceIdToUse = requestedVoiceId || ELEVEN_LABS_VOICE_ID;
+    const voiceIdToUse = resolveValidatedVoiceId(requestedVoiceId);
+
+    if (voiceIdToUse === null) {
+        return new Response(
+            JSON.stringify({
+                error: spaceTrim(`
+                    Invalid \`voiceId\`.
+
+                    ElevenLabs voice ids must be 15–40 alphanumeric characters.
+                `),
+            }),
+            {
+                status: 400,
+                headers: { 'Content-Type': 'application/json' },
+            },
+        );
+    }
 
     if (!rawText) {
         return new Response(
@@ -149,3 +186,24 @@ export async function POST(request: Request) {
         },
     });
 }
+
+/**
+ * Validates the caller-supplied voice id and falls back to the configured default.
+ *
+ * Returns `null` if the caller provided a voice id that does not match the
+ * ElevenLabs format. The default value comes from a trusted environment
+ * variable, so it is forwarded as-is without re-validation.
+ *
+ * @private internal helper of `POST /api/elevenlabs/tts`
+ */
+function resolveValidatedVoiceId(requestedVoiceId: string | undefined): string | null {
+    if (!requestedVoiceId) {
+        return ELEVEN_LABS_VOICE_ID;
+    }
+
+    if (!ELEVEN_LABS_VOICE_ID_PATTERN.test(requestedVoiceId)) {
+        return null;
+    }
+
+    return requestedVoiceId;
+}

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/images/[filename]/route.ts

@@ -1,5 +1,6 @@
 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';
@@ -11,6 +12,50 @@ 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.
@@ -37,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 {

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,46 @@
+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 importSummary = await importMetadataConfigurationPayload(payload);
+        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/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.
  */