debanshup/mitm-core

How debanshup/mitm-core works

mitm-core is a Node.js MITM proxy framework. A client connects to the Proxy, whose middleware initializes connection/request scopes, dispatches protocol lifecycle events, and runs phased handlers; the transport layer forwards traffic to upstreams and returns responses. Plugins can inspect or modify traffic, while rules, TLS certificate handling, and optional response caching provide policy and supporting capabilities. The README documents HTTP/1.1, HTTPS, WebSockets, streaming, and lifecycle support; some of those implementation links are documented capabilities rather than sampled call paths.

Main entry points: PipelineCompiler.ts Pipeline compiler · Proxy.ts Proxy API · middleware.ts Connection middleware · proxyEvents.ts Proxy events

Components 25

Proxy entry

Proxy API src/lib/Proxy.ts
Connection middleware src/middleware/middleware.ts

Processing pipeline

Pipeline compiler src/core/pipelines/PipelineCompiler.ts
Lifecycle phases src/phase/Phase.ts
Request handling src/core/handlers/request.handler.ts
Response handling src/core/handlers/response.handler.ts
TLS handshake src/core/handlers/handshake.handler.ts

Protocol transports

HTTP/1 inbound src/core/transport/http1/H1InboundBridge.ts
HTTP/1 upstream src/core/transport/http1/UpstreamInitiator.ts
HTTP/1 outbound src/core/transport/http1/H1OutboundBridge.ts
WebSocket bridge src/core/transport/ws/WSOutboundBridge.ts
HTTP/2 bridges src/core/transport/http2/H2InboundBridge.ts
Streaming responses src/core/transport/http1/streamingResponseHandler.ts

Plugins and policy

Plugin lifecycle src/core/plugin/BasePlugin.ts
Plugin events src/core/event/plugin-events/pluginEvents.ts
Proxy events src/core/event/proxy-events/proxyEvents.ts
Rule engine src/core/rule/RuleEngine.ts
Rule store src/core/rule/ruleStore.ts

Runtime services

Request scopes src/core/scope/ContextManager.ts
Scope mutation src/core/scope/ScopeMutator.ts
TLS contexts src/core/security/SecureContextManager.ts
Certificate cache src/core/cache/CertificateCacheManager.ts
Response cache src/core/cache/ResponseCache.ts
Request state src/core/state/StateStore.ts

Other components

Client

Connections 38

Client → Proxy API: connects to README.md
Proxy API → Connection middleware: registers src/lib/Proxy.ts
Connection middleware → Request scopes: initializes context src/middleware/middleware.ts
Connection middleware → Pipeline compiler: runs pipeline src/middleware/middleware.ts
Connection middleware → Plugin events: emits lifecycle events src/middleware/middleware.ts
Connection middleware → Proxy events: emits connection events src/middleware/middleware.ts
Connection middleware → Scope mutation: initializes scopes src/middleware/middleware.ts
Pipeline compiler → Lifecycle phases: dispatches phases src/core/pipelines/PipelineCompiler.ts
Pipeline compiler → Request handling: dispatches handlers src/core/pipelines/PipelineCompiler.ts
Pipeline compiler → Response handling: dispatches handlers src/core/pipelines/PipelineCompiler.ts
Pipeline compiler → TLS handshake: dispatches handlers src/core/pipelines/PipelineCompiler.ts
Pipeline compiler → WebSocket bridge: executes bridge src/core/pipelines/PipelineCompiler.ts
Pipeline compiler → Proxy events: reports errors src/core/pipelines/PipelineCompiler.ts
Request handling → HTTP/1 upstream: initiates upstream src/core/handlers/request.handler.ts
Request handling → Scope mutation: mutates scope src/core/handlers/request.handler.ts
Response handling → HTTP/1 outbound: writes response src/core/handlers/response.handler.ts
TLS handshake → TLS contexts: creates TLS context src/core/handlers/handshake.handler.ts
TLS handshake → HTTP/1 inbound: uses inbound bridge src/core/handlers/handshake.handler.ts
TLS handshake → Proxy events: reports lifecycle src/core/handlers/handshake.handler.ts
Plugin lifecycle → Plugin events: uses event hooks src/core/plugin/BasePlugin.ts
TLS contexts → Certificate cache: uses certificate cache src/core/security/SecureContextManager.ts
Streaming responses → Response cache: processes cached responses src/core/transport/http1/streamingResponseHandler.ts
Streaming responses → Scope mutation: updates scope src/core/transport/http1/streamingResponseHandler.ts
Request scopes → Request state: creates lifecycle state src/core/scope/ContextManager.ts
Rule engine → Rule store: uses rule store src/core/rule/RuleEngine.ts
WebSocket bridge → Plugin events: intercepts messages src/core/transport/ws/WSOutboundBridge.ts
WebSocket bridge → Proxy events: emits message events src/core/transport/ws/WSOutboundBridge.ts
WebSocket bridge → Scope mutation: updates scope src/core/transport/ws/WSOutboundBridge.ts
HTTP/1 inbound → Proxy events: emits connection events src/core/transport/http1/H1InboundBridge.ts
HTTP/1 inbound → Request scopes: uses request context src/core/transport/http1/H1InboundBridge.ts
Proxy API → Plugin lifecycle: manages plugins src/lib/Proxy.ts
Proxy API → Request scopes: manages active requests src/lib/Proxy.ts
Proxy API → Proxy events: reports proxy errors src/lib/Proxy.ts
Client → HTTP/2 bridges: uses HTTP/2 README.md
Client → WebSocket bridge: upgrades WebSocket README.md
HTTP/1 upstream → Streaming responses: streams responses README.md
Client → Rule engine: traffic governed by rules README.md
Proxy API → Response cache: optionally caches responses README.md

Drawn by GitDiagram on November 10, 2026 from the repository's file tree, README and source files. Read as Markdown ·