@dcasegr/skein 0.0.0-stage → 0.1.2

package/dist/host/frontdoor.js

@@ -0,0 +1,172 @@
+// The host's side of an instance's front door (#68, #66): a light router.
+// A request a transport carries in is appended as received — one `request`
+// entry, the raw request its record (method, path, headers with the
+// x-bsv-auth-* ones, body) — and nothing is verified here. The kernel steps
+// the instance's middleware (the front door) on it as the request's own
+// thread; the host holds the client's connection until that thread comes to
+// rest for good (finished or errored, not waiting) and answers with what
+// the thread's last step answered, signed on the client's session inside.
+// However many entries the thread takes, the client sees one answer; past
+// the wait's bound it gets 503 + Retry-After and the thread goes on.
+//
+// A route whose answer is a read of live state (the explorer) answers
+// {read}: the thread verified it and ended, and the answer is one kernel
+// `call` of the front door's fn "read", signed there (not recorded).
+//
+// Sessions are state (#68): the front door keeps them as records (head
+// `frontdoor/sessions`); this side holds none.
+//
+// One table (#143; docs/MESSAGES.md "The front door"). Every HTTP request
+// goes to the kernel's door: its route matched (exact path, then the longest
+// prefix), the route's filters run (kernel.brc104 — the session and signature
+// — kernel.beef, an app's own), the gate checked. What passes is admitted —
+// one entry — and its thread waited on (frontDoor). What a filter rejects or
+// answers, and what the gate refuses, writes nothing: the door's answer comes
+// back at once (DoorAnswered) and the front door's fn "respond" signs it on
+// the request's session when the request is signed (a call: nothing logged).
+// A read route — filters only, no handler — is such an answer: the host
+// serves it by the door, as a call, its fuel on the host's meter. The
+// handshake (/.well-known/auth) is a route of its own (the front door's).
+import * as dagCbor from "@ipld/dag-cbor";
+import { encode } from "../runtime/cid.js";
+import { stampMs } from "../runtime/log.js";
+import { now as clockNow } from "./clock.js";
+import { DoorAnswered } from "./door-answer.js";
+/** How long a synchronous client waits on its request's thread by default (ms): SKEIN_ANSWER_WAIT_MS, else two minutes. */
+export const ANSWER_WAIT_MS = Number(process.env.SKEIN_ANSWER_WAIT_MS) > 0 ? Number(process.env.SKEIN_ANSWER_WAIT_MS) : 120_000;
+/** The Retry-After (s) a client that waited past the bound, or met a host shutting down, is told. */
+export const RETRY_AFTER_S = 5;
+const jsonBody = (v) => new TextEncoder().encode(JSON.stringify(v));
+/** 503 + Retry-After: the wait's bound passed (the thread goes on), or the host is shutting down. */
+export function unavailable(description, extra = {}) {
+    return { status: 503, headers: { "content-type": "application/json", "retry-after": String(RETRY_AFTER_S) }, body: jsonBody({ status: "error", code: "ERR_UNAVAILABLE", description }), ...extra };
+}
+/** Lower-cased header names, one value each (joined with ", "). */
+export function headerMap(h) {
+    const out = {};
+    const add = (k, v) => { if (v !== undefined)
+        out[k.toLowerCase()] = Array.isArray(v) ? v.join(", ") : v; };
+    if (h instanceof Headers)
+        h.forEach((v, k) => add(k, v));
+    else
+        for (const [k, v] of Object.entries(h))
+            add(k, v);
+    return out;
+}
+/**
+ * Append a package as received (#68): one `request` entry naming it and its
+ * transport. The record goes with the frame, not into the store (#121): the
+ * kernel's door matches the route, runs its filters and the gate, and puts
+ * the package as it hands it back (a BEEF's bytes never stored), so the entry
+ * written — its CID, returned — may name another record than this. A package
+ * the door turns away or answers writes nothing (#143): DoorAnswered.
+ */
+export async function appendRequest(k, transport, record, time = clockNow()) {
+    return await k.admit({ request: cidOf(record), transport }, { request: record }, time);
+}
+/** An HTTP request's record (log.zig: {kind: "http", method, path, route, query, headers, body}). */
+export function httpRecord(req) {
+    return { kind: "http", method: req.method, path: req.path, route: req.route ?? req.path, query: req.query, headers: req.headers, body: req.body };
+}
+/**
+ * One HTTP request through the instance: appended, then waited on (#66)
+ * until its thread comes to rest or `waitMs` passes (503 + Retry-After).
+ * `stop`, when it settles first, answers 503 too (the host shutting down).
+ */
+export async function frontDoor(k, req, o = {}) {
+    const now = o.now ?? clockNow();
+    let entry;
+    try {
+        entry = await appendRequest(k, "http", httpRecord(req), now);
+    }
+    catch (e) {
+        if (e instanceof DoorAnswered)
+            return await doorAnswer(k, e.answer, req, now);
+        throw e;
+    }
+    const waited = k.answer(entry, o.waitMs ?? ANSWER_WAIT_MS);
+    const a = o.stop ? await Promise.race([waited, o.stop.then(() => undefined)]) : await waited;
+    if (!a)
+        return unavailable("the host is shutting down", { entry });
+    return await httpAnswer(k, entry, a, req);
+}
+/**
+ * A request thread's answer as the HTTP response: its last step's, a read after it, or 500/503.
+ * `req`, the request as received: a door refusal of a signed one is answered by the front door.
+ */
+export async function httpAnswer(k, entry, a, req) {
+    const at = { entry, ...(a.thread ? { thread: a.thread } : {}) };
+    void req;
+    if (a.state === "errored")
+        return { status: 500, headers: { "content-type": "application/json" }, body: jsonBody({ status: "error", code: "ERR_FRONT_DOOR", description: a.error }), ...at };
+    if (a.state !== "finished")
+        return unavailable(`not answered yet (its thread is ${a.state}): try again`, at);
+    const r = dagCbor.decode(a.answer);
+    if (r.read !== undefined && r.status === undefined) {
+        const caller = r.read?.caller instanceof Uint8Array ? { caller: Buffer.from(r.read.caller).toString("hex") } : {};
+        // A read of live state (the explorer): the front door answers it as a call, and signs it there.
+        const c = await k.invoke("frontdoor", "read", dagCbor.encode({ request: await requestOf(k, entry), read: r.read }));
+        if (!c.ok)
+            return { status: 500, headers: { "content-type": "application/json" }, body: jsonBody({ status: "error", code: "ERR_FRONT_DOOR", description: c.error }), fuel: c.fuel, ...caller, ...at };
+        const x = dagCbor.decode(c.result);
+        return { status: x.status, headers: x.headers ?? {}, body: x.body ?? new Uint8Array(), fuel: c.fuel, ...caller, ...at };
+    }
+    if (typeof r.status !== "number")
+        return { status: 500, headers: { "content-type": "application/json" }, body: jsonBody({ status: "error", code: "ERR_FRONT_DOOR", description: "the request's thread ended with no answer" }), ...at };
+    return { status: r.status, headers: r.headers ?? {}, body: r.body ?? new Uint8Array(), ...at };
+}
+/**
+ * The door's answer without an entry (#143: a filter's rejection or answer — a read route's — or the
+ * gate's refusal), as the HTTP response: a signed request gets it signed on its session — a
+ * front-door call (fn "respond") with the request as received, at the request's time — and an
+ * unsigned one, or one whose session does not verify (unknown, expired: the stock client shakes
+ * hands again), gets it plain.
+ */
+export async function doorAnswer(k, d, req, now = clockNow()) {
+    const meter = { fuel: d.fuel, ...(d.principal ? { caller: Buffer.from(d.principal).toString("hex") } : {}) };
+    const plain = d.kind === "answer"
+        ? { status: d.status, headers: { ...(d.headers ?? {}), "content-type": d.type ?? d.headers?.["content-type"] ?? "application/json" }, body: d.body ?? new Uint8Array(), ...meter }
+        : { status: d.status, headers: { "content-type": "application/json" }, body: jsonBody({ status: "error", code: d.code ?? "ERR_REFUSED", description: d.reason ?? "refused" }), ...meter };
+    if (!isSigned(req.headers))
+        return plain;
+    const arg = d.kind === "answer"
+        ? { request: httpRecord(req), answer: { status: d.status, ...(d.type ? { type: d.type } : {}), ...(d.headers ? { headers: d.headers } : {}), body: d.body ?? new Uint8Array() } }
+        : { request: httpRecord(req), refused: { status: d.status, code: d.code ?? "ERR_REFUSED", reason: d.reason ?? "refused" } };
+    const c = await k.invoke("frontdoor", "respond", dagCbor.encode(arg), { now: stampMs(now) });
+    if (!c.ok)
+        return plain;
+    const x = dagCbor.decode(c.result);
+    return { status: x.status, headers: x.headers ?? {}, body: x.body ?? new Uint8Array(), ...meter, fuel: d.fuel + c.fuel };
+}
+/** The request record an entry names. */
+async function requestOf(k, entry) {
+    const e = await k.store.get(entry);
+    if (!e.request)
+        throw new Error(`${entry} is not a request entry`);
+    return e.request;
+}
+// ---------------------------------------------------------------- one table (#143)
+/** The BRC-104 handshake's path: a route of its own (the front door's fn "handshake"). */
+export const HANDSHAKE_PATH = "/.well-known/auth";
+/** Whether a request carries BRC-104 headers (x-bsv-auth-*): a signed request. */
+export const isSigned = (headers) => Object.keys(headers).some((h) => h.toLowerCase().startsWith("x-bsv-auth-"));
+/**
+ * One HTTP request through the kernel's door (#143): its route's filters decide — admitted and
+ * waited on, or answered at once with nothing logged (a read route; a rejection; the gate's refusal).
+ */
+export async function serveHttp(k, req, o = {}) {
+    return await frontDoor(k, req, o);
+}
+/** A fetch over one instance's door (serveHttp), no socket: for a client in a test, or a URL of the host's own. */
+export function frontDoorFetch(k, o = {}) {
+    return (async (input, init = {}) => {
+        const url = new URL(typeof input === "string" || input instanceof URL ? input : input.url);
+        const req = input instanceof Request ? input : new Request(url, init);
+        const body = new Uint8Array(await req.arrayBuffer());
+        const fr = { method: req.method, path: url.pathname, route: o.route ? o.route(url.pathname) : url.pathname, query: url.search, headers: headerMap(req.headers), body };
+        const a = await serveHttp(k, fr, { now: o.now?.(), waitMs: o.waitMs });
+        o.onAnswer?.(a);
+        return new Response(a.body.length ? Buffer.from(a.body) : null, { status: a.status, headers: a.headers });
+    });
+}
+export const cidOf = (v) => encode(v).cid;

