openapi: 3.1.0

info:
  title: Node-RED AI Access Plugin API
  version: 0.1.1
  summary: Temporary, owner-approved Node-RED access for AI clients
  description: |
    REST surface exposed by the `@com55/node-red-ai-access` Node-RED plugin
    under the editor admin root (respects `httpAdminRoot`).

    **Git mental model:** a proposal is like a pull request. Human approve =
    merge; reject = close; withdraw = the author closes their own PR. If `rev` /
    `expectedRev` does not match, treat it as a conflict: re-read the flow,
    rebase the edit, and resubmit. Every access link can see all proposals
    (`mine: true|false`).

    ## Base path

    All routes are under `{httpAdminRoot}/mcp/api/v1`
    (for example `/mcp/api/v1` when `httpAdminRoot` is `/`).

    ## Quick start for access-link clients

    ### Self-contained GET link (no headers)

    Prefer this when the AI can only issue HTTP GET (no `Authorization` header,
    no MCP). An admin creates a **get_link** token via `POST /links` (this
    OpenAPI document); the create response returns `url` like
    `http(s)://{host}{httpAdminRoot}/mcp/a/{token}` (default TTL **4h**).

    **GET `/mcp/a/<token>/…` never mints tokens.** There is no link-create
    operation under the get-link surface (no `POST …/links`). Attempted mint
    paths return **403** `link_create_not_supported`. Only admins with `*`
    may create tokens on `POST /mcp/api/v1/links`.

    1. `GET {url}` — markdown docs (workflow, exact paths, errors, limits),
       served by default as `text/html; charset=utf-8` (the same text escaped in
       a `<pre>`), because some AI web fetchers only read HTML. Every response
       under `/mcp/a/<token>` follows the same rule: `Accept: text/markdown`
       or `application/json`, or `?format=md` / `?format=json`, return the
       raw representation; `Accept: text/plain` returns the raw text as
       `text/plain` (`Vary: Accept`).
    2. `GET {url}/status`, `/flows`, …
    3. Layered read (prefer before loading whole tabs):
       `GET {url}/flows/{id}?summary=1` → `GET {url}/search?q=&flow=` →
       `GET {url}/nodes/{id}` / `…/nodes/{id}/field/{name}?lines=A-B`.
    4. Small string edits (preferred): `GET {url}/propose?flow=&rev=&node=&field=&find=&replace=`
       (`occurrence` 1-based if find is not unique). Same as patch
       `{op:'replace_text',...}` / REST·MCP `payload.nodes`.
    5. Whole property: `GET {url}/propose?flow=&rev=&node=&set.<prop>=&summary=`
    6. Multi-node / add / remove / replace_text: `GET {url}/propose?flow=&rev=&patch=<base64url JSON>`
       where the JSON is `nodes:[{op:'set'|'add'|'remove'|'replace_text',...}]` or a
       full `replace_flow` document (URL soft-cap ~8KB → use chunked drafts;
       prefer ~4–5 KB raw chunks; base64url adds ~33%).
    7. Chunked drafts: `…/draft/new` → `…/draft/{id}/append?seq=&data=` →
       `…/draft/{id}/submit?sha256=` (30 min expiry, 1.5MB **decoded** bytes;
       field mode validates node/field at `draft/new`; `mode=json` may add nodes).
       Last resort if still too large: placeholder propose → human deploy → user pastes
       full content in the editor (not reviewed via diff).
    8. Human approves on `/mcp`. JSON uses `Cache-Control: no-store`.
       Unknown paths under `/mcp/a/*` return JSON `not_found` (never echo the token).

    Recommended edit loop: summary → search → read a line range →
    `replace_text` → propose.

    ### Bearer REST (clients that can send headers)

    Plain HTTP AI clients (no MCP required) can also use an access-link token
    and this REST API:

    1. Ask the user for an access link from the `/mcp` admin page (**Access
       links** → Create). Prefer the copy-link output (full GET `url` + Bearer
       token + docs hint).
    2. Discover endpoints (no auth): `GET {httpAdminRoot}/mcp/api/v1`.
    3. Send `Authorization: Bearer <token>` on every authenticated call.
    4. Read flows lightly: `GET /flows`, then `GET /flows/{id}?summary=1`,
       `GET /search?q=`, `GET /nodes/{id}`, `GET /nodes/{id}/field/{name}?lines=A-B`
       (full `GET /flows/{id}` still available; response always includes
       `flow.type`, defaulting to `tab`).
    5. Submit a proposal. Prefer targeted `replace_text` for small string edits:

    ```json
    {
      "type": "replace_flow",
      "expectedRev": "<rev from GET /flows or /flows/{id}>",
      "payload": {
        "flowId": "tab1",
        "nodes": [
          {
            "op": "replace_text",
            "node": "n1",
            "field": "template",
            "find": "Hello",
            "replace": "Hi"
          }
        ]
      }
    }
    ```

    Or a full tab via `payload.flow` (from `GET /flows/{id}`).

    Missing tokens return **401** `access_link_missing`; invalid/expired/revoked
    tokens return **401** `access_link_invalid`. Both tell you to ask the user
    for a new link. OpenAPI: `GET /openapi.yaml` (or `GET /openapi.json`). MCP (optional):
    `POST {httpAdminRoot}/mcp/rpc` with the same Bearer token.

    ## MCP JSON-RPC

    AI clients may also use MCP Streamable HTTP at `{httpAdminRoot}/mcp/rpc`
    with the same access-link Bearer token. Tools mirror the AI-facing REST
    operations (`get_status`, `list_flows`, `get_flow` with optional `summary`,
    `get_node`, `get_node_field`, `search_flows`, `list_node_types`,
    `get_node_type`, `search_palette`, `submit_proposal`, `list_proposals`
    (alias `list_my_proposals`),
    `get_proposal`, `get_proposal_diff`). Approve/reject/link management stay on
    this REST API and the `/mcp` admin page. This OpenAPI document covers the
    REST surface only.

    ## Authentication

    - **Admin session** — Node-RED `adminAuth` cookie/session. Users with
      `read` may view status, flows, proposals, and logs. Users with `*` may
      also manage access links and approve/reject proposals.
    - **Access-link Bearer token** — temporary token minted by an admin with
      `*` via `POST /links` (never under `/mcp/a`). Each token has a
      `kind` (`get_link` | `rest` | `mcp`) and only works on that surface.
      AI clients send `Authorization: Bearer <token>` for **rest** (this API)
      or **mcp** (`/mcp/rpc`). Tokens are in-memory only (lost on restart).

    When an access-link token is **missing**, AI-facing routes return **401**
    with `code: access_link_missing`. When the token is **invalid**, expired,
    revoked, or cleared by a restart, they return **401** with
    `code: access_link_invalid`. Both include `WWW-Authenticate: Bearer` and a
    message that tells the AI to ask the user for a new access link.
    When the token kind does not match the surface, routes return **403**
    with `code: wrong_token_kind` (`expectedKind` / `actualKind`).

    ## Admin page (`GET /mcp`)

    The HTML shell is served **without** adminAuth so the browser can read the
    Node-RED editor token from `localStorage` (editors do not use cookies) and
    call APIs with `Authorization: Bearer`. All data and mutating actions stay
    behind `needsPermission` / access-link checks.

    ## Size limits

    Proposal JSON is capped at **1_500_000 bytes** (`MAX_PROPOSAL_JSON_BYTES` /
    ~1.5MB) on **every** channel: GET propose/drafts, REST `POST /proposals`,
    and MCP `submit_proposal`. Oversized proposal JSON or audit append payloads
    return **413** with `code: payload_too_large` (never silently truncate).
    Malformed JSON bodies return **400** JSON (`code: invalid_json` on REST;
    JSON-RPC `-32700` Parse error on `/mcp/rpc`) — never HTML stack traces.
    Unauthenticated admin API calls return JSON `{ code: auth_required }`
    (not plain-text `Unauthorized` from `needsPermission`).
    The MCP endpoint shares the same limits, rate limiting, and audit logging
    as REST.

    ## Proposal visibility and conflicts

    Every access-link token can **list and read all proposals**. Each item
    includes `mine: true|false` for the caller. Filter with `?mine=true`,
    `?status=`, and/or `?flowId=` (REST/GET), or MCP `list_proposals` with the
    same fields. Paginate with `limit`/`offset`; every channel returns the
    same pagination fields: `total` (matches before paging), `offset`, `limit`
    (when given), `hasMore`, and `nextOffset` (only when `hasMore`). Pagination
    is offset-based (no cursor). MCP keeps `list_my_proposals` as an alias.

    Invalid filters are rejected (never clamped or ignored) with
    `400 invalid_filter`, naming `parameter` and `allowed`: `status` must be a
    proposal status, `limit` an integer 1–200, `offset` an integer ≥ 0, and
    `mine` one of true/false/1/0. MCP argument errors use the same JSON body
    (`invalid_filter` for list filters, `invalid_arguments` otherwise).

    On submit and on **get** of a **pending** proposal, responses may include
    `conflictingProposals` (same-`expectedRev` peers or true node/field overlaps)
    with optional `overlappingNodeIds` / `overlappingFields`. List endpoints
    omit `conflictingProposals`. Submit, get, and list responses include
    `autoClosedCount` when that request auto-closed pending proposals as
    `expired` (omitted when zero).

    Validation: a single error returns its own code (e.g. `404 node_not_found`);
    several errors return `400 validation_failed` with message
    `N validation errors` and every entry in `errors[]`. Duplicate node ids in a
    full tab or batch return `duplicate_node_id`.

    Pending proposals whose `expectedRev` no longer matches the live flow rev
    are auto-closed as `expired`. When a proposal is approved, other pending
    proposals on the same flow become `superseded`. Closed proposals are never
    conflicts.

    ## Withdraw

    The creating access link may withdraw its own pending proposal
    (`POST /proposals/{id}/withdraw`, GET `…/proposals/{id}/withdraw?confirm=1`,
    or MCP `withdraw_proposal`). GET withdraw requires `confirm=1` so prefetchers
    cannot trigger it. Status becomes `withdrawn` (separate from admin
    `rejected`).

    ## Known issues

    - **Rate limits are per token (and per IP).** Each access-link token has its
      own token bucket. Several tokens can each use the full per-token limit at
      the same time; the shared IP bucket still applies across them.
    - **`RateLimit-*` headers describe the per-token bucket** on requests that
      carry a Bearer or path token (`RateLimit-Policy: 300;w=60` by default):
      that is the bucket being consumed and normally the stricter one. Requests
      without a token report the per-IP bucket (`600;w=60`). Both buckets are
      enforced; either can return `429 rate_limited`.

  contact:
    name: com55
    url: https://github.com/com55/node-red-ai-access
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: /mcp/api/v1
    description: Relative to Node-RED httpAdminRoot (default `/`)

