{
  "openapi": "3.1.0",
  "info": {
    "title": "A & L Security API",
    "version": "1.0.0",
    "description": "API privada para compartilhar exclusivamente bans técnicos por hack entre servidores autorizados. Além do Bearer token, todas as rotas protegidas exigem os cabeçalhos X-ALS-Timestamp, X-ALS-Nonce, X-ALS-Content-SHA256 e X-ALS-Signature."
  },
  "servers": [{ "url": "/api/v1" }],
  "components": {
    "securitySchemes": {
      "serverKey": { "type": "http", "scheme": "bearer", "bearerFormat": "als_live_PREFIX.SECRET" }
    },
    "schemas": {
      "CreateBan": {
        "type": "object",
        "additionalProperties": false,
        "required": ["steamId", "playerName", "reasonCode", "reasonDetail", "confidence", "occurredAt"],
        "properties": {
          "steamId": { "type": "string", "pattern": "^7656119[0-9]{10}$" },
          "playerName": { "type": "string", "minLength": 1, "maxLength": 80 },
          "reasonCode": { "type": "string", "enum": ["aimbot", "wallhack_esp", "speedhack", "flyhack", "impossible_damage", "inventory_exploit", "anti_cheat_tampering"] },
          "reasonDetail": { "type": "string", "minLength": 8, "maxLength": 500 },
          "confidence": { "type": "integer", "minimum": 1, "maximum": 100 },
          "occurredAt": { "type": "string", "format": "date-time" },
          "evidenceUrl": { "type": ["string", "null"], "format": "uri", "pattern": "^https://" },
          "evidenceHash": { "type": ["string", "null"], "pattern": "^[a-fA-F0-9]{64}$" }
        }
      },
      "Error": {
        "type": "object",
        "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } }
      }
    },
    "parameters": {
      "timestamp": { "name": "X-ALS-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } },
      "nonce": { "name": "X-ALS-Nonce", "in": "header", "required": true, "schema": { "type": "string", "minLength": 16, "maxLength": 128 } },
      "contentHash": { "name": "X-ALS-Content-SHA256", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } },
      "signature": { "name": "X-ALS-Signature", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }
    }
  },
  "paths": {
    "/health": {
      "get": { "summary": "Verifica disponibilidade", "responses": { "200": { "description": "Serviço disponível" } } }
    },
    "/bans/{identifier}": {
      "get": {
        "summary": "Consulta bans ativos por SteamID64",
        "security": [{ "serverKey": [] }],
        "parameters": [
          { "name": "identifier", "in": "path", "required": true, "description": "SteamID64 para consultas GET", "schema": { "type": "string", "pattern": "^7656119[0-9]{10}$" } },
          { "$ref": "#/components/parameters/timestamp" }, { "$ref": "#/components/parameters/nonce" }, { "$ref": "#/components/parameters/contentHash" }, { "$ref": "#/components/parameters/signature" }
        ],
        "responses": { "200": { "description": "Consulta concluída" }, "401": { "description": "Assinatura inválida" }, "429": { "description": "Limite atingido" } }
      },
      "delete": {
        "summary": "Revoga ban criado pelo mesmo servidor",
        "security": [{ "serverKey": [] }],
        "parameters": [
          { "name": "identifier", "in": "path", "required": true, "description": "Ban ID para revogação DELETE", "schema": { "type": "string", "pattern": "^ban_[0-9a-f-]{36}$" } },
          { "$ref": "#/components/parameters/timestamp" }, { "$ref": "#/components/parameters/nonce" }, { "$ref": "#/components/parameters/contentHash" }, { "$ref": "#/components/parameters/signature" }
        ],
        "responses": { "200": { "description": "Ban revogado" }, "404": { "description": "Ban não encontrado ou de outra origem" } }
      }
    },
    "/bans": {
      "post": {
        "summary": "Registra um ban técnico",
        "security": [{ "serverKey": [] }],
        "parameters": [
          { "$ref": "#/components/parameters/timestamp" }, { "$ref": "#/components/parameters/nonce" }, { "$ref": "#/components/parameters/contentHash" }, { "$ref": "#/components/parameters/signature" },
          { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 16, "maxLength": 100 } }
        ],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBan" } } } },
        "responses": { "201": { "description": "Ban registrado" }, "400": { "description": "Dados inválidos" }, "409": { "description": "Repetição ou conflito" } }
      }
    }
  }
}