@com55/node-red-ai-access 0.1.1 → 0.2.0-beta.2

package/CHANGELOG.md

@@ -6,6 +6,78 @@ 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.2] - 2026-10-28
+
+### Fixed
+
+- OAuth route collision check no longer counts disabled `http in` nodes or nodes
+  on disabled flows; collisions are re-evaluated from scratch on every deploy,
+  and an enabled `http in` node is reported once (not again as an Express "bound
+  dispatch" route).
+- OAuth route collision check ignores `http in` nodes in subflow templates
+  without a running instance, compares real mounted paths (`httpAdminRoot` /
+  `httpNodeRoot`), and matches paths case-insensitively like Express.
+- `GET /mcp/api/v1/oauth/status` no longer exposes absolute `httpStatic`
+  filesystem paths to users without full (`*`) permission.
+- Editor sidebar: OAuth lifetime number inputs and unit dropdowns sit on one
+  line, including the narrow Node-RED 5 sidebar.
+- Editor sidebar: OAuth route collisions are shown as a readable bulleted list,
+  one route per line with paths in `<code>`; `http in` nodes link to the node in
+  the editor.
+- Editor sidebar: Public URL "Check" result is shown as a clear green/red
+  status; loopback notes and the trust proxy state are moved into a muted,
+  collapsible "About the check" section with human-readable wording.
+- OAuth route collision check also honours `httpStaticRoot` (and per-entry
+  `httpStatic` roots).
+- `/mcp` page Access links: the area under the form now always shows generic
+  usage (with a `<YOUR_TOKEN>` placeholder) for the currently selected channel
+  and updates when the channel changes. The real token and client setup are
+  shown once in a modal right after creation; closing it removes the token from
+  the page.
+- Access link create/list responses are sent with `Cache-Control: no-store` and
+  `Pragma: no-cache`.
+- Access link tokens are kept in memory as a SHA-256 hash only (the raw token is
+  no longer retained after creation).
+
+### Breaking
+
+- **Access tokens can no longer be viewed or copied after creation:**
+  `GET /mcp/api/v1/links` no longer returns `token` (rest/mcp) or `url`
+  (get_link), and the links table only offers Revoke. Revoke and create a new
+  token instead.
+
+### Added
+
+- Editor sidebar: short "How to use MCP OAuth" help in the OAuth section.
+- `GET /mcp/api/v1/oauth/status` returns structured `details` (path, source,
+  node id/name) for each collision.
+
+## [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
@@ -384,5 +456,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):
 
@@ -80,6 +81,13 @@ module.exports = {
     // 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,
+    // },
   },
 };
 ```
@@ -89,8 +97,10 @@ module.exports = {
 Access-link `url`, proposal `reviewUrl`, and `accessLinksUrl` (in
 `token_expired`) are absolute URLs built by one shared helper:
 
-1. `aiAccess.publicBaseUrl`, when set, is used as-is (scheme, host, and an
-   optional path prefix). It is read from `settings.js` only.
+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.
@@ -117,34 +127,82 @@ 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` (`settings.js` only, restart
-required). 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.
+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`
@@ -229,9 +287,9 @@ a `code`. `token_expired` also includes `expiredAt` and `accessLinksUrl` (the
 
 Access links are **in memory** (default TTL **4h**, max 10). Caps: **get_link ≤
 24h**, **rest/mcp ≤ 30d**. Creating a link returns the raw `token` plus a
-self-contained `url` for `get_link` (`/mcp/a/<token>`). While the link remains
-active, `GET /links` includes `url` again so admins can re-copy from `/mcp` (the
-raw `token` field stays create-only). After a restart every old token is
+self-contained `url` for `get_link` (`/mcp/a/<token>`). The token is shown only
+once: `GET /links` never returns `token` or `url`, so to give access again
+revoke the link and create a new one. After a restart every old token is
 invalid.
 
 Call `list_flows` or `get_flow` first and pass the returned `rev` as

package/ai-access.html

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