@aurorajs.dev/catalyst-cli 1.0.0

package/dist/templates/backend/application/src/@aurora/modules/authentication/infrastructure/factory/authentication-strategy.factory.spec.ts

@@ -0,0 +1,261 @@
+/**
+ * Unit tests for the authentication strategy factory and mode-aware adapters.
+ * Covers: none-mode dormant strategy, JwtSignerAdapter disabled behavior,
+ * and LocalProviderAdapter / JwtSignerAdapter skipping readFileSync in none mode.
+ */
+import { ConfigService } from '@nestjs/config';
+import { Test } from '@nestjs/testing';
+import { generateKeyPairSync } from 'node:crypto';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { ACCOUNT_LOADER } from '../../domain/ports';
+import { JwtSignerAdapter } from '../strategies/local-provider/jwt-signer.adapter';
+import { LocalProviderAdapter } from '../strategies/local-provider/local-provider.adapter';
+
+// ---------------------------------------------------------------------------
+// JwtSignerAdapter — none mode
+// ---------------------------------------------------------------------------
+
+describe('JwtSignerAdapter — none mode', () => {
+  let adapter: JwtSignerAdapter;
+
+  beforeEach(async () => {
+    const configService = {
+      get: jest.fn((key: string, fallback?: unknown) => {
+        if (key === 'OAUTH_STRATEGY') return 'none';
+        return fallback;
+      }),
+    };
+
+    const module = await Test.createTestingModule({
+      providers: [JwtSignerAdapter, { provide: ConfigService, useValue: configService }],
+    }).compile();
+
+    adapter = module.get(JwtSignerAdapter);
+  });
+
+  it('constructs without reading any key file (no readFileSync error)', () => {
+    // If this test reaches here without throwing, the constructor did not call readFileSync.
+    expect(adapter).toBeDefined();
+  });
+
+  it('signAccess throws a clear "disabled" error in none mode', async () => {
+    await expect(adapter.signAccess({ aci: 'test-id' })).rejects.toThrow(
+      /token issuance disabled.*OAUTH_STRATEGY=none/i,
+    );
+  });
+
+  it('signRefresh throws a clear "disabled" error in none mode', async () => {
+    await expect(adapter.signRefresh()).rejects.toThrow(
+      /token issuance disabled.*OAUTH_STRATEGY=none/i,
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// JwtSignerAdapter — local-provider mode (keys present)
+// ---------------------------------------------------------------------------
+
+describe('JwtSignerAdapter — local-provider mode', () => {
+  let tempDir: string;
+  let privateKeyPath: string;
+
+  beforeAll(() => {
+    const { privateKey } = generateKeyPairSync('rsa', {
+      modulusLength: 2048,
+      privateKeyEncoding: { format: 'pem', type: 'pkcs1' },
+      publicKeyEncoding: { format: 'pem', type: 'pkcs1' },
+    });
+    tempDir = mkdtempSync(join(tmpdir(), 'factory-spec-'));
+    privateKeyPath = join(tempDir, 'oauth-private.key');
+    writeFileSync(privateKeyPath, privateKey);
+  });
+
+  afterAll(() => {
+    rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it('constructs and signs tokens when mode is local-provider and key file exists', async () => {
+    const configService = {
+      get: jest.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;
+        return fallback;
+      }),
+    };
+
+    const module = await Test.createTestingModule({
+      providers: [JwtSignerAdapter, { provide: ConfigService, useValue: configService }],
+    }).compile();
+
+    const adapter = module.get(JwtSignerAdapter);
+    const result = await adapter.signAccess({ aci: 'test-id' });
+    expect(result.token).toBeDefined();
+    expect(result.expiresAt).toBeInstanceOf(Date);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// LocalProviderAdapter — none mode skips readFileSync
+// ---------------------------------------------------------------------------
+
+describe('LocalProviderAdapter — none mode skips readFileSync', () => {
+  it('constructs without reading any public key file (no readFileSync error)', async () => {
+    const configService = {
+      get: jest.fn((key: string, fallback?: unknown) => {
+        if (key === 'OAUTH_STRATEGY') return 'none';
+        return fallback;
+      }),
+    };
+
+    // In none mode there is no key file. The constructor must NOT call readFileSync.
+    // If it does, it will throw because the default path doesn't exist.
+    const module = await Test.createTestingModule({
+      providers: [
+        LocalProviderAdapter,
+        { provide: ConfigService, useValue: configService },
+        { provide: 'CACHE_MANAGER', useValue: {} },
+        { provide: ACCOUNT_LOADER, useValue: {} },
+      ],
+    }).compile();
+
+    const adapter = module.get(LocalProviderAdapter);
+    expect(adapter).toBeDefined();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// LocalProviderAdapter — aurora-hub mode skips readFileSync
+// ---------------------------------------------------------------------------
+
+describe('LocalProviderAdapter — aurora-hub mode skips readFileSync', () => {
+  it('constructs without reading any public key file (no readFileSync error)', async () => {
+    // aurora-hub mode: the local public key is irrelevant. Construction MUST NOT call
+    // readFileSync regardless of whether OAUTH_PUBLIC_KEY_PATH is set.
+    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_PUBLIC_KEY_PATH') return '/nonexistent/aurora-hub-test.key';
+        return fallback;
+      }),
+    };
+
+    const module = await Test.createTestingModule({
+      providers: [
+        LocalProviderAdapter,
+        { provide: ConfigService, useValue: configService },
+        { provide: 'CACHE_MANAGER', useValue: {} },
+        { provide: ACCOUNT_LOADER, useValue: {} },
+      ],
+    }).compile();
+
+    const adapter = module.get(LocalProviderAdapter);
+    expect(adapter).toBeDefined();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Authentication strategy factory — none mode returns a dormant strategy
+//
+// Note: the factory module imports AuroraHubConsumerAdapter which imports
+// `jwks-rsa` (ESM-only — not transformable by ts-jest). To work around this
+// known limitation (catalyst-backend-testing SKILL.md), we mock the entire
+// adapter module so the import chain doesn't reach jwks-rsa, then call the
+// factory's useFactory directly.
+// ---------------------------------------------------------------------------
+
+// Mock the ESM-importing module before any imports run.
+jest.mock('../strategies/aurora-hub/aurora-hub-consumer.adapter', () => ({
+  AuroraHubConsumerAdapter: class AuroraHubConsumerAdapterMock {},
+}));
+
+describe('authenticationStrategyProvider — none mode (direct factory call)', () => {
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  const { authenticationStrategyProvider } = require('./authentication-strategy.factory');
+
+  it('returns a dormant strategy with valid getPassportOptions() when mode is none', () => {
+    const configService = {
+      get: jest.fn((key: string) => {
+        if (key === 'OAUTH_STRATEGY') return 'none';
+        return undefined;
+      }),
+    };
+
+    // Minimal stub adapters — not used when mode=none
+    const stubAuroraHub = {} as never;
+    const stubLocalProvider = {} as never;
+
+    const strategy = authenticationStrategyProvider.useFactory(
+      configService,
+      stubAuroraHub,
+      stubLocalProvider,
+    );
+
+    const options = strategy.getPassportOptions();
+
+    expect(options).toBeDefined();
+    expect(options.jwtFromRequest).toBeDefined();
+    expect(options.secretOrKey).toBeDefined();
+  });
+
+  it('validate() throws a clear error if invoked in none mode (should never happen)', () => {
+    const configService = {
+      get: jest.fn((key: string) => {
+        if (key === 'OAUTH_STRATEGY') return 'none';
+        return undefined;
+      }),
+    };
+
+    const strategy = authenticationStrategyProvider.useFactory(configService, {}, {});
+
+    // validate() throws synchronously (never returns a Promise) because it must
+    // never be invoked — the guard short-circuits before passport in none mode.
+    expect(() => strategy.validate()).toThrow('noneStrategy.validate() must never be invoked');
+  });
+
+  it('returns the aurora-hub adapter stub when mode is aurora-hub', () => {
+    const configService = {
+      get: jest.fn((key: string) => {
+        if (key === 'OAUTH_STRATEGY') return 'aurora-hub';
+        return undefined;
+      }),
+    };
+
+    const stubAuroraHub = { getPassportOptions: jest.fn() } as never;
+    const stubLocalProvider = {} as never;
+
+    const strategy = authenticationStrategyProvider.useFactory(
+      configService,
+      stubAuroraHub,
+      stubLocalProvider,
+    );
+
+    expect(strategy).toBe(stubAuroraHub);
+  });
+
+  it('returns the local-provider adapter stub when mode is local-provider', () => {
+    const configService = {
+      get: jest.fn((key: string) => {
+        if (key === 'OAUTH_STRATEGY') return 'local-provider';
+        return undefined;
+      }),
+    };
+
+    const stubAuroraHub = {} as never;
+    const stubLocalProvider = { getPassportOptions: jest.fn() } as never;
+
+    const strategy = authenticationStrategyProvider.useFactory(
+      configService,
+      stubAuroraHub,
+      stubLocalProvider,
+    );
+
+    expect(strategy).toBe(stubLocalProvider);
+  });
+});

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

@@ -0,0 +1,81 @@
+import type { Provider } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import { ExtractJwt, type StrategyOptionsWithRequest } from 'passport-jwt';
+import { AUTHENTICATION_STRATEGY, type IAuthenticationStrategy } from '../../domain/ports';
+import { resolveAuthenticationMode } from '../../domain/resolve-authentication-mode';
+import { AuroraHubConsumerAdapter } from '../strategies/aurora-hub/aurora-hub-consumer.adapter';
+import { LocalProviderAdapter } from '../strategies/local-provider/local-provider.adapter';
+
+/**
+ * Authentication strategy registry. To add a new strategy (e.g. an OIDC external consumer
+ * for Phase 3 — Keycloak, Auth0, Azure AD), follow these four steps:
+ *
+ *   1. Create the adapter under `infrastructure/strategies/<name>/<name>.adapter.ts`
+ *      implementing `IAuthenticationStrategy`. The adapter's `getPassportOptions()` is
+ *      called once at boot when this strategy is selected; `validate(req, payload)` runs
+ *      per request and must return the same `AuthenticatedAccount` shape that
+ *      `AuroraHubConsumerAdapter` produces (downstream guards expect it).
+ *   2. Add the adapter class to the `inject` array below.
+ *   3. Add a new `if (mode === '<name>')` branch in `useFactory` before the throw.
+ *   4. Add the value to `resolveAuthenticationMode`'s `VALID_MODES` list (controls the
+ *      error message and validation).
+ *
+ * The adapter MUST be registered as a provider in `AuthenticationModule` (see the
+ * `providers` array there). If the new adapter has cross-BC dependencies (e.g. an IAM
+ * service), follow the `catalyst-cross-bounded-context-ports` skill: declare a port in
+ * `domain/ports/`, an adapter under `@bridges/<supplier-bc>/`, and a bridge provider in
+ * `BridgesModule`.
+ */
+
+/**
+ * Dormant strategy bound under `AUTHENTICATION_STRATEGY` when `OAUTH_STRATEGY=none`.
+ *
+ * `getPassportOptions()` returns a minimal valid options object so `JwtPassportStrategy`
+ * constructs without crashing. `validate()` is never invoked because `AuthenticationJwtGuard`
+ * short-circuits before passport runs in none mode.
+ */
+const NONE_STRATEGY_DUMMY_SECRET = 'aurora-none-mode-dummy-secret-never-used';
+
+const noneStrategy: IAuthenticationStrategy = {
+  getPassportOptions(): StrategyOptionsWithRequest {
+    return {
+      jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),
+      passReqToCallback: true,
+      secretOrKey: NONE_STRATEGY_DUMMY_SECRET,
+    };
+  },
+  validate(): Promise<object> {
+    // This method is NEVER called in none mode: the guard short-circuits before passport.
+    // If somehow reached, fail loudly so the bug is visible immediately.
+    throw new Error('noneStrategy.validate() must never be invoked');
+  },
+};
+
+export const authenticationStrategyProvider: Provider = {
+  provide: AUTHENTICATION_STRATEGY,
+  useFactory: (
+    configService: ConfigService,
+    auroraHubAdapter: AuroraHubConsumerAdapter,
+    localProviderAdapter: LocalProviderAdapter,
+  ): IAuthenticationStrategy => {
+    const mode = resolveAuthenticationMode(configService.get<string>('OAUTH_STRATEGY'));
+
+    if (mode === 'none') {
+      return noneStrategy;
+    }
+
+    if (mode === 'aurora-hub') {
+      return auroraHubAdapter;
+    }
+
+    if (mode === 'local-provider') {
+      return localProviderAdapter;
+    }
+
+    // resolveAuthenticationMode already throws for invalid values, but TypeScript
+    // requires exhaustive handling of the union for the return type.
+    const _exhaustive: never = mode;
+    throw new Error(`Unhandled authentication mode: ${String(_exhaustive)}`);
+  },
+  inject: [ConfigService, AuroraHubConsumerAdapter, LocalProviderAdapter],
+};

package/dist/templates/backend/application/src/@aurora/modules/authentication/infrastructure/guards/authentication-jwt.guard.spec.ts

@@ -0,0 +1,207 @@
+/**
+ * Unit test for AuthenticationJwtGuard.canActivate — none-mode shortcircuit.
+ *
+ * Note: testing @Auth-decorated classes via ts-jest pulls in ESM modules (cache-manager,
+ * jwks-rsa) that are not transpiled and break the test runner. This test exercises the
+ * guard CLASS DIRECTLY with a faked ExecutionContext, per the known ts-jest limitation
+ * documented in catalyst-backend-testing SKILL.md.
+ */
+import { Api } from '@aurorajs.dev/core-back';
+import { ExecutionContext } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import { Test } from '@nestjs/testing';
+import * as anonymousAccountModule from '../../domain/anonymous-account';
+import { AuthenticationJwtGuard } from './authentication-jwt.guard';
+
+// ---------------------------------------------------------------------------
+// Context factory helpers
+// ---------------------------------------------------------------------------
+
+function makeHttpContext(userContainer: { user?: unknown }): ExecutionContext {
+  return {
+    getType: () => 'http',
+    switchToHttp: () => ({
+      getRequest: () => userContainer,
+    }),
+    getClass: () => ({ name: 'TestController' }),
+    getHandler: () => ({ name: 'testHandler' }),
+    getArgs: () => [],
+    getArgByIndex: () => undefined,
+    switchToRpc: () => ({}),
+    switchToWs: () => ({}),
+  } as unknown as ExecutionContext;
+}
+
+function makeGraphqlContext(userContainer: { user?: unknown }): ExecutionContext {
+  return {
+    getType: () => 'graphql',
+    switchToHttp: () => ({
+      getRequest: () => ({}),
+    }),
+    getClass: () => ({ name: 'TestResolver' }),
+    getHandler: () => ({ name: 'testQuery' }),
+    getArgs: () => [null, null, { req: userContainer }, null],
+    getArgByIndex: (index: number) => {
+      const args = [null, null, { req: userContainer }, null];
+      return args[index];
+    },
+    switchToRpc: () => ({}),
+    switchToWs: () => ({}),
+  } as unknown as ExecutionContext;
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('AuthenticationJwtGuard', () => {
+  let guard: AuthenticationJwtGuard;
+  let configService: { get: jest.Mock };
+
+  beforeEach(async () => {
+    configService = { get: jest.fn() };
+    const module = await Test.createTestingModule({
+      providers: [AuthenticationJwtGuard, { provide: ConfigService, useValue: configService }],
+    }).compile();
+
+    guard = module.get(AuthenticationJwtGuard);
+  });
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  describe('mode=none — shortcircuit path', () => {
+    beforeEach(() => {
+      configService.get.mockImplementation((key: string) => {
+        if (key === 'OAUTH_STRATEGY') return 'none';
+        return undefined;
+      });
+    });
+
+    it('returns true for an HTTP context without calling super.canActivate', async () => {
+      const userContainer: { user?: unknown } = {};
+      const ctx = makeHttpContext(userContainer);
+
+      const superSpy = jest
+        .spyOn(Object.getPrototypeOf(Object.getPrototypeOf(guard)), 'canActivate')
+        .mockResolvedValue(true);
+
+      const result = await guard.canActivate(ctx);
+
+      expect(result).toBe(true);
+      expect(superSpy).not.toHaveBeenCalled();
+    });
+
+    it('injects an anonymous account into request.user (HTTP context)', async () => {
+      const userContainer: { user?: unknown } = {};
+      const ctx = makeHttpContext(userContainer);
+
+      // Mock Api.getRequestFromExecutionContext to return our container
+      jest.spyOn(Api, 'getRequestFromExecutionContext').mockReturnValue(userContainer);
+
+      // Confirm createAnonymousAccount IS called in none mode (counterpart to the
+      // local-provider negative assertion that it is NOT called).
+      const createAnonymousSpy = jest.spyOn(anonymousAccountModule, 'createAnonymousAccount');
+
+      await guard.canActivate(ctx);
+
+      expect(createAnonymousSpy).toHaveBeenCalledTimes(1);
+      expect(userContainer.user).toBeDefined();
+      const account = userContainer.user as { username: string; dPermissions: { all: string[] } };
+      expect(account.username).toBe('anonymous');
+      expect(account.dPermissions.all).toEqual([]);
+    });
+
+    it('injects an anonymous account into request.user (GraphQL context)', async () => {
+      const userContainer: { user?: unknown } = {};
+      const ctx = makeGraphqlContext(userContainer);
+
+      jest.spyOn(Api, 'getRequestFromExecutionContext').mockReturnValue(userContainer);
+
+      const result = await guard.canActivate(ctx);
+
+      expect(result).toBe(true);
+      const account = userContainer.user as { username: string; dPermissions: { all: string[] } };
+      expect(account.username).toBe('anonymous');
+      expect(account.dPermissions.all).toEqual([]);
+    });
+
+    it('injects a FRESH account object on each call (not a shared reference)', async () => {
+      const containerA: { user?: unknown } = {};
+      const containerB: { user?: unknown } = {};
+      const ctxA = makeHttpContext(containerA);
+      const ctxB = makeHttpContext(containerB);
+
+      jest
+        .spyOn(Api, 'getRequestFromExecutionContext')
+        .mockReturnValueOnce(containerA)
+        .mockReturnValueOnce(containerB);
+
+      await guard.canActivate(ctxA);
+      await guard.canActivate(ctxB);
+
+      expect(containerA.user).not.toBe(containerB.user);
+    });
+  });
+
+  describe('mode=local-provider — delegate to super path', () => {
+    beforeEach(() => {
+      configService.get.mockImplementation((key: string) => {
+        if (key === 'OAUTH_STRATEGY') return 'local-provider';
+        return undefined;
+      });
+    });
+
+    it('calls super.canActivate when mode is local-provider', async () => {
+      const userContainer: { user?: unknown } = {};
+      const ctx = makeHttpContext(userContainer);
+
+      const superSpy = jest
+        .spyOn(Object.getPrototypeOf(Object.getPrototypeOf(guard)), 'canActivate')
+        .mockResolvedValue(true);
+
+      await guard.canActivate(ctx);
+
+      expect(superSpy).toHaveBeenCalledWith(ctx);
+    });
+
+    it('does NOT call createAnonymousAccount in local-provider mode', async () => {
+      const userContainer: { user?: unknown } = {};
+      const ctx = makeHttpContext(userContainer);
+
+      // Spy on the module-level factory so we can assert the short-circuit
+      // code path (none mode) never fires when JWT mode is active.
+      const createAnonymousSpy = jest.spyOn(anonymousAccountModule, 'createAnonymousAccount');
+
+      jest
+        .spyOn(Object.getPrototypeOf(Object.getPrototypeOf(guard)), 'canActivate')
+        .mockResolvedValue(true);
+
+      await guard.canActivate(ctx);
+
+      // The short-circuit path must NOT have run: createAnonymousAccount is
+      // only called inside the `if (mode === 'none')` branch of the guard.
+      // If this assertion fails, the guard mistakenly ran the none-mode path
+      // for a JWT-based strategy — a security regression.
+      expect(createAnonymousSpy).not.toHaveBeenCalled();
+
+      // Confirm passport delegation happened (the super call is the JWT path).
+      // This is already covered by the sibling 'calls super.canActivate' test;
+      // repeating it here makes the negative guard self-contained.
+      expect(userContainer.user).toBeUndefined();
+    });
+  });
+
+  describe('handleRequest — unchanged rejection path', () => {
+    it('throws UnauthorizedException when user is falsy', () => {
+      expect(() => guard.handleRequest(null, null)).toThrow();
+    });
+
+    it('returns the user when valid', () => {
+      const user = { username: 'test', dPermissions: { all: [] } };
+      const result = guard.handleRequest(null, user);
+      expect(result).toBe(user);
+    });
+  });
+});

package/dist/templates/backend/application/src/@aurora/modules/authentication/infrastructure/guards/authentication-jwt.guard.ts

@@ -0,0 +1,52 @@
+import { Api } from '@aurorajs.dev/core-back';
+import { ExecutionContext, Injectable, UnauthorizedException } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import { AuthGuard } from '@nestjs/passport';
+import { Observable } from 'rxjs';
+import { createAnonymousAccount } from '../../domain/anonymous-account';
+import { resolveAuthenticationMode } from '../../domain/resolve-authentication-mode';
+
+@Injectable()
+export class AuthenticationJwtGuard extends AuthGuard('jwt') {
+  constructor(private readonly configService: ConfigService) {
+    super();
+  }
+
+  override canActivate(
+    context: ExecutionContext,
+  ): boolean | Promise<boolean> | Observable<boolean> {
+    const mode = resolveAuthenticationMode(this.configService.get<string>('OAUTH_STRATEGY'));
+
+    if (mode === 'none') {
+      // Short-circuit: inject an anonymous account and allow the request through.
+      // AuthorizationPermissionsGuard (unchanged) handles permission checks:
+      // dPermissions.all=[] lets through public endpoints and rejects @Auth('x') with 403.
+      const request = Api.getRequestFromExecutionContext<{ user?: unknown }>(context);
+      request.user = createAnonymousAccount();
+      return true;
+    }
+
+    // JWT modes: delegate to passport (the existing path is unchanged).
+    return super.canActivate(context);
+  }
+
+  // override the getRequest() method for return request from graphql or rest api.
+  getRequest<Request>(context: ExecutionContext): Request {
+    return Api.getRequestFromExecutionContext(context);
+  }
+
+  // Account returned by jwt.strategy in validate method (JwtStrategy).
+  // NOT weakened: passport rejection path is identical to before for JWT modes.
+  handleRequest<AccountResponse>(err: unknown, user: AccountResponse): AccountResponse {
+    if (err || !user) {
+      throw (
+        err ||
+        new UnauthorizedException({
+          statusCode: 401,
+          message: 'OAuthAccessToken not allowed',
+        })
+      );
+    }
+    return user;
+  }
+}

package/dist/templates/backend/application/src/@aurora/modules/authentication/infrastructure/guards/authorization-permissions.guard.ts

@@ -0,0 +1,33 @@
+import { Api } from '@aurorajs.dev/core-back';
+import { Arr } from '@aurorajs.dev/core-common';
+import { CanActivate, ExecutionContext, Injectable, UnauthorizedException } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import { Observable } from 'rxjs';
+
+@Injectable()
+export class AuthorizationPermissionsGuard implements CanActivate {
+  constructor(private readonly reflector: Reflector) {}
+
+  canActivate(context: ExecutionContext): boolean | Promise<boolean> | Observable<boolean> {
+    const apiPermissions = this.reflector.get<string[]>('permissions', context.getClass());
+    const accountPermissions = this.getRequest(context).user.dPermissions.all;
+
+    // if no permissions are defined, allow access
+    if (!apiPermissions || (Array.isArray(apiPermissions) && apiPermissions.length === 0))
+      return true;
+
+    if (Arr.intersects(apiPermissions, accountPermissions)) return true;
+
+    throw new UnauthorizedException({
+      statusCode: 403,
+      message:
+        'Forbidden resource, requires the following permissions ' + apiPermissions.join(', '),
+      error: 'Forbidden',
+    });
+  }
+
+  // override the getRequest() method for return request from graphql or rest api.
+  getRequest<T = any>(context: ExecutionContext): T {
+    return Api.getRequestFromExecutionContext(context);
+  }
+}

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

@@ -0,0 +1,2 @@
+export * from './authentication-jwt.guard';
+export * from './authorization-permissions.guard';

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

@@ -0,0 +1,15 @@
+import type { Provider } from '@nestjs/common';
+import { HUB_SESSION_MANAGER } from '../../domain/ports';
+import { JwtSignerAdapter } from '../strategies/local-provider/jwt-signer.adapter';
+
+/**
+ * Port-to-adapter binding for the hub session manager (intra-module DI, NOT a cross-BC bridge).
+ *
+ * `HUB_SESSION_MANAGER` is the token consumers `@Inject(...)` to obtain an `IHubSessionManager`
+ * implementation. `JwtSignerAdapter` implements both `IJwtSigner` and `IHubSessionManager` using
+ * the same RS256 key pair — `useExisting` reuses the singleton registered for `JwtSignerAdapter`.
+ */
+export const hubSessionManagerProvider: Provider = {
+  provide: HUB_SESSION_MANAGER,
+  useExisting: JwtSignerAdapter,
+};

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

@@ -0,0 +1,16 @@
+import type { Provider } from '@nestjs/common';
+import { JWT_SIGNER } from '../../domain/ports';
+import { JwtSignerAdapter } from '../strategies/local-provider/jwt-signer.adapter';
+
+/**
+ * Port-to-adapter binding for the JWT signer (intra-module DI, NOT a cross-BC bridge).
+ *
+ * `JWT_SIGNER` is the token consumers `@Inject(...)` to obtain an `IJwtSigner` implementation.
+ * Today the only implementation is `JwtSignerAdapter` (RS256, file-based key pair). To swap
+ * implementations (e.g. KMS-backed signer in Phase 3), provide an alternative class implementing
+ * `IJwtSigner` and replace the `useExisting` target.
+ */
+export const jwtSignerProvider: Provider = {
+  provide: JWT_SIGNER,
+  useExisting: JwtSignerAdapter,
+};