@learncard/network-brain-service 4.1.3 → 5.0.0

package/src/helpers/credential-status-mutation.helpers.test.ts

@@ -0,0 +1,155 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import type { Transaction } from 'neo4j-driver';
+import type { BitstringStatusListEntry } from '@learncard/types';
+
+const mocks = vi.hoisted(() => ({
+    run: vi.fn(),
+    transaction: vi.fn(),
+    entries: vi.fn(),
+    setBit: vi.fn(),
+}));
+vi.mock('@instance', () => ({ neogma: { getTransaction: mocks.transaction } }));
+vi.mock('./status-list.helpers', () => ({
+    CREDENTIAL_STATUS_ROOT_QUERY: 'MATCH (credential:Credential {id: $credentialId})',
+    getStatusEntriesForCredential: mocks.entries,
+    setStatusListEntryBit: mocks.setBit,
+    isNetworkStatusEntry: (entry: BitstringStatusListEntry) =>
+        new URL(entry.statusListCredential).hostname === 'network.example',
+}));
+import {
+    mutateCredentialStatus,
+    reconcileCredentialStatus,
+} from './credential-status-mutation.helpers';
+
+const entry: BitstringStatusListEntry = {
+    type: 'BitstringStatusListEntry',
+    statusPurpose: 'revocation',
+    statusListIndex: '7',
+    statusListCredential: 'https://network.example/status-lists/list',
+};
+const tx = { run: mocks.run } as unknown as Transaction;
+const record = (values: Record<string, unknown>) => ({
+    get: (key: string): unknown => values[key] ?? null,
+});
+
+describe('credential lifecycle status mutations', () => {
+    beforeEach(() => {
+        vi.resetAllMocks();
+        vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+        mocks.transaction.mockImplementation(
+            async (_existing: unknown, callback: (transaction: Transaction) => Promise<unknown>) =>
+                callback(tx)
+        );
+        mocks.run.mockResolvedValue({
+            records: [record({ rootId: 'root', owner: 'status-owner' })],
+        });
+        mocks.entries.mockResolvedValue([entry]);
+        mocks.setBit.mockResolvedValue(true);
+    });
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+
+    it.each([
+        { value: true, previous: null, next: 'suspended' },
+        { value: false, previous: 'suspended', next: null },
+    ])(
+        'updates revocation-only relationship suspension value=$value',
+        async ({ value, previous, next }) => {
+            mocks.run.mockResolvedValue({
+                records: [record({ rootId: 'root', owner: 'status-owner', status: previous })],
+            });
+            await expect(
+                mutateCredentialStatus('version', 'recipient', 'suspension', value)
+            ).resolves.toBe(true);
+            expect(mocks.setBit).not.toHaveBeenCalled();
+            expect(console.warn).toHaveBeenCalledWith(expect.any(String), {
+                rootId: 'root',
+                purpose: 'suspension',
+            });
+            expect(mocks.run).toHaveBeenLastCalledWith(
+                expect.stringContaining('SET sent.status = $status'),
+                expect.objectContaining({ status: next })
+            );
+        }
+    );
+    it('revokes using the stored status owner before the sender', async () => {
+        await expect(
+            mutateCredentialStatus('version', 'recipient', 'revocation', true)
+        ).resolves.toBe(true);
+        expect(mocks.run.mock.calls[0]?.[0]).toContain(
+            'coalesce(refresh.issuerProfileId, root.statusOwnerProfileId, issuer.profileId) AS owner'
+        );
+        expect(mocks.setBit).toHaveBeenCalledWith(entry, true, 'status-owner', tx);
+        expect(mocks.run).toHaveBeenLastCalledWith(
+            expect.stringContaining('SET sent.status = $status'),
+            expect.objectContaining({ status: 'revoked' })
+        );
+    });
+    it.each(['revocation', 'suspension'] as const)(
+        'fails before relationship writes when advertised %s bit fails',
+        async purpose => {
+            mocks.entries.mockResolvedValue([{ ...entry, statusPurpose: purpose }]);
+            mocks.run
+                .mockResolvedValueOnce({
+                    records: [
+                        record({
+                            rootId: 'root',
+                            owner: 'status-owner',
+                            storedOwner: null,
+                            managed: false,
+                        }),
+                    ],
+                })
+                .mockResolvedValueOnce({ records: [record({ status: null })] })
+                .mockResolvedValueOnce({ records: [record({ owner: 'status-owner' })] });
+            mocks.setBit.mockResolvedValue(false);
+            await expect(
+                mutateCredentialStatus('version', 'recipient', purpose, true)
+            ).rejects.toThrow('Public credential status could not be updated');
+            expect(mocks.run).toHaveBeenCalledTimes(3);
+            expect(mocks.run.mock.calls[2]).toEqual([
+                'MATCH (list:BitstringStatusList {statusListCredential: $url}) RETURN list.ownerProfileId AS owner',
+                { url: entry.statusListCredential },
+            ]);
+            expect(mocks.setBit).toHaveBeenCalledWith(
+                { ...entry, statusPurpose: purpose },
+                true,
+                'status-owner',
+                tx
+            );
+            for (const [query] of mocks.run.mock.calls) {
+                expect(query).not.toMatch(/SET sent\.|SET refresh\.state/);
+            }
+        }
+    );
+    it('reconciles using the stored status owner', async () => {
+        mocks.run.mockResolvedValueOnce({
+            records: [record({ owner: 'status-owner', status: 'revoked' })],
+        });
+        await reconcileCredentialStatus('root', tx);
+        expect(mocks.run.mock.calls[0]?.[0]).toContain(
+            'coalesce(refresh.issuerProfileId, root.statusOwnerProfileId, issuer.profileId) AS owner'
+        );
+        expect(mocks.setBit).toHaveBeenCalledWith(entry, true, 'status-owner', tx);
+    });
+    it.each(['revocation', 'suspension'] as const)(
+        'rejects managed external %s before any writes',
+        async purpose => {
+            mocks.run.mockResolvedValue({ records: [record({ rootId: 'root', managed: true })] });
+            mocks.entries.mockResolvedValue([
+                {
+                    ...entry,
+                    statusPurpose: purpose,
+                    statusListCredential: 'https://provider.example/list',
+                },
+            ]);
+            await expect(
+                mutateCredentialStatus('version', 'recipient', purpose, true)
+            ).rejects.toMatchObject({ code: 'PRECONDITION_FAILED' });
+            expect(mocks.run).toHaveBeenCalledTimes(1);
+            expect(mocks.run.mock.calls[0]?.[0]).not.toContain('SET ');
+            expect(mocks.setBit).not.toHaveBeenCalled();
+        }
+    );
+});

