@emseepea/create-soap-backed-server 0.0.0

package/initializer-dist/template/src/generated/pea-service.schema-model.json

@@ -0,0 +1,205 @@
+{
+  "targetNamespace": "http://schemas.xmlsoap.org/soap/envelope/",
+  "elementFormDefault": "qualified",
+  "attributeFormDefault": "unqualified",
+  "version": "",
+  "elements": {
+    "{http://schemas.xmlsoap.org/soap/envelope/}Envelope": {
+      "name": "Envelope",
+      "namespace": "http://schemas.xmlsoap.org/soap/envelope/",
+      "typeName": "{http://schemas.xmlsoap.org/soap/envelope/}SoapEnvelope",
+      "nillable": false,
+      "abstract": false,
+      "defaultValue": null,
+      "fixedValue": null,
+      "substitutionGroup": null,
+      "minOccurs": 1,
+      "maxOccurs": 1
+    },
+    "{urn:emseepea:pea-service}GetPeaRequest": {
+      "name": "GetPeaRequest",
+      "namespace": "urn:emseepea:pea-service",
+      "typeName": null,
+      "nillable": false,
+      "abstract": false,
+      "defaultValue": null,
+      "fixedValue": null,
+      "substitutionGroup": null,
+      "minOccurs": 1,
+      "maxOccurs": 1
+    },
+    "{urn:emseepea:pea-service}GetPeaResponse": {
+      "name": "GetPeaResponse",
+      "namespace": "urn:emseepea:pea-service",
+      "typeName": "{urn:emseepea:pea-service}PeaVariety",
+      "nillable": false,
+      "abstract": false,
+      "defaultValue": null,
+      "fixedValue": null,
+      "substitutionGroup": null,
+      "minOccurs": 1,
+      "maxOccurs": 1
+    }
+  },
+  "simpleTypes": {
+    "{urn:emseepea:pea-service}PeaType": {
+      "kind": "simple",
+      "name": "PeaType",
+      "namespace": "urn:emseepea:pea-service",
+      "baseTypeName": "xs:string",
+      "variety": "atomic",
+      "facets": [
+        {
+          "kind": "minLength",
+          "value": "1"
+        },
+        {
+          "kind": "maxLength",
+          "value": "40"
+        }
+      ],
+      "memberTypes": [],
+      "itemType": null
+    }
+  },
+  "complexTypes": {
+    "{http://schemas.xmlsoap.org/soap/envelope/}SoapBody": {
+      "kind": "complex",
+      "name": "SoapBody",
+      "namespace": "http://schemas.xmlsoap.org/soap/envelope/",
+      "abstract": false,
+      "mixed": false,
+      "contentType": "elementOnly",
+      "baseTypeName": null,
+      "derivationMethod": null,
+      "attributes": [],
+      "particle": {
+        "particleKind": "group",
+        "compositor": "choice",
+        "occurrence": {
+          "min": 1,
+          "max": 1
+        },
+        "particles": [
+          {
+            "particleKind": "element",
+            "occurrence": {
+              "min": 1,
+              "max": 1
+            },
+            "element": "GetPeaResponse"
+          },
+          {
+            "particleKind": "element",
+            "occurrence": {
+              "min": 1,
+              "max": 1
+            },
+            "element": "Fault"
+          }
+        ]
+      },
+      "simpleContent": null,
+      "final": [],
+      "block": []
+    },
+    "{http://schemas.xmlsoap.org/soap/envelope/}SoapEnvelope": {
+      "kind": "complex",
+      "name": "SoapEnvelope",
+      "namespace": "http://schemas.xmlsoap.org/soap/envelope/",
+      "abstract": false,
+      "mixed": false,
+      "contentType": "elementOnly",
+      "baseTypeName": null,
+      "derivationMethod": null,
+      "attributes": [],
+      "particle": {
+        "particleKind": "group",
+        "compositor": "sequence",
+        "occurrence": {
+          "min": 1,
+          "max": 1
+        },
+        "particles": [
+          {
+            "particleKind": "element",
+            "occurrence": {
+              "min": 1,
+              "max": 1
+            },
+            "element": "Body"
+          }
+        ]
+      },
+      "simpleContent": null,
+      "final": [],
+      "block": []
+    },
+    "{urn:emseepea:pea-service}PeaVariety": {
+      "kind": "complex",
+      "name": "PeaVariety",
+      "namespace": "urn:emseepea:pea-service",
+      "abstract": false,
+      "mixed": false,
+      "contentType": "elementOnly",
+      "baseTypeName": null,
+      "derivationMethod": null,
+      "attributes": [],
+      "particle": {
+        "particleKind": "group",
+        "compositor": "sequence",
+        "occurrence": {
+          "min": 1,
+          "max": 1
+        },
+        "particles": [
+          {
+            "particleKind": "element",
+            "occurrence": {
+              "min": 1,
+              "max": 1
+            },
+            "element": "name"
+          },
+          {
+            "particleKind": "element",
+            "occurrence": {
+              "min": 1,
+              "max": 1
+            },
+            "element": "peaType"
+          },
+          {
+            "particleKind": "element",
+            "occurrence": {
+              "min": 1,
+              "max": 1
+            },
+            "element": "daysToMaturity"
+          },
+          {
+            "particleKind": "element",
+            "occurrence": {
+              "min": 0,
+              "max": 1
+            },
+            "element": "note"
+          },
+          {
+            "particleKind": "element",
+            "occurrence": {
+              "min": 0,
+              "max": 5
+            },
+            "element": "trait"
+          }
+        ]
+      },
+      "simpleContent": null,
+      "final": [],
+      "block": []
+    }
+  },
+  "attributes": {},
+  "substitutionGroups": {}
+}

