baesian 0.0.0-stage → 1.0.1

package/dist/sshsig.js

@@ -0,0 +1,159 @@
+import { createHash, createPublicKey, sign, verify } from "node:crypto";
+import { NewerFormat, newestFormat } from "./schema.js";
+// OpenSSH signatures (D160): the hosted service signs each file a person writes with Ed25519, in OpenSSH's own format
+// (PROTOCOL.sshsig), so `ssh-keygen -Y verify -n baesian` can check one by hand. Node's crypto does the Ed25519; this
+// module reads and writes the format around it. docs/vault/Modules/src-trust.md describes it.
+/** The namespace every signature on a file carries (D160): a signature made for anything else never counts here. */
+export const NAMESPACE = "baesian";
+/** The namespace of the relay's draw proofs (P16 section 3), kept apart so a draw can never pass for a file's signature. */
+export const DRAW_NAMESPACE = "baesian-draw";
+const MAGIC = Buffer.from("SSHSIG");
+const BEGIN = "-----BEGIN SSH SIGNATURE-----";
+const END = "-----END SSH SIGNATURE-----";
+const ED25519 = "ssh-ed25519";
+/** A signature file that isn't one: unreadable, or not what this namespace and key type allow. */
+export class BadSignature extends Error {
+}
+/** Reads SSH's wire format: big-endian lengths before strings. */
+class Reader {
+    buf;
+    at = 0;
+    constructor(buf) {
+        this.buf = buf;
+    }
+    bytes(n) {
+        if (this.at + n > this.buf.length)
+            throw new BadSignature("it ends too soon");
+        const out = this.buf.subarray(this.at, this.at + n);
+        this.at += n;
+        return out;
+    }
+    uint32() {
+        return this.bytes(4).readUInt32BE(0);
+    }
+    string() {
+        return this.bytes(this.uint32());
+    }
+    done() {
+        return this.at === this.buf.length;
+    }
+}
+const uint32 = (n) => {
+    const b = Buffer.alloc(4);
+    b.writeUInt32BE(n);
+    return b;
+};
+const sshString = (b) => {
+    const buf = typeof b === "string" ? Buffer.from(b) : b;
+    return Buffer.concat([uint32(buf.length), buf]);
+};
+/** An `ssh-ed25519 AAAA…` key's wire form: the base64 part, checked to be an Ed25519 key. */
+export function publicKeyBlob(openssh) {
+    const [type, b64] = openssh.trim().split(/\s+/);
+    if (type !== ED25519 || !b64)
+        throw new BadSignature(`not an Ed25519 key in OpenSSH's form: ${type ?? "nothing"}`);
+    const blob = Buffer.from(b64, "base64");
+    const r = new Reader(blob);
+    if (r.string().toString() !== ED25519 || r.string().length !== 32 || !r.done())
+        throw new BadSignature("the key's bytes aren't an Ed25519 key");
+    return blob;
+}
+/** An Ed25519 public key in OpenSSH's form, `ssh-ed25519 AAAA…`, from Node's key object. */
+export function opensshPublicKey(key) {
+    const x = createPublicKey(key).export({ format: "jwk" }).x;
+    if (!x)
+        throw new BadSignature("not an Ed25519 key");
+    return `${ED25519} ${Buffer.concat([sshString(ED25519), sshString(Buffer.from(x, "base64url"))]).toString("base64")}`;
+}
+/** Node's key object for a wire-form Ed25519 public key. */
+function keyOf(blob) {
+    const r = new Reader(blob);
+    if (r.string().toString() !== ED25519)
+        throw new BadSignature("only Ed25519 keys sign Baesian's files");
+    const raw = r.string();
+    if (raw.length !== 32)
+        throw new BadSignature("the key isn't 32 bytes");
+    return createPublicKey({ key: { kty: "OKP", crv: "Ed25519", x: raw.toString("base64url") }, format: "jwk" });
+}
+/**
+ * Read a signature: armored, as `ssh-keygen -Y sign` writes it, or its base64 alone, as a draw proof is kept. A newer
+ * SSHSIG version than this Baesian reads throws `NewerFormat` (D157), naming `file`; anything else unreadable throws
+ * `BadSignature`.
+ */
+export function parseSignature(text, file = "the signature") {
+    const trimmed = text.trim();
+    let b64 = trimmed;
+    if (trimmed.startsWith(BEGIN)) {
+        if (!trimmed.endsWith(END))
+            throw new BadSignature("it has no end line");
+        b64 = trimmed.slice(BEGIN.length, -END.length);
+    }
+    b64 = b64.replace(/\s+/g, "");
+    if (!/^[A-Za-z0-9+/]+={0,2}$/.test(b64))
+        throw new BadSignature("it isn't base64");
+    const r = new Reader(Buffer.from(b64, "base64"));
+    if (!r.bytes(6).equals(MAGIC))
+        throw new BadSignature("it isn't an SSH signature");
+    const version = r.uint32();
+    if (version > newestFormat("signature"))
+        throw new NewerFormat(file, "signature", version);
+    if (version < 1)
+        throw new BadSignature(`it has version ${version}`);
+    const publicKey = r.string();
+    const namespace = r.string().toString();
+    r.string(); // reserved
+    const hashAlgorithm = r.string().toString();
+    if (hashAlgorithm !== "sha256" && hashAlgorithm !== "sha512")
+        throw new BadSignature(`it uses ${hashAlgorithm}, not sha256 or sha512`);
+    const sig = new Reader(r.string());
+    if (!r.done())
+        throw new BadSignature("it has bytes after the signature");
+    const keyType = sig.string().toString();
+    if (keyType !== ED25519)
+        throw new BadSignature(`it's a ${keyType} signature; only Ed25519 signs Baesian's files`);
+    const signature = sig.string();
+    if (signature.length !== 64 || !sig.done())
+        throw new BadSignature("the Ed25519 signature isn't 64 bytes");
+    return { publicKey, namespace, hashAlgorithm, signature };
+}
+/** The bytes an SSH signature signs (PROTOCOL.sshsig): the namespace, and the message's hash, never the message itself. */
+function toBeSigned(namespace, hashAlgorithm, message) {
+    const digest = createHash(hashAlgorithm).update(message).digest();
+    return Buffer.concat([MAGIC, sshString(namespace), sshString(""), sshString(hashAlgorithm), sshString(digest)]);
+}
+/** Whether `sig` is its own key's signature over `message`, in `namespace`. Which keys to trust is the caller's question. */
+export function signatureMatches(sig, message, namespace) {
+    if (sig.namespace !== namespace)
+        return false;
+    try {
+        return verify(null, toBeSigned(namespace, sig.hashAlgorithm, message), keyOf(sig.publicKey), sig.signature);
+    }
+    catch {
+        return false;
+    }
+}
+/** The signature's blob, armored as `ssh-keygen` writes it: lines of 70 characters. */
+function armor(blob) {
+    const b64 = blob.toString("base64");
+    const lines = b64.match(/.{1,70}/g) ?? [];
+    return `${BEGIN}\n${lines.join("\n")}\n${END}\n`;
+}
+/**
+ * Sign `message` with an Ed25519 private key, as `ssh-keygen -Y sign -n <namespace>` does (SHA-512 by default). The
+ * relay signs this way, as do the tests' stand-in for it; `bare` gives the base64 alone, for a draw proof.
+ */
+export function signMessage(privateKey, message, namespace, opts = {}) {
+    const hashAlgorithm = opts.hashAlgorithm ?? "sha512";
+    const signature = sign(null, toBeSigned(namespace, hashAlgorithm, message), privateKey);
+    const blob = Buffer.concat([
+        MAGIC,
+        uint32(1),
+        sshString(publicKeyBlob(opensshPublicKey(privateKey))),
+        sshString(namespace),
+        sshString(""),
+        sshString(hashAlgorithm),
+        sshString(Buffer.concat([sshString(ED25519), sshString(signature)])),
+    ]);
+    return opts.bare ? blob.toString("base64") : armor(blob);
+}
+//# sourceMappingURL=sshsig.js.map

