@revibase/transaction-manager 0.1.0 → 0.2.0

package/README.md

@@ -1,8 +1,8 @@
 # @revibase/transaction-manager
 
-Transaction verification and policy-based signing for the Revibase multi-wallet system.
+Server-side transaction verification and policy-based signing for the Revibase multi-wallet system.
 
-This package verifies incoming Solana transaction intents, extracts the on-chain instructions and verified signers, and lets you apply custom allow/deny policies before producing Ed25519 signatures.
+This package verifies incoming Solana transaction intents, extracts the on-chain instructions and verified signers, and lets you apply your own allow/deny policies before producing Ed25519 signatures.
 
 ---
 
@@ -18,119 +18,207 @@ npm install @revibase/transaction-manager
 
 A **transaction manager** is a server-side signer that:
 
-1. Verifies a transaction request using your custom rules
-2. Applies your own business / security policy
+1. Verifies a transaction request using your rules
+2. Applies your business and security policy
 3. Signs the Solana **transaction message bytes** (Ed25519)
 4. Returns base58-encoded signatures to the caller
 
+Use this package when you want a single, auditable place in your backend where every multi-wallet transaction is verified and approved before it is signed.
+
 ---
 
 ## Usage
 
-### Basic signing endpoint
+### 1. Generate a transaction manager keypair
+
+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",
+]);
+
+const [pubRaw, privJwk] = await Promise.all([
+  crypto.subtle.exportKey("raw", keyPair.publicKey),
+  crypto.subtle.exportKey("jwk", keyPair.privateKey),
+]);
+
+console.log({
+  publicKey: getBase58Decoder().decode(new Uint8Array(pubRaw)),
+  privateKey: JSON.stringify(privJwk),
+});
+```
+
+Store:
+
+- **`publicKey`**: as the transaction manager public key (base58).
+- **`privateKey`**: as a JWK JSON 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_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`.
+
+### 3. Implement a basic signing endpoint
+
+Expose a public HTTPS endpoint, for example:
+
+`https://your-transaction-manager.com/sign`
+
+This endpoint:
+
+- Verifies that the request is intended for this transaction manager.
+- Calls `verifyTransaction` to decode and verify the transaction.
+- Applies your custom policy.
+- Signs the verified transaction message bytes.
+- Returns base58-encoded signatures.
 
 ```ts
 import { verifyTransaction } from "@revibase/transaction-manager";
-import { createSolanaRpc, getBase58Encoder } from "gill";
+import { createSolanaRpc, getBase58Decoder } from "gill";
+import { enforcePolicies } from "@/lib/policy";
 
-const rpc = createSolanaRpc("https://api.mainnet-beta.solana.com");
+const rpc = createSolanaRpc(
+  process.env.RPC_URL ?? "https://api.mainnet-beta.solana.com",
+);
 
 const transactionManagerConfig = {
-  /**
-   * Base58-encoded Ed25519 public key of this transaction manager
-   */
-  publicKey: "YOUR_TRANSACTION_MANAGER_PUBLIC_KEY",
-
-  /**
-   * Public URL of this signing endpoint
-   */
-  url: "https://your-transaction-manager.com/sign",
+  publicKey: process.env.TX_MANAGER_PUBLIC_KEY!, // base58
+  url: process.env.TX_MANAGER_URL!, // public HTTPS URL of this endpoint
 };
 
-export async function sign(request: Request): Promise<Response> {
-  const { publicKey, payload } = await request.json();
-
-  if (publicKey !== transactionManagerConfig.publicKey) {
-    return new Response(
-      JSON.stringify({ error: "Invalid transaction manager public key" }),
-      {
-        status: 400,
-        headers: { "Content-Type": "application/json" },
-      },
+export async function POST(req: Request) {
+  try {
+    const { publicKey, payload } = (await req.json()) as {
+      publicKey: string;
+      payload: {
+        transaction: string;
+        transactionMessageBytes?: string;
+        authResponses?: unknown[];
+      }[];
+    };
+
+    if (publicKey !== transactionManagerConfig.publicKey) {
+      return Response.json(
+        { error: "Invalid transaction manager public key" },
+        { status: 400 },
+      );
+    }
+
+    const jwk = JSON.parse(process.env.TX_MANAGER_PRIVATE_KEY!);
+    const privateKey = await crypto.subtle.importKey(
+      "jwk",
+      jwk,
+      { name: "Ed25519" },
+      false,
+      ["sign"],
     );
-  }
 
-  // Load the Ed25519 private key corresponding to `transactionManagerConfig.publicKey`
-  const privateKey = await loadTransactionManagerPrivateKey(publicKey);
+    const signatures: string[] = [];
 
-  const signatures: string[] = [];
+    for (const payloadItem of payload) {
+      const result = await verifyTransaction(
+        rpc,
+        transactionManagerConfig,
+        payloadItem,
+      );
 
-  for (const payloadItem of payload) {
-    const { messageBytes, verificationResults } = await verifyTransaction(
-      rpc,
-      transactionManagerConfig,
-      payloadItem,
-    );
+      await enforcePolicies(result);
 
-    /**
-     * ------------------------------------------------------------------
-     * Custom policy enforcement
-     * ------------------------------------------------------------------
-     *
-     * `verificationResults` contains fully verified metadata such as:
-     *
-     * - `instructions`: decoded Solana instructions that will be sent on-chain
-     * - `verifiedSigners`: wallets, members, and credentials involved
-     *
-     * Use this information to:
-     * - allow only transfers
-     * - reject config changes
-     * - restrict destination addresses
-     * - enforce amount limits
-     */
-
-    // Sign the Solana *message* bytes (not the full transaction)
-    const signatureBytes = await crypto.subtle.sign(
-      { name: "Ed25519" },
-      privateKey,
-      messageBytes,
-    );
+      const signatureBytes = await crypto.subtle.sign(
+        { name: "Ed25519" },
+        privateKey,
+        result.transactionMessage,
+      );
 
-    // Return base58-encoded signatures
-    signatures.push(getBase58Encoder().encode(signatureBytes));
-  }
+      signatures.push(
+        getBase58Decoder().decode(new Uint8Array(signatureBytes)),
+      );
+    }
 
-  return new Response(JSON.stringify({ signatures }), {
-    headers: { "Content-Type": "application/json" },
-  });
+    return Response.json({ signatures });
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    return Response.json({ error: msg }, { status: 500 });
+  }
 }
 ```
 
 ---
 
