@tidblink/server 0.0.0-stage → 0.4.0-rc.0

package/dist/client-tool-executor.js

@@ -0,0 +1,190 @@
+import { BackendConnectionClosedError, BackendRequestError, TiDBLinkError, } from "./errors.js";
+const OUTPUT_MAX = 65_536;
+const ERROR_MAX = 4_096;
+/** How long a settled callId is remembered to ignore late duplicates. */
+const SETTLED_MEMORY_MS = 60_000;
+/**
+ * Raised through `onError` when the core did not accept a Client Tool
+ * result. `reason` is the core's: `call_settled` (the call already had an
+ * outcome, for example its deadline passed), `not_claimed` or
+ * `call_not_found`.
+ */
+export class ClientToolResultRefusedError extends TiDBLinkError {
+    callId;
+    reason;
+    constructor(callId, reason) {
+        super(`The core did not accept the result of Client Tool call ${callId}: ${reason}`);
+        this.callId = callId;
+        this.reason = reason;
+    }
+}
+const isString = (value) => typeof value === "string" && value !== "";
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const parseCall = (params) => isString(params.callId) &&
+    isString(params.sessionId) &&
+    isString(params.userId) &&
+    isString(params.turnId) &&
+    isString(params.name) &&
+    isObject(params.arguments) &&
+    isString(params.claimBy) &&
+    isString(params.deadlineAt) &&
+    Number.isFinite(Date.parse(params.deadlineAt))
+    ? params
+    : undefined;
+const truncate = (text, max) => text.length <= max ? text : `${text.slice(0, max - 1)}…`;
+/** The text the model receives for a handler's return value. */
+const outputOf = (value) => {
+    let output;
+    try {
+        output = typeof value === "string" ? value : value === undefined ? "" : JSON.stringify(value);
+    }
+    catch (cause) {
+        return { error: { message: `The tool returned a value that is not JSON: ${String(cause)}` } };
+    }
+    if (output === undefined)
+        return { error: { message: "The tool returned a value that is not JSON" } };
+    if (output.length > OUTPUT_MAX)
+        return {
+            error: { message: `The tool output exceeds ${OUTPUT_MAX} characters` },
+        };
+    return { output };
+};
+const errorOf = (error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    return { error: { message: truncate(message || "The tool failed", ERROR_MAX) } };
+};
+/**
+ * Executes the Client Tool calls an executing Session connection receives:
+ * claim first, run only after `claimed: true`, then submit the result over any
+ * Backend Connection until the call's deadline. Each callId runs at most once.
+ */
+export class ClientToolExecutor {
+    #pool;
+    #sessionId;
+    #handlers;
+    #report;
+    #calls = new Map();
+    constructor(input) {
+        this.#pool = input.pool;
+        this.#sessionId = input.sessionId;
+        this.#handlers = input.handlers;
+        this.#report = input.report;
+    }
+    /** Handle one `tool.call` from the connection that delivered it. */
+    receive(params, link) {
+        const call = parseCall(params);
+        if (!call || call.sessionId !== this.#sessionId) {
+            this.#report(new TiDBLinkError("Received an invalid Client Tool call"));
+            return;
+        }
+        // The core may send a call again after a reconnect; it runs once.
+        if (this.#calls.has(call.callId))
+            return;
+        // Never sent: the core sends it again to the next attachment while unclaimed.
+        if (!link.open)
+            return;
+        this.#calls.set(call.callId, "claiming");
+        void this.#claimAndRun(call, link);
+    }
+    async #claimAndRun(call, link) {
+        let answer;
+        try {
+            answer = await link.request("tool.claim", { callId: call.callId });
+        }
+        catch (error) {
+            if (error instanceof BackendConnectionClosedError ||
+                (error instanceof BackendRequestError && error.code === -32603)) {
+                // The claim may have been granted; the call must not run, so close it as failed.
+                await this.#submit(call, {
+                    error: {
+                        message: "The Application Server lost the claim's answer and did not execute the call",
+                    },
+                });
+                return;
+            }
+            this.#calls.set(call.callId, "settled");
+            this.#forget(call);
+            this.#report(error);
+            return;
+        }
+        if (!answer || answer.claimed !== true) {
+            if (answer?.reason === "superseded") {
+                // Another generation holds the Session; this process may receive it again there.
+                this.#calls.delete(call.callId);
+            }
+            else {
+                this.#calls.set(call.callId, "settled");
+                this.#forget(call);
+            }
+            return;
+        }
+        this.#calls.set(call.callId, "running");
+        await this.#submit(call, await this.#execute(call));
+    }
+    async #execute(call) {
+        const handler = Object.hasOwn(this.#handlers, call.name)
+            ? this.#handlers[call.name]
+            : undefined;
+        if (!handler)
+            return {
+                error: {
+                    message: `Client Tool ${call.name} has no handler in this Application Server`,
+                },
+            };
+        const deadlineAt = new Date(call.deadlineAt);
+        const controller = new AbortController();
+        let timer;
+        const expired = new Promise((resolve) => {
+            timer = setTimeout(() => {
+                controller.abort(new TiDBLinkError("The Client Tool call reached its deadline"));
+                resolve({ error: { message: "The tool did not finish before its deadline" } });
+            }, Math.max(0, deadlineAt.getTime() - Date.now()));
+        });
+        const context = {
+            callId: call.callId,
+            sessionId: call.sessionId,
+            userId: call.userId,
+            turnId: call.turnId,
+            name: call.name,
+            deadlineAt,
+            signal: controller.signal,
+        };
+        const run = (async () => {
+            try {
+                return outputOf(await handler.run(call.arguments, context));
+            }
+            catch (error) {
+                return errorOf(error);
+            }
+        })();
+        try {
+            return await Promise.race([run, expired]);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    async #submit(call, result) {
+        try {
+            const answer = await this.#pool.request("tool.result", { callId: call.callId, ...result }, { retryUntil: Date.parse(call.deadlineAt) });
+            if (answer?.accepted !== true) {
+                if (answer?.reason === "not_claimed") {
+                    // The lost claim never took effect: the call may arrive again and run then.
+                    this.#calls.delete(call.callId);
+                    return;
+                }
+                this.#report(new ClientToolResultRefusedError(call.callId, answer?.reason ?? "unknown"));
+            }
+        }
+        catch (error) {
+            this.#report(error);
+        }
+        this.#calls.set(call.callId, "settled");
+        this.#forget(call);
+    }
+    #forget(call) {
+        const timer = setTimeout(() => this.#calls.delete(call.callId), Math.max(0, Date.parse(call.deadlineAt) - Date.now()) + SETTLED_MEMORY_MS);
+        timer.unref?.();
+    }
+}
+//# sourceMappingURL=client-tool-executor.js.map

