Skip to content

A desktop coding agent with free access to frontier models.

TypeScript
13.6 KB
Raw Blame
import type { EnterpriseMcpScenario } from "../contracts/scenario.js"
import type {
  MutationOperationSummary,
  RuntimeSnapshot,
  SafeTraceDetail,
  SafeTraceEvent,
  EnterpriseMcpMockEnvironment,
} from "../contracts/runtime.js"
import type { HandshakePhase } from "../contracts/phases.js"
import type { ProviderProfile } from "../contracts/profile.js"
import type { FaultDefinition } from "../contracts/fault.js"
import { sanitizeTraceDetails, sha256 } from "../observability/redaction.js"
import { deepFreeze } from "../immutability.js"

export interface OAuthClientRecord {
  readonly clientId: string
  readonly clientSecret: string
  readonly redirectUris: readonly string[]
  readonly tokenEndpointAuthMethod: "none" | "client_secret_post"
  readonly createdAt: number
  readonly expiresAt: number | null
}

export interface AuthorizationCodeRecord {
  readonly code: string
  readonly clientId: string
  readonly redirectUri: string
  readonly codeChallenge: string
  readonly resource: string
  readonly scopes: readonly string[]
  readonly expiresAt: number
}

export interface AccessTokenRecord {
  readonly accessToken: string
  readonly familyId: string
  readonly clientId: string
  readonly resource: string
  readonly scopes: readonly string[]
  readonly subject: string
  readonly expiresAt: number
}

export interface RefreshTokenRecord {
  readonly refreshToken: string
  readonly familyId: string
  readonly clientId: string
  readonly resource: string
  readonly scopes: readonly string[]
  readonly subject: string
  readonly expiresAt: number
}

export interface SessionRecord {
  readonly sessionId: string
  readonly tokenFamilyId: string
  readonly operationNamespace: string
  readonly profileId: string
  readonly protocolVersion: string
  readonly scenarioRevision: number
  readonly expiresAt: number
  initialized: boolean
}

interface MutableOperation {
  readonly operationId: string
  readonly idempotencyKeyHash: string
  readonly namespaceHash: string
  readonly tool: string
  readonly argumentsHash: string
  state: "prepared" | "committed" | "responded" | "indeterminate"
  resultReference: string | null
  readonly createdAt: number
}

export type PrepareOperationResult =
  | { readonly kind: "prepared"; readonly operation: MutationOperationSummary }
  | { readonly kind: "duplicate"; readonly operation: MutationOperationSummary }
  | { readonly kind: "conflict"; readonly operation: MutationOperationSummary }
  | { readonly kind: "reconcile"; readonly operation: MutationOperationSummary }
  | { readonly kind: "capacity" }

interface EmitEventInput {
  readonly correlationId: string
  readonly scenario: EnterpriseMcpScenario
  readonly phase: HandshakePhase
  readonly direction: SafeTraceEvent["direction"]
  readonly kind: SafeTraceEvent["kind"]
  readonly outcome: SafeTraceEvent["outcome"]
  readonly summary: string
  readonly details?: Readonly<Record<string, SafeTraceDetail>>
}

const maximumEventCount = 500
const maximumClientCount = 100
const maximumAuthorizationCodeCount = 100
const maximumTokenCount = 100
const maximumSessionCount = 100
const maximumOperationCount = 1000
const maximumFaultCounterCount = 100
const operationTtlMs = 86_400_000

function isRecord(value: unknown): value is Record<string, unknown> {
  return typeof value === "object" && value !== null && !Array.isArray(value)
}

