@learncard/network-brain-service 3.19.0 → 4.0.0

package/test/credential-storage.neo4j.spec.ts

@@ -0,0 +1,122 @@
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { VCValidator, type BitstringStatusListEntry } from '@learncard/types';
+import { Credential, Profile, StatusList } from '@models';
+import { storeCredential } from '../src/accesslayer/credential/create';
+import { getCredentialById } from '../src/accesslayer/credential/read';
+import { setCredentialBitstringStatus, decodeBitstring } from '../src/helpers/status-list.helpers';
+import { getUser } from './helpers/getClient';
+import { app as statusListsApp } from '../src/status-lists';
+
+let issuer: Awaited<ReturnType<typeof getUser>>;
+const credentialIds: string[] = [];
+
+const isStatusBitSet = async (entry: BitstringStatusListEntry): Promise<boolean> => {
+    const id = entry.statusListCredential.split('/').pop();
+    if (!id) throw new Error('Missing status list id');
+    const response = await statusListsApp.inject({ method: 'GET', url: `/status-lists/${id}` });
+    expect(response.statusCode).toBe(200);
+    const list = JSON.parse(response.body);
+    const bytes = decodeBitstring(list.credentialSubject.encodedList, 131_072);
+    const index = Number(entry.statusListIndex);
+    return ((bytes[Math.floor(index / 8)] ?? 0) & (1 << (index % 8))) !== 0;
+};
+
+describe('credential status storage in Neo4j', () => {
+    beforeAll(async () => {
+        issuer = await getUser();
+        await issuer.clients.fullAuth.profile.createProfile({ profileId: 'storage-issuer' });
+        await statusListsApp.ready();
+    });
+    afterAll(async () => {
+        for (const id of credentialIds) await Credential.delete({ where: { id } });
+        await Profile.delete({ detach: true, where: { profileId: 'storage-issuer' } });
+        await StatusList.delete({ detach: true, where: { ownerProfileId: 'storage-issuer' } });
+    });
+
+    it('persists trusted public status descriptors for revocation consumers without decrypting the payload', async () => {
+        const [entry] = await issuer.clients.fullAuth.boost.allocateCredentialStatus({
+            statusPurposes: ['revocation'],
+        });
+        if (!entry) throw new Error('Expected allocated revocation entry');
+        const signed = await issuer.learnCard.invoke.issueCredential({
+            ...(await issuer.learnCard.invoke.getTestVc()),
+            credentialStatus: entry,
+        });
+        const jwe = await issuer.learnCard.invoke.createDagJwe(signed, [issuer.learnCard.id.did()]);
+        const stored = await storeCredential({
+            kind: 'issued-credential',
+            credential: jwe,
+            statusEntries: [entry],
+        });
+        credentialIds.push(stored.id);
+
+        const row = await getCredentialById(stored.id);
+        expect(row?.credential).toBe(JSON.stringify(jwe));
+        expect(JSON.parse(row?.statusEntries ?? 'null')).toEqual([entry]);
+        expect(await isStatusBitSet(entry)).toBe(false);
+        expect(await setCredentialBitstringStatus(stored.id, 'revocation', true)).toBe(true);
+        expect(await isStatusBitSet(entry)).toBe(true);
+    });
+
+    it.each(['embedded', 'absent'] as const)(
+        'preserves a valid signed wire VC and proof with %s status',
+        async statusCase => {
+            const unsigned = await issuer.learnCard.invoke.getTestVc();
+            if (statusCase === 'embedded') {
+                const [entry] = await issuer.clients.fullAuth.boost.allocateCredentialStatus({
+                    statusPurposes: ['revocation'],
+                });
+                unsigned.credentialStatus = entry;
+            }
+            const signed = await issuer.learnCard.invoke.issueCredential(unsigned);
+            const stored = await storeCredential(signed);
+            credentialIds.push(stored.id);
+            const row = await getCredentialById(stored.id);
+            const recovered = VCValidator.parse(JSON.parse(row?.credential ?? 'null'));
+            expect(recovered).toEqual(signed);
+            expect(
+                await issuer.learnCard.invoke.verifyCredential(recovered, { checks: ['proof'] })
+            ).toMatchObject({
+                checks: expect.arrayContaining(['proof']),
+                warnings: [],
+                errors: [],
+            });
+        }
+    );
+
+    it('does not promote wire JWE metadata to trusted status descriptors', async () => {
+        const [entry] = await issuer.clients.fullAuth.boost.allocateCredentialStatus({
+            statusPurposes: ['revocation'],
+        });
+        if (!entry) throw new Error('Expected allocated revocation entry');
+        const signed = await issuer.learnCard.invoke.issueCredential({
+            ...(await issuer.learnCard.invoke.getTestVc()),
+            credentialStatus: entry,
+        });
+        const jwe = await issuer.learnCard.invoke.createDagJwe(signed, [issuer.learnCard.id.did()]);
+        const wire = { ...jwe, kind: 'issued-credential', statusEntries: [entry] };
+        const stored = await storeCredential(wire);
+        credentialIds.push(stored.id);
+        const row = await getCredentialById(stored.id);
+        expect(row?.credential).toBe(JSON.stringify(wire));
+        expect(row?.statusEntries).toBeUndefined();
+        expect(await setCredentialBitstringStatus(stored.id, 'revocation', true)).toBe(false);
+        expect(await isStatusBitSet(entry)).toBe(false);
+    });
+
+    it('does not persist or apply an empty trusted status descriptor set', async () => {
+        const signed = await issuer.learnCard.invoke.issueCredential(
+            await issuer.learnCard.invoke.getTestVc()
+        );
+        const jwe = await issuer.learnCard.invoke.createDagJwe(signed, [issuer.learnCard.id.did()]);
+        const stored = await storeCredential({
+            kind: 'issued-credential',
+            credential: jwe,
+            statusEntries: [],
+        });
+        credentialIds.push(stored.id);
+        const row = await getCredentialById(stored.id);
+        expect(row?.statusEntries).toBeUndefined();
+        expect(await setCredentialBitstringStatus(stored.id, 'revocation', true)).toBe(false);
+    });
+});

