@hydradb/mcp 1.2.2 → 1.4.0

package/dist/hydra/transport.js

@@ -0,0 +1,114 @@
+/**
+ * The hand-rolled HTTP path for endpoints the SDK does not expose.
+ *
+ * CONTRACT §2 rule 7: a call that bypasses the SDK is still the wrapper — same
+ * `API-Version: 2` header, same envelope-by-shape unwrap, same translated error
+ * type — so a caller cannot tell which methods went through the SDK. This used
+ * to live inside GraphResource, where BYOG was the only such surface. The
+ * connected-subgraph read (PRO-1848) is the second, and a second copy of the
+ * retry/abort/translate logic is exactly what the rule exists to prevent, so
+ * it moved here and both resources call it.
+ *
+ * `fetchFn` is injectable for tests only; production never sets it.
+ */
+import { unwrap } from "./envelope.js";
+import { HydraWrapperError, responseError, translateError } from "./errors.js";
+/** The SDK's own default, restated so this file does not depend on importing it. */
+export const DEFAULT_BASE_URL = "https://api.hydradb.com";
+export function newRawTransport(config, defaults) {
+    return {
+        token: config.token,
+        // Trailing slashes would produce `//byog/query`, which some proxies treat
+        // as a different path.
+        baseUrl: (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, ""),
+        timeoutMs: (config.timeoutSeconds ?? defaults.timeoutSeconds) * 1000,
+        maxRetries: config.maxRetries ?? defaults.maxRetries,
+        ...(config.fetchFn ? { fetchFn: config.fetchFn } : {}),
+    };
+}
+function isRetryable(status) {
+    return status === 429 || (status >= 500 && status <= 599);
+}
+/** Send with bounded retries on 429/5xx; the caller's abort ends retrying. */
+export async function sendRaw(t, path, method, body, opts) {
+    let lastError;
+    for (let attempt = 0; attempt <= t.maxRetries; attempt++) {
+        try {
+            return await attemptRaw(t, path, method, body, opts);
+        }
+        catch (err) {
+            lastError = err;
+            const status = err instanceof HydraWrapperError ? err.status : undefined;
+            // A caller who cancelled is not waiting for a retry.
+            if (opts?.signal?.aborted)
+                throw err;
+            if (attempt === t.maxRetries)
+                break;
+            if (status != null && !isRetryable(status))
+                break;
+            // Exponential backoff. Bounded so a 429 on the last attempt does not
+            // hold the MCP host's tool timeout open for its own sake.
+            const delay = Math.min(250 * 2 ** attempt, 2000);
+            await new Promise((resolve) => setTimeout(resolve, delay));
+        }
+    }
+    throw lastError;
+}
+async function attemptRaw(t, path, method, body, opts) {
+    // The host's cancellation and our own deadline both have to be able to
+    // abort the request, and `AbortSignal.any` is not available on every Node
+    // 18 this package supports — so they are combined by hand.
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), t.timeoutMs);
+    const onAbort = () => controller.abort();
+    opts?.signal?.addEventListener("abort", onAbort, { once: true });
+    const doFetch = t.fetchFn ?? fetch;
+    try {
+        const response = await doFetch(`${t.baseUrl}${path}`, {
+            method,
+            headers: {
+                Authorization: `Bearer ${t.token}`,
+                "Content-Type": "application/json",
+                // CONTRACT §2 rule 6. The SDK sends this on every call; a
+                // hand-rolled path that omitted it would silently get v1
+                // behaviour from the same endpoints.
+                "API-Version": "2",
+            },
+            ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+            signal: controller.signal,
+        });
+        const text = await response.text();
+        let parsed;
+        try {
+            parsed = text === "" ? null : JSON.parse(text);
+        }
+        catch {
+            parsed = text;
+        }
+        if (!response.ok) {
+            // Hand the parsed envelope to the shared formatter so a raw-path
+            // failure reads exactly like an SDK one, error code and request id
+            // and all.
+            throw responseError(path, response.status, parsed);
+        }
+        return unwrap(parsed);
+    }
+    catch (err) {
+        if (err instanceof HydraWrapperError)
+            throw err;
+        // Distinguish our own deadline from the caller's cancellation: they
+        // need different actions, and "aborted" alone says neither.
+        if (err instanceof Error && err.name === "AbortError") {
+            if (opts?.signal?.aborted) {
+                throw new HydraWrapperError(`Hydra DB ${path} → ERR: request cancelled by the caller`, path, { cause: err });
+            }
+            throw new HydraWrapperError(`Hydra DB ${path} → ERR: request timed out after ${t.timeoutMs / 1000}s`, path, { cause: err });
+        }
+        throw translateError(path, err);
+    }
+    finally {
+        clearTimeout(timer);
+        opts?.signal?.removeEventListener("abort", onAbort);
+    }
+}
+//# sourceMappingURL=transport.js.map

