Skip to content

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

TypeScript
32.1 KB
Raw Blame
/**
 * Registry Client — fetches entries from Clerum Registry service.
 * Managed deployments use CLERUM_REGISTRY_AUTH_ENABLED plus env-provided
 * client credentials. Self-hosted deployments become Bearer-authenticated when
 * their claimed registry_connection row holds machine credentials.
 */
import { config } from '../config.js'
import { rootLogger } from '../observability/logger.js'
import { resolveMachineCreds } from './registryConnectionDb.js'
import {
  isRegistryIdentityCacheGenerationCurrent,
  withCurrentRegistryIdentity,
} from './registryIdentityCache.js'

export { invalidateRegistryIdentityCaches } from './registryIdentityCache.js'

const API_BASE = `${config.registryUrl}/api/v1`

const logger = rootLogger.child({ module: 'registry-client' })

// ── Read-path timeouts ───────────────────────────────────────────────────────
// A 1–2s registry (origin/tunnel) hiccup must not surface as a user-visible
// marketplace 500. Bound every READ-path fetch with AbortSignal.timeout so a
// stalled connection fails fast (as a retriable transient) instead of hanging
// the request. Token / search / getEntry / categories get the short budget;
// bundle downloads (larger payloads) get a longer one. Write paths
// (publish / report-install / artifacts / PUT / DELETE) deliberately get NO
// timeout — they are not idempotent and must not be silently abandoned mid-write.
const READ_TIMEOUT_MS = 5_000
const BUNDLE_TIMEOUT_MS = 10_000

/**
 * True when `err` is an aborted/timed-out fetch (AbortSignal.timeout fires an
 * `AbortError`/`TimeoutError`). Treated as a retriable transient by the GET
 * retry-once path below and surfaced as a transient, not a hard failure.
 */
function isTransientFetchError(err: unknown): boolean {
  if (!(err instanceof Error)) return false
  return err.name === 'AbortError' || err.name === 'TimeoutError'
}

/**
 * Registry origin/gateway is unreachable (network refusal, timeout, or an
 * upstream HTTP 5xx). A clean, user-safe error the global handler forwards as a
 * 503 so the marketplace shows a clear message instead of a raw 500.
 */
export class RegistryUnavailableError extends Error {
  readonly status = 503
  readonly code = 'registry_unavailable'
  constructor(
    message = 'The registry is currently unavailable. Check the connection and try again.'
  ) {
    super(message)
    this.name = 'RegistryUnavailableError'
  }
}

function staleRegistryIdentityError(): RegistryUnavailableError {
  return new RegistryUnavailableError('The registry identity changed. Please try again.')
}

// ── OAuth2 client_credentials token cache ────────────────────────────────────
// control-api is one-per-cluster; a single cached token serves the whole
// process. Refreshed ~30s before expiry so we never hit 401 from expiry in
// the steady state. On a real 401 (e.g. registry key rotation), authedFetch
// evicts the cache and retries once.
let cached: { token: string; expiresAt: number; generation: number } | null = null

// ── Catalog cache (declared here so __resetTokenCacheForTests can clear it;
// populated/consumed by withReadThroughCache below). ─────────────────────────
const STALE_WHILE_ERROR_TTL_MS = 45_000

// Read-through TTL: within this window the default catalog search and the
// category list are served from process memory WITHOUT a live cross-cluster
// registry round trip (the dominant marketplace-load latency). Kept short so an
// admin sees publishes/edits promptly; mutating calls also bust it explicitly.
const CATALOG_CACHE_TTL_MS = 15_000

// The two hot read paths the marketplace lands on. Shared so the cache writes
// (withReadThroughCache) and the invalidation (invalidateCatalogCaches) can
// never drift on the key strings.
const CATALOG_CACHE_KEYS = {
  search: 'search:default-catalog',
  categories: 'categories',
} as const

interface CacheEntry<T> {
  value: T
  ts: number
  generation: number
}

const swrCache = new Map<string, CacheEntry<unknown>>()
const pendingSWRReads = new Map<string, { generation: number; promise: Promise<unknown> }>()

