147 lines
6.3 KiB
Markdown
147 lines
6.3 KiB
Markdown
# 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.
|