@stasho/vf-records 0.0.1

package/README.md

@@ -0,0 +1,13 @@
+# @stasho/vf-records
+
+The wire codec for Stasho Verified Frontends records: domain/authority
+normalization, the on-chain memo payload encoder, and a raw Solana legacy
+message decoder.
+
+`checkPreparedMessage` is the public verifier-side helper — it re-derives
+what a prepared publish or transfer message should say and compares it
+against what the signer actually asked for, before that signer's key ever
+touches the message.
+
+Zero runtime dependencies, no Node-only imports — safe to import from a
+browser or from `@stasho/vf`.

package/dist/base58.d.ts

@@ -0,0 +1,3 @@
+/** Bitcoin-alphabet base58, the Solana address encoding. Zero dependencies. */
+export declare function base58Encode(bytes: Uint8Array): string;
+export declare function base58Decode(text: string): Uint8Array;

package/dist/base58.js

@@ -0,0 +1,50 @@
+const ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+const INDEX = new Map([...ALPHABET].map((c, i) => [c, i]));
+/** Bitcoin-alphabet base58, the Solana address encoding. Zero dependencies. */
+export function base58Encode(bytes) {
+    let zeros = 0;
+    while (zeros < bytes.length && bytes[zeros] === 0)
+        zeros++;
+    const digits = [];
+    for (let i = zeros; i < bytes.length; i++) {
+        let carry = bytes[i] ?? 0;
+        for (let j = 0; j < digits.length; j++) {
+            carry += (digits[j] ?? 0) << 8;
+            digits[j] = carry % 58;
+            carry = Math.floor(carry / 58);
+        }
+        while (carry > 0) {
+            digits.push(carry % 58);
+            carry = Math.floor(carry / 58);
+        }
+    }
+    let out = "1".repeat(zeros);
+    for (let i = digits.length - 1; i >= 0; i--)
+        out += ALPHABET[digits[i] ?? 0];
+    return out;
+}
+export function base58Decode(text) {
+    let zeros = 0;
+    while (zeros < text.length && text[zeros] === "1")
+        zeros++;
+    const bytes = [];
+    for (let i = zeros; i < text.length; i++) {
+        const value = INDEX.get(text[i] ?? "");
+        if (value === undefined)
+            throw new RangeError(`invalid base58 character ${JSON.stringify(text[i])}`);
+        let carry = value;
+        for (let j = 0; j < bytes.length; j++) {
+            carry += (bytes[j] ?? 0) * 58;
+            bytes[j] = carry & 0xff;
+            carry >>= 8;
+        }
+        while (carry > 0) {
+            bytes.push(carry & 0xff);
+            carry >>= 8;
+        }
+    }
+    const out = new Uint8Array(zeros + bytes.length);
+    for (let i = 0; i < bytes.length; i++)
+        out[zeros + i] = bytes[bytes.length - 1 - i] ?? 0;
+    return out;
+}

package/dist/client-check.d.ts

@@ -0,0 +1,31 @@
+import { type VfRecord } from "./records.ts";
+export type ExpectedRecord = {
+    kind: "pub";
+    domain: string;
+    cid: string;
+    version: string;
+} | {
+    kind: "transfer";
+    domain: string;
+    newVault: string;
+};
+export type CheckResult = {
+    ok: true;
+    payload: string;
+    record: VfRecord;
+} | {
+    ok: false;
+    reason: string;
+};
+export declare const CLIENT_CHECK_SKEW_MS: number;
+/**
+ * Spec §4 step 2. Everything a compromised backend could vary is pinned to
+ * what the client obtained on its own: the signer, the program, the account
+ * list, and every payload field except the server timestamp (bounded).
+ */
+export declare function checkPreparedMessage(args: {
+    message: Uint8Array;
+    signer: Uint8Array;
+    expected: ExpectedRecord;
+    now: number;
+}): CheckResult;

package/dist/client-check.js

