cloving 1.2.0 → 1.3.0

package/dist/src/relay/answer-inbox.js

@@ -0,0 +1,173 @@
+import { setTimeout as delay } from "node:timers/promises";
+import { record } from "../protocol.js";
+import { answerDecisionId, answerVerdict, } from "./answer-check.js";
+import { receiptEnvelope } from "./decision-envelopes.js";
+import { envelopeAad, relayInfo, unpadPlaintext } from "./envelope.js";
+import { envelopesBody } from "./envelope-post.js";
+import { openFrom } from "./hpke.js";
+import { relayRequest } from "./relay-http.js";
+import { storedRegistration } from "./relay-registration.js";
+import { envelopeExpiry, sealedPost, } from "./sealed-post.js";
+export const inboxTiming = {
+    waitSeconds: 25,
+    retryMilliseconds: 5000,
+};
+function inboxItem(value) {
+    const fields = record(value);
+    const answerId = fields?.["answer_id"];
+    const deviceId = fields?.["device_id"];
+    const ciphertext = fields?.["ciphertext"];
+    const sequence = fields?.["sequence"];
+    if (typeof answerId !== "string" ||
+        typeof deviceId !== "string" ||
+        typeof ciphertext !== "string" ||
+        typeof sequence !== "number")
+        return [];
+    return [{ answerId, deviceId, ciphertext, sequence }];
+}
+function inboxItems(body) {
+    const answers = record(body)?.["answers"];
+    if (!Array.isArray(answers))
+        return [];
+    return answers
+        .flatMap((item) => inboxItem(item))
+        .sort((left, right) => left.sequence - right.sequence);
+}
+function openedAnswer(answering) {
+    const { registration, item } = answering;
+    try {
+        const padded = openFrom(registration.keys.agreementPrivateKey, {
+            info: relayInfo,
+            aad: envelopeAad({
+                daemonId: registration.link.daemonId,
+                deviceId: item.deviceId,
+                kind: "answer",
+            }),
+            sealed: Buffer.from(item.ciphertext, "base64url"),
+        });
+        const message = record(JSON.parse(unpadPlaintext(padded).toString("utf8")));
+        const payload = message?.["payload"];
+        const signature = message?.["signature"];
+        if (typeof payload !== "string" || typeof signature !== "string")
+            return undefined;
+        return { payload, signature };
+    }
+    catch {
+        return undefined;
+    }
+}
+async function verdictOf(context, answering) {
+    const message = openedAnswer(answering);
+    if (message === undefined)
+        return { kind: "refused", code: "answer-invalid", decisionId: null };
+    const decisionId = answerDecisionId(message);
+    return answerVerdict(message, {
+        daemonId: answering.registration.link.daemonId,
+        routedDeviceId: answering.item.deviceId,
+        devices: await context.store.devices(),
+        now: context.now(),
+        sentPromptDigest: decisionId === null
+            ? null
+            : await context.store.delivery.promptDigest(decisionId),
+    });
+}
+function receiptBody(base, answered) {
+    if (answered.kind === "result")
+        return {
+            ...base,
+            code: String(answered.result["kind"]),
+            outcome: answered.result["decision"] ?? null,
+            receipt: answered.result["receipt"] ?? null,
+        };
+    const code = answered.kind === "refused" ? answered.code : answered.error.code;
+    return { ...base, code, outcome: null, receipt: null };
+}
+async function receiptWork(context, answering) {
+    const { registration, item } = answering;
+    const verdict = await verdictOf(context, answering);
+    const answered = verdict.kind === "decision"
+        ? await context.control({
+            operation: "decision",
+            parameters: verdict.parameters,
+        })
+        : verdict;
+    const receipt = receiptBody({ answerId: item.answerId, decisionId: verdict.decisionId }, answered);
+    const device = (await context.store.devices()).find((known) => known.deviceId === item.deviceId);
+    const issued = context.now();
+    const envelope = device === undefined
+        ? null
+        : await sealedPost(context, {
+            registration,
+            device,
+            decisionId: verdict.decisionId ?? item.answerId,
+            issuedAt: new Date(issued).toISOString(),
+            expiresAt: envelopeExpiry(null, issued),
+            build: (target) => receiptEnvelope({ receipt, target }),
+        });
+    return {
+        answerId: item.answerId,
+        sequence: item.sequence,
+        deviceId: item.deviceId,
+        envelope,
+    };
+}
+async function handled(context, answering) {
+    const { item } = answering;
+    const { link } = answering.registration;
+    const work = (await context.store.inbox.work(item.answerId)) ??
+        (await context.store.inbox.record(await receiptWork(context, answering)));
+    if (work.envelope !== null) {
+        const posted = await relayRequest(link.origin, {
+            method: "POST",
+            path: "/api/v1/relay/envelopes",
+            token: link.token,
+            body: envelopesBody(work.deviceId, [work.envelope]),
+        });
+        if (posted.status !== 201)
+            return false;
+    }
+    const acknowledged = await relayRequest(link.origin, {
+        method: "POST",
+        path: "/api/v1/relay/inbox/acks",
+        token: link.token,
+        body: { answer_ids: [item.answerId] },
+    });
+    if (acknowledged.status !== 200)
+        return false;
+    await context.store.inbox.complete({
+        answerId: item.answerId,
+        sequence: item.sequence,
+    });
+    return true;
+}
+export async function readAnswers(context, reading) {
+    const registration = await storedRegistration(context.phoneDirectory);
+    if (registration === undefined)
+        return false;
+    const { link } = registration;
+    const cursor = await context.store.inbox.cursor();
+    const reply = await relayRequest(link.origin, {
+        method: "GET",
+        path: `/api/v1/relay/inbox?after=${String(cursor)}&wait=${String(reading.waitSeconds)}`,
+        token: link.token,
+        timeoutMilliseconds: (reading.waitSeconds + 10) * 1000,
+        signal: reading.signal,
+    });
+    if (reply.status !== 200)
+        throw new Error(`inbox-failed: cloving.ai answered ${String(reply.status)}.`);
+    for (const item of inboxItems(reply.body))
+        if (!(await handled(context, { registration, item })))
+            return false;
+    return true;
+}
+export async function runInbox(context, running) {
+    const { signal, timing } = running;
+    while (!signal.aborted) {
+        const polled = await readAnswers(context, {
+            waitSeconds: timing.waitSeconds,
+            signal,
+        }).catch(() => false);
+        if (!polled)
+            await delay(timing.retryMilliseconds, undefined, { signal }).catch(() => undefined);
+    }
+}

