openapi.yaml

openapi: 3.1.0
info:
  title: Portwing Agent API
  version: 0.9.17
  description: |
    Portwing is a lightweight remote Docker agent for the Drydock container
    monitoring platform. This specification covers the **Standard Mode** HTTP API
    only (Edge Mode communicates over a WebSocket multiplexed protocol documented
    separately in SPEC.md §3).

    ## Authentication

    All protected endpoints require the agent token, supplied via one of:

    - `Authorization: Bearer <token>` (standard, checked first)
    - `X-Portwing-Token` header
    - `X-Dd-Agent-Secret` header (Drydock agent secret header)

    Raw-token verification hashes each presented value and compares a
    fixed-size SHA-256 digest with `crypto/subtle.ConstantTimeCompare`.
    Standard mode fails closed when no token, token hash, or authorized-keys
    registry is configured. Unauthenticated development requires explicit
    opt-in and an additional acknowledgement for non-loopback binds.

    **Rate limiting:** 10 failed attempts per IP per rolling minute. Exceeding
    the threshold returns HTTP 429 until the window expires.

    ## Docker Engine API Proxy

    Any path not matched by a named route is transparently proxied to the local
    Docker daemon (Unix socket). This includes every endpoint in the
    [Docker Engine API](https://docs.docker.com/engine/api/) — streaming
    endpoints (`/logs`, `/attach`, `/exec/*/start`, `/events`, `/build`,
    `/images/create`, `/images/{name}/push`, `/containers/{id}/stats` (streaming is disabled when `stream` is empty, `0`, `no`, `false`, or `none`)), interactive exec hijacking
    (`Upgrade: tcp`), and binary responses. Paths are forwarded verbatim; the
    agent negotiates the API version on startup (fallback: `v1.44`).

    A representative proxy path is shown below under `/v1.44/{path}`.

  contact:
    email: security@codeswhat.com
  license:
    name: AGPL-3.0
    url: https://www.gnu.org/licenses/agpl-3.0.html

servers:
  - url: http://{host}:{port}
    description: Standard mode (HTTP)
    variables:
      host:
        default: localhost
      port:
        default: "3000"
  - url: https://{host}:{port}
    description: Standard mode (HTTPS/TLS 1.2+)
    variables:
      host:
        default: localhost
      port:
        default: "3000"

components:
  securitySchemes:
    bearerToken:
      type: http
      scheme: bearer
      description: >
        Agent token via Authorization: Bearer. Also accepted in the
        `X-Portwing-Token` header, or Drydock's `X-Dd-Agent-Secret` header.
    portwingToken:
      type: apiKey
      in: header
      name: X-Portwing-Token
      description: Agent token via the X-Portwing-Token header.
    ed25519Signature:
      type: apiKey
      in: header
      name: X-Portwing-Signature
      description: |
        Ed25519 per-request signature (base64url, no padding). When this header
        is present the agent verifies the request via Ed25519 instead of the
        shared token.

        Signature version 2 requires five headers together:

        | Header | Format | Example |
        |--------|--------|---------|
        | `X-Portwing-Key-ID` | hex(SHA-256(raw 32-byte pubkey)[:8]) | `4a3f2b1c9d8e7f6a` |
        | `X-Portwing-Timestamp` | Unix epoch, seconds, decimal | `1749600000` |
        | `X-Portwing-Nonce` | 32 random hex chars (128-bit) | `a1b2c3d4e5f6...` |
        | `X-Portwing-Signature` | base64url (no padding) Ed25519 signature | `d2hh...` |
        | `X-Portwing-Signature-Version` | canonical format version | `2` |

        The signed canonical string is:
        ```
        METHOD\nREQUEST-TARGET\nbody-sha256-hex\nunix-timestamp\nnonce
        ```
        `REQUEST-TARGET` is the escaped path plus the exact raw query string.
        Unversioned legacy signatures are accepted only on query-free requests.
        For an empty body, `body-sha256-hex` is the full SHA-256 of the empty
        string: `e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855`.

        On failure, the response includes `X-Portwing-Reason` with one of:
        `timestamp-skew`, `replay`, `unknown-key`, `invalid-signature`.

  schemas:
    HealthResponse:
      type: object
      required: [status, live, ready, mode, version, uptimeSeconds, docker, controller]
      properties:
        status:
          type: string
          enum: [ok, healthy, unhealthy]
          example: healthy
        live:
          type: boolean
          description: Whether the Portwing process is running.
        ready:
          type: boolean
          description: Whether the dependencies required by the current mode are connected.
        mode:
          type: string
          enum: [standard, edge]
        version:
          type: string
          description: Portwing agent version.
          example: "0.9.17"
        uptimeSeconds:
          type: number
          minimum: 0
          description: Seconds since the agent process started.
        docker:
          type: string
          enum: [connected, disconnected, unknown]
          example: connected
        controller:
          type: string
          enum: [connected, disconnected, not_applicable]
          description: Edge controller state, or `not_applicable` in standard mode.

    InfoResponse:
      type: object
      required: [version, dockerVersion, mode, uptime, hostname, agentId, agentName, capabilities]
      properties:
        version:
          type: string
          description: Portwing agent version
          example: "0.9.17"
        dockerVersion:
          type: string
          description: Docker Engine version string
          example: "27.0.3"
        mode:
          type: string
          enum: [standard]
          description: Connection mode (always "standard" in HTTP API)
        uptime:
          type: string
          description: Agent uptime as a Go duration string
          example: "2h34m56.789s"
        hostname:
          type: string
          example: "my-server"
        agentId:
          type: string
          format: uuid
          example: "550e8400-e29b-41d4-a716-446655440000"
        agentName:
          type: string
          example: "my-server"
        capabilities:
          type: array
          description: >
            Adapter namespace and transport capabilities. Unsupported legacy
            dd:watch and dd:trigger capabilities are omitted. Use the watcher
            descriptor and empty trigger list to discover the v0.9.0
            controller-owned execution contract; the corresponding wire message
            types remain reserved but unadvertised.
          items:
            type: string
          example: ["compose", "exec", "metrics", "events", "dd:container-sync", "dd:logs"]

    ComposeRequest:
      type: object
      required: [operation, stackName]
      properties:
        operation:
          type: string
          enum: [up, down, pull, ps, logs, restart, stop, start]
          description: Compose sub-command to execute.
        stackName:
          type: string
          description: >
            Stack name. Used as the subdirectory under `STACKS_DIR`
            when `stackDir` is not supplied.
          example: "myapp"
        stackDir:
          type: string
          description: >
            Explicit subdirectory within `STACKS_DIR`. Overrides the
            `stackName`-derived path. Must not escape the stacks directory
            (path-traversal protected).
          example: "myapp/v2"
        services:
          type: array
          items:
            type: string
          description: >
            Optional list of service names to scope the operation.
            Names starting with `-` are rejected (flag-injection guard).
          example: ["web", "worker"]
        build:
          type: boolean
          description: Pass `--build` to `compose up`.
          default: false
        forceRecreate:
          type: boolean
          description: Pass `--force-recreate` to `compose up`.
          default: false
        removeVolumes:
          type: boolean
          description: Pass `--volumes` to `compose down`.
          default: false
        noDeps:
          type: boolean
          description: Pass `--no-deps` to `compose up`.
          default: false
        tail:
          type: integer
          minimum: 1
          description: Number of log lines to tail (`logs` operation only).
          example: 100
        envVars:
          type: object
          additionalProperties:
            type: string
          description: >
            Environment variables written to `.env.drydock` before execution.
            Keys must match `^[a-zA-Z_][a-zA-Z0-9_]*$`. The following keys
            are denied: `LD_PRELOAD`, `LD_LIBRARY_PATH`, `PATH`,
            `DOCKER_HOST`, `DOCKER_CONFIG`, `DOCKER_CERT_PATH`,
            `DOCKER_TLS_VERIFY`, `DOCKER_CONTEXT`, `HOME`, `SHELL`,
            `BASH_ENV`, `ENV`, `CDPATH`, `IFS`.
          example:
            DATABASE_URL: "postgres://..."
            APP_PORT: "8080"
        files:
          type: object
          additionalProperties:
            type: string
          description: >
            Files to write into the stack directory before execution.
            Keys are paths relative to the stack directory; values are
            file content (plain text) or base64-encoded content prefixed
            with `base64:`. Paths are resolved and verified within the
            stacks directory (path-traversal protected).
          example:
            "docker-compose.yml": "version: '3'\nservices:\n  web:\n    image: nginx\n"
        registryAuth:
          $ref: '#/components/schemas/RegistryAuth'

    RegistryAuth:
      type: object
      required: [server, username, password]
      properties:
        server:
          type: string
          description: Registry hostname (e.g. `ghcr.io`).
          example: "ghcr.io"
        username:
          type: string
          example: "myuser"
        password:
          type: string
          format: password
          description: >
            Registry password or token. Passed via `--password-stdin`
            to `docker login`; never appears in process argument list.
          example: "ghp_..."

    ComposeResponse:
      type: object
      required: [success]
      properties:
        success:
          type: boolean
        output:
          type: string
          description: Combined stdout + stderr from the Compose command.
          example: "Container myapp-web-1  Started\n"
        error:
          type: string
          description: Error message if `success` is false.
          example: "exit status 1"

    Container:
      type: object
      description: Drydock container model with update metadata.
      properties:
        id:
          type: string
          example: "abc123def456"
        name:
          type: string
          example: "myapp-web-1"
        displayName:
          type: string
          example: "My App Web"
        displayIcon:
          type: string
          example: "docker"
        status:
          type: string
          example: "running"
        watcher:
          type: string
          example: "docker"
        agent:
          type: string
        health:
          type: string
          description: >
            Docker health-check state, present only when the container
            declares a health check.
          enum: [starting, healthy, unhealthy]
          example: "healthy"
        image:
          $ref: '#/components/schemas/ContainerImage'
        result:
          $ref: '#/components/schemas/ContainerResult'
        error:
          $ref: '#/components/schemas/ContainerError'
        updateAvailable:
          type: boolean
        updateKind:
          $ref: '#/components/schemas/ContainerUpdateKind'
        includeTags:
          type: string
        excludeTags:
          type: string
        transformTags:
          type: string
        labels:
          type: object
          additionalProperties:
            type: string
        details:
          $ref: '#/components/schemas/RuntimeDetails'

    ContainerImage:
      type: object
      description: >
        Drydock's image model. `registry`, `tag` and `digest` are objects, not
        strings: Drydock's AgentClient stores this shape verbatim, so the
        nesting is the wire contract rather than an encoding detail.
      required: [id, registry, name, tag, digest, architecture, os]
      properties:
        id:
          type: string
          example: "sha256:0f2c1a2f"
        registry:
          $ref: '#/components/schemas/ContainerImageRegistry'
        name:
          type: string
          example: "library/nginx"
        tag:
          $ref: '#/components/schemas/ContainerImageTag'
        digest:
          $ref: '#/components/schemas/ContainerImageDigest'
        architecture:
          type: string
          description: Image architecture, falling back to the agent's own.
          example: "arm64"
        os:
          type: string
          description: Image OS, falling back to the agent's own.
          example: "linux"
        created:
          type: string
          description: Image creation timestamp, when the daemon reports one.

    ContainerImageRegistry:
      type: object
      description: >
        Registry component assignment. Portwing reports the URL it parsed from
        the image reference and leaves `name` as `unknown`, because the
        registry component is named by the Drydock controller's own config.
      required: [name, url]
      properties:
        name:
          type: string
          example: "unknown"
        url:
          type: string
          example: "docker.io"

    ContainerImageTag:
      type: object
      required: [value, semver]
      properties:
        value:
          type: string
          example: "1.27.0"
        semver:
          type: boolean
          description: >
            Whether Drydock should treat `value` as a semver range. Portwing
            reports false; semver classification is controller-owned.
          example: false

    ContainerImageDigest:
      type: object
      required: [watch]
      properties:
        watch:
          type: boolean
          description: >
            Whether Drydock should watch the digest for changes. Portwing
            reports false; digest watching is controller-owned.
          example: false
        value:
          type: string
          description: Image digest (`sha256:...`) when the daemon reports one.
        repo:
          type: string
          description: Digest repository, set by the Drydock controller.

    ContainerUpdateKind:
      type: object
      description: >
        Update classification. Portwing's raw inventory always reports
        `{"kind":"unknown"}`; the Drydock controller fills in the real kind
        from its own watcher result.
      required: [kind]
      properties:
        kind:
          type: string
          example: "unknown"

    ContainerResult:
      type: object
      properties:
        tag:
          type: string
        digest:
          type: string
          description: Image digest (`sha256:...`) when resolved.
        created:
          type: string
          format: date-time
        link:
          type: string
          description: Optional link to the image/registry page.

    ContainerError:
      type: object
      properties:
        message:
          type: string

    RuntimeDetails:
      type: object
      description: Runtime container details (ports, mounts, environment, etc.).
      additionalProperties: true

    WatcherComponent:
      type: object
      description: >
        Drydock watcher component descriptor. Portwing v0.9.0's `docker`
        descriptor marks Docker API transport and watcher/update execution as
        controller-owned while retaining Portwing lifecycle events. Drydock
        v1.6.0-rc.11+ consumes this complete feature contract.
      required: [type, name, configuration]
      properties:
        type:
          type: string
          example: docker
        name:
          type: string
          example: docker
        configuration:
          type: object
          additionalProperties: true
          example:
            description: Watches Docker containers for updates via Docker Engine API
            capabilities: [container-sync, labels]
            transport: docker-api
            execution: controller
            events: portwing

    TriggerComponent:
      type: object
      description: >
        Drydock trigger component descriptor. Portwing v0.9.0 advertises an
        empty trigger list because update execution is controller-owned.
      additionalProperties: true

    NotImplementedResponse:
      type: object
      required: [error, message]
      properties:
        error:
          type: string
          example: "not implemented in v1.0"
        message:
          type: string
          example: "registry checking is performed by the Drydock controller"

    ErrorResponse:
      type: object
      properties:
        error:
          type: string

    GenericVersionResponse:
      type: object
      required: [agentVersion, protocolName, protocolVersion, adapter]
      description: Generic adapter version and protocol metadata.
      properties:
        agentVersion:
          type: string
          example: "0.9.17"
        protocolName:
          type: string
          example: "portwing"
        protocolVersion:
          type: string
          example: "1.0"
        adapter:
          type: string
          example: "generic"

    GenericEvent:
      type: object
      required: [ts, type, action, containerId, name, image]
      description: Generic Docker lifecycle event envelope (ADAPTER=generic SSE stream).
      properties:
        ts:
          type: string
          format: date-time
          description: Event timestamp in RFC 3339 UTC.
          example: "2026-06-11T10:00:00Z"
        type:
          type: string
          description: Docker object type (always "container" for this stream).
          example: "container"
        action:
          type: string
          description: Docker event action (create, start, stop, die, kill, etc.).
          example: "start"
        containerId:
          type: string
          description: Container ID from the Docker actor.
          example: "abc123def456"
        name:
          type: string
          description: Container name from event attributes.
          example: "my-container"
        image:
          type: string
          description: Image name from event attributes.
          example: "nginx:latest"
        labels:
          type: object
          additionalProperties:
            type: string
          description: >
            User-defined container labels from event attributes. Synthetic
            Docker keys (name, image, exitCode, etc.) are stripped.

    AuditRecord:
      type: object
      required: [cursor, ts, event]
      description: >
        A single structured audit event from the in-memory ring buffer. Field
        names match the stable on-wire JSON schema; optional fields are omitted
        when empty. This ring-buffer schema differs from the streamed slog log
        line, which uses `time`/`level`/`msg` keys.
      properties:
        cursor:
          type: integer
          format: int64
          minimum: 1
          description: Monotonic cursor scoped to the current agent process.
        ts:
          type: string
          format: date-time
          description: Event timestamp (RFC3339 UTC).
        event:
          type: string
          description: Event type.
          example: "exec_start"
        actor:
          type: string
          description: Authenticated principal (token label or key ID).
        method:
          type: string
          description: HTTP method (api_request / auth_failure / rate_limited events only).
        path:
          type: string
          description: HTTP path (api_request / auth_failure / rate_limited events only).
        outcome:
          type: string
          example: "allowed"
        status:
          type: integer
          example: 200
        duration_ms:
          type: number
        operation:
          type: string
        stack:
          type: string
        container:
          type: string
        exec_id:
          type: string
        key_id:
          type: string
          description: hex(SHA-256(pubkey)[:8]).

    AuditResponse:
      type: object
      required: [records, count]
      properties:
        records:
          type: array
          items:
            $ref: '#/components/schemas/AuditRecord'
        count:
          type: integer
          description: Number of records returned.

    MCPRequest:
      type: object
      required: [jsonrpc, method]
      description: JSON-RPC 2.0 request envelope.
      properties:
        jsonrpc:
          type: string
          enum: ["2.0"]
        id:
          description: Request ID (string, number, or null). Absent for notifications.
        method:
          type: string
          example: "tools/list"
        params:
          type: object
          additionalProperties: true

    MCPResponse:
      type: object
      required: [jsonrpc, id]
      description: JSON-RPC 2.0 response envelope.
      properties:
        jsonrpc:
          type: string
          enum: ["2.0"]
        id:
          description: Echoes the request ID.
        result:
          type: object
          additionalProperties: true
        error:
          type: object
          properties:
            code:
              type: integer
            message:
              type: string

paths:
  /health:
    get:
      operationId: getHealth
      summary: Process liveness
      description: >
        Returns HTTP 200 while the Portwing process is running. No auth
        required. This route does not probe Docker or the edge controller;
        use `/ready` for dependency readiness.
      tags: [Health]
      responses:
        "200":
          description: Agent is running.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'

  /ready:
    get:
      operationId: getReadiness
      summary: Agent readiness
      description: >
        Probes Docker connectivity and, in edge mode, the controller
        WebSocket. No auth required. Returns HTTP 503 until all dependencies
        required by the active mode are connected.
      tags: [Health]
      responses:
        "200":
          description: Agent dependencies are ready.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'
        "503":
          description: Docker or the edge controller is unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'

  /_portwing/health:
    get:
      operationId: getPortwingHealth
      summary: Agent health check with Docker connectivity
      description: >
        Compatibility alias for `/ready`. Returns mode, version, uptime,
        Docker state, and edge-controller state. No auth required.
      tags: [Health]
      responses:
        "200":
          description: Agent healthy and Docker connected.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'
              example:
                status: healthy
                docker: connected
        "503":
          description: Docker daemon unreachable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'
              example:
                status: unhealthy
                docker: disconnected

  /_portwing/info:
    get:
      operationId: getPortwingInfo
      summary: Agent metadata
      description: >
        Returns agent version, Docker version, connection mode, uptime,
        hostname, and capability list. Bearer auth required.
      tags: [Agent]
      security:
        - bearerToken: []
        - portwingToken: []
      responses:
        "200":
          description: Agent metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InfoResponse'
        "401":
          description: Missing or invalid token.
        "429":
          description: Rate limit exceeded (10 failures/min/IP).

  /_portwing/metrics:
    get:
      operationId: getPortwingMetrics
      summary: Prometheus metrics (namespaced)
      description: >
        Exposes Portwing agent metrics in Prometheus text exposition format
        (version 0.0.4), including HTTP, host, container, audit, and edge
        connection/backpressure series. Metrics are prefixed with `portwing_`
        or `container_`. Bearer auth is required in standard mode.

        Scrape this endpoint rather than `/metrics` when you want only
        agent-specific metrics without Docker daemon metrics.
      tags: [Metrics]
      security:
        - bearerToken: []
        - portwingToken: []
      responses:
        "200":
          description: Prometheus text format metrics.
          content:
            text/plain; version=0.0.4:
              schema:
                type: string
              example: |
                # HELP portwing_cpu_usage_percent Host CPU usage percentage.
                # TYPE portwing_cpu_usage_percent gauge
                portwing_cpu_usage_percent 23.5
                # HELP portwing_memory_used_bytes Host memory used in bytes.
                # TYPE portwing_memory_used_bytes gauge
                portwing_memory_used_bytes 4294967296
        "401":
          description: Missing or invalid token.
        "429":
          description: Rate limit exceeded.

  /metrics:
    get:
      operationId: getMetrics
      summary: Prometheus metrics (root)
      description: >
        Alias for `/_portwing/metrics`. Exposes Portwing agent metrics in
        Prometheus text exposition format (version 0.0.4). Bearer auth
        required.

        Provided for compatibility with default Prometheus scrape configs
        that expect metrics at `/metrics`.
      tags: [Metrics]
      security:
        - bearerToken: []
        - portwingToken: []
      responses:
        "200":
          description: Prometheus text format metrics.
          content:
            text/plain; version=0.0.4:
              schema:
                type: string
        "401":
          description: Missing or invalid token.
        "429":
          description: Rate limit exceeded.

  /_portwing/compose:
    post:
      operationId: postPortwingCompose
      summary: Docker Compose operations
      description: >
        Executes a Docker Compose sub-command within the managed stacks
        directory (`STACKS_DIR`, default `/data/stacks`). The request body
        specifies the operation, stack, optional files to write, and optional
        env vars.

        **Security controls applied before execution:**
        - Stack path resolved to absolute and verified within `STACKS_DIR`
          (path-traversal protection).
        - Env var keys validated against `^[a-zA-Z_][a-zA-Z0-9_]*$` and
          checked against the denylist.
        - Service names must not start with `-` (flag-injection prevention).
        - Registry auth passed via `--password-stdin` (never in argv).
      tags: [Compose]
      security:
        - bearerToken: []
        - portwingToken: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ComposeRequest'
            examples:
              up:
                summary: Bring up a stack
                value:
                  operation: up
                  stackName: myapp
                  build: false
                  forceRecreate: false
              down-with-volumes:
                summary: Remove a stack including volumes
                value:
                  operation: down
                  stackName: myapp
                  removeVolumes: true
              deploy-with-files:
                summary: Write compose file then bring up
                value:
                  operation: up
                  stackName: myapp
                  files:
                    "docker-compose.yml": "version: '3'\nservices:\n  web:\n    image: nginx:latest\n"
                  envVars:
                    APP_PORT: "8080"
      responses:
        "200":
          description: Compose command executed (check `success` field for result).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComposeResponse'
              examples:
                success:
                  value:
                    success: true
                    output: "Container myapp-web-1  Started\n"
                failure:
                  value:
                    success: false
                    output: "Error response from daemon: ..."
                    error: "exit status 1"
        "400":
          description: Invalid or malformed request body.
        "401":
          description: Missing or invalid token.
        "429":
          description: Rate limit exceeded.
        "500":
          description: Internal server error.

  /_portwing/audit:
    get:
      operationId: getPortwingAudit
      summary: Recent audit records
      description: >
        Returns recent structured audit records from the in-memory ring
        buffer, newest-first. Bearer auth required.
      tags: [Agent]
      security:
        - bearerToken: []
        - portwingToken: []
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
          description: >
            Maximum number of records to return (newest-first). Omit or use a
            non-positive value to return all currently buffered records.
          example: 100
      responses:
        "200":
          description: Buffered audit records.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuditResponse'
        "401":
          description: Missing or invalid token.
        "429":
          description: Rate limit exceeded.

  /_portwing/audit/export:
    get:
      operationId: exportPortwingAudit
      summary: Cursor-based NDJSON audit export
      description: >
        Streams retained audit records oldest-first as newline-delimited JSON.
        On the first request, omit `cursor` to bootstrap from the oldest
        retained record. Persist `X-Portwing-Next-Cursor` and provide it on the
        next request. A 409 response detects overwritten history or an agent
        restart instead of silently skipping records. Standard mode requires
        Bearer or Portwing-token authentication. Edge mode exposes this route
        without inbound authentication on its private operations listener;
        restrict listener access because records may contain sensitive
        operational metadata.
      tags: [Agent]
      security:
        - bearerToken: []
        - portwingToken: []
      parameters:
        - name: cursor
          in: query
          schema:
            type: integer
            format: int64
            minimum: 0
          description: Last successfully consumed cursor. Omit for initial bootstrap.
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 0
          description: Maximum records to return; zero or omitted returns all retained matches.
      responses:
        "200":
          description: Retained records after the supplied cursor.
          headers:
            X-Portwing-Oldest-Cursor:
              schema:
                type: integer
            X-Portwing-Latest-Cursor:
              schema:
                type: integer
            X-Portwing-Next-Cursor:
              schema:
                type: integer
              description: Cursor to persist after consuming the response.
            X-Portwing-Record-Count:
              schema:
                type: integer
          content:
            application/x-ndjson:
              schema:
                type: string
              example: |
                {"cursor":41,"ts":"2026-07-28T19:00:00Z","event":"auth_failure","actor":"203.0.113.9","method":"GET","path":"/_portwing/info","outcome":"denied"}
                {"cursor":42,"ts":"2026-07-28T19:00:01Z","event":"api_request","actor":"203.0.113.42","method":"GET","path":"/metrics","outcome":"allowed","status":200}
        "400":
          description: Invalid cursor or limit.
        "409":
          description: >
            Cursor is outside the current retained window. Reset to the
            `X-Portwing-Next-Cursor` response header and surface the gap.
        "401":
          description: Missing or invalid token (Standard mode only).
        "429":
          description: Rate limit exceeded.

  /_portwing/mcp:
    post:
      operationId: postPortwingMcp
      summary: MCP server (Model Context Protocol, read-only)
      description: >
        Read-only MCP server over the Streamable HTTP transport (protocol
        revision `2025-11-25`). Each POST carries a single JSON-RPC 2.0 request
        and returns one JSON-RPC 2.0 response (`application/json`); the server
        is stateless and assigns no `Mcp-Session-Id`. Supported methods include
        `initialize`, `tools/list`, and `tools/call`. Bearer auth required.

        `GET /_portwing/mcp` returns 405 (no server-initiated SSE stream).
      tags: [MCP]
      security:
        - bearerToken: []
        - portwingToken: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MCPRequest'
            example:
              jsonrpc: "2.0"
              id: 1
              method: tools/list
      responses:
        "200":
          description: JSON-RPC 2.0 response object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MCPResponse'
        "202":
          description: >
            Accepted, empty body. Returned for a valid JSON-RPC notification
            (a request with no `id`) and for a valid JSON-RPC response
            message sent to the server (a `result`/`error` object with no
            `method`); the server does not reply to either.
        "400":
          description: >
            Bad request, empty body. Returned only for notification-shaped
            bodies: a `result`/`error` object with no `method` that fails
            JSON-RPC response validation, or a notification (no `id`) whose
            `params` is present but not a JSON object. Requests carrying an
            `id` report errors inside a 200 JSON-RPC error envelope instead.
        "401":
          description: Missing or invalid token.
        "405":
          description: Method not allowed (POST required; GET has no SSE stream).
        "429":
          description: Rate limit exceeded.

  /api/events:
    get:
      operationId: getApiEvents
      summary: SSE container event stream
      description: >
        Server-Sent Events stream of container lifecycle events. Immediately
        emits a `dd:ack` event with agent metadata and current container
        counts, followed by a `dd:watcher-snapshot` event carrying the watcher
        descriptor and the full authoritative container inventory, then streams
        `dd:container-added`, `dd:container-updated`, and `dd:container-removed`
        events as Docker reports them. A fresh `dd:watcher-snapshot` is also
        broadcast after every poll cycle.

        The connection is held open until the client disconnects. Each event
        is a JSON object on a `data:` line followed by a blank line (standard
        SSE format).

        **Event types:**

        | Type | Description |
        |------|-------------|
        | `dd:ack` | Initial handshake; agent metadata + container counts |
        | `dd:watcher-snapshot` | Watcher descriptor + full container inventory (on connect and after every poll cycle) |
        | `dd:container-added` | New container discovered |
        | `dd:container-updated` | Container state or metadata changed |
        | `dd:container-removed` | Container removed |

        **Example stream:**
        ```
        data: {"type":"dd:ack","data":{"version":"0.9.17","os":"linux","arch":"amd64","cpus":4,"memoryGb":0,"uptimeSeconds":3600,"lastSeen":"2024-07-23T10:00:00Z","containers":{"total":5,"running":4,"stopped":1},"images":3}}

        data: {"type":"dd:watcher-snapshot","data":{"watcher":{...WatcherComponent...},"containers":[{...Container...}]}}

        data: {"type":"dd:container-added","data":{...Container...}}

        data: {"type":"dd:container-removed","data":{"id":"abc123","name":"old-container"}}
        ```
      tags: [Drydock Compat]
      security:
        - bearerToken: []
        - portwingToken: []
      responses:
        "200":
          description: SSE stream opened.
          content:
            text/event-stream:
              schema:
                type: string
                description: Newline-delimited SSE frames.
        "401":
          description: Missing or invalid token.
        "429":
          description: Rate limit exceeded.
        "500":
          description: Streaming not supported by server.

  /api/containers:
    get:
      operationId: getApiContainers
      summary: Container inventory
      description: >
        Returns the full container inventory as parsed from Docker with
        `dd.*` label metadata applied. This is the same data set sent via
        the `dd:container_sync` WebSocket message in Edge mode.
      tags: [Drydock Compat]
      security:
        - bearerToken: []
        - portwingToken: []
      responses:
        "200":
          description: Array of containers.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Container'
        "401":
          description: Missing or invalid token.
        "429":
          description: Rate limit exceeded.

  /api/containers/{id}/logs:
    get:
      operationId: getApiContainerLogs
      summary: Container logs
      description: >
        Returns demuxed container logs (Docker's 8-byte stream multiplexing
        header is stripped). Supports optional tailing, time filtering, and
        live following.
      tags: [Drydock Compat]
      security:
        - bearerToken: []
        - portwingToken: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Container ID or name.
          example: "abc123def456"
        - name: tail
          in: query
          schema:
            type: integer
            minimum: 1
          description: Number of lines from the end to return.
          example: 100
        - name: since
          in: query
          schema:
            type: string
          description: >
            Show logs since this timestamp (RFC3339) or relative duration
            (e.g., `1h`). Passed directly to Docker API.
          example: "2024-07-23T10:00:00Z"
        - name: until
          in: query
          schema:
            type: string
          description: Show logs before this timestamp or duration.
        - name: follow
          in: query
          schema:
            type: string
            enum: ["0", "1", "true", "false"]
          description: >
            Stream logs in real time. Response uses chunked transfer
            encoding when `follow=1` or `follow=true`.
        - name: timestamps
          in: query
          schema:
            type: string
            enum: ["0", "1", "true", "false"]
          description: >
            Prefix each log line with Docker's RFC3339Nano timestamp when
            `timestamps=1` or `timestamps=true`.
      responses:
        "200":
          description: Log output (plain text, demuxed).
          content:
            text/plain:
              schema:
                type: string
        "400":
          description: Invalid `tail` value.
        "401":
          description: Missing or invalid token.
        "404":
          description: Container not found (Docker reported status 404).
        "409":
          description: >
            Conflict reported by Docker for this container (Docker reported
            status 409).
        "429":
          description: Rate limit exceeded.
        "500":
          description: Error retrieving logs from Docker.
        "503":
          description: >
            Concurrent stream limit reached (follow mode only; see
            MAX_STREAM_SESSIONS).

  /api/containers/{id}:
    delete:
      operationId: deleteApiContainer
      summary: Remove a container
      description: Removes a container (force=true). Returns 204 on success.
      tags: [Drydock Compat]
      security:
        - bearerToken: []
        - portwingToken: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Container ID or name.
      responses:
        "204":
          description: Container removed.
        "401":
          description: Missing or invalid token.
        "404":
          description: Container not found (Docker reported status 404).
        "409":
          description: >
            Removal conflict — e.g. the container is still running and cannot
            be removed (Docker reported status 409).
        "429":
          description: Rate limit exceeded.
        "500":
          description: Error removing container.

  /api/watchers:
    get:
      operationId: getApiWatchers
      summary: Watcher component descriptors
      description: >
        Returns the list of watcher component descriptors registered with
        this agent. Portwing reports one `docker` watcher marked
        `transport=docker-api`, `execution=controller`, and `events=portwing`.
        Drydock v1.6.0-rc.11+ runs its native watcher and update trigger through
        Portwing's authenticated proxy; Portwing supplies lifecycle events.
      tags: [Drydock Compat]
      security:
        - bearerToken: []
        - portwingToken: []
      responses:
        "200":
          description: Array of watcher components.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/WatcherComponent'
        "401":
          description: Missing or invalid token.
        "429":
          description: Rate limit exceeded.

  /api/triggers:
    get:
      operationId: getApiTriggers
      summary: Trigger component descriptors
      description: >
        Returns an empty list. Portwing advertises no remote trigger; compatible
        Drydock runs its controller-owned update trigger through the Docker API
        proxy. Legacy trigger POST routes remain present and return 501.
      tags: [Drydock Compat]
      security:
        - bearerToken: []
        - portwingToken: []
      responses:
        "200":
          description: Array of trigger components.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TriggerComponent'
        "401":
          description: Missing or invalid token.
        "429":
          description: Rate limit exceeded.

  /api/watchers/{type}/{name}:
    get:
      operationId: getApiWatcher
      summary: Single watcher descriptor
      description: >
        Returns the watcher component descriptor matching `type`/`name`
        (case-insensitive). Called by Drydock's `AgentClient.getWatcher()`.
      tags: [Drydock Compat]
      security:
        - bearerToken: []
        - portwingToken: []
      parameters:
        - name: type
          in: path
          required: true
          schema:
            type: string
          example: "docker"
        - name: name
          in: path
          required: true
          schema:
            type: string
          example: "docker"
      responses:
        "200":
          description: Watcher component descriptor.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WatcherComponent'
        "401":
          description: Missing or invalid token.
        "404":
          description: No watcher matches the given type/name.
        "429":
          description: Rate limit exceeded.
    post:
      operationId: postApiWatcherPoll
      summary: Trigger watcher poll
      description: >
        Not implemented in v1.0. Registry checking is performed by the
        Drydock controller. Returns HTTP 501.
      tags: [Drydock Compat]
      security:
        - bearerToken: []
        - portwingToken: []
      parameters:
        - name: type
          in: path
          required: true
          schema:
            type: string
          example: "docker"
        - name: name
          in: path
          required: true
          schema:
            type: string
          example: "my-watcher"
      responses:
        "501":
          description: Not implemented.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotImplementedResponse'
        "401":
          description: Missing or invalid token.
        "429":
          description: Rate limit exceeded.

  /api/watchers/{type}/{name}/container/{id}:
    post:
      operationId: postApiWatcherContainer
      summary: Check single container
      description: >
        Not implemented in v1.0. Registry checking is performed by the
        Drydock controller. Returns HTTP 501.
      tags: [Drydock Compat]
      security:
        - bearerToken: []
        - portwingToken: []
      parameters:
        - name: type
          in: path
          required: true
          schema:
            type: string
        - name: name
          in: path
          required: true
          schema:
            type: string
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "501":
          description: Not implemented.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotImplementedResponse'
        "401":
          description: Missing or invalid token.
        "429":
          description: Rate limit exceeded.

  /api/triggers/{type}/{name}:
    post:
      operationId: postApiTriggerExec
      summary: Execute trigger
      description: >
        Not implemented in v1.0. Returns HTTP 501.
      tags: [Drydock Compat]
      security:
        - bearerToken: []
        - portwingToken: []
      parameters:
        - name: type
          in: path
          required: true
          schema:
            type: string
        - name: name
          in: path
          required: true
          schema:
            type: string
      responses:
        "501":
          description: Not implemented.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotImplementedResponse'
        "401":
          description: Missing or invalid token.
        "429":
          description: Rate limit exceeded.

  /api/triggers/{type}/{name}/batch:
    post:
      operationId: postApiTriggerBatch
      summary: Execute batch trigger
      description: >
        Not implemented in v1.0. Returns HTTP 501.
      tags: [Drydock Compat]
      security:
        - bearerToken: []
        - portwingToken: []
      parameters:
        - name: type
          in: path
          required: true
          schema:
            type: string
        - name: name
          in: path
          required: true
          schema:
            type: string
      responses:
        "501":
          description: Not implemented.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotImplementedResponse'
        "401":
          description: Missing or invalid token.
        "429":
          description: Rate limit exceeded.

  /api/log/entries:
    get:
      operationId: getApiLogEntries
      summary: Agent log entries (compatibility stub)
      description: >
        Returns an empty JSON array. Drydock calls this endpoint to populate
        its agent log viewer; Portwing keeps no in-memory log buffer, so it
        returns `[]` to avoid 404s in Drydock's log panel.
      tags: [Drydock Compat]
      security:
        - bearerToken: []
        - portwingToken: []
      responses:
        "200":
          description: Always an empty array.
          content:
            application/json:
              schema:
                type: array
                items: {}
                example: []
        "401":
          description: Missing or invalid token.
        "429":
          description: Rate limit exceeded.

  /api/v1/version:
    get:
      operationId: getGenericVersion
      summary: Agent version and protocol info (generic adapter)
      description: >
        Returns agent version, protocol name/version, and the active adapter
        name. Available when `ADAPTER=generic`. No platform integration required.
      tags: [Generic]
      security:
        - bearerToken: []
        - portwingToken: []
      responses:
        "200":
          description: Version metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericVersionResponse'
        "401":
          description: Missing or invalid token.
        "429":
          description: Rate limit exceeded.

  /api/v1/containers:
    get:
      operationId: getGenericContainers
      summary: Container inventory (generic adapter)
      description: >
        Returns the cached container inventory built from the Docker daemon.
        Available when `ADAPTER=generic`. The response shape is the same
        `Container` model used by the Drydock-compatible endpoints.
      tags: [Generic]
      security:
        - bearerToken: []
        - portwingToken: []
      responses:
        "200":
          description: Array of containers.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Container'
        "401":
          description: Missing or invalid token.
        "429":
          description: Rate limit exceeded.

  /api/v1/containers/{id}/logs:
    get:
      operationId: getGenericContainerLogs
      summary: Container logs (generic adapter)
      description: >
        Returns demuxed container logs (Docker's 8-byte stream multiplexing
        header is stripped). Supports optional tailing, time filtering, and
        live following. Available when `ADAPTER=generic`.
      tags: [Generic]
      security:
        - bearerToken: []
        - portwingToken: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Container ID or name.
          example: "abc123def456"
        - name: tail
          in: query
          schema:
            type: integer
            minimum: 1
          description: Number of lines from the end to return.
          example: 100
        - name: since
          in: query
          schema:
            type: string
          description: Show logs since this timestamp (RFC3339) or relative duration.
          example: "2026-01-01T00:00:00Z"
        - name: until
          in: query
          schema:
            type: string
          description: Show logs before this timestamp or duration.
        - name: follow
          in: query
          schema:
            type: string
            enum: ["0", "1", "true", "false"]
          description: Stream logs in real time with chunked transfer encoding.
      responses:
        "200":
          description: Log output (plain text, demuxed).
          content:
            text/plain:
              schema:
                type: string
        "400":
          description: Invalid `tail` value.
        "401":
          description: Missing or invalid token.
        "404":
          description: Container not found (Docker reported status 404).
        "409":
          description: >
            Conflict reported by Docker for this container (Docker reported
            status 409).
        "429":
          description: Rate limit exceeded.
        "500":
          description: Error retrieving logs from Docker.
        "503":
          description: >
            Concurrent stream limit reached (follow mode only; see
            MAX_STREAM_SESSIONS).

  /api/v1/events:
    get:
      operationId: getGenericEvents
      summary: Docker lifecycle event stream (generic adapter)
      description: >
        Server-Sent Events stream of Docker container lifecycle events in a
        stable generic envelope. Available when `ADAPTER=generic`.

        Each event is a JSON object on a `data:` line followed by a blank line
        (standard SSE format). A comment heartbeat (`": heartbeat"`) is sent
        every 30 seconds to keep the connection alive. The stream reconnects
        internally with exponential backoff if Docker becomes unavailable.

        Client disconnect cleanly terminates the stream.

        **Event actions** (from `allowedActions` in `internal/docker/events.go`):
        `create`, `start`, `stop`, `die`, `kill`, `restart`, `pause`,
        `unpause`, `destroy`, `rename`, `update`, `oom`, `health_status`.

        **Example stream:**
        ```
        data: {"ts":"2026-06-11T10:00:00Z","type":"container","action":"start","containerId":"abc123","name":"my-app","image":"nginx:latest"}

        : heartbeat

        data: {"ts":"2026-06-11T10:00:30Z","type":"container","action":"die","containerId":"abc123","name":"my-app","image":"nginx:latest","labels":{"app":"web"}}
        ```
      tags: [Generic]
      security:
        - bearerToken: []
        - portwingToken: []
      responses:
        "200":
          description: SSE stream opened.
          content:
            text/event-stream:
              schema:
                type: string
                description: >
                  Newline-delimited SSE frames. Each `data:` frame contains a
                  `GenericEvent` JSON object.
        "401":
          description: Missing or invalid token.
        "429":
          description: Rate limit exceeded.
        "500":
          description: Streaming not supported by server.

  /v1.44/{path}:
    x-docker-proxy: true
    get:
      operationId: dockerProxyGet
      summary: Docker Engine API proxy (representative entry)
      description: >
        **All paths not matched by a named route above are transparently
        proxied to the local Docker daemon.** This entry is representative;
        the full API surface is the Docker Engine API at
        https://docs.docker.com/engine/api/v1.44/.

        The agent negotiates the API version on startup (e.g., `v1.47`);
        `v1.44` is the fallback. Clients may omit the version prefix — the
        agent prepends it automatically.

        Streaming endpoints (`/logs`, `/attach`, `/exec/*/start`, `/events`,
        `/build`, `/images/create`, `/images/{name}/push`, `/containers/{id}/stats` (streaming is disabled when `stream` is empty, `0`, `no`, `false`, or `none`)) are detected by path and
        forwarded with flush-on-read streaming. Interactive exec sessions
        using `Upgrade: tcp` or `Upgrade: websocket` are handled via HTTP
        hijacking. Bearer auth is required for all proxy paths.
      tags: [Docker Proxy]
      security:
        - bearerToken: []
        - portwingToken: []
      parameters:
        - name: path
          in: path
          required: true
          schema:
            type: string
          example: "containers/json"
      responses:
        "200":
          description: Response from Docker daemon (format varies by endpoint).
        "401":
          description: Missing or invalid token.
        "429":
          description: Rate limit exceeded.
        "502":
          description: Docker daemon unreachable or returned an error.

  /api/portwing/enroll:
    post:
      operationId: enrollPublicKey
      summary: Register an Ed25519 public key (Model C enrollment)
      description: |
        One-shot bootstrap endpoint that registers an Ed25519 public key using
        a pre-configured enrollment token. The token is burned after first
        successful use; subsequent calls are rejected until the agent restarts
        with a new `ENROLLMENT_TOKEN`.

        This endpoint is **only available** when `ENROLLMENT_TOKEN` (and
        `AUTHORIZED_KEYS`) are configured. It is reachable without prior
        authentication — the enrollment token IS the credential — but it is
        rate-limited. Bad enrollment credentials feed the authentication
        failure limiter; malformed or oversized bodies feed a separate per-IP
        abuse limiter. Request bodies are capped at 64 KiB.

        On success the public key is appended to the authorized-keys file and
        the key registry is hot-reloaded. The new key is immediately active.
      tags: [Auth]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [enrollment_token, public_key]
              properties:
                enrollment_token:
                  type: string
                  description: The pre-configured enrollment token.
                  example: "a3f2b1c9d8e7f6a4b5c6d7e8f9a0b1c2"
                public_key:
                  type: string
                  description: >
                    Base64 (standard encoding) of the raw 32-byte Ed25519
                    public key to register.
                  example: "AAAAC3NzaC1lZDI1NTE5AAAAIB3..."
      responses:
        "200":
          description: Key enrolled successfully.
          content:
            application/json:
              schema:
                type: object
                required: [key_id]
                properties:
                  key_id:
                    type: string
                    description: hex(SHA-256(pubkey)[:8]) — the Key-ID for subsequent requests.
                    example: "4a3f2b1c9d8e7f6a"
                  comment:
                    type: string
                    description: Comment assigned to the enrolled key.
                    example: "enrolled:4a3f2b1c9d8e7f6a"
        "400":
          description: Invalid request body, bad base64, or wrong key length.
        "401":
          description: Wrong enrollment token, or token already burned.
        "413":
          description: Request body exceeds the 64 KiB enrollment limit.
        "405":
          description: Method not allowed (POST required).
        "429":
          description: Rate limit exceeded.
        "500":
          description: Could not write to the authorized_keys file.

tags:
  - name: Health
    description: Health check endpoints (no auth).
  - name: Agent
    description: Portwing agent metadata endpoints.
  - name: Auth
    description: Ed25519 key enrollment (Model C bootstrap).
  - name: Compose
    description: Docker Compose lifecycle management.
  - name: Metrics
    description: Prometheus-format host and agent metrics.
  - name: MCP
    description: Read-only Model Context Protocol server (`/_portwing/mcp`).
  - name: Drydock Compat
    description: Drydock-compatible REST and SSE endpoints (`/api/*`).
  - name: Generic
    description: >
      Standalone headless management API (`/api/v1/*`). Active when
      `ADAPTER=generic`. No external controller required.
  - name: Docker Proxy
    description: Transparent proxy to the local Docker Engine API.