node-api.openapi.yaml

openapi: 3.0.3
info:
  title: Erebrus Node API v2
  version: 2.0.0
  description: |
    REST API served by every Erebrus VPN node. The only intended caller is the
    Erebrus gateway (and node-local tooling); end users never talk to a node
    directly. All /api/v2 routes require a gateway-issued, node-scoped PASETO
    bearer token except /api/v2/status and /metrics. Drop routes additionally
    require X-Erebrus-Node-Key and an exact-purpose token.

    When Drop is enabled, CID reads use the authenticated Erebrus gateway-to-node
    API. Kubo admin RPC `5001` and the raw Kubo gateway `8080` remain private.

    FROZEN (v2.0): additive changes only. See ../../../erebrus-gateway/docs/v2/ws-protocol.md
    for the WebSocket control plane.
servers:
  - url: http://{host}:9080
    variables:
      host:
        default: localhost
security:
  - paseto: []
paths:
  /api/v2/status:
    get:
      summary: Public node status (unauthenticated)
      security: []
      responses:
        "200":
          content:
            application/json:
              schema:
                type: object
                properties:
                  version: { type: string, example: "2.0.0" }
                  region: { type: string, example: "SG" }
                  zone: { type: string, example: "us-east", description: "Optional placement within region (e.g. east, west)" }
                  status: { type: string, enum: [online, draining] }
                  peer_id: { type: string }
                  did: { type: string, example: "did:erebrus:12D3KooW..." }
                  capabilities:
                    $ref: "#/components/schemas/Capabilities"
                  protocols:
                    type: array
                    items: { type: string, enum: [wireguard, vless_reality, hysteria2] }
                  readiness:
                    $ref: "#/components/schemas/Readiness"
          description: Node identity and advertised protocols. No secrets, no peer data.
  /api/v2/stats:
    get:
      summary: Coarse public stats for the local dashboard (unauthenticated)
      security: []
      responses:
        "200":
          content:
            application/json:
              schema:
                type: object
                properties:
                  status: { type: string, enum: [online, draining] }
                  version: { type: string }
                  region: { type: string }
                  zone: { type: string }
                  protocols: { type: array, items: { type: string } }
                  total_peers: { type: integer, description: Provisioned peers in the store }
                  connected_peers: { type: integer, description: WireGuard handshake in the last 3 minutes }
                  rx_bytes: { type: integer, format: int64 }
                  tx_bytes: { type: integer, format: int64 }
                  uptime_sec: { type: integer, format: int64 }
          description: Aggregates only — never per-client rows.
  /healthz:
    get:
      summary: Liveness probe (unauthenticated)
      security: []
      responses:
        "200": { description: '{ "status": "ok" }' }
  /metrics:
    get:
      summary: Prometheus metrics (unauthenticated, bind/firewall to taste)
      security: []
      responses:
        "200": { description: Prometheus text exposition format }
  /api/v2/drop/status:
    get:
      summary: Drop health and repository capacity
      description: Requires a token with exact purpose `drop_status`.
      security:
        - dropPurpose: []
          nodeKey: []
      responses:
        "200":
          description: Current Drop state
          content:
            application/json:
              schema: { $ref: "#/components/schemas/DropStatus" }
        "401": { $ref: "#/components/responses/DropUnauthorized" }
        "503": { description: Drop is unavailable }
  /api/v2/drop/uploads/{upload_id}:
    parameters:
      - { name: upload_id, in: path, required: true, schema: { type: string }, description: Gateway-generated idempotency and audit identifier }
    put:
      summary: Stream an object to Kubo and recursively pin it
      description: |
        Requires exact purpose `drop_upload`. The body is streamed and limited
        while being read; the node does not buffer the complete object. The v1
        per-object maximum is 1,000,000,000 bytes.
      security:
        - dropPurpose: []
          nodeKey: []
      parameters:
        - { name: X-Erebrus-Declared-Size, in: header, required: true, schema: { type: integer, format: int64, minimum: 0, maximum: 1000000000 } }
        - { name: X-Erebrus-SHA256, in: header, required: false, schema: { type: string, pattern: "^[0-9A-Fa-f]{64}$" }, description: Optional expected SHA-256 digest }
      requestBody:
        required: true
        content:
          application/octet-stream:
            schema: { type: string, format: binary }
      responses:
        "200":
          description: Object added and pinned
          content:
            application/json:
              schema:
                type: object
                required: [cid, size_bytes, pinned]
                properties:
                  cid: { $ref: "#/components/schemas/CID" }
                  size_bytes: { type: integer, format: int64 }
                  pinned: { type: boolean, enum: [true] }
        "401": { $ref: "#/components/responses/DropUnauthorized" }
        "413": { description: Declared or streamed bytes exceed the limit }
        "422": { description: Declared size or SHA-256 verification failed }
        "507": { description: Drop storage reservation exceeds capacity }
  /api/v2/drop/objects/{cid}:
    parameters:
      - { name: cid, in: path, required: true, schema: { $ref: "#/components/schemas/CID" } }
    get:
      summary: Stream one Drop object
      description: Requires exact purpose `drop_read`. Response bytes are streamed and bounded to the v1 object limit.
      security:
        - dropPurpose: []
          nodeKey: []
      responses:
        "200":
          description: Object bytes
          content:
            application/octet-stream:
              schema: { type: string, format: binary }
        "400": { description: Invalid CID }
        "401": { $ref: "#/components/responses/DropUnauthorized" }
        "413": { description: Kubo stream exceeds the object limit }
        "502": { description: Generic Drop operation failure }
  /api/v2/drop/pins/{cid}:
    parameters:
      - { name: cid, in: path, required: true, schema: { $ref: "#/components/schemas/CID" } }
    get:
      summary: Check recursive pin state
      description: Requires exact purpose `drop_pin_check`.
      security:
        - dropPurpose: []
          nodeKey: []
      responses:
        "200":
          description: Pin state
          content:
            application/json:
              schema:
                type: object
                required: [cid, pinned]
                properties:
                  cid: { $ref: "#/components/schemas/CID" }
                  pinned: { type: boolean }
        "400": { description: Invalid CID }
        "401": { $ref: "#/components/responses/DropUnauthorized" }
        "502": { description: Generic Drop operation failure }
    delete:
      summary: Remove a recursive pin
      description: Requires exact purpose `drop_unpin`. Absence is treated idempotently.
      security:
        - dropPurpose: []
          nodeKey: []
      responses:
        "204": { description: Pin absent or removed }
        "400": { description: Invalid CID }
        "401": { $ref: "#/components/responses/DropUnauthorized" }
        "502": { description: Generic Drop operation failure }
  /api/v2/drop/webui:
    get:
      summary: Private Kubo WebUI entry point
      description: Requires exact purpose `drop_webui` and DROP_WEBUI_ENABLED on a private node.
      security:
        - dropPurpose: []
          nodeKey: []
      responses:
        "200": { description: Proxied WebUI response }
        "401": { $ref: "#/components/responses/DropUnauthorized" }
        "404": { description: Drop WebUI is disabled or unavailable }
        "502": { description: Kubo WebUI is unavailable }
  /api/v2/drop/webui/{path}:
    parameters:
      - { name: path, in: path, required: true, schema: { type: string }, description: Kubo WebUI path }
    get:
      summary: Private Kubo WebUI proxy
      description: |
        Requires exact purpose `drop_webui` and DROP_WEBUI_ENABLED on a private
        node. Authorization, node-key, Origin, and Referer headers are removed
        before proxying to Kubo.
      security:
        - dropPurpose: []
          nodeKey: []
      responses:
        "200": { description: Proxied WebUI response }
        "401": { $ref: "#/components/responses/DropUnauthorized" }
        "404": { description: Drop WebUI is disabled or unavailable }
        "502": { description: Kubo WebUI is unavailable }
  /api/v2/peers:
    get:
      summary: List provisioned peers (ids and metadata only, no credentials)
      responses:
        "200":
          description: Peer list
          content:
            application/json:
              schema:
                type: array
                items: { $ref: "#/components/schemas/PeerInfo" }
  /api/v2/peers/{id}:
    parameters:
      - { name: id, in: path, required: true, schema: { type: string, format: uuid }, description: Gateway-issued VPN client UUID }
    put:
      summary: Create or update a peer (idempotent upsert)
      description: |
        Provisions the peer across ALL protocols atomically: allocates a
        WireGuard IP, generates VLESS UUID and Hysteria2 password, applies the
        WireGuard peer via wgctrl, and rebuilds sing-box inbounds. Repeating
        the call with the same id and public key returns the same bundle
        (gateway retries are safe). Returns 409 while the node is draining.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name, wg_public_key]
              properties:
                name: { type: string, maxLength: 64 }
                wallet: { type: string, description: Owner wallet address (informational) }
                wg_public_key: { type: string, description: Client-generated Curve25519 public key, base64 }
                wg_preshared_key: { type: string, description: Optional client-generated PSK, base64 }
                expires_at: { type: integer, format: int64, description: Unix seconds; 0 = no expiry }
      responses:
        "200": { description: Peer upserted, content: { application/json: { schema: { $ref: "#/components/schemas/CredentialBundle" } } } }
        "400": { description: Invalid key or body }
        "409": { description: Node is draining or subnet exhausted }
    delete:
      summary: Remove a peer from all protocols
      responses:
        "204": { description: Peer removed (idempotent — also returned if absent) }
  /api/v2/peers/{id}/credentials:
    parameters:
      - { name: id, in: path, required: true, schema: { type: string, format: uuid } }
    get:
      summary: Re-fetch the credential bundle for an existing peer
      description: |
        Same response as PUT. Used by the gateway's authenticated config
        re-fetch (replaces the v1 Walrus blob flow). The WireGuard client_conf
        contains a placeholder for the private key, which only the end client
        ever held.
      responses:
        "200": { description: Bundle, content: { application/json: { schema: { $ref: "#/components/schemas/CredentialBundle" } } } }
        "404": { description: Unknown peer }
