@learncard/network-brain-service 3.18.0 → 3.19.1

package/src/accesslayer/inbox-credential/refresh.ts

@@ -0,0 +1,221 @@
+import { CredentialRefreshRecordValidator } from 'types/credential-refresh';
+import { randomUUID } from 'node:crypto';
+import { TRPCError } from '@trpc/server';
+import { neogma } from '@instance';
+import type { InboxCredentialType, PublishCredentialRefreshResult } from '@learncard/types';
+import { inflateObject } from '@helpers/objects.helpers';
+
+export const getInboxRefreshIssue = async (
+    issueKey: string
+): Promise<{
+    inbox: InboxCredentialType;
+    requestDigest: string;
+    claimUrl?: string;
+} | null> => {
+    const result = await neogma.queryRunner.run(
+        'MATCH (ic:InboxCredential {refreshIssueKey: $issueKey}) RETURN ic LIMIT 1',
+        { issueKey }
+    );
+    const props = result.records[0]?.get('ic')?.properties;
+    return props
+        ? {
+              inbox: inflateObject(props),
+              requestDigest: props.refreshRequestDigest,
+              claimUrl: props.refreshClaimUrl,
+          }
+        : null;
+};
+
+/** Creates the inbox row and unbound aggregate together; a retry cannot allocate a second root. */
+export const createPendingInboxRefresh = async (params: {
+    inbox: Record<string, unknown>;
+    aggregate: Record<string, unknown>;
+    issueKey: string;
+    requestDigest: string;
+}): Promise<InboxCredentialType> => {
+    const result = await neogma.queryRunner.run(
+        `MATCH (issuer:Profile {profileId: $issuerProfileId})
+         MERGE (ic:InboxCredential {refreshIssueKey: $issueKey})
+         ON CREATE SET ic += $inbox, ic.refreshRequestDigest = $requestDigest
+         WITH issuer, ic WHERE ic.refreshRequestDigest = $requestDigest
+         MERGE (refresh:CredentialRefresh {refreshId: ic.refreshId})
+         ON CREATE SET refresh += $aggregate
+         MERGE (issuer)-[:ISSUED_REFRESH]->(refresh)
+         MERGE (refresh)-[:INBOX]->(ic)
+         MERGE (p:InboxRefreshPublication {refreshVersionKey: ic.refreshId + ':1'})
+         ON CREATE SET p.id = ic.refreshId, p.refreshId = ic.refreshId, p.version = 1,
+                       p.publishedAt = ic.createdAt, p.signingMode = 'signing-authority'
+         RETURN ic`,
+        { ...params, issuerProfileId: params.aggregate.issuerProfileId }
+    );
+    const props = result.records[0]?.get('ic')?.properties;
+    if (!props)
+        throw new TRPCError({
+            code: 'CONFLICT',
+            message: 'This idempotencyKey was used for a different inbox issuance.',
+        });
+    return inflateObject<InboxCredentialType>(props);
+};
+
+/** Metadata only. Pending publication bodies live exclusively in the expiring inbox escrow. */
+export const getPendingInboxPublication = async (
+    refreshId: string,
+    idempotencyKey?: string
+): Promise<PublishCredentialRefreshResult | null> => {
+    if (!idempotencyKey) return null;
+    const result = await neogma.queryRunner.run(
+        `MATCH (p:InboxRefreshPublication {refreshIdempotencyKey: $key}) RETURN p LIMIT 1`,
+        { key: `${refreshId}:${idempotencyKey}` }
+    );
+    const props = result.records[0]?.get('p')?.properties;
+    return props
+        ? {
+              refreshId,
+              version: Number(props.version),
+              publishedAt: props.publishedAt,
+              notification: 'not-applicable',
+          }
+        : null;
+};
+
+/** Publication and claim both lock the inbox row, then compare the version they prepared. */
+export const advancePendingInboxRefresh = async (params: {
+    refreshId: string;
+    expectedVersion: number;
+    credential: string;
+    credentialName?: string;
+    materialDigest: string;
+    idempotencyKey?: string;
+    updateSummary?: string;
+}): Promise<PublishCredentialRefreshResult | null> => {
+    const { refreshId, expectedVersion, idempotencyKey } = params;
+    const replay = await getPendingInboxPublication(refreshId, idempotencyKey);
+    if (replay) return replay;
+    const version = expectedVersion + 1;
+    const publishedAt = new Date().toISOString();
+    const result = await neogma.queryRunner.run(
+        `MATCH (refresh:CredentialRefresh {refreshId: $refreshId})-[:INBOX]->(ic:InboxCredential)
+         SET ic._escrowLock = true REMOVE ic._escrowLock
+         WITH refresh, ic
+         WHERE refresh.state = 'pending_holder' AND refresh.currentVersion = $expectedVersion
+           AND ic.currentStatus = 'PENDING' AND datetime(ic.expiresAt) > datetime()
+           AND ($key IS NULL OR NOT EXISTS { MATCH (:InboxRefreshPublication {refreshIdempotencyKey: $key}) })
+         CREATE (p:InboxRefreshPublication $publication)
+         SET ic.credential = $credential, ic.credentialName = $credentialName,
+             refresh.currentVersion = $version, refresh.materialDigest = $materialDigest,
+             refresh.credentialDisplayName = coalesce($credentialName, refresh.credentialDisplayName),
+             refresh.lastPublishedAt = $publishedAt, refresh.updatedAt = $publishedAt,
+             refresh.updateSummary = $updateSummary
+         RETURN p`,
+        {
+            ...params,
+            version,
+            publishedAt,
+            credentialName: params.credentialName ?? null,
+            updateSummary: params.updateSummary ?? null,
+            key: idempotencyKey ? `${refreshId}:${idempotencyKey}` : null,
+            publication: Object.fromEntries(
+                Object.entries({
+                    id: randomUUID(),
+                    refreshId,
+                    version,
+                    refreshVersionKey: `${refreshId}:${version}`,
+                    publishedAt,
+                    signingMode: 'signing-authority',
+                    updateSummary: params.updateSummary,
+                    refreshIdempotencyKey: idempotencyKey
+                        ? `${refreshId}:${idempotencyKey}`
+                        : undefined,
+                }).filter(([, value]) => value !== undefined)
+            ),
+        }
+    );
+    if (!result.records.length) return getPendingInboxPublication(refreshId, idempotencyKey);
+    return { refreshId, version, publishedAt, notification: 'not-applicable' };
+};
+
+/** Single commit: holder binding, canonical delivery, current version, and escrow erasure. */
+export const bindPendingInboxRefresh = async (params: {
+    inboxId: string;
+    refreshId: string;
+    expectedVersion: number;
+    holderDid: string;
+    holderProfileId?: string;
+    issuerProfileId: string;
+    root: Record<string, unknown>;
+    aggregate: Record<string, unknown>;
+    deliveryCredential: string;
+    deliveryExpiresAt: string;
+    accepted: boolean;
+    boostId?: string;
+}): Promise<boolean> => {
+    const now = new Date().toISOString();
+    const result = await neogma.queryRunner.run(
+        `MATCH (refresh:CredentialRefresh {refreshId: $refreshId})-[:INBOX]->(ic:InboxCredential {id: $inboxId})
+         SET ic._escrowLock = true REMOVE ic._escrowLock
+         WITH refresh, ic
+         WHERE refresh.state = 'pending_holder' AND refresh.currentVersion = $expectedVersion
+           AND ic.currentStatus = 'PENDING' AND datetime(ic.expiresAt) > datetime()
+           AND (ic.guardianStatus IS NULL OR ic.guardianStatus = 'GUARDIAN_APPROVED')
+         MATCH (issuer:Profile {profileId: $issuerProfileId})
+         OPTIONAL MATCH (holder:Profile {profileId: $holderProfileId})
+         OPTIONAL MATCH (boost:Boost {id: $boostId})
+         CREATE (root:Credential $root)
+         CREATE (refresh)-[:ROOT]->(root)
+         CREATE (refresh)-[:HEAD]->(root)
+         CREATE (issuer)-[:CREDENTIAL_SENT {to: $deliveryTarget, date: $now, activityId: ic.activityId, integrationId: ic.integrationId}]->(root)
+         FOREACH (_ IN CASE WHEN holder IS NULL THEN [] ELSE [1] END |
+             CREATE (holder)-[:HELD_REFRESH]->(refresh))
+         FOREACH (_ IN CASE WHEN holder IS NOT NULL AND $accepted THEN [1] ELSE [] END |
+             CREATE (root)-[:CREDENTIAL_RECEIVED {date: $now}]->(holder))
+         FOREACH (_ IN CASE WHEN boost IS NULL THEN [] ELSE [1] END |
+             CREATE (root)-[:INSTANCE_OF]->(boost))
+         SET refresh += $aggregate,
+             refresh.holderDid = $holderDid, refresh.holderProfileId = $holderProfileId,
+             refresh.state = CASE WHEN $accepted THEN 'active' ELSE 'awaiting_claim' END,
+             refresh.updatedAt = $now,
+             ic.currentStatus = 'ISSUED', ic.isAccepted = $accepted, ic.finalizedAt = $now,
+             ic.credential = null, ic.credentialName = null, ic.achievementType = null,
+             ic.deliveryCredential = $deliveryCredential, ic.deliveryRecipientDid = $holderDid,
+             ic.deliveryExpiresAt = $deliveryExpiresAt
+         RETURN root.id AS id`,
+        {
+            ...params,
+            now,
+            holderProfileId: params.holderProfileId ?? null,
+            boostId: params.boostId ?? null,
+            deliveryTarget: params.holderProfileId ?? params.holderDid,
+        }
+    );
+    return result.records.length > 0;
+};
+
+/** A read snapshot under the same inbox lock used by publish/claim, preventing mixed revisions. */
+export const getInboxRefreshSnapshot = async (inboxId: string) => {
+    const result = await neogma.queryRunner.run(
+        `MATCH (refresh:CredentialRefresh)-[:INBOX]->(ic:InboxCredential {id: $inboxId})
+         SET ic._escrowLock = true REMOVE ic._escrowLock
+         RETURN ic, refresh LIMIT 1`,
+        { inboxId }
+    );
+    const row = result.records[0];
+    if (!row) return null;
+    const props = row.get('refresh').properties;
+    return {
+        inbox: inflateObject<InboxCredentialType>(row.get('ic').properties),
+        aggregate: CredentialRefreshRecordValidator.parse({
+            ...props,
+            currentVersion: Number(props.currentVersion),
+        }),
+    };
+};
+
+export const recordInboxRefreshClaimUrl = async (id: string, claimUrl: string): Promise<string> => {
+    const result = await neogma.queryRunner.run(
+        `MATCH (ic:InboxCredential {id: $id})
+         SET ic.refreshClaimUrl = coalesce(ic.refreshClaimUrl, $claimUrl)
+         RETURN ic.refreshClaimUrl AS claimUrl`,
+        { id, claimUrl }
+    );
+    return result.records[0]!.get('claimUrl');
+};

