Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto'
/**
* State binding for an OAuth callback. The state value carried in the
* provider redirect chain is HMAC-signed by control-api at authorize-URL
* issuance, then re-verified on the callback. The signed binding glues the
* callback to a specific subject + (user, oauthClientId) — a malicious caller
* cannot replay another subject's state and claim the resulting tokens.
*
* The subject is one of two kinds:
* - a WorkflowRecipe (the historical embed/admin Connect flow), OR
* - an OAuth McpServer (U5, reactive consent for mcp-servers).
*
* The recipe subject wire format is FROZEN: a recipe state carries NO
* `subjectKind` discriminator and NO mcp fields, so an existing recipe state
* serializes / signs byte-for-byte identically to before U5. The mcp subject is
* strictly additive — it carries `subjectKind:'mcp'` + `mcpServerName`. Anything
* that is neither an unmarked recipe nor a well-formed mcp subject fails closed
* (see {@link decodePayload}): a state marked `mcp` with a missing
* `mcpServerName`, or an unrecognized `subjectKind`, is rejected rather than
* silently reinterpreted as a recipe.
*
* Spec §9.9 / Decision 20 (recipe) · §U5 (mcp).
*/
/** Fields common to every subject. */
interface OAuthStateCommonClaims {
userId: string
oauthClientId: string
/**
* `user` — embed/mcp Connect flow, grant owned by `userId` (or, for a
* context-identity mcp-server, bootstrapped by `userId` — resolved on the
* callback from the server's authoritative `spec.contextRef`).
* `service` — admin "connect for the recipe" flow (Path B). `userId` is the
* initiating admin, recorded for audit only and NOT written to the grant.
*/
grantKind: 'user' | 'service'
/** True when the user opted into background (offline) use of this grant. */
background: boolean
/** Unix seconds when the state value becomes invalid. */
expiresAt: number
/** Random nonce so identical bindings produce distinct state strings. */
nonce: string
}
/**
* Recipe subject — the FROZEN legacy shape. No `subjectKind` field is present on
* the wire; its absence IS the discriminator.
*/
export interface OAuthRecipeStateClaims extends OAuthStateCommonClaims {
subjectKind?: undefined
recipeNamespace: string
recipeName: string
}
/** OAuth McpServer subject (U5) — additive, `subjectKind:'mcp'`. */
export interface OAuthMcpStateClaims extends OAuthStateCommonClaims {
subjectKind: 'mcp'
mcpServerName: string
}
export type OAuthStateClaims = OAuthRecipeStateClaims | OAuthMcpStateClaims
const STATE_VERSION = 'v1'
const STATE_TTL_SECONDS = 600 // 10 min — covers slow user OAuth flow but no longer
const NONCE_BYTES = 16
/**
* The (recipe, user, client) tuple the callback re-asserts against the
* URL-path-derived and cookie/peek-derived values. `grantKind` is deliberately
* NOT part of the binding — it is a property of the signed state itself, with
* no independent source to check it against.
*
* Only the recipe subject carries an external binding to re-check; the mcp
* subject's identity is recovered from the unforgeable signed claims (there is
* no recipe (ns, name) in the mcp callback path).
*/
export interface OAuthStateBinding {
recipeNamespace: string
recipeName: string
userId: string
oauthClientId: string
}
export type SignStateInput =
| {
/** Recipe subject (default). Omit `subjectKind` or pass `'recipe'`. */
subjectKind?: 'recipe'
recipeNamespace: string
recipeName: string
userId: string
oauthClientId: string
grantKind: 'user' | 'service'
background: boolean
}
| {
/** OAuth McpServer subject (U5). */
subjectKind: 'mcp'
mcpServerName: string
userId: string
oauthClientId: string
grantKind: 'user' | 'service'
background: boolean
}
/**
* Sign a fresh state value. Caller embeds the returned string in the
* provider authorize URL's `state` parameter.
*/
export function signOAuthState(secret: string, input: SignStateInput): string {
if (secret.length < 32) {
throw new Error('signOAuthState: secret must be at least 32 characters')
}
const nonce = randomBytes(NONCE_BYTES).toString('base64url')
const expiresAt = Math.floor(Date.now() / 1000) + STATE_TTL_SECONDS
let claims: OAuthStateClaims
if (input.subjectKind === 'mcp') {
// Additive mcp subject — carries the discriminator + mcpServerName.
claims = {
subjectKind: 'mcp',
mcpServerName: input.mcpServerName,
userId: input.userId,
oauthClientId: input.oauthClientId,
grantKind: input.grantKind,
background: input.background,
expiresAt,
nonce,
}
} else {
// FROZEN recipe subject — this object literal (field set + order) MUST stay
// byte-for-byte identical to the pre-U5 shape. No `subjectKind`, no mcp
// fields. The golden test in oauth.state.test.ts pins this.
claims = {
recipeNamespace: input.recipeNamespace,
recipeName: input.recipeName,
userId: input.userId,
oauthClientId: input.oauthClientId,
grantKind: input.grantKind,
background: input.background,
expiresAt,
nonce,
}
}
const payload = encodePayload(claims)
const signature = computeSignature(secret, payload)
return `${STATE_VERSION}.${payload}.${signature}`
}
export type VerifyOAuthStateResult =
| { kind: 'ok'; claims: OAuthStateClaims }
| { kind: 'invalid_format' }
| { kind: 'invalid_version' }
| { kind: 'invalid_signature' }
| { kind: 'expired' }
| { kind: 'binding_mismatch'; reason: string }
/**
* Verify a state value's version, signature, and expiry, returning the parsed
* claims on success. Unlike {@link verifyOAuthState}, this asserts NO external
* binding — use it when the callback URL no longer carries the
* (recipeNamespace, recipeName) in its path and the subject identity is
* recovered from the signed claims instead. That is safe because the HMAC
* signature makes the payload unforgeable. Callers that still hold an
* out-of-band value (e.g. the oauthClientId in the callback path) SHOULD
* cross-check it against the returned claims for defence in depth.
*/
export function verifyOAuthStateSignature(secret: string, state: string): VerifyOAuthStateResult {
const parts = state.split('.')
if (parts.length !== 3) return { kind: 'invalid_format' }
const [version, payload, providedSignature] = parts
if (version !== STATE_VERSION) return { kind: 'invalid_version' }
const expectedSignature = computeSignature(secret, payload)
if (!constantTimeEqualString(expectedSignature, providedSignature)) {
return { kind: 'invalid_signature' }
}
let claims: OAuthStateClaims
try {
claims = decodePayload(payload)
} catch {
return { kind: 'invalid_format' }
}
if (claims.expiresAt <= Math.floor(Date.now() / 1000)) {
return { kind: 'expired' }
}
return { kind: 'ok', claims }
}
/**
* Verify a state value supplied by the provider redirect. On success returns
* the parsed claims; on failure returns a discriminated error variant.
*
* The caller MUST also assert binding to the URL-path-derived
* (recipeNamespace, recipeName, oauthClientId) and to the cookie-derived
* userId — pass them via `expected` for an inline binding check.
*
* This binding check is RECIPE-ONLY: an mcp-subject state carries no recipe
* (ns, name) to bind against, so it fails closed here (`binding_mismatch`).
* The mcp callback path uses {@link verifyOAuthStateSignature} + a claims-side
* cross-check instead.
*/
export function verifyOAuthState(
secret: string,
state: string,
expected: OAuthStateBinding
): VerifyOAuthStateResult {
const verified = verifyOAuthStateSignature(secret, state)
if (verified.kind !== 'ok') return verified
const { claims } = verified
// Fail closed: this external-binding verifier only understands recipe
// subjects. An mcp subject has no recipe coordinates to re-assert.
if (claims.subjectKind === 'mcp') {
return { kind: 'binding_mismatch', reason: 'subjectKind' }
}
if (claims.recipeNamespace !== expected.recipeNamespace) {
return { kind: 'binding_mismatch', reason: 'recipeNamespace' }
}
if (claims.recipeName !== expected.recipeName) {
return { kind: 'binding_mismatch', reason: 'recipeName' }
}
if (claims.userId !== expected.userId) {
return { kind: 'binding_mismatch', reason: 'userId' }
}
if (claims.oauthClientId !== expected.oauthClientId) {
return { kind: 'binding_mismatch', reason: 'oauthClientId' }
}
return { kind: 'ok', claims }
}
function encodePayload(claims: OAuthStateClaims): string {
return Buffer.from(JSON.stringify(claims)).toString('base64url')
}
function decodePayload(payload: string): OAuthStateClaims {
const obj = JSON.parse(Buffer.from(payload, 'base64url').toString('utf8'))
if (
typeof obj !== 'object' ||
obj === null ||
typeof obj.userId !== 'string' ||
typeof obj.oauthClientId !== 'string' ||
(obj.grantKind !== 'user' && obj.grantKind !== 'service') ||
typeof obj.expiresAt !== 'number' ||
typeof obj.nonce !== 'string'
) {
throw new Error('decodePayload: malformed claims')
}
const common: OAuthStateCommonClaims = {
userId: obj.userId,
oauthClientId: obj.oauthClientId,
grantKind: obj.grantKind,
background: obj.background === true,
expiresAt: obj.expiresAt,
nonce: obj.nonce,
}
// mcp subject — requires a well-formed mcpServerName. Fail closed otherwise.
if (obj.subjectKind === 'mcp') {
if (typeof obj.mcpServerName !== 'string' || obj.mcpServerName.length === 0) {
throw new Error('decodePayload: malformed mcp claims')
}
return { subjectKind: 'mcp', mcpServerName: obj.mcpServerName, ...common }
}
// Recipe subject — the ONLY shape allowed to omit `subjectKind`. Requires the
// recipe coordinates.
if (obj.subjectKind === undefined) {
if (typeof obj.recipeNamespace !== 'string' || typeof obj.recipeName !== 'string') {
throw new Error('decodePayload: malformed recipe claims')
}
return { recipeNamespace: obj.recipeNamespace, recipeName: obj.recipeName, ...common }
}
// Any other `subjectKind` value is an unknown subject — fail closed rather
// than defaulting to recipe.
throw new Error('decodePayload: unknown subjectKind')
}
function computeSignature(secret: string, payload: string): string {
return createHmac('sha256', secret).update(`${STATE_VERSION}.${payload}`).digest('base64url')
}
function constantTimeEqualString(a: string, b: string): boolean {
const ab = Buffer.from(a, 'utf8')
const bb = Buffer.from(b, 'utf8')
if (ab.length !== bb.length) return false
return timingSafeEqual(ab, bb)
}