@learncard/network-brain-service 3.19.0 → 3.19.1

package/dist/routes/share-links.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"share-links.d.ts","sourceRoot":"","sources":["../../src/routes/share-links.ts"],"names":[],"mappings":"AAiCA,OAAO,KAAK,EACR,0BAA0B,EAC1B,oBAAoB,EAEvB,MAAM,iCAAiC,CAAC;AAEzC,OAAO,KAAK,EACR,mBAAmB,EACnB,oBAAoB,EAEvB,MAAM,+BAA+B,CAAC;AAYvC,MAAM,MAAM,2BAA2B,GAAG;IACtC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,oBAAoB,CAAC;IAC3C,QAAQ,CAAC,QAAQ,EAAE,0BAA0B,CAAC;IAM9C,QAAQ,CAAC,cAAc,EAAE,CAAC,KAAK,EAAE,mBAAmB,KAAK,OAAO,CAAC,oBAAoB,CAAC,CAAC;IAEvF,QAAQ,CAAC,0BAA0B,EAAE,CAAC,cAAc,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAM/E,QAAQ,CAAC,8BAA8B,EAAE,CAAC,cAAc,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CACzF,CAAC;AAgHF,eAAO,MAAM,sBAAsB,GAC/B,iBAAiB,MAAM,OAAO,CAAC,2BAA2B,GAAG,IAAI,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuVrE,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG,UAAU,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAGzE,eAAO,MAAM,+BAA+B,GACxC,WAAW,MAAM,EACjB,gBAAgB,MAAM,KACvB,OAAO,CAAC,IAAI,CASd,CAAC;AAkBF,eAAO,MAAM,yBAAyB,mDAOhC,CAAC;AAoEP,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAAoD,CAAC"}

