@learncard/network-brain-service 4.1.3 → 5.0.0

package/src/routes/credential-input-privacy.test.ts

@@ -0,0 +1,92 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { resolveTenantFromRequest } from '@learncard/email-templates';
+import type {
+    PrepareRefreshableSendInput,
+    SendBoostInput,
+    PublishCredentialRefreshInput,
+} from '@learncard/types';
+
+const transport = vi.hoisted(() => ({ send: vi.fn(), lookup: vi.fn() }));
+vi.mock('@sentry/serverless', () => ({
+    Handlers: {
+        trpcMiddleware:
+            ({ attachRpcInput }: { attachRpcInput: boolean }) =>
+            async (opts: { next: () => Promise<unknown>; getRawInput: () => Promise<unknown> }) => {
+                const input = attachRpcInput ? await opts.getRawInput() : undefined;
+                try {
+                    return await opts.next();
+                } finally {
+                    transport.send({ input });
+                }
+            },
+    },
+    configureScope: vi.fn(),
+    setUser: vi.fn(),
+}));
+vi.mock('@accesslayer/profile/read', () => ({
+    getProfileByDid: transport.lookup,
+    getProfileByProfileId: transport.lookup,
+}));
+vi.mock('../models/credential-refresh-constraints', () => ({
+    ensureCredentialRefreshConstraints: vi.fn(),
+}));
+
+import { boostsRouter } from './boosts';
+import { credentialRefreshesRouter } from './credential-refreshes';
+import type { Context } from './index';
+
+describe('credential route input telemetry', () => {
+    beforeEach(() => {
+        process.env.CREDENTIAL_REFRESH_ENABLED = 'true';
+        transport.send.mockClear();
+        transport.lookup.mockResolvedValue({ profileId: 'issuer', did: 'did:key:issuer' });
+    });
+
+    it.each(['prepare', 'send', 'publish'] as const)(
+        '%s never captures malformed, unauthenticated or failing request input',
+        async route => {
+            const privateInput = {
+                recipient: 42,
+                signedCredential: 'PRIVATE CLAIM',
+                templateData: { private: 'PRIVATE CLAIM' },
+            };
+            const invoke = (ctx: Context): Promise<unknown> => {
+                if (route === 'prepare')
+                    return boostsRouter
+                        .createCaller(ctx)
+                        .prepareRefreshableSend(
+                            privateInput as unknown as PrepareRefreshableSendInput
+                        );
+                if (route === 'send')
+                    return boostsRouter
+                        .createCaller(ctx)
+                        .send(privateInput as unknown as SendBoostInput);
+                return credentialRefreshesRouter
+                    .createCaller(ctx)
+                    .publishCredentialRefresh(
+                        privateInput as unknown as PublishCredentialRefreshInput
+                    );
+            };
+            const authenticated: Context = {
+                domain: 'example.com',
+                tenant: resolveTenantFromRequest({}),
+                user: { did: 'did:key:issuer', isChallengeValid: true, scope: '*:*' },
+            };
+            await expect(invoke(authenticated)).rejects.toMatchObject({ code: 'BAD_REQUEST' });
+            await expect(
+                invoke({ domain: 'example.com', tenant: resolveTenantFromRequest({}) })
+            ).rejects.toMatchObject({
+                code: 'UNAUTHORIZED',
+            });
+            transport.lookup.mockRejectedValueOnce(new Error('LOOKUP_FAILED'));
+            await expect(invoke(authenticated)).rejects.toThrow('LOOKUP_FAILED');
+            expect(transport.send).toHaveBeenCalledTimes(3);
+            expect(transport.send.mock.calls).toEqual([
+                [{ input: undefined }],
+                [{ input: undefined }],
+                [{ input: undefined }],
+            ]);
+            expect(JSON.stringify(transport.send.mock.calls)).not.toContain('PRIVATE CLAIM');
+        }
+    );
+});

package/src/routes/credential-refreshes.ts

