@dcasegr/skein 0.0.0-stage → 0.1.2

package/dist/envelope-cbor.js

@@ -0,0 +1,160 @@
+// BRC-169 §7.3 envelopes — the dag-cbor form (issue #33, #21; BRC-231 bodies):
+// the §7.2 members with identity key, contentHash and signature as byte
+// strings and `content` the BRC-78 bytes; the signature over SHA-256 of the
+// dag-cbor of the map without `content` and `signature` (no canonicalisation
+// step: dag-cbor is deterministic). Same signing key as §7.2 (skein's: [2,
+// "metanet handles envelope"], key "send", counterparty anyone). A signature is
+// over the encoding it was made in, so a relay delivers an envelope in the
+// encoding it was submitted in and never transcodes; the kernel keeps each in
+// its own form (the SDK's lib/message.zig). A message's id is the CID of its
+// signed part as kept.
+import { createHash, randomBytes } from "node:crypto";
+import * as dagCbor from "@ipld/dag-cbor";
+import { brc78Decode, brc78Encode, ENVELOPE_KEY_ID, ENVELOPE_PROTOCOL, isEnvelope, MESSAGE_ENCRYPTION, signedPart, verify } from "./envelope.js";
+import { verifyAnyone } from "./runtime/identity.js";
+import { encode } from "./runtime/cid.js";
+import { CID } from "multiformats/cid";
+const hex = (b) => Buffer.from(b).toString("hex");
+const isBytes = (x) => x instanceof Uint8Array;
+export function isCborSigned(x) {
+    const e = x;
+    return !!e && typeof e === "object" && e.metanetHandles === "1.0" && !!e.recipient && typeof e.recipient.handle === "string" && typeof e.recipient.domain === "string"
+        && !!e.sender && isBytes(e.sender.identityKey) && e.sender.identityKey.length === 33 && typeof e.created === "string"
+        && isBytes(e.contentHash) && e.contentHash.length === 32 && isBytes(e.signature);
+}
+export const isCborEnvelope = (x) => isCborSigned(x) && isBytes(x.content);
+/** The preimage: dag-cbor of the envelope without content and signature. */
+export function preimage(env) {
+    const { content: _c, signature: _s, ...rest } = env;
+    return dagCbor.encode(strip(rest));
+}
+export function cborSignedPart(env) {
+    const { content: _c, ...rest } = env;
+    return rest;
+}
+export function verifyCbor(env) {
+    if (!isCborSigned(env))
+        return false;
+    const key = hex(env.sender.identityKey);
+    const c = env.content;
+    if (c !== undefined) {
+        try {
+            if (brc78Decode(c).sender !== key)
+                return false;
+        }
+        catch {
+            return false;
+        }
+    }
+    return verifyAnyone(key, ENVELOPE_PROTOCOL, ENVELOPE_KEY_ID, preimage(env), env.signature);
+}
+/** Seal `body` (dag-cbor) to `recipient` in the §7.3 form. */
+export async function sealCbor(wallet, args) {
+    const { publicKey: me } = await wallet.getPublicKey({ identityKey: true });
+    const unsigned = strip({
+        metanetHandles: "1.0",
+        recipient: { handle: args.recipient.handle, domain: args.recipient.domain },
+        sender: { identityKey: Uint8Array.from(Buffer.from(me, "hex")), handle: args.sender?.handle, domain: args.sender?.domain },
+        created: args.created ?? new Date().toISOString(),
+        contentHash: Uint8Array.from(createHash("sha256").update(args.body).digest()),
+    });
+    const hash = [...createHash("sha256").update(preimage(unsigned)).digest()];
+    const { signature } = await wallet.createSignature({ hashToDirectlySign: hash, protocolID: ENVELOPE_PROTOCOL, keyID: ENVELOPE_KEY_ID, counterparty: "anyone" });
+    const keyId = new Uint8Array(randomBytes(32));
+    const { ciphertext } = await wallet.encrypt({ protocolID: MESSAGE_ENCRYPTION, keyID: Buffer.from(keyId).toString("base64"), counterparty: args.recipient.identityKey, plaintext: [...args.body] });
+    const content = brc78Encode({ sender: me, recipient: args.recipient.identityKey, keyId, ciphertext: Uint8Array.from(ciphertext) });
+    return { ...unsigned, content, signature: Uint8Array.from(signature) };
+}
+/** Decrypt a §7.3 envelope's content as its recipient; checked against contentHash. */
+export async function openCbor(wallet, env) {
+    const m = brc78Decode(env.content);
+    const { publicKey: me } = await wallet.getPublicKey({ identityKey: true });
+    if (m.recipient !== me)
+        throw new Error(`envelope: addressed to ${m.recipient}, not this wallet (${me})`);
+    const { plaintext } = await wallet.decrypt({ protocolID: MESSAGE_ENCRYPTION, keyID: Buffer.from(m.keyId).toString("base64"), counterparty: m.sender, ciphertext: [...m.ciphertext] });
+    const body = Uint8Array.from(plaintext);
+    if (!Buffer.from(createHash("sha256").update(body).digest()).equals(Buffer.from(env.contentHash)))
+        throw new Error("envelope: the content does not match its signed contentHash");
+    return { body, senderIdentityKey: m.sender };
+}
+export function formOf(x) {
+    if (isCborEnvelope(x))
+        return "cbor";
+    if (isEnvelope(x))
+        return "json";
+    return undefined;
+}
+/** The sender's identity key (hex), the recipient (hex, from BRC-78), whether the signature verifies, the signed part and the message id (its CID as kept). */
+export function inspect(env) {
+    if (isCborEnvelope(env)) {
+        const signed = cborSignedPart(env);
+        return { form: "cbor", sender: hex(env.sender.identityKey), recipient: brc78Decode(env.content).recipient, verified: verifyCbor(env), signed, id: encode(signed).cid };
+    }
+    const e = env;
+    const signed = signedPart(e);
+    return { form: "json", sender: e.sender.identityKey, recipient: brc78Decode(Buffer.from(e.content, "base64")).recipient, verified: verify(e), signed, id: encode(signed).cid };
+}
+export function isCompactReply(x) {
+    const r = x;
+    return !!r && typeof r === "object" && !(r instanceof Uint8Array) && r.type === "reply" && CID.asCID(r.replyTo) !== null && isBytes(r.body);
+}
+/**
+ * The record a session reply is kept as — the same entry shape as a full
+ * envelope's ({envelope, box, body}), its envelope record carrying the proof:
+ * the BRC-104 signature over `payload` (the signed request) with the session
+ * nonces; `messageId` is SHA-256 of that payload.
+ */
+export function sessionRecord(r, sender, created, s) {
+    return {
+        type: "reply", replyTo: r.replyTo, sender: { identityKey: Uint8Array.from(Buffer.from(sender, "hex")) }, created,
+        contentHash: Uint8Array.from(createHash("sha256").update(r.body).digest()),
+        messageId: Uint8Array.from(createHash("sha256").update(s.payload).digest()),
+        session: { payload: s.payload, signature: s.signature, nonce: s.nonce, yourNonce: s.yourNonce },
+    };
+}
+/** How a JSON client carries §7.3 bytes in a BRC-33 JSON body: {"dag-cbor": "<base64>"}. */
+export const wrapCbor = (env) => ({ "dag-cbor": Buffer.from(dagCbor.encode(env)).toString("base64") });
+/**
+ * A BRC-33 body as an envelope: §7.3 dag-cbor (its bytes, as BRC-231 carries
+ * them, or `{"dag-cbor": "<base64>"}`, how a JSON client carries those bytes,
+ * or the decoded map), or §7.2 JSON (the object, or its JSON text).
+ */
+export function asEnvelope(raw) {
+    let v = raw;
+    try {
+        for (let i = 0; i < 2 && typeof v === "string"; i++)
+            v = JSON.parse(v);
+    }
+    catch {
+        return undefined;
+    }
+    const wrapped = v && typeof v === "object" && !(v instanceof Uint8Array) ? v["dag-cbor"] : undefined;
+    if (typeof wrapped === "string")
+        v = Uint8Array.from(Buffer.from(wrapped, "base64"));
+    if (v instanceof Uint8Array) {
+        const bytes = v;
+        try {
+            v = dagCbor.decode(bytes);
+        }
+        catch {
+            try {
+                v = JSON.parse(new TextDecoder().decode(bytes));
+            }
+            catch {
+                return undefined;
+            }
+        }
+    }
+    if (isCborEnvelope(v) || isEnvelope(v))
+        return v;
+    return undefined;
+}
+function strip(v) {
+    if (v === null || typeof v !== "object" || Array.isArray(v) || v instanceof Uint8Array)
+        return v;
+    const out = {};
+    for (const [k, x] of Object.entries(v))
+        if (x !== undefined)
+            out[k] = strip(x);
+    return out;
+}

