@learncard/network-brain-service 3.19.0 → 4.0.0

package/src/helpers/contract-requests.helpers.ts

@@ -0,0 +1,211 @@
+import { randomUUID } from 'node:crypto';
+import { BindParam, QueryBuilder } from 'neogma';
+import { TRPCError } from '@trpc/server';
+import type { SendContractRequest } from '@learncard/types';
+import {
+    getContractByUri,
+    getContractRequestAccess,
+    getStoredContractRequest,
+} from '@accesslayer/consentflowcontract/read';
+import { getProfileByProfileId } from '@accesslayer/profile/read';
+import { getWritersForContract } from '@accesslayer/consentflowcontract/relationships/read';
+import {
+    canReadContractData,
+    lockContractAudience,
+    runAudienceMutation,
+} from '@accesslayer/consentflowcontract/relationships/recipients';
+import { getProfileIdFromString } from './did.helpers';
+import { userHasRequiredScopes } from './auth-grant.helpers';
+import { enforceRateLimits } from './rateLimit.helpers';
+import { requestEventCypher, tryDispatchContractEvent } from './contract-events.helpers';
+import type { ProfileType } from 'types/profile';
+import type { DbContractType } from 'types/consentflowcontract';
+
+/** Resolve shared request inputs without granting writers access to consented data. */
+export const resolveContractRequest = async (
+    contractUri: string,
+    targetIdentifier: string,
+    profile: ProfileType,
+    domain: string,
+    allowRecipients = true
+): Promise<{ contract: DbContractType; target: ProfileType }> => {
+    const contract = await getContractByUri(contractUri);
+    if (!contract) throw new TRPCError({ code: 'NOT_FOUND', message: 'Contract not found' });
+    if (!(await canManageContractRequests(contract, profile.profileId, allowRecipients)))
+        throw new TRPCError({
+            code: 'UNAUTHORIZED',
+            message: 'You do not have permission to send requests for this contract.',
+        });
+    const targetId = await getProfileIdFromString(targetIdentifier, domain);
+    const target = targetId ? await getProfileByProfileId(targetId) : null;
+    if (!target) throw new TRPCError({ code: 'NOT_FOUND', message: 'Target profile not found' });
+    return { contract, target };
+};
+
+export const canManageContractRequests = async (
+    contract: DbContractType,
+    profileId: string,
+    allowRecipients = false
+): Promise<boolean> => {
+    const access = await getContractRequestAccess(contract.id, profileId);
+    return access.isManager || (allowRecipients && access.isRecipient);
+};
+
+/** One request per contract/target in v1. Exact pending retries do not create another event. */
+export const sendGenericContractRequest = async (
+    input: SendContractRequest,
+    profile: ProfileType,
+    domain: string
+): Promise<boolean> => {
+    const { contract, target } = await resolveContractRequest(
+        input.contractUri,
+        input.targetProfileId,
+        profile,
+        domain
+    );
+    if (target.profileId === profile.profileId)
+        throw new TRPCError({
+            code: 'BAD_REQUEST',
+            message: 'You cannot send a request to yourself.',
+        });
+    await enforceRateLimits([
+        {
+            key: `contract-request-rate:${contract.id}:${profile.profileId}`,
+            limit: 500,
+            windowSeconds: 3600,
+            description: '500 contract requests per hour',
+        },
+    ]);
+    const requestId = randomUUID();
+    const query = lockContractAudience(
+        new QueryBuilder(
+            new BindParam({
+                targetProfileId: target.profileId,
+                senderProfileId: profile.profileId,
+                requestId,
+                externalReferenceId: input.externalReferenceId ?? null,
+                message: input.message ?? null,
+                now: new Date().toISOString(),
+                domain,
+                eventFrom: profile.profileId,
+                eventKind: 'request_sent',
+            })
+        ),
+        contract.id
+    ).raw(`
+        MATCH (target:Profile {profileId: $targetProfileId})
+        WITH contract, target WHERE $targetProfileId <> $senderProfileId AND EXISTS {
+            MATCH (contract)-[:CREATED_BY|CAN_WRITE|SHARES_DATA_WITH]->(:Profile {profileId: $senderProfileId})
+        } AND CASE WHEN contract.expiresAt IS NULL OR trim(contract.expiresAt) = '' THEN true ELSE datetime(contract.expiresAt) > datetime($now) END
+        AND NOT EXISTS {
+            MATCH (target)-[:CREATED_BY]->(terms:ConsentFlowTerms)-[:CONSENTS_TO]->(contract)
+            WHERE (terms.status = 'live' OR (terms.status = 'stale' AND terms.oneTime = true)) AND
+                CASE WHEN terms.expiresAt IS NULL OR trim(terms.expiresAt) = '' THEN true ELSE datetime(terms.expiresAt) > datetime($now) END
+        }
+        OPTIONAL MATCH (contract)-[existing:REQUESTED_FOR]->(target)
+        WITH contract, target, existing WHERE existing IS NULL OR
+            (existing.status = 'pending' AND existing.requestId IS NOT NULL AND
+                existing.requestedBy = $senderProfileId AND
+                coalesce(existing.externalReferenceId, '') = coalesce($externalReferenceId, '') AND
+                coalesce(existing.message, '') = coalesce($message, ''))
+        MERGE (contract)-[request:REQUESTED_FOR]->(target)
+        ON CREATE SET request += {requestId: $requestId, requestedBy: $senderProfileId,
+            externalReferenceId: $externalReferenceId, message: $message,
+            requestedAt: $now, status: 'pending', readStatus: 'unseen'}
+        ${requestEventCypher}
+    `);
+    const result = await runAudienceMutation(query);
+    if (!result.records.length)
+        throw new TRPCError({
+            code: 'CONFLICT',
+            message:
+                'Active consent or a conflicting/terminal request already exists, or the contract changed.',
+        });
+    await tryDispatchContractEvent(result.records[0]!.get('eventId'));
+    return true;
+};
+
+/** Target-only denial; cancellation also permits owner/writers and the requesting recipient. */
+export const decideGenericContractRequest = async ({
+    contract,
+    targetProfileId,
+    actorProfileId,
+    status,
+    domain,
+}: {
+    contract: DbContractType;
+    targetProfileId: string;
+    actorProfileId: string;
+    status: 'denied' | 'cancelled';
+    domain: string;
+}): Promise<boolean> => {
+    const request = await getStoredContractRequest(contract.id, targetProfileId);
+    if (!request?.requestId)
+        throw new TRPCError({ code: 'NOT_FOUND', message: 'Contract request not found' });
+    const isTarget = actorProfileId === targetProfileId;
+    const writers = await getWritersForContract(contract);
+    const authorized =
+        isTarget ||
+        (status === 'cancelled' &&
+            (writers.some(profile => profile.profileId === actorProfileId) ||
+                (request.requestedBy === actorProfileId &&
+                    (await canReadContractData(contract.id, actorProfileId)))));
+    if (!authorized)
+        throw new TRPCError({ code: 'UNAUTHORIZED', message: 'You cannot change this request' });
+    const result = await runAudienceMutation(
+        lockContractAudience(
+            new QueryBuilder(
+                new BindParam({
+                    targetProfileId,
+                    actorProfileId,
+                    status,
+                    domain,
+                    now: new Date().toISOString(),
+                    eventKind: status === 'denied' ? 'request_denied' : 'request_cancelled',
+                    eventFrom: actorProfileId,
+                })
+            ),
+            contract.id
+        ).raw(`
+        MATCH (contract)-[request:REQUESTED_FOR]->(target:Profile {profileId: $targetProfileId})
+        WHERE request.requestId IS NOT NULL AND request.status IN ['pending', $status]
+            AND ($actorProfileId = $targetProfileId OR ($status = 'cancelled' AND
+                (EXISTS { MATCH (contract)-[:CREATED_BY|CAN_WRITE]->(:Profile {profileId: $actorProfileId}) } OR
+                 (request.requestedBy = $actorProfileId AND EXISTS {
+                    MATCH (contract)-[:SHARES_DATA_WITH]->(:Profile {profileId: $actorProfileId}) }))))
+        SET request.status = $status
+        ${requestEventCypher}
+    `)
+    );
+    if (!result.records.length)
+        throw new TRPCError({
+            code: 'CONFLICT',
+            message: 'Request already decided or permission changed',
+        });
+    await tryDispatchContractEvent(result.records[0]!.get('eventId'));
+    return true;
+};
+
+export const markGenericContractRequestSeen = async (
+    contractId: string,
+    targetProfileId: string
+): Promise<boolean> => {
+    const result = await runAudienceMutation(
+        lockContractAudience(new QueryBuilder(new BindParam({ targetProfileId })), contractId)
+            .raw(`MATCH (contract)-[request:REQUESTED_FOR]->(:Profile {profileId: $targetProfileId})
+            WHERE request.requestId IS NOT NULL
+            SET request.readStatus = 'seen' RETURN request`)
+    );
+    if (!result.records.length)
+        throw new TRPCError({ code: 'NOT_FOUND', message: 'Request not found' });
+    return true;
+};
+
+/** Legacy request mutations retain their scope behavior; attributed requests require write. */
+export const assertGenericRequestWriteScope = (scope?: string): void => {
+    if (!userHasRequiredScopes(scope ?? '', 'contracts:write'))
+        throw new TRPCError({
+            code: 'UNAUTHORIZED',
+            message: 'This operation requires contracts:write scope',
+        });
+};

