@gizmodata/hardcharger-mcp 2.1.0 → 2.2.1

package/CHANGELOG.md

@@ -7,6 +7,43 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.2.1] - 2026-11-04
+
+### Changed
+- Built on `@gizmodata/hardcharger` 2.1.1 and `@gizmodata/chargewire` 2.1.0 (the dependency range is
+  now `^2.1.1`). A query that returns no rows with a LIST column no longer fails when the client
+  sets its unread result aside ([gizmodata/hardcharger#23](https://github.com/gizmodata/hardcharger/issues/23)),
+  and a session Hardcharger 2.7.0 ends for an idle transaction is replaced by the client.
+- `server_info` reports the server's `hardcharger.idle_in_transaction_session_timeout` among its settings.
+
+### Fixed
+- With writes enabled, a statement that found its transaction ended for sitting idle past the server's
+  `idle_in_transaction_session_timeout` (`session_ended`, reason `idle_in_transaction`, Hardcharger
+  2.7.0) was retried on a new connection, where it ran in autocommit and committed on its own while
+  the transaction's earlier statements had been rolled back. It now fails with that error and is not
+  retried; the next statement runs on the new session. A live test covers it, beside a busy
+  transaction that commits.
+
+## [2.2.0] - 2026-10-30
+
+### Added
+- Per-person credentials through a connection broker (`HARDCHARGER_MCP_BROKER_URL`,
+  `HARDCHARGER_MCP_BROKER_TOKEN`, HTTP transport with OAuth). The server then holds no Hardcharger
+  credentials: a broker, such as the control plane that runs the servers, lists the servers each
+  signed-in person may reach and mints them short-lived sign-in tokens, which the client exchanges
+  (token_exchange). Every statement runs as that person, under the server's grants, row policies and
+  masking. The person's token is presented to the broker as an RFC 8693 subject token, never as its
+  credential. The broker also checks each request's access token (`/introspect`, answers reused for 60 s), so
+  opaque access tokens such as Clerk's work and this server needs no provider keys; a broker outage answers 503,
+  not 401. Writes need the broker's per-server `allow_writes` as well as `HARDCHARGER_ALLOW_WRITES`.
+  Protocol: `docs/connection-broker.md`.
+- `list_connections` and `server_info` report whether each connection accepts writes
+  (`allow_writes`), and a brokered connection's description.
+
+### Fixed
+- The README said Clerk issues JWT access tokens by default; it issues opaque ones unless the instance turns JWT
+  access tokens on.
+
 ## [2.1.0] - 2026-10-29
 
 ### Changed

package/README.md

@@ -38,8 +38,8 @@ runs on. It is the Hardcharger port of
 [gizmosql-mcp](https://github.com/gizmodata/gizmosql-mcp), with the same tools and settings
 (`HARDCHARGER_*` instead of `GIZMOSQL_*`; see [CHANGELOG.md](CHANGELOG.md) for what changed).
 
-> **Status: 2.1.0, with Hardcharger 2.3.0.** Built on `@gizmodata/hardcharger` 2.1.0 (hardcharger-js
-> `1a524f6`, on `@gizmodata/chargewire` 2.0.0, chargewire-js `1ea10dd`, Chargewire protocol 1.0.0);
+> **Status: 2.2.1, with Hardcharger 2.7.0.** Built on `@gizmodata/hardcharger` 2.1.1 (hardcharger-js
+> `3849b40`, on `@gizmodata/chargewire` 2.1.0, chargewire-js `8a4ed78`, Chargewire protocol 1.0.0);
 > tested against the image of Hardcharger's main branch and against Hardcharger 2.2.0, released
 > before the protocol was renamed to Chargewire.
 
@@ -197,7 +197,8 @@ Microsoft Entra ID, Okta (custom authorization server), Auth0, Keycloak, Cognito
 is an OAuth 2.1 *resource server*: it verifies each bearer token against the provider's JWKS
 (issuer, audience, signature, expiry) and serves the RFC 9728 metadata at
 `/.well-known/oauth-protected-resource[/mcp]` so clients find the provider on their own. The token
-is never forwarded; the Hardcharger connection uses the configured service credentials.
+is never forwarded; the Hardcharger connection uses the configured service credentials, or, with a
+[connection broker](#-per-person-credentials-connection-broker), each person's own.
 
 <!-- example: http-oauth -->
 ```bash
@@ -237,8 +238,10 @@ connector enters the app registration's client ID and secret under *Advanced set
 `https://claude.ai/api/mcp/auth_callback`, *Expose an API* with the MCP URL as Application ID URI
 and a scope such as `access_as_user`, `requestedAccessTokenVersion` 2; v2 tokens carry the client ID
 as `aud`). **Okta** needs a custom authorization server; **Auth0** an API with the audience;
-**Keycloak** works out of the box; **Clerk** issues JWT access tokens by default. Providers with
-opaque access tokens (Google) are not supported in this mode.
+**Keycloak** works out of the box; **Clerk** issues opaque access tokens unless the instance has
+*JWT access tokens* turned on (checked 2026-10-30), so turn that on for this mode. Providers with
+opaque access tokens (Google) are not supported in this mode; with a connection broker they are,
+because the broker checks the tokens.
 
 **Static bearer token.** For a quick shared secret instead of OAuth, set
 `HARDCHARGER_MCP_BEARER_TOKEN`; every request must then send `Authorization: Bearer <token>`. The
@@ -253,6 +256,38 @@ HARDCHARGER_MCP_BEARER_TOKEN=a-long-random-secret \
 npx -y @gizmodata/hardcharger-mcp --transport http --port 3000
 ```
 
+### 🪪 Per-person credentials (connection broker)
+
+With a connection broker, the server holds no Hardcharger credentials at all. A broker, usually
+the control plane that runs your Hardcharger servers (GizmoData Cloud is one), tells it which
+servers each signed-in person may reach and mints that person a short-lived sign-in token for
+each one. The client exchanges the token (Chargewire token_exchange), so every statement runs
+**as that person**: the server's access control (grants, row policies, masking) decides what
+they may see and change, and its audit log names them. One connector serves everyone, and each
+person sees only their own servers in `list_connections`.
+
+```bash
+HARDCHARGER_MCP_PUBLIC_URL=https://mcp.example.com/mcp \
+HARDCHARGER_MCP_OAUTH_ISSUER=https://login.example.com \
+HARDCHARGER_MCP_BROKER_URL=https://control-plane.example.com/api/mcp-broker \
+HARDCHARGER_MCP_BROKER_TOKEN=this-servers-own-broker-credential \
+HARDCHARGER_ALLOW_WRITES=true \
+npx -y @gizmodata/hardcharger-mcp --transport http --host 0.0.0.0 --port 3000
+```
+
+The broker also checks each request's access token (`/introspect`), so the provider's tokens may be
+opaque (Clerk's are by default) and this server needs none of the provider's keys or credentials;
+`HARDCHARGER_MCP_OAUTH_ISSUER` only names the authorization server in the metadata clients read.
+It needs OAuth (each request must carry a verified person) and the HTTP transport, and takes no
+`HARDCHARGER_URI`: a configured connection's credentials would be shared by every user. The
+person's access token is never the broker credential: the server authenticates to the broker
+with `HARDCHARGER_MCP_BROKER_TOKEN` and presents the person's token as an RFC 8693 subject token.
+Writes need both `HARDCHARGER_ALLOW_WRITES=true` (the server-wide ceiling) and the broker's
+`allow_writes` for that person and server. Table resources are listed only for servers the
+person has already used, so a resource listing never signs in to every server they can reach.
+The protocol, for anyone writing a broker, is in
+[docs/connection-broker.md](docs/connection-broker.md).
+
 ### Container image and Helm chart
 
 [`Dockerfile`](Dockerfile) builds an image whose entrypoint runs the HTTP transport on port 3000, and
@@ -300,6 +335,10 @@ Only `HARDCHARGER_*` names are read.
 | `HARDCHARGER_MCP_OAUTH_ALLOW_INSECURE` | `false` | Accept `http://` issuer and public URLs (local testing only) |
 | `HARDCHARGER_MCP_SESSION_IDLE_SECONDS` | `1800` | HTTP transport with OAuth: close a user's session after this long without a request |
 | `HARDCHARGER_MCP_MAX_SESSIONS` | `200` | HTTP transport with OAuth: cap on concurrent user sessions |
+| `HARDCHARGER_MCP_BROKER_URL` | | HTTP transport with OAuth: a connection broker supplies each person's servers and sign-in tokens ([protocol](docs/connection-broker.md)); no `HARDCHARGER_URI` then |
+| `HARDCHARGER_MCP_BROKER_TOKEN` | | This server's own credential at the broker (required with the URL) |
+| `HARDCHARGER_MCP_BROKER_CACHE_SECONDS` | `60` | How long a person's server list is reused (`list_connections` always asks again) |
+| `HARDCHARGER_MCP_BROKER_ALLOW_INSECURE` | `false` | Accept a plain `http` broker URL (local testing) |
 | `HARDCHARGER_2_URI`, `HARDCHARGER_3_URI`, … | | Additional connections, see below |
 | `HARDCHARGER_CONNECTIONS` | | Comma-separated names of further connections, see below |
 
@@ -347,7 +386,8 @@ clients ask before running it.
 The guard is defense in depth; the real boundary is the privileges of the Hardcharger user the
 server signs in as. A sign-in token with `role: readonly` can only read (Hardcharger refuses
 anything else with `permission_denied`), and under Hardcharger's access control a store user's
-grants decide what each table allows.
+grants decide what each table allows. With a connection broker that user is the person asking,
+not a shared service account.
 
 - Credentials never appear in tool output, `server_info` or error messages: every message that
   reaches the client is redacted.
@@ -362,7 +402,11 @@ grants decide what each table allows.
   session are gone. A session an administrator killed, a closed connection or a transport failure
   reopens the connection once and retries (`reconnects`); a refused credential is never retried,
   and neither is a session ended because the sign-in was withdrawn (`token_revoked`,
-  `credentials_changed`, `principal_dropped`).
+  `credentials_changed`, `principal_dropped`). With writes enabled, a transaction (`BEGIN` through
+  `execute_statement`) left idle past the server's `idle_in_transaction_session_timeout`
+  (Hardcharger 2.7.0) is rolled back by the server: the next statement fails with
+  `session_ended` and `idle_in_transaction` and is not retried, so it can't commit on its own
+  outside the transaction, and the statement after it runs on a new session in autocommit.
 - The server has no tools that touch the local filesystem or any network endpoint other than the
   configured Hardcharger servers (and, for `login_sso`, the server's sign-in routes and your
   identity provider in your browser).
@@ -404,7 +448,7 @@ built from [gizmodata/hardcharger-js](https://github.com/gizmodata/hardcharger-j
 [scripts/hardcharger-js.commit](scripts/hardcharger-js.commit) and
 [scripts/chargewire-js.commit](scripts/chargewire-js.commit), and packed to `.clients/`, where
 `package-lock.json` finds them, so the tests run against those exact clients. `package.json`, and
-so the published package, names the npm package and its range (`^2.1.0`); the tarballs are a
+so the published package, names the npm package and its range (`^2.1.1`); the tarballs are a
 stand-in for development and CI only (`scripts/check-lock.mjs` checks both).
 
 ```bash

package/dist/broker.d.ts

@@ -0,0 +1,82 @@
+import { z } from "zod";
+import { type BrokerConfig, type McpConfig } from "./connection.js";
+import type { IntrospectionResult } from "./oauth.js";
+import { ConnectionRegistry } from "./registry.js";
+/** RFC 8693 token type of the caller's OAuth access token. */
+export declare const ACCESS_TOKEN_TYPE = "urn:ietf:params:oauth:token-type:access_token";
+declare const connectionSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    label: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    uri: z.ZodString;
+    default_catalog: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    default_schema: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    allow_writes: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+export type BrokeredConnection = z.infer<typeof connectionSchema>;
+/** A broker request that failed; `message` is safe to show the caller. */
+export declare class BrokerError extends Error {
+    readonly status?: number | undefined;
+    constructor(message: string, status?: number | undefined);
+}
+export interface BrokerHooks {
+    /** Test hook: the fetch implementation. */
+    fetch?: typeof fetch;
+    /** Test hook: clock (ms). */
+    now?: () => number;
+}
+/** Talks to the broker's two endpoints. Stateless; one instance serves every caller. */
+export declare class BrokerClient {
+    readonly config: BrokerConfig;
+    private readonly fetchImpl;
+    constructor(config: BrokerConfig, hooks?: BrokerHooks);
+    /** The servers the caller may reach. */
+    listConnections(subjectToken: string): Promise<{
+        connections: unknown[];
+        message?: string;
+    }>;
+    /**
+     * 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.
+     */
+    introspect(subjectToken: string): Promise<IntrospectionResult>;
+    /** A sign-in token for the caller on one server, and its lifetime in seconds. */
+    issueToken(subjectToken: string, connectionId: string): Promise<{
+        token: string;
+        expiresIn: number;
+    }>;
+    private post;
+}
+/**
+ * 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 declare class BrokeredRegistry extends ConnectionRegistry {
+    readonly broker: BrokerClient;
+    private callerToken;
+    private listedAt;
+    private refreshing;
+    private lastProblem;
+    private emptyMessage;
+    private readonly clock;
+    constructor(config: McpConfig, broker: BrokerClient, log: (message: string) => void, hooks?: Pick<BrokerHooks, "now">);
+    now(): number;
+    /** The caller's current OAuth access token (verified by the transport), presented to the broker. */
+    subjectToken(): string;
+    /** Records the token of the request being served: the newest one the client sent. */
+    setSubjectToken(token: string): void;
+    /** Asks the broker again when the list is stale (or always, with `force`). Never throws. */
+    refresh({ force }?: {
+        force?: boolean;
+    }): Promise<void>;
+    private load;
+    /** The broker's own words when it listed nothing, or why it could not be asked. */
+    status(): string | undefined;
+    protected noConnectionsMessage(): string;
+    /** Only servers this caller already uses: listing every table would sign in to every server they can reach. */
+    resourceConnections(): import("./connection.js").HardchargerConnection[];
+    secrets(): Array<string | undefined>;
+}
+export {};

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 {
@@ -125,7 +171,8 @@ export declare function errorCode(err: unknown): string | undefined;
  * this server doesn't know), a closed connection, a transport failure, and a lost session
  * the client could not replace. A refused credential is never retried, and neither is a
  * session ended because the sign-in was withdrawn (`token_revoked`, `credentials_changed`,
- * `principal_dropped`).
+ * `principal_dropped`), nor one ended for an idle transaction (`idle_in_transaction`: the
+ * client replaced that session itself, and the failed statement must not run again).
  */
 export declare function isConnectionLost(err: unknown): boolean;
 export interface SessionOverrides {
@@ -151,7 +198,7 @@ export interface RunContext {
     statementTimeoutMs: number | undefined;
 }
 /** Setting names read from hardcharger_settings() and reported by server_info. */
-export declare const SERVER_SETTINGS_OF_INTEREST: readonly ["hardcharger.version", "hardcharger.read_only", "hardcharger.max_sessions", "hardcharger.session_idle_timeout", "hardcharger.query_timeout", "hardcharger.memory_limit", "hardcharger.max_concurrent_statements", "hardcharger.instance_id", "hardcharger.cluster_id"];
+export declare const SERVER_SETTINGS_OF_INTEREST: readonly ["hardcharger.version", "hardcharger.read_only", "hardcharger.max_sessions", "hardcharger.session_idle_timeout", "hardcharger.idle_in_transaction_session_timeout", "hardcharger.query_timeout", "hardcharger.memory_limit", "hardcharger.max_concurrent_statements", "hardcharger.instance_id", "hardcharger.cluster_id"];
 export interface ConnectionHooks {
     /** Test hook: opens the client connection (defaults to `connect` from @gizmodata/hardcharger). */
     connect?: (options: ConnectOptions) => Promise<Connection>;