package/dist/envelope.d.ts

@@ -0,0 +1,38 @@
+import type { WalletInterface } from "@bsv/sdk";
+import { CID } from "multiformats/cid";
+import { type Envelope, type Signed } from "./runtime/envelope.ts";
+export * from "./runtime/envelope.ts";
+/** A `created` value: ISO 8601 of a time in ms since the epoch. */
+/** An envelope's id: CIDv1 dag-cbor, sha2-256 of the dag-cbor encoded signed part (the envelope without `content`). */
+export declare function envelopeCid(env: Envelope | Signed): Promise<CID>;
+export declare const isoTime: (ms: number) => string;
+export interface SealArgs {
+    recipient: {
+        identityKey: string;
+        handle: string;
+        domain: string;
+    };
+    sender?: {
+        handle?: string;
+        domain?: string;
+    };
+    body: Uint8Array;
+    created?: string;
+    quoteId?: string;
+    payment?: unknown;
+}
+/** The signed part for `body`: metadata with its contentHash, signed by the wallet. No encryption. */
+export declare function sign(wallet: WalletInterface, args: SealArgs): Promise<Signed>;
+/** The wire encryption: `body` as BRC-78 content from this wallet to `recipient`, base64. */
+export declare function encryptContent(wallet: WalletInterface, recipient: string, body: Uint8Array): Promise<string>;
+/** sign + encryptContent: the envelope as sent. */
+export declare function seal(wallet: WalletInterface, args: SealArgs): Promise<Envelope>;
+/**
+ * Decrypt `content` as its recipient and check it against `contentHash`.
+ * Throws if this wallet is not the recipient, the content was altered, or the
+ * plaintext is not what the sender signed.
+ */
+export declare function open(wallet: WalletInterface, env: Envelope): Promise<{
+    body: Uint8Array;
+    senderIdentityKey: string;
+}>;

