Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

7.5 KB
Raw Blame
/**
 * Signed-state token codec — a thin wrapper around `jose` that stamps an
 * HMAC-SHA256 JWT-compact-format token (`header.payload.signature`)
 * binding a `(user, purpose, payload)` triple plus expiry + nonce. Used
 * by the typed-confirm two-tool paradigm to carry confirmation state
 * through the LLM between a `prepare-X` and `execute-X` call.
 *
 * Claims:
 *   - `sub`     — user identity (mapped to JWT `sub`); binds the token to the authenticated principal
 *   - `purpose` — what the token is for, e.g. tool name (mapped to JWT `aud`); guards cross-purpose replay
 *   - `nonce`   — 128 random bits (mapped to JWT `jti`); the key for the single-use ledger
 *   - `iat/exp` — unix seconds; expiry caps the replay window
 *   - `payload` — caller-supplied opaque data, kept as a custom claim
 *
 * The token header is `{alg: 'HS256', typ: 'MCP-SIGNED-STATE'}` — `jose`
 * validates both at decode time so a token signed for a different purpose
 * or a different system (`typ`) can't be coerced into ours.
 *
 * One key: `MCP_SIGNED_STATE_KEY`. No encryption — confidentiality of
 * `payload` is the caller's responsibility.
 */

import { jwtVerify, SignJWT } from 'jose'
import { JOSEError, JWSSignatureVerificationFailed, JWTClaimValidationFailed, JWTExpired } from 'jose/errors'
import { randomBytes } from 'node:crypto'

import { DEFAULT_STATE_TTL_SECONDS, SIGNING_KEY_ENV_VAR, SIGNING_KEY_MIN_BYTES } from './constants'
import {
    SignedStateError,
    SignedStateExpired,
    SignedStateMalformed,
    SignedStatePurposeMismatch,
    SignedStateSignatureInvalid,
    SignedStateUserMismatch,
} from './errors'

const JWT_TYP = 'MCP-SIGNED-STATE'

export interface SignedStateClaims {
    sub: string
    purpose: string
    iat: number
    exp: number
    nonce: string
    payload: unknown
}

export interface SignedStateCodecOptions {
    /** TTL applied at encode time; default `DEFAULT_STATE_TTL_SECONDS`. */
    ttlSeconds?: number
    /** Override `Date.now()` for tests. */
    now?: () => number
    /** Override the entropy source for tests. */
    randomNonce?: () => string
}

export class SignedStateCodec {
    private readonly key: Uint8Array
    /** TTL stamped on tokens at encode time. Public so callers can surface the window in user-facing copy. */
    readonly ttlSeconds: number
    private readonly now: () => number
    private readonly randomNonce: () => string

    constructor(key: Buffer | Uint8Array, options: SignedStateCodecOptions = {}) {
        this.key = key instanceof Uint8Array ? key : new Uint8Array(key)
        this.ttlSeconds = options.ttlSeconds ?? DEFAULT_STATE_TTL_SECONDS
        this.now = options.now ?? (() => Date.now())
        this.randomNonce = options.randomNonce ?? (() => randomBytes(16).toString('hex'))
    }

    /** Encode a fresh signed-state token bound to `(sub, purpose, payload)`. */
    async encode(input: {
        sub: string
        purpose: string
        payload: unknown
    }): Promise<{ token: string; claims: SignedStateClaims }> {
        const iat = Math.floor(this.now() / 1000)
        const exp = iat + this.ttlSeconds
        const nonce = this.randomNonce()
        const token = await new SignJWT({ payload: input.payload })
            .setProtectedHeader({ alg: 'HS256', typ: JWT_TYP })
            .setSubject(input.sub)
            .setAudience(input.purpose)
            .setIssuedAt(iat)
            .setExpirationTime(exp)
            .setJti(nonce)
            .sign(this.key)
        return {
            token,
            claims: { sub: input.sub, purpose: input.purpose, iat, exp, nonce, payload: input.payload },
        }
    }

