Site security blueprint

Step 1: Choose a network layout

Pick a deployment topology before you write policy. Isolation is the first control; identity and policy sit 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, app runtimes, MCP server and Workers, 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 Kernel allowlist that names every caller key.

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

Admission decides which keys may connect to Kernel. It is fail-closed (an empty allowlist admits nobody) and it grants nothing: what an admitted caller may do comes from its access token and spec.rbac. There are no allowlist roles. An entry written as { key, roles } is refused at start with ERR_KERNEL_CALLER_ROLES_UNSUPPORTED, and allowAll on the Kernel with ERR_KERNEL_ALLOW_ALL_REMOVED.

Options

Suggested default across hosts: one persistent key per caller, each hex public key on the Kernel's allowlist:

const kernel = await getKernel({
  hrpc: { whitelist: ['<gateway-key-hex>', '<mcp-key-hex>', '<app-runtime-key-hex>'] }
})

The Gateway derives its caller key from a seed persisted in its store, so the key survives restarts: read it from status.rpcClientKey in the Gateway status file. The standalone MCP server (mdk run mcp) and each app runtime have their own persistent keys too; mdk run publishes them to the trusted-keys dir (mcp.pub, app-<name>.pub). Treat each of those stores with the same care as a TLS key, since a copy of it presents that caller's transport identity.

Admission alone gets a caller nowhere. A Gateway or MCP server in its own process also signs in as its service account (mdk-gateway, mdk-mcp) to read the policy it enforces, which needs policy: read; mdk rbac init binds both to a gateway role holding exactly that. Each app runtime signs in as app:<name>. A service account's token is bound to the transport key that signed in, so a copied token is refused from any other key.

Kernel admits Workers from the DHT topic the same way: only 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; it is for throwaway local experiments only and logs a warning. Without it, a peer with the topic could register as a Worker and receive the commands, including credentials, for its device family.

Workers are fail-closed too. Give each Worker the Kernel's client key (kernel.getClientPublicKey(), not the listener key) as its only allowedKeys entry, so every command goes through Kernel's checks and write-command log. Do not add the Gateway's key: an app reaches devices through Kernel, never by dialing a Worker.

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 answers only the keys in its allowedKeys, and mdk run and the @tetherto/mdk-core helpers admit the Kernel's client key and no other. A Worker therefore takes device calls only through Kernel, where spec.rbac and the write-command log apply. The device network is still yours to isolate: a Worker's key protects the Worker, not the miner behind it. Security boundaries give the trust-boundary rationale behind the controls below.

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 and params 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: Write the policy and put identity in the Gateway

spec.rbac in mdk.yaml is the only place policy is written. The Kernel applies it at every start and on mdk rbac apply; a policy that fails validation is refused and the one in force stays. A rule names resources, verbs and, optionally, resourceNames; a binding ties a role to User, Group or ServiceAccount subjects. The RBAC vocabulary lists every resource, including devices (named family/brand/worker/device), actions, commands, policy, identities and app routes (<app>/<path> with get, list, create, update, delete).

A package never decides who may call it. An app only requests its own Kernel access in mdk-app.yaml (permissions, required); mdk add app, mdk create app, mdk onboard and mdk rbac init write that request as role app-<name> bound to service account app:<name>, and the role is yours to narrow from then on. mdk validate app <name> fails when the grant is missing, differs from the request or binds nobody. Who may call the app's routes is set by your own roles.

The Gateway is the user identity seam. It serves POST /auth/login, POST /auth/token, POST /auth/refresh, POST /auth/logout and GET /auth/me from the Kernel's token issuer. A client that keeps no cookies, such as the CLI or a script, sends "refreshIn": "body" at login and gets its refresh token in the body instead, which the Gateway's sign-in routes cover along with the rest of the cookie behavior.

On every app route it checks a bearer access token and a spec.rbac rule for the route's resource and verb (401 ERR_AUTH_UNAUTHORIZED, 403 ERR_AUTH_FORBIDDEN) before body validation, the cache or the app. A route that declares resourceName (from a param, query or body field) is checked for that instance. The app receives the verified identity, { kind, sub, email?, groups? }, as req._info, never the token. The Gateway apps guide covers the route fields.

Options

Suggested default: run mdk rbac init before the first mdk run (a spec.rbac that binds no user and no group, and whose bound subjects include nobody who may write the policy, makes mdk run refuse to boot the Kernel, which could not be handed a policy afterwards), create the first operator with mdk user add <name> --admin, then give everyone else a narrow role bound by group. Read the effective policy with mdk rbac show after every change, and keep mdk.yaml in review like code. Single sign-on federation is not built in: users and passwords live in the Kernel's identity store.

spec:
  rbac:
    enforcement: deny
    roles:
      - name: viewer
        rules:
          - resources: ["*"]
            verbs: [get, list]
      - name: rack3-tech
        rules:
          - resources: [ops-center/miners/command]
            verbs: [create]
            resourceNames: ["rack-3-*"]
    bindings:
      - role: viewer
        subjects: [{ kind: Group, name: ops-team }]
      - role: rack3-tech
        subjects: [{ kind: User, name: tech@example.com }]

Also, on the Gateway:

