{
  "openapi": "3.1.0",
  "info": {
    "title": "Aegis Product Authorization API",
    "version": "1.0.0",
    "description": "Online, product-scoped authorization for native Windows EXE and DLL integrations. Member accounts only; admin and owner accounts are rejected. A successful login does not create an offline license. Run /check at least every 30 seconds and fail closed."
  },
  "servers": [{ "url": "https://aegis.xcheat.space" }],
  "tags": [{ "name": "Native authorization" }],
  "components": {
    "securitySchemes": {
      "session": { "type": "http", "scheme": "bearer", "bearerFormat": "43-character opaque token" }
    },
    "parameters": {
      "protocol": {
        "name": "X-Aegis-Protocol", "in": "header", "required": true,
        "schema": { "type": "string", "const": "1" }
      }
    },
    "schemas": {
      "Error": {
        "type": "object", "required": ["error"],
        "properties": {
          "error": { "type": "string" },
          "code": { "type": "string", "description": "Machine-readable error code, when available." }
        }
      },
      "Proof": {
        "type": "object", "required": ["challenge_id", "signature"],
        "properties": {
          "challenge_id": { "type": "string", "minLength": 43, "maxLength": 43 },
          "signature": {
            "type": "string", "pattern": "^[0-9a-f]{128}$",
            "description": "ECDSA P-256/SHA-256 signature of the exact challenge UTF-8 bytes, IEEE P1363 r||s format."
          }
        }
      },
      "Challenge": {
        "type": "object", "required": ["ok", "challenge_id", "challenge", "expires_at"],
        "properties": {
          "ok": { "type": "boolean", "const": true },
          "challenge_id": { "type": "string" },
          "challenge": { "type": "string", "description": "Sign these exact UTF-8 bytes. Never reconstruct the string." },
          "expires_at": { "type": "integer", "description": "Unix milliseconds; single use, 60-second validity." }
        }
      },
      "Session": {
        "type": "object",
        "required": ["ok", "username", "product_id", "product_name", "session_token", "server_time", "expires_at", "heartbeat_seconds"],
        "properties": {
          "ok": { "type": "boolean", "const": true },
          "username": { "type": "string" },
          "product_id": { "type": "string" },
          "product_name": { "type": "string" },
          "license_expires_at": { "type": ["integer", "null"], "description": "Unix milliseconds, or null for lifetime. Informational; the server is authoritative." },
          "session_token": { "type": "string", "minLength": 43, "maxLength": 43 },
          "server_time": { "type": "integer" },
          "expires_at": { "type": "integer" },
          "heartbeat_seconds": { "type": "integer", "const": 30 }
        }
      }
    },
    "responses": {
      "Error": {
        "description": "Denied, expired, rate-limited or unavailable. The client must stop protected functionality.",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      }
    }
  },
  "paths": {
    "/api/sdk/v1/auth/start": {
      "post": {
        "tags": ["Native authorization"], "summary": "Verify credentials and request a login challenge",
        "parameters": [{ "$ref": "#/components/parameters/protocol" }],
        "requestBody": { "required": true, "content": { "application/json": { "schema": {
          "type": "object", "required": ["username", "password", "product_id", "public_key", "key_storage"],
          "properties": {
            "username": { "type": "string" }, "password": { "type": "string" },
            "code": { "type": "string", "description": "TOTP or recovery code only when this account has MFA enabled." },
            "product_id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,47}$" },
            "public_key": { "type": "string", "pattern": "^[0-9a-f]{128}$", "description": "P-256 x||y coordinates, 64 bytes in lowercase hex." },
            "key_storage": { "type": "string", "enum": ["tpm", "software"], "description": "Informational; this is not hardware attestation." }
          }
        } } } },
        "responses": {
          "200": { "description": "Login challenge", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Challenge" } } } },
          "default": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/api/sdk/v1/auth/finish": {
      "post": {
        "tags": ["Native authorization"], "summary": "Sign login challenge and create product session",
        "parameters": [{ "$ref": "#/components/parameters/protocol" }],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Proof" } } } },
        "responses": {
          "200": { "description": "Product-scoped online session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Session" } } } },
          "default": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/api/sdk/v1/challenge": {
      "post": {
        "tags": ["Native authorization"], "summary": "Get a one-use check or logout challenge",
        "security": [{ "session": [] }],
        "parameters": [{ "$ref": "#/components/parameters/protocol" }],
        "requestBody": { "required": true, "content": { "application/json": { "schema": {
          "type": "object", "required": ["action"],
          "properties": { "action": { "type": "string", "enum": ["check", "logout"] } }
        } } } },
        "responses": {
          "200": { "description": "Device challenge", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Challenge" } } } },
          "default": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/api/sdk/v1/check": {
      "post": {
        "tags": ["Native authorization"], "summary": "Recheck license and rotate session token",
        "security": [{ "session": [] }],
        "parameters": [{ "$ref": "#/components/parameters/protocol" }],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Proof" } } } },
        "responses": {
          "200": { "description": "New session token; discard the old one", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Session" } } } },
          "default": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/api/sdk/v1/logout": {
      "post": {
        "tags": ["Native authorization"], "summary": "Revoke the current SDK session",
        "security": [{ "session": [] }],
        "parameters": [{ "$ref": "#/components/parameters/protocol" }],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Proof" } } } },
        "responses": {
          "200": { "description": "Session revoked", "content": { "application/json": { "schema": {
            "type": "object", "properties": { "ok": { "type": "boolean", "const": true } }
          } } } },
          "default": { "$ref": "#/components/responses/Error" }
        }
      }
    }
  }
}