@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.ts

@@ -5,19 +5,24 @@
 import {
   IamAccount,
   IamAccountTypeEnum,
+  IamTenant,
   IamUpdateAccountByIdInput,
   IamUpdateUserByIdInput,
-} from '@api/graphql';
+} from '@api/graphql.js';
+import { IamFindAccountByIdService } from '@app/iam/account/application/find/iam-find-account-by-id.service.js';
+import { IamGetAccountsService } from '@app/iam/account/application/get/iam-get-accounts.service.js';
+import { IamUpdateAccountByIdPayload } from '@app/iam/account/application/iam-account.payload-types.js';
+import { IamUpdateAccountByIdService } from '@app/iam/account/application/update/iam-update-account-by-id.service.js';
+import { IamAccountFieldSchema } from '@app/iam/account/domain/index.js';
+import { IamGetRolesService } from '@app/iam/role/index.js';
 import {
-  IamFindAccountByIdService,
-  IamGetAccountsService,
-  IamUpdateAccountByIdService,
-} from '@app/iam/account';
-import { IamAccountFieldSchema } from '@app/iam/account/domain';
-import { IamGetRolesService } from '@app/iam/role';
-import { AccountPermissions, iamCreatePermissionsFromRoles, IamPermissions } from '@app/iam/shared';
-import { IamGetTenantsService } from '@app/iam/tenant';
-import { IamUpdateUserByIdService } from '@app/iam/user';
+  AccountPermissions,
+  iamCreatePermissionsFromRoles,
+  IamPermissions,
+  iamResolveAccountTenants,
+} from '@app/iam/shared/index.js';
+import { IamGetTenantsService } from '@app/iam/tenant/index.js';
+import { IamUpdateUserByIdService } from '@app/iam/user/index.js';
 import {
   ApplySchema,
   Arr,
@@ -27,7 +32,7 @@ import {
   QueryStatement,
   type WhereClause,
 } from '@aurorajs.dev/core-back';
-import { IAM_CLIENT_READER, IIamClientReader } from '@bridges/iam/client';
+import { IAM_CLIENT_READER, IIamClientReader } from '@bridges/iam/client/index.js';
 import { ConflictException, Inject, Injectable, NotFoundException } from '@nestjs/common';
 import { EventEmitter2 } from '@nestjs/event-emitter';
 
@@ -45,18 +50,24 @@ export class IamUpdateAccountByIdHandler {
     private readonly userUpdateByIdService: IamUpdateUserByIdService,
   ) {}
 
+  /**
+   * @rule BR-IAM-ACCOUNT-003 — dApplicationCodes/dPermissions/dTenants are readonly for clients.
+   */
   @EmitEvent('iam.account.updated')
-  @ApplySchema(IamAccountFieldSchema)
+  @ApplySchema({ schema: IamAccountFieldSchema, operation: 'update' })
   async main(
     payload: IamUpdateAccountByIdInput,
     currentAccount: IamAccount,
     constraint?: QueryStatement,
     handlerMeta?: HandlerMeta,
   ): Promise<IamAccount> {
-    // #region fetch existing account with user relation
+    // #region fetch existing account with user + tenants relations
+    // `tenants` (the pivot's direct membership, not the denormalized `dTenants` snapshot) is
+    // needed by the tenant-scope guard below when the caller flips `hasAddChildTenants` without
+    // resending `tenantIds` — the guard then has no other way to know the account's direct set.
     const existing = await this.findByIdService.main(
       payload.id,
-      { relations: { user: true } } satisfies QueryStatement,
+      { relations: { user: true, tenants: true } } satisfies QueryStatement,
       handlerMeta,
     );
 
@@ -139,9 +150,54 @@ export class IamUpdateAccountByIdHandler {
     }
     // #endregion
 
-    // #region permission escalation check (only when roles change)
+    // #region expand child tenants
+    // `directTenantIds` are the DIRECT tenants — what gets written to the tenantAccount pivot.
+    // `resolvedTenantIds` is the (possibly wider) set persisted to `dTenants`. Writing the
+    // expanded set into the pivot itself would make every descendant look like a direct
+    // membership: turning hasAddChildTenants off would never shrink it back, and a tenant moved
+    // to another branch later would never be removed. See
+    // iam-account-loader.adapter.ts, which reads `account.tenants` (the pivot) as the direct set
+    // and `account.hasAddChildTenants` (the STORED flag, not any request's payload) to expand
+    // from there — the same two inputs this handler must resolve against, and the reason both
+    // fall back to the account's CURRENT stored value whenever a request omits one of them.
+    // Resolving `dTenants` against a narrower payload-only flag (e.g. treating an omitted flag
+    // as false while the stored flag is true) would let the GUARD below approve a scope the
+    // loader re-expands wider at the account's next token issuance — a self-escalation path.
+    const touchesTenantScope =
+      Array.isArray(payload.tenantIds) || payload.hasAddChildTenants !== undefined;
+
+    let directTenantIds: string[] | undefined;
+    let resolvedTenantIds: string[] | undefined;
+    // Hoisted out of the `if` below (not re-declared inside it) so the escalation guard can also
+    // see the account's CURRENT direct membership — the set an empty `tenantIds: []` would remove.
+    const existingDirectTenantIds = (existing.tenants ?? [])
+      .filter((tenant): tenant is IamTenant => tenant !== null && tenant !== undefined)
+      .map((tenant) => tenant.id);
+    if (touchesTenantScope) {
+      if (Array.isArray(payload.tenantIds)) {
+        directTenantIds = payload.tenantIds.filter((id): id is string => Boolean(id));
+      }
+
+      const effectiveDirectTenantIds = directTenantIds ?? existingDirectTenantIds;
+      const effectiveHasAddChildTenants =
+        payload.hasAddChildTenants ?? Boolean(existing.hasAddChildTenants);
+
+      const tenants =
+        effectiveHasAddChildTenants && effectiveDirectTenantIds.length > 0
+          ? await this.getTenantsService.main()
+          : [];
+      resolvedTenantIds = iamResolveAccountTenants(
+        effectiveDirectTenantIds,
+        tenants,
+        effectiveHasAddChildTenants,
+      );
+    }
+    // #endregion
+
+    // #region escalation checks (role + tenant scope)
+    const callerPermissions = (currentAccount?.dPermissions as { all?: string[] })?.all ?? [];
+
     if (computedPermissions) {
-      const callerPermissions = (currentAccount?.dPermissions as { all?: string[] })?.all ?? [];
       if (
         !callerPermissions.includes(IamPermissions.SUDO) &&
         !Arr.contained(computedPermissions.all, callerPermissions)
@@ -153,51 +209,73 @@ export class IamUpdateAccountByIdHandler {
         });
       }
     }
-    // #endregion
 
-    // #region expand child tenants
-    let resolvedTenantIds: string[] | undefined;
-    if (Array.isArray(payload.tenantIds)) {
-      const incomingTenantIds = payload.tenantIds.filter((id): id is string => Boolean(id));
-      resolvedTenantIds = incomingTenantIds;
-      if (payload.hasAddChildTenants && incomingTenantIds.length > 0) {
-        const tenants = await this.getTenantsService.main();
-        const tenantTreeNodes = tenants
-          .filter((tenant): tenant is typeof tenant & { id: string } => Boolean(tenant?.id))
-          .map((tenant) => ({ ...tenant, parentId: tenant.parentId ?? '' }));
-        const expanded = new Set<string>();
-        for (const tenantId of incomingTenantIds) {
-          expanded.add(tenantId);
-          for (const descendant of Obj.getNestedObjectsFromParentId(tenantTreeNodes, tenantId)) {
-            expanded.add(descendant.id);
-          }
-        }
-        resolvedTenantIds = [...expanded];
+    // Fires only when the update actually touches tenant scope (tenantIds or
+    // hasAddChildTenants present), mirroring the role guard firing only on a role change.
+    // `resolvedTenantIds` (computed above, against the EFFECTIVE flag + direct ids) already IS
+    // the requested scope — checking it here means the guard sees exactly what gets persisted to
+    // `dTenants` and exactly what the loader will grant at the account's next token issuance.
+    //
+    // When `tenantIds` is explicitly present, the check must ALSO cover the account's CURRENT
+    // direct tenants — the set an empty (or narrower) `tenantIds` would REMOVE. Without this,
+    // `tenantIds: []` resolves to an empty requested scope, `Arr.contained([], callerTenants)` is
+    // vacuously true for ANY caller (including one with no tenants at all), and the repository's
+    // update hook then deletes every membership row of the target account. The requested scope
+    // alone is not enough here — unlike the create handler, an update can also REMOVE tenants the
+    // caller never needed to hold to grant them in the first place.
+    if (touchesTenantScope) {
+      const callerTenants = (currentAccount?.dTenants as string[]) ?? [];
+      const requiredScope = Array.isArray(payload.tenantIds)
+        ? [...new Set([...(resolvedTenantIds ?? []), ...existingDirectTenantIds])]
+        : (resolvedTenantIds ?? []);
+
+      if (
+        !callerPermissions.includes(IamPermissions.SUDO) &&
+        !Arr.contained(requiredScope, callerTenants)
+      ) {
+        throw new ConflictException({
+          statusCode: 401,
+          message: 'Insufficient permissions to update account with these tenants',
+          translation: 'iam.error.insufficientTenantScope',
+        });
       }
     }
+
+    // A caller may grant hasAddChildTenants=true only if their OWN account already carries it (or
+    // holds SUDO) — see the identical guard on IamCreateAccountHandler for the full reasoning.
+    // Only an explicit `true` in the payload widens; turning it off (or leaving it untouched) is
+    // never a widening and stays unrestricted.
+    if (
+      payload.hasAddChildTenants === true &&
+      !callerPermissions.includes(IamPermissions.SUDO) &&
+      !currentAccount?.hasAddChildTenants
+    ) {
+      throw new ConflictException({
+        statusCode: 401,
+        message: 'Insufficient permissions to grant hasAddChildTenants on this account',
+        translation: 'iam.error.insufficientHasAddChildTenantsScope',
+      });
+    }
     // #endregion
 
     // #region update account (with diff to skip unchanged fields)
-    // dApplicationCodes / dPermissions / dTenants are derived OUTPUT columns: they must never come
-    // from the raw client payload (a client that sends one of them directly, without triggering its
-    // recompute, would have it persisted verbatim — a privilege-escalation path via dPermissions,
-    // and the cause of a production data-corruption incident on dTenants). They may only reach
-    // enrichedPayload through the computed*/resolved* variables below.
-    const {
-      dApplicationCodes: _dApplicationCodes,
-      dPermissions: _dPermissions,
-      dTenants: _dTenants,
-      ...safePayload
-    } = payload;
-    const enrichedPayload: IamUpdateAccountByIdInput = { ...safePayload };
+    // dApplicationCodes / dPermissions / dTenants are derived OUTPUT columns, readonly in the
+    // field schema: a client-supplied value is rejected by @ApplySchema before main() runs, so
+    // `payload` can never carry them. They reach enrichedPayload only through the computed*/
+    // resolved* variables below, assigned on IamUpdateAccountByIdPayload — the internal type
+    // that keeps them assignable for this write. See
+    // openspec/changes/archive/*-reject-client-supplied-derived-account-columns/design.md D2.
+    const enrichedPayload: IamUpdateAccountByIdPayload = { ...payload };
     if (computedApplicationCodes !== undefined) {
       enrichedPayload.dApplicationCodes = computedApplicationCodes;
     }
     if (computedPermissions !== undefined) {
       enrichedPayload.dPermissions = computedPermissions;
     }
+    if (directTenantIds !== undefined) {
+      enrichedPayload.tenantIds = directTenantIds;
+    }
     if (resolvedTenantIds !== undefined) {
-      enrichedPayload.tenantIds = resolvedTenantIds;
       enrichedPayload.dTenants = resolvedTenantIds;
     }
 

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

@@ -2,17 +2,17 @@
  * @aurora-catalyst-generated
  * @source cliter/iam/account.aurora.yaml
  */
-import { IamUpdateAccountByIdInput } from '@api/graphql';
-import { IamDrizzleAccountRepository } from '@app/iam/account';
+import { IamDrizzleAccountRepository } from '@app/iam/account/infrastructure/drizzle/iam-drizzle-account.repository.js';
 import { HandlerMeta, QueryStatement } from '@aurorajs.dev/core-back';
 import { Injectable } from '@nestjs/common';
+import { IamUpdateAccountByIdPayload } from '../iam-account.payload-types.js';
 
 @Injectable()
 export class IamUpdateAccountByIdService {
   constructor(private readonly repository: IamDrizzleAccountRepository) {}
 
   async main(
-    payload: IamUpdateAccountByIdInput,
+    payload: IamUpdateAccountByIdPayload,
     constraint?: QueryStatement,
     handlerMeta?: HandlerMeta,
   ): Promise<void> {

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

@@ -1,18 +1,32 @@
-import { IamAccount, IamAccountTypeEnum, IamUpdateAccountsInput } from '@api/graphql';
+import type { Mock } from 'vitest';
+import { IamAccount, IamAccountTypeEnum, IamUpdateAccountsInput } from '@api/graphql.js';
 import {
   IamCountAccountService,
   IamGetAccountsService,
   IamUpdateAccountsService,
-} from '@app/iam/account';
+} from '@app/iam/account/index.js';
 import { QueryStatement } from '@aurorajs.dev/core-back';
 import { EventEmitter2 } from '@nestjs/event-emitter';
 import { Test, TestingModule } from '@nestjs/testing';
-import { IamUpdateAccountsHandler } from './iam-update-accounts.handler';
+import { IamUpdateAccountsHandler } from './iam-update-accounts.handler.js';
 
 const buildPayload = (overrides: Partial<IamUpdateAccountsInput> = {}): IamUpdateAccountsInput => ({
   ...overrides,
 });
 
+/**
+ * Asserting only the exception class would also pass for any other 400 (a type or null-element
+ * failure); the message binds the assertion to the readonly gate
+ * (`buildReadonlyFieldRejectedMessage` in `type-handler.types.ts`).
+ */
+const readonlyRejection = (field: string) => ({
+  response: {
+    message: expect.arrayContaining([
+      expect.stringMatching(new RegExp(`^${field}: property is readonly`)),
+    ]),
+  },
+});
+
 const buildAccount = (overrides: Partial<IamAccount> = {}): IamAccount =>
   ({
     id: 'a1111111-a111-4111-8111-111111111111',
@@ -22,16 +36,16 @@ const buildAccount = (overrides: Partial<IamAccount> = {}): IamAccount =>
 
 describe('IamUpdateAccountsHandler', () => {
   let handler: IamUpdateAccountsHandler;
-  let updateService: { main: jest.Mock };
-  let getService: { main: jest.Mock };
-  let countService: { main: jest.Mock };
-  let eventEmitter: { emit: jest.Mock };
+  let updateService: { main: Mock };
+  let getService: { main: Mock };
+  let countService: { main: Mock };
+  let eventEmitter: { emit: Mock };
 
   beforeEach(async () => {
-    updateService = { main: jest.fn().mockResolvedValue(undefined) };
-    getService = { main: jest.fn().mockResolvedValue([]) };
-    countService = { main: jest.fn().mockResolvedValue(0) };
-    eventEmitter = { emit: jest.fn() };
+    updateService = { main: vi.fn().mockResolvedValue(undefined) };
+    getService = { main: vi.fn().mockResolvedValue([]) };
+    countService = { main: vi.fn().mockResolvedValue(0) };
+    eventEmitter = { emit: vi.fn() };
 
     const module: TestingModule = await Test.createTestingModule({
       providers: [
@@ -213,4 +227,73 @@ describe('IamUpdateAccountsHandler', () => {
     );
     expect(updateService.main).toHaveBeenCalledTimes(1);
   });
+
+  // The bulk-update path had NO defence at all before this change: dApplicationCodes,
+  // dPermissions and dTenants are derived OUTPUT columns nothing here recomputes, so a
+  // client-supplied value used to reach the persistence delta verbatim (the
+  // privilege-escalation path the incident comment on the by-id handler warns about).
+  // `readonly: true` on the field schema now rejects all three uniformly.
+  it('rejects a client-supplied dApplicationCodes', async () => {
+    const payload = {
+      ...buildPayload(),
+      dApplicationCodes: ['APP_HACKED'],
+    } as IamUpdateAccountsInput;
+
+    await expect(handler.main(payload, { where: { id: { in: ['x'] } } })).rejects.toMatchObject(
+      readonlyRejection('dApplicationCodes'),
+    );
+    expect(updateService.main).not.toHaveBeenCalled();
+  });
+
+  it('rejects a client-supplied dPermissions', async () => {
+    const payload = {
+      ...buildPayload(),
+      dPermissions: { all: ['SUDO'] },
+    } as IamUpdateAccountsInput;
+
+    await expect(handler.main(payload, { where: { id: { in: ['x'] } } })).rejects.toMatchObject(
+      readonlyRejection('dPermissions'),
+    );
+    expect(updateService.main).not.toHaveBeenCalled();
+  });
+
+  it('rejects a client-supplied dTenants', async () => {
+    const payload = {
+      ...buildPayload(),
+      dTenants: ['tenant-a'],
+    } as IamUpdateAccountsInput;
+
+    await expect(handler.main(payload, { where: { id: { in: ['x'] } } })).rejects.toMatchObject(
+      readonlyRejection('dTenants'),
+    );
+    expect(updateService.main).not.toHaveBeenCalled();
+  });
+
+  it('rejects a client-supplied dTenants containing a null entry (production incident)', async () => {
+    const payload = {
+      ...buildPayload(),
+      dTenants: ['tenant-a', null as unknown as string, 'tenant-b'],
+    } as IamUpdateAccountsInput;
+
+    await expect(handler.main(payload, { where: { id: { in: ['x'] } } })).rejects.toMatchObject(
+      readonlyRejection('dTenants'),
+    );
+    expect(updateService.main).not.toHaveBeenCalled();
+  });
+
+  // A bulk update has no per-account "existing" row to recompute dTenants against (unlike
+  // create/update-by-id, which read one account and expand its tenant tree). Letting
+  // hasAddChildTenants through here would flip the flag on every matched account with no
+  // recompute at all — reject it outright instead.
+  it('rejects a bulk update that carries hasAddChildTenants', async () => {
+    const payload = {
+      ...buildPayload(),
+      hasAddChildTenants: true,
+    } as IamUpdateAccountsInput;
+
+    await expect(handler.main(payload, { where: { id: { in: ['x'] } } })).rejects.toMatchObject({
+      response: { translation: 'iam.error.hasAddChildTenantsBulkNotAllowed' },
+    });
+    expect(updateService.main).not.toHaveBeenCalled();
+  });
 });

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

@@ -2,13 +2,11 @@
  * @aurora-catalyst-generated
  * @source cliter/iam/account.aurora.yaml
  */
-import { IamAccount, IamUpdateAccountsInput } from '@api/graphql';
-import {
-  IamCountAccountService,
-  IamGetAccountsService,
-  IamUpdateAccountsService,
-} from '@app/iam/account';
-import { IamAccountFieldSchema } from '@app/iam/account/domain';
+import { IamAccount, IamUpdateAccountsInput } from '@api/graphql.js';
+import { IamCountAccountService } from '@app/iam/account/application/count/iam-count-account.service.js';
+import { IamGetAccountsService } from '@app/iam/account/application/get/iam-get-accounts.service.js';
+import { IamUpdateAccountsService } from '@app/iam/account/application/update/iam-update-accounts.service.js';
+import { IamAccountFieldSchema } from '@app/iam/account/domain/index.js';
 import { ApplySchema, EmitEvent, HandlerMeta, QueryStatement } from '@aurorajs.dev/core-back';
 import { ConflictException, Injectable } from '@nestjs/common';
 import { EventEmitter2 } from '@nestjs/event-emitter';
@@ -36,14 +34,33 @@ export class IamUpdateAccountsHandler {
     private readonly countService: IamCountAccountService,
   ) {}
 
+  /**
+   * @rule BR-IAM-ACCOUNT-003 — dApplicationCodes/dPermissions/dTenants are readonly for clients.
+   */
   @EmitEvent('iam.account.updated')
-  @ApplySchema(IamAccountFieldSchema)
+  @ApplySchema({ schema: IamAccountFieldSchema, operation: 'update' })
   async main(
     payload: IamUpdateAccountsInput,
     queryStatement?: QueryStatement,
     constraint?: QueryStatement,
     handlerMeta?: HandlerMeta,
   ): Promise<IamAccount[]> {
+    // #region reject hasAddChildTenants on bulk updates
+    // Unlike create/update-by-id, a bulk update has no single "existing" account to recompute
+    // dTenants against — one payload is applied to every matched row. Letting this flag through
+    // would flip it on every matched account with no per-account recompute at all. The GraphQL
+    // IamUpdateAccountsInput does not declare the field (the REST IamUpdateAccountsDto does), but
+    // it is a real, non-readOnly FieldSchema entry (`hasAddChildTenants`), so a client can still
+    // send it — `@ApplySchema` accepts it before main() runs, and only this check refuses it.
+    if ('hasAddChildTenants' in payload) {
+      throw new ConflictException({
+        message:
+          'hasAddChildTenants cannot be changed through a bulk update — update the account individually',
+        translation: 'iam.error.hasAddChildTenantsBulkNotAllowed',
+      });
+    }
+    // #endregion
+
     // #region type immutability (product decision: no conversion path — delete + recreate instead)
     // A bulk update has no single "existing" record to diff against: one SQL statement
     // is applied to every account the filter matches, so a mismatch on ANY matched row

package/dist/templates/backend/packages/iam/src/@app/iam/account/application/update/iam-update-accounts.service.ts

@@ -2,17 +2,17 @@
  * @aurora-catalyst-generated
  * @source cliter/iam/account.aurora.yaml
  */
-import { IamUpdateAccountsInput } from '@api/graphql';
-import { IamDrizzleAccountRepository } from '@app/iam/account';
+import { IamDrizzleAccountRepository } from '@app/iam/account/infrastructure/drizzle/iam-drizzle-account.repository.js';
 import { HandlerMeta, QueryStatement } from '@aurorajs.dev/core-back';
 import { Injectable } from '@nestjs/common';
+import { IamUpdateAccountsPayload } from '../iam-account.payload-types.js';
 
 @Injectable()
 export class IamUpdateAccountsService {
   constructor(private readonly repository: IamDrizzleAccountRepository) {}
 
   async main(
-    payload: IamUpdateAccountsInput,
+    payload: IamUpdateAccountsPayload,
     queryStatement?: QueryStatement,
     constraint?: QueryStatement,
     handlerMeta?: HandlerMeta,

package/dist/templates/backend/packages/iam/src/@app/iam/account/application/update/subscribers/iam-account-updated-cache-invalidator.subscriber.spec.ts

@@ -0,0 +1,62 @@
+import type { Mock } from 'vitest';
+import type { IamAccount } from '@api/graphql.js';
+import { IamAccountUpdatedCacheInvalidatorSubscriber } from './iam-account-updated-cache-invalidator.subscriber.js';
+
+// The subscriber only ever reads `.id`; the event's real payload is a full IamAccount, but
+// tests only need to prove id-extraction and per-id resilience — not field-schema fidelity.
+const account = (id: string): IamAccount => ({ id }) as unknown as IamAccount;
+
+describe('IamAccountUpdatedCacheInvalidatorSubscriber', () => {
+  let invalidate: Mock;
+  let subscriber: IamAccountUpdatedCacheInvalidatorSubscriber;
+
+  beforeEach(() => {
+    invalidate = vi.fn().mockResolvedValue(undefined);
+    subscriber = new IamAccountUpdatedCacheInvalidatorSubscriber({ invalidate });
+  });
+
+  it('invalidates the cache for a single-account payload (iam-update-account-by-id shape)', async () => {
+    await subscriber.onAccountUpdated({ payload: account('acc-1'), meta: {} });
+
+    expect(invalidate).toHaveBeenCalledTimes(1);
+    expect(invalidate).toHaveBeenCalledWith('acc-1');
+  });
+
+  it('invalidates the cache once per account for an array payload (iam-update-accounts bulk shape)', async () => {
+    await subscriber.onAccountUpdated({
+      payload: [account('acc-1'), account('acc-2')],
+      meta: {},
+    });
+
+    expect(invalidate).toHaveBeenCalledTimes(2);
+    expect(invalidate).toHaveBeenCalledWith('acc-1');
+    expect(invalidate).toHaveBeenCalledWith('acc-2');
+  });
+
+  it('skips an entry with a missing id and still processes the rest of the batch', async () => {
+    await subscriber.onAccountUpdated({
+      payload: [account('acc-1'), account(''), account('acc-3')],
+      meta: {},
+    });
+
+    expect(invalidate).toHaveBeenCalledTimes(2);
+    expect(invalidate).toHaveBeenCalledWith('acc-1');
+    expect(invalidate).toHaveBeenCalledWith('acc-3');
+  });
+
+  it('does not throw when invalidate() rejects for one account, and still attempts the others', async () => {
+    invalidate.mockImplementation((id: string) =>
+      id === 'acc-broken' ? Promise.reject(new Error('cache down')) : Promise.resolve(undefined),
+    );
+
+    await expect(
+      subscriber.onAccountUpdated({
+        payload: [account('acc-broken'), account('acc-ok')],
+        meta: {},
+      }),
+    ).resolves.toBeUndefined();
+
+    expect(invalidate).toHaveBeenCalledWith('acc-broken');
+    expect(invalidate).toHaveBeenCalledWith('acc-ok');
+  });
+});

package/dist/templates/backend/packages/iam/src/@app/iam/account/application/update/subscribers/iam-account-updated-cache-invalidator.subscriber.ts

@@ -0,0 +1,59 @@
+// Sub-barrel import, not the '@aurora/modules' root barrel: the root barrel evaluates
+// AuthenticationModule, which HR-MODGRAPH-001 requires stay a leaf. `domain/ports` is
+// contracts-only (interfaces + Symbol tokens, zero side-effects).
+import type { IamAccount } from '@api/graphql.js';
+import {
+  ACCOUNT_CACHE_INVALIDATOR,
+  type IAccountCacheInvalidator,
+} from '@aurora/modules/authentication/domain/ports/index.js';
+import { Inject, Injectable, Logger } from '@nestjs/common';
+import { OnEvent } from '@nestjs/event-emitter';
+
+interface IamAccountUpdatedDomainEvent {
+  // `IamUpdateAccountByIdHandler` emits a single IamAccount (no `returnInputPayload`);
+  // `IamUpdateAccountsHandler` emits the array of updated accounts from a bulk update.
+  payload: IamAccount | IamAccount[];
+  meta: Record<string, unknown>;
+}
+
+/**
+ * Closes the gap left by `@EmitEvent('iam.account.updated')` having no listener: a role/tenant
+ * scope narrowed on an account stayed effective in the JWT account cache for up to
+ * `CACHE_TTL_MS` (5 min) because nothing evicted the stale entry. Evicting here forces the next
+ * `LocalProviderAdapter.validate()` call for that account into a cache MISS, reloading the
+ * fresh permissions immediately instead of waiting out the TTL.
+ */
+@Injectable()
+export class IamAccountUpdatedCacheInvalidatorSubscriber {
+  private readonly logger = new Logger(IamAccountUpdatedCacheInvalidatorSubscriber.name);
+
+  constructor(
+    // Cross-BC port (authentication is the supplier; this iam handler-subscriber is the
+    // consumer). Provided app-wide by the @Global() BridgesModule — no module import needed here.
+    @Inject(ACCOUNT_CACHE_INVALIDATOR)
+    private readonly accountCacheInvalidator: IAccountCacheInvalidator,
+  ) {}
+
+  @OnEvent('iam.account.updated')
+  async onAccountUpdated(event: IamAccountUpdatedDomainEvent): Promise<void> {
+    const accounts = Array.isArray(event.payload) ? event.payload : [event.payload];
+    const accountIds = accounts
+      .map((account) => account?.id)
+      .filter((id): id is string => Boolean(id));
+
+    await Promise.all(accountIds.map((accountId) => this.invalidate(accountId)));
+  }
+
+  /** Best-effort: a cache eviction failure must never fail the triggering update. */
+  private async invalidate(accountId: string): Promise<void> {
+    try {
+      await this.accountCacheInvalidator.invalidate(accountId);
+    } catch (error) {
+      this.logger.warn(
+        `Failed to invalidate cached account ${accountId} after iam.account.updated: ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+      );
+    }
+  }
+}

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

@@ -2,8 +2,8 @@
  * @aurora-catalyst-generated
  * @source cliter/iam/account.aurora.yaml
  */
-import { IamUpdateAccountByIdInput } from '@api/graphql';
-import { IamUpdateAccountByIdDto } from '@api/iam/account';
+import { IamUpdateAccountByIdInput } from '@api/graphql.js';
+import { IamUpdateAccountByIdDto } from '@api/iam/account/index.js';
 import { HandlerMeta, QueryStatement } from '@aurorajs.dev/core-back';
 import { Injectable } from '@nestjs/common';
 

package/dist/templates/backend/packages/iam/src/@app/iam/account/domain/iam-account.field-schema.ts

@@ -2,10 +2,10 @@
  * @aurora-catalyst-generated
  * @source cliter/iam/account.aurora.yaml
  */
-import { IamRoleFieldSchema } from '@app/iam/role';
-import { IamTenantFieldSchema } from '@app/iam/tenant';
-import { IamUserFieldSchema } from '@app/iam/user';
-import { OAuthClientFieldSchema } from '@app/o-auth/client';
+import { IamRoleFieldSchema } from '@app/iam/role/domain/index.js';
+import { IamTenantFieldSchema } from '@app/iam/tenant/domain/index.js';
+import { IamUserFieldSchema } from '@app/iam/user/domain/index.js';
+import { OAuthClientFieldSchema } from '@app/o-auth/client/domain/index.js';
 import { FieldSchema } from '@aurorajs.dev/core-back';
 
 /**
@@ -75,16 +75,24 @@ export const IamAccountFieldSchema: FieldSchema[] = [
     name: 'dApplicationCodes',
     type: 'array',
     nullable: false,
+    readOnly: true,
   },
   {
     name: 'dPermissions',
     type: 'jsonb',
     nullable: false,
+    readOnly: true,
   },
   {
     name: 'dTenants',
     type: 'array',
     nullable: false,
+    readOnly: true,
+  },
+  {
+    name: 'hasAddChildTenants',
+    type: 'boolean',
+    nullable: false,
   },
   {
     name: 'meta',

package/dist/templates/backend/packages/iam/src/@app/iam/account/domain/index.ts

@@ -1 +1 @@
-export * from './iam-account.field-schema';
+export * from './iam-account.field-schema.js';