@learncard/network-brain-service 3.19.1 → 4.0.0

package/src/helpers/app-manifest.helpers.ts

@@ -0,0 +1,185 @@
+import { createHash } from 'node:crypto';
+
+import { canonicalConsentScopeString, canonicalJsonString } from '@learncard/partner-connect-core';
+import type { NormalizedConsentScopes } from '@learncard/partner-connect-core';
+import type { AppManifest, AppManifestDiff, AppManifestTemplateRef } from '@learncard/types';
+
+const sortStrings = <T extends string>(values: T[]): T[] =>
+    Array.from(new Set(values)).sort() as T[];
+
+const normalizeTemplateRecord = (template: AppManifest['templates'][number]) => ({
+    alias: template.alias,
+    template: template.template,
+    version: template.version,
+});
+
+const normalizeConsentRecord = (
+    record: AppManifest['consentRequests'][number]
+): { scopes: NormalizedConsentScopes; reason?: string } => ({
+    scopes: {
+        read: {
+            credentialCategories: sortStrings(record.scopes.read.credentialCategories),
+            personalFields: sortStrings(record.scopes.read.personalFields),
+        },
+        write: {
+            credentialCategories: sortStrings(record.scopes.write.credentialCategories),
+        },
+    },
+    ...(record.reason ? { reason: record.reason } : {}),
+});
+
+const normalizeManifestForHash = (manifest: AppManifest): Record<string, unknown> => ({
+    manifestVersion: manifest.manifestVersion,
+    appUrl: manifest.appUrl,
+    ...(manifest.suggestedName ? { suggestedName: manifest.suggestedName } : {}),
+    ...(manifest.suggestedIconUrl ? { suggestedIconUrl: manifest.suggestedIconUrl } : {}),
+    permissions: sortStrings(manifest.permissions),
+    templates: [...manifest.templates]
+        .map(normalizeTemplateRecord)
+        .sort((a, b) => a.alias.localeCompare(b.alias) || a.version - b.version),
+    consentRequests: [...manifest.consentRequests]
+        .map(normalizeConsentRecord)
+        .sort((a, b) =>
+            canonicalConsentScopeString(a.scopes).localeCompare(
+                canonicalConsentScopeString(b.scopes)
+            )
+        ),
+    featuresLaunched: sortStrings(manifest.featuresLaunched),
+    counterKeys: sortStrings(manifest.counterKeys),
+    usedLearnerContext: manifest.usedLearnerContext,
+    usedNotifications: manifest.usedNotifications,
+});
+
+const buildStringDiff = (current: string[], next: string[]) => {
+    const currentSet = new Set(current);
+    const nextSet = new Set(next);
+
+    return {
+        added: sortStrings(next.filter(value => !currentSet.has(value))),
+        removed: sortStrings(current.filter(value => !nextSet.has(value))),
+        changed: [] as string[],
+    };
+};
+
+const templateSignature = (template: AppManifest['templates'][number]): string => {
+    return canonicalJsonString({ template: template.template, version: template.version });
+};
+
+const toTemplateRef = (template: AppManifest['templates'][number]): AppManifestTemplateRef => ({
+    alias: template.alias,
+    version: template.version,
+});
+
+const getConsentExpansionSurface = (
+    manifest: AppManifest
+): {
+    readCredentialCategories: Set<string>;
+    readPersonalFields: Set<string>;
+    writeCredentialCategories: Set<string>;
+} => {
+    const readCredentialCategories = new Set<string>();
+    const readPersonalFields = new Set<string>();
+    const writeCredentialCategories = new Set<string>();
+
+    for (const request of manifest.consentRequests) {
+        request.scopes.read.credentialCategories.forEach(category =>
+            readCredentialCategories.add(category)
+        );
+        request.scopes.read.personalFields.forEach(field => readPersonalFields.add(field));
+        request.scopes.write.credentialCategories.forEach(category =>
+            writeCredentialCategories.add(category)
+        );
+    }
+
+    return {
+        readCredentialCategories,
+        readPersonalFields,
+        writeCredentialCategories,
+    };
+};
+
+const isConsentExpanded = (current: AppManifest, next: AppManifest): boolean => {
+    const currentSurface = getConsentExpansionSurface(current);
+    const nextSurface = getConsentExpansionSurface(next);
+
+    return (
+        [...nextSurface.readCredentialCategories].some(
+            category => !currentSurface.readCredentialCategories.has(category)
+        ) ||
+        [...nextSurface.readPersonalFields].some(
+            field => !currentSurface.readPersonalFields.has(field)
+        ) ||
+        [...nextSurface.writeCredentialCategories].some(
+            category => !currentSurface.writeCredentialCategories.has(category)
+        )
+    );
+};
+
+export const canonicalizeManifest = (manifest: AppManifest): string => {
+    return canonicalJsonString(normalizeManifestForHash(manifest));
+};
+
+export const hashManifest = (manifest: AppManifest): string => {
+    return createHash('sha256').update(canonicalizeManifest(manifest)).digest('hex');
+};
+
+export const diffManifests = (current: AppManifest, next: AppManifest): AppManifestDiff => {
+    const currentTemplates = new Map(current.templates.map(template => [template.alias, template]));
+    const nextTemplates = new Map(next.templates.map(template => [template.alias, template]));
+
+    const addedTemplates: AppManifestTemplateRef[] = [];
+    const removedTemplates: AppManifestTemplateRef[] = [];
+    const changedTemplates: AppManifestDiff['templates']['changed'] = [];
+
+    for (const [alias, template] of nextTemplates.entries()) {
+        const existing = currentTemplates.get(alias);
+
+        if (!existing) {
+            addedTemplates.push(toTemplateRef(template));
+            continue;
+        }
+
+        if (templateSignature(existing) !== templateSignature(template)) {
+            changedTemplates.push({
+                alias,
+                fromVersion: existing.version,
+                toVersion: template.version,
+            });
+        }
+    }
+
+    for (const [alias, template] of currentTemplates.entries()) {
+        if (!nextTemplates.has(alias)) {
+            removedTemplates.push(toTemplateRef(template));
+        }
+    }
+
+    const permissionDiff = buildStringDiff(current.permissions, next.permissions);
+    const consentScopeDiff = buildStringDiff(
+        current.consentRequests.map(record =>
+            canonicalConsentScopeString(normalizeConsentRecord(record).scopes)
+        ),
+        next.consentRequests.map(record =>
+            canonicalConsentScopeString(normalizeConsentRecord(record).scopes)
+        )
+    );
+
+    return {
+        permissions: permissionDiff,
+        templates: {
+            added: addedTemplates.sort(
+                (a, b) => a.alias.localeCompare(b.alias) || a.version - b.version
+            ),
+            removed: removedTemplates.sort(
+                (a, b) => a.alias.localeCompare(b.alias) || a.version - b.version
+            ),
+            changed: changedTemplates.sort(
+                (a, b) => a.alias.localeCompare(b.alias) || a.toVersion - b.toVersion
+            ),
+        },
+        consentScopes: consentScopeDiff,
+        featurePaths: buildStringDiff(current.featuresLaunched, next.featuresLaunched),
+        counterKeys: buildStringDiff(current.counterKeys, next.counterKeys),
+        requiresReview: permissionDiff.added.length > 0 || isConsentExpanded(current, next),
+    };
+};

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())
+    `);
+};