cloving 1.2.0 → 1.4.0

package/dist/src/relay/phone-outbox.d.ts

@@ -0,0 +1,21 @@
+import { Actor } from "solid-objects";
+export declare const outboxIdentity = "phone";
+export type OpenDecision = {
+    readonly decisionId: string;
+    readonly runId: string;
+};
+export declare class PhoneOutbox extends Actor {
+    static readonly actorType = "PhoneOutbox";
+    decisions: OpenDecision[];
+    retired: string[];
+    track(decision: OpenDecision): boolean;
+    retire({ decisionId }: {
+        readonly decisionId: string;
+    }): void;
+    forget({ decisionId }: {
+        readonly decisionId: string;
+    }): void;
+    untrack({ decisionId }: {
+        readonly decisionId: string;
+    }): boolean;
+}

package/dist/src/relay/phone-outbox.js

@@ -0,0 +1,25 @@
+import { Actor } from "solid-objects";
+export const outboxIdentity = "phone";
+export class PhoneOutbox extends Actor {
+    static actorType = "PhoneOutbox";
+    decisions = [];
+    retired = [];
+    track(decision) {
+        if (this.decisions.some((item) => item.decisionId === decision.decisionId))
+            return false;
+        this.decisions = [...this.decisions, decision];
+        return true;
+    }
+    retire({ decisionId }) {
+        if (!this.retired.includes(decisionId))
+            this.retired = [...this.retired, decisionId];
+    }
+    forget({ decisionId }) {
+        this.retired = this.retired.filter((item) => item !== decisionId);
+    }
+    untrack({ decisionId }) {
+        const known = this.decisions.some((item) => item.decisionId === decisionId);
+        this.decisions = this.decisions.filter((item) => item.decisionId !== decisionId);
+        return known;
+    }
+}

package/dist/src/relay/phone-socket.d.ts

@@ -0,0 +1,6 @@
+import { type Reply, type ServiceRequest } from "../protocol.ts";
+export type PhoneHandler = (request: ServiceRequest) => Promise<Reply>;
+export interface PhoneSocket {
+    readonly close: () => Promise<void>;
+}
+export declare function listenPhoneSocket(path: string, handle: PhoneHandler): Promise<PhoneSocket>;

package/dist/src/relay/phone-socket.js

@@ -0,0 +1,63 @@
+import { chmod, rm } from "node:fs/promises";
+import net from "node:net";
+import { maximumFrameBytes, parseRequest, replyLine, } from "../protocol.js";
+function failed(error) {
+    return {
+        kind: "error",
+        error: {
+            code: "phone-relay-failed",
+            detail: String(Reflect.get(Object(error), "message")),
+        },
+    };
+}
+function served(socket, handle) {
+    let buffered = "";
+    socket.setEncoding("utf8");
+    socket.on("error", () => undefined);
+    socket.on("data", (data) => {
+        buffered += data;
+        const end = buffered.indexOf("\n");
+        if (end < 0 && Buffer.byteLength(buffered) <= maximumFrameBytes)
+            return;
+        socket.removeAllListeners("data");
+        const parsed = parseRequest(end < 0 ? "" : buffered.slice(0, end));
+        const answer = (reply) => {
+            socket.end(replyLine(reply));
+        };
+        const replied = parsed.kind === "error"
+            ? Promise.resolve(parsed)
+            : handle(parsed.request);
+        replied.then(answer, (error) => {
+            answer(failed(error));
+        });
+    });
+}
+export async function listenPhoneSocket(path, handle) {
+    await rm(path, { force: true });
+    const sockets = new Set();
+    const server = net.createServer((socket) => {
+        sockets.add(socket);
+        socket.once("close", () => sockets.delete(socket));
+        served(socket, handle);
+    });
+    await new Promise((ready, refuse) => {
+        server.once("error", refuse);
+        server.listen(path, () => {
+            server.off("error", refuse);
+            ready();
+        });
+    });
+    await chmod(path, 0o600);
+    return {
+        close: async () => {
+            const closed = new Promise((settle) => {
+                server.close(() => {
+                    settle();
+                });
+            });
+            for (const socket of sockets)
+                socket.destroy();
+            await closed;
+        },
+    };
+}

package/dist/src/relay/relay-control.d.ts

@@ -0,0 +1,7 @@
+import type { Fields, Reply, ServiceRequest } from "../protocol.ts";
+export declare function relayControl(runtimeDirectory: string): (request: ServiceRequest) => Promise<Reply>;
+export declare function relayEvents(runtimeDirectory: string, stream: {
+    readonly after: number;
+    readonly onEvent: (event: Fields) => void;
+    readonly stopped: Promise<void>;
+}): Promise<Reply>;

