@alter-ai/alter-sdk 0.2.0 → 0.2.1

package/README.md

@@ -1,7 +1,5 @@
 # Alter SDK for TypeScript / Node.js
 
-> **Version**: 0.4.0
-
 Official TypeScript SDK for [Alter Vault](https://alterai.dev) — OAuth token management with policy enforcement.
 
 ## Features
@@ -13,8 +11,6 @@ Official TypeScript SDK for [Alter Vault](https://alterai.dev) — OAuth token m
 - **Automatic Audit Logging**: All API calls logged as fire-and-forget background tasks
 - **Real-time Policy Enforcement**: Every token request checked against current policies
 - **Automatic Token Refresh**: Tokens refreshed transparently by the backend
-- **Dual HTTP Client Security**: Separate clients prevent credential leakage to providers
-- **Security Hardened (v0.4.0)**: Frozen `HttpClient` prototype, `WeakMap` token storage, unexported module-private token accessors, and hardened `fetch` capture prevent rogue agent token extraction
 - **Actor Tracking**: First-class support for AI agent and MCP server observability
 - **Native Promises**: Built on native `fetch` — no heavy dependencies
 
@@ -95,13 +91,14 @@ const response = await vault.request(
 
 ```typescript
 const response = await vault.request(
-  Provider.GOOGLE,
-  HttpMethod.GET,
-  "https://api.example.com/v1/items",
+  "notion",
+  HttpMethod.POST,
+  "https://api.notion.com/v1/databases/{db_id}/query",
   {
     user: { user_id: "alice" },
-    queryParams: { fields: "name,price", limit: "10" },
+    pathParams: { db_id: "abc123" },
     extraHeaders: { "Notion-Version": "2022-06-28" },
+    json: { page_size: 10 },
   },
 );
 ```
@@ -126,17 +123,55 @@ const response = await vault.request(
     user: { user_id: "alice" },
     runId: "550e8400-e29b-41d4-a716-446655440000",
     threadId: "thread-xyz",
+    toolCallId: "call_abc_123",
   },
 );
 ```
 
+### Multi-Agent Deployments
+
+Each agent must create its own `AlterVault` instance with a unique actor identity. Do not share a single instance across agents.
+
+```typescript
+// Each agent gets its own vault instance
+const emailAgent = new AlterVault({
+  apiKey: "alter_key_...",
+  actorType: "ai_agent",
+  actorIdentifier: "email-assistant-v2",
+  actorName: "Email Assistant",
+});
+
+const calendarAgent = new AlterVault({
+  apiKey: "alter_key_...",
+  actorType: "ai_agent",
+  actorIdentifier: "calendar-agent-v1",
+  actorName: "Calendar Agent",
+});
+
+// Audit logs and policies are tracked per agent
+const user = { user_id: "alice" };
+await emailAgent.request(
+  Provider.GOOGLE, HttpMethod.GET,
+  "https://gmail.googleapis.com/gmail/v1/users/me/messages",
+  { user },
+);
+await calendarAgent.request(
+  Provider.GOOGLE, HttpMethod.GET,
+  "https://www.googleapis.com/calendar/v3/calendars/primary/events",
+  { user },
+);
+
+// Clean up each instance
+await emailAgent.close();
+await calendarAgent.close();
+```
+
 ## Configuration
 
 ```typescript
 const vault = new AlterVault({
   apiKey: "alter_key_...",              // Required: Alter Vault API key
   baseUrl: "https://api.alter.com",     // Optional: Custom API URL
-  enableAuditLogging: true,             // Optional: Enable audit logs (default: true)
   timeout: 30000,                       // Optional: HTTP timeout in ms (default: 30000)
   // Actor tracking (optional)
   actorType: "ai_agent",               // "ai_agent" or "mcp_server"
@@ -150,14 +185,14 @@ const vault = new AlterVault({
 
 ## Error Handling
 
-> **Note:** Input validation errors (invalid `apiKey`, invalid `actorType`, SSRF URL scheme violations, missing `pathParams`) throw `AlterSDKError`.
+> **Note:** Input validation errors (invalid `apiKey`, invalid `actorType`, invalid URL scheme, missing `pathParams`) throw `AlterSDKError`.
 
 ```typescript
 import {
   AlterVault,
   Provider,
   HttpMethod,
-  AlterSDKError,              // Base error (including validation: apiKey, actorType, SSRF, pathParams)
+  AlterSDKError,              // Base error (including validation: apiKey, actorType, URL scheme, pathParams)
   PolicyViolationError,
   ConnectionNotFoundError,
   TokenExpiredError,
@@ -206,22 +241,20 @@ try {
 // Calling request() after close() throws AlterSDKError
 ```
 
-## Architecture
+## Supported Providers
 
-See [ALTER_TYPESCRIPT_SDK_ARCHITECTURE.md](./ALTER_TYPESCRIPT_SDK_ARCHITECTURE.md) for details on:
-- Dual HTTP client security model
-- Zero token exposure design
-- No SDK-side caching (real-time policy enforcement)
-- SSRF prevention with case-insensitive URL scheme validation
-- Actor tracking and audit logging
+```typescript
+import { Provider } from "@alter-ai/alter-sdk";
 
-## Development
+Provider.GOOGLE       // "google"
+Provider.GITHUB       // "github"
+Provider.SLACK        // "slack"
+Provider.MICROSOFT    // "microsoft"
+Provider.SALESFORCE   // "salesforce"
+Provider.SENTRY       // "sentry"
 
-```bash
-npm install
-npm run test           # Run tests (70 tests)
-npm run typecheck      # Type check
-npm run build          # Build for distribution
+// Strings also work for any provider
+await vault.request("notion", HttpMethod.GET, url, { user });
 ```
 
 ## Requirements

package/dist/index.cjs

@@ -276,7 +276,7 @@ function _extractAccessToken(token) {
   return value;
 }
 var _fetch;
-var SDK_VERSION = "0.2.0";
+var SDK_VERSION = "0.2.1";
 var SDK_USER_AGENT = `alter-sdk-node/${SDK_VERSION}`;
 var VALID_ACTOR_TYPES = ["ai_agent", "mcp_server"];
 var HTTP_FORBIDDEN = 403;
@@ -372,7 +372,6 @@ var AlterVault = class _AlterVault {
   // Public readonly properties (frozen by Object.freeze)
   // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   baseUrl;
-  enableAuditLogging;
   /** Actor tracking configuration (readonly, not secret) */
   #actorType;
   #actorIdentifier;
@@ -400,7 +399,6 @@ var AlterVault = class _AlterVault {
       /\/+$/,
       ""
     );
-    this.enableAuditLogging = options.enableAuditLogging ?? true;
     const timeoutMs = options.timeout ?? 3e4;
     this.#actorType = options.actorType;
     this.#actorIdentifier = options.actorIdentifier;
@@ -678,9 +676,6 @@ var AlterVault = class _AlterVault {
    * if audit logging fails.
    */
   async #logApiCall(params) {
-    if (!this.enableAuditLogging) {
-      return;
-    }
     try {
       const auditLog = new APICallAuditLog({
         connectionId: params.connectionId,
@@ -765,7 +760,7 @@ var AlterVault = class _AlterVault {
    * 1. Fetches an OAuth token from Alter backend (never exposed)
    * 2. Injects the token as a Bearer header
    * 3. Calls the provider API
-   * 4. Logs the call for audit (if enabled, fire-and-forget)
+   * 4. Logs the call for audit (fire-and-forget)
    * 5. Returns the raw response
    */
   async request(provider, method, url, options) {

package/dist/index.d.cts

@@ -60,17 +60,9 @@ declare enum HttpMethod {
 /**
  * Main Alter Vault SDK client.
  *
- * This module provides the primary AlterVault class for interacting with
- * the Alter Vault OAuth token management system.
- *
- * Security Hardening (v0.4.0):
- * - Layer 1: Prototype frozen to prevent subclass method override attacks
- * - Layer 1b: HttpClient.prototype also frozen to prevent request interception
- * - Layer 2: Instance frozen after construction (Object.freeze)
- * - Layer 3: API key not stored as instance property
- * - Layer 4: ES2022 private fields (#) for truly private internal state
- * - Layer 5: (see models.ts) TokenResponse access_token in module-private WeakMap
- * - Layer 6: Test accessors removed from production builds
+ * Provides the AlterVault class for OAuth token management with
+ * zero token exposure — tokens are retrieved and injected automatically,
+ * never returned to the caller.
  */
 
 /**
@@ -81,8 +73,6 @@ interface AlterVaultOptions {
     apiKey: string;
     /** Base URL for Alter Vault API */
     baseUrl?: string;
-    /** Whether to send audit logs to backend (default: true) */
-    enableAuditLogging?: boolean;
     /** HTTP request timeout in milliseconds (default: 30000) */
     timeout?: number;
     /** Actor type ("ai_agent" or "mcp_server") for tracking */
@@ -129,17 +119,7 @@ interface RequestOptions {
  * - Audit logging of API calls
  * - Actor tracking for AI agents and MCP servers
  *
- * Zero Token Exposure:
- * - Tokens are retrieved internally but NEVER exposed to developers
- * - All API calls inject tokens automatically behind the scenes
- * - Developers only see API results, never authentication credentials
- *
- * Security Hardening:
- * - Cannot be effectively subclassed (prototype is frozen)
- * - Instance is frozen after construction (Object.freeze)
- * - API key is NOT stored as an instance property
- * - Internal HTTP clients use ES2022 private fields (#)
- * - Test accessors are removed (no production leak path)
+ * Tokens are retrieved and injected automatically — never exposed to callers.
  *
  * @example
  * ```typescript
@@ -162,7 +142,6 @@ interface RequestOptions {
 declare class AlterVault {
     #private;
     readonly baseUrl: string;
-    readonly enableAuditLogging: boolean;
     constructor(options: AlterVaultOptions);
     /**
      * Execute an HTTP request to a provider API with automatic token injection.
@@ -171,7 +150,7 @@ declare class AlterVault {
      * 1. Fetches an OAuth token from Alter backend (never exposed)
      * 2. Injects the token as a Bearer header
      * 3. Calls the provider API
-     * 4. Logs the call for audit (if enabled, fire-and-forget)
+     * 4. Logs the call for audit (fire-and-forget)
      * 5. Returns the raw response
      */
     request(provider: Provider | string, method: HttpMethod | string, url: string, options: RequestOptions): Promise<Response>;

package/dist/index.d.ts

@@ -60,17 +60,9 @@ declare enum HttpMethod {
 /**
  * Main Alter Vault SDK client.
  *
- * This module provides the primary AlterVault class for interacting with
- * the Alter Vault OAuth token management system.
- *
- * Security Hardening (v0.4.0):
- * - Layer 1: Prototype frozen to prevent subclass method override attacks
- * - Layer 1b: HttpClient.prototype also frozen to prevent request interception
- * - Layer 2: Instance frozen after construction (Object.freeze)
- * - Layer 3: API key not stored as instance property
- * - Layer 4: ES2022 private fields (#) for truly private internal state
- * - Layer 5: (see models.ts) TokenResponse access_token in module-private WeakMap
- * - Layer 6: Test accessors removed from production builds
+ * Provides the AlterVault class for OAuth token management with
+ * zero token exposure — tokens are retrieved and injected automatically,
+ * never returned to the caller.
  */
 
 /**
@@ -81,8 +73,6 @@ interface AlterVaultOptions {
     apiKey: string;
     /** Base URL for Alter Vault API */
     baseUrl?: string;
-    /** Whether to send audit logs to backend (default: true) */
-    enableAuditLogging?: boolean;
     /** HTTP request timeout in milliseconds (default: 30000) */
     timeout?: number;
     /** Actor type ("ai_agent" or "mcp_server") for tracking */
@@ -129,17 +119,7 @@ interface RequestOptions {
  * - Audit logging of API calls
  * - Actor tracking for AI agents and MCP servers
  *
- * Zero Token Exposure:
- * - Tokens are retrieved internally but NEVER exposed to developers
- * - All API calls inject tokens automatically behind the scenes
- * - Developers only see API results, never authentication credentials
- *
- * Security Hardening:
- * - Cannot be effectively subclassed (prototype is frozen)
- * - Instance is frozen after construction (Object.freeze)
- * - API key is NOT stored as an instance property
- * - Internal HTTP clients use ES2022 private fields (#)
- * - Test accessors are removed (no production leak path)
+ * Tokens are retrieved and injected automatically — never exposed to callers.
  *
  * @example
  * ```typescript
@@ -162,7 +142,6 @@ interface RequestOptions {
 declare class AlterVault {
     #private;
     readonly baseUrl: string;
-    readonly enableAuditLogging: boolean;
     constructor(options: AlterVaultOptions);
     /**
      * Execute an HTTP request to a provider API with automatic token injection.
@@ -171,7 +150,7 @@ declare class AlterVault {
      * 1. Fetches an OAuth token from Alter backend (never exposed)
      * 2. Injects the token as a Bearer header
      * 3. Calls the provider API
-     * 4. Logs the call for audit (if enabled, fire-and-forget)
+     * 4. Logs the call for audit (fire-and-forget)
      * 5. Returns the raw response
      */
     request(provider: Provider | string, method: HttpMethod | string, url: string, options: RequestOptions): Promise<Response>;

package/dist/index.js

@@ -238,7 +238,7 @@ function _extractAccessToken(token) {
   return value;
 }
 var _fetch;
-var SDK_VERSION = "0.2.0";
+var SDK_VERSION = "0.2.1";
 var SDK_USER_AGENT = `alter-sdk-node/${SDK_VERSION}`;
 var VALID_ACTOR_TYPES = ["ai_agent", "mcp_server"];
 var HTTP_FORBIDDEN = 403;
@@ -334,7 +334,6 @@ var AlterVault = class _AlterVault {
   // Public readonly properties (frozen by Object.freeze)
   // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   baseUrl;
-  enableAuditLogging;
   /** Actor tracking configuration (readonly, not secret) */
   #actorType;
   #actorIdentifier;
@@ -362,7 +361,6 @@ var AlterVault = class _AlterVault {
       /\/+$/,
       ""
     );
-    this.enableAuditLogging = options.enableAuditLogging ?? true;
     const timeoutMs = options.timeout ?? 3e4;
     this.#actorType = options.actorType;
     this.#actorIdentifier = options.actorIdentifier;
@@ -640,9 +638,6 @@ var AlterVault = class _AlterVault {
    * if audit logging fails.
    */
   async #logApiCall(params) {
-    if (!this.enableAuditLogging) {
-      return;
-    }
     try {
       const auditLog = new APICallAuditLog({
         connectionId: params.connectionId,
@@ -727,7 +722,7 @@ var AlterVault = class _AlterVault {
    * 1. Fetches an OAuth token from Alter backend (never exposed)
    * 2. Injects the token as a Bearer header
    * 3. Calls the provider API
-   * 4. Logs the call for audit (if enabled, fire-and-forget)
+   * 4. Logs the call for audit (fire-and-forget)
    * 5. Returns the raw response
    */
   async request(provider, method, url, options) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alter-ai/alter-sdk",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Official TypeScript SDK for Alter Vault — OAuth token management with policy enforcement",
   "type": "module",
   "main": "dist/index.cjs",