Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
/**
* Enumeration + claim for the proactive refresh sweep (mini-spec L §6.3), on a
* REAL Postgres so `FOR UPDATE SKIP LOCKED`, the window predicate, and the
* eligibility filter are exercised against the actual schema/migrations — not a
* hand-built row shape. Fixtures come from the REAL producers
* (`bootstrapSharedOAuthGrant` / `upsertOAuthGrant` / `upsertDynamicClient`, T1).
*
* CONTROL_API_REAL_PG_ADMIN_URL=postgres://<user>:<pass>@<host>:5432 npm test -- \
* test/oauth.proactiveRefresh.realPostgres.integration.test.ts
*/
import { afterAll, beforeAll, describe, expect, it } from 'vitest'
import { randomUUID } from 'node:crypto'
import { Pool } from 'pg'
import { config } from '../src/config.js'
import type { DbClient } from '../src/db.js'
import { initDb } from '../src/db.js'
import type {
PinnedRawResponse,
PinnedTransport,
PinnedTransportInput,
} from '../src/http/pinnedFetch.js'
import type { RecipeWithOAuthClients } from '../src/oauth/callback.js'
import { listExpiringDynamicClients, upsertDynamicClient } from '../src/oauth/dynamicClientStore.js'
import { deriveOAuthEncryptionKey } from '../src/oauth/encryption.js'
import {
type OAuthGrantKey,
bootstrapSharedOAuthGrant,
claimRemoteGrantForRefresh,
getOAuthGrant,
listRemoteGrantsInProactiveWindow,
upsertOAuthGrant,
} from '../src/oauth/store.js'
import { getAccessToken } from '../src/oauth/tokenHelper.js'
import { type McpServerResource, normalizeMcpServerOwnerDecl } from '../src/routes/mcpOauth.js'
import { endPoolAndWaitForClients } from './helpers/realPostgresTeardown.js'
import { MockGateway } from './mockGateway.js'
const adminUrl = process.env.CONTROL_API_REAL_PG_ADMIN_URL
const describeRealPostgres = adminUrl ? describe : describe.skip
function databaseUrl(baseUrl: string, database: string): string {
const url = new URL(baseUrl)
url.pathname = `/${database}`
return url.toString()
}
const KEY = deriveOAuthEncryptionKey(config.oauthEncryptionKey)
const NS = config.mcpServersNamespace
const WINDOW = { proactiveBufferMs: 300_000, reactiveBufferMs: 60_000 }
// Seconds-to-expiry that land a grant in each region of the token life.
const IN_WINDOW_SEC = 200 // 60s < 200s ≤ 300s → proactive window
const HEALTHY_SEC = 1_000 // > Bp
const REACTIVE_SEC = 30 // ≤ Br
// The remote lane keys the grant by `oauth.id` (resolveServerOAuth), and the
// refresh path matches the recipe decl by that same id. Seed grants and the
// owner decl from ONE id so the pair stays consistent, as production is.
const REMOTE_OAUTH_ID = 'https://control.example.com/.well-known/evenfire-mcp-client'
describeRealPostgres('oauth proactive refresh — enumeration + claim (real Postgres)', () => {
const database = `control_api_proactive_${randomUUID().replace(/-/g, '')}`
let adminPool: Pool
let dbPool: Pool
let db: DbClient
beforeAll(async () => {
if (!adminUrl) throw new Error('CONTROL_API_REAL_PG_ADMIN_URL is required')
adminPool = new Pool({ connectionString: adminUrl })
await adminPool.query(`CREATE DATABASE "${database.replace(/"/g, '""')}"`)
dbPool = new Pool({ connectionString: databaseUrl(adminUrl, database) })
await initDb({ connect: () => dbPool.connect() })
db = { query: (text, values) => dbPool.query(text, values) }
})
afterAll(async () => {
try {
await endPoolAndWaitForClients(dbPool)
if (adminPool) {
await adminPool.query(
`SELECT pg_terminate_backend(pid) FROM pg_stat_activity
WHERE datname = $1 AND pid <> pg_backend_pid()`,
[database]
)
await adminPool.query(`DROP DATABASE IF EXISTS "${database.replace(/"/g, '""')}"`)
}
} finally {
await adminPool?.end()
}
})
const sharedKey = (server: string, ctx: string): OAuthGrantKey => ({
grantKind: 'shared',
ownerKind: 'mcpserver',
recipeNamespace: NS,
recipeName: server,
contextId: ctx,
oauthClientId: REMOTE_OAUTH_ID,
crUid: uidOf(server),
})
async function seedShared(
server: string,
ctx: string,
provider: string,
expiresInSec: number | undefined
): Promise<void> {
await install(server)
await bootstrapSharedOAuthGrant(db, KEY, {
...sharedKey(server, ctx),
bootstrappedByUserId: 'user-1',
provider,
accessToken: 'AT',
refreshToken: 'RT',
accessTokenExpiresInSec: expiresInSec,
})
}
async function seedUser(
server: string,
userId: string,
background: boolean,
expiresInSec: number
): Promise<void> {
await install(server)
await upsertOAuthGrant(db, KEY, {
grantKind: 'user',
ownerKind: 'mcpserver',
recipeNamespace: NS,
recipeName: server,
userId,
oauthClientId: REMOTE_OAUTH_ID,
provider: 'remote',
accessToken: 'AT',
refreshToken: 'RT',
accessTokenExpiresInSec: expiresInSec,
crUid: uidOf(server),
})
// The background column is set elsewhere at consent time; drive it directly
// here (real schema column) to build the background-vs-not distinction.
if (background) {
await dbPool.query(
`UPDATE oauth_grants SET background = true
WHERE owner_kind = 'mcpserver' AND recipe_namespace = $1 AND recipe_name = $2
AND user_id = $3 AND grant_kind = 'user'`,
[NS, server, userId]
)
}
}
const REMOTE_VALIDATED_IP = '93.184.216.34'
// The owner CR lives in a gateway (which assigns its `metadata.uid`, as the
// apiserver does) and is read back through the REAL owner normalizer the
// refresh engine consumes (T1). Grants are sealed with that uid, as the consent
// callback does, and keys carry it, as the readers derive them.
const gateway = new MockGateway(NS)
const uids = new Map<string, string>()
async function install(server: string): Promise<void> {
if (uids.has(server)) return
await gateway.createResource(
'mcpservers',
{
metadata: { name: server },
spec: {
contextRef: 'ctx-1',
auth: { type: 'oauth' },
oauth: {
source: 'remote',
id: REMOTE_OAUTH_ID,
clientMode: 'public',
authorizationEndpoint: 'https://as.example.com/authorize',
tokenEndpoint: 'https://as.example.com/token',
issuer: 'https://as.example.com',
resource: 'https://as.example.com',
grantScope: 'user',
scopes: ['read'],
bearerInBody: false,
supportsRefresh: true,
},
},
},
NS
)
const cr = (await gateway.getResource('mcpservers', server, NS)) as {
metadata: { uid: string }
}
uids.set(server, cr.metadata.uid)
}
function uidOf(server: string): string {
const uid = uids.get(server)
if (!uid) throw new Error(`fixture: ${server} not installed`)
return uid
}
const ownerReader = {
read: async (name: string): Promise<RecipeWithOAuthClients | null> =>
normalizeMcpServerOwnerDecl(
(await gateway.getResource('mcpservers', name, NS)) as McpServerResource
),
}
const constTransport =
(responseJson: string): PinnedTransport =>
async (_input: PinnedTransportInput): Promise<PinnedRawResponse> => ({
status: 200,
headers: { 'content-type': 'application/json' },
bodyText: responseJson,
})
const refreshDeps = (transport: PinnedTransport) => ({
db,
recipeReader: ownerReader,
secretReader: { read: async () => ({}) },
fetchFn: (async () => {
throw new Error('remote refresh must not use fetchFn')
}) as unknown as typeof fetch,
encryptionKey: KEY,
resolveDns: async () => [REMOTE_VALIDATED_IP],
pinnedTransport: transport,
// Bp so an in-proactive-window token is treated as stale, exactly as the cron.
refreshBufferMs: WINDOW.proactiveBufferMs,
})
it('T4/B1: a background=false shared context grant is refreshed end-to-end (only with requireBackground:false)', async () => {
await seedShared('e2e-shared', 'ctx-1', 'remote', IN_WINDOW_SEC)
const key = sharedKey('e2e-shared', 'ctx-1')
const before = await getOAuthGrant(db, KEY, key)
expect(before?.background).toBe(false) // bootstrapSharedOAuthGrant defaults false
// B1 root cause: with requireBackground:true the shared grant is invisible to
// getOAuthGrant, so the refresh returns no_grant and the row is untouched.
const gatedOut = await getAccessToken(
{ ...key, requireBackground: true },
refreshDeps(constTransport('{}'))
)
expect(gatedOut).toEqual({ kind: 'no_grant' })
const afterGated = await getOAuthGrant(db, KEY, key)
expect(afterGated?.accessToken).toBe(before?.accessToken) // unchanged
// The fix: requireBackground:false (what the cron now passes for shared) →
// refreshes and persists a new token with an advanced expiry (T4 observable).
const result = await getAccessToken(
{ ...key, requireBackground: false },
refreshDeps(
constTransport(
JSON.stringify({ access_token: 'NEW-AT', refresh_token: 'NEW-RT', expires_in: 3600 })
)
)
)
expect(result.kind).toBe('ok')
const after = await getOAuthGrant(db, KEY, key)
expect(after?.accessToken).toBe('NEW-AT')
expect(after?.refreshToken).toBe('NEW-RT')
expect(after?.accessTokenExpiresAt?.getTime()).toBeGreaterThan(
before?.accessTokenExpiresAt?.getTime() ?? 0
)
})
it('enumerates only remote mcpserver grants (shared + background user) inside the window', async () => {
await seedShared('e-shared-in', 'ctx-in', 'remote', IN_WINDOW_SEC)
await seedShared('e-shared-healthy', 'ctx-h', 'remote', HEALTHY_SEC)
await seedShared('e-shared-reactive', 'ctx-r', 'remote', REACTIVE_SEC)
await seedShared('e-shared-nullexp', 'ctx-n', 'remote', undefined)
await seedShared('e-shared-baked', 'ctx-b', 'google', IN_WINDOW_SEC) // non-remote
await seedUser('e-user-bg', 'u-bg', true, IN_WINDOW_SEC)
await seedUser('e-user-nobg', 'u-nobg', false, IN_WINDOW_SEC)
// Recipe-domain grant in-window: must never be touched by the mcpserver sweep.
await upsertOAuthGrant(db, KEY, {
grantKind: 'user',
ownerKind: 'recipe',
recipeNamespace: NS,
recipeName: 'e-recipe',
userId: 'u-recipe',
oauthClientId: REMOTE_OAUTH_ID,
provider: 'remote',
accessToken: 'AT',
accessTokenExpiresInSec: IN_WINDOW_SEC,
})
const keys = await listRemoteGrantsInProactiveWindow(db, WINDOW)
const names = keys.map(k => k.recipeName).sort()
expect(names).toEqual(['e-shared-in', 'e-user-bg'])
})
it('R1-L1: a generic mcpserver grant in the window is enumerated (like remote)', async () => {
// A generic-lane grant admits background/context use and a rotating refresh
// token just like remote; an unattended one has the same silent-expiry risk,
// so the proactive sweep must include it. Pre-fix (`provider='remote'`) it was
// excluded.
await seedShared('e-generic-in', 'ctx-g', 'generic', IN_WINDOW_SEC)
await seedShared('e-generic-healthy', 'ctx-gh', 'generic', HEALTHY_SEC) // out of window
const keys = await listRemoteGrantsInProactiveWindow(db, WINDOW)
const names = keys.map(k => k.recipeName)
expect(names).toContain('e-generic-in')
expect(names).not.toContain('e-generic-healthy')
})
it('FOR UPDATE SKIP LOCKED serializes the claim across connections', async () => {
await seedShared('claim-a', 'ctx-1', 'remote', IN_WINDOW_SEC)
const key = sharedKey('claim-a', 'ctx-1')
const c1 = await dbPool.connect()
const c2 = await dbPool.connect()
try {
await c1.query('BEGIN')
await c2.query('BEGIN')
const first = await claimRemoteGrantForRefresh(
{ query: (t, v) => c1.query(t, v) },
key,
WINDOW
)
const second = await claimRemoteGrantForRefresh(
{ query: (t, v) => c2.query(t, v) },
key,
WINDOW
)
expect(first).toBe(true)
expect(second).toBe(false) // c1 holds the row lock; c2 skips it
await c1.query('COMMIT')
await c2.query('ROLLBACK')
} finally {
c1.release()
c2.release()
}
})
it('the claim re-checks the window: a grant renewed out of the window is not claimed', async () => {
await seedShared('claim-b', 'ctx-1', 'remote', IN_WINDOW_SEC)
const key = sharedKey('claim-b', 'ctx-1')
// Simulate the reactive path having already renewed it to a full life.
await dbPool.query(
`UPDATE oauth_grants SET access_token_expires_at = NOW() + INTERVAL '1000 seconds'
WHERE owner_kind = 'mcpserver' AND recipe_namespace = $1 AND recipe_name = $2
AND context_id = $3 AND grant_kind = 'shared'`,
[NS, 'claim-b', 'ctx-1']
)
const c1 = await dbPool.connect()
try {
await c1.query('BEGIN')
const claimed = await claimRemoteGrantForRefresh(
{ query: (t, v) => c1.query(t, v) },
key,
WINDOW
)
expect(claimed).toBe(false)
await c1.query('ROLLBACK')
} finally {
c1.release()
}
})
it('T5(b): a successful proactive refresh moves the row out of the enumeration window', async () => {
await seedShared('t5b', 'ctx-1', 'remote', IN_WINDOW_SEC)
const before = await listRemoteGrantsInProactiveWindow(db, WINDOW)
expect(before.some(k => k.recipeName === 't5b')).toBe(true)
// A refresh pushes expiry to a full life ahead.
await dbPool.query(
`UPDATE oauth_grants SET access_token_expires_at = NOW() + INTERVAL '3600 seconds'
WHERE owner_kind = 'mcpserver' AND recipe_namespace = $1 AND recipe_name = $2
AND context_id = $3 AND grant_kind = 'shared'`,
[NS, 't5b', 'ctx-1']
)
const after = await listRemoteGrantsInProactiveWindow(db, WINDOW)
expect(after.some(k => k.recipeName === 't5b')).toBe(false)
})
it('listExpiringDynamicClients returns expiring + expired confidential clients only', async () => {
const nowSec = Math.floor(Date.now() / 1000)
await upsertDynamicClient(db, KEY, {
serverNamespace: NS,
serverName: 'dc-expiring',
issuer: 'https://as.example.com',
clientId: 'cid-1',
clientMode: 'confidential',
clientSecret: 'sec',
clientSecretExpiresAtSec: nowSec + 3600, // within 7d
})
await upsertDynamicClient(db, KEY, {
serverNamespace: NS,
serverName: 'dc-expired',
issuer: 'https://as.example.com',
clientId: 'cid-2',
clientMode: 'confidential',
clientSecret: 'sec',
clientSecretExpiresAtSec: nowSec - 3600, // already lapsed
})
await upsertDynamicClient(db, KEY, {
serverNamespace: NS,
serverName: 'dc-healthy',
issuer: 'https://as.example.com',
clientId: 'cid-3',
clientMode: 'confidential',
clientSecret: 'sec',
clientSecretExpiresAtSec: nowSec + 400 * 24 * 3600, // far beyond Wc
})
await upsertDynamicClient(db, KEY, {
serverNamespace: NS,
serverName: 'dc-nonexpiring',
issuer: 'https://as.example.com',
clientId: 'cid-4',
clientMode: 'confidential',
clientSecret: 'sec',
// no clientSecretExpiresAtSec → NULL (non-expiring)
})
await upsertDynamicClient(db, KEY, {
serverNamespace: NS,
serverName: 'dc-public',
issuer: 'https://as.example.com',
clientId: 'cid-5',
clientMode: 'public',
})
const rows = await listExpiringDynamicClients(db, { withinMs: 7 * 24 * 3600 * 1000 })
const names = rows.map(r => r.serverName).sort()
expect(names).toEqual(['dc-expired', 'dc-expiring'])
expect(rows.every(r => r.clientMode === 'confidential')).toBe(true)
})
})