create-nextblock 0.2.77 → 0.8.0

package/templates/nextblock-template/lib/ai-key-crypto.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  decryptOpenRouterApiKey,
+  encryptOpenRouterApiKey,
+  getMaskedOpenRouterKey,
+  getOpenRouterKeyEnvelopeStatus,
+} from './ai-key-crypto';
+
+describe('Cortex AI OpenRouter key crypto', () => {
+  const apiKey = 'sk-or-v1-test-secret-1234567890';
+  const encryptionSecret = 'local-test-encryption-secret';
+
+  it('encrypts and decrypts an OpenRouter key', () => {
+    const encryptedKey = encryptOpenRouterApiKey({
+      apiKey,
+      encryptionSecret,
+      now: new Date('2026-04-27T12:00:00.000Z'),
+    });
+
+    expect(decryptOpenRouterApiKey({ encryptedKey, encryptionSecret })).toBe(apiKey);
+  });
+
+  it('does not store the raw key in the encrypted payload', () => {
+    const encryptedKey = encryptOpenRouterApiKey({
+      apiKey,
+      encryptionSecret,
+    });
+
+    expect(JSON.stringify(encryptedKey)).not.toContain(apiKey);
+    expect(encryptedKey.last4).toBe('7890');
+  });
+
+  it('fails safely when the encryption secret is wrong or missing', () => {
+    const encryptedKey = encryptOpenRouterApiKey({
+      apiKey,
+      encryptionSecret,
+    });
+
+    expect(() =>
+      decryptOpenRouterApiKey({
+        encryptedKey,
+        encryptionSecret: 'wrong-secret',
+      })
+    ).toThrow('Failed to decrypt stored OpenRouter key.');
+
+    expect(() =>
+      encryptOpenRouterApiKey({
+        apiKey,
+        encryptionSecret: '',
+      })
+    ).toThrow('CORTEX_AI_ENCRYPTION_KEY is required');
+  });
+
+  it('reports masked stored key status', () => {
+    const encryptedKey = encryptOpenRouterApiKey({
+      apiKey,
+      encryptionSecret,
+      now: new Date('2026-04-27T12:00:00.000Z'),
+    });
+
+    expect(getMaskedOpenRouterKey(encryptedKey.last4)).toBe('**** 7890');
+    expect(getOpenRouterKeyEnvelopeStatus(encryptedKey)).toEqual({
+      hasStoredKey: true,
+      last4: '7890',
+      maskedKey: '**** 7890',
+      updatedAt: '2026-04-27T12:00:00.000Z',
+    });
+  });
+});

package/templates/nextblock-template/lib/ai-key-crypto.ts