package/dist/hydra/transport.js.map

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

package/dist/oauth.d.ts

@@ -0,0 +1,109 @@
+/**
+ * The OAuth 2.1 RESOURCE-SERVER half of MCP authorization (PRO-1790).
+ *
+ * This server never issues tokens and never talks to the user. It does three
+ * things the MCP authorization spec asks of a protected resource:
+ *
+ *   1. Advertise where its authorization server is, via an RFC 9728 Protected
+ *      Resource Metadata document at `/.well-known/oauth-protected-resource`,
+ *      and point at that document from every 401 (`WWW-Authenticate`).
+ *   2. Recognise an access token the authorization server issued and turn it
+ *      into the same {@link RequestCredentials} an API key would produce, by
+ *      asking the authorization server what the token stands for (RFC 7662
+ *      introspection). The answer carries the API key the dashboard minted on
+ *      the user's Approve click, so the tool layer keeps calling Hydra DB
+ *      exactly as it does for a key: nothing downstream knows OAuth exists.
+ *   3. Refuse a token that was not issued for THIS server (audience binding,
+ *      RFC 8707), so a token minted for another resource cannot be replayed
+ *      here.
+ *
+ * All of it is additive and switched on only by configuration: with no
+ * `HYDRADB_OAUTH_ISSUER` the server behaves exactly as before.
+ */
+/** Access tokens the dashboard issues carry this prefix; keys carry `sk_`. */
+export declare const ACCESS_TOKEN_PREFIX = "hmat_";
+/** The one scope this resource defines. Granularity is PRO-1789's problem. */
+export declare const SCOPE = "hydradb";
+export interface OAuthConfig {
+    /** The authorization server, e.g. `https://app.hydradb.com`. No trailing slash. */
+    issuer: string;
+    /** This server's canonical URL as clients know it, e.g. `https://mcp.hydradb.com`. */
+    resource: string;
+    /** Shared secret presented to the issuer's introspection endpoint. */
+    introspectionSecret: string;
+    /** Overrides for tests. */
+    fetchFn?: typeof fetch;
+    now?: () => number;
+}
+/** Everything an introspected token stands for. Mirrors the dashboard's response. */
+export interface IntrospectedToken {
+    apiKey: string;
+    database?: string;
+    collection?: string;
+    /**
+     * Databases a per-call `database` argument may name. Absent means any (the
+     * user chose to let the app switch when asked); present means the user
+     * confined the app to exactly these on the consent screen, and this server
+     * is where that promise is kept, because the API key behind the token is
+     * org-wide and the key never leaves this process.
+     */
+    allowedDatabases?: string[];
+    /**
+     * Collections a per-call `collection` argument may name, on the same terms.
+     * Confinement has to cover both or it means nothing: a caller pinned to one
+     * database could still step sideways into a collection the consent screen
+     * never showed and, through `drop_collection`, delete it.
+     */
+    allowedCollections?: string[];
+    userId?: string;
+    clientId?: string;
+    clientName?: string;
+    /** Epoch seconds. */
+    expiresAt: number;
+}
+export type IntrospectionResult = {
+    ok: true;
+    token: IntrospectedToken;
+} | {
+    ok: false;
+    reason: "invalid_token" | "wrong_audience" | "unavailable";
+    detail?: string;
+};
+/**
+ * Read the OAuth configuration, or `null` when the feature is off.
+ *
+ * All three values are needed: an issuer says where to send clients, a
+ * resource says which audience to accept, and the secret is what makes the
+ * introspection answer trustworthy. Half a configuration is treated as none,
+ * with a startup warning, rather than as a server that advertises an
+ * authorization flow it cannot complete.
+ */
+export declare function resolveOAuthConfig(env?: Record<string, string | undefined>, warn?: (message: string) => void): OAuthConfig | null;
+/** Where the Protected Resource Metadata document lives for this server. */
+export declare function metadataUrl(config: OAuthConfig, mcpPath?: string): string;
+/** The RFC 9728 document itself. */
+export declare function protectedResourceMetadata(config: OAuthConfig): Record<string, unknown>;
+/**
+ * The `WWW-Authenticate` value for a 401.
+ *
+ * `resource_metadata` is how a client that arrived with nothing learns where
+ * to log in (the MCP spec's first discovery step), and `scope` tells it what
+ * to ask for. `error` is included only when a token was PRESENTED and refused,
+ * so an anonymous first contact reads as "authenticate" rather than "your
+ * token is bad".
+ */
+export declare function wwwAuthenticate(config: OAuthConfig, error?: "invalid_token" | "insufficient_scope", description?: string): string;
+/** Whether a bearer value is one of OUR access tokens rather than an API key. */
+export declare function isAccessToken(bearer: string | undefined): bearer is string;
+/** Test-only. */
+export declare function __resetIntrospectionCache(): void;
+/**
+ * Ask the issuer what a token stands for.
+ *
+ * The response shape is the contract in PRO-1790: `active`, `aud`, `exp`,
+ * `api_key`, `database`, `collection`, `sub`, `client_id`, `client_name`.
+ * Audience is checked HERE, not trusted from the issuer's say-so: the issuer
+ * may legitimately serve several resources, and this server must only honour
+ * tokens minted for itself.
+ */
+export declare function introspect(config: OAuthConfig, token: string): Promise<IntrospectionResult>;

