@learncard/network-brain-service 3.17.0 → 3.19.0

package/src/accesslayer/consentflowcontract/relationships/read.ts

@@ -15,9 +15,11 @@ import {
 } from '@models';
 import {
     DbTermsType,
+    DbTermsValidator,
     FlatDbTermsType,
     DbContractType,
     FlatDbContractType,
+    DbContractValidator,
     FlatDbTransactionType,
     DbTransactionType,
 } from 'types/consentflowcontract';
@@ -32,6 +34,7 @@ import {
     HolderExportMetadata,
     LCNProfile,
 } from '@learncard/types';
+import { ConsentFlowGuardianApprovalValidator } from '@learncard/types';
 import { FlatBoostType } from 'types/boost';
 import { constructUri, getIdFromUri } from '@helpers/uri.helpers';
 import { flattenObject, inflateObject } from '@helpers/objects.helpers';
@@ -40,6 +43,8 @@ import { ProfileType } from 'types/profile';
 import { CredentialType } from 'types/credential';
 import { getBoostUri } from '@helpers/boost.helpers';
 import { getCredentialUri } from '@helpers/credential.helpers';
+import { getProfilesThatManageAProfile } from '@accesslayer/profile/relationships/read';
+import { getDidWeb } from '@helpers/did.helpers';
 
 export const isProfileConsentFlowContractAdmin = async (
     profile: ProfileType,
@@ -80,6 +85,25 @@ export const hasProfileConsentedToContract = async (
     return Number(result.records[0]?.get('count') ?? 0) > 0;
 };
 
+export const hasGuardianApprovalHistory = async (terms: DbTermsType): Promise<boolean> => {
+    if (terms.guardianApproval) return true;
+
+    const result = await new QueryBuilder()
+        .match({
+            related: [
+                { identifier: 'transaction', model: ConsentFlowTransaction },
+                ConsentFlowTransaction.getRelationshipByAlias('isFor'),
+                { model: ConsentFlowTerms, where: { id: terms.id } },
+            ],
+        })
+        .where('transaction.`guardianApproval.guardianProfileId` IS NOT NULL')
+        .return('transaction.id')
+        .limit(1)
+        .run();
+
+    return result.records.length > 0;
+};
+
 export const getContractDetailsById = async (
     id: string
 ): Promise<{ contractOwner: LCNProfile; contract: DbContractType } | null> => {
@@ -135,7 +159,7 @@ export const getContractTermsForProfile = async (
             .run()
     );
 
-    return result.length > 0 ? inflateObject<DbTermsType>(result[0]!.terms) : null;
+    return result.length > 0 ? DbTermsValidator.parse(inflateObject(result[0]!.terms)) : null;
 };
 
 export const getContractTermsById = async (
@@ -516,6 +540,13 @@ all(key IN keys($params) WHERE
     }));
 };
 
