@learncard/network-brain-service 3.19.0 → 4.0.0

package/src/helpers/notificationQueue.helpers.ts

@@ -1,14 +1,32 @@
-import { LCNNotificationValidator } from '@learncard/types';
+import { authorizeContractNotification } from '@helpers/contract-events.helpers';
+import { ConsentFlowWebhookMetadataValidator, LCNNotificationValidator } from '@learncard/types';
 
 import { acknowledgeConnectionPromptNotificationDelivery } from '@helpers/connectionPrompt.helpers';
-import { sendNotification } from '@helpers/notifications.helpers';
+import {
+    PermanentNotificationDeliveryError,
+    sendNotification,
+} from '@helpers/notifications.helpers';
 
 export const deliverQueuedNotification = async (body: string): Promise<void> => {
     const notification = await LCNNotificationValidator.parseAsync(JSON.parse(body));
 
-    const stored = await sendNotification(notification, {
-        propagateDirectWebhookTransportErrors: true,
-    });
+    if (!(await authorizeContractNotification(notification))) return;
+
+    const isContractEvent = ConsentFlowWebhookMetadataValidator.safeParse(
+        notification.data?.metadata
+    ).success;
+    let stored: boolean | undefined;
+    try {
+        stored = await sendNotification(notification, {
+            propagateDirectWebhookTransportErrors: true,
+            throwOnPermanentFailure: isContractEvent,
+        });
+    } catch (error) {
+        // Acknowledge terminal contract rejections so SQS can discard its payload too.
+        // Other notification types keep their existing worker behavior.
+        if (isContractEvent && error instanceof PermanentNotificationDeliveryError) return;
+        throw error;
+    }
 
     if (!stored) throw new Error('Notification was not durably stored');
 

package/src/helpers/notifications.helpers.ts

@@ -26,8 +26,20 @@ const TIMEOUT = 6000;
 
 type NotificationDeliveryOptions = {
     propagateDirectWebhookTransportErrors?: boolean;
+    /** Opt in to terminal rejection errors; legacy callers continue to receive false. */
+    throwOnPermanentFailure?: boolean;
 };
 
+export class PermanentNotificationDeliveryError extends Error {
+    constructor(
+        readonly reason: 'no_webhook' | 'invalid_webhook' | 'webhook_rejected',
+        readonly statusCode?: number
+    ) {
+        super(`Notification delivery rejected: ${reason}`);
+        this.name = 'PermanentNotificationDeliveryError';
+    }
+}
+
 type NotificationWebhookResponseRecord = Record<string, unknown>;
 
 const isDefinitiveWebhookRejection = (statusCode: number): boolean => {
@@ -308,6 +320,8 @@ export async function sendNotification(
         );
 
         if (!notificationsWebhook) {
+            if (options.throwOnPermanentFailure)
+                throw new PermanentNotificationDeliveryError('no_webhook');
             return false;
         }
 
@@ -360,7 +374,14 @@ export async function sendNotification(
             }
 
             if (!response.ok) {
-                if (isDefinitiveWebhookRejection(response.status)) return false;
+                if (isDefinitiveWebhookRejection(response.status)) {
+                    if (options.throwOnPermanentFailure)
+                        throw new PermanentNotificationDeliveryError(
+                            'webhook_rejected',
+                            response.status
+                        );
+                    return false;
+                }
 
                 throw createWebhookTransportError(response.status);
             }
@@ -411,7 +432,10 @@ export async function sendNotification(
 
             return notificationDelivered;
         }
+        if (options.throwOnPermanentFailure)
+            throw new PermanentNotificationDeliveryError('invalid_webhook');
     } catch (error) {
+        if (error instanceof PermanentNotificationDeliveryError) throw error;
         if (runtimeEnvironment.NODE_ENV !== 'test') {
             console.error('Notifications Helpers - Error While Sending:', error);
         }

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,17 @@ 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.' }
+);
+
+/** Legacy service flags never override an explicit child classification. */
+export const isServiceProfileExemptFromGuardianship = (
+    isServiceProfile: unknown,
+    profileType: unknown
+): boolean => isServiceProfile === true && profileType !== 'child';
+
 /**
  * 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);