@com55/node-red-ai-access 0.1.0 → 0.2.0-beta.1

package/CHANGELOG.md

@@ -6,6 +6,100 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## Unreleased
+
+## [0.2.0-beta.1] - 2026-10-28
+
+First pre-release of 0.2.0, published under the npm `beta` dist-tag.
+
+### Added
+
+- Node-RED settings and sidebar for configuring AI Access (#91).
+- MCP OAuth authorization (#99): dynamic client registration (DCR), PKCE, an
+  owner consent page, and sliding refresh tokens with defaults of 1 hour (access
+  token), 30 days (refresh idle) and 90 days (refresh maximum).
+- Route-collision check for the OAuth and metadata endpoints.
+- MCP OAuth 2.1 authorization server and protected resource support with PKCE
+  S256, dynamic client registration, resource-bound tokens, rotating refresh
+  tokens, and `read`/`propose` scopes. Existing access-link tokens still work.
+- Sidebar controls for OAuth lifetimes and client limits, registered-client
+  revocation, route-collision and metadata-fallback warnings, and a Public URL
+  warning when enabling OAuth, plus a refresh-token maximum lifetime (default 90
+  days, 0 = unlimited).
+
+### Changed
+
+- CI now tests against a Node-RED 4 and Node-RED 5 matrix.
+- Requires Node.js >= 20.19.
+
+## [0.1.1] - 2026-10-17
+
+### Added
+
+- `/status` (REST and MCP `get_status`) now includes `openapiJson` in
+  `caller.baseUrls` for `rest` tokens, pointing at the served
+  `GET /mcp/api/v1/openapi.json`.
+- Optional `aiAccess.corsAllowedOrigins` setting (settings.js): list of browser
+  origins allowed to call the AI-facing endpoints cross-origin, with
+  `Vary: Origin` and `OPTIONS` preflight support. Origins match
+  case-insensitively and the configured canonical origin is echoed; malformed
+  origins are rejected. `WWW-Authenticate`, `Retry-After`, and the `RateLimit*`
+  headers are exposed to allowed origins.
+- Optional `aiAccess.publicBaseUrl` setting (settings.js) that sets the public
+  base URL for absolute links (access-link `url`, proposal `reviewUrl`,
+  `accessLinksUrl`), overriding `Host` and `X-Forwarded-*`.
+- The MCP client snippets in the GET-link guide use the public origin
+  (`publicBaseUrl`, else the validated request origin) instead of the
+  `https://YOUR-NODE-RED` placeholder, which remains only when the origin cannot
+  be determined.
+
+### Changed
+
+- **Behavior change:** every response on the GET access-link channel
+  (`/mcp/a/<token>/*`), including the markdown guide and JSON success and error
+  bodies, now defaults to `Content-Type: text/html; charset=utf-8`, because some
+  AI web fetchers only read `text/html`. The HTML is a minimal document with the
+  same markdown or pretty-printed JSON, fully escaped in one `<pre>`, with safe
+  relative `./…` links linkified (no scripts, no external resources). Status
+  codes and data are unchanged. The previous representation is returned when
+  `Accept` explicitly lists `text/markdown` or `application/json`, or
+  `?format=md` / `?format=json` is set; an explicit `Accept: text/plain` returns
+  the raw text as `text/plain`. All `/mcp/a/*` responses carry `Vary: Accept`,
+  `Cache-Control: no-store`, `Referrer-Policy: no-referrer`,
+  `X-Robots-Tag: noindex, nofollow`, and `X-Content-Type-Options: nosniff`; HTML
+  adds a restrictive `Content-Security-Policy`. REST and MCP are unchanged.
+- **Behavior change:** the AI-facing endpoints (`/mcp/a/*`, `/mcp/api/*`,
+  `/mcp/rpc`) no longer send `Access-Control-Allow-Origin: *` (inherited from
+  Node-RED's admin app). No CORS headers are sent unless the request `Origin` is
+  listed in `aiAccess.corsAllowedOrigins`. Only browser-based callers are
+  affected; server-side clients are not.
+- Attempts to create, list, or revoke access links under a GET access link
+  (`/mcp/a/<token>/links`) now return **403** `link_create_not_supported`
+  instead of 405. Error registry, `docs/errors.md`, OpenAPI, and get-link docs
+  updated.
+- `/status` (GET link, REST, and MCP `get_status`) no longer includes
+  `storageDir` for access-link callers; it remains in admin-session responses
+  (shown on the `/mcp` page).
+
+### Fixed
+
+- Proposal titles no longer repeat the flow name when a long `<title> in <flow>`
+  was capped at 80 characters.
+- GET-link HTML no longer linkifies template paths such as `./nodes/<id>`.
+
+- **Security:** absolute URLs no longer copy unvalidated `X-Forwarded-Proto` /
+  `X-Forwarded-Host` (or `Host`) values. The scheme must be exactly `http` or
+  `https` (else the connection scheme is used); hosts must be a DNS name, IPv4,
+  or bracketed IPv6 literal with an optional port 1-65535, with no userinfo,
+  path, query, fragment, or whitespace. Invalid forwarded hosts fall back to
+  `Host`; an invalid `Host` falls back to a relative path.
+
+- Absolute URLs (access-link `url`, proposal `reviewUrl`, `accessLinksUrl`) used
+  `http://` behind a TLS-terminating proxy. With Express `trust proxy` enabled
+  the first `X-Forwarded-Proto` value is now used explicitly; without it, set
+  `aiAccess.publicBaseUrl`. Forwarded headers stay ignored when `trust proxy` is
+  off.
+
 ## [0.1.0] - 2026-10-16
 
 First public release of **Node-RED AI Access**: an admin-gated Node-RED 4 plugin
@@ -316,4 +410,7 @@ Requires Node.js 20+.
   auth, 413 limits) served at `GET /mcp/api/v1/openapi.yaml`; README install,
   config, `/mcp` usage, and AI quickstart.
 
+[0.2.0-beta.1]:
+  https://github.com/com55/node-red-ai-access/compare/v0.1.1...v0.2.0-beta.1
+[0.1.1]: https://github.com/com55/node-red-ai-access/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/com55/node-red-ai-access/releases/tag/v0.1.0

package/README.md

@@ -1,7 +1,7 @@
 # Node-RED AI Access
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Node.js Version](https://img.shields.io/badge/node-%3E%3D22.0.0-brightgreen.svg)](https://nodejs.org/)
+[![Node.js Version](https://img.shields.io/badge/node-%3E%3D20.19.0-brightgreen.svg)](https://nodejs.org/)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.7%2B-blue.svg)](https://www.typescriptlang.org/)
 [![CI](https://github.com/com55/node-red-ai-access/actions/workflows/ci.yml/badge.svg)](https://github.com/com55/node-red-ai-access/actions)
 
@@ -24,9 +24,10 @@ Derived from
 
 ## Install (Node-RED plugin)
 
-Requirements: **Node-RED 4.x or newer**, Node.js 20+, and **`adminAuth`
-enabled** (recommended). Without `adminAuth`, AI features stay off unless you
-opt in (see Configuration).
+Requirements: **Node-RED 4.x or newer**, Node.js 20.19+ (tested: Node-RED 4.1 on
+Node 20/22, Node-RED 5.0 on Node 22/24), and **`adminAuth` enabled**
+(recommended). Without `adminAuth`, AI features stay off unless you opt in (see
+Configuration).
 
 1. Install into your Node-RED user directory (or via the palette):
 
@@ -74,28 +75,134 @@ module.exports = {
     rateLimitWindowMs: 60000,
     rateLimitMaxPerIp: 600,
     rateLimitMaxPerToken: 300,
+    // Public base URL for absolute links (access-link url, reviewUrl,
+    // accessLinksUrl). Set this behind a TLS-terminating proxy (default: unset)
+    // publicBaseUrl: 'https://nodered.example.com',
+    // Browser origins allowed to call /mcp/a, /mcp/api, and /mcp/rpc
+    // cross-origin (default: none — no CORS headers are sent)
+    // corsAllowedOrigins: ['https://app.example.com'],
+    // MCP OAuth (disabled by default; publicBaseUrl is the issuer)
+    // oauth: {
+    //   enabled: true,
+    //   accessTokenTtlSec: 3600,
+    //   refreshIdleTtlSec: 2592000,
+    //   dcrMaxClients: 20,
+    // },
   },
 };
 ```
 
+### Absolute URLs behind a reverse proxy
+
+Access-link `url`, proposal `reviewUrl`, and `accessLinksUrl` (in
+`token_expired`) are absolute URLs built by one shared helper:
+
+1. Effective `aiAccess.publicBaseUrl`, when set, overrides the request origin.
+   The sidebar/settings API accepts an HTTPS origin without a path, query,
+   fragment, or credentials (HTTP localhost / loopback is allowed for
+   development). An empty value uses the request origin.
+2. Otherwise, when Express `trust proxy` is enabled (for example
+   `httpServerOptions: { 'trust proxy': true }`), the first `X-Forwarded-Proto`
+   and `X-Forwarded-Host` values are used.
+3. Otherwise the request `Host` header and the connection protocol are used;
+   `X-Forwarded-*` headers are ignored so clients cannot spoof link origins.
+
+Forwarded and `Host` values are validated: the scheme must be `http` or `https`
+(else the connection scheme is used) and the host must be a DNS name, IPv4, or
+bracketed IPv6 literal with an optional port. An invalid forwarded host falls
+back to `Host`; an invalid `Host` yields relative paths. The MCP client snippets
+in the GET-link guide use the same origin, and show a `https://YOUR-NODE-RED`
+placeholder only when no origin can be determined.
+
+Behind a TLS-terminating proxy (for example Cloudflare) with neither option set,
+links therefore start with `http://`.
+
+### CORS
+
+CORS only affects code running in a browser (a web page calling the plugin from
+another origin). Server-side AI fetchers and agents (for example Gemini,
+ChatGPT, or an MCP client running outside a browser) ignore CORS and are not
+affected by this setting.
+
+By default the AI-facing endpoints (`/mcp/a/*`, `/mcp/api/*`, `/mcp/rpc`) send
+**no** CORS headers, overriding Node-RED's built-in
+`Access-Control-Allow-Origin: *` for those paths. To allow a browser app, list
+its origin in `aiAccess.corsAllowedOrigins` via the AI Access sidebar or
+settings API. Changes apply immediately. The API rejects any invalid origin in
+the supplied list (including paths, credentials, queries, and fragments). For a
+listed `Origin` the response echoes it in `Access-Control-Allow-Origin` with
+`Vary: Origin`, and `OPTIONS` preflight returns `204` with allowed methods
+(`GET, POST, DELETE, OPTIONS`) and headers (`Authorization`, `Content-Type`,
+`Accept`, `Mcp-Session-Id`, `Mcp-Protocol-Version`, `Last-Event-ID`). Origins
+match case-insensitively and the configured origin is echoed; malformed origins
+are rejected. Exposed headers include `Mcp-Session-Id`, `WWW-Authenticate`,
+`Retry-After`, and the `RateLimit*` headers. Other origins get no CORS headers.
+
 ### Settings precedence
 
 Effective values are resolved **without restart** in this order (highest wins):
 
-1. **Disk** — `<userDir>/.ai-access/settings.json` (editor sidebar **AI Access**
+1. **`settings.js`** — keys present in the `aiAccess` block are locked
+2. **Disk** — `<userDir>/.ai-access/config.json` (editor sidebar **AI Access**
    tab, or `PUT /mcp/api/v1/settings`)
-2. **`settings.js`** — `aiAccess` block (install / bootstrap defaults)
 3. **Built-in defaults** — as documented above
 
-Only keys present on disk override; omitted keys fall through to `settings.js`,
-then defaults. The editor right-hand sidebar tab (**AI Access**, next to
-Information / Help / Debug / Configuration nodes / Context Data) lets `*` admins
-change enable/disable, default deploy type, and default access-link TTL; `read`
-users see the same values read-only. A button opens the `/mcp` page. When
+This is a breaking precedence change in 0.2.0: settings.js now wins over disk.
+Legacy `settings.json` is read when `config.json` is absent; the next save
+writes `config.json`. Locked fields show a lock indicator and disabled input.
+PUT ignores locked keys while applying unlocked ones; GET and PUT return
+per-field `sources` (`settings.js`, `disk`, or `default`) and the precedence
+order.
+
+The editor right-hand sidebar tab (**AI Access**, next to Information / Help /
+Debug / Configuration nodes / Context Data) lets `*` admins change
+enable/disable, default deploy type, access-link TTL, maximum active links,
+Public URL, CORS origins, and the three rate limits. `read` users see the same
+values read-only. Express's effective `trust proxy` setting is displayed
+read-only. Public URL, CORS, and rate limits apply immediately; changing limits
+starts fresh rate-limit buckets. A button opens the `/mcp` page. When
 `adminAuth` is off, the tab exposes the `allowWithoutAdminAuth` opt-in with a
 clear local-only warning.
 
-Storage lives under **`<userDir>/.ai-access`** (`settings.json`,
+The sidebar also configures MCP OAuth, shows registered clients with revoke
+buttons, and reports route collisions and the `httpNodeRoot: false` metadata
+fallback. Enabling OAuth with no Public URL or an HTTP non-loopback URL shows a
+warning confirmation; it does not block the change. OAuth fields set in
+`settings.js` are locked in the sidebar.
+
+### MCP OAuth
+
+OAuth is disabled by default. Set `aiAccess.publicBaseUrl` to the public HTTPS
+origin before enabling it; localhost and loopback HTTP are supported for local
+development. Node-RED serves authorization, token, dynamic client registration,
+and revocation under `/mcp/oauth/*`. It publishes authorization server metadata
+at `/.well-known/oauth-authorization-server` and protected resource metadata at
+`/.well-known/oauth-protected-resource/mcp` and
+`/.well-known/oauth-protected-resource`. The issuer is `publicBaseUrl` and the
+resource indicator is `{publicBaseUrl}/mcp`. When `httpNodeRoot` is false,
+metadata is available under the admin `/mcp` path instead; the sidebar displays
+this fallback. Route collisions disable the affected OAuth endpoints and appear
+in the sidebar.
+
+Clients use authorization code with PKCE S256 and can request `read` or
+`propose`. Consent uses the Node-RED editor login. Access tokens last one hour
+by default; refresh tokens expire after 30 days of inactivity and rotate on each
+use. Reusing a rotated refresh token revokes its token family. Tokens are stored
+as SHA-256 hashes in `<userDir>/.ai-access/oauth.json`. Access-link `aia_`
+bearer tokens continue to work. See [MCP client setup](docs/mcp-clients.md).
+
+Public URL **Check** uses `POST /mcp/api/v1/settings/check-public-url` and
+requires `*` permission because it performs an outbound request. It validates
+the form URL, fetches only `{publicBaseUrl}{httpAdminRoot}/mcp/api/v1`
+(discovery), times out after 5 seconds, and never follows redirects. The result
+reports the HTTP status or a connection/timeout error; it does not save the
+form. Loopback checks use Node-RED's own listening port; behind a reverse proxy,
+use the internal Node-RED port. Unix-socket listeners are not supported. HTTPS
+checks using a self-signed certificate fail because TLS verification remains
+enabled. Saving a Public URL with a private/internal IP literal is allowed, but
+the settings response and sidebar show a warning.
+
+Storage lives under **`<userDir>/.ai-access`** (`config.json`,
 `proposals/*.json`, and append-only `logs/audit.jsonl`). Directories use mode
 `0700`, files `0600`. Proposal JSON is capped at **1_500_000 bytes**; oversized
 proposal JSON or audit lines return HTTP **413** with `code: payload_too_large`
@@ -215,6 +322,21 @@ errors mark it **failed**. Reject never mutates flows.
    `nodes:[{op:'add'|'remove'|'set',...}]` (or a full `replace_flow` document).
    Field drafts validate node/field at `draft/new`. Unknown `/mcp/a/*` paths
    return JSON `not_found` without echoing the token.
+
+   Responses on GET links default to HTML, because some AI web fetchers only
+   read `text/html`. The HTML is a minimal document (no scripts or external
+   resources) holding the same markdown or pretty-printed JSON, fully escaped in
+   one `<pre>`, with relative `./…` links clickable. Request the real type via
+   Accept or `?format=`: `Accept: text/markdown` or `?format=md` for the guide,
+   `Accept: application/json` or `?format=json` for JSON. An explicit
+   `Accept: text/plain` returns the same raw text as `text/plain`. No Accept,
+   `*/*`, `text/html`, or browser-style lists get HTML. Status codes and data
+   are unchanged; every response carries `Vary: Accept`,
+   `Cache-Control: no-store`, `Referrer-Policy: no-referrer`,
+   `X-Robots-Tag: noindex, nofollow`, and `X-Content-Type-Options: nosniff`, and
+   HTML adds a restrictive `Content-Security-Policy`. REST and MCP endpoints are
+   not affected.
+
 3. Changes become **pending proposals**; a human approves on `/mcp`. JSON
    responses use `Cache-Control: no-store`.
 

package/ai-access.html

@@ -14,7 +14,7 @@
     }
     window.__com55AiAccessSidebarLoading = true;
 
-    var EDITOR_SIDEBAR_ASSET_VERSION = '0.1.0';
+    var EDITOR_SIDEBAR_ASSET_VERSION = '0.2.0-beta.1';
     var root = (RED.settings.httpAdminRoot || '/').replace(/\/$/, '');
     var src =
       (root || '') +