clutch-hub-sdk-js 1.22.1 → 2.0.0

package/CHANGELOG.md

@@ -1,3 +1,19 @@
+## [2.0.0](https://github.com/clutchprotocol/clutch-hub-sdk-js/compare/v1.22.1...v2.0.0) (2026-07-02)
+
+
+### ⚠ BREAKING CHANGES
+
+* authenticated methods (createUnsigned*, submitTransaction,
+getAccountBalance) now require a private key via the constructor or
+setPrivateKey(), and generateToken requires timestamp + signature. Requires
+clutch-hub-api with the matching auth challenge.
+
+Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
+
+### Features
+
+* sign auth challenge for generateToken ([02c9f1e](https://github.com/clutchprotocol/clutch-hub-sdk-js/commit/02c9f1efa9db5cdecdb2ebc52744a9714254420b))
+
 ## [1.22.1](https://github.com/clutchprotocol/clutch-hub-sdk-js/compare/v1.22.0...v1.22.1) (2026-05-28)
 
 ## [1.22.0](https://github.com/clutchprotocol/clutch-hub-sdk-js/compare/v1.21.0...v1.22.0) (2026-05-22)

package/CLAUDE.md

@@ -0,0 +1,119 @@
+# clutch-hub-sdk-js
+
+TypeScript client SDK for Clutch Protocol (npm: `clutch-hub-sdk-js`). Signs transactions
+client-side (secp256k1 + keccak-256 + RLP) and talks to the Hub API over GraphQL HTTP and
+graphql-ws subscriptions. See the parent `D:\source\clutch\CLAUDE.md` for the workspace overview.
+
+## Source Layout
+
+Only four source files — the SDK is deliberately small:
+
+- `src/sdk.ts` — everything important: `ClutchHubSdk` class, JWT auth caching, signing/hashing,
+  RLP encoding (`encodeFunctionCall`), all GraphQL queries/mutations/subscriptions inline as
+  template strings, faucet helper. Also exports `stripHexPrefix`, `normalizeTxHashForRlp`,
+  `UnsignedTransaction`.
+- `src/subscriptions.ts` — `hubGraphqlWsUrl()` (HTTP base URL → `ws(s)://…/graphql/ws`),
+  `createHubSubscriptionClient()` (graphql-ws client: `lazy: false`, infinite retry, 10s keepAlive),
+  shared GraphQL field-selection constants (`RIDE_REQUEST_GQL_FIELDS` etc.), `SubscriptionHandlers<T>`.
+- `src/types.ts` — arg/result interfaces (`RideRequestArgs`, `AvailableActiveTrip`, `MapBounds`,
+  `Signature`, `FaucetResponse`, …).
+- `src/index.ts` — barrel re-exports. New public symbols must be reachable from here.
+
+There is no test suite. `test_rlp_fix.{js,mjs}` are ad-hoc manual scripts run against `dist/` after
+`npm run build` — not wired into CI.
+
+## Transaction Lifecycle (client side)
+
+1. **Build unsigned**: `createUnsignedRideRequest/Offer/Acceptance/Pay/Cancel/RequestCancel` call
+   the corresponding Hub API mutation (after `ensureAuth`) and get back
+   `{ data, from, nonce }` (`UnsignedTransaction`).
+2. **Encode call data**: `encodeFunctionCall(data)` maps the function-call type to a nested array
+   `[tag, args]` for RLP. Tags must match the Rust node: RideRequest=1, RideOffer=2,
+   RideAcceptance=3, RidePay=4, RideCancel=5, RideRequestCancel=8 (6/7 reserved elsewhere).
+3. **Hash**: RLP-encode `[from (no 0x), nonce, callDataArray]`, keccak-256 it → `rawHashHex`.
+4. **Sign**: `signHash` does **not** sign the hash bytes directly — the Rust node verifies
+   `Keccak256(hash_string.as_utf8_bytes())`, so the SDK keccaks the *hex string's UTF-8 bytes*,
+   then `secp.signAsync`. Recovery id + 27 → `v`.
+5. **Encode signed**: RLP `[from, nonce, r, s, v, hash, callDataArray]` (all hex without 0x) →
+   `rawTransaction: '0x…'`.
+6. **Submit**: `submitTransaction(rawTransaction)` → `sendRawTransaction` mutation → tx hash.
+
+Signing quirks to preserve: floats (lat/lng) are encoded as IEEE-754 big-endian u64 bits via
+`float64ToUint64` (BigInt); tx-hash args go through `normalizeTxHashForRlp` (strips 0x *and*
+legacy JSON-string quoting); empty referrer encodes as `''`.
+
+## Public API Surface (`ClutchHubSdk`)
+
+- **Constructor / identity**: `new ClutchHubSdk(apiUrl, publicKey, privateKey?)`, `getPublicKey()`,
+  `setPrivateKey(privateKey)`, `isAuthenticated()`. The private key (constructor arg or
+  `setPrivateKey`) is required for token issuance — `generateToken` demands a signed
+  proof-of-key-ownership challenge. It is kept in a module-global map keyed by publicKey
+  (like the JWT cache) and never sent to the API.
+- **Auth (internal)**: `ensureAuth()` builds the challenge `clutch-auth:{publicKey}:{timestamp}`
+  (unix seconds), signs it via `signAuthChallenge` (Keccak-256 the message to a hex string, then
+  the usual `signHashHex` convention — see Transaction Lifecycle step 4), and calls the
+  `generateToken(publicKey, timestamp, signature)` mutation. The Hub API rejects timestamps more
+  than ±120s from server time. JWTs are cached in a **module-global** map keyed by publicKey with
+  30s expiry buffer and in-flight dedup, so multiple SDK instances share tokens; `ensureAuth`
+  throws if no cached token is valid and no private key was provided. Exported helpers:
+  `buildAuthChallengeMessage`, `authChallengeHashHex`, `signAuthChallenge` — these must stay
+  byte-for-byte in sync with `clutch-hub-api`'s `hub/auth.rs`.
+- **Unsigned tx builders**: `createUnsignedRideRequest/RideOffer/RideAcceptance/RidePay/RideCancel/RideRequestCancel`.
+- **Sign & submit**: `signTransaction(unsignedTx, privateKey)` → `{ r, s, v, rawTransaction, txHash }`;
+  `submitTransaction(rawTransaction)`.
+- **Queries**: `listRideRequests(bounds?)`, `listRideOffers(hash)`, `listActiveTrips`,
+  `listCompletedTrips`, `listRecentTrips`, `getAccountBalance(publicKey?)`.
+- **Subscriptions** (each returns a dispose function): `subscribeRideRequests`,
+  `subscribeRideOffers`, `subscribeActiveTrips`, `subscribeCompletedTrips`, `subscribeRecentTrips`,
+  `subscribeAccountBalance`. All multiplex over **one shared graphql-ws socket per
+  (hub URL, publicKey)**, refcounted in a module-global map; the last dispose closes the socket.
+  Always call the returned dispose function or sockets/refcounts leak.
+- **Misc**: `requestFaucet(address)` — plain `POST /faucet` (no JWT), returns
+  `{ ok: false, error }` instead of throwing; `getGraphqlWsUrl()`.
+
+## Adding a New Transaction Type
+
+1. Add the arg interface to `src/types.ts`; export lands via `src/index.ts` automatically.
+2. Add `createUnsignedXxx` in `src/sdk.ts` mirroring existing ones (inline mutation string,
+   `ensureAuth`, `executeGraphQL`).
+3. Add a `case` in `encodeFunctionCall` with the **same tag number and argument order as the Rust
+   node's FunctionCall enum** (`clutch-node`) — a mismatch produces valid-looking txs the node
+   rejects. Support both snake_case (`ride_offer_transaction_hash`) and camelCase arg keys, as the
+   Hub API has returned both shapes.
+4. Upstream first: node RPC → `clutch-hub-api` GraphQL mutation must exist before the SDK method
+   works. Then update `clutch-hub-demo-app` and `clutch-docs`.
+
+For a new query/subscription: add types + field constant (in `subscriptions.ts` if shared between
+query and subscription), then a `listXxx` using `executeGraphQL` and/or a `subscribeXxx` using
+`subscribeGraphqlListField` (list payloads) or the manual pattern in `subscribeAccountBalance`
+(scalar payloads).
+
+## Build & Release
+
+- `npm run build` = `tsc` → `dist/` (declarations included). `prepare` also builds, which is what
+  makes the `file:` install work. No lint or test scripts exist despite CONTRIBUTING.md mentioning them.
+- tsconfig: ES2020 target, `module: ESNext`, `strict: true`, DOM lib included (browser-first).
+- **semantic-release** on push to `main` (`.github/workflows/npm-publish.yml` + `.releaserc.json`):
+  Conventional Commits required. `feat:` → minor, `fix:`/`perf:`/`refactor:` → patch,
+  `feat!:` or a `BREAKING CHANGE:` footer → major; `docs:`/`chore:`/`ci:`/`test:`/`build:`/`style:`
+  release nothing. Non-releasing pushes to `main` publish a `-canary.<sha>` build under the
+  `canary` dist-tag. A `beta` branch does prereleases. CHANGELOG.md and package.json version are
+  bot-committed (`chore(release): x.y.z [skip ci]`) — never bump the version by hand.
+- The demo app consumes this repo via `"clutch-hub-sdk-js": "file:../clutch-hub-sdk-js"`; its
+  `predev`/`prebuild` run `npm run build --prefix ../clutch-hub-sdk-js`. So SDK source changes
+  reach the demo app on its next `npm run dev` — but if Vite is already running you may need to
+  restart / clear `node_modules/.vite` to pick up the rebuilt dist.
+
+## Gotchas
+
+- **Browser + Node dual use**: `sdk.ts` imports `buffer` (npm polyfill) and assigns
+  `window.Buffer` if missing. Don't use Node-only APIs; keep DOM usage guarded by
+  `typeof window !== 'undefined'`.
+- `@noble/secp256k1` v2 hex parsers reject `0x` prefixes — always run keys/hashes through
+  `stripHexPrefix` before passing them to noble.
+- Auth state (JWT cache, in-flight dedup, shared WS clients) is module-global, not per-instance —
+  tests or multi-wallet apps share it by design.
+- WS subscriptions silently continue without a JWT if `generateToken` fails — including when no
+  private key was supplied for the wallet (public list subscriptions are allowed unauthenticated).
+- GraphQL operations are inline strings with hand-written TS result types — there is no codegen;
+  keep field constants and `types.ts` in sync with the Hub API schema manually.

package/README.md

@@ -5,115 +5,67 @@
 ![License](https://img.shields.io/badge/license-MIT-blue.svg)
 ![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?style=flat&logo=typescript&logoColor=white)
 [![npm](https://img.shields.io/npm/v/clutch-hub-sdk-js.svg)](https://www.npmjs.com/package/clutch-hub-sdk-js)
-[![npm downloads](https://img.shields.io/npm/dm/clutch-hub-sdk-js.svg)](https://www.npmjs.com/package/clutch-hub-sdk-js)
 
-> ⚠️ **ALPHA SOFTWARE** - This project is in active development and is considered experimental. Use at your own risk. APIs may change without notice.
+> ⚠️ **ALPHA SOFTWARE** — APIs may change without notice.
 
-JavaScript SDK for interacting with the clutch-hub-api
+JavaScript/TypeScript SDK for the Clutch Hub API and Clutch blockchain.
 
-**Created and maintained by [Mehran Mazhar](https://github.com/MehranMazhar)**
-
-## Overview
+**Documentation:** https://docs.clutchprotocol.io/clutch-hub-sdk-js/overview
 
-`clutch-hub-sdk-js` is a JavaScript/TypeScript SDK for building decentralized applications (dApps) that interact with the [clutch-hub-api](https://github.com/your-org/clutch-hub-api) and the Clutch custom blockchain. This SDK helps you:
-- Connect to the hub API
-- Build and sign transactions client-side (keeping private keys secure)
-- Submit signed transactions to the blockchain via the API
-- Query chain state (e.g., get nonce, balances, etc.)
+## Install
 
-## Features
-- **Client-side signing:** Never expose your private key to the server; all signing is done in the browser or mobile app.
-- **Transaction helpers:** Easily build, encode, and sign custom Clutch transactions (e.g., ride requests).
-- **API integration:** Fetch chain state and submit signed transactions to the hub API.
-- **GraphQL subscriptions:** `subscribeRideRequests`, `subscribeRideOffers`, `subscribeActiveTrips`, and `subscribeCompletedTrips` use [`graphql-ws`](https://github.com/enisdenjo/graphql-ws) against `wss://…/graphql/ws` (see `hubGraphqlWsUrl()`). Each call opens a WebSocket, sends optional JWT from `connection_init`, and returns a **dispose** function for cleanup.
-- **TypeScript support:** Type-safe interfaces for all major methods and transaction types.
-
-## Installation
 ```bash
 npm install clutch-hub-sdk-js
 ```
 
-### Latest Version
-You can also install the latest canary version for cutting-edge features:
-```bash
-npm install clutch-hub-sdk-js@canary
-```
+## Usage
 
-## Basic Usage
-```js
+```javascript
 import { ClutchHubSdk } from 'clutch-hub-sdk-js';
 
-const sdk = new ClutchHubSdk('https://your-hub-api-url');
+// privateKey is needed for authenticated calls: generateToken requires a signed
+// proof-of-key-ownership challenge (the key stays local, it is never sent).
+const sdk = new ClutchHubSdk('http://localhost:3000', publicKey, privateKey);
 
-// 1. Fetch the next nonce for the user
-const nonce = await sdk.getNextNonce(userAddress);
+// Fund test wallet
+await sdk.requestFaucet(publicKey);
 
-// 2. Build a ride request transaction
-const tx = sdk.buildRideRequestTx({
+// Create, sign, and submit a ride request
+const unsigned = await sdk.createUnsignedRideRequest({
   pickup: { latitude: 35.7, longitude: 51.4 },
   dropoff: { latitude: 35.8, longitude: 51.5 },
-  fare: 1000
-}, userAddress, nonce);
-
-// 3. Sign the transaction (using user's private key)
-const { r, s, v } = await sdk.signTx(tx, userPrivateKey);
-
-// 4. Submit the signed transaction
-const receipt = await sdk.sendTransaction({
-  from: userAddress,
-  nonce,
-  payload: tx,
-  r, s, v
+  fare: 1000,
 });
-
-console.log('Transaction receipt:', receipt);
+const signed = await sdk.signTransaction(unsigned, privateKey);
+await sdk.submitTransaction(signed.rawTransaction);
 ```
 
-## Security Note
-**Never share or expose your private key.** The SDK is designed for client-side signing only. For best security, integrate with browser wallets, hardware wallets, or secure mobile keystores.
-
-## Development & Releases
-
-This project uses [semantic-release](https://semantic-release.gitbook.io/) for automated versioning and publishing.
-
-### Commit Message Format
+## Features
 
-Use [Conventional Commits](https://conventionalcommits.org/) for automatic version bumping:
+- Client-side signing (private keys never sent to server)
+- Full ride lifecycle: request, offer, accept, pay, cancel
+- GraphQL queries and WebSocket subscriptions
+- Testnet faucet helper
+- TypeScript types
 
-```bash
-# Patch release (0.1.0 → 0.1.1)
-git commit -m "fix: resolve memory leak in transaction processing"
+## API methods
 
-# Minor release (0.1.0 → 0.2.0)  
-git commit -m "feat: add ride cancellation functionality"
+| Category | Methods |
+|----------|---------|
+| Auth | Auto `generateToken` via `ensureAuth()` (signed challenge; needs the private key), `setPrivateKey`, `signAuthChallenge` |
+| Write | `createUnsignedRide*`, `signTransaction`, `submitTransaction` |
+| Read | `listRideRequests`, `listRideOffers`, `listActiveTrips`, `getAccountBalance`, … |
+| Live | `subscribeRideRequests`, `subscribeRideOffers`, `subscribeActiveTrips`, … |
+| Faucet | `requestFaucet(recipientAddress)` |
 
-# Major release (0.1.0 → 1.0.0)
-git commit -m "feat!: change API signature for ClutchHubSdk constructor"
+Full reference: https://docs.clutchprotocol.io/clutch-hub-sdk-js/api-reference
 
-# No release
-git commit -m "docs: update README with new examples"
-git commit -m "chore: update dependencies"
-```
+## Security
 
-### Release Process
+**Never expose private keys.** Client-side signing only. See [Security](https://docs.clutchprotocol.io/reference/security).
 
-1. **Automatic Releases**: Merge commits to `main` with conventional commit messages
-2. **Canary Releases**: Non-conventional commits create canary versions (`0.1.0-canary.abc1234`)
-3. **Manual Releases**: Push git tags (`v1.0.0`) for manual version control
+## Releases
 
-### Commit Message Template
+Uses [semantic-release](https://semantic-release.gitbook.io/) with conventional commits.
 
-Set up the commit message template:
-```bash
-git config commit.template .gitmessage
-```
-
-## Author & Maintainer
-
-**Mehran Mazhar**
-- GitHub: [@MehranMazhar](https://github.com/MehranMazhar)
-- Website: [MehranMazhar.com](https://MehranMazhar.com)
-- Email: mehran.mazhar@gmail.com
-
-## License
-MIT
+**Created and maintained by [Mehran Mazhar](https://github.com/MehranMazhar)**

package/dist/sdk.d.ts

@@ -13,6 +13,25 @@ declare global {
         Buffer: typeof Buffer;
     }
 }
+/** Prefix of the canonical proof-of-key-ownership message signed for `generateToken`. */
+export declare const AUTH_CHALLENGE_PREFIX = "clutch-auth";
+/**
+ * Canonical auth challenge message for `generateToken`. Must match clutch-hub-api
+ * (`hub::auth::build_auth_challenge_message`) byte-for-byte: the exact `publicKey` string
+ * sent as the mutation argument and the timestamp in decimal unix seconds.
+ */
+export declare function buildAuthChallengeMessage(publicKey: string, timestamp: number): string;
+/**
+ * Keccak-256 of the canonical auth message as 64-char lowercase hex (no 0x).
+ * The signature is then computed over the UTF-8 bytes of this hex string (see `signHashHex`),
+ * the same convention used for transaction hashes.
+ */
+export declare function authChallengeHashHex(publicKey: string, timestamp: number): string;
+/**
+ * Sign the `generateToken` proof-of-key-ownership challenge.
+ * @param timestamp Unix seconds; the Hub API rejects timestamps more than ±120s from server time.
+ */
+export declare function signAuthChallenge(publicKey: string, timestamp: number, privateKey: string): Promise<Signature>;
 /**
  * Represents an unsigned transaction returned by the GraphQL API.
  */
@@ -30,12 +49,26 @@ export declare class ClutchHubSdk {
     private publicKey;
     private token;
     private tokenExpireTime;
-    constructor(apiUrl: string, publicKey: string);
+    /**
+     * @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.
+     */
+    constructor(apiUrl: string, publicKey: string, privateKey?: string);
     /**
      * 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.
+     */
+    setPrivateKey(privateKey: string): void;
     /**
      * Check if the SDK is currently authenticated.
      * @returns True if authenticated and token is not expired
@@ -173,14 +206,6 @@ export declare class ClutchHubSdk {
      * `faucet_private_key` on the server. No GraphQL auth token required for this HTTP endpoint.
      */
     requestFaucet(recipientAddress: string): Promise<FaucetResponse>;
-    /**
-     * Signs the message that the Rust node verifies.
-     *
-     * Rust does:
-     * - message_hash = Keccak256(tx.hash.as_bytes())
-     * - then uses ECDSA recoverable signature with that message_hash
-     */
-    private signHash;
     /**
      * Builds the nested array representing the function call for RLP encoding.
      */

package/dist/sdk.js

@@ -42,6 +42,57 @@ const globalTokenCache = new Map();
  * Deduplicate concurrent `generateToken` calls per `publicKey`.
  */
 const inFlightTokenRequests = new Map();
+/**
+ * Module-global private-key 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.
+ */
+const globalPrivateKeys = new Map();
+/** Prefix of the canonical proof-of-key-ownership message signed for `generateToken`. */
+export const AUTH_CHALLENGE_PREFIX = 'clutch-auth';
+/**
+ * Canonical auth challenge message for `generateToken`. Must match clutch-hub-api
+ * (`hub::auth::build_auth_challenge_message`) byte-for-byte: the exact `publicKey` string
+ * sent as the mutation argument and the timestamp in decimal unix seconds.
+ */
+export function buildAuthChallengeMessage(publicKey, timestamp) {
+    return `${AUTH_CHALLENGE_PREFIX}:${publicKey}:${timestamp}`;
+}
+/**
+ * Keccak-256 of the canonical auth message as 64-char lowercase hex (no 0x).
+ * The signature is then computed over the UTF-8 bytes of this hex string (see `signHashHex`),
+ * the same convention used for transaction hashes.
+ */
+export function authChallengeHashHex(publicKey, timestamp) {
+    const message = buildAuthChallengeMessage(publicKey, timestamp);
+    return Buffer.from(keccak_256(Buffer.from(message, 'utf8'))).toString('hex');
+}
+/**
+ * Signs a hash-hex string the way the Rust node/hub verify:
+ * - message_hash = Keccak256(hashHex.as_utf8_bytes()) — i.e. over the hex *string*, not its bytes
+ * - recoverable secp256k1 over that message_hash; v = recovery id + 27
+ */
+async function signHashHex(hashHex, privateKey) {
+    const privKeyClean = stripHexPrefix(privateKey);
+    const messageHash = keccak_256(Buffer.from(hashHex, 'utf8'));
+    const sig = await secp.signAsync(messageHash, privKeyClean);
+    const r = sig.r.toString(16).padStart(64, '0');
+    const s = sig.s.toString(16).padStart(64, '0');
+    const v = (typeof sig.recovery === 'number' ? sig.recovery : 0) + 27;
+    return {
+        r: '0x' + r,
+        s: '0x' + s,
+        v,
+    };
+}
+/**
+ * Sign the `generateToken` proof-of-key-ownership challenge.
+ * @param timestamp Unix seconds; the Hub API rejects timestamps more than ±120s from server time.
+ */
+export async function signAuthChallenge(publicKey, timestamp, privateKey) {
+    return signHashHex(authChallengeHashHex(publicKey, timestamp), privateKey);
+}
 /**
  * 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
@@ -52,31 +103,48 @@ function sharedGraphqlWsCacheKey(baseURL, publicKey) {
     return `${baseURL.replace(/\/$/, '')}\0${publicKey}`;
 }
 /**
- * Same token resolution as `ensureAuth`, but only updates the global cache (no `this`).
- * Used by shared WebSocket `connectionParams` so any subscriber shares one connection.
+ * Resolve a valid JWT for `publicKey` into the global cache (and return it), generating one
+ * 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.
  */
 async function ensureTokenInCacheForPublicKey(publicKey, apiClient) {
     const now = Date.now();
     const bufferTime = 30000;
     const cached = globalTokenCache.get(publicKey);
     if (cached && now < cached.expireTimeMs - bufferTime) {
-        return;
+        return cached;
     }
     const existingInFlight = inFlightTokenRequests.get(publicKey);
     if (existingInFlight) {
-        await existingInFlight;
-        return;
+        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 query = `
-    mutation GenerateToken($publicKey: String!) {
-      generateToken(publicKey: $publicKey) {
+    mutation GenerateToken($publicKey: String!, $timestamp: Int!, $signature: AuthSignatureInput!) {
+      generateToken(publicKey: $publicKey, timestamp: $timestamp, signature: $signature) {
         token
         expiresAt
       }
     }
   `;
     const requestPromise = (async () => {
-        const response = await apiClient.post('/graphql', { query, variables: { publicKey } });
+        const timestamp = Math.floor(Date.now() / 1000);
+        const signature = await signAuthChallenge(publicKey, timestamp, privateKey);
+        const response = await apiClient.post('/graphql', {
+            query,
+            variables: {
+                publicKey,
+                timestamp,
+                signature: { r: signature.r, s: signature.s, v: signature.v },
+            },
+        });
         const body = response.data;
         if (body.errors?.length) {
             throw new Error(body.errors.map((e) => e.message).join('\n'));
@@ -93,7 +161,7 @@ async function ensureTokenInCacheForPublicKey(publicKey, apiClient) {
     })();
     inFlightTokenRequests.set(publicKey, requestPromise);
     try {
-        await requestPromise;
+        return await requestPromise;
     }
     finally {
         inFlightTokenRequests.delete(publicKey);
@@ -104,11 +172,21 @@ async function ensureTokenInCacheForPublicKey(publicKey, apiClient) {
  * Provides client-side transaction signing and blockchain interaction capabilities.
  */
 export class ClutchHubSdk {
-    constructor(apiUrl, publicKey) {
+    /**
+     * @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.
+     */
+    constructor(apiUrl, publicKey, privateKey) {
         this.token = null;
         this.tokenExpireTime = 0;
         this.apiClient = axios.create({ baseURL: apiUrl });
         this.publicKey = publicKey;
+        if (privateKey) {
+            globalPrivateKeys.set(publicKey, privateKey);
+        }
     }
     /**
      * Get the current public key associated with this SDK instance.
@@ -117,6 +195,15 @@ export class ClutchHubSdk {
     getPublicKey() {
         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.
+     */
+    setPrivateKey(privateKey) {
+        globalPrivateKeys.set(this.publicKey, privateKey);
+    }
     /**
      * Check if the SDK is currently authenticated.
      * @returns True if authenticated and token is not expired
@@ -215,49 +302,9 @@ export class ClutchHubSdk {
         return response.data.data;
     }
     async ensureAuth() {
-        const now = Date.now();
-        // Add buffer time to prevent race conditions near token expiration
-        const bufferTime = 30000; // 30 seconds
-        const cached = globalTokenCache.get(this.publicKey);
-        if (cached && now < cached.expireTimeMs - bufferTime) {
-            this.token = cached.token;
-            this.tokenExpireTime = cached.expireTimeMs;
-            return;
-        }
-        // If another SDK instance is already generating a token, await it.
-        const existingInFlight = inFlightTokenRequests.get(this.publicKey);
-        if (existingInFlight) {
-            const entry = await existingInFlight;
-            this.token = entry.token;
-            this.tokenExpireTime = entry.expireTimeMs;
-            return;
-        }
-        const query = `
-      mutation GenerateToken($publicKey: String!) {
-        generateToken(publicKey: $publicKey) {
-          token
-          expiresAt
-        }
-      }
-    `;
-        const requestPromise = (async () => {
-            const data = await this.executeGraphQL(query, { publicKey: this.publicKey });
-            const entry = {
-                token: data.generateToken.token,
-                expireTimeMs: data.generateToken.expiresAt * 1000,
-            };
-            globalTokenCache.set(this.publicKey, entry);
-            return entry;
-        })();
-        inFlightTokenRequests.set(this.publicKey, requestPromise);
-        try {
-            const entry = await requestPromise;
-            this.token = entry.token;
-            this.tokenExpireTime = entry.expireTimeMs;
-        }
-        finally {
-            inFlightTokenRequests.delete(this.publicKey);
-        }
+        const entry = await ensureTokenInCacheForPublicKey(this.publicKey, this.apiClient);
+        this.token = entry.token;
+        this.tokenExpireTime = entry.expireTimeMs;
     }
     /**
      * Fetches an unsigned ride request transaction from the GraphQL API.
@@ -406,7 +453,7 @@ export class ClutchHubSdk {
         const hashBytes = keccak_256(unsignedPayload);
         const rawHashHex = Buffer.from(hashBytes).toString('hex');
         // Sign the transaction hash
-        const signature = await this.signHash(rawHashHex, privateKey);
+        const signature = await signHashHex(rawHashHex, privateKey);
         const rNo0x = stripHexPrefix(signature.r);
         const sNo0x = stripHexPrefix(signature.s);
         // RLP-encode full signed transaction to match Rust: [from, nonce, r, s, v, hash, data]
@@ -682,28 +729,6 @@ export class ClutchHubSdk {
             return { ok: false, error: String(msg) };
         }
     }
-    /**
-     * Signs the message that the Rust node verifies.
-     *
-     * Rust does:
-     * - message_hash = Keccak256(tx.hash.as_bytes())
-     * - then uses ECDSA recoverable signature with that message_hash
-     */
-    async signHash(hashHex, privateKey) {
-        const privKeyClean = stripHexPrefix(privateKey);
-        // `hashHex` is the exact string stored in the Rust transaction `hash` field.
-        // The node verifies by hashing its UTF-8 bytes with Keccak-256.
-        const messageHash = keccak_256(Buffer.from(hashHex, 'utf8'));
-        const sig = await secp.signAsync(messageHash, privKeyClean);
-        const r = sig.r.toString(16).padStart(64, '0');
-        const s = sig.s.toString(16).padStart(64, '0');
-        const v = (typeof sig.recovery === 'number' ? sig.recovery : 0) + 27;
-        return {
-            r: '0x' + r,
-            s: '0x' + s,
-            v,
-        };
-    }
     /**
      * Builds the nested array representing the function call for RLP encoding.
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clutch-hub-sdk-js",
-  "version": "1.22.1",
+  "version": "2.0.0",
   "description": "JavaScript SDK for interacting with the clutch-hub-api",
   "main": "dist/index.js",
   "module": "dist/index.js",

package/src/sdk.ts

@@ -81,6 +81,67 @@ 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).
+ * `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.
+ */
+const globalPrivateKeys = new Map<string, string>();
+
+/** Prefix of the canonical proof-of-key-ownership message signed for `generateToken`. */
+export const AUTH_CHALLENGE_PREFIX = 'clutch-auth';
+
+/**
+ * Canonical auth challenge message for `generateToken`. Must match clutch-hub-api
+ * (`hub::auth::build_auth_challenge_message`) byte-for-byte: the exact `publicKey` string
+ * sent as the mutation argument and the timestamp in decimal unix seconds.
+ */
+export function buildAuthChallengeMessage(publicKey: string, timestamp: number): string {
+  return `${AUTH_CHALLENGE_PREFIX}:${publicKey}:${timestamp}`;
+}
+
+/**
+ * Keccak-256 of the canonical auth message as 64-char lowercase hex (no 0x).
+ * The signature is then computed over the UTF-8 bytes of this hex string (see `signHashHex`),
+ * the same convention used for transaction hashes.
+ */
+export function authChallengeHashHex(publicKey: string, timestamp: number): string {
+  const message = buildAuthChallengeMessage(publicKey, timestamp);
+  return Buffer.from(keccak_256(Buffer.from(message, 'utf8'))).toString('hex');
+}
+
+/**
+ * Signs a hash-hex string the way the Rust node/hub verify:
+ * - message_hash = Keccak256(hashHex.as_utf8_bytes()) — i.e. over the hex *string*, not its bytes
+ * - recoverable secp256k1 over that message_hash; v = recovery id + 27
+ */
+async function signHashHex(hashHex: string, privateKey: string): Promise<Signature> {
+  const privKeyClean = stripHexPrefix(privateKey);
+  const messageHash = keccak_256(Buffer.from(hashHex, 'utf8'));
+  const sig = await secp.signAsync(messageHash, privKeyClean);
+  const r = sig.r.toString(16).padStart(64, '0');
+  const s = sig.s.toString(16).padStart(64, '0');
+  const v = (typeof sig.recovery === 'number' ? sig.recovery : 0) + 27;
+  return {
+    r: '0x' + r,
+    s: '0x' + s,
+    v,
+  };
+}
+
+/**
+ * Sign the `generateToken` proof-of-key-ownership challenge.
+ * @param timestamp Unix seconds; the Hub API rejects timestamps more than ±120s from server time.
+ */
+export async function signAuthChallenge(
+  publicKey: string,
+  timestamp: number,
+  privateKey: string
+): Promise<Signature> {
+  return signHashHex(authChallengeHashHex(publicKey, timestamp), privateKey);
+}
+
 type SharedGraphqlWsEntry = { client: Client; refcount: number };
 
 /**
@@ -95,30 +156,41 @@ function sharedGraphqlWsCacheKey(baseURL: string, publicKey: string): string {
 }
 
 /**
- * Same token resolution as `ensureAuth`, but only updates the global cache (no `this`).
- * Used by shared WebSocket `connectionParams` so any subscriber shares one connection.
+ * Resolve a valid JWT for `publicKey` into the global cache (and return it), generating one
+ * 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.
  */
 async function ensureTokenInCacheForPublicKey(
   publicKey: string,
   apiClient: AxiosInstance
-): Promise<void> {
+): Promise<TokenCacheEntry> {
   const now = Date.now();
   const bufferTime = 30000;
 
   const cached = globalTokenCache.get(publicKey);
   if (cached && now < cached.expireTimeMs - bufferTime) {
-    return;
+    return cached;
   }
 
   const existingInFlight = inFlightTokenRequests.get(publicKey);
   if (existingInFlight) {
-    await existingInFlight;
-    return;
+    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 query = `
-    mutation GenerateToken($publicKey: String!) {
-      generateToken(publicKey: $publicKey) {
+    mutation GenerateToken($publicKey: String!, $timestamp: Int!, $signature: AuthSignatureInput!) {
+      generateToken(publicKey: $publicKey, timestamp: $timestamp, signature: $signature) {
         token
         expiresAt
       }
@@ -126,9 +198,18 @@ async function ensureTokenInCacheForPublicKey(
   `;
 
   const requestPromise: Promise<TokenCacheEntry> = (async () => {
+    const timestamp = Math.floor(Date.now() / 1000);
+    const signature = await signAuthChallenge(publicKey, timestamp, privateKey);
     const response = await apiClient.post<{ data?: unknown; errors?: { message: string }[] }>(
       '/graphql',
-      { query, variables: { publicKey } }
+      {
+        query,
+        variables: {
+          publicKey,
+          timestamp,
+          signature: { r: signature.r, s: signature.s, v: signature.v },
+        },
+      }
     );
     const body = response.data as { errors?: { message: string }[]; data?: { generateToken: { token: string; expiresAt: number } } };
     if (body.errors?.length) {
@@ -147,7 +228,7 @@ async function ensureTokenInCacheForPublicKey(
 
   inFlightTokenRequests.set(publicKey, requestPromise);
   try {
-    await requestPromise;
+    return await requestPromise;
   } finally {
     inFlightTokenRequests.delete(publicKey);
   }
@@ -172,9 +253,19 @@ export class ClutchHubSdk {
   private token: string | null = null;
   private tokenExpireTime: number = 0;
 
-  constructor(apiUrl: string, publicKey: string) {
+  /**
+   * @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.
+   */
+  constructor(apiUrl: string, publicKey: string, privateKey?: string) {
     this.apiClient = axios.create({ baseURL: apiUrl });
     this.publicKey = publicKey;
+    if (privateKey) {
+      globalPrivateKeys.set(publicKey, privateKey);
+    }
   }
 
   /**
@@ -185,6 +276,16 @@ 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.
+   */
+  public setPrivateKey(privateKey: string): void {
+    globalPrivateKeys.set(this.publicKey, privateKey);
+  }
+
   /**
    * Check if the SDK is currently authenticated.
    * @returns True if authenticated and token is not expired
@@ -300,57 +401,9 @@ export class ClutchHubSdk {
   }
 
   private async ensureAuth(): Promise<void> {
-    const now = Date.now();
-    // Add buffer time to prevent race conditions near token expiration
-    const bufferTime = 30000; // 30 seconds
-
-    const cached = globalTokenCache.get(this.publicKey);
-    if (cached && now < cached.expireTimeMs - bufferTime) {
-      this.token = cached.token;
-      this.tokenExpireTime = cached.expireTimeMs;
-      return;
-    }
-
-    // If another SDK instance is already generating a token, await it.
-    const existingInFlight = inFlightTokenRequests.get(this.publicKey);
-    if (existingInFlight) {
-      const entry = await existingInFlight;
-      this.token = entry.token;
-      this.tokenExpireTime = entry.expireTimeMs;
-      return;
-    }
-
-    const query = `
-      mutation GenerateToken($publicKey: String!) {
-        generateToken(publicKey: $publicKey) {
-          token
-          expiresAt
-        }
-      }
-    `;
-
-    const requestPromise: Promise<TokenCacheEntry> = (async () => {
-      const data = await this.executeGraphQL<{
-        generateToken: { token: string; expiresAt: number }
-      }>(query, { publicKey: this.publicKey });
-
-      const entry: TokenCacheEntry = {
-        token: data.generateToken.token,
-        expireTimeMs: data.generateToken.expiresAt * 1000,
-      };
-
-      globalTokenCache.set(this.publicKey, entry);
-      return entry;
-    })();
-
-    inFlightTokenRequests.set(this.publicKey, requestPromise);
-    try {
-      const entry = await requestPromise;
-      this.token = entry.token;
-      this.tokenExpireTime = entry.expireTimeMs;
-    } finally {
-      inFlightTokenRequests.delete(this.publicKey);
-    }
+    const entry = await ensureTokenInCacheForPublicKey(this.publicKey, this.apiClient);
+    this.token = entry.token;
+    this.tokenExpireTime = entry.expireTimeMs;
   }
 
   /**
@@ -530,7 +583,7 @@ export class ClutchHubSdk {
     const rawHashHex = Buffer.from(hashBytes).toString('hex');
 
     // Sign the transaction hash
-    const signature = await this.signHash(rawHashHex, privateKey);
+    const signature = await signHashHex(rawHashHex, privateKey);
     const rNo0x = stripHexPrefix(signature.r);
     const sNo0x = stripHexPrefix(signature.s);
 
@@ -900,32 +953,6 @@ export class ClutchHubSdk {
     }
   }
 
-  /**
-   * Signs the message that the Rust node verifies.
-   *
-   * Rust does:
-   * - message_hash = Keccak256(tx.hash.as_bytes())
-   * - then uses ECDSA recoverable signature with that message_hash
-   */
-  private async signHash(
-    hashHex: string,
-    privateKey: string
-  ): Promise<Signature> {
-    const privKeyClean = stripHexPrefix(privateKey);
-    // `hashHex` is the exact string stored in the Rust transaction `hash` field.
-    // The node verifies by hashing its UTF-8 bytes with Keccak-256.
-    const messageHash = keccak_256(Buffer.from(hashHex, 'utf8'));
-    const sig = await secp.signAsync(messageHash, privKeyClean);
-    const r = sig.r.toString(16).padStart(64, '0');
-    const s = sig.s.toString(16).padStart(64, '0');
-    const v = (typeof sig.recovery === 'number' ? sig.recovery : 0) + 27;
-    return {
-      r: '0x' + r,
-      s: '0x' + s,
-      v,
-    };
-  }
-
   /**
    * Builds the nested array representing the function call for RLP encoding.
    */