A user-run dig-app Agent cannot read the .deb's root-owned control token — the natural server shape cannot connect

[MichaelTaylor3d]

Task

Give a server install a working shape where dig-node runs as a system service and dig-app runs as a user Agent. Today that combination cannot connect, because the control token is unreadable by anyone but root.

Parent: https://github.com/DIG-Network/dig_ecosystem/issues/3173
Source ticket: DIG-Network/dig-app#303

Context

Measured on Ubuntu Server 24.04.4 (dig-app#303, run-id dige2e-303-20260827220201), installing dig-node from the released .deb:

/var/lib/dig-node               700 root:root
/var/lib/dig-node/control-token 600 root:root

A dig-app Agent started as an ordinary user cannot read the token, and reports it accurately:

WARN dig_app_core::agent: no DIG node connected
  reason=a node is running at http://dig.local but this app has no control token for it —
  start the node as this user, or grant read access to its control-token file

The Agent stays up and keeps retrying rather than exiting, which is the correct behaviour. The message is honest and actionable. Neither is the defect.

Why this is worth a ticket

The defect is that this is the default outcome of the documented install on a server, where node-as-system-service plus app-as-user-agent is the natural shape. The e2e only got a connection by running dig-app as root — which is not a shape to recommend for a process that holds a user's identity.

An operator following the obvious path hits this as the third of three consecutive stops. It is the one with no workaround that a reader of the message would consider acceptable.

Scope

The deliverable is a decision plus the packaging change it implies, not a doc note. Candidate shapes, none pre-selected:

• a dig group owning the token, with 0640 and the installing user added to it;
• a documented --user systemd unit for dig-node so both run as the same user;
• a per-user token the node issues on request over an already-authenticated channel.

Whichever is chosen, the token must not become world-readable: it is a grant of control over a process that moves $DIG, and widening it to 0644 would trade an inconvenience for a privilege boundary. State the principal the new permission admits and why that principal is acceptable.

Evidence

The current state is measured (above). The fix needs its own: a transcript of an ordinary-user dig-app connecting to a system-service dig-node on a clean host, and the token's resulting mode and ownership.

[MichaelTaylor3d]

Owned by the dig-node CLI/service/updater batch lane — branch loop/batch-cli, worktree dn-cli, one PR closing #303 #304 #305 #392 #403 #407.

Progress is pushed at every increment; resume from the branch.

[MichaelTaylor3d]

Decision: do NOT widen the token. Issue a scoped credential through the pairing flow that already exists.

Why not the two file-permission shapes

This token is the master capability, not merely "control". It authorizes pairing administration — mint, list, revoke — and chiaPeers.add, which grants chain authority over the node's wallet replica. So the shapes in the ticket's candidate list are not conveniences:

• A dig group at 0640 grants master-tier control of a process that moves $DIG to every member, permanently, and it outlives the app that motivated it: removing dig-app does not remove the group membership. It also does not scope — a member gets everything, including the ability to mint further tokens and to revoke the operator's.
• A --user systemd unit does not widen a permission, but it changes what the node is on a server: no start at boot, per-login lifetime, per-user state. That is a different product for the one deployment shape where an always-on node matters most.

What to use instead — it is already built

crates/dig-node-service/src/pairing.rs exists for exactly this problem, described in its own module doc as "how a client which cannot read the local control-token file obtains a SCOPED, revocable credential". It is what the MV3 extension uses, and a user-run Agent is the same class of client.

The flow needs no new mechanism: pairing.request is open, approval requires the master token — which the operator who installed the .deb already holds via sudo — and pairing.poll returns the token once. The CORS restriction on the poll response binds browsers only, so a native Agent is unaffected.

The principal admitted: one client installation on this host, approved once by the operator, holding control.* mutation rights minus the master tier. It cannot mint or revoke pairings, cannot hide itself, and cannot grant itself chain authority that would survive revocation. That is strictly less than a group grant, and it is revocable with sudo dign pair revoke <id> rather than by editing a file mode.

The token stays 0600 root:root and /var/lib/dig-node stays 0700.

The packaging/CLI change this implies, landing in PR #458

The dead end was not only the permission — it was the advice. The unreadable-token remedy told the operator to "reinstall the current dig-node so the service grants your account read access". On Windows that is true (the installer keeps an explicit read grant for the interactive install-user). On Ubuntu it is false: the .deb leaves 0700 root:root and reinstalling changes nothing, so an operator following it loops through uninstall/install and arrives back at the same denial.

The remedy is now platform-correct and, on Unix, names the scoped route (sudo dign pair) and its revocation instead of a wider file. The platform is a function argument rather than a cfg! branch, so both sentences are asserted on any host.

What is NOT done here, stated plainly

The dig-app side (DIG-Network/dig-app#303) still has to perform the handshake — request, display the code, poll, persist the token. Nothing in dig-node blocks it. Until that lands, the honest server shape is sudo for CLI use, and the e2e's root-run dig-app remains the only connected configuration — which is why this ticket should stay open until an ordinary-user Agent connects on a clean host, with the transcript the ticket asks for.

[MichaelTaylor3d]

Shape decision: do NOT widen the control token — use pairing

Decided by the #403 lane and recorded here rather than left implicit. This ticket stays OPEN; PR #458 deliberately does not close it.

Why not widen

The control token is the master capability. It authorizes pairing administration and chiaPeers.add — and chiaPeers.add grants chain authority over the wallet replica, which is the node's view of the user's money. Two tempting relaxations were rejected:

• A dig group at 0640 hands that master capability permanently to every member, and outlives the app that motivated it. Nothing revokes it when dig-app is uninstalled.
• A --user unit changes what the node is on a server, which is a different product, not a permission tweak.

The token stays 0600 root:root.

The primitive already exists

Pairing (crates/dig-node-service/src/pairing.rs) was built for exactly this: a client that cannot read a file. It is what the MV3 extension uses today. The principal it admits is narrower in every dimension that matters — one operator-approved client, mutation rights minus the master tier, and revocable via sudo dign pair revoke <id>.

An allowlist drawn for one principal is not valid for a different one; pairing is the mechanism that draws a new one properly instead of reusing root's.

What landed in PR #458 — the advice half

The old remedy told the operator to "reinstall so the service grants your account read access." That is true on Windows and false on Ubuntu, where reinstalling changes nothing and the operator loops through the same failure. The platform is now a function argument rather than a cfg! branch, so both sentences are asserted on any host — a cfg! branch can only ever be tested on the platform that compiles it.

Still owed, and why this stays open

The dig-app handshake — DIG-Network/dig-app#303. dig-app must pair rather than read the token. Until that lands, a user-run Agent still cannot connect; this ticket closes when it can.