harnery 0.8.0 → 0.10.0

package/dist/core/presence/index.js

@@ -0,0 +1,224 @@
+/**
+ * Cross-machine presence (ADR 0016), phase 1: the git-refs transport.
+ *
+ * publishPresence(): serialize this machine's live sessions into a presence
+ * blob and force-push it to `refs/harnery/presence/<machine>` on origin —
+ * change-batched (only when the blob materially changed) with a keepalive
+ * (~5 min) so peers can distinguish "no change" from "machine gone".
+ *
+ * fetchPresence(): throttled fetch of every peer machine's presence ref.
+ *
+ * readRemoteMachines(): parse the locally-known refs into render-ready rows
+ * (self machine excluded, stale blobs dropped).
+ *
+ * All entry points are fail-silent and gated on `presenceEnabled()` — presence
+ * must never break a hook, a render, or a repo with no origin.
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, utimesSync, writeFileSync, } from "node:fs";
+import { join } from "node:path";
+import { coordEnv } from "../../lib/env.js";
+import { resolveMachineLabel } from "../../lib/machine.js";
+import { presenceEnabled } from "../config.js";
+import { buildPresenceBlob } from "./blob.js";
+import { fetchPresenceRefs, hasOrigin, pushPresenceRef, readPresenceRefs, sanitizeRefComponent, writePresenceCommit, } from "./git.js";
+export { buildPresenceBlob } from "./blob.js";
+export { PRESENCE_REF_PREFIX, parseForEachRefOutput, sanitizeRefComponent } from "./git.js";
+export { ensureRelayDaemon, relayDaemonStatus, runRelayDaemon } from "./relay-client.js";
+/** Re-push at least this often while sessions are live, so peers can treat a
+ * blob older than ~3x this as "machine offline" rather than "no change". */
+const KEEPALIVE_SECS = 300;
+/** Never push more often than this, however chatty the triggers. */
+const MIN_PUSH_INTERVAL_SECS = 15;
+/** Default fetch throttle (hook cadence fires far more often than this). */
+const FETCH_INTERVAL_SECS = 60;
+/** A blob whose published_at is older than this is rendered as gone. */
+const REMOTE_STALE_SECS = 900;
+function presenceDir(coordRoot) {
+    return join(coordRoot, ".harnery", "presence");
+}
+function statePath(coordRoot) {
+    return join(presenceDir(coordRoot), "publish-state.json");
+}
+function fetchStampPath(coordRoot) {
+    return join(presenceDir(coordRoot), "fetch-stamp");
+}
+function readState(coordRoot) {
+    try {
+        return JSON.parse(readFileSync(statePath(coordRoot), "utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+function writeState(coordRoot, state) {
+    try {
+        const p = statePath(coordRoot);
+        mkdirSync(presenceDir(coordRoot), { recursive: true });
+        const tmp = `${p}.tmp.${process.pid}`;
+        writeFileSync(tmp, JSON.stringify(state), "utf8");
+        renameSync(tmp, p);
+    }
+    catch {
+        /* best-effort */
+    }
+}
+/**
+ * Publish this machine's presence blob to origin if it changed (or the
+ * keepalive elapsed). `sync: true` pushes in-process and reports errors (CLI
+ * path); default spawns the push detached (hook path).
+ */
+export function publishPresence(coordRoot, opts = {}) {
+    try {
+        if (!presenceEnabled(coordRoot))
+            return { status: "skipped", reason: "disabled" };
+        if (!hasOrigin(coordRoot))
+            return { status: "skipped", reason: "no origin remote" };
+        const { blob, basisHash, json } = buildPresenceBlob(coordRoot);
+        const state = readState(coordRoot);
+        const pushedAtMs = Date.parse(state.pushed_at ?? "");
+        const sincePush = Number.isFinite(pushedAtMs)
+            ? (Date.now() - pushedAtMs) / 1000
+            : Number.POSITIVE_INFINITY;
+        if (!opts.force) {
+            // Nothing live and the last publish already said so → stay quiet.
+            if (blob.agents.length === 0 && (state.agents ?? 0) === 0) {
+                return { status: "skipped", reason: "no live sessions" };
+            }
+            const unchanged = state.basis_hash === basisHash;
+            if (unchanged && sincePush < KEEPALIVE_SECS) {
+                return { status: "skipped", reason: "unchanged (within keepalive)" };
+            }
+            if (!unchanged && sincePush < MIN_PUSH_INTERVAL_SECS) {
+                return { status: "skipped", reason: "min push interval" };
+            }
+        }
+        const sha = writePresenceCommit(coordRoot, json);
+        if (!sha)
+            return { status: "error", error: "commit-tree failed" };
+        const push = pushPresenceRef(coordRoot, blob.machine, sha, { sync: opts.sync });
+        if (!push.ok)
+            return { status: "error", error: push.error ?? "push failed" };
+        // Optimistic on the detached path: a failed background push self-heals at
+        // the next keepalive re-push.
+        writeState(coordRoot, {
+            basis_hash: basisHash,
+            pushed_at: new Date().toISOString(),
+            agents: blob.agents.length,
+        });
+        return { status: "published", machine: blob.machine, agents: blob.agents.length, sha };
+    }
+    catch (e) {
+        return { status: "error", error: e instanceof Error ? e.message : String(e) };
+    }
+}
+/** Throttled fetch of peer presence refs from origin. */
+export function fetchPresence(coordRoot, opts = {}) {
+    try {
+        if (!presenceEnabled(coordRoot))
+            return { status: "skipped", reason: "disabled" };
+        if (!hasOrigin(coordRoot))
+            return { status: "skipped", reason: "no origin remote" };
+        const stamp = fetchStampPath(coordRoot);
+        if (!opts.force) {
+            const interval = Number.parseInt(coordEnv("PRESENCE_FETCH_INTERVAL") ?? String(FETCH_INTERVAL_SECS), 10);
+            try {
+                const age = (Date.now() - statSync(stamp).mtimeMs) / 1000;
+                if (age < interval)
+                    return { status: "skipped", reason: "within fetch interval" };
+            }
+            catch {
+                /* no stamp yet → fetch */
+            }
+        }
+        // Touch the stamp BEFORE spawning so concurrent hooks don't stampede.
+        try {
+            mkdirSync(presenceDir(coordRoot), { recursive: true });
+            if (existsSync(stamp)) {
+                const now = new Date();
+                utimesSync(stamp, now, now);
+            }
+            else {
+                writeFileSync(stamp, "", "utf8");
+            }
+        }
+        catch {
+            /* best-effort */
+        }
+        const r = fetchPresenceRefs(coordRoot, { sync: opts.sync });
+        if (!r.ok)
+            return { status: "error", error: r.error ?? "fetch failed" };
+        return { status: "fetched" };
+    }
+    catch (e) {
+        return { status: "error", error: e instanceof Error ? e.message : String(e) };
+    }
+}
+/**
+ * Render-ready view of every OTHER machine's presence, merged from BOTH
+ * transports: the locally-fetched git refs (the floor) and the relay
+ * daemon's cache files at `.harnery/presence/remote/` (the live upgrade).
+ * Freshest source per machine wins. Self machine excluded; blobs older than
+ * the stale window or with zero agents dropped.
+ */
+export function readRemoteMachines(coordRoot, opts = {}) {
+    try {
+        if (!presenceEnabled(coordRoot))
+            return [];
+        const selfMachine = sanitizeRefComponent(resolveMachineLabel());
+        // Collect candidate blobs from both transports, freshest per machine.
+        const byMachine = new Map();
+        const consider = (machine, blob) => {
+            if (blob?.v !== 1 || !Array.isArray(blob.agents))
+                return;
+            const publishedMs = Date.parse(blob.published_at ?? "");
+            if (!Number.isFinite(publishedMs))
+                return;
+            const prev = byMachine.get(machine);
+            if (prev && Date.parse(prev.published_at) >= publishedMs)
+                return;
+            byMachine.set(machine, blob);
+        };
+        for (const { machine, message } of readPresenceRefs(coordRoot)) {
+            try {
+                consider(machine, JSON.parse(message));
+            }
+            catch {
+                /* skip malformed */
+            }
+        }
+        const relayDir = join(coordRoot, ".harnery", "presence", "remote");
+        if (existsSync(relayDir)) {
+            for (const f of readdirSync(relayDir)) {
+                if (!f.endsWith(".json"))
+                    continue;
+                try {
+                    consider(f.replace(/\.json$/, ""), JSON.parse(readFileSync(join(relayDir, f), "utf8")));
+                }
+                catch {
+                    /* skip malformed */
+                }
+            }
+        }
+        const out = [];
+        for (const [machine, blob] of byMachine) {
+            if (!opts.includeSelf && machine === selfMachine)
+                continue;
+            const ageSecs = Math.max(0, Math.floor((Date.now() - Date.parse(blob.published_at)) / 1000));
+            if (!opts.includeStale && ageSecs > REMOTE_STALE_SECS)
+                continue;
+            if (blob.agents.length === 0)
+                continue;
+            out.push({
+                machine,
+                published_at: blob.published_at,
+                age_secs: ageSecs,
+                agents: blob.agents,
+            });
+        }
+        out.sort((a, b) => a.machine.localeCompare(b.machine));
+        return out;
+    }
+    catch {
+        return [];
+    }
+}

package/dist/core/presence/relay-client.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Relay client transport for cross-machine presence (ADR 0016, phase 2c).
+ *
+ * The hooks are short-lived processes, so a live WebSocket needs a home: a
+ * small per-repo-per-machine DAEMON that the hooks lazy-start
+ * (`ensureRelayDaemon`) and that exits itself when the machine goes idle.
+ * The daemon:
+ *
+ *   - derives the room credentials from the repo identity (root-commit SHA +
+ *     origin URL + optional committed `.harnery/presence-salt`)
+ *   - holds the socket open with auto-reconnect + jittered backoff
+ *   - watches `.harnery/active/` and publishes the encrypted presence blob on
+ *     change (debounced), plus a 60s keepalive so peers' staleness math works
+ *   - decrypts received peer frames and writes them to
+ *     `.harnery/presence/remote/<machine>.json`, where `readRemoteMachines`
+ *     merges them with the git-refs floor (freshest source per machine wins)
+ *   - exits after ~5 minutes with no live local sessions (hooks restart it
+ *     when sessions return), and exits if its pid file is superseded
+ *
+ * Everything fails silent; the git-refs transport is always the floor.
+ * Requires a global WebSocket (Bun, Node >= 21, Workers) — on older Nodes the
+ * daemon refuses to start and presence stays on git-refs.
+ */
+/**
+ * Lazy-start the relay daemon for this repo if a relay is configured and no
+ * live daemon already owns the pid file. Called from the hook path — must
+ * return fast and never throw.
+ */
+export declare function ensureRelayDaemon(coordRoot: string): void;
+/** Foreground daemon loop (spawned detached by ensureRelayDaemon). */
+export declare function runRelayDaemon(coordRoot: string): Promise<number>;
+/** Daemon status for `presence peers`/doctor surfaces. */
+export declare function relayDaemonStatus(coordRoot: string): {
+    running: boolean;
+    pid?: number;
+    url?: string;
+    started_at?: string;
+};
+//# sourceMappingURL=relay-client.d.ts.map

package/dist/core/presence/relay-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relay-client.d.ts","sourceRoot":"","sources":["../../../src/core/presence/relay-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAwFH;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAwBzD;AAED,sEAAsE;AACtE,wBAAsB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAqKvE;AAED,0DAA0D;AAC1D,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG;IACpD,OAAO,EAAE,OAAO,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAMA"}

package/dist/core/presence/relay-client.js

@@ -0,0 +1,295 @@
+/**
+ * Relay client transport for cross-machine presence (ADR 0016, phase 2c).
+ *
+ * The hooks are short-lived processes, so a live WebSocket needs a home: a
+ * small per-repo-per-machine DAEMON that the hooks lazy-start
+ * (`ensureRelayDaemon`) and that exits itself when the machine goes idle.
+ * The daemon:
+ *
+ *   - derives the room credentials from the repo identity (root-commit SHA +
+ *     origin URL + optional committed `.harnery/presence-salt`)
+ *   - holds the socket open with auto-reconnect + jittered backoff
+ *   - watches `.harnery/active/` and publishes the encrypted presence blob on
+ *     change (debounced), plus a 60s keepalive so peers' staleness math works
+ *   - decrypts received peer frames and writes them to
+ *     `.harnery/presence/remote/<machine>.json`, where `readRemoteMachines`
+ *     merges them with the git-refs floor (freshest source per machine wins)
+ *   - exits after ~5 minutes with no live local sessions (hooks restart it
+ *     when sessions return), and exits if its pid file is superseded
+ *
+ * Everything fails silent; the git-refs transport is always the floor.
+ * Requires a global WebSocket (Bun, Node >= 21, Workers) — on older Nodes the
+ * daemon refuses to start and presence stays on git-refs.
+ */
+import { spawn } from "node:child_process";
+import { existsSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, watch, writeFileSync, } from "node:fs";
+import { join } from "node:path";
+import { resolveMachineLabel } from "../../lib/machine.js";
+import { presenceRelayUrl } from "../config.js";
+import { buildPresenceBlob } from "./blob.js";
+import { originUrl, rootCommitSha, sanitizeRefComponent } from "./git.js";
+import { computeSenderId, decryptPayload, deriveRoomCredentials, encryptPayload, parseRelayFrame, } from "./relay-protocol.js";
+const KEEPALIVE_MS = 60_000;
+const WATCH_DEBOUNCE_MS = 500;
+const IDLE_EXIT_MS = 5 * 60_000;
+const BACKOFF_MIN_MS = 1_000;
+const BACKOFF_MAX_MS = 60_000;
+function presenceDir(coordRoot) {
+    return join(coordRoot, ".harnery", "presence");
+}
+function remoteCacheDir(coordRoot) {
+    return join(presenceDir(coordRoot), "remote");
+}
+function pidFilePath(coordRoot) {
+    return join(presenceDir(coordRoot), "relay-daemon.json");
+}
+function logFilePath(coordRoot) {
+    return join(presenceDir(coordRoot), "relay-daemon.log");
+}
+function readPidRecord(coordRoot) {
+    try {
+        return JSON.parse(readFileSync(pidFilePath(coordRoot), "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+function pidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** The committed rotatable room salt, when the repo minted one. */
+function readRoomSalt(coordRoot) {
+    try {
+        const s = readFileSync(join(coordRoot, ".harnery", "presence-salt"), "utf8").trim();
+        return s || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function atomicWriteJson(path, value) {
+    mkdirSync(join(path, ".."), { recursive: true });
+    const tmp = `${path}.tmp.${process.pid}`;
+    writeFileSync(tmp, JSON.stringify(value), "utf8");
+    renameSync(tmp, path);
+}
+/**
+ * Lazy-start the relay daemon for this repo if a relay is configured and no
+ * live daemon already owns the pid file. Called from the hook path — must
+ * return fast and never throw.
+ */
+export function ensureRelayDaemon(coordRoot) {
+    try {
+        const url = presenceRelayUrl(coordRoot);
+        if (!url)
+            return;
+        const rec = readPidRecord(coordRoot);
+        if (rec && rec.url === url && pidAlive(rec.pid))
+            return;
+        // Resolve the harn bin at the package root (works from src/ under Bun and
+        // dist/ under Node — both sit two levels below the root).
+        const harnBin = new URL("../../../bin/harn", import.meta.url).pathname;
+        if (!existsSync(harnBin))
+            return;
+        mkdirSync(presenceDir(coordRoot), { recursive: true });
+        const log = openSync(logFilePath(coordRoot), "a");
+        const child = spawn(harnBin, ["presence", "relay-daemon"], {
+            cwd: coordRoot,
+            detached: true,
+            stdio: ["ignore", log, log],
+            env: { ...process.env, HARNERY_OUTPUT_SESSION_TEE: "0" },
+        });
+        child.unref();
+    }
+    catch {
+        /* best-effort */
+    }
+}
+/** Foreground daemon loop (spawned detached by ensureRelayDaemon). */
+export async function runRelayDaemon(coordRoot) {
+    const url = presenceRelayUrl(coordRoot);
+    if (!url) {
+        console.error("relay-daemon: no relay configured (presence.relay)");
+        return 2;
+    }
+    if (typeof WebSocket === "undefined") {
+        console.error("relay-daemon: no global WebSocket in this runtime (need Bun or Node >= 21)");
+        return 2;
+    }
+    const sha = rootCommitSha(coordRoot);
+    const origin = originUrl(coordRoot);
+    if (!sha || !origin) {
+        console.error("relay-daemon: repo has no commits or no origin remote");
+        return 2;
+    }
+    // Take (or take over) the pid file. A superseded daemon notices and exits.
+    const myRecord = {
+        pid: process.pid,
+        url,
+        started_at: new Date().toISOString(),
+    };
+    atomicWriteJson(pidFilePath(coordRoot), myRecord);
+    const creds = await deriveRoomCredentials({
+        rootCommitSha: sha,
+        originUrl: origin,
+        salt: readRoomSalt(coordRoot),
+    });
+    const machine = sanitizeRefComponent(resolveMachineLabel());
+    const senderId = await computeSenderId(creds, machine);
+    const wsUrl = `${url.replace(/\/+$/, "")}/v1/room/${creds.roomId}`;
+    let ws = null;
+    let backoff = BACKOFF_MIN_MS;
+    let lastBasisHash = "";
+    let lastSentAt = 0;
+    let idleSince = null;
+    let shuttingDown = false;
+    const log = (msg) => {
+        console.log(`[${new Date().toISOString()}] ${msg}`);
+    };
+    const publishNow = async (force = false) => {
+        if (!ws || ws.readyState !== WebSocket.OPEN)
+            return;
+        try {
+            const { blob, basisHash, json } = buildPresenceBlob(coordRoot);
+            const keepaliveDue = Date.now() - lastSentAt >= KEEPALIVE_MS;
+            if (!force && basisHash === lastBasisHash && !keepaliveDue)
+                return;
+            const enc = await encryptPayload(creds, json);
+            ws.send(JSON.stringify({ t: "pub", sender: senderId, ...enc }));
+            lastBasisHash = basisHash;
+            lastSentAt = Date.now();
+            idleSince = blob.agents.length === 0 ? (idleSince ?? Date.now()) : null;
+        }
+        catch {
+            /* next trigger retries */
+        }
+    };
+    const handleFrame = async (raw) => {
+        const frame = parseRelayFrame(raw);
+        if (frame?.t !== "pub")
+            return;
+        if (frame.sender === senderId)
+            return; // our own warm-join echo
+        const pt = await decryptPayload(creds, frame);
+        if (!pt)
+            return;
+        let blob;
+        try {
+            blob = JSON.parse(pt);
+        }
+        catch {
+            return;
+        }
+        if (blob?.v !== 1 || typeof blob.machine !== "string")
+            return;
+        const m = sanitizeRefComponent(blob.machine);
+        if (m === machine)
+            return;
+        try {
+            atomicWriteJson(join(remoteCacheDir(coordRoot), `${m}.json`), blob);
+        }
+        catch {
+            /* best-effort */
+        }
+    };
+    const connect = () => {
+        if (shuttingDown)
+            return;
+        try {
+            const sock = new WebSocket(wsUrl);
+            ws = sock;
+            sock.onopen = () => {
+                backoff = BACKOFF_MIN_MS;
+                log(`connected room=${creds.roomId.slice(0, 8)}… as ${machine}`);
+                void publishNow(true);
+            };
+            sock.onmessage = (ev) => {
+                void handleFrame(String(ev.data));
+            };
+            const scheduleReconnect = () => {
+                if (shuttingDown)
+                    return;
+                const jitter = Math.random() * backoff * 0.3;
+                const delay = Math.min(BACKOFF_MAX_MS, backoff) + jitter;
+                backoff = Math.min(BACKOFF_MAX_MS, backoff * 2);
+                setTimeout(connect, delay);
+            };
+            sock.onclose = scheduleReconnect;
+            sock.onerror = () => {
+                try {
+                    sock.close();
+                }
+                catch {
+                    /* ignore */
+                }
+            };
+        }
+        catch {
+            setTimeout(connect, backoff);
+            backoff = Math.min(BACKOFF_MAX_MS, backoff * 2);
+        }
+    };
+    connect();
+    // Publish on heartbeat change (debounced).
+    let debounce = null;
+    const activeDir = join(coordRoot, ".harnery", "active");
+    mkdirSync(activeDir, { recursive: true });
+    try {
+        watch(activeDir, () => {
+            if (debounce)
+                clearTimeout(debounce);
+            debounce = setTimeout(() => void publishNow(), WATCH_DEBOUNCE_MS);
+        });
+    }
+    catch {
+        /* keepalive interval still covers publication */
+    }
+    // Keepalive + lifecycle checks.
+    const interval = setInterval(() => {
+        void publishNow();
+        // Superseded by a newer daemon → exit quietly.
+        const rec = readPidRecord(coordRoot);
+        if (!rec || rec.pid !== process.pid) {
+            log("pid file superseded; exiting");
+            shuttingDown = true;
+            clearInterval(interval);
+            try {
+                ws?.close();
+            }
+            catch {
+                /* ignore */
+            }
+            process.exit(0);
+        }
+        // Idle machine (no live sessions for a while) → exit; hooks restart us.
+        if (idleSince && Date.now() - idleSince > IDLE_EXIT_MS) {
+            log("no live sessions; idle exit");
+            shuttingDown = true;
+            clearInterval(interval);
+            try {
+                rmSync(pidFilePath(coordRoot), { force: true });
+                ws?.close();
+            }
+            catch {
+                /* ignore */
+            }
+            process.exit(0);
+        }
+    }, KEEPALIVE_MS);
+    // Never resolves in normal operation; exits happen above.
+    return await new Promise(() => { });
+}
+/** Daemon status for `presence peers`/doctor surfaces. */
+export function relayDaemonStatus(coordRoot) {
+    const rec = readPidRecord(coordRoot);
+    if (rec && pidAlive(rec.pid)) {
+        return { running: true, pid: rec.pid, url: rec.url, started_at: rec.started_at };
+    }
+    return { running: false };
+}

package/dist/core/presence/relay-protocol.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Relay protocol for cross-machine presence (ADR 0016, phase 2): the shared,
+ * host-agnostic logic both relay hosts (the Cloudflare Durable Objects worker
+ * and `harn relay serve`) and the client transport build on.
+ *
+ * Capability-based rooms: the room id and the E2E symmetric key are BOTH
+ * derived client-side via HKDF-SHA256 from (repo root-commit SHA, normalized
+ * origin URL, a rotatable salt). Anyone who can read the repo can derive them;
+ * nobody else can — including the relay operator, who sees only an opaque
+ * room id, opaque sender ids, and AES-GCM ciphertext. Rotating the salt
+ * rotates the room.
+ *
+ * The committed salt is NOT a secret and must never be treated as one: the
+ * derivation needs the root-commit SHA + origin URL too, which only
+ * repo-readers have. Repo access is the trust boundary (same as the git-refs
+ * transport).
+ *
+ * Wire format (JSON text frames over WebSocket):
+ *   client → relay:  { t: "pub", sender, iv, ct }        broadcast + cache
+ *   relay  → client: { t: "pub", sender, iv, ct }        live or warm-join replay
+ *   relay  → client: { t: "hello", peers }               on join (peer count)
+ * The relay never sees plaintext: `ct` is AES-GCM over the presence-blob JSON,
+ * `sender` is an HMAC-derived opaque id, `iv` is the per-message nonce.
+ *
+ * Uses WebCrypto only (globalThis.crypto.subtle) so the same module runs on
+ * Bun, Node ≥ 20, and Cloudflare Workers.
+ */
+/** Default derivation salt when a repo hasn't minted `.harnery/presence-salt`.
+ * Public by design (see module docs); committing a random per-repo salt just
+ * rotates the room away from anything derived before. */
+export declare const DEFAULT_ROOM_SALT = "harnery-presence-salt/v1";
+export interface RoomInputs {
+    /** SHA of the repo's root commit (`git rev-list --max-parents=0 HEAD`,
+     * first line). Stable for the repo's whole life. */
+    rootCommitSha: string;
+    /** The origin remote URL, any format — normalized internally so ssh and
+     * https clones of the same repo land in the same room. */
+    originUrl: string;
+    /** Rotatable room salt (default DEFAULT_ROOM_SALT). */
+    salt?: string;
+}
+export interface RoomCredentials {
+    /** Opaque 32-hex-char room id — the only room identity the relay sees. */
+    roomId: string;
+    /** AES-GCM-256 key for payload E2E encryption. Never leaves the client. */
+    key: CryptoKey;
+    /** Raw bytes for deriving per-machine opaque sender ids. */
+    senderKeyBytes: Uint8Array;
+}
+/**
+ * Normalize a git remote URL so every clone shape of the same repo derives
+ * the same room: `git@github.com:Org/Repo.git`, `ssh://git@github.com/org/repo`,
+ * and `https://github.com/org/repo.git` all → `github.com/org/repo`.
+ */
+export declare function normalizeOriginUrl(raw: string): string;
+/** Derive the room id, E2E key, and sender-id key from the repo identity. */
+export declare function deriveRoomCredentials(inputs: RoomInputs): Promise<RoomCredentials>;
+/** Opaque, stable per-machine sender id: HMAC(senderKey, machineLabel). The
+ * relay caches last-message-per-sender by this without learning the label. */
+export declare function computeSenderId(creds: RoomCredentials, machineLabel: string): Promise<string>;
+/** AES-GCM-encrypt a plaintext payload → { iv, ct } base64 pair. */
+export declare function encryptPayload(creds: RoomCredentials, plaintext: string): Promise<{
+    iv: string;
+    ct: string;
+}>;
+/** Decrypt an { iv, ct } pair. Returns null on any failure (wrong room key,
+ * tampered frame) — callers drop the frame silently. */
+export declare function decryptPayload(creds: RoomCredentials, frame: {
+    iv: string;
+    ct: string;
+}): Promise<string | null>;
+/** Client → relay and relay → client publication frame. */
+export interface PubFrame {
+    t: "pub";
+    /** Opaque sender id (computeSenderId). The relay keys its warm-join cache on this. */
+    sender: string;
+    iv: string;
+    ct: string;
+}
+/** Relay → client greeting on join. */
+export interface HelloFrame {
+    t: "hello";
+    /** Live sockets in the room at join time (including the joiner). */
+    peers: number;
+}
+export type RelayFrame = PubFrame | HelloFrame;
+/** Hard cap a relay enforces per text frame (ciphertext of a ~2KB blob is far
+ * smaller; anything bigger is abuse or a bug). */
+export declare const MAX_FRAME_BYTES: number;
+/** Parse + shape-validate an incoming relay frame. Null on anything off. */
+export declare function parseRelayFrame(raw: string): RelayFrame | null;
+/** Room ids are 32 lowercase hex chars; relays reject anything else. */
+export declare function isValidRoomId(roomId: string): boolean;
+//# sourceMappingURL=relay-protocol.d.ts.map

package/dist/core/presence/relay-protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relay-protocol.d.ts","sourceRoot":"","sources":["../../../src/core/presence/relay-protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAOH;;yDAEyD;AACzD,eAAO,MAAM,iBAAiB,6BAA6B,CAAC;AAE5D,MAAM,WAAW,UAAU;IACzB;wDACoD;IACpD,aAAa,EAAE,MAAM,CAAC;IACtB;8DAC0D;IAC1D,SAAS,EAAE,MAAM,CAAC;IAClB,uDAAuD;IACvD,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,eAAe;IAC9B,0EAA0E;IAC1E,MAAM,EAAE,MAAM,CAAC;IACf,2EAA2E;IAC3E,GAAG,EAAE,SAAS,CAAC;IACf,4DAA4D;IAC5D,cAAc,EAAE,UAAU,CAAC;CAC5B;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAiBtD;AAyBD,6EAA6E;AAC7E,wBAAsB,qBAAqB,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,eAAe,CAAC,CAgBxF;AAED;8EAC8E;AAC9E,wBAAsB,eAAe,CACnC,KAAK,EAAE,eAAe,EACtB,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,MAAM,CAAC,CAUjB;AAeD,oEAAoE;AACpE,wBAAsB,cAAc,CAClC,KAAK,EAAE,eAAe,EACtB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC,CAQrC;AAED;wDACwD;AACxD,wBAAsB,cAAc,CAClC,KAAK,EAAE,eAAe,EACtB,KAAK,EAAE;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAChC,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAWxB;AAID,2DAA2D;AAC3D,MAAM,WAAW,QAAQ;IACvB,CAAC,EAAE,KAAK,CAAC;IACT,sFAAsF;IACtF,MAAM,EAAE,MAAM,CAAC;IACf,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,uCAAuC;AACvC,MAAM,WAAW,UAAU;IACzB,CAAC,EAAE,OAAO,CAAC;IACX,oEAAoE;IACpE,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,UAAU,CAAC;AAE/C;kDACkD;AAClD,eAAO,MAAM,eAAe,QAAY,CAAC;AAEzC,4EAA4E;AAC5E,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CA6B9D;AAED,wEAAwE;AACxE,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAErD"}