@whyvix/remote 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,31 @@
-# Temporary Holding Version
+# WHYVIX Remote
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+WHYVIX Remote is an IDE-independent remote development bridge designed as a consumer ChatGPT Plugin/App product.
+
+## Product direction — LOCKED
+
+The target consumer experience is: install WHYVIX Remote from ChatGPT Plugins -> Connect -> OAuth WHYVIX -> use only devices authorized to that WHYVIX identity. The consumer must not configure a custom MCP server, MCP URL, Developer Mode, or MCP bearer token.
+
+MCP is an internal backend integration layer for the WHYVIX ChatGPT App. See `docs/R9_PRODUCT_ARCHITECTURE.md` before implementing R9 or later product integration work.
+
+## Certified foundation
+
+R0-R6 provide the local transport/tool foundation. R7 adds control/reconnect certification. R8-B is the deployed/frozen public transport baseline at `d140da7`: WSS agent connectivity, loopback-only control/public services, TLS public API routing, and stable reconnect/device identity.
+
+The local commit `f639056` contains an experimental read-only MCP adapter. It is intentionally NOT DEPLOYED and must not be treated as the final consumer authentication architecture.
+
+## Local agent UX
+
+Current development entry point: `node packages/cli/index.js remote`.
+Intended published consumer command: `npx @whyvix/remote@latest remote`.
+The published CLI must perform WHYVIX login/device pairing and establish an outbound persistent connection; it must not require an inbound port on the consumer PC.
+
+## R9 direction
+
+R9 implementation order is identity/OAuth -> device pairing -> per-user device isolation -> authenticated App/MCP tool contract -> consumer CLI UX -> ChatGPT Plugin/App integration -> end-to-end acceptance -> submission readiness.
+
+R9 is IN PROGRESS. An MCP endpoint responding is not sufficient for GREEN. Consumer Plugin/App installation, OAuth, user/device isolation, revocation, remote tool execution, and no-custom-MCP setup are acceptance requirements.
+
+## Engineering rules
+
+Preserve certified R8-B behavior. Do not expose control port 8788 or raw agent ports publicly. Do not use global device enumeration as authorization. Do not make possession of a device ID sufficient for access. Static shared bearer credentials are infrastructure/MVP artifacts, not the production consumer identity model.

package/package.json

@@ -1,6 +1,30 @@
 {
   "name": "@whyvix/remote",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "files": [
+    "packages/agent/src",
+    "packages/cli/index.js",
+    "packages/protocol/src",
+    "README.md"
+  ],
+  "scripts": {
+    "gateway": "node services/gateway/src/index.js",
+    "agent": "node packages/agent/src/index.js",
+    "test:r0": "node scripts/r0-test.js",
+    "test": "npm run test:r0 && npm run test:r1-r2 && npm run test:r3-r5",
+    "check": "node --check packages/protocol/src/index.js && node --check packages/agent/src/security.js && node --check packages/agent/src/process-manager.js && node --check packages/agent/src/tools.js && node --check packages/agent/src/agent.js && node --check packages/agent/src/index.js && node --check packages/cli/index.js && node --check services/gateway/src/device-registry.js && node --check services/gateway/src/gateway.js && node --check services/gateway/src/index.js && node --check scripts/r0-test.js && node --check scripts/r1-r2-test.js && node --check scripts/r3-r5-test.js",
+    "test:r1-r2": "node scripts/r1-r2-test.js",
+    "test:r3-r5": "node scripts/r3-r5-test.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/ext-apps": "^2.0.0",
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "ws": "^8.18.0",
+    "zod": "^4.6.5"
+  },
+  "bin": {
+    "whyvix-remote": "packages/cli/index.js"
+  }
+}

package/packages/agent/src/agent.js

