@honua/mcp-server 0.0.10-alpha.0 → 0.1.0-beta.0

package/dist/src/certification/json-schema.js

@@ -0,0 +1,172 @@
+import { Ajv2020 } from "ajv/dist/2020.js";
+import draft07MetaSchema from "ajv/dist/refs/json-schema-draft-07.json" with { type: "json" };
+/**
+ * Deterministic JSON Schema utilities for certification.
+ *
+ * Two dialects appear in practice:
+ *   - The vendored geospatial-mcp standard schemas declare draft 2020-12.
+ *   - MCP tool `inputSchema`s emitted via zod-to-json-schema declare draft-07.
+ *
+ * A single Ajv 2020-12 core handles both: we register the draft-07 meta-schema
+ * so a schema that declares `$schema: ".../draft-07/schema#"` resolves instead
+ * of erroring with "no schema with key/ref". All work is in-process: no network
+ * access, no model calls.
+ *
+ * `strict: false` tolerates non-standard annotation keywords (e.g.
+ * `x-honua-reference-shape`); `validateFormats: false` keeps well-formedness
+ * purely structural and offline.
+ */
+function createAjv() {
+    const ajv = new Ajv2020({ strict: false, allErrors: true, validateFormats: false });
+    ajv.addMetaSchema(draft07MetaSchema);
+    return ajv;
+}
+/**
+ * Check that a value is a structurally well-formed JSON Schema by asking Ajv to
+ * compile it. A schema that compiles is usable as a validator; a schema Ajv
+ * refuses to compile is malformed.
+ */
+export function checkWellFormed(schema) {
+    if (schema === undefined || schema === null) {
+        return { wellFormed: false, errors: ["schema is missing (null/undefined)"] };
+    }
+    if (typeof schema !== "object") {
+        return { wellFormed: false, errors: [`schema must be an object, got ${typeof schema}`] };
+    }
+    try {
+        const ajv = createAjv();
+        ajv.compile(schema);
+        return { wellFormed: true, errors: [] };
+    }
+    catch (err) {
+        return { wellFormed: false, errors: [err instanceof Error ? err.message : String(err)] };
+    }
+}
+function formatErrors(errors) {
+    if (!errors) {
+        return [];
+    }
+    return errors.map((e) => `${e.instancePath || "(root)"} ${e.message ?? "is invalid"}`.trim());
+}
+/** Compile a schema into a reusable validator, or throw a descriptive error. */
+export function compileValidator(schema) {
+    const ajv = createAjv();
+    return ajv.compile(schema);
+}
+/** Validate a value against a JSON Schema and collect human-readable errors. */
+export function validateAgainstSchema(schema, value) {
+    try {
+        const validate = compileValidator(schema);
+        const valid = validate(value);
+        return { valid, errors: valid ? [] : formatErrors(validate.errors) };
+    }
+    catch (err) {
+        return { valid: false, errors: [err instanceof Error ? err.message : String(err)] };
+    }
+}
+/**
+ * Extract the top-level property names a JSON Schema accepts, when discoverable
+ * from a plain `type: object` shape. Returns undefined when the property set is
+ * not statically enumerable (e.g. additionalProperties / combinators only).
+ */
+function objectPropertyNames(schema) {
+    const props = schema.properties;
+    if (props && typeof props === "object") {
+        return new Set(Object.keys(props));
+    }
+    return undefined;
+}
+function requiredPropertyNames(schema) {
+    const required = schema.required;
+    return Array.isArray(required) ? required.filter((r) => typeof r === "string") : [];
+}
+/** Normalize a JSON Schema `type` (string or array) into a set. */
+function schemaTypes(schema) {
+    if (!schema) {
+        return new Set();
+    }
+    const t = schema.type;
+    if (typeof t === "string") {
+        return new Set([t]);
+    }
+    if (Array.isArray(t)) {
+        return new Set(t.filter((x) => typeof x === "string"));
+    }
+    return new Set();
+}
+/**
+ * Deterministically compare an advertised tool inputSchema against a standard
+ * geospatial-mcp tool schema.
+ *
+ * Conformance contract (intentionally permissive to avoid false negatives — we
+ * fail only on demonstrable non-conformance, never on the absence of a tool):
+ *
+ *   1. Every property the standard marks `required` MUST be present in the
+ *      advertised schema's properties (a client that follows the standard will
+ *      send it, so the tool must accept it).
+ *   2. For each such required property, when both schemas declare a `type`, the
+ *      advertised type must be compatible (equal, or a superset, or `integer`
+ *      accepted where the standard says `number`).
+ *
+ * Extra advertised properties and looser-but-compatible types are recorded as
+ * notes, not violations: a richer reference shape is allowed to extend the
+ * bare standard.
+ */
+export function checkConformance(advertised, standard, options = {}) {
+    const violations = [];
+    const notes = [];
+    const matchedRequired = [];
+    // Required standard properties this surface may legitimately shed as a
+    // documented platform-gated degradation. See {@link ConformanceOptions.shedRequired}.
+    const shedRequired = new Set(options.shedRequired ?? []);
+    const standardRequired = requiredPropertyNames(standard);
+    const standardProps = (standard.properties ?? {});
+    const advertisedProps = (advertised.properties ?? {});
+    const advertisedNames = objectPropertyNames(advertised);
+    for (const name of standardRequired) {
+        const present = advertisedNames ? advertisedNames.has(name) : name in advertisedProps;
+        if (!present) {
+            if (shedRequired.has(name)) {
+                notes.push(`degrades platform binding: omits required "${name}" (platform-free target has no publishing surface)`);
+            }
+            else {
+                violations.push(`missing required standard property "${name}"`);
+            }
+            continue;
+        }
+        const standardTypes = schemaTypes(standardProps[name]);
+        const advertisedTypes = schemaTypes(advertisedProps[name]);
+        if (standardTypes.size > 0 && advertisedTypes.size > 0) {
+            const compatible = [...standardTypes].every((st) => {
+                if (advertisedTypes.has(st)) {
+                    return true;
+                }
+                // `integer` is a refinement of `number`: a standard `number` is
+                // satisfied by an advertised `integer`, and vice versa is acceptable.
+                if (st === "number" && advertisedTypes.has("integer")) {
+                    return true;
+                }
+                if (st === "integer" && advertisedTypes.has("number")) {
+                    notes.push(`property "${name}" widens standard integer to number`);
+                    return true;
+                }
+                return false;
+            });
+            if (!compatible) {
+                violations.push(`property "${name}" type ${[...advertisedTypes].join("|")} is incompatible with standard ${[...standardTypes].join("|")}`);
+                continue;
+            }
+        }
+        matchedRequired.push(name);
+    }
+    // Record advertised-only properties as informational coverage notes.
+    if (advertisedNames) {
+        const standardNames = new Set(Object.keys(standardProps));
+        for (const name of advertisedNames) {
+            if (!standardNames.has(name)) {
+                notes.push(`advertises non-standard property "${name}"`);
+            }
+        }
+    }
+    return { conformant: violations.length === 0, matchedRequired, violations, notes };
+}

