@ftptech/canton-agent-wallet 0.1.0

package/dist/cli.js

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+/**
+ * canton-agent-wallet CLI — the surface an agent (or its human) drives.
+ *
+ *   create  [--relay-url <url>]  generate + onboard a self-custody wallet (idempotent)
+ *   address                      print the party id (fund this)
+ *   balance                      print CC balance
+ *   claim                        accept incoming transfers (e.g. the initial funding)
+ *   pay [--relay-url <url>] <url> fetch a URL, auto-paying any x402 402 challenge
+ *   withdraw --to <p>            send CC back out (--amount <cc> for a partial amount)
+ *   export                       print the private key (backup; guard it)
+ *
+ * The relay (facilitator) URL is REQUIRED for the commands that talk to a
+ * relay (`create`, `pay`). There is intentionally no built-in default — a
+ * wrong/stale default would silently send an agent's payments to a dead host.
+ * Supply it via `--relay-url <url>` or the `CANTON_AGENT_RELAY_URL` env var.
+ * The current FTP facilitator is `http://46.225.91.251:4022` (plain HTTP, by
+ * IP — a TLS domain is planned but not yet live). `address`, `balance`,
+ * `claim`, `withdraw` and `export` reuse the relay stored in the wallet at
+ * `create` time and do not need the flag.
+ *
+ * Config via env: CANTON_AGENT_RELAY_URL, CANTON_AGENT_NETWORK,
+ * CANTON_AGENT_API_KEY. Wallet lives at ~/.canton-agent/wallet.json (0600).
+ */
+/* eslint-disable no-console -- CLI entrypoint: stdout is its result channel */
+import { ensureWallet } from "./onboard.js";
+import { loadWallet } from "./store.js";
+import { makePayingFetch } from "./pay.js";
+import { RelayClient } from "./relay-client.js";
+import { claimAll } from "./tx.js";
+import { withdraw } from "./withdraw.js";
+import { flag, positionals, resolveNetwork, resolveRelayUrl, MISSING_RELAY_HELP, } from "./cli-args.js";
+const API_KEY = process.env.CANTON_AGENT_API_KEY;
+function fail(msg) {
+    console.error(msg);
+    process.exit(1);
+}
+/** Resolve the relay URL or fail fast (never returns undefined). */
+function requireRelay(args) {
+    return resolveRelayUrl(args) ?? fail(MISSING_RELAY_HELP);
+}
+async function main() {
+    const [cmd, ...args] = process.argv.slice(2);
+    switch (cmd) {
+        case "create": {
+            const relayUrl = requireRelay(args);
+            const w = await ensureWallet({
+                relayUrl,
+                network: resolveNetwork(args),
+                apiKey: API_KEY,
+            });
+            console.log(`wallet ready (${w.network})\n` +
+                `  party:   ${w.party}\n` +
+                `  fund me: send CC to that party id, then run: canton-agent-wallet claim\n` +
+                `  keyfile: ~/.canton-agent/wallet.json  <- this IS your wallet; back it up`);
+            break;
+        }
+        case "address": {
+            const w = loadWallet();
+            if (!w)
+                return fail("no wallet yet — run: canton-agent-wallet create");
+            console.log(w.party);
+            break;
+        }
+        case "balance": {
+            const w = loadWallet();
+            if (!w)
+                return fail("no wallet yet — run: canton-agent-wallet create");
+            const b = await new RelayClient({ relayUrl: w.relayUrl, apiKey: API_KEY }).balance(w.party);
+            console.log(`${b.cc} CC  (${b.amulet} holding${b.amulet === 1 ? "" : "s"})`);
+            break;
+        }
+        case "claim": {
+            const w = loadWallet();
+            if (!w)
+                return fail("no wallet yet — run: canton-agent-wallet create");
+            const r = await claimAll(new RelayClient({ relayUrl: w.relayUrl, apiKey: API_KEY }), w);
+            console.log(r.claimed ? `claimed ${r.claimed} incoming transfer(s)` : "nothing to claim");
+            break;
+        }
+        case "pay": {
+            const url = positionals(args)[0];
+            if (!url)
+                return fail("usage: canton-agent-wallet pay [--relay-url <url>] <url>");
+            const relayUrl = requireRelay(args);
+            const f = await makePayingFetch({
+                relayUrl,
+                network: resolveNetwork(args),
+                apiKey: API_KEY,
+            });
+            const res = await f(url);
+            console.log(`${res.status} ${res.statusText}`);
+            console.log(await res.text());
+            break;
+        }
+        case "withdraw": {
+            const to = flag(args, "--to");
+            if (!to)
+                return fail("usage: canton-agent-wallet withdraw --to <party> [--amount <cc>]");
+            const amount = flag(args, "--amount");
+            const r = await withdraw({ to, ...(amount ? { amount } : {}), apiKey: API_KEY });
+            console.log(`withdrew ${r.amount} CC to ${to}\n  updateId: ${r.updateId}`);
+            break;
+        }
+        case "export": {
+            const w = loadWallet();
+            if (!w)
+                return fail("no wallet yet — run: canton-agent-wallet create");
+            console.error("!  PRIVATE KEY below — anyone who has it controls your funds. Store it securely.\n");
+            console.log(w.privateKeyPkcs8Pem);
+            break;
+        }
+        default:
+            console.error("canton-agent-wallet: create | address | balance | claim | pay <url> | withdraw --to <party> | export\n" +
+                "  relay required for create/pay: --relay-url <url> or CANTON_AGENT_RELAY_URL");
+            process.exit(cmd ? 1 : 0);
+    }
+}
+main().catch((e) => {
+    console.error("error:", e instanceof Error ? e.message : String(e));
+    process.exit(1);
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,+EAA+E;AAC/E,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAC3C,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACnC,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EACL,IAAI,EACJ,WAAW,EACX,cAAc,EACd,eAAe,EACf,kBAAkB,GACnB,MAAM,eAAe,CAAC;AAEvB,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,oBAAoB,CAAC;AAEjD,SAAS,IAAI,CAAC,GAAW;IACvB,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACnB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED,oEAAoE;AACpE,SAAS,YAAY,CAAC,IAAc;IAClC,OAAO,eAAe,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,kBAAkB,CAAC,CAAC;AAC3D,CAAC;AAED,KAAK,UAAU,IAAI;IACjB,MAAM,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAC7C,QAAQ,GAAG,EAAE,CAAC;QACZ,KAAK,QAAQ,CAAC,CAAC,CAAC;YACd,MAAM,QAAQ,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;YACpC,MAAM,CAAC,GAAG,MAAM,YAAY,CAAC;gBAC3B,QAAQ;gBACR,OAAO,EAAE,cAAc,CAAC,IAAI,CAAC;gBAC7B,MAAM,EAAE,OAAO;aAChB,CAAC,CAAC;YACH,OAAO,CAAC,GAAG,CACT,iBAAiB,CAAC,CAAC,OAAO,KAAK;gBAC7B,cAAc,CAAC,CAAC,KAAK,IAAI;gBACzB,4EAA4E;gBAC5E,4EAA4E,CAC/E,CAAC;YACF,MAAM;QACR,CAAC;QACD,KAAK,SAAS,CAAC,CAAC,CAAC;YACf,MAAM,CAAC,GAAG,UAAU,EAAE,CAAC;YACvB,IAAI,CAAC,CAAC;gBAAE,OAAO,IAAI,CAAC,iDAAiD,CAAC,CAAC;YACvE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;YACrB,MAAM;QACR,CAAC;QACD,KAAK,SAAS,CAAC,CAAC,CAAC;YACf,MAAM,CAAC,GAAG,UAAU,EAAE,CAAC;YACvB,IAAI,CAAC,CAAC;gBAAE,OAAO,IAAI,CAAC,iDAAiD,CAAC,CAAC;YACvE,MAAM,CAAC,GAAG,MAAM,IAAI,WAAW,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;YAC5F,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC,MAAM,WAAW,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC;YAC7E,MAAM;QACR,CAAC;QACD,KAAK,OAAO,CAAC,CAAC,CAAC;YACb,MAAM,CAAC,GAAG,UAAU,EAAE,CAAC;YACvB,IAAI,CAAC,CAAC;gBAAE,OAAO,IAAI,CAAC,iDAAiD,CAAC,CAAC;YACvE,MAAM,CAAC,GAAG,MAAM,QAAQ,CAAC,IAAI,WAAW,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;YACxF,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,OAAO,uBAAuB,CAAC,CAAC,CAAC,kBAAkB,CAAC,CAAC;YAC1F,MAAM;QACR,CAAC;QACD,KAAK,KAAK,CAAC,CAAC,CAAC;YACX,MAAM,GAAG,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;YACjC,IAAI,CAAC,GAAG;gBACN,OAAO,IAAI,CAAC,0DAA0D,CAAC,CAAC;YAC1E,MAAM,QAAQ,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;YACpC,MAAM,CAAC,GAAG,MAAM,eAAe,CAAC;gBAC9B,QAAQ;gBACR,OAAO,EAAE,cAAc,CAAC,IAAI,CAAC;gBAC7B,MAAM,EAAE,OAAO;aAChB,CAAC,CAAC;YACH,MAAM,GAAG,GAAG,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC;YACzB,OAAO,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,UAAU,EAAE,CAAC,CAAC;YAC/C,OAAO,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC;YAC9B,MAAM;QACR,CAAC;QACD,KAAK,UAAU,CAAC,CAAC,CAAC;YAChB,MAAM,EAAE,GAAG,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;YAC9B,IAAI,CAAC,EAAE;gBAAE,OAAO,IAAI,CAAC,kEAAkE,CAAC,CAAC;YACzF,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;YACtC,MAAM,CAAC,GAAG,MAAM,QAAQ,CAAC,EAAE,EAAE,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC;YACjF,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC,MAAM,UAAU,EAAE,iBAAiB,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC;YAC3E,MAAM;QACR,CAAC;QACD,KAAK,QAAQ,CAAC,CAAC,CAAC;YACd,MAAM,CAAC,GAAG,UAAU,EAAE,CAAC;YACvB,IAAI,CAAC,CAAC;gBAAE,OAAO,IAAI,CAAC,iDAAiD,CAAC,CAAC;YACvE,OAAO,CAAC,KAAK,CACX,oFAAoF,CACrF,CAAC;YACF,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,kBAAkB,CAAC,CAAC;YAClC,MAAM;QACR,CAAC;QACD;YACE,OAAO,CAAC,KAAK,CACX,wGAAwG;gBACtG,8EAA8E,CACjF,CAAC;YACF,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9B,CAAC;AACH,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,CAAU,EAAE,EAAE;IAC1B,OAAO,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;IACpE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/hash-binding.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Resolve how the agent binds the relay-returned prepared-transaction hash to
+ * the bytes it validated, for the CLI / autopay paths (`makeRelaySigner`,
+ * `withdraw`, `claimAll`).
+ *
+ * SECURITY DEFAULT: REAL cryptographic binding. With no configuration, the
+ * default now recomputes the prepared-transaction hash from the bytes the agent
+ * validated, EXACTLY as the Canton participant does on `execute`
+ * (HASHING_SCHEME_VERSION_V2 via `@canton-network/core-tx-visualizer`), and
+ * `assertHashBinding` signs the RECOMPUTED value only if it equals the relay
+ * `hash` — refusing otherwise. This satisfies the Canton Ledger API requirement:
+ * "clients MUST recompute the hash from the raw transaction if the preparing
+ * participant is not trusted." The previous fail-closed `{}` default existed
+ * only because no conformant recompute was wired; it now is.
+ *
+ * Escape hatch, off by default:
+ *   CANTON_AGENT_TRUST_RELAY_HASH=1 accepts the relay's hash WITHOUT
+ *   recomputation. This re-opens the blind-signing risk and is only acceptable
+ *   when a human reviews each transfer or the relay is fully trusted. It is the
+ *   documented last-resort fallback (e.g. if a future participant hashing-scheme
+ *   change outpaces the pinned library and the operator must sign before the
+ *   library catches up). Never assumed; must be explicitly set.
+ *
+ * The recompute is conformance-tested against captured live participant vectors
+ * (`canton-hash.conformance.test.ts`); a wrong recompute fails honest transfers
+ * CLOSED (refused) rather than mis-binding — it can never silently accept a
+ * relay-chosen hash.
+ */
+import type { HashBindingOptions } from "./verify-prepared.js";
+/** The env var an operator sets to accept the relay hash without recomputing. */
+export declare const TRUST_RELAY_HASH_ENV = "CANTON_AGENT_TRUST_RELAY_HASH";
+/**
+ * Build the default `HashBindingOptions` for the CLI/autopay paths from the
+ * environment. Returns `{ trustRelayHash: true }` ONLY when the operator has
+ * explicitly opted into the dangerous escape hatch; otherwise returns the REAL
+ * binding `{ recomputeHash }` (the conformant V2 recompute), which makes
+ * `assertHashBinding` sign the recomputed hash and refuse on any mismatch.
+ */
+export declare function resolveHashBinding(env?: NodeJS.ProcessEnv): HashBindingOptions;
+//# sourceMappingURL=hash-binding.d.ts.map

package/dist/hash-binding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash-binding.d.ts","sourceRoot":"","sources":["../src/hash-binding.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAG/D,iFAAiF;AACjF,eAAO,MAAM,oBAAoB,kCAAkC,CAAC;AAOpE;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,kBAAkB,CAGpB"}

package/dist/hash-binding.js

@@ -0,0 +1,20 @@
+import { recomputeHash } from "./canton-hash.js";
+/** The env var an operator sets to accept the relay hash without recomputing. */
+export const TRUST_RELAY_HASH_ENV = "CANTON_AGENT_TRUST_RELAY_HASH";
+function envSaysTrustRelayHash(env) {
+    const v = (env[TRUST_RELAY_HASH_ENV] ?? "").trim().toLowerCase();
+    return v === "1" || v === "true" || v === "yes";
+}
+/**
+ * Build the default `HashBindingOptions` for the CLI/autopay paths from the
+ * environment. Returns `{ trustRelayHash: true }` ONLY when the operator has
+ * explicitly opted into the dangerous escape hatch; otherwise returns the REAL
+ * binding `{ recomputeHash }` (the conformant V2 recompute), which makes
+ * `assertHashBinding` sign the recomputed hash and refuse on any mismatch.
+ */
+export function resolveHashBinding(env = process.env) {
+    if (envSaysTrustRelayHash(env))
+        return { trustRelayHash: true };
+    return { recomputeHash };
+}
+//# sourceMappingURL=hash-binding.js.map

package/dist/hash-binding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash-binding.js","sourceRoot":"","sources":["../src/hash-binding.ts"],"names":[],"mappings":"AA6BA,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEjD,iFAAiF;AACjF,MAAM,CAAC,MAAM,oBAAoB,GAAG,+BAA+B,CAAC;AAEpE,SAAS,qBAAqB,CAAC,GAAsB;IACnD,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,oBAAoB,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACjE,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,MAAM,IAAI,CAAC,KAAK,KAAK,CAAC;AAClD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAChC,MAAyB,OAAO,CAAC,GAAG;IAEpC,IAAI,qBAAqB,CAAC,GAAG,CAAC;QAAE,OAAO,EAAE,cAAc,EAAE,IAAI,EAAE,CAAC;IAChE,OAAO,EAAE,aAAa,EAAE,CAAC;AAC3B,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export * from "./keys.js";
+export * from "./store.js";
+export * from "./relay-client.js";
+export * from "./onboard.js";
+export * from "./relay-signer.js";
+export * from "./tx.js";
+export * from "./withdraw.js";
+export * from "./pay.js";
+export * from "./hash-binding.js";
+export * from "./canton-hash.js";
+export * from "./trusted-dso.js";
+export { assertPreparedTransferMatches, assertPreparedCreateTransferCommandMatches, assertHashBinding, assertOnboardingTopologyBindsKey, decodePrepared, extractTransfer, extractCreateTransferCommand, PreparedDecodeError, PreparedTransferMismatchError, PreparedHashUnavailableError, OnboardingTopologyMismatchError, type HashBindingOptions, type PreparedTransferExpectation, type PreparedCreateTransferCommandExpectation, type OnboardingTopologyExpectation, } from "./verify-prepared.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC;AAC3B,cAAc,mBAAmB,CAAC;AAClC,cAAc,cAAc,CAAC;AAC7B,cAAc,mBAAmB,CAAC;AAClC,cAAc,SAAS,CAAC;AACxB,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,OAAO,EACL,6BAA6B,EAC7B,0CAA0C,EAC1C,iBAAiB,EACjB,gCAAgC,EAChC,cAAc,EACd,eAAe,EACf,4BAA4B,EAC5B,mBAAmB,EACnB,6BAA6B,EAC7B,4BAA4B,EAC5B,+BAA+B,EAC/B,KAAK,kBAAkB,EACvB,KAAK,2BAA2B,EAChC,KAAK,wCAAwC,EAC7C,KAAK,6BAA6B,GACnC,MAAM,sBAAsB,CAAC"}

package/dist/index.js

@@ -0,0 +1,13 @@
+export * from "./keys.js";
+export * from "./store.js";
+export * from "./relay-client.js";
+export * from "./onboard.js";
+export * from "./relay-signer.js";
+export * from "./tx.js";
+export * from "./withdraw.js";
+export * from "./pay.js";
+export * from "./hash-binding.js";
+export * from "./canton-hash.js";
+export * from "./trusted-dso.js";
+export { assertPreparedTransferMatches, assertPreparedCreateTransferCommandMatches, assertHashBinding, assertOnboardingTopologyBindsKey, decodePrepared, extractTransfer, extractCreateTransferCommand, PreparedDecodeError, PreparedTransferMismatchError, PreparedHashUnavailableError, OnboardingTopologyMismatchError, } from "./verify-prepared.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC;AAC3B,cAAc,mBAAmB,CAAC;AAClC,cAAc,cAAc,CAAC;AAC7B,cAAc,mBAAmB,CAAC;AAClC,cAAc,SAAS,CAAC;AACxB,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,OAAO,EACL,6BAA6B,EAC7B,0CAA0C,EAC1C,iBAAiB,EACjB,gCAAgC,EAChC,cAAc,EACd,eAAe,EACf,4BAA4B,EAC5B,mBAAmB,EACnB,6BAA6B,EAC7B,4BAA4B,EAC5B,+BAA+B,GAKhC,MAAM,sBAAsB,CAAC"}

