@promptbook/cli 0.112.0-99 → 0.113.0-0

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

@@ -0,0 +1,442 @@
+import { spaceTrim } from 'spacetrim';
+import { DatabaseError } from '../../../../src/errors/DatabaseError';
+import { ParseError } from '../../../../src/errors/ParseError';
+import { normalizeToKebabCase } from '../../../../src/utils/normalization/normalize-to-kebab-case';
+import { removeEmojis } from '../../../../src/utils/normalization/removeEmojis';
+import { PROMPTBOOK_ENGINE_VERSION, type string_promptbook_version } from '../../../../src/version';
+import { $getTableName } from '../database/$getTableName';
+import { $provideSupabaseForServer } from '../database/$provideSupabaseForServer';
+import { invalidateMetadataCache } from '../database/getMetadata';
+import { getMetadataDefinition, metadataDefaults, validateMetadataValue } from '../database/metadataDefaults';
+import type { AgentsServerDatabase } from '../database/schema';
+
+/**
+ * Metadata key containing the human-readable server name.
+ */
+const SERVER_NAME_METADATA_KEY = 'SERVER_NAME';
+
+/**
+ * Fallback filename stem used when the server name cannot produce a safe name.
+ */
+const DEFAULT_METADATA_EXPORT_FILENAME_STEM = 'promptbook-agents-server';
+
+/**
+ * Filename suffix required for standalone metadata exports.
+ */
+const METADATA_EXPORT_FILENAME_SUFFIX = '.metadata.json';
+
+/**
+ * Minimal metadata row shape needed by import/export helpers.
+ */
+type MetadataConfigurationRow = Pick<
+    AgentsServerDatabase['public']['Tables']['Metadata']['Row'],
+    'key' | 'value' | 'note'
+>;
+
+/**
+ * Metadata row persisted during import.
+ */
+type MetadataConfigurationImportRow = {
+    /**
+     * Metadata key.
+     */
+    readonly key: string;
+
+    /**
+     * Metadata value to persist.
+     */
+    readonly value: string;
+
+    /**
+     * Metadata note to persist.
+     */
+    readonly note: string | null;
+};
+
+/**
+ * One entry inside the standalone metadata export JSON.
+ */
+export type MetadataConfigurationExportEntry = {
+    /**
+     * Metadata key.
+     */
+    readonly key: string;
+
+    /**
+     * Metadata value, omitted when it matches the built-in default.
+     */
+    readonly value?: string;
+
+    /**
+     * Metadata note, omitted when it matches the built-in default note.
+     */
+    readonly note?: string | null;
+};
+
+/**
+ * Standalone metadata export JSON payload.
+ */
+export type MetadataConfigurationExportPayload = {
+    /**
+     * Promptbook engine version that generated the export.
+     */
+    readonly promptbookVersion: string_promptbook_version;
+
+    /**
+     * Metadata entries with default fields omitted.
+     */
+    readonly metadata: ReadonlyArray<MetadataConfigurationExportEntry>;
+};
+
+/**
+ * Prepared metadata import plan before it touches the database.
+ */
+export type MetadataConfigurationImportPlan = {
+    /**
+     * Rows that should be inserted or updated.
+     */
+    readonly rowsToUpsert: ReadonlyArray<MetadataConfigurationImportRow>;
+
+    /**
+     * Default-backed keys absent from the import and therefore reset by deleting persisted rows.
+     */
+    readonly defaultKeysToReset: ReadonlyArray<string>;
+};
+
+/**
+ * Options controlling standalone metadata import behavior.
+ */
+export type MetadataConfigurationImportPlanOptions = {
+    /**
+     * When true, built-in metadata keys missing from the import payload keep their current persisted value.
+     */
+    readonly isDefaultResetSkipped?: boolean;
+};
+
+/**
+ * Summary returned after importing metadata.
+ */
+export type MetadataConfigurationImportSummary = {
+    /**
+     * Number of metadata rows inserted or updated from the import file.
+     */
+    readonly importedCount: number;
+
+    /**
+     * Number of built-in metadata keys reset to default.
+     */
+    readonly resetCount: number;
+};
+
+/**
+ * Full metadata export result used by the API route.
+ */
+export type MetadataConfigurationExportResult = {
+    /**
+     * Browser download filename.
+     */
+    readonly filename: string;
+
+    /**
+     * JSON payload to send to the browser.
+     */
+    readonly payload: MetadataConfigurationExportPayload;
+};
+
+/**
+ * Creates a standalone metadata export from the current server database.
+ *
+ * @returns Export filename and payload.
+ */
+export async function createMetadataConfigurationExport(): Promise<MetadataConfigurationExportResult> {
+    const metadataRows = await loadMetadataConfigurationRows();
+    const serverName = resolveServerNameFromMetadataRows(metadataRows);
+
+    return {
+        filename: createMetadataConfigurationExportFilename(serverName),
+        payload: createMetadataConfigurationExportPayload(metadataRows),
+    };
+}
+
+/**
+ * Imports standalone metadata JSON into the current server database.
+ *
+ * @param payload - Parsed JSON import payload.
+ * @param options - Import behavior options.
+ * @returns Import summary for the UI.
+ */
+export async function importMetadataConfigurationPayload(
+    payload: unknown,
+    options: MetadataConfigurationImportPlanOptions = {},
+): Promise<MetadataConfigurationImportSummary> {
+    const importPlan = createMetadataConfigurationImportPlan(payload, options);
+    const supabase = $provideSupabaseForServer();
+    const tableName = await $getTableName('Metadata');
+    const nowIso = new Date().toISOString();
+
+    if (importPlan.defaultKeysToReset.length > 0) {
+        const { error } = await supabase
+            .from(tableName)
+            .delete()
+            .in('key', [...importPlan.defaultKeysToReset]);
+
+        if (error) {
+            throw new DatabaseError(
+                spaceTrim(`
+                    Failed to reset metadata keys to their defaults.
+
+                    ${error.message}
+                `),
+            );
+        }
+    }
+
+    if (importPlan.rowsToUpsert.length > 0) {
+        const { error } = await supabase.from(tableName).upsert(
+            importPlan.rowsToUpsert.map((row) => ({
+                ...row,
+                updatedAt: nowIso,
+            })),
+            {
+                onConflict: 'key',
+            },
+        );
+
+        if (error) {
+            throw new DatabaseError(
+                spaceTrim(`
+                    Failed to import metadata configuration.
+
+                    ${error.message}
+                `),
+            );
+        }
+    }
+
+    invalidateMetadataCache();
+
+    return {
+        importedCount: importPlan.rowsToUpsert.length,
+        resetCount: importPlan.defaultKeysToReset.length,
+    };
+}
+
+/**
+ * Creates the standalone export payload from metadata rows.
+ *
+ * @param metadataRows - Persisted metadata rows.
+ * @param promptbookVersion - Promptbook version to include in the export.
+ * @returns JSON payload with default fields omitted.
+ */
+export function createMetadataConfigurationExportPayload(
+    metadataRows: ReadonlyArray<MetadataConfigurationRow>,
+    promptbookVersion: string_promptbook_version = PROMPTBOOK_ENGINE_VERSION,
+): MetadataConfigurationExportPayload {
+    const metadata = metadataRows
+        .flatMap((metadataRow) => {
+            const exportEntry = createMetadataConfigurationExportEntry(metadataRow);
+            return exportEntry ? [exportEntry] : [];
+        })
+        .sort((leftEntry, rightEntry) => leftEntry.key.localeCompare(rightEntry.key));
+
+    return {
+        promptbookVersion,
+        metadata,
+    };
+}
+
+/**
+ * Creates a browser-safe metadata export filename from the server name.
+ *
+ * @param serverName - Human-readable server name.
+ * @returns Kebab-case metadata export filename.
+ */
+export function createMetadataConfigurationExportFilename(serverName: string | null | undefined): string {
+    const normalizedServerName = normalizeToKebabCase(removeEmojis(serverName || ''));
+    const filenameStem = normalizedServerName || DEFAULT_METADATA_EXPORT_FILENAME_STEM;
+
+    return `${filenameStem}${METADATA_EXPORT_FILENAME_SUFFIX}`;
+}
+
+/**
+ * Validates and normalizes a standalone metadata import payload.
+ *
+ * @param payload - Parsed JSON import payload.
+ * @param options - Import behavior options.
+ * @returns Import plan ready for persistence.
+ */
+export function createMetadataConfigurationImportPlan(
+    payload: unknown,
+    options: MetadataConfigurationImportPlanOptions = {},
+): MetadataConfigurationImportPlan {
+    if (!payload || typeof payload !== 'object') {
+        throw new ParseError('Metadata import must be a JSON object.');
+    }
+
+    const payloadRecord = payload as Record<string, unknown>;
+
+    if (typeof payloadRecord.promptbookVersion !== 'string' || payloadRecord.promptbookVersion.trim() === '') {
+        throw new ParseError('Metadata import is missing `promptbookVersion`.');
+    }
+
+    if (!Array.isArray(payloadRecord.metadata)) {
+        throw new ParseError('Metadata import must contain a `metadata` array.');
+    }
+
+    const importedMetadataKeys = new Set<string>();
+    const rowsToUpsert = payloadRecord.metadata.map((rawMetadataEntry, index) =>
+        normalizeMetadataConfigurationImportEntry(rawMetadataEntry, index, importedMetadataKeys),
+    );
+    const defaultKeysToReset = options.isDefaultResetSkipped
+        ? []
+        : metadataDefaults
+              .map((metadataDefinition) => metadataDefinition.key)
+              .filter((metadataKey) => !importedMetadataKeys.has(metadataKey))
+              .sort((leftKey, rightKey) => leftKey.localeCompare(rightKey));
+
+    return {
+        rowsToUpsert: rowsToUpsert.sort((leftRow, rightRow) => leftRow.key.localeCompare(rightRow.key)),
+        defaultKeysToReset,
+    };
+}
+
+/**
+ * Loads all persisted metadata rows from the current server database.
+ *
+ * @returns Metadata rows sorted by key.
+ */
+async function loadMetadataConfigurationRows(): Promise<Array<MetadataConfigurationRow>> {
+    const supabase = $provideSupabaseForServer();
+    const tableName = await $getTableName('Metadata');
+    const { data, error } = await supabase.from(tableName).select('key, value, note').order('key');
+
+    if (error) {
+        throw new DatabaseError(
+            spaceTrim(`
+                Failed to load metadata configuration.
+
+                ${error.message}
+            `),
+        );
+    }
+
+    return ((data ?? []) as Array<MetadataConfigurationRow>).sort((leftRow, rightRow) =>
+        leftRow.key.localeCompare(rightRow.key),
+    );
+}
+
+/**
+ * Creates one export entry while omitting fields that match defaults.
+ *
+ * @param metadataRow - Persisted metadata row.
+ * @returns Export entry or `null` when both value and note are default.
+ */
+function createMetadataConfigurationExportEntry(
+    metadataRow: MetadataConfigurationRow,
+): MetadataConfigurationExportEntry | null {
+    const metadataDefinition = getMetadataDefinition(metadataRow.key);
+    const defaultNote = metadataDefinition?.note ?? null;
+    const isValueDefault = Boolean(metadataDefinition) && metadataRow.value === metadataDefinition!.value;
+    const isNoteDefault = metadataRow.note === defaultNote;
+    const exportEntry: MetadataConfigurationExportEntry = {
+        key: metadataRow.key,
+    };
+
+    if (!isValueDefault) {
+        (exportEntry as { value: string }).value = metadataRow.value;
+    }
+
+    if (!isNoteDefault) {
+        (exportEntry as { note: string | null }).note = metadataRow.note;
+    }
+
+    const isValueExported = Object.prototype.hasOwnProperty.call(exportEntry, 'value');
+    const isNoteExported = Object.prototype.hasOwnProperty.call(exportEntry, 'note');
+
+    if (!isValueExported && !isNoteExported) {
+        return null;
+    }
+
+    return exportEntry;
+}
+
+/**
+ * Normalizes one metadata import entry.
+ *
+ * @param rawMetadataEntry - Untrusted entry from the import JSON.
+ * @param index - Zero-based entry index for error messages.
+ * @param importedMetadataKeys - Mutable set used to reject duplicates and compute resets.
+ * @returns Metadata row ready for persistence.
+ */
+function normalizeMetadataConfigurationImportEntry(
+    rawMetadataEntry: unknown,
+    index: number,
+    importedMetadataKeys: Set<string>,
+): MetadataConfigurationImportRow {
+    if (!rawMetadataEntry || typeof rawMetadataEntry !== 'object') {
+        throw new ParseError(`Metadata entry #${index + 1} must be an object.`);
+    }
+
+    const rawMetadataEntryRecord = rawMetadataEntry as Record<string, unknown>;
+    const rawKey = rawMetadataEntryRecord.key;
+    if (typeof rawKey !== 'string' || rawKey.trim() === '') {
+        throw new ParseError(`Metadata entry #${index + 1} is missing a non-empty \`key\`.`);
+    }
+
+    const key = rawKey.trim();
+    const isDuplicateKey = importedMetadataKeys.has(key);
+    if (isDuplicateKey) {
+        throw new ParseError(`Metadata import contains duplicate key \`${key}\`.`);
+    }
+    importedMetadataKeys.add(key);
+
+    const metadataDefinition = getMetadataDefinition(key);
+    const isValueProvided = Object.prototype.hasOwnProperty.call(rawMetadataEntryRecord, 'value');
+    const isNoteProvided = Object.prototype.hasOwnProperty.call(rawMetadataEntryRecord, 'note');
+
+    if (isValueProvided && typeof rawMetadataEntryRecord.value !== 'string') {
+        throw new ParseError(`Metadata entry \`${key}\` has invalid \`value\`; expected a string.`);
+    }
+
+    if (isNoteProvided && typeof rawMetadataEntryRecord.note !== 'string' && rawMetadataEntryRecord.note !== null) {
+        throw new ParseError(`Metadata entry \`${key}\` has invalid \`note\`; expected a string or null.`);
+    }
+
+    if (!isValueProvided && !metadataDefinition) {
+        throw new ParseError(
+            spaceTrim(`
+                Metadata entry \`${key}\` is missing \`value\`.
+
+                Only built-in metadata keys can omit default values.
+            `),
+        );
+    }
+
+    const value = isValueProvided ? (rawMetadataEntryRecord.value as string) : metadataDefinition!.value;
+    const note = isNoteProvided ? (rawMetadataEntryRecord.note as string | null) : metadataDefinition?.note ?? null;
+    const validationError = validateMetadataValue(key, value);
+
+    if (validationError) {
+        throw new ParseError(validationError);
+    }
+
+    return {
+        key,
+        value,
+        note,
+    };
+}
+
+/**
+ * Resolves server name for the export filename from persisted metadata or defaults.
+ *
+ * @param metadataRows - Persisted metadata rows.
+ * @returns Server name candidate.
+ */
+function resolveServerNameFromMetadataRows(metadataRows: ReadonlyArray<MetadataConfigurationRow>): string {
+    const metadataRow = metadataRows.find((candidateRow) => candidateRow.key === SERVER_NAME_METADATA_KEY);
+    const defaultServerName =
+        getMetadataDefinition(SERVER_NAME_METADATA_KEY)?.value ?? DEFAULT_METADATA_EXPORT_FILENAME_STEM;
+
+    return metadataRow?.value.trim() || defaultServerName;
+}

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

