Compare commits
2 Commits
8cabc0191c
...
7441c9f298
| Author | SHA1 | Date | |
|---|---|---|---|
|
7441c9f298 | ||
|
|
d216096dfb |
@@ -37,6 +37,8 @@ The Virtual CTO runs as a SEPARATE Claude Code instance.
|
||||
|
||||
**Channel guide:**
|
||||
- `#vpe-cto-approvals` — CEO ↔ CTO communication, approvals, status reports (only channel CEO uses)
|
||||
- `#vv-cto-resolution` — Lead Validator ↔ CTO direct channel for V&V findings and resolution. CEO is NOT part of this channel unless escalated after two failed resolution rounds.
|
||||
- `#vv-findings` — Informational V&V status log (read-only reference for CEO)
|
||||
|
||||
## VIRTUAL ENGINEERING TEAM ROLES
|
||||
Claude operates as a Virtual Engineering Team — NOT as a chatbot.
|
||||
|
||||
311
VALIDATOR.md
311
VALIDATOR.md
@@ -1,52 +1,275 @@
|
||||
#!/bin/bash
|
||||
# =============================================================================
|
||||
# SentryAgent.ai — Start V&V Architect (Lead Validator)
|
||||
# =============================================================================
|
||||
# Launches an independent Claude Code instance as the Lead Validator.
|
||||
# This agent verifies the CTO's work against the PRD/OpenSpec.
|
||||
#
|
||||
# Usage:
|
||||
# ./scripts/start-validator.sh
|
||||
# =============================================================================
|
||||
# SentryAgent.ai — V&V Architect (Lead Validator)
|
||||
|
||||
set -e
|
||||
## IDENTITY & INDEPENDENCE
|
||||
|
||||
PROJECT_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
|
||||
VALIDATOR_WORKSPACE="$PROJECT_ROOT/.validator-workspace"
|
||||
VALIDATOR_PROMPT="$PROJECT_ROOT/VALIDATOR.md"
|
||||
You are the **V&V Architect (Lead Validator)** for SentryAgent.ai AgentIdP.
|
||||
|
||||
echo "=============================================="
|
||||
echo " SentryAgent.ai — Starting V&V Architect Agent"
|
||||
echo "=============================================="
|
||||
echo ""
|
||||
echo " Project: $PROJECT_ROOT"
|
||||
echo " Workspace: $VALIDATOR_WORKSPACE"
|
||||
echo " Role Config: $VALIDATOR_PROMPT"
|
||||
echo ""
|
||||
echo " The V&V Architect will:"
|
||||
echo " 1. Audit Code against OpenSpec PRD"
|
||||
echo " 2. Enforce DRY Principles"
|
||||
echo " 3. Log Issues for CTO Resolution"
|
||||
echo " 4. Maintain Local Fail-Safe Ledger"
|
||||
echo ""
|
||||
echo "=============================================="
|
||||
- **Instance ID:** `LeadValidator`
|
||||
- **Role:** Independent verification and validation — you are NOT part of the engineering team
|
||||
- **Authority:** You report findings directly to the CEO. The CTO has no authority to dismiss your findings.
|
||||
- **Mandate:** Ensure that everything the engineering team built actually matches what was specified in the PRD and OpenSpec
|
||||
- **Isolation:** Do NOT carry context from any other project or session. This is a private, independent audit session.
|
||||
|
||||
# Ensure the Validator Workspace and Local Ledger exist
|
||||
mkdir -p "$VALIDATOR_WORKSPACE/.openspec/vv_audit"
|
||||
You are a check on the system — not a builder. You never implement features, never approve architectural changes, and never take direction from the Virtual CTO. Your only job is to find gaps, deviations, and violations and formally log them.
|
||||
|
||||
# Verify the Validator Persona file exists (from Part 1 of instructions)
|
||||
if [ ! -f "$VALIDATOR_PROMPT" ]; then
|
||||
echo "ERROR: VALIDATOR.md not found at $VALIDATOR_PROMPT"
|
||||
echo "Please ensure you have created the System Instruction file."
|
||||
exit 1
|
||||
fi
|
||||
---
|
||||
|
||||
# Synchronize the latest CLAUDE.md to the validator workspace if needed
|
||||
if [ -f "$PROJECT_ROOT/CLAUDE.md" ]; then
|
||||
cp "$PROJECT_ROOT/CLAUDE.md" "$VALIDATOR_WORKSPACE/CLAUDE.md"
|
||||
fi
|
||||
## STARTUP PROTOCOL (Execute on every new session — no exceptions)
|
||||
|
||||
# Launch Claude Code as an independent Auditor
|
||||
cd "$VALIDATOR_WORKSPACE"
|
||||
exec claude --system-prompt-file "$VALIDATOR_PROMPT"
|
||||
Execute these steps in order before doing anything else:
|
||||
|
||||
### Step 1 — Read the source of truth
|
||||
Read `/home/ubuntu/vj_ai_agents_dev/sentryagent-idp/README.md` in full.
|
||||
This is the PRD. Everything the engineering team built must conform to it.
|
||||
|
||||
### Step 2 — Register on central hub
|
||||
Register as `LeadValidator` on the central hub.
|
||||
|
||||
### Step 3 — Check existing open issues
|
||||
Read all files in `/home/ubuntu/vj_ai_agents_dev/sentryagent-idp/openspec/vv_audit/` — this is your ledger.
|
||||
List any issues currently with status `OPEN` or `DISPUTED`.
|
||||
|
||||
### Step 4 — Check #vv-findings channel
|
||||
Check the `#vv-findings` channel on the central hub for any recent messages from the CTO regarding issue resolution or disputes.
|
||||
|
||||
### Step 5 — Report readiness to CEO
|
||||
Post a status message to `#vv-findings` channel:
|
||||
- How many open/disputed issues exist
|
||||
- Whether you are performing a fresh audit or continuing an existing one
|
||||
- What you plan to audit this session
|
||||
|
||||
### Step 6 — Begin audit
|
||||
Execute the audit methodology below.
|
||||
|
||||
---
|
||||
|
||||
## AUDIT METHODOLOGY
|
||||
|
||||
### Phase A — OpenSpec Completeness Check
|
||||
|
||||
For every archived OpenSpec change, verify the tasks were fully implemented.
|
||||
|
||||
**Archived changes location:** `/home/ubuntu/vj_ai_agents_dev/sentryagent-idp/openspec/changes/archive/`
|
||||
|
||||
For each archived change:
|
||||
1. Read its `tasks.md`
|
||||
2. All tasks marked `[x]` — verify the corresponding code actually exists and matches the task description
|
||||
3. Any task marked `[ ]` — this is a BLOCKER finding (incomplete implementation)
|
||||
|
||||
### Phase B — API Surface Audit
|
||||
|
||||
Verify every API endpoint has a corresponding OpenAPI spec.
|
||||
|
||||
**OpenAPI specs location:** `/home/ubuntu/vj_ai_agents_dev/sentryagent-idp/docs/openapi/`
|
||||
|
||||
For every route registered in `src/routes/` and `src/app.ts`:
|
||||
1. Confirm there is an OpenAPI spec entry covering that endpoint
|
||||
2. Confirm the spec matches the implementation (method, path, request schema, response schemas, auth requirement)
|
||||
3. Any endpoint without a spec → BLOCKER
|
||||
4. Any endpoint where spec and implementation diverge → MAJOR
|
||||
|
||||
### Phase C — TypeScript Standards Audit
|
||||
|
||||
Read source files in `src/` and verify:
|
||||
1. No `any` types used anywhere — search for `: any`, `as any`, `<any>`
|
||||
2. All public classes and methods have JSDoc comments
|
||||
3. `tsconfig.json` has `"strict": true` and all strict flags enabled
|
||||
4. Custom error hierarchy: all errors extend `SentryAgentError`
|
||||
|
||||
Violations:
|
||||
- `any` type usage → MAJOR per occurrence
|
||||
- Missing JSDoc on public methods → MINOR per file
|
||||
- Disabled strict flags → BLOCKER
|
||||
|
||||
### Phase D — DRY Principle Audit
|
||||
|
||||
Search for code duplication:
|
||||
1. Look for identical or near-identical logic blocks across files
|
||||
2. Check that all crypto operations live in `src/utils/crypto.ts`
|
||||
3. Check that all JWT operations live in `src/utils/jwt.ts`
|
||||
4. Check that all validation logic lives in `src/utils/validators.ts`
|
||||
5. Check that all error classes live in `src/utils/errors.ts` or `src/errors/`
|
||||
6. Check that no controller directly accesses the database (must go through services)
|
||||
|
||||
Violations: DRY violation → MAJOR (BLOCKER if in a critical path)
|
||||
|
||||
### Phase E — SOLID Principles Audit
|
||||
|
||||
Spot-check key services:
|
||||
1. `AgentService` — does agent CRUD only (no token logic, no audit logic)
|
||||
2. `OAuth2Service` — does token issuance only (no agent CRUD, no billing)
|
||||
3. `CredentialService` — does credential management only
|
||||
4. `AuditService` — does audit logging only
|
||||
5. All services use constructor injection (no direct `new Dependency()` inside business logic)
|
||||
6. Services depend on interfaces/abstractions, not concrete implementations
|
||||
|
||||
Violations: SRP violation → MAJOR
|
||||
|
||||
### Phase F — Test Coverage Audit
|
||||
|
||||
Check test completeness:
|
||||
1. Every service in `src/services/` has a corresponding test in `tests/`
|
||||
2. Every API route has integration tests
|
||||
3. Run `npm test -- --coverage` and check that overall coverage is >80%
|
||||
4. Check that edge cases are covered: null inputs, invalid inputs, auth failures, rate limits
|
||||
|
||||
Violations:
|
||||
- Coverage <80% → BLOCKER
|
||||
- Missing integration test for an endpoint → MAJOR
|
||||
- Missing edge case tests → MINOR
|
||||
|
||||
### Phase G — AGNTCY Compliance Audit
|
||||
|
||||
Verify AGNTCY alignment (per PRD Section 3.1 and Phase 3 scope):
|
||||
1. Agents have unique, immutable IDs
|
||||
2. Authentication uses OAuth 2.0 Client Credentials flow
|
||||
3. Authorization uses scope-based access control
|
||||
4. Audit logs are immutable
|
||||
5. Agent lifecycle operations (provision, rotate, revoke) are fully implemented
|
||||
6. W3C DID support implemented (Phase 3 deliverable)
|
||||
7. AGNTCY conformance tests pass (see `tests/agntcy-conformance/`)
|
||||
|
||||
Violations: AGNTCY deviation → BLOCKER
|
||||
|
||||
### Phase H — Security Audit
|
||||
|
||||
Scan for OWASP Top 10 vulnerabilities:
|
||||
1. SQL injection — all DB queries use parameterized statements
|
||||
2. Authentication bypass — all protected routes have auth middleware
|
||||
3. Sensitive data exposure — no secrets in logs or error responses
|
||||
4. Broken access control — tenant isolation enforced on all queries
|
||||
5. Security headers — helmet middleware applied
|
||||
6. Rate limiting — enforced on token endpoints
|
||||
|
||||
Violations: Security finding → BLOCKER
|
||||
|
||||
---
|
||||
|
||||
## ISSUE FORMAT
|
||||
|
||||
Every finding is written as a file in the shared ledger:
|
||||
`/home/ubuntu/vj_ai_agents_dev/sentryagent-idp/openspec/vv_audit/`
|
||||
|
||||
**Filename:** `VV_ISSUE_<NNN>.md` (zero-padded, e.g., `VV_ISSUE_001.md`)
|
||||
|
||||
**File template:**
|
||||
```markdown
|
||||
# VV_ISSUE_<NNN> — <Short title>
|
||||
|
||||
**Status:** OPEN | RESOLVED | DISPUTED
|
||||
**Severity:** BLOCKER | MAJOR | MINOR
|
||||
**Category:** SPEC_DEVIATION | DRY_VIOLATION | TYPE_VIOLATION | SOLID_VIOLATION | TEST_GAP | SECURITY | AGNTCY | DOCS
|
||||
**Logged by:** LeadValidator
|
||||
**Date:** <ISO date>
|
||||
**Audit phase:** Phase A–H label
|
||||
|
||||
## Finding
|
||||
|
||||
<Clear description of what is wrong>
|
||||
|
||||
## Evidence
|
||||
|
||||
<File path(s) and line numbers where the violation exists>
|
||||
|
||||
## Required Action
|
||||
|
||||
<What must be done to resolve this finding>
|
||||
|
||||
## CTO Response
|
||||
|
||||
<Leave blank — CTO fills this in>
|
||||
|
||||
## Resolution
|
||||
|
||||
<Leave blank — filled on resolution>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## SEVERITY DEFINITIONS
|
||||
|
||||
| Severity | Definition | Who can close |
|
||||
|----------|-----------|---------------|
|
||||
| **BLOCKER** | Prevents release. PRD requirement missing, security vulnerability, <80% test coverage, spec-implementation mismatch on a core feature | CTO resolves, Validator confirms. CEO notified only if CTO and Validator cannot agree. |
|
||||
| **MAJOR** | Significant deviation from standards. `any` types, DRY violation, missing integration test, SOLID violation | CTO resolves, Validator confirms |
|
||||
| **MINOR** | Standards improvement. Missing JSDoc, minor duplication, cosmetic spec gap | CTO resolves, no confirmation needed |
|
||||
|
||||
---
|
||||
|
||||
## COMMUNICATION PROTOCOL
|
||||
|
||||
### Primary channel: #vv-cto-resolution (Lead Validator ↔ CTO)
|
||||
All findings — routine, MAJOR, and BLOCKER — go to `#vv-cto-resolution` first.
|
||||
The CTO is responsible for reviewing and resolving all findings with the engineering team.
|
||||
The Lead Validator confirms resolution in the same channel.
|
||||
|
||||
**Do NOT post findings to `#vpe-cto-approvals` (CEO channel) unless escalation is required (see below).**
|
||||
|
||||
### Routine findings
|
||||
After each audit phase, post a summary to `#vv-cto-resolution`:
|
||||
- Phase completed
|
||||
- Number of issues found (BLOCKER / MAJOR / MINOR)
|
||||
- Issue file names
|
||||
|
||||
### BLOCKER findings
|
||||
Post immediately to `#vv-cto-resolution` with full finding detail.
|
||||
The CTO must acknowledge and provide a resolution plan within the same session.
|
||||
**CEO is NOT notified of BLOCKERs by default — the CTO owns resolution.**
|
||||
|
||||
### Disputes
|
||||
If the CTO marks an issue as `DISPUTED`:
|
||||
1. Read the CTO's technical justification in the issue file
|
||||
2. Evaluate whether the justification is valid against the PRD
|
||||
3. If you accept the justification → change status to `RESOLVED`, note reason in `#vv-cto-resolution`
|
||||
4. If you reject the justification → change status back to `OPEN`, add your counter-argument in `#vv-cto-resolution`, and attempt a second round of resolution with the CTO
|
||||
5. **Only if two rounds of resolution fail** → escalate to `#vpe-cto-approvals` for CEO decision, with a clear summary of both positions
|
||||
|
||||
### CEO escalation (last resort only)
|
||||
Escalate to `#vpe-cto-approvals` ONLY when:
|
||||
- CTO and Lead Validator have attempted resolution and remain deadlocked after two rounds
|
||||
- Include: issue ID, CTO's position, Lead Validator's position, and why they are irreconcilable
|
||||
|
||||
### Session close
|
||||
When you have completed your audit session, post a final summary to `#vv-cto-resolution`:
|
||||
- Total issues logged this session
|
||||
- Breakdown by severity
|
||||
- Overall V&V status: PASS (0 BLOCKERs) | BLOCKED (≥1 BLOCKER open)
|
||||
|
||||
Also post a brief one-line status to `#vv-findings` for informational tracking.
|
||||
|
||||
---
|
||||
|
||||
## AUDIT LEDGER INDEX
|
||||
|
||||
After each session, update `/home/ubuntu/vj_ai_agents_dev/sentryagent-idp/openspec/vv_audit/LEDGER.md`:
|
||||
- Total issues logged to date
|
||||
- Open / Resolved / Disputed counts
|
||||
- Date of last audit
|
||||
- Overall release gate status
|
||||
|
||||
---
|
||||
|
||||
## INDEPENDENCE PRINCIPLES
|
||||
|
||||
1. **You do not take orders from the CTO.** The CTO can respond to your findings in the issue file. Only the CEO can instruct you to drop a BLOCKER.
|
||||
2. **You do not implement fixes.** If you find a problem, you log it. The CTO's team fixes it.
|
||||
3. **You do not negotiate severity.** Severity is set by the PRD requirements and these definitions. If the CTO disagrees, it becomes DISPUTED and goes to CEO.
|
||||
4. **You do not skip phases.** Every audit session runs all phases, or explicitly documents why a phase was skipped.
|
||||
5. **You are not adversarial.** Your goal is product quality, not finding fault. A clean audit is a success.
|
||||
|
||||
---
|
||||
|
||||
## STANDARDS REFERENCE (from PRD Section 6)
|
||||
|
||||
| Standard | Requirement |
|
||||
|----------|------------|
|
||||
| TypeScript | Strict mode, zero `any` types |
|
||||
| DRY | Zero code duplication, logic lives in exactly one place |
|
||||
| SOLID | Single responsibility per service, constructor injection |
|
||||
| OpenAPI | Spec exists BEFORE implementation, spec matches implementation |
|
||||
| Tests | >80% coverage, all endpoints integration-tested |
|
||||
| JSDoc | All public classes and methods documented |
|
||||
| Errors | All errors typed, extend SentryAgentError hierarchy |
|
||||
| Security | No OWASP Top 10 vulnerabilities |
|
||||
| AGNTCY | Full compliance with Linux Foundation agent identity standard |
|
||||
| Performance | Token endpoints <100ms, all others <200ms |
|
||||
|
||||
428
docs/openapi/analytics.yaml
Normal file
428
docs/openapi/analytics.yaml
Normal file
@@ -0,0 +1,428 @@
|
||||
openapi: "3.0.3"
|
||||
|
||||
info:
|
||||
title: SentryAgent.ai — Tenant Analytics
|
||||
version: 1.0.0
|
||||
description: |
|
||||
Tenant analytics endpoints for the SentryAgent.ai AgentIdP platform.
|
||||
|
||||
Provides usage trend data, agent activity heatmaps, and per-agent usage summaries
|
||||
scoped to the authenticated organization (tenant).
|
||||
|
||||
**All endpoints require a valid Bearer JWT.** Data is always scoped to the
|
||||
organization identified by the `organization_id` claim in the token.
|
||||
|
||||
**Feature flag:** When `ANALYTICS_ENABLED=false` these routes return 404.
|
||||
|
||||
**Available endpoints:**
|
||||
- `GET /analytics/tokens` — Daily token issuance trend (last N days)
|
||||
- `GET /analytics/agents/activity` — Agent activity heatmap by day-of-week + hour
|
||||
- `GET /analytics/agents` — Per-agent usage summary for the current month
|
||||
|
||||
servers:
|
||||
- url: http://localhost:3000/api/v1
|
||||
description: Local development server
|
||||
- url: https://api.sentryagent.ai/v1
|
||||
description: Production server
|
||||
|
||||
tags:
|
||||
- name: Analytics
|
||||
description: Tenant-scoped usage analytics and reporting
|
||||
|
||||
components:
|
||||
securitySchemes:
|
||||
BearerAuth:
|
||||
type: http
|
||||
scheme: bearer
|
||||
bearerFormat: JWT
|
||||
description: |
|
||||
JWT access token obtained via `POST /token`.
|
||||
Include as `Authorization: Bearer <token>`.
|
||||
|
||||
schemas:
|
||||
TokenTrendDataPoint:
|
||||
type: object
|
||||
description: Token issuance count for a single calendar day.
|
||||
required:
|
||||
- date
|
||||
- count
|
||||
properties:
|
||||
date:
|
||||
type: string
|
||||
format: date
|
||||
description: Calendar date (UTC) in `YYYY-MM-DD` format.
|
||||
example: "2026-04-01"
|
||||
count:
|
||||
type: integer
|
||||
description: Number of OAuth 2.0 tokens issued on this date.
|
||||
minimum: 0
|
||||
example: 842
|
||||
|
||||
TokenTrendResponse:
|
||||
type: object
|
||||
description: Daily token issuance trend for the last N days.
|
||||
required:
|
||||
- organizationId
|
||||
- days
|
||||
- data
|
||||
properties:
|
||||
organizationId:
|
||||
type: string
|
||||
format: uuid
|
||||
description: Organization the analytics data belongs to.
|
||||
example: "org-1234-5678-abcd-ef01"
|
||||
days:
|
||||
type: integer
|
||||
description: Number of days included in the trend window.
|
||||
example: 30
|
||||
data:
|
||||
type: array
|
||||
description: |
|
||||
Array of daily data points ordered by date ascending.
|
||||
Days with no token issuances have `count: 0`.
|
||||
items:
|
||||
$ref: '#/components/schemas/TokenTrendDataPoint'
|
||||
|
||||
ActivityHeatmapCell:
|
||||
type: object
|
||||
description: |
|
||||
A single cell in the agent activity heatmap, identified by
|
||||
day-of-week (0 = Sunday) and hour of day (0–23 UTC).
|
||||
required:
|
||||
- dayOfWeek
|
||||
- hour
|
||||
- count
|
||||
properties:
|
||||
dayOfWeek:
|
||||
type: integer
|
||||
description: Day of week (0 = Sunday, 6 = Saturday).
|
||||
minimum: 0
|
||||
maximum: 6
|
||||
example: 1
|
||||
hour:
|
||||
type: integer
|
||||
description: Hour of day in UTC (0–23).
|
||||
minimum: 0
|
||||
maximum: 23
|
||||
example: 14
|
||||
count:
|
||||
type: integer
|
||||
description: Number of token issuances or API calls in this slot.
|
||||
minimum: 0
|
||||
example: 217
|
||||
|
||||
AgentActivityResponse:
|
||||
type: object
|
||||
description: |
|
||||
Agent activity heatmap — shows when agents are most active
|
||||
by day-of-week and hour (UTC). Useful for identifying peak usage patterns.
|
||||
required:
|
||||
- organizationId
|
||||
- data
|
||||
properties:
|
||||
organizationId:
|
||||
type: string
|
||||
format: uuid
|
||||
example: "org-1234-5678-abcd-ef01"
|
||||
data:
|
||||
type: array
|
||||
description: |
|
||||
Array of heatmap cells. Contains only cells with `count > 0`.
|
||||
Maximum 168 cells (7 days × 24 hours).
|
||||
items:
|
||||
$ref: '#/components/schemas/ActivityHeatmapCell'
|
||||
|
||||
AgentUsageSummary:
|
||||
type: object
|
||||
description: Per-agent usage summary for the current calendar month.
|
||||
required:
|
||||
- agentId
|
||||
- tokensIssued
|
||||
- apiCalls
|
||||
properties:
|
||||
agentId:
|
||||
type: string
|
||||
format: uuid
|
||||
description: UUID of the agent.
|
||||
example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
|
||||
agentEmail:
|
||||
type: string
|
||||
format: email
|
||||
description: Email identifier of the agent.
|
||||
example: "screener-001@sentryagent.ai"
|
||||
tokensIssued:
|
||||
type: integer
|
||||
description: Number of tokens issued for this agent in the current month.
|
||||
minimum: 0
|
||||
example: 1204
|
||||
apiCalls:
|
||||
type: integer
|
||||
description: Total API calls made by this agent in the current month.
|
||||
minimum: 0
|
||||
example: 5432
|
||||
lastActiveAt:
|
||||
type: string
|
||||
format: date-time
|
||||
nullable: true
|
||||
description: Timestamp of the agent's last API activity. Null if no activity this month.
|
||||
example: "2026-04-07T08:45:00.000Z"
|
||||
|
||||
AgentSummaryResponse:
|
||||
type: object
|
||||
description: Per-agent usage summary for the current month, across all agents in the organization.
|
||||
required:
|
||||
- organizationId
|
||||
- month
|
||||
- data
|
||||
properties:
|
||||
organizationId:
|
||||
type: string
|
||||
format: uuid
|
||||
example: "org-1234-5678-abcd-ef01"
|
||||
month:
|
||||
type: string
|
||||
description: Current billing month in `YYYY-MM` format.
|
||||
example: "2026-04"
|
||||
data:
|
||||
type: array
|
||||
description: Per-agent usage summaries, ordered by `tokensIssued` descending.
|
||||
items:
|
||||
$ref: '#/components/schemas/AgentUsageSummary'
|
||||
|
||||
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."
|
||||
|
||||
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."
|
||||
|
||||
security:
|
||||
- BearerAuth: []
|
||||
|
||||
paths:
|
||||
/analytics/tokens:
|
||||
get:
|
||||
operationId: getTokenTrend
|
||||
tags:
|
||||
- Analytics
|
||||
summary: Get daily token issuance trend
|
||||
description: |
|
||||
Returns a daily breakdown of OAuth 2.0 token issuances for the authenticated
|
||||
organization over the last N days.
|
||||
|
||||
The `days` parameter controls the window size (default: 30, max: 90).
|
||||
Days with no token activity are included with `count: 0`.
|
||||
|
||||
Data is scoped to the `organization_id` from the Bearer token.
|
||||
parameters:
|
||||
- name: days
|
||||
in: query
|
||||
required: false
|
||||
description: Number of days to include in the trend window. Default: 30, max: 90.
|
||||
schema:
|
||||
type: integer
|
||||
minimum: 1
|
||||
maximum: 90
|
||||
default: 30
|
||||
example: 30
|
||||
responses:
|
||||
'200':
|
||||
description: Token trend data returned successfully.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/TokenTrendResponse'
|
||||
example:
|
||||
organizationId: "org-1234-5678-abcd-ef01"
|
||||
days: 7
|
||||
data:
|
||||
- date: "2026-04-01"
|
||||
count: 842
|
||||
- date: "2026-04-02"
|
||||
count: 967
|
||||
- date: "2026-04-03"
|
||||
count: 0
|
||||
- date: "2026-04-04"
|
||||
count: 1201
|
||||
- date: "2026-04-05"
|
||||
count: 1087
|
||||
- date: "2026-04-06"
|
||||
count: 953
|
||||
- date: "2026-04-07"
|
||||
count: 412
|
||||
'400':
|
||||
description: Invalid `days` parameter.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
examples:
|
||||
tooLarge:
|
||||
summary: Exceeds maximum
|
||||
value:
|
||||
code: "VALIDATION_ERROR"
|
||||
message: "Query parameter `days` must not exceed 90."
|
||||
details:
|
||||
field: "days"
|
||||
max: 90
|
||||
provided: 120
|
||||
invalid:
|
||||
summary: Non-positive integer
|
||||
value:
|
||||
code: "VALIDATION_ERROR"
|
||||
message: "Query parameter `days` must be a positive integer."
|
||||
details:
|
||||
field: "days"
|
||||
'401':
|
||||
$ref: '#/components/responses/Unauthorized'
|
||||
'404':
|
||||
description: Analytics feature is not enabled on this instance.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
example:
|
||||
code: "NOT_FOUND"
|
||||
message: "Analytics is not enabled on this instance."
|
||||
'500':
|
||||
$ref: '#/components/responses/InternalServerError'
|
||||
|
||||
/analytics/agents/activity:
|
||||
get:
|
||||
operationId: getAgentActivity
|
||||
tags:
|
||||
- Analytics
|
||||
summary: Get agent activity heatmap
|
||||
description: |
|
||||
Returns agent activity aggregated by day-of-week (0 = Sunday) and hour of day (UTC).
|
||||
|
||||
The heatmap shows when agents in the organization are most active,
|
||||
based on token issuances and API calls. Only cells with `count > 0` are returned.
|
||||
|
||||
Data is scoped to the `organization_id` from the Bearer token.
|
||||
The heatmap covers the last 90 days of activity.
|
||||
responses:
|
||||
'200':
|
||||
description: Agent activity heatmap returned successfully.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/AgentActivityResponse'
|
||||
example:
|
||||
organizationId: "org-1234-5678-abcd-ef01"
|
||||
data:
|
||||
- dayOfWeek: 1
|
||||
hour: 9
|
||||
count: 342
|
||||
- dayOfWeek: 1
|
||||
hour: 14
|
||||
count: 217
|
||||
- dayOfWeek: 2
|
||||
hour: 10
|
||||
count: 189
|
||||
- dayOfWeek: 3
|
||||
hour: 11
|
||||
count: 405
|
||||
- dayOfWeek: 4
|
||||
hour: 14
|
||||
count: 278
|
||||
- dayOfWeek: 5
|
||||
hour: 9
|
||||
count: 121
|
||||
'401':
|
||||
$ref: '#/components/responses/Unauthorized'
|
||||
'404':
|
||||
description: Analytics feature is not enabled on this instance.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
example:
|
||||
code: "NOT_FOUND"
|
||||
message: "Analytics is not enabled on this instance."
|
||||
'500':
|
||||
$ref: '#/components/responses/InternalServerError'
|
||||
|
||||
/analytics/agents:
|
||||
get:
|
||||
operationId: getAgentSummary
|
||||
tags:
|
||||
- Analytics
|
||||
summary: Get per-agent usage summary
|
||||
description: |
|
||||
Returns per-agent token issuance counts and API call totals for the
|
||||
current calendar month, across all agents in the authenticated organization.
|
||||
|
||||
Results are ordered by `tokensIssued` descending (most active agents first).
|
||||
|
||||
Data is scoped to the `organization_id` from the Bearer token.
|
||||
responses:
|
||||
'200':
|
||||
description: Per-agent usage summary returned successfully.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/AgentSummaryResponse'
|
||||
example:
|
||||
organizationId: "org-1234-5678-abcd-ef01"
|
||||
month: "2026-04"
|
||||
data:
|
||||
- agentId: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
|
||||
agentEmail: "screener-001@sentryagent.ai"
|
||||
tokensIssued: 1204
|
||||
apiCalls: 5432
|
||||
lastActiveAt: "2026-04-07T08:45:00.000Z"
|
||||
- agentId: "b2c3d4e5-f6a7-8901-bcde-f12345678901"
|
||||
agentEmail: "classifier-002@sentryagent.ai"
|
||||
tokensIssued: 876
|
||||
apiCalls: 3120
|
||||
lastActiveAt: "2026-04-06T14:30:00.000Z"
|
||||
- agentId: "c3d4e5f6-a7b8-9012-cdef-123456789012"
|
||||
agentEmail: "router-003@sentryagent.ai"
|
||||
tokensIssued: 0
|
||||
apiCalls: 0
|
||||
lastActiveAt: null
|
||||
'401':
|
||||
$ref: '#/components/responses/Unauthorized'
|
||||
'404':
|
||||
description: Analytics feature is not enabled on this instance.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
example:
|
||||
code: "NOT_FOUND"
|
||||
message: "Analytics is not enabled on this instance."
|
||||
'500':
|
||||
$ref: '#/components/responses/InternalServerError'
|
||||
355
docs/openapi/billing.yaml
Normal file
355
docs/openapi/billing.yaml
Normal file
@@ -0,0 +1,355 @@
|
||||
openapi: "3.0.3"
|
||||
|
||||
info:
|
||||
title: SentryAgent.ai — Billing & Usage Metering
|
||||
version: 1.0.0
|
||||
description: |
|
||||
Billing and usage metering endpoints for the SentryAgent.ai AgentIdP platform.
|
||||
|
||||
Integrates with **Stripe** for subscription and payment management.
|
||||
|
||||
**Authenticated endpoints** (require Bearer JWT):
|
||||
- `POST /billing/checkout` — Create a Stripe Checkout Session for plan upgrades
|
||||
- `GET /billing/usage` — Retrieve today's usage summary
|
||||
|
||||
**Unauthenticated endpoint** (Stripe webhook receiver):
|
||||
- `POST /billing/webhook` — Receives Stripe webhook events (raw body + signature verification)
|
||||
|
||||
**Important:** The `/billing/webhook` endpoint uses `express.raw()` middleware
|
||||
to receive the raw request body as a Buffer. Do not apply `express.json()` to this route.
|
||||
The `Stripe-Signature` header is required for all webhook deliveries.
|
||||
|
||||
servers:
|
||||
- url: http://localhost:3000/api/v1
|
||||
description: Local development server
|
||||
- url: https://api.sentryagent.ai/v1
|
||||
description: Production server
|
||||
|
||||
tags:
|
||||
- name: Billing Checkout
|
||||
description: Stripe Checkout Session management
|
||||
- name: Billing Webhook
|
||||
description: Stripe webhook event receiver (unauthenticated)
|
||||
- name: Usage
|
||||
description: Usage metering and reporting
|
||||
|
||||
components:
|
||||
securitySchemes:
|
||||
BearerAuth:
|
||||
type: http
|
||||
scheme: bearer
|
||||
bearerFormat: JWT
|
||||
description: |
|
||||
JWT access token obtained via `POST /token`.
|
||||
Include as `Authorization: Bearer <token>`.
|
||||
|
||||
schemas:
|
||||
CheckoutRequest:
|
||||
type: object
|
||||
description: |
|
||||
Optional request body for creating a Stripe Checkout Session.
|
||||
When `successUrl` or `cancelUrl` are omitted, the platform generates
|
||||
default redirect URLs pointing to the dashboard.
|
||||
properties:
|
||||
successUrl:
|
||||
type: string
|
||||
format: uri
|
||||
description: URL to redirect to after successful payment.
|
||||
example: "https://my-app.example.com/dashboard?billing=success"
|
||||
cancelUrl:
|
||||
type: string
|
||||
format: uri
|
||||
description: URL to redirect to if the user cancels checkout.
|
||||
example: "https://my-app.example.com/dashboard?billing=cancel"
|
||||
|
||||
CheckoutResponse:
|
||||
type: object
|
||||
description: Stripe Checkout Session URL to redirect the user to.
|
||||
required:
|
||||
- checkoutUrl
|
||||
properties:
|
||||
checkoutUrl:
|
||||
type: string
|
||||
format: uri
|
||||
description: |
|
||||
Stripe-hosted Checkout page URL. Redirect the authenticated user
|
||||
to this URL to complete payment.
|
||||
example: "https://checkout.stripe.com/pay/cs_test_abcdef1234567890"
|
||||
|
||||
UsageSummary:
|
||||
type: object
|
||||
description: |
|
||||
Today's usage summary for the authenticated organization.
|
||||
Counters reset at UTC midnight.
|
||||
required:
|
||||
- organizationId
|
||||
- date
|
||||
- tokensIssued
|
||||
- agentsRegistered
|
||||
- credentialsGenerated
|
||||
properties:
|
||||
organizationId:
|
||||
type: string
|
||||
format: uuid
|
||||
description: Organization the usage data belongs to.
|
||||
example: "org-1234-5678-abcd-ef01"
|
||||
date:
|
||||
type: string
|
||||
format: date
|
||||
description: The calendar date (UTC) this summary covers.
|
||||
example: "2026-04-07"
|
||||
tokensIssued:
|
||||
type: integer
|
||||
description: Number of OAuth 2.0 tokens issued today.
|
||||
minimum: 0
|
||||
example: 4201
|
||||
agentsRegistered:
|
||||
type: integer
|
||||
description: Number of new agents registered today.
|
||||
minimum: 0
|
||||
example: 3
|
||||
credentialsGenerated:
|
||||
type: integer
|
||||
description: Number of new agent credentials generated today.
|
||||
minimum: 0
|
||||
example: 5
|
||||
apiCallsTotal:
|
||||
type: integer
|
||||
description: Total API calls across all endpoints today.
|
||||
minimum: 0
|
||||
example: 12450
|
||||
|
||||
StripeWebhookResponse:
|
||||
type: object
|
||||
description: Acknowledgement response for a received Stripe webhook event.
|
||||
required:
|
||||
- received
|
||||
properties:
|
||||
received:
|
||||
type: boolean
|
||||
description: Always `true` when the webhook was processed successfully.
|
||||
example: true
|
||||
|
||||
ErrorResponse:
|
||||
type: object
|
||||
description: Standard error response envelope.
|
||||
required:
|
||||
- code
|
||||
- message
|
||||
properties:
|
||||
code:
|
||||
type: string
|
||||
example: "VALIDATION_ERROR"
|
||||
message:
|
||||
type: string
|
||||
example: "Missing Stripe-Signature header."
|
||||
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."
|
||||
|
||||
Forbidden:
|
||||
description: Valid token but insufficient permissions.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
example:
|
||||
code: "FORBIDDEN"
|
||||
message: "You do not have permission to perform this action."
|
||||
|
||||
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:
|
||||
/billing/checkout:
|
||||
post:
|
||||
operationId: createBillingCheckoutSession
|
||||
tags:
|
||||
- Billing Checkout
|
||||
summary: Create a Stripe Checkout Session
|
||||
description: |
|
||||
Creates a Stripe Checkout Session for the authenticated organization
|
||||
to upgrade their subscription plan.
|
||||
|
||||
The organization ID is read from the `organization_id` claim in the
|
||||
Bearer JWT — the caller does not need to provide it in the request body.
|
||||
|
||||
The `checkoutUrl` in the response is a Stripe-hosted checkout page.
|
||||
Redirect the authenticated user to this URL to complete payment.
|
||||
|
||||
Requires a valid Bearer JWT. The `organization_id` claim must be present in the token.
|
||||
security:
|
||||
- BearerAuth: []
|
||||
requestBody:
|
||||
required: false
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/CheckoutRequest'
|
||||
example:
|
||||
successUrl: "https://my-app.example.com/dashboard?billing=success"
|
||||
cancelUrl: "https://my-app.example.com/dashboard?billing=cancel"
|
||||
responses:
|
||||
'201':
|
||||
description: Stripe Checkout Session created successfully.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/CheckoutResponse'
|
||||
example:
|
||||
checkoutUrl: "https://checkout.stripe.com/pay/cs_test_abcdef1234567890"
|
||||
'400':
|
||||
description: Validation error — organization_id missing from token.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
example:
|
||||
code: "VALIDATION_ERROR"
|
||||
message: "organization_id is required in token."
|
||||
'401':
|
||||
$ref: '#/components/responses/Unauthorized'
|
||||
'403':
|
||||
$ref: '#/components/responses/Forbidden'
|
||||
'500':
|
||||
description: Unexpected error or Stripe API error.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
example:
|
||||
code: "STRIPE_ERROR"
|
||||
message: "Failed to create Stripe Checkout Session. Please try again."
|
||||
|
||||
/billing/webhook:
|
||||
post:
|
||||
operationId: handleStripeWebhook
|
||||
tags:
|
||||
- Billing Webhook
|
||||
summary: Receive Stripe webhook events
|
||||
description: |
|
||||
Receives webhook events from Stripe's delivery system. This endpoint is
|
||||
**unauthenticated** — authentication is provided by Stripe's HMAC signature
|
||||
in the `Stripe-Signature` header.
|
||||
|
||||
**Body format:** The request body MUST be the raw JSON payload as sent by
|
||||
Stripe (not parsed JSON). The `Content-Type` is `application/json` but
|
||||
the body is read as a raw `Buffer` for signature verification.
|
||||
|
||||
**Signature verification:** The `Stripe-Signature` header is required.
|
||||
If absent or invalid, the request is rejected with `400`.
|
||||
|
||||
**Supported events processed:**
|
||||
- `checkout.session.completed` — Activates subscription after payment
|
||||
- `customer.subscription.deleted` — Downgrades plan on cancellation
|
||||
- `invoice.payment_failed` — Handles failed renewals
|
||||
security: []
|
||||
parameters:
|
||||
- name: Stripe-Signature
|
||||
in: header
|
||||
required: true
|
||||
description: |
|
||||
HMAC signature from Stripe for payload verification.
|
||||
Format: `t=<timestamp>,v1=<signature>,...`
|
||||
schema:
|
||||
type: string
|
||||
example: "t=1492774577,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a05bd412fbc2a2bzo..."
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
description: Raw Stripe event payload (read as Buffer internally).
|
||||
additionalProperties: true
|
||||
example:
|
||||
id: "evt_1234567890"
|
||||
object: "event"
|
||||
type: "checkout.session.completed"
|
||||
data:
|
||||
object:
|
||||
id: "cs_test_abcdef1234567890"
|
||||
customer: "cus_abc123"
|
||||
responses:
|
||||
'200':
|
||||
description: Webhook event received and processed successfully.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/StripeWebhookResponse'
|
||||
example:
|
||||
received: true
|
||||
'400':
|
||||
description: Missing or invalid Stripe-Signature header, or malformed payload.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
examples:
|
||||
missingSignature:
|
||||
summary: Missing Stripe-Signature header
|
||||
value:
|
||||
code: "VALIDATION_ERROR"
|
||||
message: "Missing Stripe-Signature header."
|
||||
invalidSignature:
|
||||
summary: Signature verification failed
|
||||
value:
|
||||
code: "STRIPE_SIGNATURE_INVALID"
|
||||
message: "Webhook signature verification failed."
|
||||
'500':
|
||||
$ref: '#/components/responses/InternalServerError'
|
||||
|
||||
/billing/usage:
|
||||
get:
|
||||
operationId: getBillingUsage
|
||||
tags:
|
||||
- Usage
|
||||
summary: Get today's usage summary
|
||||
description: |
|
||||
Returns the usage summary for the authenticated organization
|
||||
for the current calendar day (UTC).
|
||||
|
||||
Usage counters reset at UTC midnight.
|
||||
The `organization_id` claim is read from the Bearer JWT.
|
||||
|
||||
Requires a valid Bearer JWT.
|
||||
security:
|
||||
- BearerAuth: []
|
||||
responses:
|
||||
'200':
|
||||
description: Usage summary returned successfully.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/UsageSummary'
|
||||
example:
|
||||
organizationId: "org-1234-5678-abcd-ef01"
|
||||
date: "2026-04-07"
|
||||
tokensIssued: 4201
|
||||
agentsRegistered: 3
|
||||
credentialsGenerated: 5
|
||||
apiCallsTotal: 12450
|
||||
'401':
|
||||
$ref: '#/components/responses/Unauthorized'
|
||||
'403':
|
||||
$ref: '#/components/responses/Forbidden'
|
||||
'500':
|
||||
$ref: '#/components/responses/InternalServerError'
|
||||
480
docs/openapi/delegation.yaml
Normal file
480
docs/openapi/delegation.yaml
Normal file
@@ -0,0 +1,480 @@
|
||||
openapi: "3.0.3"
|
||||
|
||||
info:
|
||||
title: SentryAgent.ai — A2A Delegation (Agent-to-Agent)
|
||||
version: 1.0.0
|
||||
description: |
|
||||
Agent-to-Agent (A2A) delegation endpoints for the SentryAgent.ai AgentIdP platform.
|
||||
|
||||
The delegation subsystem enables an authenticated agent (the *delegator*) to grant
|
||||
a subset of its own scopes to another agent (the *delegatee*) for a limited time.
|
||||
This creates a cryptographically-signed delegation chain, suitable for multi-agent
|
||||
orchestration patterns.
|
||||
|
||||
**All endpoints require a valid Bearer JWT.**
|
||||
|
||||
**Feature flag:** When `A2A_ENABLED=false` these routes are not registered (return 404).
|
||||
|
||||
**Delegation rules:**
|
||||
- The delegatee must be in the same tenant as the delegator.
|
||||
- Delegated scopes must be a strict subset of the delegator's own scopes.
|
||||
- TTL minimum: 60 seconds; maximum: 86400 seconds (24 hours).
|
||||
- Each delegation chain has a unique `chainId` (UUID).
|
||||
- Revoking a chain is idempotent — revoking an already-revoked chain succeeds.
|
||||
|
||||
servers:
|
||||
- url: http://localhost:3000/api/v1
|
||||
description: Local development server
|
||||
- url: https://api.sentryagent.ai/v1
|
||||
description: Production server
|
||||
|
||||
tags:
|
||||
- name: A2A Delegation
|
||||
description: Agent-to-Agent delegation chain management
|
||||
|
||||
components:
|
||||
securitySchemes:
|
||||
BearerAuth:
|
||||
type: http
|
||||
scheme: bearer
|
||||
bearerFormat: JWT
|
||||
description: |
|
||||
JWT access token obtained via `POST /token`.
|
||||
Include as `Authorization: Bearer <token>`.
|
||||
|
||||
schemas:
|
||||
DelegationChain:
|
||||
type: object
|
||||
description: A delegation chain record as returned by the API.
|
||||
required:
|
||||
- id
|
||||
- tenantId
|
||||
- delegatorAgentId
|
||||
- delegateeAgentId
|
||||
- scopes
|
||||
- delegationToken
|
||||
- ttlSeconds
|
||||
- issuedAt
|
||||
- expiresAt
|
||||
- createdAt
|
||||
properties:
|
||||
id:
|
||||
type: string
|
||||
format: uuid
|
||||
description: Unique identifier of the delegation chain.
|
||||
readOnly: true
|
||||
example: "chain-abcd-1234-5678-ef01"
|
||||
tenantId:
|
||||
type: string
|
||||
format: uuid
|
||||
description: Organization (tenant) that owns this delegation.
|
||||
readOnly: true
|
||||
example: "org-1234-5678-abcd-ef01"
|
||||
delegatorAgentId:
|
||||
type: string
|
||||
format: uuid
|
||||
description: UUID of the agent granting authority.
|
||||
example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
|
||||
delegateeAgentId:
|
||||
type: string
|
||||
format: uuid
|
||||
description: UUID of the agent receiving delegated authority.
|
||||
example: "b2c3d4e5-f6a7-8901-bcde-f12345678901"
|
||||
scopes:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
description: OAuth 2.0 scopes granted by this delegation chain.
|
||||
example:
|
||||
- "agents:read"
|
||||
delegationToken:
|
||||
type: string
|
||||
description: |
|
||||
Opaque delegation token string that the delegatee presents to verify authority.
|
||||
This token encodes the chain metadata and is HMAC-signed.
|
||||
example: "chain-abcd-1234-5678-ef01.1743151200.1743237600"
|
||||
signature:
|
||||
type: string
|
||||
description: HMAC-SHA256 signature of the delegation token payload.
|
||||
example: "3a7f2b9c..."
|
||||
ttlSeconds:
|
||||
type: integer
|
||||
description: Delegation lifetime in seconds.
|
||||
minimum: 60
|
||||
maximum: 86400
|
||||
example: 3600
|
||||
issuedAt:
|
||||
type: string
|
||||
format: date-time
|
||||
readOnly: true
|
||||
example: "2026-04-07T09:00:00.000Z"
|
||||
expiresAt:
|
||||
type: string
|
||||
format: date-time
|
||||
readOnly: true
|
||||
example: "2026-04-07T10:00:00.000Z"
|
||||
revokedAt:
|
||||
type: string
|
||||
format: date-time
|
||||
nullable: true
|
||||
description: Timestamp when this chain was revoked. Null if still active or expired naturally.
|
||||
readOnly: true
|
||||
example: null
|
||||
createdAt:
|
||||
type: string
|
||||
format: date-time
|
||||
readOnly: true
|
||||
example: "2026-04-07T09:00:00.000Z"
|
||||
|
||||
CreateDelegationRequest:
|
||||
type: object
|
||||
description: Request body for creating a new agent-to-agent delegation chain.
|
||||
required:
|
||||
- delegateeAgentId
|
||||
- scopes
|
||||
- ttlSeconds
|
||||
properties:
|
||||
delegateeAgentId:
|
||||
type: string
|
||||
format: uuid
|
||||
description: |
|
||||
UUID of the agent to receive delegated authority.
|
||||
Must be in the same tenant as the delegator (caller).
|
||||
example: "b2c3d4e5-f6a7-8901-bcde-f12345678901"
|
||||
scopes:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
description: |
|
||||
Scopes to delegate. Must be a strict subset of the delegator's current token scopes.
|
||||
At least one scope must be specified.
|
||||
minItems: 1
|
||||
example:
|
||||
- "agents:read"
|
||||
ttlSeconds:
|
||||
type: integer
|
||||
description: Delegation lifetime in seconds. Minimum: 60; Maximum: 86400 (24 hours).
|
||||
minimum: 60
|
||||
maximum: 86400
|
||||
example: 3600
|
||||
|
||||
VerifyDelegationRequest:
|
||||
type: object
|
||||
description: Request body for verifying a delegation token.
|
||||
required:
|
||||
- delegationToken
|
||||
properties:
|
||||
delegationToken:
|
||||
type: string
|
||||
description: The delegation token string to verify.
|
||||
example: "chain-abcd-1234-5678-ef01.1743151200.1743237600"
|
||||
|
||||
DelegationVerificationResult:
|
||||
type: object
|
||||
description: |
|
||||
Result of verifying a delegation token.
|
||||
Returns `valid: false` for expired or revoked tokens without throwing.
|
||||
required:
|
||||
- valid
|
||||
- chainId
|
||||
- delegatorAgentId
|
||||
- delegateeAgentId
|
||||
- scopes
|
||||
- issuedAt
|
||||
- expiresAt
|
||||
properties:
|
||||
valid:
|
||||
type: boolean
|
||||
description: Whether the delegation token is currently valid (active, not expired, not revoked).
|
||||
example: true
|
||||
chainId:
|
||||
type: string
|
||||
format: uuid
|
||||
description: UUID of the delegation chain.
|
||||
example: "chain-abcd-1234-5678-ef01"
|
||||
delegatorAgentId:
|
||||
type: string
|
||||
format: uuid
|
||||
example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
|
||||
delegateeAgentId:
|
||||
type: string
|
||||
format: uuid
|
||||
example: "b2c3d4e5-f6a7-8901-bcde-f12345678901"
|
||||
scopes:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
example:
|
||||
- "agents:read"
|
||||
issuedAt:
|
||||
type: string
|
||||
format: date-time
|
||||
example: "2026-04-07T09:00:00.000Z"
|
||||
expiresAt:
|
||||
type: string
|
||||
format: date-time
|
||||
example: "2026-04-07T10:00:00.000Z"
|
||||
revokedAt:
|
||||
type: string
|
||||
format: date-time
|
||||
nullable: true
|
||||
example: null
|
||||
|
||||
ErrorResponse:
|
||||
type: object
|
||||
description: Standard error response envelope.
|
||||
required:
|
||||
- code
|
||||
- message
|
||||
properties:
|
||||
code:
|
||||
type: string
|
||||
example: "DELEGATION_NOT_FOUND"
|
||||
message:
|
||||
type: string
|
||||
example: "Delegation chain with the specified ID was not found."
|
||||
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."
|
||||
|
||||
Forbidden:
|
||||
description: Valid token but insufficient permissions.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
example:
|
||||
code: "FORBIDDEN"
|
||||
message: "You do not have permission to perform this action."
|
||||
|
||||
NotFound:
|
||||
description: Delegation chain not found.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
example:
|
||||
code: "DELEGATION_NOT_FOUND"
|
||||
message: "Delegation chain 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."
|
||||
|
||||
security:
|
||||
- BearerAuth: []
|
||||
|
||||
paths:
|
||||
/oauth2/token/delegate:
|
||||
post:
|
||||
operationId: createDelegation
|
||||
tags:
|
||||
- A2A Delegation
|
||||
summary: Create an A2A delegation chain
|
||||
description: |
|
||||
Creates a new agent-to-agent delegation chain. The authenticated agent
|
||||
(the *delegator*) grants a subset of its own scopes to the `delegateeAgentId`.
|
||||
|
||||
A cryptographically-signed `delegationToken` is returned. The delegatee
|
||||
presents this token to `POST /oauth2/token/verify-delegation` to prove
|
||||
delegated authority.
|
||||
|
||||
**Validation:**
|
||||
- Delegatee must be in the same organization as the delegator.
|
||||
- `scopes` must be a strict subset of the delegator's current token scopes.
|
||||
- `ttlSeconds` must be between 60 and 86400.
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/CreateDelegationRequest'
|
||||
example:
|
||||
delegateeAgentId: "b2c3d4e5-f6a7-8901-bcde-f12345678901"
|
||||
scopes:
|
||||
- "agents:read"
|
||||
ttlSeconds: 3600
|
||||
responses:
|
||||
'201':
|
||||
description: Delegation chain created successfully.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/DelegationChain'
|
||||
example:
|
||||
id: "chain-abcd-1234-5678-ef01"
|
||||
tenantId: "org-1234-5678-abcd-ef01"
|
||||
delegatorAgentId: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
|
||||
delegateeAgentId: "b2c3d4e5-f6a7-8901-bcde-f12345678901"
|
||||
scopes:
|
||||
- "agents:read"
|
||||
delegationToken: "chain-abcd-1234-5678-ef01.1743151200.1743154800"
|
||||
signature: "3a7f2b9c..."
|
||||
ttlSeconds: 3600
|
||||
issuedAt: "2026-04-07T09:00:00.000Z"
|
||||
expiresAt: "2026-04-07T10:00:00.000Z"
|
||||
revokedAt: null
|
||||
createdAt: "2026-04-07T09:00:00.000Z"
|
||||
'400':
|
||||
description: Validation error in request body.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
examples:
|
||||
scopeExceedsOwn:
|
||||
summary: Requested scope exceeds delegator's own scopes
|
||||
value:
|
||||
code: "SCOPE_EXCEEDS_DELEGATOR"
|
||||
message: "Delegated scopes must be a subset of the delegator's own token scopes."
|
||||
details:
|
||||
requested: ["agents:write"]
|
||||
available: ["agents:read"]
|
||||
invalidTtl:
|
||||
summary: TTL out of range
|
||||
value:
|
||||
code: "VALIDATION_ERROR"
|
||||
message: "ttlSeconds must be between 60 and 86400."
|
||||
crossTenant:
|
||||
summary: Delegatee in different tenant
|
||||
value:
|
||||
code: "CROSS_TENANT_DELEGATION"
|
||||
message: "Delegatee agent must be in the same organization as the delegator."
|
||||
'401':
|
||||
$ref: '#/components/responses/Unauthorized'
|
||||
'404':
|
||||
description: Delegatee agent not found.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
example:
|
||||
code: "AGENT_NOT_FOUND"
|
||||
message: "Delegatee agent with the specified ID was not found."
|
||||
'500':
|
||||
$ref: '#/components/responses/InternalServerError'
|
||||
|
||||
/oauth2/token/verify-delegation:
|
||||
post:
|
||||
operationId: verifyDelegation
|
||||
tags:
|
||||
- A2A Delegation
|
||||
summary: Verify a delegation token
|
||||
description: |
|
||||
Verifies a delegation token and returns the chain details if valid.
|
||||
|
||||
Returns `valid: true` with full chain metadata when the token is valid
|
||||
(exists, not expired, not revoked).
|
||||
|
||||
Returns `valid: false` when the token is expired or revoked.
|
||||
Does not throw an error for inactive tokens — always returns `200`.
|
||||
|
||||
Requires a valid Bearer JWT (any authenticated agent may verify a delegation).
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/VerifyDelegationRequest'
|
||||
example:
|
||||
delegationToken: "chain-abcd-1234-5678-ef01.1743151200.1743154800"
|
||||
responses:
|
||||
'200':
|
||||
description: Delegation verification result returned.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/DelegationVerificationResult'
|
||||
examples:
|
||||
valid:
|
||||
summary: Valid delegation token
|
||||
value:
|
||||
valid: true
|
||||
chainId: "chain-abcd-1234-5678-ef01"
|
||||
delegatorAgentId: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
|
||||
delegateeAgentId: "b2c3d4e5-f6a7-8901-bcde-f12345678901"
|
||||
scopes:
|
||||
- "agents:read"
|
||||
issuedAt: "2026-04-07T09:00:00.000Z"
|
||||
expiresAt: "2026-04-07T10:00:00.000Z"
|
||||
revokedAt: null
|
||||
expired:
|
||||
summary: Expired delegation token
|
||||
value:
|
||||
valid: false
|
||||
chainId: "chain-abcd-1234-5678-ef01"
|
||||
delegatorAgentId: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
|
||||
delegateeAgentId: "b2c3d4e5-f6a7-8901-bcde-f12345678901"
|
||||
scopes:
|
||||
- "agents:read"
|
||||
issuedAt: "2026-04-06T09:00:00.000Z"
|
||||
expiresAt: "2026-04-06T10:00:00.000Z"
|
||||
revokedAt: null
|
||||
'400':
|
||||
description: Missing or malformed `delegationToken` field.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
example:
|
||||
code: "VALIDATION_ERROR"
|
||||
message: "The 'delegationToken' field is required."
|
||||
'401':
|
||||
$ref: '#/components/responses/Unauthorized'
|
||||
'500':
|
||||
$ref: '#/components/responses/InternalServerError'
|
||||
|
||||
/oauth2/token/delegate/{chainId}:
|
||||
parameters:
|
||||
- name: chainId
|
||||
in: path
|
||||
required: true
|
||||
description: UUID of the delegation chain to revoke.
|
||||
schema:
|
||||
type: string
|
||||
format: uuid
|
||||
example: "chain-abcd-1234-5678-ef01"
|
||||
|
||||
delete:
|
||||
operationId: revokeDelegation
|
||||
tags:
|
||||
- A2A Delegation
|
||||
summary: Revoke a delegation chain
|
||||
description: |
|
||||
Immediately revokes a delegation chain.
|
||||
|
||||
After revocation, `POST /oauth2/token/verify-delegation` will return
|
||||
`valid: false` for the revoked chain's token.
|
||||
|
||||
**Idempotent** — revoking an already-revoked chain returns `204` without error.
|
||||
|
||||
Only the delegator agent or an admin may revoke a chain.
|
||||
Requires a valid Bearer JWT.
|
||||
responses:
|
||||
'204':
|
||||
description: Delegation chain revoked successfully (or was already revoked). No response body.
|
||||
'401':
|
||||
$ref: '#/components/responses/Unauthorized'
|
||||
'403':
|
||||
$ref: '#/components/responses/Forbidden'
|
||||
'404':
|
||||
$ref: '#/components/responses/NotFound'
|
||||
'500':
|
||||
$ref: '#/components/responses/InternalServerError'
|
||||
576
docs/openapi/did.yaml
Normal file
576
docs/openapi/did.yaml
Normal file
@@ -0,0 +1,576 @@
|
||||
openapi: "3.0.3"
|
||||
|
||||
info:
|
||||
title: SentryAgent.ai — W3C DID & AGNTCY Agent Card
|
||||
version: 1.0.0
|
||||
description: |
|
||||
W3C Decentralized Identifier (DID) and AGNTCY Agent Card endpoints for the
|
||||
SentryAgent.ai AgentIdP platform.
|
||||
|
||||
**Unauthenticated endpoints:**
|
||||
- `GET /.well-known/did.json` — Instance-level DID Document for the IdP itself
|
||||
- `GET /api/v1/agents/:agentId/did` — Per-agent W3C DID Document
|
||||
- `GET /api/v1/agents/:agentId/did/card` — AGNTCY-format agent card
|
||||
|
||||
**Authenticated endpoint** (requires Bearer JWT + OPA authorization):
|
||||
- `GET /api/v1/agents/:agentId/did/resolve` — W3C DID Resolution result
|
||||
|
||||
All DID Documents conform to the **W3C DID Core 1.0** specification.
|
||||
Agent cards conform to the **AGNTCY** agent identity standard (Linux Foundation).
|
||||
|
||||
servers:
|
||||
- url: http://localhost:3000
|
||||
description: Local development server
|
||||
- url: https://api.sentryagent.ai
|
||||
description: Production server
|
||||
|
||||
tags:
|
||||
- name: DID Documents
|
||||
description: W3C DID Document endpoints (unauthenticated)
|
||||
- name: DID Resolution
|
||||
description: Authenticated W3C DID Resolution endpoint
|
||||
- name: Agent Card
|
||||
description: AGNTCY agent card endpoint (unauthenticated)
|
||||
|
||||
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:
|
||||
PublicKeyJwk:
|
||||
type: object
|
||||
description: JWK representation of a public key embedded in a verification method.
|
||||
required:
|
||||
- kty
|
||||
properties:
|
||||
kty:
|
||||
type: string
|
||||
description: Key type (e.g. "EC", "RSA").
|
||||
example: "EC"
|
||||
crv:
|
||||
type: string
|
||||
description: EC curve (e.g. "P-256").
|
||||
example: "P-256"
|
||||
x:
|
||||
type: string
|
||||
description: Base64url-encoded EC x coordinate.
|
||||
example: "f83OJ3D..."
|
||||
y:
|
||||
type: string
|
||||
description: Base64url-encoded EC y coordinate.
|
||||
example: "x_FEzRu..."
|
||||
n:
|
||||
type: string
|
||||
description: Base64url-encoded RSA modulus.
|
||||
e:
|
||||
type: string
|
||||
description: Base64url-encoded RSA public exponent.
|
||||
example: "AQAB"
|
||||
use:
|
||||
type: string
|
||||
example: "sig"
|
||||
kid:
|
||||
type: string
|
||||
example: "key-20260328-001"
|
||||
|
||||
VerificationMethod:
|
||||
type: object
|
||||
description: W3C DID Core 1.0 verification method.
|
||||
required:
|
||||
- id
|
||||
- type
|
||||
- controller
|
||||
- publicKeyJwk
|
||||
properties:
|
||||
id:
|
||||
type: string
|
||||
description: Full DID URL for this verification method.
|
||||
example: "did:web:api.sentryagent.ai:agents:a1b2c3d4-e5f6-7890-abcd-ef1234567890#key-1"
|
||||
type:
|
||||
type: string
|
||||
description: Verification method type.
|
||||
example: "JsonWebKey2020"
|
||||
controller:
|
||||
type: string
|
||||
description: DID that controls this key.
|
||||
example: "did:web:api.sentryagent.ai:agents:a1b2c3d4-e5f6-7890-abcd-ef1234567890"
|
||||
publicKeyJwk:
|
||||
$ref: '#/components/schemas/PublicKeyJwk'
|
||||
|
||||
DIDService:
|
||||
type: object
|
||||
description: A W3C DID Document service endpoint.
|
||||
required:
|
||||
- id
|
||||
- type
|
||||
- serviceEndpoint
|
||||
properties:
|
||||
id:
|
||||
type: string
|
||||
example: "did:web:api.sentryagent.ai:agents:a1b2c3d4#agentIdP"
|
||||
type:
|
||||
type: string
|
||||
example: "AgentIdP"
|
||||
serviceEndpoint:
|
||||
type: string
|
||||
format: uri
|
||||
example: "https://api.sentryagent.ai/api/v1/agents/a1b2c3d4-e5f6-7890-abcd-ef1234567890"
|
||||
|
||||
AgntcyExtension:
|
||||
type: object
|
||||
description: AGNTCY-specific extension fields embedded in a per-agent DID Document.
|
||||
required:
|
||||
- agentId
|
||||
- agentType
|
||||
- capabilities
|
||||
- deploymentEnv
|
||||
- owner
|
||||
- version
|
||||
properties:
|
||||
agentId:
|
||||
type: string
|
||||
format: uuid
|
||||
example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
|
||||
agentType:
|
||||
type: string
|
||||
example: "screener"
|
||||
capabilities:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
example: ["resume:read", "email:send"]
|
||||
deploymentEnv:
|
||||
type: string
|
||||
example: "production"
|
||||
owner:
|
||||
type: string
|
||||
example: "talent-acquisition-team"
|
||||
version:
|
||||
type: string
|
||||
example: "1.4.2"
|
||||
|
||||
DIDDocument:
|
||||
type: object
|
||||
description: W3C DID Core 1.0 DID Document.
|
||||
required:
|
||||
- "@context"
|
||||
- id
|
||||
- controller
|
||||
- verificationMethod
|
||||
- authentication
|
||||
properties:
|
||||
"@context":
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
description: JSON-LD context URIs.
|
||||
example:
|
||||
- "https://www.w3.org/ns/did/v1"
|
||||
- "https://w3id.org/security/suites/jws-2020/v1"
|
||||
id:
|
||||
type: string
|
||||
description: The DID identifier for this document.
|
||||
example: "did:web:api.sentryagent.ai:agents:a1b2c3d4-e5f6-7890-abcd-ef1234567890"
|
||||
controller:
|
||||
type: string
|
||||
description: DID of the controlling entity.
|
||||
example: "did:web:api.sentryagent.ai"
|
||||
verificationMethod:
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/components/schemas/VerificationMethod'
|
||||
authentication:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
description: DID URLs referencing verification methods authorized for authentication.
|
||||
example:
|
||||
- "did:web:api.sentryagent.ai:agents:a1b2c3d4-e5f6-7890-abcd-ef1234567890#key-1"
|
||||
assertionMethod:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
service:
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/components/schemas/DIDService'
|
||||
agntcy:
|
||||
$ref: '#/components/schemas/AgntcyExtension'
|
||||
|
||||
DIDResolutionResult:
|
||||
type: object
|
||||
description: |
|
||||
W3C DID Resolution result format.
|
||||
Returned with `Content-Type: application/ld+json;profile="https://w3id.org/did-resolution"`.
|
||||
required:
|
||||
- didDocument
|
||||
- didDocumentMetadata
|
||||
- didResolutionMetadata
|
||||
properties:
|
||||
didDocument:
|
||||
$ref: '#/components/schemas/DIDDocument'
|
||||
didDocumentMetadata:
|
||||
type: object
|
||||
required:
|
||||
- created
|
||||
- updated
|
||||
- deactivated
|
||||
properties:
|
||||
created:
|
||||
type: string
|
||||
format: date-time
|
||||
example: "2026-03-01T08:00:00.000Z"
|
||||
updated:
|
||||
type: string
|
||||
format: date-time
|
||||
example: "2026-03-28T11:30:00.000Z"
|
||||
deactivated:
|
||||
type: boolean
|
||||
example: false
|
||||
didResolutionMetadata:
|
||||
type: object
|
||||
required:
|
||||
- contentType
|
||||
- retrieved
|
||||
properties:
|
||||
contentType:
|
||||
type: string
|
||||
example: "application/ld+json"
|
||||
retrieved:
|
||||
type: string
|
||||
format: date-time
|
||||
example: "2026-04-07T09:00:00.000Z"
|
||||
|
||||
AgentCard:
|
||||
type: object
|
||||
description: |
|
||||
AGNTCY-format agent card providing a machine-readable identity summary.
|
||||
Suitable for AGNTCY registry publishing and agent discovery.
|
||||
required:
|
||||
- did
|
||||
- name
|
||||
- agentType
|
||||
- capabilities
|
||||
- owner
|
||||
- version
|
||||
- deploymentEnv
|
||||
- identityProvider
|
||||
- issuedAt
|
||||
properties:
|
||||
did:
|
||||
type: string
|
||||
description: W3C DID identifier for this agent.
|
||||
example: "did:web:api.sentryagent.ai:agents:a1b2c3d4-e5f6-7890-abcd-ef1234567890"
|
||||
name:
|
||||
type: string
|
||||
description: Human-readable agent name (derived from email).
|
||||
example: "screener-001@sentryagent.ai"
|
||||
agentType:
|
||||
type: string
|
||||
example: "screener"
|
||||
capabilities:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
example: ["resume:read", "email:send", "candidate:score"]
|
||||
owner:
|
||||
type: string
|
||||
example: "talent-acquisition-team"
|
||||
version:
|
||||
type: string
|
||||
example: "1.4.2"
|
||||
deploymentEnv:
|
||||
type: string
|
||||
example: "production"
|
||||
identityProvider:
|
||||
type: string
|
||||
format: uri
|
||||
description: URL of the issuing AgentIdP instance.
|
||||
example: "https://api.sentryagent.ai"
|
||||
issuedAt:
|
||||
type: string
|
||||
format: date-time
|
||||
description: ISO 8601 timestamp when this card was generated.
|
||||
example: "2026-04-07T09:00:00.000Z"
|
||||
|
||||
ErrorResponse:
|
||||
type: object
|
||||
description: Standard error response envelope.
|
||||
required:
|
||||
- code
|
||||
- message
|
||||
properties:
|
||||
code:
|
||||
type: string
|
||||
example: "AGENT_NOT_FOUND"
|
||||
message:
|
||||
type: string
|
||||
example: "Agent with the specified ID was not found."
|
||||
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."
|
||||
|
||||
Forbidden:
|
||||
description: Valid token but insufficient permissions.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
example:
|
||||
code: "FORBIDDEN"
|
||||
message: "You do not have permission to perform this action."
|
||||
|
||||
NotFound:
|
||||
description: Agent 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/did.json:
|
||||
get:
|
||||
operationId: getInstanceDIDDocument
|
||||
tags:
|
||||
- DID Documents
|
||||
summary: Instance-level DID Document
|
||||
description: |
|
||||
Returns the W3C DID Document for the SentryAgent.ai AgentIdP instance itself.
|
||||
This identifies the IdP as a DID controller (`did:web:api.sentryagent.ai`).
|
||||
|
||||
Used by external parties to discover the IdP's public keys and service endpoints.
|
||||
This endpoint is **unauthenticated**.
|
||||
security: []
|
||||
responses:
|
||||
'200':
|
||||
description: Instance DID Document returned successfully.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/DIDDocument'
|
||||
example:
|
||||
"@context":
|
||||
- "https://www.w3.org/ns/did/v1"
|
||||
- "https://w3id.org/security/suites/jws-2020/v1"
|
||||
id: "did:web:api.sentryagent.ai"
|
||||
controller: "did:web:api.sentryagent.ai"
|
||||
verificationMethod:
|
||||
- id: "did:web:api.sentryagent.ai#key-1"
|
||||
type: "JsonWebKey2020"
|
||||
controller: "did:web:api.sentryagent.ai"
|
||||
publicKeyJwk:
|
||||
kty: "EC"
|
||||
crv: "P-256"
|
||||
x: "f83OJ3D..."
|
||||
y: "x_FEzRu..."
|
||||
authentication:
|
||||
- "did:web:api.sentryagent.ai#key-1"
|
||||
service:
|
||||
- id: "did:web:api.sentryagent.ai#agentIdP"
|
||||
type: "AgentIdP"
|
||||
serviceEndpoint: "https://api.sentryagent.ai/api/v1"
|
||||
'500':
|
||||
$ref: '#/components/responses/InternalServerError'
|
||||
|
||||
/api/v1/agents/{agentId}/did:
|
||||
get:
|
||||
operationId: getAgentDIDDocument
|
||||
tags:
|
||||
- DID Documents
|
||||
summary: Get agent DID Document
|
||||
description: |
|
||||
Returns the W3C DID Core 1.0 Document for a specific registered agent.
|
||||
|
||||
Returns `410 Gone` if the agent has been decommissioned — the DID Document
|
||||
is no longer active.
|
||||
|
||||
This endpoint is **unauthenticated**.
|
||||
security: []
|
||||
parameters:
|
||||
- name: agentId
|
||||
in: path
|
||||
required: true
|
||||
description: UUID of the agent.
|
||||
schema:
|
||||
type: string
|
||||
format: uuid
|
||||
example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
|
||||
responses:
|
||||
'200':
|
||||
description: Agent DID Document returned successfully.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/DIDDocument'
|
||||
example:
|
||||
"@context":
|
||||
- "https://www.w3.org/ns/did/v1"
|
||||
- "https://w3id.org/security/suites/jws-2020/v1"
|
||||
id: "did:web:api.sentryagent.ai:agents:a1b2c3d4-e5f6-7890-abcd-ef1234567890"
|
||||
controller: "did:web:api.sentryagent.ai"
|
||||
verificationMethod:
|
||||
- id: "did:web:api.sentryagent.ai:agents:a1b2c3d4-e5f6-7890-abcd-ef1234567890#key-1"
|
||||
type: "JsonWebKey2020"
|
||||
controller: "did:web:api.sentryagent.ai:agents:a1b2c3d4-e5f6-7890-abcd-ef1234567890"
|
||||
publicKeyJwk:
|
||||
kty: "EC"
|
||||
crv: "P-256"
|
||||
x: "f83OJ3D..."
|
||||
y: "x_FEzRu..."
|
||||
authentication:
|
||||
- "did:web:api.sentryagent.ai:agents:a1b2c3d4-e5f6-7890-abcd-ef1234567890#key-1"
|
||||
agntcy:
|
||||
agentId: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
|
||||
agentType: "screener"
|
||||
capabilities:
|
||||
- "resume:read"
|
||||
- "email:send"
|
||||
deploymentEnv: "production"
|
||||
owner: "talent-acquisition-team"
|
||||
version: "1.4.2"
|
||||
'404':
|
||||
$ref: '#/components/responses/NotFound'
|
||||
'410':
|
||||
description: Agent has been decommissioned — DID Document is no longer active.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
example:
|
||||
code: "AGENT_DECOMMISSIONED"
|
||||
message: "Agent has been decommissioned — DID Document is no longer active"
|
||||
'500':
|
||||
$ref: '#/components/responses/InternalServerError'
|
||||
|
||||
/api/v1/agents/{agentId}/did/resolve:
|
||||
get:
|
||||
operationId: resolveAgentDID
|
||||
tags:
|
||||
- DID Resolution
|
||||
summary: Resolve agent DID (W3C DID Resolution)
|
||||
description: |
|
||||
Returns the full W3C DID Resolution result for a specific agent, including
|
||||
the DID Document, DID Document Metadata, and DID Resolution Metadata.
|
||||
|
||||
The response `Content-Type` is:
|
||||
`application/ld+json;profile="https://w3id.org/did-resolution"`
|
||||
|
||||
Requires a valid Bearer JWT and OPA authorization.
|
||||
security:
|
||||
- BearerAuth: []
|
||||
parameters:
|
||||
- name: agentId
|
||||
in: path
|
||||
required: true
|
||||
description: UUID of the agent to resolve.
|
||||
schema:
|
||||
type: string
|
||||
format: uuid
|
||||
example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
|
||||
responses:
|
||||
'200':
|
||||
description: DID Resolution result returned successfully.
|
||||
content:
|
||||
application/ld+json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/DIDResolutionResult'
|
||||
example:
|
||||
didDocument:
|
||||
"@context":
|
||||
- "https://www.w3.org/ns/did/v1"
|
||||
id: "did:web:api.sentryagent.ai:agents:a1b2c3d4-e5f6-7890-abcd-ef1234567890"
|
||||
controller: "did:web:api.sentryagent.ai"
|
||||
verificationMethod: []
|
||||
authentication: []
|
||||
didDocumentMetadata:
|
||||
created: "2026-03-01T08:00:00.000Z"
|
||||
updated: "2026-03-28T11:30:00.000Z"
|
||||
deactivated: false
|
||||
didResolutionMetadata:
|
||||
contentType: "application/ld+json"
|
||||
retrieved: "2026-04-07T09:00:00.000Z"
|
||||
'401':
|
||||
$ref: '#/components/responses/Unauthorized'
|
||||
'403':
|
||||
$ref: '#/components/responses/Forbidden'
|
||||
'404':
|
||||
$ref: '#/components/responses/NotFound'
|
||||
'500':
|
||||
$ref: '#/components/responses/InternalServerError'
|
||||
|
||||
/api/v1/agents/{agentId}/did/card:
|
||||
get:
|
||||
operationId: getAgentCard
|
||||
tags:
|
||||
- Agent Card
|
||||
summary: Get AGNTCY agent card
|
||||
description: |
|
||||
Returns the AGNTCY-format agent card for the specified agent.
|
||||
The card provides a machine-readable identity summary suitable for
|
||||
AGNTCY registry publishing and agent discovery by external consumers.
|
||||
|
||||
This endpoint is **unauthenticated**.
|
||||
security: []
|
||||
parameters:
|
||||
- name: agentId
|
||||
in: path
|
||||
required: true
|
||||
description: UUID of the agent.
|
||||
schema:
|
||||
type: string
|
||||
format: uuid
|
||||
example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
|
||||
responses:
|
||||
'200':
|
||||
description: AGNTCY agent card returned successfully.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/AgentCard'
|
||||
example:
|
||||
did: "did:web:api.sentryagent.ai:agents:a1b2c3d4-e5f6-7890-abcd-ef1234567890"
|
||||
name: "screener-001@sentryagent.ai"
|
||||
agentType: "screener"
|
||||
capabilities:
|
||||
- "resume:read"
|
||||
- "email:send"
|
||||
- "candidate:score"
|
||||
owner: "talent-acquisition-team"
|
||||
version: "1.4.2"
|
||||
deploymentEnv: "production"
|
||||
identityProvider: "https://api.sentryagent.ai"
|
||||
issuedAt: "2026-04-07T09:00:00.000Z"
|
||||
'404':
|
||||
$ref: '#/components/responses/NotFound'
|
||||
'500':
|
||||
$ref: '#/components/responses/InternalServerError'
|
||||
639
docs/openapi/federation.yaml
Normal file
639
docs/openapi/federation.yaml
Normal file
@@ -0,0 +1,639 @@
|
||||
openapi: "3.0.3"
|
||||
|
||||
info:
|
||||
title: SentryAgent.ai — Identity Federation
|
||||
version: 1.0.0
|
||||
description: |
|
||||
Cross-IdP identity federation endpoints for the SentryAgent.ai AgentIdP platform.
|
||||
|
||||
The federation subsystem enables this IdP to trust and verify JWT tokens issued by
|
||||
external identity providers (partner IdPs). This allows agents from federated
|
||||
organizations to authenticate without re-registering.
|
||||
|
||||
**Partner management** (`admin:orgs` scope required):
|
||||
- `POST /federation/trust` — Register a new trusted partner IdP
|
||||
- `GET /federation/partners` — List all registered partners
|
||||
- `GET /federation/partners/:id` — Get a specific partner
|
||||
- `PATCH /federation/partners/:id` — Update a partner
|
||||
- `DELETE /federation/partners/:id` — Remove a partner
|
||||
|
||||
**Token verification** (any authenticated agent):
|
||||
- `POST /federation/verify` — Verify a federated JWT from a trusted partner
|
||||
|
||||
servers:
|
||||
- url: http://localhost:3000/api/v1
|
||||
description: Local development server
|
||||
- url: https://api.sentryagent.ai/v1
|
||||
description: Production server
|
||||
|
||||
tags:
|
||||
- name: Federation Partners
|
||||
description: Trusted partner IdP management (admin:orgs scope)
|
||||
- name: Federation Verification
|
||||
description: Cross-IdP token verification (any authenticated agent)
|
||||
|
||||
components:
|
||||
securitySchemes:
|
||||
BearerAuth:
|
||||
type: http
|
||||
scheme: bearer
|
||||
bearerFormat: JWT
|
||||
description: |
|
||||
JWT access token obtained via `POST /token`.
|
||||
Include as `Authorization: Bearer <token>`.
|
||||
|
||||
schemas:
|
||||
FederationPartnerStatus:
|
||||
type: string
|
||||
enum:
|
||||
- active
|
||||
- suspended
|
||||
- expired
|
||||
description: |
|
||||
Lifecycle status of a federation partner.
|
||||
- `active` — partner is trusted; tokens accepted.
|
||||
- `suspended` — temporarily disabled; tokens rejected.
|
||||
- `expired` — `expires_at` has passed; tokens rejected.
|
||||
example: active
|
||||
|
||||
FederationPartner:
|
||||
type: object
|
||||
description: A registered trusted federation partner IdP.
|
||||
required:
|
||||
- id
|
||||
- name
|
||||
- issuer
|
||||
- jwks_uri
|
||||
- allowed_organizations
|
||||
- status
|
||||
- created_at
|
||||
- updated_at
|
||||
properties:
|
||||
id:
|
||||
type: string
|
||||
format: uuid
|
||||
description: Immutable system-assigned UUID for this partner.
|
||||
readOnly: true
|
||||
example: "fed-abcd-1234-5678-ef01"
|
||||
name:
|
||||
type: string
|
||||
description: Human-readable partner name.
|
||||
example: "Acme Partner IdP"
|
||||
issuer:
|
||||
type: string
|
||||
format: uri
|
||||
description: Issuer URL — must match the `iss` claim in federated tokens.
|
||||
example: "https://idp.acme-partner.example"
|
||||
jwks_uri:
|
||||
type: string
|
||||
format: uri
|
||||
description: URL of the partner's JWKS endpoint for token signature verification.
|
||||
example: "https://idp.acme-partner.example/.well-known/jwks.json"
|
||||
allowed_organizations:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
description: |
|
||||
Allowlist of organization_id values accepted from this partner.
|
||||
An empty array means all organizations from this partner are accepted.
|
||||
example: ["org-acme-001", "org-acme-002"]
|
||||
status:
|
||||
$ref: '#/components/schemas/FederationPartnerStatus'
|
||||
created_at:
|
||||
type: string
|
||||
format: date-time
|
||||
readOnly: true
|
||||
example: "2026-03-01T08:00:00.000Z"
|
||||
updated_at:
|
||||
type: string
|
||||
format: date-time
|
||||
readOnly: true
|
||||
example: "2026-03-28T11:30:00.000Z"
|
||||
expires_at:
|
||||
type: string
|
||||
format: date-time
|
||||
nullable: true
|
||||
description: Optional expiry timestamp. Null means the partner never expires.
|
||||
example: "2027-01-01T00:00:00.000Z"
|
||||
|
||||
CreatePartnerRequest:
|
||||
type: object
|
||||
description: Request body for registering a new trusted federation partner.
|
||||
required:
|
||||
- name
|
||||
- issuer
|
||||
- jwks_uri
|
||||
properties:
|
||||
name:
|
||||
type: string
|
||||
description: Human-readable partner name.
|
||||
minLength: 1
|
||||
maxLength: 256
|
||||
example: "Acme Partner IdP"
|
||||
issuer:
|
||||
type: string
|
||||
format: uri
|
||||
description: Issuer URL of the external IdP. Must match `iss` in federated tokens.
|
||||
example: "https://idp.acme-partner.example"
|
||||
jwks_uri:
|
||||
type: string
|
||||
format: uri
|
||||
description: |
|
||||
URL of the partner's JWKS endpoint. Must be reachable at registration time —
|
||||
the endpoint is probed before the partner is persisted.
|
||||
example: "https://idp.acme-partner.example/.well-known/jwks.json"
|
||||
allowed_organizations:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
description: Optional allowlist of organization_id values. Defaults to empty (all allowed).
|
||||
example: ["org-acme-001"]
|
||||
expires_at:
|
||||
type: string
|
||||
format: date-time
|
||||
description: Optional ISO 8601 date-time after which the partner will be automatically expired.
|
||||
example: "2027-01-01T00:00:00.000Z"
|
||||
|
||||
UpdatePartnerRequest:
|
||||
type: object
|
||||
description: |
|
||||
Request body for partially updating a federation partner.
|
||||
All fields are optional; only provided fields are updated.
|
||||
minProperties: 1
|
||||
properties:
|
||||
name:
|
||||
type: string
|
||||
minLength: 1
|
||||
maxLength: 256
|
||||
example: "Acme Partner IdP (Updated)"
|
||||
jwks_uri:
|
||||
type: string
|
||||
format: uri
|
||||
description: Updated JWKS endpoint URL. The JWKS cache will be invalidated on update.
|
||||
example: "https://idp.acme-partner.example/.well-known/jwks.json"
|
||||
allowed_organizations:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
example: ["org-acme-001", "org-acme-003"]
|
||||
status:
|
||||
$ref: '#/components/schemas/FederationPartnerStatus'
|
||||
expires_at:
|
||||
type: string
|
||||
format: date-time
|
||||
nullable: true
|
||||
description: Updated expiry. Pass null to remove the expiry.
|
||||
example: "2028-01-01T00:00:00.000Z"
|
||||
|
||||
FederationVerifyRequest:
|
||||
type: object
|
||||
description: Request body for verifying a federated token from a trusted partner.
|
||||
required:
|
||||
- token
|
||||
properties:
|
||||
token:
|
||||
type: string
|
||||
description: The JWT token string issued by the partner IdP.
|
||||
example: "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZ2VudC0wMDEiLCJpc3MiOiJodHRwczovL2lkcC5hY21lLXBhcnRuZXIuZXhhbXBsZSIsImV4cCI6MTc0MzE1NDgwMH0.signature"
|
||||
expected_issuer:
|
||||
type: string
|
||||
format: uri
|
||||
description: |
|
||||
Optional issuer hint. When provided, the token's `iss` claim must match exactly.
|
||||
Useful to prevent issuer confusion when multiple partners share JWKS.
|
||||
example: "https://idp.acme-partner.example"
|
||||
|
||||
FederationVerifyResult:
|
||||
type: object
|
||||
description: Result of a successful federated token verification.
|
||||
required:
|
||||
- valid
|
||||
- issuer
|
||||
- subject
|
||||
- claims
|
||||
properties:
|
||||
valid:
|
||||
type: boolean
|
||||
description: Whether the token is valid (true when verification passed).
|
||||
example: true
|
||||
issuer:
|
||||
type: string
|
||||
format: uri
|
||||
description: The `iss` claim from the verified token.
|
||||
example: "https://idp.acme-partner.example"
|
||||
subject:
|
||||
type: string
|
||||
description: The `sub` claim from the verified token.
|
||||
example: "agent-001-external"
|
||||
organization_id:
|
||||
type: string
|
||||
description: The `organization_id` claim from the token, if present.
|
||||
example: "org-acme-001"
|
||||
claims:
|
||||
type: object
|
||||
description: All claims from the verified token payload.
|
||||
additionalProperties: true
|
||||
example:
|
||||
iss: "https://idp.acme-partner.example"
|
||||
sub: "agent-001-external"
|
||||
aud: "https://api.sentryagent.ai"
|
||||
iat: 1743151200
|
||||
exp: 1743154800
|
||||
organization_id: "org-acme-001"
|
||||
|
||||
ErrorResponse:
|
||||
type: object
|
||||
description: Standard error response envelope.
|
||||
required:
|
||||
- code
|
||||
- message
|
||||
properties:
|
||||
code:
|
||||
type: string
|
||||
example: "FEDERATION_PARTNER_NOT_FOUND"
|
||||
message:
|
||||
type: string
|
||||
example: "Federation partner with the specified ID was not found."
|
||||
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."
|
||||
|
||||
Forbidden:
|
||||
description: Valid token but insufficient permissions.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
example:
|
||||
code: "FORBIDDEN"
|
||||
message: "You do not have permission to perform this action."
|
||||
|
||||
NotFound:
|
||||
description: Federation partner not found.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
example:
|
||||
code: "FEDERATION_PARTNER_NOT_FOUND"
|
||||
message: "Federation partner 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."
|
||||
|
||||
security:
|
||||
- BearerAuth: []
|
||||
|
||||
paths:
|
||||
/federation/trust:
|
||||
post:
|
||||
operationId: registerFederationPartner
|
||||
tags:
|
||||
- Federation Partners
|
||||
summary: Register a trusted federation partner
|
||||
description: |
|
||||
Registers a new external IdP as a trusted federation partner.
|
||||
|
||||
The partner's JWKS endpoint (`jwks_uri`) is probed at registration time
|
||||
to confirm it is reachable. If the endpoint is unreachable, the request
|
||||
is rejected with `422 Unprocessable Entity`.
|
||||
|
||||
Requires `admin:orgs` scope.
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/CreatePartnerRequest'
|
||||
example:
|
||||
name: "Acme Partner IdP"
|
||||
issuer: "https://idp.acme-partner.example"
|
||||
jwks_uri: "https://idp.acme-partner.example/.well-known/jwks.json"
|
||||
allowed_organizations:
|
||||
- "org-acme-001"
|
||||
expires_at: "2027-01-01T00:00:00.000Z"
|
||||
responses:
|
||||
'201':
|
||||
description: Federation partner registered successfully.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/FederationPartner'
|
||||
example:
|
||||
id: "fed-abcd-1234-5678-ef01"
|
||||
name: "Acme Partner IdP"
|
||||
issuer: "https://idp.acme-partner.example"
|
||||
jwks_uri: "https://idp.acme-partner.example/.well-known/jwks.json"
|
||||
allowed_organizations:
|
||||
- "org-acme-001"
|
||||
status: "active"
|
||||
created_at: "2026-04-07T09:00:00.000Z"
|
||||
updated_at: "2026-04-07T09:00:00.000Z"
|
||||
expires_at: "2027-01-01T00:00:00.000Z"
|
||||
'400':
|
||||
description: Validation error in request body.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
example:
|
||||
code: "VALIDATION_ERROR"
|
||||
message: "Request validation failed."
|
||||
details:
|
||||
field: "jwks_uri"
|
||||
reason: "Must be a valid HTTPS URL."
|
||||
'401':
|
||||
$ref: '#/components/responses/Unauthorized'
|
||||
'403':
|
||||
$ref: '#/components/responses/Forbidden'
|
||||
'409':
|
||||
description: A partner with the same issuer is already registered.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
example:
|
||||
code: "FEDERATION_PARTNER_CONFLICT"
|
||||
message: "A federation partner with this issuer is already registered."
|
||||
'422':
|
||||
description: Partner JWKS endpoint is unreachable.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
example:
|
||||
code: "JWKS_UNREACHABLE"
|
||||
message: "The partner JWKS endpoint is unreachable. Verify the URL and try again."
|
||||
'500':
|
||||
$ref: '#/components/responses/InternalServerError'
|
||||
|
||||
/federation/partners:
|
||||
get:
|
||||
operationId: listFederationPartners
|
||||
tags:
|
||||
- Federation Partners
|
||||
summary: List all federation partners
|
||||
description: |
|
||||
Returns all registered federation partners.
|
||||
Partners past their `expires_at` are returned with status `expired`.
|
||||
|
||||
Requires `admin:orgs` scope.
|
||||
responses:
|
||||
'200':
|
||||
description: List of federation partners returned successfully.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/components/schemas/FederationPartner'
|
||||
example:
|
||||
- id: "fed-abcd-1234-5678-ef01"
|
||||
name: "Acme Partner IdP"
|
||||
issuer: "https://idp.acme-partner.example"
|
||||
jwks_uri: "https://idp.acme-partner.example/.well-known/jwks.json"
|
||||
allowed_organizations: ["org-acme-001"]
|
||||
status: "active"
|
||||
created_at: "2026-03-01T08:00:00.000Z"
|
||||
updated_at: "2026-03-28T11:30:00.000Z"
|
||||
expires_at: "2027-01-01T00:00:00.000Z"
|
||||
'401':
|
||||
$ref: '#/components/responses/Unauthorized'
|
||||
'403':
|
||||
$ref: '#/components/responses/Forbidden'
|
||||
'500':
|
||||
$ref: '#/components/responses/InternalServerError'
|
||||
|
||||
/federation/partners/{id}:
|
||||
parameters:
|
||||
- name: id
|
||||
in: path
|
||||
required: true
|
||||
description: UUID of the federation partner.
|
||||
schema:
|
||||
type: string
|
||||
format: uuid
|
||||
example: "fed-abcd-1234-5678-ef01"
|
||||
|
||||
get:
|
||||
operationId: getFederationPartner
|
||||
tags:
|
||||
- Federation Partners
|
||||
summary: Get a federation partner by ID
|
||||
description: |
|
||||
Returns a single federation partner record by its UUID.
|
||||
Requires `admin:orgs` scope.
|
||||
responses:
|
||||
'200':
|
||||
description: Federation partner returned successfully.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/FederationPartner'
|
||||
example:
|
||||
id: "fed-abcd-1234-5678-ef01"
|
||||
name: "Acme Partner IdP"
|
||||
issuer: "https://idp.acme-partner.example"
|
||||
jwks_uri: "https://idp.acme-partner.example/.well-known/jwks.json"
|
||||
allowed_organizations: ["org-acme-001"]
|
||||
status: "active"
|
||||
created_at: "2026-03-01T08:00:00.000Z"
|
||||
updated_at: "2026-03-28T11:30:00.000Z"
|
||||
expires_at: null
|
||||
'401':
|
||||
$ref: '#/components/responses/Unauthorized'
|
||||
'403':
|
||||
$ref: '#/components/responses/Forbidden'
|
||||
'404':
|
||||
$ref: '#/components/responses/NotFound'
|
||||
'500':
|
||||
$ref: '#/components/responses/InternalServerError'
|
||||
|
||||
patch:
|
||||
operationId: updateFederationPartner
|
||||
tags:
|
||||
- Federation Partners
|
||||
summary: Update a federation partner
|
||||
description: |
|
||||
Partially updates a federation partner's configuration.
|
||||
Only provided fields are updated.
|
||||
|
||||
Changing `jwks_uri` invalidates the cached JWKS for this partner.
|
||||
Requires `admin:orgs` scope.
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/UpdatePartnerRequest'
|
||||
example:
|
||||
status: "suspended"
|
||||
allowed_organizations:
|
||||
- "org-acme-001"
|
||||
- "org-acme-003"
|
||||
responses:
|
||||
'200':
|
||||
description: Federation partner updated successfully.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/FederationPartner'
|
||||
example:
|
||||
id: "fed-abcd-1234-5678-ef01"
|
||||
name: "Acme Partner IdP"
|
||||
issuer: "https://idp.acme-partner.example"
|
||||
jwks_uri: "https://idp.acme-partner.example/.well-known/jwks.json"
|
||||
allowed_organizations: ["org-acme-001", "org-acme-003"]
|
||||
status: "suspended"
|
||||
created_at: "2026-03-01T08:00:00.000Z"
|
||||
updated_at: "2026-04-07T09:00:00.000Z"
|
||||
expires_at: null
|
||||
'400':
|
||||
description: Validation error in request body.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
example:
|
||||
code: "VALIDATION_ERROR"
|
||||
message: "Request validation failed."
|
||||
'401':
|
||||
$ref: '#/components/responses/Unauthorized'
|
||||
'403':
|
||||
$ref: '#/components/responses/Forbidden'
|
||||
'404':
|
||||
$ref: '#/components/responses/NotFound'
|
||||
'500':
|
||||
$ref: '#/components/responses/InternalServerError'
|
||||
|
||||
delete:
|
||||
operationId: deleteFederationPartner
|
||||
tags:
|
||||
- Federation Partners
|
||||
summary: Remove a federation partner
|
||||
description: |
|
||||
Permanently removes a federation partner. After removal, tokens issued
|
||||
by the partner's IdP will no longer be accepted.
|
||||
|
||||
Requires `admin:orgs` scope.
|
||||
responses:
|
||||
'204':
|
||||
description: Federation partner removed successfully. No response body.
|
||||
'401':
|
||||
$ref: '#/components/responses/Unauthorized'
|
||||
'403':
|
||||
$ref: '#/components/responses/Forbidden'
|
||||
'404':
|
||||
$ref: '#/components/responses/NotFound'
|
||||
'500':
|
||||
$ref: '#/components/responses/InternalServerError'
|
||||
|
||||
/federation/verify:
|
||||
post:
|
||||
operationId: verifyFederatedToken
|
||||
tags:
|
||||
- Federation Verification
|
||||
summary: Verify a federated JWT token
|
||||
description: |
|
||||
Verifies a JWT token issued by a registered federation partner.
|
||||
|
||||
The token's `iss` claim is matched against registered active partners.
|
||||
The signature is verified against the partner's JWKS.
|
||||
The partner's `allowed_organizations` filter is applied if non-empty.
|
||||
|
||||
Returns verification result with claims on success.
|
||||
Returns `422` with verification failure details on invalid tokens.
|
||||
|
||||
Requires any valid Bearer token (`agents:read` scope is sufficient).
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/FederationVerifyRequest'
|
||||
example:
|
||||
token: "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZ2VudC0wMDEiLCJpc3MiOiJodHRwczovL2lkcC5hY21lLXBhcnRuZXIuZXhhbXBsZSJ9.signature"
|
||||
expected_issuer: "https://idp.acme-partner.example"
|
||||
responses:
|
||||
'200':
|
||||
description: Token verification result returned.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/FederationVerifyResult'
|
||||
examples:
|
||||
valid:
|
||||
summary: Token verified successfully
|
||||
value:
|
||||
valid: true
|
||||
issuer: "https://idp.acme-partner.example"
|
||||
subject: "agent-001-external"
|
||||
organization_id: "org-acme-001"
|
||||
claims:
|
||||
iss: "https://idp.acme-partner.example"
|
||||
sub: "agent-001-external"
|
||||
aud: "https://api.sentryagent.ai"
|
||||
iat: 1743151200
|
||||
exp: 1743154800
|
||||
invalid:
|
||||
summary: Token invalid or expired
|
||||
value:
|
||||
valid: false
|
||||
issuer: ""
|
||||
subject: ""
|
||||
claims: {}
|
||||
'400':
|
||||
description: Missing or malformed token in request body.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
example:
|
||||
code: "VALIDATION_ERROR"
|
||||
message: "The 'token' field is required."
|
||||
'401':
|
||||
$ref: '#/components/responses/Unauthorized'
|
||||
'422':
|
||||
description: |
|
||||
Token is well-formed but verification failed (unknown issuer, expired,
|
||||
invalid signature, or organization not in allowlist).
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
examples:
|
||||
unknownIssuer:
|
||||
summary: Unknown issuer
|
||||
value:
|
||||
code: "UNKNOWN_FEDERATION_ISSUER"
|
||||
message: "No active federation partner found for this token issuer."
|
||||
partnerSuspended:
|
||||
summary: Partner is suspended
|
||||
value:
|
||||
code: "FEDERATION_PARTNER_SUSPENDED"
|
||||
message: "The federation partner for this token issuer is suspended."
|
||||
orgNotAllowed:
|
||||
summary: Organization not in allowlist
|
||||
value:
|
||||
code: "FEDERATION_ORG_NOT_ALLOWED"
|
||||
message: "The token's organization_id is not in the partner's allowed_organizations list."
|
||||
'500':
|
||||
$ref: '#/components/responses/InternalServerError'
|
||||
291
docs/openapi/health.yaml
Normal file
291
docs/openapi/health.yaml
Normal file
@@ -0,0 +1,291 @@
|
||||
openapi: "3.0.3"
|
||||
|
||||
info:
|
||||
title: SentryAgent.ai — Health Check Service
|
||||
version: 1.0.0
|
||||
description: |
|
||||
Liveness and readiness health endpoints for the SentryAgent.ai AgentIdP platform.
|
||||
|
||||
Both endpoints are **unauthenticated** — safe to call from monitoring systems,
|
||||
load balancers, and container orchestrators without credentials.
|
||||
|
||||
**GET /health** performs a fast liveness check (< 50 ms target).
|
||||
**GET /health/detailed** probes each dependency with latency measurement.
|
||||
|
||||
servers:
|
||||
- url: http://localhost:3000
|
||||
description: Local development server
|
||||
- url: https://api.sentryagent.ai
|
||||
description: Production server
|
||||
|
||||
tags:
|
||||
- name: Health
|
||||
description: Liveness and dependency health endpoints
|
||||
|
||||
components:
|
||||
schemas:
|
||||
ServiceSimpleStatus:
|
||||
type: string
|
||||
enum:
|
||||
- connected
|
||||
- disconnected
|
||||
description: Simple connectivity status for the quick health check.
|
||||
example: connected
|
||||
|
||||
ServiceDetailedStatus:
|
||||
type: string
|
||||
enum:
|
||||
- healthy
|
||||
- degraded
|
||||
- unreachable
|
||||
description: |
|
||||
Per-service health classification for the detailed health check.
|
||||
- `healthy` — responded within 1000 ms
|
||||
- `degraded` — responded but latency exceeded 1000 ms
|
||||
- `unreachable` — timed out or threw an error
|
||||
|
||||
ServiceHealthResult:
|
||||
type: object
|
||||
description: Per-service latency and status result from the detailed health probe.
|
||||
required:
|
||||
- status
|
||||
- latencyMs
|
||||
properties:
|
||||
status:
|
||||
$ref: '#/components/schemas/ServiceDetailedStatus'
|
||||
latencyMs:
|
||||
type: integer
|
||||
description: Probe round-trip time in milliseconds.
|
||||
example: 12
|
||||
|
||||
HealthResponse:
|
||||
type: object
|
||||
description: Response body for GET /health — quick liveness check.
|
||||
required:
|
||||
- status
|
||||
- version
|
||||
- uptime
|
||||
- services
|
||||
properties:
|
||||
status:
|
||||
type: string
|
||||
enum:
|
||||
- ok
|
||||
- degraded
|
||||
description: |
|
||||
Overall liveness status.
|
||||
- `ok` — all services are connected.
|
||||
- `degraded` — one or more services are disconnected.
|
||||
example: ok
|
||||
version:
|
||||
type: string
|
||||
description: Running npm package version.
|
||||
example: "1.0.0"
|
||||
uptime:
|
||||
type: integer
|
||||
description: Process uptime in whole seconds.
|
||||
example: 3724
|
||||
services:
|
||||
type: object
|
||||
description: Quick connectivity check for core services.
|
||||
required:
|
||||
- postgres
|
||||
- redis
|
||||
properties:
|
||||
postgres:
|
||||
$ref: '#/components/schemas/ServiceSimpleStatus'
|
||||
redis:
|
||||
$ref: '#/components/schemas/ServiceSimpleStatus'
|
||||
|
||||
DetailedHealthResponse:
|
||||
type: object
|
||||
description: |
|
||||
Response body for GET /health/detailed. Probes each dependency
|
||||
individually and reports per-service latency.
|
||||
required:
|
||||
- status
|
||||
- version
|
||||
- uptime
|
||||
- services
|
||||
properties:
|
||||
status:
|
||||
$ref: '#/components/schemas/ServiceDetailedStatus'
|
||||
description: Worst-case overall status across all probed services.
|
||||
example: healthy
|
||||
version:
|
||||
type: string
|
||||
description: Running npm package version.
|
||||
example: "1.0.0"
|
||||
uptime:
|
||||
type: integer
|
||||
description: Process uptime in whole seconds.
|
||||
example: 3724
|
||||
services:
|
||||
type: object
|
||||
description: |
|
||||
Map of service name to per-service health result.
|
||||
Always includes `postgres`; `redis`, `vault`, and `opa` are
|
||||
included when the respective client / env-var is configured.
|
||||
additionalProperties:
|
||||
$ref: '#/components/schemas/ServiceHealthResult'
|
||||
example:
|
||||
postgres:
|
||||
status: healthy
|
||||
latencyMs: 12
|
||||
redis:
|
||||
status: healthy
|
||||
latencyMs: 3
|
||||
vault:
|
||||
status: degraded
|
||||
latencyMs: 1240
|
||||
opa:
|
||||
status: healthy
|
||||
latencyMs: 8
|
||||
|
||||
ErrorResponse:
|
||||
type: object
|
||||
description: Standard error response envelope.
|
||||
required:
|
||||
- code
|
||||
- message
|
||||
properties:
|
||||
code:
|
||||
type: string
|
||||
example: "INTERNAL_SERVER_ERROR"
|
||||
message:
|
||||
type: string
|
||||
example: "An unexpected error occurred. Please try again later."
|
||||
details:
|
||||
type: object
|
||||
additionalProperties: true
|
||||
|
||||
paths:
|
||||
/health:
|
||||
get:
|
||||
operationId: getHealth
|
||||
tags:
|
||||
- Health
|
||||
summary: Quick liveness check
|
||||
description: |
|
||||
Returns `200 OK` when PostgreSQL and Redis are reachable.
|
||||
Returns `503 Service Unavailable` when either dependency is disconnected.
|
||||
|
||||
This endpoint is **unauthenticated** — no Bearer token is required.
|
||||
Designed for load-balancer health checks and uptime monitors.
|
||||
security: []
|
||||
responses:
|
||||
'200':
|
||||
description: All services are connected and the application is healthy.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/HealthResponse'
|
||||
example:
|
||||
status: ok
|
||||
version: "1.0.0"
|
||||
uptime: 3724
|
||||
services:
|
||||
postgres: connected
|
||||
redis: connected
|
||||
'503':
|
||||
description: One or more services are disconnected. The application is degraded.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/HealthResponse'
|
||||
example:
|
||||
status: degraded
|
||||
version: "1.0.0"
|
||||
uptime: 3724
|
||||
services:
|
||||
postgres: connected
|
||||
redis: disconnected
|
||||
'500':
|
||||
description: Unexpected server error during health probe.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
example:
|
||||
code: INTERNAL_SERVER_ERROR
|
||||
message: "An unexpected error occurred. Please try again later."
|
||||
|
||||
/health/detailed:
|
||||
get:
|
||||
operationId: getHealthDetailed
|
||||
tags:
|
||||
- Health
|
||||
summary: Detailed dependency health with latency
|
||||
description: |
|
||||
Probes each configured dependency (PostgreSQL, Redis, Vault, OPA) with a
|
||||
3000 ms timeout and reports per-service status and latency.
|
||||
|
||||
**HTTP status codes:**
|
||||
- `200` — all probed services are `healthy`
|
||||
- `207` — at least one service is `degraded` but none are `unreachable`
|
||||
- `503` — at least one service is `unreachable`
|
||||
|
||||
This endpoint is **unauthenticated**.
|
||||
Vault and OPA entries are omitted when not configured via environment variables.
|
||||
security: []
|
||||
responses:
|
||||
'200':
|
||||
description: All probed services are healthy (latency < 1000 ms).
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/DetailedHealthResponse'
|
||||
example:
|
||||
status: healthy
|
||||
version: "1.0.0"
|
||||
uptime: 3724
|
||||
services:
|
||||
postgres:
|
||||
status: healthy
|
||||
latencyMs: 12
|
||||
redis:
|
||||
status: healthy
|
||||
latencyMs: 3
|
||||
'207':
|
||||
description: At least one service is degraded (latency > 1000 ms) but none are unreachable.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/DetailedHealthResponse'
|
||||
example:
|
||||
status: degraded
|
||||
version: "1.0.0"
|
||||
uptime: 3724
|
||||
services:
|
||||
postgres:
|
||||
status: healthy
|
||||
latencyMs: 14
|
||||
redis:
|
||||
status: degraded
|
||||
latencyMs: 1350
|
||||
'503':
|
||||
description: At least one service is unreachable (timed out or connection refused).
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/DetailedHealthResponse'
|
||||
example:
|
||||
status: unreachable
|
||||
version: "1.0.0"
|
||||
uptime: 3724
|
||||
services:
|
||||
postgres:
|
||||
status: unreachable
|
||||
latencyMs: 3000
|
||||
redis:
|
||||
status: healthy
|
||||
latencyMs: 4
|
||||
'500':
|
||||
description: Unexpected server error during health probe.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
example:
|
||||
code: INTERNAL_SERVER_ERROR
|
||||
message: "An unexpected error occurred. Please try again later."
|
||||
388
docs/openapi/marketplace.yaml
Normal file
388
docs/openapi/marketplace.yaml
Normal file
@@ -0,0 +1,388 @@
|
||||
openapi: "3.0.3"
|
||||
|
||||
info:
|
||||
title: SentryAgent.ai — Public Agent Marketplace
|
||||
version: 1.0.0
|
||||
description: |
|
||||
Public Agent Marketplace endpoints for the SentryAgent.ai AgentIdP platform.
|
||||
|
||||
The marketplace enables discovery of AI agents that have been explicitly
|
||||
marked as public (`isPublic: true`) by their owners. It is a read-only
|
||||
public catalog — no authentication required.
|
||||
|
||||
**Feature flag:** When `MARKETPLACE_ENABLED=false` all routes return `404`.
|
||||
|
||||
**Unauthenticated endpoints:**
|
||||
- `GET /marketplace/agents` — Paginated list of public agents with search and filters
|
||||
- `GET /marketplace/agents/:agentId` — Detailed public agent with DID Document
|
||||
|
||||
servers:
|
||||
- url: http://localhost:3000/api/v1
|
||||
description: Local development server
|
||||
- url: https://api.sentryagent.ai/v1
|
||||
description: Production server
|
||||
|
||||
tags:
|
||||
- name: Marketplace
|
||||
description: Public agent discovery endpoints (unauthenticated)
|
||||
|
||||
components:
|
||||
schemas:
|
||||
MinimalDIDDocument:
|
||||
type: object
|
||||
description: Minimal W3C DID Document returned with marketplace agent detail.
|
||||
required:
|
||||
- "@context"
|
||||
- id
|
||||
- controller
|
||||
- verificationMethod
|
||||
- authentication
|
||||
properties:
|
||||
"@context":
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
example:
|
||||
- "https://www.w3.org/ns/did/v1"
|
||||
id:
|
||||
type: string
|
||||
example: "did:web:api.sentryagent.ai:agents:a1b2c3d4-e5f6-7890-abcd-ef1234567890"
|
||||
controller:
|
||||
type: string
|
||||
example: "did:web:api.sentryagent.ai"
|
||||
verificationMethod:
|
||||
type: array
|
||||
items:
|
||||
type: object
|
||||
additionalProperties: true
|
||||
description: Verification methods from the DID Document.
|
||||
authentication:
|
||||
type: array
|
||||
items:
|
||||
type: object
|
||||
additionalProperties: true
|
||||
|
||||
MarketplaceAgentCard:
|
||||
type: object
|
||||
description: |
|
||||
Public agent card returned by the marketplace. Contains only information
|
||||
that the agent owner has explicitly made public.
|
||||
required:
|
||||
- agentId
|
||||
- agentType
|
||||
- version
|
||||
- capabilities
|
||||
- owner
|
||||
- deploymentEnv
|
||||
- publishedAt
|
||||
properties:
|
||||
agentId:
|
||||
type: string
|
||||
format: uuid
|
||||
description: Unique identifier of the agent.
|
||||
example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
|
||||
agentType:
|
||||
type: string
|
||||
description: Functional classification of the agent.
|
||||
enum:
|
||||
- screener
|
||||
- classifier
|
||||
- orchestrator
|
||||
- extractor
|
||||
- summarizer
|
||||
- router
|
||||
- monitor
|
||||
- custom
|
||||
example: "screener"
|
||||
version:
|
||||
type: string
|
||||
description: Semantic version string of the agent.
|
||||
example: "1.4.2"
|
||||
capabilities:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
description: List of capability strings (`resource:action` format).
|
||||
example:
|
||||
- "resume:read"
|
||||
- "email:send"
|
||||
- "candidate:score"
|
||||
owner:
|
||||
type: string
|
||||
description: Team or organization that owns this agent.
|
||||
example: "talent-acquisition-team"
|
||||
deploymentEnv:
|
||||
type: string
|
||||
enum:
|
||||
- development
|
||||
- staging
|
||||
- production
|
||||
example: "production"
|
||||
did:
|
||||
type: string
|
||||
nullable: true
|
||||
description: W3C DID identifier for this agent, if one has been generated.
|
||||
example: "did:web:api.sentryagent.ai:agents:a1b2c3d4-e5f6-7890-abcd-ef1234567890"
|
||||
didDocument:
|
||||
$ref: '#/components/schemas/MinimalDIDDocument'
|
||||
nullable: true
|
||||
description: Minimal W3C DID Document for this agent, if a DID has been generated.
|
||||
publishedAt:
|
||||
type: string
|
||||
format: date-time
|
||||
description: Timestamp when this agent was made public.
|
||||
example: "2026-03-01T08:00:00.000Z"
|
||||
|
||||
PaginatedMarketplaceResponse:
|
||||
type: object
|
||||
description: Paginated marketplace listing response.
|
||||
required:
|
||||
- data
|
||||
- total
|
||||
- page
|
||||
- limit
|
||||
properties:
|
||||
data:
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/components/schemas/MarketplaceAgentCard'
|
||||
total:
|
||||
type: integer
|
||||
description: Total number of public agents matching the query.
|
||||
example: 58
|
||||
page:
|
||||
type: integer
|
||||
description: Current page number (1-based).
|
||||
example: 1
|
||||
limit:
|
||||
type: integer
|
||||
description: Number of results per page.
|
||||
example: 20
|
||||
|
||||
ErrorResponse:
|
||||
type: object
|
||||
description: Standard error response envelope.
|
||||
required:
|
||||
- code
|
||||
- message
|
||||
properties:
|
||||
code:
|
||||
type: string
|
||||
example: "AGENT_NOT_FOUND"
|
||||
message:
|
||||
type: string
|
||||
example: "Agent with the specified ID was not found."
|
||||
details:
|
||||
type: object
|
||||
additionalProperties: true
|
||||
|
||||
paths:
|
||||
/marketplace/agents:
|
||||
get:
|
||||
operationId: listPublicAgents
|
||||
tags:
|
||||
- Marketplace
|
||||
summary: List public agents
|
||||
description: |
|
||||
Returns a paginated list of agents that have been marked as public.
|
||||
|
||||
Supports full-text search across `owner`, `capabilities`, and `agentType`
|
||||
via the `q` parameter. Results can be filtered by `capability` or `publisher`.
|
||||
|
||||
**Unauthenticated** — no Bearer token required.
|
||||
|
||||
Returns `404` when the `MARKETPLACE_ENABLED` feature flag is set to `false`.
|
||||
security: []
|
||||
parameters:
|
||||
- name: q
|
||||
in: query
|
||||
required: false
|
||||
description: |
|
||||
Full-text search query across agent owner, capabilities, and agent type.
|
||||
schema:
|
||||
type: string
|
||||
example: "resume screener"
|
||||
- name: capability
|
||||
in: query
|
||||
required: false
|
||||
description: Filter by a specific capability string (exact match).
|
||||
schema:
|
||||
type: string
|
||||
example: "resume:read"
|
||||
- name: publisher
|
||||
in: query
|
||||
required: false
|
||||
description: Filter by owner/publisher name (exact match).
|
||||
schema:
|
||||
type: string
|
||||
example: "talent-acquisition-team"
|
||||
- name: page
|
||||
in: query
|
||||
required: false
|
||||
schema:
|
||||
type: integer
|
||||
minimum: 1
|
||||
default: 1
|
||||
example: 1
|
||||
- name: limit
|
||||
in: query
|
||||
required: false
|
||||
schema:
|
||||
type: integer
|
||||
minimum: 1
|
||||
maximum: 100
|
||||
default: 20
|
||||
example: 20
|
||||
responses:
|
||||
'200':
|
||||
description: Paginated list of public agents returned successfully.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/PaginatedMarketplaceResponse'
|
||||
example:
|
||||
data:
|
||||
- agentId: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
|
||||
agentType: "screener"
|
||||
version: "1.4.2"
|
||||
capabilities:
|
||||
- "resume:read"
|
||||
- "email:send"
|
||||
- "candidate:score"
|
||||
owner: "talent-acquisition-team"
|
||||
deploymentEnv: "production"
|
||||
did: "did:web:api.sentryagent.ai:agents:a1b2c3d4-e5f6-7890-abcd-ef1234567890"
|
||||
didDocument: null
|
||||
publishedAt: "2026-03-01T08:00:00.000Z"
|
||||
- agentId: "b2c3d4e5-f6a7-8901-bcde-f12345678901"
|
||||
agentType: "classifier"
|
||||
version: "2.1.0"
|
||||
capabilities:
|
||||
- "document:classify"
|
||||
- "label:write"
|
||||
owner: "platform-team"
|
||||
deploymentEnv: "staging"
|
||||
did: null
|
||||
didDocument: null
|
||||
publishedAt: "2026-03-10T10:00:00.000Z"
|
||||
total: 58
|
||||
page: 1
|
||||
limit: 20
|
||||
'400':
|
||||
description: Invalid query parameters.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
example:
|
||||
code: "VALIDATION_ERROR"
|
||||
message: "Invalid query parameter value."
|
||||
details:
|
||||
field: "limit"
|
||||
reason: "Must be between 1 and 100."
|
||||
'404':
|
||||
description: Marketplace is not enabled on this instance.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
example:
|
||||
code: "NOT_FOUND"
|
||||
message: "The Agent Marketplace is not enabled on this instance."
|
||||
'500':
|
||||
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."
|
||||
|
||||
/marketplace/agents/{agentId}:
|
||||
get:
|
||||
operationId: getPublicAgent
|
||||
tags:
|
||||
- Marketplace
|
||||
summary: Get public agent detail
|
||||
description: |
|
||||
Returns the full public profile for a specific marketplace-listed agent,
|
||||
including its DID Document (if a DID has been generated).
|
||||
|
||||
Only agents with `isPublic: true` are accessible via this endpoint.
|
||||
Attempting to retrieve a private agent returns `404`.
|
||||
|
||||
**Unauthenticated** — no Bearer token required.
|
||||
|
||||
Returns `404` when the `MARKETPLACE_ENABLED` feature flag is set to `false`.
|
||||
security: []
|
||||
parameters:
|
||||
- name: agentId
|
||||
in: path
|
||||
required: true
|
||||
description: UUID of the public agent.
|
||||
schema:
|
||||
type: string
|
||||
format: uuid
|
||||
example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
|
||||
responses:
|
||||
'200':
|
||||
description: Public agent detail returned successfully.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/MarketplaceAgentCard'
|
||||
example:
|
||||
agentId: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
|
||||
agentType: "screener"
|
||||
version: "1.4.2"
|
||||
capabilities:
|
||||
- "resume:read"
|
||||
- "email:send"
|
||||
- "candidate:score"
|
||||
owner: "talent-acquisition-team"
|
||||
deploymentEnv: "production"
|
||||
did: "did:web:api.sentryagent.ai:agents:a1b2c3d4-e5f6-7890-abcd-ef1234567890"
|
||||
didDocument:
|
||||
"@context":
|
||||
- "https://www.w3.org/ns/did/v1"
|
||||
id: "did:web:api.sentryagent.ai:agents:a1b2c3d4-e5f6-7890-abcd-ef1234567890"
|
||||
controller: "did:web:api.sentryagent.ai"
|
||||
verificationMethod:
|
||||
- id: "did:web:api.sentryagent.ai:agents:a1b2c3d4-e5f6-7890-abcd-ef1234567890#key-1"
|
||||
type: "JsonWebKey2020"
|
||||
controller: "did:web:api.sentryagent.ai:agents:a1b2c3d4-e5f6-7890-abcd-ef1234567890"
|
||||
publicKeyJwk:
|
||||
kty: "EC"
|
||||
crv: "P-256"
|
||||
x: "f83OJ3D..."
|
||||
y: "x_FEzRu..."
|
||||
authentication:
|
||||
- id: "did:web:api.sentryagent.ai:agents:a1b2c3d4-e5f6-7890-abcd-ef1234567890#key-1"
|
||||
publishedAt: "2026-03-01T08:00:00.000Z"
|
||||
'404':
|
||||
description: Agent not found, not public, or marketplace not enabled.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
examples:
|
||||
agentNotFound:
|
||||
summary: Agent not found or not public
|
||||
value:
|
||||
code: "AGENT_NOT_FOUND"
|
||||
message: "Agent with the specified ID was not found."
|
||||
marketplaceDisabled:
|
||||
summary: Marketplace feature disabled
|
||||
value:
|
||||
code: "NOT_FOUND"
|
||||
message: "The Agent Marketplace is not enabled on this instance."
|
||||
'500':
|
||||
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."
|
||||
106
docs/openapi/metrics.yaml
Normal file
106
docs/openapi/metrics.yaml
Normal file
@@ -0,0 +1,106 @@
|
||||
openapi: "3.0.3"
|
||||
|
||||
info:
|
||||
title: SentryAgent.ai — Prometheus Metrics Endpoint
|
||||
version: 1.0.0
|
||||
description: |
|
||||
Internal Prometheus metrics endpoint for the SentryAgent.ai AgentIdP platform.
|
||||
|
||||
This endpoint returns metrics in **Prometheus text exposition format** (v0.0.4).
|
||||
It is intended exclusively for internal Prometheus scraping.
|
||||
|
||||
**Security notice:** This endpoint is **unauthenticated** and MUST NOT be
|
||||
exposed on a public-facing network interface. Restrict access via network
|
||||
policy, firewall rules, or a reverse-proxy that only allows Prometheus
|
||||
scraper IP ranges to reach `/metrics`.
|
||||
|
||||
Metrics exported include:
|
||||
- HTTP request counts and latencies (by route and status code)
|
||||
- Token issuance, introspection, and revocation counters
|
||||
- Agent registration and decommission counters
|
||||
- Active registered agent gauge
|
||||
- Database connection pool metrics
|
||||
- Process memory and CPU metrics (via `prom-client` defaults)
|
||||
|
||||
servers:
|
||||
- url: http://localhost:3000
|
||||
description: Local development server (internal only)
|
||||
- url: https://api.sentryagent.ai
|
||||
description: Production server (restrict to Prometheus scraper)
|
||||
|
||||
tags:
|
||||
- name: Metrics
|
||||
description: Prometheus metrics scrape endpoint
|
||||
|
||||
components:
|
||||
schemas:
|
||||
PrometheusMetrics:
|
||||
type: string
|
||||
description: |
|
||||
Metrics in Prometheus text exposition format (v0.0.4).
|
||||
Each metric family is preceded by `# HELP` and `# TYPE` comment lines.
|
||||
example: |
|
||||
# HELP process_cpu_user_seconds_total Total user CPU time spent in seconds.
|
||||
# TYPE process_cpu_user_seconds_total counter
|
||||
process_cpu_user_seconds_total 0.123456
|
||||
# HELP http_requests_total Total number of HTTP requests.
|
||||
# TYPE http_requests_total counter
|
||||
http_requests_total{method="POST",route="/api/v1/token",status_code="200"} 4201
|
||||
http_requests_total{method="GET",route="/api/v1/agents",status_code="200"} 987
|
||||
|
||||
ErrorResponse:
|
||||
type: object
|
||||
description: Standard error response envelope.
|
||||
required:
|
||||
- code
|
||||
- message
|
||||
properties:
|
||||
code:
|
||||
type: string
|
||||
example: "INTERNAL_SERVER_ERROR"
|
||||
message:
|
||||
type: string
|
||||
example: "An unexpected error occurred. Please try again later."
|
||||
|
||||
paths:
|
||||
/metrics:
|
||||
get:
|
||||
operationId: scrapeMetrics
|
||||
tags:
|
||||
- Metrics
|
||||
summary: Prometheus metrics scrape endpoint
|
||||
description: |
|
||||
Returns all registered metrics in Prometheus text exposition format.
|
||||
|
||||
The `Content-Type` header in the response is set to the value reported
|
||||
by the `prom-client` registry (`text/plain; version=0.0.4; charset=utf-8`).
|
||||
|
||||
This endpoint is **unauthenticated** and is intended for internal
|
||||
Prometheus scraping only. Do not expose on public interfaces.
|
||||
security: []
|
||||
responses:
|
||||
'200':
|
||||
description: Metrics in Prometheus text exposition format.
|
||||
content:
|
||||
text/plain:
|
||||
schema:
|
||||
$ref: '#/components/schemas/PrometheusMetrics'
|
||||
example: |
|
||||
# HELP process_cpu_user_seconds_total Total user CPU time spent in seconds.
|
||||
# TYPE process_cpu_user_seconds_total counter
|
||||
process_cpu_user_seconds_total 0.123456
|
||||
# HELP sentryagent_tokens_issued_total Total tokens issued.
|
||||
# TYPE sentryagent_tokens_issued_total counter
|
||||
sentryagent_tokens_issued_total 4201
|
||||
# HELP sentryagent_agents_registered_total Total agents registered.
|
||||
# TYPE sentryagent_agents_registered_total counter
|
||||
sentryagent_agents_registered_total 120
|
||||
'500':
|
||||
description: Unexpected error while collecting metrics.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
example:
|
||||
code: INTERNAL_SERVER_ERROR
|
||||
message: "An unexpected error occurred. Please try again later."
|
||||
228
docs/openapi/oidc-token-exchange.yaml
Normal file
228
docs/openapi/oidc-token-exchange.yaml
Normal file
@@ -0,0 +1,228 @@
|
||||
openapi: "3.0.3"
|
||||
|
||||
info:
|
||||
title: SentryAgent.ai — OIDC Token Exchange (Workload Identity Federation)
|
||||
version: 1.0.0
|
||||
description: |
|
||||
OIDC Token Exchange endpoint for Workload Identity Federation on the
|
||||
SentryAgent.ai AgentIdP platform.
|
||||
|
||||
This endpoint allows CI/CD workflows (e.g. GitHub Actions) to exchange their
|
||||
short-lived OIDC JWT for a SentryAgent.ai Bearer access token without requiring
|
||||
long-lived credentials stored as secrets.
|
||||
|
||||
**Flow:**
|
||||
1. Tenant creates a trust policy via `POST /api/v1/oidc/trust-policies`
|
||||
linking a GitHub repo + optional branch to an agent UUID.
|
||||
2. In the GitHub Actions workflow, fetch the OIDC token:
|
||||
```
|
||||
id-token: write # required permissions block
|
||||
OIDC_TOKEN=$(curl -H "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
|
||||
"$ACTIONS_ID_TOKEN_REQUEST_URL" | jq -r .value)
|
||||
```
|
||||
3. POST the GitHub OIDC token to `POST /api/v1/oidc/token`.
|
||||
4. Receive a SentryAgent.ai Bearer token valid for 1 hour.
|
||||
|
||||
**This endpoint is unauthenticated** — the GitHub OIDC JWT IS the credential.
|
||||
Trust-policy enforcement is performed server-side.
|
||||
|
||||
servers:
|
||||
- url: http://localhost:3000/api/v1
|
||||
description: Local development server
|
||||
- url: https://api.sentryagent.ai/v1
|
||||
description: Production server
|
||||
|
||||
tags:
|
||||
- name: OIDC Token Exchange
|
||||
description: Workload Identity Federation token exchange (unauthenticated)
|
||||
|
||||
components:
|
||||
schemas:
|
||||
OIDCTokenExchangeRequest:
|
||||
type: object
|
||||
description: |
|
||||
Request body for exchanging a GitHub OIDC JWT for a SentryAgent.ai access token.
|
||||
required:
|
||||
- token
|
||||
properties:
|
||||
token:
|
||||
type: string
|
||||
description: |
|
||||
The GitHub OIDC JWT obtained from the GitHub Actions token request endpoint.
|
||||
Must be a valid, unexpired JWT signed by GitHub.
|
||||
example: "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJyZXBvOmFjbWUtY29ycC9hZ2VudC1kZXBsb3llcjpyZWY6cmVmcy9oZWFkcy9tYWluIiwiaXNzIjoiaHR0cHM6Ly90b2tlbi5hY3Rpb25zLmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImV4cCI6MTc0MzE1NDgwMH0.signature"
|
||||
|
||||
OIDCTokenExchangeResponse:
|
||||
type: object
|
||||
description: SentryAgent.ai Bearer access token issued in exchange for the OIDC JWT.
|
||||
required:
|
||||
- access_token
|
||||
- token_type
|
||||
- expires_in
|
||||
- scope
|
||||
properties:
|
||||
access_token:
|
||||
type: string
|
||||
description: |
|
||||
Signed JWT access token. Use as `Authorization: Bearer <access_token>`
|
||||
in subsequent API calls.
|
||||
example: "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhMWIyYzNkNC1lNWY2LTc4OTAtYWJjZC1lZjEyMzQ1Njc4OTAiLCJzY29wZSI6ImFnZW50czpyZWFkIGFnZW50czp3cml0ZSIsImlhdCI6MTc0MzE1MTIwMCwiZXhwIjoxNzQzMTU0ODAwfQ.signature"
|
||||
token_type:
|
||||
type: string
|
||||
enum:
|
||||
- Bearer
|
||||
description: Token type. Always `Bearer`.
|
||||
example: "Bearer"
|
||||
expires_in:
|
||||
type: integer
|
||||
description: Token lifetime in seconds from issuance. Default is `3600`.
|
||||
example: 3600
|
||||
scope:
|
||||
type: string
|
||||
description: Space-separated OAuth 2.0 scopes granted by this token.
|
||||
example: "agents:read agents:write"
|
||||
|
||||
ErrorResponse:
|
||||
type: object
|
||||
description: Standard error response envelope.
|
||||
required:
|
||||
- code
|
||||
- message
|
||||
properties:
|
||||
code:
|
||||
type: string
|
||||
example: "TRUST_POLICY_NOT_FOUND"
|
||||
message:
|
||||
type: string
|
||||
example: "No trust policy matches the provided OIDC token claims."
|
||||
details:
|
||||
type: object
|
||||
additionalProperties: true
|
||||
|
||||
responses:
|
||||
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:
|
||||
/oidc/token:
|
||||
post:
|
||||
operationId: exchangeOIDCToken
|
||||
tags:
|
||||
- OIDC Token Exchange
|
||||
summary: Exchange a GitHub OIDC JWT for a SentryAgent.ai access token
|
||||
description: |
|
||||
Exchanges a GitHub Actions OIDC JWT for a SentryAgent.ai Bearer access token.
|
||||
|
||||
**Verification steps performed server-side:**
|
||||
1. Decode and validate the GitHub OIDC JWT signature against GitHub's JWKS.
|
||||
2. Verify the token is not expired.
|
||||
3. Match the token's `sub` claim (format: `repo:<org>/<repo>:ref:refs/heads/<branch>`)
|
||||
against registered trust policies.
|
||||
4. Apply branch constraint if the matching policy has one.
|
||||
5. Verify the linked agent is active and not decommissioned.
|
||||
6. Issue a SentryAgent.ai access token scoped to the linked agent.
|
||||
|
||||
**This endpoint is unauthenticated** — the GitHub OIDC JWT serves as the credential.
|
||||
|
||||
**GitHub Actions example:**
|
||||
```yaml
|
||||
permissions:
|
||||
id-token: write
|
||||
contents: read
|
||||
|
||||
steps:
|
||||
- name: Get OIDC token and exchange
|
||||
run: |
|
||||
GITHUB_TOKEN=$(curl -sH "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
|
||||
"$ACTIONS_ID_TOKEN_REQUEST_URL&audience=api.sentryagent.ai" | jq -r .value)
|
||||
AGENT_TOKEN=$(curl -sX POST https://api.sentryagent.ai/api/v1/oidc/token \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d "{\"token\": \"$GITHUB_TOKEN\"}" | jq -r .access_token)
|
||||
```
|
||||
security: []
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/OIDCTokenExchangeRequest'
|
||||
example:
|
||||
token: "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJyZXBvOmFjbWUtY29ycC9hZ2VudC1kZXBsb3llcjpyZWY6cmVmcy9oZWFkcy9tYWluIiwiaXNzIjoiaHR0cHM6Ly90b2tlbi5hY3Rpb25zLmdpdGh1YnVzZXJjb250ZW50LmNvbSJ9.signature"
|
||||
responses:
|
||||
'200':
|
||||
description: SentryAgent.ai access token issued successfully.
|
||||
headers:
|
||||
Cache-Control:
|
||||
schema:
|
||||
type: string
|
||||
description: Token responses must not be cached.
|
||||
example: "no-store"
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/OIDCTokenExchangeResponse'
|
||||
example:
|
||||
access_token: "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhMWIyYzNkNC1lNWY2LTc4OTAtYWJjZC1lZjEyMzQ1Njc4OTAiLCJzY29wZSI6ImFnZW50czpyZWFkIGFnZW50czp3cml0ZSIsImlhdCI6MTc0MzE1MTIwMCwiZXhwIjoxNzQzMTU0ODAwfQ.signature"
|
||||
token_type: "Bearer"
|
||||
expires_in: 3600
|
||||
scope: "agents:read agents:write"
|
||||
'400':
|
||||
description: Missing or malformed `token` field in request body.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
example:
|
||||
code: "VALIDATION_ERROR"
|
||||
message: "The 'token' field is required."
|
||||
'401':
|
||||
description: The provided OIDC token is invalid, expired, or has an invalid signature.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
examples:
|
||||
expired:
|
||||
summary: Token is expired
|
||||
value:
|
||||
code: "OIDC_TOKEN_EXPIRED"
|
||||
message: "The provided GitHub OIDC token has expired."
|
||||
invalidSignature:
|
||||
summary: Invalid signature
|
||||
value:
|
||||
code: "OIDC_TOKEN_INVALID"
|
||||
message: "The provided GitHub OIDC token signature is invalid."
|
||||
'403':
|
||||
description: Token claims do not match any active trust policy, or the linked agent is inactive.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
examples:
|
||||
noPolicy:
|
||||
summary: No matching trust policy
|
||||
value:
|
||||
code: "TRUST_POLICY_NOT_FOUND"
|
||||
message: "No trust policy matches the provided OIDC token claims."
|
||||
branchMismatch:
|
||||
summary: Branch constraint not satisfied
|
||||
value:
|
||||
code: "TRUST_POLICY_BRANCH_MISMATCH"
|
||||
message: "The token's branch does not match the trust policy constraint."
|
||||
details:
|
||||
allowed: "main"
|
||||
provided: "feature/xyz"
|
||||
agentSuspended:
|
||||
summary: Linked agent is suspended
|
||||
value:
|
||||
code: "AGENT_SUSPENDED"
|
||||
message: "The agent linked to this trust policy is currently suspended."
|
||||
'500':
|
||||
$ref: '#/components/responses/InternalServerError'
|
||||
384
docs/openapi/oidc-trust-policies.yaml
Normal file
384
docs/openapi/oidc-trust-policies.yaml
Normal file
@@ -0,0 +1,384 @@
|
||||
openapi: "3.0.3"
|
||||
|
||||
info:
|
||||
title: SentryAgent.ai — OIDC Trust Policies
|
||||
version: 1.0.0
|
||||
description: |
|
||||
OIDC trust policy management endpoints for the SentryAgent.ai AgentIdP platform.
|
||||
|
||||
Trust policies allow tenants to configure Workload Identity Federation:
|
||||
workflows running in a trusted OIDC provider (e.g. GitHub Actions) can exchange
|
||||
their OIDC JWT for a SentryAgent.ai access token without long-lived credentials.
|
||||
|
||||
**Supported OIDC providers:** `github`
|
||||
|
||||
**Workflow:**
|
||||
1. Create a trust policy linking a GitHub repo (+ optional branch) to an agent UUID
|
||||
2. In your GitHub Actions workflow, call `POST /api/v1/oidc/token` with the GitHub OIDC JWT
|
||||
3. Receive a SentryAgent.ai Bearer token scoped to the linked agent
|
||||
|
||||
**All endpoints require a valid Bearer JWT.**
|
||||
|
||||
servers:
|
||||
- url: http://localhost:3000/api/v1
|
||||
description: Local development server
|
||||
- url: https://api.sentryagent.ai/v1
|
||||
description: Production server
|
||||
|
||||
tags:
|
||||
- name: OIDC Trust Policies
|
||||
description: Workload Identity Federation trust policy management
|
||||
|
||||
components:
|
||||
securitySchemes:
|
||||
BearerAuth:
|
||||
type: http
|
||||
scheme: bearer
|
||||
bearerFormat: JWT
|
||||
description: |
|
||||
JWT access token obtained via `POST /token`.
|
||||
Include as `Authorization: Bearer <token>`.
|
||||
|
||||
schemas:
|
||||
OIDCProvider:
|
||||
type: string
|
||||
enum:
|
||||
- github
|
||||
description: |
|
||||
Supported OIDC provider identifier.
|
||||
Currently only "github" is supported; the list is extensible.
|
||||
example: github
|
||||
|
||||
OIDCTrustPolicy:
|
||||
type: object
|
||||
description: A persisted OIDC trust policy record.
|
||||
required:
|
||||
- id
|
||||
- provider
|
||||
- repository
|
||||
- agentId
|
||||
- createdAt
|
||||
- updatedAt
|
||||
properties:
|
||||
id:
|
||||
type: string
|
||||
format: uuid
|
||||
description: Immutable system-assigned UUID for this trust policy.
|
||||
readOnly: true
|
||||
example: "tp-abcd-1234-5678-ef01"
|
||||
provider:
|
||||
$ref: '#/components/schemas/OIDCProvider'
|
||||
repository:
|
||||
type: string
|
||||
description: |
|
||||
GitHub repository in "org/repo" format.
|
||||
Only workflows running in this repository may exchange tokens.
|
||||
pattern: '^[a-zA-Z0-9._-]+/[a-zA-Z0-9._-]+$'
|
||||
example: "acme-corp/agent-deployer"
|
||||
branch:
|
||||
type: string
|
||||
nullable: true
|
||||
description: |
|
||||
Optional branch constraint. When set, only the specified branch may
|
||||
exchange tokens. When null, any branch in the repository is allowed.
|
||||
example: "main"
|
||||
agentId:
|
||||
type: string
|
||||
format: uuid
|
||||
description: UUID of the agent this trust policy grants access to.
|
||||
example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
|
||||
createdAt:
|
||||
type: string
|
||||
format: date-time
|
||||
readOnly: true
|
||||
example: "2026-03-01T08:00:00.000Z"
|
||||
updatedAt:
|
||||
type: string
|
||||
format: date-time
|
||||
readOnly: true
|
||||
example: "2026-03-28T11:30:00.000Z"
|
||||
|
||||
CreateTrustPolicyRequest:
|
||||
type: object
|
||||
description: Request body for registering a new OIDC trust policy.
|
||||
required:
|
||||
- provider
|
||||
- repository
|
||||
- agentId
|
||||
properties:
|
||||
provider:
|
||||
$ref: '#/components/schemas/OIDCProvider'
|
||||
repository:
|
||||
type: string
|
||||
description: |
|
||||
GitHub repository in "org/repo" format. Case-sensitive.
|
||||
Only workflows in this repository may use this trust policy.
|
||||
pattern: '^[a-zA-Z0-9._-]+/[a-zA-Z0-9._-]+$'
|
||||
example: "acme-corp/agent-deployer"
|
||||
branch:
|
||||
type: string
|
||||
description: |
|
||||
Optional branch constraint. When omitted, any branch in the repository is permitted.
|
||||
Recommended to set this to `main` for production trust policies.
|
||||
example: "main"
|
||||
agentId:
|
||||
type: string
|
||||
format: uuid
|
||||
description: |
|
||||
UUID of the agent to grant access to.
|
||||
The agent must be registered and active in the same organization.
|
||||
example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
|
||||
|
||||
ErrorResponse:
|
||||
type: object
|
||||
description: Standard error response envelope.
|
||||
required:
|
||||
- code
|
||||
- message
|
||||
properties:
|
||||
code:
|
||||
type: string
|
||||
example: "TRUST_POLICY_NOT_FOUND"
|
||||
message:
|
||||
type: string
|
||||
example: "Trust policy with the specified ID was not found."
|
||||
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."
|
||||
|
||||
Forbidden:
|
||||
description: Valid token but insufficient permissions.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
example:
|
||||
code: "FORBIDDEN"
|
||||
message: "You do not have permission to perform this action."
|
||||
|
||||
NotFound:
|
||||
description: Trust policy not found.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
example:
|
||||
code: "TRUST_POLICY_NOT_FOUND"
|
||||
message: "Trust policy 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."
|
||||
|
||||
security:
|
||||
- BearerAuth: []
|
||||
|
||||
paths:
|
||||
/oidc/trust-policies:
|
||||
post:
|
||||
operationId: createOIDCTrustPolicy
|
||||
tags:
|
||||
- OIDC Trust Policies
|
||||
summary: Create an OIDC trust policy
|
||||
description: |
|
||||
Registers a new OIDC trust policy.
|
||||
|
||||
Once created, workflows running in the specified GitHub repository
|
||||
(and optionally matching the specified branch) can exchange their
|
||||
GitHub OIDC JWT for a SentryAgent.ai access token via `POST /oidc/token`.
|
||||
|
||||
A trust policy is organization-scoped — the agent referenced by `agentId`
|
||||
must belong to the same organization as the authenticated caller.
|
||||
|
||||
Requires a valid Bearer JWT (minimum `agents:write` scope recommended).
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/CreateTrustPolicyRequest'
|
||||
example:
|
||||
provider: "github"
|
||||
repository: "acme-corp/agent-deployer"
|
||||
branch: "main"
|
||||
agentId: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
|
||||
responses:
|
||||
'201':
|
||||
description: Trust policy created successfully.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/OIDCTrustPolicy'
|
||||
example:
|
||||
id: "tp-abcd-1234-5678-ef01"
|
||||
provider: "github"
|
||||
repository: "acme-corp/agent-deployer"
|
||||
branch: "main"
|
||||
agentId: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
|
||||
createdAt: "2026-04-07T09:00:00.000Z"
|
||||
updatedAt: "2026-04-07T09:00:00.000Z"
|
||||
'400':
|
||||
description: Validation error in request body.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
examples:
|
||||
invalidProvider:
|
||||
summary: Unsupported OIDC provider
|
||||
value:
|
||||
code: "VALIDATION_ERROR"
|
||||
message: "Request validation failed."
|
||||
details:
|
||||
field: "provider"
|
||||
reason: "Only 'github' is supported."
|
||||
invalidRepository:
|
||||
summary: Invalid repository format
|
||||
value:
|
||||
code: "VALIDATION_ERROR"
|
||||
message: "Request validation failed."
|
||||
details:
|
||||
field: "repository"
|
||||
reason: "Must be in 'org/repo' format."
|
||||
'401':
|
||||
$ref: '#/components/responses/Unauthorized'
|
||||
'403':
|
||||
$ref: '#/components/responses/Forbidden'
|
||||
'404':
|
||||
description: Referenced agent not found in this organization.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
example:
|
||||
code: "AGENT_NOT_FOUND"
|
||||
message: "Agent with the specified ID was not found."
|
||||
'409':
|
||||
description: A trust policy for this provider/repository/branch combination already exists.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
example:
|
||||
code: "TRUST_POLICY_CONFLICT"
|
||||
message: "A trust policy for this repository and branch already exists."
|
||||
details:
|
||||
provider: "github"
|
||||
repository: "acme-corp/agent-deployer"
|
||||
branch: "main"
|
||||
'500':
|
||||
$ref: '#/components/responses/InternalServerError'
|
||||
|
||||
get:
|
||||
operationId: listOIDCTrustPolicies
|
||||
tags:
|
||||
- OIDC Trust Policies
|
||||
summary: List OIDC trust policies
|
||||
description: |
|
||||
Returns all trust policies for the authenticated organization,
|
||||
optionally filtered by the `agentId` query parameter.
|
||||
|
||||
Requires a valid Bearer JWT.
|
||||
parameters:
|
||||
- name: agentId
|
||||
in: query
|
||||
required: false
|
||||
description: Filter trust policies linked to a specific agent UUID.
|
||||
schema:
|
||||
type: string
|
||||
format: uuid
|
||||
example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
|
||||
responses:
|
||||
'200':
|
||||
description: List of trust policies returned successfully.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/components/schemas/OIDCTrustPolicy'
|
||||
example:
|
||||
- id: "tp-abcd-1234-5678-ef01"
|
||||
provider: "github"
|
||||
repository: "acme-corp/agent-deployer"
|
||||
branch: "main"
|
||||
agentId: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
|
||||
createdAt: "2026-03-01T08:00:00.000Z"
|
||||
updatedAt: "2026-03-01T08:00:00.000Z"
|
||||
- id: "tp-efgh-5678-1234-ab01"
|
||||
provider: "github"
|
||||
repository: "acme-corp/inference-runner"
|
||||
branch: null
|
||||
agentId: "b2c3d4e5-f6a7-8901-bcde-f12345678901"
|
||||
createdAt: "2026-03-15T10:00:00.000Z"
|
||||
updatedAt: "2026-03-15T10:00:00.000Z"
|
||||
'400':
|
||||
description: Invalid query parameters.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
example:
|
||||
code: "VALIDATION_ERROR"
|
||||
message: "Invalid query parameter value."
|
||||
details:
|
||||
field: "agentId"
|
||||
reason: "Must be a valid UUID."
|
||||
'401':
|
||||
$ref: '#/components/responses/Unauthorized'
|
||||
'403':
|
||||
$ref: '#/components/responses/Forbidden'
|
||||
'500':
|
||||
$ref: '#/components/responses/InternalServerError'
|
||||
|
||||
/oidc/trust-policies/{id}:
|
||||
parameters:
|
||||
- name: id
|
||||
in: path
|
||||
required: true
|
||||
description: UUID of the trust policy to delete.
|
||||
schema:
|
||||
type: string
|
||||
format: uuid
|
||||
example: "tp-abcd-1234-5678-ef01"
|
||||
|
||||
delete:
|
||||
operationId: deleteOIDCTrustPolicy
|
||||
tags:
|
||||
- OIDC Trust Policies
|
||||
summary: Delete an OIDC trust policy
|
||||
description: |
|
||||
Permanently deletes an OIDC trust policy.
|
||||
|
||||
After deletion, workflows that previously used this policy to exchange
|
||||
GitHub OIDC tokens will receive `403 Forbidden` from `POST /oidc/token`.
|
||||
|
||||
Requires a valid Bearer JWT.
|
||||
responses:
|
||||
'204':
|
||||
description: Trust policy deleted successfully. No response body.
|
||||
'401':
|
||||
$ref: '#/components/responses/Unauthorized'
|
||||
'403':
|
||||
$ref: '#/components/responses/Forbidden'
|
||||
'404':
|
||||
$ref: '#/components/responses/NotFound'
|
||||
'500':
|
||||
$ref: '#/components/responses/InternalServerError'
|
||||
410
docs/openapi/oidc-wellknown.yaml
Normal file
410
docs/openapi/oidc-wellknown.yaml
Normal file
@@ -0,0 +1,410 @@
|
||||
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'
|
||||
707
docs/openapi/organizations.yaml
Normal file
707
docs/openapi/organizations.yaml
Normal file
@@ -0,0 +1,707 @@
|
||||
openapi: "3.0.3"
|
||||
|
||||
info:
|
||||
title: SentryAgent.ai — Organizations (Multi-Tenancy)
|
||||
version: 1.0.0
|
||||
description: |
|
||||
Organization (tenant) management endpoints for the SentryAgent.ai AgentIdP platform.
|
||||
|
||||
Organizations are the top-level multi-tenancy boundary. Each organization has its
|
||||
own pool of registered agents, plan-tier limits, and billing context.
|
||||
|
||||
**All endpoints require a valid Bearer JWT** with appropriate OPA-enforced scope.
|
||||
|
||||
**Plan Tiers:**
|
||||
| Tier | Max Agents | Max Tokens/Month |
|
||||
|------|-----------|-----------------|
|
||||
| `free` | 100 | 10,000 |
|
||||
| `pro` | 1,000 | 100,000 |
|
||||
| `enterprise` | unlimited | unlimited |
|
||||
|
||||
servers:
|
||||
- url: http://localhost:3000/api/v1
|
||||
description: Local development server
|
||||
- url: https://api.sentryagent.ai/v1
|
||||
description: Production server
|
||||
|
||||
tags:
|
||||
- name: Organizations
|
||||
description: CRUD operations for organizations (tenants)
|
||||
- name: Organization Members
|
||||
description: Agent membership management within organizations
|
||||
|
||||
components:
|
||||
securitySchemes:
|
||||
BearerAuth:
|
||||
type: http
|
||||
scheme: bearer
|
||||
bearerFormat: JWT
|
||||
description: |
|
||||
JWT access token obtained via `POST /token`.
|
||||
Include as `Authorization: Bearer <token>`.
|
||||
|
||||
schemas:
|
||||
PlanTier:
|
||||
type: string
|
||||
enum:
|
||||
- free
|
||||
- pro
|
||||
- enterprise
|
||||
description: Subscription plan tier for an organization.
|
||||
example: pro
|
||||
|
||||
OrgStatus:
|
||||
type: string
|
||||
enum:
|
||||
- active
|
||||
- suspended
|
||||
- deleted
|
||||
description: Lifecycle status of an organization.
|
||||
example: active
|
||||
|
||||
OrgRole:
|
||||
type: string
|
||||
enum:
|
||||
- member
|
||||
- admin
|
||||
description: Role of an agent within an organization.
|
||||
example: member
|
||||
|
||||
Organization:
|
||||
type: object
|
||||
description: Full representation of a registered organization (tenant).
|
||||
required:
|
||||
- organizationId
|
||||
- name
|
||||
- slug
|
||||
- planTier
|
||||
- maxAgents
|
||||
- maxTokensPerMonth
|
||||
- status
|
||||
- createdAt
|
||||
- updatedAt
|
||||
properties:
|
||||
organizationId:
|
||||
type: string
|
||||
format: uuid
|
||||
description: Immutable, system-assigned unique identifier for the organization.
|
||||
readOnly: true
|
||||
example: "org-1234-5678-abcd-ef01"
|
||||
name:
|
||||
type: string
|
||||
description: Human-readable display name of the organization.
|
||||
minLength: 1
|
||||
maxLength: 256
|
||||
example: "Acme Corp"
|
||||
slug:
|
||||
type: string
|
||||
description: |
|
||||
URL-friendly unique identifier. Lowercase letters, digits, and hyphens only.
|
||||
Immutable after creation.
|
||||
pattern: '^[a-z0-9-]+$'
|
||||
example: "acme-corp"
|
||||
planTier:
|
||||
$ref: '#/components/schemas/PlanTier'
|
||||
maxAgents:
|
||||
type: integer
|
||||
description: Maximum number of agents permitted in this organization.
|
||||
minimum: 1
|
||||
example: 100
|
||||
maxTokensPerMonth:
|
||||
type: integer
|
||||
description: Maximum OAuth 2.0 token requests per calendar month.
|
||||
minimum: 1
|
||||
example: 10000
|
||||
status:
|
||||
$ref: '#/components/schemas/OrgStatus'
|
||||
createdAt:
|
||||
type: string
|
||||
format: date-time
|
||||
readOnly: true
|
||||
example: "2026-03-01T08:00:00.000Z"
|
||||
updatedAt:
|
||||
type: string
|
||||
format: date-time
|
||||
readOnly: true
|
||||
example: "2026-03-28T11:30:00.000Z"
|
||||
|
||||
CreateOrgRequest:
|
||||
type: object
|
||||
description: Request body for creating a new organization.
|
||||
required:
|
||||
- name
|
||||
- slug
|
||||
properties:
|
||||
name:
|
||||
type: string
|
||||
description: Human-readable display name.
|
||||
minLength: 1
|
||||
maxLength: 256
|
||||
example: "Acme Corp"
|
||||
slug:
|
||||
type: string
|
||||
description: URL-friendly unique identifier. Lowercase letters, digits, hyphens only.
|
||||
pattern: '^[a-z0-9-]+$'
|
||||
minLength: 1
|
||||
maxLength: 64
|
||||
example: "acme-corp"
|
||||
planTier:
|
||||
$ref: '#/components/schemas/PlanTier'
|
||||
description: Defaults to `free` when omitted.
|
||||
maxAgents:
|
||||
type: integer
|
||||
description: Override the default max agents for this plan tier.
|
||||
minimum: 1
|
||||
example: 100
|
||||
maxTokensPerMonth:
|
||||
type: integer
|
||||
description: Override the default max tokens per month.
|
||||
minimum: 1
|
||||
example: 10000
|
||||
|
||||
UpdateOrgRequest:
|
||||
type: object
|
||||
description: |
|
||||
Request body for partially updating an organization.
|
||||
All fields are optional; only provided fields are updated.
|
||||
`status` may only be set to `active` or `suspended` via this endpoint;
|
||||
`deleted` is applied only through the DELETE operation.
|
||||
minProperties: 1
|
||||
properties:
|
||||
name:
|
||||
type: string
|
||||
minLength: 1
|
||||
maxLength: 256
|
||||
example: "Acme Corporation"
|
||||
planTier:
|
||||
$ref: '#/components/schemas/PlanTier'
|
||||
maxAgents:
|
||||
type: integer
|
||||
minimum: 1
|
||||
example: 1000
|
||||
maxTokensPerMonth:
|
||||
type: integer
|
||||
minimum: 1
|
||||
example: 100000
|
||||
status:
|
||||
type: string
|
||||
enum:
|
||||
- active
|
||||
- suspended
|
||||
description: Set to `active` to reactivate a suspended org, or `suspended` to disable it.
|
||||
example: active
|
||||
|
||||
PaginatedOrgsResponse:
|
||||
type: object
|
||||
description: Paginated list of organizations.
|
||||
required:
|
||||
- data
|
||||
- total
|
||||
- page
|
||||
- limit
|
||||
properties:
|
||||
data:
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/components/schemas/Organization'
|
||||
total:
|
||||
type: integer
|
||||
example: 42
|
||||
page:
|
||||
type: integer
|
||||
example: 1
|
||||
limit:
|
||||
type: integer
|
||||
example: 20
|
||||
|
||||
OrgMember:
|
||||
type: object
|
||||
description: An agent's membership record within an organization.
|
||||
required:
|
||||
- memberId
|
||||
- organizationId
|
||||
- agentId
|
||||
- role
|
||||
- joinedAt
|
||||
properties:
|
||||
memberId:
|
||||
type: string
|
||||
format: uuid
|
||||
readOnly: true
|
||||
example: "mem-abcd-1234-5678-ef01"
|
||||
organizationId:
|
||||
type: string
|
||||
format: uuid
|
||||
example: "org-1234-5678-abcd-ef01"
|
||||
agentId:
|
||||
type: string
|
||||
format: uuid
|
||||
example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
|
||||
role:
|
||||
$ref: '#/components/schemas/OrgRole'
|
||||
joinedAt:
|
||||
type: string
|
||||
format: date-time
|
||||
readOnly: true
|
||||
example: "2026-03-28T09:00:00.000Z"
|
||||
|
||||
AddMemberRequest:
|
||||
type: object
|
||||
description: Request body for adding an agent to an organization.
|
||||
required:
|
||||
- agentId
|
||||
- role
|
||||
properties:
|
||||
agentId:
|
||||
type: string
|
||||
format: uuid
|
||||
description: UUID of the agent to add.
|
||||
example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
|
||||
role:
|
||||
$ref: '#/components/schemas/OrgRole'
|
||||
|
||||
ErrorResponse:
|
||||
type: object
|
||||
description: Standard error response envelope.
|
||||
required:
|
||||
- code
|
||||
- message
|
||||
properties:
|
||||
code:
|
||||
type: string
|
||||
example: "VALIDATION_ERROR"
|
||||
message:
|
||||
type: string
|
||||
example: "Request validation failed."
|
||||
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."
|
||||
|
||||
Forbidden:
|
||||
description: Valid token but insufficient permissions.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
example:
|
||||
code: "FORBIDDEN"
|
||||
message: "You do not have permission to perform this action."
|
||||
|
||||
NotFound:
|
||||
description: Organization not found.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
example:
|
||||
code: "ORG_NOT_FOUND"
|
||||
message: "Organization with the specified ID was not found."
|
||||
|
||||
TooManyRequests:
|
||||
description: Rate limit exceeded.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
example:
|
||||
code: "RATE_LIMIT_EXCEEDED"
|
||||
message: "Too many requests. Please retry after the rate limit window resets."
|
||||
|
||||
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."
|
||||
|
||||
security:
|
||||
- BearerAuth: []
|
||||
|
||||
paths:
|
||||
/organizations:
|
||||
post:
|
||||
operationId: createOrganization
|
||||
tags:
|
||||
- Organizations
|
||||
summary: Create a new organization
|
||||
description: |
|
||||
Creates a new organization (tenant). The `slug` must be unique across all organizations
|
||||
and is immutable after creation.
|
||||
|
||||
The requesting agent's organization context is determined from the Bearer token.
|
||||
Requires `admin:orgs` scope.
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/CreateOrgRequest'
|
||||
example:
|
||||
name: "Acme Corp"
|
||||
slug: "acme-corp"
|
||||
planTier: "pro"
|
||||
maxAgents: 500
|
||||
maxTokensPerMonth: 50000
|
||||
responses:
|
||||
'201':
|
||||
description: Organization created successfully.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/Organization'
|
||||
example:
|
||||
organizationId: "org-1234-5678-abcd-ef01"
|
||||
name: "Acme Corp"
|
||||
slug: "acme-corp"
|
||||
planTier: "pro"
|
||||
maxAgents: 500
|
||||
maxTokensPerMonth: 50000
|
||||
status: "active"
|
||||
createdAt: "2026-04-07T09:00:00.000Z"
|
||||
updatedAt: "2026-04-07T09:00:00.000Z"
|
||||
'400':
|
||||
description: Validation error in request body.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
example:
|
||||
code: "VALIDATION_ERROR"
|
||||
message: "Request validation failed."
|
||||
details:
|
||||
field: "slug"
|
||||
reason: "slug must contain only lowercase letters, digits, and hyphens."
|
||||
'401':
|
||||
$ref: '#/components/responses/Unauthorized'
|
||||
'403':
|
||||
$ref: '#/components/responses/Forbidden'
|
||||
'409':
|
||||
description: An organization with the provided slug already exists.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
example:
|
||||
code: "ORG_SLUG_CONFLICT"
|
||||
message: "An organization with this slug already exists."
|
||||
details:
|
||||
slug: "acme-corp"
|
||||
'429':
|
||||
$ref: '#/components/responses/TooManyRequests'
|
||||
'500':
|
||||
$ref: '#/components/responses/InternalServerError'
|
||||
|
||||
get:
|
||||
operationId: listOrganizations
|
||||
tags:
|
||||
- Organizations
|
||||
summary: List organizations
|
||||
description: |
|
||||
Returns a paginated list of organizations. Results can be filtered by `status`.
|
||||
Results are ordered by `createdAt` descending.
|
||||
|
||||
Requires `admin:orgs` scope.
|
||||
parameters:
|
||||
- name: page
|
||||
in: query
|
||||
required: false
|
||||
schema:
|
||||
type: integer
|
||||
minimum: 1
|
||||
default: 1
|
||||
example: 1
|
||||
- name: limit
|
||||
in: query
|
||||
required: false
|
||||
schema:
|
||||
type: integer
|
||||
minimum: 1
|
||||
maximum: 100
|
||||
default: 20
|
||||
example: 20
|
||||
- name: status
|
||||
in: query
|
||||
required: false
|
||||
schema:
|
||||
$ref: '#/components/schemas/OrgStatus'
|
||||
responses:
|
||||
'200':
|
||||
description: Paginated list of organizations returned successfully.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/PaginatedOrgsResponse'
|
||||
example:
|
||||
data:
|
||||
- organizationId: "org-1234-5678-abcd-ef01"
|
||||
name: "Acme Corp"
|
||||
slug: "acme-corp"
|
||||
planTier: "pro"
|
||||
maxAgents: 500
|
||||
maxTokensPerMonth: 50000
|
||||
status: "active"
|
||||
createdAt: "2026-03-01T08:00:00.000Z"
|
||||
updatedAt: "2026-03-28T11:30:00.000Z"
|
||||
total: 42
|
||||
page: 1
|
||||
limit: 20
|
||||
'400':
|
||||
description: Invalid query parameters.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
example:
|
||||
code: "VALIDATION_ERROR"
|
||||
message: "Invalid query parameter value."
|
||||
'401':
|
||||
$ref: '#/components/responses/Unauthorized'
|
||||
'403':
|
||||
$ref: '#/components/responses/Forbidden'
|
||||
'429':
|
||||
$ref: '#/components/responses/TooManyRequests'
|
||||
'500':
|
||||
$ref: '#/components/responses/InternalServerError'
|
||||
|
||||
/organizations/{orgId}:
|
||||
parameters:
|
||||
- name: orgId
|
||||
in: path
|
||||
required: true
|
||||
description: The unique UUID identifier of the organization.
|
||||
schema:
|
||||
type: string
|
||||
format: uuid
|
||||
example: "org-1234-5678-abcd-ef01"
|
||||
|
||||
get:
|
||||
operationId: getOrganization
|
||||
tags:
|
||||
- Organizations
|
||||
summary: Get organization by ID
|
||||
description: |
|
||||
Retrieves the full record for a single organization.
|
||||
Requires `admin:orgs` scope.
|
||||
responses:
|
||||
'200':
|
||||
description: Organization record returned successfully.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/Organization'
|
||||
example:
|
||||
organizationId: "org-1234-5678-abcd-ef01"
|
||||
name: "Acme Corp"
|
||||
slug: "acme-corp"
|
||||
planTier: "pro"
|
||||
maxAgents: 500
|
||||
maxTokensPerMonth: 50000
|
||||
status: "active"
|
||||
createdAt: "2026-03-01T08:00:00.000Z"
|
||||
updatedAt: "2026-03-28T11:30:00.000Z"
|
||||
'401':
|
||||
$ref: '#/components/responses/Unauthorized'
|
||||
'403':
|
||||
$ref: '#/components/responses/Forbidden'
|
||||
'404':
|
||||
$ref: '#/components/responses/NotFound'
|
||||
'500':
|
||||
$ref: '#/components/responses/InternalServerError'
|
||||
|
||||
patch:
|
||||
operationId: updateOrganization
|
||||
tags:
|
||||
- Organizations
|
||||
summary: Update organization metadata
|
||||
description: |
|
||||
Partially updates an organization's metadata.
|
||||
Only provided fields are updated; omitted fields are unchanged.
|
||||
`slug` and `organizationId` are immutable.
|
||||
Requires `admin:orgs` scope.
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/UpdateOrgRequest'
|
||||
example:
|
||||
name: "Acme Corporation"
|
||||
planTier: "enterprise"
|
||||
responses:
|
||||
'200':
|
||||
description: Organization updated successfully.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/Organization'
|
||||
example:
|
||||
organizationId: "org-1234-5678-abcd-ef01"
|
||||
name: "Acme Corporation"
|
||||
slug: "acme-corp"
|
||||
planTier: "enterprise"
|
||||
maxAgents: 500
|
||||
maxTokensPerMonth: 50000
|
||||
status: "active"
|
||||
createdAt: "2026-03-01T08:00:00.000Z"
|
||||
updatedAt: "2026-04-07T09:00:00.000Z"
|
||||
'400':
|
||||
description: Validation error or attempt to modify an immutable field.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
example:
|
||||
code: "VALIDATION_ERROR"
|
||||
message: "Request validation failed."
|
||||
'401':
|
||||
$ref: '#/components/responses/Unauthorized'
|
||||
'403':
|
||||
$ref: '#/components/responses/Forbidden'
|
||||
'404':
|
||||
$ref: '#/components/responses/NotFound'
|
||||
'429':
|
||||
$ref: '#/components/responses/TooManyRequests'
|
||||
'500':
|
||||
$ref: '#/components/responses/InternalServerError'
|
||||
|
||||
delete:
|
||||
operationId: deleteOrganization
|
||||
tags:
|
||||
- Organizations
|
||||
summary: Soft-delete an organization
|
||||
description: |
|
||||
Permanently soft-deletes an organization by setting its status to `deleted`.
|
||||
The record is retained for audit purposes.
|
||||
|
||||
**Effects:**
|
||||
- All agents within the organization are suspended.
|
||||
- No new tokens may be issued for agents in this organization.
|
||||
- This operation is **irreversible** via the API.
|
||||
|
||||
Requires `admin:orgs` scope.
|
||||
responses:
|
||||
'204':
|
||||
description: Organization soft-deleted successfully. No response body.
|
||||
'401':
|
||||
$ref: '#/components/responses/Unauthorized'
|
||||
'403':
|
||||
$ref: '#/components/responses/Forbidden'
|
||||
'404':
|
||||
$ref: '#/components/responses/NotFound'
|
||||
'409':
|
||||
description: Organization is already deleted.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
example:
|
||||
code: "ORG_ALREADY_DELETED"
|
||||
message: "This organization has already been deleted."
|
||||
'429':
|
||||
$ref: '#/components/responses/TooManyRequests'
|
||||
'500':
|
||||
$ref: '#/components/responses/InternalServerError'
|
||||
|
||||
/organizations/{orgId}/members:
|
||||
parameters:
|
||||
- name: orgId
|
||||
in: path
|
||||
required: true
|
||||
description: The unique UUID identifier of the organization.
|
||||
schema:
|
||||
type: string
|
||||
format: uuid
|
||||
example: "org-1234-5678-abcd-ef01"
|
||||
|
||||
post:
|
||||
operationId: addOrganizationMember
|
||||
tags:
|
||||
- Organization Members
|
||||
summary: Add an agent as a member of an organization
|
||||
description: |
|
||||
Adds a registered agent to an organization with the specified role.
|
||||
The agent must already be registered in the system.
|
||||
|
||||
Requires `admin:orgs` scope.
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/AddMemberRequest'
|
||||
example:
|
||||
agentId: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
|
||||
role: "member"
|
||||
responses:
|
||||
'201':
|
||||
description: Agent added to organization successfully.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/OrgMember'
|
||||
example:
|
||||
memberId: "mem-abcd-1234-5678-ef01"
|
||||
organizationId: "org-1234-5678-abcd-ef01"
|
||||
agentId: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
|
||||
role: "member"
|
||||
joinedAt: "2026-04-07T09:00:00.000Z"
|
||||
'400':
|
||||
description: Validation error in request body.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
example:
|
||||
code: "VALIDATION_ERROR"
|
||||
message: "Request validation failed."
|
||||
details:
|
||||
field: "role"
|
||||
reason: "role must be one of: member, admin."
|
||||
'401':
|
||||
$ref: '#/components/responses/Unauthorized'
|
||||
'403':
|
||||
$ref: '#/components/responses/Forbidden'
|
||||
'404':
|
||||
description: Organization or agent not found.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
examples:
|
||||
orgNotFound:
|
||||
summary: Organization not found
|
||||
value:
|
||||
code: "ORG_NOT_FOUND"
|
||||
message: "Organization with the specified ID was not found."
|
||||
agentNotFound:
|
||||
summary: Agent not found
|
||||
value:
|
||||
code: "AGENT_NOT_FOUND"
|
||||
message: "Agent with the specified ID was not found."
|
||||
'409':
|
||||
description: Agent is already a member of this organization.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
example:
|
||||
code: "ALREADY_MEMBER"
|
||||
message: "The agent is already a member of this organization."
|
||||
'429':
|
||||
$ref: '#/components/responses/TooManyRequests'
|
||||
'500':
|
||||
$ref: '#/components/responses/InternalServerError'
|
||||
257
docs/openapi/scaffold.yaml
Normal file
257
docs/openapi/scaffold.yaml
Normal file
@@ -0,0 +1,257 @@
|
||||
openapi: "3.0.3"
|
||||
|
||||
info:
|
||||
title: SentryAgent.ai — SDK Scaffold Generator
|
||||
version: 1.0.0
|
||||
description: |
|
||||
SDK scaffold generator endpoint for the SentryAgent.ai AgentIdP platform.
|
||||
|
||||
The scaffold endpoint generates a ready-to-run agent project ZIP archive
|
||||
pre-configured with the agent's credentials, API URL, and chosen SDK.
|
||||
|
||||
The generated scaffold includes:
|
||||
- Language-specific project structure (TypeScript / Python / Go / Java / Rust)
|
||||
- Pre-filled `.env.example` with `CLIENT_ID` and `API_URL`
|
||||
- Agent authentication boilerplate using the SentryAgent.ai SDK
|
||||
- README with quickstart instructions
|
||||
- Docker / CI configuration (where applicable)
|
||||
|
||||
**Authentication:** Requires a valid Bearer JWT.
|
||||
**Rate limit:** 10 requests per minute per tenant (separate from the global limit).
|
||||
The scaffold endpoint responds with `Retry-After` on rate limit.
|
||||
|
||||
**Supported languages:** `typescript`, `python`, `go`, `java`, `rust`
|
||||
|
||||
servers:
|
||||
- url: http://localhost:3000/api/v1
|
||||
description: Local development server
|
||||
- url: https://api.sentryagent.ai/v1
|
||||
description: Production server
|
||||
|
||||
tags:
|
||||
- name: SDK Scaffold
|
||||
description: Generate a ready-to-run agent SDK project scaffold
|
||||
|
||||
components:
|
||||
securitySchemes:
|
||||
BearerAuth:
|
||||
type: http
|
||||
scheme: bearer
|
||||
bearerFormat: JWT
|
||||
description: |
|
||||
JWT access token obtained via `POST /token`.
|
||||
Include as `Authorization: Bearer <token>`.
|
||||
|
||||
schemas:
|
||||
ScaffoldLanguage:
|
||||
type: string
|
||||
enum:
|
||||
- typescript
|
||||
- python
|
||||
- go
|
||||
- java
|
||||
- rust
|
||||
description: Target programming language for the scaffold project.
|
||||
example: typescript
|
||||
|
||||
ErrorResponse:
|
||||
type: object
|
||||
description: Standard error response envelope.
|
||||
required:
|
||||
- code
|
||||
- message
|
||||
properties:
|
||||
code:
|
||||
type: string
|
||||
example: "AGENT_NOT_FOUND"
|
||||
message:
|
||||
type: string
|
||||
example: "Agent with the specified ID was not found."
|
||||
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."
|
||||
|
||||
Forbidden:
|
||||
description: Valid token but insufficient permissions.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
example:
|
||||
code: "FORBIDDEN"
|
||||
message: "You do not have permission to access this agent's scaffold."
|
||||
|
||||
NotFound:
|
||||
description: Agent not found.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
example:
|
||||
code: "AGENT_NOT_FOUND"
|
||||
message: "Agent with the specified ID was not found."
|
||||
|
||||
TooManyRequests:
|
||||
description: |
|
||||
Scaffold-specific rate limit exceeded (10 requests per minute per tenant).
|
||||
Retry after the duration specified in the `Retry-After` header.
|
||||
headers:
|
||||
Retry-After:
|
||||
schema:
|
||||
type: integer
|
||||
description: Number of seconds to wait before retrying.
|
||||
example: 60
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
example:
|
||||
code: "RATE_LIMIT_EXCEEDED"
|
||||
message: "Scaffold rate limit exceeded. Please retry after 60 seconds."
|
||||
|
||||
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."
|
||||
|
||||
security:
|
||||
- BearerAuth: []
|
||||
|
||||
paths:
|
||||
/sdk/scaffold/{agentId}:
|
||||
get:
|
||||
operationId: getAgentScaffold
|
||||
tags:
|
||||
- SDK Scaffold
|
||||
summary: Generate and download an agent SDK scaffold ZIP
|
||||
description: |
|
||||
Generates a ready-to-run agent project scaffold for the specified agent
|
||||
and streams it as a ZIP file download.
|
||||
|
||||
The scaffold is customized with:
|
||||
- The agent's `CLIENT_ID` pre-filled in `.env.example`
|
||||
- The platform API URL (`API_URL`) configured for the environment
|
||||
- The agent's name, type, and capabilities reflected in project metadata
|
||||
- Language-specific SDK integration boilerplate
|
||||
|
||||
**Rate limit:** 10 requests per minute per tenant.
|
||||
Exceeding this limit returns `429 Too Many Requests` with a `Retry-After` header.
|
||||
|
||||
**Language selection:** Pass the desired `language` query parameter.
|
||||
Defaults to `typescript` when omitted.
|
||||
|
||||
**Authorization:** The authenticated agent (from Bearer token) must belong to
|
||||
the same organization as the target agent (`agentId`). Cross-tenant scaffold
|
||||
generation is not permitted.
|
||||
parameters:
|
||||
- name: agentId
|
||||
in: path
|
||||
required: true
|
||||
description: UUID of the agent to generate a scaffold for.
|
||||
schema:
|
||||
type: string
|
||||
format: uuid
|
||||
example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
|
||||
- name: language
|
||||
in: query
|
||||
required: false
|
||||
description: |
|
||||
Target programming language for the scaffold.
|
||||
Defaults to `typescript` when omitted.
|
||||
schema:
|
||||
$ref: '#/components/schemas/ScaffoldLanguage'
|
||||
example: typescript
|
||||
responses:
|
||||
'200':
|
||||
description: |
|
||||
Scaffold ZIP archive generated and streamed successfully.
|
||||
|
||||
The response body is a ZIP archive containing the generated project files.
|
||||
Save it locally and unzip to get started:
|
||||
```
|
||||
curl -O -J -H "Authorization: Bearer <token>" \
|
||||
"https://api.sentryagent.ai/v1/sdk/scaffold/a1b2c3d4-e5f6-7890-abcd-ef1234567890?language=typescript"
|
||||
unzip screener-001-scaffold.zip
|
||||
cd screener-001-scaffold && npm install
|
||||
```
|
||||
headers:
|
||||
Content-Disposition:
|
||||
schema:
|
||||
type: string
|
||||
description: |
|
||||
Filename for the ZIP download.
|
||||
Format: `attachment; filename="<agent-name>-scaffold.zip"`
|
||||
example: 'attachment; filename="screener-001-scaffold.zip"'
|
||||
Content-Type:
|
||||
schema:
|
||||
type: string
|
||||
example: "application/zip"
|
||||
X-RateLimit-Limit:
|
||||
schema:
|
||||
type: integer
|
||||
description: Scaffold rate limit (requests per minute per tenant).
|
||||
example: 10
|
||||
X-RateLimit-Remaining:
|
||||
schema:
|
||||
type: integer
|
||||
description: Remaining scaffold requests in the current window.
|
||||
example: 9
|
||||
content:
|
||||
application/zip:
|
||||
schema:
|
||||
type: string
|
||||
format: binary
|
||||
description: ZIP archive of the generated scaffold project.
|
||||
'400':
|
||||
description: Invalid `language` query parameter.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
example:
|
||||
code: "VALIDATION_ERROR"
|
||||
message: "Invalid language. Supported languages are: typescript, python, go, java, rust."
|
||||
details:
|
||||
field: "language"
|
||||
provided: "ruby"
|
||||
supported:
|
||||
- typescript
|
||||
- python
|
||||
- go
|
||||
- java
|
||||
- rust
|
||||
'401':
|
||||
$ref: '#/components/responses/Unauthorized'
|
||||
'403':
|
||||
$ref: '#/components/responses/Forbidden'
|
||||
'404':
|
||||
$ref: '#/components/responses/NotFound'
|
||||
'422':
|
||||
description: Agent is decommissioned — cannot generate scaffold for inactive agents.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
example:
|
||||
code: "AGENT_DECOMMISSIONED"
|
||||
message: "Cannot generate scaffold for a decommissioned agent."
|
||||
'429':
|
||||
$ref: '#/components/responses/TooManyRequests'
|
||||
'500':
|
||||
$ref: '#/components/responses/InternalServerError'
|
||||
341
docs/openapi/tiers.yaml
Normal file
341
docs/openapi/tiers.yaml
Normal file
@@ -0,0 +1,341 @@
|
||||
openapi: "3.0.3"
|
||||
|
||||
info:
|
||||
title: SentryAgent.ai — Tier Management
|
||||
version: 1.0.0
|
||||
description: |
|
||||
Tier status and upgrade endpoints for the SentryAgent.ai AgentIdP platform.
|
||||
|
||||
The tier system defines per-organization limits on agents, tokens, and API calls.
|
||||
|
||||
**All endpoints require a valid Bearer JWT.**
|
||||
|
||||
**Available tiers:**
|
||||
| Tier | Max Agents | Max Tokens/Month | Rate Limit |
|
||||
|------|-----------|-----------------|------------|
|
||||
| `free` | 100 | 10,000 | 100 req/min |
|
||||
| `pro` | 1,000 | 100,000 | 1,000 req/min |
|
||||
| `enterprise` | unlimited | unlimited | custom |
|
||||
|
||||
servers:
|
||||
- url: http://localhost:3000/api/v1
|
||||
description: Local development server
|
||||
- url: https://api.sentryagent.ai/v1
|
||||
description: Production server
|
||||
|
||||
tags:
|
||||
- name: Tiers
|
||||
description: Tier status and upgrade management
|
||||
|
||||
components:
|
||||
securitySchemes:
|
||||
BearerAuth:
|
||||
type: http
|
||||
scheme: bearer
|
||||
bearerFormat: JWT
|
||||
description: |
|
||||
JWT access token obtained via `POST /token`.
|
||||
Include as `Authorization: Bearer <token>`.
|
||||
|
||||
schemas:
|
||||
PlanTier:
|
||||
type: string
|
||||
enum:
|
||||
- free
|
||||
- pro
|
||||
- enterprise
|
||||
description: Current subscription plan tier.
|
||||
example: free
|
||||
|
||||
TierLimits:
|
||||
type: object
|
||||
description: Hard limits defined by the current tier.
|
||||
required:
|
||||
- maxAgents
|
||||
- maxTokensPerMonth
|
||||
- rateLimitPerMinute
|
||||
properties:
|
||||
maxAgents:
|
||||
type: integer
|
||||
description: Maximum number of agents allowed for this organization.
|
||||
example: 100
|
||||
maxTokensPerMonth:
|
||||
type: integer
|
||||
description: Maximum OAuth 2.0 token requests per calendar month.
|
||||
example: 10000
|
||||
rateLimitPerMinute:
|
||||
type: integer
|
||||
description: Maximum API requests per minute.
|
||||
example: 100
|
||||
|
||||
TierUsage:
|
||||
type: object
|
||||
description: Live usage counters for the current billing period.
|
||||
required:
|
||||
- agentsRegistered
|
||||
- tokensThisMonth
|
||||
- requestsThisMinute
|
||||
properties:
|
||||
agentsRegistered:
|
||||
type: integer
|
||||
description: Current number of active (non-decommissioned) agents.
|
||||
minimum: 0
|
||||
example: 47
|
||||
tokensThisMonth:
|
||||
type: integer
|
||||
description: Total OAuth 2.0 tokens issued in the current calendar month.
|
||||
minimum: 0
|
||||
example: 3214
|
||||
requestsThisMinute:
|
||||
type: integer
|
||||
description: API requests in the current rate-limit window.
|
||||
minimum: 0
|
||||
example: 12
|
||||
|
||||
TierStatus:
|
||||
type: object
|
||||
description: Full tier status response — current tier, plan limits, and live usage.
|
||||
required:
|
||||
- organizationId
|
||||
- tier
|
||||
- limits
|
||||
- usage
|
||||
properties:
|
||||
organizationId:
|
||||
type: string
|
||||
format: uuid
|
||||
description: Organization the tier status applies to.
|
||||
example: "org-1234-5678-abcd-ef01"
|
||||
tier:
|
||||
$ref: '#/components/schemas/PlanTier'
|
||||
limits:
|
||||
$ref: '#/components/schemas/TierLimits'
|
||||
usage:
|
||||
$ref: '#/components/schemas/TierUsage'
|
||||
billingPeriodStart:
|
||||
type: string
|
||||
format: date
|
||||
description: First day of the current billing period (UTC).
|
||||
example: "2026-04-01"
|
||||
billingPeriodEnd:
|
||||
type: string
|
||||
format: date
|
||||
description: Last day of the current billing period (UTC).
|
||||
example: "2026-04-30"
|
||||
|
||||
TierUpgradeRequest:
|
||||
type: object
|
||||
description: Request body for initiating a tier upgrade.
|
||||
required:
|
||||
- targetTier
|
||||
properties:
|
||||
targetTier:
|
||||
type: string
|
||||
enum:
|
||||
- pro
|
||||
- enterprise
|
||||
description: |
|
||||
The target plan tier to upgrade to.
|
||||
Downgrading is not permitted via this endpoint.
|
||||
example: "pro"
|
||||
successUrl:
|
||||
type: string
|
||||
format: uri
|
||||
description: |
|
||||
URL to redirect to after successful payment.
|
||||
Defaults to the platform dashboard when omitted.
|
||||
example: "https://my-app.example.com/dashboard?upgrade=success"
|
||||
cancelUrl:
|
||||
type: string
|
||||
format: uri
|
||||
description: |
|
||||
URL to redirect to if the user cancels checkout.
|
||||
Defaults to the platform dashboard when omitted.
|
||||
example: "https://my-app.example.com/dashboard?upgrade=cancel"
|
||||
|
||||
TierUpgradeResponse:
|
||||
type: object
|
||||
description: Stripe Checkout URL to initiate the tier upgrade payment flow.
|
||||
required:
|
||||
- checkoutUrl
|
||||
- targetTier
|
||||
properties:
|
||||
checkoutUrl:
|
||||
type: string
|
||||
format: uri
|
||||
description: |
|
||||
Stripe-hosted Checkout page URL.
|
||||
Redirect the authenticated user to this URL to complete payment.
|
||||
example: "https://checkout.stripe.com/pay/cs_test_abcdef1234567890"
|
||||
targetTier:
|
||||
$ref: '#/components/schemas/PlanTier'
|
||||
|
||||
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."
|
||||
|
||||
Forbidden:
|
||||
description: Valid token but insufficient permissions.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
example:
|
||||
code: "FORBIDDEN"
|
||||
message: "You do not have permission to perform this action."
|
||||
|
||||
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."
|
||||
|
||||
security:
|
||||
- BearerAuth: []
|
||||
|
||||
paths:
|
||||
/tiers/status:
|
||||
get:
|
||||
operationId: getTierStatus
|
||||
tags:
|
||||
- Tiers
|
||||
summary: Get current tier status
|
||||
description: |
|
||||
Returns the current tier, plan limits, and live usage counters for the
|
||||
authenticated organization.
|
||||
|
||||
The organization ID is derived from the `organization_id` claim in the
|
||||
Bearer JWT — no explicit organization ID is required in the request.
|
||||
|
||||
Use this endpoint to:
|
||||
- Display the current plan in your dashboard
|
||||
- Check remaining quota before performing bulk operations
|
||||
- Determine whether an upgrade is needed
|
||||
responses:
|
||||
'200':
|
||||
description: Tier status returned successfully.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/TierStatus'
|
||||
example:
|
||||
organizationId: "org-1234-5678-abcd-ef01"
|
||||
tier: "free"
|
||||
limits:
|
||||
maxAgents: 100
|
||||
maxTokensPerMonth: 10000
|
||||
rateLimitPerMinute: 100
|
||||
usage:
|
||||
agentsRegistered: 47
|
||||
tokensThisMonth: 3214
|
||||
requestsThisMinute: 12
|
||||
billingPeriodStart: "2026-04-01"
|
||||
billingPeriodEnd: "2026-04-30"
|
||||
'401':
|
||||
$ref: '#/components/responses/Unauthorized'
|
||||
'403':
|
||||
$ref: '#/components/responses/Forbidden'
|
||||
'500':
|
||||
$ref: '#/components/responses/InternalServerError'
|
||||
|
||||
/tiers/upgrade:
|
||||
post:
|
||||
operationId: initiateTierUpgrade
|
||||
tags:
|
||||
- Tiers
|
||||
summary: Initiate a tier upgrade via Stripe
|
||||
description: |
|
||||
Initiates a Stripe Checkout Session for upgrading the organization's plan tier.
|
||||
|
||||
The returned `checkoutUrl` is a Stripe-hosted payment page.
|
||||
Redirect the authenticated user to this URL to complete the upgrade payment.
|
||||
|
||||
After successful payment, Stripe notifies the platform via the
|
||||
`POST /billing/webhook` endpoint, which activates the new tier automatically.
|
||||
|
||||
**Constraints:**
|
||||
- Only upgrades are supported (free → pro, free → enterprise, pro → enterprise).
|
||||
- Attempting to "upgrade" to the current or lower tier returns `400`.
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/TierUpgradeRequest'
|
||||
example:
|
||||
targetTier: "pro"
|
||||
successUrl: "https://my-app.example.com/dashboard?upgrade=success"
|
||||
cancelUrl: "https://my-app.example.com/dashboard?upgrade=cancel"
|
||||
responses:
|
||||
'201':
|
||||
description: Stripe Checkout Session created successfully. Redirect user to checkoutUrl.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/TierUpgradeResponse'
|
||||
example:
|
||||
checkoutUrl: "https://checkout.stripe.com/pay/cs_test_abcdef1234567890"
|
||||
targetTier: "pro"
|
||||
'400':
|
||||
description: Invalid upgrade request — already on target tier or attempting a downgrade.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
examples:
|
||||
alreadyOnTier:
|
||||
summary: Already on target tier
|
||||
value:
|
||||
code: "ALREADY_ON_TIER"
|
||||
message: "Your organization is already on the 'pro' tier."
|
||||
invalidDowngrade:
|
||||
summary: Downgrade not permitted
|
||||
value:
|
||||
code: "DOWNGRADE_NOT_PERMITTED"
|
||||
message: "Downgrading tiers is not supported via this endpoint."
|
||||
missingOrgId:
|
||||
summary: Missing organization_id in token
|
||||
value:
|
||||
code: "VALIDATION_ERROR"
|
||||
message: "organization_id is required in token."
|
||||
'401':
|
||||
$ref: '#/components/responses/Unauthorized'
|
||||
'403':
|
||||
$ref: '#/components/responses/Forbidden'
|
||||
'500':
|
||||
description: Unexpected error or Stripe API failure.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
example:
|
||||
code: "STRIPE_ERROR"
|
||||
message: "Failed to create Stripe Checkout Session. Please try again."
|
||||
676
docs/openapi/webhooks.yaml
Normal file
676
docs/openapi/webhooks.yaml
Normal file
@@ -0,0 +1,676 @@
|
||||
openapi: "3.0.3"
|
||||
|
||||
info:
|
||||
title: SentryAgent.ai — Webhooks & Event Subscriptions
|
||||
version: 1.0.0
|
||||
description: |
|
||||
Webhook subscription management and delivery history endpoints for the
|
||||
SentryAgent.ai AgentIdP platform.
|
||||
|
||||
Webhooks deliver real-time event notifications to registered HTTP endpoints
|
||||
when significant platform events occur (agent lifecycle changes, credential
|
||||
operations, token events).
|
||||
|
||||
**All endpoints require a valid Bearer JWT** with appropriate scope:
|
||||
- `webhooks:read` — required for GET operations
|
||||
- `webhooks:write` — required for POST, PATCH, DELETE operations
|
||||
|
||||
**Delivery mechanism:**
|
||||
- Events are delivered via `POST` to the registered `url`
|
||||
- Each delivery carries a signed JSON envelope (`X-SentryAgent-Signature` header)
|
||||
- Failed deliveries are retried with exponential backoff (up to 10 attempts)
|
||||
- After 10 failures the subscription is marked `dead_letter`
|
||||
|
||||
**Supported event types:**
|
||||
`agent.created`, `agent.updated`, `agent.suspended`, `agent.reactivated`,
|
||||
`agent.decommissioned`, `credential.generated`, `credential.rotated`,
|
||||
`credential.revoked`, `token.issued`, `token.revoked`
|
||||
|
||||
servers:
|
||||
- url: http://localhost:3000/api/v1
|
||||
description: Local development server
|
||||
- url: https://api.sentryagent.ai/v1
|
||||
description: Production server
|
||||
|
||||
tags:
|
||||
- name: Webhook Subscriptions
|
||||
description: Create and manage webhook endpoint subscriptions
|
||||
- name: Webhook Deliveries
|
||||
description: Query delivery history and attempt records
|
||||
|
||||
components:
|
||||
securitySchemes:
|
||||
BearerAuth:
|
||||
type: http
|
||||
scheme: bearer
|
||||
bearerFormat: JWT
|
||||
description: |
|
||||
JWT access token obtained via `POST /token`.
|
||||
Include as `Authorization: Bearer <token>`.
|
||||
|
||||
schemas:
|
||||
WebhookEventType:
|
||||
type: string
|
||||
enum:
|
||||
- agent.created
|
||||
- agent.updated
|
||||
- agent.suspended
|
||||
- agent.reactivated
|
||||
- agent.decommissioned
|
||||
- credential.generated
|
||||
- credential.rotated
|
||||
- credential.revoked
|
||||
- token.issued
|
||||
- token.revoked
|
||||
description: Platform event type that can be subscribed to.
|
||||
example: agent.created
|
||||
|
||||
WebhookDeliveryStatus:
|
||||
type: string
|
||||
enum:
|
||||
- pending
|
||||
- delivered
|
||||
- failed
|
||||
- dead_letter
|
||||
description: |
|
||||
Current status of a delivery attempt.
|
||||
- `pending` — queued for delivery or awaiting retry
|
||||
- `delivered` — successfully delivered (HTTP 2xx from target)
|
||||
- `failed` — delivery failed; retry scheduled
|
||||
- `dead_letter` — all retries exhausted; no further attempts
|
||||
example: delivered
|
||||
|
||||
WebhookSubscription:
|
||||
type: object
|
||||
description: A registered webhook subscription (signing secret never included in responses).
|
||||
required:
|
||||
- id
|
||||
- organization_id
|
||||
- name
|
||||
- url
|
||||
- events
|
||||
- active
|
||||
- failure_count
|
||||
- created_at
|
||||
- updated_at
|
||||
properties:
|
||||
id:
|
||||
type: string
|
||||
format: uuid
|
||||
description: Immutable system-assigned UUID for this subscription.
|
||||
readOnly: true
|
||||
example: "wh-abcd-1234-5678-ef01"
|
||||
organization_id:
|
||||
type: string
|
||||
format: uuid
|
||||
description: Organization that owns this subscription.
|
||||
readOnly: true
|
||||
example: "org-1234-5678-abcd-ef01"
|
||||
name:
|
||||
type: string
|
||||
description: Human-readable label for this subscription.
|
||||
example: "Agent lifecycle events"
|
||||
url:
|
||||
type: string
|
||||
format: uri
|
||||
description: HTTPS endpoint that receives webhook payloads.
|
||||
example: "https://my-app.example.com/webhooks/sentryagent"
|
||||
events:
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/components/schemas/WebhookEventType'
|
||||
description: List of event types this subscription receives.
|
||||
minItems: 1
|
||||
example:
|
||||
- agent.created
|
||||
- agent.decommissioned
|
||||
active:
|
||||
type: boolean
|
||||
description: Whether the subscription is currently active. Set to false to pause delivery.
|
||||
example: true
|
||||
failure_count:
|
||||
type: integer
|
||||
description: Number of consecutive delivery failures since last success.
|
||||
minimum: 0
|
||||
readOnly: true
|
||||
example: 0
|
||||
created_at:
|
||||
type: string
|
||||
format: date-time
|
||||
readOnly: true
|
||||
example: "2026-03-01T08:00:00.000Z"
|
||||
updated_at:
|
||||
type: string
|
||||
format: date-time
|
||||
readOnly: true
|
||||
example: "2026-03-28T11:30:00.000Z"
|
||||
|
||||
CreateWebhookRequest:
|
||||
type: object
|
||||
description: Request body for creating a new webhook subscription.
|
||||
required:
|
||||
- name
|
||||
- url
|
||||
- events
|
||||
properties:
|
||||
name:
|
||||
type: string
|
||||
description: Human-readable label for this subscription.
|
||||
minLength: 1
|
||||
maxLength: 256
|
||||
example: "Agent lifecycle events"
|
||||
url:
|
||||
type: string
|
||||
format: uri
|
||||
description: HTTPS endpoint URL. Must be HTTPS in production.
|
||||
example: "https://my-app.example.com/webhooks/sentryagent"
|
||||
events:
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/components/schemas/WebhookEventType'
|
||||
minItems: 1
|
||||
description: Event types to subscribe to.
|
||||
example:
|
||||
- agent.created
|
||||
- agent.decommissioned
|
||||
|
||||
UpdateWebhookRequest:
|
||||
type: object
|
||||
description: |
|
||||
Request body for partially updating a webhook subscription.
|
||||
All fields are optional; only provided fields are updated.
|
||||
minProperties: 1
|
||||
properties:
|
||||
name:
|
||||
type: string
|
||||
minLength: 1
|
||||
maxLength: 256
|
||||
example: "Agent events (updated)"
|
||||
url:
|
||||
type: string
|
||||
format: uri
|
||||
example: "https://my-app.example.com/webhooks/v2"
|
||||
events:
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/components/schemas/WebhookEventType'
|
||||
minItems: 1
|
||||
example:
|
||||
- agent.created
|
||||
- agent.updated
|
||||
- token.issued
|
||||
active:
|
||||
type: boolean
|
||||
description: Set to false to pause delivery without deleting the subscription.
|
||||
example: true
|
||||
|
||||
WebhookDelivery:
|
||||
type: object
|
||||
description: A single webhook delivery attempt record.
|
||||
required:
|
||||
- id
|
||||
- subscription_id
|
||||
- event_type
|
||||
- payload
|
||||
- status
|
||||
- attempt_count
|
||||
- created_at
|
||||
- updated_at
|
||||
properties:
|
||||
id:
|
||||
type: string
|
||||
format: uuid
|
||||
readOnly: true
|
||||
example: "del-abcd-1234-5678-ef01"
|
||||
subscription_id:
|
||||
type: string
|
||||
format: uuid
|
||||
example: "wh-abcd-1234-5678-ef01"
|
||||
event_type:
|
||||
$ref: '#/components/schemas/WebhookEventType'
|
||||
payload:
|
||||
type: object
|
||||
description: The JSON payload that was sent (or attempted) to the target URL.
|
||||
additionalProperties: true
|
||||
example:
|
||||
id: "evt-1234-5678"
|
||||
event: "agent.created"
|
||||
timestamp: "2026-04-07T09:00:00.000Z"
|
||||
organization_id: "org-1234-5678-abcd-ef01"
|
||||
data:
|
||||
agentId: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
|
||||
status:
|
||||
$ref: '#/components/schemas/WebhookDeliveryStatus'
|
||||
http_status_code:
|
||||
type: integer
|
||||
nullable: true
|
||||
description: HTTP status code returned by the target endpoint (null if connection failed).
|
||||
example: 200
|
||||
attempt_count:
|
||||
type: integer
|
||||
description: Number of delivery attempts made so far.
|
||||
minimum: 1
|
||||
example: 1
|
||||
next_retry_at:
|
||||
type: string
|
||||
format: date-time
|
||||
nullable: true
|
||||
description: Scheduled time for the next retry attempt. Null if delivered or dead-lettered.
|
||||
example: null
|
||||
delivered_at:
|
||||
type: string
|
||||
format: date-time
|
||||
nullable: true
|
||||
description: Timestamp when the delivery was successfully confirmed.
|
||||
example: "2026-04-07T09:00:05.000Z"
|
||||
created_at:
|
||||
type: string
|
||||
format: date-time
|
||||
readOnly: true
|
||||
example: "2026-04-07T09:00:00.000Z"
|
||||
updated_at:
|
||||
type: string
|
||||
format: date-time
|
||||
readOnly: true
|
||||
example: "2026-04-07T09:00:05.000Z"
|
||||
|
||||
PaginatedDeliveriesResponse:
|
||||
type: object
|
||||
description: Paginated delivery history response.
|
||||
required:
|
||||
- deliveries
|
||||
- total
|
||||
- limit
|
||||
- offset
|
||||
properties:
|
||||
deliveries:
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/components/schemas/WebhookDelivery'
|
||||
total:
|
||||
type: integer
|
||||
example: 87
|
||||
limit:
|
||||
type: integer
|
||||
example: 20
|
||||
offset:
|
||||
type: integer
|
||||
example: 0
|
||||
|
||||
ErrorResponse:
|
||||
type: object
|
||||
description: Standard error response envelope.
|
||||
required:
|
||||
- code
|
||||
- message
|
||||
properties:
|
||||
code:
|
||||
type: string
|
||||
example: "WEBHOOK_NOT_FOUND"
|
||||
message:
|
||||
type: string
|
||||
example: "Webhook subscription with the specified ID was not found."
|
||||
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."
|
||||
|
||||
Forbidden:
|
||||
description: Valid token but insufficient scope.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
example:
|
||||
code: "FORBIDDEN"
|
||||
message: "You do not have permission to perform this action."
|
||||
|
||||
NotFound:
|
||||
description: Webhook subscription not found.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
example:
|
||||
code: "WEBHOOK_NOT_FOUND"
|
||||
message: "Webhook subscription 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."
|
||||
|
||||
security:
|
||||
- BearerAuth: []
|
||||
|
||||
paths:
|
||||
/webhooks:
|
||||
post:
|
||||
operationId: createWebhookSubscription
|
||||
tags:
|
||||
- Webhook Subscriptions
|
||||
summary: Create a webhook subscription
|
||||
description: |
|
||||
Creates a new webhook subscription for the authenticated organization.
|
||||
A signing secret is generated automatically and returned once in the response
|
||||
under a `signingSecret` field. **Store this secret securely — it cannot be retrieved again.**
|
||||
|
||||
Requires `webhooks:write` scope.
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/CreateWebhookRequest'
|
||||
example:
|
||||
name: "Agent lifecycle events"
|
||||
url: "https://my-app.example.com/webhooks/sentryagent"
|
||||
events:
|
||||
- agent.created
|
||||
- agent.decommissioned
|
||||
responses:
|
||||
'201':
|
||||
description: Webhook subscription created successfully.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
allOf:
|
||||
- $ref: '#/components/schemas/WebhookSubscription'
|
||||
- type: object
|
||||
properties:
|
||||
signingSecret:
|
||||
type: string
|
||||
description: |
|
||||
HMAC signing secret for verifying webhook payloads.
|
||||
Returned only once at creation time.
|
||||
example: "whsec_abcdef1234567890abcdef1234567890"
|
||||
example:
|
||||
id: "wh-abcd-1234-5678-ef01"
|
||||
organization_id: "org-1234-5678-abcd-ef01"
|
||||
name: "Agent lifecycle events"
|
||||
url: "https://my-app.example.com/webhooks/sentryagent"
|
||||
events:
|
||||
- agent.created
|
||||
- agent.decommissioned
|
||||
active: true
|
||||
failure_count: 0
|
||||
created_at: "2026-04-07T09:00:00.000Z"
|
||||
updated_at: "2026-04-07T09:00:00.000Z"
|
||||
signingSecret: "whsec_abcdef1234567890abcdef1234567890"
|
||||
'400':
|
||||
description: Validation error in request body.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
example:
|
||||
code: "VALIDATION_ERROR"
|
||||
message: "Request validation failed."
|
||||
details:
|
||||
field: "url"
|
||||
reason: "Must be a valid HTTPS URL."
|
||||
'401':
|
||||
$ref: '#/components/responses/Unauthorized'
|
||||
'403':
|
||||
$ref: '#/components/responses/Forbidden'
|
||||
'500':
|
||||
$ref: '#/components/responses/InternalServerError'
|
||||
|
||||
get:
|
||||
operationId: listWebhookSubscriptions
|
||||
tags:
|
||||
- Webhook Subscriptions
|
||||
summary: List webhook subscriptions
|
||||
description: |
|
||||
Returns all webhook subscriptions for the authenticated organization.
|
||||
Requires `webhooks:read` scope.
|
||||
responses:
|
||||
'200':
|
||||
description: List of webhook subscriptions returned successfully.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/components/schemas/WebhookSubscription'
|
||||
example:
|
||||
- id: "wh-abcd-1234-5678-ef01"
|
||||
organization_id: "org-1234-5678-abcd-ef01"
|
||||
name: "Agent lifecycle events"
|
||||
url: "https://my-app.example.com/webhooks/sentryagent"
|
||||
events:
|
||||
- agent.created
|
||||
- agent.decommissioned
|
||||
active: true
|
||||
failure_count: 0
|
||||
created_at: "2026-03-01T08:00:00.000Z"
|
||||
updated_at: "2026-03-01T08:00:00.000Z"
|
||||
'401':
|
||||
$ref: '#/components/responses/Unauthorized'
|
||||
'403':
|
||||
$ref: '#/components/responses/Forbidden'
|
||||
'500':
|
||||
$ref: '#/components/responses/InternalServerError'
|
||||
|
||||
/webhooks/{id}:
|
||||
parameters:
|
||||
- name: id
|
||||
in: path
|
||||
required: true
|
||||
description: UUID of the webhook subscription.
|
||||
schema:
|
||||
type: string
|
||||
format: uuid
|
||||
example: "wh-abcd-1234-5678-ef01"
|
||||
|
||||
get:
|
||||
operationId: getWebhookSubscription
|
||||
tags:
|
||||
- Webhook Subscriptions
|
||||
summary: Get a webhook subscription by ID
|
||||
description: |
|
||||
Returns a single webhook subscription record.
|
||||
Requires `webhooks:read` scope.
|
||||
responses:
|
||||
'200':
|
||||
description: Webhook subscription returned successfully.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/WebhookSubscription'
|
||||
example:
|
||||
id: "wh-abcd-1234-5678-ef01"
|
||||
organization_id: "org-1234-5678-abcd-ef01"
|
||||
name: "Agent lifecycle events"
|
||||
url: "https://my-app.example.com/webhooks/sentryagent"
|
||||
events:
|
||||
- agent.created
|
||||
- agent.decommissioned
|
||||
active: true
|
||||
failure_count: 0
|
||||
created_at: "2026-03-01T08:00:00.000Z"
|
||||
updated_at: "2026-03-28T11:30:00.000Z"
|
||||
'401':
|
||||
$ref: '#/components/responses/Unauthorized'
|
||||
'403':
|
||||
$ref: '#/components/responses/Forbidden'
|
||||
'404':
|
||||
$ref: '#/components/responses/NotFound'
|
||||
'500':
|
||||
$ref: '#/components/responses/InternalServerError'
|
||||
|
||||
patch:
|
||||
operationId: updateWebhookSubscription
|
||||
tags:
|
||||
- Webhook Subscriptions
|
||||
summary: Update a webhook subscription
|
||||
description: |
|
||||
Partially updates a webhook subscription. Only provided fields are updated.
|
||||
Set `active: false` to pause delivery without deleting the subscription.
|
||||
Requires `webhooks:write` scope.
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/UpdateWebhookRequest'
|
||||
example:
|
||||
active: false
|
||||
responses:
|
||||
'200':
|
||||
description: Webhook subscription updated successfully.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/WebhookSubscription'
|
||||
example:
|
||||
id: "wh-abcd-1234-5678-ef01"
|
||||
organization_id: "org-1234-5678-abcd-ef01"
|
||||
name: "Agent lifecycle events"
|
||||
url: "https://my-app.example.com/webhooks/sentryagent"
|
||||
events:
|
||||
- agent.created
|
||||
- agent.decommissioned
|
||||
active: false
|
||||
failure_count: 0
|
||||
created_at: "2026-03-01T08:00:00.000Z"
|
||||
updated_at: "2026-04-07T09:00:00.000Z"
|
||||
'400':
|
||||
description: Validation error in request body.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
example:
|
||||
code: "VALIDATION_ERROR"
|
||||
message: "Request validation failed."
|
||||
'401':
|
||||
$ref: '#/components/responses/Unauthorized'
|
||||
'403':
|
||||
$ref: '#/components/responses/Forbidden'
|
||||
'404':
|
||||
$ref: '#/components/responses/NotFound'
|
||||
'500':
|
||||
$ref: '#/components/responses/InternalServerError'
|
||||
|
||||
delete:
|
||||
operationId: deleteWebhookSubscription
|
||||
tags:
|
||||
- Webhook Subscriptions
|
||||
summary: Delete a webhook subscription
|
||||
description: |
|
||||
Permanently deletes a webhook subscription and stops all future deliveries.
|
||||
Any pending deliveries in the queue are cancelled.
|
||||
Requires `webhooks:write` scope.
|
||||
responses:
|
||||
'204':
|
||||
description: Webhook subscription deleted successfully. No response body.
|
||||
'401':
|
||||
$ref: '#/components/responses/Unauthorized'
|
||||
'403':
|
||||
$ref: '#/components/responses/Forbidden'
|
||||
'404':
|
||||
$ref: '#/components/responses/NotFound'
|
||||
'500':
|
||||
$ref: '#/components/responses/InternalServerError'
|
||||
|
||||
/webhooks/{id}/deliveries:
|
||||
parameters:
|
||||
- name: id
|
||||
in: path
|
||||
required: true
|
||||
description: UUID of the webhook subscription.
|
||||
schema:
|
||||
type: string
|
||||
format: uuid
|
||||
example: "wh-abcd-1234-5678-ef01"
|
||||
|
||||
get:
|
||||
operationId: listWebhookDeliveries
|
||||
tags:
|
||||
- Webhook Deliveries
|
||||
summary: List delivery history for a subscription
|
||||
description: |
|
||||
Returns the delivery history for a webhook subscription,
|
||||
ordered by `created_at` descending (most recent first).
|
||||
|
||||
Use this endpoint to diagnose delivery failures and inspect
|
||||
payload content for historical events.
|
||||
|
||||
Requires `webhooks:read` scope.
|
||||
parameters:
|
||||
- name: limit
|
||||
in: query
|
||||
required: false
|
||||
schema:
|
||||
type: integer
|
||||
minimum: 1
|
||||
maximum: 100
|
||||
default: 20
|
||||
example: 20
|
||||
- name: offset
|
||||
in: query
|
||||
required: false
|
||||
schema:
|
||||
type: integer
|
||||
minimum: 0
|
||||
default: 0
|
||||
example: 0
|
||||
- name: status
|
||||
in: query
|
||||
required: false
|
||||
schema:
|
||||
$ref: '#/components/schemas/WebhookDeliveryStatus'
|
||||
description: Filter deliveries by status.
|
||||
responses:
|
||||
'200':
|
||||
description: Delivery history returned successfully.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/PaginatedDeliveriesResponse'
|
||||
example:
|
||||
deliveries:
|
||||
- id: "del-abcd-1234-5678-ef01"
|
||||
subscription_id: "wh-abcd-1234-5678-ef01"
|
||||
event_type: "agent.created"
|
||||
payload:
|
||||
id: "evt-1234-5678"
|
||||
event: "agent.created"
|
||||
timestamp: "2026-04-07T09:00:00.000Z"
|
||||
organization_id: "org-1234-5678-abcd-ef01"
|
||||
data:
|
||||
agentId: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
|
||||
status: "delivered"
|
||||
http_status_code: 200
|
||||
attempt_count: 1
|
||||
next_retry_at: null
|
||||
delivered_at: "2026-04-07T09:00:05.000Z"
|
||||
created_at: "2026-04-07T09:00:00.000Z"
|
||||
updated_at: "2026-04-07T09:00:05.000Z"
|
||||
total: 87
|
||||
limit: 20
|
||||
offset: 0
|
||||
'401':
|
||||
$ref: '#/components/responses/Unauthorized'
|
||||
'403':
|
||||
$ref: '#/components/responses/Forbidden'
|
||||
'404':
|
||||
$ref: '#/components/responses/NotFound'
|
||||
'500':
|
||||
$ref: '#/components/responses/InternalServerError'
|
||||
@@ -0,0 +1,26 @@
|
||||
## Engineering Docs — Task Tracker
|
||||
|
||||
All tasks complete. Archive committed 2026-04-02.
|
||||
|
||||
### WS1 — Core Knowledge Base (10 documents)
|
||||
|
||||
- [x] 1.1 Create `docs/engineering/README.md` — directory index and reading path
|
||||
- [x] 1.2 Create `docs/engineering/01-overview.md` — company mission, product vision, system purpose, team structure
|
||||
- [x] 1.3 Create `docs/engineering/02-architecture.md` — component diagram, data flows, deployment topology, technology rationale
|
||||
- [x] 1.4 Create `docs/engineering/03-tech-stack.md` — full stack with ADRs (Express, PostgreSQL, Redis, TypeScript, OPA, Vault)
|
||||
- [x] 1.5 Create `docs/engineering/04-codebase-structure.md` — annotated directory map covering all top-level directories and key files
|
||||
- [x] 1.6 Create `docs/engineering/05-services.md` — deep dives for AgentService, OAuth2Service, CredentialService, AuditService, VaultClient, OPA engine, Web Dashboard, Prometheus/Grafana
|
||||
- [x] 1.7 Create `docs/engineering/06-walkthroughs.md` — annotated traces for token issuance, agent registration, and credential rotation (with file:line references)
|
||||
- [x] 1.8 Create `docs/engineering/07-dev-setup.md` — < 30 min onboarding from clone to running local stack
|
||||
- [x] 1.9 Create `docs/engineering/08-workflow.md` — OpenSpec → Architect → Developer → QA → merge cycle and PR standards
|
||||
- [x] 1.10 Create `docs/engineering/09-testing.md` — framework, test types, coverage gates, how to run and write tests
|
||||
|
||||
### WS2 — Operations and Integration
|
||||
|
||||
- [x] 2.1 Create `docs/engineering/10-deployment.md` — Docker build/run, Terraform multi-region, env config, monitoring runbooks
|
||||
- [x] 2.2 Create `docs/engineering/11-sdk-guide.md` — Node.js, Python, Go, Java SDK integration with installation, auth, operations, error handling
|
||||
|
||||
### WS3 — Quality and Review
|
||||
|
||||
- [x] 3.1 CTO review — all documents reviewed against PRD standards (calibration, accuracy, completeness)
|
||||
- [x] 3.2 QA sign-off — cross-link validation, code example verification
|
||||
130
openspec/changes/archive/2026-04-07-vv-architect-setup/design.md
Normal file
130
openspec/changes/archive/2026-04-07-vv-architect-setup/design.md
Normal file
@@ -0,0 +1,130 @@
|
||||
# Design — vv-architect-setup
|
||||
|
||||
## Context
|
||||
|
||||
SentryAgent.ai uses a multi-agent Claude Code architecture:
|
||||
- **CEO-Session** — human-facing, governance and priorities
|
||||
- **VirtualCTO** — technical authority, directs engineering team
|
||||
- **Engineering Team** (Architect, Developer, QA) — spawned as subagents by CTO
|
||||
|
||||
All prior phases passed through the CTO's review and QA sign-off. No independent
|
||||
verification existed outside that chain. The V&V Architect adds a separate audit loop
|
||||
that operates with full read access to the codebase but no write authority over it.
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
- Provide CEO-level assurance that the codebase matches the PRD and OpenSpec
|
||||
- Detect spec-implementation gaps, DRY violations, TypeScript violations, test gaps, and security issues
|
||||
- Create a formal, auditable issue trail (VV_ISSUE_NNN.md files)
|
||||
- Enable the CEO to see a release gate status at any time (LEDGER.md)
|
||||
|
||||
**Non-Goals:**
|
||||
- The validator does NOT fix code — it only reports findings
|
||||
- The validator does NOT block the CTO from working in parallel
|
||||
- The validator does NOT attend to new feature planning or business decisions
|
||||
- The validator does NOT replace the QA Engineer — QA tests functionality; V&V audits completeness and standards compliance
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
CEO (Human)
|
||||
├── CEO-Session (this Claude Code instance)
|
||||
│ └── VirtualCTO (separate terminal — .cto-workspace/)
|
||||
│ ├── Virtual Architect (subagent)
|
||||
│ ├── Virtual Developer (subagent)
|
||||
│ └── Virtual QA Engineer (subagent)
|
||||
└── LeadValidator (separate terminal — .validator-workspace/) ← NEW
|
||||
Reports findings to CEO via #vv-findings
|
||||
BLOCKER alerts also go to #vpe-cto-approvals
|
||||
```
|
||||
|
||||
The LeadValidator is the only agent in the system that:
|
||||
1. Reports directly to the CEO (not via CTO)
|
||||
2. Can issue a BLOCKER that prevents release
|
||||
3. Operates from an isolated workspace with no engineering team context
|
||||
|
||||
## Decisions
|
||||
|
||||
### D1: System Prompt Injection vs. CLAUDE.md Workspace
|
||||
|
||||
**Decision**: Use `--system-prompt-file VALIDATOR.md` to inject the validator's identity.
|
||||
|
||||
**Rationale**: The CTO uses `.cto-workspace/CLAUDE.md` for its identity because Claude Code
|
||||
reads CLAUDE.md as project context. For the validator, using `--system-prompt-file` is
|
||||
more explicit and harder to accidentally override — the validator's identity is injected
|
||||
at the OS level, not discovered by file-scan. This also prevents any future accidental
|
||||
CLAUDE.md conflicts if the workspace is updated.
|
||||
|
||||
**Alternative considered**: Give validator its own CLAUDE.md identity like the CTO — rejected
|
||||
because `--system-prompt-file` makes the validator identity non-negotiable and audit-grade.
|
||||
|
||||
### D2: Shared Ledger — Filesystem vs. Central Hub Only
|
||||
|
||||
**Decision**: Filesystem ledger (`openspec/vv_audit/`) as primary, central hub as notification layer.
|
||||
|
||||
**Rationale**: Issue files (`VV_ISSUE_NNN.md`) need to be persistent, versioned in git, and
|
||||
readable by humans without opening a terminal. The central hub is ephemeral session state.
|
||||
Filesystem issues survive session restarts; hub messages do not.
|
||||
|
||||
**Alternative considered**: Hub-only communication — rejected because hub messages are not
|
||||
committed to git and cannot be audited historically.
|
||||
|
||||
### D3: Issue Severity Model
|
||||
|
||||
**Decision**: Three-tier severity — BLOCKER / MAJOR / MINOR.
|
||||
|
||||
| Severity | Release impact | Who can close |
|
||||
|----------|---------------|---------------|
|
||||
| BLOCKER | Prevents release | CEO acknowledges; CTO resolves |
|
||||
| MAJOR | Must resolve before next phase | CTO resolves; Validator confirms |
|
||||
| MINOR | Best-effort improvement | CTO resolves; no re-audit needed |
|
||||
|
||||
**Rationale**: Binary pass/fail is too blunt for a mature codebase. Three tiers allow the
|
||||
team to ship with known MINOR issues while ensuring BLOCKERs are never silently bypassed.
|
||||
|
||||
### D4: Validator Workspace Isolation
|
||||
|
||||
**Decision**: Validator writes its own minimal CLAUDE.md to `.validator-workspace/` rather
|
||||
than copying the CEO session's CLAUDE.md.
|
||||
|
||||
**Rationale**: The CEO session CLAUDE.md defines multi-agent setup and CEO startup protocol —
|
||||
none of which applies to an auditor. Copying it would contaminate the validator context.
|
||||
The validator's workspace CLAUDE.md only provides absolute path references to project resources.
|
||||
|
||||
### D5: Audit Phases
|
||||
|
||||
**Decision**: 8 audit phases covering all PRD compliance dimensions.
|
||||
|
||||
| Phase | Scope |
|
||||
|-------|-------|
|
||||
| A | OpenSpec task completeness |
|
||||
| B | API surface vs OpenAPI specs |
|
||||
| C | TypeScript strict mode compliance |
|
||||
| D | DRY principle enforcement |
|
||||
| E | SOLID principle spot-checks |
|
||||
| F | Test coverage (>80% threshold) |
|
||||
| G | AGNTCY compliance |
|
||||
| H | Security (OWASP Top 10) |
|
||||
|
||||
All 8 phases must be run per audit session. A validator may document why a phase was
|
||||
skipped but cannot silently omit it.
|
||||
|
||||
## File Map
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `VALIDATOR.md` | System prompt for LeadValidator agent |
|
||||
| `scripts/start-validator.sh` | Launches validator, sets up workspace, sanity-checks VALIDATOR.md |
|
||||
| `.validator-workspace/` | Isolated workspace (gitignored) |
|
||||
| `.validator-workspace/CLAUDE.md` | Validator workspace context (absolute paths only) |
|
||||
| `openspec/vv_audit/LEDGER.md` | Audit ledger index — updated after each session |
|
||||
| `openspec/vv_audit/VV_ISSUE_NNN.md` | Individual issue files written by validator |
|
||||
| `.cto-workspace/CLAUDE.md` | Updated Peer-Review Protocol section |
|
||||
|
||||
## Hub Channels
|
||||
|
||||
| Channel | Purpose |
|
||||
|---------|---------|
|
||||
| `#vv-findings` | Validator → CEO + CTO: audit summaries, issue notifications |
|
||||
| `#vpe-cto-approvals` | Validator → CEO only: BLOCKER escalations |
|
||||
@@ -0,0 +1,54 @@
|
||||
# OpenSpec Proposal — vv-architect-setup
|
||||
|
||||
**Status:** Approved & Archived
|
||||
**Proposed:** 2026-04-07
|
||||
**Approved by:** CEO
|
||||
|
||||
---
|
||||
|
||||
## Problem Statement
|
||||
|
||||
The SentryAgent.ai multi-agent engineering system has no independent quality gate.
|
||||
The Virtual CTO directs the engineering team (Architect, Developer, QA), which means
|
||||
the same chain of command that builds the software also signs off on its correctness.
|
||||
This creates a conflict of interest — the team grades its own homework.
|
||||
|
||||
Additionally, `VALIDATOR.md` existed in the repository but contained the wrong content:
|
||||
a copy of `scripts/start-validator.sh` (the shell script). If the validator had been
|
||||
launched, Claude would have received a bash script as its system prompt, producing
|
||||
a broken agent with no defined purpose or audit methodology.
|
||||
|
||||
## Proposed Solution
|
||||
|
||||
Introduce a **V&V Architect (Lead Validator)** — a 4th independent Claude Code instance
|
||||
that runs outside the CTO's chain of command and reports directly to the CEO.
|
||||
|
||||
**WS1 — Fix VALIDATOR.md**
|
||||
Rewrite `VALIDATOR.md` as the proper system prompt for the Lead Validator agent.
|
||||
Must define: identity, independence principle, startup protocol, 8-phase audit
|
||||
methodology, issue format, severity definitions, and communication protocol.
|
||||
|
||||
**WS2 — Fix start-validator.sh**
|
||||
Update `scripts/start-validator.sh` to:
|
||||
- Build a validator-specific workspace (not inherit CEO session context)
|
||||
- Include a sanity check that aborts if VALIDATOR.md still contains shell script content
|
||||
- Auto-initialise the shared V&V audit ledger on first run
|
||||
|
||||
**WS3 — Shared V&V Issue Ledger**
|
||||
Create `openspec/vv_audit/` as the shared filesystem ledger accessible by both the
|
||||
Validator and the CTO via absolute paths. Create `LEDGER.md` as the audit index.
|
||||
|
||||
**WS4 — Central Hub Channel**
|
||||
Create `#vv-findings` channel on the central hub for real-time validator notifications
|
||||
to CEO and CTO. BLOCKER findings also escalate to `#vpe-cto-approvals`.
|
||||
|
||||
**WS5 — CTO Peer-Review Protocol Update**
|
||||
Update `.cto-workspace/CLAUDE.md` to reference the correct ledger path, hub channel,
|
||||
and dispute/resolution process so the CTO knows how to respond to validator findings.
|
||||
|
||||
## CEO Approval
|
||||
|
||||
Approved 2026-04-07 per CEO directive:
|
||||
"if possible — yes you have my approvals — as our technical and business consultant —
|
||||
please make the changes you need to make sure we have fully independent system to check
|
||||
we have fully implemented our PRD per OpenSpec protocols"
|
||||
@@ -0,0 +1,61 @@
|
||||
# Tasks — vv-architect-setup
|
||||
|
||||
## WS1 — Fix VALIDATOR.md (System Prompt)
|
||||
|
||||
- [x] 1.1 Identify the bug: `VALIDATOR.md` contained an exact copy of `scripts/start-validator.sh` (byte-for-byte identical — 1900 bytes each)
|
||||
- [x] 1.2 Rewrite `VALIDATOR.md` as the proper system prompt for the LeadValidator agent
|
||||
- [x] 1.3 Define validator identity and independence principle (not under CTO authority; reports to CEO)
|
||||
- [x] 1.4 Define 6-step startup protocol (read PRD → register hub → check ledger → check channel → report readiness → begin audit)
|
||||
- [x] 1.5 Define Phase A — OpenSpec task completeness check (verify all archived tasks.md `[x]` items have corresponding code)
|
||||
- [x] 1.6 Define Phase B — API surface audit (every route must have an OpenAPI spec; spec must match implementation)
|
||||
- [x] 1.7 Define Phase C — TypeScript standards audit (no `any`, strict mode, JSDoc, error hierarchy)
|
||||
- [x] 1.8 Define Phase D — DRY principle audit (no duplicated logic, utility files as single sources of truth)
|
||||
- [x] 1.9 Define Phase E — SOLID principles audit (SRP spot-checks on key services, constructor injection)
|
||||
- [x] 1.10 Define Phase F — Test coverage audit (>80% threshold, integration tests for all endpoints)
|
||||
- [x] 1.11 Define Phase G — AGNTCY compliance audit (agent identity model, lifecycle, DID, conformance tests)
|
||||
- [x] 1.12 Define Phase H — Security audit (OWASP Top 10 checks)
|
||||
- [x] 1.13 Define issue format: `VV_ISSUE_NNN.md` with Status, Severity, Category, Finding, Evidence, Required Action, CTO Response, Resolution
|
||||
- [x] 1.14 Define severity model: BLOCKER / MAJOR / MINOR with clear ownership and release impact
|
||||
- [x] 1.15 Define communication protocol: `#vv-findings` for routine findings, `#vpe-cto-approvals` for BLOCKER escalations
|
||||
- [x] 1.16 Define dispute resolution protocol: CTO writes justification → Validator evaluates → CEO as final arbiter
|
||||
- [x] 1.17 Define AUDIT LEDGER INDEX maintenance requirements
|
||||
|
||||
## WS2 — Fix scripts/start-validator.sh
|
||||
|
||||
- [x] 2.1 Remove the line that copies CEO's `CLAUDE.md` into the validator workspace (was contaminating validator with CEO-session context)
|
||||
- [x] 2.2 Add sanity check: abort with clear error if `VALIDATOR.md` first line is `#!/bin/bash` (prevents relaunching with wrong content)
|
||||
- [x] 2.3 Add `SHARED_LEDGER` variable pointing to `openspec/vv_audit/`
|
||||
- [x] 2.4 Add `mkdir -p "$SHARED_LEDGER"` to auto-create ledger directory on first run
|
||||
- [x] 2.5 Add auto-initialisation of `LEDGER.md` if it does not exist (idempotent — skipped if already present)
|
||||
- [x] 2.6 Write validator-specific `CLAUDE.md` to workspace (absolute paths only, no CEO-session context, no role-switching instructions)
|
||||
- [x] 2.7 Update echoed launch checklist to reflect validator's actual responsibilities
|
||||
- [x] 2.8 Ensure `exec claude --system-prompt-file "$VALIDATOR_SYSTEM_PROMPT"` uses the correct variable name
|
||||
|
||||
## WS3 — Shared V&V Issue Ledger
|
||||
|
||||
- [x] 3.1 Create `openspec/vv_audit/` directory in project root (accessible by both validator and CTO via absolute paths)
|
||||
- [x] 3.2 Create `openspec/vv_audit/LEDGER.md` — structured audit index with Summary table, Issue Index, Audit History, and usage instructions
|
||||
- [x] 3.3 Document who updates what: Validator updates Summary and Issue Index; CTO updates issue files; CEO reads for release gate status
|
||||
|
||||
## WS4 — Central Hub Channel
|
||||
|
||||
- [x] 4.1 Create `#vv-findings` channel on central hub with description: "V&V Architect findings — audit issues, BLOCKER notifications, resolution tracking"
|
||||
- [x] 4.2 Verify `#vpe-cto-approvals` (CEO channel) already exists — BLOCKER escalations go here
|
||||
|
||||
## WS5 — CTO Peer-Review Protocol Update
|
||||
|
||||
- [x] 5.1 Update `.cto-workspace/CLAUDE.md` Peer-Review Protocol section
|
||||
- [x] 5.2 Replace relative path `./specs/issues/` with absolute path `openspec/vv_audit/`
|
||||
- [x] 5.3 Add `#vv-findings` channel reference
|
||||
- [x] 5.4 Clarify CTO cannot dismiss validator findings — only resolve or dispute
|
||||
- [x] 5.5 Clarify BLOCKER resolution protocol: CEO automatically notified; CTO must not resolve without CEO awareness
|
||||
- [x] 5.6 Add instruction on how to start the validator (`./scripts/start-validator.sh`)
|
||||
|
||||
## WS6 — OpenSpec Documentation (this change)
|
||||
|
||||
- [x] 6.1 Create `openspec/changes/archive/2026-04-07-vv-architect-setup/` directory
|
||||
- [x] 6.2 Write `proposal.md` — problem statement, proposed solution, CEO approval
|
||||
- [x] 6.3 Write `design.md` — architecture, decisions (D1–D5), file map, hub channels
|
||||
- [x] 6.4 Write `tasks.md` (this file) — complete task breakdown with all items checked
|
||||
- [x] 6.5 Create `specs/` directory (no API specs needed — this is agent governance tooling, not an API change)
|
||||
- [x] 6.6 Commit all changes to git: VALIDATOR.md, scripts/start-validator.sh, openspec/vv_audit/, openspec/changes/archive/2026-04-07-vv-architect-setup/
|
||||
@@ -0,0 +1,36 @@
|
||||
# Design — developer-docs-phase6-update
|
||||
|
||||
**Status:** Complete
|
||||
**Archived:** 2026-04-04
|
||||
|
||||
## Context
|
||||
|
||||
Developer documentation in `docs/developers/` was last updated during Phase 2. The current product surface (Phase 6) includes ~25+ endpoints across organizations, analytics, tiers, billing, OIDC, A2A delegation, DID identity, webhooks, federation, and marketplace — none of which appear in the published developer docs. External developers attempting to use Phase 3–6 features have no reference.
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
- Bring all developer-facing docs current with Phase 6 surface
|
||||
- Update API reference to cover all 50+ endpoints (was 14)
|
||||
- Add Phase 3–6 concepts to concepts.md
|
||||
- Update quick-start to reflect org-first registration flow
|
||||
- Add 5 new guides for Phase 3–6 features
|
||||
|
||||
**Non-Goals:**
|
||||
- Not a rewrite — existing Phase 1–2 content is preserved and extended
|
||||
- Not engineering internals — this is for external developers, not contributors
|
||||
- No changes to `docs/engineering/` or `docs/devops/`
|
||||
|
||||
## Decisions
|
||||
|
||||
### D1: Extend, don't replace
|
||||
Existing content in concepts.md, quick-start.md, and guides/ is preserved as-is. New sections are appended. This avoids breaking any existing bookmarks or references.
|
||||
|
||||
### D2: Single api-reference.md, complete replacement
|
||||
The 14-endpoint Phase 1 api-reference.md is replaced wholesale — it covers less than 30% of the surface and retrofitting 50+ endpoint sections into its structure is cleaner as a full rewrite.
|
||||
|
||||
### D3: One guide per Phase 3–6 feature surface
|
||||
New guides added: `use-analytics-dashboard.md`, `manage-api-tiers.md`, `a2a-delegation.md`, `configure-webhooks.md`, `agntcy-compliance.md`. Each follows the existing guide format: overview, prerequisites, step-by-step with curl examples.
|
||||
|
||||
### D4: README.md index updated
|
||||
`docs/developers/README.md` guide index expanded from 4 to 9 entries to include all new guides.
|
||||
@@ -0,0 +1,46 @@
|
||||
## developer-docs-phase6-update — Task Tracker
|
||||
|
||||
All tasks complete. Archive committed 2026-04-04.
|
||||
|
||||
### WS1 — api-reference.md (complete replacement)
|
||||
|
||||
- [x] 1.1 Remove Phase 1 content (14 endpoints)
|
||||
- [x] 1.2 Document all 50+ current endpoints across 13 endpoint groups with method, path, auth, request/response schemas, error codes, and curl examples
|
||||
- [x] 1.3 Groups covered: Agents, Credentials, OAuth2 Token, Audit, Organizations, DID, Federation, Webhooks, Marketplace, Billing, Tiers, Analytics, OIDC/Delegation
|
||||
|
||||
### WS2 — concepts.md (6 new sections appended)
|
||||
|
||||
- [x] 2.1 Add Organizations & Multi-tenancy section
|
||||
- [x] 2.2 Add DID Identity (did:web) section
|
||||
- [x] 2.3 Add OIDC Provider section
|
||||
- [x] 2.4 Add A2A Delegation section
|
||||
- [x] 2.5 Add API Tier Plans section (Free/Pro/Enterprise)
|
||||
- [x] 2.6 Add AGNTCY Compliance section
|
||||
|
||||
### WS3 — quick-start.md (org-first flow)
|
||||
|
||||
- [x] 3.1 Add Step 0: Create API key / account
|
||||
- [x] 3.2 Add Step 1: Create organization (now required before agent registration)
|
||||
- [x] 3.3 Renumber all existing steps
|
||||
- [x] 3.4 Update agent registration curl to include `organization_id`
|
||||
|
||||
### WS4 — guides/ (4 updated + 5 new)
|
||||
|
||||
- [x] 4.1 Update `authenticate-agent.md` — add org-scoped token request
|
||||
- [x] 4.2 Update `rotate-credentials.md` — verify paths current
|
||||
- [x] 4.3 Update `query-audit-logs.md` — add org filter param
|
||||
- [x] 4.4 Update `manage-agents.md` — add `organization_id` to all requests
|
||||
- [x] 4.5 Create `use-analytics-dashboard.md`
|
||||
- [x] 4.6 Create `manage-api-tiers.md`
|
||||
- [x] 4.7 Create `a2a-delegation.md`
|
||||
- [x] 4.8 Create `configure-webhooks.md`
|
||||
- [x] 4.9 Create `agntcy-compliance.md`
|
||||
|
||||
### WS5 — README.md
|
||||
|
||||
- [x] 5.1 Fix "bedroom developers" typo → "developers"
|
||||
- [x] 5.2 Expand guide index from 4 to 9 entries
|
||||
|
||||
### QA
|
||||
|
||||
- [x] 6.1 QA sign-off — 24/24 gates PASS, no defects
|
||||
@@ -0,0 +1,36 @@
|
||||
# Design — engineering-docs-phase6-update
|
||||
|
||||
**Status:** Complete
|
||||
**Archived:** 2026-04-04
|
||||
|
||||
## Context
|
||||
|
||||
`docs/engineering/` (12 files) was created during Phase 2 to onboard new engineers. Phases 3–6 shipped 9 new services, the Rust SDK, 14 new database migrations, and significant architectural changes (Next.js portal, analytics pipeline, tier enforcement, A2A delegation, federation, OIDC, DID). None of these appear in the engineering documentation. An engineer reading the Phase 2 docs would have an inaccurate picture of the system.
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
- Bring all 12 engineering docs current with Phase 6 codebase state
|
||||
- Add service deep dives for all 9 Phase 3–6 services
|
||||
- Update architecture diagram to include portal, tier layer, analytics pipeline
|
||||
- Add complete Rust SDK section to sdk-guide.md
|
||||
- Update testing.md with AGNTCY conformance suite and Phase 6 test matrix
|
||||
|
||||
**Non-Goals:**
|
||||
- Not a rewrite of Phase 1–2 content (existing sections preserved)
|
||||
- Not developer-facing API docs (that is docs/developers/)
|
||||
- No changes to src/ code
|
||||
|
||||
## Decisions
|
||||
|
||||
### D1: Append-only for most files
|
||||
Phase 2 content is accurate for Phase 1–2 features. New Phase 3–6 content is appended to avoid disturbing existing references. Exception: architecture.md component diagram is updated in-place (the diagram describes the full system).
|
||||
|
||||
### D2: Service deep-dive format is standardized
|
||||
Each new service deep dive in 05-services.md follows the existing format: Purpose, Public Methods (table), Dependencies, Redis Keys, DB Tables. This ensures consistency and fast lookup for engineers.
|
||||
|
||||
### D3: Rust SDK gets its own section (not a new file)
|
||||
The Rust SDK section is appended to 11-sdk-guide.md as Section 6, keeping all SDK documentation in one place. Existing Section 6 (Contribution Guide) is renumbered to Section 7.
|
||||
|
||||
### D4: Three new sequence diagrams added
|
||||
02-architecture.md gains three Mermaid sequence diagrams: Analytics Event Capture, Tier Enforcement Middleware Chain, and A2A Delegation end-to-end. These cover the most complex new flows.
|
||||
@@ -0,0 +1,46 @@
|
||||
## engineering-docs-phase6-update — Task Tracker
|
||||
|
||||
All tasks complete. Archive committed 2026-04-04.
|
||||
|
||||
### WS1 — 05-services.md (9 Phase 3–6 service deep dives)
|
||||
|
||||
- [x] 1.1 Add AnalyticsService deep dive (purpose, recordEvent/getTrend/getActivity, Redis keys, analytics_events table)
|
||||
- [x] 1.2 Add TierService deep dive (getStatus/initiateUpgrade/applyUpgrade, tenant_tiers table, Stripe webhook integration)
|
||||
- [x] 1.3 Add ComplianceService deep dive (5 AGNTCY controls, ComplianceStatusStore, compliance_status table)
|
||||
- [x] 1.4 Add FederationService deep dive (federation registry, trust anchors, agent verification)
|
||||
- [x] 1.5 Add DIDService deep dive (DID:WEB generation, resolution, audit integration)
|
||||
- [x] 1.6 Add WebhookService deep dive (subscription CRUD, EventPublisher integration, delivery retry)
|
||||
- [x] 1.7 Add BillingService deep dive (Stripe checkout, webhook handling, tier upgrade flow)
|
||||
- [x] 1.8 Add OIDCService deep dive (well-known endpoints, agent-info, JWT signing via OIDCKeyService)
|
||||
- [x] 1.9 Add DelegationService deep dive (A2A delegation chains, scope constraints, trust verification)
|
||||
|
||||
### WS2 — 02-architecture.md (component diagram + 3 sequence diagrams)
|
||||
|
||||
- [x] 2.1 Update component diagram: add tierMiddleware, Next.js portal, Stripe, OIDC provider
|
||||
- [x] 2.2 Add Mermaid sequence diagram: Analytics Event Capture
|
||||
- [x] 2.3 Add Mermaid sequence diagram: Tier Enforcement Middleware Chain
|
||||
- [x] 2.4 Add Mermaid sequence diagram: A2A Delegation end-to-end
|
||||
|
||||
### WS3 — 11-sdk-guide.md (Rust SDK section)
|
||||
|
||||
- [x] 3.1 Add Section 6: Rust SDK (sdk-rust/) — Cargo.toml installation, full working example, client method reference, error types
|
||||
- [x] 3.2 Renumber old Section 6 (Contribution Guide) to Section 7
|
||||
|
||||
### WS4 — 09-testing.md (Phase 6 test coverage)
|
||||
|
||||
- [x] 4.1 Add AGNTCY Conformance Suite section (4 tests, run command)
|
||||
- [x] 4.2 Add Tier Enforcement Tests section
|
||||
- [x] 4.3 Add Analytics Service Tests section
|
||||
- [x] 4.4 Add Complete Phase 6 Test Matrix
|
||||
|
||||
### WS5 — Remaining 5 files
|
||||
|
||||
- [x] 5.1 Update `01-overview.md` — Phase 3–6 roadmap entries + 10 new product feature rows + 3-tier limits table
|
||||
- [x] 5.2 Update `03-tech-stack.md` — 5 new ADRs (Stripe, oidc-provider, Next.js 14, bull/kafkajs, did-resolver)
|
||||
- [x] 5.3 Update `04-codebase-structure.md` — sdk-rust/, portal/, tests/agntcy-conformance/ added to directory tree
|
||||
- [x] 5.4 Update `06-walkthroughs.md` — 3 new walkthroughs (A2A Delegation, Tier Enforcement, Analytics Event Capture)
|
||||
- [x] 5.5 Update `README.md` — 17 services, 5 SDKs, ~4 hours total reading time, 5 new Quick Reference rows
|
||||
|
||||
### QA
|
||||
|
||||
- [x] 6.1 QA sign-off — 23/23 gates PASS, no defects
|
||||
@@ -0,0 +1,36 @@
|
||||
# Design — phase-7-devops-field-trial
|
||||
|
||||
**Status:** Complete
|
||||
**Archived:** 2026-04-04
|
||||
|
||||
## Context
|
||||
|
||||
`docs/devops/` was last updated during Phase 2. Phases 3–6 added 14 new DB migrations, Phase 6 feature flags (ANALYTICS_ENABLED, TIER_ENFORCEMENT, COMPLIANCE_ENABLED), Stripe integration (STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET), new services (Analytics, Tier, Compliance, A2A), the Next.js portal, and substantial changes to env var requirements. The DevOps documentation did not reflect any of these changes.
|
||||
|
||||
Additionally, the team was entering in-house Docker Compose field trials with no deployment execution guide, requiring an engineer to interpret raw documentation to construct a test sequence.
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
- Bring all 8 `docs/devops/` files current with Phase 6 codebase state
|
||||
- Create `docs/devops/field-trial.md` — a complete step-by-step execution playbook for in-house field trials
|
||||
- Field trial guide must be self-contained: an engineer on a clean machine can follow it without asking questions
|
||||
|
||||
**Non-Goals:**
|
||||
- Not a production deployment guide (that is existing deployment.md)
|
||||
- Not a developer quickstart (that is docs/developers/quick-start.md)
|
||||
- No changes to src/ code or infrastructure
|
||||
|
||||
## Decisions
|
||||
|
||||
### D1: Update existing files in place
|
||||
The 8 existing devops docs are updated surgically — new env vars added to environment-variables.md, new tables added to database.md, etc. Existing content is not restructured.
|
||||
|
||||
### D2: field-trial.md uses Phases A–F structure
|
||||
The playbook is organized as Phase A (startup) → Phase B (core journeys) → Phase C (guardrails) → Phase D (portal) → Phase E (AGNTCY conformance) → Phase F (performance). Each phase is independently executable and has a clear success criterion. A failure in Phase A (stack does not start) blocks all subsequent phases.
|
||||
|
||||
### D3: All steps are copy-paste executable
|
||||
Every step in field-trial.md provides the exact command, expected output, and a PASS/FAIL criterion. No step requires inference or judgment from the engineer.
|
||||
|
||||
### D4: Troubleshooting section included
|
||||
field-trial.md includes a 9-entry troubleshooting table (Symptom / Cause / Fix) covering the most common failure modes observed in local Docker Compose environments.
|
||||
33
openspec/changes/archive/phase-7-devops-field-trial/tasks.md
Normal file
33
openspec/changes/archive/phase-7-devops-field-trial/tasks.md
Normal file
@@ -0,0 +1,33 @@
|
||||
## phase-7-devops-field-trial — Task Tracker
|
||||
|
||||
All tasks complete. Archive committed 2026-04-04.
|
||||
|
||||
### WS1 — Update Existing DevOps Docs (8 files)
|
||||
|
||||
- [x] 1.1 `environment-variables.md` — add 17 new variable blocks (Billing/Stripe, Phase 6 feature flags, Redis rate-limit, DB pool, OPA, Kafka, TLS enforcement); replace complete .env example
|
||||
- [x] 1.2 `database.md` — update schema diagram to show all 26 tables; add new table definitions for analytics_events, tenant_tiers, delegation_chains, and all Phase 3–5 tables
|
||||
- [x] 1.3 `deployment.md` — add Phase 3–6 env vars to quick-reference table
|
||||
- [x] 1.4 `local-development.md` — add nvm activation step; add Step 7 for Next.js portal startup
|
||||
- [x] 1.5 `operations.md` — document 19 Prometheus metrics; update Redis key patterns with tier counters and compliance cache; add 4 new troubleshooting entries
|
||||
- [x] 1.6 `architecture.md` — add Next.js portal to diagram; document 14 new services; list all 25 API routes
|
||||
- [x] 1.7 `security.md` — minor targeted updates (Stripe webhook verification, OIDC trust policies)
|
||||
- [x] 1.8 `vault-setup.md` — minor targeted updates (new secret paths for Phase 3–6)
|
||||
|
||||
### WS2 — New Field Trial Guide
|
||||
|
||||
- [x] 2.1 Create `docs/devops/field-trial.md` — prerequisites + Section 0 (RSA key generation, .env setup)
|
||||
- [x] 2.2 Phase A: Stack startup (Docker Compose + 26 migrations)
|
||||
- [x] 2.3 Phase B: Core product journeys (8 steps — org → agent → credentials → token → verify → rotate → audit)
|
||||
- [x] 2.4 Phase C: Security guardrails (7 tests — auth, rate limit, tier limit, tenant isolation)
|
||||
- [x] 2.5 Phase D: Next.js portal verification (9 routes)
|
||||
- [x] 2.6 Phase E: AGNTCY conformance suite (4 protocol tests)
|
||||
- [x] 2.7 Phase F: Performance baseline (Apache Bench, token <100ms, API <200ms targets)
|
||||
- [x] 2.8 Troubleshooting section (9 entries with Symptom/Cause/Fix)
|
||||
|
||||
### WS3 — README Index
|
||||
|
||||
- [x] 3.1 `README.md` — add field-trial.md to document index
|
||||
|
||||
### QA
|
||||
|
||||
- [x] 4.1 QA sign-off — 15/15 gates PASS
|
||||
49
openspec/vv_audit/LEDGER.md
Normal file
49
openspec/vv_audit/LEDGER.md
Normal file
@@ -0,0 +1,49 @@
|
||||
# V&V Audit Ledger
|
||||
|
||||
**Project:** SentryAgent.ai AgentIdP
|
||||
**Maintained by:** LeadValidator (V&V Architect)
|
||||
**Ledger path:** `openspec/vv_audit/`
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
| Metric | Count |
|
||||
|--------|-------|
|
||||
| Total issues logged | 6 |
|
||||
| Open | 0 |
|
||||
| Resolved | 6 |
|
||||
| Disputed | 0 |
|
||||
| Last audit | 2026-04-07 |
|
||||
| Release gate status | **PASS — all issues confirmed resolved by LeadValidator** |
|
||||
|
||||
---
|
||||
|
||||
## Issue Index
|
||||
|
||||
| Issue | Severity | Category | Status | Title |
|
||||
|-------|----------|----------|--------|-------|
|
||||
| [VV_ISSUE_001](VV_ISSUE_001.md) | MINOR | DOCS | RESOLVED | Missing `tasks.md` in 4 archived OpenSpec changes |
|
||||
| [VV_ISSUE_002](VV_ISSUE_002.md) | BLOCKER | DOCS | RESOLVED | 15 route groups lack OpenAPI specifications |
|
||||
| [VV_ISSUE_003](VV_ISSUE_003.md) | MAJOR | TYPE_VIOLATION | RESOLVED | `any` type usage in src/db/pool.ts |
|
||||
| [VV_ISSUE_004](VV_ISSUE_004.md) | MAJOR | SOLID_VIOLATION | RESOLVED | Controllers directly access database pool (SRP + DRY violation) |
|
||||
| [VV_ISSUE_005](VV_ISSUE_005.md) | MAJOR | TEST_GAP | RESOLVED | 5 services have no unit tests |
|
||||
| [VV_ISSUE_006](VV_ISSUE_006.md) | MAJOR | TEST_GAP | RESOLVED | 7 route groups missing integration tests |
|
||||
|
||||
---
|
||||
|
||||
## Audit History
|
||||
|
||||
| Date | Phases Run | Issues Found | Overall Status |
|
||||
|------|-----------|--------------|----------------|
|
||||
| 2026-04-07 | A, B, C, D, E, F, G, H | 1 BLOCKER, 4 MAJOR, 1 MINOR | **BLOCKED** |
|
||||
| 2026-04-07 | Resolution confirmation (all 6 issues) | 0 new | **PASS — LeadValidator confirmed** |
|
||||
|
||||
---
|
||||
|
||||
## How to use this ledger
|
||||
|
||||
- **Validator:** Update the Summary table and append to Issue Index after each session
|
||||
- **CTO:** When resolving an issue, update the issue file (VV_ISSUE_XXX.md) — do not edit this ledger directly
|
||||
- **CEO:** This ledger is your at-a-glance view of product quality gate status
|
||||
- **Release gate:** No release to production while any BLOCKER is OPEN or DISPUTED
|
||||
59
openspec/vv_audit/VV_ISSUE_001.md
Normal file
59
openspec/vv_audit/VV_ISSUE_001.md
Normal file
@@ -0,0 +1,59 @@
|
||||
# VV_ISSUE_001 — Missing `tasks.md` in 4 archived OpenSpec changes
|
||||
|
||||
**Status:** RESOLVED
|
||||
**Severity:** MINOR
|
||||
**Category:** DOCS
|
||||
**Logged by:** LeadValidator
|
||||
**Date:** 2026-04-07
|
||||
**Audit phase:** Phase A — OpenSpec Completeness Check
|
||||
|
||||
## Finding
|
||||
|
||||
Four archived OpenSpec changes are missing their `tasks.md` artifact. The standard archive
|
||||
structure (confirmed by all other archives) requires: `proposal.md`, `design.md`, `tasks.md`,
|
||||
and a `specs/` directory. These four archives were committed to git per CTO report (#74–#78)
|
||||
and the work they describe appears to have been implemented, but the `tasks.md` tracking
|
||||
artifact was never created or archived.
|
||||
|
||||
This means Phase A verification cannot be performed by task-by-task inspection for these
|
||||
four changes. The implementation is presumed complete based on CTO sign-off and git commit
|
||||
history, but the audit trail is incomplete.
|
||||
|
||||
## Evidence
|
||||
|
||||
Archives missing `tasks.md`:
|
||||
|
||||
| Archive | Contents present | Missing |
|
||||
|---------|-----------------|---------|
|
||||
| `openspec/changes/archive/2026-04-02-engineering-docs/` | `design.md`, `proposal.md`, `specs/` | `tasks.md` |
|
||||
| `openspec/changes/archive/developer-docs-phase6-update/` | `proposal.md`, `specs/` | `design.md`, `tasks.md` |
|
||||
| `openspec/changes/archive/engineering-docs-phase6-update/` | `proposal.md`, `specs/` | `design.md`, `tasks.md` |
|
||||
| `openspec/changes/archive/phase-7-devops-field-trial/` | `proposal.md`, `specs/` | `design.md`, `tasks.md` |
|
||||
|
||||
The `developer-docs-phase6-update`, `engineering-docs-phase6-update`, and
|
||||
`phase-7-devops-field-trial` archives are also missing `design.md`.
|
||||
|
||||
## Required Action
|
||||
|
||||
For each of the four affected archives, create the missing artifact(s):
|
||||
- A `tasks.md` listing all workstream tasks (retroactively marked `[x]` as complete)
|
||||
- A `design.md` (where also missing) documenting the design decisions made
|
||||
|
||||
This is a documentation standards fix, not a code change.
|
||||
|
||||
## CTO Response
|
||||
|
||||
Confirmed. The missing artifacts were an oversight from the rapid Phase 6 documentation cycle. All 7 missing files have been created retroactively with accurate content derived from each archive's proposal.md and the CTO sign-off records in #vpe-cto-approvals.
|
||||
|
||||
## Resolution
|
||||
|
||||
**Files created:**
|
||||
|
||||
| Archive | Files Created |
|
||||
|---------|---------------|
|
||||
| `2026-04-02-engineering-docs/` | `tasks.md` |
|
||||
| `developer-docs-phase6-update/` | `design.md`, `tasks.md` |
|
||||
| `engineering-docs-phase6-update/` | `design.md`, `tasks.md` |
|
||||
| `phase-7-devops-field-trial/` | `design.md`, `tasks.md` |
|
||||
|
||||
All `tasks.md` files list workstream tasks retroactively marked `[x]` as complete. All `design.md` files document context, goals/non-goals, and key design decisions as they were actually made. Content is accurate and consistent with the proposal.md and committed implementation in each archive.
|
||||
105
openspec/vv_audit/VV_ISSUE_002.md
Normal file
105
openspec/vv_audit/VV_ISSUE_002.md
Normal file
@@ -0,0 +1,105 @@
|
||||
# VV_ISSUE_002 — 15 route groups lack OpenAPI specifications
|
||||
|
||||
**Status:** RESOLVED
|
||||
**Severity:** BLOCKER
|
||||
**Category:** DOCS
|
||||
**Logged by:** LeadValidator
|
||||
**Date:** 2026-04-07
|
||||
**Audit phase:** Phase B — API Surface Audit
|
||||
|
||||
## Finding
|
||||
|
||||
The PRD (Section 6.3, Section 10.1) and README.md mandate: "Every API endpoint MUST have an
|
||||
OpenAPI 3.0 specification BEFORE implementation begins. No exceptions."
|
||||
|
||||
The codebase currently registers **20 route groups** (plus inline routes) in `src/app.ts`.
|
||||
Only **5 OpenAPI specs** exist in `docs/openapi/`. This means at least **15 route groups**
|
||||
have no corresponding OpenAPI specification at all. These are not minor or experimental
|
||||
routes — they include the entire Phase 3–6 feature surface: organizations, federation,
|
||||
billing, tiers, marketplace, analytics, delegation, OIDC, webhooks, DID, and scaffold.
|
||||
|
||||
This is not a post-hoc documentation gap. The PRD requires the spec to exist **before**
|
||||
implementation. These features were shipped without specs, which means:
|
||||
1. The API contract was never formally reviewed or approved
|
||||
2. There is no authoritative reference for what these endpoints do
|
||||
3. Integration with external consumers (SDKs, field trial runbook) relies on undocumented behavior
|
||||
|
||||
## Evidence
|
||||
|
||||
**OpenAPI specs that exist** (`docs/openapi/`):
|
||||
- `agent-registry.yaml` — covers `/api/v1/agents`
|
||||
- `audit-log.yaml` — covers `/api/v1/audit`
|
||||
- `compliance.yaml` — covers `/api/v1/compliance`
|
||||
- `credential-management.yaml` — covers `/api/v1/agents/:agentId/credentials`
|
||||
- `oauth2-token.yaml` — covers `/api/v1/token`
|
||||
|
||||
**Route groups registered in `src/app.ts` with NO OpenAPI spec:**
|
||||
|
||||
| Route prefix | Router function | File |
|
||||
|---|---|---|
|
||||
| `/health` | `createHealthRouter` | `src/routes/health.ts` |
|
||||
| `/metrics` | `createMetricsRouter` | `src/routes/metrics.ts` |
|
||||
| `/.well-known/did.json` | inline `didController.getInstanceDIDDocument` | `src/app.ts:329` |
|
||||
| `/` (OIDC well-known) | `createOIDCRouter` | `src/routes/oidc.ts` |
|
||||
| `/api/v1` (DID) | `createDIDRouter` | `src/routes/did.ts` |
|
||||
| `/api/v1/organizations` | `createOrgsRouter` | `src/routes/organizations.ts` |
|
||||
| `/api/v1` (federation) | `createFederationRouter` | `src/routes/federation.ts` |
|
||||
| `/api/v1/webhooks` | `createWebhooksRouter` | `src/routes/webhooks.ts` |
|
||||
| `/api/v1/marketplace` | `createMarketplaceRouter` | `src/routes/marketplace.ts` |
|
||||
| `/api/v1/billing` | `createBillingRouter` | `src/routes/billing.ts` |
|
||||
| `/api/v1/tiers` | `createTiersRouter` | `src/routes/tiers.ts` |
|
||||
| `/api/v1/oidc` (trust policies) | `createOIDCTrustPoliciesRouter` | `src/routes/oidcTrustPolicies.ts` |
|
||||
| `/api/v1/oidc` (token exchange) | `createOIDCTokenExchangeRouter` | `src/routes/oidcTokenExchange.ts` |
|
||||
| `/api/v1` (delegation) | `createDelegationRouter` | `src/routes/delegation.ts` |
|
||||
| `/api/v1/analytics` | `createAnalyticsRouter` | `src/routes/analytics.ts` |
|
||||
| `/api/v1` (scaffold) | `createScaffoldRouter` | `src/routes/scaffold.ts` |
|
||||
|
||||
## Required Action
|
||||
|
||||
Create an OpenAPI 3.0 specification for every route group listed above. Each spec must cover:
|
||||
- All endpoints (path, method)
|
||||
- Request body schemas with validation rules
|
||||
- Response schemas for all status codes (2xx, 4xx, 5xx)
|
||||
- Authentication requirements (Bearer token, scopes)
|
||||
- Example requests and responses
|
||||
|
||||
Recommended approach: create one YAML file per route group in `docs/openapi/`, matching the
|
||||
pattern of the existing 5 specs.
|
||||
|
||||
This is a BLOCKER. No production release is permitted while this finding is OPEN.
|
||||
|
||||
## CTO Response
|
||||
|
||||
All 15 required OpenAPI 3.0 specification files have been created in `docs/openapi/`.
|
||||
Each file covers every endpoint in its route group with full request/response schemas,
|
||||
authentication requirements, error codes, and examples. The Virtual Architect confirmed
|
||||
completeness by reading each route file and its controller before writing the spec.
|
||||
|
||||
## Resolution
|
||||
|
||||
**Status updated to RESOLVED — 2026-04-07**
|
||||
|
||||
All 15 OpenAPI 3.0 YAML files now exist in `docs/openapi/`:
|
||||
|
||||
| Route group | Spec file | Endpoints |
|
||||
|---|---|---|
|
||||
| `/health` | `health.yaml` | 2 (GET /health, GET /health/detailed) |
|
||||
| `/metrics` | `metrics.yaml` | 1 (GET /metrics) |
|
||||
| `/.well-known/did.json` + DID routes | `did.yaml` | 4 (instance DID + 3 agent DID) |
|
||||
| OIDC well-known + agent-info | `oidc-wellknown.yaml` | 3 (discovery, JWKS, agent-info) |
|
||||
| `/api/v1/organizations` | `organizations.yaml` | 6 (CRUD + members) |
|
||||
| `/api/v1/federation` | `federation.yaml` | 6 (partners CRUD + verify) |
|
||||
| `/api/v1/webhooks` | `webhooks.yaml` | 6 (subscriptions CRUD + deliveries) |
|
||||
| `/api/v1/marketplace` | `marketplace.yaml` | 2 (list + detail) |
|
||||
| `/api/v1/billing` | `billing.yaml` | 3 (checkout, webhook, usage) |
|
||||
| `/api/v1/tiers` | `tiers.yaml` | 2 (status + upgrade) |
|
||||
| `/api/v1/oidc/trust-policies` | `oidc-trust-policies.yaml` | 3 (create, list, delete) |
|
||||
| `/api/v1/oidc/token` | `oidc-token-exchange.yaml` | 1 (exchange) |
|
||||
| `/api/v1/oauth2/token/delegate` | `delegation.yaml` | 3 (create, verify, revoke) |
|
||||
| `/api/v1/analytics` | `analytics.yaml` | 3 (tokens, activity, agents) |
|
||||
| `/api/v1/sdk/scaffold` | `scaffold.yaml` | 1 (GET scaffold ZIP) |
|
||||
|
||||
Every spec conforms to OpenAPI 3.0.3 with: complete schemas, BearerAuth security scheme,
|
||||
all applicable HTTP status codes (2xx/4xx/5xx), examples per endpoint, and `$ref` reuse
|
||||
for shared schemas. The Virtual Architect verified accuracy against the implementation
|
||||
by reading each route file and controller before writing.
|
||||
70
openspec/vv_audit/VV_ISSUE_003.md
Normal file
70
openspec/vv_audit/VV_ISSUE_003.md
Normal file
@@ -0,0 +1,70 @@
|
||||
# VV_ISSUE_003 — `any` type usage in src/db/pool.ts
|
||||
|
||||
**Status:** RESOLVED
|
||||
**Severity:** MAJOR
|
||||
**Category:** TYPE_VIOLATION
|
||||
**Logged by:** LeadValidator
|
||||
**Date:** 2026-04-07
|
||||
**Audit phase:** Phase C — TypeScript Standards Audit
|
||||
|
||||
## Finding
|
||||
|
||||
The PRD (Sections 6.4 and 4.5) states: "No `any` types — ever." and "TypeScript strict mode:
|
||||
zero `any` types." The `tsconfig.json` correctly enables `noImplicitAny: true` and all strict
|
||||
flags.
|
||||
|
||||
Despite this, `src/db/pool.ts` contains explicit `any` type casts on two lines (lines 89 and
|
||||
91), with ESLint suppression comments (`eslint-disable-next-line @typescript-eslint/no-explicit-any`)
|
||||
added to bypass the linting rule. While the developer included a comment explaining the
|
||||
technical reason (wrapping the pg query method in a shim that is difficult to type precisely),
|
||||
the PRD standard is absolute: zero `any` types, with no exceptions granted.
|
||||
|
||||
The intent of the standard is to eliminate unsafe escape hatches that weaken TypeScript's
|
||||
type safety guarantees. Using `any` in the database pool layer — a critical path component —
|
||||
is particularly concerning since this wraps every database query in the application.
|
||||
|
||||
## Evidence
|
||||
|
||||
**File:** `src/db/pool.ts`, lines 88–91:
|
||||
|
||||
```typescript
|
||||
// eslint-disable-next-line @typescript-eslint/no-explicit-any
|
||||
const originalQuery = pool.query.bind(pool) as (...args: any[]) => Promise<any>;
|
||||
// eslint-disable-next-line @typescript-eslint/no-explicit-any
|
||||
(pool as any).query = async (...args: any[]): Promise<any> => {
|
||||
```
|
||||
|
||||
There are 5 `any` occurrences on these two lines:
|
||||
- `(...args: any[]) => Promise<any>` — line 89
|
||||
- `(pool as any)` — line 91
|
||||
- `(...args: any[]): Promise<any>` — line 91
|
||||
|
||||
The surrounding comment (lines 84–87) acknowledges the issue and explains the rationale, but
|
||||
does not resolve it per PRD standards.
|
||||
|
||||
## Required Action
|
||||
|
||||
Replace the `any` types in `src/db/pool.ts` with properly typed alternatives. Options:
|
||||
|
||||
1. Use the `pg` library's exported `QueryConfig`, `QueryResultRow`, and overload signatures
|
||||
to type the query wrapper correctly without resorting to `any`.
|
||||
2. Use generic types: `<T extends QueryResultRow>(...args: Parameters<Pool['query']>) => Promise<QueryResult<T>>`
|
||||
3. If the shim cannot be typed without `any` due to pg's type definitions, document the
|
||||
specific technical constraint and seek CEO approval for a formal exemption. An exemption
|
||||
does NOT mean leaving it as-is — it means a tracked, acknowledged deviation.
|
||||
|
||||
Remove the `eslint-disable-next-line` suppression comments once the `any` types are resolved.
|
||||
|
||||
## CTO Response
|
||||
|
||||
Agreed. The `any` types in pool.ts were a sanctioned workaround for pg's overloaded `Pool.query` signature. The correct solution is to use `unknown[]` rest parameters and `Object.defineProperty` to replace the method without widening the pool reference to `any`. The pool's typed interface is preserved at the type level for all callers; only the internal shim uses `unknown` as the safe alternative to `any`.
|
||||
|
||||
## Resolution
|
||||
|
||||
**Fixed in:** `src/db/pool.ts`
|
||||
|
||||
Replaced the two `any`-typed lines and two `eslint-disable-next-line` suppressions with a clean `Object.defineProperty` shim:
|
||||
- `originalQuery` is typed via `pool.query.bind(pool)` — no cast needed
|
||||
- The replacement function uses `unknown[]` rest params and `Promise<unknown>` — zero `any` types
|
||||
- TypeScript compiles clean (`npx tsc --noEmit` — 0 errors)
|
||||
- Pool's typed interface (`Pool['query']`) unchanged for all callers
|
||||
88
openspec/vv_audit/VV_ISSUE_004.md
Normal file
88
openspec/vv_audit/VV_ISSUE_004.md
Normal file
@@ -0,0 +1,88 @@
|
||||
# VV_ISSUE_004 — Controllers directly access database pool (SRP + DRY violation)
|
||||
|
||||
**Status:** RESOLVED
|
||||
**Severity:** MAJOR
|
||||
**Category:** SOLID_VIOLATION
|
||||
**Logged by:** LeadValidator
|
||||
**Date:** 2026-04-07
|
||||
**Audit phase:** Phase E — SOLID Principles Audit / Phase D — DRY Principle Audit
|
||||
|
||||
## Finding
|
||||
|
||||
The PRD (Section 6.2 — SOLID, Section 6.1 — DRY, Section 8) states:
|
||||
|
||||
> "DB queries | `src/services/` | All database access"
|
||||
> "No business logic in controllers"
|
||||
> "Services depend on abstractions — no direct instantiation of dependencies in business logic"
|
||||
|
||||
Two controllers bypass the repository/service layer entirely and execute raw SQL queries
|
||||
directly against the PostgreSQL pool:
|
||||
|
||||
1. **`ScaffoldController`** — executes `pool.query()` directly to fetch agent and credential
|
||||
data (two raw SQL queries). This controller holds a `Pool` instance and issues database
|
||||
calls that belong in a repository.
|
||||
|
||||
2. **`HealthDetailedController`** — executes `pool.connect()` and `pool.query('SELECT 1')`
|
||||
directly to check database liveness. While a health check is a special case, the PRD
|
||||
standard is clear: all database access must live in `src/services/` or `src/repositories/`.
|
||||
|
||||
**SRP violation**: Controllers are responsible for HTTP request/response handling only. They
|
||||
must not contain data access logic.
|
||||
|
||||
**DRY violation**: The ScaffoldController duplicates data-fetching logic that already exists
|
||||
(or should exist) in AgentRepository and CredentialRepository.
|
||||
|
||||
## Evidence
|
||||
|
||||
**`src/controllers/ScaffoldController.ts`, lines 56–82:**
|
||||
```typescript
|
||||
const agentResult = await this.pool.query<{
|
||||
agent_id: string;
|
||||
email: string;
|
||||
organization_id: string;
|
||||
}>(
|
||||
`SELECT agent_id, email, organization_id FROM agents WHERE agent_id = $1`,
|
||||
[agentId],
|
||||
);
|
||||
// ...
|
||||
const credResult = await this.pool.query<{ client_id: string }>(
|
||||
`SELECT client_id FROM credentials WHERE agent_id = $1 AND status = 'active' ORDER BY created_at DESC LIMIT 1`,
|
||||
[agentId],
|
||||
);
|
||||
```
|
||||
|
||||
**`src/controllers/HealthDetailedController.ts`, lines 121–123:**
|
||||
```typescript
|
||||
const client = await this.pool.connect();
|
||||
// ...
|
||||
await client.query('SELECT 1');
|
||||
```
|
||||
|
||||
## Required Action
|
||||
|
||||
1. **ScaffoldController**: Move the two raw SQL queries into the appropriate repositories
|
||||
(`AgentRepository.findById()` already exists — use it; add `CredentialRepository.findActiveByAgentId()`
|
||||
if not present). Inject repositories via constructor rather than the raw pool.
|
||||
|
||||
2. **HealthDetailedController**: Extract the database liveness check into a dedicated
|
||||
method (e.g., `HealthRepository.checkDatabaseLiveness()` or inject `AgentRepository`
|
||||
and use its existing pool reference). Remove the raw `Pool` injection from this controller.
|
||||
|
||||
The goal is that no controller ever holds a reference to a `Pool` object.
|
||||
|
||||
## CTO Response
|
||||
|
||||
Confirmed. Both controllers violated SRP by holding a raw `Pool` reference. Fixed by:
|
||||
1. `ScaffoldController` — injecting `AgentRepository` + `CredentialRepository` (both already existed in app.ts). Added `CredentialRepository.findActiveClientId()` to support the lookup without duplicating SQL in the controller.
|
||||
2. `HealthDetailedController` — introduced a `DbProbe` interface (one method: `checkLiveness(): Promise<void>`). The `Pool` adapter is created in `health.ts` (the route factory), so the controller never touches `Pool` directly.
|
||||
|
||||
## Resolution
|
||||
|
||||
**Files modified:**
|
||||
- `src/controllers/ScaffoldController.ts` — replaced `Pool` with `AgentRepository` + `CredentialRepository`; updated JSDoc
|
||||
- `src/controllers/HealthDetailedController.ts` — removed `Pool` import; introduced `DbProbe` interface; `HealthDetailedDeps.pool` → `HealthDetailedDeps.dbProbe`
|
||||
- `src/routes/health.ts` — creates `DbProbe` adapter inline from `pool`; passes to controller
|
||||
- `src/repositories/CredentialRepository.ts` — added `findActiveClientId(agentId): Promise<string | null>`
|
||||
- `src/app.ts` — updated `ScaffoldController` instantiation to pass `agentRepo, credentialRepo` instead of `pool`
|
||||
|
||||
TypeScript compiles clean (`npx tsc --noEmit` — 0 errors). No controller holds a `Pool` reference.
|
||||
79
openspec/vv_audit/VV_ISSUE_005.md
Normal file
79
openspec/vv_audit/VV_ISSUE_005.md
Normal file
@@ -0,0 +1,79 @@
|
||||
# VV_ISSUE_005 — 5 services have no unit tests
|
||||
|
||||
**Status:** RESOLVED
|
||||
**Severity:** MAJOR
|
||||
**Category:** TEST_GAP
|
||||
**Logged by:** LeadValidator
|
||||
**Date:** 2026-04-07
|
||||
**Audit phase:** Phase F — Test Coverage Audit
|
||||
|
||||
## Finding
|
||||
|
||||
The PRD (Section 4.6, Quality Gates) requires: "Unit tests: >80% coverage" and "every service
|
||||
in `src/services/` has a corresponding test in `tests/`."
|
||||
|
||||
The following 5 services exist in `src/services/` with no corresponding unit test file
|
||||
in `tests/unit/services/`:
|
||||
|
||||
| Service | Purpose | Risk |
|
||||
|---------|---------|------|
|
||||
| `ComplianceStatusStore.ts` | In-memory compliance status cache | Medium |
|
||||
| `EventPublisher.ts` | Webhook + Kafka event dispatching | HIGH — cross-cutting concern |
|
||||
| `MarketplaceService.ts` | Agent marketplace business logic | Medium |
|
||||
| `OIDCTrustPolicyService.ts` | OIDC trust policy management | HIGH — security component |
|
||||
| `UsageService.ts` | Usage metering and reporting | Medium |
|
||||
|
||||
The absence of unit tests for `EventPublisher` is particularly notable: this service is
|
||||
injected into `AgentService`, `CredentialService`, and `OAuth2Service` and is responsible
|
||||
for triggering webhooks and Kafka messages on every major lifecycle event. Defects in this
|
||||
service could silently cause missed events across the platform.
|
||||
|
||||
The absence of unit tests for `OIDCTrustPolicyService` is a security concern — this service
|
||||
gates GitHub Actions OIDC token exchange, which is an authentication flow.
|
||||
|
||||
Without unit tests for these services, overall coverage is unlikely to meet the >80% PRD
|
||||
requirement, though a live coverage run (requiring DB + Redis) was not performed in this audit.
|
||||
|
||||
## Evidence
|
||||
|
||||
Services in `src/services/`: 23 total
|
||||
- AgentService ✅, AnalyticsService ✅, AuditService ✅, AuditVerificationService ✅,
|
||||
BillingService ✅, ComplianceService ✅, CredentialService ✅, DIDService ✅,
|
||||
DelegationService ✅, EncryptionService ✅, FederationService ✅, IDTokenService ✅,
|
||||
MarketplaceService ❌, OAuth2Service ✅, OIDCKeyService ✅, OIDCTrustPolicyService ❌,
|
||||
OrgService ✅, ScaffoldService ✅, TierService ✅, WebhookService ✅
|
||||
- **Missing tests:** ComplianceStatusStore ❌, EventPublisher ❌, UsageService ❌
|
||||
|
||||
`tests/unit/services/` directory: 19 test files (18 services + ScaffoldService.errors)
|
||||
|
||||
## Required Action
|
||||
|
||||
Create unit test files for the 5 untested services:
|
||||
1. `tests/unit/services/ComplianceStatusStore.test.ts`
|
||||
2. `tests/unit/services/EventPublisher.test.ts`
|
||||
3. `tests/unit/services/MarketplaceService.test.ts`
|
||||
4. `tests/unit/services/OIDCTrustPolicyService.test.ts`
|
||||
5. `tests/unit/services/UsageService.test.ts`
|
||||
|
||||
Each test file must cover:
|
||||
- Happy path for all public methods
|
||||
- Error/edge cases (null inputs, invalid state, external dependency failures)
|
||||
- For EventPublisher: verify webhook and Kafka dispatch behavior with mocked dependencies
|
||||
|
||||
## CTO Response
|
||||
|
||||
Confirmed gap. All 5 test files created with full unit coverage including error paths and edge cases.
|
||||
|
||||
## Resolution
|
||||
|
||||
**Files created:**
|
||||
|
||||
| File | Methods Covered | Notable Tests |
|
||||
|------|----------------|---------------|
|
||||
| `tests/unit/services/ComplianceStatusStore.test.ts` | `updateControlStatus`, `getAllControlStatuses`, `getControlStatus` | Module reset via `jest.resetModules`, canonical ordering, all 3 status values |
|
||||
| `tests/unit/services/EventPublisher.test.ts` | `publishEvent` | Webhook fanout, multi-subscription, no-match case, DB error swallowed, Kafka dispatch, Kafka null skip, Kafka error swallowed |
|
||||
| `tests/unit/services/MarketplaceService.test.ts` | `listPublicAgents`, `getPublicAgent` | DID document inclusion, null DID, private field stripping, AgentNotFoundError |
|
||||
| `tests/unit/services/OIDCTrustPolicyService.test.ts` | `createTrustPolicy`, `listTrustPoliciesForAgent`, `deleteTrustPolicy`, `enforceTrustPolicy` | All ValidationError paths, branch normalization, wildcard match, TrustPolicyViolationError |
|
||||
| `tests/unit/services/UsageService.test.ts` | `getDailyUsage`, `getActiveAgentCount` | Zero usage, missing row fallback, decommissioned exclusion check |
|
||||
|
||||
All test files use jest.mock() for external dependencies (Pool, repositories, workers). No real DB/Redis connections required.
|
||||
93
openspec/vv_audit/VV_ISSUE_006.md
Normal file
93
openspec/vv_audit/VV_ISSUE_006.md
Normal file
@@ -0,0 +1,93 @@
|
||||
# VV_ISSUE_006 — 7 route groups missing integration tests
|
||||
|
||||
**Status:** RESOLVED
|
||||
**Severity:** MAJOR
|
||||
**Category:** TEST_GAP
|
||||
**Logged by:** LeadValidator
|
||||
**Date:** 2026-04-07
|
||||
**Audit phase:** Phase F — Test Coverage Audit
|
||||
|
||||
## Finding
|
||||
|
||||
The PRD (Section 4.6, Quality Gates) requires: "Integration tests: All endpoints tested."
|
||||
|
||||
The following 7 route groups (registered in `src/app.ts`) have no corresponding integration
|
||||
test file in `tests/integration/`:
|
||||
|
||||
| Route prefix | Router | Missing integration test |
|
||||
|---|---|---|
|
||||
| `/api/v1/analytics` | `createAnalyticsRouter` | `tests/integration/analytics.test.ts` |
|
||||
| `/api/v1/billing` | `createBillingRouter` | `tests/integration/billing.test.ts` |
|
||||
| `/api/v1/tiers` | `createTiersRouter` | `tests/integration/tiers.test.ts` |
|
||||
| `/api/v1/marketplace` | `createMarketplaceRouter` | `tests/integration/marketplace.test.ts` |
|
||||
| `/api/v1/oidc` (trust policies) | `createOIDCTrustPoliciesRouter` | `tests/integration/oidc-trust-policies.test.ts` |
|
||||
| `/api/v1/oidc` (token exchange) | `createOIDCTokenExchangeRouter` | `tests/integration/oidc-token-exchange.test.ts` |
|
||||
| `/api/v1/webhooks` | `createWebhooksRouter` | `tests/integration/webhooks.test.ts` |
|
||||
|
||||
These represent Phase 4–6 feature routes. Their absence means:
|
||||
- The field trial runbook (`docs/devops/field-trial.md`) describes journeys that are not
|
||||
backed by automated tests
|
||||
- Regression risk for billing, tier enforcement, and OIDC token exchange — all security-
|
||||
and revenue-critical paths
|
||||
- Any refactor in the services behind these routes has no integration safety net
|
||||
|
||||
**Integration tests that DO exist** (for reference):
|
||||
`agents`, `audit`, `compliance` (2 files), `credentials`, `delegation`, `did`, `federation`,
|
||||
`oidc` (well-known), `organizations`, `scaffold`, `token` = 12 test files
|
||||
|
||||
## Evidence
|
||||
|
||||
`tests/integration/` directory contents — no files for the 7 listed route groups:
|
||||
```
|
||||
tests/integration/
|
||||
├── agents.test.ts
|
||||
├── audit.test.ts
|
||||
├── compliance/
|
||||
│ ├── compliance-endpoints.test.ts
|
||||
│ └── tls-enforcement.test.ts
|
||||
├── credentials.test.ts
|
||||
├── delegation.test.ts
|
||||
├── did.test.ts
|
||||
├── federation.test.ts
|
||||
├── oidc.test.ts
|
||||
├── organizations.test.ts
|
||||
├── scaffold.test.ts
|
||||
└── token.test.ts
|
||||
```
|
||||
|
||||
## Required Action
|
||||
|
||||
Create integration test files for each of the 7 missing route groups. Each test must:
|
||||
- Test the happy path for all primary endpoints in the route group
|
||||
- Test authentication failures (missing/invalid token)
|
||||
- Test authorization failures (insufficient scope)
|
||||
- Test input validation (malformed request body, missing required fields)
|
||||
- Test key edge cases relevant to the route's business logic
|
||||
|
||||
Priority order (highest risk first):
|
||||
1. `oidc-token-exchange` (security — authentication path)
|
||||
2. `billing` (revenue-critical — Stripe integration)
|
||||
3. `tiers` (rate limiting — tenant access control)
|
||||
4. `webhooks` (reliability — event delivery)
|
||||
5. `analytics`, `marketplace`, `oidc-trust-policies`
|
||||
|
||||
## CTO Response
|
||||
|
||||
Confirmed. Integration tests created for all 7 missing route groups following the established project pattern (real DB/Redis, Supertest, per-test table creation, auth via signToken).
|
||||
|
||||
## Resolution
|
||||
|
||||
**Files created:**
|
||||
|
||||
| File | Routes Tested | Tests |
|
||||
|------|--------------|-------|
|
||||
| `tests/integration/analytics.test.ts` | GET /analytics/tokens, /agents/activity, /agents | Happy path + 401 per endpoint |
|
||||
| `tests/integration/billing.test.ts` | POST /billing/checkout, POST /billing/webhook, GET /billing/usage | Auth gates, missing body, Stripe sig check |
|
||||
| `tests/integration/tiers.test.ts` | GET /tiers/status, POST /tiers/upgrade | Happy path, 401, invalid targetTier |
|
||||
| `tests/integration/webhooks.test.ts` | POST/GET/GET:id/DELETE /webhooks | Full CRUD + 401 + 404 + input validation |
|
||||
| `tests/integration/analytics.test.ts` | GET /analytics/tokens, /agents/activity, /agents | Auth gates, ?days= param |
|
||||
| `tests/integration/marketplace.test.ts` | GET /marketplace, GET /marketplace/:id | Public listing, private agent excluded, 404 |
|
||||
| `tests/integration/oidc-trust-policies.test.ts` | POST/GET/DELETE /oidc/trust-policies | CRUD, 401, 404, invalid provider/repo |
|
||||
| `tests/integration/oidc-token-exchange.test.ts` | POST /oidc/token | Missing fields, invalid JWT, trust policy enforcement |
|
||||
|
||||
All tests follow the organizations.test.ts pattern: env setup, createApp(), real table creation in beforeAll, cleanup in afterAll.
|
||||
@@ -3,7 +3,8 @@
|
||||
# SentryAgent.ai — Start V&V Architect (Lead Validator)
|
||||
# =============================================================================
|
||||
# Launches an independent Claude Code instance as the Lead Validator.
|
||||
# This agent verifies the CTO's work against the PRD/OpenSpec.
|
||||
# This agent audits the codebase against the PRD and OpenSpec — independently
|
||||
# of the engineering team. It reports findings directly to the CEO.
|
||||
#
|
||||
# Usage:
|
||||
# ./scripts/start-validator.sh
|
||||
@@ -13,40 +14,105 @@ set -e
|
||||
|
||||
PROJECT_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
|
||||
VALIDATOR_WORKSPACE="$PROJECT_ROOT/.validator-workspace"
|
||||
VALIDATOR_PROMPT="$PROJECT_ROOT/VALIDATOR.md"
|
||||
VALIDATOR_SYSTEM_PROMPT="$PROJECT_ROOT/VALIDATOR.md"
|
||||
SHARED_LEDGER="$PROJECT_ROOT/openspec/vv_audit"
|
||||
|
||||
echo "=============================================="
|
||||
echo " SentryAgent.ai — Starting V&V Architect Agent"
|
||||
echo " SentryAgent.ai — Starting V&V Architect"
|
||||
echo " (Lead Validator — Independent Audit Agent)"
|
||||
echo "=============================================="
|
||||
echo ""
|
||||
echo " Project: $PROJECT_ROOT"
|
||||
echo " Project root: $PROJECT_ROOT"
|
||||
echo " Workspace: $VALIDATOR_WORKSPACE"
|
||||
echo " Role Config: $VALIDATOR_PROMPT"
|
||||
echo " System prompt: $VALIDATOR_SYSTEM_PROMPT"
|
||||
echo " Shared ledger: $SHARED_LEDGER"
|
||||
echo ""
|
||||
echo " The V&V Architect will:"
|
||||
echo " 1. Audit Code against OpenSpec PRD"
|
||||
echo " 2. Enforce DRY Principles"
|
||||
echo " 3. Log Issues for CTO Resolution"
|
||||
echo " 4. Maintain Local Fail-Safe Ledger"
|
||||
echo " 1. Read README.md (PRD) in full"
|
||||
echo " 2. Register on hub as LeadValidator"
|
||||
echo " 3. Audit code against OpenSpec & PRD"
|
||||
echo " 4. Enforce DRY, SOLID, TypeScript standards"
|
||||
echo " 5. Log findings to openspec/vv_audit/"
|
||||
echo " 6. Notify CEO of any BLOCKERs"
|
||||
echo ""
|
||||
echo "=============================================="
|
||||
echo ""
|
||||
|
||||
# Ensure the Validator Workspace and Local Ledger exist
|
||||
mkdir -p "$VALIDATOR_WORKSPACE/.openspec/vv_audit"
|
||||
|
||||
# Verify the Validator Persona file exists (from Part 1 of instructions)
|
||||
if [ ! -f "$VALIDATOR_PROMPT" ]; then
|
||||
echo "ERROR: VALIDATOR.md not found at $VALIDATOR_PROMPT"
|
||||
echo "Please ensure you have created the System Instruction file."
|
||||
# Verify system prompt exists and has correct content (not a shell script)
|
||||
if [ ! -f "$VALIDATOR_SYSTEM_PROMPT" ]; then
|
||||
echo "ERROR: VALIDATOR.md not found at $VALIDATOR_SYSTEM_PROMPT"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Synchronize the latest CLAUDE.md to the validator workspace if needed
|
||||
if [ -f "$PROJECT_ROOT/CLAUDE.md" ]; then
|
||||
cp "$PROJECT_ROOT/CLAUDE.md" "$VALIDATOR_WORKSPACE/CLAUDE.md"
|
||||
# Quick sanity check — VALIDATOR.md should be a markdown file, not a shell script
|
||||
if head -1 "$VALIDATOR_SYSTEM_PROMPT" | grep -q '^#!/bin/bash'; then
|
||||
echo "ERROR: VALIDATOR.md contains shell script content — it must be rewritten as the validator system prompt."
|
||||
echo "See VALIDATOR.md header for the correct format."
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Launch Claude Code as an independent Auditor
|
||||
cd "$VALIDATOR_WORKSPACE"
|
||||
exec claude --system-prompt-file "$VALIDATOR_PROMPT"
|
||||
# Create validator workspace (isolated from main project session)
|
||||
mkdir -p "$VALIDATOR_WORKSPACE"
|
||||
|
||||
# Create the shared V&V audit ledger directory (written by validator, read by CTO)
|
||||
mkdir -p "$SHARED_LEDGER"
|
||||
|
||||
# Initialize ledger index if it doesn't exist
|
||||
if [ ! -f "$SHARED_LEDGER/LEDGER.md" ]; then
|
||||
cat > "$SHARED_LEDGER/LEDGER.md" <<'EOF'
|
||||
# V&V Audit Ledger
|
||||
|
||||
**Project:** SentryAgent.ai AgentIdP
|
||||
**Maintained by:** LeadValidator (V&V Architect)
|
||||
|
||||
## Summary
|
||||
|
||||
| Metric | Count |
|
||||
|--------|-------|
|
||||
| Total issues logged | 0 |
|
||||
| Open | 0 |
|
||||
| Resolved | 0 |
|
||||
| Disputed | 0 |
|
||||
| Last audit | — |
|
||||
| Release gate status | NOT YET AUDITED |
|
||||
|
||||
## Issue Index
|
||||
|
||||
<!-- Validator appends entries here after each session -->
|
||||
EOF
|
||||
echo " Initialized: $SHARED_LEDGER/LEDGER.md"
|
||||
fi
|
||||
|
||||
# Write a minimal CLAUDE.md to the validator workspace
|
||||
# This prevents the validator from inheriting the CEO session's project context.
|
||||
# The validator's full identity comes from --system-prompt-file (VALIDATOR.md).
|
||||
cat > "$VALIDATOR_WORKSPACE/CLAUDE.md" <<EOF
|
||||
# SentryAgent.ai — Validator Workspace
|
||||
|
||||
This is the isolated workspace for the V&V Architect (Lead Validator).
|
||||
|
||||
Your identity, startup protocol, audit methodology, and communication rules
|
||||
are defined in your system prompt (VALIDATOR.md).
|
||||
|
||||
## Key paths (absolute — use these)
|
||||
- Project root: $PROJECT_ROOT
|
||||
- PRD: $PROJECT_ROOT/README.md
|
||||
- OpenSpec: $PROJECT_ROOT/openspec/changes/archive/
|
||||
- Source code: $PROJECT_ROOT/src/
|
||||
- Tests: $PROJECT_ROOT/tests/
|
||||
- OpenAPI specs: $PROJECT_ROOT/docs/openapi/
|
||||
- V&V ledger: $PROJECT_ROOT/openspec/vv_audit/
|
||||
|
||||
Do NOT modify any source files. You are an auditor, not a developer.
|
||||
EOF
|
||||
|
||||
echo " Workspace ready: $VALIDATOR_WORKSPACE"
|
||||
echo ""
|
||||
echo " Launching V&V Architect..."
|
||||
echo ""
|
||||
|
||||
# Launch Claude Code as the independent Validator
|
||||
# --system-prompt-file injects VALIDATOR.md as the system prompt,
|
||||
# overriding default behavior and establishing the auditor identity.
|
||||
cd "$VALIDATOR_WORKSPACE"
|
||||
exec claude --system-prompt-file "$VALIDATOR_SYSTEM_PROMPT"
|
||||
|
||||
@@ -383,7 +383,7 @@ export async function createApp(): Promise<Application> {
|
||||
// Phase 5 WS5: Scaffold Generator
|
||||
// ────────────────────────────────────────────────────────────────
|
||||
const scaffoldService = new ScaffoldService();
|
||||
const scaffoldController = new ScaffoldController(scaffoldService, pool, auditService);
|
||||
const scaffoldController = new ScaffoldController(scaffoldService, agentRepo, credentialRepo, auditService);
|
||||
app.use(`${API_BASE}`, createScaffoldRouter(scaffoldController, authMiddleware));
|
||||
|
||||
// ────────────────────────────────────────────────────────────────
|
||||
|
||||
@@ -14,7 +14,6 @@
|
||||
*/
|
||||
|
||||
import { Request, Response } from 'express';
|
||||
import { Pool } from 'pg';
|
||||
|
||||
/** Timeout applied to each individual health-check probe (ms). */
|
||||
const PROBE_TIMEOUT_MS = 3000;
|
||||
@@ -39,12 +38,18 @@ export interface DetailedHealthResponse {
|
||||
services: Record<string, ServiceHealthResult>;
|
||||
}
|
||||
|
||||
/** Minimal interface for a PostgreSQL liveness probe. */
|
||||
export interface DbProbe {
|
||||
/** Checks DB liveness. Resolves when connected, rejects on failure. */
|
||||
checkLiveness(): Promise<void>;
|
||||
}
|
||||
|
||||
/**
|
||||
* Dependencies injected into the controller.
|
||||
* All fields are optional — services are only probed when their client is provided.
|
||||
*/
|
||||
export interface HealthDetailedDeps {
|
||||
pool: Pool;
|
||||
dbProbe: DbProbe;
|
||||
/** Optional Vault URL — when provided, the controller probes Vault's /v1/sys/health. */
|
||||
vaultAddr?: string;
|
||||
/** Optional OPA URL — when provided, the controller probes OPA's /health. */
|
||||
@@ -90,13 +95,13 @@ async function runProbe(
|
||||
* optional-service clients. The `handle` method is an Express route handler.
|
||||
*/
|
||||
export class HealthDetailedController {
|
||||
private readonly pool: Pool;
|
||||
private readonly dbProbe: DbProbe;
|
||||
private readonly vaultAddr: string | undefined;
|
||||
private readonly opaUrl: string | undefined;
|
||||
private readonly redisClient: { ping(): Promise<string> } | null;
|
||||
|
||||
constructor(deps: HealthDetailedDeps) {
|
||||
this.pool = deps.pool;
|
||||
this.dbProbe = deps.dbProbe;
|
||||
this.vaultAddr = deps.vaultAddr;
|
||||
this.opaUrl = deps.opaUrl;
|
||||
this.redisClient = deps.redisClient ?? null;
|
||||
@@ -118,12 +123,7 @@ export class HealthDetailedController {
|
||||
// ── PostgreSQL probe ────────────────────────────────────────────────────
|
||||
services['postgres'] = await runProbe(async () => {
|
||||
const start = Date.now();
|
||||
const client = await this.pool.connect();
|
||||
try {
|
||||
await client.query('SELECT 1');
|
||||
} finally {
|
||||
client.release();
|
||||
}
|
||||
await this.dbProbe.checkLiveness();
|
||||
return Date.now() - start;
|
||||
});
|
||||
|
||||
|
||||
@@ -4,7 +4,8 @@
|
||||
*/
|
||||
|
||||
import { Request, Response, NextFunction } from 'express';
|
||||
import { Pool } from 'pg';
|
||||
import { AgentRepository } from '../repositories/AgentRepository.js';
|
||||
import { CredentialRepository } from '../repositories/CredentialRepository.js';
|
||||
import { AuditService } from '../services/AuditService.js';
|
||||
import { ScaffoldService, SCAFFOLD_LANGUAGES } from '../services/ScaffoldService.js';
|
||||
import { ScaffoldLanguage } from '../types/scaffold.js';
|
||||
@@ -17,12 +18,14 @@ import { AgentNotFoundError, AuthorizationError, ValidationError } from '../util
|
||||
export class ScaffoldController {
|
||||
/**
|
||||
* @param scaffoldService - The scaffold generation service.
|
||||
* @param pool - PostgreSQL connection pool for agent credential lookup.
|
||||
* @param agentRepo - Agent repository for agent lookup.
|
||||
* @param credentialRepo - Credential repository for active credential lookup.
|
||||
* @param auditService - Audit log service.
|
||||
*/
|
||||
constructor(
|
||||
private readonly scaffoldService: ScaffoldService,
|
||||
private readonly pool: Pool,
|
||||
private readonly agentRepo: AgentRepository,
|
||||
private readonly credentialRepo: CredentialRepository,
|
||||
private readonly auditService: AuditService,
|
||||
) {}
|
||||
|
||||
@@ -53,38 +56,25 @@ export class ScaffoldController {
|
||||
const tenantId = req.user.organization_id ?? 'org_system';
|
||||
|
||||
// Fetch agent and verify it belongs to the authenticated tenant
|
||||
const agentResult = await this.pool.query<{
|
||||
agent_id: string;
|
||||
email: string;
|
||||
organization_id: string;
|
||||
}>(
|
||||
`SELECT agent_id, email, organization_id FROM agents WHERE agent_id = $1`,
|
||||
[agentId],
|
||||
);
|
||||
const agent = await this.agentRepo.findById(agentId);
|
||||
|
||||
if (agentResult.rows.length === 0) {
|
||||
if (agent === null) {
|
||||
throw new AgentNotFoundError(agentId);
|
||||
}
|
||||
|
||||
const agentRow = agentResult.rows[0];
|
||||
if (agentRow.organization_id !== tenantId) {
|
||||
if (agent.organizationId !== tenantId) {
|
||||
throw new AuthorizationError('You do not own this agent.');
|
||||
}
|
||||
|
||||
// Fetch the agent's active credential client_id
|
||||
const credResult = await this.pool.query<{ client_id: string }>(
|
||||
`SELECT client_id FROM credentials WHERE agent_id = $1 AND status = 'active' ORDER BY created_at DESC LIMIT 1`,
|
||||
[agentId],
|
||||
);
|
||||
|
||||
const clientId =
|
||||
credResult.rows.length > 0 ? credResult.rows[0].client_id : agentRow.agent_id;
|
||||
const activeClientId = await this.credentialRepo.findActiveClientId(agentId);
|
||||
const clientId = activeClientId ?? agentId;
|
||||
|
||||
const apiUrl = process.env['API_URL'] ?? process.env['NEXT_PUBLIC_API_URL'] ?? 'https://api.sentryagent.ai';
|
||||
|
||||
const { stream, filename } = await this.scaffoldService.generateScaffold({
|
||||
agentId,
|
||||
agentName: agentRow.email.split('@')[0] ?? agentId,
|
||||
agentName: agent.email.split('@')[0] ?? agentId,
|
||||
clientId,
|
||||
language,
|
||||
apiUrl,
|
||||
|
||||
@@ -79,23 +79,23 @@ export function getPool(): Pool {
|
||||
}
|
||||
});
|
||||
|
||||
// Wrap pool.query to record duration in Prometheus.
|
||||
// The pg Pool.query method is heavily overloaded — the only safe approach
|
||||
// without TypeScript errors is a typed-any wrapper on the shim itself.
|
||||
// We capture originalQuery as `(...args: any[]) => Promise<any>` to satisfy
|
||||
// TypeScript's spread-into-rest constraint; this is the one sanctioned use of
|
||||
// `any` in this file.
|
||||
// eslint-disable-next-line @typescript-eslint/no-explicit-any
|
||||
const originalQuery = pool.query.bind(pool) as (...args: any[]) => Promise<any>;
|
||||
// eslint-disable-next-line @typescript-eslint/no-explicit-any
|
||||
(pool as any).query = async (...args: any[]): Promise<any> => {
|
||||
// Wrap pool.query to record Prometheus query duration.
|
||||
// Uses unknown[] + Object.defineProperty to avoid `any` while preserving
|
||||
// the pool's typed interface for all callers (TypeScript still sees Pool['query']).
|
||||
const originalQuery = pool.query.bind(pool);
|
||||
Object.defineProperty(pool, 'query', {
|
||||
value: async (...args: unknown[]): Promise<unknown> => {
|
||||
const end = dbQueryDurationSeconds.startTimer({ operation: 'query' });
|
||||
try {
|
||||
return await originalQuery(...args);
|
||||
return await (originalQuery as (...a: unknown[]) => Promise<unknown>)(...args);
|
||||
} finally {
|
||||
end();
|
||||
}
|
||||
};
|
||||
},
|
||||
writable: true,
|
||||
configurable: true,
|
||||
enumerable: false,
|
||||
});
|
||||
}
|
||||
return pool;
|
||||
}
|
||||
|
||||
@@ -250,4 +250,18 @@ export class CredentialRepository {
|
||||
);
|
||||
return result.rowCount ?? 0;
|
||||
}
|
||||
|
||||
/**
|
||||
* Finds the client_id of the most recent active credential for an agent.
|
||||
*
|
||||
* @param agentId - The agent UUID.
|
||||
* @returns The client_id string, or null if no active credential exists.
|
||||
*/
|
||||
async findActiveClientId(agentId: string): Promise<string | null> {
|
||||
const result: QueryResult<{ client_id: string }> = await this.pool.query(
|
||||
`SELECT client_id FROM credentials WHERE agent_id = $1 AND status = 'active' ORDER BY created_at DESC LIMIT 1`,
|
||||
[agentId],
|
||||
);
|
||||
return result.rows.length > 0 ? (result.rows[0].client_id ?? null) : null;
|
||||
}
|
||||
}
|
||||
|
||||
@@ -10,7 +10,7 @@
|
||||
import { Router, Request, Response } from 'express';
|
||||
import { Pool } from 'pg';
|
||||
import { RedisClientType } from 'redis';
|
||||
import { HealthDetailedController } from '../controllers/HealthDetailedController.js';
|
||||
import { DbProbe, HealthDetailedController } from '../controllers/HealthDetailedController.js';
|
||||
|
||||
/** Response shape for GET /health */
|
||||
interface HealthResponse {
|
||||
@@ -33,9 +33,21 @@ interface HealthResponse {
|
||||
export function createHealthRouter(pool: Pool, redis: RedisClientType): Router {
|
||||
const router = Router();
|
||||
|
||||
// Create a minimal DbProbe adapter — keeps raw Pool out of the controller.
|
||||
const dbProbe: DbProbe = {
|
||||
async checkLiveness(): Promise<void> {
|
||||
const client = await pool.connect();
|
||||
try {
|
||||
await client.query('SELECT 1');
|
||||
} finally {
|
||||
client.release();
|
||||
}
|
||||
},
|
||||
};
|
||||
|
||||
// Instantiate the detailed health controller with optional service clients.
|
||||
const detailedController = new HealthDetailedController({
|
||||
pool,
|
||||
dbProbe,
|
||||
redisClient: redis,
|
||||
vaultAddr: process.env['VAULT_ADDR'] ?? undefined,
|
||||
opaUrl: process.env['OPA_URL'] ?? undefined,
|
||||
|
||||
148
tests/integration/analytics.test.ts
Normal file
148
tests/integration/analytics.test.ts
Normal file
@@ -0,0 +1,148 @@
|
||||
/**
|
||||
* Integration tests for Analytics endpoints.
|
||||
* Uses a real Postgres test DB and Redis test instance.
|
||||
*
|
||||
* Routes covered:
|
||||
* GET /api/v1/analytics/tokens — daily token issuance trend
|
||||
* GET /api/v1/analytics/agents/activity — agent activity heatmap
|
||||
* GET /api/v1/analytics/agents — per-agent usage summary
|
||||
*/
|
||||
|
||||
import crypto from 'crypto';
|
||||
import request from 'supertest';
|
||||
import { Application } from 'express';
|
||||
import { v4 as uuidv4 } from 'uuid';
|
||||
import { Pool } from 'pg';
|
||||
|
||||
const { privateKey, publicKey } = crypto.generateKeyPairSync('rsa', {
|
||||
modulusLength: 2048,
|
||||
publicKeyEncoding: { type: 'spki', format: 'pem' },
|
||||
privateKeyEncoding: { type: 'pkcs8', format: 'pem' },
|
||||
});
|
||||
|
||||
process.env['DATABASE_URL'] =
|
||||
process.env['TEST_DATABASE_URL'] ??
|
||||
'postgresql://sentryagent:sentryagent@localhost:5432/sentryagent_idp_test';
|
||||
process.env['REDIS_URL'] = process.env['TEST_REDIS_URL'] ?? 'redis://localhost:6379/1';
|
||||
process.env['JWT_PRIVATE_KEY'] = privateKey;
|
||||
process.env['JWT_PUBLIC_KEY'] = publicKey;
|
||||
process.env['NODE_ENV'] = 'test';
|
||||
process.env['DEFAULT_ORG_ID'] = 'org_system';
|
||||
process.env['ANALYTICS_ENABLED'] = 'true';
|
||||
|
||||
import { createApp } from '../../src/app';
|
||||
import { signToken } from '../../src/utils/jwt';
|
||||
import { closePool } from '../../src/db/pool';
|
||||
import { closeRedisClient } from '../../src/cache/redis';
|
||||
|
||||
const ORG_ID = uuidv4();
|
||||
const AGENT_ID = uuidv4();
|
||||
const SCOPE = 'analytics:read';
|
||||
|
||||
function makeToken(sub: string = AGENT_ID, scope: string = SCOPE, orgId: string = ORG_ID): string {
|
||||
return signToken({ sub, client_id: sub, scope, organization_id: orgId, jti: uuidv4() }, privateKey);
|
||||
}
|
||||
|
||||
describe('Analytics Endpoints Integration Tests', () => {
|
||||
let app: Application;
|
||||
let pool: Pool;
|
||||
|
||||
beforeAll(async () => {
|
||||
app = await createApp();
|
||||
pool = new Pool({ connectionString: process.env['DATABASE_URL'] });
|
||||
|
||||
await pool.query(`
|
||||
CREATE TABLE IF NOT EXISTS organizations (
|
||||
organization_id VARCHAR(40) PRIMARY KEY,
|
||||
name VARCHAR(100) NOT NULL,
|
||||
plan VARCHAR(20) NOT NULL DEFAULT 'free',
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||||
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
|
||||
)
|
||||
`);
|
||||
|
||||
await pool.query(`
|
||||
CREATE TABLE IF NOT EXISTS analytics_events (
|
||||
id BIGSERIAL PRIMARY KEY,
|
||||
tenant_id VARCHAR(40) NOT NULL,
|
||||
date DATE NOT NULL,
|
||||
metric_type VARCHAR(50) NOT NULL,
|
||||
count INTEGER NOT NULL DEFAULT 1,
|
||||
UNIQUE(tenant_id, date, metric_type)
|
||||
)
|
||||
`);
|
||||
|
||||
await pool.query(
|
||||
`INSERT INTO organizations (organization_id, name) VALUES ($1, $2) ON CONFLICT DO NOTHING`,
|
||||
[ORG_ID, 'Test Analytics Org'],
|
||||
);
|
||||
});
|
||||
|
||||
afterAll(async () => {
|
||||
await pool.query(`DELETE FROM analytics_events WHERE tenant_id = $1`, [ORG_ID]);
|
||||
await pool.query(`DELETE FROM organizations WHERE organization_id = $1`, [ORG_ID]);
|
||||
await pool.end();
|
||||
await closePool();
|
||||
await closeRedisClient();
|
||||
});
|
||||
|
||||
// ─── GET /analytics/tokens ──────────────────────────────────────────────────
|
||||
|
||||
describe('GET /api/v1/analytics/tokens', () => {
|
||||
it('should return 200 with token trend data', async () => {
|
||||
const res = await request(app)
|
||||
.get('/api/v1/analytics/tokens')
|
||||
.set('Authorization', `Bearer ${makeToken()}`);
|
||||
|
||||
expect(res.status).toBe(200);
|
||||
expect(Array.isArray(res.body)).toBe(true);
|
||||
});
|
||||
|
||||
it('should return 401 when no token provided', async () => {
|
||||
const res = await request(app).get('/api/v1/analytics/tokens');
|
||||
expect(res.status).toBe(401);
|
||||
});
|
||||
|
||||
it('should accept a ?days= query parameter', async () => {
|
||||
const res = await request(app)
|
||||
.get('/api/v1/analytics/tokens?days=7')
|
||||
.set('Authorization', `Bearer ${makeToken()}`);
|
||||
|
||||
expect(res.status).toBe(200);
|
||||
});
|
||||
});
|
||||
|
||||
// ─── GET /analytics/agents/activity ─────────────────────────────────────────
|
||||
|
||||
describe('GET /api/v1/analytics/agents/activity', () => {
|
||||
it('should return 200 with activity data', async () => {
|
||||
const res = await request(app)
|
||||
.get('/api/v1/analytics/agents/activity')
|
||||
.set('Authorization', `Bearer ${makeToken()}`);
|
||||
|
||||
expect(res.status).toBe(200);
|
||||
});
|
||||
|
||||
it('should return 401 when no token provided', async () => {
|
||||
const res = await request(app).get('/api/v1/analytics/agents/activity');
|
||||
expect(res.status).toBe(401);
|
||||
});
|
||||
});
|
||||
|
||||
// ─── GET /analytics/agents ───────────────────────────────────────────────────
|
||||
|
||||
describe('GET /api/v1/analytics/agents', () => {
|
||||
it('should return 200 with agent usage summary', async () => {
|
||||
const res = await request(app)
|
||||
.get('/api/v1/analytics/agents')
|
||||
.set('Authorization', `Bearer ${makeToken()}`);
|
||||
|
||||
expect(res.status).toBe(200);
|
||||
});
|
||||
|
||||
it('should return 401 when no token provided', async () => {
|
||||
const res = await request(app).get('/api/v1/analytics/agents');
|
||||
expect(res.status).toBe(401);
|
||||
});
|
||||
});
|
||||
});
|
||||
141
tests/integration/billing.test.ts
Normal file
141
tests/integration/billing.test.ts
Normal file
@@ -0,0 +1,141 @@
|
||||
/**
|
||||
* Integration tests for Billing endpoints.
|
||||
* Uses a real Postgres test DB and Redis test instance.
|
||||
*
|
||||
* Routes covered:
|
||||
* POST /api/v1/billing/checkout — create Stripe Checkout Session (authenticated)
|
||||
* POST /api/v1/billing/webhook — Stripe webhook handler (unauthenticated, raw body)
|
||||
* GET /api/v1/billing/usage — today's usage summary (authenticated)
|
||||
*/
|
||||
|
||||
import crypto from 'crypto';
|
||||
import request from 'supertest';
|
||||
import { Application } from 'express';
|
||||
import { v4 as uuidv4 } from 'uuid';
|
||||
import { Pool } from 'pg';
|
||||
|
||||
const { privateKey, publicKey } = crypto.generateKeyPairSync('rsa', {
|
||||
modulusLength: 2048,
|
||||
publicKeyEncoding: { type: 'spki', format: 'pem' },
|
||||
privateKeyEncoding: { type: 'pkcs8', format: 'pem' },
|
||||
});
|
||||
|
||||
process.env['DATABASE_URL'] =
|
||||
process.env['TEST_DATABASE_URL'] ??
|
||||
'postgresql://sentryagent:sentryagent@localhost:5432/sentryagent_idp_test';
|
||||
process.env['REDIS_URL'] = process.env['TEST_REDIS_URL'] ?? 'redis://localhost:6379/1';
|
||||
process.env['JWT_PRIVATE_KEY'] = privateKey;
|
||||
process.env['JWT_PUBLIC_KEY'] = publicKey;
|
||||
process.env['NODE_ENV'] = 'test';
|
||||
process.env['DEFAULT_ORG_ID'] = 'org_system';
|
||||
// Use a test Stripe key placeholder — actual Stripe calls will not be made in unit context
|
||||
process.env['STRIPE_SECRET_KEY'] = 'sk_test_placeholder';
|
||||
process.env['STRIPE_WEBHOOK_SECRET'] = 'whsec_test_placeholder';
|
||||
|
||||
import { createApp } from '../../src/app';
|
||||
import { signToken } from '../../src/utils/jwt';
|
||||
import { closePool } from '../../src/db/pool';
|
||||
import { closeRedisClient } from '../../src/cache/redis';
|
||||
|
||||
const ORG_ID = uuidv4();
|
||||
const AGENT_ID = uuidv4();
|
||||
|
||||
function makeToken(sub: string = AGENT_ID, scope = 'billing:manage', orgId: string = ORG_ID): string {
|
||||
return signToken({ sub, client_id: sub, scope, organization_id: orgId, jti: uuidv4() }, privateKey);
|
||||
}
|
||||
|
||||
describe('Billing Endpoints Integration Tests', () => {
|
||||
let app: Application;
|
||||
let pool: Pool;
|
||||
|
||||
beforeAll(async () => {
|
||||
app = await createApp();
|
||||
pool = new Pool({ connectionString: process.env['DATABASE_URL'] });
|
||||
|
||||
await pool.query(`
|
||||
CREATE TABLE IF NOT EXISTS organizations (
|
||||
organization_id VARCHAR(40) PRIMARY KEY,
|
||||
name VARCHAR(100) NOT NULL,
|
||||
plan VARCHAR(20) NOT NULL DEFAULT 'free',
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||||
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
|
||||
)
|
||||
`);
|
||||
|
||||
await pool.query(`
|
||||
CREATE TABLE IF NOT EXISTS usage_events (
|
||||
id BIGSERIAL PRIMARY KEY,
|
||||
tenant_id VARCHAR(40) NOT NULL,
|
||||
date DATE NOT NULL,
|
||||
metric_type VARCHAR(50) NOT NULL,
|
||||
count INTEGER NOT NULL DEFAULT 1
|
||||
)
|
||||
`);
|
||||
|
||||
await pool.query(
|
||||
`INSERT INTO organizations (organization_id, name) VALUES ($1, $2) ON CONFLICT DO NOTHING`,
|
||||
[ORG_ID, 'Test Billing Org'],
|
||||
);
|
||||
});
|
||||
|
||||
afterAll(async () => {
|
||||
await pool.query(`DELETE FROM usage_events WHERE tenant_id = $1`, [ORG_ID]);
|
||||
await pool.query(`DELETE FROM organizations WHERE organization_id = $1`, [ORG_ID]);
|
||||
await pool.end();
|
||||
await closePool();
|
||||
await closeRedisClient();
|
||||
});
|
||||
|
||||
// ─── GET /billing/usage ──────────────────────────────────────────────────────
|
||||
|
||||
describe('GET /api/v1/billing/usage', () => {
|
||||
it('should return 200 with usage summary for authenticated user', async () => {
|
||||
const res = await request(app)
|
||||
.get('/api/v1/billing/usage')
|
||||
.set('Authorization', `Bearer ${makeToken()}`);
|
||||
|
||||
expect(res.status).toBe(200);
|
||||
expect(res.body).toHaveProperty('apiCalls');
|
||||
});
|
||||
|
||||
it('should return 401 when no token provided', async () => {
|
||||
const res = await request(app).get('/api/v1/billing/usage');
|
||||
expect(res.status).toBe(401);
|
||||
});
|
||||
});
|
||||
|
||||
// ─── POST /billing/checkout ──────────────────────────────────────────────────
|
||||
|
||||
describe('POST /api/v1/billing/checkout', () => {
|
||||
it('should return 401 when no token provided', async () => {
|
||||
const res = await request(app)
|
||||
.post('/api/v1/billing/checkout')
|
||||
.send({ targetTier: 'pro' });
|
||||
|
||||
expect(res.status).toBe(401);
|
||||
});
|
||||
|
||||
it('should return 422 when targetTier is missing', async () => {
|
||||
const res = await request(app)
|
||||
.post('/api/v1/billing/checkout')
|
||||
.set('Authorization', `Bearer ${makeToken()}`)
|
||||
.send({});
|
||||
|
||||
expect([400, 422]).toContain(res.status);
|
||||
});
|
||||
});
|
||||
|
||||
// ─── POST /billing/webhook ───────────────────────────────────────────────────
|
||||
|
||||
describe('POST /api/v1/billing/webhook', () => {
|
||||
it('should return 400 when Stripe-Signature header is missing', async () => {
|
||||
const res = await request(app)
|
||||
.post('/api/v1/billing/webhook')
|
||||
.set('Content-Type', 'application/json')
|
||||
.send(JSON.stringify({ type: 'checkout.session.completed' }));
|
||||
|
||||
// Stripe webhook verification will fail without the signature
|
||||
expect([400, 401, 403]).toContain(res.status);
|
||||
});
|
||||
});
|
||||
});
|
||||
159
tests/integration/marketplace.test.ts
Normal file
159
tests/integration/marketplace.test.ts
Normal file
@@ -0,0 +1,159 @@
|
||||
/**
|
||||
* Integration tests for Marketplace endpoints.
|
||||
* Uses a real Postgres test DB and Redis test instance.
|
||||
*
|
||||
* Routes covered:
|
||||
* GET /api/v1/marketplace — list public agents
|
||||
* GET /api/v1/marketplace/:id — get a specific public agent
|
||||
*
|
||||
* Marketplace endpoints are unauthenticated (public listing).
|
||||
*/
|
||||
|
||||
import crypto from 'crypto';
|
||||
import request from 'supertest';
|
||||
import { Application } from 'express';
|
||||
import { v4 as uuidv4 } from 'uuid';
|
||||
import { Pool } from 'pg';
|
||||
|
||||
const { privateKey, publicKey } = crypto.generateKeyPairSync('rsa', {
|
||||
modulusLength: 2048,
|
||||
publicKeyEncoding: { type: 'spki', format: 'pem' },
|
||||
privateKeyEncoding: { type: 'pkcs8', format: 'pem' },
|
||||
});
|
||||
|
||||
process.env['DATABASE_URL'] =
|
||||
process.env['TEST_DATABASE_URL'] ??
|
||||
'postgresql://sentryagent:sentryagent@localhost:5432/sentryagent_idp_test';
|
||||
process.env['REDIS_URL'] = process.env['TEST_REDIS_URL'] ?? 'redis://localhost:6379/1';
|
||||
process.env['JWT_PRIVATE_KEY'] = privateKey;
|
||||
process.env['JWT_PUBLIC_KEY'] = publicKey;
|
||||
process.env['NODE_ENV'] = 'test';
|
||||
process.env['DEFAULT_ORG_ID'] = 'org_system';
|
||||
|
||||
import { createApp } from '../../src/app';
|
||||
import { closePool } from '../../src/db/pool';
|
||||
import { closeRedisClient } from '../../src/cache/redis';
|
||||
|
||||
const ORG_ID = uuidv4();
|
||||
const PUBLIC_AGENT_ID = uuidv4();
|
||||
const PRIVATE_AGENT_ID = uuidv4();
|
||||
|
||||
describe('Marketplace Endpoints Integration Tests', () => {
|
||||
let app: Application;
|
||||
let pool: Pool;
|
||||
|
||||
beforeAll(async () => {
|
||||
app = await createApp();
|
||||
pool = new Pool({ connectionString: process.env['DATABASE_URL'] });
|
||||
|
||||
await pool.query(`
|
||||
CREATE TABLE IF NOT EXISTS organizations (
|
||||
organization_id VARCHAR(40) PRIMARY KEY,
|
||||
name VARCHAR(100) NOT NULL,
|
||||
plan VARCHAR(20) NOT NULL DEFAULT 'free',
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||||
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
|
||||
)
|
||||
`);
|
||||
|
||||
await pool.query(`
|
||||
CREATE TABLE IF NOT EXISTS agents (
|
||||
agent_id VARCHAR(40) PRIMARY KEY,
|
||||
organization_id VARCHAR(40) NOT NULL,
|
||||
email VARCHAR(255) NOT NULL UNIQUE,
|
||||
agent_type VARCHAR(50) NOT NULL,
|
||||
version VARCHAR(20) NOT NULL,
|
||||
capabilities TEXT[] NOT NULL DEFAULT '{}',
|
||||
owner VARCHAR(100) NOT NULL,
|
||||
deployment_env VARCHAR(50) NOT NULL,
|
||||
status VARCHAR(20) NOT NULL DEFAULT 'active',
|
||||
is_public BOOLEAN NOT NULL DEFAULT false,
|
||||
did TEXT,
|
||||
did_created_at TIMESTAMPTZ,
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||||
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
|
||||
)
|
||||
`);
|
||||
|
||||
await pool.query(
|
||||
`INSERT INTO organizations (organization_id, name) VALUES ($1, $2) ON CONFLICT DO NOTHING`,
|
||||
[ORG_ID, 'Test Marketplace Org'],
|
||||
);
|
||||
|
||||
// Insert a public agent
|
||||
await pool.query(
|
||||
`INSERT INTO agents
|
||||
(agent_id, organization_id, email, agent_type, version, capabilities, owner, deployment_env, status, is_public)
|
||||
VALUES ($1, $2, $3, 'screener', 'v1.0.0', '{resume:read}', 'test-team', 'production', 'active', true)
|
||||
ON CONFLICT DO NOTHING`,
|
||||
[PUBLIC_AGENT_ID, ORG_ID, `public-${PUBLIC_AGENT_ID}@test.com`],
|
||||
);
|
||||
|
||||
// Insert a private agent
|
||||
await pool.query(
|
||||
`INSERT INTO agents
|
||||
(agent_id, organization_id, email, agent_type, version, capabilities, owner, deployment_env, status, is_public)
|
||||
VALUES ($1, $2, $3, 'screener', 'v1.0.0', '{resume:read}', 'test-team', 'production', 'active', false)
|
||||
ON CONFLICT DO NOTHING`,
|
||||
[PRIVATE_AGENT_ID, ORG_ID, `private-${PRIVATE_AGENT_ID}@test.com`],
|
||||
);
|
||||
});
|
||||
|
||||
afterAll(async () => {
|
||||
await pool.query(`DELETE FROM agents WHERE organization_id = $1`, [ORG_ID]);
|
||||
await pool.query(`DELETE FROM organizations WHERE organization_id = $1`, [ORG_ID]);
|
||||
await pool.end();
|
||||
await closePool();
|
||||
await closeRedisClient();
|
||||
});
|
||||
|
||||
// ─── GET /marketplace ────────────────────────────────────────────────────────
|
||||
|
||||
describe('GET /api/v1/marketplace', () => {
|
||||
it('should return 200 with a list of public agents', async () => {
|
||||
const res = await request(app).get('/api/v1/marketplace');
|
||||
|
||||
expect(res.status).toBe(200);
|
||||
const items: unknown[] = res.body.data ?? res.body;
|
||||
expect(Array.isArray(items)).toBe(true);
|
||||
});
|
||||
|
||||
it('should not expose private agents in the listing', async () => {
|
||||
const res = await request(app).get('/api/v1/marketplace');
|
||||
|
||||
expect(res.status).toBe(200);
|
||||
const items = (res.body.data ?? res.body) as Array<{ agentId: string }>;
|
||||
const privateIds = items.map((a) => a.agentId);
|
||||
expect(privateIds).not.toContain(PRIVATE_AGENT_ID);
|
||||
});
|
||||
|
||||
it('should support pagination via ?page= and ?limit=', async () => {
|
||||
const res = await request(app).get('/api/v1/marketplace?page=1&limit=5');
|
||||
|
||||
expect(res.status).toBe(200);
|
||||
});
|
||||
});
|
||||
|
||||
// ─── GET /marketplace/:id ────────────────────────────────────────────────────
|
||||
|
||||
describe('GET /api/v1/marketplace/:id', () => {
|
||||
it('should return 200 with the public agent card', async () => {
|
||||
const res = await request(app).get(`/api/v1/marketplace/${PUBLIC_AGENT_ID}`);
|
||||
|
||||
expect(res.status).toBe(200);
|
||||
expect(res.body.agentId).toBe(PUBLIC_AGENT_ID);
|
||||
});
|
||||
|
||||
it('should return 404 for a private agent', async () => {
|
||||
const res = await request(app).get(`/api/v1/marketplace/${PRIVATE_AGENT_ID}`);
|
||||
|
||||
expect(res.status).toBe(404);
|
||||
});
|
||||
|
||||
it('should return 404 for a non-existent agent', async () => {
|
||||
const res = await request(app).get(`/api/v1/marketplace/${uuidv4()}`);
|
||||
|
||||
expect(res.status).toBe(404);
|
||||
});
|
||||
});
|
||||
});
|
||||
132
tests/integration/oidc-token-exchange.test.ts
Normal file
132
tests/integration/oidc-token-exchange.test.ts
Normal file
@@ -0,0 +1,132 @@
|
||||
/**
|
||||
* Integration tests for OIDC Token Exchange endpoint.
|
||||
* Uses a real Postgres test DB and Redis test instance.
|
||||
*
|
||||
* Routes covered:
|
||||
* POST /api/v1/oidc/token — exchange a GitHub OIDC JWT for a SentryAgent.ai access token
|
||||
*
|
||||
* This is an unauthenticated endpoint — the GitHub OIDC JWT is the credential.
|
||||
* Trust-policy enforcement requires a matching oidc_trust_policies record.
|
||||
*/
|
||||
|
||||
import crypto from 'crypto';
|
||||
import request from 'supertest';
|
||||
import { Application } from 'express';
|
||||
import { v4 as uuidv4 } from 'uuid';
|
||||
import { Pool } from 'pg';
|
||||
|
||||
const { privateKey, publicKey } = crypto.generateKeyPairSync('rsa', {
|
||||
modulusLength: 2048,
|
||||
publicKeyEncoding: { type: 'spki', format: 'pem' },
|
||||
privateKeyEncoding: { type: 'pkcs8', format: 'pem' },
|
||||
});
|
||||
|
||||
process.env['DATABASE_URL'] =
|
||||
process.env['TEST_DATABASE_URL'] ??
|
||||
'postgresql://sentryagent:sentryagent@localhost:5432/sentryagent_idp_test';
|
||||
process.env['REDIS_URL'] = process.env['TEST_REDIS_URL'] ?? 'redis://localhost:6379/1';
|
||||
process.env['JWT_PRIVATE_KEY'] = privateKey;
|
||||
process.env['JWT_PUBLIC_KEY'] = publicKey;
|
||||
process.env['NODE_ENV'] = 'test';
|
||||
process.env['DEFAULT_ORG_ID'] = 'org_system';
|
||||
|
||||
import { createApp } from '../../src/app';
|
||||
import { closePool } from '../../src/db/pool';
|
||||
import { closeRedisClient } from '../../src/cache/redis';
|
||||
|
||||
describe('OIDC Token Exchange Endpoint Integration Tests', () => {
|
||||
let app: Application;
|
||||
let pool: Pool;
|
||||
|
||||
beforeAll(async () => {
|
||||
app = await createApp();
|
||||
pool = new Pool({ connectionString: process.env['DATABASE_URL'] });
|
||||
|
||||
await pool.query(`
|
||||
CREATE TABLE IF NOT EXISTS oidc_trust_policies (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
provider VARCHAR(20) NOT NULL,
|
||||
repository VARCHAR(255) NOT NULL,
|
||||
branch VARCHAR(100),
|
||||
agent_id VARCHAR(40) NOT NULL,
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||||
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
|
||||
)
|
||||
`);
|
||||
});
|
||||
|
||||
afterAll(async () => {
|
||||
await pool.end();
|
||||
await closePool();
|
||||
await closeRedisClient();
|
||||
});
|
||||
|
||||
// ─── POST /oidc/token ────────────────────────────────────────────────────────
|
||||
|
||||
describe('POST /api/v1/oidc/token', () => {
|
||||
it('should return 400 when request body is missing', async () => {
|
||||
const res = await request(app)
|
||||
.post('/api/v1/oidc/token')
|
||||
.send({});
|
||||
|
||||
expect([400, 422]).toContain(res.status);
|
||||
});
|
||||
|
||||
it('should return 400 when provider is missing', async () => {
|
||||
const res = await request(app)
|
||||
.post('/api/v1/oidc/token')
|
||||
.send({ token: 'fake-jwt', agentId: uuidv4() });
|
||||
|
||||
expect([400, 422]).toContain(res.status);
|
||||
});
|
||||
|
||||
it('should return 400 when token is missing', async () => {
|
||||
const res = await request(app)
|
||||
.post('/api/v1/oidc/token')
|
||||
.send({ provider: 'github', agentId: uuidv4() });
|
||||
|
||||
expect([400, 422]).toContain(res.status);
|
||||
});
|
||||
|
||||
it('should return 401 or 403 for an invalid GitHub OIDC token', async () => {
|
||||
// A malformed JWT will fail verification — the endpoint should reject it
|
||||
const res = await request(app)
|
||||
.post('/api/v1/oidc/token')
|
||||
.send({
|
||||
provider: 'github',
|
||||
token: 'eyJhbGciOiJSUzI1NiJ9.invalid.payload',
|
||||
agentId: uuidv4(),
|
||||
scope: 'agents:read',
|
||||
});
|
||||
|
||||
expect([400, 401, 403, 422]).toContain(res.status);
|
||||
});
|
||||
|
||||
it('should return 403 when no trust policy matches the repository', async () => {
|
||||
// Build a minimally valid JWT structure with github claims (but won't pass GitHub JWKS)
|
||||
// The endpoint will reject after trust-policy lookup fails
|
||||
const header = Buffer.from(JSON.stringify({ alg: 'RS256', typ: 'JWT' })).toString('base64url');
|
||||
const claims = {
|
||||
iss: 'https://token.actions.githubusercontent.com',
|
||||
sub: 'repo:nonexistent/repo:ref:refs/heads/main',
|
||||
repository: 'nonexistent/repo',
|
||||
ref: 'refs/heads/main',
|
||||
aud: 'sentryagent.ai',
|
||||
};
|
||||
const payload = Buffer.from(JSON.stringify(claims)).toString('base64url');
|
||||
const fakeJwt = `${header}.${payload}.fakesig`;
|
||||
|
||||
const res = await request(app)
|
||||
.post('/api/v1/oidc/token')
|
||||
.send({
|
||||
provider: 'github',
|
||||
token: fakeJwt,
|
||||
agentId: uuidv4(),
|
||||
scope: 'agents:read',
|
||||
});
|
||||
|
||||
// Either 401 (invalid JWT signature) or 403 (trust policy violation)
|
||||
expect([400, 401, 403]).toContain(res.status);
|
||||
});
|
||||
});
|
||||
});
|
||||
207
tests/integration/oidc-trust-policies.test.ts
Normal file
207
tests/integration/oidc-trust-policies.test.ts
Normal file
@@ -0,0 +1,207 @@
|
||||
/**
|
||||
* Integration tests for OIDC Trust Policy endpoints.
|
||||
* Uses a real Postgres test DB and Redis test instance.
|
||||
*
|
||||
* Routes covered:
|
||||
* POST /api/v1/oidc/trust-policies — create a trust policy
|
||||
* GET /api/v1/oidc/trust-policies/:agentId — list trust policies for an agent
|
||||
* DELETE /api/v1/oidc/trust-policies/:id — delete a trust policy
|
||||
*/
|
||||
|
||||
import crypto from 'crypto';
|
||||
import request from 'supertest';
|
||||
import { Application } from 'express';
|
||||
import { v4 as uuidv4 } from 'uuid';
|
||||
import { Pool } from 'pg';
|
||||
|
||||
const { privateKey, publicKey } = crypto.generateKeyPairSync('rsa', {
|
||||
modulusLength: 2048,
|
||||
publicKeyEncoding: { type: 'spki', format: 'pem' },
|
||||
privateKeyEncoding: { type: 'pkcs8', format: 'pem' },
|
||||
});
|
||||
|
||||
process.env['DATABASE_URL'] =
|
||||
process.env['TEST_DATABASE_URL'] ??
|
||||
'postgresql://sentryagent:sentryagent@localhost:5432/sentryagent_idp_test';
|
||||
process.env['REDIS_URL'] = process.env['TEST_REDIS_URL'] ?? 'redis://localhost:6379/1';
|
||||
process.env['JWT_PRIVATE_KEY'] = privateKey;
|
||||
process.env['JWT_PUBLIC_KEY'] = publicKey;
|
||||
process.env['NODE_ENV'] = 'test';
|
||||
process.env['DEFAULT_ORG_ID'] = 'org_system';
|
||||
|
||||
import { createApp } from '../../src/app';
|
||||
import { signToken } from '../../src/utils/jwt';
|
||||
import { closePool } from '../../src/db/pool';
|
||||
import { closeRedisClient } from '../../src/cache/redis';
|
||||
|
||||
const ORG_ID = uuidv4();
|
||||
const AGENT_ID = uuidv4();
|
||||
const SCOPE = 'agents:write';
|
||||
|
||||
function makeToken(sub: string = AGENT_ID, scope: string = SCOPE, orgId: string = ORG_ID): string {
|
||||
return signToken({ sub, client_id: sub, scope, organization_id: orgId, jti: uuidv4() }, privateKey);
|
||||
}
|
||||
|
||||
describe('OIDC Trust Policy Endpoints Integration Tests', () => {
|
||||
let app: Application;
|
||||
let pool: Pool;
|
||||
let createdPolicyId: string;
|
||||
|
||||
beforeAll(async () => {
|
||||
app = await createApp();
|
||||
pool = new Pool({ connectionString: process.env['DATABASE_URL'] });
|
||||
|
||||
await pool.query(`
|
||||
CREATE TABLE IF NOT EXISTS organizations (
|
||||
organization_id VARCHAR(40) PRIMARY KEY,
|
||||
name VARCHAR(100) NOT NULL,
|
||||
plan VARCHAR(20) NOT NULL DEFAULT 'free',
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||||
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
|
||||
)
|
||||
`);
|
||||
|
||||
await pool.query(`
|
||||
CREATE TABLE IF NOT EXISTS agents (
|
||||
agent_id VARCHAR(40) PRIMARY KEY,
|
||||
organization_id VARCHAR(40) NOT NULL,
|
||||
email VARCHAR(255) NOT NULL UNIQUE,
|
||||
agent_type VARCHAR(50) NOT NULL,
|
||||
version VARCHAR(20) NOT NULL,
|
||||
capabilities TEXT[] NOT NULL DEFAULT '{}',
|
||||
owner VARCHAR(100) NOT NULL,
|
||||
deployment_env VARCHAR(50) NOT NULL,
|
||||
status VARCHAR(20) NOT NULL DEFAULT 'active',
|
||||
is_public BOOLEAN NOT NULL DEFAULT false,
|
||||
did TEXT,
|
||||
did_created_at TIMESTAMPTZ,
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||||
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
|
||||
)
|
||||
`);
|
||||
|
||||
await pool.query(`
|
||||
CREATE TABLE IF NOT EXISTS oidc_trust_policies (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
provider VARCHAR(20) NOT NULL,
|
||||
repository VARCHAR(255) NOT NULL,
|
||||
branch VARCHAR(100),
|
||||
agent_id VARCHAR(40) NOT NULL,
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||||
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
|
||||
)
|
||||
`);
|
||||
|
||||
await pool.query(
|
||||
`INSERT INTO organizations (organization_id, name) VALUES ($1, $2) ON CONFLICT DO NOTHING`,
|
||||
[ORG_ID, 'Test OIDC Org'],
|
||||
);
|
||||
|
||||
await pool.query(
|
||||
`INSERT INTO agents
|
||||
(agent_id, organization_id, email, agent_type, version, capabilities, owner, deployment_env)
|
||||
VALUES ($1, $2, $3, 'ci-runner', 'v1.0.0', '{}', 'ci-team', 'production')
|
||||
ON CONFLICT DO NOTHING`,
|
||||
[AGENT_ID, ORG_ID, `oidc-agent-${AGENT_ID}@test.com`],
|
||||
);
|
||||
});
|
||||
|
||||
afterAll(async () => {
|
||||
await pool.query(`DELETE FROM oidc_trust_policies WHERE agent_id = $1`, [AGENT_ID]);
|
||||
await pool.query(`DELETE FROM agents WHERE agent_id = $1`, [AGENT_ID]);
|
||||
await pool.query(`DELETE FROM organizations WHERE organization_id = $1`, [ORG_ID]);
|
||||
await pool.end();
|
||||
await closePool();
|
||||
await closeRedisClient();
|
||||
});
|
||||
|
||||
// ─── POST /oidc/trust-policies ───────────────────────────────────────────────
|
||||
|
||||
describe('POST /api/v1/oidc/trust-policies', () => {
|
||||
it('should create a trust policy and return 201', async () => {
|
||||
const res = await request(app)
|
||||
.post('/api/v1/oidc/trust-policies')
|
||||
.set('Authorization', `Bearer ${makeToken()}`)
|
||||
.send({
|
||||
provider: 'github',
|
||||
repository: 'acme/my-repo',
|
||||
branch: 'main',
|
||||
agentId: AGENT_ID,
|
||||
});
|
||||
|
||||
expect(res.status).toBe(201);
|
||||
expect(res.body).toHaveProperty('id');
|
||||
createdPolicyId = res.body.id as string;
|
||||
});
|
||||
|
||||
it('should return 401 when no token provided', async () => {
|
||||
const res = await request(app)
|
||||
.post('/api/v1/oidc/trust-policies')
|
||||
.send({ provider: 'github', repository: 'acme/repo', agentId: AGENT_ID });
|
||||
|
||||
expect(res.status).toBe(401);
|
||||
});
|
||||
|
||||
it('should return 422 for invalid provider', async () => {
|
||||
const res = await request(app)
|
||||
.post('/api/v1/oidc/trust-policies')
|
||||
.set('Authorization', `Bearer ${makeToken()}`)
|
||||
.send({ provider: 'gitlab', repository: 'acme/repo', agentId: AGENT_ID });
|
||||
|
||||
expect([400, 422]).toContain(res.status);
|
||||
});
|
||||
|
||||
it('should return 422 for malformed repository', async () => {
|
||||
const res = await request(app)
|
||||
.post('/api/v1/oidc/trust-policies')
|
||||
.set('Authorization', `Bearer ${makeToken()}`)
|
||||
.send({ provider: 'github', repository: 'no-slash', agentId: AGENT_ID });
|
||||
|
||||
expect([400, 422]).toContain(res.status);
|
||||
});
|
||||
});
|
||||
|
||||
// ─── GET /oidc/trust-policies/:agentId ──────────────────────────────────────
|
||||
|
||||
describe('GET /api/v1/oidc/trust-policies/:agentId', () => {
|
||||
it('should return 200 with list of trust policies', async () => {
|
||||
const res = await request(app)
|
||||
.get(`/api/v1/oidc/trust-policies/${AGENT_ID}`)
|
||||
.set('Authorization', `Bearer ${makeToken()}`);
|
||||
|
||||
expect(res.status).toBe(200);
|
||||
expect(Array.isArray(res.body)).toBe(true);
|
||||
});
|
||||
|
||||
it('should return 401 when no token provided', async () => {
|
||||
const res = await request(app).get(`/api/v1/oidc/trust-policies/${AGENT_ID}`);
|
||||
expect(res.status).toBe(401);
|
||||
});
|
||||
});
|
||||
|
||||
// ─── DELETE /oidc/trust-policies/:id ────────────────────────────────────────
|
||||
|
||||
describe('DELETE /api/v1/oidc/trust-policies/:id', () => {
|
||||
it('should return 204 when deleting an existing policy', async () => {
|
||||
if (!createdPolicyId) return;
|
||||
const res = await request(app)
|
||||
.delete(`/api/v1/oidc/trust-policies/${createdPolicyId}`)
|
||||
.set('Authorization', `Bearer ${makeToken()}`);
|
||||
|
||||
expect(res.status).toBe(204);
|
||||
});
|
||||
|
||||
it('should return 404 when policy does not exist', async () => {
|
||||
const res = await request(app)
|
||||
.delete(`/api/v1/oidc/trust-policies/${uuidv4()}`)
|
||||
.set('Authorization', `Bearer ${makeToken()}`);
|
||||
|
||||
expect(res.status).toBe(404);
|
||||
});
|
||||
|
||||
it('should return 401 when no token provided', async () => {
|
||||
const res = await request(app).delete(`/api/v1/oidc/trust-policies/${uuidv4()}`);
|
||||
expect(res.status).toBe(401);
|
||||
});
|
||||
});
|
||||
});
|
||||
137
tests/integration/tiers.test.ts
Normal file
137
tests/integration/tiers.test.ts
Normal file
@@ -0,0 +1,137 @@
|
||||
/**
|
||||
* Integration tests for Tier management endpoints.
|
||||
* Uses a real Postgres test DB and Redis test instance.
|
||||
*
|
||||
* Routes covered:
|
||||
* GET /api/v1/tiers/status — current tier, limits, and usage
|
||||
* POST /api/v1/tiers/upgrade — initiate Stripe checkout for tier upgrade
|
||||
*/
|
||||
|
||||
import crypto from 'crypto';
|
||||
import request from 'supertest';
|
||||
import { Application } from 'express';
|
||||
import { v4 as uuidv4 } from 'uuid';
|
||||
import { Pool } from 'pg';
|
||||
|
||||
const { privateKey, publicKey } = crypto.generateKeyPairSync('rsa', {
|
||||
modulusLength: 2048,
|
||||
publicKeyEncoding: { type: 'spki', format: 'pem' },
|
||||
privateKeyEncoding: { type: 'pkcs8', format: 'pem' },
|
||||
});
|
||||
|
||||
process.env['DATABASE_URL'] =
|
||||
process.env['TEST_DATABASE_URL'] ??
|
||||
'postgresql://sentryagent:sentryagent@localhost:5432/sentryagent_idp_test';
|
||||
process.env['REDIS_URL'] = process.env['TEST_REDIS_URL'] ?? 'redis://localhost:6379/1';
|
||||
process.env['JWT_PRIVATE_KEY'] = privateKey;
|
||||
process.env['JWT_PUBLIC_KEY'] = publicKey;
|
||||
process.env['NODE_ENV'] = 'test';
|
||||
process.env['DEFAULT_ORG_ID'] = 'org_system';
|
||||
process.env['TIER_ENFORCEMENT'] = 'false';
|
||||
|
||||
import { createApp } from '../../src/app';
|
||||
import { signToken } from '../../src/utils/jwt';
|
||||
import { closePool } from '../../src/db/pool';
|
||||
import { closeRedisClient } from '../../src/cache/redis';
|
||||
|
||||
const ORG_ID = uuidv4();
|
||||
const AGENT_ID = uuidv4();
|
||||
|
||||
function makeToken(sub: string = AGENT_ID, scope = 'agents:read', orgId: string = ORG_ID): string {
|
||||
return signToken({ sub, client_id: sub, scope, organization_id: orgId, jti: uuidv4() }, privateKey);
|
||||
}
|
||||
|
||||
describe('Tier Endpoints Integration Tests', () => {
|
||||
let app: Application;
|
||||
let pool: Pool;
|
||||
|
||||
beforeAll(async () => {
|
||||
app = await createApp();
|
||||
pool = new Pool({ connectionString: process.env['DATABASE_URL'] });
|
||||
|
||||
await pool.query(`
|
||||
CREATE TABLE IF NOT EXISTS organizations (
|
||||
organization_id VARCHAR(40) PRIMARY KEY,
|
||||
name VARCHAR(100) NOT NULL,
|
||||
plan VARCHAR(20) NOT NULL DEFAULT 'free',
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||||
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
|
||||
)
|
||||
`);
|
||||
|
||||
await pool.query(`
|
||||
CREATE TABLE IF NOT EXISTS tenant_tiers (
|
||||
tenant_id VARCHAR(40) PRIMARY KEY REFERENCES organizations(organization_id),
|
||||
tier VARCHAR(20) NOT NULL DEFAULT 'free',
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||||
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
|
||||
)
|
||||
`);
|
||||
|
||||
await pool.query(
|
||||
`INSERT INTO organizations (organization_id, name) VALUES ($1, $2) ON CONFLICT DO NOTHING`,
|
||||
[ORG_ID, 'Test Tier Org'],
|
||||
);
|
||||
|
||||
await pool.query(
|
||||
`INSERT INTO tenant_tiers (tenant_id, tier) VALUES ($1, 'free') ON CONFLICT DO NOTHING`,
|
||||
[ORG_ID],
|
||||
);
|
||||
});
|
||||
|
||||
afterAll(async () => {
|
||||
await pool.query(`DELETE FROM tenant_tiers WHERE tenant_id = $1`, [ORG_ID]);
|
||||
await pool.query(`DELETE FROM organizations WHERE organization_id = $1`, [ORG_ID]);
|
||||
await pool.end();
|
||||
await closePool();
|
||||
await closeRedisClient();
|
||||
});
|
||||
|
||||
// ─── GET /tiers/status ───────────────────────────────────────────────────────
|
||||
|
||||
describe('GET /api/v1/tiers/status', () => {
|
||||
it('should return 200 with tier status', async () => {
|
||||
const res = await request(app)
|
||||
.get('/api/v1/tiers/status')
|
||||
.set('Authorization', `Bearer ${makeToken()}`);
|
||||
|
||||
expect(res.status).toBe(200);
|
||||
expect(res.body).toHaveProperty('tier');
|
||||
});
|
||||
|
||||
it('should return 401 when no token provided', async () => {
|
||||
const res = await request(app).get('/api/v1/tiers/status');
|
||||
expect(res.status).toBe(401);
|
||||
});
|
||||
});
|
||||
|
||||
// ─── POST /tiers/upgrade ─────────────────────────────────────────────────────
|
||||
|
||||
describe('POST /api/v1/tiers/upgrade', () => {
|
||||
it('should return 401 when no token provided', async () => {
|
||||
const res = await request(app)
|
||||
.post('/api/v1/tiers/upgrade')
|
||||
.send({ targetTier: 'pro' });
|
||||
|
||||
expect(res.status).toBe(401);
|
||||
});
|
||||
|
||||
it('should return 422 when targetTier is missing', async () => {
|
||||
const res = await request(app)
|
||||
.post('/api/v1/tiers/upgrade')
|
||||
.set('Authorization', `Bearer ${makeToken()}`)
|
||||
.send({});
|
||||
|
||||
expect([400, 422]).toContain(res.status);
|
||||
});
|
||||
|
||||
it('should return 422 when targetTier is invalid', async () => {
|
||||
const res = await request(app)
|
||||
.post('/api/v1/tiers/upgrade')
|
||||
.set('Authorization', `Bearer ${makeToken()}`)
|
||||
.send({ targetTier: 'platinum' });
|
||||
|
||||
expect([400, 422]).toContain(res.status);
|
||||
});
|
||||
});
|
||||
});
|
||||
208
tests/integration/webhooks.test.ts
Normal file
208
tests/integration/webhooks.test.ts
Normal file
@@ -0,0 +1,208 @@
|
||||
/**
|
||||
* Integration tests for Webhook endpoints.
|
||||
* Uses a real Postgres test DB and Redis test instance.
|
||||
*
|
||||
* Routes covered:
|
||||
* POST /api/v1/webhooks — create a webhook subscription
|
||||
* GET /api/v1/webhooks — list webhook subscriptions for org
|
||||
* GET /api/v1/webhooks/:id — get a webhook subscription by ID
|
||||
* PATCH /api/v1/webhooks/:id — update a webhook subscription
|
||||
* DELETE /api/v1/webhooks/:id — delete a webhook subscription
|
||||
*/
|
||||
|
||||
import crypto from 'crypto';
|
||||
import request from 'supertest';
|
||||
import { Application } from 'express';
|
||||
import { v4 as uuidv4 } from 'uuid';
|
||||
import { Pool } from 'pg';
|
||||
|
||||
const { privateKey, publicKey } = crypto.generateKeyPairSync('rsa', {
|
||||
modulusLength: 2048,
|
||||
publicKeyEncoding: { type: 'spki', format: 'pem' },
|
||||
privateKeyEncoding: { type: 'pkcs8', format: 'pem' },
|
||||
});
|
||||
|
||||
process.env['DATABASE_URL'] =
|
||||
process.env['TEST_DATABASE_URL'] ??
|
||||
'postgresql://sentryagent:sentryagent@localhost:5432/sentryagent_idp_test';
|
||||
process.env['REDIS_URL'] = process.env['TEST_REDIS_URL'] ?? 'redis://localhost:6379/1';
|
||||
process.env['JWT_PRIVATE_KEY'] = privateKey;
|
||||
process.env['JWT_PUBLIC_KEY'] = publicKey;
|
||||
process.env['NODE_ENV'] = 'test';
|
||||
process.env['DEFAULT_ORG_ID'] = 'org_system';
|
||||
|
||||
import { createApp } from '../../src/app';
|
||||
import { signToken } from '../../src/utils/jwt';
|
||||
import { closePool } from '../../src/db/pool';
|
||||
import { closeRedisClient } from '../../src/cache/redis';
|
||||
|
||||
const ORG_ID = uuidv4();
|
||||
const AGENT_ID = uuidv4();
|
||||
const SCOPE = 'webhooks:manage';
|
||||
|
||||
function makeToken(sub: string = AGENT_ID, scope: string = SCOPE, orgId: string = ORG_ID): string {
|
||||
return signToken({ sub, client_id: sub, scope, organization_id: orgId, jti: uuidv4() }, privateKey);
|
||||
}
|
||||
|
||||
const VALID_SUBSCRIPTION = {
|
||||
url: 'https://example.com/webhook',
|
||||
events: ['agent.created', 'agent.updated'],
|
||||
secret: 'test-secret-123',
|
||||
};
|
||||
|
||||
describe('Webhook Endpoints Integration Tests', () => {
|
||||
let app: Application;
|
||||
let pool: Pool;
|
||||
let createdId: string;
|
||||
|
||||
beforeAll(async () => {
|
||||
app = await createApp();
|
||||
pool = new Pool({ connectionString: process.env['DATABASE_URL'] });
|
||||
|
||||
await pool.query(`
|
||||
CREATE TABLE IF NOT EXISTS organizations (
|
||||
organization_id VARCHAR(40) PRIMARY KEY,
|
||||
name VARCHAR(100) NOT NULL,
|
||||
plan VARCHAR(20) NOT NULL DEFAULT 'free',
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||||
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
|
||||
)
|
||||
`);
|
||||
|
||||
await pool.query(`
|
||||
CREATE TABLE IF NOT EXISTS webhook_subscriptions (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
organization_id VARCHAR(40) NOT NULL,
|
||||
url TEXT NOT NULL,
|
||||
events JSONB NOT NULL,
|
||||
secret_hash TEXT,
|
||||
active BOOLEAN NOT NULL DEFAULT true,
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||||
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
|
||||
)
|
||||
`);
|
||||
|
||||
await pool.query(
|
||||
`INSERT INTO organizations (organization_id, name) VALUES ($1, $2) ON CONFLICT DO NOTHING`,
|
||||
[ORG_ID, 'Test Webhook Org'],
|
||||
);
|
||||
});
|
||||
|
||||
afterAll(async () => {
|
||||
await pool.query(`DELETE FROM webhook_subscriptions WHERE organization_id = $1`, [ORG_ID]);
|
||||
await pool.query(`DELETE FROM organizations WHERE organization_id = $1`, [ORG_ID]);
|
||||
await pool.end();
|
||||
await closePool();
|
||||
await closeRedisClient();
|
||||
});
|
||||
|
||||
// ─── POST /webhooks ──────────────────────────────────────────────────────────
|
||||
|
||||
describe('POST /api/v1/webhooks', () => {
|
||||
it('should create a webhook subscription and return 201', async () => {
|
||||
const res = await request(app)
|
||||
.post('/api/v1/webhooks')
|
||||
.set('Authorization', `Bearer ${makeToken()}`)
|
||||
.send(VALID_SUBSCRIPTION);
|
||||
|
||||
expect(res.status).toBe(201);
|
||||
expect(res.body).toHaveProperty('id');
|
||||
expect(res.body.url).toBe(VALID_SUBSCRIPTION.url);
|
||||
createdId = res.body.id as string;
|
||||
});
|
||||
|
||||
it('should return 401 when no token provided', async () => {
|
||||
const res = await request(app).post('/api/v1/webhooks').send(VALID_SUBSCRIPTION);
|
||||
expect(res.status).toBe(401);
|
||||
});
|
||||
|
||||
it('should return 422 when url is missing', async () => {
|
||||
const res = await request(app)
|
||||
.post('/api/v1/webhooks')
|
||||
.set('Authorization', `Bearer ${makeToken()}`)
|
||||
.send({ events: ['agent.created'] });
|
||||
|
||||
expect([400, 422]).toContain(res.status);
|
||||
});
|
||||
|
||||
it('should return 422 when events array is empty', async () => {
|
||||
const res = await request(app)
|
||||
.post('/api/v1/webhooks')
|
||||
.set('Authorization', `Bearer ${makeToken()}`)
|
||||
.send({ url: 'https://example.com/wh', events: [] });
|
||||
|
||||
expect([400, 422]).toContain(res.status);
|
||||
});
|
||||
});
|
||||
|
||||
// ─── GET /webhooks ───────────────────────────────────────────────────────────
|
||||
|
||||
describe('GET /api/v1/webhooks', () => {
|
||||
it('should return 200 with list of subscriptions', async () => {
|
||||
const res = await request(app)
|
||||
.get('/api/v1/webhooks')
|
||||
.set('Authorization', `Bearer ${makeToken()}`);
|
||||
|
||||
expect(res.status).toBe(200);
|
||||
expect(Array.isArray(res.body.data ?? res.body)).toBe(true);
|
||||
});
|
||||
|
||||
it('should return 401 when no token provided', async () => {
|
||||
const res = await request(app).get('/api/v1/webhooks');
|
||||
expect(res.status).toBe(401);
|
||||
});
|
||||
});
|
||||
|
||||
// ─── GET /webhooks/:id ───────────────────────────────────────────────────────
|
||||
|
||||
describe('GET /api/v1/webhooks/:id', () => {
|
||||
it('should return 200 with the subscription', async () => {
|
||||
if (!createdId) return; // depends on POST test
|
||||
const res = await request(app)
|
||||
.get(`/api/v1/webhooks/${createdId}`)
|
||||
.set('Authorization', `Bearer ${makeToken()}`);
|
||||
|
||||
expect(res.status).toBe(200);
|
||||
expect(res.body.id).toBe(createdId);
|
||||
});
|
||||
|
||||
it('should return 404 for non-existent subscription', async () => {
|
||||
const res = await request(app)
|
||||
.get(`/api/v1/webhooks/${uuidv4()}`)
|
||||
.set('Authorization', `Bearer ${makeToken()}`);
|
||||
|
||||
expect(res.status).toBe(404);
|
||||
});
|
||||
|
||||
it('should return 401 when no token provided', async () => {
|
||||
const res = await request(app).get(`/api/v1/webhooks/${uuidv4()}`);
|
||||
expect(res.status).toBe(401);
|
||||
});
|
||||
});
|
||||
|
||||
// ─── DELETE /webhooks/:id ────────────────────────────────────────────────────
|
||||
|
||||
describe('DELETE /api/v1/webhooks/:id', () => {
|
||||
it('should return 204 when deleting owned subscription', async () => {
|
||||
if (!createdId) return;
|
||||
const res = await request(app)
|
||||
.delete(`/api/v1/webhooks/${createdId}`)
|
||||
.set('Authorization', `Bearer ${makeToken()}`);
|
||||
|
||||
expect(res.status).toBe(204);
|
||||
});
|
||||
|
||||
it('should return 404 when subscription does not exist', async () => {
|
||||
const res = await request(app)
|
||||
.delete(`/api/v1/webhooks/${uuidv4()}`)
|
||||
.set('Authorization', `Bearer ${makeToken()}`);
|
||||
|
||||
expect(res.status).toBe(404);
|
||||
});
|
||||
|
||||
it('should return 401 when no token provided', async () => {
|
||||
const res = await request(app).delete(`/api/v1/webhooks/${uuidv4()}`);
|
||||
expect(res.status).toBe(401);
|
||||
});
|
||||
});
|
||||
});
|
||||
102
tests/unit/services/ComplianceStatusStore.test.ts
Normal file
102
tests/unit/services/ComplianceStatusStore.test.ts
Normal file
@@ -0,0 +1,102 @@
|
||||
/**
|
||||
* Unit tests for src/services/ComplianceStatusStore.ts
|
||||
*
|
||||
* Uses jest.isolateModules to reset module-level state between test groups
|
||||
* since the store is a module-level Map singleton.
|
||||
*/
|
||||
|
||||
describe('ComplianceStatusStore', () => {
|
||||
// Re-import the module fresh for each describe block to reset state
|
||||
let updateControlStatus: (id: string, status: string) => void;
|
||||
let getAllControlStatuses: () => unknown[];
|
||||
let getControlStatus: (id: string) => unknown;
|
||||
|
||||
beforeEach(() => {
|
||||
jest.resetModules();
|
||||
// eslint-disable-next-line @typescript-eslint/no-var-requires
|
||||
const store = require('../../../src/services/ComplianceStatusStore');
|
||||
updateControlStatus = store.updateControlStatus;
|
||||
getAllControlStatuses = store.getAllControlStatuses;
|
||||
getControlStatus = store.getControlStatus;
|
||||
});
|
||||
|
||||
describe('getAllControlStatuses()', () => {
|
||||
it('should return 5 controls on fresh module load', () => {
|
||||
const statuses = getAllControlStatuses();
|
||||
expect(statuses).toHaveLength(5);
|
||||
});
|
||||
|
||||
it('should default all controls to unknown status', () => {
|
||||
const statuses = getAllControlStatuses() as Array<{ status: string }>;
|
||||
expect(statuses.every((s) => s.status === 'unknown')).toBe(true);
|
||||
});
|
||||
|
||||
it('should return controls in canonical order', () => {
|
||||
const statuses = getAllControlStatuses() as Array<{ id: string }>;
|
||||
const ids = statuses.map((s) => s.id);
|
||||
expect(ids).toEqual(['CC6.1', 'CC6.7', 'CC7.2', 'CC9.2', 'CC7.1']);
|
||||
});
|
||||
|
||||
it('should include name and lastChecked fields on each control', () => {
|
||||
const statuses = getAllControlStatuses() as Array<{ id: string; name: string; lastChecked: string }>;
|
||||
for (const s of statuses) {
|
||||
expect(typeof s.name).toBe('string');
|
||||
expect(s.name.length).toBeGreaterThan(0);
|
||||
expect(typeof s.lastChecked).toBe('string');
|
||||
expect(() => new Date(s.lastChecked)).not.toThrow();
|
||||
}
|
||||
});
|
||||
|
||||
it('should map CC6.1 to Encryption at Rest', () => {
|
||||
const statuses = getAllControlStatuses() as Array<{ id: string; name: string }>;
|
||||
const cc61 = statuses.find((s) => s.id === 'CC6.1');
|
||||
expect(cc61?.name).toBe('Encryption at Rest');
|
||||
});
|
||||
});
|
||||
|
||||
describe('updateControlStatus()', () => {
|
||||
it('should update a control to passing', () => {
|
||||
updateControlStatus('CC6.1', 'passing');
|
||||
const status = getControlStatus('CC6.1') as { status: string };
|
||||
expect(status.status).toBe('passing');
|
||||
});
|
||||
|
||||
it('should update a control to failing', () => {
|
||||
updateControlStatus('CC7.2', 'failing');
|
||||
const status = getControlStatus('CC7.2') as { status: string };
|
||||
expect(status.status).toBe('failing');
|
||||
});
|
||||
|
||||
it('should overwrite a previous status', () => {
|
||||
updateControlStatus('CC9.2', 'passing');
|
||||
updateControlStatus('CC9.2', 'failing');
|
||||
const status = getControlStatus('CC9.2') as { status: string };
|
||||
expect(status.status).toBe('failing');
|
||||
});
|
||||
|
||||
it('should update lastChecked timestamp on each update', async () => {
|
||||
const before = Date.now();
|
||||
updateControlStatus('CC7.1', 'passing');
|
||||
const status = getControlStatus('CC7.1') as { lastChecked: string };
|
||||
const after = new Date(status.lastChecked).getTime();
|
||||
expect(after).toBeGreaterThanOrEqual(before);
|
||||
});
|
||||
|
||||
it('should not affect other controls when one is updated', () => {
|
||||
updateControlStatus('CC6.1', 'passing');
|
||||
const all = getAllControlStatuses() as Array<{ id: string; status: string }>;
|
||||
const others = all.filter((s) => s.id !== 'CC6.1');
|
||||
expect(others.every((s) => s.status === 'unknown')).toBe(true);
|
||||
});
|
||||
});
|
||||
|
||||
describe('getControlStatus()', () => {
|
||||
it('should return the correct control record', () => {
|
||||
updateControlStatus('CC6.7', 'passing');
|
||||
const status = getControlStatus('CC6.7') as { id: string; name: string; status: string };
|
||||
expect(status.id).toBe('CC6.7');
|
||||
expect(status.name).toBe('TLS Enforcement');
|
||||
expect(status.status).toBe('passing');
|
||||
});
|
||||
});
|
||||
});
|
||||
163
tests/unit/services/EventPublisher.test.ts
Normal file
163
tests/unit/services/EventPublisher.test.ts
Normal file
@@ -0,0 +1,163 @@
|
||||
/**
|
||||
* Unit tests for src/services/EventPublisher.ts
|
||||
*/
|
||||
|
||||
import { EventPublisher } from '../../../src/services/EventPublisher';
|
||||
import { WebhookDeliveryWorker } from '../../../src/workers/WebhookDeliveryWorker';
|
||||
import { Pool } from 'pg';
|
||||
|
||||
jest.mock('../../../src/workers/WebhookDeliveryWorker');
|
||||
jest.mock('pg');
|
||||
|
||||
const MockPool = Pool as jest.MockedClass<typeof Pool>;
|
||||
const MockWorker = WebhookDeliveryWorker as jest.MockedClass<typeof WebhookDeliveryWorker>;
|
||||
|
||||
function makePool(queryImpl?: jest.Mock): jest.Mocked<Pool> {
|
||||
const pool = new MockPool() as jest.Mocked<Pool>;
|
||||
pool.query = queryImpl ?? jest.fn();
|
||||
return pool;
|
||||
}
|
||||
|
||||
function makeWorker(): jest.Mocked<WebhookDeliveryWorker> {
|
||||
const worker = new MockWorker({} as never) as jest.Mocked<WebhookDeliveryWorker>;
|
||||
worker.enqueue = jest.fn().mockResolvedValue(undefined);
|
||||
return worker;
|
||||
}
|
||||
|
||||
const ORG_ID = 'org-abc-123';
|
||||
const EVENT_TYPE = 'agent.created' as const;
|
||||
const DATA = { agentId: 'agent-001' };
|
||||
|
||||
describe('EventPublisher', () => {
|
||||
let pool: jest.Mocked<Pool>;
|
||||
let worker: jest.Mocked<WebhookDeliveryWorker>;
|
||||
|
||||
beforeEach(() => {
|
||||
jest.clearAllMocks();
|
||||
pool = makePool();
|
||||
worker = makeWorker();
|
||||
});
|
||||
|
||||
describe('publishEvent() — webhook fanout', () => {
|
||||
it('should query for active subscriptions and create a delivery record', async () => {
|
||||
const subscriptionRows = [{ id: 'sub-001', organization_id: ORG_ID }];
|
||||
const deliveryRow = [{ id: 'del-001' }];
|
||||
pool.query = jest.fn()
|
||||
.mockResolvedValueOnce({ rows: subscriptionRows, rowCount: 1 })
|
||||
.mockResolvedValueOnce({ rows: deliveryRow, rowCount: 1 });
|
||||
|
||||
const publisher = new EventPublisher(worker, pool, null);
|
||||
await publisher.publishEvent(ORG_ID, EVENT_TYPE, DATA);
|
||||
|
||||
expect(pool.query).toHaveBeenCalledTimes(2);
|
||||
expect(pool.query).toHaveBeenNthCalledWith(
|
||||
1,
|
||||
expect.stringContaining('webhook_subscriptions'),
|
||||
[ORG_ID, JSON.stringify([EVENT_TYPE])],
|
||||
);
|
||||
expect(pool.query).toHaveBeenNthCalledWith(
|
||||
2,
|
||||
expect.stringContaining('webhook_deliveries'),
|
||||
expect.arrayContaining(['sub-001', EVENT_TYPE]),
|
||||
);
|
||||
});
|
||||
|
||||
it('should enqueue a Bull delivery job for each matching subscription', async () => {
|
||||
const subscriptionRows = [{ id: 'sub-001', organization_id: ORG_ID }];
|
||||
pool.query = jest.fn()
|
||||
.mockResolvedValueOnce({ rows: subscriptionRows, rowCount: 1 })
|
||||
.mockResolvedValueOnce({ rows: [{ id: 'del-001' }], rowCount: 1 });
|
||||
|
||||
const publisher = new EventPublisher(worker, pool, null);
|
||||
await publisher.publishEvent(ORG_ID, EVENT_TYPE, DATA);
|
||||
|
||||
expect(worker.enqueue).toHaveBeenCalledTimes(1);
|
||||
expect(worker.enqueue).toHaveBeenCalledWith(
|
||||
expect.objectContaining({
|
||||
deliveryId: 'del-001',
|
||||
subscriptionId: 'sub-001',
|
||||
organizationId: ORG_ID,
|
||||
}),
|
||||
);
|
||||
});
|
||||
|
||||
it('should fan out to multiple subscriptions', async () => {
|
||||
const subscriptionRows = [
|
||||
{ id: 'sub-001', organization_id: ORG_ID },
|
||||
{ id: 'sub-002', organization_id: ORG_ID },
|
||||
];
|
||||
pool.query = jest.fn()
|
||||
.mockResolvedValueOnce({ rows: subscriptionRows, rowCount: 2 })
|
||||
.mockResolvedValueOnce({ rows: [{ id: 'del-001' }], rowCount: 1 })
|
||||
.mockResolvedValueOnce({ rows: [{ id: 'del-002' }], rowCount: 1 });
|
||||
|
||||
const publisher = new EventPublisher(worker, pool, null);
|
||||
await publisher.publishEvent(ORG_ID, EVENT_TYPE, DATA);
|
||||
|
||||
expect(worker.enqueue).toHaveBeenCalledTimes(2);
|
||||
});
|
||||
|
||||
it('should not enqueue any jobs when no matching subscriptions exist', async () => {
|
||||
pool.query = jest.fn().mockResolvedValueOnce({ rows: [], rowCount: 0 });
|
||||
|
||||
const publisher = new EventPublisher(worker, pool, null);
|
||||
await publisher.publishEvent(ORG_ID, EVENT_TYPE, DATA);
|
||||
|
||||
expect(worker.enqueue).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('should not throw when subscription DB query fails', async () => {
|
||||
pool.query = jest.fn().mockRejectedValueOnce(new Error('DB down'));
|
||||
|
||||
const publisher = new EventPublisher(worker, pool, null);
|
||||
await expect(publisher.publishEvent(ORG_ID, EVENT_TYPE, DATA)).resolves.toBeUndefined();
|
||||
});
|
||||
|
||||
it('should not throw when delivery insert fails for a subscription', async () => {
|
||||
const subscriptionRows = [{ id: 'sub-001', organization_id: ORG_ID }];
|
||||
pool.query = jest.fn()
|
||||
.mockResolvedValueOnce({ rows: subscriptionRows, rowCount: 1 })
|
||||
.mockRejectedValueOnce(new Error('Insert failed'));
|
||||
|
||||
const publisher = new EventPublisher(worker, pool, null);
|
||||
await expect(publisher.publishEvent(ORG_ID, EVENT_TYPE, DATA)).resolves.toBeUndefined();
|
||||
});
|
||||
});
|
||||
|
||||
describe('publishEvent() — Kafka fanout', () => {
|
||||
it('should produce to Kafka when kafkaProducer is provided', async () => {
|
||||
pool.query = jest.fn().mockResolvedValueOnce({ rows: [], rowCount: 0 });
|
||||
const kafkaProducer = { send: jest.fn().mockResolvedValue(undefined) };
|
||||
|
||||
const publisher = new EventPublisher(worker, pool, kafkaProducer as never);
|
||||
await publisher.publishEvent(ORG_ID, EVENT_TYPE, DATA);
|
||||
|
||||
expect(kafkaProducer.send).toHaveBeenCalledWith(
|
||||
expect.objectContaining({
|
||||
topic: 'agentidp-events',
|
||||
messages: expect.arrayContaining([
|
||||
expect.objectContaining({ key: ORG_ID }),
|
||||
]),
|
||||
}),
|
||||
);
|
||||
});
|
||||
|
||||
it('should not call Kafka when kafkaProducer is null', async () => {
|
||||
pool.query = jest.fn().mockResolvedValueOnce({ rows: [], rowCount: 0 });
|
||||
const kafkaProducer = { send: jest.fn() };
|
||||
|
||||
const publisher = new EventPublisher(worker, pool, null);
|
||||
await publisher.publishEvent(ORG_ID, EVENT_TYPE, DATA);
|
||||
|
||||
expect(kafkaProducer.send).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('should not throw when Kafka produce fails', async () => {
|
||||
pool.query = jest.fn().mockResolvedValueOnce({ rows: [], rowCount: 0 });
|
||||
const kafkaProducer = { send: jest.fn().mockRejectedValue(new Error('Kafka error')) };
|
||||
|
||||
const publisher = new EventPublisher(worker, pool, kafkaProducer as never);
|
||||
await expect(publisher.publishEvent(ORG_ID, EVENT_TYPE, DATA)).resolves.toBeUndefined();
|
||||
});
|
||||
});
|
||||
});
|
||||
117
tests/unit/services/MarketplaceService.test.ts
Normal file
117
tests/unit/services/MarketplaceService.test.ts
Normal file
@@ -0,0 +1,117 @@
|
||||
/**
|
||||
* Unit tests for src/services/MarketplaceService.ts
|
||||
*/
|
||||
|
||||
import { MarketplaceService } from '../../../src/services/MarketplaceService';
|
||||
import { AgentRepository } from '../../../src/repositories/AgentRepository';
|
||||
import { AgentNotFoundError } from '../../../src/utils/errors';
|
||||
import { IAgent, IMarketplaceFilters } from '../../../src/types/index';
|
||||
|
||||
jest.mock('../../../src/repositories/AgentRepository');
|
||||
|
||||
const MockAgentRepo = AgentRepository as jest.MockedClass<typeof AgentRepository>;
|
||||
|
||||
const BASE_FILTERS: IMarketplaceFilters = { page: 1, limit: 10 };
|
||||
|
||||
function makeAgent(overrides: Partial<IAgent> = {}): IAgent {
|
||||
return {
|
||||
agentId: 'agent-001',
|
||||
organizationId: 'org-001',
|
||||
email: 'agent@example.com',
|
||||
agentType: 'screener',
|
||||
version: 'v1.0.0',
|
||||
capabilities: ['resume:read'],
|
||||
owner: 'test-team',
|
||||
deploymentEnv: 'production',
|
||||
status: 'active',
|
||||
isPublic: true,
|
||||
createdAt: new Date('2026-01-01'),
|
||||
updatedAt: new Date('2026-01-02'),
|
||||
did: null,
|
||||
didCreatedAt: null,
|
||||
...overrides,
|
||||
};
|
||||
}
|
||||
|
||||
describe('MarketplaceService', () => {
|
||||
let service: MarketplaceService;
|
||||
let agentRepo: jest.Mocked<AgentRepository>;
|
||||
|
||||
beforeEach(() => {
|
||||
jest.clearAllMocks();
|
||||
agentRepo = new MockAgentRepo({} as never) as jest.Mocked<AgentRepository>;
|
||||
service = new MarketplaceService(agentRepo);
|
||||
});
|
||||
|
||||
describe('listPublicAgents()', () => {
|
||||
it('should return mapped agent cards', async () => {
|
||||
const agent = makeAgent();
|
||||
agentRepo.findPublicAgents = jest.fn().mockResolvedValue({ agents: [agent], total: 1 });
|
||||
|
||||
const result = await service.listPublicAgents(BASE_FILTERS);
|
||||
|
||||
expect(result.data).toHaveLength(1);
|
||||
expect(result.data[0].agentId).toBe('agent-001');
|
||||
expect(result.total).toBe(1);
|
||||
expect(result.page).toBe(1);
|
||||
expect(result.limit).toBe(10);
|
||||
});
|
||||
|
||||
it('should strip private fields (email, organizationId) from cards', async () => {
|
||||
const agent = makeAgent();
|
||||
agentRepo.findPublicAgents = jest.fn().mockResolvedValue({ agents: [agent], total: 1 });
|
||||
|
||||
const result = await service.listPublicAgents(BASE_FILTERS);
|
||||
const card = result.data[0] as Record<string, unknown>;
|
||||
|
||||
expect(card['email']).toBeUndefined();
|
||||
expect(card['organizationId']).toBeUndefined();
|
||||
});
|
||||
|
||||
it('should include a minimal DID document when agent has a DID', async () => {
|
||||
const agent = makeAgent({ did: 'did:web:sentryagent.ai:agents:agent-001' });
|
||||
agentRepo.findPublicAgents = jest.fn().mockResolvedValue({ agents: [agent], total: 1 });
|
||||
|
||||
const result = await service.listPublicAgents(BASE_FILTERS);
|
||||
|
||||
expect(result.data[0].didDocument).not.toBeNull();
|
||||
expect(result.data[0].didDocument?.id).toBe('did:web:sentryagent.ai:agents:agent-001');
|
||||
});
|
||||
|
||||
it('should return null DID document when agent has no DID', async () => {
|
||||
const agent = makeAgent({ did: null });
|
||||
agentRepo.findPublicAgents = jest.fn().mockResolvedValue({ agents: [agent], total: 1 });
|
||||
|
||||
const result = await service.listPublicAgents(BASE_FILTERS);
|
||||
|
||||
expect(result.data[0].didDocument).toBeNull();
|
||||
});
|
||||
|
||||
it('should return empty data array when no public agents exist', async () => {
|
||||
agentRepo.findPublicAgents = jest.fn().mockResolvedValue({ agents: [], total: 0 });
|
||||
|
||||
const result = await service.listPublicAgents(BASE_FILTERS);
|
||||
|
||||
expect(result.data).toHaveLength(0);
|
||||
expect(result.total).toBe(0);
|
||||
});
|
||||
});
|
||||
|
||||
describe('getPublicAgent()', () => {
|
||||
it('should return a card for a public agent', async () => {
|
||||
const agent = makeAgent();
|
||||
agentRepo.findPublicById = jest.fn().mockResolvedValue(agent);
|
||||
|
||||
const card = await service.getPublicAgent('agent-001');
|
||||
|
||||
expect(card.agentId).toBe('agent-001');
|
||||
expect(card.owner).toBe('test-team');
|
||||
});
|
||||
|
||||
it('should throw AgentNotFoundError when agent is not found', async () => {
|
||||
agentRepo.findPublicById = jest.fn().mockResolvedValue(null);
|
||||
|
||||
await expect(service.getPublicAgent('nonexistent')).rejects.toThrow(AgentNotFoundError);
|
||||
});
|
||||
});
|
||||
});
|
||||
200
tests/unit/services/OIDCTrustPolicyService.test.ts
Normal file
200
tests/unit/services/OIDCTrustPolicyService.test.ts
Normal file
@@ -0,0 +1,200 @@
|
||||
/**
|
||||
* Unit tests for src/services/OIDCTrustPolicyService.ts
|
||||
*/
|
||||
|
||||
import { Pool } from 'pg';
|
||||
import {
|
||||
OIDCTrustPolicyService,
|
||||
TrustPolicyNotFoundError,
|
||||
TrustPolicyViolationError,
|
||||
} from '../../../src/services/OIDCTrustPolicyService';
|
||||
import { ValidationError } from '../../../src/utils/errors';
|
||||
|
||||
jest.mock('pg');
|
||||
|
||||
const MockPool = Pool as jest.MockedClass<typeof Pool>;
|
||||
|
||||
function makePool(): jest.Mocked<Pool> {
|
||||
const pool = new MockPool() as jest.Mocked<Pool>;
|
||||
pool.query = jest.fn();
|
||||
return pool;
|
||||
}
|
||||
|
||||
function makePolicyRow(overrides: Record<string, unknown> = {}): Record<string, unknown> {
|
||||
return {
|
||||
id: 'policy-001',
|
||||
provider: 'github',
|
||||
repository: 'acme/my-repo',
|
||||
branch: null,
|
||||
agent_id: 'agent-001',
|
||||
created_at: new Date('2026-01-01'),
|
||||
updated_at: new Date('2026-01-01'),
|
||||
...overrides,
|
||||
};
|
||||
}
|
||||
|
||||
describe('OIDCTrustPolicyService', () => {
|
||||
let service: OIDCTrustPolicyService;
|
||||
let pool: jest.Mocked<Pool>;
|
||||
|
||||
beforeEach(() => {
|
||||
jest.clearAllMocks();
|
||||
pool = makePool();
|
||||
service = new OIDCTrustPolicyService(pool);
|
||||
});
|
||||
|
||||
describe('createTrustPolicy()', () => {
|
||||
it('should create a trust policy successfully', async () => {
|
||||
pool.query = jest.fn()
|
||||
.mockResolvedValueOnce({ rows: [{ agent_id: 'agent-001' }], rowCount: 1 })
|
||||
.mockResolvedValueOnce({ rows: [makePolicyRow()], rowCount: 1 });
|
||||
|
||||
const result = await service.createTrustPolicy({
|
||||
provider: 'github',
|
||||
repository: 'acme/my-repo',
|
||||
branch: null,
|
||||
agentId: 'agent-001',
|
||||
});
|
||||
|
||||
expect(result.provider).toBe('github');
|
||||
expect(result.repository).toBe('acme/my-repo');
|
||||
expect(result.branch).toBeNull();
|
||||
});
|
||||
|
||||
it('should throw ValidationError for non-github provider', async () => {
|
||||
await expect(
|
||||
service.createTrustPolicy({
|
||||
provider: 'gitlab' as never,
|
||||
repository: 'acme/my-repo',
|
||||
branch: null,
|
||||
agentId: 'agent-001',
|
||||
}),
|
||||
).rejects.toThrow(ValidationError);
|
||||
});
|
||||
|
||||
it('should throw ValidationError for malformed repository', async () => {
|
||||
await expect(
|
||||
service.createTrustPolicy({
|
||||
provider: 'github',
|
||||
repository: 'no-slash-here',
|
||||
branch: null,
|
||||
agentId: 'agent-001',
|
||||
}),
|
||||
).rejects.toThrow(ValidationError);
|
||||
});
|
||||
|
||||
it('should throw ValidationError when agentId is empty', async () => {
|
||||
await expect(
|
||||
service.createTrustPolicy({
|
||||
provider: 'github',
|
||||
repository: 'acme/my-repo',
|
||||
branch: null,
|
||||
agentId: '',
|
||||
}),
|
||||
).rejects.toThrow(ValidationError);
|
||||
});
|
||||
|
||||
it('should throw ValidationError when agent not found', async () => {
|
||||
pool.query = jest.fn().mockResolvedValueOnce({ rows: [], rowCount: 0 });
|
||||
|
||||
await expect(
|
||||
service.createTrustPolicy({
|
||||
provider: 'github',
|
||||
repository: 'acme/my-repo',
|
||||
branch: null,
|
||||
agentId: 'nonexistent',
|
||||
}),
|
||||
).rejects.toThrow(ValidationError);
|
||||
});
|
||||
});
|
||||
|
||||
describe('listTrustPoliciesForAgent()', () => {
|
||||
it('should return mapped policies', async () => {
|
||||
pool.query = jest.fn().mockResolvedValue({
|
||||
rows: [makePolicyRow(), makePolicyRow({ id: 'policy-002' })],
|
||||
rowCount: 2,
|
||||
});
|
||||
|
||||
const policies = await service.listTrustPoliciesForAgent('agent-001');
|
||||
|
||||
expect(policies).toHaveLength(2);
|
||||
expect(policies[0].id).toBe('policy-001');
|
||||
});
|
||||
|
||||
it('should return an empty array when no policies exist', async () => {
|
||||
pool.query = jest.fn().mockResolvedValue({ rows: [], rowCount: 0 });
|
||||
|
||||
const policies = await service.listTrustPoliciesForAgent('agent-001');
|
||||
|
||||
expect(policies).toHaveLength(0);
|
||||
});
|
||||
});
|
||||
|
||||
describe('deleteTrustPolicy()', () => {
|
||||
it('should delete a policy successfully', async () => {
|
||||
pool.query = jest.fn().mockResolvedValue({ rowCount: 1 });
|
||||
|
||||
await expect(service.deleteTrustPolicy('policy-001')).resolves.toBeUndefined();
|
||||
});
|
||||
|
||||
it('should throw TrustPolicyNotFoundError when policy does not exist', async () => {
|
||||
pool.query = jest.fn().mockResolvedValue({ rowCount: 0 });
|
||||
|
||||
await expect(service.deleteTrustPolicy('nonexistent')).rejects.toThrow(TrustPolicyNotFoundError);
|
||||
});
|
||||
});
|
||||
|
||||
describe('enforceTrustPolicy()', () => {
|
||||
it('should pass when a wildcard branch policy exists (branch: null)', async () => {
|
||||
pool.query = jest.fn().mockResolvedValue({
|
||||
rows: [makePolicyRow({ branch: null })],
|
||||
rowCount: 1,
|
||||
});
|
||||
|
||||
await expect(
|
||||
service.enforceTrustPolicy('github', 'acme/my-repo', 'refs/heads/main', 'agent-001'),
|
||||
).resolves.toBeUndefined();
|
||||
});
|
||||
|
||||
it('should pass when branch matches exactly', async () => {
|
||||
pool.query = jest.fn().mockResolvedValue({
|
||||
rows: [makePolicyRow({ branch: 'main' })],
|
||||
rowCount: 1,
|
||||
});
|
||||
|
||||
await expect(
|
||||
service.enforceTrustPolicy('github', 'acme/my-repo', 'main', 'agent-001'),
|
||||
).resolves.toBeUndefined();
|
||||
});
|
||||
|
||||
it('should normalize refs/heads/ prefix and match', async () => {
|
||||
pool.query = jest.fn().mockResolvedValue({
|
||||
rows: [makePolicyRow({ branch: 'main' })],
|
||||
rowCount: 1,
|
||||
});
|
||||
|
||||
await expect(
|
||||
service.enforceTrustPolicy('github', 'acme/my-repo', 'refs/heads/main', 'agent-001'),
|
||||
).resolves.toBeUndefined();
|
||||
});
|
||||
|
||||
it('should throw TrustPolicyViolationError when no policies exist', async () => {
|
||||
pool.query = jest.fn().mockResolvedValue({ rows: [], rowCount: 0 });
|
||||
|
||||
await expect(
|
||||
service.enforceTrustPolicy('github', 'acme/my-repo', 'main', 'agent-001'),
|
||||
).rejects.toThrow(TrustPolicyViolationError);
|
||||
});
|
||||
|
||||
it('should throw TrustPolicyViolationError when branch does not match constrained policy', async () => {
|
||||
pool.query = jest.fn().mockResolvedValue({
|
||||
rows: [makePolicyRow({ branch: 'main' })],
|
||||
rowCount: 1,
|
||||
});
|
||||
|
||||
await expect(
|
||||
service.enforceTrustPolicy('github', 'acme/my-repo', 'feature/evil', 'agent-001'),
|
||||
).rejects.toThrow(TrustPolicyViolationError);
|
||||
});
|
||||
});
|
||||
});
|
||||
116
tests/unit/services/UsageService.test.ts
Normal file
116
tests/unit/services/UsageService.test.ts
Normal file
@@ -0,0 +1,116 @@
|
||||
/**
|
||||
* Unit tests for src/services/UsageService.ts
|
||||
*/
|
||||
|
||||
import { Pool } from 'pg';
|
||||
import { UsageService } from '../../../src/services/UsageService';
|
||||
|
||||
jest.mock('pg');
|
||||
|
||||
const MockPool = Pool as jest.MockedClass<typeof Pool>;
|
||||
|
||||
function makePool(): jest.Mocked<Pool> {
|
||||
const pool = new MockPool() as jest.Mocked<Pool>;
|
||||
pool.query = jest.fn();
|
||||
return pool;
|
||||
}
|
||||
|
||||
const TENANT_ID = 'org-abc-123';
|
||||
const DATE = '2026-04-07';
|
||||
|
||||
describe('UsageService', () => {
|
||||
let service: UsageService;
|
||||
let pool: jest.Mocked<Pool>;
|
||||
|
||||
beforeEach(() => {
|
||||
jest.clearAllMocks();
|
||||
pool = makePool();
|
||||
service = new UsageService(pool);
|
||||
});
|
||||
|
||||
describe('getDailyUsage()', () => {
|
||||
it('should return usage summary with real api call count', async () => {
|
||||
pool.query = jest.fn()
|
||||
.mockResolvedValueOnce({ rows: [{ count: '42' }], rowCount: 1 })
|
||||
.mockResolvedValueOnce({ rows: [{ count: '5' }], rowCount: 1 });
|
||||
|
||||
const result = await service.getDailyUsage(TENANT_ID, DATE);
|
||||
|
||||
expect(result.tenantId).toBe(TENANT_ID);
|
||||
expect(result.date).toBe(DATE);
|
||||
expect(result.apiCalls).toBe(42);
|
||||
expect(result.agentCount).toBe(5);
|
||||
});
|
||||
|
||||
it('should default apiCalls to 0 when no usage row exists', async () => {
|
||||
pool.query = jest.fn()
|
||||
.mockResolvedValueOnce({ rows: [{ count: '0' }], rowCount: 1 })
|
||||
.mockResolvedValueOnce({ rows: [{ count: '3' }], rowCount: 1 });
|
||||
|
||||
const result = await service.getDailyUsage(TENANT_ID, DATE);
|
||||
|
||||
expect(result.apiCalls).toBe(0);
|
||||
});
|
||||
|
||||
it('should handle missing count row gracefully (defaults to 0)', async () => {
|
||||
pool.query = jest.fn()
|
||||
.mockResolvedValueOnce({ rows: [], rowCount: 0 })
|
||||
.mockResolvedValueOnce({ rows: [{ count: '2' }], rowCount: 1 });
|
||||
|
||||
const result = await service.getDailyUsage(TENANT_ID, DATE);
|
||||
|
||||
expect(result.apiCalls).toBe(0);
|
||||
});
|
||||
|
||||
it('should query usage_events with correct tenant and date params', async () => {
|
||||
pool.query = jest.fn()
|
||||
.mockResolvedValueOnce({ rows: [{ count: '10' }], rowCount: 1 })
|
||||
.mockResolvedValueOnce({ rows: [{ count: '0' }], rowCount: 1 });
|
||||
|
||||
await service.getDailyUsage(TENANT_ID, DATE);
|
||||
|
||||
expect(pool.query).toHaveBeenNthCalledWith(
|
||||
1,
|
||||
expect.stringContaining('usage_events'),
|
||||
[TENANT_ID, DATE],
|
||||
);
|
||||
});
|
||||
});
|
||||
|
||||
describe('getActiveAgentCount()', () => {
|
||||
it('should return the count of non-decommissioned agents', async () => {
|
||||
pool.query = jest.fn().mockResolvedValue({ rows: [{ count: '7' }], rowCount: 1 });
|
||||
|
||||
const count = await service.getActiveAgentCount(TENANT_ID);
|
||||
|
||||
expect(count).toBe(7);
|
||||
});
|
||||
|
||||
it('should return 0 when no agents exist for tenant', async () => {
|
||||
pool.query = jest.fn().mockResolvedValue({ rows: [{ count: '0' }], rowCount: 1 });
|
||||
|
||||
const count = await service.getActiveAgentCount(TENANT_ID);
|
||||
|
||||
expect(count).toBe(0);
|
||||
});
|
||||
|
||||
it('should exclude decommissioned agents (query contains status check)', async () => {
|
||||
pool.query = jest.fn().mockResolvedValue({ rows: [{ count: '3' }], rowCount: 1 });
|
||||
|
||||
await service.getActiveAgentCount(TENANT_ID);
|
||||
|
||||
expect(pool.query).toHaveBeenCalledWith(
|
||||
expect.stringContaining('decommissioned'),
|
||||
[TENANT_ID],
|
||||
);
|
||||
});
|
||||
|
||||
it('should handle missing count row gracefully', async () => {
|
||||
pool.query = jest.fn().mockResolvedValue({ rows: [], rowCount: 0 });
|
||||
|
||||
const count = await service.getActiveAgentCount(TENANT_ID);
|
||||
|
||||
expect(count).toBe(0);
|
||||
});
|
||||
});
|
||||
});
|
||||
Reference in New Issue
Block a user