182c789e05
- 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>
99 lines
4.7 KiB
Markdown
99 lines
4.7 KiB
Markdown
# 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`.
|