shadowkey-agent-sdk 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 ShadowKey Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,178 @@
+# ShadowKey Agent SDK
+
+Official SDK for integrating AI agents with ShadowKey's privacy-preserving data vault.
+
+## Features
+
+- 🔐 Secure API key authentication with request signing
+- 🔄 Automatic retry logic with exponential backoff
+- ⏱️ Configurable timeouts and polling
+- 🎯 TypeScript-first with full type definitions
+- 🪶 Zero dependencies for minimal bundle size
+- 🔍 Debug mode for development
+
+## Installation
+
+```bash
+npm install @shadowkey/agent-sdk
+```
+
+## Quick Start
+
+```typescript
+import { ShadowKeyClient } from '@shadowkey/agent-sdk';
+
+const client = new ShadowKeyClient({
+  apiUrl: 'https://your-project.supabase.co/functions/v1',
+  apiKey: 'your-api-key',
+  debug: true // Enable logging during development
+});
+
+// Request access to user data
+const response = await client.requestAccess({
+  agentId: 'shopping-assistant-001',
+  agentName: 'Smart Shopping Assistant',
+  requestedFields: ['creditCard', 'shippingAddress'],
+  purpose: 'Complete your purchase of wireless headphones',
+  category: 'shopping'
+});
+
+console.log('Request ID:', response.requestId);
+
+// Wait for user approval (with timeout)
+const result = await client.waitForApproval(response.requestId, 300000);
+
+if (result.status === 'approved') {
+  console.log('Access granted!', result.grantedData);
+} else {
+  console.log('Access denied:', result.message);
+}
+```
+
+## API Reference
+
+### Constructor
+
+```typescript
+new ShadowKeyClient(config: ShadowKeyConfig)
+```
+
+**Config Options:**
+- `apiUrl` (required): Your Supabase project URL + `/functions/v1`
+- `apiKey` (required): API key generated from ShadowKey settings
+- `timeout` (optional): Request timeout in ms (default: 30000)
+- `retryAttempts` (optional): Number of retry attempts (default: 3)
+- `debug` (optional): Enable debug logging (default: false)
+
+### Methods
+
+#### `requestAccess(request: AccessRequest): Promise<AccessResponse>`
+
+Request access to user's vault data.
+
+**Parameters:**
+```typescript
+{
+  agentId: string;          // Unique identifier for your agent
+  agentName: string;        // Human-readable agent name
+  requestedFields: string[]; // Array of field names to request
+  purpose: string;          // Clear explanation of why you need access
+  category?: string;        // Optional category (shopping, travel, etc)
+  expiresIn?: number;       // Optional expiration time in seconds
+}
+```
+
+**Returns:**
+```typescript
+{
+  requestId: string;        // Use this to check status
+  status: 'pending' | 'approved' | 'denied' | 'expired';
+  grantedData?: Record<string, any>; // Present if approved
+  expiresAt?: string;       // ISO timestamp
+  message?: string;
+}
+```
+
+#### `checkStatus(requestId: string): Promise<DisclosureStatus>`
+
+Check the current status of an access request.
+
+#### `waitForApproval(requestId: string, maxWaitMs?: number, pollIntervalMs?: number): Promise<AccessResponse>`
+
+Poll for approval with automatic retries.
+
+**Parameters:**
+- `requestId`: The ID returned from `requestAccess()`
+- `maxWaitMs`: Maximum time to wait (default: 300000 = 5 minutes)
+- `pollIntervalMs`: Time between polls (default: 2000 = 2 seconds)
+
+#### `submitReverseDisclosure(request: ReverseDisclosureRequest): Promise<ReverseDisclosureResponse>`
+
+Submit data to user's vault (reverse data flow).
+
+**Parameters:**
+```typescript
+{
+  serviceId: string;
+  serviceName: string;
+  dataOffered: Array<{
+    field: string;
+    value: string;
+    category: string;
+  }>;
+  purpose: string;
+}
+```
+
+## Examples
+
+See the `/examples` directory for complete integration examples:
+
+- `openrouter/` - AI agent using OpenRouter free models
+- `node-express/` - Express.js server with webhook handling
+- `langchain/` - LangChain tool integration
+- `python/` - Python SDK wrapper
+
+## Error Handling
+
+```typescript
+try {
+  const response = await client.requestAccess({...});
+} catch (error) {
+  if (error.message.includes('timeout')) {
+    console.error('Request timed out');
+  } else if (error.message.includes('401')) {
+    console.error('Invalid API key');
+  } else {
+    console.error('Request failed:', error.message);
+  }
+}
+```
+
+## Security Best Practices
+
+1. **Never expose your API key** in client-side code
+2. **Use environment variables** to store credentials
+3. **Rotate keys regularly** using the ShadowKey dashboard
+4. **Set appropriate rate limits** for your use case
+5. **Validate all data** received from the vault
+6. **Use HTTPS** for all requests (enforced by default)
+
+## Rate Limits
+
+Default rate limits per API key:
+- 100 requests per minute
+- 1000 requests per hour
+- 10000 requests per day
+
+Contact support for enterprise limits.
+
+## Support
+
+- Documentation: https://shadowkey.dev/docs
+- Issues: https://github.com/shadowkey/agent-sdk/issues
+- Discord: https://discord.gg/shadowkey
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,72 @@
+interface ShadowKeyConfig {
+    apiUrl: string;
+    apiKey: string;
+    timeout?: number;
+    retryAttempts?: number;
+    debug?: boolean;
+}
+interface AccessRequest {
+    agentId: string;
+    agentName: string;
+    requestedFields: string[];
+    purpose: string;
+    category?: string;
+    expiresIn?: number;
+}
+interface AccessResponse {
+    requestId: string;
+    status: 'pending' | 'approved' | 'denied' | 'expired';
+    grantedFields?: string[];
+    grantedData?: Record<string, any>;
+    expiresAt?: string;
+    message?: string;
+}
+interface ReverseDisclosureRequest {
+    serviceId: string;
+    serviceName: string;
+    dataOffered: Array<{
+        field: string;
+        value: string;
+        category: string;
+    }>;
+    purpose: string;
+}
+interface ReverseDisclosureResponse {
+    receiptId: string;
+    status: 'accepted' | 'rejected';
+    storedFields?: string[];
+    message?: string;
+}
+interface DisclosureStatus {
+    requestId: string;
+    status: 'pending' | 'approved' | 'denied' | 'expired';
+    approvedAt?: string;
+    deniedAt?: string;
+    expiresAt?: string;
+    grantedFields?: string[];
+    grantedData?: Record<string, any>;
+}
+interface APIError {
+    code: string;
+    message: string;
+    details?: any;
+}
+interface RequestMetadata {
+    timestamp: number;
+    signature: string;
+    nonce: string;
+}
+
+declare class ShadowKeyClient {
+    private config;
+    constructor(config: ShadowKeyConfig);
+    private log;
+    private generateSignature;
+    private makeRequest;
+    requestAccess(request: AccessRequest): Promise<AccessResponse>;
+    checkStatus(requestId: string): Promise<DisclosureStatus>;
+    submitReverseDisclosure(request: ReverseDisclosureRequest): Promise<ReverseDisclosureResponse>;
+    waitForApproval(requestId: string, maxWaitMs?: number, pollIntervalMs?: number): Promise<AccessResponse>;
+}
+
+export { type APIError, type AccessRequest, type AccessResponse, type DisclosureStatus, type RequestMetadata, type ReverseDisclosureRequest, type ReverseDisclosureResponse, ShadowKeyClient, type ShadowKeyConfig };