@@ -0,0 +1,32 @@
+import os from "node:os";
+import { randomUUID } from "node:crypto";
+import WebSocket from "ws";
+import { envelope, parseMessage, TYPES } from "../../protocol/src/index.js";
+import { createSecurity } from "./security.js";
+import { ProcessManager } from "./process-manager.js";
+import { createToolExecutor } from "./tools.js";
+
+export function createAgent({gatewayUrl="ws://127.0.0.1:8787",deviceId=randomUUID(),deviceName=os.hostname(),token="",workspaces=[process.cwd()],reconnectMs=1000,reconnect=true,audit=()=>{}}={}) {
+  let ws=null,reconnectTimer=null,stopped=false,generation=0;
+  const security=createSecurity({token,workspaces,audit});
+  const processManager=new ProcessManager({audit});
+  const executeTool=createToolExecutor({security,processManager});
+  function scheduleReconnect(reason){
+    if(stopped||!reconnect||reconnectTimer)return;
+    console.log("[agent:reconnect-scheduled]",reason,reconnectMs);
+    reconnectTimer=setTimeout(()=>{reconnectTimer=null;connect();},reconnectMs);
+  }
+  function connect(){
+    if(stopped)return;
+    clearTimeout(reconnectTimer); reconnectTimer=null;
+    const current=++generation;
+    const socket=new WebSocket(gatewayUrl); ws=socket;
+    console.log("[agent:connecting]",gatewayUrl,"generation="+current);
+    socket.on("open",()=>{if(ws!==socket)return;console.log("[agent:connected]",gatewayUrl);socket.send(JSON.stringify(envelope(TYPES.REGISTER,{auth:{token},device:{id:deviceId,name:deviceName,platform:process.platform,agentVersion:"0.3.0"}})));});
+    socket.on("message",async(raw)=>{if(ws!==socket)return;try{const m=parseMessage(raw);if(m.type===TYPES.REGISTERED){console.log("[agent:registered]",m.deviceId);if(m.authorizedAccount)console.log("Authorized:",m.authorizedAccount);return;}if(m.type!==TYPES.REQUEST)return;try{const result=await executeTool(m.tool,m.arguments);if(m.tool==="device.ping")Object.assign(result,{deviceId,deviceName});if(socket.readyState===WebSocket.OPEN)socket.send(JSON.stringify(envelope(TYPES.RESPONSE,{requestId:m.requestId,result})));}catch(error){if(socket.readyState===WebSocket.OPEN)socket.send(JSON.stringify(envelope(TYPES.ERROR,{requestId:m.requestId,error:{code:error.code||"TOOL_ERROR",message:error.message}})));}}catch(error){console.error("[agent:protocol-error]",error.message);}});
+    socket.on("close",(code)=>{console.log("[agent:disconnected]","generation="+current,"code="+code);if(ws===socket)ws=null;if(code===1008){console.error("[agent:authorization-required] device credential rejected");return;}if(code===4001){console.error("[agent:replaced] newer WHYVIX Remote connection is active");return;}scheduleReconnect("close");});
+    socket.on("error",(e)=>{console.error("[agent:socket-error]",e.message);scheduleReconnect("error");});
+  }
+  async function stop(){stopped=true;clearTimeout(reconnectTimer);reconnectTimer=null;const socket=ws;ws=null;if(socket&&socket.readyState<WebSocket.CLOSING)await new Promise(r=>{socket.once("close",r);socket.close();});}
+  connect(); return{deviceId,deviceName,stop};
+}

package/packages/agent/src/identity.js

@@ -0,0 +1,6 @@
+import os from "node:os";
+import crypto from "node:crypto";
+
+export function stableDeviceId({ hostname = os.hostname(), username = os.userInfo().username } = {}) {
+  return crypto.createHash("sha256").update(hostname + "|" + username).digest("hex").slice(0, 24);
+}

package/packages/agent/src/index.js

@@ -0,0 +1,15 @@
+import { createAgent } from "./agent.js";
+import { stableDeviceId } from "./identity.js";
+
+const workspaces=(process.env.WHYVIX_WORKSPACES||process.cwd()).split(";").filter(Boolean);
+const agent=createAgent({
+  gatewayUrl:process.env.WHYVIX_GATEWAY_URL||"ws://127.0.0.1:8787",
+  deviceId:process.env.WHYVIX_DEVICE_ID||stableDeviceId(),
+  deviceName:process.env.WHYVIX_DEVICE_NAME,
+  token:process.env.WHYVIX_DEVICE_TOKEN||"",
+  workspaces,
+  audit:(e)=>console.log("[audit]",JSON.stringify(e))
+});
+async function shutdown(){await agent.stop();process.exit(0);}
+process.on("SIGINT",shutdown);
+process.on("SIGTERM",shutdown);

package/packages/agent/src/process-manager.js

