Skip to content

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

TypeScript
26.2 KB
Raw Blame
import jwt from 'jsonwebtoken'
import { createPublicKey, randomUUID } from 'node:crypto'
import { config } from '../../config.js'
import { pool } from '../../db.js'
import { mcpHostJwtIssueTotal } from '../../observability/metrics.js'

// ─── DB-backed refresh token revocation ────────────────────────────────
// JTIs of rotated refresh tokens are persisted to workflow_revoked_refresh_jtis.
// This survives process restarts — a rotated token cannot be replayed even
// after control-api restarts. Expired entries are cleaned by the expiry cron.
// An in-memory cache avoids a DB round-trip on every refresh verification.

const revokedRefreshJtis = new Set<string>()
const MAX_CACHED_JTIS = 10_000
const EXPIRED_REFRESH_REISSUE_GRACE_SECONDS = 5 * 60

export const MCP_HOST_WORKFLOW_AUDIENCE = 'workflow-approvals'
export const MCP_HOST_HCC_AUDIENCE = 'host-context-controller'
export const MCP_HOST_CREDENTIAL_CAPABILITY = 'mcp:credential:read'
/**
 * HCC's access-token verifier accepts at most ten minutes. Keep the issuer
 * fail-closed if an operator raises the shared workflow access TTL without
 * first changing the HCC security contract.
 */
export const MCP_HOST_HCC_ACCESS_MAX_TTL_SECONDS = 600
const HCC_HOST_NAME_RE = /^[a-z0-9]([-a-z0-9]*[a-z0-9])?$/
export const HCC_STANDALONE_RECIPE_NAME = 'standalone'

/** HCC token lineage: the hosts-namespace standalone recipe and one bare Host name. */
function isHccShape(
  recipeNamespace: string,
  recipeName: string,
  hostRefs: string[],
  hostsNamespace: string = config.hostsNamespace
): boolean {
  return (
    recipeNamespace === hostsNamespace &&
    recipeName === HCC_STANDALONE_RECIPE_NAME &&
    hostRefs.length === 1 &&
    hostRefs[0].length <= 63 &&
    HCC_HOST_NAME_RE.test(hostRefs[0])
  )
}

type McpHostCredentialLineage = {
  hostUid: string
}

function normalizeAudienceClaim(aud: jwt.JwtPayload['aud']): string[] | null {
  const values = typeof aud === 'string' ? [aud] : Array.isArray(aud) ? aud : null
  if (!values || values.length === 0 || values.some(value => typeof value !== 'string')) {
    return null
  }
  if (new Set(values).size !== values.length) return null

  const actual = new Set(values)
  const workflowOnly = actual.size === 1 && actual.has(MCP_HOST_WORKFLOW_AUDIENCE)
  const hccQualified =
    actual.size === 2 && actual.has(MCP_HOST_WORKFLOW_AUDIENCE) && actual.has(MCP_HOST_HCC_AUDIENCE)
  return workflowOnly || hccQualified ? values : null
}

// Eviction is FIFO (Set iterator is insertion-ordered), not LRU. At
// replicas: 1 and current throughput this is fine — every cache miss falls
// back to the DB query, so an evicted-but-still-valid revocation is still
// enforced. If control-api ever scales horizontally or ingestion rate spikes
// past MAX_CACHED_JTIS/TTL, revisit: either raise MAX, switch to LRU, or
// back the cache with Redis.
function cacheRevokedRefreshJti(jti: string): void {
  revokedRefreshJtis.add(jti)
  if (revokedRefreshJtis.size > MAX_CACHED_JTIS) {
    const iter = revokedRefreshJtis.values()
    const toRemove = revokedRefreshJtis.size - MAX_CACHED_JTIS
    for (let i = 0; i < toRemove; i++) {
      const entry = iter.next()
      if (entry.done) break
      revokedRefreshJtis.delete(entry.value)
    }
  }
}

async function insertRefreshJtiOnce(jti: string, exp: number): Promise<boolean> {
  if (revokedRefreshJtis.has(jti)) {
    return false
  }

  const expiresAt = new Date(exp * 1000).toISOString()
  const result = await pool.query(
    `INSERT INTO workflow_revoked_refresh_jtis (jti, expires_at)
     VALUES ($1, $2)
     ON CONFLICT DO NOTHING
     RETURNING jti`,
    [jti, expiresAt]
  )

  if ((result.rowCount ?? 0) === 0) {
    cacheRevokedRefreshJti(jti)
    return false
  }

  cacheRevokedRefreshJti(jti)
  return true
}

