Mantine UI and standard auth (#7)

Author: alex-struk

apps/backend-services/package.json

@@ -25,7 +25,6 @@
     "db:seed": "tsx prisma/seed.ts"
   },
   "dependencies": {
-    "@bcgov/citz-imb-sso-express": "^1.0.2",
     "@nestjs/axios": "4.0.1",
     "@nestjs/common": "^11.0.1",
     "@nestjs/config": "^4.0.2",

apps/backend-services/src/auth/README.md

@@ -0,0 +1,43 @@
+# Auth Module Overview
+
+This folder contains the NestJS pieces that implement the confidential OAuth 2.0 Authorization Code flow against Keycloak. The backend acts as the confidential client and handles all exchanges with the identity provider; the frontend only ever receives the provider-issued tokens after the server validates and temporarily stores them.
+
+## Flow Summary
+
+1. `GET /auth/login` creates a signed `state` token + nonce and redirects the browser to Keycloak.
+2. Keycloak redirects back to `GET /auth/callback` with `code` and `state`.
+3. `AuthService.handleCallback` verifies `state`, exchanges the code for tokens, validates the ID token, and saves the token bundle in `AuthSessionStore`, returning an opaque `resultId`.
+4. The controller redirects the browser to the SPA with `?auth_result=resultId`.
+5. The SPA immediately calls `GET /auth/result?result=resultId` to retrieve the tokens; the entry is deleted after this call.
+6. Refreshes happen via `POST /auth/refresh`, which proxies the refresh token to Keycloak.
+7. Protected routes rely on `BCGovAuthGuard` and (optionally) `RolesGuard` to validate bearer tokens and enforce RBAC.
+
+## Key Components
+
+| File | Responsibility |
+| --- | --- |
+| `auth.service.ts` | Builds Keycloak URLs, exchanges codes, validates ID tokens, and manages one-time auth results. |
+| `auth.controller.ts` | Exposes `/auth/login`, `/auth/callback`, `/auth/result`, `/auth/refresh`, and `/auth/logout`. |
+| `auth-session.store.ts` | In-memory, short-lived cache used to hand provider tokens to the SPA exactly once. |
+| `bcgov-auth.guard.ts` | Validates incoming bearer tokens via JWKS, enforces issuer+audience, and projects normalized Keycloak roles onto the request. |
+| `roles.guard.ts` | Enforces role metadata from `@Roles` decorators. |
+| `dto/*.ts` | DTOs that validate every auth route payload/query via Nest's ValidationPipe. |
+
+## Configuration Flags
+
+- `SSO_*` variables configure the Keycloak realm, client id/secret, and redirect URIs.
+- `FRONTEND_URL` is used for redirecting the browser back to the SPA after login/logout.
+- `AUTH_STATE_SECRET` signs the state JWT; defaults to the client secret.
+- `AUTH_RESULT_TTL_SECONDS` controls how long an auth result can be redeemed (default 60).
+
+## Validation & Guardrails
+
+- Every auth controller route accepts a DTO (body or query) that is validated by the global `ValidationPipe`, preventing malformed requests from reaching the business logic.
+- `BCGovAuthGuard` now verifies both the issuer and the `aud` claim (matching `SSO_CLIENT_ID`) and normalizes Keycloak's realm/resource role claims into a single `roles` array for downstream guards.
+
+## Testing Tips
+
+- Ensure the Keycloak client redirect URI points to `/auth/callback` on the backend.
+- Watch backend logs during login; failures will emit `callback_failed` redirects.
+- Because `AuthSessionStore` is in-memory, a backend restart invalidates in-flight `auth_result` ids.
+

apps/backend-services/src/auth/auth-session.store.ts

@@ -0,0 +1,65 @@
+import { Injectable, NotFoundException } from "@nestjs/common";
+import { ConfigService } from "@nestjs/config";
+import { randomUUID } from "crypto";
+import type { TokenResponse } from "./auth.service";
+
+interface StoredTokens {
+  tokens: TokenResponse;
+  expiresAt: number;
+}
+
+/**
+ * Lightweight in-memory store for short-lived auth results.
+ * Each entry is consumed exactly once by the SPA immediately after OAuth redirect.
+ * This avoids persisting sessions server-side while still preventing token leakage in URLs.
+ */
+@Injectable()
+export class AuthSessionStore {
+  private readonly ttlMs: number;
+  private readonly store = new Map<string, StoredTokens>();
+
+  constructor(private configService: ConfigService) {
+    const ttlSeconds = Number(
+      this.configService.get<string>("AUTH_RESULT_TTL_SECONDS") ?? "60",
+    );
+    this.ttlMs = ttlSeconds * 1000;
+
+    // Background sweeper keeps the map from growing unbounded if the SPA never redeems an id.
+    setInterval(() => this.cleanupExpired(), this.ttlMs).unref();
+  }
+
+  /**
+   * Saves provider tokens and returns a one-time opaque identifier.
+   */
+  save(tokens: TokenResponse): string {
+    const id = randomUUID();
+    this.store.set(id, {
+      tokens,
+      expiresAt: Date.now() + this.ttlMs,
+    });
+    return id;
+  }
+
+  /**
+   * Reads and immediately deletes a stored token bundle.
+   */
+  consume(id: string): TokenResponse {
+    const entry = this.store.get(id);
+    if (!entry || entry.expiresAt < Date.now()) {
+      this.store.delete(id);
+      throw new NotFoundException("Auth result expired or invalid");
+    }
+
+    this.store.delete(id);
+    return entry.tokens;
+  }
+
+  private cleanupExpired(): void {
+    const now = Date.now();
+    for (const [id, entry] of this.store.entries()) {
+      if (entry.expiresAt < now) {
+        this.store.delete(id);
+      }
+    }
+  }
+}

apps/backend-services/src/auth/auth.controller.ts

@@ -0,0 +1,115 @@
+import {
+  Controller,
+  Post,
+  Body,
+  Get,
+  Query,
+  Res,
+  HttpStatus,
+} from "@nestjs/common";
+import { Response } from "express";
+import { AuthService } from "./auth.service";
+import { Public } from "./public.decorator";
+import {
+  AuthResultQueryDto,
+  LogoutQueryDto,
+  OAuthCallbackQueryDto,
+  RefreshTokenDto,
+} from "./dto";
+
+/**
+ * Thin HTTP layer that exposes the OAuth entrypoints to the frontend.
+ * All routes are public because authorization happens via bearer tokens on other controllers.
+ */
+@Controller("auth")
+export class AuthController {
+  constructor(private readonly authService: AuthService) {}
+
+  /**
+   * Backend endpoint the SPA uses to refresh provider tokens.
+   * Delegates to AuthService so only the backend interacts with Keycloak using the client secret.
+   */
+  @Public()
+  @Post("refresh")
+  async refreshToken(@Body() body: RefreshTokenDto) {
+    const tokens = await this.authService.refreshAccessToken(
+      body.refresh_token,
+    );
+    return {
+      access_token: tokens.access_token,
+      refresh_token: tokens.refresh_token,
+      id_token: tokens.id_token,
+      expires_in: tokens.expires_in,
+    };
+  }
+
+  /**
+   * Redirects the browser to the Keycloak authorization endpoint.
+   * Using a backend redirect keeps client_id/secret pairing server-side (no exposed secrets).
+   */
+  @Public()
+  @Get("login")
+  async getLoginUrl(@Res() res: Response) {
+    try {
+      const loginUrl = this.authService.getLoginUrl();
+      res.redirect(loginUrl);
+    } catch {
+      res
+        .status(HttpStatus.INTERNAL_SERVER_ERROR)
+        .json({ error: "Failed to generate login URL" });
+    }
+  }
+
+  /**
+   * Drives the browser through the Keycloak logout endpoint (if an ID token hint is provided).
+   * This ensures realm sessions are terminated and the SPA gets a clean slate.
+   */
+  @Public()
+  @Get("logout")
+  async logout(@Query() query: LogoutQueryDto, @Res() res: Response) {
+    try {
+      const logoutUrl = this.authService.getLogoutUrl(query.id_token_hint);
+      res.redirect(logoutUrl);
+    } catch {
+      res
+        .status(HttpStatus.INTERNAL_SERVER_ERROR)
+        .json({ error: "Failed to generate logout URL" });
+    }
+  }
+
+  /**
+   * Receives the redirect from Keycloak after the user authenticates.
+   * Converts the authorization code into tokens and then bounces the browser back to the SPA
+   * with an opaque `auth_result` identifier.
+   */
+  @Public()
+  @Get("callback")
+  async oauthCallback(
+    @Query() query: OAuthCallbackQueryDto,
+    @Res() res: Response,
+  ) {
+    try {
+      const resultId = await this.authService.handleCallback(
+        query.code,
+        query.state,
+      );
+      const redirectUrl = this.authService.buildAuthResultRedirect(resultId);
+      return res.redirect(redirectUrl);
+    } catch (error) {
+      console.error("OAuth callback handling failed:", error);
+      const redirectUrl =
+        this.authService.buildErrorRedirect("callback_failed");
+      return res.redirect(redirectUrl);
+    }
+  }
+
+  /**
+   * One-time endpoint the SPA calls immediately after redirect to retrieve the provider tokens.
+   * The `resultId` is invalidated after the first successful read to keep the flow stateless.
+   */
+  @Public()
+  @Get("result")
+  async consumeResult(@Query() query: AuthResultQueryDto) {
+    return this.authService.consumeAuthResult(query.result);
+  }
+}

apps/backend-services/src/auth/auth.module.ts

@@ -3,10 +3,16 @@ import { ConfigModule } from "@nestjs/config";
 import { APP_GUARD } from "@nestjs/core";
 import { BCGovAuthGuard } from "./bcgov-auth.guard";
 import { RolesGuard } from "./roles.guard";
+import { AuthController } from "./auth.controller";
+import { AuthService } from "./auth.service";
+import { AuthSessionStore } from "./auth-session.store";
 
 @Module({
   imports: [ConfigModule],
+  controllers: [AuthController],
   providers: [
+    AuthService,
+    AuthSessionStore,
     {
       provide: APP_GUARD,
       useClass: BCGovAuthGuard,
@@ -16,5 +22,6 @@ import { RolesGuard } from "./roles.guard";
       useClass: RolesGuard,
     },
   ],
+  exports: [AuthService],
 })
 export class AuthModule {}