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

package/dist/plugin.d.cts

@@ -176,7 +176,7 @@ interface AiAccessPaths {
     root: string;
     proposals: string;
     logs: string;
-    /** Persisted AI Access settings (`settings.json`). */
+    /** Persisted AI Access settings (`config.json`). */
     settings: string;
 }
 
@@ -221,11 +221,16 @@ declare class AuditLog {
 
 type ProposalStatus = 'pending' | 'approved' | 'rejected' | 'failed' | 'withdrawn' | 'expired' | 'superseded';
 type ProposalType = 'replace_flow';
-interface ProposalCreator {
+interface AccessLinkProposalCreator {
     kind: 'access-link';
     linkId: string;
     label?: string;
 }
+type ProposalCreator = AccessLinkProposalCreator | {
+    kind: 'oauth';
+    clientId: string;
+    user: string;
+};
 type ProposalDecisionBy = {
     kind: 'admin';
     username?: string;
@@ -329,11 +334,11 @@ declare class ProposalStore {
 }
 
 /**
- * Persisted AI Access settings under `<userDir>/.ai-access/settings.json`.
+ * Persisted AI Access settings under `<userDir>/.ai-access/config.json`.
  *
  * Precedence for effective values (highest wins):
- * 1. Disk file keys present in `.ai-access/settings.json` (sidebar AI Access UI)
- * 2. `settings.js` `aiAccess` block
+ * 1. `settings.js` `aiAccess` block (locked keys)
+ * 2. Disk file keys present in `.ai-access/config.json` (sidebar AI Access UI)
  * 3. Built-in defaults
  *
  * Changes via PUT /mcp/api/v1/settings update memory + disk immediately
@@ -347,6 +352,18 @@ interface PersistedAiAccessSettings {
     defaultLinkTtlSeconds?: number;
     defaultDeploymentType?: DeploymentType;
     maxActiveLinks?: number;
+    publicBaseUrl?: string;
+    corsAllowedOrigins?: string[];
+    rateLimitWindowMs?: number;
+    rateLimitMaxPerIp?: number;
+    rateLimitMaxPerToken?: number;
+    oauth?: {
+        enabled?: boolean;
+        accessTokenTtlSec?: number;
+        refreshIdleTtlSec?: number;
+        refreshMaxLifetimeSec?: number;
+        dcrMaxClients?: number;
+    };
 }
 interface EffectiveAiAccessSettings {
     enabled: boolean;
@@ -354,18 +371,31 @@ interface EffectiveAiAccessSettings {
     defaultLinkTtlSeconds: number;
     defaultDeploymentType: DeploymentType;
     maxActiveLinks: number;
+    publicBaseUrl: string;
+    corsAllowedOrigins: string[];
+    rateLimitWindowMs: number;
+    rateLimitMaxPerIp: number;
+    rateLimitMaxPerToken: number;
+    oauth: {
+        enabled: boolean;
+        accessTokenTtlSec: number;
+        refreshIdleTtlSec: number;
+        refreshMaxLifetimeSec: number;
+        dcrMaxClients: number;
+    };
 }
 type SettingsSource = 'default' | 'settings.js' | 'disk';
 interface EffectiveAiAccessSettingsWithMeta extends EffectiveAiAccessSettings {
     sources: Record<keyof EffectiveAiAccessSettings, SettingsSource>;
 }
+type Warn = (message: string) => void;
 declare class SettingsStore {
     private readonly paths;
     private readonly filePath;
     private disk;
     private settingsJs;
     private cached;
-    constructor(paths: AiAccessPaths, settingsJsAiAccess?: PersistedAiAccessSettings);
+    constructor(paths: AiAccessPaths, settingsJsAiAccess?: PersistedAiAccessSettings, warn?: Warn);
     getEffective(): EffectiveAiAccessSettingsWithMeta;
     getDisk(): PersistedAiAccessSettings;
     /**
@@ -470,8 +500,28 @@ interface AiAccessSettings {
      * Max requests per access-link token per window (default: 300).
      */
     rateLimitMaxPerToken?: number;
+    /**
+     * Explicit public base URL (e.g. `https://nodered.example.com`) used for
+     * absolute URLs (access-link `url`, proposal `reviewUrl`, `accessLinksUrl`).
+     * Overrides `Host` / `X-Forwarded-*`. Editable in the AI Access settings sidebar unless locked by settings.js.
+     */
+    publicBaseUrl?: string;
+    /**
+     * Browser origins allowed to call the AI-facing endpoints (`/mcp/a`,
+     * `/mcp/api`, `/mcp/rpc`) cross-origin, e.g. `['https://app.example.com']`.
+     * Default: none (no CORS headers). Editable in the AI Access settings sidebar unless locked by settings.js.
+     */
+    corsAllowedOrigins?: string[];
+    oauth?: {
+        enabled?: boolean;
+        accessTokenTtlSec?: number;
+        refreshIdleTtlSec?: number;
+        /** Absolute refresh-family lifetime in seconds; default 7776000 (90 days), 0 = unlimited. */
+        refreshMaxLifetimeSec?: number;
+        dcrMaxClients?: number;
+    };
 }
-type AiAccessPermission = 'read' | '*';
+type AiAccessPermission = 'read' | 'propose' | '*';
 interface AiAccessCapabilities {
     view: boolean;
     manageLinks: boolean;
@@ -488,6 +538,8 @@ interface AiAccessStatusCallerBaseUrls {
     rpc: string;
     /** OpenAPI YAML URL. */
     openapi: string;
+    /** OpenAPI JSON URL (same spec as `openapi`). */
+    openapiJson: string;
     /** Unauthenticated JSON discovery index. */
     discovery: string;
 }
@@ -515,7 +567,13 @@ interface AiAccessStatusCallerAccessLink {
      */
     baseUrls?: Partial<AiAccessStatusCallerBaseUrls>;
 }
-type AiAccessStatusCaller = AiAccessStatusCallerAdmin | AiAccessStatusCallerAccessLink;
+interface AiAccessStatusCallerOAuth {
+    kind: 'oauth';
+    clientId: string;
+    user: string;
+    scopes: string[];
+}
+type AiAccessStatusCaller = AiAccessStatusCallerAdmin | AiAccessStatusCallerAccessLink | AiAccessStatusCallerOAuth;
 interface AiAccessStatus {
     ok: boolean;
     version: string;
@@ -530,7 +588,7 @@ interface AiAccessStatus {
      */
     permission: AiAccessPermission | null;
     capabilities: AiAccessCapabilities;
-    storageDir: string;
+    storageDir?: string;
     /** Effective default access-link TTL (seconds). */
     defaultLinkTtlSeconds: number;
     /** Effective max concurrent active access links. */
@@ -543,6 +601,8 @@ interface AiAccessStatus {
 interface NodeRedPluginSettings {
     userDir: string;
     httpAdminRoot?: string;
+    httpNodeRoot?: string | false;
+    httpStatic?: string | string[];
     adminAuth?: unknown;
     aiAccess?: AiAccessSettings;
 }
@@ -552,6 +612,16 @@ interface NodeRedAuthAPI {
 interface NodeRedPluginAPI {
     settings: NodeRedPluginSettings;
     httpAdmin: Express;
+    httpNode?: Express;
+    nodes?: {
+        eachNode(listener: (node: {
+            type?: string;
+            url?: string;
+        }) => void): void;
+    };
+    events?: {
+        on(event: string, listener: () => void): void;
+    };
     auth: NodeRedAuthAPI;
     plugins: {
         registerPlugin: (id: string, definition?: Record<string, unknown>) => void;
@@ -570,6 +640,8 @@ interface AccessLinkAuthInfo {
     createdAt: string;
     expiresAt: string;
     createdBy?: string;
+    oauthClientId?: string;
+    oauthUser?: string;
 }
 interface AuthenticatedRequest extends Request {
     user?: {

package/docs/README.md

@@ -18,6 +18,8 @@ bodies. Use a **GET link** only as a fallback for headerless GET-only clients.
 - [MCP tools reference](./mcp-tools.md) — generated from live `tools/list`
   schemas
 - [Error codes](./errors.md) — code, HTTP status, meaning, hint, channels
+- [Releasing](./releasing.md) — version bump, CHANGELOG, tag, npm trusted
+  publishing
 - [OpenAPI 3.1](./api/openapi.yaml) — also served at
   `GET /mcp/api/v1/openapi.yaml` (JSON: `GET /mcp/api/v1/openapi.json`)
 - Discovery guide — `GET /mcp/api/v1` (unauthenticated JSON index)

package/docs/api/openapi.yaml

@@ -2,7 +2,7 @@ openapi: 3.1.0
 
 info:
   title: Node-RED AI Access Plugin API
-  version: 0.1.0
+  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
@@ -30,10 +30,16 @@ info:
 
     **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 **405** `link_create_not_supported`. Only admins with `*`
+    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).
+    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=` →
@@ -419,6 +425,42 @@ paths:
         '413':
           $ref: '#/components/responses/PayloadTooLarge'
 
+  /settings/check-public-url:
+    post:
+      tags: [Status]
+      summary: Check the configured public URL
+      description: Probes the MCP endpoint at the supplied HTTPS origin without following redirects.
+      operationId: checkPublicUrl
+      security:
+        - AdminSession: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [publicBaseUrl]
+              properties:
+                publicBaseUrl:
+                  type: string
+                  format: uri
+      responses:
+        '200':
+          description: Probe result
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  ok: { type: boolean }
+                  status: { type: [integer, 'null'] }
+                  url: { type: string }
+                  error: { type: string }
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+
   /links:
     get:
       tags: [Access links]
@@ -1426,7 +1468,7 @@ components:
         - `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` (405): Attempted mint under a GET link
+        - `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
@@ -1705,6 +1747,14 @@ components:
         maxActiveLinks:
           type: integer
           minimum: 1
+        publicBaseUrl:
+          type: string
+          format: uri
+        corsAllowedOrigins:
+          type: array
+          items:
+            type: string
+            format: uri
       additionalProperties: false
 
     AiAccessSettingsResponse:
@@ -1752,6 +1802,12 @@ components:
               $ref: '#/components/schemas/DeploymentType'
             maxActiveLinks:
               type: integer
+            publicBaseUrl:
+              type: string
+            corsAllowedOrigins:
+              type: array
+              items:
+                type: string
         sources:
           type: object
           additionalProperties:
@@ -1777,7 +1833,6 @@ components:
         - allowWithoutAdminAuth
         - permission
         - capabilities
-        - storageDir
         - defaultLinkTtlSeconds
         - maxActiveLinks
         - defaultDeploymentType
@@ -1807,6 +1862,9 @@ components:
           $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:
@@ -1859,7 +1917,7 @@ components:
                     proposals:create, proposals:read-own)
                 baseUrls:
                   type: object
-                  required: [api, rpc, openapi, discovery]
+                  required: [api, rpc, openapi, openapiJson, discovery]
                   properties:
                     api:
                       type: string
@@ -1867,6 +1925,8 @@ components:
                       type: string
                     openapi:
                       type: string
+                    openapiJson:
+                      type: string
                     discovery:
                       type: string
 

package/docs/errors.md

@@ -25,7 +25,7 @@ GET-link `401` responses include a `WWW-Authenticate: Bearer …` header.
 | `invalid_ttl` | 400 | `ttlSeconds` is zero, negative, not a number, or over the cap for the kind | ttlSeconds must be a positive number of seconds within the cap for the token kind: get_link ≤ 86400 (24h); rest and mcp ≤ 2592000 (30 days). | admin |
 | `access_link_limit` | 409 | Too many active links | Revoke an existing link first | admin |
 | `access_link_not_found` | 404 | Unknown link id on revoke | List links and use an existing id | admin |
-| `link_create_not_supported` | 405 | Attempted mint under a GET link | Admin mints via `POST /mcp/api/v1/links` only | GET |
+| `link_create_not_supported` | 403 | Attempted mint under a GET link | Admin mints via `POST /mcp/api/v1/links` only | GET |
 | `rate_limited` | 429 | Per-IP or per-token limit | Wait `retryAfter` / `Retry-After` | GET, REST, MCP |
 | `payload_too_large` | 413 | Body / proposal over ~1.5MB | Shrink content | GET, REST, MCP |
 | `invalid_json` | 400 | Malformed JSON body | Fix Content-Type / body | REST, MCP |

package/docs/mcp-clients.md

@@ -1,5 +1,39 @@
 # MCP client setup
 
+## OAuth (for clients with OAuth discovery)
+
+Enable MCP OAuth in the AI Access editor sidebar and set a public HTTPS origin
+in **Public URL**. Give the client the MCP endpoint
+`https://YOUR-NODE-RED/mcp/rpc`. It can discover the authorization server from
+the protected resource metadata, register itself, and request `read` or
+`propose` scope. Sign in to Node-RED and approve the client on the consent page.
+The sidebar lists registered clients and lets an admin revoke them and their
+tokens. Localhost HTTP is supported for development. If `httpNodeRoot` is
+disabled, see the sidebar warning for the metadata fallback path.
+
+Notes:
+
+- Redirect URIs must use `https://`, or `http://` on a loopback host
+  (`localhost`, `127.0.0.1`, `[::1]`). Custom native-app schemes such as
+  `myapp://callback` are not supported.
+- The consent page uses your Node-RED editor login from the same browser (the
+  editor keeps its token in browser storage, not a cookie). Open the editor on
+  the same origin as the Public URL and sign in first; the consent page offers a
+  Retry button after you sign in.
+- Users with read-only Node-RED permission can approve only the `read` scope;
+  `propose` requires full (`*`) permission.
+- Clients that register but are never approved are removed after one hour and do
+  not count toward the client limit.
+- Refresh tokens are sliding: each refresh renews the idle lifetime. A token
+  chain also has a maximum lifetime of 90 days from approval by default; after
+  that the client must sign in again. Change it in the sidebar (0 = unlimited).
+  Lowering the maximum applies immediately to existing token chains. Raising it
+  or setting 0 does not extend the refresh token a client already holds; the new
+  limit takes effect from that chain's next successful refresh (and for new
+  chains).
+
+## Access-link bearer tokens
+
 Use an **mcp** access-link token from `/mcp` → Access links (kind = MCP token).
 Endpoint: `POST https://YOUR-NODE-RED/mcp/rpc` with
 `Authorization: Bearer <mcp-token>`.

package/docs/releasing.md

@@ -0,0 +1,82 @@
+# Releasing
+
+Releases are published by the `Release` workflow
+(`.github/workflows/release.yml`). Pushing a `v*` tag runs quality checks, the
+production build and tests. It then publishes the package to npm and creates or
+updates the GitHub release for that tag, with the CHANGELOG section as notes and
+the `npm pack` tarball attached.
+
+## Cut a release
+
+1. Bump the version (no tag yet):
+
+   ```sh
+   npm version 0.1.1 --no-git-tag-version
+   ```
+
+2. In `CHANGELOG.md`, rename `## [Unreleased]` to `## [0.1.1] - YYYY-MM-DD` (or
+   add that section) and summarise the changes. The workflow uses this section
+   as the release notes and fails if it is missing.
+3. Commit, open a PR, and merge it to `main` once CI passes.
+4. Tag the merge commit and push the tag:
+
+   ```sh
+   git checkout main && git pull
+   git tag -a v0.1.1 -m "v0.1.1"
+   git push origin v0.1.1
+   ```
+
+The workflow fails early if the tag does not equal `v` + the `package.json`
+version. If that version is already on npm, the publish step is skipped and only
+the GitHub release is updated. Re-running the workflow is safe.
+
+### Re-run for an existing tag
+
+Use **Actions → Release → Run workflow** and enter the tag (for example
+`v0.1.0`). The workflow checks out that tag and runs the same steps. Use this to
+publish a version that was tagged before this workflow existed.
+
+## npm authentication
+
+The publish step supports two modes:
+
+- **Trusted publishing (OIDC, preferred).** No secret is needed. The job has
+  `permissions: id-token: write` and uses Node 24 with the latest npm (trusted
+  publishing needs npm >= 11.5.1 and Node >= 22.14.0). Provenance is generated
+  automatically for a public package published from a public repository;
+  `--provenance` is also passed.
+- **Token fallback.** If the repository secret `NPM_TOKEN` is set, it is used as
+  `NODE_AUTH_TOKEN` instead. Use this for the first publish, because a trusted
+  publisher can only be configured on a package that already exists on npm.
+
+### First publish
+
+1. On npmjs.com, create a granular access token with read and write access to
+   publish packages for the `@com55` scope. It needs "bypass 2FA" if your
+   account requires 2FA for writes, and a short expiry.
+2. Add it to the GitHub repository as the Actions secret `NPM_TOKEN` (**Settings
+   → Secrets and variables → Actions**).
+3. Push the tag, or run the workflow manually with the existing tag.
+
+### Switch to trusted publishing
+
+After the package exists on npm:
+
+1. Open npmjs.com → the package → **Settings → Trusted publishing**, and choose
+   **GitHub Actions**.
+2. Enter:
+   - Organization or user: `com55`
+   - Repository: `node-red-ai-access`
+   - Workflow filename: `release.yml` (the filename only, with the extension)
+   - Environment: leave empty
+   - Allowed actions: enable direct `npm publish`. The workflow runs
+     `npm publish`, not `npm stage publish`.
+3. Complete a publish through the workflow within 2 days, or the new
+   configuration expires and has to be recreated.
+4. Delete the `NPM_TOKEN` secret and revoke the token on npmjs.com.
+5. Optional: under the package's **Settings → Publishing access**, choose
+   "Require two-factor authentication and disallow tokens". Trusted publishing
+   keeps working.
+
+`repository.url` in `package.json` must match this GitHub repository exactly, or
+OIDC publishing is rejected.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@com55/node-red-ai-access",
-  "version": "0.1.0",
+  "version": "0.2.0-beta.1",
   "description": "Node-RED plugin that gives AI agents temporary, owner-approved access via REST and MCP",
   "main": "dist/plugin.cjs",
   "types": "dist/plugin.d.cts",
@@ -82,7 +82,7 @@
   "author": "com55",
   "license": "MIT",
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.31.0",
+    "@modelcontextprotocol/sdk": "^1.32.2",
     "express": "^5.3.0",
     "express-rate-limit": "^8.5.2",
     "yaml": "^2.8.0",
@@ -99,18 +99,18 @@
     "eslint-plugin-import": "^2.32.0",
     "husky": "^9.1.7",
     "lint-staged": "^17.6.0",
-    "node-red": "4.1.12",
+    "node-red": "4.1.17",
     "prettier": "^3.9.10",
     "rimraf": "^6.1.3",
     "supertest": "^7.3.1",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
     "typescript-eslint": "^8.71.1",
-    "vite": "^6.4.0",
+    "vite": "^8.3.5",
     "vitest": "^5.0.3"
   },
   "engines": {
-    "node": ">=20.0.0",
+    "node": ">=20.19.0",
     "npm": ">=10.0.0"
   },
   "repository": {