@aurorajs.dev/catalyst-cli 1.1.3 → 2.0.0

package/dist/templates/backend/application/scripts/db/query.ts

@@ -0,0 +1,410 @@
+/**
+ * Runs a read-only SQL query against the Postgres catalog, for headless
+ * workers that have no `psql` in their environment and need to look
+ * something up directly (e.g. "what ENUM types exist in this schema?").
+ * Mirrors `migrate.ts`'s env-loading and `pg.Pool` construction so both
+ * scripts stay consistent without a shared helper module (none exists in
+ * `backend/scripts/db/` today, and this alone doesn't earn one).
+ *
+ * Read-only is enforced by three layers — the first is the PRIMARY control,
+ * the other two are defense in depth for the case where the first is
+ * misconfigured:
+ *
+ * - Layer 1 (primary), the CONNECTING ROLE. `resolveQueryCredentials()`
+ *   reads the dedicated `DATABASE_QUERY_USER` / `DATABASE_QUERY_PASSWORD`
+ *   role and fails closed — no fallback to `DATABASE_USER` — if they are
+ *   absent. `runReadOnlyQuery()` then PROBES the live connection right
+ *   after opening it and aborts if the role turns out to be a superuser or
+ *   a member of a server-file role (`pg_read_server_files` /
+ *   `pg_write_server_files` / `pg_execute_server_program`): the property
+ *   this fix depends on is measured against the actual connection, not
+ *   trusted from configuration.
+ * - Layer 2, `validateReadOnlyQuery()`, runs BEFORE a connection opens. It
+ *   rejects anything that isn't a single SELECT/WITH statement, and it
+ *   rejects a denylist of functions that reach the filesystem or another
+ *   host (`DENIED_SQL_FUNCTIONS`). This is the second line for a role that
+ *   is more privileged than intended — it does not substitute for layer 1.
+ * - Layer 3, `BEGIN TRANSACTION READ ONLY` plus a `SET LOCAL
+ *   statement_timeout`, runs at execution time. The READ ONLY mode makes
+ *   Postgres reject any statement whose plan contains a data-modifying
+ *   node — INSERT/UPDATE/DELETE, or a `SELECT INTO`, even nested inside a
+ *   CTE — at any depth. It stops WRITES, not reads. The statement timeout
+ *   is unrelated to read-only enforcement: it bounds how long a runaway
+ *   read (an accidental cross-join, an unreachable host) can stall a
+ *   headless worker.
+ *
+ * Usage:
+ *   pnpm db:query "SELECT * FROM iam.account LIMIT 5"
+ *   pnpm db:query "SELECT * FROM iam.account LIMIT 5" --json
+ */
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Pool } from 'pg';
+
+const BACKEND_ROOT = join(import.meta.dirname, '..', '..');
+
+/**
+ * Minimal `.env` loader: `KEY = value` per line (matches this repo's `.env`
+ * style — spaces around `=` are common), `#`-comments, quoted values.
+ * Existing `process.env` values win (never overwritten) so an operator can
+ * still override via real environment variables.
+ *
+ * Copied from `migrate.ts` rather than extracted into a shared module: each
+ * script in `backend/scripts/db/` is self-contained by convention.
+ */
+function loadEnvFile(envPath: string): void {
+  if (!existsSync(envPath)) {
+    return;
+  }
+
+  const lines = readFileSync(envPath, 'utf-8').split('\n');
+  for (const rawLine of lines) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith('#')) {
+      continue;
+    }
+
+    const eqIndex = line.indexOf('=');
+    if (eqIndex === -1) {
+      continue;
+    }
+
+    const key = line.slice(0, eqIndex).trim();
+    let value = line.slice(eqIndex + 1).trim();
+
+    const isQuoted = /^['"]/.test(value);
+    if (!isQuoted) {
+      const inlineCommentIndex = value.indexOf(' #');
+      if (inlineCommentIndex !== -1) {
+        value = value.slice(0, inlineCommentIndex).trim();
+      }
+    }
+    value = value.replace(/^['"]|['"]$/g, '');
+
+    if (process.env[key] === undefined) {
+      process.env[key] = value;
+    }
+  }
+}
+
+export type ValidateReadOnlyQueryResult =
+  { ok: true; query: string } | { ok: false; reason: string };
+
+export type ResolveQueryCredentialsResult =
+  { ok: true; user: string; password: string | undefined } | { ok: false; reason: string };
+
+/**
+ * Reads the dedicated read-only role's credentials — never `DATABASE_USER`
+ * (see the header comment). Pure so it is testable without a database: the
+ * caller passes `env` in rather than this function reading `process.env`
+ * itself. `DATABASE_QUERY_USER` is mandatory; there is no fallback to
+ * `DATABASE_USER` if it is absent — the tool is new, so nothing regresses
+ * by failing closed.
+ *
+ * An absent OR empty-string `DATABASE_QUERY_PASSWORD` resolves to
+ * `undefined`, never `''` — `node-postgres` only falls through to `.pgpass`
+ * (or trust auth) when the password is `null`/`undefined`; an empty string
+ * is sent to the server as an empty password and authentication fails. An
+ * operator who writes `DATABASE_QUERY_PASSWORD =` with nothing after it in
+ * `backend/.env` almost certainly means "I authenticate some other way",
+ * not "my password is the empty string" — a Postgres role with a genuinely
+ * empty password isn't a real use case, since trust auth ignores the
+ * password anyway.
+ */
+export function resolveQueryCredentials(env: NodeJS.ProcessEnv): ResolveQueryCredentialsResult {
+  const user = env.DATABASE_QUERY_USER;
+  if (!user) {
+    return {
+      ok: false,
+      reason:
+        'DATABASE_QUERY_USER (and DATABASE_QUERY_PASSWORD) must be set — db:query refuses to ' +
+        'fall back to DATABASE_USER. Create a dedicated role that is NOT a superuser and set ' +
+        'both variables in backend/.env; see the CREATE ROLE snippet in ' +
+        'backend/.claude/skills/catalyst-schema-migrations/SKILL.md.',
+    };
+  }
+
+  const password = env.DATABASE_QUERY_PASSWORD;
+  return { ok: true, user, password: password ? password : undefined };
+}
+
+/**
+ * The exact probe run by `runReadOnlyQuery()` immediately after opening the
+ * read-only transaction: measures the connecting role's privilege instead
+ * of trusting the configuration that resolved it. `has_file_role` is `NULL`
+ * on an older server where the predefined `pg_*_server_files` /
+ * `pg_execute_server_program` roles don't exist yet — that is treated as
+ * "not a member", not as an error.
+ */
+export const PRIVILEGE_PROBE_QUERY = `SELECT current_setting('is_superuser') AS is_superuser,
+       (SELECT bool_or(pg_has_role(current_user, r.oid, 'MEMBER'))
+        FROM pg_roles r
+        WHERE r.rolname IN ('pg_read_server_files', 'pg_write_server_files', 'pg_execute_server_program')
+       ) AS has_file_role`;
+
+/**
+ * SQL-callable primitives that reach the filesystem or another host. The
+ * PRIMARY control is now the connecting role (see the header comment):
+ * `DATABASE_QUERY_USER` must not be a superuser or hold a server-file role,
+ * and `runReadOnlyQuery()` probes and aborts if it is. This denylist is the
+ * SECOND line, for the case where that role turns out to be more
+ * privileged than intended — it is incomplete by construction (it cannot
+ * enumerate every dangerous built-in; extensions add more, Postgres could
+ * add more) and does nothing about a legitimate-looking `SELECT` that reads
+ * sensitive table data the role can see.
+ *
+ * `dblink` and `dblink_exec` are both listed even though `dblink_exec` is
+ * not a substring match for `dblink` under a `\b`-bounded regex (the `_`
+ * keeps `\bdblink\b` from matching inside `dblink_exec`) — listed
+ * separately so each produces its own, correctly-named rejection reason.
+ */
+export const DENIED_SQL_FUNCTIONS = [
+  'pg_read_file',
+  'pg_read_binary_file',
+  'pg_stat_file',
+  'pg_ls_dir',
+  'pg_ls_logdir',
+  'pg_ls_waldir',
+  'pg_ls_tmpdir',
+  'pg_ls_archive_statusdir',
+  'lo_import',
+  'lo_export',
+  'lo_get',
+  'lo_put',
+  'lo_from_bytea',
+  'dblink',
+  'dblink_exec',
+] as const;
+
+/**
+ * How long a single `db:query` statement may run before Postgres cancels it, set via
+ * `SET LOCAL statement_timeout` right after `BEGIN`. Chosen generously enough for a
+ * legitimate catalog/count query (the tool's stated purpose — see the header comment)
+ * while still bounding a runaway query (an accidental cross-join with no `LIMIT`) to a
+ * few seconds rather than however long the underlying scan takes.
+ */
+const STATEMENT_TIMEOUT_MS = 5_000;
+
+/** `SET LOCAL` — scoped to the current transaction, never leaks to the next connection. */
+export const STATEMENT_TIMEOUT_QUERY = `SET LOCAL statement_timeout = ${STATEMENT_TIMEOUT_MS}`;
+
+/**
+ * How long `pg.Pool` waits for a new connection (TCP + auth) before giving up, set on the
+ * `Pool` itself (see `main()`). Without it, a worker pointed at an unreachable or
+ * firewalled host blocks on the OS TCP timeout — tens of seconds to minutes depending on
+ * the platform — stalling a headless dispatch slot with no output in the meantime.
+ */
+const CONNECTION_TIMEOUT_MS = 5_000;
+
+function findDeniedFunction(statement: string): string | undefined {
+  return DENIED_SQL_FUNCTIONS.find((name) => new RegExp(`\\b${name}\\b`, 'i').test(statement));
+}
+
+/**
+ * Pure validation, no DB connection: accepts a single SELECT/WITH statement,
+ * with at most one trailing `;`. Rejects anything else — including a
+ * statement that merely starts with SELECT/WITH as a substring
+ * (`SELECTFROM foo`) or that hides a second statement after a `;`.
+ *
+ * Does NOT reject data-modifying CTEs (`WITH x AS (DELETE FROM foo
+ * RETURNING *) SELECT * FROM x`) or `SELECT ... INTO` — those pass this
+ * layer and are stopped by the READ ONLY transaction at execution time
+ * instead (see the header comment).
+ */
+export function validateReadOnlyQuery(raw: string): ValidateReadOnlyQueryResult {
+  const trimmed = raw.trim();
+  if (!trimmed) {
+    return { ok: false, reason: 'Query is empty.' };
+  }
+
+  const withoutTrailingSemicolon = trimmed.endsWith(';') ? trimmed.slice(0, -1).trimEnd() : trimmed;
+
+  if (withoutTrailingSemicolon.includes(';')) {
+    return {
+      ok: false,
+      reason:
+        'Only a single SQL statement is allowed (found an embedded `;`). This check is ' +
+        'textual — it does not parse string literals or comments, so a `;` inside a quoted ' +
+        "string (e.g. `WHERE name = 'a;b'`) is rejected too, even though it is one statement. " +
+        'If the value you need contains a literal `;`, filter for it another way (e.g. LIKE ' +
+        'with a wildcard, or a different predicate) instead of embedding it verbatim.',
+    };
+  }
+
+  if (!/^(SELECT|WITH)\b/i.test(withoutTrailingSemicolon)) {
+    return {
+      ok: false,
+      reason: 'Only SELECT or WITH statements are allowed (this script is read-only).',
+    };
+  }
+
+  const deniedFunction = findDeniedFunction(withoutTrailingSemicolon);
+  if (deniedFunction) {
+    return {
+      ok: false,
+      reason:
+        `Query text matches the denylisted function name '${deniedFunction}' ` +
+        '(reaches the filesystem or another host). This check is textual — it does not parse ' +
+        'string literals, so the name matching inside a quoted value (e.g. ' +
+        `WHERE proname = '${deniedFunction}') triggers it too, even when the function is never ` +
+        'called. This denylist is a backstop, not a guarantee — see the DENIED_SQL_FUNCTIONS ' +
+        'comment. If you need to query for this name as data, avoid spelling it out verbatim ' +
+        '(e.g. build it from a substring, or filter on a different column).',
+    };
+  }
+
+  return { ok: true, query: withoutTrailingSemicolon };
+}
+
+/**
+ * Runs the already-validated query inside a read-only transaction:
+ * `BEGIN TRANSACTION READ ONLY` → `SET LOCAL statement_timeout` → privilege
+ * probe → query → `COMMIT`, or `ROLLBACK` and re-throw on failure.
+ * Takes the `Pool` as a parameter (rather than constructing one itself) so
+ * it can be unit-tested against a mocked `pg` client, without a real
+ * database connection.
+ *
+ * On failure, the `ROLLBACK` itself is guarded: if the original error
+ * already killed the connection (e.g. "Connection terminated
+ * unexpectedly"), issuing `ROLLBACK` against it rejects too — unguarded,
+ * THAT rejection would propagate instead of the real error the operator
+ * needs to see. The client is released with the original error passed to
+ * `release()` on the failure path, so `pg` discards a possibly poisoned
+ * connection instead of returning it to the pool for reuse.
+ */
+export async function runReadOnlyQuery(
+  pool: Pool,
+  query: string,
+): Promise<Record<string, unknown>[]> {
+  const client = await pool.connect();
+  try {
+    await client.query('BEGIN TRANSACTION READ ONLY');
+    await client.query(STATEMENT_TIMEOUT_QUERY);
+
+    const probeResult = await client.query(PRIVILEGE_PROBE_QUERY);
+    const probeRow = probeResult.rows[0] as {
+      is_superuser: string;
+      has_file_role: boolean | null;
+    };
+    if (probeRow.is_superuser === 'on') {
+      throw new Error(
+        'Privilege probe failed (is_superuser): the connecting role is a Postgres superuser. ' +
+          'db:query must connect as the dedicated read-only role (DATABASE_QUERY_USER), never ' +
+          'a superuser.',
+      );
+    }
+    if (probeRow.has_file_role === true) {
+      throw new Error(
+        'Privilege probe failed (has_file_role): the connecting role is a member of a ' +
+          'server-file role (pg_read_server_files / pg_write_server_files / ' +
+          'pg_execute_server_program). db:query must connect as the dedicated read-only role ' +
+          '(DATABASE_QUERY_USER), which must not hold those memberships.',
+      );
+    }
+
+    const result = await client.query(query);
+    await client.query('COMMIT');
+    client.release();
+    return result.rows;
+  } catch (error) {
+    try {
+      await client.query('ROLLBACK');
+    } catch {
+      // The ROLLBACK failed too — most likely the connection is already dead. Swallow
+      // it so `error` below (the real failure) is what the caller sees.
+    }
+    client.release(error instanceof Error ? error : true);
+    throw error;
+  }
+}
+
+/** Plain-text table: header row + aligned columns, no external dependency. */
+export function formatAsTable(rows: Record<string, unknown>[]): string {
+  if (rows.length === 0) {
+    return '(0 rows)';
+  }
+
+  const columns = Object.keys(rows[0]);
+  const cell = (row: Record<string, unknown>, column: string): string => {
+    const value = row[column];
+    return value === null || value === undefined ? '' : String(value);
+  };
+  // `Math.max(...rows.map(...))` blows the call stack around 125k rows — the spread
+  // turns every row into a separate argument. `reduce` visits them one at a time instead,
+  // so a large result set degrades in time, not in a crash that discards data the query
+  // already fetched successfully.
+  const columnWidths = columns.map((column) =>
+    rows.reduce((max, row) => Math.max(max, cell(row, column).length), column.length),
+  );
+  const formatRow = (values: string[]): string =>
+    values.map((value, index) => value.padEnd(columnWidths[index])).join(' | ');
+
+  const header = formatRow(columns);
+  const separator = columnWidths.map((width) => '-'.repeat(width)).join('-+-');
+  const body = rows.map((row) => formatRow(columns.map((column) => cell(row, column)))).join('\n');
+
+  return [header, separator, body].join('\n');
+}
+
+export function formatAsJson(rows: Record<string, unknown>[]): string {
+  return JSON.stringify(rows, null, 2);
+}
+
+async function main(): Promise<void> {
+  const args = process.argv.slice(2);
+  const asJson = args.includes('--json');
+  const rawQuery = args.find((arg) => arg !== '--json');
+
+  if (!rawQuery) {
+    console.error('[db:query] Usage: pnpm db:query "<SQL>" [--json]');
+    process.exitCode = 1;
+    return;
+  }
+
+  const validation = validateReadOnlyQuery(rawQuery);
+  if (validation.ok === false) {
+    console.error(`[db:query] Rejected: ${validation.reason}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  loadEnvFile(join(BACKEND_ROOT, '.env'));
+
+  const credentials = resolveQueryCredentials(process.env);
+  if (credentials.ok === false) {
+    console.error(`[db:query] ${credentials.reason}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const pool = new Pool({
+    host: process.env.DATABASE_HOST ?? 'localhost',
+    port: Number(process.env.DATABASE_PORT ?? 5432),
+    user: credentials.user,
+    password: credentials.password,
+    database: process.env.DATABASE_SCHEMA ?? '',
+    connectionTimeoutMillis: CONNECTION_TIMEOUT_MS,
+  });
+
+  try {
+    const rows = await runReadOnlyQuery(pool, validation.query);
+    console.log(asJson ? formatAsJson(rows) : formatAsTable(rows));
+  } finally {
+    await pool.end();
+  }
+}
+
+// Guarded so this module can be `import`ed from a test (to unit-test
+// `runReadOnlyQuery` against a mocked `pg.Pool`) without immediately
+// connecting to a real database as a side effect of the import.
+// Both sides go through realpath — Node resolves a symlinked project directory for the
+// ESM entry module (`import.meta.url`) but leaves `process.argv[1]` as typed, so a plain
+// compare silently misses on a symlinked path (e.g. macOS `/tmp` → `/private/tmp`).
+const entryPath = process.argv[1];
+if (entryPath !== undefined && realpathSync(entryPath) === realpathSync(fileURLToPath(import.meta.url))) {
+  main().catch((error: unknown) => {
+    console.error('[db:query] Failed:', error);
+    process.exitCode = 1;
+  });
+}

package/dist/templates/backend/application/scripts/iam/permissions-without-role.ts

@@ -3,9 +3,10 @@
  * bounded context. `iam.seed.ts` deliberately seeds every permission with `roleIds: []` —
  * assigning a permission to a role is a MANUAL step in the IAM panel (see
  * `backend/src/@app/iam/iam.seed.ts`). Nobody enforces that the step actually happens: the
- * `biller` bounded context shipped three changes with all 88 permissions unassigned, and its
- * whole sidebar section stayed invisible (nav is filtered by `biller.access`) because every
- * verification used direct URLs instead of the panel. This script makes the gap visible.
+ * measured incident was a bounded context shipping three changes with all 88 permissions
+ * unassigned, so its whole sidebar section stayed invisible (nav is filtered by the BC's
+ * `<bc>.access` permission) because every verification used direct URLs instead of the panel.
+ * This script makes the gap visible.
  *
  * This script NEVER writes to the database — it only reads `iam_permission`,
  * `iam_bounded_context`, and the `iam_permission_role` pivot. It reuses
@@ -30,15 +31,15 @@ import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { Pool } from 'pg';
 
-import { iamBoundedContextTable } from '@app/iam/bounded-context';
-import { iamPermissionTable } from '@app/iam/permission';
-import { iamPermissionRoleTable } from '@app/iam/permission-role';
+import { iamBoundedContextTable } from '@app/iam/bounded-context/index.js';
+import { iamPermissionTable } from '@app/iam/permission/index.js';
+import { iamPermissionRoleTable } from '@app/iam/permission-role/index.js';
 import {
   groupIamPermissionsWithoutRoleByBoundedContext,
   type IamPermissionWithRolesAndBoundedContext,
-} from '@app/iam/permission/application/get-permissions-without-role/iam-get-permissions-without-role.handler';
+} from '@app/iam/permission/application/get-permissions-without-role/iam-get-permissions-without-role.handler.js';
 
-const BACKEND_ROOT = join(__dirname, '..', '..');
+const BACKEND_ROOT = join(import.meta.dirname, '..', '..');
 
 /**
  * Minimal `.env` loader, copied from `scripts/db/migrate.ts` — same file, same rationale

package/dist/templates/backend/application/scripts/tz-pin.spec.ts

@@ -0,0 +1,10 @@
+// Captured at MODULE-EVALUATION time, not inside an `it()`: a `TZ` assignment made inside a
+// test body never reaches V8's date cache in time, so this constant is the only way to prove
+// the pin from `test/vitest-setup.ts` actually lands before a test file's own code runs.
+const tzAtModuleEvaluation = process.env.TZ;
+
+describe('vitest-setup TZ pin', () => {
+  it('is already Europe/Madrid when this file is evaluated', () => {
+    expect(tzAtModuleEvaluation).toBe('Europe/Madrid');
+  });
+});

package/dist/templates/backend/application/src/@aurora/core.module.ts

@@ -15,8 +15,8 @@ import {
   DrizzleConfigModuleOptions,
 } from '@aurorajs.dev/core-back';
 import { DynamicModule, Module } from '@nestjs/common';
-import { CriteriaConfigModule, GraphQLConfigModule, MailerCLientModule } from './modules';
-import { SharedModule } from './shared.module';
+import { CriteriaConfigModule, GraphQLConfigModule, MailerCLientModule } from './modules/index.js';
+import { SharedModule } from './shared.module.js';
 
 /**
  * `forRoot`-parameterized (group 12.2, HR-PORTS-001 fix — decisión del

package/dist/templates/backend/application/src/@aurora/decorators/auth.decorator.ts

@@ -1,4 +1,3 @@
-import { AuthenticationJwtGuard, AuthorizationPermissionsGuard } from '@aurora/modules';
 import { Permissions, AuthenticationDisabledAdapterGuard, AuthorizationDisabledAdapterGuard } from '@aurorajs.dev/core-back';
 import { applyDecorators, UseGuards } from '@nestjs/common';
 

package/dist/templates/backend/application/src/@aurora/decorators/index.ts

@@ -1 +1 @@
-export * from './auth.decorator';
+export * from './auth.decorator.js';

package/dist/templates/backend/application/src/@aurora/modules/authentication/authentication.module.spec.ts

@@ -8,37 +8,17 @@
  * - (scaffold scenario) Verify that AuthenticationModule bootstraps with the anonymous
  *   ACCOUNT_LOADER wiring that the packager injects — no IAM module, no override needed.
  *
- * The AuroraHubConsumerAdapter imports jwks-rsa (ESM-only); we mock it before imports run
- * to avoid the known ts-jest/ESM limitation (catalyst-backend-testing SKILL.md).
  */
 
-// Mock the ESM-importing adapter BEFORE any module imports run.
-jest.mock(
-  '@aurora/modules/authentication/infrastructure/strategies/aurora-hub/aurora-hub-consumer.adapter',
-  () => ({
-    AuroraHubConsumerAdapter: class AuroraHubConsumerAdapterMock {
-      getPassportOptions() {
-        return {
-          jwtFromRequest: () => null,
-          secretOrKey: 'mock',
-        };
-      }
-      validate(): Promise<Record<string, never>> {
-        return Promise.resolve({});
-      }
-    },
-  }),
-);
-
 import { CacheModule } from '@nestjs/cache-manager';
 import { ConfigModule } from '@nestjs/config';
 import { PassportModule } from '@nestjs/passport';
 import { Test } from '@nestjs/testing';
-import { AuthenticationModule } from './authentication.module';
-import { ACCOUNT_LOADER, HUB_SESSION_MANAGER, JWT_SIGNER } from './domain/ports';
-import { AnonymousAccountLoaderAdapter } from './infrastructure/strategies/local-provider/anonymous-account-loader.adapter';
-import { JwtSignerAdapter } from './infrastructure/strategies/local-provider/jwt-signer.adapter';
-import { LocalProviderAdapter } from './infrastructure/strategies/local-provider/local-provider.adapter';
+import { AuthenticationModule } from './authentication.module.js';
+import { ACCOUNT_LOADER, HUB_SESSION_MANAGER, JWT_SIGNER } from './domain/ports/index.js';
+import { AnonymousAccountLoaderAdapter } from './infrastructure/strategies/local-provider/anonymous-account-loader.adapter.js';
+import { JwtSignerAdapter } from './infrastructure/strategies/local-provider/jwt-signer.adapter.js';
+import { LocalProviderAdapter } from './infrastructure/strategies/local-provider/local-provider.adapter.js';
 
 // ── Source-repo tests (with explicit ACCOUNT_LOADER override) ─────────────────
 // These represent the full-install (with IAM bridge) scenario.
@@ -56,12 +36,12 @@ describe('AuthenticationModule — none mode integration', () => {
         ],
       })
         .overrideProvider(ACCOUNT_LOADER)
-        .useValue({ loadById: jest.fn() })
+        .useValue({ loadById: vi.fn() })
         // Override LocalProviderAdapter so it doesn't need CACHE_MANAGER from a non-global module
         .overrideProvider(LocalProviderAdapter)
         .useValue({
           getPassportOptions: () => ({ jwtFromRequest: () => null, secretOrKey: 'mock' }),
-          validate: jest.fn(),
+          validate: vi.fn(),
         })
     );
   }

