epic: Agent Auth as a First-Class Citizen

[sangalo20]

Epic Overview

This epic tracks all work required to make agent authentication a first-class citizen in the Nexus Framework, as defined in AGENT_AUTH_PROPOSAL.md.

Context

Nexus today is a well-built OAuth 2.0 broker. It handles user consent flows, encrypts tokens at rest, manages token refresh, and exposes a clean REST API. But the framework was designed around a user-centric model — a human connects to a provider, the broker stores the token, the agent retrieves it.

This model leaves a critical gap for production agent systems:

• Agents have no registered identity or bounded permissions
• There is no mechanism to act on behalf of a specific human user
• Custom (non-OAuth) internal scopes have no representation
• Provider credentials live in Postgres rather than enterprise vaults
• SDKs only exist for Go, excluding Python and TypeScript agent developers

This epic closes that gap without turning Nexus into an identity provider. Human identity remains in the developer's existing auth backend. Nexus becomes a Policy Enforcement Point and Token Exchange layer for machines.

---

Child Issues

Core Broker (implement first — everything else depends on this)

• feat(broker): Agent Identity Registry & Scoped Session Endpoints #59 — Agent Identity Registry & Scoped Session Endpoints (P1)
• feat(broker): On-Behalf-Of (OBO) Session Endpoint #61 — On-Behalf-Of (OBO) Session Endpoint (P2)
• feat(broker): Custom (Non-OAuth) Scope Support #62 — Custom (Non-OAuth) Scope Support (P3)

Infrastructure

• feat(broker): External Vault Integration for Provider Credentials #63 — External Vault Integration for Provider Credentials (P5)

SDKs

• feat(sdk): Python SDK — Extract from JarvisCore, Publish to PyPI #64 — Python SDK: Extract from JarvisCore, Publish to PyPI (P3)
• feat(sdk): TypeScript SDK — New Package, Publish to NPM #65 — TypeScript SDK: New Package, Publish to NPM (P4)
• feat(sdk): Go SDK — Add Agent Session & OBO Methods to nexus-sdk #66 — Go SDK: Add Agent Session & OBO Methods (P6)

Documentation & Tooling

• docs(openapi): Document All New Agent Session Endpoints in OpenAPI Spec #67 — OpenAPI: Document All New Agent Session Endpoints (P7)
• feat(cli): Add Agent & Session Management Commands to nexus-cli #68 — CLI: Agent & Session Management Commands (P8)

---

Implementation Order

#59 (Agent Identity)
  └─> #61 (OBO)
  └─> #62 (Custom Scopes)
  └─> #66 (Go SDK methods)
  └─> #67 (OpenAPI spec)
        └─> #64 (Python SDK)
        └─> #65 (TypeScript SDK)
  └─> #68 (CLI commands)

#63 (Vault) — independent, can be done in parallel

What This Epic Explicitly Does NOT Do

• ❌ Replace your existing identity provider (Auth0, Clerk, Cognito, etc.)
• ❌ Compete with HashiCorp Vault, AWS SSM, or GCP Secret Manager
• ❌ Add an agent runtime or orchestration layer
• ❌ Introduce a new standalone service — all additions go into nexus-broker

Reference

AGENT_AUTH_PROPOSAL.md