@armoriq/sdk-dev 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ArmorIQ 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,204 @@
+# ArmorIQ SDK (TypeScript)
+
+**Build secure AI agents with cryptographic intent verification.**
+
+The ArmorIQ SDK enables developers to build AI agents with built-in security and auditability. Just one API key - no cloud complexity.
+
+---
+
+## Why ArmorIQ?
+
+- **Simple** - Just one API key, no cloud credentials
+- **Secure** - Cryptographic verification for every action
+- **Auditable** - Complete execution trail
+- **Fast** - Get started in 5 minutes
+
+---
+
+## Installation
+
+```bash
+npm install @armoriq/sdk
+# or
+yarn add @armoriq/sdk
+```
+
+---
+
+## Quick Start
+
+### 1. Get Your API Key
+
+Visit [platform.armoriq.ai](https://platform.armoriq.ai) to generate your API key.
+
+### 2. Initialize the Client
+
+```typescript
+import { ArmorIQClient } from '@armoriq/sdk';
+
+const client = new ArmorIQClient({
+  apiKey: 'ak_your_key_here',
+  userId: 'your-user-id',
+  agentId: 'your-agent-id',
+});
+```
+
+### 3. Capture Your Plan
+
+```typescript
+const plan = {
+  goal: 'Get weather forecast',
+  steps: [
+    {
+      action: 'get_weather',
+      tool: 'weather_api',
+      mcp: 'weather-mcp',
+      inputs: { city: 'Boston' },
+    },
+  ],
+};
+
+const planCapture = client.capturePlan('gpt-4', "What's the weather in Boston?", plan);
+```
+
+### 4. Get Intent Token
+
+```typescript
+const token = await client.getIntentToken(planCapture);
+```
+
+### 5. Invoke Actions
+
+```typescript
+const result = await client.invoke('weather-mcp', 'get_weather', token, {
+  city: 'Boston',
+});
+
+console.log(result);
+```
+
+---
+
+## Environment Variables
+
+```bash
+# Required
+ARMORIQ_API_KEY=ak_your_key_here
+USER_ID=your-user-id
+AGENT_ID=your-agent-id
+
+# Optional
+ARMORIQ_ENV=production  # or 'development' for local
+CONTEXT_ID=default
+IAP_ENDPOINT=https://customer-iap.armoriq.ai
+PROXY_ENDPOINT=https://customer-proxy.armoriq.ai
+BACKEND_ENDPOINT=https://customer-api.armoriq.ai
+```
+
+---
+
+## Advanced Usage
+
+### Delegation
+
+```typescript
+import * as crypto from 'crypto';
+
+// Generate delegate keypair
+const { publicKey, privateKey } = crypto.generateKeyPairSync('ed25519');
+const pubKeyHex = publicKey.export({ type: 'spki', format: 'der' }).toString('hex');
+
+const delegation = await client.delegate(token, pubKeyHex, 1800);
+console.log(`Delegated token: ${delegation.delegatedToken.tokenId}`);
+```
+
+### Custom Proxy Endpoints
+
+```typescript
+const client = new ArmorIQClient({
+  apiKey: 'ak_your_key_here',
+  userId: 'user-123',
+  agentId: 'agent-456',
+  proxyEndpoints: {
+    'weather-mcp': 'https://weather-proxy.example.com',
+    'finance-mcp': 'https://finance-proxy.example.com',
+  },
+});
+```
+
+### Error Handling
+
+```typescript
+import {
+  InvalidTokenException,
+  IntentMismatchException,
+  MCPInvocationException,
+  TokenExpiredException,
+} from '@armoriq/sdk';
+
+try {
+  const result = await client.invoke('weather-mcp', 'get_weather', token, { city: 'Boston' });
+} catch (error) {
+  if (error instanceof TokenExpiredException) {
+    console.error('Token expired, please get a new one');
+  } else if (error instanceof IntentMismatchException) {
+    console.error('Action not in original plan');
+  } else if (error instanceof MCPInvocationException) {
+    console.error('MCP invocation failed:', error.message);
+  }
+}
+```
+
+---
+
+## API Reference
+
+### `ArmorIQClient`
+
+#### Constructor Options
+
+```typescript
+interface SDKConfig {
+  apiKey: string; // Required: Your API key
+  userId: string; // Required: User identifier
+  agentId: string; // Required: Agent identifier
+  contextId?: string; // Optional: Context identifier (default: 'default')
+  useProduction?: boolean; // Optional: Use production endpoints (default: true)
+  iapEndpoint?: string; // Optional: Override IAP endpoint
+  proxyEndpoint?: string; // Optional: Override proxy endpoint
+  backendEndpoint?: string; // Optional: Override backend endpoint
+  proxyEndpoints?: Record<string, string>; // Optional: MCP-specific proxies
+  timeout?: number; // Optional: Request timeout in ms (default: 30000)
+  maxRetries?: number; // Optional: Max retry attempts (default: 3)
+  verifySsl?: boolean; // Optional: Verify SSL (default: true)
+}
+```
+
+#### Methods
+
+- `capturePlan(llm, prompt, plan, metadata?)` - Capture an execution plan
+- `getIntentToken(planCapture, policy?, validitySeconds?)` - Get a signed intent token
+- `invoke(mcp, action, intentToken, params?, merkleProof?, userEmail?)` - Invoke an MCP action
+- `delegate(intentToken, delegatePublicKey, validitySeconds?, allowedActions?, targetAgent?, subtask?)` - Delegate to another agent
+- `verifyToken(intentToken)` - Verify a token locally
+- `close()` - Cleanup resources
+
+---
+
+## Documentation
+
+For complete documentation, visit [docs.armoriq.ai](https://docs.armoriq.ai)
+
+---
+
+## Links
+
+- [armoriq.ai](https://armoriq.ai)
+- [docs.armoriq.ai](https://docs.armoriq.ai)
+- [platform.armoriq.ai](https://platform.armoriq.ai)
+
+---
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.

package/dist/client.d.ts

@@ -0,0 +1,135 @@
+/**
+ * ArmorIQ SDK Client - Main entry point for SDK usage.
+ */
+import { IntentToken, PlanCapture, MCPInvocationResult, DelegationResult, SDKConfig, MCPSemanticMetadata, InvokeOptions, DelegationRequestParams, DelegationRequestResult, ApprovedDelegation } from './models';
+/**
+ * Main client for ArmorIQ SDK.
+ *
+ * Provides high-level APIs for:
+ * - Plan capture and canonicalization
+ * - Intent token management
+ * - MCP action invocation
+ * - Agent delegation
+ */
+export declare class ArmorIQClient {
+    private static readonly DEFAULT_IAP_ENDPOINT;
+    private static readonly DEFAULT_PROXY_ENDPOINT;
+    private static readonly DEFAULT_BACKEND_ENDPOINT;
+    private static readonly ARMORCLAW_IAP_ENDPOINT;
+    private static readonly ARMORCLAW_PROXY_ENDPOINT;
+    private static readonly ARMORCLAW_BACKEND_ENDPOINT;
+    private static readonly LOCAL_IAP_ENDPOINT;
+    private static readonly LOCAL_PROXY_ENDPOINT;
+    private static readonly LOCAL_BACKEND_ENDPOINT;
+    private static readonly LOCAL_ARMORCLAW_IAP_ENDPOINT;
+    private static readonly LOCAL_ARMORCLAW_PROXY_ENDPOINT;
+    private static readonly LOCAL_ARMORCLAW_BACKEND_ENDPOINT;
+    private iapEndpoint;
+    private defaultProxyEndpoint;
+    private backendEndpoint;
+    private proxyEndpoints;
+    private userId;
+    private agentId;
+    private contextId;
+    private apiKey;
+    private timeout;
+    private maxRetries;
+    private verifySsl;
+    private httpClient;
+    private tokenCache;
+    private metadataCache;
+    constructor(options?: Partial<SDKConfig> & {
+        apiKey?: string;
+        useProduction?: boolean;
+    });
+    /**
+     * Get the default proxy endpoint URL.
+     */
+    get proxyEndpoint(): string;
+    /**
+     * Validate API key with the proxy server.
+     */
+    private validateApiKey;
+    /**
+     * Capture an execution plan structure.
+     */
+    capturePlan(llm: string, prompt: string, plan?: Record<string, any>, metadata?: Record<string, any>): PlanCapture;
+    /**
+     * Request a signed intent token from IAP for the given plan.
+     */
+    getIntentToken(planCapture: PlanCapture, policy?: Record<string, any>, validitySeconds?: number): Promise<IntentToken>;
+    /**
+     * Invoke an MCP action through the ArmorIQ proxy with token verification.
+     */
+    invoke(mcp: string, action: string, intentToken: IntentToken, params?: Record<string, any>, merkleProof?: Array<Record<string, any>>, userEmail?: string): Promise<MCPInvocationResult>;
+    /**
+     * Delegate authority to another agent using CSRG token delegation.
+     */
+    delegate(intentToken: IntentToken, delegatePublicKey: string, validitySeconds?: number, allowedActions?: string[], targetAgent?: string, subtask?: Record<string, any>): Promise<DelegationResult>;
+    /**
+     * Verify an intent token with IAP.
+     */
+    verifyToken(intentToken: IntentToken): Promise<boolean>;
+    /**
+     * Fetch and cache semantic tool metadata for an MCP server.
+     */
+    fetchToolMetadata(mcpName: string): Promise<MCPSemanticMetadata>;
+    /**
+     * Eagerly load metadata for an MCP so subsequent invoke() calls are fast.
+     */
+    loadMcp(mcpName: string): Promise<void>;
+    /**
+     * List all MCPs registered for this org (resolved via API key).
+     */
+    listMcps(): Promise<Array<{
+        mcpId: string;
+        name: string;
+        url: string;
+    }>>;
+    /**
+     * Get full OpenAI-compatible tool schemas for a named MCP.
+     */
+    getMcpToolSchemas(mcpName: string): Promise<any[]>;
+    /**
+     * Enrich policy context from semantic metadata for a tool invocation.
+     */
+    private enrichPolicyContext;
+    /**
+     * Resolve an org role to a domain-specific role for an MCP.
+     */
+    resolveRole(mcpName: string, orgRole: string): Promise<string>;
+    /**
+     * Resolve the user's role and limit from the backend for delegation.
+     */
+    private resolveUserRole;
+    /**
+     * Create a delegation request on the backend.
+     */
+    createDelegationRequest(params: DelegationRequestParams): Promise<DelegationRequestResult>;
+    /**
+     * Check if a delegation request has been approved.
+     */
+    checkApprovedDelegation(userEmail: string, tool: string, amount: number): Promise<ApprovedDelegation | null>;
+    /**
+     * Mark a delegation as executed.
+     */
+    markDelegationExecuted(userEmail: string, delegationId: string): Promise<void>;
+    /**
+     * Mark an intent plan as completed after all tools have been executed.
+     */
+    completePlan(planId: string): Promise<void>;
+    /**
+     * Update an intent plan's status.
+     * Valid statuses: 'active', 'completed', 'failed', 'expired'
+     */
+    updatePlanStatus(planId: string, status: string): Promise<void>;
+    /**
+     * Enhanced invoke with automatic policy context enrichment and delegation handling.
+     */
+    invokeWithPolicy(mcp: string, action: string, intentToken: IntentToken, params?: Record<string, any>, options?: InvokeOptions): Promise<MCPInvocationResult>;
+    /**
+     * Close HTTP client and cleanup resources.
+     */
+    close(): void;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,EACL,WAAW,EACX,WAAW,EACX,mBAAmB,EACnB,gBAAgB,EAChB,SAAS,EACT,mBAAmB,EAEnB,aAAa,EACb,uBAAuB,EACvB,uBAAuB,EACvB,kBAAkB,EAEnB,MAAM,UAAU,CAAC;AAYlB;;;;;;;;GAQG;AACH,qBAAa,aAAa;IAExB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,oBAAoB,CAA4B;IACxE,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,sBAAsB,CAAwC;IACtF,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,wBAAwB,CAAoC;IAGpF,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,sBAAsB,CAA8B;IAC5E,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,wBAAwB,CAAgC;IAChF,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,0BAA0B,CAA8B;IAGhF,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,kBAAkB,CAA2B;IACrE,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,oBAAoB,CAA2B;IACvE,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,sBAAsB,CAA2B;IAGzE,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,4BAA4B,CAA2B;IAC/E,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,8BAA8B,CAA2B;IACjF,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,gCAAgC,CAA2B;IAEnF,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,oBAAoB,CAAS;IACrC,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,cAAc,CAAyB;IAC/C,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,SAAS,CAAU;IAC3B,OAAO,CAAC,UAAU,CAAgB;IAClC,OAAO,CAAC,UAAU,CAA2B;IAC7C,OAAO,CAAC,aAAa,CAAmC;gBAE5C,OAAO,GAAE,OAAO,CAAC,SAAS,CAAC,GAAG;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,aAAa,CAAC,EAAE,OAAO,CAAA;KAAO;IAgG3F;;OAEG;IACH,IAAI,aAAa,IAAI,MAAM,CAE1B;IAED;;OAEG;YACW,cAAc;IA4B5B;;OAEG;IACH,WAAW,CACT,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC7B,WAAW;IAyCd;;OAEG;IACG,cAAc,CAClB,WAAW,EAAE,WAAW,EACxB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC5B,eAAe,GAAE,MAAa,GAC7B,OAAO,CAAC,WAAW,CAAC;IA6FvB;;OAEG;IACG,MAAM,CACV,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,WAAW,EACxB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC5B,WAAW,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,EACxC,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,mBAAmB,CAAC;IA0O/B;;OAEG;IACG,QAAQ,CACZ,WAAW,EAAE,WAAW,EACxB,iBAAiB,EAAE,MAAM,EACzB,eAAe,GAAE,MAAa,EAC9B,cAAc,CAAC,EAAE,MAAM,EAAE,EACzB,WAAW,CAAC,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC5B,OAAO,CAAC,gBAAgB,CAAC;IAwF5B;;OAEG;IACG,WAAW,CAAC,WAAW,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC;IAwB7D;;OAEG;IACG,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC;IA6BtE;;OAEG;IACG,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI7C;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAa9E;;OAEG;IACG,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;IAaxD;;OAEG;YACW,mBAAmB;IA+BjC;;OAEG;IACG,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAOpE;;OAEG;YACW,eAAe;IAsB7B;;OAEG;IACG,uBAAuB,CAAC,MAAM,EAAE,uBAAuB,GAAG,OAAO,CAAC,uBAAuB,CAAC;IAgBhG;;OAEG;IACG,uBAAuB,CAC3B,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC;IAgBrC;;OAEG;IACG,sBAAsB,CAAC,SAAS,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQpF;;OAEG;IACG,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIjD;;;OAGG;IACG,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAarE;;OAEG;IACG,gBAAgB,CACpB,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,WAAW,EACxB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC5B,OAAO,CAAC,EAAE,aAAa,GACtB,OAAO,CAAC,mBAAmB,CAAC;IAiJ/B;;OAEG;IACH,KAAK,IAAI,IAAI;CAId"}