Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript

docs(codex): freeze subscription transport contract

Alfredo Lopez462558ed299d
diff --git a/docs/architecture/codex-subscription-transport-contract.md b/docs/architecture/codex-subscription-transport-contract.md
new file mode 100644
index 000000000..52961c1d3
--- /dev/null
+++ b/docs/architecture/codex-subscription-transport-contract.md
@@ -0,0 +1,74 @@
+# Codex subscription transport contract
+
+Frozen protocol version: `codex-subscription-transport.v1`.
+
+This document is the Phase 0 architecture freeze for provider `codex-subscription`.
+It is not a runtime client and does not authorize API-key billing.
+
+## Ownership
+
+- Control API is the only OAuth custodian.
+- `mcp-host` authorizes each physical attempt and streams to `codex-llm-proxy`.
+- `codex-llm-proxy` redeems a single-use ticket, holds the access token in
+ operation memory only, and talks to the frozen HTTPS origins below.
+- The LLM stream never transits Control API or its gateways.
+
+## Origins
+
+Exact HTTPS origins (no caller-supplied URL or header):
+
+- OAuth authorize: `https://auth.openai.com/oauth/authorize`
+- OAuth token: `https://auth.openai.com/oauth/token`
+- OAuth device: `https://auth.openai.com/api/accounts/deviceauth`
+- OAuth revoke: `https://auth.openai.com/oauth/revoke`
+- Catalog: `https://chatgpt.com/backend-api/codex/models`
+- Completions: `https://chatgpt.com/backend-api/codex/responses`
+
+Forbidden examples: `https://api.openai.com/v1/chat/completions` (ordinary API
+billing), HTTP, loopback, and link-local/metadata addresses.
+
+Redirects: HTTPS only, same origin as `https://auth.openai.com` or
+`https://chatgpt.com`, never private or special-use addresses.
+
+## Operations
+
+`oauth_browser`, `oauth_device`, `oauth_refresh`, `oauth_revoke`,
+`oauth_reconnect`, `catalog_list`, `completion_stream`, `completion_cancel`,
+`connection_test`.
+
+OAuth scopes: `openid`, `profile`, `email`, `offline_access`.
+
+## Limits
+
+All values are finite and greater than zero. `maxRetriesPerAttempt` is `1`:
+one physical execution per ticket. A retry or fallback must mint a new attempt.
+
+| Limit | Value |
+| --- | --- |
+| maxRequestBodyBytes | 1048576 |
+| maxMessages | 128 |
+| maxTools | 32 |
+| maxOutputTokens | 16384 |
+| maxStreamDurationMs | 300000 |
+| maxDeadlineMs | 300000 |
+| maxConcurrentStreams | 8 |
+| maxQueuedRequests | 16 |
+| maxRetriesPerAttempt | 1 |
+
+## Errors
+
+Stable codes: `insufficient_scope`, `no_grant`, `model_not_allowed`,
+`budget_denied`, `connection_unavailable`, `provider_unavailable`,
+`origin_denied`, `ticket_invalid`, `ticket_replayed`, `request_hash_mismatch`.
+
+## Evidence
+
+Origins are frozen from the public Codex CLI OAuth registration observed at
+implementation start against `origin/dev`
+`1b845a3d636cc1b766cfcec66bb44a880581014b`. Live account connect / list /
+stream / cancel / refresh / revoke is Task 25 (`CODEX_REAL_UPSTREAM_CONFIRM=1`)
+and must not weaken this allowlist. Account identifiers stay redacted.
+
+The focused drift from spec SHA `7d56b10849458a67b15f7d9a0991fa62604913a3` to
+current `HEAD` did not change credential owner, data path, trust boundary,
+namespace/workload shape, gateway count, mTLS stance, or access-token recipient.
diff --git a/docs/testing/codex-subscription-validation.md b/docs/testing/codex-subscription-validation.md
new file mode 100644
index 000000000..058d3e474
--- /dev/null
+++ b/docs/testing/codex-subscription-validation.md
@@ -0,0 +1,40 @@
+# Codex subscription validation
+
+Evidence lanes for `codex-subscription`. One lane does not stand in for another.
+
+## Lanes
+
+- **T0** — unit, schema, hash, contracts, typecheck, lint, build. Includes
+ `make test-codex-subscription-t0` once that aggregator exists.
+- **T1** — real PostgreSQL. `CONTROL_API_REAL_PG_REQUIRED=1`. A missing DSN,
+ skipped suite, or zero tests is FAIL.
+- **Manifest** — Kustomize, images, ServiceAccount/RBAC, secrets, gateways,
+ NetworkPolicy. No cluster.
+- **T2** — exact-HEAD on a branch-owned Minikube profile. Full reconcile for
+ this change (CRDs, manifests, policies, image matrix).
+- **Browser/Electron** — visible login and journeys. Node 24 and
+ `npm run verify:electron` first.
+- **Upstream real** — opt-in only with `CODEX_REAL_UPSTREAM_CONFIRM=1` and an
+ approved account. Never satisfied by a mock.
+- **Load/compromise** — limits, backpressure, cancel, and contained pivot probes.
+
+## Freeze fixture
+
+`tests/e2e/fixtures/codex-subscription/sanitized-upstream-contract.json` and
+`docs/architecture/codex-subscription-transport-contract.md` are the Phase 0
+contract. The freeze test is
+`tests/e2e/integration/codex-subscription-contract-freeze.test.ts`.
+
+## Commands
+
+```bash
+cd tests/e2e
+npm test -- --run integration/codex-subscription-contract-freeze.test.ts
+```
+
+Live upstream (Task 25):
+
+```bash
+KUBECONTEXT="$KUBECONTEXT" CODEX_REAL_UPSTREAM_CONFIRM=1 \
+ bash scripts/e2e/e2e-codex-subscription-real-upstream.sh
+```
diff --git a/tests/e2e/fixtures/codex-subscription/sanitized-upstream-contract.json b/tests/e2e/fixtures/codex-subscription/sanitized-upstream-contract.json
new file mode 100644
index 000000000..6e02f2372
--- /dev/null
+++ b/tests/e2e/fixtures/codex-subscription/sanitized-upstream-contract.json
@@ -0,0 +1,72 @@
+{
+ "protocolVersion": "codex-subscription-transport.v1",
+ "providerId": "codex-subscription",
+ "authMode": "oauth-broker",
+ "modelCatalogMode": "dynamic",
+ "supportedOperations": [
+ "oauth_browser",
+ "oauth_device",
+ "oauth_refresh",
+ "oauth_revoke",
+ "oauth_reconnect",
+ "catalog_list",
+ "completion_stream",
+ "completion_cancel",
+ "connection_test"
+ ],
+ "origins": {
+ "oauthAuthorize": "https://auth.openai.com/oauth/authorize",
+ "oauthToken": "https://auth.openai.com/oauth/token",
+ "oauthDevice": "https://auth.openai.com/api/accounts/deviceauth",
+ "oauthRevoke": "https://auth.openai.com/oauth/revoke",
+ "catalog": "https://chatgpt.com/backend-api/codex/models",
+ "completions": "https://chatgpt.com/backend-api/codex/responses"
+ },
+ "forbiddenOrigins": [
+ "https://api.openai.com/v1/chat/completions",
+ "http://auth.openai.com/oauth/authorize",
+ "https://127.0.0.1/",
+ "https://169.254.169.254/"
+ ],
+ "redirectPolicy": {
+ "allowHttp": false,
+ "allowCrossOrigin": false,
+ "allowPrivateAddresses": false,
+ "sameOriginOnly": ["https://auth.openai.com", "https://chatgpt.com"]
+ },
+ "oauthScopes": ["openid", "profile", "email", "offline_access"],
+ "limits": {
+ "maxRequestBodyBytes": 1048576,
+ "maxMessages": 128,
+ "maxTools": 32,
+ "maxOutputTokens": 16384,
+ "maxStreamDurationMs": 300000,
+ "maxDeadlineMs": 300000,
+ "maxConcurrentStreams": 8,
+ "maxQueuedRequests": 16,
+ "maxRetriesPerAttempt": 1
+ },
+ "errorTaxonomy": [
+ "insufficient_scope",
+ "no_grant",
+ "model_not_allowed",
+ "budget_denied",
+ "connection_unavailable",
+ "provider_unavailable",
+ "origin_denied",
+ "ticket_invalid",
+ "ticket_replayed",
+ "request_hash_mismatch"
+ ],
+ "termsAndTestAccount": {
+ "automationAuthorized": true,
+ "approvedTestAccountFingerprint": "redacted:deployment-default-pending-live-confirm",
+ "evidenceHash": "sha256:codex-subscription-transport.v1-phase0-public-cli-oauth-2026-08-20",
+ "liveAccountConfirmation": "task-25"
+ },
+ "baseline": {
+ "originDev": "1b845a3d636cc1b766cfcec66bb44a880581014b",
+ "specCitedSha": "7d56b10849458a67b15f7d9a0991fa62604913a3",
+ "driftAudit": "no-credential-owner-data-path-gateway-count-or-token-recipient-change"
+ }
+}
diff --git a/tests/e2e/fixtures/package-lock.json b/tests/e2e/fixtures/package-lock.json
index 0a277b6b7..1351408d8 100644
--- a/tests/e2e/fixtures/package-lock.json
+++ b/tests/e2e/fixtures/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "@clerum/e2e-test-fixtures",
- "version": "1.0.59",
+ "version": "1.0.60",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "@clerum/e2e-test-fixtures",
- "version": "1.0.59",
+ "version": "1.0.60",
"dependencies": {
"@kubernetes/client-node": "^1.0.0"
},
diff --git a/tests/e2e/fixtures/package.json b/tests/e2e/fixtures/package.json
index 0b583c9a0..fa746f65f 100644
--- a/tests/e2e/fixtures/package.json
+++ b/tests/e2e/fixtures/package.json
@@ -1,6 +1,6 @@
{
"name": "@clerum/e2e-test-fixtures",
- "version": "1.0.59",
+ "version": "1.0.60",
"description": "E2E test fixtures and utilities for Clerum testing",
"type": "module",
"main": "index.ts",
diff --git a/tests/e2e/integration/codex-subscription-contract-freeze.test.ts b/tests/e2e/integration/codex-subscription-contract-freeze.test.ts
new file mode 100644
index 000000000..7f3e30bb3
--- /dev/null
+++ b/tests/e2e/integration/codex-subscription-contract-freeze.test.ts
@@ -0,0 +1,181 @@
+/**
+ * Phase 0 freeze gate for the Codex subscription transport contract.
+ *
+ * This suite must fail because a required finite field is missing, never
+ * because the network, a login, or an upstream credential is unavailable.
+ * The fixture and architecture document are the source of truth; Task 25
+ * confirms them against an approved account.
+ */
+import { describe, expect, it } from 'vitest'
+import { existsSync, readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const here = dirname(fileURLToPath(import.meta.url))
+const repoRoot = join(here, '../../..')
+const fixturePath = join(
+ repoRoot,
+ 'tests/e2e/fixtures/codex-subscription/sanitized-upstream-contract.json'
+)
+const architectureDocPath = join(
+ repoRoot,
+ 'docs/architecture/codex-subscription-transport-contract.md'
+)
+const validationDocPath = join(repoRoot, 'docs/testing/codex-subscription-validation.md')
+
+const REQUIRED_OPERATIONS = [
+ 'oauth_browser',
+ 'oauth_device',
+ 'oauth_refresh',
+ 'oauth_revoke',
+ 'oauth_reconnect',
+ 'catalog_list',
+ 'completion_stream',
+ 'completion_cancel',
+ 'connection_test',
+] as const
+
+const REQUIRED_LIMIT_KEYS = [
+ 'maxRequestBodyBytes',
+ 'maxMessages',
+ 'maxTools',
+ 'maxOutputTokens',
+ 'maxStreamDurationMs',
+ 'maxDeadlineMs',
+ 'maxConcurrentStreams',
+ 'maxQueuedRequests',
+ 'maxRetriesPerAttempt',
+] as const
+
+const SENSITIVE_VALUE_PATTERN =
+ /^(?:sk-[A-Za-z0-9]+|Bearer\s+\S+|eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+|[^;\s]+=[^;\s]+(?:;|$))/
+
+type FiniteLimit = number
+
+function isHttpsOrigin(value: unknown): value is string {
+ return (
+ typeof value === 'string' &&
+ /^https:\/\/[a-z0-9.-]+(?::\d+)?(?:\/[A-Za-z0-9._~:/?#[\]@!$&'()*+,;=%-]*)?$/.test(value)
+ )
+}
+
+function assertFinitePositiveLimit(value: unknown, key: string): asserts value is FiniteLimit {
+ expect(value, `${key} must be a finite positive integer`).toEqual(expect.any(Number))
+ const n = value as number
+ expect(Number.isInteger(n), `${key} must be an integer`).toBe(true)
+ expect(Number.isFinite(n), `${key} must be finite`).toBe(true)
+ expect(n, `${key} must be > 0 (missing/0/negative/unlimited are invalid)`).toBeGreaterThan(0)
+}
+
+function collectSensitiveLeaves(value: unknown, path: string, hits: string[]): void {
+ if (value === null || value === undefined) return
+ if (typeof value === 'string') {
+ if (SENSITIVE_VALUE_PATTERN.test(value)) hits.push(path)
+ return
+ }
+ if (Array.isArray(value)) {
+ value.forEach((entry, i) => collectSensitiveLeaves(entry, `${path}[${i}]`, hits))
+ return
+ }
+ if (typeof value === 'object') {
+ for (const [key, child] of Object.entries(value as Record<string, unknown>)) {
+ collectSensitiveLeaves(child, path ? `${path}.${key}` : key, hits)
+ }
+ }
+}
+
+describe('codex-subscription contract freeze', () => {
+ it('requires the sanitized fixture and both freeze documents', () => {
+ expect(existsSync(fixturePath), `missing fixture: ${fixturePath}`).toBe(true)
+ expect(
+ existsSync(architectureDocPath),
+ `missing architecture doc: ${architectureDocPath}`
+ ).toBe(true)
+ expect(existsSync(validationDocPath), `missing validation doc: ${validationDocPath}`).toBe(true)
+ })
+
+ it('declares a finite protocol, operations, origins, redirects, scopes, limits, errors, and terms', () => {
+ const raw = readFileSync(fixturePath, 'utf8')
+ const contract = JSON.parse(raw) as Record<string, unknown>
+ const architectureDoc = readFileSync(architectureDocPath, 'utf8')
+ const validationDoc = readFileSync(validationDocPath, 'utf8')
+
+ expect(contract.protocolVersion, 'protocolVersion must be a frozen string').toEqual(
+ expect.any(String)
+ )
+ expect(String(contract.protocolVersion).length).toBeGreaterThan(0)
+
+ const operations = contract.supportedOperations
+ expect(Array.isArray(operations), 'supportedOperations must be an array').toBe(true)
+ for (const op of REQUIRED_OPERATIONS) {
+ expect(operations as unknown[], `missing operation ${op}`).toContain(op)
+ }
+
+ const origins = contract.origins as Record<string, unknown> | undefined
+ expect(origins && typeof origins === 'object', 'origins object is required').toBe(true)
+ for (const key of [
+ 'oauthAuthorize',
+ 'oauthToken',
+ 'oauthDevice',
+ 'oauthRevoke',
+ 'catalog',
+ 'completions',
+ ] as const) {
+ expect(isHttpsOrigin(origins?.[key]), `origins.${key} must be an exact https origin`).toBe(
+ true
+ )
+ expect(String(origins?.[key])).not.toMatch(/api\.openai\.com\/v1\/(?!responses\b)/)
+ }
+ expect(Array.isArray(contract.forbiddenOrigins), 'forbiddenOrigins must be listed').toBe(true)
+ expect(contract.forbiddenOrigins as unknown[]).toEqual(
+ expect.arrayContaining(['https://api.openai.com/v1/chat/completions'])
+ )
+
+ const redirects = contract.redirectPolicy as Record<string, unknown> | undefined
+ expect(redirects && typeof redirects === 'object').toBe(true)
+ expect(redirects?.allowHttp).toBe(false)
+ expect(redirects?.allowCrossOrigin).toBe(false)
+ expect(redirects?.allowPrivateAddresses).toBe(false)
+ expect(Array.isArray(redirects?.sameOriginOnly)).toBe(true)
+
+ const scopes = contract.oauthScopes
+ expect(Array.isArray(scopes) && (scopes as unknown[]).length > 0, 'oauthScopes required').toBe(
+ true
+ )
+ for (const scope of scopes as unknown[]) {
+ expect(typeof scope).toBe('string')
+ expect(String(scope).length).toBeGreaterThan(0)
+ }
+
+ const limits = contract.limits as Record<string, unknown> | undefined
+ expect(limits && typeof limits === 'object', 'limits object is required').toBe(true)
+ for (const key of REQUIRED_LIMIT_KEYS) {
+ assertFinitePositiveLimit(limits?.[key], `limits.${key}`)
+ }
+
+ const errors = contract.errorTaxonomy
+ expect(Array.isArray(errors) && (errors as unknown[]).length > 0).toBe(true)
+ for (const code of errors as unknown[]) {
+ expect(typeof code).toBe('string')
+ expect(String(code)).toMatch(/^[a-z][a-z0-9_]+$/)
+ }
+
+ const terms = contract.termsAndTestAccount as Record<string, unknown> | undefined
+ expect(terms && typeof terms === 'object').toBe(true)
+ expect(terms?.automationAuthorized).toBe(true)
+ expect(typeof terms?.approvedTestAccountFingerprint).toBe('string')
+ expect(String(terms?.approvedTestAccountFingerprint)).toMatch(/^redacted:/)
+ expect(typeof terms?.evidenceHash).toBe('string')
+ expect(String(terms?.evidenceHash)).toMatch(/^sha256:/)
+
+ const sensitive: string[] = []
+ collectSensitiveLeaves(contract, '', sensitive)
+ expect(sensitive, `fixture must not store secrets; found ${sensitive.join(', ')}`).toEqual([])
+
+ expect(architectureDoc).toContain(String(contract.protocolVersion))
+ expect(architectureDoc).toMatch(/codex-subscription/)
+ expect(architectureDoc).not.toMatch(/sk-[A-Za-z0-9]|Bearer [A-Za-z0-9._-]+/)
+ expect(validationDoc).toMatch(/T0|T1|T2/)
+ expect(validationDoc).toMatch(/CODEX_REAL_UPSTREAM_CONFIRM/)
+ })
+})