From 31e4bd51c48a774beb3805be24f2d2b59e2093aa Mon Sep 17 00:00:00 2001 From: Tyler Gillispie Date: Sun, 23 Aug 2026 20:35:14 -0700 Subject: [PATCH] docs: add phased implementation plan and pre-configured Jules orchestrator meta-prompts --- docs/Auth-Yes System Enhancement Research.md | 625 +++++++++++++++++++ docs/PHASED_IMPLEMENTATION_PLAN.md | 146 +++++ tasks/JULES_PROMPTS.md | 151 +++++ 3 files changed, 922 insertions(+) create mode 100644 docs/Auth-Yes System Enhancement Research.md create mode 100644 docs/PHASED_IMPLEMENTATION_PLAN.md create mode 100644 tasks/JULES_PROMPTS.md diff --git a/docs/Auth-Yes System Enhancement Research.md b/docs/Auth-Yes System Enhancement Research.md new file mode 100644 index 0000000..e8b4fe3 --- /dev/null +++ b/docs/Auth-Yes System Enhancement Research.md @@ -0,0 +1,625 @@ +# **Strategic Architecture and Cryptographic Frontiers for the Auth-Yes Zero-Trust IAM Ecosystem** + +## **Executive Summary and Architectural Mandate** + +The architectural mandate for the next-generation Auth-Yes Identity and Access +Management (IAM) ecosystem demands an infrastructure that operates as a perfect, +indefinite solution characterized by maximal security, frictionless automation, +and unparalleled ease of use1. Achieving a state of indefinite perfection +requires abandoning the fragile legacy constructs of OAuth2, OpenID Connect +(OIDC), and Security Assertion Markup Language (SAML). These legacy federations +are historically plagued by bearer token exfiltration, endless redirect loops, +and catastrophic vulnerabilities stemming from centralized server-side +secrets1.\ +Instead, the synthesis of current research indicates that the future of +enterprise and consumer IAM lies in a strictly decentralized, zero-trust +microservice architecture1. This architecture must be anchored by 100% +phishing-proof Web Authentication (WebAuthn) passkeys, hardware-bound symmetric +key derivation algorithms, and extreme high-throughput caching networks1. To +push the Auth-Yes project beyond the boundaries of conventional system design, +the architecture incorporates advanced cryptographic frontiers drawn from +decentralized finance, distributed ledger technology, and emerging Internet +Engineering Task Force (IETF) draft standards1.\ +By integrating WebAuthn Pseudo-Random Function (PRF) extensions for +deterministic encryption, Shamir's Secret Sharing (SSS) for decentralized +recovery matrices, Merkle Tree structures for immutable audit ledgers, and +Ephemeral Ed25519-Signed HTTP Headers for edge authentication, the Auth-Yes +architecture is designed to operate securely across profoundly untrusted +networks1. Furthermore, through deep automation techniques like Byte-1 +Server-Side Rendering (SSR) Hydration and the non-destructive Ghost Cockpit +Protocol, the system abstracts this immense cryptographic complexity away from +the user, ensuring the solution remains the premier standard indefinitely1. + +## **The "Two-Locks" Defense-in-Depth Architecture** + +The structural foundation of the Auth-Yes ecosystem is predicated on a +"Two-Locks" defense-in-depth security model, which fundamentally rejects the +flawed assumption that any internal network can be trusted1. This dual-layered +architecture enforces rigorous authorization checks both at the network +perimeter edge and directly within the highly volatile memory space of the +individual application runtime1. + +### **Lock 1: The Perimeter Guard and Edge Rejection** + +The first lock operates as a universal, edge-level inspection layer, powered by +the Traefik ForwardAuth middleware1. The primary function of this boundary layer +is to intercept all incoming ingress traffic, validate the presence of +cryptographic session material, and execute routing decisions in a matter of +microseconds before traffic ever reaches core application logic1. By +intercepting traffic at the absolute edge, the system effectively shields +internal microservices from unauthenticated reconnaissance, lateral header +spoofing, and volumetric application-layer denial-of-service attacks1.\ +To optimize throughput and ensure maximum automated availability, the Traefik +perimeter guard utilizes a sophisticated Dual-Router pattern1. The network +topology establishes a Priority 100 router designed specifically for public +bypass routes, health checks, and automated Command Line Interface (CLI) +scripts, allowing non-sensitive, unauthenticated traffic to pass unhindered1. +Simultaneously, a Priority 10 router is deployed to rigorously defend the +authenticated secure web boundary1. When unauthenticated or malicious +traffic—such as automated bot activity or unauthorized payload manipulation—is +detected, the perimeter guard drops the connection or triggers automated +user-interface redirects in under a millisecond, effectively neutralizing +external probes without consuming internal compute resources1. This addresses +the research directive for Ingress Boundary Hardening (Frontier 9), formalizing +the network topology to absolutely prevent lateral header spoofing by +off-the-shelf containers that might otherwise bypass application-layer checks1. + +### **Lock 2: The Zero-Trust Core and Sub-Millisecond Invalidation** + +While the Traefik edge provides robust perimeter defense, the Zero-Trust Core +operates under the assumption that the internal network has already been +compromised by an advanced persistent threat. The second lock relies on an +in-app Software Development Kit (SDK) embedded directly within the application +runtime—typically deployed on minimal Alpine Linux containers utilizing the Deno +2 runtime for extreme Web Cryptography performance1.\ +This internal token validation mechanism achieves unprecedented velocity by +integrating Valkey 8, specifically leveraging the REdis Serialization Protocol +version 3 (RESP3) Client-Side Cache Tracking capabilities1. High-performance +caching clients in the Golang and Deno ecosystems execute automatic request +pipelining and subscribe to broadcast (BCAST) invalidation messages instantly +propagated across the distributed cluster8. The deep integration of Valkey 8 +BCAST architecture allows the embedded in-app SDK to validate access tokens +entirely in volatile memory in under 30 microseconds, entirely bypassing the +network round-trips to an authentication database that cripple traditional +monolithic architectures1.\ +The critical vulnerability in systems relying on short-lived JSON Web Tokens +(JWTs) is the revocation window; if a token is stolen or a user's access is +terminated, the token remains valid until its expiration timestamp is reached. +The Auth-Yes Zero-Trust Core eliminates this vulnerability. When a session must +be terminated or a role is revoked, the Valkey RESP3 Push Invalidation protocol +guarantees a global, cluster-wide cache purge in less than one millisecond1. +This ensures that revoked access rights are instantly and mathematically +enforced across the entire microservice mesh, closing the window of +vulnerability completely. + +### **Sub-10 Microsecond RBAC Resolution** + +To ensure that extreme security does not impede the system's mandate for high +automation and performance, the architecture aggressively optimizes the +authorization decision engine, defined in the research dossier as Frontier 8: +Sub-10µs RBAC Resolution1. Traditional Role-Based Access Control (RBAC) engines +execute complex SQL join operations against relational databases for every +incoming authorization request, introducing unacceptable latency overheads in +microservice architectures1.\ +The Auth-Yes system utilizes a strictly decoupled Default-Deny RBAC schema +housed in PostgreSQL 181. Under this paradigm, identities possess absolutely +zero permissions until explicitly granted via a central table1. To achieve +sub-10 microsecond resolution, the system synchronizes these complex permission +matrices into flat vectors of granted permissions directly within the Valkey 8 +cluster1. The in-app SDK can then evaluate deeply nested permission requirements +instantly via in-memory bitwise comparisons, pushing runtime authorization to +speeds previously considered unattainable1. + +## **Automated Workload Identity via Zero-Copy SPIFFE/SPIRE** + +Human authentication represents only one half of the identity matrix in a +perfect system; automated microservice-to-microservice communication requires +equal, if not superior, cryptographic rigor1. To make the system "highly +automatic" without burdening platform engineers with manual, error-prone secret +management, the internal Auth-Yes ecosystem relies on the Secure Production +Identity Framework for Everyone (SPIFFE) and the SPIFFE Runtime Environment +(SPIRE)1.\ +Internal inter-service communications, operating over high-throughput ConnectRPC +and HTTP/2 protocols, are automatically secured using SPIRE cryptographic +container attestation1. This mechanism autonomously provisions, manages, and +rotates short-lived x509 SPIFFE Verifiable Identity Documents (SVIDs) over +strictly controlled UNIX domain sockets1. This implementation guarantees +zero-trust mutual Transport Layer Security (mTLS) workload identity, ensuring +that lateral movement by an attacker who manages to compromise a single +container is mathematically blocked by the TLS handshake failure1.\ +To optimize this process further and eliminate processing bottlenecks, the +architecture explores Frontier 3: Zero-Copy SPIRE SVID Rotation1. Traditional +mTLS rotation requires significant memory copying and Transmission Control +Protocol (TCP) overhead. By utilizing Rust Foreign Function Interfaces (FFI) +integrated directly into the Deno 2 runtime, the Auth-Yes system can update and +seamlessly rotate mTLS certificates in memory with absolute zero TCP latency1. +This advancement allows microservices to negotiate secure channels and rotate +keys autonomously thousands of times per second without degrading the broader +network throughput1. + +## **Maximal Security: The Phishing-Proof WebAuthn Authority** + +To achieve an indefinite state of maximal security, the Auth-Yes system is +engineered as a 100% Pure WebAuthn Passkey Authority1. The architecture +fundamentally and categorically rejects all legacy, phishing-susceptible +authentication fallbacks, including Short Message Service (SMS) one-time +passwords, magic email links, and traditional passwords1. These legacy methods +rely on shared secrets or inherently interceptable communication channels, +rendering them perpetually vulnerable to social engineering and +adversary-in-the-middle (AiTM) attacks2.\ +Instead, identity within the Auth-Yes ecosystem is inextricably bound to +cryptographic hardware enclaves—such as YubiKeys, the Apple Secure Enclave, or +Windows Hello Trusted Platform Modules (TPMs)—via a Multi-Passkey Mesh1. This +approach leverages asymmetric cryptography standardized by the W3C WebAuthn and +FIDO2 specifications to authenticate users without ever storing shared secrets +on a centralized server2. During registration, the user's secure hardware +generates a P-256 or Ed25519 key pair, storing the private key safely inside the +unexportable hardware boundary and sending only the public key to the Auth-Yes +relying party2.\ +However, standard asymmetric WebAuthn signatures only prove possession of a +private key; they cannot encrypt or decrypt payload data natively2. To achieve +the goal of a perfect, highly secure system capable of decentralized data +protection, the architecture must move beyond simple signatures. + +### **The WebAuthn Pseudo-Random Function (PRF) Extension** + +The most profound cryptographic evolution powering the Auth-Yes zero-trust core +is the deep integration of the WebAuthn Pseudo-Random Function (PRF) extension2. +Originally pioneered in high-security decentralized finance applications and +seedless self-custodial Bitcoin wallet architectures, the PRF extension bridges +the gap between hardware authentication and deterministic symmetric +encryption2.\ +The PRF extension allows the browser's JavaScript environment to request the +hardware authenticator to evaluate a highly deterministic cryptographic HMAC +function over a provided salt2. Unlike standard WebAuthn operations, this +extension enables the generation of high-entropy symmetric key material bound +directly to the hardware's internal secrets, effectively turning a biometric +passkey into a cryptographic derivation engine2.\ +To utilize this mechanism, the system must interact with the +navigator.credentials.create and navigator.credentials.get browser APIs using +highly specific extension payloads11. + +| Operational Phase | API Invocation | WebAuthn extensions Payload Structure | Purpose and System Behavior | +| :----------------- | :----------------------------- | :------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Registration** | navigator.credentials.create() | prf: {} | Passing an empty PRF object signals intent to the authenticator, instructing it to generate and permanently associate an internal PRF symmetric key with the newly created credential12. | +| **Authentication** | navigator.credentials.get() | prf: { eval: { first: encryptionSalt } } | The server provides a deterministic salt. The authenticator evaluates this salt against its internal secret, returning a 32-byte high-entropy pseudo-random string directly to the client memory13. | +| **Key Rotation** | navigator.credentials.get() | prf: { eval: { first: oldSalt, second: newSalt } } | Allows atomic key rotation. The authenticator processes both salts sequentially, returning two distinct 32-byte secrets to unwrap legacy data and re-encrypt with fresh keys simultaneously14. | + +When a user authenticates, the Auth-Yes backend provides a deterministic salt to +the client14. The client requests the authenticator to evaluate this salt via +the eval.first parameter13. To prevent cross-protocol attacks where an adversary +might trick an authenticator into signing a malicious payload disguised as a PRF +request, the authenticator strictly prefixes the provided salt with the byte +string "WebAuthn PRF", followed by a zero byte, and hashes the entire construct +with SHA-256 before evaluation15.\ +The resulting output is a deterministic, cryptographically secure 32-byte binary +string14. Because a PRF output is inherently raw entropy, the Auth-Yes system +utilizes the Web Cryptography API to pass this 32-byte string through a +Hash-based Message Authentication Code Extract-and-Expand Key Derivation +Function (HKDF)12. The HKDF derives a robust symmetric key, specifically an +AES-256-GCM key, which is entirely ephemeral and lives exclusively within the +client application's volatile RAM12. This derived AES key is then used to +decrypt highly sensitive, zero-trust application payloads natively in the +browser12.\ +Crucially, because the Auth-Yes servers never possess the authenticator's +internal PRF master secret, a catastrophic server-side data breach would yield +only mathematically useless ciphertext to the attacker3. + +### **Advanced Key Rotation Semantics** + +Cryptographic best practices, such as those defined in NIST SP 800-57, dictate +that encryption keys must not live indefinitely; the "cryptoperiod" of a key +must be aggressively restricted to limit the potential exposure of a compromised +key14. The Auth-Yes system achieves highly automatic, frictionless key rotation +by leveraging the advanced dual-evaluation capabilities of the PRF extension14.\ +During a rotation event, the system passes both an initial salt and a newly +generated secondary salt simultaneously during a single authentication request +via the eval.first and eval.second parameters14. The hardware authenticator +processes both values sequentially and returns two completely distinct 32-byte +secrets without requiring the user to execute multiple biometric +interactions14.\ +The Auth-Yes client application immediately utilizes the first derived secret to +generate the retiring Key Encryption Key (KEK) to unwrap existing ciphertext +blobs, and simultaneously utilizes the second secret to derive a new KEK, +instantly re-wrapping the Data Encryption Keys (DEKs) for future secure +storage14. This provides seamless, mathematically sound key rotation directly at +the network edge, fully abstracting complex envelope encryption mechanics away +from the end-user while maintaining the system's mandate for an indefinite, +perfect security posture1. + +## **Defeating Supply Chain and Dependency Compromise** + +A critical and pervasive vulnerability in modern software architecture is the +reliance on extensive front-end dependency graphs (e.g., React, Node.js +packages, Expo)3. A single malicious dependency update or an injected build-step +modification can trivially exfiltrate sensitive data the moment it enters the +Document Object Model (DOM) or client application memory3. Mobile and web +environments are highly susceptible to DOM injection, overlay attacks, +accessibility scraping, and clipboard listeners3. If a wallet or authentication +system relies on a single private key stored or derived within such an +environment, a supply-chain compromise allows complete, silent exfiltration of +credentials3.\ +Furthermore, in single-environment architectures, the application that +constructs a transaction is the same one that displays the transaction summary +and performs the signing3. A compromised UI can easily misrepresent amounts, +alter destination parameters, and construct valid signatures over malicious +transactions while displaying benign data to the user—an attack known as blind +signing3.\ +To engineer a system that is maximally secure against these advanced threats, +the Auth-Yes architecture integrates principles derived from 2-of-2 MuSig +Taproot aggregated key architectures used in high-security Bitcoin self-custody +wallets3. This architecture relies on the inherent domain-binding constraints of +the WebAuthn protocol3.\ +The system utilizes two entirely independent passkeys to authorize high-risk +actions: + +> 1. **Passkey A:** Registered strictly to the primary application's Relying +> Party ID (RP\_ID) and utilized within the standard client application (web, +> iOS, Android)3. +> 2. **Passkey B:** Registered exclusively to a completely separate, highly +> isolated co-signing domain with zero shared dependencies3. + +Because WebAuthn authenticators strictly enforce origin boundaries at the +hardware and operating system level, the primary application is +cryptographically and physically incapable of requesting an assertion from +Passkey B, and the co-signer cannot access Passkey A3. A phishing domain or a +compromised mobile app cannot trick the OS into unlocking a passkey bound to a +different domain3.\ +When a sensitive operation requires authorization, the primary application +derives its signing key (k1) via PRF evaluation using Passkey A and provides the +first partial signature3. The user is then directed to the isolated co-signing +domain, which independently renders and validates the transaction parameters3. +The user authenticates with Passkey B, deriving the second key (k2) via a +separate PRF evaluation3. The co-signer generates the second partial MuSig +signature, aggregates it with the first, and immediately zeroizes all sensitive +data in memory3. By forcing the cryptographic execution across two isolated +domain contexts, the architecture renders traditional supply-chain exfiltration, +clipboard theft, and DOM manipulation mathematically impotent3. + +## **Decentralized Recovery via Shamir's Secret Sharing (SSS)** + +The complete elimination of passwords and centralized server-side secrets +introduces a critical architectural challenge known as the "Lost YubiKey +Problem"5. If a user loses their physical hardware authenticator or their +biometric device is destroyed, access to the deterministic PRF output is +permanently severed5. Because the encrypted Master Key stored on the server is +cryptographically useless without the PRF output, the user's data would be +irrecoverable5.\ +While major technology vendors offer synchronized passkeys (e.g., Apple iCloud +Keychain, Google Password Manager) to solve device-loss scenarios through cloud +backups, this introduces severe platform dependency and vendor lock-in2. Relying +on a third-party ecosystem for recovery fundamentally violates the zero-trust +ethos required for a perfect, indefinite solution2. Alternatively, relying on +users to securely store and manage 12 or 24-word BIP-39 mnemonic seed phrases +places an immense operational burden on non-technical users, leading to high +rates of complete data loss2.\ +To architect a highly automatic, resilient, and fully uncompromisable recovery +mesh, the Auth-Yes system utilizes Shamir's Secret Sharing (SSS) algorithm5. SSS +is a cryptographic primitive that allows a master secret to be mathematically +divided into multiple unique fragments called shares using polynomial +interpolation5. The Auth-Yes architecture employs a strict threshold mechanism, +requiring a predefined subset of shares to accurately reconstruct the original +master key16. Crucially, possessing fewer than the threshold number of shares +reveals absolutely zero cryptographic information about the master secret5.\ +The optimal configuration for balancing extreme security with frictionless +availability is a 2-of-3 threshold sharing scheme16. The master encryption key +is split and distributed across independent storage mediums to eradicate any +single point of failure5. + +| Share Designation | Storage Location | Cryptographic Protection | Access Mechanism and Constraints | +| :------------------------- | :---------------------------------------------- | :----------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------- | +| **Device Share** | Client-side (Browser LocalStorage or IndexedDB) | Encrypted via AES-256-GCM using hardware PRF derivation16. | Bound exclusively to the local hardware authenticator or spending password. Never transmitted over the network16. | +| **Hot Share** (Auth Share) | Auth-Yes Zero-Trust Core (Backend Database) | Encrypted via AES-CBC using Argon2id derived keys (12 iterations, 64MiB memory, 128-bit salt)17. | Retrieved dynamically upon the successful issuance of a short-lived JSON Web Token (JWT) over authenticated channels16. | +| **Cold Share** | Isolated / Air-gapped Shield Storage | Multi-layered AES-CBC encryption requiring ephemeral, one-time Session IDs17. | Requires external secondary authentication (e.g., Out-of-Band OTP) and dedicated project encryption keys held strictly by the end-user17. | + +In the event of catastrophic device loss, the user accesses the Auth-Yes +recovery portal from a completely new device5. The client application fetches +the encrypted Hot Share from the backend using temporary session credentials5. +The user then supplies their decentralized Cold Share, or optionally inputs an +armored offline cryptographic voucher (such as a BIP-39 mnemonic seed phrase)1.\ +The client application evaluates the polynomial combining the Hot and Cold +shares exclusively within a highly isolated, sandboxed iframe16. This +mathematical reconstruction perfectly regenerates the master encryption key +without ever requiring the original hardware authenticator5.\ +Following a successful reconstruction, the system seamlessly executes an +automated key rotation sequence5. The user is prompted to register a new +WebAuthn passkey, generating a fresh PRF salt5. The system immediately issues an +entirely new suite of SSS shares, systematically re-encrypting the master key +and definitively invalidating the lost hardware, thereby securing the perimeter +against physical device compromise5. + +## **High Automation and Frictionless User Experience (UX)** + +An architecture cannot be deemed the "perfect solution indefinitely" if its +advanced security mechanisms introduce severe friction to the end-user or +operational overhead for the developer1. A hallmark of the Auth-Yes ecosystem is +the achievement of extreme usability through deep automation at both the network +edge and the presentation layer1. + +### **Zero-Redirect UX and Byte-1 SSR Hydration** + +Legacy identity federations utilizing OIDC and SAML protocols notoriously force +users through three to five HTTP redirect loops across disparate domains simply +to establish an authenticated session, resulting in degraded performance and +poor user experience1. The Auth-Yes architecture eliminates this entirely via a +Zero-Redirect User Experience (UX) model1.\ +By strategically configuring WebAuthn credentials and shared secure session +cookies to be scoped to the parent domain wildcard (e.g., \*.atyg.org), +credentials are automatically and seamlessly shared across all operational +subdomains1. This approach directly addresses the research directives analyzing +Parent-Domain Scoping versus W3C Related Origin Requests (ROR) for multi-domain +federation (Frontier 5), confirming that parent-domain scoping provides superior +latency characteristics without the overhead of cross-origin API calls1.\ +This zero-redirect capability operates in perfect tandem with "Byte-1" +Server-Side Rendering (SSR) Hydration1. When a user requests an application, the +Traefik ForwardAuth perimeter guard inspects the session and dynamically injects +specific Grant Headers directly into the HTTP request before routing it to the +application backend1. These headers (e.g., X-Forwarded-User-Id, +X-Forwarded-Scopes) utilize standard flattened vectors, allowing arrays of roles +(e.g., commander,operator) to be transmitted as simple comma-separated strings +for zero-overhead parsing1.\ +The application backend receives these headers on the very first byte of the +request1. Consequently, middleware SDKs—such as @auth-yes/sdk/hono—automatically +extract these flattened vectors and bind the identity and scopes directly to the +application context, exporting strict role-based guards for the rendering +engine1. The user interface is therefore capable of rendering perfectly +tailored, role-specific HTML immediately on "Byte 1," entirely eliminating +secondary API fetches, loading spinners, and layout shifts1. + +### **The Ghost Cockpit Protocol for Ambient Re-Authentication** + +A pervasive and highly disruptive anti-pattern in high-security environments is +the destructive termination of active user sessions1. In traditional systems, +when an access token expires, the network severs the connection, and the user is +abruptly redirected to a login page. This instantly destroys unsaved form data, +interrupts live WebSocket telemetry streams, and erases complex UI states, +severely impeding operational continuity1.\ +To push the UX "beyond anyone's imagination," the system formalizes and +implements the Ghost Cockpit Protocol, a specialized architectural standard +specifically designed to handle WebSocket and WebTransport session expirations +non-destructively1. This innovation addresses Frontier 4 of the research +dossier, formalizing the renewal protocol for live, continuous-connection +architectures1.\ +When the Valkey-backed session layer determines a token has reached its maximum +lifespan, it does not sever the TCP connection ungracefully1. Instead, the +server emits a localized AUTH\_REVOKED frame down the active WebSocket channel1. +The frontend SDK intercepts this discrete signal and immediately executes a +comprehensive non-destructive state freeze1. The entire UI state—including all +unsaved data and stream positions—is frozen securely in memory1.\ +Simultaneously, the application overlays an ambient glassmorphism dialog over +the interface, prompting the user to briefly tap their fingerprint scanner, +Windows Hello sensor, or hardware key1. Upon this minimal interaction, a +background WebAuthn biometric ceremony executes silently, derives the necessary +cryptographic proofs, and negotiates a fresh session cookie with the backend1. +The WebSocket seamlessly reconnects and flushes any queued telemetry, resulting +in absolutely zero lost data and minimal cognitive disruption to the operator1. +To ensure reliability during this process, the SDKs implement a timeoutMs abort +controller (defaulting to 5000ms via AbortSignal.timeout) to prevent hanging +requests from blocking the UI thread indefinitely1. + +## **Advanced Research Frontiers: Ephemeral Ed25519-Signed Headers** + +To guarantee the Auth-Yes system scales seamlessly into Internet of Things (IoT) +deployments, highly distributed edge computing, and complex microservice +topologies outside the primary Valkey mesh, the architecture incorporates +extensive research into Frontier 2: Ephemeral Ed25519-Signed Headers1. This +frontier is powered by the emerging IETF RFC 9421 specification for HTTP Message +Signatures4.\ +Traditional token architectures rely fundamentally on bearer tokens (such as +OAuth2 JWTs). If a bearer token is intercepted by an adversary, it can be +endlessly replayed to gain unauthorized access6. Furthermore, when an HTTP +request traverses multiple TLS-terminating proxies, load balancers, and +gateways, the original client IP address and connection metadata are often lost, +stripped, or obfuscated in the proxy bucket brigade, rendering network-level +trust impossible4. RFC 9421 solves this by providing application-layer, +end-to-end cryptographic integrity and authenticity that survives transformation +by intermediaries4. + +### **Canonical Signature Base and Component Coverage** + +Under the RFC 9421 protocol, the client dynamically signs specific components of +the HTTP request using a private key securely bound to its specific hardware +environment19. The protocol requires the signer to construct a strict canonical +signature base composed of selected components, format them deterministically +(separated by newline characters), and append an @signature-params metadata line +containing the ordered list of covered components, the algorithm used, and +precise timestamp parameters19. + +| Component Category | RFC 9421 Syntax | Description and Architectural Purpose | +| :------------------- | :----------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Derived Method** | @method | Binds the signature strictly to the specific HTTP verb (e.g., POST), mathematically preventing the signature from being intercepted and replayed as a destructive DELETE or GET request6. | +| **Derived Target** | @authority & @path | Ensures the signature is strictly bound to the target destination hostname and absolute path, neutralizing attempts to replay the signature against alternate, highly privileged API endpoints within the mesh6. | +| **Body Integrity** | content-digest | Protects the actual payload of the HTTP message by mathematically hashing the body (typically via SHA-256) and including the resulting hash directly in the canonical signature base6. | +| **Response Binding** | ;req flag | Applied specifically to response headers to cryptographically prove that the server's signed response was generated directly and exclusively in answer to a specific signed client request6. | + +To sign an outbound request, the Auth-Yes edge client extracts the values for +these chosen components, normalizes them according to the strict +canonicalization rules, and generates a digital signature using the highly +performant Edwards-curve Digital Signature Algorithm (Ed25519)4. Ed25519 is +heavily prioritized over traditional RSA-PSS or ECDSA-P256 algorithms due to its +superior computational speed, significantly smaller key sizes, and inherent +resistance to side-channel attacks, making it uniquely suited for +sub-millisecond validation on lightweight edge devices4. Implementations +utilizing highly optimized C libraries, such as wolfCrypt, allow these edge +devices to execute the wc\_HttpSig\_Sign and wc\_HttpSig\_Verify routines to +generate and verify these cryptographic proofs with negligible latency +overhead20. + +### **Replay Prevention and Signature-Input Mechanics** + +The resulting cryptographic output is transmitted via two dedicated HTTP +headers: Signature-Input and Signature6. The Signature-Input header explicitly +declares the covered components and the critical security parameters required +for validation6.\ +Crucially, to prevent adversarial exploitation, the Auth-Yes system strictly +mandates the inclusion of the created, expires, and nonce parameters within +every Signature-Input header6. The created and expires parameters define a +highly narrow, ephemeral validity window defined in Unix time, while the nonce +ensures absolute high-entropy uniqueness for every individual request6. If a +sophisticated attacker successfully intercepts the entire HTTP payload, the +signature simply cannot be replayed; any modification to the path, the body, or +the timestamp instantly breaks the Ed25519 signature validation at the Traefik +perimeter guard6. Systems utilizing this technology, such as Cloudflare Verified +Bots, use successful verification of these parameters as irrefutable proof of +identity, applying rules corresponding to that identity instantly21. + +### **Autonomous Key Distribution via Signature-Key** + +To achieve the mandate of high automation without relying on centralized, +bottlenecked key distribution centers, the Auth-Yes framework actively monitors +and integrates the IETF draft specifications for the Signature-Key HTTP +header23. This proposed standard allows the client to transmit the necessary +public key material (or a reference to it) directly within the HTTP request, +enabling the verifier to obtain the key dynamically without any prior +coordination23.\ +The Auth-Yes architecture specifically utilizes the Header Web Key (hwk) +distribution scheme for pseudonymous verification at the extreme edge23. Under +the hwk scheme, the client embeds its Ed25519 public key—encoded strictly in the +Octet Key Pair (OKP) format—directly alongside the signature within the +Signature-Key header23.\ +When the Traefik gateway receives the request, it extracts the key using the +correlating label defined in the keyid parameter, evaluates the Ed25519 proof +against the canonical signature base, and authorizes the transaction in +microseconds6. This autonomous mechanism allows ephemeral microservices, remote +IoT sensors, and high-velocity telemetry consumers to seamlessly authenticate +with the Zero-Trust Core without requiring complex, pre-shared secrets or +synchronous database lookups, perfectly aligning with the "highly automatic" +system requirement1. + +## **Immutable Cryptographic Audit Ledgers for Non-Repudiation** + +A critical component of a perfect, indefinite IAM system is the ability to +guarantee absolute mathematical non-repudiation for all administrative actions, +role assignments, and authorization state changes. Traditional relational audit +logs are fundamentally flawed; if an advanced persistent threat breaches the +core database, they can simply modify or delete the text-based logs to obfuscate +their lateral movement. To permanently eradicate this vector, Frontier 7 of the +Auth-Yes research dossier outlines the architectural transition to an Immutable +Cryptographic Audit Ledger1.\ +This paradigm shift relies heavily on the structural principles defined in RFC +6962, originally designed to secure Certificate Transparency (CT) logs7. The +Auth-Yes audit engine completely replaces standard relational logging tables +with highly structured, append-only Merkle Trees1.\ +In a Merkle Tree architecture, every newly generated audit event within the +Auth-Yes ecosystem (such as a role assignment, a passkey registration, or an +edge boundary breach attempt) is cryptographically hashed7. This individual hash +forms a leaf node at the base of the tree7. These leaf nodes are then +systematically paired and concatenated, and their combined hash forms the parent +node7. This mathematical process recursively bubbles up to the apex of the +structure, resulting in a single, cryptographic Root Hash that mathematically +represents the entire, unbroken history of the IAM ecosystem7.\ +Because every single event is mathematically bound to the events that preceded +it, altering or deleting a historical log entry instantly and irreparably +invalidates the Root Hash7. To prove that a specific administrative action +definitively occurred, the system generates an inclusion proof—a localized +branch of hashes that allows any independent verifier to quickly compute the +path to the root and verify its integrity7. The deep integration of Merkle Tree +hash chains ensures absolute, mathematically verifiable non-repudiation, +transforming the Auth-Yes audit trail from a highly vulnerable text record into +a resilient, tamper-evident cryptographic artifact1. + +## **Extreme System Optimization and Future Horizons** + +The Auth-Yes mandate dictates that these complex cryptographic evaluations must +execute without ever bottlenecking application throughput. To ensure the system +operates at the highest possible velocity, two major research frontiers focus +entirely on extreme optimization: + +> 1. **High-Throughput Rate Limiting (Frontier 6):** To maintain absolute +> resilience during highly volumetric Distributed Denial of Service (DDoS) +> attacks, the system actively benchmarks advanced sliding-window log +> algorithms within the Valkey mesh1. By executing rapid rate-limiting checks +> at the microsecond level directly in the cache memory, the infrastructure +> is engineered to absorb upwards of 100,000 requests per second1. This +> allows the perimeter guard to instantly identify and throttle malicious IPs +> without ever degrading the latency or experience for legitimate users1. +> 2. **Universal Language SDKs (Frontier 10):** The architecture is actively +> standardizing Universal Language SDKs across the development stack1. By +> unifying the exact cryptographic core architecture across Go, Rust, Python, +> and Deno environments, the Auth-Yes ecosystem ensures that any newly +> deployed microservice, regardless of its underlying runtime language, +> automatically inherits the exact same defense-in-depth security posture, +> the sub-30µs BCAST invalidation speed, and the non-destructive Ghost +> Cockpit capabilities1. + +## **Conclusion** + +The Auth-Yes architecture represents a definitive, generational evolution in +Identity and Access Management. By systematically abandoning the fragile +methodologies of legacy federations and replacing them with a strict, +defense-in-depth "Two-Locks" model, the system fundamentally hardens both the +network perimeter and the highly vulnerable application core.\ +The deep integration of WebAuthn PRF extensions allows the system to operate as +a completely passwordless, mathematically secure cryptographic authority. By +leveraging 2-of-2 MuSig Taproot concepts and decentralized Shamir's Secret +Sharing matrices, the architecture ensures robust, automated account recovery +and supply-chain defense without ever exposing centralized symmetric secrets to +attackers. Concurrently, the Ghost Cockpit Protocol and Zero-Redirect Hydration +mechanisms guarantee that this immense cryptographic weight remains entirely +invisible to the end-user, providing a seamless, automated, and frictionless +experience that fulfills the requirement for extreme ease of use.\ +Furthermore, by actively expanding into advanced frontiers—such as Ephemeral +Ed25519 HTTP Message Signatures for edge computing and Merkle Tree structures +for non-repudiation—the architecture anticipates and neutralizes emerging threat +vectors before they materialize. The comprehensive, multidisciplinary fusion of +sub-millisecond Valkey caching, hardware-bound biometric authentication, and +immutable cryptographic ledgers fulfills the project mandate precisely: Auth-Yes +is positioned not merely as a modern IAM solution, but as a robust, highly +automated, and maximally secure framework explicitly engineered to serve as the +definitive standard indefinitely. + +#### **Works cited** + +> 1. [https://drive.google.com/open?id=1DBe7ZKB3Fp\_XsdGbdlqKhCWQPSnpbQViuRZMqYyHJYk](https://drive.google.com/open?id=1DBe7ZKB3Fp_XsdGbdlqKhCWQPSnpbQViuRZMqYyHJYk) +> 2. Passkeys for Bitcoin Wallets: How WebAuthn Replaces Seed Phrases | Spark, +> [https://www.spark.money/research/bitcoin-passkey-wallet-authentication](https://www.spark.money/research/bitcoin-passkey-wallet-authentication) +> 3. A Passkey-Derived 2-of-2 Taproot Wallet Architecture Eliminating Seed +> Phrases, Mitigating Supply-Chain Risk, and Enforcing Verified, Non-Blind +> Signing, +> [https://emino.app/posts/a-passkey-derived-2-of-2-taproot-wallet-architecture-elimina/](https://emino.app/posts/a-passkey-derived-2-of-2-taproot-wallet-architecture-elimina/) +> 4. RFC 9421 \- HTTP Message Signatures \- IETF Datatracker, +> [https://datatracker.ietf.org/doc/rfc9421/](https://datatracker.ietf.org/doc/rfc9421/) +> 5. Solving the Lost YubiKey problem with WebAuthn PRF & Shamir's Secret +> Sharing, +> [https://ludvikprokopec.cz/solving-the-lost-yubikey-problem-with-webauthn-prf-and-shamir-secret-sharing/](https://ludvikprokopec.cz/solving-the-lost-yubikey-problem-with-webauthn-prf-and-shamir-secret-sharing/) +> 6. Signature-Input \- Expert Guide to HTTP headers, +> [https://http.dev/signature-input](https://http.dev/signature-input) +> 7. Tamper-Evident Status Derivation from Cryptographic Execution Proof — +> Eliminating Mutable Status Fields \- Technical Disclosure Commons, +> [https://www.tdcommons.org/cgi/viewcontent.cgi?article=10638\&context=dpubs\_series](https://www.tdcommons.org/cgi/viewcontent.cgi?article=10638&context=dpubs_series) +> 8. valkey package \- github.com/rueian/valkey-go \- Go Packages, +> [https://pkg.go.dev/github.com/rueian/valkey-go](https://pkg.go.dev/github.com/rueian/valkey-go) +> 9. rueidis package \- github.com/redis/rueidis \- Go Packages, +> [https://pkg.go.dev/github.com/redis/rueidis](https://pkg.go.dev/github.com/redis/rueidis) +> 10. artttj/nemo: \[BETA\] Nemo is a browser extension that keeps ... \- +> GitHub, [https://github.com/artttj/nemo](https://github.com/artttj/nemo) +> 11. Web Authentication extensions \- Web APIs \- MDN Web Docs \- Mozilla, +> [https://developer.mozilla.org/en-US/docs/Web/API/Web\_Authentication\_API/WebAuthn\_extensions](https://developer.mozilla.org/en-US/docs/Web/API/Web_Authentication_API/WebAuthn_extensions) +> 12. Experimental WebAuthn PRF Extension Demonstration \- Levi's Blog, +> [https://levischuck.com/blog/2023-02-prf-webauthn](https://levischuck.com/blog/2023-02-prf-webauthn) +> 13. oblique-security/webauthn-prf-demo: Passkeys for end-to-end encryption \- +> GitHub, +> [https://github.com/oblique-security/webauthn-prf-demo](https://github.com/oblique-security/webauthn-prf-demo) +> 14. A Developer's Guide to Deriving Keys with WebAuthn PRF and YubiKeys, +> [https://developers.yubico.com/WebAuthn/Concepts/PRF\_Extension/Developers\_Guide\_to\_PRF.html](https://developers.yubico.com/WebAuthn/Concepts/PRF_Extension/Developers_Guide_to_PRF.html) +> 15. A Tour of WebAuthn \- ImperialViolet, +> [https://www.imperialviolet.org/tourofwebauthn/tourofwebauthn.html](https://www.imperialviolet.org/tourofwebauthn/tourofwebauthn.html) +> 16. How Wallet as a Service Works \- UTXOS, +> [https://docs.utxos.dev/wallet/how-it-works](https://docs.utxos.dev/wallet/how-it-works) +> 17. Recovery methods – OpenSigner, +> [https://www.opensigner.dev/security/recovery-methods](https://www.opensigner.dev/security/recovery-methods) +> 18. HTTP Request Signatures \- SANS Internet Storm Center, +> [https://isc.sans.edu/diary/32266](https://isc.sans.edu/diary/32266) +> 19. Understanding HTTP Message Signatures \- Blog Notes, +> [https://blog.vitalvas.com/post/2025/12/12/understanding-http-message-signatures/](https://blog.vitalvas.com/post/2025/12/12/understanding-http-message-signatures/) +> 20. wolfssl-examples/http-message-signatures/README.md at master \- GitHub, +> [https://github.com/wolfSSL/wolfssl-examples/blob/master/http-message-signatures/README.md](https://github.com/wolfSSL/wolfssl-examples/blob/master/http-message-signatures/README.md) +> 21. Message Signatures are now part of our Verified Bots Program, simplifying +> bot authentication | Cloudflare Blog, +> [https://blog.cloudflare.com/verified-bots-with-cryptography/](https://blog.cloudflare.com/verified-bots-with-cryptography/) +> 22. Native HTTP Message Signatures in curl, Powered by wolfSSL \- Part 3, +> [https://www.wolfssl.com/native-http-message-signatures-in-curl-powered-by-wolfssl-part-3/](https://www.wolfssl.com/native-http-message-signatures-in-curl-powered-by-wolfssl-part-3/) +> 23. HTTP Signature-Key Header \- IETF, +> [https://www.ietf.org/archive/id/draft-hardt-httpbis-signature-key-01.html](https://www.ietf.org/archive/id/draft-hardt-httpbis-signature-key-01.html) +> 24. Kathon/research/02-ledger-browser-agent-audit | Anticloud Wiki, +> [https://anticloud.fandom.com/wiki/Kathon/research/02-ledger-browser-agent-audit](https://anticloud.fandom.com/wiki/Kathon/research/02-ledger-browser-agent-audit) diff --git a/docs/PHASED_IMPLEMENTATION_PLAN.md b/docs/PHASED_IMPLEMENTATION_PLAN.md new file mode 100644 index 0000000..5eeb9c7 --- /dev/null +++ b/docs/PHASED_IMPLEMENTATION_PLAN.md @@ -0,0 +1,146 @@ +# 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: ` + - `X-Forwarded-User-Name: ` + - `X-Forwarded-Scopes: ` + - `X-Forwarded-App-Id: ` +- **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::`), 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. diff --git a/tasks/JULES_PROMPTS.md b/tasks/JULES_PROMPTS.md new file mode 100644 index 0000000..0389d5f --- /dev/null +++ b/tasks/JULES_PROMPTS.md @@ -0,0 +1,151 @@ +# Orchestrator Task Prompts for Jules (System Analyst & Implementation) + +This document contains pre-configured orchestrator prompts strictly following +the +[`tasks/META_PROMPT.md`](file:///home/tylerg/p/data/auth-yes/tasks/META_PROMPT.md) +and +[`tasks/GUIDELINES.md`](file:///home/tylerg/p/data/auth-yes/tasks/GUIDELINES.md) +standards. Use these prompts to instruct Jules to plan each task in `tasks/new/` +and subsequently execute them. + +--- + +## Phase 1 Prompts + +### Prompt 1.1: Ingress Grant Vector Injection (`/api/forward-auth`) + +```text +**Role:** Act as a System Analyst and Solutions Architect. Do not execute code or modify the codebase during this session. Your sole deliverable is to generate a task file in tasks/new/. + +**The Objective:** Implement Ingress Grant Vector Injection in the `/api/forward-auth` endpoint so that Traefik ForwardAuth injects flattened user grant headers (`X-Forwarded-User-Id`, `X-Forwarded-User-Name`, `X-Forwarded-Scopes`, `X-Forwarded-App-Id`) into downstream application requests for Byte-1 SSR UI hydration. + +**Suggestions & Initial Thoughts:** +*Here is our starting hypothesis. Treat these as ideas to evaluate, not rigid requirements:* +* In `server/main.ts`, extract the `X-Forwarded-Host` header during `GET /api/forward-auth`. +* Match the host against registered applications in PostgreSQL/Valkey to resolve `app_id`. +* Evaluate the user's active RBAC grants in Valkey/PostgreSQL. If valid, return HTTP 200 with `X-Forwarded-User-Id`, `X-Forwarded-User-Name`, `X-Forwarded-Scopes: role1,role2`, and `X-Forwarded-App-Id`. +* If the user has no grant for the target app, enforce Default-Deny by returning HTTP 403 Forbidden. + +**Your Task:** +1. Research the codebase and analyze this objective against our current architecture in `server/main.ts`, `server/db.ts`, and `server/valkey.ts`. +2. Critically evaluate our suggestions: Do they make technical sense, or is there a cleaner, more native, or more modular approach? +3. Map out the `Target Files`, prerequisites/dependencies, and explicitly identify potential architectural risks, regressions, or friction. +4. Draft the task file in `tasks/new/` strictly adhering to the naming conventions, header metadata, and mandatory structure defined in `tasks/GUIDELINES.md`. +``` + +--- + +### Prompt 1.2: SDK Real-Time Invalidation Event Bus (`@auth-yes/sdk`) + +```text +**Role:** Act as a System Analyst and Solutions Architect. Do not execute code or modify the codebase during this session. Your sole deliverable is to generate a task file in tasks/new/. + +**The Objective:** Extend `@auth-yes/sdk` with a real-time event emitter listener for Valkey 8 RESP3 push invalidation events so downstream microservices (e.g. `ed-droid`) can terminate live WebSocket telemetry connections immediately upon session revocation. + +**Suggestions & Initial Thoughts:** +*Here is our starting hypothesis. Treat these as ideas to evaluate, not rigid requirements:* +* In `sdk/mod.ts`, integrate a lightweight EventEmitter or custom callback map (`authSdk.on("invalidate", (token) => ...)`). +* In `initValkeyClient()`, when the `push` event receives an `"invalidate"` message from Valkey 8 BCAST tracking, iterate over the invalidated keys and trigger all registered callback handlers. +* Ensure zero memory leaks by providing an `authSdk.off("invalidate", handler)` cleanup method. + +**Your Task:** +1. Research the codebase and analyze this objective against our current architecture in `sdk/mod.ts` and `sdk/mod.test.ts`. +2. Critically evaluate our suggestions: Do they make technical sense, or is there a cleaner, more native, or more modular approach? +3. Map out the `Target Files`, prerequisites/dependencies, and explicitly identify potential architectural risks, regressions, or friction. +4. Draft the task file in `tasks/new/` strictly adhering to the naming conventions, header metadata, and mandatory structure defined in `tasks/GUIDELINES.md`. +``` + +--- + +## Phase 2 Prompts + +### Prompt 2.1: RFC 9421 HTTP Message Signatures & Autonomous `Signature-Key` + +```text +**Role:** Act as a System Analyst and Solutions Architect. Do not execute code or modify the codebase during this session. Your sole deliverable is to generate a task file in tasks/new/. + +**The Objective:** Implement RFC 9421 HTTP Message Signatures verification for edge nodes and headless daemons, utilizing `Signature-Input` and `Signature-Key` with Header Web Key (`hwk`) in Octet Key Pair (`OKP`) format, validated against an $O(1)$ Valkey authorized fingerprint set in under 5 microseconds. + +**Suggestions & Initial Thoughts:** +*Here is our starting hypothesis. Treat these as ideas to evaluate, not rigid requirements:* +* Create a pure Deno WebCrypto/Ed25519 validator module in `server/http_signatures.ts`. +* Parse RFC 9421 canonical components (`@method`, `@authority`, `@path`, `content-digest`, `created`, `expires`, `nonce`). +* Extract the inline Ed25519 public key from `Signature-Key: hwk="..."` and verify the SHA-256 fingerprint exists in Valkey's authorized set (`auth:hwk:fingerprints`). +* Verify the Ed25519 digital signature over the canonical signature base with strict $\pm 30$s timestamp drift tolerance. + +**Your Task:** +1. Research the codebase and analyze this objective against our current architecture in `server/` and `sdk/`. +2. Critically evaluate our suggestions: Do they make technical sense, or is there a cleaner, more native, or more modular approach? +3. Map out the `Target Files`, prerequisites/dependencies, and explicitly identify potential architectural risks, regressions, or friction. +4. Draft the task file in `tasks/new/` strictly adhering to the naming conventions, header metadata, and mandatory structure defined in `tasks/GUIDELINES.md`. +``` + +--- + +### Prompt 2.2: The Ghost Cockpit Protocol Specification & Re-Auth Choreography + +```text +**Role:** Act as a System Analyst and Solutions Architect. Do not execute code or modify the codebase during this session. Your sole deliverable is to generate a task file in tasks/new/. + +**The 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. + +**Suggestions & Initial Thoughts:** +*Here is our starting hypothesis. Treat these as ideas to evaluate, not rigid requirements:* +* Document the protocol choreography in `docs/GHOST_COCKPIT_SPEC.md`. +* Create a reusable WebSocket session guard helper in `sdk/hono.ts` that listens to `authSdk.on("invalidate")` and emits the `{ "type": "AUTH_REVOKED", "reason": "SESSION_EXPIRED" }` control frame before closing the socket. +* Provide a client-side TypeScript snippet demonstrating state-freeze in memory and zero-redirect background WebAuthn re-authentication. + +**Your Task:** +1. Research the codebase and analyze this objective against our current architecture in `sdk/hono.ts` and `docs/`. +2. Critically evaluate our suggestions: Do they make technical sense, or is there a cleaner, more native, or more modular approach? +3. Map out the `Target Files`, prerequisites/dependencies, and explicitly identify potential architectural risks, regressions, or friction. +4. Draft the task file in `tasks/new/` strictly adhering to the naming conventions, header metadata, and mandatory structure defined in `tasks/GUIDELINES.md`. +``` + +--- + +## Phase 3 Prompts + +### Prompt 3.1: WebAuthn PRF Extension & Progressive Fallback + +```text +**Role:** Act as a System Analyst and Solutions Architect. Do not execute code or modify the codebase during this session. Your sole deliverable is to generate a task file in tasks/new/. + +**The Objective:** Implement WebAuthn PRF (Pseudo-Random Function) extension support in Auth-Yes registration and login flows, including progressive feature detection (`getClientExtensionResults()?.prf?.enabled`) and dual-salt evaluation (`eval.first`, `eval.second`) for atomic envelope re-encryption. + +**Suggestions & Initial Thoughts:** +*Here is our starting hypothesis. Treat these as ideas to evaluate, not rigid requirements:* +* In `server/main.ts` (SimpleWebAuthn challenge generation), request the `prf: {}` extension during passkey registration. +* In `ui/views/register.tsx` and `ui/views/login.tsx`, evaluate the PRF salt during `navigator.credentials.get()`. +* If PRF is supported by the authenticator, derive the 256-bit AES-GCM Key Encryption Key (KEK) using HKDF over the 32-byte PRF output. +* If `getClientExtensionResults()?.prf?.enabled` is false, gracefully continue standard signature-only authentication without blocking login. + +**Your Task:** +1. Research the codebase and analyze this objective against our current architecture in `server/` and `ui/`. +2. Critically evaluate our suggestions: Do they make technical sense, or is there a cleaner, more native, or more modular approach? +3. Map out the `Target Files`, prerequisites/dependencies, and explicitly identify potential architectural risks, regressions, or friction. +4. Draft the task file in `tasks/new/` strictly adhering to the naming conventions, header metadata, and mandatory structure defined in `tasks/GUIDELINES.md`. +``` + +--- + +### Prompt 3.2: Native SIMD Argon2id Derivation in `spire_ffi` Rust Crate + +```text +**Role:** Act as a System Analyst and Solutions Architect. Do not execute code or modify the codebase during this session. Your sole deliverable is to generate a task file in tasks/new/. + +**The Objective:** Implement high-throughput native Argon2id derivation (12 iterations, 64 MiB memory, 128-bit salt, 256-bit output key) in the `spire_ffi` Rust crate to accelerate server-side Hot Share encryption and zero-knowledge voucher hashing. + +**Suggestions & Initial Thoughts:** +*Here is our starting hypothesis. Treat these as ideas to evaluate, not rigid requirements:* +* Add the `argon2` Rust crate with SIMD acceleration (`argon2 = { version = "0.5", features = ["std"] }`) to `spire_ffi/Cargo.toml`. +* Export a C-compatible FFI function `argon2id_derive(password, salt, iterations, memory_kb, out_buf)`. +* Expose `deriveArgon2idKey()` in `server/spire_ffi.ts` using Deno FFI (`Deno.dlopen`). +* Include comprehensive unit tests and fallback behavior in `server/spire_ffi.test.ts`. + +**Your Task:** +1. Research the codebase and analyze this objective against our current architecture in `spire_ffi/` and `server/spire_ffi.ts`. +2. Critically evaluate our suggestions: Do they make technical sense, or is there a cleaner, more native, or more modular approach? +3. Map out the `Target Files`, prerequisites/dependencies, and explicitly identify potential architectural risks, regressions, or friction. +4. Draft the task file in `tasks/new/` strictly adhering to the naming conventions, header metadata, and mandatory structure defined in `tasks/GUIDELINES.md`. +```