@aurorajs.dev/catalyst-cli 1.0.2 → 2.0.0

package/dist/templates/backend/application/src/@aurora/modules/authentication/infrastructure/providers/hub-session-manager.provider.ts

@@ -1,6 +1,6 @@
 import type { Provider } from '@nestjs/common';
-import { HUB_SESSION_MANAGER } from '../../domain/ports';
-import { JwtSignerAdapter } from '../strategies/local-provider/jwt-signer.adapter';
+import { HUB_SESSION_MANAGER } from '../../domain/ports/index.js';
+import { JwtSignerAdapter } from '../strategies/local-provider/jwt-signer.adapter.js';
 
 /**
  * Port-to-adapter binding for the hub session manager (intra-module DI, NOT a cross-BC bridge).

package/dist/templates/backend/application/src/@aurora/modules/authentication/infrastructure/providers/jwt-signer.provider.ts

@@ -1,6 +1,6 @@
 import type { Provider } from '@nestjs/common';
-import { JWT_SIGNER } from '../../domain/ports';
-import { JwtSignerAdapter } from '../strategies/local-provider/jwt-signer.adapter';
+import { JWT_SIGNER } from '../../domain/ports/index.js';
+import { JwtSignerAdapter } from '../strategies/local-provider/jwt-signer.adapter.js';
 
 /**
  * Port-to-adapter binding for the JWT signer (intra-module DI, NOT a cross-BC bridge).

package/dist/templates/backend/application/src/@aurora/modules/authentication/infrastructure/strategies/aurora-hub/aurora-hub-consumer.adapter.ts

@@ -6,7 +6,8 @@ import type { Cache } from 'cache-manager';
 import type { Request } from 'express';
 import { passportJwtSecret } from 'jwks-rsa';
 import { ExtractJwt, type StrategyOptionsWithRequest } from 'passport-jwt';
-import type { IAuthenticationStrategy } from '../../../domain/ports';
+import type { AuthenticatedAccount, IAuthenticationStrategy } from '../../../domain/ports/index.js';
+import { buildJwtAccountCacheKey } from '../cache-key.js';
 
 @Injectable()
 export class AuroraHubConsumerAdapter implements IAuthenticationStrategy {
@@ -35,11 +36,11 @@ export class AuroraHubConsumerAdapter implements IAuthenticationStrategy {
     };
   }
 
-  async validate(req: Request, payload: Record<string, unknown>): Promise<object> {
+  async validate(req: Request, payload: Record<string, unknown>): Promise<AuthenticatedAccount> {
     const accountId = payload.aci as string;
-    const cacheKey = `jwt-account:${accountId}`;
+    const cacheKey = buildJwtAccountCacheKey(accountId);
 
-    const cached = await this.cacheManager.get<object>(cacheKey);
+    const cached = await this.cacheManager.get<AuthenticatedAccount>(cacheKey);
     if (cached) return cached;
 
     const authorization = req.headers.authorization;
@@ -57,6 +58,7 @@ export class AuroraHubConsumerAdapter implements IAuthenticationStrategy {
             dApplicationCodes
             dPermissions
             dTenants
+            hasAddChildTenants
             meta
             roles {
               id
@@ -93,7 +95,18 @@ export class AuroraHubConsumerAdapter implements IAuthenticationStrategy {
       throw new Error(response.data.errors[0]?.message || 'Failed to fetch user data.');
     }
 
-    const account = response.data.data.iamMeAccount;
+    // F4 fix (security review, gate 12.2): the hub's `iamMeAccount` GraphQL query has no
+    // `impersonatedBy` field (hub/satellite impersonation is explicitly out of scope for this
+    // change — design.md Non-Goals: "Impersonation across the hub / authorization-code flow, or
+    // from a satellite app"), so the raw response never carries it. Normalizing it to
+    // `null` here — rather than leaving it `undefined` — matters downstream: the impersonation
+    // flow's V2 veto reads `AuthenticatedAccount.impersonatedBy`, and an `undefined` value would
+    // fail the `!== null` / truthiness check identically to a real actor claim, refusing every
+    // impersonation request under hub mode with no way to tell the two apart.
+    const account: AuthenticatedAccount = {
+      ...response.data.data.iamMeAccount,
+      impersonatedBy: null,
+    };
 
     await this.cacheManager.set(cacheKey, account, 300_000);
 

package/dist/templates/backend/application/src/@aurora/modules/authentication/infrastructure/strategies/aurora-hub/index.ts

@@ -0,0 +1 @@
+export * from './aurora-hub-consumer.adapter.js';

package/dist/templates/backend/application/src/@aurora/modules/authentication/infrastructure/strategies/authentication-cache-invalidator.adapter.spec.ts

@@ -0,0 +1,56 @@
+/**
+ * Unit tests for AuthenticationCacheInvalidatorAdapter.
+ *
+ * TDD — this spec was written BEFORE the implementation existed (red phase).
+ * The test must FAIL when the adapter does not exist and PASS after it is created.
+ *
+ * What we assert:
+ *   - invalidate(accountId) calls cacheManager.del('jwt-account:<accountId>')
+ *     with the exact key built by buildJwtAccountCacheKey — NOT a hardcoded string.
+ *   - The call is idempotent: calling del on a missing key does not throw
+ *     (cache-manager's del is a no-op when the key is absent).
+ *
+ * CACHE_MANAGER is a plain injection token from @nestjs/cache-manager; we provide
+ * it directly as a mock object literal.
+ */
+
+import { CACHE_MANAGER } from '@nestjs/cache-manager';
+import { Test } from '@nestjs/testing';
+import { AuthenticationCacheInvalidatorAdapter } from './authentication-cache-invalidator.adapter.js';
+import { buildJwtAccountCacheKey } from './cache-key.js';
+
+describe('AuthenticationCacheInvalidatorAdapter', () => {
+  let adapter: AuthenticationCacheInvalidatorAdapter;
+  const cacheManager = { del: vi.fn() };
+
+  beforeEach(async () => {
+    vi.clearAllMocks();
+
+    const moduleRef = await Test.createTestingModule({
+      providers: [
+        AuthenticationCacheInvalidatorAdapter,
+        { provide: CACHE_MANAGER, useValue: cacheManager },
+      ],
+    }).compile();
+
+    adapter = moduleRef.get(AuthenticationCacheInvalidatorAdapter);
+  });
+
+  it('calls cacheManager.del with the canonical jwt-account key for the given accountId', async () => {
+    const accountId = 'account-uuid-1234';
+
+    await adapter.invalidate(accountId);
+
+    expect(cacheManager.del).toHaveBeenCalledTimes(1);
+    expect(cacheManager.del).toHaveBeenCalledWith(buildJwtAccountCacheKey(accountId));
+    // Verify the exact key format so the test fails if buildJwtAccountCacheKey changes.
+    expect(cacheManager.del).toHaveBeenCalledWith(`jwt-account:${accountId}`);
+  });
+
+  it('is idempotent — del on a missing key does not throw', async () => {
+    // cache-manager del returns void; simulate a no-op for missing keys.
+    cacheManager.del.mockResolvedValue(undefined);
+
+    await expect(adapter.invalidate('non-existent-account')).resolves.not.toThrow();
+  });
+});

