@getcofund/protocol 0.0.0-stage → 0.1.0

package/dist/btc/witness.js

@@ -0,0 +1,439 @@
+/** biome-ignore-all lint/suspicious/noBitwiseOperators: a control block's first byte is the leaf version plus the output key's parity. */
+import { schnorr } from "@noble/curves/secp256k1.js";
+import { bytesToHex } from "@noble/hashes/utils";
+import * as btc from "@scure/btc-signer";
+import { OutScript, Script } from "@scure/btc-signer";
+import { vaultSpendSighash } from "./vault/spend.js";
+/** The control block of a leaf: its version plus the output key's parity, the internal key, and the merkle path. */
+export function encodeCBFromStruct(cbStruct) {
+    const parity = cbStruct.parity ?? 0;
+    return btc.TaprootControlBlock.encode({
+        version: (cbStruct.version + parity) & 0xff,
+        internalKey: cbStruct.internalKey,
+        merklePath: cbStruct.merklePath,
+    });
+}
+/**
+ * Does `sig` verify as `signerXonly`'s BIP340 signature over `msg`?
+ *
+ * The single answer to "did this key actually approve THIS exact transaction".
+ * Malformed input makes noble throw, which is easy to swallow by accident —
+ * always returning a boolean makes it hard for a call site to treat an
+ * unverifiable signature as an approval.
+ */
+export function verifyPartialSignatureAgainstMsg(msg, signerXonly, sig) {
+    // Tapscript CHECKSIG under SIGHASH_DEFAULT takes a bare 64-byte BIP340
+    // signature — no trailing sighash-flag byte.
+    if (sig.length !== 64) {
+        return false;
+    }
+    try {
+        return schnorr.verify(sig, msg, signerXonly);
+    }
+    catch {
+        return false;
+    }
+}
+/** The sighash a signer of `leaf` signs for input `inputIndex` of the spend. */
+function msgHashForLeaf(spend, leaf, inputIndex) {
+    return vaultSpendSighash(spend.tx, inputIndex, leaf.script);
+}
+function bytesEqual(a, b) {
+    return a.length === b.length && a.every((byte, index) => byte === b[index]);
+}
+/**
+ * Decode the policy Bitcoin actually executes, rather than trusting metadata.
+ *
+ * The hard threshold is committed by the tapscript. `Leaf.threshold` is useful
+ * descriptive metadata, but it must never be the authority used to decide how
+ * many signatures enter a witness.
+ */
+export function leafScriptPolicy(leaf) {
+    try {
+        const decoded = OutScript.decode(leaf.script);
+        if (decoded.type === "tr_ms") {
+            return {
+                kind: "non-admin-required",
+                signatureKeys: [...decoded.pubkeys],
+                threshold: decoded.m,
+            };
+        }
+    }
+    catch {
+        // ADMINS_REQUIRED has a CHECKSIGVERIFY prefix, so it is not a bare tr_ms.
+    }
+    try {
+        const ops = Script.decode(leaf.script);
+        const adminKey = ops[0];
+        if (!(adminKey instanceof Uint8Array) ||
+            adminKey.length !== 32 ||
+            ops[1] !== "CHECKSIGVERIFY") {
+            return null;
+        }
+        const prefix = Script.encode([adminKey, "CHECKSIGVERIFY"]);
+        const body = OutScript.decode(leaf.script.slice(prefix.length));
+        if (body.type !== "tr_ms") {
+            return null;
+        }
+        const bodyKeys = [...body.pubkeys];
+        return {
+            kind: "admin-required",
+            signatureKeys: [adminKey, ...bodyKeys],
+            threshold: body.m + 1,
+            adminKey,
+            bodyKeys,
+            bodyThreshold: body.m,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/** Match each script key to one leaf signer slot, preserving duplicate slots. */
+export function signerSlotsForScript(leaf, signatureKeys) {
+    const used = new Set();
+    return signatureKeys.map((key) => {
+        let matchedSigner;
+        for (let index = 0; index < leaf.signers.length; index++) {
+            const signer = leaf.signers[index];
+            if (!used.has(index) && bytesEqual(signer.xonly, key)) {
+                used.add(index);
+                matchedSigner = signer;
+                break;
+            }
+        }
+        return matchedSigner;
+    });
+}
+export function signatureSlotCountForLeaf(leaf) {
+    return leafScriptPolicy(leaf)?.signatureKeys.length ?? null;
+}
+// Build an ordered signature stack in reverse consumption order.
+// For signer i, the signature is placed at stack[n-1-i]. Missing or invalid -> empty push.
+//
+// Hydration retains all verified signatures. This NAR assembler selects the
+// exact threshold committed by the script; ADMINS_REQUIRED selects separately.
+//
+// A key contributes to the count AT MOST ONCE. New vaults can no longer be
+// built with two signer slots sharing a key, but one created before that
+// invariant existed still has a leaf where a single signature would satisfy
+// both slots — so the counting here is by distinct key, not by slot. A
+// legitimate spend by two different keyholders is unaffected, which is what
+// lets the funds be migrated off such a vault.
+export function orderedSigStackForLeaf(spend, leaf, inputIndex, bucket) {
+    const msg = msgHashForLeaf(spend, leaf, inputIndex);
+    const policy = leafScriptPolicy(leaf);
+    if (!policy || policy.kind !== "non-admin-required") {
+        return { stack: [], nonEmpty: 0 };
+    }
+    const { signatureKeys, threshold } = policy;
+    const signerSlots = signerSlotsForScript(leaf, signatureKeys);
+    const n = signatureKeys.length;
+    let taken = 0;
+    const countedKeys = new Set();
+    const stack = Array.from({ length: n }, () => new Uint8Array(0));
+    for (let i = 0; i < n; i++) {
+        const user = signerSlots[i];
+        if (!user) {
+            continue;
+        }
+        const sig = bucket.get(user.id);
+        const stackIdx = n - 1 - i;
+        if (!sig || sig.length === 0) {
+            stack[stackIdx] = new Uint8Array(0);
+            continue;
+        }
+        // Use leaf-local pubkey (per-branch derived for account-based vaults)
+        const pub = signatureKeys[i];
+        const pubHex = bytesToHex(pub);
+        // Checked before verifying: the signature would verify fine — it is the
+        // same key — and counting it again is exactly the collapse.
+        if (countedKeys.has(pubHex)) {
+            console.error(`[Leaf ${bytesToHex(leaf.leafHash)}] Refusing to reuse key ${pubHex} for ${user.id}: another signer slot already contributed it, which would double-count one signature toward the threshold.`);
+            stack[stackIdx] = new Uint8Array(0);
+            continue;
+        }
+        if (!verifyPartialSignatureAgainstMsg(msg, pub, sig)) {
+            console.error(`[Leaf ${bytesToHex(leaf.leafHash)}] Sig verify failed for ${user.id}`);
+            stack[stackIdx] = new Uint8Array(0);
+            continue;
+        }
+        if (taken < threshold) {
+            taken += 1;
+            countedKeys.add(pubHex);
+            stack[stackIdx] = sig;
+        }
+        else {
+            stack[stackIdx] = new Uint8Array(0);
+        }
+    }
+    return { stack, nonEmpty: taken };
+}
+function evaluateSignatureSlots(opts) {
+    const { spend, leaf, sigStack, signatureKeys, inputIndex } = opts;
+    const msg = msgHashForLeaf(spend, leaf, inputIndex);
+    const countedKeys = new Set();
+    const satisfied = Array.from({ length: signatureKeys.length }, () => false);
+    for (let index = 0; index < signatureKeys.length; index++) {
+        const stackIndex = signatureKeys.length - 1 - index;
+        const sig = sigStack[stackIndex];
+        // A malformed stack is an unsatisfied leaf, not an exceptional condition.
+        if (!sig || (sig.length !== 0 && sig.length !== 64)) {
+            return null;
+        }
+        if (sig.length === 0) {
+            continue;
+        }
+        // Verify against the key committed by the script, not roster metadata.
+        const pub = signatureKeys[index];
+        const pubHex = bytesToHex(pub);
+        if (countedKeys.has(pubHex)) {
+            console.error(`[Leaf ${bytesToHex(leaf.leafHash)}] Key ${pubHex} appears in more than one signed slot; not counting it twice toward the threshold.`);
+            continue;
+        }
+        if (!verifyPartialSignatureAgainstMsg(msg, pub, sig)) {
+            console.error(`[Leaf ${bytesToHex(leaf.leafHash)}] Sig verify failed at i=${index}`);
+            continue;
+        }
+        countedKeys.add(pubHex);
+        satisfied[index] = true;
+    }
+    return satisfied;
+}
+// Sum CHECKSIGADD results across signer order and compare to threshold.
+//
+// Counts DISTINCT keys, matching `orderedSigStackForLeaf`. Bitcoin itself would
+// count a repeated key twice (BIP-342 requires neither keys nor signatures in a
+// CHECKSIGADD ladder to be distinct); refusing to here is what stops cofund
+// from assembling a witness that meets the threshold with one signature.
+export function sigStackSolvesLeaf(spend, leaf, sigStack, inputIndex) {
+    const policy = leafScriptPolicy(leaf);
+    if (!policy || sigStack.length !== policy.signatureKeys.length) {
+        return false;
+    }
+    // The exact-length check above also rejects oversized stacks.
+    const satisfied = evaluateSignatureSlots({
+        spend,
+        leaf,
+        sigStack,
+        signatureKeys: policy.signatureKeys,
+        inputIndex,
+    });
+    if (!satisfied) {
+        return false;
+    }
+    if (policy.kind === "admin-required") {
+        const adminSatisfied = satisfied[0];
+        const bodySum = satisfied.slice(1).filter(Boolean).length;
+        return adminSatisfied && bodySum === policy.bodyThreshold;
+    }
+    return satisfied.filter(Boolean).length === policy.threshold;
+}
+// <adminX> CHECKSIGVERIFY <pk> CHECKSIG (<pk> CHECKSIGADD)* <k> NUMEQUAL
+/** An ADMINS_REQUIRED leaf: its admin, then its body signers in script order, and the body's k. */
+export function decodeAdminRequiredLeaf(leaf) {
+    const policy = leafScriptPolicy(leaf);
+    if (!policy || policy.kind !== "admin-required") {
+        return null;
+    }
+    const signerSlots = signerSlotsForScript(leaf, policy.signatureKeys);
+    if (signerSlots.some((signer) => !signer)) {
+        return null;
+    }
+    const [admin, ...body] = signerSlots;
+    if (!admin) {
+        return null;
+    }
+    const bodyOrderIds = [];
+    for (const signer of body) {
+        if (!signer) {
+            return null;
+        }
+        bodyOrderIds.push(signer.id);
+    }
+    return {
+        adminId: admin.id,
+        adminKey: policy.adminKey,
+        bodyOrderIds,
+        bodyKeys: policy.bodyKeys,
+        k: policy.bodyThreshold,
+    };
+}
+function addEligibleSigner(selection, eligibleSignerIds, signerId, key) {
+    const keyHex = bytesToHex(key);
+    if (!eligibleSignerIds.has(signerId) || selection.countedKeys.has(keyHex)) {
+        return false;
+    }
+    selection.countedKeys.add(keyHex);
+    selection.signerIds.push(signerId);
+    return true;
+}
+function selectAdminRequiredSignerIds(leaf, eligibleSignerIds) {
+    const decoded = decodeAdminRequiredLeaf(leaf);
+    const selection = {
+        countedKeys: new Set(),
+        signerIds: [],
+    };
+    if (!decoded) {
+        return null;
+    }
+    if (!addEligibleSigner(selection, eligibleSignerIds, decoded.adminId, decoded.adminKey)) {
+        return null;
+    }
+    for (let index = 0; index < decoded.bodyOrderIds.length; index++) {
+        addEligibleSigner(selection, eligibleSignerIds, decoded.bodyOrderIds[index], decoded.bodyKeys[index]);
+        if (selection.signerIds.length === decoded.k + 1) {
+            return selection.signerIds;
+        }
+    }
+    return null;
+}
+function selectNonAdminRequiredSignerIds(leaf, eligibleSignerIds) {
+    const policy = leafScriptPolicy(leaf);
+    if (!policy || policy.kind !== "non-admin-required") {
+        return null;
+    }
+    const signerSlots = signerSlotsForScript(leaf, policy.signatureKeys);
+    const selection = {
+        countedKeys: new Set(),
+        signerIds: [],
+    };
+    for (let index = 0; index < signerSlots.length; index++) {
+        const signer = signerSlots[index];
+        if (signer) {
+            addEligibleSigner(selection, eligibleSignerIds, signer.id, policy.signatureKeys[index]);
+        }
+        if (selection.signerIds.length === policy.threshold) {
+            return selection.signerIds;
+        }
+    }
+    return null;
+}
+/**
+ * Select the exact hard-threshold signer identities available for one leaf.
+ * Returns null when the eligible set cannot satisfy the on-chain script.
+ */
+export function selectHardThresholdSignerIds(leaf, vaultType, eligibleSignerIds) {
+    if (vaultType === "ADMINS_REQUIRED") {
+        return selectAdminRequiredSignerIds(leaf, eligibleSignerIds);
+    }
+    return selectNonAdminRequiredSignerIds(leaf, eligibleSignerIds);
+}
+function stackForNAR(spend, leaf, inputIndex, bucket) {
+    const { stack } = orderedSigStackForLeaf(spend, leaf, inputIndex, bucket);
+    if (!sigStackSolvesLeaf(spend, leaf, stack, inputIndex)) {
+        return null;
+    }
+    return stack;
+}
+function stackForAR(spend, leaf, inputIndex, bucket) {
+    const decoded = decodeAdminRequiredLeaf(leaf);
+    if (!decoded) {
+        return null;
+    }
+    const { adminId, bodyOrderIds, bodyKeys, k } = decoded;
+    const adminSig = bucket.get(adminId);
+    if (!adminSig) {
+        return null;
+    }
+    // Collect exactly k distinct-key body signatures in script order.
+    const slots = new Array(bodyOrderIds.length).fill(new Uint8Array());
+    const countedKeys = new Set();
+    let kept = 0;
+    for (let j = 0; j < bodyOrderIds.length; j++) {
+        const sig = bucket.get(bodyOrderIds[j]);
+        const keyHex = bytesToHex(bodyKeys[j]);
+        if (sig && !countedKeys.has(keyHex) && kept < k) {
+            slots[j] = sig;
+            countedKeys.add(keyHex);
+            kept += 1;
+        }
+    }
+    if (kept !== k) {
+        return null;
+    }
+    // witness: reverse(body) then admin
+    const stack = [...slots.slice().reverse(), adminSig];
+    if (!sigStackSolvesLeaf(spend, leaf, stack, inputIndex)) {
+        return null;
+    }
+    return stack;
+}
+/** Write `leaf`'s witness for input `inputIndex`: the signature stack, the leaf script and its control block. */
+export function finalizeWithWitness(tx, inputIndex, leaf, sigStack) {
+    const expectedSlots = signatureSlotCountForLeaf(leaf);
+    if (expectedSlots === null || sigStack.length !== expectedSlots) {
+        throw new Error("signature stack length mismatch");
+    }
+    const witness = [
+        ...sigStack,
+        leaf.script,
+        encodeCBFromStruct(leaf.controlBlockStruct),
+    ];
+    tx.updateInput(inputIndex, { finalScriptWitness: witness });
+    return witness;
+}
+function restrictBucketToApprovers(bucket, approverIds) {
+    if (!approverIds) {
+        return bucket;
+    }
+    return new Map([...bucket].filter(([signerId]) => approverIds.has(signerId)));
+}
+function stacksForEveryInput(opts) {
+    const { spend, leaf, perLeaf, vaultType, approverIds } = opts;
+    const stacks = [];
+    for (let inputIndex = 0; inputIndex < spend.tx.inputsLength; inputIndex++) {
+        const bucket = perLeaf.get(inputIndex);
+        if (!bucket) {
+            return null;
+        }
+        const eligibleBucket = restrictBucketToApprovers(bucket, approverIds);
+        const stack = vaultType === "ADMINS_REQUIRED"
+            ? stackForAR(spend, leaf, inputIndex, eligibleBucket)
+            : stackForNAR(spend, leaf, inputIndex, eligibleBucket);
+        if (!stack) {
+            return null;
+        }
+        stacks.push(stack);
+    }
+    return stacks;
+}
+/**
+ * Finalize every input with the first candidate leaf that the collected
+ * signatures solve on every input — the template's rules: k of the leaf's
+ * keys, and on an ADMINS_REQUIRED leaf its admin plus k − 1 of the rest.
+ * With a plan, only its leaf and its approvers' signatures count.
+ */
+export function tryFinalizeAny(spend, vaultType, plan) {
+    if (spend.tx.inputsLength === 0) {
+        return { finalized: false };
+    }
+    const scopedApprovers = plan ? new Set(plan.approverIds) : null;
+    const plannedLeafHash = plan?.leafHash.toLowerCase();
+    for (const leaf of spend.candidates) {
+        const key = bytesToHex(leaf.leafHash).toLowerCase();
+        if (plannedLeafHash && key !== plannedLeafHash) {
+            continue;
+        }
+        const perLeaf = spend.partials.get(key);
+        if (!perLeaf) {
+            continue;
+        }
+        // Finalization is all-or-nothing: one common leaf must solve every input.
+        const stacks = stacksForEveryInput({
+            spend,
+            leaf,
+            perLeaf,
+            vaultType,
+            approverIds: scopedApprovers,
+        });
+        if (!stacks) {
+            continue;
+        }
+        for (let inputIndex = 0; inputIndex < stacks.length; inputIndex++) {
+            finalizeWithWitness(spend.tx, inputIndex, leaf, stacks[inputIndex]);
+        }
+        return { finalized: true, usedLeaf: leaf };
+    }
+    return { finalized: false };
+}

package/dist/btc-policies/activation.d.ts

@@ -0,0 +1,76 @@
+import type { BtcPolicy } from "./policy.ts";
+/**
+ * What an admin signs to approve a BTC policy's activation, shared by the
+ * webapp (`apps/cofund/src/lib/bitcoin/policy-activation-data.ts` re-exports
+ * it) and the SDK, so the server's verifier and a local signer hash the same
+ * bytes.
+ *
+ * BTC policies are soft: no contract checks this. An approval is still a
+ * signature over exactly which policy was approved, verifiable later against
+ * the admin's registered key, rather than a row anyone with database access
+ * could write.
+ */
+export type BtcPolicyActivationData = {
+    /** hex sha256(companyName) — matches the other chains' clientId. */
+    clientId: string;
+    policyId: string;
+    authId: string;
+    policyType: string;
+    policyTitle: string;
+    /** Hex compressed signer keys, codepoint-ordered. */
+    policySignerKeys: string[];
+    policyThreshold: number;
+    /** Wrapper binding for tx-style policies; empty strings for transfers. */
+    txWrapper: string;
+    txFunc: string;
+    isTransaction: boolean;
+    maxAmount: string;
+    tokenIdentifier: string;
+    recipients: string[];
+};
+/**
+ * Length-prefixed encoding, then sha256. Every field is written as a 4-byte
+ * big-endian length followed by its UTF-8 bytes, so no choice of field values
+ * can produce the same byte string as a different choice — plain concatenation
+ * would let a title ending in a recipient address impersonate one.
+ */
+export declare function btcPolicyActivationDigest(data: BtcPolicyActivationData): Uint8Array;
+/**
+ * The string an approving admin signs: the payload digest, hex-encoded.
+ *
+ * Wrapped in the Bitcoin Signed Message envelope below rather than signed raw,
+ * because that is the only thing a Ledger's Bitcoin app will sign
+ * (`SignerBtc.signMessage`). Keeping the format signer-agnostic from the start
+ * means a device branch can be added without re-collecting approvals.
+ */
+export declare function btcPolicyActivationMessage(data: BtcPolicyActivationData): string;
+/** BIP-137 message hash: sha256d(prefix || varint(len) || message). */
+export declare function bitcoinSignedMessageHash(message: string): Uint8Array;
+/** BIP-137 message hash of the activation message: what the leaf key signs. */
+export declare function btcPolicyActivationSigningHash(data: BtcPolicyActivationData): Uint8Array;
+/** What an activation commits to beyond the policy. */
+export type BtcPolicyActivationContext = {
+    /** The cofund's name, as its members sign it: `clientId` is its sha256. */
+    company: string;
+};
+/**
+ * The activation of `policy`, as the app builds it for a Bitcoin transfer
+ * policy (`deriveBtcPolicyActivationData`,
+ * `apps/cofund/src/lib/bitcoin/policy-activation-data.ts:28-78`): its id as
+ * the `authId`, each signer's Cofund leaf key and the recipients in codepoint
+ * order, the cap, the token `BTC`, and no wrapper.
+ */
+export declare function activationDataFor(policy: BtcPolicy, context: BtcPolicyActivationContext): BtcPolicyActivationData;
+/**
+ * Whether `signature` (64-byte compact ECDSA, hex) is the Cofund leaf of
+ * `xpub` (an account xpub) signing the activation as a Bitcoin Signed Message:
+ * the app's verifier (`verifyCofundLeafMessage`,
+ * `apps/cofund/src/lib/bitcoin/signed-message.ts:47-83`). `btcMessageSigner`
+ * (`./keys`) and a Ledger's Bitcoin app sign it.
+ *
+ * One approval, checked. Whose approvals an activation takes, and how many,
+ * is the consumer's rule: the app takes its cofund's admins, one while it is
+ * onboarding and two after, every admin for a threshold-1 policy
+ * (`lib/policies/required-activation-signatures.ts`).
+ */
+export declare function verifyActivationSignature(data: BtcPolicyActivationData, signature: string, xpub: string): boolean;

package/dist/btc-policies/activation.js

@@ -0,0 +1,153 @@
+import { secp256k1 } from "@noble/curves/secp256k1.js";
+import { sha256 } from "@noble/hashes/sha2";
+import { bytesToHex, hexToBytes, utf8ToBytes } from "@noble/hashes/utils";
+import { compareCodepoint } from "../btc/vault/canonical-order.js";
+import { COFUND_LEAF_INDEX, deriveChildFromXpub } from "../btc/vault/xpub.js";
+const DOMAIN = "cofund-btc-policy-activation-v1";
+/**
+ * Length-prefixed encoding, then sha256. Every field is written as a 4-byte
+ * big-endian length followed by its UTF-8 bytes, so no choice of field values
+ * can produce the same byte string as a different choice — plain concatenation
+ * would let a title ending in a recipient address impersonate one.
+ */
+export function btcPolicyActivationDigest(data) {
+    const fields = [
+        DOMAIN,
+        data.clientId,
+        data.policyId,
+        data.authId,
+        data.policyType,
+        data.policyTitle,
+        String(data.policySignerKeys.length),
+        ...data.policySignerKeys,
+        String(data.policyThreshold),
+        data.txWrapper,
+        data.txFunc,
+        data.isTransaction ? "1" : "0",
+        data.maxAmount,
+        data.tokenIdentifier,
+        String(data.recipients.length),
+        ...data.recipients,
+    ];
+    const encoder = new TextEncoder();
+    const parts = fields.map((field) => {
+        const body = encoder.encode(field);
+        const out = new Uint8Array(4 + body.length);
+        new DataView(out.buffer).setUint32(0, body.length, false);
+        out.set(body, 4);
+        return out;
+    });
+    const total = parts.reduce((n, part) => n + part.length, 0);
+    const buf = new Uint8Array(total);
+    let offset = 0;
+    for (const part of parts) {
+        buf.set(part, offset);
+        offset += part.length;
+    }
+    return sha256(buf);
+}
+/**
+ * The string an approving admin signs: the payload digest, hex-encoded.
+ *
+ * Wrapped in the Bitcoin Signed Message envelope below rather than signed raw,
+ * because that is the only thing a Ledger's Bitcoin app will sign
+ * (`SignerBtc.signMessage`). Keeping the format signer-agnostic from the start
+ * means a device branch can be added without re-collecting approvals.
+ */
+export function btcPolicyActivationMessage(data) {
+    return bytesToHex(btcPolicyActivationDigest(data));
+}
+function varint(n) {
+    if (n < 0xfd) {
+        return Uint8Array.of(n);
+    }
+    if (n <= 0xff_ff) {
+        const out = new Uint8Array(3);
+        out[0] = 0xfd;
+        new DataView(out.buffer).setUint16(1, n, true);
+        return out;
+    }
+    const out = new Uint8Array(5);
+    out[0] = 0xfe;
+    new DataView(out.buffer).setUint32(1, n, true);
+    return out;
+}
+const BITCOIN_SIGNED_MESSAGE_PREFIX = new TextEncoder().encode("\u0018Bitcoin Signed Message:\n");
+/** BIP-137 message hash: sha256d(prefix || varint(len) || message). */
+export function bitcoinSignedMessageHash(message) {
+    const bytes = new TextEncoder().encode(message);
+    const len = varint(bytes.length);
+    const buf = new Uint8Array(BITCOIN_SIGNED_MESSAGE_PREFIX.length + len.length + bytes.length);
+    buf.set(BITCOIN_SIGNED_MESSAGE_PREFIX, 0);
+    buf.set(len, BITCOIN_SIGNED_MESSAGE_PREFIX.length);
+    buf.set(bytes, BITCOIN_SIGNED_MESSAGE_PREFIX.length + len.length);
+    return sha256(sha256(buf));
+}
+/** BIP-137 message hash of the activation message: what the leaf key signs. */
+export function btcPolicyActivationSigningHash(data) {
+    return bitcoinSignedMessageHash(btcPolicyActivationMessage(data));
+}
+const HEX_PREFIX = /^0x/;
+/** The Cofund leaf's compressed key, `m/86'/coin'/0'/0/376864517` below an account xpub. */
+const cofundLeafKey = (xpub) => deriveChildFromXpub(xpub, 0, COFUND_LEAF_INDEX).compressedPubKey;
+/**
+ * The activation of `policy`, as the app builds it for a Bitcoin transfer
+ * policy (`deriveBtcPolicyActivationData`,
+ * `apps/cofund/src/lib/bitcoin/policy-activation-data.ts:28-78`): its id as
+ * the `authId`, each signer's Cofund leaf key and the recipients in codepoint
+ * order, the cap, the token `BTC`, and no wrapper.
+ */
+export function activationDataFor(policy, context) {
+    return {
+        clientId: bytesToHex(sha256(utf8ToBytes(context.company))),
+        policyId: policy.id,
+        authId: policy.id,
+        policyType: policy.type,
+        policyTitle: policy.name,
+        policySignerKeys: policy.signers
+            .map((xpub) => bytesToHex(cofundLeafKey(xpub)))
+            .sort(compareCodepoint),
+        policyThreshold: policy.threshold,
+        txWrapper: "",
+        txFunc: "",
+        isTransaction: false,
+        maxAmount: policy.maxAmount,
+        tokenIdentifier: "BTC",
+        recipients: [...(policy.recipients ?? [])].sort(compareCodepoint),
+    };
+}
+/**
+ * Whether `signature` (64-byte compact ECDSA, hex) is the Cofund leaf of
+ * `xpub` (an account xpub) signing the activation as a Bitcoin Signed Message:
+ * the app's verifier (`verifyCofundLeafMessage`,
+ * `apps/cofund/src/lib/bitcoin/signed-message.ts:47-83`). `btcMessageSigner`
+ * (`./keys`) and a Ledger's Bitcoin app sign it.
+ *
+ * One approval, checked. Whose approvals an activation takes, and how many,
+ * is the consumer's rule: the app takes its cofund's admins, one while it is
+ * onboarding and two after, every admin for a threshold-1 policy
+ * (`lib/policies/required-activation-signatures.ts`).
+ */
+export function verifyActivationSignature(data, signature, xpub) {
+    let sig;
+    let key;
+    try {
+        sig = hexToBytes(signature.replace(HEX_PREFIX, ""));
+        key = cofundLeafKey(xpub);
+    }
+    catch {
+        return false;
+    }
+    if (sig.length !== 64) {
+        return false;
+    }
+    try {
+        // The BIP-137 hash is final: no second hash.
+        return secp256k1.verify(sig, btcPolicyActivationSigningHash(data), key, {
+            prehash: false,
+        });
+    }
+    catch {
+        return false;
+    }
+}

package/dist/btc-policies/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * `@getcofund/protocol/btc-policies`: Bitcoin spending policies, the soft
+ * rules a spend is checked against before it is signed, and what an admin
+ * signs to activate one. No script enforces them.
+ */
+export * from "./activation.ts";
+export * from "./policy.ts";

package/dist/btc-policies/index.js

@@ -0,0 +1,8 @@
+/**
+ * `@getcofund/protocol/btc-policies`: Bitcoin spending policies, the soft
+ * rules a spend is checked against before it is signed, and what an admin
+ * signs to activate one. No script enforces them.
+ */
+// biome-ignore lint/performance/noBarrelFile: the package's `./btc-policies` entry
+export * from "./activation.js";
+export * from "./policy.js";