# Phase 3: Enterprise — Change Proposal

**Date**: 2026-03-29
**Author**: Virtual Architect
**Status**: Proposed — awaiting CEO approval

---

## Summary

Phase 1 delivered a complete, working AgentIdP MVP. Phase 2 made it production-ready: Vault-backed secrets, multi-language SDKs, OPA policy engine, React dashboard, Prometheus/Grafana observability, and multi-region Terraform deployment. Phase 3 makes AgentIdP enterprise-grade: the platform moves from a single-tenant developer tool to a multi-tenant enterprise identity platform with W3C DID support, OIDC compliance, AGNTCY federation, real-time event streaming, and SOC 2 Type II controls.

---

## Problem Statement

Phase 1 and Phase 2 are functional and production-ready but have the following enterprise gaps:

| Gap | Risk |
|-----|------|
| Single-tenant architecture | Cannot serve enterprise customers with isolated data requirements |
| No W3C DID support | Not fully AGNTCY-compliant; agents lack interoperable decentralized identifiers |
| OAuth 2.0 only, no OIDC | Cannot integrate with standard enterprise identity ecosystems (SSO, SCIM) |
| No cross-instance federation | Multi-organization agent identity cannot be verified across AgentIdP deployments |
| No webhook/event streaming | Operators cannot react to agent lifecycle events in real time |
| No SOC 2 controls | Cannot pass enterprise security reviews; blocks revenue from regulated industries |

---

## Proposed Changes

### 1. Multi-Tenancy
Introduce an Organization model so a single AgentIdP instance can serve multiple isolated organizations. Each organization has its own namespace of agents, credentials, audit log, and rate limits. A new Admin API provides organization lifecycle management. All existing agent, credential, and audit endpoints become organization-scoped.

### 2. W3C Decentralized Identifiers (DIDs)
Issue a W3C `did:web` identifier for every registered agent. Serve DID Documents at `/.well-known/did.json` (instance root) and `/agents/:id/did` (per-agent). Expose a DID resolution endpoint. Produce AGNTCY-format agent cards from DID Documents.

### 3. AGNTCY Federation
Enable cross-instance agent identity federation using signed JWT assertions. Operators register trusted federation partners. Tokens issued by a trusted remote AgentIdP instance can be verified locally, enabling multi-organization and cross-enterprise agent identity interoperability aligned with AGNTCY standards.

### 4. OpenID Connect (OIDC)
Add a full OIDC layer on top of the existing OAuth 2.0 implementation using the `oidc-provider` certified library. Exposes OIDC Discovery, JWKS, ID tokens with agent claims, and an `/agent-info` endpoint (the agent-identity equivalent of the OIDC `/userinfo` endpoint).

### 5. Webhooks and Event Streaming
Real-time event notifications for all agent lifecycle events: agent created, suspended, revoked, credential rotated, token issued. Operators create webhook subscriptions with HMAC-SHA256 signing. Delivery is async via a Redis-backed queue with exponential backoff retry. An optional Kafka/NATS adapter is available for high-throughput environments.

### 6. SOC 2 Type II Preparation
Implement the technical controls required for SOC 2 Type II audit: encryption at rest via PostgreSQL column-level encryption for secrets, TLS enforcement on all inbound connections, automated secrets rotation, security event alerting via Prometheus alerting rules, and audit log immutability proof using a Merkle hash chain appended to each `audit_logs` row.

---

## Out of Scope for Phase 3

- Rust/C++ SDKs (Phase 4)
- Azure Terraform module (Phase 4)
- SCIM provisioning (Phase 4)
- End-user (human operator) identity management (out of product scope — AgentIdP is agent-first)

---

## Capabilities Table

### New Capabilities