package/dist/oauth.js

@@ -0,0 +1,228 @@
+/**
+ * The OAuth 2.1 RESOURCE-SERVER half of MCP authorization (PRO-1790).
+ *
+ * This server never issues tokens and never talks to the user. It does three
+ * things the MCP authorization spec asks of a protected resource:
+ *
+ *   1. Advertise where its authorization server is, via an RFC 9728 Protected
+ *      Resource Metadata document at `/.well-known/oauth-protected-resource`,
+ *      and point at that document from every 401 (`WWW-Authenticate`).
+ *   2. Recognise an access token the authorization server issued and turn it
+ *      into the same {@link RequestCredentials} an API key would produce, by
+ *      asking the authorization server what the token stands for (RFC 7662
+ *      introspection). The answer carries the API key the dashboard minted on
+ *      the user's Approve click, so the tool layer keeps calling Hydra DB
+ *      exactly as it does for a key: nothing downstream knows OAuth exists.
+ *   3. Refuse a token that was not issued for THIS server (audience binding,
+ *      RFC 8707), so a token minted for another resource cannot be replayed
+ *      here.
+ *
+ * All of it is additive and switched on only by configuration: with no
+ * `HYDRADB_OAUTH_ISSUER` the server behaves exactly as before.
+ */
+import { createHash } from "node:crypto";
+import { logger } from "./logger.js";
+/** Access tokens the dashboard issues carry this prefix; keys carry `sk_`. */
+export const ACCESS_TOKEN_PREFIX = "hmat_";
+/** The one scope this resource defines. Granularity is PRO-1789's problem. */
+export const SCOPE = "hydradb";
+function stripSlash(url) {
+    return url.replace(/\/+$/, "");
+}
+/**
+ * Read the OAuth configuration, or `null` when the feature is off.
+ *
+ * All three values are needed: an issuer says where to send clients, a
+ * resource says which audience to accept, and the secret is what makes the
+ * introspection answer trustworthy. Half a configuration is treated as none,
+ * with a startup warning, rather than as a server that advertises an
+ * authorization flow it cannot complete.
+ */
+export function resolveOAuthConfig(env = process.env, warn = (m) => console.error(`[hydradb-mcp] ${m}`)) {
+    const issuer = env.HYDRADB_OAUTH_ISSUER?.trim();
+    const resource = env.HYDRADB_MCP_PUBLIC_URL?.trim();
+    const introspectionSecret = env.HYDRADB_OAUTH_INTROSPECTION_SECRET?.trim();
+    if (!issuer && !resource && !introspectionSecret)
+        return null;
+    const missing = [
+        !issuer && "HYDRADB_OAUTH_ISSUER",
+        !resource && "HYDRADB_MCP_PUBLIC_URL",
+        !introspectionSecret && "HYDRADB_OAUTH_INTROSPECTION_SECRET",
+    ].filter(Boolean);
+    if (missing.length > 0) {
+        warn(`WARNING: OAuth is partially configured (missing ${missing.join(", ")}); ` +
+            "it stays OFF until all three are set.");
+        return null;
+    }
+    for (const [name, value] of [
+        ["HYDRADB_OAUTH_ISSUER", issuer],
+        ["HYDRADB_MCP_PUBLIC_URL", resource],
+    ]) {
+        if (!/^https?:\/\//i.test(value)) {
+            warn(`WARNING: ${name} must be an absolute http(s) URL; OAuth stays OFF.`);
+            return null;
+        }
+    }
+    return {
+        issuer: stripSlash(issuer),
+        resource: stripSlash(resource),
+        introspectionSecret: introspectionSecret,
+    };
+}
+/** Where the Protected Resource Metadata document lives for this server. */
+export function metadataUrl(config, mcpPath = "") {
+    // RFC 9728 puts the well-known segment BEFORE the resource's path, so a
+    // server at /mcp advertises at /.well-known/oauth-protected-resource/mcp.
+    return `${config.resource}/.well-known/oauth-protected-resource${mcpPath}`;
+}
+/** The RFC 9728 document itself. */
+export function protectedResourceMetadata(config) {
+    return {
+        resource: config.resource,
+        authorization_servers: [config.issuer],
+        scopes_supported: [SCOPE],
+        bearer_methods_supported: ["header"],
+        resource_name: "Hydra DB MCP",
+        resource_documentation: "https://docs.hydradb.com/mcp",
+    };
+}
+/**
+ * The `WWW-Authenticate` value for a 401.
+ *
+ * `resource_metadata` is how a client that arrived with nothing learns where
+ * to log in (the MCP spec's first discovery step), and `scope` tells it what
+ * to ask for. `error` is included only when a token was PRESENTED and refused,
+ * so an anonymous first contact reads as "authenticate" rather than "your
+ * token is bad".
+ */
+export function wwwAuthenticate(config, error, description) {
+    const parts = [`Bearer realm="Hydra DB MCP"`];
+    if (error)
+        parts.push(`error="${error}"`);
+    if (description)
+        parts.push(`error_description="${description.replace(/"/g, "'")}"`);
+    parts.push(`resource_metadata="${metadataUrl(config)}"`);
+    parts.push(`scope="${SCOPE}"`);
+    return parts.join(", ");
+}
+/** Whether a bearer value is one of OUR access tokens rather than an API key. */
+export function isAccessToken(bearer) {
+    return typeof bearer === "string" && bearer.startsWith(ACCESS_TOKEN_PREFIX);
+}
+// --- Introspection, with a bounded memo ---
+/**
+ * Introspection answers are memoised per token so the hosted server, which
+ * builds a client per request, does not ask the dashboard on every tool call.
+ * Only successes are cached, for the shorter of the token's own expiry and
+ * this ceiling. The ceiling IS the revocation lag: measured end to end, a
+ * disconnect or a refresh-token reuse detection reaches this server exactly
+ * one ceiling later. Thirty seconds keeps an agent's burst of tool calls at
+ * one hop while keeping that lag short enough that a revoked token cannot do
+ * much with it.
+ */
+const INTROSPECTION_CACHE_TTL_MS = 30000;
+const INTROSPECTION_CACHE_MAX = 5000;
+const INTROSPECTION_TIMEOUT_MS = 5000;
+const cache = new Map();
+/** Test-only. */
+export function __resetIntrospectionCache() {
+    cache.clear();
+}
+function cacheKey(token) {
+    // Never keep the raw token as a Map key: it would sit in memory in the
+    // clear for as long as the entry lives.
+    return createHash("sha256").update(token).digest("hex");
+}
+/**
+ * Ask the issuer what a token stands for.
+ *
+ * The response shape is the contract in PRO-1790: `active`, `aud`, `exp`,
+ * `api_key`, `database`, `collection`, `sub`, `client_id`, `client_name`.
+ * Audience is checked HERE, not trusted from the issuer's say-so: the issuer
+ * may legitimately serve several resources, and this server must only honour
+ * tokens minted for itself.
+ */
+export async function introspect(config, token) {
+    const now = config.now ?? Date.now;
+    const key = cacheKey(token);
+    const hit = cache.get(key);
+    if (hit && hit.expires > now())
+        return { ok: true, token: hit.token };
+    if (hit)
+        cache.delete(key);
+    const fetchFn = config.fetchFn ?? fetch;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), INTROSPECTION_TIMEOUT_MS);
+    let body;
+    try {
+        const res = await fetchFn(`${config.issuer}/api/oauth/introspect`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/x-www-form-urlencoded",
+                Accept: "application/json",
+                Authorization: `Bearer ${config.introspectionSecret}`,
+            },
+            body: new URLSearchParams({ token }).toString(),
+            signal: controller.signal,
+        });
+        if (res.status === 401 || res.status === 403) {
+            // Our secret was refused. That is an operator problem, not the
+            // caller's, and it must not read as "your token is invalid".
+            logger.error("introspection refused: HYDRADB_OAUTH_INTROSPECTION_SECRET is not accepted by the issuer");
+            return { ok: false, reason: "unavailable", detail: "introspection refused" };
+        }
+        if (!res.ok) {
+            return { ok: false, reason: "unavailable", detail: `introspection HTTP ${res.status}` };
+        }
+        body = (await res.json());
+    }
+    catch (err) {
+        return {
+            ok: false,
+            reason: "unavailable",
+            detail: err instanceof Error ? err.message : String(err),
+        };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    if (body.active !== true)
+        return { ok: false, reason: "invalid_token" };
+    const aud = body.aud;
+    const audiences = Array.isArray(aud) ? aud : typeof aud === "string" ? [aud] : [];
+    if (!audiences.some((a) => typeof a === "string" && stripSlash(a) === config.resource)) {
+        return { ok: false, reason: "wrong_audience" };
+    }
+    const apiKey = typeof body.api_key === "string" ? body.api_key : "";
+    const exp = typeof body.exp === "number" ? body.exp : 0;
+    if (!apiKey || exp <= Math.floor(now() / 1000)) {
+        return { ok: false, reason: "invalid_token" };
+    }
+    const stringList = (v) => Array.isArray(v)
+        ? v.filter((d) => typeof d === "string" && d.length > 0)
+        : undefined;
+    const allowed = stringList(body.databases);
+    const allowedCols = stringList(body.collections);
+    const resolved = {
+        apiKey,
+        ...(allowed ? { allowedDatabases: allowed } : {}),
+        ...(allowedCols ? { allowedCollections: allowedCols } : {}),
+        database: typeof body.database === "string" && body.database ? body.database : undefined,
+        collection: typeof body.collection === "string" && body.collection ? body.collection : undefined,
+        userId: typeof body.sub === "string" ? body.sub : undefined,
+        clientId: typeof body.client_id === "string" ? body.client_id : undefined,
+        clientName: typeof body.client_name === "string" ? body.client_name : undefined,
+        expiresAt: exp,
+    };
+    if (cache.size >= INTROSPECTION_CACHE_MAX) {
+        const oldest = cache.keys().next().value;
+        if (oldest != null)
+            cache.delete(oldest);
+    }
+    cache.set(key, {
+        token: resolved,
+        expires: Math.min(now() + INTROSPECTION_CACHE_TTL_MS, exp * 1000),
+    });
+    return { ok: true, token: resolved };
+}
+//# sourceMappingURL=oauth.js.map

package/dist/oauth.js.map

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

package/dist/server.d.ts

@@ -19,12 +19,20 @@ export declare function inFlightCount(): number;
 export declare function legacyToolsEnabled(env?: NodeJS.ProcessEnv): boolean;
 /** Test-only: reset the once-per-process alias warning dedupe. */
 export declare function __resetAliasWarnings(): void;
+export interface ServerOptions {
+    /**
+     * Register the OAuth-connection tools (currently `hydradb_databases`).
+     * Set by the HTTP transport when the request authenticated with an OAuth
+     * token; never for API keys, so their tool list is unchanged.
+     */
+    oauthTools?: boolean;
+}
 export declare function createHydraDBServer(hydraOverride?: HydraDB, 
 /**
  * Graph scope/gating override, for tests and embedders. Without it the graph
  * config is read from the environment exactly as the rest of the config is.
  */
-graphOverride?: Partial<GraphConfig>): import("@modelcontextprotocol/sdk/server").Server<{
+graphOverride?: Partial<GraphConfig>, options?: ServerOptions): import("@modelcontextprotocol/sdk/server").Server<{
     method: string;
     params?: {
         [x: string]: unknown;