@alter-ai/alter-sdk 0.2.1 → 0.3.1

package/dist/index.js

@@ -1,3 +1,6 @@
+// src/client.ts
+import { createHash, createHmac, randomUUID } from "crypto";
+
 // src/exceptions.ts
 var AlterSDKError = class extends Error {
   details;
@@ -66,6 +69,12 @@ var TimeoutError = class extends NetworkError {
 };
 
 // src/models.ts
+var ActorType = /* @__PURE__ */ ((ActorType2) => {
+  ActorType2["BACKEND_SERVICE"] = "backend_service";
+  ActorType2["AI_AGENT"] = "ai_agent";
+  ActorType2["MCP_SERVER"] = "mcp_server";
+  return ActorType2;
+})(ActorType || {});
 var TokenResponse = class _TokenResponse {
   /** Token type (usually "Bearer") */
   tokenType;
@@ -77,12 +86,21 @@ var TokenResponse = class _TokenResponse {
   scopes;
   /** Connection ID that provided this token */
   connectionId;
+  /** Provider ID (google, github, etc.) */
+  providerId;
+  /** HTTP header name for credential injection (e.g., "Authorization", "X-API-Key") */
+  injectionHeader;
+  /** Header value format with {token} placeholder (e.g., "Bearer {token}", "{token}") */
+  injectionFormat;
   constructor(data) {
     this.tokenType = data.token_type ?? "Bearer";
     this.expiresIn = data.expires_in ?? null;
     this.expiresAt = data.expires_at ? _TokenResponse.parseExpiresAt(data.expires_at) : null;
     this.scopes = data.scopes ?? [];
     this.connectionId = data.connection_id;
+    this.providerId = data.provider_id ?? "";
+    this.injectionHeader = data.injection_header ?? "Authorization";
+    this.injectionFormat = data.injection_format ?? "Bearer {token}";
     Object.freeze(this);
   }
   /**
@@ -144,6 +162,84 @@ var TokenResponse = class _TokenResponse {
     return this.toString();
   }
 };
+var ConnectionInfo = class {
+  id;
+  providerId;
+  scopes;
+  accountIdentifier;
+  accountDisplayName;
+  status;
+  expiresAt;
+  createdAt;
+  lastUsedAt;
+  constructor(data) {
+    this.id = data.id;
+    this.providerId = data.provider_id;
+    this.scopes = data.scopes ?? [];
+    this.accountIdentifier = data.account_identifier ?? null;
+    this.accountDisplayName = data.account_display_name ?? null;
+    this.status = data.status;
+    this.expiresAt = data.expires_at ?? null;
+    this.createdAt = data.created_at;
+    this.lastUsedAt = data.last_used_at ?? null;
+    Object.freeze(this);
+  }
+  toJSON() {
+    return {
+      id: this.id,
+      provider_id: this.providerId,
+      scopes: this.scopes,
+      account_identifier: this.accountIdentifier,
+      account_display_name: this.accountDisplayName,
+      status: this.status,
+      expires_at: this.expiresAt,
+      created_at: this.createdAt,
+      last_used_at: this.lastUsedAt
+    };
+  }
+  toString() {
+    return `ConnectionInfo(id=${this.id}, provider=${this.providerId}, status=${this.status})`;
+  }
+};
+var ConnectSession = class {
+  sessionToken;
+  connectUrl;
+  expiresIn;
+  expiresAt;
+  constructor(data) {
+    this.sessionToken = data.session_token;
+    this.connectUrl = data.connect_url;
+    this.expiresIn = data.expires_in;
+    this.expiresAt = data.expires_at;
+    Object.freeze(this);
+  }
+  toJSON() {
+    return {
+      session_token: this.sessionToken,
+      connect_url: this.connectUrl,
+      expires_in: this.expiresIn,
+      expires_at: this.expiresAt
+    };
+  }
+  toString() {
+    return `ConnectSession(url=${this.connectUrl}, expires_in=${this.expiresIn})`;
+  }
+};
+var ConnectionListResult = class {
+  connections;
+  total;
+  limit;
+  offset;
+  hasMore;
+  constructor(data) {
+    this.connections = data.connections;
+    this.total = data.total;
+    this.limit = data.limit;
+    this.offset = data.offset;
+    this.hasMore = data.has_more;
+    Object.freeze(this);
+  }
+};
 var SENSITIVE_HEADERS = /* @__PURE__ */ new Set([
   "authorization",
   "cookie",
@@ -238,9 +334,8 @@ function _extractAccessToken(token) {
   return value;
 }
 var _fetch;
-var SDK_VERSION = "0.2.1";
+var SDK_VERSION = "0.3.0";
 var SDK_USER_AGENT = `alter-sdk-node/${SDK_VERSION}`;
-var VALID_ACTOR_TYPES = ["ai_agent", "mcp_server"];
 var HTTP_FORBIDDEN = 403;
 var HTTP_NOT_FOUND = 404;
 var HTTP_BAD_REQUEST = 400;
@@ -320,6 +415,8 @@ var AlterVault = class _AlterVault {
   // SECURITY LAYER 4: ES2022 private fields — truly private at runtime.
   // These are NOT accessible via (obj as any), Object.keys(), or prototype.
   // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  /** HMAC signing key (derived from API key using AWS SigV4 pattern, raw bytes) */
+  #hmacKey;
   /** HTTP Client for Alter Backend (has x-api-key) */
   #alterClient;
   /** HTTP Client for External Provider APIs (NO x-api-key) */
@@ -357,10 +454,8 @@ var AlterVault = class _AlterVault {
     for (const [name, value] of actorStrings) {
       _AlterVault.#validateActorString(value, name);
     }
-    this.baseUrl = (options.baseUrl ?? "https://api.alter.com").replace(
-      /\/+$/,
-      ""
-    );
+    this.#hmacKey = createHmac("sha256", options.apiKey).update("alter-signing-v1").digest();
+    this.baseUrl = (process.env.ALTER_BASE_URL ?? "https://backend.alterai.dev").replace(/\/+$/, "");
     const timeoutMs = options.timeout ?? 3e4;
     this.#actorType = options.actorType;
     this.#actorIdentifier = options.actorIdentifier;
@@ -413,14 +508,20 @@ var AlterVault = class _AlterVault {
     if (!apiKey.startsWith("alter_key_")) {
       throw new AlterSDKError("api_key must start with 'alter_key_'");
     }
-    if (actorType && !VALID_ACTOR_TYPES.includes(actorType)) {
-      throw new AlterSDKError("actor_type must be 'ai_agent' or 'mcp_server'");
+    if (!actorType) {
+      throw new AlterSDKError(
+        "actor_type is required (use ActorType.AI_AGENT, ActorType.MCP_SERVER, or ActorType.BACKEND_SERVICE)"
+      );
     }
-    if (actorType && !actorIdentifier) {
+    const validValues = Object.values(ActorType);
+    if (!validValues.includes(String(actorType))) {
       throw new AlterSDKError(
-        "actor_identifier is required when actor_type is set"
+        `actor_type must be one of ${JSON.stringify(validValues.sort())}, got '${String(actorType)}'`
       );
     }
+    if (!actorIdentifier) {
+      throw new AlterSDKError("actor_identifier is required");
+    }
   }
   /**
    * Build default headers for the Alter backend HTTP client.
@@ -447,6 +548,28 @@ var AlterVault = class _AlterVault {
     }
     return headers;
   }
+  /**
+   * Compute HMAC-SHA256 signature headers for an Alter backend request.
+   *
+   * String-to-sign format: METHOD\nPATH_WITH_SORTED_QUERY\nTIMESTAMP\nCONTENT_HASH
+   *
+   * The path should include sorted query parameters if present (e.g. "/sdk/endpoint?a=1&b=2").
+   * Currently all SDK→backend calls are POSTs without query params, so the path is clean.
+   */
+  #computeHmacHeaders(method, path, body) {
+    const timestamp = String(Math.floor(Date.now() / 1e3));
+    const contentHash = createHash("sha256").update(body ?? "").digest("hex");
+    const stringToSign = `${method.toUpperCase()}
+${path}
+${timestamp}
+${contentHash}`;
+    const signature = createHmac("sha256", this.#hmacKey).update(stringToSign).digest("hex");
+    return {
+      "X-Alter-Timestamp": timestamp,
+      "X-Alter-Content-SHA256": contentHash,
+      "X-Alter-Signature": signature
+    };
+  }
   /**
    * Build per-request actor headers for instance tracking.
    */
@@ -543,7 +666,7 @@ var AlterVault = class _AlterVault {
     if (response.status === HTTP_NOT_FOUND) {
       const errorData = await _AlterVault.#safeParseJson(response);
       throw new ConnectionNotFoundError(
-        errorData.message ?? "OAuth connection not found for these attributes",
+        errorData.message ?? "OAuth connection not found for the given connection_id",
         errorData
       );
     }
@@ -589,21 +712,24 @@ var AlterVault = class _AlterVault {
    * This is a private method. Tokens are NEVER exposed to developers.
    * Use request() instead, which handles tokens internally.
    */
-  async #getToken(providerId, attributes, reason, runId, threadId, toolCallId) {
+  async #getToken(connectionId, reason, requestMetadata, runId, threadId, toolCallId) {
     const actorHeaders = this.#getActorRequestHeaders(
       runId,
       threadId,
       toolCallId
     );
     let response;
+    const tokenBody = {
+      connection_id: connectionId,
+      reason: reason ?? null,
+      request: requestMetadata ?? null
+    };
+    const tokenPath = "/sdk/token";
+    const hmacHeaders = this.#computeHmacHeaders("POST", tokenPath, JSON.stringify(tokenBody));
     try {
-      response = await this.#alterClient.post("/oauth/token", {
-        json: {
-          provider_id: providerId,
-          attributes,
-          reason: reason ?? null
-        },
-        headers: actorHeaders
+      response = await this.#alterClient.post(tokenPath, {
+        json: tokenBody,
+        headers: { ...actorHeaders, ...hmacHeaders }
       });
     } catch (error) {
       if (_AlterVault.#isTimeoutOrAbortError(error)) {
@@ -620,7 +746,7 @@ var AlterVault = class _AlterVault {
       }
       throw new TokenRetrievalError(
         `Failed to retrieve token: ${error instanceof Error ? error.message : String(error)}`,
-        { provider_id: providerId, error: String(error) }
+        { connection_id: connectionId, error: String(error) }
       );
     }
     this.#cacheActorIdFromResponse(response);
@@ -628,6 +754,18 @@ var AlterVault = class _AlterVault {
     const tokenData = await response.json();
     const typedData = tokenData;
     const tokenResponse = new TokenResponse(typedData);
+    if (!/^[A-Za-z][A-Za-z0-9-]*$/.test(tokenResponse.injectionHeader)) {
+      throw new TokenRetrievalError(
+        `Backend returned invalid injection_header: ${tokenResponse.injectionHeader}`,
+        { connectionId: String(connectionId) }
+      );
+    }
+    if (/[\r\n\x00]/.test(tokenResponse.injectionFormat)) {
+      throw new TokenRetrievalError(
+        `Backend returned invalid injection_format (contains control characters)`,
+        { connectionId: String(connectionId) }
+      );
+    }
     _storeAccessToken(tokenResponse, typedData.access_token);
     return tokenResponse;
   }
@@ -656,10 +794,13 @@ var AlterVault = class _AlterVault {
         toolCallId: params.toolCallId
       });
       const sanitized = auditLog.sanitize();
-      const actorHeaders = this.#getActorRequestHeaders();
-      const response = await this.#alterClient.post("/oauth/audit/api-call", {
-        json: sanitized,
-        headers: actorHeaders
+      const actorHeaders = this.#getActorRequestHeaders(params.runId);
+      const auditPath = "/sdk/oauth/audit/api-call";
+      const auditBody = sanitized;
+      const auditHmac = this.#computeHmacHeaders("POST", auditPath, JSON.stringify(auditBody));
+      const response = await this.#alterClient.post(auditPath, {
+        json: auditBody,
+        headers: { ...actorHeaders, ...auditHmac }
       });
       this.#cacheActorIdFromResponse(response);
       if (!response.ok) {
@@ -725,13 +866,13 @@ var AlterVault = class _AlterVault {
    * 4. Logs the call for audit (fire-and-forget)
    * 5. Returns the raw response
    */
-  async request(provider, method, url, options) {
+  async request(connectionId, method, url, options) {
     if (this.#closed) {
       throw new AlterSDKError(
         "SDK instance has been closed. Create a new AlterVault instance to make requests."
       );
     }
-    const providerStr = String(provider);
+    const runId = options?.runId ?? randomUUID();
     const methodStr = String(method).toUpperCase();
     const urlLower = url.toLowerCase();
     if (!ALLOWED_URL_SCHEMES.some((scheme) => urlLower.startsWith(scheme))) {
@@ -739,7 +880,7 @@ var AlterVault = class _AlterVault {
         `URL must start with https:// or http://, got: ${url.slice(0, 50)}`
       );
     }
-    if (options.pathParams && Object.keys(options.pathParams).length > 0) {
+    if (options?.pathParams && Object.keys(options.pathParams).length > 0) {
       const encodedParams = {};
       for (const [key, value] of Object.entries(options.pathParams)) {
         encodedParams[key] = encodeURIComponent(String(value));
@@ -769,21 +910,25 @@ var AlterVault = class _AlterVault {
         );
       }
     }
-    if (options.extraHeaders && "Authorization" in options.extraHeaders) {
+    const tokenResponse = await this.#getToken(
+      connectionId,
+      options?.reason,
+      { method: methodStr, url },
+      runId,
+      options?.threadId,
+      options?.toolCallId
+    );
+    const injectionHeaderLower = tokenResponse.injectionHeader.toLowerCase();
+    if (options?.extraHeaders && Object.keys(options.extraHeaders).some(
+      (k) => k.toLowerCase() === injectionHeaderLower
+    )) {
       console.warn(
-        "extraHeaders contains 'Authorization' which will be overwritten with the auto-injected Bearer token"
+        `extraHeaders contains '${tokenResponse.injectionHeader}' which will be overwritten with the auto-injected credential`
       );
     }
-    const tokenResponse = await this.#getToken(
-      providerStr,
-      options.user,
-      options.reason,
-      options.runId,
-      options.threadId,
-      options.toolCallId
-    );
-    const requestHeaders = options.extraHeaders ? { ...options.extraHeaders } : {};
-    requestHeaders["Authorization"] = `Bearer ${_extractAccessToken(tokenResponse)}`;
+    const requestHeaders = options?.extraHeaders ? { ...options.extraHeaders } : {};
+    const accessToken = _extractAccessToken(tokenResponse);
+    requestHeaders[tokenResponse.injectionHeader] = tokenResponse.injectionFormat.replace("{token}", accessToken);
     if (!requestHeaders["User-Agent"]) {
       requestHeaders["User-Agent"] = SDK_USER_AGENT;
     }
@@ -791,16 +936,16 @@ var AlterVault = class _AlterVault {
     let response;
     try {
       response = await this.#providerClient.request(methodStr, url, {
-        json: options.json,
+        json: options?.json,
         headers: requestHeaders,
-        params: options.queryParams
+        params: options?.queryParams
       });
     } catch (error) {
       if (_AlterVault.#isTimeoutOrAbortError(error)) {
         throw new TimeoutError(
           `Provider API request timed out: ${error instanceof Error ? error.message : String(error)}`,
           {
-            provider: providerStr,
+            connection_id: connectionId,
             method: methodStr,
             url
           }
@@ -809,7 +954,7 @@ var AlterVault = class _AlterVault {
       throw new NetworkError(
         `Failed to call provider API: ${error instanceof Error ? error.message : String(error)}`,
         {
-          provider: providerStr,
+          connection_id: connectionId,
           method: methodStr,
           url,
           error: String(error)
@@ -819,7 +964,7 @@ var AlterVault = class _AlterVault {
     const latencyMs = Date.now() - startTime;
     const auditHeaders = {};
     for (const [key, value] of Object.entries(requestHeaders)) {
-      if (key.toLowerCase() !== "authorization") {
+      if (key.toLowerCase() !== injectionHeaderLower) {
         auditHeaders[key] = value;
       }
     }
@@ -830,19 +975,19 @@ var AlterVault = class _AlterVault {
     });
     this.#scheduleAuditLog({
       connectionId: tokenResponse.connectionId,
-      providerId: providerStr,
+      providerId: tokenResponse.providerId || connectionId,
       method: methodStr,
       url,
       requestHeaders: auditHeaders,
-      requestBody: options.json ?? null,
+      requestBody: options?.json ?? null,
       responseStatus: response.status,
       responseHeaders,
       responseBody,
       latencyMs,
-      reason: options.reason ?? null,
-      runId: options.runId ?? null,
-      threadId: options.threadId ?? null,
-      toolCallId: options.toolCallId ?? null
+      reason: options?.reason ?? null,
+      runId,
+      threadId: options?.threadId ?? null,
+      toolCallId: options?.toolCallId ?? null
     });
     if (response.status >= HTTP_CLIENT_ERROR_START) {
       throw new ProviderAPIError(
@@ -850,7 +995,7 @@ var AlterVault = class _AlterVault {
         response.status,
         responseBody,
         {
-          provider: providerStr,
+          connection_id: connectionId,
           method: methodStr,
           url
         }
@@ -858,6 +1003,117 @@ var AlterVault = class _AlterVault {
     }
     return response;
   }
+  /**
+   * List OAuth connections for this app.
+   *
+   * Returns paginated connection metadata (no tokens).
+   * Useful for discovering which services a user has connected.
+   */
+  async listConnections(options) {
+    if (this.#closed) {
+      throw new AlterSDKError(
+        "SDK instance has been closed. Create a new AlterVault instance to make requests."
+      );
+    }
+    const actorHeaders = this.#getActorRequestHeaders();
+    let response;
+    const listBody = {
+      provider_id: options?.providerId ?? null,
+      limit: options?.limit ?? 100,
+      offset: options?.offset ?? 0
+    };
+    const listPath = "/sdk/oauth/connections/list";
+    const listHmac = this.#computeHmacHeaders("POST", listPath, JSON.stringify(listBody));
+    try {
+      response = await this.#alterClient.post(listPath, {
+        json: listBody,
+        headers: { ...actorHeaders, ...listHmac }
+      });
+    } catch (error) {
+      if (_AlterVault.#isTimeoutOrAbortError(error)) {
+        throw new TimeoutError(
+          `Request to Alter Vault backend timed out: ${error instanceof Error ? error.message : String(error)}`,
+          { base_url: this.baseUrl }
+        );
+      }
+      if (error instanceof TypeError) {
+        throw new NetworkError(
+          `Failed to connect to Alter Vault backend: ${error.message}`,
+          { base_url: this.baseUrl }
+        );
+      }
+      throw new AlterSDKError(
+        `Failed to list connections: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+    this.#cacheActorIdFromResponse(response);
+    await this.#handleErrorResponse(response);
+    const data = await response.json();
+    const connections = data.connections.map(
+      (c) => new ConnectionInfo(
+        c
+      )
+    );
+    return new ConnectionListResult({
+      connections,
+      total: data.total,
+      limit: data.limit,
+      offset: data.offset,
+      has_more: data.has_more
+    });
+  }
+  /**
+   * Create a Connect session for initiating OAuth flows.
+   *
+   * Returns a URL the user can open in their browser to authorize access.
+   */
+  async createConnectSession(options) {
+    if (this.#closed) {
+      throw new AlterSDKError(
+        "SDK instance has been closed. Create a new AlterVault instance to make requests."
+      );
+    }
+    if (!options.endUser?.id) {
+      throw new AlterSDKError("endUser.id is required");
+    }
+    const actorHeaders = this.#getActorRequestHeaders();
+    let response;
+    const sessionBody = {
+      end_user: options.endUser,
+      allowed_providers: options.allowedProviders ?? null,
+      return_url: options.returnUrl ?? null,
+      allowed_origin: options.allowedOrigin ?? null,
+      metadata: options.metadata ?? null
+    };
+    const sessionPath = "/sdk/oauth/connect/session";
+    const sessionHmac = this.#computeHmacHeaders("POST", sessionPath, JSON.stringify(sessionBody));
+    try {
+      response = await this.#alterClient.post(sessionPath, {
+        json: sessionBody,
+        headers: { ...actorHeaders, ...sessionHmac }
+      });
+    } catch (error) {
+      if (_AlterVault.#isTimeoutOrAbortError(error)) {
+        throw new TimeoutError(
+          `Request to Alter Vault backend timed out: ${error instanceof Error ? error.message : String(error)}`,
+          { base_url: this.baseUrl }
+        );
+      }
+      if (error instanceof TypeError) {
+        throw new NetworkError(
+          `Failed to connect to Alter Vault backend: ${error.message}`,
+          { base_url: this.baseUrl }
+        );
+      }
+      throw new AlterSDKError(
+        `Failed to create connect session: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+    this.#cacheActorIdFromResponse(response);
+    await this.#handleErrorResponse(response);
+    const data = await response.json();
+    return new ConnectSession(data);
+  }
   /**
    * Close HTTP clients and release resources.
    * Waits for any pending audit tasks before closing.
@@ -886,8 +1142,6 @@ var Provider = /* @__PURE__ */ ((Provider2) => {
   Provider2["GOOGLE"] = "google";
   Provider2["GITHUB"] = "github";
   Provider2["SLACK"] = "slack";
-  Provider2["MICROSOFT"] = "microsoft";
-  Provider2["SALESFORCE"] = "salesforce";
   Provider2["SENTRY"] = "sentry";
   return Provider2;
 })(Provider || {});
@@ -903,8 +1157,12 @@ var HttpMethod = /* @__PURE__ */ ((HttpMethod2) => {
 })(HttpMethod || {});
 export {
   APICallAuditLog,
+  ActorType,
   AlterSDKError,
   AlterVault,
+  ConnectSession,
+  ConnectionInfo,
+  ConnectionListResult,
   ConnectionNotFoundError,
   HttpMethod,
   NetworkError,

package/package.json

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