@@ -0,0 +1,132 @@
+import { createCipheriv, createDecipheriv, createHash, randomBytes } from 'crypto';
+
+export const CORTEX_AI_KEY_ALGORITHM = 'aes-256-gcm';
+export const CORTEX_AI_KEY_ENVELOPE_VERSION = 1;
+
+export type EncryptedOpenRouterKeyEnvelope = {
+  algorithm: typeof CORTEX_AI_KEY_ALGORITHM;
+  authTag: string;
+  ciphertext: string;
+  iv: string;
+  last4: string;
+  updatedAt: string;
+  version: typeof CORTEX_AI_KEY_ENVELOPE_VERSION;
+};
+
+function normalizeSecret(secret: string) {
+  const normalizedSecret = secret.trim();
+
+  if (!normalizedSecret) {
+    throw new Error('CORTEX_AI_ENCRYPTION_KEY is required to manage stored OpenRouter keys.');
+  }
+
+  return createHash('sha256').update(normalizedSecret).digest();
+}
+
+function assertEnvelope(value: unknown): EncryptedOpenRouterKeyEnvelope {
+  if (!value || typeof value !== 'object') {
+    throw new Error('Invalid encrypted OpenRouter key payload.');
+  }
+
+  const envelope = value as Partial<EncryptedOpenRouterKeyEnvelope>;
+
+  if (
+    envelope.algorithm !== CORTEX_AI_KEY_ALGORITHM ||
+    envelope.version !== CORTEX_AI_KEY_ENVELOPE_VERSION ||
+    typeof envelope.authTag !== 'string' ||
+    typeof envelope.ciphertext !== 'string' ||
+    typeof envelope.iv !== 'string'
+  ) {
+    throw new Error('Invalid encrypted OpenRouter key payload.');
+  }
+
+  return {
+    algorithm: envelope.algorithm,
+    authTag: envelope.authTag,
+    ciphertext: envelope.ciphertext,
+    iv: envelope.iv,
+    last4: typeof envelope.last4 === 'string' ? envelope.last4 : '',
+    updatedAt: typeof envelope.updatedAt === 'string' ? envelope.updatedAt : '',
+    version: envelope.version,
+  };
+}
+
+export function getMaskedOpenRouterKey(last4?: string | null) {
+  const normalizedLast4 = (last4 || '').trim();
+  return normalizedLast4 ? `**** ${normalizedLast4}` : 'Stored key';
+}
+
+export function encryptOpenRouterApiKey(params: {
+  apiKey: string;
+  encryptionSecret: string;
+  now?: Date;
+}): EncryptedOpenRouterKeyEnvelope {
+  const apiKey = params.apiKey.trim();
+
+  if (!apiKey) {
+    throw new Error('OpenRouter API key is required.');
+  }
+
+  const key = normalizeSecret(params.encryptionSecret);
+  const iv = randomBytes(12);
+  const cipher = createCipheriv(CORTEX_AI_KEY_ALGORITHM, key, iv);
+  const ciphertext = Buffer.concat([
+    cipher.update(apiKey, 'utf8'),
+    cipher.final(),
+  ]);
+  const authTag = cipher.getAuthTag();
+
+  return {
+    algorithm: CORTEX_AI_KEY_ALGORITHM,
+    authTag: authTag.toString('base64'),
+    ciphertext: ciphertext.toString('base64'),
+    iv: iv.toString('base64'),
+    last4: apiKey.slice(-4),
+    updatedAt: (params.now || new Date()).toISOString(),
+    version: CORTEX_AI_KEY_ENVELOPE_VERSION,
+  };
+}
+
+export function decryptOpenRouterApiKey(params: {
+  encryptedKey: unknown;
+  encryptionSecret: string;
+}) {
+  const envelope = assertEnvelope(params.encryptedKey);
+  const key = normalizeSecret(params.encryptionSecret);
+
+  try {
+    const decipher = createDecipheriv(
+      CORTEX_AI_KEY_ALGORITHM,
+      key,
+      Buffer.from(envelope.iv, 'base64')
+    );
+    decipher.setAuthTag(Buffer.from(envelope.authTag, 'base64'));
+
+    return Buffer.concat([
+      decipher.update(Buffer.from(envelope.ciphertext, 'base64')),
+      decipher.final(),
+    ]).toString('utf8');
+  } catch {
+    throw new Error('Failed to decrypt stored OpenRouter key.');
+  }
+}
+
+export function getOpenRouterKeyEnvelopeStatus(value: unknown) {
+  try {
+    const envelope = assertEnvelope(value);
+
+    return {
+      hasStoredKey: true,
+      last4: envelope.last4 || null,
+      maskedKey: getMaskedOpenRouterKey(envelope.last4),
+      updatedAt: envelope.updatedAt || null,
+    };
+  } catch {
+    return {
+      hasStoredKey: false,
+      last4: null,
+      maskedKey: null,
+      updatedAt: null,
+    };
+  }
+}

