brane 0.1.1 → 0.3.1

package/dist/test/token-lapse.test.js

@@ -0,0 +1,94 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { createTestDb } from "./helpers.js";
+import { DbTokenStore } from "../db/tokens.js";
+import { TokenRing, UNUSED_TOKEN_LAPSE_MS, hashToken } from "../daemon/token-ring.js";
+import { mintDeviceTokenRoute } from "../daemon/token-routes.js";
+const T0 = Date.UTC(2026, 9, 3, 12);
+const LATE = T0 + UNUSED_TOKEN_LAPSE_MS;
+function setup() {
+    const db = createTestDb();
+    const store = new DbTokenStore(db);
+    const revokedAt = (id) => db.prepare("SELECT revoked_at FROM tokens WHERE id = ?").get(id).revoked_at;
+    return { db, store, revokedAt };
+}
+describe("unused device tokens lapse", () => {
+    it("refuses a minted device token never used within the window, and revokes its row", () => {
+        const { store, revokedAt } = setup();
+        const rec = store.insert(hashToken("qr"), "device", "melded", T0);
+        assert.equal(store.find(hashToken("qr"), LATE), null);
+        assert.equal(revokedAt(rec.id), LATE);
+        assert.equal(store.find(hashToken("qr"), LATE + 1), null, "and stays refused");
+    });
+    it("accepts it just inside the window", () => {
+        const { store } = setup();
+        const rec = store.insert(hashToken("qr"), "device", "melded", T0);
+        assert.equal(store.find(hashToken("qr"), LATE - 1)?.id, rec.id);
+    });
+    it("keeps a token for good once it has been used", () => {
+        const { store } = setup();
+        store.insert(hashToken("qr"), "device", "melded", T0);
+        assert.ok(store.find(hashToken("qr"), T0 + 1000));
+        assert.ok(store.find(hashToken("qr"), T0 + 30 * 24 * 3600_000));
+    });
+    it("counts a first use recorded on disk by an earlier daemon", () => {
+        const { db } = setup();
+        const store = new DbTokenStore(db);
+        store.insert(hashToken("qr"), "device", "melded", T0);
+        store.find(hashToken("qr"), T0 + 1000);
+        // A restart: a new store with no memory of that use.
+        assert.ok(new DbTokenStore(db).find(hashToken("qr"), LATE + 1));
+    });
+    it("never lapses the local row or an adopted token", () => {
+        const { store } = setup();
+        store.insert(hashToken("local"), "local", "this machine", T0);
+        store.adopt(hashToken("old-shared"), "device", "melded before hashing", T0);
+        assert.ok(store.find(hashToken("local"), LATE * 2));
+        assert.ok(store.find(hashToken("old-shared"), LATE * 2));
+    });
+    it("sweeps unused rows without anyone presenting them, and only those", () => {
+        const { store, revokedAt } = setup();
+        const unused = store.insert(hashToken("unscanned"), "device", "melded", T0);
+        const used = store.insert(hashToken("scanned"), "device", "melded", T0);
+        const fresh = store.insert(hashToken("just-minted"), "device", "melded", LATE - 1000);
+        const local = store.insert(hashToken("local"), "local", "this machine", T0);
+        store.find(hashToken("scanned"), T0 + 1000);
+        assert.equal(store.lapseUnused(LATE), 1);
+        assert.equal(revokedAt(unused.id), LATE);
+        assert.equal(revokedAt(used.id), null);
+        assert.equal(revokedAt(fresh.id), null);
+        assert.equal(revokedAt(local.id), null);
+        assert.equal(store.lapseUnused(LATE), 0, "a second sweep finds nothing");
+    });
+    it("does not lapse a token used in this process whose last_used_at write was lost", () => {
+        const { db, store } = setup();
+        const rec = store.insert(hashToken("qr"), "device", "melded", T0);
+        assert.ok(store.find(hashToken("qr"), T0 + 1000));
+        // Simulate the best-effort stamp having failed.
+        db.prepare("UPDATE tokens SET last_used_at = NULL WHERE id = ?").run(rec.id);
+        assert.equal(store.lapseUnused(LATE), 0);
+        assert.ok(store.find(hashToken("qr"), LATE + 1));
+    });
+    it("writes a rotation's replacement as used, so a device that only holds a socket keeps it", () => {
+        const { db, store } = setup();
+        store.insert(hashToken("phone"), "device", "phone", T0);
+        const ring = new TokenRing(store, () => "phone-2");
+        assert.ok(ring.authenticate("phone", T0 + 1000).ok);
+        const { token } = ring.beginRotation(store.find(hashToken("phone"), T0 + 1000), T0 + 2000);
+        const auth = ring.authenticate(token, T0 + 3000);
+        assert.ok(auth.ok && auth.retired);
+        const row = db.prepare("SELECT last_used_at FROM tokens WHERE hash = ?").get(hashToken("phone-2"));
+        assert.equal(row.last_used_at, T0 + 3000);
+        // Ten minutes of nothing but an open socket later, it still authenticates.
+        assert.ok(new DbTokenStore(db).find(hashToken("phone-2"), T0 + 3000 + UNUSED_TOKEN_LAPSE_MS * 2));
+    });
+    it("tells the minting client when its token lapses", () => {
+        const { store } = setup();
+        const ring = new TokenRing(store, () => "qr");
+        const res = mintDeviceTokenRoute(ring, "{}", T0);
+        assert.ok(res.status === 200);
+        assert.equal(res.body.expiresAt, LATE);
+        assert.equal(res.body.validForMs, UNUSED_TOKEN_LAPSE_MS);
+    });
+});
+//# sourceMappingURL=token-lapse.test.js.map

