Skip to content

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

TypeScript

fix: close review findings on rate-limit recovery and SDK pre-auth

Alfredo Lopezb6b4e9981ac2
diff --git a/control-api/package-lock.json b/control-api/package-lock.json
index 33f2df8e4..f70bce446 100644
--- a/control-api/package-lock.json
+++ b/control-api/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-control-api",
- "version": "0.1.713",
+ "version": "0.1.714",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-control-api",
- "version": "0.1.713",
+ "version": "0.1.714",
"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 0a60f5958..d6b80060c 100644
--- a/control-api/package.json
+++ b/control-api/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-control-api",
- "version": "0.1.713",
+ "version": "0.1.714",
"description": "Internal Clerum control plane REST API + UI for managing CRDs and secrets",
"main": "dist/main.js",
"engines": {
diff --git a/control-api/src/middleware/pluginWorkloadSdkRateLimits.ts b/control-api/src/middleware/pluginWorkloadSdkRateLimits.ts
index ce9aa0f74..12562f581 100644
--- a/control-api/src/middleware/pluginWorkloadSdkRateLimits.ts
+++ b/control-api/src/middleware/pluginWorkloadSdkRateLimits.ts
@@ -55,6 +55,27 @@ export function pluginSdkPreauthAssignment(principal: string | null): {
return { limit: config.pluginSdkPreauthRlPerMin, key: null }
}
+/**
+ * Bound signature verification per source IP before any limiter that needs a
+ * verified principal to pick its bucket. Only requests presenting a bearer
+ * token reach the verifier, so only they are counted. The budget equals the
+ * verified SDK allowance: invalid credentials still stop at the IP600 ceiling
+ * and valid callers behind a flooded IP keep passing until this budget, after
+ * which further tokens from that IP are denied without being verified.
+ */
+export function createPluginWorkloadSdkVerificationBudgetRateLimit(): RequestHandler {
+ return rateLimit({
+ windowMs: 60_000,
+ limit: config.pluginSdkAuthenticatedPreauthRlPerMin,
+ skip: req => extractBearerToken(req) === '',
+ keyGenerator: req =>
+ `plugin_workload_sdk_verification:ip:${ipKeyGenerator(req.ip || 'unknown')}`,
+ standardHeaders: 'draft-8',
+ legacyHeaders: false,
+ message: { error: 'Too Many Requests', retryable: true },
+ })
+}
+
export function createPluginWorkloadSdkAnonymousPreauthRateLimit(): RequestHandler {
return rateLimit({
windowMs: 60_000,
diff --git a/control-api/src/routes/internal/pluginWorkloadSdk.ts b/control-api/src/routes/internal/pluginWorkloadSdk.ts
index 4d5edee94..61b7d46ec 100644
--- a/control-api/src/routes/internal/pluginWorkloadSdk.ts
+++ b/control-api/src/routes/internal/pluginWorkloadSdk.ts
@@ -4,6 +4,7 @@ import { requireInternalControlJwt } from '../../middleware/internalControlJwt.j
import {
createPluginWorkloadSdkInternalEdgeRateLimit,
createPluginWorkloadSdkInternalRateLimit,
+ createPluginWorkloadSdkVerificationBudgetRateLimit,
} from '../../middleware/pluginWorkloadSdkRateLimits.js'
import {
type PluginWorkloadSdkRevocationActor,
@@ -59,6 +60,8 @@ export function createInternalPluginWorkloadSdkRouter(): Router {
// the prefix so every current/future internal SDK route inherits the guard.
router.use(
'/internal/plugin-workload-sdk',
+ // The edge limiter verifies to pick its key; bound that work per IP first.
+ createPluginWorkloadSdkVerificationBudgetRateLimit(),
createPluginWorkloadSdkInternalEdgeRateLimit(),
requireInternalControlJwt,
createPluginWorkloadSdkInternalRateLimit()
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 d85177a35..3b488b832 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
@@ -8,6 +8,7 @@ import {
createPluginWorkloadSdkAnonymousPreauthRateLimit,
createPluginWorkloadSdkAuthenticatedPreauthRateLimit,
createPluginWorkloadSdkRequestRateLimit,
+ createPluginWorkloadSdkVerificationBudgetRateLimit,
pluginWorkloadSdkCredentialBucketKey,
} from '../../middleware/pluginWorkloadSdkRateLimits.js'
import { rateLimitMiddleware } from '../../middleware/rateLimitMiddleware.js'
@@ -629,7 +630,9 @@ export function createMcpHostPluginWorkloadSdkRoutes(): Router {
'/mcp-host/plugin-workload-sdk',
// Invalid or missing credentials stay on the anonymous source-IP gate.
// Verified Host principals use a separate pre-auth allowance, then the
- // recipe-scoped request bucket after authentication.
+ // recipe-scoped request bucket after authentication. The verification
+ // budget runs first because both pre-auth gates verify to pick a bucket.
+ createPluginWorkloadSdkVerificationBudgetRateLimit(),
createPluginWorkloadSdkAnonymousPreauthRateLimit(),
createPluginWorkloadSdkAuthenticatedPreauthRateLimit(),
requireMcpHostJwt,
diff --git a/control-api/test/app.subscriptionCapabilitiesWiring.test.ts b/control-api/test/app.subscriptionCapabilitiesWiring.test.ts
new file mode 100644
index 000000000..c48037166
--- /dev/null
+++ b/control-api/test/app.subscriptionCapabilitiesWiring.test.ts
@@ -0,0 +1,91 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import request from 'supertest'
+import { createApp } from '../src/app.js'
+import { config } from '../src/config.js'
+import { MockGateway } from './mockGateway.js'
+
+const mockVerifyAdminToken = vi.fn()
+const mockIsAdminTokenRevoked = vi.fn()
+const mockFindAdminById = vi.fn()
+const limiterQuery = vi.fn()
+
+// The read limiter counts in the dedicated limiter pool; answer its upsert at
+// the boundary so the request reaches the capabilities handler.
+vi.mock('../src/db.js', () => ({
+ pool: { query: vi.fn(async () => ({ rows: [], rowCount: 0 })), connect: vi.fn() },
+ rateLimitPool: { query: (...args: unknown[]) => limiterQuery(...args) },
+}))
+
+vi.mock('../src/utils/auth/adminAuthToken.js', () => ({
+ verifyAdminToken: (...args: unknown[]) => mockVerifyAdminToken(...args),
+}))
+
+vi.mock('../src/services/adminAuthService.js', () => ({
+ findAdminById: (...args: unknown[]) => mockFindAdminById(...args),
+ isAdminTokenRevoked: (...args: unknown[]) => mockIsAdminTokenRevoked(...args),
+}))
+
+const ADMIN_CLAIMS = {
+ sub: '00000000-0000-4000-8000-000000000001',
+ typ: 'user' as const,
+ role: 'admin' as const,
+ jti: 'admin-jti',
+ exp: Math.floor(Date.now() / 1000) + 3600,
+}
+
+const ACTIVE_ADMIN = {
+ id: ADMIN_CLAIMS.sub,
+ username: 'admin',
+ email: '[email protected]',
+ passwordHash: 'hash',
+ sessionVersion: 0,
+ role: 'admin' as const,
+ status: 'active' as const,
+ failedAttempts: 0,
+ lockedUntil: null,
+}
+
+const CAPABILITIES = '/api/v1/admin/llm/providers/capabilities'
+
+describe('subscription capability discovery wiring through createApp', () => {
+ beforeEach(() => {
+ mockVerifyAdminToken.mockReset()
+ mockVerifyAdminToken.mockReturnValue(ADMIN_CLAIMS)
+ mockIsAdminTokenRevoked.mockReset()
+ mockIsAdminTokenRevoked.mockResolvedValue(false)
+ mockFindAdminById.mockReset()
+ mockFindAdminById.mockResolvedValue(ACTIVE_ADMIN)
+ limiterQuery.mockReset()
+ limiterQuery.mockResolvedValue({ rows: [{ count: 1 }], rowCount: 1 })
+ })
+
+ it('serves an authenticated administrator through the mounted, rate-limited router', async () => {
+ const app = createApp(new MockGateway('mcp-server') as never)
+ const response = await request(app)
+ .get(CAPABILITIES)
+ .set('Cookie', 'control_ui_admin_session=admin-token')
+ .expect(200)
+ expect(response.body).toEqual({
+ providers: {
+ 'codex-subscription': { enabled: config.codexSubscriptionEnabled },
+ 'grok-subscription': { enabled: config.grokSubscriptionEnabled },
+ },
+ })
+ expect(response.headers['cache-control']).toBe('private, no-store')
+ // The read family limiter counted this request in the limiter pool.
+ expect(limiterQuery).toHaveBeenCalled()
+ expect(String(limiterQuery.mock.calls[0]?.[1]?.[0])).toContain('admin_subscription_read:')
+ })
+
+ it('rejects the same route without a verified session', async () => {
+ mockVerifyAdminToken.mockReturnValue(null)
+ const app = createApp(new MockGateway('mcp-server') as never)
+ await request(app).get(CAPABILITIES).expect(401)
+ // Witness: the guard evaluated the presented cookie before refusing.
+ await request(app)
+ .get(CAPABILITIES)
+ .set('Cookie', 'control_ui_admin_session=unverified-fixture')
+ .expect(401)
+ expect(mockVerifyAdminToken).toHaveBeenCalledWith('unverified-fixture')
+ })
+})
diff --git a/control-api/test/pluginWorkloadSdkVerificationBudget.test.ts b/control-api/test/pluginWorkloadSdkVerificationBudget.test.ts
new file mode 100644
index 000000000..2d4aebade
--- /dev/null
+++ b/control-api/test/pluginWorkloadSdkVerificationBudget.test.ts
@@ -0,0 +1,163 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import express from 'express'
+import jwt from 'jsonwebtoken'
+import request from 'supertest'
+import { config } from '../src/config.js'
+import {
+ createPluginWorkloadSdkAnonymousPreauthRateLimit,
+ createPluginWorkloadSdkAuthenticatedPreauthRateLimit,
+ createPluginWorkloadSdkInternalEdgeRateLimit,
+ createPluginWorkloadSdkVerificationBudgetRateLimit,
+} from '../src/middleware/pluginWorkloadSdkRateLimits.js'
+import { createInternalPluginWorkloadSdkRouter } from '../src/routes/internal/pluginWorkloadSdk.js'
+import { createMcpHostPluginWorkloadSdkRoutes } from '../src/routes/mcp-host/plugin-workload-sdk.routes.js'
+import { verifyInternalControlJwt } from '../src/utils/auth/internalControlToken.js'
+import { issueMcpHostAccessJwt, verifyMcpHostAccessJwt } from '../src/utils/auth/mcpHostJwtToken.js'
+
+// Count signature verifications without changing their result, so each test
+// can prove how many tokens a limiter verified before it denied.
+vi.mock('../src/utils/auth/mcpHostJwtToken.js', async importOriginal => {
+ const actual = await importOriginal<typeof import('../src/utils/auth/mcpHostJwtToken.js')>()
+ return { ...actual, verifyMcpHostAccessJwt: vi.fn(actual.verifyMcpHostAccessJwt) }
+})
+vi.mock('../src/utils/auth/internalControlToken.js', async importOriginal => {
+ const actual = await importOriginal<typeof import('../src/utils/auth/internalControlToken.js')>()
+ return { ...actual, verifyInternalControlJwt: vi.fn(actual.verifyInternalControlJwt) }
+})
+vi.mock('../src/db.js', () => ({
+ pool: { query: vi.fn(), connect: vi.fn() },
+ rateLimitPool: { query: vi.fn() },
+}))
+
+const mcpHostVerifier = vi.mocked(verifyMcpHostAccessJwt)
+const internalVerifier = vi.mocked(verifyInternalControlJwt)
+
+function mcpHostVerificationsOf(token: string): number {
+ return mcpHostVerifier.mock.calls.filter(([candidate]) => candidate === token).length
+}
+
+function signedHost(): string {
+ return issueMcpHostAccessJwt('sandbox-recipes', 'budget-sdk', undefined, {
+ workflowControlScopes: ['plugin-workload-sdk'],
+ }).token
+}
+
+function forgedInternal(): string {
+ return jwt.sign({ iss: 'wrc', aud: 'control-api', sub: 'wrc-provisioner' }, 'not-the-secret', {
+ algorithm: 'HS256',
+ expiresIn: 60,
+ })
+}
+
+describe('Plugin Workload SDK verification budget', () => {
+ const original = {
+ authenticated: config.pluginSdkAuthenticatedPreauthRlPerMin,
+ anonymous: config.pluginSdkPreauthRlPerMin,
+ }
+
+ beforeEach(() => {
+ mcpHostVerifier.mockClear()
+ internalVerifier.mockClear()
+ })
+
+ afterEach(() => {
+ config.pluginSdkAuthenticatedPreauthRlPerMin = original.authenticated
+ config.pluginSdkPreauthRlPerMin = original.anonymous
+ })
+
+ function preauthApp() {
+ const instance = express()
+ instance.use(
+ createPluginWorkloadSdkVerificationBudgetRateLimit(),
+ createPluginWorkloadSdkAnonymousPreauthRateLimit(),
+ createPluginWorkloadSdkAuthenticatedPreauthRateLimit()
+ )
+ // The handler never verifies, so every counted call came from a limiter.
+ instance.get('/sdk-gate', (_req, res) => res.json({ ok: true }))
+ return instance
+ }
+
+ it('denies tokens past the per-IP budget without verifying them', async () => {
+ config.pluginSdkAuthenticatedPreauthRlPerMin = 4
+ config.pluginSdkPreauthRlPerMin = 2
+ const instance = preauthApp()
+ const forged = `${signedHost()}x`
+ const valid = signedHost()
+
+ await request(instance).get('/sdk-gate').set('Authorization', `Bearer ${forged}`).expect(200)
+ await request(instance).get('/sdk-gate').set('Authorization', `Bearer ${forged}`).expect(200)
+ await request(instance).get('/sdk-gate').set('Authorization', `Bearer ${forged}`).expect(429)
+ // A valid caller behind the flooded IP still passes inside the budget.
+ await request(instance).get('/sdk-gate').set('Authorization', `Bearer ${valid}`).expect(200)
+ expect(mcpHostVerificationsOf(forged)).toBe(3)
+ expect(mcpHostVerificationsOf(valid)).toBe(1)
+
+ const denied = await request(instance).get('/sdk-gate').set('Authorization', `Bearer ${valid}`)
+ expect(denied.status).toBe(429)
+ expect(denied.body).toEqual({ error: 'Too Many Requests', retryable: true })
+ expect(mcpHostVerificationsOf(valid)).toBe(1)
+ })
+
+ it('does not spend the budget on requests that present no bearer token', async () => {
+ config.pluginSdkAuthenticatedPreauthRlPerMin = 1
+ config.pluginSdkPreauthRlPerMin = 10
+ const instance = preauthApp()
+ const valid = signedHost()
+
+ for (let i = 0; i < 3; i += 1) await request(instance).get('/sdk-gate').expect(200)
+ await request(instance).get('/sdk-gate').set('Authorization', `Bearer ${valid}`).expect(200)
+ expect(mcpHostVerificationsOf(valid)).toBe(1)
+ })
+
+ it('bounds internal edge verification per IP before the edge limiter verifies', async () => {
+ config.pluginSdkAuthenticatedPreauthRlPerMin = 3
+ const instance = express()
+ instance.use(
+ createPluginWorkloadSdkVerificationBudgetRateLimit(),
+ createPluginWorkloadSdkInternalEdgeRateLimit()
+ )
+ instance.post('/edge', (_req, res) => res.json({ ok: true }))
+ const forged = forgedInternal()
+
+ for (let i = 0; i < 3; i += 1) {
+ await request(instance).post('/edge').set('Authorization', `Bearer ${forged}`).expect(200)
+ }
+ expect(internalVerifier).toHaveBeenCalledTimes(3)
+ await request(instance).post('/edge').set('Authorization', `Bearer ${forged}`).expect(429)
+ expect(internalVerifier).toHaveBeenCalledTimes(3)
+ })
+
+ it('is mounted ahead of verification on both SDK routers', async () => {
+ config.pluginSdkAuthenticatedPreauthRlPerMin = 2
+ config.pluginSdkPreauthRlPerMin = 600
+
+ const mcpHost = express()
+ mcpHost.use(express.json())
+ mcpHost.use('/api/v1', createMcpHostPluginWorkloadSdkRoutes())
+ const forgedHost = `${signedHost()}x`
+ const hostPath = '/api/v1/mcp-host/plugin-workload-sdk/capabilities'
+ for (let i = 0; i < 2; i += 1) {
+ await request(mcpHost).get(hostPath).set('Authorization', `Bearer ${forgedHost}`).expect(401)
+ }
+ await request(mcpHost).get(hostPath).set('Authorization', `Bearer ${forgedHost}`).expect(429)
+
+ const internal = express()
+ internal.use(express.json())
+ internal.use('/api/v1', createInternalPluginWorkloadSdkRouter())
+ const forged = forgedInternal()
+ const internalPath = '/api/v1/internal/plugin-workload-sdk/revoke'
+ for (let i = 0; i < 2; i += 1) {
+ await request(internal)
+ .post(internalPath)
+ .set('Authorization', `Bearer ${forged}`)
+ .send({})
+ .expect(401)
+ }
+ await request(internal)
+ .post(internalPath)
+ .set('Authorization', `Bearer ${forged}`)
+ .send({})
+ .expect(429)
+ expect(internalVerifier.mock.calls.length).toBeGreaterThanOrEqual(2)
+ })
+})
diff --git a/control-ui/app/hosts/[name]/page.tsx b/control-ui/app/hosts/[name]/page.tsx
index 1639f6246..0c25f88a6 100644
--- a/control-ui/app/hosts/[name]/page.tsx
+++ b/control-ui/app/hosts/[name]/page.tsx
@@ -431,21 +431,14 @@ export default function HostDetailsPage() {
}
const controller = new AbortController()
setSubscriptionInventoryLoading(true)
+ // Retry only re-runs this effect. An inventory the shared recovery already
+ // read after a 429 is cached; forcing a refresh would spend a second read
+ // in the same quota window and answer the visible Retry with another 429.
const requests = [
codexEnabled
- ? listCodexSubscriptionConnections({
- signal: controller.signal,
- refresh: inventoryRetryNonce > 0,
- })
+ ? listCodexSubscriptionConnections({ signal: controller.signal })
: Promise.resolve([]),
- ...(grokEnabled
- ? [
- listGrokSubscriptionConnections({
- signal: controller.signal,
- refresh: inventoryRetryNonce > 0,
- }),
- ]
- : []),
+ ...(grokEnabled ? [listGrokSubscriptionConnections({ signal: controller.signal })] : []),
]
Promise.allSettled(requests)
.then(([codexResult, grokResult]) => {
@@ -490,10 +483,7 @@ export default function HostDetailsPage() {
const controller = new AbortController()
setGrantCatalogError('')
if (providerDraft === GROK_SUBSCRIPTION_PROVIDER) {
- void listGrokConnectionModels(connectionRefDraft, {
- signal: controller.signal,
- refresh: inventoryRetryNonce > 0,
- })
+ void listGrokConnectionModels(connectionRefDraft, { signal: controller.signal })
.then(models => {
if (controller.signal.aborted) return
setGrantCatalog({
@@ -512,10 +502,7 @@ export default function HostDetailsPage() {
controller.abort()
}
}
- void listCodexConnectionModels(connectionRefDraft, {
- signal: controller.signal,
- refresh: inventoryRetryNonce > 0,
- })
+ void listCodexConnectionModels(connectionRefDraft, { signal: controller.signal })
.then(models => {
if (controller.signal.aborted) return
setGrantCatalog({
diff --git a/control-ui/app/plugin-workload-sdk/page.tsx b/control-ui/app/plugin-workload-sdk/page.tsx
index f24699c22..26705593d 100644
--- a/control-ui/app/plugin-workload-sdk/page.tsx
+++ b/control-ui/app/plugin-workload-sdk/page.tsx
@@ -560,10 +560,7 @@ function GrantFormModal({
if (!isCodexProvider) return
const controller = new AbortController()
setGrantInventoryLoading(true)
- listCodexSubscriptionConnections({
- signal: controller.signal,
- refresh: grantInventoryRetryNonce > 0,
- })
+ listCodexSubscriptionConnections({ signal: controller.signal })
.then(connections => {
if (controller.signal.aborted) return
setCodexConnections(connections.filter(isAssignableCodexGrant))
@@ -584,10 +581,7 @@ function GrantFormModal({
if (!isGrokProvider) return
const controller = new AbortController()
setGrantInventoryLoading(true)
- listGrokSubscriptionConnections({
- signal: controller.signal,
- refresh: grantInventoryRetryNonce > 0,
- })
+ listGrokSubscriptionConnections({ signal: controller.signal })
.then(connections => {
if (controller.signal.aborted) return
setGrokConnections(connections.filter(isAssignableGrokGrant))
@@ -609,9 +603,12 @@ function GrantFormModal({
setCodexModels([])
return
}
+ // A catalog belongs to one connection: drop the previous connection's
+ // models so they cannot be added under this connection's reference.
+ setCodexModels([])
const controller = new AbortController()
const loader = isGrokProvider ? listGrokConnectionModels : listCodexConnectionModels
- loader(codexConnectionRef, { signal: controller.signal, refresh: grantInventoryRetryNonce > 0 })
+ loader(codexConnectionRef, { signal: controller.signal })
.then(models => {
if (controller.signal.aborted) return
setCodexModels(models.filter(row => row.enabled && !row.stale).map(row => row.model))
diff --git a/control-ui/components/HostWizard/index.tsx b/control-ui/components/HostWizard/index.tsx
index 4ff5adab2..13ea1d772 100644
--- a/control-ui/components/HostWizard/index.tsx
+++ b/control-ui/components/HostWizard/index.tsx
@@ -199,9 +199,9 @@ function isStepValid(stepIndex: number, state: HostWizardValidationState): boole
isOauthBrokerProvider(state.provider) &&
(!state.connectionRef.trim() ||
state.connectionRef.trim() === CODEX_UNASSIGNED_CONNECTION_KEY ||
- (state.provider === GROK_SUBSCRIPTION_PROVIDER
- ? state.grokModels.length > 0 && !state.grokModels.includes(state.modelName.trim())
- : state.codexModels.length > 0 && !state.codexModels.includes(state.modelName.trim())))
+ // An empty picker offers nothing, so a model kept from an earlier
+ // catalog or connection cannot pass.
+ !state.brokerModelOptions.includes(state.modelName.trim()))
) {
return false
}
@@ -425,6 +425,13 @@ export function HostWizard({
() => getModelOptions(catalogForEditor, provider),
[catalogForEditor, provider]
)
+ const brokerModelOptions = useMemo(
+ () =>
+ isOauthBrokerProvider(provider)
+ ? constrainModelOptions(catalogForEditor, allowedModels, provider)
+ : [],
+ [allowedModels, catalogForEditor, provider]
+ )
const chainRequiresSecret = llmChainRequiresSecret(provider, llmPolicy?.fallbacks)
const handleExistingSecretChange = useCallback(
(secretName: string) => {
@@ -461,19 +468,9 @@ export function HostWizard({
setGrantInventoryLoading(true)
const requests = [
codexEnabled
- ? listCodexSubscriptionConnections({
- signal: controller.signal,
- refresh: inventoryRetryNonce > 0,
- })
+ ? listCodexSubscriptionConnections({ signal: controller.signal })
: Promise.resolve([]),
- ...(grokEnabled
- ? [
- listGrokSubscriptionConnections({
- signal: controller.signal,
- refresh: inventoryRetryNonce > 0,
- }),
- ]
- : []),
+ ...(grokEnabled ? [listGrokSubscriptionConnections({ signal: controller.signal })] : []),
]
Promise.allSettled(requests)
.then(([codexResult, grokResult]) => {
@@ -506,13 +503,15 @@ export function HostWizard({
return
}
setGrantCatalogError('')
+ // A catalog belongs to one connection: drop the previous connection's
+ // models before this load so they can never be offered under this ref.
+ setCodexModels([])
+ setGrokModels([])
const controller = new AbortController()
+ // The retry nonce only re-runs this load. A catalog recovered after a 429
+ // is already cached; bypassing it would spend a second read in the window.
if (provider === GROK_SUBSCRIPTION_PROVIDER) {
- setCodexModels([])
- void listGrokConnectionModels(connectionRef, {
- signal: controller.signal,
- refresh: inventoryRetryNonce > 0,
- })
+ void listGrokConnectionModels(connectionRef, { signal: controller.signal })
.then(models => {
if (!controller.signal.aborted) setGrokModels(offeredCodexModelNames(models))
})
@@ -527,11 +526,7 @@ export function HostWizard({
controller.abort()
}
}
- setGrokModels([])
- void listCodexConnectionModels(connectionRef, {
- signal: controller.signal,
- refresh: inventoryRetryNonce > 0,
- })
+ void listCodexConnectionModels(connectionRef, { signal: controller.signal })
.then(models => {
if (!controller.signal.aborted) setCodexModels(offeredCodexModelNames(models))
})
@@ -552,12 +547,11 @@ export function HostWizard({
useEffect(() => {
if (modelsLoading) return
if (isOauthBrokerProvider(provider)) {
- const offered = constrainModelOptions(catalogForEditor, allowedModels, provider)
- if (offered.length === 0) return
+ if (brokerModelOptions.length === 0) return
const grant = (
provider === GROK_SUBSCRIPTION_PROVIDER ? grokConnections : codexConnections
).find(row => row.connectionKey === connectionRef)
- const next = resolveCodexGrantModel(modelName, offered, grant?.defaultModel)
+ const next = resolveCodexGrantModel(modelName, brokerModelOptions, grant?.defaultModel)
if (next !== modelName) setModelName(next)
return
}
@@ -566,7 +560,7 @@ export function HostWizard({
}
// Intentionally omit modelName: this reconciles the picker to the options.
// eslint-disable-next-line react-hooks/exhaustive-deps
- }, [allowedModels, catalogForEditor, modelsLoading, provider, providerModelOptions])
+ }, [brokerModelOptions, modelsLoading, provider, providerModelOptions])
// Auto-derive the new Secret name from the agent name ("this agent's
// credentials") until the operator edits it, so naming a Kubernetes Secret is
@@ -620,8 +614,7 @@ export function HostWizard({
provider,
modelName,
connectionRef,
- codexModels,
- grokModels,
+ brokerModelOptions,
}),
[
hostName,
@@ -634,8 +627,7 @@ export function HostWizard({
provider,
modelName,
connectionRef,
- codexModels,
- grokModels,
+ brokerModelOptions,
]
)
@@ -959,7 +951,6 @@ export function HostWizard({
>
{step === 0 && (
<div className="cu-form-stack cu-agent-form-stack">
- <SubscriptionCapabilityNotice state={subscriptionCapabilities} />
<Field
description="The name members see. The identifier used in URLs is derived automatically."
htmlFor="wizard-agent-name"
@@ -1052,6 +1043,8 @@ export function HostWizard({
{step === 1 && (
<div className="cu-form-stack cu-agent-form-stack">
+ {/* Capability discovery is enabled on this step, so its failure and Retry live here. */}
+ <SubscriptionCapabilityNotice state={subscriptionCapabilities} />
{grantInventoryLoading ? (
<p className="cu-muted" role="status">
Loading subscription options…
diff --git a/control-ui/components/HostWizard/types.ts b/control-ui/components/HostWizard/types.ts
index 89855b3c8..32ad82804 100644
--- a/control-ui/components/HostWizard/types.ts
+++ b/control-ui/components/HostWizard/types.ts
@@ -81,6 +81,6 @@ export type HostWizardValidationState = {
provider: LlmProvider
modelName: string
connectionRef: string
- codexModels: string[]
- grokModels: string[]
+ /** Models the subscription picker offers for the selected connection. */
+ brokerModelOptions: string[]
}
diff --git a/control-ui/components/RecipeEditor.tsx b/control-ui/components/RecipeEditor.tsx
index 12c975cfc..c98430d18 100644
--- a/control-ui/components/RecipeEditor.tsx
+++ b/control-ui/components/RecipeEditor.tsx
@@ -1846,7 +1846,7 @@ export function RecipeEditor({ initial, onSaved, onCancel, pageHeader }: Props)
const controller = new AbortController()
setGrantInventoryLoading(true)
const loader = isGrokRecipe ? listGrokSubscriptionConnections : listCodexSubscriptionConnections
- loader({ signal: controller.signal, refresh: grantInventoryRetryNonce > 0 })
+ loader({ signal: controller.signal })
.then(rows => {
if (controller.signal.aborted) return
if (isGrokRecipe) {
diff --git a/control-ui/components/__tests__/HostDetailsPage.rateLimit.test.tsx b/control-ui/components/__tests__/HostDetailsPage.rateLimit.test.tsx
index ba28a7266..339187c43 100644
--- a/control-ui/components/__tests__/HostDetailsPage.rateLimit.test.tsx
+++ b/control-ui/components/__tests__/HostDetailsPage.rateLimit.test.tsx
@@ -278,6 +278,61 @@ describe('HostDetailsPage optional subscription throttling', () => {
expect(api.apiSend).not.toHaveBeenCalled()
})
+ it('answers the visible Retry from the background recovery without spending another read in its window', async () => {
+ vi.useFakeTimers()
+ // The server's shared subscription-read quota: two reads per twelve-second window.
+ const windowMs = 12_000
+ const startedAt = Date.now()
+ const reads: Array<{ url: string; window: number; status: number }> = []
+ fetchMock.mockImplementation((input: RequestInfo | URL) => {
+ const url = String(input)
+ const window = Math.floor((Date.now() - startedAt) / windowMs)
+ const inWindow = reads.filter(read => read.window === window).length
+ const response =
+ inWindow >= 2
+ ? throttle()
+ : url.endsWith('/capabilities')
+ ? json({
+ providers: {
+ 'codex-subscription': { enabled: true },
+ 'grok-subscription': { enabled: true },
+ },
+ })
+ : json({ connections: [] })
+ reads.push({ url, window, status: response.status })
+ return Promise.resolve(response)
+ })
+ const flush = () =>
+ act(async () => {
+ await vi.advanceTimersByTimeAsync(0)
+ })
+ renderPage()
+ await flush()
+ navigate('Models & creds')
+ fireEvent.click(screen.getByRole('button', { name: 'Edit' }))
+ await flush()
+ const dialog = screen.getByRole('dialog', { name: 'Edit model configuration' })
+ const alert = within(dialog).getByRole('alert')
+ expect(alert).toHaveTextContent('Try again in 12 seconds.')
+ expect(reads.map(read => read.status)).toEqual([200, 200, 429])
+
+ // The shared recovery reads the denied inventory once the deadline passes.
+ await act(async () => {
+ await vi.advanceTimersByTimeAsync(windowMs)
+ })
+ const afterDeadline = () => reads.filter(read => read.window >= 1)
+ expect(afterDeadline()).toHaveLength(1)
+ expect(afterDeadline()[0]?.status).toBe(200)
+
+ fireEvent.click(within(alert).getByRole('button', { name: 'Retry' }))
+ await flush()
+ // Witness: the visible error cleared through the Retry.
+ expect(within(dialog).queryByRole('alert')).toBeNull()
+ expect(afterDeadline().map(read => read.status)).not.toContain(429)
+ expect(afterDeadline().length).toBeLessThanOrEqual(2)
+ expect(api.apiSend).not.toHaveBeenCalled()
+ })
+
it.each(['codex-subscription', 'grok-subscription'] as const)(
'does not confirm retained %s models under a different connection that throttles, then recovers only that binding',
async provider => {
diff --git a/control-ui/components/__tests__/HostWizard.test.tsx b/control-ui/components/__tests__/HostWizard.test.tsx
index efd37bfe8..c0b63d9f8 100644
--- a/control-ui/components/__tests__/HostWizard.test.tsx
+++ b/control-ui/components/__tests__/HostWizard.test.tsx
@@ -2,6 +2,10 @@ import React from 'react'
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import { act, cleanup, fireEvent, render, screen, waitFor, within } from '@testing-library/react'
import * as api from '../../lib/api'
+import {
+ listCodexConnectionModels,
+ listCodexSubscriptionConnections,
+} from '../../lib/codexSubscription'
import {
listGrokConnectionModels,
listGrokSubscriptionConnections,
@@ -20,12 +24,23 @@ const grokCapabilityState = vi.hoisted(() => ({
capabilities: {
providers: { 'codex-subscription': { enabled: true }, 'grok-subscription': { enabled: true } },
},
+ // When set, the enabled probe fails with this error and offers this retry.
+ error: null as Error | null,
+ retry: vi.fn(),
}))
vi.mock('../../lib/hooks/useSubscriptionCapabilities', () => ({
- useSubscriptionCapabilities: () => {
+ useSubscriptionCapabilities: (options?: { enabled?: boolean }) => {
grokCapabilityState.capabilities.providers['grok-subscription'].enabled =
grokCapabilityState.enabled
+ if (grokCapabilityState.error && options?.enabled) {
+ return {
+ capabilities: null,
+ loading: false,
+ error: grokCapabilityState.error,
+ retry: grokCapabilityState.retry,
+ }
+ }
return {
capabilities: grokCapabilityState.capabilities,
loading: false,
@@ -171,6 +186,8 @@ if (!Element.prototype.scrollIntoView) {
beforeEach(() => {
grokCapabilityState.enabled = true
+ grokCapabilityState.error = null
+ grokCapabilityState.retry.mockReset()
})
async function renderWizard(props?: {
@@ -1375,6 +1392,84 @@ describe('HostWizard — broker-backed Codex authoring', () => {
expect(screen.queryByRole('option', { name: 'xAI Grok Subscription' })).not.toBeInTheDocument()
}, 15_000)
+ it('never offers one subscription connection catalog under another connection that throttles', async () => {
+ const connections = vi.mocked(listCodexSubscriptionConnections)
+ const models = vi.mocked(listCodexConnectionModels)
+ const defaultConnections = connections.getMockImplementation()
+ const defaultModels = models.getMockImplementation()
+ const row = (await defaultConnections!())[0]!
+ connections.mockResolvedValue([
+ row,
+ { ...row, connectionKey: 'codex-bbb', displayName: 'Team B', defaultModel: 'gpt-5.4' },
+ ])
+ models.mockImplementation(async connectionRef => {
+ if (connectionRef === 'codex-bbb') {
+ throw Object.assign(
+ new Error('This request limit has been reached. Try again in 9 seconds.'),
+ { status: 429, code: 'rate_limited', retryAfterSeconds: 9 }
+ )
+ }
+ return [{ model: 'gpt-5.1', enabled: true, stale: false }]
+ })
+ try {
+ await renderWizard()
+ await walkToModelStep({ agentName: 'catalog-binding' })
+ await selectCodexSubscription()
+ fireEvent.click(screen.getByRole('button', { name: /Team A/i }))
+ fireEvent.click(screen.getByRole('option', { name: /Team B/i }))
+ // Witness: B's catalog was requested and its throttle is on screen.
+ expect(await screen.findByText(/Try again in 9 seconds/)).toBeInTheDocument()
+ expect(models).toHaveBeenCalledWith('codex-bbb', expect.anything())
+ fireEvent.click(screen.getByLabelText('Default model', { selector: '#llm-primary-model' }))
+ const offered = screen
+ .queryAllByRole('option')
+ .filter(option => /gpt-5\.1/.test(option.textContent ?? ''))
+ for (const option of offered) expect(option).toHaveTextContent(/out of allowlist/i)
+ } finally {
+ connections.mockImplementation(defaultConnections!)
+ models.mockImplementation(defaultModels!)
+ }
+ }, 15_000)
+
+ it('blocks Next when a reloaded catalog offers no models instead of keeping the previous model', async () => {
+ const models = vi.mocked(listCodexConnectionModels)
+ const defaultModels = models.getMockImplementation()
+ models.mockResolvedValue([{ model: 'gpt-5.1', enabled: true, stale: false }])
+ try {
+ await renderWizard()
+ await walkToModelStep({ agentName: 'empty-catalog' })
+ await selectCodexSubscription()
+ // Witness: the first catalog makes the selected model valid.
+ await waitFor(() => expect(screen.getByRole('button', { name: 'Next' })).not.toBeDisabled())
+ const loadsBefore = models.mock.calls.length
+
+ // Leave the step and come back; the reloaded catalog is now empty.
+ models.mockResolvedValue([])
+ fireEvent.click(screen.getByRole('button', { name: 'Back' }))
+ fireEvent.click(screen.getByRole('button', { name: 'Next' }))
+ await waitFor(() => expect(models.mock.calls.length).toBeGreaterThan(loadsBefore))
+ expect(screen.getByRole('button', { name: /Team A/i })).toBeInTheDocument()
+ await waitFor(() => expect(screen.getByRole('button', { name: 'Next' })).toBeDisabled())
+ } finally {
+ models.mockImplementation(defaultModels!)
+ }
+ }, 15_000)
+
+ it('shows a capability probe failure and its Retry on the model step that runs the probe', async () => {
+ grokCapabilityState.error = new Error('Try again in 7 seconds.')
+ await renderWizard()
+ // Step 0 does not run the probe, so it has nothing to report.
+ expect(screen.getByLabelText(/^Agent name/, { selector: 'input' })).toBeInTheDocument()
+ expect(screen.queryByText(/Provider availability could not be checked/)).toBeNull()
+ await walkToModelStep({ agentName: 'capability-failure' })
+ const notice = (await screen.findByText(/Provider availability could not be checked/)).closest(
+ '[role="alert"]'
+ ) as HTMLElement
+ expect(notice).toHaveTextContent('Try again in 7 seconds.')
+ fireEvent.click(within(notice).getByRole('button', { name: 'Retry' }))
+ expect(grokCapabilityState.retry).toHaveBeenCalledTimes(1)
+ }, 15_000)
+
it('loads inventories only at the model step and keeps the provider through a throttle and explicit retry', async () => {
mockGrokGrant()
vi.mocked(listGrokSubscriptionConnections).mockRejectedValueOnce(
diff --git a/control-ui/components/__tests__/PluginWorkloadSdkPage.test.tsx b/control-ui/components/__tests__/PluginWorkloadSdkPage.test.tsx
index 08e857111..32ecdb31d 100644
--- a/control-ui/components/__tests__/PluginWorkloadSdkPage.test.tsx
+++ b/control-ui/components/__tests__/PluginWorkloadSdkPage.test.tsx
@@ -11,7 +11,7 @@ import {
listWorkflowGrants,
searchPluginWorkloadSdkInvocations,
} from '@lib/api'
-import { listGrokSubscriptionConnections } from '@lib/grokSubscription'
+import { listGrokConnectionModels, listGrokSubscriptionConnections } from '@lib/grokSubscription'
import PluginWorkloadSdkPage from '../../app/plugin-workload-sdk/page'
const mocks = vi.hoisted(() => ({
@@ -308,6 +308,69 @@ describe('Plugin Workload SDK operator page', () => {
expect(within(provider).queryByRole('option', { name: /xAI Grok Subscription/i })).toBeNull()
})
+ it('cannot add one subscription connection model under another connection whose catalog throttles', async () => {
+ grokCapability.enabled = true
+ vi.mocked(listGrokSubscriptionConnections).mockResolvedValue([
+ {
+ connectionKey: 'team-grok',
+ displayName: 'Team Grok',
+ status: 'connected',
+ catalogStatus: 'ready',
+ },
+ {
+ connectionKey: 'team-grok-b',
+ displayName: 'Team Grok B',
+ status: 'connected',
+ catalogStatus: 'ready',
+ },
+ ] as never)
+ const models = vi.mocked(listGrokConnectionModels)
+ const defaultModels = models.getMockImplementation()
+ models.mockImplementation(async connectionRef => {
+ if (connectionRef === 'team-grok-b') {
+ throw Object.assign(new Error('Try again in 8 seconds.'), {
+ status: 429,
+ code: 'rate_limited',
+ retryAfterSeconds: 8,
+ })
+ }
+ return [{ model: 'grok-4.6', enabled: true, stale: false }]
+ })
+ try {
+ render(<PluginWorkloadSdkPage />)
+ const create = await screen.findByRole('button', { name: 'New grant' })
+ await waitFor(() => expect(create).toBeEnabled())
+ fireEvent.click(create)
+ const dialog = screen.getByRole('dialog', { name: 'New SDK grant' })
+ fireEvent.change(within(dialog).getByRole('combobox', { name: /^Capability family\b/ }), {
+ target: { value: 'promptBridge' },
+ })
+ fireEvent.change(within(dialog).getByRole('combobox', { name: 'Target provider' }), {
+ target: { value: 'grok-subscription' },
+ })
+ const connection = await within(dialog).findByRole('combobox', { name: /grok subscription/i })
+ await within(connection).findByRole('option', { name: /Team Grok B/ })
+ const targetModel = within(dialog).getByRole('combobox', { name: /^Target model\b/ })
+ fireEvent.change(connection, { target: { value: 'team-grok' } })
+ expect(
+ await within(targetModel).findByRole('option', { name: 'grok-4.6' })
+ ).toBeInTheDocument()
+ fireEvent.change(targetModel, { target: { value: 'grok-4.6' } })
+ // Witness: A's model is genuinely selected and addable before the switch.
+ expect(targetModel).toHaveValue('grok-4.6')
+ expect(within(dialog).getByRole('button', { name: 'Add target' })).toBeEnabled()
+
+ fireEvent.change(connection, { target: { value: 'team-grok-b' } })
+ // Witness: B's catalog was requested and its throttle is on screen.
+ expect(await within(dialog).findByText('Try again in 8 seconds.')).toBeInTheDocument()
+ expect(models).toHaveBeenCalledWith('team-grok-b', expect.anything())
+ expect(within(targetModel).queryByRole('option', { name: 'grok-4.6' })).toBeNull()
+ expect(within(dialog).getByRole('button', { name: 'Add target' })).toBeDisabled()
+ } finally {
+ models.mockImplementation(defaultModels!)
+ }
+ })
+
it('offers Grok grants in the SDK picker when the Grok flag is on', async () => {
grokCapability.enabled = true
render(<PluginWorkloadSdkPage />)
diff --git a/control-ui/e2e/qa-recorder-admin-rate-limit-recovery.spec.ts b/control-ui/e2e/qa-recorder-admin-rate-limit-recovery.spec.ts
index 9a7c95226..5292495f9 100644
--- a/control-ui/e2e/qa-recorder-admin-rate-limit-recovery.spec.ts
+++ b/control-ui/e2e/qa-recorder-admin-rate-limit-recovery.spec.ts
@@ -734,13 +734,11 @@ test.describe('optional QA recorder: administrative rate-limit journeys', () =>
message: 'Respect the observed server Retry-After deadline before the visible retry',
})
.toBeGreaterThanOrEqual(retryAt)
- const recovered = INVENTORIES.map(path =>
- page.waitForResponse(response => isRead(response, path))
- )
+ // The shared background recovery may read the denied inventory before or
+ // after this click; Retry reuses that result instead of forcing a second
+ // read, so assert the quota invariant rather than an exact read count.
+ const readsBeforeDeadline = 3
await alert.getByRole('button', { name: 'Retry', exact: true }).click()
- expect((await Promise.all(recovered)).map(response => response.status())).toEqual([
- 200, 200,
- ])
await expect(dialog.getByRole('alert')).toHaveCount(0)
await expect(
dialog.getByRole('status').filter({ hasText: 'Loading subscription options…' })
@@ -748,18 +746,29 @@ test.describe('optional QA recorder: administrative rate-limit journeys', () =>
await expect(dialog.getByLabel('Current model', { exact: true })).toContainText(
fixture.draftModelName
)
+ const afterDeadline = coldSession.snapshot().slice(readsBeforeDeadline)
+ expect(afterDeadline.length, 'Recovery reads the denied inventory').toBeGreaterThan(0)
expect(
- coldSession.snapshot(),
- 'One visible recovery reloads only the two inventories'
- ).toHaveLength(5)
+ afterDeadline.map(read => read.status),
+ 'No read after the Retry-After deadline is throttled again'
+ ).not.toContain(429)
+ expect(
+ afterDeadline.length,
+ 'Recovery and the visible Retry stay within one quota window'
+ ).toBeLessThanOrEqual(fixture.quota)
+ expect(
+ afterDeadline.every(read => read.path !== CAPABILITIES),
+ 'Recovery reloads only inventories'
+ ).toBe(true)
expect(coldSession.snapshot().filter(read => read.path === CAPABILITIES)).toHaveLength(1)
await screenshotAndLog(page, testInfo, 'admin-rate-limit-recovered-draft')
+ const readsAfterRecovery = coldSession.snapshot().length
await cancelEditor(page, owned, fixture)
await agentSections(page, owned, fixture)
expect(
coldSession.snapshot(),
'Agent identity/access/connectors stay usable after the real throttle'
- ).toHaveLength(5)
+ ).toHaveLength(readsAfterRecovery)
} finally {
coldSession.stop()
}
diff --git a/control-ui/lib/__tests__/readRequestCache.test.ts b/control-ui/lib/__tests__/readRequestCache.test.ts
index 1cfb82076..e300ec4a8 100644
--- a/control-ui/lib/__tests__/readRequestCache.test.ts
+++ b/control-ui/lib/__tests__/readRequestCache.test.ts
@@ -4,6 +4,7 @@ import {
apiSend,
clearAdminAuthToken,
loginControlUI,
+ logoutControlUI,
setControlUIReadPrincipal,
setGlobalAuthErrorHandler,
} from '../api'
@@ -369,50 +370,124 @@ describe('bounded metadata read reuse', () => {
const listener = new BroadcastChannel('control-ui-read-metadata-invalidation')
const received: unknown[] = []
listener.onmessage = event => received.push(event.data)
+ const sends = vi.spyOn(BroadcastChannel.prototype, 'postMessage')
+ try {
+ fetchMock.mockResolvedValueOnce(success({ principal: 'one' }))
+ await expect(apiGet('/api/v1/admin/metadata', {}, metadataOptions)).resolves.toEqual({
+ principal: 'one',
+ })
- fetchMock.mockResolvedValueOnce(success({ principal: 'one' }))
- await expect(apiGet('/api/v1/admin/metadata', {}, metadataOptions)).resolves.toEqual({
- principal: 'one',
- })
-
- clearAdminAuthToken()
- await vi.advanceTimersByTimeAsync(0)
- expect(received).toEqual([{ type: 'session-invalidation' }])
- expect(JSON.stringify(received)).not.toContain('admin-one')
-
- setControlUIReadPrincipal('admin-one', 'admin')
- setControlUIReadPrincipal('admin-two', 'admin')
- await vi.advanceTimersByTimeAsync(0)
- expect(received).toEqual([{ type: 'session-invalidation' }, { type: 'session-invalidation' }])
+ clearAdminAuthToken()
+ expect(sends).toHaveBeenCalledTimes(1)
+ await vi.waitFor(() => expect(received).toEqual([{ type: 'session-invalidation' }]))
+ expect(JSON.stringify(received)).not.toContain('admin-one')
+
+ setControlUIReadPrincipal('admin-one', 'admin')
+ setControlUIReadPrincipal('admin-two', 'admin')
+ expect(sends).toHaveBeenCalledTimes(2)
+ await vi.waitFor(() =>
+ expect(received).toEqual([
+ { type: 'session-invalidation' },
+ { type: 'session-invalidation' },
+ ])
+ )
- fetchMock.mockResolvedValueOnce(success({ principal: 'two' }))
- await expect(apiGet('/api/v1/admin/metadata', {}, metadataOptions)).resolves.toEqual({
- principal: 'two',
- })
- listener.close()
+ fetchMock.mockResolvedValueOnce(success({ principal: 'two' }))
+ await expect(apiGet('/api/v1/admin/metadata', {}, metadataOptions)).resolves.toEqual({
+ principal: 'two',
+ })
+ } finally {
+ listener.close()
+ }
})
it('invalidates on a remote session change without rebroadcast or caching an unverified identity', async () => {
const remoteTab = new BroadcastChannel('control-ui-read-metadata-invalidation')
- const rebroadcasts: unknown[] = []
- remoteTab.onmessage = event => rebroadcasts.push(event.data)
- fetchMock.mockResolvedValueOnce(success({ revision: 'old-tab' }))
- await apiGet('/api/v1/admin/metadata', {}, metadataOptions)
- remoteTab.postMessage({ type: 'session-invalidation' })
- await vi.advanceTimersByTimeAsync(0)
- expect(getReadRequestPrincipal()).toBeNull()
- expect(rebroadcasts).toEqual([])
- fetchMock
- .mockResolvedValueOnce(success({ revision: 'new-tab' }))
- .mockResolvedValueOnce(success({ revision: 'fresh' }))
- await expect(apiGet('/api/v1/admin/metadata', {}, metadataOptions)).resolves.toEqual({
- revision: 'new-tab',
- })
- await expect(apiGet('/api/v1/admin/metadata', {}, metadataOptions)).resolves.toEqual({
- revision: 'fresh',
- })
- expect(fetchMock).toHaveBeenCalledTimes(3)
- remoteTab.close()
+ try {
+ fetchMock.mockResolvedValueOnce(success({ revision: 'old-tab' }))
+ await apiGet('/api/v1/admin/metadata', {}, metadataOptions)
+ const sends = vi.spyOn(BroadcastChannel.prototype, 'postMessage')
+ remoteTab.postMessage({ type: 'session-invalidation' })
+ // Witness: the message was delivered and this tab dropped its principal.
+ await vi.waitFor(() => expect(getReadRequestPrincipal()).toBeNull())
+ expect(sends.mock.contexts.filter(channel => channel !== remoteTab)).toHaveLength(0)
+ fetchMock
+ .mockResolvedValueOnce(success({ revision: 'new-tab' }))
+ .mockResolvedValueOnce(success({ revision: 'fresh' }))
+ await expect(apiGet('/api/v1/admin/metadata', {}, metadataOptions)).resolves.toEqual({
+ revision: 'new-tab',
+ })
+ await expect(apiGet('/api/v1/admin/metadata', {}, metadataOptions)).resolves.toEqual({
+ revision: 'fresh',
+ })
+ expect(fetchMock).toHaveBeenCalledTimes(3)
+ } finally {
+ remoteTab.close()
+ }
+ })
+
+ it('answers the post-invalidation 401 locally so logged-out tabs cannot invalidate each other forever', async () => {
+ const remoteTab = new BroadcastChannel('control-ui-read-metadata-invalidation')
+ const received: unknown[] = []
+ remoteTab.onmessage = event => received.push(event.data)
+ const sends = vi.spyOn(BroadcastChannel.prototype, 'postMessage')
+ const sentByThisTab = () => sends.mock.contexts.filter(channel => channel !== remoteTab).length
+ try {
+ // The other tab logged out: this tab drops its principal on the message.
+ remoteTab.postMessage({ type: 'session-invalidation' })
+ await vi.waitFor(() => expect(getReadRequestPrincipal()).toBeNull())
+
+ // Its /auth/me re-check now answers 401, which clears the token again.
+ setReadRequestCacheEntry('post-invalidation-entry', { stale: true }, 30_000)
+ clearAdminAuthToken()
+ // Witness: the local clear ran and dropped the entry cached after the message.
+ expect(getReadRequestCacheEntry('post-invalidation-entry')).toBeUndefined()
+ expect(sentByThisTab()).toBe(0)
+
+ // A verified tab that logs out still tells the others exactly once.
+ setControlUIReadPrincipal('admin-one', 'admin')
+ clearAdminAuthToken()
+ expect(sentByThisTab()).toBe(1)
+ await vi.waitFor(() => expect(received).toEqual([{ type: 'session-invalidation' }]))
+ } finally {
+ remoteTab.close()
+ }
+ })
+
+ it('tells peer tabs about the committed cookie change after a login or logout POST', async () => {
+ const peerTab = new BroadcastChannel('control-ui-read-metadata-invalidation')
+ const received: unknown[] = []
+ peerTab.onmessage = event => received.push(event.data)
+ const sends = vi.spyOn(BroadcastChannel.prototype, 'postMessage')
+ const invalidation = { type: 'session-invalidation' }
+ try {
+ let commitLogin: (response: Response) => void = () => {}
+ fetchMock.mockReturnValueOnce(new Promise<Response>(resolve => (commitLogin = resolve)))
+ const login = loginControlUI('operator', 'unit-test-password')
+ // Pre-POST clear of the verified principal; a peer may now reconfirm the old cookie.
+ expect(sends).toHaveBeenCalledTimes(1)
+ await vi.waitFor(() => expect(received).toEqual([invalidation]))
+ commitLogin(success({ me: { id: 'admin-two', role: 'admin' } }))
+ await login
+ expect(sends).toHaveBeenCalledTimes(2)
+ await vi.waitFor(() => expect(received).toEqual([invalidation, invalidation]))
+
+ setControlUIReadPrincipal('admin-two', 'admin')
+ sends.mockClear()
+ received.length = 0
+ let commitLogout: (response: Response) => void = () => {}
+ fetchMock.mockReturnValueOnce(new Promise<Response>(resolve => (commitLogout = resolve)))
+ const logout = logoutControlUI()
+ expect(sends).toHaveBeenCalledTimes(1)
+ await vi.waitFor(() => expect(received).toEqual([invalidation]))
+ commitLogout(success({ ok: true }))
+ await logout
+ expect(sends).toHaveBeenCalledTimes(2)
+ await vi.waitFor(() => expect(received).toEqual([invalidation, invalidation]))
+ expect(fetchMock).toHaveBeenCalledTimes(2)
+ } finally {
+ peerTab.close()
+ }
})
it('clears cached reads on successful login even when the principal is unchanged', async () => {
diff --git a/control-ui/lib/api.ts b/control-ui/lib/api.ts
index e25da01a3..832b9ed22 100644
--- a/control-ui/lib/api.ts
+++ b/control-ui/lib/api.ts
@@ -830,8 +830,8 @@ export type AdminLoginResponse = {
me: { id: string; username?: string; email?: string | null; role: 'admin' }
}
-export function clearAdminAuthToken(): void {
- clearReadRequestPrincipal()
+export function clearAdminAuthToken(options: { sessionChanged?: boolean } = {}): void {
+ clearReadRequestPrincipal(options)
if (typeof window === 'undefined') return
// Remove the legacy browser-readable admin JWT if it exists. Active admin
// sessions now live in an HttpOnly cookie set by control-api.
@@ -858,7 +858,8 @@ export async function loginControlUI(
throw new Error(`${res.status} ${res.statusText} - ${text}`)
}
const data = (await res.json()) as AdminLoginResponse
- clearAdminAuthToken()
+ // The shared cookie now belongs to the new session; tell every peer tab.
+ clearAdminAuthToken({ sessionChanged: true })
return data
}
@@ -870,7 +871,7 @@ export async function logoutControlUI(): Promise<void> {
// Logout is best-effort: a stale token or backend revoke failure should not
// keep the local admin session alive or surface a dev/runtime overlay.
} finally {
- clearAdminAuthToken()
+ clearAdminAuthToken({ sessionChanged: true })
}
}
diff --git a/control-ui/lib/hooks/__tests__/useSubscriptionCapabilities.cache.test.tsx b/control-ui/lib/hooks/__tests__/useSubscriptionCapabilities.cache.test.tsx
new file mode 100644
index 000000000..4736c75ce
--- /dev/null
+++ b/control-ui/lib/hooks/__tests__/useSubscriptionCapabilities.cache.test.tsx
@@ -0,0 +1,63 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { act, cleanup, renderHook, waitFor } from '@testing-library/react'
+import { setControlUIReadPrincipal } from '../../api'
+import { __resetReadRequestCacheForTests } from '../../readRequestCache'
+import { SUBSCRIPTION_CAPABILITIES_API_PATH } from '../../subscriptionCapabilities'
+import { useSubscriptionCapabilities } from '../useSubscriptionCapabilities'
+
+const capabilitiesBody = {
+ providers: {
+ 'codex-subscription': { enabled: true },
+ 'grok-subscription': { enabled: true },
+ },
+}
+
+function capabilityReads(fetchMock: ReturnType<typeof vi.fn>): number {
+ return fetchMock.mock.calls.filter(([url]) =>
+ String(url).includes(SUBSCRIPTION_CAPABILITIES_API_PATH)
+ ).length
+}
+
+describe('useSubscriptionCapabilities with the real read cache', () => {
+ let fetchMock: ReturnType<typeof vi.fn>
+
+ beforeEach(() => {
+ __resetReadRequestCacheForTests()
+ setControlUIReadPrincipal('admin-one', 'admin')
+ fetchMock = vi.fn()
+ vi.stubGlobal('fetch', fetchMock)
+ })
+
+ afterEach(() => {
+ cleanup()
+ __resetReadRequestCacheForTests()
+ vi.unstubAllGlobals()
+ })
+
+ it('answers Retry from a result another consumer already cached instead of reading again', async () => {
+ fetchMock.mockResolvedValueOnce(
+ new Response(JSON.stringify({ error: 'Unavailable' }), {
+ status: 503,
+ headers: { 'content-type': 'application/json' },
+ })
+ )
+ const failed = renderHook(() => useSubscriptionCapabilities())
+ await waitFor(() => expect(failed.result.current.error?.status).toBe(503))
+
+ fetchMock.mockResolvedValueOnce(
+ new Response(JSON.stringify(capabilitiesBody), {
+ status: 200,
+ headers: { 'content-type': 'application/json' },
+ })
+ )
+ const recovered = renderHook(() => useSubscriptionCapabilities())
+ await waitFor(() => expect(recovered.result.current.capabilities).not.toBeNull())
+ expect(capabilityReads(fetchMock)).toBe(2)
+
+ act(() => failed.result.current.retry())
+ // Witness: the failed consumer recovers and shows the cached capabilities.
+ await waitFor(() => expect(failed.result.current.capabilities).toEqual(capabilitiesBody))
+ expect(failed.result.current.error).toBeNull()
+ expect(capabilityReads(fetchMock)).toBe(2)
+ })
+})
diff --git a/control-ui/lib/hooks/__tests__/useSubscriptionCapabilities.test.tsx b/control-ui/lib/hooks/__tests__/useSubscriptionCapabilities.test.tsx
index ed9851f2e..a248d973e 100644
--- a/control-ui/lib/hooks/__tests__/useSubscriptionCapabilities.test.tsx
+++ b/control-ui/lib/hooks/__tests__/useSubscriptionCapabilities.test.tsx
@@ -43,7 +43,8 @@ describe('useSubscriptionCapabilities', () => {
await waitFor(() =>
expect(result.current.capabilities?.providers['grok-subscription'].enabled).toBe(true)
)
- expect(load).toHaveBeenNthCalledWith(2, { refresh: true, signal: expect.any(AbortSignal) })
+ // Retry re-runs the load through the shared cache; it never forces a refresh.
+ expect(load).toHaveBeenNthCalledWith(2, { signal: expect.any(AbortSignal) })
})
it('keeps a previously confirmed provider enabled during a transient failure', async () => {
diff --git a/control-ui/lib/hooks/useSubscriptionCapabilities.ts b/control-ui/lib/hooks/useSubscriptionCapabilities.ts
index b84949815..9005adbdd 100644
--- a/control-ui/lib/hooks/useSubscriptionCapabilities.ts
+++ b/control-ui/lib/hooks/useSubscriptionCapabilities.ts
@@ -32,7 +32,9 @@ export function useSubscriptionCapabilities(
const enabledRef = useRef(enabled)
enabledRef.current = enabled
- const load = useCallback(async (refresh: boolean) => {
+ // Retry only re-runs the load. Forcing a refresh would discard a result that
+ // another consumer's recovery already cached and spend a second read.
+ const load = useCallback(async () => {
if (!enabledRef.current) return
const controller =
controllerRef.current && !controllerRef.current.signal.aborted
@@ -43,7 +45,7 @@ export function useSubscriptionCapabilities(
setLoading(true)
setError(null)
try {
- const next = await loadSubscriptionCapabilities({ refresh, signal: controller.signal })
+ const next = await loadSubscriptionCapabilities({ signal: controller.signal })
if (controller.signal.aborted || requestRef.current !== requestId) return
setCapabilities(next)
recoveryAttemptsRef.current = 0
@@ -64,7 +66,7 @@ export function useSubscriptionCapabilities(
setLoading(false)
return
}
- void load(retryNonce > 0)
+ void load()
return () => {
requestRef.current += 1
controllerRef.current?.abort()
@@ -82,7 +84,7 @@ export function useSubscriptionCapabilities(
const delay = Math.max(0, retryAtMs - Date.now())
const timer = setTimeout(() => {
recoveryAttemptsRef.current += 1
- void load(false)
+ void load()
}, delay)
return () => clearTimeout(timer)
}, [enabled, error, load])
diff --git a/control-ui/lib/readRequestCache.ts b/control-ui/lib/readRequestCache.ts
index e24bcc2e9..7cca1f4eb 100644
--- a/control-ui/lib/readRequestCache.ts
+++ b/control-ui/lib/readRequestCache.ts
@@ -89,11 +89,20 @@ export function setReadRequestPrincipal(principalId: string, scope: string): voi
if (wasVerified) channel?.postMessage({ type: 'session-invalidation' })
}
-export function clearReadRequestPrincipal(): void {
+export function clearReadRequestPrincipal(options: { sessionChanged?: boolean } = {}): void {
+ const wasVerified = principal !== null
principal = null
clearReadRequestCache()
invalidationHandler?.()
- ensureChannel()?.postMessage({ type: 'session-invalidation' })
+ const channel = ensureChannel()
+ // Only a locally verified principal or a committed cookie change is news to
+ // other tabs. A tab already cleared by a remote invalidation answers its /me
+ // 401 here; rebroadcasting that would make logged-out tabs invalidate one
+ // another indefinitely. A peer may have reconfirmed the old cookie while a
+ // login/logout POST was pending, so the committed change always propagates.
+ if (wasVerified || options.sessionChanged) {
+ channel?.postMessage({ type: 'session-invalidation' })
+ }
}
export function clearReadRequestCache(): void {
diff --git a/control-ui/package-lock.json b/control-ui/package-lock.json
index da72f227f..236bd94a0 100644
--- a/control-ui/package-lock.json
+++ b/control-ui/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-control-ui",
- "version": "0.1.710",
+ "version": "0.1.711",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-control-ui",
- "version": "0.1.710",
+ "version": "0.1.711",
"dependencies": {
"@clerum/display-field": "file:../packages/display-field",
"@clerum/frontend-components": "file:../packages/frontend-components",
diff --git a/control-ui/package.json b/control-ui/package.json
index 6576c8a4f..0895d2ba5 100644
--- a/control-ui/package.json
+++ b/control-ui/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-control-ui",
- "version": "0.1.710",
+ "version": "0.1.711",
"private": true,
"scripts": {
"dev": "NEXT_IGNORE_INCORRECT_LOCKFILE=1 next dev",
diff --git a/docs/architecture/administrative-rate-limits.md b/docs/architecture/administrative-rate-limits.md
index caaf904ee..2cfad1ae4 100644
--- a/docs/architecture/administrative-rate-limits.md
+++ b/docs/architecture/administrative-rate-limits.md
@@ -61,6 +61,19 @@ Code defaults and base/minikube ConfigMap literals must agree. A code-only
increase can be defeated by an older deployment override. This document and
changed manifests are source artifacts, not confirmation of a rollout.
+## SDK verification budget
+
+The SDK pre-auth gates and the internal SDK edge verify a bearer token to
+choose a bucket, so the IP600 ceiling cannot deny before that verification.
+A per-source-IP verification budget runs first on both SDK routers. It counts
+only requests that present a bearer token, uses
+CONTROL_API_PLUGIN_SDK_AUTHENTICATED_PREAUTH_PER_MIN (6000) as its limit, and
+denies further tokens from that IP without verifying them. Invalid credentials
+still stop at IP600, and valid callers behind a flooded IP keep passing until
+the IP has spent 6000 verifications in the minute. Verified principals that
+share one source IP share this budget, and the internal SDK edge allowance
+cannot exceed it from one IP.
+
## SDK operation multiplicity
A healthy static-secret attempt performs reissue, pre-Secret introspection and