@carbonx3/cx3.js 0.3.11 → 0.4.0

package/README.md

@@ -6,7 +6,10 @@
 
 The official Node.js SDK (**CX3js**) for [CarbonX3 Green Chain](https://carbonx3.com/).
 
-CX3js connects server-side applications to CarbonX3 Green Chain through the CX3Api gateway. It signs in as an OAuth2 application, signs transactions locally with secp256k1, binds contract ABIs to plain JavaScript methods and deploys the Green Chain token standards. Requests are REST + JSON with named parameters, not binary calldata.
+- **Developer site:** [CX3Script](https://cx3script.com)
+- **Documentation:** [cx3script.com/docs](https://cx3script.com/docs)
+
+CX3js connects server-side applications to CarbonX3 Green Chain through the CX3Api gateway. It signs in as an OAuth2 application, signs transactions with secp256k1 (a key in your process, or your own signer), binds contract ABIs to plain JavaScript methods and deploys the Green Chain token standards. Requests are REST + JSON with named parameters, not binary calldata.
 
 > **Network status:** CarbonX3 Green Chain currently runs as a development network (devnet; `provider.getStatus()` returns its current chain id). Devnet CX3, tokens and contracts are test data with no monetary value and may be cleared when the devnet is reset.
 
@@ -14,6 +17,7 @@ CX3js connects server-side applications to CarbonX3 Green Chain through the CX3A
 
 - **OAuth2 application access**: client credentials from CX3WebUI; the access token is requested, cached and renewed for you.
 - **Local signing**: private keys stay in your process, and every write carries the wallet's secp256k1 signature.
+- **External signers**: a wallet can sign through an HSM, a KMS, a hardware wallet or a custody service, so the key never enters your process.
 - **Secrets stay out of logs**: a wallet, a provider or a result that is logged or sent as JSON never contains the private key, the client secret or the access token.
 - **Honest results**: a send or transfer the network refuses is reported as failed, and `"confirmed"` always comes with the block it is in.
 - **ABI-bound contracts**: `token.balanceOf(owner)` and `token.transfer(to, amount)`, with the ABI loaded from the chain.
@@ -87,27 +91,19 @@ ES modules work too: `import { Cx3Provider, Cx3Wallet } from "@carbonx3/cx3.js";
 
 ## Authentication
 
-**OAuth2 application (recommended).** The provider exchanges `clientId` and `clientSecret` at `POST /oauth/token` (client credentials grant) for a one-hour access token and sends it as `Authorization: Bearer …`. It renews the token a minute before it expires and, if the gateway answers `invalid_token`, fetches a fresh one and retries once. The secret is sent only to the token endpoint. `scope: ["read"]` requests fewer scopes than the application has. When the options are omitted, the provider reads `CX3_CLIENT_ID` and `CX3_CLIENT_SECRET`.
+**OAuth2 application.** The provider exchanges `clientId` and `clientSecret` at `POST /oauth/token` (client credentials grant) for a one-hour access token and sends it as `Authorization: Bearer …`. It renews the token a minute before it expires and, if the gateway answers `invalid_token`, fetches a fresh one and retries once. The secret is sent only to the token endpoint. `scope: ["read"]` requests fewer scopes than the application has. When the options are omitted, the provider reads `CX3_CLIENT_ID` and `CX3_CLIENT_SECRET`.
 
 The access token identifies the application; every write is still signed by the wallet. A route outside the application's scopes answers `403 insufficient_scope`, and routes reserved for CarbonX3's own services answer `403 ROUTE_NOT_ALLOWED`. Each application has its own rate limit (300 requests per minute by default, `429 RATE_LIMITED`).
 
 `provider.bindApiKey(address)` (or `wallet.bindApiKey()`) confirms that a wallet is the one the application belongs to: `{ ok: true }`, otherwise `wallet_mismatch`.
 
-**Wallet API key (legacy).** A `cx3wk_…` key from the same settings page still works while applications move to OAuth2. Pass it as `apiKey` (or set `CX3_API_KEY`); it is sent as `X-Api-Key` and carries every scope of its wallet.
-
-```javascript
-const provider = new Cx3Provider("https://cx3api.carbonx3.com", { apiKey: process.env.CX3_API_KEY });
-```
-
 **Development node.** `new Cx3Provider(devNodeUrl, { devNode: true })` talks to a development node that runs without authentication (its `/api/v1` routes).
 
-**Credentials are required.** Without an application, an API key or `devNode: true`, the constructor throws `CREDENTIALS_REQUIRED`.
-
-**No HTTP Basic.** HTTP Basic is the internal login between Green Chain nodes and CarbonX3 services, not an application credential, so the SDK never sends it: the `auth` option throws `BASIC_AUTH_UNSUPPORTED`, and `headers` cannot carry `Authorization` or `X-Api-Key`.
+**Credentials are required.** Without an application or `devNode: true`, the constructor throws `CREDENTIALS_REQUIRED`. The application is the only credential: `headers` cannot carry `Authorization`.
 
 ## Keeping secrets out of logs
 
-A wallet's private key and a provider's client secret, API key and access token are private fields of their objects. Nothing that prints, serializes or copies an object can reach them:
+A wallet's private key and a provider's client secret and access token are private fields of their objects. Nothing that prints, serializes or copies an object can reach them:
 
 ```javascript
 JSON.stringify(wallet);          // {"address":"0x…","publicKey":"02…"}
@@ -118,7 +114,7 @@ const copy = { ...wallet };      // address, publicKey and provider; no key
 const key = wallet.exportPrivateKey();   // the one way to read the key back (for example to store a new wallet)
 ```
 
-`Cx3Wallet.createRandom()` makes a new key in memory only: call `exportPrivateKey()` and store it safely, or the wallet is gone when the process ends. `provider.clearAccessToken()` forgets the held access token, so the next request asks for a new one. Since 0.3.10 there is no `wallet._privateKey`, `provider.apiKey` or `provider._clientSecret` to read.
+`Cx3Wallet.createRandom()` makes a new key in memory only: call `exportPrivateKey()` and store it safely, or the wallet is gone when the process ends. `provider.clearAccessToken()` forgets the held access token, so the next request asks for a new one.
 
 ## Reading chain data
 
@@ -164,6 +160,8 @@ Supported ABI shapes:
 
 `provider.getContract(address)` loads the ABI the chain calls the contract with: shape 2 for contracts compiled to CX3JS, shape 3 for CX3WASM. Built-in chain standards (ABI inputs `["params"]`) take one named object: `await lp.transfer({ to, amount })`. A contract handle created with a provider instead of a wallet can only read; its writes throw `NO_SIGNER`.
 
+ABI methods are properties of a `Contract`, except the names JavaScript calls by itself (`then`, `catch`, `finally`, `toJSON`, `inspect`): a method with such a name is reached with `contract.call(name, params)` or `contract.send(name, params)`.
+
 ## Transactions and fees
 
 Gas is paid in CX3 to the validator that produces the block: gas used × gas price (devnet default 0.0001 CX3 per gas).
@@ -280,7 +278,7 @@ A private CX31, CX300, CX315 or CX3192 takes its CX3WebUI source as `sourceCode`
 
 Digests are UTF-8 strings, hashed with SHA-256 and signed with secp256k1, byte-identical to what the Green Chain node verifies. Each kind starts with its own prefix (signing domains), so a signature of one kind never verifies as another; `chainId` and `genesisHash` are the network's (`provider.getChainIdentity()`, fetched by the wallet methods themselves) and addresses are lower-case `0x` + 40 hex:
 
-- **Deploy:** `CX3_DEPLOY_V2|` + `JSON.stringify([chainId, genesisHash, owner, standard, name, symbol, decimals, initialSupply, contentHash, timestamp])`. `contentHash` is `Cx3Wallet.deployContentHash(request)`: the SHA-256 of the code, the constructor arguments, the target and the template switches of the request, so the signature is good for that content only. `deployContract` computes it, signs it and sends it. `signDeploy` without a `contentHash` signs the older `CX3_DEPLOY_V1` (the same list without it), which the network still accepts.
+- **Deploy:** `CX3_DEPLOY_V2|` + `JSON.stringify([chainId, genesisHash, owner, standard, name, symbol, decimals, initialSupply, contentHash, timestamp])`. `contentHash` is `Cx3Wallet.deployContentHash(request)`: the SHA-256 of the code, the constructor arguments, the target and the template switches of the request, so the signature is good for that content only. `deployContract` computes it, signs it and sends it.
 - **Contract send:** `CX3_CALL_V1|` + `JSON.stringify([chainId, genesisHash, contractAddress, method, params, fromAddress, timestamp])`. The chain checks this signature again inside the relayed transaction: a call runs as your wallet only with it.
 - **Owner action:** `CX3_OWNER_V1|` + `JSON.stringify([chainId, genesisHash, action, address, owner, timestamp])`
 - **Site message:** `0x19` + `"CX3 Signed Message:\n"` + UTF-8 length + message (`signPersonalMessage`), the way the CX3Wallet extension and app sign `cx3_sign_message`
@@ -288,7 +286,30 @@ Digests are UTF-8 strings, hashed with SHA-256 and signed with secp256k1, byte-i
 
 BigInt values in params are converted to decimal strings before signing, and exactly those params are sent. Deploy, contract-send and owner signatures carry a timestamp and are accepted within ±5 minutes of the gateway's clock. A native transfer is admitted only within 60 seconds after its timestamp (the pool drops it after 60 seconds), and a block takes it only within 10 minutes of its timestamp. The genesis hash ties a native transfer to one network and one genesis: after a chain reset, a transfer signed before it no longer verifies. An address is `0x` + the last 20 bytes of `sha256(uncompressedPublicKey)`.
 
-The same building blocks are exported: `buildDeployDigest`, `buildSendDigest`, `buildOwnerActionDigest` (each takes the identity as its last argument), `buildTransferPayload`, `personalMessageBytes`, `signMessage` (signs a digest as given), `signPersonalMessage`, `privateKeyToAddress` and `createPrivateKey`.
+The same building blocks are exported: `buildDeployDigest`, `buildSendDigest`, `buildOwnerActionDigest` (each takes the identity as its last argument), `buildTransferPayload`, `personalMessageBytes`, `signMessage` (signs a digest as given), `signPersonalMessage`, `privateKeyToAddress`, `publicKeyToAddress` and `createPrivateKey`.
+
+`wallet.signPersonalMessage(text)` is for any text that comes from outside (a login challenge, a user's message). `wallet.signMessage` signs a text as it is and refuses one the chain would accept as a transfer, contract call, deploy or owner action (`SIGN_REFUSED_TRANSACTION_PAYLOAD`), so a service that signs messages for its users cannot be made to sign a payment.
+
+### External signers
+
+`Cx3Wallet.fromSigner()` makes a wallet whose key stays outside your process: in an HSM, a cloud KMS, a hardware wallet or a custody service. You give the public key and a `sign` function; everything else (`transferNative`, contract sends, deploys, `signPersonalMessage`) works as with a local key.
+
+```javascript
+const wallet = Cx3Wallet.fromSigner({
+  publicKey: process.env.CX3_PUBLIC_KEY,   // compressed (33 bytes) or uncompressed (65 bytes), hex or bytes
+  async sign(hash, info) {
+    // hash: the 32-byte SHA-256 the chain verifies (Uint8Array)
+    // info.kind: "transaction" | "personalMessage" | "message"; info.payload: what the hash is of
+    return myKms.signSecp256k1(hash);      // r || s (64 bytes, hex or bytes) or { r, s }
+  }
+}, provider);
+
+await wallet.transferNative("0xRecipient…", 1.5);
+```
+
+- `info.payload` is the exact text being signed (the typed digest or the transfer's JSON), so the signer can show it or check it against a policy before it signs.
+- The SDK checks every answer against the wallet's public key before it is used: a signature of another key or over another hash throws `SIGNER_BAD_SIGNATURE` and nothing is sent. A signature with a high `s` is normalized to the low form the chain expects.
+- An error thrown by `sign` surfaces as `SIGNER_FAILED`. `wallet.external` is `true`, and `exportPrivateKey()` throws `NO_PRIVATE_KEY`: there is no key to export.
 
 ## Error handling
 
@@ -307,7 +328,7 @@ try {
 
 | Code | Meaning |
 |------|---------|
-| `CREDENTIALS_REQUIRED` | No application, API key or `devNode` was given |
+| `CREDENTIALS_REQUIRED` | No application or `devNode` was given |
 | `INVALID_CLIENT_CREDENTIALS` | The client ID or secret is not in the `cx3app_…` / `cx3sec_…` format |
 | `invalid_client` | The token endpoint refused the application (wrong secret, or revoked) |
 | `insufficient_scope`, `ROUTE_NOT_ALLOWED` | The route needs another scope, or is not open to applications (403) |
@@ -332,46 +353,31 @@ try {
 | `REPLAYED_REQUEST` | This signed request was already received or already ran (409); the answer does not say how it ended. Look it up with `provider.getRequest(err.body.requestId, wallet.address)` and never sign it again |
 | `REQUEST_LOOKUP_UNAVAILABLE` | `getRequest` could not ask the chain (503): try again later, do not sign again |
 | `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 |
+| `INVALID_SIGNER`, `INVALID_PUBLIC_KEY` | `Cx3Wallet.fromSigner` was given no `sign` function, or a public key that is not a secp256k1 point |
+| `SIGNER_FAILED`, `SIGNER_BAD_SIGNATURE` | An external signer threw, or returned a signature that is not this wallet's over this hash; nothing is sent |
+| `NO_PRIVATE_KEY` | `exportPrivateKey()` on a wallet that signs with an external signer |
 | `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.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.
+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 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 (not read with `devNode: true`) |
-| `CX3_API_KEY` | Legacy wallet API key |
 | `CX3_NODE_URL` | Gateway URL for `getDefaultProvider()` |
 
 ## TypeScript
 
 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. 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.
-- **Typed digests.** Contract sends, deploys and owner actions sign `CX3_CALL_V1` / `CX3_DEPLOY_V1` / `CX3_OWNER_V1` digests bound to the network (see Signing); the `|`-joined digests of 0.2.x are refused. `signSend`, `signDeploy` and `signOwnerAction` take an optional `{ chainId, genesisHash }`, else they ask the provider (kept for a minute). The `build*Digest` helpers need the identity as their last argument.
-- **Site messages.** `signPersonalMessage` signs the way the wallets sign `cx3_sign_message` (with the `0x19` prefix). Use it for any text that comes from outside (a login challenge, a user's message). `wallet.signMessage` signs a text as it is, without the prefix, and refuses a text the chain would accept as a transfer, contract call, deploy or owner action (`SIGN_REFUSED_TRANSACTION_PAYLOAD`), so a service that signs messages for its users cannot be made to sign a payment. The exported `signMessage(message, privateKey)` function is the low-level form without that check.
-- **Contract method names.** ABI methods are properties of a `Contract`, except the names JavaScript calls by itself (`then`, `catch`, `finally`, `toJSON`, `inspect`): a contract with such a method is reached with `contract.call(name, params)` or `contract.send(name, params)`.
-
-## Upgrading from 0.1.x
-
-CX3js is in beta (0.x), so a minor version may contain breaking changes. Version 0.2.0:
+## Versioning
 
-- **Credentials are required.** The provider talks to the CX3Api gateway as an OAuth2 application (or with a wallet API key) and throws `CREDENTIALS_REQUIRED` without one. A development node without authentication needs `devNode: true`; 0.1.x used node routes under `/api/v1` by default.
-- **HTTP Basic was removed.** The `auth` option throws `BASIC_AUTH_UNSUPPORTED`, and `headers` cannot carry `Authorization` or `X-Api-Key`.
-- **Node.js 20.19 or later** is required (`@noble/secp256k1` 3.x).
-- **Fixes:** BigInt params are signed and sent as decimal strings, and `transferNative` sends the gas fields it signs.
-- **New:** public chain reads (`getStatus`, `getTokens`, `getActivity`, `getDexPairs`, `getLpBalance`, `getWit`), private tokens and `isValidTokenSymbol`.
+CX3js is in beta (0.x): a minor version may contain breaking changes, a patch version does not. Version 0.4.0 adds external signers (`Cx3Wallet.fromSigner`), makes the OAuth2 application the SDK's only credential.
 
 ## Documentation
 

package/index.d.ts

@@ -29,8 +29,6 @@ export interface Cx3ProviderOptions {
   clientSecret?: string;
   /** ask for fewer scopes than the app has: "read", "write", "deploy" */
   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); 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 */
@@ -40,9 +38,7 @@ export interface Cx3ProviderOptions {
   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) */
-  auth?: never;
-  /** extra headers; Authorization and X-Api-Key are dropped (use clientId / clientSecret or apiKey) */
+  /** extra headers; Authorization and X-Api-Key are dropped (the application is the only credential) */
   headers?: Record<string, string>;
   fetch?: typeof fetch;
   timeoutMs?: number;
@@ -78,14 +74,13 @@ export class Cx3Provider {
   devNode: boolean;
   oauth: boolean;
   clientId: string;
-  apiKeyMode: "public" | "private" | "invalid";
-  authMode: "oauth" | "apiKey" | "devNode";
-  /** Throws CREDENTIALS_REQUIRED without clientId / clientSecret, apiKey or devNode */
+  authMode: "oauth" | "devNode";
+  /** Throws CREDENTIALS_REQUIRED without clientId / clientSecret or devNode */
   constructor(baseUrl: string, options?: Cx3ProviderOptions);
   /** Forget the held access token: the next request asks for a new one */
   clearAccessToken(): void;
   /** Where the provider points and how it signs in; never a credential (JSON.stringify and util.inspect use it) */
-  toJSON(): { baseUrl: string; authMode: "oauth" | "apiKey" | "devNode"; clientId?: string; scope?: string };
+  toJSON(): { baseUrl: string; authMode: "oauth" | "devNode"; clientId?: string; scope?: string };
   /** The current OAuth2 access token (renewed a minute before it expires); null without an OAuth2 app */
   getAccessToken(force?: boolean): Promise<string | null>;
   request(path: string, opts?: { method?: string; body?: unknown; query?: Record<string, string | number> }): Promise<any>;
@@ -117,6 +112,7 @@ export class Cx3Provider {
   getBalance(address: string): Promise<any>;
   getNonce(address: string): Promise<number>;
   getPendingNonce(address: string): Promise<any>;
+  /** Is this wallet the one the application belongs to: { ok: true }, or wallet_mismatch */
   bindApiKey(address: string): Promise<any>;
   /** The gateway lists a private token only when the app's wallet is its owner or an authorized wallet */
   listContracts(opts?: { limit?: number; offset?: number; viewer?: string; owner?: string; standard?: string; type?: string; live?: boolean }): Promise<any>;
@@ -136,14 +132,32 @@ export class Cx3Provider {
   getContract(address: string, abi?: unknown, signer?: Cx3Wallet | null): Promise<Contract>;
 }
 
+/** What an external signer is asked to sign: the kind of request and the exact text (or bytes) the hash is of */
+export interface Cx3SignInfo {
+  kind: "transaction" | "personalMessage" | "message";
+  payload: string | Uint8Array;
+}
+
+/** A key kept outside the process (HSM, KMS, hardware wallet, custody service) */
+export interface Cx3Signer {
+  /** secp256k1 public key, compressed (33 bytes) or uncompressed (65 bytes), hex or bytes */
+  publicKey: string | Uint8Array;
+  /** Signs the 32-byte SHA-256 `hash`; returns r || s (64 bytes, hex or bytes) or { r, s } (hex) */
+  sign(hash: Uint8Array, info: Cx3SignInfo): Promise<string | Uint8Array | { r: string; s: string }> | string | Uint8Array | { r: string; s: string };
+}
+
 export class Cx3Wallet {
   address: string;
   publicKey: string;
   provider: Cx3Provider | null;
+  /** true for a wallet made with fromSigner (no private key in this process) */
+  external: boolean;
   constructor(privateKey: string | Uint8Array | Buffer, provider?: Cx3Provider | null);
   static createRandom(provider?: Cx3Provider | null): Cx3Wallet;
+  /** A wallet that signs through `signer`; every answer is checked against the public key (SIGNER_BAD_SIGNATURE) */
+  static fromSigner(signer: Cx3Signer, provider?: Cx3Provider | null): Cx3Wallet;
   connect(provider: Cx3Provider): Cx3Wallet;
-  /** The private key as given to the constructor; the wallet shows it nowhere else (not in JSON, logs or a spread) */
+  /** The private key as given to the constructor; the wallet shows it nowhere else (not in JSON, logs or a spread). Throws NO_PRIVATE_KEY on an external-signer wallet */
   exportPrivateKey(): string | Uint8Array | Buffer;
   /** Address and public key only (JSON.stringify and util.inspect use it) */
   toJSON(): { address: string; publicKey: string };
@@ -295,7 +309,6 @@ export class TransactionResponse {
 export function getDefaultProvider(options?: Cx3ProviderOptions & { url?: string }): Cx3Provider;
 export function readCallValue(response: any): unknown;
 export function normalizeAddress(addr: string): string;
-export function walletApiKeyMode(key?: string | null): "public" | "private" | "invalid";
 /** BigInt → decimal string, recursively (params are signed and sent in this form) */
 export function toJsonSafe<T>(value: T): unknown;
 export function ensure0x(hex: string): string;
@@ -317,6 +330,8 @@ export function signPersonalMessage(message: string, privateKey: string | Uint8A
 export function buildTransferPayload(fields: object): string;
 export function signMessage(message: string | Uint8Array, privateKey: string | Uint8Array | Buffer): Promise<any>;
 export function privateKeyToAddress(privateKey: string | Uint8Array | Buffer): string;
+/** The address of a secp256k1 public key (compressed or uncompressed, hex or bytes) */
+export function publicKeyToAddress(publicKey: string | Uint8Array | Buffer): string;
 export function createPrivateKey(): string;
 export function normalizeAbi(abi: unknown): Record<string, any>;
 export function argsToParams(inputs: any[], args: any[]): object;

package/index.js

@@ -15,7 +15,6 @@ const {
     normalizeAddress,
     ensure0x,
     strip0x,
-    walletApiKeyMode,
     toJsonSafe
 } = require("./src/utils");
 const {
@@ -30,11 +29,12 @@ const {
     signMessage,
     signPersonalMessage,
     privateKeyToAddress,
+    publicKeyToAddress,
     createPrivateKey
 } = require("./src/crypto");
 const { normalizeAbi, argsToParams } = require("./src/abi");
 
-const VERSION = "0.3.11";
+const VERSION = "0.4.0";
 
 /**
  * Convenience: provider from `options.url` or env `CX3_NODE_URL` — the CX3Api gateway
@@ -63,7 +63,6 @@ module.exports = {
     normalizeAddress,
     ensure0x,
     strip0x,
-    walletApiKeyMode,
     toJsonSafe,
     buildDeployDigest,
     deployContentText,
@@ -74,6 +73,7 @@ module.exports = {
     signMessage,
     signPersonalMessage,
     privateKeyToAddress,
+    publicKeyToAddress,
     createPrivateKey,
     normalizeAbi,
     argsToParams,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@carbonx3/cx3.js",
-  "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",
+  "version": "0.4.0",
+  "description": "Official Node.js SDK (CX3js) for CarbonX3 Green Chain: OAuth2 app access, local or external secp256k1 signing, ABI-bound contracts and token deploys over REST + JSON",
   "homepage": "https://cx3script.com",
   "publishConfig": {
     "access": "public"

package/src/crypto.js

@@ -73,6 +73,91 @@ async function signMessage(message, privateKeyInput) {
     };
 }
 
+/** secp256k1 group order: a signature's s is kept in the lower half (the form the chain and the wallets produce). */
+const CURVE_N = 0xfffffffffffffffffffffffffffffffebaaedce6af48a03bbfd25e8cd0364141n;
+
+function bytesOf(input, what, code) {
+    if (input instanceof Uint8Array || Buffer.isBuffer(input)) return Buffer.from(input);
+    const hex = strip0x(String(input == null ? "" : input)).toLowerCase();
+    if (!hex || hex.length % 2 || !/^[0-9a-f]+$/.test(hex)) throw new Cx3Error(`Invalid ${what}`, code);
+    return Buffer.from(hex, "hex");
+}
+
+/** Both forms of a public key given compressed (33 bytes) or uncompressed (65 bytes), hex or bytes. */
+function publicKeyForms(input) {
+    const bytes = bytesOf(input, "public key", "INVALID_PUBLIC_KEY");
+    if (bytes.length !== 33 && bytes.length !== 65) throw new Cx3Error("Invalid public key length", "INVALID_PUBLIC_KEY");
+    let point;
+    try {
+        point = secp.Point.fromBytes(bytes);
+        point.assertValidity();
+    } catch (_) {
+        throw new Cx3Error("Invalid public key", "INVALID_PUBLIC_KEY");
+    }
+    return { compressed: Buffer.from(point.toBytes(true)), uncompressed: Buffer.from(point.toBytes(false)) };
+}
+
+function publicKeyToAddress(publicKeyInput) {
+    return ensure0x(sha256(publicKeyForms(publicKeyInput).uncompressed).slice(-20).toString("hex"));
+}
+
+/** What a signer returned, as 64 bytes r || s with s in the lower half: 64 bytes (hex or bytes) or { r, s } (hex). */
+function compactSignature(out) {
+    let bytes;
+    if (out && typeof out === "object" && !(out instanceof Uint8Array) && out.r != null && out.s != null) {
+        const part = (v) => strip0x(String(v)).toLowerCase().padStart(64, "0");
+        bytes = bytesOf(part(out.r) + part(out.s), "signature", "SIGNER_BAD_SIGNATURE");
+    } else {
+        bytes = bytesOf(out, "signature", "SIGNER_BAD_SIGNATURE");
+    }
+    if (bytes.length !== 64) throw new Cx3Error("The signer must return 64 bytes (r || s)", "SIGNER_BAD_SIGNATURE");
+    const r = BigInt("0x" + bytes.subarray(0, 32).toString("hex"));
+    let s = BigInt("0x" + bytes.subarray(32).toString("hex"));
+    if (r <= 0n || r >= CURVE_N || s <= 0n || s >= CURVE_N) throw new Cx3Error("Signature out of range", "SIGNER_BAD_SIGNATURE");
+    if (s > CURVE_N / 2n) s = CURVE_N - s;
+    return Buffer.from(r.toString(16).padStart(64, "0") + s.toString(16).padStart(64, "0"), "hex");
+}
+
+/**
+ * signMessage() with a signer that keeps the key elsewhere (an HSM, a KMS, a hardware wallet, a custody
+ * service). `signer.sign(hash, info)` gets the 32-byte sha256 the chain verifies and what it is the hash
+ * of; the answer is checked against the wallet's public key before anything is sent with it.
+ */
+async function signWithSigner(message, signer, kind) {
+    const msgBytes = typeof message === "string" ? Buffer.from(message, "utf8") : Buffer.from(message);
+    const msgHash = sha256(msgBytes);
+    let out;
+    try {
+        out = await signer.sign(new Uint8Array(msgHash), { kind, payload: typeof message === "string" ? message : new Uint8Array(msgBytes) });
+    } catch (e) {
+        if (e instanceof Cx3Error) throw e;
+        throw new Cx3Error("The signer did not sign: " + String((e && e.message) || e).slice(0, 200), "SIGNER_FAILED");
+    }
+    const compact = compactSignature(out);
+    let recovery = -1;
+    for (const bit of [0, 1]) {
+        try {
+            const got = secp.recoverPublicKey(Buffer.concat([Buffer.from([bit]), compact]), msgHash, { prehash: false, isCompressed: false });
+            if (Buffer.from(got).equals(signer.uncompressed)) { recovery = bit; break; }
+        } catch (_) { /* not this bit */ }
+    }
+    // a signature of another key, or over another hash, never leaves the SDK
+    if (recovery < 0) throw new Cx3Error("The signer's signature is not this wallet's", "SIGNER_BAD_SIGNATURE");
+    const signature = compact.toString("hex");
+    const publicKey = signer.compressed.toString("hex");
+    return {
+        signature,
+        r: signature,
+        s: null,
+        v: recovery + 27,
+        publicKey,
+        senderPublicKey: publicKey,
+        publicKeyUncompressed: signer.uncompressed.toString("hex"),
+        hash: ensure0x(msgHash.toString("hex")),
+        derivedAddress: ensure0x(sha256(signer.uncompressed).slice(-20).toString("hex"))
+    };
+}
+
 /**
  * Sign a site message the way the CX3Wallet extension and app do (cx3_sign_message):
  * sha256(0x19 "CX3 Signed Message:\n" + UTF-8 length + message). Such a signature never verifies as
@@ -103,5 +188,8 @@ module.exports = {
     privateKeyToAddress,
     signMessage,
     signPersonalMessage,
+    signWithSigner,
+    publicKeyForms,
+    publicKeyToAddress,
     createPrivateKey
 };

package/src/provider.js

@@ -5,7 +5,7 @@
 "use strict";
 
 const { Cx3Error, Cx3HttpError, Cx3TxError } = require("./errors");
-const { readCallValue, sleep, normalizeAddress, walletApiKeyMode, toJsonSafe } = require("./utils");
+const { readCallValue, sleep, normalizeAddress, toJsonSafe } = require("./utils");
 const { Contract } = require("./contract");
 const { normalizeGenesisHash } = require("./digest");
 
@@ -14,12 +14,11 @@ const { normalizeGenesisHash } = require("./digest");
  *
  * Apps sign in to the CX3Api gateway with an OAuth2 client (`clientId` + `clientSecret`, created in
  * CX3WebUI → Settings → API → Applications): the provider gets a one-hour access token at
- * `POST /oauth/token`, sends it as `Authorization: Bearer`, and renews it before it expires. A wallet
- * API key (`cx3wk_…`, `X-Api-Key`) still works during the move to applications. Without one of the
- * two the provider refuses to start (CREDENTIALS_REQUIRED): no app development without credentials.
+ * `POST /oauth/token`, sends it as `Authorization: Bearer`, and renews it before it expires. Without
+ * an application the provider refuses to start (CREDENTIALS_REQUIRED).
  * Gateway routes: `/contracts/:address/call`, `/contracts/:address/send`, `/wallet/...`, …
- * `devNode: true` talks to a development node that runs without auth (`/api/v1`). The SDK never sends
- * HTTP Basic (the nodes' internal login). Never talks to CX3VM directly.
+ * `devNode: true` talks to a development node that runs without auth (`/api/v1`). Never talks to
+ * CX3VM directly.
  */
 
 // node route → CX3Api route (the gateway forwards the same body to the node)
@@ -56,7 +55,7 @@ function boolVerdict(v) {
     return null;
 }
 
-// credentials come only from clientId / clientSecret or apiKey, never from an extra header
+// credentials come only from clientId / clientSecret, never from an extra header
 function withoutCredentialHeaders(headers) {
     const out = {};
     for (const [k, v] of Object.entries(headers || {})) {
@@ -90,7 +89,6 @@ class Cx3Provider {
     // Credentials live in private fields: JSON.stringify, util.inspect, console.log, Object.keys and a
     // spread of the provider (or of anything that holds it) never show them.
     #clientSecret = "";
-    #apiKey = "";
     #token = null;          // { value, refreshAt, scope }
 
     /**
@@ -99,7 +97,6 @@ class Cx3Provider {
      * @param {string} [options.clientId]  OAuth2 client id (`cx3app_…`; env CX3_CLIENT_ID)
      * @param {string} [options.clientSecret]  OAuth2 client secret (`cx3sec_…`; env CX3_CLIENT_SECRET)
      * @param {string|string[]} [options.scope]  ask for fewer scopes than the app has ("read", "write", "deploy")
-     * @param {string} [options.apiKey]  wallet API key (`cx3wk_…`; env CX3_API_KEY), until apps move to OAuth2
      * @param {boolean} [options.devNode]  a development node without auth (`/api/v1`), no credentials
      * @param {string} [options.apiPrefix] ("" on the gateway, "/api/v1" on a development node)
      * @param {Record<string,string>} [options.headers] Extra headers (Authorization / X-Api-Key are dropped)
@@ -109,32 +106,24 @@ class Cx3Provider {
     constructor(baseUrl, options = {}) {
         if (!baseUrl) throw new Cx3Error("Cx3Provider requires baseUrl (CX3_NODE_URL)", "NO_BASE_URL");
         this.baseUrl = String(baseUrl).replace(/\/$/, "");
-        if (options.auth != null) {
-            throw new Cx3Error(
-                "HTTP Basic is the nodes' internal login and is not sent by the SDK: create an application in CX3WebUI (Settings → API) and pass clientId / clientSecret",
-                "BASIC_AUTH_UNSUPPORTED"
-            );
-        }
         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.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");
         }
-        const hasKey = walletApiKeyMode(this.#apiKey) !== "public";
-        if (!this.oauth && !hasKey && !this.devNode) {
+        if (!this.oauth && !this.devNode) {
             throw new Cx3Error(
                 "App credentials required: create an application in CX3WebUI (Settings → API → Applications) and pass clientId / clientSecret (or set CX3_CLIENT_ID / CX3_CLIENT_SECRET)",
                 "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)) {
+        if (this.oauth && 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"
@@ -164,14 +153,9 @@ class Cx3Provider {
         }
     }
 
-    get apiKeyMode() {
-        return walletApiKeyMode(this.#apiKey);
-    }
-
-    /** "oauth" | "apiKey" | "devNode" */
+    /** "oauth" | "devNode" */
     get authMode() {
-        if (this.devNode && !this.oauth && walletApiKeyMode(this.#apiKey) === "public") return "devNode";
-        return this.oauth ? "oauth" : "apiKey";
+        return this.oauth ? "oauth" : "devNode";
     }
 
     /**
@@ -223,11 +207,7 @@ class Cx3Provider {
             "Content-Type": "application/json",
             ...this.extraHeaders
         };
-        if (this.oauth) {
-            headers.Authorization = `Bearer ${await this.getAccessToken(forceToken)}`;
-        } else if (/^cx3wk_[a-f0-9]{48}$/i.test(this.#apiKey)) {
-            headers["X-Api-Key"] = this.#apiKey;
-        }
+        if (this.oauth) headers.Authorization = `Bearer ${await this.getAccessToken(forceToken)}`;
         return headers;
     }
 
@@ -252,9 +232,6 @@ class Cx3Provider {
      * @param {{ method?: string, body?: object, query?: Record<string,string|number> }} [opts]
      */
     async request(path, opts = {}) {
-        if (!this.oauth && this.apiKeyMode === "invalid") {
-            throw new Cx3Error("api_key_required", "api_key_required");
-        }
         const method = opts.method || "GET";
         let route = path.startsWith("/") ? path : `/${path}`;
         if (this.gateway) route = gatewayPath(route, opts.body);
@@ -564,34 +541,14 @@ class Cx3Provider {
     }
 
     /**
-     * Check that this wallet is the one the credentials belong to (an app and a wallet API key are
-     * both bound to one wallet): `{ ok: true }`, or `wallet_mismatch`.
-     * OAuth2 app and cx3wk_ key → GET `/wallet/api-key/bind` (the gateway route; it has no `/whoami`);
-     * a cx3wk_ key falls back to `/whoami` on 404 (a same-origin proxy that only forwards that).
-     * A development node has no credentials: `{ ok: true, devNode: true }`.
+     * Check that this wallet is the one the application belongs to: `{ ok: true }`, or `wallet_mismatch`.
+     * A development node has no application: `{ ok: true, devNode: true }`.
      */
     async bindApiKey(address) {
         const addr = normalizeAddress(address);
         if (!addr) throw new Cx3Error("address required", "NO_ADDRESS");
-        const query = { address: addr };
-        if (this.oauth) return this._rejectEnvelope(await this.request("/wallet/api-key/bind", { query }));
-        const mode = this.apiKeyMode;
-        if (mode === "invalid") {
-            throw new Cx3Error("api_key_required", "api_key_required");
-        }
-        if (mode === "public") {
-            return { ok: true, devNode: true };
-        }
-        try {
-            const json = await this.request("/wallet/api-key/bind", { query });
-            return this._rejectEnvelope(json);
-        } catch (e) {
-            if (e && e.status === 404) {
-                const json = await this.request("/whoami", { query });
-                return this._rejectEnvelope(json);
-            }
-            throw e;
-        }
+        if (!this.oauth) return { ok: true, devNode: true };
+        return this._rejectEnvelope(await this.request("/wallet/api-key/bind", { query: { address: addr } }));
     }
 
     /**

package/src/utils.js

@@ -70,17 +70,6 @@ function toJsonSafe(value) {
     return value;
 }
 
-/**
- * Same rules as DappsExamples/CX3AssetDashboard `cx3_dapp_key_mode`:
- * empty → public (any wallet); valid cx3wk_ → private (that wallet); else invalid.
- */
-function walletApiKeyMode(key) {
-    const n = String(key == null ? "" : key).trim();
-    if (!n) return "public";
-    if (/^cx3wk_[a-f0-9]{48}$/i.test(n)) return "private";
-    return "invalid";
-}
-
 module.exports = {
     readCallValue,
     strip0x,
@@ -88,6 +77,5 @@ module.exports = {
     normalizeAddress,
     sleep,
     isPlainObject,
-    toJsonSafe,
-    walletApiKeyMode
+    toJsonSafe
 };

package/src/wallet.js

@@ -9,12 +9,14 @@ const {
     privateKeyToPublicKey,
     signMessage,
     signPersonalMessage,
+    signWithSigner,
+    publicKeyForms,
     createPrivateKey,
     sha256
 } = require("./crypto");
 const { normalizeAddress, toJsonSafe } = require("./utils");
 const { Cx3Error } = require("./errors");
-const { buildDeployDigest, buildSendDigest, buildOwnerActionDigest, buildTransferPayload, stripNativeAddress, deployContentText } = require("./digest");
+const { buildDeployDigest, buildSendDigest, buildOwnerActionDigest, buildTransferPayload, stripNativeAddress, deployContentText, personalMessageBytes } = require("./digest");
 const { TransactionResponse } = require("./transaction");
 
 /** Green Chain deploy rule: a token symbol is capital letters A-Z and digits 0-9 only. */
@@ -84,36 +86,69 @@ function withDeployWait(result, provider) {
     return result;
 }
 
+/** A key that lives outside this process (Cx3Wallet.fromSigner): its public key and its sign function. */
+class ExternalSigner {
+    constructor(spec) {
+        if (!spec || typeof spec.sign !== "function") throw new Cx3Error("signer.sign must be a function", "INVALID_SIGNER");
+        const forms = publicKeyForms(spec.publicKey);
+        this.compressed = forms.compressed;
+        this.uncompressed = forms.uncompressed;
+        this.sign = (hash, info) => spec.sign(hash, info);
+    }
+}
+
 /**
- * Local secp256k1 wallet for Green Chain digests.
+ * secp256k1 wallet for Green Chain digests: a private key in this process, or a signer that keeps the
+ * key elsewhere (Cx3Wallet.fromSigner).
  */
 class Cx3Wallet {
     // The key is a private field: JSON.stringify, util.inspect, console.log, Object.keys and a spread of
     // the wallet (or of a result that holds it) never show it. It leaves only through exportPrivateKey().
-    #privateKey;
+    #privateKey = null;
+    #signer = null;
 
     /**
      * @param {string|Uint8Array|Buffer} privateKey
      * @param {import('./provider').Cx3Provider|null} [provider]
      */
     constructor(privateKey, provider = null) {
+        this.provider = provider;
+        if (privateKey instanceof ExternalSigner) {
+            this.#signer = privateKey;
+            this.address = normalizeAddress("0x" + sha256(privateKey.uncompressed).slice(-20).toString("hex"));
+            this.publicKey = privateKey.compressed.toString("hex");
+            this.external = true;
+            return;
+        }
         if (!privateKey) throw new Cx3Error("privateKey required", "NO_PRIVATE_KEY");
         this.#privateKey = privateKey;
-        this.provider = provider;
         this.address = privateKeyToAddress(privateKey);
         this.publicKey = privateKeyToPublicKey(privateKey, true).toString("hex");
+        this.external = false;
     }
 
     static createRandom(provider = null) {
         return new Cx3Wallet(createPrivateKey(), provider);
     }
 
+    /**
+     * A wallet whose key never enters this process (an HSM, a KMS, a hardware wallet, a custody service).
+     * `signer.publicKey`: the key's public key, compressed or uncompressed (hex or bytes).
+     * `signer.sign(hash, info)`: gets the 32-byte sha256 to sign and `info` ({ kind, payload }: what the
+     * hash is of, to show or to check a policy against) and returns r || s (64 bytes, hex or bytes) or
+     * { r, s }. The SDK checks the answer against the public key (SIGNER_BAD_SIGNATURE) before using it.
+     */
+    static fromSigner(signer, provider = null) {
+        return new Cx3Wallet(new ExternalSigner(signer), provider);
+    }
+
     connect(provider) {
-        return new Cx3Wallet(this.#privateKey, provider);
+        return new Cx3Wallet(this.#signer || this.#privateKey, provider);
     }
 
     /** The private key as given to the constructor (a createRandom() wallet: the only way to save it). */
     exportPrivateKey() {
+        if (this.#signer) throw new Cx3Error("This wallet signs with an external signer and holds no private key", "NO_PRIVATE_KEY");
         return this.#privateKey;
     }
 
@@ -141,16 +176,19 @@ class Cx3Wallet {
         if (isChainPayload(message)) {
             throw new Cx3Error("This text is a chain transaction or call, not a message", "SIGN_REFUSED_TRANSACTION_PAYLOAD");
         }
+        if (this.#signer) return signWithSigner(message, this.#signer, "message");
         return signMessage(message, this.#privateKey);
     }
 
     /** The wallet's own typed digests and transfer payloads. */
     #signPayload(payload) {
+        if (this.#signer) return signWithSigner(payload, this.#signer, "transaction");
         return signMessage(payload, this.#privateKey);
     }
 
     /** Sign a site message the way the CX3Wallet extension and app do (with the site-message prefix). */
     async signPersonalMessage(message) {
+        if (this.#signer) return signWithSigner(personalMessageBytes(message), this.#signer, "personalMessage");
         return signPersonalMessage(message, this.#privateKey);
     }
 
@@ -475,6 +513,7 @@ class Cx3Wallet {
         return new TransactionResponse(result, this.provider, opts);
     }
 
+    /** Is this wallet the one the provider's application belongs to: `{ ok: true }`, or `wallet_mismatch`. */
     async bindApiKey(address) {
         if (!this.provider) throw new Cx3Error("Wallet has no provider", "NO_PROVIDER");
         return this.provider.bindApiKey(address || this.address);