Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
import { type NextFunction, type Request, type Response, Router } from 'express'
import { PROVIDER_AUTH_MODE, isLlmProviderId } from '@clerum/llm-providers'
import { config } from '../../config.js'
import { pool } from '../../db.js'
import { asyncHandler } from '../../http/asyncHandler.js'
import { requireMcpHostJwt } from '../../middleware/mcpHostJwtAuth.js'
import {
createPluginWorkloadSdkAnonymousPreauthRateLimit,
createPluginWorkloadSdkAuthenticatedPreauthRateLimit,
createPluginWorkloadSdkRequestRateLimit,
createPluginWorkloadSdkVerificationBudgetRateLimit,
pluginWorkloadSdkCredentialBucketKey,
} from '../../middleware/pluginWorkloadSdkRateLimits.js'
import { rateLimitMiddleware } from '../../middleware/rateLimitMiddleware.js'
import { pluginWorkloadSdkNotificationAuthDurationSeconds } from '../../observability/metrics.js'
import { getSafeCodexSubscriptionConnection } from '../../services/codexSubscriptionConnection.js'
import { getSafeGrokSubscriptionConnection } from '../../services/grokSubscriptionConnection.js'
import { enqueuePluginWorkloadSdkNotification } from '../../services/notificationEmitter.js'
import {
type PluginWorkloadSdkAuthzError,
authorizeClientNotification,
authorizeListRecipients,
authorizePromptBridge,
reissuePromptBridgeCredentialTicket,
} from '../../services/pluginWorkloadSdkAuthorizer.js'
import { verifyPluginWorkloadSdkCredentialTicket } from '../../services/pluginWorkloadSdkCredentialTicket.js'
import {
DEFAULT_IDEMPOTENCY_KEY_PATTERN,
DEFAULT_MAX_BODY_BYTES,
DEFAULT_MAX_REQUEST_CONTENT_BYTES,
DEFAULT_MAX_TITLE_BYTES,
MAX_IDEMPOTENCY_KEY_LENGTH,
MAX_TARGET_REF_LENGTH,
MAX_USER_REF_LENGTH,
PLUGIN_WORKLOAD_SDK_PURPOSES,
type PluginWorkloadSdkErrorCode,
} from '../../services/pluginWorkloadSdkDb.js'
import {
findGrant,
getInvocationById,
getPluginWorkloadSdkAttemptReceipt,
getPluginWorkloadSdkProviderAttempt,
hasUsableClientNotificationRecipients,
hashPromptTargetPolicy,
isClientNotificationsPolicyReady,
listInvocations,
markPluginWorkloadSdkProviderAttemptStatus,
redeemPluginWorkloadSdkCredentialTicketJti,
resolveRecipientProfiles,
} from '../../services/pluginWorkloadSdkDb.js'
import {
PromptBridgeFinalizationError,
type PromptBridgeFinalizationInput,
finalizePromptBridge,
} from '../../services/pluginWorkloadSdkFinalization.js'
import { markInvocationStatus } from '../../services/pluginWorkloadSdkInvocationAuditor.js'
import type { McpHostAccessClaims } from '../../utils/auth/mcpHostJwtToken.js'
import { isPlainObject } from '../../utils/isPlainObject.js'
// ─── Plugin Workload SDK — mcp-host gateway routes (plan §2.5, §2.7) ─────
// Registered under the /mcp-host/ prefix so SDK traffic follows the same
// host/control gateway path as every other mcp-host runtime call
// (conformance: spec §19 "mcp-host control-api access uses the gateway").
//
// POST /mcp-host/plugin-workload-sdk/prompt-bridge/v2
// GET /mcp-host/plugin-workload-sdk/capabilities
// POST /mcp-host/plugin-workload-sdk/client-notification
// POST /mcp-host/plugin-workload-sdk/prompt-bridge/credential-ticket
// GET /mcp-host/plugin-workload-sdk/invocations/:recipeRef
const IDEMPOTENCY_KEY_RE = new RegExp(DEFAULT_IDEMPOTENCY_KEY_PATTERN)
const PURPOSE_SET = new Set<string>(PLUGIN_WORKLOAD_SDK_PURPOSES)
/** Opaque refs must not smuggle raw channel addresses (spec §17). */
const EMAIL_LIKE_RE = /@/
const PHONE_LIKE_RE = /^\+?[0-9][0-9\s().-]{6,}$/
/** Current target-aware/JIT promptBridge wire contract. */
export const PLUGIN_WORKLOAD_SDK_PROMPT_BRIDGE_CONTRACT_VERSION = 2
// Credential-ticket introspection and reissue both perform signature checks,
// database reads, and (for reissue) signing work before the provider call.
// Bound the cost per recipe after JWT authentication, while the authorizer's
// grant rate/quota remains the product-level invocation limit.
const pluginWorkloadSdkCredentialRateLimit = rateLimitMiddleware({
bucketType: 'plugin_workload_sdk_credential',
maxPerMinute: config.pluginSdkCredentialRlPerMin,
getBucketKey: pluginWorkloadSdkCredentialBucketKey,
onBackendUnavailable: 'process-memory',
})
function requirePluginWorkloadSdkScope(req: Request, res: Response, next: NextFunction): void {
const claims = req.mcpHostJwt
if (!claims?.workflowControlScopes.includes('plugin-workload-sdk')) {
res.status(403).json({ error: 'scope_denied', retryable: false })
return
}
next()
}
const AUTHZ_HTTP_STATUS: Record<PluginWorkloadSdkErrorCode, number> = {
capability_not_declared: 403,
caller_not_allowed: 403,
scope_denied: 403,
target_not_allowed: 403,
ambiguous_model: 409,
event_type_not_allowed: 403,
quota_exceeded: 429,
provider_policy_denied: 403,
provider_unavailable: 503,
payload_too_large: 413,
idempotency_conflict: 422,
recipe_binding_mismatch: 400,
protocol_mismatch: 503,
}
function sendAuthzError(res: Response, error: PluginWorkloadSdkAuthzError): void {
res.status(AUTHZ_HTTP_STATUS[error.error] ?? 403).json({
error: error.error,
message: error.message,
retryable: error.retryable,
})
}
/**
* Binding-match enforcement (same contract as workflow approvals): the body
* MUST carry recipeNamespace/recipeName and both MUST equal the JWT claims —
* otherwise a token issued for one recipe could act on another.
*/
function checkRecipeBinding(
body: Record<string, unknown>,
claims: McpHostAccessClaims,
res: Response
): boolean {
const ns = typeof body.recipeNamespace === 'string' ? body.recipeNamespace.trim() : ''
const name = typeof body.recipeName === 'string' ? body.recipeName.trim() : ''
if (!ns || !name) {
res.status(400).json({ error: 'recipeNamespace and recipeName are required in body' })
return false
}
if (ns !== claims.recipeNamespace || name !== claims.recipeName) {
res.status(400).json({ error: 'recipe_binding_mismatch' })
return false
}
return true
}
function validateIdempotencyKey(value: unknown, res: Response): string | null {
if (typeof value !== 'string' || value.length === 0) {
res.status(400).json({ error: 'idempotencyKey is required' })
return null
}
if (value.length > MAX_IDEMPOTENCY_KEY_LENGTH || !IDEMPOTENCY_KEY_RE.test(value)) {
res.status(400).json({ error: 'invalid_idempotency_key' })
return null
}
return value
}
function validateCallerRef(value: unknown, res: Response): string | null {
if (typeof value !== 'string' || !value.trim()) {
res.status(400).json({ error: 'callerRef is required' })
return null
}
return value.trim()
}
function parsePromptBridgeFinalizationBody(
body: Record<string, unknown>,
claims: McpHostAccessClaims,
res: Response
): PromptBridgeFinalizationInput | null {
const invocationId = typeof body.invocationId === 'string' ? body.invocationId.trim() : ''
const providerAttemptId =
typeof body.providerAttemptId === 'string' ? body.providerAttemptId.trim() : ''
const attemptGeneration = Number.isInteger(body.attemptGeneration)
? Number(body.attemptGeneration)
: 0
const providerAttemptIndex = Number.isInteger(body.providerAttemptIndex)
? Number(body.providerAttemptIndex)
: 0
const status = body.status
const reason = typeof body.reason === 'string' ? body.reason.trim() : ''
const target = isPlainObject(body.target) ? body.target : null
const targetRef = typeof target?.targetRef === 'string' ? target.targetRef.trim() : ''
const provider = typeof target?.provider === 'string' ? target.provider.trim() : ''
const model = typeof target?.model === 'string' ? target.model.trim() : ''
const credentialSlot =
typeof target?.credentialSlot === 'string' ? target.credentialSlot.trim() : ''
if (
!invocationId ||
!providerAttemptId ||
attemptGeneration < 1 ||
providerAttemptIndex < 1 ||
providerAttemptIndex > 4 ||
!['complete', 'failed', 'provider_unavailable'].includes(String(status)) ||
!reason ||
reason.length > 128 ||
!targetRef ||
!provider ||
!model
) {
res.status(400).json({
error:
'invocationId, attemptGeneration, providerAttemptId, providerAttemptIndex, status, reason and target are required',
})
return null
}
const rawUsage = body.usage
let usage: PromptBridgeFinalizationInput['usage']
if (rawUsage !== undefined) {
if (!isPlainObject(rawUsage)) {
res.status(400).json({ error: 'usage must be an object' })
return null
}
const llmSecretName =
typeof rawUsage.llmSecretName === 'string' ? rawUsage.llmSecretName.trim() : ''
const callerRef = typeof rawUsage.callerRef === 'string' ? rawUsage.callerRef.trim() : ''
const attemptCount = Number.isInteger(rawUsage.attemptCount) ? Number(rawUsage.attemptCount) : 0
const inputTokens = Number.isInteger(rawUsage.inputTokens) ? Number(rawUsage.inputTokens) : -1
const outputTokens = Number.isInteger(rawUsage.outputTokens)
? Number(rawUsage.outputTokens)
: -1
if (
!callerRef ||
typeof rawUsage.fallbackUsed !== 'boolean' ||
attemptCount < 1 ||
attemptCount > 4 ||
inputTokens < 0 ||
outputTokens < 0
) {
res.status(400).json({ error: 'usage fields are invalid' })
return null
}
usage = {
llmSecretName,
callerRef,
fallbackUsed: rawUsage.fallbackUsed,
attemptCount,
inputTokens,
outputTokens,
}
}
return {
invocationId,
recipeNamespace: claims.recipeNamespace,
recipeName: claims.recipeName,
hostRef: claims.hostRefs[0] ?? '',
attemptGeneration,
providerAttemptId,
providerAttemptIndex,
status: status as PromptBridgeFinalizationInput['status'],
target: { targetRef, provider, model, credentialSlot },
reason,
...(usage ? { usage } : {}),
}
}
// ─── promptBridge input validation (plan §2.7) ───────────────────────────
interface ParsedPromptBridgeBody {
contractVersion?: number
callerRef: string
bootstrapProvider: string
bootstrapModel: string
model?: string
provider?: string
targetRef?: string
modelPolicyRef?: string
purpose: string
idempotencyKey: string
messages: Array<{ role: string; content: string }>
metadata?: Record<string, unknown>
correlationId?: string
}
function parsePromptBridgeBody(
body: Record<string, unknown>,
res: Response,
options: {
requireContractVersion?: boolean
requireBootstrapBinding?: boolean
} = {}
): ParsedPromptBridgeBody | null {
const callerRef = validateCallerRef(body.callerRef, res)
if (!callerRef) return null
const contractVersion =
body.contractVersion === undefined
? undefined
: Number.isInteger(body.contractVersion)
? Number(body.contractVersion)
: 0
if (
(options.requireContractVersion &&
contractVersion !== PLUGIN_WORKLOAD_SDK_PROMPT_BRIDGE_CONTRACT_VERSION) ||
(!options.requireContractVersion &&
contractVersion !== undefined &&
contractVersion !== PLUGIN_WORKLOAD_SDK_PROMPT_BRIDGE_CONTRACT_VERSION)
) {
res.status(409).json({
error: 'protocol_mismatch',
message: `promptBridge contractVersion ${PLUGIN_WORKLOAD_SDK_PROMPT_BRIDGE_CONTRACT_VERSION} is required`,
retryable: true,
})
return null
}
// These fields are supplied only by the recipe-bound mcp-host. They carry
// the public provider/model identity from spec.agent, never credentials.
const bootstrapProvider =
typeof body.bootstrapProvider === 'string' ? body.bootstrapProvider.trim() : ''
const bootstrapModel = typeof body.bootstrapModel === 'string' ? body.bootstrapModel.trim() : ''
if (options.requireBootstrapBinding && (!bootstrapProvider || !bootstrapModel)) {
res.status(400).json({ error: 'bootstrap_binding_required' })
return null
}
const idempotencyKey = validateIdempotencyKey(body.idempotencyKey, res)
if (!idempotencyKey) return null
if (typeof body.purpose !== 'string' || !PURPOSE_SET.has(body.purpose)) {
res.status(400).json({ error: 'invalid_purpose' })
return null
}
if (!Array.isArray(body.messages) || body.messages.length === 0) {
res.status(400).json({ error: 'messages must be a non-empty array' })
return null
}
let totalContentBytes = 0
const messages: Array<{ role: string; content: string }> = []
for (const entry of body.messages) {
if (
!isPlainObject(entry) ||
typeof entry.role !== 'string' ||
!['system', 'user', 'assistant'].includes(entry.role) ||
typeof entry.content !== 'string'
) {
res.status(400).json({ error: 'messages entries must be { role, content }' })
return null
}
totalContentBytes += Buffer.byteLength(entry.content, 'utf8')
messages.push({ role: entry.role, content: entry.content })
}
if (totalContentBytes > DEFAULT_MAX_REQUEST_CONTENT_BYTES) {
res.status(413).json({ error: 'payload_too_large', retryable: false })
return null
}
// Attachments are not part of the promptBridge JSON contract.
if (Array.isArray(body.attachments) && body.attachments.length > 0) {
res.status(400).json({ error: 'attachments_not_supported' })
return null
}
let metadata: Record<string, unknown> | undefined
if (body.metadata !== undefined) {
if (!isPlainObject(body.metadata)) {
res.status(400).json({ error: 'metadata must be an object' })
return null
}
try {
if (Buffer.byteLength(JSON.stringify(body.metadata), 'utf8') > 16 * 1024) {
res.status(413).json({ error: 'metadata_too_large', retryable: false })
return null
}
metadata = body.metadata as Record<string, unknown>
} catch {
res.status(400).json({ error: 'metadata must be JSON-serializable' })
return null
}
}
const model = typeof body.model === 'string' && body.model.trim() ? body.model.trim() : undefined
const provider =
typeof body.provider === 'string' && body.provider.trim() ? body.provider.trim() : undefined
const targetRef =
typeof body.targetRef === 'string' && body.targetRef.trim() ? body.targetRef.trim() : undefined
if (targetRef && targetRef.length > MAX_TARGET_REF_LENGTH) {
res.status(400).json({ error: `targetRef exceeds maximum length of ${MAX_TARGET_REF_LENGTH}` })
return null
}
if (provider && !model && !targetRef) {
res.status(400).json({ error: 'provider requires model or targetRef' })
return null
}
const modelPolicyRef =
typeof body.modelPolicyRef === 'string' && body.modelPolicyRef.trim()
? body.modelPolicyRef.trim()
: undefined
const correlationId =
typeof body.correlationId === 'string' && body.correlationId.trim()
? body.correlationId.trim().slice(0, 256)
: undefined
return {
...(contractVersion !== undefined ? { contractVersion } : {}),
callerRef,
bootstrapProvider,
bootstrapModel,
model,
provider,
targetRef,
modelPolicyRef,
purpose: body.purpose,
idempotencyKey,
messages,
...(metadata ? { metadata } : {}),
correlationId,
}
}
// ─── clientNotifications input validation (plan §2.7) ────────────────────
interface ParsedClientNotificationBody {
callerRef: string
eventType: string
targetRef?: string
userRef?: string
idempotencyKey: string
notification: {
title: string
body: string
data?: Record<string, unknown>
actionRef?: { type: string; id: string; urlRef?: string }
deliveryPolicyRef?: string
correlationId?: string
}
}
function validateOpaqueRef(
value: string,
field: string,
maxLength: number,
res: Response
): boolean {
if (value.length > maxLength) {
res.status(400).json({ error: `${field} exceeds maximum length of ${maxLength}` })
return false
}
if (EMAIL_LIKE_RE.test(value) || PHONE_LIKE_RE.test(value)) {
res.status(400).json({
error: `${field} must be an opaque reference, not a raw channel address`,
})
return false
}
return true
}
function parseClientNotificationBody(
body: Record<string, unknown>,
res: Response
): ParsedClientNotificationBody | null {
const callerRef = validateCallerRef(body.callerRef, res)
if (!callerRef) return null
const idempotencyKey = validateIdempotencyKey(body.idempotencyKey, res)
if (!idempotencyKey) return null
if (typeof body.eventType !== 'string' || !body.eventType.trim()) {
res.status(400).json({ error: 'eventType is required' })
return null
}
const eventType = body.eventType.trim()
if (eventType.length > 128) {
res.status(400).json({ error: 'eventType exceeds maximum length of 128' })
return null
}
const target = isPlainObject(body.target) ? body.target : undefined
const targetRef =
target && typeof target.targetRef === 'string' && target.targetRef.trim()
? target.targetRef.trim()
: undefined
const userRef =
typeof body.userRef === 'string' && body.userRef.trim() ? body.userRef.trim() : undefined
if ((targetRef === undefined) === (userRef === undefined)) {
res.status(400).json({ error: 'exactly one of target.targetRef or userRef is required' })
return null
}
if (targetRef && !validateOpaqueRef(targetRef, 'target.targetRef', MAX_TARGET_REF_LENGTH, res)) {
return null
}
if (userRef && !validateOpaqueRef(userRef, 'userRef', MAX_USER_REF_LENGTH, res)) {
return null
}
if (!isPlainObject(body.notification)) {
res.status(400).json({ error: 'notification is required' })
return null
}
const notification = body.notification
if (typeof notification.title !== 'string' || !notification.title.trim()) {
res.status(400).json({ error: 'notification.title is required' })
return null
}
if (Buffer.byteLength(notification.title, 'utf8') > DEFAULT_MAX_TITLE_BYTES) {
res.status(413).json({ error: 'payload_too_large', retryable: false })
return null
}
if (typeof notification.body !== 'string') {
res.status(400).json({ error: 'notification.body is required' })
return null
}
if (Buffer.byteLength(notification.body, 'utf8') > DEFAULT_MAX_BODY_BYTES) {
res.status(413).json({ error: 'payload_too_large', retryable: false })
return null
}
const actionRefRaw = isPlainObject(notification.actionRef) ? notification.actionRef : undefined
if (notification.actionRef !== undefined && !actionRefRaw) {
res.status(400).json({ error: 'notification.actionRef must be { type, id, urlRef? }' })
return null
}
// A present actionRef object MUST carry string `type` and `id`. Without this
// guard, a malformed object (e.g. { type: 42, id: null }) would be silently
// coerced to `undefined` below and the request would succeed while dropping
// the actionRef with no feedback to the caller.
if (
actionRefRaw &&
(typeof actionRefRaw.type !== 'string' || typeof actionRefRaw.id !== 'string')
) {
res.status(400).json({ error: 'notification.actionRef must have string type and id' })
return null
}
const actionRef =
actionRefRaw && typeof actionRefRaw.type === 'string' && typeof actionRefRaw.id === 'string'
? {
type: actionRefRaw.type,
id: actionRefRaw.id,
...(typeof actionRefRaw.urlRef === 'string' ? { urlRef: actionRefRaw.urlRef } : {}),
}
: undefined
return {
callerRef,
eventType,
targetRef,
userRef,
idempotencyKey,
notification: {
title: notification.title,
body: notification.body,
data: isPlainObject(notification.data) ? notification.data : undefined,
actionRef,
deliveryPolicyRef:
typeof notification.deliveryPolicyRef === 'string'
? notification.deliveryPolicyRef
: undefined,
correlationId:
typeof notification.correlationId === 'string'
? notification.correlationId.slice(0, 256)
: undefined,
},
}
}
// ─── Router ──────────────────────────────────────────────────────────────
async function handlePromptBridgeAuthorization(
req: Request,
res: Response,
options: {
requireContractVersion: boolean
requireBootstrapBinding: boolean
}
): Promise<void> {
const claims = req.mcpHostJwt!
const body = isPlainObject(req.body) ? req.body : {}
if (!checkRecipeBinding(body, claims, res)) return
const parsed = parsePromptBridgeBody(body, res, options)
if (!parsed) return
const result = await authorizePromptBridge({
claims,
callerRef: parsed.callerRef,
bootstrapProvider: parsed.bootstrapProvider,
bootstrapModel: parsed.bootstrapModel,
model: parsed.model,
provider: parsed.provider,
targetRef: parsed.targetRef,
modelPolicyRef: parsed.modelPolicyRef,
purpose: parsed.purpose,
idempotencyKey: parsed.idempotencyKey,
payload: {
messages: parsed.messages,
model: parsed.model ?? null,
provider: parsed.provider ?? null,
targetRef: parsed.targetRef ?? null,
modelPolicyRef: parsed.modelPolicyRef ?? null,
purpose: parsed.purpose,
...(parsed.metadata ? { metadata: parsed.metadata } : {}),
},
correlationId: parsed.correlationId,
})
if (!result.ok) {
sendAuthzError(res, result)
return
}
res.status(result.value.replay ? 200 : 201).json({
...(options.requireContractVersion
? { contractVersion: PLUGIN_WORKLOAD_SDK_PROMPT_BRIDGE_CONTRACT_VERSION }
: {}),
invocationId: result.value.invocationId,
replay: result.value.replay,
providerCallRequired: result.value.providerCallRequired,
status: result.value.status,
model: result.value.model,
modelPolicy: result.value.modelPolicy,
selectedTarget: result.value.selectedTarget,
authorizedTargets: result.value.authorizedTargets,
attemptGeneration: result.value.attemptGeneration,
policyRevision: result.value.policyRevision,
policyHash: result.value.policyHash,
maxOutputTokens: result.value.maxOutputTokens,
})
}
export function createMcpHostPluginWorkloadSdkRoutes(): Router {
const router = Router()
// This router contains no unauthenticated endpoint. Apply the boundary
// protections once, scoped to the SDK prefix, so newly added SDK routes
// cannot accidentally omit either the pre-auth flood guard or the
// recipe-scoped PG limiter (the outer app bounds JSON bodies).
router.use(
'/mcp-host/plugin-workload-sdk',
// Invalid or missing credentials stay on the anonymous source-IP gate.
// Verified Host principals use a separate pre-auth allowance, then the
// recipe-scoped request bucket after authentication. The verification
// budget runs first because both pre-auth gates verify to pick a bucket.
createPluginWorkloadSdkVerificationBudgetRateLimit(),
createPluginWorkloadSdkAnonymousPreauthRateLimit(),
createPluginWorkloadSdkAuthenticatedPreauthRateLimit(),
requireMcpHostJwt,
requirePluginWorkloadSdkScope,
createPluginWorkloadSdkRequestRateLimit()
)
router.post(
// JIT fallback-ticket contract for mcp-host:
// - call only after the prior provider attempt has failed;
// - provide invocationId + next targetRef, never a credential identity;
// - redeem the returned ticket once, immediately before WRC reads the slot.
// The server derives caller and allowed suffix from the persisted
// invocation, verifies current policy, and emits a new one-shot jti.
'/mcp-host/plugin-workload-sdk/prompt-bridge/credential-ticket',
pluginWorkloadSdkCredentialRateLimit,
asyncHandler(async (req, res) => {
const claims = req.mcpHostJwt!
const body = isPlainObject(req.body) ? req.body : {}
if (!checkRecipeBinding(body, claims, res)) return
const invocationId = typeof body.invocationId === 'string' ? body.invocationId.trim() : ''
const targetRef = typeof body.targetRef === 'string' ? body.targetRef.trim() : ''
const attemptGeneration = Number.isInteger(body.attemptGeneration)
? Number(body.attemptGeneration)
: 0
if (
!invocationId ||
!targetRef ||
targetRef.length > MAX_TARGET_REF_LENGTH ||
attemptGeneration < 1
) {
res
.status(400)
.json({ error: 'invocationId, targetRef and attemptGeneration are required' })
return
}
const result = await reissuePromptBridgeCredentialTicket({
claims,
invocationId,
targetRef,
attemptGeneration,
})
if (!result.ok) {
sendAuthzError(res, result)
return
}
res.status(201).json(result.value)
})
)
// v2 is the only supported target-aware/JIT contract. There is no runtime
// compatibility lane: old hosts must fail clearly and be upgraded rather
// than bypassing target policy and per-attempt credential fencing.
router.post(
'/mcp-host/plugin-workload-sdk/prompt-bridge/v2',
asyncHandler(async (req, res) =>
handlePromptBridgeAuthorization(req, res, {
requireContractVersion: true,
requireBootstrapBinding: true,
})
)
)
router.get(
'/mcp-host/plugin-workload-sdk/capabilities',
asyncHandler(async (_req, res) => {
const claims = _req.mcpHostJwt!
const grant = await findGrant(claims.recipeNamespace, claims.recipeName, 'promptBridge')
const clientNotificationsGrant = await findGrant(
claims.recipeNamespace,
claims.recipeName,
'clientNotifications'
)
const v2Ready = Boolean(
grant &&
grant.policyState === 'active' &&
grant.policyRevision >= 1 &&
grant.policyReviewProvenancePresent !== false &&
grant.promptTargets.length > 0 &&
grant.defaultTargetRef !== null &&
grant.promptTargets[0]?.targetRef === grant.defaultTargetRef
)
const clientNotificationsReady = Boolean(
clientNotificationsGrant &&
isClientNotificationsPolicyReady(clientNotificationsGrant) &&
(await hasUsableClientNotificationRecipients(clientNotificationsGrant))
)
const alignedPrimary =
grant &&
grant.promptTargets[0] &&
grant.defaultTargetRef !== null &&
grant.promptTargets[0].targetRef === grant.defaultTargetRef
? grant.promptTargets[0]
: null
const reservationOnlyOauthBroker = Boolean(
alignedPrimary &&
isLlmProviderId(alignedPrimary.provider) &&
PROVIDER_AUTH_MODE[alignedPrimary.provider] === 'oauth-broker'
)
// Old mcp-host/WRC require capabilities.contractVersion === 2. Advertise
// 3 only for oauth-broker defaults so those binaries fail at reconcile
// instead of Validated-then-empty-ticket. Authorize/grant wire stays 2.
//
// #533 acceptance criterion 2 ties the Codex binding to the catalog and
// credential revisions, but those live on the connection row and never
// reached the host, so `codexBindingReady` could not compare them. They
// are advertised additively, gated by `codexBindingRevisions`, because
// the two rollout directions need opposite defaults: a host that
// predates the fields ignores them, and a host that postdates them must
// learn whether THIS API can send them at all — otherwise it would fail
// closed against an older control-api on a field that peer cannot emit,
// which is the #540 failure shape. Omitting the comparison is a
// readiness gap, never an unfenced spend: llmProviderAttemptAuthorizer
// and llmProviderAttemptRedemption already reject a stale revision.
//
// `codexBindingRevisions` is a STATIC capability of this binary —
// "I know how to publish the revisions" — not a statement about any one
// connection. Emitting it only alongside the numbers made a revoked or
// missing connection look like an older control-api, so the host skipped
// the freshness check exactly when the binding could not possibly be
// backed. With the flag static, absent numbers take the host's
// partial-deploy branch and fail closed, which is correct: a revoked
// connection can never back a live binding.
const grokDefault = alignedPrimary?.provider === 'grok-subscription'
const brokerConnection =
reservationOnlyOauthBroker && typeof alignedPrimary?.connectionRef === 'string'
? grokDefault
? await getSafeGrokSubscriptionConnection(pool, alignedPrimary.connectionRef)
: await getSafeCodexSubscriptionConnection(pool, alignedPrimary.connectionRef)
: null
res.status(200).json({
contractVersion: reservationOnlyOauthBroker
? 3
: PLUGIN_WORKLOAD_SDK_PROMPT_BRIDGE_CONTRACT_VERSION,
supportedContractVersions: [2, 3],
targetAwarePromptBridge: true,
attemptLedger: true,
credentialTickets: true,
policyState: grant?.policyState ?? 'missing',
policyRevision: grant?.policyRevision ?? 0,
policyHash: v2Ready && grant ? hashPromptTargetPolicy(grant) : null,
defaultTargetRef: grant?.defaultTargetRef ?? null,
defaultProvider: alignedPrimary?.provider ?? null,
defaultModel: alignedPrimary?.model ?? null,
defaultConnectionRef: alignedPrimary?.connectionRef ?? null,
v2Ready,
...(reservationOnlyOauthBroker
? {
reservationOnlyOauthBroker: true,
// Static for both brokers: mcp-host gates the Grok revision
// comparison on this same flag, so no Grok-only twin is emitted.
codexBindingRevisions: true,
}
: {}),
...(brokerConnection
? {
defaultCatalogRevision: brokerConnection.catalogRevision,
defaultCredentialRevision: brokerConnection.credentialRevision,
}
: {}),
clientNotificationsPolicyState: clientNotificationsGrant?.policyState ?? 'missing',
clientNotificationsReady,
})
})
)
router.post(
'/mcp-host/plugin-workload-sdk/client-notification',
asyncHandler(async (req, res) => {
const claims = req.mcpHostJwt!
const body = isPlainObject(req.body) ? req.body : {}
if (!checkRecipeBinding(body, claims, res)) return
const parsed = parseClientNotificationBody(body, res)
if (!parsed) return
const authStartedAt = process.hrtime.bigint()
const result = await authorizeClientNotification({
claims,
callerRef: parsed.callerRef,
eventType: parsed.eventType,
targetRef: parsed.targetRef,
userRef: parsed.userRef,
idempotencyKey: parsed.idempotencyKey,
payload: {
eventType: parsed.eventType,
target: parsed.targetRef ?? null,
userRef: parsed.userRef ?? null,
notification: {
title: parsed.notification.title,
body: parsed.notification.body,
data: parsed.notification.data ?? null,
actionRef: parsed.notification.actionRef ?? null,
deliveryPolicyRef: parsed.notification.deliveryPolicyRef ?? null,
},
},
correlationId: parsed.notification.correlationId,
})
pluginWorkloadSdkNotificationAuthDurationSeconds.observe(
{ recipe: `${claims.recipeNamespace}/${claims.recipeName}` },
Number(process.hrtime.bigint() - authStartedAt) / 1e9
)
if (!result.ok) {
sendAuthzError(res, result)
return
}
// Plan §4.2: the authorized intent is already persisted in the audit
// trail; delivery enqueue is best-effort. If the Notification Service
// path is down the caller still sees 'accepted' and delivery retries
// ride on the queue once it recovers. Always attempt enqueue — even on
// idempotency replay — because dedupe_key ON CONFLICT DO NOTHING makes
// the insert safe and repairs a missing delivery row after cleanup.
try {
await enqueuePluginWorkloadSdkNotification(pool, {
notificationId: result.value.notificationId,
recipeNamespace: claims.recipeNamespace,
recipeName: claims.recipeName,
callerRef: parsed.callerRef,
eventType: parsed.eventType,
userRef: parsed.userRef,
targetRef: parsed.targetRef,
title: parsed.notification.title,
body: parsed.notification.body,
data: parsed.notification.data,
actionRef: parsed.notification.actionRef,
deliveryPolicyRef: parsed.notification.deliveryPolicyRef,
})
} catch (err) {
req.log?.warn(
{ event: 'plugin_workload_sdk_notification_enqueue_failed', err },
'plugin workload sdk notification enqueue failed (intent stays audited)'
)
}
res.status(result.value.replay ? 200 : 201).json({
notificationId: result.value.notificationId,
replay: result.value.replay,
status: result.value.status,
eventType: parsed.eventType,
target: { targetRef: parsed.targetRef, userRef: parsed.userRef },
})
})
)
// Recipient listing (read-only): returns the clientNotifications grant's
// allowedUserRefs resolved to display labels so a recipe's sandbox UI can
// render a recipient picker from the authoritative source. POST carries the
// recipe binding in the body (same checkRecipeBinding contract as the send
// path); it consumes no quota and writes no audit row.
router.post(
'/mcp-host/plugin-workload-sdk/client-notification/recipients',
asyncHandler(async (req, res) => {
const claims = req.mcpHostJwt!
const body = isPlainObject(req.body) ? req.body : {}
if (!checkRecipeBinding(body, claims, res)) return
const callerRef = validateCallerRef(body.callerRef, res)
if (!callerRef) return
const result = await authorizeListRecipients({ claims, callerRef })
if (!result.ok) {
sendAuthzError(res, result)
return
}
const recipients = await resolveRecipientProfiles(result.value.allowedUserRefs)
res.status(200).json({ recipients })
})
)
// TOCTOU guard for cross-provider credential resolution. The mcp-host must
// re-check a short-lived signed target ticket immediately before reading its
// credential slot. This endpoint returns no target data and never redeems a
// secret; it only attests that the ticket still matches the current policy.
router.post(
'/mcp-host/plugin-workload-sdk/credential-ticket/introspect',
pluginWorkloadSdkCredentialRateLimit,
asyncHandler(async (req, res) => {
const claims = req.mcpHostJwt!
const body = isPlainObject(req.body) ? req.body : {}
const ticket = typeof body.credentialTicket === 'string' ? body.credentialTicket : ''
const invocationId = typeof body.invocationId === 'string' ? body.invocationId : ''
const targetRef = typeof body.targetRef === 'string' ? body.targetRef : ''
const providedAttemptGeneration = Number.isInteger(body.attemptGeneration)
? Number(body.attemptGeneration)
: null
const attemptGeneration = providedAttemptGeneration ?? 0
const providerAttemptId =
typeof body.providerAttemptId === 'string' ? body.providerAttemptId.trim() : ''
const providerAttemptIndex = Number.isInteger(body.providerAttemptIndex)
? Number(body.providerAttemptIndex)
: 0
const redeem = body.redeem === true
if (
!ticket ||
!invocationId ||
!targetRef ||
!providerAttemptId ||
attemptGeneration < 1 ||
providerAttemptIndex < 1
) {
res.status(400).json({
error:
'credentialTicket, invocationId, targetRef, providerAttemptId and attemptGeneration are required',
})
return
}
const ticketClaims = verifyPluginWorkloadSdkCredentialTicket(ticket)
if (
!ticketClaims ||
ticketClaims.recipeNamespace !== claims.recipeNamespace ||
ticketClaims.recipeName !== claims.recipeName ||
ticketClaims.sub !== `${claims.recipeNamespace}/${claims.recipeName}` ||
ticketClaims.invocationId !== invocationId ||
ticketClaims.targetRef !== targetRef ||
ticketClaims.attemptGeneration !== attemptGeneration ||
ticketClaims.providerAttemptId !== providerAttemptId ||
ticketClaims.providerAttemptIndex !== providerAttemptIndex
) {
res.status(403).json({ error: 'provider_policy_denied', retryable: false })
return
}
const invocation = await getInvocationById(invocationId)
if (
!invocation ||
invocation.recipeNamespace !== claims.recipeNamespace ||
invocation.recipeName !== claims.recipeName ||
invocation.method !== 'promptBridge' ||
invocation.status !== 'in_progress' ||
invocation.attemptGeneration !== attemptGeneration ||
invocation.authorizationDecision !== 'authorized' ||
!invocation.promptAuthorization ||
!invocation.promptAuthorization.authorizedTargetRefs.includes(targetRef) ||
invocation.promptAuthorization.policyRevision !== ticketClaims.policyRevision ||
invocation.promptAuthorization.policyHash !== ticketClaims.policyHash
) {
res.status(403).json({ error: 'provider_policy_denied', retryable: false })
return
}
const receipt = await getPluginWorkloadSdkAttemptReceipt(invocationId, attemptGeneration)
const providerAttempt = await getPluginWorkloadSdkProviderAttempt(providerAttemptId)
if (
!receipt ||
receipt.recipeNamespace !== claims.recipeNamespace ||
receipt.recipeName !== claims.recipeName ||
receipt.method !== 'promptBridge' ||
receipt.status !== 'in_progress' ||
receipt.attemptGeneration !== attemptGeneration ||
!providerAttempt ||
providerAttempt.invocationId !== invocationId ||
providerAttempt.attemptGeneration !== attemptGeneration ||
providerAttempt.targetRef !== targetRef ||
providerAttempt.status !== 'in_progress'
) {
res.status(403).json({ error: 'provider_policy_denied', retryable: false })
return
}
const grant = await findGrant(claims.recipeNamespace, claims.recipeName, 'promptBridge')
const target = grant?.promptTargets.find(candidate => candidate.targetRef === targetRef)
if (
!grant ||
grant.policyState !== 'active' ||
!target ||
grant.policyRevision !== ticketClaims.policyRevision ||
hashPromptTargetPolicy(grant) !== ticketClaims.policyHash ||
target.provider !== ticketClaims.provider ||
target.model !== ticketClaims.model ||
target.credentialSlot !== ticketClaims.credentialSlot
) {
res.status(403).json({ error: 'provider_policy_denied', retryable: false })
return
}
if (redeem) {
const redeemed = await redeemPluginWorkloadSdkCredentialTicketJti({
jti: ticketClaims.jti,
recipeNamespace: claims.recipeNamespace,
recipeName: claims.recipeName,
invocationId,
targetRef,
attemptGeneration,
providerAttemptId,
})
if (!redeemed) {
res.status(403).json({ error: 'provider_policy_denied', retryable: false })
return
}
}
res.status(200).json({ active: true })
})
)
// Invocation status reporting (plan §2.4 lifecycle): the mcp-host SDK
// server reports promptBridge outcomes so the audit trail tracks
// in_progress → complete | failed | provider_unavailable.
router.post(
'/mcp-host/plugin-workload-sdk/invocations/:id/status',
asyncHandler(async (req, res) => {
const claims = req.mcpHostJwt!
const body = isPlainObject(req.body) ? req.body : {}
if (!checkRecipeBinding(body, claims, res)) return
const status = typeof body.status === 'string' ? body.status : ''
const providedAttemptGeneration = Number.isInteger(body.attemptGeneration)
? Number(body.attemptGeneration)
: null
if (!['complete', 'failed', 'provider_unavailable'].includes(status)) {
res
.status(400)
.json({ error: 'status must be one of: complete, failed, provider_unavailable' })
return
}
const invocation = await getInvocationById(req.params.id)
if (!invocation) {
res.status(404).json({ error: 'invocation not found' })
return
}
// Cross-recipe isolation: 403 without leaking row data.
if (
invocation.recipeNamespace !== claims.recipeNamespace ||
invocation.recipeName !== claims.recipeName
) {
res.status(403).json({ error: 'binding_mismatch' })
return
}
const attemptGeneration = providedAttemptGeneration ?? invocation.attemptGeneration
if (providedAttemptGeneration === null) {
res.status(400).json({ error: 'attemptGeneration is required for contract v2' })
return
}
if (attemptGeneration < 1) {
res.status(400).json({ error: 'attemptGeneration is required' })
return
}
const updated = await markInvocationStatus(
invocation.id,
status as 'complete' | 'failed' | 'provider_unavailable',
{
recipeNamespace: claims.recipeNamespace,
recipeName: claims.recipeName,
expectedCurrentStatus: 'in_progress',
expectedAttemptGeneration: attemptGeneration,
}
)
if (!updated) {
res.status(409).json({ error: 'stale_attempt', retryable: false })
return
}
res.status(200).json({ id: invocation.id, status })
})
)
// Finalization is the SDK-only promptBridge accounting boundary. It binds
// the provider receipt, logical invocation, and exact/unknown spend outcome
// in one idempotent transaction; callers must not separately report status
// and usage for this lane.
router.post(
'/mcp-host/plugin-workload-sdk/invocations/:id/finalize',
asyncHandler(async (req, res) => {
const claims = req.mcpHostJwt!
const body = isPlainObject(req.body) ? req.body : {}
if (!checkRecipeBinding(body, claims, res)) return
const parsed = parsePromptBridgeFinalizationBody(body, claims, res)
if (!parsed) return
if (parsed.invocationId !== req.params.id) {
res.status(400).json({ error: 'invocation id does not match path' })
return
}
try {
const result = await finalizePromptBridge(parsed)
res.status(result.idempotent ? 200 : 201).json(result)
} catch (error) {
if (error instanceof PromptBridgeFinalizationError) {
const errorCode =
error.code === 'conflict'
? 'idempotency_conflict'
: error.code === 'ledger_pending' || error.code === 'stale_attempt'
? 'provider_unavailable'
: error.code === 'binding_mismatch'
? 'provider_policy_denied'
: error.code === 'not_found'
? 'invalid_request'
: error.code
res.status(error.httpStatus).json({
error: errorCode,
message: error.message,
retryable: error.retryable === true,
...(error.code === 'ledger_pending' ? { reason: 'provider_unavailable' } : {}),
})
return
}
throw error
}
})
)
router.post(
'/mcp-host/plugin-workload-sdk/provider-attempts/:id/status',
asyncHandler(async (req, res) => {
const claims = req.mcpHostJwt!
const body = isPlainObject(req.body) ? req.body : {}
if (!checkRecipeBinding(body, claims, res)) return
const invocationId = typeof body.invocationId === 'string' ? body.invocationId.trim() : ''
const attemptGeneration = Number.isInteger(body.attemptGeneration)
? Number(body.attemptGeneration)
: 0
const providerAttemptIndex = Number.isInteger(body.providerAttemptIndex)
? Number(body.providerAttemptIndex)
: 0
const status = body.status
if (
!invocationId ||
attemptGeneration < 1 ||
providerAttemptIndex < 1 ||
!['complete', 'failed', 'provider_unavailable', 'skipped'].includes(String(status))
) {
res.status(400).json({
error: 'invocationId, attemptGeneration, providerAttemptIndex and status are required',
})
return
}
const attempt = await getPluginWorkloadSdkProviderAttempt(req.params.id)
if (
!attempt ||
attempt.invocationId !== invocationId ||
attempt.recipeNamespace !== claims.recipeNamespace ||
attempt.recipeName !== claims.recipeName ||
attempt.attemptGeneration !== attemptGeneration ||
attempt.attemptIndex !== providerAttemptIndex
) {
res.status(403).json({ error: 'provider_policy_denied', retryable: false })
return
}
const updated = await markPluginWorkloadSdkProviderAttemptStatus({
id: attempt.id,
invocationId,
recipeNamespace: claims.recipeNamespace,
recipeName: claims.recipeName,
attemptGeneration,
status: status as 'complete' | 'failed' | 'provider_unavailable' | 'skipped',
})
if (!updated) {
res.status(409).json({ error: 'stale_attempt', retryable: false })
return
}
res.status(200).json({ id: attempt.id, status })
})
)
router.get(
'/mcp-host/plugin-workload-sdk/invocations/:recipeRef',
asyncHandler(async (req, res) => {
const claims = req.mcpHostJwt!
// Cross-recipe isolation: the path recipeRef must match the JWT's
// recipe binding (same 403 contract as approval /:id/status). Accepts
// the bare recipeName or the fully-qualified '<namespace>/<name>'
// form (URL-encoded slash) so callers can pin both binding halves.
const recipeRef = req.params.recipeRef
const qualifiedRef = `${claims.recipeNamespace}/${claims.recipeName}`
if (recipeRef !== claims.recipeName && recipeRef !== qualifiedRef) {
res.status(403).json({ error: 'binding_mismatch' })
return
}
const items = await listInvocations({
recipeNamespace: claims.recipeNamespace,
recipeName: claims.recipeName,
limit: 100,
})
res.status(200).json({ items })
})
)
return router
}