@learncard/network-brain-service 3.17.0 → 3.19.0

package/src/helpers/inbox.helpers.ts

@@ -1,4 +1,19 @@
+import { environment } from '@environment';
+import { recordInboxRefreshClaimUrl } from '@accesslayer/inbox-credential/refresh';
+import { randomUUID } from 'node:crypto';
+import {
+    assertInboxRefreshEnabled,
+    prepareInboxRefresh,
+    getInboxRefreshReceipt,
+    finalizeInboxRefresh,
+    getInboxRefreshIssueKey,
+    resumeInboxRefreshDelivery,
+} from './inbox-refresh.helpers';
 import { TRPCError } from '@trpc/server';
+import {
+    InboxDeliveryCheckpointError,
+    InboxIssuancePreflightError,
+} from './inbox-issuance-error.helpers';
 import {
     VC,
     UnsignedVC,
@@ -12,6 +27,8 @@ import {
 } from '@learncard/types';
 
 import { ProfileType, SigningAuthorityForUserType } from 'types/profile';
+import type { IssuedCredential } from 'types/credential';
+import { getBitstringStatusListEntries } from '@learncard/helpers';
 import { createInboxCredential } from '@accesslayer/inbox-credential/create';
 import { Context } from '@routes';
 import { getAppDidWeb } from '@helpers/did.helpers';
@@ -30,7 +47,7 @@ import { doesProfileManageProfile } from '@accesslayer/profile-manager/relations
 import { getProfilesThatManageAProfile } from '@accesslayer/profile/relationships/read';
 import { getProfileForInboxCredential } from '@accesslayer/inbox-credential/read';
 import { sendCredential } from '@helpers/credential.helpers';
-import { sendBoost } from '@helpers/boost.helpers';
+import { prepareCredentialFromBoost, getBoostUri, sendBoost } from '@helpers/boost.helpers';
 import { getBoostByUri } from '@accesslayer/boost/read';
 import { issueCredentialWithSigningAuthority } from '@helpers/signingAuthority.helpers';
 import { getSigningAuthorityForUserByName } from '@accesslayer/signing-authority/relationships/read';
@@ -105,14 +122,16 @@ export const claimIntoInbox = async (
                 ? getAppDidWeb(ctx.domain, listingSlug)
                 : undefined;
 
-            finalCredential = (await issueCredentialWithSigningAuthority(
-                { type: 'profile', profile: issuerProfile },
-                credential as UnsignedVC,
-                signingAuthorityForUser,
-                ctx.domain,
-                false, // don't encrypt
-                ownerDidOverride
-            )) as VC;
+            finalCredential = (
+                await issueCredentialWithSigningAuthority(
+                    { type: 'profile', profile: issuerProfile },
+                    credential as UnsignedVC,
+                    signingAuthorityForUser,
+                    ctx.domain,
+                    false, // don't encrypt
+                    ownerDidOverride
+                )
+            ).credential as VC;
         }
 
         // Use the explicit-recipient API; the seeded encryption plugin also adds the service DID.
@@ -124,7 +143,11 @@ export const claimIntoInbox = async (
         await sendCredential(
             issuerProfile,
             existingProfile,
-            encryptedDelivery,
+            {
+                kind: 'issued-credential',
+                credential: encryptedDelivery,
+                statusEntries: getBitstringStatusListEntries(finalCredential),
+            },
             ctx.domain,
             undefined,
             activityId,
@@ -184,9 +207,15 @@ export const issueToInbox = async (
         activityId?: string;
         integrationId?: string;
         guardianEmail?: string;
+        refresh?: boolean;
+        idempotencyKey?: string;
+        refreshRequestDigest?: string;
     } = {},
-    ctx: Context
+    ctx: Context,
+    /** Queue ownership checkpoint immediately before delivery or inbox persistence. */
+    beforeDelivery?: () => Promise<void>
 ): Promise<{
+    refresh?: import('@learncard/types').InboxCredentialRefreshReceipt;
     status: 'PENDING' | 'ISSUED' | 'EXPIRED' | 'DELIVERED' | 'CLAIMED'; // DELIVERED & CLAIMED are deprecated, use ISSUED
     inboxCredential: InboxCredentialType;
     claimUrl?: string;
@@ -203,13 +232,35 @@ export const issueToInbox = async (
         integrationId,
         guardianEmail,
     } = configuration;
+    if (configuration.refresh) {
+        await assertInboxRefreshEnabled(ctx.user?.scope);
+        if (
+            credential.proof ||
+            credential.type.includes('VerifiablePresentation') ||
+            Array.isArray(credential.credentialSubject)
+        ) {
+            throw new TRPCError({
+                code: 'BAD_REQUEST',
+                message:
+                    'Inbox refresh requires an unsigned credential with a single subject and a signing authority.',
+            });
+        }
+    }
     const isSigned = !!credential?.proof;
     let signingAuthority: IssueInboxSigningAuthority | undefined = _signingAuthority;
+    let deliveryCheckpointReached = beforeDelivery === undefined;
+    const checkpointDelivery = async (): Promise<void> => {
+        await beforeDelivery?.();
+        deliveryCheckpointReached = true;
+    };
+    const assertDeliveryCheckpoint = (result: InboxDeliveryCheckpointError['result']): void => {
+        if (!deliveryCheckpointReached) throw new InboxDeliveryCheckpointError(result);
+    };
 
     if (recipient.type === 'phone') {
         const isTrusted = await getRegistryService().isTrusted(issuerProfile.did);
         if (!isTrusted) {
-            throw new TRPCError({
+            throw new InboxIssuancePreflightError({
                 code: 'FORBIDDEN',
                 message:
                     'Sending credentials via phone is a feature reserved for members of the LearnCard Trusted Registry. Email delivery is available for all issuers. To verify your issuer, visit: https://docs.learncard.com/how-to-guides/verify-my-issuer',
@@ -237,20 +288,35 @@ export const issueToInbox = async (
              * By providing this parameter, the developer explicitly takes responsibility for the signing process. We trust them and proceed.
              **/
             if (!(await verifyCredentialCanBeSigned(credential as UnsignedVC))) {
-                throw new TRPCError({
+                throw new InboxIssuancePreflightError({
                     code: 'BAD_REQUEST',
                     message:
                         'Credential failed to pass a pre-flight issuance test. Please verify that the credential is well-formed and can be issued.',
                 });
             }
         } else {
-            throw new TRPCError({
+            throw new InboxIssuancePreflightError({
                 code: 'BAD_REQUEST',
                 message: 'Unsigned credentials require a signing authority',
             });
         }
     }
 
+    if (
+        configuration.refresh &&
+        (!signingAuthority ||
+            !(await getSigningAuthorityForUserByName(
+                issuerProfile,
+                signingAuthority.endpoint,
+                signingAuthority.name
+            )))
+    ) {
+        throw new TRPCError({
+            code: 'NOT_FOUND',
+            message: 'Signing authority not found for issuer',
+        });
+    }
+
     // Check if recipient already exists with verified email
     const existingProfile = await getProfileByVerifiedContactMethod(
         recipient.type,
@@ -264,7 +330,7 @@ export const issueToInbox = async (
         : [];
     const recipientIsManaged = recipientManagers.length > 0;
 
-    if (existingProfile && !guardianEmail && !recipientIsManaged) {
+    if (existingProfile && !guardianEmail && !recipientIsManaged && !configuration.refresh) {
         // Auto-deliver to existing user
         let finalCredential: VC;
 
@@ -279,19 +345,21 @@ export const issueToInbox = async (
             );
 
             if (!signingAuthorityForUser) {
-                throw new TRPCError({
+                throw new InboxIssuancePreflightError({
                     code: 'NOT_FOUND',
                     message: 'Signing authority not found for issuer',
                 });
             }
 
-            finalCredential = (await issueCredentialWithSigningAuthority(
-                { type: 'profile', profile: issuerProfile },
-                credential as UnsignedVC,
-                signingAuthorityForUser,
-                ctx.domain,
-                false // don't encrypt
-            )) as VC;
+            finalCredential = (
+                await issueCredentialWithSigningAuthority(
+                    { type: 'profile', profile: issuerProfile },
+                    credential as UnsignedVC,
+                    signingAuthorityForUser,
+                    ctx.domain,
+                    false // don't encrypt
+                )
+            ).credential as VC;
         }
 
         // Send credential using appropriate helper (sendBoost handles boost tracking)
@@ -301,36 +369,30 @@ export const issueToInbox = async (
             existingProfile.did,
             issuerProfile.did,
         ]);
-        if (boostUri) {
-            const boost = await getBoostByUri(boostUri);
-            if (boost) {
-                await sendBoost({
-                    from: { type: 'profile', profile: issuerProfile },
-                    to: existingProfile,
-                    boost,
-                    credential: encryptedDelivery,
-                    domain: ctx.domain,
-                    skipCertification: true,
-                    activityId,
-                    integrationId,
-                });
-            } else {
-                // Fallback to sendCredential if boost not found
-                await sendCredential(
-                    issuerProfile,
-                    existingProfile,
-                    encryptedDelivery,
-                    ctx.domain,
-                    undefined,
-                    activityId,
-                    integrationId
-                );
-            }
+        // Carry only public status coordinates alongside the newly encrypted payload.
+        const delivery: IssuedCredential = {
+            kind: 'issued-credential',
+            credential: encryptedDelivery,
+            statusEntries: getBitstringStatusListEntries(finalCredential),
+        };
+        const boost = boostUri ? await getBoostByUri(boostUri) : undefined;
+        await checkpointDelivery();
+        if (boostUri && boost) {
+            await sendBoost({
+                from: { type: 'profile', profile: issuerProfile },
+                to: existingProfile,
+                boost,
+                credential: delivery,
+                domain: ctx.domain,
+                activityId,
+                integrationId,
+            });
         } else {
+            // Fall back to ordinary delivery when no boost exists for the supplied URI.
             await sendCredential(
                 issuerProfile,
                 existingProfile,
-                encryptedDelivery,
+                delivery,
                 ctx.domain,
                 undefined,
                 activityId,
@@ -357,6 +419,7 @@ export const issueToInbox = async (
             await logCredentialDelivered({
                 activityId,
                 actorProfileId: issuerProfile.profileId,
+                onBehalfOf: ctx.user?.onBehalfOf,
                 recipientType: recipient.type as 'email' | 'phone',
                 recipientIdentifier: recipient.value,
                 recipientProfileId: existingProfile.profileId,
@@ -405,6 +468,11 @@ export const issueToInbox = async (
             });
         }
 
+        assertDeliveryCheckpoint({
+            issuanceId: finalizedInboxCredential.id,
+            status: LCNInboxStatusEnumValidator.enum.ISSUED,
+            recipientDid: existingProfile.did,
+        });
         return {
             status: LCNInboxStatusEnumValidator.enum.ISSUED,
             inboxCredential: finalizedInboxCredential,
@@ -414,7 +482,24 @@ export const issueToInbox = async (
         // Store in inbox for claiming
         // Guardian gate if issuer specified guardianEmail OR recipient is a managed child
         const needsGuardianGate = !!guardianEmail || recipientIsManaged;
+        const preparedRefresh = configuration.refresh
+            ? await prepareInboxRefresh(credential, issuerProfile, ctx.domain)
+            : undefined;
+        if (preparedRefresh) credential = preparedRefresh.credential;
+        await checkpointDelivery();
         const inboxCredential = await createInboxCredential({
+            ...(preparedRefresh
+                ? {
+                      refresh: {
+                          aggregate: preparedRefresh.aggregate,
+                          issueKey: getInboxRefreshIssueKey(
+                              issuerProfile.profileId,
+                              configuration.idempotencyKey ?? randomUUID()
+                          ),
+                          requestDigest: configuration.refreshRequestDigest!,
+                      },
+                  }
+                : {}),
             credential: JSON.stringify(credential),
             isSigned,
             recipient,
@@ -429,6 +514,101 @@ export const issueToInbox = async (
             ...(needsGuardianGate ? { guardianStatus: 'AWAITING_GUARDIAN' as const } : {}),
         });
 
+        const refresh = inboxCredential.refreshId
+            ? await getInboxRefreshReceipt(inboxCredential.refreshId, ctx.domain)
+            : undefined;
+        if (refresh && existingProfile && !needsGuardianGate) {
+            await finalizeInboxRefresh({
+                inboxId: inboxCredential.id,
+                holderDid: existingProfile.did,
+                holderProfile: existingProfile,
+                domain: ctx.domain,
+                accepted: false,
+            });
+            await resumeInboxRefreshDelivery(refresh.refreshId, ctx.domain);
+            await createDeliveredRelationship(
+                issuerProfile.profileId,
+                inboxCredential.id,
+                existingProfile.did,
+                'auto-delivery'
+            );
+            if (activityId)
+                await logCredentialDelivered({
+                    activityId,
+                    actorProfileId: issuerProfile.profileId,
+                    onBehalfOf: ctx.user?.onBehalfOf,
+                    recipientType: recipient.type,
+                    recipientIdentifier: recipient.value,
+                    recipientProfileId: existingProfile.profileId,
+                    boostUri,
+                    inboxCredentialId: inboxCredential.id,
+                    integrationId,
+                    source: 'send',
+                });
+            if (webhookUrl)
+                await addNotificationToQueue({
+                    webhookUrl,
+                    type: LCNNotificationTypeEnumValidator.enum.ISSUANCE_DELIVERED,
+                    from: { did: (await getLearnCard()).id.did() },
+                    to: issuerProfile,
+                    message: getNotificationMessage(
+                        'issuanceDelivered',
+                        resolveRecipientLocale(issuerProfile),
+                        {
+                            issuer: issuerProfile.displayName,
+                            recipientType: recipient.type,
+                            recipientValue: recipient.value,
+                        }
+                    ),
+                    data: {
+                        inbox: {
+                            issuanceId: inboxCredential.id,
+                            status: LCNInboxStatusEnumValidator.enum.ISSUED,
+                            recipient: {
+                                contactMethod: recipient,
+                                learnCardId: existingProfile.did,
+                            },
+                            timestamp: new Date().toISOString(),
+                        },
+                    },
+                });
+            // Existing accounts receive the signed credential in their app inbox.
+            // Send the email there too, without a claim token for an already-bound delivery.
+            if (recipient.type === 'email' && !delivery?.suppress) {
+                try {
+                    const appUrl = environment.IS_OFFLINE
+                        ? generateClaimUrl('')
+                        : ctx.tenant?.emailBranding?.appUrl || generateClaimUrl('');
+                    await getDeliveryService(recipient).send({
+                        contactMethod: recipient,
+                        templateId: 'universal-inbox-claim',
+                        templateModel: {
+                            claimUrl: new URL('/notifications', appUrl).href,
+                            issuer: { name: issuerProfile.displayName },
+                            credential: { name: credential.name },
+                        },
+                        branding: ctx.tenant?.emailBranding,
+                        locale: resolveRecipientLocale(existingProfile),
+                        messageStream: 'universal-inbox',
+                    });
+                } catch {
+                    // The credential and in-app notification are already durable. An
+                    // email transport failure must not turn that delivery into an error.
+                    console.warn('Inbox refresh: initial email failed after auto-delivery.');
+                }
+            }
+            return {
+                status: 'ISSUED',
+                inboxCredential: {
+                    ...inboxCredential,
+                    currentStatus: 'ISSUED',
+                    credential: undefined,
+                },
+                recipientDid: existingProfile.did,
+                refresh: { ...refresh, holderDid: existingProfile.did },
+            };
+        }
+
         // Generate claim token
         let recipientContactMethod = await getContactMethodByValue(recipient.type, recipient.value);
         if (!recipientContactMethod) {
@@ -802,13 +982,84 @@ export const issueToInbox = async (
             expiresInDays ? 24 * expiresInDays : 24,
             false
         );
-        const claimUrl = generateClaimUrl(claimToken);
+        const claimUrl = refresh
+            ? await recordInboxRefreshClaimUrl(inboxCredential.id, generateClaimUrl(claimToken))
+            : generateClaimUrl(claimToken);
 
+        assertDeliveryCheckpoint({
+            issuanceId: inboxCredential.id,
+            status: LCNInboxStatusEnumValidator.enum.PENDING,
+            claimUrl,
+            ...(guardianEmail ? { guardianStatus: 'AWAITING_GUARDIAN' as const } : {}),
+        });
         return {
             status: LCNInboxStatusEnumValidator.enum.PENDING,
             inboxCredential,
             claimUrl,
+            ...(refresh ? { refresh } : {}),
             ...(guardianEmail ? { guardianStatus: 'AWAITING_GUARDIAN' as const } : {}),
         };
     }
 };
+
+/**
+ * Resolves an input into the credential that issueToInbox consumes. Keeping this outside either
+ * route makes direct credentials and Boost templates behave identically for single and batch
+ * issuance, including template rendering, Boost metadata, and standard client-facing errors.
+ */
+export const resolveInboxCredentialInput = async (
+    input: IssueInboxCredentialType,
+    ctx: Context
+): Promise<{ credential: VC | UnsignedVC | VP; resolvedBoostUri?: string }> => {
+    const { templateUri, configuration } = input;
+    // A direct credential wins when both fields are present, matching the existing single-route
+    // behavior. A template is only loaded when the caller supplied no credential.
+    let credential = input.credential;
+    let resolvedBoostUri: string | undefined;
+
+    if (templateUri && !credential) {
+        const boostInstance = await getBoostByUri(templateUri);
+
+        if (!boostInstance) {
+            throw new TRPCError({
+                code: 'NOT_FOUND',
+                message: `Boost not found: ${templateUri}`,
+            });
+        }
+
+        if (!boostInstance.dataValues.boost) {
+            throw new TRPCError({
+                code: 'BAD_REQUEST',
+                message: `Boost does not contain a credential template: ${templateUri}`,
+            });
+        }
+
+        try {
+            // Use shared helper to prepare credential with templateData rendering,
+            // issuance date, boostId injection, and OBv3 alignments
+            resolvedBoostUri = getBoostUri(boostInstance.id, ctx.domain);
+
+            credential = await prepareCredentialFromBoost(
+                boostInstance,
+                resolvedBoostUri,
+                ctx.domain,
+                { templateData: configuration?.templateData as Record<string, unknown> }
+            );
+        } catch (e) {
+            console.error('Failed to prepare boost credential', e);
+            throw new TRPCError({
+                code: 'BAD_REQUEST',
+                message: `Failed to prepare boost credential template: ${templateUri}`,
+            });
+        }
+    }
+
+    if (!credential) {
+        throw new TRPCError({
+            code: 'BAD_REQUEST',
+            message: 'Either credential or templateUri must be provided',
+        });
+    }
+
+    return { credential, resolvedBoostUri };
+};

package/src/helpers/issuedCredentialStatus.helpers.ts

@@ -0,0 +1,11 @@
+import type { JWE, UnsignedVC, VC } from '@learncard/types';
+import type { IssuedCredential } from '../types/credential';
+
+/** Internal envelopes never have the top-level fields of a wire-format VC or JWE. */
+export const isIssuedCredential = (
+    value: UnsignedVC | VC | JWE | IssuedCredential
+): value is IssuedCredential =>
+    !('@context' in value) && !('ciphertext' in value) && value.kind === 'issued-credential';
+
+export const getIssuedCredentialPayload = (value: VC | JWE | IssuedCredential): VC | JWE =>
+    isIssuedCredential(value) ? value.credential : value;

package/src/helpers/notifications.helpers.ts

@@ -223,8 +223,10 @@ export const buildCredentialRefreshedNotification = (
     return {
         notification: {
             type: LCNNotificationTypeEnumValidator.enum.CREDENTIAL_REFRESHED,
-            to: holderProfile,
-            from: issuerProfile,
+            // Local webhook delivery normalizes these DIDs in place. Keep the
+            // database profiles intact for the subsequent verified-email lookup.
+            to: { ...holderProfile },
+            from: { ...issuerProfile },
             message: getNotificationMessage(
                 'credentialRefreshed',
                 resolveRecipientLocale(holderProfile),

package/src/helpers/rateLimit.helpers.ts

@@ -24,7 +24,7 @@ export type RateLimitWindow = {
 };
 
 /**
- * Consume one unit against each window, in order, and throw once any is
+ * Consume the requested units against each window, in order, and throw once any is
  * exhausted.
  *
  * Fails CLOSED: if the cache is unavailable, `cache.incr` returns `undefined`
@@ -48,11 +48,8 @@ export const enforceRateLimits = async (windows: RateLimitWindow[]): Promise<voi
         }
 
         if (count > limit) {
-            // tRPC has no native 429; the existing convention in this service is
-            // to cast to BAD_REQUEST while keeping the semantic code, so clients
-            // can still discriminate on it.
             throw new TRPCError({
-                code: 'TOO_MANY_REQUESTS' as 'BAD_REQUEST',
+                code: 'TOO_MANY_REQUESTS',
                 message: `Rate limit exceeded: ${description}`,
             });
         }