@revibase/transaction-manager 0.5.1 → 0.5.3

package/README.md

@@ -34,37 +34,34 @@ Use this package when you want a single, auditable place in your backend where e
 Generate one keypair for the manager and keep the private key server-side only.
 
 ```ts
-import { getBase58Decoder } from "gill";
-
-const keyPair = await crypto.subtle.generateKey({ name: "Ed25519" }, true, [
-  "sign",
-  "verify",
-]);
+import {
+  getBase58Decoder,
+  generateExtractableKeyPairSigner,
+  extractBytesFromKeyPairSigner,
+} from "gill";
 
-const [pubRaw, privJwk] = await Promise.all([
-  crypto.subtle.exportKey("raw", keyPair.publicKey),
-  crypto.subtle.exportKey("jwk", keyPair.privateKey),
-]);
+const keypair = await generateExtractableKeyPairSigner();
+const secretKey = await extractBytesFromKeyPairSigner(keypair);
 
 console.log({
-  publicKey: getBase58Decoder().decode(new Uint8Array(pubRaw)),
-  privateKey: JSON.stringify(privJwk),
+  publicKey: getBase58Decoder().decode(secretKey.slice(32)),
+  secretKey: getBase58Decoder().decode(secretKey),
 });
 ```
 
 Store:
 
 - **`publicKey`**: as the transaction manager public key (base58).
-- **`privateKey`**: as a JWK JSON string in a secure secret store.
+- **`secretKey`**: as a base58 string in a secure secret store.
 
 ### 2. Configure environment
 
 Set the following environment variables for your signing service:
 
-- **`TX_MANAGER_PRIVATE_KEY`**: Manager private key (JWK JSON string).
+- **`TX_MANAGER_SECRET_KEY`**: Manager secret key (base58 string).
 - **`TX_MANAGER_PUBLIC_KEY`**: Manager public key (base58).
-- **`TX_MANAGER_URL`**: Public HTTPS URL of your signing endpoint.
-- **`RPC_URL`** (optional): Solana RPC URL. Defaults to `https://api.mainnet-beta.solana.com`.
+- **`TX_MANAGER_URL`**: Public HTTPS URL of your signing endpoint (the client will connect via WebSocket at the same URL).
+- **`RPC_URL`** Solana RPC URL.
 
 ### 3. Implement a basic signing endpoint
 
@@ -72,6 +69,12 @@ Expose a public HTTPS endpoint, for example:
 
 `https://your-transaction-manager.com/sign`
 
