@mysten/sui 2.7.0 → 2.9.0

package/docs/zklogin.md

@@ -0,0 +1,78 @@
+# ZkLogin
+
+> Zero-knowledge authentication with OAuth providers on Sui
+
+Utilities for working with zkLogin. Currently contains functionality to create and parse zkLogin
+signatures and compute zkLogin addresses.
+
+To parse a serialized zkLogin signature
+
+```typescript
+const parsedSignature = await parseZkLoginSignature('BQNNMTY4NjAxMzAyO....');
+```
+
+Use `getZkLoginSignature` to serialize a zkLogin signature.
+
+```typescript
+const serializedSignature = await getZkLoginSignature({ inputs, maxEpoch, userSignature });
+```
+
+To compute the address for a given address seed and iss you can use `computeZkLoginAddressFromSeed`
+
+```typescript
+const address = computeZkLoginAddressFromSeed(0n, 'https://accounts.google.com');
+```
+
+To compute an address from jwt:
+
+```typescript
+const address = jwtToAddress(jwtAsString, salt);
+```
+
+To compute an address from a parsed jwt:
+
+```typescript
+const address = computeZkLoginAddress({
+	claimName,
+	claimValue,
+	iss,
+	aud,
+	userSalt: BigInt(salt),
+});
+```
+
+To use zkLogin inside a multisig, see the [Multisig Guide](../sui/cryptography/multisig) for more
+details.
+
+## Legacy addresses
+
+When zklogin was first introduced, there was an inconsistency in how the address seed was computed.
+For backwards compatibility reasons there are 2 valid addresses for a given set of inputs. Methods
+that produce zklogin addresses all accept a `legacyAddress` boolean flag, either as their last
+parameter, or in their options argument.
+
+```typescript
+
+	computeZkLoginAddress,
+	computeZkLoginAddressFromSeed,
+	jwtToAddress,
+	toZkLoginPublicIdentifier,
+	genAddressSeed,
+} from '@mysten/sui/zklogin';
+
+const address = jwtToAddress(jwtAsString, salt, true);
+const address = computeZkLoginAddressFromSeed(0n, 'https://accounts.google.com', true);
+const address = computeZkLoginAddress({
+	claimName,
+	claimValue,
+	iss,
+	aud,
+	userSalt: BigInt(salt),
+	legacyAddress: true,
+});
+const address = toZkLoginPublicIdentifier(
+	genAddressSeed(userSalt, claimName, claimValue, aud),
+	iss,
+	{ legacyAddress: true },
+).toSuiAddress();
+```

package/package.json

@@ -3,7 +3,7 @@
   "author": "Mysten Labs <build@mystenlabs.com>",
   "description": "Sui TypeScript API",
   "homepage": "https://sdk.mystenlabs.com",
-  "version": "2.7.0",
+  "version": "2.9.0",
   "license": "Apache-2.0",
   "sideEffects": false,
   "files": [
@@ -15,6 +15,7 @@
     "client",
     "cryptography",
     "dist",
+    "docs",
     "experimental",
     "faucet",
     "graphql",
@@ -168,7 +169,7 @@
     "graphql": "^16.12.0",
     "poseidon-lite": "0.2.1",
     "valibot": "^1.2.0",
-    "@mysten/bcs": "^2.0.2",
+    "@mysten/bcs": "^2.0.3",
     "@mysten/utils": "^0.3.1"
   },
   "scripts": {
@@ -182,6 +183,7 @@
     "codegen:grpc-header": "find src/grpc/proto -type f -exec sh -c 'echo \"// Copyright (c) Mysten Labs, Inc.\\n// SPDX-License-Identifier: Apache-2.0\\n\" | cat - {} > temp && mv temp {}' \\;",
     "codegen:grpc-extensions": "find src/grpc/proto -name '*.ts' | xargs sed -i '' -E 's/from \"(\\.[^\"]+)\"/from \"\\1.js\"/g'",
     "build": "rm -rf dist && node genversion.mjs && tsc --noEmit && tsdown",
+    "build:docs": "tsx ../docs/scripts/build-docs.ts",
     "vitest": "vitest",
     "test": "pnpm test:typecheck && pnpm test:unit",
     "test:typecheck": "tsc -p ./test",

package/src/keypairs/passkey/keypair.ts

@@ -39,7 +39,7 @@ export type BrowserPasswordProviderOptions = Pick<
 
 export interface PasskeyProvider {
 	create(): Promise<RegistrationCredential>;
-	get(challenge: Uint8Array): Promise<AuthenticationCredential>;
+	get(challenge: Uint8Array, credentialId?: Uint8Array): Promise<AuthenticationCredential>;
 }
 
 // Default browser implementation
@@ -80,12 +80,15 @@ export class BrowserPasskeyProvider implements PasskeyProvider {
 		})) as RegistrationCredential;
 	}
 
