viveworker 0.7.0-beta.3 → 0.8.0

package/README.md

@@ -5,7 +5,7 @@
 [![npm version](https://badge.fury.io/js/viveworker.svg)](https://badge.fury.io/js/viveworker)
 [![License](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
-`viveworker` is an open mobile control surface for Codex Desktop, Claude Desktop, Claude Code, A2A tasks, File Share, and Moltbook.
+`viveworker` is an open mobile control surface for Codex Desktop, Claude Desktop, Claude Code, Remote connection, A2A tasks, File Share, and Moltbook.
 
 When your AI desktop session needs an approval, asks whether to implement a plan, wants you to choose from options, finishes a task, needs to hand off a file, or receives a task from another agent while you are away from your desk, `viveworker` keeps all of that within reach on your phone. Instead of breaking your rhythm, it helps you keep vivecoding going from anywhere in your home or office.
 
@@ -31,6 +31,7 @@ keep your AI session moving, keep context close, and keep your momentum.
 
 - **AI coding sessions**: approvals, plan checks, questions, completions, and mobile code review for Codex and Claude
 - **Thread Sharing**: pass context, plan-review requests, or full handoffs between Codex and Claude sessions
+- **Remote connection**: reach your Mac from a paired device outside your LAN through an end-to-end encrypted relay
 - **File Share**: host static files on a private URL, with optional password protection and expiry
 - **Moltbook ops**: draft posts, scout replies, and handle incoming responses from the same phone UI
 - **A2A relay**: receive tasks from other agents, approve them on your phone, and execute locally on your Mac
@@ -50,8 +51,9 @@ one phone, one local control surface, multiple agent workflows.
 It gets even more fun with a Mac mini.
 Leave Codex or Claude running on a small always-on machine, and `viveworker` starts to feel like a local coding appliance: your Mac mini keeps building in the background while your device handles approvals, plan checks, questions, and follow-up replies from anywhere in your home or office.
 
-`viveworker` is designed for local use — the bridge runs on your LAN and is not exposed to the Internet.
-External communication is handled through the A2A relay (`a2a.viveworker.com`), which the bridge polls outbound.
+`viveworker` starts from a local-first model: the bridge runs on your Mac and is not exposed directly to the Internet.
+When Remote connection is enabled, paired devices can also reach that bridge off-LAN through an end-to-end encrypted relay.
+External agent communication is handled separately through the A2A relay (`a2a.viveworker.com`), which the bridge polls outbound.
 
 ## Mac mini Ideas
 
@@ -117,6 +119,22 @@ After setup:
 - use the pairing URL only for first-time setup or when you intentionally add another device
 - keep using the Home Screen app if you want notifications to work reliably
 
+## Remote Connection
+
+Remote connection lets a paired device reach your Mac even when it is not on the same Wi-Fi.
+
+Enable it from `Settings > Remote connection` in the Home Screen app. The bridge still stays local on your Mac; it does not open an inbound public port. Instead, the Mac and the paired device meet through the relay, and the actual traffic is end-to-end encrypted between the paired device and your bridge.
+
+Security details:
+
+- only devices already paired on your LAN can use Remote connection
+- the relay token can be rotated manually from the paired device when you are back on the same LAN
+- existing devices refresh their relay token automatically during LAN enrollment after the rotation window
+- connection events and token rotations appear in `Settings > Remote connection > Connection history`
+- if a device is lost, revoke it from `Settings > Remote connection` or `Settings > Devices`
+
+If Remote connection is turned off, off-LAN devices cannot reach the Mac again until you return to the same Wi-Fi and turn it back on.
+
 ## Common Commands
 
 Use these commands most often:
@@ -392,6 +410,7 @@ Today the project already exposes practical integration points through:
 
 - Codex + Claude Desktop support
 - Claude hooks
+- Remote connection for paired devices
 - A2A relay + Agent Card
 - File Share URLs
 - Thread Sharing across sessions
@@ -404,6 +423,7 @@ make `viveworker` the default local/mobile surface that other AI tools can plug
 If you want to build on `viveworker`, these are the main surfaces to think in:
 
 - **Approvals and structured decisions**: approvals, plan checks, multiple-choice questions, and completions all land in the same mobile flow
+- **Remote connection**: keep that mobile flow reachable from paired devices even when they are outside the LAN
 - **Thread Sharing**: move notes, plan reviews, and handoffs between Codex and Claude sessions with phone approval in the loop
 - **File Share**: hand back static artefacts as private URLs instead of chat attachments
 - **A2A relay**: receive or send external agent tasks through a public relay while execution stays local
@@ -416,6 +436,7 @@ These parts already feel like core product surface, not side experiments:
 - Codex mobile approvals, questions, completions, and code review
 - Claude Desktop integration through hooks
 - trusted-LAN pairing, HTTPS, PWA install, and Web Push
+- Remote connection for paired devices, with E2E relay traffic, token rotation, and connection history
 - A2A task intake + approval + local execution
 - File Share for static artefacts
 - Thread Sharing between Codex and Claude sessions
@@ -474,8 +495,11 @@ If you can map your tool onto one of those paths, you probably do not need a bra
 
 ## Security Model
 
-- use `viveworker` only on a trusted LAN
+- pair devices only on a trusted LAN
 - do not expose the bridge directly to the Internet
+- Remote connection uses a relay only for rendezvous/transport; paired-device traffic is end-to-end encrypted to your bridge
+- relay tokens can be rotated manually and are refreshed automatically during LAN enrollment after the rotation window
+- remote connection activity is recorded locally in `~/.viveworker/remote-pairing-audit.jsonl`
 - if you lose a paired device, revoke it from `Settings > Devices`
 - use `pair` only when you want to add another trusted device
 - A2A relay authentication: external agents must provide a valid API key (`X-A2A-Key` header), and registration requires GitHub OAuth
@@ -490,6 +514,7 @@ If you later want a second wake-up notification path, you can add `ntfy` alongsi
 ## Troubleshooting
 
 - If the `.local` URL does not open, use the printed IP-based URL
+- If Remote connection does not work off-LAN, open `Settings > Remote connection` once on the same Wi-Fi as the Mac and confirm the device is registered
 - If pairing has expired, run `npx viveworker pair`
 - If notifications do not appear, make sure you opened the Home Screen app, not just a browser tab
 - If Web Push is enabled, make sure you are opening the HTTPS URL
@@ -512,3 +537,7 @@ Planned next steps include:
 - ✅ ~~Android support~~ (Apr 1, 2026)
 - ✅ ~~Moltbook integration~~ (Apr 10, 2026)
 - ✅ ~~A2A protocol support~~ (Apr 12, 2026)
+- ✅ ~~File Share~~ (Apr 18, 2026)
+- ✅ ~~Auto Pilot~~ (Apr 21, 2026)
+- ✅ ~~x402 / pay-per-unlock flow (testnet)~~ (Apr 25, 2026)
+- ✅ ~~Remote connection~~ (Apr 28, 2026)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "viveworker",
-  "version": "0.7.0-beta.3",
+  "version": "0.8.0",
   "description": "Open mobile control surface for Codex, Claude, Thread Sharing, File Share, Moltbook, and A2A tasks on your trusted LAN.",
   "author": "Yuta Hoshino <hoshino.lireneo@gmail.com>",
   "license": "MIT",
@@ -61,12 +61,16 @@
     "ntfy/docker-compose.yml.example"
   ],
   "dependencies": {
-    "@hazbase/auth": "^0.5.0",
+    "@hazbase/auth": "^0.5.1",
+    "@noble/ciphers": "^1.0.0",
+    "@noble/curves": "^1.2.0",
+    "@noble/hashes": "^1.3.2",
     "ethers": "^6.16.0",
     "qrcode-terminal": "^0.12.0",
     "web-push": "^3.6.7"
   },
   "devDependencies": {
-    "@cf-wasm/resvg": "^0.3.3"
+    "@cf-wasm/resvg": "^0.3.3",
+    "fake-indexeddb": "^6.2.5"
   }
 }

package/scripts/lib/remote-pairing/README.md

@@ -0,0 +1,164 @@
+# `scripts/lib/remote-pairing/` — viveworker remote pairing crypto
+
+End-to-end encryption layer for connecting phone PWA ↔ PC bridge over an
+**untrusted relay** (Cloudflare Worker + Durable Object). Status: **Phase 0**
+— crypto primitives + handshake + identity key persistence verified by
+unit tests and a two-process E2E demo. Transport (WSS), envelope (replay
+buffer / sequence numbers), and PWA wiring are tracked separately.
+
+## Why this exists
+
+viveworker today pairs a phone PWA and a Mac bridge over the local LAN
+(`https://<lan-ip>:8810` with mkcert). For users away from the LAN we
+want the same UX without:
+
+- shipping a phone-side app (PWA constraint),
+- terminating TLS at a third party (no Cloudflare Tunnel),
+- exposing a public HTTPS endpoint to the internet at large.
+
+The chosen architecture is a Cloudflare Worker + Durable Object that
+brokers WSS connections between phone and PC. This module is the
+**E2EE layer that runs on top of that relay**. The relay carries
+ciphertext and routing metadata; it never sees decrypted application
+data and never holds long-term keys.
+
+## Protocol choice: `Noise_IK_25519_ChaChaPoly_SHA256`
+
+Why IK specifically:
+
+- The phone (initiator) knows the PC bridge's static public key from the
+  pairing flow that happened over LAN. With that prior knowledge IK
+  gives **mutual authentication in 1 round-trip** (msg 1: phone → PC,
+  msg 2: PC → phone, then transport).
+- Both sides' static keys are bound into the handshake hash, so a MitM
+  who tampers with either side fails to produce a valid AEAD tag.
+- The chosen DH (`X25519`), AEAD (`ChaCha20-Poly1305`), and hash (`SHA256`)
+  all map cleanly to Web Crypto / libsodium.js / `@noble/*` so the same
+  protocol is implementable in the PWA without a polyfill audit.
+
+What we **explicitly didn't pick**:
+
+- **Static-static ECDH with a long-term symmetric key**: would lose
+  forward secrecy. A relay snapshot + future identity-key compromise
+  would decrypt all past sessions.
+- **Signal Double Ratchet**: per-message rotation, but for a request/
+  response control plane the cost (more state, more code, more
+  failure modes on resume) doesn't earn its keep.
+- **Noise XX**: would work too, but adds a round trip for static-key
+  exchange that IK avoids.
+
+## Layered key model
+
+Three keys, kept strictly separated. Mixing them is a confused-deputy
+hazard (e.g., a wallet-signed device-pairing message becoming a wallet
+authorization).
+
+| Layer    | Algo                | Lifetime                 | Where             | Used for                                  |
+| -------- | ------------------- | ------------------------ | ----------------- | ----------------------------------------- |
+| Wallet   | `secp256k1`         | Long-term                | hazBase / wallet  | EVM signing, USDC x402 payments           |
+| Identity | `X25519`            | Long-term, per device    | This module       | Noise IK static `s`, device-pair auth     |
+| Session  | `X25519` ephemeral  | Per WS connection        | Derived in Noise  | AEAD `k`/`n`, **per-session forward sec** |
+
+The session key never touches disk. Each new WSS connection runs a fresh
+IK handshake → fresh ephemeral DH → fresh `CipherState`. A relay
+compromise plus future identity-key leak still cannot decrypt past
+recordings.
+
+## Files
+
+- `noise.mjs` — Noise IK state machine. `HandshakeState`, `CipherState`,
+  `SymmetricState`, `NoiseSession`. Pure Uint8Array I/O so the same
+  module runs in Node and browser bundlers (no `Buffer` leakage).
+- `keys.mjs` — Identity key generation, hex encoding, persistence to
+  `~/.viveworker/remote-pairing.env` (file mode `0o600`, dir `0o700`).
+  Includes `fingerprintIdentity()` for human-readable verification
+  strings (`XXXX-XXXX-XXXX`, Crockford-ish alphabet).
+
+## Wire layout (Phase 0)
+
+This module produces and consumes **Noise transport messages only**.
+Envelope-level fields (sequence numbers, message IDs, replay buffer
+indexing) are deliberately not part of this layer — they're added by
+the Phase 1 envelope module so the relay can route without seeing
+ciphertext. End-state target:
+
+```
+WSS frame body (binary)
+└── outer envelope                    ← visible to relay; routing-only
+    ├── seq: u32                      ← replay buffer ordering
+    ├── mid: 16 bytes (UUID)          ← deduplication
+    ├── type: data | ack | ping | resume
+    └── payload: bytes                ← Noise transport message (this module)
+        └── ciphertext + 16-byte Poly1305 tag
+```
+
+Message sizes today:
+
+- **Handshake msg 1** (initiator → responder, `e, es, s, ss + payload`):
+  `32 + 32 + 16 + payload_len + 16` bytes (e pub, encrypted s pub, AEAD tag,
+  encrypted payload, AEAD tag).
+- **Handshake msg 2** (responder → initiator, `e, ee, se + payload`):
+  `32 + payload_len + 16` bytes.
+- **Transport message**: `payload_len + 16` bytes.
+
+## Channel binding
+
+After handshake both sides agree on a 32-byte hash of the handshake
+transcript. `NoiseSession.getChannelBinding()` returns it. Higher
+layers can pin sensitive operations to this binding — e.g., a
+**WebAuthn challenge that the PWA derives from the channel binding**,
+so a passkey assertion is bound to the specific Noise session, not
+just to "any browser session at this origin."
+
+This is how we'll wire Phase 5's "passkey-confirm before USDC payment"
+flow without inventing a separate challenge nonce.
+
+## Testing
+
+```bash
+# Unit tests — protocol semantics (15 tests)
+node --test scripts/test/remote-pairing-noise.test.mjs
+
+# End-to-end demo — two real processes over stdio pipes (Phase 0 DoD)
+node scripts/test/remote-pairing-demo.mjs
+```
+
+The demo prints a transcript of both sides' wire frames in hex; eyeball
+that no plaintext (e.g. `"approve task #42"`) appears anywhere outside
+the decrypted payloads.
+
+## Phase 0 → Phase 1 hand-off
+
+What this module guarantees today:
+
+- ✅ Handshake completes with 1 round-trip given a pre-shared responder static key.
+- ✅ Mutual authentication (wrong responder static key fails handshake).
+- ✅ Forward secrecy per session (ephemeral DH keys, dropped on session end).
+- ✅ AEAD-bound associated data (envelope tampering breaks decryption).
+- ✅ Channel binding for higher-layer auth pinning.
+- ✅ Identity keys persist to disk with strict perms; round-trip verified.
+
+What Phase 1 still needs to add (not this module's job):
+
+- 🔜 **Envelope** with `seq` / `mid` / `type` for routing + dedup.
+- 🔜 **Replay buffer** in the Durable Object (5-min TTL by default).
+- 🔜 **Reconnect resume** via `RESUME { lastSeq }` → DO drains buffer.
+- 🔜 **At-least-once delivery** with explicit `ACK { mid }` frames.
+- 🔜 **Hibernatable WS** in the Durable Object (cost-critical from day 1).
+- 🔜 **Ping/pong** every 30–45 s to defeat CF's ~100 s WS idle timeout.
+
+What Phase 2 still needs to add (PWA side):
+
+- 🔜 PWA bundle of `noise.mjs` (already Uint8Array-clean, should JustWork).
+- 🔜 Identity key persistence in browser (IndexedDB; non-extractable
+  CryptoKey if the platform supports it, else raw bytes with a passkey
+  unlock).
+- 🔜 `visibilitychange` → reconnect-with-resume flow.
+- 🔜 Web Push wake → re-establish WS pipe.
+
+## References
+
+- Noise spec rev 34: <https://noiseprotocol.org/noise.html>
+- IK pattern security: § 7.4 "Pattern security properties"
+- HKDF: RFC 5869, used as `MixKey` per Noise § 4.3
+- ChaCha20-Poly1305 nonce format: 4 zero bytes + 8-byte LE counter (Noise § 5.1)

package/scripts/lib/remote-pairing/_browser-bundle-entry.mjs

@@ -0,0 +1,86 @@
+/**
+ * _browser-bundle-entry.mjs — Aggregator for the browser bundle.
+ *
+ * The PWA can't pull npm packages directly (no build step on the
+ * served-files side). This module is the input to esbuild — it pulls in
+ * noise.mjs + envelope.mjs + keys-core.mjs and their @noble/* dependencies
+ * so the bundler can produce a single self-contained ESM file
+ * (`web/remote-pairing.bundle.js`).
+ *
+ * To regenerate the bundle:
+ *
+ *   node scripts/build-remote-pairing-bundle.mjs
+ *
+ * Anything Node-specific (load/save/ensure helpers from keys.mjs, the
+ * stdio demo, the wrangler-driven smoke test) must NOT be re-exported
+ * here — those would either fail to bundle or pull node_modules into
+ * the browser payload.
+ */
+
+// Crypto / handshake / session
+export {
+  PROTOCOL_NAME,
+  HASHLEN,
+  KEYLEN,
+  DHLEN,
+  TAGLEN,
+  HandshakeState,
+  NoiseSession,
+  createInitiator,
+  createResponder,
+} from "./noise.mjs";
+
+// Wire envelope (frame types, encoders, decoder, helpers)
+export {
+  FRAME_DATA,
+  FRAME_ACK,
+  FRAME_PING,
+  FRAME_PONG,
+  FRAME_RESUME_REQ,
+  FRAME_RESUME_OK,
+  FRAME_RESUME_FAIL,
+  RESUME_FAIL_BUFFER_EXPIRED,
+  RESUME_FAIL_UNKNOWN_PAIRING,
+  RESUME_FAIL_HIBERNATED,
+  MID_BYTES,
+  encodeData,
+  encodeAck,
+  encodePing,
+  encodePong,
+  encodeResumeReq,
+  encodeResumeOk,
+  encodeResumeFail,
+  decode,
+  generateMid,
+  midToHex,
+  frameTypeName,
+} from "./envelope.mjs";
+
+// Pure key helpers (encoding, derivation, fingerprint). The browser side
+// layers IndexedDB-backed persistence over these in web/remote-pairing/keys.js.
+export {
+  IDENTITY_KEY_BYTES,
+  bytesToHex,
+  hexToBytes,
+  generateIdentityKeypair,
+  publicFromPrivate,
+  fingerprintIdentity,
+} from "./keys-core.mjs";
+
+// Application-level RPC framing carried inside the Noise channel. Phone-side
+// rpc-client.js imports these to encode requests / decode responses + events.
+export {
+  RPC,
+  MAX_RPC_ID_LEN,
+  MAX_HEADERS,
+  MAX_HEADER_LEN,
+  MAX_METHOD_LEN,
+  MAX_PATH_LEN,
+  MAX_BODY_BYTES,
+  MAX_TOPIC_LEN,
+  encodeRequest,
+  encodeResponse,
+  encodeCancel,
+  encodeEvent,
+  decode as decodeRpc,
+} from "./rpc.mjs";

package/scripts/lib/remote-pairing/audit.mjs

@@ -0,0 +1,122 @@
+/**
+ * audit.mjs — small local audit log for remote-pairing operations.
+ *
+ * This intentionally stores only human-operational metadata. Relay tokens,
+ * request bodies, channel bindings, and raw phone public keys are never
+ * written here.
+ */
+
+import { randomBytes } from "node:crypto";
+import { promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+export const REMOTE_PAIRING_AUDIT_FILE = path.join(
+  os.homedir(),
+  ".viveworker",
+  "remote-pairing-audit.jsonl",
+);
+
+const MAX_AUDIT_EVENTS = 500;
+const MAX_READ_EVENTS = 100;
+const TYPE_RE = /^[a-z0-9_.:-]{1,64}$/u;
+const OUTCOMES = new Set(["success", "failure", "info"]);
+
+export async function appendRemotePairingAuditEvent(event, {
+  filePath = REMOTE_PAIRING_AUDIT_FILE,
+} = {}) {
+  const record = normalizeAuditEvent(event);
+  const dir = path.dirname(filePath);
+  await fs.mkdir(dir, { recursive: true, mode: 0o700 });
+  await fs.appendFile(filePath, `${JSON.stringify(record)}\n`, { mode: 0o600 });
+  await pruneAuditFile(filePath).catch(() => {});
+  return record;
+}
+
+export async function readRemotePairingAuditEvents({
+  limit = 20,
+  filePath = REMOTE_PAIRING_AUDIT_FILE,
+} = {}) {
+  const safeLimit = Math.max(0, Math.min(Number(limit) || 20, MAX_READ_EVENTS));
+  if (safeLimit === 0) return [];
+
+  let text;
+  try {
+    text = await fs.readFile(filePath, "utf8");
+  } catch (err) {
+    if (err.code === "ENOENT") return [];
+    throw err;
+  }
+
+  const events = [];
+  for (const line of text.split(/\r?\n/u)) {
+    if (!line.trim()) continue;
+    try {
+      events.push(normalizeAuditEvent(JSON.parse(line)));
+    } catch {
+      // Ignore malformed historical lines. The audit log must never break
+      // the settings page.
+    }
+  }
+  return events
+    .sort((a, b) => b.atMs - a.atMs)
+    .slice(0, safeLimit);
+}
+
+function normalizeAuditEvent(event) {
+  const atMs = Number.isFinite(event?.atMs) ? Number(event.atMs) : Date.now();
+  const type = TYPE_RE.test(String(event?.type || ""))
+    ? String(event.type)
+    : "unknown";
+  const outcome = OUTCOMES.has(String(event?.outcome || ""))
+    ? String(event.outcome)
+    : "info";
+
+  const out = {
+    id: cleanText(event?.id, 80) || `${atMs}-${randomBytes(4).toString("hex")}`,
+    atMs,
+    type,
+    outcome,
+  };
+
+  copyText(out, event, "label", 120);
+  copyText(out, event, "phoneFingerprint", 32);
+  copyText(out, event, "deviceId", 120);
+  copyText(out, event, "pairingId", 24);
+  copyText(out, event, "state", 32);
+  copyText(out, event, "previousState", 32);
+  copyText(out, event, "route", 32);
+  copyText(out, event, "reason", 160);
+  copyText(out, event, "relayHost", 120);
+
+  return out;
+}
+
+function copyText(out, event, key, maxLen) {
+  const value = cleanText(event?.[key], maxLen);
+  if (value) out[key] = value;
+}
+
+function cleanText(value, maxLen) {
+  if (typeof value !== "string") return "";
+  return value
+    .replace(/[\r\n\t]+/gu, " ")
+    .replace(/\s{2,}/gu, " ")
+    .trim()
+    .slice(0, maxLen);
+}
+
+async function pruneAuditFile(filePath) {
+  let text;
+  try {
+    text = await fs.readFile(filePath, "utf8");
+  } catch {
+    return;
+  }
+  const lines = text.split(/\r?\n/u).filter((line) => line.trim());
+  if (lines.length <= MAX_AUDIT_EVENTS) return;
+  const kept = lines.slice(-MAX_AUDIT_EVENTS).join("\n") + "\n";
+  const tmpPath = `${filePath}.tmp-${process.pid}-${Date.now()}-${randomBytes(4).toString("hex")}`;
+  await fs.writeFile(tmpPath, kept, { mode: 0o600 });
+  await fs.rename(tmpPath, filePath);
+}