Runtime
Secure Browser-To-Companion Protocol For Local Inference And Direct P2P
Report summary
The architectural mandate for the protocol bridging the TinyRustLM.com web application and the local Rust/.NET companion demands a transport layer that guarantees cryptographic integrity, adheres strictly to modern web security boundaries, and minimizes deployment friction for end-users. Following a
Key topics
- Runtime
- AI
- .NET
- C#
- Python
- Rust
- Privacy
- Strategy
Research provenance
For citation, use the report title and canonical URL. Archival presence does not establish authorship or promote report statements into portfolio evidence.
This page renders the archived Markdown as safe, formatted HTML. It is background research and does not become a portfolio claim without evidence review.
Full report
On this page
1. Executive protocol and transport recommendation
The architectural mandate for the protocol bridging the TinyRustLM.com web application and the local Rust/.NET companion demands a transport layer that guarantees cryptographic integrity, adheres strictly to modern web security boundaries, and minimizes deployment friction for end-users. Following an exhaustive evaluation of available transport mechanisms, the definitive engineering recommendation for the first-release protocol is HTTP/1.1 operating over a plaintext loopback connection (bound strictly to 127.0.0.1 and ::1), augmented by Server-Sent Events (SSE) for downstream streaming and governed by the W3C Fetch API with explicit Local Network Access (LNA) annotations. The selection of plaintext loopback relies on the normative behavior of modern web browsers, which explicitly designate 127.0.0.1 and ::1 as potentially trustworthy origins. Consequently, these loopback addresses are treated as Secure Contexts, circumventing the traditional requirement for Transport Layer Security (TLS) to access advanced web platform features1. Attempting to provision and manage a locally trusted TLS certificate introduces catastrophic deployment complexity, requiring the injection of a local Certificate Authority (CA) into the operating system's trust store. This practice not only triggers aggressive heuristics from Endpoint Detection and Response (EDR) systems but also conditions users to accept arbitrary local certificates, degrading the overall security posture of the host machine. By leveraging the browser's native trust of the loopback interface, the architecture achieves a Secure Context without the operational hazards of local PKI management. To facilitate communication from the HTTPS-served TinyRustLM.com origin to the plaintext local companion, the protocol must actively navigate mixed-content restrictions and the evolving Local Network Access specifications. The W3C LNA framework explicitly permits requests from public secure contexts to loopback endpoints, provided the fetch request is explicitly annotated. By injecting the targetAddressSpace: "loopback" directive into the fetch() initialization, the browser is instructed to bypass traditional mixed-content blocking, acknowledging that the target resides within the local machine's boundary3. This mechanism ensures that the web application can reliably connect to the local companion without degrading the HTTPS posture of the primary domain. Alternative transports present insurmountable flaws for a pre-publication, zero-configuration local agent. WebSockets, while offering bidirectional streaming, suffer from systemic vulnerabilities related to Cross-Site WebSocket Hijacking (CSWSH). If the Origin header is not validated with absolute perfection, malicious web pages can silently upgrade connections and hijack the companion5. Furthermore, early implementations of Local Network Access protections did not consistently guard WebSocket handshakes, leaving them exposed to cross-origin abuse until very recent browser updates7. WebTransport, though technologically superior for low-latency multiplexing, enforces draconian constraints on self-signed certificates. Specifically, the serverCertificateHashes mechanism dictates that the utilized certificate must have a maximum validity period of 14 days9. For a background companion process expected to run unattended for months, forcing a certificate rotation and subsequent re-pairing every two weeks constitutes an unacceptable degradation of the user experience. Thus, HTTP/1.1 with strict CORS, LNA preflights, and application-layer cryptographic signatures remains the singular viable transport for this architecture.
2. Threat model and protected-asset inventory
The security architecture must enforce an impermeable trust boundary between the unprivileged, sandboxed JavaScript execution environment hosted by TinyRustLM.com and the local operating system process executing the companion. Loopback communication is not inherently secure; it merely guarantees that packets do not traverse external network interfaces. The local machine remains a highly contested environment.
| Threat Actor / Vector | Description and Capabilities | Architectural Mitigation |
|---|---|---|
| Malicious Remote Origin | A hostile website attempts to scan local ports, discover the companion, and issue Cross-Site Request Forgery (CSRF) payloads to initiate unauthorized inference or model deletion. | Strict enforcement of CORS and Local Network Access preflights. Rejection of any request lacking a valid RFC 9421 HTTP Message Signature. |
| DNS Rebinding Attack | An attacker configures a public DNS record to resolve to 127.0.0.1, tricking the browser into bypassing Same-Origin Policy and routing malicious requests to the companion10. | Absolute validation of the HTTP Host header. Any request not explicitly addressed to 127.0.0.1, \[::1\], or localhost is immediately dropped at the socket layer. |
| Compromised Project Page (XSS) | If TinyRustLM.com suffers a Cross-Site Scripting vulnerability, the attacker inherits the origin's trust and attempts to extract P2P keys or exfiltrate local model bytes. | The companion never returns administrative credentials, P2P signing keys, or raw model bytes to the browser. Capabilities are strictly scoped to inference requests. |
| Malicious Browser Extension | An extension with \<all\_urls\> permissions intercepts Fetch requests, attempting to steal bearer tokens to replay commands. | Complete elimination of bearer tokens. Implementation of cryptographic pairing and per-request signatures with strict nonce tracking and timestamp validation11. |
| Local Port Squatter | Co-resident malware binds to the companion's designated port before the companion starts, intercepting all browser traffic directed at TinyRustLM. | Utilization of SO\_EXCLUSIVEADDRUSE on Windows to prevent port hijacking, combined with a bounded port-discovery algorithm to find a safe listening socket13. |
| Stale Browser Profile | A user leaves a session active for weeks, expanding the window for physical or logical session hijacking. | Cryptographic session capabilities expire automatically. The companion requires periodic re-authentication for long-running idle connections. |
The protected assets within this threat model dictate the protocol's constraints. The most critical assets are the localized model files (.slm artifacts), which represent significant intellectual property and bandwidth investment. These files must never be exposed to the browser's memory space, preventing exfiltration via a compromised web context. Similarly, the P2P private keys, utilized to establish and sign secure WebRTC datagrams for direct model transfer, are supreme secrets. If these keys cross the boundary into the browser, a malicious script could impersonate the user's node in the broader peer-to-peer swarm. The companion's execution environment itself is a protected asset; the parsing of model artifacts must be structurally verified to prevent arbitrary code execution, a vulnerability notoriously present in legacy machine learning serialization formats like Python's pickle15. Finally, the cryptographic capabilities that bind a specific browser session to the companion must be rigorously protected against theft, interception, and replay.
3. Browser and transport standards matrix
The selection of a transport protocol requires navigating a complex matrix of evolving web standards, specifically concerning how browsers mediate communication between public internet origins and local network interfaces. The W3C has fundamentally restructured this mediation through the Local Network Access (LNA) specification, which mandates explicit permission structures and preflight checks to mitigate decades of CSRF and Confused Deputy attacks against local devices17.
| Transport Mechanism | Origin Validation | Mixed Content Compatibility | Streaming & Lifecycle | Security Verdict for Companion |
|---|---|---|---|---|
| HTTP/1.1 (Loopback \+ Fetch) | Exceptional. Enforced via CORS preflights and LNA Access-Control-Request-Private-Network headers19. | Native support via targetAddressSpace: "loopback" annotation, bypassing traditional secure-context blocks3. | Supports unidirectional streaming via Server-Sent Events (SSE) and cancellation via AbortController. | Selected. Provides the highest degree of deterministic security, compatibility, and precise origin control without requiring PKI infrastructure. |
| WebSockets | Manual. The companion must strictly parse and validate the Origin header; failure leads directly to CSWSH5. | Generally exempt from strict mixed-content rules, but historically inconsistent across browser LNA implementations7. | Excellent bidirectional streaming, but lacks native backpressure mechanisms compared to HTTP/3 or pure TCP streams. | Rejected. The manual burden of origin validation and the historical fragility of WebSocket security in local contexts introduces unnecessary risk. |
| WebTransport (HTTP/3) | Exceptional. Inherits web security model with mandatory TLS. | Requires secure contexts. Local usage relies on the serverCertificateHashes API. | Unparalleled multiplexing and datagram support, ideal for complex inference streaming. | Rejected. The serverCertificateHashes API hardcodes a maximum 14-day certificate lifetime9, requiring continuous, disruptive local credential rotation. |
| HTTPS (Local Certificate) | Exceptional. | Natively compatible as it presents a fully secure context to the browser. | Fully supports all modern Fetch and streaming APIs without mixed-content warnings. | Rejected. Distributing a private key with the application or generating a local CA compromises system trust and frequently triggers aggressive EDR intervention. |
The reliance on HTTP/1.1 with Fetch demands precise configuration of the TinyRustLM.com web application. To enable advanced local processing within the browser—specifically the use of WebAssembly threads and SharedArrayBuffer for rendering optimizations or local cryptographic operations—the hosting origin must establish a cross-origin isolated state22. This state is achieved by serving the web page with the HTTP headers Cross-Origin-Opener-Policy: same-origin and Cross-Origin-Embedder-Policy: require-corp (or credentialless)24. These headers instruct the browser to sever potentially dangerous cross-window communications and strictly regulate the embedding of cross-origin resources, thereby neutralizing classes of side-channel attacks (such as Spectre) that could otherwise monitor the rapid cryptographic operations utilized in the browser-to-companion authentication flow.
4. Loopback binding, discovery, and port-squatting defense
The foundation of the protocol's physical security is the local socket binding. The companion must rigidly bind its listening sockets exclusively to the IPv4 loopback (127.0.0.1) and the IPv6 loopback (::1) interfaces. Binding to wildcard addresses, such as 0.0.0.0 or ::, exposes the companion to the entire Local Area Network (LAN) and potentially the public internet, violating the core architectural constraint that all command and control must originate from the local machine. Operating systems handle socket binding uniquely, presenting specific adversarial opportunities. On Windows environments, the default behavior of the Winsock API permits multiple processes to bind to the same port if specific flags are manipulated. An unprivileged malicious process can utilize the SO\_REUSEADDR socket option to hijack a port already in use by a legitimate application, creating a non-deterministic state where incoming TCP connections may be routed to the attacker's process13. To permanently neutralize this port hijacking vector, the companion must forcefully apply the SO\_EXCLUSIVEADDRUSE socket option prior to executing the bind() system call13. This flag commands the Windows kernel to reject any subsequent binding attempts to that specific port and IP combination, securing the companion's listening interface against co-resident malware. On Linux environments, the companion must ensure that SO\_REUSEPORT and SO\_REUSEADDR are strictly disabled during normal operation to achieve equivalent exclusivity. Discovering the active port without leaking bearer secrets to the operating system's process table, DNS logs, or browser history requires a deterministic, bounded search algorithm.
| Discovery Phase | Execution Protocol | Security Rationale |
|---|---|---|
| Companion Startup | The companion attempts to bind to port 51042 with exclusive flags. If the OS returns WSAEADDRINUSE (Windows) or EADDRINUSE (Linux), the companion increments the port by one and retries, up to a maximum boundary of 51052\. | Prevents denial-of-service by local port squatters. Ensures the companion can always establish a secure listening post without requiring elevated administrative privileges to kill conflicting processes. |
| Browser Polling | TinyRustLM.com executes concurrent fetch() requests to http://127.0.0.1:\<port\>/v1/health across the bounded port range, utilizing the targetAddressSpace: "loopback" annotation. | Discovers the companion instantly without relying on mDNS, registry keys, or local configuration files that might leak state. The LNA annotation bypasses mixed-content blocks3. |
| Health Response | The companion responds with a static JSON payload containing the protocol schema version, an ephemeral instance ID, and readiness state. | The endpoint requires no authentication but explicitly returns zero sensitive data. It serves solely as a cryptographic beacon indicating the protocol dialect supported by the specific port. |
By utilizing a bounded port set and parallel local fetching, the protocol completely avoids dynamic URI handlers (which leak parameters to the OS execution shell) or OAuth-style loopback redirects (which expose tokens in the browser's navigation history).
5. Pairing, origin binding, session capabilities, and secret lifetime
Establishing a trusted session between the unprivileged browser context and the highly privileged local companion requires a pairing ceremony that explicitly proves user intent and cryptographically binds the session to the designated origin, without ever transmitting a long-lived bearer secret across the boundary. The protocol leverages asymmetric cryptography to establish this trust. The pairing sequence initiates with the TinyRustLM.com JavaScript application utilizing the native WebCrypto API to generate an Ed25519 keypair. The private key is strictly marked as non-extractable and persisted within the browser's IndexedDB, ensuring it cannot be exfiltrated by malicious JavaScript injected via a cross-site scripting (XSS) attack. Simultaneously, upon startup or user request, the companion process generates a cryptographically secure, random 6-digit numeric PIN. This PIN is presented out-of-band to the user, typically via the companion's local graphical user interface or standard output console. The user acts as the secure bridge, reading the PIN from the companion and manually entering it into the TinyRustLM.com web interface. The browser computes a cryptographic hash of this PIN and constructs a pairing request (POST /v1/pair), transmitting the hashed PIN alongside its newly generated Ed25519 public key. The companion receives this request, verifies the hash against its internal ephemeral state, and if successful, records the browser's public key. Crucially, the companion binds this public key exclusively to the https://tinyrustlm.com origin and issues a short-lived session nonce.
| Pairing State | Cryptographic Action | Lifecycle & Revocation |
|---|---|---|
| Initialization | WebCrypto generates Ed25519 keypair. Companion generates ephemeral 6-digit PIN. | Browser private key persists in IndexedDB until explicitly cleared. Companion PIN expires after 5 minutes of inactivity. |
| Verification | Browser submits PIN hash and Public Key. Companion verifies hash and registers Public Key. | Establishes the trust anchor. The companion maps the Public Key to specific capability scopes (e.g., inference:run, model:import). |
| Session Active | Companion issues a cryptographic Session ID. Browser uses private key to sign all subsequent HTTP requests. | Session ID requires continuous heartbeat. If no valid signed request is received within 24 hours, the session is aggressively evicted from companion memory. |
| Revocation | User triggers disconnect in UI, or companion detects a catastrophic protocol violation (e.g., repeated invalid signatures). | The companion deletes the registered Public Key and drops all active TCP sockets associated with the Session ID. Explicit re-pairing is required. |
This architecture ensures that long-lived secrets—such as the companion's administrative keys, catalog signing credentials, or WebRTC/P2P private keys—are never serialized into HTTP responses or passed to the browser's JavaScript environment. The browser is only granted the capability to request actions (like inference), and it proves its authorization to make these requests by signing them with its local, non-extractable private key. If the browser profile is stolen, the attacker acquires the ability to ask the companion to generate text, but they do not acquire the capability to masquerade as the companion on the broader peer-to-peer network.
6. Credential storage and secret lifetime
The persistence of credentials across system restarts presents a critical security challenge. The companion must store the registered browser public keys, its own P2P identity keys, and integration tokens without relying on plaintext configuration files that could be easily harvested by local malware or overly permissive backup software. On Windows operating systems, the companion must integrate directly with the Data Protection API (DPAPI) via the CryptProtectData and CryptUnprotectData functions14. DPAPI provides a robust mechanism to encrypt arbitrary data utilizing cryptographic keys derived directly from the active user's logon session. By invoking CryptProtectData without cross-machine flags, the resulting encrypted blob is cryptographically bound to both the local machine and the specific user account14. This ensures that even if another user logs into the same machine, or if a malicious process attempts to copy the encrypted vault to a remote server, the data remains undecipherable29. The companion writes this DPAPI-protected blob to its localized AppData directory. On Linux environments, the companion integrates with the Secret Service API via libraries such as libsecret31. This delegates the encryption and storage of key material to the user's desktop keyring (e.g., GNOME Keyring or KDE Wallet). Similar to DPAPI, this ensures that the data is protected by the user's login credentials and is isolated from other users on the system. In the event of a catastrophic crash, the companion relies on the atomic writes of the underlying OS file system to ensure the encrypted vault is not corrupted. Upon restart, the companion utilizes CryptUnprotectData (or the libsecret equivalent) to restore its state14. The browser's Ed25519 private key remains secured in IndexedDB. Because the browser signs requests based on the session established during pairing, a companion restart merely forces the browser to negotiate a new ephemeral session nonce using its persistently trusted public key, creating a seamless recovery experience that requires no additional user intervention.
7. Versioned discovery and route/message schemas
To ensure forward compatibility and deterministic behavior, the protocol relies on strict versioning and rigid JSON schemas for all payloads. The companion exposes a discovery document at GET /v1/health that serves as the definitive source of truth regarding its capabilities and protocol dialect. This discovery payload includes the schema identity (e.g., tinyrustlm-local-v1), the exact build hash of the companion binary, a matrix of supported operations, maximum permitted payload sizes (e.g., a 100MB limit on initial import headers to prevent memory exhaustion32), and a list of active feature flags. This allows the TinyRustLM.com frontend to gracefully degrade features if it detects an older companion version. The protocol mandates that all parsers within the companion reject unknown fields deterministically. If the browser transmits a JSON payload containing an undocumented key, the companion must not silently ignore it; it must immediately return a 400 Bad Request containing a standardized error schema. This rigid parsing strategy neutralizes request smuggling attacks, prevents parser differential vulnerabilities, and ensures that developers do not accidentally rely on undefined protocol behavior. Unsupported protocol versions requested by the browser similarly result in a hard failure, forcing the user to update their companion binary rather than operating in a vulnerable legacy state.
8. Exact HTTP or message routes
The protocol surface area is minimized to exclusively support the essential operations required for local inference and P2P coordination. Every endpoint is explicitly defined, and any route not present in this specification is considered a severe security violation.
| Route Definition | HTTP Method | Authentication Requirement | Functional Description |
|---|---|---|---|
| /v1/health | GET | Unauthenticated | Returns protocol readiness, schema version, and an ephemeral instance ID for discovery. |
| /v1/pair | POST | Unauthenticated | Accepts the browser's Ed25519 public key and the user-mediated PIN hash to establish origin binding. |
| /v1/models | GET | RFC 9421 Signature | Returns an inventory of locally available models, utilizing public-safe identifiers (e.g., SHA-256 hashes) rather than revealing absolute file system paths. |
| /v1/models/import | POST | RFC 9421 Signature | Initiates the streaming import of a .slm artifact from the browser or triggers a P2P acquisition sequence. |
| /v1/models/import/{id} | GET | RFC 9421 Signature | An SSE endpoint streaming the real-time progress and verification status of an active import operation. |
| /v1/generate | POST | RFC 9421 Signature | Accepts a model identifier and a prompt hash. Returns an SSE stream of text deltas representing the inference output. |
| /v1/generate/{id}/cancel | POST | RFC 9421 Signature | Explicitly aborts a long-running generation task, signaling the companion to drop the context and free VRAM. |
| /v1/p2p/status | GET | RFC 9421 Signature | Returns abstract health metrics regarding the P2P lane (e.g., active\_peers, transfer\_rate). |
Routes that manipulate absolute file system paths, expose raw memory dumps, permit arbitrary configuration editing, or allow the retrieval of historical prompt logs are strictly prohibited in this release. Legacy endpoints designed for deprecated architectures are entirely eradicated from the codebase to eliminate lingering attack surfaces.
9. Canonical authentication, anti-replay, and idempotency
To protect against interception, replay, and manipulation of requests by malicious browser extensions or co-resident processes, the protocol discards traditional bearer tokens (such as standard JWTs) in favor of HTTP Message Signatures as defined by the IETF standard RFC 942133. This ensures that every mutating request is cryptographically bound to the specific action intended by the browser. The browser construct a signature base string using strictly defined canonicalization rules. The covered components must include the HTTP method (@method), the exact request path (@path), the host authority (@authority), and a cryptographic hash of the HTTP body (content-digest)11. By including the content-digest, the protocol guarantees that an attacker cannot intercept a valid signed request and swap out the prompt or model identifier without invalidating the signature11. The signature parameters (@signature-params) append critical temporal and uniqueness metadata to the base string. This includes a created timestamp, an expires timestamp (enforcing a maximum validity window of 5 minutes), a unique nonce, and a keyid mapping to the established session11. The browser signs this base string using its non-extractable Ed25519 private key and attaches the resulting bytes in the Signature and Signature-Input headers. The companion verifies this signature using constant-time comparison functions to prevent timing side-channel attacks. To defeat replay attacks, the companion maintains an in-memory Least Recently Used (LRU) cache of all processed nonce values11. If a request presents a nonce that exists in the cache, or if the created timestamp falls outside the strict clock-skew tolerance, the companion deterministically rejects the request with a 401 Unauthorized response. Furthermore, to safely handle network interruptions during state-mutating requests (such as model imports), the protocol mandates an Idempotency-Key header. The companion caches the final response of operations keyed by this header for 24 hours, allowing the browser to safely retry operations without triggering duplicate processing.
10. CORS, CSP, Private Network Access, Host, and DNS-rebinding controls
The protocol's defense against cross-origin attacks relies on a deeply integrated, multi-layered validation pipeline executing within the companion. The most immediate threat is DNS rebinding, where an attacker modifies a public DNS record to resolve to 127.0.0.1, tricking the browser into sending requests to the companion while bypassing the Same-Origin Policy10. The companion defeats DNS rebinding at the HTTP parser level by strictly validating the Host header. If the Host header does not exactly match 127.0.0.1:\<port\>, \[::1\]:\<port\>, or localhost:\<port\>, the companion must immediately terminate the TCP socket without returning an HTTP response. This aggressive closure prevents the browser from processing any potentially confusing redirect or error headers. For legitimate cross-origin requests originating from TinyRustLM.com, the companion enforces strict Cross-Origin Resource Sharing (CORS) combined with Local Network Access (LNA) validations. When the browser initiates a request, it sends a preflight OPTIONS request containing the Access-Control-Request-Private-Network: true header19. The companion evaluates the Origin header. If, and only if, the origin is exactly https://tinyrustlm.com, the companion responds with Access-Control-Allow-Origin: https://tinyrustlm.com and Access-Control-Allow-Private-Network: true. The use of wildcard origins (\) or dynamic reflection of arbitrary origins is explicitly prohibited, as these practices dismantle the fundamental security boundary of the web platform. To optimize performance while maintaining security, the preflight response includes an Access-Control-Max-Age: 7200 header. Chromium-based browsers cap the maximum duration for caching CORS preflights at 2 hours (7200 seconds); specifying this exact value minimizes the latency overhead of repeated preflight negotiations without running afoul of browser-imposed limitations35. On the frontend, TinyRustLM.com enforces a rigorous Content Security Policy (CSP) to restrict the execution environment:default-src 'self'; connect-src 'self' http://127.0.0.1:\ http://localhost:\ ws://127.0.0.1:\ ws://localhost:\*; script-src 'self' 'wasm-unsafe-eval'; This policy ensures that the application can only communicate with the local companion or its own origin, preventing compromised dependencies from exfiltrating data to unauthorized third-party servers.
11. Streaming generation, backpressure, cancellation, and response ownership
Model inference is a computationally intensive, long-running process that generates text sequentially. Standard unary HTTP requests are fundamentally unsuited for this interaction model. The protocol dictates the use of Server-Sent Events (SSE) operating over HTTP/1.1 chunked transfer encoding, providing a robust, unidirectional stream from the companion to the browser. Effective streaming requires sophisticated backpressure mechanisms to prevent the companion from overwhelming the browser's DOM rendering pipeline. The protocol achieves this organically through OS-level TCP flow control. The companion utilizes asynchronous I/O abstractions (such as System.IO.Pipelines in .NET or equivalent async streams in Rust) to write data to the socket38. If the browser struggles to process the incoming text deltas, the operating system's TCP receive window fills up. This backpressure propagates natively up the networking stack to the companion's application layer, causing the write operations to block and seamlessly pausing the underlying LLM inference loop until the browser recovers. Each event within the SSE stream includes a generation\_id and a strictly monotonic sequence integer alongside the token delta. The browser tracks this sequence to detect dropped frames or stream corruption. The protocol also enforces single-ownership of the response rendering path; to prevent race conditions where multiple browser tabs attempt to append text to the same UI component, generation requests are uniquely bound to the specific invoking tab, and the actual prompt hash remains local to the companion, never echoing back across the loopback interface. Cancellation is a first-class requirement to ensure optimal resource utilization. The browser leverages the native AbortController API to terminate the fetch() stream. The companion monitors the socket for closure (TCP FIN or RST packets) and interprets this as an immediate cancellation signal, aborting the active inference thread and forcefully reclaiming RAM and VRAM. A secondary, explicit cancellation route (POST /v1/generate/{id}/cancel) is provided as a fallback to clear stale state in the event of unpredictable network stack behavior.
12. Model import, storage, privacy, and P2P status separation
The mechanism by which the companion ingests model artifacts dictates the security posture of the execution environment. Historically, machine learning frameworks relied on Python's pickle serialization format (e.g., .pkl, .pt), which reconstructs arbitrary Python objects during deserialization. Loading an untrusted pickle file constitutes a Remote Code Execution (RCE) vulnerability, allowing attackers to compromise the host system immediately upon import15. To neutralize this threat, the protocol strictly limits imports to the .safetensors format. Developed specifically to address the security flaws of legacy serialization, the safetensors format decouples metadata from binary storage. It utilizes a flat JSON header to describe the model architecture, followed by a raw byte buffer containing the tensor data. Crucially, this structure permits zero-copy memory mapping (mmap), allowing the companion to load massive language models directly into memory or VRAM without invoking any code execution primitives32. During the import phase (POST /v1/models/import), the companion performs aggressive structural validation. It parses the initial 8-byte little-endian length integer, explicitly rejecting headers larger than a predefined threshold (e.g., 100MB) to prevent memory exhaustion Denial of Service (DoS) attacks15. It then validates the JSON metadata, ensuring that all data\_offsets point strictly to locations within the file's physical boundaries15. If any structural anomaly is detected, the file is immediately quarantined and deleted. To preserve user privacy, the browser never transmits absolute local file paths (e.g., C:\\Users\\Name\\Downloads\\model.slm) to the companion, preventing directory traversal or information disclosure. Instead, the user employs the browser's native file picker, and the browser streams the raw file bytes over the loopback interface, which the companion writes to a sandboxed internal storage directory. Furthermore, the protocol rigorously separates local loopback API health from external Peer-to-Peer (P2P) reachability. The /v1/health endpoint reflects only the readiness of the local API. The status of the WebRTC DTLS-SRTP connections utilized for direct model transfer41 is sequestered behind the authenticated /v1/p2p/status route. This route returns abstract status enumerations (e.g., active\_peers) and never exposes cryptographic P2P signing keys, SDP offers, or IP addresses to the browser, ensuring the web context cannot manipulate the companion's presence on the wider network.
13. Windows/Linux service lifecycle and update security
The operational lifecycle of the companion must ensure high availability for local inference while adhering to the principle of least privilege. The companion is explicitly designed to operate as a per-user background service rather than a system-wide daemon, isolating its execution context and file system access to the specific logged-in user. On Linux architectures, the service lifecycle is governed by systemd \--user. This mechanism allows the companion to be installed without root privileges42. The protocol leverages systemd socket activation, where the operating system creates the listening socket (.socket unit) during boot and holds it open44. The companion process (.service unit) is only launched when the browser initiates the first HTTP connection44. This lazy-startup architecture guarantees zero idle resource consumption until explicitly invoked by the user, while ensuring that the TCP handshake is never dropped during the spin-up phase44. On Windows platforms, the companion executes as a background task governed by the Task Scheduler or a localized service wrapper, deeply integrated with the DPAPI vault mechanisms described previously. Updates to the companion binary require stringent downgrade defenses. The protocol dialect is inherently tied to the cryptographic signature of the distribution package (e.g., Authenticode on Windows). Because the product is pre-publication, the update strategy avoids maintaining vulnerable legacy endpoints for compatibility. Instead, protocol upgrades necessitate a coordinated replacement of the binary. If the browser detects an unsupported schema version, it directs the user to install the updated package. Upon upgrade, the companion migrates necessary receipts and immediately drops all legacy routing logic, presenting a consistently minimized attack surface.
14. Adversarial, package, browser, and restart test matrix
The resilience of the protocol is guaranteed through continuous, automated adversarial testing. The CI/CD pipeline must include a dedicated test harness that simulates hostile browser behavior and degraded network states to verify the deterministic enforcement of security boundaries.
| Threat Scenario | Simulated Test Action | Expected Deterministic Companion Behavior |
|---|---|---|
| DNS Rebinding | Initiate an HTTP request to 127.0.0.1 but explicitly forge the header to Host: attacker.com | Immediate termination of the TCP socket at the parser level; no HTTP error response returned. |
| Origin Forgery | Transmit an OPTIONS LNA preflight containing Origin: https://malicious.site.com | Return 403 Forbidden or drop request; no Access-Control-Allow-Origin header emitted. |
| Port Squatting | Execute a dummy Python script binding to 51042, then launch the companion. | Companion detects EADDRINUSE, utilizes SO\_EXCLUSIVEADDRUSE, and successfully binds to 51043 without crashing13. |
| Replay Attack | Intercept a valid signed request and retransmit it with the identical nonce and timestamp. | Return 401 Unauthorized; the nonce is identified within the companion's LRU cache11. |
| Temporal Skew | Transmit a valid signature where the created parameter is mathematically 6 minutes in the past. | Return 401 Unauthorized; violates the strict 5-minute clock-skew tolerance policy11. |
| Missing Signature | Submit a standard fetch() POST lacking the Signature-Input and Signature headers. | Return 401 Unauthorized; request rejected prior to routing. |
| Corrupted Safetensors | Stream a .safetensors payload where data\_offsets mathematically exceed the total file size. | Return 400 Bad Request; file immediately quarantined and purged from disk15. |
| Cancellation Race | Trigger AbortController on an active SSE stream and immediately fire a new generation request. | Original stream terminates gracefully; VRAM allocations are freed; subsequent stream initializes cleanly. |
15. Public-safe receipts and secret-scanning contract
To prevent accidental data leakage, the protocol establishes a strict redaction contract for all information exiting the companion's boundary. This encompasses HTTP error responses returned to the browser, OS event logs, crash dumps, and public receipts utilized in P2P coordination. Public receipts, which serve to validate successful model transfers or local execution metrics, are structurally constrained to contain only non-sensitive mathematical representations. They may include cryptographic hashes of prompts, SHA-256 digests of model binaries, token counts, and timestamps. The inclusion of plaintext prompts, absolute file system paths, user identity strings, or raw IP addresses within the receipt schema is explicitly prohibited. The development lifecycle enforces this contract through automated secret scanning. The build pipeline continuously monitors traces, logs, and generated artifacts for high-entropy strings, Ed25519 key patterns, and DPAPI vault signatures. Furthermore, the error schemas returned via the HTTP API are heavily bounded. If a file system operation fails during model import, the companion returns a generic, sanitized error object (e.g., {"error": "storage\_access\_denied", "code": 403}) rather than emitting a raw OS stack trace that could reveal the user's local directory structure or username to the browser console.
16. TDD backlog and clean protocol cutover
The implementation of the protocol must follow a Test-Driven Development (TDD) methodology, ensuring that security boundaries are demonstrably enforced before functional logic is integrated. The deployment is phased to construct the foundation systematically. Phase 1: Transport and Parsing Foundation The initial iteration implements the HTTP/1.1 server, loopback binding utilizing SO\_EXCLUSIVEADDRUSE, and the strict Host header validation parser. Tests must aggressively simulate DNS rebinding and hostile CORS origins, verifying that only requests bearing targetAddressSpace: "loopback" from the exact https://tinyrustlm.com origin are acknowledged. Phase 2: Cryptographic Identity and Authentication Development shifts to the pairing protocol. Implementation covers Ed25519 key generation, DPAPI/libsecret storage mechanics, and the RFC 9421 HTTP Message Signatures verification engine. The test harness must exhaustively validate the anti-replay LRU caches and clock-skew failures. Phase 3: Core Idempotent Logic and Safe Import Functional endpoints for /v1/models inventory and the .safetensors structural parser are introduced. Testing requires the ingestion of known-valid models alongside intentionally corrupted or maliciously crafted .safetensors headers to guarantee the quarantine logic functions correctly. Phase 4: Streaming, Backpressure, and Teardown The implementation of the SSE /v1/generate endpoint. Extensive testing focuses on the propagation of TCP backpressure from the browser up to the inference loop, and verifying that AbortController cancellations accurately trigger the deallocation of VRAM within the Rust/.NET engine. Phase 5: Eradication and Publication Cutover Prior to publication, a mandatory eradication phase removes all unpublished routes, legacy code, and permissive compatibility tokens. A strict stop-rule is enforced: the continuous integration build will fail if any deprecated route is accessible or if a dual-transport fallback (e.g., an insecure WebSocket attempt) is detected.
17. Unknowns requiring private code, packaging, or live network access
Several environmental variables require live verification outside the theoretical model, necessitating testing against the specific packaged binary and its operational context.
1. EDR and Antivirus Heuristics: The behavior of the companion—specifically binding to 127.0.0.1 utilizing SO\_EXCLUSIVEADDRUSE and operating a localized HTTP server—may trigger false positives in aggressive Endpoint Detection and Response (EDR) solutions. Verification requires executing the signed binary against enterprise security stacks to ensure it is not erroneously quarantined.
2. OS Memory Paging: While the .safetensors format ensures zero-copy mmap loading39, it must be empirically verified that the host operating system does not inadvertently page sensitive P2P keys or active LLM context windows into unencrypted swap or pagefiles. OS-level memory locking (e.g., mlock on Linux, VirtualLock on Windows) may be necessary to guarantee absolute confidentiality of the active context.
3. Edge Browser Mixed-Content Deviations: While the Local Network Access specification explicitly permits the targetAddressSpace: "loopback" annotation to bypass mixed-content blocks in Chromium3, the exact user experience in browsers with differing implementation timelines (such as Firefox or Safari) requires live cross-browser testing. Should an edge browser lack LNA support, the protocol must ensure failures are handled gracefully without degrading to insecure practices.
18. Annotated primary-source bibliography with direct links and dates
| Primary Source & Specification | Retrieval Context & Relevance | Link & Temporal Data |
|---|---|---|
| W3C Local Network Access (Draft) | Defines the modern security boundary for loopback requests. Explicitly establishes the local and loopback address spaces and the targetAddressSpace fetch parameter required to bypass mixed-content blocking safely3. | https://wicg.github.io/local-network-access/ (Drafts spanning 2024-2026). |
| IETF RFC 9421: HTTP Message Signatures | The normative standard for canonicalizing and signing HTTP components. Provides the cryptographic mechanism (@method, @target-uri, content-digest) to replace vulnerable bearer tokens11. | https://datatracker.ietf.org/doc/html/rfc9421 (Published Feb 2024). |
| W3C Secure Contexts (CR) | Establishes the foundational rule that 127.0.0.0/8 and ::1/128 are considered a priori authenticated, justifying the architectural decision to utilize plaintext HTTP on the local link without compromising modern web capabilities1. | https://www.w3.org/TR/secure-contexts/ (Recommendation track). |
| Microsoft DPAPI (CryptProtectData) | The definitive API for securing credentials on Windows. The documentation verifies that using CRYPTPROTECT\_LOCAL\_MACHINE (or user defaults) binds encrypted payloads securely to the host and user session, ensuring persistent storage of P2P keys14. | https://learn.microsoft.com/en-us/windows/win32/api/dpapi/nf-dpapi-cryptprotectdata |
| Safetensors Format Specification | Details the decoupled JSON header and raw byte buffer architecture. Validates the capability for zero-copy memory mapping (mmap) while mathematically preventing the arbitrary code execution risks associated with Python pickle32. | https://github.com/huggingface/safetensors |
Works cited
1. Secure Contexts \- W3C, https://www.w3.org/TR/2016/CR-secure-contexts-20160915/
2. content/files/en-us/web/security/defenses/secure\_contexts/index.md at main \- GitHub, https://github.com/mdn/content/blob/main/files/en-us/web/security/defenses/secure\_contexts/index.md?plain=1
3. Request: targetAddressSpace property \- Web APIs \- MDN Web Docs, https://developer.mozilla.org/en-US/docs/Web/API/Request/targetAddressSpace
4. Local network access \- Security \- MDN Web Docs \- Mozilla, https://developer.mozilla.org/en-US/docs/Web/Security/Defenses/Local\_network\_access
5. WebSocket \- Wikipedia, https://en.wikipedia.org/wiki/WebSocket
6. Cross-Site WebSocket Hijacking (CSWSH) · Advisory · f/textream \- GitHub, https://github.com/f/textream/security/advisories/GHSA-wr3v-x247-337w
7. Local network access restrictions \- Chrome Platform Status, https://chromestatus.com/feature/5152728072060928
8. Apply Local Network Access permission to WebSocket connections \[421156866\] \- Chromium Issue, https://issues.chromium.org/issues/421156866
9. WebTransport: Browser Support, Features, Use Cases \- TestMu AI, https://www.testmuai.com/learning-hub/webtransport-browser-support/
10. State of DNS rebinding in 2023 \- APNIC Blog, https://blog.apnic.net/2023/06/27/state-of-dns-rebinding-in-2023/
11. Understanding HTTP Message Signatures \- Blog Notes, https://blog.vitalvas.com/post/2025/12/12/understanding-http-message-signatures/
12. ERC-8128: Signed HTTP Requests with Ethereum \- EIP.tools, https://eip.tools/eip/8128
13. Using SO\_REUSEADDR and SO\_EXCLUSIVEADDRUSE \- Win32 apps | Microsoft Learn, https://learn.microsoft.com/en-us/windows/win32/winsock/using-so-reuseaddr-and-so-exclusiveaddruse
14. CryptUnprotectData function (dpapi.h) \- Win32 apps | Microsoft Learn, https://learn.microsoft.com/en-us/windows/win32/api/dpapi/nf-dpapi-cryptunprotectdata
15. ModelAudit Scanners | Promptfoo, https://www.promptfoo.dev/docs/model-audit/scanners/
16. AI Models RCE \- HackTricks, https://hacktricks.wiki/en/AI/AI-Models-RCE.html
17. Private Network Access \- GitHub Pages, https://wicg.github.io/private-network-access/
18. local-network-access/explainer.md at main \- GitHub, https://github.com/WICG/local-network-access/blob/main/explainer.md
19. Private Network Access: introducing preflights | Blog \- Chrome for Developers, https://developer.chrome.com/blog/private-network-access-preflight
20. Use case for WebSocket communications · Issue \#16 · WICG/local-network-access \- GitHub, https://github.com/WICG/local-network-access/issues/16
21. v3 rewrite · Issue \#371 · m1k1o/neko \- GitHub, https://github.com/m1k1o/neko/issues/371
22. Making your website "cross-origin isolated" using COOP and COEP | Articles \- web.dev, https://web.dev/articles/coop-coep
23. Flutter \+ WASM \+ Google Auth \+ Production \= Headache (SOLVED) | by Leland Reardon, https://medium.com/@leland6925/flutter-wasm-google-auth-production-headache-e7346af926d5
24. Cross-Origin-Opener-Policy (COOP) header \- HTTP \- MDN Web Docs, https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Cross-Origin-Opener-Policy
25. Cross-Origin-Embedder-Policy (COEP) header \- HTTP \- MDN Web Docs, https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Cross-Origin-Embedder-Policy
26. Windows Network Services Internals: Jean-Baptiste Marchand | PDF \- Scribd, https://www.scribd.com/document/544744339/win-net-srv
27. Drop usage of SO\_EXCLUSIVEADDRUSE on Windows · Issue \#928 · python-trio/trio, https://github.com/python-trio/trio/issues/928
28. UDP Sockets Programming \- MYcsvtu Notes, https://mycsvtunotes.weebly.com/uploads/1/0/1/7/10174835/network\_programming\_2.pdf
29. delphi \- Secure way to store password in Windows \- Stack Overflow, https://stackoverflow.com/questions/13145112/secure-way-to-store-password-in-windows
30. DPAPI \- Extracting Passwords \- HackTricks \- GitBook, https://angelica.gitbook.io/hacktricks/windows-hardening/windows-local-privilege-escalation/dpapi-extracting-passwords
31. Libsecret — data structures in Rust // Lib.rs, https://lib.rs/crates/libsecret
32. GitHub \- safetensors/safetensors: Simple, safe way to store and distribute tensors, https://github.com/safetensors/safetensors
33. RFC 9421 \- HTTP Message Signatures \- IETF Datatracker, https://datatracker.ietf.org/doc/html/rfc9421
34. AdCP — Request Signing Guide, https://docs.adcontextprotocol.org/docs/building/by-layer/L1/request-signing
35. Cross-Origin Resource Sharing (CORS) explained \- HTTP.DEV, https://http.dev/cors
36. Access-Control-Max-Age header \- HTTP \- MDN Web Docs, https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Access-Control-Max-Age
37. CORS Access-Control-Max-Age is ignored \- Stack Overflow, https://stackoverflow.com/questions/23543719/cors-access-control-max-age-is-ignored
38. transports.md \- modelcontextprotocol/csharp-sdk \- GitHub, https://github.com/modelcontextprotocol/csharp-sdk/blob/main/docs/concepts/transports/transports.md
39. Securing LLM Supply Chains: Model Serialization Attacks and Safe Formats (Safetensors), https://www.shyankdev.us/blogs/securing-llm-supply-chains-safetensors
40. CryptoTensors: A Light-Weight Large Language Model File Format for Highly-Secure Model Distribution \- arXiv, https://arxiv.org/pdf/2512.04580
41. WebRTC Security in 2026: Plain-Language Guide to E2EE, HIPAA, GDPR & Common Attacks \- Fora Soft, https://www.forasoft.com/blog/article/webrtc-security-in-plain-language-495
42. systemd \- Freedesktop.org, https://www.freedesktop.org/software/systemd/man/systemd.html
43. Introduction to systemd Basics | SUSE Linux Enterprise Server for SAP applications 16.0, https://documentation.suse.com/sles-sap/16.0/html/SAP-systemd-basics/index.html
44. systemd Socket Activation and User Services \- ServerCake, https://servercake.in/guides/systemd-deep-dive/sd-socket-activation-and-user-services
45. Chapter 10\. Managing Services with systemd | System Administrator's Guide | Red Hat Enterprise Linux | 7, https://docs.redhat.com/en/documentation/red\_hat\_enterprise\_linux/7/html/system\_administrators\_guide/chap-managing\_services\_with\_systemd
46. Systemd Deep Dive Best Practices for Enterprise Linux \- Medium, https://linuxgd.medium.com/systemd-deep-dive-best-practices-for-enterprise-linux-18a832c4310a
47. Local Network Access \- GitHub Pages, https://wicg.github.io/local-network-access/