@oharness/server 0.9.2 → 0.10.0

package/dist/remote-crypto.js

@@ -0,0 +1,216 @@
+import { createHash, createCipheriv, createDecipheriv, createPrivateKey, createPublicKey, diffieHellman, generateKeyPairSync, hkdfSync, sign, verify, } from "node:crypto";
+/**
+ * The cryptography of remote control, Mac side. The phone's half is
+ * HarnessKit's `RemoteCrypto.swift`, and the two must agree byte for byte.
+ *
+ * Every channel starts with a handshake that the relay forwards and cannot
+ * take part in:
+ *
+ *   phone → mac   {hs:"hello", v:1, device:{id,name}, identity, eph}
+ *   mac → phone   {hs:"welcome", identity, eph, sig}      sig = Ed25519_mac(T)
+ *   phone → mac   {hs:"proof", sig}                       sig = Ed25519_phone(T)
+ *
+ * `identity` is the side's long-term Ed25519 public key and `eph` a fresh
+ * X25519 public key, each as 32 raw bytes in base64. The transcript is
+ *
+ *   T = SHA-256("oharness-remote-v1" ‖ 0x00 ‖ channel ‖ 0x00 ‖
+ *               phoneIdentity ‖ phoneEph ‖ macIdentity ‖ macEph)
+ *
+ * which binds both identities, both ephemeral keys and this channel. Each
+ * direction gets its own AES-256-GCM key:
+ *
+ *   key = HKDF-SHA256(ikm = X25519(eph, eph'), salt = T, info = "oharness phone->mac" | "oharness mac->phone")
+ *
+ * and every sealed frame is `s.` + base64url(counter₈ ‖ ciphertext ‖ tag₁₆),
+ * nonce = 0x00000000 ‖ counter₈. Counters start at 0 and must arrive in
+ * order: the relay is one ordered socket, so anything else is a replay or a
+ * drop, and either way the channel is closed.
+ *
+ * The pairing code both screens show is the first four bytes of
+ * SHA-256("oharness-remote-sas" ‖ T), big-endian, mod 1 000 000, six digits.
+ * A relay that put itself in the middle would hold two different
+ * transcripts, so the two screens would show two different codes.
+ */
+const TRANSCRIPT_LABEL = "oharness-remote-v1";
+const SAS_LABEL = "oharness-remote-sas";
+const INFO_PHONE_TO_MAC = "oharness phone->mac";
+const INFO_MAC_TO_PHONE = "oharness mac->phone";
+export function b64(bytes) {
+    return Buffer.from(bytes).toString("base64");
+}
+export function unb64(text, length) {
+    if (typeof text !== "string")
+        throw new Error("expected base64");
+    const bytes = Buffer.from(text, "base64");
+    if (length !== undefined && bytes.length !== length)
+        throw new Error(`expected ${length} bytes`);
+    return bytes;
+}
+export function newIdentity() {
+    const { privateKey } = generateKeyPairSync("ed25519");
+    const pkcs8 = privateKey.export({ format: "der", type: "pkcs8" }).toString("base64");
+    return { identity: loadIdentity(pkcs8), pkcs8 };
+}
+export function loadIdentity(pkcs8) {
+    const privateKey = createPrivateKey({ key: Buffer.from(pkcs8, "base64"), format: "der", type: "pkcs8" });
+    return { privateKey, publicRaw: rawPublic(createPublicKey(privateKey)) };
+}
+function rawPublic(key) {
+    const jwk = key.export({ format: "jwk" });
+    if (typeof jwk.x !== "string")
+        throw new Error("not an OKP key");
+    return Buffer.from(jwk.x, "base64url");
+}
+function okpPublic(raw, crv) {
+    return createPublicKey({ key: { kty: "OKP", crv, x: raw.toString("base64url") }, format: "jwk" });
+}
+export function transcript(channel, phoneIdentity, phoneEph, macIdentity, macEph) {
+    return createHash("sha256")
+        .update(TRANSCRIPT_LABEL)
+        .update(Buffer.from([0]))
+        .update(channel)
+        .update(Buffer.from([0]))
+        .update(phoneIdentity)
+        .update(phoneEph)
+        .update(macIdentity)
+        .update(macEph)
+        .digest();
+}
+export function pairingCode(t) {
+    const digest = createHash("sha256").update(SAS_LABEL).update(t).digest();
+    return String(digest.readUInt32BE(0) % 1_000_000).padStart(6, "0");
+}
+/** One direction's key and counter. */
+class Direction {
+    counter = 0n;
+    key;
+    constructor(key) {
+        this.key = key;
+    }
+    seal(plaintext) {
+        const counter = Buffer.alloc(8);
+        counter.writeBigUInt64BE(this.counter++);
+        const cipher = createCipheriv("aes-256-gcm", this.key, Buffer.concat([Buffer.alloc(4), counter]));
+        const body = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final(), cipher.getAuthTag()]);
+        return "s." + Buffer.concat([counter, body]).toString("base64url");
+    }
+    open(frame) {
+        if (!frame.startsWith("s."))
+            throw new Error("expected a sealed frame");
+        const bytes = Buffer.from(frame.slice(2), "base64url");
+        if (bytes.length < 8 + 16)
+            throw new Error("sealed frame too short");
+        const counter = bytes.readBigUInt64BE(0);
+        if (counter !== this.counter)
+            throw new Error("sealed frame out of order");
+        const decipher = createDecipheriv("aes-256-gcm", this.key, Buffer.concat([Buffer.alloc(4), bytes.subarray(0, 8)]));
+        decipher.setAuthTag(bytes.subarray(bytes.length - 16));
+        const plaintext = Buffer.concat([decipher.update(bytes.subarray(8, bytes.length - 16)), decipher.final()]).toString("utf8");
+        this.counter++;
+        return plaintext;
+    }
+}
+export function readHello(message) {
+    if (message["hs"] !== "hello" || message["v"] !== 1)
+        throw new Error("expected a v1 hello");
+    const device = message["device"];
+    if (!device || typeof device.id !== "string" || !/^[A-Za-z0-9_-]{8,64}$/.test(device.id))
+        throw new Error("hello without a device id");
+    const name = typeof device.name === "string" && device.name.trim() ? device.name.trim().slice(0, 80) : device.id;
+    return { device: { id: device.id, name }, identity: unb64(message["identity"], 32), eph: unb64(message["eph"], 32) };
+}
+/**
+ * The Mac's side of one channel's handshake: answer the hello, then check the
+ * proof. `welcome()` is sent as plaintext; after `accept()` every frame is sealed.
+ */
+export class MacHandshake {
+    transcript;
+    code;
+    sendKey;
+    receiveKey;
+    welcomeFrame;
+    hello;
+    constructor(channel, hello, identity) {
+        this.hello = hello;
+        const { privateKey: ephPrivate, publicKey: ephPublic } = generateKeyPairSync("x25519");
+        const macEph = rawPublic(ephPublic);
+        this.transcript = transcript(channel, hello.identity, hello.eph, identity.publicRaw, macEph);
+        this.code = pairingCode(this.transcript);
+        const shared = diffieHellman({ privateKey: ephPrivate, publicKey: okpPublic(hello.eph, "X25519") });
+        this.receiveKey = Buffer.from(hkdfSync("sha256", shared, this.transcript, INFO_PHONE_TO_MAC, 32));
+        this.sendKey = Buffer.from(hkdfSync("sha256", shared, this.transcript, INFO_MAC_TO_PHONE, 32));
+        this.welcomeFrame = {
+            hs: "welcome",
+            identity: b64(identity.publicRaw),
+            eph: b64(macEph),
+            sig: b64(sign(null, this.transcript, identity.privateKey)),
+        };
+    }
+    welcome() {
+        return this.welcomeFrame;
+    }
+    /** Checks the phone's proof; on success, the sealed session for this channel. */
+    accept(message) {
+        if (message["hs"] !== "proof")
+            throw new Error("expected the proof");
+        const ok = verify(null, this.transcript, okpPublic(this.hello.identity, "Ed25519"), unb64(message["sig"], 64));
+        if (!ok)
+            throw new Error("the phone's proof does not verify");
+        return new SealedSession(new Direction(this.sendKey), new Direction(this.receiveKey));
+    }
+}
+export class SealedSession {
+    outgoing;
+    incoming;
+    constructor(outgoing, incoming) {
+        this.outgoing = outgoing;
+        this.incoming = incoming;
+    }
+    seal(message) {
+        return this.outgoing.seal(JSON.stringify(message));
+    }
+    open(frame) {
+        const value = JSON.parse(this.incoming.open(frame));
+        if (!value || typeof value !== "object" || Array.isArray(value))
+            throw new Error("sealed frame is not an object");
+        return value;
+    }
+}
+// ---- The phone's half, in TypeScript: used by tests, and by anything that
+// ---- wants to drive a Mac from Node. It mirrors RemoteCrypto.swift.
+export class PhoneHandshake {
+    eph = generateKeyPairSync("x25519");
+    ephRaw = rawPublic(this.eph.publicKey);
+    channel;
+    device;
+    identity;
+    constructor(channel, device, identity) {
+        this.channel = channel;
+        this.device = device;
+        this.identity = identity;
+    }
+    hello() {
+        return { hs: "hello", v: 1, device: this.device, identity: b64(this.identity.publicRaw), eph: b64(this.ephRaw) };
+    }
+    /** Verifies the welcome and returns the proof to send, the code, and the sealed session. */
+    finish(welcome) {
+        if (welcome["hs"] !== "welcome")
+            throw new Error("expected the welcome");
+        const macIdentity = unb64(welcome["identity"], 32);
+        const macEph = unb64(welcome["eph"], 32);
+        const t = transcript(this.channel, this.identity.publicRaw, this.ephRaw, macIdentity, macEph);
+        if (!verify(null, t, okpPublic(macIdentity, "Ed25519"), unb64(welcome["sig"], 64))) {
+            throw new Error("the Mac's signature does not verify");
+        }
+        const shared = diffieHellman({ privateKey: this.eph.privateKey, publicKey: okpPublic(macEph, "X25519") });
+        const send = Buffer.from(hkdfSync("sha256", shared, t, INFO_PHONE_TO_MAC, 32));
+        const receive = Buffer.from(hkdfSync("sha256", shared, t, INFO_MAC_TO_PHONE, 32));
+        return {
+            proof: { hs: "proof", sig: b64(sign(null, t, this.identity.privateKey)) },
+            code: pairingCode(t),
+            macIdentity,
+            session: new SealedSession(new Direction(send), new Direction(receive)),
+        };
+    }
+}
+//# sourceMappingURL=remote-crypto.js.map