• Terminate TLS in front of it. The refresh cookie is Secure everywhere but plain-HTTP loopback, so over plain HTTP on a network the browser keeps no refresh cookie and every reload signs the user out
• Set trustProxy only behind a TLS proxy whose hop count you trust: it makes the Gateway see https, and without a trusted proxy client IPs (and so rate limits) can be spoofed
• List the names clients use in allowedHosts; only loopback on the bound port passes the Host check by default
• Tune rateLimit (default 300 requests per minute per IP). It is counted before the auth check, so failed sign-ins are throttled too
• Ship the Gateway's authz decision lines (subject, route, resource, verb, decision, policy version) to your log store
• 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

Step 5: Authorize writes

Kernel checks every write against spec.rbac, whichever path it takes. A command.request needs devices: write on its target device, and a command scoped to a worker or rack needs it on every device that worker owns. Every attempt, refused ones included, is recorded in the write-command log with the caller's subject and the roles spec.rbac binds to it; reading it with command.log needs commands: read. When an app acts for a signed-in user (req.mdk), Kernel verifies the user's own token, requires both the app's and the user's rules to allow the write, and records the user as the caller via the app.

Options

For a caller with a token, the voter and requester are the operator it acts for (req.mdk), else the caller's own identity, and the payload's self-asserted authPerms are ignored on both push and vote; they apply only to in-process calls. Naming another voter without the operator's token needs actions: delegate. Prefer req.mdk, which needs no delegate grant, and grant delegate only to an app whose code you trust to name the right user.

Provisioning a device

Registering, updating or forgetting a device is a write action (registerThing, updateThing, forgetThings) pushed through the Kernel with the target Worker in params[0].workerId. It needs actions: write to push, and devices: write on every device the push resolves to.

The payload requires voter and authPerms (ERR_PAYLOAD_VOTER_REQUIRED, ERR_PAYLOAD_AUTH_PERMS_REQUIRED), so a push without them is refused before its targets are resolved. For a caller carrying a token the Kernel then ignores what they assert and evaluates the caller's own identity and rules instead, so they satisfy the schema rather than grant anything.

updateThing and forgetThings name a device the registry already knows, so a devices: write rule narrowed with resourceNames matches them normally. registerThing does not: the device is not in the registry yet, so it resolves to no instance name, and a rule scoped to instances never matches a request that names none. Registering needs an unscoped devices: write rule, which grants write access to every device the policy covers. Bind that to a dedicated provisioning account rather than to an operator role, and keep the scoped rule for everything else.

A push that resolves and executes means the configuration is persisted. The running Worker does not publish the new device: it appears after the Worker restarts against the same store.

Suggested default: approval-gated writes for anything that changes hash, power, or network membership, with the people who vote bound to a role holding actions: vote and devices: write on the affected devices. Direct commands only where a single operator's devices: write rule is enough. Keep commands: read with the people who audit.

Step 6: Wire the UI session

passwordAuth() from @tetherto/mdk-ui-foundation signs a user in through the Gateway's /auth/login. The access token stays in memory; the refresh token stays in an HttpOnly, SameSite=Strict cookie scoped to /auth, out of reach of page scripts. The provider renews the token on a timer and on a 401, and tabs refresh one at a time under a Web Locks lock. Refresh tokens rotate on every use, and a used one presented again revokes the whole session (theft detection). The one exception is two clients refreshing at once: within about 10 seconds of its use, while its successor is still unused, a used token gets that same successor, so both hold one refresh token and the next reuse of it, by whoever is behind, revokes the session.

Options

Suggested default for a production dashboard:

• passwordAuth({ baseUrl: httpsOrigin }) passed to <MdkProvider>, with restore() before the first render
• HTTPS end to end, a real apiBaseUrl, no Vite dev proxy
• One fetch client (the provider's fetcher) so pages cannot skip Authorization
• Route guards on any view that can mutate the fleet (the shell template uses <RequireAuth>)
• Hide write controls the user's roles do not allow. Hiding is not authorization; the Gateway and Kernel still deny
• Static bundle behind the same proxy that terminates TLS. Do not run vite dev as the production UI

Step 7: (Optional) MCP and the operator agent

MCP is optional. The standalone @tetherto/mdk-mcp process binds 127.0.0.1 and answers POST /mcp. With an authority (an in-process Kernel, or mdk run mcp signing in as mdk-mcp), every request needs an agent's own access token, each agent's tools/list is filtered by its rules, and each call is checked as the Gateway checks the same route. A tool scoped by an instance name is listed when some instance is allowed and checked per call; a tool with no declared access is not offered. The static spec.mcp.token and spec.mcp.identity are refused.

Options

Suggested default: leave MCP on 127.0.0.1, give each agent its own service account with a read-only role, and grant write tools only with allowWrite or allowTools plus a rule that allows them. 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, .mdk/, the trusted-keys dir and Worker storeDir, and 0600 on seed, key and credential files. The Kernel store holds users, password hashes and the token signing key; .mdk/credentials/ holds every app's and agent's private key. Encrypt at rest if the host requires it
• Back up those directories as operational data, with the same access control as the live files
• When staff leave, mdk user disable or mdk user remove them: their access tokens stop at the Kernel at once, and their bindings stay until you remove them from spec.rbac
• Rotate service-account keys with mdk sa rotate, and Kernel, Gateway and Worker transport keys when a host is rebuilt, updating the allowlist in the same change
• Practice recovery from a wiped data directory before an incident
• Watch Gateway-to-Kernel errors and the Gateway's policy version, 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 an admission in running processes. Use kernel.revokeKey(key) and each affected runtime.revokeKey(key), and remove the publication and startup configuration that would admit it again. Check the live Kernel and Worker allowlists, not just files on disk, and verify that refused calls fail after revocation and after restart.