Skip to content

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

TypeScript
6.8 KB
Raw Blame
import type { DbClient } from '../../db.js'
import type { K8sGateway } from '../../k8s.js'
import { type McpHostControlClaims, isHccControlLineage } from '../../utils/auth/mcpHostJwtToken.js'
import { isK8sResourceNotFound } from './mcpInvocable.js'

/**
 * Binding of an OAuth-broker caller to the Host it runs for. The broker
 * (`user-token`, `grants/exists`) never trusts the request body for the
 * Context: it derives it from the authenticated Host, with the same relation
 * host-context-controller uses to hand mcp-servers to that Host (Context by
 * name, live, allowlist matched exactly). The broker must not be more
 * permissive than the controller that decides what the Host may reach.
 */

// DNS-1123 subdomain, the shape a k8s resource name takes. Checked before any
// apiserver read: a malformed name would otherwise surface a non-404 apiserver
// error, and an empty one would address the collection instead of an object.
const K8S_NAME_RE = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$/
export function isValidK8sName(name: string): boolean {
  return name.length > 0 && name.length <= 253 && K8S_NAME_RE.test(name)
}

// Stricter than Postgres' `::uuid` cast (which also accepts braces and no
// hyphens): anything that passes here is guaranteed to cast, so a channel
// provider id or a test sender is a definitive denial, never a DB error.
const CANONICAL_UUID_RE =
  /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/
export function isCanonicalUuid(value: string): boolean {
  return CANONICAL_UUID_RE.test(value)
}

export type CallerLineage =
  | { kind: 'ok'; hostName: string; hostUid: string }
  | { kind: 'lineage' }
  | { kind: 'unauthenticated' }

/**
 * Synchronous caller checks. Lineage goes first so a workflow-recipe token gets
 * a definitive 403 instead of a 401 that would make it renew for nothing; an
 * HCC token without host_uid predates the claim and is sent to renew.
 */
export function checkBrokerCallerLineage(
  claims: McpHostControlClaims,
  cfg: { hostsNamespace: string }
): CallerLineage {
  if (!isHccControlLineage(claims, cfg.hostsNamespace)) return { kind: 'lineage' }
  if (typeof claims.host_uid !== 'string' || claims.host_uid.length === 0) {
    return { kind: 'unauthenticated' }
  }
  return { kind: 'ok', hostName: claims.hostRefs[0], hostUid: claims.host_uid }
}

type ObjectMeta = { name?: unknown; uid?: unknown; deletionTimestamp?: unknown }

export interface HostCR {
  metadata?: ObjectMeta
  spec?: { contextRef?: unknown }
}

export interface ContextCR {
  metadata?: ObjectMeta
  spec?: { contextId?: unknown; mcpServers?: unknown }
}

export interface ResolvedHostBinding {
  kind: 'ok'
  hostName: string
  /** The Host's Context, by name: the only Context the caller may act for. */
  contextName: string
  host: HostCR
  ctx: ContextCR
  allowlist: readonly string[]
}

export type HostBinding =
  | ResolvedHostBinding
  | { kind: 'denied' }
  | { kind: 'unavailable'; cause: unknown }

export type BrokerBindingGateway = Pick<K8sGateway, 'getResource'>

/** Not being deleted: the apiserver keeps a deleting object readable until finalizers run. */
export function isLive(meta: { deletionTimestamp?: unknown } | undefined): boolean {
  return meta?.deletionTimestamp === undefined || meta.deletionTimestamp === null
}

/**
 * Live Host → Context resolution. Namespaces are always explicit: without one
 * the gateway falls back to a cluster-wide list. Not-found and every failed
 * condition are a definitive denial; any other read error is `unavailable`, so
 * callers never forward an apiserver RBAC/availability error to the client.
 * A draining Host still resolves: its pod keeps serving until it is gone.
 */
export async function resolveBrokerHostBinding(
  gateway: BrokerBindingGateway,
  hostName: string,
  hostUid: string,
  cfg: { hostsNamespace: string; contextsNamespace: string }
): Promise<HostBinding> {
  let host: HostCR
  try {
    host = (await gateway.getResource('hosts', hostName, cfg.hostsNamespace)) as HostCR
  } catch (err) {
    return isK8sResourceNotFound(err) ? { kind: 'denied' } : { kind: 'unavailable', cause: err }
  }
  if (!host || !isLive(host.metadata) || host.metadata?.uid !== hostUid) return { kind: 'denied' }

  const contextRef = host.spec?.contextRef
  if (typeof contextRef !== 'string' || !isValidK8sName(contextRef)) return { kind: 'denied' }

  let ctx: ContextCR
  try {
    ctx = (await gateway.getResource('contexts', contextRef, cfg.contextsNamespace)) as ContextCR
  } catch (err) {
    return isK8sResourceNotFound(err) ? { kind: 'denied' } : { kind: 'unavailable', cause: err }
  }
  if (!ctx || ctx.metadata?.name !== contextRef || !isLive(ctx.metadata)) return { kind: 'denied' }

  const raw = ctx.spec?.mcpServers
  const allowlist = Array.isArray(raw)
    ? raw.filter((entry): entry is string => typeof entry === 'string')
    : []
  return { kind: 'ok', hostName, contextName: contextRef, host, ctx, allowlist }
}

/**
 * The admin API lets `spec.contextId` differ from the Context's name. The
 * broker keys nothing by contextId, so a mismatch is only worth a warning:
 * denying on it would silently cut OAuth for every Host of that Context.
 */
export function hasContextIdMismatch(ctx: ContextCR): boolean {
  const contextId = ctx.spec?.contextId
  return typeof contextId === 'string' && contextId !== ctx.metadata?.name
}

// Host entry rule: an active user with the agent assigned directly or through
// any active team membership. rpc-proxy only counts the team of the current
// session; the broker never sees that session, so it accepts any active team
// (a superset, so nobody who can enter the Host loses their token).
// Context membership (`user_contexts`) deliberately does not count: it never
// admits a user to a Host, and counting it would let any Context member's
// identity be used from every Host of that Context.
const HOST_ACCESS_SQL = `
  SELECT 1
    FROM users u
   WHERE u.id = $1::uuid
     AND u.lifecycle_state = 'active'
     AND (
       EXISTS (SELECT 1 FROM user_agents ua WHERE ua.user_id = u.id AND ua.agent_name = $2)
       OR EXISTS (
         SELECT 1
           FROM team_members tm
           JOIN team_agents ta ON ta.team_id = tm.team_id
          WHERE tm.user_id = u.id
            AND tm.status = 'active'
            AND ta.agent_name = $2
       )
     )
   LIMIT 1`

/**
 * Whether `userId` may act through Host `hostName`. A non-canonical id is a
 * denial without touching the DB. Throws on a DB error so the caller decides
 * between fail-closed (token mint) and fail-open (existence sweep).
 */
export async function hostAccessForUser(
  db: Pick<DbClient, 'query'>,
  userId: string,
  hostName: string
): Promise<'allowed' | 'denied'> {
  if (!isCanonicalUuid(userId)) return 'denied'
  const result = await db.query(HOST_ACCESS_SQL, [userId, hostName])
  return (result.rowCount ?? 0) > 0 ? 'allowed' : 'denied'
}