@haneullabs/signers 0.1.0

package/src/gcp/gcp-kms-client.ts

@@ -0,0 +1,165 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+import { KeyManagementServiceClient } from '@google-cloud/kms';
+import type { PublicKey, SignatureFlag } from '@haneullabs/haneul/cryptography';
+import { SIGNATURE_FLAG_TO_SCHEME, Signer } from '@haneullabs/haneul/cryptography';
+import { Secp256k1PublicKey } from '@haneullabs/haneul/keypairs/secp256k1';
+import { Secp256r1PublicKey } from '@haneullabs/haneul/keypairs/secp256r1';
+import { fromBase64 } from '@haneullabs/haneul/utils';
+
+import { getConcatenatedSignature, publicKeyFromDER } from '../utils/utils.js';
+
+/**
+ * Configuration options for initializing the GcpKmsSigner.
+ */
+export interface GcpKmsSignerOptions {
+	/** The version name generated from `client.cryptoKeyVersionPath()` */
+	versionName: string;
+	/** Options for setting up the GCP KMS client */
+	client: KeyManagementServiceClient;
+	/** Public key */
+	publicKey: PublicKey;
+}
+
+/**
+ * GCP KMS Signer integrates GCP Key Management Service (KMS) with the Haneul blockchain
+ * to provide signing capabilities using GCP-managed cryptographic keys.
+ */
+export class GcpKmsSigner extends Signer {
+	#publicKey: PublicKey;
+	/** GCP KMS client instance */
+	#client: KeyManagementServiceClient;
+	/** GCP KMS version name (generated from `client.cryptoKeyVersionPath()`) */
+	#versionName: string;
+
+	/**
+	 * Creates an instance of GcpKmsSigner. It's expected to call the static `fromOptions`
+	 * or `fromVersionName` method to create an instance.
+	 * For example:
+	 * ```
+	 * const signer = await GcpKmsSigner.fromVersionName(versionName);
+	 * ```
+	 * @throws Will throw an error if required GCP credentials are not provided.
+	 */
+	constructor({ versionName, client, publicKey }: GcpKmsSignerOptions) {
+		super();
+		if (!versionName) throw new Error('Version name is required');
+
+		this.#client = client;
+		this.#versionName = versionName;
+		this.#publicKey = publicKey;
+	}
+
+	/**
+	 * Retrieves the key scheme used by this signer.
+	 * @returns GCP supports only `Secp256k1` and `Secp256r1` schemes.
+	 */
+	getKeyScheme() {
+		return SIGNATURE_FLAG_TO_SCHEME[this.#publicKey.flag() as SignatureFlag];
+	}
+
+	/**
+	 * Retrieves the public key associated with this signer.
+	 * @returns The Secp256k1PublicKey instance.
+	 * @throws Will throw an error if the public key has not been initialized.
+	 */
+	getPublicKey() {
+		return this.#publicKey;
+	}
+
+	/**
+	 * Signs the given data using GCP KMS.
+	 * @param bytes - The data to be signed as a Uint8Array.
+	 * @returns A promise that resolves to the signature as a Uint8Array.
+	 * @throws Will throw an error if the public key is not initialized or if signing fails.
+	 */
+	async sign(bytes: Uint8Array): Promise<Uint8Array<ArrayBuffer>> {
+		const [signResponse] = await this.#client.asymmetricSign({
+			name: this.#versionName,
+			data: bytes,
+		});
+
+		if (!signResponse.signature) {
+			throw new Error('No signature returned from GCP KMS');
+		}
+
+		return getConcatenatedSignature(signResponse.signature as Uint8Array, this.getKeyScheme());
+	}
+
+	/**
+	 * Synchronous signing is not supported by GCP KMS.
+	 * @throws Always throws an error indicating synchronous signing is unsupported.
+	 * @deprecated use `sign` instead
+	 */
+	signData(): never {
+		throw new Error('GCP Signer does not support sync signing');
+	}
+
+	/**
+	 * Creates a GCP KMS signer from the provided options.
+	 * Expects the credentials file to be set as an env variable
+	 * (GOOGLE_APPLICATION_CREDENTIALS).
+	 */
+	static async fromOptions(options: {
+		projectId: string;
+		location: string;
+		keyRing: string;
+		cryptoKey: string;
+		cryptoKeyVersion: string;
+	}) {
+		const client = new KeyManagementServiceClient();
+
+		const versionName = client.cryptoKeyVersionPath(
+			options.projectId,
+			options.location,
+			options.keyRing,
+			options.cryptoKey,
+			options.cryptoKeyVersion,
+		);
+
+		return new GcpKmsSigner({
+			versionName,
+			client,
+			publicKey: await getPublicKey(client, versionName),
+		});
+	}
+
+	static async fromVersionName(versionName: string) {
+		const client = new KeyManagementServiceClient();
+		return new GcpKmsSigner({
+			versionName,
+			client,
+			publicKey: await getPublicKey(client, versionName),
+		});
+	}
+}
+
+/**
+ * Retrieves the public key associated with the given version name.
+ */
+async function getPublicKey(
+	client: KeyManagementServiceClient,
+	versionName: string,
+): Promise<PublicKey> {
+	const [publicKey] = await client.getPublicKey({ name: versionName });
+
+	const { algorithm, pem } = publicKey;
+
+	if (!pem) throw new Error('No PEM key returned from GCP KMS');
+
+	const base64 = pem
+		.replace('-----BEGIN PUBLIC KEY-----', '')
+		.replace('-----END PUBLIC KEY-----', '')
+		.replace(/\s/g, '');
+
+	const compressedKey = publicKeyFromDER(fromBase64(base64));
+
+	switch (algorithm) {
+		case 'EC_SIGN_SECP256K1_SHA256':
+			return new Secp256k1PublicKey(compressedKey);
+		case 'EC_SIGN_P256_SHA256':
+			return new Secp256r1PublicKey(compressedKey);
+		default:
+			throw new Error(`Unsupported algorithm: ${algorithm}`);
+	}
+}

