@quantovainc/qcore 0.1.29 → 0.1.31

package/README.md

@@ -91,7 +91,7 @@ Quantova is post quantum from the ground. There is no elliptic curve anywhere in
 
 3. The address. A Quantova address is the Bech32m Q1 string that renders the SHA3 256 hash of the scheme byte together with the whole module lattice public key of one thousand nine hundred fifty two bytes. The entire public key is bound into the address. Nothing is truncated to a twenty byte hash and there is no key recovery from a signature, so one address names exactly one post quantum key.
 
-4. The transaction. A transaction body carries the sender, the nonce, the meter limit, the fee, and the call. The bytes a signature stands over are the SHA3 256 hash of the canonical body followed by a fixed Quantova transaction domain tag, so a transaction signature can never be replayed as another kind of signed message. QCore.js assembles the body, signs the digest inside the compiled core, and returns the wrapper bytes and the transaction id ready for the gateway.
+4. The transaction. A transaction body carries the sender, the nonce, the meter limit, the fee, and the call. The bytes a signature stands over are the SHA3 256 hash of the canonical body, and a fixed Quantova transaction domain tag is bound in as the post quantum signing context, so a transaction signature can never be replayed as another kind of signed message. QCore.js assembles the body, signs the digest inside the compiled core, and returns the wrapper bytes and the transaction id ready for the gateway.
 
 5. The payable call. `core.signPayableCall` carries a native value and an explicit chain id alongside the sender, the nonce, the meter limit, the fee, and the call, so a call to a contract can move value in the same signed body a transfer does, and the same signature can be pinned to one network. The sender and the target never enter that signature as the rendered Q1 string, since a display convention can change over time. Each is parsed back to its raw thirty two byte payload first, and that payload, never the string, is what the preimage carries, so the signature stays bound to the account and never to how an address happened to be printed.
 

package/index.d.ts

@@ -162,6 +162,8 @@ export class Network {
 export interface ClientOptions {
   acknowledgeMainnet?: boolean;
   network?: Network;
+  /** Bind signatures to this chain name; a gateway reporting any other is refused. */
+  expectedChainId?: string;
 }
 
 export class Client {
@@ -228,6 +230,7 @@ export class Client {
     ownerIndex: number,
     meterLimit: number | bigint,
     maxFeeQuon: string | bigint,
+    expectedOrderNonce?: bigint | number | string
   ): Promise<SignedOrderResult>;
 }
 

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@quantovainc/qcore",
-  "version": "0.1.29",
+  "version": "0.1.31",
   "description": "Quantova's post quantum client core for JavaScript. Signs with ML-DSA-65 and builds Q1 addresses.",
   "scripts": {
     "build": "bash scripts/build.sh",
-    "test": "node test-conformance.js && node test-sign-validate.js && node test-transport.js && node test-fee-cap.js && node test-network.js"
+    "test": "node test-types.js && node test-conformance.js && node test-order-nonce.js && node test-chain-binding.js && node test-sign-validate.js && node test-transport.js && node test-fee-cap.js && node test-network.js"
   },
   "keywords": [
     "post-quantum",
@@ -83,5 +83,8 @@
   ],
   "engines": {
     "node": ">=18"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0"
   }
 }

package/pkg/package.json

@@ -2,7 +2,7 @@
   "name": "qcore-js",
   "type": "module",
   "description": "The JavaScript binding for the Quantova client core, generated over QCore with wasm-bindgen. The core does the key derivation, the post quantum signing, and the wire, the page does the fetch.",
-  "version": "0.1.29",
+  "version": "0.1.31",
   "license": "Apache-2.0 OR MIT",
   "repository": {
     "type": "git",
@@ -13,8 +13,8 @@
     "qcore_js.js",
     "qcore_js_bg.js",
     "qcore_js.d.ts",
-    "LICENSE-APACHE",
-    "LICENSE-MIT"
+    "LICENSE-MIT",
+    "LICENSE-APACHE"
   ],
   "main": "qcore_js.js",
   "types": "qcore_js.d.ts",

