feat: Phase 1 MVP — complete AgentIdP implementation

Implements all P0 features per OpenSpec change phase-1-mvp-implementation: - Agent Registry Service (CRUD) — full lifecycle management - OAuth 2.0 Token Service (Client Credentials flow) - Credential Management (generate, rotate, revoke) - Immutable Audit Log Service Tech: Node.js 18+, TypeScript 5.3+ strict, Express 4.18+, PostgreSQL 14+, Redis 7+ Standards: OpenAPI 3.0 specs, DRY/SOLID, zero `any` types Quality: 18 unit test suites, 244 tests passing, 97%+ coverage OpenAPI: 4 complete specs (14 endpoints total) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-03-28 09:14:41 +00:00
parent 245f8df427
commit d3530285b9
78 changed files with 20590 additions and 1 deletions
--- a/openspec/changes/phase-1-mvp-implementation/.openspec.yaml
+++ b/openspec/changes/phase-1-mvp-implementation/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-03-28
--- a/openspec/changes/phase-1-mvp-implementation/design.md
+++ b/openspec/changes/phase-1-mvp-implementation/design.md
@@ -0,0 +1,130 @@
+## Context
+
+SentryAgent.ai AgentIdP is a greenfield Node.js/TypeScript service with no existing implementation. The codebase contains only scaffolding. Four CEO-approved OpenAPI 3.0 specs define the full API surface. This design governs the architecture for all four P0 services and their shared infrastructure.
+
+**Constraints:**
+- TypeScript 5.3+ strict mode — no `any` types, ever
+- DRY and SOLID enforced on every file
+- PostgreSQL 14+ for all persistent state; Redis 7+ for caching and rate limiting
+- Express 4.18+ as the HTTP framework
+- All secrets bcrypt-hashed (10 rounds); `clientSecret` never persisted in plain text
+- Specs are the source of truth — implementation must match exactly
+
+## Goals / Non-Goals
+
+**Goals:**
+- Implement all 4 P0 services (Agent Registry, OAuth2 Token, Credential Management, Audit Log) as typed Express route handlers backed by typed service classes
+- Enforce free-tier limits (100 agents, 10,000 tokens/month, 100 req/min, 90-day audit retention)
+- Provide a single Express app entry point with all middleware and routing wired up
+- Provide PostgreSQL migrations for all 4 tables
+- Provide a Docker Compose file for local development (Node.js app + Postgres + Redis)
+
+**Non-Goals:**
+- HashiCorp Vault, OPA, Web UI, Python/Go SDKs (Phase 2+)
+- Multi-region deployment, SOC 2 (Phase 3+)
+- Admin-scoped cross-agent credential management (stub `403` — implement in Phase 2)
+
+## Decisions
+
+### D1: Layered architecture (Controller → Service → Repository)
+**Decision**: Each feature has a Controller (HTTP), a Service (business logic), and a Repository (DB queries). No business logic in controllers; no SQL outside repositories.
+**Rationale**: SOLID Single Responsibility. Controllers handle HTTP concerns only. Services are testable in isolation (inject mock repository). Repositories are the sole owners of SQL.
+**Alternative considered**: Fat controllers — rejected (untestable, violates SRP).
+
+### D2: Dependency injection via constructor injection
+**Decision**: All dependencies (repositories, services, Redis client, JWT utils) are injected via constructor parameters. No `new Foo()` inside business logic.
+**Rationale**: SOLID Dependency Inversion. Enables unit testing with mocks. No global singletons in services.
+**Alternative considered**: Service locator / global singletons — rejected (hidden coupling, hard to test).
+
+### D3: Single shared error hierarchy (`SentryAgentError`)
+**Decision**: All custom errors extend `SentryAgentError` (as defined in README §6.6). A single Express error-handling middleware maps each error class to its HTTP status code and `ErrorResponse` shape.
+**Rationale**: DRY — error-to-status mapping exists in exactly one place. Every thrown error is typed and explicit.
+
+### D4: JWT signed with RS256 (asymmetric)
+**Decision**: Access tokens are signed with RS256 (RSA 2048-bit). Public key exposed for external verification.
+**Rationale**: Allows downstream services to verify tokens without calling back to AgentIdP. Industry standard for OAuth2 JWTs. Symmetric HS256 would require sharing the secret with every verifier.
+**Alternative considered**: HS256 — rejected (key distribution problem at scale).
+
+### D5: Redis for token revocation and rate limiting
+**Decision**: Revoked token JTIs are stored in Redis with TTL = token expiry. Rate-limit counters use Redis sliding window. Free-tier monthly token count uses Redis with monthly TTL.
+**Rationale**: Redis provides O(1) token revocation checks without DB round-trips. Token introspection path must be fast (<100ms per spec).
+
+### D6: `clientSecret` format — `sk_live_` prefix + 32 random hex bytes
+**Decision**: Generated secrets follow the pattern `sk_live_<64 hex chars>`. Stored as bcrypt hash (10 rounds).
+**Rationale**: Prefixed format is recognisable in logs/config and grep-able for secret scanning. 64 hex chars = 256 bits of entropy.
+
+### D7: Audit log written synchronously within the request transaction
+**Decision**: Audit events are inserted within the same DB transaction as the action that triggers them (where applicable). For token issuance (Redis-only operation), audit is a separate async fire-and-forget insert.
+**Rationale**: For state-changing DB operations (agent creation, credential rotation) atomicity guarantees the audit record is never lost. Token issuance latency must be <100ms — synchronous audit insert would risk this on high load.
+
+### D8: Project file layout
+```
+src/
+  app.ts                  — Express app factory (no listen call — testable)
+  server.ts               — Entry point (calls app.ts, calls listen)
+  types/index.ts          — All shared TypeScript interfaces and types
+  utils/
+    crypto.ts             — Secret generation, bcrypt helpers
+    jwt.ts                — JWT sign/verify
+    validators.ts         — Joi schemas for all request bodies
+    errors.ts             — SentryAgentError hierarchy
+  middleware/
+    auth.ts               — Bearer token extraction and verification
+    rateLimit.ts          — Redis-backed rate limiter
+    errorHandler.ts       — Global Express error handler
+  db/
+    pool.ts               — pg Pool singleton
+    migrations/           — SQL migration files (001_create_agents.sql, etc.)
+  cache/
+    redis.ts              — Redis client singleton
+  services/
+    AgentService.ts
+    OAuth2Service.ts
+    CredentialService.ts
+    AuditService.ts
+  repositories/
+    AgentRepository.ts
+    CredentialRepository.ts
+    AuditRepository.ts
+    TokenRepository.ts
+  routes/
+    agents.ts
+    token.ts
+    credentials.ts
+    audit.ts
+  controllers/
+    AgentController.ts
+    TokenController.ts
+    CredentialController.ts
+    AuditController.ts
+tests/
+  unit/
+    services/
+    utils/
+  integration/
+    agents.test.ts
+    token.test.ts
+    credentials.test.ts
+    audit.test.ts
+```
+
+## Risks / Trade-offs
+
+- **[Risk] RS256 key management in Phase 1** → Keys loaded from `PEM` env vars (`JWT_PRIVATE_KEY`, `JWT_PUBLIC_KEY`). Rotation not automated until Phase 2 (Vault). Mitigation: documented in deployment guide.
+- **[Risk] Async audit insert on token issuance may drop events on crash** → Acceptable for Phase 1 free tier. Synchronous insert + queue buffering addressed in Phase 2.
+- **[Risk] bcrypt 10 rounds adds ~100ms to credential verification** → Token endpoint latency target is <100ms. Bcrypt is only called on `POST /token` (credential verification), not on every authenticated request (JWT verification is fast). Acceptable.
+- **[Trade-off] No admin scope in Phase 1** → Agents can only manage their own credentials. Cross-agent admin operations return `403 FORBIDDEN` with a clear message. Unblocks Phase 1 shipping without scope management complexity.
+
+## Migration Plan
+
+1. Run `npm install` to install all dependencies
+2. Start Docker Compose (`docker-compose up -d`) — spins up Postgres + Redis
+3. Run migrations: `npm run db:migrate`
+4. Set required env vars (see `.env.example`)
+5. Start server: `npm run dev`
+
+**Rollback**: Drop database, stop containers, revert to previous commit. No shared state in Phase 1 (single-instance).
+
+## Open Questions
+
+- _None_ — all decisions required for Phase 1 implementation are resolved above.
--- a/openspec/changes/phase-1-mvp-implementation/proposal.md
+++ b/openspec/changes/phase-1-mvp-implementation/proposal.md
@@ -0,0 +1,36 @@
+## Why
+
+SentryAgent.ai AgentIdP has no implemented codebase — only scaffolding exists. Phase 1 MVP must ship a production-ready Agent Identity Provider so developers worldwide can register, authenticate, and govern their AI agents for free. All four P0 features have CEO-approved OpenAPI 3.0 specs and are ready for implementation.
+
+## What Changes
+
+- **NEW**: Agent Registry Service — full CRUD lifecycle management for AI agent identities (AGNTCY-aligned)
+- **NEW**: OAuth 2.0 Token Service — Client Credentials grant (RFC 6749), token introspection (RFC 7662), token revocation (RFC 7009)
+- **NEW**: Credential Management Service — generate, rotate, and revoke agent `client_id`/`client_secret` pairs
+- **NEW**: Audit Log Service — immutable, append-only compliance event log (read-only via API)
+- **NEW**: Express.js application bootstrap — routing, middleware (helmet, cors, morgan, pino), error handling
+- **NEW**: PostgreSQL database layer — migrations, connection pool, typed query services
+- **NEW**: Redis caching layer — token validation cache, rate-limit counters
+- **NEW**: Shared infrastructure — typed error hierarchy, Joi validation, JWT utilities, crypto utilities, DI container
+
+## Capabilities
+
+### New Capabilities
+
+- `agent-registry`: Register, retrieve, update, and decommission AI agent identities with AGNTCY-aligned fields (`agentId`, `email`, `agentType`, `capabilities`, `owner`, `deploymentEnv`, `status`)
+- `oauth2-token`: Issue signed JWT access tokens via OAuth 2.0 Client Credentials flow; introspect and revoke tokens per RFC
+- `credential-management`: Generate and rotate `client_id`/`client_secret` pairs per agent; revoke credentials; `clientSecret` shown once only
+- `audit-log`: Query immutable audit events by `agentId`, `action`, `outcome`, and date range; 90-day free-tier retention
+
+### Modified Capabilities
+
+_None — this is a greenfield implementation._
+
+## Impact
+
+- **APIs**: 14 new REST endpoints across 4 services (`/agents`, `/token`, `/agents/{id}/credentials`, `/audit`)
+- **Database**: 4 new PostgreSQL tables (`agents`, `tokens`, `credentials`, `audit_events`) with migrations
+- **Cache**: Redis used for token validation and rate-limit counters
+- **Dependencies**: Express, Joi, jsonwebtoken, bcryptjs, uuid, pg, redis, pino, helmet, cors, dotenv (all pre-approved in README Section 7)
+- **Auth**: All endpoints require Bearer JWT; token endpoint uses `client_id`/`client_secret`
+- **Free tier enforcement**: 100 agents max, 10,000 tokens/month, 100 req/min rate limit, 90-day audit retention
--- a/openspec/changes/phase-1-mvp-implementation/specs/agent-registry/spec.md
+++ b/openspec/changes/phase-1-mvp-implementation/specs/agent-registry/spec.md
@@ -0,0 +1,86 @@
+## ADDED Requirements
+
+### Requirement: Register a new AI agent
+The system SHALL create a new agent identity record with a system-assigned immutable UUID (`agentId`) when a valid `CreateAgentRequest` is received. The `email` field SHALL be unique across all agents. The agent SHALL be created with `status: active`. The system SHALL enforce a free-tier limit of 100 registered agents per account.
+
+#### Scenario: Successful agent registration
+- **WHEN** a POST request to `/agents` is received with a valid `CreateAgentRequest` body and a valid Bearer token
+- **THEN** the system creates the agent, assigns a UUID `agentId`, sets `status` to `active`, sets `createdAt` and `updatedAt` to the current timestamp, and returns `201` with the full `Agent` object
+
+#### Scenario: Duplicate email rejected
+- **WHEN** a POST request to `/agents` is received with an `email` that is already registered
+- **THEN** the system returns `409 Conflict` with `code: AGENT_ALREADY_EXISTS`
+
+#### Scenario: Free tier limit enforced
+- **WHEN** a POST request to `/agents` is received and the account already has 100 registered agents
+- **THEN** the system returns `403 Forbidden` with `code: FREE_TIER_LIMIT_EXCEEDED` and `details.limit: 100`
+
+#### Scenario: Invalid request body rejected
+- **WHEN** a POST request to `/agents` is received with a missing required field or invalid field value (e.g. invalid semver, invalid email, invalid capability pattern)
+- **THEN** the system returns `400 Bad Request` with `code: VALIDATION_ERROR` and `details` identifying the failing field
+
+### Requirement: Retrieve a single agent by ID
+The system SHALL return the full `Agent` record for a given `agentId`.
+
+#### Scenario: Agent found
+- **WHEN** a GET request to `/agents/{agentId}` is received with a valid Bearer token and a UUID that exists in the registry
+- **THEN** the system returns `200 OK` with the full `Agent` object
+
+#### Scenario: Agent not found
+- **WHEN** a GET request to `/agents/{agentId}` is received with a UUID that does not exist
+- **THEN** the system returns `404 Not Found` with `code: AGENT_NOT_FOUND`
+
+### Requirement: List agents with pagination and filtering
+The system SHALL return a paginated list of agents, orderd by `createdAt` descending, optionally filtered by `owner`, `agentType`, and/or `status`.
+
+#### Scenario: Successful paginated list
+- **WHEN** a GET request to `/agents` is received with optional `page`, `limit`, `owner`, `agentType`, `status` query parameters and a valid Bearer token
+- **THEN** the system returns `200 OK` with a `PaginatedAgentsResponse` containing `data`, `total`, `page`, and `limit`
+
+#### Scenario: Invalid pagination parameters rejected
+- **WHEN** a GET request to `/agents` is received with `limit` greater than 100 or `page` less than 1
+- **THEN** the system returns `400 Bad Request` with `code: VALIDATION_ERROR`
+
+### Requirement: Update agent metadata
+The system SHALL partially update a mutable agent record. `agentId`, `email`, and `createdAt` SHALL be immutable. Setting `status` to `decommissioned` SHALL be a one-way irreversible operation.
+
+#### Scenario: Successful partial update
+- **WHEN** a PATCH request to `/agents/{agentId}` is received with a valid partial `UpdateAgentRequest` body and a valid Bearer token
+- **THEN** the system updates only the provided fields, sets `updatedAt` to the current timestamp, and returns `200 OK` with the full updated `Agent` object
+
+#### Scenario: Attempt to modify immutable field rejected
+- **WHEN** a PATCH request to `/agents/{agentId}` contains the `email` field
+- **THEN** the system returns `400 Bad Request` with `code: IMMUTABLE_FIELD` and `details.field: email`
+
+#### Scenario: Decommissioned agent cannot be updated
+- **WHEN** a PATCH request to `/agents/{agentId}` targets an agent with `status: decommissioned`
+- **THEN** the system returns `403 Forbidden` with `code: AGENT_DECOMMISSIONED`
+
+### Requirement: Decommission (soft-delete) an agent
+The system SHALL set an agent's `status` to `decommissioned` and revoke all of its active credentials. The agent record SHALL be retained for audit purposes. This operation SHALL be irreversible.
+
+#### Scenario: Successful decommission
+- **WHEN** a DELETE request to `/agents/{agentId}` is received with a valid Bearer token and the agent exists and is not already decommissioned
+- **THEN** the system sets `status` to `decommissioned`, revokes all active credentials for this agent, and returns `204 No Content`
+
+#### Scenario: Already decommissioned agent rejected
+- **WHEN** a DELETE request to `/agents/{agentId}` is received for an agent that is already `decommissioned`
+- **THEN** the system returns `409 Conflict` with `code: AGENT_ALREADY_DECOMMISSIONED`
+
+### Requirement: Authentication required on all agent endpoints
+All agent endpoints SHALL require a valid Bearer JWT in the `Authorization` header.
+
+#### Scenario: Missing token rejected
+- **WHEN** any request to `/agents` or `/agents/{agentId}` is received without an `Authorization: Bearer` header
+- **THEN** the system returns `401 Unauthorized` with `code: UNAUTHORIZED`
+
+#### Scenario: Invalid token rejected
+- **WHEN** any request to `/agents` or `/agents/{agentId}` is received with an expired, malformed, or revoked Bearer token
+- **THEN** the system returns `401 Unauthorized` with `code: UNAUTHORIZED`
+
+### Requirement: Rate limiting on all agent endpoints
+The system SHALL enforce a rate limit of 100 requests per minute per authenticated client. Rate limit state SHALL be tracked in Redis.
+
+#### Scenario: Rate limit exceeded
+- **WHEN** a client sends more than 100 requests to any agent endpoint within a 60-second window
+- **THEN** the system returns `429 Too Many Requests` with `X-RateLimit-Limit`, `X-RateLimit-Remaining: 0`, and `X-RateLimit-Reset` headers
--- a/openspec/changes/phase-1-mvp-implementation/specs/audit-log/spec.md
+++ b/openspec/changes/phase-1-mvp-implementation/specs/audit-log/spec.md
@@ -0,0 +1,72 @@
+## ADDED Requirements
+
+### Requirement: Audit events are written internally for all significant actions
+The system SHALL automatically create an immutable `AuditEvent` record for each of the following actions: `agent.created`, `agent.updated`, `agent.decommissioned`, `agent.suspended`, `agent.reactivated`, `token.issued`, `token.revoked`, `token.introspected`, `credential.generated`, `credential.rotated`, `credential.revoked`, `auth.failed`. No API endpoint SHALL allow external creation, modification, or deletion of audit records.
+
+#### Scenario: Audit event created on agent registration
+- **WHEN** a new agent is successfully registered via `POST /agents`
+- **THEN** an `AuditEvent` with `action: agent.created`, `outcome: success`, and `metadata` containing `agentType` and `owner` is persisted
+
+#### Scenario: Audit event created on failed authentication
+- **WHEN** a `POST /token` request fails due to invalid credentials
+- **THEN** an `AuditEvent` with `action: auth.failed`, `outcome: failure`, and `metadata` containing `reason` and `clientId` is persisted
+
+#### Scenario: Audit event created on token issuance
+- **WHEN** a token is successfully issued via `POST /token`
+- **THEN** an `AuditEvent` with `action: token.issued`, `outcome: success`, and `metadata` containing `scope` and `expiresAt` is persisted
+
+### Requirement: Query the audit log with pagination and filtering
+The system SHALL return a paginated list of audit events ordered by `timestamp` descending. The caller SHALL hold a valid Bearer token with `audit:read` scope. Filtering SHALL support `agentId`, `action`, `outcome`, `fromDate`, and `toDate` — all optional, combined with logical AND.
+
+#### Scenario: Successful audit log query
+- **WHEN** a GET request to `/audit` is received with a valid Bearer token with `audit:read` scope
+- **THEN** the system returns `200 OK` with a `PaginatedAuditEventsResponse` containing `data`, `total`, `page`, and `limit`
+
+#### Scenario: Filter by agentId
+- **WHEN** a GET request to `/audit?agentId={uuid}` is received
+- **THEN** only events where `agentId` equals the provided UUID are returned
+
+#### Scenario: Filter by action
+- **WHEN** a GET request to `/audit?action=token.issued` is received
+- **THEN** only events with `action: token.issued` are returned
+
+#### Scenario: Filter by date range
+- **WHEN** a GET request to `/audit?fromDate=2026-03-01T00:00:00.000Z&toDate=2026-03-28T23:59:59.999Z` is received
+- **THEN** only events with `timestamp` within the specified range are returned
+
+#### Scenario: fromDate after toDate rejected
+- **WHEN** a GET request to `/audit` is received with `fromDate` that is chronologically after `toDate`
+- **THEN** the system returns `400 Bad Request` with `code: VALIDATION_ERROR` and `details.reason` explaining the invalid date range
+
+#### Scenario: Insufficient scope rejected
+- **WHEN** a GET request to `/audit` is received with a valid Bearer token that does not have `audit:read` scope
+- **THEN** the system returns `403 Forbidden` with `code: INSUFFICIENT_SCOPE`
+
+### Requirement: Retrieve a single audit event by ID
+The system SHALL return a single immutable `AuditEvent` by its `eventId`. The caller SHALL hold a valid Bearer token with `audit:read` scope.
+
+#### Scenario: Audit event found
+- **WHEN** a GET request to `/audit/{eventId}` is received with a valid Bearer token with `audit:read` scope and a UUID that exists in the audit log
+- **THEN** the system returns `200 OK` with the full `AuditEvent` object
+
+#### Scenario: Audit event not found
+- **WHEN** a GET request to `/audit/{eventId}` is received with a UUID that does not exist in the audit log
+- **THEN** the system returns `404 Not Found` with `code: AUDIT_EVENT_NOT_FOUND`
+
+### Requirement: Free-tier 90-day audit log retention
+On the free tier, the system SHALL only return audit events from the last 90 days. Events older than 90 days SHALL be treated as not accessible (return empty results for queries, `404` for direct lookups). The system SHALL return a `400` error with `code: RETENTION_WINDOW_EXCEEDED` if a `fromDate` query parameter falls outside the 90-day retention window.
+
+#### Scenario: Query outside retention window rejected
+- **WHEN** a GET request to `/audit` is received with `fromDate` more than 90 days before today
+- **THEN** the system returns `400 Bad Request` with `code: RETENTION_WINDOW_EXCEEDED` and `details.retentionDays: 90`
+
+#### Scenario: Direct lookup of expired event returns 404
+- **WHEN** a GET request to `/audit/{eventId}` is received for an event with a `timestamp` older than 90 days
+- **THEN** the system returns `404 Not Found` with `code: AUDIT_EVENT_NOT_FOUND`
+
+### Requirement: Rate limiting on audit endpoints
+The system SHALL enforce a rate limit of 100 requests per minute per authenticated client on all audit endpoints.
+
+#### Scenario: Rate limit exceeded on audit endpoint
+- **WHEN** a client sends more than 100 requests to any audit endpoint within a 60-second window
+- **THEN** the system returns `429 Too Many Requests` with `X-RateLimit-Limit`, `X-RateLimit-Remaining: 0`, and `X-RateLimit-Reset` headers
--- a/openspec/changes/phase-1-mvp-implementation/specs/credential-management/spec.md
+++ b/openspec/changes/phase-1-mvp-implementation/specs/credential-management/spec.md
@@ -0,0 +1,83 @@
+## ADDED Requirements
+
+### Requirement: Generate new credentials for an agent
+The system SHALL generate a new `client_id`/`client_secret` pair for a specified agent. The `client_id` SHALL equal the agent's `agentId`. The `client_secret` SHALL be a cryptographically random string with the prefix `sk_live_` followed by 64 hex characters (256 bits of entropy). The plain-text secret SHALL be returned in the response exactly once and SHALL never be stored in plain text — only a bcrypt hash (10 rounds) SHALL be persisted. The agent MUST be in `active` status to generate credentials.
+
+#### Scenario: Successful credential generation
+- **WHEN** a POST request to `/agents/{agentId}/credentials` is received with a valid Bearer token and the agent exists with `status: active`
+- **THEN** the system generates a new credential, persists the bcrypt hash of the secret, and returns `201 Created` with a `CredentialWithSecret` response including the plain-text `clientSecret`
+
+#### Scenario: clientSecret not returned after creation
+- **WHEN** a GET request to `/agents/{agentId}/credentials` is made after credential creation
+- **THEN** the `clientSecret` field is NOT present in any `Credential` object in the response
+
+#### Scenario: Suspended agent cannot generate credentials
+- **WHEN** a POST request to `/agents/{agentId}/credentials` is received for an agent with `status: suspended`
+- **THEN** the system returns `403 Forbidden` with `code: AGENT_NOT_ACTIVE`
+
+#### Scenario: Decommissioned agent cannot generate credentials
+- **WHEN** a POST request to `/agents/{agentId}/credentials` is received for an agent with `status: decommissioned`
+- **THEN** the system returns `403 Forbidden` with `code: AGENT_NOT_ACTIVE`
+
+#### Scenario: Optional expiry respected
+- **WHEN** a POST request to `/agents/{agentId}/credentials` is received with an `expiresAt` value that is a future date-time
+- **THEN** the credential is created with the specified `expiresAt` value
+
+#### Scenario: Past expiry rejected
+- **WHEN** a POST request to `/agents/{agentId}/credentials` is received with an `expiresAt` value that is in the past
+- **THEN** the system returns `400 Bad Request` with `code: VALIDATION_ERROR` and `details.field: expiresAt`
+
+#### Scenario: Agent not found
+- **WHEN** a POST request to `/agents/{agentId}/credentials` is received for a `agentId` that does not exist
+- **THEN** the system returns `404 Not Found` with `code: AGENT_NOT_FOUND`
+
+### Requirement: List credentials for an agent
+The system SHALL return a paginated list of all credentials (both `active` and `revoked`) for an agent, ordered by `createdAt` descending. The `clientSecret` SHALL never be included in list responses.
+
+#### Scenario: Successful credential list
+- **WHEN** a GET request to `/agents/{agentId}/credentials` is received with optional `page`, `limit`, `status` query parameters and a valid Bearer token
+- **THEN** the system returns `200 OK` with a `PaginatedCredentialsResponse` containing `data`, `total`, `page`, and `limit`, with no `clientSecret` fields
+
+#### Scenario: Filter by status
+- **WHEN** a GET request to `/agents/{agentId}/credentials?status=active` is received
+- **THEN** only credentials with `status: active` are returned
+
+### Requirement: Rotate a credential
+The system SHALL rotate an existing active credential by generating a new `clientSecret` for the same `credentialId`. The previous secret SHALL be immediately invalidated. The new plain-text secret SHALL be returned once and never persisted. Only `active` credentials can be rotated.
+
+#### Scenario: Successful rotation
+- **WHEN** a POST request to `/agents/{agentId}/credentials/{credentialId}/rotate` is received with a valid Bearer token and the credential exists with `status: active`
+- **THEN** the system generates a new secret, replaces the stored bcrypt hash, and returns `200 OK` with a `CredentialWithSecret` response including the new plain-text `clientSecret`. The `credentialId` remains unchanged.
+
+#### Scenario: Revoked credential cannot be rotated
+- **WHEN** a POST request to `/agents/{agentId}/credentials/{credentialId}/rotate` is received for a credential with `status: revoked`
+- **THEN** the system returns `409 Conflict` with `code: CREDENTIAL_ALREADY_REVOKED`
+
+#### Scenario: Credential not found
+- **WHEN** a POST request to `/agents/{agentId}/credentials/{credentialId}/rotate` is received with a `credentialId` that does not exist for the given agent
+- **THEN** the system returns `404 Not Found` with `code: CREDENTIAL_NOT_FOUND`
+
+### Requirement: Revoke a credential
+The system SHALL permanently revoke a credential by setting its `status` to `revoked` and recording a `revokedAt` timestamp. The credential record SHALL be retained for audit purposes. Revocation SHALL be irreversible. Tokens previously issued with this credential SHALL remain valid until their natural expiry (token revocation is handled separately via `POST /token/revoke`). Revoking an already-revoked credential SHALL return `409 Conflict`.
+
+#### Scenario: Successful revocation
+- **WHEN** a DELETE request to `/agents/{agentId}/credentials/{credentialId}` is received with a valid Bearer token and the credential exists with `status: active`
+- **THEN** the system sets `status` to `revoked`, sets `revokedAt` to the current timestamp, and returns `204 No Content`
+
+#### Scenario: Already-revoked credential rejected
+- **WHEN** a DELETE request to `/agents/{agentId}/credentials/{credentialId}` is received for a credential that is already `revoked`
+- **THEN** the system returns `409 Conflict` with `code: CREDENTIAL_ALREADY_REVOKED`
+
+### Requirement: Agent decommission cascades to credential revocation
+When an agent is decommissioned via `DELETE /agents/{agentId}`, the system SHALL revoke all active credentials for that agent as part of the same operation.
+
+#### Scenario: All credentials revoked on agent decommission
+- **WHEN** an agent is successfully decommissioned via `DELETE /agents/{agentId}`
+- **THEN** all credentials for that agent with `status: active` are set to `status: revoked` with `revokedAt` = current timestamp
+
+### Requirement: Authentication required on all credential endpoints
+All credential endpoints SHALL require a valid Bearer JWT. An agent MAY manage its own credentials using a self-issued token. Managing another agent's credentials SHALL return `403 Forbidden` unless the caller holds an admin-scoped token (admin scope is not implemented in Phase 1 — return `403` for all cross-agent requests).
+
+#### Scenario: Unauthenticated request rejected
+- **WHEN** any request to `/agents/{agentId}/credentials` is received without a valid Bearer token
+- **THEN** the system returns `401 Unauthorized` with `code: UNAUTHORIZED`
--- a/openspec/changes/phase-1-mvp-implementation/specs/oauth2-token/spec.md
+++ b/openspec/changes/phase-1-mvp-implementation/specs/oauth2-token/spec.md
@@ -0,0 +1,76 @@
+## ADDED Requirements
+
+### Requirement: Issue access token via Client Credentials grant
+The system SHALL issue a signed RS256 JWT access token when an agent authenticates with a valid `client_id` (agentId) and `client_secret` using the OAuth 2.0 Client Credentials grant (RFC 6749 §4.4). The request body SHALL use `application/x-www-form-urlencoded` encoding. The response SHALL include `Cache-Control: no-store` and `Pragma: no-cache` headers. The system SHALL enforce a free-tier limit of 10,000 token requests per calendar month per client.
+
+#### Scenario: Successful token issuance
+- **WHEN** a POST request to `/token` is received with `grant_type=client_credentials`, a valid `client_id`, and a valid `client_secret` for an `active` agent
+- **THEN** the system verifies the credential, issues a signed JWT with `sub` = `agentId`, `scope` = requested (or default) scope, `exp` = now + 3600s, and returns `200 OK` with `TokenResponse`
+
+#### Scenario: Invalid client credentials rejected
+- **WHEN** a POST request to `/token` is received with a `client_id` that does not exist or a `client_secret` that does not match
+- **THEN** the system returns `401 Unauthorized` with `error: invalid_client`
+
+#### Scenario: Suspended agent cannot obtain tokens
+- **WHEN** a POST request to `/token` is received for an agent with `status: suspended`
+- **THEN** the system returns `403 Forbidden` with `error: unauthorized_client` and a description indicating the agent is suspended
+
+#### Scenario: Decommissioned agent cannot obtain tokens
+- **WHEN** a POST request to `/token` is received for an agent with `status: decommissioned`
+- **THEN** the system returns `403 Forbidden` with `error: unauthorized_client`
+
+#### Scenario: Unsupported grant type rejected
+- **WHEN** a POST request to `/token` is received with a `grant_type` other than `client_credentials`
+- **THEN** the system returns `400 Bad Request` with `error: unsupported_grant_type`
+
+#### Scenario: Invalid scope rejected
+- **WHEN** a POST request to `/token` is received with a `scope` value that contains an unrecognised scope identifier
+- **THEN** the system returns `400 Bad Request` with `error: invalid_scope`
+
+#### Scenario: Free tier monthly token limit enforced
+- **WHEN** a POST request to `/token` is received and the agent has already made 10,000 token requests in the current calendar month
+- **THEN** the system returns `403 Forbidden` with `error: unauthorized_client` and a description indicating the monthly free-tier limit is reached
+
+### Requirement: Token introspection (RFC 7662)
+The system SHALL determine whether a given access token is currently active (valid, not expired, not revoked). The endpoint SHALL return `200 OK` for both active and inactive tokens — the `active` field in the response SHALL indicate validity. The caller SHALL hold a valid Bearer token with `tokens:read` scope.
+
+#### Scenario: Active token introspection
+- **WHEN** a POST request to `/token/introspect` is received with a valid, non-expired, non-revoked token and the caller has `tokens:read` scope
+- **THEN** the system returns `200 OK` with `active: true` and the token's claims (`sub`, `client_id`, `scope`, `token_type`, `iat`, `exp`)
+
+#### Scenario: Expired or revoked token introspection
+- **WHEN** a POST request to `/token/introspect` is received with a token that is expired or has been revoked
+- **THEN** the system returns `200 OK` with `active: false` and no other claims
+
+#### Scenario: Insufficient scope for introspection
+- **WHEN** a POST request to `/token/introspect` is received with a valid Bearer token that does not have `tokens:read` scope
+- **THEN** the system returns `403 Forbidden` with `code: INSUFFICIENT_SCOPE`
+
+### Requirement: Token revocation (RFC 7009)
+The system SHALL invalidate a given access token immediately. Revoking an already-revoked or expired token SHALL be a successful, idempotent operation (RFC 7009 §2.1). Revoked token JTIs SHALL be stored in Redis with TTL equal to the token's remaining lifetime.
+
+#### Scenario: Successful token revocation
+- **WHEN** a POST request to `/token/revoke` is received with a valid Bearer token and a `token` parameter containing a valid JWT
+- **THEN** the system adds the token's JTI to the Redis revocation list, and returns `200 OK` with an empty body
+
+#### Scenario: Revocation of already-revoked token is idempotent
+- **WHEN** a POST request to `/token/revoke` is received with a token that is already in the Redis revocation list
+- **THEN** the system returns `200 OK` with an empty body (no error)
+
+#### Scenario: Missing token parameter rejected
+- **WHEN** a POST request to `/token/revoke` is received with no `token` field in the body
+- **THEN** the system returns `400 Bad Request` with `code: VALIDATION_ERROR`
+
+### Requirement: JWT claims structure
+All issued JWTs SHALL contain the following claims: `sub` (agentId), `client_id` (agentId), `scope` (space-separated granted scopes), `jti` (UUID, unique per token), `iat` (issued-at Unix timestamp), `exp` (expiry Unix timestamp). Tokens SHALL be signed with RS256.
+
+#### Scenario: JWT contains required claims
+- **WHEN** a token is issued via `POST /token`
+- **THEN** the decoded JWT payload contains `sub`, `client_id`, `scope`, `jti`, `iat`, and `exp` fields
+
+### Requirement: Rate limiting on token endpoints
+The system SHALL enforce a rate limit of 100 requests per minute per `client_id` on all token endpoints.
+
+#### Scenario: Rate limit exceeded on token endpoint
+- **WHEN** a client sends more than 100 requests to any token endpoint within a 60-second window
+- **THEN** the system returns `429 Too Many Requests` with `X-RateLimit-Limit`, `X-RateLimit-Remaining: 0`, and `X-RateLimit-Reset` headers
--- a/openspec/changes/phase-1-mvp-implementation/tasks.md
+++ b/openspec/changes/phase-1-mvp-implementation/tasks.md
@@ -0,0 +1,83 @@
+## 1. Project Bootstrap & Infrastructure
+
+- [x] 1.1 Initialise `package.json` with all required dependencies (Express, TypeScript, Joi, jsonwebtoken, bcryptjs, uuid, pg, redis, pino, helmet, cors, dotenv, jest, supertest, ts-jest, ESLint, Prettier)
+- [x] 1.2 Create `tsconfig.json` with strict mode enabled (all flags from README §6.4)
+- [x] 1.3 Create `.eslintrc.json` with `@typescript-eslint` plugin and no-`any` rule
+- [x] 1.4 Create `.prettierrc`
+- [x] 1.5 Create `jest.config.ts` with `ts-jest` preset and coverage thresholds (>80%)
+- [x] 1.6 Create `docker-compose.yml` with `postgres:14-alpine` and `redis:7-alpine` services
+- [x] 1.7 Create `.env.example` documenting all required environment variables (`DATABASE_URL`, `REDIS_URL`, `JWT_PRIVATE_KEY`, `JWT_PUBLIC_KEY`, `PORT`, etc.)
+
+## 2. Shared Infrastructure
+
+- [x] 2.1 Create `src/types/index.ts` — all shared TypeScript interfaces (`IAgent`, `ICredential`, `IAuditEvent`, `ITokenPayload`, `ICreateAgentRequest`, `IUpdateAgentRequest`, etc.)
+- [x] 2.2 Create `src/utils/errors.ts` — full `SentryAgentError` hierarchy (`ValidationError`, `AgentNotFoundError`, `AgentAlreadyExistsError`, `CredentialError`, `AuthenticationError`, `AuthorizationError`, `RateLimitError`, `FreeTierLimitError`)
+- [x] 2.3 Create `src/utils/crypto.ts` — `generateClientSecret()` (sk_live_ prefix + 64 hex), `hashSecret(plain)` (bcrypt 10 rounds), `verifySecret(plain, hash)` (bcrypt compare)
+- [x] 2.4 Create `src/utils/jwt.ts` — `signToken(payload, privateKey)` (RS256), `verifyToken(token, publicKey)` (returns typed payload), `decodeToken(token)` (no verification)
+- [x] 2.5 Create `src/utils/validators.ts` — Joi schemas for `CreateAgentRequest`, `UpdateAgentRequest`, `TokenRequest`, `IntrospectRequest`, `RevokeRequest`, `GenerateCredentialRequest`, list query params
+- [x] 2.6 Create `src/db/pool.ts` — typed `pg.Pool` singleton, reads `DATABASE_URL` from env
+- [x] 2.7 Create `src/cache/redis.ts` — typed Redis client singleton, reads `REDIS_URL` from env
+- [x] 2.8 Create `src/db/migrations/001_create_agents.sql` — `agents` table (all fields from OpenAPI spec, `status` as varchar)
+- [x] 2.9 Create `src/db/migrations/002_create_credentials.sql` — `credentials` table (`credential_id`, `client_id`, `secret_hash`, `status`, `created_at`, `expires_at`, `revoked_at`)
+- [x] 2.10 Create `src/db/migrations/003_create_audit_events.sql` — `audit_events` table (`event_id`, `agent_id`, `action`, `outcome`, `ip_address`, `user_agent`, `metadata` JSONB, `timestamp`)
+- [x] 2.11 Create `src/db/migrations/004_create_tokens.sql` — `token_revocations` table (`jti`, `expires_at`) for soft revocation tracking (supplementary to Redis)
+- [x] 2.12 Create `npm run db:migrate` script to execute migrations in order
+
+## 3. Middleware
+
+- [x] 3.1 Create `src/middleware/auth.ts` — Bearer token extraction from `Authorization` header, RS256 JWT verification, Redis revocation check, attaches decoded payload to `req.user`; throws `AuthenticationError` on failure
+- [x] 3.2 Create `src/middleware/rateLimit.ts` — Redis sliding window counter keyed by `client_id`; injects `X-RateLimit-*` headers on every response; throws `RateLimitError` at 100 req/min
+- [x] 3.3 Create `src/middleware/errorHandler.ts` — Express error middleware; maps `SentryAgentError` subclasses to HTTP status codes and `ErrorResponse` JSON; maps unknown errors to `500`
+
+## 4. Agent Registry
+
+- [x] 4.1 Create `src/repositories/AgentRepository.ts` — typed methods: `create`, `findById`, `findByEmail`, `findAll` (with filters + pagination), `update`, `decommission`, `countByOwner`; all SQL in this file only
+- [x] 4.2 Create `src/services/AgentService.ts` — `registerAgent`, `getAgentById`, `listAgents`, `updateAgent`, `decommissionAgent`; enforces free-tier 100-agent limit; validates immutable fields on update; calls `AuditService` for all write operations; JSDoc on all public methods
+- [x] 4.3 Create `src/controllers/AgentController.ts` — HTTP handlers for all 5 agent endpoints; Joi validation using `validators.ts`; delegates to `AgentService`; no business logic
+- [x] 4.4 Create `src/routes/agents.ts` — Express router wiring `AgentController` handlers to paths with `auth` and `rateLimit` middleware
+
+## 5. OAuth 2.0 Token Service
+
+- [x] 5.1 Create `src/repositories/TokenRepository.ts` — `addToRevocationList(jti, expiresAt)`, `isRevoked(jti)` (checks Redis first, then DB); `incrementMonthlyCount(clientId)`, `getMonthlyCount(clientId)` (Redis-backed)
+- [x] 5.2 Create `src/services/OAuth2Service.ts` — `issueToken` (validates client credentials via bcrypt, checks agent status, enforces 10k monthly limit, signs RS256 JWT, writes audit event), `introspectToken` (verifies + checks revocation), `revokeToken` (adds JTI to Redis + DB revocation list, writes audit event); JSDoc on all public methods
+- [x] 5.3 Create `src/controllers/TokenController.ts` — HTTP handlers for `POST /token`, `POST /token/introspect`, `POST /token/revoke`; parses `application/x-www-form-urlencoded`; delegates to `OAuth2Service`; returns `OAuth2ErrorResponse` for `/token` errors, `ErrorResponse` for introspect/revoke errors
+- [x] 5.4 Create `src/routes/token.ts` — Express router; `/token` uses no Bearer auth middleware (credentials are in body); `/token/introspect` and `/token/revoke` use `auth` middleware
+
+## 6. Credential Management
+
+- [x] 6.1 Create `src/repositories/CredentialRepository.ts` — `create`, `findById`, `findByAgentId` (with pagination + status filter), `updateHash`, `revoke`, `revokeAllForAgent`; all SQL here only
+- [x] 6.2 Create `src/services/CredentialService.ts` — `generateCredential` (checks agent active status, generates secret via `crypto.ts`, bcrypt-hashes, persists), `listCredentials`, `rotateCredential` (generates new secret, replaces hash, same credentialId), `revokeCredential`; calls `AuditService` for all write operations; JSDoc on all public methods
+- [x] 6.3 Create `src/controllers/CredentialController.ts` — HTTP handlers for all 4 credential endpoints; Joi validation; delegates to `CredentialService`
+- [x] 6.4 Create `src/routes/credentials.ts` — Express router under `/agents/:agentId/credentials` with `auth` and `rateLimit` middleware
+
+## 7. Audit Log Service
+
+- [x] 7.1 Create `src/repositories/AuditRepository.ts` — `create(event)`, `findById(eventId)`, `findAll(filters, pagination)` with support for `agentId`, `action`, `outcome`, `fromDate`, `toDate` filtering and 90-day retention window enforcement
+- [x] 7.2 Create `src/services/AuditService.ts` — `logEvent(agentId, action, outcome, ipAddress, userAgent, metadata)` (async insert, fire-and-forget for token endpoints); `queryEvents(filters, pagination)`, `getEventById(eventId)`; enforces 90-day retention on queries; JSDoc on all public methods
+- [x] 7.3 Create `src/controllers/AuditController.ts` — HTTP handlers for `GET /audit` and `GET /audit/{eventId}`; scope check for `audit:read`; Joi validation of query params
+- [x] 7.4 Create `src/routes/audit.ts` — Express router with `auth` and `rateLimit` middleware
+
+## 8. Application Assembly
+
+- [x] 8.1 Create `src/app.ts` — Express app factory: registers `helmet`, `cors`, `morgan`/`pino-http`, JSON body parser, `urlencoded` body parser (for token endpoints), all 4 route modules, and `errorHandler` middleware; exported function (not called directly — testable)
+- [x] 8.2 Create `src/server.ts` — imports `app.ts`, reads `PORT` from env, calls `app.listen`; entry point only
+
+## 9. Unit Tests
+
+- [x] 9.1 Write unit tests for `src/utils/crypto.ts` — secret generation format, bcrypt hash/verify round-trip
+- [x] 9.2 Write unit tests for `src/utils/jwt.ts` — sign/verify/decode with RS256 test keys
+- [x] 9.3 Write unit tests for `src/utils/validators.ts` — valid and invalid inputs for every Joi schema
+- [x] 9.4 Write unit tests for `src/services/AgentService.ts` — mock `AgentRepository` and `AuditService`; cover all scenarios from agent-registry spec
+- [x] 9.5 Write unit tests for `src/services/OAuth2Service.ts` — mock `TokenRepository`, `CredentialRepository`, `AuditService`; cover all scenarios from oauth2-token spec
+- [x] 9.6 Write unit tests for `src/services/CredentialService.ts` — mock `CredentialRepository`, `AgentRepository`, `AuditService`; cover all scenarios from credential-management spec
+- [x] 9.7 Write unit tests for `src/services/AuditService.ts` — mock `AuditRepository`; cover query, filter, and retention logic
+- [x] 9.8 Write unit tests for `src/middleware/auth.ts` — valid token, expired token, revoked token, missing header
+- [x] 9.9 Write unit tests for `src/middleware/errorHandler.ts` — each `SentryAgentError` subclass maps to correct HTTP status and error code
+
+## 10. Integration Tests
+
+- [x] 10.1 Write integration tests for Agent Registry (`tests/integration/agents.test.ts`) — all 5 endpoints, all response codes, pagination, filtering; uses real Postgres (test DB) and Redis
+- [x] 10.2 Write integration tests for OAuth2 Token Service (`tests/integration/token.test.ts`) — all 3 endpoints, all response codes, token issuance and revocation flow, RFC compliance
+- [x] 10.3 Write integration tests for Credential Management (`tests/integration/credentials.test.ts`) — all 4 endpoints, all response codes, full rotate-then-revoke flow
+- [x] 10.4 Write integration tests for Audit Log Service (`tests/integration/audit.test.ts`) — query with all filter combinations, single event retrieval, retention window enforcement
+- [x] 10.5 Verify test coverage meets >80% threshold across all services (`npm test -- --coverage`)
--- a/openspec/config.yaml
+++ b/openspec/config.yaml
@@ -0,0 +1,20 @@
+schema: spec-driven
+
+# Project context (optional)
+# This is shown to AI when creating artifacts.
+# Add your tech stack, conventions, style guides, domain knowledge, etc.
+# Example:
+#   context: |
+#     Tech stack: TypeScript, React, Node.js
+#     We use conventional commits
+#     Domain: e-commerce platform
+
+# Per-artifact rules (optional)
+# Add custom rules for specific artifacts.
+# Example:
+#   rules:
+#     proposal:
+#       - Keep proposals under 500 words
+#       - Always include a "Non-goals" section
+#     tasks:
+#       - Break tasks into chunks of max 2 hours