@buyong/pi-devin 0.0.0-stage → 0.1.0

package/src/core/protocol/device.ts

@@ -0,0 +1,73 @@
+import { execFileSync } from "node:child_process";
+import { networkInterfaces, userInfo, type NetworkInterfaceInfo } from "node:os";
+
+export interface DeviceIdentity {
+  serial: string;
+  macs: string[];
+  username: string;
+}
+
+/** OS inputs read by device collection. Tests control only this boundary; collection rules and the fingerprint computation run unchanged. */
+export interface DeviceSystem {
+  platform: NodeJS.Platform;
+  run(file: string, args: string[]): string;
+  networkInterfaces(): NodeJS.Dict<NetworkInterfaceInfo[]>;
+  username(): string;
+}
+
+// The MAC collection shell input is a fixed string and never includes user input.
+const MAC_COMMAND = `ifconfig 2>/dev/null | awk '/^[a-z]/{iface=$1} /inet6? /{has_ip[iface]=1} /ether /{mac[iface]=$2} END{for(i in has_ip) if(mac[i] && mac[i]!="00:00:00:00:00:00") print mac[i]}' | tr '[:upper:]' '[:lower:]' | sort -u`;
+const COMMAND_OPTIONS = {
+  encoding: "utf8" as const, timeout: 3000, maxBuffer: 1024 * 1024,
+  env: { PATH: "/usr/bin:/bin:/usr/sbin:/sbin", LC_ALL: "C" },
+  stdio: ["ignore", "pipe", "ignore"] as ["ignore", "pipe", "ignore"],
+};
+
+function nodeDeviceSystem(): DeviceSystem {
+  return {
+    platform: process.platform,
+    run: (file, args) => execFileSync(file, args, COMMAND_OPTIONS),
+    networkInterfaces,
+    username: () => userInfo().username,
+  };
+}
+
+/** MAC collection conditions: non-zero MACs of interfaces that have an address, lowercased, deduplicated and sorted. */
+function interfaceMACs(interfaces: NodeJS.Dict<NetworkInterfaceInfo[]>): string[] {
+  const macs = new Set<string>();
+  for (const addresses of Object.values(interfaces)) {
+    for (const address of addresses ?? []) {
+      const mac = address.mac.toLowerCase();
+      if (mac && mac !== "00:00:00:00:00:00") macs.add(mac);
+    }
+  }
+  return [...macs].sort();
+}
+
+/**
+ * Device values are used only for the fingerprint. Credentials and settings of an installed CLI are never read.
+ * macOS reads ioreg/ifconfig. Serial collection on other OSes is unverified, so the
+ * serial is left empty instead of being invented; MACs come from the common Node API under the same conditions.
+ */
+export function collectDeviceIdentity(system: DeviceSystem = nodeDeviceSystem()): DeviceIdentity {
+  const isDarwin = system.platform === "darwin";
+  let serial = "";
+  if (isDarwin) {
+    try {
+      const result = system.run("/usr/sbin/ioreg", ["-rd1", "-c", "IOPlatformExpertDevice"]);
+      const match = result.match(/"IOPlatformSerialNumber"\s*=\s*("(?:\\.|[^"\\])*")/);
+      if (match) serial = JSON.parse(match[1]) as string;
+    } catch { /* A failed serial read becomes an empty value. The output may be sensitive, so it is not included in errors. */ }
+  }
+  let macs: string[] = [];
+  if (Buffer.byteLength(serial) < 4) {
+    try {
+      macs = isDarwin
+        ? system.run("/bin/sh", ["-c", MAC_COMMAND]).split(/\r?\n/).filter(Boolean)
+        : interfaceMACs(system.networkInterfaces());
+    } catch { /* A failed MAC collection yields an empty list. */ }
+  }
+  let username = "unknown";
+  try { username = system.username(); } catch { /* value used when the system call fails */ }
+  return { serial, macs, username };
+}

package/src/core/protocol/fingerprint.ts