package/dist/keys.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Ed25519 key material for a self-custody agent wallet.
+ *
+ * The agent generates and holds this key. The participant only ever sees the
+ * SPKI/DER public key (during onboarding); the private key never leaves the
+ * agent. Serialized as strings so it can live in ~/.canton-agent/wallet.json.
+ */
+import { type KeyObject } from "node:crypto";
+export interface AgentKeyMaterial {
+    /** Base64 of the SPKI/DER public key — what onboarding sends as keyData. */
+    publicKeySpkiB64: string;
+    /** PKCS8 PEM private key — self-custody secret, persisted locally only. */
+    privateKeyPkcs8Pem: string;
+}
+export declare function generateAgentKey(): AgentKeyMaterial;
+export declare function loadPrivateKey(pkcs8Pem: string): KeyObject;
+export declare function loadPublicKey(spkiB64: string): KeyObject;
+/**
+ * Sign a base64 hash (the `multiHash` from generate-topology, or a
+ * `preparedTransactionHash` from interactive-submission) with the agent's key.
+ * Returns a base64 64-byte R||S Ed25519 signature — `SIGNATURE_FORMAT_CONCAT`.
+ */
+export declare function signHashB64(hashB64: string, pkcs8Pem: string): string;
+/** Verify a signHashB64 result — used in tests + the sign-before-trust check. */
+export declare function verifyHashB64(hashB64: string, signatureB64: string, spkiB64: string): boolean;
+//# sourceMappingURL=keys.d.ts.map