async function isRefreshJtiRevoked(jti: string): Promise<boolean> {
  if (revokedRefreshJtis.has(jti)) return true
  // Cache miss — check DB
  const result = await pool.query(`SELECT 1 FROM workflow_revoked_refresh_jtis WHERE jti = $1`, [
    jti,
  ])
  if ((result.rowCount ?? 0) > 0) {
    revokedRefreshJtis.add(jti)
    return true
  }
  return false
}

/**
 * For 1st-party HCC-issued tokens, `hostRefs[0]` is the actual Host CRD
 * name (e.g. "trader", "chatllm") and per-event identity binding (e.g.
 * usage ingest) verifies the bearer is acting on its own behalf.
 * For WRC-issued recipe tokens, `hostRefs[0]` is the recipe binding
 * `${recipeNamespace}/${recipeName}` — recipe pods don't run on a single
 * named host. Authorization for those tokens uses recipeName/recipeNamespace
 * (recipe binding) rather than hostRefs.
 */
export type McpHostAccessClaims = {
  sub: string
  recipeNamespace: string
  recipeName: string
  hostRefs: string[]
  scope: 'workflow:approval:request'
  workflowControlScopes: McpHostControlScope[]
  mcpCapabilities: string[]
  host_uid?: string
  iss: string
  aud: string | string[]
  jti: string
  exp: number
}

export type McpHostRefreshClaims = {
  sub: string
  recipeNamespace: string
  recipeName: string
  hostRefs: string[]
  scope: 'workflow:approval:refresh'
  workflowControlScopes: McpHostControlScope[]
  mcpCapabilities: string[]
  host_uid?: string
  iss: string
  aud: string | string[]
  jti: string
  exp: number
}

export type McpHostRefreshVerificationFailureReason =
  | 'invalid_sig'
  | 'invalid_claims'
  | 'expired_beyond_reissue_grace'
  | 'revoked'

export type McpHostRefreshVerificationResult =
  | { ok: true; claims: McpHostRefreshClaims }
  | { ok: false; reason: McpHostRefreshVerificationFailureReason }

export const ALL_MCP_HOST_CONTROL_SCOPES = [
  'workflow:list',
  'workflow:read',
  'workflow:trigger',
  'workflow:approval:resolve',
  'workflow:approval:decide',
  // Plugin Workload SDK (promptBridge + clientNotifications). Provisioners
  // request this scope only for recipes whose validated capability
  // (status.pluginWorkloadSdk) declares the SDK; SDK routes reject access
  // tokens without it via scope_denied.
  'plugin-workload-sdk',
  // OAuth mcp-server broker (U1). Lets mcp-host exchange its control JWT for a
  // per-connection provider access token at POST /api/v1/mcp-oauth/user-token.
  // Provisioners request it only for hosts that front OAuth mcp-servers; the
  // route rejects control tokens lacking it with 403 insufficient_scope.
  'oauth:user-token',
  // Derive-only Codex execution. HCC/WRC may request this after projecting an
  // eligible broker target. Never add it to user-declarable Host/Recipe CRD fields.
  'llm:codex:execute',
  'llm:grok:execute',
] as const

export type McpHostControlScope = (typeof ALL_MCP_HOST_CONTROL_SCOPES)[number]

// Control JWTs are intentionally stateless short-lived bearer credentials.
// Runtime Secret rotation is the revocation boundary; refresh JWTs use the
// DB-backed JTI path because they are rotation credentials.
const MCP_HOST_CONTROL_SCOPE_SET = new Set<string>(ALL_MCP_HOST_CONTROL_SCOPES)

export type McpHostControlClaims = {
  sub: string
  recipeNamespace: string
  recipeName: string
  hostRefs: string[]
  typ: 'service'
  scopes: McpHostControlScope[]
  host_uid?: string
  iss: string
  aud: string
  jti: string
  exp: number
}

const BROKER_USER_TOKEN_SCOPE: McpHostControlScope = 'oauth:user-token'

/**
 * Structural shape of a control token minted for a host-context-controller
 * Host: the sentinel standalone recipe in the hosts namespace and exactly one
 * bare Host name. `standalone` itself is rejected because it is the reserved
 * name of the legacy shared principal, not a Host. Deliberately not part of
 * `verifyMcpHostControlJwt`: other verifiers accept workflow-recipe tokens and
 * a Host that happens to be called `standalone`.
 */
