@com55/node-red-ai-access 0.1.0 → 0.1.1

package/dist/plugin.d.cts

@@ -470,6 +470,18 @@ 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-*`. settings.js only.
+     */
+    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). settings.js only.
+     */
+    corsAllowedOrigins?: string[];
 }
 type AiAccessPermission = 'read' | '*';
 interface AiAccessCapabilities {
@@ -488,6 +500,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;
 }
@@ -530,7 +544,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. */

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=` →
@@ -1426,7 +1432,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
@@ -1777,7 +1783,6 @@ components:
         - allowWithoutAdminAuth
         - permission
         - capabilities
-        - storageDir
         - defaultLinkTtlSeconds
         - maxActiveLinks
         - defaultDeploymentType
@@ -1807,6 +1812,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 +1867,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 +1875,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/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.1.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",