@learncard/lca-api-service 1.5.2 → 1.6.0

package/serverless.yml

@@ -7,6 +7,7 @@ frameworkVersion: '3'
 useDotenv: true
 
 plugins:
+    - ./scripts/node24-runtime.cjs
     - serverless-esbuild
     - serverless-domain-manager
     - serverless-certificate-creator
@@ -47,7 +48,7 @@ custom:
         # serverless-esbuild default and must be preserved when overriding.
         exclude: ['aws-sdk', '@learncard/didkit-plugin-node']
         sourcemap: external
-        target: 'node20'
+        target: 'node24'
         watch:
             pattern: ['src/**/*.ts', 'dids.ts']
 
@@ -117,13 +118,13 @@ layers:
         name: ${self:service}-${opt:stage, 'dev'}-didkit-native
         description: Native DIDKit napi addon and runtime DIDKit dependency
         compatibleRuntimes:
-            - nodejs20.x
+            - nodejs24.x
         compatibleArchitectures:
             - x86_64
 
 provider:
     name: aws
-    runtime: nodejs20.x
+    runtime: nodejs24.x
     # Attach the native DIDKit layer to every function in this service.
     layers:
         - { Ref: DidkitNativeLambdaLayer }
@@ -272,6 +273,14 @@ resources:
     # ESCROW_ENCLAVE_ENDPOINT_SERVICE_NAME (the enclave account's endpoint
     # service). TLS trust for the hostname is pinned in enclaveTrustAnchors.ts.
     Conditions:
+        LcaDevBedrockGeneration:
+            Fn::And:
+                - Fn::Equals:
+                      - ${sls:stage}
+                      - dev
+                - Fn::Equals:
+                      - Ref: AWS::Region
+                      - us-east-1
         EscrowEnclavePrivateLink:
             Fn::Not:
                 - Fn::Equals: ['${env:ESCROW_ENCLAVE_ENDPOINT_SERVICE_NAME, ""}', '']
@@ -283,6 +292,70 @@ resources:
             Value:
                 Ref: SeedMigrationLambdaFunction
     Resources:
+        LcaDevBedrockGenerationPolicy:
+            Type: AWS::IAM::Policy
+            Condition: LcaDevBedrockGeneration
+            Properties:
+                PolicyName: lca-api-dev-bedrock-generation
+                Roles:
+                    - Ref: SigningAuthorityExecutionRole
+                PolicyDocument:
+                    Version: '2012-10-17'
+                    Statement:
+                        - Sid: ShortTermBearerOnly
+                          Effect: Allow
+                          Action: bedrock:CallWithBearerToken
+                          Resource: '*'
+                          Condition:
+                              StringEquals:
+                                  bedrock:bearerTokenType: SHORT_TERM
+                        - Sid: ApprovedProfiles
+                          Effect: Allow
+                          Action:
+                              - bedrock:GetInferenceProfile
+                              - bedrock:InvokeModel
+                          Resource:
+                              - Fn::Sub: arn:${AWS::Partition}:bedrock:us-east-1:${AWS::AccountId}:inference-profile/us.openai.gpt-6.1-sol
+                              - Fn::Sub: arn:${AWS::Partition}:bedrock:us-east-1:${AWS::AccountId}:inference-profile/us.openai.gpt-6-luna
+                        - Sid: DefaultProjectForApprovedProfiles
+                          Effect: Allow
+                          Action: bedrock:InvokeModel
+                          Resource:
+                              Fn::Sub: arn:${AWS::Partition}:bedrock:us-east-1:${AWS::AccountId}:project/default
+                          Condition:
+                              StringEquals:
+                                  bedrock:ModelArn:
+                                      - Fn::Sub: arn:${AWS::Partition}:bedrock:us-east-1:${AWS::AccountId}:inference-profile/us.openai.gpt-6.1-sol
+                                      - Fn::Sub: arn:${AWS::Partition}:bedrock:us-east-1:${AWS::AccountId}:inference-profile/us.openai.gpt-6-luna
+                        - Sid: SolBackingModelsThroughSolProfile
+                          Effect: Allow
+                          Action: bedrock:InvokeModel
+                          Resource:
+                              - Fn::Sub: arn:${AWS::Partition}:bedrock:us-east-1::foundation-model/openai.gpt-6.1-sol
+                              - Fn::Sub: arn:${AWS::Partition}:bedrock:us-east-2::foundation-model/openai.gpt-6.1-sol
+                              - Fn::Sub: arn:${AWS::Partition}:bedrock:us-west-2::foundation-model/openai.gpt-6.1-sol
+                          Condition:
+                              StringEquals:
+                                  bedrock:InferenceProfileArn:
+                                      Fn::Sub: arn:${AWS::Partition}:bedrock:us-east-1:${AWS::AccountId}:inference-profile/us.openai.gpt-6.1-sol
+                        - Sid: LunaBackingModelsThroughLunaProfile
+                          Effect: Allow
+                          Action: bedrock:InvokeModel
+                          Resource:
+                              - Fn::Sub: arn:${AWS::Partition}:bedrock:us-east-1::foundation-model/openai.gpt-6-luna
+                              - Fn::Sub: arn:${AWS::Partition}:bedrock:us-east-2::foundation-model/openai.gpt-6-luna
+                              - Fn::Sub: arn:${AWS::Partition}:bedrock:us-west-2::foundation-model/openai.gpt-6-luna
+                          Condition:
+                              StringEquals:
+                                  bedrock:InferenceProfileArn:
+                                      Fn::Sub: arn:${AWS::Partition}:bedrock:us-east-1:${AWS::AccountId}:inference-profile/us.openai.gpt-6-luna
+                        # generateImage default provider (docs/image-generation.md): one model,
+                        # one region, non-streaming InvokeModel only.
+                        - Sid: StableImageCoreUsWest2
+                          Effect: Allow
+                          Action: bedrock:InvokeModel
+                          Resource:
+                              Fn::Sub: arn:${AWS::Partition}:bedrock:us-west-2::foundation-model/stability.stable-image-core-v1:1
         # Only the two signing entry points and the migration worker assume this role.
         # Keep KMS references out of the role itself to avoid a Role -> Key -> Role cycle.
         SigningAuthorityExecutionRole:

