getcofund 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cofund
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,201 @@
-# Temporary Holding Version
+# getcofund
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Client, local signers and the `cofund` CLI for the Cofund API (`/api/v1`).
+
+Two kinds of key:
+- **The API key is access.** Cofund issues it.
+- **The signing key is authority.** It is generated on your machine and never leaves it. The API receives only addresses, xpubs and signatures.
+
+## CLI
+
+Run it with `npx getcofund`, or install it globally (`npm i -g getcofund`) and run `cofund`. The `cofund` package on npm is unrelated, so never use `npx cofund`.
+
+```sh
+npx getcofund keys init
+# or
+npm i -g getcofund
+cofund keys init
+```
+
+With npx, put `--` first when passing flags, or npm takes flags such as `--help` and `--force` for itself: `npx -- getcofund invite accept --company "Acme"`.
+
+```sh
+cofund keys init [--force]
+cofund me
+cofund invite accept [--invite <id>] [--company <name>]
+cofund invite create --email <email> --first-name <name> --last-name <name> --position <title> [--admin] [--chains A,B] [--yes]
+cofund policies create --vault <id> --name <name> --signers <id|email,...> --threshold <n>
+  (--token <address|BTC> --max-amount <base units> | --wrapper <address>) [--type <PolicyType>] [--yes]
+cofund requests [list]
+cofund requests show <id>
+cofund requests sign <id> [--yes]
+cofund requests reject <id> [--yes]
+cofund stocks buy <SYMBOL> --spend <USDG> [--policy <id>]
+cofund webhooks [list]
+cofund webhooks add <url> [--events a,b]
+cofund webhooks remove <id>
+```
+
+Commands on a cofund take `--cofund <id>` when the key is a member of several.
+
+Environment:
+- `COFUND_API_URL`, `COFUND_API_KEY`: the API and your key.
+- `COFUND_KEYSTORE`: the keystore file. Default `~/.cofund/keystore.json`, mode 0600.
+- `COFUND_ROBINHOOD_RPC_URL`: the Robinhood Chain RPC `stocks buy` quotes from. Default the public one.
+
+Cofund runs on mainnet only. For local development, `COFUND_CHAINS` pins other chain ids and State addresses (JSON), and `COFUND_BTC_NETWORK=testnet` makes testnet BTC keys.
+
+`invite accept` checks the invite before signing anything:
+- it shows and pins the company;
+- the seat is yours;
+- it expires within 30 days.
+
+It rebuilds the EIP-712 message itself under the pinned domain, signs locally, and sends the BTC xpub with its ownership proof.
+
+`requests` lists what awaits you, as the app's Requests page shows it: transfers, calls and, for an admin, policy activations and admin invites (one per chain).
+
+`requests sign` signs nothing it has not read:
+- the domain is the pinned one, and `company` is the one pinned at `invite accept`;
+- the message is rebuilt from the request's fields (a call's `instructionsHash` is hashed here), and must match the server's;
+- a call goes through its verb's decoder: the StockSwap wrapper only, the instructions must re-encode from the decoded swap, and the allowances must be exactly its input;
+- a policy activation is rebuilt from its name, type, signers, threshold and bounds (token, cap, recipients, or wrapper); a BTC one is signed with the BTC key's Cofund leaf;
+- an admin invite must seat an admin, and its authorization must be open and at most 30 days out;
+- it shows the decoded request and asks, or takes `--yes`.
+
+What it takes from the server: which on-chain user id (EVM) or account xpub (BTC) belongs to which named policy signer, and an invite's `callerId` and `authId` (a wrong one only makes the chain refuse it). `approve` receives each signer with its id or xpub, so a script holding its own roster can check the pairing.
+
+An admin creates policies and invites with keys of their own:
+- `policies create` builds the activation from the flags: the signers by member id or email (an EVM activation names their `onchainId`, a BTC one their account xpubs), the threshold, and the token and cap per transfer in base units or the wrapper (function `entry`). A transfer policy is `Operational_Expense` and a call policy `Treasury_Management` unless `--type` says otherwise. It signs under the pinned domain and company, with the BTC key's Cofund leaf on a Bitcoin vault. The policy activates at once when one admin may activate it; otherwise it awaits the other admins as a `policy` request.
+- `invite create` asks which user id the email's seat registers (an existing account keeps its own), signs `InviteUser` on each of the cofund's EVM vault chains (or `--chains`), 29 days out, and sends the invite. A member seat is claimable at once; an admin seat awaits the other admins' co-signatures where the chain asks for them, one `invite` request per chain.
+- Both show what they will sign and ask, or take `--yes`.
+
+`stocks buy` quotes the pool, sets the minimum output 1% under the quote, signs the swap and proposes it on the cofund's Stocks policy. The other signers approve it in the app or with `requests sign`.
+
+## SDK
+
+```js
+import {
+  btcMessageSigner,
+  CofundClient,
+  evmWallet,
+  readKeystore,
+  signRequest,
+} from "getcofund";
+
+const api = new CofundClient({ baseUrl, apiKey });
+const me = await api.me();
+
+// Sign what awaits you and matches your intent; refuse the rest unsigned.
+const keystore = readKeystore(path);
+for (const request of await api.requests(cofundId)) {
+  const signature = await signRequest(
+    request,
+    {
+      company: keystore.cofunds[cofundId].company,
+      approve: (decoded) => decoded.kind === "transfer" && decoded.amount === "1000000",
+    },
+    pins,
+    { evm: evmWallet(keystore), btc: btcMessageSigner(keystore) },
+  ).catch(() => null); // not approved, or not what its fields say
+  if (signature) {
+    await api.signRequest(cofundId, request.id, signature);
+  }
+}
+```
+
+`proposeTransfer` and `proposeCall` take an id the caller picks (`id`, `authId`); a retry with the same id returns the same request, so the client retries them on a lost response. `signTransferProposal` and `signCallProposal` sign the proposer's own intent.
+
+An admin's writes work the same way: `signPolicyCreation` and `signInviteCreation` build the activation or each chain's `InviteUser` from your inputs and sign it locally, and `createPolicy` and `createInvite` send it under the id you picked.
+
+```js
+import { randomUUID } from "node:crypto";
+import { signInviteCreation, signPolicyCreation } from "getcofund";
+
+const company = keystore.cofunds[cofundId].company;
+const signers = { evm: evmWallet(keystore), btc: btcMessageSigner(keystore) };
+const [vault] = await api.vaults(cofundId);
+const roster = await api.members(cofundId);
+
+const policy = await signPolicyCreation(
+  {
+    id: randomUUID(),
+    vault,
+    name: "Payouts",
+    type: "Operational_Expense",
+    signers: roster.filter((m) => m.isAdmin),
+    threshold: 2,
+    token: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+    maxAmount: "1000000000", // 1,000 USDC per transfer
+  },
+  company,
+  pins,
+  signers,
+);
+await api.createPolicy(cofundId, policy); // AWAITING_SIGNATURES, or active at once
+
+const id = randomUUID();
+const { userId } = await api.inviteUserId(cofundId, "nia@example.com");
+const invite = await signInviteCreation(
+  {
+    id,
+    callerId: me.id,
+    userId: userId ?? id,
+    email: "nia@example.com",
+    firstName: "Nia",
+    lastName: "Okafor",
+    position: "Treasurer",
+    isAdmin: false,
+    chains: ["ETHEREUM", "ROBINHOOD"],
+  },
+  company,
+  pins,
+  signers.evm,
+);
+await api.createInvite(cofundId, invite);
+```
+
+## Webhooks
+
+`cofund webhooks add https://bot.example.com/cofund` subscribes an endpoint for your key's agent, to every event or those named with `--events`, and prints its signing secret once. The URL must be https, on a host that resolves only to public addresses.
+
+| Event | When |
+|---|---|
+| `request.signature_needed` | A transfer, call, policy activation or admin invite awaits your signature |
+| `request.executed` | It went through: executed on chain; a Bitcoin policy once approved; an admin invite's chain row once its last co-signature lands |
+| `request.failed` | It failed on chain; or its simulation reverted and nothing was sent, and it stays open; or it expired unsent (a swap's quote, an admin invite). `reason` says why |
+| `request.rejected` | An admin rejected it |
+| `invite.received` | You were invited to a cofund (`inviteId`) |
+
+The body is `{id, type, createdAt, cofundId}` and, by type: every `request.*` event its `requestId` and `kind` (`transfer`, `call`, `policy` or `invite`), `request.failed` an optional `reason`, `invite.received` its `inviteId`. Never amounts or addresses: fetch the request with `api.request(cofundId, requestId)` and check it as `signRequest` does. `WebhookEventSchema` parses it, narrowed by `type`. Delivery is at least once and in no particular order. Answer 2xx within 10 seconds; anything else is retried at 1m, 5m, 30m, 2h, 6h and 24h, and three days of failures disable the subscription (your key's owner is emailed).
+
+```js
+import { createServer } from "node:http";
+import { verifyWebhookSignature, WebhookEventSchema } from "getcofund";
+
+const seen = new Set(); // use your database in production
+
+createServer((req, res) => {
+  let rawBody = "";
+  req.setEncoding("utf8");
+  req.on("data", (chunk) => (rawBody += chunk));
+  req.on("end", async () => {
+    // The exact bytes received, before any JSON parsing; refuses a stale timestamp.
+    if (!verifyWebhookSignature(req.headers["cofund-signature"], rawBody, process.env.COFUND_WEBHOOK_SECRET)) {
+      res.writeHead(401).end();
+      return;
+    }
+    const event = WebhookEventSchema.parse(JSON.parse(rawBody));
+    res.writeHead(200).end(); // acknowledge first, then work
+    if (seen.has(event.id)) return; // a retry of one already handled
+    seen.add(event.id);
+    if (event.type === "request.signature_needed") {
+      const request = await api.request(event.cofundId, event.requestId);
+      // ...decide, then sign it as in the SDK example above
+    } else if (event.type === "invite.received") {
+      // ...accept event.inviteId with `cofund invite accept --invite <id>`
+    }
+  });
+}).listen(8080);
+```
+
+Node 20 or later, ESM.