@techspokes/typescript-wsdl-client 0.18.0 → 0.19.2

package/docs/gateway-guide.md

@@ -122,13 +122,13 @@ terminating zero-chunk.
 
 The centralized error handler (runtime.ts) automatically classifies errors:
 
-| Error Type | HTTP Status | Error Code |
-|------------|-------------|------------|
-| Validation errors | 400 | VALIDATION_ERROR |
-| SOAP faults | 502 | SOAP_FAULT |
-| Connection refused | 503 | SERVICE_UNAVAILABLE |
-| Timeout | 504 | GATEWAY_TIMEOUT |
-| Other errors | 500 | INTERNAL_ERROR |
+| Error Type         | HTTP Status | Error Code          |
+|--------------------|-------------|---------------------|
+| Validation errors  | 400         | VALIDATION_ERROR    |
+| SOAP faults        | 502         | SOAP_FAULT          |
+| Connection refused | 503         | SERVICE_UNAVAILABLE |
+| Timeout            | 504         | GATEWAY_TIMEOUT     |
+| Other errors       | 500         | INTERNAL_ERROR      |
 
 All errors are wrapped in the standard envelope format. See [Concepts](concepts.md) for the envelope structure.
 
@@ -186,7 +186,7 @@ await app.register(async (scope) => {
 await app.listen({ port: 3000 });
 ```
 
-See [`examples/fastify-gateway/`](../examples/fastify-gateway/) for a complete example.
+See [`examples/fastify-gateway`](../examples/fastify-gateway/README.md) for a complete example.
 
 ## Contract Assumptions
 

package/docs/generated-code.md

@@ -18,6 +18,13 @@ const client = new Weather({
 
 The `source` parameter accepts a URL or local file path to the WSDL.
 
+When generating a runnable app with a security config, the scaffold can create
+`security.ts` to build `soap.IOptions` and `soap.ISecurity` from environment
+variables. The generated helper supports common `node-soap` profiles such as
+Basic auth, bearer auth, WS-Security UsernameToken, TLS client certificates,
+X509 signing, and NTLM. Secrets are read at runtime and are not embedded in
+generated source.
+
 ## Calling Operations
 
 ```typescript

package/docs/migration-playbook.md

@@ -126,9 +126,16 @@ Create a security configuration file to add authentication to the OpenAPI spec a
 
 ```json
 {
-  "global": {
-    "scheme": "bearer",
-    "bearer": { "bearerFormat": "JWT" }
+  "gateway": {
+    "global": {
+      "scheme": "bearer",
+      "bearer": { "bearerFormat": "JWT" }
+    }
+  },
+  "upstream": {
+    "profile": "ws-security-username-token",
+    "usernameEnv": "SOAP_USERNAME",
+    "passwordEnv": "SOAP_PASSWORD"
   }
 }
 ```
@@ -142,11 +149,13 @@ npx wsdl-tsc pipeline \
   ...
 ```
 
-See [Configuration](configuration.md) for all options including per-operation overrides and custom headers.
+See [Configuration](configuration.md) for all options including per-operation overrides, custom headers, and upstream SOAP security profiles.
 
 ### Custom middleware
 
-Add middleware in your application code, not in the generated gateway files. The generated app scaffold (`index.ts`) is the right place for auth verification, logging, CORS, and other cross-cutting concerns.
+Add middleware in your application code, not in the generated gateway files. The generated app scaffold (`server.ts`) is the right place for auth verification, logging, CORS, and other cross-cutting concerns.
+
+The security config describes gateway authentication in OpenAPI and can scaffold upstream SOAP credentials for `node-soap`. It does not validate JWTs, OAuth tokens, or API keys for inbound REST requests. Use Fastify hooks, platform middleware, or your API gateway for that enforcement.
 
 ```typescript
 import Fastify from "fastify";

package/docs/troubleshooting.md

@@ -12,7 +12,7 @@ See [README](../README.md) for quick start and [CLI Reference](cli-reference.md)
 | Unresolved type references | Re-run with --client-fail-on-unresolved=false to inspect partial graph |
 | Missing schema in OpenAPI | Ensure the global element exists (catalog shows compiled symbols) |
 | Wrong array modeling | Check maxOccurs in WSDL; tool only arrays when maxOccurs>1 or unbounded |
-| Authentication errors | Provide proper soap.ISecurity instance (WSSecurity, BasicAuthSecurity) |
+| Authentication errors | Provide proper upstream security config or `soap.ISecurity` instance |
 | Date/time confusion | Use --client-date-as Date for runtime Date objects |
 | TypeScript compilation errors | Check --import-extensions matches your tsconfig moduleResolution |
 | Gateway validation failures | Ensure OpenAPI has valid $ref paths and all schemas in components.schemas |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@techspokes/typescript-wsdl-client",
-  "version": "0.18.0",
+  "version": "0.19.2",
   "description": "Turn legacy WSDL/SOAP services into typed TypeScript clients, OpenAPI 3.1 specs, and production-ready Fastify REST gateways. Built for enterprise SOAP modernization.",
   "keywords": [
     "wsdl",

package/src/runtime/appSecurity.tpl.txt

@@ -0,0 +1,108 @@
+/**
+ * Upstream SOAP Security
+ *
+ * Builds node-soap runtime options from environment variables referenced by
+ * the generation-time security config. Secrets are intentionally read at
+ * runtime and are never embedded in generated source.
+ *
+ * Scaffolded by wsdl-tsc. Customize freely.
+ */
+import fs from "node:fs";
+import soap from "soap";
+
+const upstream: any = __UPSTREAM_JSON__;
+
+export interface SoapRuntimeConfig {
+  options?: soap.IOptions;
+  security?: soap.ISecurity;
+}
+
+export function buildSoapRuntimeConfig(): SoapRuntimeConfig {
+  const options: soap.IOptions = {};
+  const wsdlHeaders = buildHeaders(upstream.wsdlHeaders, upstream.wsdlHeaderEnv);
+  if (Object.keys(wsdlHeaders).length) {
+    options.wsdl_headers = wsdlHeaders;
+  }
+  const requestHeaders = buildHeaders(upstream.requestHeaders, upstream.requestHeaderEnv);
+  if (Object.keys(requestHeaders).length) {
+    options.extraHeaders = requestHeaders;
+  }
+  if (upstream.endpointEnv) {
+    const endpoint = process.env[upstream.endpointEnv];
+    if (endpoint) options.endpoint = endpoint;
+  }
+
+  const security = buildSoapSecurity();
+  return {
+    ...(Object.keys(options).length ? { options } : {}),
+    ...(security ? { security } : {}),
+  };
+}
+
+function buildSoapSecurity(): soap.ISecurity | undefined {
+  const soapRuntime = soap as any;
+  switch (upstream.profile ?? "none") {
+    case "none":
+      return undefined;
+    case "basic":
+      return new soapRuntime.BasicAuthSecurity(requiredEnv(upstream.usernameEnv, "upstream.usernameEnv"), requiredEnv(upstream.passwordEnv, "upstream.passwordEnv"));
+    case "bearer":
+      return new soapRuntime.BearerSecurity(requiredEnv(upstream.tokenEnv, "upstream.tokenEnv"));
+    case "ws-security-username-token":
+      return new soapRuntime.WSSecurity(
+        requiredEnv(upstream.usernameEnv, "upstream.usernameEnv"),
+        requiredEnv(upstream.passwordEnv, "upstream.passwordEnv"),
+        upstream.wsSecurity ?? {},
+      );
+    case "ntlm":
+      return new soapRuntime.NTLMSecurity({
+        username: requiredEnv(upstream.usernameEnv, "upstream.usernameEnv"),
+        password: requiredEnv(upstream.passwordEnv, "upstream.passwordEnv"),
+        domain: envValue(upstream.domainEnv),
+        workstation: envValue(upstream.workstationEnv),
+      });
+    case "client-ssl":
+      return new soapRuntime.ClientSSLSecurity(
+        readFileFromEnv(upstream.keyFileEnv, "upstream.keyFileEnv"),
+        readFileFromEnv(upstream.certFileEnv, "upstream.certFileEnv"),
+        upstream.caFileEnv ? readFileFromEnv(upstream.caFileEnv, "upstream.caFileEnv") : undefined,
+      );
+    case "client-ssl-pfx":
+      return new soapRuntime.ClientSSLSecurityPFX(
+        readFileFromEnv(upstream.pfxFileEnv, "upstream.pfxFileEnv"),
+        envValue(upstream.passphraseEnv),
+      );
+    case "x509":
+      return new soapRuntime.WSSecurityCert(
+        readFileFromEnv(upstream.keyFileEnv, "upstream.keyFileEnv"),
+        readFileFromEnv(upstream.certFileEnv, "upstream.certFileEnv"),
+        envValue(upstream.passphraseEnv) ?? "",
+      );
+    case "custom":
+      throw new Error("upstream.profile=custom requires editing security.ts to return a soap.ISecurity implementation.");
+  }
+}
+
+function buildHeaders(staticHeaders?: Record<string, string>, envHeaders?: Record<string, string>): Record<string, string> {
+  const headers: Record<string, string> = {...(staticHeaders ?? {})};
+  for (const [headerName, envName] of Object.entries(envHeaders ?? {})) {
+    const value = process.env[envName];
+    if (value) headers[headerName] = value;
+  }
+  return headers;
+}
+
+function requiredEnv(envName: string | undefined, label: string): string {
+  if (!envName) throw new Error(`${label} must name an environment variable.`);
+  const value = process.env[envName];
+  if (!value) throw new Error(`${envName} environment variable is required for upstream SOAP security.`);
+  return value;
+}
+
+function envValue(envName: string | undefined): string | undefined {
+  return envName ? process.env[envName] : undefined;
+}
+
+function readFileFromEnv(envName: string | undefined, label: string): Buffer {
+  return fs.readFileSync(requiredEnv(envName, label));
+}