components:
  securitySchemes:
    paseto:
      type: http
      scheme: bearer
      description: Node-scoped PASETO issued by the gateway at node registration.
    dropPurpose:
      type: http
      scheme: bearer
      description: Gateway-issued PASETO targeted to this node with the exact Drop route purpose.
    nodeKey:
      type: apiKey
      in: header
      name: X-Erebrus-Node-Key
      description: Per-node key required in addition to the exact-purpose bearer token.
  responses:
    DropUnauthorized:
      description: Missing/invalid node key or bearer token, including target or exact-purpose mismatch
  schemas:
    Capabilities:
      type: object
      properties:
        services:
          type: object
          additionalProperties:
            type: string
          description: Coarse service states; the `drop` value uses the DropStatus state enum.
        drop:
          $ref: "#/components/schemas/DropCapability"
    DropCapability:
      type: object
      required: [enabled, accepts_public_uploads, webui_available]
      properties:
        enabled: { type: boolean }
        accepts_public_uploads: { type: boolean }
        webui_available: { type: boolean }
    DropStatus:
      type: object
      required: [state, repo_size_bytes, storage_max_bytes, num_objects]
      properties:
        state: { type: string, enum: [disabled, starting, active, degraded, full, unreachable] }
        kubo_version: { type: string, example: "0.42.0" }
        repo_size_bytes: { type: integer, format: int64, minimum: 0 }
        storage_max_bytes: { type: integer, format: int64, minimum: 0 }
        num_objects: { type: integer, format: int64, minimum: 0 }
    Readiness:
      type: object
      required: [ok, checks]
      properties:
        ok: { type: boolean, description: VPN readiness; optional Drop failures do not change this value }
        checks:
          type: array
          items: { $ref: "#/components/schemas/ReadinessCheck" }
        warnings:
          type: array
          items: { type: string }
    ReadinessCheck:
      type: object
      required: [id, ok]
      properties:
        id: { type: string }
        ok: { type: boolean }
        detail: { type: string }
        optional: { type: boolean }
    CID:
      type: string
      description: Valid CIDv0 or CIDv1 accepted by go-cid
      example: bafkreidy534f3mmy722yr73zat5nd65m22zbbir5vnmytafwu42bnnx4t4
    PeerInfo:
      type: object
      properties:
        id: { type: string, format: uuid }
        name: { type: string }
        wg_allowed_ip: { type: string, example: "10.0.0.7/32" }
        enabled: { type: boolean }
        created_at: { type: integer, format: int64 }
        expires_at: { type: integer, format: int64 }
    CredentialBundle:
      type: object
      description: Everything a client needs for every protocol, in one response.
      properties:
        id: { type: string, format: uuid }
        wireguard:
          type: object
          properties:
            client_conf:
              type: string
              description: |
                Complete wg-quick [Interface]/[Peer] file with the literal
                placeholder REPLACE_WITH_PRIVATE_KEY for the client's private
                key (the node never sees it).
            server_public_key: { type: string }
            endpoint: { type: string, example: "203.0.113.10:51820" }
            address: { type: string, example: "10.0.0.7/32" }
            dns: { type: string, example: "10.0.0.1" }
        vless_uri:
          type: string
          description: vless:// share URI (REALITY, flow=xtls-rprx-vision)
          example: "vless://c0a4f1de-...@203.0.113.10:443?security=reality&pbk=...&sid=...&sni=www.microsoft.com&flow=xtls-rprx-vision&type=tcp#erebrus-sg"
        hysteria2_uri:
          type: string
          example: "hysteria2://pw@203.0.113.10:443/?insecure=1&sni=node#erebrus-sg"
        singbox_profile:
          type: object
          description: |
            Complete sing-box client config fragment: outbounds for wg
            (endpoint), vless and hysteria2, WITHOUT selector/urltest groups —
            the gateway injects the "auto"/"stealth" groups before handing the
            profile to end clients.