@@ -0,0 +1,59 @@
+import { createCipheriv, createHash, randomBytes } from "node:crypto";
+import { performance } from "node:perf_hooks";
+import { collectDeviceIdentity, type DeviceIdentity } from "./device.ts";
+
+// Matches the CLI's fingerprint construction; verified with fake-token requests only.
+// This is not encryption for credential storage. f contains the API token, so it is never logged.
+const KEY_MATERIAL = "df97465349f38646af1d66c263e25e08";
+const KEY = createHash("sha256").update(KEY_MATERIAL, "utf8").digest();
+
+export interface FingerprintProvider {
+  create(): string;
+  device(): string;
+}
+
+export function hashDeviceIdentity(identity: DeviceIdentity): string {
+  const macs = Buffer.byteLength(identity.serial) >= 4 ? "" : identity.macs.join(",");
+  return createHash("sha512").update(macs + identity.serial + identity.username, "utf8").digest("hex");
+}
+
+export function createFingerprintProvider(sessionToken: string, options: {
+  collectIdentity?: () => DeviceIdentity;
+  nowNanoseconds?: () => bigint;
+  nonce?: () => Uint8Array;
+} = {}): FingerprintProvider {
+  let device: string | undefined;
+  const getDevice = () => device ??= hashDeviceIdentity((options.collectIdentity ?? collectDeviceIdentity)());
+  return {
+    device: getDevice,
+    create: () => encodeFingerprint({
+      deviceFingerprint: getDevice(), sessionToken,
+      timestampNanoseconds: options.nowNanoseconds?.(), nonce: options.nonce?.(),
+    }),
+  };
+}
+
+export function unixNanoseconds(): bigint {
+  // High-resolution epoch clock from the public Node API. It does not guarantee the OS's raw CLOCK_REALTIME precision.
+  const originMilliseconds = Math.trunc(performance.timeOrigin);
+  const fractionalNanoseconds = Math.round((performance.timeOrigin - originMilliseconds + performance.now()) * 1_000_000);
+  return BigInt(originMilliseconds) * 1_000_000n + BigInt(fractionalNanoseconds);
+}
+
+export function encodeFingerprint(options: {
+  deviceFingerprint: string;
+  sessionToken: string;
+  timestampNanoseconds?: bigint;
+  nonce?: Uint8Array;
+}): string {
+  if (!/^[0-9a-f]{128}$/.test(options.deviceFingerprint)) throw new Error("The device identifier must be 128 lowercase hex characters.");
+  if (!options.sessionToken || /[|\s\u0000-\u001f\u007f]/.test(options.sessionToken)) throw new Error("Invalid session token format.");
+  const timestamp = options.timestampNanoseconds ?? unixNanoseconds();
+  if (timestamp < 0n || timestamp >= (1n << 128n)) throw new Error("Invalid fingerprint timestamp.");
+  const nonce = options.nonce ?? randomBytes(12);
+  if (nonce.length !== 12) throw new Error("The fingerprint nonce must be 12 bytes.");
+  const plaintext = `${options.deviceFingerprint}|${options.sessionToken}|${timestamp}`;
+  const cipher = createCipheriv("aes-256-gcm", KEY, nonce);
+  const ciphertext = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
+  return Buffer.concat([nonce, ciphertext, cipher.getAuthTag()]).toString("hex");
+}

package/src/core/protocol/http.ts

