@aurorajs.dev/catalyst-cli 1.1.3 → 2.0.0

package/dist/templates/backend/packages/iam/src/@app/iam/account/application/update/iam-update-account-by-id.handler.spec.ts

@@ -1,17 +1,19 @@
-import { IamAccount, IamAccountTypeEnum, IamUpdateAccountByIdInput } from '@api/graphql';
+import type { Mock } from 'vitest';
+import { IamAccount, IamAccountTypeEnum, IamUpdateAccountByIdInput } from '@api/graphql.js';
 import {
   IamFindAccountByIdService,
   IamGetAccountsService,
   IamUpdateAccountByIdService,
-} from '@app/iam/account';
-import { IamGetRolesService } from '@app/iam/role';
-import { IamPermissions } from '@app/iam/shared';
-import { IamGetTenantsService } from '@app/iam/tenant';
-import { IamUpdateUserByIdService } from '@app/iam/user';
-import { IAM_CLIENT_READER } from '@bridges/iam/client';
+} from '@app/iam/account/index.js';
+import { IamGetRolesService } from '@app/iam/role/index.js';
+import { IamPermissions } from '@app/iam/shared/index.js';
+import { IamGetTenantsService } from '@app/iam/tenant/index.js';
+import { IamUpdateUserByIdService } from '@app/iam/user/index.js';
+import { mapToAuthenticatedAccount } from '@bridges/iam/account/adapters/iam-account-loader.adapter.js';
+import { IAM_CLIENT_READER } from '@bridges/iam/client/index.js';
 import { EventEmitter2 } from '@nestjs/event-emitter';
 import { Test, TestingModule } from '@nestjs/testing';
-import { IamUpdateAccountByIdHandler } from './iam-update-account-by-id.handler';
+import { IamUpdateAccountByIdHandler } from './iam-update-account-by-id.handler.js';
 
 const ACCOUNT_ID = 'a1111111-a111-4111-8111-111111111111';
 const CLIENT_OLD = 'c0000000-c000-4000-8000-000000000001';
@@ -20,6 +22,27 @@ const ROLE_NEW = 'b1111111-b111-4111-8111-111111111111';
 const USER_ID = 'e1111111-e111-4111-8111-111111111111';
 const COLLIDER_ID = 'f0000000-f000-4000-8000-000000000000';
 const CALLER_ID = 'd0000000-0000-4000-8000-000000000000';