+// Empty expiry values historically mean no expiry. Invalid nonempty values never authorize access.
+const isConsentExpiryActive = (expiresAt: string | undefined, now: number): boolean => {
+    if (!expiresAt?.trim()) return true;
+    const expiry = Date.parse(expiresAt);
+    return Number.isFinite(expiry) && expiry > now;
+};
+
 export const getConsentedDataBetweenProfiles = async (
     ownerProfileId: string,
     consenterProfileId: string,
@@ -530,29 +561,40 @@ export const getConsentedDataBetweenProfiles = async (
     const convertedContractQuery = id ? convertObjectRegExpToNeo4j({ id }) : {};
     const { whereClause: contractWhereClause, params: contractQueryParams } =
         buildWhereForQueryBuilder('contract', convertedContractQuery as any);
-
-    const _dbQuery = new QueryBuilder(
-        new BindParam({
-            params: flattenObject({ terms: flattenObject(convertDataQueryToNeo4jQuery(params)) }),
-            cursor,
-            ...contractQueryParams,
-        })
-    ).match({
-        related: [
-            { model: Profile, where: { profileId: consenterProfileId } },
-            ConsentFlowTerms.getRelationshipByAlias('createdBy'),
-            { identifier: 'terms', model: ConsentFlowTerms },
-            ConsentFlowTerms.getRelationshipByAlias('consentsTo'),
-            { model: ConsentFlowContract, identifier: 'contract' },
-            ConsentFlowContract.getRelationshipByAlias('createdBy'),
-            { model: Profile, where: { profileId: ownerProfileId } },
-        ],
-        // The following is custom Cypher logic that has the following behavior:
-        // If query key is true, ensure all resulting terms have that key
-        // If query key is false, ensure no resulting terms have that key
-        // If query key is not present, return all terms whether they have it or not
-    }).where(`
-all(key IN keys($params) WHERE 
+    const now = Date.now();
+    const managers = await getProfilesThatManageAProfile(consenterProfileId);
+    const records: ConsentFlowContractDataForDid[] = [];
+    const batchSize = Math.max(limit, 50);
+    let offset = 0;
+
+    // Filter dates after parsing, but fetch bounded batches so invalid or expired grants
+    // cannot truncate an otherwise full page or require loading every grant at once.
+    while (records.length < limit) {
+        const _dbQuery = new QueryBuilder(
+            new BindParam({
+                params: flattenObject({
+                    terms: flattenObject(convertDataQueryToNeo4jQuery(params)),
+                }),
+                cursor,
+                ...contractQueryParams,
+            })
+        ).match({
+            related: [
+                { model: Profile, where: { profileId: consenterProfileId } },
+                ConsentFlowTerms.getRelationshipByAlias('createdBy'),
+                { identifier: 'terms', model: ConsentFlowTerms },
+                ConsentFlowTerms.getRelationshipByAlias('consentsTo'),
+                { model: ConsentFlowContract, identifier: 'contract' },
+                ConsentFlowContract.getRelationshipByAlias('createdBy'),
+                { model: Profile, where: { profileId: ownerProfileId } },
+            ],
+            // The following is custom Cypher logic that has the following behavior:
+            // If query key is true, ensure all resulting terms have that key
+            // If query key is false, ensure no resulting terms have that key
+            // If query key is not present, return all terms whether they have it or not
+        }).where(`
+(terms.status = 'live' OR (terms.status = 'stale' AND terms.oneTime = true))
+AND all(key IN keys($params) WHERE
     CASE $params[key]
         WHEN true THEN terms[key] IS NOT NULL AND terms[key] <> []
         WHEN false THEN terms[key] IS NULL OR terms[key] = []
@@ -561,47 +603,103 @@ all(key IN keys($params) WHERE
 AND ${contractWhereClause}
 `);
 
-    const dbQuery = cursor ? _dbQuery.raw(' AND terms.updatedAt < $cursor') : _dbQuery;
-
-    const results = convertQueryResultToPropertiesObjectArray<{
-        terms: FlatDbTermsType;
-        contract: FlatDbContractType;
-    }>(
-        await dbQuery
-            .return('DISTINCT terms, contract')
-            .orderBy('terms.updatedAt DESC')
-            .limit(limit)
-            .run()
-    );
+        const dbQuery = _dbQuery.match({
+            optional: true,
+            related: [
+                { identifier: 'transaction', model: ConsentFlowTransaction },
+                ConsentFlowTransaction.getRelationshipByAlias('isFor'),
+                { identifier: 'terms' },
+            ],
+        }).with(`terms, contract,
+            coalesce(terms.createdAt, min(CASE WHEN transaction.action = 'consent' THEN transaction.date END)) AS createdAt,
+            coalesce(terms.updatedAt, max(transaction.date), terms.createdAt) AS date,
+            count(transaction.\`guardianApproval.guardianProfileId\`) > 0 AS hadGuardianApproval`);
+
+        if (cursor) dbQuery.where('date < $cursor');
+
+        const results = convertQueryResultToPropertiesObjectArray<{
+            terms: FlatDbTermsType;
+            contract: FlatDbContractType;
+            createdAt: string | null;
+            date: string;
+            hadGuardianApproval: boolean;
+        }>(
+            await dbQuery
+                .return('terms, contract, createdAt, date, hadGuardianApproval')
+                .orderBy('date DESC, terms.id ASC')
+                .skip(offset)
+                .limit(batchSize)
+                .run()
+        );
+
+        for (const result of results) {
+            const parsedTerm = DbTermsValidator.safeParse(inflateObject(result.terms));
+            const parsedContract = DbContractValidator.safeParse(inflateObject(result.contract));
+            if (!parsedTerm.success || !parsedContract.success) {
+                // Never log stored consent data, identifiers, or raw validation errors.
+                console.warn('consented_data: invalid_stored_grant');
+                continue;
+            }
+            const term = parsedTerm.data;
+            const contract = parsedContract.data;
+            if (
+                !isConsentExpiryActive(term.expiresAt, now) ||
+                !isConsentExpiryActive(contract.expiresAt, now)
+            )
+                continue;
+
+            const parsedApproval = ConsentFlowGuardianApprovalValidator.safeParse(
+                term.guardianApproval
+            );
+            const approval = parsedApproval.success ? parsedApproval.data : undefined;
+            const required =
+                managers.length > 0 || !!term.guardianApproval || result.hadGuardianApproval;
+            const approved =
+                !!approval &&
+                approval.contractUpdatedAt === contract.updatedAt &&
+                managers.some(
+                    manager =>
+                        manager.profileId === approval.guardianProfileId &&
+                        (manager.did === approval.guardianDid ||
+                            getDidWeb(domain, manager.profileId) === approval.guardianDid)
+                );
 
-    const inflatedResults = results.map(result => ({
-        term: inflateObject<any>(result.terms) as DbTermsType,
-        contract: inflateObject<any>(result.contract) as DbContractType,
-    }));
+            records.push({
+                date: result.date,
+                ...(result.createdAt ? { createdAt: result.createdAt } : {}),
+                contractUpdatedAt: contract.updatedAt,
+                ...(contract.expiresAt?.trim() ? { contractExpiresAt: contract.expiresAt } : {}),
+                ...(contract.reasonForAccessing !== undefined
+                    ? { reasonForAccessing: contract.reasonForAccessing }
+                    : {}),
+                guardian: { required, approved, ...(approval ? { approval } : {}) },
+                contractUri: constructUri('contract', contract.id, domain),
+                termsUri: constructUri('terms', term.id, domain),
+                status: term.status,
+                ...(term.expiresAt?.trim() ? { expiresAt: term.expiresAt } : {}),
+                terms: term.terms,
+                credentials: Object.entries(term.terms.read.credentials.categories).flatMap(
+                    ([category, { shared, sharing, shareUntil }]) => {
+                        if (
+                            term.terms.read.credentials.sharing === false ||
+                            !sharing ||
+                            !isConsentExpiryActive(shareUntil, now) ||
+                            !shouldIncludeCategory(params.credentials?.categories, category)
+                        )
+                            return [];
+
+                        return shared?.map(uri => ({ category, uri })) ?? [];
+                    }
+                ),
+                personal: term.terms.read.personal,
+            });
+            if (records.length >= limit) return records;
+        }
+        if (results.length < batchSize) break;
+        offset += batchSize;
+    }
 
-    return inflatedResults.map(({ term, contract }) => ({
-        date: term.updatedAt!,
-        contractUri: constructUri('contract', contract.id, domain),
-        credentials: Object.entries(term.terms.read.credentials.categories)
-            .flatMap(([category, { shared, sharing, shareUntil }]) => {
-                if (
-                    !sharing ||
-                    (shareUntil && new Date(shareUntil) < new Date()) ||
-                    !shouldIncludeCategory(params.credentials?.categories, category)
-                ) {
-                    return false as any as { category: string; uri: string };
-                }
-
-                return (
-                    shared?.map(uri => ({
-                        category: category,
-                        uri,
-                    })) ?? []
-                );
-            })
-            .filter(Boolean),
-        personal: term.terms.read.personal,
-    }));
+    return records;
 };
 
 export const getTransactionsForTerms = async (

package/src/accesslayer/consentflowcontract/relationships/update.ts

@@ -3,6 +3,7 @@ import { v4 as uuid } from 'uuid';
 import {
     ConsentFlowTerms as ConsentFlowTermsType,
     ConsentFlowTransaction as ConsentFlowTransactionType,
+    ConsentFlowGuardianApproval,
     LCNNotificationTypeEnumValidator,
     LCNProfile,
     VC,
@@ -34,10 +35,12 @@ export const reconsentTerms = async (
         terms,
         expiresAt,
         oneTime,
+        guardianApproval,
     }: {
         terms: ConsentFlowTermsType;
         expiresAt?: string;
         oneTime?: boolean;
+        guardianApproval?: ConsentFlowGuardianApproval;
     },
     domain: string
 ): Promise<boolean> => {
@@ -49,15 +52,27 @@ export const reconsentTerms = async (
         ...(typeof oneTime === 'boolean' ? { oneTime } : {}),
     } as const satisfies ConsentFlowTransactionType;
 
+    const existingFlat = flattenObject({
+        terms: relationship.terms.terms,
+        guardianApproval: relationship.terms.guardianApproval,
+    });
+    const newFlat = flattenObject({ terms, ...(guardianApproval ? { guardianApproval } : {}) });
+    const removedProperties = Object.fromEntries(
+        Object.keys(existingFlat)
+            .filter(key => !(key in newFlat))
+            .map(key => [key, null])
+    );
+
     const result = await new QueryBuilder(
         new BindParam({
-            params: flattenObject({
-                terms,
-                updatedAt: new Date().toISOString(),
+            params: {
+                ...newFlat,
+                ...removedProperties,
+                updatedAt: transaction.date,
                 status: oneTime ? 'stale' : 'live',
                 ...(typeof expiresAt === 'string' ? { expiresAt } : {}),
                 ...(typeof oneTime === 'boolean' ? { oneTime } : {}),
-            }),
+            },
         })
     )
         .match({
@@ -167,7 +182,10 @@ export const reconsentTerms = async (
                         boostCredential,
                         contractOwnerSigningAuthority,
                         domain,
-                        false
+                        true,
+                        undefined,
+                        true,
+                        [getDidWeb(domain, relationship.contractOwner.profileId)]
                     );
 
                     // Create transaction to record the boost issuance
@@ -244,7 +262,13 @@ export const updateTerms = async (
         terms,
         expiresAt,
         oneTime,
-    }: { terms: ConsentFlowTermsType; expiresAt?: string; oneTime?: boolean },
+        guardianApproval,
+    }: {
+        terms: ConsentFlowTermsType;
+        expiresAt?: string;
+        oneTime?: boolean;
+        guardianApproval?: ConsentFlowGuardianApproval;
+    },
     domain: string
 ): Promise<boolean> => {
     const transaction = {
@@ -260,8 +284,14 @@ export const updateTerms = async (
     /* -------------------------------------------------------------------------- */
 
     // 1. Flatten both the existing stored terms and the new terms we are saving
-    const existingFlat = flattenObject({ terms: relationship.terms.terms });
-    const newFlatInner = flattenObject({ terms });
+    const existingFlat = flattenObject({
+        terms: relationship.terms.terms,
+        guardianApproval: relationship.terms.guardianApproval,
+    });
+    const newFlatInner = flattenObject({
+        terms,
+        ...(guardianApproval ? { guardianApproval } : {}),
+    });
 
     // 2. Determine keys that are present in the existing node but NOT in the new update
     const keysToRemove = Object.keys(existingFlat).filter(key => !(key in newFlatInner));
@@ -269,7 +299,7 @@ export const updateTerms = async (
     // 3. Build a params object: keys for new/updated properties + keys to delete (set to null)
     const paramsForSet = {
         ...newFlatInner,
-        updatedAt: new Date().toISOString(),
+        updatedAt: transaction.date,
         status: oneTime ? 'stale' : 'live',
         ...(typeof expiresAt === 'string' ? { expiresAt } : {}),
         ...(typeof oneTime === 'boolean' ? { oneTime } : {}),
@@ -382,7 +412,10 @@ export const updateTerms = async (
                         boostCredential,
                         contractOwnerSigningAuthority,
                         domain,
-                        false
+                        true,
+                        undefined,
+                        true,
+                        [getDidWeb(domain, relationship.contractOwner.profileId)]
                     );
 
                     // Create transaction to record the boost issuance

package/src/accesslayer/credential/create.test.ts

@@ -0,0 +1,141 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import type { JWE, VC } from '@learncard/types';
+import type { IssuedCredential } from '../../types/credential';
+
+const mocks = vi.hoisted(() => ({ createOne: vi.fn(async input => input) }));
+vi.mock('@models', () => ({ Credential: { createOne: mocks.createOne } }));
+
+import { storeCredential } from './create';
+
+const statusEntry = {
+    id: 'https://network.example/status/1#42',
+    type: 'BitstringStatusListEntry' as const,
+    statusPurpose: 'revocation' as const,
+    statusListIndex: '42',
+    statusListCredential: 'https://network.example/status/1',
+};
+const createJwe = (): JWE => ({
+    protected: 'header',
+    iv: 'iv',
+    ciphertext: 'ciphertext',
+    tag: 'tag',
+    recipients: [],
+});
+const createVc = (): VC => ({
+    '@context': ['https://www.w3.org/2018/credentials/v1'],
+    type: ['VerifiableCredential'],
+    issuer: 'did:example:issuer',
+    issuanceDate: '2026-01-01T00:00:00Z',
+    credentialSubject: { id: 'did:example:subject' },
+    proof: {
+        type: 'Ed25519Signature2020',
+        created: '2026-01-01T00:00:00Z',
+        proofPurpose: 'assertionMethod',
+        verificationMethod: 'did:example:issuer#key-1',
+        proofValue: 'existing-signature',
+    },
+});
+
+describe('credential status storage', () => {
+    beforeEach(() => {
+        vi.restoreAllMocks();
+        vi.clearAllMocks();
+    });
+
+    it('persists public status coordinates after serializing an issuance result', async () => {
+        const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+        const jwe = createJwe();
+        const issued: IssuedCredential = {
+            kind: 'issued-credential',
+            credential: jwe,
+            statusEntries: [statusEntry],
+        };
+        await storeCredential(JSON.parse(JSON.stringify(issued)));
+        expect(mocks.createOne).toHaveBeenCalledWith(
+            expect.objectContaining({
+                credential: JSON.stringify(jwe),
+                statusEntries: JSON.stringify([statusEntry]),
+            })
+        );
+        expect(warn).not.toHaveBeenCalled();
+    });
+
+    it('warns when a client-encrypted JWE has no metadata, without logging its payload', async () => {
+        const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+        const original = createJwe();
+        const jwe = { ...original };
+        await storeCredential(jwe);
+        expect(warn).toHaveBeenCalledExactlyOnceWith(
+            expect.stringContaining('Encrypted credential has no status metadata'),
+            { credentialId: expect.any(String) }
+        );
+        expect(mocks.createOne.mock.calls[0]![0].statusEntries).toBeUndefined();
+        expect(mocks.createOne.mock.calls[0]![0].credential).toBe(JSON.stringify(jwe));
+    });
+
+    it('rejects internal issuance results that lost their status metadata before writing', async () => {
+        const issued = { kind: 'issued-credential', credential: createJwe() } as IssuedCredential;
+        await expect(storeCredential(issued)).rejects.toThrow();
+        expect(mocks.createOne).not.toHaveBeenCalled();
+    });
+
+    it.each([undefined, []])(
+        'warns for a pre-signed plaintext VC with missing or empty status (%j) and preserves its signature',
+        async credentialStatus => {
+            const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+            const credential = { ...createVc(), credentialStatus };
+            const stored = await storeCredential(credential);
+            expect(warn).toHaveBeenCalledExactlyOnceWith(
+                expect.stringContaining('Plaintext credential has no status metadata'),
+                { credentialId: stored.id }
+            );
+            expect(stored.credential).toBe(JSON.stringify(credential));
+            expect(stored.statusEntries).toBeUndefined();
+        }
+    );
+
+    it.each([statusEntry, [statusEntry]])(
+        'does not warn for a plaintext VC with embedded status entries (%j)',
+        async credentialStatus => {
+            const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+            const credential = { ...createVc(), credentialStatus };
+            const stored = await storeCredential(credential);
+            expect(warn).not.toHaveBeenCalled();
+            expect(stored.credential).toBe(JSON.stringify(credential));
+        }
+    );
+
+    it.each([
+        ['Encrypted', createJwe()],
+        ['Plaintext', createVc()],
+    ] as const)(
+        'warns for %s VC v1 issuance with empty status metadata',
+        async (kind, credential) => {
+            const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+            const stored = await storeCredential({
+                kind: 'issued-credential',
+                credential,
+                statusEntries: [],
+            });
+            expect(warn).toHaveBeenCalledExactlyOnceWith(
+                expect.stringContaining(`${kind} credential has no status metadata`),
+                { credentialId: stored.id }
+            );
+            expect(stored.credential).toBe(JSON.stringify(credential));
+            expect(stored.statusEntries).toBeUndefined();
+        }
+    );
+
+    it('does not treat a wire JWE with extra envelope-like fields as trusted issuance metadata', async () => {
+        vi.spyOn(console, 'warn').mockImplementation(() => {});
+        const jwe = {
+            ...createJwe(),
+            kind: 'issued-credential',
+            credential: createJwe(),
+            statusEntries: [statusEntry],
+        };
+        await storeCredential(jwe);
+        expect(mocks.createOne.mock.calls[0]![0].statusEntries).toBeUndefined();
+        expect(mocks.createOne.mock.calls[0]![0].credential).toBe(JSON.stringify(jwe));
+    });
+});

package/src/accesslayer/credential/create.ts

@@ -1,12 +1,36 @@
-import { UnsignedVC, VC, JWE } from '@learncard/types';
+import { BitstringStatusListEntryValidator, UnsignedVC, VC, JWE } from '@learncard/types';
 import { v4 as uuid } from 'uuid';
+import { getBitstringStatusListEntries, isEncrypted } from '@learncard/helpers';
+import { isIssuedCredential } from '@helpers/issuedCredentialStatus.helpers';
+import type { IssuedCredential } from 'types/credential';
 
 import { Credential, CredentialInstance } from '@models';
 
 export const storeCredential = async (
-    credential: UnsignedVC | VC | JWE
+    input: UnsignedVC | VC | JWE | IssuedCredential
 ): Promise<CredentialInstance> => {
     const id = uuid();
 
-    return Credential.createOne({ id, credential: JSON.stringify(credential) });
+    const issued = isIssuedCredential(input);
+    const credential = issued ? input.credential : input;
+    // Fail if an internal issuance result lost its metadata. Pre-signed wire
+    // payloads remain supported, with an explicit revocation warning.
+    const statusEntries = issued
+        ? BitstringStatusListEntryValidator.array().parse(input.statusEntries)
+        : undefined;
+    const encrypted = isEncrypted(credential);
+    if (
+        !statusEntries?.length &&
+        (encrypted || !getBitstringStatusListEntries(credential).length)
+    ) {
+        console.warn(
+            `[storeCredential] ${encrypted ? 'Encrypted' : 'Plaintext'} credential has no status metadata; network revocation and suspension cannot update its signed status list.`,
+            { credentialId: id }
+        );
+    }
+    return Credential.createOne({
+        id,
+        credential: JSON.stringify(credential),
+        ...(statusEntries?.length ? { statusEntries: JSON.stringify(statusEntries) } : {}),
+    });
 };

package/src/accesslayer/credential-activity/create.ts

@@ -23,6 +23,7 @@ export const createCredentialActivity = async (
         eventType: params.eventType,
         timestamp,
         actorProfileId: params.actorProfileId,
+        onBehalfOf: params.onBehalfOf,
         recipientType: params.recipientType,
         recipientIdentifier: params.recipientIdentifier,
         boostUri: params.boostUri,