brane 0.3.3 → 0.3.5

package/dist/test/tailnet.test.js

@@ -0,0 +1,125 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { checkMeldHost, hostnameOf, isFirstMeld, meldRefusalMessage, tailnetOf, trustDomainOf, } from "../shared/tailnet.js";
+describe("tailnetOf", () => {
+    it("reads the tailnet off a MagicDNS name, port or not", () => {
+        assert.equal(tailnetOf("mac.tail1234.ts.net"), "tail1234.ts.net");
+        assert.equal(tailnetOf("mac.tail1234.ts.net:47443"), "tail1234.ts.net");
+        assert.equal(tailnetOf("Mac.Tail1234.TS.net."), "tail1234.ts.net");
+        assert.equal(tailnetOf("mac.cat-crocodile.ts.net"), "cat-crocodile.ts.net");
+    });
+    it("is null for anything that is not a machine under a tailnet", () => {
+        assert.equal(tailnetOf("tail1234.ts.net"), null);
+        assert.equal(tailnetOf("ts.net"), null);
+        assert.equal(tailnetOf("100.101.102.103:58353"), null);
+        assert.equal(tailnetOf("brane.organelle.dev"), null);
+        assert.equal(tailnetOf("mac.tail1234.ts.net.evil.com"), null);
+        assert.equal(tailnetOf("localhost:8081"), null);
+    });
+});
+describe("trustDomainOf", () => {
+    it("is the tailnet for a MagicDNS name", () => {
+        assert.equal(trustDomainOf("mac.tail1234.ts.net:47443"), "tail1234.ts.net");
+    });
+    it("is one domain for every loopback spelling", () => {
+        for (const h of ["localhost", "localhost:58353", "127.0.0.1:58353", "127.9.9.9", "[::1]:58353", "app.localhost"]) {
+            assert.equal(trustDomainOf(h), "localhost", h);
+        }
+    });
+    it("is the hostname itself for any other host", () => {
+        assert.equal(trustDomainOf("100.101.102.103:58353"), "100.101.102.103");
+        assert.equal(trustDomainOf("192.168.1.5:58353"), "192.168.1.5");
+        assert.equal(trustDomainOf("brane.example.com"), "brane.example.com");
+    });
+    it("is null for what is not a host", () => {
+        for (const h of ["", "  ", "https://mac.tail1234.ts.net", "mac.tail1234.ts.net/x", "user@mac.tail1234.ts.net", "a b"]) {
+            assert.equal(trustDomainOf(h), null, h);
+            assert.equal(hostnameOf(h), null, h);
+        }
+    });
+});
+describe("checkMeldHost", () => {
+    const home = ["mac.tail1234.ts.net:47443", "studio.tail1234.ts.net:51000"];
+    it("lets the first meld pick the domain, and says it does", () => {
+        assert.deepEqual(checkMeldHost("evil.tail5678.ts.net", []), { ok: true, domain: "tail5678.ts.net", setsHome: true });
+        assert.deepEqual(checkMeldHost("192.168.1.5:58353", []), { ok: true, domain: "192.168.1.5", setsHome: true });
+    });
+    it("admits another machine on the same tailnet", () => {
+        assert.deepEqual(checkMeldHost("fly-box.tail1234.ts.net", home), { ok: true, domain: "tail1234.ts.net", setsHome: false });
+    });
+    it("refuses a daemon on another tailnet, which is what a Funnel host is", () => {
+        assert.deepEqual(checkMeldHost("ben-macbook.tail5678.ts.net", home), {
+            ok: false,
+            domain: "tail5678.ts.net",
+            home: ["tail1234.ts.net"],
+        });
+    });
+    it("refuses IPs and public names beside a tailnet, and the reverse", () => {
+        for (const h of ["100.101.102.103:58353", "192.168.1.5:58353", "brane.organelle.dev"]) {
+            assert.equal(checkMeldHost(h, home).ok, false, h);
+        }
+        assert.equal(checkMeldHost("mac.tail1234.ts.net", ["100.101.102.103:58353"]).ok, false);
+    });
+    it("admits loopback beside a tailnet, without it deciding anything", () => {
+        for (const h of ["127.0.0.1:58353", "localhost:58353", "[::1]:58353"]) {
+            assert.deepEqual(checkMeldHost(h, home), { ok: true, domain: "localhost", setsHome: false }, h);
+            assert.deepEqual(checkMeldHost(h, []), { ok: true, domain: "localhost", setsHome: false }, h);
+        }
+    });
+    it("treats a browser with only loopback daemons as holding no domain, so its first tailnet is screened", () => {
+        assert.deepEqual(checkMeldHost("mac.tail1234.ts.net", ["localhost:58353"]), { ok: true, domain: "tail1234.ts.net", setsHome: true });
+        // …and once that tailnet is held, loopback beside it decides nothing.
+        assert.deepEqual(checkMeldHost("other.tail5678.ts.net", ["localhost:58353", "mac.tail1234.ts.net"]), {
+            ok: false,
+            domain: "tail5678.ts.net",
+            home: ["tail1234.ts.net"],
+        });
+    });
+    it("lets a browser that already holds two domains add to either, and nothing else", () => {
+        const mixed = ["mac.tail1234.ts.net", "box.tail5678.ts.net"];
+        assert.equal(checkMeldHost("other.tail5678.ts.net", mixed).ok, true);
+        const third = checkMeldHost("x.tail9999.ts.net", mixed);
+        assert.deepEqual(third, { ok: false, domain: "tail9999.ts.net", home: ["tail1234.ts.net", "tail5678.ts.net"] });
+    });
+    it("refuses an unparseable candidate and ignores unparseable stored hosts", () => {
+        assert.deepEqual(checkMeldHost("https://mac.tail1234.ts.net", []), { ok: false, domain: null, home: [] });
+        assert.equal(checkMeldHost("mac.tail1234.ts.net", ["not a host"]).ok, true);
+    });
+});
+describe("meldRefusalMessage", () => {
+    it("names both tailnets and the ways out", () => {
+        const v = checkMeldHost("evil.tail5678.ts.net:443", ["mac.tail1234.ts.net"]);
+        assert.equal(v.ok, false);
+        if (v.ok)
+            return;
+        const msg = meldRefusalMessage("evil.tail5678.ts.net:443", v);
+        assert.match(msg, /^evil\.tail5678\.ts\.net is on tail5678\.ts\.net, but this browser's daemons are on tail1234\.ts\.net\./);
+        assert.match(msg, /another browser or profile/);
+    });
+});
+describe("isFirstMeld", () => {
+    const ok = (candidate, hosts) => {
+        const v = checkMeldHost(candidate, hosts);
+        assert.equal(v.ok, true);
+        return v;
+    };
+    const APP = "brane.organelle.dev";
+    it("warns in a browser with no daemons, loopback link included", () => {
+        assert.equal(isFirstMeld([], ok("mac.tail1234.ts.net", []), "mac.tail1234.ts.net", APP), true);
+        assert.equal(isFirstMeld([], ok("127.0.0.1:58353", []), "127.0.0.1:58353", APP), true);
+    });
+    it("warns when the meld picks the domain beside loopback daemons", () => {
+        const hosts = ["localhost:58353"];
+        assert.equal(isFirstMeld(hosts, ok("mac.tail1234.ts.net", hosts), "mac.tail1234.ts.net", APP), true);
+    });
+    it("doesn't warn once the domain is held", () => {
+        const hosts = ["mac.tail1234.ts.net"];
+        assert.equal(isFirstMeld(hosts, ok("box.tail1234.ts.net", hosts), "box.tail1234.ts.net", APP), false);
+        assert.equal(isFirstMeld(hosts, ok("localhost:58353", hosts), "localhost:58353", APP), false);
+    });
+    it("never warns on the daemon's own origin, where Isolate lands", () => {
+        const host = "mac.tail1234.ts.net:47443";
+        assert.equal(isFirstMeld([], ok(host, []), host, "MAC.tail1234.ts.net:47443"), false);
+    });
+});
+//# sourceMappingURL=tailnet.test.js.map

package/docs/daemon-api.md

@@ -25,14 +25,15 @@ until someone lists it. An agent also may not revive or prompt a
 | Method | Path | Purpose |
 |--------|------|---------|
 | `GET` | `/api/status` | Daemon status (brane_id, hostname, username, pid, port, uptime_ms, `tls: { state, expires_at, ... }`, `app_domain`: the shared app's host, where a daemon's own bundle hops out to on Isolate — see [View URLs](view-urls.md)) |
-| `GET` | `/api/narratives?archived=1` | List narratives (excludes archived by default) |
+| `GET` | `/api/narratives?archived=1&brane_ids=` | List narratives (excludes archived by default). Without `brane_ids`, an archived brane's ended narratives are left out too |
 | `GET` | `/api/narratives/recent?since=&search=&status=&fold=&limit=&archived=1&brane_ids=` | Recently active narratives — the browse half of the `narrative_info` MCP tool; every brane unless `brane_ids` scopes it |
 | `PATCH` | `/api/narratives/:id/archive` | Archive/unarchive a narrative; archiving a running one is a 409 (`src/daemon/archive-gate.ts`) |
 | `GET` | `/api/narratives/:id/events?after=N&before=S&tail=T` | Fetch events with cursor-based query |
 | `POST` | `/api/narratives/:id/signal` | Send operator signal (supports payloads). `source` is stamped from the token (`web` for a device, `local` for this account); a `source` in the body is ignored, and an agent's token is refused (`src/daemon/signal-source.ts`) |
 | `GET` | `/api/narratives/:id/export?format=html[&palette=N][&seqs=A,B,C][&seqs_mode=except]` | Conversation as a standalone HTML document; `palette` is the device's 🎨 Recolor salt, so foreign speakers wear the hues the operator sees, `seqs` is the chat's message selection, and `seqs_mode=except` exports its complement — see [Export Scope](export-scope.md) |
 | `GET` | `/api/payloads/:nid/:filename` | Serve stored payload files (immutable, cached) |
-| `GET` | `/api/branes` | List branes with narrative counts, home flag, and `cost: [{ unit, amount, metered }]` — per-unit running totals over every narrative, archived included |
+| `GET` | `/api/branes?archived=1` | List branes with narrative counts, home flag, `archived` flag, and `cost: [{ unit, amount, metered }]` — per-unit running totals over every narrative, archived included. Archived branes are left out unless `archived=1` — see [Multi-Brane](multi-brane.md#archived-branes) |
+| `PATCH` | `/api/branes/archive` | Archive/unarchive a brane (`{ brane_id, archived }`). Refuses the home brane and the last brane not archived (400) and an unknown one (404); never deletes anything |
 | `GET` | `/api/folds?archived=1` | List registered fold directories (includes brane_id; archived hidden unless asked) |
 | `POST` | `/api/folds` | Register a fold (`{ path, brane_id? }`) — idempotent; see [Folds API](#folds-api) for who may register what |
 | `PATCH` | `/api/folds/archive` | Soft-hide/unhide a fold (`{ path, archived }`) — never deletes the row |
@@ -48,6 +49,7 @@ until someone lists it. An agent also may not revive or prompt a
 | `POST` | `/api/tokens/remote` | A device token for a daemon on another machine, and its hash (`{ token, hash }`), for `brane meld --remote`; nothing is stored, so this response is the one copy of either. Gated like `POST /api/tokens`: the shell waits for the [presence check](presence.md#the-gate), an agent's token gets 403 unasked |
 | `GET` | `/api/tokens` | The Devices list: every live token (`{ tokens }`), each with `device` ("Safari on iPhone", from the User-Agent it was first presented with), `remote_addr`, the latest sighting and `elsewhere_at` (presented from a second address), `minted_by_device`, `last_used_at`, `current` (the requester), `connected`, and `unused` / `expires_at` for a QR nobody has scanned — see [Token Rotation](token-rotation.md#the-devices-list) |
 | `POST` | `/api/tokens/:id/revoke` | Revoke one device token, bodiless, plus `?also=a,b` from the devices it added (each row's `descendants`); every socket it opened (control, terminal, MCP) closes with 4401. Refuses this machine's own `local` row (400), the requester's own (409), and an id that is not live (404), all before any prompt. Signing out a device waits for the [presence check](presence.md#the-gate) from the shell and is refused (403) to an agent's token; revoking an agent does neither |
+| `POST` | `/api/token/forget` | A device signs itself out, bodiless: its own token is revoked and its sockets close. The app's "Delete permanently" on a daemon. Refused (400) to anything but a device token |
 | `POST` | `/api/token/rotate` | From a device: mint a pending replacement token, returned as `{ token, expires_at, replaced }`; the old one is retired on the new one's first use — see [Token Rotation](token-rotation.md). From this machine's shell (no token, over `daemon.sock`): wait for the [presence check](presence.md#the-gate), then sign out every device in this one request, answering `{ signed_out, replaced }`. An agent's token gets 403 |
 | — | `BRANE_DEVICE_TOKEN_SHA256` | Not a route: comma-separated SHA-256 hashes in the daemon's environment, each adopted at startup as a device row unless ever seen before, then dropped from the environment. How `brane meld --remote` hands a remote daemon (a Fly machine, say) a token minted elsewhere — see [Presence Check](presence.md#the-gate) |
 | `POST` | `/api/presence/cancel` | Close the presence prompt that is up (`?id=` from the control socket's `presence` message, so a stale tap closes nothing) → `{ canceled }`. Device tokens only (403 otherwise); there is no approve |

package/docs/multi-brane.md

@@ -12,3 +12,16 @@ A single daemon can host multiple branes. The **home brane** is auto-generated o
 Brane_id resolution chain for new narratives: fold's `brane_id` → `config default.brane` → home brane (`getBraneId`).
 
 Existing folds are backfilled to the home brane on upgrade (idempotent, runs on every `openDatabase()`).
+
+## Archived branes
+
+A brane has no row of its own: it is the `brane_id` its narratives share. Archiving one writes a row in `branes` (`brane_id`, `archived`, `archived_at`), lazily and never deleted; unarchiving clears the flag (`src/db/branes.ts`, `PATCH /api/branes/archive`). The switcher offers it on each brane row's ⋯ and lists archived branes, with **Unarchive**, behind **Show N archived**, under the daemon that holds them.
+
+What an archived brane hides:
+
+- **The brane itself** from `GET /api/branes`, unless `archived=1`. `list_branes` still returns it, flagged `archived`, so an agent can reach it on purpose.
+- **Its ended narratives** from every listing that names no brane: the app's All branes and its cost total, `brane list`, `brane memory log`. Naming the brane (`brane_ids`, or selecting it in the switcher) still shows all of it.
+
+What it never hides is a **running** narrative: one whose status is not `ended`, or whose agent is on the bridge. Archiving a single narrative is refused while it runs (`src/daemon/archive-gate.ts`) so that a rogue agent can't drop out of sight, and an agent may spawn into an archived brane, so the brane must not become a hiding place either.
+
+Two branes can't be archived: the **home brane**, where every spawn without a brane lands, and **the last brane not already archived**, which would leave All branes with nothing. The daemon refuses both with the reason; the switcher doesn't offer them. Archiving is an operator act, closed to agents' tokens.

package/docs/token-rotation.md

@@ -379,6 +379,16 @@ revoke), the **requester's own** token (409; "Sign
 out other devices" keeps this one and signs out the rest), and an id that
 is **not live** (404, which the app treats as done).
 
+A device that does mean to sign itself out uses `POST /api/token/forget`
+(`forgetSelfRoute`, `src/daemon/token-routes.ts`). It is what the app's
+**Delete permanently** on a daemon sends before forgetting it, so deleting
+a daemon from a device leaves no live token on the daemon that nobody
+holds. It is bodiless, revokes the requester's token and the externals it
+dialed in (the devices it added stay), closes its sockets, and is refused
+to anything but a device token. If the daemon can't be reached, the app
+says so and offers to forget it anyway; the token then waits in another
+device's Devices list for a Revoke.
+
 **A revoke can take the devices it added** (`?also=a,b`, in the query
 string so the request stays bodiless; `brane token revoke --cascade`). The
 first thing a stolen token's holder does is mint a spare, and a spare's

package/docs/view-urls.md

@@ -56,15 +56,12 @@ pins, Files path and line, the `?scrollToSeq=` selection) goes through
 since the stack did not grow. So the URL keeps that state and Back returns to
 it, but it never costs an extra Back: browsing ten files is one entry, not ten.
 A bare link to the narrative you are in, with no seq, goes nowhere. The list
-is a jump too: a swipe down on the narrative's header card dismisses it to
-a pushed list, so Back returns to the narrative, whether or not a list was
-already beneath. **All narratives** in the switcher, in a browser, does not
-navigate this tab at all: it is a link that opens the list in a new one, on
-the same daemon (see "A new tab names its daemon" below). On native, and in
-the web app launched from the home screen, it pushes like the swipe: there is
-no tab to open, and on iOS a `_blank` link from a home-screen app lands in a
-browser view that shares none of its storage, so it would open on the meld
-screen. So does
+is a jump too: **All narratives** in the switcher pushes it, so Back returns
+to the narrative, whether or not a list was already beneath. It is an anchor
+like the prose links, so a ⌘-click opens the list in a new tab instead, on
+the same daemon (see "A new tab names its daemon" below). (In 0.3.3 every
+click opened a new tab; that was undone.) So does a swipe down on the
+narrative's header card, which dismisses it. So does
 **Archive** in the narrative's 🦠 menu, once the daemon has confirmed it (the
 pushed list fetches on mount, and nothing is broadcast to correct a fetch that
 raced the archive); Back returns to the archived narrative. Archiving from the
@@ -151,8 +148,8 @@ starts with none: ⌘-click, middle-click, long-press "Open in New Tab" and
 this browser's *default* daemon, which on a shared app with several melded
 need not be the one the link came from. So every in-app anchor names it:
 `inAppLinkProps` (the `@nid`, `nid:seq` and file links in prose, the narrate
-rows in tool groups) and `newTabLinkProps` (**All narratives**) render their
-href with `#daemon=<home brane_id>` (`DAEMON_PARAM`, `withDaemonFragment`),
+rows in tool groups, **All narratives**) renders its href with
+`#daemon=<home brane_id>` (`DAEMON_PARAM`, `withDaemonFragment`),
 while a plain click still navigates in place by the clean path. It goes in the
 fragment because it says which daemon, not what you are looking at: it is a
 connection param (`CONNECTION_PARAMS`), and like the token it never reaches the

package/docs/web-app.md

@@ -16,8 +16,8 @@ The Expo app runs as a web PWA served by the daemon (and optionally via Cloudfla
 - **Archive/unarchive** — from the 🦠 menu, on a list card's status badge or in the narrative's header. Archive is offered only once the session has ended (the same test that swaps End for Revive); Unarchive on any archived narrative. Archiving from the header goes to the list as a jump, so Back returns — see [View URLs](view-urls.md)
 - **Payload rendering** — inline display of image payloads in chat
 - **Export** — download a narrative as standalone HTML via `/api/narratives/:id/export?format=html`. Foreign rows carry their speaker's hue inline, from the same `speakerColor` / `speakerBgColor` the chat uses, at the 🎨 Recolor salt the device sends as `&palette=` — the one place the salt leaves the browser. With messages selected, the menu offers both sides of the selection — **those messages only**, or the conversation with **those messages left out** — see [Export Scope](export-scope.md)
-- **Brane switcher** — dropdown to filter narratives by brane, add/switch daemons. Each brane row (and "All branes") shows its running metered cost as `$2441.72 (138) + 100.2 AIC (1)` — one total per unit with the number of sessions it covers, so a per-session figure can be read off without the line asserting one; the list screen re-reads `/api/branes` (debounced) when a cost `meta` arrives, since the total includes archived narratives the screen never loads. **Devices** lists every token on the active daemon (this device, this machine's CLI and agents, each melded device by browser, platform, address and when it was last seen, and any meld QR not yet scanned) with a Revoke on each other device; **Sign out other devices**, at the foot of that list, rotates instead — see [Token Rotation](token-rotation.md#the-devices-list)
+- **Brane switcher** — dropdown to filter narratives by brane, add/switch daemons. Each row has a ⋯: **Archive** on a brane (on the daemon, for every device — see [Multi-Brane](multi-brane.md#archived-branes)), on another daemon, and, as "Archive this daemon", on the All branes row, which is the active daemon's. An archived daemon stays on this device with its token but is never connected to; **Show N archived** lists archived branes (**Unarchive**) and daemons (**Reconnect**, or **Delete…**, which signs this device out of the daemon with `POST /api/token/forget` and then forgets it). Each brane row (and "All branes") shows its running metered cost as `$2441.72 (138) + 100.2 AIC (1)` — one total per unit with the number of sessions it covers, so a per-session figure can be read off without the line asserting one; the list screen re-reads `/api/branes` (debounced) when a cost `meta` arrives, since the total includes archived narratives the screen never loads. **Devices** lists every token on the active daemon (this device, this machine's CLI and agents, each melded device by browser, platform, address and when it was last seen, and any meld QR not yet scanned) with a Revoke on each other device; **Sign out other devices**, at the foot of that list, rotates instead — see [Token Rotation](token-rotation.md#the-devices-list)
 
 `expo/lib/api.ts` also exports `searchNarratives()`, `searchWiki()`, and `readWikiSection()` clients for `/api/search` and `/api/wiki/*`. These have no UI yet — the transport landed ahead of the views.
 
-Connection via the URL **fragment**, `#host=<host>&token=<token>` on the shared app and `#token=<token>` on a daemon's own bundle (the legacy `?token=` query form is still read). Tailscale hostname auto-detected by `brane meld`. See [View URLs](view-urls.md) for why the fragment, and for the Expo Router trap it has to dodge.
+Connection via the URL **fragment**, `#host=<host>&token=<token>` on the shared app and `#token=<token>` on a daemon's own bundle (the legacy `?token=` query form is still read). Tailscale hostname auto-detected by `brane meld`. See [View URLs](view-urls.md) for why the fragment, and for the Expo Router trap it has to dodge. A browser holds daemons from one tailnet only: a link or **+ Add Daemon** entry for a host on another tailnet is refused before anything is sent to it (`src/shared/tailnet.ts`, SECURITY.md, "One tailnet per browser").