Security boundaries

TL;DR

• User identity. MDK does not identify users for you. Your site supplies user authentication; Gateway routes that do not require it remain open to anyone who can reach them.
• Backend access. Kernel and Workers check backend keys, not human identity. Kernel roles apply to calls through Kernel; direct Worker access is a separate permission without read/write roles.
• Site controls. Your site owns network access, process isolation, and key permissions, including permissions granted automatically during startup.

Overview

This page describes the trust boundary at the Worker tier in depth and where it sits in the Worker → Kernel → Gateway → UI chain. Data flows outward along that chain; a request travels the other way, entering at the Gateway (or, for AI agents, the standalone MCP server). It covers what each layer does and does not authenticate.

Worker security boundary

Endpoint identity and key material

WorkerRuntime listens over HyperswarmRPC (HRPC) on an encrypted Noise transport, and its HRPC public key identifies and addresses the endpoint. That proves which endpoint a backend peer is talking to: it does not establish a human or application identity, grant command permission, or substitute for the application-level authentication you implement above it.

A Worker's identity is a pair of seeds, seedDht and seedRpc, from which its DHT and HRPC keypairs are derived. With a storeDir, they are written unencrypted as plain files in that directory; with a Hyperbee store, they live unencrypted in the store's workerConf space. Anyone who can read them can regenerate the keypair and impersonate the endpoint. Restrict access to the seeds with the same care as a private key: use restrictive file permissions, at-rest encryption where the host requires it, and treat backups as secrets. A DHT topic is only a discovery rendezvous — not a credential or an authorization token.

Reachability and network controls

The WorkerRuntime enforces a caller allowlist at connection time and on every request. Unless allowAll is enabled, unlisted keys are rejected and an empty list prevents startup. The list has no roles: an admitted key can send any request the Worker supports, including commands. A public key addresses a Worker; it does not grant a caller admission.

The Kernel's HRPC allowlist and roles apply to requests sent to Kernel. Direct Worker clients pass the Worker's own allowlist instead; Kernel's command controls do not run on that path. A site that requires Kernel-mediated access admits only Kernel's client key on Workers and avoids startup helpers that add other callers. Granting direct access to another process is a separate authorization decision, not a firewall bypass. User-facing Gateway and MCP entry points still need their own authentication and authorization.

In addition to caller admission, the surrounding controls are yours:

• Restrict direct Worker reachability to trusted backend networks, and apply a host/container firewall policy
• Never expose device management interfaces publicly
• Treat Worker public keys and DHT topics as deployment configuration, distributed through an authenticated control plane
• Run Kernel, Workers, and Gateway as separate processes or containers, so a compromise of one is contained and cannot spread to the others

Production command path and secrets

A host that starts a Worker with services: null — the minimal setup — provides no first-party service built-ins and no write.calls.request approval integration (MDK's built-in write-approval flow). Direct command.request dispatch still reaches plugin command handlers regardless, so a production command path must:

• Authenticate the requester at the Gateway or control plane
• Authorize each device and command, and optionally require approval for high-impact actions
• Validate the request again in the handler, and rate-limit it
• Write an audit record with actor, target, requested parameters, outcome, and correlation ID

The handler context does not currently include actor identity, so actor-level auditing belongs upstream, with handler logs to supplement it. The control-plane security model covers the production trust path.

Inject credentials through the host process from a secret manager or protected environment. Pass only the minimum device-specific values in config, and never place secrets in mdk-contract.json. Redact credentials and device responses from errors, debug logs, telemetry, and audit records.

Next steps

• Follow the site security blueprint: steps, options, and suggested defaults for a real site
• Understand the Gateway's security model: where user identity checks are meant to live
• Review the control-plane security model: the production trust path for approval-gated writes
• Read the Worker Runtime store services reference: the full built-in surface opts.services can activate