auth-yes/docs/PHASED_IMPLEMENTATION_PLAN.md

# Auth-Yes — Phased Architectural Implementation Roadmap

This document structures the complete cryptographic, zero-trust, and
high-velocity IAM enhancements into concrete, testable phases. Each phase is
broken down into modular technical stories with specific target files, test
specifications, and quality gate criteria.

---

## 1. Architectural Phases Overview

```mermaid
graph TD
    subgraph "Phase 1: Ingress Grant Ingestion & Real-Time Invalidation Bus"
        T11["Story 1.1: Ingress Grant Vector Injection (/api/forward-auth)"]
        T12["Story 1.2: SDK Real-Time Invalidation Event Bus (authSdk.on)"]
    end

    subgraph "Phase 2: Edge Autonomy & Non-Destructive UX"
        T21["Story 2.1: RFC 9421 Ed25519 Message Signatures & hwk Verification"]
        T22["Story 2.2: The Ghost Cockpit Protocol (WebSocket Non-Destructive Re-Auth)"]
        T23["Story 2.3: Sub-10µs Dynamic RBAC Bitwise Cache Engine"]
    end

    subgraph "Phase 3: Deep Cryptographic Sovereignty & Immutable Ledgers"
        T31["Story 3.1: WebAuthn PRF Extension & Progressive Feature Detection"]
        T32["Story 3.2: 2-of-3 Shamir's Secret Sharing (SSS) Wasm Recovery Matrix"]
        T33["Story 3.3: Native SIMD Argon2id Derivation in Rust FFI (spire_ffi)"]
        T34["Story 3.4: RFC 6962 Merkle Tree Audit Ledger with Micro-Batched STH"]
    end

    Phase 1 --> Phase 2 --> Phase 3
```

---

## 2. Phase 1: Ingress Grant Ingestion & Real-Time Invalidation Bus

### Story 1.1: Ingress Grant Vector Injection (`/api/forward-auth`)

- **Objective:** Update `/api/forward-auth` in `server/main.ts` to extract
  `X-Forwarded-Host`, look up the matching application grants for the
  authenticated session, and inject flattened grant headers:
  - `X-Forwarded-User-Id: <uuid>`
  - `X-Forwarded-User-Name: <username>`
  - `X-Forwarded-Scopes: <role1,role2>`
  - `X-Forwarded-App-Id: <app-name>`
- **Target Files:** `server/main.ts`, `server/main.test.ts`, `server/valkey.ts`
- **Verification:** Unit tests verifying `/api/forward-auth` returns `200 OK`
  with proper headers for granted applications, and `403 Forbidden` if
  default-deny grant is missing.

### Story 1.2: SDK Real-Time Invalidation Event Bus

- **Objective:** Extend `@auth-yes/sdk` with an event emitter
  (`authSdk.on("invalidate", (token) => ...)` and
  `authSdk.on("revoke_user", (userId) => ...)`) when Valkey RESP3 pushes
  `invalidate` events.
- **Target Files:** `sdk/mod.ts`, `sdk/mod.test.ts`
- **Verification:** Test verifying that when Valkey sends an invalidation push,
  registered listeners fire immediately with the affected token.

---

## 3. Phase 2: Edge Autonomy & Non-Destructive UX

### Story 2.1: RFC 9421 Ed25519 Message Signatures & `hwk` Verification

- **Objective:** Implement RFC 9421 HTTP Message Signatures parser and validator
  for edge nodes. Edge nodes submit `Signature-Input` and `Signature-Key` using
  Header Web Key (`hwk`) in Octet Key Pair (`OKP`) format. ForwardAuth verifies
  the signature and checks the SHA-256 fingerprint of the `hwk` against Valkey's
  authorized set in $<5\mu s$.
- **Target Files:** `server/http_signatures.ts`,
  `server/http_signatures.test.ts`, `sdk/mod.ts`
- **Verification:** Test canonical base derivation, timestamp validation
  ($\pm 30$s drift), nonce deduplication, and Ed25519 cryptographic
  verification.

### Story 2.2: The Ghost Cockpit Protocol (Non-Destructive Re-Auth)

- **Objective:** Formalize client-side and WebSocket server-side
  re-authentication protocols:
  1. On session expiry/revocation, server emits `{ "type": "AUTH_REVOKED" }`
     frame.
  2. UI freezes state in memory, triggers modal WebAuthn passkey ceremony.
  3. New session cookie negotiated $\rightarrow$ WebSocket reconnects without
     data loss.
- **Target Files:** `docs/GHOST_COCKPIT_SPEC.md`, `sdk/hono.ts`
- **Verification:** End-to-end simulation of WebSocket lifecycle during session
  purge.

### Story 2.3: Sub-10µs Dynamic RBAC Bitwise Cache Engine

- **Objective:** Synchronize PostgreSQL `grants` into flat bitwise permission
  vectors in Valkey 8 hashes (`auth:grants:<userId>:<appId>`), enabling
  microsecond authorization evaluations.
- **Target Files:** `server/db.ts`, `server/valkey.ts`, `server/main.ts`
- **Verification:** Benchmark testing resolving 10,000 permissions in $<10\mu s$
  per call.

---

## 4. Phase 3: Deep Cryptographic Sovereignty & Immutable Ledgers

### Story 3.1: WebAuthn PRF Extension & Progressive Feature Detection

- **Objective:** Implement WebAuthn PRF extension support during registration
  (`prf: {}`) and authentication (`eval: { first: salt }`), with progressive
  detection checking `getClientExtensionResults()?.prf?.enabled`.
- **Target Files:** `server/main.ts`, `ui/views/login.tsx`,
  `ui/views/register.tsx`, `sdk/mod.ts`
- **Verification:** Verification of SHA-256(`"WebAuthn PRF\0" + salt`) hardware
  derivation and AES-256-GCM symmetric key derivation via HKDF.

### Story 3.2: 2-of-3 Shamir's Secret Sharing (SSS) Wasm Recovery Matrix

- **Objective:** Implement constant-time 2-of-3 Shamir's Secret Sharing in
  WebAssembly/Rust for the client recovery iframe, with mandatory
  `Uint8Array.fill(0)` memory zeroization post-reconstruction.
- **Target Files:** `spire_ffi/src/sss.rs`, `ui/views/recovery.tsx`,
  `server/main.ts`
- **Verification:** Unit tests splitting master key into 3 shares, proving any 2
  shares reconstruct the key, and single shares reveal 0 bits.

### Story 3.3: Native SIMD Argon2id Derivation in Rust FFI (`spire_ffi`)

- **Objective:** Add native Argon2id derivation (12 iterations, 64 MiB memory,
  128-bit salt) to `spire_ffi` crate for high-throughput Hot Share derivation in
  Deno 2.
- **Target Files:** `spire_ffi/src/lib.rs`, `server/spire_ffi.ts`,
  `server/spire_ffi.test.ts`
- **Verification:** Benchmark testing native derivation throughput vs WebCrypto
  HKDF.

### Story 3.4: RFC 6962 Merkle Tree Audit Ledger with Micro-Batched STH

- **Objective:** Implement append-only Merkle Tree audit ledger in PostgreSQL.
  Micro-batch audit events every 30–60 seconds, compute Merkle Root, sign with
  SPIRE server key, and broadcast Signed Tree Head (STH) over Valkey pub/sub
  witness bus.
- **Target Files:** `server/audit_merkle.ts`, `server/audit_merkle.test.ts`,
  `server/audit.ts`
- **Verification:** Inclusion proof verification
  (`verifyInclusionProof(leaf, auditPath, rootHash) == true`) and tamper
  detection.