@salesforce/afv-skills 1.8.0 → 1.9.0

package/skills/generating-mermaid-diagrams/assets/oauth/authorization-code.md

@@ -0,0 +1,152 @@
+# Authorization Code Flow Template
+
+Standard OAuth 2.0 Authorization Code flow for web applications with backend servers.
+
+## When to Use
+- Web applications with secure backend servers
+- Confidential clients that can protect client_secret
+- When you need refresh tokens for long-lived access
+
+## Mermaid Template
+
+```mermaid
+%%{init: {'theme': 'base', 'themeVariables': {
+  'actorBkg': '#ddd6fe',
+  'actorTextColor': '#1f2937',
+  'actorBorder': '#6d28d9',
+  'signalColor': '#334155',
+  'signalTextColor': '#1f2937',
+  'noteBkgColor': '#f8fafc',
+  'noteTextColor': '#1f2937',
+  'noteBorderColor': '#334155'
+}}}%%
+sequenceDiagram
+    autonumber
+
+    box rgba(165,243,252,0.3) BROWSER/USER
+        participant U as 👤 User
+        participant B as 🌐 Browser
+    end
+
+    box rgba(221,214,254,0.3) CLIENT APPLICATION
+        participant A as 🖥️ App Server
+    end
+
+    box rgba(167,243,208,0.3) SALESFORCE
+        participant SF as ☁️ Salesforce<br/>Authorization Server
+    end
+
+    Note over U,SF: Authorization Code Flow (RFC 6749)
+
+    U->>B: 1. Click "Login with Salesforce"
+    B->>A: 2. Initiate OAuth Login
+
+    A->>A: 3. Generate state parameter (CSRF protection)
+
+    A->>B: 4. Redirect to Salesforce /authorize
+    Note over A,B: response_type=code<br/>client_id=CONSUMER_KEY<br/>redirect_uri=CALLBACK_URL<br/>scope=api refresh_token<br/>state=RANDOM_STATE
+
+    B->>SF: 5. GET /services/oauth2/authorize
+
+    SF->>B: 6. Display Login Page
+    U->>SF: 7. Enter Username & Password
+
+    SF->>SF: 8. Authenticate User
+
+    SF->>B: 9. Display Consent Screen
+    Note over SF,B: "App requests access to:<br/>• API Access<br/>• Refresh Token"
+
+    U->>SF: 10. Grant Consent (Allow)
+
+    SF->>SF: 11. Generate Authorization Code
+
+    SF->>B: 12. Redirect to callback_uri
+    Note over SF,B: ?code=AUTH_CODE_123<br/>&state=RANDOM_STATE
+
+    B->>A: 13. Deliver Code to App Server
+
+    A->>A: 14. Verify state matches
+
+    A->>SF: 15. POST /services/oauth2/token
+    Note over A,SF: grant_type=authorization_code<br/>code=AUTH_CODE_123<br/>client_id=CONSUMER_KEY<br/>client_secret=CONSUMER_SECRET<br/>redirect_uri=CALLBACK_URL
+
+    SF->>SF: 16. Validate Code & Client
+
+    SF->>A: 17. Return Tokens
+    Note over SF,A: {<br/>  access_token: "...",<br/>  refresh_token: "...",<br/>  instance_url: "https://...",<br/>  token_type: "Bearer",<br/>  issued_at: "..."<br/>}
+
+    A->>A: 18. Store tokens securely
+
+    A->>B: 19. Set user session
+    B->>U: 20. ✅ Successfully Logged In
+```
+
+## ASCII Fallback Template
+
+```
+┌──────────┐     ┌───────────────┐     ┌────────────────────┐
+│  User/   │     │  Application  │     │     Salesforce     │
+│  Browser │     │    Server     │     │  (Auth Server)     │
+└────┬─────┘     └───────┬───────┘     └─────────┬──────────┘
+     │                   │                       │
+     │  1. Click Login   │                       │
+     │──────────────────>│                       │
+     │                   │                       │
+     │  2. Redirect to   │                       │
+     │     /authorize    │                       │
+     │<──────────────────│                       │
+     │                   │                       │
+     │  3. GET /authorize (client_id, scope, state)         │
+     │───────────────────────────────────────────────────────>│
+     │                   │                       │
+     │           4. Login Page                   │
+     │<───────────────────────────────────────────────────────│
+     │                   │                       │
+     │  5. Enter Credentials                     │
+     │───────────────────────────────────────────────────────>│
+     │                   │                       │
+     │           6. Consent Screen               │
+     │<───────────────────────────────────────────────────────│
+     │                   │                       │
+     │  7. Grant Consent (Allow)                 │
+     │───────────────────────────────────────────────────────>│
+     │                   │                       │
+     │  8. Redirect with ?code=ABC123&state=xyz  │
+     │<───────────────────────────────────────────────────────│
+     │                   │                       │
+     │  9. Deliver Code  │                       │
+     │──────────────────>│                       │
+     │                   │                       │
+     │                   │  10. POST /token      │
+     │                   │      (code, secret)   │
+     │                   │──────────────────────>│
+     │                   │                       │
+     │                   │  11. Access Token +   │
+     │                   │      Refresh Token    │
+     │                   │<──────────────────────│
+     │                   │                       │
+     │ 12. Logged In ✅  │                       │
+     │<──────────────────│                       │
+```
+
+## Key Endpoints
+
+| Endpoint | URL | Purpose |
+|----------|-----|---------|
+| Authorization | `https://login.salesforce.com/services/oauth2/authorize` | Start OAuth flow |
+| Token | `https://login.salesforce.com/services/oauth2/token` | Exchange code for tokens |
+
+## Security Considerations
+
+1. **Always use HTTPS** for redirect_uri in production
+2. **Validate state parameter** to prevent CSRF attacks
+3. **Store client_secret securely** (never in client-side code)
+4. **Use short-lived access tokens** with refresh token rotation
+
+## Customization Points
+
+Replace these placeholders:
+- `CONSUMER_KEY` → Your Connected App's Consumer Key
+- `CONSUMER_SECRET` → Your Connected App's Consumer Secret
+- `CALLBACK_URL` → Your registered callback URL
+- `RANDOM_STATE` → Cryptographically random state value

