@fangorn-network/westmarch 0.0.1-dev

package/publish/terms.js

@@ -0,0 +1,200 @@
+// Who gets paid, and how much, when something sells.
+//
+// An app owner registers terms; publishers join under them; a buyer pays once.
+// This file is the arithmetic in the middle, and it is the only revenue
+// mechanism in the whole architecture — discovery cannot be charged for (the
+// query never leaves the client and the index holds 4 KB per corpus), so a take
+// at settlement is the business model or there isn't one.
+//
+// Two layers, because they are set by different people at different times:
+//
+//   app terms   the owner's cut, fixed when the app is registered and hashed so
+//               a publisher can prove what they agreed to
+//   lineage     what a publisher owes UPSTREAM, declared per resource when they
+//               publish. Paid out of the publisher's share, never the app's:
+//               a derivative's author pays their sources, and the app's cut does
+//               not shrink because someone built on someone else.
+//
+// That second layer is the point. An agent buys three corpora, synthesises a
+// fourth, publishes it with lineage naming the three, and every later sale of
+// the derivative pays back up the chain. Knowledge in, concept out, concept
+// becomes knowledge someone else builds on — with the money following the
+// citations instead of stopping at the last hop.
+//
+// ponytail: BigInt base units, one level of lineage, no recursion. A derivative
+// OF a derivative declares its own immediate sources and each hop settles on its
+// own sale — walking the tree at settlement time would mean fetching a stranger's
+// terms mid-payment, and a payment that depends on someone else's server being
+// up is a payment that fails.
+
+const BPS = 10000n;
+const ADDR = /^0x[0-9a-fA-F]{40}$/;
+
+const addr = (a) => {
+    const s = String(a ?? "").toLowerCase();
+    if (!ADDR.test(s)) throw new Error(`not an address: ${a}`);
+    return s;
+};
+const bps = (n, what) => {
+    const v = BigInt(n ?? 0);
+    if (v < 0n || v > BPS) throw new Error(`${what} must be 0..10000 bps, got ${n}`);
+    return v;
+};
+
+/**
+ * An app's terms, canonical.
+ *
+ * Canonical because the hash is the thing a publisher agrees to and a buyer can
+ * check: same terms must produce the same bytes on any machine, in any key
+ * order, forever. So: fixed field order, lowercase addresses, decimal strings
+ * for numbers (JSON has no integers), and nothing else in the object.
+ */
+export function appTerms({ appId, owner, appBps = 0, currency = "USDC", chainId = 421614 }) {
+    if (!appId) throw new Error("terms need an appId");
+    return {
+        v: 1,
+        appId: String(appId),
+        owner: addr(owner),
+        appBps: String(bps(appBps, "appBps")),
+        currency: String(currency),
+        chainId: Number(chainId),
+    };
+}
+
+/** Canonical bytes → sha-256. Async because that is the only hash both node and
+ *  a browser have without a dependency. */
+export async function termsHash(t) {
+    const canon = JSON.stringify(appTerms(t));
+    const d = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(canon));
+    return `0x${[...new Uint8Array(d)].map((b) => b.toString(16).padStart(2, "0")).join("")}`;
+}
+
+/** What a publisher owes upstream for one resource. Deduped by payee — the same
+ *  source cited twice is one debt, not two, and merging is the only reading that
+ *  cannot be gamed by repeating an entry. */
+export function lineage(entries = []) {
+    const by = new Map();
+    for (const e of entries) {
+        const to = addr(e.to);
+        by.set(to, { to, bps: (by.get(to)?.bps ?? 0n) + bps(e.bps, "lineage bps"), note: e.note ?? by.get(to)?.note ?? "" });
+    }
+    const out = [...by.values()];
+    const total = out.reduce((s, e) => s + e.bps, 0n);
+    if (total > BPS) throw new Error(`lineage owes ${total} bps of the publisher's share — more than all of it`);
+    return out.map((e) => ({ to: e.to, bps: String(e.bps), ...(e.note ? { note: e.note } : {}) }));
+}
+
+/**
+ * One payment → the payouts it becomes.
+ *
+ * Integer base units end to end, and the dust is given to the publisher rather
+ * than rounded away: the payouts MUST sum to exactly what the buyer paid, or
+ * settlement is inventing or destroying money. Every share rounds down; the
+ * publisher absorbs the difference, which is at most one base unit per payee.
+ */
+export function splitPayment(amount, { terms, publisher, lineage: up = [] } = {}) {
+    const total = BigInt(amount);
+    if (total < 0n) throw new Error("amount must not be negative");
+    const t = appTerms(terms);
+    const pub = addr(publisher);
+
+    const payouts = [];
+    const appCut = (total * BigInt(t.appBps)) / BPS;
+    if (appCut > 0n) payouts.push({ to: t.owner, amount: appCut, why: `app ${t.appId} (${t.appBps} bps)` });
+
+    // Everything the app did not take is the publisher's, and upstream is paid
+    // out of that — so a publisher who cites nobody keeps it all, and one who
+    // builds on three sources pays them from their own half.
+    const publisherPool = total - appCut;
+    let owed = 0n;
+    for (const e of lineage(up)) {
+        const cut = (publisherPool * BigInt(e.bps)) / BPS;
+        if (cut === 0n) continue;
+        owed += cut;
+        payouts.push({ to: e.to, amount: cut, why: `upstream ${e.note || e.to.slice(0, 10)} (${e.bps} bps of the publisher's share)` });
+    }
+
+    const keeps = publisherPool - owed;
+    payouts.push({ to: pub, amount: keeps, why: "publisher" });
+
+    // Merge payees — an app owner who is also the publisher gets one payout, not
+    // two, and a downstream reconciliation that sees the same address twice has
+    // no way to tell a split from a double-pay.
+    const by = new Map();
+    for (const p of payouts) {
+        const at = by.get(p.to);
+        by.set(p.to, at ? { ...at, amount: at.amount + p.amount, why: `${at.why} + ${p.why}` } : p);
+    }
+    const merged = [...by.values()];
+    const sum = merged.reduce((s, p) => s + p.amount, 0n);
+    if (sum !== total) throw new Error(`payouts sum to ${sum}, buyer paid ${total}`);
+    return merged;
+}
+
+/** Human-readable, for a receipt or a quote. 6-decimal base units — every asset
+ *  this settles on is 6-decimal, and a bare "50000" on a buy button is not a
+ *  price anyone reads. */
+export const label = (base, currency = "USDC") => `${(Number(base) / 1e6).toFixed(2)} ${currency}`;
+
+// ── self-check: `node publish/terms.js` ────────────────────────────────────
+if (typeof process !== "undefined" && import.meta.url === `file://${process.argv[1]}`) {
+    const A = "0x" + "a".repeat(40);   // app owner
+    const P = "0x" + "b".repeat(40);   // publisher
+    const S1 = "0x" + "c".repeat(40);  // a source
+    const S2 = "0x" + "d".repeat(40);  // another
+    const T = { appId: "fangorn.tv", owner: A, appBps: 1000 };
+    const at = (ps, to) => ps.find((p) => p.to === to)?.amount ?? 0n;
+
+    // The plain case: 10% to the app, the rest to whoever published it.
+    let ps = splitPayment(1_000_000n, { terms: T, publisher: P });
+    if (at(ps, A) !== 100_000n || at(ps, P) !== 900_000n) throw new Error(`plain split wrong: ${JSON.stringify(ps, (k, v) => typeof v === "bigint" ? String(v) : v)}`);
+
+    // A derivative: two sources, 20% and 5% OF THE PUBLISHER'S SHARE. The app's
+    // cut must not move — that is the whole reason lineage comes out of the
+    // publisher's half.
+    ps = splitPayment(1_000_000n, { terms: T, publisher: P, lineage: [{ to: S1, bps: 2000 }, { to: S2, bps: 500 }] });
+    if (at(ps, A) !== 100_000n) throw new Error("the app's cut must not shrink because the publisher cited someone");
+    if (at(ps, S1) !== 180_000n || at(ps, S2) !== 45_000n) throw new Error(`upstream is a share of 900000: ${at(ps, S1)}/${at(ps, S2)}`);
+    if (at(ps, P) !== 675_000n) throw new Error(`publisher keeps the rest: ${at(ps, P)}`);
+
+    // Money is neither created nor destroyed, at any amount.
+    for (const amt of [0n, 1n, 3n, 7n, 999n, 1_000_001n, 123_456_789n]) {
+        const out = splitPayment(amt, { terms: T, publisher: P, lineage: [{ to: S1, bps: 3333 }, { to: S2, bps: 3333 }] });
+        const sum = out.reduce((s, p) => s + p.amount, 0n);
+        if (sum !== amt) throw new Error(`${amt} split into ${sum}`);
+        if (out.some((p) => p.amount < 0n)) throw new Error(`negative payout at ${amt}`);
+    }
+
+    // Dust goes to the publisher, never to rounding.
+    ps = splitPayment(7n, { terms: { ...T, appBps: 3333 }, publisher: P });
+    if (at(ps, A) !== 2n || at(ps, P) !== 5n) throw new Error(`dust must land on the publisher: ${JSON.stringify(ps.map((p) => [p.to.slice(0, 4), String(p.amount)]))}`);
+
+    // One payee, one payout: an app owner who publishes under their own app.
+    ps = splitPayment(1_000_000n, { terms: T, publisher: A });
+    if (ps.length !== 1 || at(ps, A) !== 1_000_000n) throw new Error("the same address must be paid once, not twice");
+
+    // Citing the same source twice is one debt.
+    ps = splitPayment(1_000_000n, { terms: T, publisher: P, lineage: [{ to: S1, bps: 1000 }, { to: S1, bps: 1000 }] });
+    if (at(ps, S1) !== 180_000n) throw new Error(`a repeated citation must merge, not double-pay: ${at(ps, S1)}`);
+
+    // Terms are refused, not silently clamped.
+    for (const bad of [{ ...T, appBps: 10001 }, { ...T, appBps: -1 }, { ...T, owner: "0xnope" }, { appId: "", owner: A }]) {
+        let threw = false;
+        try { splitPayment(1n, { terms: bad, publisher: P }); } catch { threw = true; }
+        if (!threw) throw new Error(`bad terms must throw: ${JSON.stringify(bad)}`);
+    }
+    let threw = false;
+    try { lineage([{ to: S1, bps: 6000 }, { to: S2, bps: 6000 }]); } catch { threw = true; }
+    if (!threw) throw new Error("a publisher cannot owe more than they have");
+
+    // The hash is what a publisher agreed to: stable across key order, and it
+    // moves the moment a single term does.
+    const h1 = await termsHash(T);
+    const h2 = await termsHash({ owner: A, appBps: 1000, appId: "fangorn.tv" });
+    if (h1 !== h2) throw new Error("key order must not change the hash");
+    if (h1 === await termsHash({ ...T, appBps: 1001 })) throw new Error("a changed cut must change the hash");
+    if (!/^0x[0-9a-f]{64}$/.test(h1)) throw new Error(`hash shape: ${h1}`);
+
+    console.log("terms.js self-check ok — app cut fixed, lineage paid from the publisher's share, payouts always sum to what was paid, "
+        + "dust to the publisher, repeated payees merged, bad terms refused, terms hash canonical");
+}