export function isHccControlLineage(
  claims: Pick<McpHostControlClaims, 'recipeNamespace' | 'recipeName' | 'hostRefs'>,
  hostsNamespace: string
): boolean {
  return (
    isHccShape(claims.recipeNamespace, claims.recipeName, claims.hostRefs, hostsNamespace) &&
    claims.hostRefs[0] !== HCC_STANDALONE_RECIPE_NAME
  )
}

// Lazy memoized public key — deferred until first verification call so that
// tests can mock config.adminJwtPrivateKey before the key is computed.
let _workflowJwtPublicKey: string | null = null
function getWorkflowJwtPublicKey(): string {
  if (!_workflowJwtPublicKey) {
    _workflowJwtPublicKey = createPublicKey(config.adminJwtPrivateKey).export({
      type: 'spki',
      format: 'pem',
    }) as string
  }
  return _workflowJwtPublicKey
}

function issueToken(
  recipeNamespace: string,
  recipeName: string,
  scope: 'workflow:approval:request' | 'workflow:approval:refresh',
  ttlSec: number,
  hostRefs: string[],
  workflowControlScopes: McpHostControlScope[] = [],
  hccCredential?: McpHostCredentialLineage
): { token: string; expiresInSeconds: number } {
  if (hccCredential) {
    assertHccCredentialLineage(recipeNamespace, recipeName, hostRefs, hccCredential)
  }
  const effectiveTtlSec =
    hccCredential && scope === 'workflow:approval:request'
      ? Math.min(ttlSec, MCP_HOST_HCC_ACCESS_MAX_TTL_SECONDS)
      : ttlSec
  const token = jwt.sign(
    {
      sub: `${recipeNamespace}/${recipeName}`,
      recipeNamespace,
      recipeName,
      hostRefs,
      scope,
      workflowControlScopes,
      ...(hccCredential
        ? {
            host_uid: hccCredential.hostUid,
            mcpCapabilities: [MCP_HOST_CREDENTIAL_CAPABILITY],
          }
        : {}),
    },
    config.adminJwtPrivateKey,
    {
      algorithm: 'RS256',
      issuer: config.adminJwtIssuer,
      audience: hccCredential
        ? [MCP_HOST_WORKFLOW_AUDIENCE, MCP_HOST_HCC_AUDIENCE]
        : MCP_HOST_WORKFLOW_AUDIENCE,
      jwtid: randomUUID(),
      expiresIn: effectiveTtlSec,
    }
  )
  return { token, expiresInSeconds: effectiveTtlSec }
}

export function issueMcpHostAccessJwt(
  recipeNamespace: string,
  recipeName: string,
  hostRefs?: string[],
  options: {
    workflowControlScopes?: McpHostControlScope[]
    hccCredential?: McpHostCredentialLineage
  } = {}
): { token: string; expiresInSeconds: number } {
  const refs = normalizeIssuedMcpHostHostRefs(recipeNamespace, recipeName, hostRefs)
  const workflowControlScopes = normalizeMcpHostControlScopes(options.workflowControlScopes ?? [])
  if (!workflowControlScopes) throw new Error('invalid mcp-host workflowControlScopes')
  const out = issueToken(
    recipeNamespace,
    recipeName,
    'workflow:approval:request',
    config.mcpHostJwtAccessTtlSec,
    refs,
    workflowControlScopes,
    options.hccCredential
  )
  mcpHostJwtIssueTotal.inc({ kind: 'access' }, 1)
  return out
}

export function issueMcpHostRefreshJwt(
  recipeNamespace: string,
  recipeName: string,
  hostRefs?: string[],
  options: {
    workflowControlScopes?: McpHostControlScope[]
    hccCredential?: McpHostCredentialLineage
  } = {}
): { token: string; expiresInSeconds: number } {
  const refs = normalizeIssuedMcpHostHostRefs(recipeNamespace, recipeName, hostRefs)
  const workflowControlScopes = normalizeMcpHostControlScopes(options.workflowControlScopes ?? [])
  if (!workflowControlScopes) throw new Error('invalid mcp-host workflowControlScopes')
  const out = issueToken(
    recipeNamespace,
    recipeName,
    'workflow:approval:refresh',
    config.mcpHostJwtRefreshTtlSec,
    refs,
    workflowControlScopes,
    options.hccCredential
  )
  mcpHostJwtIssueTotal.inc({ kind: 'refresh' }, 1)
  return out
}

