http_listener.h File Reference

Serve the external MCP bridge over Streamable HTTP (gh#204, v2.14.0). More...

#include <entropic/entropic_export.h>
#include <atomic>
#include <chrono>
#include <filesystem>
#include <memory>
#include <mutex>
#include <string>
#include <thread>

Include dependency graph for http_listener.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
class	entropic::http::AuthThrottle
	Refuses after repeated authentication failures (decision #84). More...
class	entropic::http::HttpListener
	Streamable-HTTP front end for an ExternalBridge (gh#204). More...

Namespaces
namespace	entropic
	Activate model on GPU (WARM → ACTIVE).

Functions
std::string	entropic::http::generate_token ()
	A fresh bearer token: 256 bits from getrandom(), hex-encoded.
bool	entropic::http::tokens_equal (const std::string &a, const std::string &b)
	Compare two tokens in time independent of where they differ.
bool	entropic::http::host_allowed (const std::string &host, int port)
	Whether a Host header names this listener's loopback endpoint.
std::string	entropic::http::bearer_token (const std::string &header)
	The token in an Authorization: Bearer <t> header, or "".
std::filesystem::path	entropic::http::token_path_for (int port)
	Where the token for a port is written.
bool	entropic::http::prepare_private_dir (const std::filesystem::path &dir, std::string &err)
	Create or verify the token directory: 0700, ours, not a symlink.
bool	entropic::http::write_token_file (const std::filesystem::path &path, const std::string &token, std::string &err)
	Write token to path atomically (temp + rename), mode 0600.

Detailed Description

Serve the external MCP bridge over Streamable HTTP (gh#204, v2.14.0).

Why

Every MCP client that wanted the engine spawned its own entropic mcp-bridge over stdio, and a consumer started a host per client behind it — N editors, N hosts, N × idle device memory. MCP's answer to "many clients, one server" is a network transport: every client points at one URL. This serves the SAME bridge — the same tools, sessions and turn queue the unix socket serves — at http://127.0.0.1:<port>/mcp.

Security (decision #84)

The listener never leaves loopback and carries no TLS: remote use goes through ssh -L <port>:127.0.0.1:<port> host, which supplies both. Over TCP there is no SO_PEERCRED, so a bearer token stands in for it:

• 256 bits from getrandom(), regenerated every start, written atomically to ~/.entropic/serve/<port>.token, mode 0600, in a directory that must be 0700, owned by this uid and not a symlink — otherwise start refuses. Removed on a clean stop.
• Compared in constant time; never logged, never echoed.
• Any request carrying an Origin header is refused (a browser page cannot drive the engine), as is a Host that is not this loopback address and port (DNS rebinding).
• Body and header sizes capped; read/write timeouts; repeated auth failures throttled, each logged without the token.

Transport

POST /mcp carries one JSON-RPC message. A notification or response gets

1. tools/call streams: progress notifications, then the result, as SSE events. Anything else answers as application/json. GET and DELETE are 405: there is no server-initiated stream and no transport session (conversation identity is the session tool argument). Async completion notifications are delivered over the unix socket only; an HTTP client polls ask_status.

Exported (ENTROPIC_EXPORT) for white-box tests only, as ExternalBridge is; not part of the C API.

Version

2.14.0

Definition in file http_listener.h.

Function Documentation

bearer_token()

ENTROPIC_EXPORT std::string entropic::http::bearer_token

(

const std::string &

header

)

The token in an Authorization: Bearer <t> header, or "".

Parameters

header

Authorization header value.

Returns

The token, or "" when the scheme is not Bearer. @utility

Version

2.14.0

Definition at line 119 of file http_listener.cpp.

generate_token()

ENTROPIC_EXPORT std::string entropic::http::generate_token

(

)

A fresh bearer token: 256 bits from getrandom(), hex-encoded.

Returns

64 lowercase hex characters, or "" if the kernel gave no entropy. @utility

Version

2.14.0

Definition at line 62 of file http_listener.cpp.

host_allowed()

ENTROPIC_EXPORT bool entropic::http::host_allowed	(	const std::string &	host,
		int	port
	)

Whether a Host header names this listener's loopback endpoint.

Parameters

host	Host header value ("" when absent).
port	Listening port.

Returns

true for 127.0.0.1:<port> or localhost:<port>. @utility

Version

2.14.0

Definition at line 107 of file http_listener.cpp.

prepare_private_dir()

ENTROPIC_EXPORT bool entropic::http::prepare_private_dir	(	const std::filesystem::path &	dir,
		std::string &	err
	)

Create or verify the token directory: 0700, ours, not a symlink.

Parameters

	dir	Directory to prepare.
[out]	err	Why it is unusable.

Returns

true when the directory is safe to hold a token. @utility

Version

2.14.0

Definition at line 146 of file http_listener.cpp.

token_path_for()

ENTROPIC_EXPORT std::filesystem::path entropic::http::token_path_for

(

int

port

)

Where the token for a port is written.

Parameters

port	Listening port.

Returns

$HOME/.entropic/serve/<port>.token. @utility

Version

2.14.0

Definition at line 132 of file http_listener.cpp.

tokens_equal()

ENTROPIC_EXPORT bool entropic::http::tokens_equal	(	const std::string &	a,
		const std::string &	b
	)

Compare two tokens in time independent of where they differ.

Parameters

a	First value.
b	Second value.

Returns

true when equal. @utility

Version

2.14.0

Definition at line 88 of file http_listener.cpp.

write_token_file()

ENTROPIC_EXPORT bool entropic::http::write_token_file	(	const std::filesystem::path &	path,
		const std::string &	token,
		std::string &	err
	)

Write token to path atomically (temp + rename), mode 0600.

Parameters

	path	Destination.
	token	Token text.
[out]	err	Why the write failed.

Returns

true on success. @utility

Version

2.14.0

Definition at line 171 of file http_listener.cpp.