| Workstream | Capability | Type |
|-----------|-----------|------|
| Multi-Tenancy | Organization model with isolated agent namespaces | New |
| Multi-Tenancy | Admin API: create, list, update, delete organizations | New |
| Multi-Tenancy | Per-organization rate limits and audit logs | New |
| Multi-Tenancy | Organization member management | New |
| W3C DIDs | `did:web` identifier on every registered agent | New |
| W3C DIDs | DID Document endpoint per agent | New |
| W3C DIDs | Instance-level root DID Document | New |
| W3C DIDs | DID resolution endpoint | New |
| W3C DIDs | AGNTCY-format agent card from DID Document | New |
| OIDC | OIDC Discovery endpoint (`/.well-known/openid-configuration`) | New |
| OIDC | JWKS endpoint (`/.well-known/jwks.json`) | New |
| OIDC | ID token with agent claims in token response | Modified |
| OIDC | `/agent-info` endpoint (agent claims) | New |
| Federation | Trust registry: register and list federation partners | New |
| Federation | Cross-instance token verification endpoint | New |
| Federation | Signed JWT assertion inter-IdP protocol | New |
| Webhooks | Webhook subscription management (CRUD) | New |
| Webhooks | HMAC-SHA256 signed delivery with retry | New |
| Webhooks | Delivery history log | New |
| Webhooks | Kafka/NATS adapter (optional) | New |
| SOC 2 | PostgreSQL column-level encryption for secrets at rest | New |
| SOC 2 | TLS enforcement middleware (reject non-TLS) | New |
| SOC 2 | Automated secrets rotation schedule | New |
| SOC 2 | Security event alerting (Prometheus alerting rules) | New |
| SOC 2 | Merkle hash chain on `audit_logs` for immutability proof | New |
| SOC 2 | Compliance documentation (controls matrix, runbook) | New |

### Modified Capabilities

| Workstream | Capability | Change |
|-----------|-----------|--------|
| Multi-Tenancy | `POST /agents` | Now scoped to `organizationId` |
| Multi-Tenancy | `GET /agents` | Filters restricted to caller's organization |
| Multi-Tenancy | `GET /audit` | Restricted to caller's organization by default |
| Multi-Tenancy | Rate limiting | Per-organization limits in addition to global |
| OIDC | `POST /oauth2/token` | Returns `id_token` in addition to `access_token` |
| SOC 2 | Audit log write path | Computes and appends Merkle hash on insert |

---

## Repository Impact

| Area | Impact |
|------|--------|
| `src/` | New services: OrgService, DIDService, OIDCService, FederationService, WebhookService, SOC2Controls |
| `src/db/migrations/` | 8–10 new migration files |
| `src/types/index.ts` | ~80 new interfaces/types |
| `src/middleware/` | New TLS enforcement middleware, updated auth middleware for org context |
| `src/routes/` | 6 new route files |
| `/.well-known/` | 3 new well-known endpoints |
| `policies/` | Updated Rego policies for org-scoped permissions |
| `dashboard/` | New Organization management pages |
| `monitoring/` | New alerting rules for SOC 2 security events |
| `docs/` | Compliance documentation, federation setup guide, webhook integration guide |

---

## New Dependencies

| Workstream | Package | Purpose | CEO Approval Required |
|-----------|---------|---------|----------------------|
| Multi-Tenancy | No new packages — row-level tenancy in existing PostgreSQL | — | No |
| W3C DIDs | `did-resolver` | W3C DID resolution | Yes |
| W3C DIDs | `web-did-resolver` | DID:WEB method resolver | Yes |
| OIDC | `oidc-provider` | Certified OIDC server library | Yes |
| Federation | No new packages — signed JWT assertions use existing `jsonwebtoken` | — | No |
| Webhooks | `bull` (Redis-backed queue) | Async webhook delivery queue | Yes |
| Webhooks | `kafkajs` (optional, Kafka adapter) | Kafka event streaming | Yes |
| SOC 2 | `node-forge` | Column-level encryption primitives | Yes |

---

## Delivery Sequence

Multi-tenancy is a prerequisite for all enterprise customer work — it must land first. DID support and OIDC are independent and can proceed in parallel. Federation depends on DIDs being in place. Webhooks are standalone. SOC 2 controls cut across the entire codebase and are implemented last to ensure all features they protect are already present.

```
1. Multi-Tenancy (prerequisite — all enterprise features assume org context)
2. W3C DIDs  (parallel)
   OIDC      (parallel)
3. Federation (depends on DIDs)
4. Webhooks (standalone)
5. SOC 2 (cuts across all workstreams — implemented after all features are stable)
```

---

## Success Criteria

- All new dependencies CEO-approved before implementation begins
- All new API endpoints have OpenAPI 3.0 specs before implementation
- Multi-tenancy isolation verified: no cross-organization data leakage
- DID Documents are W3C DID Core 1.0 compliant and resolve correctly
- OIDC Discovery passes `oidc-provider` conformance test suite
- Federation token verification rejects tampered assertions
- Webhook delivery achieves >99.9% success rate with retry logic
- SOC 2 controls pass independent technical review
- TypeScript strict mode + zero `any` maintained throughout
- >80% test coverage on all new services