@phantom/api-key-stamper 0.0.2

package/README.md

@@ -0,0 +1,120 @@
+# @phantom/api-key-stamper
+
+API key stamper for authenticating requests to Phantom Wallet API.
+
+## Installation
+
+```bash
+npm install @phantom/api-key-stamper
+# or
+yarn add @phantom/api-key-stamper
+```
+
+## Usage
+
+The `ApiKeyStamper` is used to sign HTTP requests with Ed25519 signatures for authentication with Phantom's API.
+
+### Basic Usage
+
+```typescript
+import { ApiKeyStamper } from "@phantom/api-key-stamper";
+import { PhantomClient } from "@phantom/client";
+
+// Create a stamper with your secret key
+const stamper = new ApiKeyStamper({
+  apiSecretKey: "your-base58-encoded-secret-key",
+});
+
+// Use it with PhantomClient
+const client = new PhantomClient(
+  {
+    apiBaseUrl: "https://api.phantom.com",
+    organizationId: "your-org-id",
+  },
+  stamper,
+);
+
+// Now all requests will be automatically signed
+const wallet = await client.createWallet("My Wallet");
+```
+
+### With Server SDK
+
+The `@phantom/server-sdk` package uses this stamper internally:
+
+```typescript
+import { ServerSDK } from "@phantom/server-sdk";
+
+const sdk = new ServerSDK({
+  organizationId: "your-org-id",
+  apiBaseUrl: "https://api.phantom.com",
+  apiPrivateKey: "your-base58-encoded-secret-key",
+});
+
+// The SDK automatically creates and uses an ApiKeyStamper
+const wallet = await sdk.createWallet("My Wallet");
+```
+
+### How it Works
+
+1. The stamper takes your base58-encoded Ed25519 secret key
+2. For each request, it signs the request body with the secret key
+3. The stamp is added to the request headers as `X-Phantom-Stamp` containing:
+   - `publicKey`: Base64url-encoded public key
+   - `signature`: Base64url-encoded signature
+   - `kind`: Always "PKI" for this authentication method
+4. The entire stamp object is JSON-encoded and then base64url-encoded
+5. The server verifies the signature to authenticate the request
+
+#### Example Stamp Structure
+
+Before encoding, the stamp object looks like:
+
+```json
+{
+  "publicKey": "base64url-encoded-public-key",
+  "signature": "base64url-encoded-signature",
+  "kind": "PKI"
+}
+```
+
+This JSON is then base64url-encoded and sent as the `X-Phantom-Stamp` header.
+
+### Security Notes
+
+- Keep your secret key secure and never expose it in client-side code
+- Only use this stamper in server-side applications
+- The secret key should be stored securely (e.g., in environment variables)
+
+## Development
+
+### Running Tests
+
+```bash
+npm test
+```
+
+The test suite includes:
+
+- Constructor validation with valid/invalid keys
+- Header addition and preservation
+- Different data types (string, object, undefined)
+- Stamp structure validation
+- Cryptographic signature verification
+- Base64url encoding/decoding utilities
+- Edge cases and error handling
+
+## API Reference
+
+### ApiKeyStamper
+
+```typescript
+class ApiKeyStamper {
+  constructor(config: ApiKeyStamperConfig);
+  stamp(config: AxiosRequestConfig): Promise<AxiosRequestConfig>;
+}
+
+interface ApiKeyStamperConfig {
+  apiSecretKey: string; // Base58-encoded Ed25519 secret key
+}
+```

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+import { AxiosRequestConfig } from 'axios';
+
+interface ApiKeyStamperConfig {
+    apiSecretKey: string;
+}
+/**
+ * ApiKeyStamper that signs requests with Ed25519
+ */
+declare class ApiKeyStamper {
+    private keypair;
+    constructor(config: ApiKeyStamperConfig);
+    /**
+     * Stamp (sign) an axios request configuration
+     */
+    stamp(config: AxiosRequestConfig): Promise<AxiosRequestConfig>;
+}
+
+export { ApiKeyStamper, ApiKeyStamperConfig };

package/dist/index.js

