@learncard/network-brain-service 3.19.1 → 4.0.0

package/test/signing-authority-encryption.spec.ts

@@ -0,0 +1,75 @@
+import { describe, expect, it } from 'vitest';
+import { JWEValidator, VCValidator, type UnsignedVC } from '@learncard/types';
+import { getLearnCard } from '@helpers/learnCard.helpers';
+import { issueCredentialWithSigningAuthority } from '@helpers/signingAuthority.helpers';
+import type { CredentialIssuer } from 'types/issuer';
+import type { SigningAuthorityForUserType } from 'types/profile';
+
+const issuer = {
+    type: 'profile',
+    profile: { profileId: 'signer-owner' },
+} as unknown as CredentialIssuer;
+const authority = {
+    signingAuthority: { endpoint: 'https://sa.example' },
+    relationship: { name: 'test', did: 'did:example:authority' },
+} as unknown as SigningAuthorityForUserType;
+const unsignedFor = (subjectDid: string): UnsignedVC => ({
+    '@context': ['https://www.w3.org/ns/credentials/v2'],
+    type: ['VerifiableCredential'],
+    issuer: 'did:example:issuer',
+    validFrom: '2026-01-01T00:00:00Z',
+    name: 'Private signer credential',
+    credentialSubject: { id: subjectDid },
+});
+
+describe('test signing-authority encryption', () => {
+    it('encrypts for subject, owner, and delegated readers but not outsiders or the brain signer', async () => {
+        const subject = await getLearnCard('1'.repeat(64));
+        const owner = await getLearnCard('2'.repeat(64));
+        const delegate = await getLearnCard('3'.repeat(64));
+        const outsider = await getLearnCard('4'.repeat(64));
+        const brain = await getLearnCard();
+        const issued = await issueCredentialWithSigningAuthority(
+            issuer,
+            unsignedFor(subject.id.did()),
+            authority,
+            'network.example',
+            true,
+            owner.id.did(),
+            false,
+            [delegate.id.did()]
+        );
+        const jwe = JWEValidator.parse(issued.credential);
+        const decrypted = await subject.invoke.decryptDagJwe(jwe);
+        expect(decrypted).toMatchObject({
+            name: 'Private signer credential',
+            credentialSubject: { id: subject.id.did() },
+        });
+        expect(await owner.invoke.decryptDagJwe(jwe)).toEqual(decrypted);
+        expect(await delegate.invoke.decryptDagJwe(jwe)).toEqual(decrypted);
+        expect(await outsider.invoke.decryptDagJwe(jwe).catch(() => undefined)).toBeFalsy();
+        expect(await brain.invoke.decryptDagJwe(jwe).catch(() => undefined)).toBeFalsy();
+    });
+
+    it('preserves signed status coordinates when explicitly opting out of encryption', async () => {
+        const subject = await getLearnCard('6'.repeat(64));
+        const status = {
+            id: 'https://network.example/status/1#7',
+            type: 'BitstringStatusListEntry' as const,
+            statusPurpose: 'revocation' as const,
+            statusListIndex: '7',
+            statusListCredential: 'https://network.example/status/1',
+        };
+        const issued = await issueCredentialWithSigningAuthority(
+            issuer,
+            { ...unsignedFor(subject.id.did()), credentialStatus: status },
+            authority,
+            'network.example',
+            false,
+            undefined,
+            false
+        );
+        expect(VCValidator.parse(issued.credential).credentialStatus).toEqual(status);
+        expect(issued.statusEntries).toEqual([status]);
+    });
+});

package/test/smart-resume-consent.spec.ts