package/dist/services/delivery/adapters/postmark.adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"postmark.adapter.d.ts","sourceRoot":"","sources":["../../../../src/services/delivery/adapters/postmark.adapter.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAwCpE,qBAAa,eAAgB,YAAW,eAAe;IACnD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAe;gBAE1B,MAAM,EAAE,MAAM;IAIb,IAAI,CAAC,YAAY,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAwF5D,OAAO,CAAC,gBAAgB;CA8F3B"}
+{"version":3,"file":"postmark.adapter.d.ts","sourceRoot":"","sources":["../../../../src/services/delivery/adapters/postmark.adapter.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAwCpE,qBAAa,eAAgB,YAAW,eAAe;IACnD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAe;gBAE1B,MAAM,EAAE,MAAM;IAIb,IAAI,CAAC,YAAY,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAwF5D,OAAO,CAAC,gBAAgB;CAiG3B"}

package/dist/types/consentflowcontract.d.ts

@@ -96,8 +96,8 @@ export type FlatDbTransactionType = Omit<DbTransactionType, 'guardianApproval' |
 export declare const DbTermsValidator: z.ZodObject<{
     id: z.ZodString;
     status: z.ZodEnum<{
-        live: "live";
         stale: "stale";
+        live: "live";
         withdrawn: "withdrawn";
     }>;
     terms: z.ZodPrefault<z.ZodObject<{

package/lambda.ts

@@ -14,6 +14,7 @@ import skillsViewerApp from './src/skills-viewer';
 import statusListsApp from './src/status-lists';
 import credentialRefreshApp from './src/credential-refresh';
 import { appRouter, createContext } from './src/app';
+import { publicShareLinkCacheControlHeaders } from './src/routes';
 import { deliverQueuedNotification } from './src/helpers/notificationQueue.helpers';
 import { startSkillEmbeddingBackfill } from './src/helpers/skill-embedding.helpers';
 import { createOpenApiAwsLambdaHandler } from './src/helpers/shim';
@@ -72,6 +73,7 @@ export const _openApiHandler = createOpenApiAwsLambdaHandler({
                 'Access-Control-Allow-Origin': '*',
                 'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS',
                 'Access-Control-Allow-Headers': 'Authorization, Content-Type',
+                ...publicShareLinkCacheControlHeaders(meta.paths),
             },
         };
     },
@@ -85,12 +87,13 @@ export const _trpcHandler = withInboxBatchBodyLimit(
         router: appRouter,
         createContext,
         onError: handleTrpcError,
-        responseMeta: () => {
+        responseMeta: ({ paths }) => {
             return {
                 headers: {
                     'Access-Control-Allow-Origin': '*',
                     'Access-Control-Allow-Methods': '*',
                     'Access-Control-Allow-Headers': 'authorization',
+                    ...publicShareLinkCacheControlHeaders(paths),
                 },
             };
         },

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@learncard/network-brain-service",
-    "version": "3.19.0",
+    "version": "3.19.1",
     "description": "",
     "engines": {
         "node": ">=24.12 <25"
@@ -19,6 +19,7 @@
         "test:integration:watch": "vitest --config vitest.integration.config.ts",
         "test:docker": "vitest run --config vitest.integration.config.ts",
         "seed:dev-app": "bun scripts/seed-dev-app.ts",
+        "seed:demo-persona": "bun --conditions=development scripts/seed-demo-persona.ts",
         "skill-frameworks": "bun scripts/skill-frameworks.ts",
         "build": "shx rm -rf dist && node bundle.mjs && tsc --p tsconfig.build.json && tsc --showConfig --p tsconfig.build.json > tsconfig.temp.json && tsc-alias --replacer ./tsc-alias-replacer.cjs -p tsconfig.temp.json && shx rm tsconfig.temp.json",
         "typecheck": "tsc --noEmit -p tsconfig.build.json && tsc --noEmit -p tsconfig.entrypoints.json",
@@ -61,27 +62,30 @@
         "@digitalcredentials/issuer-registry-client": "^3.2.0-beta.5",
         "@fastify/cors": "^11.2.0",
         "@google/genai": "^1.27.0",
-        "@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",
+        "@learncard/credential-library": "2.0.5",
+        "@learncard/core": "9.4.37",
+        "@learncard/crypto-plugin": "1.1.37",
+        "@learncard/did-web-plugin": "1.1.37",
+        "@learncard/didkey-plugin": "1.1.37",
+        "@learncard/didkit-plugin": "1.10.2",
+        "@learncard/didkit-plugin-node": "0.3.2",
+        "@learncard/dynamic-loader-plugin": "1.1.37",
+        "@learncard/encryption-plugin": "1.1.37",
+        "@learncard/expiration-plugin": "1.2.37",
+        "@learncard/email-templates": "1.2.0",
+        "@learncard/helpers": "1.6.1",
+        "@learncard/learn-card-plugin": "1.2.37",
+        "@learncard/types": "5.22.0",
+        "@learncard/vc-plugin": "1.6.3",
+        "@learncard/vc-templates-plugin": "1.1.37",
         "@sentry/serverless": "7.61.0",
         "@trpc/server": "11.8.0",
         "@types/lodash": "^4.14.191",
         "base64url": "^3.0.1",
+        "bs58": "^5.0.0",
         "cors": "^2.8.5",
         "dotenv": "^16.0.3",
+        "hash-wasm": "^4.12.0",
         "express": "^4.18.2",
         "fastify": "^5.8.5",
         "fastify-plugin": "^5.1.0",
@@ -93,6 +97,7 @@
         "lodash": "^4.17.21",
         "messagebird": "^4.0.1",
         "multiformats": "^11.0.1",
+        "mongodb": "^6.2.0",
         "mustache": "^4.2.0",
         "neo4j-driver": "5.18.0",
         "neogma": "1.13.0",
@@ -103,6 +108,7 @@
         "tsc-alias": "^1.8.10",
         "twilio": "^5.7.1",
         "undici": "^6",
+        "tweetnacl": "^1.0.3",
         "uuid": "^14.0.0",
         "zod": "4.4.3",
         "zod-openapi": "^5.0.1"

package/scripts/seed-demo-persona.ts

@@ -0,0 +1,425 @@
+#!/usr/bin/env bun
+/**
+ * Publish a credential-library persona as a ConsentFlow contract with auto-boosts.
+ *
+ * Usage (from services/learn-card-network/brain-service):
+ *   bun run seed:demo-persona student
+ *
+ * The script is idempotent: profile, signing authority, Boost, contract, and
+ * AUTO_RECEIVE identifiers are stable. Re-running updates fixture content and
+ * replaces the contract's auto-boost set without changing its URI.
+ *
+ * Every target requires explicit database, domain, signing-authority endpoint,
+ * and 64-character signing seed configuration.
+ */
+
+import { fileURLToPath } from 'url';
+import { createHmac } from 'node:crypto';
+
+import * as bs58 from 'bs58';
+import * as dotenv from 'dotenv';
+import { MongoClient } from 'mongodb';
+import { Neogma } from 'neogma';
+import Redis from 'ioredis';
+import * as nacl from 'tweetnacl';
+import { v4 as uuid, v5 as uuidv5 } from 'uuid';
+
+import {
+    getBundle,
+    getFixture,
+    prepareFixture,
+    type CredentialBundleEntry,
+    type CredentialBundleIssuer,
+} from '@learncard/credential-library';
+import type { UnsignedVC } from '@learncard/types';
+import { flattenObject } from '../src/helpers/objects.helpers';
+
+dotenv.config({ path: fileURLToPath(new URL('../.env', import.meta.url)) });
+
+const PERSONA_NAMESPACE = '5c4bb193-6e65-43d9-940d-d85b758a94f2';
+const SIGNING_AUTHORITY_NAME = 'sample-personas';
+
+const NEO4J_URI = process.env.NEO4J_URI ?? 'bolt://localhost:7687';
+const NEO4J_USERNAME = process.env.NEO4J_USERNAME ?? 'neo4j';
+const NEO4J_PASSWORD = process.env.NEO4J_PASSWORD ?? 'this-is-the-password';
+const MONGO_URI = process.env.MONGO_URI ?? 'mongodb://localhost:27017/?replicaSet=rs0';
+const MONGO_DB_NAME = process.env.MONGO_DB_NAME ?? 'lca-api';
+const REDIS_HOST = process.env.REDIS_HOST ?? 'localhost';
+const REDIS_PORT = Number.parseInt(process.env.REDIS_PORT ?? '6379', 10);
+const BRAIN_DOMAIN = process.env.DOMAIN_NAME || 'localhost%3A4000';
+const SIGNING_AUTHORITY_ENDPOINT = process.env.DEMO_PERSONA_SIGNING_AUTHORITY_ENDPOINT;
+const SIGNING_AUTHORITY_SEED = process.env.DEMO_PERSONA_SA_SEED;
+
+const personaId = process.argv[2];
+
+if (!personaId) {
+    throw new Error('Usage: bun scripts/seed-demo-persona.ts <personaId>');
+}
+
+if (!SIGNING_AUTHORITY_SEED || !SIGNING_AUTHORITY_ENDPOINT) {
+    throw new Error(
+        'DEMO_PERSONA_SA_SEED and DEMO_PERSONA_SIGNING_AUTHORITY_ENDPOINT are required.'
+    );
+}
+
+if (!/^[0-9a-f]{64}$/i.test(SIGNING_AUTHORITY_SEED)) {
+    throw new Error('DEMO_PERSONA_SA_SEED must contain exactly 64 hexadecimal characters.');
+}
+
+const transformProfileId = (raw: string): string => raw.toLowerCase().replace(/:/g, '%3A');
+
+const getDidWeb = (domain: string, profileId: string): string =>
+    `did:web:${domain}:users:${profileId}`;
+
+const constructContractUri = (contractId: string): string => {
+    const encodedDomain = BRAIN_DOMAIN.includes('localhost')
+        ? BRAIN_DOMAIN.replace(/:/g, '%3A')
+        : BRAIN_DOMAIN.replace(/:/g, '/');
+
+    return `lc:network:${encodedDomain.replace(/\/trpc$/, '')}/trpc:contract:${contractId}`;
+};
+
+const deriveDidKeyFromSeed = (hexSeed: string): string => {
+    const seedBytes = Buffer.from(hexSeed, 'hex');
+    const keyPair = nacl.sign.keyPair.fromSeed(seedBytes);
+    const multicodec = Buffer.concat([Buffer.from('ed01', 'hex'), Buffer.from(keyPair.publicKey)]);
+
+    return `did:key:z${bs58.encode(multicodec)}`;
+};
+const deriveSigningAuthoritySeed = (profileId: string): string =>
+    createHmac('sha256', Buffer.from(SIGNING_AUTHORITY_SEED, 'hex'))
+        .update(`learncard:sample-persona:${profileId}`)
+        .digest('hex');
+
+const clearProfileDidDocumentCache = async (profileId: string): Promise<void> => {
+    const redis = new Redis({
+        host: REDIS_HOST,
+        port: REDIS_PORT,
+        lazyConnect: true,
+        connectTimeout: 2_000,
+        retryStrategy: () => null,
+    });
+
+    try {
+        await redis.connect();
+        await redis.del(`did-doc:${profileId}`);
+    } catch {
+        console.warn(
+            `Could not clear did-doc:${profileId} at ${REDIS_HOST}:${REDIS_PORT}; delete that Redis key manually, or restart the brain service if it uses an in-memory cache.`
+        );
+    } finally {
+        redis.disconnect();
+    }
+};
+
+const shiftDate = (offsetDays: number): string => {
+    const date = new Date();
+    date.setUTCDate(date.getUTCDate() + offsetDays);
+    return date.toISOString();
+};
+
+const prepareBundleCredential = (entry: CredentialBundleEntry, issuerDid: string): UnsignedVC => {
+    const fixture = getFixture(entry.fixtureId);
+    const prepared = prepareFixture(fixture, {
+        issuerDid,
+        subjectDid: 'did:example:123',
+        validFrom: shiftDate(entry.validFromOffsetDays),
+        freshIds: false,
+    });
+
+    if (entry.name) prepared.name = entry.name;
+
+    return prepared;
+};
+
+const toBoostTemplate = (credential: UnsignedVC, issuerDid: string): string => {
+    const template = structuredClone(credential) as Record<string, unknown>;
+    delete template.id;
+    delete template.proof;
+    template.issuer = issuerDid;
+
+    const subjects = Array.isArray(template.credentialSubject)
+        ? template.credentialSubject
+        : [template.credentialSubject];
+    for (const subject of subjects) {
+        if (subject && typeof subject === 'object') {
+            Object.assign(subject, { id: 'did:example:123' });
+        }
+    }
+
+    return JSON.stringify(template);
+};
+
+const ensureSigningAuthority = async (
+    ownerDid: string,
+    did: string,
+    seed: string
+): Promise<void> => {
+    const client = new MongoClient(MONGO_URI);
+
+    try {
+        await client.connect();
+        await client
+            .db(MONGO_DB_NAME)
+            .collection('signingauthorities')
+            .updateOne(
+                { ownerDid, name: SIGNING_AUTHORITY_NAME },
+                {
+                    $set: { seed, did },
+                    $setOnInsert: { _id: uuid(), ownerDid, name: SIGNING_AUTHORITY_NAME },
+                },
+                { upsert: true }
+            );
+    } finally {
+        await client.close();
+    }
+};
+
+const main = async (): Promise<void> => {
+    const bundle = getBundle(personaId);
+    const [firstEntry] = bundle.entries;
+    if (!firstEntry) {
+        throw new Error(`Credential bundle ${bundle.id} has no entries.`);
+    }
+
+    const issuerProfiles = new Map<
+        string,
+        CredentialBundleIssuer & {
+            profileId: `sample-${string}`;
+            did: string;
+            signingAuthorityDid: string;
+            signingAuthoritySeed: string;
+        }
+    >();
+    for (const entry of bundle.entries) {
+        const profileId = transformProfileId(entry.issuer.profileId);
+        if (!profileId.startsWith('sample-')) {
+            throw new Error(`Refusing to seed non-sample issuer profile: ${profileId}`);
+        }
+        const existingIssuer = issuerProfiles.get(profileId);
+
+        if (
+            existingIssuer &&
+            (existingIssuer.displayName !== entry.issuer.displayName ||
+                existingIssuer.image !== entry.issuer.image)
+        ) {
+            throw new Error(`Conflicting metadata configured for sample issuer ${profileId}.`);
+        }
+
+        const signingAuthoritySeed = deriveSigningAuthoritySeed(profileId);
+        const signingAuthorityDid = deriveDidKeyFromSeed(signingAuthoritySeed);
+        issuerProfiles.set(profileId, {
+            ...entry.issuer,
+            profileId: profileId as `sample-${string}`,
+            did: getDidWeb(BRAIN_DOMAIN, profileId),
+            signingAuthorityDid,
+            signingAuthoritySeed,
+        });
+    }
+
+    const contractOwnerProfileId = transformProfileId(firstEntry.issuer.profileId);
+    const contractId = uuidv5(`persona:${bundle.id}:contract`, PERSONA_NAMESPACE);
+    const neogma = new Neogma({
+        url: NEO4J_URI,
+        username: NEO4J_USERNAME,
+        password: NEO4J_PASSWORD,
+    });
+    const run = neogma.queryRunner.run.bind(neogma.queryRunner);
+
+    try {
+        for (const issuer of issuerProfiles.values()) {
+            const profileResult = await run(
+                `MERGE (p:Profile {profileId: $profileId})
+                 ON CREATE SET p.isSamplePersona = true
+                 WITH p
+                 WHERE p.isSamplePersona = true
+                   AND (p.did IS NULL OR p.did = $did)
+                 SET p.displayName = $displayName,
+                     p.shortBio = $shortBio,
+                     p.image = $image,
+                     p.did = $did
+                 RETURN p.did AS did`,
+                {
+                    profileId: issuer.profileId,
+                    displayName: issuer.displayName,
+                    shortBio: 'Issuer for LearnCard sample credentials',
+                    image: issuer.image ?? '',
+                    did: issuer.signingAuthorityDid,
+                }
+            );
+            const storedSigningAuthorityDid = profileResult.records[0]?.get('did');
+            if (!storedSigningAuthorityDid) {
+                throw new Error(
+                    `Refusing to overwrite existing non-sample profile ${issuer.profileId}.`
+                );
+            }
+            if (storedSigningAuthorityDid !== issuer.signingAuthorityDid) {
+                throw new Error(
+                    `Profile ${issuer.profileId} did not retain its signing authority DID.`
+                );
+            }
+
+            await run(
+                `MERGE (sa:SigningAuthority {endpoint: $endpoint})
+                 WITH sa
+                 MATCH (p:Profile {profileId: $profileId})
+                 MERGE (p)-[r:USES_SIGNING_AUTHORITY {name: $name}]->(sa)
+                 SET r.did = $did, r.isPrimary = true
+                 RETURN r`,
+                {
+                    endpoint: SIGNING_AUTHORITY_ENDPOINT,
+                    profileId: issuer.profileId,
+                    name: SIGNING_AUTHORITY_NAME,
+                    did: issuer.signingAuthorityDid,
+                }
+            );
+            await clearProfileDidDocumentCache(issuer.profileId);
+            await ensureSigningAuthority(
+                issuer.did,
+                issuer.signingAuthorityDid,
+                issuer.signingAuthoritySeed
+            );
+        }
+
+        const autoBoosts: Array<{ boostId: string; issuerProfileId: string }> = [];
+        for (const entry of bundle.entries) {
+            const fixture = getFixture(entry.fixtureId);
+            const profileId = transformProfileId(entry.issuer.profileId);
+            const issuer = issuerProfiles.get(profileId);
+            if (!issuer) {
+                throw new Error(`Missing seeded issuer profile ${profileId}.`);
+            }
+
+            const boostId = uuidv5(
+                `persona:${bundle.id}:fixture:${entry.fixtureId}`,
+                PERSONA_NAMESPACE
+            );
+            const credential = prepareBundleCredential(entry, issuer.did);
+            const boost = toBoostTemplate(credential, issuer.did);
+            autoBoosts.push({ boostId, issuerProfileId: profileId });
+            const boostProperties = flattenObject({
+                id: boostId,
+                boost,
+                name: entry.name ?? fixture.name,
+                type: fixture.profile,
+                category: 'Achievement',
+                status: 'LIVE',
+                meta: { personaId: bundle.id, fixtureId: fixture.id },
+            });
+
+            const boostResult = await run(
+                `MERGE (b:Boost {id: $boostId})
+                 SET b = $properties
+                 WITH b
+                 OPTIONAL MATCH (b)-[oldCreated:CREATED_BY]->(:Profile)
+                 DELETE oldCreated
+                 WITH DISTINCT b
+                 OPTIONAL MATCH (:Profile)-[oldRole:HAS_ROLE {roleId: '__creator__'}]->(b)
+                 DELETE oldRole
+                 WITH DISTINCT b
+                 MATCH (p:Profile {profileId: $profileId})
+                 MERGE (b)-[created:CREATED_BY]->(p)
+                 SET created.date = $date
+                 MERGE (p)-[:HAS_ROLE {roleId: '__creator__'}]->(b)
+                 WITH b
+                 MATCH (b)-[:CREATED_BY]->(creator:Profile)
+                 MATCH (roleOwner:Profile)-[:HAS_ROLE {roleId: '__creator__'}]->(b)
+                 RETURN collect(creator.profileId) AS creatorProfileIds,
+                        collect(roleOwner.profileId) AS roleOwnerProfileIds`,
+                {
+                    boostId,
+                    properties: boostProperties,
+                    profileId,
+                    date: new Date().toISOString(),
+                }
+            );
+            const creatorProfileIds = boostResult.records[0]?.get('creatorProfileIds');
+            const roleOwnerProfileIds = boostResult.records[0]?.get('roleOwnerProfileIds');
+            if (
+                creatorProfileIds?.length !== 1 ||
+                creatorProfileIds[0] !== profileId ||
+                roleOwnerProfileIds?.length !== 1 ||
+                roleOwnerProfileIds[0] !== profileId
+            ) {
+                throw new Error(`Boost ${boostId} has ambiguous profile ownership.`);
+            }
+        }
+
+        const contract = {
+            read: {
+                personal: { name: { required: false } },
+                credentials: { categories: { Achievement: { required: false } } },
+            },
+            write: {
+                personal: {},
+                credentials: {
+                    categories: { Achievement: { required: false, defaultEnabled: true } },
+                },
+            },
+        };
+        const now = new Date().toISOString();
+        const contractProperties = flattenObject({
+            id: contractId,
+            name: `${bundle.displayName} Sample Credentials`,
+            subtitle: bundle.blurb,
+            description: bundle.blurb,
+            reasonForAccessing: '',
+            needsGuardianConsent: false,
+            redirectUrl: '',
+            frontDoorBoostUri: '',
+            image: '',
+            contract,
+            updatedAt: now,
+        });
+
+        await run(
+            `MERGE (c:ConsentFlowContract {id: $contractId})
+             ON CREATE SET c.createdAt = $createdAt
+             WITH c, c.createdAt AS createdAt
+             SET c = $properties,
+                 c.createdAt = createdAt
+             WITH c
+             OPTIONAL MATCH (c)-[oldOwner:CREATED_BY]->(:Profile)
+             DELETE oldOwner
+             WITH DISTINCT c
+             MATCH (p:Profile {profileId: $profileId})
+             MERGE (c)-[:CREATED_BY]->(p)
+             RETURN c`,
+            {
+                contractId,
+                createdAt: now,
+                profileId: contractOwnerProfileId,
+                properties: contractProperties,
+            }
+        );
+
+        await run(
+            `MATCH (c:ConsentFlowContract {id: $contractId})
+             OPTIONAL MATCH (c)-[old:AUTO_RECEIVE]->(:Boost)
+             DELETE old
+             WITH DISTINCT c
+             UNWIND $autoBoosts AS autoBoost
+             MATCH (b:Boost {id: autoBoost.boostId})
+             CREATE (c)-[:AUTO_RECEIVE {
+                 signingAuthorityEndpoint: $endpoint,
+                 signingAuthorityName: $name,
+                 issuer: autoBoost.issuerProfileId
+             }]->(b)`,
+            {
+                contractId,
+                autoBoosts,
+                endpoint: SIGNING_AUTHORITY_ENDPOINT,
+                name: SIGNING_AUTHORITY_NAME,
+            }
+        );
+
+        console.log(constructContractUri(contractId));
+    } finally {
+        await neogma.driver.close();
+    }
+};
+
+main().catch(error => {
+    console.error(error);
+    process.exitCode = 1;
+});

package/serverless.yml

@@ -193,6 +193,25 @@ provider:
         CREDENTIAL_REFRESH_ENABLED: ${env:CREDENTIAL_REFRESH_ENABLED, "false"}
         CREDENTIAL_REFRESH_DIGEST_SECRET: ${env:CREDENTIAL_REFRESH_DIGEST_SECRET, ""}
         CREDENTIAL_REFRESH_NOTIFICATION_WINDOW_HOURS: ${env:CREDENTIAL_REFRESH_NOTIFICATION_WINDOW_HOURS, "24"}
+        # Stable HMAC key for passcode-bearing share-link request fingerprints.
+        SHARE_LINK_REQUEST_HASH_SECRET: ${env:SHARE_LINK_REQUEST_HASH_SECRET, ""}
+        # LC-2187 share-link service wiring and automatic maintenance. Every value is
+        # bounded and re-validated fail-closed at runtime. Never read from the
+        # scheduled event payload.
+        SHARE_LINK_MAINTENANCE_NAMESPACE: ${env:SHARE_LINK_MAINTENANCE_NAMESPACE, ""}
+        SHARE_LINK_MAINTENANCE_ORIGIN: ${env:SHARE_LINK_MAINTENANCE_ORIGIN, ""}
+        SHARE_LINK_MAINTENANCE_AUDIENCE: ${env:SHARE_LINK_MAINTENANCE_AUDIENCE, ""}
+        SHARE_LINK_MAINTENANCE_ALLOW_INSECURE_LOOPBACK: ${env:SHARE_LINK_MAINTENANCE_ALLOW_INSECURE_LOOPBACK, "false"}
+        SHARE_LINK_MAINTENANCE_CLAIMANT: ${env:SHARE_LINK_MAINTENANCE_CLAIMANT, "brain-share-link-maintenance"}
+        SHARE_LINK_MAINTENANCE_RECOVERY_LIMIT: ${env:SHARE_LINK_MAINTENANCE_RECOVERY_LIMIT, "25"}
+        SHARE_LINK_MAINTENANCE_CLEANUP_LIMIT: ${env:SHARE_LINK_MAINTENANCE_CLEANUP_LIMIT, "25"}
+        SHARE_LINK_MAINTENANCE_LEASE_MS: ${env:SHARE_LINK_MAINTENANCE_LEASE_MS, "120000"}
+        SHARE_LINK_MAINTENANCE_CLAIM_MS: ${env:SHARE_LINK_MAINTENANCE_CLAIM_MS, "300000"}
+        SHARE_LINK_MAINTENANCE_BUDGET_MS: ${env:SHARE_LINK_MAINTENANCE_BUDGET_MS, "60000"}
+        SHARE_LINK_MAINTENANCE_INTERVAL_MS: ${env:SHARE_LINK_MAINTENANCE_INTERVAL_MS, "300000"}
+        SHARE_LINK_MAINTENANCE_REQUEST_TIMEOUT_MS: ${env:SHARE_LINK_MAINTENANCE_REQUEST_TIMEOUT_MS, "10000"}
+        SHARE_LINK_MAINTENANCE_FINALIZE_RESERVE_MS: ${env:SHARE_LINK_MAINTENANCE_FINALIZE_RESERVE_MS, "5000"}
+        SHARE_LINK_MAINTENANCE_GRAPH_TIMEOUT_MS: ${env:SHARE_LINK_MAINTENANCE_GRAPH_TIMEOUT_MS, "15000"}
     tracing:
         apiGateway: true
         lambda: true
@@ -244,6 +263,23 @@ functions:
                   rate: rate(1 day)
                   enabled: true
 
+    # 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
+    # matches the default Docker maintenance interval (5 minutes).
+    shareLinkMaintenance:
+        handler: shareLinkMaintenanceLambda.shareLinkMaintenanceHandler
+        timeout: 300
+        vpc:
+            securityGroupIds:
+                - 'Fn::GetAtt': [ServerlessSecurityGroup, GroupId]
+            subnetIds:
+                - Ref: PrivateSubnetA
+        events:
+            - schedule:
+                  rate: rate(5 minutes)
+                  enabled: true
+
     trpc:
         handler: lambda.trpcHandler
         vpc:

package/shareLinkMaintenanceLambda.ts

@@ -0,0 +1,49 @@
+import type { Context } from 'aws-lambda';
+
+import {
+    createShareLinkMaintenanceRuntime,
+    type ShareLinkMaintenanceRuntime,
+} from './src/helpers/share-link-maintenance';
+
+/**
+ * Dedicated LC-2187 share-link maintenance Lambda entrypoint.
+ *
+ * It deliberately does NOT import `lambda.ts`, so no unrelated embedding
+ * backfill, tRPC router, Sentry input capture or inbox handler runs at import
+ * time. The only side effect is resolving the service and maintenance
+ * configuration; when it is absent or malformed the runtime is inert and the
+ * handler performs no graph, remote or signing work.
+ *
+ * The scheduled event payload is ignored entirely: it can never override the
+ * namespace, origin, audience or any other configuration, and it is never
+ * logged.
+ */
+
+let runtime: ShareLinkMaintenanceRuntime | null = null;
+
+const getRuntime = (): ShareLinkMaintenanceRuntime => {
+    if (runtime === null) {
+        runtime = createShareLinkMaintenanceRuntime({
+            rawEnvironment: process.env as Record<string, unknown>,
+        });
+    }
+
+    return runtime;
+};
+
+export const shareLinkMaintenanceHandler = async (
+    _event: unknown,
+    context?: Pick<Context, 'getRemainingTimeInMillis'>
+): Promise<{ status: string }> => {
+    const hasRemainingTime = typeof context?.getRemainingTimeInMillis === 'function';
+
+    const summary = await getRuntime().runOnce({
+        // Preserve the LIVE Lambda remaining-time source: the runtime samples it
+        // once, before dependency initialization, and anchors the invocation
+        // budget to that instant.
+        remainingTimeMs: hasRemainingTime ? () => context!.getRemainingTimeInMillis() : undefined,
+    });
+
+    // The runtime already emitted one aggregate-only allowlisted event.
+    return { status: summary.status };
+};