jukto-cli 0.1.0

package/dist/transport/protocol.d.ts

@@ -0,0 +1,77 @@
+export interface Message {
+    v: 1;
+    id: string;
+    ns: string;
+    action: string;
+    payload: Record<string, unknown>;
+}
+export interface Response {
+    v: 1;
+    id: string;
+    ns: string;
+    action: string;
+    ok: boolean;
+    payload: Record<string, unknown>;
+    error?: {
+        code: string;
+        message: string;
+    };
+}
+export interface EventMessage {
+    v: 1;
+    id: string;
+    ns: string;
+    action: string;
+    payload: Record<string, unknown>;
+}
+export interface SystemMessage {
+    type: "connected" | "peer_connected" | "peer_disconnected" | "error" | "app_disconnected" | "close_connection";
+    role?: string;
+    channel?: string;
+    peer?: string;
+    reconnectDeadline?: number;
+    reason?: string;
+    payload?: Record<string, unknown>;
+}
+export type V2HandshakeFrame = {
+    t: "jukto_v2";
+    kind: "client_hello";
+    pubkey: string;
+} | {
+    t: "jukto_v2";
+    kind: "server_hello";
+    pubkey: string;
+} | {
+    t: "jukto_v2";
+    kind: "client_key";
+    nonce: string;
+    box: string;
+    auth: string;
+} | {
+    t: "jukto_v2";
+    kind: "server_ready";
+    auth: string;
+};
+export type EncryptedProtocolEnvelope = {
+    kind: "request";
+    message: Message;
+} | {
+    kind: "response";
+    message: Response;
+} | {
+    kind: "event";
+    message: EventMessage;
+};
+export declare const V2_BINARY_MAGIC_0 = 76;
+export declare const V2_BINARY_MAGIC_1 = 50;
+export declare const V2_FRAME_ENCRYPTED_MESSAGE = 1;
+export declare function isProtocolRequest(value: unknown): value is Message;
+export declare function isProtocolResponse(value: unknown): value is Response;
+export declare function isV2HandshakeFrame(value: unknown): value is V2HandshakeFrame;
+export declare function isEncryptedProtocolEnvelope(value: unknown): value is EncryptedProtocolEnvelope;
+export declare function encodeV2EncryptedFrame(payload: Uint8Array): Uint8Array;
+export declare function decodeV2BinaryFrame(data: Uint8Array): {
+    type: number;
+    payload: Uint8Array;
+} | null;
+export declare function buildSessionV2WsUrl(gatewayUrl: string, role: "cli" | "app", password: string, generation?: number | null): string;

package/dist/transport/protocol.js

