Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
// Pure, testable state machine for the `source:'generic'` install wizard (S3-B4).
// The form state is the single source of truth; each event transforms it with a pure
// function. Nothing auto-applies: discovery/catalog SUGGEST, the operator confirms, and
// control-api arbitrates (S-4). This module owns no network and no React.
import type {
GenericClientMode,
GenericConfigSuggestion,
GenericDiscoveryPrefill,
GenericExtraParam,
GenericFieldOrigin,
GenericFormState,
GenericImmutableView,
GenericOAuthInstallSubmit,
GenericOAuthKnobs,
GenericTouchKey,
GenericWizardDefaults,
} from './oauthGeneric.types'
import type { OAuthGrantScope, OAuthSecretInput } from './oauthInstall.types'
// The wizard defaults (§5.1 "Default wizard" column = D-A1 defaults). The server writes
// no defaults (fidelity to a CRD with none); the wizard is the sole default provider.
export const GENERIC_WIZARD_DEFAULTS: GenericWizardDefaults = {
tokenRequestFormat: 'form',
tokenAuthMethod: 'body',
scopeSeparator: 'space',
sendScope: true,
usePkce: true,
includeResponseType: true,
supportsRefresh: true,
}
// The touch/origin keys, in a fixed order, so origin maps are always fully populated.
const TOUCH_KEYS: readonly GenericTouchKey[] = [
'authorizationEndpoint',
'tokenEndpoint',
'refreshEndpoint',
'resource',
'tokenRequestFormat',
'tokenAuthMethod',
'scopeSeparator',
'sendScope',
'usePkce',
'includeResponseType',
'supportsRefresh',
'scopes',
]
// The subset of fields that generic discovery can inform (§5.1, "fuentes ∋ discovery").
// Apply only ever touches these; every other field is catalog/manual only.
const DISCOVERY_FIELDS: readonly GenericTouchKey[] = [
'authorizationEndpoint',
'tokenEndpoint',
'resource',
'tokenAuthMethod',
'usePkce',
'supportsRefresh',
'scopes',
]
let paramCounter = 0
/** Stable, unique id for an extra-param row (non-index React key). */
function newParamId(): string {
paramCounter += 1
const rand =
typeof globalThis.crypto?.randomUUID === 'function'
? globalThis.crypto.randomUUID()
: Math.random().toString(36).slice(2)
return `gxp-${paramCounter}-${rand}`
}
/** A fresh, empty extra-param row for the editor. */
export function newExtraParamRow(): GenericExtraParam {
return { id: newParamId(), key: '', value: '' }
}
function extraParamsFromRecord(record: Record<string, string> | undefined): GenericExtraParam[] {
if (!record) return []
return Object.entries(record).map(([key, value]) => ({ id: newParamId(), key, value }))
}
/**
* Fold the extra-param editor rows into the wire record. Rows with a blank key are
* dropped (a half-typed row is not a param); a later duplicate key wins (last write).
*/
export function extraParamsToRecord(rows: readonly GenericExtraParam[]): Record<string, string> {
const out: Record<string, string> = {}
for (const row of rows) {
const key = row.key.trim()
if (key) out[key] = row.value
}
return out
}
function fullOrigin(value: GenericFieldOrigin): Record<GenericTouchKey, GenericFieldOrigin> {
const origin = {} as Record<GenericTouchKey, GenericFieldOrigin>
for (const key of TOUCH_KEYS) origin[key] = value
return origin
}
/**
* Mount-time seed (§5.3, "Montaje del wizard"). Each knob ← the catalog suggestion when
* present and of the right shape, else the wizard default; `origin` records which. The
* catalog SUGGESTS: an operator can still change anything afterwards. `clientMode` is
* confidential when the catalog pins `tokenAuthMethod:'basic'` (a Basic client needs a
* secret), else public (D-A5). `scopes` seed from the catalog's top-level scope list.
*/
export function seedFromCatalog(
defaults: GenericWizardDefaults,
suggestion?: GenericConfigSuggestion,
catalogScopes?: readonly string[]
): GenericFormState {
const s = suggestion ?? {}
const origin = fullOrigin('default')
function str(key: 'authorizationEndpoint' | 'tokenEndpoint' | 'refreshEndpoint' | 'resource') {
const v = s[key]
if (typeof v === 'string' && v.length > 0) {
origin[key] = 'catalog'
return v
}
return ''
}
function enumField<T extends string>(
key: 'tokenRequestFormat' | 'tokenAuthMethod' | 'scopeSeparator',
allowed: readonly T[],
fallback: T
): T {
const v = s[key]
if (typeof v === 'string' && (allowed as readonly string[]).includes(v)) {
origin[key] = 'catalog'
return v as T
}
return fallback
}
function bool(key: 'sendScope' | 'usePkce' | 'includeResponseType' | 'supportsRefresh'): boolean {
const v = s[key]
if (typeof v === 'boolean') {
origin[key] = 'catalog'
return v
}
return defaults[key]
}
const tokenAuthMethod = enumField(
'tokenAuthMethod',
['body', 'basic'] as const,
defaults.tokenAuthMethod
)
const scopes = (catalogScopes ?? []).filter(x => typeof x === 'string')
if (scopes.length > 0) origin.scopes = 'catalog'
return {
authorizationEndpoint: str('authorizationEndpoint'),
tokenEndpoint: str('tokenEndpoint'),
refreshEndpoint: str('refreshEndpoint'),
resource: str('resource'),
tokenRequestFormat: enumField(
'tokenRequestFormat',
['form', 'json'] as const,
defaults.tokenRequestFormat
),
tokenAuthMethod,
scopeSeparator: enumField(
'scopeSeparator',
['space', 'comma'] as const,
defaults.scopeSeparator
),
sendScope: bool('sendScope'),
usePkce: bool('usePkce'),
includeResponseType: bool('includeResponseType'),
supportsRefresh: bool('supportsRefresh'),
extraAuthorizeParams: extraParamsFromRecord(s.extraAuthorizeParams),
scopes,
// A Basic client needs a secret, so a catalog that pins basic implies confidential.
clientMode: tokenAuthMethod === 'basic' ? 'confidential' : 'public',
detected: null,
touched: new Set<GenericTouchKey>(),
origin,
}
}
/** Record the operator's edit of a field: mark touched, flip origin to 'edited'. */
export function markEdited(state: GenericFormState, field: GenericTouchKey): GenericFormState {
const touched = new Set(state.touched)
touched.add(field)
return { ...state, touched, origin: { ...state.origin, [field]: 'edited' } }
}
/**
* Edit an enum knob, upholding the basic⇒confidential invariant that `seedFromCatalog`
* and `applyDiscoveryPrefill` also maintain: selecting HTTP Basic client authentication
* forces a confidential client (a Basic header needs a client secret). Without this, the
* client-type toggle renders disabled (forced confidential via `effectiveClientMode`)
* while `clientMode` stays `'public'`, so the form could never validate and the one
* control that could fix it is disabled. Marks the edited field touched.
*/
export function editEnumKnob(
state: GenericFormState,
field: 'tokenRequestFormat' | 'tokenAuthMethod' | 'scopeSeparator',
value: string
): GenericFormState {
const next = markEdited({ ...state, [field]: value } as GenericFormState, field)
if (field === 'tokenAuthMethod' && value === 'basic') {
return { ...next, clientMode: 'confidential' }
}
return next
}
/**
* Apply a discovery result (§5.3, "Apply"). Only ever called on an explicit operator
* click — Detect alone stores `detected` and leaves the form untouched (invariant 8).
* For each field discovery can inform: value ← detected, UNLESS the operator has already
* edited it (`touched`) or discovery carries no datum for it ("sin dato nunca
* sobrescribe"). `scopes` fill only when currently empty. Idempotent by construction:
* Apply never marks a field touched, and re-applying the same result yields the same
* values, so `apply(apply(s,d),d) === apply(s,d)`.
*/
export function applyDiscoveryPrefill(
state: GenericFormState,
prefill: GenericDiscoveryPrefill
): GenericFormState {
const next: GenericFormState = { ...state, origin: { ...state.origin } }
const set = <K extends GenericTouchKey>(field: K, value: GenericFormState[K]) => {
if (state.touched.has(field)) return // manual wins
;(next[field] as GenericFormState[K]) = value
next.origin[field] = 'detected'
}
set('authorizationEndpoint', prefill.endpoints.authorization)
set('tokenEndpoint', prefill.endpoints.token)
// "Sin dato nunca sobrescribe": each suggestion is gated on the AS actually having
// advertised the underlying metadata, read off `capabilities` (the raw arrays).
if (prefill.resource) set('resource', prefill.resource)
if (prefill.capabilities.tokenEndpointAuthMethods.length > 0) {
set('tokenAuthMethod', prefill.suggested.tokenAuthMethod)
}
if (prefill.capabilities.codeChallengeMethods.length > 0) {
set('usePkce', prefill.suggested.usePkce)
}
if (prefill.capabilities.grantTypes.length > 0) {
set('supportsRefresh', prefill.suggested.supportsRefresh)
}
// Scopes fill only when empty AND not operator-edited: an operator-typed or
// catalog-seeded list is kept, and an explicitly cleared list is respected (§5.3,
// "nunca sobre edited").
if (
!state.touched.has('scopes') &&
state.scopes.length === 0 &&
prefill.scopesSupported.length > 0
) {
next.scopes = [...prefill.scopesSupported]
next.origin.scopes = 'detected'
}
// `tokenAuthMethod` may have moved to 'basic'; a Basic client must be confidential.
if (next.tokenAuthMethod === 'basic') next.clientMode = 'confidential'
return next
}
const HAS_SPACE = /\s/
function urlIssue(raw: string, label: string): string | undefined {
const value = raw.trim()
if (HAS_SPACE.test(value)) return `${label} must not contain spaces.`
let parsed: URL
try {
parsed = new URL(value)
} catch {
return `${label} must be an absolute https URL.`
}
if (parsed.protocol !== 'https:') return `${label} must use https.`
if (!parsed.hostname.includes('.')) return `${label} must have a fully-qualified hostname.`
return undefined
}
/**
* Client-side FORM validation for the generic wizard (UX only — the 422 from control-api
* is the authority). Returns a `field → message` map keyed by wizard field ids. Covers:
* required/absolute-https endpoints, optional refresh/resource URLs, `basic ⇒
* confidential`, `sendScope ⇒ ≥1 scope` (DA-4/GAP-6), and the extra-param bounds.
*/
export function genericFormIssues(state: GenericFormState): Record<string, string> {
const issues: Record<string, string> = {}
const authIssue = state.authorizationEndpoint.trim()
? urlIssue(state.authorizationEndpoint, 'Authorization endpoint')
: 'Authorization endpoint is required.'
if (authIssue) issues.authorizationEndpoint = authIssue
const tokenIssue = state.tokenEndpoint.trim()
? urlIssue(state.tokenEndpoint, 'Token endpoint')
: 'Token endpoint is required.'
if (tokenIssue) issues.tokenEndpoint = tokenIssue
if (state.refreshEndpoint.trim()) {
const issue = urlIssue(state.refreshEndpoint, 'Refresh endpoint')
if (issue) issues.refreshEndpoint = issue
}
if (state.resource.trim()) {
const issue = urlIssue(state.resource, 'Resource')
if (issue) issues.resource = issue
}
if (state.tokenAuthMethod === 'basic' && state.clientMode !== 'confidential') {
issues.tokenAuthMethod =
'Basic client authentication requires a confidential client with a client secret.'
}
if (state.sendScope && state.scopes.length === 0) {
issues.scopes = 'Add at least one scope, or turn off “Send scope” to authorize without one.'
}
const rows = state.extraAuthorizeParams
const nonEmpty = rows.filter(r => r.key.trim())
if (nonEmpty.length > 16) {
issues.extraAuthorizeParams = 'At most 16 extra authorize params are allowed.'
} else if (nonEmpty.some(r => r.value.length > 1024)) {
issues.extraAuthorizeParams = 'An extra authorize param value must be 1024 characters or fewer.'
} else {
const keys = nonEmpty.map(r => r.key.trim())
if (new Set(keys).size !== keys.length) {
issues.extraAuthorizeParams = 'Extra authorize param keys must be unique.'
}
}
return issues
}
/** True when the generic form has no client-side blocking issue. */
export function genericFormOk(state: GenericFormState): boolean {
return Object.keys(genericFormIssues(state)).length === 0
}
/**
* Build the `body.oauth` sub-object for a generic install (§5.1 knob→wire). Sends the 10
* required knobs explicitly plus the optional ones only when present. `secret` is
* attached only for a confidential client (the caller passes it, or nothing for public).
*/
export function buildGenericSubmit(
state: GenericFormState,
grantScope: OAuthGrantScope,
secret?: OAuthSecretInput
): GenericOAuthInstallSubmit {
const generic: GenericOAuthKnobs = {
authorizationEndpoint: state.authorizationEndpoint.trim(),
tokenEndpoint: state.tokenEndpoint.trim(),
tokenRequestFormat: state.tokenRequestFormat,
tokenAuthMethod: state.tokenAuthMethod,
scopeSeparator: state.scopeSeparator,
sendScope: state.sendScope,
usePkce: state.usePkce,
includeResponseType: state.includeResponseType,
supportsRefresh: state.supportsRefresh,
}
const refresh = state.refreshEndpoint.trim()
if (refresh) generic.refreshEndpoint = refresh
const resource = state.resource.trim()
if (resource) generic.resource = resource
const extra = extraParamsToRecord(state.extraAuthorizeParams)
if (Object.keys(extra).length > 0) generic.extraAuthorizeParams = extra
const submit: GenericOAuthInstallSubmit = {
scopes: state.scopes,
grantScope,
generic,
}
if (secret) submit.secret = secret
return submit
}
function asString(value: unknown): string {
return typeof value === 'string' ? value : ''
}
function asBool(value: unknown): boolean {
return value === true
}
/**
* Read the immutable generic knobs off an installed connector's `spec.oauth` for the
* read-only edit view (D-B7). `clientMode` is inferred from the presence of the paired
* client refs (confidential) vs their absence (public, DA-1). Tolerant of a malformed CR
* (missing/extra fields) — the edit view must never crash on unexpected data (§9 risk 7).
*/
export function readGenericImmutables(oauth: Record<string, unknown>): GenericImmutableView {
const extraRaw = oauth.extraAuthorizeParams
const extraAuthorizeParams: GenericExtraParam[] =
extraRaw && typeof extraRaw === 'object' && !Array.isArray(extraRaw)
? Object.entries(extraRaw as Record<string, unknown>).map(([key, value]) => ({
id: newParamId(),
key,
value: asString(value),
}))
: []
const hasSecret =
(oauth.clientSecretRef !== undefined && oauth.clientSecretRef !== null) ||
(oauth.clientIdRef !== undefined && oauth.clientIdRef !== null)
return {
authorizationEndpoint: asString(oauth.authorizationEndpoint),
tokenEndpoint: asString(oauth.tokenEndpoint),
refreshEndpoint: asString(oauth.refreshEndpoint),
resource: asString(oauth.resource),
tokenRequestFormat: asString(oauth.tokenRequestFormat),
tokenAuthMethod: asString(oauth.tokenAuthMethod),
scopeSeparator: asString(oauth.scopeSeparator),
sendScope: asBool(oauth.sendScope),
usePkce: asBool(oauth.usePkce),
includeResponseType: asBool(oauth.includeResponseType),
supportsRefresh: asBool(oauth.supportsRefresh),
clientMode: hasSecret ? 'confidential' : 'public',
extraAuthorizeParams,
}
}
/** The effective client mode: `basic` token auth forces confidential regardless of toggle. */
export function effectiveClientMode(state: GenericFormState): GenericClientMode {
return state.tokenAuthMethod === 'basic' ? 'confidential' : state.clientMode
}