@learncard/network-brain-service 3.18.0 → 3.19.0

package/src/helpers/refresh-send-intent.helpers.ts

@@ -0,0 +1,273 @@
+import { createHash, randomUUID } from 'crypto';
+import { TRPCError } from '@trpc/server';
+import type { ManagedCredentialRefreshReceipt, SendBoostResponse } from '@learncard/types';
+import { canonicalizeCredentialJson } from '@learncard/helpers';
+
+import { neogma } from '@instance';
+
+import { getInitialRefreshRoot, getManagedCredentialUri } from './credential-refresh.helpers';
+
+/** A preparation not touched for this long is considered abandoned and may be taken over. */
+export const REFRESH_SEND_INTENT_STALE_MS = 5 * 60_000;
+
+export type RefreshSendIntentState = 'preparing' | 'prepared' | 'delivered';
+
+/**
+ * Whole-call idempotency record for a managed refresh send (LC-2198 follow-up).
+ * Metadata only: never stores credential claims, subject bodies, plaintext VCs or JWEs.
+ */
+export type RefreshSendIntent = {
+    intentKey: string;
+    issuerProfileId: string;
+    requestDigest: string;
+    state: RefreshSendIntentState;
+    claimToken: string;
+    boostUri?: string;
+    credentialId?: string;
+    refreshId?: string;
+    holderDid?: string;
+    pendingReceipt?: ManagedCredentialRefreshReceipt;
+    pendingActivityId?: string;
+    result?: SendBoostResponse;
+    updatedAt: string;
+};
+
+export type ClaimRefreshSendIntentResult =
+    | { kind: 'owned'; intent: RefreshSendIntent }
+    | { kind: 'prepared'; intent: RefreshSendIntent }
+    | { kind: 'delivered'; intent: RefreshSendIntent };
+
+const getIntentKey = (issuerProfileId: string, idempotencyKey: string): string =>
+    `${issuerProfileId}:${idempotencyKey}`;
+
+/** Digest of everything that defines a prepare request; a reused key must match it. */
+export const computeRefreshSendRequestDigest = (request: {
+    recipientProfileId: string;
+    holderDid: string;
+    templateUri?: string;
+    template?: unknown;
+    contractUri?: string;
+    templateData?: Record<string, unknown>;
+    integrationId?: string;
+    credentialId?: string;
+}): string =>
+    createHash('sha256')
+        .update(
+            canonicalizeCredentialJson({
+                recipientProfileId: request.recipientProfileId,
+                holderDid: request.holderDid,
+                templateUri: request.templateUri ?? null,
+                template: request.template ?? null,
+                contractUri: request.contractUri ?? null,
+                templateData: request.templateData ?? {},
+                integrationId: request.integrationId ?? null,
+                credentialId: request.credentialId ?? null,
+            })
+        )
+        .digest('base64url');
+
+const parseIntent = (props: Record<string, unknown>): RefreshSendIntent => ({
+    intentKey: props.intentKey as string,
+    issuerProfileId: props.issuerProfileId as string,
+    requestDigest: props.requestDigest as string,
+    state: props.state as RefreshSendIntentState,
+    claimToken: props.claimToken as string,
+    boostUri: (props.boostUri as string | undefined) ?? undefined,
+    credentialId: (props.credentialId as string | undefined) ?? undefined,
+    refreshId: (props.refreshId as string | undefined) ?? undefined,
+    holderDid: (props.holderDid as string | undefined) ?? undefined,
+    pendingReceipt: props.pendingReceipt
+        ? (JSON.parse(props.pendingReceipt as string) as ManagedCredentialRefreshReceipt)
+        : undefined,
+    pendingActivityId: (props.pendingActivityId as string | undefined) ?? undefined,
+    result: props.result ? (JSON.parse(props.result as string) as SendBoostResponse) : undefined,
+    updatedAt: props.updatedAt as string,
+});
+
+export const getRefreshSendIntent = async (
+    issuerProfileId: string,
+    idempotencyKey: string
+): Promise<RefreshSendIntent | null> => {
+    const result = await neogma.queryRunner.run(
+        'MATCH (i:RefreshSendIntent {intentKey: $intentKey}) RETURN i',
+        { intentKey: getIntentKey(issuerProfileId, idempotencyKey) }
+    );
+    const node = result.records[0]?.get('i');
+
+    return node ? parseIntent(node.properties) : null;
+};
+
+/**
+ * Creates or claims the intent for (issuer, idempotencyKey). Concurrency-safe through
+ * the `refresh_send_intent_key_unique` constraint. Throws CONFLICT when the key was used
+ * for a different request, or when another live request is still preparing it.
+ */
+export const claimRefreshSendIntent = async (params: {
+    issuerProfileId: string;
+    idempotencyKey: string;
+    requestDigest: string;
+}): Promise<ClaimRefreshSendIntentResult> => {
+    const { issuerProfileId, idempotencyKey, requestDigest } = params;
+    const claimToken = randomUUID();
+    const now = new Date();
+
+    const result = await neogma.queryRunner.run(
+        `MERGE (i:RefreshSendIntent {intentKey: $intentKey})
+         ON CREATE SET i.issuerProfileId = $issuerProfileId,
+                       i.requestDigest = $requestDigest,
+                       i.state = 'preparing',
+                       i.claimToken = $claimToken,
+                       i.createdAt = $now,
+                       i.updatedAt = $now
+         SET i.updatedAt = i.updatedAt
+         WITH i
+         CALL {
+             WITH i
+             WITH i WHERE i.state = 'preparing'
+                      AND i.claimToken <> $claimToken
+                      AND i.requestDigest = $requestDigest
+                      AND i.updatedAt < $staleBefore
+             SET i.claimToken = $claimToken, i.updatedAt = $now
+         }
+         RETURN i`,
+        {
+            intentKey: getIntentKey(issuerProfileId, idempotencyKey),
+            issuerProfileId,
+            requestDigest,
+            claimToken,
+            now: now.toISOString(),
+            staleBefore: new Date(now.getTime() - REFRESH_SEND_INTENT_STALE_MS).toISOString(),
+        }
+    );
+    const intent = parseIntent(result.records[0]!.get('i').properties);
+
+    if (intent.requestDigest !== requestDigest) {
+        throw new TRPCError({
+            code: 'CONFLICT',
+            message: 'This idempotencyKey was already used for a different send request.',
+        });
+    }
+
+    if (intent.state === 'delivered') return { kind: 'delivered', intent };
+    if (intent.state === 'prepared') return { kind: 'prepared', intent };
+    if (intent.claimToken === claimToken) return { kind: 'owned', intent };
+
+    throw new TRPCError({
+        code: 'CONFLICT',
+        message: 'A send with this idempotencyKey is still being prepared. Retry shortly.',
+    });
+};
+
+const lostIntentClaim = (): TRPCError =>
+    new TRPCError({
+        code: 'CONFLICT',
+        message:
+            'This send preparation was taken over or completed. Retry with the same idempotencyKey.',
+    });
+
+/**
+ * Records progress on an intent owned by `claimToken` (boost first, then allocation).
+ * The self-dependent SET takes the node write lock before checking ownership, so
+ * a concurrent takeover cannot pass a stale check and overwrite the new owner.
+ */
+export const recordRefreshSendIntent = async (
+    intent: RefreshSendIntent,
+    fields: Partial<
+        Pick<RefreshSendIntent, 'boostUri' | 'credentialId' | 'refreshId' | 'holderDid'>
+    > & { state?: 'prepared' }
+): Promise<RefreshSendIntent> => {
+    const result = await neogma.queryRunner.run(
+        `MATCH (i:RefreshSendIntent {intentKey: $intentKey})
+         SET i.updatedAt = i.updatedAt
+         WITH i WHERE i.claimToken = $claimToken AND i.state = 'preparing'
+         SET i += $fields, i.updatedAt = $now
+         RETURN i`,
+        {
+            intentKey: intent.intentKey,
+            claimToken: intent.claimToken,
+            fields: Object.fromEntries(
+                Object.entries(fields).filter(([, value]) => value !== undefined)
+            ),
+            now: new Date().toISOString(),
+        }
+    );
+
+    if (!result.records.length) throw lostIntentClaim();
+    return parseIntent(result.records[0]!.get('i').properties);
+};
+
+/** Stores the metadata-only receipt (and activity) right before delivery is attempted. */
+export const recordRefreshSendIntentPending = async (
+    intent: RefreshSendIntent,
+    pendingReceipt: ManagedCredentialRefreshReceipt,
+    pendingActivityId?: string
+): Promise<void> => {
+    const updated = await neogma.queryRunner.run(
+        `MATCH (i:RefreshSendIntent {intentKey: $intentKey})
+         SET i.updatedAt = i.updatedAt
+         WITH i WHERE i.claimToken = $claimToken AND i.state = 'prepared'
+         SET i.pendingReceipt = $pendingReceipt,
+             i.pendingActivityId = coalesce($pendingActivityId, i.pendingActivityId),
+             i.updatedAt = $now
+         RETURN i`,
+        {
+            intentKey: intent.intentKey,
+            claimToken: intent.claimToken,
+            pendingReceipt: JSON.stringify(pendingReceipt),
+            pendingActivityId: pendingActivityId ?? null,
+            now: new Date().toISOString(),
+        }
+    );
+    if (!updated.records.length) throw lostIntentClaim();
+};
+
+export const markRefreshSendIntentDelivered = async (
+    intent: RefreshSendIntent,
+    result: SendBoostResponse
+): Promise<void> => {
+    const updated = await neogma.queryRunner.run(
+        `MATCH (i:RefreshSendIntent {intentKey: $intentKey})
+         SET i.updatedAt = i.updatedAt
+         WITH i WHERE i.claimToken = $claimToken
+                      AND (i.state = 'prepared' OR (i.state = 'delivered' AND i.result = $result))
+         SET i.state = 'delivered', i.result = $result, i.updatedAt = $now
+         RETURN i`,
+        {
+            intentKey: intent.intentKey,
+            claimToken: intent.claimToken,
+            // The atomic replay comparison must ignore object property insertion order.
+            result: canonicalizeCredentialJson(result),
+            now: new Date().toISOString(),
+        }
+    );
+    if (!updated.records.length) throw lostIntentClaim();
+};
+
+/**
+ * When an intent's refresh is already bound (delivery succeeded but the result was never
+ * recorded), rebuild the result from the pending receipt and mark it delivered. Returns
+ * null when nothing is bound yet.
+ */
+export const reconcileBoundRefreshSendIntent = async (
+    intent: RefreshSendIntent,
+    domain: string
+): Promise<SendBoostResponse | null> => {
+    if (intent.result) return intent.result;
+    if (!intent.refreshId || !intent.boostUri || !intent.pendingReceipt) return null;
+
+    const root = await getInitialRefreshRoot(intent.refreshId);
+
+    if (!root) return null;
+
+    const result: SendBoostResponse = {
+        type: 'boost',
+        uri: intent.boostUri,
+        credentialUri: getManagedCredentialUri(root.rootId, domain),
+        activityId: intent.pendingActivityId ?? '',
+        refresh: intent.pendingReceipt,
+    };
+
+    await markRefreshSendIntentDelivered(intent, result);
+
+    return result;
+};

