@dcasegr/skein 0.0.0-stage → 0.1.1

package/dist/runtime/heads.js

@@ -0,0 +1,37 @@
+// Named heads (docs/VM.md, "Heads"): a chain per name, origin
+//
+//   { kind: "head", name }
+//
+// and one update per move, { tree, owner, thread, input, at } (the store adds
+// origin, prev, seq). The origin is the name's record, so a head is found by
+// encoding it; a name never moved has no chain. Only the kernel writes heads
+// (kernel-zig/src/heads.zig advanceHead): a program's step says so (the
+// `advance` import) and that step ends without error, or a kernel operation
+// does; the update names the thread and the log entry, so replay writes the
+// same chain. This side reads them. `main` is the tree `chat` and `run` start
+// from when they name none.
+import { encode } from "./cid.js";
+import { NotFound } from "./store.js";
+export const MAIN = "main";
+export const isHeadName = (x) => typeof x === "string" && x !== "" && !/[\s\0]/.test(x);
+/** The head's chain origin: the same CID in every store. */
+export function headOrigin(name) {
+    if (!isHeadName(name))
+        throw new TypeError(`head: bad name ${JSON.stringify(name)}`);
+    return encode({ kind: "head", name }).cid;
+}
+/** The tree a head names now, or undefined if it has never moved. */
+export async function headTree(store, name) {
+    const origin = headOrigin(name);
+    let tip;
+    try {
+        tip = await store.chains.tip(origin);
+    }
+    catch (e) {
+        if (e instanceof NotFound)
+            return undefined;
+        throw e;
+    }
+    return tip.equals(origin) ? undefined : treeOf(store, tip);
+}
+const treeOf = async (store, update) => (await store.get(update)).tree;

package/dist/runtime/identity.d.ts

@@ -0,0 +1,28 @@
+import { PublicKey, type WalletInterface, type WalletProtocol } from "@bsv/sdk";
+export type { WalletInterface };
+/** Every skein key is derived under this protocol, keyID = the service/actor name. */
+export declare const PROTOCOL: WalletProtocol;
+/** The part of BRC-100 skein's identities use. Any WalletInterface is one. */
+export type KeyWallet = Pick<WalletInterface, "getPublicKey" | "createSignature">;
+/** The public key (compressed hex) a wallet derives for `name`. */
+export declare function identityOf(wallet: KeyWallet, name: string): Promise<string>;
+/** The wallet's identity key: the instance's root. Nothing is signed with it directly (see Signer). */
+export declare function rootIdentity(wallet: KeyWallet): Promise<string>;
+export interface Signer {
+    /** DER ECDSA (secp256k1, low-S) over sha256(bytes), by the key behind `identity`. */
+    sign(bytes: Uint8Array): Promise<Uint8Array>;
+    identity: string;
+}
+export declare function signerFor(wallet: KeyWallet, name: string): Promise<Signer>;
+/**
+ * The public key a wallet signs with for (protocol, keyID, counterparty
+ * "anyone") under `identityKey` (BRC-42/43). Anyone can compute it: the
+ * counterparty "anyone" is the private key 1, so the shared secret is the
+ * identity key itself. This is how skein verifies log entries and
+ * envelopes without a wallet.
+ */
+export declare function anyoneKey(identityKey: string, protocol: WalletProtocol, keyID: string): PublicKey;
+/** Verify a DER signature over sha256(data) by the "anyone" key of (identityKey, protocol, keyID). */
+export declare function verifyAnyone(identityKey: string, protocol: WalletProtocol, keyID: string, data: Uint8Array, der: Uint8Array): boolean;
+/** Sign sha256(data) with the wallet's "anyone" key for (protocol, keyID): what verifyAnyone checks. */
+export declare function signAnyone(wallet: KeyWallet, protocol: WalletProtocol, keyID: string, data: Uint8Array): Promise<Uint8Array>;