package/dist/state.js

@@ -0,0 +1,135 @@
+import { blankRow, countedCards, replayCards, routingReport } from "./report.js";
+import { ALL_ROWS, LEVEL_AT, POSITIONS, POSITION_NAMES, PRESETS, ROW_FLOOR, ROW_NAMES, SURVEY, SURVEY_QUESTION, isFixed, replay } from "./routing.js";
+import { linkText } from "./wikilinks.js";
+/** A deck's context notes where there's no vault to resolve them in: each link, with what it shows. */
+export const plainNotes = (links) => links.map((link) => ({ link, text: linkText(link) }));
+/** The state `GET /api/state` returns, read as one consistent view (D96). A file that can't be read is in `problems`. */
+export function snapshot(store, ctx) {
+    const problems = [];
+    const notes = ctx.notes ?? plainNotes;
+    return store.view(() => {
+        const cards = [];
+        const all = store.cardIds().flatMap((id) => store.card(id) ?? []);
+        const dependents = new Map();
+        for (const c of all)
+            for (const p of c.meta.depends_on)
+                dependents.set(p, [...(dependents.get(p) ?? []), c.meta.id]);
+        const nowMs = ctx.now ?? Date.now();
+        for (const c of all) {
+            const id = c.meta.id;
+            try {
+                const decision = store.decision(id);
+                const status = store.status(id);
+                const gate = store.gateRecord(id, c.meta.revision);
+                cards.push({
+                    meta: c.meta,
+                    body: c.body,
+                    revisions: store.revisions(id).length,
+                    replied: store.revisions(id).some((r) => r.meta.reply !== undefined),
+                    status,
+                    ...(decision !== undefined ? { decision } : {}),
+                    canonicalTopic: store.canonicalTopic(c.meta.topic),
+                    verdicts: store.verdicts(id),
+                    dependents: dependents.get(id) ?? [],
+                    briefs: store.briefs(id),
+                    waiting: store.waitingOn(id, nowMs).map(({ marker, stale }) => ({ agent: marker.agent, since: marker.since, at: marker.at, stale })),
+                    fallbacks: store.fallbacks(id),
+                    attachments: store.attachments(id).length,
+                    ...(gate ? { gate } : {}),
+                    ...(status === "held" && gate?.drawn ? { audit: true } : {}),
+                    ...(status === "resolved" && store.decidedBeforeLinking(id) ? { before_linking: true } : {}),
+                });
+            }
+            catch (e) {
+                problems.push({ path: `cards/${id}`, error: e instanceof Error ? e.message : String(e) });
+            }
+        }
+        const presence = store.presence();
+        const defaultBranch = readDefaultBranch(store, problems);
+        return {
+            version: ctx.version,
+            server: { ...(ctx.server.pid !== undefined ? { pid: ctx.server.pid } : {}), started: ctx.server.started, now: new Date(nowMs).toISOString(), watch: ctx.server.watch },
+            project: ctx.project,
+            ...(defaultBranch ? { defaultBranch } : {}),
+            ...(presence ? { presence } : {}),
+            decks: store.decks().map((d) => ({ ...d, notes: notes(d.meta.context_notes) })),
+            rules: store.rules(),
+            cards,
+            routing: routingState(store, problems),
+            problems,
+            ...branchesState(store),
+        };
+    }, (path, error) => problems.push({ path, error }));
+}
+/**
+ * The repo's default branch (B-jr8mk), the trunk the branches panel draws on top: read from git on your machine, from
+ * what a machine sent on the relay (`Store.defaultBranch`). One that can't be read is left out, as the panel then guesses.
+ */
+function readDefaultBranch(store, problems) {
+    try {
+        return store.defaultBranch();
+    }
+    catch (e) {
+        problems.push({ path: "default-branch.json", error: e instanceof Error ? e.message : String(e) });
+        return undefined;
+    }
+}
+/**
+ * What the branches panel draws besides the cards (D181): the merges the hooks found, each with the tip that landed and
+ * the commits citing cards it brought (B-w41p7), and the commits the ledger says cite cards, each once: its ID, time,
+ * branch and card, never its subject.
+ */
+function branchesState(store) {
+    const merges = store.merges().map(({ type: _t, format: _f, ...m }) => m);
+    const seen = new Set();
+    const commits = store.ledgerEntries().flatMap((e) => {
+        const commit = e.meta.commit;
+        if (!commit || seen.has(`${commit} ${e.meta.card}`))
+            return [];
+        seen.add(`${commit} ${e.meta.card}`);
+        return [{ commit, branch: e.meta.branch, card: e.meta.card, at: e.meta.at }];
+    });
+    return { merges, commits };
+}
+/** The preferences in force, their history, and the report per row (M8), for the state. */
+function routingState(store, problems) {
+    const force = store.inForce();
+    const history = store.preferenceNames().flatMap((name) => {
+        const file = store.preferenceFile(name);
+        return file ? [{ name, file }] : [];
+    });
+    let report;
+    try {
+        report = routingReport(store, force);
+    }
+    catch (e) {
+        problems.push({ path: "preferences", error: e instanceof Error ? e.message : String(e) });
+        report = { rows: {}, pooled: blankRow(), beforeGate: 0 };
+    }
+    return {
+        ...(force.name && force.file ? { preferences: { name: force.name, file: force.file } } : {}),
+        ...(force.problem ? { problem: force.problem } : {}),
+        settings: force.settings,
+        history,
+        report,
+    };
+}
+/** `GET /api/presets` (M8): the rows and positions, each preset and the settings in force replayed over past cards, and the setup survey. */
+export function presets(store) {
+    return store.view(() => {
+        const cards = replayCards(countedCards(store));
+        const force = store.inForce();
+        return {
+            rows: ALL_ROWS.map((row) => ({ row, name: ROW_NAMES[row], ...(isFixed(row) ? { fixed: true } : ROW_FLOOR[row] ? { floor: ROW_FLOOR[row] } : {}) })),
+            positions: POSITIONS.map((position) => ({ position, name: POSITION_NAMES[position], ...(LEVEL_AT[position] ? { level: LEVEL_AT[position] } : {}) })),
+            presets: PRESETS.map((p) => {
+                const settings = { ...force.settings, rows: p.rows };
+                return { id: p.id, name: p.name, summary: p.summary, settings, replay: replay(cards, settings) };
+            }),
+            inForce: { settings: force.settings, replay: replay(cards, force.settings) },
+            survey: { ...SURVEY_QUESTION, items: [...SURVEY] },
+        };
+        // A file that can't be read is left out, as the snapshot leaves it, rather than failing the request (D84).
+    }, () => { });
+}
+//# sourceMappingURL=state.js.map

