mcp-connectwise-psa 0.2.0 → 0.3.0

package/dist/tools/toolsets.js

@@ -0,0 +1,83 @@
+/**
+ * Toolsets — capability groups that can be enabled per session.
+ *
+ * A session exposes only the tools in its selected toolsets, so a dispatcher
+ * or a billing user isn't shown the full technician surface. Selection comes
+ * from the `x-cw-toolsets` header (HTTP) or the `CW_TOOLSETS` env / `--toolsets`
+ * flag (stdio); both accept a comma-separated list mixing capability keys and
+ * persona presets. This is a surface/usability filter, not access control —
+ * ConnectWise still enforces the member's real security role.
+ */
+export const TOOLSET_KEYS = [
+    "tickets",
+    "time",
+    "companies",
+    "configurations",
+    "schedule",
+    "finance",
+];
+const TECH = ["tickets", "time", "companies", "configurations"];
+/** Persona presets — convenient shortcuts that expand to a set of keys. */
+export const PRESETS = {
+    tech: TECH,
+    dispatch: ["tickets", "schedule", "companies", "configurations"],
+    invoicing: ["finance", "time", "companies"],
+    all: [...TOOLSET_KEYS],
+};
+/** The default selection when nothing is specified — today's technician surface. */
+export const DEFAULT_TOOLSETS = TECH;
+const KEY_SET = new Set(TOOLSET_KEYS);
+function isToolsetKey(value) {
+    return KEY_SET.has(value);
+}
+export class UnknownToolsetError extends Error {
+}
+/**
+ * Resolve a raw comma-separated list (keys and/or preset names) to a deduped,
+ * order-stable list of toolset keys.
+ *
+ * @param raw       the header / env value, or undefined/empty
+ * @param fallback  used when `raw` is undefined/blank/only-separators
+ * @param onUnknown "throw" (config/env — fail loudly) or "warn" (request header —
+ *                  ignore the bad token, keep the rest, never 500)
+ */
+export function resolveToolsets(raw, fallback, onUnknown = "throw") {
+    const tokens = (raw ?? "")
+        .split(",")
+        .map((t) => t.trim().toLowerCase())
+        .filter((t) => t.length > 0);
+    if (tokens.length === 0)
+        return dedupe(fallback);
+    const keys = [];
+    for (const token of tokens) {
+        const preset = PRESETS[token];
+        if (preset) {
+            keys.push(...preset);
+        }
+        else if (isToolsetKey(token)) {
+            keys.push(token);
+        }
+        else if (onUnknown === "throw") {
+            throw new UnknownToolsetError(`Unknown toolset "${token}" — expected keys (${TOOLSET_KEYS.join(", ")}) ` +
+                `or presets (${Object.keys(PRESETS).join(", ")}).`);
+        }
+        else {
+            console.error(`[toolsets] ignoring unknown toolset "${token}" in x-cw-toolsets header.`);
+        }
+    }
+    const resolved = dedupe(keys);
+    // An all-unknown "warn" list would otherwise silently expose nothing.
+    return resolved.length > 0 ? resolved : dedupe(fallback);
+}
+/** Dedupe while preserving first-seen order and TOOLSET_KEYS ordering intent. */
+function dedupe(keys) {
+    const seen = new Set();
+    const out = [];
+    for (const key of keys) {
+        if (!seen.has(key)) {
+            seen.add(key);
+            out.push(key);
+        }
+    }
+    return out;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-connectwise-psa",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "MCP server for ConnectWise PSA (Manage) — tickets, time entries, companies, and configurations for technicians, with per-tech API keys (BYOK) so writes are attributed to the real member",
   "mcpName": "io.github.selic/mcp-connectwise-psa",
   "type": "module",

package/dist/auth/roles.js

@@ -1,74 +0,0 @@
-/**
- * Role-based tool gating.
- *
- * Every tool belongs to a tier. The tier is derived from the tool's MCP
- * annotations (readOnlyHint / destructiveHint) unless the tool declares an
- * explicit `tier` override — used when the RBAC intent differs from the
- * annotation (e.g. deleting a document section is destructive for clients,
- * but editors need it to restructure documents).
- *
- * Enforcement is two-layered:
- *  1. Tools outside the session's role are never registered, so they don't
- *     even appear in tools/list.
- *  2. Registered handlers are wrapped with a runtime re-check, so a
- *     registration bug can never reach the IT Glue client.
- */
-const TIER_ROLES = {
-    read: ["viewer", "editor", "admin"],
-    write: ["editor", "admin"],
-    destructive: ["admin"],
-};
-export function tierOf(spec) {
-    if (spec.tier)
-        return spec.tier;
-    if (spec.annotations.readOnlyHint === true)
-        return "read";
-    if (spec.annotations.destructiveHint === true)
-        return "destructive";
-    return "write";
-}
-export function roleAllows(role, tier) {
-    return TIER_ROLES[tier].includes(role);
-}
-/** Minimum role that can use a tier — for error messages. */
-function tierRequires(tier) {
-    return TIER_ROLES[tier][0] === "viewer" ? "viewer" : tier === "write" ? "editor" : "admin";
-}
-/**
- * Registers tools on an McpServer, filtered and guarded by the session role.
- */
-export class ToolRegistrar {
-    server;
-    role;
-    constructor(server, role) {
-        this.server = server;
-        this.role = role;
-    }
-    register(spec, handler) {
-        const tier = tierOf(spec);
-        if (!roleAllows(this.role, tier)) {
-            return; // tool is invisible to this session
-        }
-        const role = this.role;
-        const guarded = async (args) => {
-            if (!roleAllows(role, tier)) {
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: `Error: ${spec.name} requires the ${tierRequires(tier)} role; this session is authenticated as ${role}.`,
-                        },
-                    ],
-                    isError: true,
-                };
-            }
-            return handler(args);
-        };
-        this.server.registerTool(spec.name, {
-            title: spec.title,
-            description: spec.description,
-            inputSchema: spec.inputSchema,
-            annotations: spec.annotations,
-        }, guarded);
-    }
-}