package/src/gcp/index.ts

@@ -0,0 +1,9 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+import type { GcpKmsSignerOptions } from './gcp-kms-client.js';
+import { GcpKmsSigner } from './gcp-kms-client.js';
+
+export { GcpKmsSigner };
+
+export type { GcpKmsSignerOptions };

package/src/ledger/bcs.ts

@@ -0,0 +1,87 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+import { bcs, TypeTagSerializer } from '@haneullabs/haneul/bcs';
+import type { ObjectOwner } from '@haneullabs/haneul/client';
+import {
+	fromBase64,
+	normalizeStructTag,
+	normalizeHaneulAddress,
+	parseStructTag,
+} from '@haneullabs/haneul/utils';
+
+const HANEUL_FRAMEWORK_ADDRESS = normalizeHaneulAddress('0x2');
+const HANEUL_SYSTEM_ADDRESS = normalizeHaneulAddress('0x3');
+
+const MoveObjectType = bcs.enum('MoveObjectType', {
+	Other: bcs.StructTag,
+	GasCoin: null,
+	StakedSui: null,
+	Coin: bcs.TypeTag,
+});
+
+export const HaneulMoveObject = bcs.struct('HaneulMoveObject', {
+	data: bcs.enum('Data', {
+		MoveObject: bcs.struct('MoveObject', {
+			type: MoveObjectType.transform({
+				input: (objectType: string): typeof MoveObjectType.$inferType => {
+					const structTag = parseStructTag(objectType);
+
+					if (
+						structTag.address === HANEUL_FRAMEWORK_ADDRESS &&
+						structTag.module === 'coin' &&
+						structTag.name === 'Coin' &&
+						typeof structTag.typeParams[0] === 'object'
+					) {
+						const innerStructTag = structTag.typeParams[0];
+						if (
+							innerStructTag.address === HANEUL_FRAMEWORK_ADDRESS &&
+							innerStructTag.module === 'haneul' &&
+							innerStructTag.name === 'SUI'
+						) {
+							return { GasCoin: true, $kind: 'GasCoin' };
+						}
+						return { Coin: normalizeStructTag(innerStructTag), $kind: 'Coin' };
+					} else if (
+						structTag.address === HANEUL_SYSTEM_ADDRESS &&
+						structTag.module === 'staking_pool' &&
+						structTag.name === 'StakedSui'
+					) {
+						return { StakedSui: true, $kind: 'StakedSui' };
+					}
+					return {
+						Other: {
+							...structTag,
+							typeParams: structTag.typeParams.map((typeParam) => {
+								return TypeTagSerializer.parseFromStr(normalizeStructTag(typeParam));
+							}),
+						},
+						$kind: 'Other',
+					};
+				},
+			}),
+			hasPublicTransfer: bcs.bool(),
+			version: bcs.u64(),
+			contents: bcs.byteVector().transform({ input: fromBase64 }),
+		}),
+	}),
+	owner: bcs.Owner.transform({
+		input: (objectOwner: ObjectOwner) => {
+			if (objectOwner === 'Immutable') {
+				return { Immutable: null };
+			} else if ('Shared' in objectOwner) {
+				return { Shared: { initialSharedVersion: objectOwner.Shared.initial_shared_version } };
+			} else if ('ConsensusAddressOwner' in objectOwner) {
+				return {
+					ConsensusAddressOwner: {
+						owner: objectOwner.ConsensusAddressOwner.owner,
+						startVersion: objectOwner.ConsensusAddressOwner.start_version,
+					},
+				};
+			}
+			return objectOwner;
+		},
+	}),
+	previousTransaction: bcs.ObjectDigest,
+	storageRebate: bcs.u64(),
+});

