@alter-ai/alter-sdk 0.4.0 → 0.6.0

package/dist/index.cjs

@@ -34,22 +34,28 @@ __export(index_exports, {
   ActorType: () => ActorType,
   AlterSDKError: () => AlterSDKError,
   AlterVault: () => AlterVault,
+  BackendError: () => BackendError,
+  ConnectConfigError: () => ConnectConfigError,
+  ConnectDeniedError: () => ConnectDeniedError,
   ConnectFlowError: () => ConnectFlowError,
   ConnectResult: () => ConnectResult,
   ConnectSession: () => ConnectSession,
   ConnectTimeoutError: () => ConnectTimeoutError,
+  ConnectionDeletedError: () => ConnectionDeletedError,
+  ConnectionExpiredError: () => ConnectionExpiredError,
   ConnectionInfo: () => ConnectionInfo,
   ConnectionListResult: () => ConnectionListResult,
   ConnectionNotFoundError: () => ConnectionNotFoundError,
+  ConnectionRevokedError: () => ConnectionRevokedError,
   HttpMethod: () => HttpMethod,
   NetworkError: () => NetworkError,
   PolicyViolationError: () => PolicyViolationError,
   Provider: () => Provider,
   ProviderAPIError: () => ProviderAPIError,
+  ReAuthRequiredError: () => ReAuthRequiredError,
+  ScopeReauthRequiredError: () => ScopeReauthRequiredError,
   TimeoutError: () => TimeoutError,
-  TokenExpiredError: () => TokenExpiredError,
-  TokenResponse: () => TokenResponse,
-  TokenRetrievalError: () => TokenRetrievalError
+  TokenResponse: () => TokenResponse
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -72,40 +78,70 @@ 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 {
-  policyError;
-  constructor(message, policyError, details) {
+var ReAuthRequiredError = class extends BackendError {
+  constructor(message, details) {
     super(message, details);
-    this.name = "PolicyViolationError";
-    this.policyError = policyError;
+    this.name = "ReAuthRequiredError";
   }
 };
-var ConnectionNotFoundError = class extends TokenRetrievalError {
+var ConnectionExpiredError = class extends ReAuthRequiredError {
   constructor(message, details) {
     super(message, details);
-    this.name = "ConnectionNotFoundError";
+    this.name = "ConnectionExpiredError";
   }
 };
-var TokenExpiredError = class extends TokenRetrievalError {
+var ConnectionRevokedError = class extends ReAuthRequiredError {
   connectionId;
   constructor(message, connectionId, details) {
     super(message, details);
-    this.name = "TokenExpiredError";
+    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);
+    this.name = "PolicyViolationError";
+    this.policyError = policyError;
+  }
+};
 var ConnectFlowError = class extends AlterSDKError {
   constructor(message, details) {
     super(message, details);
     this.name = "ConnectFlowError";
   }
 };
+var ConnectDeniedError = class extends ConnectFlowError {
+  constructor(message, details) {
+    super(message, details);
+    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);
@@ -122,6 +158,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);
@@ -161,6 +207,8 @@ var TokenResponse = class _TokenResponse {
   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;
@@ -176,6 +224,7 @@ var TokenResponse = class _TokenResponse {
     } else {
       this.additionalCredentials = null;
     }
+    this.additionalInjections = data.additional_injections ?? null;
     Object.freeze(this);
   }
   /**
@@ -221,7 +270,8 @@ var TokenResponse = class _TokenResponse {
       expires_in: this.expiresIn,
       expires_at: this.expiresAt?.toISOString() ?? null,
       scopes: this.scopes,
-      connection_id: this.connectionId
+      connection_id: this.connectionId,
+      provider_id: this.providerId
     };
   }
   /**
@@ -238,22 +288,24 @@ var TokenResponse = class _TokenResponse {
   }
 };
 var ConnectionInfo = class {
-  id;
+  connectionId;
   providerId;
   scopes;
   accountIdentifier;
   accountDisplayName;
   status;
+  scopeMismatch;
   expiresAt;
   createdAt;
   lastUsedAt;
   constructor(data) {
-    this.id = data.id;
+    this.connectionId = data.connection_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.scopeMismatch = data.scope_mismatch ?? false;
     this.expiresAt = data.expires_at ?? null;
     this.createdAt = data.created_at;
     this.lastUsedAt = data.last_used_at ?? null;
@@ -261,19 +313,20 @@ var ConnectionInfo = class {
   }
   toJSON() {
     return {
-      id: this.id,
+      connection_id: this.connectionId,
       provider_id: this.providerId,
       scopes: this.scopes,
       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
     };
   }
   toString() {
-    return `ConnectionInfo(id=${this.id}, provider=${this.providerId}, status=${this.status})`;
+    return `ConnectionInfo(connection_id=${this.connectionId}, provider=${this.providerId}, status=${this.status})`;
   }
 };
 var ConnectSession = class {
@@ -320,11 +373,23 @@ var ConnectResult = class {
   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 ?? [];
+    const rawPolicy = data.connection_policy;
+    if (rawPolicy) {
+      const raw = rawPolicy;
+      this.connectionPolicy = Object.freeze({
+        expiresAt: raw["expires_at"] !== void 0 ? raw["expires_at"] : rawPolicy.expiresAt ?? null,
+        createdBy: raw["created_by"] !== void 0 ? raw["created_by"] : rawPolicy.createdBy ?? null,
+        createdAt: raw["created_at"] !== void 0 ? raw["created_at"] : rawPolicy.createdAt ?? null
+      });
+    } else {
+      this.connectionPolicy = null;
+    }
     Object.freeze(this);
   }
   toJSON() {
@@ -332,7 +397,12 @@ var ConnectResult = class {
       connection_id: this.connectionId,
       provider_id: this.providerId,
       account_identifier: this.accountIdentifier,
-      scopes: this.scopes
+      scopes: this.scopes,
+      connection_policy: this.connectionPolicy ? {
+        expires_at: this.connectionPolicy.expiresAt ?? null,
+        created_by: this.connectionPolicy.createdBy ?? null,
+        created_at: this.connectionPolicy.createdAt ?? null
+      } : null
     };
   }
   toString() {
@@ -346,7 +416,8 @@ var SENSITIVE_HEADERS = /* @__PURE__ */ new Set([
   "x-api-key",
   "x-auth-token",
   "x-amz-date",
-  "x-amz-content-sha256"
+  "x-amz-content-sha256",
+  "x-amz-security-token"
 ]);
 var APICallAuditLog = class {
   connectionId;
@@ -425,6 +496,7 @@ 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$/;
+var VPCE_HOST_RE = /^vpce-[a-z0-9-]+\.(?<service>[a-z0-9-]+)\.(?<region>[a-z]{2}(?:-[a-z0-9]+)+-\d+)\.vpce\.amazonaws\.com$/;
 function hmacSha256(key, message) {
   return (0, import_node_crypto.createHmac)("sha256", key).update(message, "utf8").digest();
 }
@@ -447,6 +519,10 @@ function detectServiceAndRegion(hostname) {
   if (s3m?.groups) {
     return { service: "s3", region: s3m.groups.region };
   }
+  const vpcem = VPCE_HOST_RE.exec(lower);
+  if (vpcem?.groups) {
+    return { service: vpcem.groups.service, region: vpcem.groups.region };
+  }
   return { service: null, region: null };
 }
 function deriveSigningKey(secretKey, dateStamp, region, service) {
@@ -481,18 +557,21 @@ function canonicalQueryString(query) {
       ]);
     }
   }
-  sorted.sort((a, b) => {
+  const sigv4Encode = (s) => encodeURIComponent(s).replace(
+    /[!'()*]/g,
+    (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`
+  );
+  const encoded = sorted.map(
+    ([k, v]) => [sigv4Encode(k), sigv4Encode(v)]
+  );
+  encoded.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("&");
+  return encoded.map(([k, v]) => `${k}=${v}`).join("&");
 }
 function canonicalHeadersAndSigned(headers) {
   const canonical = {};
@@ -511,11 +590,9 @@ 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;
-  }
+  const detected = detectServiceAndRegion(hostname);
+  if (detected.region != null) region = detected.region;
+  if (detected.service != null) service = detected.service;
   if (!region) {
     throw new Error(
       `Cannot determine AWS region from URL '${opts.url}'. Pass region explicitly via additional_credentials.`
@@ -598,10 +675,11 @@ function _extractAdditionalCredentials(token) {
   return _additionalCredsStore.get(token);
 }
 var _fetch;
-var SDK_VERSION = "0.4.0";
+var SDK_VERSION = "0.6.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;
@@ -657,6 +735,9 @@ var HttpClient = class {
     };
     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";
@@ -693,6 +774,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)
   // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -728,6 +811,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;
@@ -902,6 +986,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();
@@ -923,12 +1025,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(
@@ -938,35 +1053,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
       );
@@ -978,24 +1093,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)) {
@@ -1010,7 +1153,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) }
       );
@@ -1019,15 +1162,16 @@ ${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) }
       );
@@ -1036,7 +1180,7 @@ ${contentHash}`;
     if (typedData.additional_credentials) {
       _storeAdditionalCredentials(tokenResponse, typedData.additional_credentials);
     }
-    return tokenResponse;
+    return { tokenResponse, scopeMismatch };
   }
   /**
    * Log an API call to the backend audit endpoint (INTERNAL).
@@ -1066,10 +1210,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) {
@@ -1141,12 +1286,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 ?? (0, import_node_crypto2.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) {
@@ -1155,7 +1310,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)) {
@@ -1166,26 +1321,28 @@ ${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 requestHeaders = options?.extraHeaders ? { ...options.extraHeaders } : {};
     const accessToken = _extractAccessToken(tokenResponse);
@@ -1202,14 +1359,14 @@ ${contentHash}`;
         }
       }
       if (!additionalCreds.secret_key) {
-        throw new TokenRetrievalError(
+        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: connectionId }
+          { connection_id: effectiveConnectionId }
         );
       }
       const awsHeaders = signAwsRequest({
         method: methodStr,
-        url,
+        url: currentUrl,
         headers: requestHeaders,
         body: sigv4BodyStr,
         accessKeyId,
@@ -1228,6 +1385,25 @@ ${contentHash}`;
       }
       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;
     }
@@ -1235,13 +1411,13 @@ ${contentHash}`;
     let response;
     try {
       if (isSigV4 && sigv4BodyStr != null) {
-        response = await this.#providerClient.request(methodStr, url, {
+        response = await this.#providerClient.request(methodStr, currentUrl, {
           body: sigv4BodyStr,
           headers: requestHeaders,
           params: options?.queryParams
         });
       } else {
-        response = await this.#providerClient.request(methodStr, url, {
+        response = await this.#providerClient.request(methodStr, currentUrl, {
           json: options?.json,
           headers: requestHeaders,
           params: options?.queryParams
@@ -1252,18 +1428,18 @@ ${contentHash}`;
         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)
         }
       );
@@ -1271,6 +1447,13 @@ ${contentHash}`;
     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 (!stripHeaders.has(key.toLowerCase())) {
@@ -1284,9 +1467,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,
@@ -1299,14 +1482,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
         }
       );
     }
@@ -1331,12 +1529,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)) {
@@ -1382,24 +1591,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)) {
@@ -1430,7 +1652,7 @@ ${contentHash}`;
    * 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)
+   * @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
@@ -1446,8 +1668,8 @@ ${contentHash}`;
     const pollInterval = options.pollInterval ?? 2;
     const openBrowser = options.openBrowser ?? true;
     const session = await this.createConnectSession({
-      endUser: options.endUser,
-      allowedProviders: options.providers
+      allowedProviders: options.providers,
+      connectionPolicy: options.connectionPolicy
     });
     if (openBrowser) {
       try {
@@ -1484,18 +1706,28 @@ ${contentHash}`;
             connection_id: conn.connection_id ?? "",
             provider_id: conn.provider_id ?? "",
             account_identifier: conn.account_identifier ?? null,
-            scopes: conn.scopes ?? []
+            scopes: conn.scopes ?? [],
+            connection_policy: conn.connection_policy ?? null
           })
         );
       }
       if (pollStatus === "error") {
         const err = pollResult.error;
-        throw new ConnectFlowError(
-          err?.error_message ?? "OAuth flow failed",
-          {
-            error_code: err?.error_code ?? "unknown_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(
@@ -1517,16 +1749,17 @@ ${contentHash}`;
     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,
-      JSON.stringify(pollBody)
+      pollBodyStr
     );
     let response;
     try {
       response = await this.#alterClient.post(pollPath, {
-        json: pollBody,
-        headers: { ...actorHeaders, ...pollHmac }
+        body: pollBodyStr,
+        headers: { ...actorHeaders, ...pollHmac, "Content-Type": "application/json" }
       });
     } catch (error) {
       if (_AlterVault.#isTimeoutOrAbortError(error)) {
@@ -1574,10 +1807,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) => {
@@ -1596,20 +1891,26 @@ var HttpMethod = /* @__PURE__ */ ((HttpMethod2) => {
   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
 });