@@ -0,0 +1,67 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  ApiKeyStamper: () => ApiKeyStamper
+});
+module.exports = __toCommonJS(src_exports);
+var import_buffer = require("buffer");
+var import_base64url = require("@phantom/base64url");
+var import_crypto = require("@phantom/crypto");
+var import_bs58 = __toESM(require("bs58"));
+var ApiKeyStamper = class {
+  constructor(config) {
+    this.keypair = (0, import_crypto.createKeyPairFromSecret)(config.apiSecretKey);
+  }
+  /**
+   * Stamp (sign) an axios request configuration
+   */
+  async stamp(config) {
+    const requestBody = typeof config.data === "string" ? config.data : config.data === void 0 ? "" : JSON.stringify(config.data);
+    const dataUtf8 = import_buffer.Buffer.from(requestBody, "utf8");
+    const signature = (0, import_crypto.signWithSecret)(this.keypair.secretKey, dataUtf8);
+    const stampData = {
+      // The keypair is bs58 encoded, need to decode and then base64url encode the public key
+      publicKey: (0, import_base64url.base64urlEncode)(import_bs58.default.decode(this.keypair.publicKey)),
+      signature: (0, import_base64url.base64urlEncode)(signature),
+      kind: "PKI"
+    };
+    const stampJson = JSON.stringify(stampData);
+    const stamp = (0, import_base64url.stringToBase64url)(stampJson);
+    config.headers = config.headers || {};
+    config.headers["X-Phantom-Stamp"] = stamp;
+    return Promise.resolve(config);
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ApiKeyStamper
+});

package/dist/index.mjs

@@ -0,0 +1,32 @@
+// src/index.ts
+import { Buffer } from "buffer";
+import { base64urlEncode, stringToBase64url } from "@phantom/base64url";
+import { createKeyPairFromSecret, signWithSecret } from "@phantom/crypto";
+import bs58 from "bs58";
+var ApiKeyStamper = class {
+  constructor(config) {
+    this.keypair = createKeyPairFromSecret(config.apiSecretKey);
+  }
+  /**
+   * Stamp (sign) an axios request configuration
+   */
+  async stamp(config) {
+    const requestBody = typeof config.data === "string" ? config.data : config.data === void 0 ? "" : JSON.stringify(config.data);
+    const dataUtf8 = Buffer.from(requestBody, "utf8");
+    const signature = signWithSecret(this.keypair.secretKey, dataUtf8);
+    const stampData = {
+      // The keypair is bs58 encoded, need to decode and then base64url encode the public key
+      publicKey: base64urlEncode(bs58.decode(this.keypair.publicKey)),
+      signature: base64urlEncode(signature),
+      kind: "PKI"
+    };
+    const stampJson = JSON.stringify(stampData);
+    const stamp = stringToBase64url(stampJson);
+    config.headers = config.headers || {};
+    config.headers["X-Phantom-Stamp"] = stamp;
+    return Promise.resolve(config);
+  }
+};
+export {
+  ApiKeyStamper
+};

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@phantom/api-key-stamper",
+  "version": "0.0.2",
+  "description": "API key stamper for Phantom Wallet SDK",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "rimraf ./dist && tsup src/index.ts --format cjs,esm --dts --external buffer,@phantom/base64url,@phantom/crypto",
+    "dev": "tsc --watch",
+    "clean": "rm -rf dist",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "lint": "tsc --noEmit && eslint --cache . --ext .ts,.tsx",
+    "prettier": "prettier --write \"src/**/*.{ts,tsx}\""
+  },
+  "devDependencies": {
+    "@types/bs58": "^4.0.1",
+    "@types/jest": "^29.5.12",
+    "@types/node": "^20.11.0",
+    "eslint": "8.53.0",
+    "jest": "^29.7.0",
+    "prettier": "^3.5.2",
+    "rimraf": "^6.0.1",
+    "ts-jest": "^29.1.2",
+    "tsup": "^6.7.0",
+    "typescript": "^5.0.4"
+  },
+  "dependencies": {
+    "@phantom/base64url": "workspace:^",
+    "@phantom/crypto": "workspace:^",
+    "axios": "^1.10.0",
+    "bs58": "^6.0.0",
+    "buffer": "^6.0.3"
+  },
+  "files": [
+    "dist"
+  ]
+}