package/src/helpers/shim.ts

@@ -5,6 +5,7 @@ import {
     type Context as AWSContext,
 } from 'aws-lambda';
 import { TRPCError } from '@trpc/server';
+import { withInboxBatchBodyLimit } from './inbox-batch-http.helpers';
 import { type IncomingMessage, type ServerResponse } from 'http';
 
 import { OpenApiRouter } from 'trpc-to-openapi';
@@ -183,36 +184,36 @@ export const createOpenApiAwsLambdaHandler = <TRouter extends OpenApiRouter>(
         maxBodySize: undefined, // AWS Lambda handles body size limits
     });
 
-    return async (
-        event: AWSAPIGatewayEvent,
-        _context: AWSContext
-    ): Promise<APIGatewayProxyResult> => {
-        try {
-            const req = createRequestFromEvent(event);
-            const { res, promise } = createResponseHandler();
-
-            // Execute the handler
-            await openApiHttpHandler(req, res);
-
-            return await promise;
-        } catch (cause) {
-            // Handle any uncaught errors
-            const error = cause instanceof Error ? cause : new Error('Unknown error');
-            const statusCode =
-                error instanceof TRPCError ? (error.code === 'NOT_FOUND' ? 404 : 500) : 500;
-
-            return {
-                statusCode,
-                headers: {
-                    'Content-Type': 'application/json',
-                },
-                body: JSON.stringify({
-                    error: {
-                        message: error.message || 'Internal server error',
-                        code: error instanceof TRPCError ? error.code : 'INTERNAL_SERVER_ERROR',
+    return withInboxBatchBodyLimit(
+        async (event: AWSAPIGatewayEvent, _context: AWSContext): Promise<APIGatewayProxyResult> => {
+            try {
+                const req = createRequestFromEvent(event);
+                const { res, promise } = createResponseHandler();
+
+                // Execute the handler
+                await openApiHttpHandler(req, res);
+
+                return await promise;
+            } catch (cause) {
+                // Handle any uncaught errors
+                const error = cause instanceof Error ? cause : new Error('Unknown error');
+                const statusCode =
+                    error instanceof TRPCError ? (error.code === 'NOT_FOUND' ? 404 : 500) : 500;
+
+                return {
+                    statusCode,
+                    headers: {
+                        'Content-Type': 'application/json',
                     },
-                }),
-            } satisfies APIGatewayProxyResult;
-        }
-    };
+                    body: JSON.stringify({
+                        error: {
+                            message: error.message || 'Internal server error',
+                            code: error instanceof TRPCError ? error.code : 'INTERNAL_SERVER_ERROR',
+                        },
+                    }),
+                } satisfies APIGatewayProxyResult;
+            }
+        },
+        'openapi'
+    );
 };