-	async get(challenge: Uint8Array): Promise<AuthenticationCredential> {
+	async get(challenge: Uint8Array, credentialId?: Uint8Array): Promise<AuthenticationCredential> {
 		return (await navigator.credentials.get({
 			publicKey: {
 				challenge: challenge as BufferSource,
 				userVerification: this.#options.authenticatorSelection?.userVerification || 'required',
 				timeout: this.#options.timeout ?? 60000,
+				...(credentialId && {
+					allowCredentials: [{ type: 'public-key' as const, id: credentialId as BufferSource }],
+				}),
 			},
 		})) as AuthenticationCredential;
 	}
@@ -98,6 +101,7 @@ export class BrowserPasskeyProvider implements PasskeyProvider {
 export class PasskeyKeypair extends Signer {
 	private publicKey: Uint8Array;
 	private provider: PasskeyProvider;
+	private credentialId?: Uint8Array;
 
 	/**
 	 * Get the key scheme of passkey,
@@ -120,10 +124,20 @@ export class PasskeyKeypair extends Signer {
 	 * If there are existing passkey wallet, use `signAndRecover` to identify the correct
 	 * public key and then initialize the instance. See usage in `signAndRecover`.
 	 */
-	constructor(publicKey: Uint8Array, provider: PasskeyProvider) {
+	constructor(publicKey: Uint8Array, provider: PasskeyProvider, credentialId?: Uint8Array) {
 		super();
 		this.publicKey = publicKey;
 		this.provider = provider;
+		this.credentialId = credentialId;
+	}
+
+	/**
+	 * Return the credential ID for this passkey, if available.
+	 * The credential ID is captured when creating a new passkey via `getPasskeyInstance`
+	 * and can be used to constrain which credential the browser selects during signing.
+	 */
+	getCredentialId(): Uint8Array | undefined {
+		return this.credentialId;
 	}
 
 	/**
@@ -145,7 +159,7 @@ export class PasskeyKeypair extends Signer {
 			const pubkeyUncompressed = parseDerSPKI(new Uint8Array(derSPKI));
 			const pubkey = secp256r1.Point.fromBytes(pubkeyUncompressed);
 			const pubkeyCompressed = pubkey.toBytes(true);
-			return new PasskeyKeypair(pubkeyCompressed, provider);
+			return new PasskeyKeypair(pubkeyCompressed, provider, new Uint8Array(credential.rawId));
 		}
 	}
 
@@ -162,7 +176,7 @@ export class PasskeyKeypair extends Signer {
 	 */
 	async sign(data: Uint8Array) {
 		// asks the passkey to sign over challenge as the data.
-		const credential = await this.provider.get(data);
+		const credential = await this.provider.get(data, this.credentialId);
 
 		// parse authenticatorData (as bytes), clientDataJSON (decoded as string).
 		const authenticatorData = new Uint8Array(credential.response.authenticatorData);
@@ -245,7 +259,7 @@ export class PasskeyKeypair extends Signer {
 	 * const testMessage2 = new TextEncoder().encode('Hello world 2!');
 	 * const possiblePks2 = await PasskeyKeypair.signAndRecover(provider, testMessage2);
 	 * const commonPk = findCommonPublicKey(possiblePks, possiblePks2);
-	 * const signer = new PasskeyKeypair(provider, commonPk.toRawBytes());
+	 * const signer = new PasskeyKeypair(commonPk.toRawBytes(), provider);
 	 * ```
 	 *
 	 * @param provider - the passkey provider.

package/src/utils/constants.ts

@@ -18,5 +18,7 @@ export const SUI_SYSTEM_STATE_OBJECT_ID =
 	'0x0000000000000000000000000000000000000000000000000000000000000005';
 export const SUI_RANDOM_OBJECT_ID =
 	'0x0000000000000000000000000000000000000000000000000000000000000008';
+export const SUI_COIN_REGISTRY_OBJECT_ID =
+	'0x000000000000000000000000000000000000000000000000000000000000000c';
 export const SUI_DENY_LIST_OBJECT_ID =
 	'0x0000000000000000000000000000000000000000000000000000000000000403';

package/src/utils/index.ts

@@ -28,6 +28,7 @@ export {
 	SUI_TYPE_ARG,
 	SUI_SYSTEM_STATE_OBJECT_ID,
 	SUI_RANDOM_OBJECT_ID,
+	SUI_COIN_REGISTRY_OBJECT_ID,
 	SUI_DENY_LIST_OBJECT_ID,
 } from './constants.js';
 

package/src/version.ts

@@ -3,5 +3,5 @@
 
 // This file is generated by genversion.mjs. Do not edit it directly.
 
-export const PACKAGE_VERSION = '2.7.0';
-export const TARGETED_RPC_VERSION = '1.68.0';
+export const PACKAGE_VERSION = '2.9.0';
+export const TARGETED_RPC_VERSION = '1.69.0';