Site security blueprint

Step 1: 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 explicit Kernel caller admission and pinned Worker keys for topic discovery. Knowing a topic or a listener key does not grant access: unlisted callers are rejected unless allowAll is enabled.

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

Step 2: Admit the Gateway to Kernel

auth.whitelist defaults to [], which admits nobody before startup helpers add keys. Kernel then checks each admitted caller's role on every request; the Kernel role reference lists the actions each of read, write and admin permits. A plain key or kernel.allowKey(key) without roles grants admin.

Options

Suggested default: admit only the persistent backend caller keys the site needs, with explicit roles. Disable automatic directory admission when enforcing that list. Gateway clients, app runtimes, and MCP clients may each use separate keys.

Start a programmatic host with explicit admission and directory-based admission disabled:

const kernel = await getKernel({
  trustedKeysDir: false,
  hrpc: {
    whitelist: [{ key: '<caller-public-key-hex>', roles: ['read'] }]
  }
})

Choose roles per backend caller, widen a caller to write only when it needs to change devices. Gateway clients use the persistent status.rpcClientKey from the Gateway handle or status file. An app runtime uses its own Kernel caller key, so admitting a Gateway key does not grant an app runtime access. Treat each store containing identity seeds as a private key: copying it can allow impersonation.

Automatic admission during startup

Inspect the startup admission helpers before relying on a restricted allowlist. The trusted-keys directory stores public keys, but publishing a key there is an authorization action for the processes watching it.

getKernel() uses <root>/.trusted-keys by default. The CLI supplies its project-local directory; supervised Workers use DEFAULT_TRUSTED_KEYS_DIR (~/.mdk/.trusted-keys). Grant directory write access only to processes you trust to grant backend access. Filesystem protections restrict who can publish a key; they do not assign that key a narrower role.

For explicit Kernel roles, use trustedKeysDir: false on getKernel(). To avoid the additional in-process grant, start the Gateway with kernelKey rather than the live kernel handle, disable its directory publishing with trustedKeysDir: false, and admit its caller key explicitly. Passing trustedKeysDir: false only to startGateway({ kernel }) does not prevent its full-access grant. Manage MCP and app runtime keys explicitly as well.

The standalone MCP server (mdk run mcp) is a separate Kernel caller with its own persistent key. mdk run publishes it to the trusted-keys dir; on a multi-host site add it to auth.whitelist alongside the Gateway, or its tools can't reach Kernel.

Each app runtime is a Kernel caller too, with its own persistent key: mdk run publishes it as app-<name>.pub in the trusted-keys dir, next to kernel.pub, gateway.pub, mcp.pub and cli.pub. The directory watcher admits valid caller keys with full access, excluding Kernel's own client key. An app's permissions in mdk-app.yaml are not enforced by Kernel yet, so review an app before you add it to a stack.

Worker discovery admission

The list of Workers a Kernel may discover is separate from the list of clients allowed to call Kernel. For DHT-topic discovery, only Worker RPC keys on discovery.workerKeys (or added with kernel.allowWorkerKey()) register, and an empty list admits nobody. discovery.allowAnyWorker: true admits every peer that knows the topic; like allowAll, it is for throwaway local experiments only and logs a warning. With it, a peer with the topic could register as a Worker and receive the commands, including credentials, for its device family.

Local shared-directory discovery and explicit kernel.registerWorker() skip that topic allowlist. Control who can publish Worker keys or call registration; adding discovery.workerKeys does not restrict those paths.

On separate hosts, pass Kernel's public key to the Gateway as kernelKey. Do not rely on the well-known key file (~/.mdk/.kernel-key) across machines. Where that file still exists on the Kernel host, it holds the public key, written world-readable (0644) inside a directory you own; it is not deleted on shutdown. Do not expose Kernel's HRPC listener off the backend network.

Step 3: Isolate Workers and devices

WorkerRuntime rejects unlisted caller keys at connection time and checks the key again on every request. With allowAll disabled, it refuses to start with an empty allowedKeys list. This is a key-based firewall, not a list of allowed server addresses. An admitted key can send any request the Worker supports, including command.request; the list has no read-only role.

Choose which request paths the site allows:

The direct Worker client, sendWorkerCommand() and pullWorkerTelemetry() use the second path. Resolving a Worker's public key through Kernel does not make the following Worker call Kernel-mediated. The caller still needs a key admitted by that Worker. This is separately granted access, not a way around the Worker's firewall.