package/src/inbox-queue-local.ts

@@ -0,0 +1,28 @@
+import {
+    consumeInboxQueueOnce,
+    consumeInboxDeadLettersOnce,
+    dispatchInboxJobs,
+} from './helpers/inbox-queue.helpers';
+
+let running = true;
+process.on('SIGINT', () => {
+    running = false;
+});
+process.on('SIGTERM', () => {
+    running = false;
+});
+
+/** Run separately from the HTTP process; restarting either process leaves durable jobs intact. */
+const run = async (): Promise<void> => {
+    while (running) {
+        try {
+            await dispatchInboxJobs();
+            await consumeInboxQueueOnce(10);
+            await consumeInboxDeadLettersOnce();
+        } catch {
+            console.error('Inbox queue iteration failed; durable jobs will be retried.');
+            await new Promise(resolve => setTimeout(resolve, 1000));
+        }
+    }
+};
+void run();

package/src/models/AuthGrant.ts

@@ -21,6 +21,7 @@ export const AuthGrant = ModelFactory<FlatAuthGrantType, AuthGrantRelationships>
             challenge: { type: 'string', required: true, uniqueItems: true },
             status: { type: 'string', required: true },
             scope: { type: 'string', required: true },
+            actAs: { type: 'string', required: false },
             createdAt: { type: 'string', required: true },
             expiresAt: { type: 'string', required: false },
         },