package/dist/keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys.d.ts","sourceRoot":"","sources":["../src/keys.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAML,KAAK,SAAS,EACf,MAAM,aAAa,CAAC;AAErB,MAAM,WAAW,gBAAgB;IAC/B,4EAA4E;IAC5E,gBAAgB,EAAE,MAAM,CAAC;IACzB,2EAA2E;IAC3E,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAED,wBAAgB,gBAAgB,IAAI,gBAAgB,CAQnD;AAED,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAE1D;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAMxD;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAMrE;AAED,iFAAiF;AACjF,wBAAgB,aAAa,CAC3B,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,MAAM,GACd,OAAO,CAOT"}

package/dist/keys.js

@@ -0,0 +1,38 @@
+/**
+ * Ed25519 key material for a self-custody agent wallet.
+ *
+ * The agent generates and holds this key. The participant only ever sees the
+ * SPKI/DER public key (during onboarding); the private key never leaves the
+ * agent. Serialized as strings so it can live in ~/.canton-agent/wallet.json.
+ */
+import { generateKeyPairSync, createPrivateKey, createPublicKey, sign as cryptoSign, verify as cryptoVerify, } from "node:crypto";
+export function generateAgentKey() {
+    const { publicKey, privateKey } = generateKeyPairSync("ed25519");
+    return {
+        publicKeySpkiB64: Buffer.from(publicKey.export({ type: "spki", format: "der" })).toString("base64"),
+        privateKeyPkcs8Pem: privateKey.export({ type: "pkcs8", format: "pem" }),
+    };
+}
+export function loadPrivateKey(pkcs8Pem) {
+    return createPrivateKey(pkcs8Pem);
+}
+export function loadPublicKey(spkiB64) {
+    return createPublicKey({
+        key: Buffer.from(spkiB64, "base64"),
+        format: "der",
+        type: "spki",
+    });
+}
+/**
+ * Sign a base64 hash (the `multiHash` from generate-topology, or a
+ * `preparedTransactionHash` from interactive-submission) with the agent's key.
+ * Returns a base64 64-byte R||S Ed25519 signature — `SIGNATURE_FORMAT_CONCAT`.
+ */
+export function signHashB64(hashB64, pkcs8Pem) {
+    return cryptoSign(null, Buffer.from(hashB64, "base64"), createPrivateKey(pkcs8Pem)).toString("base64");
+}
+/** Verify a signHashB64 result — used in tests + the sign-before-trust check. */
+export function verifyHashB64(hashB64, signatureB64, spkiB64) {
+    return cryptoVerify(null, Buffer.from(hashB64, "base64"), loadPublicKey(spkiB64), Buffer.from(signatureB64, "base64"));
+}
+//# sourceMappingURL=keys.js.map