export function issueMcpHostControlJwt(
  recipeNamespace: string,
  recipeName: string,
  hostRefs?: string[],
  options: { scopes?: McpHostControlScope[]; hccCredential?: McpHostCredentialLineage } = {}
): { token: string; expiresInSeconds: number; scopeStripped: boolean } {
  const refs = normalizeIssuedMcpHostHostRefs(recipeNamespace, recipeName, hostRefs)
  const requestedScopes = normalizeMcpHostControlScopes(options.scopes ?? [])
  if (!requestedScopes) throw new Error('invalid mcp-host control scopes')
  const { hccCredential } = options
  if (hccCredential) {
    assertHccCredentialLineage(recipeNamespace, recipeName, refs, hccCredential)
  }
  // The OAuth broker binds a control token to a live Host through host_uid, so
  // only HCC-lineage tokens may carry the broker scope. Filtering here (not in
  // each route) also covers refresh/reissue of older chains that still list the
  // scope. Access and refresh keep it because they never authorize at the
  // broker. workflow-recipes compares the scopes of all three tokens, control
  // included, against what it requested and re-mints on any difference: if it
  // ever requests oauth:user-token, this strip turns into a permanent re-mint
  // loop. Today only host-context-controller requests that scope.
  const scopeStripped = !hccCredential && requestedScopes.includes(BROKER_USER_TOKEN_SCOPE)
  const scopes = scopeStripped
    ? requestedScopes.filter(scope => scope !== BROKER_USER_TOKEN_SCOPE)
    : requestedScopes
  const token = jwt.sign(
    {
      sub: `${recipeNamespace}/${recipeName}`,
      recipeNamespace,
      recipeName,
      hostRefs: refs,
      typ: 'service',
      scopes,
      // host_uid only. mcpCapabilities would let this token act as an HCC
      // credential reader; that authority stays on access/refresh.
      ...(hccCredential ? { host_uid: hccCredential.hostUid } : {}),
    },
    config.adminJwtPrivateKey,
    {
      algorithm: 'RS256',
      issuer: config.adminJwtIssuer,
      audience: 'mcp-host',
      jwtid: randomUUID(),
      expiresIn: config.mcpHostJwtControlTtlSec,
    }
  )
  mcpHostJwtIssueTotal.inc({ kind: 'control' }, 1)
  return { token, expiresInSeconds: config.mcpHostJwtControlTtlSec, scopeStripped }
}

function normalizeMcpHostControlScopes(value: unknown): McpHostControlScope[] | null {
  if (!Array.isArray(value)) return null

  const scopes: McpHostControlScope[] = []
  const seen = new Set<string>()
  for (const entry of value) {
    if (typeof entry !== 'string' || !MCP_HOST_CONTROL_SCOPE_SET.has(entry) || seen.has(entry)) {
      return null
    }
    seen.add(entry)
    scopes.push(entry as McpHostControlScope)
  }
  return scopes
}

function normalizeMcpHostHostRefs(value: unknown): string[] | null {
  if (!Array.isArray(value) || value.length === 0) return null
  if (value.length > config.mcpHostJwtMaxHostRefs) return null

  const hostRefs: string[] = []
  for (const entry of value) {
    if (typeof entry !== 'string') return null
    const hostRef = entry.trim()
    if (!hostRef) return null
    if (hostRef.length > config.mcpHostJwtMaxHostRefLength) return null
    hostRefs.push(hostRef)
  }
  return hostRefs
}

function normalizeHostUid(value: unknown): string | null {
  if (typeof value !== 'string') return null
  const normalized = value.trim()
  if (!normalized || normalized !== value || normalized.length > 128) return null
  if (/[^A-Za-z0-9._:-]/.test(normalized)) return null
  return normalized
}

function assertHccCredentialLineage(
  recipeNamespace: string,
  recipeName: string,
  hostRefs: string[],
  lineage: McpHostCredentialLineage
): void {
  if (!isHccShape(recipeNamespace, recipeName, hostRefs) || !normalizeHostUid(lineage.hostUid)) {
    throw new Error('invalid HCC mcp-host credential lineage')
  }
}