package/src/accesslayer/inbox-credential/update.ts

@@ -10,7 +10,7 @@ import {
 
 export const updateInboxCredential = async (
     id: string,
-    updates: Partial<Omit<InboxCredentialType, 'id' | 'createdAt' | 'credential'>>
+    updates: Partial<Omit<InboxCredentialType, 'id' | 'createdAt' | 'credential' | 'refresh'>>
 ): Promise<InboxCredentialType | null> => {
     const result = await new QueryBuilder(new BindParam({ id, updates: flattenObject(updates) }))
         .match({ model: InboxCredential, identifier: 'inboxCredential' })

package/src/accesslayer/presentation/read.ts

@@ -14,6 +14,12 @@ import { PresentationType } from 'types/presentation';
 import { ProfileType } from 'types/profile';
 import { convertQueryResultToPropertiesObjectArray } from '@helpers/neo4j.helpers';
 import { getIdFromUri } from '@helpers/uri.helpers';
+import { inflateObject } from '@helpers/objects.helpers';
+
+const inflateRelationshipProperties = (
+    properties: Record<string, unknown>
+): Record<string, unknown> & { metadata?: Record<string, unknown> } =>
+    inflateObject(properties) as Record<string, unknown> & { metadata?: Record<string, unknown> };
 
 export const getPresentationById = async (id: string): Promise<PresentationInstance | null> => {
     return Presentation.findOne({ where: { id } });
@@ -56,8 +62,8 @@ export const getReceivedPresentationsForProfile = async (
     const query =
         from && from.length > 0
             ? matchQuery.where(
-                new Where({ source: { profileId: { [Op.in]: from } } }, matchQuery.getBindParam())
-            )
+                  new Where({ source: { profileId: { [Op.in]: from } } }, matchQuery.getBindParam())
+              )
             : matchQuery;
 
     const results = convertQueryResultToPropertiesObjectArray<{
@@ -66,13 +72,22 @@ export const getReceivedPresentationsForProfile = async (
         received: PresentationRelationships['presentationReceived']['RelationshipProperties'];
     }>(await query.return('sent, presentation, received').limit(limit).run());
 
-    return results.map(({ sent, presentation, received }) => ({
-        uri: getPresentationUri(presentation.id, domain),
-        to: sent.to,
-        from: received.from,
-        sent: sent.date,
-        received: received.date,
-    }));
+    return results.map(({ sent, presentation, received }) => {
+        const sentProps = inflateRelationshipProperties(sent as unknown as Record<string, unknown>);
+        const receivedProps = inflateRelationshipProperties(
+            received as unknown as Record<string, unknown>
+        );
+
+        return {
+            uri: getPresentationUri(presentation.id, domain),
+            to: sentProps.to as string,
+            from: receivedProps.from as string,
+            sent: sentProps.date as string,
+            received: receivedProps.date as string,
+            metadata: (receivedProps.metadata ?? sentProps.metadata) as
+                Record<string, unknown> | undefined,
+        };
+    });
 };
 
 export const getSentPresentationsForProfile = async (
@@ -101,8 +116,8 @@ export const getSentPresentationsForProfile = async (
     const whereQuery =
         to && to.length > 0
             ? matchQuery.where(
-                new Where({ sent: { to: { [Op.in]: to } } }, matchQuery.getBindParam())
-            )
+                  new Where({ sent: { to: { [Op.in]: to } } }, matchQuery.getBindParam())
+              )
             : matchQuery;
 
     const query = whereQuery.match({
@@ -124,13 +139,22 @@ export const getSentPresentationsForProfile = async (
         received?: PresentationRelationships['presentationReceived']['RelationshipProperties'];
     }>(await query.return('source, sent, presentation, received').limit(limit).run());
 
-    return results.map(({ source, sent, presentation, received }) => ({
-        uri: getPresentationUri(presentation.id, domain),
-        to: sent.to,
-        from: source.profileId,
-        sent: sent.date,
-        received: received?.date,
-    }));
+    return results.map(({ source, sent, presentation, received }) => {
+        const sentProps = inflateRelationshipProperties(sent as unknown as Record<string, unknown>);
+        const receivedProps = received
+            ? inflateRelationshipProperties(received as unknown as Record<string, unknown>)
+            : undefined;
+
+        return {
+            uri: getPresentationUri(presentation.id, domain),
+            to: sentProps.to as string,
+            from: source.profileId,
+            sent: sentProps.date as string,
+            received: receivedProps?.date as string | undefined,
+            metadata: (sentProps.metadata ?? receivedProps?.metadata) as
+                Record<string, unknown> | undefined,
+        };
+    });
 };
 
 export const getIncomingPresentationsForProfile = async (
@@ -168,7 +192,8 @@ export const getIncomingPresentationsForProfile = async (
             })
             // Don't return presentations that have been accepted
             .where(
-                `NOT (presentation)-[:PRESENTATION_RECEIVED]->()${whereFrom ? `AND ${whereFrom.getStatement('text')}` : ''
+                `NOT (presentation)-[:PRESENTATION_RECEIVED]->()${
+                    whereFrom ? `AND ${whereFrom.getStatement('text')}` : ''
                 }`
             )
             .return('source, relationship, presentation')
@@ -176,10 +201,17 @@ export const getIncomingPresentationsForProfile = async (
             .run()
     );
 
-    return results.map(({ source, relationship, presentation }) => ({
-        uri: getPresentationUri(presentation.id, domain),
-        to: relationship.to,
-        from: source.profileId,
-        sent: relationship.date,
-    }));
+    return results.map(({ source, relationship, presentation }) => {
+        const relationshipProps = inflateRelationshipProperties(
+            relationship as unknown as Record<string, unknown>
+        );
+
+        return {
+            uri: getPresentationUri(presentation.id, domain),
+            to: relationshipProps.to as string,
+            from: source.profileId,
+            sent: relationshipProps.date as string,
+            metadata: relationshipProps.metadata,
+        };
+    });
 };

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

@@ -1,26 +1,69 @@
-import { PresentationInstance, Profile } from '@models';
+import { BindParam, QueryBuilder } from 'neogma';
+
+import { Presentation, PresentationInstance, Profile } from '@models';
+import { flattenObject } from '@helpers/objects.helpers';
 import { ProfileType } from 'types/profile';
 
 export const createSentPresentationRelationship = async (
     from: ProfileType,
     to: ProfileType,
-    presentation: PresentationInstance
+    presentation: PresentationInstance,
+    metadata?: Record<string, unknown>
 ): Promise<void> => {
-    await Profile.relateTo({
-        alias: 'presentationSent',
-        where: { source: { profileId: from.profileId }, target: { id: presentation.id } },
-        properties: { to: to.profileId, date: new Date().toISOString() },
+    const properties = flattenObject({
+        to: to.profileId,
+        date: new Date().toISOString(),
+        ...(metadata ? { metadata } : {}),
     });
+
+    await new QueryBuilder(new BindParam({ params: properties }))
+        .match({
+            related: [
+                { model: Profile, where: { profileId: from.profileId }, identifier: 'profile' },
+            ],
+        })
+        .match({
+            related: [
+                { model: Presentation, where: { id: presentation.id }, identifier: 'presentation' },
+            ],
+        })
+        .create(
+            `(profile)-[relationship:${
+                Profile.getRelationshipByAlias('presentationSent').name
+            }]->(presentation)`
+        )
+        .set('relationship = $params')
+        .run();
 };
 
 export const createReceivedPresentationRelationship = async (
     to: ProfileType,
     from: ProfileType,
-    presentation: PresentationInstance
+    presentation: PresentationInstance,
+    metadata?: Record<string, unknown>
 ): Promise<void> => {
-    await presentation.relateTo({
-        alias: 'presentationReceived',
-        where: { profileId: to.profileId },
-        properties: { from: from.profileId, date: new Date().toISOString() },
+    const properties = flattenObject({
+        from: from.profileId,
+        date: new Date().toISOString(),
+        ...(metadata ? { metadata } : {}),
     });
+
+    await new QueryBuilder(new BindParam({ params: properties }))
+        .match({
+            related: [
+                { model: Presentation, where: { id: presentation.id }, identifier: 'presentation' },
+            ],
+        })
+        .match({
+            related: [
+                { model: Profile, where: { profileId: to.profileId }, identifier: 'profile' },
+            ],
+        })
+        .create(
+            `(presentation)-[relationship:${
+                Presentation.getRelationshipByAlias('presentationReceived').name
+            }]->(profile)`
+        )
+        .set('relationship = $params')
+        .run();
 };

package/src/accesslayer/presentation/relationships/read.ts

@@ -2,15 +2,26 @@ import { inflateObject } from '@helpers/objects.helpers';
 import { Presentation, PresentationInstance, Profile, ProfileRelationships } from '@models';
 import { ProfileType } from 'types/profile';
 
+const relationshipProperties = (value: unknown): Record<string, unknown> => {
+    if (value && typeof value === 'object' && 'dataValues' in value) {
+        const { dataValues } = value as { dataValues?: unknown };
+        if (dataValues && typeof dataValues === 'object') {
+            return dataValues as Record<string, unknown>;
+        }
+    }
+
+    return value as Record<string, unknown>;
+};
+
 export const getPresentationSentToProfile = async (
     id: string,
     to: ProfileType
 ): Promise<
     | {
-        source: ProfileType;
-        relationship: ProfileRelationships['presentationSent']['RelationshipProperties'];
-        target: PresentationInstance;
-    }
+          source: ProfileType;
+          relationship: ProfileRelationships['presentationSent']['RelationshipProperties'];
+          target: PresentationInstance;
+      }
     | undefined
 > => {
     const data = (
@@ -22,7 +33,11 @@ export const getPresentationSentToProfile = async (
 
     if (!data) return undefined;
 
-    return { ...data, source: inflateObject(data.source.dataValues as any) };
+    return {
+        ...data,
+        source: inflateObject(data.source.dataValues as unknown as Record<string, unknown>),
+        relationship: inflateObject(relationshipProperties(data.relationship)),
+    };
 };
 
 export const getPresentationOwner = async (
@@ -39,7 +54,7 @@ export const getPresentationOwner = async (
 
     if (!owner) return undefined;
 
-    return inflateObject<ProfileType>(owner.dataValues as any);
+    return inflateObject(owner.dataValues as unknown as Record<string, unknown>) as ProfileType;
 };
 
 export const getPresentationReceivedByProfile = async (

package/src/accesslayer/share-link/abandon.ts

@@ -0,0 +1,100 @@
+import { ensureShareLinkConstraints } from '../../models/share-link-constraints';
+import { failShareLink } from './errors';
+import {
+    deleteReservation,
+    enqueueCleanupJob,
+    lockShare,
+    markOperationAbandoned,
+    readReservation,
+    toShareLinkRecord,
+    toShareLinkReservationRecord,
+} from './helpers';
+import { withShareLinkTransaction } from './transaction';
+import type { AbandonReservationInput, AbandonReservationResult } from './types';
+
+/**
+ * Irreversibly abandons a reservation.
+ *
+ * The operation transitions to cleanup-only: its exact immutable object is queued
+ * for tracked cleanup and the reservation is deleted, so a late finalize for the
+ * same operation is rejected. A stale worker can never abandon a newer reservation
+ * because the operation id (and, when supplied, generation/lease owner) must match.
+ *
+ * When the reservation is already gone but the share records this operation as the
+ * committed one, abandon reports `already_finalized` instead of pretending to have
+ * cleaned up live content.
+ */
+export const abandonReservation = async (
+    input: AbandonReservationInput
+): Promise<AbandonReservationResult> => {
+    await ensureShareLinkConstraints();
+
+    const now = input.now ?? new Date();
+    const nowIso = now.toISOString();
+
+    return withShareLinkTransaction(async tx => {
+        const lockedProps = await lockShare(tx, input.shareId);
+
+        if (!lockedProps) {
+            failShareLink('NOT_FOUND', 'share not found');
+        }
+
+        const share = toShareLinkRecord(lockedProps);
+
+        if (share.namespace !== input.namespace || share.ownerProfileId !== input.ownerProfileId) {
+            failShareLink('NOT_FOUND', 'share not found');
+        }
+
+        const reservationProps = await readReservation(tx, input.shareId);
+
+        if (!reservationProps) {
+            if (share.lastOperationId === input.operationId) {
+                return { outcome: 'already_finalized', share };
+            }
+
+            return { outcome: 'already_absent' };
+        }
+
+        const reservation = toShareLinkReservationRecord(reservationProps);
+
+        if (reservation.operationId !== input.operationId) {
+            return { outcome: 'already_absent' };
+        }
+
+        if (input.generation !== undefined && reservation.generation !== input.generation) {
+            return { outcome: 'already_absent' };
+        }
+
+        if (input.leaseOwner !== undefined && reservation.leaseOwner !== input.leaseOwner) {
+            return { outcome: 'already_absent' };
+        }
+
+        let cleanupQueuedFor: string | null = null;
+
+        if (reservation.objectRef) {
+            await enqueueCleanupJob(tx, {
+                objectRef: reservation.objectRef,
+                operationId: reservation.operationId,
+                namespace: reservation.namespace,
+                ownerProfileId: reservation.ownerProfileId,
+                shareId: reservation.shareId,
+                contentVersion: reservation.contentVersion ?? reservation.baseContentVersion,
+                reason: 'abandoned',
+                now: nowIso,
+            });
+
+            cleanupQueuedFor = reservation.objectRef;
+        }
+
+        await markOperationAbandoned(tx, {
+            namespace: reservation.namespace,
+            ownerProfileId: reservation.ownerProfileId,
+            opKind: reservation.opKind,
+            clientRequestId: reservation.clientRequestId,
+            now: nowIso,
+        });
+        await deleteReservation(tx, input.shareId);
+
+        return { outcome: 'abandoned', cleanupQueuedFor };
+    });
+};