7441c9f298
All findings from the inaugural LeadValidator audit resolved and confirmed. Release gate: PASS. VV_ISSUE_002 (BLOCKER): 15 OpenAPI specs verified present covering all 20 route groups (46 endpoints documented in docs/openapi/) VV_ISSUE_003 (MAJOR): Remove any types from src/db/pool.ts — replaced pool.query shim with unknown[] + Object.defineProperty, zero any types, eslint-disable suppressions removed VV_ISSUE_004 (MAJOR): Remove raw Pool from ScaffoldController and HealthDetailedController — injected AgentRepository/CredentialRepository and DbProbe interface respectively; added CredentialRepository.findActiveClientId() VV_ISSUE_005 (MAJOR): Add unit tests for 5 untested services — ComplianceStatusStore, EventPublisher, MarketplaceService, OIDCTrustPolicyService, UsageService VV_ISSUE_006 (MAJOR): Add integration tests for 7 missing route groups — analytics, billing, tiers, webhooks, marketplace, oidc-trust-policies, oidc-token-exchange VV_ISSUE_001 (MINOR): Create missing design.md and tasks.md in 4 OpenSpec archives — all archives now complete Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
411 lines
13 KiB
YAML
411 lines
13 KiB
YAML
openapi: "3.0.3"
|
|
|
|
info:
|
|
title: SentryAgent.ai — OIDC Well-Known & Agent Info
|
|
version: 1.0.0
|
|
description: |
|
|
OpenID Connect discovery, JWKS, and agent identity endpoints for the
|
|
SentryAgent.ai AgentIdP platform.
|
|
|
|
**Unauthenticated endpoints** (public metadata):
|
|
- `GET /.well-known/openid-configuration` — OIDC Discovery Document
|
|
- `GET /.well-known/jwks.json` — JSON Web Key Set (public signing keys)
|
|
|
|
**Authenticated endpoint** (requires Bearer JWT):
|
|
- `GET /agent-info` — Agent identity claims (equivalent to OIDC UserInfo)
|
|
|
|
All endpoints are mounted at the application root (`/`) so that
|
|
`/.well-known/*` paths resolve correctly without an `/api/v1` prefix.
|
|
|
|
servers:
|
|
- url: http://localhost:3000
|
|
description: Local development server
|
|
- url: https://api.sentryagent.ai
|
|
description: Production server
|
|
|
|
tags:
|
|
- name: OIDC Discovery
|
|
description: Public OIDC metadata endpoints (unauthenticated)
|
|
- name: Agent Info
|
|
description: Authenticated agent identity endpoint
|
|
|
|
components:
|
|
securitySchemes:
|
|
BearerAuth:
|
|
type: http
|
|
scheme: bearer
|
|
bearerFormat: JWT
|
|
description: |
|
|
JWT access token obtained via `POST /api/v1/token`.
|
|
Include as `Authorization: Bearer <token>`.
|
|
|
|
schemas:
|
|
OIDCDiscoveryDocument:
|
|
type: object
|
|
description: |
|
|
OpenID Connect Discovery 1.0 document as defined in the OIDC specification.
|
|
Returned by `GET /.well-known/openid-configuration`.
|
|
required:
|
|
- issuer
|
|
- authorization_endpoint
|
|
- token_endpoint
|
|
- jwks_uri
|
|
- response_types_supported
|
|
- subject_types_supported
|
|
- id_token_signing_alg_values_supported
|
|
- scopes_supported
|
|
- claims_supported
|
|
- grant_types_supported
|
|
properties:
|
|
issuer:
|
|
type: string
|
|
format: uri
|
|
description: OIDC Issuer URL. Must match the `iss` claim in ID tokens.
|
|
example: "https://idp.sentryagent.ai"
|
|
authorization_endpoint:
|
|
type: string
|
|
format: uri
|
|
description: Authorization endpoint (stub — not implemented; client_credentials only).
|
|
example: "https://idp.sentryagent.ai/oauth2/authorize"
|
|
token_endpoint:
|
|
type: string
|
|
format: uri
|
|
description: Token endpoint for the client_credentials grant.
|
|
example: "https://idp.sentryagent.ai/oauth2/token"
|
|
jwks_uri:
|
|
type: string
|
|
format: uri
|
|
description: JWKS endpoint for ID token verification public keys.
|
|
example: "https://idp.sentryagent.ai/.well-known/jwks.json"
|
|
response_types_supported:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: Supported response types.
|
|
example: ["token", "id_token"]
|
|
subject_types_supported:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: Supported subject types.
|
|
example: ["public"]
|
|
id_token_signing_alg_values_supported:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: Supported ID token signing algorithms.
|
|
example: ["RS256", "ES256"]
|
|
scopes_supported:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: Supported OAuth 2.0 scopes.
|
|
example: ["openid", "agents:read", "agents:write", "tokens:read", "audit:read", "admin:orgs"]
|
|
claims_supported:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: Claims that may appear in ID tokens or the agent-info response.
|
|
example: ["sub", "iss", "aud", "iat", "exp", "agent_type", "deployment_env", "organization_id", "did"]
|
|
grant_types_supported:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: Supported grant types.
|
|
example: ["client_credentials"]
|
|
|
|
JWKSKey:
|
|
type: object
|
|
description: A single JSON Web Key. Supports RSA (RS256) and EC P-256 (ES256) keys.
|
|
required:
|
|
- kid
|
|
- kty
|
|
- use
|
|
- alg
|
|
properties:
|
|
kid:
|
|
type: string
|
|
description: Key ID — matches the `kid` header in signed JWTs.
|
|
example: "key-20260328-001"
|
|
kty:
|
|
type: string
|
|
description: Key type.
|
|
enum:
|
|
- RSA
|
|
- EC
|
|
example: "RSA"
|
|
use:
|
|
type: string
|
|
description: Intended use. Always `sig` for signing keys.
|
|
example: "sig"
|
|
alg:
|
|
type: string
|
|
description: Algorithm.
|
|
enum:
|
|
- RS256
|
|
- ES256
|
|
example: "RS256"
|
|
n:
|
|
type: string
|
|
description: RSA — Base64url-encoded modulus.
|
|
example: "sI3P8XVb..."
|
|
e:
|
|
type: string
|
|
description: RSA — Base64url-encoded public exponent.
|
|
example: "AQAB"
|
|
crv:
|
|
type: string
|
|
description: EC — Curve name.
|
|
example: "P-256"
|
|
x:
|
|
type: string
|
|
description: EC — Base64url-encoded x coordinate.
|
|
example: "f83OJ3D..."
|
|
y:
|
|
type: string
|
|
description: EC — Base64url-encoded y coordinate.
|
|
example: "x_FEzRu..."
|
|
|
|
JWKSResponse:
|
|
type: object
|
|
description: JSON Web Key Set returned by `GET /.well-known/jwks.json`.
|
|
required:
|
|
- keys
|
|
properties:
|
|
keys:
|
|
type: array
|
|
description: |
|
|
Array of JSON Web Keys. Includes all non-expired keys to support
|
|
key rotation grace periods.
|
|
items:
|
|
$ref: '#/components/schemas/JWKSKey'
|
|
|
|
AgentInfoResponse:
|
|
type: object
|
|
description: |
|
|
Agent identity claims for the authenticated caller.
|
|
Analogous to the OIDC UserInfo endpoint.
|
|
required:
|
|
- sub
|
|
- agent_type
|
|
- deployment_env
|
|
- organization_id
|
|
- scope
|
|
properties:
|
|
sub:
|
|
type: string
|
|
format: uuid
|
|
description: Agent UUID (subject).
|
|
example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
|
|
agent_type:
|
|
type: string
|
|
description: Functional classification of the agent.
|
|
example: "screener"
|
|
deployment_env:
|
|
type: string
|
|
description: Target deployment environment of the agent.
|
|
example: "production"
|
|
organization_id:
|
|
type: string
|
|
format: uuid
|
|
description: Organization UUID the agent belongs to.
|
|
example: "org-1234-5678-abcd-ef01"
|
|
did:
|
|
type: string
|
|
description: W3C DID identifier for the agent, if one has been generated.
|
|
example: "did:web:api.sentryagent.ai:agents:a1b2c3d4-e5f6-7890-abcd-ef1234567890"
|
|
scope:
|
|
type: string
|
|
description: OAuth 2.0 scope associated with the Bearer token used to call this endpoint.
|
|
example: "agents:read agents:write"
|
|
|
|
ErrorResponse:
|
|
type: object
|
|
description: Standard error response envelope.
|
|
required:
|
|
- code
|
|
- message
|
|
properties:
|
|
code:
|
|
type: string
|
|
example: "UNAUTHORIZED"
|
|
message:
|
|
type: string
|
|
example: "A valid Bearer token is required to access this resource."
|
|
details:
|
|
type: object
|
|
additionalProperties: true
|
|
|
|
responses:
|
|
Unauthorized:
|
|
description: Missing or invalid Bearer token.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
example:
|
|
code: "UNAUTHORIZED"
|
|
message: "A valid Bearer token is required to access this resource."
|
|
|
|
NotFound:
|
|
description: The requested resource was not found.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
example:
|
|
code: "AGENT_NOT_FOUND"
|
|
message: "Agent with the specified ID was not found."
|
|
|
|
InternalServerError:
|
|
description: Unexpected server error.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
example:
|
|
code: "INTERNAL_SERVER_ERROR"
|
|
message: "An unexpected error occurred. Please try again later."
|
|
|
|
paths:
|
|
/.well-known/openid-configuration:
|
|
get:
|
|
operationId: getOIDCDiscoveryDocument
|
|
tags:
|
|
- OIDC Discovery
|
|
summary: OIDC Discovery Document
|
|
description: |
|
|
Returns the OpenID Connect Discovery 1.0 document for the SentryAgent.ai AgentIdP.
|
|
|
|
Consumers can fetch this document to auto-discover the token endpoint,
|
|
JWKS URI, supported scopes, and supported claims — without hard-coding URLs.
|
|
|
|
This endpoint is **unauthenticated** and publicly cacheable.
|
|
security: []
|
|
responses:
|
|
'200':
|
|
description: OIDC Discovery Document returned successfully.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/OIDCDiscoveryDocument'
|
|
example:
|
|
issuer: "https://idp.sentryagent.ai"
|
|
authorization_endpoint: "https://idp.sentryagent.ai/oauth2/authorize"
|
|
token_endpoint: "https://idp.sentryagent.ai/oauth2/token"
|
|
jwks_uri: "https://idp.sentryagent.ai/.well-known/jwks.json"
|
|
response_types_supported:
|
|
- token
|
|
- id_token
|
|
subject_types_supported:
|
|
- public
|
|
id_token_signing_alg_values_supported:
|
|
- RS256
|
|
- ES256
|
|
scopes_supported:
|
|
- openid
|
|
- agents:read
|
|
- agents:write
|
|
- tokens:read
|
|
- audit:read
|
|
- admin:orgs
|
|
claims_supported:
|
|
- sub
|
|
- iss
|
|
- aud
|
|
- iat
|
|
- exp
|
|
- agent_type
|
|
- deployment_env
|
|
- organization_id
|
|
- did
|
|
grant_types_supported:
|
|
- client_credentials
|
|
'500':
|
|
$ref: '#/components/responses/InternalServerError'
|
|
|
|
/.well-known/jwks.json:
|
|
get:
|
|
operationId: getJWKS
|
|
tags:
|
|
- OIDC Discovery
|
|
summary: JSON Web Key Set (public signing keys)
|
|
description: |
|
|
Returns the JSON Web Key Set (JWKS) containing all active public keys
|
|
used to sign ID tokens. Consumers use this to verify ID token signatures.
|
|
|
|
All non-expired keys are returned to support key rotation grace periods —
|
|
a token signed with a recently-rotated key will still verify correctly
|
|
if the old key appears in the JWKS response.
|
|
|
|
**Cache-Control:** `public, max-age=3600` — responses may be cached for up to 1 hour.
|
|
|
|
This endpoint is **unauthenticated**.
|
|
security: []
|
|
responses:
|
|
'200':
|
|
description: JWKS returned successfully.
|
|
headers:
|
|
Cache-Control:
|
|
schema:
|
|
type: string
|
|
description: Caching directive. Always `public, max-age=3600`.
|
|
example: "public, max-age=3600"
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/JWKSResponse'
|
|
example:
|
|
keys:
|
|
- kid: "key-20260328-001"
|
|
kty: "RSA"
|
|
use: "sig"
|
|
alg: "RS256"
|
|
n: "sI3P8XVb..."
|
|
e: "AQAB"
|
|
'500':
|
|
$ref: '#/components/responses/InternalServerError'
|
|
|
|
/agent-info:
|
|
get:
|
|
operationId: getAgentInfo
|
|
tags:
|
|
- Agent Info
|
|
summary: Get authenticated agent identity claims
|
|
description: |
|
|
Returns identity claims for the agent authenticated by the provided Bearer token.
|
|
Equivalent to the OIDC UserInfo endpoint — returns the agent's type,
|
|
deployment environment, organization, DID (if generated), and active scopes.
|
|
|
|
The agent UUID is read from the `sub` claim of the Bearer token.
|
|
Requires a valid Bearer JWT.
|
|
security:
|
|
- BearerAuth: []
|
|
responses:
|
|
'200':
|
|
description: Agent identity claims returned successfully.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/AgentInfoResponse'
|
|
example:
|
|
sub: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
|
|
agent_type: "screener"
|
|
deployment_env: "production"
|
|
organization_id: "org-1234-5678-abcd-ef01"
|
|
did: "did:web:api.sentryagent.ai:agents:a1b2c3d4-e5f6-7890-abcd-ef1234567890"
|
|
scope: "agents:read agents:write"
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'404':
|
|
description: The agent referenced in the token no longer exists.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
example:
|
|
code: "AGENT_NOT_FOUND"
|
|
message: "Agent with the specified ID was not found."
|
|
'500':
|
|
$ref: '#/components/responses/InternalServerError'
|