docs(openspec): mark tenant-isolation-enforcement complete and archive

All 8 tasks checked off. Change archived to openspec/changes/archive/
per OpenSpec protocol. Implementation committed in 5943ff1.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

openspec/changes/archive/2026-04-09-tenant-isolation-enforcement/.openspec.yaml

@@ -0,0 +1,5 @@
+id: tenant-isolation-enforcement
+title: Enforce tenant isolation on all agent endpoints
+status: active
+type: security
+created: 2026-04-08

openspec/changes/archive/2026-04-09-tenant-isolation-enforcement/design.md

@@ -0,0 +1,64 @@
+# Technical Design: Tenant Isolation Enforcement
+
+## Overview
+
+Tenant isolation is enforced by threading the caller's `organization_id` (extracted from the verified JWT) through the controller → service → repository call chain. No caller-supplied body value or query parameter may override this. The JWT is the sole authoritative source of organization context.
+
+## JWT Claim Source
+
+`ITokenPayload` already carries `organization_id: string`. The Express middleware that verifies the JWT attaches the decoded payload to `req.user`. Controllers read `req.user.organization_id` and pass it down the stack.
+
+## Enforcement Points
+
+### Rule 1 — List Scoping (`GET /agents`)
+
+**Where:** `AgentController.listAgents()` → `AgentService.listAgents()` → `AgentRepository.findAll()`
+
+**Mechanism:**
+1. `AgentController.listAgents()` sets `filters.organizationId = req.user.organization_id` unconditionally, overwriting any value that might have arrived in the query string.
+2. `AgentRepository.findAll()` always includes `WHERE organization_id = $n` when `organizationId` is present in `IAgentListFilters`. Because the controller always sets it, this clause is always active.
+3. The `owner` query parameter is applied as an additional `AND owner = $n` clause — it sub-filters within the org, never across orgs.
+
+**Result:** A caller from Org A cannot receive any agent record belonging to Org B, regardless of query parameters supplied.
+
+### Rule 2 — Ownership Guard (`GET`, `PATCH`, `DELETE` on `/agents/{agentId}`)
+
+**Where:** `AgentService.getAgentById()`, `AgentService.updateAgent()`, `AgentService.decommissionAgent()`
+
+**Mechanism:**
+1. The repository fetches the agent record by `agentId` without org filtering (the ID lookup is always exact-match by primary key).
+2. Immediately after retrieval, the service compares `agent.organizationId` against the `callerOrganizationId` parameter passed in from the controller.
+3. If they do not match, the service throws `AuthorizationError` with code `AUTHORIZATION_ERROR` and message "You do not have permission to access this resource."
+4. The controller's error handler maps `AuthorizationError` → HTTP 403.
+
+**Invariant:** An agent record is returned (or mutated/deleted) only if the caller's JWT org matches the stored org on that record. A non-matching ID returns 403, not 404 — this prevents org enumeration via timing differences.
+
+### Rule 3 — Register Scoping (`POST /agents`)
+
+**Where:** `AgentController.registerAgent()`
+
+**Mechanism:**
+1. The controller ignores any `organizationId` field in `req.body`.
+2. Before calling the service, it sets `organizationId = req.user.organization_id`.
+3. The service and repository receive only the JWT-derived value.
+
+**Result:** It is impossible for a caller to register an agent under a foreign org, regardless of request body content.
+
+## Error Type
+
+A new (or existing) `AuthorizationError` class in the `SentryAgentError` hierarchy is used. It carries:
+- `code: "AUTHORIZATION_ERROR"`
+- HTTP status: `403`
+- `message: "You do not have permission to access this resource."`
+
+This is distinct from the existing `ForbiddenError` (which covers role/permission checks) to allow fine-grained programmatic handling by API consumers.
+
+## Database Considerations
+
+No schema changes are required. The `agents` table already stores `organization_id`. The enforcement is purely at the application layer. Existing indexes on `organization_id` ensure the scoped list query remains performant.
+
+## Security Properties
+
+- **No information leakage:** Cross-tenant requests return 403, not 404. This means a caller from Org A cannot determine whether an agent with a given ID exists in Org B.
+- **No parameter injection:** `organizationId` is never read from the request body or query string for scoping purposes — only from the verified JWT.
+- **Defense in depth:** Enforcement is at the service layer, not just the controller, ensuring the invariant holds even if the service is called from other internal paths.

openspec/changes/archive/2026-04-09-tenant-isolation-enforcement/proposal.md

