@learncard/network-brain-service 3.17.0 → 3.19.0

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

@@ -0,0 +1,77 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+const mocks = vi.hoisted(() => ({ findOne: vi.fn(), session: vi.fn(), transaction: vi.fn() }));
+vi.mock('@environment', () => ({ environment: {} }));
+vi.mock('@models', () => ({ Credential: { findOne: mocks.findOne } }));
+vi.mock('@instance', () => ({
+    neogma: { driver: { session: mocks.session }, getTransaction: mocks.transaction },
+}));
+vi.mock('@helpers/learnCard.helpers', () => ({
+    getLearnCard: vi.fn(),
+    getDidWebLearnCard: vi.fn(),
+}));
+
+import { setCredentialBitstringStatus } from './status-list.helpers';
+
+describe('stored credential status validation', () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+    });
+
+    it.each(['{truncated', 'null', '{}', '[null]', '[{}]', '"not an array"'])(
+        'returns false for malformed status metadata (%s) without starting a status write',
+        async statusEntries => {
+            mocks.findOne.mockResolvedValue({ statusEntries, credential: '{}' });
+            await expect(
+                setCredentialBitstringStatus('credential', 'revocation', true)
+            ).resolves.toBe(false);
+            expect(mocks.session).not.toHaveBeenCalled();
+        }
+    );
+
+    it('returns false when legacy credential JSON cannot be parsed', async () => {
+        mocks.findOne.mockResolvedValue({ credential: '{truncated' });
+        await expect(setCredentialBitstringStatus('credential', 'suspension', true)).resolves.toBe(
+            false
+        );
+        expect(mocks.session).not.toHaveBeenCalled();
+    });
+
+    it('returns false for valid empty metadata or a missing credential', async () => {
+        mocks.findOne
+            .mockResolvedValueOnce({ statusEntries: '[]', credential: '{}' })
+            .mockResolvedValueOnce(null);
+        expect(await setCredentialBitstringStatus('credential', 'revocation', true)).toBe(false);
+        expect(await setCredentialBitstringStatus('missing', 'revocation', true)).toBe(false);
+    });
+
+    it('returns false when a valid entry cannot be updated', async () => {
+        mocks.findOne.mockResolvedValue({
+            statusEntries: JSON.stringify([
+                {
+                    type: 'BitstringStatusListEntry',
+                    statusPurpose: 'revocation',
+                    statusListIndex: '42',
+                    statusListCredential: 'https://network.example/status/1',
+                },
+            ]),
+        });
+        mocks.transaction.mockResolvedValue(false);
+        expect(await setCredentialBitstringStatus('credential', 'revocation', true)).toBe(false);
+    });
+
+    it('rejects malformed numeric coordinates before any status write', async () => {
+        mocks.findOne.mockResolvedValue({
+            statusEntries: JSON.stringify([
+                {
+                    type: 'BitstringStatusListEntry',
+                    statusPurpose: 'revocation',
+                    statusListIndex: 'not-a-number',
+                    statusListCredential: 'https://network.example/status/1',
+                },
+            ]),
+        });
+        expect(await setCredentialBitstringStatus('credential', 'revocation', true)).toBe(false);
+        expect(mocks.transaction).not.toHaveBeenCalled();
+    });
+});

package/src/helpers/status-list.helpers.ts

@@ -8,7 +8,10 @@ import type {
     UnsignedVC,
     VC,
 } from '@learncard/types';