package/dist/host/genesis.d.ts

@@ -0,0 +1,259 @@
+import type { CID } from "multiformats/cid";
+import { type DispatchRow, type Transport } from "../runtime/dispatch.ts";
+import type { Stamp } from "../runtime/syscalls.ts";
+import type { KernelSurface as Kernel } from "./kernel.ts";
+import type { FeedSpec } from "./feeds.ts";
+/** Session expiry (#33 part 2, #40): the instance's own policy, judged against the session record's stamp (a day). */
+export declare const SESSION_DEFAULTS: Record<string, string>;
+export declare const keyBytes: (hex: string) => Uint8Array;
+export declare const keyHex: (k: unknown) => string;
+type Named = {
+    handle: string;
+    domain: string;
+};
+/** What the host brings to a genesis: the instance's own facts and the parties it knows. */
+export interface Genesis2Config {
+    identity: string;
+    /**
+     * The initial root holders (hex; #143). Absent or empty: an image (#89) — a genesis with no root
+     * holder; its routes carry the claim route, and root comes with the claim. The host skein's is
+     * the operator's key (#142).
+     */
+    root?: string[];
+    handle: string;
+    domain: string;
+    infer?: string;
+    /** The first root holder's handle, for `names` (a code genesis). */
+    ownerHandle?: Named;
+    inferHandle?: Named;
+    /**
+     * The host's defaults. Code genesis: over DEFAULTS, whole. A system tree:
+     * only what the tree's config leaves unset (its behaviour comes from its tree).
+     */
+    defaults?: Record<string, string>;
+    /** Explicit host overrides (dev: SKEIN_FUEL_PER_STEP) that win even over a tree's config; `warn` says so when they do. */
+    overrides?: Record<string, string>;
+    warn?(line: string): void;
+    /** More box routes, after these (e.g. the wallet's boxes, #29): a box and its handler program record. */
+    subscriptions?: Array<{
+        box: string;
+        handler: CID;
+    }>;
+    /** More routes of any transport (#77), after these: the route as a system writes it (handler names resolved against the programs). */
+    dispatch?: DispatchSpec[];
+    /** Feeds the host holds for the instance (code genesis; a tree's config names its own). */
+    feeds?: FeedSpec[];
+    /** Code genesis (#51): libp2p for the instance (a tree's config names its own). */
+    libp2p?: Libp2pSpec;
+    /** Write scopes of genesis-wired programs beyond STOCK_SCOPES (#77): program name → head names (a prefix ends in `/`). */
+    scopes?: Record<string, string[]>;
+    /** A mailbox instance (#40): only the front door and the messagebox, keeping mail for its root from anyone. */
+    mailbox?: boolean;
+    /** The root holder's messagebox URL (#40): the one peer a genesis names (`defaults.ownerMessagebox`). */
+    ownerMessagebox?: string;
+    /** Where the instance's own domain resolves (`defaults.resolveOrigin`): the host's origin in dev. */
+    resolveOrigin?: string;
+    /**
+     * The network the whole host runs on (SKEIN_NETWORK: `main` | `test` | `regtest`), written as
+     * `defaults.walletNetwork` at the host's fill-ins level (a tree's config and `overrides` win).
+     * A network fact, not a host fact: the chain app takes its network from it (`config.chain.network`).
+     */
+    network?: string;
+    /**
+     * The address book's seed (#70): the host's providers (their keys, `local`,
+     * address = name; #126: no role) and, when the host knows it, the root holder's mailbox. Written
+     * into the head `peers` when the genesis is processed.
+     */
+    addressBook?: AddressSeed[];
+    /**
+     * The host's providers by name (hex keys: fetch, waker, cron, libp2p,
+     * status), for a config key written `$<name>` (`peers`, `names`).
+     */
+    providers?: Record<string, string>;
+    /**
+     * #142: an installed app's config at birth, by app name, merged over its manifest's `config` as an
+     * install's `--config` is (the host skein's onboard: domain, origin, name, note from host.env).
+     */
+    appConfig?: Record<string, Record<string, unknown>>;
+}
+/** One address book entry a genesis seeds (#70): key → transport and address. */
+export interface AddressSeed {
+    key: Uint8Array;
+    transport: "mailbox" | "libp2p" | "local";
+    address: string;
+    handle?: string;
+    domain?: string;
+}
+/**
+ * A route as a system writes it (etc/dispatch.json, #77, #143): `transport`
+ * defaults to `mailbox`; `address` a box (`*`: any box), an event's box, an
+ * HTTP path (with `prefix: true` for a prefix), a libp2p topic or
+ * `/<protocol>`; `filters` what runs before anything is recorded
+ * ("kernel.brc104", "kernel.beef", "<app>.<filter>"); `program` a program name
+ * (bin/<name>), a program record's CID, or `kernel` (an admin route: `fn` the
+ * operation — objects, head, dispatch, peers, grant, claim, tick), absent for a
+ * read route (http: its filters answer); `fn` a handler's function; anything
+ * else a handler's own setting (a file handler's `root`, `index`). No `sender`
+ * (#143).
+ */
+export interface DispatchSpec {
+    transport?: Transport;
+    address: string;
+    prefix?: boolean;
+    filters?: string[];
+    program?: string;
+    fn?: string;
+    [setting: string]: unknown;
+}
+/**
+ * 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 declare const ADMIN_OPS: readonly ["objects", "head", "dispatch", "peers", "grant"];
+export declare const ADMIN_ROWS: DispatchSpec[];
+/** What a kernel route may name: the admin operations, the claim (#89), and the host's tick (#130: the host row, billing.ts). */
+export declare const KERNEL_OPS: readonly ["objects", "head", "dispatch", "peers", "grant", "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 declare const CLAIM_ROW: DispatchSpec;
+/** The BRC-103 handshake's route (#143): the front door's, no filters (it makes the session). */
+export declare const HANDSHAKE_ROW: DispatchSpec;
+/**
+ * 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 declare const STOCK_HTTP: DispatchSpec[];
+/** What gates the genesis's own programs' functions (#143): the explorer is root's. */
+export declare const STOCK_ROLES: Record<string, string[]>;
+/**
+ * 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 declare const STOCK_DISPATCH: DispatchSpec[];
+/**
+ * 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 declare const MAILBOX_DISPATCH: DispatchSpec[];
+/**
+ * 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 declare const STOCK_SCOPES: Record<string, string[]>;
+/** A system's config (etc/config.json): every field optional; keys in hex, `$self`, `$infer` or a provider's `$<name>`. */
+export interface ConfigSpec {
+    defaults?: Record<string, string>;
+    peers?: Record<string, string>;
+    names?: Array<{
+        identityKey: string;
+        handle: string;
+        domain: string;
+    }>;
+    collect?: string[];
+    feeds?: FeedSpec[];
+    /** The root holder as a peer (#40): its messagebox URL — the one peer a genesis names. */
+    owner?: {
+        messagebox?: string;
+    };
+    /** libp2p (#51): the topics the host subscribes for the instance, the protocols it serves, the node's own listen addresses. */
+    libp2p?: Libp2pSpec;
+    /** Write scopes of the tree's genesis-wired programs (#77), over STOCK_SCOPES: program name → head names (a prefix ends in `/`). */
+    scopes?: Record<string, string[]>;
+    /** What gates the tree's genesis-wired programs' functions (#143), over STOCK_ROLES: {<role>: ["<program>.<fn>"]}. */
+    roles?: Record<string, string[]>;
+}
+/**
+ * libp2p as a system writes it (etc/config.json `libp2p`, #51): `topics` the
+ * host's node subscribes (each message a front-door step; its `libp2p` route
+ * comes from etc/dispatch.json), `protocols` it serves, each naming its
+ * handler — a program (bin/ name or CID; fn "libp2p") or {program, fn} —
+ * which becomes its route (unless the tree has one), `listen` this node's
+ * addresses over the host's.
+ */
+export interface Libp2pSpec {
+    topics?: string[];
+    protocols?: Record<string, string | {
+        program: string;
+        fn?: string;
+    }>;
+    listen?: string[];
+}
+/** A system resolved for one instance: what its genesis says besides who it is. */
+export interface System {
+    programs: Record<string, CID>;
+    /** The route table's seed (#77), programs resolved. */
+    dispatch: DispatchRow[];
+    /** What gates the genesis's own programs' functions (#143). */
+    roles: Record<string, string[]>;
+    scopes: Record<string, string[]>;
+    peers?: Record<string, Uint8Array>;
+    defaults: Record<string, string>;
+    names: Array<{
+        identityKey: Uint8Array;
+        handle: string;
+        domain: string;
+    }>;
+    collect: string[];
+    /** The system tree (a git tree CID): `main` starts there. */
+    tree?: CID;
+    feeds?: FeedSpec[];
+    /** libp2p (#51): what the host's libp2p node does for the instance. */
+    libp2p?: {
+        topics: string[];
+        protocols: string[];
+        listen?: string[];
+    };
+    /** #141: heads the genesis sets (an image's installed apps: `<app>/app`), name → record CID. */
+    heads?: Record<string, CID>;
+}
+/** A system's libp2p, checked: the genesis's `libp2p` and the routes its protocols add (those the tree lacks). */
+export declare function libp2pIn(spec: Libp2pSpec | undefined, specs: DispatchSpec[]): {
+    libp2p?: System["libp2p"];
+    specs: DispatchSpec[];
+};
+/** A key as a system writes it: hex, or `$self` / `$infer` (the host's), or a provider's `$<name>` (Genesis2Config.providers). */
+export declare function keyOf(s: string, c: Pick<Genesis2Config, "infer" | "providers"> & {
+    identity?: string;
+}): Uint8Array;
+/** A `$<name>` that this host has no provider for. */
+export declare class NoProvider extends Error {
+    readonly provider: string;
+    constructor(provider: string);
+}
+/** 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 declare function rowsOf(specs: DispatchSpec[], programs: Record<string, CID>): DispatchRow[];
+/**
+ * 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 declare function resolveSystem(c: Genesis2Config, programs: Record<string, CID>, config?: ConfigSpec, tree?: CID, specs?: DispatchSpec[]): System;
+/** The stock system in code: the kernel's pinned programs (its `programs` frame) and the stock seed. */
+export declare function codeSystem(c: Genesis2Config, programs: Record<string, CID>): System;
+/** The genesis record: who the instance is, and its system. */
+export declare function genesisRecord(c: Pick<Genesis2Config, "identity" | "root" | "handle" | "domain" | "addressBook">, s: System): Record<string, unknown>;
+/** The genesis record for a new instance over the kernel's programs (name → program record CID): code genesis. */
+export declare function genesis2(c: Genesis2Config, programs: Record<string, CID>): Record<string, unknown>;
+/** Write a genesis over `s` into an empty store through its kernel; the entry's CID. */
+export declare function writeSystemGenesis(k: Kernel, c: Genesis2Config, s: System, time?: Stamp): Promise<CID>;
+/** Code genesis (the stock system) into an empty store; the entry's CID. */
+export declare function writeGenesis(k: Kernel, c: Genesis2Config, time?: Stamp): Promise<CID>;
+export {};