@learncard/network-brain-service 4.1.2 → 5.0.0

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

@@ -7,6 +7,7 @@ import { environment } from '@environment';
 import {
     ConsentFlowTransactionValidator,
     ConsentFlowWebhookMetadataValidator,
+    ConsentFlowContractNotificationDataValidator,
     LCNNotificationTypeEnumValidator,
     type ConsentFlowTransaction,
     type ConsentFlowWebhookMetadata,
@@ -25,8 +26,10 @@ import { sanitizeProfileForTier, stripSensitiveProfileListFields } from './profi
 import { getStoredContractRequest } from '@accesslayer/consentflowcontract/read';
 import { resolveRecipientLocale } from './getRecipientLocale.helpers';
 import { ensureContractEventMaintenance } from './contract-event-maintenance.helpers';
+import { updateDidForProfile } from './did.helpers';
+import { buildContractUpdatePreview } from '@learncard/helpers';
 
-type EventKind = ConsentFlowWebhookMetadata['event'];
+type EventKind = ConsentFlowWebhookMetadata['event'] | 'contract_updated';
 const defaultDomain = (): string => environment.DOMAIN_NAME ?? 'network.learncard.com';
 
 const MAX_DELIVERY_ATTEMPTS = 12;
@@ -62,7 +65,7 @@ export const appendConsentEvent = (
     const kind: EventKind =
         transaction.action === 'consent'
             ? 'consent_created'
-            : transaction.action === 'update'
+            : transaction.action === 'update' || transaction.action === 'reconsent'
               ? 'consent_updated'
               : transaction.action === 'withdraw'
                 ? 'consent_withdrawn'
@@ -210,7 +213,7 @@ export const authorizeContractNotification = async (
     if (!relationship || !parsedTerms.success) return false;
     const terms = parsedTerms.data;
     if (
-        !(terms.status === 'live' || (terms.status === 'stale' && terms.oneTime)) ||
+        !(terms.status === 'live' || (terms.status === 'consumed' && terms.oneTime)) ||
         !expiryActive(terms.expiresAt) ||
         !expiryActive(relationship.contract.expiresAt)
     )
@@ -245,6 +248,35 @@ const buildNotification = async (
         getContractById(event.contractId),
     ]);
     if (!from || !to || !owner) return null;
+    if (event.kind === 'contract_updated') {
+        if (!contract) return null;
+        const data = ConsentFlowContractNotificationDataValidator.parse(
+            JSON.parse(event.payload ?? '')
+        );
+        const preview =
+            data.preview ??
+            buildContractUpdatePreview({
+                name: contract.name,
+                kind: data.kind,
+                diff: data.diff,
+            });
+        const sender = updateDidForProfile(event.domain, from);
+        return {
+            type: LCNNotificationTypeEnumValidator.enum.CONSENT_FLOW_CONTRACT_UPDATED,
+            from: {
+                ...stripSensitiveProfileListFields(
+                    sanitizeProfileForTier(sender, 'unauthenticated')
+                ),
+                did: sender.did,
+            },
+            to: updateDidForProfile(event.domain, to),
+            sent: event.createdAt,
+            ...(data.kind === 'requires_consent'
+                ? { message: { title: preview.headline, body: data.reason ?? preview.subhead } }
+                : {}),
+            data,
+        };
+    }
     const eventKind =
         delivery.role === 'requester' && event.requestAccepted ? 'request_accepted' : event.kind;
     const metadata = ConsentFlowWebhookMetadataValidator.parse({

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

@@ -99,7 +99,7 @@ export const sendGenericContractRequest = async (
         } AND CASE WHEN contract.expiresAt IS NULL OR trim(contract.expiresAt) = '' THEN true ELSE datetime(contract.expiresAt) > datetime($now) END
         AND NOT EXISTS {
             MATCH (target)-[:CREATED_BY]->(terms:ConsentFlowTerms)-[:CONSENTS_TO]->(contract)
-            WHERE (terms.status = 'live' OR (terms.status = 'stale' AND terms.oneTime = true)) AND
+            WHERE (terms.status = 'live' OR (terms.status = 'consumed' AND terms.oneTime = true)) AND
                 CASE WHEN terms.expiresAt IS NULL OR trim(terms.expiresAt) = '' THEN true ELSE datetime(terms.expiresAt) > datetime($now) END
         }
         OPTIONAL MATCH (contract)-[existing:REQUESTED_FOR]->(target)

package/src/helpers/contract.helpers.ts

@@ -5,7 +5,11 @@ import {
 } from '@learncard/types';
 import cloneDeep from 'lodash/cloneDeep';
 
-export const areTermsValid = (terms: ConsentFlowTermsInput, contract: ConsentFlowContractInput) => {
+export const areTermsValid = (
+    terms: ConsentFlowTermsInput,
+    contractSnapshot: ConsentFlowContractInput
+) => {
+    const contract = contractSnapshot;
     const contractPersonalReadKeys = Object.keys(contract.read?.personal ?? {});
     const contractPersonalWriteKeys = Object.keys(contract.write?.personal ?? {});
     const contractCategoryReadKeys = Object.keys(contract.read?.credentials?.categories ?? {});

package/src/helpers/credential-display.helpers.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, it } from 'vitest';
+import {
+    CredentialDisplayValidator,
+    PublishCredentialRefreshInputValidator,
+} from '@learncard/types';
+import { getPublicBoostDisplayName } from './credential-display.helpers';
+import { buildCredentialUpdatedEmailModel } from './credential-refresh-email-content.helpers';
+
+describe('public credential display', () => {
+    it('never infers an anchor title from private claims or the generic list label', () => {
+        const name = getPublicBoostDisplayName({
+            name: 'Credential',
+            boost: JSON.stringify({ displayOnlyAnchor: true, display: {}, name: 'PRIVATE CLAIM' }),
+        });
+        expect(name).toBeUndefined();
+        expect(
+            JSON.stringify(buildCredentialUpdatedEmailModel({ credentialTitle: name }))
+        ).not.toContain('PRIVATE CLAIM');
+    });
+
+    it('uses only explicit public display fields', () => {
+        const display = CredentialDisplayValidator.parse({
+            name: 'Public label',
+            claims: 'PRIVATE',
+        });
+        expect(display).toEqual({ name: 'Public label' });
+        expect(
+            getPublicBoostDisplayName({
+                boost: JSON.stringify({ displayOnlyAnchor: true, display }),
+            })
+        ).toBe('Public label');
+    });
+
+    it('leaves reusable Boost metadata unchanged', () => {
+        expect(getPublicBoostDisplayName({ name: 'Public template', boost: '{}' })).toBe(
+            'Public template'
+        );
+    });
+
+    it("does not mistake an ordinary Boost's own display object (e.g. app appearance fields) for a display-only anchor", () => {
+        // Real app-created BoostCredentials have their own top-level `display` object
+        // (backgroundImage, backgroundColor, displayType) — `'display' in boost` alone
+        // is not a safe anchor marker, unlike `displayOnlyAnchor`.
+        const name = getPublicBoostDisplayName({
+            name: 'Real Boost Name',
+            boost: JSON.stringify({
+                display: { backgroundColor: '#fff', backgroundImage: '', displayType: 'card' },
+            }),
+        });
+        expect(name).toBe('Real Boost Name');
+    });
+
+    it('bounds public summaries and rejects arbitrary update reasons', () => {
+        const input = {
+            refreshId: 'refresh',
+            mode: 'issuer-signed',
+            updateSummary: 'x'.repeat(281),
+            updateReason: 'PRIVATE',
+        };
+        const result = PublishCredentialRefreshInputValidator.safeParse(input);
+        expect(result.success).toBe(false);
+        if (!result.success) {
+            expect(result.error.issues.map(issue => issue.path[0])).toEqual(
+                expect.arrayContaining(['updateSummary', 'updateReason'])
+            );
+        }
+    });
+});

package/src/helpers/credential-display.helpers.ts

@@ -0,0 +1,15 @@
+import { CredentialDisplayValidator } from '@learncard/types';
+import { isDisplayOnlyAnchorTemplate } from '@learncard/helpers';
+
+/** Display-only anchors distinguish an omitted public name from the generic list label. */
+export const getPublicBoostDisplayName = (
+    boost: { boost: string; name?: string } | null | undefined
+): string | undefined => {
+    if (!boost) return undefined;
+    const template: unknown = JSON.parse(boost.boost);
+    if (isDisplayOnlyAnchorTemplate(template)) {
+        return CredentialDisplayValidator.parse((template as { display?: unknown }).display).name;
+    }
+    // Explicit reusable Boost/CMS metadata retains its existing public contract.
+    return boost.name;
+};

package/src/helpers/credential-refresh-email.helpers.ts

@@ -2,6 +2,7 @@ import { environment } from '@environment';
 import { generateClaimUrl } from './contact-method.helpers';
 import type { BoostInstance } from '@models';
 import { getBoostById } from '@accesslayer/boost/read';
+import { getPublicBoostDisplayName } from './credential-display.helpers';
 import { getContactMethodsForProfile } from '@accesslayer/contact-method/read';
 import {
     claimCredentialRefreshEmailDelivery,
@@ -84,29 +85,21 @@ export const resolveCredentialRefreshEmailTarget = async (
 };
 
 /**
- * Resolves the bounded email-only title: the persisted publish-input title first,
- * then the aggregate's coalesced title, then the original boost template name.
- * The holder-encrypted payload is never decrypted to recover a title.
+ * Only explicit public Boost display metadata can supply an email title.
+ * Historical publication titles may contain claims, so they are never used.
  */
 export const resolveCredentialRefreshEmailDisplayTitle = async (params: {
     version: CredentialRefreshVersionNode;
     refreshId: string;
 }): Promise<string | undefined> => {
-    const { version, refreshId } = params;
-    const fromVersion = extractBoundedCredentialDisplayTitle(version.credentialDisplayName);
-
-    if (fromVersion) return fromVersion;
-
+    const { refreshId } = params;
     const aggregate = await getCredentialRefresh(refreshId);
-    const fromAggregate = extractBoundedCredentialDisplayTitle(aggregate?.credentialDisplayName);
-
-    if (fromAggregate) return fromAggregate;
 
     if (!aggregate?.boostId) return undefined;
 
     const boost: BoostInstance | null = await getBoostById(aggregate.boostId);
 
-    return extractBoundedCredentialDisplayTitle(boost?.name);
+    return extractBoundedCredentialDisplayTitle(getPublicBoostDisplayName(boost));
 };
 
 /**

package/src/helpers/credential-refresh-materiality.helpers.test.ts

@@ -1,11 +1,148 @@
-import { describe, expect, it } from 'vitest';
+import { afterEach, describe, expect, it, vi } from 'vitest';
 
 import {
+    computeCredentialMaterialDigest,
+    matchesCredentialMaterialDigest,
+    matchesCredentialSubjectDigest,
+    getCredentialRefreshDigestCandidateSecrets,
+    decideCredentialRefreshNotification,
     computeCredentialSubjectDigest,
+    computeCredentialStatusDigest,
+    matchesCredentialStatusDigest,
     computeCredentialRefreshInitialDeliveryKey,
     computeCredentialRefreshRouteKey,
 } from './credential-refresh-materiality.helpers';
 
+describe('versioned status fingerprints', () => {
+    afterEach(() => vi.unstubAllEnvs());
+
+    it('matches current-version digests without parsing previous keys', () => {
+        vi.stubEnv('CREDENTIAL_REFRESH_DIGEST_KEY_VERSION', 'v2');
+        vi.stubEnv('CREDENTIAL_REFRESH_DIGEST_SECRET', 'current-test-key');
+        const status = { type: 'BitstringStatusListEntry', statusPurpose: 'revocation' };
+        const digest = computeCredentialStatusDigest(status);
+        // Startup validation is separate; current matches never consult old keys.
+        vi.stubEnv('CREDENTIAL_REFRESH_DIGEST_PREVIOUS_KEYS', 'invalid-json');
+        expect(getCredentialRefreshDigestCandidateSecrets('v2')).toEqual(['current-test-key']);
+        expect(matchesCredentialStatusDigest(status, digest)).toBe(true);
+        expect(() => getCredentialRefreshDigestCandidateSecrets('v1')).toThrow();
+    });
+
+    it('retains shape, array order and fields, and accepts unversioned current-key digests', () => {
+        const status = { type: 'BitstringStatusListEntry', statusPurpose: 'revocation' };
+        const digest = computeCredentialStatusDigest(status);
+        expect(digest).toMatch(/^v1:/);
+        expect(matchesCredentialStatusDigest(status, digest)).toBe(true);
+        expect(matchesCredentialStatusDigest(status, digest.split(':')[1])).toBe(true);
+        expect(matchesCredentialStatusDigest([status], digest)).toBe(false);
+        expect(matchesCredentialStatusDigest({ ...status, extra: true }, digest)).toBe(false);
+        expect(
+            matchesCredentialStatusDigest([status, {}], computeCredentialStatusDigest([{}, status]))
+        ).toBe(false);
+    });
+
+    it('accepts only current or explicitly retained previous keys', () => {
+        vi.stubEnv('CREDENTIAL_REFRESH_DIGEST_SECRET', 'old-test-key');
+        vi.stubEnv('CREDENTIAL_REFRESH_DIGEST_KEY_VERSION', 'v1');
+        const digest = computeCredentialStatusDigest({ type: 'example' });
+        vi.stubEnv('CREDENTIAL_REFRESH_DIGEST_SECRET', 'new-test-key');
+        vi.stubEnv('CREDENTIAL_REFRESH_DIGEST_KEY_VERSION', 'v2');
+        vi.stubEnv(
+            'CREDENTIAL_REFRESH_DIGEST_PREVIOUS_KEYS',
+            JSON.stringify({ v1: 'old-test-key' })
+        );
+        expect(matchesCredentialStatusDigest({ type: 'example' }, digest)).toBe(true);
+        expect(matchesCredentialStatusDigest({ type: 'example' }, digest.split(':')[1])).toBe(true);
+        vi.stubEnv('CREDENTIAL_REFRESH_DIGEST_PREVIOUS_KEYS', '{}');
+        expect(matchesCredentialStatusDigest({ type: 'example' }, digest)).toBe(false);
+    });
+});
+
+describe('subject and material digest key rotation', () => {
+    afterEach(() => vi.unstubAllEnvs());
+
+    it.each([false, true])('matches retained old keys (version prefix: %s)', prefixed => {
+        const subject = { id: 'holder' };
+        const credential = { credentialSubject: subject, name: 'Original' };
+        vi.stubEnv('CREDENTIAL_REFRESH_DIGEST_SECRET', 'old-test-key');
+        vi.stubEnv('CREDENTIAL_REFRESH_DIGEST_KEY_VERSION', 'v1');
+        vi.stubEnv('CREDENTIAL_REFRESH_DIGEST_PREVIOUS_KEYS', '{}');
+        const prefix = prefixed ? 'v1:' : '';
+        const subjectDigest = prefix + computeCredentialSubjectDigest(subject);
+        const materialDigest = prefix + computeCredentialMaterialDigest(credential);
+
+        vi.stubEnv('CREDENTIAL_REFRESH_DIGEST_SECRET', 'new-test-key');
+        vi.stubEnv('CREDENTIAL_REFRESH_DIGEST_KEY_VERSION', 'v2');
+        vi.stubEnv(
+            'CREDENTIAL_REFRESH_DIGEST_PREVIOUS_KEYS',
+            JSON.stringify({ v1: 'old-test-key' })
+        );
+        expect(getCredentialRefreshDigestCandidateSecrets()).toEqual([
+            'new-test-key',
+            'old-test-key',
+        ]);
+        expect(matchesCredentialSubjectDigest(subject, subjectDigest)).toBe(true);
+        expect(matchesCredentialMaterialDigest(credential, materialDigest)).toBe(true);
+        expect(matchesCredentialSubjectDigest({ id: 'other' }, subjectDigest)).toBe(false);
+        expect(
+            matchesCredentialMaterialDigest({ ...credential, name: 'Changed' }, materialDigest)
+        ).toBe(false);
+        expect(matchesCredentialSubjectDigest(subject, `unknown:${subjectDigest}`)).toBe(false);
+        expect(matchesCredentialMaterialDigest(credential, `unknown:${materialDigest}`)).toBe(
+            false
+        );
+        const nextDigest = computeCredentialMaterialDigest(credential);
+        expect(nextDigest).toBe(computeCredentialMaterialDigest(credential, 'new-test-key'));
+        expect(computeCredentialSubjectDigest(subject)).toBe(
+            computeCredentialSubjectDigest(subject, 'new-test-key')
+        );
+        expect(
+            decideCredentialRefreshNotification({
+                state: 'active',
+                previousDigest: matchesCredentialMaterialDigest(credential, materialDigest)
+                    ? nextDigest
+                    : materialDigest,
+                nextDigest,
+            })
+        ).toBe('suppressed');
+
+        vi.stubEnv('CREDENTIAL_REFRESH_DIGEST_PREVIOUS_KEYS', '{}');
+        expect(matchesCredentialSubjectDigest(subject, subjectDigest)).toBe(false);
+        expect(matchesCredentialMaterialDigest(credential, materialDigest)).toBe(false);
+    });
+
+    it('rejects missing digests and mismatched version prefixes', () => {
+        vi.stubEnv('CREDENTIAL_REFRESH_DIGEST_SECRET', 'current-test-key');
+        vi.stubEnv('CREDENTIAL_REFRESH_DIGEST_KEY_VERSION', 'v2');
+        vi.stubEnv(
+            'CREDENTIAL_REFRESH_DIGEST_PREVIOUS_KEYS',
+            JSON.stringify({ v1: 'old-test-key' })
+        );
+        const subject = { id: 'holder' };
+        const credential = { credentialSubject: subject };
+        expect(matchesCredentialSubjectDigest(subject)).toBe(false);
+        expect(matchesCredentialMaterialDigest(credential, '')).toBe(false);
+        expect(
+            matchesCredentialSubjectDigest(subject, `v1:${computeCredentialSubjectDigest(subject)}`)
+        ).toBe(false);
+        expect(
+            matchesCredentialMaterialDigest(
+                credential,
+                `v1:${computeCredentialMaterialDigest(credential)}`
+            )
+        ).toBe(false);
+        expect(
+            matchesCredentialSubjectDigest(subject, `v2:${computeCredentialSubjectDigest(subject)}`)
+        ).toBe(true);
+        expect(
+            matchesCredentialMaterialDigest(
+                credential,
+                `v2:${computeCredentialMaterialDigest(credential)}`
+            )
+        ).toBe(true);
+    });
+});
+
 describe('managed initial credential notification keys', () => {
     it('derives a stable opaque initial-delivery key from the refresh route key', () => {
         const secret = 'test-secret';

package/src/helpers/credential-refresh-materiality.helpers.ts

@@ -1,6 +1,9 @@
 import { createHmac } from 'crypto';
 
-import { getCredentialRefreshRuntimeEnvironment } from '@environment';
+import {
+    getCredentialRefreshRuntimeEnvironment,
+    getCredentialRefreshPreviousDigestKeys,
+} from '@environment';
 import { canonicalizeCredentialContent, canonicalizeCredentialJson } from '@learncard/helpers';
 import type { PublishCredentialRefreshNotification } from '@learncard/types';
 
@@ -37,6 +40,55 @@ export const getCredentialRefreshDigestSecret = (): string => {
     );
 };
 
+/**
+ * Returns current then explicitly retained previous HMAC secrets for legacy digests.
+ * A version prefix restricts matching to that version's key, just as status digests do.
+ * Candidates are read-only compatibility keys; new writes use the current secret.
+ * Rotate SECRET and KEY_VERSION together, retaining the old secret under its old
+ * version in CREDENTIAL_REFRESH_DIGEST_PREVIOUS_KEYS until all aggregates republish.
+ * Original subject/status/root fingerprints survive republishing, so retain their
+ * keys while those aggregates still need publication, repair, or initial-send retries.
+ * Notification route/delivery keys also rotate, potentially producing one duplicate
+ * notification across the rotation boundary.
+ */
+export const getCredentialRefreshDigestCandidateSecrets = (version?: string): string[] => {
+    const runtime = getCredentialRefreshRuntimeEnvironment();
+    const current = getCredentialRefreshDigestSecret();
+    if (version === runtime.CREDENTIAL_REFRESH_DIGEST_KEY_VERSION) return [current];
+    const previous = getCredentialRefreshPreviousDigestKeys();
+    if (version === undefined) return [current, ...Object.values(previous)];
+    return Object.prototype.hasOwnProperty.call(previous, version) ? [previous[version]!] : [];
+};
+
+const matchesStoredDigest = (
+    stored: string | undefined,
+    compute: (secret: string) => string
+): boolean => {
+    if (!stored) return false;
+    const separator = stored.indexOf(':');
+    const version = separator < 0 ? undefined : stored.slice(0, separator);
+    const digest = separator < 0 ? stored : stored.slice(separator + 1);
+    return getCredentialRefreshDigestCandidateSecrets(version).some(
+        secret => compute(secret) === digest
+    );
+};
+
+/** Matches persisted material fingerprints across explicitly retained key rotations. */
+export const matchesCredentialMaterialDigest = (
+    credential: CredentialLike,
+    stored?: string
+): boolean =>
+    matchesStoredDigest(stored, secret => computeCredentialMaterialDigest(credential, secret));
+
+/** Matches persisted subject identities across explicitly retained key rotations. */
+export const matchesCredentialSubjectDigest = (
+    credentialSubject: unknown,
+    stored?: string
+): boolean =>
+    matchesStoredDigest(stored, secret =>
+        computeCredentialSubjectDigest(credentialSubject, secret)
+    );
+
 /**
  * Keys excluded from the user-visible projection:
  *
@@ -96,11 +148,20 @@ export const computeCredentialStatusDigest = (
     credentialStatus: unknown,
     secret: string = getCredentialRefreshDigestSecret()
 ): string =>
+    `${getCredentialRefreshRuntimeEnvironment().CREDENTIAL_REFRESH_DIGEST_KEY_VERSION}:${statusDigest(credentialStatus, secret)}`;
+
+const statusDigest = (credentialStatus: unknown, secret: string): string =>
     createHmac('sha256', secret)
         .update('credential-status:v1\0')
         .update(canonicalizeCredentialJson(credentialStatus ?? null))
         .digest('base64url');
 
+/** Legacy fingerprints accept the current key or explicitly retained previous keys. */
+export const matchesCredentialStatusDigest = (
+    credentialStatus: unknown,
+    stored?: string
+): boolean => matchesStoredDigest(stored, secret => statusDigest(credentialStatus, secret));
+
 /** Keyed fingerprint matching the holder SDK's sorted subject identity comparison. */
 export const computeCredentialSubjectDigest = (
     credentialSubject: unknown,

package/src/helpers/credential-refresh-proof.helpers.test.ts

@@ -82,7 +82,7 @@ describe('managed refresh proof verification', () => {
             {
                 code: 'BAD_REQUEST',
                 message: 'Credential proof could not be verified',
-                cause,
+                cause: expect.objectContaining({ message: 'CREDENTIAL_PROOF_INVALID' }),
             }
         );
         expect(verifier.verifyCredential).toHaveBeenCalledTimes(retry ? 2 : 1);

package/src/helpers/credential-refresh-proof.helpers.ts

@@ -28,11 +28,11 @@ export const verifyManagedRefreshProof = async (
             result = await verifier.verifyCredential(credential, { checks: ['proof'] });
             if (proofVerified(result)) return;
         }
-    } catch (cause) {
+    } catch {
         throw new TRPCError({
             code: 'BAD_REQUEST',
             message: 'Credential proof could not be verified',
-            cause,
+            cause: 'CREDENTIAL_PROOF_INVALID',
         });
     }