@gizmodata/hardcharger-mcp 2.0.0 → 2.2.0

package/dist/broker.js

@@ -0,0 +1,278 @@
+// Connection broker: per-user connections and sign-in tokens for the hosted HTTP transport.
+//
+// With HARDCHARGER_MCP_BROKER_URL, this server holds no Hardcharger credentials of its own. A
+// broker (a control plane such as GizmoData Cloud) knows which Hardcharger servers each person
+// may reach and mints short-lived sign-in tokens for them; the client exchanges such a token
+// (Chargewire token_exchange), so every statement runs as the person who asked, under that
+// person's grants. The protocol is in docs/connection-broker.md.
+//
+// The caller's OAuth access token is never forwarded as a credential (MCP forbids token
+// passthrough). Each broker request authenticates this server with its own credential and
+// presents the caller's token as an RFC 8693 subject token, which the broker verifies and
+// maps to a person. Only the broker decides what that person may reach.
+import { z } from "zod";
+import { parseHardchargerUri, } from "./connection.js";
+import { ConnectionRegistry } from "./registry.js";
+/** RFC 8693 token type of the caller's OAuth access token. */
+export const ACCESS_TOKEN_TYPE = "urn:ietf:params:oauth:token-type:access_token";
+/** A minted token is reused until this share of its lifetime has passed. */
+const TOKEN_REUSE_FRACTION = 0.8;
+/** Connection names the tools accept (the same rule as configured connections). */
+const NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/u;
+const connectionSchema = z.object({
+    id: z.string().min(1),
+    name: z.string().min(1),
+    label: z.string().nullish(),
+    uri: z.string().min(1),
+    default_catalog: z.string().nullish(),
+    default_schema: z.string().nullish(),
+    allow_writes: z.boolean().default(false),
+});
+const listSchema = z.object({
+    connections: z.array(z.unknown()),
+    /** Shown to the caller when the list is empty (e.g. how to create a server). */
+    message: z.string().nullish(),
+});
+const introspectionSchema = z.object({
+    active: z.boolean(),
+    sub: z.string().nullish(),
+    email: z.string().nullish(),
+    name: z.string().nullish(),
+});
+const tokenSchema = z.object({
+    token: z.string().min(1),
+    expires_in: z.number().positive(),
+});
+/** A broker request that failed; `message` is safe to show the caller. */
+export class BrokerError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+        this.name = "BrokerError";
+    }
+}
+/** The broker's error text from a JSON body (`error_description`, `message` or a string `detail`). */
+function brokerDetail(body) {
+    if (!body || typeof body !== "object")
+        return undefined;
+    for (const key of ["error_description", "message", "detail"]) {
+        const value = body[key];
+        if (typeof value === "string" && value.trim() !== "")
+            return value.trim();
+    }
+    return undefined;
+}
+/** Talks to the broker's two endpoints. Stateless; one instance serves every caller. */
+export class BrokerClient {
+    config;
+    fetchImpl;
+    constructor(config, hooks = {}) {
+        this.config = config;
+        this.fetchImpl = hooks.fetch ?? fetch;
+    }
+    /** The servers the caller may reach. */
+    async listConnections(subjectToken) {
+        const body = listSchema.safeParse(await this.post("/connections", subjectToken));
+        if (!body.success)
+            throw new BrokerError("The connection broker answered the connection list with an unexpected body.");
+        return { connections: body.data.connections, message: body.data.message ?? undefined };
+    }
+    /**
+     * Whether the caller's access token is active, and whose it is: the broker verifies the tokens of
+     * the provider it trusts, opaque ones included, so this server needs no provider credentials.
+     */
+    async introspect(subjectToken) {
+        const body = introspectionSchema.safeParse(await this.post("/introspect", subjectToken));
+        if (!body.success)
+            throw new BrokerError("The connection broker answered the token check with an unexpected body.");
+        const { active, sub, email, name } = body.data;
+        return { active, sub: sub ?? undefined, email: email ?? undefined, name: name ?? undefined };
+    }
+    /** A sign-in token for the caller on one server, and its lifetime in seconds. */
+    async issueToken(subjectToken, connectionId) {
+        const body = tokenSchema.safeParse(await this.post(`/connections/${encodeURIComponent(connectionId)}/token`, subjectToken));
+        if (!body.success)
+            throw new BrokerError("The connection broker answered the token request with an unexpected body.");
+        return { token: body.data.token, expiresIn: body.data.expires_in };
+    }
+    async post(path, subjectToken) {
+        let res;
+        try {
+            res = await this.fetchImpl(`${this.config.url}${path}`, {
+                method: "POST",
+                headers: {
+                    authorization: `Bearer ${this.config.credential}`,
+                    "content-type": "application/json",
+                    accept: "application/json",
+                },
+                body: JSON.stringify({ subject_token: subjectToken, subject_token_type: ACCESS_TOKEN_TYPE }),
+                signal: AbortSignal.timeout(this.config.timeoutMs),
+                redirect: "error",
+            });
+        }
+        catch (err) {
+            const reason = err instanceof Error && err.name === "TimeoutError" ? `no answer within ${this.config.timeoutMs} ms` : "unreachable";
+            throw new BrokerError(`The connection broker is ${reason}; try again shortly.`);
+        }
+        let body;
+        try {
+            body = await res.json();
+        }
+        catch {
+            body = undefined;
+        }
+        if (res.ok)
+            return body;
+        const detail = brokerDetail(body);
+        if (res.status === 401) {
+            // The broker refused this server's own credential (or found the caller's token invalid).
+            throw new BrokerError(detail ?? "The connection broker refused this request; reconnect the connector, or ask the administrator to check this server's broker credential.", 401);
+        }
+        throw new BrokerError(detail ?? `The connection broker answered HTTP ${res.status}.`, res.status);
+    }
+}
+/** Sign-in tokens for one caller on one server, minted by the broker and reused for most of their life. */
+class BrokeredTokenSource {
+    registry;
+    connectionId;
+    cached;
+    inFlight;
+    issued = new Set();
+    constructor(registry, connectionId) {
+        this.registry = registry;
+        this.connectionId = connectionId;
+    }
+    async token() {
+        const now = this.registry.now();
+        if (this.cached && now < this.cached.reuseUntil)
+            return this.cached.token;
+        this.inFlight ??= this.registry.broker
+            .issueToken(this.registry.subjectToken(), this.connectionId)
+            .then(({ token, expiresIn }) => {
+            this.cached = { token, reuseUntil: this.registry.now() + expiresIn * 1000 * TOKEN_REUSE_FRACTION };
+            this.issued.add(token);
+            return token;
+        })
+            .finally(() => {
+            this.inFlight = undefined;
+        });
+        return this.inFlight;
+    }
+    secrets() {
+        return [...this.issued];
+    }
+}
+/**
+ * One caller's connections, as the broker lists them. Refreshed on a request when the list is
+ * older than HARDCHARGER_MCP_BROKER_CACHE_SECONDS (and by list_connections at once); servers
+ * the broker no longer lists are closed. Each connection signs in with a token the broker
+ * mints for this caller.
+ */
+export class BrokeredRegistry extends ConnectionRegistry {
+    broker;
+    callerToken = "";
+    listedAt;
+    refreshing;
+    lastProblem;
+    emptyMessage;
+    clock;
+    constructor(config, broker, log, hooks = {}) {
+        super(config, log, { connections: [], allowEmpty: true });
+        this.broker = broker;
+        this.clock = hooks.now ?? (() => Date.now());
+    }
+    now() {
+        return this.clock();
+    }
+    /** The caller's current OAuth access token (verified by the transport), presented to the broker. */
+    subjectToken() {
+        return this.callerToken;
+    }
+    /** Records the token of the request being served: the newest one the client sent. */
+    setSubjectToken(token) {
+        this.callerToken = token;
+    }
+    /** Asks the broker again when the list is stale (or always, with `force`). Never throws. */
+    async refresh({ force = false } = {}) {
+        const ttl = (this.config.broker?.cacheSeconds ?? 0) * 1000;
+        if (!force && this.listedAt !== undefined && this.now() - this.listedAt < ttl)
+            return;
+        this.refreshing ??= this.load().finally(() => {
+            this.refreshing = undefined;
+        });
+        await this.refreshing;
+    }
+    async load() {
+        let listed;
+        try {
+            listed = await this.broker.listConnections(this.callerToken);
+        }
+        catch (err) {
+            // Keep what the caller had; say why on the next tool call that finds nothing.
+            this.lastProblem = err instanceof Error ? err.message : String(err);
+            this.log(`[hardcharger-mcp] connection broker: ${this.redact(this.lastProblem)}`);
+            return;
+        }
+        const configs = [];
+        const seen = new Set();
+        for (const raw of listed.connections) {
+            const parsed = connectionSchema.safeParse(raw);
+            if (!parsed.success) {
+                this.log("[hardcharger-mcp] connection broker: skipped a connection with an unexpected shape");
+                continue;
+            }
+            const c = parsed.data;
+            if (!NAME_PATTERN.test(c.name) || seen.has(c.name.toLowerCase())) {
+                this.log(`[hardcharger-mcp] connection broker: skipped connection ${JSON.stringify(c.name)} (invalid or repeated name)`);
+                continue;
+            }
+            let target;
+            try {
+                target = parseHardchargerUri(`connection ${c.name}`, c.uri);
+            }
+            catch (err) {
+                this.log(`[hardcharger-mcp] connection broker: skipped ${c.name}: ${err instanceof Error ? err.message : String(err)}`);
+                continue;
+            }
+            seen.add(c.name.toLowerCase());
+            configs.push({
+                name: c.name,
+                ...target,
+                tlsSkipVerify: false,
+                defaultCatalog: c.default_catalog ?? undefined,
+                defaultSchema: c.default_schema ?? undefined,
+                queryTimeoutSeconds: this.config.queryTimeoutSeconds,
+                id: c.id,
+                label: c.label ?? undefined,
+                allowWrites: c.allow_writes,
+                tokenSource: new BrokeredTokenSource(this, c.id),
+            });
+        }
+        this.lastProblem = undefined;
+        this.emptyMessage = listed.message;
+        this.listedAt = this.now();
+        await this.replaceConnections(configs);
+    }
+    /** The broker's own words when it listed nothing, or why it could not be asked. */
+    status() {
+        if (this.lastProblem !== undefined)
+            return this.lastProblem;
+        if (this.names().length === 0)
+            return this.noConnectionsMessage();
+        return undefined;
+    }
+    noConnectionsMessage() {
+        if (this.lastProblem !== undefined)
+            return this.lastProblem;
+        return this.emptyMessage ?? "You have no Hardcharger servers to connect to.";
+    }
+    /** Only servers this caller already uses: listing every table would sign in to every server they can reach. */
+    resourceConnections() {
+        return this.all().filter((c) => c.connectedAt !== null);
+    }
+    secrets() {
+        return [...super.secrets(), this.callerToken];
+    }
+}
+//# sourceMappingURL=broker.js.map