export function __resetTokenCacheForTests(): void {
  cached = null
  swrCache.clear()
  pendingSWRReads.clear()
}

export async function mintToken(envOverride?: NodeJS.ProcessEnv): Promise<string> {
  return withCurrentRegistryIdentity(
    generation => mintTokenForGeneration(generation, envOverride),
    { staleError: staleRegistryIdentityError }
  )
}

async function mintTokenForGeneration(
  cacheGeneration: number,
  envOverride?: NodeJS.ProcessEnv
): Promise<string> {
  const env = envOverride ?? process.env
  const now = Date.now()
  if (cached && cached.generation === cacheGeneration && now < cached.expiresAt - 30_000)
    return cached.token

  // An explicit override is a test-only path and remains fully env-driven. In
  // production, credentials MUST come from the mode-aware resolver: managed
  // reads config/env, self-hosted reads only the claimed DB row. Reading env
  // first here would create a split brain where isRegistryAuthActive authorizes
  // the DB identity while the registry client authenticates as a stale managed
  // identity left in the pod environment.
  let id = envOverride ? env.CLERUM_REGISTRY_CLIENT_ID || '' : ''
  let secret = envOverride ? env.CLERUM_REGISTRY_CLIENT_SECRET || '' : ''
  // Single source of truth for the registry base URL — env override wins for
  // tests/minikube, else config.registryUrl (mandatory + allowlisted when auth
  // is on). resolveMachineCreds no longer carries a `url`.
  const url = env.CLERUM_REGISTRY_URL || (envOverride ? '' : config.registryUrl)

  let authEnabled = false
  if (!envOverride) {
    const resolved = await resolveMachineCreds()
    if (resolved) {
      id = resolved.clientId
      secret = resolved.clientSecret
    }
    // Derive the decision from the SAME resolution used for the credentials.
    // Managed deliberately keeps its env flag; self-hosted is active exactly
    // when the DB row yielded a complete credential pair.
    authEnabled =
      config.registryConnectionMode === 'managed' ? config.registryAuthEnabled : resolved !== null
  }

  if (!id || !secret) {
    if (!authEnabled) return '' // minikube / auth-off
    throw new Error(
      'registry machine credentials unavailable (env in managed mode, DB row in self-hosted)'
    )
  }

  // Minting a token is a read-side prerequisite for every catalog read, so it
  // carries the read timeout. (It is a POST, but an idempotent credential
  // exchange — not a state-mutating write — so bounding it is safe.)
  const res = await fetch(`${url}/oauth/token`, {
    method: 'POST',
    headers: {
      Authorization: `Basic ${Buffer.from(`${id}:${secret}`).toString('base64')}`,
      'Content-Type': 'application/x-www-form-urlencoded',
    },
    body: 'grant_type=client_credentials',
    signal: AbortSignal.timeout(READ_TIMEOUT_MS),
  })
  if (!res.ok) {
    await discardResponseBody(res)
    // Distinguish a rejected credential (rotate the secret) from an origin /
    // tunnel outage (page on-call about reachability, do NOT rotate). A 5xx at
    // the token endpoint is the registry origin or its tunnel being down, not a
    // bad client secret — the previous identical label sent on-call to rotate
    // secrets during an outage.
    if (res.status >= 500) {
      throw new Error(`registry token endpoint unavailable (origin/tunnel): ${res.status}`)
    }
    throw new Error(`registry credential rejected: ${res.status}`)
  }
  const json = (await res.json()) as { access_token: string; expires_in: number }
  const next = {
    token: json.access_token,
    expiresAt: now + json.expires_in * 1000,
    generation: cacheGeneration,
  }
  if (isRegistryIdentityCacheGenerationCurrent(cacheGeneration)) cached = next
  return next.token
}

interface RegistrySearchParams {
  q?: string
  entryType?: string
  category?: string
  serverMode?: string
  transport?: string
  trustLevel?: string
  sort?: string
  limit?: number
  offset?: number
}

