@techspokes/typescript-wsdl-client 0.18.0 → 0.20.0

package/docs/configuration.md

@@ -8,28 +8,43 @@ See [CLI Reference](cli-reference.md) for flag details and [README](../README.md
 
 Pass via `--openapi-security-config-file`.
 
-Defines security schemes, headers, and per-operation overrides.
+Defines REST gateway security, request headers, and upstream SOAP security. The `gateway` section describes the generated REST API in OpenAPI and adds Fastify header validation. The `upstream` section is used by the generated app scaffold to build `node-soap` runtime options from environment variables.
 
 ```json
 {
-  "global": {
-    "scheme": "bearer",
-    "bearer": { "bearerFormat": "JWT" },
-    "headers": [
-      {
-        "name": "X-Correlation-Id",
-        "required": false,
-        "schema": { "type": "string" }
-      }
-    ]
+  "gateway": {
+    "global": {
+      "scheme": "bearer",
+      "bearer": { "bearerFormat": "JWT" },
+      "headers": [
+        {
+          "name": "X-Correlation-Id",
+          "required": false,
+          "schema": { "type": "string" }
+        }
+      ]
+    },
+    "operations": {
+      "CancelBooking": { "scheme": "apiKey" },
+      "HealthCheck": { "scheme": "none" }
+    }
   },
-  "overrides": {
-    "CancelBooking": { "scheme": "apiKey" }
+  "upstream": {
+    "profile": "ws-security-username-token",
+    "usernameEnv": "SOAP_USERNAME",
+    "passwordEnv": "SOAP_PASSWORD",
+    "endpointEnv": "SOAP_ENDPOINT"
   }
 }
 ```
 
-Supported schemes: none, basic, bearer, apiKey, oauth2.
+Gateway schemes: none, basic, bearer, apiKey, oauth2, mutualTLS, openIdConnect.
+
+Upstream SOAP profiles: none, basic, bearer, ws-security-username-token, client-ssl, client-ssl-pfx, x509, ntlm, custom.
+
+The older OpenAPI-only shape with top-level `global` and `overrides` is still accepted. New projects should use `gateway.global` and `gateway.operations`.
+
+The generated app scaffold reads upstream secrets from environment variables. It does not embed secret values in generated source and does not implement production JWT, OAuth, or API-key verification for inbound gateway requests. Add that verification in app hooks or your platform gateway.
 
 ## Tags Configuration
 
@@ -107,8 +122,8 @@ terminal-error policy.
 
 ## Example Files
 
-Example configuration files are available in the `examples/openapi/` directory:
+Example configuration files are available in the `examples/config/` directory:
 
-- `examples/openapi/security.json` for security scheme configuration
-- `examples/openapi/tags.json` for tag mapping
-- `examples/openapi/ops.json` for operation overrides
+- `examples/config/security.json` for gateway and upstream security configuration
+- `examples/config/tags.json` for tag mapping
+- `examples/config/ops.json` for operation overrides

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/releases/README.md

@@ -0,0 +1,42 @@
+# Release Notes
+
+Add one Markdown file per release tag. The draft release workflow requires this file before it creates or updates a GitHub draft release.
+
+## File Naming
+
+Use the Git tag as the filename:
+
+```text
+vX.Y.Z.md
+```
+
+For example, release `0.20.1` uses tag `v0.20.1` and release notes file `docs/releases/v0.20.1.md`.
+
+## File Structure
+
+Each release notes file must use this structure:
+
+```markdown
+# TypeScript WSDL Client vX.Y.Z
+
+Short summary paragraph.
+
+## Highlights
+
+- User-facing release highlight.
+
+## Upgrade Notes
+
+No special upgrade steps.
+
+## Validation
+
+- `npm run maint:deps`
+- `npm run ci`
+
+## Notes
+
+Release tag: `vX.Y.Z`.
+```
+
+Write release notes for users and maintainers, not as a file-by-file change log. Use `CHANGELOG.md` for the canonical version history.

package/docs/releases/v0.20.0.md

@@ -0,0 +1,22 @@
+# TypeScript WSDL Client v0.20.0
+
+This release refreshes dependency minimums and adds a tag-driven draft release workflow so each GitHub release starts from a reviewed release notes document.
+
+## Highlights
+
+- Bump root and generated app dependency minimums for `@types/node`, `soap`, and `tsx`.
+- Add a `vX.Y.Z` tag workflow that validates the release state and creates or updates a GitHub draft release from `docs/releases/vX.Y.Z.md`.
+- Require release notes in agent and contributor guidance so the changelog, package version, tag, and release description stay synchronized.
+
+## Upgrade Notes
+
+No special upgrade steps.
+
+## Validation
+
+- `npm run maint:deps`
+- `npm run ci`
+
+## Notes
+
+Release tag: `v0.20.0`.

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.20.0",
   "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",
@@ -83,12 +83,12 @@
   },
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",
-    "@types/node": "^25.7.0",
+    "@types/node": "^25.9.0",
     "@types/yargs": "^17.0.35",
     "fastify": "^5.8.5",
     "fastify-plugin": "^5.1.0",
     "rimraf": "^6.1.3",
-    "tsx": "^4.21.0",
+    "tsx": "^4.22.2",
     "typescript": "^6.0.3",
     "vitest": "^4.1.6"
   },
@@ -97,7 +97,7 @@
     "fast-xml-parser": "^5.8.0",
     "js-yaml": "^4.1.1",
     "saxes": "^6.0.0",
-    "soap": "^1.9.1",
+    "soap": "^1.9.2",
     "yargs": "^18.0.0"
   },
   "funding": {

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));
+}