API - CODEX AGENTS: secure owner lifecycle endpoints

docs/ARCHITECTURE.md

@@ -86,6 +86,8 @@ Agent Gateway owns:
 
 It should not execute user code and should not run Codex itself.
 
+Agent lifecycle management is not public. Tasker/Launcher-facing management calls use `NODEDC_AGENT_GATEWAY_INTERNAL_TOKEN`, while external Codex calls use only the opaque agent token issued for one agent. The owner-scoped internal routes verify that the requested agent belongs to the requested `owner_user_id`.
+
 ### Tasker internal adapter
 
 The adapter is a narrow Tasker API layer for Agent Gateway. It exists because the current Plane REST API is broad and includes operations the agent must not receive directly.

docs/IMPLEMENTATION_PLAN.md

@@ -113,6 +113,8 @@ Acceptance:
 
 Status: initial product slice implemented. `/mcp` supports JSON-RPC `initialize`, `ping`, `tools/list`, and `tools/call`. REST product endpoints and MCP tools share the same runtime, scope checks, grant checks, idempotency handling, audit events, and Tasker adapter calls. `/api/v1/agent-session/setup` returns the MCP config template and generated AGENTS.md instruction pack. `npm run smoke:mcp:e2e` verifies real local Tasker writes and idempotent replay.
 
+Owner lifecycle API is now split from public agent traffic. Management routes require `NODEDC_AGENT_GATEWAY_INTERNAL_TOKEN`, and Tasker UI should use `/api/internal/v1/owners/:ownerUserId/agents...` through a backend proxy. The owner routes verify that the requested agent belongs to the owner before returning grants, tokens, setup packets, profile updates, or revoke actions.
+
 ## Phase 6. Agent identity
 
 Tasker/Gateway integration:

docs/THREAT_MODEL.md

@@ -75,6 +75,17 @@ Mitigation:
 - rate limits;
 - optional IP/device binding later.
 
+### Lifecycle API exposure
+
+Risk: an external caller creates agents, grants projects, or mints tokens without going through Launcher/Tasker entitlement.
+
+Mitigation:
+
+- lifecycle routes require `NODEDC_AGENT_GATEWAY_INTERNAL_TOKEN`;
+- owner-scoped routes verify `owner_user_id` against the stored agent owner;
+- external Codex tokens can call only agent-session, setup, tool, and MCP routes;
+- raw agent token is returned only once on token creation.
+
 ### Owner lifecycle bypass
 
 Risk: blocked/annulled user keeps active agent token.