mc8yp 2.0.1 → 2.2.0

package/README.md

@@ -4,7 +4,7 @@
 ![License](https://img.shields.io/npm/l/mc8yp)
 ![Node Version](https://img.shields.io/node/v/mc8yp)
 
-A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that gives AI agents full access to the Cumulocity IoT platform through code execution. Instead of exposing dozens of fixed tools, the server provides two code-mode tools — `query` and `execute` — that let the agent write JavaScript to inspect the core OpenAPI spec and call any API endpoint.
+A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that gives AI agents full access to the Cumulocity IoT platform through code execution. Instead of exposing dozens of fixed tools, the server provides two code-mode tools — `query` and `execute` — that let the agent write JavaScript to inspect the bundled OpenAPI specs and call any API endpoint.
 
 **Two Deployment Modes:**
 
@@ -19,7 +19,7 @@ A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that gi
 # Run directly (recommended)
 pnpm dlx mc8yp
 
-# Pick a specific core OpenAPI snapshot for query
+# Pick a specific bundled OpenAPI build for query
 pnpm dlx mc8yp --spec 2025
 
 # Or install globally
@@ -28,7 +28,7 @@ mc8yp
 ```
 
 **Credential Storage:**
-Credentials are stored using your operating system's secure credential manager:
+Credentials are stored using your operating system's secure credential manager. The interactive `mc8yp creds add` flow uses hidden password input so the secret is not echoed back in the terminal while you type it.
 
 - **macOS**: Keychain
 - **Windows**: Credential Vault
@@ -50,7 +50,7 @@ No additional credential configuration needed — the microservice uses Cumuloci
 ### Managing Credentials (CLI)
 
 ```sh
-# Add credentials (prompts for tenant URL, username, password)
+# Add credentials (prompts for tenant URL, username, and a masked password)
 pnpm dlx mc8yp creds add
 
 # List stored credentials
@@ -60,24 +60,31 @@ pnpm dlx mc8yp creds list
 pnpm dlx mc8yp creds remove
 ```
 
-### Selecting The Core OpenAPI Snapshot (CLI)
+### Selecting The Bundled OpenAPI Build (CLI)
 
-Use `--spec` or `-s` to choose which bundled core OpenAPI snapshot the `query` tool exposes.
+Use `--spec` or `-s` to choose which bundled **core** OpenAPI snapshot the `query` tool exposes.
 
 Supported values are `release`, `2026`, `2025`, and `2024`.
 
+This flag selects the bundled **core** API version only. The bundled **dtm** OpenAPI snapshot is currently fixed and is included alongside every supported core build.
+
+Each bundled CLI build currently contains:
+
+- the selected bundled **core** OpenAPI snapshot
+- the bundled **dtm** OpenAPI snapshot
+
 ```sh
-# Default: latest bundled release snapshot
+# Default: latest bundled release build
 mc8yp
 
-# Explicitly use the 2025 core OpenAPI snapshot
+# Explicitly use the 2025 bundled build
 mc8yp --spec 2025
 
 # Short form
 mc8yp -s 2024
 ```
 
-This only affects the `query` tool's OpenAPI view. The `execute` tool still calls the live Cumulocity API of the selected tenant or deployed service environment.
+This only affects the bundled OpenAPI data that `query` sees. The `execute` tool still calls the live Cumulocity API of the selected tenant or deployed service environment.
 
 ### Connecting to AI Agents
 
@@ -115,7 +122,7 @@ With restrictions (see [API Restrictions](#api-restrictions)):
 
 | Tool               | Description                                                                                                                                                                                                                                        |
 | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `query`            | Search and inspect the bundled Cumulocity core OpenAPI spec by running a JavaScript module. The spec is injected as a top-level `spec` binding. Export the result with `export default`.                                                           |
+| `query`            | Search and inspect the bundled OpenAPI specs by running a JavaScript function expression. The sandbox exposes `coreSpec`, `dtmSpec`, and `specsEnabled`, and it never hides bundled specs from the query surface.                                  |
 | `execute`          | Execute JavaScript against the live Cumulocity API. Provide an async JavaScript function expression. A top-level `cumulocity` binding provides `cumulocity.request({ method, path, body?, headers? })`. Return the final value from that function. |
 | `list-credentials` | _(CLI mode only)_ List stored credentials from your system keyring.                                                                                                                                                                                |
 
@@ -154,39 +161,97 @@ async () => {
 
 ### Prompts
 
-| Prompt            | Description                                                                                                                               |
-| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
-| `code-mode-guide` | Full reference for the `query` and `execute` tools, including available types, examples, and restriction info for the current connection. |
+| Prompt            | Description                                                                                                                                 |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| `code-mode-guide` | Full reference for the `query` and `execute` tools, including available types, examples, and access-policy info for the current connection. |
+
+## API Access Policy
+
+mc8yp supports two per-connection rule types:
+
+- **Restrictions** — deny rules that block matching API operations
+- **Allow rules** — allow-list rules that permit matching API operations and block everything else when at least one allow rule is configured
+
+If both apply to the same operation, **restrictions take priority**.
+
+Example: allowing `/inventory/**` but restricting `/inventory/managedObjects` still blocks `/inventory/managedObjects`.
+
+Both rule types use the same syntax.
+
+### Restrictions
 
-## API Restrictions
+Restrictions are deny rules that block specific API operations.
 
-Restrictions are deny rules that block specific API operations. They can be applied per-connection to limit what an AI agent can access.
+### Allow Rules
+
+Allow rules are the inverse of restrictions. They define what is permitted. When one or more allow rules are configured, any operation that does not match at least one allow rule is blocked.
 
 ### Rule Format
 
+A restriction or allow rule can be written in either of these forms:
+
+```txt
+<path-pattern>
+<method>:<path-pattern>
 ```
-[METHOD:]<path-pattern>
-```
 
-- **Without a method prefix** — blocks all HTTP methods for matching paths
-- **With a method prefix** — blocks only that method (e.g. `GET:`, `DELETE:`, `POST:`)
-- **Path patterns** support `*` (single segment wildcard) and `**` (recursive wildcard)
-- Query strings and fragments are not allowed in patterns
+- **Without a method prefix** — matches all HTTP methods for matching paths
+- **With a method prefix** — matches only that method (for example `GET:`, `DELETE:`, `POST:`)
+- **The `:` separator is only present when a method prefix is provided**
+- **Supported methods** — `DELETE`, `GET`, `HEAD`, `OPTIONS`, `PATCH`, `POST`, `PUT`, `TRACE`, or `*`
+- Method names are case-insensitive when parsed (`get:/inventory/**` becomes `GET:/inventory/**`)
+
+### Path Pattern Syntax
+
+Patterns are matched against the request **pathname**.
+
+- Query strings and fragments are **not allowed in rule patterns**
+- Incoming request query strings are ignored for matching, so `/inventory/**` also matches requests such as `/inventory?pageSize=5`
+- Patterns must start with `/`
+- Matching is path-segment aware: `/` separates segments
+
+Supported wildcards:
+
+- `*` — wildcard **inside a single path segment**. It matches any characters except `/`
+- `**` — recursive wildcard across **zero or more whole path segments**. `**` must be its own complete segment
+
+### Path Pattern Examples
+
+| Pattern               | Matches                                                     | Does Not Match                             |
+| --------------------- | ----------------------------------------------------------- | ------------------------------------------ |
+| `/inventory`          | `/inventory`                                                | `/inventory/managedObjects`                |
+| `/inventory/**`       | `/inventory`, `/inventory/managedObjects`, `/inventory/x/y` | `/alarm/alarms`                            |
+| `/i*`                 | `/inventory`, `/identity`, `/i`                             | `/inventory/managedObjects`                |
+| `/i*/**`              | `/inventory`, `/inventory/managedObjects`, `/identity/x`    | `/alarm/alarms`                            |
+| `/inventory/m*`       | `/inventory/managedObjects`, `/inventory/measurements`      | `/inventory/events`, `/inventory/m/x`      |
+| `/inventory/*/child`  | `/inventory/device-1/child`, `/inventory/x/child`           | `/inventory/child`, `/inventory/a/b/child` |
+| `/inventory/**/child` | `/inventory/child`, `/inventory/a/b/child`                  | `/inventory/a/b/sibling`                   |
 
-### Examples
+### Common Rule Examples
 
-| Rule                             | Effect                                              |
-| -------------------------------- | --------------------------------------------------- |
-| `/inventory/**`                  | Block all methods on all inventory paths            |
-| `DELETE:/inventory/**`           | Block only DELETE on inventory paths                |
-| `/alarm/alarms`                  | Block all methods on the exact path `/alarm/alarms` |
-| `GET:/measurement/measurements`  | Block only GET on measurements                      |
-| `POST:/inventory/managedObjects` | Block creating new managed objects                  |
-| `/user/**`                       | Block all user management                           |
+| Rule                             | Restriction Effect                                           | Allow-list Effect                                             |
+| -------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------- |
+| `/inventory/**`                  | Block all methods on `/inventory` and everything below it    | Permit all methods on `/inventory` and everything below it    |
+| `DELETE:/inventory/**`           | Block only DELETE on `/inventory` and everything below it    | Permit only DELETE on `/inventory` and everything below it    |
+| `/alarm/alarms`                  | Block all methods on the exact path `/alarm/alarms`          | Permit all methods on the exact path `/alarm/alarms`          |
+| `GET:/measurement/measurements`  | Block only GET on the exact path `/measurement/measurements` | Permit only GET on the exact path `/measurement/measurements` |
+| `POST:/inventory/managedObjects` | Block creating new managed objects                           | Permit creating new managed objects                           |
+| `/i*/**`                         | Block all routes whose first path segment starts with `i`    | Permit all routes whose first path segment starts with `i`    |
+| `/user/**`                       | Block all user management paths                              | Permit all user management paths                              |
+
+### Important Notes
+
+- `/inventory/**` already matches `/inventory` itself, so you do **not** need both `/inventory` and `/inventory/**`
+- `/i**` is **not valid** because `**` must be its own segment. Use `/i*/**` if you want to match a first segment starting with `i` and everything below it
+- `*:/inventory/**` is allowed and means the same thing as `/inventory/**`
+- Root paths across the bundled core and DTM specs are intentionally treated as disjoint, so path-based restriction and allow rules are enough for request enforcement
+- Rule patterns may not contain empty segments (`//`), `.` or `..` segments, query strings, or fragments
 
 ### CLI Mode
 
-Pass restrictions as CLI arguments. Repeat `-r` / `--restriction` for multiple rules:
+Pass restrictions and allow rules as CLI arguments.
+
+Repeat `-r`, `--restrict`, or `--restriction` for deny rules:
 
 ```sh
 # Block all inventory access
@@ -195,31 +260,78 @@ mc8yp -r "/inventory/**"
 # Block deletes on inventory and all alarm access
 mc8yp -r "DELETE:/inventory/**" -r "/alarm/**"
 
-# Block everything under user management
-mc8yp --restriction "/user/**"
+# Same thing using the long alias
+mc8yp --restrict "/user/**"
+```
+
+Repeat `-a`, `--allow`, or `--allowed` for allow rules:
+
+```sh
+# Only permit inventory access
+mc8yp -a "/inventory/**"
+
+# Permit GET inventory access and POST alarms
+mc8yp --allow "GET:/inventory/**" --allowed "POST:/alarm/**"
+
+# Allow inventory broadly, but still block one path with a restriction
+mc8yp -a "/inventory/**" -r "/inventory/managedObjects"
+```
+
+To forbid one or more bundled OpenAPI parts for execute policy, repeat `--disable-openapi` (or `-d`) in CLI mode. `query` still sees all bundled specs and can inspect `specsEnabled` to understand which spec families remain enabled for execute policy:
+
+```sh
+# Disable bundled DTM APIs for execute policy on this CLI connection
+mc8yp -d dtm
+
+# Disable multiple bundled specs if more are added in the future
+mc8yp -d dtm -d core
 ```
 
 ### Microservice Mode (HTTP)
 
-Pass restrictions as `restriction` query parameters on the MCP endpoint URL:
+Pass restrictions as `restriction`, `restrict`, or `r` query parameters on the MCP endpoint URL.
+Pass allow rules as `allowed`, `allow`, or `a` query parameters.
+To forbid bundled OpenAPI parts for execute policy, pass the `openapi-disabled` query parameter.
+You can also send project-scoped HTTP headers to avoid conflicts with well-known headers:
+
+- `mc8yp-restriction` for deny rules
+- `mc8yp-allow` for allow-list rules
+- `mc8yp-openapi-disabled` for bundled OpenAPI part disablement
 
+Both headers accept either repeated header instances or a comma-separated list of values. Query parameters and headers can be combined on the same connection.
+
+```
+/mcp?restriction=/inventory/**&restrict=DELETE:/alarm/**
+/mcp?r=/inventory/**&r=DELETE:/alarm/**
+/mcp?allow=/inventory/**&allowed=POST:/alarm/**
+/mcp?openapi-disabled=dtm
+/mcp?openapi-disabled=dtm&openapi-disabled=core
 ```
-/mcp?restriction=/inventory/**&restriction=DELETE:/alarm/**
+
+```http
+POST /mcp HTTP/1.1
+Authorization: Bearer <token>
+mc8yp-restriction: /inventory/**
+mc8yp-restriction: DELETE:/alarm/**
+mc8yp-allow: GET:/measurement/**
+mc8yp-openapi-disabled: dtm
 ```
 
-### How Restrictions Work
+### How Access Policy Works
+
+1. **Query visibility**: The `query` tool exposes the raw bundled OpenAPI specs for the current MCP connection. Bundled specs are not hidden or rewritten, and the query sandbox exposes `specsEnabled` so the model can see which spec families are enabled for execute policy.
 
-1. **OpenAPI spec annotation**: The `query` tool annotates blocked operations in the spec with `x-mc8yp-restricted` and related `x-mc8yp-*` metadata fields. The operations remain visible so the agent understands what exists, but they are clearly marked as blocked.
+2. **Sandbox request enforcement**: The `execute` tool checks restrictions and allow rules inside the generated sandbox request helper, where the actual HTTP method and normalized path are both available. Matching deny rules block first. If any allow rules are configured, requests must also match at least one allow rule.
 
-2. **Sandbox request enforcement**: The `execute` tool checks restrictions inside the generated sandbox request helper, where the actual HTTP method and normalized path are both available. Matching requests are blocked before any `fetch` is attempted.
+3. **Bundled spec disablement**: When the connection disables bundled OpenAPI parts such as `dtm`, `query` still shows all bundled specs, while the server expands that selection into additional restrictions so `execute` stays path-and-method based.
 
-3. **Network boundary**: The secure-exec permission layer independently restricts network access to the configured tenant host. Other network operations are denied.
+4. **Network boundary**: The secure-exec permission layer independently restricts network access to the configured tenant host. Other network operations are denied.
 
-When an `execute` request is blocked by MCP restrictions, the tool returns explanatory text stating that the operation was intentionally denied by MCP connection policy, no request was sent to Cumulocity, and retrying through the same connection will not help.
+When an `execute` request is blocked by MCP connection policy, the tool returns explanatory text stating whether the operation was denied by a restriction or blocked because it is outside the configured allow list, no request was sent to Cumulocity, and retrying through the same connection will not help.
 
 ## Build And Packaging
 
-The repository bundles multiple core OpenAPI snapshots for CLI use and builds one microservice server bundle per snapshot version.
+The repository bundles multiple OpenAPI specs for CLI use and builds one microservice server bundle per configured build version.
 
 ### Build Outputs
 
@@ -228,7 +340,7 @@ The repository bundles multiple core OpenAPI snapshots for CLI use and builds on
 - CLI bundle in `dist/`
 - Versioned server bundles in `.output/release/`, `.output/2026/`, `.output/2025/`, and `.output/2024/`
 
-The versions built are driven by [`openapi-versions.json`](openapi-versions.json). Each server bundle contains only its own `core-openapi/<version>.json` snapshot.
+The build matrix is driven by [`openapi-builds.json`](openapi-builds.json). Core snapshots live under `openapi/core/`, DTM snapshots live under `openapi/dtm/`, and each server bundle contains the configured combination for that build.
 
 ### Release Packaging
 
@@ -244,10 +356,10 @@ pnpm package:microservices
 
 That command creates one zip per bundled server variant in the repository root, for example:
 
-- `mc8yp-release-v1.2.3.zip`
-- `mc8yp-2026-v1.2.3.zip`
-- `mc8yp-2025-v1.2.3.zip`
-- `mc8yp-2024-v1.2.3.zip`
+- `mc8yp-core-release-dtm-v1.2.3.zip`
+- `mc8yp-core-2026-dtm-v1.2.3.zip`
+- `mc8yp-core-2025-dtm-v1.2.3.zip`
+- `mc8yp-core-2024-dtm-v1.2.3.zip`
 
 The GitHub release workflow uses that packaging command when building tagged releases.
 

package/dist/{add-C-dXxz3k.mjs → add-BecAtXuv.mjs}

@@ -3,6 +3,7 @@ import { defineCommand } from "citty";
 import consola from "consola";
 import * as v from "valibot";
 import { exit } from "node:process";
+import { cancel, isCancel, password } from "@clack/prompts";
 //#region src/cli/subcommands/subcommands/add.ts
 const command = defineCommand({
 	meta: {
@@ -20,10 +21,17 @@ const command = defineCommand({
 				type: "text",
 				cancel: "reject"
 			});
-			const password = await consola.prompt("Password:", {
-				type: "text",
-				cancel: "reject"
+			const passwordPrompt = await password({
+				message: "Password:",
+				clearOnError: true,
+				validate: (value) => {
+					if (!value) return "Password is required.";
+				}
 			});
+			if (isCancel(passwordPrompt)) {
+				cancel("Cancelled.");
+				exit();
+			}
 			if ((await getStoredC8yAuth()).some((cred) => cred.tenantUrl === cleanTenantUrl(tenantUrl))) {
 				if (!await consola.prompt("Credentials for this tenant already exist. Overwrite?", {
 					type: "confirm",
@@ -36,7 +44,7 @@ const command = defineCommand({
 			await setStoredC8yAuth({
 				tenantUrl,
 				user,
-				password
+				password: passwordPrompt
 			});
 			consola.success("Credentials saved successfully!");
 			exit();