brane 0.1.1 → 0.3.0

package/dist/daemon/gated-routes.js

@@ -0,0 +1,112 @@
+/**
+ * The four routes the presence gate holds, and its cancel route, as
+ * functions of the gate, the token ring and store, and who is asking — out
+ * of the server's closure so the suite can drive them
+ * (`src/test/presence-gate.test.ts`). The server keeps what is about its
+ * sockets: logging, and closing what a revoke signed out.
+ *
+ * Each one checks what it would refuse anyway, then asks, then acts — and
+ * the act re-checks, since rows can change while a prompt is up.
+ */
+import { gateStanding, revokeSignsOutDevice } from "./presence-gate.js";
+import { mintRemoteToken } from "./token-ring.js";
+import { mintDeviceTokenRoute, parseMintBody, planRevoke, revokeTokenRoute } from "./token-routes.js";
+/** What an agent is told for each gated act: it is the operator's to do. */
+const AGENT_REFUSALS = {
+    meld: "An agent cannot add a device (spawn without --meld). The operator melds from a shell outside an agent session, or from the app's Meld sheet",
+    "meld-remote": "An agent cannot add a device to a remote daemon; the operator runs `brane meld --remote` from a shell outside an agent session",
+    "revoke-device": "An agent cannot sign out a device; the operator does, from a shell outside an agent session or from the app",
+    rotate: "An agent's token is replaced by reviving its narrative, not rotated",
+};
+/** Null when `caller` may go on — a device, or a prompt approved — else the
+ *  refusal to send: an agent's at once, the shell's once the prompt says no. */
+export async function askPresence(gate, act, caller, signal) {
+    const standing = gateStanding(caller.record);
+    if (standing === "pass")
+        return null;
+    if (standing === "refuse") {
+        gate.refuse(act, caller.by, "an agent's token");
+        return { status: 403, body: { error: AGENT_REFUSALS[act], presence: "agent" } };
+    }
+    const outcome = await gate.check(act, caller.by, signal);
+    if (outcome.ok)
+        return null;
+    return {
+        status: outcome.status,
+        body: { error: outcome.error, presence: outcome.reason },
+        ...(outcome.retryAfterMs !== undefined ? { retryAfterMs: outcome.retryAfterMs } : {}),
+    };
+}
+/** `POST /api/tokens`, gated. A body the mint would refuse is refused before
+ *  anyone is asked. */
+export async function gatedMintRoute(deps, caller, rawBody, signal, now = Date.now) {
+    const parsed = parseMintBody(rawBody, now());
+    if ("error" in parsed)
+        return { status: 400, body: parsed };
+    const refused = await askPresence(deps.gate, "meld", caller, signal);
+    if (refused)
+        return refused;
+    return mintDeviceTokenRoute(deps.ring, rawBody, now(), caller.record);
+}
+/** `POST /api/tokens/remote`, gated: a device token for a daemon on another
+ *  machine, and its hash, for `brane meld --remote`. Nothing is stored here,
+ *  so the 200 is the only copy of either. */
+export async function gatedRemoteMintRoute(deps, caller, signal) {
+    const refused = await askPresence(deps.gate, "meld-remote", caller, signal);
+    if (refused)
+        return refused;
+    return { status: 200, body: (deps.mint ?? mintRemoteToken)() };
+}
+/** `POST /api/tokens/:id/revoke`, gated when it signs out a device; stopping
+ *  an agent is not. Refusals the revoke would give come back unasked, and
+ *  the revoke runs its own checks again after the prompt. */
+export async function gatedRevokeRoute(deps, caller, id, also, signal, now = Date.now) {
+    const plan = planRevoke(deps.store, caller.record, id, also);
+    if ("status" in plan)
+        return plan;
+    if (revokeSignsOutDevice(deps.store, plan.ids)) {
+        const refused = await askPresence(deps.gate, "revoke-device", caller, signal);
+        if (refused)
+            return refused;
+    }
+    const revoked = revokeTokenRoute(deps.store, deps.ring, caller.record, id, now(), also);
+    return { status: revoked.status, body: revoked.body, revoked };
+}
+/** `POST /api/token/rotate`, gated. An agent's token is bound to its
+ *  narrative and replaced by reviving it, so agents get 403 unasked, as on
+ *  every gated act. The
+ *  prompt comes before `beginRotation`: a second begin replaces a pending
+ *  rotation, so a refused request must never reach it, or a loop could void
+ *  the operator's own rotation without passing a prompt.
+ *
+ *  A device begins a rotation and completes it by presenting the token this
+ *  returns. This account (the shell, over `daemon.sock`) holds no token to
+ *  swap, so for it the devices are signed out here, in this one request,
+ *  and the answer is `{ signed_out }` with no token in it. */
+export async function gatedRotateRoute(deps, caller, signal) {
+    const refused = await askPresence(deps.gate, "rotate", caller, signal);
+    if (refused)
+        return refused;
+    if (caller.record.kind === "local") {
+        const signedOut = deps.ring.signOutDevices(caller.record);
+        return { status: 200, body: { signed_out: signedOut.devices, replaced: signedOut.replaced }, signedOut };
+    }
+    const rotation = deps.ring.beginRotation(caller.record);
+    return {
+        status: 200,
+        body: { token: rotation.token, expires_at: rotation.expiresAt, replaced: rotation.replaced },
+        rotation,
+    };
+}
+/** `POST /api/presence/cancel?id=`: close the prompt that is up. Only a
+ *  device may: it is how the operator, away from the machine, says "that one
+ *  is not mine". Anything on this machine that could cancel could cancel
+ *  every prompt as it appeared, and with the cooldown keep `brane token
+ *  rotate` from ever completing; the asker withdraws by disconnecting. */
+export function cancelPresenceRoute(gate, record, id) {
+    if (record.kind !== "device") {
+        return { status: 403, body: { error: "Only a signed-in device can cancel a presence prompt" } };
+    }
+    return { status: 200, body: { canceled: gate.cancel(id) } };
+}
+//# sourceMappingURL=gated-routes.js.map

