{
  "openapi": "3.1.0",
  "info": {
    "title": "Agent Authority Chain Controlled Beta API",
    "version": "0.5.0",
    "description": "Authenticated verification of Ed25519-signed AAC authority chains against an operator-configured issuer keyset and revocation registry. A valid result is not legal authority, payment authorization, or independent proof of issuer legitimacy."
  },
  "servers": [{"url": "https://agentauthoritychain.com"}],
  "paths": {
    "/api/v1/capabilities": {
      "get": {
        "summary": "Discover verifier capabilities",
        "responses": {"200": {"description": "Capability metadata"}}
      }
    },
    "/api/v1/status": {
      "get": {
        "summary": "Check service and database readiness",
        "responses": {"200": {"description": "Service and database are ready"}, "503": {"description": "Service is degraded"}}
      }
    },
    "/api/v1/evaluate": {
      "get": {
        "summary": "Evaluate AAC using a fixed, zero-credential conformance case",
        "description": "Safe read-only evaluation surface. It accepts no caller-supplied chain, context, key, URL, or code and cannot authorize a real operation.",
        "parameters": [
          {"name": "case", "in": "query", "required": false, "schema": {"type": "string", "enum": ["valid", "widened", "expired"], "default": "valid"}}
        ],
        "responses": {
          "200": {"description": "Fixed fixture evaluated; inspect decision_receipt.decision", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/VerifyResponse"}}}},
          "400": {"description": "Unknown evaluation case"},
          "429": {"description": "Public evaluation rate limit exceeded"}
        }
      }
    },
    "/api/v1/verify": {
      "post": {
        "summary": "Verify a signed AAC authority chain",
        "security": [{"bearerAuth": []}],
        "parameters": [
          {"name": "X-AAC-Timestamp", "in": "header", "required": true, "schema": {"type": "integer"}, "description": "Current Unix time in seconds; accepted within 300 seconds."},
          {"name": "X-AAC-Nonce", "in": "header", "required": true, "schema": {"type": "string", "minLength": 20, "maxLength": 200}, "description": "A unique high-entropy value for replay prevention."}
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["input_type", "signed_scenario"],
                "properties": {
                  "input_type": {"const": "signed"},
                  "signed_scenario": {
                    "type": "object",
                    "required": ["signed_chain", "request"],
                    "properties": {
                      "signed_chain": {"type": "array", "maxItems": 10, "items": {"type": "string"}},
                      "request": {"type": "object"},
                      "transaction_context": {"type": "object"}
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Verification completed; release an operation only when decision_receipt.decision is permit",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/VerifyResponse"}}}
          },
          "400": {"description": "Malformed request or replay metadata"},
          "401": {"description": "Missing, invalid, or stale authentication"},
          "409": {"description": "Nonce replay detected"},
          "413": {"description": "Request limit exceeded"},
          "429": {"description": "Client rate limit exceeded"}
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {"type": "http", "scheme": "bearer", "bearerFormat": "AAC API key"}
    },
    "schemas": {
      "VerifyResponse": {
        "type": "object",
        "required": ["api_version", "request_id", "result", "checks", "errors", "warnings", "decision_receipt"],
        "properties": {
          "api_version": {"type": "string"},
          "request_id": {"type": "string"},
          "result": {"enum": ["valid", "invalid"]},
          "checks": {"type": "object", "additionalProperties": true},
          "provenance": {"type": ["object", "null"]},
          "errors": {"type": "array", "items": {"type": "object"}},
          "warnings": {"type": "array", "items": {"type": "object"}},
          "decision_receipt": {"$ref": "#/components/schemas/DecisionReceipt"}
        }
      },
      "DecisionReceipt": {
        "type": "object",
        "description": "Portable fail-closed enforcement evidence. The v1 receipt_digest is a correlation/integrity digest, not a digital signature or independent proof of AAC issuance.",
        "required": ["receipt_version", "decision_id", "decision", "issued_at", "verifier", "policy_profile", "trust_mode", "revocation_checked", "request_hash", "authority_chain_hash", "error_codes", "receipt_digest"],
        "properties": {
          "receipt_version": {"const": "aac-decision-receipt/1"},
          "decision_id": {"type": "string"},
          "decision": {"enum": ["permit", "deny"], "description": "Only exact permit may release the protected operation."},
          "issued_at": {"type": "string", "format": "date-time"},
          "verifier": {"type": "string", "format": "uri"},
          "policy_profile": {"type": "string"},
          "trust_mode": {"type": "string"},
          "revocation_checked": {"type": "boolean"},
          "request_hash": {"type": "string", "pattern": "^sha256:[0-9a-f]{64}$"},
          "authority_chain_hash": {"type": ["string", "null"]},
          "error_codes": {"type": "array", "items": {"type": "string"}},
          "receipt_digest": {"type": "string", "pattern": "^sha256:[0-9a-f]{64}$"}
        }
      }
    }
  }
}