@mysten/sui 2.17.0 → 2.19.0

package/src/verify/verify.ts

@@ -13,24 +13,65 @@ import { MultiSigPublicKey } from '../multisig/publickey.js';
 import { ZkLoginPublicIdentifier } from '../zklogin/publickey.js';
 import type { ClientWithCoreApi } from '../client/core.js';
 
+/**
+ * Whether `signature` is a valid signature over `bytes` (and, if `options.address`
+ * is given, was produced by that address). Returns `false` for a malformed or
+ * cryptographically invalid signature, or one that doesn't match the address;
+ * only an *environmental* failure (e.g. a zkLogin JWK/epoch lookup) throws, so a
+ * network blip is never reported as an invalid signature.
+ */
+export async function isValidSignature(
+	bytes: Uint8Array,
+	signature: string,
+	options: { address?: string } = {},
+): Promise<boolean> {
+	const parsed = tryParseSignature(signature);
+	if (!parsed) return false;
+	if (!(await parsed.publicKey.verify(bytes, parsed.serializedSignature))) return false;
+	return options.address ? parsed.publicKey.verifyAddress(options.address) : true;
+}
+
+/** Like {@link isValidSignature}, for a personal message. */
+export async function isValidPersonalMessageSignature(
+	message: Uint8Array,
+	signature: string,
+	options: { client?: ClientWithCoreApi; address?: string } = {},
+): Promise<boolean> {
+	const parsed = tryParseSignature(signature, { client: options.client });
+	if (!parsed) return false;
+	if (!(await parsed.publicKey.verifyPersonalMessage(message, parsed.serializedSignature))) {
+		return false;
+	}
+	return options.address ? parsed.publicKey.verifyAddress(options.address) : true;
+}
+
+/** Like {@link isValidSignature}, for transaction bytes. */
+export async function isValidTransactionSignature(
+	transaction: Uint8Array,
+	signature: string,
+	options: { client?: ClientWithCoreApi; address?: string } = {},
+): Promise<boolean> {
+	const parsed = tryParseSignature(signature, { client: options.client });
+	if (!parsed) return false;
+	if (!(await parsed.publicKey.verifyTransaction(transaction, parsed.serializedSignature))) {
+		return false;
+	}
+	return options.address ? parsed.publicKey.verifyAddress(options.address) : true;
+}
+
 export async function verifySignature(
 	bytes: Uint8Array,
 	signature: string,
-	options?: {
-		address?: string;
-	},
+	options: { address?: string } = {},
 ): Promise<PublicKey> {
-	const parsedSignature = parseSignature(signature);
-
-	if (!(await parsedSignature.publicKey.verify(bytes, parsedSignature.serializedSignature))) {
+	const { publicKey } = parseSignature(signature);
+	if (!(await isValidSignature(bytes, signature))) {
 		throw new Error(`Signature is not valid for the provided data`);
 	}
-
-	if (options?.address && !parsedSignature.publicKey.verifyAddress(options.address)) {
+	if (options.address && !publicKey.verifyAddress(options.address)) {
 		throw new Error(`Signature is not valid for the provided address`);
 	}
-
-	return parsedSignature.publicKey;
+	return publicKey;
 }
 
 export async function verifyPersonalMessageSignature(
@@ -38,22 +79,14 @@ export async function verifyPersonalMessageSignature(
 	signature: string,
 	options: { client?: ClientWithCoreApi; address?: string } = {},
 ): Promise<PublicKey> {
-	const parsedSignature = parseSignature(signature, options);
-
-	if (
-		!(await parsedSignature.publicKey.verifyPersonalMessage(
-			message,
-			parsedSignature.serializedSignature,
-		))
-	) {
+	const { publicKey } = parseSignature(signature, options);
+	if (!(await isValidPersonalMessageSignature(message, signature, { client: options.client }))) {
 		throw new Error(`Signature is not valid for the provided message`);
 	}
-
-	if (options?.address && !parsedSignature.publicKey.verifyAddress(options.address)) {
+	if (options.address && !publicKey.verifyAddress(options.address)) {
 		throw new Error(`Signature is not valid for the provided address`);
 	}
-
-	return parsedSignature.publicKey;
+	return publicKey;
 }
 
 export async function verifyTransactionSignature(
@@ -61,22 +94,14 @@ export async function verifyTransactionSignature(
 	signature: string,
 	options: { client?: ClientWithCoreApi; address?: string } = {},
 ): Promise<PublicKey> {
-	const parsedSignature = parseSignature(signature, options);
-
-	if (
-		!(await parsedSignature.publicKey.verifyTransaction(
-			transaction,
-			parsedSignature.serializedSignature,
-		))
-	) {
+	const { publicKey } = parseSignature(signature, options);
+	if (!(await isValidTransactionSignature(transaction, signature, { client: options.client }))) {
 		throw new Error(`Signature is not valid for the provided Transaction`);
 	}
-
-	if (options?.address && !parsedSignature.publicKey.verifyAddress(options.address)) {
+	if (options.address && !publicKey.verifyAddress(options.address)) {
 		throw new Error(`Signature is not valid for the provided address`);
 	}
-
-	return parsedSignature.publicKey;
+	return publicKey;
 }
 
 function parseSignature(signature: string, options: { client?: ClientWithCoreApi } = {}) {
@@ -100,6 +125,15 @@ function parseSignature(signature: string, options: { client?: ClientWithCoreApi
 	};
 }
 
+/** {@link parseSignature}, returning `null` instead of throwing on a malformed signature. */
+function tryParseSignature(signature: string, options: { client?: ClientWithCoreApi } = {}) {
+	try {
+		return parseSignature(signature, options);
+	} catch {
+		return null;
+	}
+}
+
 export function publicKeyFromRawBytes(
 	signatureScheme: SignatureScheme,
 	bytes: Uint8Array,

package/src/version.ts

@@ -3,4 +3,4 @@
 
 // This file is generated by genversion.mjs. Do not edit it directly.
 
-export const PACKAGE_VERSION = '2.17.0';
+export const PACKAGE_VERSION = '2.19.0';

package/src/zklogin/jwt-utils.ts

@@ -116,6 +116,9 @@ export function extractClaimValue<R>(claim: Claim, claimName: string): R {
 	return value;
 }
 
+// TODO: root cause of the claim-escaping bug — jwtDecode resolves JSON escapes, but the
+// circuit derives the address seed from raw JWT bytes, so escaped claim values decode
+// differently here than the circuit hashes. Real fix: parse claims over raw bytes.
 export function decodeJwt(jwt: string): Omit<JwtPayload, 'iss' | 'aud' | 'sub'> & {
 	iss: string;
 	aud: string;

package/src/zklogin/utils.ts

@@ -87,6 +87,20 @@ export function hashASCIIStrToField(str: string, maxSize: number) {
 	return poseidonHash(packed);
 }
 
+// Reject claim inputs whose decoded form reveals a JSON escape ('"', '\', control char):
+// the circuit hashes raw JWT bytes, so an escaped value would derive a different address.
+function assertNoJsonEscape(value: string, label: string) {
+	for (let i = 0; i < value.length; i++) {
+		const c = value.charCodeAt(i);
+		if (c < 0x20 || c === 0x22 || c === 0x5c) {
+			throw new Error(
+				`zkLogin ${label} contains a JSON-escaped character (code ${c}); the circuit ` +
+					`hashes raw JWT bytes, so claim values with escapes are not supported`,
+			);
+		}
+	}
+}
+
 export function genAddressSeed(
 	salt: string | bigint,
 	name: string,
@@ -96,6 +110,9 @@ export function genAddressSeed(
 	max_value_length = MAX_KEY_CLAIM_VALUE_LENGTH,
 	max_aud_length = MAX_AUD_VALUE_LENGTH,
 ): bigint {
+	assertNoJsonEscape(name, 'key claim name');
+	assertNoJsonEscape(value, 'key claim value');
+	assertNoJsonEscape(aud, 'aud');
 	return poseidonHash([
 		hashASCIIStrToField(name, max_name_length),
 		hashASCIIStrToField(value, max_value_length),

package/docs/faucet.md

@@ -1,26 +0,0 @@
-# Faucet
-
-> Request test SUI tokens from the faucet on Devnet, Testnet, or local networks.
-
-Devnet, Testnet, and local networks include faucets that mint SUI. You can use the Sui TypeScript
-SDK to call a network's faucet and provide SUI to the address you provide.
-
-To request SUI from a faucet, import the `requestSuiFromFaucetV2` function from the
-`@mysten/sui/faucet` package to your project.
-
-```typescript
-
-```
-
-Use `requestSuiFromFaucetV2` in your TypeScript code to request SUI from the network's faucet.
-
-```typescript
-await requestSuiFromFaucetV2({
-	host: getFaucetHost('testnet'),
-	recipient: <RECIPIENT_ADDRESS>,
-});
-```
-
-> **Note:** Faucets on Devnet and Testnet are rate limited. If you run the script too many times, you surpass
-> the limit and must wait to successfully run it again. For Testnet, the best way to get SUI is
-> through the Web UI: `faucet.sui.io`.

package/docs/hello-sui.md

@@ -1,115 +0,0 @@
-# Hello Sui
-
-> Build your first Sui application with the TypeScript SDK.
-
-This basic example introduces you to the Sui TypeScript SDK. The Node.js example mints SUI on a Sui
-network and then queries the address to get a sum for the owned SUI. You don't need to use an IDE to
-complete the example, but one like Microsoft Visual Studio Code helps centralize more advanced
-projects.
-
-## Before you begin
-
-You need an address on a Sui development network (Devnet, Testnet, or local). If you don't already
-have an address, use the [Sui Client CLI](https://docs.sui.io/references/cli/client) or the
-[Sui Wallet browser extension](https://docs.mystenlabs.com) to create one.
-
-You also need [Node.js](https://nodejs.org/en/download/current) and a package manager like
-[pnpm](https://pnpm.io/installation) to follow this example, so install them on your system if you
-haven't already.
-
-## Start a project
-
-Using a Terminal or Console, create a folder on your system (`hello-sui` in this example) and make
-it the working directory.
-
-```sh
-mkdir hello-sui
-cd hello-sui
-```
-
-When you use a package manager to install the necessary packages, it downloads the modules to your
-`node_modules` folder and adds the references to your `package.json` file, creating the file if it
-doesn't already exist. For this example, you need only the Sui TypeScript SDK:
-
-```sh npm2yarn
-npm i -D @mysten/sui
-```
-
-The SDK is published as an ESM only package, so you also need to set `"type": "module"` in your
-`package.json`. Your `package.json` file should look like this:
-
-```json
-{
-	"type": "module",
-	"dependencies": {
-		"@mysten/sui": "^<VERSION_NUMBER>"
-	}
-}
-```
-
-## Get some SUI for your account
-
-Instead of a 'Hello World' output to your console, this example introduces some SUI to your wallet
-address. You must be on Devnet, Testnet, or a local network to use a faucet for minting SUI.
-
-Create a new `index.js` file in the root of your project with the following code.
-
-```js
-
-// replace <YOUR_SUI_ADDRESS> with your actual address, which is in the form 0x123...
-const MY_ADDRESS = '<YOUR_SUI_ADDRESS>';
-
-// create a new SuiGrpcClient object pointing to the network you want to use
-const suiClient = new SuiGrpcClient({
-	network: 'devnet',
-	baseUrl: 'https://fullnode.devnet.sui.io:443',
-});
-
-// Convert MIST to Sui
-const balance = (balance) => {
-	return Number.parseInt(balance.totalBalance) / Number(MIST_PER_SUI);
-};
-
-// store the JSON representation for the SUI the address owns before using faucet
-const suiBefore = await suiClient.getBalance({
-	owner: MY_ADDRESS,
-});
-
-await requestSuiFromFaucetV2({
-	// use getFaucetHost to make sure you're using correct faucet address
-	// you can also just use the address (see Sui TypeScript SDK Quick Start for values)
-	host: getFaucetHost('devnet'),
-	recipient: MY_ADDRESS,
-});
-
-// store the JSON representation for the SUI the address owns after using faucet
-const suiAfter = await suiClient.getBalance({
-	owner: MY_ADDRESS,
-});
-
-// Output result to console.
-console.log(
-	`Balance before faucet: ${balance(suiBefore)} SUI. Balance after: ${balance(
-		suiAfter,
-	)} SUI. Hello, SUI!`,
-);
-```
-
-Save the file, then use Node.js to run it in your Console or Terminal:
-
-```sh
-node index.js
-```
-
-The code imports the `requestSuiFromFaucetV2` function from the SDK and calls it to mint SUI for the
-provided address. The code also imports `SuiGrpcClient` to create a new client on the Sui network
-that it uses to query the address and output the amount of SUI the address owns before and after
-using the faucet. You can check the total SUI for your address using the Sui Wallet or Sui Client
-CLI.
-
-> **Note:** Faucets on Devnet and Testnet are rate limited. If you run the script too many times, you surpass
-> the limit and must wait to successfully run it again. For Testnet, the best way to get SUI is
-> through the Web UI: `faucet.sui.io`.
-
-You can also use the [Sui Client CLI](https://docs.sui.io/references/cli/client) to perform client
-calls on a Sui network.

package/docs/install.md

@@ -1,61 +0,0 @@
-# Install Sui TypeScript SDK
-
-> Install the @mysten/sui package and configure your project.
-
-The Sui TypeScript SDK is available in the
-[Sui TS SDK monorepo](https://github.com/MystenLabs/ts-sdks) and NPM.
-
-## Install from NPM
-
-To use the Sui TypeScript SDK in your project, run the following command in your project root:
-
-```sh npm2yarn
-npm i @mysten/sui
-```
-
-The SDK is published as an ESM only package. Make sure your `package.json` includes
-`"type": "module"`:
-
-```json
-{
-	"type": "module"
-}
-```
-
-If you are using TypeScript, your `tsconfig.json` should use a compatible `moduleResolution` setting
-such as `"NodeNext"`, `"Node16"`, or `"Bundler"`. See the
-[2.0 migration guide](/sui/migrations/sui-2.0#esm-migration) for more details.
-
-## Experimental tag for use with a local Sui network
-
-Projects developing against one of the onchain Sui networks (Devnet, Testnet, Mainnet) should use
-the base SDK published in the NPM registry (previous section) because the code aligns with the
-relevant JSON-RPC. If you are developing against a
-[local network](https://docs.sui.io/guides/developer/getting-started/local-network) built from the
-`main` branch of the Sui monorepo, however, you should use the `experimental`-tagged SDK package as
-it contains the latest features (or a local build detailed in the section that follows).
-
-```sh npm2yarn
-npm i @mysten/sui@experimental
-```
-
-## Install from local build
-
-To build the SDK from the Sui monorepo, you must use [pnpm](https://pnpm.io/). With pnpm installed,
-run the following command from the `sui` root directory:
-
-```bash
-# Install all dependencies
-pnpm install
-# Run the build for the TypeScript SDK
-pnpm sdk build
-```
-
-With the SDK built, you can import the library from your `sui` project. To do so, use a path to the
-`ts-sdks/packages/sui` directory that is relative to your project. For example, if you created a
-folder `my-sui-project` at the same level as `sui`, use the following to import the locally built
-Sui TypeScript package:
-
-```bash
-pnpm add ../ts-sdks/packages/sui
-```