@@ -0,0 +1,233 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { randomBytes } from 'node:crypto';
+import { environment } from '@environment';
+import { ConsentFlowTerms } from '@models';
+import { neogma } from '@instance';
+import { getUser } from './helpers/getClient';
+import { normalContract, normalFullTerms } from './helpers/contract';
+import { getContractTermsForProfile } from '@accesslayer/consentflowcontract/relationships/read';
+import { getContractDetailsByUri } from '@accesslayer/consentflowcontract/relationships/read';
+import { uploadSmartResume } from '@helpers/smartResume.helpers';
+
+vi.mock('@helpers/smartResume.helpers', () => ({ uploadSmartResume: vi.fn() }));
+const upload = vi.mocked(uploadSmartResume);
+
+describe('SmartResume consent before publication', () => {
+    let owner: Awaited<ReturnType<typeof getUser>>;
+    let learner: Awaited<ReturnType<typeof getUser>>;
+    let recipient: Awaited<ReturnType<typeof getUser>>;
+    let contractUri: string;
+    let recipientId: string;
+    const originalUri = environment.SMART_RESUME_CONTRACT_URI;
+    beforeEach(async () => {
+        upload.mockReset().mockResolvedValue('https://example.com/resume');
+        [owner, learner, recipient] = await Promise.all([
+            getUser(randomBytes(32).toString('hex')),
+            getUser(randomBytes(32).toString('hex')),
+            getUser(randomBytes(32).toString('hex')),
+        ]);
+        for (const [i, actor] of [owner, learner, recipient].entries())
+            await actor.clients.fullAuth.profile.createProfile({
+                profileId: `resume-${i}-${randomBytes(5).toString('hex')}`,
+            });
+        recipientId = (await recipient.clients.fullAuth.profile.getProfile())!.profileId;
+        contractUri = await owner.clients.fullAuth.contracts.createConsentFlowContract({
+            name: 'Synthetic SmartResume',
+            contract: normalContract,
+            recipients: [recipientId],
+        });
+        environment.SMART_RESUME_CONTRACT_URI = contractUri;
+    });
+    afterEach(() => {
+        environment.SMART_RESUME_CONTRACT_URI = originalUri;
+    });
+    const accept = (overrides: Record<string, unknown> = {}) =>
+        learner.clients.fullAuth.contracts.consentToContract({
+            contractUri,
+            terms: normalFullTerms,
+            audienceVersion: 1,
+            recipientToken: 'synthetic-recipient-token',
+            ...overrides,
+        });
+    const savedTerms = async () => {
+        const details = (await getContractDetailsByUri(contractUri))!;
+        return getContractTermsForProfile(
+            (await learner.clients.fullAuth.profile.getProfile())!,
+            details.contract
+        );
+    };
+
+    it.each([undefined, 0])(
+        'does not publish a rejected audience version %s',
+        async audienceVersion => {
+            await expect(accept({ audienceVersion })).rejects.toMatchObject({ code: 'CONFLICT' });
+            expect(upload).not.toHaveBeenCalled();
+            expect(await savedTerms()).toBeFalsy();
+        }
+    );
+    it('commits consent before calling the external uploader and caches a completed retry', async () => {
+        upload.mockImplementationOnce(async terms => {
+            expect((await savedTerms())?.status).toBe('live');
+            expect(terms).toEqual(normalFullTerms);
+            return 'https://example.com/resume';
+        });
+        const result = await accept();
+        expect(await accept()).toEqual(result);
+        expect(upload).toHaveBeenCalledTimes(1);
+        expect((await savedTerms())?.smartResumePublicationStatus).toBe('succeeded');
+    });
+    it('retains consent on upload failure and retries the same decision without consenting again', async () => {
+        upload.mockRejectedValueOnce(new Error('Synthetic upstream outage'));
+        await expect(accept()).rejects.toMatchObject({ code: 'BAD_GATEWAY' });
+        const failed = (await savedTerms())!;
+        expect(failed.status).toBe('live');
+        expect(failed.smartResumePublicationStatus).toBe('failed');
+        await expect(accept({ recipientToken: 'different-token' })).rejects.toMatchObject({
+            code: 'CONFLICT',
+        });
+        const result = await accept();
+        expect(result.termsUri).toContain(failed.id);
+        const history = await learner.clients.fullAuth.contracts.getTermsTransactionHistory({
+            uri: result.termsUri,
+        });
+        expect(history.records).toHaveLength(1);
+        expect(upload).toHaveBeenCalledTimes(2);
+    });
+    it('rejects a failed-upload retry after the audience changes', async () => {
+        upload.mockRejectedValueOnce(new Error('Synthetic upstream outage'));
+        await expect(accept()).rejects.toMatchObject({ code: 'BAD_GATEWAY' });
+        await owner.clients.fullAuth.contracts.removeContractRecipient({
+            contractUri,
+            recipient: recipientId,
+        });
+        await expect(accept()).rejects.toMatchObject({ code: 'CONFLICT' });
+        expect(upload).toHaveBeenCalledTimes(1);
+    });
+    it('rejects an audience removal between reading the contract and committing consent', async () => {
+        const reads = await import('@accesslayer/consentflowcontract/relationships/read');
+        const original = reads.getContractDetailsByUri;
+        const spy = vi.spyOn(reads, 'getContractDetailsByUri').mockImplementationOnce(async uri => {
+            const details = await original(uri);
+            await owner.clients.fullAuth.contracts.removeContractRecipient({
+                contractUri,
+                recipient: recipientId,
+            });
+            return details;
+        });
+        try {
+            await expect(accept()).rejects.toMatchObject({ code: 'CONFLICT' });
+            expect(upload).not.toHaveBeenCalled();
+            expect(await savedTerms()).toBeFalsy();
+        } finally {
+            spy.mockRestore();
+        }
+    });
+    it('recovers a publication lease left behind by an interrupted process', async () => {
+        upload.mockRejectedValueOnce(new Error('Synthetic outage'));
+        await expect(accept()).rejects.toMatchObject({ code: 'BAD_GATEWAY' });
+        const terms = (await savedTerms())!;
+        await ConsentFlowTerms.update(
+            { smartResumePublicationStatus: 'sending', smartResumeLeaseUntil: Date.now() - 1 },
+            { where: { id: terms.id } }
+        );
+        await expect(accept()).resolves.toHaveProperty('redirectUrl', 'https://example.com/resume');
+        expect(upload).toHaveBeenCalledTimes(2);
+    });
+
+    it('ties a referral upload retry to the accepted invitation', async () => {
+        const profileId = (await learner.clients.fullAuth.profile.getProfile())!.profileId;
+        await owner.clients.fullAuth.contracts.sendContractRequest({
+            contractUri,
+            targetProfileId: profileId,
+        });
+        const invitation = (await owner.clients.fullAuth.contracts.getRequestStatusForProfile({
+            contractUri,
+            targetProfileId: profileId,
+        }))!;
+        upload.mockRejectedValueOnce(new Error('Synthetic outage'));
+        await expect(accept({ expectedRequestId: invitation.requestId })).rejects.toMatchObject({
+            code: 'BAD_GATEWAY',
+        });
+        await expect(accept({ expectedRequestId: 'different-invitation' })).rejects.toMatchObject({
+            code: 'CONFLICT',
+        });
+        await expect(accept({ expectedRequestId: invitation.requestId })).resolves.toHaveProperty(
+            'redirectUrl'
+        );
+        await neogma.queryRunner.run(
+            'MATCH (c:ConsentFlowContract {id: $contractId})-[r:REQUESTED_FOR]->(:Profile {profileId: $profileId}) SET r.requestId = $replacement',
+            {
+                contractId: contractUri.split(':').at(-1),
+                profileId,
+                replacement: 'replacement-invitation',
+            }
+        );
+        await expect(accept({ expectedRequestId: invitation.requestId })).rejects.toMatchObject({
+            code: 'CONFLICT',
+        });
+        expect(upload).toHaveBeenCalledTimes(2);
+    });
+
+    it('allows only one uploader while a publication is in flight', async () => {
+        let release!: () => void;
+        let started!: () => void;
+        const entered = new Promise<void>(resolve => {
+            started = resolve;
+        });
+        upload.mockImplementationOnce(async () => {
+            started();
+            await new Promise<void>(resolve => {
+                release = resolve;
+            });
+            return 'https://example.com/resume';
+        });
+        const first = accept();
+        await entered;
+        await expect(accept()).rejects.toMatchObject({ code: 'CONFLICT' });
+        release();
+        await first;
+        expect(upload).toHaveBeenCalledTimes(1);
+    });
+    it('retries a one-time upload without creating a second consent', async () => {
+        upload.mockRejectedValueOnce(new Error('Synthetic outage'));
+        await expect(accept({ oneTime: true })).rejects.toMatchObject({ code: 'BAD_GATEWAY' });
+        const result = await accept({ oneTime: true });
+        expect((await savedTerms())?.status).toBe('stale');
+        expect(
+            (
+                await learner.clients.fullAuth.contracts.getTermsTransactionHistory({
+                    uri: result.termsUri,
+                })
+            ).records
+        ).toHaveLength(1);
+    });
+    it('allows a new one-time decision after a completed one-time upload', async () => {
+        const first = await accept({ oneTime: true });
+        const terms = structuredClone(normalFullTerms);
+        terms.read.personal.name = 'Updated synthetic name';
+        const second = await accept({ oneTime: true, terms });
+        expect(second.termsUri).toBe(first.termsUri);
+        expect(upload).toHaveBeenCalledTimes(2);
+        expect(
+            (
+                await learner.clients.fullAuth.contracts.getTermsTransactionHistory({
+                    uri: second.termsUri,
+                })
+            ).records
+        ).toHaveLength(2);
+    });
+
+    it('does not publish a retry after terms were changed or expired', async () => {
+        upload.mockRejectedValueOnce(new Error('Synthetic outage'));
+        await expect(accept()).rejects.toMatchObject({ code: 'BAD_GATEWAY' });
+        const terms = (await savedTerms())!;
+        await ConsentFlowTerms.update({ mutationVersion: 1 }, { where: { id: terms.id } });
+        await expect(accept()).rejects.toMatchObject({ code: 'CONFLICT' });
+        await ConsentFlowTerms.update(
+            { mutationVersion: 0, expiresAt: '2000-01-01T00:00:00Z' },
+            { where: { id: terms.id } }
+        );
+        await expect(accept()).rejects.toMatchObject({ code: 'CONFLICT' });
+        expect(upload).toHaveBeenCalledTimes(1);
+    });
+});