package/dist/src/relay/relay-control.js

@@ -0,0 +1,24 @@
+import { follow, send } from "../cli/client.js";
+const allowed = new Set([
+    "questions",
+    "status",
+    "events",
+    "decision",
+]);
+export function relayControl(runtimeDirectory) {
+    return (request) => {
+        if (!allowed.has(request.operation))
+            return Promise.reject(new Error(`relay-operation-refused: The phone relay may not send ${request.operation}.`));
+        return send(runtimeDirectory, request);
+    };
+}
+export function relayEvents(runtimeDirectory, stream) {
+    return follow(runtimeDirectory, {
+        request: {
+            operation: "events",
+            parameters: { after: stream.after, follow: true },
+        },
+        onEvent: stream.onEvent,
+        signal: stream.stopped,
+    });
+}

package/dist/src/relay/relay-files.d.ts

@@ -0,0 +1,2 @@
+export declare function readOptional(path: string): Promise<string | undefined>;
+export declare function writePrivate(path: string, value: unknown): Promise<void>;

package/dist/src/relay/relay-files.js

@@ -0,0 +1,23 @@
+import { randomUUID } from "node:crypto";
+import { readFile, rename, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+export async function readOptional(path) {
+    return readFile(path, "utf8").catch((error) => {
+        if (Reflect.get(Object(error), "code") === "ENOENT")
+            return undefined;
+        throw error;
+    });
+}
+export async function writePrivate(path, value) {
+    const temporary = join(path, "..", `.${randomUUID()}.tmp`);
+    try {
+        await writeFile(temporary, `${JSON.stringify(value, null, 2)}\n`, {
+            mode: 0o600,
+            flag: "wx",
+        });
+        await rename(temporary, path);
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}

package/dist/src/relay/relay-heartbeat.d.ts

@@ -0,0 +1,17 @@
+import type { RelayStore } from "./relay-store.ts";
+export interface HeartbeatTiming {
+    readonly intervalMilliseconds: number;
+    readonly firstBackoffMilliseconds: number;
+    readonly longestBackoffMilliseconds: number;
+}
+export declare const heartbeatTiming: HeartbeatTiming;
+export interface HeartbeatContext {
+    readonly phoneDirectory: string;
+    readonly store: RelayStore;
+    readonly lost: () => void;
+    readonly timing: HeartbeatTiming;
+    readonly wait: (milliseconds: number, signal: AbortSignal) => Promise<void>;
+}
+export type BeatOutcome = "beat" | "failed" | "lost" | "replaced" | "unregistered";
+export declare function heartbeat(context: HeartbeatContext, signal?: AbortSignal): Promise<BeatOutcome>;
+export declare function runHeartbeats(context: HeartbeatContext, signal: AbortSignal): Promise<void>;

package/dist/src/relay/relay-heartbeat.js

@@ -0,0 +1,81 @@
+import { rm } from "node:fs/promises";
+import { join } from "node:path";
+import { relayRequest } from "./relay-http.js";
+import { readLink } from "./relay-registration.js";
+export const heartbeatTiming = {
+    intervalMilliseconds: 60_000,
+    firstBackoffMilliseconds: 5000,
+    longestBackoffMilliseconds: 300_000,
+};
+function revokedDevices(body) {
+    const devices = typeof body === "object" && body !== null
+        ? Reflect.get(body, "devices")
+        : undefined;
+    if (!Array.isArray(devices))
+        return [];
+    return devices.flatMap((device) => {
+        const deviceId = Reflect.get(Object(device), "device_id");
+        const revokedAt = Reflect.get(Object(device), "revoked_at");
+        return typeof deviceId === "string" && typeof revokedAt === "string"
+            ? [deviceId]
+            : [];
+    });
+}
+async function applyRevocations(context, call) {
+    const { link, signal } = call;
+    if (signal.aborted)
+        return;
+    const reply = await relayRequest(link.origin, {
+        method: "GET",
+        path: "/api/v1/relay/devices",
+        token: link.token,
+        signal,
+    });
+    if (reply.status !== 200)
+        return;
+    const known = new Set((await context.store.devices())
+        .filter((device) => device.removedAt === null)
+        .map((device) => device.deviceId));
+    for (const deviceId of revokedDevices(reply.body))
+        if (known.has(deviceId))
+            await context.store.remove(deviceId);
+}
+async function lostRegistration(context, link) {
+    const current = await readLink(context.phoneDirectory);
+    if (current?.token !== link.token)
+        return "replaced";
+    await context.store.removeAll();
+    await rm(join(context.phoneDirectory, "link.json"), { force: true });
+    context.lost();
+    return "lost";
+}
+export async function heartbeat(context, signal = new AbortController().signal) {
+    const link = await readLink(context.phoneDirectory);
+    if (link === undefined)
+        return "unregistered";
+    const reply = await relayRequest(link.origin, {
+        method: "PUT",
+        path: "/api/v1/relay/daemon/heartbeat",
+        token: link.token,
+        signal,
+    }).catch(() => undefined);
+    if (reply?.status === 401)
+        return lostRegistration(context, link);
+    if (reply === undefined || reply.status >= 300)
+        return "failed";
+    await applyRevocations(context, { link, signal }).catch(() => undefined);
+    return "beat";
+}
+function pause(timing, failures) {
+    if (failures === 0)
+        return timing.intervalMilliseconds;
+    return Math.min(timing.firstBackoffMilliseconds * 2 ** (failures - 1), timing.longestBackoffMilliseconds);
+}
+export async function runHeartbeats(context, signal) {
+    let failures = 0;
+    while (!signal.aborted) {
+        const outcome = await heartbeat(context, signal).catch(() => "failed");
+        failures = outcome === "failed" ? failures + 1 : 0;
+        await context.wait(pause(context.timing, failures), signal);
+    }
+}

package/dist/src/relay/relay-http.d.ts

@@ -0,0 +1,14 @@
+export interface RelayCall {
+    readonly method: "GET" | "POST" | "PUT" | "DELETE";
+    readonly path: string;
+    readonly token?: string;
+    readonly body?: unknown;
+    readonly timeoutMilliseconds?: number;
+    readonly signal?: AbortSignal;
+}
+export interface RelayReply {
+    readonly status: number;
+    readonly body: unknown;
+}
+export declare function relayOrigin(value: string | undefined): string;
+export declare function relayRequest(origin: string, call: RelayCall): Promise<RelayReply>;

package/dist/src/relay/relay-http.js

@@ -0,0 +1,63 @@
+import http from "node:http";
+import https from "node:https";
+export function relayOrigin(value) {
+    const given = value ?? "https://cloving.ai";
+    const url = URL.parse(given);
+    const local = url?.protocol === "http:" && url.hostname === "127.0.0.1";
+    if (url === null ||
+        (url.protocol !== "https:" && !local) ||
+        url.origin !== given ||
+        given.length > 161)
+        throw new Error(`relay-origin-invalid: CLOVING_RELAY_ORIGIN must be an https origin of at most 161 characters, such as https://cloving.ai.`);
+    return url.origin;
+}
+function parsed(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}
+function headers(call, payload) {
+    return {
+        accept: "application/json",
+        ...(payload === undefined ? {} : { "content-type": "application/json" }),
+        ...(call.token === undefined
+            ? {}
+            : { authorization: `Bearer ${call.token}` }),
+    };
+}
+export function relayRequest(origin, call) {
+    const url = new URL(call.path, origin);
+    const transport = url.protocol === "https:" ? https : http;
+    const payload = call.body === undefined ? undefined : JSON.stringify(call.body);
+    return new Promise((settle, reject) => {
+        const request = transport.request(url, {
+            method: call.method,
+            headers: headers(call, payload),
+            timeout: call.timeoutMilliseconds ?? 30_000,
+            ...(call.signal === undefined ? {} : { signal: call.signal }),
+        }, (response) => {
+            let text = "";
+            response.setEncoding("utf8");
+            response.on("data", (chunk) => {
+                text += chunk;
+            });
+            response.once("end", () => {
+                settle({ status: response.statusCode ?? 0, body: parsed(text) });
+            });
+            const incomplete = () => {
+                if (!response.complete)
+                    reject(new Error("relay-response-incomplete: cloving.ai closed the answer before its end."));
+            };
+            response.once("error", incomplete);
+            response.once("close", incomplete);
+        });
+        request.once("timeout", () => {
+            request.destroy(new Error("relay-timeout: cloving.ai did not answer."));
+        });
+        request.once("error", reject);
+        request.end(payload);
+    });
+}

package/dist/src/relay/relay-registration.d.ts

@@ -0,0 +1,15 @@
+import { type PhoneLink } from "../phone/phone-link.ts";
+import { type DaemonKeys } from "./daemon-keys.ts";
+export interface RegistrationContext {
+    readonly phoneDirectory: string;
+    readonly origin: string;
+    readonly computerName: string;
+}
+export interface Registration {
+    readonly link: PhoneLink;
+    readonly keys: DaemonKeys;
+}
+export declare function readLink(phoneDirectory: string): Promise<PhoneLink | undefined>;
+export declare function storedRegistration(phoneDirectory: string): Promise<Registration | undefined>;
+export declare function forgetRegistration(phoneDirectory: string): Promise<void>;
+export declare function registration(context: RegistrationContext): Promise<Registration>;

package/dist/src/relay/relay-registration.js

@@ -0,0 +1,63 @@
+import { rm } from "node:fs/promises";
+import { join } from "node:path";
+import { parsePhoneLink } from "../phone/phone-link.js";
+import { newDaemonKeys, parseDaemonKeys, } from "./daemon-keys.js";
+import { readOptional, writePrivate } from "./relay-files.js";
+import { relayRequest } from "./relay-http.js";
+export function readLink(phoneDirectory) {
+    return readOptional(join(phoneDirectory, "link.json")).then(parsePhoneLink);
+}
+function readKeys(phoneDirectory) {
+    return readOptional(join(phoneDirectory, "daemon-keys.json")).then(parseDaemonKeys);
+}
+export async function storedRegistration(phoneDirectory) {
+    const link = await readLink(phoneDirectory);
+    const keys = await readKeys(phoneDirectory);
+    if (link === undefined || keys === undefined)
+        return undefined;
+    return { link, keys };
+}
+export async function forgetRegistration(phoneDirectory) {
+    await rm(join(phoneDirectory, "link.json"), { force: true });
+}
+function text(body, name) {
+    const value = typeof body === "object" && body !== null
+        ? Reflect.get(body, name)
+        : undefined;
+    if (typeof value !== "string" || value === "")
+        throw new Error(`registration-invalid: cloving.ai sent no ${name}.`);
+    return value;
+}
+async function registered(context, keys) {
+    const reply = await relayRequest(context.origin, {
+        method: "POST",
+        path: "/api/v1/relay/daemons",
+        body: {
+            name: context.computerName,
+            agreement_public_key: keys.agreementPublicKey,
+            signing_public_key: keys.signingPublicKey,
+        },
+    });
+    if (reply.status !== 201)
+        throw new Error(`registration-failed: cloving.ai answered ${String(reply.status)}.`);
+    const link = {
+        daemonId: text(reply.body, "daemon_id"),
+        origin: context.origin,
+        token: text(reply.body, "token"),
+        registeredAt: new Date().toISOString(),
+    };
+    await writePrivate(join(context.phoneDirectory, "link.json"), link);
+    return { link, keys };
+}
+export async function registration(context) {
+    const link = await readLink(context.phoneDirectory);
+    const stored = await readKeys(context.phoneDirectory);
+    if (link !== undefined &&
+        stored !== undefined &&
+        link.origin === context.origin)
+        return { link, keys: stored };
+    const keys = stored ?? newDaemonKeys();
+    if (stored === undefined)
+        await writePrivate(join(context.phoneDirectory, "daemon-keys.json"), keys);
+    return registered(context, keys);
+}

package/dist/src/relay/relay-service.d.ts

@@ -0,0 +1,28 @@
+import type { Reply } from "../protocol.ts";
+import { type InboxTiming } from "./answer-inbox.ts";
+import { type WatchTiming } from "./decision-watch.ts";
+import { type OperationState } from "./phone-operations.ts";
+import { type HeartbeatTiming } from "./relay-heartbeat.ts";
+export interface RelayPaths {
+    readonly runtimeDirectory: string;
+    readonly phoneDirectory: string;
+}
+export interface RelayOptions extends RelayPaths {
+    readonly origin?: string;
+    readonly computerName?: string;
+    readonly secret?: () => Buffer;
+    readonly heartbeatTiming?: HeartbeatTiming;
+    readonly watchTiming?: WatchTiming;
+    readonly inboxTiming?: InboxTiming;
+}
+export interface Relay {
+    readonly close: () => Promise<void>;
+}
+export declare function phoneState(relay: OperationState): Promise<Reply>;
+export declare function computerName(name: string): string;
+export declare function startRelay(options: RelayOptions): Promise<Relay>;
+export interface RelayProgram {
+    readonly stopped: Promise<unknown>;
+    readonly error: (line: string) => void;
+}
+export declare function runRelay(environment: Readonly<Record<string, string | undefined>>, program: RelayProgram): Promise<number>;