package/dist/templates/backend/application/src/@aurora/modules/authentication/infrastructure/strategies/authentication-cache-invalidator.adapter.ts

@@ -0,0 +1,28 @@
+import { CACHE_MANAGER } from '@nestjs/cache-manager';
+import { Inject, Injectable } from '@nestjs/common';
+import type { Cache } from 'cache-manager';
+import type { IAccountCacheInvalidator } from '../../domain/ports/index.js';
+import { buildJwtAccountCacheKey } from './cache-key.js';
+
+/**
+ * Adapter: AuthenticationCacheInvalidatorAdapter
+ *
+ * Implements IAccountCacheInvalidator by deleting the `jwt-account:<accountId>`
+ * entry from the shared CacheManager. Registered in AuthenticationModule (zero-leak
+ * variant) and exported as the concrete class; BridgesModule wires the port token
+ * to this instance via `useExisting`.
+ *
+ * The `CACHE_MANAGER` token is provided globally by `SharedModule`'s
+ * `CacheModule.register({ isGlobal: true })` — no extra import needed here.
+ *
+ * See: `@aurora/modules/authentication/domain/ports/account-cache-invalidator.port.ts`
+ * See: `.claude/skills/catalyst-cross-bounded-context-ports/SKILL.md` — zero-leak variant.
+ */
+@Injectable()
+export class AuthenticationCacheInvalidatorAdapter implements IAccountCacheInvalidator {
+  constructor(@Inject(CACHE_MANAGER) private readonly cacheManager: Cache) {}
+
+  async invalidate(accountId: string): Promise<void> {
+    await this.cacheManager.del(buildJwtAccountCacheKey(accountId));
+  }
+}