@@ -2,32 +2,50 @@ import { TRPCError } from '@trpc/server';
 import { z } from 'zod';
 import {
     AllocateCredentialRefreshInputValidator,
+    AttachCredentialRefreshStatusEntriesInputValidator,
     AllocateCredentialRefreshResultValidator,
+    EncryptionRecipientsResultValidator,
     GetCredentialRefreshHistoryInputValidator,
     GetCredentialRefreshHistoryResultValidator,
+    GetEncryptionRecipientsInputValidator,
     PublishCredentialRefreshInputValidator,
     PublishCredentialRefreshResultValidator,
+    PublishHolderEncryptedRefreshInputValidator,
+    SendHolderEncryptedRefreshableInputValidator,
     VCValidator,
+    GetCredentialRefreshReceiptInputValidator,
+    CredentialRefreshReceiptValidator,
 } from '@learncard/types';
 import type { PublishCredentialRefreshInput } from '@learncard/types';
 
-import { t, profileRoute } from '@routes';
+import { t, credentialProfileRoute } from '@routes';
 import { getCredentialRefreshRuntimeEnvironment } from '@environment';
 import { getProfileByDid, getProfileByProfileId } from '@accesslayer/profile/read';
 import {
     getCredentialRefresh,
     getCredentialRefreshVersions,
+    getCredentialRefreshReceiptBinding,
 } from '@accesslayer/credential-refresh';
 import {
     allocateCredentialRefresh,
+    getCurrentEncryptionRecipients,
     publishCredentialRefresh,
+    publishHolderEncryptedRefreshableCredential,
+    sendHolderEncryptedRefreshableCredential,
     sendRefreshableCredential,
 } from '@helpers/credential-refresh.helpers';
 import { getDidWeb } from '@helpers/did.helpers';
 import { isRelationshipBlocked } from '@helpers/connection.helpers';
 import { ensureCredentialRefreshConstraints } from '../models/credential-refresh-constraints';
+import { getBitstringStatusListEntries } from '@learncard/helpers';
+import { neogma } from '@instance';
+import { matchesCredentialStatusDigest } from '@helpers/credential-refresh-materiality.helpers';
+import { bindRefreshStatusEntries } from '@helpers/managed-status.helpers';
+import { getStatusManagement } from '@helpers/status-list.helpers';
+import { constructUri, getUriParts } from '@helpers/uri.helpers';
+import { getCredentialRefreshServiceUrl } from '@helpers/credential-refresh.helpers';
 