package/dist/index.d.ts

@@ -0,0 +1,72 @@
+interface ShadowKeyConfig {
+    apiUrl: string;
+    apiKey: string;
+    timeout?: number;
+    retryAttempts?: number;
+    debug?: boolean;
+}
+interface AccessRequest {
+    agentId: string;
+    agentName: string;
+    requestedFields: string[];
+    purpose: string;
+    category?: string;
+    expiresIn?: number;
+}
+interface AccessResponse {
+    requestId: string;
+    status: 'pending' | 'approved' | 'denied' | 'expired';
+    grantedFields?: string[];
+    grantedData?: Record<string, any>;
+    expiresAt?: string;
+    message?: string;
+}
+interface ReverseDisclosureRequest {
+    serviceId: string;
+    serviceName: string;
+    dataOffered: Array<{
+        field: string;
+        value: string;
+        category: string;
+    }>;
+    purpose: string;
+}
+interface ReverseDisclosureResponse {
+    receiptId: string;
+    status: 'accepted' | 'rejected';
+    storedFields?: string[];
+    message?: string;
+}
+interface DisclosureStatus {
+    requestId: string;
+    status: 'pending' | 'approved' | 'denied' | 'expired';
+    approvedAt?: string;
+    deniedAt?: string;
+    expiresAt?: string;
+    grantedFields?: string[];
+    grantedData?: Record<string, any>;
+}
+interface APIError {
+    code: string;
+    message: string;
+    details?: any;
+}
+interface RequestMetadata {
+    timestamp: number;
+    signature: string;
+    nonce: string;
+}
+
+declare class ShadowKeyClient {
+    private config;
+    constructor(config: ShadowKeyConfig);
+    private log;
+    private generateSignature;
+    private makeRequest;
+    requestAccess(request: AccessRequest): Promise<AccessResponse>;
+    checkStatus(requestId: string): Promise<DisclosureStatus>;
+    submitReverseDisclosure(request: ReverseDisclosureRequest): Promise<ReverseDisclosureResponse>;
+    waitForApproval(requestId: string, maxWaitMs?: number, pollIntervalMs?: number): Promise<AccessResponse>;
+}
+
+export { type APIError, type AccessRequest, type AccessResponse, type DisclosureStatus, type RequestMetadata, type ReverseDisclosureRequest, type ReverseDisclosureResponse, ShadowKeyClient, type ShadowKeyConfig };