tags:
  - name: Status
  - name: Access links
  - name: Flows
  - name: Node types
  - name: Proposals
  - name: Audit log
  - name: Spec

paths:
  /:
    get:
      tags: [Spec]
      summary: Discovery index (no auth)
      description: |
        Unauthenticated JSON index listing auth scheme, OpenAPI URL, MCP
        endpoint, and available REST paths. Intended for plain HTTP AI clients.
        Advertises that token minting is admin `POST /links` only — not under
        GET `/mcp/a/<token>`.
      operationId: getDiscoveryIndex
      security: []
      responses:
        '200':
          description: Discovery payload
          content:
            application/json:
              schema:
                type: object
                required: [ok, auth, openapi, mcp, endpoints]
                properties:
                  ok:
                    type: boolean
                  name:
                    type: string
                  version:
                    type: string
                  auth:
                    type: object
                    required: [scheme, header]
                    properties:
                      scheme:
                        type: string
                        const: Bearer
                      header:
                        type: string
                        example: 'Authorization: Bearer <token>'
                      description:
                        type: string
                      tokenKinds:
                        type: array
                        items:
                          $ref: '#/components/schemas/AccessLinkKind'
                      mint:
                        type: object
                        description: Where admins create tokens (not under get-link)
                        properties:
                          path:
                            type: string
                            const: /links
                          method:
                            type: string
                            const: POST
                          auth:
                            type: string
                            const: admin
                          note:
                            type: string
                  openapi:
                    type: string
                  openapiJson:
                    type: string
                  mcp:
                    type: string
                  apiBase:
                    type: string
                  getLink:
                    type: object
                    description: |
                      Self-contained GET surface metadata. `canMintTokens` is
                      always false — no link-create under `/mcp/a`.
                    properties:
                      base:
                        type: string
                      canMintTokens:
                        type: boolean
                        const: false
                      note:
                        type: string
                  endpoints:
                    type: array
                    items:
                      type: object
                      required: [method, path, auth, summary]
                      properties:
                        method:
                          type: string
                        path:
                          type: string
                        auth:
                          type: string
                        summary:
                          type: string

  /openapi.yaml:
    get:
      tags: [Spec]
      summary: OpenAPI document (YAML)
      operationId: getOpenApiYaml
      security: []
      responses:
        '200':
          description: OpenAPI 3.1 YAML for this API
          content:
            application/yaml:
              schema:
                type: string

  /openapi.json:
    get:
      tags: [Spec]
      summary: OpenAPI document (JSON)
      description: The same specification as `/openapi.yaml`, converted to JSON.
      operationId: getOpenApiJson
      security: []
      responses:
        '200':
          description: OpenAPI 3.1 JSON for this API
          content:
            application/json:
              schema:
                type: object

  /status:
    get:
      tags: [Status]
      summary: Plugin status
      description: |
        Accepts an **admin session** or a valid **access-link Bearer**.
        Access-link callers receive `permission: null` and a `caller` object
        with link label, expiry, permissions, and base URLs.
      operationId: getStatus
      security:
        - AdminSession: []
        - AccessLinkBearer: []
      responses:
        '200':
          description: Status payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /settings:
    get:
      tags: [Status]
      summary: Get effective AI Access settings
      description: |
        Returns effective settings with precedence metadata
        (`disk` → `settings.js` → built-in defaults). Admin `read` or `*`.
        `read` users get `canEdit: false`; `*` can PUT.
      operationId: getAiAccessSettings
      security:
        - AdminSession: []
      responses:
        '200':
          description: Effective settings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AiAccessSettingsResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
    put:
      tags: [Status]
      summary: Update AI Access settings (persist to disk)
      description: |
        Requires `*`. Writes `<userDir>/.ai-access/settings.json` and applies
        immediately (no restart). Partial body merges into existing disk
        overrides.
      operationId: putAiAccessSettings
      security:
        - AdminSession: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AiAccessSettingsPatch'
      responses:
        '200':
          description: Updated effective settings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AiAccessSettingsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'

  /links:
    get:
      tags: [Access links]
      summary: List active access links
      description: Requires full admin permission (`*`).
      operationId: listLinks
      security:
        - AdminSession: []
      responses:
        '200':
          description: Active links (no raw tokens)
          content:
            application/json:
              schema:
                type: object
                required: [links]
                properties:
                  links:
                    type: array
                    items:
                      $ref: '#/components/schemas/AccessLinkPublic'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    post:
      tags: [Access links]
      summary: Create an access link
      description: |
        Requires full admin permission (`*`). This is the **only** link-create
        operation — GET `/mcp/a/<token>/…` has no mint/create-link route.
        The raw `token` is returned **once** in this response. For
        `kind=get_link`, a self-contained `url` is included for GET-only
        clients at `/mcp/a/<token>`. For `rest` / `mcp`, `url` is omitted
        (use the Bearer token on the matching surface). Default TTL is
        14400 seconds (4h). Caps: `get_link` ≤ 24h; `rest` / `mcp` ≤ 30d
        (over-cap → **400**). Max active links defaults to 10
        (`aiAccess.maxActiveLinks`).
      operationId: createLink
      security:
        - AdminSession: []
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateLinkRequest'
      responses:
        '201':
          description: Link created (includes token)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessLinkCreated'
        '400':
          description: |
            Invalid body — including unknown `kind`
            (`code: invalid_link_kind`).
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/InvalidLinkKindError'
                  - $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          description: Active link limit reached
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /links/{id}:
    delete:
      tags: [Access links]
      summary: Revoke an access link
      operationId: revokeLink
      security:
        - AdminSession: []
      parameters:
        - $ref: '#/components/parameters/LinkId'
      responses:
        '200':
          description: Link revoked
          content:
            application/json:
              schema:
                type: object
                required: [revoked, link]
                properties:
                  revoked:
                    type: boolean
                    const: true
                  link:
                    $ref: '#/components/schemas/AccessLinkPublic'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  /flows:
    get:
      tags: [Flows]
      summary: List flows with revision
      description: |
        AI clients and admins with at least `read` may call this.
        Use `rev` as `expectedRev` when submitting a `replace_flow` proposal.
      operationId: listFlows
      security:
        - AccessLinkBearer: []
        - AdminSession: []
      responses:
        '200':
          description: Flat flows array plus global revision
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlowsSnapshot'
        '401':
          $ref: '#/components/responses/AccessLinkUnauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '502':
          $ref: '#/components/responses/BadGateway'

  /flows/{id}:
    get:
      tags: [Flows]
      summary: Get one flow (tab) with revision
      description: |
        Returns the nested tab shape used as the basis for a `replace_flow`
        proposal payload. Pass `summary=1` for a lightweight node list
        (`id`/`type`/`name`/`wires` + per-node `bytes`, no field contents).
        Always re-read before proposing so `expectedRev` matches the current
        revision.
      operationId: getFlow
      security:
        - AccessLinkBearer: []
        - AdminSession: []
      parameters:
        - $ref: '#/components/parameters/FlowId'
        - name: summary
          in: query
          required: false
          description: When `1`/`true`/`yes`, return a node summary without field bodies
          schema:
            type: string
            enum: ['1', 'true', 'yes']
      responses:
        '200':
          description: Nested flow tab plus revision, or summary shape when `summary=1`
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/FlowSnapshot'
                  - $ref: '#/components/schemas/FlowSummary'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/AccessLinkUnauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '502':
          $ref: '#/components/responses/BadGateway'

  /nodes/{id}:
    get:
      tags: [Flows]
      summary: Get one full node
      description: |
        Returns one node plus owning `flowId` when known. Optional `flow`
        scopes the lookup to a tab.
      operationId: getNode
      security:
        - AccessLinkBearer: []
        - AdminSession: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: flow
          in: query
          required: false
          description: Optional tab id to scope the lookup
          schema:
            type: string
      responses:
        '200':
          description: One node with revision
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NodeSnapshot'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/AccessLinkUnauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '502':
          $ref: '#/components/responses/BadGateway'

  /nodes/{id}/field/{name}:
    get:
      tags: [Flows]
      summary: Get one node string field
      description: |
        Returns one string field. Optional `lines=A-B` (1-based inclusive)
        returns a slice; response always includes `totalLines` and `bytes`.
      operationId: getNodeField
      security:
        - AccessLinkBearer: []
        - AdminSession: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: name
          in: path
          required: true
          schema:
            type: string
        - name: lines
          in: query
          required: false
          description: Optional 1-based line range `A` or `A-B`
          schema:
            type: string
            pattern: '^[0-9]+(-[0-9]+)?$'
        - name: flow
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Field value (possibly sliced) with metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NodeFieldSnapshot'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/AccessLinkUnauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '502':
          $ref: '#/components/responses/BadGateway'

  /search:
    get:
      tags: [Flows]
      summary: Text search across string fields
      description: |
        Case-sensitive substring search. Hits include node id, field, line
        numbers, and a short snippet. Results are capped (default 50);
        `truncated:true` when the cap is hit. Optional `flow` scopes to one tab.
      operationId: searchFlows
      security:
        - AccessLinkBearer: []
        - AdminSession: []
      parameters:
        - name: q
          in: query
          required: true
          schema:
            type: string
            minLength: 1
        - name: flow
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Search hits
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResult'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/AccessLinkUnauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '502':
          $ref: '#/components/responses/BadGateway'

  /node-types:
    get:
      tags: [Node types]
      summary: List installed palette node types
      description: |
        Returns installed Node-RED palette types (`type`, `module`, optional
        `category`, `description`, `enabled`, `version`, `setId`). Optional
        `q` filters type/module/category/description (case-insensitive).
        Results are capped; response includes `total` and `truncated`.
      operationId: listNodeTypes
      security:
        - AccessLinkBearer: []
        - AdminSession: []
      parameters:
        - name: q
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Installed node types
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NodeTypeListResult'
        '401':
          $ref: '#/components/responses/AccessLinkUnauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '502':
          $ref: '#/components/responses/BadGateway'

  /node-types/{type}:
    get:
      tags: [Node types]
      summary: Get one installed node type
      description: |
        Detail for one type: `properties`/`defaults`, `inputs`/`outputs`,
        `requiredConfigNodeTypes`, short `help`, plus `category`/`module`/`color`
        when available. **404** `node_type_not_found` when unknown (may include
        `nearest` suggestions).
      operationId: getNodeType
      security:
        - AccessLinkBearer: []
        - AdminSession: []
      parameters:
        - name: type
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Node type detail
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NodeTypeDetail'
        '401':
          $ref: '#/components/responses/AccessLinkUnauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '502':
          $ref: '#/components/responses/BadGateway'

  /palette/search:
    get:
      tags: [Node types]
      summary: Search Node-RED catalogue (recommend only)
      description: |
        Searches `catalogue.nodered.org` (cached ~1h). Returns modules with
        `installed` boolean. **Recommend only — never installs.** Ask the user
        to install via Manage palette, then recheck `/node-types`. Response
        always includes a `hint` stating this.
      operationId: searchPalette
      security:
        - AccessLinkBearer: []
        - AdminSession: []
      parameters:
        - name: q
          in: query
          required: true
          schema:
            type: string
            minLength: 1
      responses:
        '200':
          description: Catalogue search hits
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaletteSearchResult'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/AccessLinkUnauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '502':
          $ref: '#/components/responses/BadGateway'

  /proposals:
    get:
      tags: [Proposals]
      summary: List proposals
      description: |
        Admins see all proposals. Access-link clients also see **all** proposals,
        each marked `mine: true|false`. Filter with `?mine=true` (own only) or
        `?mine=false` (only other links' proposals), `?status=` (one or more
        statuses, comma-separated `?status=pending,superseded` or repeated
        `?status=pending&status=expired`; any unknown value is `invalid_filter`),
        and/or `?flowId=`. Other filter parameters may appear at most once. Paginate with `?limit=` (1–200) and `?offset=`; responses
        always include `total` (count after filters, before pagination). Pending
        items may include `conflictingProposals` on get/submit (not on list).
      operationId: listProposals
      security:
        - AccessLinkBearer: []
        - AdminSession: []
      parameters:
        - name: mine
          in: query
          required: false
          schema:
            type: boolean
          description: >-
            Access-link only. true (or 1) returns only this token's proposals;
            false (or 0) returns only proposals created by other links.
        - name: status
          in: query
          required: false
          style: form
          explode: true
          schema:
            type: array
            items:
              $ref: '#/components/schemas/ProposalStatus'
          description: >-
            One or more statuses. Repeat the parameter or pass a comma-separated
            list. Any invalid value returns 400 invalid_filter.
        - name: flowId
          in: query
          required: false
          schema:
            type: string
          description: Filter by payload.flowId
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 200
          description: Page size. Omit to return all matching proposals.
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
          description: Skip this many filtered results
        - $ref: '#/components/parameters/ProposalInclude'
        - $ref: '#/components/parameters/ProposalIncludePayload'
      responses:
        '200':
          description: Proposal list
          content:
            application/json:
              schema:
                type: object
                required: [proposals, total]
                properties:
                  proposals:
                    type: array
                    items:
                      $ref: '#/components/schemas/Proposal'
                  total:
                    type: integer
                    description: Count after filters, before limit/offset
                  limit:
                    type: integer
                    description: Echo of requested limit when pagination is used
                  offset:
                    type: integer
                    description: Echo of offset when pagination is used
        '401':
          $ref: '#/components/responses/AccessLinkUnauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    post:
      tags: [Proposals]
      summary: Create a replace_flow proposal
      description: |
        **Access-link Bearer only.** Submits a proposed replacement for one
        flow tab. Does not mutate Node-RED until an admin with `*` approves.

        Include `expectedRev` (preferred; `expected_rev` accepted as alias)
        from the latest `GET /flows` or `GET /flows/{id}` response. The live
        flow revision is checked **at submit time** (**409**
        `version_mismatch` if stale). On approve, a stale revision marks the
        proposal `rejected` with a resubmit message (no deploy).

        Optional `title` (≤80 chars) is stored as a human-friendly label; when
        omitted it is auto-generated from the change set. Responses always
        include `title`, `displayName` (`title ·` server-local submitted time
        with offset), absolute `reviewUrl`, and relative `reviewPath`. AI clients
        should cite `displayName` + `reviewUrl` to users (not the raw id).

        `payload.flow` must be a tab object (`id`, `type`, `label?`, `nodes[]`,
        optional `configs[]`). Payloads over 1_500_000 bytes return **413**.
        Unknown palette `node.type` values return **400** `unknown_node_type`
        with `nearest` suggestions — call `/node-types` or `/palette/search`
        and ask the user to install via Manage palette (this API never installs).

        Responses are **lean** by default (no `payload` / `baseFlow`). Pass
        `?include=payload,baseFlow` or `?include_payload=true` to include them
        (same as MCP `include_payload`).
      operationId: createProposal
      security:
        - AccessLinkBearer: []
      parameters:
        - $ref: '#/components/parameters/ProposalInclude'
        - $ref: '#/components/parameters/ProposalIncludePayload'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateProposalRequest'
      responses:
        '201':
          description: Proposal created (`pending`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Proposal'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/AccessLinkUnauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/VersionConflict'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'

  /proposals/{id}:
    get:
      tags: [Proposals]
      summary: Get one proposal
      operationId: getProposal
      security:
        - AccessLinkBearer: []
        - AdminSession: []
      parameters:
        - $ref: '#/components/parameters/ProposalId'
        - $ref: '#/components/parameters/ProposalInclude'
        - $ref: '#/components/parameters/ProposalIncludePayload'
      responses:
        '200':
          description: Proposal
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Proposal'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/AccessLinkUnauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  /proposals/{id}/diff:
    get:
      tags: [Proposals]
      summary: Diff a proposal against the current flow
      description: |
        Compares the proposal payload to the **base flow snapshot** stored at
        submit (`baseFlow` at `expectedRev`) — what the AI actually changed —
        not the live editor flow. Returns counts of added / removed / modified
        nodes. Added/removed nodes are single presence blocks with properties
        (long text fields listed for expandable UI). Modified nodes include
        line-level diffs for text fields such as `func` and `template`.

        `baseRevStale` is true only for **pending** proposals when
        `expectedRev` does not match the live revision (approve would fail).
        Approved/rejected/failed proposals never set `baseRevStale`. When
        pending and stale, `vsCurrent` optionally includes proposal-vs-live
        sections for review.

        Admins with `read` can diff any proposal. Access-link clients can only
        diff proposals they created.
      operationId: getProposalDiff
      security:
        - AccessLinkBearer: []
        - AdminSession: []
      parameters:
        - $ref: '#/components/parameters/ProposalId'
      responses:
        '200':
          description: Proposal diff
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProposalDiff'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/AccessLinkUnauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  /proposals/{id}/approve:
    post:
      tags: [Proposals]
      summary: Approve and deploy a proposal
      description: |
        Requires full admin permission (`*`). Deploys via the FlowAdapter.
        Optional body `deploymentType`: `nodes` (default from settings),
        `flows`, or `full`.

        Revision conflict: proposal is marked `rejected` with a resubmit
        message (HTTP 200 with `status: rejected`). Other deploy errors mark
        it `failed`. Concurrent approve of the same id returns 409.
      operationId: approveProposal
      security:
        - AdminSession: []
      parameters:
        - $ref: '#/components/parameters/ProposalId'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApproveProposalRequest'
      responses:
        '200':
          description: Updated proposal (`approved`, `rejected`, or `failed`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Proposal'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: Not pending, or approve already in progress
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'

  /proposals/{id}/reject:
    post:
      tags: [Proposals]
      summary: Reject a proposal
      description: Requires full admin permission (`*`). Never mutates flows.
      operationId: rejectProposal
      security:
        - AdminSession: []
      parameters:
        - $ref: '#/components/parameters/ProposalId'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RejectProposalRequest'
      responses:
        '200':
          description: Proposal rejected
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Proposal'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: Proposal is not pending
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'

  /proposals/{id}/withdraw:
    post:
      tags: [Proposals]
      summary: Withdraw own pending proposal
      description: |
        Access-link Bearer only. Withdraws a **pending** proposal created by
        this token. Status becomes `withdrawn` (not `rejected`). Optional
        JSON body `{ "reason": "…" }`.
      operationId: withdrawProposal
      security:
        - AccessLinkBearer: []
      parameters:
        - $ref: '#/components/parameters/ProposalId'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                reason:
                  type: string
      responses:
        '200':
          description: Proposal withdrawn
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Proposal'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Not owned by this access link
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: Proposal is not pending
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'

  /logs:
    get:
      tags: [Audit log]
      summary: List recent audit log entries
      description: Admin session with at least `read`. Newest entries first.
      operationId: listLogs
      security:
        - AdminSession: []
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 500
            default: 100
      responses:
        '200':
          description: Audit entries
          content:
            application/json:
              schema:
                type: object
                required: [logs]
                properties:
                  logs:
                    type: array
                    items:
                      $ref: '#/components/schemas/AuditEntry'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

components:
  securitySchemes:
    AdminSession:
      type: apiKey
      in: cookie
      name: node-red-session
      description: |
        Node-RED editor admin session established via `adminAuth`.
        Equivalent browser cookie/session auth used by the `/mcp` admin UI.
    AccessLinkBearer:
      type: http
      scheme: bearer
      bearerFormat: access-link
      description: |
        Temporary access-link token from `POST /links` (`token` field).
        On 401, ask the user for a new access link.

  parameters:
    LinkId:
      name: id
      in: path
      required: true
      schema:
        type: string
    FlowId:
      name: id
      in: path
      required: true
      schema:
        type: string
    ProposalId:
      name: id
      in: path
      required: true
      schema:
        type: string
        pattern: '^prop-'
    ProposalInclude:
      name: include
      in: query
      required: false
      schema:
        type: string
      description: |
        Comma-separated fields to include on lean proposal responses.
        Supported keys: `payload`, `baseFlow`. Default is lean (omit both).
        Example: `include=payload,baseFlow`.
    ProposalIncludePayload:
      name: include_payload
      in: query
      required: false
      schema:
        type: boolean
      description: |
        Alias for MCP clients: when `true` / `1` / `yes`, includes both
        `payload` and `baseFlow` (same as `include=payload,baseFlow`).

  responses:
    BadRequest:
      description: Invalid request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Admin authentication required or insufficient permissions
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    AccessLinkUnauthorized:
      description: |
        Missing (`code: access_link_missing`), wrong scheme such as Basic
        (`code: bearer_scheme_required`), known-expired
        (`code: token_expired`), or invalid/revoked/pre-restart
        (`code: access_link_invalid`) access link. Includes
        `WWW-Authenticate: Bearer` (on every channel, including GET links).
        `token_expired` also includes `expiredAt` and `accessLinksUrl` (the
        `/mcp` page's Access links section, where the user creates a new link). Message instructs the AI to ask the user
        for a new access link (or to use Bearer, not Basic).
      headers:
        WWW-Authenticate:
          schema:
            type: string
          description: 'Bearer realm="node-red-ai-access", charset="UTF-8"'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            missing:
              value:
                error: 'Access link Bearer token is missing. Ask the user for a new access link and send Authorization: Bearer <token>.'
                code: access_link_missing
            basicScheme:
              value:
                error: 'Authorization must use the Bearer scheme (Authorization: Bearer <access-link-token>), not Basic. Ask the user for a new access link.'
                code: bearer_scheme_required
            expired:
              value:
                error: 'Access link token has expired. Ask the user for a new access link.'
                code: token_expired
                expiredAt: '2026-01-01T12:00:00.000Z'
                accessLinksUrl: 'https://node-red.example/mcp#links'
                hint: 'Ask the user to create a new access link in Node-RED on the /mcp page → Access links (https://node-red.example/mcp#links).'
            askForNewLink:
              value:
                error: 'Access link is invalid, revoked, or no longer available after a restart. Ask the user for a new access link.'
                code: access_link_invalid
    VersionConflict:
      description: |
        `expectedRev` does not match the current flow revision
        (`code: version_mismatch`). Re-read flows and resubmit.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/VersionConflictError'
    Forbidden:
      description: |
        AI features disabled, full (`*`) permission required, or access-link
        token kind mismatch (`code: wrong_token_kind` with `expectedKind` /
        `actualKind`).
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/WrongTokenKindError'
              - $ref: '#/components/schemas/Error'
          examples:
            wrongTokenKind:
              value:
                error: 'Access link kind mismatch: expected rest, got get_link'
                code: wrong_token_kind
                expectedKind: rest
                actualKind: get_link
                hint: 'This REST endpoint requires a rest token. This token is kind=get_link — ask the user for a REST Bearer token (kind=rest).'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    LinkCreateNotSupported:
      description: |
        Attempted to create/list/revoke access links under the GET
        `/mcp/a/<token>` surface (`code: link_create_not_supported`).
        GET links cannot mint tokens — use admin `POST /links` instead.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/LinkCreateNotSupportedError'
    PayloadTooLarge:
      description: Proposal JSON or audit append exceeds size cap
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PayloadTooLargeError'
    UnsupportedMediaType:
      description: |
        Request body Content-Type is not `application/json`
        (`code: unsupported_media_type`). Send
        `Content-Type: application/json` with a JSON body.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            notJson:
              value:
                error: 'Content-Type must be application/json'
                code: unsupported_media_type
                hint: 'Send Content-Type: application/json with a JSON body.'
    BadGateway:
      description: Upstream Node-RED runtime/Admin API failure
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

  schemas:
    Error:
      type: object
      required: [error, code]
      properties:
        error:
          type: string
        code:
          type: string
          description: Machine-readable error code — see `ErrorCode` and docs/errors.md.
        hint:
          type: string

    # BEGIN GENERATED ERROR CODES (src/plugin/error-registry.ts)
    ErrorCode:
      type: string
      description: |
        Machine-readable `code` on JSON error bodies. See docs/errors.md.

        - `access_link_missing` (401): No Bearer / path token
        - `bearer_scheme_required` (401): Auth used Basic (or non-Bearer)
        - `token_expired` (401): Known token past `expiresAt` (body includes `expiredAt` and `accessLinksUrl`)
        - `access_link_invalid` (401): Unknown, revoked, or cleared after restart
        - `wrong_token_kind` (403): Token kind does not match this surface
        - `ai_features_disabled` (403): Plugin AI features off
        - `auth_required` (401): Admin session required
        - `insufficient_permissions` (403): Admin lacks required scope
        - `invalid_link_kind` (400): Unknown `kind` on create
        - `invalid_ttl` (400): `ttlSeconds` is zero, negative, not a number, or over the cap for the kind
        - `access_link_limit` (409): Too many active links
        - `access_link_not_found` (404): Unknown link id on revoke
        - `link_create_not_supported` (403): Attempted mint under a GET link
        - `rate_limited` (429): Per-IP or per-token limit
        - `payload_too_large` (413): Body / proposal over ~1.5MB
        - `invalid_json` (400): Malformed JSON body
        - `unsupported_media_type` (415): POST body is not `application/json`
        - `url_too_long` (414): GET URL over soft cap (~8KB)
        - `not_found` (404): Unknown path or resource
        - `missing_query` (400): Required search `q` missing
        - `invalid_filter` (400): Invalid list filter (`status`, `limit`, `offset`, `mine`); body names `parameter` and `allowed`
        - `invalid_arguments` (400): MCP tool arguments failed schema validation; body names `parameter`
        - `invalid_diff_format` (400): Unknown `format` on proposal diff
        - `confirm_required` (400): GET withdraw without `confirm=1`
        - `missing_expected_rev` (400): Proposal submitted without `expectedRev` / `rev`
        - `version_mismatch` (409): Stale `rev` / `expectedRev`
        - `proposal_not_found` (404): Unknown proposal id
        - `proposal_not_pending` (409): Action needs a pending proposal
        - `proposal_not_owned` (403): Withdraw of another token’s proposal
        - `validation_failed` (400): Several validation errors at once (message `N validation errors`)
        - `duplicate_node_id` (400): The same node id appears more than once in a full tab or batch
        - `missing_node_id` (400): Node / op without an id
        - `missing_node_type` (400): Node without a `type`
        - `invalid_node_type` (400): `type` is not a string
        - `invalid_nodes` (400): `flow.nodes` / `flow.configs` not an array
        - `invalid_node` (400): Node entry is not an object
        - `invalid_wires` (400): Bad wires shape, missing target, or more ports than outputs
        - `z_mismatch` (400): Node `z` differs from the flow id
        - `node_already_exists` (400): `add` op for an id already in the flow
        - `protected_property` (400): Tried to change id / type / z
        - `node_not_found` (404): Unknown node (single error only; several errors → `validation_failed`)
        - `field_not_found` (404): Unknown field on a node
        - `text_not_found` (400): `replace_text` find had no match
        - `ambiguous_match` (409): `replace_text` matched more than once
        - `unknown_node_type` (400): Proposal uses a type that is not installed
        - `node_type_not_found` (404): Unknown type on node-types detail
        - `chunk_conflict` (409): Same draft seq re-sent with different data
        - `missing_chunks` (400): Draft submit with gaps in seq
        - `draft_hash_mismatch` (400): Draft sha256 does not match assembled bytes
        - `upstream_error` (502): Node-RED runtime/flows error
        - `internal_error` (500): Unexpected server error
      enum:
        - access_link_missing
        - bearer_scheme_required
        - token_expired
        - access_link_invalid
        - wrong_token_kind
        - ai_features_disabled
        - auth_required
        - insufficient_permissions
        - invalid_link_kind
        - invalid_ttl
        - access_link_limit
        - access_link_not_found
        - link_create_not_supported
        - rate_limited
        - payload_too_large
        - invalid_json
        - unsupported_media_type
        - url_too_long
        - not_found
        - missing_query
        - invalid_filter
        - invalid_arguments
        - invalid_diff_format
        - confirm_required
        - missing_expected_rev
        - version_mismatch
        - proposal_not_found
        - proposal_not_pending
        - proposal_not_owned
        - validation_failed
        - duplicate_node_id
        - missing_node_id
        - missing_node_type
        - invalid_node_type
        - invalid_nodes
        - invalid_node
        - invalid_wires
        - z_mismatch
        - node_already_exists
        - protected_property
        - node_not_found
        - field_not_found
        - text_not_found
        - ambiguous_match
        - unknown_node_type
        - node_type_not_found
        - chunk_conflict
        - missing_chunks
        - draft_hash_mismatch
        - upstream_error
        - internal_error
    # END GENERATED ERROR CODES

    WrongTokenKindError:
      allOf:
        - $ref: '#/components/schemas/Error'
        - type: object
          required: [code, expectedKind, actualKind]
          properties:
            code:
              type: string
              const: wrong_token_kind
            expectedKind:
              $ref: '#/components/schemas/AccessLinkKind'
            actualKind:
              $ref: '#/components/schemas/AccessLinkKind'
            hint:
              type: string

    InvalidLinkKindError:
      allOf:
        - $ref: '#/components/schemas/Error'
        - type: object
          required: [code]
          properties:
            code:
              type: string
              const: invalid_link_kind
            error:
              type: string
              example: "kind must be one of: 'get_link', 'rest', 'mcp'"

    LinkCreateNotSupportedError:
      allOf:
        - $ref: '#/components/schemas/Error'
        - type: object
          required: [code]
          properties:
            code:
              type: string
              const: link_create_not_supported
            error:
              type: string
              example: GET access links cannot create tokens
            hint:
              type: string

    NodeTypeListItem:
      type: object
      required: [type, module]
      properties:
        type:
          type: string
        module:
          type: string
        category:
          type: string
        description:
          type: string
        enabled:
          type: boolean
        version:
          type: string
        setId:
          type: string

    NodeTypeListResult:
      type: object
      required: [types, total, truncated]
      properties:
        types:
          type: array
          items:
            $ref: '#/components/schemas/NodeTypeListItem'
        total:
          type: integer
        truncated:
          type: boolean
        q:
          type: string

    NodeTypeDetail:
      type: object
      required: [type, module]
      properties:
        type:
          type: string
        module:
          type: string
        setId:
          type: string
        version:
          type: string
        enabled:
          type: boolean
        category:
          type: string
        color:
          type: string
        inputs:
          type: number
        outputs:
          type: number
        properties:
          type: object
          additionalProperties: true
        defaults:
          type: object
          additionalProperties: true
        requiredConfigNodeTypes:
          type: array
          items:
            type: string
        help:
          type: string

    PaletteSearchItem:
      type: object
      required: [module, installed]
      properties:
        module:
          type: string
        description:
          type: string
        version:
          type: string
        updated:
          type: string
        downloads:
          type: number
        link:
          type: string
        installed:
          type: boolean

    PaletteSearchResult:
      type: object
      required: [q, modules, total, truncated, hint]
      properties:
        q:
          type: string
        modules:
          type: array
          items:
            $ref: '#/components/schemas/PaletteSearchItem'
        total:
          type: integer
        truncated:
          type: boolean
        hint:
          type: string

    PayloadTooLargeError:
      allOf:
        - $ref: '#/components/schemas/Error'
        - type: object
          properties:
            code:
              type: string
              const: payload_too_large

    VersionConflictError:
      allOf:
        - $ref: '#/components/schemas/Error'
        - type: object
          properties:
            code:
              type: string
              const: version_mismatch
            expectedRev:
              type: string
            currentRev:
              type: string

    AiAccessSettingsPatch:
      type: object
      properties:
        enabled:
          type: boolean
        allowWithoutAdminAuth:
          type: boolean
        defaultLinkTtlSeconds:
          type: integer
          minimum: 1
        defaultDeploymentType:
          $ref: '#/components/schemas/DeploymentType'
        maxActiveLinks:
          type: integer
          minimum: 1
      additionalProperties: false

    AiAccessSettingsResponse:
      type: object
      required:
        - ok
        - adminAuthEnabled
        - canEdit
        - mcpPageUrl
        - settings
        - sources
        - precedence
      properties:
        ok:
          type: boolean
        adminAuthEnabled:
          type: boolean
        canEdit:
          type: boolean
        permission:
          oneOf:
            - type: string
              enum: [read, '*']
            - type: 'null'
        mcpPageUrl:
          type: string
        apiBase:
          type: string
        settings:
          type: object
          required:
            - enabled
            - allowWithoutAdminAuth
            - defaultLinkTtlSeconds
            - defaultDeploymentType
            - maxActiveLinks
          properties:
            enabled:
              type: boolean
            allowWithoutAdminAuth:
              type: boolean
            defaultLinkTtlSeconds:
              type: integer
            defaultDeploymentType:
              $ref: '#/components/schemas/DeploymentType'
            maxActiveLinks:
              type: integer
        sources:
          type: object
          additionalProperties:
            type: string
            enum: [default, settings.js, disk]
        disk:
          type: object
          additionalProperties: true
        precedence:
          type: array
          items:
            type: string
          description: Highest-wins order for effective values

    Status:
      type: object
      required:
        - ok
        - version
        - adminAuthEnabled
        - aiAccessEnabled
        - aiFeaturesEnabled
        - allowWithoutAdminAuth
        - permission
        - capabilities
        - defaultLinkTtlSeconds
        - maxActiveLinks
        - defaultDeploymentType
      properties:
        ok:
          type: boolean
        version:
          type: string
        adminAuthEnabled:
          type: boolean
        aiAccessEnabled:
          type: boolean
          description: Master switch from resolved settings (disk / settings.js)
        aiFeaturesEnabled:
          type: boolean
        allowWithoutAdminAuth:
          type: boolean
        permission:
          oneOf:
            - type: string
              enum: [read, '*']
            - type: 'null'
          description: |
            Admin session permission, or `null` for access-link callers
            (AI tokens are not admin sessions — see `caller`).
        capabilities:
          $ref: '#/components/schemas/Capabilities'
        storageDir:
          type: string
          description: |
            Server-side plugin storage directory. Admin sessions only; omitted
            for access-link (AI token) callers.
        defaultLinkTtlSeconds:
          type: integer
        maxActiveLinks:
          type: integer
        defaultDeploymentType:
          $ref: '#/components/schemas/DeploymentType'
        caller:
          description: Who is calling — admin session or access-link Bearer.
          oneOf:
            - type: object
              required: [kind]
              properties:
                kind:
                  type: string
                  const: admin
                permission:
                  type: string
                  enum: [read, '*']
            - type: object
              required: [kind, linkId]
              properties:
                kind:
                  type: string
                  const: access-link
                linkId:
                  type: string
                label:
                  type: string
                expiresAt:
                  type: string
                  format: date-time
                  description: ISO expiry time of this access-link token.
                minutesRemaining:
                  type: integer
                  minimum: 0
                  description: >
                    Whole minutes until `expiresAt`, rounded up so it is never 0 while
                    the token is still valid (never negative).
                secondsRemaining:
                  type: integer
                  minimum: 0
                  description: >
                    Whole seconds until `expiresAt` (rounded up; never negative).
                permissions:
                  type: array
                  items:
                    type: string
                  description: >
                    Access-link capabilities (e.g. status:read, flows:read,
                    proposals:create, proposals:read-own)
                baseUrls:
                  type: object
                  required: [api, rpc, openapi, openapiJson, discovery]
                  properties:
                    api:
                      type: string
                    rpc:
                      type: string
                    openapi:
                      type: string
                    openapiJson:
                      type: string
                    discovery:
                      type: string

    Capabilities:
      type: object
      required: [view, manageLinks, approveProposals]
      properties:
        view:
          type: boolean
        manageLinks:
          type: boolean
        approveProposals:
          type: boolean

    DeploymentType:
      type: string
      enum: [nodes, flows, full]
      default: nodes

    AccessLinkKind:
      type: string
      enum: [get_link, rest, mcp]
      description: |
        Surface this token is minted for (admin `POST /links` only):
        - `get_link` → path token on `/mcp/a/<token>/…` (GET-only; **cannot**
          create further tokens)
        - `rest` → `Authorization: Bearer` on this REST API
        - `mcp` → `Authorization: Bearer` on `/mcp/rpc`
        Default on create when omitted: `get_link`. Wrong surface → **403**
        `wrong_token_kind`.

    AccessLinkPublic:
      type: object
      required: [id, kind, createdAt, expiresAt]
      properties:
        id:
          type: string
        kind:
          $ref: '#/components/schemas/AccessLinkKind'
        label:
          type: string
        createdAt:
          type: string
          format: date-time
        expiresAt:
          type: string
          format: date-time
        createdBy:
          type: string

    AccessLinkCreated:
      allOf:
        - $ref: '#/components/schemas/AccessLinkPublic'
        - type: object
          required: [token]
          properties:
            token:
              type: string
              description: Raw bearer token (returned only at creation)
            url:
              type: string
              nullable: true
              description: >
                Self-contained GET link (`http(s)://{host}{httpAdminRoot}/mcp/a/{token}`).
                Present for kind=get_link; omitted for rest/mcp. The get-link
                URL itself has no create-link operation.

    CreateLinkRequest:
      type: object
      properties:
        ttlSeconds:
          type: number
          exclusiveMinimum: 0
          description: |
            Lifetime in seconds (default 14400 = 4h). Caps by `kind`:
            `get_link` ≤ 86400 (24h); `rest` / `mcp` ≤ 2592000 (30d).
            Over the cap → **400**.
        label:
          type: string
        kind:
          $ref: '#/components/schemas/AccessLinkKind'
          description: |
            Token surface (default `get_link`). Unknown values return
            **400** `invalid_link_kind`.

    FlowsSnapshot:
      type: object
      required: [rev, flows]
      properties:
        rev:
          type: string
        flows:
          type: array
          items:
            type: object
            additionalProperties: true

    FlowSnapshot:
      type: object
      required: [rev, flow]
      properties:
        rev:
          type: string
        flow:
          $ref: '#/components/schemas/FlowTab'

    FlowSummary:
      type: object
      description: Lightweight flow view from `GET /flows/{id}?summary=1`
      required: [rev, flowId, nodes, nodeCount]
      properties:
        rev:
          type: string
        flowId:
          type: string
        label:
          type: string
        type:
          type: string
        nodeCount:
          type: integer
        nodes:
          type: array
          items:
            type: object
            required: [id, type, bytes]
            properties:
              id:
                type: string
              type:
                type: string
              name:
                type: string
              wires: {}
              bytes:
                type: integer
                description: UTF-8 byte size of the full node JSON

    NodeSnapshot:
      type: object
      required: [rev, flowId, node]
      properties:
        rev:
          type: string
        flowId:
          oneOf:
            - type: string
            - type: 'null'
        node:
          type: object
          additionalProperties: true

    NodeFieldSnapshot:
      type: object
      required: [rev, flowId, nodeId, field, value, totalLines, bytes]
      properties:
        rev:
          type: string
        flowId:
          oneOf:
            - type: string
            - type: 'null'
        nodeId:
          type: string
        field:
          type: string
        value:
          type: string
        totalLines:
          type: integer
        bytes:
          type: integer
        lineRange:
          type: object
          required: [start, end]
          properties:
            start:
              type: integer
            end:
              type: integer

    SearchResult:
      type: object
      required: [rev, q, hits, hitCount, truncated, cap]
      properties:
        rev:
          type: string
        q:
          type: string
        flowId:
          type: string
        hitCount:
          type: integer
        truncated:
          type: boolean
        cap:
          type: integer
        hits:
          type: array
          items:
            type: object
            required: [flowId, nodeId, field, lines, snippet]
            properties:
              flowId:
                oneOf:
                  - type: string
                  - type: 'null'
              nodeId:
                type: string
              field:
                type: string
              lines:
                type: array
                items:
                  type: integer
              snippet:
                type: string

    FlowTab:
      type: object
      description: |
        Nested tab shape from `GET /flows/{id}` / `get_flow`. Reuse this object
        as `payload.flow` on `submit_proposal`. `get_flow` always includes
        `type` (defaults to `tab` when Node-RED omits it) and `nodes` (array,
        possibly empty). `configs` is optional.
      required: [id, type, nodes]
      properties:
        id:
          type: string
        type:
          type: string
          description: Tab/subflow type; `get_flow` defaults omitted values to `tab`
          default: tab
        label:
          type: string
        disabled:
          type: boolean
        info:
          type: string
        env:
          type: array
          items: {}
        nodes:
          type: array
          description: Child nodes for the tab (required on submit_proposal)
          items:
            type: object
            additionalProperties: true
        configs:
          type: array
          items:
            type: object
            additionalProperties: true
      additionalProperties: true

    ProposalStatus:
      type: string
      enum: [pending, approved, rejected, failed, withdrawn, expired, superseded]

    Proposal:
      type: object
      required:
        - id
        - type
        - status
        - expectedRev
        - payload
        - createdBy
        - createdAt
        - updatedAt
        - title
        - displayName
        - reviewUrl
        - reviewPath
      properties:
        id:
          type: string
        type:
          type: string
          const: replace_flow
        status:
          $ref: '#/components/schemas/ProposalStatus'
        expectedRev:
          type: string
        payload:
          $ref: '#/components/schemas/ReplaceFlowPayload'
        baseFlow:
          $ref: '#/components/schemas/FlowTab'
          description: |
            Flow tab snapshot at `expectedRev` when the proposal was submitted.
            Diffs compare `payload.flow` against this base. Omitted on legacy
            proposals created before this field existed.
        title:
          type: string
          maxLength: 80
          description: |
            Short human display title. Set at submit (AI-supplied or
            auto-generated); ` in <flowLabel>` is appended when the title does
            not already name the flow. Always present on API responses
            (resolved for legacy rows).
        storedTitle:
          type: string
          maxLength: 80
          description: |
            The title as saved. With an AI-supplied title this is that title
            (sanitized) without the ` in <flowLabel>` suffix that `title` may
            add. When no title was given it is the auto-generated title, which
            may already contain the flow name. Present on every proposal
            response, including submit.
        flowLabel:
          type: string
          description: |
            Human label of the target flow tab (stored snapshot, else the live
            flows). Empty string when unknown.
        displayName:
          type: string
          description: |
            `title · <submitted datetime>` in Node-RED **server local time**
            with an explicit UTC offset (e.g. `Edit fn1 (function) · 16 Oct 01:35 +00:00`).
            Prefer this when referring to the proposal with a human. UIs with a
            browser should render `createdAt` in the client's local timezone
            instead of parsing this embedded server clock.
        reviewUrl:
          type: string
          description: |
            Absolute deep link (`https://host/mcp#proposal=<id>`) built from the
            request Host/protocol. Uses `X-Forwarded-Host` / `X-Forwarded-Proto`
            only when Express `trust proxy` is enabled; otherwise falls back to
            the relative `reviewPath` when Host is unavailable.
        reviewPath:
          type: string
          description: |
            Relative deep link `/mcp#proposal=<id>` (under `httpAdminRoot` when
            set) that opens the admin page, switches to Proposals, and
            scrolls/highlights this item.
        createdBy:
          $ref: '#/components/schemas/ProposalCreator'
        createdAt:
          type: string
          format: date-time
          description: |
            ISO-8601 instant when the proposal was created. Prefer this for
            client-side local-time rendering.
        updatedAt:
          type: string
          format: date-time
        mine:
          type: boolean
          description: |
            Present on access-link responses: true when this token created the
            proposal.
        conflictingProposals:
          type: array
          description: |
            Pending proposals on the same flow (any token). Included on submit
            and on read of pending proposals when siblings exist.
          items:
            type: object
            required: [id, title, displayName, mine]
            properties:
              id:
                type: string
              title:
                type: string
              displayName:
                type: string
              mine:
                type: boolean
              overlappingNodeIds:
                type: array
                items:
                  type: string
              overlappingFields:
                type: array
                items:
                  type: object
                  required: [nodeId, fields]
                  properties:
                    nodeId:
                      type: string
                    fields:
                      type: array
                      items:
                        type: string
        decidedBy:
          $ref: '#/components/schemas/ProposalDecisionBy'
        reason:
          type: string
          description: |
            Present when rejected, failed, or withdrawn. On revision conflict
            after approve, explains that expectedRev is stale and the AI should
            re-read flows and submit a new proposal.
        resultRev:
          type: string

    ReplaceFlowPayload:
      type: object
      required: [flowId]
      description: |
        **Canonical form (preferred):** `{ flowId, nodes: [op…] }` with no
        `flow`. Ops apply to the live tab at top-level `expectedRev`.

        Supported `nodes[]` ops:
        - `replace_text` — `{ op:"replace_text", node, field, find, replace, occurrence? }`
        - `set` — `{ id, set:{…} }` or `{ op:"set", id, …props }`
        - `add` — `{ op:"add", node:{ id, type, … } }`
        - `remove` — `{ op:"remove", id }` (or `{ id }` remove shape)

        **Alternative:** top-level `nodes` on `CreateProposalRequest` is an
        alias for `payload.nodes` (same shapes).

        **Full tab:** `{ flowId, flow }` from `GET /flows/{id}` still works
        (optionally with `nodes` applied first when both are present).
      properties:
        flowId:
          type: string
        flow:
          $ref: '#/components/schemas/FlowTab'
        nodes:
          type: array
          description: |
            Canonical node ops (`replace_text` / `set` / `add` / `remove`)
            applied to the live tab when `flow` is omitted
          items:
            type: object
            additionalProperties: true

    ProposalCreator:
      type: object
      required: [kind, linkId]
      properties:
        kind:
          type: string
          const: access-link
        linkId:
          type: string
        label:
          type: string

    ProposalDecisionBy:
      type: object
      required: [kind]
      description: |
        Admin for approve/reject/fail; access-link for withdraw.
      properties:
        kind:
          type: string
          enum: [admin, access-link]
        username:
          type: string
        linkId:
          type: string
        label:
          type: string

    CreateProposalRequest:
      type: object
      required: [type, expectedRev, payload]
      properties:
        type:
          type: string
          const: replace_flow
        expectedRev:
          type: string
          description: Preferred field name for the current flow revision (required)
        expected_rev:
          type: string
          description: Alias for expectedRev
        title:
          type: string
          maxLength: 80
          description: |
            Optional short human title (≤80 chars, sanitized). Auto-generated
            from the change set when omitted.
        payload:
          $ref: '#/components/schemas/ReplaceFlowPayload'
        nodes:
          type: array
          description: Optional top-level alias for payload.nodes
          items:
            type: object
            additionalProperties: true
      example:
        type: replace_flow
        expectedRev: 'abc123rev'
        title: Rename inject to Hello
        payload:
          flowId: tab1
          nodes:
            - op: replace_text
              node: n1
              field: template
              find: Hello
              replace: Hi

    ApproveProposalRequest:
      type: object
      properties:
        deploymentType:
          $ref: '#/components/schemas/DeploymentType'

    RejectProposalRequest:
      type: object
      properties:
        reason:
          type: string
          default: Rejected by admin

    ProposalDiffLine:
      type: object
      required: [op, text]
      properties:
        op:
          type: string
          enum: [equal, add, remove]
        text:
          type: string

    ProposalDiffPropertyChange:
      oneOf:
        - type: object
          required: [key, kind, before, after]
          properties:
            key:
              type: string
            kind:
              const: scalar
            before: {}
            after: {}
        - type: object
          required: [key, kind, before, after, lines]
          properties:
            key:
              type: string
            kind:
              const: text
            before:
              type: string
            after:
              type: string
            lines:
              type: array
              items:
                $ref: '#/components/schemas/ProposalDiffLine'

    ProposalDiffModifiedNode:
      type: object
      required: [id, type, changes]
      properties:
        id:
          type: string
        type:
          type: string
        name:
          type: string
        changes:
          type: array
          description: Changed properties only (modified nodes).
          items:
            $ref: '#/components/schemas/ProposalDiffPropertyChange'

    ProposalDiffPresenceProperty:
      type: object
      required: [key, kind, value]
      properties:
        key:
          type: string
        kind:
          type: string
          enum: [scalar, text]
        value: {}
        preview:
          type: string
          enum: [html]
          description: When set, the /mcp UI may offer a sandboxed HTML preview.

    ProposalDiffPresenceNode:
      type: object
      required: [id, type, summary, keyFields, properties]
      description: |
        Added or removed node as one readable block: summary sentence, key
        fields (name, wires by node name, code/HTML), and full properties.
      properties:
        id:
          type: string
        type:
          type: string
        name:
          type: string
        summary:
          type: string
          description: |
            Human sentence, e.g. Adds template node "demo-html" to flow "Test Flow".
        keyFields:
          type: array
          items:
            $ref: '#/components/schemas/ProposalDiffPresenceProperty'
        properties:
          type: array
          description: 'Full property list (UI: under All properties).'
          items:
            $ref: '#/components/schemas/ProposalDiffPresenceProperty'

    ProposalDiffSections:
      type: object
      required: [summary, added, removed, modified]
      properties:
        summary:
          type: object
          required: [added, removed, modified, tabChanges]
          properties:
            added:
              type: integer
            removed:
              type: integer
            modified:
              type: integer
            tabChanges:
              type: array
              items:
                type: string
        added:
          type: array
          items:
            $ref: '#/components/schemas/ProposalDiffPresenceNode'
        removed:
          type: array
          items:
            $ref: '#/components/schemas/ProposalDiffPresenceNode'
        modified:
          type: array
          items:
            $ref: '#/components/schemas/ProposalDiffModifiedNode'

    ProposalDiff:
      allOf:
        - $ref: '#/components/schemas/ProposalDiffSections'
        - type: object
          required:
            - proposalId
            - flowId
            - expectedRev
            - currentRev
            - baseRevStale
            - compareAgainst
          properties:
            proposalId:
              type: string
            flowId:
              type: string
            expectedRev:
              type: string
            currentRev:
              type: string
            baseRevStale:
              type: boolean
              description: |
                True only for pending proposals when expectedRev ≠ live rev.
                Never true for approved/rejected/failed.
            compareAgainst:
              type: string
              enum: [base, current]
            baseSnapshotMissing:
              type: boolean
              description: True for legacy proposals without a stored baseFlow
            vsCurrent:
              $ref: '#/components/schemas/ProposalDiffSections'
              description: |
                Present when pending and baseRevStale — proposal vs live flow.

    AuditActor:
      oneOf:
        - type: object
          required: [kind, linkId]
          properties:
            kind:
              const: access-link
            linkId:
              type: string
            label:
              type: string
        - type: object
          required: [kind]
          properties:
            kind:
              const: admin
            username:
              type: string
        - type: object
          required: [kind]
          properties:
            kind:
              const: system

    AuditEntry:
      type: object
      required: [id, at, action, actor]
      properties:
        id:
          type: string
        at:
          type: string
          format: date-time
        action:
          type: string
        actor:
          $ref: '#/components/schemas/AuditActor'
        details:
          type: object
          additionalProperties: true