@dcasegr/skein 0.0.0-stage → 0.1.1

package/dist/host/genesis.js

@@ -0,0 +1,353 @@
+// Format 10 (#146: the BEEF envelope beside the pointer record; format 9, #143: routes without senders, filters, roles and grants, root instead of an owner; format 8,
+// #77: the kernel's tables — one route table, admin operations in the kernel, write scope by app name;
+// format 7, #65, #69; format 6, #70, #67; #68: requests appended as received; format 3, #40; format 2,
+// #33: unsigned entries, keys as bytes) on the host's side: the genesis a new instance's log starts with,
+// and entries.
+//
+//   entry    {kind: "log", prev, n, time, genesis | request+transport | mail | event+box}   — no `sig`: no host key;
+//            the genesis entry is built here (nextEntry: n = 0, no prev); every other the kernel appends
+//            (#163: Kernel.admit hands over the body and its stamp, the kernel assigns prev and n)
+//   genesis  {kind: "genesis", identity: bytes(33), root?: [bytes(33)], handle, domain, programs,
+//             dispatch: [<route>], roles?: {<role>: ["<program>.<fn>"]},
+//             scopes?: {<program name>: [<head name | prefix/>]}, peers?: {role: bytes(33)},
+//             defaults, names?: [{identityKey: bytes(33), handle, domain}], collect, tree?,
+//             feeds?: [{kind: "headers", url, box?}]  (#58: statuses come from the host's broadcaster, arc.ts),
+//             libp2p?: {topics: [string], protocols: [string], listen?: [multiaddr]},
+//             addressBook?: [{key: bytes(33), transport, address, handle?, domain?}],
+//             heads?: {<head name>: <record CID>}}  (#141: an image's installed apps, `<app>/app`)
+//   route    {transport: "mailbox" | "event" | "http" | "libp2p" | "local", address, prefix?: true,
+//             filters?: ["kernel.brc104" | "kernel.beef" | "<app>.<filter>"], program?: <program record CID> | "kernel",
+//             fn?, …settings}
+//            (`dispatch`: the seed of the kernel's route table, docs/APPS.md §2 — the admin routes (boxes
+//            objects, head, dispatch, peers, grant → the kernel, gated by root), the boxes programs take,
+//            the events the host's wiring brings, the HTTP paths and libp2p topics and protocols. No
+//            `sender` (#143): who may run a function is the grants'. `root`: the initial root holders
+//            (#143; #142: the host skein's operator key) — none: an image, its routes carry the claim
+//            route and root comes with the claim. `roles`: what gates the genesis's own programs'
+//            functions — STOCK_ROLES: the explorer is root's. `scopes`: the heads a genesis-wired
+//            program may advance — STOCK_SCOPES, plus a tree's config `scopes`.)
+//            (`addressBook`, #70: the address book's seed — the host's providers (transport `local`, address
+//            their name: fetch, waker, cron, libp2p, status; #126: no role) and the root holder's mailbox —
+//            written into the head `peers` at the genesis)
+//            (no `jobs`, #69: a schedule is a program's message to the cron provider; a genesis naming
+//            them is refused)
+//            (`libp2p`, #51: the host's libp2p node runs for the instance, subscribes `topics` and serves
+//            `protocols`; each message or frame is a front-door step routed by its `libp2p` route)
+//            (`feeds`: what the host holds for the instance, feeds.ts; `defaults.ownerMessagebox`: the root
+//            holder's messagebox URL — the one peer a genesis names; `defaults.resolveOrigin`: where the
+//            instance's own domain is looked up (a dev host))
+//
+// The stamp is the host's clock at admission (#10): the sequence is the
+// order. A genesis is written from a **system** (issue #4, docs/BOOTSTRAP.md):
+// the programs, the routes, the config — read from a system tree by the
+// loader (boot.ts), which then also names the tree (`tree`: `main` starts
+// there), or, for an instance with no tree, the stock system in code
+// (codeSystem: the kernel's own pinned programs and STOCK_DISPATCH). The same
+// `genesisRecord` writes both. The forms before #77 and #115
+// (etc/subscriptions.json, etc/routes.json, etc/reads.json) are gone (#143):
+// they spoke of senders.
+import { parse as parseCid } from "../runtime/cid.js";
+import { isFilterRef, rowKey } from "../runtime/dispatch.js";
+import { DEFAULTS, nextEntry } from "../runtime/log.js";
+import { now as clockNow } from "./clock.js";
+/** Session expiry (#33 part 2, #40): the instance's own policy, judged against the session record's stamp (a day). */
+export const SESSION_DEFAULTS = { sessionTtlMs: "86400000" };
+export const keyBytes = (hex) => {
+    if (!/^0[23][0-9a-f]{64}$/.test(hex))
+        throw new TypeError(`not an identity key: ${hex}`);
+    return Uint8Array.from(Buffer.from(hex, "hex"));
+};
+export const keyHex = (k) => k instanceof Uint8Array ? Buffer.from(k).toString("hex") : String(k);
+/**
+ * The kernel's admin operations (#77, #143: and `grant`), one per table, each gated by root. Every
+ * genesis carries their routes — `{address: <op>, program: kernel, fn: <op>}` — ahead of its own
+ * (#31: a bare genesis is the tables and the admin routes; a bundle adds what its apps ask for).
+ * Delegating is a grant (root, or an app's role), never another route.
+ */
+export const ADMIN_OPS = ["objects", "head", "dispatch", "peers", "grant"];
+export const ADMIN_ROWS = ADMIN_OPS.map((op) => ({ address: op, program: "kernel", fn: op }));
+/** What a kernel route may name: the admin operations, the claim (#89), and the host's tick (#130: the host row, billing.ts). */
+export const KERNEL_OPS = [...ADMIN_OPS, "claim", "tick"];
+/**
+ * The claim route (#89, #143): an image's route to the kernel. A message in box `claim`, from anyone:
+ * root is granted to its sender (#127) and this route removed (a second claim finds no route). The
+ * claimant's own message (`skein claim`), or a claim signed before the instance existed, which the
+ * host's instance manager forwards as its first entry before the hostname is published
+ * (Router.createInstance).
+ */
+export const CLAIM_ROW = { address: "claim", program: "kernel", fn: "claim" };
+/** The BRC-103 handshake's route (#143): the front door's, no filters (it makes the session). */
+export const HANDSHAKE_ROW = { transport: "http", address: "/.well-known/auth", program: "frontdoor", fn: "handshake" };
+/**
+ * The stock HTTP routes (#40, #143): the BRC-33 messagebox, at the root and under /messagebox (where
+ * older clients were pointed), behind kernel.brc104 (a session: the caller is its key); the
+ * explorer's route (the front door's `explore`: log, threads, heads, records as JSON), behind
+ * kernel.brc104 and gated by root (STOCK_ROLES); the handshake.
+ */
+export const STOCK_HTTP = [
+    HANDSHAKE_ROW,
+    ...["", "/messagebox"].flatMap((p) => ["sendMessage", "listMessages", "acknowledgeMessage"].map((fn) => ({ transport: "http", address: `${p}/${fn}`, filters: ["kernel.brc104"], program: "messagebox", fn }))),
+    { transport: "http", address: "/explore", prefix: true, filters: ["kernel.brc104"], program: "frontdoor", fn: "explore" },
+];
+/** What gates the genesis's own programs' functions (#143): the explorer is root's. */
+export const STOCK_ROLES = { root: ["frontdoor.explore"] };
+/**
+ * The stock seed (#77), after the admin routes: the reserved box the host admits events into, `:ack`
+ * (the messagebox moves a reader's pointer: an event, #143); and the stock HTTP routes. No `run`, no
+ * `chat` (#83): the shell and the chat loop are apps. No `register` box (#40): registration is
+ * application wiring.
+ */
+export const STOCK_DISPATCH = [
+    { transport: "event", address: ":ack", program: "messagebox" },
+    ...STOCK_HTTP,
+];
+/**
+ * A mailbox instance's seed (#40): the messagebox's acknowledgements, and every message in any box to
+ * the messagebox (kept for its root; a mailbox exists only where such a route does).
+ */
+export const MAILBOX_DISPATCH = [
+    { transport: "event", address: ":ack", program: "messagebox" },
+    { address: "*", program: "messagebox" },
+    ...STOCK_HTTP,
+];
+/**
+ * The write scopes of the stock genesis-wired programs (#77): the heads each
+ * may advance, by program name. The front door's sessions; the messagebox's
+ * lists (#126: its outbound sessions are the kernel's, authfetch); the wallet's records (#79: `wallet/…`, its
+ * coins, actions, drafts and outputs — the chain is the chain app's). The
+ * resolve program's records (#87: `resolve/peers`, what a BRC-169 lookup
+ * found — never the address book, which only root's `peers` messages
+ * change; the messagebox's delivery reads them for a key the address book
+ * does not name).
+ */
+export const STOCK_SCOPES = {
+    frontdoor: ["frontdoor/"],
+    messagebox: ["mailbox"],
+    resolve: ["resolve/"],
+    wallet: ["wallet/"],
+    // #78: the chain module (shruggr/skein-chain) wired at boot by a system tree as `bin/chain.wasm`:
+    // its heads are `chain/…`, as an installed chain app's are by the name rule.
+    chain: ["chain/"],
+};
+/** A system's libp2p, checked: the genesis's `libp2p` and the routes its protocols add (those the tree lacks). */
+export function libp2pIn(spec, specs) {
+    if (spec === undefined)
+        return { specs };
+    const bad = (why) => new Error(`etc/config.json: libp2p ${why} (want {topics?: [string], protocols?: {protocol: program | {program, fn?}}, listen?: [multiaddr]})`);
+    if (!spec || typeof spec !== "object")
+        throw bad("is not an object");
+    const strs = (v, what) => {
+        if (v === undefined)
+            return [];
+        if (!Array.isArray(v) || v.some((x) => typeof x !== "string" || !x))
+            throw bad(`${what} is not a list of strings`);
+        return v;
+    };
+    const topics = strs(spec.topics, "topics");
+    const listen = strs(spec.listen, "listen");
+    const ps = spec.protocols ?? {};
+    if (typeof ps !== "object" || Array.isArray(ps))
+        throw bad("protocols is not an object");
+    const out = [...specs];
+    for (const [protocol, h] of Object.entries(ps)) {
+        const program = typeof h === "string" ? h : h?.program;
+        if (!protocol || typeof program !== "string" || !program)
+            throw bad(`protocols.${protocol} names no program`);
+        if (!out.some((r) => r.transport === "libp2p" && r.address === protocol))
+            out.push({ transport: "libp2p", address: protocol, program, fn: (typeof h === "object" && h.fn) || "libp2p" });
+    }
+    return { libp2p: { topics, protocols: Object.keys(ps), ...(listen.length ? { listen } : {}) }, specs: out };
+}
+/** A key as a system writes it: hex, or `$self` / `$infer` (the host's), or a provider's `$<name>` (Genesis2Config.providers). */
+export function keyOf(s, c) {
+    if (s === "$owner")
+        throw new Error("$owner: gone (#143: there is no owner; root holders are the genesis's `root`, granted by a claim or a grant)");
+    if (s === "$self") {
+        if (!c.identity)
+            throw new Error("$self: no instance identity here");
+        return keyBytes(c.identity);
+    }
+    if (s === "$infer") {
+        if (!c.infer)
+            throw new Error("the system names $infer, and this host has no inference peer (SKEIN_INFER)");
+        return keyBytes(c.infer);
+    }
+    if (s.startsWith("$")) {
+        const k = c.providers?.[s.slice(1)];
+        if (!k)
+            throw new NoProvider(s);
+        return keyBytes(k);
+    }
+    return keyBytes(s);
+}
+/** A `$<name>` that this host has no provider for. */
+export class NoProvider extends Error {
+    provider;
+    constructor(provider) { super(`no provider ${provider} on this host`); this.provider = provider; }
+}
+/** The program a spec names: by name in `programs`, else a CID; `kernel` for an admin route. */
+function programOf(h, programs) {
+    if (h === "kernel")
+        return "kernel";
+    const p = programs[h];
+    if (p)
+        return p;
+    try {
+        return parseCid(h);
+    }
+    catch {
+        return undefined;
+    } // neither a program's name nor a CID: the caller refuses the route and says so
+}
+const isBox = (b) => typeof b === "string" && b.length > 0 && !/[\s\0]/.test(b);
+const TRANSPORTS = ["mailbox", "event", "http", "libp2p", "local"];
+/** The routes of a system's specs (etc/dispatch.json, #77, #143), programs resolved; a route to a program the system lacks is dropped. */
+export function rowsOf(specs, programs) {
+    const out = [];
+    for (const s of specs) {
+        if (!s || typeof s !== "object" || !isBox(s.address) || (s.program !== undefined && typeof s.program !== "string"))
+            throw new Error(`etc/dispatch.json: bad route ${JSON.stringify(s)} (want {transport?, address, prefix?, filters?, program?, fn?, …})`);
+        if (s.sender !== undefined)
+            throw new Error(`etc/dispatch.json: route ${s.address}: \`sender\` is gone (#143: a route has none — filters say who it is from, roles gate functions)`);
+        const transport = s.transport ?? "mailbox";
+        if (!TRANSPORTS.includes(transport))
+            throw new Error(`etc/dispatch.json: route ${s.address}: transport ${JSON.stringify(transport)} is not mailbox, event, http, libp2p or local`);
+        if (s.filters !== undefined && (!Array.isArray(s.filters) || !s.filters.every(isFilterRef)))
+            throw new Error(`etc/dispatch.json: route ${s.address}: filters is a list of "kernel.brc104", "kernel.beef" or "<app>.<filter>"`);
+        if (s.program === undefined) {
+            if (!(transport === "http" || (transport === "libp2p" && s.address.startsWith("/"))) || !s.filters?.length)
+                throw new Error(`etc/dispatch.json: route ${s.address}: no program — only an http or libp2p protocol (/…) read route (its filters answer) has none`);
+            const { transport: _t, ...rest } = s;
+            void _t;
+            out.push({ ...rest, transport });
+            continue;
+        }
+        const program = programOf(s.program, programs);
+        if (!program)
+            continue;
+        if (program === "kernel" && (typeof s.fn !== "string" || !KERNEL_OPS.includes(s.fn)))
+            throw new Error(`etc/dispatch.json: route ${s.address}: a kernel route's fn is one of ${KERNEL_OPS.join(", ")}`);
+        const { transport: _t, address, prefix, filters, program: _p, fn, ...settings } = s;
+        void _t;
+        void _p;
+        out.push({ transport, address, ...(prefix ? { prefix: true } : {}), ...(filters?.length ? { filters } : {}), program, ...(fn ? { fn } : {}), ...settings });
+    }
+    return out;
+}
+/**
+ * Resolve a system's routes, config and programs for one instance (both genesis paths). `specs` is
+ * its etc/dispatch.json. The order: the admin routes (every genesis), the dispatch specs, the
+ * host's extra box routes and routes, then the protocols' routes. A route with an admin route's key
+ * is left out (the kernel's operation keeps the box), with a warning.
+ */
+export function resolveSystem(c, programs, config = {}, tree, specs = []) {
+    if (config.jobs !== undefined)
+        throw new Error("etc/config.json: `jobs` are gone (#69): a schedule is a program's message to the cron provider ({fn: \"tick\", every | at, box, body?, name}, docs/MESSAGES.md)");
+    if (config.scopes !== undefined && (typeof config.scopes !== "object" || Array.isArray(config.scopes) || Object.values(config.scopes).some((v) => !Array.isArray(v) || v.some((h) => typeof h !== "string" || !h))))
+        throw new Error("etc/config.json: scopes is {<program name>: [<head name | prefix/>]}");
+    if (config.roles !== undefined && (typeof config.roles !== "object" || Array.isArray(config.roles) || Object.values(config.roles).some((v) => !Array.isArray(v) || v.some((f) => typeof f !== "string" || !f.includes(".")))))
+        throw new Error("etc/config.json: roles is {<role>: [\"<program>.<fn>\"]}");
+    const p2p = libp2pIn(config.libp2p ?? c.libp2p, [...specs, ...(c.subscriptions ?? []).map((x) => ({ address: x.box, program: x.handler.toString() })), ...(c.dispatch ?? [])]);
+    const admin = rowsOf(ADMIN_ROWS, programs);
+    const dispatch = [...admin];
+    for (const r of rowsOf(p2p.specs, programs)) {
+        if (dispatch.some((a) => rowKey(a) === rowKey(r))) {
+            if (admin.some((a) => rowKey(a) === rowKey(r)) && r.program !== "kernel")
+                c.warn?.(`a route for the admin box ${r.address} is left out: the kernel's ${r.address} operation keeps it`);
+            continue;
+        }
+        dispatch.push(r);
+    }
+    const root = c.root ?? [];
+    // A tree booted with root and no root holder's handle (#142: the host skein from its image) names no one.
+    let names = root.length && (c.ownerHandle || !tree) ? [{ identityKey: keyBytes(root[0]), ...(c.ownerHandle ?? { handle: "david", domain: "localhost" }) }] : [];
+    if (c.infer)
+        names.push({ identityKey: keyBytes(c.infer), ...(c.inferHandle ?? { handle: "infer", domain: "localhost" }) });
+    if (config.names)
+        names = config.names.map((n) => ({ identityKey: keyOf(n.identityKey, c), handle: n.handle, domain: n.domain }));
+    const peers = config.peers
+        ? Object.fromEntries(Object.entries(config.peers).map(([role, k]) => [role, keyOf(k, c)]))
+        : c.infer ? { infer: keyBytes(c.infer) } : undefined;
+    return {
+        programs, dispatch, roles: mergeRoles(STOCK_ROLES, config.roles ?? {}), scopes: { ...STOCK_SCOPES, ...c.scopes, ...config.scopes }, ...(peers ? { peers } : {}),
+        defaults: mergeDefaults(c, { ...(config.owner?.messagebox ? { ownerMessagebox: config.owner.messagebox } : {}), ...config.defaults }),
+        names, collect: config.collect ?? ["completions"], ...(tree ? { tree } : {}),
+        ...(feedsIn(config.feeds ?? c.feeds)),
+        ...(p2p.libp2p ? { libp2p: p2p.libp2p } : {}),
+    };
+}
+/** Two role maps joined (#143): each role's functions, both lists' (a tree's roles add to the stock ones, never replace them). */
+function mergeRoles(a, b) {
+    const out = {};
+    for (const [r, fs] of [...Object.entries(a), ...Object.entries(b)])
+        out[r] = [...new Set([...(out[r] ?? []), ...fs])];
+    return out;
+}
+/** A system's feeds, checked. */
+function feedsIn(fs) {
+    if (!fs)
+        return {};
+    if (!Array.isArray(fs))
+        throw new Error("etc/config.json: feeds is a list");
+    for (const f of fs) {
+        if (f?.kind === "headers" && typeof f.url === "string" && f.url)
+            continue;
+        if (f?.kind === "arc-callback")
+            throw new Error("etc/config.json: the arc-callback feed is gone (#58): transaction statuses come from the host's broadcaster (SKEIN_ARC_URL), routed to every instance holding the transaction");
+        throw new Error(`etc/config.json: a feed is {kind: "headers", url, box?}: ${JSON.stringify(f)}`);
+    }
+    return fs.length ? { feeds: fs } : {};
+}
+/** DEFAULTS < the host's fill-ins (its facts, its network) < the tree's config < explicit overrides (warned when they replace a tree value). */
+function mergeDefaults(c, tree = {}) {
+    for (const [k, v] of Object.entries(c.overrides ?? {})) {
+        if (tree[k] !== undefined && tree[k] !== v)
+            c.warn?.(`host override: ${k} = ${v} replaces the system tree's ${k} = ${tree[k]}`);
+    }
+    return { ...DEFAULTS, ...SESSION_DEFAULTS, ...hostFacts(c), ...networkDefault(c), ...c.defaults, ...tree, ...c.overrides };
+}
+/** The host's network (SKEIN_NETWORK) as the genesis default `walletNetwork`: a network fact, beside the host facts. */
+function networkDefault(c) {
+    return c.network ? { walletNetwork: c.network } : {};
+}
+/** What the host knows at genesis (#40): the root holder's messagebox, where its own domain resolves. */
+function hostFacts(c) {
+    return { ...(c.ownerMessagebox ? { ownerMessagebox: c.ownerMessagebox } : {}), ...(c.resolveOrigin ? { resolveOrigin: c.resolveOrigin } : {}) };
+}
+/** The stock system in code: the kernel's pinned programs (its `programs` frame) and the stock seed. */
+export function codeSystem(c, programs) {
+    const known = (s) => s.program === undefined || s.program === "kernel" || !!programs[s.program];
+    if (c.mailbox) {
+        // A mailbox instance: the front door and the messagebox, nothing else.
+        const mine = { frontdoor: programs.frontdoor, messagebox: programs.messagebox };
+        const s = resolveSystem({ ...c, defaults: undefined, overrides: undefined, infer: undefined, subscriptions: undefined, dispatch: undefined }, mine, { peers: {}, names: [] }, undefined, MAILBOX_DISPATCH);
+        return { ...s, collect: [], defaults: { ...SESSION_DEFAULTS, ...networkDefault(c), ...c.defaults, ...c.overrides } };
+    }
+    // Code genesis has always taken the host's defaults whole (DEFAULTS when none).
+    return { ...resolveSystem({ ...c, defaults: undefined, overrides: undefined }, programs, {}, undefined, STOCK_DISPATCH.filter(known)), defaults: { ...SESSION_DEFAULTS, ...hostFacts(c), ...networkDefault(c), ...(c.defaults ? { ...c.defaults, ...c.overrides } : c.overrides ? { ...DEFAULTS, ...c.overrides } : DEFAULTS) } };
+}
+/** The genesis record: who the instance is, and its system. */
+export function genesisRecord(c, s) {
+    return {
+        kind: "genesis", identity: keyBytes(c.identity), handle: c.handle, domain: c.domain, ...(c.root?.length ? { root: c.root.map(keyBytes) } : {}),
+        ...(Object.keys(s.roles).length ? { roles: s.roles } : {}),
+        ...(c.addressBook?.length ? { addressBook: c.addressBook.map((e) => ({ key: e.key, transport: e.transport, address: e.address, ...(e.handle ? { handle: e.handle } : {}), ...(e.domain ? { domain: e.domain } : {}) })) } : {}),
+        programs: s.programs, dispatch: s.dispatch, ...(Object.keys(s.scopes).length ? { scopes: s.scopes } : {}), ...(s.peers ? { peers: s.peers } : {}),
+        defaults: s.defaults, names: s.names, collect: s.collect, ...(s.tree ? { tree: s.tree } : {}), ...(s.feeds ? { feeds: s.feeds } : {}),
+        ...(s.libp2p ? { libp2p: s.libp2p } : {}), ...(s.heads && Object.keys(s.heads).length ? { heads: s.heads } : {}),
+    };
+}
+/** The genesis record for a new instance over the kernel's programs (name → program record CID): code genesis. */
+export function genesis2(c, programs) {
+    return genesisRecord(c, codeSystem(c, programs));
+}
+/** Write a genesis over `s` into an empty store through its kernel; the entry's CID. */
+export async function writeSystemGenesis(k, c, s, time = clockNow()) {
+    const g = await k.store.put(genesisRecord(c, s));
+    return await k.store.log.append(await nextEntry(k.store, { genesis: g }, time)); // the kernel's log takes a format-10 entry; Store's type is format 1
+}
+/** Code genesis (the stock system) into an empty store; the entry's CID. */
+export async function writeGenesis(k, c, time = clockNow()) {
+    const programs = await k.call("programs");
+    return await writeSystemGenesis(k, c, codeSystem(c, programs), time);
+}