package/pkg-node/package.json

@@ -1,7 +1,7 @@
 {
   "name": "qcore-js",
   "description": "The JavaScript binding for the Quantova client core, generated over QCore with wasm-bindgen. The core does the key derivation, the post quantum signing, and the wire, the page does the fetch.",
-  "version": "0.1.29",
+  "version": "0.1.31",
   "license": "Apache-2.0 OR MIT",
   "repository": {
     "type": "git",
@@ -11,8 +11,8 @@
     "qcore_js_bg.wasm",
     "qcore_js.js",
     "qcore_js.d.ts",
-    "LICENSE-APACHE",
-    "LICENSE-MIT"
+    "LICENSE-MIT",
+    "LICENSE-APACHE"
   ],
   "main": "qcore_js.js",
   "types": "qcore_js.d.ts"

package/shared.js

@@ -198,6 +198,17 @@ function makeClient(core) {
         this.network = opts.network instanceof Network ? opts.network : Network.forUrl(base);
       }
       this.base = requireSafeTransport(base).replace(/\/$/, '');
+      // The chain name the gateway reports is hashed into the signature preimage of
+      // every signing path, so whoever names it decides which network a signature is
+      // valid on. `Network.forUrl` leaves chainId null, which is the default for
+      // `new Client(url)`, and the configured check is skipped when it is null, so by
+      // default the endpoint chose. Bind it with expectedChainId, or rely on the pin,
+      // which at least refuses a gateway that changes its mind mid session.
+      this.expectedChainId =
+        typeof opts.expectedChainId === 'string' && opts.expectedChainId.length > 0
+          ? opts.expectedChainId
+          : null;
+      this._pinnedChainName = null;
     }
 
     _guardMainnet() {
@@ -212,13 +223,25 @@ function makeClient(core) {
       if (!name) throw new Error('the gateway did not report a chain id to bind the signature to');
       if (typeof name !== 'string') throw new Error('the gateway reported a chain id that is not a string, refusing to bind a signature to it');
       const id = BigInt(core.chainIdFromName(name));
-      const configured = this.network && this.network.chainId;
+      const configured =
+        this.expectedChainId || (this.network && this.network.chainId) || null;
       if (configured && name !== configured) {
         throw new Error(`the gateway reports chain ${name} but this client is configured for ${configured}; refusing to sign a transaction that would be valid on a network you did not choose`);
       }
       if (!this.acknowledgeMainnet && this._isMainnetId(id)) {
         throw new Error(`the gateway reports the mainnet chain ${name}; refusing to sign a mainnet transaction without acknowledgeMainnet`);
       }
+      // Pin on first ACCEPTED use, after every refusal above. With nothing configured
+      // the endpoint names the chain, and the least this can do is refuse one that
+      // answers differently later in the same session, which is how a signature ends
+      // up bound to a network the caller never chose while every earlier call looked
+      // entirely normal. Pinning a name we refused to sign for would be wrong: it was
+      // never a chain this client accepted.
+      if (this._pinnedChainName === null) {
+        this._pinnedChainName = name;
+      } else if (this._pinnedChainName !== name) {
+        throw new Error(`the gateway reported chain ${this._pinnedChainName} earlier and now reports ${name}; refusing to sign, the endpoint is not naming one network`);
+      }
       return id;
     }
 
@@ -252,7 +275,22 @@ function makeClient(core) {
 
     nodeInfo() { return this._call('node_info', '{}'); }
     head() { return this._call('head', '{}'); }
-    account(address) { return this._call('get_account', core.account_body(address)); }
+    async account(address) {
+      const acct = await this._call('get_account', core.account_body(address));
+      if (acct && acct.address != null && acct.address !== address) {
+        throw new Error(`the gateway answered for ${acct.address} when asked about ${address}, refusing to trust it`);
+      }
+      return acct;
+    }
+    _checkedNonce(reported, expected) {
+      const n = accountNonce(reported);
+      if (expected != null) {
+        const e = BigInt(expected);
+        if (n < e) throw new Error(`the gateway reported nonce ${n} below the expected ${e}; refusing so a replayed lower nonce cannot force a second payment`);
+        if (n > e + 16n) throw new Error(`the gateway reported nonce ${n} far above the expected ${e}; refusing`);
+      }
+      return n;
+    }
     transaction(txId) { return this._call('get_transaction', core.transaction_body(txId)); }
     block(height) { return this._call('get_block', core.block_by_height_body(BigInt(height))); }
     submit(txHex) { return this._call('submit_transaction', core.submit_body(txHex)); }
@@ -262,7 +300,7 @@ function makeClient(core) {
 
     address(seedHex, index) { return core.address(seedHex, accountIndex(index)); }
 
-    async transfer(seedHex, index, to, amount, maxFeeQuon) {
+    async transfer(seedHex, index, to, amount, maxFeeQuon, expectedNonce) {
       if (!core.valid_address(to)) throw new Error('the recipient is not a q1 address');
       checkAmount(amount);
       const ceiling = feeCeiling(maxFeeQuon);
@@ -277,8 +315,9 @@ function makeClient(core) {
       const from = core.address(seedHex, accountIndex(index));
       const acct = await this.account(from);
       if (!acct || acct.nonce == null) throw new Error('the gateway did not report a nonce');
+      const nonce = this._checkedNonce(acct.nonce, expectedNonce);
       const signed = JSON.parse(
-        core.sign_transfer(seedHex, accountIndex(index), to, String(amount), accountNonce(acct.nonce), String(fee), chainId)
+        core.sign_transfer(seedHex, accountIndex(index), to, String(amount), nonce, String(fee), chainId)
       );
       const outcome = await this.submit(signed.tx_hex);
       return { signed, outcome };
@@ -378,7 +417,7 @@ function makeClient(core) {
       return BigInt(core.storageValue(JSON.stringify(resp), core.scalarSlotKey(BigInt(slot))));
     }
 
-    async callSignedOrder(callerSeedHex, callerIndex, contract, selectorHex, orderSpec, ownerSeedHex, ownerIndex, meterLimit, maxFeeQuon) {
+    async callSignedOrder(callerSeedHex, callerIndex, contract, selectorHex, orderSpec, ownerSeedHex, ownerIndex, meterLimit, maxFeeQuon, expectedOrderNonce) {
       if (!core.valid_address(contract)) throw new Error('the contract is not a q1 address');
       const ceiling = feeCeiling(maxFeeQuon);
       const info = await this.nodeInfo();
@@ -390,7 +429,18 @@ function makeClient(core) {
         throw new Error(`the gateway fee ${fee} is above the maximum you allowed ${maxFeeQuon}, refusing to sign`);
       }
       const signer = core.orderSigner(ownerSeedHex, accountIndex(ownerIndex));
+      // The owner authorisation carries no deadline, so this nonce is the only thing
+      // that stops it being replayed. Reading it from the gateway hands the party the
+      // signature protects against the one term that expires it: answer with a future
+      // nonce and the reply is a valid order banked until the contract counter reaches
+      // it. Pass expectedOrderNonce to bind what you meant to sign; without it you are
+      // trusting the endpoint with the owner key.
       const nonce = await this.contractNonce(contract, signer);
+      if (expectedOrderNonce != null && BigInt(expectedOrderNonce) !== nonce) {
+        throw new Error(
+          `the gateway reported order nonce ${nonce} but you expected ${expectedOrderNonce}, refusing to sign`
+        );
+      }
       const order = JSON.parse(core.buildTypedOrderCall(
         chainId,
         contract,
@@ -410,7 +460,7 @@ function makeClient(core) {
         core.sign_call(callerSeedHex, accountIndex(callerIndex), contract, order.call_args, accountNonce(acct.nonce), BigInt(meterLimit), String(fee), chainId)
       );
       const outcome = await this.submit(signed.tx_hex);
-      return { order, signed, outcome };
+      return { order, signed, outcome, orderNonce: nonce };
     }
   };
 }