@learncard/network-brain-service 3.19.1 → 4.0.0

package/src/accesslayer/credential/create.test.ts

@@ -1,19 +1,12 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest';
-import type { JWE, VC } from '@learncard/types';
+import type { JWE } from '@learncard/types';
 import type { IssuedCredential } from '../../types/credential';
 
-const mocks = vi.hoisted(() => ({ createOne: vi.fn(async input => input) }));
+const mocks = vi.hoisted(() => ({ createOne: vi.fn() }));
 vi.mock('@models', () => ({ Credential: { createOne: mocks.createOne } }));
 
 import { storeCredential } from './create';
 
-const statusEntry = {
-    id: 'https://network.example/status/1#42',
-    type: 'BitstringStatusListEntry' as const,
-    statusPurpose: 'revocation' as const,
-    statusListIndex: '42',
-    statusListCredential: 'https://network.example/status/1',
-};
 const createJwe = (): JWE => ({
     protected: 'header',
     iv: 'iv',
@@ -21,121 +14,15 @@ const createJwe = (): JWE => ({
     tag: 'tag',
     recipients: [],
 });
-const createVc = (): VC => ({
-    '@context': ['https://www.w3.org/2018/credentials/v1'],
-    type: ['VerifiableCredential'],
-    issuer: 'did:example:issuer',
-    issuanceDate: '2026-01-01T00:00:00Z',
-    credentialSubject: { id: 'did:example:subject' },
-    proof: {
-        type: 'Ed25519Signature2020',
-        created: '2026-01-01T00:00:00Z',
-        proofPurpose: 'assertionMethod',
-        verificationMethod: 'did:example:issuer#key-1',
-        proofValue: 'existing-signature',
-    },
-});
 
 describe('credential status storage', () => {
     beforeEach(() => {
-        vi.restoreAllMocks();
         vi.clearAllMocks();
     });
 
-    it('persists public status coordinates after serializing an issuance result', async () => {
-        const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
-        const jwe = createJwe();
-        const issued: IssuedCredential = {
-            kind: 'issued-credential',
-            credential: jwe,
-            statusEntries: [statusEntry],
-        };
-        await storeCredential(JSON.parse(JSON.stringify(issued)));
-        expect(mocks.createOne).toHaveBeenCalledWith(
-            expect.objectContaining({
-                credential: JSON.stringify(jwe),
-                statusEntries: JSON.stringify([statusEntry]),
-            })
-        );
-        expect(warn).not.toHaveBeenCalled();
-    });
-
-    it('warns when a client-encrypted JWE has no metadata, without logging its payload', async () => {
-        const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
-        const original = createJwe();
-        const jwe = { ...original };
-        await storeCredential(jwe);
-        expect(warn).toHaveBeenCalledExactlyOnceWith(
-            expect.stringContaining('Encrypted credential has no status metadata'),
-            { credentialId: expect.any(String) }
-        );
-        expect(mocks.createOne.mock.calls[0]![0].statusEntries).toBeUndefined();
-        expect(mocks.createOne.mock.calls[0]![0].credential).toBe(JSON.stringify(jwe));
-    });
-
     it('rejects internal issuance results that lost their status metadata before writing', async () => {
         const issued = { kind: 'issued-credential', credential: createJwe() } as IssuedCredential;
         await expect(storeCredential(issued)).rejects.toThrow();
         expect(mocks.createOne).not.toHaveBeenCalled();
     });
-
-    it.each([undefined, []])(
-        'warns for a pre-signed plaintext VC with missing or empty status (%j) and preserves its signature',
-        async credentialStatus => {
-            const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
-            const credential = { ...createVc(), credentialStatus };
-            const stored = await storeCredential(credential);
-            expect(warn).toHaveBeenCalledExactlyOnceWith(
-                expect.stringContaining('Plaintext credential has no status metadata'),
-                { credentialId: stored.id }
-            );
-            expect(stored.credential).toBe(JSON.stringify(credential));
-            expect(stored.statusEntries).toBeUndefined();
-        }
-    );
-
-    it.each([statusEntry, [statusEntry]])(
-        'does not warn for a plaintext VC with embedded status entries (%j)',
-        async credentialStatus => {
-            const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
-            const credential = { ...createVc(), credentialStatus };
-            const stored = await storeCredential(credential);
-            expect(warn).not.toHaveBeenCalled();
-            expect(stored.credential).toBe(JSON.stringify(credential));
-        }
-    );
-
-    it.each([
-        ['Encrypted', createJwe()],
-        ['Plaintext', createVc()],
-    ] as const)(
-        'warns for %s VC v1 issuance with empty status metadata',
-        async (kind, credential) => {
-            const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
-            const stored = await storeCredential({
-                kind: 'issued-credential',
-                credential,
-                statusEntries: [],
-            });
-            expect(warn).toHaveBeenCalledExactlyOnceWith(
-                expect.stringContaining(`${kind} credential has no status metadata`),
-                { credentialId: stored.id }
-            );
-            expect(stored.credential).toBe(JSON.stringify(credential));
-            expect(stored.statusEntries).toBeUndefined();
-        }
-    );
-
-    it('does not treat a wire JWE with extra envelope-like fields as trusted issuance metadata', async () => {
-        vi.spyOn(console, 'warn').mockImplementation(() => {});
-        const jwe = {
-            ...createJwe(),
-            kind: 'issued-credential',
-            credential: createJwe(),
-            statusEntries: [statusEntry],
-        };
-        await storeCredential(jwe);
-        expect(mocks.createOne.mock.calls[0]![0].statusEntries).toBeUndefined();
-        expect(mocks.createOne.mock.calls[0]![0].credential).toBe(JSON.stringify(jwe));
-    });
 });

package/src/accesslayer/credential/create.ts

@@ -1,4 +1,5 @@
 import { BitstringStatusListEntryValidator, UnsignedVC, VC, JWE } from '@learncard/types';
+import type { Transaction } from 'neo4j-driver';
 import { v4 as uuid } from 'uuid';
 import { getBitstringStatusListEntries, isEncrypted } from '@learncard/helpers';
 import { isIssuedCredential } from '@helpers/issuedCredentialStatus.helpers';
@@ -7,7 +8,8 @@ import type { IssuedCredential } from 'types/credential';
 import { Credential, CredentialInstance } from '@models';
 
 export const storeCredential = async (
-    input: UnsignedVC | VC | JWE | IssuedCredential
+    input: UnsignedVC | VC | JWE | IssuedCredential,
+    transaction?: Transaction
 ): Promise<CredentialInstance> => {
     const id = uuid();
 
@@ -28,9 +30,12 @@ export const storeCredential = async (
             { credentialId: id }
         );
     }
-    return Credential.createOne({
-        id,
-        credential: JSON.stringify(credential),
-        ...(statusEntries?.length ? { statusEntries: JSON.stringify(statusEntries) } : {}),
-    });
+    return Credential.createOne(
+        {
+            id,
+            credential: JSON.stringify(credential),
+            ...(statusEntries?.length ? { statusEntries: JSON.stringify(statusEntries) } : {}),
+        },
+        transaction ? { session: transaction } : undefined
+    );
 };

package/src/accesslayer/credential/relationships/create.ts

@@ -1,4 +1,6 @@
+import { termsReferralSnapshotCypher } from '@helpers/consent-referral.helpers';
 import { QueryBuilder, BindParam } from 'neogma';
+import type { Transaction } from 'neo4j-driver';
 import { v4 as uuid } from 'uuid';
 
 import {
@@ -24,7 +26,8 @@ export const createSentCredentialRelationship = async (
     credential: CredentialInstance,
     metadata?: Record<string, unknown>,
     activityId?: string,
-    integrationId?: string
+    integrationId?: string,
+    transaction?: Transaction
 ): Promise<void> => {
     const properties = flattenObject({
         to: to.profileId,
@@ -57,12 +60,10 @@ export const createSentCredentialRelationship = async (
             ],
         })
         .create(
-            `(profile)-[r:${
-                Profile.getRelationshipByAlias('credentialSent').name
-            }]->(credential)`
+            `(profile)-[r:${Profile.getRelationshipByAlias('credentialSent').name}]->(credential)`
         )
         .set('r = $params')
-        .run();
+        .run(transaction);
 
     // If the issuer is an AppStoreListing, additionally write the
     // AppStoreListing -> CREDENTIAL_SENT -> Credential edge so that
@@ -91,7 +92,7 @@ export const createSentCredentialRelationship = async (
                 }]->(credential)`
             )
             .set('r = $params')
-            .run();
+            .run(transaction);
     }
 };
 
@@ -139,7 +140,8 @@ export const createReceivedCredentialRelationship = async (
     to: ProfileType,
     from: ProfileType | { listing_id: string },
     credential: CredentialInstance,
-    metadata?: Record<string, unknown>
+    metadata?: Record<string, unknown>,
+    transaction?: Transaction
 ): Promise<void> => {
     const fromId = 'profileId' in from ? from.profileId : from.listing_id;
     const properties = flattenObject({
@@ -165,12 +167,13 @@ export const createReceivedCredentialRelationship = async (
             }]->(profile)`
         )
         .set('r = $params')
-        .run();
+        .run(transaction);
 };
 
 export const setDefaultClaimedRole = async (
     profile: ProfileType,
-    credential: CredentialInstance
+    credential: CredentialInstance,
+    transaction?: Transaction
 ): Promise<void> => {
     await new QueryBuilder()
         .match({
@@ -200,7 +203,10 @@ export const setDefaultClaimedRole = async (
                 { identifier: 'boost' },
             ],
         })
-        .run();
+        .run(transaction);
+
+    // An enclosing transaction invalidates caches only after its writes commit.
+    if (transaction) return;
 
     try {
         const boostId = await getBoostIdForCredentialInstance(credential);
@@ -239,6 +245,7 @@ export const createCredentialIssuedViaContractRelationship = async (
                 { identifier: 'terms' },
             ],
         })