package/dist/src/certification/lifecycle.d.ts

@@ -0,0 +1,14 @@
+import type { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import type { ContractCheck } from "./certifier.js";
+export interface DeepContractOptions {
+    client: Client;
+    advertisedToolNames: Set<string>;
+    /** Whether the backend is the disposable offline mock (auto-allows mutation). */
+    isDisposableBackend: boolean;
+    /** Open a fresh unauthenticated client (for the permission-denied case). */
+    connectUnauthenticated?: (() => Promise<Client>) | undefined;
+    env?: NodeJS.ProcessEnv;
+}
+/** Run all deep contracts, returning one ContractCheck per contract (never throws). */
+export declare function runDeepContracts(options: DeepContractOptions): Promise<ContractCheck[]>;
+//# sourceMappingURL=lifecycle.d.ts.map

package/dist/src/certification/lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../../../src/certification/lifecycle.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AACxE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAoCpD,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,mBAAmB,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACjC,iFAAiF;IACjF,mBAAmB,EAAE,OAAO,CAAC;IAC7B,4EAA4E;IAC5E,sBAAsB,CAAC,EAAE,CAAC,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,SAAS,CAAC;IAC7D,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACzB;AAcD,uFAAuF;AACvF,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC,CAW7F"}

package/dist/src/certification/lifecycle.js

@@ -0,0 +1,326 @@
+import { randomUUID } from "node:crypto";
+import { checkAuthContract, checkFeatureRoundTrip, checkJobLifecycle, checkPaginationContract, } from "./contracts.js";
+import { resolveEditTarget } from "./fixtures.js";
+/**
+ * Deep, stateful certification contracts (A5 provability): the mutating-tool
+ * round-trip, the async job lifecycle, and query pagination. These extend the
+ * read-side contracts in {@link certifier} into the parts of a real deployment
+ * that were "never certified" — writes and asynchronous execution.
+ *
+ * Safety: mutating contracts only auto-run against the offline mock (a disposable
+ * fixture). Against a live/remote target they are gated behind
+ * `HONUA_MCP_CERT_ALLOW_MUTATION=1` + a caller-supplied scratch service, so a
+ * scheduled cert against a shared demo never mutates real data. When a target
+ * lacks the tool, the contract SKIPS with a loud reason rather than failing — so
+ * the suite stays runnable against any revision. Note: the reference honua-server
+ * `/mcp` surface does NOT advertise `EDIT_TOOL` — Honua does not support AI
+ * operational data editing (honua-server ADR-0028) — so against it these mutating
+ * contracts skip. `EDIT_TOOL` here represents the standard's OPTIONAL `mutation`
+ * profile, exercised via a mutation-profile-adopter fixture.
+ */
+const MUTATION_ALLOW_ENV = "HONUA_MCP_CERT_ALLOW_MUTATION";
+const EDIT_TOOL = "honua_edit_features";
+const QUERY_TOOL = "honua_query_features";
+const EXECUTE_TOOL = "honua_execute_plan";
+const MAX_JOB_POLLS = 12;
+const PAGE_LIMIT = 2;
+const MAX_FEATURE_PAGES = 20;
+function isTruthy(value) {
+    if (typeof value !== "string") {
+        return false;
+    }
+    const v = value.trim().toLowerCase();
+    return v.length > 0 && v !== "0" && v !== "false" && v !== "no" && v !== "off";
+}
+function skip(contract, target, detail) {
+    return { contract, target, status: "skipped", detail };
+}
+/** Run all deep contracts, returning one ContractCheck per contract (never throws). */
+export async function runDeepContracts(options) {
+    const env = options.env ?? process.env;
+    const target = resolveEditTarget(env);
+    const mutationAllowed = options.isDisposableBackend || isTruthy(env[MUTATION_ALLOW_ENV]);
+    return [
+        await runMutatingRoundTrip(options, target, mutationAllowed),
+        await runMutatingPermissionDenied(options),
+        await runJobLifecycle(options, mutationAllowed),
+        await runQueryPagination(options, target),
+    ];
+}
+async function callTool(client, name, args) {
+    const result = (await client.callTool({ name, arguments: args }));
+    return result;
+}
+async function readJsonResource(client, uri) {
+    const res = (await client.readResource({ uri }));
+    const text = res.contents?.[0]?.text;
+    return typeof text === "string" ? JSON.parse(text) : {};
+}
+function featureAttributes(result) {
+    const features = (result.structuredContent?.features ?? []);
+    return features.map((f) => f.attributes ?? {});
+}
+// ── Contract 1: mutating-tool insert→verify→update→verify→delete→verify ──────
+async function runMutatingRoundTrip(options, target, mutationAllowed) {
+    const contract = "mutating-round-trip";
+    if (!options.advertisedToolNames.has(EDIT_TOOL) || !options.advertisedToolNames.has(QUERY_TOOL)) {
+        return skip(contract, EDIT_TOOL, `${EDIT_TOOL}/${QUERY_TOOL} not advertised by this surface (pre-P1 or read-only)`);
+    }
+    if (!mutationAllowed) {
+        return skip(contract, EDIT_TOOL, `mutating contract disabled for this target — set ${MUTATION_ALLOW_ENV}=1 with a scratch service to certify writes`);
+    }
+    const { client } = options;
+    const marker = `cert-${randomUUID().slice(0, 8)}`;
+    const updatedMarker = `${marker}-updated`;
+    let objectId;
+    try {
+        const inserted = await callTool(client, EDIT_TOOL, {
+            serviceId: target.serviceId,
+            layerId: target.layerId,
+            adds: [{ attributes: { NAME: marker } }],
+        });
+        const addResults = (inserted.structuredContent?.addResults ?? []);
+        objectId = typeof addResults[0]?.objectId === "number" ? addResults[0].objectId : undefined;
+        const presentAfterInsert = objectId !== undefined &&
+            featureAttributes(await callTool(client, QUERY_TOOL, {
+                serviceId: target.serviceId,
+                layerId: target.layerId,
+                objectIds: [objectId],
+            })).some((a) => Number(a.OBJECTID) === objectId);
+        if (objectId !== undefined) {
+            await callTool(client, EDIT_TOOL, {
+                serviceId: target.serviceId,
+                layerId: target.layerId,
+                updates: [{ objectId, attributes: { NAME: updatedMarker } }],
+            });
+        }
+        const attributeAfterUpdate = objectId === undefined
+            ? undefined
+            : featureAttributes(await callTool(client, QUERY_TOOL, {
+                serviceId: target.serviceId,
+                layerId: target.layerId,
+                objectIds: [objectId],
+            }))[0]?.NAME;
+        if (objectId !== undefined) {
+            await callTool(client, EDIT_TOOL, { serviceId: target.serviceId, layerId: target.layerId, deletes: [objectId] });
+        }
+        const absentAfterDelete = objectId !== undefined &&
+            featureAttributes(await callTool(client, QUERY_TOOL, {
+                serviceId: target.serviceId,
+                layerId: target.layerId,
+                objectIds: [objectId],
+            })).every((a) => Number(a.OBJECTID) !== objectId);
+        const outcome = checkFeatureRoundTrip({
+            insertedObjectId: objectId,
+            presentAfterInsert,
+            attributeAfterUpdate,
+            expectedAttribute: updatedMarker,
+            absentAfterDelete,
+        });
+        return {
+            contract,
+            target: EDIT_TOOL,
+            status: outcome.ok ? "passed" : "failed",
+            detail: outcome.ok
+                ? `insert→verify→update→verify→delete→verify round-trip succeeded (objectId ${objectId})`
+                : outcome.errors.join("; "),
+        };
+    }
+    catch (err) {
+        return {
+            contract,
+            target: EDIT_TOOL,
+            status: "failed",
+            detail: `mutating round-trip raised: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+    finally {
+        // Guaranteed cleanup: remove the scratch feature even if an assertion threw.
+        if (objectId !== undefined) {
+            await callTool(client, EDIT_TOOL, {
+                serviceId: target.serviceId,
+                layerId: target.layerId,
+                deletes: [objectId],
+            }).catch(() => { });
+        }
+    }
+}
+// ── Contract 1b: mutating call without credentials → structured auth error ───
+async function runMutatingPermissionDenied(options) {
+    const contract = "mutating-permission-denied";
+    if (!options.advertisedToolNames.has(EDIT_TOOL)) {
+        return skip(contract, EDIT_TOOL, `${EDIT_TOOL} not advertised by this surface (pre-P1)`);
+    }
+    if (!options.connectUnauthenticated) {
+        return skip(contract, EDIT_TOOL, "target does not support an unauthenticated pass");
+    }
+    const target = resolveEditTarget(options.env ?? process.env);
+    let unauth;
+    try {
+        unauth = await options.connectUnauthenticated();
+        // An unauthenticated write MUST be refused with a structured auth signal. If
+        // the boundary holds, nothing is mutated.
+        let result;
+        try {
+            result = await callTool(unauth, EDIT_TOOL, {
+                serviceId: target.serviceId,
+                layerId: target.layerId,
+                adds: [{ attributes: { NAME: "cert-should-be-denied" } }],
+            });
+        }
+        catch (err) {
+            const outcome = checkAuthContract(err);
+            return {
+                contract,
+                target: EDIT_TOOL,
+                status: outcome.ok ? "passed" : "failed",
+                detail: outcome.ok ? "unauthenticated write refused with a structured auth error" : outcome.errors.join("; "),
+            };
+        }
+        if (result.isError !== true) {
+            return {
+                contract,
+                target: EDIT_TOOL,
+                status: "failed",
+                detail: "unauthenticated write returned a non-error result — the write auth boundary is not enforced",
+            };
+        }
+        const outcome = checkAuthContract(result);
+        return {
+            contract,
+            target: EDIT_TOOL,
+            status: outcome.ok ? "passed" : "failed",
+            detail: outcome.ok ? "unauthenticated write refused with a structured auth error" : outcome.errors.join("; "),
+        };
+    }
+    catch (err) {
+        return {
+            contract,
+            target: EDIT_TOOL,
+            status: "failed",
+            detail: `permission-denied pass could not be established: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+    finally {
+        if (unauth) {
+            await unauth.close().catch(() => { });
+        }
+    }
+}
+// ── Contract 2: async job lifecycle execute → poll → result ──────────────────
+async function runJobLifecycle(options, mutationAllowed) {
+    const contract = "async-job-lifecycle";
+    if (!options.advertisedToolNames.has(EXECUTE_TOOL)) {
+        return skip(contract, EXECUTE_TOOL, `${EXECUTE_TOOL} not advertised by this surface (pre-P1)`);
+    }
+    if (!mutationAllowed) {
+        return skip(contract, EXECUTE_TOOL, `job lifecycle disabled for this target — set ${MUTATION_ALLOW_ENV}=1 to certify execution against a scratch target`);
+    }
+    const { client } = options;
+    try {
+        const submitted = await callTool(client, EXECUTE_TOOL, {
+            plan: { planId: "cert-plan", steps: [{ stepId: "s1", kind: "QueryFeatures" }] },
+        });
+        const jobId = submitted.structuredContent?.jobId;
+        const initialStatus = String(submitted.structuredContent?.status ?? "Unknown");
+        if (typeof jobId !== "string") {
+            return { contract, target: EXECUTE_TOOL, status: "failed", detail: "execute did not return a jobId" };
+        }
+        const jobUri = `honua://jobs/${jobId}`;
+        const polledStatuses = [];
+        const progressFractions = [];
+        let finalStatus = initialStatus;
+        let resultUri;
+        for (let i = 0; i < MAX_JOB_POLLS; i++) {
+            const state = await readJsonResource(client, jobUri);
+            const status = String(state.status ?? "Unknown");
+            polledStatuses.push(status);
+            const fraction = state.progress?.fraction;
+            if (typeof fraction === "number") {
+                progressFractions.push(fraction);
+            }
+            finalStatus = status;
+            if (typeof state.resultUri === "string") {
+                resultUri = state.resultUri;
+            }
+            if (["Succeeded", "Failed", "Cancelled"].includes(status)) {
+                break;
+            }
+        }
+        let resultReady = false;
+        if (resultUri) {
+            const pkg = await readJsonResource(client, resultUri);
+            resultReady = String(pkg.status ?? "") === "Ready";
+        }
+        const outcome = checkJobLifecycle({
+            initialStatus,
+            polledStatuses,
+            progressFractions,
+            finalStatus,
+            resultReady,
+        });
+        return {
+            contract,
+            target: EXECUTE_TOOL,
+            status: outcome.ok ? "passed" : "failed",
+            detail: outcome.ok
+                ? `execute→poll→result honored the state machine (${[initialStatus, ...polledStatuses].join("→")}; result ready)`
+                : outcome.errors.join("; "),
+        };
+    }
+    catch (err) {
+        return {
+            contract,
+            target: EXECUTE_TOOL,
+            status: "failed",
+            detail: `job lifecycle raised: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+}
+// ── Contract 3: query_features pagination (read-only, safe against any target) ─
+async function runQueryPagination(options, target) {
+    const contract = "query-pagination";
+    if (!options.advertisedToolNames.has(QUERY_TOOL)) {
+        return skip(contract, QUERY_TOOL, `${QUERY_TOOL} not advertised by this surface`);
+    }
+    const { client } = options;
+    try {
+        const pages = [];
+        let cursor;
+        for (let i = 0; i < MAX_FEATURE_PAGES; i++) {
+            const args = { serviceId: target.serviceId, layerId: target.layerId, limit: PAGE_LIMIT };
+            if (cursor) {
+                args.cursor = cursor;
+            }
+            const result = await callTool(client, QUERY_TOOL, args);
+            const keys = featureAttributes(result).map((a) => String(a.OBJECTID));
+            const nextCursor = result.structuredContent?.nextCursor;
+            pages.push({ keys, nextCursor: typeof nextCursor === "string" ? nextCursor : undefined });
+            if (typeof nextCursor !== "string") {
+                break;
+            }
+            cursor = nextCursor;
+        }
+        const paginated = pages.length > 1 || pages[0]?.nextCursor !== undefined;
+        if (!paginated) {
+            return skip(contract, QUERY_TOOL, `surface returned a single page with no nextCursor (pagination not exercised — pre-P1 surface or fewer than ${PAGE_LIMIT} features)`);
+        }
+        const outcome = checkPaginationContract(pages);
+        return {
+            contract,
+            target: QUERY_TOOL,
+            status: outcome.ok ? "passed" : "failed",
+            detail: outcome.ok
+                ? `query_features paginated across ${pages.length} pages; nextCursor honored and terminated`
+                : outcome.errors.join("; "),
+        };
+    }
+    catch (err) {
+        return {
+            contract,
+            target: QUERY_TOOL,
+            status: "failed",
+            detail: `query pagination raised: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+}

package/dist/src/certification/mock-upstream.d.ts

@@ -0,0 +1,29 @@
+/**
+ * A real, in-process streamable-HTTP mock of the honua `/mcp` operator surface.
+ *
+ * The certification harness connects to this over the SAME client transport it
+ * uses for a live server (`StreamableHTTPClientTransport`), so the offline CI
+ * path exercises the identical connect/negotiate/tools-call code as the remote
+ * path — only the upstream is swapped for a deterministic fixture.
+ *
+ * Auth is enforced per request: the listener parses the bearer token / API key
+ * and attaches `req.auth` when present. Requests without a credential reach the
+ * operator server as unauthenticated, so the certifier's auth-contract pass sees
+ * the same structured `unauthenticated` signal a real deployment would emit.
+ */
+export interface MockUpstreamOptions {
+    /** Bearer token the mock accepts; default `mock-cert-token`. */
+    authToken?: string;
+    /** Whether tools/list and resources/list paginate (default true). */
+    paginate?: boolean;
+}
+export interface MockUpstream {
+    /** Absolute URL of the mock `/mcp` endpoint (loopback, ephemeral port). */
+    url: string;
+    /** Bearer token the mock accepts. */
+    authToken: string;
+    close(): Promise<void>;
+}
+/** Start the mock operator upstream and resolve once it is listening. */
+export declare function startMockUpstream(options?: MockUpstreamOptions): Promise<MockUpstream>;
+//# sourceMappingURL=mock-upstream.d.ts.map

package/dist/src/certification/mock-upstream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock-upstream.d.ts","sourceRoot":"","sources":["../../../src/certification/mock-upstream.ts"],"names":[],"mappings":"AAQA;;;;;;;;;;;;GAYG;AAEH,MAAM,WAAW,mBAAmB;IAClC,gEAAgE;IAChE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,qEAAqE;IACrE,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B,2EAA2E;IAC3E,GAAG,EAAE,MAAM,CAAC;IACZ,qCAAqC;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAcD,yEAAyE;AACzE,wBAAsB,iBAAiB,CAAC,OAAO,GAAE,mBAAwB,GAAG,OAAO,CAAC,YAAY,CAAC,CA4BhG"}

package/dist/src/certification/mock-upstream.js

@@ -0,0 +1,96 @@
+import { randomUUID } from "node:crypto";
+import { createServer } from "node:http";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
+import { createOperatorCatalogServer } from "./operator-catalog.js";
+function readBearer(req) {
+    const header = req.headers.authorization;
+    if (typeof header === "string" && header.toLowerCase().startsWith("bearer ")) {
+        return header.slice(7).trim();
+    }
+    const apiKey = req.headers["x-api-key"];
+    if (typeof apiKey === "string" && apiKey.length > 0) {
+        return apiKey;
+    }
+    return undefined;
+}
+/** Start the mock operator upstream and resolve once it is listening. */
+export async function startMockUpstream(options = {}) {
+    const authToken = options.authToken ?? "mock-cert-token";
+    const paginate = options.paginate ?? true;
+    // One transport + server per session (the documented multi-session pattern),
+    // so multiple certifier clients — the authenticated pass and the
+    // unauthenticated auth-contract pass — can connect concurrently.
+    const sessions = new Map();
+    const httpServer = createServer((req, res) => {
+        void handleHttpRequest(req, res, sessions, authToken, paginate);
+    });
+    await new Promise((resolve) => httpServer.listen(0, "127.0.0.1", resolve));
+    const address = httpServer.address();
+    const url = `http://127.0.0.1:${address.port}/mcp`;
+    return {
+        url,
+        authToken,
+        async close() {
+            for (const transport of sessions.values()) {
+                await transport.close().catch(() => { });
+            }
+            sessions.clear();
+            await new Promise((resolve) => httpServer.close(() => resolve()));
+        },
+    };
+}
+async function readJsonBody(req) {
+    const chunks = [];
+    for await (const chunk of req) {
+        chunks.push(chunk);
+    }
+    if (chunks.length === 0) {
+        return undefined;
+    }
+    try {
+        return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+async function handleHttpRequest(req, res, sessions, authToken, paginate) {
+    const token = readBearer(req);
+    if (token && token === authToken) {
+        // AuthInfo the transport threads through to request handlers (per request).
+        req.auth = { token, clientId: "cert-client", scopes: ["operator"] };
+    }
+    const sessionId = req.headers["mcp-session-id"];
+    const existing = typeof sessionId === "string" ? sessions.get(sessionId) : undefined;
+    if (existing) {
+        await existing.handleRequest(req, res);
+        return;
+    }
+    // No session yet — only an initialize request may open one.
+    const body = await readJsonBody(req);
+    if (!isInitializeRequest(body)) {
+        res.writeHead(400, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({
+            jsonrpc: "2.0",
+            error: { code: -32000, message: "Bad Request: no valid session ID provided" },
+            id: null,
+        }));
+        return;
+    }
+    const transport = new StreamableHTTPServerTransport({
+        sessionIdGenerator: () => randomUUID(),
+        enableJsonResponse: true,
+        onsessioninitialized: (id) => {
+            sessions.set(id, transport);
+        },
+    });
+    transport.onclose = () => {
+        if (transport.sessionId) {
+            sessions.delete(transport.sessionId);
+        }
+    };
+    const server = createOperatorCatalogServer({ paginate });
+    await server.connect(transport);
+    await transport.handleRequest(req, res, body);
+}