package/dist/templates/backend/application/src/@aurora/modules/authentication/authentication.module.ts

@@ -1,16 +1,16 @@
 import { Module } from '@nestjs/common';
 import { PassportModule } from '@nestjs/passport';
-import { HUB_SESSION_MANAGER, JWT_SIGNER, ACCOUNT_LOADER } from './domain/ports';
-import { authenticationStrategyProvider } from './infrastructure/factory/authentication-strategy.factory';
-import { hubSessionManagerProvider } from './infrastructure/providers/hub-session-manager.provider';
-import { jwtSignerProvider } from './infrastructure/providers/jwt-signer.provider';
-import { AuroraHubConsumerAdapter } from './infrastructure/strategies/aurora-hub/aurora-hub-consumer.adapter';
-import { AuthenticationCacheInvalidatorAdapter } from './infrastructure/strategies/authentication-cache-invalidator.adapter';
-import { JwtPassportStrategy } from './infrastructure/strategies/jwt-passport.strategy';
-import { JwtSignerAdapter } from './infrastructure/strategies/local-provider/jwt-signer.adapter';
-import { LocalProviderAdapter } from './infrastructure/strategies/local-provider/local-provider.adapter';
-import { AuthenticationBootWarning } from './infrastructure/warnings/authentication-boot-warning';
-import { AnonymousAccountLoaderAdapter } from './infrastructure/strategies/local-provider/anonymous-account-loader.adapter';
+import { HUB_SESSION_MANAGER, JWT_SIGNER, ACCOUNT_LOADER } from './domain/ports/index.js';
+import { authenticationStrategyProvider } from './infrastructure/factory/authentication-strategy.factory.js';
+import { hubSessionManagerProvider } from './infrastructure/providers/hub-session-manager.provider.js';
+import { jwtSignerProvider } from './infrastructure/providers/jwt-signer.provider.js';
+import { AuroraHubConsumerAdapter } from './infrastructure/strategies/aurora-hub/index.js';
+import { AuthenticationCacheInvalidatorAdapter } from './infrastructure/strategies/authentication-cache-invalidator.adapter.js';
+import { JwtPassportStrategy } from './infrastructure/strategies/jwt-passport.strategy.js';
+import { JwtSignerAdapter } from './infrastructure/strategies/local-provider/jwt-signer.adapter.js';
+import { LocalProviderAdapter } from './infrastructure/strategies/local-provider/local-provider.adapter.js';
+import { AuthenticationBootWarning } from './infrastructure/warnings/authentication-boot-warning.js';
+import { AnonymousAccountLoaderAdapter } from './infrastructure/strategies/local-provider/anonymous-account-loader.adapter.js';
 
 /**
  * Leaf module: depends ONLY on `@nestjs/passport` + the cross-BC port tokens exposed by

package/dist/templates/backend/application/src/@aurora/modules/authentication/domain/anonymous-account.spec.ts

@@ -1,4 +1,4 @@
-import { createAnonymousAccount } from './anonymous-account';
+import { createAnonymousAccount } from './anonymous-account.js';
 
 describe('createAnonymousAccount', () => {
   it('returns an object with username "anonymous"', () => {

package/dist/templates/backend/application/src/@aurora/modules/authentication/domain/anonymous-account.ts

@@ -1,4 +1,4 @@
-import type { AuthenticatedAccount } from './ports/account-loader.port';
+import type { AuthenticatedAccount } from './ports/account-loader.port.js';
 
 /**
  * Factory that returns a fresh anonymous `AuthenticatedAccount` per request.
@@ -25,6 +25,7 @@ export function createAnonymousAccount(): AuthenticatedAccount {
     dApplicationCodes: [],
     dPermissions: { all: [] },
     dTenants: [],
+    hasAddChildTenants: false,
     meta: null,
     roles: [],
     tenants: [],

package/dist/templates/backend/application/src/@aurora/modules/authentication/domain/errors/index.ts

@@ -1 +1 @@
-export * from './token-issuance-disabled.error';
+export * from './token-issuance-disabled.error.js';

package/dist/templates/backend/application/src/@aurora/modules/authentication/domain/index.ts

@@ -1 +1 @@
-export * from './resolve-authentication-mode';
+export * from './resolve-authentication-mode.js';

package/dist/templates/backend/application/src/@aurora/modules/authentication/domain/ports/account-loader.port.ts

@@ -28,6 +28,12 @@ export interface AuthenticatedAccount {
   dApplicationCodes: string[];
   dPermissions: { all: string[] } & Record<string, string[]>;
   dTenants: string[];
+  /** Whether this account's tenant scope auto-expands to descendants of its direct tenants.
+   * Read by the create/update account handlers to gate widening the flag on ANOTHER account —
+   * a caller may only grant it if their own principal already carries it (or holds SUDO). Must
+   * be carried on every principal-building path (`mapToAuthenticatedAccount` here, and the
+   * Aurora Hub consumer strategy), or the guard silently rejects every non-SUDO caller. */
+  hasAddChildTenants: boolean;
   meta: Record<string, unknown> | null;
   roles: AuthenticatedAccountRole[];
   tenants: AuthenticatedAccountTenant[];