function canonicalJson(value: unknown): string {
  if (value === null) return "null"
  if (typeof value === "string" || typeof value === "boolean" || typeof value === "number") return JSON.stringify(value)
  if (Array.isArray(value)) return `[${value.map((item) => canonicalJson(item)).join(",")}]`
  if (isRecord(value)) {
    return `{${Object.keys(value)
      .sort()
      .map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`)
      .join(",")}}`
  }
  return JSON.stringify(String(value))
}

export class InstanceState {
  readonly instanceId: string
  readonly clients = new Map<string, OAuthClientRecord>()
  readonly authorizationCodes = new Map<string, AuthorizationCodeRecord>()
  readonly tokens = new Map<string, AccessTokenRecord>()
  readonly refreshTokens = new Map<string, RefreshTokenRecord>()
  readonly sessions = new Map<string, SessionRecord>()
  readonly operations = new Map<string, MutableOperation>()
  readonly faultCounters = new Map<string, number>()
  private readonly traceEvents: SafeTraceEvent[] = []
  private runtimeStatus: RuntimeSnapshot["status"] = "idle"
  private runtimeBaseUrl: string | null = null

  constructor(
    private currentScenario: EnterpriseMcpScenario,
    private currentProfile: ProviderProfile,
    private readonly knownSecrets: readonly string[],
    private readonly environment: EnterpriseMcpMockEnvironment,
    instanceId?: string,
  ) {
    this.instanceId = instanceId ?? environment.randomId()
    this.currentScenario = deepFreeze(currentScenario)
    this.currentProfile = deepFreeze(currentProfile)
  }

  get scenario(): EnterpriseMcpScenario {
    return this.currentScenario
  }

  get profile(): ProviderProfile {
    return this.currentProfile
  }

  get status(): RuntimeSnapshot["status"] {
    return this.runtimeStatus
  }

  get baseUrl(): string | null {
    return this.runtimeBaseUrl
  }

  setRuntime(status: RuntimeSnapshot["status"], baseUrl: string | null): void {
    this.runtimeStatus = status
    this.runtimeBaseUrl = baseUrl
  }

  replaceScenario(scenario: EnterpriseMcpScenario, profile: ProviderProfile): void {
    this.currentScenario = deepFreeze(scenario)
    this.currentProfile = deepFreeze(profile)
    this.clearEphemeralState()
  }

  clearEphemeralState(): void {
    this.clearConnectionState()
    this.operations.clear()
    this.faultCounters.clear()
  }

  clearConnectionState(): void {
    this.clients.clear()
    this.authorizationCodes.clear()
    this.tokens.clear()
    this.refreshTokens.clear()
    this.sessions.clear()
  }

  inheritEstablishedOAuthAuthority(source: InstanceState): void {
    this.clearEphemeralState()
    this.clearEvents()
    source.maintainBounds(this.environment.now())
    for (const [clientId, client] of source.clients) this.clients.set(clientId, client)
    for (const [accessToken, token] of source.tokens) {
      if (this.clients.has(token.clientId)) this.tokens.set(accessToken, token)
    }
    for (const [refreshToken, token] of source.refreshTokens) {
      if (this.clients.has(token.clientId)) this.refreshTokens.set(refreshToken, token)
    }
    this.maintainBounds(this.environment.now())
  }

  maintainBounds(now = this.environment.now()): void {
    for (const [key, client] of this.clients) {
      if (client.expiresAt !== null && client.expiresAt < now) this.clients.delete(key)
    }
    for (const [key, code] of this.authorizationCodes) if (code.expiresAt < now) this.authorizationCodes.delete(key)
    for (const [key, token] of this.tokens) if (token.expiresAt < now) this.tokens.delete(key)
    for (const [key, token] of this.refreshTokens) if (token.expiresAt < now) this.refreshTokens.delete(key)
    for (const [key, session] of this.sessions) if (session.expiresAt < now) this.sessions.delete(key)
    for (const [key, operation] of this.operations) {
      if (operation.state === "responded" && operation.createdAt + operationTtlMs < now) this.operations.delete(key)
    }
    this.trimOldest(this.clients, maximumClientCount)
    this.trimOldest(this.authorizationCodes, maximumAuthorizationCodeCount)
    this.trimOldest(this.tokens, maximumTokenCount)
    this.trimOldest(this.refreshTokens, maximumTokenCount)
    this.trimOldest(this.sessions, maximumSessionCount)
    this.trimRespondedOperations(maximumOperationCount)
    this.trimOldest(this.faultCounters, maximumFaultCounterCount)
  }

  putClient(client: OAuthClientRecord): void {
    this.clients.set(client.clientId, client)
    this.maintainBounds()
  }

  putAuthorizationCode(code: AuthorizationCodeRecord): void {
    this.authorizationCodes.set(code.code, code)
    this.maintainBounds()
  }

  putToken(token: AccessTokenRecord): void {
    this.tokens.set(token.accessToken, token)
    this.maintainBounds()
  }

  putRefreshToken(token: RefreshTokenRecord): void {
    this.refreshTokens.set(token.refreshToken, token)
    this.maintainBounds()
  }

  putSession(session: SessionRecord): void {
    this.sessions.set(session.sessionId, session)
    this.maintainBounds()
  }

  clearEvents(): void {
    this.traceEvents.splice(0, this.traceEvents.length)
  }

  issueOpaque(prefix: string): string {
    return this.environment.opaqueValue(prefix)
  }

  now(): number {
    return this.environment.now()
  }

  emit(input: EmitEventInput): SafeTraceEvent {
    const event: SafeTraceEvent = deepFreeze({
      id: this.environment.randomId(),
      occurredAt: new Date(this.environment.now()).toISOString(),
      correlationId: input.correlationId,
      revision: input.scenario.revision,
      phase: input.phase,
      direction: input.direction,
      kind: input.kind,
      outcome: input.outcome,
      summary: input.summary,
      details: sanitizeTraceDetails(input.details ?? {}, this.knownSecrets),
    })
    this.traceEvents.push(event)
    if (this.traceEvents.length > maximumEventCount) this.traceEvents.splice(0, this.traceEvents.length - maximumEventCount)
    return event
  }

  events(): readonly SafeTraceEvent[] {
    return deepFreeze([...this.traceEvents])
  }

  shouldApplyFault(definition: FaultDefinition, scenario: EnterpriseMcpScenario): boolean {
    const active = scenario.activeFault
    if (!active || active.id !== definition.id) return false
    const counterKey = `${scenario.revision}:${definition.id}`
    const nextCount = (this.faultCounters.get(counterKey) ?? 0) + 1
    this.faultCounters.set(counterKey, nextCount)
    if (active.trigger.occurrence === "always") return true
    if (active.trigger.occurrence === "once") return nextCount === 1
    return nextCount === active.trigger.requestNumber
  }

  prepareOperation(namespace: string, tool: string, idempotencyKey: string, argumentsValue: unknown): PrepareOperationResult {
    const namespaceHash = sha256(namespace)
    const idempotencyKeyHash = sha256(idempotencyKey)
    const argumentsHash = sha256(canonicalJson(argumentsValue))
    const existing = [...this.operations.values()].find(
      (operation) => operation.namespaceHash === namespaceHash && operation.idempotencyKeyHash === idempotencyKeyHash,
    )
    if (existing) {
      const operation = this.operationSummary(existing)
      if (existing.tool !== tool || existing.argumentsHash !== argumentsHash) return { kind: "conflict", operation }
      if (existing.state !== "responded") return { kind: "reconcile", operation }
      return { kind: "duplicate", operation }
    }

    this.maintainBounds()
    if (this.operations.size >= maximumOperationCount) {
      this.trimRespondedOperations(maximumOperationCount - 1)
      if (this.operations.size >= maximumOperationCount) return { kind: "capacity" }
    }

    const operation: MutableOperation = {
      operationId: this.issueOpaque("operation"),
      idempotencyKeyHash,
      namespaceHash,
      tool,
      argumentsHash,
      state: "prepared",
      resultReference: null,
      createdAt: this.environment.now(),
    }
    this.operations.set(operation.operationId, operation)
    this.maintainBounds()
    return { kind: "prepared", operation: this.operationSummary(operation) }
  }

  transitionOperation(
    operationId: string,
    state: MutableOperation["state"],
    resultReference: string | null,
  ): MutationOperationSummary {
    const operation = this.operations.get(operationId)
    if (!operation) throw new Error(`Unknown operation '${operationId}'`)
    operation.state = state
    operation.resultReference = resultReference
    return this.operationSummary(operation)
  }

  snapshot(clientSecretConfigured: boolean): RuntimeSnapshot {
    this.maintainBounds()
    const baseUrl = this.runtimeBaseUrl
    return deepFreeze({
      status: this.runtimeStatus,
      instanceId: this.instanceId,
      scenario: this.currentScenario,
      profile: this.currentProfile,
      baseUrl,
      mcpUrl: baseUrl ? new URL(this.currentProfile.endpointPath, baseUrl).href : null,
      oauth: {
        authorizationServerUrl: baseUrl,
        protectedResourceMetadataUrl: baseUrl ? new URL(`/.well-known/oauth-protected-resource${this.currentProfile.endpointPath}`, baseUrl).href : null,
        registration: this.currentScenario.oauth.registration,
        clientId: this.currentScenario.oauth.clientId,
        clientSecretConfigured,
      },
      counts: {
        events: this.traceEvents.length,
        sessions: this.sessions.size,
        clients: this.clients.size,
        tokens: this.tokens.size + this.refreshTokens.size,
        operations: this.operations.size,
      },
      operations: [...this.operations.values()].map((operation) => this.operationSummary(operation)),
    })
  }

  private operationSummary(operation: MutableOperation): MutationOperationSummary {
    return {
      operationId: operation.operationId,
      idempotencyKeyHash: operation.idempotencyKeyHash,
      tool: operation.tool,
      argumentsHash: operation.argumentsHash,
      state: operation.state,
      resultReference: operation.resultReference,
    }
  }

  private trimOldest<Key, Value>(map: Map<Key, Value>, maximum: number): void {
    while (map.size > maximum) {
      const oldestKey = map.keys().next().value
      if (oldestKey === undefined) return
      map.delete(oldestKey)
    }
  }

  private trimRespondedOperations(maximum: number): void {
    if (this.operations.size <= maximum) return
    for (const [operationId, operation] of this.operations) {
      if (operation.state === "responded") this.operations.delete(operationId)
      if (this.operations.size <= maximum) return
    }
  }
}