feat(auth): FAM/Cognito SPA sign-in via Amplify (Story 1.2) (#300)

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: gpascucci

.github/workflows/reusable-tests.yml

@@ -68,6 +68,13 @@ jobs:
     # raw-Playwright frontend/e2e). Only the DATA-INDEPENDENT `@smoke` project runs here: it aborts /api,
     # so it needs neither the seeded delivery Oracle nor the pinned fixtures the deployed env lacks. The
     # full data-backed suite (setup + chromium — SCH1/SEC) is a LOCAL/manual gate; see frontend/e2e/README.md.
+    #
+    # The smoke runs against a LOCAL Vite server on localhost, NOT the deployed PR URL. Since Story 1.2
+    # turned auth on, mock auth is (by design) disabled off-localhost — `isMockAuth()` double-gates on
+    # `isLocalHost()` (src/env.ts) — so an anonymous visit to a deployed host correctly bounces to the
+    # FAM/Cognito Hosted UI and never renders the shell. On localhost with the repo-default
+    # `{ mockUser: true }` config the shell renders client-side, keeping this smoke auth- AND
+    # backend-independent (the scenarios still abort every /api call).
     defaults:
       run:
         working-directory: frontend/e2e
@@ -82,17 +89,28 @@ jobs:
           node-version: 24
           cache: "npm"
           cache-dependency-path: frontend/e2e/package-lock.json
-      - name: Install dependencies
+      - name: Install e2e dependencies
         run: |
           npm ci
           npx playwright install --with-deps chromium
 
-      - name: Run smoke (data-independent)
+      - name: Install frontend
+        working-directory: frontend
+        run: npm ci
+
+      - name: Run smoke (data-independent, localhost mock auth)
+        working-directory: frontend
         env:
-          E2E_BASE_URL: https://${{ env.PREFIX }}.${{ env.DOMAIN }}/
           CI: "true"
         run: |
-          npm test -- --project=smoke --reporter=html
+          # Serve the app on localhost so mock auth engages (isMockAuth() requires localhost); the
+          # @smoke scenarios abort /api, so no backend is needed. No E2E_BASE_URL → the Playwright
+          # config defaults baseURL to http://localhost:3000.
+          npm run dev -- --port 3000 &
+          DEV_PID=$!
+          npx --yes wait-on -t 120000 http://localhost:3000
+          ( cd e2e && npm test -- --project=smoke --reporter=html )
+          kill "$DEV_PID" 2>/dev/null || true
 
       - uses: actions/upload-artifact@v7
         if: (! cancelled())

README.md

@@ -107,6 +107,49 @@ The recommended, zero-import workaround is to leverage your Windows host's trust
    ```
    Docker Compose will automatically detect this variable and mount your local Windows Maven cache into the container's `/root/.m2` path, bypassing the certificate handshake issues completely!
 
+### Authentication (FAM/Cognito) — local testing
+
+The SPA has two auth modes, selected at runtime by `public/amplify-config.js` (loaded before the
+bundle). The repo default is **mock**; deployed environments mount a per-env ConfigMap over it. See
+`src/context/auth/` (the `AuthProvider` seam) and `src/config/auth/amplify-initializer.ts`.
+
+**Mock mode (default — no Cognito).** `npm run dev` with the backend running (security off by
+default) signs you in automatically. Use the **"Mock user"** dropdown in the header to switch
+`ILCR_ADMIN` ↔ `ILCR_SUBMITTER` — it switches both the nav/route-guards **and** the backend mock
+principal (via the `X-Mock-Groups` header), so it exercises role gating end to end. This is the
+fastest path for manual testing.
+
+**Real FAM/Cognito login (Hosted UI).**
+
+1. Frontend — copy the example config over the default (do **not** commit it; the repo default must
+   stay `mockUser: true`):
+   ```bash
+   cd frontend
+   cp amplify-config.local.example.js public/amplify-config.js
+   npm run dev            # then hard-refresh the browser (public/ files load at page load)
+   ```
+2. Backend — run with security on so `/api/v1/me` validates the real ID token:
+   ```bash
+   cd backend
+   ILCR_SECURITY_ENABLED=true COGNITO_REGION=ca-central-1 \
+   COGNITO_USER_POOL=ca-central-1_UpeAqsYt4 COGNITO_CLIENT_ID=352pis0ark86dam7ht1jlp9uj5 \
+   SPRING_PROFILES_ACTIVE=oracle,openshift ./mvnw spring-boot:run
+   ```
+3. Open `http://localhost:3000` → FAM Hosted UI → sign in (IDIR/BCeID) → back to the app with your
+   real role. Confirm the exact `cognitoDomain` with the FAM admin if the Hosted UI does not load.
+
+**Dev-only testing aids (real session, local dev only — `import.meta.env.DEV`, tree-shaken from every
+deployed build):**
+
+- **"View as (dev)"** header dropdown — overrides the role the SPA uses (nav + route guards) so you
+  can test both roles without re-logging-in. It is **frontend-only**: the backend still enforces your
+  real token, so admin APIs still `403` if your account isn't really in that group.
+- A **"viewing as" warning banner** appears whenever an override is active, naming your real role.
+- A **Sign out** button (header, Logout icon) runs the Cognito/loginproxy logout chain on a real
+  session; hidden in mock mode.
+
+When done with real login: `git checkout -- frontend/public/amplify-config.js`.
+
 ## Frontend Shared Conventions
 
 Reusable building blocks and global styles that new schedule/feature pages should adopt rather than

frontend/amplify-config.local.example.js

@@ -0,0 +1,24 @@
+// Local real-FAM-login example (DEV Cognito client).
+//
+// Copy this over `public/amplify-config.js` to exercise the real Cognito Hosted UI locally:
+//     cp amplify-config.local.example.js public/amplify-config.js
+// Do NOT commit your edited public/amplify-config.js — the repo default must stay { mockUser: true }.
+//
+// These are public identifiers (Cognito pool + SPA web-client id), not secrets. Run the backend with
+// security on so /api/v1/me validates the real token:
+//     ILCR_SECURITY_ENABLED=true COGNITO_REGION=ca-central-1 \
+//     COGNITO_USER_POOL=ca-central-1_UpeAqsYt4 COGNITO_CLIENT_ID=352pis0ark86dam7ht1jlp9uj5 \
+//     SPRING_PROFILES_ACTIVE=oracle,openshift ./mvnw spring-boot:run
+//
+// Confirm with the FAM admin (Ian): the exact cognitoDomain, and that your IDIR account carries an
+// ILCR group in the DEV pool (otherwise you correctly land on the No-access screen). Values from
+// Ian's 2026-07-28 FAM config; the DEV client allow-lists http://localhost:3000/.
+window.amplifyConfig = {
+  mockUser: false,
+  userPoolId: 'ca-central-1_UpeAqsYt4',
+  userPoolClientId: '352pis0ark86dam7ht1jlp9uj5', // DEV web client
+  cognitoDomain: 'lza-prod-fam-user-pool-domain.auth.ca-central-1.amazoncognito.com',
+  redirectSignIn: 'http://localhost:3000/',
+  redirectSignOut:
+    'https://logontest7.gov.bc.ca/clp-cgi/logoff.cgi?retnow=1&returl=https://dev.loginproxy.gov.bc.ca/auth/realms/standard/protocol/openid-connect/logout?redirect_uri=http://localhost:3000/logout',
+}

frontend/index.html

@@ -10,6 +10,9 @@
   </head>
   <body>
     <div id="root"></div>
+    <!-- Runtime Cognito config, injected before the bundle. Local dev serves the mock template from
+         public/; each deployed environment mounts a ConfigMap over this file (no secrets in the image). -->
+    <script src="/amplify-config.js"></script>
     <script type="module" src="/src/main.tsx"></script>
   </body>
 </html>