Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
import type { ReaderConfig } from './config.js'
import { fetchWithTimeout, timeoutErrorName } from './httpTimeout.js'
import { readerLogger } from './logger.js'
const log = readerLogger.child({ module: 'control-api-client' })
export type CanApproveResult = {
canApprove: boolean
reason?: string
}
export type ChannelRefResult =
| { ok: true; communicationChannelRef: string }
| { ok: false; error: string }
export type SlackTargetVerificationResult =
| {
ok: true
hostRef: string
communicationChannelRef: string
providerWorkspaceId: string
replyOnlyWhenMentioned?: boolean
replyInThreads?: boolean
channelName: string
channelNamespace: string
}
| { ok: false; status?: number; error: string }
export type TeamsTargetResolveResult =
| {
ok: true
hostRef: string
communicationChannelRef: string
providerWorkspaceId: string
appId: string
appName?: string
tenantId: string
replyOnlyWhenMentioned?: boolean
channelName: string
channelNamespace: string
}
| { ok: false; status?: number; error: string }
export type SlackTargetMessageResult =
| { ok: true; ts?: string | null }
| { ok: false; status?: number; error: string }
export type TeamsTargetMessageResult =
| { ok: true; id?: string | null }
| { ok: false; status?: number; error: string }
type SlackBlock = Record<string, unknown>
/**
* Figure D consulta (spec §10.3, diagram step 6): the reader asks control-api
* whether (providerUserId, channelAlias) may approve the given request, BEFORE
* forwarding the decision to the recipe mcp-host. This is a read-only
* validation — it never records the decision. The authoritative barrier is the
* D1 STRICT filter applied again at transmission time.
*
* Returns `null` when the consulta endpoint is not configured (no token/baseUrl
* in the reader config). Callers treat null as "skip consulta, forward to
* mcp-host" — transmission-time D1 STRICT remains the safety net.
*
* On any failure (non-2xx, timeout, network) the result is fail-safe:
* `{ canApprove: false, reason: '...' }`. Better to not forward than to forward
* without validation; the user can retry once control-api recovers.
*/
export async function canApprove(
cfg: ReaderConfig,
params: {
approvalRequestId: string
medium: string
providerUserId: string
providerWorkspaceId?: string | null
providerChannelId?: string | null
channelAlias: string
}
): Promise<CanApproveResult | null> {
if (!cfg.controlApiBaseUrl || !cfg.controlApiToken) {
return null
}
const base = cfg.controlApiBaseUrl.replace(/\/+$/, '')
const url = new URL(
`/api/v1/internal/workflow-approval-reader/approvals/${encodeURIComponent(params.approvalRequestId)}/can-approve`,
base
)
url.searchParams.set('medium', params.medium)
url.searchParams.set('providerUserId', params.providerUserId)
if (params.providerWorkspaceId) url.searchParams.set('providerWorkspaceId', params.providerWorkspaceId)
if (params.providerChannelId) url.searchParams.set('providerChannelId', params.providerChannelId)
url.searchParams.set('channelAlias', params.channelAlias)
let response: Response
try {
response = await fetchWithTimeout(
url.toString(),
{
method: 'GET',
headers: {
'x-service-token': 'workflow-approval-reader',
Authorization: `Bearer ${cfg.controlApiToken}`,
},
},
cfg.controlApiTimeoutMs
)
} catch (err) {
log.error('control-api can-approve consulta error', {
error: timeoutErrorName(err),
approvalRequestId: params.approvalRequestId,
})
return { canApprove: false, reason: 'consulta_error' }
}
const body = (await response.json().catch(() => ({}))) as Partial<CanApproveResult>
if (!response.ok) {
log.warn('control-api can-approve consulta non-2xx', {
status: response.status,
approvalRequestId: params.approvalRequestId,
})
return { canApprove: false, reason: 'consulta_failed' }
}
return {
canApprove: body.canApprove === true,
...(body.reason ? { reason: body.reason } : {}),
}
}
export async function resolveCommunicationChannelRef(
cfg: ReaderConfig,
params: {
medium: string
providerWorkspaceId?: string | null
providerChannelId?: string | null
}
): Promise<ChannelRefResult | null> {
if (!cfg.controlApiBaseUrl || !cfg.controlApiToken) return null
const base = cfg.controlApiBaseUrl.replace(/\/+$/, '')
const url = new URL('/api/v1/internal/workflow-approval-reader/channel-ref', base)
url.searchParams.set('medium', params.medium)
if (params.providerWorkspaceId) url.searchParams.set('providerWorkspaceId', params.providerWorkspaceId)
if (params.providerChannelId) url.searchParams.set('providerChannelId', params.providerChannelId)
let response: Response
try {
response = await fetchWithTimeout(
url.toString(),
{
method: 'GET',
headers: {
'x-service-token': 'workflow-approval-reader',
Authorization: `Bearer ${cfg.controlApiToken}`,
},
},
cfg.controlApiTimeoutMs
)
} catch (err) {
log.error('control-api channel-ref resolve error', {
error: timeoutErrorName(err),
medium: params.medium,
})
return { ok: false, error: 'channel_ref_resolve_error' }
}
const body = (await response.json().catch(() => ({}))) as {
communicationChannelRef?: string
error?: string
}
if (!response.ok) {
log.warn('control-api channel-ref resolve non-2xx', {
status: response.status,
medium: params.medium,
error: body.error,
})
return { ok: false, error: body.error ?? 'channel_ref_resolve_failed' }
}
const ref = body.communicationChannelRef?.trim()
return ref ? { ok: true, communicationChannelRef: ref } : { ok: false, error: 'channel_ref_missing' }
}
export async function verifySlackTargetSignature(
cfg: ReaderConfig,
params: {
targetId: string
timestamp: string
signature: string
rawBody: Buffer
}
): Promise<SlackTargetVerificationResult> {
if (!cfg.controlApiBaseUrl || !cfg.controlApiToken) {
return { ok: false, status: 503, error: 'control_api_not_configured' }
}
const base = cfg.controlApiBaseUrl.replace(/\/+$/, '')
const url = new URL(
`/api/v1/internal/workflow-approval-reader/slack-targets/${encodeURIComponent(params.targetId)}/verify-signature`,
base
)
let response: Response
try {
response = await fetchWithTimeout(
url.toString(),
{
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-service-token': 'workflow-approval-reader',
Authorization: `Bearer ${cfg.controlApiToken}`,
},
body: JSON.stringify({
timestamp: params.timestamp,
signature: params.signature,
rawBodyBase64: params.rawBody.toString('base64'),
}),
},
cfg.controlApiTimeoutMs
)
} catch (err) {
log.error('control-api slack target signature verify error', {
error: timeoutErrorName(err),
targetId: params.targetId,
})
return { ok: false, status: 504, error: 'slack_target_verify_error' }
}
const body = (await response.json().catch(() => ({}))) as Partial<
Extract<SlackTargetVerificationResult, { ok: true }>
> & { error?: string }
if (!response.ok || body.ok !== true) {
log.warn('control-api slack target signature verify non-2xx', {
status: response.status,
targetId: params.targetId,
error: body.error,
})
return {
ok: false,
status: response.status,
error: body.error ?? 'slack_target_verify_failed',
}
}
return {
ok: true,
hostRef: String(body.hostRef || ''),
communicationChannelRef: String(body.communicationChannelRef || ''),
providerWorkspaceId: String(body.providerWorkspaceId || ''),
replyOnlyWhenMentioned: body.replyOnlyWhenMentioned === true,
replyInThreads: body.replyInThreads === true,
channelName: String(body.channelName || ''),
channelNamespace: String(body.channelNamespace || ''),
}
}
export async function resolveTeamsTarget(
cfg: ReaderConfig,
params: {
targetId: string
}
): Promise<TeamsTargetResolveResult> {
if (!cfg.controlApiBaseUrl || !cfg.controlApiToken) {
return { ok: false, status: 503, error: 'control_api_not_configured' }
}
const base = cfg.controlApiBaseUrl.replace(/\/+$/, '')
const url = new URL(
`/api/v1/internal/workflow-approval-reader/teams-targets/${encodeURIComponent(params.targetId)}/resolve`,
base
)
let response: Response
try {
response = await fetchWithTimeout(
url.toString(),
{
method: 'GET',
headers: {
'x-service-token': 'workflow-approval-reader',
Authorization: `Bearer ${cfg.controlApiToken}`,
},
},
cfg.controlApiTimeoutMs
)
} catch (err) {
log.error('control-api teams target resolve error', {
error: timeoutErrorName(err),
targetId: params.targetId,
})
return { ok: false, status: 504, error: 'teams_target_resolve_error' }
}
const body = (await response.json().catch(() => ({}))) as Partial<
Extract<TeamsTargetResolveResult, { ok: true }>
> & { error?: string }
if (!response.ok || body.ok !== true) {
log.warn('control-api teams target resolve non-2xx', {
status: response.status,
targetId: params.targetId,
error: body.error,
})
return {
ok: false,
status: response.status,
error: body.error ?? 'teams_target_resolve_failed',
}
}
return {
ok: true,
hostRef: String(body.hostRef || ''),
communicationChannelRef: String(body.communicationChannelRef || ''),
providerWorkspaceId: String(body.providerWorkspaceId || body.tenantId || ''),
appId: String(body.appId || ''),
appName: String(body.appName || ''),
tenantId: String(body.tenantId || body.providerWorkspaceId || ''),
replyOnlyWhenMentioned: body.replyOnlyWhenMentioned === true,
channelName: String(body.channelName || ''),
channelNamespace: String(body.channelNamespace || ''),
}
}
async function postProviderTargetProxy(
cfg: ReaderConfig,
provider: 'slack' | 'teams',
path: string,
body: Record<string, unknown>
): Promise<SlackTargetMessageResult | TeamsTargetMessageResult> {
if (!cfg.controlApiBaseUrl || !cfg.controlApiToken) {
return { ok: false, status: 503, error: 'control_api_not_configured' }
}
const base = cfg.controlApiBaseUrl.replace(/\/+$/, '')
const url = new URL(path, base)
let response: Response
try {
response = await fetchWithTimeout(
url.toString(),
{
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-service-token': 'workflow-approval-reader',
Authorization: `Bearer ${cfg.controlApiToken}`,
},
body: JSON.stringify(body),
},
cfg.controlApiTimeoutMs
)
} catch (err) {
log.warn(`control-api ${provider} target proxy error`, {
error: timeoutErrorName(err),
path,
})
return { ok: false, status: 504, error: `${provider}_target_proxy_error` }
}
const responseBody = (await response.json().catch(() => ({}))) as {
ok?: boolean
ts?: string | null
id?: string | null
error?: string
}
if (!response.ok || responseBody.ok === false) {
log.warn(`control-api ${provider} target proxy non-2xx`, {
status: response.status,
path,
error: responseBody.error,
})
return {
ok: false,
status: response.status,
error: responseBody.error ?? `${provider}_target_proxy_failed`,
}
}
return { ok: true, ts: responseBody.ts ?? null, id: responseBody.id ?? null }
}
export function sendSlackTargetMessage(
cfg: ReaderConfig,
params: {
targetId: string
channelId: string
text: string
threadTs?: string | null
}
): Promise<SlackTargetMessageResult> {
return postProviderTargetProxy(
cfg,
'slack',
`/api/v1/internal/workflow-approval-reader/slack-targets/${encodeURIComponent(
params.targetId
)}/send-message`,
{
channelId: params.channelId,
text: params.text,
...(params.threadTs ? { threadTs: params.threadTs } : {}),
}
) as Promise<SlackTargetMessageResult>
}
export function updateSlackTargetMessage(
cfg: ReaderConfig,
params: {
targetId: string
channelId: string
messageTs: string
text: string
blocks?: SlackBlock[]
}
): Promise<SlackTargetMessageResult> {
return postProviderTargetProxy(
cfg,
'slack',
`/api/v1/internal/workflow-approval-reader/slack-targets/${encodeURIComponent(
params.targetId
)}/update-message`,
{
channelId: params.channelId,
messageTs: params.messageTs,
text: params.text,
...(params.blocks ? { blocks: params.blocks } : {}),
}
) as Promise<SlackTargetMessageResult>
}
export function updateTeamsTargetMessage(
cfg: ReaderConfig,
params: {
targetId: string
conversationId: string
messageId: string
serviceUrl: string
text: string
}
): Promise<TeamsTargetMessageResult> {
return postProviderTargetProxy(
cfg,
'teams',
`/api/v1/internal/workflow-approval-reader/teams-targets/${encodeURIComponent(
params.targetId
)}/update-message`,
{
conversationId: params.conversationId,
messageId: params.messageId,
serviceUrl: params.serviceUrl,
text: params.text,
}
) as Promise<TeamsTargetMessageResult>
}