package/dist/test/token-ring.test.js

@@ -0,0 +1,188 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { TokenRing, MemoryTokenStore, ROTATION_GRACE_MS, hashToken, } from "../daemon/token-ring.js";
+import { DbTokenStore } from "../db/tokens.js";
+import { createTestDb } from "./helpers.js";
+// Every case runs against both stores: the in-memory one, and the SQLite one
+// the daemon uses, so what is pinned here is the real rotation, not a double.
+const STORES = [
+    ["memory", (seed) => new MemoryTokenStore(seed)],
+    [
+        "sqlite",
+        (seed) => {
+            const store = new DbTokenStore(createTestDb());
+            // Seeded as devices already in use: an unused device row minted at 0
+            // would have lapsed long before these tests' real clock.
+            for (const s of seed)
+                store.insert(hashToken(s.token), s.kind, s.label ?? s.kind, 0, { used: true });
+            return store;
+        },
+    ],
+];
+for (const [storeName, makeStore] of STORES) {
+    function ring(...minted) {
+        const queue = [...minted];
+        const store = makeStore([
+            { token: "local", kind: "local", label: "this machine" },
+            { token: "phone", kind: "device", label: "phone" },
+            { token: "laptop", kind: "device", label: "laptop" },
+        ]);
+        const r = new TokenRing(store, () => queue.shift() ?? "unexpected-mint");
+        const record = (token) => {
+            const a = r.authenticate(token);
+            assert.ok(a.ok, `${token} should authenticate`);
+            return a.record;
+        };
+        return { r, store, record };
+    }
+    describe(`TokenRing (${storeName} store)`, () => {
+        it("authenticates live tokens and nothing else", () => {
+            const { r } = ring();
+            assert.equal(r.authenticate("local").ok, true);
+            assert.equal(r.authenticate("phone").ok, true);
+            assert.deepEqual(r.authenticate("nope"), { ok: false });
+            assert.deepEqual(r.authenticate(null), { ok: false });
+            assert.deepEqual(r.authenticate(""), { ok: false });
+        });
+        it("stores only hashes", () => {
+            const store = makeStore([]);
+            const r = new TokenRing(store, () => "minted");
+            const { token, record } = r.issue("device", "tablet");
+            assert.equal(token, "minted");
+            assert.deepEqual(store.find(hashToken("minted"), 0), record);
+            assert.equal(store.find("minted", 0), null);
+        });
+        it("beginRotation mints a pending token and leaves every live token in place", () => {
+            const { r, record } = ring("new");
+            const t0 = 1_000;
+            assert.deepEqual(r.beginRotation(record("phone"), t0), {
+                token: "new",
+                expiresAt: t0 + ROTATION_GRACE_MS,
+                replaced: false,
+            });
+            // Nothing durable has moved: every token still authenticates, without consequence.
+            for (const t of ["local", "phone", "laptop"]) {
+                const a = r.authenticate(t, t0 + 1);
+                assert.equal(a.ok, true);
+                assert.equal(a.ok && a.retired, undefined);
+            }
+        });
+        it("first use of the pending token retires the requester and every other device, exactly once", () => {
+            const { r, record } = ring("new");
+            const phone = record("phone");
+            const laptop = record("laptop");
+            r.beginRotation(phone, 0);
+            const confirmed = r.authenticate("new", 10);
+            assert.ok(confirmed.ok);
+            assert.equal(confirmed.record.kind, "device");
+            assert.equal(confirmed.record.label, "phone");
+            assert.deepEqual(new Set(confirmed.retired?.ids), new Set([phone.id, laptop.id]));
+            assert.equal(r.pendingRotation(10), null);
+            // The retirement is reported on that one request only.
+            const again = r.authenticate("new", 11);
+            assert.ok(again.ok);
+            assert.equal(again.retired, undefined);
+            // And the old device tokens are dead from that moment.
+            assert.deepEqual(r.authenticate("phone", 11), { ok: false });
+            assert.deepEqual(r.authenticate("laptop", 11), { ok: false });
+            // This machine rides through a device's rotation: the CLI and MCP
+            // bridges are not "other devices".
+            assert.equal(r.authenticate("local", 11).ok, true);
+        });
+        it("refuses to begin a rotation for this account, which would mint a token that opens the local row", () => {
+            const { r, record } = ring("new-local");
+            const local = record("local");
+            assert.throws(() => r.beginRotation(local, 0), /holds no token to rotate/);
+            assert.equal(r.pendingRotation(0), null);
+            assert.deepEqual(r.authenticate("new-local", 1), { ok: false }, "nothing was minted");
+            for (const t of ["local", "phone", "laptop"])
+                assert.equal(r.authenticate(t, 2).ok, true, `${t} is untouched`);
+        });
+        it("signOutDevices revokes every device at once, keeps this account, and voids a pending rotation", () => {
+            const { r, record } = ring("phone-2");
+            const local = record("local");
+            r.beginRotation(record("phone"), 0);
+            const out = r.signOutDevices(local, 1);
+            assert.equal(out.devices, 2);
+            assert.equal(out.ids.length, 2);
+            assert.equal(out.replaced, true);
+            for (const t of ["phone", "laptop"])
+                assert.deepEqual(r.authenticate(t, 2), { ok: false });
+            assert.equal(r.authenticate("local", 2).ok, true);
+            // The phone's pending token must not write it back in.
+            assert.deepEqual(r.authenticate("phone-2", 2), { ok: false });
+            assert.deepEqual(r.signOutDevices(local, 3), { ids: [], devices: 0, replaced: false });
+        });
+        it("a second rotate during the window replaces the pending token, never re-issues it", () => {
+            // Anyone holding a token can call rotate. If the daemon answered a second
+            // call with the token already pending, an attacker racing the operator
+            // would be handed the new credential and could use it first — and the
+            // operator's own confirm would still succeed, hiding the guest.
+            const { r, record } = ring("first", "second");
+            const a = r.beginRotation(record("phone"), 0);
+            const b = r.beginRotation(record("laptop"), 30_000);
+            assert.equal(a.replaced, false);
+            assert.deepEqual(b, { token: "second", expiresAt: 30_000 + ROTATION_GRACE_MS, replaced: true });
+            // The first pending token is dead: the requester who got it sees a 401
+            // on confirm, which is the visible failure the design wants.
+            assert.deepEqual(r.authenticate("first", 31_000), { ok: false });
+            const confirmed = r.authenticate("second", 31_000);
+            assert.ok(confirmed.ok && confirmed.retired);
+            assert.equal(confirmed.record.label, "laptop");
+        });
+        it("an unused pending token lapses and every token simply remains", () => {
+            const { r, record } = ring("new", "newer");
+            const phone = record("phone");
+            r.beginRotation(phone, 0);
+            const late = ROTATION_GRACE_MS;
+            assert.deepEqual(r.authenticate("new", late), { ok: false });
+            assert.equal(r.authenticate("phone", late).ok, true);
+            assert.equal(r.pendingRotation(late), null);
+            // A fresh rotate after the lapse mints anew rather than reviving the stale one.
+            // A lapsed pending token is gone, not "replaced" — nothing was live.
+            assert.deepEqual(r.beginRotation(phone, late), {
+                token: "newer",
+                expiresAt: late + ROTATION_GRACE_MS,
+                replaced: false,
+            });
+        });
+        it("revoked tokens stay revoked across several rotations", () => {
+            const { r, record } = ring("b", "c");
+            r.beginRotation(record("phone"), 0);
+            const b = r.authenticate("b", 1);
+            assert.ok(b.ok);
+            r.beginRotation(b.record, 2);
+            const c = r.authenticate("c", 3);
+            assert.ok(c.ok && c.retired);
+            assert.deepEqual(c.retired.ids, [b.record.id]);
+            for (const t of ["phone", "laptop", "b"])
+                assert.deepEqual(r.authenticate(t, 4), { ok: false });
+            assert.equal(r.authenticate("c", 4).ok, true);
+        });
+    });
+    describe(`TokenRing rotation is all or nothing (${storeName} store)`, () => {
+        it("a failed write leaves every token as it was and the pending token usable", () => {
+            const store = makeStore([
+                { token: "phone", kind: "device" },
+                { token: "laptop", kind: "device" },
+            ]);
+            const r = new TokenRing(store, () => "new");
+            const phone = r.authenticate("phone");
+            assert.ok(phone.ok);
+            r.beginRotation(phone.record, 0);
+            const revoke = store.revoke.bind(store);
+            store.revoke = () => { throw new Error("disk full"); };
+            assert.throws(() => r.authenticate("new", 1), /disk full/);
+            // Nothing landed: the old tokens work, and the new one is not a row yet.
+            assert.equal(r.authenticate("phone", 2).ok, true);
+            assert.equal(r.authenticate("laptop", 2).ok, true);
+            assert.equal(store.find(hashToken("new"), 2), null);
+            // The pending token survived, so the retry completes the rotation.
+            store.revoke = revoke;
+            const retry = r.authenticate("new", 3);
+            assert.ok(retry.ok && retry.retired);
+            assert.equal(r.authenticate("phone", 4).ok, false);
+        });
+    });
+}
+//# sourceMappingURL=token-ring.test.js.map