@@ -0,0 +1,79 @@
+export const V2_BINARY_MAGIC_0 = 0x4c; // L
+export const V2_BINARY_MAGIC_1 = 0x32; // 2
+export const V2_FRAME_ENCRYPTED_MESSAGE = 0x01;
+export function isProtocolRequest(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const msg = value;
+    return (msg.v === 1 &&
+        typeof msg.id === "string" &&
+        typeof msg.ns === "string" &&
+        typeof msg.action === "string" &&
+        typeof msg.payload === "object" &&
+        msg.payload !== null &&
+        typeof msg.ok === "undefined");
+}
+export function isProtocolResponse(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const msg = value;
+    return msg.v === 1 && typeof msg.id === "string" && typeof msg.ok === "boolean";
+}
+export function isV2HandshakeFrame(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const frame = value;
+    if (frame.t !== "jukto_v2" || typeof frame.kind !== "string")
+        return false;
+    if (frame.kind === "client_hello")
+        return typeof frame.pubkey === "string";
+    if (frame.kind === "server_hello")
+        return typeof frame.pubkey === "string";
+    if (frame.kind === "client_key") {
+        return typeof frame.nonce === "string" && typeof frame.box === "string" && typeof frame.auth === "string";
+    }
+    if (frame.kind === "server_ready")
+        return typeof frame.auth === "string";
+    return false;
+}
+export function isEncryptedProtocolEnvelope(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const envelope = value;
+    if (envelope.kind === "request")
+        return isProtocolRequest(envelope.message);
+    if (envelope.kind === "response")
+        return isProtocolResponse(envelope.message);
+    if (envelope.kind === "event")
+        return isProtocolRequest(envelope.message);
+    return false;
+}
+export function encodeV2EncryptedFrame(payload) {
+    const frame = new Uint8Array(payload.length + 3);
+    frame[0] = V2_BINARY_MAGIC_0;
+    frame[1] = V2_BINARY_MAGIC_1;
+    frame[2] = V2_FRAME_ENCRYPTED_MESSAGE;
+    frame.set(payload, 3);
+    return frame;
+}
+export function decodeV2BinaryFrame(data) {
+    if (data.length < 3)
+        return null;
+    if (data[0] !== V2_BINARY_MAGIC_0 || data[1] !== V2_BINARY_MAGIC_1)
+        return null;
+    return {
+        type: data[2],
+        payload: data.subarray(3),
+    };
+}
+export function buildSessionV2WsUrl(gatewayUrl, role, password, generation) {
+    const wsBase = gatewayUrl.replace(/^https:/, "wss:");
+    if (!wsBase.startsWith("wss://")) {
+        throw new Error("Gateway URL must use https://");
+    }
+    const query = new URLSearchParams({ password });
+    if (typeof generation === "number" && Number.isFinite(generation) && generation > 0) {
+        query.set("generation", String(generation));
+    }
+    return `${wsBase}/v2/ws/${role}?${query.toString()}`;
+}

package/dist/transport/v2.d.ts

@@ -0,0 +1,47 @@
+import type { EventMessage, Message, Response, SystemMessage } from "./protocol.js";
+export interface V2TransportHandlers {
+    onSystemMessage: (message: SystemMessage) => Promise<void> | void;
+    onProtocolRequest: (message: Message) => Promise<Response>;
+    onProtocolResponse?: (message: Response) => Promise<void> | void;
+    onProtocolEvent?: (message: EventMessage) => Promise<void> | void;
+    onClose: (reason: string) => void;
+}
+export interface V2TransportOptions {
+    gatewayUrl: string;
+    password: string;
+    sessionSecret: string;
+    generation?: number | null;
+    role: "cli" | "app";
+    handlers: V2TransportHandlers;
+    debugLog?: (message: string, ...args: unknown[]) => void;
+}
+export declare class V2SessionTransport {
+    private readonly options;
+    private ws;
+    private closed;
+    private state;
+    private keyPair;
+    private remotePublicKey;
+    private sessionKeys;
+    private secureReadyResolve;
+    private secureReadyReject;
+    private secureReadyPromise;
+    constructor(options: V2TransportOptions);
+    connect(): Promise<void>;
+    sendMessage(message: Message): Promise<void>;
+    sendResponse(response: Response): Promise<void>;
+    sendEvent(message: EventMessage): Promise<void>;
+    close(): void;
+    isSecure(): boolean;
+    private handleMessage;
+    private maybeStartHandshake;
+    private handleHandshakeFrame;
+    private encryptEnvelope;
+    private ensureKeyPair;
+    private resetPeerSession;
+    private computeHandshakeAuth;
+    private sendJsonFrame;
+    private sendBinaryFrame;
+    private markSecure;
+    private failSecure;
+}

package/dist/transport/v2.js

