# TASK METADATA

- **Target Files:** `ui/mod.ts`, `ui/components/AppLaunchpadPage.tsx`,
  `ui/components/AuthenticatedLayout.tsx`, `server/audit.ts`,
  `server/main.test.ts`, `docs/HYBRID_INGRESS_PLAYBOOK.md`
- **Core Objective:** Implement Central SSO Application Launchpad, Logout
  Return-Path Preservation (`GET /logout?redirect=...`), SIEM Cryptographic
  Merkle Auditing, and Hybrid Ingress Playbook.
- **Dependencies:** Pure Hono SSR JSX UI system,
  `docs/FORWARDAUTH_REDIRECT_SPEC.md`, `server/auth-session.ts`, RFC 6962 Merkle
  Audit Ledger.
- **Additional Important Notes:** Must adhere strictly to Zero-Trust
  invisibility (regular users see only granted apps; Global Admins see all apps
  with `[Admin]` badge). Must maintain 100% test coverage with zero regressions
  across WebAuthn, SSS, and RFC 9421.

---

### 1. TASK METADATA

(Defined in the header block above)

### 2. Architectural Considerations & Risks

- **Risks & Vulnerabilities:**
  - **Open-Redirect Attacks (CWE-601):** Unvalidated `?redirect=` parameters on
    `GET /logout` present severe phishing attack vectors. All destination
    targets must be strictly validated against the approved domain whitelist
    (`*.atyg.org`, `localhost`, and relative paths).
  - **RBAC Topology Leakage:** Displaying ungranted applications on the
    Launchpad (even in a greyed-out or disabled state) leaks internal network
    topology, microservice hostnames, and organizational tooling to unauthorized
    users. Ungranted apps must be completely invisible to non-admin users.
  - **Session Cookie Domain Duplication:** When logging out, failing to wipe
    both host-scoped and parent wildcard (`.atyg.org`) cookies causes lingering
    session collisions across subdomains.
  - **Cryptographic Audit Gaps:** Failing to log intercepted open-redirect
    attempts deprives security teams of automated anomaly detection during
    phishing campaigns.

- **Alternatives & Architecture Decisions:**
  - **Zero-Knowledge Launchpad:** Regular users query `grants` JOIN `apps` to
    view strictly their authorized services. Global Admins
    (`isGlobalAdmin = true`) query `apps` to see all applications annotated with
    an `[Admin]` badge and a 1-click link to the IAM Management Console.
  - **Pure Hono SSR JSX Purity:** In strict adherence to `AGENTS.md`,
    `AppLaunchpadPage.tsx` must be 100% React-free, utilizing lightweight pure
    JSX templates and CSS grid layout matching `Layout.tsx`.
  - **Cryptographic SIEM Auditing:** Explicit audit events (`logout_success`,
    `open_redirect_intercepted`) are appended directly to the RFC 6962 Merkle
    tree ledger and broadcast over Valkey channel `auth:audit:sth`.

### 3. Proposed Implementation

#### Phase 1: Logout Return-Path Preservation (`GET /logout`)

1. **Update `GET /logout` Handler (`ui/mod.ts`):**
   - Extract `redirect` query parameter from the request.
   - Validate target using `isSafeRedirectUrl(redirect)` (allowing `*.atyg.org`,
     `localhost`, and relative paths).
   - **Audit Integration:**
     - If validation fails, log `open_redirect_intercepted` to `audit_records`
       (including client IP, raw URL, and discarded destination), then discard
       the parameter.
     - Upon session deletion in Valkey and PostgreSQL, log `logout_success`.
   - Clear session cookies across both host and parent wildcard domain
     (`getCookieDomain()`).
   - If a valid `redirect` was supplied, redirect to
     `/login?redirect=${encodeURIComponent(safeRedirect)}`, otherwise redirect
     to `/login`.

#### Phase 2: Central SSO Application Launchpad (App Switcher)

1. **Create Launchpad Component (`ui/components/AppLaunchpadPage.tsx`):**
   - Author a pure Hono SSR JSX page rendering responsive card tiles for
     authorized applications.
   - Each card displays app title, description, domain link
     (`https://<domain>`), role badge (`Admin`, `Operator`, `Viewer`), and
     1-click "Launch" button.
2. **Mount Launchpad Route (`ui/mod.ts`):**
   - Update `GET /dashboard` to render `AppLaunchpadPage` as the default
     authenticated landing view.
   - Update `ui/components/AuthenticatedLayout.tsx` navigation bar to feature
     "Launchpad" alongside Sessions, Passkeys, and Admin Console.
3. **Zero-Trust Query Logic (`ui/mod.ts`):**
   - Authenticate session via `getAuthenticatedUser(c)`.
   - Check `isAdmin = await isGlobalAdmin(auth.userId)`.
   - If `isAdmin`: Fetch all apps from `apps` table.
   - Else: Fetch only apps where `grants.user_id = auth.userId`.

#### Phase 3: Hybrid Ingress Routing Playbook

1. **Author `docs/HYBRID_INGRESS_PLAYBOOK.md`:**
   - Provide concrete reference architectures for consumer applications needing
     hybrid public splash pages alongside protected private cockpits.
   - Detail the dual-routing pattern: Traefik ForwardAuth on `/control-panel`,
     `/ws`, `/api/*` + App/SDK-level SSR hydration on root `/`.

#### Phase 4: Strict Additive Security & Regression Audit

1. **Pre/Post Hermetic Test Suite Verification:**
   - Execute all 42+ existing unit tests in `server/*.test.ts` and
     `sdk/*.test.ts` to guarantee 0 regressions.
2. **New Unit Tests (`server/main.test.ts`):**
   - Test `GET /logout` preserves valid `?redirect=https://ed-droid.atyg.org/`
     and redirects to `/login?redirect=...`.
   - Test `GET /logout` intercepts and discards malicious
     `?redirect=https://evil.com`, logging `open_redirect_intercepted`.
   - Test Launchpad Zero-Knowledge query logic (regular user sees only granted
     apps; admin sees all).
3. **Manual End-to-End QA Checklist (Included in PR Summary):**
   - [ ] WebAuthn PRF extension negotiation (`/api/login/challenge` &
         `/api/register/verify`).
   - [ ] 2-of-3 SSS Wasm memory zeroization and key reconstruction (Scenario A &
         Scenario B).
   - [ ] RFC 9421 Ed25519 signature verification against $O(1)$ Valkey
         fingerprint set.
4. **Coverage Validation Requirement:**
   - Run
     `deno test -A --unstable-ffi --coverage=cov_profile && deno coverage cov_profile`
     and attach the coverage report to the PR summary.

---

### 4. Quality Gates & Verification Checklist

- [ ] All 42+ unit tests passing hermetically.
- [ ] Zero lint warnings (`deno task lint`).
- [ ] Zero typecheck errors (`deno task check`).
- [ ] Code formatted with `deno fmt`.