@opensea/wallet-adapters 0.2.1 → 0.3.1

package/README.md

@@ -2,6 +2,17 @@
 
 Provider-agnostic wallet adapters for signing and sending transactions across managed and local backends.
 
+## Why wallet-adapters?
+
+`@opensea/wallet-adapters` is the shared wallet layer used across the OpenSea developer toolchain. Every package that needs to sign transactions depends on the same `WalletAdapter` interface:
+
+- [`@opensea/sdk`](https://github.com/ProjectOpenSea/opensea-js) — TypeScript SDK for buying, selling, and managing NFTs
+- [`@opensea/cli`](https://github.com/ProjectOpenSea/opensea-cli) — command-line interface for the OpenSea API
+- [`@opensea/tool-sdk`](https://github.com/ProjectOpenSea/tool-sdk) — SDK for building ERC-8257 AI agent tools
+- [`opensea-skill`](https://github.com/ProjectOpenSea/opensea-skill) — modular AI agent skills for Claude, Devin, and other assistants
+
+By implementing the `WalletAdapter` interface once, a new wallet provider automatically works everywhere — the CLI, the SDK, AI agent tool execution, and any future package that depends on this library.
+
 ## Features
 
 - **Provider-agnostic interface** — unified `WalletAdapter` abstraction with capabilities declaration
@@ -151,6 +162,33 @@ wallet.onResponse = (method, result, durationMs) => {
 }
 ```
 
+## Adding a New Provider
+
+To add a wallet provider, implement the `WalletAdapter` interface:
+
+```ts
+import type { WalletAdapter, WalletCapabilities } from "@opensea/wallet-adapters"
+
+export class MyProviderAdapter implements WalletAdapter {
+  readonly name = "my-provider"
+  readonly capabilities: WalletCapabilities = {
+    signMessage: true,
+    signTypedData: true,
+    managedGas: true,
+    managedNonce: true,
+  }
+
+  async getAddress(): Promise<string> { /* ... */ }
+  async sendTransaction(tx) { /* ... */ }
+  async signMessage(request) { /* ... */ }
+  async signTypedData(request) { /* ... */ }
+
+  static fromEnv(): MyProviderAdapter { /* ... */ }
+}
+```
+
+Then register it in the `createWalletFromEnv()` factory in `src/factory.ts` so the CLI and tool-sdk auto-detect it from environment variables.
+
 ## License
 
 MIT

package/dist/ethers.d.ts

@@ -1,4 +1,4 @@
-import { W as WalletAdapter } from './index-DFTwYt_e.js';
+import { W as WalletAdapter } from './index-jjHnOuwA.js';
 
 /**
  * Bridge between WalletAdapter and ethers.js Signer.

package/dist/{index-DFTwYt_e.d.ts → index-jjHnOuwA.d.ts}

@@ -5,6 +5,61 @@
  * Designed to be provider-agnostic and extensible for future signing
  * capabilities (EIP-712, EIP-191, batch transactions, etc.).
  */
+/**
+ * Provider-shaped wallet metadata used by the `opensea wallet info` CLI
+ * command and by callers auditing the security posture of an agent wallet.
+ *
+ * Each variant surfaces only what the provider's API actually exposes for
+ * the calling credentials. Fields whose absence indicates a hardening gap
+ * (no on-chain policy enforcement, no off-machine credential gating
+ * administrative changes, etc.) are intentionally surfaced as falsy values
+ * rather than hidden, so callers can warn the user.
+ */
+type WalletInfo = {
+    provider: "privy";
+    address: string;
+    chainType: string;
+    policyIds: string[];
+    ownerKeyId: string | null;
+    additionalSignerCount: number;
+    /**
+     * True iff the wallet has an `owner_id` set, in which case all
+     * `/v1/wallets/{id}/rpc` requests must carry an authorization
+     * signature from the owner's key quorum. False means the env app
+     * secret can sign and rewrite policy unilaterally.
+     */
+    ownerEnforcesAuthKey: boolean;
+} | {
+    provider: "turnkey";
+    address: string;
+    organizationId: string;
+    userId: string;
+    username: string;
+    /**
+     * True iff the calling API user is in the organization's root
+     * quorum. Root users bypass Turnkey's policy engine entirely, so a
+     * leaked root API key has the same blast radius as a raw private
+     * key — sign, mutate, export, all unconstrained.
+     */
+    isRootUser: boolean;
+} | {
+    provider: "fireblocks";
+    address: string;
+    vaultId: string;
+    /**
+     * Fireblocks does not expose API-user role via API. The CLI
+     * surfaces a static reminder to verify the role at the console.
+     */
+    roleIntrospectable: false;
+} | {
+    provider: "bankr";
+    address: string;
+    /**
+     * Bankr does not expose key-scope flags via API. The CLI surfaces
+     * a static reminder to verify scope at bankr.bot/api.
+     */
+    scopeIntrospectable: false;
+};
 interface TransactionRequest {
     to: string;
     data: string;
@@ -53,8 +108,16 @@ interface WalletAdapter {
     signMessage?(request: SignMessageRequest): Promise<string>;
     /** Sign EIP-712 typed data. Throws if not supported. */
     signTypedData?(request: SignTypedDataRequest): Promise<string>;
+    /**
+     * Read-only metadata about the wallet's security posture. Used by the
+     * `opensea wallet info` CLI to surface hardening gaps (no policy, no
+     * authorization-key gating, root-user API key, etc.). Optional because
+     * not every adapter has a meaningful introspection surface — the
+     * private-key adapter, for instance, has nothing to report.
+     */
+    getWalletInfo?(): Promise<WalletInfo>;
     /** Optional RPC URL for read operations (gas estimation, nonce, etc.) */
-    getRpcUrl?(): string;
+    getRpcUrl?(): string | undefined;
     /** Optional hook called before each adapter request (for metrics/logging) */
     onRequest?: (method: string, params: unknown) => void;
     /** Optional hook called after each adapter response (for metrics/logging) */
@@ -77,4 +140,4 @@ interface WalletCapabilities {
 type WalletProvider = "privy" | "turnkey" | "fireblocks" | "bankr" | "private-key";
 declare const WALLET_PROVIDERS: WalletProvider[];
 
-export { type SignMessageRequest as S, type TransactionRequest as T, type WalletAdapter as W, type WalletCapabilities as a, type TransactionResult as b, type SignTypedDataRequest as c, type WalletProvider as d, WALLET_PROVIDERS as e };
+export { type SignMessageRequest as S, type TransactionRequest as T, type WalletAdapter as W, type WalletCapabilities as a, type WalletInfo as b, type TransactionResult as c, type SignTypedDataRequest as d, type WalletProvider as e, WALLET_PROVIDERS as f };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { W as WalletAdapter, a as WalletCapabilities, T as TransactionRequest, b as TransactionResult, S as SignMessageRequest, c as SignTypedDataRequest, d as WalletProvider } from './index-DFTwYt_e.js';
-export { e as WALLET_PROVIDERS } from './index-DFTwYt_e.js';
+import { W as WalletAdapter, a as WalletCapabilities, b as WalletInfo, T as TransactionRequest, c as TransactionResult, S as SignMessageRequest, d as SignTypedDataRequest, e as WalletProvider } from './index-jjHnOuwA.js';
+export { f as WALLET_PROVIDERS } from './index-jjHnOuwA.js';
 
 /**
  * Bankr wallet adapter.
@@ -7,6 +7,38 @@ export { e as WALLET_PROVIDERS } from './index-DFTwYt_e.js';
  * Uses Bankr's Wallet API to sign and send transactions via a managed
  * agent wallet. Authentication is done via API key in the X-API-Key header.
  *
+ * # Security model
+ *
+ * This adapter is **signing-only by design.** It exposes only the
+ * primitives an agent needs: `getAddress`, `sendTransaction`,
+ * `signMessage`, `signTypedData`, and `getWalletInfo`. Future
+ * contributors: do not add scope-mutation or key-management surfaces
+ * here — Bankr does not expose them via API anyway, and adding
+ * adapter-side wrappers around dashboard ops would be a footgun.
+ *
+ * Effective hardening is done at the API key configuration level on
+ * bankr.bot/api, not in this adapter:
+ *
+ *   1. For monitoring-only agents, enable the key's `readOnly` flag —
+ *      `/wallet/sign` and `/wallet/submit` will return 403.
+ *
+ *   2. For signing agents, set `allowedRecipients` (an EVM/Solana
+ *      address allowlist) and `allowedIps` (CIDR allowlist) on the
+ *      key. Disable `agentApiEnabled` if the agent does not need
+ *      Bankr's prompt API.
+ *
+ *   3. Set per-key daily message limits at bankr.bot/api.
+ *
+ *   4. Bankr does not expose key-scope flags via API, so
+ *      `getWalletInfo()` cannot verify these settings at runtime —
+ *      `opensea wallet info` reminds the user to verify scope at the
+ *      dashboard. Re-confirm after any key rotation.
+ *
+ *   5. Bankr keys cannot enforce aggregate dollar/ETH spend caps; daily
+ *      message-quota limits are not the same thing. Use the hot/cold
+ *      wallet float pattern documented in
+ *      `packages/skill/opensea-wallet/references/wallet-funding.md`.
+ *
  * Required environment variables:
  *   BANKR_API_KEY — Bankr API key with Wallet API access enabled
  *
@@ -14,7 +46,7 @@ export { e as WALLET_PROVIDERS } from './index-DFTwYt_e.js';
  *   BANKR_API_BASE_URL — Override the Bankr API base URL
  *
  * @see https://docs.bankr.bot/agent-api/authentication
- * @see https://docs.bankr.bot/wallet-api/wallet-info
+ * @see https://docs.bankr.bot/agent-api/access-control
  */
 
 interface BankrConfig {
@@ -33,6 +65,7 @@ declare class BankrAdapter implements WalletAdapter {
     private get baseUrl();
     private get authHeaders();
     getAddress(): Promise<string>;
+    getWalletInfo(): Promise<WalletInfo>;
     sendTransaction(tx: TransactionRequest): Promise<TransactionResult>;
     signMessage(request: SignMessageRequest): Promise<string>;
     signTypedData(request: SignTypedDataRequest): Promise<string>;
@@ -52,8 +85,43 @@ declare const CHAIN_TO_FIREBLOCKS_ASSET: Record<number, string>;
  * Uses Fireblocks' REST API to sign and send transactions through their
  * enterprise-grade MPC custody infrastructure.
  *
+ * # Security model
+ *
+ * This adapter is **signing-only by design.** It exposes only the
+ * primitives an agent needs to sign and send transactions:
+ * `getAddress`, `sendTransaction`, `signMessage`, `signTypedData`, and
+ * `getWalletInfo`. Future contributors: **do not add
+ * `createTransactionAuthPolicy`, `updateUser`, `createApiUser`,
+ * `whitelistAddress`, or any other administrative endpoint to this
+ * adapter.** If they exist, an agent will find and use them.
+ *
+ * Effective hardening requires creating the API key with the **`Signer`
+ * role** and nothing broader:
+ *
+ *   1. Fireblocks supports nine API key roles: Admin, Signer,
+ *      NCW_SIGNER, Non-Signing Admin, Approver, Editor, NCW_ADMIN,
+ *      Viewer, and Security Auditor. Only `Signer` (or `NCW_SIGNER`)
+ *      gives signing capability without governance access. Do not use
+ *      `Admin` for an agent.
+ *
+ *   2. Fireblocks does not expose API-user role via API — there is no
+ *      `/v1/users/me` introspection endpoint, and `GET /v1/users/{id}`
+ *      itself requires admin role. `getWalletInfo()` therefore cannot
+ *      verify the calling key's role at runtime; verify it manually at
+ *      console.fireblocks.io and re-confirm whenever you rotate the key.
+ *
+ *   3. TAP changes require admin quorum approval at the console — a
+ *      leaked Signer-role key cannot rewrite TAP. This is structurally
+ *      stronger than Privy or Turnkey, but only if the key is actually
+ *      `Signer` rather than `Admin`.
+ *
+ *   4. TAP rules cap per-tx values; aggregate (daily/weekly) caps are
+ *      not a TAP primitive. Use the hot/cold wallet float pattern
+ *      documented in
+ *      `packages/skill/opensea-wallet/references/wallet-funding.md`.
+ *
  * Required environment variables:
- *   FIREBLOCKS_API_KEY       — Fireblocks API key
+ *   FIREBLOCKS_API_KEY       — Fireblocks API key (must be Signer role)
  *   FIREBLOCKS_API_SECRET    — Fireblocks API secret (RSA private key, PEM-encoded)
  *   FIREBLOCKS_VAULT_ID      — Fireblocks vault account ID
  *
@@ -62,7 +130,8 @@ declare const CHAIN_TO_FIREBLOCKS_ASSET: Record<number, string>;
  *   FIREBLOCKS_ASSET_ID           — Override the Fireblocks asset ID
  *   FIREBLOCKS_MAX_POLL_ATTEMPTS  — Override max polling attempts (default: 60 = 120s)
  *
- * @see https://developers.fireblocks.com/docs/introduction
+ * @see https://developers.fireblocks.com/docs/manage-api-keys
+ * @see https://developers.fireblocks.com/docs/manage-users
  */
 
 interface FireblocksConfig {
@@ -88,6 +157,7 @@ declare class FireblocksAdapter implements WalletAdapter {
     private hashBody;
     private resolveAssetId;
     getAddress(): Promise<string>;
+    getWalletInfo(): Promise<WalletInfo>;
     sendTransaction(tx: TransactionRequest): Promise<TransactionResult>;
     signMessage(request: SignMessageRequest): Promise<string>;
     signTypedData(request: SignTypedDataRequest): Promise<string>;
@@ -106,15 +176,16 @@ declare class FireblocksAdapter implements WalletAdapter {
  *
  * Required environment variables:
  *   PRIVATE_KEY — Hex-encoded private key (with or without 0x prefix)
- *   RPC_URL    — JSON-RPC endpoint for broadcasting and gas estimation
  *
  * Optional:
+ *   RPC_URL        — JSON-RPC endpoint for broadcasting and gas estimation
+ *                    (required only when sending transactions)
  *   WALLET_ADDRESS — Pre-computed address (skips derivation)
  */
 
 interface PrivateKeyConfig {
     privateKey: string;
-    rpcUrl: string;
+    rpcUrl?: string;
     address?: string;
 }
 declare class PrivateKeyAdapter implements WalletAdapter {
@@ -126,7 +197,7 @@ declare class PrivateKeyAdapter implements WalletAdapter {
     private cachedAddress?;
     constructor(config: PrivateKeyConfig);
     static fromEnv(): PrivateKeyAdapter;
-    getRpcUrl(): string;
+    getRpcUrl(): string | undefined;
     getAddress(): Promise<string>;
     sendTransaction(tx: TransactionRequest): Promise<TransactionResult>;
     signMessage(request: SignMessageRequest): Promise<string>;
@@ -141,16 +212,58 @@ declare class PrivateKeyAdapter implements WalletAdapter {
  * Transactions are governed by Privy's programmable policy engine —
  * policies are evaluated in a trusted execution environment before signing.
  *
+ * # Security model
+ *
+ * This adapter is **signing-only by design.** It exposes only the
+ * primitives an agent needs to sign transactions and read wallet
+ * metadata: `getAddress`, `sendTransaction`, `signMessage`,
+ * `signTypedData`, and `getWalletInfo`. It deliberately does not, and
+ * should not, expose policy mutation, owner-key rotation, additional-
+ * signer changes, key export, or wallet deletion. Future contributors:
+ * **do not add `setPolicy`, `rotateOwner`, `addSigner`, or similar
+ * mutation methods to this adapter.** If they exist, an agent will find
+ * and use them — including raising its own spending cap.
+ *
+ * Effective hardening requires Privy-side configuration in addition to
+ * this adapter's defaults:
+ *
+ *   1. Create the wallet with an `owner_id` (a key quorum). The owner's
+ *      private key MUST live outside the agent environment — on a
+ *      trusted operator machine, in a hardware wallet, or in a separate
+ *      vault. The owner gates all `PATCH /v1/wallets/{id}` and similar
+ *      administrative operations.
+ *
+ *   2. Register the agent's signing key as an `additional_signer` on the
+ *      wallet, with `override_policy_ids` set to the policy you want
+ *      the agent to be subject to. The agent's signing key may live in
+ *      env (`PRIVY_AUTH_SIGNING_KEY`) — it has signing power but cannot
+ *      mutate policy, signers, or owner.
+ *
+ *   3. Apply a Privy policy that caps per-tx spend, allowlists
+ *      contracts, and restricts chains. Policies are stateless per-tx
+ *      evaluators — they cannot enforce aggregate (daily/weekly)
+ *      caps. Use the hot/cold wallet float pattern documented in
+ *      `packages/skill/opensea-wallet/references/wallet-funding.md`
+ *      for aggregate ceilings.
+ *
  * Required environment variables:
  *   PRIVY_APP_ID      — Privy application ID
  *   PRIVY_APP_SECRET  — Privy application secret
  *   PRIVY_WALLET_ID   — Wallet ID to use for signing
  *
  * Optional:
- *   PRIVY_API_BASE_URL — Override the Privy API base URL
+ *   PRIVY_API_BASE_URL      — Override the Privy API base URL
+ *   PRIVY_AUTH_SIGNING_KEY  — Base64-encoded PKCS8 P-256 private key for
+ *                             an `additional_signer` on this wallet. When
+ *                             set, the adapter signs every POST /rpc
+ *                             request with it and attaches the
+ *                             `privy-authorization-signature` header.
+ *                             Required when the wallet has an `owner_id`
+ *                             set; ignored when it does not.
  *
- * @see https://docs.privy.io/wallets/wallets/server-side-access
+ * @see https://docs.privy.io/wallets/wallets
  * @see https://docs.privy.io/controls/policies/overview
+ * @see https://docs.privy.io/controls/authorization-keys/overview
  */
 
 interface PrivyConfig {
@@ -158,6 +271,15 @@ interface PrivyConfig {
     appSecret: string;
     walletId: string;
     baseUrl?: string;
+    /**
+     * Optional base64-encoded PKCS8 P-256 authorization private key.
+     * When set, every POST /v1/wallets/{id}/rpc request is signed with it
+     * and the resulting signature is attached as
+     * `privy-authorization-signature`. Use this when the wallet has an
+     * `owner_id` configured and the agent's key is registered as an
+     * `additional_signer`.
+     */
+    authSigningKey?: string;
 }
 declare class PrivyAdapter implements WalletAdapter {
     readonly name = "privy";
@@ -169,8 +291,16 @@ declare class PrivyAdapter implements WalletAdapter {
     constructor(config: PrivyConfig);
     static fromEnv(): PrivyAdapter;
     private get baseUrl();
-    private get authHeaders();
+    private get basicAuthHeaders();
+    /**
+     * Build headers for a POST /rpc call, including the authorization
+     * signature when `authSigningKey` is configured. Lazy-imports
+     * `@privy-io/node` so users who don't enable auth-key signing don't
+     * need the optional peer dependency installed.
+     */
+    private rpcHeaders;
     getAddress(): Promise<string>;
+    getWalletInfo(): Promise<WalletInfo>;
     sendTransaction(tx: TransactionRequest): Promise<TransactionResult>;
     signMessage(request: SignMessageRequest): Promise<string>;
     signTypedData(request: SignTypedDataRequest): Promise<string>;
@@ -183,6 +313,42 @@ declare class PrivyAdapter implements WalletAdapter {
  * signing infrastructure. Authentication uses Turnkey's stamp scheme:
  * each request body is hashed and signed with a P-256 ECDSA key.
  *
+ * # Security model
+ *
+ * This adapter is **signing-only by design.** It exposes only the
+ * primitives an agent needs to sign transactions and read user
+ * metadata: `getAddress`, `sendTransaction`, `signMessage`,
+ * `signTypedData`, and `getWalletInfo`. Future contributors: **do not
+ * add `createPolicy`, `deletePolicy`, `createApiKeys`, `updateUser`,
+ * `exportWallet`, or any other administrative activity submission to
+ * this adapter.** If they exist, an agent will find and use them.
+ *
+ * Effective hardening requires creating the API user as a **non-root
+ * user** with a tightly scoped sign-only policy:
+ *
+ *   1. Root users in Turnkey bypass the policy engine entirely. A
+ *      leaked root-user API key has the same blast radius as a raw
+ *      private key — it can sign anything, mutate any policy, mint new
+ *      wallets, and export keys. Do not use a root user as the agent's
+ *      API user.
+ *
+ *   2. Create a non-root API user, then attach a policy that allows
+ *      only `ACTIVITY_TYPE_SIGN_TRANSACTION_V2` (and
+ *      `ACTIVITY_TYPE_SIGN_RAW_PAYLOAD_V2` if EIP-712 is needed) for
+ *      the wallet addresses the agent should be able to sign for.
+ *      Default-deny on everything else; Turnkey policies default to
+ *      deny so this is mostly a matter of writing the allowlist.
+ *
+ *   3. Note that Turnkey policies are stateless per-activity
+ *      evaluators — they cannot enforce aggregate (daily/weekly) caps.
+ *      Use the hot/cold wallet float pattern documented in
+ *      `packages/skill/opensea-wallet/references/wallet-funding.md`
+ *      for aggregate ceilings.
+ *
+ * `getWalletInfo()` calls `whoami` and `get_organization` to surface
+ * whether the API user is in the root quorum, so `opensea wallet info`
+ * can warn loudly if the agent is running as root.
+ *
  * Required environment variables:
  *   TURNKEY_API_PUBLIC_KEY   — Turnkey API public key (hex-encoded)
  *   TURNKEY_API_PRIVATE_KEY  — Turnkey API private key (hex-encoded P-256)
@@ -194,7 +360,8 @@ declare class PrivyAdapter implements WalletAdapter {
  *   TURNKEY_API_BASE_URL   — Override the Turnkey API base URL
  *   TURNKEY_PRIVATE_KEY_ID — Turnkey private key ID (for signing with a specific key)
  *
- * @see https://docs.turnkey.com/
+ * @see https://docs.turnkey.com/concepts/policies/overview
+ * @see https://docs.turnkey.com/concepts/users/best-practices
  */
 
 interface TurnkeyConfig {
@@ -219,6 +386,7 @@ declare class TurnkeyAdapter implements WalletAdapter {
     private stamp;
     private signedRequest;
     getAddress(): Promise<string>;
+    getWalletInfo(): Promise<WalletInfo>;
     sendTransaction(tx: TransactionRequest): Promise<TransactionResult>;
     signMessage(request: SignMessageRequest): Promise<string>;
     signTypedData(request: SignTypedDataRequest): Promise<string>;
@@ -238,4 +406,4 @@ declare function createWalletFromEnv(): WalletAdapter;
 declare function createWalletForProvider(provider: WalletProvider): WalletAdapter;
 declare function detectProvider(): WalletProvider | null;
 
-export { BankrAdapter, type BankrConfig, CHAIN_TO_FIREBLOCKS_ASSET, FireblocksAdapter, type FireblocksConfig, PrivateKeyAdapter, type PrivateKeyConfig, PrivyAdapter, type PrivyConfig, SignMessageRequest, SignTypedDataRequest, TransactionRequest, TransactionResult, TurnkeyAdapter, type TurnkeyConfig, WalletAdapter, WalletCapabilities, WalletProvider, createWalletForProvider, createWalletFromEnv, detectProvider };
+export { BankrAdapter, type BankrConfig, CHAIN_TO_FIREBLOCKS_ASSET, FireblocksAdapter, type FireblocksConfig, PrivateKeyAdapter, type PrivateKeyConfig, PrivyAdapter, type PrivyConfig, SignMessageRequest, SignTypedDataRequest, TransactionRequest, TransactionResult, TurnkeyAdapter, type TurnkeyConfig, WalletAdapter, WalletCapabilities, WalletInfo, WalletProvider, createWalletForProvider, createWalletFromEnv, detectProvider };