package/src/helpers/credential-status-mutation.helpers.ts

@@ -0,0 +1,166 @@
+import { TRPCError } from '@trpc/server';
+import type { BitstringStatusListEntry, BitstringStatusPurpose } from '@learncard/types';
+import type { Transaction } from 'neo4j-driver';
+
+import { neogma } from '@instance';
+import {
+    CREDENTIAL_STATUS_ROOT_QUERY,
+    getStatusEntriesForCredential,
+    isNetworkStatusEntry,
+    setStatusListEntryBit,
+} from './status-list.helpers';
+
+const assertNetworkManagedPurpose = (
+    entries: BitstringStatusListEntry[],
+    purpose: BitstringStatusPurpose
+): void => {
+    if (entries.some(entry => entry.statusPurpose === purpose && !isNetworkStatusEntry(entry))) {
+        throw new TRPCError({
+            code: 'PRECONDITION_FAILED',
+            message:
+                purpose === 'revocation'
+                    ? "This credential's public revocation is managed outside LearnCard. Revoke it with your status-list provider."
+                    : "This credential's public suspension is managed outside LearnCard. Update it with your status-list provider.",
+        });
+    }
+};
+
+/** Commit relationship state and signed public bits together, including all managed versions. */
+export const mutateCredentialStatus = async (
+    credentialId: string,
+    profileId: string,
+    purpose: BitstringStatusPurpose,
+    value: boolean
+): Promise<boolean> =>
+    neogma.getTransaction(null, async tx => {
+        const result = await tx.run(
+            `${CREDENTIAL_STATUS_ROOT_QUERY}
+         MATCH (sender)-[sent:CREDENTIAL_SENT {to: $profileId}]->(root)
+         WHERE sender:Profile OR sender:AppStoreListing
+         WITH root, refresh, sent
+         OPTIONAL MATCH (issuer:Profile)-[:CREDENTIAL_SENT]->(root)
+         RETURN root.id AS rootId, sent.status AS status,
+                 coalesce(refresh.issuerProfileId, root.statusOwnerProfileId) AS storedOwner,
+                 refresh IS NOT NULL AS managed,
+                 root.statusReservationMode AS reservationMode,
+                 coalesce(refresh.issuerProfileId, root.statusOwnerProfileId, issuer.profileId) AS owner`,
+            { credentialId, profileId, now: new Date().toISOString() }
+        );
+        if (result.records.length === 0) return false;
+        const row = result.records[0]!;
+        const rootId = String(row.get('rootId'));
+        if (row.get('managed')) {
+            assertNetworkManagedPurpose(await getStatusEntriesForCredential(rootId, tx), purpose);
+        }
+        const locked = await tx.run(
+            `MATCH (root:Credential {id: $rootId})
+             SET root._statusMutationLock = true REMOVE root._statusMutationLock
+             WITH root
+             OPTIONAL MATCH (refresh:CredentialRefresh)-[:ROOT]->(root)
+             FOREACH (_ IN CASE WHEN refresh IS NULL THEN [] ELSE [1] END |
+                 SET refresh._statusBindingLock = true REMOVE refresh._statusBindingLock)
+             WITH root
+             MATCH ()-[sent:CREDENTIAL_SENT {to: $profileId}]->(root)
+             RETURN sent.status AS status`,
+            { rootId, profileId }
+        );
+        const allEntries = await getStatusEntriesForCredential(rootId, tx);
+        if (row.get('managed')) assertNetworkManagedPurpose(allEntries, purpose);
+        const status = locked.records[0]?.get('status');
+        if (purpose === 'suspension' && status === 'revoked') return false;
+        if (!value && status !== 'suspended') return false;
+        const entries = allEntries.filter(entry => entry.statusPurpose === purpose);
+        if (allEntries.length > 0 && entries.length === 0) {
+            console.warn(
+                '[mutateCredentialStatus] no public status entry for purpose; relationship-only update',
+                { rootId, purpose }
+            );
+        }
+        for (const entry of [...entries].sort((a, b) =>
+            a.statusListCredential.localeCompare(b.statusListCredential)
+        )) {
+            let owner = String(row.get('owner'));
+            const lenient = !row.get('managed') && row.get('reservationMode') === 'lenient';
+            const legacy = !row.get('managed') && !row.get('storedOwner');
+            if (lenient || legacy) {
+                const list = await tx.run(
+                    'MATCH (list:BitstringStatusList {statusListCredential: $url}) RETURN list.ownerProfileId AS owner',
+                    { url: entry.statusListCredential }
+                );
+                const listOwner: unknown = list.records[0]?.get('owner');
+                if (typeof listOwner !== 'string' || (lenient && listOwner !== owner)) {
+                    console.warn('[credential-status] RELATIONSHIP_ONLY_UNCONTROLLED_STATUS_LIST');
+                    continue;
+                }
+                // Before stored owners existed, lifecycle updates used the matched list,
+                // including contract autoboosts delivered by a different sender.
+                if (legacy) owner = listOwner;
+            }
+            if (!(await setStatusListEntryBit(entry, value, owner, tx))) {
+                throw new TRPCError({
+                    code: 'INTERNAL_SERVER_ERROR',
+                    message: 'Public credential status could not be updated; retry the operation',
+                });
+            }
+        }
+        await tx.run(
+            `MATCH (root:Credential {id: $rootId})<-[sent:CREDENTIAL_SENT {to: $profileId}]-(sender)
+         WHERE sender:Profile OR sender:AppStoreListing
+         SET sent.status = $status
+         FOREACH (_ IN CASE WHEN $purpose = 'revocation' THEN [1] ELSE [] END |
+             SET sent.revokedAt = $now)
+         FOREACH (_ IN CASE WHEN $purpose = 'suspension' AND $value THEN [1] ELSE [] END |
+             SET sent.suspendedAt = $now)
+         FOREACH (_ IN CASE WHEN NOT $value THEN [1] ELSE [] END |
+             SET sent.unsuspendedAt = $now)
+         WITH root
+         OPTIONAL MATCH (refresh:CredentialRefresh)-[:ROOT]->(root)
+         FOREACH (_ IN CASE WHEN refresh IS NOT NULL AND $purpose = 'revocation' THEN [1] ELSE [] END |
+             SET refresh.state = 'revoked', refresh.updatedAt = $now)`,
+            {
+                rootId,
+                profileId,
+                purpose,
+                value,
+                status: purpose === 'revocation' ? 'revoked' : value ? 'suspended' : null,
+                now: new Date().toISOString(),
+            }
+        );
+        return true;
+    });
+
+/** Reconcile historical lifecycle state while holding the same root lock as mutations. */
+export const reconcileCredentialStatus = async (
+    rootId: string,
+    transaction: Transaction
+): Promise<void> => {
+    const result = await transaction.run(
+        `MATCH (root:Credential {id: $rootId})
+         SET root._statusMutationLock = true REMOVE root._statusMutationLock
+         WITH root
+         OPTIONAL MATCH (issuer:Profile)-[sent:CREDENTIAL_SENT]->(root)
+         OPTIONAL MATCH (refresh:CredentialRefresh)-[:ROOT]->(root)
+         RETURN coalesce(refresh.issuerProfileId, root.statusOwnerProfileId, issuer.profileId) AS owner,
+                sent.status AS status, refresh.state AS state`,
+        { rootId }
+    );
+    const row = result.records[0];
+    if (!row)
+        throw new TRPCError({ code: 'CONFLICT', message: 'Credential has no original delivery' });
+    const entries = await getStatusEntriesForCredential(rootId, transaction);
+    for (const entry of [...entries].sort((a, b) =>
+        a.statusListCredential.localeCompare(b.statusListCredential)
+    )) {
+        if (!isNetworkStatusEntry(entry)) continue;
+        const value =
+            entry.statusPurpose === 'revocation'
+                ? row.get('status') === 'revoked' || row.get('state') === 'revoked'
+                : row.get('status') === 'suspended';
+        if (!(await setStatusListEntryBit(entry, value, String(row.get('owner')), transaction))) {
+            throw new TRPCError({
+                code: 'INTERNAL_SERVER_ERROR',
+                message: 'Public credential status could not be updated; retry the operation',
+            });
+        }
+    }
+};

