sentryagent-idp/README.md

SentryAgent.ai — Agent Identity Provider (AgentIdP)

Virtual Engineering Team Charter & Project Specification

Company: SentryAgent.ai
Product: Free, Open Agent Identity Provider for Global AI Developers
Git Repository: https://git.sentryagent.ai/
AI Partner: Anthropic (Claude — All Development, Implementation & Deployment)
Standards: AGNTCY (Linux Foundation), OpenAPI 3.0, OAuth 2.0, OIDC
Last Updated: 2026-03-28
Status: ? Active — Phase 1 MVP

---

1. Company Mission

SentryAgent.ai is building the world's first free, open-source Agent Identity Provider (AgentIdP) — democratizing AI agent authentication, authorization, and governance for developers worldwide.

Aligned with AGNTCY standards (Linux Foundation), SentryAgent.ai treats AI agents as first-class identities — providing unique identifiers, lifecycle management, and governance for any AI agent, built by anyone, anywhere in the world.

Our Promise: Every bedroom developer on the planet can register, authenticate, and govern their AI agents for free — with enterprise-grade security and AGNTCY compliance.

---

2. Anthropic Partnership

SentryAgent.ai has signed a formal agreement with Anthropic for all development, implementation, and deployment activities.

2.1 Claude as Engineering Partner

• All code is written, reviewed, and maintained by Claude
• All architecture decisions are made by Claude (Virtual CTO)
• All documentation is authored by Claude
• All testing is designed and executed by Claude
• All deployments are orchestrated by Claude

2.2 Claude Session Protocol

When a new Claude session is started, Claude MUST:

1. Read this README.md in full before any action
2. Adopt the Virtual Engineering Team roles as defined in Section 4
3. Enforce all standards defined in Section 6 without exception
4. Resume from last known state (check git.sentryagent.ai for latest commits)
5. Report status to CEO before proceeding
6. Never deviate from the technology stack defined in Section 7
7. Never skip OpenSpec documentation for any new endpoint or service
8. Always provide complete files — no partial code, no placeholders

2.3 Claude Communication Protocol

Claude communicates as a Virtual Engineering Team, not as a chatbot:

• Speaks as Virtual CTO for architecture and strategic decisions
• Speaks as Virtual Architect for design and specification
• Speaks as Virtual Principal Developer for implementation
• Speaks as Virtual QA Engineer for testing and quality
• Always identifies which role is speaking when providing output
• Always asks for CEO approval before scope changes

---

3. Project Overview

3.1 Product: SentryAgent.ai AgentIdP

A free, open-source Agent Identity Provider that provides:

Feature	Description	AGNTCY Alignment
Agent Registry	Unique, immutable agent IDs	? First-class non-human identity
Authentication	OAuth 2.0 Client Credentials	? Standardized auth protocol
Authorization	Scope-based access control	? Capability-based governance
Lifecycle Management	Provision, rotate, revoke	? Full agent lifecycle
Audit Logs	Immutable, compliance-ready	? Accountability & governance
Developer SDK	Node.js (Phase 1)	? Developer-first experience

3.2 Target Users

• Bedroom developers building AI agents on limited budgets
• Startups needing AGNTCY-compliant agent identity
• Enterprises evaluating open-source IdP alternatives
• AI researchers experimenting with multi-agent systems

3.3 Free Tier Limits (Phase 1)

Resource	Free Tier Limit
Registered Agents	100
Token Requests/Month	10,000
Audit Log Retention	90 days
API Rate Limit	100 req/min

---

4. Virtual Engineering Team

4.1 Team Structure

CEO (Human — SentryAgent.ai Founder)
+-- Virtual CTO (Claude — Anthropic)
    +-- Virtual Architect (Claude — Anthropic)
    +-- Virtual Principal Developer (Claude — Anthropic)
    +-- Virtual QA Engineer (Claude — Anthropic)

4.2 CEO (Human — SentryAgent.ai Founder)

Authority: Final decision on all business, scope, and strategic matters.

Responsibilities:

• Define business goals and success metrics
• Approve architectural decisions and scope changes
• Manage external stakeholder relationships
• Review and approve all Phase completions
• Provide feedback on deliverables
• Escalation endpoint for all blockers

Communication:

• Reviews Claude's daily progress reports
• Approves/rejects architecture proposals
• Provides business context for technical decisions

4.3 Virtual CTO (Claude — Anthropic)

Authority: All technical decisions within approved scope.

Responsibilities:

• Define and enforce technical vision and architecture
• Ensure 100% compliance with DRY, SOLID, and OpenSpec standards
• Review all code before it is considered complete
• Manage technical risk and debt
• Coordinate Virtual Architect, Principal Developer, and QA Engineer
• Report weekly progress to CEO
• Escalate scope changes and blockers to CEO immediately

Claude Session Startup (CTO Role):

1. Read README.md (this file) in full
2. Check git.sentryagent.ai for latest commits
3. Identify current phase and sprint
4. Report status to CEO
5. Confirm today's priorities
6. Begin work

4.4 Virtual Architect (Claude — Anthropic)

Authority: System design within CTO-approved architecture.

Responsibilities:

• Design all system components and data flows
• Define API contracts (OpenAPI 3.0 — mandatory)
• Specify all database schemas before implementation
• Write Architecture Decision Records (ADRs) for all major decisions
• Ensure scalability, reliability, and security by design
• Review all implementation against specifications
• Maintain docs/architecture.md and docs/openapi.yaml

Deliverables:

• OpenAPI 3.0 spec for every endpoint (before implementation)
• ADR for every major architectural decision
• Database schema for every new table
• Data flow diagrams for every new service

4.5 Virtual Principal Developer (Claude — Anthropic)

Authority: Implementation within Architect-approved specifications.

Responsibilities:

• Implement all features per Virtual Architect specifications
• Write production-grade TypeScript (strict mode, no any)
• Follow DRY and SOLID principles without exception
• Write JSDoc comments for all public methods and classes
• Create unit tests for all services and utilities (>80% coverage)
• Create integration tests for all API endpoints
• Maintain CHANGELOG.md for all changes
• Push all code to git.sentryagent.ai

Code Standards (non-negotiable):

• TypeScript strict mode: "strict": true
• No any types — ever
• No code duplication — extract to utils/services
• All functions documented with JSDoc
• All errors handled explicitly
• All inputs validated before processing

4.6 Virtual QA Engineer (Claude — Anthropic)

Authority: Quality sign-off before any feature is considered complete.

Responsibilities:

• Design test strategy for every feature
• Write unit tests (Jest) for all services
• Write integration tests (Supertest) for all API endpoints
• Test all edge cases and failure scenarios
• Verify AGNTCY compliance for all agent identity operations
• Verify OpenAPI spec matches implementation
• Maintain tests/ directory and test documentation
• Sign off on quality before CEO review

Quality Gates (must pass before completion):

• Unit tests: >80% coverage
• Integration tests: All endpoints tested
• Edge cases: Null, empty, invalid inputs tested
• Security: No OWASP Top 10 vulnerabilities
• Performance: Token <100ms, API <200ms
• AGNTCY: Agent identity model compliant
• OpenAPI: Spec matches implementation exactly

---

5. Project Scope

5.1 Phase 1: MVP (Weeks 1–8)

Objective: Prove the concept. Ship a production-ready AgentIdP.

In Scope ?

Feature	Owner	Priority
Agent Registry Service (CRUD)	Principal Dev	P0
OAuth 2.0 Token Service (Client Credentials)	Principal Dev	P0
Credential Management (generate, rotate, revoke)	Principal Dev	P0
Immutable Audit Log Service	Principal Dev	P0
REST API (agents, tokens, audit)	Principal Dev	P0
PostgreSQL database + migrations	Principal Dev	P0
Redis caching layer	Principal Dev	P1
Node.js SDK	Principal Dev	P1
Docker containerization	Principal Dev	P1
Unit & integration tests (>80% coverage)	QA Engineer	P0
OpenAPI 3.0 documentation	Architect	P0
Docker Compose (local dev)	Principal Dev	P1
Deployment guide	Architect	P1
AGNTCY alignment documentation	Architect	P1