export interface RegistryEntry {
  id: string
  name: string
  version: string
  entry_type: string
  description: string
  author: string
  origin: string
  category: string
  tags: string[]
  trust_level: string
  quality_tier: string
  status: string
  server_mode: string | null
  transport: string | null
  recipe_type: string | null
  mcp_server_meta: Record<string, unknown> | null
  recipe_meta: Record<string, unknown> | null
  // Catalog record for an installed guardrail hook (entry_type 'llm-hook'), read
  // by the install-hook saga (guardrails spec §8.5). Shape mirrors the registry's
  // HookMeta: { target, lifecyclePoints, path?, credentialSchema?, defaultConfig?, requiredEgress? }.
  hook_meta: Record<string, unknown> | null
  artifact_refs: Record<string, unknown> | null
  downloads: number
  installs: number
  created_at: string
  // Ownership — hooks are org-scoped (§8.5); the saga verifies owner_type==='org'
  // and the org identity feeds the platform trust-level policy (never the
  // publisher-influenced trust_level column at face value).
  owner_type?: string
  owner_id?: string | null
}

interface PaginatedResponse<T> {
  data: T[]
  meta: { total: number; limit: number; offset: number }
}

/** Retriable upstream statuses for an idempotent GET (gateway/tunnel hiccups). */
const RETRIABLE_GET_STATUSES = new Set([502, 503, 504])

async function discardResponseBody(res: Response): Promise<void> {
  try {
    await res.body?.cancel()
  } catch {
    // Releasing a failed upstream response is best-effort; preserve the original
    // auth/status error when an undici stream is already closed.
  }
}

function jitterSleep(baseMs: number): Promise<void> {
  // ~baseMs ± up to baseMs jitter so concurrent callers don't retry in lockstep.
  const ms = baseMs + Math.floor(Math.random() * baseMs)
  return new Promise(resolve => setTimeout(resolve, ms))
}

async function authedFetch(
  path: string,
  init: RequestInit = {},
  opts: { timeoutMs?: number } = {}
): Promise<Response> {
  // READ paths get a timeout so a stalled origin/tunnel fails fast as a
  // transient. Writes (method !== GET) pass no signal and are never retried.
  const method = (init.method ?? 'GET').toUpperCase()
  const isGet = method === 'GET'
  const timeoutMs = opts.timeoutMs ?? READ_TIMEOUT_MS

  const send = async (): Promise<Response> => {
    const token = await mintToken()
    const headers: Record<string, string> = {
      ...(init.headers as Record<string, string> | undefined),
    }
    if (token) headers.Authorization = `Bearer ${token}`
    return fetch(`${API_BASE}${path}`, {
      ...init,
      headers,
      ...(isGet ? { signal: AbortSignal.timeout(timeoutMs) } : {}),
    })
  }

  // For idempotent GETs we add a single bounded retry on a transient gateway
  // status (502/503/504) or a network/Abort rejection, so a 1–2s registry blip
  // is absorbed here instead of becoming a marketplace 500. Non-GET requests
  // are never retried (could double-apply a write).
  const attempt = async (allowTransientRetry: boolean): Promise<Response> => {
    let res: Response
    try {
      res = await send()
    } catch (err) {
      if (isGet && allowTransientRetry && isTransientFetchError(err)) {
        await jitterSleep(250)
        return attempt(false)
      }
      throw err
    }
    if (res.status === 401) {
      // Existing behavior: a 401 means the cached token is stale (e.g. registry
      // key rotation) — evict and retry once with a fresh mint. Orthogonal to
      // the transient-status retry below.
      await discardResponseBody(res)
      cached = null
      res = await send()
    }
    if (isGet && allowTransientRetry && RETRIABLE_GET_STATUSES.has(res.status)) {
      await discardResponseBody(res)
      await jitterSleep(250)
      return attempt(false)
    }
    return res
  }

  return attempt(isGet)
}

