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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.jsonnew file mode 100644index 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.jsonindex 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.jsonindex 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.tsnew file mode 100644index 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/)+ })+})