package/dist/broker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"broker.js","sourceRoot":"","sources":["../src/broker.ts"],"names":[],"mappings":"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"}

package/dist/connection.d.ts

@@ -3,7 +3,17 @@ import { Table } from "apache-arrow";
 import type { OAuthConfig } from "./oauth.js";
 import type { BoundParams } from "./params.js";
 /** How a connection signs in. */
-export type AuthMethod = "password" | "token" | "mtls" | "sso" | "none";
+export type AuthMethod = "password" | "token" | "mtls" | "sso" | "brokered" | "none";
+/**
+ * Where a brokered connection gets its sign-in tokens: the connection broker mints one for the
+ * calling user each time the client signs in (see broker.ts).
+ */
+export interface TokenSource {
+    /** A signed sign-in token for this user and server, for the token_exchange grant. */
+    token(): Promise<string>;
+    /** Tokens this source has handed out or holds, for redaction. */
+    secrets(): string[];
+}
 /** Settings for one Hardcharger server. */
 export interface ConnectionConfig {
     /** Unique, case-insensitive name used in tool arguments (e.g. "default", "prod"). */
@@ -31,6 +41,18 @@ export interface ConnectionConfig {
     defaultSchema?: string;
     /** Per-statement timeout applied to this connection's statements (0 = none). */
     queryTimeoutSeconds: number;
+    /** Brokered connections: the broker's id for this server. */
+    id?: string;
+    /** Brokered connections: a human description (e.g. organization / project / cluster). */
+    label?: string;
+    /**
+     * Brokered connections: whether the broker lets this user write through this server. Writes
+     * also need HARDCHARGER_ALLOW_WRITES, which stays the server-wide ceiling. Unset means the
+     * server-wide setting alone decides.
+     */
+    allowWrites?: boolean;
+    /** Brokered connections: the per-user sign-in tokens (token_exchange grant). */
+    tokenSource?: TokenSource;
 }
 /** Whole-server settings plus every configured connection (the first is the initial default). */
 export interface McpConfig {
@@ -49,6 +71,22 @@ export interface McpConfig {
     mcpMaxSessions: number;
     /** Enables the optional `login_sso` tool (the server's OAuth browser sign-in). */
     enableSso: boolean;
+    /**
+     * HTTP transport with OAuth: a connection broker supplies each caller's connections and
+     * sign-in tokens (HARDCHARGER_MCP_BROKER_URL); `connections` is then empty.
+     */
+    broker?: BrokerConfig;
+}
+/** Settings for the connection broker (see broker.ts and docs/connection-broker.md). */
+export interface BrokerConfig {
+    /** Base URL of the broker's API: `<url>/connections` and `<url>/connections/<id>/token`. */
+    url: string;
+    /** This MCP server's own credential at the broker, sent as a bearer token. */
+    credential: string;
+    /** How long a caller's connection list is reused before the broker is asked again. */
+    cacheSeconds: number;
+    /** Timeout of one broker request. */
+    timeoutMs: number;
 }
 export declare const DEFAULTS: {
     readonly maxRows: 500;
@@ -57,6 +95,8 @@ export declare const DEFAULTS: {
     readonly connectionName: "default";
     readonly sessionIdleSeconds: 1800;
     readonly maxSessions: 200;
+    readonly brokerCacheSeconds: 60;
+    readonly brokerTimeoutMs: 10000;
 };
 /** Extra connection slots the Claude Desktop manifest exposes (`HARDCHARGER_2_*`, `HARDCHARGER_3_*`). */
 export declare const MANIFEST_SLOTS: readonly ["2", "3"];
@@ -92,6 +132,12 @@ export declare function parseHardchargerUri(name: string, raw: string): {
  * Slots without a URI are ignored. At least one connection is required.
  */
 export declare function parseConfig(env?: NodeJS.ProcessEnv): McpConfig;
+/**
+ * Reads the connection broker settings (HTTP transport with OAuth). Returns undefined unless
+ * HARDCHARGER_MCP_BROKER_URL is set. A plain http URL needs
+ * HARDCHARGER_MCP_BROKER_ALLOW_INSECURE=true (local testing).
+ */
+export declare function parseBroker(env: NodeJS.ProcessEnv): BrokerConfig | undefined;
 /** Default claim precedence used to name an authenticated caller. */
 export declare const DEFAULT_USER_CLAIMS: readonly ["email", "preferred_username", "upn", "name", "sub"];
 /**
@@ -102,7 +148,7 @@ export declare const DEFAULT_USER_CLAIMS: readonly ["email", "preferred_username
  */
 export declare function parseOAuth(env: NodeJS.ProcessEnv): OAuthConfig | undefined;
 /** The sign-in a connection's settings call for (before any login_sso). */
-export declare function authMethod(config: Pick<ConnectionConfig, "username" | "token" | "mtlsCertFile">): AuthMethod;
+export declare function authMethod(config: Pick<ConnectionConfig, "username" | "token" | "mtlsCertFile" | "tokenSource">): AuthMethod;
 /** Replaces every configured secret in `text` with `***`. */
 export declare function redactSecrets(text: string, secrets: Array<string | undefined>): string;
 export declare class QueryTimeoutError extends Error {
@@ -114,7 +160,7 @@ export interface CappedResult {
     /** True when more rows existed beyond `maxRows` (the extra row is not in `table`). */
     truncated: boolean;
 }
-/** The error's Hardcharger (Warp SQL) code, if it is one of the client's errors. */
+/** The error's Hardcharger (Chargewire) code, if it is one of the client's errors. */
 export declare function errorCode(err: unknown): string | undefined;
 /**
  * Does this error mean the connection (or the server's session behind it) is gone in a
@@ -159,7 +205,7 @@ export interface ConnectionHooks {
 /**
  * One Hardcharger connection per configured server, opened lazily and serialized so a
  * single statement is in flight at a time. Timeouts are enforced by the server
- * (`statementTimeoutMs`, Warp SQL §6.9) with a client-side abort as backstop that cancels
+ * (`statementTimeoutMs`, Chargewire §6.9) with a client-side abort as backstop that cancels
  * the statement on the server; only if that fails to settle the call is the connection
  * dropped and reopened. The client replaces a session the server lost and replays its
  * catalog and schema; a connection that is gone altogether (a killed session, a closed
@@ -187,7 +233,7 @@ export declare class HardchargerConnection {
     /** The search path (catalog, schema) applied to every session. */
     currentSearchPath(): SearchPath;
     /**
-     * Switches the session's default catalog and/or schema (Warp SQL session options, which
+     * Switches the session's default catalog and/or schema (Chargewire session options, which
      * the client replays on a replacement session). Throws when the server refuses it.
      */
     useSchema(path: SearchPath): Promise<SearchPath>;
@@ -225,7 +271,7 @@ export declare class HardchargerConnection {
     /** Opens a fresh client and applies the session settings. */
     private open;
     /**
-     * The search path, as Warp SQL session options. A catalog or schema the server does not
+     * The search path, as Chargewire session options. A catalog or schema the server does not
      * have is reported (with the catalogs it does have) instead of failing the connection;
      * the server's default then applies.
      */

package/dist/connection.js

@@ -10,6 +10,8 @@ export const DEFAULTS = {
     connectionName: "default",
     sessionIdleSeconds: 1800,
     maxSessions: 200,
+    brokerCacheSeconds: 60,
+    brokerTimeoutMs: 10_000,
 };
 /** Extra connection slots the Claude Desktop manifest exposes (`HARDCHARGER_2_*`, `HARDCHARGER_3_*`). */
 export const MANIFEST_SLOTS = ["2", "3"];
@@ -170,7 +172,13 @@ export function parseConfig(env = process.env) {
         if (c)
             connections.push(c);
     }
-    if (connections.length === 0) {
+    const broker = parseBroker(env);
+    if (broker !== undefined && connections.length > 0) {
+        throw new ConfigError("HARDCHARGER_MCP_BROKER_URL supplies every caller's connections; remove " +
+            `${connections.map((c) => c.name).join(", ")} (HARDCHARGER_URI and the other connection settings): a configured ` +
+            "connection's credentials would be shared by every user of this server.");
+    }
+    if (connections.length === 0 && broker === undefined) {
         throw new ConfigError("HARDCHARGER_URI is required: the Hardcharger server's URI, e.g. hardcharger://db.example.com " +
             "(TLS to port 31337), or hardcharger://localhost?tls=false for a server without TLS.");
     }
@@ -187,6 +195,10 @@ export function parseConfig(env = process.env) {
     if (mcpBearerToken !== undefined && mcpOAuth !== undefined) {
         throw new ConfigError("HARDCHARGER_MCP_BEARER_TOKEN and HARDCHARGER_MCP_OAUTH_ISSUER are mutually exclusive: pick one way to authenticate HTTP clients.");
     }
+    if (broker !== undefined && mcpOAuth === undefined) {
+        throw new ConfigError("HARDCHARGER_MCP_BROKER_URL needs HARDCHARGER_MCP_OAUTH_ISSUER: the broker issues credentials per signed-in user, " +
+            "so every request must carry a verified identity (HTTP transport with OAuth).");
+    }
     return {
         connections,
         allowWrites: parseBoolean("HARDCHARGER_ALLOW_WRITES", env.HARDCHARGER_ALLOW_WRITES, false),
@@ -204,6 +216,35 @@ export function parseConfig(env = process.env) {
             max: 100000,
         }),
         enableSso,
+        broker,
+    };
+}
+/**
+ * Reads the connection broker settings (HTTP transport with OAuth). Returns undefined unless
+ * HARDCHARGER_MCP_BROKER_URL is set. A plain http URL needs
+ * HARDCHARGER_MCP_BROKER_ALLOW_INSECURE=true (local testing).
+ */
+export function parseBroker(env) {
+    const allowHttp = parseBoolean("HARDCHARGER_MCP_BROKER_ALLOW_INSECURE", env.HARDCHARGER_MCP_BROKER_ALLOW_INSECURE, false);
+    const url = parseHttpsUrl("HARDCHARGER_MCP_BROKER_URL", env.HARDCHARGER_MCP_BROKER_URL, { allowHttp });
+    if (url === undefined) {
+        for (const key of Object.keys(env)) {
+            if (key.startsWith("HARDCHARGER_MCP_BROKER_") && key !== "HARDCHARGER_MCP_BROKER_ALLOW_INSECURE" && !isUnset(env[key])) {
+                throw new ConfigError(`${key} is set but HARDCHARGER_MCP_BROKER_URL is not; the URL enables the connection broker.`);
+            }
+        }
+        return undefined;
+    }
+    const credential = nonEmpty(env.HARDCHARGER_MCP_BROKER_TOKEN);
+    if (credential === undefined) {
+        throw new ConfigError("HARDCHARGER_MCP_BROKER_TOKEN is required with HARDCHARGER_MCP_BROKER_URL: this server's own credential at the " +
+            "broker. Callers' tokens are presented to the broker as subject tokens, never as its credential.");
+    }
+    return {
+        url,
+        credential,
+        cacheSeconds: parseInteger("HARDCHARGER_MCP_BROKER_CACHE_SECONDS", env.HARDCHARGER_MCP_BROKER_CACHE_SECONDS, DEFAULTS.brokerCacheSeconds, { min: 0, max: 3600 }),
+        timeoutMs: DEFAULTS.brokerTimeoutMs,
     };
 }
 /** Splits a comma- or whitespace-separated list, dropping blanks. */
@@ -274,6 +315,8 @@ export function parseOAuth(env) {
 }
 /** The sign-in a connection's settings call for (before any login_sso). */
 export function authMethod(config) {
+    if (config.tokenSource !== undefined)
+        return "brokered";
     if (config.username !== undefined)
         return "password";
     if (config.token !== undefined)
@@ -306,12 +349,12 @@ export class QueryTimeoutError extends Error {
 const CLIENT_DEADLINE_GRACE_MS = 5000;
 /** If an abort does not settle the call, drop the connection after this. */
 const HARD_RESET_GRACE_MS = 15000;
-/** The error's Hardcharger (Warp SQL) code, if it is one of the client's errors. */
+/** The error's Hardcharger (Chargewire) code, if it is one of the client's errors. */
 export function errorCode(err) {
     return err instanceof HardchargerError ? err.code : undefined;
 }
 /**
- * `session_ended` reasons after which the user's sign-in itself no longer holds (Warp SQL
+ * `session_ended` reasons after which the user's sign-in itself no longer holds (Chargewire
  * §4.2, §5.6): a revoked token, changed credentials, a dropped user. Nothing signs in again
  * on its own after these; the error is the answer.
  */
@@ -365,7 +408,7 @@ function readPem(what, file) {
 /**
  * One Hardcharger connection per configured server, opened lazily and serialized so a
  * single statement is in flight at a time. Timeouts are enforced by the server
- * (`statementTimeoutMs`, Warp SQL §6.9) with a client-side abort as backstop that cancels
+ * (`statementTimeoutMs`, Chargewire §6.9) with a client-side abort as backstop that cancels
  * the statement on the server; only if that fails to settle the call is the connection
  * dropped and reopened. The client replaces a session the server lost and replays its
  * catalog and schema; a connection that is gone altogether (a killed session, a closed
@@ -400,7 +443,7 @@ export class HardchargerConnection {
         return { ...this.searchPath };
     }
     /**
-     * Switches the session's default catalog and/or schema (Warp SQL session options, which
+     * Switches the session's default catalog and/or schema (Chargewire session options, which
      * the client replays on a replacement session). Throws when the server refuses it.
      */
     async useSchema(path) {
@@ -435,7 +478,7 @@ export class HardchargerConnection {
     }
     /** Secrets to redact from any message that might reach a client. */
     secrets() {
-        return [this.config.password, this.config.token, this.overrides.accessToken];
+        return [this.config.password, this.config.token, this.overrides.accessToken, ...(this.config.tokenSource?.secrets() ?? [])];
     }
     redact(text) {
         return redactSecrets(text, this.secrets());
@@ -513,6 +556,11 @@ export class HardchargerConnection {
         if (this.overrides.accessToken !== undefined) {
             options.token = this.overrides.accessToken;
         }
+        else if (cfg.tokenSource !== undefined) {
+            const source = cfg.tokenSource;
+            // Called for every new sign-in: a fresh token from the broker, for this user.
+            options.subjectToken = () => source.token();
+        }
         else if (cfg.username !== undefined) {
             options.username = cfg.username;
             options.password = cfg.password ?? "";
@@ -548,7 +596,7 @@ export class HardchargerConnection {
         return client;
     }
     /**
-     * The search path, as Warp SQL session options. A catalog or schema the server does not
+     * The search path, as Chargewire session options. A catalog or schema the server does not
      * have is reported (with the catalogs it does have) instead of failing the connection;
      * the server's default then applies.
      */