package/src/ledger/index.ts

@@ -0,0 +1,164 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+import type HaneulLedgerClient from '@haneullabs/ledgerjs-hw-app-haneul';
+import type { HaneulClient } from '@haneullabs/haneul/client';
+import type { SignatureWithBytes } from '@haneullabs/haneul/cryptography';
+import { messageWithIntent, Signer, toSerializedSignature } from '@haneullabs/haneul/cryptography';
+import { Ed25519PublicKey } from '@haneullabs/haneul/keypairs/ed25519';
+import { Transaction } from '@haneullabs/haneul/transactions';
+import { toBase64 } from '@haneullabs/haneul/utils';
+
+import { bcs } from '@haneullabs/haneul/bcs';
+import { getInputObjects } from './objects.js';
+import type { Resolution } from '@haneullabs/ledgerjs-hw-app-haneul';
+
+export { HaneulMoveObject } from './bcs.js';
+export { getInputObjects } from './objects.js';
+
+/**
+ * Configuration options for initializing the LedgerSigner.
+ */
+export interface LedgerSignerOptions {
+	publicKey: Ed25519PublicKey;
+	derivationPath: string;
+	ledgerClient: HaneulLedgerClient;
+	haneulClient: HaneulClient;
+}
+
+/**
+ * Ledger integrates with the Haneul blockchain to provide signing capabilities using Ledger devices.
+ */
+export class LedgerSigner extends Signer {
+	#derivationPath: string;
+	#publicKey: Ed25519PublicKey;
+	#ledgerClient: HaneulLedgerClient;
+	#haneulClient: HaneulClient;
+
+	/**
+	 * Creates an instance of LedgerSigner. It's expected to call the static `fromDerivationPath` method to create an instance.
+	 * @example
+	 * ```
+	 * const signer = await LedgerSigner.fromDerivationPath(derivationPath, options);
+	 * ```
+	 */
+	constructor({ publicKey, derivationPath, ledgerClient, haneulClient }: LedgerSignerOptions) {
+		super();
+		this.#publicKey = publicKey;
+		this.#derivationPath = derivationPath;
+		this.#ledgerClient = ledgerClient;
+		this.#haneulClient = haneulClient;
+	}
+
+	/**
+	 * Retrieves the key scheme used by this signer.
+	 */
+	override getKeyScheme() {
+		return 'ED25519' as const;
+	}
+
+	/**
+	 * Retrieves the public key associated with this signer.
+	 * @returns The Ed25519PublicKey instance.
+	 */
+	override getPublicKey() {
+		return this.#publicKey;
+	}
+
+	/**
+	 * Signs the provided transaction bytes.
+	 * @returns The signed transaction bytes and signature.
+	 */
+	override async signTransaction(
+		bytes: Uint8Array,
+		bcsObjects?: Uint8Array[],
+		resolution?: Resolution,
+	): Promise<SignatureWithBytes> {
+		const transactionOptions = bcsObjects
+			? { bcsObjects }
+			: await getInputObjects(Transaction.from(bytes), this.#haneulClient).catch(() => ({
+					// Fail gracefully so network errors or serialization issues don't break transaction signing:
+					bcsObjects: [],
+				}));
+
+		const intentMessage = messageWithIntent('TransactionData', bytes);
+		const { signature } = await this.#ledgerClient.signTransaction(
+			this.#derivationPath,
+			intentMessage,
+			transactionOptions,
+			resolution,
+		);
+
+		return {
+			bytes: toBase64(bytes),
+			signature: toSerializedSignature({
+				signature,
+				signatureScheme: this.getKeyScheme(),
+				publicKey: this.#publicKey,
+			}),
+		};
+	}
+
+	/**
+	 * Signs the provided personal message.
+	 * @returns The signed message bytes and signature.
+	 */
+	override async signPersonalMessage(bytes: Uint8Array): Promise<SignatureWithBytes> {
+		const intentMessage = messageWithIntent(
+			'PersonalMessage',
+			bcs.byteVector().serialize(bytes).toBytes(),
+		);
+		const { signature } = await this.#ledgerClient.signTransaction(
+			this.#derivationPath,
+			intentMessage,
+		);
+
+		return {
+			bytes: toBase64(bytes),
+			signature: toSerializedSignature({
+				signature,
+				signatureScheme: this.getKeyScheme(),
+				publicKey: this.#publicKey,
+			}),
+		};
+	}
+
+	/**
+	 * Prepares the signer by fetching and setting the public key from a Ledger device.
+	 * It is recommended to initialize an `LedgerSigner` instance using this function.
+	 * @returns A promise that resolves once a `LedgerSigner` instance is prepared (public key is set).
+	 */
+	static async fromDerivationPath(
+		derivationPath: string,
+		ledgerClient: HaneulLedgerClient,
+		haneulClient: HaneulClient,
+	) {
+		const { publicKey } = await ledgerClient.getPublicKey(derivationPath);
+		if (!publicKey) {
+			throw new Error('Failed to get public key from Ledger.');
+		}
+
+		return new LedgerSigner({
+			derivationPath,
+			publicKey: new Ed25519PublicKey(publicKey),
+			ledgerClient,
+			haneulClient,
+		});
+	}
+
+	/**
+	 * Generic signing is not supported by Ledger.
+	 * @throws Always throws an error indicating generic signing is unsupported.
+	 */
+	override sign(): never {
+		throw new Error('Ledger Signer does not support generic signing.');
+	}
+
+	/**
+	 * Generic signing is not supported by Ledger.
+	 * @throws Always throws an error indicating generic signing is unsupported.
+	 */
+	override signWithIntent(): never {
+		throw new Error('Ledger Signer does not support generic signing.');
+	}
+}