package/dist/client-tool-executor.js.map

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

package/dist/client-tools.d.ts

@@ -0,0 +1,21 @@
+import { HttpClient } from "./http.js";
+import type { RequestOptions } from "./organization.js";
+export interface ClientToolDeclaration {
+    type: "function";
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+}
+export interface ClientToolSet {
+    revision: number;
+    tools: ClientToolDeclaration[];
+    /** Pass this exact value when replacing the complete set. */
+    etag: string;
+}
+export interface ReplaceClientToolsOptions extends RequestOptions {
+    ifMatch: string;
+}
+export declare function validateClientTools(tools: readonly ClientToolDeclaration[]): void;
+export declare function getClientTools(http: HttpClient, sessionId: string, options?: RequestOptions): Promise<ClientToolSet>;
+export declare function replaceClientTools(http: HttpClient, sessionId: string, tools: readonly ClientToolDeclaration[], options: ReplaceClientToolsOptions): Promise<ClientToolSet>;
+//# sourceMappingURL=client-tools.d.ts.map

package/dist/client-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-tools.d.ts","sourceRoot":"","sources":["../src/client-tools.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,UAAU,EAKX,MAAM,WAAW,CAAC;AACnB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAExD,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,UAAU,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrC;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,qBAAqB,EAAE,CAAC;IAC/B,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,yBAA0B,SAAQ,cAAc;IAC/D,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,SAAS,qBAAqB,EAAE,GACtC,IAAI,CAuBN;AAkBD,wBAAsB,cAAc,CAClC,IAAI,EAAE,UAAU,EAChB,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,aAAa,CAAC,CAQxB;AAED,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,UAAU,EAChB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,SAAS,qBAAqB,EAAE,EACvC,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC,aAAa,CAAC,CAqBxB"}

package/dist/client-tools.js

