# TASK METADATA

- **Target Files:** `ui/mod.ts`, `ui/components/AppLaunchpadPage.tsx`,
  `ui/components/AuthenticatedLayout.tsx`, `server/main.test.ts`,
  `docs/HYBRID_INGRESS_PLAYBOOK.md`
- **Core Objective:** Architect and formalize the specification and
  implementation plan for Universal Logout Return-Path Preservation, Central SSO
  Application Launchpad, Hybrid Ingress Routing Playbook, and Strict Additive
  Security Audit.
- **Dependencies:** Existing UI layout system,
  `docs/FORWARDAUTH_REDIRECT_SPEC.md`, `server/auth-session.ts`, Merkle Tree
  Audit Ledger.
- **Additional Important Notes:** Must adhere strictly to Zero-Trust
  invisibility for ungranted apps. Must maintain 100% test coverage and ensure
  zero regressions across WebAuthn, SSS, and RFC 9421.

---

## 2. Architectural Considerations & Risks

Before detailing implementation steps, the following risks and constraints must
be strictly adhered to:

- **Risks:**
  - **Open-Redirect Vulnerability (CWE-601):** The `/logout?redirect=` endpoint
    is a prime target for phishing if not strictly validated against an approved
    whitelist.
  - **RBAC Data Leakage:** Exposing ungranted applications, even visually
    disabled, leaks internal network topology and service architecture.
  - **Regression of Cryptographic Core:** Modifying session lifecycle hooks
    (like logout) must not break the Merkle Tree Audit Ledger, WebAuthn PRF
    flows, or Edge Signatures.

- **Alternatives & Architecture Decisions:**
  - **Redirect Validation:** We will strictly implement the `isSafeRedirectUrl`
    logic defined in `docs/FORWARDAUTH_REDIRECT_SPEC.md` (`*.atyg.org`,
    `localhost`, relative paths) for both login and logout flows.
  - **Zero-Knowledge Launchpad:** Regular users will only see applications they
    have explicit grants for. Global Admins (`isGlobalAdmin = true`) will see
    all fleet applications.
  - **Cryptographic Auditing:** Explicit audit events (`logout_success`,
    `open_redirect_intercepted`) will be injected directly into the RFC 6962
    Merkle tree upon logout operations.

## 3. Proposed Implementation

The implementation must be executed in the following strict phases:

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

1. **Update `ui/mod.ts`:**
   - Extract the `redirect` query parameter in the `GET /logout` handler.
   - Implement strict whitelist validation (`isSafeRedirectUrl`):
     - Must allow relative paths (`/`).
     - Must allow explicit wildcard `*.atyg.org` or `localhost`.
   - **Audit Integration:**
     - If validation fails, immediately log an `open_redirect_intercepted` event
       to the Merkle Audit Ledger (including client IP, original requested URL,
       and blocked destination), then discard the parameter.
     - Upon successful session destruction (cache + DB wipe), log a
       `logout_success` audit event.
   - Redirect the user to `/login?redirect=${encodeURIComponent(safeRedirect)}`
     (if a safe redirect exists), otherwise fallback to `/login`.

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

1. **Create `ui/components/AppLaunchpadPage.tsx`:**
   - Build a pure Hono SSR JSX component rendering interactive application
     cards.
   - Each card must display the app name, description, role indicator (e.g.,
     `Admin`, `Operator`), and a 1-click launch link.
2. **Update Route `GET /dashboard` in `ui/mod.ts`:**
   - Change the default `/dashboard` redirect to render `AppLaunchpadPage`.
   - Update navigation in `ui/components/AuthenticatedLayout.tsx` to include the
     new Launchpad as the primary dashboard view.
3. **Zero-Trust Query Logic:**
   - Fetch the authenticated user and their `isGlobalAdmin` status.
   - **Regular Users:** Query `grants` JOIN `apps` to fetch strictly only the
     applications they possess an active grant for.
   - **Global Admins:** Query `apps` to fetch all applications, annotating them
     with an `[Admin]` badge and providing a direct link to the IAM Management
     Console.

### Phase 3: Hybrid Ingress Routing Pattern & Playbook

1. **Document `docs/HYBRID_INGRESS_PLAYBOOK.md`:**
   - Provide concrete reference configurations for consumer web applications
     requiring hybrid public splash views alongside protected private cockpits.
   - Detail the dual-routing pattern: Traefik edge ForwardAuth protection for
     `/control-panel`, `/ws`, `/api/*` + App/SDK-level SSR hydration on the root
     `/`.

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

1. **Test Coverage Additions (`server/main.test.ts`):**
   - Write tests validating the open-redirect whitelist logic in `/logout`.
   - Write tests verifying Zero-Knowledge visibility of the Launchpad (users see
     only granted apps, admins see all).
   - Write tests verifying the new audit log events (`logout_success`,
     `open_redirect_intercepted`) are correctly appended.
2. **Pre/Post Hermetic Test Mandate:**
   - All 42+ existing unit tests in `server/*.test.ts` and `sdk/*.test.ts` MUST
     pass hermetically before and after modifications.
3. **End-to-End QA Checklist (To be included in Completion Report):**
   - [ ] Verify WebAuthn PRF extension negotiation (`/api/login/challenge` &
         `/api/register/verify`).
   - [ ] Verify 2-of-3 SSS Wasm memory zeroization and key reconstruction
         (Scenario A & Scenario B).
   - [ ] Verify RFC 9421 Ed25519 signature verification against the O(1) Valkey
         fingerprint set.
4. **Coverage Validation Requirement:**
   - Run the following command before final submission:
     `deno test -A --unstable-ffi --coverage=cov_profile && deno coverage cov_profile`
   - Include the generated coverage table in the PR description / final
     completion summary.