package/dist/src/relay/daemon-keys.d.ts

@@ -0,0 +1,16 @@
+import { type KeyObject } from "node:crypto";
+export interface DaemonKeys {
+    readonly agreementPrivateKey: string;
+    readonly agreementPublicKey: string;
+    readonly signingPrivateKey: string;
+    readonly signingPublicKey: string;
+}
+export declare function publicPoint(key: KeyObject): string;
+export declare function newDaemonKeys(): DaemonKeys;
+export declare function parseDaemonKeys(text: string | undefined): DaemonKeys | undefined;
+export declare function keyFingerprint(keys: DaemonKeys): Buffer;
+export declare function pairingIdentity(secret: Buffer): string;
+export declare function pairingLink(origin: string, values: {
+    readonly secret: Buffer;
+    readonly keys: DaemonKeys;
+}): string;

package/dist/src/relay/daemon-keys.js

@@ -0,0 +1,75 @@
+import { createHash, generateKeyPairSync } from "node:crypto";
+import { canonicalJson } from "../phone/canonical-json.js";
+const fields = [
+    "agreementPrivateKey",
+    "agreementPublicKey",
+    "signingPrivateKey",
+    "signingPublicKey",
+];
+export function publicPoint(key) {
+    const jwk = key.export({ format: "jwk" });
+    return Buffer.concat([
+        Buffer.from([4]),
+        Buffer.from(String(jwk.x), "base64url"),
+        Buffer.from(String(jwk.y), "base64url"),
+    ]).toString("base64url");
+}
+function pair() {
+    const { privateKey, publicKey } = generateKeyPairSync("ec", {
+        namedCurve: "prime256v1",
+    });
+    return {
+        privateKey: privateKey
+            .export({ format: "der", type: "pkcs8" })
+            .toString("base64url"),
+        publicKey: publicPoint(publicKey),
+    };
+}
+export function newDaemonKeys() {
+    const agreement = pair();
+    const signing = pair();
+    return {
+        agreementPrivateKey: agreement.privateKey,
+        agreementPublicKey: agreement.publicKey,
+        signingPrivateKey: signing.privateKey,
+        signingPublicKey: signing.publicKey,
+    };
+}
+export function parseDaemonKeys(text) {
+    if (text === undefined)
+        return undefined;
+    const value = JSON.parse(text);
+    if (typeof value !== "object" || value === null)
+        return undefined;
+    const complete = fields.every((name) => {
+        const field = Reflect.get(value, name);
+        return typeof field === "string" && field !== "";
+    });
+    if (!complete)
+        return undefined;
+    return {
+        agreementPrivateKey: String(Reflect.get(value, "agreementPrivateKey")),
+        agreementPublicKey: String(Reflect.get(value, "agreementPublicKey")),
+        signingPrivateKey: String(Reflect.get(value, "signingPrivateKey")),
+        signingPublicKey: String(Reflect.get(value, "signingPublicKey")),
+    };
+}
+export function keyFingerprint(keys) {
+    const text = canonicalJson({
+        agreementKey: keys.agreementPublicKey,
+        signingKey: keys.signingPublicKey,
+    });
+    return createHash("sha256").update(text).digest().subarray(0, 16);
+}
+export function pairingIdentity(secret) {
+    return createHash("sha256")
+        .update("cloving-pairing-id|")
+        .update(secret)
+        .digest()
+        .subarray(0, 16)
+        .toString("base64url");
+}
+export function pairingLink(origin, values) {
+    const payload = Buffer.concat([values.secret, keyFingerprint(values.keys)]);
+    return `${origin}/pair#v1.${payload.toString("base64url")}`;
+}

