@learncard/network-brain-service 3.17.0 → 3.19.0

package/src/types/consentflowcontract.ts

@@ -3,9 +3,20 @@ import {
     ConsentFlowTermsValidator,
     ConsentFlowTermsStatusValidator,
     ConsentFlowTransactionActionValidator,
+    ConsentFlowGuardianApprovalValidator,
 } from '@learncard/types';
 import { z } from 'zod';
 
+type FlatGuardianApproval = {
+    [
+        Key in keyof z.infer<
+            typeof ConsentFlowGuardianApprovalValidator
+        > as `guardianApproval.${Key}`
+    ]?: string;
+};
+
+type FlatConsentTerms = Partial<Record<`terms.${string}`, string | boolean | string[]>>;
+
 export const DbContractValidator = z.object({
     id: z.string(),
     name: z.string(),
@@ -29,18 +40,23 @@ export const DbTransactionValidator = z.object({
     id: z.string(),
     action: ConsentFlowTransactionActionValidator,
     terms: ConsentFlowTermsValidator,
+    guardianApproval: ConsentFlowGuardianApprovalValidator.optional(),
     date: z.string(),
     expiresAt: z.string().optional(),
     oneTime: z.boolean().optional(),
 });
 
 export type DbTransactionType = z.infer<typeof DbTransactionValidator>;
-export type FlatDbTransactionType = DbTransactionType & { terms: any };
+export type FlatDbTransactionType = Omit<DbTransactionType, 'guardianApproval' | 'terms'> &
+    FlatConsentTerms &
+    FlatGuardianApproval;
 
 export const DbTermsValidator = z.object({
     id: z.string(),
     status: ConsentFlowTermsStatusValidator,
-    terms: ConsentFlowTermsValidator,
+    // Neo4j has no properties to store for entirely empty permission objects.
+    terms: ConsentFlowTermsValidator.prefault({}),
+    guardianApproval: ConsentFlowGuardianApprovalValidator.optional(),
     createdAt: z.string().optional(),
     updatedAt: z.string().optional(),
     expiresAt: z.string().optional(),
@@ -48,4 +64,6 @@ export const DbTermsValidator = z.object({
 });
 
 export type DbTermsType = z.infer<typeof DbTermsValidator>;
-export type FlatDbTermsType = DbTermsType & { terms: any };
+export type FlatDbTermsType = Omit<DbTermsType, 'guardianApproval' | 'terms'> &
+    FlatConsentTerms &
+    FlatGuardianApproval;

package/src/types/credential-refresh.ts

@@ -12,17 +12,26 @@ import {
  * immutable Credential nodes as holder-encrypted JWE JSON — never plaintext VC JSON.
  */
 
-export const CredentialRefreshStateValidator = z.enum(['awaiting_claim', 'active', 'revoked']);
+export const CredentialRefreshStateValidator = z.enum([
+    'pending_holder',
+    'awaiting_claim',
+    'active',
+    'revoked',
+]);
 export type CredentialRefreshState = z.infer<typeof CredentialRefreshStateValidator>;
 
 /** The managed refresh aggregate node (metadata only — no credential bodies) */
 export const CredentialRefreshRecordValidator = z.object({
+    /** Pending Universal Inbox delivery associated with this aggregate. */
+    inboxCredentialId: z.string().optional(),
+    /** Public status mechanism coordinates retained for the issuer allocation receipt. */
+    inboxCredentialStatus: z.string().optional(),
     /** Cryptographically random, unguessable public route identifier */
     refreshId: z.string().min(1),
     issuerProfileId: z.string().min(1),
     issuerDid: z.string().min(1),
     holderProfileId: z.string().min(1).optional(),
-    holderDid: z.string().min(1),
+    holderDid: z.string().min(1).optional(),
     /** Stable nonempty VC identifier shared by every version */
     credentialId: z.string().min(1),
     state: CredentialRefreshStateValidator,
@@ -45,6 +54,12 @@ export const CredentialRefreshRecordValidator = z.object({
     idempotencyKey: z.string().optional(),
     /** Issuer-authored, privacy-safe update summary */
     updateSummary: z.string().optional(),
+    /**
+     * Bounded, normalized credential display title used only for the email update
+     * notice. Never rendered in in-app/push payloads. Sourced from the unsigned
+     * publish input or the original boost template; never from decrypted content.
+     */
+    credentialDisplayName: z.string().optional(),
     lastPublishedAt: z.string().optional(),
     /** Notification delivery window key used to collapse repeat notifications */
     notificationWindowKey: z.string().optional(),
@@ -93,6 +108,8 @@ export const CredentialRefreshVersionNodeValidator = z.object({
     etag: z.string().optional(),
     signingMode: CredentialRefreshSigningModeValidator,
     updateSummary: z.string().optional(),
+    /** Bounded credential display title for the email update notice only. */
+    credentialDisplayName: z.string().optional(),
     /** Caller-provided key for replaying this exact historical publication */
     idempotencyKey: z.string().optional(),
     /** Aggregate-scoped unique key used to enforce historical idempotency */
@@ -132,6 +149,8 @@ export const AdvanceCredentialRefreshHeadParamsValidator = z.object({
     materialDigest: z.string().optional(),
     signingMode: CredentialRefreshSigningModeValidator,
     updateSummary: z.string().optional(),
+    /** Bounded credential display title persisted for the email update notice only. */
+    credentialDisplayName: z.string().optional(),
     idempotencyKey: z.string().optional(),
     /** Aggregate state observed by the caller; prevents claim/revocation races. */
     expectedState: CredentialRefreshStateValidator.optional(),

package/src/types/credential.ts

@@ -1,4 +1,16 @@
 import { z } from 'zod';
+import type { BitstringStatusListEntry, JWE, VC } from '@learncard/types';
 
-export const CredentialValidator = z.object({ id: z.string(), credential: z.string() });
+/** Internal issuance result; serialize and pass both fields together until storage. */
+export interface IssuedCredential {
+    readonly kind: 'issued-credential';
+    readonly credential: VC | JWE;
+    readonly statusEntries: BitstringStatusListEntry[];
+}
+
+export const CredentialValidator = z.object({
+    id: z.string(),
+    credential: z.string(),
+    statusEntries: z.string().optional(),
+});
 export type CredentialType = z.infer<typeof CredentialValidator>;

package/src/types/inbox-batch.ts

@@ -0,0 +1,46 @@
+import type { InboxBatchStatus, IssueInboxCredentialBatch } from '@learncard/types';
+import type { Context } from '@routes';
+
+export type BatchItem = {
+    id: string;
+    batchId: string;
+    index: number;
+    state: InboxBatchStatus['items'][number]['state'];
+    phase?: 'PREPARING' | 'ISSUING';
+    owner?: string;
+    leaseUntil?: number;
+    attempts: number;
+    result?: string;
+    replayKey: string;
+    duplicate: boolean;
+    /** Encrypted client correlation fields retained after the batch payload is removed. */
+    correlation?: string;
+};
+
+export type InboxDispatchLease = { id: string; dispatchAt: number };
+
+export type BatchJob = {
+    id: string;
+    issuer: string;
+    createdAt: number;
+    payload?: string;
+    completedAt?: number;
+};
+
+export type BatchJobPayload = {
+    batch: IssueInboxCredentialBatch;
+    context: Pick<Context, 'domain' | 'tenant'>;
+    /** Submitting caller's permissions, retained for deferred refresh authorization. */
+    scope?: string;
+};
+
+export type BatchReplayStore = {
+    get: (key: string) => Promise<string | null | undefined>;
+    setIfAbsent: (key: string, value: string, ttl: number) => Promise<'OK' | null | undefined>;
+    compareAndSet: (
+        key: string,
+        expected: string,
+        value: string | null,
+        ttl: number
+    ) => Promise<boolean | undefined>;
+};

package/test/app-store-listing.spec.ts

@@ -1,6 +1,7 @@
 import { describe, it, beforeAll, beforeEach, afterAll, expect } from 'vitest';
 
 import { getClient, getUser } from './helpers/getClient';
+import { minimalContract, minimalTerms } from './helpers/contract';
 
 import { AppStoreListing, Integration, Profile } from '@models';
 
@@ -40,7 +41,7 @@ let userB: Awaited<ReturnType<typeof getUser>>;
 let userC: Awaited<ReturnType<typeof getUser>>;
 
 // For access layer tests - can set all fields including protected ones
-const makeListingInput = (overrides?: Record<string, any>) => ({
+const makeListingInput = (overrides?: Record<string, unknown>) => ({
     display_name: 'Test App',
     tagline: 'A test application',
     full_description: 'This is a comprehensive test application for the app store',
@@ -54,7 +55,7 @@ const makeListingInput = (overrides?: Record<string, any>) => ({
 });
 
 // For router tests - excludes protected fields (app_listing_status, promotion_level)
-const makeRouterListingInput = (overrides?: Record<string, any>) => {
+const makeRouterListingInput = (overrides?: Record<string, unknown>) => {
     const { app_listing_status, promotion_level, ...rest } = makeListingInput(overrides);
     return rest;
 };
@@ -157,33 +158,6 @@ describe('AppStoreListing', () => {
                 expect(listing.contact_email).toBe('developer@example.com');
             });
 
-            it('creates and updates contact_email field', async () => {
-                // Create without contact_email
-                const listing = await createAppStoreListing(makeListingInput());
-                expect(listing.contact_email).toBeUndefined();
-
-                // Update to add contact_email
-                await updateAppStoreListing(listing, {
-                    contact_email: 'support@example.com',
-                });
-                const afterAdd = await readAppStoreListingById(listing.listing_id);
-                expect(afterAdd?.contact_email).toBe('support@example.com');
-
-                // Update to change contact_email
-                await updateAppStoreListing(afterAdd!, {
-                    contact_email: 'newcontact@example.com',
-                });
-                const afterChange = await readAppStoreListingById(listing.listing_id);
-                expect(afterChange?.contact_email).toBe('newcontact@example.com');
-
-                // Update to remove contact_email (cast to any to test null handling)
-                await updateAppStoreListing(afterChange!, {
-                    contact_email: null as any,
-                });
-                const afterRemove = await readAppStoreListingById(listing.listing_id);
-                expect(afterRemove?.contact_email).toBeUndefined();
-            });
-
             it('creates listing with custom listing_id', async () => {
                 const customId = 'custom-listing-123';
                 const listing = await createAppStoreListing(
@@ -671,7 +645,7 @@ describe('AppStoreListing', () => {
         const seedListingViaRouter = async (
             user: Awaited<ReturnType<typeof getUser>>,
             integrationId: string,
-            overrides?: Record<string, any>
+            overrides?: Record<string, unknown>
         ) => {
             // Router creates listings as DRAFT - protected fields are stripped
             const listingId = await user.clients.fullAuth.appStore.createListing({
@@ -692,6 +666,68 @@ describe('AppStoreListing', () => {
             }
         };
 
+        describe('request-learner-context authorization', () => {
+            it('uses current app consent and stops returning data after withdrawal', async () => {
+                const integrationId = await seedIntegrationViaRouter(userA);
+                const contractUri =
+                    await userA.clients.fullAuth.contracts.createConsentFlowContract({
+                        contract: minimalContract,
+                        name: 'App context consent',
+                    });
+                const listingId = await seedListingViaRouter(userA, integrationId, {
+                    launch_config_json: JSON.stringify({
+                        iframeUrl: 'https://app.example.com',
+                        contractUri,
+                    }),
+                });
+                await installAppForProfile('userb', listingId);
+                const request = {
+                    listingId,
+                    event: { type: 'request-learner-context' as const, includePersonalData: true },
+                };
+                await expect(
+                    userB.clients.fullAuth.appStore.appEvent(request)
+                ).rejects.toMatchObject({ code: 'FORBIDDEN' });
+                const { termsUri } = await userB.clients.fullAuth.contracts.consentToContract({
+                    contractUri,
+                    terms: minimalTerms,
+                });
+                const context = await userB.clients.fullAuth.appStore.appEvent(request);
+                expect(context.personalData).toEqual({ name: minimalTerms.read.personal.name });
+                expect(context.credentialUris).toEqual([]);
+                expect(context.did).toMatch(/:users:userb$/);
+                await userB.clients.fullAuth.contracts.withdrawConsent({ uri: termsUri });
+                await expect(
+                    userB.clients.fullAuth.appStore.appEvent(request)
+                ).rejects.toMatchObject({ code: 'FORBIDDEN' });
+            });
+
+            it('cannot borrow another integration owner’s consent contract', async () => {
+                const integrationId = await seedIntegrationViaRouter(userA);
+                const contractUri =
+                    await userB.clients.fullAuth.contracts.createConsentFlowContract({
+                        contract: minimalContract,
+                        name: 'Unrelated owner contract',
+                    });
+                await userA.clients.fullAuth.contracts.consentToContract({
+                    contractUri,
+                    terms: minimalTerms,
+                });
+                const listingId = await seedListingViaRouter(userA, integrationId, {
+                    launch_config_json: JSON.stringify({
+                        iframeUrl: 'https://app.example.com',
+                        contractUri,
+                    }),
+                });
+                await expect(
+                    userA.clients.fullAuth.appStore.appEvent({
+                        listingId,
+                        event: { type: 'request-learner-context', includePersonalData: true },
+                    })
+                ).rejects.toMatchObject({ code: 'FORBIDDEN' });
+            });
+        });
+
         describe('createListing', () => {
             it('requires app-store:write scope and an existing profile', async () => {
                 const integrationId = await seedIntegrationViaRouter(userA);

package/test/atomic-counter.e2e.ts

@@ -0,0 +1,12 @@
+import { afterAll, expect, it } from 'vitest';
+import cache from '@cache';
+import { testAtomicCacheCounter } from '../src/cache/atomic-counter.test-helpers';
+
+// Fail if the isolated Redis container is missing; never silently test the mock in CI.
+it('uses real Redis for the atomic counter contract', () => {
+    expect(cache.redis).toBeDefined();
+});
+testAtomicCacheCounter(cache);
+afterAll(async () => {
+    await cache.redis?.quit();
+});

package/test/auth-grant.spec.ts

@@ -200,7 +200,7 @@ describe('Auth Grants', () => {
 
             const authGrants = await userA.clients.fullAuth.authGrants.getAuthGrants();
             expect(authGrants).toHaveLength(1);
-            expect((authGrants[0] as any).id).toEqual(authGrantId);
+            expect(authGrants[0]?.id).toEqual(authGrantId);
 
             await userA.clients.fullAuth.authGrants.addAuthGrant({
                 name: 'test2',
@@ -209,8 +209,8 @@ describe('Auth Grants', () => {
             const authGrants2 = await userA.clients.fullAuth.authGrants.getAuthGrants();
 
             expect(authGrants2).toHaveLength(2);
-            expect(authGrants2[0] as any).toBeDefined();
-            expect(authGrants2[1] as any).toBeDefined();
+            expect(authGrants2[0]).toBeDefined();
+            expect(authGrants2[1]).toBeDefined();
         });
 
         it('should accept a limit', async () => {
@@ -247,7 +247,7 @@ describe('Auth Grants', () => {
             });
 
             expect(authGrants).toHaveLength(1);
-            expect((authGrants[0] as any).id).toEqual(authGrantId);
+            expect(authGrants[0]?.id).toEqual(authGrantId);
         });
     });
 
@@ -278,17 +278,18 @@ describe('Auth Grants', () => {
                 id: authGrantId,
             });
 
-            expect((updatedAuthGrant as any).name).toEqual('test2');
+            expect(updatedAuthGrant?.name).toEqual('test2');
         });
 
-        it('should not allow you to update the scopes, challenge, id, createdAt, expiresAt, status of an auth grant', async () => {
+        it('should reject updates to the scopes, actAs, challenge, id, createdAt, expiresAt, status of an auth grant', async () => {
             await userA.clients.fullAuth.profile.createProfile({ profileId: 'usera' });
             const authGrantId = await userA.clients.fullAuth.authGrants.addAuthGrant({
                 name: 'test',
             });
 
-            const invalidUpdates: any = {
+            const invalidUpdates: Record<string, string> = {
                 scope: '*:*',
+                actAs: '*',
                 challenge: 'test',
                 id: 'test',
                 createdAt: 'test',
@@ -296,27 +297,26 @@ describe('Auth Grants', () => {
                 status: 'revoked',
             };
 
-            for (const key in invalidUpdates) {
+            for (const [key, value] of Object.entries(invalidUpdates)) {
                 await expect(
                     userA.clients.fullAuth.authGrants.updateAuthGrant({
                         id: authGrantId,
-                        updates: {
-                            [key]: invalidUpdates[key],
-                        },
+                        updates: { [key]: value } as never,
                     })
-                ).resolves.toBe(false);
+                ).rejects.toMatchObject({ code: 'BAD_REQUEST' });
             }
 
             const updatedAuthGrant = await userA.clients.fullAuth.authGrants.getAuthGrant({
                 id: authGrantId,
             });
 
-            expect((updatedAuthGrant as any).scope).toEqual(AUTH_GRANT_READ_ONLY_SCOPE);
-            expect((updatedAuthGrant as any).challenge).not.toEqual('test');
-            expect((updatedAuthGrant as any).id).not.toEqual('test');
-            expect((updatedAuthGrant as any).createdAt).not.toEqual('test');
-            expect((updatedAuthGrant as any).expiresAt).not.toEqual('test');
-            expect((updatedAuthGrant as any).status).not.toEqual('revoked');
+            expect(updatedAuthGrant).toMatchObject({ scope: AUTH_GRANT_READ_ONLY_SCOPE });
+            expect(updatedAuthGrant?.challenge).not.toEqual('test');
+            expect(updatedAuthGrant?.id).not.toEqual('test');
+            expect(updatedAuthGrant?.createdAt).not.toEqual('test');
+            expect(updatedAuthGrant?.expiresAt).not.toEqual('test');
+            expect(updatedAuthGrant?.status).not.toEqual('revoked');
+            expect(updatedAuthGrant?.actAs).toBeUndefined();
         });
 
         // it('should not allow you to update an auth grant for a scoped user profile', async () => {
@@ -366,7 +366,7 @@ describe('Auth Grants', () => {
                 id: authGrantId,
             });
 
-            expect((updatedAuthGrant as any).name).toEqual('test2');
+            expect(updatedAuthGrant?.name).toEqual('test2');
         });
 
         it("should not allow you to update someone else's auth grant", async () => {
@@ -511,7 +511,7 @@ describe('Auth Grants', () => {
                 id: authGrantId,
             });
 
-            expect((authGrant as any).status).toEqual(AuthGrantStatusValidator.enum.revoked);
+            expect(authGrant?.status).toEqual(AuthGrantStatusValidator.enum.revoked);
         });
 
         // it('should not allow you to revoke an auth grant for a scoped user profile', async () => {
@@ -552,7 +552,7 @@ describe('Auth Grants', () => {
                 id: authGrantId,
             });
 
-            expect((authGrant as any).status).toEqual(AuthGrantStatusValidator.enum.revoked);
+            expect(authGrant?.status).toEqual(AuthGrantStatusValidator.enum.revoked);
         });
 
         it("should not allow you to revoke someone else's auth grant", async () => {

package/test/bitstring-status-list.spec.ts

@@ -1,3 +1,5 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
 import { Profile, Credential, Boost, StatusList } from '@models';
 import { app as statusListsApp } from '../src/status-lists';
 import { decodeBitstring } from '../src/helpers/status-list.helpers';
@@ -42,7 +44,7 @@ const isStatusBitSet = async (entry: any): Promise<boolean> => {
     const index = Number(entry.statusListIndex);
     const byte = bitstring[Math.floor(index / 8)] ?? 0;
 
-    return (byte & (1 << index % 8)) !== 0;
+    return (byte & (1 << (index % 8))) !== 0;
 };
 
 const statusBoostTemplate = {
@@ -78,18 +80,18 @@ const sendBoostWithStatus = async (
     const boostUri = await userA.clients.fullAuth.boost.createBoost({
         credential: template,
     });
-    const statusEntries =
-        statusPurpose === 'suspension'
-            ? await userA.clients.fullAuth.boost.allocateCredentialStatus({
-                  statusPurposes: ['suspension'],
-              })
-            : [];
+    // Status coordinates must be included in the issuer's signature. The network
+    // no longer adds a certified wrapper after receiving the signed credential.
+    const statusEntries = await userA.clients.fullAuth.boost.allocateCredentialStatus({
+        statusPurposes:
+            statusPurpose === 'suspension' ? ['suspension'] : ['revocation', 'suspension'],
+    });
 
     const signedCredential = await userA.learnCard.invoke.issueCredential({
         ...template,
         issuer: userA.learnCard.id.did(),
         validFrom: new Date().toISOString(),
-        ...(statusEntries[0] ? { credentialStatus: statusEntries[0] } : {}),
+        credentialStatus: statusEntries,
         credentialSubject: {
             id: userB.learnCard.id.did(),
         },
@@ -105,6 +107,7 @@ const sendBoostWithStatus = async (
     await userB.clients.fullAuth.credential.acceptCredential({ uri: credentialUri });
 
     const credential = await userB.clients.fullAuth.storage.resolve({ uri: credentialUri });
+    expect(credential).toEqual(signedCredential);
 
     return { credentialUri, credential, boostUri };
 };
@@ -140,7 +143,7 @@ describe('Bitstring Status List issuance', () => {
         expect(await isStatusBitSet(getEntryForPurpose(credential, 'revocation'))).toBe(false);
     });
 
-    it('allocates BOTH revocation and suspension entries by default (no statusPurposes passed)', async () => {
+    it('preserves both issuer-signed revocation and suspension entries', async () => {
         const { credential } = await sendBoostWithStatus();
         expect(getEntryForPurpose(credential, 'revocation').type).toBe('BitstringStatusListEntry');
         expect(getEntryForPurpose(credential, 'suspension').type).toBe('BitstringStatusListEntry');