reqon-dsl 0.2.0

package/docusaurus/docs/authentication/api-key.md

@@ -0,0 +1,339 @@
+---
+sidebar_position: 4
+---
+
+# API Key Authentication
+
+API key authentication sends a key in either a header or query parameter. Many SaaS APIs use this method.
+
+## Configuration
+
+### Mission File
+
+```vague
+source API {
+  auth: api_key,
+  base: "https://api.example.com"
+}
+```
+
+### Credentials File
+
+```json
+{
+  "API": {
+    "type": "api_key",
+    "key": "your-api-key",
+    "header": "X-API-Key"
+  }
+}
+```
+
+## Credential Options
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `type` | Yes | Must be `"api_key"` |
+| `key` | Yes | The API key value |
+| `header` | No* | Header name for the key |
+| `query` | No* | Query parameter name for the key |
+| `prefix` | No | Prefix for header value (e.g., "Bearer") |
+
+*One of `header` or `query` is required.
+
+## Header-Based API Key
+
+### Standard Header
+
+```json
+{
+  "API": {
+    "type": "api_key",
+    "key": "your-api-key",
+    "header": "X-API-Key"
+  }
+}
+```
+
+Request:
+```http
+GET /api/data HTTP/1.1
+X-API-Key: your-api-key
+```
+
+### Authorization Header with Prefix
+
+```json
+{
+  "API": {
+    "type": "api_key",
+    "key": "your-api-key",
+    "header": "Authorization",
+    "prefix": "ApiKey"
+  }
+}
+```
+
+Request:
+```http
+GET /api/data HTTP/1.1
+Authorization: ApiKey your-api-key
+```
+
+### Bearer-Style API Key
+
+Some APIs use bearer format for API keys:
+
+```json
+{
+  "API": {
+    "type": "api_key",
+    "key": "sk_live_xxxxx",
+    "header": "Authorization",
+    "prefix": "Bearer"
+  }
+}
+```
+
+Request:
+```http
+GET /api/data HTTP/1.1
+Authorization: Bearer sk_live_xxxxx
+```
+
+## Query Parameter API Key
+
+```json
+{
+  "API": {
+    "type": "api_key",
+    "key": "your-api-key",
+    "query": "api_key"
+  }
+}
+```
+
+Request:
+```http
+GET /api/data?api_key=your-api-key HTTP/1.1
+```
+
+## Common API Examples
+
+### SendGrid
+
+```json
+{
+  "SendGrid": {
+    "type": "api_key",
+    "key": "SG.xxxxxxxxxxxx",
+    "header": "Authorization",
+    "prefix": "Bearer"
+  }
+}
+```
+
+### Mailchimp
+
+```json
+{
+  "Mailchimp": {
+    "type": "api_key",
+    "key": "your-api-key-us1",
+    "header": "Authorization",
+    "prefix": "apikey"
+  }
+}
+```
+
+### OpenAI
+
+```json
+{
+  "OpenAI": {
+    "type": "api_key",
+    "key": "sk-xxxxxxxxxxxx",
+    "header": "Authorization",
+    "prefix": "Bearer"
+  }
+}
+```
+
+### Google Maps
+
+```json
+{
+  "GoogleMaps": {
+    "type": "api_key",
+    "key": "AIzaxxxxxxxxxxxxx",
+    "query": "key"
+  }
+}
+```
+
+### Custom API
+
+```json
+{
+  "CustomAPI": {
+    "type": "api_key",
+    "key": "your-api-key",
+    "header": "X-Custom-Auth"
+  }
+}
+```
+
+## Environment Variables
+
+### In Credentials
+
+```json
+{
+  "API": {
+    "type": "api_key",
+    "key": "${API_KEY}",
+    "header": "X-API-Key"
+  }
+}
+```
+
+### In Mission
+
+```vague
+source API {
+  auth: api_key,
+  base: "https://api.example.com",
+  apiKey: env("API_KEY"),
+  apiKeyHeader: "X-API-Key"
+}
+```
+
+## Multiple API Keys
+
+For APIs requiring multiple keys:
+
+```vague
+source API {
+  auth: api_key,
+  base: "https://api.example.com",
+  headers: {
+    "X-API-Key": env("API_KEY"),
+    "X-App-ID": env("APP_ID")
+  }
+}
+```
+
+Or use custom header addition:
+
+```json
+{
+  "API": {
+    "type": "api_key",
+    "key": "primary-key",
+    "header": "X-API-Key",
+    "additionalHeaders": {
+      "X-App-ID": "your-app-id"
+    }
+  }
+}
+```
+
+## Key Rotation
+
+### Manual Rotation
+
+1. Generate new key in provider dashboard
+2. Update credentials file
+3. Run mission
+
+### Zero-Downtime Rotation
+
+Some APIs support multiple active keys:
+
+```json
+{
+  "API": {
+    "type": "api_key",
+    "key": "new-key",
+    "header": "X-API-Key"
+  }
+}
+```
+
+1. Create new key (old still works)
+2. Update credentials
+3. Verify new key works
+4. Revoke old key
+
+## Error Handling
+
+```vague
+action FetchData {
+  get "/data"
+
+  match response {
+    { error: "invalid_api_key" } -> abort "Invalid API key",
+    { error: "expired_api_key" } -> abort "API key expired",
+    { error: _, code: 401 } -> abort "Authentication failed",
+    { error: _, code: 403 } -> abort "API key lacks permissions",
+    _ -> continue
+  }
+}
+```
+
+## Security Best Practices
+
+### Never Expose in URLs (When Possible)
+
+Prefer header over query:
+
+```json
+// Better: key in header
+{
+  "type": "api_key",
+  "key": "...",
+  "header": "X-API-Key"
+}
+
+// Avoid: key in URL (may be logged)
+{
+  "type": "api_key",
+  "key": "...",
+  "query": "api_key"
+}
+```
+
+### Use Environment Variables
+
+```bash
+export API_KEY="your-key"
+```
+
+### Restrict Key Permissions
+
+Use keys with minimal required permissions.
+
+## Troubleshooting
+
+### "Invalid API Key"
+
+1. Check key is correct
+2. Check for extra whitespace
+3. Verify key hasn't been revoked
+
+### "Header Not Recognized"
+
+Check the exact header name the API expects:
+
+```json
+// Case matters!
+"header": "X-API-Key"  // Not "x-api-key"
+```
+
+### Key Being Sent Wrong
+
+Debug by checking what's being sent:
+
+```bash
+reqon mission.vague --verbose
+```