package/templates/nextblock-template/lib/ai-model-catalog.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { listCortexAiCompatibleOpenRouterModels } from './ai-model-catalog';
+
+describe('Cortex AI OpenRouter model catalog', () => {
+  it('fetches and filters compatible OpenRouter models', async () => {
+    const fetch = vi.fn(async () =>
+      new Response(
+        JSON.stringify({
+          data: [
+            {
+              architecture: { output_modalities: ['text'] },
+              context_length: 128000,
+              id: 'openai/gpt-5.5',
+              name: 'OpenAI: GPT-5.5',
+              pricing: { completion: '0.00003', prompt: '0.000005' },
+              supported_parameters: ['tools', 'structured_outputs', 'temperature'],
+            },
+            {
+              architecture: { output_modalities: ['text'] },
+              id: 'text/no-structured-output',
+              name: 'No Structured Output',
+              pricing: { completion: '0', prompt: '0' },
+              supported_parameters: ['tools'],
+            },
+          ],
+        }),
+        {
+          headers: { 'Content-Type': 'application/json' },
+          status: 200,
+        }
+      )
+    );
+
+    const models = await listCortexAiCompatibleOpenRouterModels({
+      fetch,
+      now: new Date('2026-04-29T12:00:00.000Z'),
+    });
+
+    expect(fetch).toHaveBeenCalledWith(
+      expect.stringContaining('/models?supported_parameters=tools%2Cstructured_outputs'),
+      expect.objectContaining({
+        cache: 'no-store',
+        headers: { Accept: 'application/json' },
+      })
+    );
+    expect(models.map((model) => model.id)).toEqual(['openai/gpt-5.5']);
+  });
+});

package/templates/nextblock-template/lib/ai-model-catalog.ts

@@ -0,0 +1,41 @@
+import {
+  CORTEX_AI_OPENROUTER_BASE_URL,
+  CORTEX_AI_REQUIRED_MODEL_PARAMETERS,
+  filterCortexAiCompatibleOpenRouterModels,
+  type CortexAiCompatibleOpenRouterModel,
+} from './ai-model-registry';
+
+const SERVER_ONLY_ERROR_MESSAGE =
+  'Cortex AI OpenRouter model catalog can only be imported from server-side code.';
+
+if (typeof window !== 'undefined') {
+  throw new Error(SERVER_ONLY_ERROR_MESSAGE);
+}
+
+type FetchFunction = typeof globalThis.fetch;
+
+function buildOpenRouterModelsUrl() {
+  const url = new URL(`${CORTEX_AI_OPENROUTER_BASE_URL}/models`);
+  url.searchParams.set('supported_parameters', CORTEX_AI_REQUIRED_MODEL_PARAMETERS.join(','));
+  url.searchParams.set('output_modalities', 'text');
+  return url.toString();
+}
+
+export async function listCortexAiCompatibleOpenRouterModels(params?: {
+  fetch?: FetchFunction;
+  now?: Date;
+}): Promise<CortexAiCompatibleOpenRouterModel[]> {
+  const fetchImpl = params?.fetch || globalThis.fetch;
+  const response = await fetchImpl(buildOpenRouterModelsUrl(), {
+    cache: 'no-store',
+    headers: {
+      Accept: 'application/json',
+    },
+  });
+
+  if (!response.ok) {
+    throw new Error(`Failed to load OpenRouter models: ${response.status} ${response.statusText}`);
+  }
+
+  return filterCortexAiCompatibleOpenRouterModels(await response.json(), params?.now);
+}

package/templates/nextblock-template/lib/ai-model-registry.test.ts

