Merge pull request #20 from mrteye/feat/sso-launchpad-task-file-4077230937799430847

docs: draft phase 4 sso launchpad and logout spec
2026-08-24 14:12:51 -07:00 · 2026-08-24 14:12:51 -07:00 · 9ace888b4b
commit 9ace888b4b
parent 4fce954c86 b0dd2d098c
2 changed files with 126 additions and 11 deletions
--- a/tasks/JULES_PROMPTS.md
+++ b/tasks/JULES_PROMPTS.md
@ -9,18 +9,18 @@ and

 ## Progress & Execution Roadmap

-| Prompt ID      | Task Scope                                             | Status                          | Target File                                   |
-| :------------- | :----------------------------------------------------- | :------------------------------ | :-------------------------------------------- |
-| **Prompt 1.1** | Ingress Grant Vector Injection (`/api/forward-auth`)   | ✅ **COMPLETE**                 | `server/main.ts`, `server/auth-session.ts`    |
-| **Prompt 1.2** | SDK Real-Time Invalidation Event Bus (`@auth-yes/sdk`) | ✅ **COMPLETE**                 | `sdk/mod.ts`                                  |
-| **Prompt 3.2** | Native SIMD Argon2id Derivation in `spire_ffi`         | ✅ **COMPLETE**                 | `spire_ffi/src/lib.rs`, `server/spire_ffi.ts` |
-| **Prompt 2.2** | Ghost Cockpit Protocol & WebSocket Freeze/Re-Auth      | ✅ **COMPLETE**                 | `docs/GHOST_COCKPIT_SPEC.md`, `sdk/hono.ts`   |
-| **Prompt 2.1** | RFC 9421 HTTP Signatures & `Signature-Key` (`hwk`)     | ✅ **COMPLETE**                 | `server/http_signatures.ts`, `server/main.ts` |
-| **Prompt 3.1** | WebAuthn PRF Extension & Progressive Fallback          | ✅ **COMPLETE**                 | `server/main.ts`, `ui/public/auth-client.js`  |
-| **Prompt 3.3** | 2-of-3 SSS Recovery Matrix (Wasm/Rust)                 | ✅ **COMPLETE**                 | `ui/components/RecoveryPage.tsx`, `wasm/`     |
-| **Prompt 3.4** | RFC 6962 Merkle Tree Audit Ledger & STH                | ✅ **COMPLETE**                 | `server/audit_merkle.ts`, `server/audit.ts`   |
+| Prompt ID      | Task Scope                                             | Status                                          | Target File                                   |
+| :------------- | :----------------------------------------------------- | :---------------------------------------------- | :-------------------------------------------- |
+| **Prompt 1.1** | Ingress Grant Vector Injection (`/api/forward-auth`)   | ✅ **COMPLETE**                                 | `server/main.ts`, `server/auth-session.ts`    |
+| **Prompt 1.2** | SDK Real-Time Invalidation Event Bus (`@auth-yes/sdk`) | ✅ **COMPLETE**                                 | `sdk/mod.ts`                                  |
+| **Prompt 3.2** | Native SIMD Argon2id Derivation in `spire_ffi`         | ✅ **COMPLETE**                                 | `spire_ffi/src/lib.rs`, `server/spire_ffi.ts` |
+| **Prompt 2.2** | Ghost Cockpit Protocol & WebSocket Freeze/Re-Auth      | ✅ **COMPLETE**                                 | `docs/GHOST_COCKPIT_SPEC.md`, `sdk/hono.ts`   |
+| **Prompt 2.1** | RFC 9421 HTTP Signatures & `Signature-Key` (`hwk`)     | ✅ **COMPLETE**                                 | `server/http_signatures.ts`, `server/main.ts` |
+| **Prompt 3.1** | WebAuthn PRF Extension & Progressive Fallback          | ✅ **COMPLETE**                                 | `server/main.ts`, `ui/public/auth-client.js`  |
+| **Prompt 3.3** | 2-of-3 SSS Recovery Matrix (Wasm/Rust)                 | ✅ **COMPLETE**                                 | `ui/components/RecoveryPage.tsx`, `wasm/`     |
+| **Prompt 3.4** | RFC 6962 Merkle Tree Audit Ledger & STH                | ✅ **COMPLETE**                                 | `server/audit_merkle.ts`, `server/audit.ts`   |
 | **Prompt 4.1** | Traefik Tier 1 Universal Global Ingress Control        | ⏳ **IN PLANNING (Jules #6742583984777370201)** | `infra/`, Host Traefik Config                 |
-| **Prompt 4.2** | SSO Launchpad, Logout Return-Path & Hybrid Ingress     | ⏳ **IN PLANNING (Next Milestone)** | `ui/`, `server/`, `docs/`                     |
+| **Prompt 4.2** | SSO Launchpad, Logout Return-Path & Hybrid Ingress     | ⏳ **IN PLANNING (Next Milestone)**             | `ui/`, `server/`, `docs/`                     |

 ---

--- a/tasks/new/2026-0824.01.jul.story.app-launchpad.sso-launchpad-and-logout-2100.md
+++ b/tasks/new/2026-0824.01.jul.story.app-launchpad.sso-launchpad-and-logout-2100.md
@ -0,0 +1,115 @@
+# 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.