package/dist/auth/tokens.js

@@ -1,93 +0,0 @@
-/**
- * Bearer-token authentication with per-role token pools.
- *
- * Tokens are configured through three environment variables, one per role:
- *
- *   MCP_TOKENS_VIEWER="alice:tok1,bob:tok2"
- *   MCP_TOKENS_EDITOR="automation:tok3"
- *   MCP_TOKENS_ADMIN="ops:tok4"
- *
- * Each entry is `label:token`; the label identifies the holder in audit logs
- * and lets individual tokens be revoked. Entries without a label get an
- * auto-generated one (`viewer-1`, ...). Tokens must be unique across roles —
- * duplicates are dropped with a warning.
- */
-import { timingSafeEqual } from "node:crypto";
-const ROLE_ENV_VARS = [
-    ["viewer", "MCP_TOKENS_VIEWER"],
-    ["editor", "MCP_TOKENS_EDITOR"],
-    ["admin", "MCP_TOKENS_ADMIN"],
-];
-export function parseTokenList(raw, role) {
-    const entries = [];
-    let unlabeled = 0;
-    for (const piece of raw.split(",")) {
-        const trimmed = piece.trim();
-        if (!trimmed)
-            continue;
-        const sep = trimmed.indexOf(":");
-        if (sep > 0 && sep < trimmed.length - 1) {
-            entries.push({
-                role,
-                label: trimmed.slice(0, sep).trim(),
-                token: trimmed.slice(sep + 1).trim(),
-            });
-        }
-        else {
-            unlabeled += 1;
-            entries.push({ role, label: `${role}-${unlabeled}`, token: trimmed.replace(/^:|:$/g, "") });
-        }
-    }
-    return entries.filter((e) => e.token.length > 0);
-}
-/** Load all configured token entries; duplicate token values are dropped. */
-export function loadTokenEntries(env = process.env) {
-    const entries = [];
-    for (const [role, envVar] of ROLE_ENV_VARS) {
-        const raw = env[envVar];
-        if (raw)
-            entries.push(...parseTokenList(raw, role));
-    }
-    const seen = new Set();
-    return entries.filter((entry) => {
-        if (seen.has(entry.token)) {
-            console.error(`[auth] Warning: duplicate token for "${entry.label}" (${entry.role}) ignored — tokens must be unique across roles.`);
-            return false;
-        }
-        seen.add(entry.token);
-        return true;
-    });
-}
-/** Timing-safe string comparison for secrets. */
-export function safeEquals(a, b) {
-    const bufA = Buffer.from(a, "utf-8");
-    const bufB = Buffer.from(b, "utf-8");
-    if (bufA.length !== bufB.length)
-        return false;
-    try {
-        return timingSafeEqual(bufA, bufB);
-    }
-    catch {
-        return false;
-    }
-}
-/** Extract the token from an `Authorization: Bearer <token>` header. */
-export function bearerToken(authorizationHeader) {
-    if (!authorizationHeader)
-        return null;
-    const parts = authorizationHeader.split(" ");
-    if (parts.length !== 2 || parts[0] !== "Bearer" || !parts[1])
-        return null;
-    return parts[1];
-}
-/** Match an Authorization header against the configured tokens. */
-export function authenticateToken(authorizationHeader, entries) {
-    const presented = bearerToken(authorizationHeader);
-    if (!presented)
-        return null;
-    for (const entry of entries) {
-        if (safeEquals(presented, entry.token))
-            return entry;
-    }
-    return null;
-}