@learncard/network-brain-service 3.18.0 → 3.19.1

package/shareLinkMaintenanceLambda.ts

@@ -0,0 +1,49 @@
+import type { Context } from 'aws-lambda';
+
+import {
+    createShareLinkMaintenanceRuntime,
+    type ShareLinkMaintenanceRuntime,
+} from './src/helpers/share-link-maintenance';
+
+/**
+ * Dedicated LC-2187 share-link maintenance Lambda entrypoint.
+ *
+ * It deliberately does NOT import `lambda.ts`, so no unrelated embedding
+ * backfill, tRPC router, Sentry input capture or inbox handler runs at import
+ * time. The only side effect is resolving the service and maintenance
+ * configuration; when it is absent or malformed the runtime is inert and the
+ * handler performs no graph, remote or signing work.
+ *
+ * The scheduled event payload is ignored entirely: it can never override the
+ * namespace, origin, audience or any other configuration, and it is never
+ * logged.
+ */
+
+let runtime: ShareLinkMaintenanceRuntime | null = null;
+
+const getRuntime = (): ShareLinkMaintenanceRuntime => {
+    if (runtime === null) {
+        runtime = createShareLinkMaintenanceRuntime({
+            rawEnvironment: process.env as Record<string, unknown>,
+        });
+    }
+
+    return runtime;
+};
+
+export const shareLinkMaintenanceHandler = async (
+    _event: unknown,
+    context?: Pick<Context, 'getRemainingTimeInMillis'>
+): Promise<{ status: string }> => {
+    const hasRemainingTime = typeof context?.getRemainingTimeInMillis === 'function';
+
+    const summary = await getRuntime().runOnce({
+        // Preserve the LIVE Lambda remaining-time source: the runtime samples it
+        // once, before dependency initialization, and anchors the invocation
+        // budget to that instant.
+        remainingTimeMs: hasRemainingTime ? () => context!.getRemainingTimeInMillis() : undefined,
+    });
+
+    // The runtime already emitted one aggregate-only allowlisted event.
+    return { status: summary.status };
+};

package/src/accesslayer/auth-grant/read.ts