For example, a monitoring script admitted to Kernel as read cannot send a command through Kernel. If its key is also on a Worker's allowlist, the same script can send supported commands directly to that Worker. To keep it read-only, restrict both paths.

For a site that requires all device requests to pass through Kernel, set each Worker's allowedKeys to only kernel.getClientPublicKey(), not Kernel's listener key from getPublicKey(). Do not add the Gateway, MCP, app runtime, or script key to that list. If the site deliberately needs direct provisioning or Worker queries, admit the required caller explicitly and treat it as able to issue supported commands too.

Keep the Worker firewall enabled and isolate the network as an additional control. Security boundaries explain the distinction between endpoint identity, key admission, and user authentication.

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.

Step 4: Put identity in the Gateway

The Gateway is the only supported user-auth seam. Pass startGateway() an authVerifier(request, route) backed by your identity layer: routes a manifest marks "auth": true answer 401 unless it returns an identity, which controllers read as req._info. Routes without "auth": true are served to any caller. Paths under /auth/metrics/* are historical names, not a login gate.

Options

Suggested default: one authVerifier for the whole Gateway, and "auth": true on every route that reads or changes the fleet. Map verified roles onto Kernel authPerms (miner:w, container:w, and any others you define). Never accept authPerms or voter from the HTTP client. Return false for a missing or bad token (401) and throw a 403 ERR_* error for a missing permission.

// The verifier does the check; the Gateway apps guide owns the full example.
authVerifier: async (request, route) => {
  const identity = await verify(request.headers.authorization)
  if (!identity) return false
  if (!(route.permissions || []).every(p => identity.perms.includes(p))) {
    throw Object.assign(new Error('ERR_AUTH_PERM_DENIED'), { statusCode: 403 })
  }
  return identity
}

The Gateway apps guide owns this pattern. Also:

• Bind HTTP to the proxy network, not a public interface without that proxy
• List the names clients use in allowedHosts; only loopback on the bound port passes the Host check by default
• Tune rateLimit for writes. ?overwriteCache=true is honored only for an identity whose perms holds cache:overwrite
• trustProxy is off by default. Turn it on only behind a proxy whose hop count you trust, or client IPs (and so rate limits) 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

Step 5: Authorize writes

Kernel distinguishes a command sent to Kernel (command.request) from an approval-gated action (action.push and votes). Both require a Kernel caller role of write or admin. A command sent directly to a Worker is a third path with only the Worker checks described in Step 3. Choose the path per action and enforce that choice at every entry point you admit.

Kernel's role check authorizes the backend process, not the person behind an HTTP request. For commands sent to Kernel, the Gateway or app controller must authorize that person. Approval-gated writes also check authPerms, but the admitted caller supplies that array; derive it from verified identity. Non-admin callers vote as their transport key; an admin caller may forward a user's voter identity. Grant that delegation only to a process trusted to authenticate those users.

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.

Step 6: 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 mvp-site example UI has no sign-in, no session, and a hardcoded profile. Do not copy that into a reachable host.

Step 7: (Optional) MCP and the operator agent

MCP is optional. When you enable it, it has the same authority as the process that hosts it. The standalone @tetherto/mdk-mcp process binds 127.0.0.1 and answers POST /mcp with no user auth by default; an optional bearer token gates every call. The Gateway hosts no MCP itself.

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.

Step 8: Handle secrets, stores, and day-two operations

Options for secrets

Options for process lifecycle

Suggested default:

• Mode 0700 (or equivalent) on the Kernel db directory and Worker storeDir, and 0600 on seed 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 keys when access changes, and update every callee that admits them, including direct Worker grants
• 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

Revoke access on every admitted path

Trusted-directory watchers add keys; deleting a .pub file does not revoke its grants in running processes. Use kernel.revokeKey(key) and each affected runtime.revokeKey(key), and remove the publication and startup configuration that would grant it again. With allowAll enabled, removing an allowlist entry does not deny that caller; disable allowAll as well.

trustKernel() mirrors explicit Kernel revocations to attached Workers, but changing a Kernel role from write to read does not remove an existing Worker grant. A directory watcher does not mirror Kernel role changes or revocations. Check the live Kernel roles and Worker allowlists, not just files on disk, and verify that denied calls fail after revocation and after restart.