{
    "openapi": "3.0.3",
    "info": {
        "title": "WHBOS Licensing Authority & Release Hub API",
        "version": "2.0.0",
        "description": "Enterprise cryptographic license authority, seat management, and software release distribution API for WHBOS.",
        "contact": {
            "name": "WHBOS Technical Operations",
            "url": "https://whbos.com"
        }
    },
    "servers": [
        {
            "url": "https://whbos.com/api/v2",
            "description": "Production API Authority Endpoint"
        }
    ],
    "paths": {
        "/health": {
            "get": {
                "summary": "System Health & Authority Status",
                "description": "Returns operational liveness, cryptographic authority readiness, and active license telemetry.",
                "responses": {
                    "200": {
                        "description": "Operational status payload",
                        "content": {
                            "application/json": {
                                "example": {
                                    "status": "operational",
                                    "service": "WHBOS License Authority API",
                                    "version": "v2.0",
                                    "authority": "Ed25519 Cryptographic Canonical Authority"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/license/validate": {
            "post": {
                "summary": "License Verification & Read-Only Pre-Activation Probe",
                "description": "Validates key validity, resolves current edition entitlements (Unbranded / Branded OS), and returns license status. Strictly read-only: does not consume seats, mutate bindings, or issue persistent leases.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "license_key"
                                ],
                                "properties": {
                                    "license_key": {
                                        "type": "string",
                                        "example": "WHBOS-H9TC-F6QP-TYCA-UBUX"
                                    },
                                    "domain": {
                                        "type": "string",
                                        "example": "cloud.example.com"
                                    },
                                    "server_ip": {
                                        "type": "string",
                                        "example": "103.120.176.45"
                                    },
                                    "device_public_key": {
                                        "type": "string",
                                        "example": "installer_probe_a8f9c10d"
                                    },
                                    "counter": {
                                        "type": "integer",
                                        "example": 1788370000
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "License successfully verified (read-only)",
                        "content": {
                            "application/json": {
                                "example": {
                                    "success": true,
                                    "status": "active",
                                    "plan": "Unbranded",
                                    "is_branded": false,
                                    "white_label": true,
                                    "message": "License validated successfully (read-only verification)."
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid or expired license key"
                    }
                }
            }
        },
        "/license/activate": {
            "post": {
                "summary": "Device Key Enrollment & Seat Locking",
                "description": "Binds an installation host to a cryptographic Ed25519 keypair and issues a signed 30-day entitlement lease token.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "license_key",
                                    "device_public_key",
                                    "device_sig",
                                    "timestamp",
                                    "nonce"
                                ],
                                "properties": {
                                    "license_key": {
                                        "type": "string",
                                        "example": "WHBOS-N9X2-8910-4B1C-7D60"
                                    },
                                    "device_public_key": {
                                        "type": "string",
                                        "description": "Base64 encoded Ed25519 public key"
                                    },
                                    "device_sig": {
                                        "type": "string",
                                        "description": "Base64 detached Ed25519 signature"
                                    },
                                    "timestamp": {
                                        "type": "integer",
                                        "example": 1786528692
                                    },
                                    "nonce": {
                                        "type": "string",
                                        "example": "3f9a21b80a9d4f"
                                    },
                                    "counter": {
                                        "type": "integer",
                                        "example": 1
                                    },
                                    "domain": {
                                        "type": "string",
                                        "example": "srv01.mycloud.io"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Activation successful with signed lease token"
                    },
                    "401": {
                        "description": "Invalid Ed25519 signature or stale timestamp/nonce"
                    },
                    "409": {
                        "description": "Maximum activation seat limit reached"
                    }
                }
            }
        },
        "/license/heartbeat": {
            "post": {
                "summary": "Periodic Seat Refresh & Lease Renewal",
                "description": "Refreshes the active seat and re-issues an updated signed entitlement lease token with anti-replay counter checks.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "license_key",
                                    "device_public_key",
                                    "device_sig",
                                    "counter"
                                ]
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Lease renewed successfully"
                    },
                    "401": {
                        "description": "Stale monotonic counter or invalid signature"
                    }
                }
            }
        },
        "/license/deactivate": {
            "post": {
                "summary": "Graceful Seat De-enrollment",
                "description": "Releases an active device seat from the license, freeing the node slot for reassignment.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "license_key",
                                    "device_public_key",
                                    "device_sig",
                                    "timestamp",
                                    "nonce"
                                ]
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Seat successfully released with cryptographic revocation notice"
                    },
                    "401": {
                        "description": "Invalid device signature"
                    },
                    "404": {
                        "description": "Seat not found"
                    }
                }
            }
        },
        "/license/transfer": {
            "post": {
                "summary": "Atomic Seat Migration & Host Re-binding",
                "description": "Deactivates this device existing seat and re-activates with fresh host binding in a single atomic transaction.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "license_key",
                                    "device_public_key",
                                    "device_sig",
                                    "timestamp",
                                    "nonce",
                                    "counter",
                                    "domain"
                                ],
                                "properties": {
                                    "license_key": {
                                        "type": "string"
                                    },
                                    "device_public_key": {
                                        "type": "string"
                                    },
                                    "device_sig": {
                                        "type": "string"
                                    },
                                    "timestamp": {
                                        "type": "integer"
                                    },
                                    "nonce": {
                                        "type": "string"
                                    },
                                    "counter": {
                                        "type": "integer"
                                    },
                                    "domain": {
                                        "type": "string",
                                        "example": "new-server.domain.com"
                                    },
                                    "activation_id": {
                                        "type": "integer",
                                        "example": 42
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "License seat successfully transferred and new lease issued"
                    },
                    "401": {
                        "description": "Invalid signature or expired timestamp"
                    },
                    "409": {
                        "description": "Seat limit reached on target license"
                    }
                }
            }
        },
        "/release/check": {
            "get": {
                "summary": "Software Update Availability Check",
                "description": "Checks for newer WHBOS Core release packages and returns signed manifest tokens.",
                "parameters": [
                    {
                        "name": "channel",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "default": "stable"
                        }
                    },
                    {
                        "name": "current_version",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "default": "1.0.0"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Update status and manifest details"
                    }
                }
            }
        },
        "/release/manifest": {
            "get": {
                "summary": "Signed Release Manifest",
                "description": "Returns cryptographic SHA-256 integrity checksums and signed release manifests.",
                "parameters": [
                    {
                        "name": "version",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Signed release manifest token"
                    },
                    "404": {
                        "description": "Release version not found"
                    }
                }
            }
        },
        "/release/download": {
            "get": {
                "summary": "Official Release Binary Download Stream",
                "description": "Streams the official release ZIP archive for authorized core upgrades.",
                "parameters": [
                    {
                        "name": "version",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "ZIP archive binary stream"
                    },
                    "404": {
                        "description": "Release package archive not found"
                    }
                }
            }
        }
    }
}