+This section uses the [`ws`](https://www.npmjs.com/package/ws) package for the WebSocket server:
+
+```bash
+npm install ws
+```
+
 This endpoint:
 
 - Verifies that the request is intended for this transaction manager.
@@ -81,73 +84,225 @@ This endpoint:
 - Returns base58-encoded signatures.
 
 ```ts
-import { verifyTransaction } from "@revibase/transaction-manager";
-import { createSolanaRpc, getBase58Decoder } from "gill";
+import {
+  initialize,
+  type CompleteMessageRequest,
+  type TransactionAuthDetails,
+  verifyMessage,
+  verifyTransaction,
+} from "@revibase/transaction-manager";
+import {
+  getBase58Decoder,
+  createKeypairSignerFromBase58,
+  signBytes,
+} from "gill";
 import { enforcePolicies } from "@/lib/policy";
+import http from "node:http";
+import { WebSocketServer } from "ws";
 
-const rpc = createSolanaRpc(
-  process.env.RPC_URL ?? "https://api.mainnet-beta.solana.com",
-);
+initialize({
+  rpcEndpoint: process.env.RPC_URL,
+});
 
 const transactionManagerConfig = {
   publicKey: process.env.TX_MANAGER_PUBLIC_KEY!, // base58
   url: process.env.TX_MANAGER_URL!, // public HTTPS URL of this endpoint
 };
 
-export async function POST(req: Request) {
+/**
+ * The @revibase/core client connects using WebSocket (wss://...) and sends one JSON message.
+ * This is the exact shape produced by createTransactionManagerSigner():
+ *
+ * Transaction signing:
+ * {
+ *   type: "transaction",
+ *   data: {
+ *     publicKey: string,
+ *     payload: Array<{
+ *       transaction: string,
+ *       transactionMessageBytes?: string,
+ *       authResponses?: TransactionAuthDetails[],
+ *     }>,
+ *   }
+ * }
+ *
+ * Message signing:
+ * {
+ *   type: "message",
+ *   data: {
+ *      publicKey: string,
+ *      payload: CompleteMessageRequest
+ *    }
+ * }
+ *
+ * Your service should respond with JSON events:
+ * - { event: "signatures", data: { signatures: string[] } }  // base58 signatures
+ * - { event: "error", data: { error: string } }
+ *
+ * (Optional) approval UX:
+ * - { event: "pending_transaction_approval", data: { validTill: number } }
+ * - { event: "transaction_approved", data: {} }
+ */
+const server = http.createServer();
+
+// Route upgrade requests for "/sign" to WebSocket.
+const wss = new WebSocketServer({ noServer: true });
+server.on("upgrade", (req, socket, head) => {
   try {
-    const { publicKey, payload } = (await req.json()) as {
-      publicKey: string;
-      payload: {
-        transaction: string;
-        transactionMessageBytes?: string;
-        authResponses?: unknown[];
-      }[];
-    };
+    const url = new URL(req.url ?? "/", "http://localhost");
+    if (url.pathname !== "/sign") {
+      socket.destroy();
+      return;
+    }
+    wss.handleUpgrade(req, socket, head, (ws) => {
+      wss.emit("connection", ws, req);
+    });
+  } catch {
+    socket.destroy();
+  }
+});
 
-    if (publicKey !== transactionManagerConfig.publicKey) {
-      return Response.json(
-        { error: "Invalid transaction manager public key" },
-        { status: 400 },
+wss.on("connection", async (ws) => {
+  try {
+    // Read exactly one request message from the client.
+    const msg = (await readJsonOnce(ws)) as {
+      type: string;
+      data?: unknown;
+    };
+    if (msg.type !== "transaction" && msg.type !== "message") {
+      ws.send(
+        JSON.stringify({
+          event: "error",
+          data: { error: `Unsupported request type: ${msg.type}` },
+        }),
       );
+      ws.close();
+      return;
     }
 
-    const jwk = JSON.parse(process.env.TX_MANAGER_PRIVATE_KEY!);
-    const privateKey = await crypto.subtle.importKey(
-      "jwk",
-      jwk,
-      { name: "Ed25519" },
-      false,
-      ["sign"],
+    // Shared: load signer key once per connection.
+    const { keyPair } = await createKeypairSignerFromBase58(
+      process.env.TX_MANAGER_SECRET_KEY!,
     );
 
-    const signatures: string[] = [];
+    if (msg.type === "transaction") {
+      const { publicKey, payload } = (msg.data ?? {}) as {
+        publicKey: string;
+        payload: {
+          transaction: string;
+          transactionMessageBytes?: string;
+          authResponses?: TransactionAuthDetails[];
+        }[];
+      };
+
+      if (publicKey !== transactionManagerConfig.publicKey) {
+        ws.send(
+          JSON.stringify({
+            event: "error",
+            data: { error: "Invalid transaction manager public key" },
+          }),
+        );
+        ws.close();
+        return;
+      }
 
-    for (const payloadItem of payload) {
-      const result = await verifyTransaction(
-        rpc,
-        transactionManagerConfig,
-        payloadItem,
-      );
+      const signatures: string[] = [];
+      for (const payloadItem of payload) {
+        const { messageBytes, verificationResults } = await verifyTransaction(
+          transactionManagerConfig,
+          payloadItem,
+        );
+
+        await enforcePolicies(verificationResults);
+
+        // (Optional) if your policy requires an out-of-band human approval:
+        // ws.send(JSON.stringify({ event: "pending_transaction_approval", data: { validTill: Date.now() + 60_000 } }));
 
-      await enforcePolicies(result);
+        // await waitForYourApprovalSystem(...);
 
-      const signatureBytes = await crypto.subtle.sign(
-        { name: "Ed25519" },
-        privateKey,
-        result.transactionMessage,
+        // ws.send(JSON.stringify({ event: "transaction_approved", data: {} }));
+
+        const signatureBytes = await signBytes(
+          keyPair.privateKey,
+          messageBytes,
+        );
+
+        signatures.push(getBase58Decoder().decode(signatureBytes));
+      }
+
+      ws.send(JSON.stringify({ event: "signatures", data: { signatures } }));
+      ws.close();
+    } else {
+      // msg.type === "message"
+      const { publicKey, payload } = (msg.data ?? {}) as {
+        publicKey: string;
+        payload: CompleteMessageRequest;
+      };
+
+      if (publicKey !== transactionManagerConfig.publicKey) {
+        ws.send(
+          JSON.stringify({
+            event: "error",
+            data: { error: "Invalid transaction manager public key" },
+          }),
+        );
+        ws.close();
+        return;
+      }
+
+      const { messageBytes, verificationResults } = await verifyMessage(
+        publicKey,
+        payload,
       );
 
-      signatures.push(
-        getBase58Decoder().decode(new Uint8Array(signatureBytes)),
+      // (Optional) if your policy requires an out-of-band human approval:
+
+      // ws.send(JSON.stringify({ event: "pending_transaction_approval", data: { validTill: Date.now() + 60_000 } }));
+
+      // await waitForYourApprovalSystem(...);
+
+      // ws.send(JSON.stringify({ event: "transaction_approved", data: {} }));
+
+      const signatureBytes = await signBytes(keyPair.privateKey, messageBytes);
+
+      ws.send(
+        JSON.stringify({
+          event: "signatures",
+          data: {
+            signatures: [getBase58Decoder().decode(signatureBytes)],
+          },
+        }),
       );
+      ws.close();
     }
-
-    return Response.json({ signatures });
   } catch (e) {
     const msg = e instanceof Error ? e.message : String(e);
-    return Response.json({ error: msg }, { status: 500 });
+    try {
+      ws.send(JSON.stringify({ event: "error", data: { error: msg } }));
+    } finally {
+      ws.close();
+    }
   }
+});
+
+server.listen(3000, () => {
+  console.log("Transaction manager listening on http://localhost:3000/sign");
+});
+
+function readJsonOnce(ws: import("ws").WebSocket): Promise<unknown> {
+  return new Promise((resolve, reject) => {
+    const onMessage = (data: import("ws").RawData) => {
+      try {
+        const text = typeof data === "string" ? data : data.toString("utf8");
+        resolve(JSON.parse(text));
+      } catch (e) {
+        reject(e);
+      } finally {
+        ws.off("message", onMessage);
+      }
+    };
+    ws.on("message", onMessage);
+  });
 }
 ```
 
@@ -157,9 +312,9 @@ export async function POST(req: Request) {
 
 Your transaction manager should express your security model in one place.
 
-`verifyTransaction` returns a `VerificationResults` object with:
+`verifyTransaction` returns a `VerifyTransactionResult` object with:
 
-- **`transactionMessage`**: Raw transaction message bytes to sign.
+- **`messageBytes`**: Raw transaction message bytes to sign.
 - **`verificationResults`**: An array of batches, where each batch contains:
   - **`instructions`**: Decoded on-chain instructions.
   - **`signers`**: The signers that successfully passed verification for those instructions.
@@ -172,7 +327,8 @@ The example below:
 - Caps each transfer at **1 SOL**.
 
 ```ts
-import type { VerificationResults } from "@revibase/transaction-manager";
+import type { ExpectedTransactionSigner } from "@revibase/transaction-manager";
+import type { Instruction } from "gill";
 import {
   SYSTEM_PROGRAM_ADDRESS,
   identifySystemInstruction,
@@ -184,13 +340,18 @@ import {
 const ALLOWED_ORIGINS = new Set(["https://app.revibase.com"]);
 const MAX_TRANSFER_LAMPORTS = 1_000_000_000n; // 1 SOL
 
-export async function enforcePolicies(results: VerificationResults) {
-  for (const batch of results.verificationResults) {
+export async function enforcePolicies(
+  verificationResults: {
+    instructions: Instruction[];
+    signers: ExpectedTransactionSigner[];
+  }[],
+) {
+  for (const batch of verificationResults) {
     const { signers, instructions } = batch;
 
     for (const signer of signers) {
-      const origin = "client" in signer ? signer.client?.origin : undefined;
-      if (origin && !ALLOWED_ORIGINS.has(origin)) {
+      // Only secp256r1/passkey signers include `client` metadata (origin + client JWK).
+      if ("client" in signer && !ALLOWED_ORIGINS.has(signer.client.origin)) {
         throw new Error("Unauthorized app origin");
       }
     }
@@ -233,16 +394,23 @@ export async function enforcePolicies(results: VerificationResults) {
 
 This package exports the following public API:
 
-- **`verifyTransaction(rpc, transactionManagerConfig, payload, wellKnownProxyUrl?)`**
+- **`verifyTransaction(transactionManagerConfig, payload, getClientDetails?)`**
   - Decodes and verifies a serialized Solana transaction.
-  - Returns a `VerificationResults` object with the transaction message bytes and verification batches.
+  - Returns a `VerifyTransactionResult` object with the transaction message bytes and verification batches.
+
+- **`verifyMessage(publicKey, payload, getClientDetails?)`**
+  - Verifies a sign-in / message authorization payload (`CompleteMessageRequest`).
+  - Returns a `VerifyMessageResult` containing:
+    - `messageBytes`: the message bytes to sign (Ed25519).
+    - `verificationResults`: the verified payload plus the extracted signer metadata.
+  - Uses `payload.data.payload.startRequest.rpId` and `payload.data.payload.startRequest.clientOrigin` for WebAuthn verification (RP ID + expected origin).
 
 - **`TransactionManagerConfig`**
   - `publicKey`: Transaction manager public key (base58 string).
   - `url`: Public URL of your transaction manager endpoint.
 
-- **`VerificationResults`**
-  - `transactionMessage`: Transaction message bytes to sign.
+- **`VerifyTransactionResult`**
+  - `messageBytes`: Transaction message bytes to sign.
   - `verificationResults`: Array of `{ instructions, signers }` batches used by your policy.
 
 ---