diff --git a/AGENTS.md b/AGENTS.md index fc5ff3e..6195ee4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -24,11 +24,12 @@ Management (IAM) fabric and WebAuthn Passkey authority. server-side (`deleteCookie` across host and wildcard domains). 3. **Quality Gates:** Every PR must pass `deno fmt`, `deno task lint`, `deno task check`, and `deno test`. -4. **Dual Remote & SDK Distribution:** Development is tracked on GitHub (`origin`: - `git@github.com:mrteye/auth-yes.git`). All commits and SDK changes must be - mirrored to Gitea (`gitea`: `git@git.atyg.org:tylerg/auth-yes.git`) so that - external agents (e.g. Jules) and unauthenticated local projects can consume - raw SDK modules via `https://git.atyg.org/tylerg/auth-yes/raw/branch/main/sdk/mod.ts`. +4. **Dual Remote & SDK Distribution:** Development is tracked on GitHub + (`origin`: `git@github.com:mrteye/auth-yes.git`). All commits and SDK changes + must be mirrored to Gitea (`gitea`: `git@git.atyg.org:tylerg/auth-yes.git`) + so that external agents (e.g. Jules) and unauthenticated local projects can + consume raw SDK modules via + `https://git.atyg.org/tylerg/auth-yes/raw/branch/main/sdk/mod.ts`. ## 3. History & Context Link diff --git a/tasks/new/2026-0821.01.jul.audit.layered-security.verify-3tier-auth-and-rbac-2303.md b/tasks/new/2026-0821.01.jul.audit.layered-security.verify-3tier-auth-and-rbac-2303.md index b0a871b..96b9ced 100644 --- a/tasks/new/2026-0821.01.jul.audit.layered-security.verify-3tier-auth-and-rbac-2303.md +++ b/tasks/new/2026-0821.01.jul.audit.layered-security.verify-3tier-auth-and-rbac-2303.md @@ -1,68 +1,144 @@ # 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.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. + - `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. **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. + +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: 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. + +- **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 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):** +### 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. + - 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` + +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. + - 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`. + - 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`). + +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 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. + - **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 across endpoints. + +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 generate the correct event payload structures and are dispatched to the mocked DB. + - 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: SDK Ergonomics & Hono Middleware -1. **Target:** `sdk/mod.ts` +### Phase 5: Modular SDK Ergonomics & Hono Middleware + +1. **Target:** `sdk/hono.ts` (new) and `sdk/hono.test.ts` (new). 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`. + - 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/mod.test.ts`, create a mock Hono app, apply the middleware, and assert that authorized requests pass and unauthorized requests are halted cleanly. \ No newline at end of file + - 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`.