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

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>