@learncard/network-brain-service 3.19.0 → 4.0.0

package/src/helpers/claim-hooks.helpers.ts

@@ -1,4 +1,5 @@
 import { QueryBuilder } from 'neogma';
+import type { Transaction } from 'neo4j-driver';
 
 import { CredentialInstance, Credential, Boost, Profile, ClaimHook, Role } from '@models';
 import { ProfileType } from 'types/profile';
@@ -8,7 +9,8 @@ import { getAdminRole } from '@accesslayer/role/read';
 
 const processPermissionsClaimHooks = async (
     profile: ProfileType,
-    credential: CredentialInstance
+    credential: CredentialInstance,
+    transaction?: Transaction
 ): Promise<void> => {
     await new QueryBuilder()
         .match({
@@ -43,12 +45,13 @@ const processPermissionsClaimHooks = async (
                 { identifier: 'targetBoost' },
             ],
         })
-        .run();
+        .run(transaction);
 };
 
 const processAutoConnectClaimHooks = async (
     profile: ProfileType,
-    credential: CredentialInstance
+    credential: CredentialInstance,
+    transaction?: Transaction
 ): Promise<void> => {
     // For any AUTO_CONNECT claim hooks attached to the boost this credential is an instance of,
     // create an explicit AUTO_CONNECT_RECIPIENT relationship from the target boost to the claiming profile.
@@ -76,12 +79,13 @@ const processAutoConnectClaimHooks = async (
                 Boost.getRelationshipByAlias('autoConnectRecipient').name
             }]->(profile)`
         )
-        .run();
+        .run(transaction);
 };
 
 const processAdminClaimHooks = async (
     profile: ProfileType,
-    credential: CredentialInstance
+    credential: CredentialInstance,
+    transaction?: Transaction
 ): Promise<void> => {
     const adminRole = await getAdminRole();
     await new QueryBuilder()
@@ -115,13 +119,22 @@ const processAdminClaimHooks = async (
                 { identifier: 'targetBoost' },
             ],
         })
-        .run();
+        .run(transaction);
 };
 
 export const processClaimHooks = async (
     profile: ProfileType,
-    credential: CredentialInstance
+    credential: CredentialInstance,
+    transaction?: Transaction
 ): Promise<void> => {
+    if (transaction) {
+        // Keep graph effects in the caller's transaction; cache invalidation follows commit.
+        await processPermissionsClaimHooks(profile, credential, transaction);
+        await processAdminClaimHooks(profile, credential, transaction);
+        await processAutoConnectClaimHooks(profile, credential, transaction);
+        return;
+    }
+
     await Promise.all([
         processPermissionsClaimHooks(profile, credential),
         processAdminClaimHooks(profile, credential),

package/src/helpers/consent-referral.helpers.ts

@@ -0,0 +1,6 @@
+/** Internal aliases only: capture durable attribution on issuance/maintenance transactions. */
+export const termsReferralSnapshotCypher = (transactionAlias = 'transaction'): string => `
+    SET ${transactionAlias}.\`referral.requestId\` = terms.\`referral.requestId\`,
+        ${transactionAlias}.\`referral.requestedBy\` = terms.\`referral.requestedBy\`,
+        ${transactionAlias}.\`referral.externalReferenceId\` = terms.\`referral.externalReferenceId\`
+`;

package/src/helpers/consent-scopes.helpers.ts

