@learncard/network-brain-service 4.1.3 → 5.0.0

package/src/helpers/notifications.helpers.ts

@@ -20,6 +20,7 @@ import {
 } from './credential-refresh-materiality.helpers';
 import { getNotificationMessage } from './notificationMessages';
 import { resolveRecipientLocale } from './getRecipientLocale.helpers';
+import { fetchNotificationWebhook } from './notification-webhook-fetch.helpers';
 
 // Timeout value in milliseconds for aborting the request
 const TIMEOUT = 6000;
@@ -357,18 +358,25 @@ export async function sendNotification(
             // Set a timeout to abort the fetch request
             const timeoutId = setTimeout(() => controller.abort(), TIMEOUT);
 
-            let response: Response;
+            let response: Pick<Response, 'ok' | 'status' | 'text'>;
+            let responseText: string;
             try {
                 directWebhookRequestStarted = true;
-                response = await fetch(notificationsWebhook, {
-                    method: 'POST',
-                    headers: {
-                        'Content-Type': 'application/json',
-                        'Authorization': `Bearer ${didJwt}`,
+                response = await fetchNotificationWebhook(
+                    notificationsWebhook,
+                    {
+                        method: 'POST',
+                        headers: {
+                            'Content-Type': 'application/json',
+                            'Authorization': `Bearer ${didJwt}`,
+                        },
+                        body: JSON.stringify(notification),
+                        signal,
                     },
-                    body: JSON.stringify(notification),
-                    signal,
-                });
+                    runtimeEnvironment.IS_OFFLINE
+                );
+                // Keep the deadline active while reading the acknowledgement body too.
+                responseText = await response.text();
             } finally {
                 clearTimeout(timeoutId);
             }
@@ -386,8 +394,6 @@ export async function sendNotification(
                 throw createWebhookTransportError(response.status);
             }
 
-            const responseText = await response.text();
-
             let responseBody: unknown;
             if (responseText.trim().length > 0) {
                 try {
@@ -398,7 +404,8 @@ export async function sendNotification(
             }
 
             if (
-                notification.data?.metadata?.connectionPrompt &&
+                (notification.data?.metadata?.connectionPrompt ||
+                    notification.type === 'ANNOUNCEMENT') &&
                 extractNotificationWebhookSuccess(responseBody) === null
             ) {
                 throw createUnrecognizedWebhookAcknowledgementError(response.status);

package/src/helpers/refresh-send-intent.helpers.test.ts

@@ -0,0 +1,60 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+vi.mock('@instance', () => ({ neogma: {} }));
+vi.mock('./credential-refresh.helpers', () => ({}));
+
+import {
+    computeRefreshSendRequestDigest,
+    matchesRefreshSendRequestDigest,
+} from './refresh-send-intent.helpers';
+
+describe('managed send metadata digest', () => {
+    afterEach(() => vi.unstubAllEnvs());
+    const request = { recipientProfileId: 'recipient', holderDid: 'did:example:holder' };
+
+    it('matches current and retained keys without accepting removed keys or changed metadata', () => {
+        vi.stubEnv('CREDENTIAL_REFRESH_DIGEST_SECRET', 'old-send-test-key');
+        vi.stubEnv('CREDENTIAL_REFRESH_DIGEST_KEY_VERSION', 'v1');
+        vi.stubEnv('CREDENTIAL_REFRESH_DIGEST_PREVIOUS_KEYS', '{}');
+        const stored = computeRefreshSendRequestDigest(request);
+        expect(matchesRefreshSendRequestDigest(request, stored)).toBe(true);
+        vi.stubEnv('CREDENTIAL_REFRESH_DIGEST_SECRET', 'new-send-test-key');
+        vi.stubEnv('CREDENTIAL_REFRESH_DIGEST_KEY_VERSION', 'v2');
+        vi.stubEnv(
+            'CREDENTIAL_REFRESH_DIGEST_PREVIOUS_KEYS',
+            JSON.stringify({ v1: 'old-send-test-key' })
+        );
+        expect(matchesRefreshSendRequestDigest(request, stored)).toBe(true);
+        expect(
+            matchesRefreshSendRequestDigest(request, computeRefreshSendRequestDigest(request))
+        ).toBe(true);
+        expect(
+            matchesRefreshSendRequestDigest({ ...request, integrationId: 'other' }, stored)
+        ).toBe(false);
+        expect(computeRefreshSendRequestDigest(request)).toMatch(/^v1:[A-Za-z0-9_-]{43}$/);
+        vi.stubEnv('CREDENTIAL_REFRESH_DIGEST_PREVIOUS_KEYS', '{}');
+        expect(matchesRefreshSendRequestDigest(request, stored)).toBe(false);
+    });
+
+    it('ignores claim content and uses a versioned HMAC', () => {
+        const original = {
+            ...request,
+            template: { name: 'PRIVATE' },
+            templateData: { grade: 'A' },
+        };
+        const changed = { ...request, template: { name: 'OTHER' }, templateData: { grade: 'F' } };
+        expect(computeRefreshSendRequestDigest(original)).toMatch(/^v1:[A-Za-z0-9_-]{43}$/);
+        expect(computeRefreshSendRequestDigest(original)).toBe(
+            computeRefreshSendRequestDigest(changed)
+        );
+    });
+
+    it('binds explicitly public display and routing metadata', () => {
+        expect(
+            computeRefreshSendRequestDigest({ ...request, display: { name: 'Public' } })
+        ).not.toBe(computeRefreshSendRequestDigest(request));
+        expect(computeRefreshSendRequestDigest({ ...request, integrationId: 'other' })).not.toBe(
+            computeRefreshSendRequestDigest(request)
+        );
+    });
+});

package/src/helpers/refresh-send-intent.helpers.ts

@@ -1,11 +1,16 @@
-import { createHash, randomUUID } from 'crypto';
+import { createHmac, randomUUID } from 'crypto';
 import { TRPCError } from '@trpc/server';
 import type { ManagedCredentialRefreshReceipt, SendBoostResponse } from '@learncard/types';
+import { getStatusEntriesForCredential, getStatusManagement } from './status-list.helpers';
 import { canonicalizeCredentialJson } from '@learncard/helpers';
 
 import { neogma } from '@instance';
 
 import { getInitialRefreshRoot, getManagedCredentialUri } from './credential-refresh.helpers';
+import {
+    getCredentialRefreshDigestSecret,
+    getCredentialRefreshDigestCandidateSecrets,
+} from './credential-refresh-materiality.helpers';
 
 /** A preparation not touched for this long is considered abandoned and may be taken over. */
 export const REFRESH_SEND_INTENT_STALE_MS = 5 * 60_000;
@@ -26,6 +31,8 @@ export type RefreshSendIntent = {
     credentialId?: string;
     refreshId?: string;
     holderDid?: string;
+    contractUri?: string;
+    integrationId?: string;
     pendingReceipt?: ManagedCredentialRefreshReceipt;
     pendingActivityId?: string;
     result?: SendBoostResponse;
@@ -40,32 +47,58 @@ export type ClaimRefreshSendIntentResult =
 const getIntentKey = (issuerProfileId: string, idempotencyKey: string): string =>
     `${issuerProfileId}:${idempotencyKey}`;
 
-/** Digest of everything that defines a prepare request; a reused key must match it. */
-export const computeRefreshSendRequestDigest = (request: {
-    recipientProfileId: string;
-    holderDid: string;
-    templateUri?: string;
-    template?: unknown;
-    contractUri?: string;
-    templateData?: Record<string, unknown>;
-    integrationId?: string;
-    credentialId?: string;
-}): string =>
-    createHash('sha256')
+/** Versioned, domain-separated public-metadata digest. Legacy unkeyed intents fail closed. */
+export const computeRefreshSendRequestDigest = (
+    request: {
+        statusBinding?: 'server';
+        statusPurposes?: ('revocation' | 'suspension')[];
+        recipientProfileId: string;
+        holderDid: string;
+        credentialId?: string;
+        templateUri?: string;
+        display?: import('@learncard/types').CredentialDisplay;
+        contractUri?: string;
+        integrationId?: string;
+        /** Included so an idempotencyKey can never silently replay across modes. */
+        encryption?: 'network' | 'holder';
+    },
+    secret: string = getCredentialRefreshDigestSecret()
+): string =>
+    'v1:' +
+    createHmac('sha256', secret)
+        .update('refresh-send-intent:v1\0')
         .update(
             canonicalizeCredentialJson({
                 recipientProfileId: request.recipientProfileId,
                 holderDid: request.holderDid,
                 templateUri: request.templateUri ?? null,
-                template: request.template ?? null,
+                display: request.display ?? {},
                 contractUri: request.contractUri ?? null,
-                templateData: request.templateData ?? {},
                 integrationId: request.integrationId ?? null,
+                refresh: true,
                 credentialId: request.credentialId ?? null,
+                encryption: request.encryption ?? 'network',
+                ...(request.statusBinding ? { statusBinding: request.statusBinding } : {}),
+                ...(request.statusPurposes?.includes('suspension')
+                    ? { suspensionRequested: true }
+                    : {}),
             })
         )
         .digest('base64url');
 
+/** The v1 prefix identifies the request scheme, not the rotating key version. */
+export const getRefreshSendRequestDigestCandidates = (
+    request: Parameters<typeof computeRefreshSendRequestDigest>[0]
+): string[] =>
+    getCredentialRefreshDigestCandidateSecrets().map(secret =>
+        computeRefreshSendRequestDigest(request, secret)
+    );
+
+export const matchesRefreshSendRequestDigest = (
+    request: Parameters<typeof computeRefreshSendRequestDigest>[0],
+    stored: string
+): boolean => getRefreshSendRequestDigestCandidates(request).includes(stored);
+
 const parseIntent = (props: Record<string, unknown>): RefreshSendIntent => ({
     intentKey: props.intentKey as string,
     issuerProfileId: props.issuerProfileId as string,
@@ -76,6 +109,8 @@ const parseIntent = (props: Record<string, unknown>): RefreshSendIntent => ({
     credentialId: (props.credentialId as string | undefined) ?? undefined,
     refreshId: (props.refreshId as string | undefined) ?? undefined,
     holderDid: (props.holderDid as string | undefined) ?? undefined,
+    contractUri: (props.contractUri as string | undefined) ?? undefined,
+    integrationId: (props.integrationId as string | undefined) ?? undefined,
     pendingReceipt: props.pendingReceipt
         ? (JSON.parse(props.pendingReceipt as string) as ManagedCredentialRefreshReceipt)
         : undefined,
@@ -97,6 +132,19 @@ export const getRefreshSendIntent = async (
     return node ? parseIntent(node.properties) : null;
 };
 
+/** Resolve the preparation even when the caller did not supply an idempotency key. */
+export const getRefreshSendIntentForRefresh = async (
+    issuerProfileId: string,
+    refreshId: string
+): Promise<RefreshSendIntent | null> => {
+    const result = await neogma.queryRunner.run(
+        'MATCH (i:RefreshSendIntent {issuerProfileId: $issuerProfileId, refreshId: $refreshId}) RETURN i',
+        { issuerProfileId, refreshId }
+    );
+    const node = result.records[0]?.get('i');
+    return node ? parseIntent(node.properties) : null;
+};
+
 /**
  * Creates or claims the intent for (issuer, idempotencyKey). Concurrency-safe through
  * the `refresh_send_intent_key_unique` constraint. Throws CONFLICT when the key was used
@@ -106,8 +154,10 @@ export const claimRefreshSendIntent = async (params: {
     issuerProfileId: string;
     idempotencyKey: string;
     requestDigest: string;
+    requestDigestCandidates?: string[];
 }): Promise<ClaimRefreshSendIntentResult> => {
     const { issuerProfileId, idempotencyKey, requestDigest } = params;
+    const requestDigestCandidates = params.requestDigestCandidates ?? [requestDigest];
     const claimToken = randomUUID();
     const now = new Date();
 
@@ -125,7 +175,7 @@ export const claimRefreshSendIntent = async (params: {
              WITH i
              WITH i WHERE i.state = 'preparing'
                       AND i.claimToken <> $claimToken
-                      AND i.requestDigest = $requestDigest
+                       AND i.requestDigest IN $requestDigestCandidates
                       AND i.updatedAt < $staleBefore
              SET i.claimToken = $claimToken, i.updatedAt = $now
          }
@@ -134,6 +184,7 @@ export const claimRefreshSendIntent = async (params: {
             intentKey: getIntentKey(issuerProfileId, idempotencyKey),
             issuerProfileId,
             requestDigest,
+            requestDigestCandidates,
             claimToken,
             now: now.toISOString(),
             staleBefore: new Date(now.getTime() - REFRESH_SEND_INTENT_STALE_MS).toISOString(),
@@ -141,7 +192,7 @@ export const claimRefreshSendIntent = async (params: {
     );
     const intent = parseIntent(result.records[0]!.get('i').properties);
 
-    if (intent.requestDigest !== requestDigest) {
+    if (!requestDigestCandidates.includes(intent.requestDigest)) {
         throw new TRPCError({
             code: 'CONFLICT',
             message: 'This idempotencyKey was already used for a different send request.',
@@ -173,7 +224,15 @@ const lostIntentClaim = (): TRPCError =>
 export const recordRefreshSendIntent = async (
     intent: RefreshSendIntent,
     fields: Partial<
-        Pick<RefreshSendIntent, 'boostUri' | 'credentialId' | 'refreshId' | 'holderDid'>
+        Pick<
+            RefreshSendIntent,
+            | 'boostUri'
+            | 'credentialId'
+            | 'refreshId'
+            | 'holderDid'
+            | 'contractUri'
+            | 'integrationId'
+        >
     > & { state?: 'prepared' }
 ): Promise<RefreshSendIntent> => {
     const result = await neogma.queryRunner.run(
@@ -265,6 +324,10 @@ export const reconcileBoundRefreshSendIntent = async (
         credentialUri: getManagedCredentialUri(root.rootId, domain),
         activityId: intent.pendingActivityId ?? '',
         refresh: intent.pendingReceipt,
+        statusManagement: getStatusManagement(
+            await getStatusEntriesForCredential(root.rootId),
+            domain
+        ),
     };
 
     await markRefreshSendIntentDelivered(intent, result);

package/src/helpers/send-contract.helpers.ts

@@ -0,0 +1,36 @@
+import { TRPCError } from '@trpc/server';
+import type { BoostInstance } from '@models';
+import type { ProfileType } from 'types/profile';
+import {
+    getContractDetailsByUri,
+    getContractTermsForProfile,
+    getWritersForContract,
+} from '@accesslayer/consentflowcontract/relationships/read';
+import { setRelatedBoostForContract } from '@accesslayer/consentflowcontract/relationships/create';
+
+/** Resolve current send permissions; delivery must recheck the returned terms transactionally. */
+export const resolveContractForSend = async (params: {
+    profile: ProfileType;
+    targetProfile: ProfileType;
+    boost: BoostInstance;
+    boostCreated: boolean;
+    contractUri?: string;
+}): Promise<Awaited<ReturnType<typeof getContractTermsForProfile>> | null> => {
+    const { profile, targetProfile, boost, boostCreated, contractUri } = params;
+    if (!contractUri) return null;
+
+    const details = await getContractDetailsByUri(decodeURIComponent(contractUri));
+    if (!details) {
+        throw new TRPCError({ code: 'NOT_FOUND', message: 'Could not find contract' });
+    }
+    const terms = await getContractTermsForProfile(targetProfile, details.contract);
+    const writers = await getWritersForContract(details.contract);
+    const allowed =
+        terms &&
+        writers.some(writer => writer.profileId === profile.profileId) &&
+        !terms.terms.deniedWriters?.includes(profile.profileId) &&
+        (!boost.category || terms.terms.write?.credentials?.categories?.[boost.category] === true);
+
+    if (boostCreated) await setRelatedBoostForContract(details.contract, boost);
+    return allowed ? terms : null;
+};

package/src/helpers/status-list.helpers.test.ts

@@ -1,10 +1,13 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 
-const mocks = vi.hoisted(() => ({ findOne: vi.fn(), session: vi.fn(), transaction: vi.fn() }));
+const mocks = vi.hoisted(() => ({ run: vi.fn(), session: vi.fn(), transaction: vi.fn() }));
 vi.mock('@environment', () => ({ environment: {} }));
-vi.mock('@models', () => ({ Credential: { findOne: mocks.findOne } }));
 vi.mock('@instance', () => ({
-    neogma: { driver: { session: mocks.session }, getTransaction: mocks.transaction },
+    neogma: {
+        driver: { session: mocks.session },
+        getTransaction: mocks.transaction,
+        queryRunner: { run: mocks.run },
+    },
 }));
 vi.mock('@helpers/learnCard.helpers', () => ({
     getLearnCard: vi.fn(),
@@ -13,6 +16,21 @@ vi.mock('@helpers/learnCard.helpers', () => ({
 
 import { setCredentialBitstringStatus } from './status-list.helpers';
 
+type StoredRow = { direct?: string; body?: string; entries?: string };
+
+/** Mock the stored-status lookup, then the issuer-owner lookup. */
+const mockStored = (row: StoredRow | null, owner: string | null = 'issuer') => {
+    const record = (values: Record<string, unknown>) => ({
+        get: (key: string) => values[key] ?? null,
+    });
+    mocks.run.mockImplementation(async (query: string) => {
+        if (query.includes('AS owner')) {
+            return { records: owner ? [record({ owner })] : [] };
+        }
+        return { records: row ? [record({ ...row })] : [] };
+    });
+};
+
 describe('stored credential status validation', () => {
     beforeEach(() => {
         vi.clearAllMocks();
@@ -21,7 +39,7 @@ describe('stored credential status validation', () => {
     it.each(['{truncated', 'null', '{}', '[null]', '[{}]', '"not an array"'])(
         'returns false for malformed status metadata (%s) without starting a status write',
         async statusEntries => {
-            mocks.findOne.mockResolvedValue({ statusEntries, credential: '{}' });
+            mockStored({ direct: statusEntries, body: '{}' });
             await expect(
                 setCredentialBitstringStatus('credential', 'revocation', true)
             ).resolves.toBe(false);
@@ -30,7 +48,7 @@ describe('stored credential status validation', () => {
     );
 
     it('returns false when legacy credential JSON cannot be parsed', async () => {
-        mocks.findOne.mockResolvedValue({ credential: '{truncated' });
+        mockStored({ body: '{truncated' });
         await expect(setCredentialBitstringStatus('credential', 'suspension', true)).resolves.toBe(
             false
         );
@@ -38,16 +56,15 @@ describe('stored credential status validation', () => {
     });
 
     it('returns false for valid empty metadata or a missing credential', async () => {
-        mocks.findOne
-            .mockResolvedValueOnce({ statusEntries: '[]', credential: '{}' })
-            .mockResolvedValueOnce(null);
+        mockStored({ direct: '[]', body: '{}' });
         expect(await setCredentialBitstringStatus('credential', 'revocation', true)).toBe(false);
+        mockStored(null);
         expect(await setCredentialBitstringStatus('missing', 'revocation', true)).toBe(false);
     });
 
     it('returns false when a valid entry cannot be updated', async () => {
-        mocks.findOne.mockResolvedValue({
-            statusEntries: JSON.stringify([
+        mockStored({
+            direct: JSON.stringify([
                 {
                     type: 'BitstringStatusListEntry',
                     statusPurpose: 'revocation',
@@ -61,8 +78,8 @@ describe('stored credential status validation', () => {
     });
 
     it('rejects malformed numeric coordinates before any status write', async () => {
-        mocks.findOne.mockResolvedValue({
-            statusEntries: JSON.stringify([
+        mockStored({
+            direct: JSON.stringify([
                 {
                     type: 'BitstringStatusListEntry',
                     statusPurpose: 'revocation',