package/dist/templates/backend/application/src/@aurora/modules/authentication/infrastructure/strategies/cache-key.ts

@@ -0,0 +1,9 @@
+/**
+ * Shared cache-key builder for the JWT account cache.
+ *
+ * Both strategy adapters (LocalProviderAdapter, AuroraHubConsumerAdapter) write to this
+ * key on successful authentication. The AuthenticationCacheInvalidatorAdapter reads it
+ * on logout to delete the entry. A single definition here ensures all three sides stay
+ * in sync — no inline string literals, no third copy.
+ */
+export const buildJwtAccountCacheKey = (accountId: string): string => `jwt-account:${accountId}`;

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

@@ -0,0 +1,11 @@
+/**
+ * Public sub-barrel for the authentication strategies folder.
+ *
+ * Exposes ONLY the artifact that crosses the module boundary: the cache-invalidator
+ * adapter, wired to the `ACCOUNT_CACHE_INVALIDATOR` port by the @Global() BridgesModule.
+ * The passport strategy and the concrete provider adapters (local-provider, aurora-hub)
+ * are internal — registered by `authentication.module.ts` via relative imports — and must
+ * NOT be surfaced here: `authentication` is a leaf module (HR-MODGRAPH-001) and this
+ * surface stays intentionally bounded (HR-BARRELS-001).
+ */
+export * from './authentication-cache-invalidator.adapter.js';

package/dist/templates/backend/application/src/@aurora/modules/authentication/infrastructure/strategies/jwt-passport.strategy.ts

@@ -2,7 +2,7 @@ import { Inject, Injectable } from '@nestjs/common';
 import { PassportStrategy } from '@nestjs/passport';
 import type { Request } from 'express';
 import { Strategy } from 'passport-jwt';