package/dist/src/relay/decision-check.d.ts

@@ -0,0 +1,3 @@
+import { type CheckContext } from "./sealed-post.ts";
+export type { CheckContext } from "./sealed-post.ts";
+export declare function checkDecisions(context: CheckContext): Promise<void>;

package/dist/src/relay/decision-check.js

@@ -0,0 +1,77 @@
+import { record } from "../protocol.js";
+import { closeDecisions } from "./decision-close.js";
+import { fullEnvelope, previewEnvelope, promptDigest, } from "./decision-envelopes.js";
+import { storedRegistration } from "./relay-registration.js";
+import { envelopeExpiry, resultOf, rows, sealedPost, } from "./sealed-post.js";
+async function devicePosts(context, plan) {
+    const { decision, workflowId } = plan;
+    const issued = context.now();
+    const posts = [];
+    for (const build of [previewEnvelope, fullEnvelope])
+        posts.push(await sealedPost(context, {
+            registration: plan.registration,
+            device: plan.device,
+            decisionId: String(decision["decisionId"]),
+            issuedAt: new Date(issued).toISOString(),
+            expiresAt: envelopeExpiry(decision["expiresAt"], issued),
+            build: (target) => build({ decision, workflowId, target }),
+        }));
+    return posts;
+}
+async function workflowOf(context, lookup) {
+    const known = lookup.known.get(lookup.runId);
+    if (known !== undefined)
+        return known;
+    const status = await resultOf(context, {
+        operation: "status",
+        parameters: { runId: lookup.runId },
+    });
+    const workflowId = record(status?.["run"])?.["workflowId"];
+    if (typeof workflowId !== "string")
+        return undefined;
+    lookup.known.set(lookup.runId, workflowId);
+    return workflowId;
+}
+async function offerDecision(context, plan) {
+    const decisionId = String(plan.decision["decisionId"]);
+    const delivered = new Set((await context.store.delivery.list(decisionId))
+        .filter((item) => item.topic === "decision")
+        .map((item) => item.deviceId));
+    for (const device of plan.devices.filter((item) => !delivered.has(item.deviceId)))
+        await context.store.delivery.offer(decisionId, {
+            runId: String(plan.decision["runId"]),
+            promptDigest: promptDigest(String(plan.decision["prompt"])),
+            deviceId: device.deviceId,
+            envelopes: await devicePosts(context, { ...plan, device }),
+        });
+}
+export async function checkDecisions(context) {
+    const registration = await storedRegistration(context.phoneDirectory);
+    if (registration === undefined)
+        return;
+    const questions = await resultOf(context, {
+        operation: "questions",
+        parameters: {},
+    });
+    if (questions === undefined)
+        return;
+    const decisions = rows(questions["decisions"]);
+    const devices = (await context.store.devices()).filter((device) => device.state === "connected" && device.removedAt === null);
+    const known = new Map();
+    for (const decision of devices.length === 0 ? [] : decisions) {
+        const runId = String(decision["runId"]);
+        const workflowId = await workflowOf(context, { runId, known });
+        if (workflowId !== undefined)
+            await offerDecision(context, {
+                decision,
+                workflowId,
+                registration,
+                devices,
+            });
+    }
+    await closeDecisions(context, {
+        registration,
+        pending: new Set(decisions.map((decision) => decision["decisionId"])),
+    });
+    await context.store.delivery.sweep();
+}