package/dist/daemon/keep-awake.js

@@ -0,0 +1,103 @@
+// KeepAwake — holds an idle-sleep power assertion while the daemon runs.
+//
+// On macOS the daemon spawns a single hidden `caffeinate -i` child whose
+// lifetime mirrors the daemon's. The child holds a
+// `PreventUserIdleSystemSleep` IOKit assertion, equivalent to running
+// `caffeinate -i` in a terminal, but without occupying a tmux session.
+// Display sleep is unaffected — the screen still dims normally.
+//
+// On other platforms this is a no-op. The status surface lets callers tell
+// "we are deliberately not holding an assertion" (unsupported) apart from
+// "we tried and failed" (unavailable).
+import { spawn } from "node:child_process";
+const RESPAWN_BACKOFF_MS = 5000;
+export class KeepAwake {
+    log;
+    child = null;
+    wantRunning = false;
+    respawnTimer = null;
+    lastError;
+    supported;
+    constructor(log = () => { }) {
+        this.log = log;
+        this.supported = process.platform === "darwin";
+    }
+    start() {
+        if (!this.supported)
+            return;
+        if (this.wantRunning)
+            return;
+        this.wantRunning = true;
+        this.spawnChild();
+    }
+    stop() {
+        this.wantRunning = false;
+        if (this.respawnTimer) {
+            clearTimeout(this.respawnTimer);
+            this.respawnTimer = null;
+        }
+        if (this.child && this.child.exitCode === null) {
+            try {
+                this.child.kill("SIGTERM");
+            }
+            catch { }
+        }
+        this.child = null;
+    }
+    getStatus() {
+        if (!this.supported)
+            return { state: "unsupported", pid: null };
+        if (this.child && this.child.exitCode === null && this.child.pid) {
+            return { state: "held", pid: this.child.pid };
+        }
+        const status = { state: this.wantRunning ? "unavailable" : "released", pid: null };
+        if (this.lastError)
+            status.last_error = this.lastError;
+        return status;
+    }
+    spawnChild() {
+        try {
+            const child = spawn("caffeinate", ["-i"], {
+                stdio: "ignore",
+                detached: false,
+            });
+            this.child = child;
+            child.once("error", (err) => {
+                this.lastError = err.message;
+                this.log(`caffeinate failed to spawn: ${err.message}`);
+                this.child = null;
+                this.scheduleRespawn();
+            });
+            child.once("exit", (code, signal) => {
+                if (this.child === child)
+                    this.child = null;
+                if (this.wantRunning) {
+                    this.lastError = `caffeinate exited (code=${code} signal=${signal})`;
+                    this.log(this.lastError);
+                    this.scheduleRespawn();
+                }
+            });
+            this.lastError = undefined;
+            this.log(`keep-awake: caffeinate pid=${child.pid} (PreventUserIdleSystemSleep)`);
+        }
+        catch (err) {
+            this.lastError = err.message;
+            this.log(`caffeinate spawn threw: ${this.lastError}`);
+            this.scheduleRespawn();
+        }
+    }
+    scheduleRespawn() {
+        if (!this.wantRunning)
+            return;
+        if (this.respawnTimer)
+            return;
+        this.respawnTimer = setTimeout(() => {
+            this.respawnTimer = null;
+            if (this.wantRunning)
+                this.spawnChild();
+        }, RESPAWN_BACKOFF_MS);
+        if (typeof this.respawnTimer.unref === "function")
+            this.respawnTimer.unref();
+    }
+}
+//# sourceMappingURL=keep-awake.js.map