package/src/models/CredentialActivity.ts

@@ -7,11 +7,7 @@ import { Boost, BoostInstance } from './Boost';
 import { AppStoreListing, AppStoreListingInstance } from './AppStoreListing';
 
 export type CredentialActivityEventType =
-    | 'CREATED'
-    | 'DELIVERED'
-    | 'CLAIMED'
-    | 'EXPIRED'
-    | 'FAILED';
+    'CREATED' | 'DELIVERED' | 'CLAIMED' | 'EXPIRED' | 'FAILED';
 
 export type CredentialActivityRecipientType = 'profile' | 'email' | 'phone';
 
@@ -32,6 +28,7 @@ export type CredentialActivityType = {
     eventType: CredentialActivityEventType;
     timestamp: string;
     actorProfileId?: string;
+    onBehalfOf?: string;
     recipientType: CredentialActivityRecipientType;
     recipientIdentifier: string;
     boostUri?: string;
@@ -70,6 +67,7 @@ export const CredentialActivity = ModelFactory<
             },
             timestamp: { type: 'string', required: true },
             actorProfileId: { type: 'string', required: false },
+            onBehalfOf: { type: 'string', required: false },
             recipientType: {
                 type: 'string',
                 required: true,

package/src/models/CredentialRefresh.ts

@@ -36,16 +36,18 @@ export const CredentialRefresh = ModelFactory<
     {
         label: 'CredentialRefresh',
         schema: {
+            inboxCredentialId: { type: 'string', required: false },
+            inboxCredentialStatus: { type: 'string', required: false },
             refreshId: { type: 'string', required: true },
             issuerProfileId: { type: 'string', required: true },
             issuerDid: { type: 'string', required: true },
             holderProfileId: { type: 'string', required: false },
-            holderDid: { type: 'string', required: true },
+            holderDid: { type: 'string', required: false },
             credentialId: { type: 'string', required: true },
             state: {
                 type: 'string',
                 required: true,
-                enum: ['awaiting_claim', 'active', 'revoked'],
+                enum: ['pending_holder', 'awaiting_claim', 'active', 'revoked'],
             },
             currentVersion: { type: 'number', required: true },
             etag: { type: 'string', required: false },

package/src/models/InboxCredential.ts

@@ -6,6 +6,7 @@ import { Profile, ProfileInstance } from './Profile';
 import ContactMethod, { ContactMethodInstance } from './ContactMethod';
 
 export type InboxCredentialType = {
+    refreshId?: string;
     id: string;
     credential?: string; // Versioned JWE; removed immediately after successful finalization
     isSigned: boolean;
@@ -86,6 +87,7 @@ export const InboxCredential = ModelFactory<InboxCredentialType, InboxCredential
     {
         label: 'InboxCredential',
         schema: {
+            refreshId: { type: 'string', required: false },
             id: { type: 'string', required: true, uniqueItems: true },
             credential: { type: 'string', required: false },
             isSigned: { type: 'boolean', required: true },

package/src/models/credential-refresh-constraints.test.ts

@@ -38,11 +38,16 @@ describe('credential refresh constraint readiness', () => {
         releaseFirstQuery();
         await Promise.all([first, second]);
 
-        expect(mocks.run).toHaveBeenCalledTimes(3);
+        expect(mocks.run).toHaveBeenCalledTimes(8);
         expect(mocks.run.mock.calls.map(([query]) => query)).toEqual([
+            'CREATE CONSTRAINT inbox_refresh_issue_key_unique IF NOT EXISTS FOR (i:InboxCredential) REQUIRE (i.refreshIssueKey) IS UNIQUE',
+            'CREATE CONSTRAINT inbox_refresh_publication_key_unique IF NOT EXISTS FOR (p:InboxRefreshPublication) REQUIRE (p.refreshIdempotencyKey) IS UNIQUE',
+            'CREATE CONSTRAINT inbox_refresh_version_key_unique IF NOT EXISTS FOR (p:InboxRefreshPublication) REQUIRE (p.refreshVersionKey) IS UNIQUE',
             'CREATE CONSTRAINT credential_refresh_id_unique IF NOT EXISTS FOR (r:CredentialRefresh) REQUIRE (r.refreshId) IS UNIQUE',
             'CREATE CONSTRAINT credential_refresh_version_key_unique IF NOT EXISTS FOR (c:Credential) REQUIRE (c.refreshVersionKey) IS UNIQUE',
             'CREATE CONSTRAINT credential_refresh_idempotency_key_unique IF NOT EXISTS FOR (c:Credential) REQUIRE (c.refreshIdempotencyKey) IS UNIQUE',
+            'CREATE CONSTRAINT credential_refresh_email_delivery_key_unique IF NOT EXISTS FOR (d:CredentialRefreshEmailDelivery) REQUIRE (d.deliveryKey) IS UNIQUE',
+            'CREATE CONSTRAINT refresh_send_intent_key_unique IF NOT EXISTS FOR (i:RefreshSendIntent) REQUIRE (i.intentKey) IS UNIQUE',
         ]);
     });
 
@@ -57,7 +62,7 @@ describe('credential refresh constraint readiness', () => {
             await import('./credential-refresh-constraints');
 
         await expect(ensureCredentialRefreshConstraints()).resolves.toBeUndefined();
-        expect(mocks.run).toHaveBeenCalledTimes(3);
+        expect(mocks.run).toHaveBeenCalledTimes(8);
     });
 
     it('clears failed readiness so a later request can retry', async () => {
@@ -70,6 +75,6 @@ describe('credential refresh constraint readiness', () => {
         await expect(ensureCredentialRefreshConstraints()).rejects.toBe(setupFailure);
         await expect(ensureCredentialRefreshConstraints()).resolves.toBeUndefined();
 
-        expect(mocks.run).toHaveBeenCalledTimes(4);
+        expect(mocks.run).toHaveBeenCalledTimes(9);
     });
 });

package/src/models/credential-refresh-constraints.ts

@@ -1,9 +1,14 @@
 import { neogma } from '@instance';
 
 const CREDENTIAL_REFRESH_CONSTRAINT_QUERIES = [
+    'CREATE CONSTRAINT inbox_refresh_issue_key_unique IF NOT EXISTS FOR (i:InboxCredential) REQUIRE (i.refreshIssueKey) IS UNIQUE',
+    'CREATE CONSTRAINT inbox_refresh_publication_key_unique IF NOT EXISTS FOR (p:InboxRefreshPublication) REQUIRE (p.refreshIdempotencyKey) IS UNIQUE',
+    'CREATE CONSTRAINT inbox_refresh_version_key_unique IF NOT EXISTS FOR (p:InboxRefreshPublication) REQUIRE (p.refreshVersionKey) IS UNIQUE',
     'CREATE CONSTRAINT credential_refresh_id_unique IF NOT EXISTS FOR (r:CredentialRefresh) REQUIRE (r.refreshId) IS UNIQUE',
     'CREATE CONSTRAINT credential_refresh_version_key_unique IF NOT EXISTS FOR (c:Credential) REQUIRE (c.refreshVersionKey) IS UNIQUE',
     'CREATE CONSTRAINT credential_refresh_idempotency_key_unique IF NOT EXISTS FOR (c:Credential) REQUIRE (c.refreshIdempotencyKey) IS UNIQUE',
+    'CREATE CONSTRAINT credential_refresh_email_delivery_key_unique IF NOT EXISTS FOR (d:CredentialRefreshEmailDelivery) REQUIRE (d.deliveryKey) IS UNIQUE',
+    'CREATE CONSTRAINT refresh_send_intent_key_unique IF NOT EXISTS FOR (i:RefreshSendIntent) REQUIRE (i.intentKey) IS UNIQUE',
 ];
 
 type Neo4jSchemaError = {

package/src/openapi.ts

@@ -25,6 +25,14 @@ export const openApiDocument = generateOpenApiDocument(appRouter, {
     ],
 });
 
+// Keep this path/status aligned with inboxBatchResponseMeta in helpers/inbox-batch-http.helpers.ts.
+// The adapter's responseMeta returns 202 for durable batch acceptance.
+const batchResponses = openApiDocument.paths?.['/inbox/issue-batch']?.post?.responses;
+if (batchResponses?.['200']) {
+    batchResponses['202'] = batchResponses['200'];
+    delete batchResponses['200'];
+}
+
 // trpc-to-openapi requires a top-level ZodObject and cannot render the validator's
 // cross-field refinement. Preserve the runtime-safe object parser while documenting
 // the two mutually exclusive publication shapes for generated OpenAPI clients.