From c5ed17ae864fdf3a35dc72f75b3f53c131b52c3b Mon Sep 17 00:00:00 2001 From: Michael Taylor Date: Mon, 3 Aug 2026 22:28:27 -0700 Subject: [PATCH 1/3] docs(cli): the node ladder prefers your own node; document --local and the no-node error digs defaults to the local node rather than rpc.dig.net, so the published ladder needed to say so, and two new behaviours needed documenting: - `digs config node.url --local ` sets a per-project node in .dig/node.toml, and that file is NOT trusted on sight because it can arrive with a cloned repository. - With no local node, reads fall through to the gateway with a notice while push/revoke stop with NO_LOCAL_NODE, so the docs now give the check command and the install links. Also corrects the ladder's addresses to the ones dig-node actually binds (portless dig.local; plaintext localhost:9778). Refs DIG-Network/dig_ecosystem#2099 Co-Authored-By: Claude --- docs/digstore/cli/command-reference.md | 41 ++++++++++++++++++++++---- docs/rpc/dig-remote.md | 8 +++-- docs/run-a-node/point-a-consumer.md | 2 +- package.json | 2 +- 4 files changed, 43 insertions(+), 10 deletions(-) diff --git a/docs/digstore/cli/command-reference.md b/docs/digstore/cli/command-reference.md index 461a33d..a93075f 100644 --- a/docs/digstore/cli/command-reference.md +++ b/docs/digstore/cli/command-reference.md @@ -67,21 +67,52 @@ Set the wallet passphrase non-interactively with `DIGSTORE_PASSPHRASE`. Global c | Command | What it does | |---|---| -| `digs config node.url ` | Persist a custom node endpoint to `~/.dig/config.toml` — every subsequent command talks to this node first, ahead of the automatic `dig.local` → `localhost` → `rpc.dig.net` resolution below. | -| `digs config node.url --unset` | Remove the stored override; resolution falls back to the automatic ladder. | +| `digs config node.url ` | Persist a custom node endpoint for this machine (`~/.dig/config.toml`) — every subsequent command talks to this node first, ahead of the automatic `dig.local` → `localhost` → `rpc.dig.net` resolution below. | +| `digs config node.url --local ` | Persist a node endpoint for **this project only** (`.dig/node.toml`), so one project can use the public gateway while another uses your own node. Beats the machine-wide value. | +| `digs config node.url [--local] --show` | Print the current value for that scope. | +| `digs config node.url [--local] --unset` | Remove the stored override; resolution falls back to the automatic ladder. | | `digs config []` | Get or set any config key in `~/.dig/config.toml` (`coinset_url`, `unlock_ttl`, `fee`, `node.url`). Omit `` to print the current value. | ### Which node dig-store talks to {#which-node-digstore-talks-to} Every command that reaches a node (`clone`, `pull`, `push`, reads, `serve` peers, etc.) resolves the endpoint in this fixed order, using the first that responds: -1. **An explicit override** — the `--node ` global flag, then the `$DIG_NODE_URL` environment variable, then the `node.url` value in `~/.dig/config.toml` (set via `digs config node.url `). Any of these always wins over the steps below. -2. **`dig.local`** — your installed local dig-node. -3. **`localhost`** — a dig-node on the loopback address, its default local port. +1. **An explicit override** — the `--node ` global flag, then the `$DIG_NODE_URL` environment variable, then this project's `node.url` (`.dig/node.toml`, set via `digs config node.url --local `), then the machine-wide `node.url` in `~/.dig/config.toml`. Any of these always wins over the steps below. +2. **`dig.local`** — your installed local dig-node, on `https://dig.local` then `http://dig.local`. +3. **`localhost`** — a dig-node on the loopback address, `http://localhost:9778` (or `$DIG_NODE_PORT`). 4. **`rpc.dig.net`** — the public gateway, the final fallback when no local node answers. +Your own node comes first: `rpc.dig.net` is an ordinary node that happens to be well known, not a privileged one, and it is only used when nothing local answers. + Each tier is a cheap health probe with a short timeout, so dig-store never hangs waiting on an unreachable local node. Connections to any tier use mTLS with a client certificate derived from your identity key; `rpc.dig.net` additionally serves plain HTTPS for browsers, which can't present a client certificate. See [Point a consumer at your node](../../run-a-node/point-a-consumer.md) for the same ladder as it applies to the DIG Browser and extension. +#### Setting a node per project {#per-project-node} + +`--local` writes `.dig/node.toml` in the current project, so the setting travels with the project rather than the machine: + +```bash +# this project reads through the public gateway… +digs config node.url --local https://rpc.dig.net + +# …while every other project keeps using your own node +cd ../other-project && digs config node.url --local --unset +``` + +Because `.dig/node.toml` can be committed and therefore arrives with a repository you clone, **digs does not use a `node.url` it did not see you set.** The first time an unfamiliar project asks for a node, digs shows you the URL and asks; if it cannot ask — a script, CI, or `--json` — it ignores the value and uses the normal ladder. Approving one project does not approve another, and if a project later changes its `node.url`, digs asks again. This matters because digs signs every request it sends to a node with your identity key. + +#### When no local node is running {#no-local-node} + +**Reading still works.** `pull`, `clone`, and `cat` fall back to `rpc.dig.net` and tell you that the read left your machine. + +**Publishing does not.** `push` and `revoke` sign every request with your identity key, so rather than send your content and your signatures to a server you never chose, they stop with `NO_LOCAL_NODE` (exit 19) and tell you how to check your node and where to install one: + +```bash +dig-node status # exit 0 = serving, 1 = not serving +dig-node start # if it is installed but stopped +``` + +No node yet? See [Run a node](../../run-a-node/index.md) — or, if you deliberately want a remote one for this project, `digs config node.url --local https://rpc.dig.net`. + ## Stores & workspace A single workspace (`.dig/`) can hold many stores. The commands below create and switch between the stores in your workspace. diff --git a/docs/rpc/dig-remote.md b/docs/rpc/dig-remote.md index 58afe97..a9fe071 100644 --- a/docs/rpc/dig-remote.md +++ b/docs/rpc/dig-remote.md @@ -51,11 +51,13 @@ The owner segment never changes which bytes you fetch — content is addressed b When a `dig://` URL doesn't name a host, the CLI resolves one by trying, in order, the **first that responds**: -1. **An explicitly-configured node** — the `--node ` flag, the `$DIG_NODE_URL` environment variable, or a stored `digs config node.url ` value. Sourced in that order, and this always wins over the automatic steps below. -2. **`dig.local`** — your installed local dig-node. -3. **`localhost`** — a dig-node on the loopback address, its default local port. +1. **An explicitly-configured node** — the `--node ` flag, the `$DIG_NODE_URL` environment variable, this project's `digs config node.url --local ` value, or the machine-wide `digs config node.url ` value. Sourced in that order, and this always wins over the automatic steps below. +2. **`dig.local`** — your installed local dig-node (`https://dig.local`, then `http://dig.local`). +3. **`localhost`** — a dig-node on the loopback address, `http://localhost:9778` (or `$DIG_NODE_PORT`). 4. **`rpc.dig.net`** — the public gateway, used only when no local node answers. +An unconfigured `origin` follows this same order, so it means *your* node by default. Publishing (`push`, `revoke`) requires one of tiers 1–3: rather than send your content and your request signatures to a public server you never chose, it stops and tells you how to start or install a node. + Each tier is a cheap health probe with a short timeout, so an unreachable local node falls through quickly rather than hanging a `clone`/`pull`/`push`. See [Which node dig-store talks to](../digstore/cli/command-reference.md#which-node-digstore-talks-to) for how to set an override, and [Point a consumer at your node](../run-a-node/point-a-consumer.md) for the same ladder as it applies to the DIG Browser and extension. Connections to any of the three tiers use mTLS, presenting a client certificate derived from your identity key — the same per-request signing described below rides on top of that authenticated channel. diff --git a/docs/run-a-node/point-a-consumer.md b/docs/run-a-node/point-a-consumer.md index 5bdb4dd..9d8f4df 100644 --- a/docs/run-a-node/point-a-consumer.md +++ b/docs/run-a-node/point-a-consumer.md @@ -39,7 +39,7 @@ Either way **every byte is verified client-side against the chain**; pointing at - **DIG Browser** — the **My Node** UI lets you select the local dig-node and view its status. - **Extension** — set the `dig-node` host (the `server.host` setting) to your node; leave it blank to use the automatic `dig.local` → `localhost` → `rpc.dig.net` resolution. To also read wallet balances/tokens/NFTs from your node, see [Wallet data (extension)](#wallet-data-extension) below. -- **dig-store CLI** — set an explicit override with the `--node ` global flag, the `$DIG_NODE_URL` environment variable, or a persisted `digs config node.url `; leave all three unset to use the automatic resolution. See [Which node dig-store talks to](../digstore/cli/command-reference.md#which-node-digstore-talks-to). +- **dig-store CLI** — set an explicit override with the `--node ` global flag, the `$DIG_NODE_URL` environment variable, a per-project `digs config node.url --local `, or a machine-wide `digs config node.url `; leave them all unset to use the automatic resolution, which prefers your own node. See [Which node dig-store talks to](../digstore/cli/command-reference.md#which-node-digstore-talks-to). ## Wallet data (extension) diff --git a/package.json b/package.json index 09fc676..fa21e06 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "docs-dig-net", - "version": "0.11.4", + "version": "0.12.0", "private": true, "scripts": { "docusaurus": "docusaurus", From 95cc7ee3706d1d7312a0350822de6a5a098bccd1 Mon Sep 17 00:00:00 2001 From: Michael Taylor Date: Tue, 4 Aug 2026 11:26:51 -0700 Subject: [PATCH 2/3] docs(cli): the node ladder is plain HTTPS today, not mTLS MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The resolution section claimed 'connections to any tier use mTLS with a client certificate derived from your identity key'. That is not what ships: `digstore-remote`'s TransportMode marks Mtls NOT YET WIRED and the resolver refuses it, so every tier is reached over plain HTTPS (loopback over plain HTTP) with the §21.9 signed identity headers doing the authenticating. Telling a reader their traffic is mutually authenticated when it is not is the kind of docs error that changes what someone is willing to send. Corrected to describe what ships, and to say mTLS is specified-but-pending rather than dropping the mention. Co-Authored-By: Claude --- docs/digstore/cli/command-reference.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/digstore/cli/command-reference.md b/docs/digstore/cli/command-reference.md index a93075f..4af5ddb 100644 --- a/docs/digstore/cli/command-reference.md +++ b/docs/digstore/cli/command-reference.md @@ -84,7 +84,9 @@ Every command that reaches a node (`clone`, `pull`, `push`, reads, `serve` peers Your own node comes first: `rpc.dig.net` is an ordinary node that happens to be well known, not a privileged one, and it is only used when nothing local answers. -Each tier is a cheap health probe with a short timeout, so dig-store never hangs waiting on an unreachable local node. Connections to any tier use mTLS with a client certificate derived from your identity key; `rpc.dig.net` additionally serves plain HTTPS for browsers, which can't present a client certificate. See [Point a consumer at your node](../../run-a-node/point-a-consumer.md) for the same ladder as it applies to the DIG Browser and extension. +Each tier is a cheap health probe with a short timeout, so dig-store never hangs waiting on an unreachable local node. + +Today every tier is reached over plain HTTPS (loopback tiers over plain HTTP), with each request carrying your signed identity headers — that signature, not the transport, is what authenticates you. Mutual TLS with a client certificate derived from your identity key is specified for node-class clients but is **not yet wired**; when it lands, it will be layered under the same signed requests rather than replacing them. See [Point a consumer at your node](../../run-a-node/point-a-consumer.md) for the same ladder as it applies to the DIG Browser and extension. #### Setting a node per project {#per-project-node} From ff70deb09b610c3d69a60912c1d52ed6bbfa5e96 Mon Sep 17 00:00:00 2001 From: Michael Taylor Date: Tue, 4 Aug 2026 12:28:05 -0700 Subject: [PATCH 3/3] docs(rpc): the dig-remote ladder is plain HTTPS today, not mTLS MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The same over-claim as the command-reference page, twelve lines below a list I had already rewritten: 'Connections to any of the three tiers use mTLS, presenting a client certificate derived from your identity key'. TransportMode::Mtls is NOT YET WIRED and the resolver refuses it, so what authenticates a request today is the §21.9 signature, not the transport. Same replacement applied, so both pages now say the same true thing. Co-Authored-By: Claude --- docs/rpc/dig-remote.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/rpc/dig-remote.md b/docs/rpc/dig-remote.md index a9fe071..c2d3b9e 100644 --- a/docs/rpc/dig-remote.md +++ b/docs/rpc/dig-remote.md @@ -60,7 +60,7 @@ An unconfigured `origin` follows this same order, so it means *your* node by def Each tier is a cheap health probe with a short timeout, so an unreachable local node falls through quickly rather than hanging a `clone`/`pull`/`push`. See [Which node dig-store talks to](../digstore/cli/command-reference.md#which-node-digstore-talks-to) for how to set an override, and [Point a consumer at your node](../run-a-node/point-a-consumer.md) for the same ladder as it applies to the DIG Browser and extension. -Connections to any of the three tiers use mTLS, presenting a client certificate derived from your identity key — the same per-request signing described below rides on top of that authenticated channel. +Today every tier is reached over plain HTTPS (loopback tiers over plain HTTP), and the per-request signing described below is what authenticates you — not the transport. Mutual TLS with a client certificate derived from your identity key is specified for node-class clients but is **not yet wired**; when it lands, the same signed requests will ride on top of that authenticated channel rather than being replaced by it. ## Every request is signed (per-request auth)