feat: add two-factor client certificate (mTLS) support for WebDAV (#94)

Add support for client certificates and SSL verification control for
WebDAV operations, enabling secure connections to instances that require
two-factor authentication.

New CLI flags:
- --certificate: Path to PKCS12 (.p12/.pfx) certificate file
- --passphrase: Passphrase for the certificate
- --selfsigned/--no-verify: Disable SSL certificate verification

Environment variables:
- SFCC_CERTIFICATE, SFCC_CERTIFICATE_PASSPHRASE, SFCC_SELFSIGNED

dw.json fields:
- certificate, certificate-passphrase, self-signed

Also adds 'server' and 'webdav-server' as dw.json field aliases for
consistency with CLI flag names.

Author: clavery

.changeset/two-factor-mtls-support.md

@@ -0,0 +1,18 @@
+---
+'@salesforce/b2c-tooling-sdk': minor
+'@salesforce/b2c-cli': minor
+---
+
+Add two-factor client certificate (mTLS) support for WebDAV operations
+
+New CLI flags for instance commands:
+- `--certificate <path>`: Path to PKCS12 (.p12/.pfx) certificate file
+- `--passphrase <string>`: Passphrase for the certificate
+- `--selfsigned`: Disable SSL certificate verification (for self-signed certs)
+- `--no-verify`: Alias for --selfsigned
+
+Environment variables: `SFCC_CERTIFICATE`, `SFCC_CERTIFICATE_PASSPHRASE`, `SFCC_SELFSIGNED`
+
+dw.json fields: `certificate`, `certificate-passphrase`, `self-signed`
+
+**SDK Note**: The `AuthStrategy.fetch` method signature changed from `RequestInit` to `FetchInit`. Custom `AuthStrategy` implementations should update their type annotations.

docs/guide/configuration.md

@@ -68,6 +68,9 @@ You can configure the CLI using environment variables:
 | `SFCC_AUTH_METHODS` | Comma-separated list of allowed auth methods |
 | `SFCC_OAUTH_SCOPES` | OAuth scopes to request |
 | `SFCC_CODE_VERSION` | Code version for deployments |
+| `SFCC_CERTIFICATE` | Path to PKCS12 certificate for two-factor auth (mTLS) |
+| `SFCC_CERTIFICATE_PASSPHRASE` | Passphrase for the certificate |
+| `SFCC_SELFSIGNED` | Allow self-signed server certificates |
 
 ## .env File
 
@@ -142,7 +145,7 @@ If no instance is specified, the config with `"active": true` is used.
 | Field | Description |
 |-------|-------------|
 | `hostname` | B2C instance hostname |
-| `webdav-hostname` | Separate hostname for WebDAV (if different from main hostname). Also accepts `secureHostname` or `secure-server`. |
+| `webdav-hostname` | Separate hostname for WebDAV (if different from main hostname). Also accepts `webdav-server`, `secureHostname`, or `secure-server`. |
 | `code-version` | Code version for deployments |
 | `client-id` | OAuth client ID |
 | `client-secret` | OAuth client secret |
@@ -151,6 +154,27 @@ If no instance is specified, the config with `"active": true` is used.
 | `oauth-scopes` | OAuth scopes (array of strings) |
 | `auth-methods` | Authentication methods in priority order (array of strings) |
 | `shortCode` | SCAPI short code. Also accepts `short-code` or `scapi-shortcode`. |
+| `certificate` | Path to PKCS12 certificate for two-factor auth (mTLS) |
+| `certificate-passphrase` | Passphrase for the certificate. Also accepts `passphrase`. |
+| `self-signed` | Allow self-signed server certificates. Also accepts `selfsigned`. |
+
+### Two-Factor Authentication (mTLS)
+
+For instances that require client certificate authentication:
+
+```json
+{
+  "hostname": "cert.staging.example.demandware.net",
+  "code-version": "version1",
+  "username": "your-username",
+  "password": "your-access-key",
+  "certificate": "/path/to/client-cert.p12",
+  "certificate-passphrase": "cert-password",
+  "self-signed": true
+}
+```
+
+The certificate must be in PKCS12 format (`.p12` or `.pfx`). The `self-signed` option is often needed for staging environments with internal certificates.
 
 ::: tip MRT Configuration
 Managed Runtime API key is not stored in `dw.json`. It is loaded from `~/.mobify`. You can specify `mrtProject` and `mrtEnvironment` in `dw.json` for project/environment selection.

packages/b2c-tooling-sdk/package.json

@@ -293,6 +293,7 @@
     "openapi-fetch": "^0.15.0",
     "pino": "^10.1.0",
     "pino-pretty": "^13.1.2",
+    "undici": "^7.0.0",
     "xml2js": "^0.6.2"
   }
 }