+        .raw(termsReferralSnapshotCypher())
         .with('transaction')
         .match({
             model: Credential,

package/src/accesslayer/inbox-credential/relationships/create.ts

@@ -1,4 +1,5 @@
 import { QueryBuilder, BindParam } from 'neogma';
+import type { Transaction } from 'neo4j-driver';
 import { Profile, InboxCredential } from '@models';
 
 export const createDeliveredRelationship = async (
@@ -8,19 +9,23 @@ export const createDeliveredRelationship = async (
     deliveryMethod: string = 'direct'
 ): Promise<boolean> => {
     const timestamp = new Date().toISOString();
-    
-    const result = await new QueryBuilder(new BindParam({ 
-        profileId, 
-        inboxCredentialId, 
-        timestamp, 
-        recipientDid, 
-        deliveryMethod 
-    }))
+
+    const result = await new QueryBuilder(
+        new BindParam({
+            profileId,
+            inboxCredentialId,
+            timestamp,
+            recipientDid,
+            deliveryMethod,
+        })
+    )
         .match({ model: Profile, identifier: 'profile' })
         .where('profile.profileId = $profileId')
         .match({ model: InboxCredential, identifier: 'inboxCredential' })
         .where('inboxCredential.id = $inboxCredentialId')
-        .create('(profile)-[:DELIVERED_INBOX_CREDENTIAL { timestamp: $timestamp, recipientDid: $recipientDid, deliveryMethod: $deliveryMethod }]->(inboxCredential)')
+        .create(
+            '(profile)-[:DELIVERED_INBOX_CREDENTIAL { timestamp: $timestamp, recipientDid: $recipientDid, deliveryMethod: $deliveryMethod }]->(inboxCredential)'
+        )
         .return('profile')
         .run();
 
@@ -30,23 +35,28 @@ export const createDeliveredRelationship = async (
 export const createClaimedRelationship = async (
     profileId: string,
     inboxCredentialId: string,
-    claimToken: string
+    claimToken: string,
+    transaction?: Transaction
 ): Promise<boolean> => {
     const timestamp = new Date().toISOString();
-    
-    const result = await new QueryBuilder(new BindParam({ 
-        profileId, 
-        inboxCredentialId, 
-        timestamp, 
-        claimToken 
-    }))
-        .match({ model: Profile, identifier: 'profile'})
+
+    const result = await new QueryBuilder(
+        new BindParam({
+            profileId,
+            inboxCredentialId,
+            timestamp,
+            claimToken,
+        })
+    )
+        .match({ model: Profile, identifier: 'profile' })
         .where('profile.profileId = $profileId')
-        .match({ model: InboxCredential, identifier: 'inboxCredential'})
+        .match({ model: InboxCredential, identifier: 'inboxCredential' })
         .where('inboxCredential.id = $inboxCredentialId')
-        .create('(profile)-[:CLAIMED_INBOX_CREDENTIAL { timestamp: $timestamp, claimToken: $claimToken }]->(inboxCredential)')
+        .create(
+            '(profile)-[:CLAIMED_INBOX_CREDENTIAL { timestamp: $timestamp, claimToken: $claimToken }]->(inboxCredential)'
+        )
         .return('profile')
-        .run();
+        .run(transaction);
 
     return result.records.length > 0;
 };
@@ -58,19 +68,23 @@ export const createEmailSentRelationship = async (
     token: string
 ): Promise<boolean> => {
     const timestamp = new Date().toISOString();
-    
-    const result = await new QueryBuilder(new BindParam({ 
-        profileDid, 
-        inboxCredentialId, 
-        timestamp, 
-        emailAddress, 
-        token 
-    }))
+
+    const result = await new QueryBuilder(
+        new BindParam({
+            profileDid,
+            inboxCredentialId,
+            timestamp,
+            emailAddress,
+            token,
+        })
+    )
         .match({ model: Profile, identifier: 'profile' })
         .where('profile.did = $profileDid')
         .match({ model: InboxCredential, identifier: 'inboxCredential' })
         .where('inboxCredential.id = $inboxCredentialId')
-        .create('(profile)-[:SENT_EMAIL { timestamp: $timestamp, emailAddress: $emailAddress, token: $token }]->(inboxCredential)')
+        .create(
+            '(profile)-[:SENT_EMAIL { timestamp: $timestamp, emailAddress: $emailAddress, token: $token }]->(inboxCredential)'
+        )
         .return('profile')
         .run();
 
@@ -85,20 +99,24 @@ export const createWebhookSentRelationship = async (
     response?: string
 ): Promise<boolean> => {
     const timestamp = new Date().toISOString();
-    
-    const result = await new QueryBuilder(new BindParam({ 
-        profileDid, 
-        inboxCredentialId, 
-        timestamp, 
-        url, 
-        status,
-        response: response || null
-    }))
+
+    const result = await new QueryBuilder(
+        new BindParam({
+            profileDid,
+            inboxCredentialId,
+            timestamp,
+            url,
+            status,
+            response: response || null,
+        })
+    )
         .match({ model: Profile, identifier: 'profile' })
         .where('profile.did = $profileDid')
         .match({ model: InboxCredential, identifier: 'inboxCredential' })
         .where('inboxCredential.id = $inboxCredentialId')
-        .create('(profile)-[:SENT_WEBHOOK { timestamp: $timestamp, url: $url, status: $status, response: $response }]->(inboxCredential)')
+        .create(
+            '(profile)-[:SENT_WEBHOOK { timestamp: $timestamp, url: $url, status: $status, response: $response }]->(inboxCredential)'
+        )
         .return('profile')
         .run();
 
@@ -110,19 +128,23 @@ export const createExpiredRelationship = async (
     inboxCredentialId: string
 ): Promise<boolean> => {
     const timestamp = new Date().toISOString();
-    
-    const result = await new QueryBuilder(new BindParam({ 
-        profileDid, 
-        inboxCredentialId, 
-        timestamp 
-    }))
+
+    const result = await new QueryBuilder(
+        new BindParam({
+            profileDid,
+            inboxCredentialId,
+            timestamp,
+        })
+    )
         .match({ model: Profile, identifier: 'profile' })
         .where('profile.did = $profileDid')
         .match({ model: InboxCredential, identifier: 'inboxCredential' })
         .where('inboxCredential.id = $inboxCredentialId')
-        .create('(profile)-[:EXPIRED_INBOX_CREDENTIAL { timestamp: $timestamp }]->(inboxCredential)')
+        .create(
+            '(profile)-[:EXPIRED_INBOX_CREDENTIAL { timestamp: $timestamp }]->(inboxCredential)'
+        )
         .return('profile')
         .run();
 
     return result.records.length > 0;
-};
+};

package/src/accesslayer/inbox-credential/update.ts

@@ -1,4 +1,5 @@
 import { QueryBuilder, BindParam } from 'neogma';
+import type { Transaction } from 'neo4j-driver';
 import { InboxCredential } from '@models';
 import { InboxCredentialType } from '@learncard/types';
 import { flattenObject, inflateObject } from '@helpers/objects.helpers';
@@ -31,7 +32,8 @@ export const updateInboxCredential = async (
 export const finalizeAndWipeInboxCredential = async (
     id: string,
     delivery: InboxDelivery,
-    { isAccepted = true }: { isAccepted?: boolean } = {}
+    { isAccepted = true }: { isAccepted?: boolean } = {},
+    transaction?: Transaction
 ): Promise<InboxCredentialType | null> => {
     const result = await new QueryBuilder(
         new BindParam({
@@ -64,7 +66,7 @@ export const finalizeAndWipeInboxCredential = async (
         )
         .return('inboxCredential')
         .limit(1)
-        .run();
+        .run(transaction);
 
     const inboxCredential = result.records[0]?.get('inboxCredential')?.properties;
     return inboxCredential

package/src/accesslayer/share-link/abandon.ts

@@ -1,5 +1,6 @@
 import { ensureShareLinkConstraints } from '../../models/share-link-constraints';
 import { failShareLink } from './errors';
+import { queueShareAttachmentCleanup } from './attachment';
 import {
     deleteReservation,
     enqueueCleanupJob,
@@ -70,6 +71,25 @@ export const abandonReservation = async (
         }
 
         let cleanupQueuedFor: string | null = null;
+        if (
+            reservation.attachmentId &&
+            reservation.attachmentChunkCount &&
+            reservation.contentVersion
+        ) {
+            await queueShareAttachmentCleanup(
+                tx,
+                {
+                    namespace: reservation.namespace,
+                    ownerProfileId: reservation.ownerProfileId,
+                    shareId: reservation.shareId,
+                    contentVersion: reservation.contentVersion,
+                    attachmentId: reservation.attachmentId,
+                    chunkCount: reservation.attachmentChunkCount,
+                },
+                'abandoned',
+                nowIso
+            );
+        }
 
         if (reservation.objectRef) {
             await enqueueCleanupJob(tx, {