Security & Authentication

name: public-api
trigger:
  - type: http
    path: /api/users/:id
    methods: [GET]
    public: true  # Must be explicit!

flow:
  - agent: fetch-user

# Execute an ensemble
POST /api/v1/execute/ensemble/invoice-pdf
Authorization: Bearer <token>
Content-Type: application/json

{"input": {"orderId": "12345"}}

# Execute an agent directly (if enabled)
POST /api/v1/execute/agent/http
Authorization: Bearer <token>
Content-Type: application/json

{"input": {"url": "https://api.example.com/data"}}

curl -X POST https://your-worker.workers.dev/api/v1/execute/ensemble/my-workflow \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{"input": {}}'

# In ensemble trigger config
auth:
  type: bearer
  secret: ${env.JWT_SECRET}

curl -X POST https://your-worker.workers.dev/api/v1/execute/ensemble/my-workflow \
  -H "X-API-Key: cnd_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"input": {}}'

wrangler kv:namespace create "API_KEYS"

[[kv_namespaces]]
binding = "API_KEYS"
id = "your-kv-namespace-id"

trigger:
  - type: http
    path: /api/data
    auth:
      type: apiKey  # Uses API_KEYS KV namespace

ensemble conductor keys generate --name "my-service" --permissions "ensemble:*:execute"

// conductor.config.ts
export default {
  auth: {
    provider: 'unkey',
    rootKey: process.env.UNKEY_ROOT_KEY,
  },
}

{resource}:{name}:{action}

// These all match "ensemble:billing-invoice:execute"
"*"                           // Superuser
"ensemble:*"                  // All ensemble permissions
"ensemble:*:execute"          // Execute any ensemble
"ensemble:billing-*:execute"  // Pattern matching

// conductor.config.ts
export default {
  security: {
    autoPermissions: true,
  },
}

# Basic key with full access
ensemble conductor keys generate --name "admin-key" --permissions "*"

# Scoped key for specific ensembles
ensemble conductor keys generate \
  --name "billing-service" \
  --permissions "ensemble:billing-*:execute,ensemble:invoice-*:execute" \
  --expires "90d"

# Key that never expires
ensemble conductor keys generate \
  --name "internal-service" \
  --permissions "ensemble:*:execute" \
  --expires "never"

✓ API Key generated
Key ID: key_abc123
Key: cnd_live_xxxxxxxxxxxxxxxxxxxx
Permissions: ensemble:billing-*:execute, ensemble:invoice-*:execute
Expires: 2024-05-15

⚠️  Save this key now - it won't be shown again!

ensemble conductor keys list

# Output as JSON
ensemble conductor keys list --json

ensemble conductor keys revoke key_abc123

ensemble conductor keys info key_abc123

ensemble conductor keys rotate key_abc123

// conductor.config.ts
export default {
  auth: {
    /**
     * Require authentication on /api/* routes
     * @default true (SECURE BY DEFAULT)
     */
    requireAuth: true,

    /** List of valid API keys (for simple setups) */
    apiKeys: [process.env.API_KEY],

    /** Allow anonymous access (not recommended for production) */
    allowAnonymous: false,
  },

  security: {
    /**
     * Allow direct agent execution via /api/v1/execute/agent/:name
     * Set to false to only allow ensemble execution
     * @default true
     */
    allowDirectAgentExecution: true,

    /**
     * Automatically require resource-specific permissions
     * When true, executing ensemble "foo" requires permission "ensemble:foo:execute"
     * @default false
     */
    autoPermissions: false,
  },

  /**
   * API execution controls
   * Controls which agents and ensembles can be executed via the Execute API
   */
  api: {
    execution: {
      agents: {
        /**
         * When true, agents must have apiExecutable: true to be executable via API
         * When false (default), all agents are executable unless apiExecutable: false
         */
        requireExplicit: false,
      },
      ensembles: {
        /**
         * When true, ensembles must have apiExecutable: true to be executable via API
         * When false (default), all ensembles are executable unless apiExecutable: false
         */
        requireExplicit: false,
      },
    },
  },
}

# Ensemble that cannot be executed via API
name: internal-workflow
apiExecutable: false  # Prevents API execution

# Agent that requires explicit opt-in
agent: sensitive-operation
apiExecutable: true   # Required when requireExplicit: true

// conductor.config.ts
export default {
  api: {
    execution: {
      ensembles: { requireExplicit: true },  // Require opt-in
      agents: { requireExplicit: true },
    },
  },
}

