@salesforce/afv-skills 1.8.0 → 1.9.0

package/skills/configuring-connected-apps/references/security-checklist.md

@@ -0,0 +1,209 @@
+<!-- Parent: configuring-connected-apps/SKILL.md -->
+# Security Checklist for Connected Apps & ECAs
+
+Use this checklist before deploying any OAuth application to production.
+
+## Pre-Deployment Checklist
+
+### OAuth Configuration
+
+- [ ] **Callback URLs are specific** (no wildcards)
+- [ ] **All URLs use HTTPS** (required for production)
+- [ ] **PKCE is enabled** for public clients (mobile, SPA)
+- [ ] **Consumer secret is protected** (not in source control)
+- [ ] **Minimal scopes selected** (principle of least privilege)
+- [ ] **No deprecated scopes** in use
+
+### Token Policies
+
+- [ ] **Access token expiration** is configured appropriately
+- [ ] **Refresh token policy** matches use case
+  - `infinite` only for trusted server applications
+  - `specific_lifetime` for user-facing apps
+  - `zero` for JWT Bearer flows
+- [ ] **Token rotation enabled** for ECAs in production
+- [ ] **IP restrictions configured** for server-to-server apps
+
+### Access Control
+
+- [ ] **Admin pre-authorization** required for sensitive apps
+- [ ] **User assignment via Permission Set** or Profile
+- [ ] **Connected App policies** reviewed in Setup
+- [ ] **High Assurance session** required if needed
+
+### External Client Apps (Additional)
+
+- [ ] **Distribution state** correctly set (Local vs Packageable)
+- [ ] **Consumer key rotation** enabled for production
+- [ ] **Consumer secret rotation** enabled for production
+- [ ] **Policies file** reviewed after first deployment
+
+---
+
+## Security Scoring Criteria
+
+### Critical (Block Deployment)
+
+| Issue | Impact | Fix |
+|-------|--------|-----|
+| Wildcard callback URL | Token hijacking | Use specific URLs |
+| HTTP callback URL | Credential interception | Use HTTPS only |
+| Full scope without justification | Over-privileged access | Use minimal scopes |
+| Consumer secret in code | Credential leak | Use environment variables |
+
+### High Priority
+
+| Issue | Impact | Fix |
+|-------|--------|-----|
+| PKCE disabled for mobile/SPA | Auth code interception | Enable PKCE |
+| No IP restrictions (server) | Unauthorized access | Configure IP ranges |
+| Infinite refresh tokens (user app) | Long-term compromise | Set expiration |
+| No token rotation (ECA) | Compromised credentials | Enable rotation |
+
+### Medium Priority
+
+| Issue | Impact | Fix |
+|-------|--------|-----|
+| Missing description | Audit difficulty | Add clear description |
+| Generic contact email | Incident response delay | Use team email |
+| Introspection disabled | Token validation gaps | Enable if needed |
+| No logout URL | Session persistence | Configure logout |
+
+---
+
+## Scope Security Guide
+
+### Recommended Scopes by Use Case
+
+| Use Case | Recommended Scopes |
+|----------|-------------------|
+| API Integration | `Api`, `RefreshToken` |
+| User Authentication | `OpenID`, `Profile`, `Email` |
+| Full API + Identity | `Api`, `RefreshToken`, `OpenID`, `Profile` |
+| Chatter Integration | `Api`, `ChatterApi` |
+| Server-to-Server | `Api` only |
+
+### Scopes to Avoid
+
+| Scope | Risk | Alternative |
+|-------|------|-------------|
+| `Full` | Complete access to everything | Use specific scopes |
+| `Web` + `Api` together | Redundant, increases attack surface | Choose one |
+| `RefreshToken` for JWT | Unnecessary, JWT generates new tokens | Remove scope |
+
+---
+
+## IP Restriction Policies
+
+### Policy Options
+
+| Policy | Description | Use Case |
+|--------|-------------|----------|
+| `ENFORCE` | Strict IP enforcement | Production server-to-server |
+| `BYPASS` | No IP restrictions | Development only |
+| `ENFORCE_ACTIVATED_USERS` | Enforce for active users | Mixed environments |
+
+### Recommended Configuration
+
+```xml
+<!-- Production: Server-to-Server -->
+<oauthPolicy>
+    <ipRelaxation>ENFORCE</ipRelaxation>
+</oauthPolicy>
+
+<!-- Production: User-Facing -->
+<oauthPolicy>
+    <ipRelaxation>ENFORCE_ACTIVATED_USERS</ipRelaxation>
+</oauthPolicy>
+
+<!-- Development Only -->
+<oauthPolicy>
+    <ipRelaxation>BYPASS</ipRelaxation>
+</oauthPolicy>
+```
+
+---
+
+## Certificate Management (JWT Bearer)
+
+### Certificate Requirements
+
+- [ ] RSA 2048-bit or higher key size
+- [ ] Valid not-before and not-after dates
+- [ ] Uploaded to Salesforce Certificate and Key Management
+- [ ] Private key stored securely (HSM, Vault, secure storage)
+
+### Certificate Rotation
+
+1. Generate new certificate before expiration
+2. Upload new certificate to Salesforce
+3. Update Connected App to use new certificate
+4. Update external system with new private key
+5. Test authentication
+6. Remove old certificate after transition period
+
+---
+
+## Monitoring & Audit
+
+### What to Monitor
+
+- [ ] **Login History** for Connected App users
+- [ ] **OAuth Usage** in Setup
+- [ ] **Event Monitoring** for token events (Shield required)
+- [ ] **API Usage** limits and patterns
+
+### Audit Checklist
+
+- [ ] Review Connected Apps quarterly
+- [ ] Remove unused applications
+- [ ] Rotate credentials annually
+- [ ] Verify scope appropriateness
+- [ ] Check for policy violations
+
+---
+
+## Incident Response
+
+### If Credentials Are Compromised
+
+1. **Immediately** rotate Consumer Secret
+2. Revoke all active tokens
+3. Review login and access logs
+4. Update external systems with new credentials
+5. Investigate scope of compromise
+6. Document and report incident
+
+### Commands for Response
+
+```bash
+# List all Connected Apps
+sf org list metadata --metadata-type ConnectedApp --target-org <org>
+
+# Retrieve for review
+sf project retrieve start --metadata ConnectedApp:<AppName> --target-org <org>
+```
+
+---
+
+## Compliance Considerations
+
+### GDPR/Privacy
+
+- Ensure data access matches user consent
+- Document data flows through Connected Apps
+- Implement data retention policies
+
+### SOC 2
+
+- Enable audit logging
+- Implement access reviews
+- Document security controls
+- Use certificate-based authentication
+
+### HIPAA
+
+- Enable High Assurance sessions
+- Restrict data access scopes
+- Implement IP restrictions
+- Use encrypted connections only

