@dcasegr/skein 0.0.0-stage → 0.1.2

package/dist/client/raw.d.ts

@@ -0,0 +1,94 @@
+import { AuthFetch, type WalletInterface } from "@bsv/sdk";
+import { CID } from "multiformats/cid";
+export interface Listed {
+    /** The message's id: its record's CID (text). */
+    messageId: string;
+    /** The sender's identity key (hex). */
+    sender: string;
+    /** The body's dag-cbor bytes. */
+    body: Uint8Array;
+    /** The body decoded. */
+    value: unknown;
+    /** The message itself: its mail record as the messagebox keeps it. */
+    message?: Record<string, unknown>;
+}
+/**
+ * A claim (#127), signed by `wallet` and naming no recipient: a message in
+ * box `claim`, its body {messagebox?, handle?, domain?} (the owner's mailbox
+ * entry, if any), signed by its sender ([2, "metanet handles envelope"], key
+ * "send", counterparty anyone) — the one message a client signs itself (#126
+ * step 4: no session of the instance's carries it). Signed before the instance it claims exists;
+ * the host forwards it into that instance as its first entry, and the kernel
+ * takes the owner from the signer. {message, body: its dag-cbor bytes}.
+ */
+export declare function signClaim(wallet: WalletInterface, body?: {
+    messagebox?: string;
+    handle?: string;
+    domain?: string;
+}, originator?: string): Promise<{
+    message: Record<string, unknown>;
+    body: Uint8Array;
+}>;
+/**
+ * A message signed by `wallet` in its own process (#142): the mail record {kind: "mail", op: "put",
+ * sender, recipient?, box, body: <the body's CID>, nonce, signature}, signed as every message is
+ * ([2, "metanet handles envelope"], key "send", counterparty anyone, over the record's dag-cbor
+ * without `signature`) — what the front door checks on a message carried in `local` (a provider's
+ * answer, a forwarded claim, the operator's message over the host's control socket). `recipient`
+ * (hex) names the instance; a claim names none (#127). {message, body: the body's dag-cbor bytes}.
+ */
+export declare function signMessage(wallet: WalletInterface, m: {
+    recipient?: string;
+    box: string;
+    body: Uint8Array;
+}, originator?: string): Promise<{
+    message: Record<string, unknown>;
+    body: Uint8Array;
+}>;
+export declare class RawBox {
+    readonly url: string;
+    readonly af: AuthFetch;
+    private readonly fetchFn;
+    private readonly wallet;
+    private readonly originator?;
+    private peer?;
+    constructor(wallet: WalletInterface, url: string, o?: {
+        fetch?: typeof fetch;
+        originator?: string;
+    });
+    /**
+     * The session's peer, made here rather than by AuthFetch (#83): the stock
+     * AuthFetch's peer keeps the SDK's default cap on a message's payload
+     * (16 MiB counted at four per byte: about 4 MiB), and an install's
+     * `objects` message carries a module whole (the shell's coreutils is
+     * 10 MB). The peer takes `maxGeneralPayloadBytes: null`, the SDK's own
+     * option for leaving the capacity to the transport; the receiving front
+     * door judges what it takes. Such a request takes seconds to check and
+     * send, so it waits up to five minutes (the SDK's default is 30 s).
+     */
+    private ensurePeer;
+    /** The session, made (the handshake happens on the first request). */
+    ready(): Promise<void>;
+    /** The identity key (hex) the other side's session answers as, once a request has been answered. */
+    peerIdentity(): string | undefined;
+    private post;
+    /**
+     * A message to `recipient` (hex) in `box`: `body` a record (encoded here) or its dag-cbor bytes. Its id.
+     * The BRC-33 message alone (#126 step 4): the session proves who sends it, and nothing in it is signed.
+     */
+    send(recipient: string, box: string, body: unknown): Promise<{
+        id: CID;
+    }>;
+    /**
+     * A BRC-33 request with a JSON body on the session (`path` under the box URL, e.g. "/sendMessage"):
+     * what any BRC-100 wallet's BRC-104 client sends (`1sat authfetch POST <origin>/sendMessage --body @file`,
+     * the owner's admin messages as JSON, src/client/admin.ts messageJson). The status and the answer's text.
+     */
+    postJson(path: string, json: string): Promise<{
+        status: number;
+        text: string;
+    }>;
+    /** The messages in the caller's `box`, oldest first. */
+    list(box: string): Promise<Listed[]>;
+    ack(ids: string[]): Promise<void>;
+}

package/dist/client/raw.js