package/src/ledger/objects.ts

@@ -0,0 +1,56 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+import type { Transaction } from '@haneullabs/haneul/transactions';
+import type { HaneulClient } from '@haneullabs/haneul/client';
+import { HaneulMoveObject } from './bcs.js';
+
+export const getInputObjects = async (transaction: Transaction, client: HaneulClient) => {
+	const data = transaction.getData();
+
+	const gasObjectIds = data.gasData.payment?.map((object) => object.objectId) ?? [];
+	const inputObjectIds = data.inputs
+		.map((input) => {
+			return input.$kind === 'Object' && input.Object.$kind === 'ImmOrOwnedObject'
+				? input.Object.ImmOrOwnedObject.objectId
+				: null;
+		})
+		.filter((objectId): objectId is string => !!objectId);
+
+	const objects = await client.multiGetObjects({
+		ids: [...gasObjectIds, ...inputObjectIds],
+		options: {
+			showBcs: true,
+			showPreviousTransaction: true,
+			showStorageRebate: true,
+			showOwner: true,
+		},
+	});
+
+	// NOTE: We should probably get rid of this manual serialization logic in favor of using the
+	// already serialized object bytes from the GraphQL API once there is more mainstream support
+	// for it + we can enforce the transport type on the Haneul client.
+	const bcsObjects = objects
+		.map((object) => {
+			if (object.error || !object.data || object.data.bcs?.dataType !== 'moveObject') {
+				return null;
+			}
+
+			return HaneulMoveObject.serialize({
+				data: {
+					MoveObject: {
+						type: object.data.bcs.type,
+						hasPublicTransfer: object.data.bcs.hasPublicTransfer,
+						version: object.data.bcs.version,
+						contents: object.data.bcs.bcsBytes,
+					},
+				},
+				owner: object.data.owner!,
+				previousTransaction: object.data.previousTransaction!,
+				storageRebate: object.data.storageRebate!,
+			}).toBytes();
+		})
+		.filter((bcsBytes): bcsBytes is Uint8Array<ArrayBuffer> => !!bcsBytes);
+
+	return { bcsObjects };
+};

package/src/utils/utils.ts