package/publish/vault.js

@@ -0,0 +1,162 @@
+// Your taste, sealed to your wallet, kept in Fangorn.
+//
+// WHY NOT localStorage, AND WHY NOT A URL
+// ---------------------------------------
+// `localStorage` is origin-scoped, so a taste learned in one app is invisible to
+// the next, and gone when the browser is. Passing it in a `?taste=` query fixes
+// the first problem and none of the others: it cannot survive a new machine, it
+// leaks the object into every referrer header and server log along the way, and
+// it makes the person responsible for carrying their own state around by hand.
+//
+// So the taste goes where every other durable thing in this system goes — the
+// graph — and the wallet is what opens it. Same wallet on a new laptop, same
+// taste, no export, no backup file, nothing to lose.
+//
+// WHY IT IS ENCRYPTED, WHICH IS NOT OPTIONAL
+// ------------------------------------------
+// A taste vector is not metadata about behaviour, it IS the behaviour: μ is where
+// you are, `no` is what you rejected, and both are directly comparable to every
+// corpus on the network. Publishing that in the clear, on a public chain, bound
+// permanently to an address, would build exactly the profile this project exists
+// to refuse — and worse than the ad networks do, because a chain does not forget
+// and cannot be asked to delete.
+//
+// The key is derived from ONE deterministic signature over a fixed string, which
+// is the same trick `sond3r/src/pay/buy.js:deriveBuyer` already uses to re-derive
+// a Semaphore identity on a machine that has never seen it. ECDSA signing is
+// deterministic (RFC 6979), so the wallet is the only input.
+//
+// The string is DIFFERENT from the identity one on purpose. Two secrets derived
+// from one signature are one secret, and the buyer identity is used to prove
+// payment — a vault that shared it would let anyone who could open your taste
+// also spend your entitlements.
+//
+// ponytail: a single key for the whole vault, rotated by nobody. Rotation needs
+// somewhere to put the version, and there is no second reader to coordinate with
+// yet. Add a `keyEpoch` to the vertex when one exists.
+
+const ENC = new TextEncoder();
+const DEC = new TextDecoder();
+
+/** The string the wallet signs. Domain-separated from `fangorn:identity:v1`. */
+export const VAULT_MESSAGE = "fangorn:taste-vault:v1";
+/** What a sealed blob announces itself as, so a reader can refuse politely. */
+export const VAULT_VERSION = 1;
+
+const b64 = (u8) => btoa(String.fromCharCode(...u8));
+const unb64 = (s) => Uint8Array.from(atob(s), (c) => c.charCodeAt(0));
+
+/**
+ * Wallet → the AES key that opens this person's vault.
+ *
+ * `walletClient` is anything with `signMessage({ account, message })` — viem's
+ * local account, a browser wallet, or a Privy signer. The signature never leaves
+ * this function; what comes back is a non-extractable CryptoKey.
+ */
+export async function vaultKey(walletClient) {
+    const account = walletClient.account;
+    const signature = await walletClient.signMessage({ account, message: VAULT_MESSAGE });
+    // HKDF, not the raw signature. A signature is 65 bytes of structured data
+    // with a recoverable public key in it — fine as key MATERIAL, wrong as a key.
+    const material = await crypto.subtle.importKey("raw", ENC.encode(signature), "HKDF", false, ["deriveKey"]);
+    return crypto.subtle.deriveKey(
+        { name: "HKDF", hash: "SHA-256", salt: ENC.encode("fangorn/taste-vault"), info: ENC.encode(VAULT_VERSION.toString()) },
+        material, { name: "AES-GCM", length: 256 }, false, ["encrypt", "decrypt"],
+    );
+}
+
+/** Seal any JSON-able object. A fresh IV every time, so two seals of the same
+ *  taste are not recognisably the same taste to anyone watching the chain. */
+export async function seal(key, obj) {
+    const iv = crypto.getRandomValues(new Uint8Array(12));
+    const ct = await crypto.subtle.encrypt({ name: "AES-GCM", iv }, key, ENC.encode(JSON.stringify(obj)));
+    return { v: VAULT_VERSION, iv: b64(iv), ct: b64(new Uint8Array(ct)) };
+}
+
+/** Open a sealed blob, or null. Null rather than throw: the common failure is
+ *  the wrong wallet, which is a question to ask the person, not a crash. */
+export async function open(key, blob) {
+    if (!blob || blob.v !== VAULT_VERSION || !blob.iv || !blob.ct) return null;
+    try {
+        const pt = await crypto.subtle.decrypt({ name: "AES-GCM", iv: unb64(blob.iv) }, key, unb64(blob.ct));
+        return JSON.parse(DEC.decode(pt));
+    } catch { return null; }
+}
+
+/**
+ * The vertex this becomes in the reader's own namespace.
+ *
+ * One id, overwritten on every sync, because a taste has no history worth keeping
+ * on-chain — and a chain of past selves is precisely the profile the encryption
+ * exists to prevent. The payload carries no `path`, so it never appears in an
+ * app's file tree; it is state, not content.
+ */
+export const TASTE_ID = "self/taste";
+export const tasteVertex = (blob) => ({
+    id: TASTE_ID, tag: "taste",
+    payload: { kind: "taste", model: "nomic-256", enc: `vault-v${VAULT_VERSION}`, blob: JSON.stringify(blob) },
+});
+
+/** Pull the sealed blob back out of whatever `fangorn read` handed over. */
+export function tasteFrom(vertices = []) {
+    const v = vertices.find((x) => (x.payload ?? x)?.kind === "taste");
+    if (!v) return null;
+    try { return JSON.parse((v.payload ?? v).blob); } catch { return null; }
+}
+
+// ── self-check: `node publish/vault.js` ───────────────────────────────────
+if (typeof process !== "undefined" && import.meta.url === `file://${process.argv[1]}`) {
+    const { privateKeyToAccount } = await import("viem/accounts");
+    const KEY_A = `0x${"11".repeat(32)}`, KEY_B = `0x${"22".repeat(32)}`;
+    // A "machine": a fresh client over the same key, holding no state at all.
+    const machine = (pk) => { const account = privateKeyToAccount(pk); return { account, signMessage: (a) => account.signMessage(a) }; };
+
+    const TASTE = { v: 1, model: "nomic-256", q: "AQIDBA==", mu: "BQYHCA==", from: ["Nosferatu (1922)"], rejected: ["a sitcom"], n: 6 };
+
+    const k1 = await vaultKey(machine(KEY_A));
+    const blob = await seal(k1, TASTE);
+    if (JSON.stringify(await open(k1, blob)) !== JSON.stringify(TASTE)) throw new Error("round trip must be exact");
+
+    // THE POINT: a different machine, no shared state, same wallet — same taste.
+    const k2 = await vaultKey(machine(KEY_A));
+    if (JSON.stringify(await open(k2, blob)) !== JSON.stringify(TASTE)) throw new Error("the same wallet on a new machine must open the vault");
+
+    // …and nobody else's wallet does.
+    if (await open(await vaultKey(machine(KEY_B)), blob) !== null) throw new Error("another wallet must not open it");
+
+    // The chain sees ciphertext and nothing else. The titles are the part that
+    // would identify a person, so they are the part that must not survive.
+    const wire = JSON.stringify(tasteVertex(blob));
+    for (const secret of ["Nosferatu", "sitcom", "AQIDBA==", "nomic-256\",\"q\""]) {
+        if (wire.includes(secret)) throw new Error(`the published vertex leaks ${JSON.stringify(secret)}`);
+    }
+    if (!wire.includes("vault-v1")) throw new Error("a reader must be able to tell what sealed this");
+    if (wire.includes("\"path\"")) throw new Error("a taste is state, not a file — it must not enter an app's tree");
+
+    // Two seals of one taste must not be recognisably equal to an observer.
+    const again = await seal(k1, TASTE);
+    if (again.ct === blob.ct || again.iv === blob.iv) throw new Error("a fresh IV every seal, or syncing twice announces 'unchanged'");
+    if (JSON.stringify(await open(k1, again)) !== JSON.stringify(TASTE)) throw new Error("…and both must still open");
+
+    // Tampering is caught by GCM rather than producing plausible garbage.
+    const bad = { ...blob, ct: blob.ct.slice(0, -4) + (blob.ct.endsWith("A") ? "BBBB" : "AAAA") };
+    if (await open(k1, bad) !== null) throw new Error("a modified blob must not open");
+    if (await open(k1, { ...blob, v: 99 }) !== null) throw new Error("an unknown version must be refused, not guessed at");
+    if (await open(k1, null) !== null || await open(k1, {}) !== null) throw new Error("absent input reads as absent, not as a crash");
+
+    // Domain separation: the vault key must not be the buyer identity's secret.
+    const acct = privateKeyToAccount(KEY_A);
+    const idSig = await acct.signMessage({ message: "fangorn:identity:v1" });
+    const vaultSig = await acct.signMessage({ message: VAULT_MESSAGE });
+    if (idSig === vaultSig) throw new Error("one signature for two secrets is one secret — opening a vault would grant spending");
+
+    // Round-trips out of the shape `fangorn read` returns.
+    if (JSON.stringify(tasteFrom([{ payload: { kind: "other" } }, tasteVertex(blob).payload ? tasteVertex(blob) : null].filter(Boolean))) !== JSON.stringify(blob)) {
+        throw new Error("the blob must survive a trip through the graph");
+    }
+    if (tasteFrom([]) !== null) throw new Error("an empty namespace is no taste, not a crash");
+
+    console.log("vault.js self-check ok — one deterministic signature opens it on any machine, no other wallet opens it, "
+        + "the published vertex carries ciphertext and no title, a fresh IV per sync, tampering and unknown versions refused, "
+        + "and the vault key is domain-separated from the buyer identity");
+}