@learncard/network-brain-service 3.19.1 → 4.0.0

package/src/routes/inbox.ts

@@ -768,8 +768,10 @@ export const inboxRouter = t.router({
                 claimed: z.number(),
                 errors: z.number(),
                 guardianPending: z.number(),
-                verifiableCredentials: z.array(VCValidator),
-                deliveries: z.array(z.object({ id: z.string(), credential: VCValidator })),
+                verifiableCredentials: z.array(VCValidator.or(JWEValidator)),
+                deliveries: z.array(
+                    z.object({ id: z.string(), credential: VCValidator.or(JWEValidator) })
+                ),
             })
         )
         .mutation(async ({ ctx }) => {

package/src/routes/index.ts

@@ -23,6 +23,7 @@ import {
 } from '@accesslayer/profile/relationships/read';
 import { getDidWeb } from '@helpers/did.helpers';
 import { getEmptyLearnCard, isServersDidWebDID } from '@helpers/learnCard.helpers';
+import { isServiceProfileExemptFromGuardianship } from '@helpers/profile.helpers';
 import { invalidateChallengeForDid, isChallengeValidForDid } from '@cache/challenges';
 import { ProfileType } from 'types/profile';
 import { getProfileManagerById } from '@accesslayer/profile-manager/read';
@@ -555,7 +556,9 @@ export const guardianGatedRoute = profileRoute.use(async ({ ctx, next }) => {
     const { profile } = ctx.user;
     const guardianApprovalToken = ctx._guardianApprovalToken;
     // Service profiles (orgs) are managed for admin purposes, not guardianship.
-    const isChildAccount = !profile.isServiceProfile && (await isProfileManaged(profile.profileId));
+    const isChildAccount =
+        !isServiceProfileExemptFromGuardianship(profile.isServiceProfile, profile.type) &&
+        (await isProfileManaged(profile.profileId));
     let guardianIdentity: { profileId: string; did: string } | undefined;
 
     if (isChildAccount && guardianApprovalToken) {

package/src/routes/profile-manager.ts

@@ -29,6 +29,7 @@ import {
 import { getProfilesThatManageAProfile } from '@accesslayer/profile/relationships/read';
 import { updateProfileManager } from '@accesslayer/profile-manager/update';
 import { getProfileManagerById } from '@accesslayer/profile-manager/read';
+import { ProfileManager } from '@models';
 
 export const profileManagersRouter = t.router({
     createProfileManager: profileRoute
@@ -126,6 +127,24 @@ export const profileManagersRouter = t.router({
         )
         .output(z.string())
         .mutation(async ({ input, ctx }) => {
+            // Org onboarding also uses this API. Only the persisted Family parent
+            // (or an explicit child type), not a client service flag, defines a child path.
+            if (input.isServiceProfile) {
+                const parents = await ProfileManager.findRelationships({
+                    alias: 'childOf',
+                    where: { source: { id: ctx.user.manager.id } },
+                });
+                if (
+                    input.type === 'child' ||
+                    parents.some(({ target }) => target.category === 'Family')
+                ) {
+                    throw new TRPCError({
+                        code: 'BAD_REQUEST',
+                        message: 'Child profiles cannot be service profiles.',
+                    });
+                }
+            }
+
             const profileExists = await checkIfProfileExists(input);
 
             if (profileExists) {

package/src/routes/profiles.ts

@@ -574,6 +574,18 @@ export const profilesRouter = t.router({
         .output(z.boolean())
         .mutation(async ({ input, ctx }) => {
             const { profile } = ctx.user;
+            if (
+                profile.isServiceProfile === true &&
+                profile.type === 'child' &&
+                typeof input.type === 'string' &&
+                input.type !== 'child'
+            ) {
+                throw new TRPCError({
+                    code: 'BAD_REQUEST',
+                    message:
+                        'A service profile explicitly typed as a child cannot change profile type.',
+                });
+            }
 
             const {
                 profileId,

package/src/routes/public-share-links.ts

@@ -10,6 +10,9 @@ import {
     ShareEnvelopeValidator,
     ShareLinkPublicContentViewValidator,
     ShareLinkPublicStateValidator,
+    GetShareLinkAttachmentChunkInputValidator,
+    ShareLinkAttachmentChunkOutputValidator,
+    ShareLinkAttachmentChunkEnvelopeValidator,
 } from '@learncard/types';
 import { LCNNotificationTypeEnumValidator } from '@learncard/types';
 
@@ -32,6 +35,11 @@ import type {
     ShareViewEligibilitySource,
 } from '@accesslayer/share-link';
 import type { ShareLinkRecord } from '../models/ShareLink';
+import { shareAttachmentTuple } from '@accesslayer/share-link/attachment';
+import {
+    mintShareAttachmentAccessToken,
+    verifyShareAttachmentAccessToken,
+} from '@helpers/share-link-attachment-access';
 
 /**
  * LC-2187 public (anonymous) share-link API: resolve, guarded content and
@@ -67,6 +75,11 @@ export type PublicShareLinkRouterDependencies = {
         }) => Promise<
             { ok: true; value: ShareContentContentProjection } | { ok: false; error: string }
         >;
+        fetchAttachmentChunk?: (
+            input: import('@helpers/share-content-client/types').ShareContentTuple
+        ) => Promise<
+            { ok: true; value: ShareContentContentProjection } | { ok: false; error: string }
+        >;
     };
     readonly receipts: {
         persist: (input: PersistShareViewReceiptInput) => Promise<boolean>;
@@ -219,6 +232,161 @@ export const createPublicShareLinksRouter = (
     };
 
     return t.router({
+        attachmentChunk: openRouteWithoutInputCapture
+            .meta({
+                openapi: openapi(
+                    'POST',
+                    '/public/share-links/attachment-chunk',
+                    'Fetch guarded encrypted attachment chunk'
+                ),
+            })
+            .input(GetShareLinkAttachmentChunkInputValidator)
+            .output(ShareLinkAttachmentChunkOutputValidator)
+            .mutation(async ({ ctx, input }) => {
+                const dependencies = await resolve();
+                if (!dependencies.repository.fetchAttachmentChunk) notFound();
+                try {
+                    await dependencies.enforceRateLimit({
+                        key: rateLimitKey('attachment', dependencies.namespace, ctx.sourceIp),
+                        limit: 240,
+                        windowSeconds: 60,
+                        description: 'public share-link attachment',
+                    });
+                } catch (error) {
+                    if (error instanceof TRPCError && error.code === 'TOO_MANY_REQUESTS')
+                        throw new TRPCError({
+                            code: 'TOO_MANY_REQUESTS',
+                            message: 'try again later',
+                        });
+                    throw new TRPCError({
+                        code: 'SERVICE_UNAVAILABLE',
+                        message: 'share-link content is unavailable',
+                    });
+                }
+                const read = async (): Promise<ShareLinkRecord> => {
+                    let record: ShareLinkRecord | null;
+                    try {
+                        record = await dependencies.repository.getShareLink({
+                            shareId: input.id,
+                            namespace: dependencies.namespace,
+                        });
+                    } catch {
+                        throw new TRPCError({
+                            code: 'SERVICE_UNAVAILABLE',
+                            message: 'share-link content is unavailable',
+                        });
+                    }
+                    const state = classifyPublicShare(record, dependencies.now());
+                    if (
+                        state.state !== 'active' ||
+                        state.record.namespace !== dependencies.namespace ||
+                        state.record.contentVersion !== input.contentVersion ||
+                        state.record.attachmentId !== input.attachmentId ||
+                        !state.record.attachmentChunkCount ||
+                        input.chunkIndex >= state.record.attachmentChunkCount
+                    )
+                        notFound();
+                    return state.record;
+                };
+                const first = await read();
+                const grantAccepted =
+                    input.accessToken &&
+                    verifyShareAttachmentAccessToken(
+                        input.accessToken,
+                        first,
+                        dependencies.namespace,
+                        ctx.sourceIp,
+                        dependencies.now()
+                    );
+                const access = grantAccepted
+                    ? 'accepted'
+                    : await passcodeAccepted(first, input.passcode, dependencies, ctx.sourceIp);
+                if (access === 'try_later')
+                    throw new TRPCError({ code: 'TOO_MANY_REQUESTS', message: 'try again later' });
+                if (access !== 'accepted')
+                    throw new TRPCError({
+                        code: 'UNAUTHORIZED',
+                        message: 'share-link passcode required',
+                    });
+                const tuple = shareAttachmentTuple(
+                    {
+                        namespace: dependencies.namespace,
+                        ownerProfileId: first.ownerProfileId,
+                        shareId: first.id,
+                        contentVersion: first.contentVersion,
+                        attachmentId: input.attachmentId,
+                        chunkCount: first.attachmentChunkCount!,
+                    },
+                    input.chunkIndex
+                );
+                let fetched;
+                try {
+                    fetched = await dependencies.repository.fetchAttachmentChunk(tuple);
+                } catch {
+                    throw new TRPCError({
+                        code: 'SERVICE_UNAVAILABLE',
+                        message: 'share-link content is unavailable',
+                    });
+                }
+                if (!fetched.ok) {
+                    if (fetched.error === 'NOT_FOUND' || fetched.error === 'CONFLICT') notFound();
+                    throw new TRPCError({
+                        code: 'SERVICE_UNAVAILABLE',
+                        message: 'share-link content is unavailable',
+                    });
+                }
+                if (
+                    Object.entries(tuple).some(
+                        ([key, value]) => fetched.value[key as keyof typeof fetched.value] !== value
+                    )
+                )
+                    notFound();
+                const final = await read();
+                if (
+                    final.version !== first.version ||
+                    final.ownerProfileId !== first.ownerProfileId ||
+                    final.activeObjectRef !== first.activeObjectRef ||
+                    final.passcodeHash !== first.passcodeHash
+                )
+                    notFound();
+                if (
+                    grantAccepted &&
+                    !verifyShareAttachmentAccessToken(
+                        input.accessToken!,
+                        final,
+                        dependencies.namespace,
+                        ctx.sourceIp,
+                        dependencies.now()
+                    )
+                ) {
+                    throw new TRPCError({
+                        code: 'UNAUTHORIZED',
+                        message: 'share-link passcode required',
+                    });
+                }
+                const envelope = ShareLinkAttachmentChunkEnvelopeValidator.safeParse(
+                    fetched.value.envelope
+                );
+                if (!envelope.success) notFound();
+                return {
+                    id: input.id,
+                    contentVersion: input.contentVersion,
+                    attachmentId: input.attachmentId,
+                    chunkIndex: input.chunkIndex,
+                    envelope: envelope.data,
+                    ...(final.passcodeHash
+                        ? {
+                              // Renew only after the chunk and its current policy pass every check.
+                              accessToken: mintShareAttachmentAccessToken(
+                                  final,
+                                  dependencies.namespace,
+                                  ctx.sourceIp,
+                                  dependencies.now()
+                              ),
+                          }
+                        : {}),
+                };
+            }),
         resolve: openRouteWithoutInputCapture
             .meta({
                 openapi: openapi('POST', PUBLIC_RESOLVE_PATH, 'Resolve public share metadata'),
@@ -735,6 +903,7 @@ const buildProductionDependencies = async (
     return {
         namespace: config.namespace,
         repository: {
+            fetchAttachmentChunk: input => client.get(input),
             getShareLink: input => getShareLink(input),
             fetchContent: async input => {
                 const result = await coordinator.fetchShareContent(input.shareId, {

package/src/routes/share-links.ts

@@ -11,6 +11,10 @@ import {
     ShareLinkOperationKeyInputValidator,
     ShareOwnerRecoveryValidator,
     UpdateShareLinkInputValidator,
+    PutShareLinkAttachmentChunkInputValidator,
+    PutShareLinkAttachmentChunkOutputValidator,
+    DeleteShareLinkAttachmentChunksInputValidator,
+    DeleteShareLinkAttachmentChunksOutputValidator,
 } from '@learncard/types';
 
 import { t, profileRouteWithoutInputCapture } from '@routes';
@@ -37,6 +41,7 @@ import type {
     ShareLinkCoordinatorErrorCode,
 } from '@helpers/share-link-coordinator';
 import { decodeShareLinkListCursor } from '@accesslayer/share-link/list';
+import type { ShareLinkAttachmentOwnerApi } from '@helpers/share-link-attachment';
 import type {
     ListShareLinksInput,
     ListShareLinksResult,
@@ -57,6 +62,8 @@ export type ShareLinkRouterDependencies = {
     readonly namespace: string;
     readonly coordinator: ShareLinkCoordinator;
     readonly recovery: RecoveryRunnerDependencies;
+    readonly attachments?: ShareLinkAttachmentOwnerApi;
+    readonly enforceAttachmentWriteRateLimit?: (ownerProfileId: string) => Promise<void>;
     /**
      * Bounded, namespace+owner-scoped keyset listing over the immutable
      * `(createdAt, id)` key. Receives only trusted scope; the route decodes and
@@ -206,6 +213,56 @@ export const createShareLinksRouter = (
     };
 
     return t.router({
+        putAttachmentChunk: profileRouteWithoutInputCapture
+            .meta({
+                openapi: openapi(
+                    'POST',
+                    '/share-links/attachment-chunk/put',
+                    'Stage encrypted share attachment chunk'
+                ),
+                requiredScope: AUTH_GRANT_SHARE_LINKS_WRITE_SCOPE,
+            })
+            .input(PutShareLinkAttachmentChunkInputValidator)
+            .output(PutShareLinkAttachmentChunkOutputValidator)
+            .mutation(async ({ ctx, input }) => {
+                const dependencies = await resolve();
+                if (!dependencies.attachments) notFound();
+                await (
+                    dependencies.enforceAttachmentWriteRateLimit ??
+                    dependencies.enforceOwnerWriteRateLimit
+                )(ctx.user.profile.profileId);
+                return runCoordinated(() =>
+                    dependencies.attachments!.put(input, {
+                        namespace: dependencies.namespace,
+                        ownerProfileId: ctx.user.profile.profileId,
+                    })
+                );
+            }),
+        deleteAttachmentChunks: profileRouteWithoutInputCapture
+            .meta({
+                openapi: openapi(
+                    'POST',
+                    '/share-links/attachment-chunks/delete',
+                    'Delete unreferenced encrypted attachment'
+                ),
+                requiredScope: AUTH_GRANT_SHARE_LINKS_WRITE_SCOPE,
+            })
+            .input(DeleteShareLinkAttachmentChunksInputValidator)
+            .output(DeleteShareLinkAttachmentChunksOutputValidator)
+            .mutation(async ({ ctx, input }) => {
+                const dependencies = await resolve();
+                if (!dependencies.attachments) notFound();
+                await (
+                    dependencies.enforceAttachmentWriteRateLimit ??
+                    dependencies.enforceOwnerWriteRateLimit
+                )(ctx.user.profile.profileId);
+                return runCoordinated(() =>
+                    dependencies.attachments!.delete(input, {
+                        namespace: dependencies.namespace,
+                        ownerProfileId: ctx.user.profile.profileId,
+                    })
+                );
+            }),
         create: profileRouteWithoutInputCapture
             .meta({
                 openapi: openapi('POST', '/share-links/create', 'Create an owner share link'),
@@ -629,6 +686,18 @@ const buildProductionDependencies = async (
         namespace: config.namespace,
         coordinator,
         recovery,
+        attachments: (
+            await import('@helpers/share-link-attachment')
+        ).createShareLinkAttachmentOwnerApi(client),
+        enforceAttachmentWriteRateLimit: ownerProfileId =>
+            enforceRateLimits([
+                {
+                    key: `share-link-attachment-write:${config.namespace}:${ownerProfileId}`,
+                    limit: 120,
+                    windowSeconds: 60 * 60,
+                    description: 'owner share-link attachment writes',
+                },
+            ]),
         listShareLinks: listRepository.listShareLinks,
         enforceOwnerWriteRateLimit: ownerProfileId =>
             enforceOwnerShareWriteRateLimit(config.namespace, ownerProfileId),

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/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;