# This ensemble CAN be executed via API
name: public-workflow
apiExecutable: true

# This ensemble CANNOT be executed via API (no apiExecutable)
name: internal-only
# apiExecutable defaults to undefined, so blocked when requireExplicit: true

# Default docs-serve ensemble (built-in)
name: docs-serve
trigger:
  - type: http
    paths:
      - path: /docs
        methods: [GET]
      - path: /docs/:slug
        methods: [GET]
    public: true  # Explicitly public for docs

# ensembles/docs-internal.yaml
name: docs-internal
trigger:
  - type: http
    path: /docs/internal
    methods: [GET]
    public: false  # Requires authentication

flow:
  - name: render
    agent: docs
    config:
      title: Internal Documentation
      basePath: /docs/internal

output:
  _raw: ${render.output}

// This happens automatically in agents that accept user URLs
import { safeFetch, validateURL } from '@ensemble-edge/conductor'

// safeFetch blocks requests to private IPs
await safeFetch(userProvidedUrl)  // Throws if URL is unsafe

// You can also validate URLs manually
validateURL(url)  // Throws if URL points to private/internal address

import { safeFetch } from '@ensemble-edge/conductor'

// WARNING: Only use this for trusted, hardcoded URLs
// Never use allowInternalRequests with user-provided URLs
const response = await safeFetch(internalServiceUrl, {
  allowInternalRequests: true,
})

// Your custom agent - SSRF protection is automatic
export default async function(context: AgentExecutionContext) {
  const { fetch, input } = context

  // This fetch is SSRF-protected - blocks private IPs automatically
  const response = await fetch(input.userProvidedUrl)
  return { data: await response.json() }
}

# agent.yaml
name: internal-service-proxy
operation: code
handler: ./proxy.ts
security:
  ssrf: false  # ⚠️ Disables SSRF protection for this agent only

export default async function(context: AgentExecutionContext) {
  const { location, input } = context

  // Automatic jurisdiction detection
  if (location?.isGDPR) {
    // User is in EU/EEA/UK - opt-in consent required
    if (!input.consents?.analytics) {
      return { requiresConsent: true, jurisdiction: 'GDPR' }
    }
  }

  if (location?.isCCPA) {
    // User is in California - opt-out model
    // Can process unless user has opted out
  }

  // Process with appropriate compliance
  return processUserData(input)
}

export default async function(context: AgentExecutionContext) {
  const { location } = context

  // Check specific consent purposes
  const purposes = ['analytics', 'marketing', 'personalization']

  const requiredConsents = purposes.filter(
    purpose => location?.requiresConsent(purpose as any)
  )

  return {
    consentModel: location?.consentModel,  // 'opt-in' | 'opt-out' | 'none'
    requiredConsents,
    jurisdiction: location?.jurisdiction
  }
}

# Bad: Full access
ensemble conductor keys generate --name "billing" --permissions "*"

# Good: Scoped to what's needed
ensemble conductor keys generate --name "billing" \
  --permissions "ensemble:billing-*:execute,ensemble:invoice-*:execute"

# Rotate keys periodically
ensemble conductor keys rotate key_abc123

// conductor.config.ts
export default {
  security: {
    autoPermissions: true,
  },
}

// conductor.config.ts
export default {
  security: {
    allowDirectAgentExecution: false,
  },
}

export default async function(context: AgentExecutionContext) {
  const { edge } = context

  // Detect automated traffic
  if (edge?.isFromCloudProvider()) {
    // Requests from AWS, GCP, Azure often indicate bots
    return { action: 'challenge', reason: edge.getCloudProvider() }
  }

  // Check for modern protocols
  if (!edge?.isModernTLS()) {
    // Outdated clients may be suspicious
    return { action: 'warn', reason: 'legacy_tls' }
  }

  return { action: 'allow' }
}

POST /api/v1/execute/ensemble/{name}

{
  "input": {
    // Ensemble input data
  }
}

{
  "success": true,
  "output": {
    // Ensemble output
  },
  "metadata": {
    "executionId": "req_abc123",
    "duration": 1234,
    "timestamp": 1699900000000
  }
}

POST /api/v1/execute/agent/{name}

{
  "input": {
    // Agent input data (required)
  },
  "config": {
    // Optional config overrides
  }
}

{
  "success": true,
  "data": {
    // Agent output
  },
  "metadata": {
    "executionId": "req_abc123",
    "duration": 567,
    "timestamp": 1699900000000
  }
}