Out of Scope ? (Phase 2+)

Feature	Phase
HashiCorp Vault integration	Phase 2
Multi-region deployment	Phase 2
Advanced policy engine (OPA)	Phase 2
Web dashboard UI	Phase 2
Python/Go/Java/Rust SDKs	Phase 2
Prometheus + Grafana monitoring	Phase 2
AGNTCY federation support	Phase 3
W3C DID support	Phase 3
Agent marketplace	Phase 3
SOC 2 certification	Phase 3

5.2 Phase 2: Production-Ready (Weeks 9–20)

• HashiCorp Vault for secret management
• Multi-language SDKs (Python, Go, Java)
• Advanced policy engine (OPA integration)
• Web dashboard UI (React + TypeScript)
• Prometheus + Grafana monitoring
• Multi-region deployment (US, EU, APAC)
• SOC 2 Type II certification process

5.3 Phase 3: Ecosystem & Standards (Weeks 21–36)

• AGNTCY federation support
• W3C Decentralized Identifiers (DIDs)
• Agent marketplace
• Advanced compliance reporting
• Enterprise tier features

---

6. Engineering Standards (Non-Negotiable)

6.1 DRY — Don't Repeat Yourself

Rule: Zero code duplication. Every piece of logic exists in exactly one place.

Implementation:

Pattern	Location	Purpose
Type definitions	src/types/index.ts	Single source of truth
Crypto utilities	src/utils/crypto.ts	All crypto operations
JWT utilities	src/utils/jwt.ts	All JWT operations
Validation logic	src/utils/validators.ts	All input validation
Error classes	src/utils/errors.ts	All custom errors
DB queries	src/services/	All database access
HTTP middleware	src/middleware/	All cross-cutting concerns

Enforcement:

• Virtual CTO reviews every PR for duplication
• ESLint rules flag repeated patterns
• No copy-paste code — ever

6.2 SOLID Principles

S — Single Responsibility:

• AgentService: Agent CRUD only — nothing else
• OAuth2Service: Token issuance only — nothing else
• CredentialService: Credential management only — nothing else
• AuditService: Audit logging only — nothing else

O — Open/Closed:

• All services implement interfaces
• New features extend, never modify existing code
• Plugin architecture for credential backends

L — Liskov Substitution:

• All service implementations are interchangeable
• Consistent error handling across all services
• Uniform response shapes across all endpoints

I — Interface Segregation:

• Separate read/write interfaces where applicable
• Minimal, focused interfaces — no fat interfaces
• Controllers depend on service interfaces, not implementations

D — Dependency Inversion:

• All dependencies injected via constructor
• Services depend on abstractions (interfaces)
• No direct instantiation of dependencies in business logic

6.3 OpenSpec Standards (Mandatory)

Rule: Every API endpoint MUST have an OpenAPI 3.0 specification BEFORE implementation begins. No exceptions.

Process:

1. Virtual Architect writes OpenAPI spec
2. CEO reviews and approves
3. Virtual Principal Developer implements
4. Virtual QA Engineer verifies spec matches implementation
5. Swagger UI auto-generated from spec

OpenAPI Spec Location: docs/openapi.yaml

Required for every endpoint:

• Summary and description
• Request body schema (with validation rules)
• Response schemas (all status codes)
• Error response schemas
• Authentication requirements
• Example requests and responses

6.4 TypeScript Strict Mode (Mandatory)

Rule: TypeScript strict mode is always enabled. No any types. Ever.

{
  "compilerOptions": {
    "strict": true,
    "noImplicitAny": true,
    "strictNullChecks": true,
    "strictFunctionTypes": true,
    "strictBindCallApply": true,
    "strictPropertyInitialization": true,
    "noImplicitThis": true,
    "alwaysStrict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true
  }
}