@@ -0,0 +1,60 @@
+import { decodeLegacyMessage } from "./legacy-message.js";
+import { MEMO_PROGRAM_ID, encodeRecord, parsePayload } from "./records.js";
+import { base58Decode } from "./base58.js";
+export const CLIENT_CHECK_SKEW_MS = 10 * 60_000;
+const MEMO_KEY = base58Decode(MEMO_PROGRAM_ID);
+const eq = (a, b) => a.length === b.length && a.every((v, i) => v === b[i]);
+const refuse = (reason) => ({ ok: false, reason });
+/**
+ * Spec §4 step 2. Everything a compromised backend could vary is pinned to
+ * what the client obtained on its own: the signer, the program, the account
+ * list, and every payload field except the server timestamp (bounded).
+ */
+export function checkPreparedMessage(args) {
+    let m;
+    try {
+        m = decodeLegacyMessage(args.message);
+    }
+    catch (err) {
+        return refuse(`could not decode the message: ${err.message}`);
+    }
+    if (m.numRequiredSignatures !== 2)
+        return refuse(`header requires ${m.numRequiredSignatures} signatures, expected two signatures (fee payer + you)`);
+    const feePayer = m.accountKeys[0];
+    const customer = m.accountKeys[1];
+    if (!feePayer || !customer || !eq(customer, args.signer))
+        return refuse("account 1 is not your key");
+    if (eq(feePayer, args.signer))
+        return refuse("your key is listed as the fee payer");
+    if (m.instructions.length !== 1)
+        return refuse(`message has ${m.instructions.length} instructions, expected exactly one instruction`);
+    const ix = m.instructions[0];
+    const program = m.accountKeys[ix.programIdIndex];
+    if (!program || !eq(program, MEMO_KEY))
+        return refuse("instruction program is not the memo program");
+    if (ix.accounts.length !== 1 || ix.accounts[0] !== 1)
+        return refuse("your key must be the instruction's only account");
+    const payload = new TextDecoder().decode(ix.data);
+    const record = parsePayload(payload);
+    if (record === null)
+        return refuse("instruction data is not a stasho-vf record");
+    if (encodeRecord(record) !== payload)
+        return refuse("record payload carries content outside the canonical encoding");
+    if (record.kind !== args.expected.kind)
+        return refuse(`record is a ${record.kind}, you asked for a ${args.expected.kind}`);
+    if (record.domain !== args.expected.domain)
+        return refuse(`record is for ${record.domain}, not ${args.expected.domain}`);
+    if (record.kind === "pub" && args.expected.kind === "pub") {
+        if (record.cid !== args.expected.cid)
+            return refuse(`record cid ${record.cid} differs from ${args.expected.cid}`);
+        if (record.version !== args.expected.version)
+            return refuse(`record version ${record.version} differs from ${args.expected.version}`);
+    }
+    if (record.kind === "transfer" && args.expected.kind === "transfer" && record.newVault !== args.expected.newVault) {
+        return refuse(`transfer target ${record.newVault} differs from ${args.expected.newVault}`);
+    }
+    const t = Date.parse(record.ts);
+    if (!Number.isFinite(t) || Math.abs(t - args.now) > CLIENT_CHECK_SKEW_MS)
+        return refuse("record timestamp is more than 10 minutes from this clock");
+    return { ok: true, payload, record };
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./records.ts";
+export { base58Decode, base58Encode } from "./base58.ts";
+export type { LegacyInstruction, LegacyMessage } from "./legacy-message.ts";
+export { decodeLegacyMessage } from "./legacy-message.ts";
+export type { CheckResult, ExpectedRecord } from "./client-check.ts";
+export { checkPreparedMessage, CLIENT_CHECK_SKEW_MS } from "./client-check.ts";

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from "./records.js";
+export { base58Decode, base58Encode } from "./base58.js";
+export { decodeLegacyMessage } from "./legacy-message.js";
+export { checkPreparedMessage, CLIENT_CHECK_SKEW_MS } from "./client-check.js";

package/dist/legacy-message.d.ts

@@ -0,0 +1,19 @@
+export interface LegacyInstruction {
+    programIdIndex: number;
+    accounts: number[];
+    data: Uint8Array;
+}
+export interface LegacyMessage {
+    numRequiredSignatures: number;
+    numReadonlySignedAccounts: number;
+    numReadonlyUnsignedAccounts: number;
+    accountKeys: Uint8Array[];
+    recentBlockhash: Uint8Array;
+    instructions: LegacyInstruction[];
+}
+/**
+ * Decodes a LEGACY Solana transaction message (the shape `prepare` builds).
+ * Versioned messages (first byte with the high bit set) are refused: the
+ * publish path never builds one, so one arriving is not ours to sign.
+ */
+export declare function decodeLegacyMessage(bytes: Uint8Array): LegacyMessage;

package/dist/legacy-message.js

@@ -0,0 +1,65 @@
+class Reader {
+    bytes;
+    offset = 0;
+    constructor(bytes) {
+        this.bytes = bytes;
+    }
+    u8() {
+        const v = this.bytes[this.offset];
+        if (v === undefined)
+            throw new RangeError(`message truncated at byte ${this.offset}`);
+        this.offset += 1;
+        return v;
+    }
+    /** Solana "compact-u16" (ShortVec): little-endian 7-bit groups, high bit = more. */
+    compactU16() {
+        let value = 0;
+        for (let shift = 0; shift <= 14; shift += 7) {
+            const b = this.u8();
+            value |= (b & 0x7f) << shift;
+            if ((b & 0x80) === 0)
+                return value;
+        }
+        throw new RangeError("compact-u16 longer than 3 bytes");
+    }
+    take(n) {
+        if (this.offset + n > this.bytes.length)
+            throw new RangeError(`message truncated at byte ${this.offset}`);
+        const out = this.bytes.slice(this.offset, this.offset + n);
+        this.offset += n;
+        return out;
+    }
+    done() { return this.offset === this.bytes.length; }
+}
+/**
+ * Decodes a LEGACY Solana transaction message (the shape `prepare` builds).
+ * Versioned messages (first byte with the high bit set) are refused: the
+ * publish path never builds one, so one arriving is not ours to sign.
+ */
+export function decodeLegacyMessage(bytes) {
+    if ((bytes[0] ?? 0) & 0x80)
+        throw new RangeError("versioned message, expected legacy");
+    const r = new Reader(bytes);
+    const numRequiredSignatures = r.u8();
+    const numReadonlySignedAccounts = r.u8();
+    const numReadonlyUnsignedAccounts = r.u8();
+    const keyCount = r.compactU16();
+    const accountKeys = [];
+    for (let i = 0; i < keyCount; i++)
+        accountKeys.push(r.take(32));
+    const recentBlockhash = r.take(32);
+    const ixCount = r.compactU16();
+    const instructions = [];
+    for (let i = 0; i < ixCount; i++) {
+        const programIdIndex = r.u8();
+        const accountCount = r.compactU16();
+        const accounts = [];
+        for (let j = 0; j < accountCount; j++)
+            accounts.push(r.u8());
+        const data = r.take(r.compactU16());
+        instructions.push({ programIdIndex, accounts, data });
+    }
+    if (!r.done())
+        throw new RangeError("trailing bytes after the last instruction");
+    return { numRequiredSignatures, numReadonlySignedAccounts, numReadonlyUnsignedAccounts, accountKeys, recentBlockhash, instructions };
+}

package/dist/records.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Solana record codec (spec §5.3).
+ *
+ * Authority comes from ONE place: the SPL Memo program's own `Signed by <addr>`
+ * log line inside a SUCCESSFUL memo invoke bracket. The memo program verifies
+ * that every account passed to it is a signer of the executing instruction, so
+ * this holds for a PDA signing via CPI (Squads) exactly as for a plain keypair,
+ * without trusting any multisig program's internals.
+ *
+ * NEVER infer authority from account presence: `getSignaturesForAddress`
+ * returns every transaction that MENTIONS an address, and an attacker can land
+ * a transaction that mentions a vault while carrying a top-level memo with a
+ * forged payload. That transaction has no `Signed by <vault>` line, which is
+ * the only thing that separates it from a genuine record.
+ */
+export declare const MEMO_PROGRAM_ID = "MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr";
+export declare const VF_PREFIX = "stasho-vf:1:";
+export declare const SOLANA_BASE58_RE: RegExp;
+/**
+ * WHATWG-URL punycode: identical bytes in Node and browsers (`node:url` is
+ * off-limits in this package). The URL parser REPAIRS some input (percent
+ * decoding, trailing-dot stripping); every character it would repair is
+ * rejected up front so repaired input is never accepted (spec §2).
+ */
+export declare function normalizeDomain(input: string): string | null;
+/**
+ * Parses a chain-namespaced authority string (`solana:<base58>`). Every
+ * authority address on the wire and in the bindings store carries this
+ * namespace so a bare address is never mistaken for one (spec, Decision #417
+ * item 8).
+ */
+export declare function parseAuthority(value: string): {
+    chain: "solana";
+    address: string;
+} | null;
+export declare function formatAuthority(address: string): string;
+export type VfRecord = {
+    kind: "pub";
+    domain: string;
+    cid: string;
+    version: string;
+    ts: string;
+} | {
+    kind: "transfer";
+    domain: string;
+    newVault: string;
+    ts: string;
+} | {
+    kind: "bind";
+    domain: string;
+    vault: string;
+    op: "bind" | "unbind";
+    ts: string;
+};
+export declare function parsePayload(payload: string): VfRecord | null;
+export declare function encodeRecord(record: VfRecord): string;

package/dist/records.js

@@ -0,0 +1,122 @@
+/**
+ * Solana record codec (spec §5.3).
+ *
+ * Authority comes from ONE place: the SPL Memo program's own `Signed by <addr>`
+ * log line inside a SUCCESSFUL memo invoke bracket. The memo program verifies
+ * that every account passed to it is a signer of the executing instruction, so
+ * this holds for a PDA signing via CPI (Squads) exactly as for a plain keypair,
+ * without trusting any multisig program's internals.
+ *
+ * NEVER infer authority from account presence: `getSignaturesForAddress`
+ * returns every transaction that MENTIONS an address, and an attacker can land
+ * a transaction that mentions a vault while carrying a top-level memo with a
+ * forged payload. That transaction has no `Signed by <vault>` line, which is
+ * the only thing that separates it from a genuine record.
+ */
+export const MEMO_PROGRAM_ID = "MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr";
+export const VF_PREFIX = "stasho-vf:1:";
+export const SOLANA_BASE58_RE = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;
+const LABEL_RE = /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$/;
+/**
+ * WHATWG-URL punycode: identical bytes in Node and browsers (`node:url` is
+ * off-limits in this package). The URL parser REPAIRS some input (percent
+ * decoding, trailing-dot stripping); every character it would repair is
+ * rejected up front so repaired input is never accepted (spec §2).
+ */
+export function normalizeDomain(input) {
+    const trimmed = input.trim().toLowerCase().replace(/\.$/, "");
+    if (trimmed.length === 0 || trimmed.length > 253)
+        return null;
+    if (/[/:?#@\s[\]%\\]/.test(trimmed))
+        return null;
+    let ascii;
+    try {
+        ascii = new URL(`http://${trimmed}/`).hostname;
+    }
+    catch {
+        return null;
+    }
+    const labels = ascii.split(".");
+    if (labels.length < 2)
+        return null;
+    if (!labels.every((l) => LABEL_RE.test(l)))
+        return null;
+    return ascii;
+}
+/**
+ * Parses a chain-namespaced authority string (`solana:<base58>`). Every
+ * authority address on the wire and in the bindings store carries this
+ * namespace so a bare address is never mistaken for one (spec, Decision #417
+ * item 8).
+ */
+export function parseAuthority(value) {
+    const sep = value.indexOf(":");
+    if (sep < 0)
+        return null;
+    const chain = value.slice(0, sep);
+    const address = value.slice(sep + 1);
+    if (chain !== "solana" || !SOLANA_BASE58_RE.test(address))
+        return null;
+    return { chain: "solana", address };
+}
+export function formatAuthority(address) {
+    return `solana:${address}`;
+}
+export function parsePayload(payload) {
+    if (!payload.startsWith(VF_PREFIX))
+        return null;
+    const rest = payload.slice(VF_PREFIX.length);
+    const separator = rest.indexOf(":");
+    if (separator < 0)
+        return null;
+    const kind = rest.slice(0, separator);
+    let body;
+    try {
+        const parsed = JSON.parse(rest.slice(separator + 1));
+        if (typeof parsed !== "object" || parsed === null)
+            return null;
+        body = parsed;
+    }
+    catch {
+        return null;
+    }
+    const str = (key) => typeof body[key] === "string" && body[key] !== "" ? body[key] : null;
+    const domain = str("d");
+    const ts = str("t");
+    if (!domain || !ts)
+        return null;
+    if (normalizeDomain(domain) !== domain)
+        return null;
+    if (kind === "pub") {
+        const cid = str("c");
+        const version = str("v");
+        return cid && version ? { kind: "pub", domain, cid, version, ts } : null;
+    }
+    if (kind === "transfer") {
+        const newVault = str("newVault");
+        return newVault && parseAuthority(newVault) ? { kind: "transfer", domain, newVault, ts } : null;
+    }
+    if (kind === "bind") {
+        const vault = str("vault");
+        const op = str("op");
+        if (!vault || !parseAuthority(vault) || (op !== "bind" && op !== "unbind"))
+            return null;
+        return { kind: "bind", domain, vault, op, ts };
+    }
+    return null;
+}
+export function encodeRecord(record) {
+    if (record.kind === "pub") {
+        return `${VF_PREFIX}pub:${JSON.stringify({
+            d: record.domain, c: record.cid, v: record.version, t: record.ts,
+        })}`;
+    }
+    if (record.kind === "transfer") {
+        return `${VF_PREFIX}transfer:${JSON.stringify({
+            d: record.domain, newVault: record.newVault, t: record.ts,
+        })}`;
+    }
+    return `${VF_PREFIX}bind:${JSON.stringify({
+        d: record.domain, vault: record.vault, op: record.op, t: record.ts,
+    })}`;
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@stasho/vf-records",
+  "version": "0.0.1",
+  "description": "Stasho Verified Frontends record codec + the client-side check of a prepared publish message. Zero dependencies, browser-safe.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "lint": "oxlint src tests",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@solana/web3.js": "1.98.4",
+    "@types/node": "22.14.0",
+    "bs58": "6.0.0",
+    "oxlint": "1.58.0",
+    "typescript": "5.9.3",
+    "vitest": "4.1.0"
+  }
+}