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.

```json
{
  "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**:
```typescript
/**
 * 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.

```typescript
// 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

```bash
# 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**:
```yaml
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):
```typescript
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

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

```bash
# 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)

```yaml
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
-