# Production implementation plan

## Implementation status — 31 August 2026

The core authentication foundation below is implemented locally in the
production Hub and Fleet code. It has passed its unit, Docker-profile, syntax,
responsive baseline, and browser-console checks. It has not yet been deployed;
the full browser-state/accessibility matrix remains an acceptance activity.
Live acceptance must also verify Hub Entra sign-in with allowed and forbidden
customer accounts, and Fleet portal SSO with the deployed portal assertion.

## Foundation slice: authentication experience

Ship this before presenting the redesigned Hub as a customer preview. It uses
the existing identity providers and changes the browser experience around them;
it does not create another password store.

### Hub work

1. Add customer-branded access assets and the signed-in account menu:
   - `hub/templates/access.html`
   - `hub/static/auth.css`
   - `hub/static/auth.js`
2. Set `ENTRA_LOGIN_PAGE=/access` and add `/access` to the Entra login-path
   allowlist. Map `cancelled`, `invalid`, `failed`, `forbidden`, `technical`,
   `logged_out`, and `session_expired` to designed states.
3. Replace the generic logout HTML in `hub/rc_entra.py`; no Hub route or copy
   may refer to Kennisbank.
4. Preserve only server-allowlisted relative destinations through login and
   session expiry. Show the destination in human language when useful.
5. Add `/api/session` for the account menu. Return display identity, role,
   organization, and expiry only; never return the signed session value.
6. Add `prompt=select_account` for explicit account switch and after logout.
7. Keep `AUTH_MODE=dev` and its native Basic dialog isolated to visibly named
   development hosts. Acceptance/customer preview deployments use Entra.

### Fleet work

1. Move the inline `LOGIN_PAGE` in `rc-fleet/app/server.py` to a template and
   static stylesheet matching the Fleet control-plane shell.
2. Keep RapidCloud portal SSO as the primary path and add designed states for
   portal unavailable, invalid assertion, and missing operator role.
3. Move password access under an explicit `Emergency access` disclosure. Add
   CSRF protection, rate limits, success/failure audit events, and alerting.
4. Sign Fleet sessions with an independent rotated secret and include operator
   identity, issued-at, and expiry. Do not derive session integrity from the
   emergency password.
5. Change browser logout to `POST` with CSRF protection. Keep HTTP Basic only
   for non-browser compatibility while scoped automation credentials are built.

### Authentication tests

- Hub redirect/callback tests for valid login, cancellation, invalid state,
  exchange failure, forbidden tenant/domain, technical validation failure,
  explicit account switch, safe `next`, unsafe `next`, expiry, and logout.
- Assert every browser error returns branded HTML and never raw JSON, tokens,
  provider error descriptions, stack traces, or Kennisbank copy.
- Fleet tests for portal assertion signature, issuer, audience, expiry,
  allowlist, session expiry, CSRF, rate limiting, and emergency audit events.
- Assert HTML requests never trigger native Basic Auth in Fleet and production
  Hub profiles cannot start in development mode.
- Playwright screenshots for each prototype authentication state at desktop and
  mobile widths, plus keyboard/focus and account-menu dismissal tests.

### Authentication acceptance criteria

- The simulated development URL is labelled as development and is never shared
  as the customer sign-in preview.
- Customer Hub entry, expiry, forbidden, retry, account-switch, and signed-out
  states are branded for that customer.
- Microsoft password, MFA, consent, and Conditional Access remain on Microsoft
  pages; Hub never imitates them.
- Fleet SSO is visually primary and emergency access is collapsed, audited,
  rate-limited, and operationally alerted.
- Account menus in Hub and Fleet expose current identity, role, switch-account,
  and logout with keyboard and screen-reader support.

## First releasable slice: Hub home

The first production change should make Hub immediately useful without waiting
for the full Fleet redesign.

### Outcome

A signed-in customer can see their organization, open every active app, and
understand health/version/update state from one responsive screen. Customer
administrators retain the existing request and release routes during migration.

### Backend work

1. Add migration `rc-fleet/db/002_experience_v2.sql`:
   - `customer_app_config` for customer/environment launch URLs.
   - branding cache/version fields or a small catalog-presentation table.
   - `label`, `last_used_at`, and optional `expires_at` on Hub tokens.
2. Update `require_customer` to record token `last_used_at` without adding it to
   the response path's critical failure modes.
3. Add `GET /v2/home` as specified in `api-contract.md`.
4. Resolve latest **compatible approved** release, not merely latest global
   stable release.
5. Seed launch URLs for the simulation/test customer first; refuse `can_open`
   when a launch URL is absent.
6. Cache/fallback branding presentation. Do not make Fleet a second branding
   editor.

### Hub work

1. Move page markup and CSS out of `hub/server.py` into:
   - `hub/templates/base.html`
   - `hub/templates/home.html`
   - `hub/static/hub.css`
   - `hub/static/hub.js`
2. Add a small view-model adapter from `/v2/home` to template data. Keep network
   and cache behavior outside the template.
3. Preserve the last-good cache, now including app launch URLs and the exact
   successful-sync timestamp.
4. Keep `Open app` enabled from last-good data during degraded mode. Disable
   requests, updates, and settings when their source state is stale.
5. Load the customer theme from the published brand/theme source with a bundled
   neutral RapidCloud fallback.
6. Keep the existing `/apps`, `/releases/*`, `/nieuws`, and `/docs` routes as
   compatibility redirects or secondary pages until their redesigned screens
   ship.

### Tests

- Fleet unit tests for licensed/unlicensed/requested apps, no launch URL,
  compatible release selection, heartbeat age, and token scoping.
- Hub unit tests for fresh, partial, degraded-with-cache, and no-cache states.
- Role tests: employee never receives request/update controls; customer admin
  does.
- Signed-out, expired-session, forbidden-account, and account-menu states from
  the foundation slice remain covered while Hub Home is migrated.
- Playwright screenshots at 1440x1000, 768x1024, and 390x844.
- Keyboard-only navigation and visible focus review.
- No page-level horizontal overflow at supported widths.
- Existing profile/degraded-mode gates continue to pass.

### Acceptance criteria

- An active configured app opens in one action.
- Health, environment, current version, and update state are visible without a
  detail-page visit.
- Customer branding is applied; RapidCloud management attribution remains
  visible but secondary.
- Fleet outage shows the last successful sync time and does not break app
  launching.
- No Azure credentials, customer content, documents, prompts, or end-user IPs
  are added to Fleet.

## Second slice: deployment runs and Hub update review

1. Add `deployment_runs` and `deployment_run_events`.
2. Add Hub create-run, customer-pipeline callback, and read endpoints.
3. Replace browser confirmation with the review dialog flow.
4. Surface Azure what-if output as a sanitized summary or a link to the
   customer pipeline.
5. Verify final success against the post-deploy heartbeat.
6. Support exact rollback to the previous digest-pinned manifest.

## Third slice: Fleet command center

1. Add the command-center read model and stable exception filters.
2. Replace the single hidden-section page with real, linkable routes.
3. Build production exception queue and responsive deployment list.
4. Add customer detail pages with token metadata and audit history.
5. Keep RC factory/test Azure stage controls separate from customer-reported
   deployments and add confirmations to state-changing actions.

## Follow-on slices

- Structured request/license work queue.
- Release validation, preview, and promotion workflow.
- Communication drafting, audience, scheduling, and delivery state.
- Token rotation/revocation and alert ownership.
- Discover, documentation viewer, and customer notification settings.

## Migration rule

All work is additive until deployed customer Hubs are confirmed on v2. Existing
v1 routes and release/deployment scripts remain supported throughout the
migration.