package/docusaurus/docs/authentication/basic.md

@@ -0,0 +1,276 @@
+---
+sidebar_position: 5
+---
+
+# Basic Authentication
+
+HTTP Basic Authentication sends username and password with each request, encoded in Base64. While simple, it should only be used over HTTPS.
+
+## Configuration
+
+### Mission File
+
+```vague
+source API {
+  auth: basic,
+  base: "https://api.example.com"
+}
+```
+
+### Credentials File
+
+```json
+{
+  "API": {
+    "type": "basic",
+    "username": "your-username",
+    "password": "your-password"
+  }
+}
+```
+
+## How It Works
+
+Reqon encodes credentials and adds them to every request:
+
+```http
+GET /api/data HTTP/1.1
+Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
+```
+
+The value is `base64(username:password)`.
+
+## Credential Options
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `type` | Yes | Must be `"basic"` |
+| `username` | Yes | The username |
+| `password` | Yes | The password |
+
+## Environment Variables
+
+### In Credentials File
+
+```json
+{
+  "API": {
+    "type": "basic",
+    "username": "${API_USERNAME}",
+    "password": "${API_PASSWORD}"
+  }
+}
+```
+
+```bash
+export API_USERNAME="myuser"
+export API_PASSWORD="mypass"
+reqon mission.vague --auth credentials.json
+```
+
+### In Mission File
+
+```vague
+source API {
+  auth: basic,
+  base: "https://api.example.com",
+  username: env("API_USERNAME"),
+  password: env("API_PASSWORD")
+}
+```
+
+## Common Use Cases
+
+### Legacy Systems
+
+```vague
+source LegacyERP {
+  auth: basic,
+  base: "https://erp.company.com/api"
+}
+```
+
+### JIRA (Server)
+
+```json
+{
+  "JIRA": {
+    "type": "basic",
+    "username": "user@company.com",
+    "password": "api-token"
+  }
+}
+```
+
+### Bitbucket Server
+
+```json
+{
+  "Bitbucket": {
+    "type": "basic",
+    "username": "username",
+    "password": "app-password"
+  }
+}
+```
+
+### Jenkins
+
+```json
+{
+  "Jenkins": {
+    "type": "basic",
+    "username": "admin",
+    "password": "api-token"
+  }
+}
+```
+
+### Elasticsearch
+
+```json
+{
+  "Elasticsearch": {
+    "type": "basic",
+    "username": "elastic",
+    "password": "changeme"
+  }
+}
+```
+
+## Token as Password
+
+Many APIs use Basic auth with a token as password:
+
+### Atlassian Cloud
+
+```json
+{
+  "Atlassian": {
+    "type": "basic",
+    "username": "email@example.com",
+    "password": "ATATT3xFfGF0..."  // API token
+  }
+}
+```
+
+### npm Registry
+
+```json
+{
+  "NPM": {
+    "type": "basic",
+    "username": "username",
+    "password": "npm_xxxxx"  // Access token
+  }
+}
+```
+
+## Error Handling
+
+```vague
+action FetchData {
+  get "/data"
+
+  match response {
+    { error: _, code: 401 } -> abort "Invalid credentials",
+    { error: _, code: 403 } -> abort "Access denied",
+    _ -> continue
+  }
+}
+```
+
+## Security Considerations
+
+### Always Use HTTPS
+
+Basic auth credentials are only Base64 encoded (not encrypted):
+
+```vague
+// Good
+source API {
+  auth: basic,
+  base: "https://api.example.com"  // HTTPS
+}
+
+// DANGEROUS - credentials exposed
+source API {
+  auth: basic,
+  base: "http://api.example.com"  // HTTP
+}
+```
+
+### Prefer Token-Based Auth
+
+When available, use tokens instead:
+
+```vague
+// Preferred: token-based
+source API {
+  auth: bearer,
+  base: "https://api.example.com"
+}
+
+// Use basic only when necessary
+source LegacyAPI {
+  auth: basic,
+  base: "https://legacy.example.com"
+}
+```
+
+### Use Strong Passwords
+
+If using actual password (not token):
+- Use a unique password for API access
+- Enable MFA on the account if available
+- Rotate regularly
+
+## Credential Rotation
+
+### Rotate Password
+
+1. Update password in API provider
+2. Update credentials file
+3. Verify mission works
+
+### Minimal Disruption
+
+```bash
+# Update credentials
+echo '{"API": {"type": "basic", "username": "user", "password": "new-pass"}}' > credentials.json
+
+# Test
+reqon mission.vague --dry-run --auth credentials.json
+
+# Run
+reqon mission.vague --auth credentials.json
+```
+
+## Troubleshooting
+
+### "401 Unauthorized"
+
+1. Verify username and password
+2. Check for typos
+3. Ensure account has API access
+
+### "Encoding Issues"
+
+Check for special characters in password. They should be URL-safe or properly escaped:
+
+```json
+{
+  "API": {
+    "username": "user",
+    "password": "pass:word@123"  // Special chars OK
+  }
+}
+```
+
+### "Connection Refused"
+
+Verify HTTPS is working:
+
+```bash
+curl -u "user:pass" https://api.example.com/health
+```