package/test/smart-resume-upload.spec.ts

@@ -0,0 +1,65 @@
+import { afterEach, expect, it, vi } from 'vitest';
+import { uploadSmartResume } from '@helpers/smartResume.helpers';
+import { resolveUri } from '@helpers/uri.helpers';
+import { normalFullTerms } from './helpers/contract';
+
+vi.mock('@helpers/uri.helpers', () => ({ resolveUri: vi.fn() }));
+afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.resetAllMocks();
+});
+it('publishes only selected fields and deduplicated credentials with the existing SmartResume payload', async () => {
+    const terms = structuredClone(normalFullTerms);
+    terms.read.credentials.categories = {
+        Achievement: { shared: ['urn:synthetic', 'urn:synthetic'] },
+    };
+    terms.read.personal = {
+        name: 'Synthetic Learner',
+        email: 'synthetic@example.com',
+        ignored: 'private',
+    };
+    vi.mocked(resolveUri).mockResolvedValue({
+        id: 'urn:synthetic',
+        boostCredential: {
+            issuer: 'did:example:issuer',
+            credentialSubject: { id: 'did:example:learner' },
+        },
+    });
+    const fetch = vi
+        .fn()
+        .mockResolvedValueOnce(new Response(JSON.stringify({ access_token: 'synthetic-token' })))
+        .mockResolvedValueOnce(
+            new Response(JSON.stringify({ redirect_url: 'https://example.com/resume' }))
+        );
+    vi.stubGlobal('fetch', fetch);
+    expect(await uploadSmartResume(terms, 'did:example:learner', 'synthetic-recipient')).toBe(
+        'https://example.com/resume'
+    );
+    expect(resolveUri).toHaveBeenCalledOnce();
+    const payload = JSON.parse(fetch.mock.calls[1][1].body);
+    expect(payload.recipient).toEqual({
+        id: 'did:example:learner',
+        givenName: 'Synthetic Learner',
+        familyName: '',
+        email: 'synthetic@example.com',
+    });
+    expect(payload.credentials).toEqual([
+        {
+            id: 'urn:synthetic',
+            issuer: { id: 'did:example:issuer' },
+            credentialSubject: { id: 'did:example:learner' },
+        },
+    ]);
+    expect(JSON.stringify(payload)).not.toContain('private');
+});
+it('does not publish a partial selection when credential resolution fails', async () => {
+    vi.mocked(resolveUri).mockRejectedValue(new Error('Synthetic resolution failure'));
+    const fetch = vi
+        .fn()
+        .mockResolvedValue(new Response(JSON.stringify({ access_token: 'synthetic-token' })));
+    vi.stubGlobal('fetch', fetch);
+    await expect(
+        uploadSmartResume(normalFullTerms, 'did:example:learner', 'synthetic-recipient')
+    ).rejects.toThrow('Synthetic resolution failure');
+    expect(fetch).toHaveBeenCalledOnce();
+});