package/src/helpers/credentialSubject.helpers.test.ts

@@ -0,0 +1,114 @@
+import { describe, expect, it } from 'vitest';
+import type { UnsignedVC } from '@learncard/types';
+
+import { setCredentialSubjectIds } from './credentialSubject.helpers';
+
+const collectSubjectIds = (credential: Record<string, unknown>): string[] => {
+    const subject = credential.credentialSubject;
+    const subjects = Array.isArray(subject) ? subject : [subject];
+
+    return subjects.flatMap(currentSubject => {
+        if (!currentSubject || typeof currentSubject !== 'object') return [];
+
+        const subjectRecord = currentSubject as Record<string, unknown>;
+        const embedded = subjectRecord.verifiableCredential;
+        const embeddedCredentials = Array.isArray(embedded) ? embedded : embedded ? [embedded] : [];
+
+        return [
+            subjectRecord.id as string,
+            ...embeddedCredentials.flatMap(nested =>
+                collectSubjectIds(nested as Record<string, unknown>)
+            ),
+        ];
+    });
+};
+
+describe('setCredentialSubjectIds', () => {
+    it('patches every CLR learner subject without rewriting achievement identities', () => {
+        const credential = {
+            credentialSubject: {
+                id: 'did:example:old-root',
+                achievement: {
+                    id: 'https://example.edu/transcript',
+                    creator: { id: 'https://example.edu' },
+                },
+                verifiableCredential: [
+                    {
+                        credentialSubject: {
+                            id: 'did:example:old-course',
+                            achievement: {
+                                id: 'https://example.edu/courses/imd-120',
+                                creator: { id: 'https://example.edu/departments/design' },
+                            },
+                            verifiableCredential: {
+                                credentialSubject: { id: 'did:example:old-assessment' },
+                            },
+                        },
+                    },
+                ],
+            },
+        } as unknown as UnsignedVC;
+
+        setCredentialSubjectIds(credential, 'did:example:learner');
+
+        expect(collectSubjectIds(credential as unknown as Record<string, unknown>)).toEqual([
+            'did:example:learner',
+            'did:example:learner',
+            'did:example:learner',
+        ]);
+        expect(credential.credentialSubject).toMatchObject({
+            achievement: {
+                id: 'https://example.edu/transcript',
+                creator: { id: 'https://example.edu' },
+            },
+            verifiableCredential: [
+                {
+                    credentialSubject: {
+                        achievement: {
+                            id: 'https://example.edu/courses/imd-120',
+                            creator: { id: 'https://example.edu/departments/design' },
+                        },
+                    },
+                },
+            ],
+        });
+    });
+
+    it('preserves signed embedded credentials while patching unsigned subjects', () => {
+        const credential = {
+            credentialSubject: {
+                id: 'did:example:old-root',
+                verifiableCredential: [
+                    {
+                        credentialSubject: { id: 'did:example:signed-subject' },
+                        proof: { type: 'DataIntegrityProof', proofValue: 'signed-value' },
+                    },
+                    {
+                        credentialSubject: { id: 'did:example:unsigned-subject' },
+                    },
+                ],
+            },
+        } as unknown as UnsignedVC;
+
+        setCredentialSubjectIds(credential, 'did:example:learner');
+
+        const subject = credential.credentialSubject as Record<string, unknown>;
+        const embedded = subject.verifiableCredential as Array<Record<string, unknown>>;
+
+        expect(subject.id).toBe('did:example:learner');
+        expect(embedded[0]?.credentialSubject).toEqual({
+            id: 'did:example:signed-subject',
+        });
+        expect(embedded[1]?.credentialSubject).toEqual({
+            id: 'did:example:learner',
+        });
+    });
+
+    it('creates an outer credential subject when a legacy template omits it', () => {
+        const credential = {} as UnsignedVC;
+
+        setCredentialSubjectIds(credential, 'did:example:learner');
+
+        expect(credential.credentialSubject).toEqual({ id: 'did:example:learner' });
+    });
+});