packages/b2c-tooling-sdk/src/auth/api-key.ts

@@ -3,7 +3,7 @@
  * SPDX-License-Identifier: Apache-2
  * For full license text, see the license.txt file in the repo root or http://www.apache.org/licenses/LICENSE-2.0
  */
-import type {AuthStrategy} from './types.js';
+import type {AuthStrategy, FetchInit} from './types.js';
 import {getLogger} from '../logging/logger.js';
 
 /**
@@ -40,10 +40,11 @@ export class ApiKeyStrategy implements AuthStrategy {
     logger.debug({headerName, keyPreview}, `[Auth] Using API Key authentication (${headerName}): ${keyPreview}`);
   }
 
-  async fetch(url: string, init: RequestInit = {}): Promise<Response> {
+  async fetch(url: string, init: FetchInit = {}): Promise<Response> {
     const headers = new Headers(init.headers);
     headers.set(this.headerName, this.headerValue);
-    return fetch(url, {...init, headers});
+    // Pass through dispatcher for TLS/mTLS support
+    return fetch(url, {...init, headers} as RequestInit);
   }
 
   /**

packages/b2c-tooling-sdk/src/auth/basic.ts

@@ -3,7 +3,7 @@
  * SPDX-License-Identifier: Apache-2
  * For full license text, see the license.txt file in the repo root or http://www.apache.org/licenses/LICENSE-2.0
  */