package/dist/index.js

@@ -0,0 +1,165 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+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 __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  ShadowKeyClient: () => ShadowKeyClient
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/client.ts
+var ShadowKeyClient = class {
+  constructor(config) {
+    this.config = {
+      timeout: 3e4,
+      retryAttempts: 3,
+      debug: false,
+      ...config
+    };
+    if (!this.config.apiUrl) {
+      throw new Error("apiUrl is required");
+    }
+    if (!this.config.apiKey) {
+      throw new Error("apiKey is required");
+    }
+  }
+  log(message, data) {
+    if (this.config.debug) {
+      if (data && typeof data === "object") {
+        const sanitized = { ...data };
+        const sensitiveFields = ["grantedData", "grantedFields", "response_data", "decrypted_data"];
+        sensitiveFields.forEach((field) => {
+          if (sanitized[field]) {
+            sanitized[field] = "[REDACTED]";
+          }
+        });
+        console.log("[ShadowKey SDK]", message, sanitized);
+      } else {
+        console.log("[ShadowKey SDK]", message, data);
+      }
+    }
+  }
+  async generateSignature(payload) {
+    const timestamp = Date.now();
+    const nonceBytes = new Uint8Array(12);
+    crypto.getRandomValues(nonceBytes);
+    const nonce = Array.from(nonceBytes).map((b) => b.toString(16).padStart(2, "0")).join("");
+    const message = JSON.stringify({ ...payload, timestamp, nonce });
+    const encoder = new TextEncoder();
+    const data = encoder.encode(message + this.config.apiKey);
+    const hashBuffer = await crypto.subtle.digest("SHA-256", data);
+    const hashArray = Array.from(new Uint8Array(hashBuffer));
+    const signature = hashArray.map((b) => b.toString(16).padStart(2, "0")).join("");
+    return { timestamp, nonce, signature };
+  }
+  async makeRequest(endpoint, method, body, attempt = 1) {
+    const metadata = await this.generateSignature(body || {});
+    const url = `${this.config.apiUrl}${endpoint}`;
+    this.log(`${method} ${url}`, body);
+    try {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
+      const response = await fetch(url, {
+        method,
+        headers: {
+          "Content-Type": "application/json",
+          "Authorization": `Bearer ${this.config.apiKey}`,
+          "X-Timestamp": metadata.timestamp.toString(),
+          "X-Nonce": metadata.nonce,
+          "X-Signature": metadata.signature
+        },
+        body: body ? JSON.stringify(body) : void 0,
+        signal: controller.signal
+      });
+      clearTimeout(timeoutId);
+      if (!response.ok) {
+        const error = await response.json().catch(() => ({
+          code: "UNKNOWN_ERROR",
+          message: `HTTP ${response.status}: ${response.statusText}`
+        }));
+        const isClientError = response.status >= 400 && response.status < 500;
+        if (isClientError) {
+          const err = new Error(error.message || "Request failed");
+          err.isClientError = true;
+          throw err;
+        }
+        throw new Error(error.message || "Request failed");
+      }
+      const data = await response.json();
+      this.log("Response:", data);
+      return data;
+    } catch (error) {
+      this.log("Request failed:", error.message);
+      const shouldRetry = attempt < this.config.retryAttempts && error.name !== "AbortError" && !error.isClientError;
+      if (shouldRetry) {
+        const delay = Math.pow(2, attempt) * 1e3;
+        this.log(`Retrying in ${delay}ms...`, { attempt: attempt + 1, max: this.config.retryAttempts });
+        await new Promise((resolve) => setTimeout(resolve, delay));
+        return this.makeRequest(endpoint, method, body, attempt + 1);
+      }
+      throw error;
+    }
+  }
+  async requestAccess(request) {
+    return this.makeRequest("/access-request", "POST", request);
+  }
+  async checkStatus(requestId) {
+    return this.makeRequest(`/access-status/${requestId}`, "GET");
+  }
+  async submitReverseDisclosure(request) {
+    return this.makeRequest("/reverse-disclosure", "POST", request);
+  }
+  async waitForApproval(requestId, maxWaitMs = 3e5, pollIntervalMs = 2e3) {
+    const startTime = Date.now();
+    while (Date.now() - startTime < maxWaitMs) {
+      const status = await this.checkStatus(requestId);
+      if (status.status === "approved") {
+        return {
+          requestId,
+          status: "approved",
+          grantedFields: status.grantedFields || [],
+          grantedData: status.grantedData || {},
+          expiresAt: status.expiresAt,
+          message: "Access granted"
+        };
+      }
+      if (status.status === "denied") {
+        return {
+          requestId,
+          status: "denied",
+          message: "Access denied by user"
+        };
+      }
+      if (status.status === "expired") {
+        return {
+          requestId,
+          status: "expired",
+          message: "Request expired"
+        };
+      }
+      await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+    }
+    throw new Error("Timeout waiting for approval");
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ShadowKeyClient
+});