async function registryFetch<T>(path: string, init?: RequestInit): Promise<T> {
  let res: Response
  try {
    res = await authedFetch(path, init)
  } catch (err) {
    // Remap ONLY genuine network/timeout signals to a clean "unavailable":
    // undici's "fetch failed" (ECONNREFUSED / DNS) surfaces as a TypeError, and
    // an Abort/Timeout that survives the single GET retry surfaces via
    // isTransientFetchError. Everything else is rethrown unchanged — critically,
    // mintToken's status-less "registry credential rejected" (a wrong-secret
    // misconfig) must keep its own signal rather than be mislabeled "unavailable".
    if (err instanceof TypeError || isTransientFetchError(err)) {
      throw new RegistryUnavailableError()
    }
    throw err
  }
  if (!res.ok) {
    await discardResponseBody(res)
    // A persistent 401 (authedFetch already evict-retried once) is a registry
    // machine-token / integration fault — NOT the admin's control-ui session.
    // Remap to 502 (so control-ui's global 401 handler never force-logs-out the
    // admin) and carry a machine code + a user-safe message.
    if (res.status === 401) {
      throw Object.assign(new Error('The registry could not be reached.'), {
        status: 502,
        code: 'registry_integration_error',
      })
    }
    // Registry origin/gateway down — an HTTP 5xx (500/502/503/504 and Cloudflare
    // 520–524) is the dominant real-world "registry unavailable" signal (edge up,
    // origin down). Map to a clean 503. Retriable GET statuses already retried
    // once via RETRIABLE_GET_STATUSES in authedFetch before landing here.
    if (res.status >= 500) {
      throw new RegistryUnavailableError()
    }
    // Attach the upstream status so the global error handler (app.ts) forwards
    // 4xx verbatim to the API client (a registry 404 stays a 404 — the
    // e2e-registry-publish-update-remove failure class).
    throw Object.assign(new Error(`Registry ${res.status}`), {
      status: res.status,
    })
  }
  return res.json() as Promise<T>
}

function registrySend<T>(path: string, method: string, body?: unknown): Promise<T> {
  return registryFetch<T>(path, {
    method,
    ...(body !== undefined
      ? {
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify(body),
        }
      : {}),
  })
}

function buildQuery(params: Record<string, string | number | undefined | null>): string {
  const qs = new URLSearchParams()
  for (const [key, val] of Object.entries(params)) {
    if (val != null && val !== '') qs.set(key, String(val))
  }
  const query = qs.toString()
  return query ? `?${query}` : ''
}

// ── Catalog cache ────────────────────────────────────────────────────────────
// A short-TTL read-through + last-good cache for the two hot read paths the
// marketplace lands on: the default catalog search (limit:200, no other filters)
// and the category list.
//   • Read-through (CATALOG_CACHE_TTL_MS): a fresh hit is served from memory and
//     SKIPS the live registry round trip — this removes the dominant marketplace
//     latency (a cross-cluster Cloudflare/tunnel hop) from steady-state loads.
//   • Stale-while-error (STALE_WHILE_ERROR_TTL_MS): on a fresh registry error we
//     serve the last-good value (even if stale) instead of bubbling a 500; we
//     only error when there is no cached value at all.
// The Map + TTL constants are declared near the token cache above (so the test
// reset helper can clear them). Intentionally a tiny module-level Map — no extra
// dependency, process-local, evicted on restart.

/**
 * Wrap a fetcher with read-through + stale-while-error semantics:
 * - Fresh hit (age ≤ CATALOG_CACHE_TTL_MS): return the cached value, no fetch.
 * - Miss/stale: fetch; on success cache (fresh timestamp) and return it.
 * - On error: if any cached value exists, return it (stale-while-error); the
 *   STALE_WHILE_ERROR_TTL only governs whether a fallback hit is logged as fresh
 *   vs stale, never whether it is usable. If nothing is cached, rethrow so the
 *   caller 500s.
 */
