@gizmodata/hardcharger-mcp 2.0.0 → 2.2.0

package/CHANGELOG.md

@@ -7,6 +7,36 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+- Built on the Chargewire protocol and clients: `@gizmodata/hardcharger` 2.1.0, on
+  `@gizmodata/chargewire` 2.0.0. `server_info` reports
+  the protocol as `chargewire 1`. Tool names, settings and connection URIs are unchanged.
+- Still works with Hardcharger servers released before the rename (2.2.0 and earlier): the
+  client falls back to them on its own, and `HARDCHARGER_URI` values written for earlier
+  versions keep working.
+
 ## [2.0.0] - 2026-10-20
 
 The first published release, with Hardcharger 2.0.0 (0.1.0 was never published). The Changed and
@@ -14,11 +44,11 @@ Fixed entries describe what moved since 0.1.0, for anyone who installed it from
 <!-- Set the date above at tag time. -->
 
 ### Changed
-- Built on `@gizmodata/hardcharger` 2.0.0 (hardcharger-js `a6e93a2`, on `@gizmodata/warp-sql` 1.0.0,
-  warp-sql-js `903feb4`), the clients for Warp SQL protocol 1.0.0 with browser sign-in (were
+- Built on `@gizmodata/hardcharger` 2.0.0 (hardcharger-js `a6e93a2`, on `@gizmodata/chargewire` 1.0.0,
+  chargewire-js `903feb4`), the clients for Chargewire protocol 1.0.0 with browser sign-in (were
   `a4ac97c` and `6dea14c`). The chart, the extension manifest and the npm package are 2.0.0: the
   Hardcharger clients and integrations launch with the server's version.
-- **Breaking:** `login_sso` runs Warp SQL browser sign-in (§4.3) on the connection's own URI and
+- **Breaking:** `login_sso` runs Chargewire browser sign-in (§4.3) on the connection's own URI and
   port, through `@gizmodata/hardcharger`, as Hardcharger now offers it (its separate OAuth port and
   `/oauth/initiate` routes are gone). It signs in with the access token the server hands out, used
   as is (call `login_sso` again when it expires), instead of exchanging an ID token. A failed
@@ -31,10 +61,10 @@ Fixed entries describe what moved since 0.1.0, for anyone who installed it from
   `client_transport_error` and `client_connection_closed` (was `transport_error`,
   `connection_closed`), the plain-HTTP hint keys on `client_transport_error`, and error messages
   name the new codes (e.g. `(client_transport_error)`, `(client_invalid_argument)`).
-- `server_info` on a Warp SQL server other than Hardcharger reads the DuckDB version from the
+- `server_info` on a Chargewire server other than Hardcharger reads the DuckDB version from the
   server-info key `duckdb_version` (was `engine_version`, which protocol 1.0.0 dropped).
 - A session ended with reason `token_revoked`, `credentials_changed` or `principal_dropped` is no
-  longer reopened with the configured credentials (Warp SQL §4.2, §5.6): the error, with its
+  longer reopened with the configured credentials (Chargewire §4.2, §5.6): the error, with its
   reason, is returned. `killed`, `token_expired`, no reason or an unknown reason still reopen once.
 
 ### Added
@@ -50,8 +80,8 @@ Fixed entries describe what moved since 0.1.0, for anyone who installed it from
 ### Fixed
 - CI's live tests on main failed: the browser sign-in suite started `hardcharger-server` with
   `--oauth-port`, which Hardcharger 2.0.0-rc.1 removed (browser sign-in runs on the server's own
-  port, Warp SQL §4.3), so the server exited with "unknown option". The suite now passes
-  `--oauth-base-url` with the server's port (from the merged Warp SQL 1.0 work).
+  port, Chargewire §4.3), so the server exited with "unknown option". The suite now passes
+  `--oauth-base-url` with the server's port (from the merged Chargewire 1.0 work).
 
 ### Documentation
 
