@vantageos/mcp-boilerplate 0.2.3 → 0.3.0

package/dist/upstream/clientCredentials.js

@@ -0,0 +1,283 @@
+/**
+ * Outbound OAuth 2 `client_credentials` token source (RFC 6749 §4.4), for a server derived from
+ * this boilerplate that reads a third-party upstream API. It is the client side only: the inbound
+ * authorization server in `src/oauth/` is unrelated and untouched.
+ *
+ * CREATE IT ONCE, AT MODULE SCOPE. The MCP server is rebuilt per request, so a token source built
+ * inside the factory or a tool handler would fetch a fresh token on every request and defeat the
+ * cache. Build it once per process and reuse it from every request:
+ *
+ * ```ts
+ * // src/upstream.ts — evaluated once per process
+ * import { clientCredentialsFromEnv, createClientCredentialsTokenSource } from "./upstream/clientCredentials.js";
+ *
+ * export const upstream = createClientCredentialsTokenSource(
+ *   clientCredentialsFromEnv({
+ *     clientIdVar: "UPSTREAM_CLIENT_ID",
+ *     clientSecretVar: "UPSTREAM_CLIENT_SECRET",
+ *     tokenUrlVar: "UPSTREAM_TOKEN_URL",
+ *     scopeVar: "UPSTREAM_SCOPE",
+ *   })
+ * );
+ *
+ * // in a tool handler, on any request
+ * const res = await upstream.fetchWithToken("https://api.upstream.example/v1/things");
+ * ```
+ *
+ * The variable names above are examples: the caller chooses them, nothing here hardcodes one.
+ *
+ * Behaviour:
+ * - The token is cached until `expires_in − refreshSkewSeconds` (default skew 60 s), measured from
+ *   the moment the token was REQUESTED, on the injectable `now()` clock.
+ * - Concurrent callers while a token is being fetched share ONE in-flight request (single-flight).
+ *   A failed fetch rejects every waiter and is never cached: the next call fetches again.
+ * - `fetchWithToken` attaches `Authorization: Bearer`; on a 401 it invalidates the token, fetches a
+ *   new one ONCE and retries ONCE. A second 401 is returned to the caller, never looped.
+ * - Every failure of the token endpoint is an `UpstreamTokenError` naming the HTTP status and the
+ *   OAuth `error` code. It never contains the client secret, the Basic header, an access token,
+ *   or the endpoint's `error_description` (free text an endpoint may fill with the request).
+ * - A response it cannot read is refused (fail closed); there is no fallback.
+ *
+ * Errors are operator-facing (configuration and upstream failures, logged server-side), so they
+ * stay in English like `src/oauth/` and `src/envKnobs.ts`; they never reach the MCP client as a
+ * localised tool message.
+ */
+import { rawKnob } from "../envKnobs.js";
+/** A failure of the upstream token endpoint. Carries no credential and no token. */
+export class UpstreamTokenError extends Error {
+    /** HTTP status of the token endpoint, when it answered. */
+    status;
+    /** The OAuth `error` code (RFC 6749 §5.2), when the endpoint sent a readable one. */
+    oauthError;
+    constructor(message, details = {}) {
+        super(message);
+        this.name = "UpstreamTokenError";
+        this.status = details.status;
+        this.oauthError = details.oauthError;
+    }
+}
+const DEFAULT_SKEW_SECONDS = 60;
+const DEFAULT_TIMEOUT_MS = 10_000;
+/**
+ * `expires_in` is RECOMMENDED, not required (RFC 6749 §5.1). When the endpoint omits it, the token
+ * is assumed to live 300 s: short enough that a token which really lives less is soon replaced (and
+ * a 401 in between is absorbed by the one-shot refetch), long enough not to hit the endpoint on
+ * every call. With the default 60 s skew it is refreshed after 240 s.
+ */
+const DEFAULT_EXPIRES_IN_SECONDS = 300;
+/** RFC 6749 §5.2 `error` charset (%x20-21 / %x23-5B / %x5D-7E), capped at 64 characters. */
+const OAUTH_ERROR_CODE = /^[\x20\x21\x23-\x5B\x5D-\x7E]{1,64}$/;
+const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]"]);
+/** application/x-www-form-urlencoded encoding of one value (RFC 6749 Appendix B). */
+function formEncode(value) {
+    return new URLSearchParams([["", value]]).toString().slice(1);
+}
+function validateTokenUrl(tokenUrl) {
+    let url;
+    try {
+        url = new URL(tokenUrl);
+    }
+    catch {
+        throw new Error("client_credentials: tokenUrl is not a valid URL (value not shown)");
+    }
+    const loopbackHttp = url.protocol === "http:" && LOOPBACK_HOSTS.has(url.hostname);
+    if (url.protocol !== "https:" && !loopbackHttp) {
+        throw new Error("client_credentials: tokenUrl must use https (http is accepted on loopback only) (value not shown)");
+    }
+}
+export function createClientCredentialsTokenSource(options) {
+    const { tokenUrl, clientId, clientSecret, scope, audience, authMethod = "client_secret_basic", refreshSkewSeconds = DEFAULT_SKEW_SECONDS, timeoutMs = DEFAULT_TIMEOUT_MS, fetchImpl = fetch, now = Date.now, } = options;
+    validateTokenUrl(tokenUrl);
+    if (!clientId)
+        throw new Error("client_credentials: clientId is empty");
+    if (!clientSecret)
+        throw new Error("client_credentials: clientSecret is empty");
+    if (authMethod !== "client_secret_basic" && authMethod !== "client_secret_post") {
+        throw new Error('client_credentials: authMethod must be "client_secret_basic" or "client_secret_post"');
+    }
+    if (!Number.isFinite(refreshSkewSeconds) || refreshSkewSeconds < 0) {
+        throw new Error("client_credentials: refreshSkewSeconds must be a non-negative number");
+    }
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+        throw new Error("client_credentials: timeoutMs must be a positive number");
+    }
+    // Each part is form-encoded first (RFC 6749 §2.3.1), so the input to btoa is ASCII.
+    const basicCredentials = btoa(`${formEncode(clientId)}:${formEncode(clientSecret)}`);
+    const basicHeader = `Basic ${basicCredentials}`;
+    /** The endpoint's `error` code, or undefined when unreadable or echoing a credential. */
+    const readOauthError = (body) => {
+        if (!body || typeof body !== "object" || Array.isArray(body))
+            return undefined;
+        const code = body.error;
+        if (typeof code !== "string" || !OAUTH_ERROR_CODE.test(code))
+            return undefined;
+        if (code.includes(clientSecret) || code.includes(formEncode(clientSecret)))
+            return undefined;
+        if (code.includes(basicCredentials))
+            return undefined;
+        return code;
+    };
+    const requestToken = async () => {
+        const requestedAt = now();
+        const form = new URLSearchParams({ grant_type: "client_credentials" });
+        if (scope)
+            form.set("scope", scope);
+        if (audience)
+            form.set("audience", audience);
+        const headers = {
+            "Content-Type": "application/x-www-form-urlencoded",
+            Accept: "application/json",
+        };
+        if (authMethod === "client_secret_basic") {
+            headers.Authorization = basicHeader;
+        }
+        else {
+            form.set("client_id", clientId);
+            form.set("client_secret", clientSecret);
+        }
+        let res;
+        try {
+            res = await fetchImpl(tokenUrl, {
+                method: "POST",
+                headers,
+                body: form.toString(),
+                // A redirect is refused, never followed: a 307/308 would re-send this body, which carries
+                // the client secret under client_secret_post, to whatever host the Location names.
+                redirect: "error",
+                signal: AbortSignal.timeout(timeoutMs),
+            });
+        }
+        catch (err) {
+            // Only the error's NAME travels: a transport message is not ours to vouch for. A refused
+            // redirect lands here too (fetch rejects with a TypeError): its target never travels.
+            const kind = err instanceof Error ? err.name : "unknown error";
+            throw new UpstreamTokenError(`Upstream token endpoint unreachable (${kind})`);
+        }
+        let body;
+        let readable = true;
+        try {
+            body = await res.json();
+        }
+        catch {
+            readable = false;
+        }
+        if (!res.ok) {
+            const oauthError = readable ? readOauthError(body) : undefined;
+            throw new UpstreamTokenError(`Upstream token endpoint answered ${res.status}${oauthError ? ` (error: ${oauthError})` : " (no readable OAuth error code)"}`, { status: res.status, oauthError });
+        }
+        const refuse = (what) => new UpstreamTokenError(`Upstream token endpoint answered ${res.status} with ${what}`, {
+            status: res.status,
+        });
+        if (!readable)
+            throw refuse("a body that is not JSON");
+        if (!body || typeof body !== "object" || Array.isArray(body)) {
+            throw refuse("a JSON body that is not an object");
+        }
+        const fields = body;
+        const token = fields.access_token;
+        if (typeof token !== "string" || token === "") {
+            throw refuse("no usable access_token");
+        }
+        // token_type is REQUIRED by RFC 6749 §5.1 but some endpoints omit it: an absent type is
+        // taken as Bearer. A PRESENT type other than Bearer (DPoP, mac, ...) cannot be sent as
+        // `Authorization: Bearer`, so it is refused.
+        const tokenType = fields.token_type;
+        if (tokenType !== undefined) {
+            if (typeof tokenType !== "string" || tokenType.toLowerCase() !== "bearer") {
+                throw refuse("a token_type other than Bearer");
+            }
+        }
+        let expiresIn;
+        const rawExpiresIn = fields.expires_in;
+        if (rawExpiresIn === undefined) {
+            expiresIn = DEFAULT_EXPIRES_IN_SECONDS; // see the constant: absent means 300 s
+        }
+        else if (typeof rawExpiresIn === "number") {
+            expiresIn = rawExpiresIn;
+        }
+        else if (typeof rawExpiresIn === "string" && /^\d+$/.test(rawExpiresIn)) {
+            // Some endpoints send the number as a string; only plain digits are read.
+            expiresIn = Number(rawExpiresIn);
+        }
+        else {
+            throw refuse("an unreadable expires_in");
+        }
+        if (!Number.isFinite(expiresIn) || expiresIn < 0) {
+            throw refuse("an unreadable expires_in");
+        }
+        // A lifetime shorter than twice the skew would be stale on arrival and refetched on every
+        // call: such a token is refreshed at half its lifetime instead.
+        const lead = Math.min(refreshSkewSeconds, expiresIn / 2);
+        return { token, refreshAt: requestedAt + (expiresIn - lead) * 1000 };
+    };
+    let cached;
+    let inflight;
+    const getToken = () => {
+        if (cached && now() < cached.refreshAt)
+            return Promise.resolve(cached.token);
+        if (!inflight) {
+            inflight = requestToken()
+                .then((fresh) => {
+                cached = fresh;
+                return fresh.token;
+            })
+                .finally(() => {
+                inflight = undefined;
+            });
+        }
+        return inflight;
+    };
+    const invalidate = (token) => {
+        if (token === undefined || cached?.token === token)
+            cached = undefined;
+    };
+    const fetchWithToken = async (input, init) => {
+        // A stream body is consumed by the first send and cannot be replayed: such a request gets
+        // the token refresh on a 401 but no retry; the 401 is returned to the caller.
+        const replayable = !(init?.body instanceof ReadableStream);
+        const send = (token, last) => {
+            const headers = new Headers(init?.headers ?? (input instanceof Request ? input.headers : undefined));
+            headers.set("Authorization", `Bearer ${token}`);
+            // A Request input is cloned for the first send so its body is still there for the retry.
+            const target = input instanceof Request && !last ? input.clone() : input;
+            // The caller's init is spread as given, redirect mode included: the caller decides whether
+            // its API request follows redirects (the paginated client passes redirect: "error").
+            return fetchImpl(target, { ...init, headers });
+        };
+        const token = await getToken();
+        const first = await send(token, !replayable);
+        if (first.status !== 401)
+            return first;
+        invalidate(token);
+        if (!replayable)
+            return first;
+        await first.body?.cancel().catch(() => { });
+        return send(await getToken(), true);
+    };
+    return { getToken, invalidate, fetchWithToken };
+}
+/**
+ * Reads the token source's configuration from the variables the caller names. Unset and empty
+ * are both missing. Every missing required variable is named in one error; no value is ever
+ * shown. Pass the result (plus any `fetchImpl`, `authMethod`, ...) to
+ * `createClientCredentialsTokenSource`.
+ */
+export function clientCredentialsFromEnv(vars, env = process.env) {
+    const required = [vars.clientIdVar, vars.clientSecretVar, vars.tokenUrlVar];
+    const missing = required.filter((name) => rawKnob(env, name) === undefined);
+    if (missing.length > 0) {
+        throw new Error(`client_credentials: missing environment variable${missing.length > 1 ? "s" : ""} ${missing.join(", ")} (values not shown)`);
+    }
+    const options = {
+        clientId: rawKnob(env, vars.clientIdVar),
+        clientSecret: rawKnob(env, vars.clientSecretVar),
+        tokenUrl: rawKnob(env, vars.tokenUrlVar),
+    };
+    const scope = vars.scopeVar ? rawKnob(env, vars.scopeVar) : undefined;
+    if (scope !== undefined)
+        options.scope = scope;
+    const audience = vars.audienceVar ? rawKnob(env, vars.audienceVar) : undefined;
+    if (audience !== undefined)
+        options.audience = audience;
+    return options;
+}

