@alter-ai/alter-sdk 0.3.1 → 0.4.0

package/README.md

@@ -12,6 +12,7 @@ Official TypeScript SDK for [Alter Vault](https://alterai.dev) — Credential ma
 - **Real-time Policy Enforcement**: Every token request checked against current policies
 - **Automatic Token Refresh**: Tokens refreshed transparently by the backend
 - **API Key and Custom Credential Support**: Handles OAuth tokens, API keys, and custom credential formats automatically
+- **AWS SigV4 Support**: Automatic AWS Signature Version 4 signing for S3, Bedrock, DynamoDB, and other AWS services (no AWS SDK required)
 - **Actor Tracking**: First-class support for AI agent and MCP server observability
 - **HMAC Request Signing**: All SDK-to-backend requests are signed with a derived HMAC-SHA256 key for integrity, authenticity, and replay protection
 - **Native Promises**: Built on native `fetch` — no heavy dependencies
@@ -200,6 +201,42 @@ console.log(`Expires in: ${session.expiresIn}s`);
 
 Returns `ConnectSession` with: `sessionToken`, `connectUrl`, `expiresIn`, `expiresAt`.
 
+#### Headless Connect (from code)
+
+For CLI tools, scripts, and server-side applications -- opens the browser, waits for the user to complete OAuth, and returns the result:
+
+```typescript
+const results = await vault.connect({
+  endUser: { id: "alice" },
+  providers: ["google"],
+  timeout: 300,        // max wait in seconds (default: 5 min)
+  openBrowser: true,   // set false to print URL instead
+});
+for (const result of results) {
+  console.log(`Connected: ${result.connectionId} (${result.providerId})`);
+  console.log(`Account: ${result.accountIdentifier}`);
+}
+
+// Now use the connectionId with vault.request()
+const response = await vault.request(
+  results[0].connectionId,
+  HttpMethod.GET,
+  "https://www.googleapis.com/calendar/v3/calendars/primary/events",
+);
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `endUser` | `{ id: string }` | *required* | End user identity |
+| `providers` | `string[]` | - | Restrict to specific providers |
+| `timeout` | `number` | `300` | Max seconds to wait for completion |
+| `pollInterval` | `number` | `2` | Seconds between status checks |
+| `openBrowser` | `boolean` | `true` | Open browser automatically |
+
+Returns `ConnectResult[]` — one per connected provider. Each has: `connectionId`, `providerId`, `accountIdentifier`, `scopes`.
+
+Throws `ConnectTimeoutError` if the user doesn't complete in time, `ConnectFlowError` if denied.
+
 ### AI Agent Actor Tracking
 
 ```typescript
@@ -295,6 +332,8 @@ import {
   ConnectionNotFoundError,
   TokenExpiredError,
   TokenRetrievalError,
+  ConnectFlowError,           // Headless connect() failed (denied, provider error)
+  ConnectTimeoutError,        // Headless connect() timed out
   NetworkError,
   TimeoutError,
   ProviderAPIError,

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,6 +17,14 @@ 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
@@ -24,7 +34,10 @@ __export(index_exports, {
   ActorType: () => ActorType,
   AlterSDKError: () => AlterSDKError,
   AlterVault: () => AlterVault,
+  ConnectFlowError: () => ConnectFlowError,
+  ConnectResult: () => ConnectResult,
   ConnectSession: () => ConnectSession,
+  ConnectTimeoutError: () => ConnectTimeoutError,
   ConnectionInfo: () => ConnectionInfo,
   ConnectionListResult: () => ConnectionListResult,
   ConnectionNotFoundError: () => ConnectionNotFoundError,
@@ -41,7 +54,7 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/client.ts
-var import_node_crypto = require("crypto");
+var import_node_crypto2 = require("crypto");
 
 // src/exceptions.ts
 var AlterSDKError = class extends Error {
@@ -87,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;
@@ -134,6 +159,8 @@ 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;
   constructor(data) {
     this.tokenType = data.token_type ?? "Bearer";
     this.expiresIn = data.expires_in ?? null;
@@ -143,6 +170,12 @@ 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;
+    }
     Object.freeze(this);
   }
   /**
@@ -282,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;
@@ -361,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) {
@@ -375,8 +594,11 @@ function _extractAccessToken(token) {
   }
   return value;
 }
+function _extractAdditionalCredentials(token) {
+  return _additionalCredsStore.get(token);
+}
 var _fetch;
-var SDK_VERSION = "0.3.0";
+var SDK_VERSION = "0.4.0";
 var SDK_USER_AGENT = `alter-sdk-node/${SDK_VERSION}`;
 var HTTP_FORBIDDEN = 403;
 var HTTP_NOT_FOUND = 404;
@@ -433,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";
     }
@@ -496,7 +720,7 @@ var AlterVault = class _AlterVault {
     for (const [name, value] of actorStrings) {
       _AlterVault.#validateActorString(value, name);
     }
-    this.#hmacKey = (0, import_node_crypto.createHmac)("sha256", options.apiKey).update("alter-signing-v1").digest();
+    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;
@@ -600,12 +824,12 @@ var AlterVault = class _AlterVault {
    */
   #computeHmacHeaders(method, path, body) {
     const timestamp = String(Math.floor(Date.now() / 1e3));
-    const contentHash = (0, import_node_crypto.createHash)("sha256").update(body ?? "").digest("hex");
+    const contentHash = (0, import_node_crypto2.createHash)("sha256").update(body ?? "").digest("hex");
     const stringToSign = `${method.toUpperCase()}
 ${path}
 ${timestamp}
 ${contentHash}`;
-    const signature = (0, import_node_crypto.createHmac)("sha256", this.#hmacKey).update(stringToSign).digest("hex");
+    const signature = (0, import_node_crypto2.createHmac)("sha256", this.#hmacKey).update(stringToSign).digest("hex");
     return {
       "X-Alter-Timestamp": timestamp,
       "X-Alter-Content-SHA256": contentHash,
@@ -809,6 +1033,9 @@ ${contentHash}`;
       );
     }
     _storeAccessToken(tokenResponse, typedData.access_token);
+    if (typedData.additional_credentials) {
+      _storeAdditionalCredentials(tokenResponse, typedData.additional_credentials);
+    }
     return tokenResponse;
   }
   /**
@@ -914,7 +1141,7 @@ ${contentHash}`;
         "SDK instance has been closed. Create a new AlterVault instance to make requests."
       );
     }
-    const runId = options?.runId ?? (0, import_node_crypto.randomUUID)();
+    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))) {
@@ -960,28 +1187,66 @@ ${contentHash}`;
       options?.threadId,
       options?.toolCallId
     );
-    const injectionHeaderLower = tokenResponse.injectionHeader.toLowerCase();
-    if (options?.extraHeaders && Object.keys(options.extraHeaders).some(
-      (k) => k.toLowerCase() === injectionHeaderLower
-    )) {
-      console.warn(
-        `extraHeaders contains '${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 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(
@@ -1004,9 +1269,11 @@ ${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]);
     const auditHeaders = {};
     for (const [key, value] of Object.entries(requestHeaders)) {
-      if (key.toLowerCase() !== injectionHeaderLower) {
+      if (!stripHeaders.has(key.toLowerCase())) {
         auditHeaders[key] = value;
       }
     }
@@ -1156,6 +1423,132 @@ ${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 (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.
@@ -1203,7 +1596,10 @@ var HttpMethod = /* @__PURE__ */ ((HttpMethod2) => {
   ActorType,
   AlterSDKError,
   AlterVault,
+  ConnectFlowError,
+  ConnectResult,
   ConnectSession,
+  ConnectTimeoutError,
   ConnectionInfo,
   ConnectionListResult,
   ConnectionNotFoundError,