@learncard/network-brain-service 3.19.0 → 4.0.0

package/src/routes/workflows.ts

@@ -409,6 +409,7 @@ async function handlePresentationForClaim(
         // Inject OBv3 skill alignments based on boost's framework/skills
         await injectObv3AlignmentsIntoCredentialForBoost(boostCredential, boost, domain);
 
+        // encrypt=false on purpose: interoperable claim wallets may not decrypt LearnCard JWEs. See LC-2201.
         const vc = (
             await issueCredentialWithSigningAuthority(
                 { type: 'profile', profile: saOwnerProfile },
@@ -679,14 +680,14 @@ async function handleInboxClaimPresentation(
                 // Set issuer from signing authority
                 unsignedCredential.issuer = signingAuthorityForUser.relationship.did;
 
-                // Sign the credential
+                // encrypt=false on purpose: interoperable inbox claim wallets may not decrypt LearnCard JWEs. See LC-2201.
                 finalCredential = (
                     await issueCredentialWithSigningAuthority(
                         { type: 'profile', profile: issuerProfile },
                         unsignedCredential,
                         signingAuthorityForUser,
                         ctx.domain,
-                        false // don't encrypt
+                        false
                     )
                 ).credential as VC;
             }

package/src/services/delivery/adapters/postmark.adapter.ts

@@ -178,7 +178,10 @@ export class PostmarkAdapter implements DeliveryService {
                 };
 
             case 'recovery-key':
-                return { recoveryKey: model.recoveryKey };
+                return {
+                    recoveryKey: model.recoveryKey,
+                    confirmationCode: model.confirmationCode,
+                };
 
             case 'endorsement-request':
                 return {

package/src/types/app-manifest.ts

@@ -0,0 +1,28 @@
+import { z } from 'zod';
+
+import {
+    AppManifestValidator,
+    AppManifestVersionValidator,
+    AppManifestDiffValidator,
+} from '@learncard/types';
+
+export const AppManifestTypeValidator = AppManifestValidator;
+export type AppManifestType = z.infer<typeof AppManifestTypeValidator>;
+
+export const AppManifestVersionTypeValidator = AppManifestVersionValidator;
+export type AppManifestVersionType = z.infer<typeof AppManifestVersionTypeValidator>;
+
+export const FlatAppManifestVersionValidator = z.object({
+    id: z.string(),
+    version: z.number().int().min(1),
+    manifestHash: z.string(),
+    manifestJson: z.string(),
+    status: z.enum(['draft', 'active', 'superseded']),
+    createdAt: z.string(),
+    activatedAt: z.string().optional(),
+});
+
+export type FlatAppManifestVersionType = z.infer<typeof FlatAppManifestVersionValidator>;
+
+export const AppManifestDiffTypeValidator = AppManifestDiffValidator;
+export type AppManifestDiffType = z.infer<typeof AppManifestDiffTypeValidator>;

package/src/types/app-store-listing.ts

@@ -19,6 +19,16 @@ export type PromotionLevelEnum = z.infer<typeof PromotionLevel>;
 export const AgeRating = z.enum(['4+', '9+', '12+', '17+']);
 export type AgeRatingEnum = z.infer<typeof AgeRating>;
 
+export const PendingListingUpdateStatus = z.enum(['DRAFT', 'PENDING_REVIEW']);
+export type PendingListingUpdateStatusEnum = z.infer<typeof PendingListingUpdateStatus>;
+
+/** Changes to a LISTED app held back until review, stored as listing storage fields. */
+export const StoredPendingListingUpdateValidator = z.object({
+    changes: z.record(z.string(), z.unknown()).default({}),
+    manifestVersion: z.number().int().min(1).optional(),
+});
+export type StoredPendingListingUpdate = z.infer<typeof StoredPendingListingUpdateValidator>;
+
 export const AppStoreListingValidator = z.object({
     listing_id: z.string(),
     slug: z.string().optional(),
@@ -43,6 +53,9 @@ export const AppStoreListingValidator = z.object({
     age_rating: AgeRating.optional(),
     submitted_at: z.string().optional(),
     contact_email: z.string().email().optional(),
+    pending_update_json: z.string().optional(),
+    pending_update_status: PendingListingUpdateStatus.optional(),
+    pending_update_submitted_at: z.string().optional(),
 });
 export type AppStoreListingType = z.infer<typeof AppStoreListingValidator>;
 

package/src/types/consentflowcontract.ts

@@ -4,6 +4,7 @@ import {
     ConsentFlowTermsStatusValidator,
     ConsentFlowTransactionActionValidator,
     ConsentFlowGuardianApprovalValidator,
+    ConsentFlowReferralValidator,
 } from '@learncard/types';
 import { z } from 'zod';
 
@@ -15,6 +16,10 @@ type FlatGuardianApproval = {
     ]?: string;
 };
 
+type FlatReferral = {
+    [Key in keyof z.infer<typeof ConsentFlowReferralValidator> as `referral.${Key}`]?: string;
+};
+
 type FlatConsentTerms = Partial<Record<`terms.${string}`, string | boolean | string[]>>;
 
 export const DbContractValidator = z.object({
@@ -31,6 +36,8 @@ export const DbContractValidator = z.object({
     createdAt: z.string(),
     updatedAt: z.string(),
     expiresAt: z.string().optional(),
+    audienceVersion: z.coerce.number().int().nonnegative().optional(),
+    hasConsented: z.boolean().optional(),
 });
 
 export type DbContractType = z.infer<typeof DbContractValidator>;
@@ -41,22 +48,35 @@ export const DbTransactionValidator = z.object({
     action: ConsentFlowTransactionActionValidator,
     terms: ConsentFlowTermsValidator,
     guardianApproval: ConsentFlowGuardianApprovalValidator.optional(),
+    referral: ConsentFlowReferralValidator.optional(),
     date: z.string(),
     expiresAt: z.string().optional(),
     oneTime: z.boolean().optional(),
 });
 
 export type DbTransactionType = z.infer<typeof DbTransactionValidator>;
-export type FlatDbTransactionType = Omit<DbTransactionType, 'guardianApproval' | 'terms'> &
+export type FlatDbTransactionType = Omit<
+    DbTransactionType,
+    'guardianApproval' | 'terms' | 'referral'
+> &
     FlatConsentTerms &
-    FlatGuardianApproval;
+    FlatGuardianApproval &
+    FlatReferral;
 
 export const DbTermsValidator = z.object({
+    smartResumeFingerprint: z.string().optional(),
+    smartResumePublicationStatus: z.enum(['pending', 'sending', 'failed', 'succeeded']).optional(),
+    smartResumeLeaseId: z.string().optional(),
+    smartResumeLeaseUntil: z.coerce.number().optional(),
+    smartResumeMutationVersion: z.coerce.number().optional(),
+    smartResumeRedirectUrl: z.string().optional(),
+    mutationVersion: z.coerce.number().int().nonnegative().optional(),
     id: z.string(),
     status: ConsentFlowTermsStatusValidator,
     // Neo4j has no properties to store for entirely empty permission objects.
     terms: ConsentFlowTermsValidator.prefault({}),
     guardianApproval: ConsentFlowGuardianApprovalValidator.optional(),
+    referral: ConsentFlowReferralValidator.optional(),
     createdAt: z.string().optional(),
     updatedAt: z.string().optional(),
     expiresAt: z.string().optional(),
@@ -64,6 +84,7 @@ export const DbTermsValidator = z.object({
 });
 
 export type DbTermsType = z.infer<typeof DbTermsValidator>;
-export type FlatDbTermsType = Omit<DbTermsType, 'guardianApproval' | 'terms'> &
+export type FlatDbTermsType = Omit<DbTermsType, 'guardianApproval' | 'terms' | 'referral'> &
     FlatConsentTerms &
-    FlatGuardianApproval;
+    FlatGuardianApproval &
+    FlatReferral;

package/test/app-manifest.helpers.spec.ts

@@ -0,0 +1,170 @@
+import { describe, expect, it } from 'vitest';
+
+import type { AppManifest } from '@learncard/types';
+
+import {
+    canonicalizeManifest,
+    diffManifests,
+    hashManifest,
+} from '../src/helpers/app-manifest.helpers';
+
+const makeManifest = (overrides: Partial<AppManifest> = {}): AppManifest => ({
+    manifestVersion: 1,
+    appUrl: 'https://example.com',
+    suggestedName: 'Example App',
+    suggestedIconUrl: 'https://example.com/icon.png',
+    permissions: ['send_credential'],
+    templates: [
+        {
+            alias: 'completion',
+            version: 1,
+            lastUsedAt: '2026-01-01T00:00:00.000Z',
+            template: {
+                name: 'Course Completion: {{courseName}}',
+                description: 'Awarded to {{learnerName}}',
+                category: 'Achievement',
+            },
+        },
+    ],
+    consentRequests: [
+        {
+            scopes: {
+                read: {
+                    credentialCategories: ['Achievement'],
+                    personalFields: ['email'],
+                },
+                write: {
+                    credentialCategories: ['Achievement'],
+                },
+            },
+            reason: 'Show progress',
+            lastUsedAt: '2026-01-01T00:00:00.000Z',
+        },
+    ],
+    featuresLaunched: ['/wallet'],
+    counterKeys: ['coins'],
+    usedLearnerContext: false,
+    usedNotifications: false,
+    firstCapturedAt: '2026-01-01T00:00:00.000Z',
+    lastUpdatedAt: '2026-01-01T00:00:00.000Z',
+    ...overrides,
+});
+
+describe('app-manifest.helpers', () => {
+    it('canonicalizes and hashes manifests deterministically while ignoring volatile timestamps', () => {
+        const first = makeManifest();
+        const second = makeManifest({
+            permissions: ['send_credential'],
+            templates: [
+                {
+                    alias: 'completion',
+                    version: 1,
+                    lastUsedAt: '2026-02-01T00:00:00.000Z',
+                    template: {
+                        description: 'Awarded to {{learnerName}}',
+                        category: 'Achievement',
+                        name: 'Course Completion: {{courseName}}',
+                    },
+                },
+            ],
+            consentRequests: [
+                {
+                    scopes: {
+                        read: {
+                            credentialCategories: ['Achievement'],
+                            personalFields: ['email'],
+                        },
+                        write: {
+                            credentialCategories: ['Achievement'],
+                        },
+                    },
+                    reason: 'Show progress',
+                    lastUsedAt: '2026-02-01T00:00:00.000Z',
+                },
+            ],
+            firstCapturedAt: '2026-03-01T00:00:00.000Z',
+            lastUpdatedAt: '2026-03-01T00:00:00.000Z',
+        });
+
+        expect(canonicalizeManifest(first)).toBe(canonicalizeManifest(second));
+        expect(hashManifest(first)).toBe(hashManifest(second));
+    });
+
+    it('computes diffs and flags review when permissions or consent scopes expand', () => {
+        const current = makeManifest();
+        const next = makeManifest({
+            permissions: ['send_credential', 'request_consent'],
+            templates: [
+                {
+                    alias: 'completion',
+                    version: 2,
+                    lastUsedAt: '2026-01-02T00:00:00.000Z',
+                    template: {
+                        name: 'Course Completion: {{courseName}}',
+                        description: 'Awarded to {{learnerName}}',
+                        category: 'Achievement',
+                        issuerName: 'Example University',
+                    },
+                },
+                {
+                    alias: 'badge',
+                    version: 1,
+                    lastUsedAt: '2026-01-02T00:00:00.000Z',
+                    template: {
+                        name: 'Skill Badge: {{skillName}}',
+                        category: 'Skill',
+                    },
+                },
+            ],
+            consentRequests: [
+                ...current.consentRequests,
+                {
+                    scopes: {
+                        read: {
+                            credentialCategories: ['Achievement', 'Skill'],
+                            personalFields: ['email', 'name'],
+                        },
+                        write: {
+                            credentialCategories: ['Achievement'],
+                        },
+                    },
+                    reason: 'Expanded access',
+                    lastUsedAt: '2026-01-02T00:00:00.000Z',
+                },
+            ],
+            featuresLaunched: ['/wallet', '/pathways'],
+            counterKeys: ['coins', 'streak'],
+        });
+
+        expect(diffManifests(current, next)).toEqual({
+            permissions: {
+                added: ['request_consent'],
+                removed: [],
+                changed: [],
+            },
+            templates: {
+                added: [{ alias: 'badge', version: 1 }],
+                removed: [],
+                changed: [{ alias: 'completion', fromVersion: 1, toVersion: 2 }],
+            },
+            consentScopes: {
+                added: [
+                    '{"read":{"credentialCategories":["Achievement","Skill"],"personalFields":["email","name"]},"write":{"credentialCategories":["Achievement"]}}',
+                ],
+                removed: [],
+                changed: [],
+            },
+            featurePaths: {
+                added: ['/pathways'],
+                removed: [],
+                changed: [],
+            },
+            counterKeys: {
+                added: ['streak'],
+                removed: [],
+                changed: [],
+            },
+            requiresReview: true,
+        });
+    });
+});

package/test/app-manifest.routes.spec.ts

@@ -0,0 +1,299 @@
+import { afterAll, beforeAll, beforeEach, describe, expect, it } from 'vitest';
+
+import {
+    AppManifestVersion,
+    AppStoreListing,
+    Boost,
+    ConsentFlowContract,
+    Integration,
+    Profile,
+    SigningAuthority,
+} from '@models';
+
+import {
+    getBoostForListingByTemplateAlias,
+    getConsentContractForListingByScopeHash,
+} from '@accesslayer/app-store-listing/relationships/read';
+import { getProfileByProfileId } from '@accesslayer/profile/read';
+import { createSigningAuthority } from '@accesslayer/signing-authority/create';
+import { createUseSigningAuthorityRelationship } from '@accesslayer/signing-authority/relationships/create';
+import { getPrimarySigningAuthorityForListing } from '@accesslayer/signing-authority/relationships/read';
+
+import { computeConsentScopeHash } from '../src/helpers/consent-scopes.helpers';
+import { getUser } from './helpers/getClient';
+import { seedListedApp } from './helpers/app-store.helpers';
+
+import type { AppManifest } from '@learncard/types';
+
+let ownerUser: Awaited<ReturnType<typeof getUser>>;
+let otherUser: Awaited<ReturnType<typeof getUser>>;
+
+const seedProfile = async (user: Awaited<ReturnType<typeof getUser>>, profileId: string) => {
+    await user.clients.fullAuth.profile.createProfile({ profileId });
+};
+
+const makeManifest = (overrides: Partial<AppManifest> = {}): AppManifest => ({
+    manifestVersion: 1,
+    appUrl: 'https://partner.example.com',
+    suggestedName: 'Partner Example',
+    suggestedIconUrl: 'https://partner.example.com/icon.png',
+    permissions: ['send_credential'],
+    templates: [
+        {
+            alias: 'completion',
+            version: 1,
+            lastUsedAt: '2026-01-01T00:00:00.000Z',
+            template: {
+                name: 'Course Completion: {{courseName}}',
+                description: 'Awarded to {{learnerName}}',
+                category: 'Achievement',
+            },
+        },
+    ],
+    consentRequests: [
+        {
+            scopes: {
+                read: {
+                    credentialCategories: ['Achievement'],
+                    personalFields: ['email'],
+                },
+                write: {
+                    credentialCategories: ['Achievement'],
+                },
+            },
+            reason: 'Show progress',
+            lastUsedAt: '2026-01-01T00:00:00.000Z',
+        },
+    ],
+    featuresLaunched: ['/wallet'],
+    counterKeys: ['coins'],
+    usedLearnerContext: false,
+    usedNotifications: false,
+    firstCapturedAt: '2026-01-01T00:00:00.000Z',
+    lastUpdatedAt: '2026-01-01T00:00:00.000Z',
+    ...overrides,
+});
+
+describe('app manifest routes', () => {
+    beforeAll(async () => {
+        ownerUser = await getUser('a'.repeat(64));
+        otherUser = await getUser('b'.repeat(64));
+    });
+
+    beforeEach(async () => {
+        await AppManifestVersion.delete({ detach: true, where: {} });
+        await Boost.delete({ detach: true, where: {} });
+        await ConsentFlowContract.delete({ detach: true, where: {} });
+        await AppStoreListing.delete({ detach: true, where: {} });
+        await SigningAuthority.delete({ detach: true, where: {} });
+        await Integration.delete({ detach: true, where: {} });
+        await Profile.delete({ detach: true, where: {} });
+
+        await seedProfile(ownerUser, 'owner-user');
+        await seedProfile(otherUser, 'other-user');
+    });
+
+    afterAll(async () => {
+        await AppManifestVersion.delete({ detach: true, where: {} });
+        await Boost.delete({ detach: true, where: {} });
+        await ConsentFlowContract.delete({ detach: true, where: {} });
+        await AppStoreListing.delete({ detach: true, where: {} });
+        await SigningAuthority.delete({ detach: true, where: {} });
+        await Integration.delete({ detach: true, where: {} });
+        await Profile.delete({ detach: true, where: {} });
+    });
+
+    it('submits manifests idempotently and increments version on change', async () => {
+        const { integration } = await seedListedApp('owner-user');
+        const manifest = makeManifest();
+
+        const first = await ownerUser.clients.fullAuth.appStore.submitAppManifest({
+            integrationId: integration.id,
+            manifest,
+        });
+
+        expect(first).toMatchObject({ version: 1, noop: false, diff: null });
+
+        const second = await ownerUser.clients.fullAuth.appStore.submitAppManifest({
+            integrationId: integration.id,
+            manifest: {
+                ...manifest,
+                firstCapturedAt: '2026-02-01T00:00:00.000Z',
+                lastUpdatedAt: '2026-02-01T00:00:00.000Z',
+                templates: [{ ...manifest.templates[0]!, lastUsedAt: '2026-02-01T00:00:00.000Z' }],
+                consentRequests: [
+                    { ...manifest.consentRequests[0]!, lastUsedAt: '2026-02-01T00:00:00.000Z' },
+                ],
+            },
+        });
+
+        expect(second).toMatchObject({ version: 1, noop: true, diff: null });
+
+        const changed = await ownerUser.clients.fullAuth.appStore.submitAppManifest({
+            integrationId: integration.id,
+            manifest: makeManifest({ permissions: ['send_credential', 'request_consent'] }),
+        });
+
+        expect(changed.version).toBe(2);
+        expect(changed.noop).toBe(false);
+        expect(changed.diff).toBeNull();
+
+        const diff = await ownerUser.clients.fullAuth.appStore.getManifestDiff({
+            integrationId: integration.id,
+            fromVersion: 1,
+            toVersion: 2,
+        });
+
+        expect(diff.permissions.added).toEqual(['request_consent']);
+
+        const versions = await ownerUser.clients.fullAuth.appStore.getManifestVersions({
+            integrationId: integration.id,
+            limit: 10,
+        });
+
+        expect(versions.records.map(record => record.version)).toEqual([2, 1]);
+    });
+
+    it('treats a capture missing earlier features as unchanged, not removed', async () => {
+        const { integration, listing } = await seedListedApp('owner-user', {
+            app_listing_status: 'DRAFT',
+        });
+        const fuller = makeManifest({
+            permissions: ['send_credential', 'request_identity', 'launch_feature'],
+        });
+
+        const first = await ownerUser.clients.fullAuth.appStore.submitAppManifest({
+            integrationId: integration.id,
+            manifest: fuller,
+        });
+        await ownerUser.clients.fullAuth.appStore.applyManifestVersion({
+            integrationId: integration.id,
+            version: first.version,
+            listingId: listing.listing_id,
+        });
+
+        const partial = await ownerUser.clients.fullAuth.appStore.submitAppManifest({
+            integrationId: integration.id,
+            manifest: makeManifest({
+                permissions: ['send_credential'],
+                consentRequests: [],
+                featuresLaunched: [],
+                counterKeys: [],
+                lastUpdatedAt: '2026-03-01T00:00:00.000Z',
+            }),
+        });
+
+        expect(partial).toMatchObject({ version: first.version, noop: true });
+
+        const grown = await ownerUser.clients.fullAuth.appStore.submitAppManifest({
+            integrationId: integration.id,
+            manifest: makeManifest({
+                permissions: ['send_credential', 'send_notification'],
+                counterKeys: [],
+                lastUpdatedAt: '2026-03-02T00:00:00.000Z',
+            }),
+        });
+
+        expect(grown.diff?.permissions).toEqual({
+            added: ['send_notification'],
+            removed: [],
+            changed: [],
+        });
+        expect(grown.diff?.counterKeys.removed).toEqual([]);
+        expect(grown.diff?.featurePaths.removed).toEqual([]);
+    });
+
+    it('applies manifest reconciliation idempotently', async () => {
+        const { integration, listing } = await seedListedApp('owner-user', {
+            app_listing_status: 'DRAFT',
+        });
+        const signingAuthority = await createSigningAuthority('https://sa.example.com');
+        const ownerProfile = await getProfileByProfileId('owner-user');
+
+        if (!ownerProfile) {
+            throw new Error('Expected owner profile to exist');
+        }
+
+        await createUseSigningAuthorityRelationship(
+            ownerProfile,
+            signingAuthority,
+            'default',
+            'did:web:sa.example.com:issuer',
+            true
+        );
+
+        const manifest = makeManifest({ permissions: ['send_credential', 'request_consent'] });
+
+        const submitted = await ownerUser.clients.fullAuth.appStore.submitAppManifest({
+            integrationId: integration.id,
+            manifest,
+        });
+
+        const firstApply = await ownerUser.clients.fullAuth.appStore.applyManifestVersion({
+            integrationId: integration.id,
+            version: submitted.version,
+            listingId: listing.listing_id,
+        });
+
+        expect(firstApply).toMatchObject({
+            applied: true,
+            version: 1,
+            reconciled: {
+                templatesUpserted: 1,
+                templatesSkipped: 0,
+                contractsUpserted: 1,
+                contractsSkipped: 0,
+                signingAuthorityEnsured: true,
+            },
+        });
+
+        const boost = await getBoostForListingByTemplateAlias(
+            listing.listing_id,
+            'completion',
+            'localhost%3A3000'
+        );
+        expect(boost?.boost).toBeTruthy();
+
+        const scopeHash = computeConsentScopeHash(manifest.consentRequests[0]!.scopes);
+        const contract = await getConsentContractForListingByScopeHash(
+            listing.listing_id,
+            scopeHash
+        );
+        expect(contract?.id).toBeTruthy();
+
+        const listingSigningAuthority = await getPrimarySigningAuthorityForListing(listing);
+        expect(listingSigningAuthority?.signingAuthority.endpoint).toBe('https://sa.example.com');
+
+        const secondApply = await ownerUser.clients.fullAuth.appStore.applyManifestVersion({
+            integrationId: integration.id,
+            version: submitted.version,
+            listingId: listing.listing_id,
+        });
+
+        expect(secondApply).toMatchObject({
+            applied: true,
+            version: 1,
+            reconciled: {
+                templatesUpserted: 0,
+                templatesSkipped: 1,
+                contractsUpserted: 0,
+                contractsSkipped: 1,
+                signingAuthorityEnsured: true,
+            },
+        });
+
+        const fetchedVersion = await ownerUser.clients.fullAuth.appStore.getManifestVersion({
+            integrationId: integration.id,
+            version: 1,
+        });
+        expect(fetchedVersion.status).toBe('active');
+        expect(fetchedVersion.manifest.permissions).toEqual(['send_credential', 'request_consent']);
+
+        const diff = await ownerUser.clients.fullAuth.appStore.getManifestDiff({
+            integrationId: integration.id,
+            fromVersion: 1,
+            toVersion: 1,
+        });
+        expect(diff.requiresReview).toBe(false);
+    });
+});