Skip to content

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

TypeScript

test(control-api): cover Grok admin routes, internal routes and redemption errors

Jose Gabriel Ramirez Encinas5201d0733d42
diff --git a/control-api/package-lock.json b/control-api/package-lock.json
index c5cf42b54..0f85948c4 100644
--- a/control-api/package-lock.json
+++ b/control-api/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-control-api",
- "version": "0.1.576",
+ "version": "0.1.577",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-control-api",
- "version": "0.1.576",
+ "version": "0.1.577",
"dependencies": {
"@clerum/display-field": "file:../packages/display-field",
"@clerum/grok-provider-attempt-contract": "file:../packages/grok-provider-attempt-contract",
diff --git a/control-api/package.json b/control-api/package.json
index c14aecb9c..f35e0ce4c 100644
--- a/control-api/package.json
+++ b/control-api/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-control-api",
- "version": "0.1.576",
+ "version": "0.1.577",
"description": "Internal Clerum control plane REST API + UI for managing CRDs and secrets",
"main": "dist/main.js",
"engines": {
diff --git a/control-api/src/routes/admin/codexSubscription.ts b/control-api/src/routes/admin/codexSubscription.ts
index af4f12e82..15575ea12 100644
--- a/control-api/src/routes/admin/codexSubscription.ts
+++ b/control-api/src/routes/admin/codexSubscription.ts
@@ -55,7 +55,10 @@ import {
} from '../../services/grokSubscriptionCatalog.js'
import {
GROK_UNASSIGNED_CONNECTION_KEY,
+ GrokSubscriptionConnectionKeyConflictError,
+ GrokSubscriptionFingerprintConflictError,
GrokSubscriptionInvalidConnectionKeyError,
+ GrokSubscriptionStaleRevisionError,
assertGrokConnectionKey,
createNamedGrokSubscriptionConnection,
generateGrokConnectionKey,
@@ -183,6 +186,22 @@ function sendOAuthError(
res.status(400).json({ error: 'invalid_connection_key' })
return
}
+ // Grok connection-layer write races must never surface as unmapped 500s.
+ if (err instanceof GrokSubscriptionConnectionKeyConflictError) {
+ log.warn({ event: 'grok_oauth_admin_denied', code: err.code }, 'Grok connection key conflict')
+ res.status(409).json({ error: 'connection_key_taken' })
+ return
+ }
+ if (err instanceof GrokSubscriptionFingerprintConflictError) {
+ log.warn({ event: 'grok_oauth_admin_denied', code: err.code }, 'Grok fingerprint conflict')
+ res.status(409).json({ error: 'fingerprint_in_use' })
+ return
+ }
+ if (err instanceof GrokSubscriptionStaleRevisionError) {
+ log.warn({ event: 'grok_oauth_admin_denied', code: err.code }, 'Grok stale revision')
+ res.status(409).json({ error: 'stale_revision' })
+ return
+ }
if (err instanceof GrokSubscriptionOAuthError) {
const status =
err.code === 'disabled'
@@ -329,6 +348,21 @@ export function createAdminCodexSubscriptionRouter(
}
}
+ /**
+ * Migration 0113 archives superseded tombstones as `<key>~revoked~<id>`.
+ * Those keys sit outside the key grammar, so no keyed route can address
+ * them; listing them would only surface unactionable duplicates. The key's
+ * own terminal tombstone (status `revoked`, `revokedAt` set) stays listed.
+ */
+ function isAddressableGrokConnection(row: { connectionKey: string }): boolean {
+ try {
+ assertGrokConnectionKey(row.connectionKey)
+ return true
+ } catch {
+ return false
+ }
+ }
+
function grokKeyFromReq(req: { params?: { key?: string } }): string {
const raw = typeof req.params?.key === 'string' ? req.params.key.trim() : ''
return assertGrokConnectionKey(raw)
@@ -815,7 +849,9 @@ export function createAdminCodexSubscriptionRouter(
res.status(404).json({ error: 'disabled' })
return
}
- const rows = await listSafeGrokSubscriptionConnections(dbClient())
+ const rows = (await listSafeGrokSubscriptionConnections(dbClient())).filter(
+ isAddressableGrokConnection
+ )
const hosts = await listHostsOrUnavailable()
const connections = []
for (const row of rows) {
@@ -885,6 +921,7 @@ export function createAdminCodexSubscriptionRouter(
return
}
const code = (err as { code?: string } | null)?.code
+ // A revoked key is a terminal tombstone (0113): recreating it conflicts.
if (code === '23505') {
res.status(409).json({ error: 'connection_key_taken' })
return
diff --git a/control-api/src/routes/mcp-host/plugin-workload-sdk.routes.ts b/control-api/src/routes/mcp-host/plugin-workload-sdk.routes.ts
index b5fa727ad..d1e8f71db 100644
--- a/control-api/src/routes/mcp-host/plugin-workload-sdk.routes.ts
+++ b/control-api/src/routes/mcp-host/plugin-workload-sdk.routes.ts
@@ -782,8 +782,9 @@ export function createMcpHostPluginWorkloadSdkRoutes(): Router {
...(reservationOnlyOauthBroker
? {
reservationOnlyOauthBroker: true,
+ // Static for both brokers: mcp-host gates the Grok revision
+ // comparison on this same flag, so no Grok-only twin is emitted.
codexBindingRevisions: true,
- ...(grokDefault ? { bindingRevisions: true } : {}),
}
: {}),
...(brokerConnection
diff --git a/control-api/test/routes.admin.grokSubscription.test.ts b/control-api/test/routes.admin.grokSubscription.test.ts
new file mode 100644
index 000000000..ce301d8ab
--- /dev/null
+++ b/control-api/test/routes.admin.grokSubscription.test.ts
@@ -0,0 +1,936 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import express, { type NextFunction, type Request, type Response } from 'express'
+import request from 'supertest'
+import {
+ GrokSubscriptionConnectionKeyConflictError,
+ GrokSubscriptionFingerprintConflictError,
+ GrokSubscriptionInvalidConnectionKeyError,
+ GrokSubscriptionStaleRevisionError,
+} from '../src/services/grokSubscriptionConnection.js'
+import {
+ type GrokOAuthErrorCode,
+ GrokSubscriptionOAuthError,
+} from '../src/services/grokSubscriptionOAuth.js'
+import { K8sConflictError } from '../src/services/resourceService.js'
+
+type GrokOAuthModule = typeof import('../src/services/grokSubscriptionOAuth.js')
+type GrokCatalogModule = typeof import('../src/services/grokSubscriptionCatalog.js')
+
+const grokOAuth = vi.hoisted(() => ({
+ getGrokSubscriptionConnection: vi.fn(),
+ startGrokDeviceConnect: vi.fn(),
+ pollGrokDevice: vi.fn(),
+ refreshGrokSubscriptionConnection: vi.fn(),
+ revokeGrokSubscription: vi.fn(),
+ runGrokCatalogSync: vi.fn(),
+}))
+
+const grokCatalog = vi.hoisted(() => ({
+ listOfferedGrokModelsForAssignment: vi.fn(),
+ listGrokCatalogModels: vi.fn(),
+ setGrokCatalogModelEnabled: vi.fn(),
+}))
+
+const codexOAuth = vi.hoisted(() => ({
+ startCodexDeviceConnect: vi.fn(),
+ revokeCodexSubscription: vi.fn(),
+}))
+
+vi.mock('../src/services/grokSubscriptionOAuth.js', async () => {
+ const actual = await vi.importActual<GrokOAuthModule>('../src/services/grokSubscriptionOAuth.js')
+ return { ...actual, ...grokOAuth }
+})
+
+vi.mock('../src/services/grokSubscriptionCatalog.js', async () => {
+ const actual = await vi.importActual<GrokCatalogModule>(
+ '../src/services/grokSubscriptionCatalog.js'
+ )
+ return { ...actual, ...grokCatalog }
+})
+
+vi.mock('../src/services/codexSubscriptionOAuth.js', async () => {
+ const actual = await vi.importActual('../src/services/codexSubscriptionOAuth.js')
+ return { ...actual, ...codexOAuth }
+})
+
+vi.mock('../src/db.js', () => {
+ const query = vi.fn()
+ return {
+ pool: { query },
+ withTransaction: async <T>(work: (tx: { query: typeof query }) => Promise<T>) =>
+ work({ query }),
+ }
+})
+
+vi.mock('../src/routes/admin/hostSpecValidation.js', async () => {
+ const actual = await vi.importActual('../src/routes/admin/hostSpecValidation.js')
+ return {
+ ...actual,
+ validateHostSpec: vi.fn().mockResolvedValue(null),
+ }
+})
+
+const actualOAuth = await vi.importActual<GrokOAuthModule>(
+ '../src/services/grokSubscriptionOAuth.js'
+)
+const actualCatalog = await vi.importActual<GrokCatalogModule>(
+ '../src/services/grokSubscriptionCatalog.js'
+)
+const { pool } = await import('../src/db.js')
+const { config } = await import('../src/config.js')
+const { createAdminCodexSubscriptionRouter } =
+ await import('../src/routes/admin/codexSubscription.js')
+const { createCodexCatalogTransportFromEnv } =
+ await import('../src/services/codexSubscriptionCatalog.js')
+
+const GROK = '/admin/llm/providers/grok-subscription'
+
+type Gateway = {
+ listResource: ReturnType<typeof vi.fn>
+ getResource: ReturnType<typeof vi.fn>
+ updateResource: ReturnType<typeof vi.fn>
+ llmAllowedModelsConfigMap: () => { materialize: () => Promise<void> }
+}
+
+function makeGateway(materialize: () => Promise<void> = async () => {}): Gateway {
+ return {
+ listResource: vi.fn().mockResolvedValue([]),
+ getResource: vi.fn(),
+ updateResource: vi.fn().mockResolvedValue({}),
+ llmAllowedModelsConfigMap: () => ({ materialize }),
+ }
+}
+
+function makeApp(gateway?: Gateway) {
+ const app = express()
+ app.use(express.json())
+ app.use((req: Request & { adminAuth?: { sub: string } }, _res: Response, next: NextFunction) => {
+ req.adminAuth = { sub: 'admin-1' }
+ next()
+ })
+ app.use(
+ createAdminCodexSubscriptionRouter(createCodexCatalogTransportFromEnv(), gateway as never)
+ )
+ return app
+}
+
+function grokRow(connectionKey: string, overrides: Record<string, unknown> = {}) {
+ return {
+ id: `id-${connectionKey}`,
+ connection_key: connectionKey,
+ display_name: connectionKey,
+ default_model: null,
+ created_by: null,
+ status: 'connected',
+ credential_revision: 2,
+ catalog_revision: 1,
+ account_fingerprint: 'fp-grok',
+ catalog_status: 'ready',
+ catalog_synced_at: null,
+ last_refresh_at: null,
+ last_auth_at: null,
+ refresh_lock_token: null,
+ refresh_lock_expires_at: null,
+ revoked_at: null,
+ created_at: new Date('2026-09-01T00:00:00.000Z'),
+ updated_at: new Date('2026-09-01T00:00:00.000Z'),
+ ...overrides,
+ }
+}
+
+function safeConnection(connectionKey: string, overrides: Record<string, unknown> = {}) {
+ return {
+ id: `id-${connectionKey}`,
+ connectionKey,
+ displayName: connectionKey,
+ defaultModel: null,
+ status: 'connected',
+ credentialRevision: 2,
+ catalogRevision: 1,
+ catalogStatus: 'ready',
+ revokedAt: null,
+ ...overrides,
+ }
+}
+
+/** Route pool.query by SQL fragment; unmatched statements return no rows. */
+function routeSql(routes: Array<[string, (values?: unknown[]) => unknown]>) {
+ vi.mocked(pool.query).mockImplementation((async (sql: unknown, values?: unknown[]) => {
+ const text = String(sql)
+ for (const [fragment, handler] of routes) {
+ if (text.includes(fragment)) return handler(values)
+ }
+ return { rows: [], rowCount: 0 }
+ }) as never)
+}
+
+function assertNoLeak(body: unknown): void {
+ const serialized = JSON.stringify(body)
+ expect(serialized).not.toMatch(/Bearer |eyJ[A-Za-z0-9_-]+\.|refresh-secret|access-secret/i)
+ expect(serialized).not.toMatch(/device_code|deviceCode|cookie|authorization/i)
+}
+
+describe('admin Grok subscription routes', () => {
+ let fetchSpy: ReturnType<typeof vi.fn>
+
+ beforeEach(() => {
+ config.grokSubscriptionEnabled = true
+ config.codexSubscriptionEnabled = true
+ vi.mocked(pool.query).mockReset()
+ vi.mocked(pool.query).mockResolvedValue({ rows: [], rowCount: 0 } as never)
+ for (const [name, fn] of Object.entries(grokOAuth)) {
+ fn.mockReset().mockImplementation(actualOAuth[name as keyof typeof grokOAuth] as never)
+ }
+ for (const [name, fn] of Object.entries(grokCatalog)) {
+ fn.mockReset().mockImplementation(actualCatalog[name as keyof typeof grokCatalog] as never)
+ }
+ for (const fn of Object.values(codexOAuth)) fn.mockReset()
+ fetchSpy = vi.fn(async () => {
+ throw new Error('unexpected upstream fetch')
+ })
+ vi.stubGlobal('fetch', fetchSpy)
+ })
+
+ describe('feature flag and provider isolation', () => {
+ const grokRoutes: Array<['get' | 'post' | 'patch', string]> = [
+ ['get', `${GROK}/connections`],
+ ['post', `${GROK}/connections`],
+ ['get', `${GROK}/connections/team-grok`],
+ ['patch', `${GROK}/connections/team-grok`],
+ ['post', `${GROK}/connections/team-grok/device/start`],
+ ['get', `${GROK}/connections/team-grok/device/poll?state=s`],
+ ['post', `${GROK}/connections/team-grok/refresh`],
+ ['post', `${GROK}/connections/team-grok/catalog/sync`],
+ ['post', `${GROK}/connections/team-grok/revoke`],
+ ['get', `${GROK}/connections/team-grok/models`],
+ ['patch', `${GROK}/connections/team-grok/models/grok-4.6`],
+ ['get', `${GROK}/assignable-hosts`],
+ ['post', `${GROK}/connections/team-grok/hosts/chat/bind`],
+ ['post', `${GROK}/connections/team-grok/hosts/chat/unbind`],
+ ]
+
+ it.each(grokRoutes)(
+ 'returns 404 disabled for %s %s while the Grok flag is off',
+ async (method, path) => {
+ config.grokSubscriptionEnabled = false
+ const gateway = makeGateway()
+ const res = await request(makeApp(gateway))[method](path).send({ enabled: true })
+ expect(res.status).toBe(404)
+ expect(res.body).toEqual({ error: 'disabled' })
+ expect(pool.query).not.toHaveBeenCalled()
+ expect(fetchSpy).not.toHaveBeenCalled()
+ expect(gateway.getResource).not.toHaveBeenCalled()
+ expect(gateway.updateResource).not.toHaveBeenCalled()
+ }
+ )
+
+ it('keeps Codex routes reachable when only the Grok flag is off', async () => {
+ config.grokSubscriptionEnabled = false
+ codexOAuth.revokeCodexSubscription.mockResolvedValue({
+ connectionKey: 'team-plus',
+ status: 'revoked',
+ })
+ const res = await request(makeApp()).post(
+ '/admin/llm/providers/codex-subscription/connections/team-plus/revoke'
+ )
+ expect(res.status).toBe(200)
+ expect(grokOAuth.revokeGrokSubscription).not.toHaveBeenCalled()
+ })
+
+ it.each([
+ ['post', `${GROK}/device/start`],
+ ['get', `${GROK}/device/poll`],
+ ['post', `${GROK}/refresh`],
+ ['post', `${GROK}/catalog/sync`],
+ ['post', `${GROK}/revoke`],
+ ] as const)('rejects the un-keyed Codex alias %s %s for Grok', async (method, path) => {
+ const res = await request(makeApp())[method](path)
+ expect(res.status).toBe(404)
+ expect(res.body).toEqual({ error: 'not_found' })
+ expect(grokOAuth.startGrokDeviceConnect).not.toHaveBeenCalled()
+ expect(grokOAuth.revokeGrokSubscription).not.toHaveBeenCalled()
+ expect(codexOAuth.startCodexDeviceConnect).not.toHaveBeenCalled()
+ expect(codexOAuth.revokeCodexSubscription).not.toHaveBeenCalled()
+ })
+
+ it('never routes a keyed Grok device start through the Codex service', async () => {
+ grokOAuth.startGrokDeviceConnect.mockResolvedValue({
+ userCode: 'GROK-CODE',
+ verificationUri: 'https://accounts.x.ai/device',
+ verificationUriComplete: null,
+ intervalSeconds: 5,
+ expiresAt: new Date('2026-09-17T12:00:00.000Z'),
+ state: 'state-1',
+ intent: 'connect',
+ })
+ const res = await request(makeApp())
+ .post(`${GROK}/connections/team-grok/device/start`)
+ .send({ intent: 'reconnect' })
+ expect(res.status).toBe(200)
+ expect(res.body.userCode).toBe('GROK-CODE')
+ expect(grokOAuth.startGrokDeviceConnect).toHaveBeenCalledWith(
+ expect.objectContaining({ connectionKey: 'team-grok', enabled: true }),
+ 'reconnect'
+ )
+ expect(codexOAuth.startCodexDeviceConnect).not.toHaveBeenCalled()
+ assertNoLeak(res.body)
+ })
+ })
+
+ describe('error to HTTP mapping', () => {
+ const oauthCodes: Array<[GrokOAuthErrorCode, number]> = [
+ ['disabled', 404],
+ ['not_connected', 404],
+ ['no_grant', 404],
+ ['replacement_required', 409],
+ ['fingerprint_in_use', 409],
+ ['connection_mismatch', 409],
+ ['refresh_in_flight', 409],
+ ['stale_revision', 409],
+ ['state_replayed', 400],
+ ['state_expired', 400],
+ ['state_cancelled', 400],
+ ['provider_unavailable', 400],
+ ['invalid_callback', 400],
+ ['reauth_required', 400],
+ ]
+
+ it.each(oauthCodes)('maps GrokSubscriptionOAuthError %s to %i', async (code, status) => {
+ grokOAuth.startGrokDeviceConnect.mockRejectedValue(
+ new GrokSubscriptionOAuthError(code, 'raw upstream detail refresh-secret')
+ )
+ const res = await request(makeApp())
+ .post(`${GROK}/connections/team-grok/device/start`)
+ .send({ intent: 'connect' })
+ expect(res.status).toBe(status)
+ expect(res.body).toEqual({ error: code })
+ assertNoLeak(res.body)
+ })
+
+ it.each([
+ [new GrokSubscriptionConnectionKeyConflictError(), 409, 'connection_key_taken'],
+ [new GrokSubscriptionFingerprintConflictError(), 409, 'fingerprint_in_use'],
+ [new GrokSubscriptionStaleRevisionError(), 409, 'stale_revision'],
+ [new GrokSubscriptionInvalidConnectionKeyError('Bad Key'), 400, 'invalid_connection_key'],
+ ] as const)('maps connection-layer %s without a 500', async (err, status, error) => {
+ grokOAuth.pollGrokDevice.mockRejectedValue(err)
+ const res = await request(makeApp()).get(`${GROK}/connections/team-grok/device/poll?state=s`)
+ expect(res.status).toBe(status)
+ expect(res.body).toEqual({ error })
+ })
+
+ it('maps a connection key conflict on create to 409 connection_key_taken', async () => {
+ routeSql([
+ [
+ 'INSERT INTO grok_subscription_connections',
+ () => {
+ throw Object.assign(new Error('duplicate key'), {
+ code: '23505',
+ constraint: 'grok_subscription_connections_key_unique',
+ })
+ },
+ ],
+ ])
+ const res = await request(makeApp())
+ .post(`${GROK}/connections`)
+ .send({ connectionKey: 'revoked-grok', displayName: 'Again' })
+ expect(res.status).toBe(409)
+ expect(res.body).toEqual({ error: 'connection_key_taken' })
+ })
+
+ it('rejects a malformed or reserved key before any service call', async () => {
+ for (const key of ['Bad%20Key', 'unassigned', 'deployment-default']) {
+ const res = await request(makeApp())
+ .post(`${GROK}/connections/${key}/device/start`)
+ .send({ intent: 'connect' })
+ expect(res.status).toBe(400)
+ expect(res.body).toEqual({ error: 'invalid_connection_key' })
+ }
+ expect(pool.query).not.toHaveBeenCalled()
+ expect(fetchSpy).not.toHaveBeenCalled()
+ })
+ })
+
+ describe('device flow on a revoked key', () => {
+ function revokedTombstone() {
+ routeSql([
+ [
+ 'FROM grok_subscription_connections',
+ () => ({
+ rows: [
+ grokRow('team-grok', {
+ status: 'revoked',
+ revoked_at: new Date('2026-09-10T00:00:00.000Z'),
+ }),
+ ],
+ rowCount: 1,
+ }),
+ ],
+ ])
+ }
+
+ it('refuses to start a device flow on a revoked key without calling xAI', async () => {
+ revokedTombstone()
+ const res = await request(makeApp())
+ .post(`${GROK}/connections/team-grok/device/start`)
+ .send({ intent: 'reconnect' })
+ expect(res.status).toBe(404)
+ expect(res.body).toEqual({ error: 'not_connected' })
+ expect(fetchSpy).not.toHaveBeenCalled()
+ const writes = vi
+ .mocked(pool.query)
+ .mock.calls.filter(([sql]) => /INSERT|UPDATE/.test(String(sql)))
+ expect(writes).toEqual([])
+ })
+
+ it('refuses to poll a device flow on a revoked key without calling xAI', async () => {
+ revokedTombstone()
+ const materialize = vi.fn(async () => {})
+ const res = await request(makeApp(makeGateway(materialize))).get(
+ `${GROK}/connections/team-grok/device/poll?state=pending-state`
+ )
+ expect(res.status).toBe(404)
+ expect(res.body).toEqual({ error: 'not_connected' })
+ expect(fetchSpy).not.toHaveBeenCalled()
+ expect(grokOAuth.runGrokCatalogSync).not.toHaveBeenCalled()
+ expect(materialize).not.toHaveBeenCalled()
+ })
+ })
+
+ describe('device poll', () => {
+ it('syncs the catalog and publishes the allowlist once connected', async () => {
+ const materialize = vi.fn(async () => {})
+ grokOAuth.pollGrokDevice.mockResolvedValue({
+ status: 'connected',
+ connection: safeConnection('team-grok', { catalogStatus: 'never_synced' }),
+ })
+ grokOAuth.runGrokCatalogSync.mockResolvedValue({
+ ok: true,
+ catalogStatus: 'ready',
+ connection: safeConnection('team-grok'),
+ })
+ grokOAuth.getGrokSubscriptionConnection.mockResolvedValue(
+ safeConnection('team-grok', { catalogRevision: 2 })
+ )
+ const res = await request(makeApp(makeGateway(materialize))).get(
+ `${GROK}/connections/team-grok/device/poll?state=s`
+ )
+ expect(res.status).toBe(200)
+ expect(res.body.status).toBe('connected')
+ expect(res.body.connection.catalogRevision).toBe(2)
+ expect(grokOAuth.runGrokCatalogSync).toHaveBeenCalledWith(
+ expect.objectContaining({ connectionKey: 'team-grok' }),
+ 'team-grok',
+ expect.anything()
+ )
+ expect(materialize).toHaveBeenCalledTimes(1)
+ assertNoLeak(res.body)
+ })
+
+ it('overlays the failed catalog status and still publishes after connect', async () => {
+ const materialize = vi.fn(async () => {})
+ grokOAuth.pollGrokDevice.mockResolvedValue({
+ status: 'connected',
+ connection: safeConnection('team-grok', { catalogStatus: 'never_synced' }),
+ })
+ grokOAuth.runGrokCatalogSync.mockResolvedValue({
+ ok: false,
+ catalogStatus: 'unavailable',
+ })
+ const res = await request(makeApp(makeGateway(materialize))).get(
+ `${GROK}/connections/team-grok/device/poll?state=s`
+ )
+ expect(res.status).toBe(200)
+ expect(res.body.connection.catalogStatus).toBe('unavailable')
+ expect(materialize).toHaveBeenCalledTimes(1)
+ })
+
+ it('returns 503 when a connected poll cannot publish the allowlist', async () => {
+ grokOAuth.pollGrokDevice.mockResolvedValue({
+ status: 'connected',
+ connection: safeConnection('team-grok'),
+ })
+ grokOAuth.runGrokCatalogSync.mockResolvedValue({ ok: false, catalogStatus: 'unavailable' })
+ const res = await request(
+ makeApp(
+ makeGateway(async () => {
+ throw new Error('apiserver down')
+ })
+ )
+ ).get(`${GROK}/connections/team-grok/device/poll?state=s`)
+ expect(res.status).toBe(503)
+ expect(res.body.error).toBe('configmap_write_failed')
+ })
+
+ it('neither syncs nor publishes while pending or slow_down', async () => {
+ const materialize = vi.fn(async () => {})
+ for (const status of ['pending', 'slow_down'] as const) {
+ grokOAuth.pollGrokDevice.mockResolvedValueOnce({
+ status,
+ intervalSeconds: 10,
+ state: { intent: 'connect' },
+ })
+ const res = await request(makeApp(makeGateway(materialize))).get(
+ `${GROK}/connections/team-grok/device/poll?state=s`
+ )
+ expect(res.status).toBe(200)
+ expect(res.body).toMatchObject({ status, intervalSeconds: 10 })
+ }
+ expect(grokOAuth.runGrokCatalogSync).not.toHaveBeenCalled()
+ expect(materialize).not.toHaveBeenCalled()
+ })
+ })
+
+ describe('refresh and keyed revoke', () => {
+ it('refreshes the keyed grant and publishes the allowlist', async () => {
+ const materialize = vi.fn(async () => {})
+ grokOAuth.refreshGrokSubscriptionConnection.mockResolvedValue(
+ safeConnection('team-grok', { credentialRevision: 3 })
+ )
+ const res = await request(makeApp(makeGateway(materialize))).post(
+ `${GROK}/connections/team-grok/refresh`
+ )
+ expect(res.status).toBe(200)
+ expect(res.body.credentialRevision).toBe(3)
+ expect(grokOAuth.refreshGrokSubscriptionConnection).toHaveBeenCalledWith(
+ expect.objectContaining({ connectionKey: 'team-grok' })
+ )
+ expect(materialize).toHaveBeenCalledTimes(1)
+ })
+
+ it('does not publish when refresh is rejected', async () => {
+ const materialize = vi.fn(async () => {})
+ grokOAuth.refreshGrokSubscriptionConnection.mockRejectedValue(
+ new GrokSubscriptionOAuthError('reauth_required', 'refresh token was rejected')
+ )
+ const res = await request(makeApp(makeGateway(materialize))).post(
+ `${GROK}/connections/team-grok/refresh`
+ )
+ expect(res.status).toBe(400)
+ expect(res.body).toEqual({ error: 'reauth_required' })
+ expect(materialize).not.toHaveBeenCalled()
+ })
+
+ it('revokes only the addressed key, reports Grok Hosts, and publishes', async () => {
+ const materialize = vi.fn(async () => {})
+ const gateway = makeGateway(materialize)
+ gateway.listResource.mockResolvedValue([
+ {
+ metadata: { name: 'grok-host' },
+ spec: { model: { provider: 'grok-subscription', connectionRef: 'team-grok' } },
+ },
+ {
+ metadata: { name: 'codex-host' },
+ spec: { model: { provider: 'codex-subscription', connectionRef: 'team-grok' } },
+ },
+ ])
+ grokOAuth.revokeGrokSubscription.mockResolvedValue(
+ safeConnection('team-grok', { status: 'revoked', revokedAt: new Date() })
+ )
+ const res = await request(makeApp(gateway)).post(`${GROK}/connections/team-grok/revoke`)
+ expect(res.status).toBe(200)
+ expect(res.body.status).toBe('revoked')
+ expect(res.body.assignedHosts).toEqual([{ name: 'grok-host' }])
+ expect(grokOAuth.revokeGrokSubscription).toHaveBeenCalledWith(
+ expect.objectContaining({ connectionKey: 'team-grok' })
+ )
+ expect(codexOAuth.revokeCodexSubscription).not.toHaveBeenCalled()
+ expect(gateway.updateResource).not.toHaveBeenCalled()
+ expect(materialize).toHaveBeenCalledTimes(1)
+ })
+
+ it('returns 503 when revoke cannot publish the allowlist', async () => {
+ grokOAuth.revokeGrokSubscription.mockResolvedValue(
+ safeConnection('team-grok', { status: 'revoked' })
+ )
+ const res = await request(
+ makeApp(
+ makeGateway(async () => {
+ throw new Error('apiserver down')
+ })
+ )
+ ).post(`${GROK}/connections/team-grok/revoke`)
+ expect(res.status).toBe(503)
+ expect(res.body.error).toBe('configmap_write_failed')
+ })
+ })
+
+ describe('catalog sync', () => {
+ it('publishes after a ready sync', async () => {
+ const materialize = vi.fn(async () => {})
+ grokOAuth.runGrokCatalogSync.mockResolvedValue({
+ ok: true,
+ catalogStatus: 'ready',
+ connection: safeConnection('team-grok'),
+ })
+ const res = await request(makeApp(makeGateway(materialize))).post(
+ `${GROK}/connections/team-grok/catalog/sync`
+ )
+ expect(res.status).toBe(200)
+ expect(res.body.outcome).toBe('ready')
+ expect(materialize).toHaveBeenCalledTimes(1)
+ })
+
+ it.each([
+ [{ reason: 'no_grant' }, 404, { error: 'no_grant' }],
+ [{ reason: 'disabled' }, 404, { error: 'disabled' }],
+ [{ reason: 'stale_revision' }, 409, { error: 'stale_revision' }],
+ [{ reason: 'refresh_in_flight' }, 409, { error: 'refresh_in_flight' }],
+ [{ reason: 'reauth_required' }, 400, { error: 'reauth_required' }],
+ [{ reason: 'provider_unavailable' }, 400, { error: 'provider_unavailable' }],
+ [
+ { reason: 'catalog_sync_failed', catalogStatus: 'unavailable' },
+ 503,
+ { error: 'catalog_sync_failed', outcome: 'unavailable' },
+ ],
+ [
+ { catalogStatus: 'auth-rejected' },
+ 503,
+ { error: 'catalog_sync_failed', outcome: 'auth-rejected' },
+ ],
+ ])('maps a failed sync %j to %i without publishing', async (failure, status, body) => {
+ const materialize = vi.fn(async () => {})
+ grokOAuth.runGrokCatalogSync.mockResolvedValue({
+ ok: false,
+ catalogStatus: 'never_synced',
+ ...failure,
+ })
+ const res = await request(makeApp(makeGateway(materialize))).post(
+ `${GROK}/connections/team-grok/catalog/sync`
+ )
+ expect(res.status).toBe(status)
+ expect(res.body).toEqual(body)
+ expect(materialize).not.toHaveBeenCalled()
+ })
+ })
+
+ describe('connections list and read', () => {
+ it('omits archived ~revoked~ tombstones but keeps the terminal tombstone marked revoked', async () => {
+ routeSql([
+ [
+ 'FROM grok_subscription_connections',
+ () => ({
+ rows: [
+ grokRow('team-grok'),
+ grokRow('old-grok', {
+ status: 'revoked',
+ revoked_at: new Date('2026-09-10T00:00:00.000Z'),
+ }),
+ grokRow('old-grok~revoked~99999999-9999-4999-8999-999999999999', {
+ id: '99999999-9999-4999-8999-999999999999',
+ status: 'revoked',
+ revoked_at: new Date('2026-09-09T00:00:00.000Z'),
+ }),
+ ],
+ rowCount: 3,
+ }),
+ ],
+ ])
+ const gateway = makeGateway()
+ const res = await request(makeApp(gateway)).get(`${GROK}/connections`)
+ expect(res.status).toBe(200)
+ const keys = res.body.connections.map((row: { connectionKey: string }) => row.connectionKey)
+ expect(keys).toEqual(['team-grok', 'old-grok'])
+ expect(JSON.stringify(res.body)).not.toContain('~revoked~')
+ expect(res.body.connections[1]).toMatchObject({ status: 'revoked' })
+ expect(res.body.connections[1].revokedAt).toBeTruthy()
+ })
+
+ it('refuses to address an archived tombstone key directly', async () => {
+ const res = await request(makeApp()).get(
+ `${GROK}/connections/${encodeURIComponent('old-grok~revoked~99999999-9999-4999-8999-999999999999')}`
+ )
+ expect(res.status).toBe(400)
+ expect(res.body).toEqual({ error: 'invalid_connection_key' })
+ expect(pool.query).not.toHaveBeenCalled()
+ })
+
+ it('lists catalog models for a live grant and 409s for a disconnected key', async () => {
+ grokCatalog.listGrokCatalogModels.mockResolvedValue([
+ { model: 'grok-4.6', enabled: true, stale: false },
+ ])
+ grokOAuth.getGrokSubscriptionConnection.mockResolvedValueOnce(safeConnection('team-grok'))
+ const listed = await request(makeApp()).get(`${GROK}/connections/team-grok/models`)
+ expect(listed.status).toBe(200)
+ expect(listed.body.models).toEqual([{ model: 'grok-4.6', enabled: true, stale: false }])
+ expect(grokCatalog.listGrokCatalogModels).toHaveBeenCalledWith(
+ expect.anything(),
+ 'id-team-grok'
+ )
+
+ grokOAuth.getGrokSubscriptionConnection.mockResolvedValueOnce({
+ connectionKey: 'team-grok',
+ status: 'disconnected',
+ })
+ const missing = await request(makeApp()).get(`${GROK}/connections/team-grok/models`)
+ expect(missing.status).toBe(409)
+ expect(missing.body).toEqual({ error: 'not_connected' })
+ })
+ })
+
+ describe('model toggle', () => {
+ it('toggles a model on a live grant and publishes the allowlist', async () => {
+ const materialize = vi.fn(async () => {})
+ routeSql([['FROM grok_subscription_connections', () => ({ rows: [grokRow('team-grok')] })]])
+ grokCatalog.setGrokCatalogModelEnabled.mockResolvedValue([
+ { model: 'grok-4.6', enabled: false, stale: false },
+ ])
+ const res = await request(makeApp(makeGateway(materialize)))
+ .patch(`${GROK}/connections/team-grok/models/grok-4.6`)
+ .send({ enabled: false })
+ expect(res.status).toBe(200)
+ expect(res.body.models).toEqual([{ model: 'grok-4.6', enabled: false, stale: false }])
+ expect(grokCatalog.setGrokCatalogModelEnabled).toHaveBeenCalledWith(
+ expect.anything(),
+ 'id-team-grok',
+ 'grok-4.6',
+ false
+ )
+ expect(materialize).toHaveBeenCalledTimes(1)
+ })
+
+ it('returns 404 no_grant for a revoked grant without touching the catalog', async () => {
+ // Live-only getter: a revoked key has no row.
+ routeSql([])
+ const materialize = vi.fn(async () => {})
+ const res = await request(makeApp(makeGateway(materialize)))
+ .patch(`${GROK}/connections/team-grok/models/grok-4.6`)
+ .send({ enabled: true })
+ expect(res.status).toBe(404)
+ expect(res.body).toEqual({ error: 'no_grant' })
+ expect(grokCatalog.setGrokCatalogModelEnabled).not.toHaveBeenCalled()
+ expect(materialize).not.toHaveBeenCalled()
+ })
+
+ it('rejects a non-boolean enabled and an unknown model', async () => {
+ const bad = await request(makeApp())
+ .patch(`${GROK}/connections/team-grok/models/grok-4.6`)
+ .send({ enabled: 'yes' })
+ expect(bad.status).toBe(400)
+ expect(bad.body).toEqual({ error: 'invalid_enabled' })
+
+ routeSql([['FROM grok_subscription_connections', () => ({ rows: [grokRow('team-grok')] })]])
+ grokCatalog.setGrokCatalogModelEnabled.mockResolvedValue(null)
+ const unknown = await request(makeApp())
+ .patch(`${GROK}/connections/team-grok/models/grok-9`)
+ .send({ enabled: true })
+ expect(unknown.status).toBe(404)
+ expect(unknown.body).toEqual({ error: 'model_not_found' })
+ })
+ })
+
+ describe('metadata PATCH', () => {
+ it('updates displayName and an offered defaultModel', async () => {
+ grokCatalog.listOfferedGrokModelsForAssignment.mockResolvedValue([
+ 'grok-4.6',
+ 'grok-4.6-mini',
+ ])
+ routeSql([
+ [
+ 'UPDATE grok_subscription_connections',
+ () => ({
+ rows: [grokRow('team-grok', { display_name: 'Team', default_model: 'grok-4.6-mini' })],
+ }),
+ ],
+ ])
+ const res = await request(makeApp())
+ .patch(`${GROK}/connections/team-grok`)
+ .send({ displayName: 'Team', defaultModel: 'grok-4.6-mini' })
+ expect(res.status).toBe(200)
+ expect(res.body).toMatchObject({ displayName: 'Team', defaultModel: 'grok-4.6-mini' })
+ expect(grokCatalog.listOfferedGrokModelsForAssignment).toHaveBeenCalledWith(
+ expect.anything(),
+ 'team-grok'
+ )
+ })
+
+ it.each([
+ [{}, 400, { error: 'empty_patch' }],
+ [{ displayName: 'x'.repeat(65) }, 400, { error: 'display_name_too_long' }],
+ [{ defaultModel: 'grok-9' }, 422, { error: 'default_model_not_offered' }],
+ ])('rejects %j with %i', async (patch, status, body) => {
+ grokCatalog.listOfferedGrokModelsForAssignment.mockResolvedValue(['grok-4.6'])
+ const res = await request(makeApp()).patch(`${GROK}/connections/team-grok`).send(patch)
+ expect(res.status).toBe(status)
+ expect(res.body).toEqual(body)
+ const writes = vi
+ .mocked(pool.query)
+ .mock.calls.filter(([sql]) => String(sql).includes('UPDATE'))
+ expect(writes).toEqual([])
+ })
+
+ it('returns 404 no_grant for a revoked tombstone', async () => {
+ routeSql([])
+ const res = await request(makeApp())
+ .patch(`${GROK}/connections/team-grok`)
+ .send({ displayName: 'Tomb' })
+ expect(res.status).toBe(404)
+ expect(res.body).toEqual({ error: 'no_grant' })
+ })
+ })
+
+ describe('bind and unbind', () => {
+ it('binds an unassigned Grok host with the grant default model', async () => {
+ const gateway = makeGateway()
+ gateway.getResource.mockResolvedValue({
+ metadata: { name: 'chat', resourceVersion: '7' },
+ spec: { model: { provider: 'grok-subscription', connectionRef: 'unassigned' } },
+ })
+ grokCatalog.listOfferedGrokModelsForAssignment.mockResolvedValue([
+ 'grok-4.6',
+ 'grok-4.6-mini',
+ ])
+ routeSql([
+ [
+ 'FROM grok_subscription_connections',
+ () => ({ rows: [grokRow('team-grok', { default_model: 'grok-4.6-mini' })] }),
+ ],
+ ])
+ const res = await request(makeApp(gateway)).post(
+ `${GROK}/connections/team-grok/hosts/chat/bind`
+ )
+ expect(res.status).toBe(200)
+ expect(res.body).toEqual({ host: 'chat', connectionRef: 'team-grok', model: 'grok-4.6-mini' })
+ expect(gateway.updateResource).toHaveBeenCalledWith(
+ 'hosts',
+ 'chat',
+ {
+ metadata: { resourceVersion: '7' },
+ spec: {
+ model: {
+ provider: 'grok-subscription',
+ connectionRef: 'team-grok',
+ name: 'grok-4.6-mini',
+ },
+ },
+ },
+ expect.any(String)
+ )
+ })
+
+ it('converts a Codex host to Grok on bind', async () => {
+ const gateway = makeGateway()
+ gateway.getResource.mockResolvedValue({
+ metadata: { name: 'chat' },
+ spec: {
+ model: { provider: 'codex-subscription', connectionRef: 'team-plus', name: 'gpt-5.1' },
+ },
+ })
+ grokCatalog.listOfferedGrokModelsForAssignment.mockResolvedValue(['grok-4.6'])
+ routeSql([['FROM grok_subscription_connections', () => ({ rows: [grokRow('team-grok')] })]])
+ const res = await request(makeApp(gateway)).post(
+ `${GROK}/connections/team-grok/hosts/chat/bind`
+ )
+ expect(res.status).toBe(200)
+ expect(res.body).toEqual({ host: 'chat', connectionRef: 'team-grok', model: 'grok-4.6' })
+ const written = gateway.updateResource.mock.calls[0]?.[2] as {
+ spec: { model: Record<string, unknown> }
+ }
+ expect(written.spec.model).toEqual({
+ provider: 'grok-subscription',
+ connectionRef: 'team-grok',
+ name: 'grok-4.6',
+ })
+ })
+
+ it('refuses to bind a grant whose catalog offers no models', async () => {
+ const gateway = makeGateway()
+ gateway.getResource.mockResolvedValue({
+ metadata: { name: 'chat' },
+ spec: { model: { provider: 'grok-subscription', connectionRef: 'unassigned' } },
+ })
+ grokCatalog.listOfferedGrokModelsForAssignment.mockResolvedValue([])
+ const res = await request(makeApp(gateway)).post(
+ `${GROK}/connections/team-grok/hosts/chat/bind`
+ )
+ expect(res.status).toBe(422)
+ expect(res.body.error).toBe('catalog_not_ready')
+ expect(gateway.updateResource).not.toHaveBeenCalled()
+ })
+
+ it('maps a Host write conflict to 409 resource_changed', async () => {
+ const gateway = makeGateway()
+ gateway.getResource.mockResolvedValue({
+ metadata: { name: 'chat' },
+ spec: { model: { provider: 'grok-subscription', connectionRef: 'unassigned' } },
+ })
+ gateway.updateResource.mockRejectedValue(new K8sConflictError('changed'))
+ grokCatalog.listOfferedGrokModelsForAssignment.mockResolvedValue(['grok-4.6'])
+ routeSql([['FROM grok_subscription_connections', () => ({ rows: [grokRow('team-grok')] })]])
+ const res = await request(makeApp(gateway)).post(
+ `${GROK}/connections/team-grok/hosts/chat/bind`
+ )
+ expect(res.status).toBe(409)
+ expect(res.body).toEqual({ error: 'conflict', reason: 'resource_changed' })
+ })
+
+ it('unbinds a Grok host to unassigned without revoking', async () => {
+ const gateway = makeGateway()
+ gateway.getResource.mockResolvedValue({
+ metadata: { name: 'chat' },
+ spec: {
+ model: { provider: 'grok-subscription', connectionRef: 'team-grok', name: 'grok-4.6' },
+ },
+ })
+ const res = await request(makeApp(gateway)).post(
+ `${GROK}/connections/team-grok/hosts/chat/unbind`
+ )
+ expect(res.status).toBe(200)
+ expect(res.body).toEqual({ host: 'chat', connectionRef: 'unassigned', model: 'grok-4.6' })
+ expect(grokOAuth.revokeGrokSubscription).not.toHaveBeenCalled()
+ const written = gateway.updateResource.mock.calls[0]?.[2] as {
+ spec: { model: Record<string, unknown> }
+ }
+ expect(written.spec.model).toMatchObject({
+ provider: 'grok-subscription',
+ connectionRef: 'unassigned',
+ })
+ })
+
+ it.each([
+ [
+ 'a Codex host bound to the same key',
+ { provider: 'codex-subscription', connectionRef: 'team-grok' },
+ 409,
+ { error: 'not_grok_host' },
+ ],
+ [
+ 'a static-provider host',
+ { provider: 'openai', name: 'gpt-5.4' },
+ 409,
+ { error: 'not_grok_host' },
+ ],
+ [
+ 'a Grok host bound to another grant',
+ { provider: 'grok-subscription', connectionRef: 'other-grok' },
+ 409,
+ { error: 'connection_mismatch' },
+ ],
+ ])('refuses to unbind %s', async (_label, model, status, body) => {
+ const gateway = makeGateway()
+ gateway.getResource.mockResolvedValue({ metadata: { name: 'chat' }, spec: { model } })
+ const res = await request(makeApp(gateway)).post(
+ `${GROK}/connections/team-grok/hosts/chat/unbind`
+ )
+ expect(res.status).toBe(status)
+ expect(res.body).toEqual(body)
+ expect(gateway.updateResource).not.toHaveBeenCalled()
+ })
+
+ it('maps a missing Host to 404 and an invalid key to 400', async () => {
+ const gateway = makeGateway()
+ gateway.getResource.mockRejectedValue(Object.assign(new Error('gone'), { httpStatus: 404 }))
+ const missing = await request(makeApp(gateway)).post(
+ `${GROK}/connections/team-grok/hosts/chat/bind`
+ )
+ expect(missing.status).toBe(404)
+ expect(missing.body).toEqual({ error: 'host_not_found' })
+
+ const invalid = await request(makeApp(gateway)).post(
+ `${GROK}/connections/unassigned/hosts/chat/bind`
+ )
+ expect(invalid.status).toBe(400)
+ expect(invalid.body).toEqual({ error: 'invalid_connection_key' })
+ })
+ })
+})
diff --git a/control-api/test/routes.internal.llmProviderAttempts.grok.test.ts b/control-api/test/routes.internal.llmProviderAttempts.grok.test.ts
new file mode 100644
index 000000000..461f15f01
--- /dev/null
+++ b/control-api/test/routes.internal.llmProviderAttempts.grok.test.ts
@@ -0,0 +1,191 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import express, { type NextFunction, type Request, type Response } from 'express'
+import request from 'supertest'
+import {
+ GrokProviderAttemptFinalizeError,
+ type GrokProviderAttemptFinalizeErrorCode,
+} from '../src/services/grokProviderAttemptFinalization.js'
+import {
+ GrokProviderAttemptRedeemError,
+ type GrokProviderAttemptRedeemErrorCode,
+} from '../src/services/grokProviderAttemptRedemption.js'
+import { LlmProviderAttemptRedeemError } from '../src/services/llmProviderAttemptRedemption.js'
+
+const services = vi.hoisted(() => ({
+ redeemGrok: vi.fn(),
+ finalizeGrok: vi.fn(),
+ redeemCodex: vi.fn(),
+ finalizeCodex: vi.fn(),
+}))
+
+vi.mock('../src/services/grokProviderAttemptRedemption.js', async () => ({
+ ...(await vi.importActual('../src/services/grokProviderAttemptRedemption.js')),
+ redeemGrokProviderAttempt: services.redeemGrok,
+}))
+vi.mock('../src/services/grokProviderAttemptFinalization.js', async () => ({
+ ...(await vi.importActual('../src/services/grokProviderAttemptFinalization.js')),
+ finalizeGrokProviderAttempt: services.finalizeGrok,
+}))
+vi.mock('../src/services/llmProviderAttemptRedemption.js', async () => ({
+ ...(await vi.importActual('../src/services/llmProviderAttemptRedemption.js')),
+ redeemLlmProviderAttempt: services.redeemCodex,
+}))
+vi.mock('../src/services/llmProviderAttemptFinalization.js', async () => ({
+ ...(await vi.importActual('../src/services/llmProviderAttemptFinalization.js')),
+ finalizeLlmProviderAttempt: services.finalizeCodex,
+}))
+vi.mock('../src/db.js', () => ({ pool: { query: vi.fn() }, withTransaction: vi.fn() }))
+
+const { createInternalLlmProviderAttemptRoutes } =
+ await import('../src/routes/internal/llmProviderAttempts.js')
+
+const REDEEM = '/internal/llm/grok/provider-attempts/redeem'
+const FINALIZE = '/internal/llm/grok/provider-attempts/finalize'
+
+/** Stand-in for internalServiceAuth: the header names the authenticated caller. */
+function makeApp() {
+ const app = express()
+ app.use(express.json())
+ app.use((req: Request, _res: Response, next: NextFunction) => {
+ const service = req.header('x-test-service')
+ if (service) {
+ ;(req as Request & { internalService?: { name: string } }).internalService = {
+ name: service,
+ }
+ }
+ next()
+ })
+ app.use(createInternalLlmProviderAttemptRoutes())
+ app.use((err: unknown, _req: Request, res: Response, _next: NextFunction) => {
+ res.status(500).json({ error: 'internal', name: (err as Error)?.name })
+ })
+ return app
+}
+
+describe('internal Grok provider-attempt routes', () => {
+ beforeEach(() => {
+ for (const fn of Object.values(services)) fn.mockReset()
+ })
+
+ describe('service identity', () => {
+ it.each([
+ [REDEEM, undefined],
+ [REDEEM, 'codex-llm-proxy'],
+ [FINALIZE, undefined],
+ [FINALIZE, 'codex-llm-proxy'],
+ ])('rejects %s for caller %s', async (path, service) => {
+ const req = request(makeApp()).post(path).send({})
+ const res = await (service ? req.set('x-test-service', service) : req)
+ expect(res.status).toBe(401)
+ expect(services.redeemGrok).not.toHaveBeenCalled()
+ expect(services.finalizeGrok).not.toHaveBeenCalled()
+ })
+
+ it('does not let the Grok proxy reach the Codex redeem route', async () => {
+ const res = await request(makeApp())
+ .post('/internal/llm/provider-attempts/redeem')
+ .set('x-test-service', 'grok-llm-proxy')
+ .send({ executionTicket: 't', requestHash: 'h' })
+ expect(res.status).toBe(401)
+ expect(services.redeemCodex).not.toHaveBeenCalled()
+ })
+ })
+
+ describe('redeem', () => {
+ it('passes only typed fields and defaults the operation', async () => {
+ services.redeemGrok.mockResolvedValue({ accessToken: 'access', attemptReceipt: 'r' })
+ const res = await request(makeApp())
+ .post(REDEEM)
+ .set('x-test-service', 'grok-llm-proxy')
+ .send({
+ executionTicket: 'ticket',
+ requestHash: 'a'.repeat(64),
+ model: 'grok-4.6',
+ hostRef: 7,
+ operation: 'drop_tables',
+ })
+ expect(res.status).toBe(200)
+ expect(services.redeemGrok).toHaveBeenCalledWith({
+ executionTicket: 'ticket',
+ requestHash: 'a'.repeat(64),
+ model: 'grok-4.6',
+ hostRef: undefined,
+ operation: 'completion_stream',
+ })
+ expect(services.redeemCodex).not.toHaveBeenCalled()
+ })
+
+ const redeemStatus: Array<[GrokProviderAttemptRedeemErrorCode, number]> = [
+ ['disabled', 404],
+ ['ticket_invalid', 403],
+ ['ticket_replayed', 409],
+ ['ticket_expired', 403],
+ ['request_hash_mismatch', 403],
+ ['connection_unavailable', 503],
+ ['no_grant', 403],
+ ['provider_unavailable', 503],
+ ]
+
+ it.each(redeemStatus)('maps redeem error %s to %i', async (code, status) => {
+ services.redeemGrok.mockRejectedValue(
+ new GrokProviderAttemptRedeemError(code, 'detail with access-secret')
+ )
+ const res = await request(makeApp())
+ .post(REDEEM)
+ .set('x-test-service', 'grok-llm-proxy')
+ .send({ executionTicket: 'ticket', requestHash: 'h' })
+ expect(res.status).toBe(status)
+ expect(res.body).toEqual({ error: code })
+ })
+
+ it('does not translate a Codex redeem error thrown on the Grok route', async () => {
+ services.redeemGrok.mockRejectedValue(new LlmProviderAttemptRedeemError('no_grant', 'codex'))
+ const res = await request(makeApp())
+ .post(REDEEM)
+ .set('x-test-service', 'grok-llm-proxy')
+ .send({ executionTicket: 'ticket', requestHash: 'h' })
+ expect(res.status).toBe(500)
+ })
+ })
+
+ describe('finalize', () => {
+ const finalizeStatus: Array<[GrokProviderAttemptFinalizeErrorCode, number]> = [
+ ['disabled', 404],
+ ['ticket_invalid', 403],
+ ['request_hash_mismatch', 403],
+ ['invalid_receipt', 400],
+ ['conflict', 409],
+ ]
+
+ it.each(finalizeStatus)('maps finalize error %s to %i', async (code, status) => {
+ services.finalizeGrok.mockRejectedValue(new GrokProviderAttemptFinalizeError(code, 'detail'))
+ const res = await request(makeApp())
+ .post(FINALIZE)
+ .set('x-test-service', 'grok-llm-proxy')
+ .send({ attemptReceipt: 'a'.repeat(64), receipt: {} })
+ expect(res.status).toBe(status)
+ expect(res.body).toEqual({ error: code })
+ expect(services.finalizeCodex).not.toHaveBeenCalled()
+ })
+
+ it('forwards a non-string attemptReceipt as empty and returns the result', async () => {
+ services.finalizeGrok.mockResolvedValue({
+ providerAttemptId: 'attempt-1',
+ outcome: 'success',
+ duplicate: false,
+ })
+ const receipt = { schemaVersion: 'grok-attempt-receipt.v1' }
+ const res = await request(makeApp())
+ .post(FINALIZE)
+ .set('x-test-service', 'grok-llm-proxy')
+ .send({ attemptReceipt: 42, receipt })
+ expect(res.status).toBe(200)
+ expect(res.body).toEqual({
+ providerAttemptId: 'attempt-1',
+ outcome: 'success',
+ duplicate: false,
+ })
+ expect(services.finalizeGrok).toHaveBeenCalledWith({ attemptReceipt: '', receipt })
+ })
+ })
+})
diff --git a/control-api/test/routes.mcp-host.plugin-workload-sdk.test.ts b/control-api/test/routes.mcp-host.plugin-workload-sdk.test.ts
index 3a302c57c..ac443de71 100644
--- a/control-api/test/routes.mcp-host.plugin-workload-sdk.test.ts
+++ b/control-api/test/routes.mcp-host.plugin-workload-sdk.test.ts
@@ -461,8 +461,12 @@ describe('GET /mcp-host/plugin-workload-sdk/capabilities', () => {
defaultConnectionRef: 'team-grok',
defaultCatalogRevision: 5,
defaultCredentialRevision: 2,
- bindingRevisions: true,
+ reservationOnlyOauthBroker: true,
+ codexBindingRevisions: true,
})
+ // B-L15: no consumer reads a Grok-only `bindingRevisions` flag; the static
+ // `codexBindingRevisions` capability is the single revision gate.
+ expect(res.body).not.toHaveProperty('bindingRevisions')
expect(vi.mocked(grokConnection.getSafeGrokSubscriptionConnection)).toHaveBeenCalledWith(
expect.anything(),
'team-grok'
diff --git a/control-api/test/services.grokProviderAttemptRedemption.refresh.realPostgres.integration.test.ts b/control-api/test/services.grokProviderAttemptRedemption.refresh.realPostgres.integration.test.ts
new file mode 100644
index 000000000..f9eb643d9
--- /dev/null
+++ b/control-api/test/services.grokProviderAttemptRedemption.refresh.realPostgres.integration.test.ts
@@ -0,0 +1,363 @@
+import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest'
+import { createHash, randomBytes, randomUUID } from 'node:crypto'
+import { Pool } from 'pg'
+import { config } from '../src/config.js'
+import { initDb } from '../src/db.js'
+import { deriveOAuthEncryptionKey, encryptOAuthSecret } from '../src/oauth/encryption.js'
+import {
+ type RedeemGrokAttemptDeps,
+ redeemGrokProviderAttempt,
+} from '../src/services/grokProviderAttemptRedemption.js'
+import { issueRegisteredGrokExecutionTicket } from '../src/services/grokProviderAttemptTicket.js'
+import {
+ getSafeGrokSubscriptionConnectionById,
+ insertInitialGrokSubscriptionConnection,
+ loadGrokSubscriptionSecrets,
+} from '../src/services/grokSubscriptionConnection.js'
+import { ensureFreshGrokAccessToken } from '../src/services/grokSubscriptionOAuth.js'
+import { insertLlmProviderAttempt } from '../src/services/llmProviderAttemptStore.js'
+import './realPostgres.requirement.ts'
+
+/**
+ * Redemption with `ensureFreshAccessToken` wired to the real refresh path.
+ * The sibling suite (services.grokProviderAttemptRedemption.realPostgres) omits
+ * the refresh dependency; this one proves refresh, refresh denial and the
+ * consume rollback against real row locks and transactions.
+ */
+
+const adminUrl = process.env.CONTROL_API_REAL_PG_ADMIN_URL
+const describeRealPostgres = adminUrl ? describe : describe.skip
+const ENCRYPTION_KEY_HEX = 'cd'.repeat(32)
+const KEY = deriveOAuthEncryptionKey(ENCRYPTION_KEY_HEX)
+
+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, '""')}"`
+}
+
+/** Unsigned JWT-shaped token; the refresh path only reads `sub` for the fingerprint. */
+function tokenWithSubject(subject: string, marker: string): string {
+ const part = (value: unknown) => Buffer.from(JSON.stringify(value)).toString('base64url')
+ return `${part({ alg: 'none' })}.${part({ sub: subject, marker })}.sig`
+}
+
+function fingerprintOf(connectionKey: string): string {
+ return createHash('sha256').update(`sub-${connectionKey}`, 'utf8').digest('hex')
+}
+
+function jsonResponse(status: number, body: unknown): Response {
+ return new Response(JSON.stringify(body), {
+ status,
+ headers: { 'content-type': 'application/json' },
+ })
+}
+
+describeRealPostgres('Grok ticket redemption with token refresh on real PostgreSQL', () => {
+ const database = `grok_attempt_refresh_${randomBytes(6).toString('hex')}`
+ const connectionString = databaseUrl(
+ adminUrl ?? `postgresql://postgres@${['127', '0', '0', '1'].join('.')}/postgres`,
+ database
+ )
+ let adminPool: Pool
+ let pool: Pool
+ const previousFlag = config.grokSubscriptionEnabled
+ const previousEncryptionKey = config.oauthEncryptionKey
+
+ beforeAll(async () => {
+ config.grokSubscriptionEnabled = true
+ config.oauthEncryptionKey = ENCRYPTION_KEY_HEX
+ 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 () => {
+ config.grokSubscriptionEnabled = previousFlag
+ config.oauthEncryptionKey = previousEncryptionKey
+ await pool?.end()
+ if (adminPool) {
+ await adminPool
+ .query(`DROP DATABASE IF EXISTS ${quoteIdent(database)}`)
+ .catch(() => undefined)
+ await adminPool.end()
+ }
+ })
+
+ async function connect(
+ connectionKey: string,
+ tokens: { accessToken: string | null; accessTokenExpiresAt: Date | null }
+ ) {
+ return insertInitialGrokSubscriptionConnection(
+ pool,
+ KEY,
+ {
+ refreshToken: `refresh-secret-${connectionKey}`,
+ accessToken: tokens.accessToken,
+ accessTokenExpiresAt: tokens.accessTokenExpiresAt,
+ accountFingerprint: fingerprintOf(connectionKey),
+ },
+ connectionKey
+ )
+ }
+
+ async function issueTicket(connection: { id: string; credentialRevision: number }) {
+ const attempt = await insertLlmProviderAttempt(pool, {
+ callerKind: 'host',
+ hostRef: 'research-host',
+ invocationId: `invocation-${randomUUID()}`,
+ attemptGeneration: 1,
+ providerAttemptIndex: 1,
+ provider: 'grok-subscription',
+ model: 'grok-4.6',
+ requestHash: 'd'.repeat(64),
+ policyRevision: 1,
+ policyHash: 'e'.repeat(64),
+ budgetReservationId: 'unbudgeted',
+ connectionRevision: connection.credentialRevision,
+ connectionId: connection.id,
+ })
+ const issued = await issueRegisteredGrokExecutionTicket(pool, {
+ sub: 'host/research-host',
+ hostRef: attempt.hostRef,
+ 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,
+ connectionId: connection.id,
+ })
+ return { attempt, issued }
+ }
+
+ async function ledgerState(jti: string, attemptId: string) {
+ const ticket = await pool.query<{ status: string; redeemed_at: Date | null }>(
+ `SELECT status, redeemed_at FROM llm_provider_attempt_tickets WHERE jti = $1`,
+ [jti]
+ )
+ const attempt = await pool.query<{ status: string }>(
+ `SELECT status FROM llm_provider_attempts WHERE id = $1`,
+ [attemptId]
+ )
+ return {
+ ticketStatus: ticket.rows[0]?.status,
+ redeemedAt: ticket.rows[0]?.redeemed_at ?? null,
+ attemptStatus: attempt.rows[0]?.status,
+ }
+ }
+
+ /** Real refresh path bound to this database and a scripted token endpoint. */
+ function realEnsureFresh(fetchFn: typeof fetch) {
+ return (connectionKey?: string) =>
+ ensureFreshGrokAccessToken({
+ db: pool,
+ encryptionKey: KEY,
+ fetchFn,
+ clientId: 'grok-client-test',
+ enabled: true,
+ connectionKey: connectionKey ?? '',
+ })
+ }
+
+ function redeemDeps(ensureFreshAccessToken: (connectionKey?: string) => Promise<void>) {
+ return {
+ enabled: true as const,
+ db: pool,
+ encryptionKey: KEY,
+ loadSecrets: loadGrokSubscriptionSecrets,
+ getConnectionById: getSafeGrokSubscriptionConnectionById,
+ ensureFreshAccessToken,
+ withTransaction: (async <T>(work: (tx: never) => Promise<T>): Promise<T> => {
+ const client = await pool.connect()
+ try {
+ await client.query('BEGIN')
+ const result = await work(client as never)
+ await client.query('COMMIT')
+ return result
+ } catch (error) {
+ try {
+ await client.query('ROLLBACK')
+ } catch {
+ // keep the original error
+ }
+ throw error
+ } finally {
+ client.release()
+ }
+ }) as RedeemGrokAttemptDeps['withTransaction'],
+ }
+ }
+
+ it('refreshes an expired access token before redeeming and returns the new token', async () => {
+ const connection = await connect('grok-refresh-ok', {
+ accessToken: 'access-expired',
+ accessTokenExpiresAt: new Date(Date.now() - 60_000),
+ })
+ const { attempt, issued } = await issueTicket(connection)
+ const rotatedAccessToken = tokenWithSubject('sub-grok-refresh-ok', 'rotated')
+ const fetchFn = vi.fn(async (_url: string | URL | Request, init?: RequestInit) => {
+ expect(String(init?.body)).toContain('grant_type=refresh_token')
+ return jsonResponse(200, {
+ access_token: rotatedAccessToken,
+ refresh_token: 'refresh-rotated',
+ expires_in: 7200,
+ })
+ })
+
+ const redeemed = await redeemGrokProviderAttempt(
+ { executionTicket: issued.executionTicket, requestHash: attempt.requestHash },
+ redeemDeps(realEnsureFresh(fetchFn as unknown as typeof fetch))
+ )
+
+ expect(fetchFn).toHaveBeenCalledTimes(1)
+ expect(redeemed.accessToken).toBe(rotatedAccessToken)
+ expect(redeemed.expiryClass).toBe('upstream_managed')
+ expect(JSON.stringify(redeemed)).not.toMatch(/refresh-/)
+ const secrets = await loadGrokSubscriptionSecrets(pool, KEY, 'grok-refresh-ok')
+ expect(secrets).toMatchObject({
+ refreshToken: 'refresh-rotated',
+ accessToken: rotatedAccessToken,
+ credentialRevision: connection.credentialRevision,
+ })
+ expect(await ledgerState(issued.claims.jti, attempt.id)).toMatchObject({
+ ticketStatus: 'redeemed',
+ attemptStatus: 'redeemed',
+ })
+ })
+
+ it('skips the token endpoint when the access token is still fresh', async () => {
+ const connection = await connect('grok-refresh-fresh', {
+ accessToken: 'access-fresh',
+ accessTokenExpiresAt: new Date(Date.now() + 2 * 3_600_000),
+ })
+ const { attempt, issued } = await issueTicket(connection)
+ const fetchFn = vi.fn(async () => {
+ throw new Error('token endpoint must not be called')
+ })
+ const redeemed = await redeemGrokProviderAttempt(
+ { executionTicket: issued.executionTicket, requestHash: attempt.requestHash },
+ redeemDeps(realEnsureFresh(fetchFn as unknown as typeof fetch))
+ )
+ expect(redeemed.accessToken).toBe('access-fresh')
+ expect(fetchFn).not.toHaveBeenCalled()
+ })
+
+ it('maps a rejected refresh token to no_grant and leaves the ticket issued', async () => {
+ const connection = await connect('grok-refresh-denied', {
+ accessToken: null,
+ accessTokenExpiresAt: null,
+ })
+ const { attempt, issued } = await issueTicket(connection)
+ const fetchFn = vi.fn(async () => jsonResponse(400, { error: 'invalid_grant' }))
+
+ await expect(
+ redeemGrokProviderAttempt(
+ { executionTicket: issued.executionTicket, requestHash: attempt.requestHash },
+ redeemDeps(realEnsureFresh(fetchFn as unknown as typeof fetch))
+ )
+ ).rejects.toMatchObject({ name: 'GrokProviderAttemptRedeemError', code: 'no_grant' })
+
+ expect(fetchFn).toHaveBeenCalledTimes(1)
+ expect(await ledgerState(issued.claims.jti, attempt.id)).toEqual({
+ ticketStatus: 'issued',
+ redeemedAt: null,
+ attemptStatus: 'authorized',
+ })
+ const row = await getSafeGrokSubscriptionConnectionById(pool, connection.id)
+ expect(row?.status).toBe('reauth_required')
+ expect(row?.refreshLockHeld).toBe(false)
+ })
+
+ it('rolls back the consume when the access token disappears after refresh, keeping the ticket redeemable', async () => {
+ const connection = await connect('grok-refresh-rollback', {
+ accessToken: 'access-fresh',
+ accessTokenExpiresAt: null,
+ })
+ const { attempt, issued } = await issueTicket(connection)
+ const fetchFn = vi.fn(async () => {
+ throw new Error('token endpoint must not be called')
+ })
+ const ensureFresh = realEnsureFresh(fetchFn as unknown as typeof fetch)
+ // A concurrent writer clears the access token between the refresh check and
+ // the redemption transaction. Consume runs before the secrets read, so only
+ // a real ROLLBACK can leave the ticket issued.
+ const clearingEnsureFresh = vi.fn(async (connectionKey?: string) => {
+ await ensureFresh(connectionKey)
+ await pool.query(
+ `UPDATE grok_subscription_connections
+ SET access_token_encrypted = NULL
+ WHERE id = $1`,
+ [connection.id]
+ )
+ })
+
+ await expect(
+ redeemGrokProviderAttempt(
+ { executionTicket: issued.executionTicket, requestHash: attempt.requestHash },
+ redeemDeps(clearingEnsureFresh)
+ )
+ ).rejects.toMatchObject({ code: 'connection_unavailable' })
+
+ expect(clearingEnsureFresh).toHaveBeenCalledWith('grok-refresh-rollback')
+ expect(await ledgerState(issued.claims.jti, attempt.id)).toEqual({
+ ticketStatus: 'issued',
+ redeemedAt: null,
+ attemptStatus: 'authorized',
+ })
+
+ await pool.query(
+ `UPDATE grok_subscription_connections
+ SET access_token_encrypted = $2
+ WHERE id = $1`,
+ [connection.id, encryptOAuthSecret(KEY, 'access-restored')]
+ )
+ const retried = await redeemGrokProviderAttempt(
+ { executionTicket: issued.executionTicket, requestHash: attempt.requestHash },
+ redeemDeps(ensureFresh)
+ )
+ expect(retried.accessToken).toBe('access-restored')
+ expect((await ledgerState(issued.claims.jti, attempt.id)).ticketStatus).toBe('redeemed')
+ await expect(
+ redeemGrokProviderAttempt(
+ { executionTicket: issued.executionTicket, requestHash: attempt.requestHash },
+ redeemDeps(ensureFresh)
+ )
+ ).rejects.toMatchObject({ code: 'ticket_replayed' })
+ })
+
+ it('refuses a credential revision change between refresh and redemption without consuming', async () => {
+ const connection = await connect('grok-refresh-revision', {
+ accessToken: 'access-fresh',
+ accessTokenExpiresAt: null,
+ })
+ const { attempt, issued } = await issueTicket(connection)
+ const bumpingEnsureFresh = vi.fn(async () => {
+ await pool.query(
+ `UPDATE grok_subscription_connections
+ SET credential_revision = credential_revision + 1
+ WHERE id = $1`,
+ [connection.id]
+ )
+ })
+ await expect(
+ redeemGrokProviderAttempt(
+ { executionTicket: issued.executionTicket, requestHash: attempt.requestHash },
+ redeemDeps(bumpingEnsureFresh)
+ )
+ ).rejects.toMatchObject({ code: 'connection_unavailable' })
+ expect(await ledgerState(issued.claims.jti, attempt.id)).toMatchObject({
+ ticketStatus: 'issued',
+ attemptStatus: 'authorized',
+ })
+ })
+})
diff --git a/control-api/test/services.grokProviderAttemptRedemption.test.ts b/control-api/test/services.grokProviderAttemptRedemption.test.ts
index db09d2732..e21c48ce7 100644
--- a/control-api/test/services.grokProviderAttemptRedemption.test.ts
+++ b/control-api/test/services.grokProviderAttemptRedemption.test.ts
@@ -1,4 +1,4 @@
-import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import { config } from '../src/config.js'
import {
GrokProviderAttemptRedeemError,
@@ -159,3 +159,340 @@ describe('redeemGrokProviderAttempt', () => {
expect(withTransaction).not.toHaveBeenCalled()
})
})
+
+describe('redeemGrokProviderAttempt error-path matrix', () => {
+ const ISSUED_TICKET = {
+ jti: CLAIMS.jti,
+ providerAttemptId: CLAIMS.providerAttemptId,
+ status: 'issued' as const,
+ expiresAt: new Date(Date.now() + 30_000),
+ receiptHash: null,
+ }
+
+ function attemptRow(overrides: Record<string, unknown> = {}) {
+ return {
+ id: CLAIMS.providerAttemptId,
+ provider: 'grok-subscription',
+ status: 'authorized',
+ connectionId: CONNECTION_ID,
+ requestHash: CLAIMS.requestHash,
+ model: CLAIMS.model,
+ hostRef: CLAIMS.hostRef,
+ invocationId: CLAIMS.invocationId,
+ attemptGeneration: CLAIMS.attemptGeneration,
+ policyHash: CLAIMS.policyHash,
+ policyRevision: CLAIMS.policyRevision,
+ budgetReservationId: CLAIMS.budgetReservationId,
+ connectionRevision: CLAIMS.connectionRevision,
+ ...overrides,
+ }
+ }
+
+ function liveConnection(overrides: Record<string, unknown> = {}) {
+ return {
+ id: CONNECTION_ID,
+ connectionKey: 'team-grok',
+ status: 'connected',
+ revokedAt: null,
+ credentialRevision: CLAIMS.connectionRevision,
+ ...overrides,
+ }
+ }
+
+ type Scenario = {
+ enabled?: boolean
+ claims?: Partial<typeof CLAIMS> | null
+ input?: Partial<{ requestHash: string; model: string; hostRef: string }>
+ peek?: unknown
+ previewAttempt?: unknown
+ assigned?: unknown
+ ensureFresh?: ((key?: string) => Promise<void>) | null
+ locked?: unknown
+ txAttempt?: unknown
+ connection?: unknown
+ markRedeemed?: boolean
+ secrets?: unknown
+ }
+
+ function arrange(scenario: Scenario = {}) {
+ vi.spyOn(ticket, 'verifyGrokExecutionTicket').mockReturnValue(
+ scenario.claims === null ? null : ({ ...CLAIMS, ...scenario.claims } as typeof CLAIMS)
+ )
+ const peek = vi
+ .spyOn(store, 'peekLlmProviderAttemptTicket')
+ .mockResolvedValue(('peek' in scenario ? scenario.peek : ISSUED_TICKET) as never)
+ const previewAttempt = 'previewAttempt' in scenario ? scenario.previewAttempt : attemptRow()
+ const txAttempt = 'txAttempt' in scenario ? scenario.txAttempt : attemptRow()
+ vi.spyOn(store, 'loadLlmProviderAttempt')
+ .mockResolvedValueOnce(previewAttempt as never)
+ .mockResolvedValueOnce(txAttempt as never)
+ const lock = vi
+ .spyOn(store, 'lockLlmProviderAttemptTicket')
+ .mockResolvedValue(('locked' in scenario ? scenario.locked : ISSUED_TICKET) as never)
+ const connectionById = vi
+ .spyOn(connection, 'getSafeGrokSubscriptionConnectionById')
+ .mockResolvedValue(
+ ('connection' in scenario ? scenario.connection : liveConnection()) as never
+ )
+ const markRedeemed = vi
+ .spyOn(store, 'markLlmProviderAttemptTicketRedeemed')
+ .mockResolvedValue(scenario.markRedeemed ?? true)
+ const loadSecrets = vi.fn().mockResolvedValue(
+ 'secrets' in scenario
+ ? scenario.secrets
+ : {
+ refreshToken: 'refresh-secret',
+ accessToken: 'access-secret',
+ accessTokenExpiresAt: null,
+ credentialRevision: CLAIMS.connectionRevision,
+ }
+ )
+ const ensureFresh =
+ scenario.ensureFresh === null ? undefined : vi.fn(scenario.ensureFresh ?? (async () => {}))
+ const getConnectionById = vi
+ .fn()
+ .mockResolvedValue('assigned' in scenario ? scenario.assigned : liveConnection())
+ const tx = { query: vi.fn() }
+ const withTransaction = vi.fn(async (work: (db: typeof tx) => unknown) => work(tx))
+ const run = () =>
+ redeemGrokProviderAttempt(
+ {
+ executionTicket: 'ticket',
+ requestHash: CLAIMS.requestHash,
+ ...scenario.input,
+ },
+ {
+ enabled: scenario.enabled ?? true,
+ db: { query: vi.fn() },
+ withTransaction: withTransaction as never,
+ loadSecrets,
+ getConnectionById,
+ encryptionKey: Buffer.alloc(32),
+ ...(ensureFresh ? { ensureFreshAccessToken: ensureFresh } : {}),
+ }
+ )
+ return {
+ run,
+ peek,
+ lock,
+ connectionById,
+ markRedeemed,
+ loadSecrets,
+ ensureFresh,
+ getConnectionById,
+ withTransaction,
+ }
+ }
+
+ afterEach(() => {
+ vi.restoreAllMocks()
+ })
+
+ it('redeems when every binding matches and never returns the refresh token', async () => {
+ const h = arrange()
+ const result = await h.run()
+ expect(result.accessToken).toBe('access-secret')
+ expect(result.expiryClass).toBe('upstream_managed')
+ expect(result.transport.servedModel).toBe(CLAIMS.model)
+ expect(JSON.stringify(result)).not.toContain('refresh-secret')
+ expect(h.ensureFresh).toHaveBeenCalledWith('team-grok')
+ expect(h.markRedeemed).toHaveBeenCalledTimes(1)
+ expect(h.loadSecrets).toHaveBeenCalledWith(expect.anything(), expect.any(Buffer), 'team-grok')
+ })
+
+ it('classifies an access token expiring within the hour as short_lived', async () => {
+ const h = arrange({
+ secrets: {
+ refreshToken: 'refresh-secret',
+ accessToken: 'access-secret',
+ accessTokenExpiresAt: new Date(Date.now() + 60_000),
+ credentialRevision: CLAIMS.connectionRevision,
+ },
+ })
+ await expect(h.run()).resolves.toMatchObject({ expiryClass: 'short_lived' })
+ })
+
+ it('rejects while disabled before verifying the ticket', async () => {
+ const h = arrange({ enabled: false })
+ await expect(h.run()).rejects.toMatchObject({ code: 'disabled' })
+ expect(ticket.verifyGrokExecutionTicket).not.toHaveBeenCalled()
+ expect(h.peek).not.toHaveBeenCalled()
+ })
+
+ type PreTx = [string, Scenario, string]
+ const preTransaction: PreTx[] = [
+ ['an unverifiable ticket', { claims: null }, 'ticket_invalid'],
+ [
+ 'a non-Grok ticket provider',
+ { claims: { provider: 'codex-subscription' as never } },
+ 'ticket_invalid',
+ ],
+ [
+ 'a request hash mismatch',
+ { input: { requestHash: 'c'.repeat(64) } },
+ 'request_hash_mismatch',
+ ],
+ ['a model mismatch', { input: { model: 'grok-other' } }, 'ticket_invalid'],
+ ['a hostRef mismatch', { input: { hostRef: 'other-host' } }, 'ticket_invalid'],
+ ['an unregistered ticket', { peek: null }, 'ticket_invalid'],
+ [
+ 'an already-redeemed ticket',
+ { peek: { ...ISSUED_TICKET, status: 'redeemed' } },
+ 'ticket_replayed',
+ ],
+ ['a missing attempt', { previewAttempt: null }, 'ticket_invalid'],
+ [
+ 'a Codex attempt row',
+ { previewAttempt: attemptRow({ provider: 'codex-subscription' }) },
+ 'ticket_invalid',
+ ],
+ [
+ 'an attempt bound to another connection',
+ { previewAttempt: attemptRow({ connectionId: '44444444-4444-4444-8444-444444444444' }) },
+ 'ticket_invalid',
+ ],
+ ['a vanished connection row', { assigned: null }, 'connection_unavailable'],
+ ]
+
+ it.each(preTransaction)(
+ 'rejects %s before refreshing tokens or opening the transaction',
+ async (_label, scenario, code) => {
+ const h = arrange(scenario)
+ await expect(h.run()).rejects.toMatchObject({ name: 'GrokProviderAttemptRedeemError', code })
+ expect(h.ensureFresh).not.toHaveBeenCalled()
+ expect(h.withTransaction).not.toHaveBeenCalled()
+ expect(h.loadSecrets).not.toHaveBeenCalled()
+ }
+ )
+
+ it.each([
+ ['no_grant', 'no_grant'],
+ ['not_connected', 'no_grant'],
+ ['reauth_required', 'no_grant'],
+ ['provider_unavailable', 'provider_unavailable'],
+ ['refresh_in_flight', 'connection_unavailable'],
+ ['stale_revision', 'connection_unavailable'],
+ ] as const)('maps refresh failure %s to %s without redeeming', async (oauthCode, code) => {
+ const h = arrange({
+ ensureFresh: async () => {
+ throw new GrokSubscriptionOAuthError(oauthCode, 'refresh failed')
+ },
+ })
+ await expect(h.run()).rejects.toMatchObject({ code })
+ expect(h.withTransaction).not.toHaveBeenCalled()
+ expect(h.markRedeemed).not.toHaveBeenCalled()
+ })
+
+ it('rethrows a non-OAuth refresh failure unchanged', async () => {
+ const boom = new Error('socket hang up')
+ const h = arrange({
+ ensureFresh: async () => {
+ throw boom
+ },
+ })
+ await expect(h.run()).rejects.toBe(boom)
+ expect(h.markRedeemed).not.toHaveBeenCalled()
+ })
+
+ const inTransaction: Array<[string, Scenario, string]> = [
+ ['a ticket row that disappeared', { locked: null }, 'ticket_invalid'],
+ [
+ 'a ticket redeemed concurrently',
+ { locked: { ...ISSUED_TICKET, status: 'redeemed' } },
+ 'ticket_replayed',
+ ],
+ [
+ 'an expired ticket',
+ { locked: { ...ISSUED_TICKET, expiresAt: new Date(Date.now() - 1) } },
+ 'ticket_expired',
+ ],
+ ['an attempt that vanished', { txAttempt: null }, 'ticket_invalid'],
+ [
+ 'a non-authorized attempt',
+ { txAttempt: attemptRow({ status: 'redeemed' }) },
+ 'ticket_invalid',
+ ],
+ [
+ 'a provider swap inside the transaction',
+ { txAttempt: attemptRow({ provider: 'codex-subscription' }) },
+ 'ticket_invalid',
+ ],
+ ...(
+ [
+ ['requestHash', 'f'.repeat(64)],
+ ['model', 'grok-other'],
+ ['hostRef', 'other-host'],
+ ['invocationId', 'invocation-2'],
+ ['attemptGeneration', 2],
+ ['policyHash', 'c'.repeat(64)],
+ ['policyRevision', 5],
+ ['budgetReservationId', 'res-other'],
+ ['connectionRevision', 4],
+ ] as const
+ ).map(([field, value]): [string, Scenario, string] => [
+ `${field} drift`,
+ { txAttempt: attemptRow({ [field]: value }) },
+ 'no_grant',
+ ]),
+ ['a connection row that is gone', { connection: null }, 'connection_unavailable'],
+ [
+ 'a connection needing reauth',
+ { connection: liveConnection({ status: 'reauth_required' }) },
+ 'connection_unavailable',
+ ],
+ [
+ 'a revoked connection',
+ { connection: liveConnection({ revokedAt: new Date() }) },
+ 'connection_unavailable',
+ ],
+ [
+ 'a credential revision change',
+ { connection: liveConnection({ credentialRevision: CLAIMS.connectionRevision + 1 }) },
+ 'connection_unavailable',
+ ],
+ ]
+
+ it.each(inTransaction)(
+ 'rejects %s before consuming the ticket',
+ async (_label, scenario, code) => {
+ const h = arrange(scenario)
+ await expect(h.run()).rejects.toMatchObject({ name: 'GrokProviderAttemptRedeemError', code })
+ expect(h.withTransaction).toHaveBeenCalledTimes(1)
+ expect(h.markRedeemed).not.toHaveBeenCalled()
+ expect(h.loadSecrets).not.toHaveBeenCalled()
+ }
+ )
+
+ it('reports a lost consume race as ticket_replayed without loading secrets', async () => {
+ const h = arrange({ markRedeemed: false })
+ await expect(h.run()).rejects.toMatchObject({ code: 'ticket_replayed' })
+ expect(h.loadSecrets).not.toHaveBeenCalled()
+ })
+
+ it.each([
+ ['no secrets row', null],
+ [
+ 'a null access token',
+ {
+ refreshToken: 'refresh-secret',
+ accessToken: null,
+ accessTokenExpiresAt: null,
+ credentialRevision: CLAIMS.connectionRevision,
+ },
+ ],
+ ])('throws inside the transaction for %s so the consume rolls back', async (_label, secrets) => {
+ const h = arrange({ secrets })
+ let rolledBack = false
+ h.withTransaction.mockImplementation(async work => {
+ try {
+ return await work({ query: vi.fn() })
+ } catch (err) {
+ rolledBack = true
+ throw err
+ }
+ })
+ await expect(h.run()).rejects.toMatchObject({ code: 'connection_unavailable' })
+ expect(h.markRedeemed).toHaveBeenCalledTimes(1)
+ expect(rolledBack).toBe(true)
+ })
+})
diff --git a/control-api/test/services.llmProviderAttemptAuthorizer.grok.test.ts b/control-api/test/services.llmProviderAttemptAuthorizer.grok.test.ts
index a4a51a402..1b4688158 100644
--- a/control-api/test/services.llmProviderAttemptAuthorizer.grok.test.ts
+++ b/control-api/test/services.llmProviderAttemptAuthorizer.grok.test.ts
@@ -351,7 +351,13 @@ describe('authorizeLlmProviderAttempt grok-subscription', () => {
body({ pluginWorkloadSdkProviderAttemptId: reservedSdkAttempt().id }),
current
)
- ).rejects.toMatchObject({ code: 'no_grant' })
+ ).rejects.toMatchObject({
+ code: 'no_grant',
+ // A host caller has no recipe namespace, so a later SDK-link check would
+ // also reject with no_grant. Only the host guard produces this message.
+ message: 'host Grok chat cannot bind a Plugin Workload SDK provider attempt',
+ })
+ expect(lockPluginWorkloadSdkRecipe).not.toHaveBeenCalled()
expect(getPluginWorkloadSdkProviderAttemptForUpdate).not.toHaveBeenCalled()
expect(current.insertAttempt).not.toHaveBeenCalled()
})
diff --git a/control-api/test/services.llmProviderAttemptAuthorizer.test.ts b/control-api/test/services.llmProviderAttemptAuthorizer.test.ts
index d2a2fd559..bf5a2f531 100644
--- a/control-api/test/services.llmProviderAttemptAuthorizer.test.ts
+++ b/control-api/test/services.llmProviderAttemptAuthorizer.test.ts
@@ -361,7 +361,13 @@ describe('authorizeLlmProviderAttempt', () => {
body({ pluginWorkloadSdkProviderAttemptId: reservedSdkAttempt().id }),
current
)
- ).rejects.toMatchObject({ code: 'no_grant' })
+ ).rejects.toMatchObject({
+ code: 'no_grant',
+ // A host caller has no recipe namespace, so a later SDK-link check would
+ // also reject with no_grant. Only the host guard produces this message.
+ message: 'host Codex chat cannot bind a Plugin Workload SDK provider attempt',
+ })
+ expect(lockPluginWorkloadSdkRecipe).not.toHaveBeenCalled()
expect(getPluginWorkloadSdkProviderAttemptForUpdate).not.toHaveBeenCalled()
expect(current.insertAttempt).not.toHaveBeenCalled()
})