cloving 1.1.0 → 1.3.0

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

@@ -0,0 +1,145 @@
+import { createHash, verify } from "node:crypto";
+import { record } from "../protocol.js";
+import { publicKeyObject } from "./pairing-checks.js";
+const textNames = [
+    "daemonId",
+    "deviceId",
+    "decisionId",
+    "command",
+    "subjectDigest",
+    "promptDigest",
+    "commandId",
+    "signedAt",
+    "keyClass",
+];
+const countNames = ["expectedRevision", "generation"];
+const commands = new Set(["answer", "approve", "deny"]);
+const keyClasses = new Set(["answer", "approval"]);
+const ageLimitMilliseconds = 10 * 60_000;
+function payloadFields(payload) {
+    try {
+        return record(JSON.parse(payload));
+    }
+    catch {
+        return undefined;
+    }
+}
+function optionalText(value) {
+    return value === null || typeof value === "string";
+}
+function wellFormed(fields) {
+    return (fields["version"] === 1 &&
+        fields["kind"] === "answer" &&
+        textNames.every((name) => typeof fields[name] === "string") &&
+        countNames.every((name) => {
+            const value = fields[name];
+            return Number.isSafeInteger(value) && Number(value) >= 1;
+        }) &&
+        commands.has(String(fields["command"])) &&
+        keyClasses.has(String(fields["keyClass"])) &&
+        !Number.isNaN(Date.parse(String(fields["signedAt"]))));
+}
+function parsedAnswer(message) {
+    const fields = payloadFields(message.payload);
+    if (fields === undefined || !wellFormed(fields))
+        return undefined;
+    const text = fields["text"] ?? null;
+    const textDigest = fields["textDigest"] ?? null;
+    if (!optionalText(text) || !optionalText(textDigest))
+        return undefined;
+    const value = (name) => String(fields[name]);
+    return {
+        daemonId: value("daemonId"),
+        deviceId: value("deviceId"),
+        decisionId: value("decisionId"),
+        command: value("command"),
+        text,
+        textDigest,
+        expectedRevision: Number(fields["expectedRevision"]),
+        generation: Number(fields["generation"]),
+        subjectDigest: value("subjectDigest"),
+        promptDigest: value("promptDigest"),
+        commandId: value("commandId"),
+        signedAt: Date.parse(value("signedAt")),
+        keyClass: value("keyClass"),
+    };
+}
+function deviceRefusal(device) {
+    if (device === undefined)
+        return "device-unknown";
+    if (device.removedAt !== null)
+        return "device-revoked";
+    if (device.state !== "connected")
+        return "device-not-connected";
+    return undefined;
+}
+function signatureValid(checking) {
+    const { answer, device, message } = checking;
+    const key = publicKeyObject(answer.keyClass === "approval"
+        ? device.approvalPublicKey
+        : device.answerPublicKey);
+    if (key === undefined)
+        return false;
+    try {
+        return verify("sha256", Buffer.from(message.payload), { key, dsaEncoding: "ieee-p1363" }, Buffer.from(message.signature, "base64url"));
+    }
+    catch {
+        return false;
+    }
+}
+function digestOf(text) {
+    return `sha256:${createHash("sha256").update(text).digest("hex")}`;
+}
+const checks = [
+    (checking) => (signatureValid(checking) ? undefined : "signature-invalid"),
+    ({ answer }) => answer.command !== "answer" && answer.keyClass !== "approval"
+        ? "approval-key-required"
+        : undefined,
+    ({ answer, scope }) => Math.abs(scope.now - answer.signedAt) > ageLimitMilliseconds
+        ? "answer-too-old"
+        : undefined,
+    ({ answer, scope }) => scope.sentPromptDigest === answer.promptDigest
+        ? undefined
+        : "prompt-changed",
+    ({ answer }) => {
+        const expected = answer.text === null ? null : digestOf(answer.text);
+        return answer.textDigest === expected ? undefined : "answer-invalid";
+    },
+];
+function decisionParameters(answer) {
+    return {
+        command: answer.command,
+        reference: answer.decisionId,
+        ...(answer.text === null ? {} : { text: answer.text }),
+        expectedRevision: answer.expectedRevision,
+        generation: answer.generation,
+        subjectDigest: answer.subjectDigest,
+        commandId: answer.commandId,
+        actor: `device:${answer.deviceId}`,
+    };
+}
+export function answerDecisionId(message) {
+    const decisionId = payloadFields(message.payload)?.["decisionId"];
+    return typeof decisionId === "string" ? decisionId : null;
+}
+export function answerVerdict(message, scope) {
+    const answer = parsedAnswer(message);
+    if (answer === undefined ||
+        answer.daemonId !== scope.daemonId ||
+        answer.deviceId !== scope.routedDeviceId)
+        return { kind: "refused", code: "answer-invalid", decisionId: null };
+    const device = scope.devices.find((item) => item.deviceId === answer.deviceId);
+    const refusal = deviceRefusal(device) ??
+        (device === undefined
+            ? undefined
+            : checks
+                .map((check) => check({ answer, device, message, scope }))
+                .find((code) => code !== undefined));
+    if (refusal !== undefined)
+        return { kind: "refused", code: refusal, decisionId: answer.decisionId };
+    return {
+        kind: "decision",
+        decisionId: answer.decisionId,
+        parameters: decisionParameters(answer),
+    };
+}

package/dist/src/relay/answer-inbox.d.ts

@@ -0,0 +1,15 @@
+import { type CheckContext } from "./sealed-post.ts";
+export interface InboxReading {
+    readonly waitSeconds: number;
+    readonly signal: AbortSignal;
+}
+export interface InboxTiming {
+    readonly waitSeconds: number;
+    readonly retryMilliseconds: number;
+}
+export declare const inboxTiming: InboxTiming;
+export declare function readAnswers(context: CheckContext, reading: InboxReading): Promise<boolean>;
+export declare function runInbox(context: CheckContext, running: {
+    readonly signal: AbortSignal;
+    readonly timing: InboxTiming;
+}): Promise<void>;

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;