package/initializer-dist/template/src/generated/pea-service.ts

@@ -0,0 +1,34 @@
+// Generated from the local SOAP XSD graph. Do not edit.
+/** XSD simpleType: PeaType */
+export type PeaType = string;
+
+/** XSD complexType: SoapBody */
+export interface SoapBody {
+  GetPeaResponse: unknown;
+  Fault: unknown;
+}
+
+/** XSD complexType: SoapEnvelope */
+export interface SoapEnvelope {
+  Body: SoapBody;
+}
+
+/** XSD complexType: PeaVariety */
+export interface PeaVariety {
+  name: string;
+  peaType: PeaType;
+  daysToMaturity: number;
+  note?: string;
+  trait?: string[];
+}
+
+/** XSD element: Envelope */
+export type Envelope = SoapEnvelope;
+
+/** XSD element: GetPeaRequest */
+export interface GetPeaRequest {
+  name: string;
+}
+
+/** XSD element: GetPeaResponse */
+export type GetPeaResponse = PeaVariety;

package/initializer-dist/template/src/server.ts

@@ -0,0 +1,21 @@
+import { serveEmseepea } from "@emseepea/server";
+import { createSoapExample } from "./app.js";
+
+const endpoint = process.env.PEA_SOAP_URL ?? "http://127.0.0.1:3999/soap";
+const { app } = await createSoapExample(endpoint);
+const running = await serveEmseepea(app, {
+  port: Number.parseInt(process.env.PORT ?? "3000", 10),
+});
+
+console.log(`Em See Pea SOAP-backed example listening at ${running.url}`);
+
+let shuttingDown = false;
+async function shutdown(): Promise<void> {
+  if (shuttingDown) return;
+  shuttingDown = true;
+  await running.close();
+  process.exitCode = 0;
+}
+
+process.once("SIGINT", () => void shutdown());
+process.once("SIGTERM", () => void shutdown());

package/initializer-dist/template/src/soap-schema.ts

@@ -0,0 +1,28 @@
+import { readFile } from "node:fs/promises";
+import { parseXsd, parseXsdAsync, type SchemaModel } from "xml-xsd-engine";
+
+const contractDirectory = new URL("../contracts/", import.meta.url);
+
+export interface SoapSchemaGraph {
+  readonly envelope: SchemaModel;
+  readonly service: SchemaModel;
+}
+
+export async function loadSoapEnvelopeSchema(): Promise<SoapSchemaGraph> {
+  const service = await readFile(new URL("pea-service.xsd", contractDirectory), "utf8");
+  const envelope = await readFile(new URL("soap-envelope.xsd", contractDirectory), "utf8");
+  return parseSoapEnvelopeSchema(envelope, service);
+}
+
+export async function parseSoapEnvelopeSchema(
+  envelope: string,
+  service: string,
+): Promise<SoapSchemaGraph> {
+  const resolvedEnvelope = await parseXsdAsync(envelope, async (location, namespace) => {
+    if (location !== "pea-service.xsd" || namespace !== "urn:emseepea:pea-service") {
+      throw new Error("Blocked schema import");
+    }
+    return service;
+  });
+  return { envelope: resolvedEnvelope, service: parseXsd(service) };
+}