@@ -98,7 +98,7 @@ export const isAuthGrantAssociatedWithProfile = async (
 export const isAuthGrantChallengeValidForDID = async (
     challenge: string,
     did: string
-): Promise<{ isChallengeValid: boolean; scope: string }> => {
+): Promise<{ isChallengeValid: boolean; scope: string; actAs?: string }> => {
     // TODO: Ideally, this transformation isn't required and we could use DID directly.
     const profileId = getProfileIdFromDid(did);
     if (!profileId) return { isChallengeValid: false, scope: AUTH_GRANT_NO_ACCESS_SCOPE };
@@ -126,5 +126,6 @@ export const isAuthGrantChallengeValidForDID = async (
     return {
         isChallengeValid: result.records.length > 0,
         scope: authGrant?.scope || AUTH_GRANT_NO_ACCESS_SCOPE,
+        actAs: authGrant?.actAs,
     };
 };

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

@@ -23,8 +23,8 @@ 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 { 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';
@@ -238,22 +238,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,

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

@@ -17,6 +17,7 @@ import { getNotificationMessage } from '@helpers/notificationMessages';
 import { resolveRecipientLocale } from '@helpers/getRecipientLocale.helpers';
 import { DbContractType, DbTermsType } from 'types/consentflowcontract';
 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';
@@ -154,22 +155,15 @@ export const reconsentTerms = async (
                     // Set the issuer and subject
                     boostCredential.issuer = { id: contractOwnerSigningAuthority.relationship.did };
 
-                    boostCredential.boostId = getBoostUri(boost.dataValues.id, domain);
-
-                    if (Array.isArray(boostCredential.credentialSubject)) {
-                        boostCredential.credentialSubject = boostCredential.credentialSubject.map(
-                            subject => ({
-                                ...subject,
-                                id: getDidWeb(domain, relationship.consenter.profileId),
-                            })
-                        );
-                    } else {
-                        boostCredential.credentialSubject.id = getDidWeb(
-                            domain,
-                            relationship.consenter.profileId
-                        );
+                    if (boostCredential.type.includes('BoostCredential')) {
+                        boostCredential.boostId = getBoostUri(boost.dataValues.id, domain);
                     }
 
+                    setCredentialSubjectIds(
+                        boostCredential,
+                        getDidWeb(domain, relationship.consenter.profileId)
+                    );
+
                     // Issue the credential using contract owner's signing authority
                     // Inject OBv3 skill alignments based on boost's framework/skills
                     await injectObv3AlignmentsIntoCredentialForBoost(
@@ -384,22 +378,15 @@ export const updateTerms = async (
                     // Set the issuer and subject
                     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, relationship.consenter.profileId),
-                            })
-                        );
-                    } else {
-                        boostCredential.credentialSubject.id = getDidWeb(
-                            domain,
-                            relationship.consenter.profileId
-                        );
+                    if (boostCredential.type.includes('BoostCredential')) {
+                        boostCredential.boostId = getBoostUri(boost.target.id, domain);
                     }
 
+                    setCredentialSubjectIds(
+                        boostCredential,
+                        getDidWeb(domain, relationship.consenter.profileId)
+                    );
+
                     // Issue the credential using contract owner's signing authority
                     // Inject OBv3 skill alignments based on boost's framework/skills
                     await injectObv3AlignmentsIntoCredentialForBoost(

package/src/accesslayer/credential-activity/create.ts

@@ -23,6 +23,7 @@ export const createCredentialActivity = async (
         eventType: params.eventType,
         timestamp,
         actorProfileId: params.actorProfileId,
+        onBehalfOf: params.onBehalfOf,
         recipientType: params.recipientType,
         recipientIdentifier: params.recipientIdentifier,
         boostUri: params.boostUri,

package/src/accesslayer/credential-refresh/email-delivery.ts

@@ -0,0 +1,116 @@
+import { neogma } from '@instance';
+
+/**
+ * Persisted, unique claim per (refreshId, delivery window) for the managed
+ * credential-refresh update email (LC-2198).
+ *
+ * Why a dedicated node instead of a conditional property write: Neo4j's
+ * read-committed isolation does not re-evaluate a `WHERE` after a write lock is
+ * acquired, so two concurrent `SET ... WHERE windowKey <> $key` statements can
+ * both "win" and send two emails. A unique constraint on `deliveryKey` makes the
+ * claim a hard single-writer: exactly one `CREATE` succeeds, every loser observes
+ * a constraint violation and skips.
+ *
+ * This gives at-most-once email delivery per configured window. A send that fails
+ * after the claim is recorded as `failed` and is NOT retried inside the same
+ * window (see `credential-refresh-email.helpers.ts` for the explicit policy).
+ */
+
+export type CredentialRefreshEmailDeliveryState = 'claimed' | 'delivered' | 'failed';
+
+const deliveryKeyFor = (refreshId: string, windowKey: string): string =>
+    `${refreshId}:${windowKey}`;
+
+const isUniqueConstraintViolation = (error: unknown): boolean => {
+    const code = (error as { code?: string })?.code;
+
+    return (
+        code === 'Neo.ClientError.Schema.ConstraintValidationFailed' ||
+        (error instanceof Error && error.message.includes('already exists'))
+    );
+};
+
+/**
+ * Attempts to claim the email delivery window. Returns `'claimed'` for the single
+ * winner and `'duplicate'` for every concurrent or retried caller.
+ */
+export const claimCredentialRefreshEmailDelivery = async (params: {
+    refreshId: string;
+    windowKey: string;
+}): Promise<'claimed' | 'duplicate'> => {
+    const { refreshId, windowKey } = params;
+    const now = new Date().toISOString();
+
+    try {
+        await neogma.queryRunner.run(
+            `CREATE (delivery:CredentialRefreshEmailDelivery {
+                 deliveryKey: $deliveryKey,
+                 refreshId: $refreshId,
+                 windowKey: $windowKey,
+                 state: 'claimed',
+                 attempts: 1,
+                 createdAt: $now,
+                 updatedAt: $now
+             })`,
+            {
+                deliveryKey: deliveryKeyFor(refreshId, windowKey),
+                refreshId,
+                windowKey,
+                now,
+            }
+        );
+
+        return 'claimed';
+    } catch (error) {
+        if (isUniqueConstraintViolation(error)) return 'duplicate';
+
+        throw error;
+    }
+};
+
+/** Records the terminal outcome of a claimed delivery attempt. */
+export const finalizeCredentialRefreshEmailDelivery = async (params: {
+    refreshId: string;
+    windowKey: string;
+    state: Extract<CredentialRefreshEmailDeliveryState, 'delivered' | 'failed'>;
+}): Promise<void> => {
+    const { refreshId, windowKey, state } = params;
+    const now = new Date().toISOString();
+
+    await neogma.queryRunner.run(
+        `MATCH (delivery:CredentialRefreshEmailDelivery {deliveryKey: $deliveryKey})
+         SET delivery.state = $state, delivery.updatedAt = $now`,
+        { deliveryKey: deliveryKeyFor(refreshId, windowKey), state, now }
+    );
+};
+
+/** Reads a delivery record for observability and tests. */
+export const getCredentialRefreshEmailDelivery = async (
+    refreshId: string,
+    windowKey: string
+): Promise<{
+    deliveryKey: string;
+    refreshId: string;
+    windowKey: string;
+    state: CredentialRefreshEmailDeliveryState;
+    attempts: number;
+} | null> => {
+    const result = await neogma.queryRunner.run(
+        `MATCH (delivery:CredentialRefreshEmailDelivery {deliveryKey: $deliveryKey})
+         RETURN delivery LIMIT 1`,
+        { deliveryKey: deliveryKeyFor(refreshId, windowKey) }
+    );
+    const node = result.records[0]?.get('delivery');
+
+    if (!node) return null;
+
+    const props = node.properties;
+
+    return {
+        deliveryKey: props.deliveryKey,
+        refreshId: props.refreshId,
+        windowKey: props.windowKey,
+        state: props.state,
+        attempts: Number(props.attempts),
+    };
+};

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

@@ -1,3 +1,4 @@
 export * from './create';
+export * from './email-delivery';
 export * from './read';
 export * from './update';

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

@@ -262,8 +262,14 @@ export const getCredentialRefreshVersions = async (
     }
 
     const result = await neogma.queryRunner.run(
-        `MATCH (version:Credential {refreshId: $refreshId})
-         WHERE $beforeVersion IS NULL OR version.version < $beforeVersion
+        `CALL {
+             MATCH (version:Credential {refreshId: $refreshId}) RETURN version
+             UNION ALL
+             MATCH (version:InboxRefreshPublication {refreshId: $refreshId})
+             WHERE NOT EXISTS { MATCH (:Credential {refreshVersionKey: version.refreshVersionKey}) }
+             RETURN version
+         }
+         WITH version WHERE $beforeVersion IS NULL OR version.version < $beforeVersion
          RETURN {
              id: version.id,
              refreshId: version.refreshId,

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

@@ -78,6 +78,7 @@ export const advanceCredentialRefreshHead = async (
         etag,
         materialDigest,
         updateSummary,
+        credentialDisplayName,
         effectiveAt,
         notificationOutcome,
         notificationId,
@@ -103,6 +104,7 @@ export const advanceCredentialRefreshHead = async (
             etag,
             signingMode,
             updateSummary,
+            credentialDisplayName,
             idempotencyKey,
             refreshIdempotencyKey,
             notificationOutcome,
@@ -160,6 +162,7 @@ export const advanceCredentialRefreshHead = async (
                  refresh.etag = $etag,
                  refresh.materialDigest = $materialDigest,
                  refresh.updateSummary = $updateSummary,
+                 refresh.credentialDisplayName = coalesce($credentialDisplayName, refresh.credentialDisplayName),
                  refresh.signingMode = $signingMode,
                  refresh.lastPublishedAt = $publishedAt,
                  refresh.idempotencyKey = $idempotencyKey,
@@ -176,6 +179,7 @@ export const advanceCredentialRefreshHead = async (
                 etag: etag ?? null,
                 materialDigest: materialDigest ?? null,
                 updateSummary: updateSummary ?? null,
+                credentialDisplayName: credentialDisplayName ?? null,
                 signingMode,
                 publishedAt,
                 now,