@carbonx3/cx3.js 0.3.10 → 0.3.11

package/README.md

@@ -313,7 +313,8 @@ try {
 | `insufficient_scope`, `ROUTE_NOT_ALLOWED` | The route needs another scope, or is not open to applications (403) |
 | `RATE_LIMITED` | The application's rate limit was reached (429) |
 | `INSUFFICIENT_BALANCE`, `GAS_PRICE_TOO_LOW` | A native transfer's sender cannot pay the amount plus gas, or the gas price is below the chain floor |
-| `INVALID_AMOUNT`, `INVALID_AMOUNT_PRECISION` | A native amount is not greater than 0, or has more than 6 decimal places (CX3 has 6); `transferNative` checks both before signing |
+| `INVALID_AMOUNT`, `INVALID_AMOUNT_PRECISION` | A native amount is not greater than 0, is a text that is not plain decimal digits (`"0x10"`, `"1e3"`), or has more than 6 decimal places (CX3 has 6); `transferNative` checks before signing |
+| `INVALID_RECIPIENT` | `transferNative` was given a recipient that is not a full address (`0x` or `cx3:` and 40 hex digits); nothing is signed |
 | `GAS_LIMIT_TOO_LOW`, `GAS_LIMIT_TOO_HIGH` | A native transfer's gas limit is outside 21,000–100,000 |
 | `GAS_LIMIT_EXCEEDED` | A contract send's `gasLimit` is above the chain's maximum (400, `max` in the body) |
 | `INVALID_NONCE_ORDER` | A native transfer's nonce is not the next one (`expectedNonce` in the answer) |
@@ -333,16 +334,18 @@ try {
 | `LEDGER_UNAVAILABLE`, `LEDGER_FULL` | The gateway's `/dapp/v1` send could not record the request (503): it was not sent, and the same signed body may be sent again later, without a new signature |
 | `BASIC_AUTH_UNSUPPORTED` | The `auth` option was used |
 | `NO_CHAIN_IDENTITY` | The network's chain id or genesis hash is unavailable; a native transfer is not signed without them |
+| `CHAIN_IDENTITY_MISMATCH` | The provider was made for one network (`chainId` and `genesisHash` options) and the endpoint names another; nothing is signed (`err.details.expected`, `err.details.got`) |
+| `INSECURE_BASE_URL` | Credentials would travel over plain `http` to another machine; use `https` (or `allowInsecure: true` on a network you trust) |
 
 ## Browser applications
 
-This package is for Node.js servers. Web pages use the **CX3 IIFE** (`window.cx3`) together with the CX3Wallet extension: [`@carbonx3/cx3-iife`](https://www.npmjs.com/package/@carbonx3/cx3-iife) on npm and jsDelivr, or [download it](https://cx3script.com/download/cx3-0.2.10.min.js); see the [CX3 IIFE guide](https://cx3script.com/docs?doc=cx3iife). Keep the application's credentials on your server behind a same-origin proxy, and never put a client secret, an API key or a private key in browser JavaScript.
+This package is for Node.js servers. Web pages use the **CX3 IIFE** (`window.cx3`) together with the CX3Wallet extension: [`@carbonx3/cx3-iife`](https://www.npmjs.com/package/@carbonx3/cx3-iife) on npm and jsDelivr, or [download it](https://cx3script.com/download/cx3-0.2.11.min.js); see the [CX3 IIFE guide](https://cx3script.com/docs?doc=cx3iife). Keep the application's credentials on your server behind a same-origin proxy, and never put a client secret, an API key or a private key in browser JavaScript.
 
 ## Environment variables
 
 | Variable | Used for |
 |----------|----------|
-| `CX3_CLIENT_ID`, `CX3_CLIENT_SECRET` | Application credentials when the options are omitted |
+| `CX3_CLIENT_ID`, `CX3_CLIENT_SECRET` | Application credentials when the options are omitted (not read with `devNode: true`) |
 | `CX3_API_KEY` | Legacy wallet API key |
 | `CX3_NODE_URL` | Gateway URL for `getDefaultProvider()` |
 
@@ -352,7 +355,7 @@ Type declarations (`index.d.ts`) ship with the package.
 
 ## Upgrading from 0.2.x
 
-Version 0.3.0 signs native transfers for the network's new signing format (0.3.1 to 0.3.4 change only this README, the file headers and comments, not the code). In 0.3.5, `bindApiKey` with a wallet API key asks the gateway's `/wallet/api-key/bind` (before, it asked `/whoami`, which the gateway refuses, so it always failed). In 0.3.6, `wait()` follows a send or deploy the gateway reports as not final (`dropped`) until its `finalAfter` instead of failing after 60 s, a `TX_TIMEOUT` answer with a hash is pending, `getRequest()` looks up a signed request, and `transferNative` refuses more than 6 decimals. 0.3.7 changes only this README: a native transfer's gas price floor is 0.0001 (the 0.3.6 README said 0.000001). 0.3.8 changes only this README too: the CX3 IIFE download link names `cx3-0.2.10.min.js`. In 0.3.9, `deployContract` signs `CX3_DEPLOY_V2`: the code and the constructor arguments of the request are under the signature (`Cx3Wallet.deployContentHash`, `signDeploy({ contentHash })`, `deployContentText`). In 0.3.10, a refused native transfer (HTTP 200 with `error`) is `success: false` / `status: "failed"` and `wait()` rejects (before, it was reported as confirmed); an accepted transfer without a block is `"pending"`; `wait()` rejects with `NO_TX_HASH` when the answer names no transaction; the private key, client secret, API key and access token are private fields (`wallet._privateKey`, `provider.apiKey` and `provider._clientSecret` are gone; use `wallet.exportPrivateKey()`), and results no longer carry the provider into JSON or logs.
+Version 0.3.0 signs native transfers for the network's new signing format (0.3.1 to 0.3.4 change only this README, the file headers and comments, not the code). In 0.3.5, `bindApiKey` with a wallet API key asks the gateway's `/wallet/api-key/bind` (before, it asked `/whoami`, which the gateway refuses, so it always failed). In 0.3.6, `wait()` follows a send or deploy the gateway reports as not final (`dropped`) until its `finalAfter` instead of failing after 60 s, a `TX_TIMEOUT` answer with a hash is pending, `getRequest()` looks up a signed request, and `transferNative` refuses more than 6 decimals. 0.3.7 changes only this README: a native transfer's gas price floor is 0.0001 (the 0.3.6 README said 0.000001). 0.3.8 changes only this README too: the CX3 IIFE download link names `cx3-0.2.10.min.js`. In 0.3.9, `deployContract` signs `CX3_DEPLOY_V2`: the code and the constructor arguments of the request are under the signature (`Cx3Wallet.deployContentHash`, `signDeploy({ contentHash })`, `deployContentText`). In 0.3.10, a refused native transfer (HTTP 200 with `error`) is `success: false` / `status: "failed"` and `wait()` rejects (before, it was reported as confirmed); an accepted transfer without a block is `"pending"`; `wait()` rejects with `NO_TX_HASH` when the answer names no transaction; the private key, client secret, API key and access token are private fields (`wallet._privateKey`, `provider.apiKey` and `provider._clientSecret` are gone; use `wallet.exportPrivateKey()`), and results no longer carry the provider into JSON or logs. In 0.3.11, `transferNative` refuses a recipient that is not a full address (`INVALID_RECIPIENT`) and a text amount that is not plain decimal digits; `sendTransaction`, `deployContract` and the owner actions sign for `opts.chainId` and `opts.genesisHash` when both are given; a provider can be made for one network (`chainId` and `genesisHash` options, `CHAIN_IDENTITY_MISMATCH`); credentials are not sent over plain `http` to another machine (`INSECURE_BASE_URL`); with `devNode: true` the credentials of the environment are not read; and `@noble/secp256k1` is pinned to one exact version.
 
 - **The genesis hash is signed.** `transferNative` asks the network for its chain id and genesis hash (`provider.getChainIdentity()`) unless both are given as `opts.chainId` and `opts.genesisHash`. 0.2.x transfers no longer verify on the chain.
 - **No fallback chain id.** `buildTransferPayload` throws `NO_CHAIN_IDENTITY` without `chainId` and `genesisHash`; the `CX3_CHAIN_ID` variable and the `chainIdBind` option are gone.

package/index.d.ts

@@ -31,8 +31,13 @@ export interface Cx3ProviderOptions {
   scope?: string | Array<"read" | "write" | "deploy">;
   /** wallet API key (cx3wk_…), until apps move to OAuth2; env CX3_API_KEY */
   apiKey?: string;
-  /** a development node that runs without auth (/api/v1), no credentials */
+  /** a development node that runs without auth (/api/v1); the credentials of the environment are not read for it */
   devNode?: boolean;
+  /** The network this provider is for (both together): an endpoint on another network is refused with CHAIN_IDENTITY_MISMATCH and nothing is signed */
+  chainId?: string;
+  genesisHash?: string;
+  /** Credentials over plain http to another machine throw INSECURE_BASE_URL unless this is true (localhost is always allowed) */
+  allowInsecure?: boolean;
   /** "" on the gateway, "/api/v1" on a development node */
   apiPrefix?: string;
   /** Not supported: throws BASIC_AUTH_UNSUPPORTED (HTTP Basic is the nodes' internal login) */
@@ -165,15 +170,15 @@ export class Cx3Wallet {
   signSend(contractAddress: string, method: string, params?: object, opts?: Cx3ChainIdentity): Promise<any>;
   signOwnerAction(action: string, address: string, owner?: string | null, opts?: Cx3ChainIdentity): Promise<any>;
   /** A private token's transfer / transferFrom / mint is checked first (PRIVATE_TOKEN_SENDER / _RECIPIENT); `privateCheck: false` skips it */
-  sendTransaction(contractAddress: string, method: string, params?: object, opts?: { wait?: number; async?: boolean; privateCheck?: boolean; [k: string]: unknown }): Promise<TransactionResponse>;
+  sendTransaction(contractAddress: string, method: string, params?: object, opts?: { wait?: number; async?: boolean; privateCheck?: boolean; chainId?: string; genesisHash?: string; [k: string]: unknown }): Promise<TransactionResponse>;
   /** Throws Cx3Error INVALID_TOKEN_SYMBOL (before signing) for a symbol outside A-Z / 0-9; the chain answers DUPLICATE_TOKEN_SYMBOL (409) for a symbol in use. A dropped deploy is pending: result.wait() follows it. */
   /** Sends an earlier send's signed request again, unchanged (no new signature): after SEND_OUTCOME_UNKNOWN or a lost answer */
   resendTransaction(signedRequest: Cx3SignedRequest, opts?: { wait?: number; async?: boolean }): Promise<TransactionResponse>;
-  deployContract(fields: object): Promise<Cx3DeployResult>;
-  pauseContract(address: string, owner?: string | null): Promise<any>;
-  unpauseContract(address: string, owner?: string | null): Promise<any>;
-  deleteContract(address: string, owner?: string | null): Promise<any>;
-  /** Throws Cx3Error INVALID_AMOUNT (not greater than 0) or INVALID_AMOUNT_PRECISION (more than 6 decimals) before signing */
+  deployContract(fields: object, opts?: Cx3ChainIdentity): Promise<Cx3DeployResult>;
+  pauseContract(address: string, owner?: string | null, opts?: Cx3ChainIdentity): Promise<any>;
+  unpauseContract(address: string, owner?: string | null, opts?: Cx3ChainIdentity): Promise<any>;
+  deleteContract(address: string, owner?: string | null, opts?: Cx3ChainIdentity): Promise<any>;
+  /** Before signing, throws Cx3Error INVALID_RECIPIENT (not 0x / cx3: + 40 hex), INVALID_AMOUNT (not greater than 0, or a text that is not plain decimal digits) or INVALID_AMOUNT_PRECISION (more than 6 decimals) */
   transferNative(to: string, amount: number | string, opts?: { nonce?: number; timestamp?: number; data?: unknown; gasLimit?: number; gasPrice?: number; chainId?: string; genesisHash?: string; wait?: number }): Promise<TransactionResponse>;
   bindApiKey(address?: string): Promise<any>;
 }

package/index.js

@@ -34,7 +34,7 @@ const {
 } = require("./src/crypto");
 const { normalizeAbi, argsToParams } = require("./src/abi");
 
-const VERSION = "0.3.10";
+const VERSION = "0.3.11";
 
 /**
  * Convenience: provider from `options.url` or env `CX3_NODE_URL` — the CX3Api gateway

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carbonx3/cx3.js",
-  "version": "0.3.10",
+  "version": "0.3.11",
   "description": "Official Node.js SDK (CX3js) for CarbonX3 Green Chain: OAuth2 app access, local secp256k1 signing, ABI-bound contracts and token deploys over REST + JSON",
   "homepage": "https://cx3script.com",
   "publishConfig": {
@@ -40,7 +40,7 @@
     "node": ">=20.19.0"
   },
   "dependencies": {
-    "@noble/secp256k1": "^3.2.0"
+    "@noble/secp256k1": "3.2.0"
   },
   "exports": {
     ".": {

package/src/provider.js

@@ -65,7 +65,16 @@ function withoutCredentialHeaders(headers) {
     return out;
 }
 
-const CLIENT_ID_RE = /^cx3app_[a-f0-9]{24}$/i;
+// http to another machine (not localhost / 127.x / ::1)
+function isRemotePlainHttp(baseUrl) {
+    let u;
+    try { u = new URL(baseUrl); } catch (_) { return false; }
+    if (u.protocol !== "http:") return false;
+    const host = u.hostname.replace(/^\[|\]$/g, "").toLowerCase();
+    return !(host === "localhost" || host.endsWith(".localhost") || host === "::1" || /^127(\.\d{1,3}){3}$/.test(host));
+}
+
+const CLIENT_ID_RE =/^cx3app_[a-f0-9]{24}$/i;
 const CLIENT_SECRET_RE = /^cx3sec_[a-f0-9]{64}$/i;
 
 // a dropped tx is failed for good after its finalAfter: wait this much past it (clock skew)
@@ -106,12 +115,13 @@ class Cx3Provider {
                 "BASIC_AUTH_UNSUPPORTED"
             );
         }
-        const env = (name) => (process.env[name] || "").trim();
+        this.devNode = options.devNode === true;
+        // a development node gets only what the caller passes: the gateway credentials of the environment never go to it
+        const env = (name) => (this.devNode ? "" : (process.env[name] || "").trim());
         this.clientId = String(options.clientId != null ? options.clientId : env("CX3_CLIENT_ID")).trim();
         this.#clientSecret = String(options.clientSecret != null ? options.clientSecret : env("CX3_CLIENT_SECRET")).trim();
         this.scope = Array.isArray(options.scope) ? options.scope.join(" ") : String(options.scope || "").trim();
         this.#apiKey = String(options.apiKey != null ? options.apiKey : env("CX3_API_KEY")).trim();
-        this.devNode = options.devNode === true;
         this.oauth = !!(this.clientId || this.#clientSecret);
         if (this.oauth && (!CLIENT_ID_RE.test(this.clientId) || !CLIENT_SECRET_RE.test(this.#clientSecret))) {
             throw new Cx3Error("clientId must be cx3app_… and clientSecret cx3sec_… (CX3WebUI → Settings → API → Applications)", "INVALID_CLIENT_CREDENTIALS");
@@ -123,6 +133,24 @@ class Cx3Provider {
                 "CREDENTIALS_REQUIRED"
             );
         }
+        // credentials over plain http can be read on the way: only this machine, or the caller's own word
+        if ((this.oauth || hasKey) && options.allowInsecure !== true && isRemotePlainHttp(this.baseUrl)) {
+            throw new Cx3Error(
+                "Credentials are not sent over plain http: use an https URL (or allowInsecure: true on a network you trust)",
+                "INSECURE_BASE_URL"
+            );
+        }
+        // The network this provider is for: with both given, signatures are made for this network only and
+        // an endpoint that names another one is refused (CHAIN_IDENTITY_MISMATCH).
+        this.pinnedIdentity = null;
+        if (options.chainId != null || options.genesisHash != null) {
+            const chainId = String(options.chainId == null ? "" : options.chainId).trim();
+            const genesisHash = normalizeGenesisHash(options.genesisHash);
+            if (!chainId || !genesisHash) {
+                throw new Cx3Error("chainId and genesisHash are given together (genesisHash: 64 hex)", "NO_CHAIN_IDENTITY");
+            }
+            this.pinnedIdentity = { chainId, genesisHash };
+        }
         this.gateway = !this.devNode;
         this.apiPrefix = options.apiPrefix != null ? options.apiPrefix : (this.gateway ? "" : "/api/v1");
         this.extraHeaders = withoutCredentialHeaders(options.headers);
@@ -432,6 +460,14 @@ class Cx3Provider {
         const chainId = typeof r.chainId === "string" ? r.chainId.trim() : "";
         const genesisHash = normalizeGenesisHash(r.genesisHash);
         if (!chainId || !genesisHash) throw new Cx3Error("network identity unavailable", "NO_CHAIN_IDENTITY");
+        const pin = this.pinnedIdentity;
+        if (pin && (pin.chainId !== chainId || pin.genesisHash !== genesisHash)) {
+            throw new Cx3Error(
+                "The endpoint is on another network than the one this provider was made for: nothing is signed",
+                "CHAIN_IDENTITY_MISMATCH",
+                { expected: { ...pin }, got: { chainId, genesisHash } }
+            );
+        }
         this._chainIdentity = { at: Date.now(), value: { chainId, genesisHash } };
         return { chainId, genesisHash };
     }

package/src/wallet.js

@@ -235,7 +235,7 @@ class Cx3Wallet {
         if (opts.privateCheck !== false && typeof this.provider.checkPrivateTokenSend === "function") {
             await this.provider.checkPrivateTokenSend(contractAddress, method, params, this.address);
         }
-        const signed = await this.signSend(contractAddress, method, params);
+        const signed = await this.signSend(contractAddress, method, params, opts);
         // everything the gateway needs to take the same signed call again: no key, safe to store
         const signedRequest = {
             contractAddress,
@@ -309,7 +309,7 @@ class Cx3Wallet {
      * (Cx3HttpError code DUPLICATE_TOKEN_SYMBOL, status 409). A dropped deploy (202, `dropped`,
      * `finalAfter`) is pending, not deployed: `result.wait()` follows it (withDeployWait).
      */
-    async deployContract(fields) {
+    async deployContract(fields, opts = {}) {
         if (!this.provider) throw new Cx3Error("Wallet has no provider", "NO_PROVIDER");
         fields = toJsonSafe(fields || {});
         const ctor = fields.constructorArgs && typeof fields.constructorArgs === "object" && !Array.isArray(fields.constructorArgs) ? fields.constructorArgs : {};
@@ -329,7 +329,7 @@ class Cx3Wallet {
             ...fields,
             owner: fields.owner || this.address,
             contentHash
-        });
+        }, opts);
         const body = {
             ...fields,
             owner: signed.owner,
@@ -347,9 +347,9 @@ class Cx3Wallet {
         return withDeployWait(result, this.provider);
     }
 
-    async _ownerActionRequest(action, address, owner, method, path) {
+    async _ownerActionRequest(action, address, owner, method, path, opts = {}) {
         if (!this.provider) throw new Cx3Error("Wallet has no provider", "NO_PROVIDER");
-        const signed = await this.signOwnerAction(action, address, owner);
+        const signed = await this.signOwnerAction(action, address, owner, opts);
         return this.provider.request(path, {
             method,
             body: {
@@ -361,33 +361,36 @@ class Cx3Wallet {
         });
     }
 
-    async pauseContract(address, owner = null) {
+    async pauseContract(address, owner = null, opts = {}) {
         return this._ownerActionRequest(
             "pause",
             address,
             owner,
             "PUT",
-            `/contracts/${encodeURIComponent(address)}/pause`
+            `/contracts/${encodeURIComponent(address)}/pause`,
+            opts
         );
     }
 
-    async unpauseContract(address, owner = null) {
+    async unpauseContract(address, owner = null, opts = {}) {
         return this._ownerActionRequest(
             "unpause",
             address,
             owner,
             "PUT",
-            `/contracts/${encodeURIComponent(address)}/unpause`
+            `/contracts/${encodeURIComponent(address)}/unpause`,
+            opts
         );
     }
 
-    async deleteContract(address, owner = null) {
+    async deleteContract(address, owner = null, opts = {}) {
         return this._ownerActionRequest(
             "delete",
             address,
             owner,
             "DELETE",
-            `/contracts/${encodeURIComponent(address)}`
+            `/contracts/${encodeURIComponent(address)}`,
+            opts
         );
     }
 
@@ -399,9 +402,18 @@ class Cx3Wallet {
      */
     async transferNative(to, amount, opts = {}) {
         if (!this.provider) throw new Cx3Error("Wallet has no provider", "NO_PROVIDER");
-        const toAddress = String(to || "").trim();
-        if (!toAddress) throw new Cx3Error("recipient required", "NO_RECIPIENT");
-        const amt = typeof amount === "number" ? amount : Number(amount);
+        if (to == null || String(to).trim() === "") throw new Cx3Error("recipient required", "NO_RECIPIENT");
+        // a full address only (0x / cx3: + 40 hex): anything else is not signed
+        const toAddress = normalizeAddress(to);
+        if (!/^0x[0-9a-f]{40}$/.test(toAddress)) {
+            throw new Cx3Error("The recipient is not a CX3 address (0x + 40 hex)", "INVALID_RECIPIENT");
+        }
+        // a text amount is plain decimal digits: "0x10" or "1e3" would be read as another number
+        if (typeof amount === "string" && !/^\d{1,15}(\.\d+)?$/.test(amount.trim())) {
+            throw new Cx3Error("Invalid amount", "INVALID_AMOUNT");
+        }
+        if (typeof amount !== "number" && typeof amount !== "string") throw new Cx3Error("Invalid amount", "INVALID_AMOUNT");
+        const amt = typeof amount === "number" ? amount : Number(amount.trim());
         if (!Number.isFinite(amt) || amt <= 0) {
             throw new Cx3Error("Invalid amount", "INVALID_AMOUNT");
         }