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

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.

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.

6.3 KiB Raw Blame History Unescape Escape