@@ -60,6 +66,26 @@ export interface IAccountLoaderOptions {
    *
    * Leave absent or `false` for the normal (non-refresh) path. */
   refreshPermissions?: boolean | 'strict';
+
+  /** When `true`, the adapter recomputes `dTenants` from the account's current tenant
+   * assignment → `hasAddChildTenants` and persists it if changed before returning the
+   * account. Independent of `refreshPermissions`, not a widening of it — the two refreshes
+   * have different costs (this one reads the whole tenant table to walk descendants, the
+   * permission refresh only queries the account's own roles) and an independent `'strict'`
+   * severity judgement (see below). One refresh failing never suppresses the other.
+   *
+   * Fail-soft: a recompute failure never blocks the load — the stored snapshot is returned.
+   * This is the mode the token-issuance grant services use (a stale tenant scope must never
+   * turn a login into a hard failure).
+   *
+   * `'strict'` requests the SAME recompute, but demands proof it actually happened: if the
+   * refresh itself fails (tenant query error, persistence error), `loadById` REJECTS instead
+   * of silently falling back to the stored snapshot. Reach for this only when the caller's
+   * OWN correctness depends on the refresh having succeeded.
+   *
+   * Leave absent or `false` for the normal (non-refresh) path — this is also the path every
+   * request-time JWT validation call takes, so it issues NO extra query. */
+  refreshTenants?: boolean | 'strict';
 }
 
 export interface IAccountLoader {

package/dist/templates/backend/application/src/@aurora/modules/authentication/domain/ports/authentication-strategy.port.ts

@@ -1,6 +1,6 @@
 import type { Request } from 'express';
 import type { StrategyOptionsWithRequest } from 'passport-jwt';
-import type { AuthenticatedAccount } from './account-loader.port';
+import type { AuthenticatedAccount } from './account-loader.port.js';
 
 export interface IAuthenticationStrategy {
   getPassportOptions(): StrategyOptionsWithRequest;