package/skills/generating-mermaid-diagrams/assets/oauth/client-credentials.md

@@ -0,0 +1,233 @@
+# Client Credentials Flow Template
+
+OAuth 2.0 Client Credentials Grant for server-to-server authentication using client_id and client_secret.
+
+## When to Use
+- Service accounts
+- Background processes
+- System-to-system integrations
+- When no specific user context is needed
+- External Client Apps (ECAs) with client credentials enabled
+
+## Prerequisites
+1. Connected App or External Client App configured
+2. Client Credentials flow enabled
+3. Execution user assigned via Permission Set (for ECAs)
+
+## Mermaid Template
+
+```mermaid
+%%{init: {'theme': 'base', 'themeVariables': {
+  'actorBkg': '#ddd6fe',
+  'actorTextColor': '#1f2937',
+  'actorBorder': '#6d28d9',
+  'signalColor': '#334155',
+  'signalTextColor': '#1f2937',
+  'noteBkgColor': '#f8fafc',
+  'noteTextColor': '#1f2937',
+  'noteBorderColor': '#334155'
+}}}%%
+sequenceDiagram
+    autonumber
+
+    box rgba(221,214,254,0.3) CLIENT APPLICATION
+        participant C as 🖥️ Service<br/>(Backend Server)
+    end
+
+    box rgba(167,243,208,0.3) SALESFORCE
+        participant SF as ☁️ Salesforce<br/>Authorization Server
+    end
+
+    Note over C,SF: Client Credentials Flow (RFC 6749 Section 4.4)
+
+    C->>C: 1. Retrieve Client Credentials
+    Note over C: client_id = CONSUMER_KEY<br/>client_secret = CONSUMER_SECRET
+
+    C->>SF: 2. POST /services/oauth2/token
+    Note over C,SF: grant_type=client_credentials<br/>client_id=CONSUMER_KEY<br/>client_secret=CONSUMER_SECRET
+
+    SF->>SF: 3. Validate Client Credentials
+    Note over SF: Verify client_id exists<br/>Verify client_secret matches
+
+    SF->>SF: 4. Determine Execution User
+    Note over SF: For ECA: Use assigned<br/>Permission Set user<br/><br/>For Connected App: Use<br/>"Run As" user
+
+    SF->>SF: 5. Generate Access Token
+    Note over SF: Token runs in context<br/>of execution user
+
+    SF->>C: 6. Return Access Token
+    Note over SF,C: {<br/>  "access_token": "...",<br/>  "instance_url": "https://...",<br/>  "token_type": "Bearer",<br/>  "issued_at": "..."<br/>}
+
+    Note over C: ⚠️ No refresh_token returned<br/>⚠️ No user context (runs as service user)
+
+    C->>SF: 7. Make API Calls
+    Note over C,SF: Authorization: Bearer ACCESS_TOKEN
+
+    SF->>SF: 8. Execute as Service User
+    Note over SF: All operations run with<br/>execution user's permissions
+
+    SF->>C: 9. API Response
+```
+
+## ASCII Fallback Template
+
+```
+┌───────────────────────┐     ┌────────────────────┐
+│    Service/Backend    │     │     Salesforce     │
+│   (client_id/secret)  │     │   (Auth Server)    │
+└───────────┬───────────┘     └─────────┬──────────┘
+            │                           │
+            │  1. POST /token           │
+            │     grant_type=           │
+            │       client_credentials  │
+            │     client_id=KEY         │
+            │     client_secret=SECRET  │
+            │──────────────────────────>│
+            │                           │
+            │           2. Validate     │
+            │              credentials  │
+            │                           │
+            │           3. Determine    │
+            │              execution    │
+            │              user         │
+            │                           │
+            │           4. Generate     │
+            │              access token │
+            │                           │
+            │  5. Access Token          │
+            │     (NO refresh token!)   │
+            │     (NO user context!)    │
+            │<──────────────────────────│
+            │                           │
+            │  6. API Request           │
+            │     (Bearer token)        │
+            │──────────────────────────>│
+            │                           │
+            │  7. API Response          │
+            │     (runs as svc user)    │
+            │<──────────────────────────│
+```
+
+## Token Request
+
+```bash
+curl -X POST https://login.salesforce.com/services/oauth2/token \
+  -d "grant_type=client_credentials" \
+  -d "client_id=YOUR_CONSUMER_KEY" \
+  -d "client_secret=YOUR_CONSUMER_SECRET"
+```
+
+## Response Example
+
+```json
+{
+  "access_token": "00D5g000001ABC...!ARcAQNlBrLGj...",
+  "instance_url": "https://mycompany.my.salesforce.com",
+  "token_type": "Bearer",
+  "issued_at": "1702123456789"
+}
+```
+
+## Code Examples
+
+### Python
+```python
+import requests
+
+response = requests.post(
+    'https://login.salesforce.com/services/oauth2/token',
+    data={
+        'grant_type': 'client_credentials',
+        'client_id': 'YOUR_CONSUMER_KEY',
+        'client_secret': 'YOUR_CONSUMER_SECRET'
+    }
+)
+
+token_data = response.json()
+access_token = token_data['access_token']
+instance_url = token_data['instance_url']
+
+# Make API call
+headers = {'Authorization': f'Bearer {access_token}'}
+api_response = requests.get(
+    f'{instance_url}/services/data/v66.0/sobjects/Account',
+    headers=headers
+)
+```
+
+### Node.js
+```javascript
+const axios = require('axios');
+
+const response = await axios.post(
+  'https://login.salesforce.com/services/oauth2/token',
+  new URLSearchParams({
+    grant_type: 'client_credentials',
+    client_id: 'YOUR_CONSUMER_KEY',
+    client_secret: 'YOUR_CONSUMER_SECRET'
+  })
+);
+
+const { access_token, instance_url } = response.data;
+
+// Make API call
+const apiResponse = await axios.get(
+  `${instance_url}/services/data/v66.0/sobjects/Account`,
+  { headers: { Authorization: `Bearer ${access_token}` } }
+);
+```
+
+## Connected App vs External Client App
+
+| Feature | Connected App | External Client App (ECA) |
+|---------|--------------|--------------------------|
+| Secret Management | Manual rotation | Automatic rotation supported |
+| User Assignment | "Run As" user | Permission Set assignment |
+| Configuration | Setup → App Manager | Setup → External Client Apps |
+| Recommended | Legacy integrations | New integrations (2024+) |
+
+## Key Characteristics
+
+| Aspect | Value |
+|--------|-------|
+| User Interaction | None required |
+| Refresh Token | **Not returned** - re-authenticate |
+| User Context | Runs as execution/service user |
+| Scopes | Limited to service account permissions |
+| Best For | System integrations, batch jobs |
+
+## Enabling Client Credentials
+
+### For Connected App
+1. Setup → App Manager → Edit Connected App
+2. Enable OAuth Settings
+3. Enable "Client Credentials Flow"
+4. Set "Run As" user
+
+### For External Client App
+1. Setup → External Client Apps → New
+2. Configure OAuth Settings
+3. Enable `isClientCredentialsEnabled`
+4. Assign Permission Set with user
+
+## Security Considerations
+
+1. **Protect client_secret** - Never expose in client-side code
+2. **Use dedicated service user** with minimal permissions
+3. **Rotate secrets regularly** (especially for Connected Apps)
+4. **Monitor API usage** - Set up event monitoring
+5. **Restrict IP ranges** if possible
+
+## Limitations
+
+- No refresh tokens (must re-authenticate)
+- No user context (cannot impersonate users)
+- Limited to service user's permissions
+- Cannot use for user-specific operations
+
+## Customization Points
+
+Replace these placeholders:
+- `CONSUMER_KEY` → Your Connected App's Consumer Key
+- `CONSUMER_SECRET` → Your Connected App's Consumer Secret
+- `login.salesforce.com` → Or `test.salesforce.com` for sandbox