package/src/helpers/credentialSubject.helpers.ts

@@ -0,0 +1,40 @@
+import type { UnsignedVC, VC } from '@learncard/types';
+
+const setSubjectIds = (subject: unknown, subjectDid: string): void => {
+    if (Array.isArray(subject)) {
+        subject.forEach(nestedSubject => setSubjectIds(nestedSubject, subjectDid));
+        return;
+    }
+
+    if (!subject || typeof subject !== 'object') return;
+
+    const mutableSubject = subject as Record<string, unknown>;
+    mutableSubject.id = subjectDid;
+
+    const embeddedCredentials = mutableSubject.verifiableCredential;
+    const credentials = Array.isArray(embeddedCredentials)
+        ? embeddedCredentials
+        : [embeddedCredentials];
+
+    credentials.forEach(credential => {
+        if (!credential || typeof credential !== 'object' || Array.isArray(credential)) return;
+
+        const credentialRecord = credential as Record<string, unknown>;
+        if (credentialRecord.proof !== undefined) return;
+
+        setSubjectIds(credentialRecord.credentialSubject, subjectDid);
+    });
+};
+
+/**
+ * Sets the recipient DID on the outer credential and unsigned credentials nested in a CLR.
+ * Signed embedded credentials are immutable because changing their subject invalidates the proof.
+ */
+export const setCredentialSubjectIds = (credential: UnsignedVC | VC, subjectDid: string): void => {
+    if (!credential.credentialSubject) {
+        credential.credentialSubject = { id: subjectDid };
+        return;
+    }
+
+    setSubjectIds(credential.credentialSubject, subjectDid);
+};