@@ -0,0 +1,19 @@
+import { spawn } from "node:child_process";
+
+export class ProcessManager {
+  constructor({ audit = () => {} } = {}) { this.audit=audit; this.processes=new Map(); this.nextId=1; }
+  start({ command, args = [], cwd, timeoutMs = 30000 }) {
+    if (!command) throw Object.assign(new Error("command is required"), { code:"INVALID_ARGUMENT" });
+    const id=String(this.nextId++);
+    const child=spawn(command,args,{cwd,windowsHide:true,shell:false});
+    const state={ id, command, args, cwd, stdout:"", stderr:"", exitCode:null, running:true, child };
+    this.processes.set(id,state); this.audit({event:"process.start",id,command,cwd});
+    child.stdout?.on("data",(x)=>state.stdout+=x.toString());
+    child.stderr?.on("data",(x)=>state.stderr+=x.toString());
+    child.on("close",(code)=>{state.exitCode=code;state.running=false;this.audit({event:"process.exit",id,code});});
+    if(timeoutMs>0) setTimeout(()=>{if(state.running) child.kill();},Math.min(timeoutMs,300000)).unref();
+    return {id,pid:child.pid};
+  }
+  output({id}) { const s=this.processes.get(String(id)); if(!s) throw Object.assign(new Error("Process not found"),{code:"PROCESS_NOT_FOUND"}); return {id:s.id,stdout:s.stdout,stderr:s.stderr,running:s.running,exitCode:s.exitCode}; }
+  stop({id}) { const s=this.processes.get(String(id)); if(!s) throw Object.assign(new Error("Process not found"),{code:"PROCESS_NOT_FOUND"}); if(s.running)s.child.kill(); return {id:s.id,stopping:s.running}; }
+}

package/packages/agent/src/security.js

@@ -0,0 +1,20 @@
+import path from "node:path";
+import crypto from "node:crypto";
+
+export function createSecurity({ token, workspaces = [], audit = () => {} } = {}) {
+  const roots = workspaces.map((p) => path.resolve(p));
+  function authenticate(candidate) {
+    if (!token || !candidate) return false;
+    const a = Buffer.from(String(token));
+    const b = Buffer.from(String(candidate));
+    return a.length === b.length && crypto.timingSafeEqual(a, b);
+  }
+  function resolveAllowed(input) {
+    if (typeof input !== "string" || !input.trim()) throw Object.assign(new Error("path is required"), { code:"INVALID_ARGUMENT" });
+    const target = path.resolve(input);
+    const ok = roots.some((root) => target === root || target.startsWith(root + path.sep));
+    if (!ok) throw Object.assign(new Error("Path outside allowed workspace"), { code:"PATH_DENIED" });
+    return target;
+  }
+  return { authenticate, resolveAllowed, audit, roots };
+}

package/packages/agent/src/tools.js

@@ -0,0 +1,20 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const execFileAsync=promisify(execFile);
+
+export function createToolExecutor({ security, processManager }) {
+  return async function executeTool(tool,args={}) {
+    security.audit({event:"tool.request",tool});
+    if(tool==="device.ping") return {pong:true,timestamp:new Date().toISOString()};
+    if(tool==="fs.list"){const target=security.resolveAllowed(args.path);const entries=await fs.readdir(target,{withFileTypes:true});return{path:target,entries:entries.map(e=>({name:e.name,type:e.isDirectory()?"directory":e.isFile()?"file":"other"}))};}
+    if(tool==="fs.read"){const target=security.resolveAllowed(args.path);const max=Math.min(Number(args.maxBytes||65536),262144);const h=await fs.open(target,"r");try{const stat=await h.stat();const b=Buffer.alloc(max);const {bytesRead}=await h.read(b,0,max,0);return{path:target,content:b.subarray(0,bytesRead).toString("utf8"),truncated:stat.size>bytesRead,size:stat.size};}finally{await h.close();}}
+    if(tool==="fs.search"){const root=security.resolveAllowed(args.path);const q=String(args.query||"").toLowerCase();if(!q)throw Object.assign(new Error("query is required"),{code:"INVALID_ARGUMENT"});const entries=await fs.readdir(root,{withFileTypes:true});return{path:root,query:args.query,matches:entries.filter(e=>e.name.toLowerCase().includes(q)).slice(0,Math.min(Number(args.maxResults||50),200)).map(e=>({name:e.name,path:path.join(root,e.name),type:e.isDirectory()?"directory":"file"}))};}
+    if(tool==="process.start"){const cwd=security.resolveAllowed(args.cwd);return processManager.start({...args,cwd});}
+    if(tool==="process.output")return processManager.output(args);
+    if(tool==="process.stop")return processManager.stop(args);
+    if(tool==="git.status"||tool==="git.diff"||tool==="git.log"){const cwd=security.resolveAllowed(args.cwd);const gitArgs=tool==="git.status"?["status","--porcelain=v1","--branch"]:tool==="git.diff"?["diff","--",...(args.paths||[])]:["log","--oneline","-n",String(Math.min(Number(args.limit||10),50))];const {stdout,stderr}=await execFileAsync("git",gitArgs,{cwd,windowsHide:true,maxBuffer:1024*1024});return{stdout,stderr};}
+    throw Object.assign(new Error("Unsupported tool"),{code:"TOOL_NOT_FOUND"});
+  };
+}

