@learncard/network-brain-service 4.1.2 → 5.0.0

package/src/accesslayer/credential/create.ts

@@ -6,10 +6,14 @@ import { isIssuedCredential } from '@helpers/issuedCredentialStatus.helpers';
 import type { IssuedCredential } from 'types/credential';
 
 import { Credential, CredentialInstance } from '@models';
+import { neogma } from '@instance';
+import { reserveCredentialStatusEntries } from '@helpers/status-list.helpers';
 
 export const storeCredential = async (
     input: UnsignedVC | VC | JWE | IssuedCredential,
-    transaction?: Transaction
+    transaction?: Transaction,
+    statusOwnerProfileId?: string,
+    options: { lenient?: boolean } = {}
 ): Promise<CredentialInstance> => {
     const id = uuid();
 
@@ -21,6 +25,7 @@ export const storeCredential = async (
         ? BitstringStatusListEntryValidator.array().parse(input.statusEntries)
         : undefined;
     const encrypted = isEncrypted(credential);
+    const lenient = options.lenient === true && !issued && !encrypted;
     if (
         !statusEntries?.length &&
         (encrypted || !getBitstringStatusListEntries(credential).length)
@@ -30,12 +35,31 @@ export const storeCredential = async (
             { credentialId: id }
         );
     }
-    return Credential.createOne(
-        {
-            id,
-            credential: JSON.stringify(credential),
-            ...(statusEntries?.length ? { statusEntries: JSON.stringify(statusEntries) } : {}),
-        },
-        transaction ? { session: transaction } : undefined
-    );
+    const create = (session?: Transaction, validatedOwner?: string) =>
+        Credential.createOne(
+            {
+                id,
+                credential: JSON.stringify(credential),
+                ...(statusEntries?.length ? { statusEntries: JSON.stringify(statusEntries) } : {}),
+                ...(validatedOwner
+                    ? {
+                          statusOwnerProfileId: validatedOwner,
+                          statusReservationMode: lenient
+                              ? ('lenient' as const)
+                              : ('strict' as const),
+                      }
+                    : {}),
+            },
+            session ? { session } : undefined
+        );
+    const entries = statusEntries ?? getBitstringStatusListEntries(credential);
+    if (!statusOwnerProfileId || entries.length === 0) return create(transaction);
+    return neogma.getTransaction(transaction ?? null, async tx => {
+        await reserveCredentialStatusEntries(entries, statusOwnerProfileId, id, tx, {
+            lenient,
+            ...(!encrypted ? { credential } : {}),
+        });
+        // Inbox deliveries need a validated owner even without a CREDENTIAL_SENT edge.
+        return create(tx, statusOwnerProfileId);
+    });
 };

package/src/accesslayer/credential/delete.ts

@@ -1,5 +1,50 @@
 import { CredentialInstance } from '@models';
+import { neogma } from '@instance';
 
 export const deleteCredential = async (credential: CredentialInstance): Promise<void> => {
     await credential.delete({ detach: true });
 };
+
+/** Release failed deliveries with no relationships beyond Boost instance membership. */
+export const releaseUnlinkedCredential = async (id: string): Promise<void> => {
+    await neogma.getTransaction(null, async tx => {
+        const eligible = await tx.run(
+            `MATCH (credential:Credential {id: $id})
+             SET credential._statusMutationLock = true REMOVE credential._statusMutationLock
+             WITH credential
+             WHERE NOT EXISTS {
+                 MATCH (credential)-[relationship]-()
+                 WHERE type(relationship) <> 'INSTANCE_OF'
+             }
+             RETURN credential.id AS id`,
+            { id }
+        );
+        if (eligible.records.length === 0) return;
+        const lists = await tx.run(
+            `MATCH (list:BitstringStatusList)-[:HAS_STATUS_BINDING]->(binding:CredentialStatusBinding)
+             WHERE $id IN coalesce(binding.credentialIds, [binding.credentialId])
+             RETURN DISTINCT list.statusListCredential AS url ORDER BY url`,
+            { id }
+        );
+        // Match reservation lock order and re-read membership only after acquiring each list lock.
+        for (const row of [...lists.records].sort((a, b) =>
+            String(a.get('url')).localeCompare(String(b.get('url')))
+        )) {
+            const url = String(row.get('url'));
+            await tx.run(
+                `MATCH (list:BitstringStatusList {statusListCredential: $url})
+             SET list._statusBindingLock = true REMOVE list._statusBindingLock`,
+                { url }
+            );
+            await tx.run(
+                `MATCH (:BitstringStatusList {statusListCredential: $url})-[:HAS_STATUS_BINDING]->(binding:CredentialStatusBinding)
+             WHERE binding.refreshId IS NULL AND $id IN coalesce(binding.credentialIds, [binding.credentialId])
+             WITH binding, [member IN coalesce(binding.credentialIds, [binding.credentialId]) WHERE member <> $id] AS remaining
+             SET binding.credentialIds = remaining, binding.credentialId = head(remaining)
+             FOREACH (_ IN CASE WHEN size(remaining) = 0 THEN [1] ELSE [] END | DETACH DELETE binding)`,
+                { id, url }
+            );
+        }
+        await tx.run('MATCH (credential:Credential {id: $id}) DETACH DELETE credential', { id });
+    });
+};

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

@@ -7,9 +7,9 @@ import {
     CredentialInstance,
     Credential,
     Boost,
+    BoostInstance,
     Role,
     Profile,
-    ConsentFlowTerms,
     ConsentFlowTransaction,
     AppStoreListing,
 } from '@models';
@@ -19,6 +19,8 @@ import { CredentialIssuer, getIssuerOwnerProfile, isAppStoreListingIssuer } from
 import { clearDidWebCacheForChildProfileManagers } from '@accesslayer/boost/relationships/update';
 import { getBoostIdForCredentialInstance } from '@accesslayer/credential/relationships/read';
 import { DbTermsType } from 'types/consentflowcontract';
+import { TRPCError } from '@trpc/server';
+import { runAudienceMutation } from '@accesslayer/consentflowcontract/relationships/recipients';
 
 export const createSentCredentialRelationship = async (
     issuer: CredentialIssuer,
@@ -102,7 +104,8 @@ export const createListingSentCredentialRelationship = async (
     credential: CredentialInstance,
     metadata?: Record<string, unknown>,
     activityId?: string,
-    integrationId?: string
+    integrationId?: string,
+    transaction?: Transaction
 ): Promise<void> => {
     const properties = flattenObject({
         to: to.profileId,
@@ -133,7 +136,7 @@ export const createListingSentCredentialRelationship = async (
             }]->(credential)`
         )
         .set('r = $params')
-        .run();
+        .run(transaction);
 };
 
 export const createReceivedCredentialRelationship = async (
@@ -218,49 +221,101 @@ export const setDefaultClaimedRole = async (
 };
 
 /**
- * Creates a transaction for a credential being issued via a contract's write permission
- * and links the credential to that transaction (which is linked to the terms)
+ * Commit delivery and its audit entry under the same lock as access updates.
+ * Signing may have awaited an external service; the captured grant is not authority.
  */
-export const createCredentialIssuedViaContractRelationship = async (
-    credential: CredentialInstance,
-    terms: DbTermsType
-): Promise<void> => {
-    const currentDate = new Date().toISOString();
-    const transactionId = uuid();
-
-    await new QueryBuilder()
-        .match({
-            model: ConsentFlowTerms,
-            where: { id: terms.id },
-            identifier: 'terms',
-        })
-        .create({
-            related: [
-                {
-                    model: ConsentFlowTransaction,
-                    identifier: 'transaction',
-                    properties: { id: transactionId, action: 'write', date: currentDate },
-                },
-                ConsentFlowTransaction.getRelationshipByAlias('isFor'),
-                { identifier: 'terms' },
-            ],
-        })
-        .raw(termsReferralSnapshotCypher())
-        .with('transaction')
-        .match({
-            model: Credential,
-            where: { id: credential.id },
-            identifier: 'credential',
-        })
-        .create({
-            related: [
-                { identifier: 'credential' },
-                {
-                    ...Credential.getRelationshipByAlias('issuedViaTransaction'),
-                    properties: { date: currentDate },
-                },
-                { identifier: 'transaction' },
-            ],
-        })
-        .run();
+export const createContractCredentialRelationships = async ({
+    issuer,
+    writerProfileId,
+    recipient,
+    credential,
+    boost,
+    terms,
+    metadata,
+    activityId,
+    integrationId,
+    listingId,
+    allowConsumedOneTime = false,
+}: {
+    issuer: CredentialIssuer;
+    writerProfileId: string;
+    recipient: ProfileType;
+    credential: CredentialInstance;
+    boost: BoostInstance;
+    terms: DbTermsType;
+    metadata?: Record<string, unknown>;
+    activityId?: string;
+    integrationId?: string;
+    listingId?: string;
+    allowConsumedOneTime?: boolean;
+}): Promise<void> => {
+    const date = new Date().toISOString();
+    const owner = getIssuerOwnerProfile(issuer);
+    const listingIds = [
+        ...new Set([
+            ...(isAppStoreListingIssuer(issuer) ? [issuer.listing.listing_id] : []),
+            ...(listingId ? [listingId] : []),
+        ]),
+    ];
+    const result = await runAudienceMutation(
+        new QueryBuilder(
+            new BindParam({
+                termsId: terms.id,
+                expectedVersion: terms.consentedVersion,
+                issuerId: owner.profileId,
+                writerProfileId,
+                recipientId: recipient.profileId,
+                credentialId: credential.id,
+                boostId: boost.id,
+                listingIds,
+                allowConsumedOneTime,
+                sent: flattenObject({
+                    to: recipient.profileId,
+                    date,
+                    ...(metadata ? { metadata } : {}),
+                    ...(activityId ? { activityId } : {}),
+                    ...(integrationId ? { integrationId } : {}),
+                }),
+                transactionId: uuid(),
+                date,
+            })
+        ).raw(`
+                MATCH (terms:ConsentFlowTerms {id:$termsId})-[:CONSENTS_TO]->(contract:ConsentFlowContract)
+                SET contract.audienceLock = coalesce(contract.audienceLock, 0) + 1
+                WITH terms, contract
+                WHERE coalesce(contract.status, 'active') <> 'retired'
+                  AND contract.currentVersion = $expectedVersion
+                  AND terms.consentedVersion = $expectedVersion
+                  AND (terms.status = 'live' OR
+                    ($allowConsumedOneTime AND terms.status = 'consumed' AND terms.oneTime = true))
+                  AND (terms.expiresAt IS NULL OR trim(terms.expiresAt) = '' OR datetime(terms.expiresAt) > datetime.realtime())
+                  AND (contract.expiresAt IS NULL OR trim(contract.expiresAt) = '' OR datetime(contract.expiresAt) > datetime.realtime())
+                  AND NOT $writerProfileId IN coalesce(terms['terms.deniedWriters'], [])
+                  AND EXISTS { MATCH (contract)-[:CREATED_BY|CAN_WRITE]->(:Profile {profileId:$writerProfileId}) }
+                  AND EXISTS { MATCH (:Profile {profileId:$recipientId})-[:CREATED_BY]->(terms) }
+                MATCH (credential:Credential {id:$credentialId}), (boost:Boost {id:$boostId}),
+                    (issuer:Profile {profileId:$issuerId})
+                WHERE boost.category IS NULL OR terms['terms.write.credentials.categories.' + boost.category] = true
+                OPTIONAL MATCH (listing:AppStoreListing) WHERE listing.listing_id IN $listingIds
+                WITH terms, contract, credential, boost, issuer, collect(DISTINCT listing) AS listings
+                WHERE size(listings) = size($listingIds)
+                CREATE (credential)-[:${Credential.getRelationshipByAlias('instanceOf').name}]->(boost)
+                CREATE (issuer)-[sent:${Profile.getRelationshipByAlias('credentialSent').name}]->(credential)
+                SET sent = $sent
+                FOREACH (listing IN listings |
+                    CREATE (listing)-[delivery:CREDENTIAL_SENT]->(credential)
+                    SET delivery = $sent)
+                CREATE (transaction:ConsentFlowTransaction {id:$transactionId, action:'write', date:$date, boostId:$boostId})
+                    -[:${ConsentFlowTransaction.getRelationshipByAlias('isFor').name}]->(terms)
+                ${termsReferralSnapshotCypher()}
+                CREATE (credential)-[:${Credential.getRelationshipByAlias('issuedViaTransaction').name} {date:$date}]->(transaction)
+                RETURN transaction.id AS id
+            `)
+    );
+    if (!result.records.length) {
+        throw new TRPCError({
+            code: 'FORBIDDEN',
+            message: 'User has not yet approved the latest version of this contract',
+        });
+    }
 };

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

@@ -1,135 +1,27 @@
 import { QueryBuilder, BindParam } from 'neogma';
 
 import { Credential } from '@models';
-import { setCredentialBitstringStatus } from '@helpers/status-list.helpers';
-import { revokeCredentialRefreshForCredential } from '@accesslayer/credential-refresh/update';
+import { mutateCredentialStatus } from '@helpers/credential-status-mutation.helpers';
 
-/**
- * Revoke a credential by setting its issuer-controlled status on the CREDENTIAL_SENT relationship.
- * This applies to both pending and claimed credentials without creating a received relationship.
- */
+/** Revoke the root credential and its public bit atomically. */
 export const revokeCredentialReceived = async (
     credentialId: string,
     profileId: string
-): Promise<boolean> => {
-    const revokedAt = new Date().toISOString();
-
-    const result = await new QueryBuilder(new BindParam({ profileId, revokedAt }))
-        .match({ identifier: 'credential', model: Credential, where: { id: credentialId } })
-        .raw(
-            `MATCH (sender)-[sent:CREDENTIAL_SENT {to: $profileId}]->(credential)
-             WHERE sender:Profile OR sender:AppStoreListing
-             SET sent.status = "revoked",
-                 sent.revokedAt = $revokedAt
-             RETURN sent`
-        )
-        .run();
-
-    if (result.records.length > 0) {
-        const bitSet = await setCredentialBitstringStatus(credentialId, 'revocation', true);
-        if (!bitSet) {
-            // The relationship is marked revoked but the credential has no 'revocation'
-            // status-list entry, so the verifiable bit was NOT set. Holders relying purely
-            // on verifyCredential can't see the revocation. Surface it instead of failing
-            // silently (the authoritative relationship status still drives the UI).
-            console.warn(
-                `[revokeCredentialReceived] credential ${credentialId} has no verifiable 'revocation' status entry; bitstring bit not set`
-            );
-        }
-    }
+): Promise<boolean> => mutateCredentialStatus(credentialId, profileId, 'revocation', true);
 
-    // Managed credential refresh coupling (LC-2117/LC-2135): revoking the original
-    // sent credential invalidates the whole refresh chain. Best-effort — the holder
-    // endpoint independently cross-checks this canonical relationship state on every
-    // authenticated request, so a failed write here cannot leave a revoked credential
-    // servable.
-    if (result.records.length > 0) {
-        try {
-            await revokeCredentialRefreshForCredential(credentialId);
-        } catch (error) {
-            console.error(
-                '[revokeCredentialReceived] failed to revoke credential refresh aggregate:',
-                error
-            );
-        }
-    }
-
-    return result.records.length > 0;
-};
-
-/**
- * Suspend a credential by setting its issuer-controlled status on the CREDENTIAL_SENT relationship.
- * If the credential has already been revoked, the revoked relationship state is preserved.
- */
+/** Suspend the root credential without changing an irreversible revocation. */
 export const suspendCredentialReceived = async (
     credentialId: string,
     profileId: string
-): Promise<boolean> => {
-    const suspendedAt = new Date().toISOString();
-
-    const result = await new QueryBuilder(new BindParam({ profileId, suspendedAt }))
-        .match({ identifier: 'credential', model: Credential, where: { id: credentialId } })
-        .raw(
-            `MATCH (sender)-[sent:CREDENTIAL_SENT {to: $profileId}]->(credential)
-             WHERE (sender:Profile OR sender:AppStoreListing)
-               AND coalesce(sent.status, "") <> "revoked"
-             SET sent.status = "suspended",
-                 sent.suspendedAt = $suspendedAt
-             RETURN sent`
-        )
-        .run();
-
-    if (result.records.length > 0) {
-        const bitSet = await setCredentialBitstringStatus(credentialId, 'suspension', true);
-        if (!bitSet) {
-            // Relationship marked suspended but the credential has no 'suspension' status
-            // entry, so the verifiable bit was NOT set. The authoritative relationship
-            // status still drives the UI; log so the gap is visible.
-            console.warn(
-                `[suspendCredentialReceived] credential ${credentialId} has no verifiable 'suspension' status entry; bitstring bit not set`
-            );
-        }
-    }
-
-    return result.records.length > 0;
-};
+): Promise<boolean> => mutateCredentialStatus(credentialId, profileId, 'suspension', true);
 
-/**
- * Clear a reversible suspension. Revocation remains irreversible and is not cleared.
- */
+/** Failed bit writes roll back the relationship, so unsuspension remains retryable. */
 export const unsuspendCredentialReceived = async (
     credentialId: string,
     profileId: string
-): Promise<boolean> => {
-    const unsuspendedAt = new Date().toISOString();
-
-    const result = await new QueryBuilder(new BindParam({ profileId, unsuspendedAt }))
-        .match({ identifier: 'credential', model: Credential, where: { id: credentialId } })
-        .raw(
-            `MATCH (sender)-[sent:CREDENTIAL_SENT {to: $profileId}]->(credential)
-             WHERE (sender:Profile OR sender:AppStoreListing)
-               AND sent.status = "suspended"
-             SET sent.status = null,
-                 sent.unsuspendedAt = $unsuspendedAt
-             RETURN sent`
-        )
-        .run();
-
-    if (result.records.length > 0) {
-        const bitCleared = await setCredentialBitstringStatus(credentialId, 'suspension', false);
-        if (!bitCleared) {
-            console.warn(
-                `[unsuspendCredentialReceived] credential ${credentialId} has no verifiable 'suspension' status entry; bitstring bit not cleared`
-            );
-        }
-    }
-
-    return result.records.length > 0;
-};
+): Promise<boolean> => mutateCredentialStatus(credentialId, profileId, 'suspension', false);
 
-/**
- * Check if a credential has been revoked for a specific profile
- */
+/** Check if a credential has been revoked for a specific profile. */
 export const isCredentialRevoked = async (
     credentialId: string,
     profileId: string

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

@@ -39,6 +39,28 @@ export const getCredentialRefresh = async (
     return CredentialRefreshRecordValidator.parse(normalizeProps(node.properties));
 };
 
+/** Select only a holder's actual root delivery; acceptance is deliberately not required. */
+export const getCredentialRefreshReceiptBinding = async (
+    rootId: string,
+    holderProfileId: string
+): Promise<CredentialRefreshRecord | null | undefined> => {
+    const result = await neogma.queryRunner.run(
+        `MATCH (sender)-[sent:CREDENTIAL_SENT {to: $holderProfileId}]->(root:Credential {id: $rootId})
+         WHERE (sender:Profile OR sender:AppStoreListing)
+           AND (sent.status IS NULL OR sent.status <> 'revoked')
+           AND NOT EXISTS {
+               MATCH (root)-[received:CREDENTIAL_RECEIVED]->(:Profile {profileId: $holderProfileId})
+               WHERE received.status = 'revoked'
+           }
+         OPTIONAL MATCH (refresh:CredentialRefresh)-[:ROOT]->(root)
+         RETURN refresh LIMIT 1`,
+        { rootId, holderProfileId }
+    );
+    if (!result.records.length) return undefined;
+    const node = result.records[0]?.get('refresh');
+    return node ? CredentialRefreshRecordValidator.parse(normalizeProps(node.properties)) : null;
+};
+
 /** Fetches the current head version node (including its holder-encrypted JWE payload). */
 export const getCredentialRefreshHead = async (
     refreshId: string
@@ -205,7 +227,8 @@ export const getCredentialRefreshVersionsForHolder = async (
              effectiveAt: version.effectiveAt,
              etag: version.etag,
              signingMode: version.signingMode,
-             updateSummary: version.updateSummary
+                       updateSummary: version.updateSummary,
+                       updateReason: version.updateReason
          } END) WHERE entry IS NOT NULL] AS metadata
          RETURN revoked, metadata`,
         { refreshId, beforeVersion: beforeVersion ?? null, limitPlusOne: int(limit + 1) }
@@ -279,7 +302,8 @@ export const getCredentialRefreshVersions = async (
              effectiveAt: version.effectiveAt,
              etag: version.etag,
              signingMode: version.signingMode,
-             updateSummary: version.updateSummary
+                       updateSummary: version.updateSummary,
+                       updateReason: version.updateReason
          } AS metadata
          ORDER BY version.version DESC
          LIMIT $limitPlusOne`,

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

@@ -78,6 +78,7 @@ export const advanceCredentialRefreshHead = async (
         etag,
         materialDigest,
         updateSummary,
+        updateReason,
         credentialDisplayName,
         effectiveAt,
         notificationOutcome,
@@ -104,6 +105,7 @@ export const advanceCredentialRefreshHead = async (
             etag,
             signingMode,
             updateSummary,
+            updateReason,
             credentialDisplayName,
             idempotencyKey,
             refreshIdempotencyKey,
@@ -161,8 +163,9 @@ export const advanceCredentialRefreshHead = async (
              SET refresh.currentVersion = $nextVersion,
                  refresh.etag = $etag,
                  refresh.materialDigest = $materialDigest,
-                 refresh.updateSummary = $updateSummary,
-                 refresh.credentialDisplayName = coalesce($credentialDisplayName, refresh.credentialDisplayName),
+                  refresh.updateSummary = $updateSummary,
+                  refresh.updateReason = $updateReason,
+                  refresh.credentialDisplayName = $credentialDisplayName,
                  refresh.signingMode = $signingMode,
                  refresh.lastPublishedAt = $publishedAt,
                  refresh.idempotencyKey = $idempotencyKey,
@@ -179,6 +182,7 @@ export const advanceCredentialRefreshHead = async (
                 etag: etag ?? null,
                 materialDigest: materialDigest ?? null,
                 updateSummary: updateSummary ?? null,
+                updateReason: updateReason ?? null,
                 credentialDisplayName: credentialDisplayName ?? null,
                 signingMode,
                 publishedAt,

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

@@ -16,7 +16,12 @@ export const DEFAULT_INBOX_EXPIRY_DAYS = 30;
 
 export const createInboxCredential = async (input: {
     credential: string;
-    refresh?: { aggregate: Record<string, unknown>; issueKey: string; requestDigest: string };
+    refresh?: {
+        aggregate: Record<string, unknown>;
+        issueKey: string;
+        requestDigest: string;
+        requestDigestCandidates?: string[];
+    };
     /** Only set after the normal delivery helper has durably stored the credential. */
     delivered?: boolean;
     isSigned: boolean;
@@ -93,6 +98,7 @@ export const createInboxCredential = async (input: {
             ),
             issueKey: input.refresh.issueKey,
             requestDigest: input.refresh.requestDigest,
+            requestDigestCandidates: input.refresh.requestDigestCandidates,
         });
         id = created.id;
     } else {

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

@@ -32,12 +32,13 @@ export const createPendingInboxRefresh = async (params: {
     aggregate: Record<string, unknown>;
     issueKey: string;
     requestDigest: string;
+    requestDigestCandidates?: 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
+          WITH issuer, ic WHERE ic.refreshRequestDigest IN $requestDigestCandidates
          MERGE (refresh:CredentialRefresh {refreshId: ic.refreshId})
          ON CREATE SET refresh += $aggregate
          MERGE (issuer)-[:ISSUED_REFRESH]->(refresh)
@@ -46,7 +47,11 @@ export const createPendingInboxRefresh = async (params: {
          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 }
+        {
+            ...params,
+            requestDigestCandidates: params.requestDigestCandidates ?? [params.requestDigest],
+            issuerProfileId: params.aggregate.issuerProfileId,
+        }
     );
     const props = result.records[0]?.get('ic')?.properties;
     if (!props)
@@ -87,6 +92,7 @@ export const advancePendingInboxRefresh = async (params: {
     materialDigest: string;
     idempotencyKey?: string;
     updateSummary?: string;
+    updateReason?: import('@learncard/types').CredentialRefreshUpdateReason;
 }): Promise<PublishCredentialRefreshResult | null> => {
     const { refreshId, expectedVersion, idempotencyKey } = params;
     const replay = await getPendingInboxPublication(refreshId, idempotencyKey);
@@ -101,11 +107,13 @@ export const advancePendingInboxRefresh = async (params: {
            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,
+         SET ic.credential = $credential,
+             ic.credentialName = coalesce($credentialName, ic.credentialName),
              refresh.currentVersion = $version, refresh.materialDigest = $materialDigest,
              refresh.credentialDisplayName = coalesce($credentialName, refresh.credentialDisplayName),
              refresh.lastPublishedAt = $publishedAt, refresh.updatedAt = $publishedAt,
-             refresh.updateSummary = $updateSummary
+              refresh.updateSummary = $updateSummary,
+              refresh.updateReason = $updateReason
          RETURN p`,
         {
             ...params,
@@ -113,6 +121,7 @@ export const advancePendingInboxRefresh = async (params: {
             publishedAt,
             credentialName: params.credentialName ?? null,
             updateSummary: params.updateSummary ?? null,
+            updateReason: params.updateReason ?? null,
             key: idempotencyKey ? `${refreshId}:${idempotencyKey}` : null,
             publication: Object.fromEntries(
                 Object.entries({
@@ -123,6 +132,7 @@ export const advancePendingInboxRefresh = async (params: {
                     publishedAt,
                     signingMode: 'signing-authority',
                     updateSummary: params.updateSummary,
+                    updateReason: params.updateReason,
                     refreshIdempotencyKey: idempotencyKey
                         ? `${refreshId}:${idempotencyKey}`
                         : undefined,