@datagrout/conduit 0.6.0 → 0.8.0

package/dist/index.js

@@ -435,34 +435,55 @@ var init_onramp = __esm({
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  AuthCodeError: () => AuthCodeError,
+  AuthCodeFlow: () => AuthCodeFlow,
+  AuthCodeProvider: () => AuthCodeProvider,
   AuthError: () => AuthError,
   Client: () => Client2,
   ConduitError: () => ConduitError,
   ConduitIdentity: () => ConduitIdentity,
   DEFAULT_IDENTITY_DIR: () => DEFAULT_IDENTITY_DIR,
+  DEFAULT_SCOPE: () => DEFAULT_SCOPE,
+  DELEGATION_GRANT_TYPE: () => GRANT_TYPE,
+  DELEGATION_SERVER_ERROR_CODES: () => SERVER_ERROR_CODES,
   DG_CA_URL: () => DG_CA_URL,
   DG_SUBSTRATE_ENDPOINT: () => DG_SUBSTRATE_ENDPOINT,
+  DelegatedProvider: () => DelegatedProvider,
+  DelegationError: () => DelegationError,
+  DelegationRequest: () => DelegationRequest,
   GuidedSession: () => GuidedSession,
   InvalidConfigError: () => InvalidConfigError,
+  LoopbackListener: () => LoopbackListener,
   NetworkError: () => NetworkError,
   NotInitializedError: () => NotInitializedError,
   OAuthTokenProvider: () => OAuthTokenProvider,
   RateLimitError: () => RateLimitError,
   ServerError: () => ServerError,
+  TOKEN_TYPES: () => TOKEN_TYPES,
+  TokenSource: () => TokenSource,
   WS_SUBPROTOCOL: () => SUBPROTOCOL,
   WsTransport: () => WsTransport,
+  authCodeProviderFrom: () => authCodeProviderFrom,
+  challengeS256: () => challengeS256,
   deriveTokenEndpoint: () => deriveTokenEndpoint,
   extractMeta: () => extractMeta,
   fetchDgCaCert: () => fetchDgCaCert,
   fetchWithIdentity: () => fetchWithIdentity,
   generateKeypair: () => generateKeypair,
+  generateVerifier: () => generateVerifier,
+  isDelegatedTokenExpired: () => isDelegatedTokenExpired,
   isDgUrl: () => isDgUrl,
+  isGrantExpired: () => isGrantExpired,
+  isGrantRefreshable: () => isGrantRefreshable,
   refreshCaCert: () => refreshCaCert,
+  refreshGrant: () => refreshGrant,
   registerAndExchange: () => registerAndExchange,
   registerIdentity: () => registerIdentity,
   registerOnly: () => registerOnly,
   rotateIdentity: () => rotateIdentity,
   saveIdentity: () => saveIdentity,
+  supportsS256: () => supportsS256,
+  tokenTypeName: () => tokenTypeName,
   version: () => version
 });
 module.exports = __toCommonJS(index_exports);
@@ -470,12 +491,504 @@ module.exports = __toCommonJS(index_exports);
 // src/client.ts
 var path2 = __toESM(require("path"));
 
+// src/version.ts
+var version = "0.8.0";
+
 // src/transports/base.ts
 var Transport = class {
 };
 
 // src/transports/mcp.ts
 init_oauth();