package/src/helpers/finalize-inbox.helpers.ts

@@ -3,7 +3,11 @@ import {
     LCNNotificationTypeEnumValidator,
     LCNInboxStatusEnumValidator,
     VC,
+    JWE,
     UnsignedVC,
+    VCValidator,
+    JWEValidator,
+    InboxCredentialType,
 } from '@learncard/types';
 import { ProfileType } from 'types/profile';
 import { getContactMethodsForProfile } from '@accesslayer/contact-method/read';
@@ -21,6 +25,113 @@ import { getLearnCard, getEmptyLearnCard } from '@helpers/learnCard.helpers';
 import { logCredentialClaimed, logCredentialFailed } from '@helpers/activity.helpers';
 import { handleConnectionPromptsForCredentialClaim } from '@helpers/connectionPrompt.helpers';
 import { decryptInboxCredential } from '@helpers/inbox-encryption.helpers';
+import { setCredentialSubjectIds } from '@helpers/credentialSubject.helpers';
+import { getBitstringStatusListEntries } from '@learncard/helpers';
+import type { IssuedCredential } from 'types/credential';
+import { getBoostByUri } from '@accesslayer/boost/read';
+import { storeCredential } from '@accesslayer/credential/create';
+import { createBoostInstanceOfRelationship } from '@accesslayer/boost/relationships/create';
+import {
+    createSentCredentialRelationship,
+    createReceivedCredentialRelationship,
+    setDefaultClaimedRole,
+} from '@accesslayer/credential/relationships/create';
+import { neogma } from '@instance';
+import { processClaimHooks } from '@helpers/claim-hooks.helpers';
+import { clearDidWebCacheForChildProfileManagers } from '@accesslayer/boost/relationships/update';
+
+/** Graph-only completion: a failed write retains pending escrow for the next attempt. */
+const finalizeAcceptedDelivery = async (
+    inboxCredential: InboxCredentialType,
+    issued: IssuedCredential,
+    recipient: ProfileType,
+    sender: ProfileType
+): Promise<boolean> => {
+    const boost = inboxCredential.boostUri
+        ? await getBoostByUri(inboxCredential.boostUri)
+        : undefined;
+    const session = neogma.driver.session();
+    const transaction = session.beginTransaction({ timeout: 30_000 });
+    // Signing and status-index allocation happen before this bounded graph transaction;
+    // a retry or lost claim race may leave unused indices, intentionally, rather than
+    // hold Neo4j locks across external signing.
+    try {
+        const finalized = await finalizeAndWipeInboxCredential(
+            inboxCredential.id,
+            { recipientDid: recipient.did, credential: JWEValidator.parse(issued.credential) },
+            {},
+            transaction
+        );
+        if (!finalized) {
+            // Another claim or expiry won the lock. It is not a new issuance failure.
+            await transaction.rollback();
+            return false;
+        }
+        const instance = await storeCredential(issued, transaction);
+        if (boost) await createBoostInstanceOfRelationship(instance, boost, transaction);
+        await createSentCredentialRelationship(
+            { type: 'profile', profile: sender },
+            recipient,
+            instance,
+            undefined,
+            inboxCredential.activityId,
+            inboxCredential.integrationId,
+            transaction
+        );
+        await createReceivedCredentialRelationship(
+            recipient,
+            sender,
+            instance,
+            undefined,
+            transaction
+        );
+        await processClaimHooks(recipient, instance, transaction);
+        await setDefaultClaimedRole(recipient, instance, transaction);
+        if (
+            !(await createClaimedRelationship(
+                recipient.profileId,
+                inboxCredential.id,
+                'finalize',
+                transaction
+            ))
+        ) {
+            throw new Error('Inbox claim recipient no longer exists');
+        }
+        await transaction.commit();
+    } catch (error) {
+        await transaction
+            .rollback()
+            .catch(rollbackError =>
+                console.error(
+                    'Failed to roll back inbox finalization',
+                    inboxCredential.id,
+                    rollbackError
+                )
+            );
+        throw error;
+    } finally {
+        // Closing the session cannot turn a committed delivery into a pending failure.
+        await session
+            .close()
+            .catch(error =>
+                console.error(
+                    'Failed to close inbox finalization session',
+                    inboxCredential.id,
+                    error
+                )
+            );
+    }
+    if (boost) {
+        await clearDidWebCacheForChildProfileManagers(boost.id).catch(error =>
+            console.error(
+                'Could not clear did:web cache after inbox claim',
+                inboxCredential.id,
+                error
+            )
+        );
+    }
+    return true;
+};
 
 export async function finalizeInboxCredentialsForProfile(
     profile: ProfileType,
@@ -30,8 +141,8 @@ export async function finalizeInboxCredentialsForProfile(
     claimed: number;
     errors: number;
     guardianPending: number;
-    verifiableCredentials: VC[];
-    deliveries: { id: string; credential: VC }[];
+    verifiableCredentials: (VC | JWE)[];
+    deliveries: { id: string; credential: VC | JWE }[];
 }> {
     const contactMethods = await getContactMethodsForProfile(profile.did);
     const verifiedContacts = contactMethods.filter(cm => cm.isVerified);
@@ -48,8 +159,8 @@ export async function finalizeInboxCredentialsForProfile(
         lcDid = lc.id.did();
     } catch {}
 
-    const verifiableCredentials: VC[] = [];
-    const deliveries: { id: string; credential: VC }[] = [];
+    const verifiableCredentials: (VC | JWE)[] = [];
+    const deliveries: { id: string; credential: VC | JWE }[] = [];
 
     for (const cm of verifiedContacts) {
         const pending = await getAcceptedPendingInboxCredentialsForContactMethodId(cm.id);
@@ -79,7 +190,8 @@ export async function finalizeInboxCredentialsForProfile(
             }
 
             try {
-                let finalCredential: VC;
+                let finalCredential: VC | JWE;
+                let issued: IssuedCredential | undefined;
                 const credentialPayload = inboxCredential.refreshId
                     ? undefined
                     : await decryptInboxCredential(inboxCredential.credential);
@@ -102,29 +214,16 @@ export async function finalizeInboxCredentialsForProfile(
                     if (!endpoint || !name)
                         throw new Error('Inbox credential missing signing authority info');
 
-                    const issuerProfile = await getProfileByDid(inboxCredential.issuerDid);
-                    if (!issuerProfile) throw new Error('Issuer profile not found');
+                    if (!senderProfile) throw new Error('Issuer profile not found');
 
                     const signingAuthorityForUser = await getSigningAuthorityForUserByName(
-                        issuerProfile,
+                        senderProfile,
                         endpoint,
                         name
                     );
                     if (!signingAuthorityForUser) throw new Error('Signing authority not found');
 
-                    // Set subject DID to the authenticated user's DID
-                    if (Array.isArray(unsignedCredential.credentialSubject)) {
-                        unsignedCredential.credentialSubject =
-                            unsignedCredential.credentialSubject.map(sub => ({
-                                ...sub,
-                                id: (sub as any).did || (sub as any).id || profile.did,
-                            }));
-                    } else {
-                        (unsignedCredential.credentialSubject as any).id =
-                            (unsignedCredential as any).credentialSubject?.did ||
-                            (unsignedCredential as any).credentialSubject?.id ||
-                            profile.did;
-                    }
+                    setCredentialSubjectIds(unsignedCredential, profile.did);
 
                     // Set issuer from signing authority
                     unsignedCredential.issuer = signingAuthorityForUser.relationship.did;
@@ -136,36 +235,56 @@ export async function finalizeInboxCredentialsForProfile(
                         ? getAppDidWeb(domain, listingSlug)
                         : undefined;
 
-                    finalCredential = (
-                        await issueCredentialWithSigningAuthority(
-                            { type: 'profile', profile: issuerProfile },
-                            unsignedCredential,
-                            signingAuthorityForUser,
-                            domain,
-                            false,
-                            ownerDidOverride
-                        )
-                    ).credential as VC;
+                    issued = await issueCredentialWithSigningAuthority(
+                        { type: 'profile', profile: senderProfile },
+                        unsignedCredential,
+                        signingAuthorityForUser,
+                        domain,
+                        undefined,
+                        ownerDidOverride,
+                        undefined,
+                        // Preserve issuer did:key access alongside the managed/app did:web reader.
+                        [senderProfile.did]
+                    );
+                    finalCredential = issued.credential;
                 } else {
                     finalCredential = JSON.parse(credentialPayload!) as VC;
                 }
 
                 if (!inboxCredential.refreshId) {
-                    // The seeded encryption plugin adds the service DID; use explicit recipients.
-                    const learnCard = await getEmptyLearnCard();
-                    const recoveryCredential = await learnCard.invoke.createDagJwe(
-                        finalCredential,
-                        [profile.did]
-                    );
-                    const finalized = await finalizeAndWipeInboxCredential(inboxCredential.id, {
-                        recipientDid: profile.did,
-                        credential: recoveryCredential,
-                    });
-                    if (!finalized) throw new Error('Inbox credential is no longer pending');
+                    if (!senderProfile) throw new Error('Issuer profile not found');
+                    if (!issued) {
+                        const signedCredential = VCValidator.parse(finalCredential);
+                        const learnCard = await getEmptyLearnCard();
+                        issued = {
+                            kind: 'issued-credential',
+                            credential: await learnCard.invoke.createDagJwe(signedCredential, [
+                                profile.did,
+                                inboxCredential.issuerDid,
+                            ]),
+                            statusEntries: getBitstringStatusListEntries(signedCredential),
+                        };
+                    }
+                    if (
+                        !(await finalizeAcceptedDelivery(
+                            inboxCredential,
+                            issued,
+                            profile,
+                            senderProfile
+                        ))
+                    )
+                        continue;
+                    finalCredential = issued.credential;
                 }
 
-                // Only write a claim audit edge once the record is actually finalized.
-                await createClaimedRelationship(profile.profileId, inboxCredential.id, 'finalize');
+                // Managed refresh retains its separate lifecycle; ordinary claims audit in the transaction.
+                if (inboxCredential.refreshId) {
+                    await createClaimedRelationship(
+                        profile.profileId,
+                        inboxCredential.id,
+                        'finalize'
+                    );
+                }
 
                 if (
                     senderProfile &&