@learncard/network-brain-service 3.18.0 → 3.19.1

package/src/helpers/credential.helpers.ts

@@ -1,3 +1,4 @@
+import type { TenantBranding } from '@learncard/email-templates';
 import { TRPCError } from '@trpc/server';
 import { UnsignedVC, VC, JWE, LCNNotificationTypeEnumValidator } from '@learncard/types';
 
@@ -83,7 +84,8 @@ export const acceptCredential = async (
     uri: string,
     options: { skipNotification?: boolean; metadata?: Record<string, unknown> } = {
         skipNotification: false,
-    }
+    },
+    branding?: Partial<TenantBranding>
 ): Promise<boolean> => {
     const { id, type } = getUriParts(uri);
 
@@ -174,6 +176,7 @@ export const acceptCredential = async (
             credentialNodeId: pendingVc.target.id,
             issuerProfile: sourceProfile,
             holderProfile: profile,
+            branding,
         });
     } catch (error) {
         console.error(

package/src/helpers/credentialSubject.helpers.test.ts

@@ -0,0 +1,114 @@
+import { describe, expect, it } from 'vitest';
+import type { UnsignedVC } from '@learncard/types';
+
+import { setCredentialSubjectIds } from './credentialSubject.helpers';
+
+const collectSubjectIds = (credential: Record<string, unknown>): string[] => {
+    const subject = credential.credentialSubject;
+    const subjects = Array.isArray(subject) ? subject : [subject];
+
+    return subjects.flatMap(currentSubject => {
+        if (!currentSubject || typeof currentSubject !== 'object') return [];
+
+        const subjectRecord = currentSubject as Record<string, unknown>;
+        const embedded = subjectRecord.verifiableCredential;
+        const embeddedCredentials = Array.isArray(embedded) ? embedded : embedded ? [embedded] : [];
+
+        return [
+            subjectRecord.id as string,
+            ...embeddedCredentials.flatMap(nested =>
+                collectSubjectIds(nested as Record<string, unknown>)
+            ),
+        ];
+    });
+};
+
+describe('setCredentialSubjectIds', () => {
+    it('patches every CLR learner subject without rewriting achievement identities', () => {
+        const credential = {
+            credentialSubject: {
+                id: 'did:example:old-root',
+                achievement: {
+                    id: 'https://example.edu/transcript',
+                    creator: { id: 'https://example.edu' },
+                },
+                verifiableCredential: [
+                    {
+                        credentialSubject: {
+                            id: 'did:example:old-course',
+                            achievement: {
+                                id: 'https://example.edu/courses/imd-120',
+                                creator: { id: 'https://example.edu/departments/design' },
+                            },
+                            verifiableCredential: {
+                                credentialSubject: { id: 'did:example:old-assessment' },
+                            },
+                        },
+                    },
+                ],
+            },
+        } as unknown as UnsignedVC;
+
+        setCredentialSubjectIds(credential, 'did:example:learner');
+
+        expect(collectSubjectIds(credential as unknown as Record<string, unknown>)).toEqual([
+            'did:example:learner',
+            'did:example:learner',
+            'did:example:learner',
+        ]);
+        expect(credential.credentialSubject).toMatchObject({
+            achievement: {
+                id: 'https://example.edu/transcript',
+                creator: { id: 'https://example.edu' },
+            },
+            verifiableCredential: [
+                {
+                    credentialSubject: {
+                        achievement: {
+                            id: 'https://example.edu/courses/imd-120',
+                            creator: { id: 'https://example.edu/departments/design' },
+                        },
+                    },
+                },
+            ],
+        });
+    });
+
+    it('preserves signed embedded credentials while patching unsigned subjects', () => {
+        const credential = {
+            credentialSubject: {
+                id: 'did:example:old-root',
+                verifiableCredential: [
+                    {
+                        credentialSubject: { id: 'did:example:signed-subject' },
+                        proof: { type: 'DataIntegrityProof', proofValue: 'signed-value' },
+                    },
+                    {
+                        credentialSubject: { id: 'did:example:unsigned-subject' },
+                    },
+                ],
+            },
+        } as unknown as UnsignedVC;
+
+        setCredentialSubjectIds(credential, 'did:example:learner');
+
+        const subject = credential.credentialSubject as Record<string, unknown>;
+        const embedded = subject.verifiableCredential as Array<Record<string, unknown>>;
+
+        expect(subject.id).toBe('did:example:learner');
+        expect(embedded[0]?.credentialSubject).toEqual({
+            id: 'did:example:signed-subject',
+        });
+        expect(embedded[1]?.credentialSubject).toEqual({
+            id: 'did:example:learner',
+        });
+    });
+
+    it('creates an outer credential subject when a legacy template omits it', () => {
+        const credential = {} as UnsignedVC;
+
+        setCredentialSubjectIds(credential, 'did:example:learner');
+
+        expect(credential.credentialSubject).toEqual({ id: 'did:example:learner' });
+    });
+});

package/src/helpers/credentialSubject.helpers.ts

@@ -0,0 +1,40 @@
+import type { UnsignedVC, VC } from '@learncard/types';
+
+const setSubjectIds = (subject: unknown, subjectDid: string): void => {
+    if (Array.isArray(subject)) {
+        subject.forEach(nestedSubject => setSubjectIds(nestedSubject, subjectDid));
+        return;
+    }
+
+    if (!subject || typeof subject !== 'object') return;
+
+    const mutableSubject = subject as Record<string, unknown>;
+    mutableSubject.id = subjectDid;
+
+    const embeddedCredentials = mutableSubject.verifiableCredential;
+    const credentials = Array.isArray(embeddedCredentials)
+        ? embeddedCredentials
+        : [embeddedCredentials];
+
+    credentials.forEach(credential => {
+        if (!credential || typeof credential !== 'object' || Array.isArray(credential)) return;
+
+        const credentialRecord = credential as Record<string, unknown>;
+        if (credentialRecord.proof !== undefined) return;
+
+        setSubjectIds(credentialRecord.credentialSubject, subjectDid);
+    });
+};
+
+/**
+ * Sets the recipient DID on the outer credential and unsigned credentials nested in a CLR.
+ * Signed embedded credentials are immutable because changing their subject invalidates the proof.
+ */
+export const setCredentialSubjectIds = (credential: UnsignedVC | VC, subjectDid: string): void => {
+    if (!credential.credentialSubject) {
+        credential.credentialSubject = { id: subjectDid };
+        return;
+    }
+
+    setSubjectIds(credential.credentialSubject, subjectDid);
+};

package/src/helpers/finalize-inbox.helpers.ts

@@ -1,3 +1,4 @@
+import { finalizeInboxRefresh } from './inbox-refresh.helpers';
 import {
     LCNNotificationTypeEnumValidator,
     LCNInboxStatusEnumValidator,
@@ -79,10 +80,21 @@ export async function finalizeInboxCredentialsForProfile(
 
             try {
                 let finalCredential: VC;
-                const credentialPayload = await decryptInboxCredential(inboxCredential.credential);
+                const credentialPayload = inboxCredential.refreshId
+                    ? undefined
+                    : await decryptInboxCredential(inboxCredential.credential);
 
-                if (!inboxCredential.isSigned) {
-                    const unsignedCredential = JSON.parse(credentialPayload) as UnsignedVC;
+                if (inboxCredential.refreshId) {
+                    finalCredential = (
+                        await finalizeInboxRefresh({
+                            inboxId: inboxCredential.id,
+                            holderDid: profile.did,
+                            holderProfile: profile,
+                            domain,
+                        })
+                    ).credential;
+                } else if (!inboxCredential.isSigned) {
+                    const unsignedCredential = JSON.parse(credentialPayload!) as UnsignedVC;
 
                     const endpoint =
                         (inboxCredential.signingAuthority?.endpoint as string) ?? undefined;
@@ -135,19 +147,22 @@ export async function finalizeInboxCredentialsForProfile(
                         )
                     ).credential as VC;
                 } else {
-                    finalCredential = JSON.parse(credentialPayload) as VC;
+                    finalCredential = JSON.parse(credentialPayload!) as VC;
                 }
 
-                // The seeded encryption plugin adds the service DID; use explicit recipients.
-                const learnCard = await getEmptyLearnCard();
-                const recoveryCredential = await learnCard.invoke.createDagJwe(finalCredential, [
-                    profile.did,
-                ]);
-                const finalized = await finalizeAndWipeInboxCredential(inboxCredential.id, {
-                    recipientDid: profile.did,
-                    credential: recoveryCredential,
-                });
-                if (!finalized) throw new Error('Inbox credential is no longer pending');
+                if (!inboxCredential.refreshId) {
+                    // The seeded encryption plugin adds the service DID; use explicit recipients.
+                    const learnCard = await getEmptyLearnCard();
+                    const recoveryCredential = await learnCard.invoke.createDagJwe(
+                        finalCredential,
+                        [profile.did]
+                    );
+                    const finalized = await finalizeAndWipeInboxCredential(inboxCredential.id, {
+                        recipientDid: profile.did,
+                        credential: recoveryCredential,
+                    });
+                    if (!finalized) throw new Error('Inbox credential is no longer pending');
+                }
 
                 // Only write a claim audit edge once the record is actually finalized.
                 await createClaimedRelationship(profile.profileId, inboxCredential.id, 'finalize');

package/src/helpers/inbox-batch-http.helpers.test.ts

@@ -0,0 +1,188 @@
+import { describe, expect, it, vi } from 'vitest';
+import { initTRPC } from '@trpc/server';
+import { awsLambdaRequestHandler } from '@trpc/server/adapters/aws-lambda';
+import { fastifyTRPCPlugin } from '@trpc/server/adapters/fastify';
+import { fastifyTRPCOpenApiPlugin, type OpenApiMeta } from 'trpc-to-openapi';
+import Fastify from 'fastify';
+import { z } from 'zod';
+import type { APIGatewayProxyEventV2, Context } from 'aws-lambda';
+import { Readable } from 'node:stream';
+import {
+    configureInboxBatchBodyLimit,
+    INBOX_BATCH_MAX_BYTES,
+    withInboxBatchBodyLimit,
+} from './inbox-batch-http.helpers';
+import { createOpenApiAwsLambdaHandler } from './shim';
+import { inboxBatchResponseMeta } from './inbox-batch-http.helpers';
+
+const t = initTRPC.meta<OpenApiMeta>().create();
+const calls = vi.fn(() => true);
+const router = t.router({
+    inbox: t.router({
+        issueBatch: t.procedure
+            .meta({ openapi: { method: 'POST', path: '/inbox/issue-batch' } })
+            .input(z.object({ padding: z.string() }))
+            .output(z.boolean())
+            .mutation(calls),
+        issue: t.procedure
+            .meta({ openapi: { method: 'POST', path: '/inbox/issue' } })
+            .input(z.object({ padding: z.string() }))
+            .output(z.boolean())
+            .mutation(calls),
+    }),
+});
+
+const bodyOfSize = (size: number): string => JSON.stringify({ padding: 'x'.repeat(size - 14) });
+const event = (path: string, body: string, base64 = false): APIGatewayProxyEventV2 => ({
+    version: '2.0',
+    routeKey: path.startsWith('/trpc/') ? 'ANY /trpc/{trpc+}' : 'ANY /api/{trpc+}',
+    rawPath: path,
+    rawQueryString: '',
+    headers: { 'content-type': 'application/json', host: 'localhost' },
+    requestContext: {
+        http: {
+            method: 'POST',
+            path,
+            protocol: 'HTTP/1.1',
+            sourceIp: '127.0.0.1',
+            userAgent: 'test',
+        },
+        accountId: 'test',
+        apiId: 'test',
+        domainName: 'localhost',
+        domainPrefix: 'test',
+        requestId: 'test',
+        routeKey: '$default',
+        stage: '$default',
+        time: '',
+        timeEpoch: 0,
+    },
+    isBase64Encoded: base64,
+    body: base64 ? Buffer.from(body).toString('base64') : body,
+    pathParameters: { trpc: path.replace(/^\/(api|trpc)\//, '') },
+});
+
+describe('batch production transports', () => {
+    it('enforces actual streamed bytes when Content-Length is absent', async () => {
+        const server = Fastify({ bodyLimit: 32 });
+        configureInboxBatchBodyLimit(server);
+        server.post('/api/*', async () => true);
+        try {
+            const response = await server.inject({
+                method: 'POST',
+                url: '/api/inbox/issue',
+                headers: { 'content-type': 'application/json' },
+                payload: Readable.from([bodyOfSize(33)]),
+            });
+            expect(response.statusCode).toBe(413);
+            const batchResponse = await server.inject({
+                method: 'POST',
+                url: '/api/inbox/issue-batch',
+                headers: { 'content-type': 'application/json' },
+                payload: Readable.from([bodyOfSize(33)]),
+            });
+            expect(batchResponse.statusCode).toBe(200);
+        } finally {
+            await server.close();
+        }
+    });
+    it('uses the actual wildcard adapters and preserves limits on other procedures', async () => {
+        const server = Fastify();
+        configureInboxBatchBodyLimit(server);
+        await server.register(fastifyTRPCPlugin, { prefix: '/trpc', trpcOptions: { router } });
+        await server.register(fastifyTRPCOpenApiPlugin, {
+            basePath: '/api',
+            router,
+            responseMeta: inboxBatchResponseMeta,
+        });
+        try {
+            const payload = bodyOfSize(INBOX_BATCH_MAX_BYTES);
+            expect(Buffer.byteLength(payload)).toBe(INBOX_BATCH_MAX_BYTES);
+            for (const url of ['/api/inbox/issue-batch', '/trpc/inbox.issueBatch']) {
+                const response = await server.inject({
+                    method: 'POST',
+                    url,
+                    headers: { 'content-type': 'application/json' },
+                    payload,
+                });
+                expect(response.statusCode, response.body).toBe(
+                    url.startsWith('/api/') ? 202 : 200
+                );
+                const tooLarge = await server.inject({
+                    method: 'POST',
+                    url,
+                    headers: { 'content-type': 'application/json' },
+                    payload: payload + ' ',
+                });
+                expect(tooLarge.statusCode).toBe(413);
+            }
+            for (const url of ['/api/inbox/issue', '/trpc/inbox.issue']) {
+                expect(
+                    (
+                        await server.inject({
+                            method: 'POST',
+                            url,
+                            headers: { 'content-type': 'application/json' },
+                            payload,
+                        })
+                    ).statusCode
+                ).toBe(413);
+            }
+        } finally {
+            await server.close();
+        }
+    });
+
+    it.each([false, true])(
+        'checks decoded Lambda bytes before context creation (base64=%s)',
+        async base64 => {
+            const createContext = vi.fn(() => ({}));
+            const rest = createOpenApiAwsLambdaHandler({
+                router,
+                createContext,
+                responseMeta: inboxBatchResponseMeta,
+            });
+            const trpc = withInboxBatchBodyLimit(
+                awsLambdaRequestHandler({ router, createContext }),
+                'trpc'
+            );
+            const context = {} as Context;
+            for (const [path, handler] of [
+                ['/api/inbox/issue-batch', rest],
+                ['/trpc/inbox.issueBatch', trpc],
+            ] as const) {
+                createContext.mockClear();
+                calls.mockClear();
+                const valid = await handler(
+                    event(path, bodyOfSize(INBOX_BATCH_MAX_BYTES), base64),
+                    context
+                );
+                expect(valid.statusCode, valid.body).toBe(path.startsWith('/api/') ? 202 : 200);
+                expect(calls).toHaveBeenCalledTimes(1);
+                createContext.mockClear();
+                const response = await handler(
+                    event(path, bodyOfSize(INBOX_BATCH_MAX_BYTES) + ' ', base64),
+                    context
+                );
+                expect(response.statusCode).toBe(413);
+                expect(response.headers?.['Access-Control-Allow-Origin']).toBe('*');
+                expect(createContext).not.toHaveBeenCalled();
+                expect(calls).toHaveBeenCalledTimes(1);
+            }
+        }
+    );
+
+    it('counts UTF-8 bytes and rejects malformed oversized JSON before parsing', async () => {
+        const handler = vi.fn(async () => ({ statusCode: 200 }));
+        const wrapped = withInboxBatchBodyLimit(handler, 'trpc');
+        const request = event(
+            '/trpc/inbox.issue,inbox.issueBatch',
+            'é'.repeat(INBOX_BATCH_MAX_BYTES / 2 + 1)
+        );
+        request.queryStringParameters = { batch: '1' };
+        const response = await wrapped(request, {} as Context);
+        expect(response.statusCode).toBe(413);
+        expect(handler).not.toHaveBeenCalled();
+        expect('body' in response && JSON.parse(response.body)).toHaveLength(2);
+    });
+});

package/src/helpers/inbox-batch-http.helpers.ts

@@ -0,0 +1,150 @@
+import type { FastifyInstance } from 'fastify';
+import type {
+    APIGatewayProxyEvent,
+    APIGatewayProxyEventV2,
+    APIGatewayProxyResult,
+    Context,
+} from 'aws-lambda';
+import { Transform } from 'node:stream';
+
+// This leaves headroom below Lambda's 6 MB synchronous invocation envelope. It is a byte limit,
+// rather than an item limit, because large CLR credentials can make a small batch very large.
+export const INBOX_BATCH_MAX_BYTES = 4 * 1024 * 1024;
+const MESSAGE = 'Inbox batch exceeds the 4 MiB JSON payload limit';
+
+const requestPath = (url: string): string => {
+    try {
+        return decodeURIComponent(url.split('?')[0]!).replace(/\/$/, '');
+    } catch {
+        return url.split('?')[0]!;
+    }
+};
+
+/**
+ * Identifies only the batch procedure across REST and tRPC transports. A tRPC URL may contain
+ * comma-separated procedures when the client batches calls, so any batch-issuance member raises
+ * the parser allowance for the shared request.
+ */
+export const isInboxBatchRequest = (url: string): boolean => {
+    const path = requestPath(url);
+    return (
+        path === '/api/inbox/issue-batch' ||
+        path === '/inbox/issue-batch' ||
+        (path.startsWith('/trpc/') &&
+            path.slice('/trpc/'.length).split(',').includes('inbox.issueBatch'))
+    );
+};
+
+/**
+ * Gives adapter wildcard routes a 4 MiB parser ceiling, then enforces the real per-procedure
+ * limit in preParsing. trpc-to-openapi and tRPC each register one catch-all Fastify route, so
+ * setting a limit on `/api/inbox/issue-batch` would never run in the Docker server.
+ * Other procedures retain the server's default budget here. Future procedures needing a
+ * different budget must update this selector as well as the shared parser ceiling; a route
+ * bodyLimit alone cannot override this streaming guard.
+ */
+export const configureInboxBatchBodyLimit = (server: FastifyInstance): void => {
+    const defaultLimit = server.initialConfig.bodyLimit ?? 1024 * 1024;
+    server.addHook('onRoute', options => {
+        // Both adapters register catch-all routes, not one Fastify route per procedure.
+        if (options.url.startsWith('/api/') || options.url.startsWith('/trpc/')) {
+            options.bodyLimit = INBOX_BATCH_MAX_BYTES;
+        }
+    });
+    server.addHook('preParsing', async (request, _reply, payload) => {
+        const path = requestPath(request.url);
+        if (!path.startsWith('/api/') && !path.startsWith('/trpc/')) return payload;
+        const limit = isInboxBatchRequest(request.url) ? INBOX_BATCH_MAX_BYTES : defaultLimit;
+        const tooLarge = (): Error =>
+            Object.assign(new Error('Request body is too large'), {
+                statusCode: 413,
+                code: 'FST_ERR_CTP_BODY_TOO_LARGE',
+            });
+        if (Number(request.headers['content-length']) > limit) throw tooLarge();
+        // Count actual bytes as well: Content-Length is optional and client controlled. Fastify
+        // requires receivedEncodedLength on replacement streams to retain its normal accounting.
+        let bytes = 0;
+        const stream = new Transform({
+            transform(chunk, _encoding, callback) {
+                bytes += chunk.length;
+                if (bytes > limit) callback(tooLarge());
+                else callback(null, chunk);
+            },
+        });
+        Object.defineProperty(stream, 'receivedEncodedLength', { get: () => bytes });
+        payload.once('error', error => stream.destroy(error));
+        return payload.pipe(stream);
+    });
+};
+
+/** REST adapters bypass Fastify onSend hooks. Keep the documented 202 in src/openapi.ts in sync. */
+export const inboxBatchResponseMeta = ({
+    paths,
+    errors,
+}: {
+    paths?: readonly string[];
+    errors: readonly unknown[];
+}): { status?: number } =>
+    !errors.length && paths?.includes('inbox.issueBatch') ? { status: 202 } : {};
+
+type GatewayEvent = APIGatewayProxyEvent | APIGatewayProxyEventV2;
+
+/**
+ * Enforces decoded request bytes before either Lambda adapter parses JSON or creates a context.
+ * API Gateway can base64 encode binary bodies; their encoded string length is not the payload size.
+ * The wrapper also mirrors each transport's error envelope so SDK clients retain normal semantics.
+ */
+export const withInboxBatchBodyLimit =
+    <TEvent extends GatewayEvent, TResult>(
+        handler: (event: TEvent, context: Context) => Promise<TResult>,
+        transport: 'openapi' | 'trpc'
+    ): ((event: TEvent, context: Context) => Promise<TResult | APIGatewayProxyResult>) =>
+    async (event, context) => {
+        const route = event.pathParameters?.trpc;
+        // `trpc` is a path parameter in deployed Lambda events, while local/OpenAPI events expose
+        // the concrete path. Normalize both forms before applying the same route predicate.
+        let path: string;
+        if (route) {
+            const prefix = transport === 'trpc' ? '/trpc' : '';
+            path = `${prefix}/${route.replace(/^\//, '')}`;
+        } else if ('rawPath' in event) {
+            path = event.rawPath;
+        } else {
+            path = event.path;
+        }
+        const bytes = event.isBase64Encoded
+            ? Buffer.from(event.body ?? '', 'base64').length
+            : Buffer.byteLength(event.body ?? '', 'utf8');
+        if (isInboxBatchRequest(path) && bytes > INBOX_BATCH_MAX_BYTES) {
+            // A tRPC batch expects one response entry per requested procedure, including this
+            // transport-level failure, whereas REST returns its ordinary error object.
+            // REST matches trpc-to-openapi's { message, code } validation envelope, rather
+            // than the shim's { error: ... } fallback for unexpected adapter exceptions.
+            const paths = requestPath(path)
+                .replace(/^\/trpc\//, '')
+                .split(',');
+            const errors = paths.map(procedure => ({
+                error: {
+                    message: MESSAGE,
+                    code: -32013,
+                    data: { code: 'PAYLOAD_TOO_LARGE', httpStatus: 413, path: procedure },
+                },
+            }));
+            const batched =
+                event.queryStringParameters?.batch === '1' ||
+                ('rawQueryString' in event &&
+                    new URLSearchParams(event.rawQueryString).get('batch') === '1');
+            return {
+                statusCode: 413,
+                headers: { 'Content-Type': 'application/json', 'Access-Control-Allow-Origin': '*' },
+                body: JSON.stringify(
+                    transport === 'openapi'
+                        ? { message: MESSAGE, code: 'PAYLOAD_TOO_LARGE' }
+                        : batched
+                          ? errors
+                          : errors[0]
+                ),
+            };
+        }
+        return handler(event, context);
+    };

package/src/helpers/inbox-batch-status.helpers.ts

@@ -0,0 +1,11 @@
+import type { InboxBatchStatus } from '@learncard/types';
+
+/** Use the same state precedence for polling and submission replay receipts. */
+export const getInboxBatchState = (
+    states: InboxBatchStatus['items'][number]['state'][]
+): InboxBatchStatus['status'] => {
+    if (states.length === 0) return 'QUEUED';
+    if (states.includes('NEEDS_RECONCILIATION')) return 'NEEDS_RECONCILIATION';
+    if (states.every(state => state === 'COMPLETED')) return 'COMPLETED';
+    return states.every(state => state === 'QUEUED') ? 'QUEUED' : 'PROCESSING';
+};