+const T_ROOT = '11111111-1111-4111-8111-111111111111';
+const T_CHILD_1 = '11111111-1111-4111-8111-111111111112';
+const T_CHILD_2 = '11111111-1111-4111-8111-111111111113';
+const T_OTHER = '22222222-2222-4222-8222-222222222222';
+
+/**
+ * A rejection driven by `readonly: true` (in `sanitize-record.function.ts`) is not the ONLY way
+ * `@ApplySchema` can throw a BadRequestException — e.g. ArrayTypeHandler's null-element rule
+ * (in `array.type-handler.ts`) throws one too, with a DIFFERENT message. Asserting only
+ * `rejects.toThrow(BadRequestException)` would still pass if the readonly enforcement were
+ * reverted and the null-element rule alone kept firing — matching the exact
+ * `buildReadonlyFieldRejectedMessage` shape (in `type-handler.types.ts`) is what makes the
+ * test fail for the RIGHT reason.
+ */
+const readonlyRejection = (field: string) => ({
+  response: {
+    message: expect.arrayContaining([
+      expect.stringMatching(new RegExp(`^${field}: property is readonly`)),
+    ]),
+  },
+});
 
 const buildExisting = (overrides: Partial<IamAccount> = {}): IamAccount =>
   ({
@@ -46,37 +69,40 @@ const buildPayload = (
   ...overrides,
 });
 
+// Routed through the real `mapToAuthenticatedAccount` (not a hand-fabricated cast literal) so a
+// field the mapper forgets to carry — e.g. `hasAddChildTenants` — fails the tests that depend on
+// it instead of silently defaulting to `undefined` only in production.
 const buildCaller = (overrides: Partial<IamAccount> = {}): IamAccount =>
-  ({
+  mapToAuthenticatedAccount({
     id: CALLER_ID,
     dPermissions: { all: ['p1', 'p2', 'p3', IamPermissions.SUDO] },
     ...overrides,
-  }) as unknown as IamAccount;
+  } as unknown as IamAccount) as unknown as IamAccount;
 
 describe('IamUpdateAccountByIdHandler', () => {
   let handler: IamUpdateAccountByIdHandler;
-  let updateByIdService: { main: jest.Mock };
-  let findByIdService: { main: jest.Mock };
-  let getAccountsService: { main: jest.Mock };
-  let getRolesService: { main: jest.Mock };
-  let getTenantsService: { main: jest.Mock };
-  let clientReader: { findByIdWithApplications: jest.Mock };
-  let userUpdateByIdService: { main: jest.Mock };
-  let eventEmitter: { emit: jest.Mock };
+  let updateByIdService: { main: Mock };
+  let findByIdService: { main: Mock };
+  let getAccountsService: { main: Mock };
+  let getRolesService: { main: Mock };
+  let getTenantsService: { main: Mock };
+  let clientReader: { findByIdWithApplications: Mock };
+  let userUpdateByIdService: { main: Mock };
+  let eventEmitter: { emit: Mock };
 
   beforeEach(async () => {
-    updateByIdService = { main: jest.fn().mockResolvedValue(undefined) };
-    findByIdService = { main: jest.fn().mockResolvedValue(buildExisting()) };
-    getAccountsService = { main: jest.fn().mockResolvedValue([]) };
-    getRolesService = { main: jest.fn().mockResolvedValue([]) };
-    getTenantsService = { main: jest.fn().mockResolvedValue([]) };
+    updateByIdService = { main: vi.fn().mockResolvedValue(undefined) };
+    findByIdService = { main: vi.fn().mockResolvedValue(buildExisting()) };
+    getAccountsService = { main: vi.fn().mockResolvedValue([]) };
+    getRolesService = { main: vi.fn().mockResolvedValue([]) };
+    getTenantsService = { main: vi.fn().mockResolvedValue([]) };
     clientReader = {
-      findByIdWithApplications: jest
+      findByIdWithApplications: vi
         .fn()
         .mockResolvedValue({ id: CLIENT_OLD, applicationCodes: [] }),
     };
-    userUpdateByIdService = { main: jest.fn().mockResolvedValue(undefined) };
-    eventEmitter = { emit: jest.fn() };
+    userUpdateByIdService = { main: vi.fn().mockResolvedValue(undefined) };
+    eventEmitter = { emit: vi.fn() };
 
     const module: TestingModule = await Test.createTestingModule({
       providers: [
@@ -101,6 +127,9 @@ describe('IamUpdateAccountByIdHandler', () => {
     expect(clientReader.findByIdWithApplications).not.toHaveBeenCalled();
     expect(getRolesService.main).not.toHaveBeenCalled();
     expect(updateByIdService.main).toHaveBeenCalledTimes(1);
+    const persisted = updateByIdService.main.mock.calls[0][0];
+    expect(persisted).not.toHaveProperty('dApplicationCodes');
+    expect(persisted).not.toHaveProperty('dPermissions');
   });
 
   it('fetches the existing account via the Aurora Query DSL — relations.user (not Sequelize include)', async () => {
@@ -109,7 +138,7 @@ describe('IamUpdateAccountByIdHandler', () => {
     expect(findByIdService.main).toHaveBeenCalledTimes(2); // fetch existing + final re-fetch
     const [, constraintArg] = findByIdService.main.mock.calls[0];
     expect(constraintArg).not.toHaveProperty('include');
-    expect(constraintArg.relations).toEqual({ user: true });
+    expect(constraintArg.relations).toEqual({ user: true, tenants: true });
   });
 
   it('queries roles via the Aurora Query DSL — relations.permissions (not Sequelize include)', async () => {
@@ -149,44 +178,97 @@ describe('IamUpdateAccountByIdHandler', () => {
     expect(persisted.dPermissions).toEqual({ all: ['p_new'], [ROLE_NEW]: ['p_new'] });
   });
 
-  it('strips a client-supplied dTenants when tenantIds is not provided', async () => {
-    await handler.main(buildPayload({ dTenants: ['x', 'y'] }), buildCaller());
+  it('rejects a client-supplied dTenants when tenantIds is not provided', async () => {
+    const payload = {
+      ...buildPayload(),
+      dTenants: ['x', 'y'],
+    } as IamUpdateAccountByIdInput;
 
-    const persisted = updateByIdService.main.mock.calls[0][0];
-    expect(persisted.dTenants).not.toEqual(['x', 'y']);
-    expect(persisted).not.toHaveProperty('dTenants');
+    await expect(handler.main(payload, buildCaller())).rejects.toMatchObject(
+      readonlyRejection('dTenants'),
+    );
+    expect(updateByIdService.main).not.toHaveBeenCalled();
   });
 
-  it('strips a client-supplied dApplicationCodes when clientId does not change', async () => {
-    await handler.main(buildPayload({ dApplicationCodes: ['APP_HACKED'] }), buildCaller());
+  it('rejects a client-supplied dApplicationCodes when clientId does not change', async () => {
+    const payload = {
+      ...buildPayload(),
+      dApplicationCodes: ['APP_HACKED'],
+    } as IamUpdateAccountByIdInput;
 
+    await expect(handler.main(payload, buildCaller())).rejects.toMatchObject(
+      readonlyRejection('dApplicationCodes'),
+    );
     expect(clientReader.findByIdWithApplications).not.toHaveBeenCalled();
-    const persisted = updateByIdService.main.mock.calls[0][0];
-    expect(persisted.dApplicationCodes).not.toEqual(['APP_HACKED']);
-    expect(persisted).not.toHaveProperty('dApplicationCodes');
+    expect(updateByIdService.main).not.toHaveBeenCalled();
   });
 
-  it('strips a client-supplied dPermissions when roleIds is not provided', async () => {
-    await handler.main(
-      buildPayload({ dPermissions: { all: [IamPermissions.SUDO] } }),
-      buildCaller(),
-    );
+  it('rejects a client-supplied dPermissions when roleIds is not provided', async () => {
+    const payload = {
+      ...buildPayload(),
+      dPermissions: { all: [IamPermissions.SUDO] },
+    } as IamUpdateAccountByIdInput;
 
+    await expect(handler.main(payload, buildCaller())).rejects.toMatchObject(
+      readonlyRejection('dPermissions'),
+    );
     expect(getRolesService.main).not.toHaveBeenCalled();
+    expect(updateByIdService.main).not.toHaveBeenCalled();
+  });
+
+  it('rejects a client-supplied dTenants containing a null entry when tenantIds is not provided (production incident)', async () => {
+    const payload = {
+      ...buildPayload(),
+      dTenants: ['tenant-a', null as unknown as string, 'tenant-b'],
+    } as IamUpdateAccountByIdInput;
+
+    await expect(handler.main(payload, buildCaller())).rejects.toMatchObject(
+      readonlyRejection('dTenants'),
+    );
+    expect(updateByIdService.main).not.toHaveBeenCalled();
+  });
+
+  it('persists only the direct tenantIds and expands descendants into dTenants when hasAddChildTenants is true', async () => {
+    getTenantsService.main.mockResolvedValueOnce([
+      { id: T_ROOT, parentId: null },
+      { id: T_CHILD_1, parentId: T_ROOT },
+      { id: T_CHILD_2, parentId: T_ROOT },
+      { id: T_OTHER, parentId: null },
+    ]);
+
+    const payload = buildPayload({ tenantIds: [T_ROOT], hasAddChildTenants: true });
+    await handler.main(payload, buildCaller());
+
     const persisted = updateByIdService.main.mock.calls[0][0];
-    expect(persisted.dPermissions).not.toEqual({ all: [IamPermissions.SUDO] });
-    expect(persisted).not.toHaveProperty('dPermissions');
+    expect(persisted.tenantIds).toEqual([T_ROOT]);
+    expect(new Set(persisted.dTenants)).toEqual(new Set([T_ROOT, T_CHILD_1, T_CHILD_2]));
   });
 
-  it('strips a client-supplied dTenants containing a null entry when tenantIds is not provided (production incident)', async () => {
-    await handler.main(
-      buildPayload({ dTenants: ['tenant-a', null as unknown as string, 'tenant-b'] }),
-      buildCaller(),
+  it('contracts dTenants back to the direct id when hasAddChildTenants turns false', async () => {
+    findByIdService.main.mockResolvedValueOnce(
+      buildExisting({ hasAddChildTenants: true, dTenants: [T_ROOT, T_CHILD_1, T_CHILD_2] }),
     );
 
+    const payload = buildPayload({ tenantIds: [T_ROOT], hasAddChildTenants: false });
+    await handler.main(payload, buildCaller());
+
+    expect(getTenantsService.main).not.toHaveBeenCalled();
     const persisted = updateByIdService.main.mock.calls[0][0];
-    expect(persisted.dTenants).not.toEqual(['tenant-a', null, 'tenant-b']);
-    expect(persisted).not.toHaveProperty('dTenants');
+    expect(persisted.tenantIds).toEqual([T_ROOT]);
+    expect(persisted.dTenants).toEqual([T_ROOT]);
+  });
+
+  it('persists the hasAddChildTenants flag itself, not only the tenant ids it derived', async () => {
+    findByIdService.main.mockResolvedValueOnce(buildExisting({ hasAddChildTenants: false }));
+    getTenantsService.main.mockResolvedValueOnce([
+      { id: T_ROOT, parentId: null },
+      { id: T_CHILD_1, parentId: T_ROOT },
+    ]);
+
+    const payload = buildPayload({ tenantIds: [T_ROOT], hasAddChildTenants: true });
+    await handler.main(payload, buildCaller());
+
+    expect(updateByIdService.main.mock.calls[0][0].hasAddChildTenants).toBe(true);
   });
 
   it('rejects when caller without SUDO updates roles to permissions they do not hold', async () => {
@@ -205,6 +287,302 @@ describe('IamUpdateAccountByIdHandler', () => {
     expect(updateByIdService.main).not.toHaveBeenCalled();
   });
 
+  it('rejects when caller without SUDO assigns a tenant outside their dTenants', async () => {
+    const payload = buildPayload({ tenantIds: [T_ROOT] });
+    const caller = buildCaller({ dPermissions: { all: ['p1'] }, dTenants: [T_OTHER] });
+
+    await expect(handler.main(payload, caller)).rejects.toMatchObject({
+      response: { statusCode: 401, translation: 'iam.error.insufficientTenantScope' },
+    });
+    expect(updateByIdService.main).not.toHaveBeenCalled();
+  });
+
+  it('rejects when caller without SUDO widens hasAddChildTenants beyond their own dTenants', async () => {
+    getTenantsService.main.mockResolvedValueOnce([
+      { id: T_ROOT, parentId: null },
+      { id: T_CHILD_1, parentId: T_ROOT },
+    ]);
+
+    const payload = buildPayload({ tenantIds: [T_ROOT], hasAddChildTenants: true });
+    const caller = buildCaller({ dPermissions: { all: ['p1'] }, dTenants: [T_ROOT] });
+
+    await expect(handler.main(payload, caller)).rejects.toMatchObject({
+      response: { statusCode: 401, translation: 'iam.error.insufficientTenantScope' },
+    });
+    expect(updateByIdService.main).not.toHaveBeenCalled();
+  });
+
+  it('allows a SUDO caller to widen hasAddChildTenants beyond their own dTenants', async () => {
+    getTenantsService.main.mockResolvedValueOnce([
+      { id: T_ROOT, parentId: null },
+      { id: T_CHILD_1, parentId: T_ROOT },
+    ]);
+
+    const payload = buildPayload({ tenantIds: [T_ROOT], hasAddChildTenants: true });
+    const caller = buildCaller({ dPermissions: { all: [IamPermissions.SUDO] }, dTenants: [] });
+
+    await expect(handler.main(payload, caller)).resolves.toBeDefined();
+    expect(updateByIdService.main).toHaveBeenCalledTimes(1);
+  });
+
+  it('allows a caller without SUDO to assign tenants fully inside their own dTenants', async () => {
+    const payload = buildPayload({ tenantIds: [T_ROOT] });
+    const caller = buildCaller({ dPermissions: { all: ['p1'] }, dTenants: [T_ROOT, T_OTHER] });
+
+    await expect(handler.main(payload, caller)).resolves.toBeDefined();
+    expect(updateByIdService.main).toHaveBeenCalledTimes(1);
+  });
+
+  it('rejects a non-SUDO caller whose own hasAddChildTenants is false setting it true on the target account', async () => {
+    const payload = buildPayload({ tenantIds: [], hasAddChildTenants: true });
+    const caller = buildCaller({
+      dPermissions: { all: ['p1'] },
+      dTenants: [],
+      hasAddChildTenants: false,
+    });
+
+    await expect(handler.main(payload, caller)).rejects.toMatchObject({
+      response: { statusCode: 401, translation: 'iam.error.insufficientHasAddChildTenantsScope' },
+    });
+    expect(updateByIdService.main).not.toHaveBeenCalled();
+  });
+
+  it('allows a non-SUDO caller whose own hasAddChildTenants is true to set it true on the target account', async () => {
+    const payload = buildPayload({ tenantIds: [], hasAddChildTenants: true });
+    const caller = buildCaller({
+      dPermissions: { all: ['p1'] },
+      dTenants: [],
+      hasAddChildTenants: true,
+    });
+
+    await expect(handler.main(payload, caller)).resolves.toBeDefined();
+    expect(updateByIdService.main).toHaveBeenCalledTimes(1);
+  });
+
+  it('allows a SUDO caller to set hasAddChildTenants true regardless of their own flag', async () => {
+    const payload = buildPayload({ tenantIds: [], hasAddChildTenants: true });
+    const caller = buildCaller({
+      dPermissions: { all: [IamPermissions.SUDO] },
+      dTenants: [],
+      hasAddChildTenants: false,
+    });
+
+    await expect(handler.main(payload, caller)).resolves.toBeDefined();
+    expect(updateByIdService.main).toHaveBeenCalledTimes(1);
+  });
+
+  it('allows any caller to turn hasAddChildTenants off, regardless of their own flag', async () => {
+    findByIdService.main.mockResolvedValueOnce(
+      buildExisting({ hasAddChildTenants: true, dTenants: [T_ROOT] }),
+    );
+    const payload = buildPayload({ tenantIds: [T_ROOT], hasAddChildTenants: false });
+    const caller = buildCaller({
+      dPermissions: { all: ['p1'] },
+      dTenants: [T_ROOT],
+      hasAddChildTenants: false,
+    });
+
+    await expect(handler.main(payload, caller)).resolves.toBeDefined();
+    expect(updateByIdService.main).toHaveBeenCalledTimes(1);
+  });
+
+  it('does not run the tenant guard when the update touches neither tenantIds nor hasAddChildTenants', async () => {
+    const caller = buildCaller({ dPermissions: { all: ['p1'] }, dTenants: [] });
+
+    await expect(
+      handler.main(buildPayload({ email: 'new@example.com' }), caller),
+    ).resolves.toBeDefined();
+    expect(getTenantsService.main).not.toHaveBeenCalled();
+  });
+
+  it('resolves the tenant guard against the existing direct tenants when only hasAddChildTenants changes', async () => {
+    findByIdService.main.mockResolvedValueOnce(
+      buildExisting({ tenants: [{ id: T_ROOT }] as unknown as IamAccount['tenants'] }),
+    );
+    getTenantsService.main.mockResolvedValueOnce([
+      { id: T_ROOT, parentId: null },
+      { id: T_CHILD_1, parentId: T_ROOT },
+    ]);
+
+    const payload = buildPayload({ hasAddChildTenants: true });
+    // caller holds T_ROOT directly, but not its descendant T_CHILD_1
+    const caller = buildCaller({ dPermissions: { all: ['p1'] }, dTenants: [T_ROOT] });
+
+    await expect(handler.main(payload, caller)).rejects.toMatchObject({
+      response: { statusCode: 401, translation: 'iam.error.insufficientTenantScope' },
+    });
+    expect(updateByIdService.main).not.toHaveBeenCalled();
+  });
+
+  it('rejects the flag-then-scope exploit: a stored hasAddChildTenants must gate a later tenantIds-only request, not the omitted payload flag', async () => {
+    // Step 1 — widen the STORED flag with an empty tenantIds, which the guard trivially allows
+    // (Arr.contained([], anything) is vacuously true) and persists no tenants at all.
+    const afterStep1 = buildExisting({ hasAddChildTenants: true, tenants: [], dTenants: [] });
+    findByIdService.main.mockResolvedValueOnce(
+      buildExisting({ hasAddChildTenants: false, tenants: [], dTenants: [] }),
+    );
+    findByIdService.main.mockResolvedValueOnce(afterStep1); // final re-fetch inside step 1
+
+    // Caller holds hasAddChildTenants itself — otherwise the hasAddChildTenants-widening guard
+    // (a caller may only grant the flag if their OWN account already carries it, or holds SUDO)
+    // would reject step 1 before this test ever reaches the exploit it targets.
+    const caller = buildCaller({
+      dPermissions: { all: ['p1'] },
+      dTenants: [T_ROOT],
+      hasAddChildTenants: true,
+    });
+
+    await expect(
+      handler.main(buildPayload({ tenantIds: [], hasAddChildTenants: true }), caller),
+    ).resolves.toBeDefined();
+    expect(updateByIdService.main).toHaveBeenCalledTimes(1);
+
+    // Step 2 — the account now carries a STORED hasAddChildTenants: true (from step 1), and the
+    // caller assigns a direct tenant WITHOUT resending the flag. The guard must expand against
+    // the STORED flag (true), exactly what iam-account-loader.adapter.ts will expand from at the
+    // account's next token issuance — not against `Boolean(undefined)`.
+    findByIdService.main.mockResolvedValueOnce(afterStep1);
+    getTenantsService.main.mockResolvedValueOnce([
+      { id: T_ROOT, parentId: null },
+      { id: T_CHILD_1, parentId: T_ROOT },
+      { id: T_CHILD_2, parentId: T_ROOT },
+    ]);
+
+    await expect(handler.main(buildPayload({ tenantIds: [T_ROOT] }), caller)).rejects.toMatchObject(
+      {
+        response: { statusCode: 401, translation: 'iam.error.insufficientTenantScope' },
+      },
+    );
+    // Still only the ONE persisted call from step 1 — step 2 must never reach persistence.
+    expect(updateByIdService.main).toHaveBeenCalledTimes(1);
+  });
+
+  it('rejects an empty tenantIds when the caller does not hold the account current direct tenants — nothing removed', async () => {
+    findByIdService.main.mockResolvedValueOnce(
+      buildExisting({ tenants: [{ id: T_ROOT }] as unknown as IamAccount['tenants'] }),
+    );
+
+    // Caller holds NO tenants at all — Arr.contained([], callerTenants) alone would let this
+    // through, stripping the target account's whole membership.
+    const caller = buildCaller({ dPermissions: { all: ['p1'] }, dTenants: [] });
+
+    await expect(handler.main(buildPayload({ tenantIds: [] }), caller)).rejects.toMatchObject({
+      response: { statusCode: 401, translation: 'iam.error.insufficientTenantScope' },
+    });
+    expect(updateByIdService.main).not.toHaveBeenCalled();
+  });
+
+  it('allows an empty tenantIds when the caller holds the account current direct tenants', async () => {
+    findByIdService.main.mockResolvedValueOnce(
+      buildExisting({ tenants: [{ id: T_ROOT }] as unknown as IamAccount['tenants'] }),
+    );
+
+    const caller = buildCaller({ dPermissions: { all: ['p1'] }, dTenants: [T_ROOT] });
+
+    await expect(handler.main(buildPayload({ tenantIds: [] }), caller)).resolves.toBeDefined();
+    expect(updateByIdService.main).toHaveBeenCalledTimes(1);
+  });
+
+  it('expands dTenants against the stored hasAddChildTenants when tenantIds is resent inside the caller scope and no flag is sent', async () => {
+    findByIdService.main.mockResolvedValueOnce(
+      buildExisting({
+        hasAddChildTenants: true,
+        tenants: [{ id: T_ROOT }] as unknown as IamAccount['tenants'],
+        dTenants: [T_ROOT],
+      }),
+    );
+    getTenantsService.main.mockResolvedValueOnce([
+      { id: T_ROOT, parentId: null },
+      { id: T_CHILD_1, parentId: T_ROOT },
+      { id: T_CHILD_2, parentId: T_ROOT },
+    ]);
+
+    const caller = buildCaller({
+      dPermissions: { all: ['p1'] },
+      dTenants: [T_ROOT, T_CHILD_1, T_CHILD_2],
+    });
+
+    const payload = buildPayload({ tenantIds: [T_ROOT] });
+    await expect(handler.main(payload, caller)).resolves.toBeDefined();
+
+    const persisted = updateByIdService.main.mock.calls[0][0];
+    expect(new Set(persisted.dTenants)).toEqual(new Set([T_ROOT, T_CHILD_1, T_CHILD_2]));
+  });
+
+  it('recomputes and persists dTenants down to the direct ids in the SAME request when hasAddChildTenants alone turns false', async () => {
+    findByIdService.main.mockResolvedValueOnce(
+      buildExisting({
+        hasAddChildTenants: true,
+        tenants: [{ id: T_ROOT }, { id: T_OTHER }] as unknown as IamAccount['tenants'],
+        dTenants: [T_ROOT, T_CHILD_1, T_CHILD_2, T_OTHER],
+      }),
+    );
+
+    const caller = buildCaller({ dPermissions: { all: ['p1'] }, dTenants: [T_ROOT, T_OTHER] });
+
+    const payload = buildPayload({ hasAddChildTenants: false });
+    await expect(handler.main(payload, caller)).resolves.toBeDefined();
+
+    expect(getTenantsService.main).not.toHaveBeenCalled();
+    const persisted = updateByIdService.main.mock.calls[0][0];
+    expect(persisted).not.toHaveProperty('tenantIds'); // membership (pivot) untouched
+    expect(new Set(persisted.dTenants)).toEqual(new Set([T_ROOT, T_OTHER]));
+  });
+
+  it('expands and persists dTenants in the SAME request when hasAddChildTenants alone turns true', async () => {
+    findByIdService.main.mockResolvedValueOnce(
+      buildExisting({
+        hasAddChildTenants: false,
+        tenants: [{ id: T_ROOT }] as unknown as IamAccount['tenants'],
+        dTenants: [T_ROOT],
+      }),
+    );
+    getTenantsService.main.mockResolvedValueOnce([
+      { id: T_ROOT, parentId: null },
+      { id: T_CHILD_1, parentId: T_ROOT },
+      { id: T_CHILD_2, parentId: T_ROOT },
+    ]);
+
+    // Caller holds hasAddChildTenants itself — otherwise the hasAddChildTenants-widening guard
+    // would reject regardless of dTenants already covering the whole subtree.
+    const caller = buildCaller({
+      dPermissions: { all: ['p1'] },
+      dTenants: [T_ROOT, T_CHILD_1, T_CHILD_2],
+      hasAddChildTenants: true,
+    });
+
+    const payload = buildPayload({ hasAddChildTenants: true });
+    await expect(handler.main(payload, caller)).resolves.toBeDefined();
+
+    const persisted = updateByIdService.main.mock.calls[0][0];
+    expect(persisted).not.toHaveProperty('tenantIds'); // membership (pivot) untouched
+    expect(new Set(persisted.dTenants)).toEqual(new Set([T_ROOT, T_CHILD_1, T_CHILD_2]));
+  });
+
+  it('allows a SUDO caller to expand dTenants against the stored hasAddChildTenants without resending the flag', async () => {
+    findByIdService.main.mockResolvedValueOnce(
+      buildExisting({
+        hasAddChildTenants: true,
+        tenants: [] as unknown as IamAccount['tenants'],
+        dTenants: [],
+      }),
+    );
+    getTenantsService.main.mockResolvedValueOnce([
+      { id: T_ROOT, parentId: null },
+      { id: T_CHILD_1, parentId: T_ROOT },
+      { id: T_CHILD_2, parentId: T_ROOT },
+    ]);
+
+    const caller = buildCaller({ dPermissions: { all: [IamPermissions.SUDO] }, dTenants: [] });
+
+    const payload = buildPayload({ tenantIds: [T_ROOT] });
+    await expect(handler.main(payload, caller)).resolves.toBeDefined();
+
+    const persisted = updateByIdService.main.mock.calls[0][0];
+    expect(persisted.tenantIds).toEqual([T_ROOT]);
+    expect(new Set(persisted.dTenants)).toEqual(new Set([T_ROOT, T_CHILD_1, T_CHILD_2]));
+  });
+
   it('updates user with new password when payload.user.password is non-empty', async () => {
     await handler.main(
       buildPayload({