function validateMcpCredentialLineage(
  payload: jwt.JwtPayload,
  audiences: string[],
  recipeNamespace: string,
  recipeName: string,
  hostRefs: string[]
): { hostUid?: string; capabilities: string[] } | null {
  const hccQualified = audiences.includes(MCP_HOST_HCC_AUDIENCE)
  if (!hccQualified) {
    if (payload.host_uid !== undefined || payload.mcpCapabilities !== undefined) return null
    return { capabilities: [] }
  }

  const hostUid = normalizeHostUid(payload.host_uid)
  const capabilities = payload.mcpCapabilities
  if (
    !isHccShape(recipeNamespace, recipeName, hostRefs) ||
    !hostUid ||
    !Array.isArray(capabilities) ||
    capabilities.length !== 1 ||
    capabilities[0] !== MCP_HOST_CREDENTIAL_CAPABILITY
  ) {
    return null
  }
  return { hostUid, capabilities: [MCP_HOST_CREDENTIAL_CAPABILITY] }
}

function normalizeIssuedMcpHostHostRefs(
  recipeNamespace: string,
  recipeName: string,
  hostRefs?: string[]
): string[] {
  const refs = normalizeMcpHostHostRefs(hostRefs ?? [`${recipeNamespace}/${recipeName}`])
  if (!refs) throw new Error('invalid mcp-host hostRefs')
  return refs
}

function validateClaims(
  payload: jwt.JwtPayload,
  expectedScope: string
): McpHostAccessClaims | McpHostRefreshClaims | null {
  const hostRefs = normalizeMcpHostHostRefs(payload?.hostRefs)
  const workflowControlScopes = normalizeMcpHostControlScopes(payload?.workflowControlScopes ?? [])
  const audiences = normalizeAudienceClaim(payload?.aud)
  if (
    typeof payload?.sub !== 'string' ||
    typeof payload?.recipeNamespace !== 'string' ||
    typeof payload?.recipeName !== 'string' ||
    payload.recipeNamespace.trim() !== payload.recipeNamespace ||
    payload.recipeName.trim() !== payload.recipeName ||
    !payload.recipeNamespace ||
    !payload.recipeName ||
    payload.sub !== `${payload.recipeNamespace}/${payload.recipeName}` ||
    !hostRefs ||
    !workflowControlScopes ||
    !audiences ||
    payload?.scope !== expectedScope ||
    typeof payload?.jti !== 'string' ||
    typeof payload?.exp !== 'number'
  ) {
    return null
  }
  const lineage = validateMcpCredentialLineage(
    payload,
    audiences,
    payload.recipeNamespace,
    payload.recipeName,
    hostRefs
  )
  if (!lineage) return null
  return {
    sub: payload.sub,
    recipeNamespace: payload.recipeNamespace,
    recipeName: payload.recipeName,
    hostRefs,
    scope: expectedScope as 'workflow:approval:request' | 'workflow:approval:refresh',
    workflowControlScopes,
    mcpCapabilities: lineage.capabilities,
    ...(lineage.hostUid ? { host_uid: lineage.hostUid } : {}),
    iss: payload.iss as string,
    aud: audiences.length === 1 ? audiences[0] : audiences,
    jti: payload.jti,
    exp: payload.exp,
  }
}

export function verifyMcpHostAccessJwt(token: string): McpHostAccessClaims | null {
  try {
    const payload = jwt.verify(token, getWorkflowJwtPublicKey(), {
      algorithms: ['RS256'],
      issuer: config.adminJwtIssuer,
      audience: MCP_HOST_WORKFLOW_AUDIENCE,
    }) as jwt.JwtPayload
    return validateClaims(payload, 'workflow:approval:request') as McpHostAccessClaims
  } catch {
    return null
  }
}

