@dcasegr/skein 0.0.0-stage → 0.1.2

package/dist/host/deliver.js

@@ -0,0 +1,251 @@
+// The `deliver` intention (#157): a message to a `mailbox` recipient, carried
+// by the HOST — a step never waits on the outside world. The instance's
+// delivery thread (programs/messagebox/deliver.zig) emits
+//
+//   {kind: "event", event: "deliver", app?, transport: "mailbox", url, message: <the mail record>,
+//    nonce: bytes(32)}            the nonce: sha256(thread ‖ step ‖ place) — the kernel's
+//
+// and awaits it. The host makes the exchange the kernel's authfetch used to
+// make in the step (kernel-zig/src/authfetch.zig before #157):
+//
+//   1. BRC-103's handshake at <url>/.well-known/auth, the session kept per
+//      (instance, base URL) in memory — made again when the server answers
+//      401 (it forgot the session) — its answer's signature checked;
+//   2. the BRC-104 request: POST <url>/sendMessage, BRC-231 CBOR {message:
+//      {recipient, messageBox, body, subject?, nonce}} (the BRC-33 message and
+//      the emit's own subject and nonce: the recipient keeps the record under
+//      the same CID), the request id = the event's nonce (so is the request's
+//      x-bsv-auth-nonce: everything about it derives from the emit's place),
+//      signed by the instance's key through its wallet (the signer the kernel
+//      asks), outside any step;
+//   3. the answer, as the record the instance admits (box `deliver`): {kind:
+//      "delivery", replyTo: <the event>, peer, nonce: <our session nonce>,
+//      yourNonce: <the answer's nonce>, signature, status, headers?: <the
+//      answer's signed headers>, body} — it stands on its own at the door
+//      (door.zig deliveryAnswer: the server's signature over it).
+//
+// No answer, or an unsigned one (something in front of the server): nothing
+// to admit — the thread rests, and the kernel offers the intention again at
+// its next start. No timers, no retries but the one fresh handshake a 401 on a
+// held session calls for (BRC-103's own).
+import * as dagCbor from "@ipld/dag-cbor";
+export const AUTH_PROTOCOL = [2, "auth message signature"];
+const VERSION = "0.1";
+const hex = (b) => Buffer.from(b).toString("hex");
+const b64 = (b) => Buffer.from(b).toString("base64");
+// ---------------------------------------------------------------- SimplifiedFetchTransport's framing
+class W {
+    parts = [];
+    varint(v) {
+        if (v < 0) {
+            this.parts.push(0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff);
+            return;
+        } // -1: absent
+        if (v < 0xfd)
+            this.parts.push(v);
+        else if (v <= 0xffff)
+            this.parts.push(0xfd, v & 0xff, v >> 8);
+        else if (v <= 0xffffffff) {
+            const b = Buffer.alloc(4);
+            b.writeUInt32LE(v);
+            this.parts.push(0xfe, ...b);
+        }
+        else {
+            const b = Buffer.alloc(8);
+            b.writeBigUInt64LE(BigInt(v));
+            this.parts.push(0xff, ...b);
+        }
+    }
+    bytes(b) { for (const x of b)
+        this.parts.push(x); }
+    field(b) { if (b.length === 0)
+        this.varint(-1);
+    else {
+        this.varint(b.length);
+        this.bytes(b);
+    } }
+    out() { return Uint8Array.from(this.parts); }
+}
+const utf8 = (s) => new TextEncoder().encode(s);
+/** The headers a request signs: x-bsv-* (not x-bsv-auth*), content-type (its media type), authorization; lower-cased, sorted. */
+function signedRequestHeaders(h) {
+    const out = [];
+    for (const [k0, v0] of Object.entries(h)) {
+        const k = k0.toLowerCase();
+        let v = v0;
+        if (k === "content-type")
+            v = v.split(";")[0].trim();
+        if ((k.startsWith("x-bsv-") || k === "content-type" || k === "authorization") && !k.startsWith("x-bsv-auth"))
+            out.push([k, v]);
+    }
+    return out.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+}
+/** The payload a request signs (authfetch.zig requestPayload). */
+export function requestPayload(rid, method, path, query, headers, body) {
+    const w = new W();
+    w.bytes(rid);
+    const m = utf8(method);
+    w.varint(m.length);
+    w.bytes(m);
+    w.field(utf8(path));
+    w.field(utf8(query));
+    const hs = signedRequestHeaders(headers);
+    w.varint(hs.length);
+    for (const [k, v] of hs) {
+        const kb = utf8(k), vb = utf8(v);
+        w.varint(kb.length);
+        w.bytes(kb);
+        w.varint(vb.length);
+        w.bytes(vb);
+    }
+    w.field(body);
+    return w.out();
+}
+/** The answer's signed headers: x-bsv-* but x-bsv-auth-*, and authorization; lower-cased. */
+export function signedResponseHeaders(h) {
+    const out = {};
+    for (const [k0, v] of Object.entries(h)) {
+        const k = k0.toLowerCase();
+        if ((k.startsWith("x-bsv-") && !k.startsWith("x-bsv-auth")) || k === "authorization")
+            out[k] = v;
+    }
+    return out;
+}
+/** The payload a response signs (authfetch.zig responsePayload): request id, status, the signed headers sorted, the body. */
+export function responsePayload(rid, status, headers, body) {
+    const w = new W();
+    w.bytes(rid);
+    w.varint(status);
+    const hs = Object.entries(headers).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    w.varint(hs.length);
+    for (const [k, v] of hs) {
+        const kb = utf8(k), vb = utf8(v);
+        w.varint(kb.length);
+        w.bytes(kb);
+        w.varint(vb.length);
+        w.bytes(vb);
+    }
+    w.field(body);
+    return w.out();
+}
+export class Deliverer {
+    o;
+    /** BRC-103 sessions, per instance and server base URL, in memory. */
+    sessions = new Map();
+    constructor(o) { this.o = o; }
+    /**
+     * Carry one `deliver` event for instance `handle` (its wallet: the instance's key), its mail record
+     * and the body's dag-cbor bytes: the answer to admit, or undefined (no answer that stands).
+     */
+    async carry(handle, wallet, eventCid, ev, mail, body) {
+        if (ev.transport !== "mailbox")
+            throw new Error(`deliver: no transport ${ev.transport} here`);
+        if (!(ev.nonce instanceof Uint8Array) || ev.nonce.length !== 32)
+            throw new Error("deliver: the event has no 32-byte nonce");
+        const base = ev.url.replace(/\/+$/, "");
+        const identity = (await wallet.getPublicKey({ identityKey: true })).publicKey;
+        const key = `${handle} ${base}`;
+        const message = { recipient: mail.recipient, messageBox: mail.box, body, nonce: mail.nonce };
+        if (mail.subject)
+            message.subject = mail.subject;
+        const reqBody = dagCbor.encode({ message });
+        for (let fresh = false;; fresh = true) {
+            let s = this.sessions.get(key);
+            const held = !!s && !fresh;
+            if (!s || fresh) {
+                s = await this.handshake(handle, wallet, identity, base);
+                if (!s)
+                    return undefined;
+                this.sessions.set(key, s);
+            }
+            const r = await this.send(handle, wallet, identity, base, s, ev.nonce, reqBody);
+            if (!r)
+                return undefined;
+            if (r.status === 401 && held) {
+                this.sessions.delete(key);
+                continue;
+            } // the server forgot the session: shake hands again, once
+            const sig = r.headers["x-bsv-auth-signature"];
+            if (!sig) {
+                this.o.log?.(handle, `deliver → ${base}: HTTP ${r.status}, unsigned: nothing to admit (the thread rests; offered again at the next start)`);
+                return undefined;
+            }
+            const from = r.headers["x-bsv-auth-identity-key"] ?? "";
+            if (from !== s.server) {
+                this.o.log?.(handle, `deliver → ${base}: the answer is from another identity than the session's: nothing to admit`);
+                return undefined;
+            }
+            const headers = signedResponseHeaders(r.headers);
+            return {
+                kind: "delivery", replyTo: eventCid, peer: Uint8Array.from(Buffer.from(s.server, "hex")), nonce: s.ours, yourNonce: r.headers["x-bsv-auth-nonce"] ?? "",
+                signature: Uint8Array.from(Buffer.from(sig, "hex")), status: r.status, ...(Object.keys(headers).length ? { headers } : {}), body: r.body,
+            };
+        }
+    }
+    /** BRC-103: our nonce to <base>/.well-known/auth; the answer's signature over both nonces checked. */
+    async handshake(handle, wallet, identity, base) {
+        const first = globalThis.crypto.getRandomValues(new Uint8Array(16)).map((b) => 33 + (b % 94)); // printable: the keyID reads the same as UTF-8 on every side
+        const { hmac } = await wallet.createHmac({ protocolID: [2, "server hmac"], keyID: new TextDecoder().decode(first), data: [...first], counterparty: "self" });
+        const ours = b64([...first, ...hmac]);
+        const body = JSON.stringify({ version: VERSION, messageType: "initialRequest", identityKey: identity, initialNonce: ours, requestedCertificates: { certifiers: [], types: {} } });
+        let r;
+        try {
+            r = await this.o.http({ method: "POST", url: `${base}/.well-known/auth`, headers: { "content-type": "application/json" }, body: utf8(body) }, handle);
+        }
+        catch (e) {
+            this.o.log?.(handle, `deliver → ${base}: handshake: ${e.message} (the thread rests)`);
+            return undefined;
+        }
+        if (r.status !== 200) {
+            this.o.log?.(handle, `deliver → ${base}: handshake: HTTP ${r.status} (the thread rests)`);
+            return undefined;
+        }
+        let j;
+        try {
+            j = JSON.parse(new TextDecoder().decode(r.body));
+        }
+        catch {
+            this.o.log?.(handle, `deliver → ${base}: handshake: the answer is not JSON`);
+            return undefined;
+        }
+        if (typeof j.identityKey !== "string" || typeof j.initialNonce !== "string" || j.yourNonce !== ours || !Array.isArray(j.signature)) {
+            this.o.log?.(handle, `deliver → ${base}: handshake: a malformed answer`);
+            return undefined;
+        }
+        const data = [...Buffer.from(ours, "base64"), ...Buffer.from(j.initialNonce, "base64")];
+        try {
+            const { valid } = await wallet.verifySignature({ protocolID: AUTH_PROTOCOL, keyID: `${ours} ${j.initialNonce}`, counterparty: j.identityKey, data, signature: j.signature });
+            if (!valid)
+                throw new Error("invalid");
+        }
+        catch {
+            this.o.log?.(handle, `deliver → ${base}: handshake: the server's signature does not verify`);
+            return undefined;
+        }
+        return { server: j.identityKey, ours, theirs: j.initialNonce };
+    }
+    /** BRC-104: the request signed on the session (request id and nonce = the event's nonce). Undefined: no answer. */
+    async send(handle, wallet, identity, base, s, rid, body) {
+        const u = new URL(base);
+        const path = `${u.pathname === "/" ? "" : u.pathname}/sendMessage`;
+        const headers = { "content-type": "application/cbor" };
+        const nonce = b64(rid);
+        const payload = requestPayload(rid, "POST", path, "", headers, body);
+        const { signature } = await wallet.createSignature({ protocolID: AUTH_PROTOCOL, keyID: `${nonce} ${s.theirs}`, counterparty: s.server, data: [...payload] });
+        const all = {
+            ...headers, "x-bsv-auth-version": VERSION, "x-bsv-auth-identity-key": identity, "x-bsv-auth-nonce": nonce,
+            "x-bsv-auth-your-nonce": s.theirs, "x-bsv-auth-signature": hex(signature), "x-bsv-auth-request-id": nonce,
+        };
+        try {
+            const r = await this.o.http({ method: "POST", url: `${u.origin}${path}`, headers: all, body }, handle);
+            const lower = {};
+            for (const [k, v] of Object.entries(r.headers))
+                lower[k.toLowerCase()] = v;
+            return { status: r.status, headers: lower, body: r.body };
+        }
+        catch (e) {
+            this.o.log?.(handle, `deliver → ${base}: ${e.message} (the thread rests; offered again at the next start)`);
+            return undefined;
+        }
+    }
+}

