@superdurable/connectors-sdk 0.1.1 → 0.3.0

package/dist/oauthtoken/index.js

@@ -1,14 +1,336 @@
 import {
   SecretString
-} from "../chunk-KD5DYYSU.js";
+} from "../chunk-QDMBAWXD.js";
+import "../chunk-BQGYGCOQ.js";
 import {
   ReauthorizationRequiredError
-} from "../chunk-SOXYPIMO.js";
+} from "../chunk-IHG6ADQG.js";
 
 // src/oauthtoken/index.ts
 import { createPrivateKey, sign } from "crypto";
+
+// src/oauthtoken/manifest_refresh.ts
+var ManifestCredentialRefreshDriver = class {
+  #providerName;
+  #auth;
+  #credentialFields;
+  #settings;
+  #fetch;
+  #now;
+  /** Bind validated auth data, pinned settings, a caller-owned transport, and a clock. */
+  constructor(options) {
+    if (!options?.providerName || !options.auth || !options.credentialFields) throw new TypeError("manifest refresh configuration is required");
+    this.#providerName = options.providerName;
+    this.#auth = options.auth;
+    this.#credentialFields = options.credentialFields;
+    this.#settings = options.settings ?? {};
+    this.#fetch = options.fetch ?? fetch;
+    this.#now = options.now ?? (() => /* @__PURE__ */ new Date());
+  }
+  /** Check declared access fields against the host's single credential expiry. */
+  refreshRequired(state) {
+    const grants = this.#grants(this.#selectedMethod(state.credentials));
+    if (!grants.length) return false;
+    const accessFields = grants.flatMap((grant) => grant.mappings.filter((mapping) => mapping.source === "access_token").map((mapping) => manifestText(mapping.credential)));
+    const hasAccessToken = accessFields.length > 0 && accessFields.every((name) => Boolean(this.#credentialValue(state.credentials, name)));
+    return isRefreshRequired(hasAccessToken, state.expiresAt, state.now, "keep");
+  }
+  /** Send each active grant and return one complete credential with the earliest expiry. */
+  async refresh(state, signal) {
+    let credentials = state.credentials;
+    const method = this.#selectedMethod(credentials);
+    const grants = this.#grants(method);
+    if (!grants.length) throw new ReauthorizationRequiredError();
+    for (const grant of grants) this.#validateGrant(grant);
+    const expiries = [];
+    for (const grant of grants) {
+      if (grant.refreshField && !this.#credentialValue(credentials, grant.refreshField)) continue;
+      const token = await this.#exchange(grant, credentials, method, signal);
+      const requiredScopes = this.#scopes(grant.scopes).filter((scope) => grant.kind !== "refresh" || scope !== "offline_access");
+      if (grant.exactScopes ? !hasDeclaredScopes(token.scope, requiredScopes, grant.scopeSeparators, true) : token.scope.trim() !== "" && !hasDeclaredScopes(token.scope, requiredScopes, grant.scopeSeparators, false)) throw new ReauthorizationRequiredError();
+      const updates = {};
+      for (const mapping of grant.mappings) {
+        const destination = manifestText(mapping.credential);
+        const value = token.mappedCredentialValue(manifestText(mapping.source));
+        if (value === void 0 || value === "" && destination === grant.refreshField) continue;
+        const property = this.#credentialFields[destination];
+        if (!property) throw new TypeError("manifest credential field is not mapped");
+        updates[property] = this.#isSecret(method, destination) ? new SecretString(value) : value;
+      }
+      for (const copy of grant.copies) {
+        const destination = manifestText(copy.credential);
+        const property = this.#credentialFields[destination];
+        if (!property) throw new TypeError("manifest credential field is not mapped");
+        const value = this.#credentialValue(credentials, manifestText(copy.fromCredential));
+        updates[property] = this.#isSecret(method, destination) ? new SecretString(value) : value;
+      }
+      credentials = { ...credentials, ...updates };
+      const lifetime = token.expiresInMs > 0 ? token.expiresInMs : parseDurationMs(grant.missingExpiry);
+      expiries.push(lifetime > 0 ? this.#now().getTime() + lifetime : 0);
+    }
+    if (!expiries.length) throw new ReauthorizationRequiredError();
+    return { credentials, expiresAt: new Date(Math.min(...expiries)) };
+  }
+  #selectedMethod(credentials) {
+    const methods = manifestList(this.#auth.methods);
+    if (!methods.length) return this.#auth;
+    const selected = manifestText(credentials.authMethodId);
+    const method = methods.map(manifestObject).find((item) => item.id === (selected || manifestText(this.#auth.defaultMethod)));
+    if (!method) throw new ReauthorizationRequiredError();
+    return method;
+  }
+  #grants(method) {
+    if (method.oauth2) {
+      const oauth = manifestObject(method.oauth2);
+      const refresh = method.oauth2 && manifestObject(oauth.refresh);
+      let declared = manifestList(refresh?.grants).map(manifestObject);
+      if (!declared.length) {
+        const mapped = manifestList(oauth.credentialMappings).map(manifestObject).find((mapping) => mapping.source === "refresh_token");
+        if (!mapped) return [];
+        declared = [{ refreshTokenCredential: mapped.credential, credentialMappings: oauth.credentialMappings }];
+      }
+      return declared.map((declaration) => ({
+        kind: "refresh",
+        endpoint: oauth.tokenEndpoint,
+        authentication: oauth.tokenEndpointAuthMethod ?? "client_secret_post",
+        encoding: manifestText(oauth.tokenRequestEncoding) || "form",
+        clientID: manifestText(oauth.clientIDCredential),
+        clientSecret: manifestText(oauth.clientSecretCredential),
+        refreshField: manifestText(declaration.refreshTokenCredential),
+        keyCredential: "",
+        assertion: {},
+        mappings: manifestList(declaration.credentialMappings).map(manifestObject),
+        copies: [],
+        scopes: declaration.grantedScopes === "userScopes" ? oauth.userScopes : refresh?.requiredScopes ?? oauth.scopes,
+        requestScopes: [],
+        terminalCodes: strings(refresh?.terminalErrorCodes, ["invalid_grant"]),
+        acceptedTokenTypes: strings(declaration.acceptedTokenTypes ?? refresh?.acceptedTokenTypes, ["Bearer"]),
+        exactScopes: declaration.exactScopes === true || declaration.exactScopes === void 0 && refresh?.exactScopes === true,
+        scopeSeparators: refresh?.scopeSeparators === "whitespaceAndComma" ? "whitespaceAndComma" : "whitespace",
+        allowsPublicClient: refresh?.allowsPublicClient === true,
+        acceptsMissingTokenType: declaration.acceptsMissingTokenType === void 0 ? refresh?.acceptsMissingTokenType === true : declaration.acceptsMissingTokenType === true,
+        acceptsMissingExpiresIn: refresh?.missingExpiry !== void 0,
+        missingExpiry: missingExpiryLifetime(refresh?.missingExpiry),
+        additionalParameters: stringRecord(refresh?.additionalParameters)
+      }));
+    }
+    if (method.clientCredentials) {
+      const client = manifestObject(method.clientCredentials);
+      return [{
+        kind: "client_credentials",
+        endpoint: client.tokenEndpoint,
+        authentication: client.tokenEndpointAuthMethod ?? "client_secret_post",
+        encoding: manifestText(client.tokenRequestEncoding) || "form",
+        clientID: manifestText(client.clientIDCredential),
+        clientSecret: manifestText(client.clientSecretCredential),
+        refreshField: "",
+        keyCredential: "",
+        assertion: {},
+        mappings: manifestList(client.credentialMappings).map(manifestObject),
+        copies: [],
+        scopes: client.scopes,
+        requestScopes: client.scopes,
+        terminalCodes: strings(client.terminalErrorCodes, ["invalid_client"]),
+        acceptedTokenTypes: strings(client.acceptedTokenTypes, ["Bearer"]),
+        exactScopes: false,
+        scopeSeparators: "whitespace",
+        allowsPublicClient: false,
+        acceptsMissingTokenType: client.acceptsMissingTokenType === true,
+        acceptsMissingExpiresIn: client.missingExpiry !== void 0,
+        missingExpiry: missingExpiryLifetime(client.missingExpiry),
+        additionalParameters: stringRecord(client.additionalParameters)
+      }];
+    }
+    const serviceAccount = manifestObject(method.serviceAccount);
+    if (!serviceAccount.jwtBearer) return [];
+    const bearer = manifestObject(serviceAccount.jwtBearer);
+    return [{
+      kind: "jwt_bearer",
+      endpoint: bearer.tokenEndpoint,
+      authentication: "",
+      encoding: "form",
+      clientID: "",
+      clientSecret: "",
+      refreshField: "",
+      keyCredential: manifestText(bearer.keyCredential),
+      assertion: bearer,
+      mappings: manifestList(bearer.credentialMappings).map(manifestObject),
+      copies: manifestList(bearer.credentialCopies).map(manifestObject),
+      scopes: bearer.scopes,
+      requestScopes: [],
+      terminalCodes: strings(bearer.terminalErrorCodes, ["invalid_grant"]),
+      acceptedTokenTypes: strings(bearer.acceptedTokenTypes, ["Bearer"]),
+      exactScopes: false,
+      scopeSeparators: "whitespace",
+      allowsPublicClient: false,
+      acceptsMissingTokenType: bearer.acceptsMissingTokenType === true,
+      acceptsMissingExpiresIn: bearer.missingExpiry !== void 0,
+      missingExpiry: missingExpiryLifetime(bearer.missingExpiry),
+      additionalParameters: {}
+    }];
+  }
+  async #exchange(grant, credentials, method, signal) {
+    let key = {};
+    if (grant.kind === "jwt_bearer") {
+      try {
+        key = manifestObject(JSON.parse(this.#credentialValue(credentials, grant.keyCredential)));
+      } catch {
+        throw new ReauthorizationRequiredError();
+      }
+    }
+    const endpoint = new TokenEndpoint({
+      providerName: this.#providerName,
+      url: this.#resolveSource(grant.endpoint, credentials, key),
+      terminalErrorCodes: grant.terminalCodes,
+      acceptedTokenTypes: grant.acceptedTokenTypes,
+      acceptsMissingTokenType: grant.acceptsMissingTokenType,
+      acceptsMissingExpiresIn: grant.acceptsMissingExpiresIn,
+      usesJSONRequestBody: grant.encoding === "json",
+      additionalRequestParameters: grant.additionalParameters,
+      credentialMappingPaths: grant.mappings.map((mapping) => manifestText(mapping.source)),
+      fetch: this.#fetch
+    });
+    if (grant.kind === "jwt_bearer") {
+      const assertion = grant.assertion;
+      const lifetimeMs = parseDurationMs(manifestText(assertion.lifetime));
+      let signed;
+      try {
+        signed = signJWTBearerAssertion({
+          issuer: this.#resolveSource(assertion.issuer, credentials, key),
+          audience: this.#resolveSource(assertion.audience, credentials, key),
+          ...assertion.subject ? { subject: this.#resolveSource(assertion.subject, credentials, key) } : {},
+          scope: this.#scopes(assertion.scopes).join(" "),
+          issuedAt: this.#now(),
+          lifetimeMs
+        }, parseRSAPrivateKeyPEM(this.#resolveSource(assertion.privateKey, credentials, key)));
+      } catch {
+        throw new ReauthorizationRequiredError();
+      }
+      return await endpoint.exchangeJWTBearerAssertion(signed, signal);
+    }
+    const secret = this.#credentialValue(credentials, grant.clientSecret);
+    if (!secret && !grant.allowsPublicClient && (grant.kind === "refresh" || this.#isRequired(method, grant.clientSecret)))
+      throw new ReauthorizationRequiredError();
+    const authenticationMethod = secret || grant.kind === "client_credentials" ? this.#resolveSource(grant.authentication, credentials, key) : "none";
+    const client = { id: this.#credentialValue(credentials, grant.clientID), secret: new SecretString(secret), authenticationMethod };
+    if (grant.kind === "refresh") {
+      return endpoint.exchangeRefreshToken(client, new SecretString(this.#credentialValue(credentials, grant.refreshField)), signal);
+    }
+    return endpoint.exchangeClientCredentials(client, this.#scopes(grant.requestScopes), signal);
+  }
+  #credentialValue(credentials, name) {
+    const property = this.#credentialFields[name];
+    if (!property) return "";
+    const value = credentials[property];
+    return value instanceof SecretString ? value.reveal() : typeof value === "string" ? value : "";
+  }
+  #isSecret(method, name) {
+    return manifestList(method.fields).map(manifestObject).some((field) => field.name === name && field.type === "secretString");
+  }
+  #isRequired(method, name) {
+    const field = manifestList(method.fields).map(manifestObject).find((candidate) => candidate.name === name);
+    return field ? field.required === true : true;
+  }
+  #validateGrant(grant) {
+    for (const mapping of grant.mappings) {
+      if (!manifestText(mapping.source) || !this.#credentialFields[manifestText(mapping.credential)])
+        throw new TypeError("manifest credential field is not mapped");
+    }
+    for (const copy of grant.copies) {
+      if (!this.#credentialFields[manifestText(copy.credential)] || !this.#credentialFields[manifestText(copy.fromCredential)])
+        throw new TypeError("manifest credential field is not mapped");
+    }
+    if (grant.missingExpiry && parseDurationMs(grant.missingExpiry) <= 0)
+      throw new TypeError("manifest grant duration must be positive");
+    if (grant.kind === "jwt_bearer" && parseDurationMs(manifestText(grant.assertion.lifetime)) < 1)
+      throw new TypeError("manifest JWT assertion lifetime must be at least one millisecond");
+  }
+  #scopes(source) {
+    if (Array.isArray(source)) return source.filter((value) => typeof value === "string");
+    const fromSetting = manifestObject(source).fromSetting;
+    return typeof fromSetting === "string" ? (this.#settings[fromSetting] ?? "").split(/\s+/).filter(Boolean) : [];
+  }
+  #resolveSource(source, credentials, key) {
+    if (typeof source === "string") return source;
+    const valueSource = manifestObject(source);
+    if (typeof valueSource.value === "string") return valueSource.value;
+    if (typeof valueSource.template === "string") return valueSource.template.replace(/\{([^{}]+)\}/g, (_, name) => pathEscape(this.#credentialFields[name] ? this.#credentialValue(credentials, name) : this.#settings[name] ?? ""));
+    let value = "";
+    if (typeof valueSource.fromCredential === "string") value = this.#credentialValue(credentials, valueSource.fromCredential);
+    else if (typeof valueSource.fromSetting === "string") value = this.#settings[valueSource.fromSetting] ?? "";
+    else if (typeof valueSource.fromKey === "string") value = manifestText(key[valueSource.fromKey]);
+    else throw new ReauthorizationRequiredError();
+    if (valueSource.values) {
+      const translated = manifestObject(valueSource.values)[value];
+      if (typeof translated !== "string") throw new ReauthorizationRequiredError();
+      return translated;
+    }
+    if (!value) throw new ReauthorizationRequiredError();
+    return value;
+  }
+};
+function manifestObject(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+function manifestList(value) {
+  return Array.isArray(value) ? value : [];
+}
+function manifestText(value) {
+  return typeof value === "string" ? value : "";
+}
+function strings(value, fallback) {
+  const found = manifestList(value).filter((item) => typeof item === "string");
+  return found.length ? found : fallback;
+}
+function stringRecord(value) {
+  return Object.fromEntries(Object.entries(manifestObject(value)).filter((entry) => typeof entry[1] === "string"));
+}
+function missingExpiryLifetime(value) {
+  return manifestText(manifestObject(value).lifetime);
+}
+function hasDeclaredScopes(returnedScopes, requiredScopes, separators, exact) {
+  const granted = new Set(returnedScopes.split(separators === "whitespaceAndComma" ? /[ ,]+/ : /\s+/).filter(Boolean));
+  const required = new Set(requiredScopes);
+  return (!exact || granted.size === required.size) && [...required].every((scope) => granted.has(scope));
+}
+function pathEscape(value) {
+  return encodeURIComponent(value).replace(/[!'()*]/g, (character) => `%${character.charCodeAt(0).toString(16).toUpperCase()}`).replace(/%(?:2B|26|3D|3A|40|24)/g, (escaped) => ({ "%2B": "+", "%26": "&", "%3D": "=", "%3A": ":", "%40": "@", "%24": "$" })[escaped] ?? escaped);
+}
+function parseDurationMs(value) {
+  if (!value) return 0;
+  if (value === "0" || value === "+0" || value === "-0") return 0;
+  const sign2 = value[0] === "-" ? -1n : 1n;
+  const magnitude = value[0] === "+" || value[0] === "-" ? value.slice(1) : value;
+  const parts = magnitude.matchAll(/((?:\d+(?:\.\d*)?|\.\d+))(ns|us|µs|μs|ms|s|m|h)/g);
+  const nanoseconds = {
+    ns: 1n,
+    us: 1000n,
+    "\xB5s": 1000n,
+    "\u03BCs": 1000n,
+    ms: 1000000n,
+    s: 1000000000n,
+    m: 60000000000n,
+    h: 3600000000000n
+  };
+  let duration = 0n;
+  let position = 0;
+  for (const part of parts) {
+    if (part.index !== position) throw new TypeError("manifest grant duration is invalid");
+    const [whole, fraction = ""] = part[1].split(".");
+    const unit = nanoseconds[part[2]];
+    duration += BigInt(whole || "0") * unit;
+    if (fraction) duration += BigInt(fraction) * unit / 10n ** BigInt(fraction.length);
+    position += part[0].length;
+  }
+  if (position !== magnitude.length || duration === 0n || duration > (sign2 < 0n ? 9223372036854775808n : 9223372036854775807n))
+    throw new TypeError("manifest grant duration is invalid");
+  return Number(sign2 * duration) / 1e6;
+}
+
+// src/oauthtoken/index.ts
 var RefreshSkewMs = 3e5;
 var TokenResponse = class {
+  #mappedCredentialFields;
   /** Replacement access token. */
   accessToken;
   /** Rotated refresh token, empty when the provider retained it. */
@@ -32,11 +354,16 @@ var TokenResponse = class {
     this.scope = fields.scope;
     this.tokenType = fields.tokenType;
     this.retainedFields = fields.retainedFields;
+    this.#mappedCredentialFields = fields.mappedCredentialFields ?? {};
   }
   /** Keep the previous refresh token when no rotated value was returned. */
   nextRefreshToken(prior) {
     return this.refreshToken.reveal() ? this.refreshToken : prior;
   }
+  /** Reveal only one declared credential mapping at the provider boundary. */
+  mappedCredentialValue(path) {
+    return this.#mappedCredentialFields[path]?.reveal();
+  }
 };
 var TokenEndpoint = class {
   #options;
@@ -136,13 +463,26 @@ var TokenEndpoint = class {
     if (typeof accessToken !== "string" || !accessToken || !hasAcceptedExpiry || !hasAcceptedType) throw new Error(`${options.providerName} token response omitted required fields`);
     const retainedFields = {};
     for (const field of options.retainedResponseFields ?? []) if (Object.hasOwn(decoded, field)) retainedFields[field] = decoded[field];
+    const mappedCredentialFields = {};
+    for (const path of options.credentialMappingPaths ?? []) {
+      const value = responsePathValue(decoded, path);
+      if (value !== void 0) mappedCredentialFields[path] = new SecretString(value);
+    }
     const refreshToken = typeof decoded.refresh_token === "string" ? decoded.refresh_token : "";
     const refreshTokenExpiry = typeof decoded.refresh_token_expires_in === "number" && decoded.refresh_token_expires_in > 0 ? decoded.refresh_token_expires_in : 0;
-    return new TokenResponse({ accessToken: new SecretString(accessToken), refreshToken: new SecretString(refreshToken), expiresInMs: (expiresIn ?? 0) * 1e3, refreshTokenExpiresInMs: refreshTokenExpiry * 1e3, scope: typeof decoded.scope === "string" ? decoded.scope : "", tokenType: typeof tokenType === "string" ? tokenType : "", retainedFields });
+    return new TokenResponse({ accessToken: new SecretString(accessToken), refreshToken: new SecretString(refreshToken), expiresInMs: (expiresIn ?? 0) * 1e3, refreshTokenExpiresInMs: refreshTokenExpiry * 1e3, scope: typeof decoded.scope === "string" ? decoded.scope : "", tokenType: typeof tokenType === "string" ? tokenType : "", retainedFields, mappedCredentialFields });
   }
 };
 var grantParameters = /* @__PURE__ */ new Set(["grant_type", "refresh_token", "client_id", "client_secret", "assertion", "client_assertion", "client_assertion_type"]);
 var standardResponseFields = /* @__PURE__ */ new Set(["access_token", "refresh_token", "expires_in", "refresh_token_expires_in", "scope", "token_type", "error", "error_description", "error_uri", "id_token"]);
+function responsePathValue(response, path) {
+  let value = response;
+  for (const member of path.split(".")) {
+    if (!value || typeof value !== "object" || Array.isArray(value) || !Object.hasOwn(value, member)) return void 0;
+    value = value[member];
+  }
+  return typeof value === "string" ? value : void 0;
+}
 function validateEndpointURL(value, allowsPlainHTTP, providerName) {
   let parsed;
   try {
@@ -222,6 +562,7 @@ function signJWTBearerAssertion(assertion, privateKey) {
   return new SecretString(`${unsigned}.${signature}`);
 }
 export {
+  ManifestCredentialRefreshDriver,
   RefreshSkewMs,
   TokenEndpoint,
   TokenResponse,

package/dist/{operation-Ca8rfacf.d.ts → operation-CASLOg86.d.ts}

@@ -1,4 +1,5 @@
-import { O as OperationRef, f as BranchDefinition, Z as RetryPolicy, C as Call, M as MutationAttempt, Q as QueryAttempt } from './credentials-vrvW0d4j.js';
+import { C as Call } from './credentials-JqG97kJ5.js';
+import { O as OperationRef, e as BranchDefinition, J as RetryPolicy, M as MutationAttempt, Q as QueryAttempt } from './types-D6De3sry.js';
 
 /** Execute options owned by one operation; durations are milliseconds. */
 interface StepDefaults {

package/dist/projectconfig/index.d.ts

@@ -1,7 +1,8 @@
 import { z } from 'zod';
 import { inspect } from 'node:util';
 import { S3Client } from '@aws-sdk/client-s3';
-import { t as CredentialProvider$1, C as Call, W as RefreshingCredentialProvider$1, X as RejectedCredentialRefreshingProvider, u as CredentialRefreshDriver } from '../credentials-vrvW0d4j.js';
+import { c as CredentialProvider$1, C as Call, R as RefreshingCredentialProvider$1, h as RejectedCredentialRefreshingProvider, d as CredentialRefreshDriver } from '../credentials-JqG97kJ5.js';
+import '../types-D6De3sry.js';
 import '@superdurable/dex';
 
 /** Current secret-free project configuration schema shared with Dex Web. */

package/dist/projectconfig/index.js

@@ -1,13 +1,15 @@
+import {
+  OperationRefSchema
+} from "../chunk-BQGYGCOQ.js";
 import {
   BodyTooLargeError,
   isLocalStorageHost,
   isPrivateBrokerHost,
   readBoundedBody
-} from "../chunk-2IDXFKMY.js";
+} from "../chunk-UWB627CI.js";
 import {
-  OperationRefSchema,
   ReauthorizationRequiredError
-} from "../chunk-SOXYPIMO.js";
+} from "../chunk-IHG6ADQG.js";
 
 // src/projectconfig/model.ts
 import { z } from "zod";

package/dist/providerhttp/index.d.ts

@@ -22,8 +22,21 @@ declare class ProviderTransportError extends Error {
     /** True only when the request failed before a usable connection could send HTTP bytes. */
     constructor(isProvablyNotSent: boolean);
 }
-/** Public-only HTTPS or explicitly owned private-network HTTP. */
-type AddressPolicy = 'publicHTTPS' | 'privateNetworkHTTP';
+/** Provider emitted no response byte within the configured stall timeout. */
+declare class ProviderStalledError extends Error {
+    /** Construct a sanitized no-byte timeout failure. */
+    constructor();
+}
+/** Public HTTPS, owned private HTTP, or caller-owned unrestricted transport. */
+type AddressPolicy = 'publicHTTPS' | 'privateNetworkHTTP' | 'unrestricted';
+/** Caller-owned transport for a provider exchange; implementations must not replay redirects.
+ * A client may return a complete body without calling onResponseChunk. If it calls the callback,
+ * it must feed every received chunk in order before returning and honor false by stopping the response.
+ */
+interface ProviderHTTPClient {
+    /** Send one request and return its bounded response. */
+    send(request: ProviderRequest): Promise<ProviderResponse>;
+}
 /** One bounded provider request; response bodies and URL values never enter errors. */
 interface ProviderRequest {
     /** Absolute provider URL. */ url: string;
@@ -31,9 +44,14 @@ interface ProviderRequest {
     /** Request headers, including provider credentials when needed. */ headers?: Record<string, string>;
     /** Caller-encoded request body. */ body?: Uint8Array;
     /** Maximum response body size in bytes. */ maxResponseBytes: number;
+    /** On a response limit, destroy the connection (default) or drain to EOF before rejecting. Drain requires a positive timeoutMs, positive stallTimeoutMs, or signal. */ onBodyLimit?: 'destroy' | 'drain';
+    /** Optional separate prefix limit for non-2xx error bodies; when set, its truncation takes precedence over drain. */ maxErrorResponseBytes?: number;
+    /** Classify a non-2xx status even when its diagnostic body fails to read. */ ignoreErrorBodyReadFailure?: boolean;
     /** Network policy checked against all resolved addresses. */ addressPolicy: AddressPolicy;
     /** Request deadline in milliseconds. */ timeoutMs?: number;
     /** Caller cancellation. */ signal?: AbortSignal;
+    /** Observe chunks in arrival order; returning false stops a completed event stream. */ onResponseChunk?: (chunk: Uint8Array, status: number, headers: http.IncomingHttpHeaders) => boolean | void;
+    /** Abort a response when no byte arrives for this many milliseconds. */ stallTimeoutMs?: number;
 }
 /** Bounded response; redirects remain visible as 3xx responses. */
 interface ProviderResponse {
@@ -54,4 +72,4 @@ declare function readErrorTokens(body: Uint8Array, pointers: readonly string[]):
 /** Send once using pinned, policy-checked DNS results and no redirect replay. */
 declare function sendProviderRequest(request: ProviderRequest): Promise<ProviderResponse>;
 
-export { type AddressPolicy, AddressRefusal, BodyTooLargeError, MaxErrorBodyBytes, MaxRetryAfterDelayMs, type ProviderRequest, type ProviderResponse, ProviderTransportError, isHeaderSafeCredential, parseRetryAfter, readBoundedBody, readErrorTokens, sendProviderRequest, validateBaseURL };
+export { type AddressPolicy, AddressRefusal, BodyTooLargeError, MaxErrorBodyBytes, MaxRetryAfterDelayMs, type ProviderHTTPClient, type ProviderRequest, type ProviderResponse, ProviderStalledError, ProviderTransportError, isHeaderSafeCredential, parseRetryAfter, readBoundedBody, readErrorTokens, sendProviderRequest, validateBaseURL };

package/dist/providerhttp/index.js

@@ -3,6 +3,7 @@ import {
   BodyTooLargeError,
   MaxErrorBodyBytes,
   MaxRetryAfterDelayMs,
+  ProviderStalledError,
   ProviderTransportError,
   isHeaderSafeCredential,
   parseRetryAfter,
@@ -10,12 +11,13 @@ import {
   readErrorTokens,
   sendProviderRequest,
   validateBaseURL
-} from "../chunk-2IDXFKMY.js";
+} from "../chunk-UWB627CI.js";
 export {
   AddressRefusal,
   BodyTooLargeError,
   MaxErrorBodyBytes,
   MaxRetryAfterDelayMs,
+  ProviderStalledError,
   ProviderTransportError,
   isHeaderSafeCredential,
   parseRetryAfter,

package/dist/query-CeUaW9xU.d.ts

@@ -0,0 +1,42 @@
+import { C as Call, S as SecretString } from './credentials-JqG97kJ5.js';
+import { ProviderHTTPClient } from './providerhttp/index.js';
+import { Q as QueryAttempt } from './types-D6De3sry.js';
+import { b as Query, Q as QueryDefinition } from './operation-CASLOg86.js';
+import { T as TextGenerationRequest, q as TextGenerationResponse, W as WireFormat } from './wire_format-stEVruMs.js';
+
+/** Configuration for one generateText Query; durations are milliseconds. */
+interface TextGenerationQueryConfig {
+    /** Generated connector operation definition and sync Step defaults. */ definition: QueryDefinition;
+    /** Provider-specific adapter. */ wireFormat: WireFormat;
+    /** Validated provider base URL. */ baseURL: string;
+    /** Default model; blank requires a request model. */ connectionModel?: string;
+    /** HTTP exchange deadline. */ requestTimeoutMs: number;
+    /** Optional caller-owned HTTP transport, as with Go's HTTPClient. It must not replay redirects. */ httpClient?: ProviderHTTPClient;
+    /** Resolve private credential once per validated attempt. */ resolveCredential: (call: Call) => string | SecretString | Promise<string | SecretString>;
+    /** Maximum complete body or event stream bytes. */ maxResponseBytes: number;
+    /** Maximum one SSE event bytes; required for streaming. */ maxStreamEventBytes?: number;
+}
+/** Shared provider-neutral text generation Query; concurrent invocations own isolated state.
+ *
+ * Each invocation resolves the model, validates portable fields in order, applies model rules,
+ * resolves one credential, encodes the request, dispatches once, and classifies the response.
+ * Validation or configuration failure in the first five stages selects defect with zero requests.
+ * A silent request records a nil Dex heartbeat every five seconds, clearing a caller checkpoint.
+ * Stream text can include retried, blocked, or invalid attempts; only the final Result is authoritative.
+ * Sync Execute durability prevents a long local attempt from dispatching the billed call again.
+ * Structured numbers are bounded to 256 literal characters and exponent magnitude 400.
+ */
+declare class TextGenerationQuery implements Query<TextGenerationRequest, TextGenerationResponse> {
+    #private;
+    /** Validate configuration before a provider request can be made. */
+    constructor(config: TextGenerationQueryConfig);
+    /** Return the connector's generateText definition. */ definition(): QueryDefinition;
+    /** Return optional request features declared by the provider. */ requestFeatures(): Readonly<WireFormat['features']>;
+    /** Return the provider model ID rule. */ modelIDRule(): WireFormat['modelIDRule'];
+    /** Validate in fixed order, dispatch once, and classify a branch or safe retry without exposing secrets. */
+    invoke(call: Call, request: TextGenerationRequest): Promise<QueryAttempt<TextGenerationResponse>>;
+}
+/** Construct a generateText Query, rejecting invalid definitions, wire formats, models, timeouts, and size limits before dispatch. */
+declare function newTextGenerationQuery(config: TextGenerationQueryConfig): TextGenerationQuery;
+
+export { TextGenerationQuery as T, type TextGenerationQueryConfig as a, newTextGenerationQuery as n };

package/dist/singledispatch/index.d.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod';
-import { C as Call, a as CallID } from '../credentials-vrvW0d4j.js';
+import { C as CallID } from '../types-D6De3sry.js';
+import { C as Call } from '../credentials-JqG97kJ5.js';
 import '@superdurable/dex';
 
 /** The current attempt has no permission to send another provider write. */

package/dist/singledispatch/index.js

@@ -1,6 +1,7 @@
 import {
   CallIDSchema
-} from "../chunk-SOXYPIMO.js";
+} from "../chunk-BQGYGCOQ.js";
+import "../chunk-IHG6ADQG.js";
 
 // src/singledispatch/index.ts
 import { z } from "zod";

package/dist/textgen/index.d.ts

@@ -0,0 +1,15 @@
+import { T as TextGenerationRequest } from '../wire_format-stEVruMs.js';
+export { B as BlockedBranchID, C as CredentialHeader, D as DecodedResponse, a as DefectBranchID, E as EncodeRequestInput, b as EncodedRequest, c as ErrorOutcome, d as ErrorRule, F as FinishReason, G as GeneratedBranchID, I as InvalidResponseBranchID, M as Message, e as MessageRole, f as ModelIDRule, g as ModelRequestRules, P as ProviderRejectedBranchID, h as ProviderReportedError, R as ReasoningEffort, i as RequestFeatures, j as ResponsePart, S as ServerSentEvent, k as StreamDecodeState, l as StructuredOutput, m as StructuredOutputMode, n as StructuredOutputRules, o as TemperaturePolicy, p as TextGenerationOperationID, q as TextGenerationResponse, r as TruncatedBranchID, U as Usage, W as WireFormat, s as blockedOutcome, t as classifyError, u as invalidResponseOutcome, v as providerRejectedOutcome, w as quotaExhaustedOutcome, x as resolveModel, y as retryOutcome, z as temperatureAccepted, A as temperatureNotAccepted, H as temperatureRange, J as textGenerationBranchDefinitions, K as validateModelID, L as validatePortableRequest, N as validateStructuredOutputRules, O as validateWireFormat } from '../wire_format-stEVruMs.js';
+export { T as TextGenerationQuery, a as TextGenerationQueryConfig, n as newTextGenerationQuery } from '../query-CeUaW9xU.js';
+import '../types-D6De3sry.js';
+import 'zod';
+import '../credentials-JqG97kJ5.js';
+import '@superdurable/dex';
+import '../providerhttp/index.js';
+import 'node:http';
+import '../operation-CASLOg86.js';
+
+/** Remove whitespace and one JSON Markdown fence, then validate the original schema. */
+declare function extractStructuredAnswer(request: TextGenerationRequest, generatedText: string): string;
+
+export { TextGenerationRequest, extractStructuredAnswer };