    /**
     * Decode + verify an inbound token against the currently authenticated
     * (user, purpose). Throws `SignedStateError` subclasses for any
     * failure; the caller maps these to the appropriate response shape.
     */
    async decode(token: string, expectedSub: string, expectedPurpose: string): Promise<SignedStateClaims> {
        try {
            const { payload } = await jwtVerify(token, this.key, {
                algorithms: ['HS256'],
                typ: JWT_TYP,
                subject: expectedSub,
                audience: expectedPurpose,
                clockTolerance: 0,
                currentDate: new Date(this.now()),
            })
            // jose has already validated sub/aud/exp/typ; the cast is safe.
            return {
                sub: payload.sub as string,
                purpose: payload.aud as string,
                iat: payload.iat as number,
                exp: payload.exp as number,
                nonce: payload.jti as string,
                payload: (payload as { payload: unknown }).payload,
            }
        } catch (err) {
            throw mapJoseError(err)
        }
    }

    /**
     * Seconds until `claims.exp` according to the codec's clock —
     * guaranteed to be at least 1. Used by callers (e.g. the typed-confirm
     * nonce ledger) that need to size a TTL off the same time source the
     * codec used to stamp the token; reading the wall clock here would
     * skew under test injections or clock drift between the signer and
     * the consumer.
     */
    secondsUntilExpiry(claims: SignedStateClaims): number {
        const nowSeconds = Math.floor(this.now() / 1000)
        return Math.max(1, claims.exp - nowSeconds)
    }
}

/**
 * Load the signing key from the environment. Throws unconditionally if
 * the key is missing or under `SIGNING_KEY_MIN_BYTES`. No NODE_ENV gate
 * and no dev fallback — a deterministic placeholder would be publicly
 * known via this source file, so a leaked key would let any
 * authenticated user (or prompt-injected model) forge tokens for any
 * other user. Callers that want to boot without the paradigm available
 * should catch and continue (see `createApp` for the canonical pattern).
 */
export function loadSigningKeyFromEnv(env: NodeJS.ProcessEnv = process.env): Buffer {
    const raw = env[SIGNING_KEY_ENV_VAR] ?? ''
    const key = Buffer.from(raw, 'utf8')
    if (key.length < SIGNING_KEY_MIN_BYTES) {
        throw new Error(`${SIGNING_KEY_ENV_VAR} must be set to at least ${SIGNING_KEY_MIN_BYTES} bytes`)
    }
    return key
}

/**
 * Map jose's exception hierarchy onto our typed `SignedStateError`
 * subclasses. The runtime catches by class to drive metric labels and
 * user-facing refusal messages, so we want a stable, semantic mapping
 * rather than leaking jose's internal types upward.
 *
 * The `JWTClaimValidationFailed.claim` field tells us which standard
 * claim mismatched; we map `sub` and `aud` to our user/purpose flavors.
 * Anything else (malformed token, bad header) collapses to `Malformed`.
 */
function mapJoseError(err: unknown): SignedStateError {
    const message = err instanceof Error ? err.message : String(err)
    if (err instanceof JWTExpired) {
        return new SignedStateExpired(message)
    }
    if (err instanceof JWTClaimValidationFailed) {
        if (err.claim === 'sub') {
            return new SignedStateUserMismatch(message)
        }
        if (err.claim === 'aud') {
            return new SignedStatePurposeMismatch(message)
        }
        return new SignedStateMalformed(message)
    }
    if (err instanceof JWSSignatureVerificationFailed) {
        return new SignedStateSignatureInvalid(message)
    }
    if (err instanceof JOSEError) {
        return new SignedStateMalformed(message)
    }
    // Non-jose error: shouldn't happen in normal flow; surface as malformed
    // rather than swallowing or re-throwing an unknown type upward.
    return new SignedStateMalformed(message)
}