package/dist/keys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys.js","sourceRoot":"","sources":["../src/keys.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EACL,mBAAmB,EACnB,gBAAgB,EAChB,eAAe,EACf,IAAI,IAAI,UAAU,EAClB,MAAM,IAAI,YAAY,GAEvB,MAAM,aAAa,CAAC;AASrB,MAAM,UAAU,gBAAgB;IAC9B,MAAM,EAAE,SAAS,EAAE,UAAU,EAAE,GAAG,mBAAmB,CAAC,SAAS,CAAC,CAAC;IACjE,OAAO;QACL,gBAAgB,EAAE,MAAM,CAAC,IAAI,CAC3B,SAAS,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAClD,CAAC,QAAQ,CAAC,QAAQ,CAAC;QACpB,kBAAkB,EAAE,UAAU,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,CAAW;KAClF,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,QAAgB;IAC7C,OAAO,gBAAgB,CAAC,QAAQ,CAAC,CAAC;AACpC,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,OAAe;IAC3C,OAAO,eAAe,CAAC;QACrB,GAAG,EAAE,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,QAAQ,CAAC;QACnC,MAAM,EAAE,KAAK;QACb,IAAI,EAAE,MAAM;KACb,CAAC,CAAC;AACL,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,OAAe,EAAE,QAAgB;IAC3D,OAAO,UAAU,CACf,IAAI,EACJ,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,QAAQ,CAAC,EAC9B,gBAAgB,CAAC,QAAQ,CAAC,CAC3B,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;AACvB,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,aAAa,CAC3B,OAAe,EACf,YAAoB,EACpB,OAAe;IAEf,OAAO,YAAY,CACjB,IAAI,EACJ,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,QAAQ,CAAC,EAC9B,aAAa,CAAC,OAAO,CAAC,EACtB,MAAM,CAAC,IAAI,CAAC,YAAY,EAAE,QAAQ,CAAC,CACpC,CAAC;AACJ,CAAC"}