package/dist/storage.js

@@ -0,0 +1,61 @@
+// The live layer's storage (B-0ag7h): what the store needs of a folder of files, and nothing more, so the same store
+// runs over a folder on your machine (`FolderStorage`, src/folder-storage.ts) and, on the relay, over a table in a
+// Durable Object (M9b). This module imports nothing from Node, so the relay can import it.
+/** A write-once file is already there: `Storage.create` refuses to write it again. Its `code` is Node's, `EEXIST`. */
+export class FileExists extends Error {
+    path;
+    code = "EEXIST";
+    constructor(path) {
+        super(`${path} is already written: a file is written once`);
+        this.path = path;
+    }
+}
+/** Whether an error says the file was already there: a `FileExists`, or Node's own `EEXIST`. */
+export function alreadyExists(e) {
+    return typeof e === "object" && e !== null && e.code === "EEXIST";
+}
+/** A path the store can name: relative, `/`-separated, with no empty, `.` or `..` part. The root folder is "". */
+export function checkPath(path, root = false) {
+    if (root && path === "")
+        return path;
+    if (path.split("/").some((p) => p === "" || p === "." || p === "..") || path.includes("\\"))
+        throw new Error(`not a path in the live layer: ${JSON.stringify(path)}`);
+    return path;
+}
+const copy = (bytes) => new Uint8Array(bytes);
+/**
+ * The live layer in memory (B-0ag7h): one entry per file, keyed by its path, as the relay's table will be. It stands in
+ * for the Durable Object's storage in tests, and in anything that runs the store with no repo. What it hands out is a
+ * copy, so nothing can change a file after it's written.
+ */
+export class MemoryStorage {
+    files = new Map();
+    read(path) {
+        const bytes = this.files.get(checkPath(path));
+        return bytes && copy(bytes);
+    }
+    list(dir) {
+        const prefix = checkPath(dir, true) === "" ? "" : `${dir}/`;
+        const names = new Set();
+        for (const path of this.files.keys())
+            if (path.startsWith(prefix))
+                names.add(path.slice(prefix.length).split("/")[0]);
+        return [...names];
+    }
+    create(path, bytes) {
+        if (this.files.has(checkPath(path)))
+            throw new FileExists(path);
+        this.files.set(path, copy(bytes));
+    }
+    replace(path, bytes) {
+        this.files.set(checkPath(path), copy(bytes));
+    }
+    remove(path) {
+        this.files.delete(checkPath(path));
+    }
+    /** Every file's path, sorted. */
+    paths() {
+        return [...this.files.keys()].sort();
+    }
+}
+//# sourceMappingURL=storage.js.map