package/dist/host/deploy.d.ts

@@ -0,0 +1,29 @@
+import type { Store } from "../runtime/store.ts";
+/** What goes in by default: the personality and its file-only skills (#24), not the code around them. */
+export declare const DEFAULT_ONLY: string[];
+/**
+ * scan's `ignore` for `--only`: a path is kept if a pattern names it or a
+ * directory above it (a pattern naming a directory takes all of it), or if it
+ * is a directory on the way to what a pattern names. Patterns are
+ * "/"-separated from the directory's root, `*` and `?` within one segment.
+ * .git and node_modules are never kept.
+ */
+export declare function onlyIgnore(dir: string, patterns: string[]): (rel: string) => boolean;
+/**
+ * An address-book entry (#70): how to reach a key — its transport
+ * (`mailbox`: a messagebox URL over BRC-103/104; `libp2p`: a peer ID or
+ * `topic:<name>`; `local`: a host provider's name) and address, and
+ * optionally its handle (#126: no role). The instance keeps them under the head `peers` (programs/resolve);
+ * `source` says who wrote one (`genesis`, `admin`: the `peers` box,
+ * `resolve`: its own BRC-169 lookup, `claim`).
+ */
+export interface AddressEntry {
+    key: string;
+    transport: "mailbox" | "libp2p" | "local";
+    address: string;
+    handle?: string;
+    domain?: string;
+    source?: string;
+}
+/** The row's address book as its store holds it now (empty with no store or no entries). */
+export declare function addressBook(store: Store | undefined): Promise<AddressEntry[]>;