package/dist/runtime/identity.js

@@ -0,0 +1,67 @@
+// Identities under a wallet, seen only as `KeyWallet` (BRC-100's
+// getPublicKey + createSignature); how it is connected (a remote wallet-api
+// over HTTP, an in-process wallet) is src/wallet.ts.
+import { createHash } from "node:crypto";
+import { PrivateKey, PublicKey, Signature } from "@bsv/sdk";
+/** Every skein key is derived under this protocol, keyID = the service/actor name. */
+export const PROTOCOL = [1, "skein"];
+// Keyed by wallet object: identities are a pure function of (root key, name),
+// and a round trip per lookup would dominate signing over a remote wallet.
+const identities = new WeakMap();
+/** The public key (compressed hex) a wallet derives for `name`. */
+export function identityOf(wallet, name) {
+    let byName = identities.get(wallet);
+    if (!byName)
+        identities.set(wallet, (byName = new Map()));
+    let p = byName.get(name);
+    if (!p) {
+        p = wallet.getPublicKey({ protocolID: PROTOCOL, keyID: name, counterparty: "self" }).then((r) => r.publicKey);
+        p.catch(() => byName.delete(name)); // don't memoise a failure (wallet locked, permission not yet granted); the caller awaiting `p` gets the error itself
+        byName.set(name, p);
+    }
+    return p;
+}
+/** The wallet's identity key: the instance's root. Nothing is signed with it directly (see Signer). */
+export async function rootIdentity(wallet) {
+    return (await wallet.getPublicKey({ identityKey: true })).publicKey;
+}
+export async function signerFor(wallet, name) {
+    const identity = await identityOf(wallet, name);
+    return {
+        identity,
+        async sign(bytes) {
+            // Send the digest, not the data: a remote wallet needn't see the record.
+            const hash = [...createHash("sha256").update(bytes).digest()];
+            const { signature } = await wallet.createSignature({ protocolID: PROTOCOL, keyID: name, counterparty: "self", hashToDirectlySign: hash });
+            return Uint8Array.from(signature);
+        },
+    };
+}
+// ---------------------------------------------------------------- "anyone" signatures
+/**
+ * The public key a wallet signs with for (protocol, keyID, counterparty
+ * "anyone") under `identityKey` (BRC-42/43). Anyone can compute it: the
+ * counterparty "anyone" is the private key 1, so the shared secret is the
+ * identity key itself. This is how skein verifies log entries and
+ * envelopes without a wallet.
+ */
+export function anyoneKey(identityKey, protocol, keyID) {
+    const invoice = `${protocol[0]}-${protocol[1].toLowerCase().trim()}-${keyID}`;
+    return PublicKey.fromString(identityKey).deriveChild(new PrivateKey(1), invoice);
+}
+/** Verify a DER signature over sha256(data) by the "anyone" key of (identityKey, protocol, keyID). */
+export function verifyAnyone(identityKey, protocol, keyID, data, der) {
+    try {
+        // PublicKey.verify hashes with sha256 itself.
+        return anyoneKey(identityKey, protocol, keyID).verify([...data], Signature.fromDER([...der]));
+    }
+    catch {
+        return false;
+    }
+}
+/** Sign sha256(data) with the wallet's "anyone" key for (protocol, keyID): what verifyAnyone checks. */
+export async function signAnyone(wallet, protocol, keyID, data) {
+    const hash = [...createHash("sha256").update(data).digest()];
+    const { signature } = await wallet.createSignature({ protocolID: protocol, keyID, counterparty: "anyone", hashToDirectlySign: hash });
+    return Uint8Array.from(signature);
+}

package/dist/runtime/index-store.d.ts