export function verifyMcpHostControlJwt(token: string): McpHostControlClaims | null {
  try {
    const payload = jwt.verify(token, getWorkflowJwtPublicKey(), {
      algorithms: ['RS256'],
      issuer: config.adminJwtIssuer,
      audience: 'mcp-host',
    }) as jwt.JwtPayload

    const { sub, recipeNamespace, recipeName, jti, exp } = payload
    const hostRefs = normalizeMcpHostHostRefs(payload.hostRefs)
    if (
      typeof sub !== 'string' ||
      typeof recipeNamespace !== 'string' ||
      typeof recipeName !== 'string' ||
      !hostRefs ||
      typeof jti !== 'string' ||
      typeof exp !== 'number'
    ) {
      return null
    }

    if (payload.typ !== 'service') {
      return null
    }

    const scopes = normalizeMcpHostControlScopes(payload.scopes)
    if (!scopes) {
      return null
    }

    let hostUid: string | undefined
    if (payload.host_uid !== undefined) {
      const normalized = normalizeHostUid(payload.host_uid)
      if (!normalized) return null
      hostUid = normalized
    }

    return {
      sub,
      recipeNamespace,
      recipeName,
      hostRefs,
      typ: 'service',
      scopes,
      ...(hostUid ? { host_uid: hostUid } : {}),
      iss: payload.iss as string,
      aud: 'mcp-host',
      jti,
      exp,
    }
  } catch {
    return null
  }
}

/**
 * Verified-claims identity for mcp-host rate-limit buckets.
 * Standalone 1st-party tokens share `sub = <hostsNamespace>/standalone`;
 * per-host isolation lives in `hostRefs[0]`, matching the refresh limiter.
 */
export function mcpHostVerifiedRateLimitPrincipal(
  claims:
    | Pick<McpHostAccessClaims, 'recipeNamespace' | 'recipeName' | 'hostRefs'>
    | Pick<McpHostRefreshClaims, 'recipeNamespace' | 'recipeName' | 'hostRefs'>
    | null
    | undefined
): string | null {
  if (!claims) return null
  if (claims.recipeNamespace === config.hostsNamespace) {
    const primaryHostRef = claims.hostRefs[0]?.trim()
    if (!primaryHostRef) return null
    return `${claims.recipeNamespace}/host/${primaryHostRef}`
  }
  const recipeName = claims.recipeName.trim()
  if (!recipeName) return null
  return `${claims.recipeNamespace}/${recipeName}`
}

/** Prefix a verified mcp-host principal for a PG/edge rate-limit bucket. */
export function mcpHostRateLimitBucketKey(
  prefix: string,
  claims: Parameters<typeof mcpHostVerifiedRateLimitPrincipal>[0],
  missing: string | null = null
): string | null {
  const principal = mcpHostVerifiedRateLimitPrincipal(claims)
  if (!principal) return missing
  return `${prefix}:${principal}`
}

export function getMcpHostRefreshRateLimitKey(
  token: string,
  opts: { expiredGraceSeconds?: number } = {}
): string | null {
  try {
    const expiredGraceSeconds = opts.expiredGraceSeconds ?? 0
    const payload = jwt.verify(token, getWorkflowJwtPublicKey(), {
      algorithms: ['RS256'],
      issuer: config.adminJwtIssuer,
      audience: MCP_HOST_WORKFLOW_AUDIENCE,
      ignoreExpiration: expiredGraceSeconds > 0,
    }) as jwt.JwtPayload

    if (expiredGraceSeconds > 0) {
      const exp = typeof payload.exp === 'number' ? payload.exp : 0
      if (exp < Math.floor(Date.now() / 1000) - expiredGraceSeconds) {
        return null
      }
    }

    const claims = validateClaims(
      payload,
      'workflow:approval:refresh'
    ) as McpHostRefreshClaims | null
    if (!claims) {
      return null
    }

    return mcpHostVerifiedRateLimitPrincipal(claims)
  } catch {
    return null
  }
}

export function getMcpHostExpiredRefreshRateLimitKey(token: string): string | null {
  return getMcpHostRefreshRateLimitKey(token, {
    expiredGraceSeconds: EXPIRED_REFRESH_REISSUE_GRACE_SECONDS,
  })
}

export async function verifyMcpHostRefreshJwt(token: string): Promise<McpHostRefreshClaims | null> {
  try {
    const payload = jwt.verify(token, getWorkflowJwtPublicKey(), {
      algorithms: ['RS256'],
      issuer: config.adminJwtIssuer,
      audience: MCP_HOST_WORKFLOW_AUDIENCE,
    }) as jwt.JwtPayload

    const claims = validateClaims(
      payload,
      'workflow:approval:refresh'
    ) as McpHostRefreshClaims | null
    if (!claims) {
      return null
    }

    if (await isRefreshJtiRevoked(claims.jti)) {
      return null
    }

    return claims
  } catch {
    return null
  }
}