package/dist/host/deploy.js

@@ -0,0 +1,55 @@
+// A directory into an instance (#23) and its address book (#40, #70): the
+// pieces the owner's messages are built from (#124: src/client/admin.ts
+// planDeploy, planPeers; `skein deploy|peers`). A deploy is the
+// directory's git objects in ≤ 1 MiB bundles to the instance's `objects` box,
+// the root tree on the last — the kernel sets `main` from it when there is
+// none — then `head {name: "main", tree}` when `main` is another tree. Which
+// files go in is `onlyIgnore` (default DEFAULT_ONLY: the personality and its
+// skills, #24). The owner's wallet sends them; nothing here does.
+import { lstatSync } from "node:fs";
+import { join } from "node:path";
+import { defaultIgnore } from "../dev/scan.js";
+import { headTree } from "../runtime/heads.js";
+/** What goes in by default: the personality and its file-only skills (#24), not the code around them. */
+export const DEFAULT_ONLY = ["SOUL.md", "IDENTITY.md", "skills"];
+const segment = (p) => new RegExp(`^${p.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, "[^/]*").replace(/\?/g, "[^/]")}$`);
+/**
+ * scan's `ignore` for `--only`: a path is kept if a pattern names it or a
+ * directory above it (a pattern naming a directory takes all of it), or if it
+ * is a directory on the way to what a pattern names. Patterns are
+ * "/"-separated from the directory's root, `*` and `?` within one segment.
+ * .git and node_modules are never kept.
+ */
+export function onlyIgnore(dir, patterns) {
+    const pats = patterns.map((p) => p.split("/").filter(Boolean).map(segment)).filter((p) => p.length);
+    return (rel) => {
+        if (defaultIgnore(rel))
+            return true;
+        const segs = rel.split("/");
+        for (const p of pats) {
+            if (!p.slice(0, segs.length).every((re, i) => re.test(segs[i])))
+                continue;
+            if (segs.length >= p.length)
+                return false;
+            if (lstatSync(join(dir, rel)).isDirectory())
+                return false;
+        }
+        return true;
+    };
+}
+const hexKey = (k) => k instanceof Uint8Array ? Buffer.from(k).toString("hex") : typeof k === "string" ? k : "";
+/** The row's address book as its store holds it now (empty with no store or no entries). */
+export async function addressBook(store) {
+    if (!store || !(await store.log.tip()))
+        return [];
+    const root = await headTree(store, "peers");
+    if (!root)
+        return [];
+    const t = await store.get(root);
+    const out = [];
+    for (const e of t.peers ?? []) {
+        const p = await store.get(e.peer);
+        out.push({ key: hexKey(p.key ?? e.key), transport: p.transport ?? "mailbox", address: p.address ?? "", ...(p.handle ? { handle: p.handle } : {}), ...(p.domain ? { domain: p.domain } : {}), ...(p.source ? { source: p.source } : {}) });
+    }
+    return out;
+}