package/packages/cli/index.js

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+import os from "node:os";
+import crypto from "node:crypto";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { createAgent } from "../agent/src/agent.js";
+
+const command=process.argv[2]||"remote";
+if(command!=="remote"){console.error("Usage: whyvix-remote remote");process.exit(2);}
+const gatewayUrl=process.env.WHYVIX_GATEWAY_URL||"wss://remote.whyvix.com";
+const authUrl=(process.env.WHYVIX_AUTH_URL||"https://auth.whyvix.com").replace(/\/$/,"");
+const workspaces=(process.env.WHYVIX_WORKSPACES||process.cwd()).split(";").filter(Boolean);
+const deviceId=process.env.WHYVIX_DEVICE_ID||crypto.createHash("sha256").update(os.hostname()+"|"+os.userInfo().username).digest("hex").slice(0,24);
+const credentialDir=join(os.homedir(),".whyvix-remote");
+const credentialPath=join(credentialDir,"device.json");
+
+async function loadCredential(){
+  if(process.env.WHYVIX_DEVICE_CREDENTIAL)return process.env.WHYVIX_DEVICE_CREDENTIAL;
+  try{const saved=JSON.parse(await readFile(credentialPath,"utf8"));return saved.deviceId===deviceId?saved.credential:"";}catch{return "";}
+}
+async function saveCredential(credential){
+  await mkdir(credentialDir,{recursive:true,mode:0o700});
+  await writeFile(credentialPath,JSON.stringify({deviceId,credential}),{encoding:"utf8",mode:0o600});
+}
+async function post(path,fields){
+  const response=await fetch(authUrl+path,{method:"POST",headers:{"content-type":"application/x-www-form-urlencoded"},body:new URLSearchParams(fields),redirect:"error"});
+  return{status:response.status,body:await response.json()};
+}
+async function pair(){
+  const started=await post("/device/pair/start",{device_id:deviceId,device_name:os.hostname()});
+  if(started.status!==201)throw new Error("Unable to start device pairing");
+  console.log("Open this URL to authorize the device:");
+  console.log(started.body.verification_uri);
+  while(Date.now()<started.body.expires_at){
+    await new Promise(r=>setTimeout(r,2000));
+    const result=await post("/device/pair/status",{pairing_id:started.body.pairing_id,pairing_secret:started.body.pairing_secret});
+    if(result.status===200&&result.body.status==="approved"){await saveCredential(result.body.device_credential);return result.body.device_credential;}
+  }
+  throw new Error("Device pairing expired");
+}
+let credential=await loadCredential();
+if(!credential){
+  console.log("WHYVIX Remote device authorization required.");
+  credential=await pair();
+  console.log("Device authorized.");
+}
+console.log("WHYVIX Remote");
+console.log("Device :",os.hostname());
+console.log("Gateway:",gatewayUrl);
+console.log("Workspace:",workspaces.join(", "));
+const agent=createAgent({gatewayUrl,deviceId,deviceName:os.hostname(),token:credential,workspaces,audit:(e)=>console.log("[audit]",JSON.stringify(e))});
+async function shutdown(){await agent.stop();process.exit(0);}
+process.on("SIGINT",shutdown);
+process.on("SIGTERM",shutdown);

package/packages/protocol/src/index.js

@@ -0,0 +1,22 @@
+export const PROTOCOL_VERSION = 1;
+
+export const TYPES = Object.freeze({
+  REGISTER: "register",
+  REGISTERED: "registered",
+  REQUEST: "request",
+  RESPONSE: "response",
+  ERROR: "error",
+  HEARTBEAT: "heartbeat"
+});
+
+export function envelope(type, fields = {}) {
+  return { version: PROTOCOL_VERSION, type, ...fields };
+}
+
+export function parseMessage(raw) {
+  const message = JSON.parse(raw.toString());
+  if (message.version !== PROTOCOL_VERSION) {
+    throw new Error("Unsupported protocol version");
+  }
+  return message;
+}