@@ -0,0 +1,48 @@
+import { requireInteraction } from "./history.js";
+import { OutcomeUnknownError, TiDBLinkError } from "./errors.js";
+import { HttpClient, requireEtag, requireKnownKeys, requireCreationKey, } from "./http.js";
+export function validateClientTools(tools) {
+    if (!Array.isArray(tools) || tools.length > 64)
+        throw new TypeError("tools must be an array of at most 64 declarations");
+    for (const tool of tools) {
+        requireKnownKeys(tool, ["type", "name", "description", "parameters"], "Client Tool declaration");
+        if (tool.type !== "function" ||
+            typeof tool.name !== "string" ||
+            !tool.name ||
+            typeof tool.description !== "string" ||
+            !tool.description ||
+            typeof tool.parameters !== "object" ||
+            tool.parameters === null ||
+            Array.isArray(tool.parameters))
+            throw new TypeError("Client Tools require a function name, description and JSON Schema parameters");
+    }
+}
+const toolSet = (result) => {
+    if (!Number.isSafeInteger(result.data?.revision) ||
+        result.data.revision < 0 ||
+        !Array.isArray(result.data.tools))
+        throw new TiDBLinkError("TiDB Link returned an invalid Client Tool set", {
+            requestId: result.requestId,
+        });
+    return { ...result.data, etag: requireEtag(result) };
+};
+const toolsPath = (sessionId) => `/sessions/${encodeURIComponent(sessionId)}/tools`;
+export async function getClientTools(http, sessionId, options) {
+    if (options)
+        requireKnownKeys(options, ["signal", "requestId"], "Client Tool read options");
+    return toolSet(await http.getResponse(toolsPath(sessionId), options));
+}
+export async function replaceClientTools(http, sessionId, tools, options) {
+    validateClientTools(tools);
+    requireKnownKeys(options, ["ifMatch", "signal", "requestId"], "Client Tool replacement options");
+    if (typeof options.ifMatch !== "string" || !options.ifMatch)
+        throw new TypeError("Client Tool replacement requires ifMatch");
+    const result = await http.response(toolsPath(sessionId), { method: "PUT", body: { tools }, outcomeUnknown: true, ...options });
+    try {
+        return toolSet(result);
+    }
+    catch (cause) {
+        throw new OutcomeUnknownError("Client Tool replacement returned no usable receipt; read the current set before retrying", { sessionId, requestId: result.requestId, cause });
+    }
+}
+//# sourceMappingURL=client-tools.js.map

package/dist/client-tools.js.map

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

package/dist/connector-callback.d.ts

