Skip to content

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

TypeScript

fix(control-api): remove dead classifyProactiveTokenDecision (R1-M1)

Diego Zacarias101ab5cb21f8
diff --git a/control-api/package-lock.json b/control-api/package-lock.json
index 5369c8ec4..364f3ea20 100644
--- a/control-api/package-lock.json
+++ b/control-api/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-control-api",
- "version": "0.1.657",
+ "version": "0.1.658",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-control-api",
- "version": "0.1.657",
+ "version": "0.1.658",
"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 765d5728c..0adc48882 100644
--- a/control-api/package.json
+++ b/control-api/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-control-api",
- "version": "0.1.657",
+ "version": "0.1.658",
"description": "Internal Clerum control plane REST API + UI for managing CRDs and secrets",
"main": "dist/main.js",
"engines": {
diff --git a/control-api/src/oauth/proactiveRefreshPolicy.ts b/control-api/src/oauth/proactiveRefreshPolicy.ts
index d9dfe2eeb..37e15bce9 100644
--- a/control-api/src/oauth/proactiveRefreshPolicy.ts
+++ b/control-api/src/oauth/proactiveRefreshPolicy.ts
@@ -1,87 +1,19 @@
import type { GetAccessTokenResult } from './tokenHelper.js'
/**
- * Pure decision layer for the PROACTIVE remote-token refresh + DCR client
- * lifecycle sweep (mini-spec L §4/§5). This module holds NO IO: every function
- * is `(input, now, buffers) → decision`, so the two decision tables are
+ * Pure decision helpers for the PROACTIVE remote-token refresh + DCR client
+ * lifecycle sweep (mini-spec L §4/§5). This module holds NO IO, so each helper is
* property-testable in isolation (pr-discipline T2) and the cron
* (`services/oauthProactiveRefreshCron.ts`) stays a thin orchestrator over them.
*
- * The refresh machinery itself is NOT reimplemented here — the cron feeds each
- * `refresh` decision into the existing reactive `getAccessToken` (mini-spec §6.2).
+ * It does NOT decide WHICH grants to refresh: the proactive candidate selection
+ * is the SQL `WHERE` of `listRemoteGrantsInProactiveWindow` (`store.ts`) plus the
+ * staleness check inside the reactive `getAccessToken` the cron feeds each
+ * candidate to (mini-spec §6.2). What lives here is `resultToOutcome` (map a
+ * `getAccessToken` result to a metric outcome, §4) and `classifyDcrSecretDecision`
+ * (the DCR client-secret warn/expire decision, §5).
*/
-// ─── §4 · Proactive token-refresh decision ──────────────────────────────────
-
-/**
- * The subset of an `oauth_grants` row the token decision depends on. Derived by
- * the caller from the enumerated row; `accessTokenExpiresAt` is the authoritative
- * expiry (NULL ⇒ the AS never supplied `expires_in`).
- */
-export interface ProactiveTokenInput {
- /** Authoritative access-token expiry; NULL ⇒ no computable threshold (P1). */
- accessTokenExpiresAt: Date | null
- /** Whether a refresh token is stored for the grant. */
- hasRefreshToken: boolean
- /** `spec.oauth.supportsRefresh`, fail-closed from pinned metadata (D-8). */
- supportsRefresh: boolean
- /** Whether the grant is eligible for unattended (background) use (P7). */
- eligibleForBackground: boolean
-}
-
-/**
- * A noop carries WHY it was a noop so the cron can emit a precise metric/log
- * without re-deriving the reason. `reactive_window` = the grant is inside the
- * REACTIVE window (`remaining ≤ Br`); the reactive path owns it, not the cron.
- */
-export type ProactiveTokenDecision =
- | {
- kind: 'noop'
- reason: 'not_eligible' | 'null_expiry' | 'expired' | 'healthy' | 'reactive_window'
- }
- | { kind: 'refresh' }
- | { kind: 'reconsent_imminent'; reason: 'no_refresh_support' | 'no_refresh_token' }
-
-/**
- * Classify one candidate grant against the proactive window (mini-spec §4).
- *
- * Precedence (each branch is exclusive; the first match wins):
- * 1. `!eligibleForBackground` → noop `not_eligible` (P7; the "cualquiera" gate)
- * 2. `accessTokenExpiresAt == null`→ noop `null_expiry` (P1)
- * 3. `remaining ≤ 0` → noop `expired` (P6; proactive never chases dead tokens)
- * 4. `remaining > Bp` → noop `healthy` (P2; outside the window, healthy)
- * 5. `remaining ≤ Br` → noop `reactive_window` (below the proactive window)
- * 6. in-window + `!supportsRefresh`→ reconsent_imminent (P4; fail-closed, no refresh attempt)
- * 7. in-window + no refresh token → reconsent_imminent (P5)
- * 8. in-window, refreshable → refresh (P3)
- *
- * Proactive window is the strict-open/closed interval `(now+Br, now+Bp]` i.e.
- * `Br < remaining ≤ Bp`. `Bp > Br` is a config invariant (validated at boot).
- *
- * @param now epoch milliseconds
- * @param bpMs proactive buffer (Bp)
- * @param brMs reactive buffer (Br)
- */
-export function classifyProactiveTokenDecision(
- input: ProactiveTokenInput,
- now: number,
- bpMs: number,
- brMs: number
-): ProactiveTokenDecision {
- if (!input.eligibleForBackground) return { kind: 'noop', reason: 'not_eligible' }
- if (input.accessTokenExpiresAt === null) return { kind: 'noop', reason: 'null_expiry' }
-
- const remaining = input.accessTokenExpiresAt.getTime() - now
- if (remaining <= 0) return { kind: 'noop', reason: 'expired' }
- if (remaining > bpMs) return { kind: 'noop', reason: 'healthy' }
- if (remaining <= brMs) return { kind: 'noop', reason: 'reactive_window' }
-
- // Inside the proactive window (Br < remaining ≤ Bp).
- if (!input.supportsRefresh) return { kind: 'reconsent_imminent', reason: 'no_refresh_support' }
- if (!input.hasRefreshToken) return { kind: 'reconsent_imminent', reason: 'no_refresh_token' }
- return { kind: 'refresh' }
-}
-
// ─── §4 · Refresh-result interpretation ─────────────────────────────────────
/**
diff --git a/control-api/src/services/oauthProactiveRefreshCron.ts b/control-api/src/services/oauthProactiveRefreshCron.ts
index 685a38bda..d517687b5 100644
--- a/control-api/src/services/oauthProactiveRefreshCron.ts
+++ b/control-api/src/services/oauthProactiveRefreshCron.ts
@@ -11,10 +11,13 @@
* `requireBackground` set per grantKind (`true` for `user` grants — SEC-5;
* `false` for `shared` context identity, which is unattended by design), and the
* returned access token is DISCARDED — only the side effect (persisted renewed
- * token) and the outcome label matter (mini-spec §6.2). The decision layer is
- * the pure `proactiveRefreshPolicy`
- * module; this file is the thin orchestrator: enumerate → claim → refresh →
- * classify, plus the time-based DCR sweep.
+ * token) and the outcome label matter (mini-spec §6.2). Which grants are
+ * candidates is decided by the SQL `WHERE` of `listRemoteGrantsInProactiveWindow`
+ * plus `getAccessToken`'s own staleness check — NOT by a separate decision table.
+ * The pure `proactiveRefreshPolicy` module only maps each result to a metric
+ * outcome (`resultToOutcome`) and classifies DCR secret expiry
+ * (`classifyDcrSecretDecision`). This file is the thin orchestrator: enumerate →
+ * claim → refresh → label, plus the time-based DCR sweep.
*
* Best-effort, never worsens a grant: any per-row failure is logged + counted and
* the sweep continues; a transient refresh failure leaves the row untouched and
diff --git a/control-api/test/oauth.proactiveRefreshPolicy.test.ts b/control-api/test/oauth.proactiveRefreshPolicy.test.ts
index af6a3df7a..1e8d5909e 100644
--- a/control-api/test/oauth.proactiveRefreshPolicy.test.ts
+++ b/control-api/test/oauth.proactiveRefreshPolicy.test.ts
@@ -1,169 +1,19 @@
/**
- * Pure decision layer for the proactive refresh + DCR lifecycle sweep
- * (mini-spec L §4/§5). Property-based (T2) plus the exact table cases (P1–P7,
- * C1–C5) and the `getAccessToken` result mapping.
+ * Pure decision helpers for the proactive refresh + DCR lifecycle sweep
+ * (mini-spec L §4/§5): the `getAccessToken` result mapping (§4) and the DCR
+ * secret warn/expire table (C1–C5, §5, property-based per T2). The proactive
+ * candidate selection is NOT here — it is the SQL `WHERE` of
+ * `listRemoteGrantsInProactiveWindow` plus `getAccessToken`'s staleness check.
*/
import { describe, expect, it } from 'vitest'
import fc from 'fast-check'
-import {
- classifyDcrSecretDecision,
- classifyProactiveTokenDecision,
- resultToOutcome,
-} from '../src/oauth/proactiveRefreshPolicy.js'
+import { classifyDcrSecretDecision, resultToOutcome } from '../src/oauth/proactiveRefreshPolicy.js'
import type { GetAccessTokenResult } from '../src/oauth/tokenHelper.js'
const NOW = 1_700_000_000_000
-const BR = 60_000 // reactive buffer
-const BP = 300_000 // proactive buffer (Bp > Br)
const at = (offsetMs: number) => new Date(NOW + offsetMs)
-describe('classifyProactiveTokenDecision — §4 table cases', () => {
- const eligible = { hasRefreshToken: true, supportsRefresh: true, eligibleForBackground: true }
-
- it('P1 NULL expiry → noop (no computable threshold)', () => {
- expect(
- classifyProactiveTokenDecision({ ...eligible, accessTokenExpiresAt: null }, NOW, BP, BR)
- ).toEqual({ kind: 'noop', reason: 'null_expiry' })
- })
-
- it('P2 healthy (remaining > Bp) → noop', () => {
- expect(
- classifyProactiveTokenDecision({ ...eligible, accessTokenExpiresAt: at(BP + 1) }, NOW, BP, BR)
- ).toEqual({ kind: 'noop', reason: 'healthy' })
- })
-
- it('P3 in-window, refreshable → refresh (inclusive upper bound Bp)', () => {
- expect(
- classifyProactiveTokenDecision({ ...eligible, accessTokenExpiresAt: at(BP) }, NOW, BP, BR)
- ).toEqual({ kind: 'refresh' })
- expect(
- classifyProactiveTokenDecision({ ...eligible, accessTokenExpiresAt: at(BR + 1) }, NOW, BP, BR)
- ).toEqual({ kind: 'refresh' })
- })
-
- it('P4 in-window, supportsRefresh=false → reconsent_imminent (fail-closed, no refresh)', () => {
- expect(
- classifyProactiveTokenDecision(
- { ...eligible, supportsRefresh: false, accessTokenExpiresAt: at(BP) },
- NOW,
- BP,
- BR
- )
- ).toEqual({ kind: 'reconsent_imminent', reason: 'no_refresh_support' })
- })
-
- it('P5 in-window, no refresh token → reconsent_imminent', () => {
- expect(
- classifyProactiveTokenDecision(
- { ...eligible, hasRefreshToken: false, accessTokenExpiresAt: at(BP) },
- NOW,
- BP,
- BR
- )
- ).toEqual({ kind: 'reconsent_imminent', reason: 'no_refresh_token' })
- })
-
- it('P6 already expired (remaining ≤ 0) → noop (not proactive work)', () => {
- expect(
- classifyProactiveTokenDecision({ ...eligible, accessTokenExpiresAt: at(0) }, NOW, BP, BR)
- ).toEqual({ kind: 'noop', reason: 'expired' })
- expect(
- classifyProactiveTokenDecision({ ...eligible, accessTokenExpiresAt: at(-1) }, NOW, BP, BR)
- ).toEqual({ kind: 'noop', reason: 'expired' })
- })
-
- it('P7 not eligible for background → noop, whatever else holds (the "cualquiera" gate)', () => {
- expect(
- classifyProactiveTokenDecision(
- { ...eligible, eligibleForBackground: false, accessTokenExpiresAt: at(BP) },
- NOW,
- BP,
- BR
- )
- ).toEqual({ kind: 'noop', reason: 'not_eligible' })
- })
-
- it('reactive window (0 < remaining ≤ Br) is left to the reactive path → noop', () => {
- expect(
- classifyProactiveTokenDecision({ ...eligible, accessTokenExpiresAt: at(BR) }, NOW, BP, BR)
- ).toEqual({ kind: 'noop', reason: 'reactive_window' })
- expect(
- classifyProactiveTokenDecision({ ...eligible, accessTokenExpiresAt: at(1) }, NOW, BP, BR)
- ).toEqual({ kind: 'noop', reason: 'reactive_window' })
- })
-})
-
-describe('classifyProactiveTokenDecision — properties (T2)', () => {
- interface ArbInput {
- offsetMs: number | null
- hasRefreshToken: boolean
- supportsRefresh: boolean
- eligibleForBackground: boolean
- }
- const arbInput: fc.Arbitrary<ArbInput> = fc.record({
- offsetMs: fc.oneof(fc.constant<null>(null), fc.integer({ min: -1_000_000, max: 1_000_000 })),
- hasRefreshToken: fc.boolean(),
- supportsRefresh: fc.boolean(),
- eligibleForBackground: fc.boolean(),
- })
- // Bp > Br always (config invariant): br in range, bp = br + delta.
- const arbBuffers = fc
- .tuple(fc.integer({ min: 1, max: 500_000 }), fc.integer({ min: 1, max: 500_000 }))
- .map(([br, delta]) => ({ br, bp: br + delta }))
-
- const build = (i: ArbInput) => ({
- accessTokenExpiresAt: i.offsetMs === null ? null : at(i.offsetMs),
- hasRefreshToken: i.hasRefreshToken,
- supportsRefresh: i.supportsRefresh,
- eligibleForBackground: i.eligibleForBackground,
- })
-
- it('never refreshes outside the strict proactive window, and only when fully refreshable', () => {
- fc.assert(
- fc.property(arbInput, arbBuffers, (i, { bp, br }) => {
- const input = build(i)
- const d = classifyProactiveTokenDecision(input, NOW, bp, br)
- if (d.kind !== 'refresh') return
- expect(input.accessTokenExpiresAt).not.toBeNull()
- const remaining = (input.accessTokenExpiresAt as Date).getTime() - NOW
- expect(remaining).toBeGreaterThan(br)
- expect(remaining).toBeLessThanOrEqual(bp)
- expect(input.eligibleForBackground).toBe(true)
- expect(input.supportsRefresh).toBe(true)
- expect(input.hasRefreshToken).toBe(true)
- })
- )
- })
-
- it('remaining ≤ 0 is never a refresh', () => {
- fc.assert(
- fc.property(arbInput, arbBuffers, (i, { bp, br }) => {
- const input = build(i)
- if (input.accessTokenExpiresAt === null) return
- if (input.accessTokenExpiresAt.getTime() - NOW > 0) return
- expect(classifyProactiveTokenDecision(input, NOW, bp, br).kind).not.toBe('refresh')
- })
- )
- })
-
- it('idempotence: after a simulated full-life refresh, reclassifying is a noop', () => {
- fc.assert(
- fc.property(arbInput, arbBuffers, (i, { bp, br }) => {
- const input = build(i)
- const first = classifyProactiveTokenDecision(input, NOW, bp, br)
- if (first.kind !== 'refresh') return
- // A successful refresh pushes expiry a full life into the future (>> Bp).
- const renewed = { ...input, accessTokenExpiresAt: at(bp * 10 + 1) }
- expect(classifyProactiveTokenDecision(renewed, NOW, bp, br)).toEqual({
- kind: 'noop',
- reason: 'healthy',
- })
- })
- )
- })
-})
-
describe('resultToOutcome — §4 result mapping', () => {
const cases: [GetAccessTokenResult, string][] = [
[{ kind: 'ok', accessToken: 'X' }, 'ok'],