-import { DEFAULT_BITSTRING_STATUS_LIST_SIZE } from '@learncard/types';
+import {
+    BitstringStatusListEntryValidator,
+    DEFAULT_BITSTRING_STATUS_LIST_SIZE,
+} from '@learncard/types';
 import {
     getBitstringStatusListEntries,
     getCredentialStatusArray,
@@ -397,16 +400,36 @@ export const setCredentialBitstringStatus = async (
     const credential = await Credential.findOne({ where: { id: credentialId } });
     if (!credential) return false;
 
-    const parsedCredential = JSON.parse(credential.credential);
-    const entries = getBitstringStatusListEntries(parsedCredential).filter(
-        entry => entry.statusPurpose === statusPurpose
-    );
+    // Encrypted SA credentials retain only public status coordinates separately.
+    // Legacy plaintext/wrapped credentials continue using their embedded entries.
+    let statusEntries: BitstringStatusListEntry[];
+    try {
+        statusEntries = BitstringStatusListEntryValidator.array().parse(
+            credential.statusEntries
+                ? JSON.parse(credential.statusEntries)
+                : getBitstringStatusListEntries(JSON.parse(credential.credential))
+        );
+        if (
+            statusEntries.some(
+                entry =>
+                    !Number.isSafeInteger(Number(entry.statusListIndex)) ||
+                    Number(entry.statusListIndex) < 0
+            )
+        ) {
+            throw new Error('Invalid status list index');
+        }
+    } catch {
+        console.error('[setCredentialBitstringStatus] Invalid stored status entries', {
+            credentialId,
+        });
+        return false;
+    }
+    const entries = statusEntries.filter(entry => entry.statusPurpose === statusPurpose);
 
     if (entries.length === 0) return false;
 
-    await Promise.all(entries.map(entry => setStatusListEntryBit(entry, value)));
-
-    return true;
+    const updated = await Promise.all(entries.map(entry => setStatusListEntryBit(entry, value)));
+    return updated.every(Boolean);
 };
 
 export const getSignedStatusListCredential = async (id: string): Promise<VC | null> => {

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/ConsentFlowTerms.ts

@@ -26,6 +26,10 @@ export const ConsentFlowTerms = ModelFactory<FlatDbTermsType, ConsentFlowTermsRe
             expiresAt: { type: 'string', required: false },
             oneTime: { type: 'boolean', required: false },
             deniedWriters: { type: 'string[]', required: false },
+            'guardianApproval.guardianProfileId': { type: 'string', required: false },
+            'guardianApproval.guardianDid': { type: 'string', required: false },
+            'guardianApproval.approvedAt': { type: 'string', required: false },
+            'guardianApproval.contractUpdatedAt': { type: 'string', required: false },
         } as any,
         relationships: {
             createdBy: { model: Profile, direction: 'out', name: 'CREATED_BY' },

package/src/models/ConsentFlowTransaction.ts

@@ -24,6 +24,10 @@ export const ConsentFlowTransaction = ModelFactory<
             status: { type: 'string', required: true },
             expiresAt: { type: 'string', required: false },
             oneTime: { type: 'boolean', required: false },
+            'guardianApproval.guardianProfileId': { type: 'string', required: false },
+            'guardianApproval.guardianDid': { type: 'string', required: false },
+            'guardianApproval.approvedAt': { type: 'string', required: false },
+            'guardianApproval.contractUpdatedAt': { type: 'string', required: false },
         } as any,
         relationships: { isFor: { model: ConsentFlowTerms, direction: 'out', name: 'IS_FOR' } },
         primaryKeyField: 'id',

package/src/models/Credential.ts

@@ -33,6 +33,7 @@ export const Credential = ModelFactory<CredentialType, CredentialRelationships>(
         schema: {
             id: { type: 'string', required: true, uniqueItems: true },
             credential: { type: 'string', required: true },
+            statusEntries: { type: 'string', required: false },
         },
         primaryKeyField: 'id',
     },

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.

package/src/routes/act-as.test.ts

@@ -0,0 +1,239 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { resolveTenantFromRequest } from '@learncard/email-templates';
+import { ACT_AS_HEADER, AUTH_GRANT_AUDIENCE_DOMAIN_PREFIX } from '@learncard/types';
+import type { ProfileType } from 'types/profile';
+
+const mocks = vi.hoisted(() => ({
+    getProfileByDid: vi.fn(),
+    getProfileByProfileId: vi.fn(),
+    getProfilesThatManageAProfile: vi.fn(),
+    grant: vi.fn(),
+    verifyPresentation: vi.fn(),
+    isAuthGrantAssociatedWithProfile: vi.fn(),
+    getAuthGrantById: vi.fn(),
+    updateAuthGrant: vi.fn(),
+}));
+
+vi.mock('@accesslayer/profile/read', () => ({
+    getProfileByDid: mocks.getProfileByDid,
+    getProfileByProfileId: mocks.getProfileByProfileId,
+}));
+vi.mock('@accesslayer/profile/relationships/read', () => ({
+    getProfilesThatManageAProfile: mocks.getProfilesThatManageAProfile,
+}));
+vi.mock('@accesslayer/auth-grant/read', () => ({
+    isAuthGrantChallengeValidForDID: mocks.grant,
+    isAuthGrantAssociatedWithProfile: mocks.isAuthGrantAssociatedWithProfile,
+    getAuthGrantById: mocks.getAuthGrantById,
+}));
+vi.mock('@accesslayer/auth-grant/update', () => ({ updateAuthGrant: mocks.updateAuthGrant }));
+vi.mock('@helpers/learnCard.helpers', () => ({
+    getEmptyLearnCard: async () => ({ invoke: { verifyPresentation: mocks.verifyPresentation } }),
+}));
+
+import { createContext, didRoute, profileRoute, t, type Context } from './index';
+import { profilesRouter } from './profiles';
+import { authGrantsRouter } from './auth-grants';
+
+const domain = 'network.example.com';
+const manager: ProfileType = {
+    profileId: 'manager',
+    did: 'did:key:manager',
+    displayName: 'Manager',
+    shortBio: '',
+    bio: '',
+};
+const target: ProfileType = {
+    profileId: 'the-id',
+    did: `did:web:${domain}:users:the-id`,
+    displayName: 'District',
+    shortBio: '',
+    bio: '',
+};
+const inspectionRouter = t.router({
+    context: didRoute.query(({ ctx }) => ctx.user),
+    writeInbox: profileRoute.meta({ requiredScope: 'inbox:write' }).query(() => true),
+    writeBoost: profileRoute.meta({ requiredScope: 'boosts:write' }).query(() => true),
+});
+const context = (overrides: Partial<Context> = {}): Context => ({
+    domain,
+    tenant: resolveTenantFromRequest({}),
+    actAs: target.profileId,
+    user: { did: manager.did, isChallengeValid: true, scope: '*:*' },
+    ...overrides,
+});
+
+beforeEach(() => {
+    vi.resetAllMocks();
+    mocks.getProfileByDid.mockResolvedValue(manager);
+    mocks.getProfileByProfileId.mockImplementation(async (id: string) =>
+        id === target.profileId ? target : null
+    );
+    mocks.getProfilesThatManageAProfile.mockResolvedValue([manager]);
+    mocks.verifyPresentation.mockResolvedValue({ warnings: [], errors: [], checks: ['JWS'] });
+});
+
+describe('act as a managed profile', () => {
+    it.each([target.profileId, target.did])('accepts seed-auth delegation to %s', async actAs => {
+        const ctx = context({ actAs });
+        await expect(profilesRouter.createCaller(ctx).getProfile()).resolves.toMatchObject(target);
+        await expect(inspectionRouter.createCaller(ctx).context()).resolves.toMatchObject({
+            did: target.did,
+            profile: target,
+            onBehalfOf: manager.profileId,
+            scope: '*:*',
+        });
+        expect(ctx.user?.did).toBe(manager.did);
+        expect(mocks.getProfilesThatManageAProfile).toHaveBeenCalledWith(target.profileId);
+    });
+
+    it('rejects a profile the caller does not manage', async () => {
+        mocks.getProfilesThatManageAProfile.mockResolvedValue([]);
+        await expect(inspectionRouter.createCaller(context()).context()).rejects.toMatchObject({
+            code: 'FORBIDDEN',
+            message: 'You do not manage profile "the-id".',
+        });
+    });
+
+    it('rejects an unknown profile', async () => {
+        await expect(
+            inspectionRouter.createCaller(context({ actAs: 'missing' })).context()
+        ).rejects.toMatchObject({ code: 'NOT_FOUND' });
+    });
+
+    it.each([
+        'did:key:other',
+        'did:web:elsewhere:users:the-id',
+        `did:web:${domain}:manager:the-id`,
+        `${target.did}:extra`,
+    ])('rejects an unsupported DID: %s', async actAs => {
+        await expect(
+            inspectionRouter.createCaller(context({ actAs })).context()
+        ).rejects.toMatchObject({ code: 'BAD_REQUEST' });
+    });
+
+    it.each([
+        [undefined, false],
+        ['', false],
+        ['*', true],
+        ['other-id', false],
+        ['the-id,other', true],
+        [' other, the-id ', true],
+    ] as const)('enforces token policy %s (allowed: %s)', async (actAs, allowed) => {
+        mocks.grant.mockResolvedValue({ isChallengeValid: true, scope: 'inbox:write', actAs });
+        const payload = Buffer.from(
+            JSON.stringify({
+                vp: { holder: manager.did },
+                nonce: `${AUTH_GRANT_AUDIENCE_DOMAIN_PREFIX}test`,
+            })
+        ).toString('base64url');
+        const ctx = await createContext({
+            req: {
+                headers: new Map([
+                    ['authorization', `Bearer e30.${payload}.signature`],
+                    [ACT_AS_HEADER, target.profileId],
+                ]),
+            },
+        });
+        const caller = inspectionRouter.createCaller(ctx);
+        if (!allowed) {
+            await expect(caller.context()).rejects.toMatchObject({
+                code: 'FORBIDDEN',
+                message: 'This API token may not act as "the-id". Grant actAs on the token.',
+            });
+            return;
+        }
+        await expect(caller.context()).resolves.toMatchObject({
+            profile: target,
+            did: target.did,
+            onBehalfOf: manager.profileId,
+            scope: 'inbox:write',
+            isAuthGrant: true,
+            actAsPolicy: actAs,
+        });
+        await expect(caller.writeInbox()).resolves.toBe(true);
+        await expect(caller.writeBoost()).rejects.toMatchObject({ code: 'UNAUTHORIZED' });
+    });
+
+    it('leaves the authenticated identity unchanged without a header', async () => {
+        const result = await inspectionRouter.createCaller(context({ actAs: undefined })).context();
+        expect(result).toMatchObject({ profile: manager, did: manager.did, scope: '*:*' });
+        expect(result.onBehalfOf).toBeUndefined();
+    });
+
+    it.each([ACT_AS_HEADER, ACT_AS_HEADER.toLowerCase(), ACT_AS_HEADER.toUpperCase()])(
+        'reads header %s without resolving a profile in createContext',
+        async name => {
+            const ctx = await createContext({ req: { headers: new Map([[name, target.did]]) } });
+            expect(ctx.actAs).toBe(target.did);
+            expect(mocks.getProfileByProfileId).not.toHaveBeenCalled();
+        }
+    );
+});
+
+describe('act-as ordering', () => {
+    it('does not resolve the target when the challenge is not verified', async () => {
+        const ctx = context({ user: { did: manager.did, isChallengeValid: false, scope: '*:*' } });
+        await expect(inspectionRouter.createCaller(ctx).context()).resolves.toMatchObject({
+            did: manager.did,
+        });
+        expect(mocks.getProfileByProfileId).not.toHaveBeenCalled();
+        expect(mocks.getProfilesThatManageAProfile).not.toHaveBeenCalled();
+    });
+
+    it('treats a blank header as no delegation', async () => {
+        const ctx = context({ actAs: '   ' });
+        await expect(inspectionRouter.createCaller(ctx).context()).resolves.toMatchObject({
+            did: manager.did,
+        });
+        expect(mocks.getProfileByProfileId).not.toHaveBeenCalled();
+    });
+});
+
+describe('auth grant actAs is immutable', () => {
+    const grant = {
+        id: 'grant-1',
+        name: 'svc',
+        challenge: `${AUTH_GRANT_AUDIENCE_DOMAIN_PREFIX}test`,
+        status: 'active',
+        scope: 'inbox:write',
+        createdAt: '2026-01-01T00:00:00.000Z',
+        actAs: '*',
+    };
+
+    beforeEach(() => {
+        mocks.isAuthGrantAssociatedWithProfile.mockResolvedValue(true);
+        mocks.getAuthGrantById.mockResolvedValue(grant);
+        mocks.updateAuthGrant.mockResolvedValue(true);
+    });
+
+    it.each([{ actAs: 'the-id' }, { actAs: '*' }, { scope: '*:*' }, { status: 'revoked' }])(
+        'rejects %j with BAD_REQUEST instead of silently dropping it',
+        async updates => {
+            const caller = authGrantsRouter.createCaller(context({ actAs: undefined }));
+            await expect(
+                caller.updateAuthGrant({ id: grant.id, updates: updates as never })
+            ).rejects.toMatchObject({
+                code: 'BAD_REQUEST',
+                message: expect.stringContaining('Cannot update id, scope, actAs'),
+            });
+            expect(mocks.updateAuthGrant).not.toHaveBeenCalled();
+        }
+    );
+
+    it('rejects unknown keys', async () => {
+        const caller = authGrantsRouter.createCaller(context({ actAs: undefined }));
+        await expect(
+            caller.updateAuthGrant({ id: grant.id, updates: { bogus: true } as never })
+        ).rejects.toMatchObject({ code: 'BAD_REQUEST' });
+        expect(mocks.updateAuthGrant).not.toHaveBeenCalled();
+    });
+
+    it('still allows mutable fields', async () => {
+        const caller = authGrantsRouter.createCaller(context({ actAs: undefined }));
+        await expect(
+            caller.updateAuthGrant({ id: grant.id, updates: { description: 'renamed' } })
+        ).resolves.toBe(true);
+        expect(mocks.updateAuthGrant).toHaveBeenCalledWith(grant, { description: 'renamed' });
+    });
+});