6.5 Code Documentation Standards

JSDoc required for:

• All public classes
• All public methods
• All interfaces
• All complex logic blocks

Example:

/**
 * Creates a new AI agent identity in the SentryAgent.ai registry.
 * Assigns a unique immutable ID and provisions credentials.
 *
 * @param {ICreateAgentRequest} request - Agent creation request
 * @returns {Promise<IAgent>} Created agent with assigned ID
 * @throws {AgentAlreadyExistsError} If email already registered
 * @throws {ValidationError} If request data is invalid
 *
 * @example
 * const agent = await agentService.createAgent({
 *   email: 'screener-001@sentryagent.ai',
 *   agentType: 'screener',
 *   version: 'v1.0.0',
 *   capabilities: ['resume:read'],
 *   owner: 'helloworld-team',
 *   deploymentEnv: 'production'
 * });
 */
async createAgent(request: ICreateAgentRequest): Promise<IAgent>

6.6 Error Handling Standards

Rule: All errors are explicit, typed, and handled. No silent failures.

// Custom error hierarchy
class SentryAgentError extends Error {}
class ValidationError extends SentryAgentError {}
class AgentNotFoundError extends SentryAgentError {}
class AgentAlreadyExistsError extends SentryAgentError {}
class CredentialError extends SentryAgentError {}
class AuthenticationError extends SentryAgentError {}
class AuthorizationError extends SentryAgentError {}
class RateLimitError extends SentryAgentError {}

All errors include:

• Error code (machine-readable)
• Error message (human-readable)
• HTTP status code
• Stack trace (development only)

6.7 Git Standards

Repository: https://git.sentryagent.ai/

Branch Strategy (Git Flow):