@@ -0,0 +1,154 @@
+// Raw BRC-33 on a BRC-104 session (#40): what a client speaks to an
+// instance's front door once it knows where it is. No BRC-169 envelope: the
+// session proves who sends, the URL is the recipient's messagebox, the body is
+// dag-cbor (BRC-231: an application/cbor request, recipient and body as
+// bytes). One AuthFetch per box URL — the stock AuthFetch keeps one session
+// per origin, so a URL with a `/@<handle>` path prefix (a host's dev form)
+// gets its handshake sent under the prefix too.
+//
+//   const mb = new RawBox(wallet, "http://127.0.0.1:8100/@martha")   (or http://martha.localhost:8100)
+//   await mb.send(martha, "chat", {text: "hi"})     → {id}: the message's id (what a reply's replyTo names)
+//   await mb.list("chat")                           → [{messageId, sender, body, value}]
+//   await mb.ack([messageId])
+import { AuthFetch, Peer, SimplifiedFetchTransport } from "@bsv/sdk";
+import * as dagCbor from "@ipld/dag-cbor";
+import { CID } from "multiformats/cid";
+import { encode } from "../runtime/cid.js";
+const hexOf = (b) => Buffer.from(b).toString("hex");
+/**
+ * A claim (#127), signed by `wallet` and naming no recipient: a message in
+ * box `claim`, its body {messagebox?, handle?, domain?} (the owner's mailbox
+ * entry, if any), signed by its sender ([2, "metanet handles envelope"], key
+ * "send", counterparty anyone) — the one message a client signs itself (#126
+ * step 4: no session of the instance's carries it). Signed before the instance it claims exists;
+ * the host forwards it into that instance as its first entry, and the kernel
+ * takes the owner from the signer. {message, body: its dag-cbor bytes}.
+ */
+export async function signClaim(wallet, body = {}, originator) {
+    return await signMessage(wallet, { box: "claim", body: dagCbor.encode(body) }, originator);
+}
+/**
+ * A message signed by `wallet` in its own process (#142): the mail record {kind: "mail", op: "put",
+ * sender, recipient?, box, body: <the body's CID>, nonce, signature}, signed as every message is
+ * ([2, "metanet handles envelope"], key "send", counterparty anyone, over the record's dag-cbor
+ * without `signature`) — what the front door checks on a message carried in `local` (a provider's
+ * answer, a forwarded claim, the operator's message over the host's control socket). `recipient`
+ * (hex) names the instance; a claim names none (#127). {message, body: the body's dag-cbor bytes}.
+ */
+export async function signMessage(wallet, m, originator) {
+    const bytes = m.body;
+    const me = (await wallet.getPublicKey({ identityKey: true }, originator)).publicKey;
+    const unsigned = {
+        kind: "mail", op: "put", sender: Uint8Array.from(Buffer.from(me, "hex")),
+        ...(m.recipient ? { recipient: Uint8Array.from(Buffer.from(m.recipient, "hex")) } : {}),
+        box: m.box, body: encode(dagCbor.decode(bytes)).cid, nonce: globalThis.crypto.getRandomValues(new Uint8Array(16)),
+    };
+    const { signature } = await wallet.createSignature({ protocolID: [2, "metanet handles envelope"], keyID: "send", counterparty: "anyone", data: [...dagCbor.encode(unsigned)] }, originator);
+    return { message: { ...unsigned, signature: Uint8Array.from(signature) }, body: bytes };
+}
+export class RawBox {
+    url;
+    af;
+    fetchFn;
+    wallet;
+    originator;
+    peer;
+    constructor(wallet, url, o = {}) {
+        this.url = url.replace(/\/+$/, "");
+        const u = new URL(this.url);
+        const prefix = u.pathname === "/" ? "" : u.pathname;
+        // A bound fetch: the browser's must be called on the window.
+        const base = o.fetch ?? ((input, init) => globalThis.fetch(input, init));
+        // AuthFetch shakes hands at <origin>/.well-known/auth: under the path prefix, if the URL has one.
+        const f = prefix
+            ? ((input, init) => {
+                const s = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+                const w = new URL(s);
+                if (w.origin === u.origin && w.pathname === "/.well-known/auth")
+                    w.pathname = `${prefix}/.well-known/auth`;
+                return base(input instanceof Request ? new Request(w, input) : w.href, init);
+            })
+            : base;
+        this.af = new AuthFetch(wallet, undefined, undefined, o.originator, {}, f);
+        this.fetchFn = f;
+        this.wallet = wallet;
+        this.originator = o.originator;
+    }
+    /**
+     * The session's peer, made here rather than by AuthFetch (#83): the stock
+     * AuthFetch's peer keeps the SDK's default cap on a message's payload
+     * (16 MiB counted at four per byte: about 4 MiB), and an install's
+     * `objects` message carries a module whole (the shell's coreutils is
+     * 10 MB). The peer takes `maxGeneralPayloadBytes: null`, the SDK's own
+     * option for leaving the capacity to the transport; the receiving front
+     * door judges what it takes. Such a request takes seconds to check and
+     * send, so it waits up to five minutes (the SDK's default is 30 s).
+     */
+    ensurePeer(wallet, originator) {
+        this.peer ??= (async () => {
+            const origin = new URL(this.url).origin;
+            const peer = new Peer(wallet, new SimplifiedFetchTransport(origin, this.fetchFn, { requestTimeoutMs: 300_000 }), undefined, undefined, undefined, originator, { maxGeneralPayloadBytes: null });
+            await peer.ready;
+            this.af.peers[origin] = { peer, pendingCertificateRequests: [] };
+        })();
+        return this.peer;
+    }
+    /** The session, made (the handshake happens on the first request). */
+    async ready() { await this.ensurePeer(this.wallet, this.originator); }
+    /** The identity key (hex) the other side's session answers as, once a request has been answered. */
+    peerIdentity() {
+        const p = this.af.peers[new URL(this.url).origin];
+        return p?.identityKey;
+    }
+    async post(path, body) {
+        await this.ensurePeer(this.wallet, this.originator);
+        const r = await this.af.fetch(`${this.url}${path}`, { method: "POST", headers: { "content-type": "application/cbor" }, body: dagCbor.encode(body) });
+        const bytes = new Uint8Array(await r.arrayBuffer());
+        let v = {};
+        try {
+            v = dagCbor.decode(bytes);
+        }
+        catch {
+            v = { status: "error", description: new TextDecoder().decode(bytes) };
+        }
+        return { status: r.status, v };
+    }
+    /**
+     * A message to `recipient` (hex) in `box`: `body` a record (encoded here) or its dag-cbor bytes. Its id.
+     * The BRC-33 message alone (#126 step 4): the session proves who sends it, and nothing in it is signed.
+     */
+    async send(recipient, box, body) {
+        const bytes = body instanceof Uint8Array ? body : dagCbor.encode(body);
+        const to = Uint8Array.from(Buffer.from(recipient, "hex"));
+        const r = await this.post("/sendMessage", { message: { recipient: to, messageBox: box, body: bytes } });
+        if (r.status !== 200)
+            throw new Error(`sendMessage ${box}: HTTP ${r.status} ${String(r.v.code ?? "")} ${String(r.v.description ?? "")}`.trim());
+        return { id: CID.parse(String(r.v.id ?? r.v.messageId)) };
+    }
+    /**
+     * A BRC-33 request with a JSON body on the session (`path` under the box URL, e.g. "/sendMessage"):
+     * what any BRC-100 wallet's BRC-104 client sends (`1sat authfetch POST <origin>/sendMessage --body @file`,
+     * the owner's admin messages as JSON, src/client/admin.ts messageJson). The status and the answer's text.
+     */
+    async postJson(path, json) {
+        await this.ensurePeer(this.wallet, this.originator);
+        const r = await this.af.fetch(`${this.url}${path}`, { method: "POST", headers: { "content-type": "application/json" }, body: json });
+        return { status: r.status, text: await r.text() };
+    }
+    /** The messages in the caller's `box`, oldest first. */
+    async list(box) {
+        const r = await this.post("/listMessages", { messageBox: box });
+        if (r.status !== 200)
+            throw new Error(`listMessages ${box}: HTTP ${r.status} ${String(r.v.description ?? "")}`);
+        return (r.v.messages ?? []).map((m) => ({
+            messageId: m.messageId, sender: hexOf(m.sender), body: m.body, value: dagCbor.decode(m.body), ...(m.message ? { message: m.message } : {}),
+        }));
+    }
+    async ack(ids) {
+        if (!ids.length)
+            return;
+        const r = await this.post("/acknowledgeMessage", { messageIds: ids });
+        if (r.status !== 200)
+            throw new Error(`acknowledgeMessage: HTTP ${r.status} ${String(r.v.description ?? "")}`);
+    }
+}