@@ -0,0 +1,109 @@
+import { Agent as HTTPAgent, request as httpRequest } from "node:http";
+import { Agent as HTTPSAgent, request as httpsRequest } from "node:https";
+import { Readable, pipeline } from "node:stream";
+import type { ConnectionOptions } from "node:tls";
+import { createGunzip } from "node:zlib";
+
+export interface HTTPTransportOptions {
+  /** Trusts a user-supplied CA without disabling certificate or host verification. */
+  ca?: ConnectionOptions["ca"];
+}
+
+export interface HTTPTransport {
+  fetch: typeof fetch;
+  close(): void;
+}
+
+/**
+ * HTTP/1.1-only transport. Owns a per-client pool and verifies TLS certificates and hosts.
+ * The 5000ms socket timeout spells out the previous Node global agent setting as a PoC policy;
+ * it is not the overall RPC deadline. It does not claim to match the CLI's TLS or pool policy.
+ */
+export function createHTTPTransport(options: HTTPTransportOptions = {}): HTTPTransport {
+  const httpAgent = new HTTPAgent({ keepAlive: true, timeout: 5000 });
+  const httpsAgent = new HTTPSAgent({
+    keepAlive: true, timeout: 5000, rejectUnauthorized: true, minVersion: "TLSv1.2",
+    ALPNProtocols: ["http/1.1"], ...(options.ca === undefined ? {} : { ca: options.ca }),
+  });
+  let isClosed = false;
+  const fetchHTTP: typeof fetch = async (input, init) => {
+    if (isClosed) throw new Error("The HTTP transport is closed.");
+    if (!(typeof input === "string" || input instanceof URL) || !["POST", "GET"].includes(init?.method ?? "") || init?.redirect !== "error") {
+      throw new Error("This transport supports only URL GET/POST without redirects.");
+    }
+    const url = new URL(input);
+    if (!["https:", "http:"].includes(url.protocol)) throw new Error("Unsupported HTTP protocol.");
+    const body = typeof init.body === "string" ? Buffer.from(init.body)
+      : init.body instanceof Uint8Array ? Buffer.from(init.body) : undefined;
+    if (init.method === "POST" && !body) throw new Error("A POST body must be a string or a byte array.");
+    if (init.method === "GET" && init.body != null) throw new Error("A GET body is not supported.");
+    const validated = new Headers(init.headers);
+    const entries = init.headers instanceof Headers ? [...init.headers.entries()]
+      : Array.isArray(init.headers) ? init.headers : Object.entries(init.headers ?? {});
+    const headers: Record<string, string> = {};
+    for (const [name] of entries) {
+      const key = name.toLowerCase();
+      if (key !== "host" && key !== "content-length") headers[key] = validated.get(name)!;
+    }
+    headers.host = url.host;
+    if (body) headers["content-length"] = String(body.byteLength);
+    return new Promise<Response>((resolve, reject) => {
+      const isHTTPS = url.protocol === "https:";
+      const send = isHTTPS ? httpsRequest : httpRequest;
+      const request = send(url, {
+        method: init.method, headers, signal: init.signal ?? undefined,
+        agent: isHTTPS ? httpsAgent : httpAgent,
+      }, (incoming) => {
+        try {
+          const responseHeaders = new Headers();
+          for (const [name, value] of Object.entries(incoming.headers)) {
+            for (const entry of Array.isArray(value) ? value : value === undefined ? [] : [value]) responseHeaders.append(name, entry);
+          }
+          const status = incoming.statusCode ?? 502;
+          const hasNoBody = [204, 205, 304].includes(status);
+          const encoding = responseHeaders.get("content-encoding")?.trim().toLowerCase();
+          let stream: Readable = incoming;
+          if (hasNoBody) incoming.resume();
+          else if (encoding && encoding !== "identity") {
+            if (encoding !== "gzip") {
+              // An encoding problem in an error body must not hide an already received 401/403/429 status.
+              if (status >= 200 && status < 300) throw new Error("Unsupported HTTP response compression.");
+            } else {
+              const decoded = createGunzip();
+              // Propagates consumer cancellation and compression errors to the original socket and keeps backpressure.
+              pipeline(incoming, decoded, () => {});
+              stream = decoded;
+              responseHeaders.delete("content-encoding");
+              responseHeaders.delete("content-length");
+            }
+          }
+          resolve(new Response(hasNoBody ? null : Readable.toWeb(stream) as ReadableStream<Uint8Array>, {
+            status, headers: responseHeaders,
+          }));
+        } catch (error) {
+          incoming.destroy();
+          reject(error);
+        }
+      });
+      request.once("error", reject);
+      request.once("upgrade", (_response, socket) => {
+        socket.destroy();
+        reject(new Error("HTTP upgrade is not supported."));
+      });
+      request.removeHeader("connection");
+      request.end(body);
+    });
+  };
+  return {
+    fetch: fetchHTTP,
+    close() {
+      if (isClosed) return;
+      isClosed = true;
+      httpAgent.destroy();
+      httpsAgent.destroy();
+    },
+  };
+}
+
+/** Default transport for existing direct callers. ConnectClient owns its own pool. */
+export const requestHTTP: typeof fetch = createHTTPTransport().fetch;

package/src/core/protocol/protobuf.ts