package/dist/daemon/local-socket.js

@@ -0,0 +1,145 @@
+/**
+ * The daemon's Unix-domain socket, `daemon.sock` beside the database.
+ *
+ * It is how a process on this machine reaches the daemon with the kernel
+ * vouching for who it is: connecting means resolving the path, which takes
+ * search permission on `~/.brane`, and that directory is 0700 — so only this
+ * Unix account (and root) gets in. Loopback TCP cannot say as much: any
+ * account on the machine can dial 127.0.0.1. See SECURITY.md, "Who the
+ * operator is".
+ *
+ * A connection over the socket gains loopback standing (`isLoopbackRequest`),
+ * and a request on it that presents no token acts as this account — the
+ * live `local` row — for as long as `accountDirTrust` holds.
+ */
+import { connect } from "node:net";
+import { chmodSync, lstatSync, statSync, unlinkSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { UNIX_SOCKET_SIGHTING } from "../db/tokens.js";
+/** `daemon.sock` beside a database. */
+export function getSocketPath(db) {
+    return join(dirname(db.name), "daemon.sock");
+}
+/** Whether the directory holding the socket still makes "reached the
+ *  socket" mean "is this Unix account": owned by the daemon's own uid, with
+ *  no group or other permission bits. Both chmods that set this up swallow
+ *  their errors, and anyone may loosen it later, so it is checked when it is
+ *  relied on, not once at startup. Follows a symlinked directory, as
+ *  resolving the socket's path does. */
+export function accountDirTrust(dir) {
+    const uid = process.getuid?.();
+    if (uid === undefined)
+        return { ok: false, reason: "this platform has no Unix uids" };
+    let st;
+    try {
+        st = statSync(dir);
+    }
+    catch (err) {
+        return { ok: false, reason: `${dir}: ${err.code ?? String(err)}` };
+    }
+    if (st.uid !== uid)
+        return { ok: false, reason: `${dir} is owned by uid ${st.uid}, not this daemon's ${uid}` };
+    if ((st.mode & 0o077) !== 0) {
+        return { ok: false, reason: `${dir} is mode ${(st.mode & 0o777).toString(8)}; other accounts could reach the socket (want 700)` };
+    }
+    return { ok: true };
+}
+/** The longest path `bind(2)` takes for a Unix socket: `sun_path` is 104
+ *  bytes on macOS (108 on Linux), terminator included. */
+export const MAX_SOCKET_PATH = 103;
+/** Connections accepted on the Unix socket. `isLoopbackRequest` consults it,
+ *  since such a socket has no remote address to judge by. */
+const unixConnections = new WeakSet();
+export function markUnixConnection(socket) {
+    unixConnections.add(socket);
+}
+export function isUnixConnection(socket) {
+    return unixConnections.has(socket);
+}
+/** Where a connection came from, for token sightings and log lines:
+ *  `daemon.sock` for the Unix socket, which has no address of its own, else
+ *  the remote address, or null when even that is gone. */
+export function connectionLabel(socket) {
+    return isUnixConnection(socket) ? UNIX_SOCKET_SIGHTING : (socket.remoteAddress ?? null);
+}
+/**
+ * Make `path` free to listen on. A clean shutdown leaves nothing behind
+ * (closing the server unlinks it); a crash leaves the socket file, which
+ * `listen()` would refuse. Only a socket whose connect is refused
+ * (ECONNREFUSED) is removed: one that accepts a connection belongs to a live
+ * daemon, and any other error is no proof either way, so both are left alone.
+ * Callers hold the daemon claim, so that would be another brane dir's
+ * daemon, or not a daemon at all.
+ *
+ * Anything at `path` that is not a socket is never touched.
+ *
+ * Resolves `true` when `path` is free, `false` when it is not and stays so.
+ */
+export async function clearStaleSocket(path) {
+    let isSocket;
+    try {
+        isSocket = lstatSync(path).isSocket();
+    }
+    catch (err) {
+        return err.code === "ENOENT"; // nothing there
+    }
+    if (!isSocket)
+        return false;
+    // Only a refusal proves nothing is listening. Any other failure — no
+    // permission, no file descriptors, a live listener's full backlog — proves
+    // nothing, and the path is left alone.
+    const refused = await new Promise((resolve) => {
+        const probe = connect(path);
+        probe.once("connect", () => {
+            probe.destroy();
+            resolve(false);
+        });
+        probe.once("error", (err) => resolve(err.code === "ECONNREFUSED"));
+    });
+    if (!refused)
+        return false;
+    unlinkSync(path);
+    return true;
+}
+/**
+ * Start `server` on the socket beside `db` and advertise it as
+ * `meta.daemon_socket`. Never throws: a path too long for `bind(2)`, a path
+ * that is in use or not a socket, or a failed `listen()` is logged and
+ * answered `false`. Agents and devices still reach the daemon over TCP with
+ * their tokens; this account's shell, which holds none, cannot. Marks each accepted
+ * connection, so `isLoopbackRequest` and `connectionLabel` know it.
+ */
+export async function listenOnLocalSocket(server, db, log = (line) => console.warn(line)) {
+    const path = getSocketPath(db);
+    if (Buffer.byteLength(path) > MAX_SOCKET_PATH) {
+        log(`[socket] ${path} is too long for a Unix socket (${Buffer.byteLength(path)} bytes, limit ${MAX_SOCKET_PATH})`);
+        return false;
+    }
+    server.on("connection", (socket) => markUnixConnection(socket));
+    try {
+        if (!(await clearStaleSocket(path))) {
+            log(`[socket] ${path} is in use or not a socket; left alone`);
+            return false;
+        }
+        await new Promise((resolve, reject) => {
+            server.once("error", reject);
+            server.listen(path, () => {
+                server.off("error", reject);
+                resolve();
+            });
+        });
+    }
+    catch (err) {
+        log(`[socket] could not listen on ${path}: ${err.message}`);
+        return false;
+    }
+    // The directory is what keeps other accounts out; on Linux the socket's
+    // own mode is checked too.
+    try {
+        chmodSync(path, 0o600);
+    }
+    catch { }
+    db.prepare("INSERT OR REPLACE INTO meta (key, value) VALUES ('daemon_socket', ?)").run(path);
+    return true;
+}
+//# sourceMappingURL=local-socket.js.map

package/dist/daemon/presence-gate.js

@@ -0,0 +1,206 @@
+/**
+ * The presence gate: the few acts a process on this machine may not do on
+ * its own say-so wait here for the operator to pass the OS's own prompt
+ * (`src/presence.ts`). SECURITY.md, "Who the operator is": a process running
+ * as this account is not the operator, and acts that reach off this machine
+ * or cut the operator off are gated by the presence check.
+ *
+ * Gated acts, for this machine's shell (no token, over `daemon.sock`):
+ *
+ * - `meld`: minting a device token (`POST /api/tokens`), which extends reach
+ *   off this machine;
+ * - `meld-remote`: minting a device token for a daemon on another machine
+ *   (`POST /api/tokens/remote`, `brane meld --remote`). This daemon stores
+ *   nothing and could not stop a process that made its own token; what the
+ *   gate holds is the sanctioned path, which then asks what `brane meld`
+ *   asks;
+ * - `revoke-device`: revoking a device token, which cuts the operator off a
+ *   device — an agent loop could otherwise sign out their phone;
+ * - `rotate`: signing out every other device (`POST /api/token/rotate`).
+ *
+ * A device token is the operator's delegate, minted by an operator act, and
+ * is never prompted: the app's Meld sheet, Revoke and "Sign out other
+ * devices" work as they always have. An agent's token is refused all three,
+ * unasked (`gateStanding`). Who is asking is read from the token's kind,
+ * never from the address — a device on this machine's browser is still a
+ * device, and an agent is an agent over any transport.
+ *
+ * Less obvious than it looks:
+ *
+ * - **The prompt's words are fixed per act.** Nothing from a request reaches
+ *   them, not even a device's label or user agent, which whoever minted it
+ *   chose: an agent that could write the prompt could make it read like the
+ *   one the operator expects ("Unlock 1Password").
+ * - **One prompt at a time, and no queue.** A second gated request while one
+ *   is up is refused at once (409). After a prompt that was not approved,
+ *   further requests are refused for `cooldownMs` (429), so a loop cannot
+ *   keep a dialog on screen until it is approved out of habit. A withdrawn
+ *   prompt counts: give up and ask again is exactly that loop.
+ * - **The asker can withdraw.** The route aborts the prompt when its client
+ *   goes away (Ctrl-C on `brane meld`), so no dialog outlives its request.
+ * - **A device can cancel; nothing can approve.** A remote approve would be
+ *   a device minting a token, which the Meld sheet already does in the open.
+ *   Only a device may cancel: anything on this machine that could cancel
+ *   could cancel every prompt as it appeared, and with the cooldown keep
+ *   `brane token rotate` from ever completing. The asker withdraws by
+ *   disconnecting instead.
+ */
+/** What the OS prompt says. macOS shows it as "osascript is trying to <it>",
+ *  hence the lowercase verb phrase. */
+export const PRESENCE_PROMPTS = {
+    meld: "add a device to brane",
+    "meld-remote": "add a device to brane on another machine",
+    "revoke-device": "sign out a device from brane",
+    rotate: "sign out every other device from brane",
+};
+/** How a caller holding `record` stands before a gated act: a device goes
+ *  on, an agent is refused unasked, and anything else (this machine's shell)
+ *  is asked. An agent that follows the rules therefore never puts a dialog
+ *  in front of the operator — one that read like the operator's own
+ *  `brane meld` would be approved out of habit. */
+export function gateStanding(record) {
+    return record.kind === "device" ? "pass" : record.kind === "agent" ? "refuse" : "ask";
+}
+/** Whether a revoke of `id` (plus `also`) signs out a device, which is the
+ *  gated part of revoking; stopping an agent is not. Unknown ids are not
+ *  gated, so a request the route will refuse (404) never raises a prompt. */
+export function revokeSignsOutDevice(store, ids) {
+    return ids.some((id) => store.get(id)?.kind === "device");
+}
+export const PRESENCE_TIMEOUT_MS = 45_000;
+export const PRESENCE_COOLDOWN_MS = 15_000;
+export class PresenceGate {
+    opts;
+    pending = null;
+    cooldownUntil = 0;
+    timeoutMs;
+    cooldownMs;
+    now;
+    newId;
+    constructor(opts) {
+        this.opts = opts;
+        this.timeoutMs = opts.timeoutMs ?? PRESENCE_TIMEOUT_MS;
+        this.cooldownMs = opts.cooldownMs ?? PRESENCE_COOLDOWN_MS;
+        this.now = opts.now ?? Date.now;
+        let n = 0;
+        this.newId = opts.newId ?? (() => `presence-${++n}`);
+    }
+    /** The prompt that is up, if any, without its handle. */
+    current() {
+        if (!this.pending)
+            return null;
+        const { abort: _a, remoteCancel: _r, ...pending } = this.pending;
+        return pending;
+    }
+    /** Ask the operator to approve `act` for `by`. Resolves once they answer,
+     *  the prompt times out, it is canceled, or `signal` (the request's own
+     *  lifetime) aborts. Never throws. */
+    async check(act, by, signal) {
+        const prompt = PRESENCE_PROMPTS[act];
+        const now = this.now();
+        if (this.pending) {
+            const up = this.pending;
+            this.log(act, by, "refused: another prompt is up");
+            // Name the prompt that is up and who raised it: its dialog may read
+            // exactly like the one this caller expected, and approving it would
+            // approve someone else's act.
+            return {
+                ok: false,
+                status: 409,
+                reason: "busy",
+                error: `Another presence prompt is up ("${up.prompt}", asked by ${up.by}). ` +
+                    "If you did not start it, decline it at the machine or cancel it from a signed-in device, then try again",
+            };
+        }
+        if (now < this.cooldownUntil) {
+            const retryAfterMs = this.cooldownUntil - now;
+            this.log(act, by, "refused: cooling down after a prompt that was not approved");
+            return {
+                ok: false,
+                status: 429,
+                reason: "cooldown",
+                retryAfterMs,
+                error: `A presence prompt was just declined, withdrawn or left unanswered; try again in ${Math.ceil(retryAfterMs / 1000)} s`,
+            };
+        }
+        if (signal?.aborted)
+            return { ok: false, status: 403, reason: "aborted", error: "The request was withdrawn" };
+        const abort = new AbortController();
+        const onAbort = () => abort.abort();
+        signal?.addEventListener("abort", onAbort, { once: true });
+        const pending = {
+            id: this.newId(),
+            act,
+            prompt,
+            by,
+            startedAt: now,
+            expiresAt: now + this.timeoutMs,
+            abort,
+            remoteCancel: false,
+        };
+        this.pending = pending;
+        this.opts.onChange?.(this.current());
+        let result;
+        try {
+            result = await this.opts.confirm(prompt, { timeoutMs: this.timeoutMs, signal: abort.signal });
+        }
+        catch (err) {
+            result = { ok: false, method: null, reason: "failed", detail: err instanceof Error ? err.message : String(err) };
+        }
+        finally {
+            signal?.removeEventListener("abort", onAbort);
+            this.pending = null;
+            this.opts.onChange?.(null);
+        }
+        if (result.ok) {
+            this.log(act, by, `approved (${result.method})`);
+            return { ok: true };
+        }
+        const reason = pending.remoteCancel ? "remote-cancel" : result.reason;
+        // After every prompt that was shown and not approved — a withdrawn one
+        // too, or a loop could give up and ask again with no pause between
+        // dialogs. Only `unavailable` showed nothing.
+        if (reason !== "unavailable")
+            this.cooldownUntil = this.now() + this.cooldownMs;
+        this.log(act, by, `${reason}${result.detail ? `: ${result.detail}` : ""}`);
+        return { ok: false, status: 403, reason, error: refusalMessage(reason, result.detail) };
+    }
+    /** Record an attempt refused without a prompt — an agent's token asking
+     *  for an operator's act — so it leaves the same trace as one that was
+     *  asked. An agent trying to add a device or sign out the operator's phone
+     *  is the attempt most worth seeing. */
+    refuse(act, by, why) {
+        this.log(act, by, `refused: ${why}`);
+    }
+    /** Close the prompt that is up. With `id`, only that prompt — so a stale
+     *  Cancel tap cannot close a newer one. Returns whether one was closed.
+     *  Who may call it is the route's to decide (`cancelPresenceRoute`). */
+    cancel(id) {
+        const p = this.pending;
+        if (!p || (id !== undefined && id !== p.id))
+            return false;
+        p.remoteCancel = true;
+        p.abort.abort();
+        return true;
+    }
+    log(act, by, outcome) {
+        this.opts.log?.(`[presence] ${act} for ${by}: ${outcome}`);
+    }
+}
+function refusalMessage(reason, detail) {
+    switch (reason) {
+        case "canceled":
+            return "The presence prompt was declined at this machine";
+        case "remote-cancel":
+            return "The presence prompt was canceled from a signed-in device";
+        case "timeout":
+            return "Nobody answered the presence prompt in time";
+        case "aborted":
+            return "The request was withdrawn";
+        case "unavailable":
+            return `This machine cannot show a presence prompt${detail ? ` (${detail})` : ""}; this needs the operator at a machine that can, or a signed-in device`;
+        default:
+            return `The presence check failed${detail ? `: ${detail}` : ""}`;
+    }
+}
+//# sourceMappingURL=presence-gate.js.map