sentryagent-idp/openspec/changes/phase-1-mvp-implementation/specs/oauth2-token/spec.md

## 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