@@ -0,0 +1,231 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  buildCortexAiRoutingPolicy,
+  buildCortexAiModelFallbackChain,
+  CORTEX_AI_FREE_MODEL_FALLBACK_REGISTRY,
+  CORTEX_AI_OPENROUTER_FREE_ROUTER_MODEL,
+  CortexAiRoutingError,
+  filterCortexAiCompatibleOpenRouterModels,
+  isOpenRouterRecoverableRoutingError,
+  isOpenRouterRateLimitError,
+  omitUnsupportedCortexAiModelOptions,
+  runWithCortexAiModelFallback,
+  safeParseCortexAiModelSelection,
+} from './ai-model-registry';
+
+describe('Cortex AI OpenRouter routing', () => {
+  it('builds a free-model fallback chain with preferred overrides', () => {
+    expect(buildCortexAiModelFallbackChain()).toEqual([
+      ...CORTEX_AI_FREE_MODEL_FALLBACK_REGISTRY,
+    ]);
+
+    expect(
+      buildCortexAiModelFallbackChain({
+        modelId: 'openai/gpt-oss-120b:free',
+      })
+    ).toEqual([
+      'openai/gpt-oss-120b:free',
+      ...CORTEX_AI_FREE_MODEL_FALLBACK_REGISTRY.filter(
+        (modelId) => modelId !== 'openai/gpt-oss-120b:free'
+      ),
+    ]);
+  });
+
+  it('detects OpenRouter rate limit errors across common error shapes', () => {
+    expect(isOpenRouterRateLimitError({ statusCode: 429 })).toBe(true);
+    expect(isOpenRouterRateLimitError({ response: { status: 429 } })).toBe(true);
+    expect(isOpenRouterRateLimitError({ cause: { status: 429 } })).toBe(true);
+    expect(isOpenRouterRateLimitError({ statusCode: 500 })).toBe(false);
+  });
+
+  it('detects recoverable OpenRouter routing errors for unavailable free models', () => {
+    expect(
+      isOpenRouterRecoverableRoutingError(
+        new Error('No endpoints found that can handle the requested parameters.')
+      )
+    ).toBe(true);
+    expect(
+      isOpenRouterRecoverableRoutingError(
+        new Error('Model is no longer available as a free model.')
+      )
+    ).toBe(true);
+    expect(isOpenRouterRecoverableRoutingError({ statusCode: 401 })).toBe(false);
+  });
+
+  it('retries alternate free models after a 429', async () => {
+    const tried: string[] = [];
+    const result = await runWithCortexAiModelFallback({
+      modelIds: [
+        CORTEX_AI_OPENROUTER_FREE_ROUTER_MODEL,
+        'nvidia/nemotron-3-super-120b-a12b:free',
+      ],
+      execute: async (modelId) => {
+        tried.push(modelId);
+
+        if (modelId === CORTEX_AI_OPENROUTER_FREE_ROUTER_MODEL) {
+          throw { statusCode: 429 };
+        }
+
+        return `ok:${modelId}`;
+      },
+    });
+
+    expect(tried).toEqual([
+      CORTEX_AI_OPENROUTER_FREE_ROUTER_MODEL,
+      'nvidia/nemotron-3-super-120b-a12b:free',
+    ]);
+    expect(result.modelId).toBe('nvidia/nemotron-3-super-120b-a12b:free');
+    expect(result.result).toBe('ok:nvidia/nemotron-3-super-120b-a12b:free');
+    expect(result.attempts.map((attempt) => attempt.status)).toEqual([
+      'rate_limited',
+      'success',
+    ]);
+  });
+
+  it('stops retrying on non-recoverable failures', async () => {
+    await expect(
+      runWithCortexAiModelFallback({
+        modelIds: [
+          CORTEX_AI_OPENROUTER_FREE_ROUTER_MODEL,
+          'nvidia/nemotron-3-super-120b-a12b:free',
+        ],
+        execute: async () => {
+          throw { statusCode: 401 };
+        },
+      })
+    ).rejects.toBeInstanceOf(CortexAiRoutingError);
+  });
+
+  it('keeps env-key routing locked to the configured free models', () => {
+    const policy = buildCortexAiRoutingPolicy({
+      credentialSource: 'env',
+      requestedModelId: 'openai/gpt-5.5',
+    });
+
+    expect(policy.modelIds).toEqual([...CORTEX_AI_FREE_MODEL_FALLBACK_REGISTRY]);
+    expect(policy.ignoredRequestedModelId).toBe('openai/gpt-5.5');
+    expect(policy.modelSelection).toBeNull();
+  });
+
+  it('uses the stored BYOK model before free fallbacks', () => {
+    const policy = buildCortexAiRoutingPolicy({
+      credentialSource: 'stored',
+      requestedModelId: 'anthropic/claude-sonnet-4.5',
+      selectedModel: {
+        contextLength: 128000,
+        modelId: 'openai/gpt-5.5',
+        name: 'OpenAI: GPT-5.5',
+        pricing: { completion: '0.00003', prompt: '0.000005' },
+        supportedParameters: ['tools', 'structured_outputs'],
+        updatedAt: '2026-04-29T12:00:00.000Z',
+      },
+    });
+
+    expect(policy.modelIds).toEqual([
+      'openai/gpt-5.5',
+      ...CORTEX_AI_FREE_MODEL_FALLBACK_REGISTRY,
+    ]);
+    expect(policy.ignoredRequestedModelId).toBe('anthropic/claude-sonnet-4.5');
+  });
+
+  it('keeps stored BYOK without a selection on the free registry', () => {
+    const policy = buildCortexAiRoutingPolicy({
+      credentialSource: 'stored',
+      requestedModelId: 'anthropic/claude-sonnet-4.5',
+    });
+
+    expect(policy.modelIds).toEqual([...CORTEX_AI_FREE_MODEL_FALLBACK_REGISTRY]);
+    expect(policy.ignoredRequestedModelId).toBe('anthropic/claude-sonnet-4.5');
+  });
+
+  it('filters OpenRouter catalog models to Cortex AI-compatible text models', () => {
+    const filtered = filterCortexAiCompatibleOpenRouterModels(
+      {
+        data: [
+          {
+            architecture: { output_modalities: ['text'] },
+            context_length: 128000,
+            id: 'openai/gpt-5.5',
+            name: 'OpenAI: GPT-5.5',
+            pricing: { completion: '0.00003', prompt: '0.000005' },
+            supported_parameters: ['tools', 'structured_outputs', 'temperature'],
+          },
+          {
+            architecture: { output_modalities: ['image'] },
+            id: 'image/model',
+            name: 'Image Model',
+            supported_parameters: ['tools', 'structured_outputs'],
+          },
+          {
+            architecture: { output_modalities: ['text'] },
+            id: 'text/no-tools',
+            name: 'No Tools',
+            supported_parameters: ['structured_outputs'],
+          },
+          {
+            architecture: { output_modalities: ['text'] },
+            expiration_date: '2026-04-01T00:00:00.000Z',
+            id: 'expired/model',
+            name: 'Expired',
+            supported_parameters: ['tools', 'structured_outputs'],
+          },
+        ],
+      },
+      new Date('2026-04-29T12:00:00.000Z')
+    );
+
+    expect(filtered.map((model) => model.id)).toEqual(['openai/gpt-5.5']);
+  });
+
+  it('parses stored model selections defensively', () => {
+    expect(
+      safeParseCortexAiModelSelection({
+        contextLength: 128000,
+        modelId: 'openai/gpt-5.5',
+        name: 'OpenAI: GPT-5.5',
+        pricing: { completion: '0.00003', prompt: '0.000005' },
+        supportedParameters: ['tools', 'structured_outputs'],
+        updatedAt: '2026-04-29T12:00:00.000Z',
+      })
+    ).toMatchObject({
+      modelId: 'openai/gpt-5.5',
+      name: 'OpenAI: GPT-5.5',
+    });
+
+    expect(
+      safeParseCortexAiModelSelection({
+        modelId: 'openai/gpt-5.5',
+        name: 'OpenAI: GPT-5.5',
+        supportedParameters: ['tools'],
+        updatedAt: '2026-04-29T12:00:00.000Z',
+      })
+    ).toBeNull();
+  });
+
+  it('strips unsupported optional parameters for the selected paid model only', () => {
+    const options = omitUnsupportedCortexAiModelOptions(
+      {
+        maxRetries: 0,
+        prompt: 'Hi',
+        temperature: 0.2,
+      },
+      {
+        modelId: 'openai/gpt-5.5',
+        modelSelection: {
+          contextLength: 128000,
+          modelId: 'openai/gpt-5.5',
+          name: 'OpenAI: GPT-5.5',
+          pricing: {},
+          supportedParameters: ['tools', 'structured_outputs'],
+          updatedAt: '2026-04-29T12:00:00.000Z',
+        },
+      }
+    );
+
+    expect(options).toEqual({
+      maxRetries: 0,
+      prompt: 'Hi',
+    });
+  });
+});