package/dist/host/handles.d.ts

@@ -0,0 +1,40 @@
+import { Certificate, type ProtoWallet } from "@bsv/sdk";
+/** §4.5: the handle-certificate type, base64(SHA-256("metanet-handles handle certificate v1")). */
+export declare const HANDLE_CERTIFICATE_TYPE: string;
+/**
+ * The revocation outpoint every certificate carries: BRC-52's disabled
+ * sentinel. Revocation not implemented — the host has no wallet (#100).
+ */
+export declare const NO_REVOCATION_OUTPOINT: string;
+/** The well-known paths of BRC-169's resolve (§5.2) and search (§5.6) endpoints, on the host's own origin. */
+export declare const RESOLVE_PATH = "/.well-known/metanet-handles/resolve";
+export declare const SEARCH_PATH = "/.well-known/metanet-handles/search";
+/** A certificate as JSON carries it. */
+export type CertificateJson = {
+    type: string;
+    serialNumber: string;
+    subject: string;
+    certifier: string;
+    revocationOutpoint: string;
+    fields: Record<string, string>;
+    signature: string;
+};
+/** §4.1: the resolver's copy of the certificate for handle@domain → subject under `serialNumber`, signed by the certifier. */
+export declare function issueHandleCertificate(certifier: ProtoWallet, handle: string, domain: string, subject: string, serialNumber: string): Promise<Certificate>;
+/**
+ * The holder's copy (#103, §4.6): the same binding with BRC-52 encrypted
+ * fields, and `keyringForSubject` for the wallet's `acquireCertificate`
+ * (acquisitionProtocol "direct", keyringRevealer "certifier").
+ */
+export declare function issueSubjectCertificate(certifier: ProtoWallet, handle: string, domain: string, subject: string, serialNumber: string): Promise<{
+    certificate: CertificateJson;
+    keyringForSubject: Record<string, string>;
+}>;
+/**
+ * The certifier provider's work (#113, providers.ts): a message from the
+ * host skein in box `issue`, body {handle, domain, subject: bytes(33),
+ * serialNumber, issuance?} → {certificate, holder: {certificate,
+ * keyringForSubject}, serialNumber, issuance?}. A refusal throws (the
+ * provider answers {error}).
+ */
+export declare function certify(certifier: ProtoWallet, box: string, b: Record<string, unknown>): Promise<Record<string, unknown>>;

