openapi.yaml

openapi: 3.1.0
info:
  title: Nexus Hosting API
  version: 1.0.0
  description: |
    Production-grade federated static site hosting network.
    Every node exposes this API. Authentication uses session cookies (browser)
    or Bearer API tokens (CLI / CI). Inter-node requests use Ed25519 signatures.
  contact:
    name: The No Hands Company
    url: https://github.com/The-No-Hands-company/Nexus-Hosting
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: /api
    description: Local node API

tags:
  - name: health
    description: Liveness and readiness probes
  - name: auth
    description: Browser OIDC and mobile auth
  - name: nodes
    description: Federation node registry
  - name: sites
    description: Hosted site management
  - name: deploy
    description: File upload and deployment
  - name: federation
    description: Inter-node federation protocol
  - name: gossip
    description: Peer discovery via gossip
  - name: analytics
    description: Site traffic analytics
  - name: tokens
    description: Long-lived API tokens
  - name: access
    description: Site membership and visibility
  - name: domains
    description: Custom domain management
  - name: admin
    description: Node operator dashboard
  - name: capacity
    description: Storage and bandwidth tracking
  - name: storage
    description: Object storage endpoints

  - name: nlpl
    description: NLPL and Node.js/Python dynamic site process management
  - name: builds
    description: Git-connected build pipeline
  - name: forms
    description: Form submission inbox
  - name: tls
    description: TLS certificate management and ACME challenges
  - name: storage
    description: Internal object storage access