package/dist/src/relay/decision-close.d.ts

@@ -0,0 +1,6 @@
+import type { Registration } from "./relay-registration.ts";
+import { type CheckContext } from "./sealed-post.ts";
+export declare function closeDecisions(context: CheckContext, scope: {
+    readonly registration: Registration;
+    readonly pending: ReadonlySet<unknown>;
+}): Promise<void>;

package/dist/src/relay/decision-close.js

@@ -0,0 +1,72 @@
+import { record } from "../protocol.js";
+import { closedEnvelope } from "./decision-envelopes.js";
+import { envelopeExpiry, rows, sealedPost, } from "./sealed-post.js";
+const outcomes = new Set([
+    "answered",
+    "approved",
+    "denied",
+    "expired",
+]);
+async function runOf(context, runId) {
+    const reply = await context.control({
+        operation: "status",
+        parameters: { runId },
+    });
+    if (reply.kind === "result")
+        return { run: record(reply.result["run"]) };
+    return reply.error.code === "unknown-run" ? { run: undefined } : undefined;
+}
+function endingFrom(open, run) {
+    const decided = rows(run?.["decisions"]).find((item) => item["decisionId"] === open.decisionId);
+    const outcome = decided?.["decision"];
+    const actor = decided?.["actor"];
+    return {
+        decisionId: open.decisionId,
+        outcome: typeof outcome === "string" && outcomes.has(outcome)
+            ? outcome
+            : "unknown",
+        actor: typeof actor === "string" ? actor : null,
+    };
+}
+async function endingOf(context, open) {
+    const found = await runOf(context, open.runId);
+    return found === undefined ? undefined : endingFrom(open, found.run);
+}
+async function closeDecision(context, scope) {
+    const { decisionId } = scope.open;
+    const ending = await endingOf(context, scope.open);
+    if (ending === undefined)
+        return;
+    const reached = new Set((await context.store.delivery.list(decisionId))
+        .filter((item) => item.topic === "decision" &&
+        (item.state === "sent" || item.state === "pending"))
+        .map((item) => item.deviceId));
+    const devices = (await context.store.devices()).filter((device) => reached.has(device.deviceId) &&
+        device.state === "connected" &&
+        device.removedAt === null);
+    const issued = context.now();
+    const closing = [];
+    for (const device of devices) {
+        const post = await sealedPost(context, {
+            registration: scope.registration,
+            device,
+            decisionId,
+            issuedAt: new Date(issued).toISOString(),
+            expiresAt: envelopeExpiry(null, issued),
+            build: (target) => closedEnvelope({ ending, target }),
+        });
+        closing.push({ deviceId: device.deviceId, envelopes: [post] });
+    }
+    await context.store.delivery.close(decisionId, {
+        devices: closing,
+        at: issued,
+    });
+}
+export async function closeDecisions(context, scope) {
+    for (const open of await context.store.delivery.open())
+        if (!scope.pending.has(open.decisionId))
+            await closeDecision(context, {
+                registration: scope.registration,
+                open,
+            });
+}

