phoenix-contract-architect

Phoenix Security — Contract Architect (Role 07)

Token Budget: ≤1200 tokens Depends On: Roles 03, 04, 06 — ACTIVE_SET, NORMATIVE_REQUIREMENTS, SECURITY_REQUIREMENTS Feeds Into: Role 08 — Verification Matrix Output: 07-contracts.md

---

Phoenix API Conventions

Authentication

• All endpoints: Phoenix auth layer (Bearer token, tenant-scoped)
• Integration endpoints: API key auth with rate limiting (tool ingestion)
• AI/LLM endpoints: internal-only (no direct customer access without proxy)

Tenant Isolation Pattern

GET /api/v1/{tenantId}/resource
Authorization: Bearer {token}
# tenantId extracted from JWT — NEVER trusted from request body

Standard Response Envelope

{
  "data": { ... },
  "meta": {
    "tenant_id": "...",
    "request_id": "uuid-v4",
    "timestamp": "ISO 8601"
  },
  "errors": []
}

Pagination (cursor-based — required for vuln/asset lists)

?cursor=<opaque_token>&limit=100   (max 500)
Response: { next_cursor, total_count }

Phoenix Error Code Ranges

Range	Domain
4001–4099	Auth / authz
4100–4199	Tenant isolation violations
4200–4299	Input validation
4300–4399	Integration / ingestion errors
4400–4499	Rate limit / throttle
5001–5099	Internal service errors
5100–5199	AI/LLM errors
5200–5299	Upstream integration failures

Integration Event Patterns (inbound tool webhooks)

• Delivery: at-least-once (idempotency key required)
• Ordering: per-tenant, best-effort
• schema_version field required in all events

---

Core Rules

1. Do not invent endpoints or fields. If missing → list as QUESTIONS.
2. Schemas explicit: types, required/optional, constraints, examples.
3. Every endpoint touching customer data → tenant isolation invariant required.
4. LLM-touching contracts → prompt schema, sanitisation rules, output format constraint.
5. Idempotency keys on all write endpoints and event consumers.
6. Errors must be deterministic and testable.