reqon-dsl 0.2.0 → 0.3.0

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

@@ -1,339 +0,0 @@
----
-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

@@ -1,276 +0,0 @@
----
-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
-```