@@ -0,0 +1,119 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+import { secp256r1 } from '@noble/curves/p256';
+import { secp256k1 } from '@noble/curves/secp256k1';
+import { ASN1Construction, ASN1TagClass, DERElement } from 'asn1-ts';
+
+/** The total number of bits in the DER bit string for the uncompressed public key. */
+export const DER_BIT_STRING_LENGTH = 520;
+
+/** The total number of bytes corresponding to the DER bit string length. */
+export const DER_BYTES_LENGTH = DER_BIT_STRING_LENGTH / 8;
+
+// Reference Specifications:
+// https://datatracker.ietf.org/doc/html/rfc5480#section-2.2
+// https://www.secg.org/sec1-v2.pdf
+
+/**
+ * Converts an array of bits into a byte array.
+ *
+ * @param bitsArray - A `Uint8ClampedArray` representing the bits to convert.
+ * @returns A `Uint8Array` containing the corresponding bytes.
+ *
+ * @throws {Error} If the input array does not have the expected length.
+ */
+function bitsToBytes(bitsArray: Uint8ClampedArray): Uint8Array {
+	const bytes = new Uint8Array(DER_BYTES_LENGTH);
+	for (let i = 0; i < DER_BIT_STRING_LENGTH; i++) {
+		if (bitsArray[i] === 1) {
+			bytes[Math.floor(i / 8)] |= 1 << (7 - (i % 8));
+		}
+	}
+	return bytes;
+}
+
+export function publicKeyFromDER(derBytes: Uint8Array) {
+	const encodedData: Uint8Array = derBytes;
+	const derElement = new DERElement();
+	derElement.fromBytes(encodedData);
+
+	// Validate the ASN.1 structure of the public key
+	if (
+		!(
+			derElement.tagClass === ASN1TagClass.universal &&
+			derElement.construction === ASN1Construction.constructed
+		)
+	) {
+		throw new Error('Unexpected ASN.1 structure');
+	}
+
+	const components = derElement.components;
+	const publicKeyElement = components[1];
+
+	if (!publicKeyElement) {
+		throw new Error('Public Key not found in the DER structure');
+	}
+
+	return compressPublicKeyClamped(publicKeyElement.bitString);
+}
+
+export function getConcatenatedSignature(signature: Uint8Array, keyScheme: string) {
+	if (!signature || signature.length === 0) {
+		throw new Error('Invalid signature');
+	}
+
+	// Initialize a DERElement to parse the DER-encoded signature
+	const derElement = new DERElement();
+	derElement.fromBytes(signature);
+
+	const [r, s] = derElement.toJSON() as [string, string];
+
+	switch (keyScheme) {
+		case 'Secp256k1':
+			return new secp256k1.Signature(BigInt(r), BigInt(s))
+				.normalizeS()
+				.toCompactRawBytes() as Uint8Array<ArrayBuffer>;
+		case 'Secp256r1':
+			return new secp256r1.Signature(BigInt(r), BigInt(s))
+				.normalizeS()
+				.toCompactRawBytes() as Uint8Array<ArrayBuffer>;
+		default:
+			throw new Error('Unsupported key scheme');
+	}
+}
+
+/**
+ * Compresses an uncompressed public key into its compressed form.
+ *
+ * The uncompressed key must follow the DER bit string format as specified in [RFC 5480](https://datatracker.ietf.org/doc/html/rfc5480#section-2.2)
+ * and [SEC 1: Elliptic Curve Cryptography](https://www.secg.org/sec1-v2.pdf).
+ *
+ * @param uncompressedKey - A `Uint8ClampedArray` representing the uncompressed public key bits.
+ * @returns A `Uint8Array` containing the compressed public key.
+ *
+ * @throws {Error} If the uncompressed key has an unexpected length or does not start with the expected prefix.
+ */
+export function compressPublicKeyClamped(uncompressedKey: Uint8ClampedArray): Uint8Array {
+	if (uncompressedKey.length !== DER_BIT_STRING_LENGTH) {
+		throw new Error('Unexpected length for an uncompressed public key');
+	}
+
+	// Convert bits to bytes
+	const uncompressedBytes = bitsToBytes(uncompressedKey);
+
+	// Ensure the public key starts with the standard uncompressed prefix 0x04
+	if (uncompressedBytes[0] !== 0x04) {
+		throw new Error('Public key does not start with 0x04');
+	}
+
+	// Extract X-Coordinate (skip the first byte, which is the prefix 0x04)
+	const xCoord = uncompressedBytes.slice(1, 33);
+
+	// Determine parity byte for Y coordinate based on the last byte
+	const yCoordLastByte = uncompressedBytes[64];
+	const parityByte = yCoordLastByte % 2 === 0 ? 0x02 : 0x03;
+
+	// Return the compressed public key consisting of the parity byte and X-coordinate
+	return new Uint8Array([parityByte, ...xCoord]);
+}