-import { AUTHENTICATION_STRATEGY, type IAuthenticationStrategy } from '../../domain/ports';
+import { AUTHENTICATION_STRATEGY, type IAuthenticationStrategy } from '../../domain/ports/index.js';
 
 @Injectable()
 export class JwtPassportStrategy extends PassportStrategy(Strategy, 'jwt') {

package/dist/templates/backend/application/src/@aurora/modules/authentication/infrastructure/strategies/local-provider/anonymous-account-loader.adapter.spec.ts

@@ -7,8 +7,8 @@
  */
 
 import { Test } from '@nestjs/testing';
-import { createAnonymousAccount } from '../../../domain/anonymous-account';
-import { AnonymousAccountLoaderAdapter } from './anonymous-account-loader.adapter';
+import { createAnonymousAccount } from '../../../domain/anonymous-account.js';
+import { AnonymousAccountLoaderAdapter } from './anonymous-account-loader.adapter.js';
 
 describe('AnonymousAccountLoaderAdapter', () => {
   let adapter: AnonymousAccountLoaderAdapter;
@@ -42,6 +42,6 @@ describe('AnonymousAccountLoaderAdapter', () => {
     const result2 = await adapter.loadById('x');
 
     expect(result1).not.toBe(result2); // different object references
-    expect(result1).toEqual(result2);  // same shape
+    expect(result1).toEqual(result2); // same shape
   });
 });

package/dist/templates/backend/application/src/@aurora/modules/authentication/infrastructure/strategies/local-provider/anonymous-account-loader.adapter.ts

@@ -1,6 +1,6 @@
 import { Injectable } from '@nestjs/common';
-import { createAnonymousAccount } from '../../../domain/anonymous-account';
-import type { AuthenticatedAccount, IAccountLoader } from '../../../domain/ports';
+import { createAnonymousAccount } from '../../../domain/anonymous-account.js';
+import type { AuthenticatedAccount, IAccountLoader } from '../../../domain/ports/index.js';
 
 /**
  * Framework-default implementation of `IAccountLoader` for scaffolds that have no IAM

package/dist/templates/backend/application/src/@aurora/modules/authentication/infrastructure/strategies/local-provider/jwt-signer.adapter.spec.ts

@@ -5,7 +5,8 @@ import { generateKeyPairSync, randomUUID } from 'node:crypto';
 import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
-import { JwtSignerAdapter } from './jwt-signer.adapter';
+import { TokenIssuanceDisabledError } from '../../../domain/errors/index.js';
+import { JwtSignerAdapter } from './jwt-signer.adapter.js';
 
 describe('JwtSignerAdapter', () => {
   let tempDir: string;
@@ -35,11 +36,15 @@ describe('JwtSignerAdapter', () => {
 
   beforeEach(async () => {
     const config = {
-      get: jest.fn((key: string, fallback?: unknown) => {
+      get: vi.fn((key: string, fallback?: unknown) => {
         if (key === 'OAUTH_STRATEGY') return 'local-provider';
         if (key === 'OAUTH_PRIVATE_KEY_PATH') return privateKeyPath;
         if (key === 'JWT_ACCESS_TTL_SECONDS') return 3600;
         if (key === 'JWT_REFRESH_TTL_SECONDS') return 2592000;
+        // Distinct from the port's own default (900) so the "defaults to
+        // JWT_IMPERSONATION_TTL_SECONDS" test is discriminating: it would fail if the adapter
+        // read a misspelled key and silently fell through to `fallback` instead.
+        if (key === 'JWT_IMPERSONATION_TTL_SECONDS') return 120;
         return fallback;
       }),
     };
@@ -85,6 +90,147 @@ describe('JwtSignerAdapter', () => {
 
       expect(decoded.exp - decoded.iat).toBe(3600);
     });
+
+    it('emits a fifth claim act:{aci} when an actor is supplied', async () => {
+      const aci = randomUUID();
+      const actorAci = randomUUID();
+
+      const { token } = await adapter.signAccess({ aci, act: { aci: actorAci } });
+
+      const decoded = verifier.verify<Record<string, unknown>>(token, { algorithms: ['RS256'] });
+
+      expect(Object.keys(decoded).sort()).toEqual(['aci', 'act', 'exp', 'iat', 'iss']);
+      expect(decoded.aci).toBe(aci);
+      expect(decoded.act).toEqual({ aci: actorAci });
+    });
+
+    it('never emits act:undefined when no actor is supplied — exactly four claims', async () => {
+      const { token } = await adapter.signAccess({ aci: randomUUID() });
+
+      const decoded = verifier.verify<Record<string, unknown>>(token, { algorithms: ['RS256'] });
+
+      expect(Object.keys(decoded).sort()).toEqual(['aci', 'exp', 'iat', 'iss']);
+      expect('act' in decoded).toBe(false);
+    });
+
+    it('honors a ttlSeconds override without disturbing JWT_ACCESS_TTL_SECONDS', async () => {
+      const aci = randomUUID();
+
+      const overridden = await adapter.signAccess({ aci }, { ttlSeconds: 900 });
+      const normal = await adapter.signAccess({ aci });
+
+      const decodedOverridden = verifier.verify<Record<string, number>>(overridden.token, {
+        algorithms: ['RS256'],
+      });
+      const decodedNormal = verifier.verify<Record<string, number>>(normal.token, {
+        algorithms: ['RS256'],
+      });
+
+      expect(decodedOverridden.exp - decodedOverridden.iat).toBe(900);
+      expect(decodedNormal.exp - decodedNormal.iat).toBe(3600);
+    });
+
+    it('defaults an impersonation token (act present, no explicit ttlSeconds) to JWT_IMPERSONATION_TTL_SECONDS', async () => {
+      const { token } = await adapter.signAccess({ aci: randomUUID(), act: { aci: randomUUID() } });
+
+      const decoded = verifier.verify<Record<string, number>>(token, { algorithms: ['RS256'] });
+
+      // Config mock returns 120 for JWT_IMPERSONATION_TTL_SECONDS (see beforeEach) — a value
+      // distinct from the port's own default (900) and from every other TTL in this suite, so
+      // this assertion would fail if the adapter read the wrong key or fell through to a
+      // fallback instead of this config value.
+      expect(decoded.exp - decoded.iat).toBe(120);
+    });
+  });
+
+  // ─── F12 — JWT_IMPERSONATION_TTL_SECONDS validated at read (security review, gate 12.2) ──
+  //
+  // Unlike the pre-existing JWT_ACCESS_TTL_SECONDS / JWT_REFRESH_TTL_SECONDS parsing (untouched,
+  // out of this change's lane), the impersonation TTL is validated: non-numeric, non-positive, or
+  // implausibly large values fall back to the safe 900s default instead of producing a token with
+  // a nonsensical (NaN, negative, or hours-long) lifetime.
+
+  describe('JWT_IMPERSONATION_TTL_SECONDS validation', () => {
+    const buildAdapterWithImpersonationTtl = async (
+      rawValue: unknown,
+    ): Promise<JwtSignerAdapter> => {
+      const config = {
+        get: vi.fn((key: string, fallback?: unknown) => {
+          if (key === 'OAUTH_STRATEGY') return 'local-provider';
+          if (key === 'OAUTH_PRIVATE_KEY_PATH') return privateKeyPath;
+          if (key === 'JWT_ACCESS_TTL_SECONDS') return 3600;
+          if (key === 'JWT_REFRESH_TTL_SECONDS') return 2592000;
+          if (key === 'JWT_IMPERSONATION_TTL_SECONDS') return rawValue;
+          return fallback;
+        }),
+      };
+
+      const module: TestingModule = await Test.createTestingModule({
+        providers: [JwtSignerAdapter, { provide: ConfigService, useValue: config }],
+      }).compile();
+
+      return module.get(JwtSignerAdapter);
+    };
+
+    it('falls back to the 900s default when the configured value is non-numeric', async () => {
+      const badAdapter = await buildAdapterWithImpersonationTtl('not-a-number');
+
+      const { token } = await badAdapter.signAccess({
+        aci: randomUUID(),
+        act: { aci: randomUUID() },
+      });
+      const decoded = verifier.verify<Record<string, number>>(token, { algorithms: ['RS256'] });
+
+      expect(decoded.exp - decoded.iat).toBe(900);
+    });
+
+    it('falls back to the 900s default when the configured value is negative', async () => {
+      const badAdapter = await buildAdapterWithImpersonationTtl(-100);
+
+      const { token } = await badAdapter.signAccess({
+        aci: randomUUID(),
+        act: { aci: randomUUID() },
+      });
+      const decoded = verifier.verify<Record<string, number>>(token, { algorithms: ['RS256'] });
+
+      expect(decoded.exp - decoded.iat).toBe(900);
+    });
+
+    it('falls back to the 900s default when the configured value is zero', async () => {
+      const badAdapter = await buildAdapterWithImpersonationTtl(0);
+
+      const { token } = await badAdapter.signAccess({
+        aci: randomUUID(),
+        act: { aci: randomUUID() },
+      });
+      const decoded = verifier.verify<Record<string, number>>(token, { algorithms: ['RS256'] });
+
+      expect(decoded.exp - decoded.iat).toBe(900);
+    });
+
+    it('falls back to the 900s default when the configured value exceeds the sane upper clamp (3600s)', async () => {
+      const badAdapter = await buildAdapterWithImpersonationTtl(999_999);
+
+      const { token } = await badAdapter.signAccess({
+        aci: randomUUID(),
+        act: { aci: randomUUID() },
+      });
+      const decoded = verifier.verify<Record<string, number>>(token, { algorithms: ['RS256'] });
+
+      expect(decoded.exp - decoded.iat).toBe(900);
+    });
+
+    it('accepts a valid value at the upper boundary (3600s exactly)', async () => {
+      const boundaryAdapter = await buildAdapterWithImpersonationTtl(3600);
+
+      const { token } = await boundaryAdapter.signAccess({
+        aci: randomUUID(),
+        act: { aci: randomUUID() },
+      });
+      const decoded = verifier.verify<Record<string, number>>(token, { algorithms: ['RS256'] });
+
+      expect(decoded.exp - decoded.iat).toBe(3600);
+    });
   });
 
   describe('signRefresh', () => {
@@ -196,12 +342,11 @@ describe('JwtSignerAdapter', () => {
 // ── aurora-hub mode ────────────────────────────────────────────────────────────
 
 describe('JwtSignerAdapter — aurora-hub mode', () => {
-  it('constructs without reading any key file (no readFileSync error)', async () => {
-    // aurora-hub mode: the local RSA key pair is irrelevant. OAUTH_PRIVATE_KEY_PATH
-    // is not required because the hub owns the key material. Construction MUST succeed
-    // without any key file present on disk.
+  let adapter: JwtSignerAdapter;
+
+  beforeEach(async () => {
     const configService = {
-      get: jest.fn((key: string, fallback?: unknown) => {
+      get: vi.fn((key: string, fallback?: unknown) => {
         if (key === 'OAUTH_STRATEGY') return 'aurora-hub';
         // Point the key path at a guaranteed-missing file so the test stays discriminating
         // even in a dev env where ./.keys/ exists: reverting the dormant guard would make the
@@ -215,30 +360,82 @@ describe('JwtSignerAdapter — aurora-hub mode', () => {
       providers: [JwtSignerAdapter, { provide: ConfigService, useValue: configService }],
     }).compile();
 
-    const adapter = module.get(JwtSignerAdapter);
-    expect(adapter).toBeDefined();
+    adapter = module.get(JwtSignerAdapter);
   });
 
-  it('signAccess throws naming OAUTH_STRATEGY=aurora-hub in the error message', async () => {
-    const configService = {
-      get: jest.fn((key: string, fallback?: unknown) => {
-        if (key === 'OAUTH_STRATEGY') return 'aurora-hub';
-        // Point the key path at a guaranteed-missing file so the test stays discriminating
-        // even in a dev env where ./.keys/ exists: reverting the dormant guard would make the
-        // constructor readFileSync this path → ENOENT, turning the test red.
-        if (key === 'OAUTH_PRIVATE_KEY_PATH') return '/nonexistent/aurora-hub-test.key';
-        return fallback;
-      }),
-    };
+  it('constructs without reading any key file (no readFileSync error)', () => {
+    // aurora-hub mode: the local RSA key pair is irrelevant. OAUTH_PRIVATE_KEY_PATH
+    // is not required because the hub owns the key material. Construction MUST succeed
+    // without any key file present on disk.
+    expect(adapter).toBeDefined();
+  });
 
-    const module: TestingModule = await Test.createTestingModule({
-      providers: [JwtSignerAdapter, { provide: ConfigService, useValue: configService }],
-    }).compile();
+  // Class assertion, not a message regex (backend-authentication spec, "Every signing entry point
+  // refuses with the typed error"): a revert to an untyped `new Error(...)` with the byte-identical
+  // message must fail this test, which a message-only assertion cannot do.
+  it('signAccess refuses with TokenIssuanceDisabledError naming OAUTH_STRATEGY=aurora-hub', async () => {
+    await expect(adapter.signAccess({ aci: 'test-id' })).rejects.toBeInstanceOf(
+      TokenIssuanceDisabledError,
+    );
+    await expect(adapter.signAccess({ aci: 'test-id' })).rejects.toThrow(
+      /token issuance disabled.*OAUTH_STRATEGY=aurora-hub/i,
+    );
+  });
 
-    const adapter = module.get(JwtSignerAdapter);
+  it('signRefresh refuses with TokenIssuanceDisabledError naming OAUTH_STRATEGY=aurora-hub', async () => {
+    await expect(adapter.signRefresh()).rejects.toBeInstanceOf(TokenIssuanceDisabledError);
+    await expect(adapter.signRefresh()).rejects.toThrow(
+      /token issuance disabled.*OAUTH_STRATEGY=aurora-hub/i,
+    );
+  });
 
-    await expect(adapter.signAccess({ aci: 'test-id' })).rejects.toThrow(
+  it('signHubSession refuses with TokenIssuanceDisabledError naming OAUTH_STRATEGY=aurora-hub', () => {
+    expect(() => adapter.signHubSession('test-id')).toThrow(TokenIssuanceDisabledError);
+    expect(() => adapter.signHubSession('test-id')).toThrow(
       /token issuance disabled.*OAUTH_STRATEGY=aurora-hub/i,
     );
   });
+
+  // Spec scenario "A genuine signing failure is distinguishable from the refusal": stubs the real
+  // jwtService's signAsync (local-provider mode, so jwtService is not null) to fail for a reason that
+  // has nothing to do with OAUTH_STRATEGY, and asserts the rejection is NOT the disabled-issuance type.
+  it('a genuine signing failure is NOT an instance of the disabled-issuance error', async () => {
+    const keypair = generateKeyPairSync('rsa', {
+      modulusLength: 2048,
+      privateKeyEncoding: { format: 'pem', type: 'pkcs1' },
+      publicKeyEncoding: { format: 'pem', type: 'pkcs1' },
+    });
+    const localTempDir = mkdtempSync(join(tmpdir(), 'jwt-signer-spec-genuine-failure-'));
+    const localPrivateKeyPath = join(localTempDir, 'oauth-private.key');
+    writeFileSync(localPrivateKeyPath, keypair.privateKey);
+
+    try {
+      const config = {
+        get: vi.fn((key: string, fallback?: unknown) => {
+          if (key === 'OAUTH_STRATEGY') return 'local-provider';
+          if (key === 'OAUTH_PRIVATE_KEY_PATH') return localPrivateKeyPath;
+          if (key === 'JWT_ACCESS_TTL_SECONDS') return 3600;
+          if (key === 'JWT_REFRESH_TTL_SECONDS') return 2592000;
+          return fallback;
+        }),
+      };
+      const module: TestingModule = await Test.createTestingModule({
+        providers: [JwtSignerAdapter, { provide: ConfigService, useValue: config }],
+      }).compile();
+      const localAdapter = module.get(JwtSignerAdapter);
+
+      const signingFailure = new Error('boom: unrelated signing failure');
+      // Reaching into the private jwtService is the only way to force a genuine signing failure —
+      // it is real key material otherwise, so there is no config-level way to make signAsync reject.
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      (localAdapter as any).jwtService.signAsync = vi.fn().mockRejectedValue(signingFailure);
+
+      await expect(localAdapter.signAccess({ aci: 'test-id' })).rejects.toBe(signingFailure);
+      await expect(localAdapter.signAccess({ aci: 'test-id' })).rejects.not.toBeInstanceOf(
+        TokenIssuanceDisabledError,
+      );
+    } finally {
+      rmSync(localTempDir, { recursive: true, force: true });
+    }
+  });
 });

package/dist/templates/backend/application/src/@aurora/modules/authentication/infrastructure/strategies/local-provider/jwt-signer.adapter.ts

@@ -1,10 +1,11 @@
-import { Injectable } from '@nestjs/common';
+import { Injectable, Logger } from '@nestjs/common';
 import { ConfigService } from '@nestjs/config';
 import { JwtService } from '@nestjs/jwt';
 import { createPublicKey, randomBytes } from 'node:crypto';
 import { readFileSync } from 'node:fs';
-import type { IHubSessionManager, IJwtSigner, SignedToken } from '../../../domain/ports';
-import { resolveAuthenticationMode } from '../../../domain/resolve-authentication-mode';
+import { TokenIssuanceDisabledError } from '../../../domain/errors/index.js';
+import type { IHubSessionManager, IJwtSigner, SignedToken } from '../../../domain/ports/index.js';
+import { resolveAuthenticationMode } from '../../../domain/resolve-authentication-mode.js';
 
 const DEFAULT_SESSION_TTL_SECONDS = 28800; // 8 hours
 
@@ -12,8 +13,34 @@ const ISSUER = 'Aurora Catalyst';
 const DEFAULT_PRIVATE_KEY_PATH = './.keys/oauth-private.key';
 const DEFAULT_ACCESS_TTL_SECONDS = 3600;
 const DEFAULT_REFRESH_TTL_SECONDS = 2592000;
+const DEFAULT_IMPERSONATION_TTL_SECONDS = 900;
+// F12 (security review, gate 12.2): a misconfigured impersonation TTL must never mint a token
+// with a nonsensical (NaN/negative) or implausibly long lifetime. Capped at the normal
+// access-token default — impersonation is short-lived BY DESIGN; a valid config value can never
+// legitimately need to exceed a normal session's own lifetime.
+const MAX_IMPERSONATION_TTL_SECONDS = 3600;
 const REFRESH_TOKEN_BYTES = 48; // 48 bytes → 64 chars in base64url (no padding)
 
+/**
+ * F12: validates a configured TTL is a finite, positive number within a sane upper bound before
+ * trusting it. Falls back to `DEFAULT_IMPERSONATION_TTL_SECONDS` (logging why) on any failure —
+ * scoped to `JWT_IMPERSONATION_TTL_SECONDS` only; the pre-existing
+ * JWT_ACCESS_TTL_SECONDS/JWT_REFRESH_TTL_SECONDS parsing is untouched (out of this change's lane).
+ */
+function parseImpersonationTtlSeconds(raw: string | number, logger: Logger): number {
+  const parsed = Number(raw);
+  if (Number.isFinite(parsed) && parsed > 0 && parsed <= MAX_IMPERSONATION_TTL_SECONDS) {
+    return parsed;
+  }
+
+  logger.warn(
+    `[JwtSignerAdapter] JWT_IMPERSONATION_TTL_SECONDS="${String(raw)}" is not a finite value in ` +
+      `(0, ${MAX_IMPERSONATION_TTL_SECONDS}] — falling back to the default of ` +
+      `${DEFAULT_IMPERSONATION_TTL_SECONDS}s`,
+  );
+  return DEFAULT_IMPERSONATION_TTL_SECONDS;
+}
+
 /**
  * Single adapter implementing both IJwtSigner (access/refresh token issuance) and
  * IHubSessionManager (hub_session sign/verify + access token verification).
@@ -24,11 +51,13 @@ const REFRESH_TOKEN_BYTES = 48; // 48 bytes → 64 chars in base64url (no paddin
  */
 @Injectable()
 export class JwtSignerAdapter implements IJwtSigner, IHubSessionManager {
+  private readonly logger = new Logger(JwtSignerAdapter.name);
   private readonly mode: 'none' | 'aurora-hub' | 'local-provider';
   private readonly jwtService: JwtService | null;
   private readonly accessTtlSeconds: number;
   private readonly refreshTtlSeconds: number;
   private readonly sessionTtlSeconds: number;
+  private readonly impersonationTtlSeconds: number;
 
   constructor(configService: ConfigService) {
     this.mode = resolveAuthenticationMode(configService.get<string>('OAUTH_STRATEGY'));
@@ -42,6 +71,7 @@ export class JwtSignerAdapter implements IJwtSigner, IHubSessionManager {
       this.accessTtlSeconds = DEFAULT_ACCESS_TTL_SECONDS;
       this.refreshTtlSeconds = DEFAULT_REFRESH_TTL_SECONDS;
       this.sessionTtlSeconds = DEFAULT_SESSION_TTL_SECONDS;
+      this.impersonationTtlSeconds = DEFAULT_IMPERSONATION_TTL_SECONDS;
       return;
     }
 
@@ -70,6 +100,13 @@ export class JwtSignerAdapter implements IJwtSigner, IHubSessionManager {
     this.sessionTtlSeconds = Number(
       configService.get<string | number>('OAUTH_SESSION_COOKIE_TTL', DEFAULT_SESSION_TTL_SECONDS),
     );
+    this.impersonationTtlSeconds = parseImpersonationTtlSeconds(
+      configService.get<string | number>(
+        'JWT_IMPERSONATION_TTL_SECONDS',
+        DEFAULT_IMPERSONATION_TTL_SECONDS,
+      ),
+      this.logger,
+    );
 
     this.jwtService = new JwtService({
       privateKey,
@@ -81,22 +118,34 @@ export class JwtSignerAdapter implements IJwtSigner, IHubSessionManager {
     });
   }
 
-  async signAccess(payload: { aci: string }): Promise<SignedToken> {
+  async signAccess(
+    payload: { aci: string; act?: { aci: string } },
+    options?: { ttlSeconds?: number },
+  ): Promise<SignedToken> {
     if (!this.jwtService) {
-      throw new Error(`token issuance disabled while OAUTH_STRATEGY=${this.mode}`);
+      // Typed (C12) so a caller can tell the MODE LIMITATION from a genuine signing failure below
+      // and stop reporting both as the same thing. Message unchanged.
+      throw new TokenIssuanceDisabledError(this.mode);
     }
 
-    const token = await this.jwtService.signAsync(
-      { aci: payload.aci },
-      { expiresIn: this.accessTtlSeconds },
-    );
-    const expiresAt = new Date(Date.now() + this.accessTtlSeconds * 1000);
+    // Explicit override wins; absent one, an impersonation token (act present) defaults to its
+    // own, independently-configured TTL instead of the normal access-token lifetime.
+    const ttlSeconds =
+      options?.ttlSeconds ?? (payload.act ? this.impersonationTtlSeconds : this.accessTtlSeconds);
+
+    // `act` forwarded only when present — never emitted as `act: undefined` (would still show up
+    // as an own enumerable key with `undefined` value on some JWT signers).
+    const claims = payload.act ? { aci: payload.aci, act: payload.act } : { aci: payload.aci };
+
+    const token = await this.jwtService.signAsync(claims, { expiresIn: ttlSeconds });
+    const expiresAt = new Date(Date.now() + ttlSeconds * 1000);
     return { token, expiresAt };
   }
 
   async signRefresh(): Promise<SignedToken> {
     if (!this.jwtService) {
-      throw new Error(`token issuance disabled while OAUTH_STRATEGY=${this.mode}`);
+      // Typed (C12) so a caller can tell the MODE LIMITATION from a genuine signing failure.
+      throw new TokenIssuanceDisabledError(this.mode);
     }
 
     // Refresh tokens are OPAQUE per RFC 6749 — not JWTs. Validation is DB-lookup only,
@@ -109,7 +158,8 @@ export class JwtSignerAdapter implements IJwtSigner, IHubSessionManager {
 
   signHubSession(accountId: string): string {
     if (!this.jwtService) {
-      throw new Error(`hub session signing disabled while OAUTH_STRATEGY=${this.mode}`);
+      // Typed (C12) so a caller can tell the MODE LIMITATION from a genuine signing failure.
+      throw new TokenIssuanceDisabledError(this.mode);
     }
     return this.jwtService.sign(
       { sub: accountId, type: 'hub_session' },