From d65f05ee0de4dc7242863f970c83dcdb322b5bb6 Mon Sep 17 00:00:00 2001
From: Michael Taylor <michael@michaeltaylor.dev>
Date: Sun, 12 Jul 2026 19:23:28 -0700
Subject: [PATCH 1/6] feat: machine-wide control-token state dir + dig-node
 open handler (#501, #389)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Deliverable A (#501): decouple the control token + paired-token store from the
per-user config dir into a machine-wide, identity-INDEPENDENT state dir so the
daemon (which may run as a service under a different OS account, e.g. Windows
LocalSystem) and the operator CLI resolve the SAME token file.

- Add `state::state_dir()`: Windows `%PROGRAMDATA%\DigNode`, Linux `/var/lib/dig-node`
  (fallback `/etc/dig-node`), macOS `/Library/Application Support/DigNode`; env override
  `DIG_NODE_STATE_DIR`; legacy per-user fallback for a non-service dev run (back-compat).
- Move ONLY control-token + paired-tokens.json there; the bulk per-user `.dig` cache +
  config.json stay exactly as-is (#96).
- Security: created dir/token get a restrictive ACL (Unix 0700 dir / 0600 file; Windows
  SYSTEM+Admins full + the installing user read, inheritance removed) — never world-readable.
  The ACL is applied only on FRESH create so a SYSTEM/root service re-run cannot clobber the
  installer's install-user grant. `dig-node install` pre-creates the dir as the interactive
  user; the service self-identifies via DIG_NODE_RUN_CONTEXT.
- `dig-node pair` reads the token read-only (never mints a phantom the node won't trust) and
  surfaces a precise service-vs-user remedy; the control.* 401 names the exact path + remedy.

Deliverable B (#389): implement `dig-node open <chia://… | urn:dig:chia:…>` (+ --json),
the OS scheme-handler target. Strictly validates (only chia/urn-dig schemes; rejects
file:/javascript:/data:, shell metacharacters, path traversal, non-64-hex store refs),
then opens the default browser at the node's local serve URL via a no-shell launcher
behind an injectable trait.

Version: 0.26.0 -> 0.27.0 (minor; additive + back-compat).

Refs #501 #389
Co-Authored-By: Claude <noreply@anthropic.com>
---
 Cargo.lock                                    |   2 +-
 Cargo.toml                                    |   2 +-
 crates/dig-node-service/src/cli.rs            |   5 +
 crates/dig-node-service/src/control.rs        | 182 ++++++--
 crates/dig-node-service/src/lib.rs            |   8 +
 crates/dig-node-service/src/main.rs           |  10 +
 crates/dig-node-service/src/meta.rs           |   7 +-
 crates/dig-node-service/src/open.rs           | 384 ++++++++++++++++
 crates/dig-node-service/src/pair.rs           |   6 +-
 crates/dig-node-service/src/pairing.rs        |  37 +-
 crates/dig-node-service/src/server.rs         |  36 +-
 crates/dig-node-service/src/service.rs        |  18 +
 crates/dig-node-service/src/state.rs          | 422 ++++++++++++++++++
 crates/dig-node-service/src/win_service.rs    |   9 +
 .../dig-node-service/tests/content_serve.rs   |   3 +
 crates/dig-node-service/tests/server.rs       |  16 +
 16 files changed, 1080 insertions(+), 67 deletions(-)
 create mode 100644 crates/dig-node-service/src/open.rs
 create mode 100644 crates/dig-node-service/src/state.rs

diff --git a/Cargo.lock b/Cargo.lock
index 0e340c1..16cf62b 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -1956,7 +1956,7 @@ dependencies = [
 
 [[package]]
 name = "dig-node-service"
-version = "0.26.0"
+version = "0.27.0"
 dependencies = [
  "axum",
  "base64",
diff --git a/Cargo.toml b/Cargo.toml
index 2858d71..2b4bd0e 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -31,7 +31,7 @@ edition = "2021"
 # (`[workspace.package].version`), so it MUST be set here for a release to fire
 # (§3.6). The library crates (dig-node-core/dig-runtime/dig-wallet) keep their own
 # independent versions — only the released binary tracks the workspace version.
-version = "0.26.0"
+version = "0.27.0"
 
 # Release hardening, matching digstore: keep integer-overflow checks ON in release.
 # The node parses untrusted serialized input and does offset/length arithmetic over
diff --git a/crates/dig-node-service/src/cli.rs b/crates/dig-node-service/src/cli.rs
index da2cb0e..03846f9 100644
--- a/crates/dig-node-service/src/cli.rs
+++ b/crates/dig-node-service/src/cli.rs
@@ -96,6 +96,9 @@ impl ExitCode {
         match e.kind() {
             PermissionDenied => ExitCode::PermissionDenied,
             AddrInUse | AddrNotAvailable => ExitCode::BindFailed,
+            // A bad argument surfaced as `InvalidInput` (e.g. `dig-node open` rejecting a
+            // non-DIG/malformed link) is a USAGE error, not a generic I/O failure.
+            InvalidInput => ExitCode::Usage,
             _ => ExitCode::IoError,
         }
     }
@@ -204,6 +207,8 @@ mod tests {
         assert_eq!(ExitCode::from_io_error(&bind), ExitCode::BindFailed);
         let other = std::io::Error::other("x");
         assert_eq!(ExitCode::from_io_error(&other), ExitCode::IoError);
+        let usage = std::io::Error::new(std::io::ErrorKind::InvalidInput, "bad link");
+        assert_eq!(ExitCode::from_io_error(&usage), ExitCode::Usage);
     }
 
     #[test]
diff --git a/crates/dig-node-service/src/control.rs b/crates/dig-node-service/src/control.rs
index e011c51..b2ad109 100644
--- a/crates/dig-node-service/src/control.rs
+++ b/crates/dig-node-service/src/control.rs
@@ -17,13 +17,14 @@
 //! 1. **Loopback-only.** The whole server binds `127.0.0.1` (see [`crate::config`]),
 //!    so nothing off-machine can reach any method.
 //! 2. **Local authorization** for the mutating control namespace. A random
-//!    **control token** is generated at first run into the node's config dir
-//!    (`<config_dir>/control-token`, next to dig-node's `config.json`) with
-//!    owner-only permissions where the OS supports it. A same-host controller reads
-//!    that file (it can, because it runs as the same user on the same machine) and
-//!    presents the token on every `control.*` call — as the `X-Dig-Control-Token`
-//!    request header or a `params._control_token` field. The READ methods are NOT
-//!    gated; only `control.*` requires the token.
+//!    **control token** is generated at first run into the machine-wide, identity-
+//!    INDEPENDENT state dir (`<state_dir>/control-token` — [`crate::state`], #501) with
+//!    a restrictive ACL. A same-host controller reads that file and presents the token
+//!    on every `control.*` call — as the `X-Dig-Control-Token` request header or a
+//!    `params._control_token` field. The READ methods are NOT gated; only `control.*`
+//!    requires the token. The token lives in [`crate::state::state_dir`] (NOT the
+//!    per-user config dir) so the daemon (which may run as a service under a different
+//!    OS account) and the operator CLI resolve the SAME file.
 //!
 //! This is the standard "local capability file" pattern (cf. Chia's `daemon` /
 //! Bitcoin's cookie auth): possession of the on-disk token = authorization, so a
@@ -86,25 +87,94 @@ pub fn is_pairing_admin_method(method: &str) -> bool {
     )
 }
 
-/// The path to the control-token file, given the node's config dir. The config dir
-/// is `config.json`'s parent (dig-node's `config_path()`), so the token lives beside
-/// the shared config. PURE (path math only).
-pub fn control_token_path(config_path: &Path) -> PathBuf {
-    config_path
-        .parent()
-        .map(|p| p.join(CONTROL_TOKEN_FILE))
-        .unwrap_or_else(|| PathBuf::from(CONTROL_TOKEN_FILE))
+/// The path to the control-token file: `<state_dir>/control-token`, where the state
+/// dir is the machine-wide, identity-INDEPENDENT daemon state dir (#501,
+/// [`crate::state::state_dir`]) — NOT the per-user config dir. Decoupling the token
+/// from `config_path()` is the fix for the service-vs-user path split: the running
+/// daemon and the operator CLI resolve this ONE path regardless of which OS user each
+/// runs as, so the CLI reads the SAME token the service wrote.
+pub fn control_token_path() -> PathBuf {
+    crate::state::state_dir().join(CONTROL_TOKEN_FILE)
 }
 
 /// Load the control token, generating + persisting a fresh one if absent.
 ///
 /// The token is 32 random bytes rendered as 64-hex. Generated at RUNTIME into the
-/// node's config dir on first call; subsequent calls (and other processes sharing
-/// the dir) read the same value. Written with owner-only permissions on Unix
-/// (`0600`) so another user on the box cannot read it. Never committed.
+/// machine-wide state dir ([`control_token_path`]) on first call; subsequent calls (and
+/// other processes / users on the box) read the same value. The dir + file are created
+/// with a RESTRICTIVE ACL (owner/SYSTEM + Administrators, the creating user; never
+/// world/all-users-readable — see [`crate::state`]). Never committed.
 pub fn load_or_create_token() -> std::io::Result<String> {
-    let path = control_token_path(&dig_node_core::config_path());
-    load_or_create_token_at(&path)
+    load_or_create_token_at(&control_token_path())
+}
+
+/// A precise, service-aware remedy for a control-token authorization failure (#501).
+///
+/// The classic failure is the service-vs-user PATH/PERMISSION split: the node runs as a
+/// service (Windows LocalSystem / a root daemon) and minted `control-token` in the
+/// machine-wide state dir with restrictive perms, but the interactive user running
+/// `dig-node pair` / a `control.*` call cannot READ it. This inspects the resolved token
+/// path from the CALLER's perspective and returns the exact fix (which dir + that it
+/// needs elevation or the install-user's read ACL), instead of the generic hint.
+pub fn control_token_remedy() -> String {
+    let path = control_token_path();
+    let dir = path
+        .parent()
+        .map(|p| p.display().to_string())
+        .unwrap_or_default();
+    // Read once: an Ok read = readable (whatever the contents); an Err with the file present
+    // = the service-vs-user ACL split; absent = the node has not minted one yet.
+    let read = std::fs::read_to_string(&path);
+    let readable = read.is_ok();
+    let present = readable || path.exists();
+    if present && !readable {
+        format!(
+            "the node's control token at {} exists but is NOT readable by your account — \
+             the node runs as a service under a different account (Windows LocalSystem / a \
+             root daemon). Re-run this command elevated (Administrator on Windows, sudo on \
+             Unix), or have the installer grant your account read access to {}.",
+            path.display(),
+            dir
+        )
+    } else if !present {
+        format!(
+            "no control token found at {}. Start the node so it mints one \
+             (`dig-node run`, or `dig-node start` for the installed service), then retry.",
+            path.display()
+        )
+    } else {
+        format!(
+            "the presented control token was not accepted. Ensure the node and this command \
+             resolve the SAME state dir ({dir}) — if you set DIG_NODE_STATE_DIR it must match \
+             on both the node and this command."
+        )
+    }
+}
+
+/// Read the master control token WITHOUT creating one — the OPERATOR-side load (`dig-node
+/// pair` / any local control CLI, #501). It must NEVER mint a token: minting a fresh token
+/// the running node does not trust is the exact original bug (the CLI wrote its own token to
+/// a per-user path the service never read). On a missing/unreadable/blank token it returns a
+/// rich [`std::io::Error`] carrying [`control_token_remedy`] — the precise service-vs-user
+/// remedy — with the error KIND chosen so the CLI maps it to the right exit code
+/// ([`crate::cli::ExitCode::from_io_error`]): `PermissionDenied` (the ACL split → "elevate")
+/// when the file is present but unreadable, else `NotFound` ("start the node").
+pub fn load_token_readonly() -> std::io::Result<String> {
+    let path = control_token_path();
+    match std::fs::read_to_string(&path) {
+        Ok(s) if !s.trim().is_empty() => Ok(s.trim().to_string()),
+        // Present but blank/unreadable, or absent → never mint; surface the exact remedy.
+        other => {
+            let kind = if path.exists() {
+                std::io::ErrorKind::PermissionDenied
+            } else {
+                std::io::ErrorKind::NotFound
+            };
+            // Drop the raw read value; the remedy is the actionable message.
+            drop(other);
+            Err(std::io::Error::new(kind, control_token_remedy()))
+        }
+    }
 }
 
 /// [`load_or_create_token`] for an explicit path (so tests use a temp dir and never
@@ -119,24 +189,24 @@ pub fn load_or_create_token_at(path: &Path) -> std::io::Result<String> {
     }
     let token = generate_token();
     if let Some(dir) = path.parent() {
-        std::fs::create_dir_all(dir)?;
+        // Create the state dir with a RESTRICTIVE ACL (not the world-readable default of
+        // a machine-wide `%PROGRAMDATA%`) — see [`crate::state::ensure_dir_restricted`].
+        crate::state::ensure_dir_restricted(dir)?;
     }
     std::fs::write(path, &token)?;
     restrict_permissions(path);
     Ok(token)
 }
 
-/// Restrict the token file to owner read/write where the OS supports it (Unix
-/// `0600`). On Windows the default ACL on a per-user profile dir already scopes it
-/// to the user, and loopback-only binding is the primary control; this is
-/// best-effort defense-in-depth, so a failure is ignored.
-#[cfg(unix)]
+/// Restrict a control/auth file so it is not readable by every local user. Delegates to
+/// [`crate::state::restrict_file`]: Unix `0600`; on Windows the file inherits the tight,
+/// inheritable ACL of the machine-wide state dir ([`crate::state::ensure_dir_restricted`]) —
+/// critical now that the file lives under `%PROGRAMDATA%`, whose default would otherwise let
+/// every local user read it (a local privilege-escalation vector, #501). Best-effort (a
+/// failure is ignored — loopback bind + token possession are the primary gate).
 pub(crate) fn restrict_permissions(path: &Path) {
-    use std::os::unix::fs::PermissionsExt;
-    let _ = std::fs::set_permissions(path, std::fs::Permissions::from_mode(0o600));
+    crate::state::restrict_file(path);
 }
-#[cfg(not(unix))]
-pub(crate) fn restrict_permissions(_path: &Path) {}
 
 /// Generate a fresh 64-hex control token from 32 bytes of OS randomness.
 fn generate_token() -> String {
@@ -453,6 +523,10 @@ pub struct ControlCtx {
     pub node: Arc<Node>,
     /// The node's config.json path (pins + upstream override live here).
     pub config_path: PathBuf,
+    /// The machine-wide daemon STATE dir (#501) — where the control token +
+    /// `paired-tokens.json` live (NOT the per-user config dir). The pairing-admin
+    /// methods read/write the paired-token store from here.
+    pub state_dir: PathBuf,
     /// The loopback `host:port` the node is bound to (status/config).
     pub addr: String,
     /// The upstream DIG RPC the node proxies/syncs to.
@@ -490,11 +564,11 @@ pub async fn dispatch_control(ctx: &ControlCtx, id: Value, method: &str, params:
         "control.sync.trigger" => sync_trigger(ctx, id, params).await,
         // Pairing administration (#280) — reached only with the MASTER token (the
         // gate blocks a paired token from these, see `is_pairing_admin_method`).
-        "control.pairing.list" => crate::pairing::list(&ctx.pairings, &ctx.config_path, id),
+        "control.pairing.list" => crate::pairing::list(&ctx.pairings, &ctx.state_dir, id),
         "control.pairing.approve" => {
-            crate::pairing::approve(&ctx.pairings, &ctx.config_path, id, params)
+            crate::pairing::approve(&ctx.pairings, &ctx.state_dir, id, params)
         }
-        "control.pairing.revoke" => crate::pairing::revoke(&ctx.config_path, id, params),
+        "control.pairing.revoke" => crate::pairing::revoke(&ctx.state_dir, id, params),
         // Control methods the shell does not own are delegated to the NODE's own
         // control surface (`control.peerStatus` / `control.subscribe` /
         // `control.unsubscribe` / `control.listSubscriptions` — the node's persisted
@@ -984,6 +1058,48 @@ mod tests {
         let _ = std::fs::remove_dir_all(&dir);
     }
 
+    /// SECURITY (#501): the control token grants full local control, so the created
+    /// file MUST NOT be readable by other local users. On Unix that is a hard `0600`
+    /// assertion (no group/other bits) — the CI-gated path (CI runs on Linux). On
+    /// Windows the restriction is applied via `icacls` (asserted separately in a
+    /// Windows-gated test / by the orchestrator's adversarial ACL check).
+    #[cfg(unix)]
+    #[test]
+    fn created_token_file_is_not_world_or_group_readable() {
+        use std::os::unix::fs::PermissionsExt;
+        let dir = std::env::temp_dir().join(format!(
+            "dig-node-token-perms-{}-{}",
+            std::process::id(),
+            line!()
+        ));
+        let path = dir.join(CONTROL_TOKEN_FILE);
+        let _ = std::fs::remove_dir_all(&dir);
+        load_or_create_token_at(&path).unwrap();
+        let mode = std::fs::metadata(&path).unwrap().permissions().mode() & 0o777;
+        assert_eq!(
+            mode & 0o077,
+            0,
+            "token must have NO group/other permission bits (got {mode:o})"
+        );
+        let _ = std::fs::remove_dir_all(&dir);
+    }
+
+    /// The remedy hint names the concrete token path and, when the token is absent from
+    /// the caller's perspective, tells them to start the node — never the old generic
+    /// "<config_dir>" wording.
+    #[test]
+    fn control_token_remedy_names_a_concrete_path() {
+        let remedy = control_token_remedy();
+        assert!(
+            remedy.contains("control token") || remedy.contains("control-token"),
+            "remedy should mention the control token: {remedy}"
+        );
+        assert!(
+            remedy.contains("dig-node") || remedy.contains("state dir") || remedy.contains('/') || remedy.contains('\\'),
+            "remedy should name a path or command: {remedy}"
+        );
+    }
+
     #[test]
     fn parse_store_ref_validates_hex_and_splits_capsule() {
         let store = "a".repeat(64);
diff --git a/crates/dig-node-service/src/lib.rs b/crates/dig-node-service/src/lib.rs
index 35c1448..c678f4c 100644
--- a/crates/dig-node-service/src/lib.rs
+++ b/crates/dig-node-service/src/lib.rs
@@ -38,11 +38,19 @@ pub mod config;
 pub mod content;
 pub mod control;
 pub mod meta;
+/// `dig-node open <chia://… | urn:dig:chia:…>` (#389): the OS scheme-handler target the
+/// installer registers for `chia://` + `urn:dig:chia:`. Strictly validates the untrusted
+/// handler argument, then opens the user's default browser at the resolving URL. See [`open`].
+pub mod open;
 pub mod pair;
 pub mod pairing;
 pub mod rpc;
 pub mod server;
 pub mod service;
+/// The machine-wide, identity-independent daemon STATE dir (#501): where the control token +
+/// paired-token store live so the daemon (which may run as a service under a different OS
+/// account) and the operator CLI resolve the SAME files. See [`state`].
+pub mod state;
 pub mod wallet_authz;
 
 /// Windows Service Control Protocol entrypoint — only meaningful on Windows, where
diff --git a/crates/dig-node-service/src/main.rs b/crates/dig-node-service/src/main.rs
index c979312..997277f 100644
--- a/crates/dig-node-service/src/main.rs
+++ b/crates/dig-node-service/src/main.rs
@@ -25,6 +25,7 @@
 use clap::{Parser, Subcommand};
 use dig_node_service::cli::{error_envelope, success_envelope, ExitCode, Outcome};
 use dig_node_service::config::Config;
+use dig_node_service::open;
 use dig_node_service::pair::{self, PairAction};
 use dig_node_service::{serve, service, VERSION};
 
@@ -70,6 +71,13 @@ enum Command {
         #[command(subcommand)]
         action: Option<PairCommand>,
     },
+    /// Open a DIG link in the default browser (#389). The OS scheme-handler target the
+    /// installer registers for `chia://` + `urn:dig:chia:`. Accepts ONLY those two schemes,
+    /// resolves via the local node's serve URL, and never invokes a shell.
+    Open {
+        /// The DIG link (`chia://<storeId>[:<root>]/<path>` or `urn:dig:chia:<…>`).
+        link: String,
+    },
 }
 
 /// `dig-node pair` sub-actions. With none, lists pending requests + issued tokens.
@@ -100,6 +108,7 @@ impl Command {
             Command::Stop => "stop",
             Command::Status => "status",
             Command::Pair { .. } => "pair",
+            Command::Open { .. } => "open",
         }
     }
 }
@@ -129,6 +138,7 @@ fn main() -> std::process::ExitCode {
             };
             render(pair::run(&config, pair_action), action, json)
         }
+        Command::Open { link } => render(open::run(&config, &link), action, json),
     };
     std::process::ExitCode::from(exit.code())
 }
diff --git a/crates/dig-node-service/src/meta.rs b/crates/dig-node-service/src/meta.rs
index 9f8175e..eb0fffd 100644
--- a/crates/dig-node-service/src/meta.rs
+++ b/crates/dig-node-service/src/meta.rs
@@ -452,8 +452,8 @@ pub enum ErrorCode {
     /// `-32030` — a `control.*` (CONTROL/admin) method was called without a valid
     /// local control token. The control surface is loopback-only AND locally
     /// authorized: a same-host controller (the DIG Browser "My Node" UI) must read
-    /// the node's control token from its config dir and present it. Read methods
-    /// are NOT gated; only the mutating/management control namespace is. Shell error.
+    /// the node's control token from the machine-wide state dir and present it. Read
+    /// methods are NOT gated; only the mutating/management control namespace is. Shell error.
     /// (Canonical dig-rpc-types §10 code; `-32020` is RESERVED for onion routing.)
     Unauthorized,
     /// `-32031` — a control operation the embedded dig-node cannot perform on this
@@ -710,7 +710,8 @@ pub fn openrpc_document() -> Value {
             let auth_note = if m.requires_auth {
                 " CONTROL method: requires the local control token (loopback-only + \
                   locally authorized — present it as the X-Dig-Control-Token header or \
-                  params._control_token; read it from <config_dir>/control-token)."
+                  params._control_token; read it from the machine-wide state dir's \
+                  control-token file, e.g. via `dig-node pair`)."
             } else {
                 ""
             };
diff --git a/crates/dig-node-service/src/open.rs b/crates/dig-node-service/src/open.rs
new file mode 100644
index 0000000..043bac6
--- /dev/null
+++ b/crates/dig-node-service/src/open.rs
@@ -0,0 +1,384 @@
+//! `dig-node open <chia://… | urn:dig:chia:…>` (#389) — the OS scheme-handler target.
+//!
+//! The dig-installer registers the OS handlers for `chia://` and `urn:dig:chia:` to invoke
+//! `dig-node open "%1"`. This subcommand is therefore the OS-level fallback resolver for a DIG
+//! link that no in-browser DIG extension intercepted (a link clicked outside a browser, or in a
+//! browser without the extension): it opens the user's DEFAULT browser at the node's LOCAL serve
+//! URL (`/s/<storeId>[:<root>]/<path>`, the #289 plaintext content surface), so the node — the
+//! resolver of record (#365 thin-client) — serves the decrypted content and any installed DIG
+//! extension can still verify it. It NEVER opens dig-node's own GUI (it has none).
+//!
+//! # Security — the argument is UNTRUSTED
+//!
+//! `%1` arrives from an OS protocol handler, so a hostile web page can invoke the registered
+//! scheme with an attacker-chosen argument. This module therefore:
+//!
+//! 1. **Validates STRICTLY.** Only `chia://` and `urn:dig:chia:` are accepted (case-insensitive
+//!    scheme); every other scheme (`file:`, `javascript:`, `data:`, `http:`, …) is rejected. The
+//!    store reference must be canonical 64-hex (`storeId` or `storeId:root`). Shell
+//!    metacharacters, control characters, whitespace, and `..` path traversal are rejected
+//!    outright — even though the launch path never uses a shell (defense in depth).
+//! 2. **Never touches a shell.** The resolved URL is handed to the OS "open a URL" facility as a
+//!    SINGLE, non-shell argv entry (`rundll32 url.dll,FileProtocolHandler` on Windows,
+//!    `xdg-open` on Linux, `/usr/bin/open` on macOS) — never `cmd /c start` / `sh -c`, so even a
+//!    crafted argument cannot inject a command. The launcher is behind [`UrlLauncher`] so tests
+//!    assert the exact URL without spawning a real browser.
+
+use serde_json::json;
+
+use crate::cli::Outcome;
+use crate::config::Config;
+
+/// Shell metacharacters (and quoting/grouping characters) rejected anywhere in the link. The
+/// launch path never uses a shell, so this is defense-in-depth against the untrusted OS argument
+/// — it also keeps a well-formed DIG link from ever carrying surprising bytes into the serve URL.
+const DISALLOWED: &[char] = &[
+    '&', '|', ';', '`', '$', '<', '>', '(', ')', '{', '}', '[', ']', '!', '*', '"', '\'', '\\',
+    '^', '\n', '\r', ' ', '\t',
+];
+
+/// A validated, normalized DIG link: a 64-hex store id, an optional 64-hex root (a capsule
+/// pin), and the (traversal-free) resource path within the store.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct DigLink {
+    /// The 64-hex store id.
+    pub store_id: String,
+    /// The optional 64-hex root hash (present for a `storeId:root` capsule reference).
+    pub root: Option<String>,
+    /// The resource path within the store (may be empty for the store root).
+    pub path: String,
+}
+
+impl DigLink {
+    /// The `storeId` or `storeId:root` reference the `/s/<ref>/…` serve route expects.
+    fn store_ref(&self) -> String {
+        match &self.root {
+            Some(r) => format!("{}:{}", self.store_id, r),
+            None => self.store_id.clone(),
+        }
+    }
+}
+
+/// Abstracts the OS "open this URL in the default browser / protocol handler" action so the
+/// launch path is unit-testable (a fake asserts the exact URL) and the real implementation never
+/// goes through a shell. `url` is ALREADY strictly validated + built by this module.
+pub trait UrlLauncher {
+    /// Open `url` in the user's default browser. Implementations MUST pass `url` as a single,
+    /// non-shell argument.
+    fn open_url(&self, url: &str) -> std::io::Result<()>;
+}
+
+/// The real OS launcher. Opens `url` via a per-OS facility with the URL as a SINGLE argv entry —
+/// never a shell — so a crafted URL cannot inject a command. Fire-and-forget: a failure to SPAWN
+/// the launcher (e.g. `xdg-open` not installed) is surfaced; the launcher's own exit code is not
+/// awaited (it hands off to the browser and exits).
+pub struct OsLauncher;
+
+impl UrlLauncher for OsLauncher {
+    fn open_url(&self, url: &str) -> std::io::Result<()> {
+        use std::process::{Command, Stdio};
+        let mut cmd;
+        #[cfg(target_os = "windows")]
+        {
+            // `rundll32 url.dll,FileProtocolHandler <url>` invokes the registered URL/protocol
+            // handler with the URL as one argv entry and NO shell — unlike `cmd /c start`, which
+            // would parse `&`/`^`/`|` in the argument.
+            cmd = Command::new("rundll32.exe");
+            cmd.arg("url.dll,FileProtocolHandler").arg(url);
+        }
+        #[cfg(target_os = "macos")]
+        {
+            cmd = Command::new("/usr/bin/open");
+            cmd.arg(url);
+        }
+        #[cfg(all(unix, not(target_os = "macos")))]
+        {
+            cmd = Command::new("xdg-open");
+            cmd.arg(url);
+        }
+        #[cfg(not(any(windows, unix)))]
+        {
+            return Err(std::io::Error::new(
+                std::io::ErrorKind::Unsupported,
+                "dig-node open: no URL launcher for this platform",
+            ));
+        }
+        #[cfg(any(windows, unix))]
+        {
+            cmd.stdin(Stdio::null())
+                .stdout(Stdio::null())
+                .stderr(Stdio::null())
+                .spawn()?;
+            Ok(())
+        }
+    }
+}
+
+/// Run `dig-node open <link>`: validate + normalize the link, build the local serve URL, and open
+/// it in the default browser via the real [`OsLauncher`]. See [`run_with`] for the injectable form.
+pub fn run(config: &Config, link: &str) -> std::io::Result<Outcome> {
+    run_with(config, link, &OsLauncher)
+}
+
+/// [`run`] with an injected [`UrlLauncher`] (so tests assert the exact URL without spawning a
+/// browser). A rejected link returns an `InvalidInput` error (→ `USAGE` exit) and the launcher is
+/// NEVER invoked.
+pub fn run_with(
+    config: &Config,
+    link: &str,
+    launcher: &dyn UrlLauncher,
+) -> std::io::Result<Outcome> {
+    let parsed = normalize(link).map_err(|e| {
+        std::io::Error::new(
+            std::io::ErrorKind::InvalidInput,
+            format!("dig-node open: {e}"),
+        )
+    })?;
+    let url = serve_url(config, &parsed);
+    launcher.open_url(&url)?;
+    Ok(Outcome::new(
+        format!("dig-node: opening {url} in your default browser"),
+        json!({
+            "opened": true,
+            "url": url,
+            "store_id": parsed.store_id,
+            "root": parsed.root,
+            "path": parsed.path,
+        }),
+    ))
+}
+
+/// Strictly validate + normalize a DIG link into a [`DigLink`]. PURE. Accepts ONLY `chia://` and
+/// `urn:dig:chia:` (case-insensitive scheme); rejects any other scheme, shell metacharacters,
+/// control characters, whitespace, `..` path traversal, and a non-64-hex store reference.
+pub fn normalize(input: &str) -> Result<DigLink, String> {
+    let s = input.trim();
+    if s.is_empty() {
+        return Err("empty link".to_string());
+    }
+    if let Some(bad) = s.chars().find(|c| c.is_control()) {
+        return Err(format!("control character not allowed (U+{:04X})", bad as u32));
+    }
+    if let Some(bad) = s.chars().find(|c| DISALLOWED.contains(c)) {
+        return Err(format!("disallowed character in link: {bad:?}"));
+    }
+    // Scheme gate — ONLY chia:// or urn:dig:chia: (case-insensitive), nothing else.
+    let rest = strip_prefix_ci(s, "chia://")
+        .or_else(|| strip_prefix_ci(s, "urn:dig:chia:"))
+        .ok_or_else(|| {
+            "only chia:// and urn:dig:chia: links are allowed (this link's scheme is rejected)"
+                .to_string()
+        })?;
+    // Drop any query/fragment — the serve path is store-ref + resource path only.
+    let rest = rest
+        .split(['?', '#'])
+        .next()
+        .unwrap_or("")
+        .trim_start_matches('/');
+    // Split the store reference from the resource path.
+    let (store_ref, path) = match rest.split_once('/') {
+        Some((r, p)) => (r, p),
+        None => (rest, ""),
+    };
+    if path.split('/').any(|seg| seg == "..") {
+        return Err("path traversal (`..`) not allowed".to_string());
+    }
+    // The store reference MUST be canonical 64-hex (storeId or storeId:root) — this rejects any
+    // non-hex authority (a hostname, an IP, an attacker string) outright.
+    let (store_id, root) = crate::control::parse_store_ref(store_ref)?;
+    Ok(DigLink {
+        store_id,
+        root,
+        path: path.to_string(),
+    })
+}
+
+/// Build the node's LOCAL serve URL for a validated link: `http://<host>:<port>/s/<ref>/<path>`
+/// (the #289 plaintext content route). The host/port come from the node's own config (default
+/// `localhost:9778`), so the URL always reaches the running node on this machine.
+fn serve_url(config: &Config, link: &DigLink) -> String {
+    let host = browser_host(config);
+    let port = config.port;
+    let store_ref = link.store_ref();
+    if link.path.is_empty() {
+        format!("http://{host}:{port}/s/{store_ref}/")
+    } else {
+        format!("http://{host}:{port}/s/{store_ref}/{}", link.path)
+    }
+}
+
+/// The host to put in the browser URL: the operator's explicit `DIG_NODE_HOST` when set (bracketed
+/// for IPv6), else `localhost` — friendlier than `127.0.0.1` and equally reachable (the node binds
+/// both loopback families on the port).
+fn browser_host(config: &Config) -> String {
+    match config.host {
+        Some(ip) if ip.is_ipv6() => format!("[{ip}]"),
+        Some(ip) => ip.to_string(),
+        None => "localhost".to_string(),
+    }
+}
+
+/// Case-insensitive prefix strip that is safe on non-ASCII input (never panics on a char
+/// boundary): returns the remainder after `prefix` when `s` starts with it ignoring ASCII case.
+fn strip_prefix_ci<'a>(s: &'a str, prefix: &str) -> Option<&'a str> {
+    let head = s.get(..prefix.len())?;
+    if head.eq_ignore_ascii_case(prefix) {
+        Some(&s[prefix.len()..])
+    } else {
+        None
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::sync::Mutex;
+
+    fn store() -> String {
+        "a".repeat(64)
+    }
+    fn root() -> String {
+        "b".repeat(64)
+    }
+
+    /// A test launcher that records the URL it was asked to open (and proves the real launcher was
+    /// never reached, so no browser/shell is spawned in CI).
+    #[derive(Default)]
+    struct FakeLauncher {
+        opened: Mutex<Vec<String>>,
+    }
+    impl UrlLauncher for FakeLauncher {
+        fn open_url(&self, url: &str) -> std::io::Result<()> {
+            self.opened.lock().unwrap().push(url.to_string());
+            Ok(())
+        }
+    }
+
+    #[test]
+    fn accepts_chia_scheme_with_store_only() {
+        let n = normalize(&format!("chia://{}", store())).unwrap();
+        assert_eq!(n.store_id, store());
+        assert_eq!(n.root, None);
+        assert_eq!(n.path, "");
+    }
+
+    #[test]
+    fn accepts_chia_scheme_with_capsule_and_path() {
+        let n = normalize(&format!("chia://{}:{}/index.html", store(), root())).unwrap();
+        assert_eq!(n.store_id, store());
+        assert_eq!(n.root.as_deref(), Some(root().as_str()));
+        assert_eq!(n.path, "index.html");
+    }
+
+    #[test]
+    fn accepts_urn_dig_chia_scheme() {
+        let n = normalize(&format!("urn:dig:chia:{}/a/b.css", store())).unwrap();
+        assert_eq!(n.store_id, store());
+        assert_eq!(n.path, "a/b.css");
+    }
+
+    #[test]
+    fn scheme_match_is_case_insensitive() {
+        assert!(normalize(&format!("CHIA://{}", store())).is_ok());
+        assert!(normalize(&format!("Urn:Dig:Chia:{}", store())).is_ok());
+    }
+
+    #[test]
+    fn strips_query_and_fragment() {
+        let n = normalize(&format!("chia://{}/p?x=1#frag", store())).unwrap();
+        assert_eq!(n.path, "p");
+    }
+
+    #[test]
+    fn rejects_dangerous_schemes() {
+        for bad in [
+            "file:///etc/passwd",
+            "javascript:alert(1)",
+            "data:text/html,<script>",
+            "http://evil.example/",
+            "https://evil.example/",
+            "chrome://settings",
+            "ftp://host/x",
+        ] {
+            assert!(normalize(bad).is_err(), "must reject {bad}");
+        }
+    }
+
+    #[test]
+    fn rejects_shell_metacharacters_and_traversal() {
+        let s = store();
+        for bad in [
+            format!("chia://{s};rm -rf /"),
+            format!("chia://{s}/$(whoami)"),
+            format!("chia://{s}/`id`"),
+            format!("chia://{s}/a&b"),
+            format!("chia://{s}/a|b"),
+            format!("chia://{s}/../../secret"),
+            format!("chia://{s}/a b"),
+            "chia://not-hex-authority/x".to_string(),
+            "chia://".to_string(),
+            "".to_string(),
+        ] {
+            assert!(normalize(&bad).is_err(), "must reject {bad}");
+        }
+    }
+
+    #[test]
+    fn rejects_non_64_hex_store_id() {
+        assert!(normalize("chia://deadbeef").is_err());
+        assert!(normalize(&format!("chia://{}", "g".repeat(64))).is_err());
+    }
+
+    #[test]
+    fn serve_url_targets_local_node_route() {
+        let cfg = Config::default();
+        let link = normalize(&format!("chia://{}:{}/index.html", store(), root())).unwrap();
+        let url = serve_url(&cfg, &link);
+        assert_eq!(
+            url,
+            format!(
+                "http://localhost:9778/s/{}:{}/index.html",
+                store(),
+                root()
+            )
+        );
+    }
+
+    #[test]
+    fn serve_url_store_root_has_trailing_slash() {
+        let cfg = Config::default();
+        let link = normalize(&format!("chia://{}", store())).unwrap();
+        assert_eq!(
+            serve_url(&cfg, &link),
+            format!("http://localhost:9778/s/{}/", store())
+        );
+    }
+
+    #[test]
+    fn run_with_opens_the_exact_serve_url() {
+        let cfg = Config::default();
+        let fake = FakeLauncher::default();
+        let out = run_with(&cfg, &format!("chia://{}/index.html", store()), &fake).unwrap();
+        let opened = fake.opened.lock().unwrap();
+        // Exactly one URL, the local serve route — and it is a plain http URL carrying no shell
+        // metacharacters (the trait contract passes ONLY a URL string, never a shell command).
+        assert_eq!(opened.len(), 1);
+        assert_eq!(
+            opened[0],
+            format!("http://localhost:9778/s/{}/index.html", store())
+        );
+        assert!(opened[0].starts_with("http://"));
+        assert!(!opened[0].chars().any(|c| DISALLOWED.contains(&c)));
+        assert_eq!(out.result["opened"], json!(true));
+    }
+
+    #[test]
+    fn run_with_rejects_bad_link_without_launching() {
+        let cfg = Config::default();
+        let fake = FakeLauncher::default();
+        let err = run_with(&cfg, "javascript:alert(1)", &fake).unwrap_err();
+        assert_eq!(err.kind(), std::io::ErrorKind::InvalidInput);
+        // The launcher was NEVER invoked for a rejected link.
+        assert!(fake.opened.lock().unwrap().is_empty());
+    }
+}
diff --git a/crates/dig-node-service/src/pair.rs b/crates/dig-node-service/src/pair.rs
index 1684298..ea5b63c 100644
--- a/crates/dig-node-service/src/pair.rs
+++ b/crates/dig-node-service/src/pair.rs
@@ -37,7 +37,11 @@ pub enum PairAction {
 /// `main.rs` maps them to the differentiated exit code.
 pub fn run(config: &Config, action: PairAction) -> std::io::Result<Outcome> {
     let addr = config.bind_addr();
-    let token = control::load_or_create_token()?;
+    // Read the master token WITHOUT minting one (#501): if the running node (a service under a
+    // different OS account) wrote a token this user cannot read, minting a fresh one here would
+    // recreate the exact bug — a token the node never trusts. `load_token_readonly` instead
+    // surfaces the precise service-vs-user remedy (elevate / grant read ACL / start the node).
+    let token = control::load_token_readonly()?;
     let rt = tokio::runtime::Builder::new_current_thread()
         .enable_all()
         .build()?;
diff --git a/crates/dig-node-service/src/pairing.rs b/crates/dig-node-service/src/pairing.rs
index fa1f6a2..254612f 100644
--- a/crates/dig-node-service/src/pairing.rs
+++ b/crates/dig-node-service/src/pairing.rs
@@ -58,8 +58,9 @@ use serde_json::{json, Value};
 use crate::control::{control_error, control_ok, ct_eq};
 use crate::meta::ErrorCode;
 
-/// The paired-token store file, beside `config.json` / `control-token` in the
-/// node's config dir.
+/// The paired-token store file, beside `control-token` in the machine-wide state dir
+/// (#501, [`crate::state::state_dir`]) — NOT the per-user config dir — so the daemon
+/// and the operator CLI resolve the SAME store regardless of OS user.
 pub const PAIRED_TOKENS_FILE: &str = "paired-tokens.json";
 
 /// How long a pending pairing request stays valid before it must be re-requested.
@@ -200,7 +201,7 @@ pub fn poll(pending: &Mutex<PendingPairings>, id: Value, params: &Value) -> Valu
 /// GATED `control.pairing.list` — the operator's approve view: pending requests
 /// (each with its `pairing_code` + `client_name`) AND the issued controller tokens
 /// (id + client_name + created, NEVER the token value).
-pub fn list(pending: &Mutex<PendingPairings>, config_path: &Path, id: Value) -> Value {
+pub fn list(pending: &Mutex<PendingPairings>, state_dir: &Path, id: Value) -> Value {
     let now = now_ms();
     let mut g = pending.lock().unwrap_or_else(|e| e.into_inner());
     g.prune(now);
@@ -220,7 +221,7 @@ pub fn list(pending: &Mutex<PendingPairings>, config_path: &Path, id: Value) ->
         .collect();
     pending_list.sort_by(|a, b| a["created_ms"].as_u64().cmp(&b["created_ms"].as_u64()));
 
-    let tokens: Vec<Value> = load_paired_tokens(&paired_tokens_path(config_path))
+    let tokens: Vec<Value> = load_paired_tokens(&paired_tokens_path(state_dir))
         .iter()
         .map(|t| json!({ "id": t.id, "client_name": t.client_name, "created_ms": t.created_ms }))
         .collect();
@@ -232,7 +233,7 @@ pub fn list(pending: &Mutex<PendingPairings>, config_path: &Path, id: Value) ->
 /// mark the pending entry approved (so the requester's `pairing.poll` returns it).
 pub fn approve(
     pending: &Mutex<PendingPairings>,
-    config_path: &Path,
+    state_dir: &Path,
     id: Value,
     params: &Value,
 ) -> Value {
@@ -265,7 +266,7 @@ pub fn approve(
         client_name: client_name.clone(),
         created_ms: now,
     };
-    if let Err(e) = append_paired_token(&paired_tokens_path(config_path), &record) {
+    if let Err(e) = append_paired_token(&paired_tokens_path(state_dir), &record) {
         return control_error(
             id,
             ErrorCode::ControlError,
@@ -285,7 +286,7 @@ pub fn approve(
 
 /// GATED `control.pairing.revoke { token_id }` — remove an issued token; the gate
 /// rejects it immediately (the file is consulted per request).
-pub fn revoke(config_path: &Path, id: Value, params: &Value) -> Value {
+pub fn revoke(state_dir: &Path, id: Value, params: &Value) -> Value {
     let token_id = params
         .get("token_id")
         .or_else(|| params.get("id"))
@@ -298,7 +299,7 @@ pub fn revoke(config_path: &Path, id: Value, params: &Value) -> Value {
             "control.pairing.revoke requires params.token_id",
         );
     }
-    match revoke_paired_token(&paired_tokens_path(config_path), token_id) {
+    match revoke_paired_token(&paired_tokens_path(state_dir), token_id) {
         Ok(removed) => control_ok(id, json!({ "revoked": removed, "token_id": token_id })),
         Err(e) => control_error(
             id,
@@ -322,12 +323,10 @@ pub struct PairedToken {
     pub created_ms: u64,
 }
 
-/// Path to the paired-token store, given the node's config.json path.
-pub fn paired_tokens_path(config_path: &Path) -> PathBuf {
-    config_path
-        .parent()
-        .map(|p| p.join(PAIRED_TOKENS_FILE))
-        .unwrap_or_else(|| PathBuf::from(PAIRED_TOKENS_FILE))
+/// Path to the paired-token store within the machine-wide state dir (#501). `state_dir`
+/// is [`crate::state::state_dir`] (the same dir the control token lives in).
+pub fn paired_tokens_path(state_dir: &Path) -> PathBuf {
+    state_dir.join(PAIRED_TOKENS_FILE)
 }
 
 /// Load the issued paired tokens (missing/blank/malformed file → empty).
@@ -348,10 +347,11 @@ pub fn load_paired_tokens(path: &Path) -> Vec<PairedToken> {
         .unwrap_or_default()
 }
 
-/// Persist the token list atomically + owner-only.
+/// Persist the token list atomically + owner-only. The state dir is created with a
+/// restrictive ACL (#501) — the paired tokens are as sensitive as the master token.
 fn save_paired_tokens(path: &Path, tokens: &[PairedToken]) -> std::io::Result<()> {
     if let Some(dir) = path.parent() {
-        std::fs::create_dir_all(dir)?;
+        crate::state::ensure_dir_restricted(dir)?;
     }
     let bytes = serde_json::to_vec_pretty(&json!({ "tokens": tokens })).unwrap_or_default();
     crate::control::write_atomic(path, &bytes)?;
@@ -393,6 +393,9 @@ pub fn is_paired_token(path: &Path, presented: &str) -> bool {
 mod tests {
     use super::*;
 
+    /// A unique temp STATE dir (#501: the paired-token store now lives in the state
+    /// dir, not beside a `config.json`). Returns `(state_dir, state_dir)` so both
+    /// tuple bindings point at the dir a test seeds + cleans.
     fn tmp_config() -> (PathBuf, PathBuf) {
         // A process-wide counter makes the dir unique even when two tests build it in
         // the same millisecond (parallel test threads) — otherwise one test's
@@ -407,7 +410,7 @@ mod tests {
         ));
         let _ = std::fs::remove_dir_all(&dir);
         std::fs::create_dir_all(&dir).unwrap();
-        (dir.join("config.json"), dir)
+        (dir.clone(), dir)
     }
 
     fn pending() -> Mutex<PendingPairings> {
diff --git a/crates/dig-node-service/src/server.rs b/crates/dig-node-service/src/server.rs
index 4126670..f86880e 100644
--- a/crates/dig-node-service/src/server.rs
+++ b/crates/dig-node-service/src/server.rs
@@ -62,8 +62,13 @@ pub struct AppState {
     /// The node's config.json path — where the service's pin registry + upstream
     /// override live (the CONTROL plane reads/writes here).
     config_path: std::path::PathBuf,
+    /// The machine-wide daemon STATE dir (#501) — where the control token +
+    /// `paired-tokens.json` live, resolved IDENTICALLY by the daemon and the operator
+    /// CLI regardless of OS user (see [`crate::state`]). Distinct from `config_path`:
+    /// the bulk per-user cache + `config.json` stay per-user; only the auth state moves here.
+    state_dir: std::path::PathBuf,
     /// The local control token: a same-host controller must present it on every
-    /// `control.*` call. Generated at startup into `<config_dir>/control-token`
+    /// `control.*` call. Generated at startup into `<state_dir>/control-token`
     /// (loopback-only + locally-authorized gate — see [`crate::control`]).
     control_token: String,
     /// Whether authenticated §21 whole-store sync is available (a §21 identity is
@@ -225,7 +230,7 @@ async fn host_guard(req: Request, next: Next) -> Response {
 
 /// Construct the shared state from config: apply the upstream to dig-node's env,
 /// then build the node from the environment (cache dir/cap, §21 identity), and
-/// generate/load the local control token into the node's config dir.
+/// generate/load the local control token into the machine-wide state dir (#501).
 pub async fn build_state(config: &Config) -> AppState {
     config.apply_to_env();
     let node = Node::from_env();
@@ -242,7 +247,7 @@ pub async fn build_state(config: &Config) -> AppState {
         },
     )
     .await;
-    // Generate (or read) the control token into <config_dir>/control-token. A
+    // Generate (or read) the control token into <state_dir>/control-token (#501). A
     // failure to persist it (e.g. unwritable dir) is non-fatal: fall back to an
     // in-memory token so the control plane is still gated (a controller that can't
     // read the file simply can't authorize — fail-closed). The read plane is
@@ -250,7 +255,7 @@ pub async fn build_state(config: &Config) -> AppState {
     let control_token = control::load_or_create_token().unwrap_or_else(|e| {
         eprintln!(
             "dig-node: WARN could not persist control token ({e}); using an in-memory \
-             token (control.* will be unauthorizable until the config dir is writable)"
+             token (control.* will be unauthorizable until the state dir is writable)"
         );
         // A random in-memory token nothing can present → control plane fails closed.
         control::load_or_create_token_at(
@@ -258,6 +263,9 @@ pub async fn build_state(config: &Config) -> AppState {
         )
         .unwrap_or_default()
     });
+    // The machine-wide state dir the control token + paired-token store live in (#501). The
+    // daemon and the operator CLI resolve this SAME dir regardless of OS user — the whole fix.
+    let state_dir = crate::state::state_dir();
     AppState {
         node,
         upstream: config.upstream.clone(),
@@ -267,6 +275,7 @@ pub async fn build_state(config: &Config) -> AppState {
             .expect("dig-node: build http client"),
         addr: config.bind_addr(),
         config_path,
+        state_dir,
         control_token,
         // Node::from_env loads/creates the §21.9 identity, enabling authenticated
         // whole-store sync; we report it available and let the per-capsule fetch
@@ -296,6 +305,7 @@ fn control_ctx(state: &AppState) -> ControlCtx {
     ControlCtx {
         node: state.node.clone(),
         config_path: state.config_path.clone(),
+        state_dir: state.state_dir.clone(),
         addr: state.addr.clone(),
         upstream: state.upstream.clone(),
         started: state.started,
@@ -558,7 +568,7 @@ async fn rpc(
         let master_ok = control::is_authorized(&method, presented.as_deref(), &state.control_token);
         let paired_ok = !control::is_pairing_admin_method(&method)
             && presented.as_deref().is_some_and(|tok| {
-                pairing::is_paired_token(&pairing::paired_tokens_path(&state.config_path), tok)
+                pairing::is_paired_token(&pairing::paired_tokens_path(&state.state_dir), tok)
             });
         if !(master_ok || paired_ok) {
             return (
@@ -566,9 +576,13 @@ async fn rpc(
                 Json(control::control_error(
                     id,
                     ErrorCode::Unauthorized,
-                    "control.* requires the local control token (X-Dig-Control-Token \
-                     header or params._control_token, from <config_dir>/control-token), \
-                     or a paired controller token (see `dig-node pair`)",
+                    format!(
+                        "control.* requires the local control token (X-Dig-Control-Token \
+                         header or params._control_token, from {}), or a paired controller \
+                         token (see `dig-node pair`). {}",
+                        control::control_token_path().display(),
+                        control::control_token_remedy()
+                    ),
                 )),
             );
         }
@@ -591,7 +605,7 @@ async fn rpc(
             .get(control::CONTROL_TOKEN_HEADER)
             .and_then(|v| v.to_str().ok());
         let presented = control::presented_token(header_tok, &req);
-        let paired_path = pairing::paired_tokens_path(&state.config_path);
+        let paired_path = pairing::paired_tokens_path(&state.state_dir);
         let authorized =
             wallet_authz::authorize(&method, presented.as_deref(), &state.control_token, |tok| {
                 pairing::is_paired_token(&paired_path, tok)
@@ -714,7 +728,7 @@ fn presented_wallet_token(headers: &HeaderMap, body: &str) -> Option<String> {
 /// Whether a wallet-surface caller presenting `token` is authorized for `method` (§7.12): reads are
 /// open; every custody-lifecycle + mutation method needs the master control token OR a paired token.
 fn wallet_call_authorized(state: &AppState, method: &str, token: Option<&str>) -> bool {
-    let paired_path = pairing::paired_tokens_path(&state.config_path);
+    let paired_path = pairing::paired_tokens_path(&state.state_dir);
     wallet_authz::authorize(method, token, &state.control_token, |t| {
         pairing::is_paired_token(&paired_path, t)
     })
@@ -817,7 +831,7 @@ async fn ws_dispatch(
         let master_ok = control::is_authorized(method, token, &state.control_token);
         let paired_ok = !control::is_pairing_admin_method(method)
             && token.is_some_and(|t| {
-                pairing::is_paired_token(&pairing::paired_tokens_path(&state.config_path), t)
+                pairing::is_paired_token(&pairing::paired_tokens_path(&state.state_dir), t)
             });
         if !(master_ok || paired_ok) {
             return ws_err(
diff --git a/crates/dig-node-service/src/service.rs b/crates/dig-node-service/src/service.rs
index 81cdcfb..92bf0ee 100644
--- a/crates/dig-node-service/src/service.rs
+++ b/crates/dig-node-service/src/service.rs
@@ -179,7 +179,25 @@ pub fn install(config: &Config) -> std::io::Result<Outcome> {
     let mut environment = vec![
         ("DIG_NODE_PORT".to_string(), config.port.to_string()),
         ("DIG_RPC_UPSTREAM".to_string(), config.upstream.clone()),
+        // Mark the installed service as a SERVICE run (#501): the running daemon may bootstrap
+        // the machine-wide state dir when absent, whereas a bare CLI never does. On Windows this
+        // is belt-and-suspenders (the SCM `run-service` entrypoint also sets it); on
+        // systemd/launchd this env carries the signal into the unit.
+        (
+            crate::state::RUN_CONTEXT_ENV.to_string(),
+            crate::state::RUN_CONTEXT_SERVICE.to_string(),
+        ),
     ];
+    // Create the machine-wide state dir NOW, as the INSTALLING (interactive) user, so its
+    // restrictive ACL grants THAT user read access to the control token the service will write
+    // (#501). This is the key to the fix on Windows, where the service runs as LocalSystem and
+    // could not otherwise grant the operator's account read. Best-effort + cross-platform: on a
+    // user-level Linux/macOS install the daemon runs as the SAME user, so the legacy per-user
+    // fallback already keeps daemon + CLI in agreement and a failure to create `/var/lib/dig-node`
+    // (needs root) is expected and harmless.
+    if let Some(machine_dir) = crate::state::machine_state_dirs().into_iter().next() {
+        let _ = crate::state::ensure_dir_restricted(&machine_dir);
+    }
     // Only record DIG_NODE_HOST when the operator gave an EXPLICIT override
     // (#288): omitting it lets the installed service resolve the same default the
     // CLI would — bind BOTH loopback families (127.0.0.1 AND [::1], §5.2) —
diff --git a/crates/dig-node-service/src/state.rs b/crates/dig-node-service/src/state.rs
new file mode 100644
index 0000000..e84dd28
--- /dev/null
+++ b/crates/dig-node-service/src/state.rs
@@ -0,0 +1,422 @@
+//! The machine-wide DAEMON STATE directory — where the node's control/auth state
+//! (the control token + the paired-token store) lives, resolved IDENTICALLY by the
+//! running daemon AND the operator CLI regardless of which OS user each runs as
+//! (#501).
+//!
+//! # Why this exists (the bug it fixes)
+//!
+//! The bulk per-user cache ([`dig_node_core::cache_dir`], `%LOCALAPPDATA%\DigNode\cache`
+//! / `$HOME/DigNode/cache`) and the node `config.json` beside it are resolved from the
+//! RUNNING PROCESS's identity. That is correct for the shared `.dig` cache (#96), but it
+//! breaks the control token: on a real install the node runs as the Windows
+//! **LocalSystem** service, so it writes `control-token` under
+//! `C:\Windows\System32\config\systemprofile\AppData\Local\DigNode\` — a path the
+//! interactive user's `dig-node pair` can neither read nor even resolve (the user's
+//! `%LOCALAPPDATA%` is `C:\Users\<u>\AppData\Local`). The CLI then MINTS a different
+//! token the running node never trusts, so every `control.*` / `dig-node pair` call
+//! fails `-32030 UNAUTHORIZED`. The same split happens on Linux/macOS when the daemon
+//! runs as root/a service account and the operator is a normal user.
+//!
+//! # The fix
+//!
+//! A machine-wide, identity-INDEPENDENT [`state_dir`] holds ONLY the control/auth state
+//! (control token + `paired-tokens.json`). Because it does not depend on `%LOCALAPPDATA%`
+//! / `$HOME`, the daemon and the CLI resolve the SAME directory and read the SAME token.
+//! The bulk `cache_dir` and `config.json` are UNCHANGED (they stay per-user + shared with
+//! the browser/digstore, #96) — only the small security-critical auth state moves here.
+//!
+//! # Layout (per OS)
+//!
+//! - **Windows:** `%PROGRAMDATA%\DigNode` (`C:\ProgramData\DigNode`).
+//! - **macOS:** `/Library/Application Support/DigNode`.
+//! - **Linux:** `/var/lib/dig-node`, falling back to `/etc/dig-node` when the former is
+//!   not creatable/writable.
+//! - **Env override** `DIG_NODE_STATE_DIR` — for tests + custom deploys; wins outright.
+//! - **Dev fallback** — a non-service `dig-node run` as a normal user, with no machine-wide
+//!   dir present, uses the LEGACY per-user dir ([`legacy_state_dir`]) so existing dev
+//!   workflows keep working. (Additive: nothing that worked before breaks.)
+//!
+//! # Security (the crux — see [`ensure_dir_restricted`] / [`restrict_file`])
+//!
+//! The control token grants FULL local control of the node (mint controller tokens,
+//! change pins, drive wallet-adjacent control). A machine-wide file must therefore NOT be
+//! world/all-users-readable, or ANY local user could seize control (a local privilege
+//! escalation). The token dir + files are created with a restrictive ACL: owner/SYSTEM +
+//! Administrators full, the creating user read; nobody else. On Unix the files are `0600`
+//! and the dir `0700`; on Windows inherited ACEs are stripped (`icacls /inheritance:r`)
+//! and only SYSTEM + Administrators (+ the creating user) are granted — never the default
+//! `ProgramData` grant that lets all Users read.
+
+use std::path::{Path, PathBuf};
+
+/// The env var that overrides the resolved state dir outright (tests + custom deploys).
+pub const STATE_DIR_ENV: &str = "DIG_NODE_STATE_DIR";
+
+/// The env var the INSTALLED service carries so it self-identifies as a service run
+/// (set by `dig-node install` into the service environment, and by the Windows SCM
+/// entrypoint at runtime). Only a service run may CREATE the machine-wide dir when it is
+/// absent; the CLI never does (it only reads an existing one, else the legacy dir).
+pub const RUN_CONTEXT_ENV: &str = "DIG_NODE_RUN_CONTEXT";
+
+/// The value of [`RUN_CONTEXT_ENV`] that marks a service run.
+pub const RUN_CONTEXT_SERVICE: &str = "service";
+
+/// The machine-wide base folder name (Windows/macOS) — `DigNode` under `%PROGRAMDATA%` /
+/// `/Library/Application Support`. Linux uses the kebab `dig-node` path directly.
+const MACHINE_FOLDER: &str = "DigNode";
+
+/// The ordered machine-wide candidate directories for THIS OS (identity-independent).
+/// The first that already exists wins; a service run may create the first creatable one.
+/// PURE except for reading `%PROGRAMDATA%` on Windows (an env that does not vary by user).
+pub fn machine_state_dirs() -> Vec<PathBuf> {
+    #[cfg(windows)]
+    {
+        let base = std::env::var("PROGRAMDATA")
+            .ok()
+            .filter(|s| !s.trim().is_empty())
+            .unwrap_or_else(|| r"C:\ProgramData".to_string());
+        vec![PathBuf::from(base).join(MACHINE_FOLDER)]
+    }
+    #[cfg(target_os = "macos")]
+    {
+        vec![PathBuf::from("/Library/Application Support").join(MACHINE_FOLDER)]
+    }
+    #[cfg(all(unix, not(target_os = "macos")))]
+    {
+        // Linux (and other Unix): the FHS machine-state dir, then a common fallback.
+        vec![
+            PathBuf::from("/var/lib/dig-node"),
+            PathBuf::from("/etc/dig-node"),
+        ]
+    }
+}
+
+/// The LEGACY per-user state dir used before #501 (and still used for a non-service dev
+/// run): the parent of the node `config.json` (`%LOCALAPPDATA%\DigNode` /
+/// `$HOME/DigNode`). Kept as the back-compat fallback so an existing `dig-node run` as a
+/// normal user finds its old control token unchanged.
+pub fn legacy_state_dir() -> PathBuf {
+    let config = dig_node_core::config_path();
+    config
+        .parent()
+        .map(Path::to_path_buf)
+        .unwrap_or_else(|| PathBuf::from("."))
+}
+
+/// Whether THIS process is the installed service (so it may create the machine-wide dir
+/// when absent). Driven by [`RUN_CONTEXT_ENV`] — set by `dig-node install` into the
+/// service environment and by the Windows SCM entrypoint at runtime — so the CLI (which
+/// never carries it) is never treated as a service.
+pub fn running_as_service() -> bool {
+    std::env::var(RUN_CONTEXT_ENV)
+        .ok()
+        .map(|v| v.trim().eq_ignore_ascii_case(RUN_CONTEXT_SERVICE))
+        .unwrap_or(false)
+}
+
+/// PURE decision core (no I/O): pick the state dir from the inputs, so the priority is
+/// unit-testable without touching the real filesystem/env.
+///
+/// Priority: explicit `override_dir` › the first machine candidate that already EXISTS
+/// (daemon + CLI agree via the shared filesystem) › for a SERVICE run, the first machine
+/// candidate that can be created › the legacy per-user dir (dev fallback).
+fn choose_state_dir(
+    override_dir: Option<PathBuf>,
+    machine_candidates: &[PathBuf],
+    exists: &dyn Fn(&Path) -> bool,
+    can_create: &dyn Fn(&Path) -> bool,
+    is_service: bool,
+    legacy: PathBuf,
+) -> PathBuf {
+    if let Some(dir) = override_dir {
+        return dir;
+    }
+    // A machine dir that already exists is authoritative for EVERYONE on the box: the
+    // installer or a prior service run created it, and daemon + CLI see the same disk.
+    for c in machine_candidates {
+        if exists(c) {
+            return c.clone();
+        }
+    }
+    // Only the service may bootstrap the machine dir when it is absent — the CLI must not
+    // (a normal-user `dig-node pair` should never seed a machine-wide dir; it falls back
+    // to the legacy per-user dir it always used).
+    if is_service {
+        for c in machine_candidates {
+            if can_create(c) {
+                return c.clone();
+            }
+        }
+    }
+    legacy
+}
+
+/// The resolved machine-wide state dir for this process (see the module docs). Wires the
+/// real filesystem/env into [`choose_state_dir`]. A chosen MACHINE (or override) dir is
+/// created with a restrictive ACL as a side effect of resolution when this is a service
+/// run bootstrapping it; a chosen legacy dir is left to the token writer (its per-user
+/// location is already user-scoped, matching the pre-#501 behaviour).
+pub fn state_dir() -> PathBuf {
+    let override_dir = std::env::var(STATE_DIR_ENV)
+        .ok()
+        .map(|s| s.trim().to_string())
+        .filter(|s| !s.is_empty())
+        .map(PathBuf::from);
+    let candidates = machine_state_dirs();
+    let is_service = running_as_service();
+    let exists = |p: &Path| p.is_dir();
+    // "Can create" = we successfully created it with a restrictive ACL (idempotent).
+    let can_create = |p: &Path| ensure_dir_restricted(p).is_ok() && is_dir_writable(p);
+    choose_state_dir(
+        override_dir,
+        &candidates,
+        &exists,
+        &can_create,
+        is_service,
+        legacy_state_dir(),
+    )
+}
+
+/// Is `dir` writable? Probes with a unique temp file (created + removed). Used so a
+/// service run only claims a machine candidate it can actually write the token into.
+fn is_dir_writable(dir: &Path) -> bool {
+    let probe = dir.join(format!(".dig-state-probe-{}", std::process::id()));
+    match std::fs::write(&probe, b"") {
+        Ok(()) => {
+            let _ = std::fs::remove_file(&probe);
+            true
+        }
+        Err(_) => false,
+    }
+}
+
+/// Ensure `dir` exists with a RESTRICTIVE ACL so it is not world/all-users-readable — the
+/// crux of the #501 security model. The tightening is applied ONLY when THIS call creates the
+/// dir fresh; an already-existing dir is left untouched so a later service run (as SYSTEM /
+/// root) does NOT clobber the ACL the INSTALLER carefully set (which grants the interactive
+/// install-user read — [`crate::service::install`]). On a fresh create: Unix `0700`; Windows
+/// inheritance-removed with only SYSTEM + Administrators (+ the creating user) granted, made
+/// inheritable so files created inside inherit the same tight ACL.
+///
+/// Whoever creates the dir FIRST fixes its ACL: an elevated `dig-node install` (running as the
+/// interactive user) grants that user read; a bare service bootstrap (running as SYSTEM/root)
+/// grants only the daemon identity, so a non-elevated operator CLI cannot read the token and
+/// gets the precise elevation/ACL remedy ([`crate::control::control_token_remedy`]).
+///
+/// Best-effort on the ACL step (a failure to tighten must not hard-fail node startup — the
+/// loopback bind + token possession are the primary gate), but the `create_dir_all` itself is
+/// surfaced so a caller can fall back to another candidate.
+pub fn ensure_dir_restricted(dir: &Path) -> std::io::Result<()> {
+    // Already present ⇒ trust its ACL (the installer, or a prior run, established it). Do NOT
+    // re-tighten: a SYSTEM/root service re-applying the ACL would drop the interactive user's
+    // explicit read grant, re-breaking #501 for the operator CLI.
+    if dir.is_dir() {
+        return Ok(());
+    }
+    std::fs::create_dir_all(dir)?;
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::PermissionsExt;
+        let _ = std::fs::set_permissions(dir, std::fs::Permissions::from_mode(0o700));
+    }
+    #[cfg(windows)]
+    {
+        windows_restrict(dir, true);
+    }
+    Ok(())
+}
+
+/// Restrict a control/auth FILE (the control token, the paired-token store) so it is NOT
+/// readable by every local user.
+///
+/// - **Unix:** set the file to `0600` (owner read/write only) — the CI-gated assertion path.
+/// - **Windows:** a NO-OP by design. The file INHERITS the tight, inheritable ACL of its
+///   parent state dir ([`ensure_dir_restricted`]), which is where the security boundary lives.
+///   Re-applying an explicit `icacls /inheritance:r` here would be actively harmful: when the
+///   daemon runs as SYSTEM it would grant only SYSTEM/Administrators and STRIP the interactive
+///   install-user's inherited read ACE, re-breaking #501 for the operator CLI. A freshly-created
+///   file under the restricted dir is already non-world-readable via inheritance.
+///
+/// Best-effort (a perms failure is ignored — the loopback bind + token possession are the
+/// primary gate; the dir ACL is defense-in-depth against local privilege escalation).
+pub(crate) fn restrict_file(path: &Path) {
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::PermissionsExt;
+        let _ = std::fs::set_permissions(path, std::fs::Permissions::from_mode(0o600));
+    }
+    #[cfg(not(unix))]
+    {
+        // Windows (and other): the parent dir's inheritable ACL governs — see the doc above.
+        let _ = path;
+    }
+}
+
+/// The current user's `DOMAIN\User` account name from the environment, for the Windows
+/// ACL grant (so the interactive user / dev who created the token can still read it).
+/// `None` when the environment does not carry it (then only SYSTEM + Administrators are
+/// granted, and the CLI must be run elevated to read the token — surfaced in the remedy
+/// hint).
+#[cfg(windows)]
+fn current_user_account() -> Option<String> {
+    let user = std::env::var("USERNAME").ok()?;
+    let user = user.trim();
+    if user.is_empty() {
+        return None;
+    }
+    match std::env::var("USERDOMAIN").ok().map(|d| d.trim().to_string()) {
+        Some(domain) if !domain.is_empty() => Some(format!("{domain}\\{user}")),
+        _ => Some(user.to_string()),
+    }
+}
+
+/// Apply a restrictive Windows ACL to `path` via `icacls` (no shell — args are passed
+/// directly). Removes inherited ACEs (`/inheritance:r`) and grants ONLY SYSTEM
+/// (`*S-1-5-18`) + Administrators (`*S-1-5-32-544`) full, plus the creating user. For a
+/// directory the grants are made inheritable (`(OI)(CI)`) so files created inside inherit
+/// the same tight ACL. Best-effort: a failure (icacls missing/blocked) is ignored — the
+/// loopback bind + possession model still hold, and Unix is the CI-gated assertion path.
+#[cfg(windows)]
+fn windows_restrict(path: &Path, is_dir: bool) {
+    let full = if is_dir { "(OI)(CI)(F)" } else { "(F)" };
+    let user_perm = if is_dir { "(OI)(CI)(R)" } else { "(R)" };
+    let mut cmd = std::process::Command::new("icacls");
+    cmd.arg(path)
+        .arg("/inheritance:r")
+        .arg("/grant:r")
+        .arg(format!("*S-1-5-18:{full}"))
+        .arg(format!("*S-1-5-32-544:{full}"));
+    if let Some(user) = current_user_account() {
+        cmd.arg(format!("{user}:{user_perm}"));
+    }
+    let _ = cmd
+        .stdout(std::process::Stdio::null())
+        .stderr(std::process::Stdio::null())
+        .status();
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn override_wins_over_everything() {
+        let chosen = choose_state_dir(
+            Some(PathBuf::from("/custom/state")),
+            &[PathBuf::from("/var/lib/dig-node")],
+            &|_p| true, // machine exists…
+            &|_p| true, // …and is creatable — override still wins.
+            true,
+            PathBuf::from("/home/u/.local/DigNode"),
+        );
+        assert_eq!(chosen, PathBuf::from("/custom/state"));
+    }
+
+    #[test]
+    fn existing_machine_dir_is_used_by_anyone_even_a_non_service() {
+        // The reported bug's fix: the CLI (is_service=false) MUST resolve the same
+        // machine dir the service created, so it reads the same control token.
+        let machine = PathBuf::from("/var/lib/dig-node");
+        let chosen = choose_state_dir(
+            None,
+            &[machine.clone()],
+            &|p| p == machine, // it already exists
+            &|_p| false,
+            false, // NOT a service (the operator CLI)
+            PathBuf::from("/home/u/.local/DigNode"),
+        );
+        assert_eq!(chosen, machine);
+    }
+
+    #[test]
+    fn service_creates_first_creatable_machine_candidate_when_none_exist() {
+        let primary = PathBuf::from("/var/lib/dig-node");
+        let fallback = PathBuf::from("/etc/dig-node");
+        let chosen = choose_state_dir(
+            None,
+            &[primary.clone(), fallback.clone()],
+            &|_p| false,          // none exist yet
+            &|p| p == fallback,   // only /etc is creatable here
+            true,                 // a service run
+            PathBuf::from("/home/u/.local/DigNode"),
+        );
+        assert_eq!(chosen, fallback, "picks the first creatable candidate");
+    }
+
+    #[test]
+    fn non_service_falls_back_to_legacy_when_no_machine_dir_exists() {
+        // A dev `dig-node run` as a normal user with no machine-wide dir keeps using the
+        // legacy per-user dir (no ProgramData pollution, existing workflow preserved).
+        let legacy = PathBuf::from("/home/u/.local/DigNode");
+        let chosen = choose_state_dir(
+            None,
+            &[PathBuf::from("/var/lib/dig-node")],
+            &|_p| false, // machine dir absent
+            &|_p| true,  // even if creatable, a non-service must NOT create it
+            false,       // dev run, not a service
+            legacy.clone(),
+        );
+        assert_eq!(chosen, legacy);
+    }
+
+    #[test]
+    fn service_falls_back_to_legacy_when_machine_dir_uncreatable() {
+        // A user-level Linux/macOS service that cannot create /var/lib falls back to the
+        // legacy per-user dir — which, since the service runs AS the installing user,
+        // is the SAME dir that user's CLI resolves, so they still agree.
+        let legacy = PathBuf::from("/home/u/.local/DigNode");
+        let chosen = choose_state_dir(
+            None,
+            &[PathBuf::from("/var/lib/dig-node"), PathBuf::from("/etc/dig-node")],
+            &|_p| false, // absent
+            &|_p| false, // uncreatable (no privilege)
+            true,        // a service run
+            legacy.clone(),
+        );
+        assert_eq!(chosen, legacy);
+    }
+
+    #[test]
+    fn machine_state_dirs_are_absolute_and_identity_independent() {
+        // Whatever the OS, the machine candidates must be absolute and must NOT contain a
+        // per-user segment (the whole point — they do not vary by the running user).
+        for d in machine_state_dirs() {
+            assert!(d.is_absolute(), "{d:?} must be absolute");
+            let s = d.to_string_lossy().to_lowercase();
+            assert!(
+                !s.contains("appdata") && !s.contains("/users/") && !s.contains("systemprofile"),
+                "{d:?} must be identity-independent"
+            );
+        }
+    }
+
+    #[test]
+    fn running_as_service_reads_the_run_context_env() {
+        // PURE-ish: exercised via the env contract. Save/restore so we don't leak state.
+        let prev = std::env::var(RUN_CONTEXT_ENV).ok();
+        std::env::set_var(RUN_CONTEXT_ENV, "service");
+        assert!(running_as_service());
+        std::env::set_var(RUN_CONTEXT_ENV, "SERVICE");
+        assert!(running_as_service(), "case-insensitive");
+        std::env::set_var(RUN_CONTEXT_ENV, "cli");
+        assert!(!running_as_service());
+        std::env::remove_var(RUN_CONTEXT_ENV);
+        assert!(!running_as_service(), "unset ⇒ not a service");
+        match prev {
+            Some(v) => std::env::set_var(RUN_CONTEXT_ENV, v),
+            None => std::env::remove_var(RUN_CONTEXT_ENV),
+        }
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn ensure_dir_restricted_is_0700_and_not_group_or_world_accessible() {
+        use std::os::unix::fs::PermissionsExt;
+        let dir = std::env::temp_dir().join(format!("dig-state-dir-{}-{}", std::process::id(), line!()));
+        let _ = std::fs::remove_dir_all(&dir);
+        ensure_dir_restricted(&dir).unwrap();
+        let mode = std::fs::metadata(&dir).unwrap().permissions().mode() & 0o777;
+        assert_eq!(mode, 0o700, "state dir must be owner-only (got {mode:o})");
+        let _ = std::fs::remove_dir_all(&dir);
+    }
+}
diff --git a/crates/dig-node-service/src/win_service.rs b/crates/dig-node-service/src/win_service.rs
index c8a65b6..24365a6 100644
--- a/crates/dig-node-service/src/win_service.rs
+++ b/crates/dig-node-service/src/win_service.rs
@@ -55,6 +55,15 @@ fn service_main(_args: Vec<OsString>) {
 /// The actual service body: register the control handler, report `Running`, run the
 /// HTTP server until `Stop`, then report `Stopped`.
 fn run_service() -> std::io::Result<()> {
+    // Self-identify as a SERVICE run (#501): this entrypoint is reached ONLY when the Windows
+    // SCM launches the installed service, so it is the authoritative place to mark the process
+    // as a service — the daemon may then bootstrap the machine-wide state dir
+    // (`%PROGRAMDATA%\DigNode`) if the installer did not pre-create it. Belt-and-suspenders with
+    // the same env `install` writes into the service environment.
+    std::env::set_var(
+        crate::state::RUN_CONTEXT_ENV,
+        crate::state::RUN_CONTEXT_SERVICE,
+    );
     let config = Config::from_env();
 
     // Channel the control handler signals on `Stop`; the server's graceful-shutdown
diff --git a/crates/dig-node-service/tests/content_serve.rs b/crates/dig-node-service/tests/content_serve.rs
index 085bf49..d681e89 100644
--- a/crates/dig-node-service/tests/content_serve.rs
+++ b/crates/dig-node-service/tests/content_serve.rs
@@ -109,6 +109,9 @@ async fn start_server(upstream: &str) -> (SocketAddr, PathBuf, EnvHold) {
     let cache = base.join("cache");
     std::fs::create_dir_all(&cache).unwrap();
     std::env::set_var("DIG_NODE_CACHE", &cache);
+    // Isolate the #501 control-token/paired-token state dir per test (identity-independent), so a
+    // host with a real machine state dir can't defeat the temp isolation.
+    std::env::set_var("DIG_NODE_STATE_DIR", &base);
     // Hermetic: disable the chain-anchored pin so the serve resolves against the requested root with
     // NO coinset call (the node-side gate only; a real deploy leaves the pin ON).
     std::env::set_var("DIG_NODE_PIN", "off");
diff --git a/crates/dig-node-service/tests/server.rs b/crates/dig-node-service/tests/server.rs
index 71fba47..cefeca1 100644
--- a/crates/dig-node-service/tests/server.rs
+++ b/crates/dig-node-service/tests/server.rs
@@ -142,6 +142,12 @@ async fn start_companion_full(upstream: &str) -> (SocketAddr, String, EnvHold) {
         std::fs::create_dir_all(&cache).expect("create test cache dir");
         std::env::set_var("DIG_NODE_CACHE", &cache);
         std::env::set_var("DIG_NODE_CACHE_CAP", "67108864");
+        // Isolate the control-token/paired-token STATE dir per test (#501): without this, on a
+        // host that already has a real machine state dir (`/var/lib/dig-node`, `%PROGRAMDATA%\
+        // DigNode`, …) the server + this test would resolve THAT shared dir instead of the temp
+        // one, losing isolation and clobbering across concurrent tests. DIG_NODE_STATE_DIR (the
+        // designed test/deploy override) pins it to this test's base dir, identity-independently.
+        std::env::set_var("DIG_NODE_STATE_DIR", &base);
         let state = dig_node_service::server::build_state(&config).await;
         // The token the server wrote (read from disk, exactly as a real controller
         // would). config_path() resolves under the temp DIG_NODE_CACHE we just set.
@@ -178,6 +184,12 @@ async fn start_companion_wallet(
         std::fs::create_dir_all(&cache).expect("create test cache dir");
         std::env::set_var("DIG_NODE_CACHE", &cache);
         std::env::set_var("DIG_NODE_CACHE_CAP", "67108864");
+        // Isolate the control-token/paired-token STATE dir per test (#501): without this, on a
+        // host that already has a real machine state dir (`/var/lib/dig-node`, `%PROGRAMDATA%\
+        // DigNode`, …) the server + this test would resolve THAT shared dir instead of the temp
+        // one, losing isolation and clobbering across concurrent tests. DIG_NODE_STATE_DIR (the
+        // designed test/deploy override) pins it to this test's base dir, identity-independently.
+        std::env::set_var("DIG_NODE_STATE_DIR", &base);
         let state = dig_node_service::server::build_state(&config).await;
         let token = dig_node_service::control::load_or_create_token().unwrap();
         let backend = state.wallet_backend();
@@ -426,6 +438,8 @@ async fn dual_listener_serves_localhost_when_dig_local_bind_fails() {
         let tmp = std::env::temp_dir().join(format!("dig-node-dual-{}", std::process::id()));
         std::env::set_var("DIG_NODE_CACHE", &tmp);
         std::env::set_var("DIG_NODE_CACHE_CAP", "67108864");
+        // Isolate the #501 control-token/paired-token state dir per test (see the note above).
+        std::env::set_var("DIG_NODE_STATE_DIR", &tmp);
         // This test exercises the LISTENER bind fallback, not the peer network. Opt out of the
         // §14 peer-network bring-up (#213) so `serve_with_shutdown` stays hermetic here (no gossip
         // pool / DHT / relay reach). A dedicated test covers the peer-network wiring.
@@ -489,6 +503,8 @@ async fn dual_stack_loopback_serves_both_ipv4_and_ipv6_on_the_same_port() {
         let tmp = std::env::temp_dir().join(format!("dig-node-dualstack-{}", std::process::id()));
         std::env::set_var("DIG_NODE_CACHE", &tmp);
         std::env::set_var("DIG_NODE_CACHE_CAP", "67108864");
+        // Isolate the #501 control-token/paired-token state dir per test (see the note above).
+        std::env::set_var("DIG_NODE_STATE_DIR", &tmp);
         std::env::set_var("DIG_PEER_NETWORK", "off");
         tokio::spawn(async move {
             dig_node_service::server::serve_with_shutdown(config, async move {

From 064d8e91d0073a5fb12441e1398bbfe16b826ce3 Mon Sep 17 00:00:00 2001
From: Michael Taylor <michael@michaeltaylor.dev>
Date: Sun, 12 Jul 2026 19:39:58 -0700
Subject: [PATCH 2/6] fix(state): grant creator full ACL, derive Outcome Debug,
 doc state-dir in SPEC
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Windows ACL: grant the CREATING user full (not read-only) on the fresh state dir —
  the same process that creates the dir must be able to WRITE the token it mints
  (dev/self-create path failed with Access Denied otherwise). Security property held:
  every OTHER local user is still denied. Simplify windows_restrict_dir (dirs only).
- derive Debug on cli::Outcome (needed for the open.rs error-path test).
- Map io::ErrorKind::InvalidInput -> USAGE exit (a rejected `dig-node open` link).
- SPEC.md: new §7.3a (state-dir location/resolution/ACL/threat-model), §8.5
  (`open` scheme-handler contract), and control-token/paired-token/conformance/
  security updates to the state-dir model.

Refs #501 #389
Co-Authored-By: Claude <noreply@anthropic.com>
---
 SPEC.md                                | 117 +++++++++++++++++++++----
 crates/dig-node-service/src/cli.rs     |   1 +
 crates/dig-node-service/src/control.rs |   5 +-
 crates/dig-node-service/src/open.rs    |  11 ++-
 crates/dig-node-service/src/state.rs   |  66 +++++++++-----
 5 files changed, 152 insertions(+), 48 deletions(-)

diff --git a/SPEC.md b/SPEC.md
index 80baf28..4a2643c 100644
--- a/SPEC.md
+++ b/SPEC.md
@@ -761,21 +761,72 @@ token is NOT accepted for them.
 
 ### 7.3. The control token
 
-- File: `<config_dir>/control-token`, where `<config_dir>` is the parent of the read path's
-  `config.json`.
+- **File: `<state_dir>/control-token`** (§7.3a), where `<state_dir>` is the machine-wide, identity-
+  INDEPENDENT daemon state dir — NOT the per-user config dir. This is REQUIRED (#501): on a real
+  install the daemon runs as a service under a different OS account (Windows LocalSystem, a root
+  daemon) than the operator's interactive CLI. A per-user path resolves DIFFERENTLY for the two
+  identities, so the CLI would never see the token the service wrote (and would mint a phantom the
+  daemon never trusts). Resolving a machine-wide dir independently of the running user makes the
+  daemon and the CLI read the SAME token.
 - Value: 32 bytes of OS randomness rendered as 64 lowercase hex characters. Generated at first
-  run; subsequent runs (and other same-host processes) read the same value. On Unix the file MUST
-  be written with owner-only permissions (`0600`, best-effort). The token MUST never be committed
-  or logged.
+  run; subsequent runs (and other same-host processes/users) read the same value. The token MUST
+  never be committed or logged.
 - Presentation, either of (header preferred): the `X-Dig-Control-Token` request header, or the
   `params._control_token` field. Blank presentations are treated as absent.
-- If the token cannot be persisted (unwritable config dir), the node MUST fall back to an
+- **The daemon MAY create the token (write); an operator CLI MUST NOT mint one.** The CLI
+  (`dig-node pair` / any control tool) reads the token READ-ONLY; if it is missing or unreadable it
+  MUST fail with a precise remedy (§7.3a) rather than write a fresh token the daemon does not trust.
+- If the token cannot be persisted (unwritable state dir), the daemon MUST fall back to an
   in-memory token that no controller can read — the control plane fails **closed**; the read plane
   is unaffected.
 - Randomness source: the kernel CSPRNG (`/dev/urandom`) on Unix; elsewhere a non-deterministic
   mixed fallback. The security model is *possession of a same-host-readable file*, layered on the
   loopback bind — not secrecy from a network attacker.
 
+### 7.3a. The daemon state dir — location, ACL, threat model (#501)
+
+The state dir holds ONLY the control/auth state — the control token (§7.3) and the paired-token
+store (`paired-tokens.json`, §7.11). The bulk per-user `.dig` cache and `config.json` (§3.5–3.6) do
+NOT move; they stay per-user (shared with the browser/digstore, #96).
+
+**Resolution order** (the daemon and every operator CLI MUST resolve this identically, so it MUST
+NOT depend on `$HOME`/`%LOCALAPPDATA%`/the running user):
+
+1. `DIG_NODE_STATE_DIR` (env override) — wins outright (tests + custom deploys).
+2. The first machine-wide candidate that already EXISTS — Windows `%PROGRAMDATA%\DigNode`
+   (`C:\ProgramData\DigNode`); Linux `/var/lib/dig-node` then `/etc/dig-node`; macOS
+   `/Library/Application Support/DigNode`.
+3. Only for a SERVICE run (self-identified via `DIG_NODE_RUN_CONTEXT=service`): the first
+   machine-wide candidate it can create. A bare CLI MUST NOT create a machine-wide dir.
+4. Else the LEGACY per-user dir (the parent of `config.json`) — the back-compat fallback that keeps
+   a non-service `dig-node run` as a normal user working exactly as before (additive).
+
+**Creation + ACL.** Whoever creates the state dir FIRST fixes its ACL, applied ONLY on fresh
+creation (a pre-existing dir is left untouched so a later SYSTEM/root service run cannot clobber the
+installer's grant):
+
+- **Unix:** dir `0700`, token file `0600`. NEVER group/world-readable (`0644` is forbidden).
+- **Windows:** inheritance removed (`icacls /inheritance:r`) and inheritable full granted to EXACTLY
+  three trustees — SYSTEM, Administrators, and the creating user — and NO ONE ELSE (never the
+  default `%PROGRAMDATA%` grant that lets all Users read). `dig-node install` (run elevated by the
+  interactive user) pre-creates the dir so THAT user is among the trustees and can read the token the
+  LocalSystem service later writes; the token file inherits the dir ACL.
+
+**Threat model.** The control token grants full local control of the node (mint controller tokens,
+change pins, drive wallet-adjacent control). A machine-wide file readable by every local user would
+be a local privilege-escalation vector — any user could seize control of a node running as another
+identity. The ACL above ensures every OTHER local user is denied; the creating user is granted full
+because it must write the token it mints (dev/self-create) and an elevated installer must retain
+read. The ACL is defense-in-depth layered on the loopback bind + token-possession model; a failure
+to tighten it (e.g. `icacls` unavailable) MUST NOT hard-fail node startup.
+
+**Degraded case + remedy.** When the daemon bootstraps the dir itself as SYSTEM/root (the installer
+did not pre-create it), the interactive user is not a trustee and cannot read the token. The
+`UNAUTHORIZED` (`-32030`) error and the operator CLI MUST then print the PRECISE remedy — the exact
+token path, and that it needs elevation (Administrator / `sudo`) or the install-user read ACL —
+rather than a generic hint. The CLI distinguishes token-present-but-unreadable (the service-vs-user
+split → "elevate / grant read") from token-absent ("start the node so it mints one").
+
 ### 7.4. Control methods
 
 All results/errors use the standard envelopes of §5.1. `storeId` and `rootHash` are canonical
@@ -827,7 +878,7 @@ same-host control token.
   cap/used. Node detection uses the §5.3 ladder (explicit `server.host` override > `dig.local` >
   `localhost:9778` > `rpc.dig.net`); the localhost tier MUST target the §3.2 default port `9778`.
 - **Token-gated management (a same-host process controller).** The mutating + privacy-sensitive
-  `control.*` methods require the control token from `<config_dir>/control-token` (§7.3). Only a
+  `control.*` methods require the control token from `<state_dir>/control-token` (§7.3/§7.3a). Only a
   process that can read that file — the DIG Browser "My Node" UI (a native process), the CLI, a local
   tool — can drive them. A sandboxed extension MUST NOT attempt to read the token; it MAY still CALL
   `control.status` and, on the canonical `-32030 UNAUTHORIZED` (§10), fall back to deep-linking a
@@ -854,7 +905,9 @@ a clean foreground node with zero out-of-band setup: it binds `127.0.0.1:$DIG_NO
 on Ctrl-C/SIGTERM (§9.5) so a test harness can `spawn → poll GET /health → drive control.* / read →
 signal-stop`. `DIG_NODE_PORT` MUST be honored so a test picks a free port; `DIG_NODE_DIGLOCAL=0`
 SHOULD be set in tests to skip the privileged `:80` dig.local bind. The control token for a
-token-gated test is read from `<config_dir>/control-token` after startup.
+token-gated test is read from `<state_dir>/control-token` after startup; a test SHOULD set
+`DIG_NODE_STATE_DIR` to an isolated temp dir (§7.3a) so its token/paired-token state is hermetic
+regardless of any real machine-wide state dir on the host.
 
 ### 7.9. Cache-method families (open `cache.*` vs gated `control.cache.*`)
 
@@ -915,7 +968,7 @@ eviction. These additive fields/methods complete that surface; all are `served:
 
 ### 7.11. Control-token pairing for browser controllers (#280)
 
-An MV3 browser extension cannot read the `<config_dir>/control-token` file, so it cannot drive
+An MV3 browser extension cannot read the `<state_dir>/control-token` file, so it cannot drive
 token-gated `control.*` mutations. PAIRING lets it obtain its OWN scoped, revocable controller token
 after LOCAL operator approval, WITHOUT ever exposing the master token. Two OPEN bootstrap methods +
 three MASTER-gated administration methods, all loopback-only.
@@ -936,8 +989,8 @@ three MASTER-gated administration methods, all loopback-only.
 - **`control.pairing.list`** → `{ pending: [{ pairing_id, pairing_code, client_name, created_ms,
   expires_ms }], tokens: [{ id, client_name, created_ms }] }`. The token VALUE is never listed.
 - **`control.pairing.approve { pairing_id }`** → `{ approved: true, client_name, token_id }`. Mints a
-  fresh 64-hex scoped token, PERSISTS it to `<config_dir>/paired-tokens.json` (owner-only, atomic),
-  and marks the pending entry approved so the requester's next `pairing.poll` returns it. Approval is
+  fresh 64-hex scoped token, PERSISTS it to `<state_dir>/paired-tokens.json` (§7.3a, restricted,
+  atomic), and marks the pending entry approved so the requester's next `pairing.poll` returns it. Approval is
   the CONSENT step: it requires the master token (a local file read), so only the machine's operator
   can grant a pairing.
 - **`control.pairing.revoke { token_id }`** → `{ revoked: bool, token_id }`. Removes the token; the
@@ -957,8 +1010,8 @@ origin is CORS-blocked from reading it (and blocked at preflight from sending a
 header). A paired token is SCOPED (it authorizes `control.*` mutations but not pairing administration)
 and REVOCABLE. All token comparisons are constant-time.
 
-**Paired-token store.** `<config_dir>/paired-tokens.json` = `{ "tokens": [{ id, token, client_name,
-created_ms }] }`, owner-only, atomic writes. The auth gate accepts the master token OR any token in
+**Paired-token store.** `<state_dir>/paired-tokens.json` (§7.3a) = `{ "tokens": [{ id, token,
+client_name, created_ms }] }`, restricted (dir ACL), atomic writes. The auth gate accepts the master token OR any token in
 this store (except for the pairing-administration methods).
 
 ### 7.12. Paired-token authorization for wallet methods (#370)
@@ -1002,7 +1055,30 @@ authorizes a mutation but NOT pairing administration; a revoked token is denied
 
 `run` (default when no subcommand; serves in the foreground and is the unix-service entrypoint) ·
 `run-service` (hidden; the Windows SCM entrypoint, §9.4; behaves as `run` off Windows) ·
-`install` · `uninstall` · `start` · `stop` · `status`.
+`install` · `uninstall` · `start` · `stop` · `status` · `pair` (§7.11) · `open` (§8.5).
+
+### 8.5. `open` — the OS scheme handler (#389)
+
+`dig-node open <link>` is the target the installer registers for the OS `chia://` and
+`urn:dig:chia:` protocol handlers (`dig-node open "%1"`). It is the OS-level fallback resolver for a
+DIG link that no in-browser DIG extension intercepted.
+
+- **Input.** Accepts ONLY `chia://<storeId>[:<root>][/<path>]` and
+  `urn:dig:chia:<storeId>[:<root>][/<path>]` (scheme match is case-insensitive). The store reference
+  MUST be canonical 64-hex (`storeId` or `storeId:root`).
+- **Untrusted-input validation (MUST).** The argument arrives from an OS handler and may be
+  attacker-influenced (a hostile page can invoke a registered scheme). The command MUST reject every
+  other scheme (`file:`, `javascript:`, `data:`, `http(s):`, …), shell metacharacters, control
+  characters, whitespace, and `..` path traversal, and MUST NOT pass the argument to a shell — the
+  resolved URL is launched via the OS "open a URL" facility with the URL as a SINGLE, non-shell argv
+  entry (Windows `rundll32 url.dll,FileProtocolHandler`, Linux `xdg-open`, macOS `open`). A rejected
+  link exits `USAGE` (2) and launches nothing.
+- **Behavior.** Opens the user's DEFAULT browser at the node's LOCAL serve URL
+  `http://<host>:<port>/s/<storeId>[:<root>]/<path>` (the §4.6 plaintext content route; host/port
+  from the node's own config, default `localhost:9778`), so the node — the resolver of record —
+  serves the content and any installed DIG extension can still verify it. It NEVER opens `chia://`
+  at the OS level (dig-node is itself the OS `chia://` handler, so that would recurse) and NEVER
+  opens a dig-node GUI (it has none). Under `--json`: `{ opened: true, url, store_id, root, path }`.
 
 ### 8.2. `--json` (global flag)
 
@@ -1168,10 +1244,17 @@ does offset/length arithmetic over untrusted serialized input).
 - **Read/control split:** read methods open to local consumers; `control.*` requires possession of
   the same-host capability file, compared in constant time, failing closed when unpersistable
   (§7.2–7.3).
+- **Machine-wide auth state, not world-readable:** the control token + paired-token store live in a
+  machine-wide state dir resolved identically by the daemon and the operator CLI, restricted by ACL
+  to SYSTEM + Administrators + the creating user (Unix `0700`/`0600`) — never all-users-readable, so
+  it is not a local privilege-escalation vector (§7.3a). The operator CLI reads the token read-only
+  and never mints a rival token.
+- **Untrusted scheme-handler input:** `dig-node open` (the OS `chia://`/`urn:dig:chia:` handler,
+  §8.5) strictly validates its argument and launches the resolved URL without a shell.
 - **Blind serving:** content reads return ciphertext + proofs; verification/decryption is the
   client's job (§1.3). The node never returns plaintext for content reads.
-- **No secrets in artifacts:** the control token is generated at runtime, owner-restricted on
-  Unix, and never committed or logged.
+- **No secrets in artifacts:** the control token is generated at runtime, ACL-restricted (§7.3a),
+  and never committed or logged.
 
 ---
 
@@ -1189,7 +1272,7 @@ does offset/length arithmetic over untrusted serialized input).
 | 8 | CLI exit codes + `--json` envelopes | Table §8.4; one JSON object on stdout | §8; `src/cli.rs`, `tests/cli.rs` |
 | 9 | Service label | `net.dignetwork.dig-node` across install/uninstall/start/stop/SCM dispatcher | §2.4, §9.4 |
 | 10 | Release assets | Dual-named `dig-node-*` + legacy `dig-companion-*`, identical bytes, per §11.3 matrix | §11; `.github/workflows/release.yml` |
-| 11 | Control-token scheme | `<config_dir>/control-token`, 64-hex, `X-Dig-Control-Token` / `params._control_token`, constant-time | §7.2–7.3 |
+| 11 | Control-token scheme | `<state_dir>/control-token` (machine-wide, ACL-restricted, §7.3a), 64-hex, `X-Dig-Control-Token` / `params._control_token`, constant-time | §7.2–7.3a |
 | 12 | Health/version/well-known shapes | §6 fields; additions additive only | §6; `src/meta.rs`, `src/server.rs` |
 | 13 | Subscription persistence | `<cache>/subscriptions.json` schema-versioned, atomic, cross-process-locked | §14.1; `subscription.rs` |
 | 14 | Autonomous sync fail-closed | chain-watch + gap-fill + read-path pin never serve/pull against an unconfirmable root | §14.2–14.4; `chainwatch.rs`, `lib.rs` |
diff --git a/crates/dig-node-service/src/cli.rs b/crates/dig-node-service/src/cli.rs
index 03846f9..e4a454c 100644
--- a/crates/dig-node-service/src/cli.rs
+++ b/crates/dig-node-service/src/cli.rs
@@ -121,6 +121,7 @@ impl ExitCode {
 /// stderr in the default mode) and a machine `result` object (folded into the
 /// `--json` success envelope). Service functions return this instead of printing
 /// directly, so main.rs renders ONE consistent surface for both audiences.
+#[derive(Debug)]
 pub struct Outcome {
     /// Human-readable, possibly multi-line, summary lines.
     pub summary: String,
diff --git a/crates/dig-node-service/src/control.rs b/crates/dig-node-service/src/control.rs
index b2ad109..e46e7af 100644
--- a/crates/dig-node-service/src/control.rs
+++ b/crates/dig-node-service/src/control.rs
@@ -1095,7 +1095,10 @@ mod tests {
             "remedy should mention the control token: {remedy}"
         );
         assert!(
-            remedy.contains("dig-node") || remedy.contains("state dir") || remedy.contains('/') || remedy.contains('\\'),
+            remedy.contains("dig-node")
+                || remedy.contains("state dir")
+                || remedy.contains('/')
+                || remedy.contains('\\'),
             "remedy should name a path or command: {remedy}"
         );
     }
diff --git a/crates/dig-node-service/src/open.rs b/crates/dig-node-service/src/open.rs
index 043bac6..d458066 100644
--- a/crates/dig-node-service/src/open.rs
+++ b/crates/dig-node-service/src/open.rs
@@ -157,7 +157,10 @@ pub fn normalize(input: &str) -> Result<DigLink, String> {
         return Err("empty link".to_string());
     }
     if let Some(bad) = s.chars().find(|c| c.is_control()) {
-        return Err(format!("control character not allowed (U+{:04X})", bad as u32));
+        return Err(format!(
+            "control character not allowed (U+{:04X})",
+            bad as u32
+        ));
     }
     if let Some(bad) = s.chars().find(|c| DISALLOWED.contains(c)) {
         return Err(format!("disallowed character in link: {bad:?}"));
@@ -336,11 +339,7 @@ mod tests {
         let url = serve_url(&cfg, &link);
         assert_eq!(
             url,
-            format!(
-                "http://localhost:9778/s/{}:{}/index.html",
-                store(),
-                root()
-            )
+            format!("http://localhost:9778/s/{}:{}/index.html", store(), root())
         );
     }
 
diff --git a/crates/dig-node-service/src/state.rs b/crates/dig-node-service/src/state.rs
index e84dd28..a21c52e 100644
--- a/crates/dig-node-service/src/state.rs
+++ b/crates/dig-node-service/src/state.rs
@@ -41,11 +41,13 @@
 //! The control token grants FULL local control of the node (mint controller tokens,
 //! change pins, drive wallet-adjacent control). A machine-wide file must therefore NOT be
 //! world/all-users-readable, or ANY local user could seize control (a local privilege
-//! escalation). The token dir + files are created with a restrictive ACL: owner/SYSTEM +
-//! Administrators full, the creating user read; nobody else. On Unix the files are `0600`
-//! and the dir `0700`; on Windows inherited ACEs are stripped (`icacls /inheritance:r`)
-//! and only SYSTEM + Administrators (+ the creating user) are granted — never the default
-//! `ProgramData` grant that lets all Users read.
+//! escalation). The token dir + files are created with a restrictive ACL granting EXACTLY
+//! SYSTEM + Administrators + the creating user, and NO ONE ELSE. On Unix the dir is `0700`
+//! and the token file `0600`; on Windows inherited ACEs are stripped (`icacls
+//! /inheritance:r`) and only those three trustees are granted (inheritable) — never the
+//! default `ProgramData` grant that lets all Users read. The creating user is granted full
+//! (it must write the token it mints, and an elevated installer must retain read); the
+//! security-critical property is that every OTHER local user is denied.
 
 use std::path::{Path, PathBuf};
 
@@ -221,7 +223,7 @@ pub fn ensure_dir_restricted(dir: &Path) -> std::io::Result<()> {
     }
     #[cfg(windows)]
     {
-        windows_restrict(dir, true);
+        windows_restrict_dir(dir);
     }
     Ok(())
 }
@@ -264,30 +266,42 @@ fn current_user_account() -> Option<String> {
     if user.is_empty() {
         return None;
     }
-    match std::env::var("USERDOMAIN").ok().map(|d| d.trim().to_string()) {
+    match std::env::var("USERDOMAIN")
+        .ok()
+        .map(|d| d.trim().to_string())
+    {
         Some(domain) if !domain.is_empty() => Some(format!("{domain}\\{user}")),
         _ => Some(user.to_string()),
     }
 }
 
-/// Apply a restrictive Windows ACL to `path` via `icacls` (no shell — args are passed
-/// directly). Removes inherited ACEs (`/inheritance:r`) and grants ONLY SYSTEM
-/// (`*S-1-5-18`) + Administrators (`*S-1-5-32-544`) full, plus the creating user. For a
-/// directory the grants are made inheritable (`(OI)(CI)`) so files created inside inherit
-/// the same tight ACL. Best-effort: a failure (icacls missing/blocked) is ignored — the
-/// loopback bind + possession model still hold, and Unix is the CI-gated assertion path.
+/// Apply a restrictive Windows ACL to the state DIR `path` via `icacls` (no shell — args are
+/// passed directly). Removes inherited ACEs (`/inheritance:r`) so the world-readable
+/// `%PROGRAMDATA%` default does NOT apply, then grants inheritable full (`(OI)(CI)(F)`) to
+/// EXACTLY three trustees and NO ONE ELSE: SYSTEM (`*S-1-5-18`), Administrators
+/// (`*S-1-5-32-544`), and the creating user.
+///
+/// The creating user gets FULL (not merely read): the SAME process that creates the dir must be
+/// able to WRITE the token file into it (the dev/self-create path), and when an elevated
+/// `dig-node install` creates the dir the interactive user must retain read afterwards — FULL is
+/// a superset of read and, critically, still denies every OTHER local user, which is the
+/// security property that matters (no local privilege escalation). When the daemon bootstraps the
+/// dir as SYSTEM/root, the interactive user is simply not among the three trustees, so a
+/// non-elevated operator CLI cannot read the token and gets the precise remedy. Inheritable, so
+/// the token file created inside inherits exactly this tight ACL. Best-effort: a failure (icacls
+/// missing/blocked) is ignored — the loopback bind + token possession remain the primary gate,
+/// and Unix `0700`/`0600` is the CI-gated assertion path.
 #[cfg(windows)]
-fn windows_restrict(path: &Path, is_dir: bool) {
-    let full = if is_dir { "(OI)(CI)(F)" } else { "(F)" };
-    let user_perm = if is_dir { "(OI)(CI)(R)" } else { "(R)" };
+fn windows_restrict_dir(path: &Path) {
+    const GRANT: &str = "(OI)(CI)(F)";
     let mut cmd = std::process::Command::new("icacls");
     cmd.arg(path)
         .arg("/inheritance:r")
         .arg("/grant:r")
-        .arg(format!("*S-1-5-18:{full}"))
-        .arg(format!("*S-1-5-32-544:{full}"));
+        .arg(format!("*S-1-5-18:{GRANT}"))
+        .arg(format!("*S-1-5-32-544:{GRANT}"));
     if let Some(user) = current_user_account() {
-        cmd.arg(format!("{user}:{user_perm}"));
+        cmd.arg(format!("{user}:{GRANT}"));
     }
     let _ = cmd
         .stdout(std::process::Stdio::null())
@@ -335,9 +349,9 @@ mod tests {
         let chosen = choose_state_dir(
             None,
             &[primary.clone(), fallback.clone()],
-            &|_p| false,          // none exist yet
-            &|p| p == fallback,   // only /etc is creatable here
-            true,                 // a service run
+            &|_p| false,        // none exist yet
+            &|p| p == fallback, // only /etc is creatable here
+            true,               // a service run
             PathBuf::from("/home/u/.local/DigNode"),
         );
         assert_eq!(chosen, fallback, "picks the first creatable candidate");
@@ -367,7 +381,10 @@ mod tests {
         let legacy = PathBuf::from("/home/u/.local/DigNode");
         let chosen = choose_state_dir(
             None,
-            &[PathBuf::from("/var/lib/dig-node"), PathBuf::from("/etc/dig-node")],
+            &[
+                PathBuf::from("/var/lib/dig-node"),
+                PathBuf::from("/etc/dig-node"),
+            ],
             &|_p| false, // absent
             &|_p| false, // uncreatable (no privilege)
             true,        // a service run
@@ -412,7 +429,8 @@ mod tests {
     #[test]
     fn ensure_dir_restricted_is_0700_and_not_group_or_world_accessible() {
         use std::os::unix::fs::PermissionsExt;
-        let dir = std::env::temp_dir().join(format!("dig-state-dir-{}-{}", std::process::id(), line!()));
+        let dir =
+            std::env::temp_dir().join(format!("dig-state-dir-{}-{}", std::process::id(), line!()));
         let _ = std::fs::remove_dir_all(&dir);
         ensure_dir_restricted(&dir).unwrap();
         let mode = std::fs::metadata(&dir).unwrap().permissions().mode() & 0o777;

From 3d4442e1d58b74c821312122377e48af8d47ba15 Mon Sep 17 00:00:00 2001
From: Michael Taylor <michael@michaeltaylor.dev>
Date: Sun, 12 Jul 2026 19:47:35 -0700
Subject: [PATCH 3/6] fix(state): clippy cloned-ref-to-slice in state_dir test
 (CI --all-targets)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 crates/dig-node-service/src/state.rs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/crates/dig-node-service/src/state.rs b/crates/dig-node-service/src/state.rs
index a21c52e..5fc18df 100644
--- a/crates/dig-node-service/src/state.rs
+++ b/crates/dig-node-service/src/state.rs
@@ -333,7 +333,7 @@ mod tests {
         let machine = PathBuf::from("/var/lib/dig-node");
         let chosen = choose_state_dir(
             None,
-            &[machine.clone()],
+            std::slice::from_ref(&machine),
             &|p| p == machine, // it already exists
             &|_p| false,
             false, // NOT a service (the operator CLI)

From 6828e28f8a76b207b2fedb839858619ed0ec2320 Mon Sep 17 00:00:00 2001
From: Michael Taylor <michael@michaeltaylor.dev>
Date: Sun, 12 Jul 2026 19:52:49 -0700
Subject: [PATCH 4/6] fix(state): gate MACHINE_FOLDER to win/macos (dead_code
 on Linux -D warnings)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 crates/dig-node-service/src/state.rs | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/crates/dig-node-service/src/state.rs b/crates/dig-node-service/src/state.rs
index 5fc18df..9ef538b 100644
--- a/crates/dig-node-service/src/state.rs
+++ b/crates/dig-node-service/src/state.rs
@@ -64,7 +64,9 @@ pub const RUN_CONTEXT_ENV: &str = "DIG_NODE_RUN_CONTEXT";
 pub const RUN_CONTEXT_SERVICE: &str = "service";
 
 /// The machine-wide base folder name (Windows/macOS) — `DigNode` under `%PROGRAMDATA%` /
-/// `/Library/Application Support`. Linux uses the kebab `dig-node` path directly.
+/// `/Library/Application Support`. Linux uses the kebab `dig-node` path directly, so this is
+/// only referenced on Windows + macOS (gated to avoid a dead-code lint on Linux).
+#[cfg(any(windows, target_os = "macos"))]
 const MACHINE_FOLDER: &str = "DigNode";
 
 /// The ordered machine-wide candidate directories for THIS OS (identity-independent).

From ee33f1b283ba71a68c1f6ece6648e09b41030275 Mon Sep 17 00:00:00 2001
From: Michael Taylor <michael@michaeltaylor.dev>
Date: Sun, 12 Jul 2026 21:47:52 -0700
Subject: [PATCH 5/6] fix(state): harden+verify machine state dir on service
 run (close ProgramData squat P0)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The control token grants FULL local control of the node, so its machine-wide
state dir (%PROGRAMDATA%\DigNode) must never be readable by Users/Everyone. On
Windows %PROGRAMDATA% lets BUILTIN\Users create subfolders, so a low-priv user
could pre-create C:\ProgramData\DigNode, become CREATOR OWNER (implicit
WRITE_DAC), and control the dir the node writes the control token into — a local
privilege escalation.

Previously choose_state_dir returned a pre-existing machine dir via the `exists`
branch WITHOUT hardening it, and ensure_dir_restricted early-returned on any
existing dir, so a squatted dir was trusted as-is.

Fix (coherent with dig-installer's daemon_dir.rs contract): on a SERVICE run,
before the token is written/read, harden+readback-verify the resolved MACHINE
state dir — setowner *S-1-5-18 (SYSTEM) -> /reset (purge foreign ACEs) ->
/inheritance:r + grant {SYSTEM:F, Administrators:F, and only-if-discoverable the
interactive install-user:R} -> parse `icacls`/Get-Acl readback and assert no
Users/Everyone/Authenticated-Users/Anonymous ACE, owner=SYSTEM, inheritance off,
no unexpected principal. A squatter-owned pre-existing dir is purged. FAIL
CLOSED: if the dir cannot be secured, the node refuses to serve control from it
(ephemeral dir + in-memory unauthorizable token), never writing the token into
an unsecured dir.

Grant principal comes from the CURRENT PROCESS TOKEN (whoami /user), never the
spoofable %USERNAME% env, and well-known group SIDs are rejected. A SYSTEM
service preserves an installer-set interactive read grant only on a TRUSTED
(SYSTEM/Administrators-owned) dir. The CLI (non-service) never hardens — it only
reads an existing machine dir, else the legacy per-user dir (unchanged). Dev
self-create keeps the creating user FULL so it can write the token it mints.

Pure argv builders, the SID reject, and the readback-assertion parser are
unit-tested (real ACL is not exercised in CI). SPEC.md §7.3a documents the
contract.

Co-Authored-By: Claude <noreply@anthropic.com>
---
 SPEC.md                                |  68 +-
 crates/dig-node-service/src/server.rs  |  88 ++-
 crates/dig-node-service/src/service.rs |  26 +-
 crates/dig-node-service/src/state.rs   | 865 ++++++++++++++++++++++---
 4 files changed, 920 insertions(+), 127 deletions(-)

diff --git a/SPEC.md b/SPEC.md
index 4a2643c..b6f6147 100644
--- a/SPEC.md
+++ b/SPEC.md
@@ -801,24 +801,60 @@ NOT depend on `$HOME`/`%LOCALAPPDATA%`/the running user):
 4. Else the LEGACY per-user dir (the parent of `config.json`) — the back-compat fallback that keeps
    a non-service `dig-node run` as a normal user working exactly as before (additive).
 
-**Creation + ACL.** Whoever creates the state dir FIRST fixes its ACL, applied ONLY on fresh
-creation (a pre-existing dir is left untouched so a later SYSTEM/root service run cannot clobber the
-installer's grant):
-
-- **Unix:** dir `0700`, token file `0600`. NEVER group/world-readable (`0644` is forbidden).
-- **Windows:** inheritance removed (`icacls /inheritance:r`) and inheritable full granted to EXACTLY
-  three trustees — SYSTEM, Administrators, and the creating user — and NO ONE ELSE (never the
-  default `%PROGRAMDATA%` grant that lets all Users read). `dig-node install` (run elevated by the
-  interactive user) pre-creates the dir so THAT user is among the trustees and can read the token the
-  LocalSystem service later writes; the token file inherits the dir ACL.
+**Creation + ACL — the HARDENING CONTRACT.** The state dir holds the control token that grants FULL
+local control, so its ACL MUST NOT be world/all-users-readable. On Windows this is the HARD case:
+`%PROGRAMDATA%` grants `BUILTIN\Users` "create subfolder", so ANY low-priv user can pre-create
+`C:\ProgramData\DigNode`, become its CREATOR OWNER, and keep `WRITE_DAC` forever — a naive
+`icacls /inheritance:r /grant:r` (which never resets OWNER nor purges foreign explicit ACEs) leaves
+that squatter able to rewrite the DACL and read the token → local privilege escalation. A
+pre-existing machine dir MUST therefore NOT be trusted blindly.
+
+On a SERVICE run (self-identified via `DIG_NODE_RUN_CONTEXT=service`), BEFORE the daemon writes or
+reads the control token, the resolved MACHINE state dir MUST be HARDENED and READBACK-VERIFIED:
+
+1. Resolve the interactive read-grant principal as a real SID from the CURRENT PROCESS TOKEN
+   (`whoami /user`), NEVER the spoofable `%USERNAME%`/`%USERDOMAIN%` env. REJECT it if it is a
+   well-known group/broad SID (`S-1-1-0` Everyone, `S-1-5-11` Authenticated Users, `S-1-5-7`
+   Anonymous, `S-1-5-32-545` Users) or SYSTEM (`S-1-5-18`). A LocalSystem service thus resolves NO
+   interactive grant; it instead PRESERVES an installer-set interactive read grant if one is
+   discoverable on a TRUSTED (SYSTEM/Administrators-owned) pre-existing dir.
+2. Create the dir if absent — but NEVER early-return when it already exists (a squatter may have
+   pre-created it); always run steps 3-6.
+3. Take ownership so the squatter loses `WRITE_DAC`: `icacls D /setowner *S-1-5-18 /T` (owner ⇒
+   SYSTEM). A pre-existing dir with an UNTRUSTED owner is PURGED (`remove_dir_all`) and recreated.
+4. Purge ALL foreign explicit ACEs: `icacls D /reset /T`.
+5. Lock the DACL: `icacls D /inheritance:r /grant:r *S-1-5-18:(OI)(CI)F *S-1-5-32-544:(OI)(CI)F` and,
+   only when a valid interactive read grant survived step 1, append `<user_sid>:(OI)(CI)R` (READ only
+   for the interactive user, never full). Principals are always addressed by SID literal, never the
+   localized name.
+6. READBACK-VERIFY (`Get-Acl`, SID-based) as the acceptance gate: NO Everyone/Users/Authenticated-
+   Users/Anonymous ACE; owner is SYSTEM (or Administrators); SYSTEM + Administrators present with
+   full; the interactive read grant present iff one was applied; NO principal beyond those; and
+   inheritance disabled. Any violation FAILS.
+7. FAIL CLOSED: if any of steps 3-6 fails, hardening returns an error, the dir is best-effort
+   DELETED, and the daemon MUST NOT write the token there — it falls back to an ephemeral, unshared
+   dir + a random in-memory token so the control plane is UNAUTHORIZABLE (never served from an
+   attacker-controlled dir). The read plane is unaffected.
+
+`dig-node install` (run elevated by the interactive user) applies the SAME hardening as the
+installing user, setting owner = SYSTEM and granting THAT user READ, so the LocalSystem service's
+startup harden later sees a TRUSTED dir and PRESERVES the grant. Idempotency: running the harden
+twice on a legit dir yields the same final ACL. On Unix the dir is `0700` and the token file `0600`,
+owned by the daemon identity (root on a real install under root-owned `/var/lib`, which is not
+squattable); the installer additionally best-effort `setfacl`s READ for the `SUDO_USER`.
+
+The CLI (non-service) NEVER hardens (it is not elevated) — it only READS an existing machine dir,
+else falls back to the LEGACY per-user dir. A non-service dev run on the legacy per-user dir does NOT
+invoke the machine-dir hardening (that dir is already user-scoped).
 
 **Threat model.** The control token grants full local control of the node (mint controller tokens,
-change pins, drive wallet-adjacent control). A machine-wide file readable by every local user would
-be a local privilege-escalation vector — any user could seize control of a node running as another
-identity. The ACL above ensures every OTHER local user is denied; the creating user is granted full
-because it must write the token it mints (dev/self-create) and an elevated installer must retain
-read. The ACL is defense-in-depth layered on the loopback bind + token-possession model; a failure
-to tighten it (e.g. `icacls` unavailable) MUST NOT hard-fail node startup.
+change pins, drive wallet-adjacent control). A machine-wide file readable by every local user, or one
+sitting in a squatter-controlled dir, would be a local privilege-escalation vector — any user could
+seize control of a node running as another identity. The invariant that MUST hold either way is: NO
+Users/Everyone/Authenticated-Users ACE and owner = SYSTEM. The ACL is defense-in-depth layered on the
+loopback bind + token-possession model, BUT because a loose ACL is itself a priv-esc, the SERVICE-run
+harden is FAIL-CLOSED (unlike the best-effort dev/self-create path, where an `icacls`-unavailable
+tighten failure does not hard-fail startup).
 
 **Degraded case + remedy.** When the daemon bootstraps the dir itself as SYSTEM/root (the installer
 did not pre-create it), the interactive user is not a trustee and cannot read the token. The
diff --git a/crates/dig-node-service/src/server.rs b/crates/dig-node-service/src/server.rs
index f86880e..adb1522 100644
--- a/crates/dig-node-service/src/server.rs
+++ b/crates/dig-node-service/src/server.rs
@@ -231,6 +231,65 @@ async fn host_guard(req: Request, next: Next) -> Response {
 /// Construct the shared state from config: apply the upstream to dig-node's env,
 /// then build the node from the environment (cache dir/cap, §21 identity), and
 /// generate/load the local control token into the machine-wide state dir (#501).
+/// Resolve the machine-wide state dir + the control token, applying the #501 hardening on a
+/// SERVICE run and FAILING CLOSED when the machine dir cannot be secured.
+///
+/// - **Service run:** [`crate::state::ensure_service_state_dir`] hardens + readback-verifies
+///   the machine dir (owner→SYSTEM, purge foreign ACEs, protected DACL, no Users/Everyone
+///   ACE) BEFORE the token is written. If it cannot be secured, the node does NOT write the
+///   token there — it falls back to an ephemeral, unshared dir + a random in-memory token so
+///   the control plane is unauthorizable (never served from an attacker-controlled dir).
+/// - **CLI / dev run:** unchanged — resolve (read an existing machine dir, else the legacy
+///   per-user dir), never harden. A persist failure also fails closed to the in-memory token.
+fn resolve_state_dir_and_token() -> (std::path::PathBuf, String) {
+    // The ephemeral fail-closed fallback: an unshared temp dir + a random in-memory token
+    // that nothing can present → the control plane is unauthorizable.
+    let ephemeral = || {
+        let dir =
+            std::env::temp_dir().join(format!("dig-node-control-token-{}", std::process::id()));
+        let token = control::load_or_create_token_at(&dir.join(control::CONTROL_TOKEN_FILE))
+            .unwrap_or_default();
+        (dir, token)
+    };
+
+    if crate::state::running_as_service() {
+        match crate::state::ensure_service_state_dir() {
+            Ok(dir) => {
+                match control::load_or_create_token_at(&dir.join(control::CONTROL_TOKEN_FILE)) {
+                    Ok(token) => (dir, token),
+                    Err(e) => {
+                        eprintln!(
+                            "dig-node: WARN could not persist the control token in the secured \
+                         state dir ({e}); using an in-memory token (control.* unauthorizable)"
+                        );
+                        ephemeral()
+                    }
+                }
+            }
+            Err(e) => {
+                eprintln!(
+                    "dig-node: WARN could not secure the machine state dir ({e}); refusing to \
+                     serve the control plane from it — {}",
+                    control::control_token_remedy()
+                );
+                ephemeral()
+            }
+        }
+    } else {
+        let dir = crate::state::state_dir();
+        match control::load_or_create_token() {
+            Ok(token) => (dir, token),
+            Err(e) => {
+                eprintln!(
+                    "dig-node: WARN could not persist control token ({e}); using an in-memory \
+                     token (control.* will be unauthorizable until the state dir is writable)"
+                );
+                ephemeral()
+            }
+        }
+    }
+}
+
 pub async fn build_state(config: &Config) -> AppState {
     config.apply_to_env();
     let node = Node::from_env();
@@ -247,25 +306,16 @@ pub async fn build_state(config: &Config) -> AppState {
         },
     )
     .await;
-    // Generate (or read) the control token into <state_dir>/control-token (#501). A
-    // failure to persist it (e.g. unwritable dir) is non-fatal: fall back to an
-    // in-memory token so the control plane is still gated (a controller that can't
-    // read the file simply can't authorize — fail-closed). The read plane is
-    // unaffected either way.
-    let control_token = control::load_or_create_token().unwrap_or_else(|e| {
-        eprintln!(
-            "dig-node: WARN could not persist control token ({e}); using an in-memory \
-             token (control.* will be unauthorizable until the state dir is writable)"
-        );
-        // A random in-memory token nothing can present → control plane fails closed.
-        control::load_or_create_token_at(
-            &std::env::temp_dir().join(format!("dig-node-control-token-{}", std::process::id())),
-        )
-        .unwrap_or_default()
-    });
-    // The machine-wide state dir the control token + paired-token store live in (#501). The
-    // daemon and the operator CLI resolve this SAME dir regardless of OS user — the whole fix.
-    let state_dir = crate::state::state_dir();
+    // Resolve the machine-wide state dir the control token + paired-token store live in
+    // (#501). On a SERVICE run this HARDENS + readback-verifies the machine dir per the
+    // security contract BEFORE the token is written into it (owner→SYSTEM, purge foreign
+    // ACEs, protected DACL, no Users/Everyone ACE) — closing the ProgramData squatting hole
+    // where a low-priv user pre-creates C:\ProgramData\DigNode and keeps CREATOR OWNER /
+    // WRITE_DAC. If the dir cannot be secured, the node MUST NOT write the token there:
+    // it fails closed onto an ephemeral, unshared dir + an in-memory token so the control
+    // plane is unauthorizable rather than served from an attacker-controlled dir. The read
+    // plane is unaffected either way. The CLI (non-service) never hardens — it only reads.
+    let (state_dir, control_token) = resolve_state_dir_and_token();
     AppState {
         node,
         upstream: config.upstream.clone(),
diff --git a/crates/dig-node-service/src/service.rs b/crates/dig-node-service/src/service.rs
index 92bf0ee..e3e371b 100644
--- a/crates/dig-node-service/src/service.rs
+++ b/crates/dig-node-service/src/service.rs
@@ -188,15 +188,25 @@ pub fn install(config: &Config) -> std::io::Result<Outcome> {
             crate::state::RUN_CONTEXT_SERVICE.to_string(),
         ),
     ];
-    // Create the machine-wide state dir NOW, as the INSTALLING (interactive) user, so its
-    // restrictive ACL grants THAT user read access to the control token the service will write
-    // (#501). This is the key to the fix on Windows, where the service runs as LocalSystem and
-    // could not otherwise grant the operator's account read. Best-effort + cross-platform: on a
-    // user-level Linux/macOS install the daemon runs as the SAME user, so the legacy per-user
-    // fallback already keeps daemon + CLI in agreement and a failure to create `/var/lib/dig-node`
-    // (needs root) is expected and harmless.
+    // HARDEN the machine-wide state dir NOW, as the INSTALLING (interactive) user, per the
+    // #501 contract: owner→SYSTEM, purge foreign ACEs, protected DACL granting SYSTEM +
+    // Administrators full AND this interactive user READ, then readback-verify. Setting the
+    // owner to SYSTEM here means the LocalSystem service's own startup harden later sees a
+    // TRUSTED dir and PRESERVES this interactive read grant (rather than purging it), so the
+    // operator's `dig-node pair` can read the token the service writes. Best-effort + cross-
+    // platform: on a user-level Linux/macOS install the daemon runs as the SAME user, so the
+    // legacy per-user fallback already keeps daemon + CLI in agreement, and a failure to
+    // create/secure `/var/lib/dig-node` (needs root) is expected — the service re-secures it
+    // at startup regardless.
     if let Some(machine_dir) = crate::state::machine_state_dirs().into_iter().next() {
-        let _ = crate::state::ensure_dir_restricted(&machine_dir);
+        let grant = crate::state::interactive_read_grant();
+        if let Err(e) = crate::state::harden_state_dir(&machine_dir, grant.as_deref()) {
+            eprintln!(
+                "dig-node: WARN could not harden {} during install ({e}); the service will \
+                 re-secure it at startup",
+                machine_dir.display()
+            );
+        }
     }
     // Only record DIG_NODE_HOST when the operator gave an EXPLICIT override
     // (#288): omitting it lets the installed service resolve the same default the
diff --git a/crates/dig-node-service/src/state.rs b/crates/dig-node-service/src/state.rs
index 9ef538b..711944c 100644
--- a/crates/dig-node-service/src/state.rs
+++ b/crates/dig-node-service/src/state.rs
@@ -36,18 +36,44 @@
 //!   dir present, uses the LEGACY per-user dir ([`legacy_state_dir`]) so existing dev
 //!   workflows keep working. (Additive: nothing that worked before breaks.)
 //!
-//! # Security (the crux — see [`ensure_dir_restricted`] / [`restrict_file`])
+//! # Security (the crux — the #501 hardening contract, [`harden_state_dir`])
 //!
 //! The control token grants FULL local control of the node (mint controller tokens,
 //! change pins, drive wallet-adjacent control). A machine-wide file must therefore NOT be
-//! world/all-users-readable, or ANY local user could seize control (a local privilege
-//! escalation). The token dir + files are created with a restrictive ACL granting EXACTLY
-//! SYSTEM + Administrators + the creating user, and NO ONE ELSE. On Unix the dir is `0700`
-//! and the token file `0600`; on Windows inherited ACEs are stripped (`icacls
-//! /inheritance:r`) and only those three trustees are granted (inheritable) — never the
-//! default `ProgramData` grant that lets all Users read. The creating user is granted full
-//! (it must write the token it mints, and an elevated installer must retain read); the
-//! security-critical property is that every OTHER local user is denied.
+//! world/all-users-readable, or ANY local user could seize control — a local privilege
+//! escalation.
+//!
+//! On Windows this is the HARD case: `%PROGRAMDATA%` grants `BUILTIN\Users` "create
+//! subfolder", so ANY low-priv user can pre-create `C:\ProgramData\DigNode` and become its
+//! CREATOR OWNER — and an owner keeps `WRITE_DAC` forever, so a naive
+//! `icacls /inheritance:r /grant:r` (which never resets OWNER and never purges foreign
+//! explicit ACEs) leaves the squatter able to rewrite the DACL and read the daemon's
+//! control token. A pre-existing dir must NOT be trusted blindly. On a SERVICE run,
+//! BEFORE the daemon writes/reads the control token, the resolved MACHINE state dir is
+//! therefore HARDENED + READBACK-VERIFIED ([`ensure_service_state_dir`] →
+//! [`harden_state_dir`]): a squatter-owned dir is purged, owner is forced to SYSTEM
+//! (`icacls /setowner *S-1-5-18 /T`), all foreign explicit ACEs are dropped
+//! (`icacls /reset /T`), and a PROTECTED DACL of exactly {SYSTEM:F, Administrators:F,
+//! and — only if discoverable — the interactive install-user:R} is applied
+//! (`icacls /inheritance:r /grant:r …` by SID), then the ACL is read back and asserted:
+//! owner is SYSTEM, inheritance is OFF, NO Everyone/Users/Authenticated-Users ACE, and only
+//! the granted principals are present. If any step fails, [`harden_state_dir`] FAILS CLOSED
+//! (returns `Err`) — the caller deletes the dir and refuses to serve the control plane from
+//! it (falling back to an unusable in-memory token) rather than writing the token into an
+//! unsecured dir.
+//!
+//! A SYSTEM/root service must NOT clobber a legit installer-set ACL that grants the
+//! interactive install-user READ. Idempotency reconciles this: SYSTEM + Administrators are
+//! granted full always, and an interactive read grant is preserved/re-added only when it is
+//! DISCOVERABLE on a TRUSTED (SYSTEM/Administrators-owned) pre-existing dir. The security
+//! invariant that holds EITHER way is: NO Users/Everyone/Authenticated-Users ACE and
+//! owner = SYSTEM.
+//!
+//! On Unix the dir is `0700` and the token file `0600`, owned by the daemon identity (root
+//! on a real install under root-owned `/var/lib`, which is not squattable). The CLI
+//! (non-service) NEVER hardens — it only READS an existing machine dir, else falls back to
+//! the legacy per-user dir. A non-service dev run on the legacy per-user dir does NOT invoke
+//! the machine-dir hardening (that dir is already user-scoped).
 
 use std::path::{Path, PathBuf};
 
@@ -56,8 +82,8 @@ pub const STATE_DIR_ENV: &str = "DIG_NODE_STATE_DIR";
 
 /// The env var the INSTALLED service carries so it self-identifies as a service run
 /// (set by `dig-node install` into the service environment, and by the Windows SCM
-/// entrypoint at runtime). Only a service run may CREATE the machine-wide dir when it is
-/// absent; the CLI never does (it only reads an existing one, else the legacy dir).
+/// entrypoint at runtime). Only a service run may CREATE + HARDEN the machine-wide dir when
+/// it is absent; the CLI never does (it only reads an existing one, else the legacy dir).
 pub const RUN_CONTEXT_ENV: &str = "DIG_NODE_RUN_CONTEXT";
 
 /// The value of [`RUN_CONTEXT_ENV`] that marks a service run.
@@ -69,6 +95,23 @@ pub const RUN_CONTEXT_SERVICE: &str = "service";
 #[cfg(any(windows, target_os = "macos"))]
 const MACHINE_FOLDER: &str = "DigNode";
 
+// ---------------------------------------------------------------------------
+// Well-known SIDs (locale-independent — icacls / Get-Acl accept + emit these).
+// ---------------------------------------------------------------------------
+
+/// LocalSystem — the daemon identity + the forced owner of the state dir.
+const SID_SYSTEM: &str = "S-1-5-18";
+/// BUILTIN\Administrators.
+const SID_ADMINISTRATORS: &str = "S-1-5-32-544";
+/// Everyone.
+const SID_EVERYONE: &str = "S-1-1-0";
+/// Authenticated Users.
+const SID_AUTHENTICATED_USERS: &str = "S-1-5-11";
+/// Anonymous Logon.
+const SID_ANONYMOUS: &str = "S-1-5-7";
+/// BUILTIN\Users.
+const SID_USERS: &str = "S-1-5-32-545";
+
 /// The ordered machine-wide candidate directories for THIS OS (identity-independent).
 /// The first that already exists wins; a service run may create the first creatable one.
 /// PURE except for reading `%PROGRAMDATA%` on Windows (an env that does not vary by user).
@@ -95,6 +138,14 @@ pub fn machine_state_dirs() -> Vec<PathBuf> {
     }
 }
 
+/// Is `dir` one of THIS OS's machine-wide state candidates? Only a machine dir is
+/// hardened (the legacy per-user dir is already user-scoped and a custom `DIG_NODE_STATE_DIR`
+/// override — e.g. a test temp dir — must NOT be purged/hardened). PURE given
+/// [`machine_state_dirs`].
+pub fn is_machine_state_dir(dir: &Path) -> bool {
+    machine_state_dirs().iter().any(|c| c == dir)
+}
+
 /// The LEGACY per-user state dir used before #501 (and still used for a non-service dev
 /// run): the parent of the node `config.json` (`%LOCALAPPDATA%\DigNode` /
 /// `$HOME/DigNode`). Kept as the back-compat fallback so an existing `dig-node run` as a
@@ -107,8 +158,8 @@ pub fn legacy_state_dir() -> PathBuf {
         .unwrap_or_else(|| PathBuf::from("."))
 }
 
-/// Whether THIS process is the installed service (so it may create the machine-wide dir
-/// when absent). Driven by [`RUN_CONTEXT_ENV`] — set by `dig-node install` into the
+/// Whether THIS process is the installed service (so it may create + harden the machine-wide
+/// dir when absent). Driven by [`RUN_CONTEXT_ENV`] — set by `dig-node install` into the
 /// service environment and by the Windows SCM entrypoint at runtime — so the CLI (which
 /// never carries it) is never treated as a service.
 pub fn running_as_service() -> bool {
@@ -156,10 +207,11 @@ fn choose_state_dir(
 }
 
 /// The resolved machine-wide state dir for this process (see the module docs). Wires the
-/// real filesystem/env into [`choose_state_dir`]. A chosen MACHINE (or override) dir is
-/// created with a restrictive ACL as a side effect of resolution when this is a service
-/// run bootstrapping it; a chosen legacy dir is left to the token writer (its per-user
-/// location is already user-scoped, matching the pre-#501 behaviour).
+/// real filesystem/env into [`choose_state_dir`]. This is a PATH resolver only: it does NOT
+/// harden a pre-existing machine dir (that is the SERVICE-only [`ensure_service_state_dir`]
+/// chokepoint — the CLI must never attempt to harden, being non-elevated). A service run
+/// that must BOOTSTRAP an absent machine dir creates the first creatable candidate here; the
+/// authoritative harden + readback-verify then runs in [`ensure_service_state_dir`].
 pub fn state_dir() -> PathBuf {
     let override_dir = std::env::var(STATE_DIR_ENV)
         .ok()
@@ -169,7 +221,8 @@ pub fn state_dir() -> PathBuf {
     let candidates = machine_state_dirs();
     let is_service = running_as_service();
     let exists = |p: &Path| p.is_dir();
-    // "Can create" = we successfully created it with a restrictive ACL (idempotent).
+    // "Can create" = we successfully created it (a restrictive best-effort ACL is applied on
+    // fresh create; the authoritative harden runs in `ensure_service_state_dir`).
     let can_create = |p: &Path| ensure_dir_restricted(p).is_ok() && is_dir_writable(p);
     choose_state_dir(
         override_dir,
@@ -181,6 +234,73 @@ pub fn state_dir() -> PathBuf {
     )
 }
 
+/// The SERVICE-run chokepoint (#501 P0): resolve the state dir and, when it is a MACHINE
+/// dir, HARDEN + readback-VERIFY it per the security contract BEFORE the control token is
+/// written into it. Returns the secured dir, or an `Err` when a machine dir cannot be
+/// secured — in which case the caller MUST refuse to serve the control plane from it (write
+/// nothing there; fall back to an unusable in-memory token).
+///
+/// A resolved LEGACY per-user dir (a user-level service that could not create `/var/lib`)
+/// is already user-scoped, so it is only created (not hardened) — the daemon and that same
+/// user's CLI still agree on it. MUST be called only on a service run (`debug_assert`ed).
+pub fn ensure_service_state_dir() -> std::io::Result<PathBuf> {
+    debug_assert!(
+        running_as_service(),
+        "ensure_service_state_dir is a service-only chokepoint"
+    );
+    let dir = state_dir();
+    if is_machine_state_dir(&dir) {
+        let read_grant = service_read_grant(&dir);
+        harden_state_dir(&dir, read_grant.as_deref())?;
+    } else {
+        // Legacy per-user (or override) dir — already user-scoped; just ensure it exists.
+        ensure_dir_restricted(&dir)?;
+    }
+    Ok(dir)
+}
+
+/// The read-grant principal for a SERVICE harden of `dir`: the interactive install-user's
+/// SID that should retain READ access to the control token.
+///
+/// 1. The CURRENT PROCESS TOKEN's user SID — but only when it is a REAL interactive user
+///    (a `dig-node install` run as the interactive admin). On a LocalSystem service this is
+///    SYSTEM (a forbidden grant) ⇒ `None`.
+/// 2. Otherwise, PRESERVE an installer-set interactive grant already discoverable on a
+///    TRUSTED (SYSTEM/Administrators-owned) pre-existing dir, so a later SYSTEM service run
+///    does not strip the operator's read ACE.
+/// 3. Else `None` — SYSTEM + Administrators only; a non-elevated operator CLI then needs
+///    elevation (surfaced via the precise remedy).
+#[cfg(windows)]
+fn service_read_grant(dir: &Path) -> Option<String> {
+    if let Some(sid) = current_user_sid() {
+        return Some(sid);
+    }
+    discover_existing_read_grant(dir)
+}
+
+/// Non-Windows: no ACL read-grant principal (Unix uses mode bits + a best-effort installer
+/// `setfacl`, handled by the installer, not here).
+#[cfg(not(windows))]
+fn service_read_grant(_dir: &Path) -> Option<String> {
+    None
+}
+
+/// The interactive read-grant SID for a `dig-node install` harden (the installing user, from
+/// the process token). `None` on non-Windows and when the process token is SYSTEM / a
+/// forbidden group. Used by [`crate::service`] to grant the operator READ so a later SYSTEM
+/// service run can PRESERVE that grant (via [`service_read_grant`] discovery on the
+/// SYSTEM-owned dir).
+#[cfg(windows)]
+pub fn interactive_read_grant() -> Option<String> {
+    current_user_sid()
+}
+
+/// Non-Windows: the interactive grant is expressed via the installer's `setfacl`, not here.
+#[cfg(not(windows))]
+pub fn interactive_read_grant() -> Option<String> {
+    None
+}
+
 /// Is `dir` writable? Probes with a unique temp file (created + removed). Used so a
 /// service run only claims a machine candidate it can actually write the token into.
 fn is_dir_writable(dir: &Path) -> bool {
@@ -194,26 +314,22 @@ fn is_dir_writable(dir: &Path) -> bool {
     }
 }
 
-/// Ensure `dir` exists with a RESTRICTIVE ACL so it is not world/all-users-readable — the
-/// crux of the #501 security model. The tightening is applied ONLY when THIS call creates the
-/// dir fresh; an already-existing dir is left untouched so a later service run (as SYSTEM /
-/// root) does NOT clobber the ACL the INSTALLER carefully set (which grants the interactive
-/// install-user read — [`crate::service::install`]). On a fresh create: Unix `0700`; Windows
-/// inheritance-removed with only SYSTEM + Administrators (+ the creating user) granted, made
-/// inheritable so files created inside inherit the same tight ACL.
+/// Ensure `dir` exists with a best-effort restrictive ACL — the create-path helper used
+/// during resolution ([`state_dir`]), by `dig-node install` pre-create, and by the token /
+/// paired-token writers. It is NOT the authoritative security gate: a pre-existing dir is
+/// trusted as-is (early return) so a SYSTEM/root service does not clobber the installer's
+/// interactive read grant. The AUTHORITATIVE harden + readback-verify of a machine dir on a
+/// service run is [`ensure_service_state_dir`] / [`harden_state_dir`].
 ///
-/// Whoever creates the dir FIRST fixes its ACL: an elevated `dig-node install` (running as the
-/// interactive user) grants that user read; a bare service bootstrap (running as SYSTEM/root)
-/// grants only the daemon identity, so a non-elevated operator CLI cannot read the token and
-/// gets the precise elevation/ACL remedy ([`crate::control::control_token_remedy`]).
-///
-/// Best-effort on the ACL step (a failure to tighten must not hard-fail node startup — the
-/// loopback bind + token possession are the primary gate), but the `create_dir_all` itself is
+/// On a fresh create: Unix `0700`; Windows a best-effort inheritable grant to SYSTEM +
+/// Administrators (+ the creating REAL user, by process-token SID). Best-effort on the ACL
+/// step (a tighten failure must not hard-fail this path — the loopback bind + token
+/// possession + the service-run harden are the primary gates); the `create_dir_all` is
 /// surfaced so a caller can fall back to another candidate.
 pub fn ensure_dir_restricted(dir: &Path) -> std::io::Result<()> {
-    // Already present ⇒ trust its ACL (the installer, or a prior run, established it). Do NOT
-    // re-tighten: a SYSTEM/root service re-applying the ACL would drop the interactive user's
-    // explicit read grant, re-breaking #501 for the operator CLI.
+    // Already present ⇒ trust its ACL here (the installer, a prior run, or the service-run
+    // harden established it). Do NOT re-tighten: a SYSTEM/root service re-applying an ACL via
+    // this best-effort path would drop the interactive user's explicit read grant.
     if dir.is_dir() {
         return Ok(());
     }
@@ -225,7 +341,7 @@ pub fn ensure_dir_restricted(dir: &Path) -> std::io::Result<()> {
     }
     #[cfg(windows)]
     {
-        windows_restrict_dir(dir);
+        windows_grant_best_effort(dir);
     }
     Ok(())
 }
@@ -235,11 +351,12 @@ pub fn ensure_dir_restricted(dir: &Path) -> std::io::Result<()> {
 ///
 /// - **Unix:** set the file to `0600` (owner read/write only) — the CI-gated assertion path.
 /// - **Windows:** a NO-OP by design. The file INHERITS the tight, inheritable ACL of its
-///   parent state dir ([`ensure_dir_restricted`]), which is where the security boundary lives.
-///   Re-applying an explicit `icacls /inheritance:r` here would be actively harmful: when the
-///   daemon runs as SYSTEM it would grant only SYSTEM/Administrators and STRIP the interactive
-///   install-user's inherited read ACE, re-breaking #501 for the operator CLI. A freshly-created
-///   file under the restricted dir is already non-world-readable via inheritance.
+///   parent state dir (established by the service-run harden, [`harden_state_dir`], or the
+///   installer), which is where the security boundary lives. Re-applying an explicit
+///   `icacls /inheritance:r` here would be actively harmful: when the daemon runs as SYSTEM it
+///   would grant only SYSTEM/Administrators and STRIP the interactive install-user's inherited
+///   read ACE, re-breaking #501 for the operator CLI. A freshly-created file under the
+///   restricted dir is already non-world-readable via inheritance.
 ///
 /// Best-effort (a perms failure is ignored — the loopback bind + token possession are the
 /// primary gate; the dir ACL is defense-in-depth against local privilege escalation).
@@ -256,56 +373,424 @@ pub(crate) fn restrict_file(path: &Path) {
     }
 }
 
-/// The current user's `DOMAIN\User` account name from the environment, for the Windows
-/// ACL grant (so the interactive user / dev who created the token can still read it).
-/// `None` when the environment does not carry it (then only SYSTEM + Administrators are
-/// granted, and the CLI must be run elevated to read the token — surfaced in the remedy
-/// hint).
+// ---------------------------------------------------------------------------
+// The hardening contract (#501): pure argv/parse helpers + the I/O orchestrator.
+// The SID parsing, the `icacls` argv builders, and the `Get-Acl` readback parser are
+// PURE and unit-tested; the create + ACL calls are the thin I/O layer (real ACL behaviour
+// is not exercised in CI, so correctness rests on careful code + the pure-logic tests).
+// ---------------------------------------------------------------------------
+
+/// A well-known GROUP / broad SID that must NEVER appear in the control-token dir's DACL
+/// (world/broad-group readable = the priv-esc the tight ACL exists to prevent).
+pub fn is_dangerous_group_sid(sid: &str) -> bool {
+    matches!(
+        sid,
+        SID_EVERYONE | SID_AUTHENTICATED_USERS | SID_ANONYMOUS | SID_USERS
+    )
+}
+
+/// May `sid` be the READ-grant principal (the interactive user)? Rejects the dangerous
+/// broad groups AND SYSTEM (the interactive identity must be a real user; SYSTEM is the
+/// daemon owner, never the interactive grantee). A spoofed `%USERNAME%=Everyone` used to
+/// yield `Everyone:(OI)(CI)R` — this is the guard against granting a group.
+pub fn is_forbidden_grant_sid(sid: &str) -> bool {
+    is_dangerous_group_sid(sid) || sid == SID_SYSTEM
+}
+
+/// Parse the interactive-user SID from `whoami /user /fo csv /nh` output —
+/// `"domain\user","S-1-5-21-…"`. The SID comes from the process TOKEN (not the spoofable
+/// `%USERNAME%`/`%USERDOMAIN%` env), so it cannot be forged by setting `%USERNAME%=Everyone`.
+/// Returns the first `S-1-…` field. PURE.
+pub fn parse_whoami_csv_sid(text: &str) -> Option<String> {
+    text.split([',', '"', '\r', '\n', ' ', '\t'])
+        .map(|f| f.trim())
+        .find(|f| f.starts_with("S-1-") && f.len() > 6)
+        .map(|s| s.to_string())
+}
+
+/// `icacls <dir> /setowner *S-1-5-18 /T /C /Q` — force owner = SYSTEM on the dir and every
+/// child, defeating a squatter's owner-based `WRITE_DAC`. PURE argv (no shell).
+pub fn setowner_system_args(dir: &str) -> Vec<String> {
+    vec![
+        dir.to_string(),
+        "/setowner".to_string(),
+        format!("*{SID_SYSTEM}"),
+        "/T".to_string(),
+        "/C".to_string(),
+        "/Q".to_string(),
+    ]
+}
+
+/// `icacls <dir> /reset /T /C /Q` — drop ALL explicit ACEs (purging any foreign ACE a
+/// squatter added) and restore the parent's inheritable ACEs, so the following
+/// `/inheritance:r /grant:r` starts from a known baseline. PURE argv.
+pub fn reset_dacl_args(dir: &str) -> Vec<String> {
+    vec![
+        dir.to_string(),
+        "/reset".to_string(),
+        "/T".to_string(),
+        "/C".to_string(),
+        "/Q".to_string(),
+    ]
+}
+
+/// `icacls <dir> /inheritance:r /grant:r …` that REPLACES the DACL with exactly
+/// {SYSTEM:F, Administrators:F} plus — only when `read_grant` is `Some` — {`read_grant`:R},
+/// inheritable to child files (the control-token), inheritance disabled. All principals by
+/// SID (locale-independent — the `*S-1-5-18` literal, never the localized name "SYSTEM").
+/// The interactive user gets READ only, never full. PURE so the exact ACL is unit-tested.
+pub fn windows_lockdown_grant_args(dir: &str, read_grant: Option<&str>) -> Vec<String> {
+    let mut args = vec![
+        dir.to_string(),
+        "/inheritance:r".to_string(),
+        "/grant:r".to_string(),
+        format!("*{SID_SYSTEM}:(OI)(CI)F"),
+        "/grant:r".to_string(),
+        format!("*{SID_ADMINISTRATORS}:(OI)(CI)F"),
+    ];
+    if let Some(sid) = read_grant {
+        args.push("/grant:r".to_string());
+        args.push(format!("*{sid}:(OI)(CI)R"));
+    }
+    args
+}
+
+/// The PowerShell one-liner that emits the dir's owner + each access ACE as SID-based lines
+/// (`OWNER;<sid>` / `ACE;<sid>;<isInherited>`) for the readback verification. SID-based (not
+/// name-based) so parsing is locale-independent. PURE (single-quotes in the path are doubled
+/// for PS literal safety).
+pub fn acl_verify_ps_command(dir: &str) -> String {
+    let dir = dir.replace('\'', "''");
+    format!(
+        "$ErrorActionPreference='Stop'; \
+         $acl = Get-Acl -LiteralPath '{dir}'; \
+         'OWNER;' + $acl.GetOwner([System.Security.Principal.SecurityIdentifier]).Value; \
+         foreach ($a in $acl.Access) {{ \
+           'ACE;' + $a.IdentityReference.Translate([System.Security.Principal.SecurityIdentifier]).Value + ';' + $a.IsInherited \
+         }}"
+    )
+}
+
+/// Verify a locked-down DACL from [`acl_verify_ps_command`] output against the acceptance
+/// gate (the security contract, step 6). Asserts: owner is SYSTEM (or Administrators); NO
+/// inherited ACE (inheritance disabled); NO Everyone/Users/Authenticated-Users/Anonymous
+/// ACE; SYSTEM + Administrators are present; and — strictly — NO principal beyond
+/// {SYSTEM, Administrators, `read_grant`} is present (a surviving squatter user SID or any
+/// unexpected trustee is rejected). When `read_grant` is `Some`, that SID MUST be present.
+/// `Err` on any violation. PURE.
+pub fn parse_acl_verify(output: &str, read_grant: Option<&str>) -> Result<(), String> {
+    let mut owner: Option<String> = None;
+    let mut ace_sids: Vec<String> = Vec::new();
+    for line in output.lines() {
+        let line = line.trim();
+        if let Some(rest) = line.strip_prefix("OWNER;") {
+            owner = Some(rest.trim().to_string());
+        } else if let Some(rest) = line.strip_prefix("ACE;") {
+            let mut parts = rest.split(';');
+            let sid = parts.next().unwrap_or("").trim().to_string();
+            let inherited = parts.next().unwrap_or("").trim();
+            if sid.is_empty() {
+                continue;
+            }
+            if inherited.eq_ignore_ascii_case("true") {
+                return Err(format!(
+                    "inheritance is NOT disabled — inherited ACE present for {sid}"
+                ));
+            }
+            if is_dangerous_group_sid(&sid) {
+                return Err(format!(
+                    "DACL grants a world/group principal ({sid}) — the token dir must not be group-readable"
+                ));
+            }
+            ace_sids.push(sid);
+        }
+    }
+    let owner = owner.ok_or_else(|| "could not read the directory owner".to_string())?;
+    if owner != SID_SYSTEM && owner != SID_ADMINISTRATORS {
+        return Err(format!(
+            "owner is {owner}, expected SYSTEM ({SID_SYSTEM}) or Administrators ({SID_ADMINISTRATORS})"
+        ));
+    }
+    for required in [SID_SYSTEM, SID_ADMINISTRATORS] {
+        if !ace_sids.iter().any(|s| s == required) {
+            return Err(format!("DACL is missing the required ACE for {required}"));
+        }
+    }
+    if let Some(sid) = read_grant {
+        if !ace_sids.iter().any(|s| s == sid) {
+            return Err(format!(
+                "DACL is missing the interactive read grant for {sid}"
+            ));
+        }
+    }
+    // Strict: nothing beyond the granted principals may remain.
+    for sid in &ace_sids {
+        let allowed = sid == SID_SYSTEM
+            || sid == SID_ADMINISTRATORS
+            || read_grant.map(|r| r == sid).unwrap_or(false);
+        if !allowed {
+            return Err(format!(
+                "DACL grants an unexpected principal ({sid}) — only SYSTEM, Administrators, and the interactive read grant are permitted"
+            ));
+        }
+    }
+    Ok(())
+}
+
+/// From an [`acl_verify_ps_command`] readback of a TRUSTED pre-existing dir, discover an
+/// installer-set interactive read grant to PRESERVE: the first ACE SID that is a real
+/// per-user domain SID (`S-1-5-21-…`) — i.e. not a well-known/broad group and not
+/// SYSTEM/Administrators. `None` if there is none. PURE.
+pub fn parse_first_user_read_sid(output: &str) -> Option<String> {
+    for line in output.lines() {
+        let line = line.trim();
+        if let Some(rest) = line.strip_prefix("ACE;") {
+            let sid = rest.split(';').next().unwrap_or("").trim();
+            if sid.starts_with("S-1-5-21-")
+                && sid != SID_SYSTEM
+                && sid != SID_ADMINISTRATORS
+                && !is_dangerous_group_sid(sid)
+            {
+                return Some(sid.to_string());
+            }
+        }
+    }
+    None
+}
+
+/// Harden `dir` per the #501 contract, granting an optional interactive `read_grant`.
+/// FAILS CLOSED: any failure to establish + verify the tight ACL returns `Err`, and the
+/// caller must delete the dir + refuse to serve control from it. Idempotent on a legit dir
+/// (running it twice yields the same final ACL).
+///
+/// - **Windows:** [`windows_harden_dir`] — squatter purge, owner→SYSTEM, `/reset`,
+///   protected `{SYSTEM:F, Administrators:F, read_grant:R}` DACL, readback-verify.
+/// - **Unix:** `create_dir_all` + `0700`; verified. (The interactive read grant on Unix is
+///   the installer's best-effort `setfacl`, not applied here.)
+pub fn harden_state_dir(dir: &Path, read_grant: Option<&str>) -> std::io::Result<()> {
+    #[cfg(windows)]
+    {
+        windows_harden_dir(dir, read_grant)
+    }
+    #[cfg(unix)]
+    {
+        let _ = read_grant;
+        harden_unix_dir(dir)
+    }
+    #[cfg(not(any(windows, unix)))]
+    {
+        let _ = read_grant;
+        std::fs::create_dir_all(dir)
+    }
+}
+
+/// Unix harden: `0700`, owner-only, verified. Fail closed (remove the dir) if `0700` cannot
+/// be established.
+#[cfg(unix)]
+fn harden_unix_dir(dir: &Path) -> std::io::Result<()> {
+    use std::os::unix::fs::PermissionsExt;
+    std::fs::create_dir_all(dir)?;
+    std::fs::set_permissions(dir, std::fs::Permissions::from_mode(0o700))?;
+    let mode = std::fs::metadata(dir)?.permissions().mode() & 0o777;
+    if mode != 0o700 {
+        let _ = std::fs::remove_dir_all(dir);
+        return Err(std::io::Error::new(
+            std::io::ErrorKind::PermissionDenied,
+            format!(
+                "state dir {} is not 0700 after hardening (got {mode:o})",
+                dir.display()
+            ),
+        ));
+    }
+    Ok(())
+}
+
+/// The current process TOKEN's user SID (`whoami /user`), or `None` when it cannot be
+/// resolved OR is a forbidden group/SYSTEM SID — so a SERVICE running as SYSTEM yields
+/// `None` (no interactive grant) and a spoofed `%USERNAME%=Everyone` can never leak in
+/// (the SID comes from the token, and a group SID is rejected).
 #[cfg(windows)]
-fn current_user_account() -> Option<String> {
-    let user = std::env::var("USERNAME").ok()?;
-    let user = user.trim();
-    if user.is_empty() {
+fn current_user_sid() -> Option<String> {
+    let out = std::process::Command::new("whoami")
+        .args(["/user", "/fo", "csv", "/nh"])
+        .stderr(std::process::Stdio::null())
+        .output()
+        .ok()?;
+    if !out.status.success() {
         return None;
     }
-    match std::env::var("USERDOMAIN")
-        .ok()
-        .map(|d| d.trim().to_string())
-    {
-        Some(domain) if !domain.is_empty() => Some(format!("{domain}\\{user}")),
-        _ => Some(user.to_string()),
+    let sid = parse_whoami_csv_sid(&String::from_utf8_lossy(&out.stdout))?;
+    if is_forbidden_grant_sid(&sid) {
+        return None;
     }
+    Some(sid)
 }
 
-/// Apply a restrictive Windows ACL to the state DIR `path` via `icacls` (no shell — args are
-/// passed directly). Removes inherited ACEs (`/inheritance:r`) so the world-readable
-/// `%PROGRAMDATA%` default does NOT apply, then grants inheritable full (`(OI)(CI)(F)`) to
-/// EXACTLY three trustees and NO ONE ELSE: SYSTEM (`*S-1-5-18`), Administrators
-/// (`*S-1-5-32-544`), and the creating user.
-///
-/// The creating user gets FULL (not merely read): the SAME process that creates the dir must be
-/// able to WRITE the token file into it (the dev/self-create path), and when an elevated
-/// `dig-node install` creates the dir the interactive user must retain read afterwards — FULL is
-/// a superset of read and, critically, still denies every OTHER local user, which is the
-/// security property that matters (no local privilege escalation). When the daemon bootstraps the
-/// dir as SYSTEM/root, the interactive user is simply not among the three trustees, so a
-/// non-elevated operator CLI cannot read the token and gets the precise remedy. Inheritable, so
-/// the token file created inside inherits exactly this tight ACL. Best-effort: a failure (icacls
-/// missing/blocked) is ignored — the loopback bind + token possession remain the primary gate,
-/// and Unix `0700`/`0600` is the CI-gated assertion path.
+/// The dir's current owner SID via `Get-Acl`, or `None` if it can't be read.
 #[cfg(windows)]
-fn windows_restrict_dir(path: &Path) {
-    const GRANT: &str = "(OI)(CI)(F)";
-    let mut cmd = std::process::Command::new("icacls");
-    cmd.arg(path)
-        .arg("/inheritance:r")
-        .arg("/grant:r")
-        .arg(format!("*S-1-5-18:{GRANT}"))
-        .arg(format!("*S-1-5-32-544:{GRANT}"));
-    if let Some(user) = current_user_account() {
-        cmd.arg(format!("{user}:{GRANT}"));
-    }
-    let _ = cmd
+fn dir_owner_sid(path: &Path) -> Option<String> {
+    let dir = path.to_string_lossy().replace('\'', "''");
+    let ps = format!(
+        "(Get-Acl -LiteralPath '{dir}').GetOwner([System.Security.Principal.SecurityIdentifier]).Value"
+    );
+    let out = std::process::Command::new("powershell")
+        .args(["-NoProfile", "-NonInteractive", "-Command", &ps])
+        .stderr(std::process::Stdio::null())
+        .output()
+        .ok()?;
+    if !out.status.success() {
+        return None;
+    }
+    let s = String::from_utf8_lossy(&out.stdout).trim().to_string();
+    if s.starts_with("S-1-") {
+        Some(s)
+    } else {
+        None
+    }
+}
+
+/// Discover an installer-set interactive read grant on a TRUSTED (SYSTEM/Administrators-owned)
+/// pre-existing dir, to PRESERVE it across a SYSTEM service harden. `None` for an absent dir,
+/// an untrusted-owner dir (a squatter — its grants are not preserved; the dir is purged), or a
+/// dir with no per-user grant.
+#[cfg(windows)]
+fn discover_existing_read_grant(dir: &Path) -> Option<String> {
+    if !dir.is_dir() {
+        return None;
+    }
+    let trusted = matches!(
+        dir_owner_sid(dir).as_deref(),
+        Some(SID_SYSTEM) | Some(SID_ADMINISTRATORS)
+    );
+    if !trusted {
+        return None;
+    }
+    let ps = acl_verify_ps_command(&dir.to_string_lossy());
+    let out = std::process::Command::new("powershell")
+        .args(["-NoProfile", "-NonInteractive", "-Command", &ps])
+        .stderr(std::process::Stdio::null())
+        .output()
+        .ok()?;
+    if !out.status.success() {
+        return None;
+    }
+    parse_first_user_read_sid(&String::from_utf8_lossy(&out.stdout))
+}
+
+/// Run `icacls` with `args`; `Ok(())` iff it exits 0, else an `Err` carrying the exit code +
+/// stderr. No shell — args are passed directly.
+#[cfg(windows)]
+fn run_icacls(args: &[String]) -> std::io::Result<()> {
+    let out = std::process::Command::new("icacls").args(args).output()?;
+    if out.status.success() {
+        Ok(())
+    } else {
+        Err(std::io::Error::other(format!(
+            "icacls exited with {}: {}",
+            out.status
+                .code()
+                .map(|c| c.to_string())
+                .unwrap_or_else(|| "?".to_string()),
+            String::from_utf8_lossy(&out.stderr).trim()
+        )))
+    }
+}
+
+/// Read `dir`'s ACL back and verify it meets the acceptance gate ([`parse_acl_verify`]).
+#[cfg(windows)]
+fn read_and_verify_acl(dir: &Path, read_grant: Option<&str>) -> std::io::Result<()> {
+    let ps = acl_verify_ps_command(&dir.to_string_lossy());
+    let out = std::process::Command::new("powershell")
+        .args(["-NoProfile", "-NonInteractive", "-Command", &ps])
+        .output()?;
+    if !out.status.success() {
+        return Err(std::io::Error::other(format!(
+            "Get-Acl readback exited non-zero: {}",
+            String::from_utf8_lossy(&out.stderr).trim()
+        )));
+    }
+    parse_acl_verify(&String::from_utf8_lossy(&out.stdout), read_grant)
+        .map_err(std::io::Error::other)
+}
+
+/// Windows: the full #501 hardening contract, fail-closed (see the module docs). Purges a
+/// squatter-owned pre-existing dir, forces owner = SYSTEM, drops all foreign ACEs, applies a
+/// protected `{SYSTEM:F, Administrators:F[, read_grant:R]}` DACL, and READBACK-VERIFIES it.
+/// On any failure the dir is best-effort deleted and an `Err` is returned.
+#[cfg(windows)]
+fn windows_harden_dir(dir: &Path, read_grant: Option<&str>) -> std::io::Result<()> {
+    let path_str = dir.to_string_lossy().into_owned();
+
+    // 1. Squatting defense: a pre-existing dir with an UNTRUSTED owner is purged (take
+    //    ownership so it can be deleted, then remove). Fail closed if it can't be purged
+    //    rather than adopt an attacker-controlled directory.
+    if dir.exists() {
+        let trusted = matches!(
+            dir_owner_sid(dir).as_deref(),
+            Some(SID_SYSTEM) | Some(SID_ADMINISTRATORS)
+        );
+        if !trusted {
+            let _ = run_icacls(&setowner_system_args(&path_str));
+            std::fs::remove_dir_all(dir).map_err(|e| {
+                std::io::Error::new(
+                    std::io::ErrorKind::PermissionDenied,
+                    format!(
+                        "state dir {path_str} pre-existed with an untrusted/unknown owner and could not be purged ({e}); refusing (fail closed)"
+                    ),
+                )
+            })?;
+        }
+    }
+
+    // 2. Create (idempotent if we just adopted a trusted pre-existing dir).
+    std::fs::create_dir_all(dir)?;
+
+    // 3-5. Owner→SYSTEM, purge foreign ACEs (/reset), then the protected DACL.
+    let lockdown = run_icacls(&setowner_system_args(&path_str))
+        .and_then(|_| run_icacls(&reset_dacl_args(&path_str)))
+        .and_then(|_| run_icacls(&windows_lockdown_grant_args(&path_str, read_grant)));
+    if let Err(e) = lockdown {
+        let _ = std::fs::remove_dir_all(dir);
+        return Err(std::io::Error::other(format!(
+            "ACL lockdown FAILED ({e}); removed the state dir (fail closed)"
+        )));
+    }
+
+    // 6. Readback-verify. Fail closed on any violation.
+    if let Err(e) = read_and_verify_acl(dir, read_grant) {
+        let _ = std::fs::remove_dir_all(dir);
+        return Err(std::io::Error::other(format!(
+            "ACL readback verification FAILED ({e}); removed the state dir (fail closed)"
+        )));
+    }
+    Ok(())
+}
+
+/// A BEST-EFFORT inheritable grant for the fresh-create path ([`ensure_dir_restricted`]):
+/// `icacls /inheritance:r /grant:r *SYSTEM:F *Administrators:F [*<user>:F]`. Not the
+/// authoritative gate (no owner reset, no `/reset` purge, no readback) — that is
+/// [`windows_harden_dir`] on the service run. Grants the creating REAL user (process-token
+/// SID) FULL because THIS process must WRITE the token it is about to mint into the dir it
+/// just created (the dev / self-create path); a READ-only grant would deny that write. FULL
+/// is still a superset of read and still denies every OTHER local user (the security
+/// property that matters); the authoritative service harden later re-locks the interactive
+/// user to READ. Silent best-effort.
+#[cfg(windows)]
+fn windows_grant_best_effort(dir: &Path) {
+    let mut args = vec![
+        dir.to_string_lossy().into_owned(),
+        "/inheritance:r".to_string(),
+        "/grant:r".to_string(),
+        format!("*{SID_SYSTEM}:(OI)(CI)F"),
+        "/grant:r".to_string(),
+        format!("*{SID_ADMINISTRATORS}:(OI)(CI)F"),
+    ];
+    if let Some(sid) = current_user_sid() {
+        args.push("/grant:r".to_string());
+        args.push(format!("*{sid}:(OI)(CI)F"));
+    }
+    let _ = std::process::Command::new("icacls")
+        .args(&args)
         .stdout(std::process::Stdio::null())
         .stderr(std::process::Stdio::null())
         .status();
@@ -409,6 +894,19 @@ mod tests {
         }
     }
 
+    #[test]
+    fn is_machine_state_dir_matches_only_the_real_candidates() {
+        for d in machine_state_dirs() {
+            assert!(is_machine_state_dir(&d), "{d:?} is a machine candidate");
+        }
+        // A test temp dir / legacy per-user dir is NOT a machine dir (so it is never
+        // hardened/purged — the DIG_NODE_STATE_DIR override + legacy fallback stay safe).
+        assert!(!is_machine_state_dir(
+            &std::env::temp_dir().join("dig-node-not-machine")
+        ));
+        assert!(!is_machine_state_dir(Path::new("/home/u/.local/DigNode")));
+    }
+
     #[test]
     fn running_as_service_reads_the_run_context_env() {
         // PURE-ish: exercised via the env contract. Save/restore so we don't leak state.
@@ -427,6 +925,192 @@ mod tests {
         }
     }
 
+    // -- SID resolution + spoof guard (#501: spoofable grant principal) ----------
+
+    #[test]
+    fn parse_whoami_csv_sid_reads_the_token_sid() {
+        // `whoami /user /fo csv /nh` → "domain\user","SID".
+        assert_eq!(
+            parse_whoami_csv_sid("\"mypc\\alice\",\"S-1-5-21-111-222-333-1001\"\r\n").as_deref(),
+            Some("S-1-5-21-111-222-333-1001")
+        );
+        assert_eq!(parse_whoami_csv_sid("no sid here").as_deref(), None);
+        assert_eq!(parse_whoami_csv_sid("").as_deref(), None);
+    }
+
+    #[test]
+    fn forbidden_grant_sids_are_rejected() {
+        // The exact spoof: %USERNAME%=Everyone → Everyone SID must be refused, as must the
+        // other broad groups and SYSTEM (never the interactive grantee).
+        assert!(is_forbidden_grant_sid(SID_EVERYONE));
+        assert!(is_forbidden_grant_sid(SID_AUTHENTICATED_USERS));
+        assert!(is_forbidden_grant_sid(SID_ANONYMOUS));
+        assert!(is_forbidden_grant_sid(SID_USERS));
+        assert!(is_forbidden_grant_sid(SID_SYSTEM));
+        // A real interactive-user SID is allowed.
+        assert!(!is_forbidden_grant_sid("S-1-5-21-111-222-333-1001"));
+    }
+
+    #[test]
+    fn dangerous_group_sids_cover_the_broad_principals() {
+        assert!(is_dangerous_group_sid(SID_EVERYONE));
+        assert!(is_dangerous_group_sid(SID_AUTHENTICATED_USERS));
+        assert!(is_dangerous_group_sid(SID_ANONYMOUS));
+        assert!(is_dangerous_group_sid(SID_USERS));
+        assert!(!is_dangerous_group_sid(SID_SYSTEM));
+        assert!(!is_dangerous_group_sid(SID_ADMINISTRATORS));
+        assert!(!is_dangerous_group_sid("S-1-5-21-1-2-3-1001"));
+    }
+
+    // -- icacls lockdown argv (owner reset + foreign-ACE purge + SID grants) -----
+
+    #[test]
+    fn setowner_forces_system_by_sid_recursively() {
+        let args = setowner_system_args(r"C:\ProgramData\DigNode");
+        assert!(args.iter().any(|a| a == "/setowner"));
+        assert!(
+            args.iter().any(|a| a == "*S-1-5-18"),
+            "owner must be SYSTEM by SID"
+        );
+        assert!(args.iter().any(|a| a == "/T"), "recurse to children");
+    }
+
+    #[test]
+    fn reset_purges_explicit_aces() {
+        let args = reset_dacl_args(r"C:\ProgramData\DigNode");
+        assert!(args.iter().any(|a| a == "/reset"));
+        assert!(args.iter().any(|a| a == "/T"));
+    }
+
+    #[test]
+    fn lockdown_grants_system_admins_and_the_read_sid() {
+        let args =
+            windows_lockdown_grant_args(r"C:\ProgramData\DigNode", Some("S-1-5-21-9-9-9-1001"));
+        assert!(args.contains(&"/inheritance:r".to_string()));
+        // SYSTEM + Administrators FULL by SID (not the localized name "SYSTEM").
+        assert!(args.iter().any(|a| a == "*S-1-5-18:(OI)(CI)F"));
+        assert!(args.iter().any(|a| a == "*S-1-5-32-544:(OI)(CI)F"));
+        // The interactive user gets READ only, by SID.
+        assert!(args.iter().any(|a| a == "*S-1-5-21-9-9-9-1001:(OI)(CI)R"));
+        // Never the localized "SYSTEM" name, never Everyone/Users.
+        assert!(!args.iter().any(|a| a.starts_with("SYSTEM:")));
+        assert!(!args
+            .iter()
+            .any(|a| a.contains("Everyone") || a.contains("Users:") || a.contains("S-1-1-0")));
+    }
+
+    #[test]
+    fn lockdown_without_a_read_grant_is_system_and_admins_only() {
+        // A SYSTEM service with no discoverable interactive grant → SYSTEM + Admins only.
+        let args = windows_lockdown_grant_args(r"C:\ProgramData\DigNode", None);
+        assert!(args.iter().any(|a| a == "*S-1-5-18:(OI)(CI)F"));
+        assert!(args.iter().any(|a| a == "*S-1-5-32-544:(OI)(CI)F"));
+        // No user read ACE, and definitely no broad-group grant.
+        assert!(!args.iter().any(|a| a.ends_with(":(OI)(CI)R")));
+        assert!(!args
+            .iter()
+            .any(|a| a.contains("S-1-1-0") || a.contains("S-1-5-32-545")));
+    }
+
+    // -- readback ACL verification (the acceptance gate) -------------------------
+
+    fn ok_acl_with_read(user: &str) -> String {
+        format!("OWNER;S-1-5-18\nACE;S-1-5-18;False\nACE;S-1-5-32-544;False\nACE;{user};False\n")
+    }
+    fn ok_acl_no_read() -> String {
+        "OWNER;S-1-5-18\nACE;S-1-5-18;False\nACE;S-1-5-32-544;False\n".to_string()
+    }
+
+    #[test]
+    fn verify_accepts_a_correctly_locked_dacl_with_read_grant() {
+        let user = "S-1-5-21-1-2-3-1001";
+        assert!(parse_acl_verify(&ok_acl_with_read(user), Some(user)).is_ok());
+    }
+
+    #[test]
+    fn verify_accepts_system_and_admins_only_when_no_read_grant_required() {
+        // A SYSTEM service dir with no interactive grant is valid (operator elevates).
+        assert!(parse_acl_verify(&ok_acl_no_read(), None).is_ok());
+    }
+
+    #[test]
+    fn verify_rejects_a_world_readable_ace() {
+        // The priv-esc: Everyone/Users in the DACL.
+        let bad =
+            "OWNER;S-1-5-18\nACE;S-1-5-18;False\nACE;S-1-5-32-544;False\nACE;S-1-5-32-545;False\n";
+        let e = parse_acl_verify(bad, None).unwrap_err();
+        assert!(e.contains("world/group"), "got: {e}");
+    }
+
+    #[test]
+    fn verify_rejects_an_inherited_ace() {
+        // Inheritance not disabled → the dir can inherit ProgramData's Users ACE.
+        let bad = "OWNER;S-1-5-18\nACE;S-1-5-18;True\nACE;S-1-5-32-544;False\nACE;S-1-5-21-1-2-3-1001;False\n";
+        let e = parse_acl_verify(bad, Some("S-1-5-21-1-2-3-1001")).unwrap_err();
+        assert!(e.contains("inheritance is NOT disabled"), "got: {e}");
+    }
+
+    #[test]
+    fn verify_rejects_an_untrusted_owner() {
+        // A squatter-owned dir (owner = a normal user) must fail: owner keeps WRITE_DAC.
+        let bad = "OWNER;S-1-5-21-1-2-3-1001\nACE;S-1-5-18;False\nACE;S-1-5-32-544;False\nACE;S-1-5-21-1-2-3-1001;False\n";
+        let e = parse_acl_verify(bad, Some("S-1-5-21-1-2-3-1001")).unwrap_err();
+        assert!(e.contains("owner is"), "got: {e}");
+    }
+
+    #[test]
+    fn verify_rejects_a_missing_system_ace() {
+        let bad = "OWNER;S-1-5-18\nACE;S-1-5-32-544;False\n";
+        let e = parse_acl_verify(bad, None).unwrap_err();
+        assert!(e.contains("missing the required ACE"), "got: {e}");
+    }
+
+    #[test]
+    fn verify_rejects_a_missing_required_read_grant() {
+        // A read grant was applied but the readback lacks it → operator can't read the token.
+        let e = parse_acl_verify(&ok_acl_no_read(), Some("S-1-5-21-1-2-3-1001")).unwrap_err();
+        assert!(e.contains("missing the interactive read grant"), "got: {e}");
+    }
+
+    #[test]
+    fn verify_rejects_an_unexpected_surviving_principal() {
+        // A squatter user SID that survived the reset (or an unexpected extra trustee) must
+        // be rejected even though it is not a well-known group. No read grant was applied, so
+        // ANY per-user SID present is unexpected.
+        let bad = "OWNER;S-1-5-18\nACE;S-1-5-18;False\nACE;S-1-5-32-544;False\nACE;S-1-5-21-7-7-7-1002;False\n";
+        let e = parse_acl_verify(bad, None).unwrap_err();
+        assert!(e.contains("unexpected principal"), "got: {e}");
+    }
+
+    #[test]
+    fn acl_verify_ps_command_targets_the_dir_and_emits_sids() {
+        let cmd = acl_verify_ps_command(r"C:\ProgramData\DigNode");
+        assert!(cmd.contains("Get-Acl"));
+        assert!(cmd.contains(r"C:\ProgramData\DigNode"));
+        assert!(cmd.contains("SecurityIdentifier"));
+        assert!(cmd.contains("OWNER;"));
+        assert!(cmd.contains("ACE;"));
+    }
+
+    // -- discover an installer-set interactive read grant to preserve ------------
+
+    #[test]
+    fn discover_finds_the_first_user_read_sid() {
+        let acl = ok_acl_with_read("S-1-5-21-1-2-3-1001");
+        assert_eq!(
+            parse_first_user_read_sid(&acl).as_deref(),
+            Some("S-1-5-21-1-2-3-1001")
+        );
+    }
+
+    #[test]
+    fn discover_ignores_system_admins_and_groups() {
+        // Only SYSTEM + Admins (+ a group, which should never be here) → nothing to preserve.
+        let acl =
+            "OWNER;S-1-5-18\nACE;S-1-5-18;False\nACE;S-1-5-32-544;False\nACE;S-1-5-32-545;False\n";
+        assert_eq!(parse_first_user_read_sid(acl), None);
+    }
+
     #[cfg(unix)]
     #[test]
     fn ensure_dir_restricted_is_0700_and_not_group_or_world_accessible() {
@@ -439,4 +1123,17 @@ mod tests {
         assert_eq!(mode, 0o700, "state dir must be owner-only (got {mode:o})");
         let _ = std::fs::remove_dir_all(&dir);
     }
+
+    #[cfg(unix)]
+    #[test]
+    fn harden_state_dir_sets_0700_on_unix() {
+        use std::os::unix::fs::PermissionsExt;
+        let dir =
+            std::env::temp_dir().join(format!("dig-harden-dir-{}-{}", std::process::id(), line!()));
+        let _ = std::fs::remove_dir_all(&dir);
+        harden_state_dir(&dir, None).unwrap();
+        let mode = std::fs::metadata(&dir).unwrap().permissions().mode() & 0o777;
+        assert_eq!(mode, 0o700, "harden must leave the dir 0700 (got {mode:o})");
+        let _ = std::fs::remove_dir_all(&dir);
+    }
 }

From a8a0e7a652085cf1e216f92d173c328948e9d952 Mon Sep 17 00:00:00 2001
From: Michael Taylor <michael@michaeltaylor.dev>
Date: Sun, 12 Jul 2026 22:27:09 -0700
Subject: [PATCH 6/6] fix(state): verify control-token file owner before
 trusting it (#501 residual)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Close the LOW-but-real control-token custody residual an adversarial verify
found: `load_or_create_token_at` trusted a non-empty pre-existing token file
WITHOUT checking who owns it. An unprivileged local user who plants a KNOWN
token in the machine-wide state dir (a %PROGRAMDATA% squat, or the narrow
window during a service harden) would have the LocalSystem daemon read + trust
it, learning the control token → full local `control.*` node control (local
privilege escalation).

Fix: before trusting an existing token, verify its file OWNER; a foreign-owned
token is deleted + regenerated, never returned. Trust rule (pure, unit-tested):
- Windows: owner SID SYSTEM (S-1-5-18) / Administrators (S-1-5-32-544) always;
  a NON-service run also accepts the current process user's SID (dev tokens in
  the legacy per-user dir); a SERVICE run requires SYSTEM/Administrators.
- Unix: owner uid 0 (root) always, else owner == current euid AND mode 0600.

Owner read via the existing Get-Acl helper (`dir_owner_sid` renamed to
`path_owner_sid`, now used for files too) on Windows and `stat` on Unix; euid
via a dependency-free probe file. Layered beneath the §7.3a state-dir hardening
(which already purges a squatter-owned dir on a service run — item #2 landed in
ee33f1b) as defense-in-depth: it also guards the non-hardened dev path and any
harden gap. Coherent with the installer daemon_dir.rs trust model (dir owner
SYSTEM/root + interactive-user read).

TDD: pure trust-decision helpers + FS-decision + regeneration tests (red→green,
Windows path verified locally on win32; unix-gated tests run in CI). SPEC.md
§7.3 documents the owner-verification requirement.

Co-Authored-By: Claude <noreply@anthropic.com>
---
 SPEC.md                                |  13 ++
 crates/dig-node-service/src/control.rs |  88 +++++++++-
 crates/dig-node-service/src/state.rs   | 217 ++++++++++++++++++++++++-
 3 files changed, 311 insertions(+), 7 deletions(-)

diff --git a/SPEC.md b/SPEC.md
index b6f6147..d9a6bb4 100644
--- a/SPEC.md
+++ b/SPEC.md
@@ -776,6 +776,19 @@ token is NOT accepted for them.
 - **The daemon MAY create the token (write); an operator CLI MUST NOT mint one.** The CLI
   (`dig-node pair` / any control tool) reads the token READ-ONLY; if it is missing or unreadable it
   MUST fail with a precise remedy (§7.3a) rather than write a fresh token the daemon does not trust.
+- **Trust a pre-existing token file ONLY when it is owned by a TRUSTED principal (owner
+  verification).** Before the daemon loads and trusts the bytes of an EXISTING `control-token`, it
+  MUST verify the file's OWNER; a foreign-owned token is DELETED and REGENERATED, never returned.
+  This closes the residual where an unprivileged local user plants a KNOWN token in the machine-wide
+  state dir (a `%PROGRAMDATA%` squat, or the narrow window during a service harden) so the daemon
+  (LocalSystem) reads + trusts it and the attacker learns the control token → full local control
+  (local privilege escalation). Trusted owners: **Windows** — `S-1-5-18` (SYSTEM) or `S-1-5-32-544`
+  (Administrators) always; a NON-service (dev/operator) run ALSO trusts the CURRENT process user's
+  own SID (so a dev token in the legacy per-user dir keeps working), and a SERVICE run requires
+  SYSTEM/Administrators. **Unix** — owner uid `0` (root) always, else the CURRENT effective uid AND
+  mode `0600` (owner-only); a group/other-readable or foreign-uid token is untrusted. This is layered
+  BENEATH the §7.3a state-dir hardening (which already purges a squatter-owned dir on a service run)
+  as defense-in-depth: it also guards the non-hardened dev path and any harden gap.
 - If the token cannot be persisted (unwritable state dir), the daemon MUST fall back to an
   in-memory token that no controller can read — the control plane fails **closed**; the read plane
   is unaffected.
diff --git a/crates/dig-node-service/src/control.rs b/crates/dig-node-service/src/control.rs
index e46e7af..344878b 100644
--- a/crates/dig-node-service/src/control.rs
+++ b/crates/dig-node-service/src/control.rs
@@ -178,13 +178,24 @@ pub fn load_token_readonly() -> std::io::Result<String> {
 }
 
 /// [`load_or_create_token`] for an explicit path (so tests use a temp dir and never
-/// touch the real config). Reads an existing non-blank token; otherwise generates,
-/// persists (owner-only on Unix), and returns a fresh one.
+/// touch the real config). Reads an existing non-blank token ONLY when its file is owned by a
+/// trusted principal ([`crate::state::token_file_is_trusted`], #501 residual); otherwise (or
+/// when absent) generates, persists (owner-only on Unix), and returns a fresh one.
 pub fn load_or_create_token_at(path: &Path) -> std::io::Result<String> {
     if let Ok(existing) = std::fs::read_to_string(path) {
         let t = existing.trim().to_string();
         if !t.is_empty() {
-            return Ok(t);
+            // #501 residual: TRUST a pre-existing token ONLY when its file is owned by a
+            // trusted principal. An attacker who can plant a KNOWN token in the machine-wide
+            // state dir — a `%PROGRAMDATA%` squat, or the narrow window during a service
+            // harden — would otherwise have the daemon (LocalSystem) read + trust it, learning
+            // the control token → full local node control (a local privilege escalation). A
+            // foreign-owned token is deleted + regenerated, so the daemon only ever trusts a
+            // token it (or a trusted principal: SYSTEM/Administrators/root) owns.
+            if crate::state::token_file_is_trusted(path, crate::state::running_as_service()) {
+                return Ok(t);
+            }
+            let _ = std::fs::remove_file(path);
         }
     }
     let token = generate_token();
@@ -1058,6 +1069,77 @@ mod tests {
         let _ = std::fs::remove_dir_all(&dir);
     }
 
+    /// SECURITY (#501 residual): a pre-existing control-token file that is NOT owned by a
+    /// trusted principal (here forced group/other-readable, so not owner-only) MUST be DELETED
+    /// and REGENERATED — never returned — so a planted/squatted token can never become the
+    /// trusted one (which would hand an attacker full local node control). Unix-gated: it
+    /// relies on mode bits (CI runs on Linux). Skipped when running as root, where a
+    /// root-owned file is legitimately trusted regardless of mode.
+    #[cfg(unix)]
+    #[test]
+    fn foreign_owned_token_file_is_regenerated_not_trusted() {
+        use std::os::unix::fs::MetadataExt;
+        use std::os::unix::fs::PermissionsExt;
+        let dir = std::env::temp_dir().join(format!(
+            "dig-node-token-untrusted-{}-{}",
+            std::process::id(),
+            line!()
+        ));
+        let path = dir.join(CONTROL_TOKEN_FILE);
+        let _ = std::fs::remove_dir_all(&dir);
+        std::fs::create_dir_all(&dir).unwrap();
+        let planted = "planted0".repeat(8); // a KNOWN 64-char attacker value (non-empty)
+        std::fs::write(&path, &planted).unwrap();
+        std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o644)).unwrap();
+        let running_as_root = std::fs::metadata(&path)
+            .map(|m| m.uid() == 0)
+            .unwrap_or(false);
+        let got = load_or_create_token_at(&path).unwrap();
+        if !running_as_root {
+            assert_ne!(
+                got, planted,
+                "an untrusted (group-readable) token must be regenerated, not returned"
+            );
+            assert_eq!(
+                got.len(),
+                64,
+                "the regenerated token is a fresh 64-hex value"
+            );
+            let mode = std::fs::metadata(&path).unwrap().permissions().mode() & 0o777;
+            assert_eq!(
+                mode & 0o077,
+                0,
+                "the regenerated token must be owner-only 0600 (got {mode:o})"
+            );
+        }
+        let _ = std::fs::remove_dir_all(&dir);
+    }
+
+    /// A trusted (owner-only `0600`, current-user-owned) pre-existing token is loaded AS-IS —
+    /// never regenerated — so a legit token stays stable across runs (#501 residual).
+    #[cfg(unix)]
+    #[test]
+    fn trusted_owner_only_token_file_is_kept() {
+        use std::os::unix::fs::PermissionsExt;
+        let dir = std::env::temp_dir().join(format!(
+            "dig-node-token-trusted-{}-{}",
+            std::process::id(),
+            line!()
+        ));
+        let path = dir.join(CONTROL_TOKEN_FILE);
+        let _ = std::fs::remove_dir_all(&dir);
+        std::fs::create_dir_all(&dir).unwrap();
+        let existing = "a".repeat(64);
+        std::fs::write(&path, &existing).unwrap();
+        std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o600)).unwrap();
+        let got = load_or_create_token_at(&path).unwrap();
+        assert_eq!(
+            got, existing,
+            "a trusted owner-only token must be loaded as-is, not regenerated"
+        );
+        let _ = std::fs::remove_dir_all(&dir);
+    }
+
     /// SECURITY (#501): the control token grants full local control, so the created
     /// file MUST NOT be readable by other local users. On Unix that is a hard `0600`
     /// assertion (no group/other bits) — the CI-gated path (CI runs on Linux). On
diff --git a/crates/dig-node-service/src/state.rs b/crates/dig-node-service/src/state.rs
index 711944c..5f48d9b 100644
--- a/crates/dig-node-service/src/state.rs
+++ b/crates/dig-node-service/src/state.rs
@@ -558,6 +558,109 @@ pub fn parse_first_user_read_sid(output: &str) -> Option<String> {
     None
 }
 
+// ---------------------------------------------------------------------------
+// Control-token FILE owner verification (#501 residual). A pre-existing token file must be
+// OWNED by a trusted principal before the daemon trusts its BYTES: otherwise a local user who
+// planted a known token in the (machine-wide) state dir — a `%PROGRAMDATA%` squat, or the
+// narrow window during a service harden — could learn the control token and gain full local
+// node control (a local privilege escalation). The trust DECISION is a pure, unit-tested
+// helper (per platform); the owner READ is the thin I/O in [`token_file_is_trusted`].
+// ---------------------------------------------------------------------------
+
+/// PURE: may a control-token FILE whose Windows OWNER is `owner_sid` be trusted (loaded
+/// as-is)? SYSTEM (`S-1-5-18`) and Administrators (`S-1-5-32-544`) are ALWAYS trusted (the
+/// daemon identity / an elevated installer). A SERVICE run requires one of those — it MUST
+/// NEVER trust a token owned by a normal user (that is the priv-esc). A NON-service (dev /
+/// operator) run ALSO trusts the CURRENT process user's own SID, so a dev token in the legacy
+/// per-user dir keeps working; when the current user SID is indeterminate it stays LENIENT
+/// (preserving the pre-#501 dev behaviour) rather than needlessly regenerate. Any OTHER owner
+/// (a squatter's SID) is NOT trusted → the file is deleted + regenerated.
+#[cfg(windows)]
+pub fn windows_token_owner_is_trusted(
+    owner_sid: &str,
+    is_service: bool,
+    current_user_sid: Option<&str>,
+) -> bool {
+    if owner_sid == SID_SYSTEM || owner_sid == SID_ADMINISTRATORS {
+        return true;
+    }
+    if is_service {
+        // A service (LocalSystem) must only trust a SYSTEM/Administrators-owned token.
+        return false;
+    }
+    // Non-service (dev / operator): trust the current user's OWN token; stay lenient when the
+    // current user SID is indeterminate (no needless regeneration on a legacy per-user dir).
+    match current_user_sid {
+        Some(cur) => !cur.is_empty() && owner_sid == cur,
+        None => true,
+    }
+}
+
+/// PURE: may a control-token FILE owned by `owner_uid` with unix `mode` be trusted? `root`
+/// (uid 0) is ALWAYS trusted (a root/elevated installer wrote it). Otherwise it is trusted
+/// only when owned by the CURRENT effective uid AND `0600` (owner-only) — a token owned by
+/// another user, or one any group/other can read, is NOT trusted → deleted + regenerated.
+#[cfg(unix)]
+pub fn unix_token_owner_is_trusted(owner_uid: u32, mode: u32, current_euid: u32) -> bool {
+    if owner_uid == 0 {
+        return true;
+    }
+    owner_uid == current_euid && (mode & 0o777) == 0o600
+}
+
+/// Verify a PRE-EXISTING control-token FILE at `path` is owned by a TRUSTED principal before
+/// the daemon trusts its contents (#501 residual). `is_service` is the caller's run context
+/// ([`running_as_service`]). Returns `true` when the file may be loaded as-is; `false` when it
+/// is foreign-owned (a planted/squatted token) and MUST be deleted + regenerated. Reads the
+/// real owner (Windows `Get-Acl` via [`path_owner_sid`]; unix `stat`) and defers the decision
+/// to the pure [`windows_token_owner_is_trusted`] / [`unix_token_owner_is_trusted`].
+pub fn token_file_is_trusted(path: &Path, is_service: bool) -> bool {
+    #[cfg(windows)]
+    {
+        let owner = match path_owner_sid(path) {
+            Some(o) => o,
+            // Owner indeterminate: fail CLOSED on a service run (security wins over
+            // convenience — regenerate); stay LENIENT on a dev run (pre-#501 behaviour).
+            None => return !is_service,
+        };
+        windows_token_owner_is_trusted(&owner, is_service, current_user_sid().as_deref())
+    }
+    #[cfg(unix)]
+    {
+        // The unix trust rule is is_service-independent (see the helper): a service runs as
+        // root ⇒ its own tokens are uid-0-owned (trusted), and any foreign-uid token is not.
+        let _ = is_service;
+        use std::os::unix::fs::MetadataExt;
+        let Ok(meta) = std::fs::metadata(path) else {
+            return false;
+        };
+        match current_euid_near(path) {
+            Some(euid) => unix_token_owner_is_trusted(meta.uid(), meta.mode(), euid),
+            // Can't determine our euid → trust only a root-owned file.
+            None => meta.uid() == 0,
+        }
+    }
+    #[cfg(not(any(windows, unix)))]
+    {
+        let _ = (path, is_service);
+        true
+    }
+}
+
+/// The current process's effective uid, via a probe file created in `path`'s parent dir (a
+/// freshly-created file is owned by the creating euid). Dependency-free (no `libc`); `None`
+/// when the probe cannot be created/statted. Used to compare a token file's owner to "us".
+#[cfg(unix)]
+fn current_euid_near(path: &Path) -> Option<u32> {
+    use std::os::unix::fs::MetadataExt;
+    let dir = path.parent()?;
+    let probe = dir.join(format!(".dig-euid-probe-{}", std::process::id()));
+    std::fs::write(&probe, b"").ok()?;
+    let uid = std::fs::metadata(&probe).ok().map(|m| m.uid());
+    let _ = std::fs::remove_file(&probe);
+    uid
+}
+
 /// Harden `dir` per the #501 contract, granting an optional interactive `read_grant`.
 /// FAILS CLOSED: any failure to establish + verify the tight ACL returns `Err`, and the
 /// caller must delete the dir + refuse to serve control from it. Idempotent on a legit dir
@@ -626,9 +729,11 @@ fn current_user_sid() -> Option<String> {
     Some(sid)
 }
 
-/// The dir's current owner SID via `Get-Acl`, or `None` if it can't be read.
+/// The current owner SID of `path` (a dir OR a file) via `Get-Acl`, or `None` if it can't be
+/// read. Used both for the dir-trust checks (harden / discover) and the control-token FILE
+/// owner verification ([`token_file_is_trusted`]).
 #[cfg(windows)]
-fn dir_owner_sid(path: &Path) -> Option<String> {
+fn path_owner_sid(path: &Path) -> Option<String> {
     let dir = path.to_string_lossy().replace('\'', "''");
     let ps = format!(
         "(Get-Acl -LiteralPath '{dir}').GetOwner([System.Security.Principal.SecurityIdentifier]).Value"
@@ -659,7 +764,7 @@ fn discover_existing_read_grant(dir: &Path) -> Option<String> {
         return None;
     }
     let trusted = matches!(
-        dir_owner_sid(dir).as_deref(),
+        path_owner_sid(dir).as_deref(),
         Some(SID_SYSTEM) | Some(SID_ADMINISTRATORS)
     );
     if !trusted {
@@ -726,7 +831,7 @@ fn windows_harden_dir(dir: &Path, read_grant: Option<&str>) -> std::io::Result<(
     //    rather than adopt an attacker-controlled directory.
     if dir.exists() {
         let trusted = matches!(
-            dir_owner_sid(dir).as_deref(),
+            path_owner_sid(dir).as_deref(),
             Some(SID_SYSTEM) | Some(SID_ADMINISTRATORS)
         );
         if !trusted {
@@ -1124,6 +1229,110 @@ mod tests {
         let _ = std::fs::remove_dir_all(&dir);
     }
 
+    // -- control-token FILE owner verification (#501 residual) ------------------
+
+    #[cfg(windows)]
+    #[test]
+    fn windows_token_owner_trust_rules() {
+        // SYSTEM + Administrators are trusted on BOTH a service and a non-service run.
+        assert!(windows_token_owner_is_trusted(SID_SYSTEM, true, None));
+        assert!(windows_token_owner_is_trusted(SID_SYSTEM, false, None));
+        assert!(windows_token_owner_is_trusted(
+            SID_ADMINISTRATORS,
+            true,
+            None
+        ));
+        let user = "S-1-5-21-1-2-3-1001";
+        // A SERVICE run must NOT trust a token owned by a normal user (the priv-esc)…
+        assert!(!windows_token_owner_is_trusted(user, true, Some(user)));
+        // …but a NON-service run trusts the CURRENT user's own token.
+        assert!(windows_token_owner_is_trusted(user, false, Some(user)));
+        // A DIFFERENT user's token (a squatter) is never trusted on a non-service run.
+        assert!(!windows_token_owner_is_trusted(
+            user,
+            false,
+            Some("S-1-5-21-9-9-9-2002")
+        ));
+        // Indeterminate current user on a non-service run → lenient (no needless churn).
+        assert!(windows_token_owner_is_trusted(user, false, None));
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn unix_token_owner_trust_rules() {
+        let me = 1000u32;
+        // root-owned is trusted regardless of mode (a root/elevated installer wrote it).
+        assert!(unix_token_owner_is_trusted(0, 0o644, me));
+        assert!(unix_token_owner_is_trusted(0, 0o600, me));
+        // My own owner-only (0600) token is trusted.
+        assert!(unix_token_owner_is_trusted(me, 0o600, me));
+        // My own but group/other-readable token is NOT trusted.
+        assert!(!unix_token_owner_is_trusted(me, 0o644, me));
+        assert!(!unix_token_owner_is_trusted(me, 0o660, me));
+        // Another user's token (a squatter) is NOT trusted even at 0600.
+        assert!(!unix_token_owner_is_trusted(1001, 0o600, me));
+    }
+
+    #[cfg(windows)]
+    #[test]
+    fn token_file_is_trusted_rejects_a_service_run_on_a_user_owned_file() {
+        // A file THIS (interactive-user) process creates is owned by the current user. A
+        // NON-service run trusts it; a SERVICE run does NOT (it requires SYSTEM/Administrators).
+        let dir = std::env::temp_dir().join(format!(
+            "dig-token-owner-{}-{}",
+            std::process::id(),
+            line!()
+        ));
+        let _ = std::fs::remove_dir_all(&dir);
+        std::fs::create_dir_all(&dir).unwrap();
+        let path = dir.join("control-token");
+        std::fs::write(&path, b"deadbeef").unwrap();
+        assert!(
+            token_file_is_trusted(&path, false),
+            "a non-service run trusts the current user's own token"
+        );
+        assert!(
+            !token_file_is_trusted(&path, true),
+            "a service run must NOT trust a user-owned token"
+        );
+        let _ = std::fs::remove_dir_all(&dir);
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn token_file_is_trusted_accepts_0600_rejects_group_readable() {
+        use std::os::unix::fs::MetadataExt;
+        use std::os::unix::fs::PermissionsExt;
+        let dir = std::env::temp_dir().join(format!(
+            "dig-token-owner-{}-{}",
+            std::process::id(),
+            line!()
+        ));
+        let _ = std::fs::remove_dir_all(&dir);
+        std::fs::create_dir_all(&dir).unwrap();
+        let path = dir.join("control-token");
+        std::fs::write(&path, b"deadbeef").unwrap();
+        // A 0600 file owned by the test user (== current euid) is trusted.
+        std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o600)).unwrap();
+        assert!(
+            token_file_is_trusted(&path, false),
+            "own 0600 token is trusted"
+        );
+        // A group/other-readable (0644) file is NOT trusted — UNLESS we are root (uid 0), where
+        // a root-owned file is legitimately trusted regardless of mode.
+        std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o644)).unwrap();
+        let running_as_root = std::fs::metadata(&path)
+            .map(|m| m.uid() == 0)
+            .unwrap_or(false);
+        if !running_as_root {
+            assert!(
+                !token_file_is_trusted(&path, false),
+                "a group/other-readable token is not trusted"
+            );
+        }
+        let _ = std::fs::remove_dir_all(&dir);
+    }
+
     #[cfg(unix)]
     #[test]
     fn harden_state_dir_sets_0700_on_unix() {