Site security blueprint

Choose a network layout

Pick a deployment topology before you write auth code. Isolation is the first control; identity sits on top of it.

Options

Suggested default: microservices (one process or container per service, discovery over DHT), with three networks you define:

• Operator: UI origin and Gateway HTTP, behind TLS and a reverse proxy you control
• Backend: Kernel and Workers on separate hosts, no inbound path from browsers or agents
• Devices: miner, container, meter, and pool APIs, reachable only from the Workers that own them

Pass the Kernel public key to a remote Gateway as kernelKey. Treat the DHT discovery topic as deployment configuration, not a credential: generate a site-specific topic, distribute it out of band, and do not reuse example or well-known values. Pair this shape with a non-empty Kernel allowlist in the next step. Without that allowlist, DHT makes Kernel reachable to any peer that has the topic and the listener key.

Do not pass @tetherto/mdk-client or Kernel keys into the browser. HTTP to the Gateway is the only operator path.

Admit only the Gateway to Kernel

Pre v1.0, auth.whitelist defaults to [] and admits any HRPC caller that knows Kernel's public key. A production Kernel always has a non-empty allowlist.

Options

Suggested default: one persistent Gateway key pair, that hex public key only, on Kernel:

const kernel = await getKernel({
  hrpc: { whitelist: ['<gateway-dht-public-key-hex>'] }
})

The auth-whitelist example shows the exchange. Generate the Gateway key once, store it with the same care as a TLS key, and put it on the allowlist. Do not generate a fresh key at each boot: the Gateway does not yet pass a persistent caller seed, so re-check the published Gateway key after a bounce.

On separate hosts, pass Kernel's public key to the Gateway as kernelKey. Do not rely on the well-known key file (<tmpdir>/mdk/.kernel-key) across machines. Where that file still exists on the Kernel host, keep it mode 0600 on a directory you own; it is not deleted on shutdown. Do not expose Kernel's HRPC listener off the backend network.

Isolate Workers and devices

WorkerRuntime does not enforce a caller allowlist. Any backend peer that can reach a Worker and address its public key may send command.request. Kernel's allowlist does not protect a Worker that is dialed directly.

Options

Suggested default: persist each Worker's storeDir so its key is stable, treat that key as a machine identity, and register the Worker with Kernel only after the device network is isolated. On DHT, keep Worker public keys and the discovery topic off the operator network and out of git. Inject device passwords and pool API keys from a secret manager or protected environment. Never put secrets in mdk-contract.json, git, or a committed seed file.

Validate command payloads again in the handler (types, ranges, allowed targets). Kernel checks the command name against the contract; it does not know your hardware's unsafe parameter combinations. Redact credentials and vendor responses in handler errors and logs. For CGMiner-style devices, network isolation is the control: changing the Worker password field does not add a wire handshake the protocol lacks.

Put identity in Gateway controllers

The Gateway is the only supported user-auth seam. Every bundled plugin is served to any caller. Paths under /auth/metrics/* are historical names, not a login gate. Manifest "auth": true changes nothing.

Do not mount @tetherto/mdk-plugin-auth expecting it to work. The Gateway does not register it, and its controllers still expect ctx.authLib, a services argument, and req._info.user, which the current host does not provide.

Options

Suggested default: one identity helper shared by every controller. Map verified roles onto Kernel authPerms (miner:w, container:w, and any others you define). Never accept authPerms or voter from the HTTP client. Reject missing tokens with 401 and missing perms with 403, setting err.statusCode so the Gateway does not collapse them to 400.

const { validateToken } = require('../lib/my-identity-layer')

module.exports = async function protectedRoute (req) {
  const token = req.headers.authorization?.replace('Bearer ', '')
  if (!token) throw Object.assign(new Error('ERR_UNAUTHORIZED'), { statusCode: 401 })

  const { permissions, email } = validateToken(token)
  if (!permissions.includes('miner:w')) {
    throw Object.assign(new Error('ERR_FORBIDDEN'), { statusCode: 403 })
  }

  // Pass email and permissions into Kernel yourself. Do not take them from req.body.
}

The Gateway plugins guide owns this pattern. Also:

• Bind HTTP to the proxy network, not a public interface without that proxy
• Rate-limit writes. ?overwriteCache=true bypasses the request cache with no auth: ignore it for anonymous callers, or strip it in your adapter
• The HTTP worker sets trustProxy: true. Only do that behind a proxy whose hop count you trust, or client IPs can be spoofed
• Log actor, route, target, command, outcome, and a correlation id for every write. Redact secrets. Worker handlers cannot see actor identity, so this audit stays in the Gateway

Authorize writes

Kernel treats two write paths differently. Choose per action, then enforce the choice in the Gateway. Direct command.request has no Kernel-side permission check. Approval-gated writes read authPerms, but that array is caller-supplied once the HRPC connection is accepted.

Options

Suggested default: approval-gated writes for anything that changes hash, power, or network membership; direct commands only behind a controller that already checked a token. Do not expose a raw sendCommand route to the UI without that check.

Wire the UI session

<MdkProvider auth={...}> is how the browser attaches a credential. The toolkit does not guard routes or deny writes on its own.

Options

Suggested default for a production dashboard:

• <MdkProvider apiBaseUrl={httpsOrigin} auth={bearerTokenAuth()}> or gatewayRedirectAuth({ oauthBaseUrl }) after those routes exist
• HTTPS, a real apiBaseUrl, no Vite dev proxy
• One fetch client so pages cannot skip Authorization
• Route guards on any view that can mutate the fleet (the shell template uses <RequireAuth>; copy that idea, not noAuth())
• Hide write controls unless the token carries the matching permission. Hiding is not authorization; the Gateway still denies
• Scrub ?authToken= from the URL after capture. Tokens in query strings leak through access logs and Referer
• Static bundle behind the same proxy that terminates TLS. Do not run vite dev as the production UI

The full-site example UI has no sign-in, no session, and a hardcoded profile. Do not copy that into a reachable host.

Decide about MCP and the operator agent

MCP is optional. When you enable it, it has the same authority as the process that hosts it. Standalone @tetherto/mdk-mcp and the Gateway's auto-generated server both bind 127.0.0.1 and answer POST /mcp with no user auth. Auto-generated MCP defaults to Gateway port plus 100.

Options

Suggested default: leave MCP on 127.0.0.1. Do not publish it with compose ports:, an SSH tunnel, or a reverse proxy unless that front door is authenticated. Treat the model provider (qvac or an OpenAI-compatible URL) as sensitive infrastructure: prompts can include site topology and, if you are careless, secrets.

Handle secrets, stores, and day-two operations

Options for secrets

Options for process lifecycle

Suggested default:

• Mode 0600 (or equivalent) on Kernel db, Worker storeDir, and key files. Encrypt at rest if the host requires it
• Back up those directories as operational data, with the same access control as the live files
• Rotate Kernel, Gateway, and Worker keys when staff leave or a host is rebuilt, and update the allowlist in the same change
• Practice recovery from a wiped data directory before an incident
• Watch Gateway-to-Kernel errors, not only the HTTP port
• Run Node.js >=24. Pin lockfiles. Prefer non-root containers with a read-only root filesystem
• Stay on the latest main or latest tag you have reviewed. 0.y.z is initial development; older tags may not receive security fixes. Report product issues through the security policy, not public GitHub issues