The infrastructure plane

Why a separate layer

If each module re-implemented identity, the platform would suffer the classic distributed-monolith pathology: 22 places where a security advisory needs to be applied, 22 places where MFA enforcement can drift. AUTH centralises the surface that absolutely cannot drift.

More structural: PRD §8.6 mandates that AI agents authenticate as Members — there is no "service account with broad permissions" pattern. Agent parity (PRD §2.3 bet #1) requires that a Claude session run on the same identity contract as a human session. One AUTH module is the only sensible place to enforce that.

Key contracts

# GraphQL contract — abbreviated
type Query {
  me: Member!
  myRoles: [Role!]!
  jwks: JwksDocument!  # public keys for downstream subgraphs
}

type Mutation {
  exchangeCodeForToken(code: ID!, verifier: String!): TokenBundle!
  refresh(token: String!): TokenBundle!
  enrollMfa(method: MfaMethod!): MfaEnrollment!
  stepUp(scope: String!, totp: String): TokenBundle!
  revokeSession(sessionId: ID!): Boolean!
}

type TokenBundle {
  jwt: String!          # RS256, 24h expiry
  expiresAt: DateTime!
  refreshCookie: String # Set-Cookie header sent server-side
}

# MCP tool surface
cyberos.auth.whoami       # readOnly=true
cyberos.auth.list_roles   # readOnly=true
cyberos.auth.audit_login  # readOnly=true (own sessions only)

Role catalogue (PRD §8.6.1)

Why a separate layer

The temptation in a 22-module platform is to let each module call the LLM SDK directly — "just import anthropic in the subgraph." That fails three ways. First, cost: without one place to set per-tenant budgets, the bill is unobservable until the credit-card statement arrives. Second, residency: a Vietnam-resident tenant must hit the Bedrock Singapore endpoint, never the US; the rule is too easy to bypass when 22 subgraphs each make their own choice. Third, safety: PII redaction, persona-version stamping, and the OWASP Gen-AI Top-10 mitigations cannot be 22-times-correct; they need one chokepoint.

PRD §8.5 makes the gateway non-optional: every LLM call from every module flows through it. The cost target — ≤ $150/mo internal, ≤ $4/active user/mo at 50-tenant scale — only works because we can see and cap every token at the gateway.

Key contracts

# OpenAI-shaped surface (LiteLLM convention)
POST /v1/chat/completions       # streaming + non-streaming
POST /v1/embeddings              # BGE-M3 self-hosted
POST /v1/rerank                  # BGE-reranker self-hosted
POST /v1/messages                # Anthropic-shaped passthrough
GET  /v1/usage?tenant=acme       # rolling cost view
GET  /v1/models                  # capability-classified list

# Required headers
Authorization: Bearer <subgraph JWT>
X-Cyberos-Tenant: acme
X-Cyberos-Persona: cfo-v3
X-Cyberos-Module: rew           # for cost attribution
X-Cyberos-Trace-Id: 01HXY...    # OTel trace propagation

# Response headers
X-Cyberos-Cost-Cents: 13
X-Cyberos-Cache: hit | miss | bypass
X-Cyberos-Provider: bedrock | anthropic | openai
X-Cyberos-Persona-Version: cfo-v3.2.1

Latency budgets (PRD §8.5.1)

Why a separate layer

The MCP "gateway" is not a single monolithic server — it is a federation router. Each module owns its own MCP server, runs side-by-side with its subgraph, shares the database connection pool, and uses the same RBAC predicates. The gateway's job is two things: (1) one discovery endpoint at /.well-known/mcp so a Claude Desktop or Cursor session can auto-detect the catalog, and (2) cross-cutting policy enforcement — tool annotations (destructive / readOnly / idempotent / openWorld), OAuth audience binding, audit row emission.

Naming convention is the moat against tool-name collisions: cyberos.{module}.{verb}_{noun}. Examples: cyberos.proj.create_task, cyberos.brain.search, cyberos.rew.payslip_explain (read-only narrative; never compute). Collisions are rejected at registration time.

2025-11-25 spec features adopted

OAuth-Protected Resource Metadata (PRD §8.4.3)

# GET /.well-known/oauth-protected-resource (per-tenant)
{
  "resource": "https://acme-tenant.cyberos.world",
  "authorization_servers": [
    "https://acme-tenant.cyberos.world/oauth"
  ],
  "scopes_supported": [
    "cyberos.read", "cyberos.write",
    "cyberos.brain.read", "cyberos.brain.write",
    "cyberos.proj.read", "cyberos.proj.write",
    "cyberos.chat.read", "cyberos.chat.write",
    "cyberos.rew.read"
  ],
  "bearer_methods_supported": ["header"]
}

# GET /.well-known/oauth-authorization-server
{
  "issuer": "https://acme-tenant.cyberos.world/oauth",
  "authorization_endpoint": ".../authorize",
  "token_endpoint": ".../token",
  "code_challenge_methods_supported": ["S256"],
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token"]
}

Note: Resource-server-as-OAuth-client behaviour is forbidden — the prior pattern that the security community flagged in 2025 ("token shadow handoff" via X-Forwarded-Authorization) is rejected at gateway level. Audience binding ensures an Acme tenant's token cannot be replayed at the Beta tenant's gateway even if leaked.

Why a separate layer

In a 22-module platform with agent traffic on top of human traffic, you cannot answer "why is REW slow?" without tying together: a Member's request through Apollo Router, the REW subgraph's DB query, a call out to the AI Gateway for a payslip narrative, an audit row to NATS, and a downstream LEARN subscription. OBS is the single trace tree that makes that legible.

OBS also feeds CUO's CTO skill: weekly OBS dashboard digests, security advisory pipelines, and model registry summaries all read from OBS (PRD §13 AI matrix).

Why a separate layer (and why Apollo Federation specifically)

CyberOS rejects three alternative API postures. REST per module means the front-end host shell does N round-trips per page. BFF (backend-for-frontend) per module means N+M maintenance burdens. Single monolithic GraphQL means schema-merge conflicts every time a module ships. Apollo Federation v2.5+ solves all three: each module owns its subgraph SDL, the Router composes the supergraph at deploy time, and one HTTP roundtrip can pull from 5 modules in parallel.

PRD §8.2 makes persisted queries mandatory for production traffic. Query hashes are pre-registered at deploy; any unregistered query is rejected with a 400. This caps abuse, enables CDN caching, and lets each subgraph publish a query budget.

Why a separate layer

A 22-module platform needs to decouple write paths from downstream effects. When REW publishes a payslip, six things need to happen: BRAIN ingests the narrative, LEARN updates the career-level snapshot, OBS emits a metric, CUO queues a "review your payslip" Notify, the Compliance audit row is hashed, and the Member's mobile gets a push. All six are events on the canonical subject cyberos.acme.rew.payslip.published.

PRD §8.10 locks the convention: cyberos.{tenant}.{module}.{entity}.{verb}. Subjects are tenant-scoped so subscribers cannot accidentally cross tenant boundaries. Streams retain 30 days by default, 90 days for compensation/ESOP. CUO's ambient-trigger consumers subscribe through durable consumers so a restart never loses pending nudges.

Canonical subjects (PRD §8.10)

# Format
cyberos.{tenant}.{module}.{entity}.{verb}

# Examples
cyberos.acme.proj.task.created
cyberos.acme.proj.task.assigned
cyberos.acme.proj.task.completed
cyberos.acme.rew.payslip.published       # 90-day retention
cyberos.acme.rew.bp_balance.updated
cyberos.acme.brain.fact.added
cyberos.acme.brain.fact.conflict_detected
cyberos.acme.crm.deal.stage_changed
cyberos.acme.chat.message.posted
cyberos.acme.audit.event.recorded         # Merkle-chained; 7y retention
cyberos.acme.ai.invoke.completed          # cost ledger
cyberos.acme.mcp.tool.invoked

# Durable consumers
- cuo-ambient        → subscribes to *.task.* + *.deal.* + *.payslip.*
- brain-ingest       → subscribes to all non-compensation events
- obs-rollup         → subscribes to *.>
- compliance-audit   → subscribes to *.audit.>
- learn-snapshot     → subscribes to rew.payslip.* + hr.level.*