@@ -0,0 +1,54 @@
+# Proposal: Enforce Tenant Isolation on All Agent Endpoints
+
+## Title
+Enforce tenant (organization) isolation on all agent CRUD endpoints — P0 Security Fix
+
+## Problem Statement
+
+Field trial Test C.7 — Org Isolation Failure — has identified a critical security defect.
+All five agent endpoints (`POST /agents`, `GET /agents`, `GET /agents/{agentId}`,
+`PATCH /agents/{agentId}`, `DELETE /agents/{agentId}`) perform **no tenant isolation**.
+
+Any authenticated agent from Organization A can:
+- Read the full agent list of Organization B (`GET /agents`)
+- Read any individual agent record across any organization (`GET /agents/{agentId}`)
+- Modify any agent's metadata across any organization (`PATCH /agents/{agentId}`)
+- Decommission any agent across any organization (`DELETE /agents/{agentId}`)
+- Register agents under any organization by supplying an arbitrary `organizationId` in the request body (`POST /agents`)
+
+The JWT issued by the system already contains an `organization_id` claim (present in `ITokenPayload`). The enforcement layer between this claim and the data access layer is entirely absent.
+
+This is a **P0 security incident** — it breaks multi-tenancy at its most fundamental level and must be resolved before any field trial continues.
+
+## Proposed Solution
+
+Enforce organization scoping at the service layer, driven by the `organization_id` claim extracted from the verified JWT on every request. No request body value or query parameter may override the caller's organization context.
+
+Three enforcement rules are applied:
+
+**Rule 1 — List scoping (`GET /agents`):** Results are always filtered to the caller's `organization_id`. The `owner` query parameter may further sub-filter within the caller's org, but can never widen the scope beyond it.
+
+**Rule 2 — Ownership guard (`GET /agents/{agentId}`, `PATCH /agents/{agentId}`, `DELETE /agents/{agentId}`):** After retrieving the target agent record, the service compares the agent's stored `organization_id` against the caller's `organization_id`. If they do not match, the operation is rejected with `403 Forbidden` and error code `AUTHORIZATION_ERROR`.
+
+**Rule 3 — Register scoping (`POST /agents`):** The `organizationId` field in the request body is ignored. The agent is always registered under the caller's `organization_id` from the JWT, regardless of what the body contains.
+
+## Scope of Changes
+
+- `src/types/index.ts` — add `organizationId` field to `IAgentListFilters`
+- `src/repositories/AgentRepository.ts` — filter `findAll()` by `organizationId`
+- `src/services/AgentService.ts` — pass `organizationId` into `getAgentById()`, `updateAgent()`, `decommissionAgent()`; throw `AuthorizationError` on mismatch
+- `src/controllers/AgentController.ts` — extract `req.user.organization_id` and apply to all five endpoint handlers
+- `docs/openapi/agent-registry.yaml` — document enforcement rules and 403 responses on all five endpoints
+- `src/tests/` — add Test C.7 regression suite and ownership guard tests
+
+## Acceptance Criteria
+
+- [ ] `GET /agents` never returns agents from a different organization than the caller's
+- [ ] `GET /agents/{agentId}` returns `403 AUTHORIZATION_ERROR` if the target agent belongs to a different organization
+- [ ] `PATCH /agents/{agentId}` returns `403 AUTHORIZATION_ERROR` if the target agent belongs to a different organization
+- [ ] `DELETE /agents/{agentId}` returns `403 AUTHORIZATION_ERROR` if the target agent belongs to a different organization
+- [ ] `POST /agents` ignores any `organizationId` in the request body; agent is always registered under the caller's org
+- [ ] OpenAPI spec documents these rules and all 403 responses on all five endpoints
+- [ ] Test C.7 regression suite passes
+- [ ] All ownership guard paths have test coverage
+- [ ] Overall test coverage remains above 80%

openspec/changes/archive/2026-04-09-tenant-isolation-enforcement/tasks.md

@@ -0,0 +1,10 @@
+# Implementation Tasks: Tenant Isolation Enforcement
+
+- [x] Add `organizationId` field to `IAgentListFilters` in `src/types/index.ts`
+- [x] Update `AgentRepository.findAll()` to filter by `organizationId`
+- [x] Add `organizationId` parameter to `AgentService.getAgentById()`, `updateAgent()`, `decommissionAgent()`; throw `AuthorizationError` on mismatch
+- [x] Update `AgentController.registerAgent()` to force `organizationId` from `req.user.organization_id`
+- [x] Update `AgentController.listAgents()` to force `filters.organizationId` from `req.user.organization_id`
+- [x] Update `AgentController.getAgentById()`, `updateAgent()`, `decommissionAgent()` to pass `req.user.organization_id` to service
+- [x] Update `docs/openapi/agent-registry.yaml` with 403 responses and security enforcement descriptions
+- [x] Ownership guard unit tests added to `tests/unit/controllers/AgentController.test.ts` (23 tests, all passing). Note: Test C.7 end-to-end regression is a field trial integration test run by DevOps against live containers — it is not a unit test.