@@ -0,0 +1,241 @@
+import { createHash } from 'crypto';
+import { NextRequest, NextResponse } from 'next/server';
+import { spaceTrim } from 'spacetrim';
+import { getRequestIp } from '../middleware/createMiddlewareRequestContext/getRequestIp';
+import { getSession } from './session';
+import { validateApiKey } from './validateApiKey';
+
+/**
+ * Categorizes the kind of paid third-party AI call a route performs.
+ *
+ * Each tier maps to its own per-identity sliding-window budget because the
+ * marginal cost (and therefore acceptable rate) differs significantly between
+ * speech-to-text, text-to-speech, and image generation.
+ *
+ * @private internal helper of paid AI proxy routes
+ */
+export type PaidApiRequestTier = 'AUDIO_TRANSCRIPTION' | 'TEXT_TO_SPEECH' | 'IMAGE_GENERATION';
+
+/**
+ * Per-tier rate limit definition.
+ *
+ * @private internal helper of paid AI proxy routes
+ */
+type PaidApiRateLimitDefinition = {
+    /**
+     * Maximum number of paid calls permitted per identity in a single window.
+     */
+    readonly maxRequestsPerWindow: number;
+    /**
+     * Length of the sliding window in milliseconds.
+     */
+    readonly windowMs: number;
+};
+
+/**
+ * Per-identity, per-tier sliding-window budgets for paid third-party calls.
+ *
+ * Numbers are intentionally generous for normal interactive UI use while still
+ * blocking sustained abuse — e.g. an attacker who has obtained a valid API key
+ * or signed-in account cannot loop millions of image generations.
+ *
+ * @private internal constant of paid AI proxy routes
+ */
+const PAID_API_RATE_LIMITS: Readonly<Record<PaidApiRequestTier, PaidApiRateLimitDefinition>> = {
+    AUDIO_TRANSCRIPTION: { maxRequestsPerWindow: 60, windowMs: 60_000 },
+    TEXT_TO_SPEECH: { maxRequestsPerWindow: 60, windowMs: 60_000 },
+    IMAGE_GENERATION: { maxRequestsPerWindow: 20, windowMs: 60_000 },
+};
+
+/**
+ * In-memory map of request timestamps keyed by `tier|identity`.
+ *
+ * In-memory state is intentional: the sliding window is a defense in depth on
+ * top of authentication, and we do not want to add a Redis dependency just for
+ * this guard. Operators who run multiple replicas should still configure a
+ * front-door rate limiter; this layer prevents single-process abuse.
+ *
+ * @private internal constant of paid AI proxy routes
+ */
+const PAID_API_REQUEST_TIMESTAMPS: Map<string, Array<number>> = new Map();
+
+/**
+ * Successful guard outcome describing the authenticated identity.
+ *
+ * @private internal helper of paid AI proxy routes
+ */
+export type PaidApiRequestGuardSuccess = {
+    readonly ok: true;
+    /**
+     * Stable identity key used for rate limiting and audit logs.
+     *
+     * Derived from (in order): the signed session username, the bearer API key
+     * hash, and finally the request IP for anonymous fallbacks (which should
+     * not happen because `authenticatedOnly` rejects them).
+     */
+    readonly identityKey: string;
+};
+
+/**
+ * Failure outcome containing the response that should be returned verbatim.
+ *
+ * @private internal helper of paid AI proxy routes
+ */
+export type PaidApiRequestGuardFailure = {
+    readonly ok: false;
+    readonly response: NextResponse;
+};
+
+/**
+ * Guard outcome returned by `guardPaidApiRequest`.
+ *
+ * @private internal helper of paid AI proxy routes
+ */
+export type PaidApiRequestGuardResult = PaidApiRequestGuardSuccess | PaidApiRequestGuardFailure;
+
+/**
+ * Combined authentication and per-identity rate-limit check for routes that
+ * proxy directly to paid third-party AI providers (OpenAI, ElevenLabs, ...).
+ *
+ * The guard enforces two invariants in a single place so that every paid
+ * endpoint stays consistent (DRY) and no new endpoint accidentally forgets
+ * authentication or rate limiting:
+ *
+ * 1. The caller must be authenticated via a signed session cookie or a valid
+ *    `Authorization: Bearer ptbk_...` API key.
+ * 2. The caller must stay within the per-tier sliding-window budget defined
+ *    in `PAID_API_RATE_LIMITS`.
+ *
+ * @param request - Incoming HTTP request.
+ * @param tier - Paid call category determining the applicable budget.
+ * @returns Either `{ ok: true, identityKey }` or `{ ok: false, response }`.
+ *
+ * @private internal helper of paid AI proxy routes
+ */
+export async function guardPaidApiRequest(
+    request: NextRequest,
+    tier: PaidApiRequestTier,
+): Promise<PaidApiRequestGuardResult> {
+    const apiKeyValidation = await validateApiKey(request);
+    if (!apiKeyValidation.isValid) {
+        return {
+            ok: false,
+            response: NextResponse.json(
+                {
+                    error: {
+                        message: apiKeyValidation.error || 'Authentication required',
+                        type: 'authentication_error',
+                    },
+                },
+                { status: 401 },
+            ),
+        };
+    }
+
+    const identityKey = await resolvePaidApiIdentityKey(request, apiKeyValidation.token);
+
+    const rateLimitCheck = checkPaidApiRateLimit(tier, identityKey);
+    if (!rateLimitCheck.isAllowed) {
+        return {
+            ok: false,
+            response: NextResponse.json(
+                {
+                    error: {
+                        message: spaceTrim(`
+                            Rate limit exceeded for paid AI proxy.
+
+                            **Tier:** \`${tier}\`
+                            **Limit:** ${rateLimitCheck.maxRequestsPerWindow} requests per ${Math.round(
+                            rateLimitCheck.windowMs / 1000,
+                        )} seconds.
+
+                            Try again in **${rateLimitCheck.retryAfterSeconds}** seconds.
+                        `),
+                        type: 'rate_limit_exceeded',
+                    },
+                },
+                {
+                    status: 429,
+                    headers: {
+                        'Retry-After': String(rateLimitCheck.retryAfterSeconds),
+                    },
+                },
+            ),
+        };
+    }
+
+    return { ok: true, identityKey };
+}
+
+/**
+ * Resolves a stable per-identity key used to bucket rate-limit counts.
+ *
+ * @param request - Incoming HTTP request.
+ * @param apiKeyToken - Optional bearer token recovered by `validateApiKey`.
+ * @returns Identity key prefixed with the source kind (`user:`, `apikey:`, or `ip:`).
+ *
+ * @private internal helper of `guardPaidApiRequest`
+ */
+async function resolvePaidApiIdentityKey(request: NextRequest, apiKeyToken: string | undefined): Promise<string> {
+    const session = await getSession();
+    if (session?.username) {
+        return `user:${session.username}`;
+    }
+
+    if (apiKeyToken) {
+        return `apikey:${createHash('sha256').update(apiKeyToken).digest('hex')}`;
+    }
+
+    return `ip:${getRequestIp(request)}`;
+}
+
+/**
+ * Sliding-window rate-limit check shared by all paid AI proxy tiers.
+ *
+ * @param tier - Paid call category determining the applicable budget.
+ * @param identityKey - Stable per-identity key from `resolvePaidApiIdentityKey`.
+ * @returns Decision describing whether the request is allowed and, if not, how long to wait.
+ *
+ * @private internal helper of `guardPaidApiRequest`
+ */
+function checkPaidApiRateLimit(
+    tier: PaidApiRequestTier,
+    identityKey: string,
+): {
+    readonly isAllowed: boolean;
+    readonly maxRequestsPerWindow: number;
+    readonly windowMs: number;
+    readonly retryAfterSeconds: number;
+} {
+    const { maxRequestsPerWindow, windowMs } = PAID_API_RATE_LIMITS[tier];
+    const bucketKey = `${tier}|${identityKey}`;
+    const now = Date.now();
+    const windowStart = now - windowMs;
+
+    const existingTimestamps = PAID_API_REQUEST_TIMESTAMPS.get(bucketKey) || [];
+    const recentTimestamps = existingTimestamps.filter((timestamp) => timestamp > windowStart);
+
+    if (recentTimestamps.length >= maxRequestsPerWindow) {
+        const oldestRelevantTimestamp = recentTimestamps[0]!;
+        const retryAfterMs = Math.max(1_000, oldestRelevantTimestamp + windowMs - now);
+        PAID_API_REQUEST_TIMESTAMPS.set(bucketKey, recentTimestamps);
+        return {
+            isAllowed: false,
+            maxRequestsPerWindow,
+            windowMs,
+            retryAfterSeconds: Math.ceil(retryAfterMs / 1_000),
+        };
+    }
+
+    recentTimestamps.push(now);
+    PAID_API_REQUEST_TIMESTAMPS.set(bucketKey, recentTimestamps);
+
+    return {
+        isAllowed: true,
+        maxRequestsPerWindow,
+        windowMs,
+        retryAfterSeconds: 0,
+    };
+}
+
+// Note: [🟢] Code for the Agents Server paid AI request guard should never be published into packages that could be imported into browser environment