package/dist/onboard.d.ts

@@ -0,0 +1,12 @@
+import { type AgentWallet } from "./store.js";
+import { RelayClient } from "./relay-client.js";
+export interface EnsureWalletOpts {
+    relayUrl: string;
+    network: string;
+    apiKey?: string | undefined;
+    partyHint?: string;
+    /** Injectable for tests; defaults to a real RelayClient. */
+    relay?: RelayClient;
+}
+export declare function ensureWallet(opts: EnsureWalletOpts): Promise<AgentWallet>;
+//# sourceMappingURL=onboard.d.ts.map

package/dist/onboard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"onboard.d.ts","sourceRoot":"","sources":["../src/onboard.ts"],"names":[],"mappings":"AAUA,OAAO,EAA0B,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AACtE,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAOhD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4DAA4D;IAC5D,KAAK,CAAC,EAAE,WAAW,CAAC;CACrB;AAED,wBAAsB,YAAY,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,WAAW,CAAC,CAyG/E"}

package/dist/onboard.js

@@ -0,0 +1,152 @@
+/**
+ * ensureWallet — lazy, idempotent self-custody onboarding.
+ *
+ * If a wallet already exists, return it (the agent reuses the same one forever).
+ * Otherwise generate a key, onboard the external party through the relay
+ * (generate-topology → sign the multiHash locally → allocate), persist, return.
+ * This is the flow proven by the Phase 0 live spike.
+ */
+import { ED25519_WIRE_CONSTANTS } from "@ftptech/x402-canton-ledger";
+import { generateAgentKey, signHashB64 } from "./keys.js";
+import { loadWallet, saveWallet } from "./store.js";
+import { RelayClient } from "./relay-client.js";
+import { assertOnboardingTopologyBindsKey, OnboardingTopologyMismatchError, } from "./verify-prepared.js";
+import { recomputeTopologyMultiHash, fingerprintHex } from "./canton-hash.js";
+export async function ensureWallet(opts) {
+    const existing = loadWallet();
+    if (existing)
+        return existing;
+    const key = generateAgentKey();
+    const relay = opts.relay ?? new RelayClient({ relayUrl: opts.relayUrl, apiKey: opts.apiKey });
+    const prep = await relay.onboardPrepare({
+        publicKey: {
+            format: ED25519_WIRE_CONSTANTS.publicKeyFormat,
+            keyData: key.publicKeySpkiB64,
+            keySpec: ED25519_WIRE_CONSTANTS.keySpec,
+        },
+        partyHint: opts.partyHint ?? "agent",
+    });
+    // VERIFY-BEFORE-SIGN (onboarding) — TWO complementary, fail-closed legs:
+    //  (1) STRUCTURAL: decode the topology transactions and prove they onboard the
+    //      agent's OWN key into the agent's OWN namespace (authoritative mappings
+    //      bind exactly the agent's key, threshold 1, no foreign co-holders).
+    //  (2) HASH RECOMPUTE: recompute the multiHash + fingerprint locally (below)
+    //      and sign the RECOMPUTED value, so the signature is bound to the exact
+    //      bytes we structurally verified.
+    // Either a relay that binds a different key/party (custody hijack, caught by 1)
+    // or one that pairs honest-looking topology with the hash of a different bundle
+    // (caught by 2) is refused. See verify-prepared.ts / canton-hash.ts.
+    assertOnboardingTopologyBindsKey(prep.onboardingTransactions, {
+        publicKeySpkiB64: key.publicKeySpkiB64,
+        party: prep.party,
+        publicKeyFingerprint: prep.publicKeyFingerprint,
+    });
+    // HASH RECOMPUTE (onboarding): bind the signed multiHash to the EXACT topology
+    // bytes we just structurally verified. The relay's `hashToSign` is the combined
+    // multiHash over the onboarding transactions; recompute it locally EXACTLY as
+    // the participant does on `allocate` (HashPurpose 11 per-tx, 55 combined; the
+    // official @canton-network/core-tx-visualizer primitives), compare, and sign the
+    // RECOMPUTED value — never the relay's. A relay that returns honest-looking
+    // topology paired with the multiHash of a DIFFERENT bundle is refused here.
+    const recomputedMultiHash = await recomputeTopologyMultiHash(prep.onboardingTransactions);
+    if (recomputedMultiHash !== prep.hashToSign) {
+        throw new OnboardingTopologyMismatchError(`relay-returned onboarding hashToSign does NOT match the multiHash recomputed ` +
+            `from the onboarding transactions — refusing to sign (possible tampered/` +
+            `compromised relay supplying the hash of a different topology bundle)`);
+    }
+    // LOCAL FINGERPRINT assert: the prior namespace check compared two
+    // relay-supplied strings (party namespace vs publicKeyFingerprint). Derive the
+    // fingerprint locally from the agent's OWN public-key bytes and assert it equals
+    // the relay's publicKeyFingerprint — closing the relay-vs-relay namespace trust
+    // gap (the namespace is the fingerprint; if the relay lies about the fingerprint
+    // it lies about the namespace). Fail-closed.
+    await assertLocalFingerprintMatches(key.publicKeySpkiB64, prep.publicKeyFingerprint);
+    const signature = {
+        format: ED25519_WIRE_CONSTANTS.signatureFormat,
+        // Sign the RECOMPUTED multiHash, not the relay's hashToSign (they are proven
+        // equal above; signing the recomputed value makes the binding explicit).
+        signature: signHashB64(recomputedMultiHash, key.privateKeyPkcs8Pem),
+        signingAlgorithmSpec: ED25519_WIRE_CONSTANTS.signingAlgorithmSpec,
+        signedBy: prep.publicKeyFingerprint,
+    };
+    const fin = await relay.onboardFinalize({
+        onboardingTransactions: prep.onboardingTransactions,
+        multiHashSignatures: [signature],
+    });
+    // The party we PERSIST (and will later act_as) must be the one we just proved
+    // lives in the agent key's namespace. The verified anchor is prep.party (it was
+    // checked against publicKeyFingerprint above); if the finalize step returns a
+    // different party, it must STILL be in that same verified namespace, else a
+    // relay could swap the persisted identity after the topology check. Fail-closed.
+    const party = fin.party || prep.party;
+    if (party !== prep.party) {
+        const sep = party.lastIndexOf("::");
+        const ns = sep > 0 ? party.slice(sep + 2) : "";
+        if (ns !== prep.publicKeyFingerprint) {
+            throw new OnboardingTopologyMismatchError(`onboard/finalize returned party ${JSON.stringify(party)} whose namespace does not match ` +
+                `the verified key fingerprint ${JSON.stringify(prep.publicKeyFingerprint)} — refusing to ` +
+                `persist a wallet for a party outside the agent key's own namespace`);
+        }
+    }
+    const wallet = {
+        network: opts.network,
+        relayUrl: opts.relayUrl,
+        party,
+        publicKeySpkiB64: key.publicKeySpkiB64,
+        privateKeyPkcs8Pem: key.privateKeyPkcs8Pem,
+        publicKeyFingerprint: prep.publicKeyFingerprint,
+        createdAt: new Date().toISOString(),
+    };
+    saveWallet(wallet);
+    return wallet;
+}
+/** The bare 32-byte Ed25519 public-key point from an SPKI/DER base64 (the point
+ *  is the trailing 32 bytes of the SPKI encoding). */
+function rawEd25519Point(spkiB64) {
+    const der = Buffer.from(spkiB64, "base64");
+    return der.subarray(Math.max(0, der.length - 32));
+}
+/** Normalize a Canton fingerprint hex for comparison: lowercase; tolerate an
+ *  optional `1220` (0x12 0x20 multihash sha2-256) prefix on either side so a
+ *  framed-vs-unframed representation still compares equal. */
+function normalizeFingerprint(fp) {
+    const lower = fp.trim().toLowerCase();
+    return lower.startsWith("1220") ? lower.slice(4) : lower;
+}
+/**
+ * Derive the public-key fingerprint LOCALLY from the agent's own key bytes and
+ * assert it equals the relay-returned `publicKeyFingerprint`. Fail-closed.
+ *
+ * WHICH KEY-BYTE FORM: Canton's fingerprint preimage is `HashPurpose 12 ||
+ * <key bytes>`, but whether `<key bytes>` is the SPKI/DER the agent sent or the
+ * bare 32-byte Ed25519 point is not pinned offline (spec B.5 flags this as
+ * needing a live `generate-topology` vector to confirm). We compute BOTH
+ * candidate fingerprints and accept iff the relay's value equals EITHER. This is
+ * still a real binding against the attack we care about — a relay returning the
+ * fingerprint of a FOREIGN key matches NEITHER candidate and is refused — while
+ * tolerating the spec ambiguity until a live vector pins the exact form. The
+ * conformance test (`canton-hash.conformance.test.ts`) records, once a live
+ * topology vector is dropped in, which form Canton actually uses.
+ */
+async function assertLocalFingerprintMatches(publicKeySpkiB64, relayFingerprint) {
+    if (typeof relayFingerprint !== "string" || relayFingerprint.length === 0) {
+        throw new OnboardingTopologyMismatchError("relay returned an empty publicKeyFingerprint — refusing to sign the onboarding " +
+            "topology (cannot bind the party namespace to the agent's key)");
+    }
+    const derBytes = Buffer.from(publicKeySpkiB64, "base64");
+    const pointBytes = rawEd25519Point(publicKeySpkiB64);
+    const [fpFromDer, fpFromPoint] = await Promise.all([
+        fingerprintHex(derBytes),
+        fingerprintHex(pointBytes),
+    ]);
+    const want = normalizeFingerprint(relayFingerprint);
+    const candidates = [fpFromDer, fpFromPoint].map(normalizeFingerprint);
+    if (!candidates.includes(want)) {
+        throw new OnboardingTopologyMismatchError(`relay-returned publicKeyFingerprint ${JSON.stringify(relayFingerprint)} does not ` +
+            `equal the fingerprint derived locally from the agent's own public key ` +
+            `(neither the SPKI/DER nor the bare-point preimage matched) — refusing to sign ` +
+            `the onboarding topology (possible tampered/compromised relay claiming a foreign ` +
+            `key's fingerprint as the agent's namespace)`);
+    }
+}
+//# sourceMappingURL=onboard.js.map