package/dist/client/target.d.ts

@@ -0,0 +1,34 @@
+import type { CID } from "multiformats/cid";
+import type { WalletInterface } from "@bsv/sdk";
+import { type Vars } from "../host/hostenv.ts";
+import type { InstanceView } from "../host/plan.ts";
+/** A thread at rest: its last update. */
+export interface ThreadEnd {
+    state: string;
+    result?: {
+        stdout?: Uint8Array;
+        [k: string]: unknown;
+    };
+    error?: unknown;
+}
+export interface Target {
+    /** Where the messages go, for the operator's eyes. */
+    where: string;
+    /** The instance's identity key (hex). */
+    identity: string;
+    /** A fresh view of the instance (plan.ts InstanceView). */
+    view(): Promise<InstanceView>;
+    /** One message from the operator into `box`, `body` a record value: its id (the message record's CID). */
+    send(box: string, body: unknown): Promise<CID>;
+    /** The claim (#127): the operator's message in box `claim` (on the host: naming no recipient, as a forwarded claim). */
+    claim(body: Record<string, unknown>): Promise<CID>;
+    /** The thread the message `id` launched, once it comes to rest. */
+    answer(id: CID, timeoutMs?: number): Promise<ThreadEnd>;
+    close(): Promise<void>;
+}
+/** An instance on this host machine (`--instance <handle>`): host.db's row, its store read-only, the control socket. */
+export declare function localTarget(vars: Vars, handle: string, wallet: WalletInterface): Target;
+/** An instance at `origin`: one BRC-104 session for its messages and its explorer's reads (the operator's, as its owner). */
+export declare function remoteTarget(origin: string, wallet: WalletInterface): Promise<Target>;
+/** A step's answer as the program wrote it to stdout (dag-cbor, else DAG-JSON). */
+export declare function stdoutOf(u: ThreadEnd): Record<string, unknown> | undefined;

