@datagrout/conduit 0.7.0 → 0.8.0

package/dist/index.d.mts

@@ -217,6 +217,837 @@ declare class ConduitIdentity {
  */
 declare function fetchWithIdentity(url: string, init: RequestInit, identity: ConduitIdentity): Promise<Response>;
 
+/**
+ * Typed error classes for the DataGrout Conduit SDK.
+ *
+ * All errors extend `ConduitError` so callers can catch the whole family with
+ * a single `instanceof ConduitError` check, or target specific subclasses.
+ */
+
+/**
+ * Base class for all errors thrown by the Conduit SDK.
+ *
+ * Fixes the prototype chain so `instanceof` works correctly when compiling
+ * to CommonJS / ES5 targets.
+ */
+declare class ConduitError extends Error {
+    constructor(message: string);
+}
+/**
+ * Thrown when a `Client` method is called before `connect()` has been invoked,
+ * or after `disconnect()` has been called.
+ */
+declare class NotInitializedError extends ConduitError {
+    constructor();
+}
+/**
+ * Thrown when the DataGrout gateway returns HTTP 429 (Too Many Requests).
+ *
+ * Authenticated DataGrout users are never rate-limited. Unauthenticated
+ * callers hitting the hourly cap will receive this error.
+ *
+ * @property status  - Parsed rate-limit header state.
+ * @property retryAfter - Seconds to wait before retrying (from `Retry-After` header), if present.
+ */
+declare class RateLimitError extends ConduitError {
+    readonly status: RateLimitStatus;
+    readonly retryAfter?: number;
+    constructor(status: RateLimitStatus, retryAfter?: number);
+}
+/**
+ * Thrown when the server returns HTTP 401 Unauthorized or HTTP 403 Forbidden.
+ */
+declare class AuthError extends ConduitError {
+    constructor(message?: string);
+}
+/**
+ * Thrown on network-level failures such as fetch errors, connection refused,
+ * or request timeouts.
+ */
+declare class NetworkError extends ConduitError {
+    constructor(message: string);
+}
+/**
+ * Thrown when the server returns an unexpected non-success HTTP status or
+ * a JSON-RPC error payload.
+ *
+ * @property code          - HTTP status code or JSON-RPC error code.
+ * @property serverMessage - Raw error message from the server.
+ */
+declare class ServerError extends ConduitError {
+    readonly code: number;
+    readonly serverMessage: string;
+    constructor(code: number, serverMessage: string);
+}
+/**
+ * Thrown when required parameters are missing, mutually-exclusive option
+ * combinations are invalid, or a method receives an unusable configuration.
+ */
+declare class InvalidConfigError extends ConduitError {
+    constructor(message: string);
+}
+
+/**
+ * OAuth 2.1 **authorization code + PKCE** — browser-consent sign-in.
+ *
+ * The `client_credentials` grant in {@link ./oauth} authenticates a *machine*:
+ * it needs a client secret issued out of band. This module authenticates a
+ * *person*: the app opens a browser, the user consents at the gateway, and the
+ * app receives a grant bound to that user's account. It is what a desktop or
+ * CLI application needs, and the only way to use
+ * `https://gateway.datagrout.ai/connect`, where the server binding is chosen at
+ * consent time and lives in the token rather than the URL.
+ *
+ * # Flow
+ *
+ * 1. {@link AuthCodeFlow.discover} — protected-resource metadata, then the
+ *    authorization server's metadata.
+ * 2. {@link AuthCodeFlow.register} — RFC 7591 dynamic client registration, as a
+ *    **public client** (no secret; PKCE takes its place).
+ * 3. {@link AuthCodeFlow.authorizeUrl} — build the consent URL and hold the
+ *    PKCE verifier and CSRF state in a {@link PendingAuthorization}.
+ * 4. The caller opens that URL and captures the redirect. `authcode/loopback`
+ *    can do the capturing.
+ * 5. {@link AuthCodeFlow.exchange} — trade the code for a {@link Grant}.
+ *
+ * ```ts
+ * import { AuthCodeFlow } from "@datagrout/conduit/authcode";
+ *
+ * const flow = await AuthCodeFlow.discover("https://gateway.datagrout.ai/connect");
+ * const client = await flow.register("My App", "http://127.0.0.1:8765/callback");
+ *
+ * const { url, pending } = flow.authorizeUrl();
+ * console.log(`Open: ${url}`);
+ *
+ * const grant = await flow.exchange(pending, code, state);
+ * ```
+ *
+ * # Persisting the grant
+ *
+ * This module owns the {@link Grant} shape and its refresh logic; it
+ * deliberately does **not** choose where a grant is stored. That is the
+ * application's decision — an OS keychain, a config file, a vault — and baking
+ * a filesystem opinion into an SDK makes it wrong for half its callers.
+ *
+ * {@link Grant.expires_at} is Unix **seconds** rather than a monotonic clock
+ * value, precisely so a grant survives serialization: it is written by one
+ * process and read by another, possibly in a different language.
+ */
+
+/**
+ * Scopes requested when the caller does not specify.
+ *
+ * Matches the authorization server's own registration default rather than
+ * inventing a finer-grained vocabulary: DataGrout splits the scope string on
+ * whitespace and stores what it is given, so a made-up scope is accepted
+ * silently and then means nothing.
+ */
+declare const DEFAULT_SCOPE = "mcp tools";
+/**
+ * The distinguishable failures of the authorization-code flow.
+ *
+ * The taxonomy is part of the cross-language contract: every conduit SDK
+ * distinguishes these same cases, so callers can branch identically.
+ */
+type AuthCodeErrorKind = 
+/** Metadata discovery failed or returned something unusable. */
+"discovery"
+/** The authorization server does not advertise dynamic client registration. */
+ | "no_registration_endpoint"
+/** Dynamic client registration was rejected. */
+ | "registration_rejected"
+/** `authorizeUrl` was called before a client id was known. */
+ | "no_client_id"
+/** The server does not support PKCE with S256. */
+ | "pkce_unsupported"
+/** The `state` returned by the redirect did not match the one sent. */
+ | "state_mismatch"
+/** The token endpoint rejected the exchange or refresh. */
+ | "token_exchange"
+/** The grant has no refresh token, so it cannot be renewed. */
+ | "not_refreshable"
+/** The authorization server returned an error at the redirect. */
+ | "denied"
+/** Transport failure talking to the authorization server. */
+ | "http";
+/** An error from the authorization-code flow, tagged with its {@link AuthCodeErrorKind}. */
+declare class AuthCodeError extends ConduitError {
+    readonly kind: AuthCodeErrorKind;
+    /** HTTP status, for `registration_rejected` and `token_exchange`. */
+    readonly status?: number;
+    /** Response body, for `registration_rejected` and `token_exchange`. */
+    readonly body?: string;
+    constructor(kind: AuthCodeErrorKind, message: string, extra?: {
+        status?: number;
+        body?: string;
+    });
+}
+/** RFC 8414 authorization server metadata (the fields this flow uses). */
+interface AuthServerMetadata {
+    issuer?: string;
+    authorization_endpoint: string;
+    token_endpoint: string;
+    /** RFC 7591 dynamic client registration endpoint, when offered. */
+    registration_endpoint?: string;
+    /** PKCE methods, e.g. `["S256"]`. */
+    code_challenge_methods_supported?: string[];
+    grant_types_supported?: string[];
+    scopes_supported?: string[];
+}
+/**
+ * Whether S256 is usable.
+ *
+ * An empty or absent list means the server did not advertise. RFC 8414 makes
+ * the field optional and DataGrout omits it on some paths, so absence is
+ * treated as "assume S256" rather than as a refusal — a server that truly
+ * cannot do S256 will reject the authorize request anyway.
+ */
+declare function supportsS256(metadata: AuthServerMetadata): boolean;
+/**
+ * A dynamically-registered client: the id **and** the redirect URI it is bound
+ * to.
+ *
+ * These travel together because an authorization server matches the redirect
+ * URI **exactly** against the value registered — there is no loopback-port
+ * exemption to rely on. Persisting the id alone means a later re-authorization
+ * on a freshly-chosen port is rejected as `invalid_redirect_uri`, and the
+ * failure only shows up once the first grant can no longer be refreshed.
+ */
+interface RegisteredClient {
+    client_id: string;
+    redirect_uri: string;
+}
+/**
+ * A user's authorization, ready to persist.
+ *
+ * The serialized shape is part of the cross-language contract: a grant written
+ * by one conduit SDK must be readable by another. Field names are therefore
+ * snake_case and fixed, and `expires_at` is Unix seconds.
+ */
+interface Grant {
+    access_token: string;
+    refresh_token?: string;
+    /** Absolute expiry, Unix seconds. Absent means the server did not say. */
+    expires_at?: number;
+    /** The client id this grant belongs to — needed to refresh it. */
+    client_id: string;
+    /** Token endpoint that issued it — needed to refresh it. */
+    token_endpoint: string;
+    scope?: string;
+    /** The resource this grant is bound to (RFC 8707). */
+    resource?: string;
+}
+/** Anything with `fetch`'s shape, so tests can substitute a fake. */
+type FetchLike = typeof globalThis.fetch;
+/**
+ * True when the access token is expired, or within the refresh skew of it.
+ *
+ * A grant with no stated expiry is treated as live: the server chose not to
+ * say, and guessing an expiry would throw away working tokens.
+ */
+declare function isGrantExpired(grant: Grant): boolean;
+/** Whether this grant can renew itself without user interaction. */
+declare function isGrantRefreshable(grant: Grant): boolean;
+/**
+ * Exchange the refresh token for a fresh grant.
+ *
+ * Returns a new grant; the old one should be discarded. DataGrout rotates
+ * refresh tokens, so keeping the previous grant around and using it again can
+ * invalidate the whole family.
+ */
+declare function refreshGrant(grant: Grant, fetchImpl?: FetchLike): Promise<Grant>;
+/**
+ * The secrets held between building the consent URL and redeeming the code.
+ *
+ * {@link AuthCodeFlow.exchange} consumes it, so a verifier is not replayed
+ * against a second code.
+ */
+interface PendingAuthorization {
+    readonly codeVerifier: string;
+    readonly state: string;
+    readonly redirectUri: string;
+}
+/** Drives discovery, registration, consent, and exchange. */
+declare class AuthCodeFlow {
+    private readonly fetchImpl;
+    private readonly metadataDoc;
+    /** The protected resource this grant will be bound to (RFC 8707). */
+    private readonly resource;
+    private clientIdValue?;
+    private redirectUriValue?;
+    private scope;
+    private constructor();
+    /**
+     * 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 discover(resourceUrl: string, fetchImpl?: FetchLike): Promise<AuthCodeFlow>;
+    /** Use a client id registered out of band, skipping dynamic registration. */
+    withClientId(clientId: string, redirectUri: string): 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: RegisteredClient): this;
+    /** Request scopes other than {@link DEFAULT_SCOPE}. */
+    withScope(scope: string): this;
+    /** The discovered metadata. */
+    get metadata(): AuthServerMetadata;
+    /** The client id, once registered or supplied. */
+    get clientId(): string | undefined;
+    /** The redirect URI this flow is bound to. */
+    get redirectUri(): string | undefined;
+    /**
+     * 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.
+     */
+    register(clientName: string, redirectUri: string): Promise<RegisteredClient>;
+    /**
+     * 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(): {
+        url: string;
+        pending: PendingAuthorization;
+    };
+    /**
+     * 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.
+     */
+    exchange(pending: PendingAuthorization, code: string, returnedState: string): Promise<Grant>;
+}
+/**
+ * Holds a {@link Grant} and keeps its access token fresh.
+ *
+ * Mirrors {@link ./oauth.OAuthTokenProvider} so both grant types reach the
+ * transports through the same path — `getToken` on the way out, `invalidate`
+ * on a 401.
+ */
+declare class AuthCodeProvider {
+    private grantValue;
+    private dirty;
+    private refreshPromise;
+    private readonly fetchImpl;
+    constructor(grant: Grant, fetchImpl?: FetchLike);
+    /** The current access token, refreshing first if it is at or near expiry. */
+    getToken(): Promise<string>;
+    /** A snapshot of the current grant, for persisting. */
+    grant(): Grant;
+    /** Whether the grant changed since the last {@link takeIfDirty}. */
+    isDirty(): boolean;
+    /**
+     * 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(): Grant | null;
+    /** Force the next {@link getToken} to refresh. Call on a 401. */
+    invalidate(): void;
+}
+/**
+ * Coerce whatever `auth.authorizationCode` holds into a provider.
+ *
+ * A caller who passes a bare {@link Grant} gets one made for them; a caller who
+ * passes their own {@link AuthCodeProvider} keeps it, so a rotated refresh
+ * token stays visible to them through `takeIfDirty()`.
+ */
+declare function authCodeProviderFrom(value: Grant | AuthCodeProvider | undefined, fetchImpl?: FetchLike): AuthCodeProvider | undefined;
+/** Generate an RFC 7636 code verifier: 43 characters of base64url. */
+declare function generateVerifier(): string;
+/** The S256 challenge for a verifier: `base64url(sha256(verifier))`. */
+declare function challengeS256(verifier: string): string;
+
+/**
+ * OAuth 2.1 `client_credentials` token provider for Conduit.
+ *
+ * Fetches short-lived JWTs from the DataGrout machine-client token endpoint
+ * and caches them, refreshing proactively before they expire.
+ *
+ * @example
+ * ```ts
+ * // Most users should use the high-level `auth.clientCredentials` option on
+ * // ClientOptions instead of instantiating this class directly.
+ * import { Client } from 'datagrout-conduit';
+ *
+ * const client = new Client({
+ *   url: 'https://app.datagrout.ai/servers/{uuid}/mcp',
+ *   auth: {
+ *     clientCredentials: { clientId: 'abc', clientSecret: 'xyz' },
+ *   },
+ * });
+ * ```
+ */
+/**
+ * Derive the token endpoint URL from a DataGrout MCP URL.
+ *
+ * @example
+ * ```ts
+ * deriveTokenEndpoint('https://app.datagrout.ai/servers/abc/mcp');
+ * // → 'https://app.datagrout.ai/servers/abc/oauth/token'
+ * ```
+ */
+declare function deriveTokenEndpoint(mcpUrl: string): string;
+/** @internal */
+declare class OAuthTokenProvider {
+    private readonly clientId;
+    private readonly clientSecret;
+    private readonly tokenEndpoint;
+    private readonly scope?;
+    private cached;
+    private fetchPromise;
+    constructor(opts: {
+        clientId: string;
+        clientSecret: string;
+        tokenEndpoint: string;
+        scope?: string;
+    });
+    /**
+     * Return the current bearer token, fetching a fresh one if necessary.
+     * Concurrent callers share a single in-flight fetch.
+     */
+    getToken(): Promise<string>;
+    /** Invalidate the cached token (e.g. after receiving a 401). */
+    invalidate(): void;
+    private fetchToken;
+}
+
+/**
+ * RFC 8693 **delegation** — an agent acting *for* a user.
+ *
+ * The two grants this SDK already speaks each answer one question.
+ * {@link ./oauth} (`client_credentials`) says *which machine* is calling;
+ * {@link ./authcode} says *which person* consented. Neither says both, and an
+ * agent working on a user's behalf needs to: the resource server has to know
+ * whose data it is (`sub`) and who is actually holding the connection (`act`).
+ * The RFC 8693 exchange produces exactly that token, from two the caller
+ * already has.
+ *
+ * # Delegation, not impersonation
+ *
+ * RFC 8693 distinguishes the two. In **delegation** the issued token names the
+ * user as `sub` and the agent in an `act` claim, so the resource server can
+ * see — and audit, and rate-limit, and revoke — the agent separately from the
+ * user. In **impersonation** the agent simply *becomes* the user, and the
+ * resource server cannot tell the difference. DataGrout's authorization server
+ * issues delegation tokens and requires an `actor_token`; this module
+ * therefore **requires an actor by default** and refuses to build a request
+ * without one. Impersonation is an explicit opt-in via
+ * {@link DelegationRequest.impersonation}, for RFC 8693 servers that support
+ * it.
+ *
+ * # Wire contract
+ *
+ * `POST {tokenEndpoint}`, form-encoded, in this order:
+ *
+ * | field | value |
+ * |---|---|
+ * | `grant_type` | {@link GRANT_TYPE} |
+ * | `subject_token`, `subject_token_type` | the user's token and its {@link TokenType} URN |
+ * | `actor_token`, `actor_token_type` | the agent's token and URN — omitted only under `impersonation()` |
+ * | `client_id`, `client_secret?` | client authentication, in the body by default (see {@link ClientAuth}) |
+ * | `audience?`, `resource?`, `scope?`, `requested_token_type?` | as set |
+ *
+ * `resource` is RFC 8707 and, when set, is always sent — the same invariant the
+ * authorization-code module keeps, so a delegated token cannot be replayed
+ * against a different resource.
+ *
+ * **The client must be the actor.** The `client_id` authenticating the request
+ * and the principal behind `actor_token` are expected to be the same agent.
+ * This SDK does not verify that — it cannot, without decoding the actor token —
+ * and the server enforces it (`unauthorized_client` when they differ).
+ *
+ * The response is `{access_token, issued_token_type, token_type, expires_in?,
+ * scope?}`; errors are RFC 6749 bodies `{error, error_description?}`, with the
+ * codes listed in {@link SERVER_ERROR_CODES}.
+ *
+ * ```ts
+ * import {
+ *   Client,
+ *   DelegatedProvider,
+ *   DelegationRequest,
+ *   OAuthTokenProvider,
+ *   TokenSource,
+ *   TOKEN_TYPES,
+ * } from "@datagrout/conduit";
+ *
+ * // The agent's own credential — the actor.
+ * const agent = new OAuthTokenProvider({
+ *   clientId: "agent_client_id",
+ *   clientSecret: "agent_client_secret",
+ *   tokenEndpoint: "https://gateway.datagrout.ai/oauth/token",
+ * });
+ *
+ * // The user's token — the subject. Here one handed to the agent for this run;
+ * // a long-lived app would use `TokenSource.authorizationCode(provider)`.
+ * const user = TokenSource.staticToken(userToken, TOKEN_TYPES.access_token);
+ *
+ * const request = new DelegationRequest(
+ *   "https://gateway.datagrout.ai/oauth/token",
+ *   "agent_client_id",
+ * )
+ *   .clientSecret("agent_client_secret")
+ *   .resource("https://gateway.datagrout.ai/connect");
+ *
+ * const provider = new DelegatedProvider(
+ *   request,
+ *   user,
+ *   TokenSource.clientCredentials(agent),
+ * );
+ *
+ * const client = new Client({
+ *   url: "https://gateway.datagrout.ai/connect",
+ *   auth: { delegation: provider },
+ * });
+ * ```
+ *
+ * # Naming
+ *
+ * Elsewhere in this SDK "token exchange" already means redeeming a
+ * `client_credentials` grant — `AuthCodeError`'s `token_exchange` kind, and the
+ * onramp's `token_exchange` stage. This module says *delegation* and *exchange*
+ * — {@link DelegationRequest.exchange}, {@link DelegatedToken} — and never
+ * reuses that label, so a log line cannot be read two ways.
+ */
+
+/** The RFC 8693 grant type. */
+declare const GRANT_TYPE = "urn:ietf:params:oauth:grant-type:token-exchange";
+/**
+ * `util.inspect`'s hook, resolved once so it can key a class method.
+ *
+ * Both this module's inspect overrides exist to keep tokens and the client
+ * secret out of a debug dump: without one, `util.inspect` walks the instance's
+ * own fields and prints them.
+ */
+declare const INSPECT_CUSTOM: unique symbol;
+/**
+ * RFC 6749 error codes an RFC 8693 endpoint returns, as
+ * {@link DelegationError.error} on a `server` failure.
+ *
+ * Listed so callers and ports compare against a name rather than a string they
+ * typed. `invalid_target` is the one specific to RFC 8693: the `audience` or
+ * `resource` is not one this server issues tokens for.
+ */
+declare const SERVER_ERROR_CODES: readonly ["invalid_request", "invalid_client", "invalid_grant", "unauthorized_client", "invalid_target", "invalid_scope", "unsupported_grant_type"];
+/** One of {@link SERVER_ERROR_CODES}. */
+type ServerErrorCode = (typeof SERVER_ERROR_CODES)[number];
+/**
+ * The RFC 8693 §3 token-type URNs this SDK names.
+ *
+ * Keyed by the RFC's own short names — which are also the keys
+ * `testdata/contract.json` uses — rather than camelCase, so the fixture and the
+ * table are read side by side.
+ */
+declare const TOKEN_TYPES: Readonly<{
+    /** The default for both subject and actor, and what DataGrout issues. */
+    readonly access_token: "urn:ietf:params:oauth:token-type:access_token";
+    /** A JWT presented as a JWT rather than as an opaque access token. */
+    readonly jwt: "urn:ietf:params:oauth:token-type:jwt";
+    readonly id_token: "urn:ietf:params:oauth:token-type:id_token";
+    readonly refresh_token: "urn:ietf:params:oauth:token-type:refresh_token";
+    readonly saml2: "urn:ietf:params:oauth:token-type:saml2";
+}>;
+/** A URN this SDK names. */
+type NamedTokenTypeUrn = (typeof TOKEN_TYPES)[keyof typeof TOKEN_TYPES];
+/**
+ * An RFC 8693 §3 token type identifier, **as its URN**.
+ *
+ * A token type *is* its URN here, so the wire shape is the same string in every
+ * language and serialization is the identity: nothing has to be mapped on the
+ * way out or in. The five named URNs autocomplete via {@link TOKEN_TYPES}; any
+ * other URN is carried verbatim, which is the open `other` case Rust models as
+ * `TokenType::Other` — {@link tokenTypeName} reports it as `"other"`.
+ */
+type TokenType = NamedTokenTypeUrn | (string & {});
+/** The short name of a token type, or `"other"` for a URN this SDK does not name. */
+type TokenTypeName = keyof typeof TOKEN_TYPES | "other";
+/**
+ * The short name for a token-type URN.
+ *
+ * For logs, tests and cross-language comparison — the value itself stays the
+ * URN, so this is never needed to build a request.
+ */
+declare function tokenTypeName(tokenType: TokenType): TokenTypeName;
+/**
+ * The distinguishable failures of a delegation exchange.
+ *
+ * The taxonomy is part of the cross-language contract: every conduit SDK
+ * distinguishes these same cases under the same names, so callers can branch
+ * identically.
+ */
+type DelegationErrorKind = 
+/** No subject token was set — there is nobody to act for. */
+"missing_subject"
+/** No actor token was set and the request is not an impersonation. */
+ | "missing_actor"
+/** Transport failure talking to the token endpoint. */
+ | "http"
+/** The token endpoint refused, with an RFC 6749 error body. */
+ | "server"
+/**
+ * The endpoint answered with something that is not an RFC 8693 response — a
+ * success body missing required fields, or a failure whose body is not an
+ * RFC 6749 error.
+ */
+ | "invalid_response";
+/** An error from a delegation exchange, tagged with its {@link DelegationErrorKind}. */
+declare class DelegationError extends ConduitError {
+    readonly kind: DelegationErrorKind;
+    /** HTTP status, for `server`. */
+    readonly status?: number;
+    /** RFC 6749 error code, for `server`; see {@link SERVER_ERROR_CODES}. */
+    readonly error?: ServerErrorCode | (string & {});
+    /** Human-readable description, when the server gave one. */
+    readonly errorDescription?: string;
+    constructor(kind: DelegationErrorKind, message: string, extra?: {
+        status?: number;
+        error?: ServerErrorCode | (string & {});
+        errorDescription?: string;
+    });
+}
+/**
+ * How the client authenticates to the token endpoint.
+ *
+ * - `"body"` — `client_id` and `client_secret` as form fields (RFC 6749 §2.3.1
+ *   `client_secret_post`). The default, and what DataGrout expects.
+ * - `"basic"` — `Authorization: Basic base64(client_id:client_secret)`
+ *   (`client_secret_basic`). `client_id` is still sent in the body, as RFC 6749
+ *   permits and some servers require.
+ */
+type ClientAuth = "body" | "basic";
+/**
+ * A delegation request, built up and then {@link DelegationRequest.exchange}d.
+ *
+ * The builder methods mutate and return `this`, as {@link AuthCodeFlow}'s do.
+ * {@link DelegationRequest.clone} exists because a {@link DelegatedProvider}
+ * holds one as a template and fills in fresh subject and actor tokens on each
+ * re-exchange.
+ */
+declare class DelegationRequest {
+    private readonly endpoint;
+    private readonly client;
+    private secret?;
+    private auth;
+    private subject?;
+    private actor?;
+    private audienceValue?;
+    private resourceValue?;
+    private scopeValue?;
+    private requestedTokenTypeValue?;
+    private impersonating;
+    /**
+     * Start a request against `tokenEndpoint`, authenticating as `clientId`.
+     *
+     * The client should be the actor — see the module docs.
+     */
+    constructor(tokenEndpoint: string, clientId: string);
+    /** The client secret, for confidential clients. */
+    clientSecret(secret: string): this;
+    /** Where the client secret travels. Defaults to `"body"`. */
+    clientAuth(auth: ClientAuth): this;
+    /**
+     * The token being exchanged: the **user's**, whose identity the issued token
+     * will carry as `sub`.
+     */
+    subjectToken(token: string, tokenType?: TokenType): this;
+    /** The **agent's** own token, which the issued token will name in `act`. */
+    actorToken(token: string, tokenType?: TokenType): this;
+    /** Logical name of the service the token is for (RFC 8693 `audience`). */
+    audience(audience: string): 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: string): this;
+    /** Scopes to request, space-separated. */
+    scope(scope: string): this;
+    /** The kind of token wanted back. Servers default to an access token. */
+    requestedTokenType(tokenType: TokenType): 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;
+    /** The token endpoint this request posts to. */
+    get tokenEndpoint(): string;
+    /** The client id this request authenticates as. */
+    get clientId(): string;
+    /** Whether {@link impersonation} was called. */
+    get isImpersonation(): boolean;
+    /** An independent copy, so a template can be filled in per exchange. */
+    clone(): DelegationRequest;
+    /**
+     * 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(): Array<[string, string]>;
+    /** Perform the exchange. */
+    exchange(fetchImpl?: FetchLike): Promise<DelegatedToken>;
+}
+/**
+ * A token issued by an exchange.
+ *
+ * The serialized shape is part of the cross-language contract, and is what
+ * `testdata/contract.json` pins: `access_token`, `issued_token_type` (a URN
+ * string), `token_type`, `expires_at?`, `scope?`. Field names are therefore
+ * snake_case and fixed, so `JSON.stringify` on one of these is the wire form —
+ * exactly as for `Grant`. As there, `expires_at` is **Unix seconds** —
+ * computed from the server's relative `expires_in` at receipt — never
+ * milliseconds and never a monotonic clock reading, so the token means the same
+ * thing once written down.
+ */
+interface DelegatedToken {
+    /** The bearer token to present. */
+    access_token: string;
+    /** What kind of token was issued, as its {@link TokenType} URN. */
+    issued_token_type: TokenType;
+    /** How to present it — `Bearer`, in practice. */
+    token_type: string;
+    /** Absolute expiry, Unix **seconds**. Absent means the server did not say. */
+    expires_at?: number;
+    /** Granted scopes, when the server reported them. */
+    scope?: string;
+}
+/**
+ * True when the token is expired, or within the refresh skew of it.
+ *
+ * A token with no stated expiry is treated as live: the server chose not to say,
+ * and guessing would throw away working tokens.
+ */
+declare function isDelegatedTokenExpired(token: DelegatedToken): boolean;
+/** What a {@link TokenSource} draws its token from — for logs, never the token. */
+type TokenSourceKind = "static" | "client_credentials" | "authorization_code" | "dynamic";
+/**
+ * Where a {@link DelegatedProvider} gets a subject or actor token from, and what
+ * {@link TokenType} to declare it as.
+ *
+ * A source is consulted on **every** exchange, so a provider-backed source hands
+ * over a *fresh* token each time — the whole point of wrapping a provider rather
+ * than copying its current token out.
+ */
+declare class TokenSource {
+    private readonly resolver;
+    private readonly sourceKind;
+    private readonly declaredType;
+    private constructor();
+    /** A fixed token, e.g. one handed to the agent for this run. */
+    static staticToken(token: string, tokenType?: TokenType): TokenSource;
+    /** The agent's own `client_credentials` provider — the usual **actor**. */
+    static clientCredentials(provider: OAuthTokenProvider, tokenType?: TokenType): TokenSource;
+    /**
+     * 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: AuthCodeProvider, tokenType?: TokenType): TokenSource;
+    /**
+     * 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: () => string | Promise<string>, tokenType?: TokenType): TokenSource;
+    /** Declare a different {@link TokenType} for this source. */
+    withTokenType(tokenType: TokenType): TokenSource;
+    /** The declared token type. */
+    get tokenType(): TokenType;
+    /** Where the token comes from. */
+    get kind(): TokenSourceKind;
+    /** Draw a token. */
+    resolve(): Promise<string>;
+    /** Never print tokens — only where they come from. */
+    toJSON(): {
+        kind: TokenSourceKind;
+        tokenType: TokenType;
+    };
+    [INSPECT_CUSTOM](): string;
+}
+/**
+ * Keeps a delegated token fresh, re-exchanging when it nears expiry.
+ *
+ * The third token provider in this SDK, shaped like the other two —
+ * {@link OAuthTokenProvider} and {@link AuthCodeProvider} — so every transport
+ * reaches it through the same path: `getToken` on the way out, `invalidate` on a
+ * 401. Each exchange pulls a fresh subject and actor token from its
+ * {@link TokenSource}s, so an expiring upstream credential is handled by the
+ * provider that owns it.
+ */
+declare class DelegatedProvider {
+    private readonly template;
+    private readonly subject;
+    private readonly actor?;
+    private readonly fetchImpl;
+    private cached;
+    /**
+     * The in-flight exchange, so concurrent callers make one request rather than
+     * a stampede. Mirrors `AuthCodeProvider`'s refresh de-duplication.
+     */
+    private exchangePromise;
+    /**
+     * 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: DelegationRequest, subject: TokenSource, actor?: TokenSource, fetchImpl?: FetchLike);
+    /**
+     * The current delegated bearer, exchanging first if there is none or it is at
+     * or near expiry.
+     */
+    getToken(): Promise<string>;
+    /**
+     * 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(): void;
+    /** A snapshot of the cached token, if any — for inspection or logging. */
+    token(): DelegatedToken | undefined;
+    /** The request template, without tokens. */
+    get request(): DelegationRequest;
+    /** Never print tokens, and never the client secret the template carries. */
+    toJSON(): Record<string, unknown>;
+    [INSPECT_CUSTOM](): string;
+    private liveToken;
+    private exchange;
+}
+
 /**
  * Type definitions for DataGrout Conduit
  */