@@ -0,0 +1,58 @@
+import { createHash } from 'node:crypto';
+
+import {
+    canonicalConsentScopeString,
+    normalizeConsentRequest,
+} from '@learncard/partner-connect-core';
+import type { ConsentRequest, NormalizedConsentScopes } from '@learncard/partner-connect-core';
+import type { ConsentFlowContract } from '@learncard/types';
+
+const CONSENT_CONTRACT_NAME_MAX_LENGTH = 100;
+
+const toToggle = (): { required: false; defaultEnabled: true } => ({
+    required: false,
+    defaultEnabled: true,
+});
+
+export const normalizeConsentScopes = (request: ConsentRequest): NormalizedConsentScopes => {
+    return normalizeConsentRequest(request);
+};
+
+export const computeConsentScopeHash = (scopes: NormalizedConsentScopes): string => {
+    return createHash('sha256').update(canonicalConsentScopeString(scopes)).digest('hex');
+};
+
+export const buildConsentFlowContractFromScopes = (
+    scopes: NormalizedConsentScopes
+): ConsentFlowContract => {
+    return {
+        read: {
+            credentials: {
+                categories: Object.fromEntries(
+                    scopes.read.credentialCategories.map(category => [category, toToggle()])
+                ),
+            },
+            personal: Object.fromEntries(
+                scopes.read.personalFields.map(field => [field, toToggle()])
+            ),
+        },
+        write: {
+            credentials: {
+                categories: Object.fromEntries(
+                    scopes.write.credentialCategories.map(category => [category, toToggle()])
+                ),
+            },
+            personal: {},
+        },
+    };
+};
+
+export const buildScopedConsentContractName = (listingDisplayName: string): string => {
+    const candidate = `${listingDisplayName} — Data Sharing`;
+
+    if (candidate.length <= CONSENT_CONTRACT_NAME_MAX_LENGTH) {
+        return candidate;
+    }
+
+    return candidate.slice(0, CONSENT_CONTRACT_NAME_MAX_LENGTH).trimEnd();
+};

package/src/helpers/contract-event-maintenance.helpers.ts

@@ -0,0 +1,43 @@
+import { neogma } from '@instance';
+
+export const contractEventMaintenanceSchema = [
+    'CREATE CONSTRAINT consent_event_migration_id IF NOT EXISTS FOR (m:ConsentFlowEventMigration) REQUIRE m.id IS UNIQUE',
+    'CREATE INDEX consent_event_cleanup IF NOT EXISTS FOR (e:ConsentFlowEvent) ON (e.cleanupPending)',
+    'CREATE INDEX consent_delivery_due IF NOT EXISTS FOR (d:ConsentFlowEventDelivery) ON (d.state, d.nextAttemptAt)',
+    'CREATE INDEX consent_delivery_age IF NOT EXISTS FOR (d:ConsentFlowEventDelivery) ON (d.state, d.eventCreatedAt)',
+    'CREATE INDEX consent_delivery_attempts IF NOT EXISTS FOR (d:ConsentFlowEventDelivery) ON (d.state, d.attempts)',
+];
+
+let schemaReady: Promise<void> | undefined;
+
+/** One-time backfill for pre-indexed outbox records; the unique marker serializes workers. */
+export const ensureContractEventMaintenance = async (): Promise<void> => {
+    schemaReady ??= (async (): Promise<void> => {
+        for (const query of contractEventMaintenanceSchema) await neogma.queryRunner.run(query);
+    })().catch(error => {
+        schemaReady = undefined;
+        throw error;
+    });
+    await schemaReady;
+    await neogma.queryRunner.run(`
+        MERGE (migration:ConsentFlowEventMigration {id: 'indexed-outbox-v1'})
+        SET migration.lock = coalesce(migration.lock, 0) + 1
+        WITH migration WHERE migration.completedAt IS NULL
+        CALL {
+            WITH migration
+            MATCH (event:ConsentFlowEvent)
+            WHERE event.payload IS NOT NULL OR event.message IS NOT NULL
+            SET event.cleanupPending = true
+            RETURN count(event) AS marked
+        }
+        CALL {
+            WITH migration
+            MATCH (event:ConsentFlowEvent)-[:HAS_DELIVERY]->(delivery:ConsentFlowEventDelivery)
+            WHERE delivery.state = 'pending'
+            SET delivery.eventCreatedAt = event.createdAt,
+                delivery.attempts = coalesce(delivery.attempts, 0)
+            RETURN count(delivery) AS updated
+        }
+        SET migration.completedAt = toString(datetime())
+    `);
+};