+
+// src/authcode.ts
+var import_node_crypto = require("crypto");
+
+// src/errors.ts
+var ConduitError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = this.constructor.name;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var NotInitializedError = class extends ConduitError {
+  constructor() {
+    super("Client not initialized. Call connect() first.");
+  }
+};
+var RateLimitError = class extends ConduitError {
+  status;
+  retryAfter;
+  constructor(status, retryAfter) {
+    const limitStr = status.limit === "unlimited" ? "unlimited" : `${status.limit.perHour}/hour`;
+    super(`Rate limit exceeded (${status.used} / ${limitStr} calls this hour)`);
+    this.status = status;
+    this.retryAfter = retryAfter;
+  }
+};
+var AuthError = class extends ConduitError {
+  constructor(message = "Authentication failed") {
+    super(message);
+  }
+};
+var NetworkError = class extends ConduitError {
+  constructor(message) {
+    super(message);
+  }
+};
+var ServerError = class extends ConduitError {
+  code;
+  serverMessage;
+  constructor(code, serverMessage) {
+    super(`Server error ${code}: ${serverMessage}`);
+    this.code = code;
+    this.serverMessage = serverMessage;
+  }
+};
+var InvalidConfigError = class extends ConduitError {
+  constructor(message) {
+    super(message);
+  }
+};
+
+// src/authcode.ts
+var DEFAULT_SCOPE = "mcp tools";
+var REFRESH_SKEW_SECS = 60;
+var AuthCodeError = class extends ConduitError {
+  kind;
+  /** HTTP status, for `registration_rejected` and `token_exchange`. */
+  status;
+  /** Response body, for `registration_rejected` and `token_exchange`. */
+  body;
+  constructor(kind, message, extra) {
+    super(message);
+    this.kind = kind;
+    this.status = extra?.status;
+    this.body = extra?.body;
+  }
+};
+function supportsS256(metadata) {
+  const methods = metadata.code_challenge_methods_supported;
+  if (!methods || methods.length === 0) return true;
+  return methods.some((m) => m.toUpperCase() === "S256");
+}
+function isGrantExpired(grant) {
+  if (grant.expires_at === void 0) return false;
+  return nowSecs() + REFRESH_SKEW_SECS >= grant.expires_at;
+}
+function isGrantRefreshable(grant) {
+  return grant.refresh_token !== void 0 && grant.refresh_token !== "";
+}
+async function refreshGrant(grant, fetchImpl = globalThis.fetch) {
+  if (!isGrantRefreshable(grant)) {
+    throw new AuthCodeError(
+      "not_refreshable",
+      "grant has expired and carries no refresh_token \u2014 re-authorize"
+    );
+  }
+  const form = {
+    grant_type: "refresh_token",
+    refresh_token: grant.refresh_token,
+    client_id: grant.client_id
+  };
+  if (grant.resource) form.resource = grant.resource;
+  const token = await postForm(fetchImpl, grant.token_endpoint, form);
+  return {
+    access_token: token.access_token,
+    // A server that does not rotate returns no new refresh token; keep the
+    // existing one rather than silently making the grant unrefreshable.
+    refresh_token: token.refresh_token ?? grant.refresh_token,
+    expires_at: token.expires_in === void 0 ? void 0 : nowSecs() + token.expires_in,
+    client_id: grant.client_id,
+    token_endpoint: grant.token_endpoint,
+    scope: token.scope ?? grant.scope,
+    resource: grant.resource
+  };
+}
+var AuthCodeFlow = class _AuthCodeFlow {
+  fetchImpl;
+  metadataDoc;
+  /** The protected resource this grant will be bound to (RFC 8707). */
+  resource;
+  clientIdValue;
+  redirectUriValue;
+  scope = DEFAULT_SCOPE;
+  constructor(fetchImpl, metadata, resource) {
+    this.fetchImpl = fetchImpl;
+    this.metadataDoc = metadata;
+    this.resource = resource;
+  }
+  /**
+   * Discover the authorization server protecting `resourceUrl`.
+   *
+   * `resourceUrl` is the MCP endpoint being connected to — for DataGrout,
+   * `https://gateway.datagrout.ai/connect` or a `.../servers/{uuid}/mcp` URL.
+   *
+   * Tries RFC 9728 protected-resource metadata first, then RFC 8414
+   * authorization-server metadata on whatever that names. Falls back to the
+   * resource's own origin, which is where DataGrout serves it.
+   */
+  static async discover(resourceUrl, fetchImpl = globalThis.fetch) {
+    const resource = resourceUrl.replace(/\/+$/, "");
+    const prm = await fetchResourceMetadata(fetchImpl, resource);
+    let issuer;
+    if (prm?.authorization_servers && prm.authorization_servers.length > 0) {
+      issuer = prm.authorization_servers[0];
+    } else {
+      issuer = originOf(resource);
+    }
+    if (!issuer) {
+      throw new AuthCodeError("discovery", `not a URL: ${resource}`);
+    }
+    const metadata = await fetchAsMetadata(fetchImpl, issuer);
+    if (!supportsS256(metadata)) {
+      throw new AuthCodeError(
+        "pkce_unsupported",
+        "authorization server does not support PKCE S256; refusing to downgrade"
+      );
+    }
+    return new _AuthCodeFlow(fetchImpl, metadata, resource);
+  }
+  /** Use a client id registered out of band, skipping dynamic registration. */
+  withClientId(clientId, redirectUri) {
+    this.clientIdValue = clientId;
+    this.redirectUriValue = redirectUri;
+    return this;
+  }
+  /**
+   * Reuse a client registered on a previous run.
+   *
+   * Prefer this over {@link withClientId}: it carries the redirect URI with the
+   * id, which is not optional bookkeeping — an authorization server matches the
+   * redirect URI **exactly** against what was registered, so a client id reused
+   * with a different URI is rejected.
+   */
+  withRegisteredClient(client) {
+    return this.withClientId(client.client_id, client.redirect_uri);
+  }
+  /** Request scopes other than {@link DEFAULT_SCOPE}. */
+  withScope(scope) {
+    this.scope = scope;
+    return this;
+  }
+  /** The discovered metadata. */
+  get metadata() {
+    return this.metadataDoc;
+  }
+  /** The client id, once registered or supplied. */
+  get clientId() {
+    return this.clientIdValue;
+  }
+  /** The redirect URI this flow is bound to. */
+  get redirectUri() {
+    return this.redirectUriValue;
+  }
+  /**
+   * Register this application via RFC 7591 dynamic client registration.
+   *
+   * Registers a **public client** — `token_endpoint_auth_method: "none"`, no
+   * secret issued. A desktop or CLI application cannot keep a secret, and PKCE
+   * is what stands in for one.
+   *
+   * Returns the id **and** the redirect URI it is bound to. Persist the pair
+   * and restore it with {@link withRegisteredClient} — re-registering on every
+   * launch creates a new client record each time, and reusing an id against a
+   * different redirect URI is rejected.
+   */
+  async register(clientName, redirectUri) {
+    const endpoint = this.metadataDoc.registration_endpoint;
+    if (!endpoint) {
+      throw new AuthCodeError(
+        "no_registration_endpoint",
+        "authorization server has no registration endpoint \u2014 register a client manually and use withClientId()"
+      );
+    }
+    let response;
+    try {
+      response = await this.fetchImpl(endpoint, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          client_name: clientName,
+          redirect_uris: [redirectUri],
+          grant_types: ["authorization_code", "refresh_token"],
+          response_types: ["code"],
+          token_endpoint_auth_method: "none",
+          application_type: "native"
+        })
+      });
+    } catch (err) {
+      throw new AuthCodeError("http", `HTTP error: ${err}`);
+    }
+    if (!response.ok) {
+      const body = await response.text().catch(() => "");
+      throw new AuthCodeError(
+        "registration_rejected",
+        `client registration rejected (HTTP ${response.status}): ${body}`,
+        { status: response.status, body }
+      );
+    }
+    let clientId;
+    try {
+      const parsed = await response.json();
+      clientId = parsed.client_id;
+    } catch (err) {
+      throw new AuthCodeError("http", `bad registration response: ${err}`);
+    }
+    this.clientIdValue = clientId;
+    this.redirectUriValue = redirectUri;
+    return { client_id: clientId, redirect_uri: redirectUri };
+  }
+  /**
+   * Build the consent URL, plus the {@link PendingAuthorization} needed to
+   * redeem the resulting code.
+   *
+   * The caller opens the URL however suits it — a browser, a printed
+   * instruction, a QR code. This SDK does not launch browsers.
+   */
+  authorizeUrl() {
+    const clientId = this.clientIdValue;
+    const redirectUri = this.redirectUriValue;
+    if (!clientId || !redirectUri) {
+      throw new AuthCodeError(
+        "no_client_id",
+        "no client_id \u2014 call register() or withClientId() first"
+      );
+    }
+    const codeVerifier = generateVerifier();
+    const state = generateState();
+    const query = [
+      ["response_type", "code"],
+      ["client_id", clientId],
+      ["redirect_uri", redirectUri],
+      ["scope", this.scope],
+      ["state", state],
+      ["code_challenge", challengeS256(codeVerifier)],
+      ["code_challenge_method", "S256"],
+      // RFC 8707: bind the token to this resource so it cannot be replayed
+      // against a different one.
+      ["resource", this.resource]
+    ].map(([k, v]) => `${k}=${urlencode(v)}`).join("&");
+    const separator = this.metadataDoc.authorization_endpoint.includes("?") ? "&" : "?";
+    const url = `${this.metadataDoc.authorization_endpoint}${separator}${query}`;
+    return { url, pending: { codeVerifier, state, redirectUri } };
+  }
+  /**
+   * Redeem an authorization code for a {@link Grant}.
+   *
+   * `returnedState` is the `state` parameter from the redirect. It is checked
+   * against the pending request before anything is sent: a mismatch means the
+   * response belongs to a different authorization request, and the exchange is
+   * refused rather than attempted.
+   */
+  async exchange(pending, code, returnedState) {
+    if (!constantTimeEqual(pending.state, returnedState)) {
+      throw new AuthCodeError(
+        "state_mismatch",
+        "state mismatch \u2014 the authorization response does not match this request"
+      );
+    }
+    const clientId = this.clientIdValue;
+    if (!clientId) {
+      throw new AuthCodeError(
+        "no_client_id",
+        "no client_id \u2014 call register() or withClientId() first"
+      );
+    }
+    const token = await postForm(
+      this.fetchImpl,
+      this.metadataDoc.token_endpoint,
+      {
+        grant_type: "authorization_code",
+        code,
+        redirect_uri: pending.redirectUri,
+        client_id: clientId,
+        code_verifier: pending.codeVerifier,
+        resource: this.resource
+      }
+    );
+    return {
+      access_token: token.access_token,
+      refresh_token: token.refresh_token,
+      expires_at: token.expires_in === void 0 ? void 0 : nowSecs() + token.expires_in,
+      client_id: clientId,
+      token_endpoint: this.metadataDoc.token_endpoint,
+      scope: token.scope,
+      resource: this.resource
+    };
+  }
+};
+var AuthCodeProvider = class {
+  grantValue;
+  dirty = false;
+  refreshPromise = null;
+  fetchImpl;
+  constructor(grant, fetchImpl = globalThis.fetch) {
+    this.grantValue = grant;
+    this.fetchImpl = fetchImpl;
+  }
+  /** The current access token, refreshing first if it is at or near expiry. */
+  async getToken() {
+    if (!isGrantExpired(this.grantValue)) {
+      return this.grantValue.access_token;
+    }
+    if (!this.refreshPromise) {
+      this.refreshPromise = refreshGrant(this.grantValue, this.fetchImpl).then((refreshed2) => {
+        this.grantValue = refreshed2;
+        this.dirty = true;
+        return refreshed2;
+      }).finally(() => {
+        this.refreshPromise = null;
+      });
+    }
+    const refreshed = await this.refreshPromise;
+    return refreshed.access_token;
+  }
+  /** A snapshot of the current grant, for persisting. */
+  grant() {
+    return { ...this.grantValue };
+  }
+  /** Whether the grant changed since the last {@link takeIfDirty}. */
+  isDirty() {
+    return this.dirty;
+  }
+  /**
+   * Return the grant if it has changed since the last call, clearing the flag.
+   *
+   * The intended use is a persistence loop: call periodically and write
+   * whatever comes back, so a rotated refresh token is never lost.
+   */
+  takeIfDirty() {
+    if (!this.dirty) return null;
+    this.dirty = false;
+    return this.grant();
+  }
+  /** Force the next {@link getToken} to refresh. Call on a 401. */
+  invalidate() {
+    this.grantValue = { ...this.grantValue, expires_at: 0 };
+  }
+};
+function authCodeProviderFrom(value, fetchImpl = globalThis.fetch) {
+  if (value === void 0) return void 0;
+  if (value instanceof AuthCodeProvider) return value;
+  return new AuthCodeProvider(value, fetchImpl);
+}
+function generateVerifier() {
+  return (0, import_node_crypto.randomBytes)(32).toString("base64url");
+}
+function challengeS256(verifier) {
+  return (0, import_node_crypto.createHash)("sha256").update(verifier, "utf8").digest("base64url");
+}
+function generateState() {
+  return (0, import_node_crypto.randomBytes)(16).toString("base64url");
+}
+function nowSecs() {
+  return Math.floor(Date.now() / 1e3);
+}
+function constantTimeEqual(a, b) {
+  const ab = Buffer.from(a, "utf8");
+  const bb = Buffer.from(b, "utf8");
+  if (ab.length !== bb.length) return false;
+  if (ab.length === 0) return true;
+  return (0, import_node_crypto.timingSafeEqual)(ab, bb);
+}
+function urlencode(value) {
+  let out = "";
+  for (const byte of Buffer.from(value, "utf8")) {
+    const ch = String.fromCharCode(byte);
+    if (/[A-Za-z0-9\-._~]/.test(ch)) {
+      out += ch;
+    } else {
+      out += `%${byte.toString(16).toUpperCase().padStart(2, "0")}`;
+    }
+  }
+  return out;
+}
+function originOf(url) {
+  try {
+    const parsed = new URL(url);
+    if (!parsed.hostname) return void 0;
+    return parsed.port ? `${parsed.protocol}//${parsed.hostname}:${parsed.port}` : `${parsed.protocol}//${parsed.hostname}`;
+  } catch {
+    return void 0;
+  }
+}
+async function fetchResourceMetadata(fetchImpl, resource) {
+  const origin = originOf(resource);
+  const candidates = [
+    `${resource}/.well-known/oauth-protected-resource`,
+    origin ? `${origin}/.well-known/oauth-protected-resource` : void 0
+  ].filter((u) => u !== void 0);
+  for (const url of candidates) {
+    try {
+      const resp = await fetchImpl(url);
+      if (resp.ok) {
+        return await resp.json();
+      }
+    } catch {
+    }
+  }
+  return void 0;
+}
+async function fetchAsMetadata(fetchImpl, issuer) {
+  const base = issuer.replace(/\/+$/, "");
+  const candidates = [
+    `${base}/.well-known/oauth-authorization-server`,
+    `${base}/.well-known/openid-configuration`
+  ];
+  let last = "";
+  for (const url of candidates) {
+    try {
+      const resp = await fetchImpl(url);
+      if (resp.ok) {
+        try {
+          return await resp.json();
+        } catch (err) {
+          throw new AuthCodeError(
+            "discovery",
+            `OAuth discovery failed: bad metadata at ${url}: ${err}`
+          );
+        }
+      }
+      last = `${url} \u2192 HTTP ${resp.status}`;
+    } catch (err) {
+      if (err instanceof AuthCodeError) throw err;
+      last = `${url} \u2192 ${err}`;
+    }
+  }
+  throw new AuthCodeError(
+    "discovery",
+    `OAuth discovery failed: no authorization server metadata found (last attempt: ${last})`
+  );
+}
+async function postForm(fetchImpl, endpoint, form) {
+  let response;
+  try {
+    response = await fetchImpl(endpoint, {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body: new URLSearchParams(form).toString()
+    });
+  } catch (err) {
+    throw new AuthCodeError("http", `HTTP error: ${err}`);
+  }
+  if (!response.ok) {
+    const body = await response.text().catch(() => "");
+    throw new AuthCodeError(
+      "token_exchange",
+      `token exchange failed (HTTP ${response.status}): ${body}`,
+      { status: response.status, body }
+    );
+  }
+  try {
+    return await response.json();
+  } catch (err) {
+    throw new AuthCodeError("http", `bad token response: ${err}`);
+  }
+}
+
+// src/transports/mcp.ts
 var import_client = require("@modelcontextprotocol/sdk/client/index.js");
 var import_sse = require("@modelcontextprotocol/sdk/client/sse.js");
 var import_stdio = require("@modelcontextprotocol/sdk/client/stdio.js");
