@learncard/network-brain-service 3.18.0 → 3.19.1

package/src/routes/workflows.ts

@@ -1,3 +1,4 @@
+import { finalizeInboxRefresh } from '@helpers/inbox-refresh.helpers';
 import { TRPCError } from '@trpc/server';
 import { z } from 'zod';
 import base64url from 'base64url';
@@ -606,14 +607,28 @@ async function handleInboxClaimPresentation(
     const credentialProcessingPromises = pendingCredentials.map(async inboxCredential => {
         try {
             let finalCredential: VC;
-            const credentialPayload = await decryptInboxCredential(inboxCredential.credential);
-
-            if (inboxCredential.isSigned) {
+            const credentialPayload = inboxCredential.refreshId
+                ? undefined
+                : await decryptInboxCredential(inboxCredential.credential);
+
+            if (inboxCredential.refreshId) {
+                // A contact token authorizes delivery to the VP's DID. Never attach an unrelated
+                // contact profile's decryption key to that holder's refresh aggregate.
+                const boundProfile = await getProfileByDid(holderDid);
+                finalCredential = (
+                    await finalizeInboxRefresh({
+                        inboxId: inboxCredential.id,
+                        holderDid,
+                        holderProfile: boundProfile,
+                        domain: ctx.domain,
+                    })
+                ).credential;
+            } else if (inboxCredential.isSigned) {
                 // Credential is already signed
-                finalCredential = JSON.parse(credentialPayload) as VC;
+                finalCredential = JSON.parse(credentialPayload!) as VC;
             } else {
                 // Need to sign the credential using signing authority
-                const unsignedCredential = JSON.parse(credentialPayload) as UnsignedVC;
+                const unsignedCredential = JSON.parse(credentialPayload!) as UnsignedVC;
                 const inboxCredentialSigningAuthorityEndpoint =
                     (inboxCredential.signingAuthority?.endpoint as string) ?? undefined;
                 const inboxCredentialSigningAuthorityName =
@@ -676,25 +691,29 @@ async function handleInboxClaimPresentation(
                 ).credential as VC;
             }
 
-            // Avoid the seeded encryption wrapper, which adds the service as a recipient.
-            const deliveryLearnCard = await getEmptyLearnCard();
-            let encryptedDelivery: JWE;
-            try {
-                encryptedDelivery = await deliveryLearnCard.invoke.createDagJwe(finalCredential, [
-                    holderDid,
-                ]);
-                if (!encryptedDelivery.recipients?.length) {
-                    throw new Error('No supported delivery encryption recipients');
+            let encryptedDelivery: JWE | undefined;
+            if (!inboxCredential.refreshId) {
+                // Avoid the seeded encryption wrapper, which adds the service as a recipient.
+                const deliveryLearnCard = await getEmptyLearnCard();
+
+                try {
+                    encryptedDelivery = await deliveryLearnCard.invoke.createDagJwe(
+                        finalCredential,
+                        [holderDid]
+                    );
+                    if (!encryptedDelivery.recipients?.length) {
+                        throw new Error('No supported delivery encryption recipients');
+                    }
+                } catch (error) {
+                    deliveryEncryptionFailed = true;
+                    throw error;
                 }
-            } catch (error) {
-                deliveryEncryptionFailed = true;
-                throw error;
+                const finalized = await finalizeAndWipeInboxCredential(inboxCredential.id, {
+                    recipientDid: holderDid,
+                    credential: encryptedDelivery,
+                });
+                if (!finalized) throw new Error('Inbox credential is no longer pending');
             }
-            const finalized = await finalizeAndWipeInboxCredential(inboxCredential.id, {
-                recipientDid: holderDid,
-                credential: encryptedDelivery,
-            });
-            if (!finalized) throw new Error('Inbox credential is no longer pending');
 
             // Record the claim only after finalization succeeds so failed compare-and-swap
             // attempts cannot leave a misleading audit relationship behind.
@@ -708,7 +727,7 @@ async function handleInboxClaimPresentation(
 
             // Store credential and create boost relationship if this was a boost issuance
             const boostUri = inboxCredential.boostUri;
-            if (holderProfile && boostUri) {
+            if (!inboxCredential.refreshId && holderProfile && boostUri) {
                 try {
                     const boost = await getBoostByUri(boostUri);
                     const issuerProfile = await getProfileByDid(inboxCredential.issuerDid);
@@ -717,7 +736,7 @@ async function handleInboxClaimPresentation(
                         // Store the credential in the database
                         const credentialInstance = await storeCredential({
                             kind: 'issued-credential',
-                            credential: encryptedDelivery,
+                            credential: encryptedDelivery!,
                             statusEntries: getBitstringStatusListEntries(finalCredential),
                         });
 

package/src/services/delivery/adapters/postmark.adapter.test.ts

@@ -0,0 +1,54 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import type { Notification } from '../delivery.service';
+
+const mocks = vi.hoisted(() => ({ send: vi.fn(), legacySend: vi.fn(), render: vi.fn() }));
+vi.mock('@environment', () => ({ environment: {} }));
+vi.mock('postmark', () => ({
+    ServerClient: class {
+        sendEmail = mocks.send;
+        sendEmailWithTemplate = mocks.legacySend;
+    },
+}));
+vi.mock('@learncard/email-templates', () => ({
+    resolveBranding: () => ({}),
+    renderEmail: mocks.render,
+}));
+import { PostmarkAdapter } from './postmark.adapter';
+
+const notification: Notification = {
+    contactMethod: { type: 'email', value: 'holder@example.com' },
+    templateId: 'credential-updated',
+    templateModel: { issuer: { name: 'School' }, credential: { name: 'Biology' } },
+};
+
+beforeEach(() => {
+    vi.clearAllMocks();
+    mocks.render.mockResolvedValue({ html: '<p>Updated</p>', text: 'Updated', subject: 'Updated' });
+    mocks.send.mockResolvedValue({});
+});
+
+describe('update email provider attempts', () => {
+    it('sends the locally rendered update once', async () => {
+        await new PostmarkAdapter('test-key').send(notification);
+        expect(mocks.send).toHaveBeenCalledTimes(1);
+        expect(mocks.legacySend).not.toHaveBeenCalled();
+    });
+
+    it('does not try a legacy template after an ambiguous provider failure', async () => {
+        mocks.send.mockRejectedValueOnce(new Error('Acknowledgement lost'));
+        await expect(new PostmarkAdapter('test-key').send(notification)).rejects.toThrow(
+            'Acknowledgement lost'
+        );
+        expect(mocks.send).toHaveBeenCalledTimes(1);
+        expect(mocks.legacySend).not.toHaveBeenCalled();
+    });
+
+    it('fails without sending when the local update template cannot render', async () => {
+        mocks.render.mockRejectedValueOnce(new Error('Render failed'));
+        await expect(new PostmarkAdapter('test-key').send(notification)).rejects.toThrow(
+            'Render failed'
+        );
+        expect(mocks.send).not.toHaveBeenCalled();
+        expect(mocks.legacySend).not.toHaveBeenCalled();
+    });
+});

package/src/services/delivery/adapters/postmark.adapter.ts

@@ -41,6 +41,7 @@ const LOCAL_TEMPLATE_MAP: Record<string, TemplateId> = {
     'guardian-credential-approval': 'guardian-credential-approval',
     'guardian-email-otp': 'guardian-email-otp',
     'guardian-rejected-credential': 'guardian-rejected-credential',
+    'credential-updated': 'credential-updated',
 };
 
 export class PostmarkAdapter implements DeliveryService {
@@ -85,6 +86,8 @@ export class PostmarkAdapter implements DeliveryService {
                     `[PostmarkAdapter] Local render failed for "${notification.templateId}":`,
                     renderError
                 );
+                // This template is owned locally; there is no legacy provider alias.
+                if (notification.templateId === 'credential-updated') throw renderError;
             }
 
             if (rendered) {
@@ -104,6 +107,9 @@ export class PostmarkAdapter implements DeliveryService {
                         `[PostmarkAdapter] sendEmail API failed for "${notification.templateId}":`,
                         sendError
                     );
+                    // A lost provider acknowledgement may already have sent the email.
+                    // Do not bypass the refresh delivery claim with a second attempt.
+                    if (notification.templateId === 'credential-updated') throw sendError;
                 }
             }
         }
@@ -172,7 +178,10 @@ export class PostmarkAdapter implements DeliveryService {
                 };
 
             case 'recovery-key':
-                return { recoveryKey: model.recoveryKey };
+                return {
+                    recoveryKey: model.recoveryKey,
+                    confirmationCode: model.confirmationCode,
+                };
 
             case 'endorsement-request':
                 return {
@@ -217,6 +226,12 @@ export class PostmarkAdapter implements DeliveryService {
                     recipient: model.recipient,
                 };
 
+            case 'credential-updated':
+                return {
+                    issuer: model.issuer,
+                    credential: model.credential,
+                };
+
             default:
                 return model as TemplateDataMap[TemplateId];
         }

package/src/services/registry/registry.factory.ts

@@ -7,7 +7,8 @@ export const getRegistryService = (): RegistryService => {
     if (
         environment.NODE_ENV === 'test' ||
         environment.TRUSTED_ISSUERS_WHITELIST ||
-        environment.IS_CI
+        environment.IS_CI ||
+        environment.IS_E2E_TEST
     ) {
         return new WhitelistAdapter();
     }

package/src/types/activity.ts

@@ -33,6 +33,7 @@ export const CredentialActivityValidator = z.object({
     eventType: CredentialActivityEventTypeValidator,
     timestamp: z.string(),
     actorProfileId: z.string().optional(),
+    onBehalfOf: z.string().optional(),
     recipientType: CredentialActivityRecipientTypeValidator,
     recipientIdentifier: z.string(),
     boostUri: z.string().optional(),
@@ -85,6 +86,7 @@ export const CredentialActivityStatsValidator = z.object({
 export type CredentialActivityStats = z.infer<typeof CredentialActivityStatsValidator>;
 
 export type LogCredentialActivityParams = {
+    onBehalfOf?: string;
     actorProfileId?: string;
     eventType: CredentialActivityEventType;
     recipientType: CredentialActivityRecipientType;

package/src/types/credential-refresh.ts

@@ -12,17 +12,26 @@ import {
  * immutable Credential nodes as holder-encrypted JWE JSON — never plaintext VC JSON.
  */
 
-export const CredentialRefreshStateValidator = z.enum(['awaiting_claim', 'active', 'revoked']);
+export const CredentialRefreshStateValidator = z.enum([
+    'pending_holder',
+    'awaiting_claim',
+    'active',
+    'revoked',
+]);
 export type CredentialRefreshState = z.infer<typeof CredentialRefreshStateValidator>;
 
 /** The managed refresh aggregate node (metadata only — no credential bodies) */
 export const CredentialRefreshRecordValidator = z.object({
+    /** Pending Universal Inbox delivery associated with this aggregate. */
+    inboxCredentialId: z.string().optional(),
+    /** Public status mechanism coordinates retained for the issuer allocation receipt. */
+    inboxCredentialStatus: z.string().optional(),
     /** Cryptographically random, unguessable public route identifier */
     refreshId: z.string().min(1),
     issuerProfileId: z.string().min(1),
     issuerDid: z.string().min(1),
     holderProfileId: z.string().min(1).optional(),
-    holderDid: z.string().min(1),
+    holderDid: z.string().min(1).optional(),
     /** Stable nonempty VC identifier shared by every version */
     credentialId: z.string().min(1),
     state: CredentialRefreshStateValidator,
@@ -45,6 +54,12 @@ export const CredentialRefreshRecordValidator = z.object({
     idempotencyKey: z.string().optional(),
     /** Issuer-authored, privacy-safe update summary */
     updateSummary: z.string().optional(),
+    /**
+     * Bounded, normalized credential display title used only for the email update
+     * notice. Never rendered in in-app/push payloads. Sourced from the unsigned
+     * publish input or the original boost template; never from decrypted content.
+     */
+    credentialDisplayName: z.string().optional(),
     lastPublishedAt: z.string().optional(),
     /** Notification delivery window key used to collapse repeat notifications */
     notificationWindowKey: z.string().optional(),
@@ -93,6 +108,8 @@ export const CredentialRefreshVersionNodeValidator = z.object({
     etag: z.string().optional(),
     signingMode: CredentialRefreshSigningModeValidator,
     updateSummary: z.string().optional(),
+    /** Bounded credential display title for the email update notice only. */
+    credentialDisplayName: z.string().optional(),
     /** Caller-provided key for replaying this exact historical publication */
     idempotencyKey: z.string().optional(),
     /** Aggregate-scoped unique key used to enforce historical idempotency */
@@ -132,6 +149,8 @@ export const AdvanceCredentialRefreshHeadParamsValidator = z.object({
     materialDigest: z.string().optional(),
     signingMode: CredentialRefreshSigningModeValidator,
     updateSummary: z.string().optional(),
+    /** Bounded credential display title persisted for the email update notice only. */
+    credentialDisplayName: z.string().optional(),
     idempotencyKey: z.string().optional(),
     /** Aggregate state observed by the caller; prevents claim/revocation races. */
     expectedState: CredentialRefreshStateValidator.optional(),

package/src/types/inbox-batch.ts

@@ -0,0 +1,46 @@
+import type { InboxBatchStatus, IssueInboxCredentialBatch } from '@learncard/types';
+import type { Context } from '@routes';
+
+export type BatchItem = {
+    id: string;
+    batchId: string;
+    index: number;
+    state: InboxBatchStatus['items'][number]['state'];
+    phase?: 'PREPARING' | 'ISSUING';
+    owner?: string;
+    leaseUntil?: number;
+    attempts: number;
+    result?: string;
+    replayKey: string;
+    duplicate: boolean;
+    /** Encrypted client correlation fields retained after the batch payload is removed. */
+    correlation?: string;
+};
+
+export type InboxDispatchLease = { id: string; dispatchAt: number };
+
+export type BatchJob = {
+    id: string;
+    issuer: string;
+    createdAt: number;
+    payload?: string;
+    completedAt?: number;
+};
+
+export type BatchJobPayload = {
+    batch: IssueInboxCredentialBatch;
+    context: Pick<Context, 'domain' | 'tenant'>;
+    /** Submitting caller's permissions, retained for deferred refresh authorization. */
+    scope?: string;
+};
+
+export type BatchReplayStore = {
+    get: (key: string) => Promise<string | null | undefined>;
+    setIfAbsent: (key: string, value: string, ttl: number) => Promise<'OK' | null | undefined>;
+    compareAndSet: (
+        key: string,
+        expected: string,
+        value: string | null,
+        ttl: number
+    ) => Promise<boolean | undefined>;
+};

package/test/atomic-counter.e2e.ts

@@ -0,0 +1,12 @@
+import { afterAll, expect, it } from 'vitest';
+import cache from '@cache';
+import { testAtomicCacheCounter } from '../src/cache/atomic-counter.test-helpers';
+
+// Fail if the isolated Redis container is missing; never silently test the mock in CI.
+it('uses real Redis for the atomic counter contract', () => {
+    expect(cache.redis).toBeDefined();
+});
+testAtomicCacheCounter(cache);
+afterAll(async () => {
+    await cache.redis?.quit();
+});

package/test/auth-grant.spec.ts

@@ -200,7 +200,7 @@ describe('Auth Grants', () => {
 
             const authGrants = await userA.clients.fullAuth.authGrants.getAuthGrants();
             expect(authGrants).toHaveLength(1);
-            expect((authGrants[0] as any).id).toEqual(authGrantId);
+            expect(authGrants[0]?.id).toEqual(authGrantId);
 
             await userA.clients.fullAuth.authGrants.addAuthGrant({
                 name: 'test2',
@@ -209,8 +209,8 @@ describe('Auth Grants', () => {
             const authGrants2 = await userA.clients.fullAuth.authGrants.getAuthGrants();
 
             expect(authGrants2).toHaveLength(2);
-            expect(authGrants2[0] as any).toBeDefined();
-            expect(authGrants2[1] as any).toBeDefined();
+            expect(authGrants2[0]).toBeDefined();
+            expect(authGrants2[1]).toBeDefined();
         });
 
         it('should accept a limit', async () => {
@@ -247,7 +247,7 @@ describe('Auth Grants', () => {
             });
 
             expect(authGrants).toHaveLength(1);
-            expect((authGrants[0] as any).id).toEqual(authGrantId);
+            expect(authGrants[0]?.id).toEqual(authGrantId);
         });
     });
 
@@ -278,17 +278,18 @@ describe('Auth Grants', () => {
                 id: authGrantId,
             });
 
-            expect((updatedAuthGrant as any).name).toEqual('test2');
+            expect(updatedAuthGrant?.name).toEqual('test2');
         });
 
-        it('should not allow you to update the scopes, challenge, id, createdAt, expiresAt, status of an auth grant', async () => {
+        it('should reject updates to the scopes, actAs, challenge, id, createdAt, expiresAt, status of an auth grant', async () => {
             await userA.clients.fullAuth.profile.createProfile({ profileId: 'usera' });
             const authGrantId = await userA.clients.fullAuth.authGrants.addAuthGrant({
                 name: 'test',
             });
 
-            const invalidUpdates: any = {
+            const invalidUpdates: Record<string, string> = {
                 scope: '*:*',
+                actAs: '*',
                 challenge: 'test',
                 id: 'test',
                 createdAt: 'test',
@@ -296,27 +297,26 @@ describe('Auth Grants', () => {
                 status: 'revoked',
             };
 
-            for (const key in invalidUpdates) {
+            for (const [key, value] of Object.entries(invalidUpdates)) {
                 await expect(
                     userA.clients.fullAuth.authGrants.updateAuthGrant({
                         id: authGrantId,
-                        updates: {
-                            [key]: invalidUpdates[key],
-                        },
+                        updates: { [key]: value } as never,
                     })
-                ).resolves.toBe(false);
+                ).rejects.toMatchObject({ code: 'BAD_REQUEST' });
             }
 
             const updatedAuthGrant = await userA.clients.fullAuth.authGrants.getAuthGrant({
                 id: authGrantId,
             });
 
-            expect((updatedAuthGrant as any).scope).toEqual(AUTH_GRANT_READ_ONLY_SCOPE);
-            expect((updatedAuthGrant as any).challenge).not.toEqual('test');
-            expect((updatedAuthGrant as any).id).not.toEqual('test');
-            expect((updatedAuthGrant as any).createdAt).not.toEqual('test');
-            expect((updatedAuthGrant as any).expiresAt).not.toEqual('test');
-            expect((updatedAuthGrant as any).status).not.toEqual('revoked');
+            expect(updatedAuthGrant).toMatchObject({ scope: AUTH_GRANT_READ_ONLY_SCOPE });
+            expect(updatedAuthGrant?.challenge).not.toEqual('test');
+            expect(updatedAuthGrant?.id).not.toEqual('test');
+            expect(updatedAuthGrant?.createdAt).not.toEqual('test');
+            expect(updatedAuthGrant?.expiresAt).not.toEqual('test');
+            expect(updatedAuthGrant?.status).not.toEqual('revoked');
+            expect(updatedAuthGrant?.actAs).toBeUndefined();
         });
 
         // it('should not allow you to update an auth grant for a scoped user profile', async () => {
@@ -366,7 +366,7 @@ describe('Auth Grants', () => {
                 id: authGrantId,
             });
 
-            expect((updatedAuthGrant as any).name).toEqual('test2');
+            expect(updatedAuthGrant?.name).toEqual('test2');
         });
 
         it("should not allow you to update someone else's auth grant", async () => {
@@ -511,7 +511,7 @@ describe('Auth Grants', () => {
                 id: authGrantId,
             });
 
-            expect((authGrant as any).status).toEqual(AuthGrantStatusValidator.enum.revoked);
+            expect(authGrant?.status).toEqual(AuthGrantStatusValidator.enum.revoked);
         });
 
         // it('should not allow you to revoke an auth grant for a scoped user profile', async () => {
@@ -552,7 +552,7 @@ describe('Auth Grants', () => {
                 id: authGrantId,
             });
 
-            expect((authGrant as any).status).toEqual(AuthGrantStatusValidator.enum.revoked);
+            expect(authGrant?.status).toEqual(AuthGrantStatusValidator.enum.revoked);
         });
 
         it("should not allow you to revoke someone else's auth grant", async () => {