package/skills/generating-mermaid-diagrams/assets/oauth/device-authorization.md

@@ -0,0 +1,295 @@
+# Device Authorization Flow Template
+
+OAuth 2.0 Device Authorization Grant for input-constrained devices without browsers.
+
+## When to Use
+- CLI tools (like Salesforce CLI)
+- Smart TVs and streaming devices
+- IoT devices
+- Gaming consoles
+- Any device without a browser or limited input capability
+
+## Mermaid Template
+
+```mermaid
+%%{init: {'theme': 'base', 'themeVariables': {
+  'actorBkg': '#ddd6fe',
+  'actorTextColor': '#1f2937',
+  'actorBorder': '#6d28d9',
+  'signalColor': '#334155',
+  'signalTextColor': '#1f2937',
+  'noteBkgColor': '#f8fafc',
+  'noteTextColor': '#1f2937',
+  'noteBorderColor': '#334155'
+}}}%%
+sequenceDiagram
+    autonumber
+
+    box rgba(165,243,252,0.3) USER
+        participant U as 👤 User
+        participant B as 🌐 Browser<br/>(on phone/computer)
+    end
+
+    box rgba(221,214,254,0.3) DEVICE
+        participant D as 📺 Device<br/>(CLI, TV, IoT)
+    end
+
+    box rgba(167,243,208,0.3) SALESFORCE
+        participant SF as ☁️ Salesforce<br/>Authorization Server
+    end
+
+    Note over D,SF: Device Authorization Flow (RFC 8628)
+
+    U->>D: 1. Initiate Login
+
+    D->>SF: 2. POST /services/oauth2/device/code
+    Note over D,SF: client_id=CONSUMER_KEY<br/>scope=api refresh_token
+
+    SF->>SF: 3. Generate Device & User Codes
+    Note over SF: device_code = long random string<br/>user_code = short readable code
+
+    SF->>D: 4. Return Codes
+    Note over SF,D: {<br/>  device_code: "...",<br/>  user_code: "ABCD-1234",<br/>  verification_uri: "https://login...",<br/>  verification_uri_complete: "...",<br/>  expires_in: 600,<br/>  interval: 5<br/>}
+
+    D->>U: 5. Display Instructions
+    Note over D,U: "Visit: https://login.salesforce.com/..."<br/>"Enter code: ABCD-1234"
+
+    U->>B: 6. Open Browser
+
+    B->>SF: 7. Navigate to verification_uri
+
+    SF->>B: 8. Display Code Entry Page
+    U->>SF: 9. Enter user_code: ABCD-1234
+
+    SF->>B: 10. Display Login Page
+    U->>SF: 11. Enter Username & Password
+
+    SF->>SF: 12. Authenticate User
+
+    SF->>B: 13. Display Consent Screen
+    U->>SF: 14. Grant Consent (Allow)
+
+    SF->>B: 15. Display Success Message
+    Note over SF,B: "You may close this window"
+
+    loop Poll Every 5 Seconds
+        D->>SF: 16. POST /services/oauth2/token
+        Note over D,SF: grant_type=device<br/>client_id=CONSUMER_KEY<br/>code=DEVICE_CODE
+
+        alt Authorization Pending
+            SF->>D: authorization_pending
+            Note over SF,D: User hasn't authorized yet
+        else Slow Down
+            SF->>D: slow_down
+            Note over SF,D: Polling too fast, increase interval
+        else Authorized
+            SF->>D: 17. Return Tokens
+        end
+    end
+
+    Note over SF,D: {<br/>  access_token: "...",<br/>  refresh_token: "...",<br/>  instance_url: "https://...",<br/>  token_type: "Bearer"<br/>}
+
+    D->>U: 18. ✅ Successfully Logged In
+```
+
+## ASCII Fallback Template
+
+```
+┌──────────┐  ┌───────────┐  ┌────────────┐  ┌────────────────┐
+│  User    │  │  Browser  │  │   Device   │  │   Salesforce   │
+│          │  │(phone/PC) │  │ (CLI/TV)   │  │  (Auth Server) │
+└────┬─────┘  └─────┬─────┘  └──────┬─────┘  └───────┬────────┘
+     │              │               │                │
+     │              │  1. Start     │                │
+     │              │     Login     │                │
+     │──────────────────────────────>                │
+     │              │               │                │
+     │              │               │  2. Request    │
+     │              │               │     device code│
+     │              │               │───────────────>│
+     │              │               │                │
+     │              │               │  3. device_code│
+     │              │               │     user_code  │
+     │              │               │     ABCD-1234  │
+     │              │               │<───────────────│
+     │              │               │                │
+     │     4. "Visit URL and enter: ABCD-1234"      │
+     │<──────────────────────────────                │
+     │              │               │                │
+     │  5. Open browser             │                │
+     │─────────────>│               │                │
+     │              │               │                │
+     │              │  6. Visit verification URL     │
+     │              │──────────────────────────────>│
+     │              │               │                │
+     │              │  7. Enter code page           │
+     │              │<──────────────────────────────│
+     │              │               │                │
+     │  8. Enter ABCD-1234          │                │
+     │─────────────>│──────────────────────────────>│
+     │              │               │                │
+     │  9. Login + Consent          │                │
+     │─────────────────────────────────────────────>│
+     │              │               │                │
+     │              │               │  10. Poll for  │
+     │              │               │      token     │
+     │              │               │  ┌───────────>│
+     │              │               │  │            │
+     │              │               │  │ (repeat)   │
+     │              │               │  │            │
+     │              │               │  11. Tokens!  │
+     │              │               │<─┴────────────│
+     │              │               │                │
+     │ 12. Logged In ✅             │                │
+     │<──────────────────────────────                │
+```
+
+## Step 1: Request Device Code
+
+```bash
+curl -X POST https://login.salesforce.com/services/oauth2/device/code \
+  -d "client_id=YOUR_CONSUMER_KEY" \
+  -d "scope=api refresh_token"
+```
+
+### Response
+```json
+{
+  "device_code": "aDEvhqZjZ2FwcAA6y...",
+  "user_code": "ABCD-1234",
+  "verification_uri": "https://login.salesforce.com/setup/connect",
+  "verification_uri_complete": "https://login.salesforce.com/setup/connect?user_code=ABCD-1234",
+  "expires_in": 600,
+  "interval": 5
+}
+```
+
+## Step 2: Display to User
+
+```
+═══════════════════════════════════════════════════════════════
+  To authorize this device, please:
+
+  1. Visit: https://login.salesforce.com/setup/connect
+  2. Enter code: ABCD-1234
+
+  Waiting for authorization...
+═══════════════════════════════════════════════════════════════
+```
+
+## Step 3: Poll for Token
+
+```bash
+curl -X POST https://login.salesforce.com/services/oauth2/token \
+  -d "grant_type=device" \
+  -d "client_id=YOUR_CONSUMER_KEY" \
+  -d "code=DEVICE_CODE"
+```
+
+### Possible Responses
+
+**Authorization Pending:**
+```json
+{
+  "error": "authorization_pending",
+  "error_description": "User has not yet authorized"
+}
+```
+
+**Slow Down (polling too fast):**
+```json
+{
+  "error": "slow_down",
+  "error_description": "Polling too fast"
+}
+```
+
+**Success:**
+```json
+{
+  "access_token": "00D5g000001ABC...!ARcAQNlBrLGj...",
+  "refresh_token": "5Aep8617...",
+  "instance_url": "https://mycompany.my.salesforce.com",
+  "token_type": "Bearer",
+  "issued_at": "1702123456789"
+}
+```
+
+## Code Example (CLI Tool)
+
+```python
+import requests
+import time
+
+CLIENT_ID = 'YOUR_CONSUMER_KEY'
+
+# Step 1: Request device code
+device_response = requests.post(
+    'https://login.salesforce.com/services/oauth2/device/code',
+    data={'client_id': CLIENT_ID, 'scope': 'api refresh_token'}
+).json()
+
+device_code = device_response['device_code']
+user_code = device_response['user_code']
+verification_uri = device_response['verification_uri']
+interval = device_response['interval']
+
+# Step 2: Display to user
+print(f"\nVisit: {verification_uri}")
+print(f"Enter code: {user_code}\n")
+
+# Step 3: Poll for token
+while True:
+    time.sleep(interval)
+
+    token_response = requests.post(
+        'https://login.salesforce.com/services/oauth2/token',
+        data={
+            'grant_type': 'device',
+            'client_id': CLIENT_ID,
+            'code': device_code
+        }
+    ).json()
+
+    if 'access_token' in token_response:
+        print("✅ Authorization successful!")
+        break
+    elif token_response.get('error') == 'slow_down':
+        interval += 5  # Increase polling interval
+    elif token_response.get('error') != 'authorization_pending':
+        print(f"Error: {token_response.get('error_description')}")
+        break
+
+access_token = token_response['access_token']
+```
+
+## Key Characteristics
+
+| Aspect | Value |
+|--------|-------|
+| User Interaction | On separate device |
+| Polling Required | Yes (every N seconds) |
+| Refresh Token | Yes, returned |
+| Best For | CLI tools, IoT, TVs |
+| User Code Format | Short, human-readable |
+
+## Timing Parameters
+
+| Parameter | Value | Purpose |
+|-----------|-------|---------|
+| `expires_in` | 600 (10 min) | How long codes are valid |
+| `interval` | 5 (seconds) | Minimum time between polls |
+
+## Security Considerations
+
+1. **Display user code clearly** - Use large font, easy to read
+2. **Honor interval** - Don't poll faster than specified
+3. **Handle expiration** - Codes expire after `expires_in` seconds
+4. **Secure token storage** - Store tokens securely on device
+
+## Customization Points
+
+Replace these placeholders:
+- `CONSUMER_KEY` → Your Connected App's Consumer Key
+- `DEVICE_CODE` → Device code from initial response
+- `login.salesforce.com` → Or `test.salesforce.com` for sandbox