async function withReadThroughCache<T>(key: string, fetcher: () => Promise<T>): Promise<T> {
  return withCurrentRegistryIdentity(
    generation => {
      const hit = swrCache.get(key) as CacheEntry<T> | undefined
      if (hit?.generation === generation && Date.now() - hit.ts <= CATALOG_CACHE_TTL_MS) {
        return Promise.resolve(hit.value)
      }
      const pending = pendingSWRReads.get(key)
      if (pending?.generation === generation) return pending.promise as Promise<T>

      const promise = fetcher()
        .then(value => {
          if (isRegistryIdentityCacheGenerationCurrent(generation)) {
            swrCache.set(key, { value, ts: Date.now(), generation })
          }
          return value
        })
        .catch(err => {
          if (!isRegistryIdentityCacheGenerationCurrent(generation)) throw err
          const cachedEntry = swrCache.get(key) as CacheEntry<T> | undefined
          if (cachedEntry?.generation === generation) {
            const ageMs = Date.now() - cachedEntry.ts
            logger.warn(
              {
                event: 'registry_stale_while_error',
                key,
                ageMs,
                fresh: ageMs <= STALE_WHILE_ERROR_TTL_MS,
                err: err instanceof Error ? err.message : String(err),
              },
              'registry read failed; serving last-good cached value'
            )
            return cachedEntry.value
          }
          throw err
        })
        .finally(() => {
          if (pendingSWRReads.get(key)?.promise === promise) pendingSWRReads.delete(key)
        })

      pendingSWRReads.set(key, { generation, promise })
      return promise
    },
    { staleError: staleRegistryIdentityError }
  )
}

/**
 * Bust the catalog read-through cache so the next marketplace load reflects a
 * just-applied mutation (publish / delete / metadata edit) immediately rather
 * than waiting out the TTL. Process-local: with multiple control-api replicas,
 * peers still converge within CATALOG_CACHE_TTL_MS.
 */
function invalidateCatalogCaches(): void {
  for (const key of Object.values(CATALOG_CACHE_KEYS)) {
    swrCache.delete(key)
    pendingSWRReads.delete(key)
  }
}

/** True for the default marketplace catalog landing query (limit:200, no filters). */
function isDefaultCatalogSearch(params: RegistrySearchParams): boolean {
  return (
    params.limit === 200 &&
    !params.q &&
    !params.entryType &&
    !params.category &&
    !params.serverMode &&
    !params.transport &&
    !params.trustLevel &&
    !params.sort &&
    !params.offset
  )
}

export async function searchEntries(
  params: RegistrySearchParams
): Promise<PaginatedResponse<RegistryEntry>> {
  const fetcher = (): Promise<PaginatedResponse<RegistryEntry>> =>
    registryFetch(`/entries${buildQuery(params as Record<string, string | number | undefined>)}`)

  // Only the default catalog landing search is cached. Filtered / paginated
  // searches stay strict so users never see a stale result set for a query they
  // typed; a blip on those still surfaces as an error, which is acceptable
  // because the landing page (the 500-prone hot path) is protected.
  if (isDefaultCatalogSearch(params)) {
    return withReadThroughCache(CATALOG_CACHE_KEYS.search, fetcher)
  }
  return fetcher()
}

export async function getEntry(name: string): Promise<RegistryEntry> {
  return registryFetch(`/entries/${encodeURIComponent(name)}`)
}

export async function getEntryVersion(name: string, version: string): Promise<RegistryEntry> {
  return registryFetch(
    `/entries/${encodeURIComponent(name)}/versions/${encodeURIComponent(version)}`
  )
}

export async function getCredentialSchema(
  name: string,
  version: string
): Promise<Record<string, unknown>> {
  return registryFetch(
    `/entries/${encodeURIComponent(name)}/versions/${encodeURIComponent(version)}/credential-schema`
  )
}

export async function getCategories(): Promise<{ data: string[] }> {
  return withReadThroughCache(CATALOG_CACHE_KEYS.categories, () =>
    registryFetch<{ data: string[] }>('/categories')
  )
}