package/skills/configuring-connected-apps/references/testing-validation-guide.md

@@ -0,0 +1,275 @@
+<!-- Parent: configuring-connected-apps/SKILL.md -->
+# Testing & Validation Guide
+
+This guide documents tested External Client App (ECA) and Connected App patterns based on systematic validation testing (December 2025).
+
+## Test Matrix
+
+| Component Type | Template / Source | Test Status |
+|----------------|-------------------|-------------|
+| Connected App (Basic) | `connected-app-basic.xml` | ✅ Verified |
+| Connected App (Full OAuth) | `connected-app-oauth.xml` | ✅ Verified |
+| Connected App (JWT Bearer) | `connected-app-jwt.xml` | ✅ Verified |
+| Connected App (Canvas) | `connected-app-canvas.xml` | ⚠️ Location-dependent |
+| External Client App | `external-client-app.xml` | ✅ Verified |
+| ECA Global OAuth | `eca-global-oauth.xml` | ✅ Verified |
+| ECA OAuth Settings | `eca-oauth-settings.xml` | ✅ Verified |
+| ECA OAuth Security Settings | retrieve-first (`ExtlClntAppOauthSecuritySettings`) | ✅ CLI/registry-supported |
+| ECA Configurable Policies | `eca-policies.xml` | ✅ Naming updated |
+
+---
+
+## Critical File Naming Conventions
+
+### External Client App Files
+
+| Metadata Type | Source Directory | File Suffix | Example |
+|--------------|------------------|-------------|---------|
+| ExternalClientApplication | `externalClientApps/` | `.eca-meta.xml` | `externalClientApps/MyApp.eca-meta.xml` |
+| ExtlClntAppOauthSettings | `extlClntAppOauthSettings/` | `.ecaOauth-meta.xml` | `extlClntAppOauthSettings/MyApp.ecaOauth-meta.xml` |
+| ExtlClntAppGlobalOauthSettings | `extlClntAppGlobalOauthSets/` | `.ecaGlblOauth-meta.xml` | `extlClntAppGlobalOauthSets/MyApp.ecaGlblOauth-meta.xml` |
+| ExtlClntAppOauthSecuritySettings | `extlClntAppOauthSecuritySettings/` | `.ecaOauthSecurity-meta.xml` | `extlClntAppOauthSecuritySettings/MyApp.ecaOauthSecurity-meta.xml` |
+| ExtlClntAppOauthConfigurablePolicies | `extlClntAppOauthPolicies/` | `.ecaOauthPlcy-meta.xml` | `extlClntAppOauthPolicies/MyApp.ecaOauthPlcy-meta.xml` |
+| ExtlClntAppConfigurablePolicies | `extlClntAppPolicies/` | `.ecaPlcy-meta.xml` | `extlClntAppPolicies/MyApp.ecaPlcy-meta.xml` |
+
+⚠️ **CRITICAL**:
+- Use `.ecaGlblOauth` (abbreviated), NOT `.ecaGlobalOauth`
+- Use `.ecaPlcy`, NOT `.ecaPolicy`
+- `ExtlClntAppOauthSecuritySettings` is now source-supported; prefer retrieve-first until you have an org-validated sample file
+
+### Connected App Files
+
+| Metadata Type | File Suffix | Example |
+|--------------|-------------|---------|
+| ConnectedApp | `.connectedApp-meta.xml` | `MyApp.connectedApp-meta.xml` |
+
+---
+
+## Common Deployment Errors & Solutions
+
+### Error: "Invalid or missing field" in ECA OAuth Settings
+
+**Cause**: Using wrong schema with non-existent fields
+
+**Wrong Schema (FAILS):**
+```xml
+<ExtlClntAppOauthSettings>
+    <isAdminApproved>true</isAdminApproved>           <!-- DOES NOT EXIST -->
+    <isCodeCredentialsEnabled>true</isCodeCredentialsEnabled>  <!-- DOES NOT EXIST -->
+    <scopes>Api</scopes>                               <!-- WRONG FORMAT -->
+</ExtlClntAppOauthSettings>
+```
+
+**Correct Schema:**
+```xml
+<ExtlClntAppOauthSettings xmlns="http://soap.sforce.com/2006/04/metadata">
+    <commaSeparatedOauthScopes>Api, RefreshToken</commaSeparatedOauthScopes>
+    <externalClientApplication>MyApp</externalClientApplication>
+    <label>MyApp OAuth Settings</label>
+</ExtlClntAppOauthSettings>
+```
+
+### Error: "Missing required field" in ECA Global OAuth
+
+**Cause**: Missing `externalClientApplication` or `label`
+
+**Wrong (FAILS):**
+```xml
+<ExtlClntAppGlobalOauthSettings>
+    <callbackUrl>https://example.com/callback</callbackUrl>
+    <isPkceRequired>true</isPkceRequired>
+</ExtlClntAppGlobalOauthSettings>
+```
+
+**Correct:**
+```xml
+<ExtlClntAppGlobalOauthSettings xmlns="http://soap.sforce.com/2006/04/metadata">
+    <callbackUrl>https://example.com/callback</callbackUrl>
+    <externalClientApplication>MyApp</externalClientApplication>
+    <isConsumerSecretOptional>true</isConsumerSecretOptional>
+    <isIntrospectAllTokens>false</isIntrospectAllTokens>
+    <isPkceRequired>true</isPkceRequired>
+    <isSecretRequiredForRefreshToken>false</isSecretRequiredForRefreshToken>
+    <label>MyApp Global OAuth</label>
+    <shouldRotateConsumerKey>false</shouldRotateConsumerKey>
+    <shouldRotateConsumerSecret>false</shouldRotateConsumerSecret>
+</ExtlClntAppGlobalOauthSettings>
+```
+
+### Error: "Organization is not configured to support location"
+
+**Cause**: Canvas app using location that requires org feature enablement
+
+**Problematic Locations:**
+- `AppLauncher` - Requires feature enablement
+- Some other locations may have similar requirements
+
+**Solution**: Use universally available locations:
+```xml
+<canvasApp>
+    <locations>Visualforce</locations>
+</canvasApp>
+```
+
+### Error: Certificate not found (JWT Bearer)
+
+**Cause**: Referenced certificate doesn't exist in org
+
+**Wrong:**
+```xml
+<certificate>NonExistent_Cert</certificate>
+```
+
+**Solution**: Create certificate first, then reference it:
+```bash
+# 1. Create certificate in org (Setup > Certificate and Key Management)
+# 2. Reference in Connected App
+<certificate>My_JWT_Cert</certificate>
+```
+
+---
+
+## Field Reference
+
+### ExtlClntAppOauthSettings (ECA OAuth)
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `commaSeparatedOauthScopes` | String | Yes | Comma-separated scopes (e.g., "Api, RefreshToken") |
+| `externalClientApplication` | String | Yes | Reference to parent ECA API name |
+| `label` | String | Yes | Display label |
+
+**Available Scopes:**
+- `Api` - REST/SOAP API access
+- `RefreshToken` - Offline access
+- `OpenID` - OpenID Connect
+- `Profile` - User profile info
+- `Email` - User email
+- `Web` - Web browser access
+- `ChatterApi` - Chatter REST API
+
+### ExtlClntAppGlobalOauthSettings (ECA Global OAuth)
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `callbackUrl` | URL | Yes | OAuth redirect URI |
+| `externalClientApplication` | String | Yes | Reference to parent ECA |
+| `isConsumerSecretOptional` | Boolean | No | True for public clients with PKCE |
+| `isIntrospectAllTokens` | Boolean | No | Enable token introspection |
+| `isPkceRequired` | Boolean | No | Require PKCE (recommended for public clients) |
+| `isSecretRequiredForRefreshToken` | Boolean | No | Require secret for refresh |
+| `label` | String | Yes | Display label |
+| `shouldRotateConsumerKey` | Boolean | No | Enable key rotation |
+| `shouldRotateConsumerSecret` | Boolean | No | Enable secret rotation |
+
+---
+
+## Deployment Order
+
+For External Client Apps, deploy in this order:
+
+```bash
+# 1. Deploy base ECA first
+sf project deploy start --metadata ExternalClientApplication:MyApp --target-org [alias]
+
+# 2. Deploy OAuth settings
+sf project deploy start --metadata ExtlClntAppOauthSettings:MyApp --target-org [alias]
+
+# 3. Deploy Global OAuth (if needed)
+sf project deploy start --metadata ExtlClntAppGlobalOauthSettings:MyApp --target-org [alias]
+
+# 4. Deploy companion security/policy metadata when you use it
+sf project deploy start --metadata ExtlClntAppOauthSecuritySettings:MyApp --target-org [alias]
+sf project deploy start --metadata ExtlClntAppOauthConfigurablePolicies:MyApp --target-org [alias]
+sf project deploy start --metadata ExtlClntAppConfigurablePolicies:MyApp --target-org [alias]
+
+# Or deploy the whole package directory when all ECA source directories live under it
+sf project deploy start --source-dir force-app/main/default --target-org [alias]
+```
+
+---
+
+## Post-Deployment Steps
+
+### Client Credentials Flow (ECA)
+
+Client Credentials flow still requires post-deployment admin validation. Even with broader metadata support, verify these items in Setup after deployment:
+
+1. **Create Permission Set** with "Salesforce API Integration" permission
+2. **Assign Permission Set** to the External Client App
+3. **Confirm the run-as / execution-user behavior and any org-specific OAuth security settings**
+
+### JWT Bearer Flow (Connected App)
+
+1. **Upload Certificate** to org before deployment
+2. **Pre-authorize Users** after deployment (Setup > Manage Connected Apps)
+
+---
+
+## Deployment Checklist
+
+### External Client App
+
+- [ ] `.eca-meta.xml` file exists under `externalClientApps/`
+- [ ] `.ecaOauth-meta.xml` file exists under `extlClntAppOauthSettings/`
+- [ ] `.ecaGlblOauth-meta.xml` uses abbreviated suffix under `extlClntAppGlobalOauthSets/`
+- [ ] Optional companion files use the right suffixes: `.ecaOauthSecurity`, `.ecaOauthPlcy`, `.ecaPlcy`
+- [ ] All companion files reference the same `externalClientApplication` name
+- [ ] Required files include `label` where applicable
+- [ ] `commaSeparatedOauthScopes` uses string format, not individual `<scopes>` tags
+- [ ] Callback URL is HTTPS (or custom scheme for mobile)
+- [ ] PKCE enabled for public clients
+
+### Connected App
+
+- [ ] `.connectedApp-meta.xml` file exists
+- [ ] `contactEmail` is valid
+- [ ] Callback URL matches OAuth flow requirements
+- [ ] Certificate exists in org (for JWT Bearer)
+- [ ] Canvas locations are supported by org (if using Canvas)
+
+---
+
+## Tested Configurations
+
+### Minimal ECA (API Integration)
+
+```
+Files:
+├── externalClientApps/MyApp.eca-meta.xml
+├── extlClntAppOauthSettings/MyApp.ecaOauth-meta.xml
+└── extlClntAppGlobalOauthSets/MyApp.ecaGlblOauth-meta.xml
+
+Scopes: Api, RefreshToken
+PKCE: false (confidential client)
+```
+
+### Mobile App ECA (PKCE)
+
+```
+Files:
+├── externalClientApps/MobileApp.eca-meta.xml
+├── extlClntAppOauthSettings/MobileApp.ecaOauth-meta.xml
+└── extlClntAppGlobalOauthSets/MobileApp.ecaGlblOauth-meta.xml
+
+Scopes: Api, RefreshToken, OpenID
+PKCE: true (public client)
+Callback: com.example.app://oauth/callback
+```
+
+### Server-to-Server ECA
+
+```
+Files:
+├── externalClientApps/ServiceApp.eca-meta.xml
+├── extlClntAppOauthSettings/ServiceApp.ecaOauth-meta.xml
+└── extlClntAppOauthSecuritySettings/ServiceApp.ecaOauthSecurity-meta.xml   # retrieve-first when source controlling OAuth security settings
+
+Scopes: Api
+Note: Client Credentials still requires post-deployment Permission Set assignment and admin verification
+```
+
+---
+
+*Last Updated: April 2026*
+*Based on testing with SF CLI and API v66.0*