package/dist/test/token-rotate-cli.test.js

@@ -0,0 +1,58 @@
+/**
+ * `brane token rotate` is a thin client of POST /api/token/rotate, and from
+ * the shell it is one request: this machine holds no token, so there is none
+ * to swap and nothing to confirm — the daemon signs every device out before
+ * it answers. This pins that shape against a scripted daemon, and that an
+ * older daemon's two-step answer is reported instead of being taken for a
+ * sign-out that never happened.
+ */
+import { describe, it, before, after, beforeEach } from "node:test";
+import assert from "node:assert/strict";
+import { createServer } from "node:http";
+import { rotateDaemonToken, formatRotateResult } from "../commands/token.js";
+describe("brane token rotate", () => {
+    let server;
+    let endpoint;
+    let answer;
+    const seen = [];
+    before(async () => {
+        server = createServer((req, res) => {
+            seen.push([req.method ?? "", req.url ?? ""]);
+            res.writeHead(200, { "Content-Type": "application/json" });
+            res.end(JSON.stringify(answer));
+        });
+        await new Promise((r) => server.listen(0, "127.0.0.1", r));
+        const port = server.address().port;
+        // Over TCP with a token only so the test needs no socket; who may ask is
+        // the daemon's business (src/test/presence-gate.test.ts).
+        endpoint = { baseUrl: `http://127.0.0.1:${port}`, token: "t", port: String(port) };
+    });
+    beforeEach(() => {
+        seen.length = 0;
+    });
+    after(async () => {
+        server.closeAllConnections();
+        await new Promise((r) => server.close(() => r()));
+    });
+    it("is one request, with nothing to confirm", async () => {
+        answer = { signed_out: 2, replaced: false };
+        assert.deepEqual(await rotateDaemonToken(endpoint), { signed_out: 2, replaced: false });
+        assert.deepEqual(seen, [["POST", "/api/token/rotate"]]);
+    });
+    it("reports an older daemon's two-step answer rather than claiming a sign-out", async () => {
+        answer = { token: "new", expires_at: 0, replaced: false };
+        await assert.rejects(rotateDaemonToken(endpoint), /older brane.*nobody was signed out.*brane daemon restart/);
+        assert.deepEqual(seen, [["POST", "/api/token/rotate"]], "and never presents the token it was handed");
+    });
+    it("prints what changed and what did not", () => {
+        const text = formatRotateResult({ signed_out: 2, replaced: false });
+        assert.match(text, /Signed out 2 devices/);
+        assert.match(text, /This shell and running agents are unaffected/);
+        assert.match(text, /brane meld/);
+        assert.doesNotMatch(text, /pending/);
+        assert.match(formatRotateResult({ signed_out: 1, replaced: false }), /Signed out 1 device\./);
+        assert.match(formatRotateResult({ signed_out: 0, replaced: false }), /no devices/);
+        assert.match(formatRotateResult({ signed_out: 1, replaced: true }), /never confirmed was pending/);
+    });
+});
+//# sourceMappingURL=token-rotate-cli.test.js.map