@@ -486,6 +999,10 @@ var MCPTransport = class extends Transport {
   client;
   clientTransport;
   oauthProvider;
+  /** Present only when `auth.authorizationCode` is set. */
+  authCodeProvider;
+  /** Present only when `auth.delegation` is set (RFC 8693). */
+  delegatedProvider;
   constructor(url, auth, identity) {
     super();
     this.url = url;
@@ -501,12 +1018,20 @@ var MCPTransport = class extends Transport {
         scope: cc.scope
       });
     }
+    this.authCodeProvider = authCodeProviderFrom(auth?.authorizationCode);
+    this.delegatedProvider = auth?.delegation;
   }
   async buildHeaders() {
     const headers = {};
-    if (this.oauthProvider) {
+    if (this.delegatedProvider) {
+      const token = await this.delegatedProvider.getToken();
+      headers["Authorization"] = `Bearer ${token}`;
+    } else if (this.oauthProvider) {
       const token = await this.oauthProvider.getToken();
       headers["Authorization"] = `Bearer ${token}`;
+    } else if (this.authCodeProvider) {
+      const token = await this.authCodeProvider.getToken();
+      headers["Authorization"] = `Bearer ${token}`;
     } else if (this.auth?.bearer) {
       headers["Authorization"] = `Bearer ${this.auth.bearer}`;
     } else if (this.auth?.basic) {
@@ -536,7 +1061,10 @@ var MCPTransport = class extends Transport {
       if (this.identity) {
         const id = this.identity;
         transportOpts.fetcher = (url, init) => {
-          const { fetchWithIdentity: fetchWithIdentity2 } = (init_identity(), __toCommonJS(identity_exports));
+          const { fetchWithIdentity: fetchWithIdentity2 } = (
+            // eslint-disable-next-line @typescript-eslint/no-require-imports
+            (init_identity(), __toCommonJS(identity_exports))
+          );
           return fetchWithIdentity2(
             typeof url === "string" ? url : url instanceof URL ? url.toString() : url.url,
             init ?? {},
@@ -552,7 +1080,7 @@ var MCPTransport = class extends Transport {
       throw new Error(`Unsupported MCP URL scheme: ${this.url}`);
     }
     this.client = new import_client.Client(
-      { name: "datagrout-conduit", version: "0.1.0" },
+      { name: "datagrout-conduit", version },
       { capabilities: {} }
     );
     await this.client.connect(this.clientTransport);
@@ -574,7 +1102,11 @@ var MCPTransport = class extends Transport {
       annotations: tool.annotations
     }));
   }
-  async callTool(name, args, options) {
+  // `_options` on this and the four methods below: accepted for signature
+  // parity with the other conduit SDKs, not yet consulted here. The leading
+  // underscore is the codebase's marker for a deliberately unused parameter,
+  // and what tsconfig's `noUnusedParameters` exempts.
+  async callTool(name, args, _options) {
     if (!this.client) {
       throw new Error("Not connected. Call connect() first.");
     }
@@ -596,7 +1128,7 @@ var MCPTransport = class extends Transport {
     }
     return result;
   }
-  async listResources(options) {
+  async listResources(_options) {
     if (!this.client) {
       throw new Error("Not connected. Call connect() first.");
     }
@@ -608,14 +1140,14 @@ var MCPTransport = class extends Transport {
       mimeType: resource.mimeType
     }));
   }
-  async readResource(uri, options) {
+  async readResource(uri, _options) {
     if (!this.client) {
       throw new Error("Not connected. Call connect() first.");
     }
     const result = await this.client.readResource({ uri });
     return result.contents;
   }
-  async listPrompts(options) {
+  async listPrompts(_options) {
     if (!this.client) {
       throw new Error("Not connected. Call connect() first.");
     }
@@ -626,7 +1158,7 @@ var MCPTransport = class extends Transport {
       arguments: prompt.arguments
     }));
   }
-  async getPrompt(name, args, options) {
+  async getPrompt(name, args, _options) {
     if (!this.client) {
       throw new Error("Not connected. Call connect() first.");
     }
@@ -638,56 +1170,6 @@ var MCPTransport = class extends Transport {
 // src/transports/jsonrpc.ts
 init_identity();
 init_oauth();
-
-// src/errors.ts
-var ConduitError = class extends Error {
-  constructor(message) {
-    super(message);
-    this.name = this.constructor.name;
-    Object.setPrototypeOf(this, new.target.prototype);
-  }
-};
-var NotInitializedError = class extends ConduitError {
-  constructor() {
-    super("Client not initialized. Call connect() first.");
-  }
-};
-var RateLimitError = class extends ConduitError {
-  status;
-  retryAfter;
-  constructor(status, retryAfter) {
-    const limitStr = status.limit === "unlimited" ? "unlimited" : `${status.limit.perHour}/hour`;
-    super(`Rate limit exceeded (${status.used} / ${limitStr} calls this hour)`);
-    this.status = status;
-    this.retryAfter = retryAfter;
-  }
-};
-var AuthError = class extends ConduitError {
-  constructor(message = "Authentication failed") {
-    super(message);
-  }
-};
-var NetworkError = class extends ConduitError {
-  constructor(message) {
-    super(message);
-  }
-};
-var ServerError = class extends ConduitError {
-  code;
-  serverMessage;
-  constructor(code, serverMessage) {
-    super(`Server error ${code}: ${serverMessage}`);
-    this.code = code;
-    this.serverMessage = serverMessage;
-  }
-};
-var InvalidConfigError = class extends ConduitError {
-  constructor(message) {
-    super(message);
-  }
-};
-
-// src/transports/jsonrpc.ts
 function unwrapContent(result) {
   if (!result) return result;
   if (result.structuredContent !== void 0) {
@@ -722,6 +1204,10 @@ var JSONRPCTransport = class extends Transport {
   requestId = 0;
   /** Resolved token provider, present only when `auth.clientCredentials` is set. */
   oauthProvider;
+  /** Present only when `auth.authorizationCode` is set. */
+  authCodeProvider;
+  /** Present only when `auth.delegation` is set (RFC 8693). */
+  delegatedProvider;
   constructor(url, auth, timeout = 3e4, identity) {
     super();
     this.url = url;
@@ -736,7 +1222,10 @@ var JSONRPCTransport = class extends Transport {
     if (auth?.clientCredentials) {
       const cc = auth.clientCredentials;
       const tokenEndpoint = cc.tokenEndpoint ?? (() => {
-        const { deriveTokenEndpoint: deriveTokenEndpoint2 } = (init_oauth(), __toCommonJS(oauth_exports));
+        const { deriveTokenEndpoint: deriveTokenEndpoint2 } = (
+          // eslint-disable-next-line @typescript-eslint/no-require-imports
+          (init_oauth(), __toCommonJS(oauth_exports))
+        );
         return deriveTokenEndpoint2(url);
       })();
       this.oauthProvider = new OAuthTokenProvider({
@@ -746,6 +1235,8 @@ var JSONRPCTransport = class extends Transport {
         scope: cc.scope
       });
     }
+    this.authCodeProvider = authCodeProviderFrom(auth?.authorizationCode);
+    this.delegatedProvider = auth?.delegation;
   }
   async connect() {
   }
@@ -758,9 +1249,15 @@ var JSONRPCTransport = class extends Transport {
     const headers = {
       "Content-Type": "application/json"
     };
-    if (this.oauthProvider) {
+    if (this.delegatedProvider) {
+      const token = await this.delegatedProvider.getToken();
+      headers["Authorization"] = `Bearer ${token}`;
+    } else if (this.oauthProvider) {
       const token = await this.oauthProvider.getToken();
       headers["Authorization"] = `Bearer ${token}`;
+    } else if (this.authCodeProvider) {
+      const token = await this.authCodeProvider.getToken();
+      headers["Authorization"] = `Bearer ${token}`;
     } else if (this.auth?.bearer) {
       headers["Authorization"] = `Bearer ${this.auth.bearer}`;
     } else if (this.auth?.basic) {
@@ -790,9 +1287,19 @@ var JSONRPCTransport = class extends Transport {
       if (response.status === 429) {
         throw parseRateLimitError(response);
       }
-      if (response.status === 401 && this.oauthProvider && !isRetry) {
-        this.oauthProvider.invalidate();
-        return this._callWithRetry(method, params, true);
+      if (response.status === 401 && !isRetry) {
+        if (this.delegatedProvider) {
+          this.delegatedProvider.invalidate();
+          return this._callWithRetry(method, params, true);
+        }
+        if (this.oauthProvider) {
+          this.oauthProvider.invalidate();
+          return this._callWithRetry(method, params, true);
+        }
+        if (this.authCodeProvider) {
+          this.authCodeProvider.invalidate();
+          return this._callWithRetry(method, params, true);
+        }
       }
       if (!response.ok) {
         throw new Error(`HTTP ${response.status}: ${response.statusText}`);
@@ -834,8 +1341,10 @@ var JSONRPCTransport = class extends Transport {
 };
 
 // src/transports/ws.ts
+init_oauth();
 var SUBPROTOCOL = "datagrout-jsonrpc.v1";
 var SUBSCRIPTION_BUFFER = 256;
+var PING_INTERVAL_MS = 25e3;
 var Subscription = class {
   id;
   topic;
@@ -896,12 +1405,40 @@ var Subscription = class {
 var WsTransport = class extends Transport {
   _url;
   _auth;
+  /**
+   * mTLS identity presented on the `wss://` handshake, if any.  The HTTP
+   * transports route through {@link fetchWithIdentity}; here the PEMs go to the
+   * `ws` client as `cert` / `key` / `ca` options, which it forwards to
+   * `tls.connect`.  Mirrors `build_connector` in the Rust reference.
+   */
+  _identity;
+  /**
+   * Resolved OAuth providers, built once so a token survives reconnects.
+   *
+   * All are consulted in {@link _resolveBearer} before the upgrade request is
+   * built — see the note there on why that has to happen up front.
+   */
+  _oauthProvider;
+  _authCodeProvider;
+  /** RFC 8693 delegation, when `auth.delegation` is set. */
+  _delegatedProvider;
   _ws = null;
   _nextId = 0;
   _pending = /* @__PURE__ */ new Map();
   _pendingSubscribe = /* @__PURE__ */ new Map();
   _subscriptions = /* @__PURE__ */ new Map();
-  constructor(url, auth, _timeout, _identity) {
+  /**
+   * Handle for the recurring ping timer; non-null only while connected.
+   * Cleared on disconnect / close.  Set indirectly via {@link _startPingTimer}.
+   */
+  _pingTimer = null;
+  /**
+   * Interval in ms between client-initiated ping frames.  Public-readable so
+   * tests can inject a small value via {@link WsTransport.setPingInterval};
+   * defaults to {@link PING_INTERVAL_MS}.
+   */
+  _pingIntervalMs = PING_INTERVAL_MS;
+  constructor(url, auth, _timeout, identity) {
     super();
     const scheme = new URL(url).protocol.replace(":", "");
     if (scheme !== "ws" && scheme !== "wss") {
@@ -911,14 +1448,46 @@ var WsTransport = class extends Transport {
     }
     this._url = url;
     this._auth = auth;
+    this._identity = identity;
+    if (auth?.clientCredentials) {
+      const cc = auth.clientCredentials;
+      const tokenEndpoint = cc.tokenEndpoint ?? deriveTokenEndpoint(url.replace(/^ws/, "http"));
+      this._oauthProvider = new OAuthTokenProvider({
+        clientId: cc.clientId,
+        clientSecret: cc.clientSecret,
+        tokenEndpoint,
+        scope: cc.scope
+      });
+    }
+    this._authCodeProvider = authCodeProviderFrom(auth?.authorizationCode);
+    this._delegatedProvider = auth?.delegation;
   }
   // ── Lifecycle ─────────────────────────────────────────────────────────────
+  /**
+   * The bearer to put on the upgrade request, if any.
+   *
+   * Resolved *before* the handshake is built. Fetching a token is async while
+   * header construction is not, so a provider-backed token could never reach
+   * the upgrade if it were resolved inside the header builder — which is
+   * exactly the bug this replaced: an OAuth client authenticated over WS only
+   * if it also happened to present an mTLS identity.
+   */
+  async _resolveBearer() {
+    if (this._delegatedProvider) return this._delegatedProvider.getToken();
+    if (this._oauthProvider) return this._oauthProvider.getToken();
+    if (this._authCodeProvider) return this._authCodeProvider.getToken();
+    return void 0;
+  }
   async connect() {
     if (this._ws !== null) return;
     const WsImpl = await resolveWebSocketImpl();
-    const headers = buildUpgradeHeaders(this._auth);
+    const headers = buildUpgradeHeaders(
+      this._auth,
+      await this._resolveBearer()
+    );
     const ws = new WsImpl(this._url, [SUBPROTOCOL], {
-      headers
+      headers,
+      ...buildTlsOptions(this._url, this._identity)
     });
     await new Promise((resolve, reject) => {
       ws.onopen = () => resolve();
@@ -930,13 +1499,16 @@ var WsTransport = class extends Transport {
     ws.onerror = (_ev) => this._failAll("WS connection error");
     ws.onclose = () => {
       this._failAll("WS connection closed");
+      this._stopPingTimer();
       this._ws = null;
     };
     this._ws = ws;
+    this._startPingTimer();
   }
   async disconnect() {
     const ws = this._ws;
     this._ws = null;
+    this._stopPingTimer();
     this._failAll("WS connection closed");
     if (ws !== null) {
       try {
@@ -945,6 +1517,42 @@ var WsTransport = class extends Transport {
       }
     }
   }
+  // ── Ping keepalive ────────────────────────────────────────────────────────
+  /**
+   * Override the ping interval (ms) — used by tests to avoid 25-second waits.
+   * Must be called BEFORE {@link connect}; has no effect on an already-running
+   * timer.  In production code, leave the default ({@link PING_INTERVAL_MS}).
+   */
+  setPingInterval(intervalMs) {
+    this._pingIntervalMs = intervalMs;
+  }
+  /** Tracks how many ping frames this transport has sent — for tests. */
+  get pingsSent() {
+    return this._pingsSent;
+  }
+  _pingsSent = 0;
+  _startPingTimer() {
+    if (this._pingTimer !== null || this._pingIntervalMs <= 0) return;
+    this._pingTimer = setInterval(() => {
+      const ws = this._ws;
+      if (ws === null) return;
+      if (typeof ws.ping === "function") {
+        try {
+          ws.ping();
+          this._pingsSent += 1;
+        } catch {
+        }
+      }
+    }, this._pingIntervalMs);
+    const t = this._pingTimer;
+    if (typeof t.unref === "function") t.unref();
+  }
+  _stopPingTimer() {
+    if (this._pingTimer !== null) {
+      clearInterval(this._pingTimer);
+      this._pingTimer = null;
+    }
+  }
   // ── Subscriptions ─────────────────────────────────────────────────────────
   /**
    * Open a server-side push subscription for `topic`.
@@ -1113,8 +1721,12 @@ var WsTransport = class extends Transport {
     this._subscriptions.clear();
   }
 };
-function buildUpgradeHeaders(auth) {
+function buildUpgradeHeaders(auth, resolvedBearer) {
   const headers = {};
+  if (resolvedBearer !== void 0) {
+    headers["Authorization"] = `Bearer ${resolvedBearer}`;
+    return headers;
+  }
   if (auth === void 0) return headers;
   if ("bearer" in auth && auth.bearer !== void 0) {
     headers["Authorization"] = `Bearer ${auth.bearer}`;
@@ -1128,6 +1740,21 @@ function buildUpgradeHeaders(auth) {
   }
   return headers;
 }
+function buildTlsOptions(url, identity) {
+  if (identity === void 0) return {};
+  if (!url.startsWith("wss:")) return {};
+  if (typeof process === "undefined" || !process.versions?.node) {
+    console.warn(
+      "[conduit] mTLS identity is set but this environment does not support client certificates on WebSocket.  The connection will proceed without mTLS."
+    );
+    return {};
+  }
+  return {
+    cert: identity.certPem,
+    key: identity.keyPem,
+    ...identity.caPem ? { ca: identity.caPem } : {}
+  };
+}
 async function resolveWebSocketImpl() {
   if (typeof globalThis.WebSocket !== "undefined") {
     return globalThis.WebSocket;
@@ -1313,6 +1940,8 @@ var PrismNamespace = class {
     this.callDg = callDg;
     this.warn = warn;
   }
+  callDg;
+  warn;
   /** AI-driven data transformation (`data-grout/prism.refract`). */
   async refract(options) {
     this.warn("prism.refract");
@@ -1382,6 +2011,8 @@ var LogicNamespace = class {
     this.callDg = callDg;
     this.warn = warn;
   }
+  callDg;
+  warn;
   async remember(statementOrOptions, optionsArg) {
     let statement;
     let opts;
@@ -1490,6 +2121,8 @@ var WardenNamespace = class {
     this.callDg = callDg;
     this.warn = warn;
   }
+  callDg;
+  warn;
   /** Run a canary safety check (`data-grout/warden.canary`). */
   async canary(params) {
     this.warn("warden.canary");
@@ -1519,6 +2152,8 @@ var DeliverablesNamespace = class {
     this.callDg = callDg;
     this.warn = warn;
   }
+  callDg;
+  warn;
   /** Register a work product (`data-grout/deliverables.register`). */
   async register(params) {
     this.warn("deliverables.register");
@@ -1543,6 +2178,8 @@ var EphemeralsNamespace = class {
     this.callDg = callDg;
     this.warn = warn;
   }
+  callDg;
+  warn;
   /** List cached results (`data-grout/ephemerals.list`). */
   async list(params = {}) {
     this.warn("ephemerals.list");
@@ -1562,6 +2199,8 @@ var FlowNamespace = class {
     this.callDg = callDg;
     this.warn = warn;
   }
+  callDg;
+  warn;
   /** Execute a multi-step workflow plan (`data-grout/flow.into`). */
   async run(options) {
     this.warn("flow.into");
@@ -1948,7 +2587,7 @@ var Client2 = class _Client {
   async listTools(options) {
     this.ensureInitialized();
     return this.sendWithRetry(async () => {
-      let allTools = [];
+      const allTools = [];
       let cursor;
       do {
         const response = await this.transport.listTools({ ...options, cursor });
@@ -2286,6 +2925,637 @@ var Client2 = class _Client {
 init_identity();
 init_oauth();
 
+// src/delegation.ts
+var GRANT_TYPE = "urn:ietf:params:oauth:grant-type:token-exchange";
+var INSPECT_CUSTOM = /* @__PURE__ */ Symbol.for("nodejs.util.inspect.custom");
+var REFRESH_SKEW_SECS2 = 60;
+var SERVER_ERROR_CODES = Object.freeze([
+  /** Malformed request, or a required parameter missing. */
+  "invalid_request",
+  /** Client authentication failed. */
+  "invalid_client",
+  /** The subject or actor token is invalid, expired, or revoked. */
+  "invalid_grant",
+  /** This client may not use this grant — including a client that is not the actor. */
+  "unauthorized_client",
+  /** The requested `audience` or `resource` is not served here (RFC 8693 §2.2.2). */
+  "invalid_target",
+  /** A requested scope is unknown or exceeds what the subject token allows. */
+  "invalid_scope",
+  /** The server does not support the exchange. */
+  "unsupported_grant_type"
+]);
+var TOKEN_TYPES = Object.freeze({
+  /** The default for both subject and actor, and what DataGrout issues. */
+  access_token: "urn:ietf:params:oauth:token-type:access_token",
+  /** A JWT presented as a JWT rather than as an opaque access token. */
+  jwt: "urn:ietf:params:oauth:token-type:jwt",
+  id_token: "urn:ietf:params:oauth:token-type:id_token",
+  refresh_token: "urn:ietf:params:oauth:token-type:refresh_token",
+  saml2: "urn:ietf:params:oauth:token-type:saml2"
+});
+function tokenTypeName(tokenType) {
+  for (const [name, urn] of Object.entries(TOKEN_TYPES)) {
+    if (urn === tokenType) return name;
+  }
+  return "other";
+}
+var DelegationError = class extends ConduitError {
+  kind;
+  /** HTTP status, for `server`. */
+  status;
+  /** RFC 6749 error code, for `server`; see {@link SERVER_ERROR_CODES}. */
+  error;
+  /** Human-readable description, when the server gave one. */
+  errorDescription;
+  constructor(kind, message, extra) {
+    super(message);
+    this.kind = kind;
+    this.status = extra?.status;
+    this.error = extra?.error;
+    this.errorDescription = extra?.errorDescription;
+  }
+};
+var DelegationRequest = class _DelegationRequest {
+  endpoint;
+  client;
+  secret;
+  auth = "body";
+  subject;
+  actor;
+  audienceValue;
+  resourceValue;
+  scopeValue;
+  requestedTokenTypeValue;
+  impersonating = false;
+  /**
+   * Start a request against `tokenEndpoint`, authenticating as `clientId`.
+   *
+   * The client should be the actor — see the module docs.
+   */
+  constructor(tokenEndpoint, clientId) {
+    this.endpoint = tokenEndpoint;
+    this.client = clientId;
+  }
+  /** The client secret, for confidential clients. */
+  clientSecret(secret) {
+    this.secret = secret;
+    return this;
+  }
+  /** Where the client secret travels. Defaults to `"body"`. */
+  clientAuth(auth) {
+    this.auth = auth;
+    return this;
+  }
+  /**
+   * The token being exchanged: the **user's**, whose identity the issued token
+   * will carry as `sub`.
+   */
+  subjectToken(token, tokenType = TOKEN_TYPES.access_token) {
+    this.subject = { token, tokenType };
+    return this;
+  }
+  /** The **agent's** own token, which the issued token will name in `act`. */
+  actorToken(token, tokenType = TOKEN_TYPES.access_token) {
+    this.actor = { token, tokenType };
+    return this;
+  }
+  /** Logical name of the service the token is for (RFC 8693 `audience`). */
+  audience(audience) {
+    this.audienceValue = audience;
+    return this;
+  }
+  /**
+   * URI of the resource the token is for (RFC 8707 `resource`). Always sent
+   * when set, so the token cannot be replayed elsewhere.
+   */
+  resource(resource) {
+    this.resourceValue = resource;
+    return this;
+  }
+  /** Scopes to request, space-separated. */
+  scope(scope) {
+    this.scopeValue = scope;
+    return this;
+  }
+  /** The kind of token wanted back. Servers default to an access token. */
+  requestedTokenType(tokenType) {
+    this.requestedTokenTypeValue = tokenType;
+    return this;
+  }
+  /**
+   * Opt out of delegation: send no `actor_token`, so the issued token has no
+   * `act` claim and the agent is indistinguishable from the user.
+   *
+   * DataGrout does not issue these. This exists for other RFC 8693 servers, and
+   * it is a builder call rather than a default precisely so that forgetting to
+   * set an actor is an error instead of a silent downgrade.
+   */
+  impersonation() {
+    this.impersonating = true;
+    return this;
+  }
+  /** The token endpoint this request posts to. */
+  get tokenEndpoint() {
+    return this.endpoint;
+  }
+  /** The client id this request authenticates as. */
+  get clientId() {
+    return this.client;
+  }
+  /** Whether {@link impersonation} was called. */
+  get isImpersonation() {
+    return this.impersonating;
+  }
+  /** An independent copy, so a template can be filled in per exchange. */
+  clone() {
+    const copy = new _DelegationRequest(this.endpoint, this.client);
+    copy.secret = this.secret;
+    copy.auth = this.auth;
+    copy.subject = this.subject && { ...this.subject };
+    copy.actor = this.actor && { ...this.actor };
+    copy.audienceValue = this.audienceValue;
+    copy.resourceValue = this.resourceValue;
+    copy.scopeValue = this.scopeValue;
+    copy.requestedTokenTypeValue = this.requestedTokenTypeValue;
+    copy.impersonating = this.impersonating;
+    return copy;
+  }
+  /**
+   * The form body this request will post, in wire order.
+   *
+   * Throws before any network activity when the request is incomplete:
+   * `missing_subject`, or `missing_actor` unless {@link impersonation} was
+   * called. Public so a caller — or another SDK's test suite — can check the
+   * body against the contract fixture without a server.
+   */
+  formParams() {
+    if (this.subject === void 0) {
+      throw new DelegationError(
+        "missing_subject",
+        "no subject_token \u2014 call subjectToken() first"
+      );
+    }
+    const form = [
+      ["grant_type", GRANT_TYPE],
+      ["subject_token", this.subject.token],
+      ["subject_token_type", this.subject.tokenType]
+    ];
+    if (this.actor !== void 0) {
+      form.push(["actor_token", this.actor.token]);
+      form.push(["actor_token_type", this.actor.tokenType]);
+    } else if (!this.impersonating) {
+      throw new DelegationError(
+        "missing_actor",
+        "no actor_token \u2014 delegation requires one; call impersonation() to opt out explicitly"
+      );
+    }
+    form.push(["client_id", this.client]);
+    if (this.secret !== void 0 && this.auth === "body") {
+      form.push(["client_secret", this.secret]);
+    }
+    for (const [key, value] of [
+      ["audience", this.audienceValue],
+      ["resource", this.resourceValue],
+      ["scope", this.scopeValue],
+      ["requested_token_type", this.requestedTokenTypeValue]
+    ]) {
+      if (value !== void 0) form.push([key, value]);
+    }
+    return form;
+  }
+  /** Perform the exchange. */
+  async exchange(fetchImpl = globalThis.fetch) {
+    const form = this.formParams();
+    const headers = {
+      "Content-Type": "application/x-www-form-urlencoded"
+    };
+    if (this.secret !== void 0 && this.auth === "basic") {
+      const credentials = Buffer.from(
+        `${this.client}:${this.secret}`,
+        "utf8"
+      ).toString("base64");
+      headers["Authorization"] = `Basic ${credentials}`;
+    }
+    let response;
+    try {
+      response = await fetchImpl(this.endpoint, {
+        method: "POST",
+        headers,
+        // `URLSearchParams` keeps the order it is given, which is the wire
+        // order the contract fixture pins.
+        body: new URLSearchParams(form).toString()
+      });
+    } catch (err) {
+      throw new DelegationError("http", `HTTP error: ${err}`);
+    }
+    const body = await response.text().catch(() => "");
+    if (!response.ok) {
+      throw errorFromBody(response.status, body);
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(body);
+    } catch (err) {
+      throw new DelegationError(
+        "invalid_response",
+        `HTTP ${response.status}: ${err}`
+      );
+    }
+    return tokenFromWire(parsed, response.status);
+  }
+};
+function errorFromBody(status, body) {
+  let parsed;
+  try {
+    parsed = JSON.parse(body);
+  } catch {
+    parsed = void 0;
+  }
+  const oauth = parsed;
+  if (oauth && typeof oauth.error === "string") {
+    const description = typeof oauth.error_description === "string" ? oauth.error_description : void 0;
+    return new DelegationError(
+      "server",
+      `delegation exchange refused (HTTP ${status}): ${oauth.error}` + (description ? ` \u2014 ${description}` : ""),
+      { status, error: oauth.error, errorDescription: description }
+    );
+  }
+  return new DelegationError(
+    "invalid_response",
+    `HTTP ${status} with a non-OAuth body: ${body.slice(0, 200)}`
+  );
+}
+function tokenFromWire(parsed, status) {
+  const wire = parsed;
+  const missing = ["access_token", "issued_token_type", "token_type"].filter(
+    (field) => typeof wire?.[field] !== "string"
+  );
+  if (missing.length > 0) {
+    throw new DelegationError(
+      "invalid_response",
+      `HTTP ${status}: delegation response is missing required field(s): ${missing.join(", ")}`
+    );
+  }
+  const expiresIn = wire["expires_in"];
+  const scope = wire["scope"];
+  return {
+    access_token: wire["access_token"],
+    issued_token_type: wire["issued_token_type"],
+    token_type: wire["token_type"],
+    ...typeof expiresIn === "number" ? { expires_at: nowSecs2() + expiresIn } : {},
+    ...typeof scope === "string" ? { scope } : {}
+  };
+}
+function isDelegatedTokenExpired(token) {
+  if (token.expires_at === void 0) return false;
+  return nowSecs2() + REFRESH_SKEW_SECS2 >= token.expires_at;
+}
+var TokenSource = class _TokenSource {
+  resolver;
+  sourceKind;
+  declaredType;
+  constructor(kind, tokenType, resolver) {
+    this.sourceKind = kind;
+    this.declaredType = tokenType;
+    this.resolver = resolver;
+  }
+  /** A fixed token, e.g. one handed to the agent for this run. */
+  static staticToken(token, tokenType = TOKEN_TYPES.access_token) {
+    return new _TokenSource("static", tokenType, async () => token);
+  }
+  /** The agent's own `client_credentials` provider — the usual **actor**. */
+  static clientCredentials(provider, tokenType = TOKEN_TYPES.access_token) {
+    return new _TokenSource(
+      "client_credentials",
+      tokenType,
+      () => provider.getToken()
+    );
+  }
+  /**
+   * A user's authorization-code provider — the usual **subject** in an app that
+   * signed the user in itself. Refreshes its grant as needed, so the exchange
+   * always sees a live subject token.
+   */
+  static authorizationCode(provider, tokenType = TOKEN_TYPES.access_token) {
+    return new _TokenSource(
+      "authorization_code",
+      tokenType,
+      () => provider.getToken()
+    );
+  }
+  /**
+   * Any function that yields a token — a vault lookup, a header from an inbound
+   * request, another SDK's provider. Called on every exchange.
+   */
+  static dynamic(fn, tokenType = TOKEN_TYPES.access_token) {
+    return new _TokenSource("dynamic", tokenType, async () => fn());
+  }
+  /** Declare a different {@link TokenType} for this source. */
+  withTokenType(tokenType) {
+    return new _TokenSource(this.sourceKind, tokenType, this.resolver);
+  }
+  /** The declared token type. */
+  get tokenType() {
+    return this.declaredType;
+  }
+  /** Where the token comes from. */
+  get kind() {
+    return this.sourceKind;
+  }
+  /** Draw a token. */
+  resolve() {
+    return this.resolver();
+  }
+  /** Never print tokens — only where they come from. */
+  toJSON() {
+    return { kind: this.sourceKind, tokenType: this.declaredType };
+  }
+  [INSPECT_CUSTOM]() {
+    return `TokenSource { kind: '${this.sourceKind}', tokenType: '${this.declaredType}' }`;
+  }
+};
+var DelegatedProvider = class {
+  template;
+  subject;
+  actor;
+  fetchImpl;
+  cached = null;
+  /**
+   * The in-flight exchange, so concurrent callers make one request rather than
+   * a stampede. Mirrors `AuthCodeProvider`'s refresh de-duplication.
+   */
+  exchangePromise = null;
+  /**
+   * Wrap a request template with the sources of its two tokens.
+   *
+   * Any `subjectToken` or `actorToken` already on `request` is ignored; the
+   * sources supply them. Omit `actor` only with a request that called
+   * {@link DelegationRequest.impersonation} — otherwise every `getToken` fails
+   * with `missing_actor`, which is the intended loud failure rather than a
+   * silent downgrade.
+   */
+  constructor(request, subject, actor, fetchImpl = globalThis.fetch) {
+    this.template = request;
+    this.subject = subject;
+    this.actor = actor;
+    this.fetchImpl = fetchImpl;
+  }
+  /**
+   * The current delegated bearer, exchanging first if there is none or it is at
+   * or near expiry.
+   */
+  async getToken() {
+    const live = this.liveToken();
+    if (live !== void 0) return live;
+    if (!this.exchangePromise) {
+      this.exchangePromise = this.exchange().then((token2) => {
+        this.cached = token2;
+        return token2;
+      }).finally(() => {
+        this.exchangePromise = null;
+      });
+    }
+    const token = await this.exchangePromise;
+    return token.access_token;
+  }
+  /**
+   * Force the next {@link getToken} to exchange again. Call on a 401.
+   *
+   * Only the delegated token is dropped. The subject and actor sources are left
+   * alone: a provider-backed source tracks its own expiry, and a 401 from the
+   * resource server says nothing about them.
+   */
+  invalidate() {
+    this.cached = null;
+  }
+  /** A snapshot of the cached token, if any — for inspection or logging. */
+  token() {
+    return this.cached === null ? void 0 : { ...this.cached };
+  }
+  /** The request template, without tokens. */
+  get request() {
+    return this.template;
+  }
+  /** Never print tokens, and never the client secret the template carries. */
+  toJSON() {
+    return {
+      tokenEndpoint: this.template.tokenEndpoint,
+      clientId: this.template.clientId,
+      subject: this.subject.toJSON(),
+      ...this.actor ? { actor: this.actor.toJSON() } : {},
+      hasToken: this.cached !== null
+    };
+  }
+  [INSPECT_CUSTOM]() {
+    return `DelegatedProvider ${JSON.stringify(this.toJSON())}`;
+  }
+  // ─── Private ───────────────────────────────────────────────────────────────
+  liveToken() {
+    if (this.cached === null) return void 0;
+    if (isDelegatedTokenExpired(this.cached)) return void 0;
+    return this.cached.access_token;
+  }
+  async exchange() {
+    if (this.actor === void 0 && !this.template.isImpersonation) {
+      throw new DelegationError(
+        "missing_actor",
+        "no actor_token \u2014 delegation requires one; call impersonation() to opt out explicitly"
+      );
+    }
+    const request = this.template.clone().subjectToken(await this.subject.resolve(), this.subject.tokenType);
+    if (this.actor !== void 0) {
+      request.actorToken(await this.actor.resolve(), this.actor.tokenType);
+    }
+    return request.exchange(this.fetchImpl);
+  }
+};
+function nowSecs2() {
+  return Math.floor(Date.now() / 1e3);
+}
+
+// src/loopback.ts
+var import_node_http = require("http");
+var LoopbackListener = class _LoopbackListener {
+  server;
+  boundPort;
+  path;
+  settled = false;
+  constructor(server, port, path3) {
+    this.server = server;
+    this.boundPort = port;
+    this.path = path3;
+  }
+  /**
+   * Bind an OS-assigned port on `127.0.0.1`.
+   *
+   * Letting the OS choose avoids fighting whatever else owns a fixed port —
+   * and because registration happens after binding, the real port is already
+   * known by the time the redirect URI is registered.
+   */
+  static bind() {
+    return _LoopbackListener.bindOn(0, "/callback");
+  }
+  /**
+   * Bind a specific port and path.
+   *
+   * Use when the client was registered out of band against a fixed redirect
+   * URI and the authorization server will accept no other.
+   */
+  static bindOn(port, path3) {
+    const normalized = path3.startsWith("/") ? path3 : `/${path3}`;
+    return new Promise((resolve, reject) => {
+      const server = (0, import_node_http.createServer)();
+      server.once("error", (err) => {
+        reject(new AuthCodeError("http", `cannot bind loopback port: ${err}`));
+      });
+      server.listen(port, "127.0.0.1", () => {
+        const address = server.address();
+        if (!address) {
+          server.close();
+          reject(
+            new AuthCodeError("http", "cannot bind loopback port: no address")
+          );
+          return;
+        }
+        resolve(new _LoopbackListener(server, address.port, normalized));
+      });
+    });
+  }
+  /**
+   * Re-bind the exact port and path of a previously registered redirect URI.
+   *
+   * Needed whenever a saved registration is reused: the authorization server
+   * matches the redirect URI exactly, so the listener has to come back on the
+   * same port it registered.
+   *
+   * Rejects if that port is occupied. The right recovery is to {@link bind} a
+   * fresh port and register a new client — not to retry, and not to authorize
+   * against a URI the server will reject.
+   */
+  static bindFor(redirectUri) {
+    let parsed;
+    try {
+      parsed = new URL(redirectUri);
+    } catch (err) {
+      return Promise.reject(
+        new AuthCodeError("http", `bad redirect_uri ${redirectUri}: ${err}`)
+      );
+    }
+    if (!parsed.port) {
+      return Promise.reject(
+        new AuthCodeError("http", `redirect_uri ${redirectUri} names no port`)
+      );
+    }
+    return _LoopbackListener.bindOn(Number(parsed.port), parsed.pathname);
+  }
+  /** The port actually bound. */
+  get port() {
+    return this.boundPort;
+  }
+  /**
+   * The redirect URI to register and to send in the authorize request.
+   *
+   * Uses `127.0.0.1` rather than `localhost`: RFC 8252 recommends the literal
+   * address, and it sidesteps hosts where `localhost` resolves to IPv6 first
+   * while the listener is bound to IPv4.
+   */
+  get redirectUri() {
+    return `http://127.0.0.1:${this.boundPort}${this.path}`;
+  }
+  /** Stop listening. Safe to call more than once. */
+  close() {
+    this.server.close();
+  }
+  /**
+   * Wait for the browser's redirect, up to `timeoutMs`.
+   *
+   * Serves a small page either way so the user sees an outcome rather than a
+   * browser error, then stops listening. Requests to other paths are answered
+   * 404 and ignored — browsers routinely ask for `/favicon.ico`, and treating
+   * that as the redirect would abort the flow.
+   */
+  wait(timeoutMs) {
+    return new Promise((resolve, reject) => {
+      const finish = (fn) => {
+        if (this.settled) return;
+        this.settled = true;
+        clearTimeout(timer);
+        this.server.removeAllListeners("request");
+        this.close();
+        fn();
+      };
+      const timer = setTimeout(() => {
+        finish(
+          () => reject(
+            new AuthCodeError(
+              "http",
+              `timed out after ${Math.round(
+                timeoutMs / 1e3
+              )}s waiting for the authorization redirect`
+            )
+          )
+        );
+      }, timeoutMs);
+      timer.unref?.();
+      this.server.on("request", (req, res) => {
+        const target = new URL(req.url ?? "/", "http://127.0.0.1");
+        if (target.pathname !== this.path) {
+          respond(res, 404, "Not found");
+          return;
+        }
+        const error = target.searchParams.get("error");
+        if (error) {
+          respond(
+            res,
+            200,
+            "Authorization was denied. You can close this window."
+          );
+          const description = target.searchParams.get("error_description");
+          finish(
+            () => reject(
+              new AuthCodeError(
+                "denied",
+                `authorization denied: ${error}${description ? ` \u2014 ${description}` : ""}`
+              )
+            )
+          );
+          return;
+        }
+        const code = target.searchParams.get("code");
+        const state = target.searchParams.get("state");
+        if (code !== null && state !== null) {
+          respond(
+            res,
+            200,
+            "Signed in. You can close this window and return to the app."
+          );
+          finish(() => resolve({ code, state }));
+          return;
+        }
+        respond(res, 400, "Missing code or state.");
+        finish(
+          () => reject(
+            new AuthCodeError(
+              "discovery",
+              "redirect carried neither an error nor a code/state pair"
+            )
+          )
+        );
+      });
+    });
+  }
+};
+function respond(res, status, message) {
+  const body = `<!DOCTYPE html><html><head><meta charset="utf-8"><title>DataGrout</title><style>body{font:15px/1.5 system-ui,sans-serif;margin:16vh auto;max-width:26rem;text-align:center;color-scheme:light dark}</style></head><body><p>${message}</p></body></html>`;
+  res.writeHead(status, {
+    "content-type": "text/html; charset=utf-8",
+    "content-length": Buffer.byteLength(body),
+    connection: "close"
+  });
+  res.end(body);
+}
+
 // src/types.ts
 function extractMeta(result) {
   const rich = result?._meta?.datagrout;
@@ -2354,36 +3624,56 @@ function buildToolMeta(raw) {
 
 // src/index.ts
 init_onramp();
-var version = "0.5.0";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  AuthCodeError,
+  AuthCodeFlow,
+  AuthCodeProvider,
   AuthError,
   Client,
   ConduitError,
   ConduitIdentity,
   DEFAULT_IDENTITY_DIR,
+  DEFAULT_SCOPE,
+  DELEGATION_GRANT_TYPE,
+  DELEGATION_SERVER_ERROR_CODES,
   DG_CA_URL,
   DG_SUBSTRATE_ENDPOINT,
+  DelegatedProvider,
+  DelegationError,
+  DelegationRequest,
   GuidedSession,
   InvalidConfigError,
+  LoopbackListener,
   NetworkError,
   NotInitializedError,
   OAuthTokenProvider,
   RateLimitError,
   ServerError,
+  TOKEN_TYPES,
+  TokenSource,
   WS_SUBPROTOCOL,
   WsTransport,
+  authCodeProviderFrom,
+  challengeS256,
   deriveTokenEndpoint,
   extractMeta,
   fetchDgCaCert,
   fetchWithIdentity,
   generateKeypair,
+  generateVerifier,
+  isDelegatedTokenExpired,
   isDgUrl,
+  isGrantExpired,
+  isGrantRefreshable,
   refreshCaCert,
+  refreshGrant,
   registerAndExchange,
   registerIdentity,
   registerOnly,
   rotateIdentity,
   saveIdentity,
+  supportsS256,
+  tokenTypeName,
   version
 });