package/dist/host/handles.js

@@ -0,0 +1,88 @@
+// The host's BRC-169 certifier (#100, #113; ~/Work/bsv/BRCs peer-to-peer/0169.md
+// §4.1, §4.5): the key that signs the handle certificates, and nothing else.
+// What a handle is, who holds it, which serial number its certificate gets
+// and what was issued when are the host skein's: its onboarding app
+// (shruggr/skein-onboard) registers the handle, puts the issuance record,
+// takes its hash as the serial number, asks the certifier provider to sign
+// (`issue`, providers.ts), and records the answer under its own head. The key
+// stays here, outside every instance: the certifier key (signer.ts
+// certifierKey: the master secret's child under [2, "skein provider"], key ID
+// `certifier`), which the manifest the app serves publishes as
+// `metanet.trust.publicKey` (the address book's `certifier` entry).
+//
+// One issue is two signatures of the same binding (type, serial number,
+// subject, certifier, revocation outpoint):
+//
+// - **The resolver's copy**: `fields.handle` and `fields.domain` Base64 of the
+//   plaintext, as in §A.3, not BRC-52 field encryption — resolve answers it to
+//   anyone, and a resolver checks the fields against what it resolved (§4.1
+//   rule 3). The SDK's Certificate serializes and signs it (BRC-52: protocol
+//   [2, "certificate signature"], key ID `<type> <serialNumber>`,
+//   counterparty anyone; RFC 6979, so the same bytes for the same binding).
+// - **The holder's copy** (#103): BRC-52 field encryption and a keyring for
+//   the subject (the SDK's MasterCertificate.issueCertificateForSubject),
+//   because a BRC-100 wallet's `acquireCertificate` (direct) takes only that:
+//   it rebuilds a MasterCertificate, which wants a keyring entry per field,
+//   and decrypts the fields with it. Its field ciphertexts (and so its
+//   signature) differ on every issue.
+//
+// Revocation is not implemented: the host has no wallet. §4.1 wants an
+// outpoint the certifier controls and spends on revocation; the certificate
+// carries BRC-52's disabled sentinel (64 zeros, vout 0) instead. The
+// onboarding app keeps every issue (a new serial each time, the earlier
+// records the trail), which is what revocation will need.
+import { Certificate, Hash, MasterCertificate, Utils } from "@bsv/sdk";
+/** §4.5: the handle-certificate type, base64(SHA-256("metanet-handles handle certificate v1")). */
+export const HANDLE_CERTIFICATE_TYPE = Utils.toBase64(Hash.sha256(Utils.toArray("metanet-handles handle certificate v1", "utf8")));
+/**
+ * The revocation outpoint every certificate carries: BRC-52's disabled
+ * sentinel. Revocation not implemented — the host has no wallet (#100).
+ */
+export const NO_REVOCATION_OUTPOINT = `${"00".repeat(32)}.0`;
+/** The well-known paths of BRC-169's resolve (§5.2) and search (§5.6) endpoints, on the host's own origin. */
+export const RESOLVE_PATH = "/.well-known/metanet-handles/resolve";
+export const SEARCH_PATH = "/.well-known/metanet-handles/search";
+const KEY = /^0[23][0-9a-f]{64}$/;
+const SERIAL = /^[A-Za-z0-9+/]{43}=$/;
+const asJson = (c) => ({ type: c.type, serialNumber: c.serialNumber, subject: c.subject, certifier: c.certifier, revocationOutpoint: c.revocationOutpoint, fields: { ...c.fields }, signature: c.signature ?? "" });
+/** §4.1: the resolver's copy of the certificate for handle@domain → subject under `serialNumber`, signed by the certifier. */
+export async function issueHandleCertificate(certifier, handle, domain, subject, serialNumber) {
+    const { publicKey } = await certifier.getPublicKey({ identityKey: true });
+    const fields = { handle: Utils.toBase64(Utils.toArray(handle, "utf8")), domain: Utils.toBase64(Utils.toArray(domain, "utf8")) };
+    const c = new Certificate(HANDLE_CERTIFICATE_TYPE, serialNumber, subject, publicKey, NO_REVOCATION_OUTPOINT, fields);
+    await c.sign(certifier);
+    return c;
+}
+/**
+ * The holder's copy (#103, §4.6): the same binding with BRC-52 encrypted
+ * fields, and `keyringForSubject` for the wallet's `acquireCertificate`
+ * (acquisitionProtocol "direct", keyringRevealer "certifier").
+ */
+export async function issueSubjectCertificate(certifier, handle, domain, subject, serialNumber) {
+    const c = await MasterCertificate.issueCertificateForSubject(certifier, subject, { handle, domain }, HANDLE_CERTIFICATE_TYPE, async () => NO_REVOCATION_OUTPOINT, serialNumber);
+    return { certificate: asJson(c), keyringForSubject: { ...c.masterKeyring } };
+}
+/**
+ * The certifier provider's work (#113, providers.ts): a message from the
+ * host skein in box `issue`, body {handle, domain, subject: bytes(33),
+ * serialNumber, issuance?} → {certificate, holder: {certificate,
+ * keyringForSubject}, serialNumber, issuance?}. A refusal throws (the
+ * provider answers {error}).
+ */
+export async function certify(certifier, box, b) {
+    if (box !== "issue")
+        throw new Error(`the certifier takes box issue, not ${box}`);
+    const handle = typeof b.handle === "string" ? b.handle : "";
+    const domain = typeof b.domain === "string" ? b.domain : "";
+    const subject = b.subject instanceof Uint8Array ? Buffer.from(b.subject).toString("hex") : typeof b.subject === "string" ? b.subject : "";
+    const serialNumber = typeof b.serialNumber === "string" ? b.serialNumber : "";
+    if (!handle || !domain)
+        throw new Error("issue wants {handle, domain, subject, serialNumber}");
+    if (!KEY.test(subject))
+        throw new Error("subject: not an identity key (33 bytes)");
+    if (!SERIAL.test(serialNumber))
+        throw new Error("serialNumber: base64 of 32 bytes");
+    const plain = await issueHandleCertificate(certifier, handle, domain, subject, serialNumber);
+    const holder = await issueSubjectCertificate(certifier, handle, domain, subject, serialNumber);
+    return { certificate: asJson(plain), holder, serialNumber, ...(b.issuance !== undefined ? { issuance: b.issuance } : {}) };
+}