package/initializer-dist/template/src/validating-http-client.ts

@@ -0,0 +1,125 @@
+import { request as requestHttp } from "node:http";
+import { request as requestHttps } from "node:https";
+import type { ClientRequest, IncomingMessage } from "node:http";
+import type { IExOptions, IHeaders, IHttpClient } from "soap";
+import { parseXml, validate, validateSubtree } from "xml-xsd-engine";
+import type { SoapSchemaGraph } from "./soap-schema.js";
+
+export const maximumSoapBytes = 65_536;
+
+export class ValidatingHttpClient implements IHttpClient {
+  readonly #endpoint: URL;
+  readonly #schema: SoapSchemaGraph;
+  #validation = Promise.resolve();
+
+  constructor(endpoint: URL, schema: SoapSchemaGraph) {
+    this.#endpoint = endpoint;
+    this.#schema = schema;
+  }
+
+  request(
+    requestUrl: string,
+    data: unknown,
+    callback: Parameters<IHttpClient["request"]>[2],
+    headers: IHeaders = {},
+    options: IExOptions = {},
+  ): ReturnType<IHttpClient["request"]> {
+    const body = Buffer.isBuffer(data) ? data : Buffer.from(String(data ?? ""));
+    const pending = new Promise((resolve) => {
+      let finished = false;
+      let deadline: ReturnType<typeof setTimeout> | undefined;
+      const fail = (error: Error, request?: ClientRequest) => {
+        if (finished) return;
+        finished = true;
+        clearTimeout(deadline);
+        request?.destroy();
+        callback(error);
+        resolve({});
+      };
+      const succeed = (result: object, responseBody: string) => {
+        if (finished) return;
+        finished = true;
+        clearTimeout(deadline);
+        callback(null, result, responseBody);
+        resolve(result);
+      };
+      let target: URL;
+      try {
+        target = new URL(requestUrl);
+        if (target.href !== this.#endpoint.href) throw new Error("Blocked SOAP destination");
+        if (body.byteLength > maximumSoapBytes) throw new Error("SOAP request too large");
+      } catch (error) {
+        fail(error instanceof Error ? error : new Error("Invalid SOAP destination"));
+        return;
+      }
+      const transport = target.protocol === "https:" ? requestHttps : requestHttp;
+      const request = transport(target, {
+        method: "POST",
+        headers: Object.fromEntries(Object.entries(headers).map(([name, value]) => [name, String(value)])),
+        signal: options.signal instanceof AbortSignal ? options.signal : undefined,
+      }, (response) => this.#receive(response, body, succeed, fail, request));
+      deadline = setTimeout(() => fail(new Error("SOAP request timed out"), request), 1_500);
+      request.once("error", (error) => fail(error, request));
+      request.end(body);
+    });
+    return pending as ReturnType<IHttpClient["request"]>;
+  }
+
+  #receive(
+    response: IncomingMessage,
+    requestBody: Buffer,
+    succeed: (result: object, body: string) => void,
+    fail: (error: Error, request?: ClientRequest) => void,
+    request: ClientRequest,
+  ) {
+    const status = response.statusCode ?? 500;
+    if (status < 200 || status >= 300) {
+      fail(new Error(
+        status >= 300 && status < 400 ? "SOAP redirects are blocked" : "SOAP request failed",
+      ), request);
+      return;
+    }
+    const chunks: Buffer[] = [];
+    let bytes = 0;
+    response.on("data", (chunk: Buffer) => {
+      bytes += chunk.byteLength;
+      if (bytes > maximumSoapBytes) fail(new Error("SOAP response too large"), request);
+      else chunks.push(chunk);
+    });
+    response.once("error", (error) => fail(error, request));
+    response.once("end", () => {
+      if (bytes > maximumSoapBytes) return;
+      const body = Buffer.concat(chunks).toString("utf8");
+      const validation = this.#validation.then(() => this.#validate(body));
+      this.#validation = validation.catch(() => {});
+      void validation.then(() => {
+        const result = {
+          config: { data: requestBody, headers: {} },
+          data: body,
+          headers: response.headers,
+          status: response.statusCode ?? 500,
+          statusText: response.statusMessage ?? "",
+        };
+        succeed(result, body);
+      }, (error: unknown) => fail(error instanceof Error ? error : new Error("Invalid SOAP response"), request));
+    });
+  }
+
+  #validate(source: string) {
+    if (/<!DOCTYPE|<!ENTITY/i.test(source)) throw new Error("DTD and entity declarations are blocked");
+    const document = parseXml(source, {
+      expandDtdEntities: false,
+      maxAttributes: 32,
+      maxDepth: 32,
+      maxNodeCount: 256,
+      maxTextLength: 8_192,
+    });
+    if (!validate(document, this.#schema.envelope, { mode: "strict" }).valid) {
+      throw new Error("SOAP response failed XSD validation");
+    }
+    const response = document.root?.getChild("Body")?.getChild("GetPeaResponse");
+    if (!response || !validateSubtree(response, this.#schema.service, { mode: "strict" }).valid) {
+      throw new Error("SOAP response failed XSD validation");
+    }
+  }
+}

package/initializer-dist/template/test/server.test.mjs

@@ -0,0 +1,250 @@
+import assert from "node:assert/strict";
+import { readFile } from "node:fs/promises";
+import test from "node:test";
+
+import { startMcpServer } from "@emseepea/testing";
+import { createSoapExample } from "../dist/app.js";
+import { artifactsFromSources } from "../scripts/generate-types.mjs";
+import { parseSoapEnvelopeSchema } from "../dist/soap-schema.js";
+import { maximumSoapBytes, ValidatingHttpClient } from "../dist/validating-http-client.js";
+import { startSoapFixture } from "../test-support/soap-fixture.mjs";
+
+const invalidSoapResponses = [
+  "Invalid XML",
+  "Invalid XSD",
+  "Zero Days",
+  "Negative Days",
+  "Fractional Days",
+  "Empty Type",
+  "Long Type",
+  "Too Many Traits",
+  "Missing Required Field",
+  "Wrong Namespace",
+  "DTD",
+  "Entity",
+  "Too Deep",
+  "Too Many Nodes",
+  "Too Many Attributes",
+  "Text Too Long",
+  "Oversized",
+];
+const resourceLimitFailures = new Map([
+  ["Too Deep", /nesting depth \(32\) exceeded/],
+  ["Too Many Nodes", /node count exceeds limit \(256\)/],
+  ["Too Many Attributes", /Too many attributes.+limit: 32/],
+  ["Text Too Long", /Text node exceeds maximum allowed length.+8192/],
+  ["Oversized", /SOAP response too large/],
+]);
+
+test("retrieves XSD-validated SOAP data through a described MCP schema", async (t) => {
+  const fixture = await startSoapFixture(t);
+  const running = await startMcpServer(t, new URL("../dist/server.js", import.meta.url), {
+    environment: { PEA_SOAP_URL: fixture.url.href },
+  });
+  const client = await running.connect();
+  const { tools } = await client.listTools();
+  assert.deepEqual(tools.map(({ name }) => name), ["get-pea-variety"]);
+  const [tool] = tools;
+  assert.equal(tool.inputSchema.properties.name.description, "Name of the pea variety to retrieve.");
+  for (const property of ["name", "peaType", "daysToMaturity", "note", "traits"]) {
+    assert.ok(tool.outputSchema.properties[property].description);
+  }
+  assert.equal(tool.outputSchema.properties.traits.maxItems, 5);
+
+  const result = await client.callTool({ name: "get-pea-variety", arguments: { name: "Sugar Ann" } });
+  assert.equal(result.isError, false);
+  assert.deepEqual(result.structuredContent, {
+    name: "Sugar Ann",
+    peaType: "snap",
+    daysToMaturity: 56,
+    note: "Compact plants with edible pods.",
+    traits: ["bush", "early"],
+  });
+  assert.equal(fixture.requests, 1);
+  assert.equal(fixture.lastRequest.method, "POST");
+  assert.equal(fixture.lastRequest.path, "/soap");
+  assert.match(fixture.lastRequest.soapAction, /GetPea/);
+  assert.match(fixture.lastRequest.body, /<(?:\w+:)?GetPeaRequest(?:\s|>)/);
+  assert.match(fixture.lastRequest.body, /<(?:\w+:)?name>Sugar Ann<\/(?:\w+:)?name>/);
+
+  const zeroTraits = await client.callTool({
+    name: "get-pea-variety",
+    arguments: { name: "Boundary Zero Traits" },
+  });
+  assert.deepEqual(zeroTraits.structuredContent, {
+    name: "Boundary Zero Traits",
+    peaType: "x",
+    daysToMaturity: 1,
+    traits: [],
+  });
+
+  const fiveTraits = await client.callTool({
+    name: "get-pea-variety",
+    arguments: { name: "Boundary Five Traits" },
+  });
+  assert.deepEqual(fiveTraits.structuredContent, {
+    name: "Boundary Five Traits",
+    peaType: "x".repeat(40),
+    daysToMaturity: 1,
+    traits: ["1", "2", "3", "4", "5"],
+  });
+});
+
+test("rejects unsafe and invalid SOAP responses with generic public failures", async (t) => {
+  const fixture = await startSoapFixture(t);
+  const running = await startMcpServer(t, new URL("../dist/server.js", import.meta.url), {
+    environment: { PEA_SOAP_URL: fixture.url.href },
+  });
+  const client = await running.connect();
+  for (const name of [
+    "SOAP Fault",
+    ...invalidSoapResponses,
+    "Valid Error Status",
+    "Redirect",
+    "Timeout",
+    "Trickle",
+  ]) {
+    const result = await client.callTool({ name: "get-pea-variety", arguments: { name } });
+    assert.equal(result.isError, true, name);
+    assert.equal(result.content[0].text, "Tool execution failed", name);
+    assert.doesNotMatch(JSON.stringify(result), /Private fixture detail|DOCTYPE|ENTITY|example\.com|ECONN/i, name);
+  }
+});
+
+test("invalid responses stop before the SOAP parser callback and mapper", async (t) => {
+  const fixture = await startSoapFixture(t);
+  const { schema } = await schemaSources();
+  const client = new ValidatingHttpClient(fixture.url, schema);
+  for (const name of invalidSoapResponses) {
+    const delivered = await rawTransportCall(client, fixture.url.href, name);
+    assert.ok(delivered.error instanceof Error, name);
+    if (resourceLimitFailures.has(name)) {
+      assert.match(delivered.error.message, resourceLimitFailures.get(name), name);
+    }
+    assert.equal(delivered.result, undefined, name);
+    assert.equal(delivered.body, undefined, name);
+  }
+});
+
+test("the transport blocks a different destination before sending", async (t) => {
+  const fixture = await startSoapFixture(t);
+  const { schema } = await schemaSources();
+  const client = new ValidatingHttpClient(fixture.url, schema);
+  const before = fixture.requests;
+  const error = await new Promise((resolve) => {
+    client.request("http://example.com/soap", "<request/>", (failure) => resolve(failure));
+  });
+  assert.ok(error instanceof Error);
+  assert.equal(fixture.requests, before);
+  await assert.rejects(createSoapExample("ftp://example.com/soap"));
+});
+
+test("the transport enforces an absolute deadline even while bytes arrive", { timeout: 3_000 }, async (t) => {
+  const fixture = await startSoapFixture(t);
+  const { schema } = await schemaSources();
+  const started = performance.now();
+  const delivered = await rawTransportCall(
+    new ValidatingHttpClient(fixture.url, schema),
+    fixture.url.href,
+    "Trickle",
+  );
+  assert.ok(delivered.error instanceof Error);
+  assert.match(delivered.error.message, /timed out/);
+  assert.ok(performance.now() - started < 2_000);
+  assert.equal(delivered.body, undefined);
+});
+
+test("schema loading is local-only and generated artefacts preserve their contract layers", async () => {
+  const { envelope, service } = await schemaSources();
+  await assert.rejects(parseSoapEnvelopeSchema(
+    envelope.replace("pea-service.xsd", "https://example.com/remote.xsd"),
+    service,
+  ));
+  const generated = await readFile(new URL("../src/generated/pea-service.ts", import.meta.url), "utf8");
+  assert.match(generated, /name: string;/);
+  assert.match(generated, /daysToMaturity: number;/);
+  assert.match(generated, /note\?: string;/);
+  assert.match(generated, /trait\?: string\[\];/);
+  const mapperType = generated.match(/export interface PeaVariety \{[\s\S]*?\n\}/)?.[0] ?? "";
+  assert.doesNotMatch(mapperType, /unknown/);
+  const model = JSON.parse(await readFile(
+    new URL("../src/generated/pea-service.schema-model.json", import.meta.url),
+    "utf8",
+  ));
+  assert.deepEqual(model.simpleTypes["{urn:emseepea:pea-service}PeaType"].facets, [
+    { kind: "minLength", value: "1" },
+    { kind: "maxLength", value: "40" },
+  ]);
+  const particles = model.complexTypes["{urn:emseepea:pea-service}PeaVariety"].particle.particles;
+  assert.deepEqual(particles.find(({ element }) => element === "trait").occurrence, { min: 0, max: 5 });
+});
+
+test("the response cap is below the total network ceiling", () => {
+  assert.equal(maximumSoapBytes, 64 * 1_024);
+  assert.equal(maximumSoapBytes * 2, 128 * 1_024);
+});
+
+test("an oversized request is rejected before the fixture receives it", async (t) => {
+  const fixture = await startSoapFixture(t);
+  const { schema } = await schemaSources();
+  const before = fixture.requests;
+  const delivered = await new Promise((resolve) => {
+    new ValidatingHttpClient(fixture.url, schema).request(
+      fixture.url.href,
+      "x".repeat(maximumSoapBytes + 1),
+      (error, result, body) => resolve({ error, result, body }),
+    );
+  });
+  assert.ok(delivered.error instanceof Error);
+  assert.match(delivered.error.message, /SOAP request too large/);
+  assert.equal(delivered.result, undefined);
+  assert.equal(delivered.body, undefined);
+  assert.equal(fixture.requests, before);
+});
+
+test("primitive and facet XSD changes affect the correct generated and runtime layers", async (t) => {
+  const fixture = await startSoapFixture(t);
+  const { envelope, service } = await schemaSources();
+  const original = await artifactsFromSources(envelope, service);
+
+  const primitiveService = service.replace('type="xs:positiveInteger"', 'type="xs:string"');
+  const primitive = await artifactsFromSources(envelope, primitiveService);
+  assert.match(original.types, /daysToMaturity: number;/);
+  assert.match(primitive.types, /daysToMaturity: string;/);
+  const primitiveTransport = new ValidatingHttpClient(
+    fixture.url,
+    await parseSoapEnvelopeSchema(envelope, primitiveService),
+  );
+  const primitiveResult = await rawTransportCall(primitiveTransport, fixture.url.href, "Invalid XSD");
+  assert.equal(primitiveResult.error, null);
+  assert.ok(primitiveResult.body);
+
+  const facetService = service.replace('<xs:maxLength value="40"/>', '<xs:maxLength value="3"/>');
+  const facet = await artifactsFromSources(envelope, facetService);
+  assert.equal(facet.types, original.types);
+  assert.notEqual(facet.model, original.model);
+  const facetTransport = new ValidatingHttpClient(
+    fixture.url,
+    await parseSoapEnvelopeSchema(envelope, facetService),
+  );
+  const facetResult = await rawTransportCall(facetTransport, fixture.url.href, "Facet Mutation");
+  assert.ok(facetResult.error instanceof Error);
+  assert.equal(facetResult.body, undefined);
+});
+
+async function schemaSources() {
+  const envelope = await readFile(new URL("../contracts/soap-envelope.xsd", import.meta.url), "utf8");
+  const service = await readFile(new URL("../contracts/pea-service.xsd", import.meta.url), "utf8");
+  return {
+    envelope,
+    service,
+    schema: await parseSoapEnvelopeSchema(envelope, service),
+  };
+}
+
+function rawTransportCall(client, url, name) {
+  const request = `<GetPeaRequest><name>${name}</name></GetPeaRequest>`;
+  return new Promise((resolve) => {
+    client.request(url, request, (error, result, body) => resolve({ error, result, body }));
+  });
+}