openapi: "3.1.0"
info:
  title: Agent Trust Demo API
  description: Reference implementation of the x-agent-trust extension for OpenAPI agent authentication. The Agent-Signature header is declared via an apiKey securityScheme with the required x-agent-trust extension carrying algorithm, trust levels, and JWKS endpoint. Discussed in OpenAPI spec PR #67.
  version: "1.0.0"
  contact:
    name: Raza Sharif
    url: https://cybersecai.co.uk
    email: contact@agentsign.dev
  license:
    name: BSL 1.1
components:
  securitySchemes:
    AgentTrust:
      type: apiKey
      description: Uses agent trust information in lieu of a traditional API key. Requires the x-agent-trust extension below for correct behaviour. The Agent-Signature header is an RFC 8941 structured field carrying keyid, alg, ts, nonce, and sig over a canonical request that includes a SHA-256 of the body, providing end-to-end integrity beyond what TLS alone can give in deployments with intermediaries.
      in: header
      name: Agent-Signature
      x-agent-trust:
        algorithm: ES256
        trustLevels: [L0, L1, L2, L3, L4]
        issuerKeysUrl: /.well-known/agent-trust-keys
        header:
          name: Agent-Signature
          # RFC 8941 structured field (Dictionary)
          format: 'keyid="<jwk-thumbprint>", alg="ES256", ts=<unix-seconds>, nonce="<b64url>", sig="<b64url>"'
          fields:
            keyid: JWK thumbprint (RFC 7638) of the signing key, resolvable via issuerKeysUrl
            alg:   JWS algorithm identifier (ES256 default)
            ts:    Unix seconds, validated against a bounded window (replay protection)
            nonce: Per-message random value; receiver rejects duplicates within the window
            sig:   ECDSA signature over the canonical request (method + path + ts + nonce + SHA-256 of body)
          example: 'Agent-Signature: keyid="a1b2c3...", alg="ES256", ts=1712425200, nonce="xYz9...", sig="MEUCIQDp..."'
        passportHeader:
          name: Agent-Passport-Id
          format: '<jwk-thumbprint>'
          description: Optional companion header carrying passport / delegation context
        references:
          - RFC 8941 (HTTP Structured Fields)
          - RFC 7638 (JWK Thumbprint)
          - RFC 7517 (JSON Web Key)
          - NIST FIPS 186-5 (ECDSA)
          - draft-sharif-agent-identity-framework (IETF)
          - draft-sharif-mcps-secure-mcp (IETF)
# scopes array entries are interpreted as the minimum required trust level for each operation.
paths:
  /api/data:
    get:
      summary: Read data
      security:
        - AgentTrust: [L1]
  /api/charges:
    post:
      summary: Create payment
      security:
        - AgentTrust: [L2]
  /api/execute:
    post:
      summary: Execute workflow
      security:
        - AgentTrust: [L3]
  /api/admin:
    delete:
      summary: Admin operation
      security:
        - AgentTrust: [L4]