@fluentcommerce/fc-connect-sdk 0.1.53 → 0.1.55

package/docs/04-REFERENCE/troubleshooting/troubleshooting-deno-sftp-compatibility.md

@@ -1,392 +1,392 @@
-# Deno SFTP Compatibility Fix
-
-**Issue**: `setAutoPadding(false) not supported for Aes128Gcm yet`
-
-**Impact**: SFTP connections fail when deployed to Versori platform (Deno runtime)
-
-**Root Cause**: Deno's crypto implementation doesn't support `setAutoPadding(false)` for AES-GCM ciphers. When the SSH2 library tries to negotiate `aes128-gcm@openssh.com` with AWS Transfer Family or other SFTP servers, the connection fails.
-
----
-
-## Architecture Decision
-
-**SDK handles platform compatibility, not connectors.**
-
-The SDK automatically detects Deno runtime and configures compatible SSH algorithms. Connectors don't need any special configuration.
-
----
-
-## How It Works
-
-### Automatic Detection
-
-The SDK detects Deno at runtime:
-
-```typescript
-const isDeno = typeof (globalThis as any).Deno !== 'undefined';
-```
-
-### Complete Algorithm Configuration
-
-When Deno is detected, the SDK configures all four SSH negotiation phases:
-
-1. **Cipher Algorithms** - Encryption (no AES-GCM)
-2. **Server Host Key** - Server authentication
-3. **Key Exchange (KEX)** - Session key negotiation
-4. **HMAC** - Message authentication codes
-
-**Why all four?** SSH negotiation requires compatible algorithms across all phases. Configuring only ciphers isn't enough—the server can still force AES-GCM during the handshake if other phases aren't restricted.
-
----
-
-## Implementation Details
-
-**Location**: `fc-connect-sdk/src/data-sources/sftp-data-source.ts` (search for `isDeno` to find current implementation)
-
-> **Note:** Line numbers may change between SDK versions. Search for `isDeno` in the source file to locate the algorithm detection logic (currently around lines 2083-2143).
-
-```typescript
-// Auto-detect Deno and use compatible algorithms
-const isDeno = typeof (globalThis as any).Deno !== 'undefined';
-if (isDeno) {
-  connectConfig.algorithms = {
-    // Encryption ciphers (ONLY Deno-supported - no GCM, no aes192/256-cbc)
-    // ⚠️ CRITICAL: Deno crypto limitations - only aes128-ctr and aes128-cbc fully supported
-    cipher: [
-      'aes128-ctr', // Primary - most secure + fully supported
-      'aes128-cbc', // Fallback - supported in Deno
-    ],
-    // Server authentication methods (most secure first)
-    serverHostKey: [
-      'rsa-sha2-512',   // Most secure (preferred)
-      'rsa-sha2-256',   // Modern standard
-      'ssh-rsa',        // Older standard (avoid if possible)
-      'ecdsa-sha2-nistp256',
-      'ecdsa-sha2-nistp384',
-      'ecdsa-sha2-nistp521',
-      'ssh-ed25519',
-    ],
-    // Key exchange algorithms
-    kex: [
-      'curve25519-sha256',
-      'curve25519-sha256@libssh.org',
-      'ecdh-sha2-nistp256',
-      'ecdh-sha2-nistp384',
-      'ecdh-sha2-nistp521',
-      'diffie-hellman-group14-sha256',
-      'diffie-hellman-group16-sha512',
-      'diffie-hellman-group18-sha512',
-      'diffie-hellman-group-exchange-sha256',
-      'diffie-hellman-group14-sha1',
-    ],
-    // Message authentication codes (including ETM variants for AWS Transfer Family)
-    hmac: [
-      'hmac-sha2-256-etm@openssh.com',
-      'hmac-sha2-512-etm@openssh.com',
-      'hmac-sha2-256',
-      'hmac-sha2-512',
-      'hmac-sha1-etm@openssh.com',
-      'hmac-sha1',
-    ],
-    // Compression
-    compress: ['none'],
-  };
-}
-```
-
-### Algorithm Support Details
-
-**Supported Ciphers (Deno-Compatible):**
-- `aes128-ctr` ✅ Fully supported (recommended)
-- `aes128-cbc` ✅ Fully supported (fallback)
-
-> **⚠️ IMPORTANT:** Only AES-128 variants are fully supported in Deno runtime.
-> AES-192 and AES-256 variants are NOT supported due to Deno's crypto limitations.
-
-**Supported ServerHostKey (Preferred Order):**
-- `rsa-sha2-512` ✅ Most secure (preferred for production)
-- `rsa-sha2-256` ✅ Modern standard
-- `ssh-rsa` ⚠️ Older standard (least secure, avoid if possible)
-- `ecdsa-sha2-nistp256` ✅ ECDSA variant
-- `ecdsa-sha2-nistp384` ✅ ECDSA variant
-- `ecdsa-sha2-nistp521` ✅ ECDSA variant
-- `ssh-ed25519` ✅ Modern elliptic curve
-
-> **Best Practice:** Use `rsa-sha2-512` or `rsa-sha2-256` for modern SFTP servers.
-
-**Supported HMAC Algorithms:**
-- `hmac-sha2-256-etm@openssh.com` ✅ AWS Transfer Family compatible
-- `hmac-sha2-512-etm@openssh.com` ✅ AWS Transfer Family compatible
-- `hmac-sha2-256` ✅ Standard
-- `hmac-sha2-512` ✅ Standard
-- `hmac-sha1-etm@openssh.com` ✅ Older ETM variant
-- `hmac-sha1` ⚠️ Older standard (avoid if possible)
-
-> **Note:** ETM (Encrypt-Then-MAC) variants are required for AWS Transfer Family compatibility.
-
-### Algorithm Compatibility Matrix
-
-| Algorithm Type | Node.js | Deno | Notes |
-|----------------|---------|------|-------|
-| **Ciphers** | | | |
-| aes128-ctr | ✅ | ✅ | Fully supported (recommended) |
-| aes128-cbc | ✅ | ✅ | Fully supported (fallback) |
-| aes192-ctr | ✅ | ❌ | Deno crypto limitation |
-| aes192-cbc | ✅ | ❌ | Deno crypto limitation |
-| aes256-ctr | ✅ | ❌ | Deno crypto limitation |
-| aes256-cbc | ✅ | ❌ | Deno crypto limitation |
-| aes128-gcm@openssh.com | ✅ | ❌ | Deno doesn't support setAutoPadding(false) |
-| **HMAC** | | | |
-| hmac-sha2-256 | ✅ | ✅ | Recommended |
-| hmac-sha2-512 | ✅ | ✅ | Recommended |
-| hmac-sha1 | ✅ | ✅ | Older systems compatibility |
-| hmac-*-etm@openssh.com | ✅ | ✅ | AWS Transfer Family required |
-| **ServerHostKey** | | | |
-| rsa-sha2-512 | ✅ | ✅ | Most secure (preferred) |
-| rsa-sha2-256 | ✅ | ✅ | Modern standard |
-| ssh-rsa | ✅ | ✅ | Older standard (avoid if possible) |
-| ecdsa-sha2-nistp* | ✅ | ✅ | ECDSA variants |
-| ssh-ed25519 | ✅ | ✅ | Modern elliptic curve |
-
-**Verification Commands:**
-```bash
-# Verify supported ciphers in source code
-cd fc-connect-sdk
-grep -A20 "isDeno" src/data-sources/sftp-data-source.ts | grep "cipher"
-# Expected: Only aes128-ctr and aes128-cbc
-
-# Find current line numbers
-grep -n "isDeno" src/data-sources/sftp-data-source.ts
-# Note: Currently around lines 2083-2143
-
-# Verify HMAC algorithms
-grep -A20 "isDeno" src/data-sources/sftp-data-source.ts | grep "hmac"
-# Expected: 6 algorithms including ETM variants
-
-# Verify ServerHostKey list
-grep -A20 "isDeno" src/data-sources/sftp-data-source.ts | grep "serverHostKey"
-# Expected: rsa-sha2-512 first, includes ECDSA variants
-```
-
----
-
-## Connector Usage
-
-**No configuration needed!** Just use `SftpDataSource` as normal:
-
-```typescript
-import { SftpDataSource } from '@fluentcommerce/fc-connect-sdk';
-
-const sftp = new SftpDataSource(
-  {
-    type: 'SFTP_XML',
-    connectionId: 'my-sftp',
-    name: 'My SFTP Connection',
-    settings: {
-      host: 's-xxxxx.server.transfer.ap-southeast-2.amazonaws.com',
-      port: 22,
-      username: 'myuser',
-      privateKey: sftpPrivateKey,
-      remotePath: '/upload',
-      filePattern: '*.xml',
-      // NO algorithms config needed - SDK handles it!
-    }
-  },
-  logger
-);
-
-// Works on both Node.js and Deno
-await sftp.uploadFile('/upload/file.xml', xmlData);
-```
-
----
-
-## Override if Needed
-
-For special cases, you can override the algorithms:
-
-```typescript
-// Algorithm configuration is an inline interface in SftpConnection
-// (there is no exported SftpAlgorithms type to import)
-const sftp = new SftpDataSource(
-  {
-    type: 'SFTP_XML',
-    settings: {
-      host: 'sftp.example.com',
-      // ... other settings
-      algorithms: {
-        cipher: ['aes128-ctr'],  // Deno-compatible only!
-        serverHostKey: ['rsa-sha2-512', 'rsa-sha2-256'],
-        hmac: ['hmac-sha2-256-etm@openssh.com', 'hmac-sha2-256'],
-        // ... custom kex if needed
-      }
-    }
-  },
-  logger
-);
-```
-
-> **Note:** There is no exported `SftpAlgorithms` type. The algorithms configuration
-> is defined inline in the `SftpConnection` interface at `src/types/index.ts:626-632`.
-
-**When to override:**
-- Corporate SFTP server with restricted algorithm list
-- Security policy requires specific algorithms
-- Testing specific cipher combinations
-- Need to force a particular algorithm order
-
-**When NOT to override:**
-- Normal AWS Transfer Family connections ✅
-- Standard SFTP servers ✅
-- Versori platform deployment ✅
-- Default auto-detection works for your use case ✅
-
----
-
-## Verified Compatibility
-
-This configuration works with:
-
-- ✅ AWS Transfer Family SFTP
-- ✅ OpenSSH servers
-- ✅ Versori platform (Deno runtime)
-- ✅ Node.js runtime (no impact)
-
----
-
-## Error Messages
-
-### Before Fix
-```
-Error: Failed to create SFTP connection
-getConnection: setAutoPadding(false) not supported for Aes128Gcm yet
-```
-
-### After Fix
-```
-✓ Deno runtime detected - using compatible SFTP algorithms
-✓ SFTP connection initialized
-✓ XML file uploaded successfully
-```
-
----
-
-## Testing
-
-### Manual Test
-1. Deploy connector to Versori
-2. Check logs for: `"Deno runtime detected - using compatible SFTP algorithms"`
-3. Verify successful SFTP connection and upload
-
-### Automated Test
-```bash
-cd fc-connect-sdk
-npm run test:deno
-```
-
----
-
-## Related Files
-
-- `src/data-sources/sftp-data-source.ts` - Auto-detection logic (search for `isDeno`, currently around lines 2083-2143)
-- `src/types/index.ts:626-632` - SftpConnection interface with inline algorithms configuration (no separate SftpAlgorithms type)
-
----
-
-## References
-
-- **Issue**: Deno crypto doesn't support `setAutoPadding(false)` for AES-GCM
-- **Solution**: Complete SSH algorithm configuration for Deno runtime
-- **Upstream**: Deno issue [denoland/deno#xxxxx](https://github.com/denoland/deno/issues) (when AES-GCM support is added, SDK will continue to work)
-
----
-
-## Migration Guide: Node.js to Deno
-
-### Before (Node.js - All Ciphers Work)
-
-In Node.js, you can use any cipher algorithm without restrictions:
-
-```typescript
-// Node.js - no algorithm restrictions
-const sftp = new SftpDataSource({
-  settings: {
-    host: 's-xxxxx.server.transfer.ap-southeast-2.amazonaws.com',
-    port: 22,
-    username: 'myuser',
-    privateKey: sftpPrivateKey,
-    // Optional: Custom algorithms (all work in Node.js)
-    algorithms: {
-      cipher: ['aes256-ctr', 'aes192-ctr', 'aes128-ctr'],  // All work in Node.js
-      serverHostKey: ['ssh-rsa', 'rsa-sha2-256'],
-      hmac: ['hmac-sha2-256', 'hmac-sha1'],
-    }
-  }
-}, logger);
-```
-
-### After (Deno - Only AES-128 Supported)
-
-In Deno, you MUST restrict to AES-128 ciphers only:
-
-```typescript
-// Deno - restrict to compatible algorithms
-const sftp = new SftpDataSource({
-  settings: {
-    host: 's-xxxxx.server.transfer.ap-southeast-2.amazonaws.com',
-    port: 22,
-    username: 'myuser',
-    privateKey: sftpPrivateKey,
-    // Required in Deno: Only AES-128 ciphers work
-    algorithms: {
-      cipher: ['aes128-ctr', 'aes128-cbc'],  // ONLY these work in Deno!
-      serverHostKey: ['rsa-sha2-512', 'rsa-sha2-256'],
-      hmac: ['hmac-sha2-256-etm@openssh.com', 'hmac-sha2-256'],
-    }
-  }
-}, logger);
-```
-
-### Recommended (Auto-Detection - Works Everywhere)
-
-**Best approach**: Let the SDK handle it automatically:
-
-```typescript
-// ✅ RECOMMENDED - SDK auto-detects Deno and adjusts algorithms
-const sftp = new SftpDataSource({
-  settings: {
-    host: 's-xxxxx.server.transfer.ap-southeast-2.amazonaws.com',
-    port: 22,
-    username: 'myuser',
-    privateKey: sftpPrivateKey,
-    // No algorithms specified - SDK handles it automatically!
-    // Works on both Node.js and Deno without changes
-  }
-}, logger);
-```
-
-**Why this is best:**
-- ✅ Same code works in Node.js and Deno
-- ✅ SDK automatically restricts algorithms in Deno
-- ✅ SDK uses all available algorithms in Node.js
-- ✅ No manual configuration needed
-- ✅ Future-proof (SDK updates automatically)
-
-### Migration Checklist
-
-When migrating connectors from Node.js to Deno/Versori:
-
-- [ ] Remove manual algorithm configuration (let SDK auto-detect)
-- [ ] Test SFTP connection on Versori platform
-- [ ] Check logs for: `"Deno runtime detected - using compatible SFTP algorithms"`
-- [ ] Verify successful file upload/download
-- [ ] Remove AES-192/256 ciphers if manually configured
-- [ ] Add ETM HMAC variants for AWS Transfer Family if needed
-
----
-
-## Summary
-
-**Before**: Complex algorithm configuration required in every connector
-**After**: SDK automatically handles Deno compatibility
-**Benefit**: Write once, deploy anywhere (Node.js or Deno)
+# Deno SFTP Compatibility Fix
+
+**Issue**: `setAutoPadding(false) not supported for Aes128Gcm yet`
+
+**Impact**: SFTP connections fail when deployed to Versori platform (Deno runtime)
+
+**Root Cause**: Deno's crypto implementation doesn't support `setAutoPadding(false)` for AES-GCM ciphers. When the SSH2 library tries to negotiate `aes128-gcm@openssh.com` with AWS Transfer Family or other SFTP servers, the connection fails.
+
+---
+
+## Architecture Decision
+
+**SDK handles platform compatibility, not connectors.**
+
+The SDK automatically detects Deno runtime and configures compatible SSH algorithms. Connectors don't need any special configuration.
+
+---
+
+## How It Works
+
+### Automatic Detection
+
+The SDK detects Deno at runtime:
+
+```typescript
+const isDeno = typeof (globalThis as any).Deno !== 'undefined';
+```
+
+### Complete Algorithm Configuration
+
+When Deno is detected, the SDK configures all four SSH negotiation phases:
+
+1. **Cipher Algorithms** - Encryption (no AES-GCM)
+2. **Server Host Key** - Server authentication
+3. **Key Exchange (KEX)** - Session key negotiation
+4. **HMAC** - Message authentication codes
+
+**Why all four?** SSH negotiation requires compatible algorithms across all phases. Configuring only ciphers isn't enough—the server can still force AES-GCM during the handshake if other phases aren't restricted.
+
+---
+
+## Implementation Details
+
+**Location**: `fc-connect-sdk/src/data-sources/sftp-data-source.ts` (search for `isDeno` to find current implementation)
+
+> **Note:** Line numbers may change between SDK versions. Search for `isDeno` in the source file to locate the algorithm detection logic (currently around lines 2083-2143).
+
+```typescript
+// Auto-detect Deno and use compatible algorithms
+const isDeno = typeof (globalThis as any).Deno !== 'undefined';
+if (isDeno) {
+  connectConfig.algorithms = {
+    // Encryption ciphers (ONLY Deno-supported - no GCM, no aes192/256-cbc)
+    // ⚠️ CRITICAL: Deno crypto limitations - only aes128-ctr and aes128-cbc fully supported
+    cipher: [
+      'aes128-ctr', // Primary - most secure + fully supported
+      'aes128-cbc', // Fallback - supported in Deno
+    ],
+    // Server authentication methods (most secure first)
+    serverHostKey: [
+      'rsa-sha2-512',   // Most secure (preferred)
+      'rsa-sha2-256',   // Modern standard
+      'ssh-rsa',        // Older standard (avoid if possible)
+      'ecdsa-sha2-nistp256',
+      'ecdsa-sha2-nistp384',
+      'ecdsa-sha2-nistp521',
+      'ssh-ed25519',
+    ],
+    // Key exchange algorithms
+    kex: [
+      'curve25519-sha256',
+      'curve25519-sha256@libssh.org',
+      'ecdh-sha2-nistp256',
+      'ecdh-sha2-nistp384',
+      'ecdh-sha2-nistp521',
+      'diffie-hellman-group14-sha256',
+      'diffie-hellman-group16-sha512',
+      'diffie-hellman-group18-sha512',
+      'diffie-hellman-group-exchange-sha256',
+      'diffie-hellman-group14-sha1',
+    ],
+    // Message authentication codes (including ETM variants for AWS Transfer Family)
+    hmac: [
+      'hmac-sha2-256-etm@openssh.com',
+      'hmac-sha2-512-etm@openssh.com',
+      'hmac-sha2-256',
+      'hmac-sha2-512',
+      'hmac-sha1-etm@openssh.com',
+      'hmac-sha1',
+    ],
+    // Compression
+    compress: ['none'],
+  };
+}
+```
+
+### Algorithm Support Details
+
+**Supported Ciphers (Deno-Compatible):**
+- `aes128-ctr` ✅ Fully supported (recommended)
+- `aes128-cbc` ✅ Fully supported (fallback)
+
+> **⚠️ IMPORTANT:** Only AES-128 variants are fully supported in Deno runtime.
+> AES-192 and AES-256 variants are NOT supported due to Deno's crypto limitations.
+
+**Supported ServerHostKey (Preferred Order):**
+- `rsa-sha2-512` ✅ Most secure (preferred for production)
+- `rsa-sha2-256` ✅ Modern standard
+- `ssh-rsa` ⚠️ Older standard (least secure, avoid if possible)
+- `ecdsa-sha2-nistp256` ✅ ECDSA variant
+- `ecdsa-sha2-nistp384` ✅ ECDSA variant
+- `ecdsa-sha2-nistp521` ✅ ECDSA variant
+- `ssh-ed25519` ✅ Modern elliptic curve
+
+> **Best Practice:** Use `rsa-sha2-512` or `rsa-sha2-256` for modern SFTP servers.
+
+**Supported HMAC Algorithms:**
+- `hmac-sha2-256-etm@openssh.com` ✅ AWS Transfer Family compatible
+- `hmac-sha2-512-etm@openssh.com` ✅ AWS Transfer Family compatible
+- `hmac-sha2-256` ✅ Standard
+- `hmac-sha2-512` ✅ Standard
+- `hmac-sha1-etm@openssh.com` ✅ Older ETM variant
+- `hmac-sha1` ⚠️ Older standard (avoid if possible)
+
+> **Note:** ETM (Encrypt-Then-MAC) variants are required for AWS Transfer Family compatibility.
+
+### Algorithm Compatibility Matrix
+
+| Algorithm Type | Node.js | Deno | Notes |
+|----------------|---------|------|-------|
+| **Ciphers** | | | |
+| aes128-ctr | ✅ | ✅ | Fully supported (recommended) |
+| aes128-cbc | ✅ | ✅ | Fully supported (fallback) |
+| aes192-ctr | ✅ | ❌ | Deno crypto limitation |
+| aes192-cbc | ✅ | ❌ | Deno crypto limitation |
+| aes256-ctr | ✅ | ❌ | Deno crypto limitation |
+| aes256-cbc | ✅ | ❌ | Deno crypto limitation |
+| aes128-gcm@openssh.com | ✅ | ❌ | Deno doesn't support setAutoPadding(false) |
+| **HMAC** | | | |
+| hmac-sha2-256 | ✅ | ✅ | Recommended |
+| hmac-sha2-512 | ✅ | ✅ | Recommended |
+| hmac-sha1 | ✅ | ✅ | Older systems compatibility |
+| hmac-*-etm@openssh.com | ✅ | ✅ | AWS Transfer Family required |
+| **ServerHostKey** | | | |
+| rsa-sha2-512 | ✅ | ✅ | Most secure (preferred) |
+| rsa-sha2-256 | ✅ | ✅ | Modern standard |
+| ssh-rsa | ✅ | ✅ | Older standard (avoid if possible) |
+| ecdsa-sha2-nistp* | ✅ | ✅ | ECDSA variants |
+| ssh-ed25519 | ✅ | ✅ | Modern elliptic curve |
+
+**Verification Commands:**
+```bash
+# Verify supported ciphers in source code
+cd fc-connect-sdk
+grep -A20 "isDeno" src/data-sources/sftp-data-source.ts | grep "cipher"
+# Expected: Only aes128-ctr and aes128-cbc
+
+# Find current line numbers
+grep -n "isDeno" src/data-sources/sftp-data-source.ts
+# Note: Currently around lines 2083-2143
+
+# Verify HMAC algorithms
+grep -A20 "isDeno" src/data-sources/sftp-data-source.ts | grep "hmac"
+# Expected: 6 algorithms including ETM variants
+
+# Verify ServerHostKey list
+grep -A20 "isDeno" src/data-sources/sftp-data-source.ts | grep "serverHostKey"
+# Expected: rsa-sha2-512 first, includes ECDSA variants
+```
+
+---
+
+## Connector Usage
+
+**No configuration needed!** Just use `SftpDataSource` as normal:
+
+```typescript
+import { SftpDataSource } from '@fluentcommerce/fc-connect-sdk';
+
+const sftp = new SftpDataSource(
+  {
+    type: 'SFTP_XML',
+    connectionId: 'my-sftp',
+    name: 'My SFTP Connection',
+    settings: {
+      host: 's-xxxxx.server.transfer.ap-southeast-2.amazonaws.com',
+      port: 22,
+      username: 'myuser',
+      privateKey: sftpPrivateKey,
+      remotePath: '/upload',
+      filePattern: '*.xml',
+      // NO algorithms config needed - SDK handles it!
+    }
+  },
+  logger
+);
+
+// Works on both Node.js and Deno
+await sftp.uploadFile('/upload/file.xml', xmlData);
+```
+
+---
+
+## Override if Needed
+
+For special cases, you can override the algorithms:
+
+```typescript
+// Algorithm configuration is an inline interface in SftpConnection
+// (there is no exported SftpAlgorithms type to import)
+const sftp = new SftpDataSource(
+  {
+    type: 'SFTP_XML',
+    settings: {
+      host: 'sftp.example.com',
+      // ... other settings
+      algorithms: {
+        cipher: ['aes128-ctr'],  // Deno-compatible only!
+        serverHostKey: ['rsa-sha2-512', 'rsa-sha2-256'],
+        hmac: ['hmac-sha2-256-etm@openssh.com', 'hmac-sha2-256'],
+        // ... custom kex if needed
+      }
+    }
+  },
+  logger
+);
+```
+
+> **Note:** There is no exported `SftpAlgorithms` type. The algorithms configuration
+> is defined inline in the `SftpConnection` interface at `src/types/index.ts:626-632`.
+
+**When to override:**
+- Corporate SFTP server with restricted algorithm list
+- Security policy requires specific algorithms
+- Testing specific cipher combinations
+- Need to force a particular algorithm order
+
+**When NOT to override:**
+- Normal AWS Transfer Family connections ✅
+- Standard SFTP servers ✅
+- Versori platform deployment ✅
+- Default auto-detection works for your use case ✅
+
+---
+
+## Verified Compatibility
+
+This configuration works with:
+
+- ✅ AWS Transfer Family SFTP
+- ✅ OpenSSH servers
+- ✅ Versori platform (Deno runtime)
+- ✅ Node.js runtime (no impact)
+
+---
+
+## Error Messages
+
+### Before Fix
+```
+Error: Failed to create SFTP connection
+getConnection: setAutoPadding(false) not supported for Aes128Gcm yet
+```
+
+### After Fix
+```
+✓ Deno runtime detected - using compatible SFTP algorithms
+✓ SFTP connection initialized
+✓ XML file uploaded successfully
+```
+
+---
+
+## Testing
+
+### Manual Test
+1. Deploy connector to Versori
+2. Check logs for: `"Deno runtime detected - using compatible SFTP algorithms"`
+3. Verify successful SFTP connection and upload
+
+### Automated Test
+```bash
+cd fc-connect-sdk
+npm run test:deno
+```
+
+---
+
+## Related Files
+
+- `src/data-sources/sftp-data-source.ts` - Auto-detection logic (search for `isDeno`, currently around lines 2083-2143)
+- `src/types/index.ts:626-632` - SftpConnection interface with inline algorithms configuration (no separate SftpAlgorithms type)
+
+---
+
+## References
+
+- **Issue**: Deno crypto doesn't support `setAutoPadding(false)` for AES-GCM
+- **Solution**: Complete SSH algorithm configuration for Deno runtime
+- **Upstream**: Deno issue [denoland/deno#xxxxx](https://github.com/denoland/deno/issues) (when AES-GCM support is added, SDK will continue to work)
+
+---
+
+## Migration Guide: Node.js to Deno
+
+### Before (Node.js - All Ciphers Work)
+
+In Node.js, you can use any cipher algorithm without restrictions:
+
+```typescript
+// Node.js - no algorithm restrictions
+const sftp = new SftpDataSource({
+  settings: {
+    host: 's-xxxxx.server.transfer.ap-southeast-2.amazonaws.com',
+    port: 22,
+    username: 'myuser',
+    privateKey: sftpPrivateKey,
+    // Optional: Custom algorithms (all work in Node.js)
+    algorithms: {
+      cipher: ['aes256-ctr', 'aes192-ctr', 'aes128-ctr'],  // All work in Node.js
+      serverHostKey: ['ssh-rsa', 'rsa-sha2-256'],
+      hmac: ['hmac-sha2-256', 'hmac-sha1'],
+    }
+  }
+}, logger);
+```
+
+### After (Deno - Only AES-128 Supported)
+
+In Deno, you MUST restrict to AES-128 ciphers only:
+
+```typescript
+// Deno - restrict to compatible algorithms
+const sftp = new SftpDataSource({
+  settings: {
+    host: 's-xxxxx.server.transfer.ap-southeast-2.amazonaws.com',
+    port: 22,
+    username: 'myuser',
+    privateKey: sftpPrivateKey,
+    // Required in Deno: Only AES-128 ciphers work
+    algorithms: {
+      cipher: ['aes128-ctr', 'aes128-cbc'],  // ONLY these work in Deno!
+      serverHostKey: ['rsa-sha2-512', 'rsa-sha2-256'],
+      hmac: ['hmac-sha2-256-etm@openssh.com', 'hmac-sha2-256'],
+    }
+  }
+}, logger);
+```
+
+### Recommended (Auto-Detection - Works Everywhere)
+
+**Best approach**: Let the SDK handle it automatically:
+
+```typescript
+// ✅ RECOMMENDED - SDK auto-detects Deno and adjusts algorithms
+const sftp = new SftpDataSource({
+  settings: {
+    host: 's-xxxxx.server.transfer.ap-southeast-2.amazonaws.com',
+    port: 22,
+    username: 'myuser',
+    privateKey: sftpPrivateKey,
+    // No algorithms specified - SDK handles it automatically!
+    // Works on both Node.js and Deno without changes
+  }
+}, logger);
+```
+
+**Why this is best:**
+- ✅ Same code works in Node.js and Deno
+- ✅ SDK automatically restricts algorithms in Deno
+- ✅ SDK uses all available algorithms in Node.js
+- ✅ No manual configuration needed
+- ✅ Future-proof (SDK updates automatically)
+
+### Migration Checklist
+
+When migrating connectors from Node.js to Deno/Versori:
+
+- [ ] Remove manual algorithm configuration (let SDK auto-detect)
+- [ ] Test SFTP connection on Versori platform
+- [ ] Check logs for: `"Deno runtime detected - using compatible SFTP algorithms"`
+- [ ] Verify successful file upload/download
+- [ ] Remove AES-192/256 ciphers if manually configured
+- [ ] Add ETM HMAC variants for AWS Transfer Family if needed
+
+---
+
+## Summary
+
+**Before**: Complex algorithm configuration required in every connector
+**After**: SDK automatically handles Deno compatibility
+**Benefit**: Write once, deploy anywhere (Node.js or Deno)