package/dist/host/door-answer.d.ts

@@ -0,0 +1,24 @@
+/**
+ * What the kernel's door answered without writing an entry (#143): a filter's rejection or answer
+ * (a read route's), or the gate's refusal. `admit` throws it: the request was never admitted.
+ */
+export interface DoorAnswer {
+    kind: "reject" | "answer";
+    status: number;
+    code?: string;
+    reason?: string;
+    type?: string;
+    headers?: Record<string, string>;
+    body?: Uint8Array;
+    /** Who the filters said it was from, if they got that far (the host's meter). */
+    principal?: Uint8Array;
+    /** The filters' fuel (an app's filter runs as a call): the host's meter. */
+    fuel: number;
+}
+/** A request the kernel's door turned away or answered (#143): nothing was written. */
+export declare class DoorAnswered extends Error {
+    readonly answer: DoorAnswer;
+    constructor(answer: DoorAnswer);
+}
+/** The kernel's `answered` frame as a DoorAnswer (absent fields left out). */
+export declare function doorAnswer(x: Record<string, unknown>): DoorAnswer;

package/dist/host/door-answer.js

@@ -0,0 +1,21 @@
+// What the kernel's door answers without writing an entry (#143): a filter's rejection or answer
+// (a read route's), or the gate's refusal — the `admit` frame's `{answered: {…}}`. No node APIs: the
+// node host (kernel.ts) and the browser host (web/kernel/host.ts) both read it.
+/** A request the kernel's door turned away or answered (#143): nothing was written. */
+export class DoorAnswered extends Error {
+    answer;
+    constructor(answer) {
+        super(`${answer.kind === "answer" ? "answered" : "turned away"} at the door: ${answer.status}${answer.reason ? ` ${answer.reason}` : ""}`);
+        this.answer = answer;
+    }
+}
+/** The kernel's `answered` frame as a DoorAnswer (absent fields left out). */
+export function doorAnswer(x) {
+    return {
+        kind: x.kind === "answer" ? "answer" : "reject", status: Number(x.status ?? 500), fuel: Number(x.fuel ?? 0),
+        ...(typeof x.code === "string" ? { code: x.code } : {}), ...(typeof x.reason === "string" ? { reason: x.reason } : {}),
+        ...(typeof x.type === "string" ? { type: x.type } : {}),
+        ...(x.headers && typeof x.headers === "object" ? { headers: x.headers } : {}),
+        ...(x.body instanceof Uint8Array ? { body: x.body } : {}), ...(x.principal instanceof Uint8Array ? { principal: x.principal } : {}),
+    };
+}