@@ -64,8 +94,8 @@ Fixed entries describe what moved since 0.1.0, for anyone who installed it from
 
 The Hardcharger™ port of [gizmosql-mcp](https://github.com/gizmodata/gizmosql-mcp) 0.4.11: the same
 tools, resource, transports, OAuth resource-server mode, per-user HTTP sessions, Claude Desktop
-extension, container image and Helm chart, on Hardcharger's Warp SQL protocol through
-`@gizmodata/hardcharger` (hardcharger-js `a4ac97c` on warp-sql-js `6dea14c`).
+extension, container image and Helm chart, on Hardcharger's Chargewire protocol through
+`@gizmodata/hardcharger` (hardcharger-js `a4ac97c` on chargewire-js `6dea14c`).
 
 ### Added
 - Tools `list_connections`, `use_connection`, `list_catalogs`, `list_schemas`, `list_tables`,
@@ -81,21 +111,21 @@ extension, container image and Helm chart, on Hardcharger's Warp SQL protocol th
   (`HARDCHARGER_MTLS_CERT` + `HARDCHARGER_MTLS_KEY`: alone, the certificate is the credential), or
   the server's browser sign-in (`login_sso`, the same OAuth routes as `hardcharger --auth-type
   external`; `HARDCHARGER_BROWSER` names the browser). `HARDCHARGER_TLS_ROOTS` trusts a private CA.
-- Query timeouts are the server's own (`statementTimeoutMs`, Warp SQL §6.9): a runaway statement is
+- Query timeouts are the server's own (`statementTimeoutMs`, Chargewire §6.9): a runaway statement is
   cancelled on the server and reported as `statement_timeout`, with a client-side cancel a few
   seconds later as backstop. This covers `execute_statement` too.
 - Lost sessions: the client replaces a session the server evicted and replays its catalog and
   schema, including ones set by `use_schema` or a `USE` run through `run_query`; a session an
   administrator killed, a closed connection or a transport failure reopens the connection once.
   `server_info` reports `session_replacements` and `reconnects`.
-- Errors keep the server's message with its Warp SQL code, SQLSTATE, HTTP status and request id
+- Errors keep the server's message with its Chargewire code, SQLSTATE, HTTP status and request id
   (`... (sql_error, SQLSTATE 42P01, HTTP 400, request r_...)`); errors raised before an answer get
   their code added (`(transport_error)`), and a TLS handshake against a plain-HTTP server says to
   add `?tls=false`.
 - `server_info` reports `HARDCHARGER_VERSION()`, `HARDCHARGER_USER()`, `HARDCHARGER_ROLE()`, the
   protocol and capabilities from discovery, the server's idle timeout from the session document,
   and settings from `hardcharger_settings()`.
-- Bind parameters travel as Warp SQL JSON parameters; a date, timestamp or binary parameter binds
+- Bind parameters travel as Chargewire JSON parameters; a date, timestamp or binary parameter binds
   the row as Arrow data through a prepared statement.
 - Claude Desktop extension (`.mcpb`): one all-JavaScript bundle for every platform (no native
   driver), with URI, token, client certificate and CA settings.
@@ -113,7 +143,7 @@ extension, container image and Helm chart, on Hardcharger's Warp SQL protocol th
 - The native ADBC driver and everything around it (bundled drivers per platform,
   `GIZMOSQL_DRIVER_LIB`, the install-script approval): the client is pure JavaScript.
 - The timed session refresh (`GIZMOSQL_SESSION_REFRESH_SECONDS`): GizmoSQL silently recreated an
-  evicted session, so the search path had to be re-applied on a timer; Warp SQL reports the loss
+  evicted session, so the search path had to be re-applied on a timer; Chargewire reports the loss
   and the client replays the session's options.
 - Host/port/plaintext settings (`GIZMOSQL_HOST`, `_PORT`, `_PLAINTEXT`): the URI says all three.
-- Flight SQL error unwrapping and the SqlInfo fallback, which have no Warp SQL counterpart.
+- Flight SQL error unwrapping and the SqlInfo fallback, which have no Chargewire counterpart.

package/README.md

@@ -12,7 +12,7 @@
   <img src="https://img.shields.io/badge/MCP-server%20%2B%20Claude%20Desktop%20extension-d97757.svg" alt="MCP server and Claude Desktop extension">
   <img src="https://img.shields.io/badge/TypeScript-ESM-3178C6.svg?logo=typescript&logoColor=white" alt="TypeScript, ESM">
   <img src="https://img.shields.io/badge/Node-%E2%89%A522.19-339933.svg?logo=node.js&logoColor=white" alt="Node 22.19 or later">
-  <a href="https://github.com/gizmodata/warp-sql"><img src="https://img.shields.io/badge/protocol-Warp%20SQL%201.0.0-31a8db.svg" alt="Warp SQL protocol"></a>
+  <a href="https://github.com/gizmodata/chargewire"><img src="https://img.shields.io/badge/protocol-Chargewire%201.0.0-31a8db.svg" alt="Chargewire protocol"></a>
   <a href="https://github.com/gizmodata/hardcharger-js"><img src="https://img.shields.io/badge/built%20on-Hardcharger%20JS-31a8db.svg" alt="Built on the Hardcharger JavaScript client"></a>
   <a href="https://github.com/gizmodata/hardcharger"><img src="https://img.shields.io/badge/server-Hardcharger-f15a24.svg" alt="Hardcharger"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-brightgreen.svg" alt="Apache 2.0 license"></a>
@@ -31,16 +31,17 @@ lets Claude Desktop, Claude Code and any other MCP client explore your schema an
 a Hardcharger server you can reach from your machine (including private networks over VPN), or,
 over Streamable HTTP, serves a whole team behind OAuth.
 
-It speaks [Warp SQL](https://github.com/gizmodata/warp-sql), Hardcharger's HTTP protocol, through
+It speaks [Chargewire](https://github.com/gizmodata/chargewire), Hardcharger's HTTP protocol, through
 the Hardcharger JavaScript client ([`@gizmodata/hardcharger`](https://github.com/gizmodata/hardcharger-js)):
 pure JavaScript, no native driver, so one extension bundle serves every platform Claude Desktop
 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.0.0, with Hardcharger 2.0.0.** Built on `@gizmodata/hardcharger` 2.0.0 (hardcharger-js
-> `a6e93a2`, on `@gizmodata/warp-sql` 1.0.0, Warp SQL protocol 1.0.0); tested against
-> `hardcharger-server` 2.0.0-rc.1 and the image of Hardcharger's main branch.
+> **Status: 2.2.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);
+> tested against the image of Hardcharger's main branch and against Hardcharger 2.2.0, released
+> before the protocol was renamed to Chargewire.
 
 ## 🧰 Tools
 
@@ -154,7 +155,7 @@ Each connection takes one credential:
 | Setting | Sign-in |
 | --- | --- |
 | `HARDCHARGER_USERNAME` + `HARDCHARGER_PASSWORD` | Password (any character, `:` and `@` included) |
-| `HARDCHARGER_TOKEN` | A signed sign-in token the server trusts (`--token-allowed-issuer` with `--token-jwks-uri` or `--token-signature-verify-cert-path`), sent with Warp SQL's `token_exchange` grant. The same token also works as the password of user `token`. Its `role` claim (`admin`, `user`, `readonly`) decides what it may do |
+| `HARDCHARGER_TOKEN` | A signed sign-in token the server trusts (`--token-allowed-issuer` with `--token-jwks-uri` or `--token-signature-verify-cert-path`), sent with Chargewire's `token_exchange` grant. The same token also works as the password of user `token`. Its `role` claim (`admin`, `user`, `readonly`) decides what it may do |
 | `HARDCHARGER_MTLS_CERT` + `HARDCHARGER_MTLS_KEY` | Client certificate sign-in (mutual TLS) on a server started with `--mtls-certificate-sign-in`: the certificate is the credential. With a password or token beside them, the certificate only admits the connection |
 | `HARDCHARGER_ENABLE_SSO=true` | No stored credential: `login_sso` signs in through the server's identity provider in your browser |
 
@@ -175,7 +176,7 @@ the server's codes: `unknown_certificate_identity` (401) for a certificate that
 `HARDCHARGER_TLS_ROOTS` or `HARDCHARGER_TLS_SKIP_VERIFY`).
 
 **Browser sign-in (`login_sso`).** On a server started with `--oauth-client-id` (and its identity
-provider settings), `login_sso` opens the provider's login page through the server's Warp SQL
+provider settings), `login_sso` opens the provider's login page through the server's Chargewire
 browser sign-in (on the connection's own URI and port), waits for you to finish, and connects with
 the Hardcharger access token the server hands out, kept in memory only; when it expires, call
 `login_sso` again. A refusal names its code (`access_denied`, `identity_provider_error`,
@@ -196,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
@@ -236,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
@@ -252,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
@@ -299,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 |
 
@@ -346,13 +386,14 @@ 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.
 - The row cap is enforced by the server: reads run as `SELECT * FROM (<your query>) LIMIT
   max_rows + 1`, over one result stream that is closed at the cap, which stops the statement.
-- The timeout is the server's (Warp SQL `statementTimeoutMs`): it cancels a statement that runs too
+- The timeout is the server's (Chargewire `statementTimeoutMs`): it cancels a statement that runs too
   long, `execute_statement` included, and the error says `statement_timeout`. A client-side cancel
   a few seconds later is the backstop.
 - Lost sessions: when Hardcharger evicts an idle session, the client opens a replacement with the
@@ -397,17 +438,17 @@ After changing settings, start a new chat.
 
 ## 🛠️ Building and testing
 
-Node 22.19 or later. For development and CI, `@gizmodata/hardcharger` and `@gizmodata/warp-sql` are
+Node 22.19 or later. For development and CI, `@gizmodata/hardcharger` and `@gizmodata/chargewire` are
 built from [gizmodata/hardcharger-js](https://github.com/gizmodata/hardcharger-js) and
-[gizmodata/warp-sql-js](https://github.com/gizmodata/warp-sql-js) at the commits pinned in
+[gizmodata/chargewire-js](https://github.com/gizmodata/chargewire-js) at the commits pinned in
 [scripts/hardcharger-js.commit](scripts/hardcharger-js.commit) and
-[scripts/warp-sql-js.commit](scripts/warp-sql-js.commit), and packed to `.clients/`, where
+[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.0.0`); the tarballs are a
+so the published package, names the npm package and its range (`^2.1.0`); the tarballs are a
 stand-in for development and CI only (`scripts/check-lock.mjs` checks both).
 
 ```bash
-npm run clients        # clone both clients (git access needed), build and pack the pinned commits
+npm run clients        # clone both clients, build and pack the pinned commits
 npm ci
 npm run lint:ci        # eslint and the lock's shape
 npm run typecheck      # src and tests
@@ -417,14 +458,18 @@ docker build -t hardcharger-mcp .   # container image for the HTTP transport
 helm lint charts/hardcharger-mcp    # Helm chart
 ```
 