package/dist/host/hostenv.d.ts

@@ -0,0 +1,30 @@
+import { PrivateKey } from "@bsv/sdk";
+export type Vars = Record<string, string | undefined>;
+/** The host's home: SKEIN_HOME, default ~/.skein. */
+export declare const homeOf: (vars: Vars) => string;
+export declare const HOST_ENV = "host.env";
+export declare const OPERATOR_KEY = "operator.key";
+/** The `SKEIN_*` settings of a host.env file (empty when there is none). */
+export declare function readHostEnv(file: string): Record<string, string>;
+/**
+ * The variables the commands see: host.env's `SKEIN_*` settings under the environment's (the environment
+ * wins). SKEIN_HOME comes from the environment (it says where host.env is).
+ */
+export declare function withHostEnv(vars: Vars): Vars;
+/** Where the operator's key is: SKEIN_OPERATOR_KEY, default $SKEIN_HOME/operator.key. */
+export declare const operatorKeyPath: (vars: Vars) => string;
+/** A key file's key: one line, hex (64) or WIF. */
+export declare function parseKey(text: string, where: string): PrivateKey;
+/**
+ * The operator's key: the file at SKEIN_OPERATOR_KEY (default $SKEIN_HOME/operator.key) if present, else,
+ * with `create`, a new key written there (hex, mode 0600). `made` says it was created now.
+ */
+export declare function operatorKey(vars: Vars, o?: {
+    create?: boolean;
+}): {
+    key: PrivateKey;
+    path: string;
+    made: boolean;
+};
+/** The identity key (hex) of a private key. */
+export declare const identityOf: (key: PrivateKey) => string;