paths:

  # ── Health ──────────────────────────────────────────────────────────────────

  /health:
    get:
      operationId: healthCheck
      tags: [health]
      summary: Full health check with service dependencies
      responses:
        "200":
          description: Health status
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HealthStatus"

  /health/live:
    get:
      operationId: livenessProbe
      tags: [health]
      summary: Kubernetes liveness probe
      responses:
        "200":
          description: Node is alive

  /health/ready:
    get:
      operationId: readinessProbe
      tags: [health]
      summary: Kubernetes readiness probe
      responses:
        "200":
          description: Node is ready to serve traffic
        "503":
          description: Node not ready

  /stats:
    get:
      operationId: getFederationStats
      tags: [nodes]
      summary: Network-wide federation statistics
      responses:
        "200":
          description: Federation statistics
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FederationStats"

  # ── Auth ────────────────────────────────────────────────────────────────────

  /auth/user:
    get:
      operationId: getCurrentAuthUser
      tags: [auth]
      summary: Get the currently authenticated user
      parameters:
        - $ref: "#/components/parameters/AuthorizationSessionHeader"
        - $ref: "#/components/parameters/SessionCookie"
      responses:
        "200":
          description: Auth status
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GetCurrentAuthUserResponse"

  /login:
    get:
      operationId: beginBrowserLogin
      tags: [auth]
      summary: Start the browser OIDC login flow
      parameters:
        - name: returnTo
          in: query
          required: false
          schema:
            type: string
      responses:
        "302":
          description: Redirect to OIDC authorization endpoint

  /callback:
    get:
      operationId: handleBrowserLoginCallback
      tags: [auth]
      summary: Complete the browser OIDC login flow
      responses:
        "302":
          description: Redirect to returnTo or /api/login on failure

  /logout:
    get:
      operationId: logoutBrowserSession
      tags: [auth]
      summary: Clear session and begin OIDC logout
      responses:
        "302":
          description: Redirect to OIDC logout URL

  /mobile-auth/token-exchange:
    post:
      operationId: exchangeMobileAuthorizationCode
      tags: [auth]
      summary: Exchange a mobile OIDC code for a session token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ExchangeMobileAuthorizationCodeBody"
      responses:
        "200":
          description: Session token created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ExchangeMobileAuthorizationCodeResponse"
        "400":
          $ref: "#/components/responses/BadRequest"

  /mobile-auth/logout:
    post:
      operationId: logoutMobileSession
      tags: [auth]
      summary: Revoke a mobile session token
      parameters:
        - $ref: "#/components/parameters/AuthorizationSessionHeader"
      responses:
        "200":
          description: Logged out
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LogoutMobileSessionResponse"

  # ── API Tokens ──────────────────────────────────────────────────────────────

  /tokens:
    get:
      operationId: listTokens
      tags: [tokens]
      summary: List active API tokens for the current user
      security:
        - sessionAuth: []
        - bearerToken: []
      responses:
        "200":
          description: List of tokens (hashes never returned)
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ApiToken"
        "401":
          $ref: "#/components/responses/Unauthorized"
    post:
      operationId: createToken
      tags: [tokens]
      summary: Create a new API token (plaintext returned once)
      security:
        - sessionAuth: []
        - bearerToken: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateTokenBody"
      responses:
        "201":
          description: Token created — plaintext in `token` field, shown once only
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreatedToken"
        "401":
          $ref: "#/components/responses/Unauthorized"

  /tokens/{id}:
    delete:
      operationId: revokeToken
      tags: [tokens]
      summary: Revoke an API token
      security:
        - sessionAuth: []
        - bearerToken: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "204":
          description: Token revoked
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"

  # ── Nodes ───────────────────────────────────────────────────────────────────

  /nodes:
    get:
      operationId: listNodes
      tags: [nodes]
      summary: List all federation nodes (paginated)
      parameters:
        - $ref: "#/components/parameters/PageParam"
        - $ref: "#/components/parameters/LimitParam"
      responses:
        "200":
          description: Paginated node list
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaginatedNodes"
    post:
      operationId: createNode
      tags: [nodes]
      summary: Register a new node
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateNodeBody"
      responses:
        "201":
          description: Node registered
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Node"
        "400":
          $ref: "#/components/responses/BadRequest"

  /nodes/{id}:
    get:
      operationId: getNode
      tags: [nodes]
      summary: Get node by ID
      parameters:
        - $ref: "#/components/parameters/IdPath"
      responses:
        "200":
          description: Node details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Node"
        "404":
          $ref: "#/components/responses/NotFound"
    patch:
      operationId: updateNode
      tags: [nodes]
      summary: Update a node
      parameters:
        - $ref: "#/components/parameters/IdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateNodeBody"
      responses:
        "200":
          description: Updated node
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Node"
        "404":
          $ref: "#/components/responses/NotFound"
    delete:
      operationId: deleteNode
      tags: [nodes]
      summary: Remove a node from the federation
      parameters:
        - $ref: "#/components/parameters/IdPath"
      responses:
        "204":
          description: Node removed
        "404":
          $ref: "#/components/responses/NotFound"

  /nodes/{id}/generate-keys:
    post:
      operationId: generateNodeKeys
      tags: [nodes]
      summary: Generate or rotate Ed25519 key pair for a node
      parameters:
        - $ref: "#/components/parameters/IdPath"
      responses:
        "200":
          description: New key pair generated (private key stored, not returned)
          content:
            application/json:
              schema:
                type: object
                properties:
                  nodeId:
                    type: integer
                  publicKey:
                    type: string
                  message:
                    type: string

  /nodes/{id}/capacity:
    get:
      operationId: getNodeCapacity
      tags: [capacity]
      summary: Get capacity stats for a specific node
      parameters:
        - $ref: "#/components/parameters/IdPath"
      responses:
        "200":
          description: Node capacity details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NodeCapacity"

  # ── Sites ───────────────────────────────────────────────────────────────────

  /sites:
    get:
      operationId: listSites
      tags: [sites]
      summary: List all sites (paginated, filterable)
      parameters:
        - $ref: "#/components/parameters/PageParam"
        - $ref: "#/components/parameters/LimitParam"
        - name: search
          in: query
          schema:
            type: string
        - name: status
          in: query
          schema:
            type: string
            enum: [active, suspended, migrating]
        - name: ownerId
          in: query
          schema:
            type: string
      responses:
        "200":
          description: Paginated site list
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaginatedSites"
    post:
      operationId: createSite
      tags: [sites]
      summary: Register a new site
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateSiteBody"
      responses:
        "201":
          description: Site registered
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Site"
        "400":
          $ref: "#/components/responses/BadRequest"
        "409":
          $ref: "#/components/responses/Conflict"

  /sites/{id}:
    get:
      operationId: getSite
      tags: [sites]
      summary: Get site by ID
      parameters:
        - $ref: "#/components/parameters/IdPath"
      responses:
        "200":
          description: Site details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Site"
        "404":
          $ref: "#/components/responses/NotFound"
    patch:
      operationId: updateSite
      tags: [sites]
      summary: Update site metadata
      parameters:
        - $ref: "#/components/parameters/IdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateSiteBody"
      responses:
        "200":
          description: Updated site
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Site"
        "404":
          $ref: "#/components/responses/NotFound"
    delete:
      operationId: deleteSite
      tags: [sites]
      summary: Delete a site and all its files
      parameters:
        - $ref: "#/components/parameters/IdPath"
      responses:
        "204":
          description: Site deleted
        "404":
          $ref: "#/components/responses/NotFound"

  # ── Deployment ──────────────────────────────────────────────────────────────

  /sites/{id}/files/upload-url:
    post:
      operationId: getSiteFileUploadUrl
      tags: [deploy]
      summary: Get a presigned URL to upload a site file
      security:
        - sessionAuth: []
        - bearerToken: []
      parameters:
        - $ref: "#/components/parameters/IdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SiteFileUploadUrlBody"
      responses:
        "200":
          description: Presigned upload URL
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SiteFileUploadUrlResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"

  /sites/{id}/files:
    get:
      operationId: listSiteFiles
      tags: [deploy]
      summary: List all files registered for a site
      parameters:
        - $ref: "#/components/parameters/IdPath"
      responses:
        "200":
          description: List of site files
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/SiteFile"
    post:
      operationId: registerSiteFile
      tags: [deploy]
      summary: Register an uploaded file for a site
      security:
        - sessionAuth: []
        - bearerToken: []
      parameters:
        - $ref: "#/components/parameters/IdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RegisterSiteFileBody"
      responses:
        "201":
          description: File registered
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SiteFile"
        "401":
          $ref: "#/components/responses/Unauthorized"

  /sites/{id}/deploy:
    post:
      operationId: deploySite
      tags: [deploy]
      summary: Atomically deploy all pending files and notify federation peers
      security:
        - sessionAuth: []
        - bearerToken: []
      parameters:
        - $ref: "#/components/parameters/IdPath"
      responses:
        "200":
          description: Deployment activated with replication results
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DeployResult"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"

  /sites/{id}/deployments:
    get:
      operationId: listSiteDeployments
      tags: [deploy]
      summary: List deployment history for a site
      parameters:
        - $ref: "#/components/parameters/IdPath"
      responses:
        "200":
          description: Deployment history
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/SiteDeployment"

  /sites/{id}/deployments/{depId}/rollback:
    post:
      operationId: rollbackDeployment
      tags: [deploy]
      summary: Roll back to a specific previous deployment version
      description: |
        Creates a new active deployment pointing to the files from the target
        deployment. The current active deployment is marked as rolled_back.
        History is fully preserved — rollback is a forward operation.
      security:
        - sessionAuth: []
        - bearerToken: []
      parameters:
        - $ref: "#/components/parameters/IdPath"
        - name: depId
          in: path
          required: true
          schema:
            type: integer
          description: ID of the deployment to roll back to
      responses:
        "200":
          description: Rollback successful — new deployment record created
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/SiteDeployment"
                  - type: object
                    properties:
                      rolledBackFrom:
                        type: integer
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"

  # ── Access Control ──────────────────────────────────────────────────────────

  /sites/{id}/members:
    get:
      operationId: listSiteMembers
      tags: [access]
      summary: List team members for a site
      security:
        - sessionAuth: []
        - bearerToken: []
      parameters:
        - $ref: "#/components/parameters/IdPath"
      responses:
        "200":
          description: Site members
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/SiteMember"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
    post:
      operationId: addSiteMember
      tags: [access]
      summary: Add a user to a site
      security:
        - sessionAuth: []
        - bearerToken: []
      parameters:
        - $ref: "#/components/parameters/IdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AddMemberBody"
      responses:
        "201":
          description: Member added
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SiteMember"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "409":
          $ref: "#/components/responses/Conflict"

  /sites/{id}/members/{memberId}:
    patch:
      operationId: updateSiteMember
      tags: [access]
      summary: Update a team member's role
      security:
        - sessionAuth: []
        - bearerToken: []
      parameters:
        - $ref: "#/components/parameters/IdPath"
        - name: memberId
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [role]
              properties:
                role:
                  type: string
                  enum: [editor, viewer]
      responses:
        "200":
          description: Member updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SiteMember"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
    delete:
      operationId: removeSiteMember
      tags: [access]
      summary: Remove a team member from a site
      security:
        - sessionAuth: []
        - bearerToken: []
      parameters:
        - $ref: "#/components/parameters/IdPath"
        - name: memberId
          in: path
          required: true
          schema:
            type: integer
      responses:
        "204":
          description: Member removed
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"

  /sites/{id}/visibility:
    patch:
      operationId: updateSiteVisibility
      tags: [access]
      summary: Set site visibility (public / private / password-protected)
      security:
        - sessionAuth: []
        - bearerToken: []
      parameters:
        - $ref: "#/components/parameters/IdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateVisibilityBody"
      responses:
        "200":
          description: Visibility updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                  visibility:
                    type: string
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"

  /sites/{id}/unlock:
    post:
      operationId: unlockSite
      tags: [access]
      summary: Verify a site password and set an unlock cookie
      parameters:
        - $ref: "#/components/parameters/IdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [password]
              properties:
                password:
                  type: string
      responses:
        "200":
          description: Password correct — unlock cookie set
          content:
            application/json:
              schema:
                type: object
                properties:
                  unlocked:
                    type: boolean
        "403":
          $ref: "#/components/responses/Forbidden"

  # ── Custom Domains ──────────────────────────────────────────────────────────

  /sites/{id}/domains:
    get:
      operationId: listCustomDomains
      tags: [domains]
      summary: List custom domains for a site
      security:
        - sessionAuth: []
        - bearerToken: []
      parameters:
        - $ref: "#/components/parameters/IdPath"
      responses:
        "200":
          description: Custom domains
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/CustomDomain"
        "401":
          $ref: "#/components/responses/Unauthorized"
    post:
      operationId: addCustomDomain
      tags: [domains]
      summary: Add a custom domain and get DNS verification instructions
      security:
        - sessionAuth: []
        - bearerToken: []
      parameters:
        - $ref: "#/components/parameters/IdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [domain]
              properties:
                domain:
                  type: string
                  example: "www.mysite.com"
      responses:
        "201":
          description: Domain added with DNS instructions
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CustomDomainWithInstructions"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "409":
          $ref: "#/components/responses/Conflict"

  /domains/{id}/verify:
    post:
      operationId: verifyCustomDomain
      tags: [domains]
      summary: Trigger a DNS TXT verification check for a domain
      security:
        - sessionAuth: []
        - bearerToken: []
      parameters:
        - $ref: "#/components/parameters/IdPath"
      responses:
        "200":
          description: Verification result
          content:
            application/json:
              schema:
                type: object
                properties:
                  verified:
                    type: boolean
                  domain:
                    type: string
                  status:
                    type: string
                  lastError:
                    type: ["string", "null"]
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"

  /domains/{id}:
    delete:
      operationId: deleteCustomDomain
      tags: [domains]
      summary: Remove a custom domain from a site
      security:
        - sessionAuth: []
        - bearerToken: []
      parameters:
        - $ref: "#/components/parameters/IdPath"
      responses:
        "204":
          description: Domain removed
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"

  # ── Analytics ───────────────────────────────────────────────────────────────

  /sites/{id}/analytics:
    get:
      operationId: getSiteAnalytics
      tags: [analytics]
      summary: Get per-site analytics for a time period
      parameters:
        - $ref: "#/components/parameters/IdPath"
        - name: period
          in: query
          schema:
            type: string
            enum: ["24h", "7d", "30d"]
            default: "24h"
      responses:
        "200":
          description: Analytics data
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SiteAnalyticsResponse"

  /admin/analytics:
    get:
      operationId: getAdminAnalytics
      tags: [analytics]
      summary: Network-wide analytics aggregate (operator only)
      security:
        - sessionAuth: []
        - bearerToken: []
      responses:
        "200":
          description: Network analytics
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AdminAnalyticsResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"

  # ── Admin ───────────────────────────────────────────────────────────────────

  /admin/overview:
    get:
      operationId: getAdminOverview
      tags: [admin]
      summary: Full node operator dashboard data
      security:
        - sessionAuth: []
        - bearerToken: []
      responses:
        "200":
          description: Admin overview
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AdminOverview"
        "401":
          $ref: "#/components/responses/Unauthorized"

  /admin/node:
    patch:
      operationId: updateNodeSettings
      tags: [admin]
      summary: Update local node operator settings
      security:
        - sessionAuth: []
        - bearerToken: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateNodeSettingsBody"
      responses:
        "200":
          description: Updated node
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Node"
        "401":
          $ref: "#/components/responses/Unauthorized"

  /admin/users:
    get:
      operationId: listAdminUsers
      tags: [admin]
      summary: List all registered users (paginated)
      security:
        - sessionAuth: []
        - bearerToken: []
      parameters:
        - $ref: "#/components/parameters/PageParam"
        - $ref: "#/components/parameters/LimitParam"
      responses:
        "200":
          description: Paginated user list
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaginatedUsers"
        "401":
          $ref: "#/components/responses/Unauthorized"

  /admin/sites:
    get:
      operationId: listAdminSites
      tags: [admin]
      summary: List all sites with owner info (paginated)
      security:
        - sessionAuth: []
        - bearerToken: []
      parameters:
        - $ref: "#/components/parameters/PageParam"
        - $ref: "#/components/parameters/LimitParam"
      responses:
        "200":
          description: Paginated site list
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaginatedSites"
        "401":
          $ref: "#/components/responses/Unauthorized"

  # ── Capacity ─────────────────────────────────────────────────────────────────

  /capacity/summary:
    get:
      operationId: getCapacitySummary
      tags: [capacity]
      summary: Network-wide storage and bandwidth summary
      responses:
        "200":
          description: Capacity summary
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CapacitySummary"

  # ── Federation Protocol ──────────────────────────────────────────────────────

  /federation/meta:
    get:
      operationId: getFederationMeta
      tags: [federation]
      summary: Local node federation metadata
      responses:
        "200":
          description: Node metadata
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FederationMeta"

  /federation/handshake:
    post:
      operationId: initiateHandshake
      tags: [federation]
      summary: Initiate a signed handshake with a remote node
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [targetNodeUrl]
              properties:
                targetNodeUrl:
                  type: string
                  example: "https://node2.example.com"
      responses:
        "200":
          description: Handshake result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HandshakeResult"

  /federation/ping:
    post:
      operationId: federationPing
      tags: [federation]
      summary: Receive a signed ping from a remote node
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/FederationPingBody"
      responses:
        "200":
          description: Ping verified
          content:
            application/json:
              schema:
                type: object
                properties:
                  verified:
                    type: boolean
                  protocol:
                    type: string
                  challenge:
                    type: string
        "401":
          $ref: "#/components/responses/Unauthorized"

  /federation/sync:
    post:
      operationId: federationSync
      tags: [federation]
      summary: |
        Receive a site_sync notification from a peer — fetch the file manifest
        and replicate all files to local object storage.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [siteDomain, deploymentId]
              properties:
                siteDomain:
                  type: string
                deploymentId:
                  type: integer
                timestamp:
                  type: string
      responses:
        "200":
          description: Sync complete
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FederationSyncResult"
        "202":
          description: Queued (manifest temporarily unavailable)

  /federation/manifest/{siteDomain}:
    get:
      operationId: getFederationManifest
      tags: [federation]
      summary: |
        Get the signed file manifest for a site. Used by peers to replicate
        files. Returns presigned download URLs valid for 1 hour.
      parameters:
        - name: siteDomain
          in: path
          required: true
          schema:
            type: string
        - name: deploymentId
          in: query
          required: false
          schema:
            type: integer
      responses:
        "200":
          description: Signed file manifest
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FederationManifest"
        "404":
          $ref: "#/components/responses/NotFound"

  /federation/peers:
    get:
      operationId: listFederationPeers
      tags: [federation]
      summary: List known federation peers (paginated)
      parameters:
        - $ref: "#/components/parameters/PageParam"
        - $ref: "#/components/parameters/LimitParam"
      responses:
        "200":
          description: Paginated peer list
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaginatedNodes"

  /federation/events:
    get:
      operationId: listFederationEvents
      tags: [federation]
      summary: Federation event log (paginated, newest first)
      parameters:
        - $ref: "#/components/parameters/PageParam"
        - $ref: "#/components/parameters/LimitParam"
      responses:
        "200":
          description: Paginated event log
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaginatedEvents"

  # ── Gossip ───────────────────────────────────────────────────────────────────

  /federation/gossip:
    get:
      operationId: getGossipPeers
      tags: [gossip]
      summary: Return this node's known peer list for gossip consumption
      responses:
        "200":
          description: Known peers
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GossipResponse"

  /federation/gossip/push:
    post:
      operationId: receiveGossip
      tags: [gossip]
      summary: Receive a peer list from a remote node
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/GossipPushBody"
      responses:
        "200":
          description: Gossip processed
          content:
            application/json:
              schema:
                type: object
                properties:
                  accepted:
                    type: integer
                  newPeers:
                    type: integer

  /federation/gossip/discover:
    post:
      operationId: triggerGossipDiscover
      tags: [gossip]
      summary: Manually trigger a gossip discovery cycle across all active peers
      security:
        - sessionAuth: []
        - bearerToken: []
      responses:
        "200":
          description: Discovery results
          content:
            application/json:
              schema:
                type: object
                properties:
                  peersQueried:
                    type: integer
                  totalNewNodes:
                    type: integer
        "401":
          $ref: "#/components/responses/Unauthorized"

  /federation/bootstrap:
    get:
      operationId: getBootstrapNodes
      tags: [gossip]
      summary: |
        Public bootstrap node registry. Returns healthy, recently-verified peers
        that new nodes can use to seed their peer list.
      responses:
        "200":
          description: Bootstrap node list
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BootstrapResponse"

  # ── Storage ──────────────────────────────────────────────────────────────────

  /storage/uploads/request-url:
    post:
      operationId: requestUploadUrl
      tags: [storage]
      summary: Request a presigned URL for direct file upload
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RequestUploadUrlBody"
      responses:
        "200":
          description: Presigned upload URL
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RequestUploadUrlResponse"

  /storage/public-objects/{filePath*}:
    get:
      operationId: getPublicObject
      tags: [storage]
      summary: Serve a public asset
      parameters:
        - name: filePath
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Object content
          content:
            "*/*":
              schema:
                type: string
                format: binary