@@ -0,0 +1,112 @@
+import { readdirSync, statSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import protobuf from "protobufjs";
+import { object, type JsonObject } from "../types.ts";
+
+export const CHAT_METHOD = "exa.api_server_pb.ApiServerService/GetChatMessage";
+
+export interface MessageCodec {
+  encode(value: JsonObject): Uint8Array;
+  decode(bytes: Uint8Array): JsonObject;
+}
+
+let root: protobuf.Root | undefined;
+const camelCase = (name: string) => name.replace(/_([a-z])/g, (_, letter: string) => letter.toUpperCase());
+
+const PROTO_ROOT = fileURLToPath(new URL("../../../proto/", import.meta.url));
+
+function protoSources(directory: string, out: string[] = []): string[] {
+  for (const entry of readdirSync(directory)) {
+    const path = join(directory, entry);
+    if (statSync(path).isDirectory()) protoSources(path, out);
+    else if (entry.endsWith(".proto")) out.push(path);
+  }
+  return out;
+}
+
+function getRoot(): protobuf.Root {
+  if (!root) {
+    // The schema is the shipped `proto/` source tree, parsed directly. The four definitions this
+    // package added from its own protocol analysis are marked in the sources, so nothing is
+    // patched in at runtime. keepCase keeps the declared snake_case names the DTO boundary uses.
+    root = new protobuf.Root();
+    root.resolvePath = (_origin: string, target: string) => isAbsolute(target) ? target : join(PROTO_ROOT, target);
+    root.loadSync(protoSources(PROTO_ROOT), { keepCase: true });
+    root.resolveAll();
+  }
+  return root;
+}
+
+/** Converts between camelCase DTOs and the original snake_case at the boundary; user keys inside maps stay unchanged. */
+function convertFields(type: protobuf.Type, value: JsonObject, isEncoding: boolean, path: string): JsonObject {
+  const result: [string, unknown][] = [];
+  for (const [name, entry] of Object.entries(value)) {
+    if (entry === undefined || entry === null) continue;
+    const field = isEncoding ? type.fieldsArray.find((candidate) => camelCase(candidate.name) === name)
+      : Object.hasOwn(type.fields, name) ? type.fields[name] : undefined;
+    if (!field) throw new Error(`Field not in the protobuf schema: ${path}.${name}`);
+    const convert = (item: unknown): unknown => {
+      if (field.resolvedType instanceof protobuf.Type) {
+        return convertFields(field.resolvedType, object(item, `${path}.${name}`), isEncoding, `${path}.${name}`);
+      }
+      // Prevents fromObject from silently turning an invalid enum into 0.
+      if (isEncoding && field.resolvedType instanceof protobuf.Enum) {
+        const isValid = typeof item === "string" ? Object.hasOwn(field.resolvedType.values, item)
+          : typeof item === "number" && Object.hasOwn(field.resolvedType.valuesById, item);
+        if (!isValid) throw new Error(`Unknown protobuf enum: ${path}.${name}`);
+      }
+      return item;
+    };
+    let converted: unknown;
+    if (field.map) converted = Object.fromEntries(Object.entries(object(entry, `${path}.${name}`)).map(([key, item]) => [key, convert(item)]));
+    else if (field.repeated) {
+      if (!Array.isArray(entry)) throw new Error(`Field requires an array: ${path}.${name}`);
+      converted = entry.map(convert);
+    } else converted = convert(entry);
+    result.push([isEncoding ? field.name : camelCase(field.name), converted]);
+  }
+  return Object.fromEntries(result);
+}
+
+function messageCodec(typeName: string): MessageCodec {
+  const getType = () => getRoot().lookupType(typeName);
+  return {
+    encode(value) {
+      const type = getType();
+      const message = type.fromObject(convertFields(type, value, true, typeName));
+      const error = type.verify(message);
+      if (error) throw new Error(`Invalid protobuf input: ${error}`);
+      return type.encode(message).finish();
+    },
+    decode(bytes) {
+      const type = getType();
+      try {
+        const decoded = object(type.toObject(type.decode(bytes), {
+          longs: String, enums: String, bytes: String, defaults: false,
+        }), typeName);
+        return convertFields(type, decoded, false, typeName);
+      } catch {
+        throw new Error(`Invalid protobuf response: ${typeName}`);
+      }
+    },
+  };
+}
+
+export function unaryCodecs(method: string): { request: MessageCodec; response: MessageCodec } {
+  const split = method.lastIndexOf("/");
+  if (split <= 0) throw new Error("A valid RPC path is required.");
+  const service = getRoot().lookupService(method.slice(0, split));
+  const definition = service.methods[method.slice(split + 1)];
+  definition?.resolve();
+  if (!definition?.resolvedRequestType || !definition.resolvedResponseType || definition.responseStream || definition.requestStream) {
+    throw new Error(`Unsupported unary RPC: ${method}`);
+  }
+  return {
+    request: messageCodec(definition.resolvedRequestType.fullName),
+    response: messageCodec(definition.resolvedResponseType.fullName),
+  };
+}
+
+export const chatRequestCodec = messageCodec("exa.api_server_pb.GetChatMessageRequest");
+export const chatResponseCodec = messageCodec("exa.api_server_pb.GetChatMessageResponse");