export async function reportInstall(
  name: string,
  correlationId: string,
  version: string,
  clusterFingerprint?: string
): Promise<{ acknowledged: boolean; stored: boolean }> {
  return registrySend(`/entries/${encodeURIComponent(name)}/report-install`, 'POST', {
    correlationId,
    version,
    clusterFingerprint,
    success: true,
  })
}

export async function downloadBundle(name: string, version: string): Promise<Buffer> {
  // Bundles are larger payloads, so they get the longer read budget.
  const res = await authedFetch(
    `/entries/${encodeURIComponent(name)}/versions/${encodeURIComponent(version)}/bundle`,
    {},
    { timeoutMs: BUNDLE_TIMEOUT_MS }
  )
  if (!res.ok) {
    await discardResponseBody(res)
    throw new Error(`Registry ${res.status}`)
  }
  const arrayBuffer = await res.arrayBuffer()
  return Buffer.from(arrayBuffer)
}

export async function getDigest(name: string, version: string): Promise<{ digest: string | null }> {
  return registryFetch(
    `/entries/${encodeURIComponent(name)}/versions/${encodeURIComponent(version)}/digest`
  )
}

export async function uploadArtifacts(
  name: string,
  version: string,
  artifacts: { soulMd?: string; bundle?: string }
): Promise<{ uploaded: boolean; artifact_refs: Record<string, string> }> {
  return registrySend(
    `/entries/${encodeURIComponent(name)}/versions/${encodeURIComponent(version)}/artifacts`,
    'POST',
    artifacts
  )
}

export async function updateVersionMetadata(
  name: string,
  version: string,
  fields: {
    description?: string
    tags?: string[]
    visibility?: string
    mcpServer?: {
      egressSummary?: { domains?: string[]; ports?: number[]; wideCidr?: boolean } | null
    }
  }
): Promise<RegistryEntry> {
  const result = await registrySend<RegistryEntry>(
    `/entries/${encodeURIComponent(name)}/versions/${encodeURIComponent(version)}`,
    'PUT',
    fields
  )
  invalidateCatalogCaches()
  return result
}

export async function deleteVersion(name: string, version: string): Promise<{ deleted: boolean }> {
  const result = await registrySend<{ deleted: boolean }>(
    `/entries/${encodeURIComponent(name)}/versions/${encodeURIComponent(version)}`,
    'DELETE'
  )
  invalidateCatalogCaches()
  return result
}

export async function publishEntry(body: Record<string, unknown>): Promise<unknown> {
  const result = await registrySend('/entries', 'POST', body)
  invalidateCatalogCaches()
  return result
}

// ── Org self-service (grants + owned entries) ─────────────────────────────────
// These proxy the registry's per-org owner surface (delivered by the machine-
// grant + owner-entries registry PRs). Unlike registryFetch, this helper:
//   • is 204/empty-aware (revokes return 204 with no body — res.json() would 500),
//   • throws a RegistryProxyError carrying the upstream status plus a narrowly
//     allowlisted error code, so the admin route can preserve the UI's typed
//     grant errors without reflecting arbitrary upstream diagnostics.
// Built on authedFetch (machine Bearer + 401-evict-retry), same as registryFetch.

export type RegistryProxyErrorBody = { error: string }

/** Upstream registry error carrying a status plus a safe, bounded error code. */
export class RegistryProxyError extends Error {
  constructor(
    readonly status: number,
    readonly body: RegistryProxyErrorBody
  ) {
    super(`Registry ${status}`)
    this.name = 'RegistryProxyError'
  }
}

// These are the only registry-owned codes that the current publisher UI renders
// specially. Keeping the values as an explicit allowlist means an upstream error
// cannot turn a raw message, HTML page, token, or credential into API output.
const SAFE_REGISTRY_PROXY_ERROR_CODES = new Set([
  'grantee_not_found',
  'self_grant',
  'plugin_public',
  'grantee_reserved',
  'plugin_not_found',
])

function registryProxyFallbackError(status: number): RegistryProxyErrorBody {
  return { error: status >= 400 && status <= 599 ? `registry_${status}` : 'registry_error' }
}