components:
  securitySchemes:
    sessionAuth:
      type: apiKey
      in: cookie
      name: sid
      description: Browser session cookie set by /login flow
    bearerToken:
      type: http
      scheme: bearer
      description: API token created via POST /tokens (prefix fh_)

  parameters:
    IdPath:
      name: id
      in: path
      required: true
      schema:
        type: integer
    PageParam:
      name: page
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
        default: 1
    LimitParam:
      name: limit
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
    AuthorizationSessionHeader:
      name: Authorization
      in: header
      required: false
      description: "Bearer <sid> — session token"
      schema:
        type: string
    SessionCookie:
      name: sid
      in: cookie
      required: false
      schema:
        type: string

  responses:
    BadRequest:
      description: Validation error
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    Unauthorized:
      description: Authentication required
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    Forbidden:
      description: Insufficient permissions
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    Conflict:
      description: Resource already exists
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"

  schemas:

    ErrorResponse:
      type: object
      required: [message, code]
      properties:
        message:
          type: string
        code:
          type: string
        status:
          type: integer

    PaginationMeta:
      type: object
      required: [total, page, limit, totalPages, hasNextPage, hasPrevPage]
      properties:
        total:
          type: integer
        page:
          type: integer
        limit:
          type: integer
        totalPages:
          type: integer
        hasNextPage:
          type: boolean
        hasPrevPage:
          type: boolean

    HealthStatus:
      type: object
      required: [status]
      properties:
        status:
          type: string
          enum: [healthy, degraded, error]
        uptime:
          type: number
        version:
          type: string
        environment:
          type: string
        services:
          type: object

    FederationStats:
      type: object
      required: [totalNodes, activeNodes, totalSites, activeSites, totalBandwidthGb, totalStorageGb, uptimePercent]
      properties:
        totalNodes:
          type: integer
        activeNodes:
          type: integer
        totalSites:
          type: integer
        activeSites:
          type: integer
        totalBandwidthGb:
          type: number
        totalStorageGb:
          type: number
        uptimePercent:
          type: number

    Node:
      type: object
      required: [id, name, domain, status, region, operatorName, operatorEmail, storageCapacityGb, bandwidthCapacityGb, joinedAt]
      properties:
        id:
          type: integer
        name:
          type: string
        domain:
          type: string
        description:
          type: ["string", "null"]
        status:
          type: string
          enum: [active, inactive, maintenance]
        region:
          type: string
        operatorName:
          type: string
        operatorEmail:
          type: string
        storageCapacityGb:
          type: number
        bandwidthCapacityGb:
          type: number
        uptimePercent:
          type: number
        siteCount:
          type: integer
        publicKey:
          type: ["string", "null"]
        isLocalNode:
          type: integer
        joinedAt:
          type: string
        lastSeenAt:
          type: ["string", "null"]
        verifiedAt:
          type: ["string", "null"]

    PaginatedNodes:
      type: object
      required: [data, meta]
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/Node"
        meta:
          $ref: "#/components/schemas/PaginationMeta"

    CreateNodeBody:
      type: object
      required: [name, domain, region, operatorName, operatorEmail, storageCapacityGb, bandwidthCapacityGb]
      properties:
        name:
          type: string
        domain:
          type: string
        description:
          type: string
        region:
          type: string
        operatorName:
          type: string
        operatorEmail:
          type: string
        storageCapacityGb:
          type: number
        bandwidthCapacityGb:
          type: number
        publicKey:
          type: string

    UpdateNodeBody:
      type: object
      properties:
        name:
          type: string
        description:
          type: string
        status:
          type: string
          enum: [active, inactive, maintenance]
        region:
          type: string
        operatorName:
          type: string
        operatorEmail:
          type: string
        storageCapacityGb:
          type: number
        bandwidthCapacityGb:
          type: number

    NodeCapacity:
      type: object
      properties:
        nodeId:
          type: integer
        domain:
          type: string
        storageCapacityGb:
          type: number
        storageUsedGb:
          type: number
        storageAvailableGb:
          type: number
        bandwidthCapacityGb:
          type: number
        siteCount:
          type: integer

    Site:
      type: object
      required: [id, name, domain, status, siteType, ownerName, ownerEmail, createdAt]
      properties:
        id:
          type: integer
        name:
          type: string
        domain:
          type: string
        description:
          type: ["string", "null"]
        status:
          type: string
          enum: [active, suspended, migrating]
        siteType:
          type: string
          enum: [static, dynamic, blog, portfolio, other]
        visibility:
          type: string
          enum: [public, private, password]
        ownerName:
          type: string
        ownerEmail:
          type: string
        ownerId:
          type: ["string", "null"]
        primaryNodeId:
          type: ["integer", "null"]
        primaryNodeDomain:
          type: ["string", "null"]
        replicaCount:
          type: integer
        storageUsedMb:
          type: number
        monthlyBandwidthGb:
          type: number
        hitCount:
          type: integer
        createdAt:
          type: string
        updatedAt:
          type: string

    PaginatedSites:
      type: object
      required: [data, meta]
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/Site"
        meta:
          $ref: "#/components/schemas/PaginationMeta"

    CreateSiteBody:
      type: object
      required: [name, domain, siteType, ownerName, ownerEmail]
      properties:
        name:
          type: string
        domain:
          type: string
        description:
          type: string
        siteType:
          type: string
          enum: [static, dynamic, blog, portfolio, other]
        ownerName:
          type: string
        ownerEmail:
          type: string
        primaryNodeId:
          type: integer

    UpdateSiteBody:
      type: object
      properties:
        name:
          type: string
        description:
          type: string
        status:
          type: string
          enum: [active, suspended, migrating]
        siteType:
          type: string
          enum: [static, dynamic, blog, portfolio, other, nlpl]
        primaryNodeId:
          type: integer
        spaRouting:
          type: integer
          enum: [0, 1]
          description: "1 = serve index.html for unknown paths (SPA), 0 = strict 404 (MPA)"

    SiteFile:
      type: object
      required: [id, siteId, filePath, objectPath, contentType, sizeBytes, createdAt]
      properties:
        id:
          type: integer
        siteId:
          type: integer
        deploymentId:
          type: ["integer", "null"]
        filePath:
          type: string
        objectPath:
          type: string
        contentType:
          type: string
        sizeBytes:
          type: integer
        createdAt:
          type: string

    SiteFileUploadUrlBody:
      type: object
      required: [filePath, contentType, size]
      properties:
        filePath:
          type: string
        contentType:
          type: string
        size:
          type: integer

    SiteFileUploadUrlResponse:
      type: object
      required: [uploadUrl, objectPath, filePath]
      properties:
        uploadUrl:
          type: string
        objectPath:
          type: string
        filePath:
          type: string

    RegisterSiteFileBody:
      type: object
      required: [filePath, objectPath, contentType, sizeBytes]
      properties:
        filePath:
          type: string
        objectPath:
          type: string
        contentType:
          type: string
        sizeBytes:
          type: integer

    SiteDeployment:
      type: object
      required: [id, siteId, version, status, fileCount, totalSizeMb, deployedAt]
      properties:
        id:
          type: integer
        siteId:
          type: integer
        version:
          type: integer
        status:
          type: string
          enum: [pending, active, failed, rolled_back]
        deployedBy:
          type: ["string", "null"]
        fileCount:
          type: integer
        totalSizeMb:
          type: number
        deployedAt:
          type: string
        createdAt:
          type: string

    DeployResult:
      allOf:
        - $ref: "#/components/schemas/SiteDeployment"
        - type: object
          properties:
            replication:
              type: object
              properties:
                peers:
                  type: integer
                synced:
                  type: integer
                results:
                  type: array
                  items:
                    type: object
                    properties:
                      node:
                        type: string
                      success:
                        type: boolean
                      error:
                        type: ["string", "null"]

    ApiToken:
      type: object
      required: [id, name, tokenPrefix, createdAt]
      properties:
        id:
          type: integer
        name:
          type: string
        tokenPrefix:
          type: string
        lastUsedAt:
          type: ["string", "null"]
        expiresAt:
          type: ["string", "null"]
        createdAt:
          type: string
        revokedAt:
          type: ["string", "null"]

    CreatedToken:
      allOf:
        - $ref: "#/components/schemas/ApiToken"
        - type: object
          required: [token]
          properties:
            token:
              type: string
              description: "Plaintext token — shown once only. Store securely."

    CreateTokenBody:
      type: object
      required: [name]
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 80
        expiresInDays:
          type: integer
          minimum: 1
          maximum: 365

    SiteMember:
      type: object
      required: [id, siteId, userId, role, createdAt]
      properties:
        id:
          type: integer
        siteId:
          type: integer
        userId:
          type: string
        role:
          type: string
          enum: [owner, editor, viewer]
        invitedByUserId:
          type: ["string", "null"]
        acceptedAt:
          type: ["string", "null"]
        createdAt:
          type: string
        email:
          type: ["string", "null"]
        firstName:
          type: ["string", "null"]
        lastName:
          type: ["string", "null"]

    AddMemberBody:
      type: object
      required: [userId]
      properties:
        userId:
          type: string
        role:
          type: string
          enum: [editor, viewer]
          default: viewer

    UpdateVisibilityBody:
      type: object
      required: [visibility]
      properties:
        visibility:
          type: string
          enum: [public, private, password]
        password:
          type: string
          minLength: 6
          description: Required when visibility is "password"

    CustomDomain:
      type: object
      required: [id, siteId, domain, verificationToken, status, createdAt]
      properties:
        id:
          type: integer
        siteId:
          type: integer
        domain:
          type: string
        verificationToken:
          type: string
        status:
          type: string
          enum: [pending, verified, failed]
        verifiedAt:
          type: ["string", "null"]
        lastCheckedAt:
          type: ["string", "null"]
        lastError:
          type: ["string", "null"]
        createdAt:
          type: string

    CustomDomainWithInstructions:
      allOf:
        - $ref: "#/components/schemas/CustomDomain"
        - type: object
          properties:
            instructions:
              type: object
              properties:
                txt:
                  type: object
                  properties:
                    name:
                      type: string
                    type:
                      type: string
                    value:
                      type: string
                cname:
                  type: object
                  properties:
                    name:
                      type: string
                    type:
                      type: string
                    value:
                      type: string

    SiteAnalyticsResponse:
      type: object
      properties:
        period:
          type: string
        totals:
          type: object
          properties:
            hits:
              type: integer
            bytesServed:
              type: integer
            uniqueIps:
              type: integer
        hourly:
          type: array
          items:
            type: object
        topReferrers:
          type: array
          items:
            type: object
            properties:
              referrer:
                type: string
              count:
                type: integer
        topPaths:
          type: array
          items:
            type: object
            properties:
              path:
                type: string
              count:
                type: integer

    AdminAnalyticsResponse:
      type: object
      properties:
        last24h:
          type: object
          properties:
            hits:
              type: integer
            bytesServed:
              type: integer
        last7d:
          type: object
          properties:
            hits:
              type: integer
            bytesServed:
              type: integer
        topSites:
          type: array
          items:
            type: object

    AdminOverview:
      type: object
      properties:
        node:
          $ref: "#/components/schemas/Node"
        summary:
          type: object
        analytics24h:
          type: object
        recentEvents:
          type: array
          items:
            type: object
        systemInfo:
          type: object

    UpdateNodeSettingsBody:
      type: object
      properties:
        name:
          type: string
        region:
          type: string
        operatorEmail:
          type: string
          format: email
        maxStorageGb:
          type: number
        description:
          type: string

    PaginatedUsers:
      type: object
      required: [data, meta]
      properties:
        data:
          type: array
          items:
            type: object
        meta:
          $ref: "#/components/schemas/PaginationMeta"

    CapacitySummary:
      type: object
      properties:
        totalNodes:
          type: integer
        totalStorageGb:
          type: number
        usedStorageGb:
          type: number
        totalBandwidthGb:
          type: number

    FederationMeta:
      type: object
      properties:
        protocol:
          type: string
        name:
          type: string
        domain:
          type: string
        region:
          type: string
        publicKey:
          type: ["string", "null"]
        nodeCount:
          type: integer
        activeSites:
          type: integer
        joinedAt:
          type: string
        capabilities:
          type: array
          items:
            type: string

    HandshakeResult:
      type: object
      properties:
        success:
          type: boolean
        targetUrl:
          type: string
        discoveryData:
          type: ["object", "null"]
        pingResult:
          type: ["object", "null"]
        error:
          type: ["string", "null"]

    FederationPingBody:
      type: object
      required: [nodeDomain, challenge, signature]
      properties:
        nodeDomain:
          type: string
        challenge:
          type: string
        signature:
          type: string
        timestamp:
          type: string

    FederationSyncResult:
      type: object
      properties:
        status:
          type: string
          enum: [synced, skipped, queued, failed]
        siteDomain:
          type: string
        filesSync:
          type: integer
        failedFiles:
          type: integer
        originDomain:
          type: string

    FederationManifest:
      type: object
      properties:
        site:
          type: object
        deployment:
          $ref: "#/components/schemas/SiteDeployment"
        files:
          type: array
          items:
            type: object
            properties:
              filePath:
                type: string
              contentType:
                type: string
              sizeBytes:
                type: integer
              downloadUrl:
                type: string
        signature:
          type: ["string", "null"]
        servedBy:
          type: string
        expiresAt:
          type: string

    PaginatedEvents:
      type: object
      required: [data, meta]
      properties:
        data:
          type: array
          items:
            type: object
        meta:
          $ref: "#/components/schemas/PaginationMeta"

    GossipResponse:
      type: object
      properties:
        domain:
          type: string
        peerCount:
          type: integer
        peers:
          type: array
          items:
            type: object
        servedAt:
          type: string

    GossipPushBody:
      type: object
      required: [fromDomain, peers, timestamp]
      properties:
        fromDomain:
          type: string
        peers:
          type: array
          items:
            type: object
            properties:
              domain:
                type: string
              name:
                type: string
              publicKey:
                type: string
              region:
                type: string
        timestamp:
          type: number

    BootstrapResponse:
      type: object
      properties:
        protocol:
          type: string
        description:
          type: string
        servedBy:
          type: string
        generatedAt:
          type: string
        nodeCount:
          type: integer
        nodes:
          type: array
          items:
            type: object
            properties:
              domain:
                type: string
              name:
                type: string
              region:
                type: string
              publicKey:
                type: ["string", "null"]
              verifiedAt:
                type: ["string", "null"]
        docs:
          type: string

    AuthUser:
      type: object
      required: [id]
      properties:
        id:
          type: string
        email:
          type: ["string", "null"]
        firstName:
          type: ["string", "null"]
        lastName:
          type: ["string", "null"]
        profileImageUrl:
          type: ["string", "null"]

    GetCurrentAuthUserResponse:
      type: object
      required: [user]
      properties:
        user:
          oneOf:
            - $ref: "#/components/schemas/AuthUser"
            - type: "null"

    ExchangeMobileAuthorizationCodeBody:
      type: object
      required: [code, code_verifier, redirect_uri, state]
      properties:
        code:
          type: string
        code_verifier:
          type: string
        redirect_uri:
          type: string
        state:
          type: string
        nonce:
          type: string

    ExchangeMobileAuthorizationCodeResponse:
      type: object
      required: [token]
      properties:
        token:
          type: string

    LogoutMobileSessionResponse:
      type: object
      required: [success]
      properties:
        success:
          type: boolean

    RequestUploadUrlBody:
      type: object
      required: [name, size, contentType]
      properties:
        name:
          type: string
        size:
          type: integer
        contentType:
          type: string

    RequestUploadUrlResponse:
      type: object
      required: [uploadURL, objectPath]
      properties:
        uploadURL:
          type: string
        objectPath:
          type: string

  /domains/{id}/tls-status:
    get:
      summary: Get TLS certificate status for a custom domain
      tags: [Domains]
      security: [{sessionCookie: []}, {bearerToken: []}]
      parameters:
        - {name: id, in: path, required: true, schema: {type: integer}}
      responses:
        '200':
          description: TLS status
          content:
            application/json:
              schema:
                type: object
                properties:
                  domainId: {type: integer}
                  domain: {type: string}
                  domainVerified: {type: boolean}
                  acmeEnabled: {type: boolean}
                  certExists: {type: boolean}
                  certExpiry: {type: string, nullable: true}
                  daysUntilExpiry: {type: integer, nullable: true}
                  isValid: {type: boolean}
                  willAutoRenew: {type: boolean}

  /domains/{id}/provision-tls:
    post:
      summary: Provision or renew a TLS certificate for a custom domain
      tags: [Domains]
      security: [{sessionCookie: []}, {bearerToken: []}]
      parameters:
        - {name: id, in: path, required: true, schema: {type: integer}}
        - {name: force, in: query, schema: {type: boolean}}
      responses:
        '200':
          description: Provisioning started or status response
          content:
            application/json:
              schema:
                type: object
                properties:
                  status: {type: string, enum: [provisioning, already_valid, manual_required]}
                  domain: {type: string}
                  message: {type: string}

  /admin/audit-log:
    get:
      summary: Paginated admin action history
      tags: [Admin]
      security: [{sessionCookie: []}, {bearerToken: []}]
      parameters:
        - {name: page,  in: query, schema: {type: integer, default: 1}}
        - {name: limit, in: query, schema: {type: integer, default: 50, maximum: 100}}
      responses:
        '200':
          description: Audit log entries
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id: {type: integer}
                        actor_id: {type: string}
                        actor_email: {type: string, nullable: true}
                        action: {type: string}
                        target_type: {type: string, nullable: true}
                        target_id: {type: string, nullable: true}
                        metadata: {type: object, nullable: true}
                        ip_address: {type: string, nullable: true}
                        created_at: {type: string, format: date-time}
                  meta:
                    type: object
                    properties:
                      total: {type: integer}
                      page: {type: integer}
                      limit: {type: integer}

  /metrics:
    get:
      summary: Prometheus metrics scrape endpoint
      tags: [Monitoring]
      security: [{bearerToken: []}]
      responses:
        '200':
          description: Prometheus text format metrics
          content:
            text/plain:
              schema: {type: string}
        '401':
          description: Unauthorized (METRICS_TOKEN mismatch)

  /sites/{id}/redirects:
    get:
      summary: List redirect rules
      tags: [Sites]
      security: [{sessionCookie: []}, {bearerToken: []}]
      parameters: [{name: id, in: path, required: true, schema: {type: integer}}]
      responses:
        '200': {description: Redirect rules array}
    post:
      summary: Create redirect rule
      tags: [Sites]
      security: [{sessionCookie: []}, {bearerToken: []}]
      parameters: [{name: id, in: path, required: true, schema: {type: integer}}]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [src, dest]
              properties:
                src:      {type: string, example: "/old-path/:slug"}
                dest:     {type: string, example: "/new-path/:slug"}
                status:   {type: integer, enum: [200, 301, 302, 307, 308, 404, 410], default: 301}
                force:    {type: boolean, default: false}
                position: {type: integer, default: 0}
      responses:
        '201': {description: Created rule}
    put:
      summary: Replace all redirect rules (bulk update)
      tags: [Sites]
      security: [{sessionCookie: []}, {bearerToken: []}]
      parameters: [{name: id, in: path, required: true, schema: {type: integer}}]
      requestBody:
        required: true
        content:
          application/json:
            schema: {type: array, items: {type: object}}
      responses:
        '200': {description: Updated rules}

  /sites/{id}/headers:
    get:
      summary: List custom response headers
      tags: [Sites]
      security: [{sessionCookie: []}, {bearerToken: []}]
      parameters: [{name: id, in: path, required: true, schema: {type: integer}}]
      responses:
        '200': {description: Custom headers array}
    post:
      summary: Create custom response header rule
      tags: [Sites]
      security: [{sessionCookie: []}, {bearerToken: []}]
      parameters: [{name: id, in: path, required: true, schema: {type: integer}}]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name, value]
              properties:
                path:  {type: string, default: "/*"}
                name:  {type: string, example: "X-Frame-Options"}
                value: {type: string, example: "DENY"}
      responses:
        '201': {description: Created header rule}

  /sites/{id}/invitations:
    get:
      summary: List pending invitations
      tags: [Sites]
      security: [{sessionCookie: []}, {bearerToken: []}]
      parameters: [{name: id, in: path, required: true, schema: {type: integer}}]
      responses:
        '200': {description: Pending invitations}
    post:
      summary: Send invitation email
      tags: [Sites]
      security: [{sessionCookie: []}, {bearerToken: []}]
      parameters: [{name: id, in: path, required: true, schema: {type: integer}}]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email]
              properties:
                email: {type: string, format: email}
                role:  {type: string, enum: [editor, viewer], default: viewer}
      responses:
        '201': {description: Invitation created and email sent}

  /invitations/{token}/accept:
    post:
      summary: Accept a site invitation
      tags: [Sites]
      security: [{sessionCookie: []}, {bearerToken: []}]
      parameters: [{name: token, in: path, required: true, schema: {type: string}}]
      responses:
        '200': {description: Invitation accepted, membership created}

  /sites/{id}/forms:
    get:
      summary: List form submissions
      tags: [Forms]
      security: [{sessionCookie: []}, {bearerToken: []}]
      parameters:
        - {name: id,    in: path,  required: true,  schema: {type: integer}}
        - {name: form,  in: query, required: false, schema: {type: string}}
        - {name: page,  in: query, schema: {type: integer, default: 1}}
        - {name: limit, in: query, schema: {type: integer, default: 50, maximum: 100}}
      responses:
        '200': {description: Form submissions with form breakdown}

  /forms/{domain}/{formName}:
    post:
      summary: Submit a form (public)
      tags: [Forms]
      parameters:
        - {name: domain,   in: path, required: true, schema: {type: string}}
        - {name: formName, in: path, required: true, schema: {type: string}}
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema: {type: object, additionalProperties: {type: string}}
          application/json:
            schema: {type: object, additionalProperties: {type: string}}
      responses:
        '200': {description: Submission accepted}
        '429': {description: Rate limit exceeded}

  /sites/{id}/builds:
    get:
      summary: List build jobs
      tags: [Builds]
      security: [{sessionCookie: []}, {bearerToken: []}]
      parameters:
        - {name: id,    in: path,  required: true,  schema: {type: integer}}
        - {name: page,  in: query, schema: {type: integer, default: 1}}
        - {name: limit, in: query, schema: {type: integer, default: 20}}
      responses:
        '200': {description: Build jobs list}
    post:
      summary: Trigger a build from Git
      tags: [Builds]
      security: [{sessionCookie: []}, {bearerToken: []}]
      parameters: [{name: id, in: path, required: true, schema: {type: integer}}]
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                gitUrl:         {type: string, format: uri}
                gitBranch:      {type: string, default: main}
                buildCommand:   {type: string, default: "npm run build"}
                outputDir:      {type: string, default: dist}
                environment:    {type: string, enum: [production, staging, preview]}
                installCommand: {type: string}
                envVars:        {type: object, additionalProperties: {type: string}}
      responses:
        '202': {description: Build queued}

  /git-webhook/{siteId}:
    post:
      summary: Receive GitHub/GitLab push webhook to auto-trigger builds
      tags: [Builds]
      parameters: [{name: siteId, in: path, required: true, schema: {type: integer}}]
      responses:
        '202': {description: Build triggered}
        '401': {description: Invalid webhook signature}

  /auth/2fa/setup:
    post:
      summary: Generate TOTP secret and QR code
      tags: [Auth]
      security: [{sessionCookie: []}]
      responses:
        '200':
          description: TOTP setup data
          content:
            application/json:
              schema:
                type: object
                properties:
                  secret: {type: string}
                  qrCode: {type: string, description: base64 data URL}
                  otpAuthUrl: {type: string}

  /auth/2fa/verify:
    post:
      summary: Confirm TOTP code and enable 2FA
      tags: [Auth]
      security: [{sessionCookie: []}]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [code, secret]
              properties:
                code:   {type: string, minLength: 6, maxLength: 6}
                secret: {type: string}
      responses:
        '200': {description: 2FA enabled, backup codes returned}

  /auth/2fa/validate:
    post:
      summary: Validate a TOTP or backup code
      tags: [Auth]
      security: [{sessionCookie: []}]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [code]
              properties:
                code: {type: string}
      responses:
        '200': {description: Code valid}
        '400': {description: Invalid code or account locked}

  /sites/{id}/transfer:
    post:
      summary: Initiate site ownership transfer
      tags: [Sites]
      security: [{sessionCookie: []}, {bearerToken: []}]
      parameters: [{name: id, in: path, required: true, schema: {type: integer}}]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [toEmail]
              properties:
                toEmail: {type: string, format: email}
      responses:
        '200': {description: Transfer token issued}

  /sites/{id}/export:
    get:
      summary: Export site data as JSON manifest
      tags: [Sites]
      security: [{sessionCookie: []}, {bearerToken: []}]
      parameters: [{name: id, in: path, required: true, schema: {type: integer}}]
      responses:
        '200': {description: Site export manifest with presigned file URLs}

  /sites/import:
    post:
      summary: Import site from export manifest
      tags: [Sites]
      security: [{sessionCookie: []}, {bearerToken: []}]
      responses:
        '201': {description: Site created from import}

  /sites/{id}/env:
    get:
      summary: List site build environment variables
      tags: [Builds]
      security: [{sessionCookie: []}, {bearerToken: []}]
      parameters:
        - {name: id,          in: path,  required: true,  schema: {type: integer}}
        - {name: showSecrets, in: query, required: false, schema: {type: boolean}}
      responses:
        '200': {description: Env vars (secrets masked unless showSecrets=1)}
    post:
      summary: Set a build environment variable
      tags: [Builds]
      security: [{sessionCookie: []}, {bearerToken: []}]
      parameters: [{name: id, in: path, required: true, schema: {type: integer}}]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [key, value]
              properties:
                key:    {type: string, pattern: "^[A-Z_][A-Z0-9_]{0,99}$"}
                value:  {type: string}
                secret: {type: integer, enum: [0, 1], default: 0}
      responses:
        '201': {description: Env var set}

  /sites/{id}/analytics/export:
    get:
      summary: Export analytics as CSV
      tags: [Analytics]
      security: [{sessionCookie: []}, {bearerToken: []}]
      parameters:
        - {name: id,     in: path,  required: true,  schema: {type: integer}}
        - {name: period, in: query, schema: {type: string, enum: [7d, 30d, all], default: 30d}}
      responses:
        '200':
          description: CSV file
          content: {text/csv: {schema: {type: string}}}

  /sites/{id}/analytics/stream:
    get:
      summary: Real-time analytics SSE stream
      tags: [Analytics]
      security: [{sessionCookie: []}, {bearerToken: []}]
      parameters: [{name: id, in: path, required: true, schema: {type: integer}}]
      responses:
        '200':
          description: Server-Sent Events stream of page hits
          content: {'text/event-stream': {schema: {type: string}}}

  /admin/site-health:
    get:
      summary: Site health monitoring overview
      tags: [Admin]
      security: [{sessionCookie: []}, {bearerToken: []}]
      responses:
        '200':
          description: Health status of all monitored sites
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:    {type: integer}
                  up:       {type: integer}
                  degraded: {type: integer}
                  down:     {type: integer}

  /sites/{id}/webhooks:
    get:
      summary: List webhooks for a site
      tags: [Webhooks]
      security: [{sessionCookie: []}, {bearerToken: []}]
      parameters: [{name: id, in: path, required: true, schema: {type: integer}}]
      responses:
        '200': {description: Webhook list (secrets masked)}
    post:
      summary: Create a webhook
      tags: [Webhooks]
      security: [{sessionCookie: []}, {bearerToken: []}]
      parameters: [{name: id, in: path, required: true, schema: {type: integer}}]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [url]
              properties:
                url:     {type: string, format: uri}
                secret:  {type: string}
                events:  {oneOf: [{type: string, enum: ['*']}, {type: array, items: {type: string}}]}
                enabled: {type: boolean, default: true}
      responses:
        '201': {description: Webhook created}

  /sites/{id}/webhooks/{hookId}:
    patch:
      summary: Update a webhook
      tags: [Webhooks]
      security: [{sessionCookie: []}, {bearerToken: []}]
      parameters:
        - {name: id,     in: path, required: true, schema: {type: integer}}
        - {name: hookId, in: path, required: true, schema: {type: integer}}
      responses:
        '200': {description: Updated webhook}
    delete:
      summary: Delete a webhook
      tags: [Webhooks]
      security: [{sessionCookie: []}, {bearerToken: []}]
      parameters:
        - {name: id,     in: path, required: true, schema: {type: integer}}
        - {name: hookId, in: path, required: true, schema: {type: integer}}
      responses:
        '204': {description: Deleted}

  /sites/{id}/webhooks/{hookId}/deliveries:
    get:
      summary: List recent webhook delivery attempts
      tags: [Webhooks]
      security: [{sessionCookie: []}, {bearerToken: []}]
      parameters:
        - {name: id,     in: path, required: true, schema: {type: integer}}
        - {name: hookId, in: path, required: true, schema: {type: integer}}
      responses:
        '200': {description: Last 50 deliveries with status, timing, retry count}

  /sites/{id}/clone:
    post:
      summary: Clone a site — copy all files to a new domain
      tags: [Sites]
      security: [{sessionCookie: []}, {bearerToken: []}]
      parameters: [{name: id, in: path, required: true, schema: {type: integer}}]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name, domain]
              properties:
                name:   {type: string}
                domain: {type: string}
      responses:
        '201': {description: Cloned site, no storage duplication (objectPaths reused)}

  /sites/{id}/deployments/{depId}/diff:
    get:
      summary: File-level diff between two deployments
      tags: [Sites]
      security: [{sessionCookie: []}, {bearerToken: []}]
      parameters:
        - {name: id,    in: path,  required: true,  schema: {type: integer}}
        - {name: depId, in: path,  required: true,  schema: {type: integer}}
        - {name: base,  in: query, required: false, schema: {type: integer}, description: "Base deployment ID; defaults to previous version"}
      responses:
        '200':
          description: Diff summary with added/changed/removed/unchanged file lists
          content:
            application/json:
              schema:
                type: object
                properties:
                  summary: {type: object, properties: {added: {type: integer}, changed: {type: integer}, removed: {type: integer}, unchanged: {type: integer}, netSizeBytes: {type: integer}}}
                  added:   {type: array}
                  changed: {type: array}
                  removed: {type: array}

  /tokens:
    get:
      summary: List API tokens for the current user
      tags: [Auth]
      security: [{sessionCookie: []}]
      responses:
        '200': {description: Token list (hashes never returned, prefix shown)}
    post:
      summary: Create an API token
      tags: [Auth]
      security: [{sessionCookie: []}]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name]
              properties:
                name:         {type: string}
                scopes:       {type: array, items: {type: string, enum: [read, write, deploy, admin]}, default: [read, write, deploy]}
                expiresInDays:{type: integer}
      responses:
        '201':
          description: Token created — plaintext in `token` field, shown once only

  /tokens/{id}:
    delete:
      summary: Revoke an API token
      tags: [Auth]
      security: [{sessionCookie: []}, {bearerToken: []}]
      parameters:
        - {name: id, in: path, required: true, schema: {type: integer}}
      responses:
        '204': {description: Token revoked}
        '404': {description: Token not found}

  # ── 2FA / TOTP ──────────────────────────────────────────────────────────────

  /auth/2fa/status:
    get:
      summary: Check whether 2FA is enabled for the current user
      tags: [Auth]
      security: [{sessionCookie: []}]
      responses:
        '200':
          description: 2FA status
          content:
            application/json:
              schema:
                type: object
                properties:
                  enabled:   {type: boolean}
                  enabledAt: {type: string, format: date-time, nullable: true}

  /auth/2fa/disable:
    post:
      summary: Disable 2FA (requires current TOTP code or backup code)
      tags: [Auth]
      security: [{sessionCookie: []}]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [code]
              properties:
                code: {type: string, minLength: 6, maxLength: 10}
      responses:
        '200': {description: 2FA disabled}

  /auth/2fa/backup:
    post:
      summary: Regenerate backup codes (invalidates existing codes)
      tags: [Auth]
      security: [{sessionCookie: []}]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [code]
              properties:
                code: {type: string, minLength: 6, maxLength: 6, description: Current TOTP code to confirm identity}
      responses:
        '200':
          description: New backup codes (only shown once)
          content:
            application/json:
              schema:
                type: object
                properties:
                  backupCodes: {type: array, items: {type: string}}

  /auth/2fa/complete:
    post:
      summary: Complete a 2FA login challenge (upgrades pending session to authenticated)
      tags: [Auth]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [code]
              properties:
                code: {type: string, minLength: 6, maxLength: 10, description: TOTP code or backup code}
      responses:
        '200':
          description: Authentication complete — session upgraded
          content:
            application/json:
              schema:
                type: object
                properties:
                  authenticated: {type: boolean}
                  method: {type: string, enum: [totp, backup]}
        '401': {description: No pending 2FA session}
        '400': {description: Invalid code or account locked}

  # ── NLPL / Dynamic site runtimes ─────────────────────────────────────────────

  /nlpl/runtime-info:
    get:
      summary: NLPL interpreter availability, version, and port range
      tags: [NLPL]
      responses:
        '200':
          description: Runtime info
          content:
            application/json:
              schema:
                type: object
                properties:
                  available:         {type: boolean}
                  interpreterPath:   {type: string}
                  interpreterExists: {type: boolean}
                  nlplVersion:       {type: string, nullable: true}
                  pythonVersion:     {type: string, nullable: true}
                  portRange:
                    type: object
                    properties:
                      start: {type: integer}
                      end:   {type: integer}
                  installInstructions: {type: string, nullable: true}

  /sites/{id}/nlpl/start:
    post:
      summary: Start (or restart) the dynamic process for a site
      tags: [NLPL]
      security: [{sessionCookie: []}, {bearerToken: []}]
      parameters:
        - {name: id, in: path, required: true, schema: {type: integer}}
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                entryFile: {type: string, default: server.nlpl, description: Entry file relative to site root}
      responses:
        '200':
          description: Process started — returns allocated port
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:    {type: string, enum: [running]}
                  port:      {type: integer}
                  runtime:   {type: string, enum: [nlpl, node, python]}
                  entryFile: {type: string}
        '400': {description: No active deployment or entry file not found}
        '404': {description: Site not found}

  /sites/{id}/nlpl/stop:
    post:
      summary: Stop the dynamic process for a site
      tags: [NLPL]
      security: [{sessionCookie: []}, {bearerToken: []}]
      parameters:
        - {name: id, in: path, required: true, schema: {type: integer}}
      responses:
        '200': {description: Process stopped}

  /sites/{id}/nlpl/status:
    get:
      summary: Process status, port, PID, and restart count
      tags: [NLPL]
      parameters:
        - {name: id, in: path, required: true, schema: {type: integer}}
      responses:
        '200':
          description: Process status
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:       {type: string, enum: [running, starting, crashed, stopped]}
                  port:         {type: integer, nullable: true}
                  pid:          {type: integer, nullable: true}
                  runtime:      {type: string, nullable: true}
                  restartCount: {type: integer}
                  startedAt:    {type: string, format: date-time, nullable: true}
                  lastCrashAt:  {type: string, format: date-time, nullable: true}

  /sites/{id}/nlpl/logs:
    get:
      summary: Recent process stdout/stderr (ring buffer tail)
      tags: [NLPL]
      parameters:
        - {name: id, in: path, required: true, schema: {type: integer}}
        - {name: tail, in: query, schema: {type: integer, default: 100, maximum: 500}}
      responses:
        '200':
          description: Log lines
          content:
            application/json:
              schema:
                type: object
                properties:
                  lines: {type: array, items: {type: string}}
                  count: {type: integer}

  # ── Admin: processes ─────────────────────────────────────────────────────────

  /admin/processes:
    get:
      summary: All running dynamic site processes (admin only)
      tags: [Admin]
      security: [{sessionCookie: []}]
      responses:
        '200':
          description: Process list
          content:
            application/json:
              schema:
                type: object
                properties:
                  processes: {type: array}
                  total: {type: integer}

  # ── Builds ───────────────────────────────────────────────────────────────────

  /sites/{id}/builds/{buildId}:
    get:
      summary: Get build details and log
      tags: [Builds]
      security: [{sessionCookie: []}, {bearerToken: []}]
      parameters:
        - {name: id,      in: path, required: true, schema: {type: integer}}
        - {name: buildId, in: path, required: true, schema: {type: integer}}
      responses:
        '200': {description: Build details including full log output}
    delete:
      summary: Cancel a queued build
      tags: [Builds]
      security: [{sessionCookie: []}, {bearerToken: []}]
      parameters:
        - {name: id,      in: path, required: true, schema: {type: integer}}
        - {name: buildId, in: path, required: true, schema: {type: integer}}
      responses:
        '200': {description: Build cancelled}
        '400': {description: Build cannot be cancelled (already running or finished)}

  # ── Redirects and custom headers ─────────────────────────────────────────────

  /sites/{id}/redirects/{ruleId}:
    delete:
      summary: Delete a redirect rule
      tags: [Sites]
      security: [{sessionCookie: []}, {bearerToken: []}]
      parameters:
        - {name: id,     in: path, required: true, schema: {type: integer}}
        - {name: ruleId, in: path, required: true, schema: {type: integer}}
      responses:
        '204': {description: Rule deleted}

  /sites/{id}/headers/{headerId}:
    delete:
      summary: Delete a custom response header
      tags: [Sites]
      security: [{sessionCookie: []}, {bearerToken: []}]
      parameters:
        - {name: id,       in: path, required: true, schema: {type: integer}}
        - {name: headerId, in: path, required: true, schema: {type: integer}}
      responses:
        '204': {description: Header deleted}

  # ── Forms ────────────────────────────────────────────────────────────────────

  /sites/{id}/forms/{formName}/export:
    get:
      summary: Export form submissions as CSV
      tags: [Forms]
      security: [{sessionCookie: []}, {bearerToken: []}]
      parameters:
        - {name: id,       in: path, required: true, schema: {type: integer}}
        - {name: formName, in: path, required: true, schema: {type: string}}
      responses:
        '200':
          description: CSV download
          content:
            text/csv:
              schema: {type: string}

  /sites/{id}/forms/{submissionId}:
    patch:
      summary: Mark a form submission as read/unread or add a note
      tags: [Forms]
      security: [{sessionCookie: []}, {bearerToken: []}]
      parameters:
        - {name: id,           in: path, required: true, schema: {type: integer}}
        - {name: submissionId, in: path, required: true, schema: {type: integer}}
      responses:
        '200': {description: Submission updated}
    delete:
      summary: Delete a form submission
      tags: [Forms]
      security: [{sessionCookie: []}, {bearerToken: []}]
      parameters:
        - {name: id,           in: path, required: true, schema: {type: integer}}
        - {name: submissionId, in: path, required: true, schema: {type: integer}}
      responses:
        '204': {description: Submission deleted}

  # ── Invitations ──────────────────────────────────────────────────────────────

  /invitations/{token}:
    get:
      summary: Look up an invitation by token (for accept page)
      tags: [Access]
      parameters:
        - {name: token, in: path, required: true, schema: {type: string}}
      responses:
        '200': {description: Invitation details including site name and inviter}
        '404': {description: Invitation not found or expired}

  /sites/{id}/invitations/{inviteId}:
    delete:
      summary: Revoke a pending invitation
      tags: [Access]
      security: [{sessionCookie: []}, {bearerToken: []}]
      parameters:
        - {name: id,       in: path, required: true, schema: {type: integer}}
        - {name: inviteId, in: path, required: true, schema: {type: integer}}
      responses:
        '204': {description: Invitation revoked}

  # ── Analytics extras ─────────────────────────────────────────────────────────

  /sites/{id}/analytics/referrers:
    get:
      summary: Top referrers for a site over a time period
      tags: [Analytics]
      security: [{sessionCookie: []}, {bearerToken: []}]
      parameters:
        - {name: id,     in: path,  required: true, schema: {type: integer}}
        - {name: period, in: query, schema: {type: string, enum: [24h, 7d, 30d], default: 7d}}
      responses:
        '200': {description: Referrer list with hit counts}

  /stats/hourly:
    get:
      summary: Network-wide hourly activity (last 24h, for dashboard chart)
      tags: [Analytics]
      responses:
        '200': {description: Array of hourly buckets with deployment and event counts}

  # ── Capacity ─────────────────────────────────────────────────────────────────

  /nodes/{id}/update-capacity:
    post:
      summary: Update a node's reported storage and bandwidth capacity (node-to-node)
      tags: [Nodes]
      security: [{bearerToken: []}]
      parameters:
        - {name: id, in: path, required: true, schema: {type: integer}}
      responses:
        '200': {description: Capacity updated}

  # ── Env vars ─────────────────────────────────────────────────────────────────

  /sites/{id}/env/{key}:
    delete:
      summary: Delete a single env var by key
      tags: [Sites]
      security: [{sessionCookie: []}, {bearerToken: []}]
      parameters:
        - {name: id,  in: path, required: true, schema: {type: integer}}
        - {name: key, in: path, required: true, schema: {type: string}}
      responses:
        '204': {description: Env var deleted}

  # ── Transfer ─────────────────────────────────────────────────────────────────

  /sites/{id}/transfer/accept:
    post:
      summary: Accept a site transfer (new owner only)
      tags: [Sites]
      security: [{sessionCookie: []}, {bearerToken: []}]
      parameters:
        - {name: id, in: path, required: true, schema: {type: integer}}
      responses:
        '200': {description: Transfer accepted — caller is now the site owner}

  # ── Webhooks ─────────────────────────────────────────────────────────────────

  /webhooks/config:
    get:
      summary: Node-level webhook configuration (operator endpoint URLs)
      tags: [Webhooks]
      security: [{sessionCookie: []}]
      responses:
        '200': {description: Webhook configuration and recent delivery stats}

  /webhooks/test:
    post:
      summary: Send a test webhook delivery to all configured endpoints
      tags: [Webhooks]
      security: [{sessionCookie: []}]
      responses:
        '200': {description: Test delivery sent}

  # ── TLS / ACME ───────────────────────────────────────────────────────────────

  /.well-known/acme-challenge/{token}:
    get:
      summary: Serve HTTP-01 ACME challenge response (Let's Encrypt)
      tags: [TLS]
      parameters:
        - {name: token, in: path, required: true, schema: {type: string}}
      responses:
        '200': {description: keyAuthorization string for the challenge token}
        '404': {description: No active challenge for this token}

  # ── Storage (internal) ───────────────────────────────────────────────────────

  /storage/public-objects/{filePath*}:
    get:
      summary: Serve a public object by path (internal — prefer site-domain routing)
      tags: [Storage]
      parameters:
        - {name: filePath, in: path, required: true, schema: {type: string}}
      responses:
        '200': {description: File content}
        '404': {description: File not found}

  /storage/objects/{path*}:
    get:
      summary: Serve a private object by path (requires authentication)
      tags: [Storage]
      security: [{sessionCookie: []}, {bearerToken: []}]
      parameters:
        - {name: path, in: path, required: true, schema: {type: string}}
      responses:
        '200': {description: File content}

  /sites/serve/{domain}/{filePath*}:
    get:
      summary: Serve a site file by domain and path (used for previews)
      tags: [Deploy]
      parameters:
        - {name: domain,   in: path, required: true, schema: {type: string}}
        - {name: filePath, in: path, required: true, schema: {type: string}}
      responses:
        '200': {description: File content with correct Content-Type}
        '404': {description: File not found}


  /tokens/{id}:
    delete:
      summary: Revoke an API token
      tags: [Auth]
      security: [{sessionCookie: []}, {bearerToken: []}]
      parameters:
        - {name: id, in: path, required: true, schema: {type: integer}}
      responses:
        '204': {description: Token revoked}
        '404': {description: Token not found}

  /auth/2fa/status:
    get:
      summary: Check whether 2FA is enabled for the current user
      tags: [Auth]
      security: [{sessionCookie: []}]
      responses:
        '200':
          description: 2FA status
          content:
            application/json:
              schema:
                type: object
                properties:
                  enabled:   {type: boolean}
                  enabledAt: {type: string, format: date-time, nullable: true}

  /auth/2fa/disable:
    post:
      summary: Disable 2FA (requires current TOTP code or backup code)
      tags: [Auth]
      security: [{sessionCookie: []}]
      requestBody:
        required: true
        content:
          application/json:
            schema: {type: object, required: [code], properties: {code: {type: string, minLength: 6, maxLength: 10}}}
      responses:
        '200': {description: 2FA disabled}

  /auth/2fa/backup:
    post:
      summary: Regenerate backup codes (invalidates existing codes)
      tags: [Auth]
      security: [{sessionCookie: []}]
      requestBody:
        required: true
        content:
          application/json:
            schema: {type: object, required: [code], properties: {code: {type: string, minLength: 6, maxLength: 6}}}
      responses:
        '200':
          description: New backup codes shown once only
          content:
            application/json:
              schema:
                type: object
                properties:
                  backupCodes: {type: array, items: {type: string}}

  /auth/2fa/complete:
    post:
      summary: Complete a 2FA login challenge — upgrades pending session to authenticated
      tags: [Auth]
      requestBody:
        required: true
        content:
          application/json:
            schema: {type: object, required: [code], properties: {code: {type: string, minLength: 6, maxLength: 10}}}
      responses:
        '200':
          description: Authentication complete
          content:
            application/json:
              schema:
                type: object
                properties:
                  authenticated: {type: boolean}
                  method: {type: string, enum: [totp, backup]}
        '400': {description: Invalid code or account locked}

  /nlpl/runtime-info:
    get:
      summary: NLPL interpreter availability, version, and port range
      tags: [NLPL]
      responses:
        '200':
          description: Runtime info
          content:
            application/json:
              schema:
                type: object
                properties:
                  available:         {type: boolean}
                  interpreterPath:   {type: string}
                  nlplVersion:       {type: string, nullable: true}
                  pythonVersion:     {type: string, nullable: true}
                  portRange:         {type: object, properties: {start: {type: integer}, end: {type: integer}}}
                  installInstructions: {type: string, nullable: true}

  /sites/{id}/nlpl/start:
    post:
      summary: Start or restart the dynamic process for a site
      tags: [NLPL]
      security: [{sessionCookie: []}, {bearerToken: []}]
      parameters:
        - {name: id, in: path, required: true, schema: {type: integer}}
      requestBody:
        content:
          application/json:
            schema: {type: object, properties: {entryFile: {type: string, default: server.nlpl}}}
      responses:
        '200': {description: Process started — returns allocated port and runtime info}
        '400': {description: No active deployment or entry file not found}

  /sites/{id}/nlpl/stop:
    post:
      summary: Stop the dynamic process for a site
      tags: [NLPL]
      security: [{sessionCookie: []}, {bearerToken: []}]
      parameters:
        - {name: id, in: path, required: true, schema: {type: integer}}
      responses:
        '200': {description: Process stopped}

  /sites/{id}/nlpl/status:
    get:
      summary: Process status, port, PID, and restart count
      tags: [NLPL]
      parameters:
        - {name: id, in: path, required: true, schema: {type: integer}}
      responses:
        '200':
          description: Process status
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:       {type: string, enum: [running, starting, crashed, stopped]}
                  port:         {type: integer, nullable: true}
                  pid:          {type: integer, nullable: true}
                  restartCount: {type: integer}
                  startedAt:    {type: string, format: date-time, nullable: true}
                  lastCrashAt:  {type: string, format: date-time, nullable: true}

  /sites/{id}/nlpl/logs:
    get:
      summary: Recent process stdout/stderr tail (ring buffer)
      tags: [NLPL]
      parameters:
        - {name: id,   in: path,  required: true,  schema: {type: integer}}
        - {name: tail, in: query, required: false, schema: {type: integer, default: 100, maximum: 500}}
      responses:
        '200':
          description: Log lines array
          content:
            application/json:
              schema: {type: object, properties: {lines: {type: array, items: {type: string}}, count: {type: integer}}}

  /admin/processes:
    get:
      summary: All running dynamic site processes (admin only)
      tags: [Admin]
      security: [{sessionCookie: []}]
      responses:
        '200': {description: Process list with status, PID, port, and restart counts}

  /sites/{id}/builds/{buildId}:
    get:
      summary: Get build details and log output
      tags: [Builds]
      security: [{sessionCookie: []}, {bearerToken: []}]
      parameters:
        - {name: id,      in: path, required: true, schema: {type: integer}}
        - {name: buildId, in: path, required: true, schema: {type: integer}}
      responses:
        '200': {description: Build details including full log}
    delete:
      summary: Cancel a queued build
      tags: [Builds]
      security: [{sessionCookie: []}, {bearerToken: []}]
      parameters:
        - {name: id,      in: path, required: true, schema: {type: integer}}
        - {name: buildId, in: path, required: true, schema: {type: integer}}
      responses:
        '200': {description: Build cancelled}
        '400': {description: Build cannot be cancelled}

  /sites/{id}/redirects/{ruleId}:
    delete:
      summary: Delete a redirect rule
      tags: [Sites]
      security: [{sessionCookie: []}, {bearerToken: []}]
      parameters:
        - {name: id, in: path, required: true, schema: {type: integer}}
        - {name: ruleId, in: path, required: true, schema: {type: integer}}
      responses:
        '204': {description: Rule deleted}

  /sites/{id}/headers/{headerId}:
    delete:
      summary: Delete a custom response header rule
      tags: [Sites]
      security: [{sessionCookie: []}, {bearerToken: []}]
      parameters:
        - {name: id,       in: path, required: true, schema: {type: integer}}
        - {name: headerId, in: path, required: true, schema: {type: integer}}
      responses:
        '204': {description: Header deleted}

  /sites/{id}/forms/{formName}/export:
    get:
      summary: Export form submissions as CSV
      tags: [Forms]
      security: [{sessionCookie: []}, {bearerToken: []}]
      parameters:
        - {name: id,       in: path, required: true, schema: {type: integer}}
        - {name: formName, in: path, required: true, schema: {type: string}}
      responses:
        '200':
          description: CSV file download
          content:
            text/csv: {schema: {type: string}}

  /sites/{id}/forms/{submissionId}:
    patch:
      summary: Mark a form submission as read or add a note
      tags: [Forms]
      security: [{sessionCookie: []}, {bearerToken: []}]
      parameters:
        - {name: id,           in: path, required: true, schema: {type: integer}}
        - {name: submissionId, in: path, required: true, schema: {type: integer}}
      responses:
        '200': {description: Submission updated}
    delete:
      summary: Delete a form submission
      tags: [Forms]
      security: [{sessionCookie: []}, {bearerToken: []}]
      parameters:
        - {name: id,           in: path, required: true, schema: {type: integer}}
        - {name: submissionId, in: path, required: true, schema: {type: integer}}
      responses:
        '204': {description: Submission deleted}

  /invitations/{token}:
    get:
      summary: Look up an invitation by its accept token
      tags: [Access]
      parameters:
        - {name: token, in: path, required: true, schema: {type: string}}
      responses:
        '200': {description: Invitation details including site name and inviter}
        '404': {description: Invitation not found or expired}

  /sites/{id}/invitations/{inviteId}:
    delete:
      summary: Revoke a pending invitation
      tags: [Access]
      security: [{sessionCookie: []}, {bearerToken: []}]
      parameters:
        - {name: id,       in: path, required: true, schema: {type: integer}}
        - {name: inviteId, in: path, required: true, schema: {type: integer}}
      responses:
        '204': {description: Invitation revoked}

  /sites/{id}/analytics/referrers:
    get:
      summary: Top referrers for a site
      tags: [Analytics]
      security: [{sessionCookie: []}, {bearerToken: []}]
      parameters:
        - {name: id,     in: path,  required: true,  schema: {type: integer}}
        - {name: period, in: query, required: false, schema: {type: string, enum: [24h, 7d, 30d], default: 7d}}
      responses:
        '200': {description: Referrer list with hit counts}

  /stats/hourly:
    get:
      summary: Network-wide hourly activity for dashboard chart
      tags: [Analytics]
      responses:
        '200': {description: Array of hourly buckets with deployment and event counts}

  /nodes/{id}/update-capacity:
    post:
      summary: Update a node's reported storage and bandwidth capacity
      tags: [Nodes]
      security: [{bearerToken: []}]
      parameters:
        - {name: id, in: path, required: true, schema: {type: integer}}
      responses:
        '200': {description: Capacity updated}

  /sites/{id}/env/{key}:
    delete:
      summary: Delete a single env var by key
      tags: [Sites]
      security: [{sessionCookie: []}, {bearerToken: []}]
      parameters:
        - {name: id,  in: path, required: true, schema: {type: integer}}
        - {name: key, in: path, required: true, schema: {type: string}}
      responses:
        '204': {description: Env var deleted}

  /sites/{id}/transfer/accept:
    post:
      summary: Accept a pending site transfer (new owner only)
      tags: [Sites]
      security: [{sessionCookie: []}, {bearerToken: []}]
      parameters:
        - {name: id, in: path, required: true, schema: {type: integer}}
      responses:
        '200': {description: Transfer accepted — caller is now owner}

  /webhooks/config:
    get:
      summary: Node-level webhook endpoint configuration
      tags: [Webhooks]
      security: [{sessionCookie: []}]
      responses:
        '200': {description: Configured webhook URLs and recent delivery stats}

  /webhooks/test:
    post:
      summary: Send a test event to all configured webhook endpoints
      tags: [Webhooks]
      security: [{sessionCookie: []}]
      responses:
        '200': {description: Test delivery dispatched}

  /.well-known/acme-challenge/{token}:
    get:
      summary: Serve HTTP-01 ACME challenge response (Let's Encrypt verification)
      tags: [TLS]
      parameters:
        - {name: token, in: path, required: true, schema: {type: string}}
      responses:
        '200': {description: keyAuthorization string}
        '404': {description: No active challenge for this token}

  /storage/public-objects/{filePath*}:
    get:
      summary: Serve a public object by path
      tags: [Storage]
      parameters:
        - {name: filePath, in: path, required: true, schema: {type: string}}
      responses:
        '200': {description: File content with correct Content-Type}
        '404': {description: Not found}

  /storage/objects/{path*}:
    get:
      summary: Serve a private object by path (authenticated)
      tags: [Storage]
      security: [{sessionCookie: []}, {bearerToken: []}]
      parameters:
        - {name: path, in: path, required: true, schema: {type: string}}
      responses:
        '200': {description: File content}

  /sites/serve/{domain}/{filePath*}:
    get:
      summary: Serve a site file by domain and path (preview use)
      tags: [Deploy]
      parameters:
        - {name: domain,   in: path, required: true, schema: {type: string}}
        - {name: filePath, in: path, required: true, schema: {type: string}}
      responses:
        '200': {description: File content}
        '404': {description: File not found}

  # ── Federation blocklist (defederation) ─────────────────────────────────────

  /federation/blocks:
    get:
      summary: List blocked federation nodes (admin only)
      tags: [Federation]
      security: [{sessionCookie: []}]
      responses:
        '200':
          description: Blocklist with total count
          content:
            application/json:
              schema:
                type: object
                properties:
                  blocks:
                    type: array
                    items:
                      type: object
                      properties:
                        id:          {type: integer}
                        nodeDomain:  {type: string}
                        reason:      {type: string, nullable: true}
                        blockedBy:   {type: string, nullable: true}
                        createdAt:   {type: string, format: date-time}
                  total: {type: integer}
        '403': {description: Admin access required}
    post:
      summary: Block a federation node (admin only)
      tags: [Federation]
      security: [{sessionCookie: []}]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [nodeDomain]
              properties:
                nodeDomain: {type: string, description: Domain of the node to block}
                reason:     {type: string, maxLength: 500}
      responses:
        '201':
          description: Node blocked — also marks the peer as inactive in nodes table
        '409': {description: Node is already blocked}
        '403': {description: Admin access required}

  /federation/blocks/{domain}:
    delete:
      summary: Unblock a federation node (admin only)
      tags: [Federation]
      security: [{sessionCookie: []}]
      parameters:
        - {name: domain, in: path, required: true, schema: {type: string}}
      responses:
        '200': {description: Node unblocked}
        '404': {description: No block found for this domain}
        '403': {description: Admin access required}

  /federation/blocks/check:
    get:
      summary: Check whether a domain is on this node's blocklist (public)
      description: |
        Peers can call this before initiating a handshake to avoid a wasted
        round-trip. Returns 200 with blocked=true/false rather than 403 so
        callers can handle it gracefully without error logic.
      tags: [Federation]
      parameters:
        - {name: domain, in: query, required: true, schema: {type: string}}
      responses:
        '200':
          description: Block status
          content:
            application/json:
              schema:
                type: object
                properties:
                  domain:  {type: string}
                  blocked: {type: boolean}
        '400': {description: domain query parameter missing}

  # ── Email verification ────────────────────────────────────────────────────────

  /api/auth/verify-email:
    get:
      summary: Consume an email verification token
      description: |
        Called via the link in the verification email.
        On success, sets emailVerified=1 on the user and redirects to /dashboard?email_verified=1.
        On failure, redirects to /?error=invalid_or_expired_token.
      tags: [Auth]
      parameters:
        - {name: token, in: query, required: true, schema: {type: string}}
      responses:
        '302': {description: Redirect on success or failure}

  /api/auth/resend-verification:
    post:
      summary: Re-send email verification link
      description: Rate-limited. Requires authentication. No-op if already verified.
      tags: [Auth]
      security: [{cookieAuth: []}]
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:      {type: boolean}
                  message: {type: string}
        '401': {description: Not authenticated}

  # ── Abuse reports ─────────────────────────────────────────────────────────────

  /api/abuse/report:
    post:
      summary: Submit an abuse report for a site
      description: |
        Public endpoint — no authentication required.
        Rate-limited to prevent spam.
      tags: [Abuse]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [siteDomain, reason]
              properties:
                siteDomain:    {type: string, description: Primary domain of the site being reported}
                reason:
                  type: string
                  enum: [spam, phishing, malware, csam, copyright, harassment, illegal_content, other]
                description:   {type: string, maxLength: 2000}
                evidenceUrl:   {type: string, format: uri}
                reporterEmail: {type: string, format: email}
      responses:
        '201':
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:      {type: boolean}
                  message: {type: string}
        '404': {description: Site not found}

  /api/abuse/reports:
    get:
      summary: List abuse reports (admin only)
      tags: [Abuse, Admin]
      security: [{cookieAuth: []}]
      parameters:
        - {name: status, in: query, schema: {type: string, enum: [pending, under_review, resolved_removed, resolved_no_action, escalated]}}
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: {$ref: '#/components/schemas/AbuseReport'}

  /api/abuse/reports/{id}:
    patch:
      summary: Update abuse report status (admin only)
      tags: [Abuse, Admin]
      security: [{cookieAuth: []}]
      parameters:
        - {name: id, in: path, required: true, schema: {type: integer}}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [status]
              properties:
                status:
                  type: string
                  enum: [pending, under_review, resolved_removed, resolved_no_action, escalated]
                reviewNotes: {type: string, maxLength: 2000}
      responses:
        '200': {description: Updated report}
        '404': {description: Report not found}

  /api/abuse/reports/{id}/takedown:
    post:
      summary: Take down a site and resolve report (admin only)
      description: Suspends the site and marks report as resolved_removed.
      tags: [Abuse, Admin]
      security: [{cookieAuth: []}]
      parameters:
        - {name: id, in: path, required: true, schema: {type: integer}}
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:      {type: boolean}
                  message: {type: string}

  # ── IP bans ───────────────────────────────────────────────────────────────────

  /api/admin/ip-bans:
    get:
      summary: List active IP bans (admin only)
      tags: [Admin]
      security: [{cookieAuth: []}]
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: {type: array, items: {$ref: '#/components/schemas/IpBan'}}
    post:
      summary: Create an IP ban (admin only)
      tags: [Admin]
      security: [{cookieAuth: []}]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [ipAddress]
              properties:
                ipAddress: {type: string, description: IPv4 address}
                cidrRange: {type: string, description: CIDR range e.g. 1.2.3.0/24}
                reason:    {type: string, maxLength: 500}
                scope:     {type: string, enum: [api, sites, all], default: all}
                expiresAt: {type: string, format: date-time, description: Null for permanent ban}
      responses:
        '201': {description: Ban created}

  /api/admin/ip-bans/{id}:
    delete:
      summary: Remove an IP ban (admin only)
      tags: [Admin]
      security: [{cookieAuth: []}]
      parameters:
        - {name: id, in: path, required: true, schema: {type: integer}}
      responses:
        '204': {description: Ban removed}
        '404': {description: Ban not found}

  # ── Node trust ────────────────────────────────────────────────────────────────

  /api/admin/node-trust:
    get:
      summary: List federation node trust scores (admin only)
      tags: [Admin, Federation]
      security: [{cookieAuth: []}]
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: {type: array, items: {$ref: '#/components/schemas/NodeTrust'}}


    # ── New schemas ───────────────────────────────────────────────────────────

    AbuseReport:
      type: object
      properties:
        id:            {type: integer}
        siteId:        {type: integer}
        siteDomain:    {type: string}
        reporterEmail: {type: string}
        reason:        {type: string}
        description:   {type: string}
        status:        {type: string, enum: [pending, under_review, resolved_removed, resolved_no_action, escalated]}
        reviewedBy:    {type: string}
        reviewedAt:    {type: string, format: date-time}
        reviewNotes:   {type: string}
        actionTaken:   {type: integer}
        createdAt:     {type: string, format: date-time}

    IpBan:
      type: object
      properties:
        id:        {type: integer}
        ipAddress: {type: string}
        cidrRange: {type: string, nullable: true}
        reason:    {type: string, nullable: true}
        scope:     {type: string, enum: [api, sites, all]}
        bannedBy:  {type: string, nullable: true}
        expiresAt: {type: string, format: date-time, nullable: true}
        createdAt: {type: string, format: date-time}

    NodeTrust:
      type: object
      properties:
        id:               {type: integer}
        nodeDomain:       {type: string}
        trustLevel:       {type: string, enum: [unverified, verified, trusted, blocked]}
        successfulPings:  {type: integer}
        failedPings:      {type: integer}
        uptimePercent:    {type: integer}
        firstSeenAt:      {type: string, format: date-time}
        lastPingAt:       {type: string, format: date-time, nullable: true}
        manuallyReviewed: {type: integer}
        updatedAt:        {type: string, format: date-time}


  # ── Email verification ────────────────────────────────────────────────────────

  /api/auth/verify-email:
    get:
      summary: Consume an email verification token
      description: Redirects to /dashboard?email_verified=1 on success, /?error=invalid_or_expired_token on failure.
      tags: [Auth]
      parameters:
        - {name: token, in: query, required: true, schema: {type: string}}
      responses:
        '302': {description: Redirect}

  /api/auth/resend-verification:
    post:
      summary: Re-send email verification link (authenticated)
      tags: [Auth]
      security: [{cookieAuth: []}]
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok: {type: boolean}
                  message: {type: string}

  # ── Abuse reports ─────────────────────────────────────────────────────────────

  /api/abuse/report:
    post:
      summary: Submit an abuse report (public, rate-limited)
      tags: [Abuse]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AbuseReportBody'
      responses:
        '201': {description: Report received}
        '404': {description: Site not found}

  /api/abuse/reports:
    get:
      summary: List abuse reports (admin only)
      tags: [Abuse, Admin]
      security: [{cookieAuth: []}]
      parameters:
        - {name: status, in: query, schema: {type: string}}
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: {type: array, items: {$ref: '#/components/schemas/AbuseReport'}}

  /api/abuse/reports/{id}:
    patch:
      summary: Update abuse report status (admin only)
      tags: [Abuse, Admin]
      security: [{cookieAuth: []}]
      parameters:
        - {name: id, in: path, required: true, schema: {type: integer}}
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                status: {type: string, enum: [pending, under_review, resolved_removed, resolved_no_action, escalated]}
                reviewNotes: {type: string}
      responses:
        '200': {description: Updated}

  /api/abuse/reports/{id}/takedown:
    post:
      summary: Suspend site and resolve report (admin only)
      tags: [Abuse, Admin]
      security: [{cookieAuth: []}]
      parameters:
        - {name: id, in: path, required: true, schema: {type: integer}}
      responses:
        '200': {description: Site suspended}

  # ── IP bans ───────────────────────────────────────────────────────────────────

  /api/admin/ip-bans:
    get:
      summary: List active IP bans (admin only)
      tags: [Admin]
      security: [{cookieAuth: []}]
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: {type: array, items: {$ref: '#/components/schemas/IpBan'}}
    post:
      summary: Create an IP ban (admin only)
      tags: [Admin]
      security: [{cookieAuth: []}]
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [ipAddress]
              properties:
                ipAddress: {type: string}
                cidrRange: {type: string}
                reason: {type: string}
                scope: {type: string, enum: [api, sites, all]}
                expiresAt: {type: string, format: date-time}
      responses:
        '201': {description: Ban created}

  /api/admin/ip-bans/{id}:
    delete:
      summary: Remove an IP ban (admin only)
      tags: [Admin]
      security: [{cookieAuth: []}]
      parameters:
        - {name: id, in: path, required: true, schema: {type: integer}}
      responses:
        '204': {description: Removed}

    AbuseReportBody:
      type: object
      required: [siteDomain, reason]
      properties:
        siteDomain: {type: string}
        reason: {type: string, enum: [spam, phishing, malware, csam, copyright, harassment, illegal_content, other]}
        description: {type: string, maxLength: 2000}
        evidenceUrl: {type: string, format: uri}
        reporterEmail: {type: string, format: email}

    AbuseReport:
      type: object
      properties:
        id: {type: integer}
        siteId: {type: integer}
        siteDomain: {type: string}
        reason: {type: string}
        status: {type: string, enum: [pending, under_review, resolved_removed, resolved_no_action, escalated]}
        reviewNotes: {type: string, nullable: true}
        actionTaken: {type: integer}
        createdAt: {type: string, format: date-time}

    IpBan:
      type: object
      properties:
        id: {type: integer}
        ipAddress: {type: string}
        cidrRange: {type: string, nullable: true}
        reason: {type: string, nullable: true}
        scope: {type: string, enum: [api, sites, all]}
        expiresAt: {type: string, format: date-time, nullable: true}
        createdAt: {type: string, format: date-time}

    NodeTrust:
      type: object
      properties:
        id: {type: integer}
        nodeDomain: {type: string}
        trustLevel: {type: string, enum: [unverified, verified, trusted, blocked]}
        successfulPings: {type: integer}
        failedPings: {type: integer}
        uptimePercent: {type: integer}
        firstSeenAt: {type: string, format: date-time}
        lastPingAt: {type: string, format: date-time, nullable: true}
        updatedAt: {type: string, format: date-time}

  /api/admin/node-trust:
    get:
      summary: List federation node trust scores (admin only)
      tags: [Admin, Federation]
      security: [{cookieAuth: []}]
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: {type: array, items: {$ref: '#/components/schemas/NodeTrust'}}

  /api/admin/node-trust/{domain}:
    patch:
      summary: Manually set a node's trust level (admin only)
      tags: [Admin, Federation]
      security: [{cookieAuth: []}]
      parameters:
        - {name: domain, in: path, required: true, schema: {type: string}}
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                trustLevel: {type: string, enum: [unverified, verified, trusted, blocked]}
                reviewNotes: {type: string}
      responses:
        '200': {description: Updated trust record}
        '404': {description: Node trust record not found}

  /api/admin/users/{id}/storage-cap:
    patch:
      summary: Set per-user storage cap (admin only)
      description: |
        Sets a per-user storage cap in MB. Use 0 to remove the cap (user is unlimited,
        only node-level capacity applies). This is an operator administration tool —
        NOT a pricing tier. NexusHosting is always free.
      tags: [Admin]
      security: [{cookieAuth: []}]
      parameters:
        - {name: id, in: path, required: true, schema: {type: string}}
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [storageCapMb]
              properties:
                storageCapMb: {type: integer, minimum: 0, description: "0 = no cap"}
      responses:
        '200': {description: Cap updated}
        '404': {description: User not found}

  /api/admin/users/{id}/suspend:
    patch:
      summary: Suspend or reinstate a user (admin only)
      tags: [Admin]
      security: [{cookieAuth: []}]
      parameters:
        - {name: id, in: path, required: true, schema: {type: string}}
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [suspended]
              properties:
                suspended: {type: boolean}
      responses:
        '200': {description: User suspended or reinstated}
        '404': {description: User not found}