@@ -0,0 +1,92 @@
+import { TiDBLinkError } from "./errors.js";
+import type { FetchFunction } from "./http.js";
+export declare const CONNECTOR_CALLBACK_ISSUER = "tidb-link/connector-callback/v1";
+export declare const CONNECTOR_CALLBACK_AUDIENCE = "tidb-link/connector";
+/** The `params._meta` key of the Call Context on every Connector `tools/call`. */
+export declare const CONNECTOR_CALL_CONTEXT_KEY = "tidb-link/context";
+/** A public Ed25519 key that signs Connector callback tokens. */
+export interface ConnectorVerificationKey {
+    kty: "OKP";
+    crv: "Ed25519";
+    x: string;
+    kid: string;
+    alg: "EdDSA";
+    use: "sig";
+}
+/** The verified claims of a Connector callback token. */
+export interface ConnectorCallbackClaims {
+    iss: typeof CONNECTOR_CALLBACK_ISSUER;
+    aud: typeof CONNECTOR_CALLBACK_AUDIENCE;
+    organizationId: string;
+    connectorId: string;
+    iat: number;
+    exp: number;
+}
+/**
+ * Who a Connector tool call is for, written by the platform from the
+ * Session's persisted owner. Model arguments cannot override it.
+ */
+export interface ConnectorCallContext {
+    /** Globally unique; deduplicate side effects by it. */
+    callId: string;
+    sessionId: string;
+    organizationId: string;
+    /** The Session owner's End User ID. Map it to your own account. */
+    userId: string;
+    /** When the platform stops waiting. Abandon the work after it. */
+    deadline: string;
+    /** Always 1: the platform never retries a call. */
+    attempt: 1;
+}
+/** A Connector callback was refused: bad signature, wrong scope or expired. */
+export declare class ConnectorAuthError extends TiDBLinkError {
+}
+export interface ConnectorKeySetOptions {
+    /** Your trusted TiDB Link deployment, for example `https://api.example.com`. */
+    baseUrl: string;
+    fetch?: FetchFunction;
+    /** How long fetched keys are reused. Default 10 minutes. */
+    maxAgeMs?: number;
+    /** Minimum time between refreshes for an unknown key ID. Default 30 seconds. */
+    minRefreshIntervalMs?: number;
+}
+/**
+ * Caches the deployment's public verification keys from
+ * `GET /api/v1/connectors/jwks`. Fetch keys only from your trusted deployment
+ * URL, never from a URL a token names.
+ */
+export declare class ConnectorKeySet {
+    #private;
+    constructor(options: ConnectorKeySetOptions);
+    /** The key for `kid`, refreshing the cache when it is stale or the key is new. */
+    key(kid: string): Promise<CryptoKey | undefined>;
+    /** Fetch the keys now. Concurrent callers share one request. */
+    refresh(): Promise<void>;
+}
+export interface VerifyConnectorCallbackOptions {
+    keys: ConnectorKeySet;
+    /** Your Organization; tokens for another are refused. */
+    organizationId: string;
+    /** This Connector; tokens for another are refused. */
+    connectorId: string;
+    /** Allowed clock difference with the platform. Default 5 seconds. */
+    clockToleranceSec?: number;
+    /** Override the current time, in milliseconds since the epoch. */
+    now?: number;
+}
+/**
+ * Verify the `Authorization` header of a request the platform sends to your
+ * HTTP Connector (initialization, tool discovery and tool calls). Returns the
+ * claims, or throws ConnectorAuthError. A token may be reused within its
+ * scope until it expires, so verification needs no per-request state.
+ */
+export declare function verifyConnectorCallback(authorization: string | null | undefined, options: VerifyConnectorCallbackOptions): Promise<ConnectorCallbackClaims>;
+/**
+ * Read the Call Context from a `tools/call` request's `params._meta`. Throws
+ * ConnectorAuthError when it is missing, malformed or for another
+ * Organization. Initialization and tool discovery carry no Call Context.
+ */
+export declare function readConnectorCallContext(meta: unknown, options: {
+    organizationId: string;
+}): ConnectorCallContext;
+//# sourceMappingURL=connector-callback.d.ts.map

package/dist/connector-callback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connector-callback.d.ts","sourceRoot":"","sources":["../src/connector-callback.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAE/C,eAAO,MAAM,yBAAyB,oCAAoC,CAAC;AAC3E,eAAO,MAAM,2BAA2B,wBAAwB,CAAC;AACjE,kFAAkF;AAClF,eAAO,MAAM,0BAA0B,sBAAsB,CAAC;AAE9D,iEAAiE;AACjE,MAAM,WAAW,wBAAwB;IACvC,GAAG,EAAE,KAAK,CAAC;IACX,GAAG,EAAE,SAAS,CAAC;IACf,CAAC,EAAE,MAAM,CAAC;IACV,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,OAAO,CAAC;IACb,GAAG,EAAE,KAAK,CAAC;CACZ;AAED,yDAAyD;AACzD,MAAM,WAAW,uBAAuB;IACtC,GAAG,EAAE,OAAO,yBAAyB,CAAC;IACtC,GAAG,EAAE,OAAO,2BAA2B,CAAC;IACxC,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,uDAAuD;IACvD,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,mEAAmE;IACnE,MAAM,EAAE,MAAM,CAAC;IACf,kEAAkE;IAClE,QAAQ,EAAE,MAAM,CAAC;IACjB,mDAAmD;IACnD,OAAO,EAAE,CAAC,CAAC;CACZ;AAED,+EAA+E;AAC/E,qBAAa,kBAAmB,SAAQ,aAAa;CAAG;AAExD,MAAM,WAAW,sBAAsB;IACrC,gFAAgF;IAChF,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gFAAgF;IAChF,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED;;;;GAIG;AACH,qBAAa,eAAe;;gBASd,OAAO,EAAE,sBAAsB;IAU3C,kFAAkF;IAC5E,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC;IAUtD,gEAAgE;IAChE,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAmDzB;AAED,MAAM,WAAW,8BAA8B;IAC7C,IAAI,EAAE,eAAe,CAAC;IACtB,yDAAyD;IACzD,cAAc,EAAE,MAAM,CAAC;IACvB,sDAAsD;IACtD,WAAW,EAAE,MAAM,CAAC;IACpB,qEAAqE;IACrE,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,kEAAkE;IAClE,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAaD;;;;;GAKG;AACH,wBAAsB,uBAAuB,CAC3C,aAAa,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACxC,OAAO,EAAE,8BAA8B,GACtC,OAAO,CAAC,uBAAuB,CAAC,CAuDlC;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,OAAO,EACb,OAAO,EAAE;IAAE,cAAc,EAAE,MAAM,CAAA;CAAE,GAClC,oBAAoB,CAkBtB"}

