@learncard/network-brain-service 4.1.3 → 5.0.0

package/lambdaApp.ts

@@ -13,9 +13,11 @@ import app from './src/openapi';
 import skillsViewerApp from './src/skills-viewer';
 import statusListsApp from './src/status-lists';
 import credentialRefreshApp from './src/credential-refresh';
+import campaignUnsubscribeApp from './src/campaign-unsubscribe';
 import { appRouter, createContext } from './src/app';
 import { publicShareLinkCacheControlHeaders } from './src/routes';
 import { deliverQueuedNotification } from './src/helpers/notificationQueue.helpers';
+import { processCampaignDispatchJob } from './src/helpers/campaign-queue.helpers';
 import { startSkillEmbeddingBackfill } from './src/helpers/skill-embedding.helpers';
 import { createOpenApiAwsLambdaHandler } from './src/helpers/shim';
 import {
@@ -64,6 +66,17 @@ export const credentialRefreshHandler: typeof credentialRefreshProxy = async (ev
     return credentialRefreshProxy(event, context);
 };
 
+const campaignUnsubscribeProxy = serverlessHttp(
+    toServerlessApplication(campaignUnsubscribeApp.server)
+);
+export const campaignUnsubscribeHandler: typeof campaignUnsubscribeProxy = async (
+    event,
+    context
+) => {
+    await campaignUnsubscribeApp.ready();
+    return campaignUnsubscribeProxy(event, context);
+};
+
 export const _openApiHandler = createOpenApiAwsLambdaHandler({
     router: appRouter,
     responseMeta: meta => {
@@ -197,6 +210,13 @@ export const notificationsWorker: SQSHandler = Sentry.AWSLambda.wrapHandler(asyn
     } satisfies SQSBatchResponse;
 });
 
+export const campaignDispatchWorker: SQSHandler = Sentry.AWSLambda.wrapHandler(async event => {
+    // batchSize=1; throwing lets SQS apply the construct's retry/DLQ policy.
+    for (const record of event.Records) {
+        await processCampaignDispatchJob(JSON.parse(record.body));
+    }
+});
+
 export const inboxMaintenanceHandler = Sentry.AWSLambda.wrapHandler(async (): Promise<void> => {
     const counts = await runInboxMaintenance();
     console.log('Universal Inbox maintenance completed', counts);

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@learncard/network-brain-service",
-    "version": "4.1.3",
+    "version": "5.0.0",
     "description": "",
     "engines": {
         "node": ">=24.12 <25"
@@ -23,6 +23,7 @@
         "test:boost-recipients": "vitest run --config vitest.boost-recipients-neo4j.config.ts",
         "seed:dev-app": "bun scripts/seed-dev-app.ts",
         "seed:demo-persona": "bun --conditions=development scripts/seed-demo-persona.ts",
+        "migrate:consent-flow-versions": "bun --conditions=development scripts/migrate-consent-flow-versions.ts",
         "skill-frameworks": "bun scripts/skill-frameworks.ts",
         "skill-embeddings:backfill": "bun --conditions=development scripts/skill-embeddings-backfill.ts",
         "backfill:profile-search": "bun scripts/backfill-profile-search.ts",
@@ -33,7 +34,7 @@
         "start-p-4000": "PORT=4000 serverless offline --httpPort 4000 --websocketPort 4001 --lambdaPort 4002 --albPort 4003 --host 127.0.0.1 --config serverless-local.yml",
         "dev": "bun --conditions=development --watch src/docker-entry.ts",
         "start:docker": "bun --conditions=development src/docker-entry.ts",
-        "serverless-deploy": "node ../../../scripts/prepare-didkit-native-layer.cjs && serverless deploy --verbose"
+        "serverless-deploy": "node ../../../scripts/prepare-didkit-native-layer.cjs && node ../../../scripts/verify-node24-didkit-layer.cjs && serverless deploy --verbose"
     },
     "keywords": [],
     "author": "Learning Economy Foundation (www.learningeconomy.io)",
@@ -54,7 +55,7 @@
         "serverless": "3.40.0",
         "serverless-certificate-creator": "1.6.0",
         "serverless-domain-manager": "6.3.1",
-        "serverless-esbuild": "1.55.0",
+        "serverless-esbuild": "1.57.2",
         "serverless-http": "3.2.0",
         "serverless-lift": "1.31.0",
         "serverless-offline": "^14.4.0",
@@ -68,23 +69,23 @@
         "@digitalcredentials/issuer-registry-client": "^4.1.0",
         "@fastify/cors": "^11.2.0",
         "@google/genai": "^1.27.0",
-        "@learncard/credential-library": "2.1.6",
-        "@learncard/core": "9.4.43",
-        "@learncard/crypto-plugin": "1.1.43",
-        "@learncard/did-web-plugin": "1.1.43",
-        "@learncard/didkey-plugin": "1.1.43",
-        "@learncard/didkit-plugin": "1.10.9",
-        "@learncard/didkit-plugin-node": "0.3.9",
-        "@learncard/dynamic-loader-plugin": "1.1.43",
-        "@learncard/encryption-plugin": "1.1.43",
-        "@learncard/expiration-plugin": "1.2.43",
-        "@learncard/email-templates": "1.2.2",
-        "@learncard/helpers": "1.7.3",
-        "@learncard/learn-card-plugin": "1.2.43",
+        "@learncard/credential-library": "2.1.7",
+        "@learncard/core": "9.4.44",
+        "@learncard/crypto-plugin": "1.1.44",
+        "@learncard/did-web-plugin": "1.1.44",
+        "@learncard/didkey-plugin": "1.1.44",
+        "@learncard/didkit-plugin": "1.10.10",
+        "@learncard/didkit-plugin-node": "0.3.10",
+        "@learncard/dynamic-loader-plugin": "1.1.44",
+        "@learncard/encryption-plugin": "1.2.0",
+        "@learncard/expiration-plugin": "1.2.44",
+        "@learncard/email-templates": "1.3.0",
+        "@learncard/helpers": "1.8.0",
+        "@learncard/learn-card-plugin": "1.2.44",
         "@learncard/partner-connect-core": "0.2.0",
-        "@learncard/types": "5.24.2",
-        "@learncard/vc-plugin": "1.6.9",
-        "@learncard/vc-templates-plugin": "1.1.43",
+        "@learncard/types": "6.0.0",
+        "@learncard/vc-plugin": "1.7.0",
+        "@learncard/vc-templates-plugin": "1.1.44",
         "@sentry/serverless": "7.61.0",
         "@trpc/server": "11.8.0",
         "@types/lodash": "^4.14.191",

package/project.json

@@ -149,6 +149,11 @@
             "options": {
                 "script": "test:boost-recipients"
             }
+        },
+        "build:integration-dependencies": {
+            "executor": "nx:noop",
+            "cache": false,
+            "dependsOn": ["^build"]
         }
     }
 }

package/scripts/migrate-consent-flow-versions.ts

@@ -0,0 +1,9 @@
+import { migrateLegacyConsentFlowContracts } from '../src/helpers/consentflow-legacy-migration.helpers';
+
+try {
+    await migrateLegacyConsentFlowContracts();
+    console.info('ConsentFlow contract version migration completed.');
+} catch (error) {
+    console.error('ConsentFlow contract version migration failed.', error);
+    process.exitCode = 1;
+}

package/scripts/report-send-template-exposure.ts

@@ -0,0 +1,47 @@
+import neo4j from 'neo4j-driver';
+
+/** Read-only, counts-only inventory. Pass the deployment timestamp as the sole argument. */
+const main = async (): Promise<void> => {
+    const cutoff = process.argv[2];
+    if (!cutoff || !Number.isFinite(Date.parse(cutoff))) {
+        throw new Error('A valid deployment timestamp is required');
+    }
+    const { NEO4J_URI, NEO4J_USERNAME, NEO4J_PASSWORD } = process.env;
+    if (!NEO4J_URI || !NEO4J_USERNAME || !NEO4J_PASSWORD) {
+        throw new Error('Explicit Neo4j connection environment is required');
+    }
+    const driver = neo4j.driver(NEO4J_URI, neo4j.auth.basic(NEO4J_USERNAME, NEO4J_PASSWORD));
+    const session = driver.session({ defaultAccessMode: neo4j.session.READ });
+    try {
+        const result = await session.executeRead(tx =>
+            tx.run(
+                `MATCH (b:Boost)-[created:CREATED_BY]->()
+             WHERE created.date < $cutoff
+             WITH DISTINCT b
+             WITH b, EXISTS { MATCH (r:CredentialRefresh) WHERE r.boostId = b.id }
+                OR EXISTS { MATCH (i:RefreshSendIntent) WHERE i.boostUri ENDS WITH ':' + b.id } AS managed,
+                EXISTS { MATCH (a:CredentialActivity) WHERE a.source = 'send' AND a.boostUri ENDS WITH ':' + b.id } AS sent
+             RETURN count(CASE WHEN managed THEN b END) AS managed,
+                    count(CASE WHEN sent AND NOT managed THEN b END) AS unclassifiedSendCandidates`,
+                { cutoff: new Date(cutoff).toISOString() }
+            )
+        );
+        // Signed-only sends historically had no distinguishing marker. Candidates are
+        // an upper bound, not a claim that every counted Boost contains private data.
+        const row = result.records[0];
+        console.log(
+            JSON.stringify({
+                managed: Number(row?.get('managed') ?? 0),
+                unclassifiedSendCandidates: Number(row?.get('unclassifiedSendCandidates') ?? 0),
+            })
+        );
+    } finally {
+        await session.close();
+        await driver.close();
+    }
+};
+
+main().catch(() => {
+    console.error('SEND_TEMPLATE_INVENTORY_FAILED');
+    process.exitCode = 1;
+});

package/scripts/verify-python-contracts.ts

@@ -21,6 +21,17 @@ configureOfflineSchemaEnvironment();
 const { AllocateCredentialRefreshInputValidator, PublishCredentialRefreshInputValidator } =
     await import('@learncard/types');
 const { activityRouter } = await import('../src/routes/activity');
+const { contractsRouter } = await import('../src/routes/contracts');
+const { boostsRouter } = await import('../src/routes/boosts');
+const consentListInput = contractsRouter._def.procedures.getConsentedContracts._def.inputs.at(
+    -1
+) as ZodType;
+const bodyInputs: Record<string, ZodType> = {
+    '/consent-flow-contract/update':
+        contractsRouter._def.procedures.updateConsentFlowContract._def.inputs.at(-1) as ZodType,
+    '/boost/skills/search':
+        boostsRouter._def.procedures.searchSkillsAvailableForBoost._def.inputs.at(-1) as ZodType,
+};
 
 const activityInputs: Record<string, ZodType> = {
     '/activity/credentials': activityRouter._def.procedures.getMyActivities._def.inputs.at(
@@ -38,6 +49,10 @@ for (const record of records) {
         valid = PublishCredentialRefreshInputValidator.safeParse(record.body).success;
     } else if (url.pathname === '/credential-refresh/allocate') {
         valid = AllocateCredentialRefreshInputValidator.safeParse(record.body).success;
+    } else if (url.pathname === '/consent-flow-contracts/consent') {
+        valid = consentListInput.safeParse(record.body ?? undefined).success;
+    } else if (bodyInputs[url.pathname]) {
+        valid = bodyInputs[url.pathname]!.safeParse(record.body).success;
     } else {
         const validator = activityInputs[url.pathname];
         assert(validator, `No source validator for captured path ${url.pathname}`);
@@ -67,6 +82,6 @@ for (const validator of Object.values(activityInputs)) {
     }
 }
 console.log(
-    `Verified ${records.length} captured publication/allocation/activity cases and Z-only boundaries against actual source validators`
+    `Verified ${records.length} captured publication/allocation/activity/consent/update/skill-search cases and Z-only boundaries against actual source validators`
 );
 process.exit(0);

package/serverless-local.yml

@@ -7,6 +7,7 @@ frameworkVersion: '3'
 useDotenv: true
 
 plugins:
+    - ../../../scripts/serverless-node24-runtime.cjs
     - serverless-esbuild
     - serverless-offline
     - serverless-lift
@@ -29,7 +30,7 @@ custom:
         minify: true
         external: ['@learncard/didkit-plugin/dist/didkit_wasm_bg.wasm', 'p-limit']
         sourcemap: external
-        target: 'node20'
+        target: 'node24'
         watch:
             pattern: ['src/**/*.ts', 'dids.ts']
 
@@ -41,7 +42,7 @@ package:
 
 provider:
     name: aws
-    runtime: nodejs20.x
+    runtime: nodejs24.x
     memorySize: 2048
     timeout: 29
     stage: ${opt:stage, "dev"}
@@ -124,6 +125,18 @@ functions:
             - httpApi: GET /docs
             - httpApi: GET /docs/{trpc+}
 
+    campaignUnsubscribe:
+        handler: lambda.campaignUnsubscribeHandler
+        vpc:
+            securityGroupIds:
+                - 'Fn::GetAtt': [ServerlessSecurityGroup, GroupId]
+            subnetIds:
+                - Ref: PrivateSubnetA
+        events:
+            - httpApi: POST /campaigns/unsubscribe
+            - httpApi: GET /campaigns/unsubscribe/browser
+            - httpApi: POST /campaigns/unsubscribe/browser
+
     skillsViewer:
         handler: lambda.skillsViewerHandler
         vpc:

package/serverless.function-env.cjs

@@ -24,9 +24,12 @@ const PROVIDER_SECRETS = [
     'SMART_RESUME_ACCESS_KEY',
     'SMART_RESUME_CONTRACT_URI',
     'CREDENTIAL_REFRESH_DIGEST_SECRET',
+    'CREDENTIAL_REFRESH_DIGEST_KEY_VERSION',
+    'CREDENTIAL_REFRESH_DIGEST_PREVIOUS_KEYS',
     'SHARE_LINK_REQUEST_HASH_SECRET',
     'APP_STORE_ADMIN_PROFILE_IDS',
     'CAMPAIGN_ADMIN_PROFILE_IDS',
+    'CAMPAIGN_UNSUBSCRIBE_SECRET',
     'LOGIN_PROVIDER_DID',
     'NOTIFICATIONS_SERVICE_WEBHOOK_URL',
 ];
@@ -46,6 +49,7 @@ exports.provider = ({ options = {}, env = process.env } = {}) => ({
     REDIS_PORT: { 'Fn::GetAtt': ['ElasticCacheCluster', 'RedisEndpoint.Port'] },
     NOTIFICATIONS_QUEUE_URL: '${construct:notifications-queue.queueUrl}',
     INBOX_QUEUE_URL: '${construct:inbox-queue.queueUrl}',
+    CAMPAIGN_QUEUE_URL: '${construct:campaign-queue.queueUrl}',
     // The deploy commit, emitted only when set so an empty string never counts toward the
     // 4KB per-function environment limit.
     ...pickNonEmpty(['GIT_SHA'], env),

package/serverless.local.yml

@@ -119,6 +119,18 @@ functions:
             - httpApi: GET /docs
             - httpApi: GET /docs/{trpc+}
 
+    campaignUnsubscribe:
+        handler: lambda.campaignUnsubscribeHandler
+        vpc:
+            securityGroupIds:
+                - 'Fn::GetAtt': [ServerlessSecurityGroup, GroupId]
+            subnetIds:
+                - Ref: PrivateSubnetA
+        events:
+            - httpApi: POST /campaigns/unsubscribe
+            - httpApi: GET /campaigns/unsubscribe/browser
+            - httpApi: POST /campaigns/unsubscribe/browser
+
     skillsViewer:
         handler: lambda.skillsViewerHandler
         vpc:

package/serverless.yml

@@ -7,6 +7,7 @@ frameworkVersion: '3'
 useDotenv: true
 
 plugins:
+    - ../../../scripts/serverless-node24-runtime.cjs
     - serverless-esbuild
     - serverless-offline
     - serverless-domain-manager
@@ -15,6 +16,18 @@ plugins:
     - serverless-prune-plugin
 
 constructs:
+    campaign-queue:
+        type: queue
+        batchSize: 1
+        maxRetries: 3
+        worker:
+            handler: lambda.campaignDispatchWorker
+            timeout: 300
+            vpc:
+                securityGroupIds:
+                    - 'Fn::GetAtt': [ServerlessSecurityGroup, GroupId]
+                subnetIds:
+                    - Ref: PrivateSubnetA
     inbox-queue:
         type: queue
         batchSize: 1
@@ -33,6 +46,14 @@ constructs:
         type: queue
         worker:
             handler: lambda.notificationsWorker
+            timeout: 30
+            # Graph/cache bookkeeping requires the VPC. All webhook HTTP delivery
+            # must retain the connection-time public-address and no-redirect guard.
+            vpc:
+                securityGroupIds:
+                    - 'Fn::GetAtt': [ServerlessSecurityGroup, GroupId]
+                subnetIds:
+                    - Ref: PrivateSubnetA
 
 custom:
     prune:
@@ -57,7 +78,7 @@ custom:
         # serverless-esbuild default and must be preserved when overriding.
         exclude: ['aws-sdk', '@learncard/didkit-plugin-node']
         sourcemap: external
-        target: 'node20'
+        target: 'node24'
         watch:
             pattern: ['src/**/*.ts', 'dids.ts']
 
@@ -126,13 +147,13 @@ layers:
         name: ${self:service}-${opt:stage, 'dev'}-didkit-native
         description: Native DIDKit napi addon and runtime DIDKit dependency
         compatibleRuntimes:
-            - nodejs20.x
+            - nodejs24.x
         compatibleArchitectures:
             - x86_64
 
 provider:
     name: aws
-    runtime: nodejs20.x
+    runtime: nodejs24.x
     # Attach the native DIDKit layer to every function in this service.
     layers:
         - { Ref: DidkitNativeLambdaLayer }
@@ -229,6 +250,18 @@ functions:
         events:
             - schedule: rate(1 minute)
 
+    # Suspend consent updates whose response deadline has passed.
+    consentFlowDeadline:
+        handler: consentFlowDeadlineLambda.consentFlowDeadlineHandler
+        timeout: 30
+        reservedConcurrency: 1
+        vpc:
+            securityGroupIds:
+                - 'Fn::GetAtt': [ServerlessSecurityGroup, GroupId]
+            subnetIds:
+                - Ref: PrivateSubnetA
+        events:
+            - schedule: rate(1 minute)
     # LC-2187 share-link recovery + cleanup. Dedicated entrypoint (no lambda.ts
     # import-time work). Runs automatically with valid service configuration;
     # absent wiring remains inert and partial wiring fails closed. The cadence
@@ -291,6 +324,18 @@ functions:
             - httpApi: GET /docs
             - httpApi: GET /docs/{trpc+}
 
+    campaignUnsubscribe:
+        handler: lambda.campaignUnsubscribeHandler
+        vpc:
+            securityGroupIds:
+                - 'Fn::GetAtt': [ServerlessSecurityGroup, GroupId]
+            subnetIds:
+                - Ref: PrivateSubnetA
+        events:
+            - httpApi: POST /campaigns/unsubscribe
+            - httpApi: GET /campaigns/unsubscribe/browser
+            - httpApi: POST /campaigns/unsubscribe/browser
+
     skillsViewer:
         handler: lambda.skillsViewerHandler
         vpc:

package/src/accesslayer/boost/create.ts

@@ -1,5 +1,11 @@
 import { QueryBuilder, BindParam } from 'neogma';
-import { UnsignedVC, VC } from '@learncard/types';
+import {
+    UnsignedVC,
+    VC,
+    CredentialDisplayValidator,
+    type CredentialDisplay,
+} from '@learncard/types';
+import { DISPLAY_ONLY_ANCHOR_MARKER } from '@learncard/helpers';
 import { v4 as uuid } from 'uuid';
 
 import { Boost, BoostInstance, Profile, AppStoreListing } from '@models';
@@ -13,10 +19,11 @@ import { ProfileType } from 'types/profile';
 import { AppStoreListingType } from 'types/app-store-listing';
 
 export const createBoost = async (
-    credential: UnsignedVC | VC,
+    credential: UnsignedVC | VC | null,
     creator: ProfileType,
     metadata: Omit<BoostType, 'id' | 'boost'> = {},
-    domain: string
+    domain: string,
+    publicDisplay?: CredentialDisplay
 ): Promise<BoostInstance> => {
     const id = uuid();
 
@@ -30,10 +37,20 @@ export const createBoost = async (
         new BindParam({
             params: {
                 id,
-                boost: convertCredentialToBoostTemplateJSON(
-                    credential,
-                    getDidWeb(domain, creator.profileId)
-                ),
+                boost: credential
+                    ? convertCredentialToBoostTemplateJSON(
+                          credential,
+                          getDidWeb(domain, creator.profileId)
+                      )
+                    : JSON.stringify({
+                          '@context': ['https://www.w3.org/ns/credentials/v2'],
+                          type: ['VerifiableCredential'],
+                          issuer: getDidWeb(domain, creator.profileId),
+                          credentialSubject: { id: 'did:example:123' },
+                          name: publicDisplay?.name ?? 'Credential',
+                          display: CredentialDisplayValidator.parse(publicDisplay ?? {}),
+                          [DISPLAY_ONLY_ANCHOR_MARKER]: true,
+                      }),
                 status,
                 ...((flattenObject as any)(metadata) as any),
             },
@@ -64,6 +81,44 @@ export const createBoost = async (
     return boost;
 };
 
+/**
+ * `name`/`image` come only from the caller's explicit `display`. `category` may
+ * additionally fall back to the inline template's category: consent-flow write
+ * authorization (`resolveContractForSend` and the managed-send contract binding
+ * query) keys off a Boost's `category` and treats an absent category as
+ * unrestricted. Silently dropping the category — rather than the template's actual
+ * value — would let a category the recipient never consented to pass as an
+ * unrestricted write merely because the caller omitted `display`.
+ */
+export const normalizePublicDisplay = (
+    display: CredentialDisplay | undefined,
+    template?: { category?: string | null }
+): CredentialDisplay => {
+    const category = display?.category ?? template?.category?.slice(0, 280);
+    return CredentialDisplayValidator.parse({
+        ...(display ?? {}),
+        ...(category ? { category } : {}),
+    });
+};
+
+/** Display-only anchors never receive credential content or inline template metadata,
+ *  except that `category` may be inherited from the template (see `normalizePublicDisplay`). */
+export const createDisplayOnlyBoost = (
+    display: CredentialDisplay | undefined,
+    creator: ProfileType,
+    domain: string,
+    template?: { category?: string | null }
+): Promise<BoostInstance> => {
+    const publicDisplay = normalizePublicDisplay(display, template);
+    return createBoost(
+        null,
+        creator,
+        { ...publicDisplay, name: publicDisplay.name ?? 'Credential' },
+        domain,
+        publicDisplay
+    );
+};
+
 /**
  * Creates a boost owned by an AppStoreListing (not a Profile).
  * The boost is created with the app's DID as the issuer.