@@ -0,0 +1,152 @@
+import { DatabaseSync } from "node:sqlite";
+import { CID } from "./cid.ts";
+import { type SqliteStore } from "./sqlite.ts";
+import { type Store } from "./store.ts";
+import type { Ref } from "./types.ts";
+export declare const MAPS: readonly ["log", "unique", "chains", "updates", "threads", "resting", "sleepers", "awaits", "edges", "heads"];
+export type MapName = typeof MAPS[number];
+export declare const STATE_KIND = "skein-state";
+/**
+ * A record as the TypeScript readers (the explorer, skein-dev, skein-host)
+ * show it. Format 2 (issue #33, kernel-zig/src/log.zig) keeps identity keys,
+ * hashes and signatures as byte strings and a genesis's `names` as a list;
+ * here they read back as the hex (and the `{key: name}` map) the display code
+ * knows, and a §7.3 envelope's `content` as base64. Display only: the
+ * record's CID is its stored bytes'.
+ */
+export declare function display(v: unknown): unknown;
+/**
+ * The Zig kernel's bitcoin codecs decoded the IPLD way (#42, bitcoin.ts,
+ * kernel-zig/src/bitcoin.zig): a header (bitcoin-block) links the previous
+ * header and its merkle root; a 64-byte bitcoin-tx is a merkle node linking
+ * its two children (nodes, or at the bottom transactions); a transaction's
+ * inputs link what they spend. The tree and the ancestry are sparse, so a
+ * link's target may not be held. The fields are the decoded node's.
+ */
+export { BITCOIN_BLOCK, BITCOIN_TX, DBL_SHA2_256 } from "./bitcoin.ts";
+export declare function bitcoinView(cid: CID, bytes: Uint8Array): {
+    codec: string;
+    fields: Array<[string, string | CID]>;
+} | undefined;
+export declare function be64(n: number | bigint): Uint8Array;
+export declare function readBe64(b: Uint8Array, at?: number): number;
+export declare function strKey(s: string): Uint8Array;
+declare function readStrKey(b: Uint8Array): {
+    s: string;
+    used: number;
+};
+export declare function cat(...parts: Uint8Array[]): Uint8Array;
+export declare function compare(a: Uint8Array, b: Uint8Array): number;
+/** The length of the binary CID at the front of `b` (binary CIDs are prefix-free). */
+declare function cidLen(b: Uint8Array): number;
+/** A key's level: sha2-256(key)'s leading zero 5-bit groups. */
+export declare function level(key: Uint8Array): number;
+type Entry = [Uint8Array, unknown, CID | null];
+type Node = [CID | null, Entry[]];
+/** Read the trees through `get` (a block's bytes by CID). */
+export declare class Trees {
+    private cache;
+    private readonly get;
+    constructor(get: (cid: CID) => Uint8Array | undefined);
+    node(cid: CID): Node;
+    lookup(root: CID | null, key: Uint8Array): unknown;
+    /** Entries with lo <= key < hi, in key order. */
+    range(root: CID | null, lo?: Uint8Array, hi?: Uint8Array): Generator<[Uint8Array, unknown]>;
+    prefixed(root: CID | null, p: Uint8Array): Generator<[Uint8Array<ArrayBufferLike>, unknown], any, any>;
+}
+/** The canonical tree of these pairs: its root, and its nodes (to store). */
+export declare function buildTree(pairs: Array<[Uint8Array, unknown]>): {
+    root: CID | null;
+    blocks: Array<{
+        cid: CID;
+        bytes: Uint8Array;
+    }>;
+};
+export interface State {
+    cid: CID;
+    log: CID | null;
+    cursor: number;
+    roots: Record<MapName, CID | null>;
+}
+export declare function readState(get: (cid: CID) => Uint8Array | undefined, cid: CID): State;
+/** Every map's pairs for a store's chains and log, as index.zig derives them. */
+export declare function derive(store: Store): Promise<{
+    pairs: Record<MapName, Array<[Uint8Array, unknown]>>;
+    log: CID | null;
+    cursor: number;
+}>;
+/** Does this SQLite file carry the state pointer (the format of #30)? */
+export declare function hasStatePointer(path: string): boolean;
+/**
+ * A store file, whichever format it is in: the new format (#30) through the
+ * index, read only (blocks may be added unless `readOnly`); any other
+ * through sqlite.ts. (An LMDB set, `lmdb:<env dir>#<set>`: src/host/stores.ts.)
+ */
+export declare function openStoreFile(path: string, o?: {
+    readOnly?: boolean;
+}): SqliteStore;
+/** A store over the kernel's index (#30): its state record, and every head's name and root (the state's `heads` map). */
+export type IndexStore = SqliteStore & {
+    state(): State;
+    heads(): Array<{
+        name: string;
+        root: CID;
+    }>;
+};
+export declare function indexStore(db: DatabaseSync, o?: {
+    readOnly?: boolean;
+}): IndexStore;
+/**
+ * What the index reader needs of a backend (as index.zig's `Backend`): blocks by binary CID, the
+ * state pointer (read on every call: a reader beside a live kernel follows it), a put if writable.
+ */
+export interface Blocks {
+    get(cid: Uint8Array): Uint8Array | undefined;
+    has(cid: Uint8Array): boolean;
+    put?(cid: Uint8Array, bytes: Uint8Array): void;
+    pointer(): Uint8Array | undefined;
+    close(): void;
+}
+export declare function indexStoreOver(src: Blocks): IndexStore;
+/** host.db's `store` column for a set of the host's LMDB environment: `lmdb:<env dir>` (the set: the row's handle). */
+export declare const LMDB = "lmdb:";
+/** The chain's member set (#133): readable by every set (kernel-zig/src/lmdb_store.zig CHAIN_SET). */
+export declare const CHAIN_SET = "host/chain";
+/** Whether host.db's `store` column names a set of an LMDB environment. */
+export declare function isLmdb(store: string): boolean;
+/** host.db's `store` column for a set of the one-process kernel's RocksDB database (#158): `rocksdb:<db dir>` (the set: the row's handle). */
+export declare const ROCKSDB = "rocksdb:";
+/** Whether host.db's `store` column names a set of a RocksDB database (#158). */
+export declare function isRocks(store: string): boolean;
+/**
+ * host.db's `store` column for a set of the host's one SQLite database (the settled split,
+ * 2026-10-31: the host loads the wasm kernel and keeps the storage, src/host/store-sqlite.ts):
+ * `sqlite:<db path>` (the set: the row's handle).
+ */
+export declare const SQLITE = "sqlite:";
+/** Whether host.db's `store` column names a set of the host's SQLite database. */
+export declare function isSqliteSet(store: string): boolean;
+/** Whether a store is a set of a host's shared store (LMDB #96, RocksDB #158, SQLite 2026-10-31), not a file of its own. */
+export declare function isSet(store: string): boolean;
+/** A row's store as the kernel's tools and `openStoreFile` name it: its path, `lmdb:<env dir>#<handle>`, `rocksdb:<db dir>#<handle>` or `sqlite:<db path>#<handle>`. */
+export declare function storeSpec(row: {
+    store: string;
+    handle: string;
+}): string;
+/** `rocksdb:<db dir>#<set>` → its parts (kernel-zig/src/any_store.zig parseRocksSpec); undefined for anything else. */
+export declare function parseRocksSpec(spec: string): {
+    dir: string;
+    set: string;
+} | undefined;
+/** `sqlite:<db path>#<set>` → its parts; undefined for anything else. */
+export declare function parseSqliteSpec(spec: string): {
+    db: string;
+    set: string;
+} | undefined;
+/** `lmdb:<env dir>#<set>` → its parts (kernel-zig/src/any_store.zig parseSpec); undefined for a path. */
+export declare function parseLmdbSpec(spec: string): {
+    dir: string;
+    set: string;
+} | undefined;
+export { readStrKey, cidLen };
+export type { Ref };