@agent-shield/custody-crossmint 0.1.1 → 0.1.2

package/README.md

@@ -0,0 +1,155 @@
+# @agent-shield/custody-crossmint
+
+Crossmint TEE custody adapter for AgentShield — hardware-enclave signing for AI agents. The private key never leaves the Trusted Execution Environment.
+
+`@agent-shield/custody-crossmint` wraps Crossmint's Intel TDX-backed wallets into a standard `WalletLike` interface that works with `shield()` and the rest of the AgentShield ecosystem. Your agent gets a signing interface; the private key stays in hardware.
+
+## Installation
+
+```bash
+npm install @agent-shield/custody-crossmint @solana/web3.js
+```
+
+Optional peer dependency: `@agent-shield/solana` (for `shield()` integration)
+
+## Quick Start
+
+```typescript
+import { shield } from "@agent-shield/solana";
+import { crossmint } from "@agent-shield/custody-crossmint";
+
+// Create a TEE-backed wallet and wrap it with spending controls
+const wallet = shield(
+  await crossmint({ apiKey: "sk_production_..." }),
+  { maxSpend: "500 USDC/day" }
+);
+
+// Use like any other wallet — signing happens in hardware
+await wallet.signTransaction(tx);
+```
+
+### Zero-Config from Environment
+
+```typescript
+import { shield } from "@agent-shield/solana";
+import { crossmintFromEnv } from "@agent-shield/custody-crossmint";
+
+// Reads CROSSMINT_API_KEY from environment
+const wallet = shield(await crossmintFromEnv(), { maxSpend: "500 USDC/day" });
+```
+
+## API Reference
+
+### `crossmint(config, client?): Promise<CrossmintWallet>`
+
+Create a `CrossmintWallet` from explicit configuration. If no `locator` is provided, a new wallet is created via the Crossmint API.
+
+```typescript
+const wallet = await crossmint({ apiKey: "sk_production_..." });
+console.log(wallet.publicKey.toBase58()); // Solana address
+```
+
+### `crossmintFromEnv(client?): Promise<CrossmintWallet>`
+
+Create a `CrossmintWallet` from environment variables. Throws if `CROSSMINT_API_KEY` is not set.
+
+### `CrossmintWallet`
+
+Implements `WalletLike` — compatible with `shield()`, Solana Agent Kit, and any code expecting a standard wallet interface.
+
+| Property/Method | Description |
+|-----------------|-------------|
+| `publicKey` | Solana `PublicKey` of the TEE-backed wallet |
+| `locator` | Crossmint wallet locator string |
+| `provider` | Always `"crossmint"` |
+| `signTransaction(tx)` | Sign via TEE — serializes tx, sends to Crossmint, returns signed tx |
+| `signAllTransactions(txs)` | Sign multiple transactions sequentially via TEE |
+| `CrossmintWallet.create(config, client?)` | Static factory method |
+
+### `CrossmintRESTClient`
+
+Default SDK client that calls Crossmint's REST API directly. Used automatically when no custom client is provided.
+
+| Method | Description |
+|--------|-------------|
+| `createWallet(params)` | Create a new wallet via Crossmint API |
+| `getWallet(locator)` | Get an existing wallet's address by locator |
+| `signTransaction(locator, transaction, encoding)` | Sign a serialized transaction |
+
+### Configuration Utilities
+
+| Export | Description |
+|--------|-------------|
+| `configFromEnv()` | Parse `CrossmintWalletConfig` from environment variables |
+| `validateConfig(config)` | Validate config, throw on missing/invalid fields |
+| `CROSSMINT_ENV_KEYS` | Environment variable key constants |
+
+## Configuration
+
+### `CrossmintWalletConfig`
+
+```typescript
+interface CrossmintWalletConfig {
+  apiKey: string;              // Required — Crossmint server-side API key
+  locator?: string;            // Existing wallet locator (creates new if omitted)
+  chain?: string;              // Default: "solana"
+  signerType?: "api-key" | "evm-keypair";  // Default: "api-key"
+  baseUrl?: string;            // Default: "https://www.crossmint.com"
+  linkedUser?: string;         // User identifier for wallet association
+}
+```
+
+### Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `CROSSMINT_API_KEY` | Yes | — | Server-side API key (needs `wallets.create` + `wallets:transactions.sign` scopes) |
+| `CROSSMINT_WALLET_LOCATOR` | No | — | Existing wallet locator (creates new wallet if omitted) |
+| `CROSSMINT_SIGNER_TYPE` | No | `api-key` | `"api-key"` (custodial) or `"evm-keypair"` |
+| `CROSSMINT_BASE_URL` | No | `https://www.crossmint.com` | API base URL override |
+| `CROSSMINT_LINKED_USER` | No | — | Linked user for wallet association |
+
+## Integration with shield()
+
+```typescript
+import { shield, ShieldDeniedError } from "@agent-shield/solana";
+import { crossmint } from "@agent-shield/custody-crossmint";
+
+const teeWallet = await crossmint({ apiKey: "sk_..." });
+const protectedWallet = shield(teeWallet, {
+  maxSpend: ["500 USDC/day", "10 SOL/day"],
+  blockUnknownPrograms: true,
+  rateLimit: { maxTransactions: 60, windowMs: 3_600_000 },
+});
+
+// Two layers of protection:
+// 1. Private key in TEE — agent code never sees it
+// 2. shield() enforces spending caps before signing
+try {
+  await protectedWallet.signTransaction(tx);
+} catch (error) {
+  if (error instanceof ShieldDeniedError) {
+    console.log("Policy blocked:", error.violations[0].suggestion);
+  }
+}
+```
+
+## Related Packages
+
+| Package | Description |
+|---------|-------------|
+| [`@agent-shield/solana`](https://www.npmjs.com/package/@agent-shield/solana) | Client-side wallet wrapper (`shield()`) |
+| [`@agent-shield/sdk`](https://www.npmjs.com/package/@agent-shield/sdk) | On-chain vault SDK (Level 3 enforcement) |
+| [`@agent-shield/core`](https://www.npmjs.com/package/@agent-shield/core) | Pure TypeScript policy engine |
+| [`@agent-shield/mcp`](https://www.npmjs.com/package/@agent-shield/mcp) | MCP server for AI tools |
+| [`@agent-shield/plugin-elizaos`](https://www.npmjs.com/package/@agent-shield/plugin-elizaos) | ElizaOS integration (supports Crossmint custody) |
+
+## Support
+
+- X/Twitter: [@MightieMags](https://x.com/MightieMags)
+- Telegram: [MightyMags](https://t.me/MightyMags)
+- Issues: [GitHub Issues](https://github.com/Kaleb-Rupe/agentshield/issues)
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,12 @@
 {
   "name": "@agent-shield/custody-crossmint",
-  "version": "0.1.1",
+  "version": "0.1.2",
+  "author": "Kaleb Rupe (https://x.com/MightieMags)",
+  "homepage": "https://github.com/Kaleb-Rupe/agentshield#readme",
+  "bugs": {
+    "url": "https://github.com/Kaleb-Rupe/agentshield/issues",
+    "email": "https://t.me/MightyMags"
+  },
   "description": "Crossmint TEE custody adapter for AgentShield — hardware-enclave signing for AI agents",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -12,6 +18,12 @@
   "engines": {
     "node": ">=18.0.0"
   },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run clean && npm run build",
+    "test": "TS_NODE_PROJECT=tsconfig.test.json mocha --require ts-node/register tests/**/*.test.ts --timeout 30000"
+  },
   "dependencies": {
     "@crossmint/wallets-sdk": "^0.2.0",
     "@solana/web3.js": "^1.95.0"
@@ -25,14 +37,14 @@
     }
   },
   "devDependencies": {
+    "@agent-shield/solana": "workspace:*",
     "@types/chai": "^4.3.11",
     "@types/mocha": "^10.0.6",
     "@types/node": "^20.11.0",
     "chai": "^4.4.1",
     "mocha": "^10.3.0",
     "ts-node": "^10.9.2",
-    "typescript": "^5.3.3",
-    "@agent-shield/solana": "0.3.0"
+    "typescript": "^5.3.3"
   },
   "keywords": [
     "solana",
@@ -48,10 +60,5 @@
     "type": "git",
     "url": "https://github.com/Kaleb-Rupe/agentshield",
     "directory": "sdk/custody/crossmint"
-  },
-  "scripts": {
-    "build": "tsc",
-    "clean": "rm -rf dist",
-    "test": "TS_NODE_PROJECT=tsconfig.test.json mocha --require ts-node/register tests/**/*.test.ts --timeout 30000"
   }
-}
+}