@learncard/network-brain-service 3.19.0 → 4.0.0

package/src/accesslayer/consentflowcontract/create.ts

@@ -3,12 +3,16 @@ import { QueryBuilder, BindParam } from 'neogma';
 import { ConsentFlowContract } from '@models';
 import { ConsentFlowContract as ConsentFlowContractType } from '@learncard/types';
 import { v4 as uuid } from 'uuid';
-import { getContractById } from './read';
+import { TRPCError } from '@trpc/server';
 import { DbContractType } from 'types/consentflowcontract';
-import { flattenObject } from '@helpers/objects.helpers';
+import { flattenObject, inflateObject } from '@helpers/objects.helpers';
 
 export const createConsentFlowContract = async ({
     contract,
+    ownerProfileId,
+    recipientIds = [],
+    writerIds = [],
+    autoboosts = [],
     name,
     subtitle = '',
     description = '',
@@ -20,6 +24,10 @@ export const createConsentFlowContract = async ({
     expiresAt,
 }: {
     contract: ConsentFlowContractType;
+    ownerProfileId: string;
+    recipientIds?: string[];
+    writerIds?: string[];
+    autoboosts?: { id: string; signingAuthorityEndpoint: string; signingAuthorityName: string }[];
     name: string;
     subtitle?: string;
     description?: string;
@@ -31,9 +39,35 @@ export const createConsentFlowContract = async ({
     expiresAt?: string;
 }): Promise<DbContractType> => {
     const id = uuid();
+    const createdAt = new Date().toISOString();
+    const uniqueRecipientIds = [...new Set(recipientIds)].filter(id => id !== ownerProfileId);
+    const uniqueWriterIds = [...new Set(writerIds)];
+    const autoBoostsById = new Map<string, (typeof autoboosts)[number]>();
+    for (const config of autoboosts) {
+        const existing = autoBoostsById.get(config.id);
+        if (
+            existing &&
+            (existing.signingAuthorityEndpoint !== config.signingAuthorityEndpoint ||
+                existing.signingAuthorityName !== config.signingAuthorityName)
+        ) {
+            throw new TRPCError({
+                code: 'BAD_REQUEST',
+                message: `Conflicting signing authorities for autoboost: ${config.id}`,
+            });
+        }
+        autoBoostsById.set(config.id, config);
+    }
+    // One configured template produces one issuance per consent/update.
+    const uniqueAutoBoosts = [...autoBoostsById.values()];
 
     const query = new QueryBuilder(
         new BindParam({
+            ownerProfileId,
+            recipientIds: uniqueRecipientIds,
+            writerIds: uniqueWriterIds,
+            boostIds: uniqueAutoBoosts.map(boost => boost.id),
+            autoboosts: uniqueAutoBoosts,
+            createdAt,
             params: flattenObject({
                 id,
                 name,
@@ -45,16 +79,55 @@ export const createConsentFlowContract = async ({
                 frontDoorBoostUri,
                 image,
                 contract,
-                createdAt: new Date().toISOString(),
-                updatedAt: new Date().toISOString(),
+                createdAt,
+                updatedAt: createdAt,
+                audienceVersion: uniqueRecipientIds.length,
                 expiresAt,
             }),
         })
     )
+        // Resolve every target before writing; a missing target produces no writes.
+        // One Cypher statement also rolls back the entire configuration on a write failure.
+        .raw(
+            `
+            MATCH (owner:Profile {profileId: $ownerProfileId})
+            OPTIONAL MATCH (recipient:Profile) WHERE recipient.profileId IN $recipientIds
+            WITH owner, collect(DISTINCT recipient) AS recipients
+            WHERE size(recipients) = size($recipientIds)
+            OPTIONAL MATCH (writer:Profile) WHERE writer.profileId IN $writerIds
+            WITH owner, recipients, collect(DISTINCT writer) AS writers
+            WHERE size(writers) = size($writerIds)
+            OPTIONAL MATCH (boost:Boost) WHERE boost.id IN $boostIds
+            WITH owner, recipients, writers, collect(DISTINCT boost) AS boosts
+            WHERE size(boosts) = size($boostIds)
+        `
+        )
         .create({ model: ConsentFlowContract, identifier: 'contract' })
-        .set('contract += $params');
+        .set('contract += $params')
+        .raw(
+            `
+            CREATE (contract)-[:CREATED_BY]->(owner)
+            FOREACH (recipient IN recipients |
+                CREATE (contract)-[:SHARES_DATA_WITH {addedAt: $createdAt}]->(recipient))
+            FOREACH (writer IN writers | CREATE (contract)-[:CAN_WRITE]->(writer))
+            FOREACH (config IN $autoboosts |
+                FOREACH (boost IN [target IN boosts WHERE target.id = config.id] |
+                    CREATE (contract)-[:AUTO_RECEIVE {
+                        signingAuthorityEndpoint: config.signingAuthorityEndpoint,
+                        signingAuthorityName: config.signingAuthorityName,
+                        issuer: $ownerProfileId
+                    }]->(boost)))
+        `
+        )
+        .return('contract');
 
-    await query.run();
-
-    return (await getContractById(id))!;
+    const result = await query.run();
+    const created = result.records[0]?.toObject().contract;
+    if (!created) {
+        throw new TRPCError({
+            code: 'BAD_REQUEST',
+            message: 'Could not find all contract configuration targets',
+        });
+    }
+    return inflateObject<DbContractType>(created.properties);
 };

package/src/accesslayer/consentflowcontract/read.ts

@@ -1,9 +1,11 @@
+import { neogma } from '@instance';
 import { QueryBuilder, BindParam } from 'neogma';
 
 import { getIdFromUri } from '@helpers/uri.helpers';
 import { ConsentFlowContract, ConsentFlowInstance, Profile } from '@models';
 import { DbContractType } 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> => {
@@ -37,21 +39,63 @@ export const getConsentFlowContractById = async (
     return record.toObject().contract;
 };
 
-export const getRequestedForList = async (id: string) => {
-    const result = await new QueryBuilder()
+const requestFields = (properties: ContractRequestFields): ContractRequestFields => ({
+    ...(properties.requestId ? { requestId: properties.requestId } : {}),
+    ...(properties.requestedBy ? { requestedBy: properties.requestedBy } : {}),
+    ...(properties.externalReferenceId
+        ? { externalReferenceId: properties.externalReferenceId }
+        : {}),
+    ...(properties.requestedAt ? { requestedAt: properties.requestedAt } : {}),
+    ...(properties.message ? { message: properties.message } : {}),
+});
+
+/** Referral management is distinct from permission to receive consented data. */
+export const getContractRequestAccess = async (
+    contractId: string,
+    profileId: string
+): Promise<{ isOwner: boolean; isManager: boolean; isRecipient: boolean }> => {
+    const result = await neogma.queryRunner.run(
+        `MATCH (contract:ConsentFlowContract {id:$contractId})
+         RETURN EXISTS {
+             MATCH (contract)-[:CREATED_BY]->(:Profile {profileId:$profileId})
+         } AS isOwner, EXISTS {
+             MATCH (contract)-[:CREATED_BY|CAN_WRITE]->(:Profile {profileId:$profileId})
+         } AS isManager, EXISTS {
+             MATCH (contract)-[:CREATED_BY|SHARES_DATA_WITH]->(:Profile {profileId:$profileId})
+         } AS isRecipient`,
+        { contractId, profileId }
+    );
+    const access = result.records[0];
+    return {
+        isOwner: access?.get('isOwner') === true,
+        isManager: access?.get('isManager') === true,
+        isRecipient: access?.get('isRecipient') === true,
+    };
+};
+
+const requestManagerWhere = `EXISTS {
+    MATCH (c)-[:CREATED_BY|CAN_WRITE]->(:Profile {profileId:$viewerProfileId})
+}`;
+const requestingRecipientWhere = `r.requestedBy = $viewerProfileId AND EXISTS {
+    MATCH (c)-[:SHARES_DATA_WITH]->(:Profile {profileId:$viewerProfileId})
+}`;
+
+export const getRequestedForList = async (id: string, viewerProfileId: string) => {
+    const query = new QueryBuilder(new BindParam({ viewerProfileId }))
         .match({
             model: ConsentFlowContract,
             identifier: 'c',
             where: { id },
         })
         .match('(c)-[r:REQUESTED_FOR]->(p:Profile)')
-        .return(['p', 'r'])
-        .run();
+        .where(`${requestManagerWhere} OR (${requestingRecipientWhere})`);
+    const result = await query.return(['p', 'r']).run();
 
     return result.records.map(rec => {
         const { p, r } = rec.toObject();
 
         return {
+            ...requestFields(r.properties),
             profile: p.properties,
             status: r.properties?.status ?? null,
             readStatus: r.properties?.readStatus ?? null,
@@ -82,7 +126,9 @@ export const getSharedInsightsRequestsForTargetProfile = async (
                 { identifier: 'writer', model: Profile },
             ],
         })
-        .where("writer.profileId <> $targetProfileId AND r.status IN ['pending', 'accepted']")
+        .where(
+            "writer.profileId <> $targetProfileId AND r.requestId IS NULL AND r.status IN ['pending', 'accepted']"
+        )
         .return(['writer', 'r', 'c'])
         .run();
 
@@ -129,6 +175,7 @@ export const getRequestedForByStatus = async (
         const { p, r } = rec.toObject();
 
         return {
+            ...requestFields(r.properties),
             profile: p.properties,
             status: r.properties?.status ?? null,
             readStatus: r.properties?.readStatus ?? null,
@@ -136,22 +183,29 @@ export const getRequestedForByStatus = async (
     });
 };
 
-export const getRequestedForForUser = async (contractId: string, requesterProfileId: string) => {
-    const result = await new QueryBuilder(new BindParam({ requesterProfileId }))
+export const getRequestedForForUser = async (
+    contractId: string,
+    requesterProfileId: string,
+    viewerProfileId: string
+) => {
+    const query = new QueryBuilder(new BindParam({ requesterProfileId, viewerProfileId }))
         .match({
             model: ConsentFlowContract,
             identifier: 'c',
             where: { id: contractId },
         })
         .match('(c)-[r:REQUESTED_FOR]->(p:Profile)')
-        .where('p.profileId = $requesterProfileId')
-        .return(['p', 'r'])
-        .run();
+        .where(
+            `p.profileId = $requesterProfileId AND
+             (p.profileId = $viewerProfileId OR ${requestManagerWhere} OR (${requestingRecipientWhere}))`
+        );
+    const result = await query.return(['p', 'r']).run();
 
     return result.records.map(rec => {
         const { p, r } = rec.toObject();
 
         return {
+            ...requestFields(r.properties),
             profile: p.properties,
             status: r.properties?.status ?? null,
             readStatus: r.properties?.readStatus ?? null,
@@ -175,9 +229,29 @@ export const getAllRequestsForTargetProfile = async (targetProfileId: string) =>
 
         return {
             contract: c.properties,
+            ...requestFields(r.properties),
             profile: p.properties,
             status: r.properties?.status ?? null,
             readStatus: r.properties?.readStatus ?? null,
         };
     });
 };
+
+export type StoredContractRequest = ContractRequestFields & {
+    status?: 'pending' | 'accepted' | 'denied' | 'cancelled' | null;
+    readStatus?: 'unseen' | 'seen' | null;
+};
+
+export const getStoredContractRequest = async (
+    contractId: string,
+    targetProfileId: string
+): Promise<StoredContractRequest | null> => {
+    const result = await neogma.queryRunner.run(
+        `
+        MATCH (:ConsentFlowContract {id: $contractId})-[request:REQUESTED_FOR]->(:Profile {profileId: $targetProfileId})
+        RETURN request
+    `,
+        { contractId, targetProfileId }
+    );
+    return result.records[0]?.get('request').properties ?? null;
+};

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

@@ -1,8 +1,9 @@
+import { termsReferralSnapshotCypher } from '@helpers/consent-referral.helpers';
+import { appendConsentEvent, tryDispatchContractEvent } from '@helpers/contract-events.helpers';
 import {
     ConsentFlowTerms as ConsentFlowTermsType,
     ConsentFlowTransaction,
     ConsentFlowGuardianApproval,
-    LCNNotificationTypeEnumValidator,
     LCNProfile,
     UnsignedVC,
     VC,
@@ -19,19 +20,22 @@ 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, upsertRequestedForRelationship } from './update';
-import { addNotificationToQueue } from '@helpers/notifications.helpers';
-import { getNotificationMessage } from '@helpers/notificationMessages';
-import { resolveRecipientLocale } from '@helpers/getRecipientLocale.helpers';
-import { sendBoost } from '@helpers/boost.helpers';
-import { getBoostUri } from '@helpers/boost.helpers';
+import { reconsentTerms } from './update';
+import { getBoostUri, sendBoost } from '@helpers/boost.helpers';
+import { setCredentialSubjectIds } from '@helpers/credentialSubject.helpers';
 import { getDidWeb } from '@helpers/did.helpers';
 import { getSigningAuthorityForUserByName } from '@accesslayer/signing-authority/relationships/read';
 import { issueCredentialWithSigningAuthority } from '@helpers/signingAuthority.helpers';
 import { getProfileByProfileId, getProfilesByProfileIds } from '@accesslayer/profile/read';
 import { cloneDeep } from 'lodash';
 import { injectObv3AlignmentsIntoCredentialForBoost } from '@services/skills-provider/inject';
-import { constructUri } from '@helpers/uri.helpers';
+import {
+    lockContractAudience,
+    audienceVersionWhere,
+    consentMutationWhere,
+    assertAudienceMutation,
+    runAudienceMutation,
+} from './recipients';
 
 export const setCreatorForContract = async (contract: DbContractType, profile: LCNProfile) => {
     return ConsentFlowContract.relateTo({
@@ -78,12 +82,18 @@ export const consentToContract = async (
         expiresAt,
         oneTime,
         guardianApproval,
+        audienceVersion,
+        expectedRequestId,
+        smartResumeFingerprint,
     }: {
         terms: ConsentFlowTermsType;
         expiresAt?: string;
         liveSyncing?: boolean;
         oneTime?: boolean;
         guardianApproval?: ConsentFlowGuardianApproval;
+        audienceVersion?: number;
+        expectedRequestId?: string;
+        smartResumeFingerprint?: string;
     },
     domain: string
 ) => {
@@ -125,7 +135,15 @@ export const consentToContract = async (
     if (existing.length > 0) {
         return reconsentTerms(
             { terms: inflateObject(existing[0]!.terms), consenter, contract, contractOwner },
-            { terms, expiresAt, oneTime, guardianApproval },
+            {
+                terms,
+                expiresAt,
+                oneTime,
+                guardianApproval,
+                audienceVersion,
+                smartResumeFingerprint,
+                expectedRequestId,
+            },
             domain
         );
     }
@@ -140,55 +158,95 @@ export const consentToContract = async (
 
     const termsId = uuid();
 
-    const result = await new QueryBuilder(
-        new BindParam({
-            params: flattenObject({ terms, ...(guardianApproval ? { guardianApproval } : {}) }),
-        })
-    )
-        .match({
-            multiple: [
-                {
-                    model: Profile,
-                    where: { profileId: consenter.profileId },
-                    identifier: 'profile',
-                },
-                { model: ConsentFlowContract, where: { id: contract.id }, identifier: 'contract' },
-            ],
-        })
-        .create({
-            related: [
-                { identifier: 'profile' },
-                ConsentFlowTerms.getRelationshipByAlias('createdBy'),
-                {
-                    model: ConsentFlowTerms,
-                    properties: {
-                        id: termsId,
-                        status: oneTime ? 'stale' : 'live',
-                        createdAt: transaction.date,
-                        updatedAt: transaction.date,
-                        ...(expiresAt ? { expiresAt } : {}),
-                        ...(oneTime ? { oneTime } : {}),
-                    },
-                    identifier: 'terms',
-                },
-                ConsentFlowTerms.getRelationshipByAlias('consentsTo'),
-                { identifier: 'contract' },
-            ],
-        })
-        .create({
-            related: [
-                {
-                    identifier: 'transaction',
-                    model: ConsentFlowTransactionModel,
-                    properties: transaction,
-                },
-                ConsentFlowTransactionModel.getRelationshipByAlias('isFor'),
-                { identifier: 'terms' },
-            ],
-        })
-        .set('terms += $params')
-        .set('transaction += $params')
-        .run();
+    const result = await runAudienceMutation(
+        appendConsentEvent(
+            lockContractAudience(
+                new QueryBuilder(
+                    new BindParam({
+                        params: flattenObject({
+                            terms,
+                            ...(smartResumeFingerprint
+                                ? {
+                                      smartResumeFingerprint,
+                                      smartResumePublicationStatus: 'pending',
+                                      smartResumeMutationVersion: 0,
+                                  }
+                                : {}),
+                            ...(guardianApproval ? { guardianApproval } : {}),
+                        }),
+                        audienceVersion: audienceVersion ?? null,
+                        expectedRequestId: expectedRequestId ?? null,
+                        consenterProfileId: consenter.profileId,
+                    })
+                ),
+                contract.id
+            )
+                .where(`${audienceVersionWhere} AND ${consentMutationWhere}`)
+                .set('contract.hasConsented = true')
+                .with('contract')
+                .match({
+                    multiple: [
+                        {
+                            model: Profile,
+                            where: { profileId: consenter.profileId },
+                            identifier: 'profile',
+                        },
+                        {
+                            model: ConsentFlowContract,
+                            where: { id: contract.id },
+                            identifier: 'contract',
+                        },
+                    ],
+                })
+                .where(
+                    'NOT EXISTS { MATCH (profile)-[:CREATED_BY]->(:ConsentFlowTerms)-[:CONSENTS_TO]->(contract) }'
+                )
+                .create({
+                    related: [
+                        { identifier: 'profile' },
+                        ConsentFlowTerms.getRelationshipByAlias('createdBy'),
+                        {
+                            model: ConsentFlowTerms,
+                            properties: {
+                                id: termsId,
+                                status: oneTime ? 'stale' : 'live',
+                                createdAt: transaction.date,
+                                updatedAt: transaction.date,
+                                ...(expiresAt ? { expiresAt } : {}),
+                                ...(oneTime ? { oneTime } : {}),
+                            },
+                            identifier: 'terms',
+                        },
+                        ConsentFlowTerms.getRelationshipByAlias('consentsTo'),
+                        { identifier: 'contract' },
+                    ],
+                })
+                .create({
+                    related: [
+                        {
+                            identifier: 'transaction',
+                            model: ConsentFlowTransactionModel,
+                            properties: transaction,
+                        },
+                        ConsentFlowTransactionModel.getRelationshipByAlias('isFor'),
+                        { identifier: 'terms' },
+                    ],
+                })
+                .set('terms += $params')
+                .set('transaction += $params')
+                .with('terms, contract, transaction'),
+            {
+                consenterProfileId: consenter.profileId,
+                transaction,
+                domain,
+                messageKey:
+                    contract.name === 'AI Insights'
+                        ? 'consentFlowInsightsShared'
+                        : 'consentFlowTransactionCreated',
+            }
+        ).return('terms.id AS id')
+    );
+    assertAudienceMutation(result.records.length);
 
     const autoBoosts = await ConsentFlowContract.findRelationships({
         alias: 'autoReceive',
@@ -238,22 +296,15 @@ export const consentToContract = async (
 
                     boostCredential.issuer = { id: contractOwnerSigningAuthority.relationship.did };
 
-                    boostCredential.boostId = getBoostUri(boost.target.id, domain);
-
-                    if (Array.isArray(boostCredential.credentialSubject)) {
-                        boostCredential.credentialSubject = boostCredential.credentialSubject.map(
-                            subject => ({
-                                ...subject,
-                                id: getDidWeb(domain, consenter.profileId),
-                            })
-                        );
-                    } else {
-                        boostCredential.credentialSubject.id = getDidWeb(
-                            domain,
-                            consenter.profileId
-                        );
+                    if (boostCredential.type.includes('BoostCredential')) {
+                        boostCredential.boostId = getBoostUri(boost.target.id, domain);
                     }
 
+                    setCredentialSubjectIds(
+                        boostCredential,
+                        getDidWeb(domain, consenter.profileId)
+                    );
+
                     // Inject OBv3 skill alignments based on boost's framework/skills
                     await injectObv3AlignmentsIntoCredentialForBoost(
                         boostCredential,
@@ -295,6 +346,7 @@ export const consentToContract = async (
                                 { identifier: 'terms' },
                             ],
                         })
+                        .raw(termsReferralSnapshotCypher('boostTransaction'))
                         .return('terms')
                         .run();
 
@@ -318,43 +370,7 @@ export const consentToContract = async (
         );
     }
 
-    // TODO: Improve notification handling for consent flow contracts
-    // TODO: Replace hardcoded string matching with contract type identification
-    // This should check a contract.type field instead of contract.name
-    const isAiInsights = contract.name === 'AI Insights';
-
-    const notificationMessage = getNotificationMessage(
-        isAiInsights ? 'consentFlowInsightsShared' : 'consentFlowTransactionCreated',
-        resolveRecipientLocale(contractOwner),
-        { consenter: consenter.displayName, contractName: contract.name }
-    );
-
-    const notificationMetadata = isAiInsights
-        ? {
-              type: 'AI Insight',
-              contractId: contract?.id,
-              contractUri: constructUri('contract', contract.id, domain),
-          }
-        : {};
-
-    await addNotificationToQueue({
-        type: LCNNotificationTypeEnumValidator.enum.CONSENT_FLOW_TRANSACTION,
-        from: consenter,
-        to: contractOwner,
-        message: notificationMessage,
-        data: { transaction, metadata: notificationMetadata },
-    });
-
-    try {
-        await upsertRequestedForRelationship(
-            contract.id,
-            consenter.profileId,
-            'accepted',
-            'unseen'
-        );
-    } catch {
-        console.log('Unable to update contract request status');
-    }
+    await tryDispatchContractEvent(transaction.id);
 
     return result.summary.counters.containsUpdates();
 };

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

@@ -21,6 +21,7 @@ export const removeRequestedForRelationship = async (
             identifier: 'profile',
         })
         .match({ optional: true, literal: '(contract)-[r:REQUESTED_FOR]->(profile)' })
+        .where('r.requestId IS NULL')
         .with('r')
         .delete('r')
         .return('r')