@learncard/network-brain-service 4.1.3 → 5.0.0

package/src/helpers/boost-storage.helpers.test.ts

@@ -1,5 +1,6 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 import type { JWE, VC } from '@learncard/types';
+import type { Transaction } from 'neo4j-driver';
 
 const mocks = vi.hoisted(() => ({
     decrypt: vi.fn(),
@@ -12,6 +13,17 @@ const mocks = vi.hoisted(() => ({
     accept: vi.fn(),
     notify: vi.fn(async () => undefined),
     signingAuthority: vi.fn(),
+    release: vi.fn(),
+    transaction: { run: vi.fn() },
+}));
+
+vi.mock('@instance', () => ({
+    neogma: {
+        getTransaction: async (
+            _transaction: Transaction | null,
+            action: (transaction: unknown) => Promise<unknown>
+        ) => action(mocks.transaction),
+    },
 }));
 
 vi.mock('@models', () => ({}));
@@ -24,12 +36,13 @@ vi.mock('./uri.helpers', () => ({
         `lc:network:${domain}/${kind}:${id}`,
 }));
 vi.mock('@accesslayer/credential/create', () => ({ storeCredential: mocks.store }));
+vi.mock('@accesslayer/credential/delete', () => ({ releaseUnlinkedCredential: mocks.release }));
 vi.mock('@accesslayer/boost/relationships/create', () => ({
     createBoostInstanceOfRelationship: mocks.instanceOf,
 }));
 vi.mock('@accesslayer/credential/relationships/create', () => ({
     createSentCredentialRelationship: mocks.sent,
-    createCredentialIssuedViaContractRelationship: mocks.contract,
+    createContractCredentialRelationships: mocks.contract,
     createListingSentCredentialRelationship: mocks.listing,
 }));
 vi.mock('./credential.helpers', () => ({
@@ -137,41 +150,13 @@ describe('boost payload storage', () => {
             ),
         ],
     ] as const)(
-        'stores %s payload unchanged and preserves graph, claim, and notification behavior',
+        'preserves %s bytes without decrypting or replacing the issuer signature',
         async (_kind, credential) => {
             const uri = await sendBoost({ ...options, credential });
             expect(uri).toBe('lc:network:network.example/credential:stored');
             expect(mocks.store.mock.calls[0]?.[0]).toBe(credential);
             expect(mocks.decrypt).not.toHaveBeenCalled();
             expect(mocks.issue).not.toHaveBeenCalled();
-            expect(mocks.instanceOf).toHaveBeenCalledExactlyOnceWith(
-                { id: 'stored' },
-                options.boost
-            );
-            expect(mocks.sent).toHaveBeenCalledExactlyOnceWith(
-                options.from,
-                options.to,
-                { id: 'stored' },
-                options.metadata,
-                'activity',
-                'integration'
-            );
-            expect(mocks.contract).toHaveBeenCalledExactlyOnceWith(
-                { id: 'stored' },
-                options.contractTerms
-            );
-            expect(mocks.listing).toHaveBeenCalledExactlyOnceWith(
-                'listing',
-                options.to,
-                { id: 'stored' },
-                options.metadata,
-                'activity',
-                'integration'
-            );
-            expect(mocks.accept).toHaveBeenCalledExactlyOnceWith(options.to, uri, {
-                skipNotification: false,
-            });
-            expect(mocks.notify).toHaveBeenCalledOnce();
         }
     );
 
@@ -179,12 +164,10 @@ describe('boost payload storage', () => {
         const first = deferred();
         const sent = deferred();
         const listing = deferred();
-        const contract = deferred();
         mocks.instanceOf.mockReturnValueOnce(first.promise);
         mocks.sent.mockReturnValueOnce(sent.promise);
         mocks.listing.mockReturnValueOnce(listing.promise);
-        mocks.contract.mockReturnValueOnce(contract.promise);
-        const result = sendBoost(options);
+        const result = sendBoost({ ...options, contractTerms: undefined });
         await vi.waitFor(() => expect(mocks.instanceOf).toHaveBeenCalledOnce());
         expect(mocks.sent).not.toHaveBeenCalled();
         first.resolve();
@@ -194,19 +177,67 @@ describe('boost payload storage', () => {
         await vi.waitFor(() => expect(mocks.listing).toHaveBeenCalledOnce());
         expect(mocks.contract).not.toHaveBeenCalled();
         listing.resolve();
-        await vi.waitFor(() => expect(mocks.contract).toHaveBeenCalledOnce());
-        expect(mocks.accept).not.toHaveBeenCalled();
-        expect(mocks.notify).not.toHaveBeenCalled();
-        contract.resolve();
         await expect(result).resolves.toBe('lc:network:network.example/credential:stored');
+        expect(mocks.contract).not.toHaveBeenCalled();
+        expect(mocks.instanceOf.mock.calls[0]?.[2]).toBe(mocks.transaction);
+        expect(mocks.sent.mock.calls[0]?.[6]).toBe(mocks.transaction);
+        expect(mocks.listing.mock.calls[0]?.[6]).toBe(mocks.transaction);
+    });
+
+    it('releases a failed contract send so the same signed payload can be retried', async () => {
+        let reserved = false;
+        mocks.store
+            .mockImplementationOnce(async () => {
+                reserved = true;
+                return { id: 'stored' };
+            })
+            .mockImplementationOnce(async () => {
+                if (reserved) throw new Error('Status list index is already bound');
+                return { id: 'retried' };
+            });
+        mocks.release.mockImplementationOnce(async () => {
+            reserved = false;
+        });
+        const error = new Error('contract not approved');
+        mocks.contract.mockRejectedValueOnce(error);
+        await expect(sendBoost({ ...options, credential: vc })).rejects.toBe(error);
+        expect(mocks.release).toHaveBeenCalledWith('stored');
+        await expect(sendBoost({ ...options, credential: vc })).resolves.toBe(
+            'lc:network:network.example/credential:retried'
+        );
+        expect(mocks.store.mock.calls[0]?.[0]).toBe(vc);
+        expect(mocks.store.mock.calls[1]?.[0]).toBe(vc);
+    });
+
+    it('preserves the relationship error when cleanup fails', async () => {
+        const error = new Error('relationship failed');
+        mocks.contract.mockRejectedValueOnce(error);
+        mocks.release.mockRejectedValueOnce(new Error('cleanup failed'));
+        const log = vi.spyOn(console, 'error').mockImplementation(() => undefined);
+        try {
+            await expect(sendBoost(options)).rejects.toBe(error);
+            expect(log).toHaveBeenCalledWith('BOOST_UNLINKED_CREDENTIAL_CLEANUP_FAILED');
+        } finally {
+            log.mockRestore();
+        }
     });
 
     it.each(['instanceOf', 'sent', 'listing', 'contract'] as const)(
-        'stops after a failed %s relationship without acceptance or notification',
+        'stops after a failed %s graph write without acceptance or notification',
         async failed => {
             const error = new Error('graph write failed');
             mocks[failed].mockRejectedValueOnce(error);
-            await expect(sendBoost(options)).rejects.toBe(error);
+            await expect(
+                sendBoost({
+                    ...options,
+                    contractTerms: failed === 'contract' ? options.contractTerms : undefined,
+                })
+            ).rejects.toBe(error);
+            if (failed === 'contract') {
+                expect(mocks.instanceOf).not.toHaveBeenCalled();
+                expect(mocks.sent).not.toHaveBeenCalled();
+                expect(mocks.listing).not.toHaveBeenCalled();
+            }
             const order = ['instanceOf', 'sent', 'listing', 'contract'] as const;
             for (const later of order.slice(order.indexOf(failed) + 1)) {
                 expect(mocks[later]).not.toHaveBeenCalled();
@@ -224,7 +255,7 @@ describe('boost payload storage', () => {
                 listing: { listing_id: 'listing' },
                 ownerProfile: { profileId: 'org' },
             } as Parameters<typeof sendBoost>[0]['from'];
-            await sendBoost({ ...options, from, listingId });
+            await sendBoost({ ...options, from, listingId, contractTerms: undefined });
             expect(mocks.sent).toHaveBeenCalledOnce();
             expect(mocks.listing).toHaveBeenCalledTimes(listingId === 'another-listing' ? 1 : 0);
         }
@@ -287,7 +318,7 @@ describe('boost payload storage', () => {
             } else {
                 expect(unsigned).not.toHaveProperty('boostId');
             }
-            expect(mocks.store).toHaveBeenCalledWith(issued);
+            expect(mocks.store).toHaveBeenCalledWith(issued, mocks.transaction, 'org');
         }
     );
 
@@ -411,6 +442,41 @@ describe('boost payload storage', () => {
             }
         );
 
+        describe('display-only anchor detection', () => {
+            const anchorBoostWith = (template: Record<string, unknown>) =>
+                ({
+                    dataValues: {
+                        id: BOOST_ID,
+                        boost: JSON.stringify({ ...vc, boostId: undefined, ...template }),
+                    },
+                }) as Parameters<typeof prepareCredentialFromBoost>[0];
+
+            it("does not mistake an ordinary Boost's own display object for a display-only anchor", async () => {
+                const credential = await prepareCredentialFromBoost(
+                    anchorBoostWith({
+                        display: {
+                            backgroundColor: '#fff',
+                            backgroundImage: '',
+                            displayType: 'card',
+                        },
+                    }),
+                    `lc:network:network.example/boost:${BOOST_ID}`,
+                    options.domain
+                );
+                expect(credential.boostId).toBe(`lc:network:network.example/boost:${BOOST_ID}`);
+            });
+
+            it('rejects reusing a boost marked as a display-only anchor without an issuance credential', async () => {
+                await expect(
+                    prepareCredentialFromBoost(
+                        anchorBoostWith({ displayOnlyAnchor: true, display: {} }),
+                        `lc:network:network.example/boost:${BOOST_ID}`,
+                        options.domain
+                    )
+                ).rejects.toMatchObject({ code: 'BAD_REQUEST' });
+            });
+        });
+
         describe('stampIssuanceDate', () => {
             const NOW = '2026-10-18T05:00:00.000Z';
 

package/src/helpers/boost.helpers.ts

@@ -1,6 +1,9 @@
 import cloneDeep from 'lodash/cloneDeep';
+import type { Transaction } from 'neo4j-driver';
+import { neogma } from '@instance';
 import {
     CredentialFieldError,
+    isDisplayOnlyAnchorTemplate,
     isEncrypted,
     isVC2Format,
     materializeCredentialFields,
@@ -31,13 +34,14 @@ import {
 import { setCredentialSubjectIds } from '@helpers/credentialSubject.helpers';
 
 import { getBoostOwner } from '@accesslayer/boost/relationships/read';
-import { BoostInstance } from '@models';
+import { BoostInstance, CredentialInstance } from '@models';
 import { constructUri } from './uri.helpers';
 import { storeCredential } from '@accesslayer/credential/create';
+import { releaseUnlinkedCredential } from '@accesslayer/credential/delete';
 import { createBoostInstanceOfRelationship } from '@accesslayer/boost/relationships/create';
 import {
     createSentCredentialRelationship,
-    createCredentialIssuedViaContractRelationship,
+    createContractCredentialRelationships,
     createListingSentCredentialRelationship,
 } from '@accesslayer/credential/relationships/create';
 import { acceptCredential, getCredentialUri } from './credential.helpers';
@@ -85,7 +89,7 @@ export const isEditableBoost = (boost: BoostInstance): boolean => {
  */
 export const isBoostViewableByClaimLink = async (boost: BoostInstance): Promise<boolean> => {
     const defaultRoles = await boost.findRelationships({ alias: 'defaultRole' });
-    const defaultRole = defaultRoles[0]?.target as any;
+    const defaultRole = defaultRoles[0]?.target;
     const canView = defaultRole?.canView ?? defaultRole?.dataValues?.canView;
 
     if (typeof canView === 'boolean') return canView;
@@ -138,6 +142,8 @@ export const sendBoost = async ({
     skipNotification = false,
     autoAcceptCredential = false,
     contractTerms,
+    contractWriterProfileId,
+    allowConsumedOneTime = false,
     metadata,
     activityId,
     integrationId,
@@ -151,6 +157,8 @@ export const sendBoost = async ({
     skipNotification?: boolean;
     autoAcceptCredential?: boolean;
     contractTerms?: DbTermsType;
+    contractWriterProfileId?: string;
+    allowConsumedOneTime?: boolean;
     metadata?: Record<string, unknown>;
     activityId?: string;
     integrationId?: string;
@@ -179,47 +187,78 @@ export const sendBoost = async ({
             }
 
             // Preserve the issuer's payload without decrypting or counter-signing it.
-            const credentialInstance = await traceDb('storeCredential', () =>
-                storeCredential(credential)
-            );
-
-            // These writes share Credential/Profile/Listing nodes. Separate concurrent
-            // auto-commit transactions can deadlock on Neo4j relationship-chain locks.
-            await traceDb('createRelationships', async () => {
-                await createBoostInstanceOfRelationship(credentialInstance, boost);
-                await createSentCredentialRelationship(
-                    from,
-                    to,
-                    credentialInstance,
-                    metadata,
-                    activityId,
-                    integrationId
+            // Contract auto-boosts are signed by the writer, whose profile owns the status list.
+            const persistDelivery = async (
+                transaction?: Transaction
+            ): Promise<CredentialInstance> => {
+                const stored = await traceDb('storeCredential', () =>
+                    storeCredential(
+                        credential,
+                        transaction,
+                        contractWriterProfileId ?? fromProfile.profileId
+                    )
                 );
-
-                // Listing issuers already create this edge inside createSentCredentialRelationship.
-                // Keep explicit attribution for profile/integration issuers or another listing.
-                if (
-                    listingId &&
-                    (!isAppStoreListingIssuer(from) || from.listing.listing_id !== listingId)
-                ) {
-                    await createListingSentCredentialRelationship(
-                        listingId,
-                        to,
-                        credentialInstance,
-                        metadata,
-                        activityId,
-                        integrationId
-                    );
+                if (!contractTerms) {
+                    await traceDb('createRelationships', async () => {
+                        await createBoostInstanceOfRelationship(stored, boost, transaction);
+                        await createSentCredentialRelationship(
+                            from,
+                            to,
+                            stored,
+                            metadata,
+                            activityId,
+                            integrationId,
+                            transaction
+                        );
+                        if (
+                            listingId &&
+                            (!isAppStoreListingIssuer(from) ||
+                                from.listing.listing_id !== listingId)
+                        ) {
+                            await createListingSentCredentialRelationship(
+                                listingId,
+                                to,
+                                stored,
+                                metadata,
+                                activityId,
+                                integrationId,
+                                transaction
+                            );
+                        }
+                    });
                 }
+                return stored;
+            };
+            const credentialInstance = contractTerms
+                ? await persistDelivery()
+                : await neogma.getTransaction(null, persistDelivery);
 
+            try {
                 if (contractTerms) {
-                    await createCredentialIssuedViaContractRelationship(
-                        credentialInstance,
-                        contractTerms
+                    await traceDb('createRelationships', () =>
+                        createContractCredentialRelationships({
+                            issuer: from,
+                            writerProfileId: contractWriterProfileId ?? fromProfile.profileId,
+                            recipient: to,
+                            credential: credentialInstance,
+                            boost,
+                            terms: contractTerms,
+                            metadata,
+                            activityId,
+                            integrationId,
+                            listingId,
+                            allowConsumedOneTime,
+                        })
                     );
                 }
-            });
-
+            } catch (error) {
+                try {
+                    await releaseUnlinkedCredential(credentialInstance.id);
+                } catch {
+                    console.error('BOOST_UNLINKED_CREDENTIAL_CLEANUP_FAILED');
+                }
+                throw error;
+            }
             if (autoAcceptCredential) {
                 await acceptCredential(to, getCredentialUri(credentialInstance.id, domain), {
                     skipNotification,
@@ -349,11 +388,21 @@ export const prepareCredentialFromBoost = async (
         recipientDid?: string;
         recipientName?: string;
         issuerDid?: string;
+        /** Transient issuance body for a display-only managed anchor; never persisted. */
+        credential?: UnsignedVC | VC;
     } = {}
 ): Promise<UnsignedVC> => {
     const { templateData, recipientDid, recipientName, issuerDid } = options;
 
-    let boostJsonString = boost.dataValues.boost;
+    let boostJsonString = options.credential
+        ? convertCredentialToBoostTemplateJSON(options.credential)
+        : boost.dataValues.boost;
+    if (!options.credential && isDisplayOnlyAnchorTemplate(JSON.parse(boostJsonString))) {
+        throw new TRPCError({
+            code: 'BAD_REQUEST',
+            message: 'Display-only anchors require an issuance credential in the request.',
+        });
+    }
     const allowAutoAppendEvidence = shouldAutoAppendTemplateEvidence(boostJsonString);
 
     // Auto-inject known system variables into templateData
@@ -529,7 +578,6 @@ const credentialContextSupportsDynamicEvidence = (credential: UnsignedVC): boole
  * Throws TRPCError if not found.
  */
 export const resolveBoostByUri = async (boostUri: string): Promise<BoostInstance> => {
-    const { TRPCError } = await import('@trpc/server');
     const { getBoostByUri } = await import('@accesslayer/boost/read');
 
     const boost = await getBoostByUri(boostUri);

package/src/helpers/campaign-app-origin.helpers.ts

@@ -0,0 +1,25 @@
+import { z } from 'zod';
+import { environment } from '@environment';
+
+/** Deployment-owned origins keep queued links on the same environment as the campaign. */
+export const getCampaignAppOrigin = (tenantId: string): string => {
+    try {
+        const origins = z
+            .record(z.string(), z.string())
+            .parse(JSON.parse(environment.CAMPAIGN_APP_ORIGINS ?? '{}'));
+        const origin = new URL(origins[tenantId]!);
+        const local = ['localhost', '127.0.0.1', '[::1]'].includes(origin.hostname);
+        if (
+            (origin.protocol !== 'https:' && !(local && origin.protocol === 'http:')) ||
+            origin.username ||
+            origin.password ||
+            origin.pathname !== '/' ||
+            origin.search ||
+            origin.hash
+        )
+            throw new Error('Invalid origin');
+        return origin.origin;
+    } catch {
+        throw new Error('Campaign app origin is not configured for this tenant');
+    }
+};

package/src/helpers/campaign-email.helpers.ts

@@ -0,0 +1,113 @@
+import type { Campaign } from '@learncard/types';
+import { resolveTenantFromRequest } from '@learncard/email-templates';
+import { environment } from '@environment';
+import { claimCampaignEmail, acknowledgeCampaignEmail } from '@accesslayer/campaign/email';
+import { PostmarkAdapter } from '../services/delivery/adapters/postmark.adapter';
+import { signCampaignUnsubscribeToken } from './campaign-unsubscribe.helpers';
+import { getCampaignAppOrigin } from './campaign-app-origin.helpers';
+
+/** Campaign delivery must never fall through to a logging or transactional adapter. */
+export const assertCampaignEmailConfigured = (): void => {
+    if (!environment.POSTMARK_API_KEY || !environment.DOMAIN_NAME)
+        throw new Error('Campaign email requires Postmark and a public Brain domain');
+    const stream = environment.POSTMARK_BROADCAST_STREAM;
+    if (!stream || stream.toLowerCase() === 'outbound')
+        throw new Error('Campaign email requires a broadcast stream');
+    signCampaignUnsubscribeToken('00000000-0000-4000-8000-000000000000', 'configuration-check');
+};
+
+export const campaignEmailLinks = (
+    campaign: Campaign,
+    unsubscribeId: string
+): { ctaUrl?: string; unsubscribeUrl: string; oneClickUrl: string } => {
+    const token = signCampaignUnsubscribeToken(unsubscribeId, campaign.id);
+    let ctaUrl: string | undefined;
+    if (campaign.channels.includes('inApp') && campaign.message?.enabled) {
+        const tenantId = campaign.tenantId ?? resolveTenantFromRequest({}).id;
+        const cta = new URL(`/m/${campaign.id}`, getCampaignAppOrigin(tenantId));
+        cta.searchParams.set('utm_source', 'email');
+        cta.searchParams.set('utm_campaign', campaign.id);
+        ctaUrl = cta.toString();
+    }
+    const domain = environment.DOMAIN_NAME?.replace(/%3A/gi, ':').replace(/\/trpc\/?$/, '');
+    if (!domain) throw new Error('Campaign unsubscribe endpoint is not configured');
+    const api = new URL(`https://${domain}`);
+    if (api.username || api.password || api.pathname !== '/' || api.search || api.hash)
+        throw new Error('Invalid Brain domain');
+    if (['localhost', '127.0.0.1', '[::1]'].includes(api.hostname)) api.protocol = 'http:';
+    const unsubscribe = new URL('/campaigns/unsubscribe/browser', api);
+    unsubscribe.searchParams.set('token', token);
+    const oneClick = new URL('/campaigns/unsubscribe', api);
+    oneClick.searchParams.set('token', token);
+    return {
+        ...(ctaUrl ? { ctaUrl } : {}),
+        unsubscribeUrl: unsubscribe.toString(),
+        oneClickUrl: oneClick.toString(),
+    };
+};
+
+export class CampaignEmailDeliveryError extends Error {}
+
+/** One adapter per wave keeps stream validation ahead of every durable claim. */
+export const prepareCampaignEmailDelivery = async (): Promise<PostmarkAdapter> => {
+    assertCampaignEmailConfigured();
+    const adapter = new PostmarkAdapter(environment.POSTMARK_API_KEY!);
+    await adapter.assertBroadcastStream(environment.POSTMARK_BROADCAST_STREAM);
+    return adapter;
+};
+
+export const sendCampaignEmail = async (
+    campaign: Campaign,
+    profileId: string,
+    test = false,
+    preparedAdapter?: PostmarkAdapter
+): Promise<boolean> => {
+    const adapter = preparedAdapter ?? (await prepareCampaignEmailDelivery());
+    let deliver: (() => Promise<void>) | undefined;
+    const recipient = await claimCampaignEmail(
+        campaign.id,
+        campaign.createdAt,
+        profileId,
+        test,
+        async current => {
+            try {
+                const links = campaignEmailLinks(current.campaign, current.unsubscribeId);
+                deliver = await adapter.prepareCampaignEmail({
+                    contactMethod: { type: 'email', value: current.email },
+                    templateId: 'campaign-announcement',
+                    templateModel: {
+                        ...current.campaign.email!,
+                        ctaUrl: links.ctaUrl,
+                        unsubscribeUrl: links.unsubscribeUrl,
+                    },
+                    subject: current.campaign.email!.subject,
+                    messageStream: environment.POSTMARK_BROADCAST_STREAM,
+                    headers: [
+                        { Name: 'List-Unsubscribe', Value: `<${links.oneClickUrl}>` },
+                        { Name: 'List-Unsubscribe-Post', Value: 'List-Unsubscribe=One-Click' },
+                    ],
+                    branding: resolveTenantFromRequest({
+                        'x-tenant-id': current.campaign.tenantId,
+                    }).emailBranding,
+                    locale: current.locale,
+                });
+            } catch {
+                throw new Error('Campaign email preparation failed');
+            }
+        }
+    );
+    if (!recipient) return false;
+    if (!deliver) throw new Error('Campaign email was not prepared');
+    try {
+        await deliver();
+        if (!test) await acknowledgeCampaignEmail(campaign.id, campaign.createdAt, profileId);
+    } catch {
+        // Provider errors may contain recipient addresses and bearer unsubscribe URLs.
+        throw new CampaignEmailDeliveryError(
+            test
+                ? 'Campaign test email delivery failed'
+                : 'Campaign email delivery failed; reservation retained'
+        );
+    }
+    return true;
+};