package/dist/envelope.js

@@ -0,0 +1,101 @@
+// BRC-169 §7.2 envelopes, as skein sends and receives them (docs/MESSAGES.md).
+// The wallet operations (sign, encrypt, seal, open) for the client (src/client),
+// the peers and the host, over the
+// pure part in src/runtime/envelope.ts (re-exported here). Outside
+// src/runtime: `seal` draws a random BRC-78 key id and reads the clock for
+// `created`, which the machine never does — an instance's own envelopes are
+// sealed inside the step by the program (programs/envelope), from the step's
+// stamp and random stream, through the wallet import.
+//
+//   contentHash  hex SHA-256 of the plaintext content (the dag-cbor body): in
+//              the signed part, so the sender's signature covers the content
+//              and anyone holding the plaintext can check who wrote it.
+//   content    base64 of a BRC-78 portable encrypted message: version
+//              0x42421033, sender identity (33), recipient identity (33), key id
+//              (32, random per message), then the wallet's ciphertext under
+//              protocol [2, "message encryption"], keyID base64(key id),
+//              counterparty the recipient (AES-256-GCM, IV prepended).
+//   signature  hex DER, by the sender's wallet under [2, "metanet handles
+//              envelope"], key id "1", counterparty anyone, over sha256 of the
+//              RFC 8785 canonical envelope without `content` and `signature`.
+//              Anyone can derive the key from sender.identityKey (verify()).
+//
+// The encryption is wire-level only: it keeps the messagebox operator out. The
+// recipient keeps the signed part (`Signed`: everything but `content`) and the
+// plaintext; its CID is the message's id (`replyTo` names it).
+import { createHash, randomBytes } from "node:crypto";
+import * as dagCbor from "@ipld/dag-cbor";
+import { CID } from "multiformats/cid";
+import { sha256 } from "multiformats/hashes/sha2";
+import { brc78Decode, brc78Encode, canonical, contentHash, ENVELOPE_KEY_ID, ENVELOPE_PROTOCOL, MESSAGE_ENCRYPTION, signedPart } from "./runtime/envelope.js";
+export * from "./runtime/envelope.js";
+// ---------------------------------------------------------------- sign, seal, open
+/** A `created` value: ISO 8601 of a time in ms since the epoch. */
+/** An envelope's id: CIDv1 dag-cbor, sha2-256 of the dag-cbor encoded signed part (the envelope without `content`). */
+export async function envelopeCid(env) {
+    return CID.createV1(dagCbor.code, await sha256.digest(dagCbor.encode(signedPart(env))));
+}
+export const isoTime = (ms) => new Date(ms).toISOString();
+/** The signed part for `body`: metadata with its contentHash, signed by the wallet. No encryption. */
+export async function sign(wallet, args) {
+    const { publicKey: me } = await wallet.getPublicKey({ identityKey: true });
+    const unsigned = strip({
+        metanetHandles: "1.0",
+        recipient: { handle: args.recipient.handle, domain: args.recipient.domain },
+        sender: { identityKey: me, handle: args.sender?.handle, domain: args.sender?.domain },
+        created: args.created ?? new Date().toISOString(),
+        quoteId: args.quoteId,
+        payment: args.payment,
+        contentHash: contentHash(args.body),
+    });
+    const hash = [...createHash("sha256").update(canonical(unsigned)).digest()];
+    const { signature } = await wallet.createSignature({ hashToDirectlySign: hash, protocolID: ENVELOPE_PROTOCOL, keyID: ENVELOPE_KEY_ID, counterparty: "anyone" });
+    return { ...unsigned, signature: Buffer.from(signature).toString("hex") };
+}
+/** The wire encryption: `body` as BRC-78 content from this wallet to `recipient`, base64. */
+export async function encryptContent(wallet, recipient, body) {
+    const { publicKey: me } = await wallet.getPublicKey({ identityKey: true });
+    const keyId = new Uint8Array(randomBytes(32));
+    const { ciphertext } = await wallet.encrypt({
+        protocolID: MESSAGE_ENCRYPTION,
+        keyID: Buffer.from(keyId).toString("base64"),
+        counterparty: recipient,
+        plaintext: [...body],
+    });
+    return Buffer.from(brc78Encode({ sender: me, recipient, keyId, ciphertext: Uint8Array.from(ciphertext) })).toString("base64");
+}
+/** sign + encryptContent: the envelope as sent. */
+export async function seal(wallet, args) {
+    const signed = await sign(wallet, args);
+    return { ...signed, content: await encryptContent(wallet, args.recipient.identityKey, args.body) };
+}
+/**
+ * Decrypt `content` as its recipient and check it against `contentHash`.
+ * Throws if this wallet is not the recipient, the content was altered, or the
+ * plaintext is not what the sender signed.
+ */
+export async function open(wallet, env) {
+    const m = brc78Decode(Buffer.from(env.content, "base64"));
+    const { publicKey: me } = await wallet.getPublicKey({ identityKey: true });
+    if (m.recipient !== me)
+        throw new Error(`envelope: addressed to ${m.recipient}, not this wallet (${me})`);
+    const { plaintext } = await wallet.decrypt({
+        protocolID: MESSAGE_ENCRYPTION,
+        keyID: Buffer.from(m.keyId).toString("base64"),
+        counterparty: m.sender,
+        ciphertext: [...m.ciphertext],
+    });
+    const body = Uint8Array.from(plaintext);
+    if (contentHash(body) !== env.contentHash)
+        throw new Error("envelope: the content does not match its signed contentHash");
+    return { body, senderIdentityKey: m.sender };
+}
+function strip(v) {
+    if (v === null || typeof v !== "object" || Array.isArray(v))
+        return v;
+    const out = {};
+    for (const [k, x] of Object.entries(v))
+        if (x !== undefined)
+            out[k] = strip(x);
+    return out;
+}

