@learncard/network-brain-service 4.1.2 → 5.0.0

package/src/accesslayer/consentflowcontract/delete.ts

@@ -1,6 +1,124 @@
-import { ConsentFlowContract } from '@models';
+import { neogma } from '@instance';
 import { DbContractType } from 'types/consentflowcontract';
+import { TRPCError } from '@trpc/server';
+import { ConsentFlowContractValidator } from '@learncard/types';
+import { diffContractChange, buildContractUpdatePreview } from '@learncard/helpers';
+import { getConsentFlowContractVersionRecord } from './versions';
+import { tryDispatchContractEvent } from '@helpers/contract-events.helpers';
+import { constructUri } from '@helpers/uri.helpers';
+import { environment } from '@environment';
+import { v4 as uuid } from 'uuid';
 
-export const deleteConsentFlowContract = async (contract: DbContractType): Promise<number> => {
-    return ConsentFlowContract.delete({ where: { id: contract.id }, detach: true });
+/** Retire in place so terms and transaction history remain exportable. */
+export const deleteConsentFlowContract = async (
+    contract: DbContractType,
+    domain = environment.DOMAIN_NAME ?? 'network.learncard.com',
+    appBaseUrl = domain
+): Promise<number> => {
+    const contractId = contract.id;
+    const currentVersion = contract.currentVersion ?? contract.version ?? 1;
+    const snapshot = await getConsentFlowContractVersionRecord(contractId, currentVersion);
+    if (!snapshot)
+        throw new TRPCError({
+            code: 'PRECONDITION_FAILED',
+            message: 'Contract version snapshot is missing',
+        });
+
+    const diff = diffContractChange(snapshot, {
+        ...snapshot,
+        contract: ConsentFlowContractValidator.parse({}),
+    });
+    const kind = 'relaxed' as const;
+    const preview = buildContractUpdatePreview({ name: snapshot.name, kind, diff });
+    const createdAt = new Date().toISOString();
+    const nextVersion = currentVersion + 1;
+    const reviewUrl = `${appBaseUrl.replace(/\/+$/, '')}/consent-flow/review?uri=${encodeURIComponent(constructUri('contract', contractId, domain))}`;
+    const eventId = `${contractId}:version:${nextVersion}`;
+    const notificationData = {
+        contractUri: constructUri('contract', contractId, domain),
+        contractName: snapshot.name,
+        fromVersion: currentVersion,
+        toVersion: nextVersion,
+        kind,
+        diff,
+        reviewUrl,
+        preview,
+    };
+    const result = await neogma.queryRunner.run(
+        `MATCH (c:ConsentFlowContract {id:$id})
+         WHERE coalesce(c.status,'active') <> 'retired'
+         SET c._contractVersionLock=coalesce(c._contractVersionLock,0)+1
+         WITH c
+         WHERE coalesce(c.currentVersion,1)=$currentVersion
+         OPTIONAL MATCH (terms:ConsentFlowTerms)-[:CONSENTS_TO]->(c)
+         WHERE terms.status IN ['live','needs_reconsent','suspended','consumed']
+         WITH c, collect(DISTINCT terms) AS terms
+         MATCH (c)-[:CREATED_BY]->(owner:Profile)
+         WITH c, terms, collect(DISTINCT owner.profileId)[0] AS ownerProfileId
+         UNWIND CASE WHEN size(terms)=0 THEN [null] ELSE terms END AS term
+         OPTIONAL MATCH (term)<-[:CREATED_BY]-(consenter:Profile)
+         WITH c, terms, ownerProfileId, collect(DISTINCT consenter.profileId) AS recipientProfileIds
+         CREATE (version:ConsentFlowContractVersion {
+             id:$versionId, version:$nextVersion, contract:$contractSnapshot,
+             autoboosts:$autoboostSnapshot, writers:$writerSnapshot,
+             name:$name, subtitle:$subtitle, description:$description,
+             reasonForAccessing:$reasonForAccessing, image:$image,
+             needsGuardianConsent:$needsGuardianConsent, redirectUrl:$redirectUrl,
+             frontDoorBoostUri:$frontDoorBoostUri, expiresAt:$expiresAt,
+             kind:$kind, createdAt:$createdAt
+         })
+         CREATE (c)-[:HAS_VERSION]->(version)
+         SET c.currentVersion=$nextVersion, c.status='retired', c.updatedAt=$createdAt,
+             c.latestUpdate=$latestUpdate
+         REMOVE c._contractVersionLock
+         FOREACH (term IN terms |
+             SET term.status='withdrawn', term.mutationVersion=coalesce(term.mutationVersion,0)+1, term.updatedAt=$createdAt
+             CREATE (transaction:ConsentFlowTransaction {id:randomUUID(), action:'withdraw', date:$createdAt})-[:IS_FOR]->(term))
+         CREATE (event:ConsentFlowEvent {
+             id:$eventId, contractId:c.id, fromId:ownerProfileId, ownerId:ownerProfileId,
+             domain:$eventDomain, kind:'contract_updated', payload:$eventPayload,
+             cleanupPending:true, createdAt:$createdAt
+         })
+         FOREACH (recipientId IN [id IN recipientProfileIds WHERE id IS NOT NULL AND id <> ownerProfileId] |
+             CREATE (event)-[:HAS_DELIVERY]->(:ConsentFlowEventDelivery {
+                 id:event.id + ':' + recipientId, toId:recipientId, state:'pending',
+                 nextAttemptAt:$createdAt, eventCreatedAt:$createdAt, attempts:0, role:'target'
+             }))
+         RETURN count(DISTINCT c) AS count`,
+        {
+            id: contractId,
+            currentVersion,
+            eventId,
+            eventDomain: domain,
+            eventPayload: JSON.stringify(notificationData),
+            nextVersion,
+            versionId: uuid(),
+            contractSnapshot: JSON.stringify(snapshot.contract),
+            autoboostSnapshot: JSON.stringify(snapshot.autoboosts),
+            writerSnapshot: JSON.stringify(snapshot.writers),
+            name: snapshot.name,
+            subtitle: snapshot.subtitle ?? null,
+            description: snapshot.description ?? null,
+            reasonForAccessing: snapshot.reasonForAccessing ?? null,
+            image: snapshot.image ?? null,
+            needsGuardianConsent: snapshot.needsGuardianConsent ?? false,
+            redirectUrl: snapshot.redirectUrl ?? null,
+            frontDoorBoostUri: snapshot.frontDoorBoostUri ?? null,
+            expiresAt: snapshot.expiresAt ?? null,
+            kind,
+            createdAt,
+            latestUpdate: JSON.stringify({
+                fromVersion: currentVersion,
+                toVersion: nextVersion,
+                kind,
+                diff,
+                createdAt,
+                preview,
+            }),
+        }
+    );
+    const record = result.records[0];
+    if (!record || Number(record.get('count') ?? 0) === 0) return 0;
+    await tryDispatchContractEvent(eventId);
+    return Number(record.get('count'));
 };

package/src/accesslayer/consentflowcontract/read.ts

@@ -3,21 +3,27 @@ import { QueryBuilder, BindParam } from 'neogma';
 
 import { getIdFromUri } from '@helpers/uri.helpers';
 import { ConsentFlowContract, ConsentFlowInstance, Profile } from '@models';
-import { DbContractType } from 'types/consentflowcontract';
+import { DbContractType, DbContractValidator } from 'types/consentflowcontract';
 import { inflateObject } from '@helpers/objects.helpers';
 import type { ContractRequestFields } from '@learncard/types';
 import { ProfileType } from 'types/profile';
 
 export const getContractById = async (id: string): Promise<DbContractType | null> => {
-    return inflateObject<DbContractType>(
-        (
-            await new QueryBuilder()
-                .match({ model: ConsentFlowContract, where: { id }, identifier: 'contract' })
-                .return('contract')
-                .limit(1)
-                .run()
-        ).records[0]?.toObject().contract.properties
+    const result = await neogma.queryRunner.run(
+        `MATCH (contract:ConsentFlowContract {id:$id})
+         OPTIONAL MATCH (contract)-[:HAS_VERSION]->(version:ConsentFlowContractVersion)
+         WITH contract, version ORDER BY version.version DESC
+         WITH contract, collect(version)[0] AS latest
+         RETURN properties(contract) AS contract, properties(latest) AS latest`,
+        { id }
     );
+    const record = result.records[0];
+    if (!record) return null;
+    const contract = DbContractValidator.parse(inflateObject(record.get('contract')));
+    const latest = record.get('latest') as Record<string, unknown> | null;
+    contract.currentVersion = Number(contract.currentVersion ?? latest?.version ?? 1);
+    contract.version = Number(latest?.version ?? contract.currentVersion);
+    return contract;
 };
 
 export const getContractByUri = async (uri: string): Promise<DbContractType | null> => {

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

@@ -1,4 +1,3 @@
-import { termsReferralSnapshotCypher } from '@helpers/consent-referral.helpers';
 import { appendConsentEvent, tryDispatchContractEvent } from '@helpers/contract-events.helpers';
 import {
     ConsentFlowTerms as ConsentFlowTermsType,
@@ -20,7 +19,14 @@ import { DbContractType, FlatDbTermsType } from 'types/consentflowcontract';
 import { BoostType } from 'types/boost';
 import { flattenObject, inflateObject } from '@helpers/objects.helpers';
 import { convertQueryResultToPropertiesObjectArray } from '@helpers/neo4j.helpers';
-import { reconsentTerms } from './update';
+import {
+    reconsentTerms,
+    claimAutoBoostTransaction,
+    completeAutoBoostTransaction,
+    releaseAutoBoostClaim,
+    isAutoBoostConsentCurrent,
+} from './update';
+import { getConsentFlowContractVersionRecord } from '@accesslayer/consentflowcontract/versions';
 import { getBoostUri, sendBoost, stampIssuanceDate } from '@helpers/boost.helpers';
 import { setCredentialSubjectIds } from '@helpers/credentialSubject.helpers';
 import { getDidWeb } from '@helpers/did.helpers';
@@ -85,6 +91,7 @@ export const consentToContract = async (
         audienceVersion,
         expectedRequestId,
         smartResumeFingerprint,
+        acceptVersion,
     }: {
         terms: ConsentFlowTermsType;
         expiresAt?: string;
@@ -94,9 +101,11 @@ export const consentToContract = async (
         audienceVersion?: number;
         expectedRequestId?: string;
         smartResumeFingerprint?: string;
+        acceptVersion?: number;
     },
     domain: string
 ) => {
+    const expectedContractVersion = Number(contract.currentVersion ?? 1);
     const terms = cloneDeep(_terms);
     const deniedWriters: string[] = terms.deniedWriters ?? [];
 
@@ -143,6 +152,7 @@ export const consentToContract = async (
                 audienceVersion,
                 smartResumeFingerprint,
                 expectedRequestId,
+                acceptVersion,
             },
             domain
         );
@@ -174,6 +184,7 @@ export const consentToContract = async (
                                 : {}),
                             ...(guardianApproval ? { guardianApproval } : {}),
                         }),
+                        expectedContractVersion,
                         audienceVersion: audienceVersion ?? null,
                         expectedRequestId: expectedRequestId ?? null,
                         consenterProfileId: consenter.profileId,
@@ -181,7 +192,9 @@ export const consentToContract = async (
                 ),
                 contract.id
             )
-                .where(`${audienceVersionWhere} AND ${consentMutationWhere}`)
+                .where(
+                    `${audienceVersionWhere} AND ${consentMutationWhere} AND coalesce(contract.currentVersion, 1) = $expectedContractVersion AND coalesce(contract.status, 'active') <> 'retired'`
+                )
                 .set('contract.hasConsented = true')
                 .with('contract')
                 .match({
@@ -209,7 +222,9 @@ export const consentToContract = async (
                             model: ConsentFlowTerms,
                             properties: {
                                 id: termsId,
-                                status: oneTime ? 'stale' : 'live',
+                                status: oneTime ? 'consumed' : 'live',
+                                consentedVersion: contract.currentVersion ?? 1,
+                                lastReviewedVersion: contract.currentVersion ?? 1,
                                 createdAt: transaction.date,
                                 updatedAt: transaction.date,
                                 ...(expiresAt ? { expiresAt } : {}),
@@ -248,23 +263,31 @@ export const consentToContract = async (
     );
     assertAudienceMutation(result.records.length);
 
-    const autoBoosts = await ConsentFlowContract.findRelationships({
-        alias: 'autoReceive',
-        where: { source: { id: contract.id } },
-    });
+    const versionSnapshot = await getConsentFlowContractVersionRecord(
+        contract.id,
+        Number(contract.currentVersion ?? 1)
+    );
+    const configuredAutoBoosts = new Map(
+        (versionSnapshot?.autoboosts ?? []).map(config => [config.id, config])
+    );
+    const autoBoosts = (
+        await ConsentFlowContract.findRelationships({
+            alias: 'autoReceive',
+            where: { source: { id: contract.id } },
+        })
+    ).filter(boost => configuredAutoBoosts.has(boost.target.id));
 
     if (autoBoosts.length > 0) {
         await Promise.all(
             autoBoosts.map(async boost => {
+                let claimId: string | undefined;
+                let sendStarted = false;
                 try {
-                    const signingAuthorityEndpoint =
-                        boost.relationship?.signingAuthorityEndpoint || 'default';
-                    const signingAuthorityName =
-                        boost.relationship?.signingAuthorityName || 'default';
-
+                    const config = configuredAutoBoosts.get(boost.target.id)!;
+                    const signingAuthorityEndpoint = config.signingAuthorityEndpoint || 'default';
+                    const signingAuthorityName = config.signingAuthorityName || 'default';
                     const issuer =
-                        (boost.relationship?.issuer &&
-                            (await getProfileByProfileId(boost.relationship.issuer))) ||
+                        (config.issuer && (await getProfileByProfileId(config.issuer))) ||
                         contractOwner;
 
                     if (terms.deniedWriters?.includes(issuer.profileId)) return;
@@ -278,6 +301,14 @@ export const consentToContract = async (
 
                         if (categoryWritePermission !== true) return;
                     }
+                    claimId =
+                        (await claimAutoBoostTransaction(
+                            contract.id,
+                            termsId,
+                            String(boost.target.id),
+                            Boolean(oneTime)
+                        )) ?? undefined;
+                    if (!claimId) return;
 
                     const contractOwnerSigningAuthority = await getSigningAuthorityForUserByName(
                         issuer,
@@ -286,6 +317,8 @@ export const consentToContract = async (
                     );
 
                     if (!contractOwnerSigningAuthority) {
+                        await releaseAutoBoostClaim(claimId);
+                        claimId = undefined;
                         console.error(
                             `Signing authority "${signingAuthorityName}" at endpoint "${signingAuthorityEndpoint}" not found for contract owner`
                         );
@@ -325,36 +358,24 @@ export const consentToContract = async (
                         [getDidWeb(domain, contractOwner.profileId)]
                     );
 
-                    const boostTransaction = {
-                        id: uuid(),
-                        action: 'write',
-                        date: new Date().toISOString(),
-                    } as const satisfies ConsentFlowTransaction;
-
                     const termsResult = await new QueryBuilder()
                         .match({
                             identifier: 'terms',
                             model: ConsentFlowTerms,
                             where: { id: termsId },
                         })
-                        .create({
-                            related: [
-                                {
-                                    identifier: 'boostTransaction',
-                                    model: ConsentFlowTransactionModel,
-                                    properties: boostTransaction,
-                                },
-                                ConsentFlowTransactionModel.getRelationshipByAlias('isFor'),
-                                { identifier: 'terms' },
-                            ],
-                        })
-                        .raw(termsReferralSnapshotCypher('boostTransaction'))
                         .return('terms')
                         .run();
-
                     const updatedTerms = termsResult.records[0]?.get('terms')
                         .properties as FlatDbTermsType;
-
+                    if (
+                        !(await isAutoBoostConsentCurrent(contract.id, termsId, Boolean(oneTime)))
+                    ) {
+                        await releaseAutoBoostClaim(claimId);
+                        claimId = undefined;
+                        return;
+                    }
+                    sendStarted = true;
                     await sendBoost({
                         from: { type: 'profile', profile: contractOwner },
                         to: consenter,
@@ -364,9 +385,22 @@ export const consentToContract = async (
                         skipNotification: true,
                         autoAcceptCredential: false,
                         contractTerms: inflateObject(updatedTerms),
+                        contractWriterProfileId: issuer.profileId,
+                        allowConsumedOneTime: Boolean(oneTime),
                     });
+                    await completeAutoBoostTransaction(claimId, termsId, String(boost.target.id));
+                    claimId = undefined;
                 } catch (error) {
-                    console.error('Error processing auto-boost:', error);
+                    if (claimId && sendStarted) {
+                        console.error(
+                            'Auto-boost claim send failed; delivery may be ambiguous',
+                            { claimId, termsId, boostId: String(boost.target.id) },
+                            error
+                        );
+                    } else {
+                        console.error('Error processing auto-boost:', error);
+                    }
+                    if (claimId && !sendStarted) await releaseAutoBoostClaim(claimId);
                 }
             })
         );