package/skills/connecting-datacloud/CREDITS.md

@@ -0,0 +1,5 @@
+# Credits & Acknowledgments
+
+This skill is part of the `*-datacloud` family of skills covering the full Data Cloud workflow lifecycle. Shared upstream source mapping and maintenance notes live in:
+- [../orchestrating-datacloud/CREDITS.md](../orchestrating-datacloud/CREDITS.md)
+- [../orchestrating-datacloud/UPSTREAM.md](../orchestrating-datacloud/UPSTREAM.md)

package/skills/connecting-datacloud/README.md

@@ -0,0 +1,59 @@
+# connecting-datacloud
+
+Connection and connector workflows for Salesforce Data Cloud.
+
+## Use this skill for
+
+- listing available connector types
+- inspecting configured connections
+- testing a connection
+- browsing source objects, databases, fields, and uploaded schemas
+- preparing connector JSON for Snowflake, SharePoint Unstructured, and Ingestion API sources
+- preparing for stream creation
+
+## Key reminders
+
+- `connection list` requires `--connector-type`
+- `connection test` may need `--connector-type` for non-Salesforce name resolution
+- use `connection schema-upsert` after creating an Ingestion API connector
+- start with inspection before mutation
+- use `2>/dev/null` to suppress linked-plugin warning noise
+- some connector types can be created by API while downstream stream creation still requires UI flow
+
+## Example requests
+
+```text
+"Show me which Data Cloud connections already exist in this org"
+"Test my Snowflake Data Cloud connection"
+"What source objects are available on this Salesforce connector?"
+"Help me create an Ingestion API connector and upload its schema"
+"Set up a SharePoint Unstructured connection for document ingestion"
+```
+
+## Common commands
+
+```bash
+sf data360 connection connector-list -o myorg 2>/dev/null
+sf data360 connection list -o myorg --connector-type SalesforceDotCom 2>/dev/null
+sf data360 connection get -o myorg --name SalesforceDotCom_Home 2>/dev/null
+sf data360 connection test -o myorg --name Snowflake_Demo --connector-type SNOWFLAKE 2>/dev/null
+sf data360 connection schema-get -o myorg --name <connector-id> 2>/dev/null
+sf data360 connection create -o myorg -f examples/connections/heroku-postgres.json 2>/dev/null
+sf data360 connection schema-upsert -o myorg --name <connector-id> -f examples/connections/ingest-api-schema.json 2>/dev/null
+```
+
+## Example payloads
+
+- [examples/connections/heroku-postgres.json](examples/connections/heroku-postgres.json)
+- [examples/connections/redshift.json](examples/connections/redshift.json)
+- [examples/connections/sharepoint-unstructured.json](examples/connections/sharepoint-unstructured.json)
+- [examples/connections/snowflake-connection.json](examples/connections/snowflake-connection.json)
+- [examples/connections/ingest-api-connection.json](examples/connections/ingest-api-connection.json)
+- [examples/connections/ingest-api-schema.json](examples/connections/ingest-api-schema.json)
+
+## References
+
+- [SKILL.md](SKILL.md)
+- [../orchestrating-datacloud/references/plugin-setup.md](../orchestrating-datacloud/references/plugin-setup.md)
+- [../orchestrating-datacloud/UPSTREAM.md](../orchestrating-datacloud/UPSTREAM.md)
+- [CREDITS.md](CREDITS.md)