package/dist/index.mjs

@@ -0,0 +1,138 @@
+// src/client.ts
+var ShadowKeyClient = class {
+  constructor(config) {
+    this.config = {
+      timeout: 3e4,
+      retryAttempts: 3,
+      debug: false,
+      ...config
+    };
+    if (!this.config.apiUrl) {
+      throw new Error("apiUrl is required");
+    }
+    if (!this.config.apiKey) {
+      throw new Error("apiKey is required");
+    }
+  }
+  log(message, data) {
+    if (this.config.debug) {
+      if (data && typeof data === "object") {
+        const sanitized = { ...data };
+        const sensitiveFields = ["grantedData", "grantedFields", "response_data", "decrypted_data"];
+        sensitiveFields.forEach((field) => {
+          if (sanitized[field]) {
+            sanitized[field] = "[REDACTED]";
+          }
+        });
+        console.log("[ShadowKey SDK]", message, sanitized);
+      } else {
+        console.log("[ShadowKey SDK]", message, data);
+      }
+    }
+  }
+  async generateSignature(payload) {
+    const timestamp = Date.now();
+    const nonceBytes = new Uint8Array(12);
+    crypto.getRandomValues(nonceBytes);
+    const nonce = Array.from(nonceBytes).map((b) => b.toString(16).padStart(2, "0")).join("");
+    const message = JSON.stringify({ ...payload, timestamp, nonce });
+    const encoder = new TextEncoder();
+    const data = encoder.encode(message + this.config.apiKey);
+    const hashBuffer = await crypto.subtle.digest("SHA-256", data);
+    const hashArray = Array.from(new Uint8Array(hashBuffer));
+    const signature = hashArray.map((b) => b.toString(16).padStart(2, "0")).join("");
+    return { timestamp, nonce, signature };
+  }
+  async makeRequest(endpoint, method, body, attempt = 1) {
+    const metadata = await this.generateSignature(body || {});
+    const url = `${this.config.apiUrl}${endpoint}`;
+    this.log(`${method} ${url}`, body);
+    try {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
+      const response = await fetch(url, {
+        method,
+        headers: {
+          "Content-Type": "application/json",
+          "Authorization": `Bearer ${this.config.apiKey}`,
+          "X-Timestamp": metadata.timestamp.toString(),
+          "X-Nonce": metadata.nonce,
+          "X-Signature": metadata.signature
+        },
+        body: body ? JSON.stringify(body) : void 0,
+        signal: controller.signal
+      });
+      clearTimeout(timeoutId);
+      if (!response.ok) {
+        const error = await response.json().catch(() => ({
+          code: "UNKNOWN_ERROR",
+          message: `HTTP ${response.status}: ${response.statusText}`
+        }));
+        const isClientError = response.status >= 400 && response.status < 500;
+        if (isClientError) {
+          const err = new Error(error.message || "Request failed");
+          err.isClientError = true;
+          throw err;
+        }
+        throw new Error(error.message || "Request failed");
+      }
+      const data = await response.json();
+      this.log("Response:", data);
+      return data;
+    } catch (error) {
+      this.log("Request failed:", error.message);
+      const shouldRetry = attempt < this.config.retryAttempts && error.name !== "AbortError" && !error.isClientError;
+      if (shouldRetry) {
+        const delay = Math.pow(2, attempt) * 1e3;
+        this.log(`Retrying in ${delay}ms...`, { attempt: attempt + 1, max: this.config.retryAttempts });
+        await new Promise((resolve) => setTimeout(resolve, delay));
+        return this.makeRequest(endpoint, method, body, attempt + 1);
+      }
+      throw error;
+    }
+  }
+  async requestAccess(request) {
+    return this.makeRequest("/access-request", "POST", request);
+  }
+  async checkStatus(requestId) {
+    return this.makeRequest(`/access-status/${requestId}`, "GET");
+  }
+  async submitReverseDisclosure(request) {
+    return this.makeRequest("/reverse-disclosure", "POST", request);
+  }
+  async waitForApproval(requestId, maxWaitMs = 3e5, pollIntervalMs = 2e3) {
+    const startTime = Date.now();
+    while (Date.now() - startTime < maxWaitMs) {
+      const status = await this.checkStatus(requestId);
+      if (status.status === "approved") {
+        return {
+          requestId,
+          status: "approved",
+          grantedFields: status.grantedFields || [],
+          grantedData: status.grantedData || {},
+          expiresAt: status.expiresAt,
+          message: "Access granted"
+        };
+      }
+      if (status.status === "denied") {
+        return {
+          requestId,
+          status: "denied",
+          message: "Access denied by user"
+        };
+      }
+      if (status.status === "expired") {
+        return {
+          requestId,
+          status: "expired",
+          message: "Request expired"
+        };
+      }
+      await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+    }
+    throw new Error("Timeout waiting for approval");
+  }
+};
+export {
+  ShadowKeyClient
+};

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "shadowkey-agent-sdk",
+  "version": "1.0.0",
+  "description": "Official SDK for integrating AI agents with ShadowKey privacy vault",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "test": "vitest",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "shadowkey",
+    "privacy",
+    "ai-agent",
+    "data-vault",
+    "zero-knowledge"
+  ],
+  "author": "ShadowKey Team",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/kimboltpro3-create/shadowkey"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.5.3",
+    "vitest": "^1.0.0"
+  }
+}