@@ -371,6 +1202,29 @@ interface AuthConfig {
         /** Optional space-separated scope string (e.g. `"mcp tools"`). */
         scope?: string;
     };
+    /**
+     * OAuth 2.1 **authorization code** grant — a signed-in *person* rather than
+     * a machine. Obtain one with `AuthCodeFlow`, persist it, and pass it here on
+     * later runs.
+     *
+     * Pass a `Grant` and the SDK wraps it. Pass an `AuthCodeProvider` to keep
+     * ownership, which is what you want when a rotated refresh token has to be
+     * written back: poll `takeIfDirty()` and persist whatever it returns.
+     */
+    authorizationCode?: Grant | AuthCodeProvider;
+    /**
+     * RFC 8693 **delegation** — an agent acting *for* a user, so the issued token
+     * names the user as `sub` and the agent in `act`.
+     *
+     * `clientCredentials` says which machine is calling and `authorizationCode`
+     * says which person consented; a delegated token says both. Build a
+     * `DelegatedProvider` (see `./delegation`) and pass it here: the transports
+     * exchange on the way out and re-exchange on a 401, exactly as they do for the
+     * other two grants.
+     *
+     * Set alongside another option it wins, being the most specific choice.
+     */
+    delegation?: DelegatedProvider;
     custom?: Record<string, string>;
 }
 interface ClientOptions {
@@ -644,6 +1498,23 @@ declare class Subscription {
 declare class WsTransport extends Transport {
     private readonly _url;
     private readonly _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.
+     */
+    private readonly _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.
+     */
+    private readonly _oauthProvider?;
+    private readonly _authCodeProvider?;
+    /** RFC 8693 delegation, when `auth.delegation` is set. */
+    private readonly _delegatedProvider?;
     private _ws;
     private _nextId;
     private readonly _pending;
@@ -660,7 +1531,17 @@ declare class WsTransport extends Transport {
      * defaults to {@link PING_INTERVAL_MS}.
      */
     private _pingIntervalMs;
-    constructor(url: string, auth?: AuthConfig, _timeout?: number, _identity?: ConduitIdentity);
+    constructor(url: string, auth?: AuthConfig, _timeout?: number, identity?: ConduitIdentity);
+    /**
+     * 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.
+     */
+    private _resolveBearer;
     connect(): Promise<void>;
     disconnect(): Promise<void>;
     /**
@@ -1253,57 +2134,93 @@ declare class Client {
 }
 
 /**
- * OAuth 2.1 `client_credentials` token provider for Conduit.
+ * Capture the OAuth redirect on `127.0.0.1`.
  *
- * Fetches short-lived JWTs from the DataGrout machine-client token endpoint
- * and caches them, refreshing proactively before they expire.
+ * A native app has no web server to redirect to, so it runs one for a few
+ * seconds: bind a loopback port, send the user to the consent page, and read
+ * the `code` off the single request the browser makes coming back.
+ *
+ * This lives in its own module rather than in `authcode` so a headless caller
+ * can take the flow without pulling in an HTTP server — the same split every
+ * conduit SDK makes, so the surface looks the same in every language.
  *
- * @example
  * ```ts
- * // Most users should use the high-level `auth.clientCredentials` option on
- * // ClientOptions instead of instantiating this class directly.
- * import { Client } from 'datagrout-conduit';
+ * import { AuthCodeFlow } from "@datagrout/conduit";
+ * import { LoopbackListener } from "@datagrout/conduit";
  *
- * const client = new Client({
- *   url: 'https://app.datagrout.ai/servers/{uuid}/mcp',
- *   auth: {
- *     clientCredentials: { clientId: 'abc', clientSecret: 'xyz' },
- *   },
- * });
- * ```
- */
-/**
- * Derive the token endpoint URL from a DataGrout MCP URL.
+ * const listener = await LoopbackListener.bind();
+ * const flow = await AuthCodeFlow.discover("https://gateway.datagrout.ai/connect");
+ * await flow.register("My App", listener.redirectUri);
  *
- * @example
- * ```ts
- * deriveTokenEndpoint('https://app.datagrout.ai/servers/abc/mcp');
- * // → 'https://app.datagrout.ai/servers/abc/oauth/token'
+ * const { url, pending } = flow.authorizeUrl();
+ * // open `url` in a browser however suits the application
+ *
+ * const redirect = await listener.wait(300_000);
+ * const grant = await flow.exchange(pending, redirect.code, redirect.state);
  * ```
  */
-declare function deriveTokenEndpoint(mcpUrl: string): string;
-/** @internal */
-declare class OAuthTokenProvider {
-    private readonly clientId;
-    private readonly clientSecret;
-    private readonly tokenEndpoint;
-    private readonly scope?;
-    private cached;
-    private fetchPromise;
-    constructor(opts: {
-        clientId: string;
-        clientSecret: string;
-        tokenEndpoint: string;
-        scope?: string;
-    });
+/** What the authorization server sent back to the redirect URI. */
+interface Redirect {
+    /** The authorization code. */
+    code: string;
+    /** The `state` parameter, to be checked against the pending request. */
+    state: string;
+}
+/** A one-shot loopback listener for the OAuth redirect. */
+declare class LoopbackListener {
+    private readonly server;
+    private readonly boundPort;
+    private readonly path;
+    private settled;
+    private constructor();
     /**
-     * Return the current bearer token, fetching a fresh one if necessary.
-     * Concurrent callers share a single in-flight fetch.
+     * 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.
      */
-    getToken(): Promise<string>;
-    /** Invalidate the cached token (e.g. after receiving a 401). */
-    invalidate(): void;
-    private fetchToken;
+    static bind(): Promise<LoopbackListener>;
+    /**
+     * 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: number, path: string): Promise<LoopbackListener>;
+    /**
+     * 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: string): Promise<LoopbackListener>;
+    /** The port actually bound. */
+    get port(): number;
+    /**
+     * 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(): string;
+    /** Stop listening. Safe to call more than once. */
+    close(): void;
+    /**
+     * 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: number): Promise<Redirect>;
 }
 
 /**
@@ -1456,79 +2373,13 @@ interface SavedPaths {
 declare function saveIdentity(identity: RegisteredIdentity, directory?: string): SavedPaths;
 
 /**
- * Typed error classes for the DataGrout Conduit SDK.
- *
- * All errors extend `ConduitError` so callers can catch the whole family with
- * a single `instanceof ConduitError` check, or target specific subclasses.
- */
-
-/**
- * Base class for all errors thrown by the Conduit SDK.
- *
- * Fixes the prototype chain so `instanceof` works correctly when compiling
- * to CommonJS / ES5 targets.
- */
-declare class ConduitError extends Error {
-    constructor(message: string);
-}
-/**
- * Thrown when a `Client` method is called before `connect()` has been invoked,
- * or after `disconnect()` has been called.
- */
-declare class NotInitializedError extends ConduitError {
-    constructor();
-}
-/**
- * Thrown when the DataGrout gateway returns HTTP 429 (Too Many Requests).
- *
- * Authenticated DataGrout users are never rate-limited. Unauthenticated
- * callers hitting the hourly cap will receive this error.
- *
- * @property status  - Parsed rate-limit header state.
- * @property retryAfter - Seconds to wait before retrying (from `Retry-After` header), if present.
- */
-declare class RateLimitError extends ConduitError {
-    readonly status: RateLimitStatus;
-    readonly retryAfter?: number;
-    constructor(status: RateLimitStatus, retryAfter?: number);
-}
-/**
- * Thrown when the server returns HTTP 401 Unauthorized or HTTP 403 Forbidden.
- */
-declare class AuthError extends ConduitError {
-    constructor(message?: string);
-}
-/**
- * Thrown on network-level failures such as fetch errors, connection refused,
- * or request timeouts.
- */
-declare class NetworkError extends ConduitError {
-    constructor(message: string);
-}
-/**
- * Thrown when the server returns an unexpected non-success HTTP status or
- * a JSON-RPC error payload.
+ * The package version, in one place.
  *
- * @property code          - HTTP status code or JSON-RPC error code.
- * @property serverMessage - Raw error message from the server.
- */
-declare class ServerError extends ConduitError {
-    readonly code: number;
-    readonly serverMessage: string;
-    constructor(code: number, serverMessage: string);
-}
-/**
- * Thrown when required parameters are missing, mutually-exclusive option
- * combinations are invalid, or a method receives an unusable configuration.
+ * A leaf module so anything can read it — including the transports, which
+ * `index.ts` re-exports and therefore cannot be imported *from* without a
+ * cycle. The MCP handshake reports this to the server, and it used to be a
+ * separate hardcoded literal that had drifted six minor versions behind.
  */
-declare class InvalidConfigError extends ConduitError {
-    constructor(message: string);
-}
-
-/**
- * DataGrout Conduit SDK for TypeScript/JavaScript
- */
-
-declare const version = "0.5.0";
+declare const version = "0.8.0";
 
-export { type AuthConfig, AuthError, type Byok, type ChartOptions, Client, type ClientOptions, ConduitError, ConduitIdentity, type ConstrainOptions, type CreditEstimate, DEFAULT_IDENTITY_DIR, DG_CA_URL, DG_SUBSTRATE_ENDPOINT, type DiscoverOptions, type DiscoverResult, type FlowOptions, type ForgetOptions, type GuideOptions, type GuideRequestOptions, type GuideState, GuidedSession, InvalidConfigError, type Keypair, type MCPPrompt, type MCPResource, type MCPTool, type MtlsConfig, NetworkError, NotInitializedError, OAuthTokenProvider, type OnrampCredentials, type OnrampOptions, type PerformOptions, type PerformResult, type PlanOptions, type PrismFocusOptions, type QueryCellOptions, type RateLimit, RateLimitError, type RateLimitStatus, type Receipt, type ReflectOptions, type RefractOptions, type RegisteredIdentity, type RegistrationOptions, type RememberOptions, type RenewalOptions, type RotationOptions, type SavedPaths, ServerError, Subscription, type SubscriptionEvent, type ToolInfo, type ToolMeta, SUBPROTOCOL as WS_SUBPROTOCOL, WsTransport, deriveTokenEndpoint, extractMeta, fetchDgCaCert, fetchWithIdentity, generateKeypair, isDgUrl, refreshCaCert, registerAndExchange, registerIdentity, registerOnly, rotateIdentity, saveIdentity, version };
+export { AuthCodeError, type AuthCodeErrorKind, AuthCodeFlow, AuthCodeProvider, type AuthConfig, AuthError, type AuthServerMetadata, type Byok, type ChartOptions, Client, type ClientAuth, type ClientOptions, ConduitError, ConduitIdentity, type ConstrainOptions, type CreditEstimate, DEFAULT_IDENTITY_DIR, DEFAULT_SCOPE, GRANT_TYPE as DELEGATION_GRANT_TYPE, SERVER_ERROR_CODES as DELEGATION_SERVER_ERROR_CODES, DG_CA_URL, DG_SUBSTRATE_ENDPOINT, DelegatedProvider, type DelegatedToken, DelegationError, type DelegationErrorKind, DelegationRequest, type DiscoverOptions, type DiscoverResult, type FlowOptions, type ForgetOptions, type Grant, type GuideOptions, type GuideRequestOptions, type GuideState, GuidedSession, InvalidConfigError, type Keypair, LoopbackListener, type MCPPrompt, type MCPResource, type MCPTool, type MtlsConfig, type NamedTokenTypeUrn, NetworkError, NotInitializedError, OAuthTokenProvider, type OnrampCredentials, type OnrampOptions, type PendingAuthorization, type PerformOptions, type PerformResult, type PlanOptions, type PrismFocusOptions, type QueryCellOptions, type RateLimit, RateLimitError, type RateLimitStatus, type Receipt, type Redirect, type ReflectOptions, type RefractOptions, type RegisteredClient, type RegisteredIdentity, type RegistrationOptions, type RememberOptions, type RenewalOptions, type RotationOptions, type SavedPaths, ServerError, type ServerErrorCode, Subscription, type SubscriptionEvent, TOKEN_TYPES, TokenSource, type TokenSourceKind, type TokenType, type TokenTypeName, type ToolInfo, type ToolMeta, SUBPROTOCOL as 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 };