package/dist/src/relay/decision-envelopes.d.ts

@@ -0,0 +1,29 @@
+import type { Fields } from "../protocol.ts";
+import { type Envelope } from "./envelope.ts";
+export interface EnvelopeTarget {
+    readonly daemonId: string;
+    readonly deviceId: string;
+    readonly sequence: number;
+    readonly issuedAt: string;
+    readonly expiresAt: string;
+}
+export interface DecisionSource {
+    readonly decision: Fields;
+    readonly workflowId: string;
+    readonly target: EnvelopeTarget;
+}
+export declare function promptDigest(prompt: string): string;
+export declare function receiptEnvelope(source: {
+    readonly receipt: Fields;
+    readonly target: EnvelopeTarget;
+}): Envelope;
+export declare function closedEnvelope(source: {
+    readonly ending: {
+        readonly decisionId: string;
+        readonly outcome: string;
+        readonly actor: string | null;
+    };
+    readonly target: EnvelopeTarget;
+}): Envelope;
+export declare function previewEnvelope(source: DecisionSource): Envelope;
+export declare function fullEnvelope(source: DecisionSource): Envelope;

package/dist/src/relay/decision-envelopes.js

@@ -0,0 +1,93 @@
+import { createHash } from "node:crypto";
+import { operationalDecision } from "../decision-visibility.js";
+import { plaintextBytes, } from "./envelope.js";
+const previewBytes = 2048;
+const fullBytes = 65_535;
+export function promptDigest(prompt) {
+    return `sha256:${createHash("sha256").update(prompt).digest("hex")}`;
+}
+function prefix(text, bytes) {
+    let used = 0;
+    let end = 0;
+    for (const character of text) {
+        const size = Buffer.byteLength(character);
+        if (used + size > bytes)
+            break;
+        used += size;
+        end += character.length;
+    }
+    return text.slice(0, end);
+}
+function fitted(prompt, sizing) {
+    let shown = prompt;
+    let envelope = sizing.build(shown);
+    while (plaintextBytes(envelope) > sizing.limit && shown !== "") {
+        const excess = plaintextBytes(envelope) - sizing.limit;
+        shown = prefix(shown, Buffer.byteLength(shown) - excess);
+        envelope = sizing.build(shown);
+    }
+    return envelope;
+}
+function envelopeOf(source, content) {
+    return { version: 1, ...source.target, ...content };
+}
+export function receiptEnvelope(source) {
+    return {
+        version: 1,
+        ...source.target,
+        kind: "receipt",
+        body: source.receipt,
+    };
+}
+export function closedEnvelope(source) {
+    return {
+        version: 1,
+        ...source.target,
+        kind: "closed",
+        body: source.ending,
+    };
+}
+export function previewEnvelope(source) {
+    const { decision, workflowId } = source;
+    const prompt = String(operationalDecision(decision, workflowId)["prompt"]);
+    return fitted(prompt, {
+        limit: previewBytes,
+        build: (shown) => envelopeOf(source, {
+            kind: "preview",
+            body: {
+                decisionId: decision["decisionId"],
+                label: decision["label"] ?? null,
+                type: decision["type"],
+                workflowId,
+                expiresAt: decision["expiresAt"] ?? null,
+                prompt: shown,
+                truncated: shown.length < prompt.length,
+            },
+        }),
+    });
+}
+export function fullEnvelope(source) {
+    const { decision, workflowId } = source;
+    const prompt = String(decision["prompt"]);
+    return fitted(prompt, {
+        limit: fullBytes,
+        build: (shown) => envelopeOf(source, {
+            kind: "full",
+            body: {
+                decisionId: decision["decisionId"],
+                label: decision["label"] ?? null,
+                type: decision["type"],
+                runId: decision["runId"],
+                workflowId,
+                prompt: shown,
+                allowed: decision["allowed"],
+                revision: decision["revision"],
+                generation: decision["generation"],
+                subjectDigest: decision["subjectDigest"],
+                promptDigest: promptDigest(prompt),
+                expiresAt: decision["expiresAt"] ?? null,
+                truncated: shown.length < prompt.length,
+            },
+        }),
+    });
+}

