@learncard/network-brain-service 3.18.0 → 3.19.0

package/lambda.ts

@@ -25,6 +25,10 @@ import {
 import { environment } from './src/config/environment';
 import { toServerlessApplication } from './src/helpers/serverlessApplication';
 import { runInboxMaintenance } from './src/helpers/inbox-maintenance.helpers';
+import {
+    inboxBatchResponseMeta,
+    withInboxBatchBodyLimit,
+} from './src/helpers/inbox-batch-http.helpers';
 
 Sentry.AWSLambda.init({
     dsn: environment.SENTRY_DSN,
@@ -61,8 +65,9 @@ export const credentialRefreshHandler: typeof credentialRefreshProxy = async (ev
 
 export const _openApiHandler = createOpenApiAwsLambdaHandler({
     router: appRouter,
-    responseMeta: () => {
+    responseMeta: meta => {
         return {
+            ...inboxBatchResponseMeta(meta),
             headers: {
                 'Access-Control-Allow-Origin': '*',
                 'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS',
@@ -74,21 +79,24 @@ export const _openApiHandler = createOpenApiAwsLambdaHandler({
     onError: handleTrpcError,
 });
 
-export const _trpcHandler = awsLambdaRequestHandler({
-    allowMethodOverride: true,
-    router: appRouter,
-    createContext,
-    onError: handleTrpcError,
-    responseMeta: () => {
-        return {
-            headers: {
-                'Access-Control-Allow-Origin': '*',
-                'Access-Control-Allow-Methods': '*',
-                'Access-Control-Allow-Headers': 'authorization',
-            },
-        };
-    },
-});
+export const _trpcHandler = withInboxBatchBodyLimit(
+    awsLambdaRequestHandler({
+        allowMethodOverride: true,
+        router: appRouter,
+        createContext,
+        onError: handleTrpcError,
+        responseMeta: () => {
+            return {
+                headers: {
+                    'Access-Control-Allow-Origin': '*',
+                    'Access-Control-Allow-Methods': '*',
+                    'Access-Control-Allow-Headers': 'authorization',
+                },
+            };
+        },
+    }),
+    'trpc'
+);
 
 export const openApiHandler = Sentry.AWSLambda.wrapHandler(
     async (event: APIGatewayProxyEventV2, context: Context): Promise<APIGatewayProxyResultV2> => {
@@ -124,6 +132,43 @@ export const trpcHandler = Sentry.AWSLambda.wrapHandler(
     }
 );
 
+export const inboxQueueWorker: SQSHandler = Sentry.AWSLambda.wrapHandler(async event => {
+    const { processInboxQueueMessage } = await import('./src/helpers/inbox-queue.helpers');
+    const batchItemFailures = [];
+    for (const record of event.Records) {
+        try {
+            await processInboxQueueMessage(record.body);
+        } catch {
+            console.error('Inbox worker message failed', { messageId: record.messageId });
+            batchItemFailures.push({ itemIdentifier: record.messageId });
+        }
+    }
+    return { batchItemFailures } satisfies SQSBatchResponse;
+});
+
+export const inboxQueueDispatcher = Sentry.AWSLambda.wrapHandler(
+    async (_event: unknown, context: Context): Promise<void> => {
+        const { dispatchInboxJobs } = await import('./src/helpers/inbox-queue.helpers');
+        // Share one clock across publication and recovery, retaining five seconds for shutdown.
+        const deadline = Date.now() + Math.max(0, context.getRemainingTimeInMillis() - 5_000);
+        await dispatchInboxJobs(deadline);
+    }
+);
+
+export const inboxDeadLetterWorker: SQSHandler = Sentry.AWSLambda.wrapHandler(async event => {
+    const { processInboxDeadLetter } = await import('./src/helpers/inbox-queue.helpers');
+    const batchItemFailures = [];
+    for (const record of event.Records) {
+        try {
+            await processInboxDeadLetter(record.body);
+        } catch {
+            console.error('Inbox dead-letter processing failed', { messageId: record.messageId });
+            batchItemFailures.push({ itemIdentifier: record.messageId });
+        }
+    }
+    return { batchItemFailures } satisfies SQSBatchResponse;
+});
+
 export const notificationsWorker: SQSHandler = Sentry.AWSLambda.wrapHandler(async event => {
     const batchItemFailures = await Promise.all(
         event.Records.map(async record => {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@learncard/network-brain-service",
-    "version": "3.18.0",
+    "version": "3.19.0",
     "description": "",
     "engines": {
         "node": ">=24.12 <25"
@@ -9,6 +9,8 @@
     "main": "dist/index.js",
     "types": "dist/index.d.ts",
     "scripts": {
+        "inbox:setup-queues": "bun scripts/setup-inbox-queues.ts",
+        "inbox:worker": "bun --conditions=development src/inbox-queue-local.ts",
         "test": "vitest run --config vitest.config.ts",
         "test:watch": "vitest --config vitest.config.ts",
         "test:coverage": "vitest run --coverage --config vitest.config.ts",
@@ -59,21 +61,21 @@
         "@digitalcredentials/issuer-registry-client": "^3.2.0-beta.5",
         "@fastify/cors": "^11.2.0",
         "@google/genai": "^1.27.0",
-        "@learncard/core": "9.4.35",
-        "@learncard/crypto-plugin": "1.1.35",
-        "@learncard/did-web-plugin": "1.1.35",
-        "@learncard/didkey-plugin": "1.1.35",
-        "@learncard/didkit-plugin": "1.10.0",
-        "@learncard/didkit-plugin-node": "0.3.0",
-        "@learncard/dynamic-loader-plugin": "1.1.35",
-        "@learncard/encryption-plugin": "1.1.35",
-        "@learncard/expiration-plugin": "1.2.35",
-        "@learncard/email-templates": "1.0.6",
-        "@learncard/helpers": "1.5.1",
-        "@learncard/learn-card-plugin": "1.2.35",
-        "@learncard/types": "5.20.0",
-        "@learncard/vc-plugin": "1.6.1",
-        "@learncard/vc-templates-plugin": "1.1.35",
+        "@learncard/core": "9.4.36",
+        "@learncard/crypto-plugin": "1.1.36",
+        "@learncard/did-web-plugin": "1.1.36",
+        "@learncard/didkey-plugin": "1.1.36",
+        "@learncard/didkit-plugin": "1.10.1",
+        "@learncard/didkit-plugin-node": "0.3.1",
+        "@learncard/dynamic-loader-plugin": "1.1.36",
+        "@learncard/encryption-plugin": "1.1.36",
+        "@learncard/expiration-plugin": "1.2.36",
+        "@learncard/email-templates": "1.1.0",
+        "@learncard/helpers": "1.6.0",
+        "@learncard/learn-card-plugin": "1.2.36",
+        "@learncard/types": "5.21.0",
+        "@learncard/vc-plugin": "1.6.2",
+        "@learncard/vc-templates-plugin": "1.1.36",
         "@sentry/serverless": "7.61.0",
         "@trpc/server": "11.8.0",
         "@types/lodash": "^4.14.191",

package/scripts/setup-inbox-queues.ts

@@ -0,0 +1,60 @@
+import {
+    SQSClient,
+    CreateQueueCommand,
+    GetQueueUrlCommand,
+    GetQueueAttributesCommand,
+    SetQueueAttributesCommand,
+} from '@aws-sdk/client-sqs';
+
+const endpoint = process.env.INBOX_QUEUE_ENDPOINT ?? 'http://localhost:9324';
+const client = new SQSClient({
+    region: process.env.AWS_REGION ?? 'us-east-1',
+    endpoint,
+    credentials: { accessKeyId: 'local', secretAccessKey: 'local' },
+});
+
+const ensureQueue = async (name: string): Promise<string> => {
+    let url: string | undefined;
+    try {
+        url = (await client.send(new GetQueueUrlCommand({ QueueName: name }))).QueueUrl;
+    } catch (error) {
+        if (
+            !(error instanceof Error) ||
+            !['QueueDoesNotExist', 'AWS.SimpleQueueService.NonExistentQueue'].includes(error.name)
+        )
+            throw error;
+        url = (await client.send(new CreateQueueCommand({ QueueName: name }))).QueueUrl;
+    }
+    if (!url) throw new Error(`Missing URL for ${name}`);
+    // ElasticMQ may advertise its container hostname; use the caller's reachable endpoint.
+    return `${endpoint.replace(/\/$/, '')}${new URL(url).pathname}`;
+};
+
+try {
+    const dlqUrl = await ensureQueue('inbox-dlq');
+    const attributes = await client.send(
+        new GetQueueAttributesCommand({
+            QueueUrl: dlqUrl,
+            AttributeNames: ['QueueArn'],
+        })
+    );
+    if (!attributes.Attributes?.QueueArn)
+        throw new Error('Inbox dead-letter queue ARN is missing.');
+    const queueUrl = await ensureQueue('inbox');
+    await client.send(
+        new SetQueueAttributesCommand({
+            QueueUrl: queueUrl,
+            Attributes: {
+                VisibilityTimeout: '1800',
+                RedrivePolicy: JSON.stringify({
+                    deadLetterTargetArn: attributes.Attributes.QueueArn,
+                    maxReceiveCount: '5',
+                }),
+            },
+        })
+    );
+    console.log(`INBOX_QUEUE_URL=${queueUrl}`);
+    console.log(`INBOX_DEAD_LETTER_QUEUE_URL=${dlqUrl}`);
+} finally {
+    client.destroy();
+}

package/serverless-local.yml

@@ -47,6 +47,8 @@ provider:
     stage: ${opt:stage, "dev"}
     region: ${opt:region, "us-east-1"}
     environment:
+        INBOX_QUEUE_URL: ${env:INBOX_QUEUE_URL, ''}
+        INBOX_QUEUE_ENDPOINT: ${env:INBOX_QUEUE_ENDPOINT, ''}
         PORT: ${env:PORT, 3000}
         LAMBDA_STAGE: ${opt:stage, "dev"}
         SEED: ${env:SEED}

package/serverless.yml

@@ -15,6 +15,20 @@ plugins:
     - serverless-prune-plugin
 
 constructs:
+    inbox-queue:
+        type: queue
+        batchSize: 1
+        maxConcurrency: 10
+        maxRetries: 5
+        worker:
+            handler: lambda.inboxQueueWorker
+            timeout: 300
+            reservedConcurrency: 10
+            vpc:
+                securityGroupIds:
+                    - 'Fn::GetAtt': [ServerlessSecurityGroup, GroupId]
+                subnetIds:
+                    - Ref: PrivateSubnetA
     notifications-queue:
         type: queue
         worker:
@@ -128,6 +142,7 @@ provider:
         PORT: ${env:PORT, 3000}
         INBOX_DELETE_EXPIRED_RECORDS: ${env:INBOX_DELETE_EXPIRED_RECORDS, "false"}
         LAMBDA_STAGE: ${opt:stage, "dev"}
+        INBOX_BATCH_ITEMS_PER_HOUR: ${env:INBOX_BATCH_ITEMS_PER_HOUR, '10000'}
         SEED: ${env:SEED}
         DOMAIN_NAME: ${env:DOMAIN_NAME}
         CLIENT_APP_DOMAIN_NAME: ${env:CLIENT_APP_DOMAIN_NAME}
@@ -153,6 +168,7 @@ provider:
         REDIS_PORT:
             'Fn::GetAtt': [ElasticCacheCluster, RedisEndpoint.Port]
         NOTIFICATIONS_QUEUE_URL: ${construct:notifications-queue.queueUrl}
+        INBOX_QUEUE_URL: ${construct:inbox-queue.queueUrl}
         SKILL_EMBEDDING_GOOGLE_API_KEY: ${env:SKILL_EMBEDDING_GOOGLE_API_KEY, ""}
         SKILL_EMBEDDING_GOOGLE_MODEL: ${env:SKILL_EMBEDDING_GOOGLE_MODEL, "gemini-embedding-001"}
         SKILL_EMBEDDING_BATCH_SIZE: ${env:SKILL_EMBEDDING_BATCH_SIZE, "25"}
@@ -190,6 +206,31 @@ provider:
                 - ETag
 
 functions:
+    inboxDeadLetterWorker:
+        handler: lambda.inboxDeadLetterWorker
+        timeout: 30
+        reservedConcurrency: 2
+        vpc:
+            securityGroupIds:
+                - 'Fn::GetAtt': [ServerlessSecurityGroup, GroupId]
+            subnetIds:
+                - Ref: PrivateSubnetA
+        events:
+            - sqs:
+                  arn: ${construct:inbox-queue.dlqArn}
+                  batchSize: 1
+                  functionResponseType: ReportBatchItemFailures
+    inboxQueueDispatcher:
+        handler: lambda.inboxQueueDispatcher
+        timeout: 60
+        reservedConcurrency: 1
+        vpc:
+            securityGroupIds:
+                - 'Fn::GetAtt': [ServerlessSecurityGroup, GroupId]
+            subnetIds:
+                - Ref: PrivateSubnetA
+        events:
+            - schedule: rate(1 minute)
     inboxMaintenance:
         handler: lambda.inboxMaintenanceHandler
         timeout: 300
@@ -288,6 +329,40 @@ functions:
 
 resources:
     Resources:
+        InboxQueueAgeAlarm:
+            Type: AWS::CloudWatch::Alarm
+            Properties:
+                AlarmDescription: Inbox issuance has waited over five minutes
+                Namespace: AWS/SQS
+                MetricName: ApproximateAgeOfOldestMessage
+                Dimensions:
+                    - Name: QueueName
+                      Value:
+                          Fn::Select:
+                              - 4
+                              - Fn::Split: ['/', '${construct:inbox-queue.queueUrl}']
+                Statistic: Maximum
+                Period: 60
+                EvaluationPeriods: 2
+                Threshold: 300
+                ComparisonOperator: GreaterThanThreshold
+                TreatMissingData: notBreaching
+        InboxDispatcherErrorsAlarm:
+            Type: AWS::CloudWatch::Alarm
+            Properties:
+                AlarmDescription: Durable inbox dispatch or recovery failed in three of five minutes
+                Namespace: AWS/Lambda
+                MetricName: Errors
+                Dimensions:
+                    - Name: FunctionName
+                      Value: { Ref: InboxQueueDispatcherLambdaFunction }
+                Statistic: Sum
+                Period: 60
+                EvaluationPeriods: 5
+                DatapointsToAlarm: 3
+                Threshold: 0
+                ComparisonOperator: GreaterThanThreshold
+                TreatMissingData: notBreaching
         VPC:
             Type: AWS::EC2::VPC
             Properties:

package/src/accesslayer/auth-grant/read.ts

@@ -98,7 +98,7 @@ export const isAuthGrantAssociatedWithProfile = async (
 export const isAuthGrantChallengeValidForDID = async (
     challenge: string,
     did: string
-): Promise<{ isChallengeValid: boolean; scope: string }> => {
+): Promise<{ isChallengeValid: boolean; scope: string; actAs?: string }> => {
     // TODO: Ideally, this transformation isn't required and we could use DID directly.
     const profileId = getProfileIdFromDid(did);
     if (!profileId) return { isChallengeValid: false, scope: AUTH_GRANT_NO_ACCESS_SCOPE };
@@ -126,5 +126,6 @@ export const isAuthGrantChallengeValidForDID = async (
     return {
         isChallengeValid: result.records.length > 0,
         scope: authGrant?.scope || AUTH_GRANT_NO_ACCESS_SCOPE,
+        actAs: authGrant?.actAs,
     };
 };

package/src/accesslayer/credential-activity/create.ts

@@ -23,6 +23,7 @@ export const createCredentialActivity = async (
         eventType: params.eventType,
         timestamp,
         actorProfileId: params.actorProfileId,
+        onBehalfOf: params.onBehalfOf,
         recipientType: params.recipientType,
         recipientIdentifier: params.recipientIdentifier,
         boostUri: params.boostUri,

package/src/accesslayer/credential-refresh/email-delivery.ts

@@ -0,0 +1,116 @@
+import { neogma } from '@instance';
+
+/**
+ * Persisted, unique claim per (refreshId, delivery window) for the managed
+ * credential-refresh update email (LC-2198).
+ *
+ * Why a dedicated node instead of a conditional property write: Neo4j's
+ * read-committed isolation does not re-evaluate a `WHERE` after a write lock is
+ * acquired, so two concurrent `SET ... WHERE windowKey <> $key` statements can
+ * both "win" and send two emails. A unique constraint on `deliveryKey` makes the
+ * claim a hard single-writer: exactly one `CREATE` succeeds, every loser observes
+ * a constraint violation and skips.
+ *
+ * This gives at-most-once email delivery per configured window. A send that fails
+ * after the claim is recorded as `failed` and is NOT retried inside the same
+ * window (see `credential-refresh-email.helpers.ts` for the explicit policy).
+ */
+
+export type CredentialRefreshEmailDeliveryState = 'claimed' | 'delivered' | 'failed';
+
+const deliveryKeyFor = (refreshId: string, windowKey: string): string =>
+    `${refreshId}:${windowKey}`;
+
+const isUniqueConstraintViolation = (error: unknown): boolean => {
+    const code = (error as { code?: string })?.code;
+
+    return (
+        code === 'Neo.ClientError.Schema.ConstraintValidationFailed' ||
+        (error instanceof Error && error.message.includes('already exists'))
+    );
+};
+
+/**
+ * Attempts to claim the email delivery window. Returns `'claimed'` for the single
+ * winner and `'duplicate'` for every concurrent or retried caller.
+ */
+export const claimCredentialRefreshEmailDelivery = async (params: {
+    refreshId: string;
+    windowKey: string;
+}): Promise<'claimed' | 'duplicate'> => {
+    const { refreshId, windowKey } = params;
+    const now = new Date().toISOString();
+
+    try {
+        await neogma.queryRunner.run(
+            `CREATE (delivery:CredentialRefreshEmailDelivery {
+                 deliveryKey: $deliveryKey,
+                 refreshId: $refreshId,
+                 windowKey: $windowKey,
+                 state: 'claimed',
+                 attempts: 1,
+                 createdAt: $now,
+                 updatedAt: $now
+             })`,
+            {
+                deliveryKey: deliveryKeyFor(refreshId, windowKey),
+                refreshId,
+                windowKey,
+                now,
+            }
+        );
+
+        return 'claimed';
+    } catch (error) {
+        if (isUniqueConstraintViolation(error)) return 'duplicate';
+
+        throw error;
+    }
+};
+
+/** Records the terminal outcome of a claimed delivery attempt. */
+export const finalizeCredentialRefreshEmailDelivery = async (params: {
+    refreshId: string;
+    windowKey: string;
+    state: Extract<CredentialRefreshEmailDeliveryState, 'delivered' | 'failed'>;
+}): Promise<void> => {
+    const { refreshId, windowKey, state } = params;
+    const now = new Date().toISOString();
+
+    await neogma.queryRunner.run(
+        `MATCH (delivery:CredentialRefreshEmailDelivery {deliveryKey: $deliveryKey})
+         SET delivery.state = $state, delivery.updatedAt = $now`,
+        { deliveryKey: deliveryKeyFor(refreshId, windowKey), state, now }
+    );
+};
+
+/** Reads a delivery record for observability and tests. */
+export const getCredentialRefreshEmailDelivery = async (
+    refreshId: string,
+    windowKey: string
+): Promise<{
+    deliveryKey: string;
+    refreshId: string;
+    windowKey: string;
+    state: CredentialRefreshEmailDeliveryState;
+    attempts: number;
+} | null> => {
+    const result = await neogma.queryRunner.run(
+        `MATCH (delivery:CredentialRefreshEmailDelivery {deliveryKey: $deliveryKey})
+         RETURN delivery LIMIT 1`,
+        { deliveryKey: deliveryKeyFor(refreshId, windowKey) }
+    );
+    const node = result.records[0]?.get('delivery');
+
+    if (!node) return null;
+
+    const props = node.properties;
+
+    return {
+        deliveryKey: props.deliveryKey,
+        refreshId: props.refreshId,
+        windowKey: props.windowKey,
+        state: props.state,
+        attempts: Number(props.attempts),
+    };
+};

package/src/accesslayer/credential-refresh/index.ts

@@ -1,3 +1,4 @@
 export * from './create';
+export * from './email-delivery';
 export * from './read';
 export * from './update';

package/src/accesslayer/credential-refresh/read.ts

@@ -262,8 +262,14 @@ export const getCredentialRefreshVersions = async (
     }
 
     const result = await neogma.queryRunner.run(
-        `MATCH (version:Credential {refreshId: $refreshId})
-         WHERE $beforeVersion IS NULL OR version.version < $beforeVersion
+        `CALL {
+             MATCH (version:Credential {refreshId: $refreshId}) RETURN version
+             UNION ALL
+             MATCH (version:InboxRefreshPublication {refreshId: $refreshId})
+             WHERE NOT EXISTS { MATCH (:Credential {refreshVersionKey: version.refreshVersionKey}) }
+             RETURN version
+         }
+         WITH version WHERE $beforeVersion IS NULL OR version.version < $beforeVersion
          RETURN {
              id: version.id,
              refreshId: version.refreshId,

package/src/accesslayer/credential-refresh/update.ts

@@ -78,6 +78,7 @@ export const advanceCredentialRefreshHead = async (
         etag,
         materialDigest,
         updateSummary,
+        credentialDisplayName,
         effectiveAt,
         notificationOutcome,
         notificationId,
@@ -103,6 +104,7 @@ export const advanceCredentialRefreshHead = async (
             etag,
             signingMode,
             updateSummary,
+            credentialDisplayName,
             idempotencyKey,
             refreshIdempotencyKey,
             notificationOutcome,
@@ -160,6 +162,7 @@ export const advanceCredentialRefreshHead = async (
                  refresh.etag = $etag,
                  refresh.materialDigest = $materialDigest,
                  refresh.updateSummary = $updateSummary,
+                 refresh.credentialDisplayName = coalesce($credentialDisplayName, refresh.credentialDisplayName),
                  refresh.signingMode = $signingMode,
                  refresh.lastPublishedAt = $publishedAt,
                  refresh.idempotencyKey = $idempotencyKey,
@@ -176,6 +179,7 @@ export const advanceCredentialRefreshHead = async (
                 etag: etag ?? null,
                 materialDigest: materialDigest ?? null,
                 updateSummary: updateSummary ?? null,
+                credentialDisplayName: credentialDisplayName ?? null,
                 signingMode,
                 publishedAt,
                 now,