clauderipple 0.9.5 → 0.11.0

package/dist/remote/src/e2ee.js

@@ -0,0 +1,126 @@
+// End-to-end encryption between the phone and the host, so the relay forwards bytes it cannot read
+// or forge. No imports: the host also serves this file to the browser (as /src/e2ee.ts), and
+// both ends pass in tweetnacl (`nacl`) themselves, so the same lines run on both sides.
+//
+// Handshake (one per connection):
+//   phone → host   text  {"e2ee":"hello","v":1,"pk":<phone ephemeral X25519 public key>}
+//   host  → phone  text  {"e2ee":"ready","v":1,"n":<nonce>,"box":box(<host ephemeral public key>, n, phone eph pk, host static sk)}
+// The phone knows the host's static public key from the pairing QR (URL fragment, never sent to
+// the relay), so only the real host can make a `box` that opens: the relay cannot stand in for the
+// host. Both sides then use crypto_box_beforenm(peer ephemeral pk, own ephemeral sk) as the key for
+// this connection — ephemeral on both sides, so a host key stolen later does not open old traffic.
+// The phone proves nothing here; it proves itself with the pairing token, inside the channel.
+//
+// Frames after the handshake are binary: XSalsa20-Poly1305 (crypto_box_afternm) with a nonce that
+// is not sent but counted — byte 0 the direction (1 host→phone, 2 phone→host), bytes 16–23 the
+// frame number. A dropped, repeated, reordered or altered frame fails to open, and the link closes.
+export const E2EE_VERSION = 1;
+/** Bytes crypto_box adds to a frame (the Poly1305 tag). */
+export const BOX_OVERHEAD = 16;
+const HOST_TO_PHONE = 1;
+const PHONE_TO_HOST = 2;
+export function toB64u(bytes) {
+    let s = "";
+    for (const b of bytes)
+        s += String.fromCharCode(b);
+    return btoa(s).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+export function fromB64u(text) {
+    if (!/^[A-Za-z0-9_-]*$/.test(text) || text.length % 4 === 1)
+        throw new Error("bad base64url");
+    const s = atob(text.replace(/-/g, "+").replace(/_/g, "/") + "=".repeat((4 - (text.length % 4)) % 4));
+    const out = new Uint8Array(s.length);
+    for (let i = 0; i < s.length; i++)
+        out[i] = s.charCodeAt(i);
+    return out;
+}
+function key32(text) {
+    if (typeof text !== "string")
+        throw new Error("handshake: missing key");
+    let k;
+    try {
+        k = fromB64u(text);
+    }
+    catch {
+        throw new Error("handshake: bad key");
+    }
+    if (k.length !== 32)
+        throw new Error("handshake: bad key length");
+    return k;
+}
+function nonceFor(direction, n) {
+    const nonce = new Uint8Array(24);
+    nonce[0] = direction;
+    const view = new DataView(nonce.buffer);
+    view.setUint32(16, Math.floor(n / 0x1_0000_0000));
+    view.setUint32(20, n >>> 0);
+    return nonce;
+}
+/** One direction-aware encrypted link. Throws on anything that does not open. */
+export class Channel {
+    nacl;
+    key;
+    sendDir;
+    recvDir;
+    sent = 0;
+    received = 0;
+    enc = new TextEncoder();
+    dec = new TextDecoder("utf-8", { fatal: true });
+    constructor(nacl, key, side) {
+        this.nacl = nacl;
+        this.key = key;
+        this.sendDir = side === "host" ? HOST_TO_PHONE : PHONE_TO_HOST;
+        this.recvDir = side === "host" ? PHONE_TO_HOST : HOST_TO_PHONE;
+    }
+    seal(text) {
+        return this.nacl.box.after(this.enc.encode(text), nonceFor(this.sendDir, this.sent++), this.key);
+    }
+    open(frame) {
+        const plain = this.nacl.box.open.after(frame, nonceFor(this.recvDir, this.received), this.key);
+        if (!plain)
+            throw new Error("e2ee: frame did not open (altered, replayed or out of order)");
+        this.received++;
+        return this.dec.decode(plain);
+    }
+}
+export function phoneHello(nacl) {
+    const eph = nacl.box.keyPair();
+    return { text: JSON.stringify({ e2ee: "hello", v: E2EE_VERSION, pk: toB64u(eph.publicKey) }), eph };
+}
+/** Host side: answer a phone's hello. Throws on a malformed hello. */
+export function hostAccept(nacl, hostStatic, helloText) {
+    let hello;
+    try {
+        hello = JSON.parse(helloText);
+    }
+    catch {
+        throw new Error("handshake: not JSON");
+    }
+    if (hello.e2ee !== "hello" || hello.v !== E2EE_VERSION)
+        throw new Error("handshake: not a hello");
+    const phonePk = key32(hello.pk);
+    const eph = nacl.box.keyPair();
+    const n = nacl.randomBytes(24);
+    const sealed = nacl.box(eph.publicKey, n, phonePk, hostStatic.secretKey);
+    const channel = new Channel(nacl, nacl.box.before(phonePk, eph.secretKey), "host");
+    return { text: JSON.stringify({ e2ee: "ready", v: E2EE_VERSION, n: toB64u(n), box: toB64u(sealed) }), channel };
+}
+/** Phone side: check the host's answer against the host key from pairing. Throws if it is not that host. */
+export function phoneFinish(nacl, eph, hostPublicKey, readyText) {
+    let ready;
+    try {
+        ready = JSON.parse(readyText);
+    }
+    catch {
+        throw new Error("handshake: not JSON");
+    }
+    if (ready.e2ee !== "ready" || ready.v !== E2EE_VERSION || typeof ready.n !== "string" || typeof ready.box !== "string")
+        throw new Error("handshake: not a ready");
+    const n = fromB64u(ready.n);
+    if (n.length !== 24)
+        throw new Error("handshake: bad nonce");
+    const hostEph = nacl.box.open(fromB64u(ready.box), n, hostPublicKey, eph.secretKey);
+    if (!hostEph || hostEph.length !== 32)
+        throw new Error("handshake: the answer is not from the paired host");
+    return new Channel(nacl, nacl.box.before(hostEph, eph.secretKey), "phone");
+}

package/dist/remote/src/e2ee.ts

@@ -0,0 +1,126 @@
+// End-to-end encryption between the phone and the host, so the relay forwards bytes it cannot read
+// or forge. No imports: the host also serves this file to the browser (as /src/e2ee.ts), and
+// both ends pass in tweetnacl (`nacl`) themselves, so the same lines run on both sides.
+//
+// Handshake (one per connection):
+//   phone → host   text  {"e2ee":"hello","v":1,"pk":<phone ephemeral X25519 public key>}
+//   host  → phone  text  {"e2ee":"ready","v":1,"n":<nonce>,"box":box(<host ephemeral public key>, n, phone eph pk, host static sk)}
+// The phone knows the host's static public key from the pairing QR (URL fragment, never sent to
+// the relay), so only the real host can make a `box` that opens: the relay cannot stand in for the
+// host. Both sides then use crypto_box_beforenm(peer ephemeral pk, own ephemeral sk) as the key for
+// this connection — ephemeral on both sides, so a host key stolen later does not open old traffic.
+// The phone proves nothing here; it proves itself with the pairing token, inside the channel.
+//
+// Frames after the handshake are binary: XSalsa20-Poly1305 (crypto_box_afternm) with a nonce that
+// is not sent but counted — byte 0 the direction (1 host→phone, 2 phone→host), bytes 16–23 the
+// frame number. A dropped, repeated, reordered or altered frame fails to open, and the link closes.
+
+export interface KeyPair { publicKey: Uint8Array; secretKey: Uint8Array }
+/** The slice of tweetnacl used here. */
+export interface Nacl {
+  box: {
+    (msg: Uint8Array, nonce: Uint8Array, publicKey: Uint8Array, secretKey: Uint8Array): Uint8Array;
+    keyPair(): KeyPair;
+    before(publicKey: Uint8Array, secretKey: Uint8Array): Uint8Array;
+    after(msg: Uint8Array, nonce: Uint8Array, key: Uint8Array): Uint8Array;
+    open: { after(box: Uint8Array, nonce: Uint8Array, key: Uint8Array): Uint8Array | null } & ((box: Uint8Array, nonce: Uint8Array, publicKey: Uint8Array, secretKey: Uint8Array) => Uint8Array | null);
+  };
+  randomBytes(n: number): Uint8Array;
+}
+
+export const E2EE_VERSION = 1;
+/** Bytes crypto_box adds to a frame (the Poly1305 tag). */
+export const BOX_OVERHEAD = 16;
+const HOST_TO_PHONE = 1;
+const PHONE_TO_HOST = 2;
+
+export function toB64u(bytes: Uint8Array): string {
+  let s = "";
+  for (const b of bytes) s += String.fromCharCode(b);
+  return btoa(s).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+export function fromB64u(text: string): Uint8Array {
+  if (!/^[A-Za-z0-9_-]*$/.test(text) || text.length % 4 === 1) throw new Error("bad base64url");
+  const s = atob(text.replace(/-/g, "+").replace(/_/g, "/") + "=".repeat((4 - (text.length % 4)) % 4));
+  const out = new Uint8Array(s.length);
+  for (let i = 0; i < s.length; i++) out[i] = s.charCodeAt(i);
+  return out;
+}
+
+function key32(text: unknown): Uint8Array {
+  if (typeof text !== "string") throw new Error("handshake: missing key");
+  let k: Uint8Array;
+  try { k = fromB64u(text); } catch { throw new Error("handshake: bad key"); }
+  if (k.length !== 32) throw new Error("handshake: bad key length");
+  return k;
+}
+
+function nonceFor(direction: number, n: number): Uint8Array {
+  const nonce = new Uint8Array(24);
+  nonce[0] = direction;
+  const view = new DataView(nonce.buffer);
+  view.setUint32(16, Math.floor(n / 0x1_0000_0000));
+  view.setUint32(20, n >>> 0);
+  return nonce;
+}
+
+/** One direction-aware encrypted link. Throws on anything that does not open. */
+export class Channel {
+  private nacl: Nacl;
+  private key: Uint8Array;
+  private sendDir: number;
+  private recvDir: number;
+  private sent = 0;
+  private received = 0;
+  private enc = new TextEncoder();
+  private dec = new TextDecoder("utf-8", { fatal: true });
+
+  constructor(nacl: Nacl, key: Uint8Array, side: "host" | "phone") {
+    this.nacl = nacl;
+    this.key = key;
+    this.sendDir = side === "host" ? HOST_TO_PHONE : PHONE_TO_HOST;
+    this.recvDir = side === "host" ? PHONE_TO_HOST : HOST_TO_PHONE;
+  }
+
+  seal(text: string): Uint8Array {
+    return this.nacl.box.after(this.enc.encode(text), nonceFor(this.sendDir, this.sent++), this.key);
+  }
+
+  open(frame: Uint8Array): string {
+    const plain = this.nacl.box.open.after(frame, nonceFor(this.recvDir, this.received), this.key);
+    if (!plain) throw new Error("e2ee: frame did not open (altered, replayed or out of order)");
+    this.received++;
+    return this.dec.decode(plain);
+  }
+}
+
+export function phoneHello(nacl: Nacl): { text: string; eph: KeyPair } {
+  const eph = nacl.box.keyPair();
+  return { text: JSON.stringify({ e2ee: "hello", v: E2EE_VERSION, pk: toB64u(eph.publicKey) }), eph };
+}
+
+/** Host side: answer a phone's hello. Throws on a malformed hello. */
+export function hostAccept(nacl: Nacl, hostStatic: KeyPair, helloText: string): { text: string; channel: Channel } {
+  let hello: { e2ee?: unknown; v?: unknown; pk?: unknown };
+  try { hello = JSON.parse(helloText) as typeof hello; } catch { throw new Error("handshake: not JSON"); }
+  if (hello.e2ee !== "hello" || hello.v !== E2EE_VERSION) throw new Error("handshake: not a hello");
+  const phonePk = key32(hello.pk);
+  const eph = nacl.box.keyPair();
+  const n = nacl.randomBytes(24);
+  const sealed = nacl.box(eph.publicKey, n, phonePk, hostStatic.secretKey);
+  const channel = new Channel(nacl, nacl.box.before(phonePk, eph.secretKey), "host");
+  return { text: JSON.stringify({ e2ee: "ready", v: E2EE_VERSION, n: toB64u(n), box: toB64u(sealed) }), channel };
+}
+
+/** Phone side: check the host's answer against the host key from pairing. Throws if it is not that host. */
+export function phoneFinish(nacl: Nacl, eph: KeyPair, hostPublicKey: Uint8Array, readyText: string): Channel {
+  let ready: { e2ee?: unknown; v?: unknown; n?: unknown; box?: unknown };
+  try { ready = JSON.parse(readyText) as typeof ready; } catch { throw new Error("handshake: not JSON"); }
+  if (ready.e2ee !== "ready" || ready.v !== E2EE_VERSION || typeof ready.n !== "string" || typeof ready.box !== "string") throw new Error("handshake: not a ready");
+  const n = fromB64u(ready.n);
+  if (n.length !== 24) throw new Error("handshake: bad nonce");
+  const hostEph = nacl.box.open(fromB64u(ready.box), n, hostPublicKey, eph.secretKey);
+  if (!hostEph || hostEph.length !== 32) throw new Error("handshake: the answer is not from the paired host");
+  return new Channel(nacl, nacl.box.before(hostEph, eph.secretKey), "phone");
+}

package/dist/remote/src/eventlog.js

@@ -0,0 +1,298 @@
+import { createHash, randomUUID } from "node:crypto";
+import { closeSync, ftruncateSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { readJson, writeFileAtomic } from "./fsutil.js";
+import { FRAME_CAP, INLINE_CAP } from "./protocol.js";
+import { changeCount, toolInput } from "./tool-details.js";
+const LINE_CAP = 64 * 1024;
+const PAGE_CAP = FRAME_CAP - 4096;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function serialized(event) { return JSON.stringify(event) + "\n"; }
+function fitLine(event) {
+    let line = serialized(event);
+    if (Buffer.byteLength(line) <= LINE_CAP)
+        return line;
+    // Only display strings are lossy: text, input, summary, description, title,
+    // error, detail, reason and blob previews. Routing/identity fields stay intact.
+    const fields = new Set(["text", "input", "summary", "description", "title", "error", "detail", "reason", "preview"]);
+    const candidates = [];
+    function collect(value) {
+        if (Array.isArray(value)) {
+            for (const child of value)
+                collect(child);
+            return;
+        }
+        if (value === null || typeof value !== "object")
+            return;
+        const object = value;
+        for (const [key, child] of Object.entries(object)) {
+            if (typeof child === "string" && fields.has(key) && child.length > 1)
+                candidates.push({ object, key, text: child });
+            else if (typeof child === "object")
+                collect(child);
+        }
+    }
+    collect(event);
+    candidates.sort((a, b) => Buffer.byteLength(JSON.stringify(b.text)) - Buffer.byteLength(JSON.stringify(a.text)));
+    for (const { object, key, text } of candidates) {
+        object[key] = "…";
+        line = serialized(event);
+        if (Buffer.byteLength(line) > LINE_CAP)
+            continue;
+        let low = 0;
+        let high = text.length - 1;
+        while (low < high) {
+            const mid = Math.ceil((low + high) / 2);
+            object[key] = prefix(text, mid) + "…";
+            if (Buffer.byteLength(serialized(event)) <= LINE_CAP)
+                low = mid;
+            else
+                high = mid - 1;
+        }
+        object[key] = prefix(text, low) + "…";
+        return serialized(event);
+    }
+    throw new RangeError("Event structure exceeds 64 KiB even after truncating display strings");
+}
+function prefix(text, length) {
+    const last = text.charCodeAt(length - 1);
+    return text.slice(0, last >= 0xd800 && last <= 0xdbff ? length - 1 : length);
+}
+export class EventLog {
+    epoch;
+    dir;
+    segmentBytes;
+    now;
+    entries = [];
+    segments = [];
+    finalized = new Set();
+    closed = false;
+    constructor(opts, epoch) {
+        this.dir = opts.dir;
+        this.segmentBytes = opts.segmentBytes ?? 8 * 1024 * 1024;
+        this.now = opts.now ?? Date.now;
+        this.epoch = epoch;
+        if (!Number.isFinite(this.segmentBytes) || this.segmentBytes <= 0)
+            throw new RangeError("segmentBytes must be positive");
+    }
+    static open(opts) {
+        mkdirSync(opts.dir, { recursive: true, mode: 0o700 });
+        const names = readdirSync(opts.dir).filter(name => /^events-\d{6,}\.jsonl$/.test(name))
+            .sort((a, b) => Number(a.slice(7, -6)) - Number(b.slice(7, -6)));
+        const metaFile = join(opts.dir, "meta.json");
+        let meta = readJson(metaFile);
+        if (meta === null) {
+            if (names.length)
+                throw new Error("Event log has segments but no epoch");
+            meta = { epoch: randomUUID() };
+            writeFileAtomic(metaFile, JSON.stringify(meta));
+        }
+        if (typeof meta.epoch !== "string" || !UUID.test(meta.epoch))
+            throw new Error("Invalid event log epoch");
+        const log = new EventLog(opts, meta.epoch);
+        try {
+            for (const [i, name] of names.entries())
+                log.scan(name, i === names.length - 1);
+            if (!log.segments.length)
+                log.newSegment();
+            return log;
+        }
+        catch (error) {
+            log.close();
+            throw error;
+        }
+    }
+    get lastSeq() { return this.entries.length; }
+    newSegment() {
+        const number = (this.segments.at(-1)?.number ?? 0) + 1;
+        const file = join(this.dir, `events-${String(number).padStart(6, "0")}.jsonl`);
+        const segment = { fd: openSync(file, "ax+", 0o600), bytes: 0, number };
+        this.segments.push(segment);
+        return segment;
+    }
+    scan(name, last) {
+        const file = join(this.dir, name);
+        const data = readFileSync(file);
+        const segment = { fd: openSync(file, "a+", 0o600), bytes: data.length, number: Number(name.slice(7, -6)) };
+        this.segments.push(segment);
+        let offset = 0;
+        while (offset < data.length) {
+            const end = data.indexOf(10, offset);
+            if (end === -1) {
+                if (!last)
+                    throw new Error(`Unterminated event in ${name}`);
+                break;
+            }
+            let event;
+            try {
+                event = JSON.parse(data.toString("utf8", offset, end));
+            }
+            catch (error) {
+                if (!last || end !== data.length - 1)
+                    throw error;
+                break;
+            }
+            if (event === null || event.seq !== this.lastSeq + 1 || typeof event.at !== "number" || typeof event.kind !== "string") {
+                throw new Error(`Invalid event at ${name}:${offset}`);
+            }
+            this.index(event, segment, offset, end + 1 - offset);
+            offset = end + 1;
+        }
+        if (offset !== data.length) {
+            ftruncateSync(segment.fd, offset);
+            segment.bytes = offset;
+        }
+    }
+    index(event, segment, offset, length) {
+        const entry = { seq: event.seq, segment, offset, length, kind: event.kind };
+        if (event.kind === "assistant" || event.kind === "delta") {
+            entry.msg = event.msg;
+            if (event.kind === "assistant")
+                this.finalized.add(event.msg);
+        }
+        this.entries.push(entry);
+    }
+    append(body) {
+        this.assertOpen();
+        const event = { ...structuredClone(body), seq: this.lastSeq + 1, at: this.now() };
+        const blobs = [];
+        function externalize(text) {
+            if (typeof text !== "string" || text.length <= INLINE_CAP)
+                return text;
+            const id = randomUUID();
+            blobs.push({ id, text });
+            const ref = { blob: id, bytes: Buffer.byteLength(text), preview: prefix(text, 400) };
+            return ref;
+        }
+        if (event.kind === "assistant") {
+            event.text = externalize(event.text);
+            for (const tool of event.tools) {
+                if (["Edit", "MultiEdit", "Write"].includes(tool.name) && !tool.changes)
+                    tool.changes = changeCount(tool.name, toolInput(tool.input));
+                if (tool.input !== undefined)
+                    tool.input = externalize(tool.input);
+            }
+        }
+        else if (event.kind === "tool_result" || event.kind === "thinking")
+            event.text = externalize(event.text);
+        else if (event.kind === "permission")
+            event.input = externalize(event.input);
+        const line = fitLine(event);
+        for (const { id, text } of blobs)
+            writeFileAtomic(join(this.dir, "blobs", `${id}.txt`), text);
+        let segment = this.segments.at(-1);
+        const length = Buffer.byteLength(line);
+        if (segment.bytes > 0 && segment.bytes + length > this.segmentBytes)
+            segment = this.newSegment();
+        const offset = segment.bytes;
+        try {
+            writeFileSync(segment.fd, line, "utf8");
+        }
+        catch (error) {
+            // Do not allow a partial failed append to poison the next event in this process.
+            ftruncateSync(segment.fd, offset);
+            throw error;
+        }
+        segment.bytes += length;
+        this.index(event, segment, offset, length);
+        return event;
+    }
+    assertOpen() { if (this.closed)
+        throw new Error("Event log is closed"); }
+    visible(entry) {
+        return entry.kind !== "delta" || entry.msg === undefined || !this.finalized.has(entry.msg);
+    }
+    read(entry) {
+        const buffer = Buffer.allocUnsafe(entry.length);
+        let bytes = 0;
+        while (bytes < buffer.length) {
+            const n = readSync(entry.segment.fd, buffer, bytes, buffer.length - bytes, entry.offset + bytes);
+            if (n === 0)
+                throw new Error("Event log was truncated while open");
+            bytes += n;
+        }
+        return JSON.parse(buffer.toString("utf8"));
+    }
+    page(start, direction, maxBytes) {
+        this.assertOpen();
+        if (Number.isNaN(maxBytes) || maxBytes < 0)
+            throw new RangeError("maxBytes must be nonnegative");
+        const events = [];
+        let bytes = 0;
+        let remaining = false;
+        for (let i = start; i >= 0 && i < this.entries.length; i += direction) {
+            const entry = this.entries[i];
+            if (!this.visible(entry))
+                continue;
+            if (events.length && bytes + entry.length > maxBytes) {
+                remaining = true;
+                break;
+            }
+            events.push(this.read(entry));
+            bytes += entry.length;
+        }
+        if (direction === -1)
+            events.reverse();
+        return { events, remaining };
+    }
+    readAfter(afterSeq, maxBytes = PAGE_CAP) {
+        const { events, remaining } = this.page(Math.max(0, Math.floor(afterSeq)), 1, maxBytes);
+        return { events, more: remaining };
+    }
+    tail(maxBytes = PAGE_CAP) {
+        const { events, remaining } = this.page(this.entries.length - 1, -1, maxBytes);
+        return { events, hasOlder: remaining };
+    }
+    before(beforeSeq, maxBytes = PAGE_CAP) {
+        const start = Math.min(this.entries.length - 1, Math.ceil(beforeSeq) - 2);
+        const { events, remaining } = this.page(start, -1, maxBytes);
+        return { events, hasOlder: remaining };
+    }
+    /** The last nonempty assistant text of this turn, not a previous turn or a tool result.
+     * Walk the in-memory index so even a long chain of tool events needs only relevant disk reads. */
+    lastAssistantText(beforeSeq = this.lastSeq + 1) {
+        this.assertOpen();
+        for (let i = Math.min(this.entries.length, beforeSeq - 1) - 1; i >= 0; i--) {
+            const entry = this.entries[i];
+            if (entry.kind === "turn" || entry.kind === "user" || entry.kind === "result")
+                return "";
+            if (entry.kind !== "assistant")
+                continue;
+            const event = this.read(entry);
+            if (event.kind !== "assistant")
+                continue;
+            const text = typeof event.text === "string" ? event.text : event.text.preview;
+            if (text.trim())
+                return text;
+        }
+        return "";
+    }
+    /** Content-addressed, so repeated SDK snapshots do not duplicate large image bytes. */
+    image(base64) {
+        this.assertOpen();
+        const hash = createHash("sha256").update(base64).digest("hex");
+        const id = `${hash.slice(0, 8)}-${hash.slice(8, 12)}-${hash.slice(12, 16)}-${hash.slice(16, 20)}-${hash.slice(20, 32)}`;
+        writeFileAtomic(join(this.dir, "blobs", `${id}.txt`), base64);
+        return id;
+    }
+    blob(id) {
+        this.assertOpen();
+        if (!UUID.test(id))
+            return null;
+        try {
+            return readFileSync(join(this.dir, "blobs", `${id}.txt`), "utf8");
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return null;
+            throw error;
+        }
+    }
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        for (const segment of this.segments)
+            closeSync(segment.fd);
+    }
+}

package/dist/remote/src/expo-push.js

@@ -0,0 +1,127 @@
+// Only generic fallback copy and encrypted content cross the native push provider boundary.
+import { createCipheriv, randomBytes } from "node:crypto";
+import path from "node:path";
+import { pushContent } from "./push-content.js";
+import { readJson, writeFileAtomic } from "./fsutil.js";
+export function validPushKey(key) {
+    return typeof key === "string" && /^[A-Za-z0-9_-]{43}$/.test(key) && Buffer.from(key, "base64url").toString("base64url") === key;
+}
+/** RFC 8439 / CryptoKit combined format: nonce(12) ‖ ciphertext ‖ tag(16), no AAD. */
+export function encryptPush(key, content) {
+    if (!validPushKey(key))
+        throw new Error("invalid push key");
+    const nonce = randomBytes(12);
+    const cipher = createCipheriv("chacha20-poly1305", Buffer.from(key, "base64url"), nonce, { authTagLength: 16 });
+    const ciphertext = Buffer.concat([cipher.update(JSON.stringify(content), "utf8"), cipher.final()]);
+    return Buffer.concat([nonce, ciphertext, cipher.getAuthTag()]).toString("base64url");
+}
+export const validExpoToken = (token) => /^(ExponentPushToken|ExpoPushToken)\[[A-Za-z0-9_-]+\]$/.test(token);
+export function expoBody(event, lang) {
+    if (event.kind === "permission")
+        return lang === "ko" ? "승인을 기다립니다" : "Waiting for approval";
+    if (event.kind !== "result")
+        return null;
+    if (event.ok)
+        return lang === "ko" ? "작업을 마쳤습니다" : "Work finished";
+    return lang === "ko" ? "작업이 실패했습니다" : "Work failed";
+}
+/** Inject only external boundaries: HTTP and the wait for Expo's asynchronous receipts. */
+export function expoSender(fetcher = fetch, wait = () => new Promise(resolve => { setTimeout(resolve, 15_000).unref(); })) {
+    return async (payload) => {
+        const response = await fetcher("https://exp.host/--/api/v2/push/send", {
+            method: "POST", headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(payload), signal: AbortSignal.timeout(15_000),
+        });
+        if (!response.ok)
+            throw new Error(`Expo push HTTP ${response.status}`);
+        const json = await response.json();
+        const ticket = json.data;
+        if (ticket?.details?.error === "DeviceNotRegistered")
+            return "gone";
+        if (ticket?.status !== "ok" || !ticket.id)
+            throw new Error(ticket?.message ?? "invalid Expo push ticket");
+        // Receipt errors can arrive after an accepted ticket. Poll for up to 15 minutes without
+        // blocking the session's append (main calls onEvent asynchronously).
+        for (let attempt = 0; attempt < 60; attempt++) {
+            await wait();
+            const receiptResponse = await fetcher("https://exp.host/--/api/v2/push/getReceipts", {
+                method: "POST", headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({ ids: [ticket.id] }), signal: AbortSignal.timeout(15_000),
+            });
+            if (!receiptResponse.ok)
+                throw new Error(`Expo receipts HTTP ${receiptResponse.status}`);
+            const receiptJson = await receiptResponse.json();
+            const receipt = receiptJson.data?.[ticket.id];
+            if (!receipt)
+                continue;
+            if (receipt.details?.error === "DeviceNotRegistered")
+                return "gone";
+            if (receipt.status !== "ok")
+                throw new Error(receipt.message ?? "Expo receipt failed");
+            return "sent";
+        }
+        throw new Error("Expo receipt timed out");
+    };
+}
+export class ExpoNotifier {
+    file;
+    tokens;
+    opts;
+    constructor(opts) {
+        this.opts = opts;
+        this.file = path.join(opts.dir, "expo-push.json");
+        this.tokens = readJson(this.file) ?? {};
+    }
+    devices() { return Object.keys(this.tokens); }
+    subscribe(clientId, token, lang, platform, key) {
+        if (!clientId || typeof token !== "string" || !validExpoToken(token))
+            throw new Error("invalid Expo push token");
+        if (key !== undefined && (!validPushKey(key) || (platform !== "ios" && platform !== "android")))
+            throw new Error("invalid push key or platform");
+        this.tokens[clientId] = { token, lang: lang === "en" ? "en" : "ko", ...(key && platform ? { key, platform } : {}) };
+        this.save();
+    }
+    unsubscribe(clientId) {
+        if (!(clientId in this.tokens))
+            return;
+        delete this.tokens[clientId];
+        this.save();
+    }
+    async onEvent(session, event) {
+        if (this.opts.seenRecently(session))
+            return;
+        // Resolve once per event, lazily: old devices must never cause private context reads.
+        let context;
+        await Promise.all(Object.entries(this.tokens).map(async ([id, stored]) => {
+            const body = expoBody(event, stored.lang);
+            if (!body)
+                return;
+            try {
+                let payload = { to: stored.token, title: "Ripple Remote", body, data: { session }, sound: "default", ttl: event.kind === "permission" ? 3600 : 86400 };
+                if (stored.key) {
+                    try {
+                        context ??= Promise.resolve(this.opts.context?.(session, event) ?? {});
+                        const e = encryptPush(stored.key, pushContent(event, stored.lang, await context, body));
+                        payload = stored.platform === "android"
+                            ? { to: stored.token, data: { session, e, fallback: body }, priority: "high", ttl: payload.ttl }
+                            : { ...payload, mutableContent: true, data: { session, e } };
+                    }
+                    catch {
+                        // No private exception text in logs; a context/crypto failure must still deliver fallback.
+                        this.opts.log(`expo push: content unavailable for device ${id.slice(0, 8)}; sending fallback`);
+                    }
+                }
+                // An unsubscribe/replacement during context lookup must not send an obsolete key/token.
+                if (this.tokens[id] !== stored)
+                    return;
+                const result = await this.opts.send(payload);
+                if (result === "gone" && this.tokens[id] === stored)
+                    this.unsubscribe(id);
+            }
+            catch (error) {
+                this.opts.log(`expo push: send failed for device ${id.slice(0, 8)}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }));
+    }
+    save() { writeFileAtomic(this.file, JSON.stringify(this.tokens, null, 1)); }
+}