package/dist/onboard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"onboard.js","sourceRoot":"","sources":["../src/onboard.ts"],"names":[],"mappings":"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"}

package/dist/pay.d.ts

@@ -0,0 +1,16 @@
+import { type EnsureWalletOpts } from "./onboard.js";
+import type { HashBindingOptions } from "./verify-prepared.js";
+export interface PayOpts extends EnsureWalletOpts {
+    /** @deprecated ignored; the relay sets the participant user. */
+    userId?: string;
+    /**
+     * How to bind the relay-returned hash to the validated bytes before signing
+     * each autopay transfer. Omitted → the env-resolved default, which is the REAL
+     * conformant V2 hash recompute (canton-hash.ts) unless CANTON_AGENT_TRUST_
+     * RELAY_HASH opts into the escape hatch. Supply a `recomputeHash` to override.
+     * See HashBindingOptions / verify-prepared.ts.
+     */
+    hashBinding?: HashBindingOptions;
+}
+export declare function makePayingFetch(opts: PayOpts): Promise<typeof globalThis.fetch>;
+//# sourceMappingURL=pay.d.ts.map

package/dist/pay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pay.d.ts","sourceRoot":"","sources":["../src/pay.ts"],"names":[],"mappings":"AAQA,OAAO,EAAgB,KAAK,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAEnE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE/D,MAAM,WAAW,OAAQ,SAAQ,gBAAgB;IAC/C,gEAAgE;IAChE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,kBAAkB,CAAC;CAClC;AAED,wBAAsB,eAAe,CACnC,IAAI,EAAE,OAAO,GACZ,OAAO,CAAC,OAAO,UAAU,CAAC,KAAK,CAAC,CAOlC"}