package/dist/connector-callback.js

@@ -0,0 +1,155 @@
+import { TiDBLinkError } from "./errors.js";
+export const CONNECTOR_CALLBACK_ISSUER = "tidb-link/connector-callback/v1";
+export const CONNECTOR_CALLBACK_AUDIENCE = "tidb-link/connector";
+/** The `params._meta` key of the Call Context on every Connector `tools/call`. */
+export const CONNECTOR_CALL_CONTEXT_KEY = "tidb-link/context";
+/** A Connector callback was refused: bad signature, wrong scope or expired. */
+export class ConnectorAuthError extends TiDBLinkError {
+}
+/**
+ * Caches the deployment's public verification keys from
+ * `GET /api/v1/connectors/jwks`. Fetch keys only from your trusted deployment
+ * URL, never from a URL a token names.
+ */
+export class ConnectorKeySet {
+    #url;
+    #fetch;
+    #maxAgeMs;
+    #minRefreshIntervalMs;
+    #keys = new Map();
+    #fetchedAt = -Infinity;
+    #loading;
+    constructor(options) {
+        const base = new URL(options.baseUrl);
+        if (base.protocol !== "https:" && base.protocol !== "http:")
+            throw new TypeError("baseUrl must be an HTTP(S) URL");
+        this.#url = new URL("/api/v1/connectors/jwks", base);
+        this.#fetch = options.fetch ?? ((url, init) => fetch(url, init));
+        this.#maxAgeMs = options.maxAgeMs ?? 600_000;
+        this.#minRefreshIntervalMs = options.minRefreshIntervalMs ?? 30_000;
+    }
+    /** The key for `kid`, refreshing the cache when it is stale or the key is new. */
+    async key(kid) {
+        const age = Date.now() - this.#fetchedAt;
+        if (age > this.#maxAgeMs ||
+            (!this.#keys.has(kid) && age > this.#minRefreshIntervalMs))
+            await this.refresh();
+        return this.#keys.get(kid);
+    }
+    /** Fetch the keys now. Concurrent callers share one request. */
+    refresh() {
+        this.#loading ??= this.#load().finally(() => {
+            this.#loading = undefined;
+        });
+        return this.#loading;
+    }
+    async #load() {
+        let response;
+        try {
+            response = await this.#fetch(this.#url, {
+                headers: { accept: "application/json" },
+                redirect: "error",
+            });
+        }
+        catch (cause) {
+            throw new TiDBLinkError("Connector verification keys are unreachable", { cause });
+        }
+        if (!response.ok) {
+            await response.body?.cancel();
+            throw new TiDBLinkError(`Connector verification keys are unavailable (status ${response.status})`);
+        }
+        const body = (await response.json());
+        if (!Array.isArray(body?.keys))
+            throw new TiDBLinkError("Connector verification keys are malformed");
+        const keys = new Map();
+        for (const key of body.keys) {
+            if (key?.kty !== "OKP" ||
+                key.crv !== "Ed25519" ||
+                key.alg !== "EdDSA" ||
+                key.use !== "sig" ||
+                typeof key.kid !== "string" ||
+                typeof key.x !== "string")
+                continue;
+            keys.set(key.kid, await crypto.subtle.importKey("jwk", { kty: "OKP", crv: "Ed25519", x: key.x }, { name: "Ed25519" }, false, ["verify"]));
+        }
+        this.#keys = keys;
+        this.#fetchedAt = Date.now();
+    }
+}
+const base64UrlBytes = (part) => Uint8Array.from(atob(part.replace(/-/g, "+").replace(/_/g, "/")), (c) => c.charCodeAt(0));
+const decodeJson = (part) => {
+    const value = JSON.parse(new TextDecoder().decode(base64UrlBytes(part)));
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        throw new Error("not an object");
+    return value;
+};
+/**
+ * Verify the `Authorization` header of a request the platform sends to your
+ * HTTP Connector (initialization, tool discovery and tool calls). Returns the
+ * claims, or throws ConnectorAuthError. A token may be reused within its
+ * scope until it expires, so verification needs no per-request state.
+ */
+export async function verifyConnectorCallback(authorization, options) {
+    const refuse = (reason) => {
+        throw new ConnectorAuthError(`Connector callback refused: ${reason}`);
+    };
+    const bearer = /^Bearer ([A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+)$/i.exec(authorization ?? "");
+    if (!bearer)
+        return refuse("missing or malformed bearer token");
+    const [headerPart, payloadPart, signaturePart] = bearer[1].split(".");
+    let header;
+    let claims;
+    try {
+        header = decodeJson(headerPart);
+        claims = decodeJson(payloadPart);
+    }
+    catch {
+        return refuse("undecodable token");
+    }
+    if (header.alg !== "EdDSA" || typeof header.kid !== "string")
+        return refuse("unsupported algorithm");
+    const key = await options.keys.key(header.kid);
+    if (!key)
+        return refuse("unknown signing key");
+    const valid = await crypto.subtle.verify({ name: "Ed25519" }, key, base64UrlBytes(signaturePart), new TextEncoder().encode(`${headerPart}.${payloadPart}`));
+    if (!valid)
+        return refuse("invalid signature");
+    const now = (options.now ?? Date.now()) / 1000;
+    const tolerance = options.clockToleranceSec ?? 5;
+    const { iat, exp } = claims;
+    if (claims.iss !== CONNECTOR_CALLBACK_ISSUER ||
+        claims.aud !== CONNECTOR_CALLBACK_AUDIENCE)
+        return refuse("wrong issuer or audience");
+    if (claims.organizationId !== options.organizationId ||
+        claims.connectorId !== options.connectorId)
+        return refuse("issued for another Organization or Connector");
+    if (!Number.isSafeInteger(iat) ||
+        !Number.isSafeInteger(exp) ||
+        exp <= iat ||
+        exp - iat > 60 ||
+        iat > now + tolerance ||
+        exp <= now - tolerance)
+        return refuse("expired or not yet valid");
+    return claims;
+}
+/**
+ * Read the Call Context from a `tools/call` request's `params._meta`. Throws
+ * ConnectorAuthError when it is missing, malformed or for another
+ * Organization. Initialization and tool discovery carry no Call Context.
+ */
+export function readConnectorCallContext(meta, options) {
+    const context = meta?.[CONNECTOR_CALL_CONTEXT_KEY];
+    const text = (value) => typeof value === "string" && value.length > 0;
+    if (!context ||
+        !text(context.callId) ||
+        !text(context.sessionId) ||
+        !text(context.userId) ||
+        !text(context.deadline) ||
+        !Number.isFinite(Date.parse(context.deadline)) ||
+        context.attempt !== 1)
+        throw new ConnectorAuthError("Connector call has no valid Call Context");
+    if (context.organizationId !== options.organizationId)
+        throw new ConnectorAuthError("Connector call is for another Organization");
+    return context;
+}
+//# sourceMappingURL=connector-callback.js.map

package/dist/connector-callback.js.map

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

package/dist/connectors.d.ts

@@ -0,0 +1,66 @@
+import { HttpClient } from "./http.js";
+import type { RequestOptions } from "./organization.js";
+export type ConnectorTransport = "streamable_http" | "tunnel";
+/** An Organization-owned MCP tool server that Agents can call. */
+export interface Connector {
+    connectorId: string;
+    organizationId: string;
+    displayName: string;
+    /** The HTTPS MCP endpoint of a `streamable_http` Connector. */
+    endpointUrl: string;
+    endpointVersion: number;
+    transport: ConnectorTransport;
+    status: "inactive" | "active";
+    /** Pass this as `expectedConnectorVersion` to change the registration. */
+    connectorVersion: number;
+    createdAt: string;
+    updatedAt: string;
+    /** What activation discovered at the endpoint. */
+    observation?: {
+        era: "modern" | "legacy";
+        protocolVersion: string;
+        endpointVersion: number;
+        probedAt: string;
+        expiresAt: string;
+    };
+}
+export interface RegisterConnectorInput extends RequestOptions {
+    /** Unique within the Organization. */
+    displayName: string;
+    /** Defaults to `streamable_http`. */
+    transport?: ConnectorTransport;
+    /** Required for `streamable_http`: an HTTPS URL without credentials. */
+    endpointUrl?: string;
+}
+export interface UpdateConnectorInput {
+    displayName?: string;
+    endpointUrl?: string;
+}
+export interface ConnectorVersionOptions extends RequestOptions {
+    /** The `connectorVersion` you read. A changed registration is refused with ConflictError. */
+    expectedConnectorVersion: number;
+}
+/**
+ * Organization Connector registrations. Register a Connector, then activate
+ * it: activation connects to the endpoint and discovers its tools. Edit only
+ * an inactive Connector.
+ */
+export declare class Connectors {
+    #private;
+    constructor(http: HttpClient);
+    list(options?: RequestOptions): Promise<Connector[]>;
+    get(connectorId: string, options?: RequestOptions): Promise<Connector>;
+    /**
+     * Register an inactive Connector. Registration is not retried; after an
+     * OutcomeUnknownError, list the Connectors and match the display name, which
+     * is unique in the Organization.
+     */
+    register(input: RegisterConnectorInput): Promise<Connector>;
+    /** Edit an inactive Connector. */
+    update(connectorId: string, input: UpdateConnectorInput, options: ConnectorVersionOptions): Promise<Connector>;
+    /** Discover the endpoint's tools and activate the Connector. */
+    activate(connectorId: string, options: ConnectorVersionOptions): Promise<Connector>;
+    /** Stop new calls to the Connector. */
+    deactivate(connectorId: string, options: ConnectorVersionOptions): Promise<Connector>;
+}
+//# sourceMappingURL=connectors.d.ts.map

package/dist/connectors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connectors.d.ts","sourceRoot":"","sources":["../src/connectors.ts"],"names":[],"mappings":"AACA,OAAO,EACL,UAAU,EAIX,MAAM,WAAW,CAAC;AACnB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAExD,MAAM,MAAM,kBAAkB,GAAG,iBAAiB,GAAG,QAAQ,CAAC;AAE9D,kEAAkE;AAClE,MAAM,WAAW,SAAS;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,+DAA+D;IAC/D,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;IACxB,SAAS,EAAE,kBAAkB,CAAC;IAC9B,MAAM,EAAE,UAAU,GAAG,QAAQ,CAAC;IAC9B,0EAA0E;IAC1E,gBAAgB,EAAE,MAAM,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,kDAAkD;IAClD,WAAW,CAAC,EAAE;QACZ,GAAG,EAAE,QAAQ,GAAG,QAAQ,CAAC;QACzB,eAAe,EAAE,MAAM,CAAC;QACxB,eAAe,EAAE,MAAM,CAAC;QACxB,QAAQ,EAAE,MAAM,CAAC;QACjB,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;CACH;AAED,MAAM,WAAW,sBAAuB,SAAQ,cAAc;IAC5D,sCAAsC;IACtC,WAAW,EAAE,MAAM,CAAC;IACpB,qCAAqC;IACrC,SAAS,CAAC,EAAE,kBAAkB,CAAC;IAC/B,wEAAwE;IACxE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,oBAAoB;IACnC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,uBAAwB,SAAQ,cAAc;IAC7D,6FAA6F;IAC7F,wBAAwB,EAAE,MAAM,CAAC;CAClC;AA0BD;;;;GAIG;AACH,qBAAa,UAAU;;gBAGT,IAAI,EAAE,UAAU;IAItB,IAAI,CAAC,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAQ1D,GAAG,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,SAAS,CAAC;IAItE;;;;OAIG;IACG,QAAQ,CAAC,KAAK,EAAE,sBAAsB,GAAG,OAAO,CAAC,SAAS,CAAC;IAkBjE,kCAAkC;IAC5B,MAAM,CACV,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,oBAAoB,EAC3B,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,SAAS,CAAC;IAarB,gEAAgE;IAChE,QAAQ,CACN,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,SAAS,CAAC;IAIrB,uCAAuC;IACvC,UAAU,CACR,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,SAAS,CAAC;CAoBtB"}