@mysten-incubation/dev-wallet 0.0.1 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mysten-incubation/dev-wallet",
-  "version": "0.0.1",
+  "version": "0.3.0",
   "description": "A modular dev wallet for Sui",
   "license": "Apache-2.0",
   "author": "Mysten Labs <build@mystenlabs.com>",
@@ -64,19 +64,20 @@
   "devDependencies": {
     "@lit/react": "^1.0.8",
     "@mysten/signers": "^1.0.1",
-    "@mysten/sui": "^2.9.1",
+    "@mysten/sui": "^2.17.0",
+    "@testing-library/dom": "^10.4.1",
     "@testing-library/react": "^16.3.1",
     "@types/node": "^25.0.8",
     "@types/react": "^19.2.8",
-    "@vitest/browser": "^4.0.18",
-    "@vitest/browser-playwright": "^4.0.18",
+    "@vitest/browser": "^4.1.6",
+    "@vitest/browser-playwright": "^4.1.6",
     "happy-dom": "^20.1.0",
     "playwright": "*",
     "react": "^19.2.3",
     "react-dom": "^19.2.3",
     "typescript": "^5.9.3",
     "vite": "^7.3.1",
-    "vitest": "^4.0.17"
+    "vitest": "^4.1.6"
   },
   "dependencies": {
     "@hono/node-server": "^1.19.9",
@@ -90,7 +91,7 @@
   "peerDependencies": {
     "@lit/react": "^1.0.8",
     "@mysten/signers": "^1.0.1",
-    "@mysten/sui": "^2.9.1",
+    "@mysten/sui": "^2.17.0",
     "@types/react": ">=17.0.0",
     "react": ">=17.0.0"
   },
@@ -110,6 +111,7 @@
   },
   "scripts": {
     "clean": "rm -rf tsconfig.tsbuildinfo ./dist",
+    "build:docs": "tsx ../docs/scripts/build-docs.ts",
     "build": "rm -rf dist && tsc --noEmit && tsdown && vite build --config vite.standalone.config.ts && vite build --config vite.bookmarklet.config.ts",
     "prettier:check": "prettier -c --ignore-unknown .",
     "prettier:fix": "prettier -w --ignore-unknown .",

package/src/adapters/browser.ts

@@ -11,5 +11,26 @@ export { BaseSignerAdapter } from './base-adapter.js';
 export { buildManagedAccount } from './build-managed-account.js';
 export { InMemorySignerAdapter } from './in-memory-adapter.js';
 export { RemoteCliAdapter, CliProxySigner } from './remote-cli-adapter.js';
+export {
+	DevstackSignerAdapter,
+	DevstackProxySigner,
+	parseDevstackToken,
+	createDevstackAdapterFromManifest,
+	type DevstackSignerAdapterOptions,
+	type DevstackAdapterManifest,
+} from './devstack-adapter.js';
+// Wire-level HTTP path contract mirrored from devstack's wallet plugin;
+// kept duplicated to avoid closing a workspace cycle.
+export { DEVSTACK_WALLET_HTTP_PATH, type DevstackWalletHttpPathValue } from './devstack-paths.js';
+export {
+	ForkRelay,
+	ForkRelayHttpError,
+	createForkRelayFromManifest,
+	type ForkRelayManifest,
+	type ForkRelayOptions,
+	type ForkRelayResult,
+	type ForkStatus,
+	type ForkImpersonationSlot,
+} from './fork-relay.js';
 export { WebCryptoSignerAdapter } from './webcrypto-adapter.js';
 export { PasskeySignerAdapter } from './passkey-adapter.js';

package/src/adapters/devstack-adapter.ts

@@ -0,0 +1,342 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+//
+// Devstack signer adapter — exposes accounts resolved by `devstack up`'s
+// `wallet()` plugin to dApp Kit, signing transactions over HTTP so
+// private keys never enter the frontend bundle. Mirrors RemoteCliAdapter's
+// out-of-process model; the difference is the source of accounts (devstack
+// resolved signers vs `sui keytool list`) and the endpoint paths.
+
+import { Signer } from '@mysten/sui/cryptography';
+import type { PublicKey, SignatureScheme } from '@mysten/sui/cryptography';
+import { Ed25519PublicKey } from '@mysten/sui/keypairs/ed25519';
+import { Secp256k1PublicKey } from '@mysten/sui/keypairs/secp256k1';
+import { Secp256r1PublicKey } from '@mysten/sui/keypairs/secp256r1';
+import { fromBase64, toBase64 } from '@mysten/sui/utils';
+
+import type { ManagedAccount } from '../types.js';
+import { BaseSignerAdapter } from './base-adapter.js';
+import { buildManagedAccount } from './build-managed-account.js';
+import { DEVSTACK_WALLET_HTTP_PATH } from './devstack-paths.js';
+
+const DEVSTACK_WALLET_FEATURES = [
+	'sui:signTransaction',
+	'sui:signAndExecuteTransaction',
+	'sui:signPersonalMessage',
+] as const;
+
+interface ServerAccountInfo {
+	name: string;
+	address: string;
+	scheme: SignatureScheme;
+	publicKey: string;
+}
+
+class AuthError extends Error {
+	constructor() {
+		super('Unauthorized');
+		this.name = 'AuthError';
+	}
+}
+
+function publicKeyForScheme(base64: string, scheme: SignatureScheme | string): PublicKey {
+	const bytes = fromBase64(base64);
+	// The devstack server's wallet-app endpoint surfaces the scheme in
+	// the lowercase form it standardised at the Account boundary
+	// (`'ed25519'`, `'secp256k1'`, `'secp256r1'`). The Sui SDK's
+	// `SignatureScheme` union is mixed-case (`'ED25519'`, `'Secp256k1'`,
+	// …). Normalise to lowercase before matching so either casing parses.
+	switch (String(scheme).toLowerCase()) {
+		case 'ed25519':
+			return new Ed25519PublicKey(bytes);
+		case 'secp256k1':
+			return new Secp256k1PublicKey(bytes);
+		case 'secp256r1':
+			return new Secp256r1PublicKey(bytes);
+		default:
+			throw new Error(`Unsupported key scheme: ${scheme}`);
+	}
+}
+
+/**
+ * Signer that delegates transaction signing to the devstack wallet-app
+ * over HTTP. Mirrors {@link CliProxySigner} but talks to the
+ * `wallet()` plugin's endpoints under `/api/v1/devstack/*`.
+ */
+export class DevstackProxySigner extends Signer {
+	#address: string;
+	#publicKey: PublicKey;
+	#scheme: SignatureScheme;
+	#serverOrigin: string;
+	#authToken: string | null;
+
+	constructor(options: {
+		address: string;
+		publicKey: PublicKey;
+		scheme: SignatureScheme;
+		serverOrigin: string;
+		authToken?: string | null;
+	}) {
+		super();
+		this.#address = options.address;
+		this.#publicKey = options.publicKey;
+		this.#scheme = options.scheme;
+		this.#serverOrigin = options.serverOrigin;
+		this.#authToken = options.authToken ?? null;
+	}
+
+	async sign(_bytes: Uint8Array): Promise<Uint8Array<ArrayBuffer>> {
+		throw new Error(
+			'DevstackProxySigner does not support raw digest signing. ' +
+				'Use signTransaction (the wallet-app signs BCS-serialized TransactionData).',
+		);
+	}
+
+	getKeyScheme(): SignatureScheme {
+		return this.#scheme;
+	}
+
+	getPublicKey(): PublicKey {
+		return this.#publicKey;
+	}
+
+	override toSuiAddress(): string {
+		return this.#address;
+	}
+
+	override async signTransaction(bytes: Uint8Array) {
+		const headers: Record<string, string> = { 'Content-Type': 'application/json' };
+		if (this.#authToken !== null) {
+			headers['Authorization'] = `Bearer ${this.#authToken}`;
+		}
+		const requestBytes = toBase64(bytes);
+		const res = await fetch(`${this.#serverOrigin}${DEVSTACK_WALLET_HTTP_PATH.SIGN_TRANSACTION}`, {
+			method: 'POST',
+			headers,
+			body: JSON.stringify({
+				address: this.#address,
+				bytes: requestBytes,
+			}),
+		});
+		if (!res.ok) {
+			const body = await res.json().catch(() => ({}));
+			const message = (body as { error?: unknown }).error;
+			throw new Error(
+				`Devstack signing failed: ${typeof message === 'string' ? message : res.statusText}`,
+			);
+		}
+		const { bytes: responseBytes, signature } = (await res.json()) as {
+			bytes?: string;
+			signature?: string;
+		};
+		if (typeof responseBytes !== 'string' || responseBytes.length === 0) {
+			throw new Error('Devstack signing failed: server returned invalid signed bytes');
+		}
+		if (typeof signature !== 'string' || signature.length === 0) {
+			throw new Error('Devstack signing failed: server returned invalid signature');
+		}
+		return {
+			bytes: responseBytes,
+			signature,
+		};
+	}
+
+	override async signPersonalMessage(bytes: Uint8Array) {
+		const headers: Record<string, string> = { 'Content-Type': 'application/json' };
+		if (this.#authToken !== null) {
+			headers['Authorization'] = `Bearer ${this.#authToken}`;
+		}
+		const res = await fetch(
+			`${this.#serverOrigin}${DEVSTACK_WALLET_HTTP_PATH.SIGN_PERSONAL_MESSAGE}`,
+			{
+				method: 'POST',
+				headers,
+				body: JSON.stringify({
+					address: this.#address,
+					bytes: toBase64(bytes),
+				}),
+			},
+		);
+		if (!res.ok) {
+			const body = await res.json().catch(() => ({}));
+			const message = (body as { error?: unknown }).error;
+			throw new Error(
+				`Devstack personal-message signing failed: ${
+					typeof message === 'string' ? message : res.statusText
+				}`,
+			);
+		}
+		const { bytes: responseBytes, signature } = (await res.json()) as {
+			bytes?: string;
+			signature?: string;
+		};
+		if (typeof responseBytes !== 'string' || responseBytes.length === 0) {
+			throw new Error(
+				'Devstack personal-message signing failed: server returned invalid signed bytes',
+			);
+		}
+		if (typeof signature !== 'string' || signature.length === 0) {
+			throw new Error('Devstack personal-message signing failed: server returned no signature');
+		}
+		return { bytes: responseBytes, signature };
+	}
+}
+
+export interface DevstackSignerAdapterOptions {
+	/** Wallet-app origin (e.g. `http://localhost:9420`). Read from the
+	 * matching endpoint entry on the active manifest. */
+	serverOrigin: string;
+	/** Bearer token. Parse `?token=<hex>` from the manifest entry's
+	 * `pairUrl`. Omit if the wallet-app runs without auth. */
+	token?: string | null;
+	/** Override the adapter's display name. Defaults to `'Devstack'`. */
+	name?: string;
+}
+
+/**
+ * {@link SignerAdapter} that surfaces every account resolved by `devstack up`
+ * (including `cliSigner`/`envSigner`/`generatedKeypair` slots) without
+ * shipping their private keys into the frontend bundle. All signing happens
+ * server-side via the `wallet()` plugin.
+ *
+ * The simplest construction uses devstack's generated `dapp-kit-config.ts`,
+ * which bakes the wallet adapter wiring at codegen time — apps spread
+ * `devstackDappKitConfig` into `createDAppKit(...)` and never touch the
+ * adapter directly.
+ *
+ * To construct one manually (e.g. from a non-manifest source):
+ *
+ * ```ts
+ * const adapter = new DevstackSignerAdapter({
+ *     serverOrigin: 'http://localhost:9420',
+ *     token: '<bearer hex>',
+ * });
+ * ```
+ */
+export class DevstackSignerAdapter extends BaseSignerAdapter {
+	readonly id = 'devstack';
+	readonly name: string;
+	readonly allowAutoSign = true;
+
+	#serverOrigin: string;
+	#authToken: string | null;
+
+	constructor(options: DevstackSignerAdapterOptions) {
+		super();
+		try {
+			new URL(options.serverOrigin);
+		} catch {
+			throw new Error(`DevstackSignerAdapter: invalid serverOrigin "${options.serverOrigin}"`);
+		}
+		this.#serverOrigin = options.serverOrigin;
+		this.#authToken = options.token ?? null;
+		this.name = options.name ?? 'Devstack';
+	}
+
+	async initialize(): Promise<void> {
+		try {
+			const accounts = await this.#fetchAccounts();
+			this.setInitialAccounts(accounts);
+		} catch (error) {
+			if (error instanceof AuthError) {
+				console.warn('[dev-wallet] devstack adapter: unauthorized — skipping account import');
+				return;
+			}
+			console.warn('[dev-wallet] devstack adapter: initialization failed:', error);
+		}
+	}
+
+	override destroy(): void {
+		this.#authToken = null;
+		super.destroy();
+	}
+
+	async #fetchAccounts(): Promise<ManagedAccount[]> {
+		const headers: Record<string, string> = { 'Content-Type': 'application/json' };
+		if (this.#authToken !== null) {
+			headers['Authorization'] = `Bearer ${this.#authToken}`;
+		}
+		const res = await fetch(`${this.#serverOrigin}${DEVSTACK_WALLET_HTTP_PATH.ACCOUNTS}`, {
+			headers,
+		});
+		if (res.status === 401 || res.status === 403) throw new AuthError();
+		if (!res.ok) {
+			throw new Error(`Failed to fetch devstack accounts: ${res.statusText}`);
+		}
+		const { accounts } = (await res.json()) as { accounts: ServerAccountInfo[] };
+		return accounts.map((info) => {
+			const publicKey = publicKeyForScheme(info.publicKey, info.scheme);
+			const signer = new DevstackProxySigner({
+				address: info.address,
+				publicKey,
+				scheme: info.scheme,
+				serverOrigin: this.#serverOrigin,
+				authToken: this.#authToken,
+			});
+			return buildManagedAccount(signer, info.address, info.name, DEVSTACK_WALLET_FEATURES);
+		});
+	}
+}
+
+/**
+ * Pull the bearer token off a paired URL produced by the `wallet()`
+ * plugin. Returns `null` if the input is undefined, malformed, or
+ * carries a `<redacted>` placeholder (the manifest's pairUrl carries
+ * the redacted form; the real token lives in a sibling 0o600 file the
+ * consumer reads separately).
+ *
+ * The token rides in the URL fragment as `#token=<hex>`.
+ */
+export function parseDevstackToken(pairedUrl: string | undefined): string | null {
+	if (pairedUrl === undefined) return null;
+	try {
+		const url = new URL(pairedUrl);
+		const hash = url.hash; // e.g. "#token=abcd"
+		if (hash.length <= 1) return null;
+		const params = new URLSearchParams(hash.slice(1));
+		const token = params.get('token');
+		if (token === null || token === '<redacted>') return null;
+		return token;
+	} catch {
+		return null;
+	}
+}
+
+/** Narrow input — the only field the adapter consumes is
+ *  `app.wallet.{url, pairUrl}`. Codegen emits exactly this shape so
+ *  generated `dapp-kit-config.ts` doesn't have to fabricate placeholder
+ *  manifest fields (`stack.app`, `coins`, etc.) just to satisfy the
+ *  full `Manifest` type. Mirrors a slice of `AppManifest` from
+ *  `@mysten-incubation/devstack` without importing it (dev-wallet
+ *  doesn't depend on devstack — circular). */
+export interface DevstackAdapterManifest {
+	app?: {
+		wallet?: {
+			url: string;
+			pairUrl?: string;
+		};
+	};
+}
+
+/**
+ * Convenience: read the wallet-app endpoint off a devstack manifest and
+ * build a configured adapter, or return `null` when the entry isn't
+ * present (no `wallet(...)` in the stack, or it hasn't come up yet).
+ *
+ * The wallet entry's `pairUrl` carries the `#token=…` fragment used to
+ * extract the bearer token. The full `Manifest` shape from
+ * `@mysten-incubation/devstack` is structurally compatible with
+ * {@link DevstackAdapterManifest}, so
+ * `createDevstackAdapterFromManifest(devstackManifest)` typechecks
+ * without a cast.
+ */
+export function createDevstackAdapterFromManifest(
+	manifest: DevstackAdapterManifest,
+): DevstackSignerAdapter | null {
+	const wallet = manifest.app?.wallet;
+	if (wallet === undefined) return null;
+	return new DevstackSignerAdapter({
+		serverOrigin: wallet.url,
+		token: parseDevstackToken(wallet.pairUrl),
+	});
+}

package/src/adapters/devstack-paths.ts

@@ -0,0 +1,15 @@
+// Mirror of `packages/devstack/src/plugins/wallet/protocol.ts` `WalletHttpPath`.
+// Duplicated here rather than imported because devstack already
+// (peer-)depends on `@mysten-incubation/dev-wallet` for codegen-emitted
+// wallet glue, and adding the reverse edge would close the workspace
+// cycle and break turbo's build ordering.
+
+export const DEVSTACK_WALLET_HTTP_PATH = {
+	HEALTH: '/api/v1/devstack/health',
+	ACCOUNTS: '/api/v1/devstack/accounts',
+	SIGN_TRANSACTION: '/api/v1/devstack/sign-transaction',
+	SIGN_PERSONAL_MESSAGE: '/api/v1/devstack/sign-personal-message',
+} as const;
+
+export type DevstackWalletHttpPathValue =
+	(typeof DEVSTACK_WALLET_HTTP_PATH)[keyof typeof DEVSTACK_WALLET_HTTP_PATH];