package/test/dids.spec.ts

@@ -168,7 +168,7 @@ describe('did:web profile document generation with signing authorities', () => {
         await deleteDidDocForProfile(profileId);
     });
 
-    it('never emits a fragment on a verificationMethod controller', async () => {
+    it('renders controller-owned verification and key-agreement methods', async () => {
         const profile = await getProfileByProfileId(profileId);
         const sa = await createSigningAuthority(SA_ENDPOINT);
         await createUseSigningAuthorityRelationship(profile!, sa, 'lca-sa', SA_DID, true);
@@ -195,6 +195,15 @@ describe('did:web profile document generation with signing authorities', () => {
         );
         expect(saVm).toBeDefined();
         expect((saVm as { controller: string }).controller).toBe(did);
+
+        const ownerKeyAgreement = (doc.keyAgreement ?? []).find(
+            method => typeof method === 'object' && method.controller === did
+        );
+        expect(ownerKeyAgreement).toMatchObject({
+            type: 'X25519KeyAgreementKey2019',
+            controller: did,
+            publicKeyBase58: expect.any(String),
+        });
     });
 
     it('de-duplicates repeated signing-authority relationships in the rendered document', async () => {

package/test/guardian-gated-routes.spec.ts

@@ -216,6 +216,21 @@ describe('Guardian-approved consent mutations', () => {
         expect(record?.terms.guardianApproval).toBeUndefined();
     });
 
+    it('preserves the manager-based gate for explicitly typed profiles without managers', async () => {
+        await Profile.update(
+            { type: 'child', isServiceProfile: true },
+            { where: { profileId: 'child-user' } }
+        );
+
+        const { termsUri } = await childCaller().contracts.consentToContract({
+            contractUri,
+            terms: minimalTerms,
+        });
+        const record = await getContractTermsByUri(termsUri);
+        expect(record?.terms.status).toBe('live');
+        expect(record?.terms.guardianApproval).toBeUndefined();
+    });
+
     it('does not create consent or an audit transaction without guardian approval', async () => {
         await manageChild();
         await expect(
@@ -225,6 +240,40 @@ describe('Guardian-approved consent mutations', () => {
         expect(await ConsentFlowTransaction.findMany({ where: {} })).toEqual([]);
     });
 
+    it('does not guardian-gate a managed service profile', async () => {
+        await Profile.update({ isServiceProfile: true }, { where: { profileId: 'child-user' } });
+        await manageChild();
+
+        const { termsUri } = await childCaller().contracts.consentToContract({
+            contractUri,
+            terms: minimalTerms,
+        });
+        const record = await getContractTermsByUri(termsUri);
+        expect(record?.terms.status).toBe('live');
+        expect(record?.terms.guardianApproval).toBeUndefined();
+    });
+
+    it('requires guardian approval for legacy service-flagged children', async () => {
+        await Profile.update(
+            { type: 'child', isServiceProfile: true },
+            { where: { profileId: 'child-user' } }
+        );
+        await manageChild();
+
+        await expect(
+            childCaller().contracts.consentToContract({ contractUri, terms: minimalTerms })
+        ).rejects.toMatchObject({ code: 'FORBIDDEN' });
+
+        const { termsUri } = await childCaller(await approve()).contracts.consentToContract({
+            contractUri,
+            terms: minimalTerms,
+        });
+        expect((await getContractTermsByUri(termsUri))?.terms.guardianApproval).toMatchObject({
+            guardianProfileId: 'guardian-user',
+            guardianDid: guardian.id.did(),
+        });
+    });
+
     it('records the verified guardian and contract version on consent and permission updates', async () => {
         await manageChild();
         const beforeApproval = Date.now();

package/test/helpers/share-link-fixtures.ts

@@ -0,0 +1,94 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { v4 as uuid } from 'uuid';
+import { neogma } from '@instance';
+import { computeShareLinkRequestHash } from '@helpers/share-link-lifecycle';
+import { reserveCreate } from '../../src/accesslayer/share-link';
+
+export const nextShareId = (): string => randomBytes(16).toString('base64url');
+
+export const contentBinding = (seed: string) => ({
+    contentHash: createHash('sha256').update(`content:${seed}`).digest('hex'),
+    contentBytes: 128,
+    recoveryHash: createHash('sha256').update(`recovery:${seed}`).digest('hex'),
+    recoveryBytes: 256,
+});
+
+export const clearLifecycleGraph = async (): Promise<void> => {
+    await neogma.queryRunner.run(
+        `MATCH (n)
+         WHERE n:ShareLink OR n:ShareLinkReservation OR n:ShareLinkOperation OR n:ShareContentCleanupJob
+         DETACH DELETE n`
+    );
+};
+
+export type ReservedCreate = {
+    namespace: string;
+    ownerProfileId: string;
+    shareId: string;
+    clientRequestId: string;
+    requestHash: string;
+    operationId: string;
+    objectRef: string;
+    generation: number;
+    leaseOwner: string;
+};
+
+export const reserveShareFixture = async (options: {
+    ownerProfileId: string;
+    shareId?: string;
+    expiresAt?: string | null;
+    selectedCount?: number;
+    title?: string;
+    leaseMs?: number;
+    now: Date;
+    clientRequestId?: string;
+    requestHash?: string;
+    namespace: string;
+}): Promise<ReservedCreate> => {
+    const namespace = options.namespace;
+    const ownerProfileId = options.ownerProfileId;
+    const shareId = options.shareId ?? nextShareId();
+    const clientRequestId = options.clientRequestId ?? uuid();
+    const selectedCount = options.selectedCount ?? 1;
+    const content = contentBinding(shareId);
+    const requestHash =
+        options.requestHash ??
+        computeShareLinkRequestHash('create', {
+            id: shareId,
+            title: options.title ?? 'Shared credentials',
+            selectedCount,
+            ...content,
+        });
+
+    const result = await reserveCreate({
+        namespace,
+        ownerProfileId,
+        clientRequestId,
+        shareId,
+        title: options.title ?? 'Shared credentials',
+        note: null,
+        expiresAt: options.expiresAt ?? null,
+        selectedCount,
+        content,
+        requestHash,
+        leaseOwner: 'worker-1',
+        leaseMs: options.leaseMs,
+        now: options.now,
+    });
+
+    if (result.outcome !== 'reserved' || !result.reservation.objectRef) {
+        throw new Error(`expected reserved create, got ${result.outcome}`);
+    }
+
+    return {
+        namespace,
+        ownerProfileId,
+        shareId,
+        clientRequestId,
+        requestHash,
+        operationId: result.reservation.operationId,
+        objectRef: result.reservation.objectRef,
+        generation: result.reservation.generation,
+        leaseOwner: result.reservation.leaseOwner,
+    };
+};

package/test/inbox-security.e2e.ts

@@ -3,7 +3,12 @@ import Fastify, { type FastifyInstance } from 'fastify';
 import { fastifyTRPCOpenApiPlugin } from 'trpc-to-openapi';
 import { readFile } from 'node:fs/promises';
 import { randomUUID } from 'node:crypto';
-import type { IssueInboxCredentialType, UnsignedVC, VC } from '@learncard/types';
+import {
+    JWEValidator,
+    type IssueInboxCredentialType,
+    type UnsignedVC,
+    type VC,
+} from '@learncard/types';
 import { getBitstringStatusListEntries } from '@learncard/helpers';
 
 import { appRouter, createContext } from '../src/app';
@@ -380,7 +385,8 @@ describe('Universal Inbox escrow (HTTP + isolated Neo4j/Redis)', () => {
         expect(result.deliveries).toEqual([
             { id: issued.issuanceId, credential: result.verifiableCredentials[0] },
         ]);
-        expect(result.verifiableCredentials[0]).toMatchObject({
+        const encrypted = JWEValidator.parse(result.verifiableCredentials[0]);
+        expect(await recipient.learnCard.invoke.decryptDagJwe(encrypted)).toMatchObject({
             type: ['VerifiableCredential', 'ClrCredential'],
             proof: expect.anything(),
             credentialSubject: {
@@ -397,7 +403,7 @@ describe('Universal Inbox escrow (HTTP + isolated Neo4j/Redis)', () => {
     });
 
     it.each(['finalize', 'claim link', 'claim without profile'] as const)(
-        'recovers exactly one holder-only delivery after discarding the %s response',
+        'recovers exactly one authorized delivery after discarding the %s response',
         async path => {
             const credential = await signedCredential();
             const issued = await issue({
@@ -439,11 +445,11 @@ describe('Universal Inbox escrow (HTTP + isolated Neo4j/Redis)', () => {
             expect(
                 (await service.invoke.decryptDagJwe(recovery.credential).catch(() => null)) || null
             ).toBeNull();
-            expect(
+            const issuerRead =
                 (await issuer.learnCard.invoke
                     .decryptDagJwe(recovery.credential)
-                    .catch(() => null)) || null
-            ).toBeNull();
+                    .catch(() => null)) || null;
+            expect(issuerRead).toEqual(path === 'finalize' ? credential : null);
             expect((await post('/api/inbox/deliveries', {})).status).toBe(401);
             expect(
                 (await (await post('/api/inbox/deliveries', {}, issuer)).json()).records
@@ -510,9 +516,14 @@ describe('Universal Inbox escrow (HTTP + isolated Neo4j/Redis)', () => {
                 await verifyRecipientContact('idless@example.test');
                 const response = await post('/api/inbox/finalize', {}, recipient);
                 expect(response.status).toBe(200);
-                expect((await response.json()).deliveries).toEqual([
-                    { id: issued.issuanceId, credential },
-                ]);
+                const { deliveries } = await response.json();
+                expect(deliveries).toHaveLength(1);
+                expect(deliveries[0].id).toBe(issued.issuanceId);
+                expect(
+                    await recipient.learnCard.invoke.decryptDagJwe(
+                        JWEValidator.parse(deliveries[0].credential)
+                    )
+                ).toEqual(credential);
             } else {
                 expect(await claim(issued.claimUrl!)).toEqual([credential]);
             }
@@ -893,7 +904,12 @@ describe('Universal Inbox escrow (HTTP + isolated Neo4j/Redis)', () => {
         expect(config).toMatch(
             /inboxMaintenance:\s+handler: lambda\.inboxMaintenanceHandler[\s\S]*?rate: rate\(1 day\)\s+enabled: true/
         );
-        const handler = await readFile(new URL('../lambda.ts', import.meta.url), 'utf8');
+        // lambda.ts is a thin bootstrap entry that delegates to the lazily imported lambdaApp.ts.
+        const entry = await readFile(new URL('../lambda.ts', import.meta.url), 'utf8');
+        expect(entry).toMatch(
+            /export const inboxMaintenanceHandler[\s\S]*?\(await getApplication\(\)\)\.inboxMaintenanceHandler\(/
+        );
+        const handler = await readFile(new URL('../lambdaApp.ts', import.meta.url), 'utf8');
         expect(handler).toMatch(/inboxMaintenanceHandler[\s\S]*?await runInboxMaintenance\(\)/);
     });
 });

package/test/inbox.spec.ts

@@ -8,6 +8,7 @@ import {
     VC,
     VP,
     JWE,
+    JWEValidator,
 } from '@learncard/types';
 import { sendSpy, addNotificationToQueueSpy } from './helpers/spies';
 import * as notifications from '@helpers/notifications.helpers';
@@ -16,6 +17,9 @@ import { getProfileByProfileId } from '@accesslayer/profile/read';
 import { areProfilesConnected } from '@helpers/connection.helpers';
 import { updateInboxCredential } from '@accesslayer/inbox-credential/update';
 import { neogma } from '@instance';
+import { Credential } from '@models';
+import { getInboxCredentialById } from '@accesslayer/inbox-credential/read';
+import * as credentialRelationships from '@accesslayer/credential/relationships/create';
 
 const noAuthClient = getClient();
 let userA: Awaited<ReturnType<typeof getUser>>;
@@ -1832,6 +1836,174 @@ describe('Universal Inbox', () => {
             await SigningAuthority.delete({ detach: true, where: {} });
         });
 
+        const preparePendingBoost = async (email: string) => {
+            await Profile.relateTo({
+                alias: 'usesSigningAuthority',
+                where: {
+                    source: { profileId: 'usera' },
+                    target: { endpoint: 'https://example.com' },
+                },
+                properties: { name: 'example', did: userA.learnCard.id.did() },
+            });
+            const boostUri = await userA.clients.fullAuth.boost.createBoost({
+                credential: testUnsignedBoost,
+                claimPermissions: { canRevoke: true },
+            });
+            const issued = await userA.clients.fullAuth.inbox.issue({
+                templateUri: boostUri,
+                recipient: { type: 'email', value: email },
+                configuration: {
+                    signingAuthority: { endpoint: 'https://example.com', name: 'example' },
+                    webhookUrl: 'https://example.com/finalized',
+                },
+            });
+            await updateInboxCredential(issued.issuanceId, { isAccepted: true });
+            await userB.clients.fullAuth.contactMethods.addContactMethod({
+                type: 'email',
+                value: email,
+            });
+            await userB.clients.fullAuth.contactMethods.verifyContactMethod({
+                token: sendSpy.mock.calls.at(-1)?.[0].templateModel.verificationToken,
+            });
+            addNotificationToQueueSpy.mockClear();
+            return { boostUri, inboxId: issued.issuanceId };
+        };
+
+        it('rolls back a failed received write and completes all delivery tracking on retry', async () => {
+            const { boostUri, inboxId } = await preparePendingBoost('atomic-receipt@test.com');
+            const escrow = (await getInboxCredentialById(inboxId))!.credential;
+            const originalCredentialIds = (await Credential.findMany()).map(record => record.id);
+            const failedWrite = vi
+                .spyOn(credentialRelationships, 'createReceivedCredentialRelationship')
+                .mockRejectedValueOnce(new Error('injected received write failure'));
+            try {
+                await expect(userB.clients.fullAuth.inbox.finalize({})).resolves.toMatchObject({
+                    claimed: 0,
+                    errors: 1,
+                    deliveries: [],
+                });
+            } finally {
+                failedWrite.mockRestore();
+            }
+            expect(await getInboxCredentialById(inboxId)).toMatchObject({
+                currentStatus: 'PENDING',
+                credential: escrow,
+            });
+            expect((await Credential.findMany()).map(record => record.id).sort()).toEqual(
+                originalCredentialIds.sort()
+            );
+            expect(await userB.clients.fullAuth.credential.receivedCredentials({})).toEqual([]);
+            const auditBeforeRetry = await neogma.queryRunner.run(
+                'MATCH ()-[r:CLAIMED_INBOX_CREDENTIAL]->(ic:InboxCredential {id: $id}) RETURN count(r) AS count',
+                { id: inboxId }
+            );
+            expect(auditBeforeRetry.records[0].get('count').toNumber()).toBe(0);
+            expect(
+                addNotificationToQueueSpy.mock.calls.some(
+                    ([notification]) =>
+                        notification.type ===
+                            LCNNotificationTypeEnumValidator.enum.ISSUANCE_ERROR &&
+                        notification.data?.inbox?.status === 'PENDING'
+                )
+            ).toBe(true);
+            addNotificationToQueueSpy.mockClear();
+
+            const retry = await userB.clients.fullAuth.inbox.finalize({});
+            expect(retry).toMatchObject({ claimed: 1, errors: 0, deliveries: [{ id: inboxId }] });
+            const finalized = await getInboxCredentialById(inboxId);
+            expect(finalized?.currentStatus).toBe('ISSUED');
+            expect(finalized?.credential).toBeUndefined();
+            expect(
+                await userA.clients.fullAuth.boost.getBoostRecipients({
+                    uri: boostUri,
+                    includeUnacceptedBoosts: false,
+                })
+            ).toHaveLength(1);
+            expect(await userB.clients.fullAuth.credential.receivedCredentials({})).toHaveLength(1);
+            const auditAfterRetry = await neogma.queryRunner.run(
+                'MATCH ()-[r:CLAIMED_INBOX_CREDENTIAL]->(ic:InboxCredential {id: $id}) RETURN count(r) AS count',
+                { id: inboxId }
+            );
+            expect(auditAfterRetry.records[0].get('count').toNumber()).toBe(1);
+            expect(
+                addNotificationToQueueSpy.mock.calls.some(
+                    ([notification]) =>
+                        notification.type === LCNNotificationTypeEnumValidator.enum.ISSUANCE_ERROR
+                )
+            ).toBe(false);
+        });
+
+        it('rolls back partial claim permissions and grants hooks and the default role on retry', async () => {
+            const { boostUri, inboxId } = await preparePendingBoost('atomic-permissions@test.com');
+            const targetUri = await userA.clients.fullAuth.boost.createBoost({
+                credential: testUnsignedBoost,
+            });
+            await userA.clients.fullAuth.claimHook.createClaimHook({
+                hook: {
+                    type: 'GRANT_PERMISSIONS',
+                    data: { claimUri: boostUri, targetUri, permissions: { canIssue: true } },
+                },
+            });
+            const failedRole = vi
+                .spyOn(credentialRelationships, 'setDefaultClaimedRole')
+                .mockRejectedValueOnce(new Error('injected claimed-role failure'));
+            try {
+                await expect(userB.clients.fullAuth.inbox.finalize({})).resolves.toMatchObject({
+                    claimed: 0,
+                    errors: 1,
+                });
+            } finally {
+                failedRole.mockRestore();
+            }
+            expect(await getInboxCredentialById(inboxId)).toMatchObject({
+                currentStatus: 'PENDING',
+            });
+            expect(
+                (await userB.clients.fullAuth.boost.getBoostPermissions({ uri: targetUri }))
+                    .canIssue
+            ).toBe(false);
+            expect(await userB.clients.fullAuth.credential.receivedCredentials({})).toEqual([]);
+
+            await expect(userB.clients.fullAuth.inbox.finalize({})).resolves.toMatchObject({
+                claimed: 1,
+                errors: 0,
+            });
+            expect(
+                (await userB.clients.fullAuth.boost.getBoostPermissions({ uri: targetUri }))
+                    .canIssue
+            ).toBe(true);
+            expect(
+                (await userB.clients.fullAuth.boost.getBoostPermissions({ uri: boostUri }))
+                    .canRevoke
+            ).toBe(true);
+            const [received] = await userB.clients.fullAuth.credential.receivedCredentials({});
+            expect(
+                await userB.clients.fullAuth.credential.acceptCredential({ uri: received.uri })
+            ).toBe(true);
+            const roleCounts = await neogma.queryRunner.run(
+                'MATCH (:Profile {profileId: "userb"})-[r:HAS_ROLE]->(b:Boost) WHERE b.id IN $ids RETURN b.id AS id, count(r) AS count',
+                { ids: [boostUri, targetUri].map(uri => uri.split(':').at(-1)) }
+            );
+            expect(roleCounts.records.map(record => record.get('count').toNumber())).toEqual([
+                1, 1,
+            ]);
+        });
+
+        it('commits only one accepted delivery and claim audit under concurrent finalization', async () => {
+            const { inboxId } = await preparePendingBoost('atomic-concurrent@test.com');
+            const results = await Promise.all(
+                Array.from({ length: 3 }, () => userB.clients.fullAuth.inbox.finalize({}))
+            );
+            expect(results.reduce((count, result) => count + result.claimed, 0)).toBe(1);
+            expect(results.reduce((count, result) => count + result.errors, 0)).toBe(0);
+            expect(await userB.clients.fullAuth.credential.receivedCredentials({})).toHaveLength(1);
+            const audit = await neogma.queryRunner.run(
+                'MATCH ()-[r:CLAIMED_INBOX_CREDENTIAL]->(ic:InboxCredential {id: $id}) RETURN count(r) AS count',
+                { id: inboxId }
+            );
+            expect(audit.records[0].get('count').toNumber()).toBe(1);
+        });
+
         it('should not allow finalize without full auth', async () => {
             await expect(noAuthClient.inbox.finalize({})).rejects.toMatchObject({
                 code: 'UNAUTHORIZED',
@@ -1912,8 +2084,11 @@ describe('Universal Inbox', () => {
             expect(res.claimed).toBe(2);
             expect(res.errors).toBe(0);
             expect(res.verifiableCredentials).toHaveLength(2);
-            // Ensure returned VCs are signed
-            for (const vc of res.verifiableCredentials) {
+            // The HTTP contract is encrypted; only the holder decrypts the signed VCs.
+            for (const encrypted of res.verifiableCredentials) {
+                const vc = await userB.learnCard.invoke.decryptDagJwe<VC>(
+                    JWEValidator.parse(encrypted)
+                );
                 expect(vc.proof).toBeDefined();
             }
 
@@ -2089,12 +2264,13 @@ describe('Universal Inbox', () => {
             const consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined);
 
             try {
-                await expect(userB.clients.fullAuth.inbox.finalize({})).resolves.toMatchObject({
-                    processed: 1,
-                    claimed: 1,
-                    errors: 0,
-                    verifiableCredentials: [expect.objectContaining({ proof: expect.anything() })],
-                });
+                const result = await userB.clients.fullAuth.inbox.finalize({});
+                expect(result).toMatchObject({ processed: 1, claimed: 1, errors: 0 });
+                expect(
+                    await userB.learnCard.invoke.decryptDagJwe<VC>(
+                        JWEValidator.parse(result.verifiableCredentials[0])
+                    )
+                ).toMatchObject({ proof: expect.anything() });
             } finally {
                 queryRunnerSpy.mockRestore();
                 consoleErrorSpy.mockRestore();

package/test/inline-template.helpers.spec.ts

@@ -0,0 +1,49 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+    computeInlineTemplateHash,
+    validateInlineTemplateDataOrThrow,
+    validateInlineTemplateOrThrow,
+} from '../src/helpers/inline-template.helpers';
+
+describe('inline-template.helpers', () => {
+    it('throws developer-readable template validation errors', () => {
+        expect(() =>
+            validateInlineTemplateOrThrow({
+                name: '',
+                image: 'http://not-https.example.com/badge.png',
+            })
+        ).toThrow(/TEMPLATE_INVALID:/);
+    });
+
+    it('throws strict templateData validation errors with suggestions', () => {
+        const compiled = computeInlineTemplateHash({
+            name: 'Course Completion: {{courseName}}',
+            description: 'Awarded to {{learnerName}}',
+        });
+
+        expect(() =>
+            validateInlineTemplateDataOrThrow(compiled.variableManifest, {
+                courseNmae: 'Broken key',
+                learnerName: 'Ada',
+            })
+        ).toThrow(
+            /TEMPLATE_DATA_INVALID: .*templateData.courseName is required.*did you mean "courseName"/
+        );
+    });
+
+    it('hashes template content deterministically', () => {
+        const first = computeInlineTemplateHash({
+            name: 'Course Completion: {{courseName}}',
+            description: 'Awarded to {{learnerName}}',
+            walletSkills: [{ frameworkId: 'framework-1', id: 'skill-1' }],
+        });
+        const second = computeInlineTemplateHash({
+            name: 'Course Completion: {{courseName}}',
+            description: 'Awarded to {{learnerName}}',
+            walletSkills: [{ frameworkId: 'framework-1', id: 'skill-1' }],
+        });
+
+        expect(first.contentHash).toBe(second.contentHash);
+    });
+});