function isJsonResponse(res: Response): boolean {
  const contentType = res.headers.get('content-type')
  if (!contentType) return false
  const mediaType = contentType.split(';', 1)[0]?.trim().toLowerCase()
  return mediaType === 'application/json' || mediaType?.endsWith('+json') === true
}

async function registryProxyErrorBody(res: Response): Promise<RegistryProxyErrorBody> {
  const fallback = registryProxyFallbackError(res.status)
  if (!isJsonResponse(res)) {
    await discardResponseBody(res)
    return fallback
  }
  try {
    const parsed = (await res.json()) as unknown
    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return fallback
    const error = (parsed as { error?: unknown }).error
    if (typeof error !== 'string' || !SAFE_REGISTRY_PROXY_ERROR_CODES.has(error)) return fallback
    return { error }
  } catch {
    return fallback
  }
}

async function orgRegistryFetch<T>(path: string, init?: RequestInit): Promise<T> {
  const res = await authedFetch(path, init)
  if (!res.ok) {
    // A persistent 401 (authedFetch already evict-retried once) is a machine-token /
    // integration fault, NOT the admin's session — remap to 502 at the transport so
    // every caller is protected and control-ui never force-logs-out on it. A 403
    // (e.g. tenant client lacks registry:grant) keeps its status and, when known,
    // its safe typed code.
    if (res.status === 401) {
      await discardResponseBody(res)
      throw new RegistryProxyError(502, { error: 'registry_integration_error' })
    }
    throw new RegistryProxyError(res.status, await registryProxyErrorBody(res))
  }
  // Empty body (204 or any empty 2xx) → undefined. A non-empty non-JSON 2xx body is an
  // integration fault, surfaced as a typed 502 rather than a raw SyntaxError → 500.
  const text = await res.text()
  if (!text) return undefined as T
  try {
    return JSON.parse(text) as T
  } catch {
    throw new RegistryProxyError(502, { error: 'registry_integration_error' })
  }
}

export async function createOrgGrant(
  orgName: string,
  input: { pluginName: string; granteeOrg: string; actingUserId: string }
): Promise<unknown> {
  return orgRegistryFetch(`/org/${encodeURIComponent(orgName)}/grants`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(input),
  })
}

/**
 * Mint a PULL-ONLY registry credential for `orgName` using our machine identity.
 *
 * Hits the registry's `POST /org/:org/registry-pull-credential`, which — once the
 * companion registry change ships — authorizes an org-bound machine holding
 * `registry:manage-keys` (our tenant client's standing scope) to mint a pull-only,
 * rotate-on-call key for its OWN org. The endpoint also returns a `dockerconfigjson`,
 * but we DELIBERATELY ignore it: it is keyed on the registry's own token-issuer host,
 * whereas the kubelet matches on the image host (our configured registry URL host).
 * The caller builds the dockerconfigjson locally from `key`, keyed on that host.
 *
 * Rotate-on-call: each call revokes the org's prior pull key, so callers MUST
 * read-before-mint (only call when the on-cluster Secret is absent or broken) or they
 * orphan a working credential.
 *
 * Carries an explicit timeout: `authedFetch` only bounds GETs, and this POST sits on the
 * install path behind an in-process dedupe — a stalled origin would otherwise hang every
 * concurrent install for that namespace. The response is validated because a missing
 * `key` would otherwise render a valid-LOOKING dockerconfigjson (`_:undefined`) that gets
 * written as a permanently unusable credential which later reads classify as healthy.
 */
export async function mintOrgPullCredential(orgName: string): Promise<{ key: string }> {
  const res = await orgRegistryFetch<{ username: string; key: string; dockerconfigjson: string }>(
    `/org/${encodeURIComponent(orgName)}/registry-pull-credential`,
    { method: 'POST', signal: AbortSignal.timeout(READ_TIMEOUT_MS) }
  )
  if (!res || typeof res.key !== 'string' || res.key.length === 0) {
    throw new Error('registry returned no pull key for the image-pull credential')
  }
  return { key: res.key }
}