-import type {AuthStrategy} from './types.js';
+import type {AuthStrategy, FetchInit} from './types.js';
 import {getLogger} from '../logging/logger.js';
 
 export class BasicAuthStrategy implements AuthStrategy {
@@ -16,10 +16,12 @@ export class BasicAuthStrategy implements AuthStrategy {
     logger.debug({username: user}, `[Auth] Using Basic authentication for user: ${user}`);
   }
 
-  async fetch(url: string, init: RequestInit = {}): Promise<Response> {
+  async fetch(url: string, init: FetchInit = {}): Promise<Response> {
     const headers = new Headers(init.headers);
     headers.set('Authorization', `Basic ${this.encoded}`);
-    return fetch(url, {...init, headers});
+    // Pass through dispatcher for TLS/mTLS support
+    // Node.js fetch accepts dispatcher as an undocumented option
+    return fetch(url, {...init, headers} as RequestInit);
   }
 
   async getAuthorizationHeader(): Promise<string> {

packages/b2c-tooling-sdk/src/auth/index.ts

@@ -62,6 +62,7 @@
 // Types
 export type {
   AuthStrategy,
+  FetchInit,
   AccessTokenResponse,
   DecodedJWT,
   AuthConfig,

packages/b2c-tooling-sdk/src/auth/oauth-implicit.ts

@@ -6,7 +6,7 @@
 import {createServer, type Server, type IncomingMessage, type ServerResponse} from 'node:http';
 import type {Socket} from 'node:net';
 import {URL} from 'node:url';
-import type {AuthStrategy, AccessTokenResponse, DecodedJWT} from './types.js';
+import type {AuthStrategy, AccessTokenResponse, DecodedJWT, FetchInit} from './types.js';
 import {getLogger} from '../logging/logger.js';
 import {decodeJWT} from './oauth.js';
 import {DEFAULT_ACCOUNT_MANAGER_HOST} from '../defaults.js';
@@ -113,7 +113,7 @@ export class ImplicitOAuthStrategy implements AuthStrategy {
     logger.trace({scopes: this.config.scopes}, '[Auth] Configured scopes');
   }
 
-  async fetch(url: string, init: RequestInit = {}): Promise<Response> {
+  async fetch(url: string, init: FetchInit = {}): Promise<Response> {
     const logger = getLogger();
     const method = init.method || 'GET';
 
@@ -126,7 +126,8 @@ export class ImplicitOAuthStrategy implements AuthStrategy {
     headers.set('x-dw-client-id', this.config.clientId);
 
     const startTime = Date.now();
-    let res = await fetch(url, {...init, headers});
+    // Pass through dispatcher for TLS/mTLS support
+    let res = await fetch(url, {...init, headers} as RequestInit);
     const duration = Date.now() - startTime;
 
     logger.debug({method, url, status: res.status, duration}, '[Auth] Response');
@@ -140,7 +141,7 @@ export class ImplicitOAuthStrategy implements AuthStrategy {
       headers.set('Authorization', `Bearer ${newToken}`);
 
       const retryStart = Date.now();
-      res = await fetch(url, {...init, headers});
+      res = await fetch(url, {...init, headers} as RequestInit);
       const retryDuration = Date.now() - retryStart;
 
       logger.debug({method, url, status: res.status, duration: retryDuration}, '[Auth] Retry response');

packages/b2c-tooling-sdk/src/auth/oauth.ts

@@ -3,7 +3,7 @@
  * SPDX-License-Identifier: Apache-2
  * For full license text, see the license.txt file in the repo root or http://www.apache.org/licenses/LICENSE-2.0
  */
-import type {AuthStrategy, AccessTokenResponse, DecodedJWT} from './types.js';
+import type {AuthStrategy, AccessTokenResponse, DecodedJWT, FetchInit} from './types.js';
 import {getLogger} from '../logging/logger.js';
 import {DEFAULT_ACCOUNT_MANAGER_HOST} from '../defaults.js';
 import {globalAuthMiddlewareRegistry, applyAuthRequestMiddleware, applyAuthResponseMiddleware} from './middleware.js';
@@ -38,22 +38,24 @@ export class OAuthStrategy implements AuthStrategy {
     this.accountManagerHost = config.accountManagerHost || DEFAULT_ACCOUNT_MANAGER_HOST;
   }
 
-  async fetch(url: string, init: RequestInit = {}): Promise<Response> {
+  async fetch(url: string, init: FetchInit = {}): Promise<Response> {
     const token = await this.getAccessToken();
 
     const headers = new Headers(init.headers);
     headers.set('Authorization', `Bearer ${token}`);
     headers.set('x-dw-client-id', this.config.clientId);
 
-    let res = await fetch(url, {...init, headers});
+    // Pass through dispatcher for TLS/mTLS support
+    // Node.js fetch accepts dispatcher as an undocumented option
+    let res = await fetch(url, {...init, headers} as RequestInit);
 
     // RESILIENCE: If the server says 401, the token might have expired or been revoked.
     // We retry exactly once after invalidating the cached token.
     if (res.status === 401) {
       this.invalidateToken();
       const newToken = await this.getAccessToken();
       headers.set('Authorization', `Bearer ${newToken}`);
-      res = await fetch(url, {...init, headers});
+      res = await fetch(url, {...init, headers} as RequestInit);
     }
 
     return res;

packages/b2c-tooling-sdk/src/auth/types.ts

@@ -3,12 +3,23 @@
  * SPDX-License-Identifier: Apache-2
  * For full license text, see the license.txt file in the repo root or http://www.apache.org/licenses/LICENSE-2.0
  */
+
+/**
+ * Extended RequestInit that supports undici dispatcher for TLS/mTLS.
+ * Uses `unknown` for dispatcher to avoid type conflicts between undici package
+ * and @types/node/undici-types.
+ */
+export type FetchInit = Omit<RequestInit, 'dispatcher'> & {
+  /** undici dispatcher for custom TLS options (mTLS, self-signed certs) */
+  dispatcher?: unknown;
+};
+
 export interface AuthStrategy {
   /**
    * Performs a fetch request with authentication.
    * Implementations MUST handle header injection and 401 retries (token refresh) internally.
    */
-  fetch(url: string, init?: RequestInit): Promise<Response>;
+  fetch(url: string, init?: FetchInit): Promise<Response>;
 
   /**
    * Optional: Helper for legacy clients (like a strict WebDAV lib) that need the raw header.

packages/b2c-tooling-sdk/src/cli/config.ts

@@ -90,6 +90,10 @@ export function extractInstanceFlags(flags: ParsedFlags): Partial<NormalizedConf
     codeVersion: flags['code-version'] as string | undefined,
     username: flags.username as string | undefined,
     password: flags.password as string | undefined,
+    // TLS/mTLS options
+    certificate: flags.certificate as string | undefined,
+    certificatePassphrase: flags.passphrase as string | undefined,
+    selfSigned: (flags.selfsigned as boolean) || !(flags.verify as boolean),
     // Include OAuth flags (instance operations often need OAuth too)
     ...extractOAuthFlags(flags),
   };