package/dist/upstream/paginatedClient.d.ts

@@ -0,0 +1,142 @@
+/**
+ * Paginated upstream client, for a server derived from this boilerplate that reads a third-party
+ * endpoint paginated by OFFSET and LIMIT. The upstream is configuration: the parameter names,
+ * where they travel (query string or JSON body) and the HTTP method are options, nothing here
+ * names a vendor.
+ *
+ * Two reads:
+ * - `readAll(path, params)` walks the offset pages until a short or empty page (or, when the
+ *   response declares a total, until the total is reached) and returns every row. It is bounded
+ *   by a REQUIRED finite `rowCeiling`: a set that would exceed it is refused with an
+ *   `UpstreamPageError` (`row_ceiling_exceeded`) naming the ceiling. A truncated set is never
+ *   returned as if it were complete.
+ * - `readPage(path, params, cursor?)` reads ONE upstream page per MCP call and returns
+ *   `{ rows, nextCursor?, exhausted }`. The cursor is opaque: base64url of a small JSON object
+ *   carrying a version, the upstream offset and a fingerprint of path + params. A cursor that
+ *   does not decode, is replayed against another path or other params, or was altered without
+ *   recomputing its fingerprint is refused with the `invalid_cursor` semantics of
+ *   `src/pagination.ts` (`InvalidCursorError`), never read as page one. The fingerprint is an
+ *   UNKEYED hash: it detects misuse, not forgery. Anyone can mint a well-formed cursor at any
+ *   offset, which is acceptable because the offset carries no authority (the caller could ask
+ *   for that offset anyway): a minted offset above the ceiling is refused before any request,
+ *   and the same ceiling bounds the page-by-page walk.
+ *
+ * ```ts
+ * // src/upstream.ts — evaluated once per process, beside the token source
+ * export const things = createPaginatedUpstreamClient({
+ *   fetchImpl: upstream.fetchWithToken, // G1's token source; default: the global fetch
+ *   baseUrl: "https://api.upstream.example/v1/",
+ *   allowedOrigins: ["https://api.upstream.example"],
+ *   offsetParam: "offset",
+ *   limitParam: "limit",
+ *   placement: "jsonBody", // or "query"
+ *   rowCeiling: 5000,
+ *   extractRows: (body) => (body as { data: unknown[] }).data,
+ * });
+ * ```
+ *
+ * Safety:
+ * - Every request URL is resolved against `baseUrl` and its origin must be in `allowedOrigins`,
+ *   checked BEFORE any network call: a path (possibly from a tool argument) naming another host
+ *   never receives the bearer token. Origins are https, or http on loopback only (as G1).
+ * - Redirects are never followed (`redirect: "error"`): a 30x from an allowed origin cannot carry
+ *   the request to another host. The refused redirect surfaces as `unreachable`, by error kind.
+ * - 429 and 503 are retried with exponential backoff and jitter, honouring `Retry-After`
+ *   (seconds or HTTP date) capped by `maxDelayMs`; after `maxAttempts` the error names the
+ *   status and the attempt count. No other status is retried, and neither is a transport
+ *   failure (its error KIND is reported, never its message).
+ * - A body that is not JSON, an extractor that throws or does not return an array, an unreadable
+ *   total, or a page longer than the limit asked for is refused (fail closed). There is no
+ *   silent empty page: an empty page before a declared total is `inconsistent_page`, so a walk
+ *   can never re-request the same offset forever.
+ * - Errors may name the request PATH (pathname only) and the HTTP status. They never carry a
+ *   header, a token, the query string, a parameter value or the response body.
+ *
+ * Offset pagination over an order the upstream does not declare can skip or repeat rows when the
+ * data moves between two pages. This client cannot detect that; pass a sort parameter in
+ * `params` when the upstream offers one. And when the upstream silently caps the page below
+ * `pageSize`, a short page reads as the end of the set: keep `pageSize` within the upstream's
+ * real maximum, or supply `extractTotal`, which then decides the end instead.
+ *
+ * Errors are operator-facing (logged server-side), in English like `clientCredentials.ts`.
+ */
+export type PaginationPlacement = "query" | "jsonBody";
+/** Any `fetch`-compatible function: the global fetch, or G1's `tokenSource.fetchWithToken`. */
+export type FetchLike = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+export interface PaginatedUpstreamOptions<Row = unknown> {
+    /** Default: the global fetch. */
+    fetchImpl?: FetchLike;
+    /** Paths are resolved against it (`new URL(path, baseUrl)`). Its origin must be allowed. */
+    baseUrl: string;
+    /** REQUIRED, non-empty. Exact origins (`https://host[:port]`), https or loopback http. */
+    allowedOrigins: readonly string[];
+    /** Name of the upstream offset parameter. */
+    offsetParam: string;
+    /** Name of the upstream page-size parameter. */
+    limitParam: string;
+    /** Where params, offset and limit travel. */
+    placement: PaginationPlacement;
+    /** Default: GET for `query`, POST for `jsonBody`. `jsonBody` refuses GET and HEAD. */
+    method?: string;
+    /** Rows asked per upstream page. Default 100. */
+    pageSize?: number;
+    /** REQUIRED. The most rows one walk may return; a positive finite integer. */
+    rowCeiling: number;
+    /** Returns the rows of one parsed page. Must return an array. */
+    extractRows: (body: unknown) => Row[];
+    /** Optional: the total the page declares (a non-negative integer), or undefined. */
+    extractTotal?: (body: unknown) => number | undefined;
+    /** Headers added to every request (e.g. `Accept`). */
+    headers?: Record<string, string>;
+    /** Total attempts per page on 429/503, first one included. Default 5. */
+    maxAttempts?: number;
+    /** First backoff delay. Default 500 ms. */
+    baseDelayMs?: number;
+    /** Cap on any one delay, `Retry-After` included. Default 30 000 ms. */
+    maxDelayMs?: number;
+    /** Time budget of one request. Default 30 s. */
+    timeoutMs?: number;
+    /** Default: a `setTimeout` promise. */
+    sleep?: (ms: number) => Promise<void>;
+    /** In [0, 1). Default `Math.random`. */
+    random?: () => number;
+    /** Milliseconds since the epoch, for `Retry-After` dates. Default `Date.now`. */
+    now?: () => number;
+}
+export type ParamValue = string | number | boolean | null | ParamValue[] | ParamObject;
+export interface ParamObject {
+    [key: string]: ParamValue | undefined;
+}
+export type UpstreamParams = Record<string, ParamValue | undefined>;
+export interface UpstreamPage<Row> {
+    rows: Row[];
+    /** Present exactly when more rows may follow. */
+    nextCursor?: string;
+    exhausted: boolean;
+    /** The total the page declared, when `extractTotal` is set. */
+    total?: number;
+}
+export interface PaginatedUpstreamClient<Row> {
+    readAll(path: string, params: UpstreamParams): Promise<Row[]>;
+    readPage(path: string, params: UpstreamParams, cursor?: string): Promise<UpstreamPage<Row>>;
+}
+export type UpstreamPageErrorCode = "origin_not_allowed" | "invalid_params" | "row_ceiling_exceeded" | "rate_limited" | "upstream_status" | "unreachable" | "unreadable_page" | "inconsistent_page";
+/** A refused or failed upstream page read. Carries no header, token, parameter or body. */
+export declare class UpstreamPageError extends Error {
+    readonly code: UpstreamPageErrorCode;
+    /** The request pathname (no query string), when a request was built. */
+    readonly path: string | undefined;
+    /** HTTP status, when the upstream answered. */
+    readonly status: number | undefined;
+    /** Attempts made, on `rate_limited`. */
+    readonly attempts: number | undefined;
+    /** The ceiling, on `row_ceiling_exceeded`. */
+    readonly rowCeiling: number | undefined;
+    constructor(code: UpstreamPageErrorCode, message: string, details?: {
+        path?: string;
+        status?: number;
+        attempts?: number;
+        rowCeiling?: number;
+    });
+}
+export declare function createPaginatedUpstreamClient<Row = unknown>(options: PaginatedUpstreamOptions<Row>): PaginatedUpstreamClient<Row>;