Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
import { type PinnedFetchError, type PinnedTransport, pinnedFetch } from '../http/pinnedFetch.js'
import type { DnsResolver, ValidationError } from '../http/validateMcpServerSpec.js'
import { type Logger, rootLogger } from '../observability/logger.js'
import { MAX_CLIENT_ID_LENGTH } from './cimdIdentity.js'
import type { DiscoveryResult } from './discovery.js'
import type { RemoteCallbackVariant } from './remoteCallback.js'
/**
* Dynamic Client Registration client (RFC 7591), spec 02 C2 / D-5 / DEC-18.
*
* When discovery (`discovery.ts`) resolves the registration mode to `dcr` — the
* AS offers neither a pre-registered client nor CIMD — control-api registers a
* client dynamically against the AS's registration endpoint and the caller
* persists the returned credentials in the encrypted `dynamic_clients` store.
*
* Mirrors `discovery.ts`: pure request builder, effectful register with a typed
* outcome and injectable deps. The registration endpoint was already kernel-
* validated during discovery; the POST here re-pins it through `pinnedFetch`
* (single hop, no redirect following) so it is re-validated at connect time too
* (S-1 structural). This module NEVER follows a 3xx to a `Location` (a redirect
* is fail-closed `redirect_blocked`) — an AS re-pointing the registration POST to
* an internal host is a classic SSRF, not a legitimate flow.
*/
const DCR_TIMEOUT_MS = 15_000
/** Field name used when reporting a kernel rejection of the registration endpoint. */
const REGISTRATION_ENDPOINT_FIELD = 'spec.oauth.registrationEndpoint'
/**
* The auth methods control-api can actually present at the token endpoint. The
* generic remote token builders (`providers.ts`) emit `client_secret_post` only
* (never HTTP Basic), and a public client uses `none`. Any other assignment by
* the AS — notably `client_secret_basic` — is one we cannot honor, so we refuse
* to store a client we could never authenticate (fail-closed).
*/
const PRESENTABLE_AUTH_METHODS = new Set(['none', 'client_secret_post'])
// ─── RFC 7591 shapes (request we send; response is third-party data) ────────
export interface DcrRegistrationRequest {
redirect_uris: string[]
token_endpoint_auth_method: 'none' | 'client_secret_post'
grant_types: string[]
response_types: ['code']
client_name: 'Evenfire'
application_type: 'web'
scope?: string
}
/** RFC 7591 §3.2.1 registration response — every field is untrusted AS data. */
export interface DcrRegistrationResponse {
client_id: string
client_secret?: string
/** NumericDate (epoch seconds). */
client_id_issued_at?: number
/** NumericDate (epoch seconds); 0 ⇒ non-expiring. */
client_secret_expires_at?: number
/** RFC 7592 management bearer — as sensitive as the secret. */
registration_access_token?: string
/** RFC 7592 management endpoint. */
registration_client_uri?: string
token_endpoint_auth_method?: string
/**
* RFC 7591 §3.2.1: the AS echoes the registered metadata, including the redirect
* URIs it actually accepted. Untrusted — check it with {@link verifyDcrRedirectUris}.
*/
redirect_uris?: unknown
[k: string]: unknown
}
/**
* RFC 7592 mint handle carried on the *minted-but-rejected* error variants: a 2xx
* response that DID assign a `client_id` (a real client exists at the AS) but is
* unusable to us. It lets the caller run the best-effort RFC 7592 cleanup DELETE so
* the orphaned client does not linger (DEC-18). Present ONLY on those variants and
* ONLY when the AS returned a management endpoint + token; never on non-2xx errors
* (`fetch_failed`/`redirect_blocked`/`kernel_rejected`) where nothing was minted.
* In-memory only — used solely for the cleanup DELETE, never persisted or logged.
*/
export interface DcrMintHandle {
/**
* Set when a client WAS minted at the AS, with or without a management handle, so
* the caller can tell "cleaned up" from "left behind" when the handle is missing.
*/
minted?: true
registrationClientUri?: string
registrationAccessToken?: string
}
export type DcrError =
| { kind: 'kernel_rejected'; field: string; errors: ValidationError[] }
| { kind: 'fetch_failed'; url: string; status?: number; detail: string }
/** A 3xx from the registration POST — never re-POSTed to `Location` (SSRF fail-closed). */
| { kind: 'redirect_blocked'; url: string; detail: string }
/**
* 2xx but the body is not a usable RFC 7591 registration (missing client_id, etc.).
* Carries a mint handle ONLY for the confidential-without-`client_secret` case,
* where a real `client_id` was assigned; the parse/no-client_id cases mint nothing.
*/
| ({ kind: 'invalid_response'; url: string; detail: string } & DcrMintHandle)
/** The AS assigned a token_endpoint_auth_method we cannot present (e.g. client_secret_basic). */
| ({ kind: 'auth_method_unsupported'; detail: string } & DcrMintHandle)
/** Response arrived with a non-identity content-encoding (fail-closed, never mis-parse). */
| { kind: 'content_encoding_rejected'; url: string; encoding: string }
export type DcrOutcome =
| {
ok: true
response: DcrRegistrationResponse
/**
* The auth method that actually governs the minted client — the AS's
* assignment when it overrode our request, else what we asked for. The AS is
* the final authority (RFC 7591), so a confidential request the AS downgrades
* to `none` yields `effectiveAuthMethod: 'none'` here, NOT what we requested.
*/
effectiveAuthMethod: 'none' | 'client_secret_post'
/** `public` iff `effectiveAuthMethod` is `none`; the caller persists THIS mode. */
effectiveClientMode: 'public' | 'confidential'
}
| { ok: false; error: DcrError }
export interface DcrDeps {
transport?: PinnedTransport
resolveDns?: DnsResolver
logger?: Logger
}
/**
* Build the RFC 7591 registration request (pure). `token_endpoint_auth_method` is
* `none` for a public client (AS lists `none`) or `client_secret_post` for a
* confidential one. `refresh_token` is added to `grant_types` ONLY when the AS
* advertised it (invariant §6 #8, fail-closed) — never register a refresh grant
* against an AS that did not advertise it. `redirect_uris` is the single source of
* truth passed in by the caller (the CIMD remote callback), never re-hardcoded.
*/
export function buildDcrRequest(
discovery: DiscoveryResult,
opts: { clientMode: 'public' | 'confidential'; redirectUris: string[]; scopes?: string[] }
): DcrRegistrationRequest {
const grantTypes = ['authorization_code']
if (discovery.quirks.supportsRefresh) grantTypes.push('refresh_token')
const request: DcrRegistrationRequest = {
redirect_uris: opts.redirectUris,
token_endpoint_auth_method: opts.clientMode === 'public' ? 'none' : 'client_secret_post',
grant_types: grantTypes,
response_types: ['code'],
client_name: 'Evenfire',
application_type: 'web',
}
if (opts.scopes && opts.scopes.length > 0) request.scope = opts.scopes.join(' ')
return request
}
function isRedirectStatus(status: number): boolean {
return status === 301 || status === 302 || status === 303 || status === 307 || status === 308
}
function isRecord(v: unknown): v is Record<string, unknown> {
return typeof v === 'object' && v !== null && !Array.isArray(v)
}
/** Map a pinned-fetch error onto DCR's typed error union. */
function mapPinnedError(error: PinnedFetchError, url: string): DcrError {
switch (error.kind) {
case 'kernel_rejected':
return { kind: 'kernel_rejected', field: error.field, errors: error.errors }
case 'transport_failed':
return { kind: 'fetch_failed', url, detail: error.detail }
case 'content_encoding_rejected':
return { kind: 'content_encoding_rejected', url, encoding: error.encoding }
}
}
/** Compose a human-readable detail from an RFC 6749-style error body, if present. */
function errorBodyDetail(status: number, bodyText: string): string {
try {
const parsed = JSON.parse(bodyText)
if (isRecord(parsed) && typeof parsed.error === 'string') {
const description =
typeof parsed.error_description === 'string' ? `: ${parsed.error_description}` : ''
return `${parsed.error}${description}`
}
} catch {
// Non-JSON error body — fall through to the bare status.
}
return `HTTP ${status}`
}
/**
* Register a dynamic client (RFC 7591) at `endpoint`. Single-hop POST through
* `pinnedFetch` (re-validates + pins the endpoint); a 3xx is `redirect_blocked`
* and never followed. The AS response is untrusted: a missing `client_id` or an
* un-presentable `token_endpoint_auth_method` is a typed, fail-closed error, so we
* never persist a client we cannot use.
*/
export async function registerDynamicClient(
deps: DcrDeps,
endpoint: string,
request: DcrRegistrationRequest
): Promise<DcrOutcome> {
const log = (deps.logger ?? rootLogger).child({ module: 'oauth-dcr' })
const body = JSON.stringify(request)
const fetched = await pinnedFetch(endpoint, REGISTRATION_ENDPOINT_FIELD, {
method: 'POST',
headers: {
'content-type': 'application/json',
'content-length': String(Buffer.byteLength(body)),
},
body,
resolveDns: deps.resolveDns,
transport: deps.transport,
timeoutMs: DCR_TIMEOUT_MS,
})
if (!fetched.ok) {
const error = mapPinnedError(fetched.error, endpoint)
log.warn({ dcr: error.kind }, 'dynamic client registration transport failed')
return { ok: false, error }
}
const response = fetched.response
if (isRedirectStatus(response.status)) {
// Never re-POST to a Location: an AS redirecting the registration is a
// fail-closed SSRF vector (H2), not a flow to follow.
log.warn({ dcr: 'redirect_blocked', status: response.status }, 'dcr registration redirected')
return {
ok: false,
error: {
kind: 'redirect_blocked',
url: endpoint,
detail: `HTTP ${response.status} redirect on the registration POST`,
},
}
}
const isSuccess = response.status >= 200 && response.status < 300
if (!isSuccess) {
const detail = errorBodyDetail(response.status, response.bodyText)
log.warn({ dcr: 'fetch_failed', status: response.status }, 'dcr registration rejected')
return {
ok: false,
error: { kind: 'fetch_failed', url: endpoint, status: response.status, detail },
}
}
let parsed: unknown
try {
parsed = JSON.parse(response.bodyText)
} catch (e) {
return {
ok: false,
error: {
kind: 'invalid_response',
url: endpoint,
detail: e instanceof Error ? e.message : String(e),
},
}
}
if (!isRecord(parsed) || typeof parsed.client_id !== 'string' || parsed.client_id.length === 0) {
return {
ok: false,
error: {
kind: 'invalid_response',
url: endpoint,
detail: 'registration response has no client_id',
},
}
}
const assigned = parsed as DcrRegistrationResponse
// An oversized client_id is refused before anything compares, stores or logs it. A
// client WAS minted, so the RFC 7592 handle goes back for cleanup.
if (Buffer.byteLength(assigned.client_id, 'utf8') > MAX_CLIENT_ID_LENGTH) {
return {
ok: false,
error: {
kind: 'invalid_response',
url: endpoint,
detail: `registration response client_id exceeds ${MAX_CLIENT_ID_LENGTH} bytes`,
minted: true,
registrationClientUri: stringOrUndefined(assigned.registration_client_uri),
registrationAccessToken: stringOrUndefined(assigned.registration_access_token),
},
}
}
// Fail-closed on an auth method we cannot present. The AS's assignment wins over
// what we requested; a bare absence (undefined/null) means it honored our request.
// The AS response is untrusted, so we reject anything that is NOT a presentable
// string here — an un-presentable method (e.g. client_secret_basic) OR a non-string
// the AS injected (e.g. a number/object). Both fail closed to `auth_method_unsupported`
// so a garbage value never reaches the effective-mode cast/derivation below.
const effectiveAuthMethod =
assigned.token_endpoint_auth_method ?? request.token_endpoint_auth_method
if (
typeof effectiveAuthMethod !== 'string' ||
!PRESENTABLE_AUTH_METHODS.has(effectiveAuthMethod)
) {
log.warn(
{ dcr: 'auth_method_unsupported', assigned: effectiveAuthMethod },
'dcr registration assigned an un-presentable token_endpoint_auth_method'
)
return {
ok: false,
error: {
kind: 'auth_method_unsupported',
detail: `authorization server assigned token_endpoint_auth_method "${effectiveAuthMethod}", which control-api cannot present`,
// A client WAS minted (2xx + client_id) but is unusable — expose the RFC 7592
// handle so the caller can clean it up.
minted: true,
registrationClientUri: assigned.registration_client_uri,
registrationAccessToken: assigned.registration_access_token,
},
}
}
// Past the PRESENTABLE guard the effective method is one of the two we can present.
// It — not what we requested — is the final authority on public vs confidential.
const presentedAuthMethod = effectiveAuthMethod as 'none' | 'client_secret_post'
const effectiveClientMode: 'public' | 'confidential' =
presentedAuthMethod === 'none' ? 'public' : 'confidential'
// A confidential-EFFECTIVE registration MUST hand us a secret; otherwise we would
// persist a client_secret_post client we can never authenticate. Anchoring this on
// the EFFECTIVE method (not what we requested) is deliberate: when the AS downgrades
// a confidential request to public (`none`, no secret), that is a valid public
// client per RFC 7591 — the AS owns the auth method — not an error (Vercel does this).
if (effectiveClientMode === 'confidential' && typeof assigned.client_secret !== 'string') {
return {
ok: false,
error: {
kind: 'invalid_response',
url: endpoint,
detail: 'confidential registration returned no client_secret',
// A client WAS minted (2xx + client_id) but is unusable — expose the RFC 7592
// handle so the caller can clean it up.
minted: true,
registrationClientUri: assigned.registration_client_uri,
registrationAccessToken: assigned.registration_access_token,
},
}
}
return {
ok: true,
response: assigned,
effectiveAuthMethod: presentedAuthMethod,
effectiveClientMode,
}
}
function stringOrUndefined(value: unknown): string | undefined {
return typeof value === 'string' && value.length > 0 ? value : undefined
}
export type DcrRedirectUrisCheck =
| { ok: true }
| { ok: false; reason: 'redirect_uris_missing' | 'redirect_uris_mismatch' }
/**
* Check the `redirect_uris` a registration response reports against the ones we sent.
*
* per-server: REQUIRED and exactly equal (same strings, no normalization). The
* per-server redirect URI is the only mix-up defence there, so a client
* the AS registered with a different or unreported URI cannot be trusted
* to redirect only to this installation.
* shared: the response `iss` is the defence, so an ABSENT (or `null`) field is
* tolerated (ASes that omit the echo keep working); a PRESENT one that
* differs still fails.
*
* Comparison is set equality over exact strings (RFC 7591 gives the array no order).
* Pure; the caller turns a failure into an install failure with RFC 7592 cleanup.
*/
export function verifyDcrRedirectUris(input: {
variant: RemoteCallbackVariant
requested: readonly string[]
response: Pick<DcrRegistrationResponse, 'redirect_uris'>
}): DcrRedirectUrisCheck {
const reported = input.response.redirect_uris
// JSON `null` is how some serializers spell an omitted field, so it counts as absent.
if (reported === undefined || reported === null) {
return input.variant === 'shared'
? { ok: true }
: { ok: false, reason: 'redirect_uris_missing' }
}
if (
!Array.isArray(reported) ||
reported.length !== input.requested.length ||
!reported.every(uri => typeof uri === 'string' && input.requested.includes(uri)) ||
!input.requested.every(uri => reported.includes(uri))
) {
return { ok: false, reason: 'redirect_uris_mismatch' }
}
return { ok: true }
}