package/dist/src/relay/decision-watch.d.ts

@@ -0,0 +1,14 @@
+import { type CheckContext } from "./decision-check.ts";
+export interface WatchTiming {
+    readonly pollMilliseconds: number;
+    readonly reconnectMilliseconds: number;
+}
+export declare const watchTiming: WatchTiming;
+export interface WatchContext extends CheckContext {
+    readonly runtimeDirectory: string;
+}
+export interface DecisionWatch {
+    readonly wake: () => void;
+    readonly close: () => Promise<void>;
+}
+export declare function watchDecisions(context: WatchContext, timing: WatchTiming): DecisionWatch;

package/dist/src/relay/decision-watch.js

@@ -0,0 +1,68 @@
+import { setTimeout as delay } from "node:timers/promises";
+import { checkDecisions } from "./decision-check.js";
+import { relayEvents } from "./relay-control.js";
+export const watchTiming = {
+    pollMilliseconds: 60_000,
+    reconnectMilliseconds: 5000,
+};
+const gateEvents = new Set([
+    "gate.opened",
+    "gate.decided",
+    "gate.expired",
+]);
+function pause(milliseconds, signal) {
+    return delay(milliseconds, undefined, { signal }).catch(() => undefined);
+}
+async function followGates(context, stream) {
+    const page = await context.control({
+        operation: "events",
+        parameters: { after: 0, limit: 1 },
+    });
+    const latest = page.kind === "result" ? page.result["latestSequence"] : null;
+    if (typeof latest !== "number")
+        return;
+    stream.wake();
+    await relayEvents(context.runtimeDirectory, {
+        after: latest,
+        onEvent: (event) => {
+            if (gateEvents.has(String(event["type"])))
+                stream.wake();
+        },
+        stopped: stream.stopped,
+    });
+}
+export function watchDecisions(context, timing) {
+    const stop = new AbortController();
+    const stopped = new Promise((settle) => {
+        stop.signal.addEventListener("abort", () => {
+            settle();
+        });
+    });
+    const waking = { controller: new AbortController() };
+    const wake = () => {
+        waking.controller.abort();
+    };
+    const checking = (async () => {
+        while (!stop.signal.aborted) {
+            const current = waking.controller;
+            await checkDecisions(context).catch(() => undefined);
+            await pause(timing.pollMilliseconds, AbortSignal.any([stop.signal, current.signal]));
+            if (current.signal.aborted)
+                waking.controller = new AbortController();
+        }
+    })();
+    const following = (async () => {
+        while (!stop.signal.aborted) {
+            await followGates(context, { wake, stopped }).catch(() => undefined);
+            wake();
+            await pause(timing.reconnectMilliseconds, stop.signal);
+        }
+    })();
+    return {
+        wake,
+        close: async () => {
+            stop.abort();
+            await Promise.all([checking, following]);
+        },
+    };
+}

package/dist/src/relay/envelope-post.d.ts

@@ -0,0 +1,8 @@
+import type { JsonObject } from "solid-objects";
+import type { PostedEnvelope, PostOutcome } from "./phone-delivery.ts";
+export interface PostContext {
+    readonly phoneDirectory: string;
+    readonly now: () => number;
+}
+export declare function envelopesBody(deviceId: string, envelopes: readonly PostedEnvelope[]): Readonly<Record<string, unknown>>;
+export declare function postEnvelopes(context: PostContext, request: JsonObject): Promise<PostOutcome>;