docs(agents): document dual-remote mirroring for SDK distribution

Draft comprehensive test harness architecture plan

tasks/new/2026-0821.01.jul.audit.layered-security.verify-3tier-auth-and-rbac-2303.md

@@ -0,0 +1,68 @@
+# TASK METADATA
+
+- **Target Files:**
+  - `server/main.test.ts` (new)
+  - `server/db.test.ts` (new)
+  - `server/spire_ffi.test.ts` (new)
+  - `server/valkey.test.ts` (new)
+  - `sdk/mod.test.ts`
+  - `sdk/mod.ts`
+- **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 `@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.
+
+---
+
+## 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. **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.
+3. **SDK Modularity:** Integrating a Hono-specific middleware into `@auth-yes/sdk` risks violating the generic nature of the SDK. The `AuthSdk` core must remain strictly agnostic, with the Hono helper imported optionally or cleanly segregated from the core `validateSession` logic.
+
+### 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: Full Integration Test (Hono App Mocking):** Rather than unit testing individual modules in isolation, we can heavily leverage Hono's `.request()` helper on the root app instance to test API endpoints (Tier 1 & 2) in memory while stubbing the underlying `sql` and `valkey` exports. This is generally preferred for testing Hono apps and is cleaner than spinning up a real HTTP server.
+
+---
+
+## Proposed Implementation
+
+### Phase 1: Test Environment Mocking Architecture
+1. **Database & Valkey Isolation:**
+   - Create generic mock setups using `@std/testing/mock` (`stub` and `spy`).
+   - Stub the `sql` export in `server/db.ts` to return controlled JSON objects representing mock users, apps, and grants.
+   - Stub `valkey.get` and `valkey.setex` in `server/valkey.ts` to simulate session cache hits and misses.
+2. **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`
+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 (`POST /auth.v1.AuthService/ValidateSession`).
+2. **Test Cases:**
+   - **Default-Deny:** Unassigned user attempting to access a valid SPIFFE ID. Assert `valid: false` and HTTP `403` or ConnectRPC validation failure.
+   - **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 across endpoints.
+2. **Test Cases:**
+   - Spy on `auditLog` in `server/audit.ts`.
+   - Verify that successful logins (`login_success`), login failures (`login_failed`), and explicit access denials generate the correct event payload structures and are dispatched to the mocked DB.
+
+### Phase 5: SDK Ergonomics & Hono Middleware
+1. **Target:** `sdk/mod.ts`
+2. **Implementation Steps:**
+   - Extend `sdk/mod.ts` (or create an adjunct file like `sdk/hono.ts`) to export a `createAuthMiddleware(sdk: AuthSdk)` function.
+   - The middleware will extract the `session_id` cookie or `Authorization` header, call `sdk.requireAuth()`, and inject 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/mod.test.ts`, create a mock Hono app, apply the middleware, and assert that authorized requests pass and unauthorized requests are halted cleanly.