• main: Production-ready code only
• develop: Integration branch for Phase work
• feature/*: Individual features (e.g., feature/agent-registry)
• bugfix/*: Bug fixes (e.g., bugfix/token-validation)
• release/*: Release preparation (e.g., release/v1.0.0)

Commit Standards (Conventional Commits):

feat(agent): implement agent registry CRUD
fix(oauth2): correct token expiration calculation
docs(api): update OpenAPI spec for /agents endpoint
test(credential): add rotation edge case tests
chore(deps): upgrade TypeScript to 5.3.3

Pull Request Standards:

• Feature branch created from develop
• OpenAPI spec updated (if API change)
• Unit tests added (>80% coverage)
• Integration tests added
• JSDoc comments added
• No code duplication (DRY check)
• SOLID principles followed
• Performance acceptable (<200ms)
• Security review passed
• Virtual CTO approval required
• Virtual QA Engineer sign-off required
• Merge to develop (squash commits)
• Delete feature branch

---

7. Technology Stack

7.1 Runtime & Language

Component	Version	Rationale
Node.js	18+ (LTS)	Stable, widely used, excellent TypeScript support
TypeScript	5.3+	Strict mode, type safety, no any types
npm	9+	Standard package manager

7.2 Web Framework & Middleware

Component	Version	Purpose
Express.js	4.18+	Lightweight, battle-tested web framework
helmet	7.1+	Security headers (HSTS, CSP, etc.)
cors	2.8+	CORS handling
morgan	1.10+	HTTP request logging
pino	8.17+	Structured JSON logging
pino-http	8.6+	Express integration for Pino

7.3 Database & Caching

Component	Version	Purpose
PostgreSQL	14+	Primary database (ACID, reliability)
pg	8.11+	PostgreSQL client library
Redis	7+	Caching layer (token validation, sessions)
redis	4.6+	Redis client library

7.4 Authentication & Security

Component	Version	Purpose
jsonwebtoken	9.1+	JWT signing and verification
bcryptjs	2.4+	Password/secret hashing (10 salt rounds)
uuid	9.0+	Unique ID generation
crypto (Node.js built-in)	N/A	Cryptographic operations
dotenv	16.3+	Environment variable management

7.5 Testing

Component	Version	Purpose
Jest	29.7+	Unit and integration testing
@types/jest	29.5+	TypeScript types for Jest
ts-jest	29.1+	Jest + TypeScript integration
supertest	6.3+	HTTP endpoint testing
@testing-library/node	Latest	Node.js testing utilities

7.6 Code Quality & Linting

Component	Version	Purpose
ESLint	8.56+	Code linting and style
@typescript-eslint/parser	6.17+	TypeScript parsing for ESLint
@typescript-eslint/eslint-plugin	6.17+	TypeScript-specific rules
Prettier	3.1+	Code formatting

7.7 Documentation & API

Component	Version	Purpose
swagger-ui-express	4.6+	Interactive API documentation
joi	17.11+	Schema validation

7.8 Deployment & Containerization

Component	Version	Purpose
Docker	24+	Container runtime
Docker Compose	2.20+	Local development orchestration
Alpine Linux	3.18	Minimal base image

7.9 Validation & Schema

Component	Version	Purpose
Joi	17.11+	Request/response schema validation

---

8. Project Structure (DRY Compliance)

sentryagent-idp/
+-- src/
¦   +-- config/
¦   ¦   +-- env.ts                 # Environment variables
¦   ¦   +-- database.ts            # PostgreSQL connection pool
¦   ¦   +-- redis.ts               # Redis client
¦   ¦   +-- logger.ts              # Pino logger configuration
¦   ¦
¦   +-- types/
¦   ¦   +-- index.ts               # All TypeScript interfaces (single source of truth)
¦   ¦
¦   +-- models/
¦   ¦   +-- Agent.ts               # Agent entity
¦   ¦   +-- Credential.ts          # Credential entity
¦   ¦   +-- AuditLog.ts            # Audit log entity
¦   ¦   +-- Token.ts               # Token entity
¦   ¦
¦   +-- services/
¦   ¦   +-- AgentService.ts        # Agent CRUD (no duplication)
¦   ¦   +-- OAuth2Service.ts       # Token issuance (no duplication)
¦   ¦   +-- CredentialService.ts   # Credential management (no duplication)
¦   ¦   +-- AuditService.ts        # Audit logging (no duplication)
¦   ¦   +-- TokenService.ts        # Token operations (no duplication)
¦   ¦
¦   +-- controllers/
¦   ¦   +-- AgentController.ts     # Agent endpoints
¦   ¦   +-- OAuth2Controller.ts    # OAuth 2.0 endpoints
¦   ¦   +-- HealthController.ts    # Health check endpoint
¦   ¦
¦   +-- middleware/
¦   ¦   +-- authentication.ts      # Bearer token validation
¦   ¦   +-- authorization.ts       # Scope-based access control
¦   ¦   +-- errorHandler.ts        # Global error handling
¦   ¦   +-- logging.ts             # Request/response logging
¦   ¦   +-- validation.ts          # Request validation
¦   ¦   +-- rateLimit.ts           # Rate limiting
¦   ¦
¦   +-- utils/
¦   ¦   +-- crypto.ts              # Crypto utilities (hashing, secrets)
¦   ¦   +-- jwt.ts                 # JWT utilities (sign, verify)
¦   ¦   +-- validators.ts          # Input validation (reusable)
¦   ¦   +-- errors.ts              # Custom error classes
¦   ¦   +-- helpers.ts             # General utilities
¦   ¦
¦   +-- routes/
¦   ¦   +-- agents.ts              # Agent routes
¦   ¦   +-- oauth2.ts              # OAuth 2.0 routes
¦   ¦   +-- health.ts              # Health routes
¦   ¦
¦   +-- migrations/
¦   ¦   +-- 001_create_agents_table.sql
¦   ¦   +-- 002_create_credentials_table.sql
¦   ¦   +-- 003_create_audit_logs_table.sql
¦   ¦
¦   +-- app.ts                     # Express app setup
¦   +-- server.ts                  # Server entry point
¦
+-- tests/
¦   +-- unit/
¦   ¦   +-- services/
¦   ¦   ¦   +-- AgentService.test.ts
¦   ¦   ¦   +-- OAuth2Service.test.ts
¦   ¦   ¦   +-- CredentialService.test.ts
¦   ¦   ¦   +-- AuditService.test.ts
¦   ¦   +-- utils/
¦   ¦       +-- crypto.test.ts
¦   ¦       +-- jwt.test.ts
¦   ¦       +-- validators.test.ts
¦   ¦
¦   +-- integration/
¦   ¦   +-- api/
¦   ¦   ¦   +-- agents.test.ts
¦   ¦   ¦   +-- oauth2.test.ts
¦   ¦   ¦   +-- health.test.ts
¦   ¦   +-- database/
¦   ¦       +-- migrations.test.ts
¦   ¦
¦   +-- fixtures/
¦       +-- agents.json
¦       +-- credentials.json
¦       +-- auditLogs.json
¦
+-- docs/
¦   +-- README.md                  # This file
¦   +-- architecture.md            # Architecture Decision Records
¦   +-- openapi.yaml               # OpenAPI 3.0 specification
¦   +-- deployment.md              # Deployment guide
¦   +-- agntcy-alignment.md        # AGNTCY compliance documentation
¦   +-- api-guide.md               # API usage guide
¦   +-- contributing.md            # Contribution guidelines
¦
+-- docker-compose.yml             # Local development stack
+-- Dockerfile                     # Production image
+-- .dockerignore                  # Docker build exclusions
+-- .env.example                   # Environment template
+-- .env.test                      # Test environment
+-- .gitignore                     # Git exclusions
+-- .eslintrc.js                   # ESLint configuration
+-- .prettierrc.json               # Prettier configuration
+-- tsconfig.json                  # TypeScript configuration
+-- jest.config.js                 # Jest configuration
+-- package.json                   # Dependencies and scripts
+-- package-lock.json              # Locked dependencies
+-- CHANGELOG.md                   # Version history
+-- LICENSE                        # Open source license (MIT)
+-- README.md                      # Project README

DRY Principles Applied:

• ? Single types/index.ts for all interfaces (no duplication)
• ? Shared utils/ for crypto, JWT, validation (no duplication)
• ? Centralized error handling in middleware (no duplication)
• ? Reusable service layer (no business logic in controllers)
• ? Configuration centralized in config/ (no duplication)
• ? Database queries isolated in services (no duplication)

---

9. Development Workflow

9.1 Feature Development Process

Step 1: Specification (Virtual Architect)

• Write Architecture Decision Record (ADR)
• Define OpenAPI 3.0 specification
• Specify database schema
• List test cases
• CEO approves specification

Step 2: Implementation (Virtual Principal Developer)

• Create feature branch: git checkout -b feature/agent-registry
• Implement per specification
• Follow DRY and SOLID principles
• Add JSDoc comments
• Create unit tests (>80% coverage)
• Push to git.sentryagent.ai

Step 3: Code Review (Virtual CTO)

• Check compliance with standards
• Verify DRY principles
• Review test coverage
• Verify SOLID principles
• Approve or request changes

Step 4: Testing (Virtual QA Engineer)

• Run integration tests
• Test edge cases
• Verify AGNTCY alignment
• Verify OpenAPI spec matches implementation
• Sign off on quality

Step 5: Deployment (Virtual CTO)

• Merge to develop branch (squash commits)
• Delete feature branch
• Deploy to staging
• Deploy to production

9.2 Git Workflow

# Create feature branch from develop
git checkout develop
git pull origin develop
git checkout -b feature/agent-registry

# Make changes, commit with conventional commits
git add src/services/AgentService.ts
git commit -m "feat(agent): implement agent registry CRUD"

# Push to repository
git push origin feature/agent-registry

# Create pull request on git.sentryagent.ai
# Virtual CTO reviews and approves
# Virtual QA Engineer signs off

# Merge to develop (squash commits)
git checkout develop
git pull origin develop
git merge --squash feature/agent-registry
git commit -m "feat(agent): implement agent registry CRUD"
git push origin develop

# Delete feature branch
git branch -d feature/agent-registry
git push origin --delete feature/agent-registry

9.3 Code Review Checklist

Before any code is merged to develop, verify:

• TypeScript strict mode: tsc --strict passes
• No any types used
• No code duplication (DRY check)
• SOLID principles applied
• Unit tests included (>80% coverage)
• Integration tests included
• JSDoc comments present
• Error handling implemented
• No OWASP Top 10 vulnerabilities
• Performance acceptable (<200ms)
• Database migrations included
• OpenAPI specification updated
• Conventional commit message used
• Virtual CTO approval obtained
• Virtual QA Engineer sign-off obtained

---

10. OpenSpec Compliance

10.1 OpenAPI 3.0 Specification

Location: docs/openapi.yaml

Mandatory for every endpoint:

• Summary and description
• Request body schema (with validation rules)
• Response schemas (all status codes)
• Error response schemas
• Authentication requirements
• Example requests and responses

Example OpenAPI Spec:

openapi: 3.0.0
info:
  title: SentryAgent.ai Agent Identity Provider
  version: 1.0.0
  description: Free, open-source Agent Identity Provider
  contact:
    name: SentryAgent.ai
    url: https://sentryagent.ai

servers:
  - url: https://api.sentryagent.ai
    description: Production
  - url: http://localhost:3000
    description: Development

paths:
  /agents:
    post:
      summary: Create a new AI agent
      operationId: createAgent
      tags:
        - Agents
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAgentRequest'
      responses:
        '201':
          description: Agent created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Agent'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Agent already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

components:
  schemas:
    Agent:
      type: object
      required:
        - id
        - email
        - agentType
        - version
        - capabilities
        - owner
        - deploymentEnv
        - status
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          format: uuid
          description: Unique agent identifier
        email:
          type: string
          format: email
          description: Agent email (agent-type-001@sentryagent.ai)
        agentType:
          type: string
          description: AGNTCY agent type
        version:
          type: string
          description: Semantic version
        capabilities:
          type: array
          items:
            type: string
          description: Agent capabilities
        owner:
          type: string
          description: Developer or team name
        deploymentEnv:
          type: string
          enum: [development, staging, production]
        status:
          type: string
          enum: [active, suspended, revoked, archived]
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time

    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: Error code
        message:
          type: string
          description: Error message
        details:
          type: object
          description: Additional error details

10.2 AGNTCY Alignment

Agent Identity Model (AGNTCY-compliant):

interface IAgent {
  id: string;                    // Unique agent ID (UUID) — immutable
  email: string;                 // agent-type-001@sentryagent.ai
  agentType: string;             // AGNTCY agent type
  version: string;               // Semantic versioning
  capabilities: string[];        // AGNTCY capabilities
  owner: string;                 // Developer/team name
  deploymentEnv: string;         // dev/staging/prod
  status: string;                // active/suspended/revoked/archived
  createdAt: Date;               // Agent creation timestamp
  updatedAt: Date;               // Last update timestamp
  lastAuthAt?: Date;             // Last authentication timestamp
  metadata?: Record<string, unknown>; // AGNTCY metadata
}

Audit Compliance:

• ? Immutable audit logs (no deletion, no modification)
• ? All agent actions logged (creation, auth, revocation)
• ? Timestamps in ISO 8601 format
• ? Tamper-proof storage (PostgreSQL with constraints)
• ? Retention policy (90 days free tier, configurable)

Policy Enforcement:

• ? Least privilege by default
• ? Capability-based access control
• ? Revocation at scale
• ? Credential rotation on schedule

---

11. Quality Gates & Metrics

11.1 Code Quality Standards

Metric	Target	Tool	Enforcement
Test Coverage	>80%	Jest/nyc	Fail PR if <80%
TypeScript Strict	100%	tsc --strict	Fail build if violations
Linting	0 errors	ESLint	Fail PR if errors
Code Duplication	<5%	Manual review	CTO rejects if >5%
Security Scan	0 high/critical	npm audit	Fail build if vulnerabilities

11.2 Performance Standards

Metric	Target	Measurement	Enforcement
Token Issuance	<100ms	Benchmark test	Fail if >100ms
API Response	<200ms	Integration test	Fail if >200ms
Database Query	<50ms	Query profiling	Fail if >50ms
Cache Hit Rate	>90%	Redis monitoring	Monitor weekly

11.3 Reliability Standards

Metric	Target	Measurement
Uptime	99.5% (Phase 2)	Monitoring dashboard
Error Rate	<0.1%	Error tracking
Recovery Time	<5 minutes	Runbook testing

---

12. Deployment & Operations

12.1 Local Development Setup

# Clone repository
git clone https://git.sentryagent.ai/sentryagent-idp.git
cd sentryagent-idp

# Install dependencies
npm install

# Setup environment
cp .env.example .env
# Edit .env with local values

# Start services (PostgreSQL, Redis)
docker-compose up -d

# Run database migrations
npm run migrate

# Start development server
npm run dev

# Server runs on http://localhost:3000
# Swagger UI: http://localhost:3000/api-docs

12.2 Docker Deployment

# Build image
docker build -t sentryagent-idp:1.0.0 .

# Run container
docker run -p 3000:3000 \
  -e NODE_ENV=production \
  -e DATABASE_URL=postgresql://user:pass@db:5432/sentryagent \
  -e REDIS_URL=redis://cache:6379 \
  -e JWT_SECRET=your-secret-key \
  -e JWT_ISSUER=https://api.sentryagent.ai \
  sentryagent-idp:1.0.0

12.3 Docker Compose (Local Development)

version: '3.9'

services:
  app:
    build: .
    ports:
      - "3000:3000"
    environment:
      NODE_ENV: development
      DATABASE_URL: postgresql://sentryagent:sentryagent@postgres:5432/sentryagent_idp
      REDIS_URL: redis://redis:6379
      JWT_SECRET: dev-secret-key-change-in-production
    depends_on:
      - postgres
      - redis
    volumes:
      - ./src:/app/src
    command: npm run dev

  postgres:
    image: postgres:15-alpine
    environment:
      POSTGRES_USER: sentryagent
      POSTGRES_PASSWORD: sentryagent
      POSTGRES_DB: sentryagent_idp
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    volumes:
      - redis_data:/data

volumes:
  postgres_data:
  redis_data:

12.4 Production Deployment Checklist

• Environment variables configured securely
• Database backups enabled (daily)
• SSL/TLS certificates installed
• Rate limiting configured
• Monitoring alerts set up
• Logging aggregation enabled
• Disaster recovery plan documented
• Security audit completed
• Load balancer configured
• CDN configured (if applicable)
• Health check endpoints verified
• Rollback procedure documented

---

13. Risk Management

13.1 Technical Risks

Risk	Probability	Impact	Mitigation
Database performance degradation	Medium	High	Connection pooling, caching, indexing
Token validation latency	Low	Medium	Redis cache, JWT caching
Credential compromise	Low	Critical	Encryption, audit logs, rotation, monitoring
API rate limiting bypass	Low	Medium	Token bucket algorithm, monitoring
Data loss	Very Low	Critical	Daily backups, replication, disaster recovery

13.2 Mitigation Strategies

• Code Review: Catch issues early (Virtual CTO)
• Testing: >80% coverage (Virtual QA Engineer)
• Monitoring: Real-time alerts (Phase 2)
• Documentation: Clear runbooks for operations
• Backups: Daily database snapshots
• Security: Regular audits and penetration testing

---

14. Success Metrics & KPIs

14.1 Phase 1 MVP Success Criteria

Technical:

• ? All features implemented and tested
• ? >80% test coverage
• ? Zero critical security issues
• ? API response time <200ms
• ? Token issuance <100ms
• ? AGNTCY compliance verified

Adoption:

• ? 50+ agents registered in first month
• ? 10+ developers using the service
• ? Positive feedback on ease of use