Skip to content

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

TypeScript

feat(control-api): add Codex provider-attempt ledger

Alfredo Lopezfb76efd3aebd
diff --git a/control-api/src/db.ts b/control-api/src/db.ts
index 9f434cc49..abaaa770a 100644
--- a/control-api/src/db.ts
+++ b/control-api/src/db.ts
@@ -12,6 +12,10 @@ import {
applyGfsUploadFinalizingSchema,
applyGfsUploadSessionSchema,
} from './services/gfsUploadSchema.js'
+import {
+ applyLlmProviderAttemptSchema,
+ applyLlmProviderAttemptTicketSchema,
+} from './services/llmProviderAttemptStore.js'
import { applyMemberRegistrationCredentialsSchema } from './services/memberRegistrationCredentialsSchema.js'
import {
addPluginWorkloadSdkAttemptLedgerColumns,
@@ -5924,6 +5928,14 @@ export const CONTROL_API_MIGRATIONS: DbMigration[] = [
version: '00a1_codex_subscription_oauth_states',
apply: applyCodexSubscriptionOAuthStateSchema,
},
+ {
+ version: '00a2_llm_provider_attempts',
+ apply: applyLlmProviderAttemptSchema,
+ },
+ {
+ version: '00a3_llm_provider_attempt_tickets',
+ apply: applyLlmProviderAttemptTicketSchema,
+ },
{
version: '0100_seed_minimax_allowed_model',
apply: async db => {
diff --git a/control-api/src/services/llmProviderAttemptReceipt.ts b/control-api/src/services/llmProviderAttemptReceipt.ts
new file mode 100644
index 000000000..b2b6805a2
--- /dev/null
+++ b/control-api/src/services/llmProviderAttemptReceipt.ts
@@ -0,0 +1,16 @@
+import { createHash } from 'node:crypto'
+import { stableStringify } from '../utils/stableStringify.js'
+
+export const CODEX_ATTEMPT_RECEIPT_SCHEMA_VERSION = 'codex-attempt-receipt.v1' as const
+
+export type CodexAttemptReceiptV1 = {
+ schemaVersion: typeof CODEX_ATTEMPT_RECEIPT_SCHEMA_VERSION
+ providerAttemptId: string
+ requestHash: string
+ outcome: 'success' | 'canceled' | 'error' | 'unknown'
+ usage?: { inputTokens?: number; outputTokens?: number }
+}
+
+export function hashCodexAttemptReceipt(receipt: CodexAttemptReceiptV1): string {
+ return createHash('sha256').update(stableStringify(receipt)).digest('hex')
+}
diff --git a/control-api/src/services/llmProviderAttemptStore.ts b/control-api/src/services/llmProviderAttemptStore.ts
new file mode 100644
index 000000000..9c0a3fadb
--- /dev/null
+++ b/control-api/src/services/llmProviderAttemptStore.ts
@@ -0,0 +1,168 @@
+import type { DbClient } from '../db.js'
+
+export const LLM_PROVIDER_ATTEMPT_PROVIDER = 'codex-subscription' as const
+
+export type LlmProviderAttemptStatus = 'authorized' | 'redeemed' | 'finalized'
+export type LlmProviderAttemptTicketStatus = 'issued' | 'redeemed' | 'finalized'
+export type LlmProviderAttemptOutcome = 'success' | 'canceled' | 'error' | 'unknown'
+
+export type LlmProviderAttemptInsert = {
+ callerKind: 'host' | 'recipe'
+ hostRef: string
+ recipeNamespace?: string | null
+ recipeName?: string | null
+ invocationId: string
+ attemptGeneration: number
+ providerAttemptIndex: number
+ model: string
+ requestHash: string
+ policyRevision: number
+ policyHash: string
+ budgetReservationId: string
+ connectionRevision: number
+ correlationId?: string | null
+}
+
+export type LlmProviderAttemptRow = LlmProviderAttemptInsert & {
+ id: string
+ provider: typeof LLM_PROVIDER_ATTEMPT_PROVIDER
+ status: LlmProviderAttemptStatus
+ outcome: LlmProviderAttemptOutcome | null
+ createdAt: Date
+}
+
+export async function applyLlmProviderAttemptSchema(db: DbClient): Promise<void> {
+ await db.query(`
+ CREATE TABLE IF NOT EXISTS llm_provider_attempts (
+ id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+ caller_kind TEXT NOT NULL CHECK (caller_kind IN ('host', 'recipe')),
+ host_ref TEXT NOT NULL,
+ recipe_namespace TEXT,
+ recipe_name TEXT,
+ invocation_id TEXT NOT NULL,
+ attempt_generation INTEGER NOT NULL CHECK (attempt_generation >= 1),
+ provider_attempt_index INTEGER NOT NULL CHECK (provider_attempt_index >= 1),
+ provider TEXT NOT NULL CHECK (provider = 'codex-subscription'),
+ model TEXT NOT NULL,
+ request_hash TEXT NOT NULL,
+ policy_revision BIGINT NOT NULL,
+ policy_hash TEXT NOT NULL,
+ budget_reservation_id TEXT NOT NULL,
+ connection_revision BIGINT NOT NULL,
+ status TEXT NOT NULL CHECK (status IN ('authorized', 'redeemed', 'finalized')),
+ outcome TEXT CHECK (outcome IN ('success', 'canceled', 'error', 'unknown')),
+ usage_input_tokens INTEGER,
+ usage_output_tokens INTEGER,
+ correlation_id TEXT,
+ created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+ finalized_at TIMESTAMPTZ,
+ CONSTRAINT llm_provider_attempts_invocation_unique
+ UNIQUE (invocation_id, attempt_generation, provider_attempt_index),
+ CONSTRAINT llm_provider_attempts_recipe_binding CHECK (
+ (caller_kind = 'host' AND recipe_namespace IS NULL AND recipe_name IS NULL)
+ OR (
+ caller_kind = 'recipe'
+ AND recipe_namespace IS NOT NULL
+ AND recipe_name IS NOT NULL
+ )
+ )
+ );
+
+ REVOKE ALL PRIVILEGES ON TABLE llm_provider_attempts FROM PUBLIC;
+ REVOKE ALL PRIVILEGES ON TABLE llm_provider_attempts
+ FROM trace_maintenance_runtime, workflow_recipes_runtime;
+ GRANT SELECT, INSERT, UPDATE ON TABLE llm_provider_attempts TO control_api_runtime;
+ REVOKE DELETE, TRUNCATE, REFERENCES, TRIGGER ON TABLE llm_provider_attempts FROM control_api_runtime;
+ `)
+}
+
+export async function applyLlmProviderAttemptTicketSchema(db: DbClient): Promise<void> {
+ await db.query(`
+ CREATE TABLE IF NOT EXISTS llm_provider_attempt_tickets (
+ jti UUID PRIMARY KEY,
+ provider_attempt_id UUID NOT NULL REFERENCES llm_provider_attempts(id),
+ status TEXT NOT NULL CHECK (status IN ('issued', 'redeemed', 'finalized')),
+ expires_at TIMESTAMPTZ NOT NULL,
+ redeemed_at TIMESTAMPTZ,
+ finalized_at TIMESTAMPTZ,
+ receipt_hash TEXT,
+ created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+ );
+
+ REVOKE ALL PRIVILEGES ON TABLE llm_provider_attempt_tickets FROM PUBLIC;
+ REVOKE ALL PRIVILEGES ON TABLE llm_provider_attempt_tickets
+ FROM trace_maintenance_runtime, workflow_recipes_runtime;
+ GRANT SELECT, INSERT, UPDATE ON TABLE llm_provider_attempt_tickets TO control_api_runtime;
+ REVOKE DELETE, TRUNCATE, REFERENCES, TRIGGER ON TABLE llm_provider_attempt_tickets FROM control_api_runtime;
+ `)
+}
+
+export async function insertLlmProviderAttempt(
+ db: DbClient,
+ input: LlmProviderAttemptInsert
+): Promise<LlmProviderAttemptRow> {
+ const result = await db.query(
+ `INSERT INTO llm_provider_attempts (
+ caller_kind, host_ref, recipe_namespace, recipe_name, invocation_id,
+ attempt_generation, provider_attempt_index, provider, model, request_hash,
+ policy_revision, policy_hash, budget_reservation_id, connection_revision,
+ status, correlation_id
+ ) VALUES (
+ $1, $2, $3, $4, $5, $6, $7, 'codex-subscription', $8, $9, $10, $11, $12, $13,
+ 'authorized', $14
+ )
+ RETURNING id, caller_kind, host_ref, recipe_namespace, recipe_name, invocation_id,
+ attempt_generation, provider_attempt_index, provider, model, request_hash,
+ policy_revision, policy_hash, budget_reservation_id, connection_revision,
+ status, outcome, created_at`,
+ [
+ input.callerKind,
+ input.hostRef,
+ input.recipeNamespace ?? null,
+ input.recipeName ?? null,
+ input.invocationId,
+ input.attemptGeneration,
+ input.providerAttemptIndex,
+ input.model,
+ input.requestHash,
+ input.policyRevision,
+ input.policyHash,
+ input.budgetReservationId,
+ input.connectionRevision,
+ input.correlationId ?? null,
+ ]
+ )
+ const row = result.rows[0] as Record<string, unknown>
+ return {
+ id: String(row.id),
+ callerKind: row.caller_kind as 'host' | 'recipe',
+ hostRef: String(row.host_ref),
+ recipeNamespace: (row.recipe_namespace as string | null) ?? null,
+ recipeName: (row.recipe_name as string | null) ?? null,
+ invocationId: String(row.invocation_id),
+ attemptGeneration: Number(row.attempt_generation),
+ providerAttemptIndex: Number(row.provider_attempt_index),
+ provider: LLM_PROVIDER_ATTEMPT_PROVIDER,
+ model: String(row.model),
+ requestHash: String(row.request_hash),
+ policyRevision: Number(row.policy_revision),
+ policyHash: String(row.policy_hash),
+ budgetReservationId: String(row.budget_reservation_id),
+ connectionRevision: Number(row.connection_revision),
+ status: row.status as LlmProviderAttemptStatus,
+ outcome: (row.outcome as LlmProviderAttemptOutcome | null) ?? null,
+ createdAt: row.created_at instanceof Date ? row.created_at : new Date(String(row.created_at)),
+ }
+}
+
+export async function registerLlmProviderAttemptTicket(
+ db: DbClient,
+ input: { jti: string; providerAttemptId: string; expiresAt: Date }
+): Promise<void> {
+ await db.query(
+ `INSERT INTO llm_provider_attempt_tickets (
+ jti, provider_attempt_id, status, expires_at
+ ) VALUES ($1, $2, 'issued', $3)`,
+ [input.jti, input.providerAttemptId, input.expiresAt]
+ )
+}
diff --git a/control-api/src/services/llmProviderAttemptTicket.ts b/control-api/src/services/llmProviderAttemptTicket.ts
new file mode 100644
index 000000000..61dc232bc
--- /dev/null
+++ b/control-api/src/services/llmProviderAttemptTicket.ts
@@ -0,0 +1,95 @@
+import jwt from 'jsonwebtoken'
+import { createPublicKey, randomUUID } from 'node:crypto'
+import { config } from '../config.js'
+import type { DbClient } from '../db.js'
+import { registerLlmProviderAttemptTicket } from './llmProviderAttemptStore.js'
+
+export const CODEX_EXECUTION_TICKET_TYP = 'codex-execution-ticket' as const
+export const CODEX_EXECUTION_TICKET_AUDIENCE = 'codex-llm-proxy'
+export const CODEX_EXECUTION_TICKET_TTL_SECONDS = 60
+
+export type CodexExecutionTicketClaims = {
+ jti: string
+ typ: typeof CODEX_EXECUTION_TICKET_TYP
+ sub: string
+ hostRef: string
+ recipeNamespace?: string
+ recipeName?: string
+ invocationId: string
+ attemptGeneration: number
+ providerAttemptId: string
+ providerAttemptIndex: number
+ provider: 'codex-subscription'
+ model: string
+ requestHash: string
+ policyRevision: number
+ policyHash: string
+ budgetReservationId: string
+ connectionRevision: number
+}
+
+export type IssuedCodexExecutionTicket = {
+ executionTicket: string
+ claims: CodexExecutionTicketClaims
+ expiresAt: Date
+}
+
+export async function issueRegisteredCodexExecutionTicket(
+ db: DbClient,
+ input: Omit<CodexExecutionTicketClaims, 'jti' | 'typ' | 'provider'>
+): Promise<IssuedCodexExecutionTicket> {
+ const jti = randomUUID()
+ const expiresAt = new Date(Date.now() + CODEX_EXECUTION_TICKET_TTL_SECONDS * 1000)
+ await registerLlmProviderAttemptTicket(db, {
+ jti,
+ providerAttemptId: input.providerAttemptId,
+ expiresAt,
+ })
+ const claims: CodexExecutionTicketClaims = {
+ ...input,
+ jti,
+ typ: CODEX_EXECUTION_TICKET_TYP,
+ provider: 'codex-subscription',
+ }
+ const executionTicket = jwt.sign(claims, config.adminJwtPrivateKey, {
+ algorithm: 'RS256',
+ issuer: config.adminJwtIssuer,
+ audience: CODEX_EXECUTION_TICKET_AUDIENCE,
+ expiresIn: CODEX_EXECUTION_TICKET_TTL_SECONDS,
+ })
+ return { executionTicket, claims, expiresAt }
+}
+
+export function verifyCodexExecutionTicket(ticket: string): CodexExecutionTicketClaims | null {
+ try {
+ const publicKey = createPublicKey(config.adminJwtPrivateKey).export({
+ type: 'spki',
+ format: 'pem',
+ })
+ const verified = jwt.verify(ticket, publicKey, {
+ algorithms: ['RS256'],
+ issuer: config.adminJwtIssuer,
+ audience: CODEX_EXECUTION_TICKET_AUDIENCE,
+ })
+ if (typeof verified !== 'object' || verified === null) return null
+ const claims = verified as jwt.JwtPayload
+ if (
+ typeof claims.jti !== 'string' ||
+ claims.typ !== CODEX_EXECUTION_TICKET_TYP ||
+ claims.provider !== 'codex-subscription' ||
+ typeof claims.sub !== 'string' ||
+ typeof claims.hostRef !== 'string' ||
+ typeof claims.invocationId !== 'string' ||
+ typeof claims.providerAttemptId !== 'string' ||
+ typeof claims.model !== 'string' ||
+ typeof claims.requestHash !== 'string' ||
+ typeof claims.policyHash !== 'string' ||
+ typeof claims.budgetReservationId !== 'string'
+ ) {
+ return null
+ }
+ return claims as unknown as CodexExecutionTicketClaims
+ } catch {
+ return null
+ }
+}
diff --git a/control-api/test/db.llmProviderAttemptMigration.test.ts b/control-api/test/db.llmProviderAttemptMigration.test.ts
new file mode 100644
index 000000000..925b29b0a
--- /dev/null
+++ b/control-api/test/db.llmProviderAttemptMigration.test.ts
@@ -0,0 +1,128 @@
+import { describe, expect, it } from 'vitest'
+import { readFileSync } from 'node:fs'
+
+function runtimeAccessProfile(): Map<string, string> {
+ const source = readFileSync(
+ new URL('../../deploy/scripts/control-api-runtime-access-profiles.tsv', import.meta.url),
+ 'utf8'
+ )
+ return new Map(
+ source
+ .split('\n')
+ .filter(line => line && !line.startsWith('#'))
+ .map(line => line.split('\t') as [string, string])
+ )
+}
+
+describe('00a2/00a3 LLM provider-attempt ledger', () => {
+ const dbSource = readFileSync(new URL('../src/db.ts', import.meta.url), 'utf8')
+ const storeSource = readFileSync(
+ new URL('../src/services/llmProviderAttemptStore.ts', import.meta.url),
+ 'utf8'
+ )
+ const ticketSource = readFileSync(
+ new URL('../src/services/llmProviderAttemptTicket.ts', import.meta.url),
+ 'utf8'
+ )
+ const receiptSource = readFileSync(
+ new URL('../src/services/llmProviderAttemptReceipt.ts', import.meta.url),
+ 'utf8'
+ )
+
+ it('registers additive migrations after the Codex OAuth state version', () => {
+ expect(dbSource).toContain("version: '00a1_codex_subscription_oauth_states'")
+ expect(dbSource).toContain("version: '00a2_llm_provider_attempts'")
+ expect(dbSource).toContain("version: '00a3_llm_provider_attempt_tickets'")
+ expect(dbSource).toContain('apply: applyLlmProviderAttemptSchema')
+ expect(dbSource).toContain('apply: applyLlmProviderAttemptTicketSchema')
+ expect(dbSource.indexOf("version: '00a1_codex_subscription_oauth_states'")).toBeLessThan(
+ dbSource.indexOf("version: '00a2_llm_provider_attempts'")
+ )
+ expect(dbSource.indexOf("version: '00a2_llm_provider_attempts'")).toBeLessThan(
+ dbSource.indexOf("version: '00a3_llm_provider_attempt_tickets'")
+ )
+ })
+
+ it('persists immutable attempt bindings, lifecycle, safe usage, and redacted correlation', () => {
+ expect(storeSource).toContain('CREATE TABLE IF NOT EXISTS llm_provider_attempts')
+ expect(storeSource).toContain(
+ "caller_kind TEXT NOT NULL CHECK (caller_kind IN ('host', 'recipe'))"
+ )
+ expect(storeSource).toContain('host_ref TEXT NOT NULL')
+ expect(storeSource).toContain('recipe_namespace TEXT')
+ expect(storeSource).toContain('recipe_name TEXT')
+ expect(storeSource).toContain("provider TEXT NOT NULL CHECK (provider = 'codex-subscription')")
+ expect(storeSource).toContain('model TEXT NOT NULL')
+ expect(storeSource).toContain('request_hash TEXT NOT NULL')
+ expect(storeSource).toContain('policy_revision BIGINT NOT NULL')
+ expect(storeSource).toContain('policy_hash TEXT NOT NULL')
+ expect(storeSource).toContain('budget_reservation_id TEXT NOT NULL')
+ expect(storeSource).toContain('connection_revision BIGINT NOT NULL')
+ expect(storeSource).toContain(
+ "status TEXT NOT NULL CHECK (status IN ('authorized', 'redeemed', 'finalized'))"
+ )
+ expect(storeSource).toContain(
+ "outcome TEXT CHECK (outcome IN ('success', 'canceled', 'error', 'unknown'))"
+ )
+ expect(storeSource).toContain('usage_input_tokens INTEGER')
+ expect(storeSource).toContain('usage_output_tokens INTEGER')
+ expect(storeSource).toContain('correlation_id TEXT')
+ expect(storeSource).toContain(
+ 'UNIQUE (invocation_id, attempt_generation, provider_attempt_index)'
+ )
+ expect(storeSource).not.toMatch(/DROP\s+(TABLE|COLUMN)/i)
+ expect(storeSource).not.toMatch(/\bprompt\b/i)
+ expect(storeSource).not.toMatch(/\bcompletion\b/i)
+ expect(storeSource).not.toMatch(/\baccess_token\b/i)
+ expect(storeSource).not.toMatch(/\brefresh_token\b/i)
+ expect(storeSource).not.toMatch(/\bauthorization\b/i)
+ expect(storeSource).not.toMatch(/cookie/i)
+ expect(storeSource).not.toMatch(/\bexecution_ticket\b/i)
+ expect(storeSource).not.toMatch(/\bheader\b/i)
+ })
+
+ it('persists unique jti tickets with issued/redeemed/finalized states and receipt hash', () => {
+ expect(storeSource).toContain('CREATE TABLE IF NOT EXISTS llm_provider_attempt_tickets')
+ expect(storeSource).toContain('jti UUID PRIMARY KEY')
+ expect(storeSource).toContain(
+ "status TEXT NOT NULL CHECK (status IN ('issued', 'redeemed', 'finalized'))"
+ )
+ expect(storeSource).toContain('expires_at TIMESTAMPTZ NOT NULL')
+ expect(storeSource).toContain('receipt_hash TEXT')
+ expect(storeSource).toContain('status, expires_at')
+ expect(ticketSource).toContain("'codex-execution-ticket'")
+ expect(ticketSource).toContain('audience: CODEX_EXECUTION_TICKET_AUDIENCE')
+ expect(ticketSource).toContain('registerLlmProviderAttemptTicket')
+ expect(ticketSource.indexOf('registerLlmProviderAttemptTicket')).toBeLessThan(
+ ticketSource.indexOf('jwt.sign')
+ )
+ expect(receiptSource).toContain("'codex-attempt-receipt.v1'")
+ expect(storeSource).not.toMatch(/\bexecution_ticket\b/i)
+ expect(storeSource).not.toMatch(/\baccess_token\b/i)
+ expect(storeSource).not.toMatch(/\bprompt\b/i)
+ })
+
+ it('grants Control API runtime SELECT/INSERT/UPDATE only and never creates a proxy role', () => {
+ expect(storeSource).toContain(
+ 'GRANT SELECT, INSERT, UPDATE ON TABLE llm_provider_attempts TO control_api_runtime'
+ )
+ expect(storeSource).toContain(
+ 'GRANT SELECT, INSERT, UPDATE ON TABLE llm_provider_attempt_tickets TO control_api_runtime'
+ )
+ expect(storeSource).toContain(
+ 'REVOKE DELETE, TRUNCATE, REFERENCES, TRIGGER ON TABLE llm_provider_attempts FROM control_api_runtime'
+ )
+ expect(storeSource).toContain(
+ 'REVOKE DELETE, TRUNCATE, REFERENCES, TRIGGER ON TABLE llm_provider_attempt_tickets FROM control_api_runtime'
+ )
+ expect(storeSource).not.toMatch(/CREATE ROLE/i)
+ expect(storeSource).not.toMatch(/codex.llm.proxy/i)
+ expect(storeSource).not.toMatch(/GRANT .* TO .*proxy/i)
+ })
+
+ it('classifies the new relations as upsert in the runtime access contract', () => {
+ const profile = runtimeAccessProfile()
+ expect(profile.get('llm_provider_attempts')).toBe('upsert')
+ expect(profile.get('llm_provider_attempt_tickets')).toBe('upsert')
+ })
+})
diff --git a/control-api/test/db.realPostgresMigration.integration.test.ts b/control-api/test/db.realPostgresMigration.integration.test.ts
index dc91bc517..90ae00da8 100644
--- a/control-api/test/db.realPostgresMigration.integration.test.ts
+++ b/control-api/test/db.realPostgresMigration.integration.test.ts
@@ -331,6 +331,8 @@ describeRealPostgres('control-api real Postgres migrations', () => {
'llm_allowed_models',
'llm_allowed_models_audit',
'llm_catalog_sync_runs',
+ 'llm_provider_attempt_tickets',
+ 'llm_provider_attempts',
'codex_subscription_connections',
'codex_subscription_oauth_states',
'notification_deliveries',
@@ -356,6 +358,8 @@ describeRealPostgres('control-api real Postgres migrations', () => {
'llm_allowed_models',
'llm_allowed_models_audit',
'llm_catalog_sync_runs',
+ 'llm_provider_attempt_tickets',
+ 'llm_provider_attempts',
'notification_deliveries',
'workflow_approval_requests',
'workflow_run_steps',
@@ -448,6 +452,8 @@ describeRealPostgres('control-api real Postgres migrations', () => {
'llm_allowed_models',
'llm_allowed_models_audit',
'llm_catalog_sync_runs',
+ 'llm_provider_attempt_tickets',
+ 'llm_provider_attempts',
'codex_subscription_connections',
'codex_subscription_oauth_states',
'gfs_desktop_operator_links',
@@ -468,6 +474,8 @@ describeRealPostgres('control-api real Postgres migrations', () => {
llm_allowed_models: ['DELETE', 'INSERT', 'SELECT', 'UPDATE'],
llm_allowed_models_audit: ['INSERT', 'SELECT'],
llm_catalog_sync_runs: ['INSERT', 'SELECT'],
+ llm_provider_attempt_tickets: ['INSERT', 'SELECT', 'UPDATE'],
+ llm_provider_attempts: ['INSERT', 'SELECT', 'UPDATE'],
codex_subscription_connections: ['INSERT', 'SELECT', 'UPDATE'],
codex_subscription_oauth_states: ['INSERT', 'SELECT', 'UPDATE'],
gfs_desktop_operator_links: ['INSERT', 'SELECT', 'UPDATE'],
diff --git a/control-api/test/services.llmProviderAttemptStore.realPostgres.integration.test.ts b/control-api/test/services.llmProviderAttemptStore.realPostgres.integration.test.ts
new file mode 100644
index 000000000..1eef4a599
--- /dev/null
+++ b/control-api/test/services.llmProviderAttemptStore.realPostgres.integration.test.ts
@@ -0,0 +1,166 @@
+import { afterAll, beforeAll, describe, expect, it } from 'vitest'
+import { randomBytes, randomUUID } from 'node:crypto'
+import { Pool } from 'pg'
+import { initDb } from '../src/db.js'
+import {
+ type LlmProviderAttemptInsert,
+ insertLlmProviderAttempt,
+ registerLlmProviderAttemptTicket,
+} from '../src/services/llmProviderAttemptStore.js'
+import { issueRegisteredCodexExecutionTicket } from '../src/services/llmProviderAttemptTicket.js'
+
+const adminUrl = process.env.CONTROL_API_REAL_PG_ADMIN_URL
+const describeRealPostgres = adminUrl ? describe : describe.skip
+
+function databaseUrl(baseUrl: string, database: string): string {
+ const url = new URL(baseUrl)
+ url.pathname = `/${database}`
+ return url.toString()
+}
+
+function quoteIdent(value: string): string {
+ return `"${value.replace(/"/g, '""')}"`
+}
+
+function attemptInput(overrides: Partial<LlmProviderAttemptInsert> = {}): LlmProviderAttemptInsert {
+ return {
+ callerKind: 'recipe',
+ hostRef: 'research-host',
+ recipeNamespace: 'sandbox-recipes',
+ recipeName: 'prompt-notify',
+ invocationId: `invocation-${randomUUID()}`,
+ attemptGeneration: 1,
+ providerAttemptIndex: 1,
+ model: 'gpt-5.4',
+ requestHash: 'c'.repeat(64),
+ policyRevision: 7,
+ policyHash: 'policy-hash',
+ budgetReservationId: 'reservation-1',
+ connectionRevision: 3,
+ ...overrides,
+ }
+}
+
+describeRealPostgres('LLM provider-attempt ledger on real PostgreSQL', () => {
+ const database = `llm_provider_attempt_${randomBytes(6).toString('hex')}`
+ const connectionString = databaseUrl(
+ adminUrl ?? 'postgresql://[email protected]/postgres',
+ database
+ )
+ let adminPool: Pool
+ let pool: Pool
+
+ beforeAll(async () => {
+ adminPool = new Pool({ connectionString: adminUrl })
+ await adminPool.query(`CREATE DATABASE ${quoteIdent(database)}`)
+ pool = new Pool({ connectionString })
+ await initDb({ connect: () => pool.connect() })
+ }, 60_000)
+
+ afterAll(async () => {
+ await pool?.end()
+ if (adminPool) {
+ await adminPool
+ .query(`DROP DATABASE IF EXISTS ${quoteIdent(database)}`)
+ .catch(() => undefined)
+ await adminPool.end()
+ }
+ })
+
+ it('creates the attempt and ticket tables without raw prompt, token, or ticket columns', async () => {
+ const tables = await pool.query<{ table_name: string }>(
+ `SELECT table_name
+ FROM information_schema.tables
+ WHERE table_schema = 'public'
+ AND table_name = ANY($1::text[])
+ ORDER BY table_name`,
+ [['llm_provider_attempt_tickets', 'llm_provider_attempts']]
+ )
+ expect(tables.rows.map(row => row.table_name)).toEqual([
+ 'llm_provider_attempt_tickets',
+ 'llm_provider_attempts',
+ ])
+
+ const columns = await pool.query<{ column_name: string }>(
+ `SELECT column_name
+ FROM information_schema.columns
+ WHERE table_schema = 'public'
+ AND table_name = ANY($1::text[])`,
+ [['llm_provider_attempt_tickets', 'llm_provider_attempts']]
+ )
+ const names = columns.rows.map(row => row.column_name)
+ expect(names).toEqual(
+ expect.arrayContaining(['host_ref', 'request_hash', 'jti', 'receipt_hash'])
+ )
+ expect(names.join(',')).not.toMatch(
+ /prompt|completion|access_token|refresh_token|execution_ticket|authorization|cookie|header/i
+ )
+ })
+
+ it('keeps attempt bindings immutable and rejects a duplicate invocation winner', async () => {
+ const input = attemptInput({ invocationId: 'shared-invocation' })
+ const first = await insertLlmProviderAttempt(pool, input)
+ await expect(insertLlmProviderAttempt(pool, input)).rejects.toThrow(/duplicate|unique/i)
+
+ const [winner, loser] = await Promise.allSettled([
+ insertLlmProviderAttempt(pool, { ...input, providerAttemptIndex: 2 }),
+ insertLlmProviderAttempt(pool, { ...input, providerAttemptIndex: 2 }),
+ ])
+ const fulfilled = [winner, loser].filter(result => result.status === 'fulfilled')
+ const rejected = [winner, loser].filter(result => result.status === 'rejected')
+ expect(fulfilled).toHaveLength(1)
+ expect(rejected).toHaveLength(1)
+
+ const stored = await pool.query<{ model: string; request_hash: string }>(
+ `SELECT model, request_hash FROM llm_provider_attempts WHERE id = $1`,
+ [first.id]
+ )
+ expect(stored.rows[0]).toEqual({ model: 'gpt-5.4', request_hash: 'c'.repeat(64) })
+ })
+
+ it('registers jti before returning the JWT and lets only one concurrent jti win', async () => {
+ const attempt = await insertLlmProviderAttempt(pool, attemptInput())
+ const issued = await issueRegisteredCodexExecutionTicket(pool, {
+ sub: 'host/research-host',
+ hostRef: attempt.hostRef,
+ recipeNamespace: attempt.recipeNamespace ?? undefined,
+ recipeName: attempt.recipeName ?? undefined,
+ invocationId: attempt.invocationId,
+ attemptGeneration: attempt.attemptGeneration,
+ providerAttemptId: attempt.id,
+ providerAttemptIndex: attempt.providerAttemptIndex,
+ model: attempt.model,
+ requestHash: attempt.requestHash,
+ policyRevision: attempt.policyRevision,
+ policyHash: attempt.policyHash,
+ budgetReservationId: attempt.budgetReservationId,
+ connectionRevision: attempt.connectionRevision,
+ })
+
+ const ticketRow = await pool.query<{ jti: string; status: string; execution_ticket?: string }>(
+ `SELECT jti::text, status FROM llm_provider_attempt_tickets WHERE jti = $1`,
+ [issued.claims.jti]
+ )
+ expect(ticketRow.rows).toEqual([{ jti: issued.claims.jti, status: 'issued' }])
+ expect(JSON.stringify(ticketRow.rows[0])).not.toContain(issued.executionTicket)
+
+ const duplicateJti = randomUUID()
+ const expiresAt = new Date(Date.now() + 60_000)
+ const [firstJti, secondJti] = await Promise.allSettled([
+ registerLlmProviderAttemptTicket(pool, {
+ jti: duplicateJti,
+ providerAttemptId: attempt.id,
+ expiresAt,
+ }),
+ registerLlmProviderAttemptTicket(pool, {
+ jti: duplicateJti,
+ providerAttemptId: attempt.id,
+ expiresAt,
+ }),
+ ])
+ const jtiWins = [firstJti, secondJti].filter(result => result.status === 'fulfilled')
+ const jtiLosses = [firstJti, secondJti].filter(result => result.status === 'rejected')
+ expect(jtiWins).toHaveLength(1)
+ expect(jtiLosses).toHaveLength(1)
+ })
+})
diff --git a/control-api/test/services.llmProviderAttemptTicket.test.ts b/control-api/test/services.llmProviderAttemptTicket.test.ts
new file mode 100644
index 000000000..2f95b6a34
--- /dev/null
+++ b/control-api/test/services.llmProviderAttemptTicket.test.ts
@@ -0,0 +1,117 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import jwt from 'jsonwebtoken'
+import { createPublicKey, randomUUID } from 'node:crypto'
+import { config } from '../src/config.js'
+import { hashCodexAttemptReceipt } from '../src/services/llmProviderAttemptReceipt.js'
+import {
+ CODEX_EXECUTION_TICKET_AUDIENCE,
+ CODEX_EXECUTION_TICKET_TTL_SECONDS,
+ issueRegisteredCodexExecutionTicket,
+ verifyCodexExecutionTicket,
+} from '../src/services/llmProviderAttemptTicket.js'
+
+const binding = {
+ sub: 'host/research-host',
+ hostRef: 'research-host',
+ recipeNamespace: 'sandbox-recipes',
+ recipeName: 'prompt-notify',
+ invocationId: 'invocation-1',
+ attemptGeneration: 1,
+ providerAttemptId: '33333333-3333-4333-8333-333333333333',
+ providerAttemptIndex: 1,
+ model: 'gpt-5.4',
+ requestHash: 'a'.repeat(64),
+ policyRevision: 7,
+ policyHash: 'policy-hash',
+ budgetReservationId: 'reservation-1',
+ connectionRevision: 3,
+}
+
+function memoryDb(events: string[]) {
+ return {
+ query: async () => {
+ events.push('register')
+ return { rows: [] }
+ },
+ }
+}
+
+describe('Codex execution ticket', () => {
+ afterEach(() => {
+ vi.useRealTimers()
+ })
+
+ it('registers jti before returning an RS256 ticket bound to the authorized attempt', async () => {
+ const events: string[] = []
+ const issued = await issueRegisteredCodexExecutionTicket(memoryDb(events), binding)
+ events.push('returned')
+ expect(events).toEqual(['register', 'returned'])
+
+ const publicKey = createPublicKey(config.adminJwtPrivateKey).export({
+ type: 'spki',
+ format: 'pem',
+ })
+ const header = jwt.decode(issued.executionTicket, { complete: true })?.header
+ expect(header).toMatchObject({ alg: 'RS256', typ: 'JWT' })
+ const claims = jwt.verify(issued.executionTicket, publicKey, {
+ algorithms: ['RS256'],
+ issuer: config.adminJwtIssuer,
+ audience: CODEX_EXECUTION_TICKET_AUDIENCE,
+ }) as jwt.JwtPayload
+ expect(claims).toMatchObject({
+ ...binding,
+ typ: 'codex-execution-ticket',
+ provider: 'codex-subscription',
+ aud: CODEX_EXECUTION_TICKET_AUDIENCE,
+ })
+ expect(claims.jti).toBe(issued.claims.jti)
+ expect(typeof claims.jti).toBe('string')
+ expect(claims.exp! - claims.iat!).toBe(CODEX_EXECUTION_TICKET_TTL_SECONDS)
+ expect(JSON.stringify(claims)).not.toContain('sk-')
+ expect(JSON.stringify(claims)).not.toContain('refresh')
+ expect(JSON.stringify(claims)).not.toContain('Authorization')
+ })
+
+ it('expires after 60 seconds so a captured ticket cannot be reused later', async () => {
+ vi.useFakeTimers()
+ vi.setSystemTime(new Date('2026-08-20T12:00:00.000Z'))
+ const issued = await issueRegisteredCodexExecutionTicket(memoryDb([]), binding)
+ expect(verifyCodexExecutionTicket(issued.executionTicket)).not.toBeNull()
+ vi.advanceTimersByTime(60_001)
+ expect(verifyCodexExecutionTicket(issued.executionTicket)).toBeNull()
+ })
+
+ it('reissues a fresh jti without changing the attempt binding', async () => {
+ const original = await issueRegisteredCodexExecutionTicket(memoryDb([]), binding)
+ const reissued = await issueRegisteredCodexExecutionTicket(memoryDb([]), binding)
+ expect(reissued.claims.jti).not.toBe(original.claims.jti)
+ expect(reissued.claims).toMatchObject({
+ invocationId: original.claims.invocationId,
+ providerAttemptId: original.claims.providerAttemptId,
+ requestHash: original.claims.requestHash,
+ policyHash: original.claims.policyHash,
+ })
+ })
+
+ it('hashes a receipt without including prompt, completion, or token material', () => {
+ const receipt = {
+ schemaVersion: 'codex-attempt-receipt.v1' as const,
+ providerAttemptId: randomUUID(),
+ requestHash: 'b'.repeat(64),
+ outcome: 'success' as const,
+ usage: { inputTokens: 12, outputTokens: 4 },
+ }
+ const hash = hashCodexAttemptReceipt(receipt)
+ expect(hash).toMatch(/^[a-f0-9]{64}$/)
+ expect(hash).toBe(
+ hashCodexAttemptReceipt({
+ usage: { outputTokens: 4, inputTokens: 12 },
+ outcome: 'success',
+ requestHash: receipt.requestHash,
+ providerAttemptId: receipt.providerAttemptId,
+ schemaVersion: 'codex-attempt-receipt.v1',
+ })
+ )
+ expect(hash).not.toContain('prompt')
+ })
+})
diff --git a/deploy/scripts/control-api-runtime-access-profiles.tsv b/deploy/scripts/control-api-runtime-access-profiles.tsv
index beeb99c1b..2217662cc 100644
--- a/deploy/scripts/control-api-runtime-access-profiles.tsv
+++ b/deploy/scripts/control-api-runtime-access-profiles.tsv
@@ -35,6 +35,8 @@ llm_allowed_models legacy_dml
llm_allowed_models_audit append
llm_catalog_sync_runs append
llm_model_prices legacy_dml
+llm_provider_attempt_tickets upsert
+llm_provider_attempts upsert
member_registration_credentials upsert
notification_deliveries legacy_dml
oauth_grants legacy_dml
diff --git a/scripts/tests/test-control-api-runtime-access-contract.sh b/scripts/tests/test-control-api-runtime-access-contract.sh
index f7c6a23d8..89dfb3238 100755
--- a/scripts/tests/test-control-api-runtime-access-contract.sh
+++ b/scripts/tests/test-control-api-runtime-access-contract.sh
@@ -9,7 +9,7 @@ relation_count="$(awk -F '\t' '!/^[[:space:]]*(#|$)/ { count++ } END { print cou
duplicate_count="$(awk -F '\t' '!/^[[:space:]]*(#|$)/ { seen[$1]++ } END { for (name in seen) if (seen[name] > 1) count++ } END { print count + 0 }' "$PROFILE_FILE")"
invalid_count="$(awk -F '\t' '!/^[[:space:]]*(#|$)/ && (NF != 2 || $1 !~ /^[a-z][a-z0-9_]*$/ || $2 !~ /^(legacy_dml|upsert|append|read|link_lifecycle|none)$/) { count++ } END { print count + 0 }' "$PROFILE_FILE")"
-[[ "$relation_count" == "86" ]]
+[[ "$relation_count" == "88" ]]
[[ "$duplicate_count" == "0" ]]
[[ "$invalid_count" == "0" ]]
grep -qx $'gfs_desktop_operator_links\tlink_lifecycle' "$PROFILE_FILE"
diff --git a/scripts/tests/test-gcp-scripts.sh b/scripts/tests/test-gcp-scripts.sh
index befd6cf48..2aa971418 100755
--- a/scripts/tests/test-gcp-scripts.sh
+++ b/scripts/tests/test-gcp-scripts.sh
@@ -1466,7 +1466,7 @@ assert_control_api_runtime_access_contract_is_exact() {
sequence_duplicate_count="$(awk -F '\t' '!/^[[:space:]]*(#|$)/ { seen[$1]++ } END { for (name in seen) if (seen[name] > 1) count++ } END { print count + 0 }' "$sequence_profile_file")"
sequence_invalid_count="$(awk -F '\t' '!/^[[:space:]]*(#|$)/ && (NF != 2 || $1 !~ /^[a-z][a-z0-9_]*$/ || $2 !~ /^(legacy_rw|consume)$/) { count++ } END { print count + 0 }' "$sequence_profile_file")"
- if [[ "$relation_count" == "86" && "$duplicate_count" == "0" && "$invalid_count" == "0" ]] && \
+ if [[ "$relation_count" == "88" && "$duplicate_count" == "0" && "$invalid_count" == "0" ]] && \
grep -qx $'gfs_upload_parts\tnone' "$profile_file" && \
grep -qx $'gfs_upload_sessions\tnone' "$profile_file" && \
grep -qx $'llm_allowed_models\tlegacy_dml' "$profile_file" && \