package/dist/pay.js

@@ -0,0 +1,19 @@
+/**
+ * makePayingFetch — a drop-in fetch that auto-pays x402 challenges from the
+ * agent's self-custody wallet. Lazily creates the wallet on first use, then
+ * wraps fetch so any 402 is paid (resolve factory via relay → build CIP-56
+ * transfer → sign locally → execute via relay) and the request retried. The
+ * agent just "fetches".
+ */
+import { wrapFetchWithCantonPayment } from "@ftptech/x402-canton-client";
+import { ensureWallet } from "./onboard.js";
+import { makeRelaySigner } from "./relay-signer.js";
+export async function makePayingFetch(opts) {
+    const wallet = await ensureWallet(opts);
+    const signer = makeRelaySigner(wallet, {
+        apiKey: opts.apiKey,
+        ...(opts.hashBinding ? { hashBinding: opts.hashBinding } : {}),
+    });
+    return wrapFetchWithCantonPayment(globalThis.fetch, signer);
+}
+//# sourceMappingURL=pay.js.map

package/dist/pay.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pay.js","sourceRoot":"","sources":["../src/pay.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,0BAA0B,EAAE,MAAM,6BAA6B,CAAC;AACzE,OAAO,EAAE,YAAY,EAAyB,MAAM,cAAc,CAAC;AACnE,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAgBpD,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,IAAa;IAEb,MAAM,MAAM,GAAG,MAAM,YAAY,CAAC,IAAI,CAAC,CAAC;IACxC,MAAM,MAAM,GAAG,eAAe,CAAC,MAAM,EAAE;QACrC,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC/D,CAAC,CAAC;IACH,OAAO,0BAA0B,CAAC,UAAU,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;AAC9D,CAAC"}