clutch-hub-sdk-js 4.2.1 → 4.3.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+## [4.3.0](https://github.com/clutchprotocol/clutch-hub/compare/v4.2.1...v4.3.0) (2026-10-06)
+
+
+### Features
+
+* **sdk:** sign with a wallet (MetaMask, Trust Wallet); the demo app holds no key ([#30](https://github.com/clutchprotocol/clutch-hub/issues/30)) ([db41df0](https://github.com/clutchprotocol/clutch-hub/commit/db41df077f19340afe72fac314f36e7773486f58))
+
 ## [4.2.1](https://github.com/clutchprotocol/clutch-hub-sdk-js/compare/v4.2.0...v4.2.1) (2026-09-18)
 
 

package/README.md

@@ -41,9 +41,26 @@ await sdk.submitTransaction(signed.rawTransaction);
 
 Hash arguments (`listRideOffers`, `subscribeRideOffers`) accept the `0x`-prefixed form that `signTransaction` returns; the SDK normalizes them to the form the hub matches on.
 
+## Wallets: MetaMask, Trust Wallet
+
+A wallet keeps the key and signs a short text with `personal_sign`. Use a signer where you used a key:
+
+```javascript
+import { ClutchHubSdk, discoverInjectedWallets, connectWallet } from 'clutch-hub-sdk-js';
+
+const [wallet] = await discoverInjectedWallets();   // EIP-6963, then window.ethereum
+const signer = await connectWallet(wallet);          // the wallet asks the user to share an account
+
+const sdk = new ClutchHubSdk('http://localhost:3000', signer.address, signer, 2077);
+// ... create the unsigned transaction as above ...
+const signed = await sdk.signTransaction(unsigned, signer, { type: 'RideRequest', fare: 5_000_000n });
+```
+
+Each `signTransaction` and each login opens a prompt in the wallet. The text the wallet shows is `clutch-tx:{chainId}:{hash}` for a transaction and `clutch-auth:{chainId}:{address}:{timestamp}` for the login. The node and the Hub API accept this signature next to the signature of a private key. `createWalletSigner(provider, address)` builds a signer for a provider you already have, and `createLocalSigner(privateKey)` wraps a key. A user who says no in the wallet gives a rejection with `code: 4001`.
+
 ## Features
 
-- Client-side signing (private keys never sent to server)
+- Client-side signing (private keys never sent to server), or a wallet that keeps the key (MetaMask, Trust Wallet)
 - Full ride lifecycle: request, offer, accept, pay, cancel
 - GraphQL queries and WebSocket subscriptions
 - TypeScript types
@@ -52,7 +69,8 @@ Hash arguments (`listRideOffers`, `subscribeRideOffers`) accept the `0x`-prefixe
 
 | Category | Methods |
 |----------|---------|
-| Auth | Auto `generateToken` via `ensureAuth()` (signed challenge; needs the private key), `setPrivateKey`, `signAuthChallenge` |
+| Auth | Auto `generateToken` via `ensureAuth()` (signed challenge; needs a private key or a signer), `setPrivateKey`, `setSigner`, `signAuthChallenge` |
+| Signers | `createLocalSigner`, `createWalletSigner`, `discoverInjectedWallets`, `connectWallet`, `addressFromPrivateKey` |
 | Write | `createUnsignedRide*`, `signTransaction`, `submitTransaction` |
 | Read | `listRideRequests`, `listRideOffers`, `listActiveTrips`, `getAccountBalance`, … |
 | Live | `subscribeRideRequests`, `subscribeRideOffers`, `subscribeActiveTrips`, … |

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export * from './types.js';
 export * from './sdk.js';
+export * from './signers.js';
 export { hubGraphqlWsUrl, RIDE_REQUEST_GQL_FIELDS, RIDE_OFFER_GQL_FIELDS, ACTIVE_TRIP_GQL_FIELDS, RECENT_TRIP_GQL_FIELDS, createHubSubscriptionClient, } from './subscriptions.js';
 export type { SubscriptionHandlers } from './subscriptions.js';

package/dist/index.js

@@ -1,3 +1,4 @@
 export * from './types.js';
 export * from './sdk.js';
+export * from './signers.js';
 export { hubGraphqlWsUrl, RIDE_REQUEST_GQL_FIELDS, RIDE_OFFER_GQL_FIELDS, ACTIVE_TRIP_GQL_FIELDS, RECENT_TRIP_GQL_FIELDS, createHubSubscriptionClient, } from './subscriptions.js';

package/dist/sdk.d.ts

@@ -1,6 +1,7 @@
 import { Buffer } from 'buffer';
 import { type SubscriptionHandlers } from './subscriptions.js';
 import { AvailableRideRequest, AvailableRideOffer, AvailableActiveTrip, AvailableCompletedTrip, AvailableRecentTrip, BurnArgs, MapBounds, RideRequestArgs, RideOfferArgs, RideAcceptanceArgs, RidePayArgs, RideCancelArgs, RideRequestCancelArgs, Signature } from './types.js';
+import type { Signer } from './signers.js';
 /** Strip 0x/0X prefix - hex parsers (e.g. @noble/secp256k1) do not accept it. Exported for consumers. */
 export declare function stripHexPrefix(hex: string): string;
 /**
@@ -46,6 +47,13 @@ export declare function authChallengeHashHex(chainId: number, publicKey: string,
  * @param timestamp Unix seconds; the Hub API rejects timestamps more than ±120s from server time.
  */
 export declare function signAuthChallenge(chainId: number, publicKey: string, timestamp: number, privateKey: string): Promise<Signature>;
+/** The address of a private key: `0x` and 40 lowercase hex characters. */
+export declare function addressFromPrivateKey(privateKey: string): string;
+/**
+ * A signer for a private key held in memory. It signs the hash string, as the SDK always has.
+ * A wallet cannot hand over its key: use `createWalletSigner` for that.
+ */
+export declare function createLocalSigner(privateKey: string): Signer;
 /**
  * Represents an unsigned transaction returned by the GraphQL API.
  */
@@ -120,9 +128,10 @@ export declare class ClutchHubSdk {
     /**
      * @param apiUrl Hub API base URL.
      * @param publicKey Wallet address (0x + 40 hex) or uncompressed public key (130 hex).
-     * @param privateKey Optional wallet private key, required to obtain JWTs: `generateToken`
-     *   demands a signed proof-of-key-ownership challenge. May also be provided later via
-     *   {@link setPrivateKey}. Never sent to the API — only used for local signing.
+     * @param privateKey Optional private key, or a {@link Signer} (for example a wallet's, see
+     *   `createWalletSigner`), required to obtain JWTs: `generateToken` demands a signed
+     *   proof-of-key-ownership challenge. May also be provided later via {@link setPrivateKey}
+     *   or {@link setSigner}. A key is never sent to the API — only used for local signing.
      * @param chainId This chain's id (e.g. 2077 for the app's own config), used for the
      *   chain-bound auth challenge and as the default `expected.chainId` pin in
      *   {@link signTransaction}'s `verifyUnsignedTransaction` check. Get this from app config,
@@ -133,24 +142,33 @@ export declare class ClutchHubSdk {
      * @param options Optional settings — see {@link ClutchHubSdkOptions}. Today that is the HTTP
      *   timeout (`timeoutMs`, default {@link DEFAULT_HTTP_TIMEOUT_MS}).
      */
-    constructor(apiUrl: string, publicKey: string, privateKey?: string, chainId?: number, options?: ClutchHubSdkOptions);
+    constructor(apiUrl: string, publicKey: string, privateKey?: string | Signer, chainId?: number, options?: ClutchHubSdkOptions);
     /**
      * Get the current public key associated with this SDK instance.
      * @returns The public key string
      */
     getPublicKey(): string;
     /**
-     * Provide (or replace) the private key used to sign `generateToken` auth challenges for
-     * this SDK's public key. Stored in a module-global map keyed by publicKey — like the JWT
-     * cache — so every SDK instance and shared WebSocket connection for this wallet can
-     * authenticate. In-memory only; never sent to the API.
+     * Provide (or replace) the private key — or the {@link Signer} — used to sign `generateToken`
+     * auth challenges for this SDK's public key. Stored in a module-global map keyed by
+     * publicKey — like the JWT cache — so every SDK instance and shared WebSocket connection for
+     * this wallet can authenticate. In-memory only; a key is never sent to the API.
      */
-    setPrivateKey(privateKey: string): void;
+    setPrivateKey(privateKey: string | Signer): void;
+    /** Same as {@link setPrivateKey}, for a signer such as a wallet's (`createWalletSigner`). */
+    setSigner(signer: Signer): void;
     /**
      * Check if the SDK is currently authenticated.
      * @returns True if authenticated and token is not expired
      */
     isAuthenticated(): boolean;
+    /**
+     * True when a token for this account is cached and still good, so the next authenticated call
+     * opens no sign-in prompt. `isAuthenticated` looks at this instance only; this looks at the
+     * cache that every instance of the account shares. A poll should check it first: a wallet's
+     * sign-in prompt belongs to something the user did, never to a timer.
+     */
+    hasValidToken(): boolean;
     private get authHeaders();
     /**
      * WebSocket URL for GraphQL subscriptions (same host as REST/GraphQL HTTP).
@@ -161,6 +179,15 @@ export declare class ClutchHubSdk {
      * Call `release` when unsubscribing; last release disposes the socket.
      */
     private acquireGraphqlWsClient;
+    /**
+     * The `connection_init` payload of the shared socket: a token when there is one to send.
+     *
+     * The subscriptions are public, so a token is optional here. This runs at every connect and
+     * every reconnect (the socket retries for ever), with nobody watching, so a signer that opens a
+     * prompt (a wallet) is not asked for a signature: a token from an earlier, explicit action is
+     * still sent. A key signs silently and is asked as before.
+     */
+    private wsConnectionParams;
     /**
      * Shared graphql-ws list subscription: one multiplexed client via {@link acquireGraphqlWsClient}.
      */
@@ -208,8 +235,12 @@ export declare class ClutchHubSdk {
     createUnsignedBurn(args: BurnArgs): Promise<UnsignedTransaction>;
     /**
      * Signs a transaction and returns the signature and raw RLP-encoded payload.
+     *
+     * `privateKey` is a private key, or a {@link Signer}. A key signs the hash string. A wallet's
+     * signer asks the wallet to sign `clutch-tx:{chainId}:{hash}` with `personal_sign`: the user
+     * sees a prompt, so call this only where that is expected.
      */
-    signTransaction(unsignedTx: UnsignedTransaction, privateKey: string, expected?: ExpectedTx): Promise<Signature & {
+    signTransaction(unsignedTx: UnsignedTransaction, privateKey: string | Signer, expected?: ExpectedTx): Promise<Signature & {
         rawTransaction: string;
         txHash: string;
     }>;

package/dist/sdk.js

@@ -54,12 +54,13 @@ const globalTokenCache = new Map();
  */
 const inFlightTokenRequests = new Map();
 /**
- * Module-global private-key store keyed by `publicKey` (parallel to the JWT cache).
+ * Module-global signer store keyed by `publicKey` (parallel to the JWT cache).
  * `generateToken` requires proof of key ownership (a signed challenge), so token issuance
- * needs the wallet's private key. Keys are kept in memory only and are **never** sent to
- * the Hub API — only the challenge signature is.
+ * needs a signer for the account: a private key held in memory (`createLocalSigner`) or a
+ * wallet that signs for it (`createWalletSigner`). A key is kept in memory only and is
+ * **never** sent to the Hub API — only the challenge signature is.
  */
-const globalPrivateKeys = new Map();
+const globalSigners = new Map();
 /** Prefix of the canonical proof-of-key-ownership message signed for `generateToken`. */
 export const AUTH_CHALLENGE_PREFIX = 'clutch-auth';
 /**
@@ -106,6 +107,30 @@ async function signHashHex(hashHex, privateKey) {
 export async function signAuthChallenge(chainId, publicKey, timestamp, privateKey) {
     return signHashHex(authChallengeHashHex(chainId, publicKey, timestamp), privateKey);
 }
+/** The address of a private key: `0x` and 40 lowercase hex characters. */
+export function addressFromPrivateKey(privateKey) {
+    const publicKey = secp.getPublicKey(stripHexPrefix(privateKey), false); // 0x04 || X || Y
+    return '0x' + Buffer.from(keccak_256(publicKey.slice(1)).slice(-20)).toString('hex');
+}
+/**
+ * A signer for a private key held in memory. It signs the hash string, as the SDK always has.
+ * A wallet cannot hand over its key: use `createWalletSigner` for that.
+ */
+export function createLocalSigner(privateKey) {
+    return {
+        // A getter, so that a malformed key still fails when something is signed, as it always did,
+        // and not when the SDK is built.
+        get address() {
+            return addressFromPrivateKey(privateKey);
+        },
+        signTransaction: ({ hashHex }) => signHashHex(hashHex, privateKey),
+        signAuthChallenge: ({ hashHex }) => signHashHex(hashHex, privateKey),
+    };
+}
+/** Everywhere the SDK takes a private key it also takes a signer. */
+function toSigner(keyOrSigner) {
+    return typeof keyOrSigner === 'string' ? createLocalSigner(keyOrSigner) : keyOrSigner;
+}
 /**
  * One graphql-ws connection per hub URL + wallet; multiplex all subscriptions on it.
  * Without this, each subscribe* call opened a new socket (`lazy: false`), which explodes
@@ -120,9 +145,9 @@ function sharedGraphqlWsCacheKey(baseURL, publicKey) {
  * via the `generateToken` mutation when needed. Shared by `ensureAuth` and the WebSocket
  * `connectionParams` so all SDK instances and subscriptions share tokens.
  *
- * Token issuance signs the proof-of-key-ownership challenge, so a private key for
- * `publicKey` must have been provided (constructor or `setPrivateKey`) unless a cached
- * token is still valid.
+ * Token issuance signs the proof-of-key-ownership challenge, so a signer (or a private key)
+ * for `publicKey` must have been provided (constructor, `setPrivateKey` or `setSigner`)
+ * unless a cached token is still valid. With a wallet this is the prompt the user sees.
  */
 async function ensureTokenInCacheForPublicKey(publicKey, apiClient, chainId) {
     const now = Date.now();
@@ -135,9 +160,9 @@ async function ensureTokenInCacheForPublicKey(publicKey, apiClient, chainId) {
     if (existingInFlight) {
         return existingInFlight;
     }
-    const privateKey = globalPrivateKeys.get(publicKey);
-    if (!privateKey) {
-        throw new Error(`ClutchHubSdk: generateToken requires proof of key ownership; provide the private key for ${publicKey} via the ClutchHubSdk constructor or setPrivateKey().`);
+    const signer = globalSigners.get(publicKey);
+    if (!signer) {
+        throw new Error(`ClutchHubSdk: generateToken requires proof of key ownership; provide the private key (or a signer) for ${publicKey} via the ClutchHubSdk constructor, setPrivateKey() or setSigner().`);
     }
     const query = `
     mutation GenerateToken($publicKey: String!, $timestamp: Int!, $signature: AuthSignatureInput!) {
@@ -149,7 +174,10 @@ async function ensureTokenInCacheForPublicKey(publicKey, apiClient, chainId) {
   `;
     const requestPromise = (async () => {
         const timestamp = Math.floor(Date.now() / 1000);
-        const signature = await signAuthChallenge(chainId, publicKey, timestamp, privateKey);
+        const signature = await signer.signAuthChallenge({
+            message: buildAuthChallengeMessage(chainId, publicKey, timestamp),
+            hashHex: authChallengeHashHex(chainId, publicKey, timestamp),
+        });
         const response = await apiClient.post('/graphql', {
             query,
             variables: {
@@ -274,9 +302,10 @@ export class ClutchHubSdk {
     /**
      * @param apiUrl Hub API base URL.
      * @param publicKey Wallet address (0x + 40 hex) or uncompressed public key (130 hex).
-     * @param privateKey Optional wallet private key, required to obtain JWTs: `generateToken`
-     *   demands a signed proof-of-key-ownership challenge. May also be provided later via
-     *   {@link setPrivateKey}. Never sent to the API — only used for local signing.
+     * @param privateKey Optional private key, or a {@link Signer} (for example a wallet's, see
+     *   `createWalletSigner`), required to obtain JWTs: `generateToken` demands a signed
+     *   proof-of-key-ownership challenge. May also be provided later via {@link setPrivateKey}
+     *   or {@link setSigner}. A key is never sent to the API — only used for local signing.
      * @param chainId This chain's id (e.g. 2077 for the app's own config), used for the
      *   chain-bound auth challenge and as the default `expected.chainId` pin in
      *   {@link signTransaction}'s `verifyUnsignedTransaction` check. Get this from app config,
@@ -298,7 +327,7 @@ export class ClutchHubSdk {
         this.chainId = chainId ?? 0;
         this.chainIdConfigured = chainId !== undefined;
         if (privateKey) {
-            globalPrivateKeys.set(publicKey, privateKey);
+            globalSigners.set(publicKey, toSigner(privateKey));
         }
     }
     /**
@@ -309,13 +338,17 @@ export class ClutchHubSdk {
         return this.publicKey;
     }
     /**
-     * Provide (or replace) the private key used to sign `generateToken` auth challenges for
-     * this SDK's public key. Stored in a module-global map keyed by publicKey — like the JWT
-     * cache — so every SDK instance and shared WebSocket connection for this wallet can
-     * authenticate. In-memory only; never sent to the API.
+     * Provide (or replace) the private key — or the {@link Signer} — used to sign `generateToken`
+     * auth challenges for this SDK's public key. Stored in a module-global map keyed by
+     * publicKey — like the JWT cache — so every SDK instance and shared WebSocket connection for
+     * this wallet can authenticate. In-memory only; a key is never sent to the API.
      */
     setPrivateKey(privateKey) {
-        globalPrivateKeys.set(this.publicKey, privateKey);
+        globalSigners.set(this.publicKey, toSigner(privateKey));
+    }
+    /** Same as {@link setPrivateKey}, for a signer such as a wallet's (`createWalletSigner`). */
+    setSigner(signer) {
+        globalSigners.set(this.publicKey, signer);
     }
     /**
      * Check if the SDK is currently authenticated.
@@ -326,6 +359,16 @@ export class ClutchHubSdk {
         const bufferTime = 30000; // 30 seconds
         return !!(this.token && now < (this.tokenExpireTime - bufferTime));
     }
+    /**
+     * True when a token for this account is cached and still good, so the next authenticated call
+     * opens no sign-in prompt. `isAuthenticated` looks at this instance only; this looks at the
+     * cache that every instance of the account shares. A poll should check it first: a wallet's
+     * sign-in prompt belongs to something the user did, never to a timer.
+     */
+    hasValidToken() {
+        const cached = globalTokenCache.get(this.publicKey);
+        return !!cached && Date.now() < cached.expireTimeMs - 30000;
+    }
     get authHeaders() {
         return this.token ? { Authorization: `Bearer ${this.token}` } : {};
     }
@@ -351,21 +394,9 @@ export class ClutchHubSdk {
         const key = sharedGraphqlWsCacheKey(base, this.publicKey);
         let entry = sharedGraphqlWsClients.get(key);
         if (!entry) {
-            const pk = this.publicKey;
-            const apiClient = this.apiClient;
-            const chainId = this.chainId;
             const client = createHubSubscriptionClient({
                 url: hubGraphqlWsUrl(base),
-                connectionParams: async () => {
-                    try {
-                        await ensureTokenInCacheForPublicKey(pk, apiClient, chainId);
-                    }
-                    catch {
-                        /* public list subscriptions work without JWT */
-                    }
-                    const c = globalTokenCache.get(pk);
-                    return c?.token ? { Authorization: `Bearer ${c.token}` } : {};
-                },
+                connectionParams: () => this.wsConnectionParams(),
             });
             entry = { client, refcount: 0 };
             sharedGraphqlWsClients.set(key, entry);
@@ -384,6 +415,29 @@ export class ClutchHubSdk {
         };
         return { client: entry.client, release };
     }
+    /**
+     * The `connection_init` payload of the shared socket: a token when there is one to send.
+     *
+     * The subscriptions are public, so a token is optional here. This runs at every connect and
+     * every reconnect (the socket retries for ever), with nobody watching, so a signer that opens a
+     * prompt (a wallet) is not asked for a signature: a token from an earlier, explicit action is
+     * still sent. A key signs silently and is asked as before.
+     */
+    async wsConnectionParams() {
+        const pk = this.publicKey;
+        if (!globalSigners.get(pk)?.interactive) {
+            try {
+                await ensureTokenInCacheForPublicKey(pk, this.apiClient, this.chainId);
+            }
+            catch {
+                /* public list subscriptions work without JWT */
+            }
+        }
+        const cached = globalTokenCache.get(pk);
+        return cached?.token && Date.now() < cached.expireTimeMs
+            ? { Authorization: `Bearer ${cached.token}` }
+            : {};
+    }
     /**
      * Shared graphql-ws list subscription: one multiplexed client via {@link acquireGraphqlWsClient}.
      */
@@ -579,6 +633,10 @@ export class ClutchHubSdk {
     }
     /**
      * Signs a transaction and returns the signature and raw RLP-encoded payload.
+     *
+     * `privateKey` is a private key, or a {@link Signer}. A key signs the hash string. A wallet's
+     * signer asks the wallet to sign `clutch-tx:{chainId}:{hash}` with `personal_sign`: the user
+     * sees a prompt, so call this only where that is expected.
      */
     async signTransaction(unsignedTx, privateKey, expected) {
         if (expected) {
@@ -619,7 +677,10 @@ export class ClutchHubSdk {
         const hashBytes = keccak_256(unsignedPayload);
         const rawHashHex = Buffer.from(hashBytes).toString('hex');
         // Sign the transaction hash
-        const signature = await signHashHex(rawHashHex, privateKey);
+        const signature = await toSigner(privateKey).signTransaction({
+            hashHex: rawHashHex,
+            chainId: unsignedTx.chain_id,
+        });
         const rNo0x = stripHexPrefix(signature.r);
         const sNo0x = stripHexPrefix(signature.s);
         // RLP-encode full signed transaction to match Rust: [from, nonce, chain_id, r, s, v, hash, data]

package/dist/signers.d.ts

@@ -0,0 +1,85 @@
+import type { Signature } from './types.js';
+/** What a signer is asked to sign to send a transaction. */
+export interface TransactionSigningRequest {
+    /** Keccak-256 of the unsigned transaction: 64 lowercase hex characters, no `0x`. */
+    hashHex: string;
+    /** The chain the transaction is for. A wallet's prompt names it. */
+    chainId: number;
+}
+/** What a signer is asked to sign to prove it owns a key to the Hub API. */
+export interface AuthChallengeSigningRequest {
+    /** The readable challenge, `clutch-auth:{chainId}:{publicKey}:{timestamp}`. */
+    message: string;
+    /** Keccak-256 of `message`: 64 lowercase hex characters, no `0x`. */
+    hashHex: string;
+}
+/** Something that can sign for one account. */
+export interface Signer {
+    /** The account this signer signs for: `0x` and 40 lowercase hex characters. */
+    readonly address: string;
+    /**
+     * True when signing opens a prompt for a person (a wallet). The SDK never asks such a signer for
+     * a signature in the background, for example when a subscription reconnects; only a call the
+     * app makes (create or sign a transaction) can open a prompt.
+     */
+    readonly interactive?: boolean;
+    /** Sign a transaction. A key signs the hash string; a wallet signs `walletTransactionText`. */
+    signTransaction(request: TransactionSigningRequest): Promise<Signature>;
+    /** Sign the Hub API's proof-of-key-ownership challenge. A key signs its hash; a wallet signs the message. */
+    signAuthChallenge(request: AuthChallengeSigningRequest): Promise<Signature>;
+}
+/**
+ * The part of an EIP-1193 provider (`window.ethereum`, an EIP-6963 provider) that the SDK uses.
+ * `on` and `removeListener` are there for apps that watch `accountsChanged`.
+ */
+export interface Eip1193Provider {
+    request(args: {
+        method: string;
+        params?: unknown[];
+    }): Promise<unknown>;
+    on?(event: string, listener: (...args: any[]) => void): void;
+    removeListener?(event: string, listener: (...args: any[]) => void): void;
+}
+/** The text a wallet signs for a transaction. The hash is written without `0x`, in lower case. */
+export declare function walletTransactionText(chainId: number, hashHex: string): string;
+/** What `personal_sign` hashes and signs: `Keccak256("\x19Ethereum Signed Message:\n" + length + text)`. */
+export declare function personalSignDigest(text: string): Uint8Array;
+/**
+ * A signer that asks a wallet to sign with `personal_sign`. The wallet shows the user the text,
+ * and keeps the key. `address` is the account to sign for; it is lowercased, because the hash of a
+ * transaction commits to `from` and the node reads `from` in lower case.
+ *
+ * The signature is checked here before it is returned: a wallet that signs with another account
+ * (the user switched accounts) would otherwise be found out later, as a refusal from the node
+ * that does not say why.
+ */
+export declare function createWalletSigner(provider: Eip1193Provider, address: string): Signer;
+/** A wallet found in the page. */
+export interface InjectedWallet {
+    /** The EIP-6963 `rdns` (for example `io.metamask`), or `injected-0` for a bare `window.ethereum`. */
+    id: string;
+    name: string;
+    /** A `data:` image address from the wallet, when it announced one. */
+    icon?: string;
+    provider: Eip1193Provider;
+}
+export interface WalletDiscoveryOptions {
+    /** Where to look. Default: `window`. */
+    host?: EventTarget & {
+        ethereum?: unknown;
+    };
+    /** How long to listen for EIP-6963 announcements, in milliseconds. Default: 300. */
+    timeoutMs?: number;
+}
+/**
+ * The wallets in this page. A wallet that follows EIP-6963 announces itself, so several can be
+ * listed side by side; one that only sets `window.ethereum` (older wallets, some in-app browsers)
+ * is added when no announced wallet is that same provider. Returns an empty list when there is no
+ * wallet, or when there is no page (Node).
+ */
+export declare function discoverInjectedWallets(options?: WalletDiscoveryOptions): Promise<InjectedWallet[]>;
+/**
+ * Ask a wallet to share its account (the wallet shows its own prompt) and return a signer for it.
+ * Rejects when the user says no (the provider's error, code 4001) or when no account is shared.
+ */
+export declare function connectWallet(wallet: InjectedWallet): Promise<Signer>;

package/dist/signers.js

@@ -0,0 +1,161 @@
+import { Buffer } from 'buffer';
+import { keccak_256 } from '@noble/hashes/sha3';
+import * as secp from '@noble/secp256k1';
+/*
+ * Who signs a transaction.
+ *
+ * The SDK used to take a private key string and sign with it. A wallet (MetaMask, Trust Wallet)
+ * never gives its key to a page, so the SDK now takes a `Signer`: an object that can be asked for
+ * a signature. A key in memory is one kind of signer (`createLocalSigner`, in sdk.ts); a wallet is
+ * another (`createWalletSigner`, here). Everywhere the SDK took a key it still takes a key string.
+ *
+ * A wallet will not sign a bare hash, so it signs a short readable text with `personal_sign`
+ * (EIP-191), which hashes `"\x19Ethereum Signed Message:\n" + length + text`. The node and the Hub
+ * API accept that signature next to the old one. The texts below are the contract with them:
+ *
+ *   transaction  clutch-tx:{chainId}:{hash}              hash = 64 lowercase hex, no 0x
+ *   login        clutch-auth:{chainId}:{publicKey}:{timestamp}
+ */
+/** Strip a 0x/0X prefix. A copy of `stripHexPrefix` in sdk.ts, which imports this file. */
+function strip0x(hex) {
+    return hex.replace(/^0x/i, '');
+}
+/** The text a wallet signs for a transaction. The hash is written without `0x`, in lower case. */
+export function walletTransactionText(chainId, hashHex) {
+    return `clutch-tx:${chainId}:${strip0x(hashHex).toLowerCase()}`;
+}
+/** What `personal_sign` hashes and signs: `Keccak256("\x19Ethereum Signed Message:\n" + length + text)`. */
+export function personalSignDigest(text) {
+    const body = Buffer.from(text, 'utf8');
+    const prefix = Buffer.from(`\x19Ethereum Signed Message:\n${body.length}`, 'utf8');
+    return keccak_256(Buffer.concat([prefix, body]));
+}
+/**
+ * `r`, `s` and `v` from a wallet's answer: `0x` and 130 hex characters (65 bytes). Some wallets
+ * answer with a recovery id of 0 or 1 instead of 27 or 28; the node reads only 27 and 28.
+ */
+function parseWalletSignature(raw) {
+    if (typeof raw !== 'string' || !/^0x[0-9a-fA-F]{130}$/.test(raw)) {
+        throw new Error('the wallet answered with a signature the SDK cannot read (expected 65 bytes of hex)');
+    }
+    const hex = raw.slice(2).toLowerCase();
+    let v = parseInt(hex.slice(128, 130), 16);
+    if (v < 27) {
+        v += 27;
+    }
+    if (v !== 27 && v !== 28) {
+        throw new Error(`the wallet answered with an unexpected recovery id (${v})`);
+    }
+    return { r: '0x' + hex.slice(0, 64), s: '0x' + hex.slice(64, 128), v };
+}
+/** The address a signature over `digest` came from, or `null` when it does not recover to one. */
+function recoverAddress(digest, signature) {
+    try {
+        const compact = strip0x(signature.r).padStart(64, '0') + strip0x(signature.s).padStart(64, '0');
+        const point = secp.Signature.fromCompact(compact)
+            .addRecoveryBit(signature.v - 27)
+            .recoverPublicKey(digest);
+        return '0x' + Buffer.from(keccak_256(point.toRawBytes(false).slice(1)).slice(-20)).toString('hex');
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * A signer that asks a wallet to sign with `personal_sign`. The wallet shows the user the text,
+ * and keeps the key. `address` is the account to sign for; it is lowercased, because the hash of a
+ * transaction commits to `from` and the node reads `from` in lower case.
+ *
+ * The signature is checked here before it is returned: a wallet that signs with another account
+ * (the user switched accounts) would otherwise be found out later, as a refusal from the node
+ * that does not say why.
+ */
+export function createWalletSigner(provider, address) {
+    const account = address.toLowerCase();
+    async function personalSign(text) {
+        // Always hex: a text that starts with "0x" would be read by the wallet as bytes, not text.
+        const message = '0x' + Buffer.from(text, 'utf8').toString('hex');
+        const raw = await provider.request({ method: 'personal_sign', params: [message, account] });
+        const signature = parseWalletSignature(raw);
+        const signedBy = recoverAddress(personalSignDigest(text), signature);
+        if (signedBy !== account) {
+            throw new Error(`the wallet signed with ${signedBy ?? 'an account that cannot be read'}, not ${account}: switch to ${account} in the wallet and try again`);
+        }
+        return signature;
+    }
+    return {
+        address: account,
+        interactive: true,
+        signTransaction: ({ hashHex, chainId }) => personalSign(walletTransactionText(chainId, hashHex)),
+        signAuthChallenge: ({ message }) => personalSign(message),
+    };
+}
+function isProvider(value) {
+    return !!value && typeof value.request === 'function';
+}
+/** A name for a provider that did not announce one. Trust Wallet sets `isMetaMask` too, so it is checked first. */
+function legacyName(provider) {
+    const flags = provider;
+    if (flags.isTrust || flags.isTrustWallet)
+        return 'Trust Wallet';
+    if (flags.isMetaMask)
+        return 'MetaMask';
+    if (flags.isCoinbaseWallet)
+        return 'Coinbase Wallet';
+    return 'Browser wallet';
+}
+/**
+ * The wallets in this page. A wallet that follows EIP-6963 announces itself, so several can be
+ * listed side by side; one that only sets `window.ethereum` (older wallets, some in-app browsers)
+ * is added when no announced wallet is that same provider. Returns an empty list when there is no
+ * wallet, or when there is no page (Node).
+ */
+export async function discoverInjectedWallets(options = {}) {
+    const host = options.host ?? (typeof window !== 'undefined' ? window : undefined);
+    if (!host) {
+        return [];
+    }
+    const found = new Map();
+    const onAnnounce = (event) => {
+        const detail = event.detail;
+        if (!detail || !isProvider(detail.provider)) {
+            return;
+        }
+        const info = detail.info ?? {};
+        const id = info.rdns || info.uuid || info.name || `announced-${found.size}`;
+        if (!found.has(id)) {
+            found.set(id, { id, name: info.name || id, icon: info.icon, provider: detail.provider });
+        }
+    };
+    host.addEventListener('eip6963:announceProvider', onAnnounce);
+    try {
+        host.dispatchEvent(new Event('eip6963:requestProvider'));
+        await new Promise((resolve) => setTimeout(resolve, options.timeoutMs ?? 300));
+    }
+    finally {
+        host.removeEventListener('eip6963:announceProvider', onAnnounce);
+    }
+    const wallets = [...found.values()];
+    const ethereum = host.ethereum;
+    if (isProvider(ethereum)) {
+        const list = Array.isArray(ethereum.providers) && ethereum.providers.length > 0 ? ethereum.providers : [ethereum];
+        list.filter(isProvider).forEach((provider, index) => {
+            if (!wallets.some((wallet) => wallet.provider === provider)) {
+                wallets.push({ id: `injected-${index}`, name: legacyName(provider), provider });
+            }
+        });
+    }
+    return wallets;
+}
+/**
+ * Ask a wallet to share its account (the wallet shows its own prompt) and return a signer for it.
+ * Rejects when the user says no (the provider's error, code 4001) or when no account is shared.
+ */
+export async function connectWallet(wallet) {
+    const accounts = await wallet.provider.request({ method: 'eth_requestAccounts' });
+    const first = Array.isArray(accounts) ? accounts[0] : undefined;
+    if (typeof first !== 'string' || !/^0x[0-9a-fA-F]{40}$/.test(first)) {
+        throw new Error('the wallet did not share an account');
+    }
+    return createWalletSigner(wallet.provider, first);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clutch-hub-sdk-js",
-  "version": "4.2.1",
+  "version": "4.3.0",
   "description": "JavaScript SDK for interacting with the clutch-hub-api",
   "main": "dist/index.js",
   "module": "dist/index.js",
@@ -26,13 +26,13 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/clutchprotocol/clutch-hub-sdk-js.git",
+    "url": "https://github.com/clutchprotocol/clutch-hub.git",
     "directory": "packages/sdk"
   },
   "bugs": {
-    "url": "https://github.com/clutchprotocol/clutch-hub-sdk-js/issues"
+    "url": "https://github.com/clutchprotocol/clutch-hub/issues"
   },
-  "homepage": "https://github.com/clutchprotocol/clutch-hub-sdk-js/tree/main/packages/sdk#readme",
+  "homepage": "https://github.com/clutchprotocol/clutch-hub/tree/main/packages/sdk#readme",
   "dependencies": {
     "@noble/hashes": "^1.8.0",
     "@noble/secp256k1": "^2.2.3",

package/src/index.ts

@@ -1,5 +1,6 @@
 export * from './types.js';
 export * from './sdk.js';
+export * from './signers.js';
 export {
   hubGraphqlWsUrl,
   RIDE_REQUEST_GQL_FIELDS,

package/src/sdk.ts

@@ -29,6 +29,7 @@ import {
   RideRequestCancelArgs,
   Signature,
 } from './types.js';
+import type { Signer } from './signers.js';
 
 /** Strip 0x/0X prefix - hex parsers (e.g. @noble/secp256k1) do not accept it. Exported for consumers. */
 export function stripHexPrefix(hex: string): string {
@@ -106,12 +107,13 @@ const globalTokenCache = new Map<string, TokenCacheEntry>();
 const inFlightTokenRequests = new Map<string, Promise<TokenCacheEntry>>();
 
 /**
- * Module-global private-key store keyed by `publicKey` (parallel to the JWT cache).
+ * Module-global signer store keyed by `publicKey` (parallel to the JWT cache).
  * `generateToken` requires proof of key ownership (a signed challenge), so token issuance
- * needs the wallet's private key. Keys are kept in memory only and are **never** sent to
- * the Hub API — only the challenge signature is.
+ * needs a signer for the account: a private key held in memory (`createLocalSigner`) or a
+ * wallet that signs for it (`createWalletSigner`). A key is kept in memory only and is
+ * **never** sent to the Hub API — only the challenge signature is.
  */
-const globalPrivateKeys = new Map<string, string>();
+const globalSigners = new Map<string, Signer>();
 
 /** Prefix of the canonical proof-of-key-ownership message signed for `generateToken`. */
 export const AUTH_CHALLENGE_PREFIX = 'clutch-auth';
@@ -169,6 +171,33 @@ export async function signAuthChallenge(
   return signHashHex(authChallengeHashHex(chainId, publicKey, timestamp), privateKey);
 }
 
+/** The address of a private key: `0x` and 40 lowercase hex characters. */
+export function addressFromPrivateKey(privateKey: string): string {
+  const publicKey = secp.getPublicKey(stripHexPrefix(privateKey), false); // 0x04 || X || Y
+  return '0x' + Buffer.from(keccak_256(publicKey.slice(1)).slice(-20)).toString('hex');
+}
+
+/**
+ * A signer for a private key held in memory. It signs the hash string, as the SDK always has.
+ * A wallet cannot hand over its key: use `createWalletSigner` for that.
+ */
+export function createLocalSigner(privateKey: string): Signer {
+  return {
+    // A getter, so that a malformed key still fails when something is signed, as it always did,
+    // and not when the SDK is built.
+    get address() {
+      return addressFromPrivateKey(privateKey);
+    },
+    signTransaction: ({ hashHex }) => signHashHex(hashHex, privateKey),
+    signAuthChallenge: ({ hashHex }) => signHashHex(hashHex, privateKey),
+  };
+}
+
+/** Everywhere the SDK takes a private key it also takes a signer. */
+function toSigner(keyOrSigner: string | Signer): Signer {
+  return typeof keyOrSigner === 'string' ? createLocalSigner(keyOrSigner) : keyOrSigner;
+}
+
 type SharedGraphqlWsEntry = { client: Client; refcount: number };
 
 /**
@@ -187,9 +216,9 @@ function sharedGraphqlWsCacheKey(baseURL: string, publicKey: string): string {
  * via the `generateToken` mutation when needed. Shared by `ensureAuth` and the WebSocket
  * `connectionParams` so all SDK instances and subscriptions share tokens.
  *
- * Token issuance signs the proof-of-key-ownership challenge, so a private key for
- * `publicKey` must have been provided (constructor or `setPrivateKey`) unless a cached
- * token is still valid.
+ * Token issuance signs the proof-of-key-ownership challenge, so a signer (or a private key)
+ * for `publicKey` must have been provided (constructor, `setPrivateKey` or `setSigner`)
+ * unless a cached token is still valid. With a wallet this is the prompt the user sees.
  */
 async function ensureTokenInCacheForPublicKey(
   publicKey: string,
@@ -209,10 +238,10 @@ async function ensureTokenInCacheForPublicKey(
     return existingInFlight;
   }
 
-  const privateKey = globalPrivateKeys.get(publicKey);
-  if (!privateKey) {
+  const signer = globalSigners.get(publicKey);
+  if (!signer) {
     throw new Error(
-      `ClutchHubSdk: generateToken requires proof of key ownership; provide the private key for ${publicKey} via the ClutchHubSdk constructor or setPrivateKey().`
+      `ClutchHubSdk: generateToken requires proof of key ownership; provide the private key (or a signer) for ${publicKey} via the ClutchHubSdk constructor, setPrivateKey() or setSigner().`
     );
   }
 
@@ -227,7 +256,10 @@ async function ensureTokenInCacheForPublicKey(
 
   const requestPromise: Promise<TokenCacheEntry> = (async () => {
     const timestamp = Math.floor(Date.now() / 1000);
-    const signature = await signAuthChallenge(chainId, publicKey, timestamp, privateKey);
+    const signature = await signer.signAuthChallenge({
+      message: buildAuthChallengeMessage(chainId, publicKey, timestamp),
+      hashHex: authChallengeHashHex(chainId, publicKey, timestamp),
+    });
     const response = await apiClient.post<{ data?: unknown; errors?: { message: string }[] }>(
       '/graphql',
       {
@@ -426,9 +458,10 @@ export class ClutchHubSdk {
   /**
    * @param apiUrl Hub API base URL.
    * @param publicKey Wallet address (0x + 40 hex) or uncompressed public key (130 hex).
-   * @param privateKey Optional wallet private key, required to obtain JWTs: `generateToken`
-   *   demands a signed proof-of-key-ownership challenge. May also be provided later via
-   *   {@link setPrivateKey}. Never sent to the API — only used for local signing.
+   * @param privateKey Optional private key, or a {@link Signer} (for example a wallet's, see
+   *   `createWalletSigner`), required to obtain JWTs: `generateToken` demands a signed
+   *   proof-of-key-ownership challenge. May also be provided later via {@link setPrivateKey}
+   *   or {@link setSigner}. A key is never sent to the API — only used for local signing.
    * @param chainId This chain's id (e.g. 2077 for the app's own config), used for the
    *   chain-bound auth challenge and as the default `expected.chainId` pin in
    *   {@link signTransaction}'s `verifyUnsignedTransaction` check. Get this from app config,
@@ -442,7 +475,7 @@ export class ClutchHubSdk {
   constructor(
     apiUrl: string,
     publicKey: string,
-    privateKey?: string,
+    privateKey?: string | Signer,
     chainId?: number,
     options: ClutchHubSdkOptions = {}
   ) {
@@ -454,7 +487,7 @@ export class ClutchHubSdk {
     this.chainId = chainId ?? 0;
     this.chainIdConfigured = chainId !== undefined;
     if (privateKey) {
-      globalPrivateKeys.set(publicKey, privateKey);
+      globalSigners.set(publicKey, toSigner(privateKey));
     }
   }
 
@@ -467,13 +500,18 @@ export class ClutchHubSdk {
   }
 
   /**
-   * Provide (or replace) the private key used to sign `generateToken` auth challenges for
-   * this SDK's public key. Stored in a module-global map keyed by publicKey — like the JWT
-   * cache — so every SDK instance and shared WebSocket connection for this wallet can
-   * authenticate. In-memory only; never sent to the API.
+   * Provide (or replace) the private key — or the {@link Signer} — used to sign `generateToken`
+   * auth challenges for this SDK's public key. Stored in a module-global map keyed by
+   * publicKey — like the JWT cache — so every SDK instance and shared WebSocket connection for
+   * this wallet can authenticate. In-memory only; a key is never sent to the API.
    */
-  public setPrivateKey(privateKey: string): void {
-    globalPrivateKeys.set(this.publicKey, privateKey);
+  public setPrivateKey(privateKey: string | Signer): void {
+    globalSigners.set(this.publicKey, toSigner(privateKey));
+  }
+
+  /** Same as {@link setPrivateKey}, for a signer such as a wallet's (`createWalletSigner`). */
+  public setSigner(signer: Signer): void {
+    globalSigners.set(this.publicKey, signer);
   }
 
   /**
@@ -486,6 +524,17 @@ export class ClutchHubSdk {
     return !!(this.token && now < (this.tokenExpireTime - bufferTime));
   }
 
+  /**
+   * True when a token for this account is cached and still good, so the next authenticated call
+   * opens no sign-in prompt. `isAuthenticated` looks at this instance only; this looks at the
+   * cache that every instance of the account shares. A poll should check it first: a wallet's
+   * sign-in prompt belongs to something the user did, never to a timer.
+   */
+  public hasValidToken(): boolean {
+    const cached = globalTokenCache.get(this.publicKey);
+    return !!cached && Date.now() < cached.expireTimeMs - 30000;
+  }
+
   private get authHeaders(): Record<string, string> {
     return this.token ? { Authorization: `Bearer ${this.token}` } : {};
   }
@@ -513,20 +562,9 @@ export class ClutchHubSdk {
     const key = sharedGraphqlWsCacheKey(base, this.publicKey);
     let entry = sharedGraphqlWsClients.get(key);
     if (!entry) {
-      const pk = this.publicKey;
-      const apiClient = this.apiClient;
-      const chainId = this.chainId;
       const client = createHubSubscriptionClient({
         url: hubGraphqlWsUrl(base),
-        connectionParams: async () => {
-          try {
-            await ensureTokenInCacheForPublicKey(pk, apiClient, chainId);
-          } catch {
-            /* public list subscriptions work without JWT */
-          }
-          const c = globalTokenCache.get(pk);
-          return c?.token ? { Authorization: `Bearer ${c.token}` } : {};
-        },
+        connectionParams: () => this.wsConnectionParams(),
       });
       entry = { client, refcount: 0 };
       sharedGraphqlWsClients.set(key, entry);
@@ -546,6 +584,29 @@ export class ClutchHubSdk {
     return { client: entry.client, release };
   }
 
+  /**
+   * The `connection_init` payload of the shared socket: a token when there is one to send.
+   *
+   * The subscriptions are public, so a token is optional here. This runs at every connect and
+   * every reconnect (the socket retries for ever), with nobody watching, so a signer that opens a
+   * prompt (a wallet) is not asked for a signature: a token from an earlier, explicit action is
+   * still sent. A key signs silently and is asked as before.
+   */
+  private async wsConnectionParams(): Promise<Record<string, string>> {
+    const pk = this.publicKey;
+    if (!globalSigners.get(pk)?.interactive) {
+      try {
+        await ensureTokenInCacheForPublicKey(pk, this.apiClient, this.chainId);
+      } catch {
+        /* public list subscriptions work without JWT */
+      }
+    }
+    const cached = globalTokenCache.get(pk);
+    return cached?.token && Date.now() < cached.expireTimeMs
+      ? { Authorization: `Bearer ${cached.token}` }
+      : {};
+  }
+
   /**
    * Shared graphql-ws list subscription: one multiplexed client via {@link acquireGraphqlWsClient}.
    */
@@ -785,10 +846,14 @@ export class ClutchHubSdk {
 
   /**
    * Signs a transaction and returns the signature and raw RLP-encoded payload.
+   *
+   * `privateKey` is a private key, or a {@link Signer}. A key signs the hash string. A wallet's
+   * signer asks the wallet to sign `clutch-tx:{chainId}:{hash}` with `personal_sign`: the user
+   * sees a prompt, so call this only where that is expected.
    */
   public async signTransaction(
     unsignedTx: UnsignedTransaction,
-    privateKey: string,
+    privateKey: string | Signer,
     expected?: ExpectedTx
   ): Promise<Signature & { rawTransaction: string, txHash: string }> {
     if (expected) {
@@ -835,7 +900,10 @@ export class ClutchHubSdk {
     const rawHashHex = Buffer.from(hashBytes).toString('hex');
 
     // Sign the transaction hash
-    const signature = await signHashHex(rawHashHex, privateKey);
+    const signature = await toSigner(privateKey).signTransaction({
+      hashHex: rawHashHex,
+      chainId: unsignedTx.chain_id,
+    });
     const rNo0x = stripHexPrefix(signature.r);
     const sNo0x = stripHexPrefix(signature.s);
 

package/src/signers.ts

@@ -0,0 +1,235 @@
+import { Buffer } from 'buffer';
+import { keccak_256 } from '@noble/hashes/sha3';
+import * as secp from '@noble/secp256k1';
+import type { Signature } from './types.js';
+
+/*
+ * Who signs a transaction.
+ *
+ * The SDK used to take a private key string and sign with it. A wallet (MetaMask, Trust Wallet)
+ * never gives its key to a page, so the SDK now takes a `Signer`: an object that can be asked for
+ * a signature. A key in memory is one kind of signer (`createLocalSigner`, in sdk.ts); a wallet is
+ * another (`createWalletSigner`, here). Everywhere the SDK took a key it still takes a key string.
+ *
+ * A wallet will not sign a bare hash, so it signs a short readable text with `personal_sign`
+ * (EIP-191), which hashes `"\x19Ethereum Signed Message:\n" + length + text`. The node and the Hub
+ * API accept that signature next to the old one. The texts below are the contract with them:
+ *
+ *   transaction  clutch-tx:{chainId}:{hash}              hash = 64 lowercase hex, no 0x
+ *   login        clutch-auth:{chainId}:{publicKey}:{timestamp}
+ */
+
+/** Strip a 0x/0X prefix. A copy of `stripHexPrefix` in sdk.ts, which imports this file. */
+function strip0x(hex: string): string {
+  return hex.replace(/^0x/i, '');
+}
+
+/** What a signer is asked to sign to send a transaction. */
+export interface TransactionSigningRequest {
+  /** Keccak-256 of the unsigned transaction: 64 lowercase hex characters, no `0x`. */
+  hashHex: string;
+  /** The chain the transaction is for. A wallet's prompt names it. */
+  chainId: number;
+}
+
+/** What a signer is asked to sign to prove it owns a key to the Hub API. */
+export interface AuthChallengeSigningRequest {
+  /** The readable challenge, `clutch-auth:{chainId}:{publicKey}:{timestamp}`. */
+  message: string;
+  /** Keccak-256 of `message`: 64 lowercase hex characters, no `0x`. */
+  hashHex: string;
+}
+
+/** Something that can sign for one account. */
+export interface Signer {
+  /** The account this signer signs for: `0x` and 40 lowercase hex characters. */
+  readonly address: string;
+  /**
+   * True when signing opens a prompt for a person (a wallet). The SDK never asks such a signer for
+   * a signature in the background, for example when a subscription reconnects; only a call the
+   * app makes (create or sign a transaction) can open a prompt.
+   */
+  readonly interactive?: boolean;
+  /** Sign a transaction. A key signs the hash string; a wallet signs `walletTransactionText`. */
+  signTransaction(request: TransactionSigningRequest): Promise<Signature>;
+  /** Sign the Hub API's proof-of-key-ownership challenge. A key signs its hash; a wallet signs the message. */
+  signAuthChallenge(request: AuthChallengeSigningRequest): Promise<Signature>;
+}
+
+/**
+ * The part of an EIP-1193 provider (`window.ethereum`, an EIP-6963 provider) that the SDK uses.
+ * `on` and `removeListener` are there for apps that watch `accountsChanged`.
+ */
+export interface Eip1193Provider {
+  request(args: { method: string; params?: unknown[] }): Promise<unknown>;
+  on?(event: string, listener: (...args: any[]) => void): void;
+  removeListener?(event: string, listener: (...args: any[]) => void): void;
+}
+
+/** The text a wallet signs for a transaction. The hash is written without `0x`, in lower case. */
+export function walletTransactionText(chainId: number, hashHex: string): string {
+  return `clutch-tx:${chainId}:${strip0x(hashHex).toLowerCase()}`;
+}
+
+/** What `personal_sign` hashes and signs: `Keccak256("\x19Ethereum Signed Message:\n" + length + text)`. */
+export function personalSignDigest(text: string): Uint8Array {
+  const body = Buffer.from(text, 'utf8');
+  const prefix = Buffer.from(`\x19Ethereum Signed Message:\n${body.length}`, 'utf8');
+  return keccak_256(Buffer.concat([prefix, body]));
+}
+
+/**
+ * `r`, `s` and `v` from a wallet's answer: `0x` and 130 hex characters (65 bytes). Some wallets
+ * answer with a recovery id of 0 or 1 instead of 27 or 28; the node reads only 27 and 28.
+ */
+function parseWalletSignature(raw: unknown): Signature {
+  if (typeof raw !== 'string' || !/^0x[0-9a-fA-F]{130}$/.test(raw)) {
+    throw new Error('the wallet answered with a signature the SDK cannot read (expected 65 bytes of hex)');
+  }
+  const hex = raw.slice(2).toLowerCase();
+  let v = parseInt(hex.slice(128, 130), 16);
+  if (v < 27) {
+    v += 27;
+  }
+  if (v !== 27 && v !== 28) {
+    throw new Error(`the wallet answered with an unexpected recovery id (${v})`);
+  }
+  return { r: '0x' + hex.slice(0, 64), s: '0x' + hex.slice(64, 128), v };
+}
+
+/** The address a signature over `digest` came from, or `null` when it does not recover to one. */
+function recoverAddress(digest: Uint8Array, signature: Signature): string | null {
+  try {
+    const compact = strip0x(signature.r).padStart(64, '0') + strip0x(signature.s).padStart(64, '0');
+    const point = secp.Signature.fromCompact(compact)
+      .addRecoveryBit(signature.v - 27)
+      .recoverPublicKey(digest);
+    return '0x' + Buffer.from(keccak_256(point.toRawBytes(false).slice(1)).slice(-20)).toString('hex');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * A signer that asks a wallet to sign with `personal_sign`. The wallet shows the user the text,
+ * and keeps the key. `address` is the account to sign for; it is lowercased, because the hash of a
+ * transaction commits to `from` and the node reads `from` in lower case.
+ *
+ * The signature is checked here before it is returned: a wallet that signs with another account
+ * (the user switched accounts) would otherwise be found out later, as a refusal from the node
+ * that does not say why.
+ */
+export function createWalletSigner(provider: Eip1193Provider, address: string): Signer {
+  const account = address.toLowerCase();
+
+  async function personalSign(text: string): Promise<Signature> {
+    // Always hex: a text that starts with "0x" would be read by the wallet as bytes, not text.
+    const message = '0x' + Buffer.from(text, 'utf8').toString('hex');
+    const raw = await provider.request({ method: 'personal_sign', params: [message, account] });
+    const signature = parseWalletSignature(raw);
+    const signedBy = recoverAddress(personalSignDigest(text), signature);
+    if (signedBy !== account) {
+      throw new Error(
+        `the wallet signed with ${signedBy ?? 'an account that cannot be read'}, not ${account}: switch to ${account} in the wallet and try again`
+      );
+    }
+    return signature;
+  }
+
+  return {
+    address: account,
+    interactive: true,
+    signTransaction: ({ hashHex, chainId }) => personalSign(walletTransactionText(chainId, hashHex)),
+    signAuthChallenge: ({ message }) => personalSign(message),
+  };
+}
+
+/** A wallet found in the page. */
+export interface InjectedWallet {
+  /** The EIP-6963 `rdns` (for example `io.metamask`), or `injected-0` for a bare `window.ethereum`. */
+  id: string;
+  name: string;
+  /** A `data:` image address from the wallet, when it announced one. */
+  icon?: string;
+  provider: Eip1193Provider;
+}
+
+export interface WalletDiscoveryOptions {
+  /** Where to look. Default: `window`. */
+  host?: EventTarget & { ethereum?: unknown };
+  /** How long to listen for EIP-6963 announcements, in milliseconds. Default: 300. */
+  timeoutMs?: number;
+}
+
+function isProvider(value: unknown): value is Eip1193Provider {
+  return !!value && typeof (value as Eip1193Provider).request === 'function';
+}
+
+/** A name for a provider that did not announce one. Trust Wallet sets `isMetaMask` too, so it is checked first. */
+function legacyName(provider: Eip1193Provider): string {
+  const flags = provider as unknown as Record<string, unknown>;
+  if (flags.isTrust || flags.isTrustWallet) return 'Trust Wallet';
+  if (flags.isMetaMask) return 'MetaMask';
+  if (flags.isCoinbaseWallet) return 'Coinbase Wallet';
+  return 'Browser wallet';
+}
+
+/**
+ * The wallets in this page. A wallet that follows EIP-6963 announces itself, so several can be
+ * listed side by side; one that only sets `window.ethereum` (older wallets, some in-app browsers)
+ * is added when no announced wallet is that same provider. Returns an empty list when there is no
+ * wallet, or when there is no page (Node).
+ */
+export async function discoverInjectedWallets(options: WalletDiscoveryOptions = {}): Promise<InjectedWallet[]> {
+  const host = options.host ?? (typeof window !== 'undefined' ? (window as unknown as WalletDiscoveryOptions['host']) : undefined);
+  if (!host) {
+    return [];
+  }
+  const found = new Map<string, InjectedWallet>();
+
+  const onAnnounce = (event: Event): void => {
+    const detail = (event as Event & { detail?: { info?: Record<string, string>; provider?: unknown } }).detail;
+    if (!detail || !isProvider(detail.provider)) {
+      return;
+    }
+    const info = detail.info ?? {};
+    const id = info.rdns || info.uuid || info.name || `announced-${found.size}`;
+    if (!found.has(id)) {
+      found.set(id, { id, name: info.name || id, icon: info.icon, provider: detail.provider });
+    }
+  };
+
+  host.addEventListener('eip6963:announceProvider', onAnnounce);
+  try {
+    host.dispatchEvent(new Event('eip6963:requestProvider'));
+    await new Promise<void>((resolve) => setTimeout(resolve, options.timeoutMs ?? 300));
+  } finally {
+    host.removeEventListener('eip6963:announceProvider', onAnnounce);
+  }
+
+  const wallets = [...found.values()];
+  const ethereum = host.ethereum as (Eip1193Provider & { providers?: unknown }) | undefined;
+  if (isProvider(ethereum)) {
+    const list: unknown[] =
+      Array.isArray(ethereum.providers) && ethereum.providers.length > 0 ? ethereum.providers : [ethereum];
+    list.filter(isProvider).forEach((provider, index) => {
+      if (!wallets.some((wallet) => wallet.provider === provider)) {
+        wallets.push({ id: `injected-${index}`, name: legacyName(provider), provider });
+      }
+    });
+  }
+  return wallets;
+}
+
+/**
+ * Ask a wallet to share its account (the wallet shows its own prompt) and return a signer for it.
+ * Rejects when the user says no (the provider's error, code 4001) or when no account is shared.
+ */
+export async function connectWallet(wallet: InjectedWallet): Promise<Signer> {
+  const accounts = await wallet.provider.request({ method: 'eth_requestAccounts' });
+  const first = Array.isArray(accounts) ? accounts[0] : undefined;
+  if (typeof first !== 'string' || !/^0x[0-9a-fA-F]{40}$/.test(first)) {
+    throw new Error('the wallet did not share an account');
+  }
+  return createWalletSigner(wallet.provider, first);
+}