package/src/config/environment.ts

@@ -31,6 +31,20 @@ export const lcaApiEnvironmentShape = {
     NETWORK_BRAIN_SERVICE_URL: optionalEnvironmentUrl,
     GOOGLE_APPLICATION_CREDENTIAL: optionalEnvironmentString,
     OPENAI_API_KEY: optionalEnvironmentString,
+    BEDROCK_BASE_URL: optionalEnvironmentString,
+    IMAGE_PROVIDER: optionalEnvironmentString
+        .transform(value => value ?? 'bedrock')
+        .pipe(z.enum(['openai', 'bedrock'])),
+    BEDROCK_IMAGE_REGION: optionalEnvironmentString
+        .transform(value => value ?? 'us-west-2')
+        .pipe(z.literal('us-west-2')),
+    BEDROCK_IMAGE_MODEL_ID: optionalEnvironmentString
+        .transform(value => value ?? 'stability.stable-image-core-v1:1')
+        .pipe(z.literal('stability.stable-image-core-v1:1')),
+    // Must finish inside the 29-second Lambda timeout (same 25-second ceiling as text generation).
+    IMAGE_TIMEOUT_MS: optionalEnvironmentString
+        .transform(value => (value === undefined ? 25_000 : Number(value)))
+        .pipe(z.number().int().min(1_000).max(25_000)),
     METABASE_SECRET_KEY: optionalEnvironmentString,
     SCOUTS_SSO_CLIENT_SECRET: optionalEnvironmentString,
     KEYCLOAK_ISSUERS: optionalEnvironmentString,

package/src/helpers/bedrockGeneration.test.ts

@@ -0,0 +1,222 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { z } from 'zod';
+import OpenAI from 'openai';
+import {
+    BEDROCK_BASE_URL,
+    createBedrockClient,
+    generateStructuredOutput,
+    GENERATION_MODELS,
+} from './bedrockGeneration';
+import { compileProjectedSchema } from './bedrockSchema';
+import { BoostSkillHierarchyValidator } from '../types/skills';
+
+const schema = z.object({ title: z.string().min(1).max(8), optional: z.string().optional() });
+const completed = (argumentsText = '{"title":"Hello"}'): Record<string, unknown> => ({
+    id: 'resp_synthetic',
+    object: 'response',
+    status: 'completed',
+    output: [
+        {
+            type: 'function_call',
+            name: 'result',
+            call_id: 'call_synthetic',
+            status: 'completed',
+            arguments: argumentsText,
+        },
+    ],
+});
+const harness = (result: unknown = completed(), status = 200) => {
+    const fetch = vi.fn<typeof globalThis.fetch>(
+        async () =>
+            new Response(JSON.stringify(result), {
+                status,
+                headers: { 'content-type': 'application/json' },
+            })
+    );
+    const provideToken = vi.fn(async () => 'synthetic-token');
+    const factory = vi.fn(() => provideToken);
+    const client = createBedrockClient(undefined, factory, fetch);
+    const run = (task: 'reasoning' | 'formatting' = 'reasoning') =>
+        generateStructuredOutput(client, {
+            task,
+            instructions: 'Fixed instruction',
+            input: 'Synthetic learner description',
+            schema,
+        });
+    return { client, fetch, provideToken, factory, run };
+};
+afterEach(() => vi.unstubAllEnvs());
+
+describe('Bedrock Responses real SDK contract (offline)', () => {
+    it('retains SDK compatibility for the separate first-party DALL-E image request', async () => {
+        const fetch = vi.fn<typeof globalThis.fetch>(
+            async () =>
+                new Response(
+                    JSON.stringify({ data: [{ url: 'https://example.com/synthetic.png' }] }),
+                    { headers: { 'content-type': 'application/json' } }
+                )
+        );
+        const imageClient = new OpenAI({ apiKey: 'synthetic-image-key', fetch });
+        const result = await imageClient.images.generate({
+            prompt: 'Synthetic image',
+            model: 'dall-e-3',
+            size: '1024x1024',
+            user: 'did:synthetic',
+        });
+        expect(result.data?.[0]?.url).toBe('https://example.com/synthetic.png');
+        expect(String(fetch.mock.calls[0]![0])).toBe(
+            'https://api.openai.com/v1/images/generations'
+        );
+        expect(JSON.parse(fetch.mock.calls[0]![1]!.body as string)).toMatchObject({
+            model: 'dall-e-3',
+            size: '1024x1024',
+            user: 'did:synthetic',
+        });
+    });
+    it.each(['reasoning', 'formatting'] as const)(
+        'uses approved %s profile and request fields',
+        async task => {
+            vi.stubEnv('OPENAI_ORG_ID', 'ambient-organization');
+            vi.stubEnv('OPENAI_PROJECT_ID', 'ambient-project');
+            const h = harness();
+            expect(await h.run(task)).toEqual({ title: 'Hello' });
+            const [url, init] = h.fetch.mock.calls[0]!;
+            expect(String(url)).toBe(`${BEDROCK_BASE_URL}/responses`);
+            expect(init?.redirect).toBe('error');
+            const headers = new Headers(init?.headers);
+            expect(headers.get('authorization')).toBe('Bearer synthetic-token');
+            expect(headers.has('openai-organization')).toBe(false);
+            expect(headers.has('openai-project')).toBe(false);
+            const body = JSON.parse(init!.body as string);
+            expect(body).toMatchObject({
+                model: GENERATION_MODELS[task],
+                reasoning: { effort: task === 'reasoning' ? 'medium' : 'none' },
+                store: false,
+                stream: false,
+                max_output_tokens: 8192,
+                tool_choice: 'required',
+                parallel_tool_calls: false,
+                tools: [{ name: 'result', type: 'function', strict: false }],
+            });
+            expect(body).not.toHaveProperty('response_format');
+            expect(body).not.toHaveProperty('temperature');
+            expect(body).not.toHaveProperty('user');
+            expect(h.client.timeout).toBeDefined();
+            expect(h.factory).toHaveBeenCalledWith({ region: 'us-east-1' });
+        }
+    );
+    it('resolves the token on each request rather than pinning a bearer for process life', async () => {
+        const h = harness();
+        await h.run();
+        await h.run();
+        expect(h.provideToken).toHaveBeenCalledTimes(2);
+    });
+    it('rejects alternate endpoints before generating tokens', () => {
+        const factory = vi.fn();
+        expect(() => createBedrockClient('https://example.com/openai/v1', factory)).toThrow(
+            'Unapproved'
+        );
+        expect(factory).not.toHaveBeenCalled();
+        expect(
+            createBedrockClient(`${BEDROCK_BASE_URL}/`, () => async () => 'synthetic')
+        ).toBeDefined();
+    });
+    it('removes SDK credential error causes and never sends a failed credential', async () => {
+        const fetch = vi.fn();
+        const client = createBedrockClient(
+            undefined,
+            () => async () => {
+                throw new Error('synthetic-sensitive-credential');
+            },
+            fetch
+        );
+        await expect(
+            generateStructuredOutput(client, {
+                task: 'reasoning',
+                instructions: 'test',
+                input: 'test',
+                schema,
+            })
+        ).rejects.toMatchObject({ message: 'AI generation unavailable', cause: undefined });
+        expect(fetch).not.toHaveBeenCalled();
+    });
+    it.each([429, 500, 503, 401])('sanitizes HTTP %s without retries or fallback', async status => {
+        const h = harness({ error: { message: 'synthetic-private-body', type: 'error' } }, status);
+        await expect(h.run()).rejects.toMatchObject({
+            code:
+                status === 429
+                    ? 'TOO_MANY_REQUESTS'
+                    : status === 503
+                      ? 'SERVICE_UNAVAILABLE'
+                      : 'INTERNAL_SERVER_ERROR',
+            cause: undefined,
+        });
+        expect(h.fetch).toHaveBeenCalledTimes(1);
+    });
+    it.each([
+        {
+            ...completed(),
+            status: 'incomplete',
+            incomplete_details: { reason: 'max_output_tokens' },
+        },
+        { ...completed(), status: 'failed', error: { code: 'error', message: 'private' } },
+        { ...completed(), output: [] },
+        {
+            ...completed(),
+            output: [...(completed().output as unknown[]), ...(completed().output as unknown[])],
+        },
+        {
+            ...completed(),
+            output: [{ type: 'function_call', name: 'wrong', call_id: 'call', arguments: '{}' }],
+        },
+        { ...completed(), output: [{ type: 'function_call', name: 'result', arguments: '{}' }] },
+        {
+            ...completed(),
+            output: [
+                {
+                    type: 'function_call',
+                    name: 'result',
+                    call_id: 'call',
+                    status: 'incomplete',
+                    arguments: '{}',
+                },
+            ],
+        },
+        {
+            ...completed(),
+            output: [
+                ...(completed().output as unknown[]),
+                { type: 'message', content: [{ type: 'refusal', refusal: 'private' }] },
+            ],
+        },
+        completed('```json\n{"title":"Hello"}\n```'),
+        completed('{"title":"Too long to pass local validation"}'),
+        completed('{"title":7}'),
+    ])('rejects incomplete, malformed, refused or invalid structured output %#', async result => {
+        const h = harness(result);
+        await expect(h.run()).rejects.toMatchObject({
+            message: 'AI generation unavailable',
+            cause: undefined,
+        });
+        expect(h.fetch).toHaveBeenCalledTimes(1);
+    });
+    it('compiles the entire existing skills hierarchy preserving optional categories', () => {
+        const compiled = compileProjectedSchema(BoostSkillHierarchyValidator);
+        expect(compiled.type).toBe('object');
+        expect(compiled.required).toBeUndefined();
+        expect(compiled.properties).toHaveProperty('medical');
+        expect(BoostSkillHierarchyValidator.parse({})).toEqual({});
+    });
+    it('rejects unsupported schemas before egress', async () => {
+        const h = harness();
+        await expect(
+            generateStructuredOutput(h.client, {
+                task: 'formatting',
+                instructions: 'test',
+                input: 'test',
+                schema: z.record(z.string(), z.string()),
+            })
+        ).rejects.toThrow('Unsupported Bedrock schema');
+        expect(h.fetch).not.toHaveBeenCalled();
+    });
+});

package/src/helpers/bedrockGeneration.ts

@@ -0,0 +1,110 @@
+import OpenAI from 'openai';
+import { getTokenProvider } from '@aws/bedrock-token-generator';
+import { TRPCError } from '@trpc/server';
+import { z } from 'zod';
+import { compileProjectedSchema } from './bedrockSchema';
+
+// Exact profiles and Responses protocol from AI Passport LC-2205 (#92).
+export const BEDROCK_BASE_URL = 'https://bedrock-runtime.us-east-1.amazonaws.com/openai/v1';
+export const GENERATION_MODELS = {
+    reasoning: 'us.openai.gpt-6.1-sol',
+    formatting: 'us.openai.gpt-6-luna',
+} as const;
+type GenerationTask = keyof typeof GENERATION_MODELS;
+
+/** Lambda uses its execution role; the official generator refreshes short-term tokens. */
+export const createBedrockClient = (
+    baseURL = BEDROCK_BASE_URL,
+    tokenFactory: typeof getTokenProvider = getTokenProvider,
+    fetch: typeof globalThis.fetch = globalThis.fetch
+): OpenAI => {
+    if (baseURL !== BEDROCK_BASE_URL && baseURL !== `${BEDROCK_BASE_URL}/`) {
+        throw new Error('Unapproved BEDROCK_BASE_URL for generation');
+    }
+    const provideToken = tokenFactory({ region: 'us-east-1' });
+    return new OpenAI({
+        baseURL: BEDROCK_BASE_URL,
+        organization: null,
+        project: null,
+        maxRetries: 0,
+        logLevel: 'off',
+        fetch: (input, init) => fetch(input, { ...init, redirect: 'error' }),
+        apiKey: async () => {
+            try {
+                const token = await provideToken();
+                if (!token?.trim()) throw new Error();
+                return token;
+            } catch {
+                // Never retain credential errors, JWTs, presigned URLs or raw provider bodies.
+                throw new Error('Bedrock credentials unavailable');
+            }
+        },
+    });
+};
+
+/** Non-streaming required-function output, with the original Zod validator authoritative. */
+export const generateStructuredOutput = async <Schema extends z.ZodType>(
+    client: OpenAI,
+    params: {
+        task: GenerationTask;
+        instructions: string;
+        input: string;
+        schema: Schema;
+    }
+): Promise<z.output<Schema>> => {
+    // Schema incompatibility fails locally before any request.
+    const parameters = compileProjectedSchema(params.schema);
+    try {
+        const response = await client.responses.create(
+            {
+                model: GENERATION_MODELS[params.task],
+                reasoning: { effort: params.task === 'reasoning' ? 'medium' : 'none' },
+                instructions: params.instructions,
+                input: [{ role: 'user', content: params.input }],
+                store: false,
+                stream: false,
+                // Includes reasoning tokens. Incomplete/truncated output never becomes success.
+                max_output_tokens: 8192,
+                tools: [
+                    {
+                        type: 'function',
+                        name: 'result',
+                        description: 'Return the requested structured result',
+                        parameters,
+                        strict: false,
+                    },
+                ],
+                tool_choice: 'required',
+                parallel_tool_calls: false,
+            },
+            { timeout: 25_000 }
+        );
+        if (response.status !== 'completed' || !Array.isArray(response.output)) throw new Error();
+        const calls = response.output.filter(item => item.type === 'function_call');
+        if (
+            calls.length !== 1 ||
+            calls[0]!.name !== 'result' ||
+            !calls[0]!.call_id ||
+            calls[0]!.status === 'incomplete' ||
+            calls[0]!.status === 'in_progress' ||
+            response.output.some(
+                item =>
+                    item.type === 'message' && item.content.some(part => part.type === 'refusal')
+            )
+        )
+            throw new Error();
+        return await params.schema.parseAsync(JSON.parse(calls[0]!.arguments));
+    } catch (error) {
+        // Preserve actionable status without exposing SDK response bodies or validation values.
+        const status = error instanceof OpenAI.APIError ? error.status : undefined;
+        throw new TRPCError({
+            code:
+                status === 429
+                    ? 'TOO_MANY_REQUESTS'
+                    : status === 503 || status === 504
+                      ? 'SERVICE_UNAVAILABLE'
+                      : 'INTERNAL_SERVER_ERROR',
+            message: status === 429 ? 'AI generation rate limited' : 'AI generation unavailable',
+        });
+    }
+};