@alter-ai/alter-sdk 0.2.2 → 0.4.0

package/dist/index.cjs

@@ -1,7 +1,9 @@
 "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)
@@ -15,15 +17,27 @@ var __copyProps = (to, from, except, desc) => {
   }
   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 index_exports = {};
 __export(index_exports, {
   APICallAuditLog: () => APICallAuditLog,
+  ActorType: () => ActorType,
   AlterSDKError: () => AlterSDKError,
   AlterVault: () => AlterVault,
+  ConnectFlowError: () => ConnectFlowError,
+  ConnectResult: () => ConnectResult,
   ConnectSession: () => ConnectSession,
+  ConnectTimeoutError: () => ConnectTimeoutError,
   ConnectionInfo: () => ConnectionInfo,
   ConnectionListResult: () => ConnectionListResult,
   ConnectionNotFoundError: () => ConnectionNotFoundError,
@@ -39,6 +53,9 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/client.ts
+var import_node_crypto2 = require("crypto");
+
 // src/exceptions.ts
 var AlterSDKError = class extends Error {
   details;
@@ -83,6 +100,18 @@ var TokenExpiredError = class extends TokenRetrievalError {
     this.connectionId = connectionId;
   }
 };
+var ConnectFlowError = class extends AlterSDKError {
+  constructor(message, details) {
+    super(message, details);
+    this.name = "ConnectFlowError";
+  }
+};
+var ConnectTimeoutError = class extends ConnectFlowError {
+  constructor(message, details) {
+    super(message, details);
+    this.name = "ConnectTimeoutError";
+  }
+};
 var ProviderAPIError = class extends AlterSDKError {
   statusCode;
   responseBody;
@@ -107,6 +136,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;
@@ -118,12 +153,29 @@ 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;
+  /** Extra credentials for multi-part auth (e.g. AWS SigV4 secret_key, region) */
+  additionalCredentials;
   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}";
+    if (data.additional_credentials) {
+      const { secret_key: _, ...safeCredentials } = data.additional_credentials;
+      this.additionalCredentials = Object.keys(safeCredentials).length > 0 ? safeCredentials : null;
+    } else {
+      this.additionalCredentials = null;
+    }
     Object.freeze(this);
   }
   /**
@@ -188,7 +240,6 @@ var TokenResponse = class _TokenResponse {
 var ConnectionInfo = class {
   id;
   providerId;
-  attributes;
   scopes;
   accountIdentifier;
   accountDisplayName;
@@ -199,7 +250,6 @@ var ConnectionInfo = class {
   constructor(data) {
     this.id = data.id;
     this.providerId = data.provider_id;
-    this.attributes = data.attributes ?? {};
     this.scopes = data.scopes ?? [];
     this.accountIdentifier = data.account_identifier ?? null;
     this.accountDisplayName = data.account_display_name ?? null;
@@ -213,7 +263,6 @@ var ConnectionInfo = class {
     return {
       id: this.id,
       provider_id: this.providerId,
-      attributes: this.attributes,
       scopes: this.scopes,
       account_identifier: this.accountIdentifier,
       account_display_name: this.accountDisplayName,
@@ -266,12 +315,38 @@ var ConnectionListResult = class {
     Object.freeze(this);
   }
 };
+var ConnectResult = class {
+  connectionId;
+  providerId;
+  accountIdentifier;
+  scopes;
+  constructor(data) {
+    this.connectionId = data.connection_id;
+    this.providerId = data.provider_id;
+    this.accountIdentifier = data.account_identifier ?? null;
+    this.scopes = data.scopes ?? [];
+    Object.freeze(this);
+  }
+  toJSON() {
+    return {
+      connection_id: this.connectionId,
+      provider_id: this.providerId,
+      account_identifier: this.accountIdentifier,
+      scopes: this.scopes
+    };
+  }
+  toString() {
+    return `ConnectResult(connection_id=${this.connectionId}, provider=${this.providerId})`;
+  }
+};
 var SENSITIVE_HEADERS = /* @__PURE__ */ new Set([
   "authorization",
   "cookie",
   "set-cookie",
   "x-api-key",
-  "x-auth-token"
+  "x-auth-token",
+  "x-amz-date",
+  "x-amz-content-sha256"
 ]);
 var APICallAuditLog = class {
   connectionId;
@@ -345,11 +420,171 @@ var APICallAuditLog = class {
   }
 };
 
+// src/aws-sig-v4.ts
+var import_node_crypto = require("crypto");
+var ALGORITHM = "AWS4-HMAC-SHA256";
+var AWS_HOST_RE = /^(?<service>[a-z0-9-]+)\.(?<region>[a-z]{2}(?:-[a-z0-9]+)+-\d+)\.amazonaws\.com$/;
+var S3_VIRTUAL_HOST_RE = /^[^.]+\.s3\.(?<region>[a-z]{2}(?:-[a-z0-9]+)+-\d+)\.amazonaws\.com$/;
+function hmacSha256(key, message) {
+  return (0, import_node_crypto.createHmac)("sha256", key).update(message, "utf8").digest();
+}
+function sha256Hex(data) {
+  const hash = (0, import_node_crypto.createHash)("sha256");
+  if (typeof data === "string") {
+    hash.update(data, "utf8");
+  } else {
+    hash.update(data);
+  }
+  return hash.digest("hex");
+}
+function detectServiceAndRegion(hostname) {
+  const lower = hostname.toLowerCase();
+  const m = AWS_HOST_RE.exec(lower);
+  if (m?.groups) {
+    return { service: m.groups.service, region: m.groups.region };
+  }
+  const s3m = S3_VIRTUAL_HOST_RE.exec(lower);
+  if (s3m?.groups) {
+    return { service: "s3", region: s3m.groups.region };
+  }
+  return { service: null, region: null };
+}
+function deriveSigningKey(secretKey, dateStamp, region, service) {
+  const kDate = hmacSha256(Buffer.from("AWS4" + secretKey, "utf8"), dateStamp);
+  const kRegion = hmacSha256(kDate, region);
+  const kService = hmacSha256(kRegion, service);
+  const kSigning = hmacSha256(kService, "aws4_request");
+  return kSigning;
+}
+function canonicalUri(path) {
+  if (!path) return "/";
+  if (!path.startsWith("/")) path = "/" + path;
+  const segments = path.split("/");
+  return segments.map(
+    (seg) => encodeURIComponent(seg).replace(
+      /[!'()*]/g,
+      (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`
+    )
+  ).join("/");
+}
+function canonicalQueryString(query) {
+  if (!query) return "";
+  const sorted = [];
+  for (const pair of query.split("&")) {
+    const eqIdx = pair.indexOf("=");
+    if (eqIdx === -1) {
+      sorted.push([decodeURIComponent(pair), ""]);
+    } else {
+      sorted.push([
+        decodeURIComponent(pair.slice(0, eqIdx)),
+        decodeURIComponent(pair.slice(eqIdx + 1))
+      ]);
+    }
+  }
+  sorted.sort((a, b) => {
+    if (a[0] < b[0]) return -1;
+    if (a[0] > b[0]) return 1;
+    if (a[1] < b[1]) return -1;
+    if (a[1] > b[1]) return 1;
+    return 0;
+  });
+  const sigv4Encode = (s) => encodeURIComponent(s).replace(
+    /[!'()*]/g,
+    (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`
+  );
+  return sorted.map(([k, v]) => `${sigv4Encode(k)}=${sigv4Encode(v)}`).join("&");
+}
+function canonicalHeadersAndSigned(headers) {
+  const canonical = {};
+  for (const [name, value] of Object.entries(headers)) {
+    const lowerName = name.toLowerCase().trim();
+    const trimmedValue = value.replace(/\s+/g, " ").trim();
+    canonical[lowerName] = trimmedValue;
+  }
+  const sortedNames = Object.keys(canonical).sort();
+  const canonicalStr = sortedNames.map((name) => `${name}:${canonical[name]}
+`).join("");
+  const signedStr = sortedNames.join(";");
+  return { canonicalHeaders: canonicalStr, signedHeaders: signedStr };
+}
+function signAwsRequest(opts) {
+  const parsed = new URL(opts.url);
+  const hostname = parsed.hostname;
+  let { region, service } = opts;
+  if (region == null || service == null) {
+    const detected = detectServiceAndRegion(hostname);
+    if (region == null) region = detected.region;
+    if (service == null) service = detected.service;
+  }
+  if (!region) {
+    throw new Error(
+      `Cannot determine AWS region from URL '${opts.url}'. Pass region explicitly via additional_credentials.`
+    );
+  }
+  if (!service) {
+    throw new Error(
+      `Cannot determine AWS service from URL '${opts.url}'. Pass service explicitly via additional_credentials.`
+    );
+  }
+  const timestamp = opts.timestamp ?? /* @__PURE__ */ new Date();
+  const amzDate = timestamp.toISOString().replace(/[-:]/g, "").replace(/\.\d{3}Z$/, "Z");
+  const dateStamp = amzDate.slice(0, 8);
+  const bodyBytes = opts.body != null ? typeof opts.body === "string" ? Buffer.from(opts.body, "utf8") : opts.body : Buffer.alloc(0);
+  const payloadHash = sha256Hex(bodyBytes);
+  const headersToSign = {};
+  const hasHost = Object.keys(opts.headers).some(
+    (k) => k.toLowerCase() === "host"
+  );
+  if (!hasHost) {
+    const port = parsed.port;
+    headersToSign["host"] = port && port !== "80" && port !== "443" ? `${hostname}:${port}` : hostname;
+  } else {
+    for (const [k, v] of Object.entries(opts.headers)) {
+      if (k.toLowerCase() === "host") {
+        headersToSign["host"] = v;
+        break;
+      }
+    }
+  }
+  headersToSign["x-amz-date"] = amzDate;
+  headersToSign["x-amz-content-sha256"] = payloadHash;
+  const canonicalUriStr = canonicalUri(parsed.pathname);
+  const canonicalQs = canonicalQueryString(parsed.search.replace(/^\?/, ""));
+  const { canonicalHeaders, signedHeaders } = canonicalHeadersAndSigned(headersToSign);
+  const canonicalRequest = [
+    opts.method.toUpperCase(),
+    canonicalUriStr,
+    canonicalQs,
+    canonicalHeaders,
+    signedHeaders,
+    payloadHash
+  ].join("\n");
+  const credentialScope = `${dateStamp}/${region}/${service}/aws4_request`;
+  const stringToSign = [
+    ALGORITHM,
+    amzDate,
+    credentialScope,
+    sha256Hex(canonicalRequest)
+  ].join("\n");
+  const signingKey = deriveSigningKey(opts.secretKey, dateStamp, region, service);
+  const signature = (0, import_node_crypto.createHmac)("sha256", signingKey).update(stringToSign, "utf8").digest("hex");
+  const authorization = `${ALGORITHM} Credential=${opts.accessKeyId}/${credentialScope}, SignedHeaders=${signedHeaders}, Signature=${signature}`;
+  return {
+    Authorization: authorization,
+    "x-amz-date": amzDate,
+    "x-amz-content-sha256": payloadHash
+  };
+}
+
 // src/client.ts
 var _tokenStore = /* @__PURE__ */ new WeakMap();
+var _additionalCredsStore = /* @__PURE__ */ new WeakMap();
 function _storeAccessToken(token, accessToken) {
   _tokenStore.set(token, accessToken);
 }
+function _storeAdditionalCredentials(token, creds) {
+  _additionalCredsStore.set(token, creds);
+}
 function _extractAccessToken(token) {
   const value = _tokenStore.get(token);
   if (value === void 0) {
@@ -359,10 +594,12 @@ function _extractAccessToken(token) {
   }
   return value;
 }
+function _extractAdditionalCredentials(token) {
+  return _additionalCredsStore.get(token);
+}
 var _fetch;
-var SDK_VERSION = "0.2.2";
+var SDK_VERSION = "0.4.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;
@@ -418,7 +655,9 @@ var HttpClient = class {
       headers: mergedHeaders,
       signal: controller.signal
     };
-    if (options?.json !== void 0) {
+    if (options?.body !== void 0) {
+      init.body = options.body;
+    } else if (options?.json !== void 0) {
       init.body = JSON.stringify(options.json);
       mergedHeaders["Content-Type"] = "application/json";
     }
@@ -442,6 +681,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) */
@@ -479,10 +720,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 = (0, import_node_crypto2.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;
@@ -535,14 +774,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.
@@ -569,6 +814,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 = (0, import_node_crypto2.createHash)("sha256").update(body ?? "").digest("hex");
+    const stringToSign = `${method.toUpperCase()}
+${path}
+${timestamp}
+${contentHash}`;
+    const signature = (0, import_node_crypto2.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.
    */
@@ -665,7 +932,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
       );
     }
@@ -711,22 +978,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, requestMetadata, 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,
-          request: requestMetadata ?? null
-        },
-        headers: actorHeaders
+      response = await this.#alterClient.post(tokenPath, {
+        json: tokenBody,
+        headers: { ...actorHeaders, ...hmacHeaders }
       });
     } catch (error) {
       if (_AlterVault.#isTimeoutOrAbortError(error)) {
@@ -743,7 +1012,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);
@@ -751,7 +1020,22 @@ 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);
+    if (typedData.additional_credentials) {
+      _storeAdditionalCredentials(tokenResponse, typedData.additional_credentials);
+    }
     return tokenResponse;
   }
   /**
@@ -779,10 +1063,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) {
@@ -848,13 +1135,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 ?? (0, import_node_crypto2.randomUUID)();
     const methodStr = String(method).toUpperCase();
     const urlLower = url.toLowerCase();
     if (!ALLOWED_URL_SCHEMES.some((scheme) => urlLower.startsWith(scheme))) {
@@ -862,7 +1149,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));
@@ -892,39 +1179,80 @@ var AlterVault = class _AlterVault {
         );
       }
     }
-    if (options.extraHeaders && "Authorization" in options.extraHeaders) {
-      console.warn(
-        "extraHeaders contains 'Authorization' which will be overwritten with the auto-injected Bearer token"
-      );
-    }
     const tokenResponse = await this.#getToken(
-      providerStr,
-      options.user,
-      options.reason,
+      connectionId,
+      options?.reason,
       { method: methodStr, url },
-      options.runId,
-      options.threadId,
-      options.toolCallId
+      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);
+    const injectionHeaderLower = tokenResponse.injectionHeader.toLowerCase();
+    const additionalCreds = _extractAdditionalCredentials(tokenResponse);
+    const isSigV4 = tokenResponse.injectionFormat.startsWith("AWS4-HMAC-SHA256") && additionalCreds != null;
+    let sigv4BodyStr = null;
+    if (isSigV4) {
+      const accessKeyId = accessToken;
+      if (options?.json != null) {
+        sigv4BodyStr = JSON.stringify(options.json);
+        if (!requestHeaders["Content-Type"]) {
+          requestHeaders["Content-Type"] = "application/json";
+        }
+      }
+      if (!additionalCreds.secret_key) {
+        throw new TokenRetrievalError(
+          "AWS SigV4 credential is missing secret_key in additional_credentials. Re-store the credential with both Access Key ID and Secret Access Key.",
+          { connection_id: connectionId }
+        );
+      }
+      const awsHeaders = signAwsRequest({
+        method: methodStr,
+        url,
+        headers: requestHeaders,
+        body: sigv4BodyStr,
+        accessKeyId,
+        secretKey: additionalCreds.secret_key,
+        region: additionalCreds.region ?? null,
+        service: additionalCreds.service ?? null
+      });
+      Object.assign(requestHeaders, awsHeaders);
+    } else {
+      if (options?.extraHeaders && Object.keys(options.extraHeaders).some(
+        (k) => k.toLowerCase() === injectionHeaderLower
+      )) {
+        console.warn(
+          `extraHeaders contains '${tokenResponse.injectionHeader}' which will be overwritten with the auto-injected credential`
+        );
+      }
+      requestHeaders[tokenResponse.injectionHeader] = tokenResponse.injectionFormat.replace("{token}", accessToken);
+    }
     if (!requestHeaders["User-Agent"]) {
       requestHeaders["User-Agent"] = SDK_USER_AGENT;
     }
     const startTime = Date.now();
     let response;
     try {
-      response = await this.#providerClient.request(methodStr, url, {
-        json: options.json,
-        headers: requestHeaders,
-        params: options.queryParams
-      });
+      if (isSigV4 && sigv4BodyStr != null) {
+        response = await this.#providerClient.request(methodStr, url, {
+          body: sigv4BodyStr,
+          headers: requestHeaders,
+          params: options?.queryParams
+        });
+      } else {
+        response = await this.#providerClient.request(methodStr, url, {
+          json: options?.json,
+          headers: requestHeaders,
+          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
           }
@@ -933,7 +1261,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)
@@ -941,9 +1269,11 @@ var AlterVault = class _AlterVault {
       );
     }
     const latencyMs = Date.now() - startTime;
+    const sigv4Sensitive = /* @__PURE__ */ new Set(["authorization", "x-amz-date", "x-amz-content-sha256"]);
+    const stripHeaders = isSigV4 ? sigv4Sensitive : /* @__PURE__ */ new Set([injectionHeaderLower]);
     const auditHeaders = {};
     for (const [key, value] of Object.entries(requestHeaders)) {
-      if (key.toLowerCase() !== "authorization") {
+      if (!stripHeaders.has(key.toLowerCase())) {
         auditHeaders[key] = value;
       }
     }
@@ -954,19 +1284,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(
@@ -974,7 +1304,7 @@ var AlterVault = class _AlterVault {
         response.status,
         responseBody,
         {
-          provider: providerStr,
+          connection_id: connectionId,
           method: methodStr,
           url
         }
@@ -996,14 +1326,17 @@ var AlterVault = class _AlterVault {
     }
     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("/oauth/connections/list", {
-        json: {
-          provider_id: options?.providerId ?? null,
-          limit: options?.limit ?? 100,
-          offset: options?.offset ?? 0
-        },
-        headers: actorHeaders
+      response = await this.#alterClient.post(listPath, {
+        json: listBody,
+        headers: { ...actorHeaders, ...listHmac }
       });
     } catch (error) {
       if (_AlterVault.#isTimeoutOrAbortError(error)) {
@@ -1054,17 +1387,19 @@ var AlterVault = class _AlterVault {
     }
     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("/oauth/connect/session", {
-        json: {
-          end_user: options.endUser,
-          attributes: options.attributes ?? null,
-          allowed_providers: options.allowedProviders ?? null,
-          return_url: options.returnUrl ?? null,
-          allowed_origin: options.allowedOrigin ?? null,
-          metadata: options.metadata ?? null
-        },
-        headers: actorHeaders
+      response = await this.#alterClient.post(sessionPath, {
+        json: sessionBody,
+        headers: { ...actorHeaders, ...sessionHmac }
       });
     } catch (error) {
       if (_AlterVault.#isTimeoutOrAbortError(error)) {
@@ -1088,6 +1423,132 @@ var AlterVault = class _AlterVault {
     const data = await response.json();
     return new ConnectSession(data);
   }
+  /**
+   * Open OAuth in the user's browser and wait for completion.
+   *
+   * This is the headless connect flow for CLI tools, scripts, and
+   * server-side applications. It creates a Connect session, opens the
+   * browser, and polls until the user completes OAuth.
+   *
+   * @param options - Connect options (endUser is required)
+   * @returns Array of ConnectResult objects (one per connected provider)
+   * @throws ConnectTimeoutError if the user doesn't complete within timeout
+   * @throws ConnectFlowError if the user denies or provider returns error
+   * @throws AlterSDKError if SDK is closed or session creation fails
+   */
+  async connect(options) {
+    if (this.#closed) {
+      throw new AlterSDKError(
+        "SDK instance has been closed. Create a new AlterVault instance to make requests."
+      );
+    }
+    const timeout = options.timeout ?? 300;
+    const pollInterval = options.pollInterval ?? 2;
+    const openBrowser = options.openBrowser ?? true;
+    const session = await this.createConnectSession({
+      endUser: options.endUser,
+      allowedProviders: options.providers
+    });
+    if (openBrowser) {
+      try {
+        const openModule = await import("open");
+        const openFn = openModule.default;
+        if (openFn) {
+          await openFn(session.connectUrl);
+        } else {
+          console.log(
+            `Open this URL to authorize: ${session.connectUrl}`
+          );
+        }
+      } catch {
+        console.log(
+          `Open this URL to authorize: ${session.connectUrl}`
+        );
+      }
+    } else {
+      console.log(
+        `Open this URL to authorize: ${session.connectUrl}`
+      );
+    }
+    const deadline = Date.now() + timeout * 1e3;
+    while (Date.now() < deadline) {
+      await new Promise(
+        (resolve) => setTimeout(resolve, pollInterval * 1e3)
+      );
+      const pollResult = await this.#pollSession(session.sessionToken);
+      const pollStatus = pollResult.status;
+      if (pollStatus === "completed") {
+        const connectionsData = pollResult.connections ?? [];
+        return connectionsData.map(
+          (conn) => new ConnectResult({
+            connection_id: conn.connection_id ?? "",
+            provider_id: conn.provider_id ?? "",
+            account_identifier: conn.account_identifier ?? null,
+            scopes: conn.scopes ?? []
+          })
+        );
+      }
+      if (pollStatus === "error") {
+        const err = pollResult.error;
+        throw new ConnectFlowError(
+          err?.error_message ?? "OAuth flow failed",
+          {
+            error_code: err?.error_code ?? "unknown_error"
+          }
+        );
+      }
+      if (pollStatus === "expired") {
+        throw new ConnectFlowError(
+          "Connect session expired before OAuth was completed"
+        );
+      }
+    }
+    throw new ConnectTimeoutError(
+      `OAuth flow did not complete within ${timeout} seconds. The user may not have finished authorizing in the browser.`,
+      { timeout }
+    );
+  }
+  /**
+   * Poll the Connect session for completion status (INTERNAL).
+   *
+   * Makes an HMAC-signed POST to the poll endpoint.
+   */
+  async #pollSession(sessionToken) {
+    const actorHeaders = this.#getActorRequestHeaders();
+    const pollPath = "/sdk/oauth/connect/session/poll";
+    const pollBody = { session_token: sessionToken };
+    const pollHmac = this.#computeHmacHeaders(
+      "POST",
+      pollPath,
+      JSON.stringify(pollBody)
+    );
+    let response;
+    try {
+      response = await this.#alterClient.post(pollPath, {
+        json: pollBody,
+        headers: { ...actorHeaders, ...pollHmac }
+      });
+    } 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 poll connect session: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+    this.#cacheActorIdFromResponse(response);
+    await this.#handleErrorResponse(response);
+    return await response.json();
+  }
   /**
    * Close HTTP clients and release resources.
    * Waits for any pending audit tasks before closing.
@@ -1116,8 +1577,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 || {});
@@ -1134,9 +1593,13 @@ var HttpMethod = /* @__PURE__ */ ((HttpMethod2) => {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   APICallAuditLog,
+  ActorType,
   AlterSDKError,
   AlterVault,
+  ConnectFlowError,
+  ConnectResult,
   ConnectSession,
+  ConnectTimeoutError,
   ConnectionInfo,
   ConnectionListResult,
   ConnectionNotFoundError,