package/tsconfig.build.json

@@ -4,7 +4,7 @@
         "lib": ["es2022", "dom"],
         "types": ["node"],
         "noEmit": false,
-        "resolveJsonModule": false,
+        "resolveJsonModule": true,
         "rootDir": "src"
     },
     "exclude": ["./test/**/*"]

package/tsconfig.json

@@ -1,6 +1,7 @@
 {
     "extends": "../../../tsconfig.node.json",
     "compilerOptions": {
+        "resolveJsonModule": true,
         "removeComments": true,
         "preserveConstEnums": true,
         "noUncheckedIndexedAccess": true,

package/vitest.config.ts

@@ -9,10 +9,19 @@ const brainServicePreset = {
 
 export default createVitestConfig(brainServicePreset, {
     test: {
+        env: {
+            IS_E2E_TEST: 'false',
+            // The unit router tests import the complete model registry. Keep
+            // its eager index setup off; database tests have a separate config.
+            NEO4J_SKIP_INDICES: 'true',
+        },
         include: [
+            'test/share-link-*.unit.spec.ts',
+            'test/share-content-client.*.spec.ts',
             'test/uri-helpers.spec.ts',
             'test/oidc-jwt.spec.ts',
             'test/notificationMessages.spec.ts',
+            'test/openapi.spec.ts',
             'src/helpers/posthog.helpers.test.ts',
             'src/helpers/rateLimit.helpers.test.ts',
             'src/helpers/credentialSubject.helpers.test.ts',
@@ -27,6 +36,10 @@ export default createVitestConfig(brainServicePreset, {
             'src/helpers/credential-refresh-materiality.helpers.test.ts',
             'src/helpers/credential-refresh-notification-policy.helpers.test.ts',
             'src/config/environment.test.ts',
+            'src/config/stageConfig.test.ts',
+            'src/config/serverlessFunctionEnv.test.ts',
+            'bootstrapLambda.test.ts',
+            'workerLambda.test.ts',
             'src/credential-refresh.test.ts',
             'src/accesslayer/credential-refresh/read.test.ts',
             'src/models/credential-refresh-constraints.test.ts',

package/vitest.inbox-e2e.config.ts

@@ -12,6 +12,8 @@ export default createVitestConfig(serviceIntegrationPreset, {
             'test/inbox-security.e2e.ts',
             'test/inbox-batch.spec.ts',
             'test/atomic-counter.e2e.ts',
+            'test/credential-storage.neo4j.spec.ts',
+            'test/inbox.spec.ts',
         ],
         alias: { '@instance': require.resolve('./test/helpers/mock-instance.ts') },
         env: {

package/workerLambda.test.ts

@@ -0,0 +1,100 @@
+import type { APIGatewayProxyEventV2, Context } from 'aws-lambda';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+const mocks = vi.hoisted(() => ({
+    bootstrap: vi.fn(),
+    getApp: vi.fn(),
+    contractEvents: vi.fn(),
+    shareLink: vi.fn(),
+    didWeb: vi.fn(),
+}));
+
+vi.mock('@learncard/service-config', () => ({ bootstrapLambda: mocks.bootstrap }));
+vi.mock('./src/config/stageConfig', () => ({ base: {}, stages: { dev: {}, production: {} } }));
+vi.mock('./contractEventsLambdaApp', () => ({ contractEventsHandler: mocks.contractEvents }));
+vi.mock('./shareLinkMaintenanceLambdaApp', () => ({
+    shareLinkMaintenanceHandler: mocks.shareLink,
+}));
+vi.mock('./didWebLambdaApp', () => ({ didWebHandler: mocks.didWeb }));
+
+beforeEach(() => {
+    vi.resetModules();
+    vi.clearAllMocks();
+    mocks.bootstrap.mockReturnValue(mocks.getApp);
+});
+
+describe.each([
+    {
+        name: 'contractEventsLambda',
+        entry: './contractEventsLambda',
+        handlerName: 'contractEventsHandler',
+        appHandler: mocks.contractEvents,
+        appModule: './contractEventsLambdaApp',
+        result: { status: 'ok' },
+    },
+    {
+        name: 'shareLinkMaintenanceLambda',
+        entry: './shareLinkMaintenanceLambda',
+        handlerName: 'shareLinkMaintenanceHandler',
+        appHandler: mocks.shareLink,
+        appModule: './shareLinkMaintenanceLambdaApp',
+        result: { status: 'idle' },
+    },
+    {
+        name: 'didWebLambda',
+        entry: './didWebLambda',
+        handlerName: 'didWebHandler',
+        appHandler: mocks.didWeb,
+        appModule: './didWebLambdaApp',
+        result: { statusCode: 200 },
+    },
+])('$name thin bootstrap entry', ({ entry, handlerName, appHandler, appModule, result }) => {
+    it('bootstraps once with checked-in stage config and the deploy stage', async () => {
+        vi.stubEnv('AWS_LAMBDA_FUNCTION_NAME', 'lcn-brain-service-production-worker');
+        vi.stubEnv('LAMBDA_STAGE', 'production');
+        await import(entry);
+        expect(mocks.bootstrap).toHaveBeenCalledTimes(1);
+        expect(mocks.bootstrap).toHaveBeenCalledWith({
+            base: {},
+            stages: { dev: {}, production: {} },
+            stage: 'production',
+            importApp: expect.any(Function),
+        });
+        vi.unstubAllEnvs();
+    });
+
+    it('uses CONFIG_STAGE outside Lambda rather than LAMBDA_STAGE', async () => {
+        vi.stubEnv('AWS_LAMBDA_FUNCTION_NAME', '');
+        vi.stubEnv('LAMBDA_STAGE', 'production');
+        vi.stubEnv('CONFIG_STAGE', 'dev');
+        await import(entry);
+        expect(mocks.bootstrap).toHaveBeenCalledWith(expect.objectContaining({ stage: 'dev' }));
+        vi.unstubAllEnvs();
+    });
+
+    it('imports the app module lazily through the bootstrap accessor', async () => {
+        await import(entry);
+        const call = mocks.bootstrap.mock.calls.at(-1)?.[0] as {
+            importApp: () => Promise<unknown>;
+        };
+        const imported = await call.importApp();
+        expect(imported).toHaveProperty(handlerName);
+        expect(imported).toBe(await import(appModule));
+    });
+
+    it('resolves the app once per cold start and forwards every argument', async () => {
+        appHandler.mockResolvedValue(result);
+        mocks.getApp.mockResolvedValue(await import(appModule));
+        const module = await import(entry);
+        const handler = module[handlerName as keyof typeof module] as (
+            ...args: unknown[]
+        ) => Promise<unknown>;
+        const event = {} as APIGatewayProxyEventV2;
+        const context = { getRemainingTimeInMillis: () => 50_000 } as Context;
+        await expect(handler(event, context)).resolves.toEqual(result);
+        await handler(event, context);
+        expect(mocks.getApp).toHaveBeenCalledTimes(2);
+        expect(appHandler).toHaveBeenCalledTimes(2);
+        expect(appHandler).toHaveBeenLastCalledWith(event, context);
+    });
+});