# TASK METADATA

- **Target Files:**
  - `server/main.ts`
  - `server/main.test.ts` (new)
  - `server/db.ts`
  - `server/db.test.ts` (new)
  - `server/spire_ffi.test.ts` (new)
  - `server/valkey.ts`
  - `server/valkey.test.ts` (new)
  - `sdk/mod.ts`
  - `sdk/hono.ts` (new)
  - `sdk/mod.test.ts`
  - `sdk/hono.test.ts` (new)
- **Core Objective:** Design a comprehensive multi-tier automated test harness
  and verification suite for Auth-Yes, validating Tier 1 & 2 (Traefik
  ForwardAuth), Tier 3 (ConnectRPC with SPIFFE/mTLS workload attestation),
  decoupled Default-Deny RBAC authorization, and modular `@auth-yes/sdk` client
  middleware using native Deno mocking.
- **Dependencies:** Deno standard library `@std/testing/mock`,
  `@std/testing/bdd`, and `hono`.
- **Additional Important Notes:** Do NOT use Testcontainers or Docker
  dependencies. Mock external services (Postgres, Valkey, SPIFFE API) using
  Deno's native mocking capabilities to ensure hermetic, fast, and deterministic
  test execution. Refactor `server/main.ts` top-level side effects (server
  listener and network probes) behind `if (import.meta.main)` and export `app`
  for in-memory `app.request()` testing.

---

## Architectural Considerations & Risks

### Risks

1. **Mocking Accuracy:** Using mocks for PostgreSQL (`db.ts`) and Valkey
   (`valkey.ts`) risks diverging from actual production behavior if the database
   schema or RESP3 client tracking intricacies change. We must ensure the mocked
   responses accurately reflect both success cases and edge cases (e.g.,
   specific Valkey error codes, Postgres constraint violations).
2. **Top-Level Side Effects during Test Imports:** Currently, importing
   `server/main.ts`, `server/db.ts`, or `server/valkey.ts` executes top-level
   code (e.g., `Deno.serve(...)`, `MetadataService.initialize()`,
   `pingValkey()`, and strict env validation). These must be cleanly
   decoupled/guarded so test runners can import modules in isolation without
   triggering network listeners or unhandled runtime rejections.
3. **SPIFFE Workload Mismatches:** Relying on explicit Deno stubs for
   `extractSpiffeIdFromCert` and `fetchSpiffeIdentity` must be robust enough to
   simulate corrupted X.509 certificates or unrecognized SPIFFE IDs
   deterministically. If stubs aren't well isolated between tests, state bleed
   could cause flaky test runs.
4. **SDK Modularity:** Integrating Hono middleware directly into `sdk/mod.ts`
   risks coupling the core SDK to a specific web framework. To preserve Rule 1
   of `AGENTS.md` (zero-dependency SDK), Hono helpers must be housed in a
   dedicated modular submodule (`sdk/hono.ts`) while keeping `sdk/mod.ts`
   completely framework-agnostic.

### Alternatives

- **Alternative 1: E2E Containers (Rejected):** Spinning up live Postgres,
  Valkey, and SPIRE agent containers using Docker/Testcontainers would provide
  higher fidelity but drastically slow down the test suite and introduce
  environment dependency friction. As requested, we are prioritizing hermetic
  Deno native mocking.
- **Alternative 2: In-Memory Hono App & Direct RPC Testing (Selected):**
  Leverage Hono's `.request()` helper on the exported `app` instance to test API
  endpoints (Tier 1 & 2) in memory while stubbing the underlying `sql` and
  `valkey` exports. For Tier 3 (ConnectRPC), test both direct service handler
  invocations and RPC routes in memory.

---

## Proposed Implementation

### Phase 1: Test Environment & Server Module Decoupling

1. **Entrypoint Refactoring (`server/main.ts`):**
   - Export `app` from `server/main.ts`.
   - Wrap `Deno.serve(...)`, `pingValkey()`, and `MetadataService.initialize()`
     inside `if (import.meta.main) { ... }` so importing `main.ts` in tests does
     not spin up a live server or execute remote network calls.
   - Provide safe fallback defaults for `RP_ID` and `ORIGIN` in test mode or
     allow environment overrides before import.
2. **Database & Valkey Isolation:**
   - Create reusable mock helpers using `@std/testing/mock` (`stub` and `spy`).
   - Stub the `sql` export in `server/db.ts` to return controlled records
     representing mock users, apps, and grants.
   - Stub `valkey.get` and `valkey.setex` in `server/valkey.ts` to simulate
     session cache hits, misses, and invalidations.
3. **SPIFFE/mTLS Mocking (Tier 3):**
   - Stub `extractSpiffeIdFromCert` in `server/spire_ffi.ts`.
   - Provide test cases for valid SPIFFE URIs (e.g.,
     `spiffe://system.local/ed-droid-backend`), invalid URIs, missing
     extensions, and unparseable certs.

### Phase 2: Tier 1 & 2 (Edge ForwardAuth) Verification

1. **Target:** `GET /api/forward-auth` via `app.request()` in
   `server/main.test.ts`.
2. **Test Cases:**
   - Valid session cookie: Assert HTTP `200 OK` and presence of
     `X-Forwarded-User` and `X-Forwarded-User-Id` headers.
   - Missing session cookie: Assert HTTP `401 Unauthorized`.
   - Invalid/Expired session (simulated via Valkey cache miss): Assert HTTP
     `401 Unauthorized`.
   - Suspended account (simulated via mocked `sql` returning
     `account_status: 'suspended'`): Assert HTTP `403 Forbidden`.

### Phase 3: Tier 3 (Zero-Trust Mesh & RBAC) Verification

1. **Target:** `AuthService.validateSession` ConnectRPC endpoint & handler.
2. **Test Cases:**
   - **Default-Deny:** Unassigned user attempting to access a valid SPIFFE ID.
     Assert `valid: false` and authorization rejection.
   - **Valid RBAC Grant:** Authenticated user with explicit grant for the
     calling app's SPIFFE ID. Assert `valid: true`, correct UUID, and correct
     scope (e.g., `viewer`, `admin`).
   - **SPIFFE Attestation Failure:** Missing or invalid `x-peer-cert` header.
     Assert validation failure.

### Phase 4: Audit Ledger Verification

1. **Target:** `auditLog` function calls in `server/audit.ts`.
2. **Test Cases:**
   - Spy on `auditLog` in `server/audit.ts`.
   - Verify that successful logins (`login_success`), login failures
     (`login_failed`), and explicit access denials (`session_validation_failed`)
     generate the correct event payload structures and are dispatched to the
     mocked DB.

### Phase 5: Modular SDK Ergonomics & Hono Middleware

1. **Target:** `sdk/hono.ts` (new) and `sdk/hono.test.ts` (new).
2. **Implementation Steps:**
   - Create `sdk/hono.ts` exporting `createAuthMiddleware(sdk: AuthSdk)` so the
     core `sdk/mod.ts` remains framework-agnostic.
   - The middleware extracts the `session_id` cookie or `Authorization` header,
     calls `sdk.requireAuth()`, and injects the resulting `userId` into the Hono
     context (`c.set('userId', userId)`).
   - If `requireAuth` throws, the middleware catches it and returns HTTP
     `401 Unauthorized`.
3. **Verification:**
   - In `sdk/hono.test.ts`, create a test Hono app, attach the middleware, and
     verify that authorized requests pass and unauthorized requests return
     `401 Unauthorized`.