package/src/helpers/credential.helpers.ts

@@ -3,6 +3,7 @@ import { TRPCError } from '@trpc/server';
 import { UnsignedVC, VC, JWE, LCNNotificationTypeEnumValidator } from '@learncard/types';
 
 import { storeCredential } from '@accesslayer/credential/create';
+import { neogma } from '@instance';
 import type { IssuedCredential } from 'types/credential';
 import {
     createReceivedCredentialRelationship,
@@ -42,18 +43,25 @@ export const sendCredential = async (
     domain: string,
     metadata?: Record<string, unknown> | undefined,
     activityId?: string,
-    integrationId?: string
+    integrationId?: string,
+    /** Local profile that owns any local status lists; defaults to the sender. */
+    statusOwnerProfileId: string = from.profileId
 ): Promise<string> => {
-    const credentialInstance = await storeCredential(credential);
-
-    await createSentCredentialRelationship(
-        { type: 'profile', profile: from },
-        to,
-        credentialInstance,
-        metadata,
-        activityId,
-        integrationId
-    );
+    const credentialInstance = await neogma.getTransaction(null, async tx => {
+        const instance = await storeCredential(credential, tx, statusOwnerProfileId, {
+            lenient: true,
+        });
+        await createSentCredentialRelationship(
+            { type: 'profile', profile: from },
+            to,
+            instance,
+            metadata,
+            activityId,
+            integrationId,
+            tx
+        );
+        return instance;
+    });
 
     const uri = getCredentialUri(credentialInstance.id, domain);
 

package/src/helpers/finalize-inbox.helpers.ts

@@ -67,7 +67,7 @@ const finalizeAcceptedDelivery = async (
             await transaction.rollback();
             return false;
         }
-        const instance = await storeCredential(issued, transaction);
+        const instance = await storeCredential(issued, transaction, sender.profileId);
         if (boost) await createBoostInstanceOfRelationship(instance, boost, transaction);
         await createSentCredentialRelationship(
             { type: 'profile', profile: sender },

package/src/helpers/inbox-refresh.helpers.ts

@@ -20,6 +20,9 @@ import { AUTH_GRANT_NO_ACCESS_SCOPE } from '../constants/auth-grant';
 import { ensureCredentialRefreshConstraints } from '../models/credential-refresh-constraints';
 import { getCredentialRefresh, generateRefreshId } from '@accesslayer/credential-refresh';
 import { getInboxCredentialById } from '@accesslayer/inbox-credential/read';
+import { getBoostById } from '@accesslayer/boost/read';
+import { getPublicBoostDisplayName } from './credential-display.helpers';
+import { extractBoundedCredentialDisplayTitle } from './credential-refresh-email-content.helpers';
 import {
     advancePendingInboxRefresh,
     bindPendingInboxRefresh,
@@ -46,8 +49,10 @@ import {
 } from './credential-refresh.helpers';
 import {
     getCredentialRefreshDigestSecret,
+    getCredentialRefreshDigestCandidateSecrets,
     computeCredentialMaterialDigest,
     computeCredentialStatusDigest,
+    matchesCredentialStatusDigest,
     computeCredentialSubjectDigest,
 } from './credential-refresh-materiality.helpers';
 import { appendBitstringStatusListEntries } from './status-list.helpers';
@@ -67,8 +72,11 @@ export const assertInboxRefreshEnabled = async (scope?: string): Promise<void> =
     await ensureCredentialRefreshConstraints();
 };
 
-export const inboxRefreshRequestDigest = (request: unknown): string =>
-    createHmac('sha256', getCredentialRefreshDigestSecret())
+export const inboxRefreshRequestDigest = (
+    request: unknown,
+    secret: string = getCredentialRefreshDigestSecret()
+): string =>
+    createHmac('sha256', secret)
         .update('inbox-refresh-issue:v1\0')
         .update(canonicalizeCredentialJson(request))
         .digest('base64url');
@@ -76,14 +84,23 @@ export const inboxRefreshRequestDigest = (request: unknown): string =>
 export const getInboxRefreshIssueKey = (issuerProfileId: string, key: string): string =>
     `${issuerProfileId}:${key}`;
 
+export const getInboxRefreshRequestDigestCandidates = (request: unknown): string[] =>
+    getCredentialRefreshDigestCandidateSecrets().map(secret =>
+        inboxRefreshRequestDigest(request, secret)
+    );
+
+export const matchesInboxRefreshRequestDigest = (request: unknown, stored: string): boolean =>
+    getInboxRefreshRequestDigestCandidates(request).includes(stored);
+
 export const getInboxRefreshReplay = async (
     issuerProfileId: string,
     key: string | undefined,
-    requestDigest: string
+    requestDigest: string,
+    requestDigestCandidates: string[] = [requestDigest]
 ) => {
     if (!key) return null;
     const existing = await getInboxRefreshIssue(getInboxRefreshIssueKey(issuerProfileId, key));
-    if (existing && existing.requestDigest !== requestDigest)
+    if (existing && !requestDigestCandidates.includes(existing.requestDigest))
         throw new TRPCError({
             code: 'CONFLICT',
             message: 'This idempotencyKey was used for a different inbox issuance.',
@@ -220,7 +237,7 @@ export const publishPendingInboxRefresh = async (
         computeCredentialSubjectDigest(body.credentialSubject) !==
             computeCredentialSubjectDigest(previous.credentialSubject) ||
         body.boostId !== previous.boostId ||
-        computeCredentialStatusDigest(body.credentialStatus) !== aggregate.credentialStatusDigest ||
+        !matchesCredentialStatusDigest(body.credentialStatus, aggregate.credentialStatusDigest) ||
         canonicalizeCredentialJson(body.refreshService) !==
             canonicalizeCredentialJson(previous.refreshService)
     )
@@ -237,14 +254,20 @@ export const publishPendingInboxRefresh = async (
             message: 'Credential effective time is older than the current version',
         });
     const prepared = injectManagedRefreshService(body, serviceFor(aggregate.refreshId, domain));
+    // Public label only: the anchor's explicit display name, never the VC's own name.
+    const displayBoost = aggregate.boostId ? await getBoostById(aggregate.boostId) : null;
+    const credentialName = extractBoundedCredentialDisplayTitle(
+        getPublicBoostDisplayName(displayBoost)
+    );
     const result = await advancePendingInboxRefresh({
         refreshId: aggregate.refreshId,
         expectedVersion: aggregate.currentVersion,
         credential: await encryptInboxCredential(JSON.stringify(prepared)),
-        credentialName: typeof prepared.name === 'string' ? prepared.name : undefined,
+        ...(credentialName ? { credentialName } : {}),
         materialDigest: computeCredentialMaterialDigest(prepared),
         idempotencyKey: input.idempotencyKey,
         updateSummary: input.updateSummary,
+        updateReason: input.updateReason,
     });
     if (!result)
         throw new TRPCError({
@@ -328,8 +351,10 @@ export const finalizeInboxRefresh = async (params: {
             getCredentialIssuerId(credential) !== aggregate.issuerDid ||
             computeCredentialSubjectDigest(credential.credentialSubject) !==
                 computeCredentialSubjectDigest(unsigned.credentialSubject) ||
-            computeCredentialStatusDigest(credential.credentialStatus) !==
-                aggregate.credentialStatusDigest ||
+            !matchesCredentialStatusDigest(
+                credential.credentialStatus,
+                aggregate.credentialStatusDigest
+            ) ||
             canonicalizeCredentialJson(credential.refreshService) !==
                 canonicalizeCredentialJson(unsigned.refreshService) ||
             computeCredentialMaterialDigest(credential) !==
@@ -386,6 +411,7 @@ export const finalizeInboxRefresh = async (params: {
                     ? {}
                     : { effectiveAt: new Date(effectiveTime).toISOString() }),
                 ...(aggregate.updateSummary ? { updateSummary: aggregate.updateSummary } : {}),
+                ...(aggregate.updateReason ? { updateReason: aggregate.updateReason } : {}),
                 etag,
             },
             aggregate: {

package/src/helpers/inbox.helpers.ts

@@ -207,6 +207,7 @@ export const issueToInbox = async (
         refresh?: boolean;
         idempotencyKey?: string;
         refreshRequestDigest?: string;
+        refreshRequestDigestCandidates?: string[];
     } = {},
     ctx: Context,
     /** Queue ownership checkpoint immediately before delivery or inbox persistence. */
@@ -484,6 +485,7 @@ export const issueToInbox = async (
                               configuration.idempotencyKey ?? randomUUID()
                           ),
                           requestDigest: configuration.refreshRequestDigest!,
+                          requestDigestCandidates: configuration.refreshRequestDigestCandidates,
                       },
                   }
                 : {}),

package/src/helpers/learnCard.helpers.ts

@@ -231,6 +231,29 @@ export const createDagJweForRecipients = async <T>(
     return wallet.invoke.createDagJwe(cleartext, recipients);
 };
 
+/**
+ * Resolves `did`'s key-agreement verification-method id — the exact `kid` DIDKit
+ * assigns that recipient in a DAG-JWE (see `createDagJweForRecipients`). Used to
+ * publish the expected holder-mode encryption recipient set (LC-2345) without ever
+ * performing the encryption itself.
+ */
+export const getKeyAgreementKeyId = async (
+    did: string,
+    seed = environment.SEED
+): Promise<string> => {
+    const learnCard = await getLearnCard(seed);
+    const doc = await learnCard.invoke.resolveDid(did);
+    const [agreement] = doc.keyAgreement ?? [];
+
+    if (!agreement) {
+        throw new Error(`No key-agreement verification method found for DID: ${did}`);
+    }
+
+    const id = typeof agreement === 'string' ? agreement : agreement.id;
+
+    return id.startsWith('#') ? `${doc.id}${id}` : id;
+};
+
 export const getServerDidWebDID = (): string => {
     const domainName = environment.DOMAIN_NAME;
     const isOffline = !!environment.IS_OFFLINE;

package/src/helpers/managed-status.helpers.test.ts

@@ -0,0 +1,101 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import type { Transaction } from 'neo4j-driver';
+import type { BitstringStatusListEntry } from '@learncard/types';
+
+const mocks = vi.hoisted(() => ({
+    run: vi.fn(),
+    transaction: vi.fn(),
+    allocate: vi.fn(),
+    validate: vi.fn(),
+    getRefresh: vi.fn(),
+    reconcile: vi.fn(),
+}));
+vi.mock('@instance', () => ({ neogma: { getTransaction: mocks.transaction } }));
+vi.mock('./status-list.helpers', () => ({
+    allocateStatusListEntry: mocks.allocate,
+    validateStatusEntries: mocks.validate,
+    isNetworkStatusEntry: (entry: BitstringStatusListEntry) =>
+        new URL(entry.statusListCredential).hostname === 'network.example',
+}));
+vi.mock('@accesslayer/credential-refresh', () => ({ getCredentialRefresh: mocks.getRefresh }));
+vi.mock('./credential-status-mutation.helpers', () => ({
+    reconcileCredentialStatus: mocks.reconcile,
+}));
+import { bindRefreshStatusEntries, prepareRefreshStatusEntries } from './managed-status.helpers';
+
+const entry: BitstringStatusListEntry = {
+    type: 'BitstringStatusListEntry',
+    statusPurpose: 'revocation',
+    statusListIndex: '7',
+    statusListCredential: 'https://network.example/status-lists/list',
+};
+const tx = { run: mocks.run } as unknown as Transaction;
+const record = (values: Record<string, unknown>) => ({
+    get: (key: string): unknown => values[key] ?? null,
+});
+
+describe('managed status binding', () => {
+    beforeEach(() => {
+        vi.resetAllMocks();
+        mocks.transaction.mockImplementation(
+            async (_existing: unknown, callback: (transaction: Transaction) => Promise<unknown>) =>
+                callback(tx)
+        );
+        mocks.getRefresh.mockResolvedValue(null);
+        mocks.allocate.mockResolvedValue(entry);
+        mocks.run.mockImplementation(async (query: string) => ({
+            records: query.includes('RETURN refresh.statusEntries AS entries')
+                ? [record({ rootId: 'root' })]
+                : [],
+        }));
+    });
+    it('returns after the locked read on a second matching bind', async () => {
+        await bindRefreshStatusEntries('refresh', [entry], 'owner', 'network.example');
+        expect(mocks.reconcile).toHaveBeenCalledWith('root', tx);
+        mocks.run.mockClear();
+        mocks.reconcile.mockClear();
+        mocks.run.mockResolvedValue({
+            records: [record({ entries: JSON.stringify([entry]), rootId: 'root' })],
+        });
+        await bindRefreshStatusEntries('refresh', [entry], 'owner', 'network.example');
+        expect(mocks.run).toHaveBeenCalledTimes(1);
+        expect(mocks.run.mock.calls[0]?.[0]).toContain('SET refresh._statusBindingLock = true');
+        expect(mocks.reconcile).not.toHaveBeenCalled();
+    });
+    it('rejects mismatching stored coordinates', async () => {
+        mocks.run.mockResolvedValue({
+            records: [
+                record({
+                    entries: JSON.stringify([{ ...entry, statusListIndex: '8' }]),
+                    rootId: 'root',
+                }),
+            ],
+        });
+        await expect(
+            bindRefreshStatusEntries('refresh', [entry], 'owner', 'network.example')
+        ).rejects.toThrow('Credential status does not match allocated entries');
+        expect(mocks.run).toHaveBeenCalledTimes(1);
+        expect(mocks.reconcile).not.toHaveBeenCalled();
+    });
+    it('skips the legacy scan only for freshly allocated entries', async () => {
+        await expect(
+            prepareRefreshStatusEntries('refresh', 'owner', 'network.example')
+        ).resolves.toEqual([entry]);
+        expect(mocks.run).not.toHaveBeenCalledWith(
+            expect.stringContaining('credential.statusEntries CONTAINS $url'),
+            expect.anything()
+        );
+        expect(mocks.run).toHaveBeenCalledWith(
+            expect.stringContaining('SET binding.refreshId = $refreshId'),
+            expect.anything()
+        );
+        expect(mocks.reconcile).toHaveBeenCalledWith('root', tx);
+    });
+    it('retains the legacy scan for pre-signed and repair entries', async () => {
+        await bindRefreshStatusEntries('refresh', [entry], 'owner', 'network.example', tx);
+        expect(mocks.run).toHaveBeenCalledWith(
+            expect.stringContaining('credential.statusEntries CONTAINS $url'),
+            { ownerProfileId: 'owner', refreshId: 'refresh', url: entry.statusListCredential }
+        );
+    });
+});