@promptbook/cli 0.112.0-134 → 0.112.0-135

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

@@ -1,6 +1,8 @@
 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';
 
 /**
@@ -11,14 +13,30 @@ import { checkIfUrlCanBeEmbedded } from '../../../../utils/iframe/checkIfUrlCanB
  * - `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 });

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

@@ -3,6 +3,8 @@ 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.
@@ -11,23 +13,28 @@ import { assertsError } from '../../../../../../../src/errors/assertsError';
  * - `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 });
     }
 
-    let parsedUrl: URL;
+    // Guard against SSRF: reject private/internal IPs and non-HTTP(S) schemes
     try {
-        parsedUrl = new URL(url);
-    } catch {
-        return NextResponse.json({ error: 'Invalid URL' }, { status: 400 });
-    }
-
-    if (parsedUrl.protocol !== 'http:' && parsedUrl.protocol !== 'https:') {
-        return NextResponse.json({ error: 'Only http and https URLs are supported' }, { status: 400 });
+        assertSafeUrl(url);
+    } catch (error) {
+        assertsError(error);
+        return NextResponse.json({ error: error.message }, { status: 400 });
     }
 
     try {

package/apps/agents-server/src/app/api/team-agent-profile/route.ts

@@ -8,7 +8,10 @@ import {
     resolvePlaceholderImageUrl,
     resolveProfileImageUrl,
 } from '../../../../../../src/book-components/Chat/utils/loadAgentProfile';
+import { assertsError } from '../../../../../../src/errors/assertsError';
 import { isValidAgentUrl } from '../../../../../../src/utils/validators/url/isValidAgentUrl';
+import { assertSafeUrl } from '../../../utils/assertSafeUrl';
+import { getCurrentUser } from '../../../utils/getCurrentUser';
 
 /**
  * Response for team agent profile.
@@ -88,8 +91,17 @@ async function fetchAgentProfile(agentUrl: string, localServerUrl: string): Prom
  *
  * The client uses this to render tool call chips without relying on direct cross-origin requests
  * to the teammate agent.
+ *
+ * Requires authentication to prevent unauthenticated SSRF abuse and exfiltration of the
+ * internal team access token. The destination URL is validated against private/internal
+ * IP ranges before any outbound request is made.
  */
 export async function GET(request: Request) {
+    const currentUser = await getCurrentUser();
+    if (!currentUser) {
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+    }
+
     const requestUrl = new URL(request.url);
     const agentUrl = requestUrl.searchParams.get('url');
 
@@ -97,6 +109,14 @@ export async function GET(request: Request) {
         return NextResponse.json({ error: 'Invalid agent URL' }, { status: 400 });
     }
 
+    // Guard against SSRF: reject private/internal IPs and non-HTTP(S) schemes
+    try {
+        assertSafeUrl(agentUrl);
+    } catch (error) {
+        assertsError(error);
+        return NextResponse.json({ error: error.message }, { status: 400 });
+    }
+
     const normalizedUrl = agentUrl.replace(/\/$/, '');
     const profile = await fetchAgentProfile(normalizedUrl, requestUrl.origin);
 

package/apps/agents-server/src/components/AgentContextMenu/useAgentContextMenuItems.ts

@@ -300,6 +300,7 @@ function createManagementMenuItems(
  * @param formatText - Agent-aware text formatter.
  * @param handleRequestVisibilityUpdate - Visibility dialog action.
  * @param integrationLink - Generated integration link metadata.
+ * @param isAdmin - Whether the current user is an administrator (gates admin-only links).
  * @param isAuthenticated - Whether the current user is logged in.
  * @param shouldShowVisibilityAction - Whether visibility editing is available.
  * @param usageAnalyticsHref - Usage analytics URL for the current agent.
@@ -311,6 +312,7 @@ function createAdminMenuItems(
     formatText: FormatAgentContextMenuText,
     handleRequestVisibilityUpdate: () => Promise<void>,
     integrationLink: AgentContextMenuNavigationLink,
+    isAdmin: boolean,
     isAuthenticated: boolean,
     shouldShowVisibilityAction: boolean,
     usageAnalyticsHref: string,
@@ -333,26 +335,31 @@ function createAdminMenuItems(
         );
     }
 
+    if (isAdmin) {
+        menuItems.push(
+            {
+                type: 'link',
+                href: `/admin/chat-history?agentName=${encodeURIComponent(agentName)}`,
+                icon: MessageSquareIcon,
+                label: formatText('Chat History'),
+            },
+            {
+                type: 'link',
+                href: usageAnalyticsHref,
+                icon: BarChart3Icon,
+                label: formatText('Usage Analytics'),
+            },
+            {
+                type: 'link',
+                href: `/admin/chat-feedback?agentName=${encodeURIComponent(agentName)}`,
+                icon: MessageCircleQuestionIcon,
+                label: formatText('Chat Feedback'),
+            },
+            createDividerItem(),
+        );
+    }
+
     menuItems.push(
-        {
-            type: 'link',
-            href: `/admin/chat-history?agentName=${encodeURIComponent(agentName)}`,
-            icon: MessageSquareIcon,
-            label: formatText('Chat History'),
-        },
-        {
-            type: 'link',
-            href: usageAnalyticsHref,
-            icon: BarChart3Icon,
-            label: formatText('Usage Analytics'),
-        },
-        {
-            type: 'link',
-            href: `/admin/chat-feedback?agentName=${encodeURIComponent(agentName)}`,
-            icon: MessageCircleQuestionIcon,
-            label: formatText('Chat Feedback'),
-        },
-        createDividerItem(),
         {
             type: 'link',
             href: integrationLink.href,
@@ -437,6 +444,7 @@ export function useAgentContextMenuItems(props: AgentContextMenuBaseProps): Cont
         formatText,
         handleRequestVisibilityUpdate,
         integrationLink,
+        isAdmin,
         isAuthenticated,
         shouldShowVisibilityAction,
         usageAnalyticsHref,

package/apps/agents-server/src/constants/defaultAgentAvatarVisual.ts

@@ -53,7 +53,7 @@ export const DEFAULT_AGENT_AVATAR_VISUAL_METADATA_VALUES = DEFAULT_AGENT_AVATAR_
 export const DEFAULT_AGENT_AVATAR_VISUAL_METADATA_VALUE =
     DEFAULT_AGENT_AVATAR_VISUAL_METADATA_OPTIONS.find(
         ({ visualId }) => visualId === SHARED_DEFAULT_AGENT_AVATAR_VISUAL_ID,
-    )?.metadataValue || 'OCTOPUS3D3';
+    )?.metadataValue || 'OCTOPUS3D4';
 
 /**
  * Resolves one raw metadata value to a supported built-in avatar visual id.

package/apps/agents-server/src/database/migrations/2026-06-2700-default-agent-avatar-visual-octopus3d4.sql

@@ -0,0 +1,16 @@
+INSERT INTO "prefix_Metadata" ("key", "value", "note", "createdAt", "updatedAt")
+SELECT 'DEFAULT_AGENT_AVATAR_VISUAL',
+       'OCTOPUS3D4',
+       'Default built-in avatar visual used for agents without `META IMAGE` or `META AVATAR`. Allowed values: PIXEL_ART, OCTOPUS, OCTOPUS2, OCTOPUS3, OCTOPUS3D, OCTOPUS3D2, OCTOPUS3D3, OCTOPUS3D4, ASCII_OCTOPUS, MINECRAFT, MINECRAFT2, FRACTAL, ORB.',
+       NOW(),
+       NOW()
+WHERE NOT EXISTS (SELECT 1 FROM "prefix_Metadata" WHERE "key" = 'DEFAULT_AGENT_AVATAR_VISUAL');
+
+UPDATE "prefix_Metadata"
+SET "value" = CASE
+                  WHEN UPPER(COALESCE("value", '')) = 'OCTOPUS3D3' THEN 'OCTOPUS3D4'
+                  ELSE "value"
+              END,
+    "note" = 'Default built-in avatar visual used for agents without `META IMAGE` or `META AVATAR`. Allowed values: PIXEL_ART, OCTOPUS, OCTOPUS2, OCTOPUS3, OCTOPUS3D, OCTOPUS3D2, OCTOPUS3D3, OCTOPUS3D4, ASCII_OCTOPUS, MINECRAFT, MINECRAFT2, FRACTAL, ORB.',
+    "updatedAt" = NOW()
+WHERE "key" = 'DEFAULT_AGENT_AVATAR_VISUAL';

package/apps/agents-server/src/utils/agentOwnership.ts

@@ -69,9 +69,7 @@ export async function findOwnedAgentByIdentifier(userId: number, identifier: str
     const tableName = await $getTableName('Agent');
     const { data, error } = await supabase
         .from(tableName)
-        .select(
-            'id, agentName, createdAt, updatedAt, permanentId, agentHash, agentSource, agentProfile, promptbookEngineVersion, folderId, sortOrder, deletedAt, visibility, userId',
-        )
+        .select(OWNED_AGENT_ROW_COLUMNS)
         .eq('userId', userId as never)
         .or(buildAgentNameOrIdFilter(identifier))
         .limit(10);
@@ -80,7 +78,58 @@ export async function findOwnedAgentByIdentifier(userId: number, identifier: str
         throw new Error(`Failed to load agent "${identifier}": ${error.message}`);
     }
 
-    const rows = (data || []) as unknown as OwnedAgentRow[];
+    return pickAgentRowByIdentifier((data || []) as unknown as OwnedAgentRow[], identifier, 'for this owner');
+}
+
+/**
+ * Loads one agent by permanent id or agent name without an owner restriction.
+ *
+ * Owner-aware callers should use {@link findOwnedAgentByIdentifier}; this helper is reserved for administrative
+ * overrides where the caller has been independently authorized to read or mutate any agent.
+ *
+ * @param identifier - Permanent id or agent name.
+ * @returns Matching agent row or `null` when nothing matches.
+ */
+export async function findAgentByIdentifier(identifier: string): Promise<OwnedAgentRow | null> {
+    const supabase = $provideSupabaseForServer();
+    const tableName = await $getTableName('Agent');
+    const { data, error } = await supabase
+        .from(tableName)
+        .select(OWNED_AGENT_ROW_COLUMNS)
+        .or(buildAgentNameOrIdFilter(identifier))
+        .limit(10);
+
+    if (error) {
+        throw new Error(`Failed to load agent "${identifier}": ${error.message}`);
+    }
+
+    return pickAgentRowByIdentifier((data || []) as unknown as OwnedAgentRow[], identifier, 'across agents');
+}
+
+/**
+ * Database columns selected for every agent row exposed by ownership-aware helpers.
+ */
+const OWNED_AGENT_ROW_COLUMNS =
+    'id, agentName, createdAt, updatedAt, permanentId, agentHash, agentSource, agentProfile, promptbookEngineVersion, folderId, sortOrder, deletedAt, visibility, userId';
+
+/**
+ * Disambiguates a list of agent rows that all matched the same identifier.
+ *
+ * Resolution order:
+ * 1. Exact `permanentId` match — always preferred because permanent ids are unique.
+ * 2. Single `agentName` match — preserves the legacy lookup by human-readable name.
+ * 3. Single remaining row — accepts the only candidate found.
+ *
+ * @param rows - Candidate agent rows returned by Supabase.
+ * @param identifier - Identifier that was searched.
+ * @param ambiguityScope - Human-readable scope used in the ambiguity error message.
+ * @returns Best-matching row or `null` when no candidate matches.
+ */
+function pickAgentRowByIdentifier(
+    rows: OwnedAgentRow[],
+    identifier: string,
+    ambiguityScope: string,
+): OwnedAgentRow | null {
     if (rows.length === 0) {
         return null;
     }
@@ -100,7 +149,7 @@ export async function findOwnedAgentByIdentifier(userId: number, identifier: str
     }
 
     throw new Error(
-        `Agent identifier "${identifier}" is ambiguous for this owner. Use the stable \`permanentId\` returned by the API.`,
+        `Agent identifier "${identifier}" is ambiguous ${ambiguityScope}. Use the stable \`permanentId\` returned by the API.`,
     );
 }
 

package/apps/agents-server/src/utils/findAgentForCallerWriteAccess.ts

@@ -0,0 +1,36 @@
+import { findAgentByIdentifier, findOwnedAgentByIdentifier, type OwnedAgentRow } from './agentOwnership';
+import { getCurrentUser } from './getCurrentUser';
+import { isUserAdmin } from './isUserAdmin';
+
+/**
+ * Loads one agent for the current caller, enforcing ownership-or-admin write access.
+ *
+ * Resolution order:
+ * 1. Anonymous callers receive `null` so routes can return `403`.
+ * 2. Owners are matched via {@link findOwnedAgentByIdentifier} using the authenticated user id.
+ * 3. Administrators (resolved via {@link isUserAdmin}) fall through to {@link findAgentByIdentifier} so they can manage any agent — including legacy `ADMIN_PASSWORD` admins that have no database user id.
+ *
+ * @param identifier - Permanent id or agent name supplied by the route.
+ * @returns Matching agent row when the caller owns it or is an administrator, otherwise `null`.
+ *
+ * @private internal helper of Agents Server route handlers
+ */
+export async function findAgentForCallerWriteAccess(identifier: string): Promise<OwnedAgentRow | null> {
+    const [currentUser, isAdmin] = await Promise.all([getCurrentUser(), isUserAdmin()]);
+    if (!currentUser) {
+        return null;
+    }
+
+    if (typeof currentUser.id === 'number') {
+        const ownedAgent = await findOwnedAgentByIdentifier(currentUser.id, identifier);
+        if (ownedAgent) {
+            return ownedAgent;
+        }
+    }
+
+    if (!isAdmin) {
+        return null;
+    }
+
+    return findAgentByIdentifier(identifier);
+}