# TASK METADATA

- **Target Files:** `docs/GHOST_COCKPIT_SPEC.md`, `sdk/hono.ts`,
  `sdk/hono.test.ts`
- **Core Objective:** Formalize the Ghost Cockpit Protocol specification and
  write server/client reference helpers in `@auth-yes/sdk/hono` to support
  non-destructive WebSocket telemetry freezes and seamless in-flight WebAuthn
  re-authentication.
- **Dependencies:** Deno 2.x native WebSocket support, `AuthSdk` event bus
  (`.on("invalidate")`) in `sdk/mod.ts`.
- **Additional Important Notes:** Must use native Hono `upgradeWebSocket` (do
  not use `@hono/node-ws`). Client-side snippet demonstrating state-freeze and
  background WebAuthn re-auth must be embedded within the spec markdown file.

---

### 2. Architectural Considerations & Risks

- **Risks:**
  - **Memory Leaks:** If the WebSocket closes gracefully or errors out and the
    `authSdk.off("invalidate")` cleanup is not correctly executed, the SDK's
    listener map will leak memory over time.
  - **Connection State Race Conditions:** Emitting the
    `{ "type": "AUTH_REVOKED", "reason": "SESSION_EXPIRED" }` frame and closing
    the socket must happen cleanly. The helper must handle scenarios where the
    socket is already in a `CLOSING` or `CLOSED` state to avoid uncaught
    exceptions during invalidation.
  - **Blocking the Event Loop:** The `invalidate` event handler executes within
    the SDK's Valkey push handler context. The WebSocket control frame emission
    must not block or crash this primary loop.

- **Alternatives:**
  - We evaluated creating a dedicated Valkey Pub/Sub channel exclusively for
    WebSocket termination. However, since `AuthSdk` already utilizes RESP3 BCAST
    tracking and exposes a robust `.on("invalidate")` bus, utilizing this
    existing mechanism directly in `sdk/hono.ts` is the cleanest, most
    zero-dependency approach. It avoids adding unnecessary architectural layers.

### 3. Proposed Implementation

1. **Formalize `docs/GHOST_COCKPIT_SPEC.md`:**
   - Document the choreography for the Ghost Cockpit Protocol.
   - Explain the concept of freezing UI/telemetry state in memory upon receiving
     the `AUTH_REVOKED` WebSocket frame.
   - Embed a complete, reference client-side TypeScript snippet demonstrating
     the background WebAuthn re-authentication flow (zero-redirect) and
     subsequent reconnection and state resumption.

2. **Implement WebSocket Guard in `sdk/hono.ts`:**
   - Create a reusable helper (e.g., `createWebSocketAuthGuard` or
     `createWebSocketSessionManager`).
   - The helper will take an `AuthSdk` instance and a session token.
   - It will attach an `invalidate` listener to the SDK. When the specific token
     is invalidated, it will send the `AUTH_REVOKED` JSON string to the active
     WebSocket and then explicitly close the connection.
   - It will include robust lifecycle hooks to guarantee
     `authSdk.off("invalidate", handler)` is called when the WebSocket closes
     naturally or errors out.
   - Add JSDoc comments to the helper with brief server-side usage examples
     demonstrating its use alongside Hono's `upgradeWebSocket`.

3. **Testing:**
   - Update `sdk/hono.test.ts` to include tests for the new WebSocket guard
     helper.
   - Mock the `AuthSdk` invalidation emission to verify the helper sends the
     correct payload and gracefully closes the mock WebSocket.
   - Verify the unregister cleanup logic executes correctly on socket close.