@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.56

package/docs/02-CORE-GUIDES/data-sources/data-sources-sftp-credential-access-security.md

@@ -1,553 +1,553 @@
-# SFTP Credential Access & Security Best Practices
-
-**For Versori Platform Integration**
-
----
-
-## 🎯 Overview
-
-This guide covers the **secure retrieval of SFTP credentials** in Versori platform connectors. We'll show **two approaches** - one using `credentials()` API and one using `activation.connections` (recommended).
-
-**Key Principle:** Never hardcode credentials in code - always use Versori connection configuration.
-
-> **Note:** This guide consolidates the canonical pattern documentation. For production-ready patterns with comprehensive error handling, see the Method 1 section below.
-
----
-
-## 📋 The Two Approaches
-
-| Approach | Method | Decoding | Complexity | Recommended |
-|----------|--------|----------|------------|-------------|
-| **Method 1** | `credentials().getAccessToken()` | ⚠️ Base64 | Medium | ❌ More work |
-| **Method 2** | `activation.connections` | ✅ None | Low | ✅ **BEST** |
-
----
-
-## ✅ Correct Method: credentials().getAccessToken()
-
-```typescript
-// ✅ CORRECT - Use .getAccessToken()
-const sftpCred = await ctx.credentials().getAccessToken('SFTP');
-```
-
----
-
-## Method 1: credentials() API (Your Corrected Code)
-
-**Use when:** Working in `fn()` tasks where `connectionVariables` not available
-
-### ✅ Corrected Implementation
-
-```typescript
-import { schedule, fn } from '@versori/run';
-import { Buffer } from 'node:buffer';  // ⭐ Required for Deno runtime!
-import { SftpDataSource } from '@fluentcommerce/fc-connect-sdk';
-
-export const sftpWorkflow = schedule("sftp-sync", "0 * * * *")
-  .then(fn("get-files", async (ctx) => {
-    const { log } = ctx;
-
-    // ========================================
-    // SFTP CREDENTIAL RETRIEVAL
-    // ========================================
-
-    /**
-     * Retrieve SFTP credentials from connection configuration
-     *
-     * This approach retrieves credentials stored in the Versori connection settings.
-     * The connection must be configured in the UI with Basic Authentication.
-     *
-     * Steps:
-     * 1. Call ctx.credentials().getAccessToken('SFTP') to get base64-encoded credentials
-     * 2. Decode the accessToken from base64 to get "username:password" string
-     * 3. Split on ':' to extract username and password
-     *
-     * Connection Name: 'SFTP' (must match the connection name in Versori UI)
-     * Auth Type: Basic Authentication (username + password)
-     *
-     * This method provides:
-     * - Centralized credential management through Versori UI
-     * - Better security (credentials not stored in integration variables)
-     * - Easier credential rotation and updates
-     */
-    log.info('Retrieving SFTP credentials from connection configuration');
-
-    let sftpUsername: string;
-    let sftpPassword: string;
-
-    try {
-      // Retrieve credentials from the 'SFTP' connection
-      const sftpCred = await ctx.credentials().getAccessToken('SFTP');
-
-      if (!sftpCred?.accessToken) {
-        throw new Error('No SFTP credentials found in connection configuration');
-      }
-
-      // Decode base64 accessToken to get "username:password"
-      const rawBasicAuth = Buffer.from(sftpCred.accessToken, 'base64').toString('utf-8');
-
-      // Split on ':' to extract username and password
-      const parts = rawBasicAuth.split(':');
-
-      if (parts.length !== 2) {
-        throw new Error('Invalid SFTP credential format - expected username:password');
-      }
-
-      sftpUsername = parts[0];
-      sftpPassword = parts[1];
-
-      log.info('SFTP credentials retrieved successfully', {
-        hasUsername: !!sftpUsername,
-        hasPassword: !!sftpPassword,
-        usernameLength: sftpUsername.length,
-        passwordLength: sftpPassword.length,
-      });
-    } catch (error: any) {
-      log.error('Failed to retrieve SFTP credentials', {
-        error: error?.message,
-        stack: error?.stack,
-      });
-
-      return {
-        success: false,
-        error: 'Failed to retrieve SFTP credentials from connection configuration',
-        details: error?.message,
-        recommendation: 'Please ensure the SFTP connection is configured in the Connections section with Basic Authentication (username and password)',
-      };
-    }
-
-    // ========================================
-    // USE CREDENTIALS WITH SFTP
-    // ========================================
-
-    const sftp = new SftpDataSource({
-      host: 'sftp.example.com',
-      port: 22,
-      username: sftpUsername,
-      password: sftpPassword
-    }, log);
-
-    const files = await sftp.listFiles('/inbound');
-    log.info('Files retrieved', { count: files.length });
-
-    return { success: true, fileCount: files.length };
-  }));
-```
-
-### ⚠️ Limitations of Method 1
-
-**Why this is NOT the best approach:**
-
-1. ❌ **Requires base64 decoding** - Extra complexity
-2. ❌ **Only works in `fn()` tasks** - Not in `http()` tasks with `connectionVariables`
-3. ❌ **More error-prone** - Manual string splitting
-4. ❌ **Depends on connection structure** - Assumes `accessToken` field exists
-
----
-
-## ✅ Method 2: activation.connections (RECOMMENDED!)
-
-**Use when:** Any task type - **PREFERRED for all cases**
-
-### Why This Is Better
-
-✅ **Already Decoded** - No Buffer.from() needed!
-✅ **Works Everywhere** - fn(), http(), webhook() tasks
-✅ **Type-Safe** - Direct access to credential structure
-✅ **Cleaner Code** - Fewer steps, less error handling
-
-### Complete Implementation
-
-```typescript
-import { schedule, http } from '@versori/run';
-import { SftpDataSource } from '@fluentcommerce/fc-connect-sdk';
-
-export const sftpWorkflowRecommended = schedule("sftp-sync-best", "0 * * * *")
-  .then(http("process", { connection: "fluent_commerce" }, async (ctx) => {
-    const { activation, log } = ctx;
-
-    // ========================================
-    // SFTP CREDENTIAL RETRIEVAL (RECOMMENDED APPROACH)
-    // ========================================
-
-    /**
-     * Retrieve SFTP credentials using activation.connections
-     *
-     * This is the RECOMMENDED approach because:
-     * 1. Credentials are ALREADY DECODED (no Buffer.from needed!)
-     * 2. Works in any task type (fn, http, webhook)
-     * 3. Type-safe access to credential structure
-     * 4. Cleaner, more maintainable code
-     *
-     * Connection Name: 'versori_ftp_server' (must match Versori UI)
-     * Auth Type: Basic Authentication (username + password)
-     *
-     * Benefits:
-     * - ✅ No base64 decoding required
-     * - ✅ Direct access to username and password
-     * - ✅ Better error messages
-     * - ✅ Works with multiple connections
-     */
-    log.info('Retrieving SFTP credentials from activation.connections');
-
-    let sftpUsername: string;
-    let sftpPassword: string;
-    let sftpHost: string;
-
-    try {
-      // Get ALL connections from activation
-      const allConnections = activation.connections || [];
-
-      log.debug('Available connections', {
-        names: allConnections.map(c => c.name)
-      });
-
-      // Find the SFTP connection by name
-      const sftpConnection = allConnections.find(c => c.name === 'versori_ftp_server');
-
-      if (!sftpConnection) {
-        throw new Error(
-          `SFTP connection 'versori_ftp_server' not found. ` +
-          `Available connections: ${allConnections.map(c => c.name).join(', ')}`
-        );
-      }
-
-      // Extract credential data
-      const sftpCred = sftpConnection.credentials[0]?.credential;
-
-      if (!sftpCred?.data?.basicAuth) {
-        throw new Error(
-          'SFTP connection is not configured with Basic Authentication. ' +
-          'Please configure username and password in the Versori connection settings.'
-        );
-      }
-
-      // ⭐ ALREADY DECODED - No Buffer.from needed!
-      sftpUsername = sftpCred.data.basicAuth.username;
-      sftpPassword = sftpCred.data.basicAuth.password;
-      sftpHost = sftpConnection.baseUrl || 'sftp.example.com';
-
-      log.info('SFTP credentials retrieved successfully', {
-        username: sftpUsername,
-        host: sftpHost,
-        hasPassword: !!sftpPassword,
-        passwordLength: sftpPassword.length
-      });
-
-    } catch (error: any) {
-      log.error('Failed to retrieve SFTP credentials', {
-        error: error?.message,
-        stack: error?.stack
-      });
-
-      return {
-        success: false,
-        error: 'Failed to retrieve SFTP credentials',
-        details: error?.message,
-        recommendation: [
-          'Ensure the SFTP connection is configured in Versori:',
-          '1. Connection name: "versori_ftp_server"',
-          '2. Auth type: Basic Authentication',
-          '3. Username and password configured',
-          '4. BaseUrl set (optional, for host)'
-        ].join('\n')
-      };
-    }
-
-    // ========================================
-    // USE CREDENTIALS WITH SFTP
-    // ========================================
-
-    const sftp = new SftpDataSource({
-      host: sftpHost,
-      port: 22,
-      username: sftpUsername,
-      password: sftpPassword
-    }, log);
-
-    log.info('Connecting to SFTP server', { host: sftpHost });
-
-    try {
-      const files = await sftp.listFiles('/inbound');
-      log.info('Files retrieved from SFTP', { count: files.length });
-
-      return {
-        success: true,
-        fileCount: files.length,
-        host: sftpHost,
-        method: 'activation.connections (recommended)'
-      };
-
-    } catch (error: any) {
-      log.error('SFTP operation failed', {
-        error: error?.message,
-        host: sftpHost
-      });
-      throw error;
-    }
-  }));
-```
-
----
-
-## 🔐 Versori Connection Setup
-
-### Step 1: Create Connection in Versori UI
-
-1. Go to **Connections** section in Versori
-2. Click **"Add Connection"**
-3. Choose **Basic Authentication** type
-4. Configure:
-   - **Name:** `versori_ftp_server` (must match code)
-   - **Username:** Your SFTP username
-   - **Password:** Your SFTP password
-   - **BaseUrl:** `sftp.example.com` (optional - for host)
-
-### Step 2: Verify Connection Structure
-
-Use this debug connector to inspect your connection:
-
-```typescript
-import { webhook, fn } from '@versori/run';
-
-export const debugConnection = webhook("debug-sftp-connection")
-  .then(fn("inspect", async (ctx) => {
-    const { activation } = ctx;
-
-    const allConnections = activation.connections || [];
-    const sftpConn = allConnections.find(c => c.name === 'versori_ftp_server');
-
-    if (!sftpConn) {
-      return {
-        error: "Connection 'versori_ftp_server' not found",
-        available: allConnections.map(c => c.name)
-      };
-    }
-
-    const cred = sftpConn.credentials[0]?.credential;
-
-    return {
-      connectionName: sftpConn.name,
-      hasBasicAuth: !!cred?.data?.basicAuth,
-      hasUsername: !!cred?.data?.basicAuth?.username,
-      hasPassword: !!cred?.data?.basicAuth?.password,
-      username: cred?.data?.basicAuth?.username,
-      baseUrl: sftpConn.baseUrl,
-      // Don't log the actual password!
-      passwordLength: cred?.data?.basicAuth?.password?.length
-    };
-  }));
-
-// Call: GET https://your-versori-url/debug-sftp-connection
-```
-
----
-
-## 🎯 Decision Guide
-
-```
-Need SFTP credentials?
-├─ In http() task?
-│  └─ Can use connectionVariables? (single connection in http() parameter)
-│     ├─ YES → Use connectionVariables.username/password (SIMPLEST!)
-│     └─ NO → Use activation.connections ✅
-│
-└─ In fn() task?
-   ├─ Only one connection needed?
-   │  ├─ Use activation.connections ✅ (RECOMMENDED)
-   │  └─ Or credentials().getAccessToken() (if you must)
-   │
-   └─ Multiple connections?
-      └─ Use activation.connections ✅ (REQUIRED)
-```
-
----
-
-## 🔒 Security Best Practices
-
-### 1. Never Log Credentials
-
-```typescript
-// ❌ BAD - Logs password
-log.info('SFTP config', { username, password });
-
-// ✅ GOOD - Logs without password
-log.info('SFTP config', {
-  username,
-  hasPassword: !!password,
-  passwordLength: password.length,
-  host
-});
-```
-
-### 2. Validate Credentials
-
-```typescript
-// ✅ Check before using
-if (!sftpUsername || !sftpPassword) {
-  throw new Error('Missing SFTP credentials');
-}
-
-if (sftpPassword.length < 8) {
-  log.warn('SFTP password seems short', { length: sftpPassword.length });
-}
-```
-
-### 3. Handle Missing Connections
-
-```typescript
-// ✅ Provide helpful error messages
-const sftpConn = allConnections.find(c => c.name === 'versori_ftp_server');
-
-if (!sftpConn) {
-  throw new Error(
-    `SFTP connection not found. Available: ${allConnections.map(c => c.name).join(', ')}`
-  );
-}
-```
-
-### 4. Use Connection Configuration (Not Integration Variables)
-
-```typescript
-// ❌ BAD - Credentials in code or integration variables
-const username = 'hardcoded-user';
-const password = process.env.SFTP_PASSWORD;
-
-// ✅ GOOD - From connection configuration
-const { username, password } = sftpCred.data.basicAuth;
-```
-
----
-
-## 📊 Comparison Summary
-
-| Feature | credentials().getAccessToken() | activation.connections |
-|---------|-------------------|----------------------|
-| **Decoding** | ⚠️ Manual base64 | ✅ Already decoded |
-| **Complexity** | Medium (3-4 steps) | Low (2 steps) |
-| **Error Handling** | Custom string parsing | Type-safe access |
-| **Task Type** | fn() only | Any (fn, http, webhook) |
-| **Multiple Connections** | One at a time | All at once |
-| **Recommended** | ❌ No | ✅ **YES** |
-
----
-
-## ✅ Recommendations
-
-### For New Code
-
-**Use `activation.connections` (Method 2):**
-
-```typescript
-const allConns = ctx.activation.connections || [];
-const sftpConn = allConns.find(c => c.name === 'versori_ftp_server');
-const { username, password } = sftpConn.credentials[0].credential.data.basicAuth;
-```
-
-**Why:**
-- ✅ No decoding needed
-- ✅ Cleaner code
-- ✅ Better error messages
-- ✅ Works everywhere
-
-### For Existing Code
-
-**If using `credentials().getAccessToken()`:**
-
-1. ✅ **Use correct method:** `.getAccessToken()` (not `.get()`)
-2. ✅ **Add Buffer import:** `import { Buffer } from 'node:buffer';`
-3. ✅ **Add error handling** for missing credentials
-4. ⚠️ **Consider migrating** to `activation.connections` for cleaner code
-
----
-
-## 🔍 Troubleshooting
-
-### Error: "credentials is not a function"
-
-```typescript
-// ❌ Missing ctx
-const creds = credentials().getAccessToken('SFTP');
-
-// ✅ Call from ctx
-const creds = await ctx.credentials().getAccessToken('SFTP');
-```
-
-### Error: "getAccessToken is not a function"
-
-```typescript
-// ✅ Correct method
-const cred = await ctx.credentials().getAccessToken('SFTP');
-
-// Make sure you're calling from ctx:
-const { credentials } = ctx;
-const cred = await credentials().getAccessToken('SFTP');
-```
-
-### Error: "Buffer is not defined"
-
-```typescript
-// ❌ Missing import
-const decoded = Buffer.from(base64, 'base64').toString('utf-8');
-
-// ✅ Add import
-import { Buffer } from 'node:buffer';
-const decoded = Buffer.from(base64, 'base64').toString('utf-8');
-```
-
-### Credentials are undefined
-
-```typescript
-// ✅ Check connection exists
-const sftpConn = allConnections.find(c => c.name === 'versori_ftp_server');
-if (!sftpConn) {
-  ctx.log.error('Connection not found', {
-    requested: 'versori_ftp_server',
-    available: allConnections.map(c => c.name)
-  });
-}
-```
-
----
-
-## 📚 Related Documentation
-
-- **Versori Expert Skill:** Complete credential access patterns for all connection types
-- **SFTP Complete Guide:** Full SFTP usage documentation
-- **Connection Handling:** Multi-connection workflows
-- **[SFTP Operations Guide](./modules/data-sources-03-sftp-operations.md)** - Complete SFTP integration patterns
-
----
-
-## Migration Checklist
-
-If you have workflows using the old pattern, follow these steps:
-
-### 1. Update Code
-- [ ] Replace old pattern with recommended pattern (activation.connections)
-- [ ] Add comprehensive error handling
-- [ ] Update variable names (`sftpUsername`, `sftpPassword`)
-- [ ] Add detailed logging
-- [ ] Add user-friendly error handling
-
-### 2. Configure Connection
-- [ ] Create SFTP connection in Versori UI
-- [ ] Set authentication type to Basic Auth
-- [ ] Enter username and password
-- [ ] Test connection
-
-### 3. Update Activation Variables
-- [ ] Remove `sftpUsername` from activation variables (if stored there)
-- [ ] Remove `sftpPassword` from activation variables (if stored there)
-- [ ] Keep `sftpHost`, `sftpPort`, paths in activation variables
-
-### 4. Test
-- [ ] Test credential retrieval with valid connection
-- [ ] Test error handling with missing connection
-- [ ] Test error handling with malformed credentials
-- [ ] Verify logging output
-
----
-
-**Generated:** 2025-10-29
-**Platform:** Versori
+# SFTP Credential Access & Security Best Practices
+
+**For Versori Platform Integration**
+
+---
+
+## 🎯 Overview
+
+This guide covers the **secure retrieval of SFTP credentials** in Versori platform connectors. We'll show **two approaches** - one using `credentials()` API and one using `activation.connections` (recommended).
+
+**Key Principle:** Never hardcode credentials in code - always use Versori connection configuration.
+
+> **Note:** This guide consolidates the canonical pattern documentation. For production-ready patterns with comprehensive error handling, see the Method 1 section below.
+
+---
+
+## 📋 The Two Approaches
+
+| Approach | Method | Decoding | Complexity | Recommended |
+|----------|--------|----------|------------|-------------|
+| **Method 1** | `credentials().getAccessToken()` | ⚠️ Base64 | Medium | ❌ More work |
+| **Method 2** | `activation.connections` | ✅ None | Low | ✅ **BEST** |
+
+---
+
+## ✅ Correct Method: credentials().getAccessToken()
+
+```typescript
+// ✅ CORRECT - Use .getAccessToken()
+const sftpCred = await ctx.credentials().getAccessToken('SFTP');
+```
+
+---
+
+## Method 1: credentials() API (Your Corrected Code)
+
+**Use when:** Working in `fn()` tasks where `connectionVariables` not available
+
+### ✅ Corrected Implementation
+
+```typescript
+import { schedule, fn } from '@versori/run';
+import { Buffer } from 'node:buffer';  // ⭐ Required for Deno runtime!
+import { SftpDataSource } from '@fluentcommerce/fc-connect-sdk';
+
+export const sftpWorkflow = schedule("sftp-sync", "0 * * * *")
+  .then(fn("get-files", async (ctx) => {
+    const { log } = ctx;
+
+    // ========================================
+    // SFTP CREDENTIAL RETRIEVAL
+    // ========================================
+
+    /**
+     * Retrieve SFTP credentials from connection configuration
+     *
+     * This approach retrieves credentials stored in the Versori connection settings.
+     * The connection must be configured in the UI with Basic Authentication.
+     *
+     * Steps:
+     * 1. Call ctx.credentials().getAccessToken('SFTP') to get base64-encoded credentials
+     * 2. Decode the accessToken from base64 to get "username:password" string
+     * 3. Split on ':' to extract username and password
+     *
+     * Connection Name: 'SFTP' (must match the connection name in Versori UI)
+     * Auth Type: Basic Authentication (username + password)
+     *
+     * This method provides:
+     * - Centralized credential management through Versori UI
+     * - Better security (credentials not stored in integration variables)
+     * - Easier credential rotation and updates
+     */
+    log.info('Retrieving SFTP credentials from connection configuration');
+
+    let sftpUsername: string;
+    let sftpPassword: string;
+
+    try {
+      // Retrieve credentials from the 'SFTP' connection
+      const sftpCred = await ctx.credentials().getAccessToken('SFTP');
+
+      if (!sftpCred?.accessToken) {
+        throw new Error('No SFTP credentials found in connection configuration');
+      }
+
+      // Decode base64 accessToken to get "username:password"
+      const rawBasicAuth = Buffer.from(sftpCred.accessToken, 'base64').toString('utf-8');
+
+      // Split on ':' to extract username and password
+      const parts = rawBasicAuth.split(':');
+
+      if (parts.length !== 2) {
+        throw new Error('Invalid SFTP credential format - expected username:password');
+      }
+
+      sftpUsername = parts[0];
+      sftpPassword = parts[1];
+
+      log.info('SFTP credentials retrieved successfully', {
+        hasUsername: !!sftpUsername,
+        hasPassword: !!sftpPassword,
+        usernameLength: sftpUsername.length,
+        passwordLength: sftpPassword.length,
+      });
+    } catch (error: any) {
+      log.error('Failed to retrieve SFTP credentials', {
+        error: error?.message,
+        stack: error?.stack,
+      });
+
+      return {
+        success: false,
+        error: 'Failed to retrieve SFTP credentials from connection configuration',
+        details: error?.message,
+        recommendation: 'Please ensure the SFTP connection is configured in the Connections section with Basic Authentication (username and password)',
+      };
+    }
+
+    // ========================================
+    // USE CREDENTIALS WITH SFTP
+    // ========================================
+
+    const sftp = new SftpDataSource({
+      host: 'sftp.example.com',
+      port: 22,
+      username: sftpUsername,
+      password: sftpPassword
+    }, log);
+
+    const files = await sftp.listFiles('/inbound');
+    log.info('Files retrieved', { count: files.length });
+
+    return { success: true, fileCount: files.length };
+  }));
+```
+
+### ⚠️ Limitations of Method 1
+
+**Why this is NOT the best approach:**
+
+1. ❌ **Requires base64 decoding** - Extra complexity
+2. ❌ **Only works in `fn()` tasks** - Not in `http()` tasks with `connectionVariables`
+3. ❌ **More error-prone** - Manual string splitting
+4. ❌ **Depends on connection structure** - Assumes `accessToken` field exists
+
+---
+
+## ✅ Method 2: activation.connections (RECOMMENDED!)
+
+**Use when:** Any task type - **PREFERRED for all cases**
+
+### Why This Is Better
+
+✅ **Already Decoded** - No Buffer.from() needed!
+✅ **Works Everywhere** - fn(), http(), webhook() tasks
+✅ **Type-Safe** - Direct access to credential structure
+✅ **Cleaner Code** - Fewer steps, less error handling
+
+### Complete Implementation
+
+```typescript
+import { schedule, http } from '@versori/run';
+import { SftpDataSource } from '@fluentcommerce/fc-connect-sdk';
+
+export const sftpWorkflowRecommended = schedule("sftp-sync-best", "0 * * * *")
+  .then(http("process", { connection: "fluent_commerce" }, async (ctx) => {
+    const { activation, log } = ctx;
+
+    // ========================================
+    // SFTP CREDENTIAL RETRIEVAL (RECOMMENDED APPROACH)
+    // ========================================
+
+    /**
+     * Retrieve SFTP credentials using activation.connections
+     *
+     * This is the RECOMMENDED approach because:
+     * 1. Credentials are ALREADY DECODED (no Buffer.from needed!)
+     * 2. Works in any task type (fn, http, webhook)
+     * 3. Type-safe access to credential structure
+     * 4. Cleaner, more maintainable code
+     *
+     * Connection Name: 'versori_ftp_server' (must match Versori UI)
+     * Auth Type: Basic Authentication (username + password)
+     *
+     * Benefits:
+     * - ✅ No base64 decoding required
+     * - ✅ Direct access to username and password
+     * - ✅ Better error messages
+     * - ✅ Works with multiple connections
+     */
+    log.info('Retrieving SFTP credentials from activation.connections');
+
+    let sftpUsername: string;
+    let sftpPassword: string;
+    let sftpHost: string;
+
+    try {
+      // Get ALL connections from activation
+      const allConnections = activation.connections || [];
+
+      log.debug('Available connections', {
+        names: allConnections.map(c => c.name)
+      });
+
+      // Find the SFTP connection by name
+      const sftpConnection = allConnections.find(c => c.name === 'versori_ftp_server');
+
+      if (!sftpConnection) {
+        throw new Error(
+          `SFTP connection 'versori_ftp_server' not found. ` +
+          `Available connections: ${allConnections.map(c => c.name).join(', ')}`
+        );
+      }
+
+      // Extract credential data
+      const sftpCred = sftpConnection.credentials[0]?.credential;
+
+      if (!sftpCred?.data?.basicAuth) {
+        throw new Error(
+          'SFTP connection is not configured with Basic Authentication. ' +
+          'Please configure username and password in the Versori connection settings.'
+        );
+      }
+
+      // ⭐ ALREADY DECODED - No Buffer.from needed!
+      sftpUsername = sftpCred.data.basicAuth.username;
+      sftpPassword = sftpCred.data.basicAuth.password;
+      sftpHost = sftpConnection.baseUrl || 'sftp.example.com';
+
+      log.info('SFTP credentials retrieved successfully', {
+        username: sftpUsername,
+        host: sftpHost,
+        hasPassword: !!sftpPassword,
+        passwordLength: sftpPassword.length
+      });
+
+    } catch (error: any) {
+      log.error('Failed to retrieve SFTP credentials', {
+        error: error?.message,
+        stack: error?.stack
+      });
+
+      return {
+        success: false,
+        error: 'Failed to retrieve SFTP credentials',
+        details: error?.message,
+        recommendation: [
+          'Ensure the SFTP connection is configured in Versori:',
+          '1. Connection name: "versori_ftp_server"',
+          '2. Auth type: Basic Authentication',
+          '3. Username and password configured',
+          '4. BaseUrl set (optional, for host)'
+        ].join('\n')
+      };
+    }
+
+    // ========================================
+    // USE CREDENTIALS WITH SFTP
+    // ========================================
+
+    const sftp = new SftpDataSource({
+      host: sftpHost,
+      port: 22,
+      username: sftpUsername,
+      password: sftpPassword
+    }, log);
+
+    log.info('Connecting to SFTP server', { host: sftpHost });
+
+    try {
+      const files = await sftp.listFiles('/inbound');
+      log.info('Files retrieved from SFTP', { count: files.length });
+
+      return {
+        success: true,
+        fileCount: files.length,
+        host: sftpHost,
+        method: 'activation.connections (recommended)'
+      };
+
+    } catch (error: any) {
+      log.error('SFTP operation failed', {
+        error: error?.message,
+        host: sftpHost
+      });
+      throw error;
+    }
+  }));
+```
+
+---
+
+## 🔐 Versori Connection Setup
+
+### Step 1: Create Connection in Versori UI
+
+1. Go to **Connections** section in Versori
+2. Click **"Add Connection"**
+3. Choose **Basic Authentication** type
+4. Configure:
+   - **Name:** `versori_ftp_server` (must match code)
+   - **Username:** Your SFTP username
+   - **Password:** Your SFTP password
+   - **BaseUrl:** `sftp.example.com` (optional - for host)
+
+### Step 2: Verify Connection Structure
+
+Use this debug connector to inspect your connection:
+
+```typescript
+import { webhook, fn } from '@versori/run';
+
+export const debugConnection = webhook("debug-sftp-connection")
+  .then(fn("inspect", async (ctx) => {
+    const { activation } = ctx;
+
+    const allConnections = activation.connections || [];
+    const sftpConn = allConnections.find(c => c.name === 'versori_ftp_server');
+
+    if (!sftpConn) {
+      return {
+        error: "Connection 'versori_ftp_server' not found",
+        available: allConnections.map(c => c.name)
+      };
+    }
+
+    const cred = sftpConn.credentials[0]?.credential;
+
+    return {
+      connectionName: sftpConn.name,
+      hasBasicAuth: !!cred?.data?.basicAuth,
+      hasUsername: !!cred?.data?.basicAuth?.username,
+      hasPassword: !!cred?.data?.basicAuth?.password,
+      username: cred?.data?.basicAuth?.username,
+      baseUrl: sftpConn.baseUrl,
+      // Don't log the actual password!
+      passwordLength: cred?.data?.basicAuth?.password?.length
+    };
+  }));
+
+// Call: GET https://your-versori-url/debug-sftp-connection
+```
+
+---
+
+## 🎯 Decision Guide
+
+```
+Need SFTP credentials?
+├─ In http() task?
+│  └─ Can use connectionVariables? (single connection in http() parameter)
+│     ├─ YES → Use connectionVariables.username/password (SIMPLEST!)
+│     └─ NO → Use activation.connections ✅
+│
+└─ In fn() task?
+   ├─ Only one connection needed?
+   │  ├─ Use activation.connections ✅ (RECOMMENDED)
+   │  └─ Or credentials().getAccessToken() (if you must)
+   │
+   └─ Multiple connections?
+      └─ Use activation.connections ✅ (REQUIRED)
+```
+
+---
+
+## 🔒 Security Best Practices
+
+### 1. Never Log Credentials
+
+```typescript
+// ❌ BAD - Logs password
+log.info('SFTP config', { username, password });
+
+// ✅ GOOD - Logs without password
+log.info('SFTP config', {
+  username,
+  hasPassword: !!password,
+  passwordLength: password.length,
+  host
+});
+```
+
+### 2. Validate Credentials
+
+```typescript
+// ✅ Check before using
+if (!sftpUsername || !sftpPassword) {
+  throw new Error('Missing SFTP credentials');
+}
+
+if (sftpPassword.length < 8) {
+  log.warn('SFTP password seems short', { length: sftpPassword.length });
+}
+```
+
+### 3. Handle Missing Connections
+
+```typescript
+// ✅ Provide helpful error messages
+const sftpConn = allConnections.find(c => c.name === 'versori_ftp_server');
+
+if (!sftpConn) {
+  throw new Error(
+    `SFTP connection not found. Available: ${allConnections.map(c => c.name).join(', ')}`
+  );
+}
+```
+
+### 4. Use Connection Configuration (Not Integration Variables)
+
+```typescript
+// ❌ BAD - Credentials in code or integration variables
+const username = 'hardcoded-user';
+const password = process.env.SFTP_PASSWORD;
+
+// ✅ GOOD - From connection configuration
+const { username, password } = sftpCred.data.basicAuth;
+```
+
+---
+
+## 📊 Comparison Summary
+
+| Feature | credentials().getAccessToken() | activation.connections |
+|---------|-------------------|----------------------|
+| **Decoding** | ⚠️ Manual base64 | ✅ Already decoded |
+| **Complexity** | Medium (3-4 steps) | Low (2 steps) |
+| **Error Handling** | Custom string parsing | Type-safe access |
+| **Task Type** | fn() only | Any (fn, http, webhook) |
+| **Multiple Connections** | One at a time | All at once |
+| **Recommended** | ❌ No | ✅ **YES** |
+
+---
+
+## ✅ Recommendations
+
+### For New Code
+
+**Use `activation.connections` (Method 2):**
+
+```typescript
+const allConns = ctx.activation.connections || [];
+const sftpConn = allConns.find(c => c.name === 'versori_ftp_server');
+const { username, password } = sftpConn.credentials[0].credential.data.basicAuth;
+```
+
+**Why:**
+- ✅ No decoding needed
+- ✅ Cleaner code
+- ✅ Better error messages
+- ✅ Works everywhere
+
+### For Existing Code
+
+**If using `credentials().getAccessToken()`:**
+
+1. ✅ **Use correct method:** `.getAccessToken()` (not `.get()`)
+2. ✅ **Add Buffer import:** `import { Buffer } from 'node:buffer';`
+3. ✅ **Add error handling** for missing credentials
+4. ⚠️ **Consider migrating** to `activation.connections` for cleaner code
+
+---
+
+## 🔍 Troubleshooting
+
+### Error: "credentials is not a function"
+
+```typescript
+// ❌ Missing ctx
+const creds = credentials().getAccessToken('SFTP');
+
+// ✅ Call from ctx
+const creds = await ctx.credentials().getAccessToken('SFTP');
+```
+
+### Error: "getAccessToken is not a function"
+
+```typescript
+// ✅ Correct method
+const cred = await ctx.credentials().getAccessToken('SFTP');
+
+// Make sure you're calling from ctx:
+const { credentials } = ctx;
+const cred = await credentials().getAccessToken('SFTP');
+```
+
+### Error: "Buffer is not defined"
+
+```typescript
+// ❌ Missing import
+const decoded = Buffer.from(base64, 'base64').toString('utf-8');
+
+// ✅ Add import
+import { Buffer } from 'node:buffer';
+const decoded = Buffer.from(base64, 'base64').toString('utf-8');
+```
+
+### Credentials are undefined
+
+```typescript
+// ✅ Check connection exists
+const sftpConn = allConnections.find(c => c.name === 'versori_ftp_server');
+if (!sftpConn) {
+  ctx.log.error('Connection not found', {
+    requested: 'versori_ftp_server',
+    available: allConnections.map(c => c.name)
+  });
+}
+```
+
+---
+
+## 📚 Related Documentation
+
+- **Versori Expert Skill:** Complete credential access patterns for all connection types
+- **SFTP Complete Guide:** Full SFTP usage documentation
+- **Connection Handling:** Multi-connection workflows
+- **[SFTP Operations Guide](./modules/data-sources-03-sftp-operations.md)** - Complete SFTP integration patterns
+
+---
+
+## Migration Checklist
+
+If you have workflows using the old pattern, follow these steps:
+
+### 1. Update Code
+- [ ] Replace old pattern with recommended pattern (activation.connections)
+- [ ] Add comprehensive error handling
+- [ ] Update variable names (`sftpUsername`, `sftpPassword`)
+- [ ] Add detailed logging
+- [ ] Add user-friendly error handling
+
+### 2. Configure Connection
+- [ ] Create SFTP connection in Versori UI
+- [ ] Set authentication type to Basic Auth
+- [ ] Enter username and password
+- [ ] Test connection
+
+### 3. Update Activation Variables
+- [ ] Remove `sftpUsername` from activation variables (if stored there)
+- [ ] Remove `sftpPassword` from activation variables (if stored there)
+- [ ] Keep `sftpHost`, `sftpPort`, paths in activation variables
+
+### 4. Test
+- [ ] Test credential retrieval with valid connection
+- [ ] Test error handling with missing connection
+- [ ] Test error handling with malformed credentials
+- [ ] Verify logging output
+
+---
+
+**Generated:** 2025-10-29
+**Platform:** Versori