/**
 * Verify a refresh token for the recovery path.
 *
 * Unlike `verifyMcpHostRefreshJwt`, this accepts tokens whose `exp` has
 * already passed within a short grace window. The re-issue endpoint exists to
 * recover from the crash window where mcp-host persisted a refresh pair but
 * the corresponding rotation round-trip didn't complete, so by the time
 * mcp-host retries the token may be both expired AND revoked.
 *
 * Returns the claims if: signature valid, iss/aud match, scope is refresh,
 * and the jti is NOT in the revoked table. Returns null in ALL other cases
 * (the caller surfaces an opaque 401 to avoid leaking which check failed).
 *
 * Does NOT consume the jti — callers that want one-shot semantics must
 * invoke `consumeRefreshJti` separately (see route handler).
 */
export async function verifyExpiredMcpHostRefreshJwt(
  token: string
): Promise<McpHostRefreshClaims | null> {
  const result = await verifyExpiredMcpHostRefreshJwtDetailed(token)
  return result.ok ? result.claims : null
}

export async function verifyExpiredMcpHostRefreshJwtDetailed(
  token: string
): Promise<McpHostRefreshVerificationResult> {
  let payload: jwt.JwtPayload
  try {
    payload = jwt.verify(token, getWorkflowJwtPublicKey(), {
      algorithms: ['RS256'],
      issuer: config.adminJwtIssuer,
      audience: MCP_HOST_WORKFLOW_AUDIENCE,
      // Critical: do NOT let jsonwebtoken reject expiration here. This route
      // applies its own bounded grace window after normal claim validation.
      ignoreExpiration: true,
    }) as jwt.JwtPayload
  } catch {
    return { ok: false, reason: 'invalid_sig' }
  }

  const claims = validateClaims(payload, 'workflow:approval:refresh') as McpHostRefreshClaims | null
  if (!claims) {
    return { ok: false, reason: 'invalid_claims' }
  }

  const now = Math.floor(Date.now() / 1000)
  if (claims.exp < now - EXPIRED_REFRESH_REISSUE_GRACE_SECONDS) {
    return { ok: false, reason: 'expired_beyond_reissue_grace' }
  }

  if (await isRefreshJtiRevoked(claims.jti)) {
    return { ok: false, reason: 'revoked' }
  }

  return { ok: true, claims }
}

/**
 * Atomic single-use consumption of a refresh jti. Callers verify first
 * (`verifyMcpHostRefreshJwt` / `verifyExpiredMcpHostRefreshJwtDetailed`),
 * run every check that can fail transiently, and only then consume: a
 * consumed jti cannot be retried, so consuming before a check that answers
 * 503 would burn the caller's rotation chain. When two requests race on the
 * same jti only one wins the INSERT.
 */
export async function consumeRefreshJti(jti: string, exp: number): Promise<boolean> {
  // Reissue accepts a refresh until `exp + grace`, and the expiry cron deletes
  // rows once `expires_at` passes. The row must therefore outlive the whole
  // reissue window: stored at plain `exp`, the cron could drop it while the
  // consumed token is still reissuable, and after a restart (cold in-memory
  // cache) reissue would accept it a second time. `now + grace` covers a jti
  // consumed on reissue after its exp.
  const now = Math.floor(Date.now() / 1000)
  const replayableUntil = Math.max(exp, now) + EXPIRED_REFRESH_REISSUE_GRACE_SECONDS
  return insertRefreshJtiOnce(jti, replayableUntil)
}

export function getMcpHostCallerKey(
  claims: Pick<
    McpHostAccessClaims | McpHostRefreshClaims | McpHostControlClaims,
    'hostRefs' | 'sub'
  >
): string {
  // hostRefs[0] is the protocol caller/usage binding. Do not scan later
  // entries: they authorize additional targets, but they do not redefine the
  // caller identity stamped into approvals, workflow runs, or usage records.
  const primaryHostRef = claims.hostRefs?.[0]?.trim()
  if (!primaryHostRef) {
    throw new Error('mcp-host JWT missing canonical hostRefs[0] caller binding')
  }
  return primaryHostRef
}

export function isHostRefAuthorized(
  claims: McpHostAccessClaims | McpHostRefreshClaims | McpHostControlClaims,
  targetNamespace: string,
  targetName: string
): boolean {
  const target = `${targetNamespace}/${targetName}`
  return claims.hostRefs.includes(target)
}