package/dist/test/token-routes.test.js

@@ -0,0 +1,95 @@
+/**
+ * The token routes' own logic, outside the server closure: minting a device
+ * token from a request body, and finishing a rotation — closing the sockets
+ * the retired rows opened, and no others.
+ */
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { TokenRing, MemoryTokenStore, WS_CLOSE_TOKEN_ROTATED } from "../daemon/token-ring.js";
+import { mintDeviceTokenRoute, retireTokens } from "../daemon/token-routes.js";
+function freshRing(...minted) {
+    const queue = [...minted];
+    return new TokenRing(new MemoryTokenStore([
+        { token: "local", kind: "local", label: "this machine" },
+        { token: "phone", kind: "device", label: "phone" },
+    ]), () => queue.shift() ?? "unexpected-mint");
+}
+describe("mintDeviceTokenRoute", () => {
+    it("mints a device token that authenticates", () => {
+        const ring = freshRing("tablet-token");
+        const res = mintDeviceTokenRoute(ring, JSON.stringify({ label: "tablet" }));
+        assert.equal(res.status, 200);
+        assert.ok(res.status === 200);
+        assert.equal(res.body.token, "tablet-token");
+        assert.equal(res.body.label, "tablet");
+        const auth = ring.authenticate("tablet-token");
+        assert.ok(auth.ok);
+        assert.equal(auth.record.kind, "device");
+    });
+    it("labels by date when no label is given, empty body included", () => {
+        const now = Date.UTC(2026, 9, 3);
+        for (const body of [undefined, "", "{}", JSON.stringify({ label: "   " })]) {
+            const res = mintDeviceTokenRoute(freshRing("t"), body, now);
+            assert.ok(res.status === 200, `body ${JSON.stringify(body)}`);
+            assert.equal(res.body.label, "melded 2026-10-03");
+        }
+    });
+    it("caps a label at 200 characters", () => {
+        const res = mintDeviceTokenRoute(freshRing("t"), JSON.stringify({ label: "x".repeat(500) }));
+        assert.ok(res.status === 200);
+        assert.equal(res.body.label.length, 200);
+    });
+    it("refuses a body that is not a JSON object, and mints nothing", () => {
+        for (const body of ["not json", "null", "[]", "42"]) {
+            const ring = freshRing("should-not-mint");
+            const res = mintDeviceTokenRoute(ring, body);
+            assert.equal(res.status, 400, `body ${body}`);
+            assert.equal(ring.authenticate("should-not-mint").ok, false);
+        }
+    });
+});
+class FakeSocket {
+    closed = [];
+    close(code, reason) {
+        this.closed.push([code, reason]);
+    }
+}
+function rotate(ring, requester, next) {
+    const r = ring.authenticate(requester);
+    assert.ok(r.ok);
+    ring.beginRotation(r.record);
+    const confirmed = ring.authenticate(next);
+    assert.ok(confirmed.ok && confirmed.retired);
+    return { requester: r.record, confirmed: { record: confirmed.record, retired: confirmed.retired } };
+}
+describe("retireTokens", () => {
+    it("closes only the sockets opened under revoked rows, with 4401", () => {
+        const ring = freshRing("new-phone");
+        const local = ring.authenticate("local");
+        assert.ok(local.ok);
+        const { requester, confirmed } = rotate(ring, "phone", "new-phone");
+        const onOldPhone = new FakeSocket();
+        const onLocal = new FakeSocket();
+        const onNewPhone = new FakeSocket();
+        const sockets = new Map([
+            [onOldPhone, requester.id],
+            [onLocal, local.record.id],
+            [onNewPhone, confirmed.record.id],
+        ]);
+        const { closed } = retireTokens({ ...confirmed, viewerSockets: sockets });
+        assert.equal(closed, 1);
+        assert.deepEqual(onOldPhone.closed, [[WS_CLOSE_TOKEN_ROTATED, "token rotated"]]);
+        assert.deepEqual(onLocal.closed, []);
+        assert.deepEqual(onNewPhone.closed, []);
+        assert.deepEqual([...sockets.keys()], [onLocal, onNewPhone]);
+    });
+});
+describe("mintDeviceTokenRoute labels", () => {
+    it("replaces control characters, so a label cannot forge a log line", () => {
+        const res = mintDeviceTokenRoute(freshRing("t"), JSON.stringify({ label: "phone\n[token] minted device token \"x\"\u0007" }));
+        assert.ok(res.status === 200);
+        assert.doesNotMatch(res.body.label, /[\u0000-\u001f\u007f-\u009f]/);
+        assert.equal(res.body.label, 'phone [token] minted device token "x"');
+    });
+});
+//# sourceMappingURL=token-routes.test.js.map