package/dist/host/hostenv.js

@@ -0,0 +1,83 @@
+// The host's configuration file and the operator's key.
+//
+// `$SKEIN_HOME/host.env` holds the host's settings: every `SKEIN_*` line
+// (`KEY=value`, `export KEY=value`, quotes stripped, `#` comments). The
+// environment wins over the file. It configures the commands (`skein-host`,
+// `skein`) and, through them, how `skein-host run` builds the host skein the
+// first time; once the host skein exists, a change to host.env does not
+// reach into it.
+//
+// The operator's key (`SKEIN_OPERATOR_KEY`, a path, default
+// `$SKEIN_HOME/operator.key`): the key that owns the host skein and that the
+// client `skein` signs with. A plain file, one line, hex (or WIF), mode
+// 0600: if present it is used, if not it is created.
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { PrivateKey } from "@bsv/sdk";
+/** The host's home: SKEIN_HOME, default ~/.skein. */
+export const homeOf = (vars) => vars.SKEIN_HOME || join(vars.HOME ?? ".", ".skein");
+export const HOST_ENV = "host.env";
+export const OPERATOR_KEY = "operator.key";
+/** The `SKEIN_*` settings of a host.env file (empty when there is none). */
+export function readHostEnv(file) {
+    const out = {};
+    if (!existsSync(file))
+        return out;
+    for (const line of readFileSync(file, "utf8").split("\n")) {
+        const m = /^\s*(?:export\s+)?(SKEIN_[A-Z0-9_]+)=(.*)$/.exec(line);
+        if (!m)
+            continue;
+        let v = m[2].trim();
+        const q = /^(["'])(.*)\1$/.exec(v);
+        if (q)
+            v = q[2];
+        else
+            v = v.replace(/\s+#.*$/, "");
+        out[m[1]] = v;
+    }
+    return out;
+}
+/**
+ * The variables the commands see: host.env's `SKEIN_*` settings under the environment's (the environment
+ * wins). SKEIN_HOME comes from the environment (it says where host.env is).
+ */
+export function withHostEnv(vars) {
+    const file = readHostEnv(join(homeOf(vars), HOST_ENV));
+    const out = { ...vars };
+    for (const [k, v] of Object.entries(file))
+        if (out[k] === undefined || out[k] === "")
+            out[k] = v;
+    return out;
+}
+/** Where the operator's key is: SKEIN_OPERATOR_KEY, default $SKEIN_HOME/operator.key. */
+export const operatorKeyPath = (vars) => vars.SKEIN_OPERATOR_KEY || join(homeOf(vars), OPERATOR_KEY);
+/** A key file's key: one line, hex (64) or WIF. */
+export function parseKey(text, where) {
+    const s = text.trim();
+    if (/^[0-9a-fA-F]{64}$/.test(s))
+        return PrivateKey.fromHex(s.toLowerCase());
+    try {
+        return PrivateKey.fromWif(s);
+    }
+    catch {
+        throw new Error(`${where}: not a private key (64 hex digits, or WIF)`);
+    }
+}
+/**
+ * The operator's key: the file at SKEIN_OPERATOR_KEY (default $SKEIN_HOME/operator.key) if present, else,
+ * with `create`, a new key written there (hex, mode 0600). `made` says it was created now.
+ */
+export function operatorKey(vars, o = {}) {
+    const path = operatorKeyPath(vars);
+    if (existsSync(path))
+        return { key: parseKey(readFileSync(path, "utf8"), path), path, made: false };
+    if (!o.create)
+        throw new Error(`no operator key at ${path} (SKEIN_OPERATOR_KEY): \`skein-host run\` makes it, or put the key there (hex or WIF, mode 0600)`);
+    const key = PrivateKey.fromRandom();
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, `${key.toHex()}\n`, { mode: 0o600 });
+    chmodSync(path, 0o600);
+    return { key, path, made: true };
+}
+/** The identity key (hex) of a private key. */
+export const identityOf = (key) => key.toPublicKey().toString();