@@ -0,0 +1,347 @@
+import { WebSocket } from "ws";
+import { createRequire } from "module";
+import { V2_FRAME_ENCRYPTED_MESSAGE, buildSessionV2WsUrl, decodeV2BinaryFrame, encodeV2EncryptedFrame, isEncryptedProtocolEnvelope, isV2HandshakeFrame, } from "./protocol.js";
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+const require = createRequire(import.meta.url);
+const sodium = require("libsodium-wrappers");
+function toUint8Array(data) {
+    if (data instanceof Uint8Array)
+        return data;
+    if (Array.isArray(data))
+        return new Uint8Array(Buffer.concat(data.map((chunk) => Buffer.from(chunk))));
+    return new Uint8Array(data);
+}
+function encodeUtf8(value) {
+    return encoder.encode(value);
+}
+function decodeUtf8(value) {
+    return decoder.decode(value);
+}
+export class V2SessionTransport {
+    options;
+    ws = null;
+    closed = false;
+    state = "idle";
+    keyPair = null;
+    remotePublicKey = null;
+    sessionKeys = null;
+    secureReadyResolve = null;
+    secureReadyReject = null;
+    secureReadyPromise = null;
+    constructor(options) {
+        this.options = options;
+    }
+    async connect() {
+        if (this.ws && (this.ws.readyState === WebSocket.OPEN || this.ws.readyState === WebSocket.CONNECTING)) {
+            if (this.secureReadyPromise) {
+                return await this.secureReadyPromise;
+            }
+            return;
+        }
+        await sodium.ready;
+        this.secureReadyPromise = new Promise((resolve, reject) => {
+            this.secureReadyResolve = resolve;
+            this.secureReadyReject = reject;
+        });
+        const wsUrl = buildSessionV2WsUrl(this.options.gatewayUrl, this.options.role, this.options.password, this.options.generation);
+        await new Promise((resolve, reject) => {
+            const ws = new WebSocket(wsUrl);
+            let opened = false;
+            this.ws = ws;
+            this.closed = false;
+            this.state = "connecting";
+            ws.on("open", () => {
+                opened = true;
+                this.state = "open";
+                resolve();
+            });
+            ws.on("message", async (data, isBinary) => {
+                try {
+                    await this.handleMessage(data, isBinary);
+                }
+                catch (error) {
+                    this.options.debugLog?.("[transport:v2] message handling failed", error);
+                    this.failSecure(new Error(error instanceof Error ? error.message : String(error)));
+                    this.close();
+                }
+            });
+            ws.on("close", (code, reason) => {
+                this.ws = null;
+                this.state = "closed";
+                if (!opened) {
+                    reject(new Error(`v2 socket closed during setup (${code}: ${reason.toString()})`));
+                    return;
+                }
+                if (!this.closed) {
+                    this.closed = true;
+                    this.failSecure(new Error(`v2 socket closed (${code}: ${reason.toString()})`));
+                    this.options.handlers.onClose(`v2 socket closed (${code}: ${reason.toString()})`);
+                }
+            });
+            ws.on("error", (error) => {
+                if (!opened) {
+                    reject(new Error(`v2 socket error: ${error.message}`));
+                    return;
+                }
+                this.options.debugLog?.("[transport:v2] websocket error", error.message);
+            });
+        });
+        if (!this.secureReadyPromise) {
+            throw new Error("secure readiness promise missing");
+        }
+        await this.secureReadyPromise;
+    }
+    async sendMessage(message) {
+        const ciphertext = this.encryptEnvelope({ kind: "request", message });
+        this.sendBinaryFrame(ciphertext);
+    }
+    async sendResponse(response) {
+        const ciphertext = this.encryptEnvelope({ kind: "response", message: response });
+        this.sendBinaryFrame(ciphertext);
+    }
+    async sendEvent(message) {
+        const ciphertext = this.encryptEnvelope({ kind: "event", message });
+        this.sendBinaryFrame(ciphertext);
+    }
+    close() {
+        this.closed = true;
+        this.state = "closed";
+        if (!this.ws)
+            return;
+        if (this.ws.readyState === WebSocket.OPEN || this.ws.readyState === WebSocket.CONNECTING) {
+            this.ws.close();
+        }
+        this.ws = null;
+    }
+    isSecure() {
+        return this.state === "secure";
+    }
+    async handleMessage(data, isBinary) {
+        if (!isBinary) {
+            const text = typeof data === "string" ? data : Buffer.from(data).toString("utf-8");
+            const raw = JSON.parse(text);
+            if ("type" in raw) {
+                await this.options.handlers.onSystemMessage(raw);
+                if (raw.type === "peer_connected") {
+                    this.resetPeerSession();
+                    await this.maybeStartHandshake();
+                }
+                else if (raw.type === "peer_disconnected" || raw.type === "app_disconnected") {
+                    this.resetPeerSession();
+                }
+                return;
+            }
+            if (isV2HandshakeFrame(raw)) {
+                await this.handleHandshakeFrame(raw);
+                return;
+            }
+            throw new Error(this.state === "secure"
+                ? "received plaintext app message after secure transport"
+                : "received plaintext app message before secure transport");
+        }
+        const bytes = toUint8Array(data);
+        const frame = decodeV2BinaryFrame(bytes);
+        if (!frame) {
+            throw new Error("invalid binary v2 frame");
+        }
+        if (frame.type !== V2_FRAME_ENCRYPTED_MESSAGE) {
+            throw new Error(`unsupported v2 frame type ${frame.type}`);
+        }
+        if (this.state !== "secure" || !this.sessionKeys) {
+            throw new Error("received encrypted frame before secure transport");
+        }
+        if (frame.payload.length < sodium.crypto_aead_xchacha20poly1305_ietf_NPUBBYTES) {
+            throw new Error("encrypted frame missing nonce");
+        }
+        const nonce = frame.payload.subarray(0, sodium.crypto_aead_xchacha20poly1305_ietf_NPUBBYTES);
+        const ciphertext = frame.payload.subarray(sodium.crypto_aead_xchacha20poly1305_ietf_NPUBBYTES);
+        const plaintext = sodium.crypto_aead_xchacha20poly1305_ietf_decrypt(null, ciphertext, null, nonce, this.sessionKeys.rx);
+        const parsed = JSON.parse(decodeUtf8(plaintext));
+        if (!isEncryptedProtocolEnvelope(parsed)) {
+            throw new Error("invalid decrypted protocol envelope");
+        }
+        if (parsed.kind === "response") {
+            await this.options.handlers.onProtocolResponse?.(parsed.message);
+            return;
+        }
+        if (parsed.kind === "event") {
+            await this.options.handlers.onProtocolEvent?.(parsed.message);
+            return;
+        }
+        if (parsed.kind === "request") {
+            const response = await this.options.handlers.onProtocolRequest(parsed.message);
+            await this.sendResponse(response);
+            return;
+        }
+        throw new Error("invalid decrypted protocol envelope");
+    }
+    async maybeStartHandshake() {
+        if (this.state === "secure" || this.state === "handshaking")
+            return;
+        if (this.options.role !== "app")
+            return;
+        this.state = "handshaking";
+        const keyPair = this.ensureKeyPair();
+        const hello = {
+            t: "jukto_v2",
+            kind: "client_hello",
+            pubkey: sodium.to_base64(keyPair.publicKey, sodium.base64_variants.URLSAFE_NO_PADDING),
+        };
+        this.sendJsonFrame(hello);
+    }
+    async handleHandshakeFrame(frame) {
+        this.state = "handshaking";
+        if (frame.kind === "client_hello") {
+            if (this.options.role !== "cli") {
+                throw new Error("unexpected client_hello on app transport");
+            }
+            this.remotePublicKey = sodium.from_base64(frame.pubkey, sodium.base64_variants.URLSAFE_NO_PADDING);
+            const keyPair = this.ensureKeyPair();
+            this.sendJsonFrame({
+                t: "jukto_v2",
+                kind: "server_hello",
+                pubkey: sodium.to_base64(keyPair.publicKey, sodium.base64_variants.URLSAFE_NO_PADDING),
+            });
+            return;
+        }
+        if (frame.kind === "server_hello") {
+            if (this.options.role !== "app") {
+                throw new Error("unexpected server_hello on cli transport");
+            }
+            this.remotePublicKey = sodium.from_base64(frame.pubkey, sodium.base64_variants.URLSAFE_NO_PADDING);
+            const keyPair = this.ensureKeyPair();
+            const c2sKey = sodium.crypto_aead_xchacha20poly1305_ietf_keygen();
+            const s2cKey = sodium.crypto_aead_xchacha20poly1305_ietf_keygen();
+            const nonce = sodium.randombytes_buf(sodium.crypto_box_NONCEBYTES);
+            const payload = {
+                c2s: sodium.to_base64(c2sKey, sodium.base64_variants.URLSAFE_NO_PADDING),
+                s2c: sodium.to_base64(s2cKey, sodium.base64_variants.URLSAFE_NO_PADDING),
+            };
+            const boxed = sodium.crypto_box_easy(encodeUtf8(JSON.stringify(payload)), nonce, this.remotePublicKey, keyPair.privateKey);
+            const auth = this.computeHandshakeAuth("client_key", "app", sodium.to_base64(keyPair.publicKey, sodium.base64_variants.URLSAFE_NO_PADDING), nonce, boxed);
+            this.sessionKeys = { rx: s2cKey, tx: c2sKey };
+            this.sendJsonFrame({
+                t: "jukto_v2",
+                kind: "client_key",
+                nonce: sodium.to_base64(nonce, sodium.base64_variants.URLSAFE_NO_PADDING),
+                box: sodium.to_base64(boxed, sodium.base64_variants.URLSAFE_NO_PADDING),
+                auth,
+            });
+            return;
+        }
+        if (frame.kind === "client_key") {
+            if (this.options.role !== "cli") {
+                throw new Error("unexpected client_key on app transport");
+            }
+            if (!this.remotePublicKey) {
+                throw new Error("missing client public key before client_key");
+            }
+            const keyPair = this.ensureKeyPair();
+            const nonce = sodium.from_base64(frame.nonce, sodium.base64_variants.URLSAFE_NO_PADDING);
+            const boxed = sodium.from_base64(frame.box, sodium.base64_variants.URLSAFE_NO_PADDING);
+            const expectedAuth = this.computeHandshakeAuth("client_key", "app", sodium.to_base64(this.remotePublicKey, sodium.base64_variants.URLSAFE_NO_PADDING), nonce, boxed);
+            if (frame.auth !== expectedAuth) {
+                throw new Error("client_key authentication failed");
+            }
+            const opened = sodium.crypto_box_open_easy(boxed, nonce, this.remotePublicKey, keyPair.privateKey);
+            const payload = JSON.parse(decodeUtf8(opened));
+            this.sessionKeys = {
+                rx: sodium.from_base64(payload.c2s, sodium.base64_variants.URLSAFE_NO_PADDING),
+                tx: sodium.from_base64(payload.s2c, sodium.base64_variants.URLSAFE_NO_PADDING),
+            };
+            const auth = this.computeHandshakeAuth("server_ready", "cli", sodium.to_base64(keyPair.publicKey, sodium.base64_variants.URLSAFE_NO_PADDING));
+            this.sendJsonFrame({
+                t: "jukto_v2",
+                kind: "server_ready",
+                auth,
+            });
+            this.markSecure();
+            return;
+        }
+        if (frame.kind === "server_ready") {
+            if (this.options.role !== "app") {
+                throw new Error("unexpected server_ready on cli transport");
+            }
+            if (!this.sessionKeys) {
+                throw new Error("missing session keys before server_ready");
+            }
+            const expectedAuth = this.computeHandshakeAuth("server_ready", "cli", sodium.to_base64(this.remotePublicKey, sodium.base64_variants.URLSAFE_NO_PADDING));
+            if (frame.auth !== expectedAuth) {
+                throw new Error("server_ready authentication failed");
+            }
+            this.markSecure();
+        }
+    }
+    encryptEnvelope(envelope) {
+        if (this.state !== "secure" || !this.sessionKeys) {
+            throw new Error("secure transport is not active");
+        }
+        const nonce = sodium.randombytes_buf(sodium.crypto_aead_xchacha20poly1305_ietf_NPUBBYTES);
+        const ciphertext = sodium.crypto_aead_xchacha20poly1305_ietf_encrypt(encodeUtf8(JSON.stringify(envelope)), null, null, nonce, this.sessionKeys.tx);
+        const payload = new Uint8Array(nonce.length + ciphertext.length);
+        payload.set(nonce, 0);
+        payload.set(ciphertext, nonce.length);
+        return payload;
+    }
+    ensureKeyPair() {
+        if (this.keyPair)
+            return this.keyPair;
+        const pair = sodium.crypto_box_keypair();
+        this.keyPair = {
+            publicKey: pair.publicKey,
+            privateKey: pair.privateKey,
+        };
+        return this.keyPair;
+    }
+    resetPeerSession() {
+        this.remotePublicKey = null;
+        this.sessionKeys = null;
+        if (this.ws?.readyState === WebSocket.OPEN) {
+            this.state = "open";
+        }
+        else {
+            this.state = "idle";
+        }
+    }
+    computeHandshakeAuth(phase, senderRole, peerPubkeyB64, nonce, boxed) {
+        const authKey = sodium.crypto_generichash(sodium.crypto_auth_KEYBYTES, encodeUtf8(this.options.sessionSecret), undefined);
+        const parts = [
+            phase,
+            senderRole,
+            peerPubkeyB64,
+            nonce ? sodium.to_base64(nonce, sodium.base64_variants.URLSAFE_NO_PADDING) : "",
+            boxed ? sodium.to_base64(boxed, sodium.base64_variants.URLSAFE_NO_PADDING) : "",
+        ];
+        const tag = sodium.crypto_auth(parts.join(":"), authKey);
+        return sodium.to_base64(tag, sodium.base64_variants.URLSAFE_NO_PADDING);
+    }
+    sendJsonFrame(frame) {
+        if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+            throw new Error("v2 transport is not connected");
+        }
+        this.ws.send(JSON.stringify(frame));
+    }
+    sendBinaryFrame(ciphertext) {
+        if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+            throw new Error("v2 transport is not connected");
+        }
+        const framed = encodeV2EncryptedFrame(ciphertext);
+        this.ws.send(framed);
+    }
+    markSecure() {
+        this.state = "secure";
+        if (this.secureReadyResolve) {
+            this.secureReadyResolve();
+            this.secureReadyResolve = null;
+            this.secureReadyReject = null;
+        }
+    }
+    failSecure(error) {
+        if (this.secureReadyReject) {
+            this.secureReadyReject(error);
+            this.secureReadyResolve = null;
+            this.secureReadyReject = null;
+        }
+    }
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "jukto-cli",
+  "version": "0.1.0",
+  "author": {
+    "name": "Saif Ahmed",
+    "email": "codingwebsa@gmail.com",
+    "username": "ahm0xc"
+  },
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "jukto-cli": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "bin"
+  ],
+  "scripts": {
+    "build": "tsc && npm run prepare-bin",
+    "dev": "tsc && node dist/index.js",
+    "prepare-bin": "node -e \"require('fs').chmodSync('dist/index.js', 0o755)\"",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@opencode-ai/sdk": "1.3.15",
+    "ignore": "^6.0.2",
+    "libsodium-wrappers": "^0.7.15",
+    "qrcode-terminal": "^0.12.0",
+    "shelljs": "^0.10.0",
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@types/minimatch": "^5.1.2",
+    "@types/node": "^20.0.0",
+    "@types/qrcode-terminal": "^0.12.2",
+    "@types/shelljs": "^0.10.0",
+    "@types/ws": "^8.5.13",
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}