package/dist/host/arc.d.ts

@@ -0,0 +1,131 @@
+import { txCid } from "./feeds.ts";
+import type { HostDb } from "./instances.ts";
+/** The host's Arcade (host config: SKEIN_ARC_* in the environment or $SKEIN_HOME/host.env). */
+export interface ArcConfig {
+    /** Arcade's API, e.g. https://arcade.example.com (its POST /tx). */
+    url: string;
+    /** The host's one callback token: X-CallbackToken on every submission, the SSE stream's scope, the webhook's bearer. */
+    token: string;
+    /** Arcade's SSE service (its own port): default <url>/events. */
+    events?: string;
+    /** Where Arcade posts webhooks: a URL of this router's POST /arc/callback that Arcade can reach (Arcade wants public HTTPS). Unset: SSE only. */
+    callbackUrl?: string;
+}
+/** The webhook's path on the router. */
+export declare const ARC_ROUTE = "/arc";
+/** The host's Arcade from SKEIN_ARC_URL, SKEIN_ARC_TOKEN, SKEIN_ARC_EVENTS_URL, SKEIN_ARC_CALLBACK_URL (the environment, else $SKEIN_HOME/host.env); none without a URL. */
+export declare function hostArcConfig(vars: Record<string, string | undefined>, home?: string): ArcConfig | undefined;
+export interface ArcAnswer {
+    status: number;
+    headers: Record<string, string>;
+    body: Uint8Array;
+}
+export interface BroadcasterOptions {
+    arc: ArcConfig;
+    db: HostDb;
+    /** Admit a proof event into `handle`'s box (Router.admitEvent): unsigned, self-validating. */
+    admit(handle: string, box: string, event: Record<string, unknown>): Promise<unknown>;
+    /** Send `handle` a status message from the host's status provider (providers.ts `status`): box `chain/status` (#128), `subject` the transaction's CID. */
+    status(handle: string, body: Record<string, unknown>, subject: ReturnType<typeof txCid>): Promise<unknown>;
+    /** The instances a transaction may be in: every enabled row, and those whose kernel runs now. */
+    instances(): {
+        all: string[];
+        running: string[];
+    };
+    /** Whether `handle`'s state holds the transaction (a read), hydrating it if it is not running. */
+    holds(handle: string, txid: string): Promise<boolean>;
+    log?(source: string, line: string): void;
+    fetch?: typeof fetch;
+    /** SSE reconnect backoff, ms (default 500 → 30 000). */
+    backoff?: {
+        min: number;
+        max: number;
+    };
+    /** A queued broadcast Arcade did not take: tried again after `min` ms, doubling to `max` (default 1 000 → 300 000). */
+    retry?: {
+        min: number;
+        max: number;
+    };
+    /** A queued broadcast is dropped this long after it was queued (default a day: the instance abandons it by then). */
+    giveUpMs?: number;
+    /** How long a call to Arcade may take (default 30 000 ms). */
+    timeoutMs?: number;
+    /** Transactions whose holders are cached (default 100 000; the oldest go first). */
+    maxKnown?: number;
+    /** The clock (ms): the queue's. */
+    now?(): number;
+}
+/** The transaction a broadcast body carries (Atomic BEEF, BEEF, raw), and the bytes to post to Arcade: Extended Format when its inputs' sources are there. */
+export declare function arcadeBody(body: Uint8Array): {
+    txid?: string;
+    bytes: Uint8Array;
+};
+/** A status with a merkle path as the proof event an instance records (#65), or undefined. */
+export declare function proofOf(ev: Record<string, unknown>): Record<string, unknown> | undefined;
+/** A status without a path as the status provider's message body (#65). */
+export declare function statusBodyOf(ev: Record<string, unknown>): Record<string, unknown>;
+export declare class Broadcaster {
+    readonly o: BroadcasterOptions;
+    /** txid → the instances known to hold it, and whether every enabled instance was asked. */
+    private known;
+    /** Statuses being routed now (txid + key): a webhook and the stream delivering the same one route it once. */
+    private inflight;
+    private stream?;
+    private timer?;
+    private pumping?;
+    private again;
+    private stopped;
+    /** Counts (tests, the log): statuses routed, redeliveries dropped, admissions (proofs and status messages), posts. */
+    readonly stats: {
+        routed: number;
+        duplicates: number;
+        admitted: number;
+        proofs: number;
+        statuses: number;
+        posted: number;
+    };
+    constructor(o: BroadcasterOptions);
+    private say;
+    private now;
+    /** Arcade's SSE service for the host's token. */
+    eventsUrl(): string;
+    /** Open the subscription (resuming after the last event id taken), and take up the queue where it was. */
+    start(): void;
+    stop(): Promise<void>;
+    /** `handle` holds `txid` (it broadcast it). */
+    note(txid: string, handle: string): void;
+    /** The instances holding `txid`: the cached ones, and those a read finds (every enabled one the first time, then the running ones not known yet). */
+    holders(txid: string): Promise<string[]>;
+    /**
+     * One status from Arcade (the stream's, a webhook's, or its answer to a
+     * post): routed to every instance holding the transaction, once — a proof
+     * as an event, anything else as a status message. `askers` (a post's
+     * broadcasters) get it even when it was routed before: Arcade's answer to
+     * a duplicate is the news for an instance that broadcast it later. The
+     * number of instances it reached.
+     */
+    deliver(v: unknown, via: "stream" | "webhook" | "post", askers?: string[]): Promise<number>;
+    /**
+     * A broadcast event from `handle` (#65): the transaction's bytes and, if
+     * the event carried it, its Atomic BEEF. Queued durably and posted; the
+     * txid, or undefined when the bytes are not a transaction.
+     */
+    enqueue(handle: string, tx: Uint8Array, beef?: Uint8Array): string | undefined;
+    /** Post what is due now, then wait for the next. */
+    private kick;
+    private pump;
+    private post;
+    /** Whether a post (and the routing of its answer) is under way. */
+    busy(): boolean;
+    /** Until the posts under way, and the routing of their answers, are done (tests, the corpus: Router.settled). */
+    idle(): Promise<void>;
+    /** The queue as it stands (tests, the log). */
+    queued(): Array<{
+        txid: string;
+        attempts: number;
+        next: number;
+    }>;
+    private arcade;
+    /** POST /arc/callback: Arcade's webhook, with the host token as bearer; answered once the status is routed (Arcade retries otherwise). */
+    callback(headers: Record<string, string | undefined>, raw: Uint8Array): Promise<ArcAnswer>;
+}