-`HARDCHARGER_MCP_WARP_SQL_JS_REPO` and `HARDCHARGER_MCP_HARDCHARGER_JS_REPO` point `npm run clients`
-at local checkouts.
+`HARDCHARGER_MCP_CHARGEWIRE_JS_REPO` and `HARDCHARGER_MCP_HARDCHARGER_JS_REPO` point
+`npm run clients` at local checkouts.
 
 The live suites start `hardcharger-server` themselves, on free loopback ports, with a fresh
 administrator password that contains `:` and `@`, an empty home directory (DuckDB's secrets
 directory included), and only `PATH`, `HOME`, `TMPDIR` and the password in its environment; the MCP
 server under test gets `PATH`, `HOME` and the settings each test names, never your shell's. Without
-the binary they fail; they never skip, and a run in which no test passed fails too.
+the binary they fail; they never skip, and a run in which no test passed fails too. One suite
+checks a Hardcharger released before the protocol was renamed to Chargewire (the
+`ghcr.io/gizmodata/hardcharger:2.2.0` image, already running, plain HTTP), named by
+`HARDCHARGER_MCP_TEST_OLD_SERVER` (`host:port`, with `HARDCHARGER_MCP_TEST_OLD_SERVER_PASSWORD`);
+CI starts one. Without it a full local run leaves that suite out and says so; in CI it fails.
 
 ```bash
 export HARDCHARGER_MCP_TEST_SERVER_BINARY=/path/to/hardcharger-server
@@ -439,9 +484,8 @@ Negative tests assert the error code (`invalid_credentials`, `permission_denied`
 `invalid_option_value`), each beside a positive twin. CI runs everything against the image of
 Hardcharger's main branch (`ghcr.io/gizmodata/hardcharger:main`), pulled with the workflow's
 `GITHUB_TOKEN`; while the image is private the package must grant this repository read access
-(package settings, "Manage Actions access"), or the live jobs fail. CI clones the clients with
-`DEPLOY_KEY_WARP_SQL_JS` and `DEPLOY_KEY_HARDCHARGER_JS`, read-only deploy keys of those
-repositories (needed while they are private).
+(package settings, "Manage Actions access"), or the live jobs fail. CI clones both clients
+anonymously over https.
 
 ## 📦 Releasing
 

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 {};