package/dist/client/target.js

@@ -0,0 +1,158 @@
+// Where the operator's messages go (#142). Signing is the client's own
+// (raw.ts signMessage, with the operator's key: hostenv.ts operatorKey);
+// delivery is only a question of which host the message is going to:
+//
+//   --instance <handle>   an instance on this host machine: its row in
+//                         $SKEIN_HOME/host.db, its store read read-only (the
+//                         plan's view, a thread's answer), each message signed
+//                         here and handed to the running host over its control
+//                         socket ($SKEIN_HOME/host.sock, op `message`: appended
+//                         as a signed `local` request, the path a forwarded
+//                         claim takes)
+//   <origin>              an instance anywhere: one BRC-104 session (@bsv/sdk's
+//                         Peer/AuthFetch, raw.ts RawBox) carries the messages
+//                         (dag-cbor bodies) and the explorer's reads
+//
+// No other process is started: no wallet command, no handshake per message.
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import * as dagCbor from "@ipld/dag-cbor";
+import * as dagJson from "@ipld/dag-json";
+import { encode } from "../runtime/cid.js";
+import { storeSpec } from "../runtime/index-store.js";
+import { openStoreFile, storeExists } from "../host/stores.js";
+import { CONTROL_SOCKET, controlRequest } from "../host/control.js";
+import { homeOf } from "../host/hostenv.js";
+import { HostDb } from "../host/instances.js";
+import { instanceView } from "../host/install.js";
+import { explorerView } from "./admin.js";
+import { RawBox, signMessage } from "./raw.js";
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const b64 = (b) => Buffer.from(b).toString("base64");
+/** Poll `look` (500 ms, doubling to 5 s) until it answers, or fail past `timeoutMs`. */
+async function until(what, look, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    for (let wait = 250;; wait = Math.min(wait * 2, 5000)) {
+        const v = await look();
+        if (v !== undefined)
+            return v;
+        if (Date.now() > deadline)
+            throw new Error(`${what}: no answer in ${Math.round(timeoutMs / 1000)} s`);
+        await sleep(wait);
+    }
+}
+const atRest = (u) => !!u && (u.state === "finished" || u.state === "errored");
+/** An instance on this host machine (`--instance <handle>`): host.db's row, its store read-only, the control socket. */
+export function localTarget(vars, handle, wallet) {
+    const home = homeOf(vars);
+    const dbPath = join(home, "host.db");
+    if (!existsSync(dbPath))
+        throw new Error(`--instance ${handle}: no host here (${dbPath}; SKEIN_HOME)`);
+    const db = new HostDb(dbPath, { readOnly: true });
+    const row = db.get(handle);
+    db.close();
+    if (!row)
+        throw new Error(`--instance ${handle}: no such instance on this host`);
+    if (!row.identity)
+        throw new Error(`--instance ${handle}: it has no identity yet (never booted)`);
+    const sock = join(home, CONTROL_SOCKET);
+    const opened = [];
+    const openOnce = () => {
+        if (!storeExists(storeSpec(row)))
+            throw new Error(`${handle}: no store at ${storeSpec(row)} yet`);
+        return openStoreFile(storeSpec(row), { readOnly: true });
+    };
+    // A view's store stays open while the view is used (until close).
+    const open = () => { const s = openOnce(); opened.push(s); return s; };
+    const deliver = async (m) => {
+        const a = await controlRequest(sock, { op: "message", handle, message: b64(dagCbor.encode(m.message)), body: b64(m.body) }, 600_000);
+        if (!a)
+            throw new Error(`no host answers on ${sock}: start it (skein-host run)`);
+        if (!a.ok)
+            throw new Error(a.error);
+        return encode(m.message).cid;
+    };
+    return {
+        where: `${handle} (this host)`,
+        identity: row.identity,
+        view: async () => await instanceView(open()),
+        send: async (box, body) => await deliver(await signMessage(wallet, { recipient: row.identity, box, body: dagCbor.encode(body) })),
+        claim: async (body) => await deliver(await signMessage(wallet, { box: "claim", body: dagCbor.encode(body) })),
+        answer: (id, timeoutMs = 300_000) => until(`the thread of ${id}`, async () => {
+            const s = openOnce();
+            try {
+                for (const e of await s.edges.refsTo(id)) {
+                    if (e.rel !== "launched-by" || !e.from)
+                        continue;
+                    const u = await s.get(await s.chains.tip(e.from)).catch(() => undefined);
+                    if (atRest(u))
+                        return u;
+                }
+                return undefined;
+            }
+            finally {
+                s.close();
+            }
+        }, timeoutMs),
+        close: async () => { for (const s of opened.splice(0))
+            s.close(); },
+    };
+}
+/** An instance at `origin`: one BRC-104 session for its messages and its explorer's reads (the operator's, as its owner). */
+export async function remoteTarget(origin, wallet) {
+    const url = origin.replace(/\/+$/, "");
+    const box = new RawBox(wallet, url);
+    const get = async (path) => {
+        await box.ready();
+        return await box.af.fetch(`${url}${path}`, { method: "GET" });
+    };
+    const read = async (path) => {
+        const r = await get(`/explore${path}`);
+        const bytes = new Uint8Array(await r.arrayBuffer());
+        if (r.status === 404)
+            return undefined;
+        if (r.status !== 200)
+            throw new Error(`GET ${url}/explore${path}: ${r.status} ${new TextDecoder().decode(bytes).slice(0, 200)}${r.status === 403 ? " (the explorer is the owner's: is the operator's key this instance's owner?)" : ""}`);
+        return dagJson.decode(bytes);
+    };
+    // Who answers: the session's peer (the instance's identity), learnt on the first signed request.
+    const first = await get("/explore");
+    await first.arrayBuffer();
+    const identity = box.peerIdentity() ?? first.headers.get("x-bsv-auth-identity-key") ?? "";
+    if (!/^0[23][0-9a-f]{64}$/.test(identity))
+        throw new Error(`${url}: no BRC-104 identity answered (is it a skein's origin?)`);
+    return {
+        where: url,
+        identity,
+        view: async () => await explorerView(read),
+        send: async (b, body) => (await box.send(identity, b, body)).id,
+        claim: async (body) => (await box.send(identity, "claim", body)).id,
+        answer: (id, timeoutMs = 300_000) => until(`the thread of ${id}`, async () => {
+            const e = await read(`/edges/${id}?rel=launched-by`);
+            for (const edge of e?.edges ?? []) {
+                const t = await read(`/thread/${edge.from}`);
+                const last = t?.updates?.at(-1)?.record;
+                if (atRest(last))
+                    return last;
+            }
+            return undefined;
+        }, timeoutMs),
+        close: async () => { },
+    };
+}
+/** A step's answer as the program wrote it to stdout (dag-cbor, else DAG-JSON). */
+export function stdoutOf(u) {
+    const b = u.result?.stdout;
+    if (!(b instanceof Uint8Array) || !b.length)
+        return undefined;
+    try {
+        return dagCbor.decode(b);
+    }
+    catch { /* not dag-cbor */ }
+    try {
+        return dagJson.decode(b);
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/dev/cli.d.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env -S node --experimental-strip-types --no-warnings
+import type { CID } from "multiformats/cid";
+import type { SqliteStore } from "../runtime/sqlite.ts";
+export declare const dbPath: () => string;
+/** Put the pinned wasm modules into the store under their CIDs (the shell's are the shell app's, #83: installed with it). */
+export declare function install(store: Pick<SqliteStore, "has" | "putBlock">): Promise<string[]>;
+export declare function resolveCid(store: Pick<SqliteStore, "findByPrefix">, s: string): Promise<CID>;
+export declare function main(argv: string[]): Promise<number>;