export async function listOrgGrants(orgName: string): Promise<unknown> {
  return orgRegistryFetch(`/org/${encodeURIComponent(orgName)}/grants`)
}

export async function revokeOrgGrant(
  orgName: string,
  grantId: string,
  actingUserId: string
): Promise<void> {
  await orgRegistryFetch(
    `/org/${encodeURIComponent(orgName)}/grants/${encodeURIComponent(grantId)}${buildQuery({
      actingUserId,
    })}`,
    { method: 'DELETE' }
  )
}

export async function listGrantedToMe(orgName: string): Promise<unknown> {
  return orgRegistryFetch(`/org/${encodeURIComponent(orgName)}/granted-to-me`)
}

export async function listOrgEntries(
  orgName: string,
  params?: { limit?: number; offset?: number }
): Promise<unknown> {
  return orgRegistryFetch(
    `/org/${encodeURIComponent(orgName)}/entries${buildQuery({
      limit: params?.limit,
      offset: params?.offset,
    })}`
  )
}

// ── Publish scope (who is this control-api, and where do its publishes land) ──
// Resolved from the registry's /whoami (the registry maps our machine OAuth
// client to its bound org / curator status). The module-level cache is scoped to
// the current registry identity generation and is invalidated when the local
// registry connection row or credentials change.
const PUBLISH_SCOPE_CACHE_TTL_MS = CATALOG_CACHE_TTL_MS

export interface PublishScope {
  curator: boolean
  orgName: string | null
  scope: string | null
}

let _scopeCache: { generation: number; scope: PublishScope; ts: number } | null = null
let _scopePending: { generation: number; promise: Promise<PublishScope> } | null = null

export async function whoami(): Promise<{
  clientId?: string
  orgName: string | null
  curator: boolean
}> {
  // registryFetch already prefixes /api/v1 and attaches the machine OAuth Bearer.
  return registryFetch('/whoami')
}

export async function resolvePublishScope(opts?: { force?: boolean }): Promise<PublishScope> {
  return withCurrentRegistryIdentity(
    generation => {
      if (
        _scopeCache &&
        _scopeCache.generation === generation &&
        Date.now() - _scopeCache.ts < PUBLISH_SCOPE_CACHE_TTL_MS &&
        !opts?.force
      )
        return Promise.resolve(_scopeCache.scope)
      const pending =
        !opts?.force && _scopePending?.generation === generation ? _scopePending : null
      if (pending) return pending.promise

      const promise = whoami().then(w => {
        const scope = {
          curator: w.curator,
          orgName: w.orgName,
          // Curator publishes stay unscoped (the registry maps them to @clerum).
          // Org-bound clients MUST scope to their own org or the registry 400s
          // (scope_required), so we derive the @<org> prefix here.
          scope: w.curator || !w.orgName ? null : `@${w.orgName}`,
        }
        if (isRegistryIdentityCacheGenerationCurrent(generation)) {
          _scopeCache = { generation, scope, ts: Date.now() }
        }
        return scope
      })
      if (!opts?.force) {
        _scopePending = { generation, promise }
        void promise
          .finally(() => {
            if (_scopePending?.promise === promise) _scopePending = null
          })
          .catch(() => undefined)
      }
      return promise
    },
    { staleError: staleRegistryIdentityError }
  )
}

export function __resetScopeCacheForTests(): void {
  _scopeCache = null
  _scopePending = null
}

/**
 * Prefix a publish name with the caller's org scope when org-bound.
 *
 * Org-bound clients (curator:false) must publish into their own org with a
 * scoped `@<org>/<name>` or the registry 400s (scope_required). Curator clients
 * (scope:null) publish unscoped and the registry maps them to the @clerum bridge
 * — so we leave their name untouched. An already-@-scoped name is respected
 * as-is, and a non-string / undefined name is returned unchanged.
 */
export function applyPublishScope(
  name: string | undefined,
  scope: PublishScope
): string | undefined {
  if (scope.scope && typeof name === 'string' && !name.startsWith('@')) {
    return `${scope.scope}/${name}`
  }
  return name
}