tessl/npm-soap
A minimal node SOAP client and server implementation for Node.js applications
—
Pending
security.mddocs/
Security
Comprehensive security system supporting multiple authentication mechanisms for enterprise SOAP integration, including HTTP authentication, SSL certificates, and WS-Security standards.
Capabilities
Basic Authentication
HTTP Basic Authentication using username and password credentials.
/**
* HTTP Basic Authentication security handler
* @param username - Username for authentication
* @param password - Password for authentication
* @param defaults - Optional default options
*/
class BasicAuthSecurity implements ISecurity {
constructor(username: string, password: string, defaults?: any);
addOptions?(options: any): void;
toXML?(): string;
addHeaders?(headers: IHeaders): void;
postProcess?(xml: any, envelopeKey: any): string;
}Usage Examples:
import { createClientAsync, BasicAuthSecurity } from "soap";
const client = await createClientAsync("http://example.com/service.wsdl");
// Set Basic Auth security
const basicAuth = new BasicAuthSecurity("username", "password");
client.setSecurity(basicAuth);
// All subsequent requests will include Basic Auth header
const result = await client.SomeMethodAsync({ param: "value" });Bearer Token Authentication
Bearer token authentication for OAuth and API key scenarios.
/**
* Bearer Token authentication security handler
* @param token - Bearer token string
* @param defaults - Optional default options
*/
class BearerSecurity implements ISecurity {
constructor(token: string, defaults?: any);
addOptions?(options: any): void;
toXML?(): string;
addHeaders?(headers: IHeaders): void;
postProcess?(xml: any, envelopeKey: any): string;
}Usage Examples:
import { BearerSecurity } from "soap";
// Using OAuth token
const bearerAuth = new BearerSecurity("your-oauth-token-here");
client.setSecurity(bearerAuth);
// Using API key as bearer token
const apiKeyAuth = new BearerSecurity("api-key-12345");
client.setSecurity(apiKeyAuth);SSL Client Certificate Authentication
SSL client certificate authentication using PEM format certificates.
/**
* SSL Client Certificate (PEM) authentication security handler
* @param key - Private key in PEM format
* @param cert - Certificate in PEM format
* @param ca - Certificate Authority certificate (optional)
* @param defaults - Optional default options
*/
class ClientSSLSecurity implements ISecurity {
constructor(key: string | Buffer, cert: string | Buffer, ca?: string | Buffer | Array<string | Buffer>, defaults?: any);
addOptions?(options: any): void;
toXML?(): string;
addHeaders?(headers: IHeaders): void;
postProcess?(xml: any, envelopeKey: any): string;
}Usage Examples:
import { ClientSSLSecurity } from "soap";
import * as fs from "fs";
// Load certificate files
const key = fs.readFileSync("client-key.pem");
const cert = fs.readFileSync("client-cert.pem");
const ca = fs.readFileSync("ca-cert.pem");
const sslSecurity = new ClientSSLSecurity(key, cert, ca);
client.setSecurity(sslSecurity);SSL Client Certificate Authentication (PFX)
SSL client certificate authentication using PFX/PKCS#12 format certificates.
/**
* SSL Client Certificate (PFX) authentication security handler
* @param pfx - PFX certificate data
* @param passphrase - Passphrase for PFX certificate
* @param defaults - Optional default options
*/
class ClientSSLSecurityPFX implements ISecurity {
constructor(pfx: string | Buffer, passphrase: string, defaults?: any);
addOptions?(options: any): void;
toXML?(): string;
addHeaders?(headers: IHeaders): void;
postProcess?(xml: any, envelopeKey: any): string;
}Usage Examples:
import { ClientSSLSecurityPFX } from "soap";
import * as fs from "fs";
const pfxData = fs.readFileSync("client-cert.pfx");
const pfxSecurity = new ClientSSLSecurityPFX(pfxData, "certificate-password");
client.setSecurity(pfxSecurity);WS-Security Username Token
WS-Security Username Token authentication with digest or plaintext password.
/**
* WS-Security Username Token authentication security handler
* @param username - Username for authentication
* @param password - Password for authentication
* @param options - WS-Security options (can be string for password type or full options object)
*/
class WSSecurity implements ISecurity {
constructor(username: string, password: string, options?: string | IWSSecurityOptions);
toXML(): string;
}
interface IWSSecurityOptions {
/** Password type: 'PasswordDigest' or 'PasswordText' */
passwordType?: string;
/** Whether to add timestamps */
hasTimeStamp?: boolean;
/** Whether to add nonce */
hasNonce?: boolean;
/** Whether to add token creation time */
hasTokenCreated?: boolean;
/** Actor attribute for SOAP 1.1 */
actor?: string;
/** mustUnderstand attribute */
mustUnderstand?: any;
/** Envelope key for SOAP envelope */
envelopeKey?: string;
}Usage Examples:
import { WSSecurity } from "soap";
// Basic WS-Security with password digest
const wsSecurity = new WSSecurity("username", "password", {
passwordType: 'PasswordDigest',
hasTimeStamp: true,
hasNonce: true
});
client.setSecurity(wsSecurity);
// WS-Security with plaintext password
const wsSecurityPlain = new WSSecurity("username", "password", {
passwordType: 'PasswordText'
});
client.setSecurity(wsSecurityPlain);WS-Security with X.509 Certificate
WS-Security authentication using X.509 certificates for message signing.
/**
* WS-Security with X.509 Certificate authentication security handler
* @param privatePEM - Private key in PEM format
* @param publicP12PEM - Public certificate in PEM format
* @param password - Certificate password
* @param options - Certificate security options
*/
class WSSecurityCert implements ISecurity {
constructor(privatePEM: any, publicP12PEM: any, password: any, options?: IWSSecurityCertOptions);
postProcess(xml: string, envelopeKey: string): string;
}
interface IWSSecurityCertOptions {
/** Whether to add timestamps */
hasTimeStamp?: boolean;
/** Signature transformation algorithms */
signatureTransformations?: string[];
/** Signature algorithm */
signatureAlgorithm?: string;
/** Digest algorithm */
digestAlgorithm?: string;
/** Additional references to sign */
additionalReferences?: string[];
/** XML signer options */
signerOptions?: IXmlSignerOptions;
/** References to exclude from signing */
excludeReferencesFromSigning?: string[];
}
interface IXmlSignerOptions {
/** XML signature prefix */
prefix?: string;
/** Additional attributes */
attrs?: { [key: string]: string };
/** Existing namespace prefixes */
existingPrefixes?: { [key: string]: string };
/** ID mode for WS-Security */
idMode?: 'wssecurity';
}Usage Examples:
import { WSSecurityCert } from "soap";
import * as fs from "fs";
const privateKey = fs.readFileSync("private-key.pem");
const publicCert = fs.readFileSync("public-cert.pem");
const certSecurity = new WSSecurityCert(privateKey, publicCert, "cert-password");
client.setSecurity(certSecurity);WS-Security Certificate with Token
Combined WS-Security implementation with both certificate and username token.
/**
* WS-Security combining certificate and username token
* @param privatePEM - Private key in PEM format
* @param publicP12PEM - Public certificate in PEM format
* @param password - Certificate password
* @param options - Security configuration options
*/
class WSSecurityCertWithToken implements ISecurity {
constructor(privatePEM: string | Buffer, publicP12PEM: string | Buffer, password: string, options?: any);
addOptions?(options: any): void;
toXML?(): string;
addHeaders?(headers: IHeaders): void;
postProcess?(xml: any, envelopeKey: any): string;
}Enhanced WS-Security
Enhanced WS-Security implementation with additional cryptographic features.
/**
* Enhanced WS-Security with advanced certificate handling
* @param privatePEM - Private key in PEM format
* @param publicP12PEM - Public certificate in PEM format
* @param password - Certificate password
* @param options - Advanced security options
*/
class WSSecurityPlusCert implements ISecurity {
constructor(privatePEM: string | Buffer, publicP12PEM: string | Buffer, password: string, options?: any);
addOptions?(options: any): void;
toXML?(): string;
addHeaders?(headers: IHeaders): void;
postProcess?(xml: any, envelopeKey: any): string;
}NTLM Authentication
NTLM (NT LAN Manager) authentication for Windows-based SOAP services.
/**
* NTLM authentication security handler
* @param username - Windows username
* @param password - Windows password
* @param domain - Windows domain (optional)
* @param workstation - Workstation name (optional)
*/
class NTLMSecurity implements ISecurity {
constructor(username: string, password: string, domain?: string, workstation?: string);
addOptions?(options: any): void;
toXML?(): string;
addHeaders?(headers: IHeaders): void;
postProcess?(xml: any, envelopeKey: any): string;
}Usage Examples:
import { NTLMSecurity } from "soap";
// NTLM with domain
const ntlmSecurity = new NTLMSecurity("username", "password", "DOMAIN");
client.setSecurity(ntlmSecurity);
// NTLM without domain
const ntlmLocal = new NTLMSecurity("username", "password");
client.setSecurity(ntlmLocal);Security Interface
All security implementations follow a common interface for consistent integration.
/**
* Common interface for all security handlers
*/
interface ISecurity {
/** Add security-specific options to HTTP request */
addOptions?(options: any): void;
/** Generate security XML for SOAP header */
toXML?(): string;
/** Add security-specific HTTP headers */
addHeaders?(headers: IHeaders): void;
/** Post-process SOAP envelope with security information */
postProcess?(xml: any, envelopeKey: any): string;
}
interface IHeaders {
[key: string]: any;
}Utility Functions
Password Digest Generation
Generate WS-Security password digests for username token authentication.
/**
* Generate WS-Security password digest
* @param nonce - Random nonce value (base64 encoded)
* @param created - Timestamp when token was created (ISO 8601)
* @param password - Plaintext password
* @returns Base64 encoded password digest
*/
function passwordDigest(nonce: string, created: string, password: string): string;Usage Examples:
import { passwordDigest } from "soap";
const nonce = Buffer.from(Math.random().toString()).toString('base64');
const created = new Date().toISOString();
const digest = passwordDigest(nonce, created, "mypassword");
console.log('Password Digest:', digest);
// Manual digest calculation for custom WS-Security implementations
const customNonce = Buffer.from('random-nonce-value').toString('base64');
const customCreated = new Date().toISOString();
const customDigest = passwordDigest(customNonce, customCreated, "secretpassword");
// Use in custom security header
const customSecurityHeader = {
'wsse:UsernameToken': {
'wsse:Username': 'myuser',
'wsse:Password': {
$: { Type: 'http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordDigest' },
_: customDigest
},
'wsse:Nonce': { $: { EncodingType: 'http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#Base64Binary' }, _: customNonce },
'wsu:Created': customCreated
}
};Advanced Security Features
Custom Security Handlers
Create custom security implementations by implementing the ISecurity interface.
class CustomSecurity implements ISecurity {
constructor(private apiKey: string) {}
addHeaders(headers: IHeaders): void {
headers['X-API-Key'] = this.apiKey;
headers['X-Custom-Auth'] = 'custom-token';
}
addOptions(options: any): void {
// Add custom HTTP options
options.timeout = 30000;
}
}
// Use custom security
const customSecurity = new CustomSecurity("api-key-123");
client.setSecurity(customSecurity);Multiple Security Layers
Combine multiple security mechanisms by chaining security handlers.
// Note: Only one security handler can be active at a time per client
// For multiple security requirements, implement a composite security handler
class CompositeSecurity implements ISecurity {
constructor(
private basicAuth: BasicAuthSecurity,
private customHeaders: any
) {}
addHeaders(headers: IHeaders): void {
this.basicAuth.addHeaders?.(headers);
Object.assign(headers, this.customHeaders);
}
addOptions(options: any): void {
this.basicAuth.addOptions?.(options);
}
}Install with Tessl CLI
npx tessl i tessl/npm-soap