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

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.