-## Key Management
+## Policy checks
+
+Your transaction manager should express your security model in one place.
+
+`verifyTransaction` returns a `VerificationResults` object with:
+
+- **`transactionMessage`**: 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.
+
+The example below:
+
+- Allows only native SOL transfers.
+- Requires the request to originate from `https://app.revibase.com`.
+- Rejects any non-system-program instruction.
+- Caps each transfer at **1 SOL**.
 
 ```ts
-async function loadTransactionManagerPrivateKey(
-  publicKey: string,
-): Promise<CryptoKey> {
-  /**
-   * Fetch the private key corresponding to `publicKey`.
-   *
-   * - Must be an Ed25519 private key
-   * - SHOULD be stored in a secure system (KMS / HSM / Secrets Manager)
-   * - MUST NOT be hard-coded in source code
-   */
-
-  const jwk = await fetchPrivateKeyJwkFromSecureStore(publicKey);
-
-  return crypto.subtle.importKey(
-    "jwk",
-    jwk,
-    { name: "Ed25519" },
-    false, // non-extractable
-    ["sign"],
-  );
+import type { VerificationResults } from "@revibase/transaction-manager";
+import {
+  SYSTEM_PROGRAM_ADDRESS,
+  identifySystemInstruction,
+  parseTransferSolInstruction,
+  parseTransferSolWithSeedInstruction,
+  SystemInstruction,
+} from "gill";
+
+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) {
+    const { signers, instructions } = batch;
+
+    for (const signer of signers) {
+      const origin = "client" in signer ? signer.client?.origin : undefined;
+      if (origin && !ALLOWED_ORIGINS.has(origin)) {
+        throw new Error("Unauthorized app origin");
+      }
+    }
+
+    for (const ix of instructions) {
+      if (ix.programAddress.toString() !== SYSTEM_PROGRAM_ADDRESS.toString()) {
+        throw new Error("Unauthorized program");
+      }
+
+      const ixKind = identifySystemInstruction(ix.data);
+
+      if (
+        ixKind !== SystemInstruction.TransferSol &&
+        ixKind !== SystemInstruction.TransferSolWithSeed
+      ) {
+        throw new Error("Unauthorized instruction");
+      }
+
+      const parsed =
+        ixKind === SystemInstruction.TransferSol
+          ? parseTransferSolInstruction(ix)
+          : parseTransferSolWithSeedInstruction(ix);
+
+      if (parsed.data.amount > MAX_TRANSFER_LAMPORTS) {
+        throw new Error("Transfer limit exceeded");
+      }
+    }
+  }
 }
 ```
 
@@ -141,17 +229,25 @@ async function loadTransactionManagerPrivateKey(
 
 ---
 
-## What `verifyTransaction` Does
+## API surface
+
+This package exports the following public API:
+
+- **`verifyTransaction(rpc, transactionManagerConfig, payload, wellKnownProxyUrl?)`**
+  - Decodes and verifies a serialized Solana transaction.
+  - Returns a `VerificationResults` object with the transaction message bytes and verification batches.
 
-`verifyTransaction` performs:
+- **`TransactionManagerConfig`**
+  - `publicKey`: Transaction manager public key (base58 string).
+  - `url`: Public URL of your transaction manager endpoint.
 
-- Signature verification of all required members
-- Instruction decoding and validation
-- Wallet, member, and permission checks
+- **`VerificationResults`**
+  - `transactionMessage`: Transaction message bytes to sign.
+  - `verificationResults`: Array of `{ instructions, signers }` batches used by your policy.
 
 ---
 
-## What This Package Does _Not_ Do
+## What this package does _not_ do
 
 - ❌ Store private keys for you
 - ❌ Enforce your business rules automatically