d100495ead
Created the task file for formalizing the Ghost Cockpit Protocol and its corresponding WebSocket guard helper in the SDK, adhering strictly to the required guidelines. Co-authored-by: mrteye <1945243+mrteye@users.noreply.github.com>
68 lines
3.4 KiB
Markdown
68 lines
3.4 KiB
Markdown
# 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.
|