@getcofund/cli 0.0.0 → 0.1.0

package/dist/signature-file.js

@@ -0,0 +1,214 @@
+import { readFileSync, writeFileSync } from "node:fs";
+import { Address as AddressSchema, COMPLETE_ONBOARDING_TYPES, Hex as HexSchema, INVITE_USER_TYPES, POLICY_DEACTIVATION_TYPES, REMOVE_USER_TYPES, ROTATE_USER_TYPES, sameAddress, TRANSACTION_POLICY_ACTIVATION_TYPES, TRANSACTION_TYPES, TRANSFER_POLICY_ACTIVATION_TYPES, TRANSFER_TYPES, tryRecover, typedData, typedDataDigest, } from "@getcofund/protocol/evm";
+import { keccak256 } from "viem";
+import { z } from "zod";
+/**
+ * A signature as co-signers pass it around: a JSON file holding the message,
+ * its EIP-712 type, the domain it was signed under, the signer's address and
+ * the signature (and a `Transaction`'s instructions, which it signs by hash).
+ * A file is checked when it is loaded: the message is its type's shape, the
+ * domain is the deployment's, the signature recovers to the address the file
+ * claims, and every file a command takes is for the same call. The type's
+ * fields are always this package's, never the file's.
+ */
+export const SIGNATURE_TYPES = {
+    InviteUser: INVITE_USER_TYPES,
+    RemoveUser: REMOVE_USER_TYPES,
+    RotateUser: ROTATE_USER_TYPES,
+    CompleteOnboarding: COMPLETE_ONBOARDING_TYPES,
+    TransferPolicyActivation: TRANSFER_POLICY_ACTIVATION_TYPES,
+    TransactionPolicyActivation: TRANSACTION_POLICY_ACTIVATION_TYPES,
+    PolicyDeactivation: POLICY_DEACTIVATION_TYPES,
+    Transfer: TRANSFER_TYPES,
+    Transaction: TRANSACTION_TYPES,
+};
+const TYPE_NAMES = Object.keys(SIGNATURE_TYPES);
+const FileSchema = z.strictObject({
+    version: z.literal(1),
+    type: z.enum(TYPE_NAMES),
+    domain: z.strictObject({
+        name: z.string(),
+        version: z.string(),
+        chainId: z.number().int().positive(),
+        verifyingContract: AddressSchema,
+    }),
+    message: z.record(z.string(), z.unknown()),
+    signer: AddressSchema,
+    signature: HexSchema,
+    instructions: HexSchema.optional(),
+});
+const UINT256 = /^\d{1,78}$/;
+const BYTES32 = /^0x[0-9a-fA-F]{64}$/;
+const ARRAY = /\[\]$/;
+/** Why `value` is not an EIP-712 `type` of `types`, or null when it is. */
+function fieldProblem(type, value, types) {
+    if (ARRAY.test(type)) {
+        if (!Array.isArray(value)) {
+            return "not a list";
+        }
+        for (const item of value) {
+            const problem = fieldProblem(type.replace(ARRAY, ""), item, types);
+            if (problem) {
+                return problem;
+            }
+        }
+        return null;
+    }
+    const struct = types[type];
+    if (struct) {
+        return structProblem(struct, value, types);
+    }
+    const ok = {
+        string: typeof value === "string",
+        bool: typeof value === "boolean",
+        address: AddressSchema.safeParse(value).success,
+        uint256: typeof value === "string" &&
+            UINT256.test(value) &&
+            BigInt(value) < 2n ** 256n,
+        bytes32: typeof value === "string" && BYTES32.test(value),
+    }[type];
+    return ok ? null : `not a ${type}`;
+}
+/** Why `value` is not exactly the struct `fields` (no field missing, none extra), or null. */
+function structProblem(fields, value, types) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return "not an object";
+    }
+    const names = new Set(fields.map(({ name }) => name));
+    const extra = Object.keys(value).find((key) => !names.has(key));
+    if (extra) {
+        return `${extra} is no field of it`;
+    }
+    for (const { name, type } of fields) {
+        const problem = fieldProblem(type, value[name], types);
+        if (problem) {
+            return `${name} is ${problem}`;
+        }
+    }
+    return null;
+}
+/** The digest of `type`'s `message` under the deployment's domain: what a key signs. */
+export function digestOf(deployment, type, message) {
+    return typedDataDigest(typedData(deployment.eip712Domain, SIGNATURE_TYPES[type], message));
+}
+/**
+ * `signer`'s signature over `type`'s `message` under the deployment's domain,
+ * as a file's contents (a `Transaction`'s with its `instructions`).
+ */
+export async function signMessage(signer, deployment, { type, message, instructions, }) {
+    const signature = await signer.signTypedData(typedData(deployment.eip712Domain, SIGNATURE_TYPES[type], message));
+    return {
+        version: 1,
+        type,
+        domain: deployment.eip712Domain,
+        message: message,
+        signer: signer.address,
+        signature,
+        ...(instructions !== undefined && { instructions }),
+    };
+}
+/** Write a signature file; an existing file is never overwritten. */
+export function writeSignatureFile(path, file) {
+    try {
+        writeFileSync(path, `${JSON.stringify(file, null, 2)}\n`, { flag: "wx" });
+    }
+    catch (error) {
+        if (error.code === "EEXIST") {
+            throw new Error(`${path} exists; pass another --out`);
+        }
+        throw error;
+    }
+}
+/** The file at `path` as a signature file's shape, or why it is not one. */
+function readFile(path) {
+    let json;
+    try {
+        json = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch (error) {
+        throw new Error(`${path}: not a signature file (${error instanceof Error ? error.message : String(error)})`);
+    }
+    const parsed = FileSchema.safeParse(json);
+    if (!parsed.success) {
+        const issue = parsed.error.issues[0];
+        throw new Error(`${path}: not a signature file (${issue.path.join(".") || "file"}: ${issue.message})`);
+    }
+    return parsed.data;
+}
+/** The file's domain must be the deployment's. */
+function checkDomain(path, { domain }, deployment) {
+    const mine = deployment.eip712Domain;
+    if (domain.name !== mine.name ||
+        domain.version !== mine.version ||
+        domain.chainId !== mine.chainId ||
+        !sameAddress(domain.verifyingContract, mine.verifyingContract)) {
+        throw new Error(`${path} was signed under another domain ("${domain.name}" ${domain.version} on chain ${domain.chainId} at ${domain.verifyingContract}), not this deployment's ("${mine.name}" ${mine.version} on chain ${mine.chainId} at ${mine.verifyingContract})`);
+    }
+}
+/** A `Transaction` carries the instructions it signs by hash; no other file carries any. */
+function checkInstructions(path, file) {
+    if (file.type !== "Transaction") {
+        if (file.instructions !== undefined) {
+            throw new Error(`${path}: only a Transaction file carries instructions`);
+        }
+        return;
+    }
+    if (file.instructions === undefined) {
+        throw new Error(`${path}: a Transaction file carries its instructions`);
+    }
+    if (keccak256(file.instructions) !==
+        String(file.message.instructionsHash).toLowerCase()) {
+        throw new Error(`${path}: its instructions are not the ones signed (their keccak256 is not the message's instructionsHash)`);
+    }
+}
+/** One file read and checked on its own: its type, its shape, its domain, its signer. */
+async function loadOne(path, deployment, expected) {
+    const file = readFile(path);
+    if (!expected.includes(file.type)) {
+        throw new Error(`${path} signs a ${file.type}; this command takes ${expected.join(" or ")}: a file for another call`);
+    }
+    const types = SIGNATURE_TYPES[file.type];
+    const problem = structProblem(types[file.type], file.message, types);
+    if (problem) {
+        throw new Error(`${path}: not a ${file.type} message: ${problem}`);
+    }
+    checkDomain(path, file, deployment);
+    checkInstructions(path, file);
+    const digest = digestOf(deployment, file.type, file.message);
+    const recovered = await tryRecover(digest, file.signature);
+    if ("failure" in recovered) {
+        throw new Error(`${path}: the signature recovers to no address (${recovered.failure})`);
+    }
+    if (!sameAddress(recovered.signer, file.signer)) {
+        throw new Error(`${path}: the signature is ${recovered.signer}'s, not ${file.signer}'s as the file claims`);
+    }
+    return {
+        path,
+        type: file.type,
+        message: file.message,
+        signer: recovered.signer,
+        signature: file.signature,
+        ...(file.instructions !== undefined && {
+            instructions: file.instructions,
+        }),
+        digest,
+    };
+}
+/**
+ * Signature files for one call, each checked (`loadOne`), and all over the
+ * same message: a file for another call, or of a type the command does not
+ * take, is refused.
+ */
+export async function loadSignatures(paths, deployment, expected) {
+    const loaded = [];
+    for (const path of paths) {
+        const signed = await loadOne(path, deployment, expected);
+        const [first] = loaded;
+        if (first &&
+            (signed.type !== first.type || signed.digest !== first.digest)) {
+            throw new Error(`${path} signs another ${signed.type} than ${first.path}: a file for another call`);
+        }
+        loaded.push(signed);
+    }
+    return loaded;
+}

package/dist/usage.js

@@ -0,0 +1,62 @@
+export const USAGE = `usage: cofund-chain <command> [flags]
+
+keys
+  keys init [--force]
+  keys show
+
+a cofund on an EVM chain
+  found --name <name> [--company <company>] [--tier <tier>]
+  show
+  members
+  policies show <id>
+  invite --user-id <id> --position <title> [--admin] --out <file>
+  invite cosign <file>... --out <file>
+  join <file>...
+  members remove <user-id> [<file>...] [--out <file>]
+  members rotate [<file>...] [--new-address <address>] [--user-id <id>]
+    [--out <file>]
+  policies sign (--name <title> --signers <user-id,...> --threshold <n>
+    (--token <address> --max-amount <amount> [--recipients <address,...>]
+    | --wrapper <address>) [--type <policy type>] | <file>...) --out <file>
+  policies activate <file>...
+  policies deactivate <id> [<file>] [--out <file>]
+  transfers sign (--policy <id> --to <address> --amount <amount> | <file>...)
+    --out <file>
+  transfers send <file>...
+  calls sign (--policy <id> --instructions <hex>
+    [--allowance <token>:<amount>]... | <file>...) --out <file>
+  calls send <file>...
+  calls simulate <file>...
+  onboarding complete [<file>] [--out <file>]
+
+a Bitcoin vault
+  btc vault create --xpubs <xpub,...> --threshold <k>
+    [--type ALL|ADMINS_INCLUDED|ADMINS_REQUIRED] [--admins <xpub,...>]
+    --out <file>
+  btc spend build --vault <file> --to <address> --amount <sats>
+    [--fee-rate <sat/vB>] --out <file>
+  btc spend sign <psbt> --vault <file> --to <address> --amount <sats>
+    --out <file>
+  btc spend combine <psbt>... --out <file>
+  btc spend finalize <psbt> --vault <file> --out <file>
+  btc spend broadcast <hex or file>
+
+flags
+  --keystore <file>        the keystore (COFUND_KEYSTORE; ~/.cofund/keystore.json)
+  --deployment <file>      a deployments/<chainId>.json (COFUND_DEPLOYMENT)
+  --rpc <url>              the EVM chain's RPC (COFUND_RPC_URL)
+  --esplora <url>          an Esplora API for Bitcoin (COFUND_ESPLORA_URL)
+  --via direct|guard       direct (the default): the keystore's EVM key sends
+                           and pays gas; guard: relayed by the deployment's
+                           guard, sent from --sponsor-key-file
+  --sponsor-key-file <f>   a sponsor's key: a hex private key, or a keystore
+  --company <company>      the cofund, when the keystore pins several
+  --yes                    act without asking
+
+A signature is a JSON file; a command that sends takes every signer's file.
+On EVM, amounts (--amount, --max-amount, --allowance) are whole tokens,
+converted with the token's decimals; previews show base units too. On
+Bitcoin, --amount is sats.
+A PSBT is a base64 file; a signer states what it expects the spend to pay
+(--to, --amount) and signs nothing else. COFUND_BTC_NETWORK (mainnet, testnet
+or regtest) picks the network of new keys and vaults; regtest uses testnet keys.`;

package/package.json

@@ -1,5 +1,43 @@
 {
   "name": "@getcofund/cli",
-  "version": "0.0.0",
-  "description": "Placeholder; the first release is published from Strata-Labs/cofund-webapp"
-}
+  "version": "0.1.0",
+  "description": "cofund-chain: the Cofund protocol from the command line, on the chain alone. Found a cofund, seat members, activate policies, sign and send transfers, and spend Bitcoin vaults through PSBTs, with local keys and signature files.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Strata-Labs/cofund-webapp.git",
+    "directory": "packages/cli"
+  },
+  "type": "module",
+  "bin": {
+    "cofund-chain": "./dist/cli.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "viem": "^2.56.0",
+    "zod": "^4.3.6",
+    "@getcofund/protocol": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "24.10.13",
+    "typescript": "5.9.3",
+    "vitest": "^4.1.5"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p test",
+    "test": "vitest run",
+    "smoke": "bash scripts/smoke-pack.sh",
+    "local-up": "node scripts/local.ts up",
+    "local-down": "node scripts/local.ts down"
+  }
+}