Skip to content

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

TypeScript

fix(control-api): rename refresh race label to race_lost (BR-12)

Diego Zacariasf47751217a84
diff --git a/control-api/package-lock.json b/control-api/package-lock.json
index a58ec0225..ec2042166 100644
--- a/control-api/package-lock.json
+++ b/control-api/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-control-api",
- "version": "0.1.824",
+ "version": "0.1.825",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-control-api",
- "version": "0.1.824",
+ "version": "0.1.825",
"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 7b6dd017b..c6a69e4f7 100644
--- a/control-api/package.json
+++ b/control-api/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-control-api",
- "version": "0.1.824",
+ "version": "0.1.825",
"description": "Internal Clerum control plane REST API + UI for managing CRDs and secrets",
"main": "dist/main.js",
"engines": {
diff --git a/control-api/src/observability/metrics.ts b/control-api/src/observability/metrics.ts
index 060edb03b..113c92c69 100644
--- a/control-api/src/observability/metrics.ts
+++ b/control-api/src/observability/metrics.ts
@@ -190,14 +190,16 @@ export const oauthBrokerJwtIssueTotal = getOrCreateCounter({
// Refresh endpoint outcomes (also the label of the duration histogram below).
// The 401 body stays opaque; the label is emitted server-side in a `finally`.
-// Label values, aligned with the re-issue counter where the outcome is shared:
+// Label values (binding outcomes share their names with the re-issue counter):
// success — token rotated, fresh token set minted
-// failed — missing bearer; signature/claims/expiry rejected or
-// jti already consumed at verify time; unhandled error
+// failed — missing bearer; signature/claims/expiry rejected;
+// replay of a jti already consumed at verify time;
+// unhandled error
// host_unavailable — Host lookup failed transiently (503, jti not consumed)
// host_mismatch — HCC chain's Host is gone or was recreated (new uid)
// lineage_without_audience — hosts-namespace standalone chain without HCC audience
-// revoked — jti consumed concurrently between verify and consume
+// race_lost — jti consumed concurrently between verify and consume
+// (not the re-issue `revoked`, which also covers replay)
// Rate-limited requests never reach the handler and are not counted here.
export const mcpHostJwtRefreshTotal = getOrCreateCounter({
name: 'workflow_auth_refresh_total',
@@ -221,7 +223,8 @@ export const mcpHostJwtRefreshDurationSeconds = getOrCreateHistogram({
// invalid_sig — JWT signature / iss / aud / scope / format rejected
// invalid_claims — JWT verified but failed refresh-token claim validation
// expired_beyond_reissue_grace — signed refresh token is too old to reissue
-// revoked — jti already present in workflow_revoked_refresh_jtis
+// revoked — jti already present in workflow_revoked_refresh_jtis at verify
+// time, or consumed concurrently between verify and consume
// mismatch — recipe_name body did not match JWT sub's recipe component
// bad_request — missing/malformed body or bearer token
// host_unavailable — Host lookup failed transiently (503, jti not consumed)
diff --git a/control-api/src/routes/mcp-host/renewal/refresh.routes.ts b/control-api/src/routes/mcp-host/renewal/refresh.routes.ts
index fe28ab65f..cc7fe7746 100644
--- a/control-api/src/routes/mcp-host/renewal/refresh.routes.ts
+++ b/control-api/src/routes/mcp-host/renewal/refresh.routes.ts
@@ -37,14 +37,16 @@ export function createMcpHostRefreshRoutes(gateway: RenewalHostGateway): Router
(req, res, next) => {
void (async () => {
const refreshStart = process.hrtime.bigint()
- // Values mirror the reissue route's labels so the two can be compared.
+ // Binding labels share their names with the reissue counter so the two
+ // can be compared. `race_lost` is refresh-only and is not reissue's
+ // `revoked`: here a jti already consumed at verify time lands in `failed`.
type ResultLabel =
| 'success'
| 'failed'
| 'host_unavailable'
| 'host_mismatch'
| 'lineage_without_audience'
- | 'revoked'
+ | 'race_lost'
let resultLabel: ResultLabel = 'failed'
try {
const token = extractBearerToken(req)
@@ -94,7 +96,7 @@ export function createMcpHostRefreshRoutes(gateway: RenewalHostGateway): Router
const consumed = await consumeRefreshJti(claims.jti, claims.exp)
if (!consumed) {
- resultLabel = 'revoked'
+ resultLabel = 'race_lost'
req.log?.info(
{ event: 'auth_denied', reason: 'jti_race_lost', route: 'workflow_auth_refresh' },
'auth denied'
diff --git a/control-api/test/routes.mcp-host.user-approval-requests.test.ts b/control-api/test/routes.mcp-host.user-approval-requests.test.ts
index 4292d6da7..0146f7096 100644
--- a/control-api/test/routes.mcp-host.user-approval-requests.test.ts
+++ b/control-api/test/routes.mcp-host.user-approval-requests.test.ts
@@ -317,7 +317,7 @@ describe('User Approval Request Routes', () => {
'host_unavailable',
'host_mismatch',
'lineage_without_audience',
- 'revoked',
+ 'race_lost',
]
const out: Record<string, number> = {}
for (const label of labels) out[label] = await refreshCount(label)
@@ -410,7 +410,7 @@ describe('User Approval Request Routes', () => {
await expectOnlyIncremented(before, 'lineage_without_audience')
})
- it('counts a jti consumed between verify and consume as revoked', async () => {
+ it('counts a jti consumed between verify and consume as race_lost', async () => {
const { refreshToken } = issueTestTokens()
conflictOnNextRefreshJtiInsert = true
const before = await snapshot()
@@ -418,7 +418,18 @@ describe('User Approval Request Routes', () => {
const res = await postRefresh(refreshToken)
expect(res.status).toBe(401)
- await expectOnlyIncremented(before, 'revoked')
+ await expectOnlyIncremented(before, 'race_lost')
+ })
+
+ it('counts a replay of an already-rotated refresh token as failed, not race_lost', async () => {
+ const { refreshToken } = issueTestTokens()
+ expect((await postRefresh(refreshToken)).status).toBe(200)
+ const before = await snapshot()
+
+ const res = await postRefresh(refreshToken)
+
+ expect(res.status).toBe(401)
+ await expectOnlyIncremented(before, 'failed')
})
it('keeps an invalid refresh token on the failed label', async () => {