@learncard/network-brain-service 3.19.0 → 3.19.1

package/src/docker-entry.ts

@@ -15,6 +15,8 @@ import {
 
 import { neogma } from '@instance';
 import { appRouter, type AppRouter, createContext } from './app';
+import { publicShareLinkCacheControlHeaders } from './routes';
+import { registerPublicShareLinkNoStore } from './public-share-link-http';
 import { openApiDocument } from './openapi';
 import { inboxBatchResponseMeta } from './helpers/inbox-batch-http.helpers';
 import { didFastifyPlugin } from './dids';
@@ -23,10 +25,26 @@ import { statusListsFastifyPlugin } from './status-lists';
 import { credentialRefreshFastifyPlugin } from './credential-refresh';
 import { deliverQueuedNotification } from '@helpers/notificationQueue.helpers';
 import { startSkillEmbeddingBackfill } from '@helpers/skill-embedding.helpers';
+import {
+    createConsoleMaintenanceLogger,
+    createShareLinkMaintenanceRuntime,
+    createShareLinkMaintenanceScheduler,
+    type ShareLinkMaintenanceScheduler,
+} from '@helpers/share-link-maintenance';
 import { maybeAutoSeedSkillFrameworks } from './seed/seedSkillFrameworks';
 
 const server = Fastify({ routerOptions: { maxParamLength: 5000 } });
 
+/**
+ * The scheduled maintenance runtime is created only after the server is ready.
+ * When its config is disabled/invalid it is inert, so no interval and no
+ * graph/remote/signing dependency is initialized at all.
+ */
+let shareLinkMaintenanceScheduler: ShareLinkMaintenanceScheduler | null = null;
+
+server.addHook('onClose', async () => {
+    await shareLinkMaintenanceScheduler?.stop();
+});
 // Register before either OpenAPI or tRPC registers its wildcard route. The hook raises the
 // parser ceiling for those shared routes, then narrows it back to 4 MiB only for batch issuance.
 // Registering this later would leave the already-created adapter routes at Fastify's 1 MiB limit.
@@ -78,6 +96,9 @@ server.register(fastifyTRPCPlugin, {
         allowMethodOverride: true,
         router: appRouter,
         createContext,
+        responseMeta: ({ paths }) => ({
+            headers: publicShareLinkCacheControlHeaders(paths),
+        }),
         onError({ path, error }) {
             // report to error monitoring
             console.error(`Error in tRPC handler on path '${path}':`, error);
@@ -96,6 +117,13 @@ server.register(fastifyTRPCOpenApiPlugin, {
     },
 } satisfies CreateOpenApiFastifyPluginOptions<AppRouter>);
 
+/**
+ * LC-2187: the Fastify OpenAPI adapter has no `responseMeta` hook, so the
+ * no-store contract for the anonymous public share-link routes is applied at
+ * the adapter boundary itself. It never depends on a cache layer above.
+ */
+registerPublicShareLinkNoStore(server);
+
 server.get('/docs/openapi.json', () => openApiDocument);
 
 const SCALAR_HTML = `<!DOCTYPE html>
@@ -138,12 +166,41 @@ server.register(credentialRefreshFastifyPlugin);
         } catch (error) {
             console.error('Skill embedding backfill failed', error);
         }
+
+        // Explicit startup after readiness. Disabled/invalid config stays inert.
+        const maintenanceRuntime = createShareLinkMaintenanceRuntime();
+
+        if (maintenanceRuntime.resolution.status === 'enabled') {
+            shareLinkMaintenanceScheduler = createShareLinkMaintenanceScheduler({
+                runOnce: () => maintenanceRuntime.runOnce(),
+                intervalMs: maintenanceRuntime.resolution.config.intervalMs,
+                logger: createConsoleMaintenanceLogger(),
+            });
+            shareLinkMaintenanceScheduler.start();
+        }
     } catch (err) {
         console.error(err);
         process.exit(1);
     }
 })();
 
+const shutdown = async (signal: NodeJS.Signals): Promise<void> => {
+    console.log(`Received ${signal}; closing server and draining maintenance`);
+    try {
+        await server.close();
+    } catch (error) {
+        console.error('Server shutdown failed', error);
+    }
+    process.exit(0);
+};
+
+process.once('SIGTERM', () => {
+    void shutdown('SIGTERM');
+});
+process.once('SIGINT', () => {
+    void shutdown('SIGINT');
+});
+
 const pollUrl = environment.NOTIFICATIONS_QUEUE_POLL_URL;
 
 if (pollUrl) {

package/src/helpers/boost.helpers.ts

@@ -22,6 +22,7 @@ import {
     parseRenderedTemplate,
     shouldAutoAppendTemplateEvidence,
 } from '@helpers/template.helpers';
+import { setCredentialSubjectIds } from '@helpers/credentialSubject.helpers';
 
 import { getBoostOwner } from '@accesslayer/boost/relationships/read';
 import { BoostInstance } from '@models';
@@ -95,15 +96,7 @@ export const convertCredentialToBoostTemplateJSON = (
     delete template.proof;
     template.issuer = defaultIssuerDid ?? 'did:example:123';
 
-    if (Array.isArray(template.credentialSubject)) {
-        template.credentialSubject = template.credentialSubject.map(subject => {
-            subject.id = 'did:example:123';
-
-            return subject;
-        });
-    } else {
-        template.credentialSubject.id = 'did:example:123';
-    }
+    setCredentialSubjectIds(template, 'did:example:123');
     return JSON.stringify(template);
 };
 
@@ -262,14 +255,7 @@ export const issueClaimLinkBoost = async (
 
     boostCredential.issuer = signingAuthorityForUser.relationship.did;
 
-    if (Array.isArray(boostCredential.credentialSubject)) {
-        boostCredential.credentialSubject = boostCredential.credentialSubject.map(subject => ({
-            ...subject,
-            id: getDidWeb(domain, to.profileId),
-        }));
-    } else {
-        boostCredential.credentialSubject.id = getDidWeb(domain, to.profileId);
-    }
+    setCredentialSubjectIds(boostCredential, getDidWeb(domain, to.profileId));
 
     // Embed the boostURI into the boost credential for verification purposes.
     if (boostCredential.type.includes('BoostCredential')) {
@@ -362,20 +348,7 @@ export const prepareCredentialFromBoost = async (
         credential.issuer = issuerDid;
     }
 
-    // Set recipient DID in credentialSubject if provided
-    if (recipientDid) {
-        if (Array.isArray(credential.credentialSubject)) {
-            credential.credentialSubject = credential.credentialSubject.map(subject => ({
-                ...subject,
-                id: recipientDid,
-            }));
-        } else {
-            credential.credentialSubject = {
-                ...(credential.credentialSubject || {}),
-                id: recipientDid,
-            };
-        }
-    }
+    if (recipientDid) setCredentialSubjectIds(credential, recipientDid);
 
     // Embed boostId for BoostCredential types
     if (credential?.type?.includes('BoostCredential')) {

package/src/helpers/credentialSubject.helpers.test.ts

@@ -0,0 +1,114 @@
+import { describe, expect, it } from 'vitest';
+import type { UnsignedVC } from '@learncard/types';
+
+import { setCredentialSubjectIds } from './credentialSubject.helpers';
+
+const collectSubjectIds = (credential: Record<string, unknown>): string[] => {
+    const subject = credential.credentialSubject;
+    const subjects = Array.isArray(subject) ? subject : [subject];
+
+    return subjects.flatMap(currentSubject => {
+        if (!currentSubject || typeof currentSubject !== 'object') return [];
+
+        const subjectRecord = currentSubject as Record<string, unknown>;
+        const embedded = subjectRecord.verifiableCredential;
+        const embeddedCredentials = Array.isArray(embedded) ? embedded : embedded ? [embedded] : [];
+
+        return [
+            subjectRecord.id as string,
+            ...embeddedCredentials.flatMap(nested =>
+                collectSubjectIds(nested as Record<string, unknown>)
+            ),
+        ];
+    });
+};
+
+describe('setCredentialSubjectIds', () => {
+    it('patches every CLR learner subject without rewriting achievement identities', () => {
+        const credential = {
+            credentialSubject: {
+                id: 'did:example:old-root',
+                achievement: {
+                    id: 'https://example.edu/transcript',
+                    creator: { id: 'https://example.edu' },
+                },
+                verifiableCredential: [
+                    {
+                        credentialSubject: {
+                            id: 'did:example:old-course',
+                            achievement: {
+                                id: 'https://example.edu/courses/imd-120',
+                                creator: { id: 'https://example.edu/departments/design' },
+                            },
+                            verifiableCredential: {
+                                credentialSubject: { id: 'did:example:old-assessment' },
+                            },
+                        },
+                    },
+                ],
+            },
+        } as unknown as UnsignedVC;
+
+        setCredentialSubjectIds(credential, 'did:example:learner');
+
+        expect(collectSubjectIds(credential as unknown as Record<string, unknown>)).toEqual([
+            'did:example:learner',
+            'did:example:learner',
+            'did:example:learner',
+        ]);
+        expect(credential.credentialSubject).toMatchObject({
+            achievement: {
+                id: 'https://example.edu/transcript',
+                creator: { id: 'https://example.edu' },
+            },
+            verifiableCredential: [
+                {
+                    credentialSubject: {
+                        achievement: {
+                            id: 'https://example.edu/courses/imd-120',
+                            creator: { id: 'https://example.edu/departments/design' },
+                        },
+                    },
+                },
+            ],
+        });
+    });
+
+    it('preserves signed embedded credentials while patching unsigned subjects', () => {
+        const credential = {
+            credentialSubject: {
+                id: 'did:example:old-root',
+                verifiableCredential: [
+                    {
+                        credentialSubject: { id: 'did:example:signed-subject' },
+                        proof: { type: 'DataIntegrityProof', proofValue: 'signed-value' },
+                    },
+                    {
+                        credentialSubject: { id: 'did:example:unsigned-subject' },
+                    },
+                ],
+            },
+        } as unknown as UnsignedVC;
+
+        setCredentialSubjectIds(credential, 'did:example:learner');
+
+        const subject = credential.credentialSubject as Record<string, unknown>;
+        const embedded = subject.verifiableCredential as Array<Record<string, unknown>>;
+
+        expect(subject.id).toBe('did:example:learner');
+        expect(embedded[0]?.credentialSubject).toEqual({
+            id: 'did:example:signed-subject',
+        });
+        expect(embedded[1]?.credentialSubject).toEqual({
+            id: 'did:example:learner',
+        });
+    });
+
+    it('creates an outer credential subject when a legacy template omits it', () => {
+        const credential = {} as UnsignedVC;
+
+        setCredentialSubjectIds(credential, 'did:example:learner');
+
+        expect(credential.credentialSubject).toEqual({ id: 'did:example:learner' });
+    });
+});

package/src/helpers/credentialSubject.helpers.ts

@@ -0,0 +1,40 @@
+import type { UnsignedVC, VC } from '@learncard/types';
+
+const setSubjectIds = (subject: unknown, subjectDid: string): void => {
+    if (Array.isArray(subject)) {
+        subject.forEach(nestedSubject => setSubjectIds(nestedSubject, subjectDid));
+        return;
+    }
+
+    if (!subject || typeof subject !== 'object') return;
+
+    const mutableSubject = subject as Record<string, unknown>;
+    mutableSubject.id = subjectDid;
+
+    const embeddedCredentials = mutableSubject.verifiableCredential;
+    const credentials = Array.isArray(embeddedCredentials)
+        ? embeddedCredentials
+        : [embeddedCredentials];
+
+    credentials.forEach(credential => {
+        if (!credential || typeof credential !== 'object' || Array.isArray(credential)) return;
+
+        const credentialRecord = credential as Record<string, unknown>;
+        if (credentialRecord.proof !== undefined) return;
+
+        setSubjectIds(credentialRecord.credentialSubject, subjectDid);
+    });
+};
+
+/**
+ * Sets the recipient DID on the outer credential and unsigned credentials nested in a CLR.
+ * Signed embedded credentials are immutable because changing their subject invalidates the proof.
+ */
+export const setCredentialSubjectIds = (credential: UnsignedVC | VC, subjectDid: string): void => {
+    if (!credential.credentialSubject) {
+        credential.credentialSubject = { id: subjectDid };
+        return;
+    }
+
+    setSubjectIds(credential.credentialSubject, subjectDid);
+};

package/src/helpers/inbox.helpers.ts

@@ -325,9 +325,11 @@ export const issueToInbox = async (
 
     // Check if the recipient is a managed child (has a guardian via MANAGES relationship).
     // Managed children need guardian approval for all inbox credentials, even without explicit guardianEmail.
-    const recipientManagers = existingProfile
-        ? await getProfilesThatManageAProfile(existingProfile.profileId)
-        : [];
+    // Service profiles (orgs) are managed for admin purposes, not guardianship.
+    const recipientManagers =
+        existingProfile && !existingProfile.isServiceProfile
+            ? await getProfilesThatManageAProfile(existingProfile.profileId)
+            : [];
     const recipientIsManaged = recipientManagers.length > 0;
 
     if (existingProfile && !guardianEmail && !recipientIsManaged && !configuration.refresh) {
@@ -877,8 +879,9 @@ export const issueToInbox = async (
 
                 await deliveryService.send({
                     contactMethod: recipient,
-                    templateId: delivery?.template?.id ?? 'universal-inbox',
+                    templateId: delivery?.template?.id || 'universal-inbox-claim',
                     templateModel: {
+                        claimUrl: emailClaimUrl,
                         emailClaimUrl,
                         claimToken: emailClaimToken,
                         ...injectedTemplateFields,

package/src/helpers/notificationMessages.ts

@@ -57,7 +57,8 @@ export type NotificationMessageKey =
     | 'credentialRestoredUnnamed'
     // --- Managed credential refresh (LC-2136) — generic copy only: never name the
     // credential, the holder's claims, or implementation terms (refresh/sync/etc.) ---
-    | 'credentialRefreshed';
+    | 'credentialRefreshed'
+    | 'shareViewed';
 
 type MessageTemplate = { title: string; body: string };
 type LocaleCatalog = Record<NotificationMessageKey, MessageTemplate>;
@@ -216,6 +217,10 @@ const en: LocaleCatalog = {
         title: 'Credential updated',
         body: '{from} updated one of your credentials.',
     },
+    shareViewed: {
+        title: 'Share viewed',
+        body: 'Your share “{title} ({count})” was viewed.',
+    },
 };
 
 const es: LocaleCatalog = {
@@ -367,6 +372,10 @@ const es: LocaleCatalog = {
         title: 'Credencial actualizada',
         body: '{from} actualizó una de tus credenciales.',
     },
+    shareViewed: {
+        title: 'Enlace visto',
+        body: 'Se vio tu enlace «{title} ({count})».',
+    },
 };
 
 const fr: LocaleCatalog = {
@@ -518,6 +527,10 @@ const fr: LocaleCatalog = {
         title: 'Titre mis à jour',
         body: "{from} a mis à jour l'un de vos titres.",
     },
+    shareViewed: {
+        title: 'Partage consulté',
+        body: 'Votre partage « {title} ({count}) » a été consulté.',
+    },
 };
 
 const ar: LocaleCatalog = {
@@ -669,6 +682,10 @@ const ar: LocaleCatalog = {
         title: 'تم تحديث الشهادة',
         body: 'قام {from} بتحديث إحدى شهاداتك.',
     },
+    shareViewed: {
+        title: 'تمت مشاهدة المشاركة',
+        body: 'تمت مشاهدة مشاركتك «{title} ({count})».',
+    },
 };
 
 const CATALOGS: Record<NotificationLocale, LocaleCatalog> = { en, es, fr, ar };

package/src/helpers/presentation-metadata.ts

@@ -0,0 +1,41 @@
+import { TRPCError } from '@trpc/server';
+import { ShareLinkIdValidator } from '@learncard/types';
+import { z } from 'zod';
+
+// Relationship metadata is not signed VP content. Bound generic metadata and
+// reserve the share-link shape for the recipient's own send/accept workflow.
+const ShareLinkPresentationMetadataValidator = z
+    .object({
+        type: z.literal('learncard.share-link.v1'),
+        shareId: ShareLinkIdValidator,
+        title: z.string().min(1).max(120),
+        note: z.string().max(500).optional(),
+        sharer: z
+            .object({
+                profileId: z.string().min(1).max(128),
+                displayName: z.string().min(1).max(120),
+            })
+            .strict(),
+    })
+    .strict();
+
+export const PresentationMetadataValidator = z
+    .record(z.string().min(1).max(64), z.unknown())
+    .refine(value => JSON.stringify(value).length <= 4096, 'Metadata is too large')
+    .superRefine((value, ctx) => {
+        if (value.type !== 'learncard.share-link.v1') return;
+        if (!ShareLinkPresentationMetadataValidator.safeParse(value).success)
+            ctx.addIssue({ code: 'custom', message: 'Invalid share-link metadata' });
+    });
+
+export const assertPresentationMetadataRecipient = (
+    metadata: Record<string, unknown> | undefined,
+    senderProfileId: string,
+    recipientProfileId: string
+): void => {
+    if (metadata?.type === 'learncard.share-link.v1' && senderProfileId !== recipientProfileId)
+        throw new TRPCError({
+            code: 'BAD_REQUEST',
+            message: 'Share-link metadata requires a self-save',
+        });
+};

package/src/helpers/presentation.helpers.ts

@@ -23,23 +23,29 @@ export const sendPresentation = async (
     from: ProfileType,
     to: ProfileType,
     presentation: VP | JWE,
-    domain: string
+    domain: string,
+    metadata?: Record<string, unknown>
 ): Promise<string> => {
     const presentationInstance = await storePresentation(presentation);
 
-    await createSentPresentationRelationship(from, to, presentationInstance);
+    await createSentPresentationRelationship(from, to, presentationInstance, metadata);
 
-    let uri = getPresentationUri(presentationInstance.id, domain);
+    const uri = getPresentationUri(presentationInstance.id, domain);
 
-    await addNotificationToQueue({
-        type: LCNNotificationTypeEnumValidator.enum.PRESENTATION_RECEIVED,
-        to,
-        from,
-        message: getNotificationMessage('presentationReceived', resolveRecipientLocale(to), {
-            from: from.displayName,
-        }),
-        data: { vpUris: [uri] },
-    });
+    // Saving a shared collection reuses the presentation send/accept pipeline by
+    // sending it to the current profile. Keep that storage behavior without
+    // creating a meaningless "you sent this to yourself" recipient alert.
+    if (from.profileId !== to.profileId) {
+        await addNotificationToQueue({
+            type: LCNNotificationTypeEnumValidator.enum.PRESENTATION_RECEIVED,
+            to,
+            from,
+            message: getNotificationMessage('presentationReceived', resolveRecipientLocale(to), {
+                from: from.displayName,
+            }),
+            data: { vpUris: [uri] },
+        });
+    }
 
     return uri;
 };
@@ -63,16 +69,17 @@ export const acceptPresentation = async (profile: ProfileType, uri: string): Pro
         });
     }
 
-    // Check if presentation has already been received by this profile
+    // Acceptance is idempotent so a client can safely recover from a response
+    // interruption without producing a second received relationship.
     const alreadyReceived = await getPresentationReceivedByProfile(id, profile);
-    if (alreadyReceived) {
-        throw new TRPCError({
-            code: 'BAD_REQUEST',
-            message: 'Presentation has already been received',
-        });
+    if (!alreadyReceived) {
+        await createReceivedPresentationRelationship(
+            profile,
+            pendingVp.source,
+            pendingVp.target,
+            pendingVp.relationship.metadata
+        );
     }
 
-    await createReceivedPresentationRelationship(profile, pendingVp.source, pendingVp.target);
-
     return true;
 };

package/src/helpers/profile.helpers.ts

@@ -1,3 +1,5 @@
+import { LCNProfileValidator } from '@learncard/types';
+
 import { getProfileByProfileId } from '@accesslayer/profile/read';
 import { createProfile } from '@accesslayer/profile/create';
 import { getProfileIdFromDid } from './did.helpers';
@@ -6,6 +8,11 @@ import { ProfileType } from 'types/profile';
 export const transformProfileId = (rawInput: string): string =>
     rawInput.toLowerCase().replaceAll(':', '%3A');
 
+export const PublicProfileIdValidator = LCNProfileValidator.shape.profileId.refine(
+    profileId => !transformProfileId(profileId).startsWith('sample-'),
+    { message: 'Profile IDs beginning with "sample-" are reserved.' }
+);
+
 /**
  * Gets or creates a federated profile for cross-instance credential sending.
  * Federated profiles use email-like format: profileId@service-domain to avoid collisions.

package/src/helpers/share-content-client/adapters.ts

@@ -0,0 +1,55 @@
+import { getDidWebLearnCard, getServerDidWebDID } from '@helpers/learnCard.helpers';
+
+import type { ShareContentTokenSigner } from './types';
+
+/**
+ * Runtime signing adapter for the LC-2187 share-content service token.
+ *
+ * It reuses the existing did:web LearnCard signing primitives — no new
+ * cryptographic algorithm or key material is introduced. The fixed C1 verifier
+ * expects a holder-signed VP JWT whose `nonce` is the JSON-serialized claims
+ * object, signed with `EdDSA` by an allowlisted did:web verification method. The
+ * `kid` did:web fragment is produced by DIDKit from the signing key; the client
+ * independently re-checks that it binds the configured signer DID before any
+ * request is sent.
+ *
+ * Exported separately from the client barrel so unit tests never load the
+ * LearnCard/environment graph.
+ */
+export const createDidWebLearnCardTokenSigner = (dependencies?: {
+    getLearnCard?: () => Promise<{
+        invoke: { issuePresentation: (...args: unknown[]) => unknown };
+    }>;
+    getSignerDid?: () => string;
+}): ShareContentTokenSigner => {
+    const resolveLearnCard = dependencies?.getLearnCard ?? getDidWebLearnCard;
+    const resolveSignerDid = dependencies?.getSignerDid ?? getServerDidWebDID;
+
+    return async claims => {
+        const learnCard = await resolveLearnCard();
+        const signerDid = resolveSignerDid();
+
+        if (claims.iss !== signerDid) {
+            throw new Error('share-content signer DID does not match the token issuer binding');
+        }
+
+        const presentation = {
+            '@context': ['https://www.w3.org/2018/credentials/v1'],
+            type: ['VerifiablePresentation'],
+            holder: signerDid,
+            verifiableCredential: [],
+        };
+
+        const issued = await learnCard.invoke.issuePresentation(presentation, {
+            proofPurpose: 'authentication',
+            proofFormat: 'jwt',
+            challenge: JSON.stringify(claims),
+        });
+
+        if (typeof issued !== 'string' || issued.length === 0) {
+            throw new Error('share-content signer did not return a JWT presentation');
+        }
+
+        return issued;
+    };
+};

package/src/helpers/share-content-client/canonical.ts

@@ -0,0 +1,25 @@
+import { createHash } from 'node:crypto';
+import { canonicalizeShareContentRequestBody } from '@learncard/helpers';
+
+export {
+    canonicalizeShareContentRequestBody,
+    DEFAULT_MAX_CANONICAL_BYTES,
+    DEFAULT_MAX_CANONICAL_DEPTH,
+    ShareContentCanonicalizationError,
+} from '@learncard/helpers';
+
+/**
+ * SHA-256 (lowercase hex) over the canonical request body. This is exactly the
+ * value signed into `claims.requestHash` and recomputed by C1.
+ */
+export const computeShareContentRequestBodyHash = (
+    body: unknown,
+    options: { maxBytes?: number; maxDepth?: number } = {}
+): string =>
+    createHash('sha256')
+        .update(canonicalizeShareContentRequestBody(body, options), 'utf8')
+        .digest('hex');
+
+/** Strict lowercase hex SHA-256. */
+export const isSha256Hex = (value: unknown): value is string =>
+    typeof value === 'string' && /^[0-9a-f]{64}$/.test(value);