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.jsonindex 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.jsonindex 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.tsindex 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.tsindex 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 anddiff --git a/control-api/test/oauth.proactiveRefreshPolicy.test.ts b/control-api/test/oauth.proactiveRefreshPolicy.test.tsindex 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'],