package/dist/host/events.d.ts

@@ -0,0 +1,89 @@
+import type { CID } from "multiformats/cid";
+import type { Store } from "../runtime/store.ts";
+/** The store a fold reads (a store file opened read-only), closed after. */
+export type EventStore = Pick<Store, "get" | "chains" | "edges" | "bytes"> & {
+    close(): unknown;
+};
+/** One emitted event as the stream sends it. */
+export interface Delivered {
+    /** Its place: `<n>.<seq>.<i>.<thread>`. */
+    id: string;
+    n: number;
+    event: string;
+    app: string;
+    topic: string;
+    /** The record as DAG-JSON. */
+    data: string;
+}
+/** A subscription's request: the app, the event's name, the topics; and where it resumes (Last-Event-ID). */
+export interface EventsQuery {
+    app: string;
+    event: string;
+    topics: string[];
+    after?: string;
+}
+/** The query of GET /<app>/.events (`event`, `topic` repeated) and Last-Event-ID, or why it is not one. */
+export declare function eventsQuery(app: string, params: URLSearchParams, lastEventId: string | undefined): EventsQuery | {
+    problem: string;
+};
+/** An event id's parts, or undefined. */
+export declare function placeOf(id: string): {
+    n: number;
+    seq: number;
+    i: number;
+    thread: string;
+} | undefined;
+/** One event as an SSE message. */
+export declare function sseMessage(d: Delivered): string;
+/** Every event record a stream serves in the log, in log order, as delivered (resume and the current value). */
+export declare function foldEvents(store: EventStore): Promise<Delivered[]>;
+/** What a subscription is sent first (folded from the log): after its Last-Event-ID, else the last per topic. */
+export declare function backlog(all: Delivered[], q: EventsQuery): Delivered[];
+/** An event's place in the log, as the kernel's `emit` notice carries it beside the record (#148). */
+export interface Place {
+    n: number;
+    seq: number;
+    i: number;
+    thread: CID;
+}
+/** The id of the event at `p`: `<n>.<seq>.<i>.<thread>` — the fold's (foldEvents), free from the notice. */
+export declare const idOf: (p: Place) => string;
+/** A handed-over event as delivered, or undefined when it is not one a stream serves (no app, no topic). */
+export declare function deliveredOf(rec: Record<string, unknown>, p: Place): Delivered | undefined;
+export interface EventStreamsOptions {
+    /** The instance's store, read-only (undefined: none). */
+    open(handle: string): EventStore | undefined;
+}
+/** The registry of open subscriptions, per instance (#148). */
+export declare class EventStreams {
+    private subs;
+    /** Per instance: the ids handed over lately, in order: one handed over again is not sent again. */
+    private sent;
+    private readonly o;
+    constructor(o: EventStreamsOptions);
+    /** Whether `handle` has an open subscription. */
+    open(handle: string): boolean;
+    /** How many subscriptions `handle` has open (tests). */
+    count(handle: string): number;
+    /**
+     * Open a subscription for `handle`: its backlog folded from the log and sent, then each new
+     * matching event as it is handed over (what came during the fold, after it, once). `send` writes
+     * one event; `close` ends the stream (the host's: an uninstall, the instance stopping). The
+     * returned function forgets it (the client went).
+     */
+    subscribe(handle: string, q: EventsQuery, send: (d: Delivered) => void, close: () => void): Promise<() => void>;
+    /**
+     * An event handed over for `handle` (after its step's commit), with its place in the log: sent
+     * as it is to each open subscription it matches — no log read. One handed over again (a start
+     * re-offers what a waiting thread awaits) is not sent again.
+     */
+    emitted(handle: string, rec: Record<string, unknown>, place: Place): void;
+    /** The apps `handle` has installed now (rows in its dispatch table): the others' subscriptions close. */
+    keep(handle: string, apps: Set<string>): void;
+    /** Close every subscription of `handle` (it stops). */
+    drop(handle: string): void;
+    /** Close them all (the host shuts down). */
+    stop(): void;
+    private remove;
+    private end;
+}