@alter-ai/alter-sdk 0.3.1 → 0.5.0

package/dist/index.js

@@ -1,5 +1,5 @@
 // src/client.ts
-import { createHash, createHmac, randomUUID } from "crypto";
+import { createHash as createHash2, createHmac as createHmac2, randomUUID } from "crypto";
 
 // src/exceptions.ts
 var AlterSDKError = class extends Error {
@@ -17,13 +17,45 @@ var AlterSDKError = class extends Error {
     return this.message;
   }
 };
-var TokenRetrievalError = class extends AlterSDKError {
+var BackendError = class extends AlterSDKError {
   constructor(message, details) {
     super(message, details);
-    this.name = "TokenRetrievalError";
+    this.name = "BackendError";
   }
 };
-var PolicyViolationError = class extends TokenRetrievalError {
+var ReAuthRequiredError = class extends BackendError {
+  constructor(message, details) {
+    super(message, details);
+    this.name = "ReAuthRequiredError";
+  }
+};
+var ConnectionExpiredError = class extends ReAuthRequiredError {
+  constructor(message, details) {
+    super(message, details);
+    this.name = "ConnectionExpiredError";
+  }
+};
+var ConnectionRevokedError = class extends ReAuthRequiredError {
+  connectionId;
+  constructor(message, connectionId, details) {
+    super(message, details);
+    this.name = "ConnectionRevokedError";
+    this.connectionId = connectionId;
+  }
+};
+var ConnectionDeletedError = class extends ReAuthRequiredError {
+  constructor(message, details) {
+    super(message, details);
+    this.name = "ConnectionDeletedError";
+  }
+};
+var ConnectionNotFoundError = class extends BackendError {
+  constructor(message, details) {
+    super(message, details);
+    this.name = "ConnectionNotFoundError";
+  }
+};
+var PolicyViolationError = class extends BackendError {
   policyError;
   constructor(message, policyError, details) {
     super(message, details);
@@ -31,18 +63,28 @@ var PolicyViolationError = class extends TokenRetrievalError {
     this.policyError = policyError;
   }
 };
-var ConnectionNotFoundError = class extends TokenRetrievalError {
+var ConnectFlowError = class extends AlterSDKError {
   constructor(message, details) {
     super(message, details);
-    this.name = "ConnectionNotFoundError";
+    this.name = "ConnectFlowError";
   }
 };
-var TokenExpiredError = class extends TokenRetrievalError {
-  connectionId;
-  constructor(message, connectionId, details) {
+var ConnectDeniedError = class extends ConnectFlowError {
+  constructor(message, details) {
     super(message, details);
-    this.name = "TokenExpiredError";
-    this.connectionId = connectionId;
+    this.name = "ConnectDeniedError";
+  }
+};
+var ConnectConfigError = class extends ConnectFlowError {
+  constructor(message, details) {
+    super(message, details);
+    this.name = "ConnectConfigError";
+  }
+};
+var ConnectTimeoutError = class extends ConnectFlowError {
+  constructor(message, details) {
+    super(message, details);
+    this.name = "ConnectTimeoutError";
   }
 };
 var ProviderAPIError = class extends AlterSDKError {
@@ -55,6 +97,16 @@ var ProviderAPIError = class extends AlterSDKError {
     this.responseBody = responseBody;
   }
 };
+var ScopeReauthRequiredError = class extends ProviderAPIError {
+  connectionId;
+  providerId;
+  constructor(message, connectionId, providerId, statusCode, responseBody, details) {
+    super(message, statusCode, responseBody, details);
+    this.name = "ScopeReauthRequiredError";
+    this.connectionId = connectionId;
+    this.providerId = providerId;
+  }
+};
 var NetworkError = class extends AlterSDKError {
   constructor(message, details) {
     super(message, details);
@@ -92,6 +144,10 @@ var TokenResponse = class _TokenResponse {
   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;
+  /** Additional injection rules for multi-header or query param auth */
+  additionalInjections;
   constructor(data) {
     this.tokenType = data.token_type ?? "Bearer";
     this.expiresIn = data.expires_in ?? null;
@@ -101,6 +157,13 @@ var TokenResponse = class _TokenResponse {
     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;
+    }
+    this.additionalInjections = data.additional_injections ?? null;
     Object.freeze(this);
   }
   /**
@@ -169,6 +232,7 @@ var ConnectionInfo = class {
   accountIdentifier;
   accountDisplayName;
   status;
+  scopeMismatch;
   expiresAt;
   createdAt;
   lastUsedAt;
@@ -179,6 +243,7 @@ var ConnectionInfo = class {
     this.accountIdentifier = data.account_identifier ?? null;
     this.accountDisplayName = data.account_display_name ?? null;
     this.status = data.status;
+    this.scopeMismatch = data.scope_mismatch ?? false;
     this.expiresAt = data.expires_at ?? null;
     this.createdAt = data.created_at;
     this.lastUsedAt = data.last_used_at ?? null;
@@ -192,6 +257,7 @@ var ConnectionInfo = class {
       account_identifier: this.accountIdentifier,
       account_display_name: this.accountDisplayName,
       status: this.status,
+      scope_mismatch: this.scopeMismatch,
       expires_at: this.expiresAt,
       created_at: this.createdAt,
       last_used_at: this.lastUsedAt
@@ -240,12 +306,41 @@ var ConnectionListResult = class {
     Object.freeze(this);
   }
 };
+var ConnectResult = class {
+  connectionId;
+  providerId;
+  accountIdentifier;
+  scopes;
+  connectionPolicy;
+  constructor(data) {
+    this.connectionId = data.connection_id;
+    this.providerId = data.provider_id;
+    this.accountIdentifier = data.account_identifier ?? null;
+    this.scopes = data.scopes ?? [];
+    this.connectionPolicy = data.connection_policy ?? null;
+    Object.freeze(this);
+  }
+  toJSON() {
+    return {
+      connection_id: this.connectionId,
+      provider_id: this.providerId,
+      account_identifier: this.accountIdentifier,
+      scopes: this.scopes,
+      connection_policy: this.connectionPolicy
+    };
+  }
+  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;
@@ -319,11 +414,171 @@ var APICallAuditLog = class {
   }
 };
 
+// src/aws-sig-v4.ts
+import { createHash, createHmac } from "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 createHmac("sha256", key).update(message, "utf8").digest();
+}
+function sha256Hex(data) {
+  const hash = 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 = 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) {
@@ -333,11 +588,15 @@ function _extractAccessToken(token) {
   }
   return value;
 }
+function _extractAdditionalCredentials(token) {
+  return _additionalCredsStore.get(token);
+}
 var _fetch;
-var SDK_VERSION = "0.3.0";
+var SDK_VERSION = "0.5.0";
 var SDK_USER_AGENT = `alter-sdk-node/${SDK_VERSION}`;
 var HTTP_FORBIDDEN = 403;
 var HTTP_NOT_FOUND = 404;
+var HTTP_GONE = 410;
 var HTTP_BAD_REQUEST = 400;
 var HTTP_UNAUTHORIZED = 401;
 var HTTP_BAD_GATEWAY = 502;
@@ -391,7 +650,12 @@ var HttpClient = class {
       headers: mergedHeaders,
       signal: controller.signal
     };
-    if (options?.json !== void 0) {
+    if (options?.body !== void 0) {
+      init.body = options.body;
+      if (!mergedHeaders["Content-Type"]) {
+        mergedHeaders["Content-Type"] = "application/json";
+      }
+    } else if (options?.json !== void 0) {
       init.body = JSON.stringify(options.json);
       mergedHeaders["Content-Type"] = "application/json";
     }
@@ -427,6 +691,8 @@ var AlterVault = class _AlterVault {
   #closed = false;
   /** Pending audit log promises (fire-and-forget) */
   #auditPromises = /* @__PURE__ */ new Set();
+  /** JWT identity resolution: callable that returns user token */
+  #userTokenGetter = null;
   // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   // Public readonly properties (frozen by Object.freeze)
   // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -454,7 +720,7 @@ var AlterVault = class _AlterVault {
     for (const [name, value] of actorStrings) {
       _AlterVault.#validateActorString(value, name);
     }
-    this.#hmacKey = createHmac("sha256", options.apiKey).update("alter-signing-v1").digest();
+    this.#hmacKey = createHmac2("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;
@@ -462,6 +728,7 @@ var AlterVault = class _AlterVault {
     this.#actorName = options.actorName;
     this.#actorVersion = options.actorVersion;
     this.#clientType = options.clientType;
+    this.#userTokenGetter = options.userTokenGetter ?? null;
     this.#framework = options.framework;
     if (!_fetch) {
       _fetch = globalThis.fetch;
@@ -558,12 +825,12 @@ var AlterVault = class _AlterVault {
    */
   #computeHmacHeaders(method, path, body) {
     const timestamp = String(Math.floor(Date.now() / 1e3));
-    const contentHash = createHash("sha256").update(body ?? "").digest("hex");
+    const contentHash = createHash2("sha256").update(body ?? "").digest("hex");
     const stringToSign = `${method.toUpperCase()}
 ${path}
 ${timestamp}
 ${contentHash}`;
-    const signature = createHmac("sha256", this.#hmacKey).update(stringToSign).digest("hex");
+    const signature = createHmac2("sha256", this.#hmacKey).update(stringToSign).digest("hex");
     return {
       "X-Alter-Timestamp": timestamp,
       "X-Alter-Content-SHA256": contentHash,
@@ -636,6 +903,24 @@ ${contentHash}`;
     }
     return false;
   }
+  /**
+   * Resolve a value_source to the actual value for injection.
+   *
+   * @param valueSource - "token" or "additional_credentials.<field>"
+   * @param accessToken - The main credential value
+   * @param additionalCreds - Additional credentials from vault
+   * @returns The resolved value, or null if not available
+   */
+  static #resolveInjectionValue(valueSource, accessToken, additionalCreds) {
+    if (valueSource === "token") {
+      return accessToken;
+    }
+    if (valueSource.startsWith("additional_credentials.")) {
+      const field = valueSource.slice("additional_credentials.".length);
+      return additionalCreds?.[field] ?? null;
+    }
+    return null;
+  }
   static async #safeParseJson(response) {
     try {
       return await response.clone().json();
@@ -657,12 +942,25 @@ ${contentHash}`;
     }
     if (response.status === HTTP_FORBIDDEN) {
       const errorData = await _AlterVault.#safeParseJson(response);
+      if (errorData.error === "connection_expired") {
+        throw new ConnectionExpiredError(
+          errorData.message ?? "Connection expired per TTL policy",
+          errorData.details
+        );
+      }
       throw new PolicyViolationError(
         errorData.message ?? "Access denied by policy",
         errorData.error,
         errorData.details
       );
     }
+    if (response.status === HTTP_GONE) {
+      const errorData = await _AlterVault.#safeParseJson(response);
+      throw new ConnectionDeletedError(
+        errorData.message ?? "Connection has been deleted. A new connection_id will be issued on re-authorization.",
+        errorData
+      );
+    }
     if (response.status === HTTP_NOT_FOUND) {
       const errorData = await _AlterVault.#safeParseJson(response);
       throw new ConnectionNotFoundError(
@@ -672,35 +970,35 @@ ${contentHash}`;
     }
     if (response.status === HTTP_BAD_REQUEST || response.status === HTTP_BAD_GATEWAY) {
       const errorData = await _AlterVault.#safeParseJson(response);
-      if (JSON.stringify(errorData).toLowerCase().includes("token_expired")) {
-        throw new TokenExpiredError(
-          errorData.message ?? "Token expired and refresh failed",
+      if (errorData.error === "connection_revoked") {
+        throw new ConnectionRevokedError(
+          errorData.message ?? "Connection has been revoked. User must re-authorize.",
           errorData.connection_id,
           errorData
         );
       }
-      throw new TokenRetrievalError(
+      throw new BackendError(
         errorData.message ?? `Backend error ${response.status}`,
         errorData
       );
     }
     if (response.status === HTTP_UNAUTHORIZED) {
       const errorData = await _AlterVault.#safeParseJson(response);
-      throw new TokenRetrievalError(
+      throw new BackendError(
         errorData.message ?? "Unauthorized \u2014 check your API key",
         errorData
       );
     }
     if (response.status === HTTP_INTERNAL_SERVER_ERROR || response.status === HTTP_SERVICE_UNAVAILABLE) {
       const errorData = await _AlterVault.#safeParseJson(response);
-      throw new TokenRetrievalError(
+      throw new BackendError(
         errorData.message ?? `Backend unavailable (HTTP ${response.status})`,
         errorData
       );
     }
     if (response.status >= HTTP_CLIENT_ERROR_START) {
       const errorData = await _AlterVault.#safeParseJson(response);
-      throw new TokenRetrievalError(
+      throw new BackendError(
         errorData.message ?? `Unexpected backend error (HTTP ${response.status})`,
         errorData
       );
@@ -712,24 +1010,52 @@ ${contentHash}`;
    * This is a private method. Tokens are NEVER exposed to developers.
    * Use request() instead, which handles tokens internally.
    */
-  async #getToken(connectionId, reason, requestMetadata, runId, threadId, toolCallId) {
+  async #getUserToken() {
+    if (!this.#userTokenGetter) {
+      throw new AlterSDKError(
+        "userTokenGetter is required for provider-based resolution. Pass userTokenGetter to AlterVault constructor."
+      );
+    }
+    const result = this.#userTokenGetter();
+    const token = result instanceof Promise ? await result : result;
+    if (!token || typeof token !== "string") {
+      throw new AlterSDKError("userTokenGetter must return a non-empty string");
+    }
+    return token;
+  }
+  async #getToken(connectionId, reason, requestMetadata, runId, threadId, toolCallId, provider, account) {
     const actorHeaders = this.#getActorRequestHeaders(
       runId,
       threadId,
       toolCallId
     );
     let response;
-    const tokenBody = {
-      connection_id: connectionId,
-      reason: reason ?? null,
-      request: requestMetadata ?? null
-    };
+    let tokenBody;
+    if (provider) {
+      const userToken = await this.#getUserToken();
+      tokenBody = {
+        provider_id: provider,
+        user_token: userToken,
+        reason: reason ?? null,
+        request: requestMetadata ?? null
+      };
+      if (account) {
+        tokenBody.account = account;
+      }
+    } else {
+      tokenBody = {
+        connection_id: connectionId,
+        reason: reason ?? null,
+        request: requestMetadata ?? null
+      };
+    }
     const tokenPath = "/sdk/token";
-    const hmacHeaders = this.#computeHmacHeaders("POST", tokenPath, JSON.stringify(tokenBody));
+    const tokenBodyStr = JSON.stringify(tokenBody);
+    const hmacHeaders = this.#computeHmacHeaders("POST", tokenPath, tokenBodyStr);
     try {
       response = await this.#alterClient.post(tokenPath, {
-        json: tokenBody,
-        headers: { ...actorHeaders, ...hmacHeaders }
+        body: tokenBodyStr,
+        headers: { ...actorHeaders, ...hmacHeaders, "Content-Type": "application/json" }
       });
     } catch (error) {
       if (_AlterVault.#isTimeoutOrAbortError(error)) {
@@ -744,7 +1070,7 @@ ${contentHash}`;
           { base_url: this.baseUrl }
         );
       }
-      throw new TokenRetrievalError(
+      throw new BackendError(
         `Failed to retrieve token: ${error instanceof Error ? error.message : String(error)}`,
         { connection_id: connectionId, error: String(error) }
       );
@@ -753,21 +1079,25 @@ ${contentHash}`;
     await this.#handleErrorResponse(response);
     const tokenData = await response.json();
     const typedData = tokenData;
+    const scopeMismatch = typedData.scope_mismatch ?? false;
     const tokenResponse = new TokenResponse(typedData);
     if (!/^[A-Za-z][A-Za-z0-9-]*$/.test(tokenResponse.injectionHeader)) {
-      throw new TokenRetrievalError(
+      throw new BackendError(
         `Backend returned invalid injection_header: ${tokenResponse.injectionHeader}`,
         { connectionId: String(connectionId) }
       );
     }
     if (/[\r\n\x00]/.test(tokenResponse.injectionFormat)) {
-      throw new TokenRetrievalError(
+      throw new BackendError(
         `Backend returned invalid injection_format (contains control characters)`,
         { connectionId: String(connectionId) }
       );
     }
     _storeAccessToken(tokenResponse, typedData.access_token);
-    return tokenResponse;
+    if (typedData.additional_credentials) {
+      _storeAdditionalCredentials(tokenResponse, typedData.additional_credentials);
+    }
+    return { tokenResponse, scopeMismatch };
   }
   /**
    * Log an API call to the backend audit endpoint (INTERNAL).
@@ -797,10 +1127,11 @@ ${contentHash}`;
       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 auditBodyStr = JSON.stringify(auditBody);
+      const auditHmac = this.#computeHmacHeaders("POST", auditPath, auditBodyStr);
       const response = await this.#alterClient.post(auditPath, {
-        json: auditBody,
-        headers: { ...actorHeaders, ...auditHmac }
+        body: auditBodyStr,
+        headers: { ...actorHeaders, ...auditHmac, "Content-Type": "application/json" }
       });
       this.#cacheActorIdFromResponse(response);
       if (!response.ok) {
@@ -872,12 +1203,22 @@ ${contentHash}`;
         "SDK instance has been closed. Create a new AlterVault instance to make requests."
       );
     }
+    const provider = options?.provider;
+    const account = options?.account;
+    if (!connectionId && !provider) {
+      throw new AlterSDKError("Provide connectionId or options.provider");
+    }
+    if (connectionId && provider) {
+      throw new AlterSDKError("Cannot provide both connectionId and options.provider");
+    }
+    const effectiveConnectionId = connectionId ?? null;
+    let currentUrl = url;
     const runId = options?.runId ?? randomUUID();
     const methodStr = String(method).toUpperCase();
-    const urlLower = url.toLowerCase();
+    const urlLower = currentUrl.toLowerCase();
     if (!ALLOWED_URL_SCHEMES.some((scheme) => urlLower.startsWith(scheme))) {
       throw new AlterSDKError(
-        `URL must start with https:// or http://, got: ${url.slice(0, 50)}`
+        `URL must start with https:// or http://, got: ${currentUrl.slice(0, 50)}`
       );
     }
     if (options?.pathParams && Object.keys(options.pathParams).length > 0) {
@@ -886,7 +1227,7 @@ ${contentHash}`;
         encodedParams[key] = encodeURIComponent(String(value));
       }
       try {
-        let resolvedUrl = url;
+        let resolvedUrl = currentUrl;
         for (const [key, value] of Object.entries(encodedParams)) {
           const placeholder = `{${key}}`;
           if (!resolvedUrl.includes(placeholder)) {
@@ -897,74 +1238,142 @@ ${contentHash}`;
         const remaining = resolvedUrl.match(/\{(\w+)\}/);
         if (remaining) {
           throw new AlterSDKError(
-            `Invalid URL template or missing path_params: '${remaining[1]}'. URL: ${url}, path_params: ${JSON.stringify(options.pathParams)}`
+            `Invalid URL template or missing path_params: '${remaining[1]}'. URL: ${currentUrl}, path_params: ${JSON.stringify(options.pathParams)}`
           );
         }
-        url = resolvedUrl;
+        currentUrl = resolvedUrl;
       } catch (error) {
         if (error instanceof AlterSDKError) {
           throw error;
         }
         throw new AlterSDKError(
-          `Invalid URL template or missing path_params: ${error instanceof Error ? error.message : String(error)}. URL: ${url}, path_params: ${JSON.stringify(options.pathParams)}`
+          `Invalid URL template or missing path_params: ${error instanceof Error ? error.message : String(error)}. URL: ${currentUrl}, path_params: ${JSON.stringify(options.pathParams)}`
         );
       }
     }
-    const tokenResponse = await this.#getToken(
-      connectionId,
+    const { tokenResponse, scopeMismatch } = await this.#getToken(
+      effectiveConnectionId,
       options?.reason,
-      { method: methodStr, url },
+      { method: methodStr, url: currentUrl },
       runId,
       options?.threadId,
-      options?.toolCallId
+      options?.toolCallId,
+      provider,
+      account
     );
-    const injectionHeaderLower = tokenResponse.injectionHeader.toLowerCase();
-    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`
-      );
-    }
     const requestHeaders = options?.extraHeaders ? { ...options.extraHeaders } : {};
     const accessToken = _extractAccessToken(tokenResponse);
-    requestHeaders[tokenResponse.injectionHeader] = tokenResponse.injectionFormat.replace("{token}", accessToken);
+    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 BackendError(
+          "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: effectiveConnectionId }
+        );
+      }
+      const awsHeaders = signAwsRequest({
+        method: methodStr,
+        url: currentUrl,
+        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);
+    }
+    const auditUrl = currentUrl;
+    if (tokenResponse.additionalInjections && !isSigV4) {
+      for (const rule of tokenResponse.additionalInjections) {
+        const value = _AlterVault.#resolveInjectionValue(
+          rule.value_source,
+          accessToken,
+          additionalCreds
+        );
+        if (!value) continue;
+        if (!/^[A-Za-z][A-Za-z0-9\-_]*$/.test(rule.key)) continue;
+        if (rule.target === "header") {
+          requestHeaders[rule.key] = value;
+        } else if (rule.target === "query_param") {
+          const urlObj = new URL(currentUrl);
+          urlObj.searchParams.set(rule.key, value);
+          currentUrl = urlObj.toString();
+        }
+      }
+    }
     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, currentUrl, {
+          body: sigv4BodyStr,
+          headers: requestHeaders,
+          params: options?.queryParams
+        });
+      } else {
+        response = await this.#providerClient.request(methodStr, currentUrl, {
+          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)}`,
           {
-            connection_id: connectionId,
+            connection_id: effectiveConnectionId,
             method: methodStr,
-            url
+            url: currentUrl
           }
         );
       }
       throw new NetworkError(
         `Failed to call provider API: ${error instanceof Error ? error.message : String(error)}`,
         {
-          connection_id: connectionId,
+          connection_id: effectiveConnectionId,
           method: methodStr,
-          url,
+          url: currentUrl,
           error: String(error)
         }
       );
     }
     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]);
+    if (tokenResponse.additionalInjections && !isSigV4) {
+      for (const rule of tokenResponse.additionalInjections) {
+        if (rule.target === "header") {
+          stripHeaders.add(rule.key.toLowerCase());
+        }
+      }
+    }
     const auditHeaders = {};
     for (const [key, value] of Object.entries(requestHeaders)) {
-      if (key.toLowerCase() !== injectionHeaderLower) {
+      if (!stripHeaders.has(key.toLowerCase())) {
         auditHeaders[key] = value;
       }
     }
@@ -975,9 +1384,9 @@ ${contentHash}`;
     });
     this.#scheduleAuditLog({
       connectionId: tokenResponse.connectionId,
-      providerId: tokenResponse.providerId || connectionId,
+      providerId: tokenResponse.providerId || effectiveConnectionId || "",
       method: methodStr,
-      url,
+      url: auditUrl,
       requestHeaders: auditHeaders,
       requestBody: options?.json ?? null,
       responseStatus: response.status,
@@ -990,14 +1399,29 @@ ${contentHash}`;
       toolCallId: options?.toolCallId ?? null
     });
     if (response.status >= HTTP_CLIENT_ERROR_START) {
+      if (response.status === HTTP_FORBIDDEN && scopeMismatch) {
+        throw new ScopeReauthRequiredError(
+          "Provider API returned 403 and the connection's scopes don't match the provider config. The user needs to re-authorize to grant updated permissions.",
+          tokenResponse.connectionId,
+          tokenResponse.providerId,
+          response.status,
+          responseBody,
+          {
+            connection_id: tokenResponse.connectionId,
+            provider_id: tokenResponse.providerId,
+            method: methodStr,
+            url: currentUrl
+          }
+        );
+      }
       throw new ProviderAPIError(
         `Provider API returned error ${response.status}`,
         response.status,
         responseBody,
         {
-          connection_id: connectionId,
+          connection_id: effectiveConnectionId,
           method: methodStr,
-          url
+          url: currentUrl
         }
       );
     }
@@ -1022,12 +1446,23 @@ ${contentHash}`;
       limit: options?.limit ?? 100,
       offset: options?.offset ?? 0
     };
+    if (this.#userTokenGetter) {
+      try {
+        listBody.user_token = await this.#getUserToken();
+      } catch (err) {
+        console.warn(
+          "user_token_getter failed in listConnections, falling back to un-scoped listing:",
+          err instanceof Error ? err.message : String(err)
+        );
+      }
+    }
     const listPath = "/sdk/oauth/connections/list";
-    const listHmac = this.#computeHmacHeaders("POST", listPath, JSON.stringify(listBody));
+    const listBodyStr = JSON.stringify(listBody);
+    const listHmac = this.#computeHmacHeaders("POST", listPath, listBodyStr);
     try {
       response = await this.#alterClient.post(listPath, {
-        json: listBody,
-        headers: { ...actorHeaders, ...listHmac }
+        body: listBodyStr,
+        headers: { ...actorHeaders, ...listHmac, "Content-Type": "application/json" }
       });
     } catch (error) {
       if (_AlterVault.#isTimeoutOrAbortError(error)) {
@@ -1073,24 +1508,37 @@ ${contentHash}`;
         "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
     };
+    if (options.connectionPolicy) {
+      sessionBody.connection_policy = {
+        max_ttl_seconds: options.connectionPolicy.maxTtlSeconds ?? null,
+        default_ttl_seconds: options.connectionPolicy.defaultTtlSeconds ?? null
+      };
+    }
+    if (this.#userTokenGetter) {
+      try {
+        sessionBody.user_token = await this.#getUserToken();
+      } catch (err) {
+        console.warn(
+          "userTokenGetter failed in createConnectSession, session will not have identity tagging:",
+          err instanceof Error ? err.message : String(err)
+        );
+      }
+    }
     const sessionPath = "/sdk/oauth/connect/session";
-    const sessionHmac = this.#computeHmacHeaders("POST", sessionPath, JSON.stringify(sessionBody));
+    const sessionBodyStr = JSON.stringify(sessionBody);
+    const sessionHmac = this.#computeHmacHeaders("POST", sessionPath, sessionBodyStr);
     try {
       response = await this.#alterClient.post(sessionPath, {
-        json: sessionBody,
-        headers: { ...actorHeaders, ...sessionHmac }
+        body: sessionBodyStr,
+        headers: { ...actorHeaders, ...sessionHmac, "Content-Type": "application/json" }
       });
     } catch (error) {
       if (_AlterVault.#isTimeoutOrAbortError(error)) {
@@ -1114,6 +1562,143 @@ ${contentHash}`;
     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
+   * @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({
+      allowedProviders: options.providers,
+      connectionPolicy: options.connectionPolicy
+    });
+    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 ?? [],
+            connection_policy: conn.connection_policy ?? null
+          })
+        );
+      }
+      if (pollStatus === "error") {
+        const err = pollResult.error;
+        const errorCode = err?.error_code ?? "unknown_error";
+        const errorMessage = err?.error_message ?? "OAuth flow failed";
+        const errorDetails = { error_code: errorCode };
+        if (errorCode === "connect_denied") {
+          throw new ConnectDeniedError(errorMessage, errorDetails);
+        }
+        if ([
+          "connect_config_error",
+          "invalid_redirect_uri",
+          "invalid_client",
+          "unauthorized_client"
+        ].includes(errorCode)) {
+          throw new ConnectConfigError(errorMessage, errorDetails);
+        }
+        throw new ConnectFlowError(errorMessage, errorDetails);
+      }
+      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 pollBodyStr = JSON.stringify(pollBody);
+    const pollHmac = this.#computeHmacHeaders(
+      "POST",
+      pollPath,
+      pollBodyStr
+    );
+    let response;
+    try {
+      response = await this.#alterClient.post(pollPath, {
+        body: pollBodyStr,
+        headers: { ...actorHeaders, ...pollHmac, "Content-Type": "application/json" }
+      });
+    } 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.
@@ -1139,10 +1724,72 @@ Object.freeze(AlterVault.prototype);
 
 // src/providers/enums.ts
 var Provider = /* @__PURE__ */ ((Provider2) => {
-  Provider2["GOOGLE"] = "google";
+  Provider2["ACUITY_SCHEDULING"] = "acuity-scheduling";
+  Provider2["ADOBE"] = "adobe";
+  Provider2["AIRCALL"] = "aircall";
+  Provider2["AIRTABLE"] = "airtable";
+  Provider2["APOLLO"] = "apollo";
+  Provider2["ASANA"] = "asana";
+  Provider2["ATLASSIAN"] = "atlassian";
+  Provider2["ATTIO"] = "attio";
+  Provider2["AUTODESK"] = "autodesk";
+  Provider2["BASECAMP"] = "basecamp";
+  Provider2["BITBUCKET"] = "bitbucket";
+  Provider2["BITLY"] = "bitly";
+  Provider2["BOX"] = "box";
+  Provider2["BREX"] = "brex";
+  Provider2["CALENDLY"] = "calendly";
+  Provider2["CAL_COM"] = "cal-com";
+  Provider2["CANVA"] = "canva";
+  Provider2["CLICKUP"] = "clickup";
+  Provider2["CLOSE"] = "close";
+  Provider2["CONSTANT_CONTACT"] = "constant-contact";
+  Provider2["CONTENTFUL"] = "contentful";
+  Provider2["DEEL"] = "deel";
+  Provider2["DIALPAD"] = "dialpad";
+  Provider2["DIGITALOCEAN"] = "digitalocean";
+  Provider2["DISCORD"] = "discord";
+  Provider2["DOCUSIGN"] = "docusign";
+  Provider2["DROPBOX"] = "dropbox";
+  Provider2["EBAY"] = "ebay";
+  Provider2["EVENTBRITE"] = "eventbrite";
+  Provider2["FACEBOOK"] = "facebook";
+  Provider2["FIGMA"] = "figma";
   Provider2["GITHUB"] = "github";
-  Provider2["SLACK"] = "slack";
+  Provider2["GOOGLE"] = "google";
+  Provider2["HUBSPOT"] = "hubspot";
+  Provider2["INSTAGRAM"] = "instagram";
+  Provider2["LINEAR"] = "linear";
+  Provider2["LINKEDIN"] = "linkedin";
+  Provider2["MAILCHIMP"] = "mailchimp";
+  Provider2["MERCURY"] = "mercury";
+  Provider2["MICROSOFT"] = "microsoft";
+  Provider2["MIRO"] = "miro";
+  Provider2["MONDAY"] = "monday";
+  Provider2["NOTION"] = "notion";
+  Provider2["OUTREACH"] = "outreach";
+  Provider2["PAGERDUTY"] = "pagerduty";
+  Provider2["PAYPAL"] = "paypal";
+  Provider2["PINTEREST"] = "pinterest";
+  Provider2["PIPEDRIVE"] = "pipedrive";
+  Provider2["QUICKBOOKS"] = "quickbooks";
+  Provider2["RAMP"] = "ramp";
+  Provider2["REDDIT"] = "reddit";
+  Provider2["RINGCENTRAL"] = "ringcentral";
+  Provider2["SALESFORCE"] = "salesforce";
   Provider2["SENTRY"] = "sentry";
+  Provider2["SLACK"] = "slack";
+  Provider2["SNAPCHAT"] = "snapchat";
+  Provider2["SPOTIFY"] = "spotify";
+  Provider2["SQUARE"] = "square";
+  Provider2["SQUARESPACE"] = "squarespace";
+  Provider2["STRIPE"] = "stripe";
+  Provider2["TIKTOK"] = "tiktok";
+  Provider2["TODOIST"] = "todoist";
+  Provider2["TWITTER"] = "twitter";
+  Provider2["TYPEFORM"] = "typeform";
+  Provider2["WEBEX"] = "webex";
+  Provider2["WEBFLOW"] = "webflow";
   return Provider2;
 })(Provider || {});
 var HttpMethod = /* @__PURE__ */ ((HttpMethod2) => {
@@ -1160,17 +1807,26 @@ export {
   ActorType,
   AlterSDKError,
   AlterVault,
+  BackendError,
+  ConnectConfigError,
+  ConnectDeniedError,
+  ConnectFlowError,
+  ConnectResult,
   ConnectSession,
+  ConnectTimeoutError,
+  ConnectionDeletedError,
+  ConnectionExpiredError,
   ConnectionInfo,
   ConnectionListResult,
   ConnectionNotFoundError,
+  ConnectionRevokedError,
   HttpMethod,
   NetworkError,
   PolicyViolationError,
   Provider,
   ProviderAPIError,
+  ReAuthRequiredError,
+  ScopeReauthRequiredError,
   TimeoutError,
-  TokenExpiredError,
-  TokenResponse,
-  TokenRetrievalError
+  TokenResponse
 };