From a0989a3bed2093787c7bfdc8afc3912cae640cf3 Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Mon, 24 Aug 2026 04:41:05 +0000 Subject: [PATCH] Add task for RFC 9421 HTTP Message Signatures verification Adds a detailed markdown task file in `tasks/new/` following the Kanban guidelines to outline the architectural implementation plan for RFC 9421 HTTP Message Signatures verification at edge nodes using native Deno WebCrypto. Co-authored-by: mrteye <1945243+mrteye@users.noreply.github.com> --- ...eat.http-sigs.rfc9421-verification-0436.md | 98 +++++++++++++++++++ 1 file changed, 98 insertions(+) create mode 100644 tasks/new/2026-0824.02.jul.feat.http-sigs.rfc9421-verification-0436.md diff --git a/tasks/new/2026-0824.02.jul.feat.http-sigs.rfc9421-verification-0436.md b/tasks/new/2026-0824.02.jul.feat.http-sigs.rfc9421-verification-0436.md new file mode 100644 index 0000000..8302a72 --- /dev/null +++ b/tasks/new/2026-0824.02.jul.feat.http-sigs.rfc9421-verification-0436.md @@ -0,0 +1,98 @@ +# TASK METADATA + +- **Target Files:** + - `server/http_signatures.ts` (New module) + - `server/main.ts` (Update `/api/forward-auth` and add admin routes) + - `server/valkey.ts` (Ensure SISMEMBER helper exists or is exposed) +- **Core Objective:** Implement RFC 9421 HTTP Message Signatures verification + middleware using native Deno Ed25519 for headless daemons and edge nodes. +- **Dependencies:** Deno 2.x native `crypto.subtle` (Ed25519 support), Valkey + access for fingerprint sets. +- **Additional Important Notes:** Must support dual-auth in `/api/forward-auth` + (Session OR Signature). Verification must complete in <5 microseconds (mostly + $O(1)$ Valkey lookup). The `Signature-Key` uses the `hwk` parameter via + draft-hardt-httpbis-signature-key containing an OKP JWK inline. + +--- + +## Architectural Considerations & Risks + +### Risks + +1. **Replay Attacks:** If the `nonce` and strict $\pm 30$s timestamp drift + (`created`/`expires`) are not strictly validated, attackers could replay + intercepted signed requests. +2. **Valkey Exhaustion/Availability:** Relying on Valkey for sub-5 microsecond + fingerprint checks is fast but introduces a hard dependency on Valkey + availability for edge authentication. If Valkey is down, headless clients + cannot authenticate. +3. **Parsing Overhead:** Parsing complex `Signature-Input` and canonicalizing + HTTP components according to RFC 9421 can be CPU intensive. The + implementation must be heavily optimized to avoid DoS vectors. +4. **Header Size Limits:** Including raw JWKs in headers (`hwk`) increases + header size, potentially hitting proxy limits if not managed carefully. + +### Alternatives Evaluated + +1. **mTLS (Mutual TLS):** We already use mTLS/SPIFFE internally (via + `spire_ffi.ts`). However, for edge nodes/IoT devices traversing multiple + proxies or load balancers, HTTP Message Signatures provide application-layer + end-to-end integrity that survives TLS termination, making it the superior + choice for this specific headless use case. +2. **External NPM Packages:** Libraries like `@peertube/http-signature` exist, + but adhering to the zero-dependency SDK/pure Deno backend policy dictates a + native WebCrypto approach, which is cleaner and guarantees compatibility with + Deno 2.x. + +## Proposed Implementation + +### Phase 1: Core Cryptography and Parsing (`server/http_signatures.ts`) + +1. Create `server/http_signatures.ts`. +2. Implement parsing logic for RFC 9421 `Signature-Input` and `Signature` + headers. +3. Extract the inline `hwk` (Header Web Key) JSON Web Key (JWK) parameter. + Ensure it is of type `kty="OKP"` and `crv="Ed25519"`. +4. Generate the SHA-256 fingerprint of the `hwk` object or public key bytes. +5. Build the Canonical Signature Base string using the requested components + (`@method`, `@authority`, `@path`, `content-digest`, `created`, `expires`, + `nonce`). +6. Validate timestamps (`created`, `expires`) with a strict $\pm 30$ seconds + drift tolerance against the server's current time. +7. Use Deno's native `crypto.subtle.importKey` and + `crypto.subtle.verify({ name: "Ed25519" })` to validate the digital + signature. + +### Phase 2: Valkey Integration & Middleware Export (`server/http_signatures.ts`) + +1. Integrate the $O(1)$ Valkey authorized fingerprint set check. +2. Query `SISMEMBER auth:hwk:fingerprints `. If the result + is `0`, deny access immediately. +3. Wrap this logic into an exportable Hono middleware or helper function + (`verifyHttpSignature`). + +### Phase 3: Route Integration (`server/main.ts`) + +1. Modify `/api/forward-auth`: + - Inspect headers for either a valid Session Cookie OR + `Signature`/`Signature-Input` headers. + - If signature headers exist, invoke `verifyHttpSignature`. + - If valid, treat the request as authenticated (resolve the app context + similarly to the session-based flow). Ensure scopes/roles can be inferred, + possibly by mapping the fingerprint to a specific service account or app + grant in the DB if necessary (or relying on a default edge role). +2. Implement Admin Management Routes: + - `POST /api/admin/hwk`: Accept a public key / JWK, generate its fingerprint, + and add it to `auth:hwk:fingerprints` using Valkey `SADD`. + - `DELETE /api/admin/hwk/:fingerprint`: Remove a fingerprint using Valkey + `SREM`. + - Protect these routes using the existing global admin middleware. + +### Phase 4: Testing & Quality Gates + +1. Write hermetic tests simulating a headless client generating an RFC 9421 + signature and submitting it. +2. Mock Valkey responses to test authorized vs unauthorized fingerprint checks. +3. Validate Deno native Ed25519 verification against a known good signature + payload. +4. Run `deno fmt`, `deno task lint`, `deno task check`, and `deno task test`.