package/dist/remote-crypto.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote-crypto.js","sourceRoot":"","sources":["../src/remote-crypto.ts"],"names":[],"mappings":"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"}

package/dist/remote.d.ts

@@ -0,0 +1,103 @@
+import { type Identity } from "./remote-crypto.ts";
+/**
+ * Remote control: this machine, reachable from a phone through the relay.
+ *
+ * The Mac dials out — it never listens on anything but loopback — and holds
+ * one WebSocket to the relay while remote is on. A phone on the same account
+ * opens a channel to it; each request that arrives on the channel is replayed
+ * against this process's own HTTP server, so the phone speaks exactly the
+ * routes the page speaks and there is no second API to keep in step.
+ *
+ * A channel is useless until its handshake (remote-crypto.ts) finishes: the
+ * phone proves which device it is, the Mac proves it is this Mac, and every
+ * frame after that is sealed end to end. A phone this Mac has not seen before
+ * is then held until someone at the Mac allows it — the same account is what
+ * gets a phone to the door, and the Allow is what opens it. Both screens show
+ * a six-digit code derived from the handshake, so a relay that put itself in
+ * the middle would be caught by two codes that disagree.
+ *
+ * Once a channel is ready, inside each sealed frame:
+ *
+ *   ← {pair: "ok"} | {pair: "pending", code} | {pair: "denied"}
+ *   → {id, method, path, query?, body?}    ← {id, status, body}
+ *   → {id, subscribe: "/events"}           ← {sub: id, event} …  ← {sub: id, end: true}
+ *   → {id, unsubscribe: <sub id>}          ← {id, status: 200, body: {ok: true}}
+ */
+/**
+ * What a phone may ask for. Chat and its controls, read-only views of what the
+ * agent produced — not the terminal, the browser, the file system, settings,
+ * sign-in or computer use. A route not here is refused before anything runs.
+ */
+export declare const REMOTE_ROUTES: ReadonlySet<string>;
+/** The relay a Mac dials when nothing names another. */
+export declare const DEFAULT_RELAY = "wss://relay.oharness.ai/v1/connect";
+/**
+ * Where remote control connects, and whether this run is told to use it
+ * whatever the setting says.
+ *
+ * OHARNESS_REMOTE_RELAY names another relay for development (a local one is
+ * `ws://127.0.0.1:4490/v1/connect`) and, as it did before there was a switch,
+ * turns remote on by itself. Without it the relay is ours and the switch in
+ * Settings decides.
+ */
+export declare function remoteRelay(env?: NodeJS.ProcessEnv): {
+    relay: string;
+    always: boolean;
+};
+export interface RemoteMachine {
+    id: string;
+    name: string;
+}
+export interface RemoteOptions {
+    /** The relay's WebSocket endpoint, `wss://…/v1/connect` (or ws:// on loopback). */
+    relay: string;
+    /** The account token to present; asked again on every reconnect, since it expires. */
+    token: () => Promise<string | undefined>;
+    machine: RemoteMachine;
+    /** This Mac's long-term identity, from `remoteMachine()`. */
+    identity: Identity;
+    /** This process's own server, as `startWebServer` reports it (its URL carries the token). */
+    local: string;
+    /**
+     * Asks the person at the Mac whether a new phone may connect. Settles false
+     * when the signal aborts (the phone gave up), and is never asked about a
+     * phone that is already paired.
+     */
+    approve: (request: PairingRequest, signal: AbortSignal) => Promise<boolean>;
+    /** Told when an approval is no longer wanted, so its card can close. */
+    withdrawn?: (id: string) => void;
+    log?: (line: string) => void;
+}
+export interface RemoteHandle {
+    readonly connected: boolean;
+    /** Ends every channel a phone holds open, once it has been forgotten. */
+    forget(deviceId: string): void;
+    close(): void;
+}
+/** A phone this Mac has allowed. */
+export interface PairedDevice {
+    id: string;
+    name: string;
+    /** The phone's Ed25519 identity, base64 of 32 raw bytes. */
+    publicKey: string;
+    pairedAt: number;
+}
+/**
+ * This Mac's id and identity for remote control, made on first use and kept
+ * in ~/.oharness/remote.json. The identity is what a phone pins: replacing it
+ * makes every paired phone refuse this Mac until it is paired again.
+ */
+export declare function remoteMachine(): Promise<{
+    machine: RemoteMachine;
+    identity: Identity;
+}>;
+export declare function pairedDevices(): Promise<PairedDevice[]>;
+export declare function revokeDevice(id: string): Promise<boolean>;
+/** A phone waiting at the door, as the Mac's page is asked about it. */
+export interface PairingRequest {
+    /** The channel id, which is also how the answer finds its way back. */
+    id: string;
+    device: RemoteMachine;
+    code: string;
+}
+export declare function startRemote(options: RemoteOptions): RemoteHandle;