-const credentialRefreshRoute = profileRoute.use(async ({ ctx, next }) => {
+const credentialRefreshRoute = credentialProfileRoute.use(async ({ ctx, next }) => {
     if (!getCredentialRefreshRuntimeEnvironment().CREDENTIAL_REFRESH_ENABLED) {
         throw new TRPCError({
             code: 'NOT_FOUND',
@@ -41,6 +59,149 @@ const credentialRefreshRoute = profileRoute.use(async ({ ctx, next }) => {
 });
 
 export const credentialRefreshesRouter = t.router({
+    getReceipt: credentialRefreshRoute
+        .meta({ requiredScope: 'credentials:read' })
+        .input(GetCredentialRefreshReceiptInputValidator)
+        .output(CredentialRefreshReceiptValidator.nullable())
+        .query(async ({ ctx, input }) => {
+            const { id, type } = getUriParts(input.uri);
+            if (type !== 'credential' || input.uri !== constructUri('credential', id, ctx.domain)) {
+                throw new TRPCError({ code: 'BAD_REQUEST', message: 'Invalid delivery URI' });
+            }
+            const refresh = await getCredentialRefreshReceiptBinding(
+                id,
+                ctx.user.profile.profileId
+            );
+            if (refresh === null) return null;
+            if (
+                !refresh ||
+                !refresh.holderDid ||
+                refresh.holderProfileId !== ctx.user.profile.profileId ||
+                !['awaiting_claim', 'active'].includes(refresh.state)
+            ) {
+                throw new TRPCError({ code: 'NOT_FOUND', message: 'Delivery not found' });
+            }
+            // Coordinates alone cannot reconstruct the exact signed descriptor of legacy sends.
+            let binding = refresh.credentialStatusBinding ?? refresh.inboxCredentialStatus;
+            if (binding === undefined) {
+                binding = await neogma.getTransaction(null, async tx => {
+                    const result = await tx.run(
+                        `MATCH (refresh:CredentialRefresh {refreshId: $refreshId})
+                         SET refresh._statusBindingLock = true
+                         REMOVE refresh._statusBindingLock
+                         RETURN refresh.credentialStatusBinding AS binding,
+                                refresh.inboxCredentialStatus AS inboxBinding,
+                                refresh.credentialStatusDigest AS digest`,
+                        { refreshId: refresh.refreshId }
+                    );
+                    const row = result.records[0];
+                    const existing: unknown = row?.get('binding') ?? row?.get('inboxBinding');
+                    if (typeof existing === 'string') return existing;
+                    const digest: unknown = row?.get('digest');
+                    if (
+                        typeof digest !== 'string' ||
+                        !matchesCredentialStatusDigest(null, digest)
+                    ) {
+                        return undefined;
+                    }
+                    // The JSON string "null" authenticates absence; an unset property
+                    // means an unknown legacy descriptor. Never store Neo4j null.
+                    await tx.run(
+                        `MATCH (refresh:CredentialRefresh {refreshId: $refreshId})
+                         SET refresh.credentialStatusBinding = 'null'`,
+                        { refreshId: refresh.refreshId }
+                    );
+                    return 'null';
+                });
+            }
+            if (binding === undefined) {
+                throw new TRPCError({
+                    code: 'PRECONDITION_FAILED',
+                    message: 'Delivery binding unavailable',
+                });
+            }
+            const status: unknown = JSON.parse(binding);
+            return CredentialRefreshReceiptValidator.parse({
+                refreshId: refresh.refreshId,
+                credentialId: refresh.credentialId,
+                issuerDid: refresh.issuerDid,
+                holderDid: refresh.holderDid,
+                ...(refresh.refreshServiceBinding
+                    ? {}
+                    : { refreshServiceBinding: 'managed-entry' }),
+                refreshService: refresh.refreshServiceBinding
+                    ? JSON.parse(refresh.refreshServiceBinding)
+                    : {
+                          id: getCredentialRefreshServiceUrl(refresh.refreshId, ctx.domain),
+                          type: 'LearnCardCredentialRefresh2026',
+                          authorization: { type: 'LearnCardDIDAuth' },
+                      },
+                ...(status === null ? {} : { credentialStatus: status }),
+                encryptionMode: refresh.encryptionMode ?? 'network',
+            });
+        }),
+
+    attachStatusEntries: credentialRefreshRoute
+        .meta({ requiredScope: 'credentials:write' })
+        .input(AttachCredentialRefreshStatusEntriesInputValidator)
+        .output(z.boolean())
+        .mutation(async ({ ctx, input }) => {
+            const refresh = await getCredentialRefresh(input.refreshId);
+            if (!refresh || refresh.issuerProfileId !== ctx.user.profile.profileId) {
+                throw new TRPCError({ code: 'NOT_FOUND', message: 'Credential refresh not found' });
+            }
+            if (
+                !matchesCredentialStatusDigest(
+                    input.credentialStatus,
+                    refresh.credentialStatusDigest
+                )
+            ) {
+                throw new TRPCError({
+                    code: 'BAD_REQUEST',
+                    message: 'Credential status does not match the original credential',
+                });
+            }
+            const entries = getBitstringStatusListEntries({
+                credentialStatus: input.credentialStatus ?? undefined,
+            });
+            if (entries.length === 0 && input.credentialStatus !== null) {
+                throw new TRPCError({
+                    code: 'BAD_REQUEST',
+                    message: 'Credential has no supported public status entries',
+                });
+            }
+            await neogma.getTransaction(null, async tx => {
+                const result = await tx.run(
+                    `MATCH (refresh:CredentialRefresh {refreshId: $refreshId})-[:ROOT]->(root:Credential)
+                 SET root._statusMutationLock = true REMOVE root._statusMutationLock
+                 RETURN root.id AS id`,
+                    { refreshId: input.refreshId }
+                );
+                const root = result.records[0];
+                if (!root)
+                    throw new TRPCError({
+                        code: 'CONFLICT',
+                        message: 'Credential has no original delivery',
+                    });
+                await bindRefreshStatusEntries(
+                    input.refreshId,
+                    entries,
+                    refresh.issuerProfileId,
+                    ctx.domain,
+                    tx
+                );
+                await tx.run(
+                    `MATCH (refresh:CredentialRefresh {refreshId: $refreshId})
+                     SET refresh.credentialStatusBinding = $credentialStatusBinding`,
+                    {
+                        refreshId: input.refreshId,
+                        credentialStatusBinding: JSON.stringify(input.credentialStatus),
+                    }
+                );
+            });
+            return true;
+        }),
+
     allocateCredentialRefresh: credentialRefreshRoute
         .meta({
             openapi: {
@@ -136,6 +297,83 @@ export const credentialRefreshesRouter = t.router({
             return uri;
         }),
 
+    /**
+     * Holder-mode counterpart of `sendRefreshableCredential` (LC-2345): a separate
+     * route rather than a branch of `send`/`sendRefreshableCredential`, so the
+     * ciphertext-only input shape (`HolderEncryptedHandoffValidator`) never has to
+     * share a validator with the plaintext `credential`/`signedCredential` paths.
+     */
+    sendHolderEncryptedRefreshable: credentialRefreshRoute
+        .meta({
+            openapi: {
+                protect: true,
+                method: 'POST',
+                path: '/credential-refresh/send-holder-encrypted',
+                tags: ['Credential Refresh'],
+                summary: 'Send a holder-mode (student-only encrypted) refreshable credential',
+                description:
+                    'Binds an already-encrypted handoff to its allocated refresh aggregate. The server never decrypts or processes the credential.',
+            },
+            requiredScope: 'credentials:write',
+        })
+        .input(SendHolderEncryptedRefreshableInputValidator)
+        .output(
+            z.object({
+                uri: z.string(),
+                activityId: z.string(),
+                statusManagement: z.enum(['network', 'external', 'mixed', 'none']),
+            })
+        )
+        .mutation(async ({ ctx, input }) => {
+            const { profile } = ctx.user;
+
+            const { uri, activityId } = await sendHolderEncryptedRefreshableCredential({
+                issuerProfile: profile,
+                handoff: input.handoff,
+                idempotencyKey: input.idempotencyKey,
+                boostUri: input.boostUri,
+                skipNotification: input.skipNotification,
+                domain: ctx.domain,
+                onBehalfOf: ctx.user.onBehalfOf,
+            });
+
+            return {
+                uri,
+                activityId,
+                statusManagement: getStatusManagement(
+                    getBitstringStatusListEntries(input.handoff),
+                    ctx.domain
+                ),
+            };
+        }),
+
+    /** Issuer-only: the current recipient set a holder-mode handoff must encrypt to. */
+    getEncryptionRecipients: credentialRefreshRoute
+        .meta({
+            openapi: {
+                protect: true,
+                method: 'GET',
+                path: '/credential-refresh/encryption-recipients',
+                tags: ['Credential Refresh'],
+                summary: 'Get the current holder-mode encryption recipients',
+                description:
+                    'Returns the current key-agreement verification-method ids (holder + managers) a holder-mode handoff must encrypt to. Used after a RECIPIENTS_CHANGED conflict.',
+            },
+            requiredScope: 'credentials:read',
+        })
+        .input(GetEncryptionRecipientsInputValidator)
+        .output(EncryptionRecipientsResultValidator)
+        .query(async ({ ctx, input }) => {
+            const { profile } = ctx.user;
+
+            const recipientKeyIds = await getCurrentEncryptionRecipients({
+                issuerProfile: profile,
+                refreshId: input.refreshId,
+            });
+
+            return { recipientKeyIds };
+        }),
+
     publishCredentialRefresh: credentialRefreshRoute
         .meta({
             openapi: {
@@ -162,6 +400,38 @@ export const credentialRefreshesRouter = t.router({
             });
         }),
 
+    /**
+     * Holder-mode counterpart of `publishCredentialRefresh`: a separate route, for the
+     * same reason as `sendHolderEncryptedRefreshable`. `PublishCredentialRefreshInputValidator`
+     * has no signing-authority equivalent for a handoff — a holder aggregate rejects
+     * signing-authority publication outright (`publishCredentialRefresh` enforces this).
+     */
+    publishHolderEncryptedRefreshable: credentialRefreshRoute
+        .meta({
+            openapi: {
+                protect: true,
+                method: 'POST',
+                path: '/credential-refresh/publish-holder-encrypted',
+                tags: ['Credential Refresh'],
+                summary: 'Publish a holder-mode (student-only encrypted) refresh version',
+                description:
+                    'Publishes a new immutable version from an already-encrypted handoff and atomically advances the refresh head. `notify` replaces server-inferred materiality.',
+            },
+            requiredScope: 'credentials:write',
+        })
+        .input(PublishHolderEncryptedRefreshInputValidator)
+        .output(PublishCredentialRefreshResultValidator)
+        .mutation(async ({ ctx, input }) => {
+            const { profile } = ctx.user;
+
+            return publishHolderEncryptedRefreshableCredential({
+                issuerProfile: profile,
+                input,
+                domain: ctx.domain,
+                branding: ctx.tenant?.emailBranding,
+            });
+        }),
+
     getCredentialRefreshHistory: credentialRefreshRoute
         .meta({
             openapi: {
@@ -212,6 +482,7 @@ export const credentialRefreshesRouter = t.router({
                     etag: record.etag,
                     signingMode: record.signingMode,
                     updateSummary: record.updateSummary,
+                    updateReason: record.updateReason,
                 })),
                 hasMore,
                 cursor,

package/src/routes/federation.ts

@@ -9,7 +9,7 @@ import {
     getServerDidWebDID,
     getOwningServiceDid,
 } from '@helpers/federation.helpers';
-import { getProfileByProfileId } from '@accesslayer/profile/read';
+import { getProfileByDid, getProfileByProfileId } from '@accesslayer/profile/read';
 import { getProfileIdFromDid } from '@helpers/did.helpers';
 
 import { getOrCreateFederatedProfile } from '@helpers/profile.helpers';
@@ -99,13 +99,18 @@ export const federationRouter = t.router({
                     senderDid,
                     issuerDisplayName
                 );
+                // A local sender's status lists belong to its real profile, not the federated alias.
+                const localIssuer = await getProfileByDid(issuerDid);
 
                 const credentialUri = await sendCredential(
                     federatedSender,
                     recipientProfile,
                     credential,
                     ctx.domain,
-                    configuration
+                    configuration,
+                    undefined,
+                    undefined,
+                    localIssuer?.profileId ?? federatedSender.profileId
                 );
 
                 return {

package/src/routes/inbox.ts

@@ -3,6 +3,7 @@ import { submitInboxBatch, getInboxBatch } from '@helpers/inbox-queue.helpers';
 import {
     assertInboxRefreshEnabled,
     inboxRefreshRequestDigest,
+    getInboxRefreshRequestDigestCandidates,
     getInboxRefreshReplay,
     getInboxRefreshReceipt,
     resumeInboxRefreshDelivery,
@@ -466,7 +467,8 @@ export const inboxRouter = t.router({
                 const replay = await getInboxRefreshReplay(
                     profile.profileId,
                     input.idempotencyKey,
-                    refreshDigest!
+                    refreshDigest!,
+                    getInboxRefreshRequestDigestCandidates(input)
                 );
                 if (replay && (replay.claimUrl || replay.inbox.currentStatus !== 'PENDING')) {
                     await resumeInboxRefreshDelivery(replay.inbox.refreshId!, ctx.domain);
@@ -511,6 +513,9 @@ export const inboxRouter = t.router({
                         refresh: input.refresh,
                         idempotencyKey: input.idempotencyKey,
                         refreshRequestDigest: refreshDigest,
+                        refreshRequestDigestCandidates: input.refresh
+                            ? getInboxRefreshRequestDigestCandidates(input)
+                            : undefined,
                     },
                     ctx
                 );

package/src/routes/index.ts

@@ -9,7 +9,11 @@ import { CreateFastifyContextOptions } from '@trpc/server/adapters/fastify';
 import { OpenApiMeta } from 'trpc-to-openapi';
 import jwtDecode from 'jwt-decode';
 import * as Sentry from '@sentry/serverless';
-import { ACT_AS_HEADER, AUTH_GRANT_AUDIENCE_DOMAIN_PREFIX } from '@learncard/types';
+import {
+    ACT_AS_HEADER,
+    AUTH_GRANT_AUDIENCE_DOMAIN_PREFIX,
+    CONTRACT_APPROVAL_REQUIRED,
+} from '@learncard/types';
 import { ContactMethodType } from '@learncard/types';
 import { MAX_SHARE_LINK_REQUEST_BYTES, utf8ByteLength } from '@learncard/types';
 
@@ -80,6 +84,18 @@ export const t = initTRPC
             input: RegExpTransformer,
             output: { serialize: o => o, deserialize: o => o },
         },
+        errorFormatter: ({ shape, error }) => ({
+            ...shape,
+            data: {
+                ...shape.data,
+                reason:
+                    error.cause &&
+                    'code' in error.cause &&
+                    error.cause.code === CONTRACT_APPROVAL_REQUIRED
+                        ? CONTRACT_APPROVAL_REQUIRED
+                        : undefined,
+            },
+        }),
     });
 
 export const createContext = async (
@@ -290,7 +306,9 @@ export const PUBLIC_SHARE_LINK_ROUTE_PREFIX = 'publicShareLinks.';
 export const publicShareLinkCacheControlHeaders = (
     paths: readonly string[] | undefined
 ): Record<string, string> =>
-    (paths ?? []).some(path => path.startsWith(PUBLIC_SHARE_LINK_ROUTE_PREFIX))
+    (paths ?? []).some(
+        path => path.startsWith(PUBLIC_SHARE_LINK_ROUTE_PREFIX) || path === 'campaigns.unsubscribe'
+    )
         ? { 'Cache-Control': 'private, no-store' }
         : {};
 
@@ -493,6 +511,17 @@ export const didRouteWithoutInputCapture = withDid(openRouteWithoutInputCapture)
 export const didAndChallengeRouteWithoutInputCapture = withChallenge(didRouteWithoutInputCapture);
 export const profileRouteWithoutInputCapture = withProfile(didAndChallengeRouteWithoutInputCapture);
 
+/** Credential payloads need the same privacy/auth chain, not the share-link byte limit. */
+export const credentialProfileRoute = withProfile(
+    withChallenge(
+        withDid(
+            t.procedure
+                .use(t.middleware(sentryNoInputCaptureMiddleware))
+                .use(sentryTransactionNameMiddleware)
+        )
+    )
+);
+
 export const openProfileManagerRoute = openRoute.use(async ({ ctx, next }) => {
     if (!ctx.user?.did) throw new TRPCError({ code: 'UNAUTHORIZED' });