diff --git a/docs/digstore/cli/command-reference.md b/docs/digstore/cli/command-reference.md index 461a33d..4af5ddb 100644 --- a/docs/digstore/cli/command-reference.md +++ b/docs/digstore/cli/command-reference.md @@ -67,20 +67,53 @@ 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. -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. +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. + +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} + +`--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 diff --git a/docs/rpc/dig-remote.md b/docs/rpc/dig-remote.md index 58afe97..c2d3b9e 100644 --- a/docs/rpc/dig-remote.md +++ b/docs/rpc/dig-remote.md @@ -51,14 +51,16 @@ 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. +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) 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",