@learncard/network-brain-service 3.17.0 → 3.19.0

package/src/routes/index.ts

@@ -9,7 +9,7 @@ import { CreateFastifyContextOptions } from '@trpc/server/adapters/fastify';
 import { OpenApiMeta } from 'trpc-to-openapi';
 import jwtDecode from 'jwt-decode';
 import * as Sentry from '@sentry/serverless';
-import { AUTH_GRANT_AUDIENCE_DOMAIN_PREFIX } from '@learncard/types';
+import { ACT_AS_HEADER, AUTH_GRANT_AUDIENCE_DOMAIN_PREFIX } from '@learncard/types';
 import { ContactMethodType } from '@learncard/types';
 
 import { RegExpTransformer } from '@learncard/helpers';
@@ -48,7 +48,11 @@ export type Context = {
         did: string;
         isChallengeValid: boolean;
         scope?: string;
+        isAuthGrant?: boolean;
+        actAsPolicy?: string;
+        onBehalfOf?: string;
     };
+    actAs?: string;
     contactMethod?: ContactMethodType;
     domain: string;
     tenant: ResolvedTenant;
@@ -84,6 +88,14 @@ export const createContext = async (
         | { req: { headers: Map<string, string> } }
 ): Promise<Context> => {
     const event = 'event' in options ? options.event : options.req;
+    const headerEntries =
+        'get' in event.headers
+            ? Array.from(event.headers as Map<string, string>)
+            : Object.entries(event.headers);
+    const rawActAs = headerEntries.find(
+        ([name]) => name.toLowerCase() === ACT_AS_HEADER.toLowerCase()
+    )?.[1];
+    const actAs = Array.isArray(rawActAs) ? rawActAs.join(',') : rawActAs;
     const authHeader =
         'get' in event.headers
             ? (event.headers as Map<string, string>).get('authorization')
@@ -141,6 +153,7 @@ export const createContext = async (
                 if (!challenge)
                     return {
                         user: { did, isChallengeValid: false, scope: AUTH_GRANT_NO_ACCESS_SCOPE },
+                        actAs,
                         domain,
                         tenant,
                         sourceIp,
@@ -148,6 +161,8 @@ export const createContext = async (
 
                 let isChallengeValid = false;
                 let scope = AUTH_GRANT_FULL_ACCESS_SCOPE;
+                let isAuthGrant = false;
+                let actAsPolicy: string | undefined;
 
                 // If the user is using a provisional auth token for a contact method:
                 if (challenge?.includes(CONTACT_METHOD_SESSION_PREFIX)) {
@@ -159,6 +174,7 @@ export const createContext = async (
                         if (!contactMethod) throw new TRPCError({ code: 'NOT_FOUND' });
                         return {
                             contactMethod,
+                            actAs,
                             domain,
                             tenant,
                             sourceIp,
@@ -166,9 +182,14 @@ export const createContext = async (
                     }
                     // If the user is using a real auth grant i.e. an API Token.
                 } else if (challenge?.includes(AUTH_GRANT_AUDIENCE_DOMAIN_PREFIX)) {
-                    const { isChallengeValid: _isChallengeValid, scope: _scope } =
-                        await isAuthGrantChallengeValidForDID(challenge, did);
-
+                    const {
+                        isChallengeValid: _isChallengeValid,
+                        scope: _scope,
+                        actAs: policy,
+                    } = await isAuthGrantChallengeValidForDID(challenge, did);
+
+                    isAuthGrant = true;
+                    actAsPolicy = policy;
                     isChallengeValid = _isChallengeValid;
                     scope = _scope;
                     // If the user is using a real challenge signed by their private key.
@@ -182,7 +203,8 @@ export const createContext = async (
                 Sentry.setUser({ id: did });
 
                 return {
-                    user: { did, isChallengeValid, scope },
+                    user: { did, isChallengeValid, scope, isAuthGrant, actAsPolicy },
+                    actAs,
                     domain,
                     tenant,
                     _guardianApprovalToken,
@@ -192,7 +214,7 @@ export const createContext = async (
         }
     }
 
-    return { domain, tenant, _guardianApprovalToken, sourceIp };
+    return { domain, tenant, _guardianApprovalToken, sourceIp, actAs };
 };
 
 export const openRoute = t.procedure
@@ -245,6 +267,55 @@ export const resolveProfileFromContextDid = async (
     return getProfileByDid(did);
 };
 
+type ActingUser = NonNullable<Context['user']> & { profile: ProfileType | null };
+
+const resolveActAs = async (
+    user: ActingUser,
+    actAs: string | undefined,
+    domain: string
+): Promise<ActingUser> => {
+    const requested = actAs?.trim();
+    if (!requested) return user;
+
+    const { profile } = user;
+    const prefix = `did:web:${domain}:users:`;
+    const profileId = requested.startsWith(prefix) ? requested.slice(prefix.length) : requested;
+    if (!profileId || /[:/?#]/.test(profileId)) {
+        throw new TRPCError({ code: 'BAD_REQUEST', message: 'Invalid act-as profile identifier' });
+    }
+
+    // Two DB lookups per request when the act-as header is present (target profile,
+    // then its managers) — acceptable at backend issuance volume; not worth caching.
+    const target = await getProfileByProfileId(profileId);
+    if (!target)
+        throw new TRPCError({ code: 'NOT_FOUND', message: 'Act-as target profile not found' });
+
+    const managers = await getProfilesThatManageAProfile(target.profileId);
+    if (!profile || !managers.some(manager => manager.profileId === profile.profileId)) {
+        throw new TRPCError({
+            code: 'FORBIDDEN',
+            message: `You do not manage profile "${profileId}".`,
+        });
+    }
+
+    const policy = user.actAsPolicy;
+    const permitted =
+        policy === '*' ||
+        policy
+            ?.split(',')
+            .map(id => id.trim())
+            .includes(target.profileId);
+    if (user.isAuthGrant && !permitted) {
+        throw new TRPCError({
+            code: 'FORBIDDEN',
+            message: `This API token may not act as "${profileId}". Grant actAs on the token.`,
+        });
+    }
+
+    Sentry.setUser({ id: target.profileId, username: target.displayName });
+    return { ...user, profile: target, did: target.did, onBehalfOf: profile.profileId };
+};
+
 export const didRoute = openRoute.use(async ({ ctx, next }) => {
     if (!ctx.user?.did) {
         throw new TRPCError({ code: 'UNAUTHORIZED' });
@@ -254,7 +325,11 @@ export const didRoute = openRoute.use(async ({ ctx, next }) => {
 
     if (profile) Sentry.setUser({ id: profile.profileId, username: profile.displayName });
 
-    return next({ ctx: { ...ctx, user: { ...ctx.user, profile } } });
+    const user = ctx.user.isChallengeValid
+        ? await resolveActAs({ ...ctx.user, profile }, ctx.actAs, ctx.domain)
+        : { ...ctx.user, profile };
+
+    return next({ ctx: { ...ctx, user } });
 });
 
 export const didAndChallengeRoute = didRoute.use(({ ctx, next }) => {
@@ -373,99 +448,100 @@ export const verifiedContactRoute = openRoute.use(async ({ ctx, next }) => {
 export type GuardianApprovalToken = {
     iss: string;
     sub: string;
-    iat: number;
+    iat?: number;
     exp: number;
     scope: string;
 };
 
+// Match the existing guardian UI's five-minute approval window.
+const GUARDIAN_APPROVAL_MAX_TTL_SECONDS = 5 * 60;
+const GUARDIAN_APPROVAL_CLOCK_SKEW_SECONDS = 60;
+
 export const guardianGatedRoute = profileRoute.use(async ({ ctx, next }) => {
     const { profile } = ctx.user;
     const guardianApprovalToken = ctx._guardianApprovalToken;
-
     const isChildAccount = await isProfileManaged(profile.profileId);
+    let guardianIdentity: { profileId: string; did: string } | undefined;
 
-    if (!isChildAccount) {
-        return next({
-            ctx: { ...ctx, isChildAccount: false, hasGuardianApproval: false },
-        });
-    }
-
-    if (!guardianApprovalToken) {
-        return next({
-            ctx: { ...ctx, isChildAccount: true, hasGuardianApproval: false },
-        });
-    }
-
-    try {
-        const learnCard = await getEmptyLearnCard();
-
-        const result = await learnCard.invoke.verifyPresentation(guardianApprovalToken, {
-            proofFormat: 'jwt',
-        });
-
-        if (result.errors.length > 0 || !result.checks.includes('JWS')) {
-            return next({
-                ctx: { ...ctx, isChildAccount: true, hasGuardianApproval: false },
-            });
-        }
-
-        const jwtPayload = jwtDecode<{ vp?: { proof?: { challenge?: string } }; nonce?: string }>(
-            guardianApprovalToken
-        );
-
-        const challengeStr = jwtPayload.vp?.proof?.challenge ?? jwtPayload.nonce;
-        if (!challengeStr) {
-            return next({
-                ctx: { ...ctx, isChildAccount: true, hasGuardianApproval: false },
-            });
-        }
-
-        let guardianClaims: GuardianApprovalToken;
+    if (isChildAccount && guardianApprovalToken) {
         try {
-            guardianClaims = JSON.parse(challengeStr);
-        } catch {
-            return next({
-                ctx: { ...ctx, isChildAccount: true, hasGuardianApproval: false },
-            });
-        }
-
-        if (!guardianClaims.exp || guardianClaims.exp * 1000 < Date.now()) {
-            return next({
-                ctx: { ...ctx, isChildAccount: true, hasGuardianApproval: false },
-            });
-        }
-
-        if (guardianClaims.scope !== 'guardian-approval') {
-            return next({
-                ctx: { ...ctx, isChildAccount: true, hasGuardianApproval: false },
-            });
-        }
-
-        const childDidWeb = getDidWeb(ctx.domain, profile.profileId);
-        if (guardianClaims.sub !== childDidWeb) {
-            return next({
-                ctx: { ...ctx, isChildAccount: true, hasGuardianApproval: false },
+            const learnCard = await getEmptyLearnCard();
+            const result = await learnCard.invoke.verifyPresentation(guardianApprovalToken, {
+                proofFormat: 'jwt',
             });
-        }
-
-        const managers = await getProfilesThatManageAProfile(profile.profileId);
-        const guardianProfile = managers.find(manager => {
-            const managerDidWeb = getDidWeb(ctx.domain, manager.profileId);
-            return guardianClaims.iss === managerDidWeb || guardianClaims.iss === manager.did;
-        });
 
-        if (!guardianProfile) {
-            return next({
-                ctx: { ...ctx, isChildAccount: true, hasGuardianApproval: false },
-            });
+            // Verifier warnings are advisory; errors and a missing JWS check are fatal.
+            // Identity and current manager authorization are checked independently below.
+            if (result.errors.length === 0 && result.checks.includes('JWS')) {
+                const jwtHeader = jwtDecode<{ kid?: string }>(guardianApprovalToken, {
+                    header: true,
+                });
+                const jwtPayload = jwtDecode<{
+                    iss?: string;
+                    vp?: { holder?: string; proof?: { challenge?: string } };
+                    nonce?: string;
+                }>(guardianApprovalToken);
+                const challenge = jwtPayload.vp?.proof?.challenge ?? jwtPayload.nonce;
+                const claims: GuardianApprovalToken | null =
+                    typeof challenge === 'string' ? JSON.parse(challenge) : null;
+                const now = Date.now() / 1000;
+                const signerDid =
+                    typeof jwtHeader.kid === 'string' ? jwtHeader.kid.split('#')[0] : undefined;
+
+                // Verification proves the key's signature; bind every identity claim to that key.
+                // Older clients omit iat. Allow clock skew without extending the signed lifetime
+                // or accepting a token whose actual expiry has passed.
+                if (
+                    claims &&
+                    signerDid &&
+                    jwtPayload.iss === signerDid &&
+                    jwtPayload.vp?.holder === signerDid &&
+                    claims.iss === signerDid &&
+                    typeof claims.exp === 'number' &&
+                    Number.isFinite(claims.exp) &&
+                    claims.exp > now &&
+                    claims.exp <=
+                        now +
+                            GUARDIAN_APPROVAL_MAX_TTL_SECONDS +
+                            GUARDIAN_APPROVAL_CLOCK_SKEW_SECONDS &&
+                    (claims.iat === undefined ||
+                        (typeof claims.iat === 'number' &&
+                            Number.isFinite(claims.iat) &&
+                            claims.iat <= now + GUARDIAN_APPROVAL_CLOCK_SKEW_SECONDS &&
+                            claims.exp > claims.iat &&
+                            claims.exp - claims.iat <= GUARDIAN_APPROVAL_MAX_TTL_SECONDS)) &&
+                    claims.scope === 'guardian-approval' &&
+                    claims.sub === getDidWeb(ctx.domain, profile.profileId)
+                ) {
+                    const managers = await getProfilesThatManageAProfile(profile.profileId);
+                    const guardian = managers.find(
+                        manager =>
+                            signerDid === manager.did ||
+                            signerDid === getDidWeb(ctx.domain, manager.profileId)
+                    );
+                    if (guardian) {
+                        guardianIdentity = { profileId: guardian.profileId, did: signerDid };
+                    } else {
+                        console.warn('guardian_approval: unauthorized_manager');
+                    }
+                } else {
+                    console.warn('guardian_approval: invalid_claims');
+                }
+            } else {
+                console.warn('guardian_approval: verification_failed');
+            }
+        } catch {
+            // Malformed or unverifiable presentations never authorize a guardian-only mutation.
+            console.warn('guardian_approval: malformed_or_unverifiable');
         }
-
-        return next({
-            ctx: { ...ctx, isChildAccount: true, hasGuardianApproval: true },
-        });
-    } catch {
-        return next({
-            ctx: { ...ctx, isChildAccount: true, hasGuardianApproval: false },
-        });
     }
+
+    return next({
+        ctx: {
+            ...ctx,
+            isChildAccount,
+            hasGuardianApproval: guardianIdentity !== undefined,
+            guardianIdentity,
+        },
+    });
 });

package/src/routes/skills.ts

@@ -241,7 +241,7 @@ export const skillsRouter = t.router({
 
                 if (rateCount > SEMANTIC_SEARCH_RATE_LIMIT_PER_MIN) {
                     throw new TRPCError({
-                        code: 'TOO_MANY_REQUESTS' as 'BAD_REQUEST',
+                        code: 'TOO_MANY_REQUESTS',
                         message: `Rate limit exceeded: max ${SEMANTIC_SEARCH_RATE_LIMIT_PER_MIN} semantic searches per minute`,
                     });
                 }

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';
@@ -5,6 +6,7 @@ import base64url from 'base64url';
 import {
     VC,
     UnsignedVC,
+    JWE,
     VP,
     VPValidator,
     VCValidator,
@@ -48,6 +50,7 @@ import { resolveRecipientLocale } from '@helpers/getRecipientLocale.helpers';
 import { logCredentialClaimed, logCredentialFailed } from '@helpers/activity.helpers';
 import { handleConnectionPromptsForCredentialClaim } from '@helpers/connectionPrompt.helpers';
 import { decryptInboxCredential } from '@helpers/inbox-encryption.helpers';
+import { getBitstringStatusListEntries } from '@learncard/helpers';
 import {
     EXHAUSTED,
     exhaustExchangeChallengeForToken,
@@ -347,6 +350,7 @@ async function handlePresentationForClaim(
     const verificationResult = await learnCard.invoke.verifyPresentation(verifiablePresentation, {
         challenge,
         domain,
+        proofPurpose: 'authentication',
     });
 
     if (verificationResult.errors.length > 0 || !verificationResult.checks.includes('proof')) {
@@ -405,13 +409,15 @@ async function handlePresentationForClaim(
         // Inject OBv3 skill alignments based on boost's framework/skills
         await injectObv3AlignmentsIntoCredentialForBoost(boostCredential, boost, domain);
 
-        const vc = (await issueCredentialWithSigningAuthority(
-            { type: 'profile', profile: saOwnerProfile },
-            boostCredential,
-            signingAuthorityForUser,
-            domain,
-            false
-        )) as VC;
+        const vc = (
+            await issueCredentialWithSigningAuthority(
+                { type: 'profile', profile: saOwnerProfile },
+                boostCredential,
+                signingAuthorityForUser,
+                domain,
+                false
+            )
+        ).credential as VC;
 
         // Mark the challenge as used
         await useClaimLinkForBoost(exchangeInfo.boostUri, exchangeInfo.challenge);
@@ -543,6 +549,7 @@ async function handleInboxClaimPresentation(
     const verificationResult = await learnCard.invoke.verifyPresentation(verifiablePresentation, {
         challenge,
         domain: ctx.domain,
+        proofPurpose: 'authentication',
     });
 
     if (verificationResult.errors.length > 0 || !verificationResult.checks.includes('proof')) {
@@ -594,19 +601,34 @@ async function handleInboxClaimPresentation(
     }
 
     const claimedCredentials: VC[] = [];
+    let deliveryEncryptionFailed = false;
 
     // Process each pending credential in parallel
     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 =
@@ -658,25 +680,40 @@ async function handleInboxClaimPresentation(
                 unsignedCredential.issuer = signingAuthorityForUser.relationship.did;
 
                 // Sign the credential
-                finalCredential = (await issueCredentialWithSigningAuthority(
-                    { type: 'profile', profile: issuerProfile },
-                    unsignedCredential,
-                    signingAuthorityForUser,
-                    ctx.domain,
-                    false // don't encrypt
-                )) as VC;
+                finalCredential = (
+                    await issueCredentialWithSigningAuthority(
+                        { type: 'profile', profile: issuerProfile },
+                        unsignedCredential,
+                        signingAuthorityForUser,
+                        ctx.domain,
+                        false // don't encrypt
+                    )
+                ).credential as VC;
             }
 
-            // Avoid the seeded encryption wrapper, which adds the service as a recipient.
-            const deliveryLearnCard = await getEmptyLearnCard();
-            const encryptedDelivery = await deliveryLearnCard.invoke.createDagJwe(finalCredential, [
-                holderDid,
-            ]);
-            const finalized = await finalizeAndWipeInboxCredential(inboxCredential.id, {
-                recipientDid: holderDid,
-                credential: encryptedDelivery,
-            });
-            if (!finalized) throw new Error('Inbox credential is no longer pending');
+            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;
+                }
+                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.
@@ -690,14 +727,18 @@ 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);
 
                     if (boost && issuerProfile) {
                         // Store the credential in the database
-                        const credentialInstance = await storeCredential(encryptedDelivery);
+                        const credentialInstance = await storeCredential({
+                            kind: 'issued-credential',
+                            credential: encryptedDelivery!,
+                            statusEntries: getBitstringStatusListEntries(finalCredential),
+                        });
 
                         // Create the boost instance relationship
                         await createBoostInstanceOfRelationship(credentialInstance, boost);
@@ -868,6 +909,14 @@ async function handleInboxClaimPresentation(
 
     const settledCredentials = await Promise.all(credentialProcessingPromises);
     const inboxDeliveries = settledCredentials.filter(c => c !== null);
+    if (inboxDeliveries.length === 0 && deliveryEncryptionFailed) {
+        // Preserve the pending credentials and challenge so a compatible holder can retry.
+        throw new TRPCError({
+            code: 'BAD_REQUEST',
+            message:
+                'Unable to encrypt inbox delivery. The holder DID must resolve to a supported X25519 key-agreement method.',
+        });
+    }
     claimedCredentials.push(...inboxDeliveries.map(delivery => delivery.credential));
 
     // Create response VP with all claimed credentials

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;
                 }
             }
         }
@@ -217,6 +223,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;