tylerg/auth-yes
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
auth-yes/tasks/complete/2026-0824.02.jul.feat.http-sigs.rfc9421-verification-0436.md
google-labs-jules[bot] 182c789e05 feat(auth): implement RFC 9421 HTTP Message Signatures 
- Added native Deno WebCrypto Ed25519 signature verification middleware for headless edge workloads.
- Integrated dual authentication path to `/api/forward-auth` processing signatures and session cookies.
- Added dual storage Admin Management routes (`/api/admin/hwk`) securely inserting directly to PostgreSQL and pushing to $O(1)$ Valkey verification set.
- Completed all quality gates checks and hermetic mocked tests successfully.

Co-authored-by: mrteye <1945243+mrteye@users.noreply.github.com>
2026-08-24 05:36:01 +00:00

4.7 KiB
Raw Blame History

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 <sha256_fingerprint>. 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.