@fruggr/zendesk-mcp-server 2.20.2 → 2.21.0

package/README.md

@@ -126,6 +126,10 @@ Signing in needs a Zendesk OAuth client, so register one first (next section).
      `ZENDESK_OAUTH_CALLBACK_PORT` / `--callback-port` if you override it; Zendesk
      accepts several redirect URLs, one per line)
 
+If the client restricts its **allowed scopes**, it needs `read` — plus `write`
+unless the server runs with [`--read-only`](docs/configuration.md), which asks
+Zendesk for the `read` scope alone.
+
 On the first tool call the server starts the sign-in flow: it opens a browser
 window and returns the authorize URL in a tool message. The call does not block
 waiting for sign-in, so authenticate in the browser and then retry the request.

package/dist/index.js

@@ -143,6 +143,48 @@ const getOAuthUrls = (subdomain) => ({
 	tokenUrl: `https://${subdomain}.zendesk.com/oauth/tokens`
 });
 //#endregion
+//#region src/auth/oauth-scopes.ts
+/**
+* The OAuth scope the server asks Zendesk for, and the one predicate that
+* decides whether a cached token's grant is still good enough.
+*
+* Both scope strings live here rather than in `constants.ts` on purpose: they
+* are behavioural strings whose mutants must be killed by assertions
+* (`docs/decisions/mutation-testing.md`, "OAuth parameters and scopes"), and
+* `src/auth/**` is inside the mutation scope while `constants.ts` is not.
+* Keeping them next to the predicate that consumes them keeps both under the
+* same gate.
+*/
+const READ_SCOPE = "read";
+const READ_WRITE_SCOPE = "read write";
+const WHITESPACE = /\s+/;
+const scopeTokens = (scope) => scope.split(WHITESPACE).filter((s) => s.length > 0);
+/**
+* The scope to request for a given tool surface. `--read-only` already filters
+* every write tool out of the surface, so asking Zendesk for `write` on top of
+* that would be requesting an authority the server cannot even exercise — and
+* an OAuth client whose allowed scopes stop at `read` rejects the whole
+* authorize request with `invalid_scope`, minting no token at all (#283).
+*/
+const requestedScope = (readOnly) => readOnly ? READ_SCOPE : READ_WRITE_SCOPE;
+/**
+* The same decision as a list, for the RFC 9728 / RFC 8414 `scopes_supported`
+* metadata. Derived from `requestedScope` so what the HTTP transport advertises
+* provably cannot drift from what the stdio flow requests.
+*/
+const supportedScopes = (readOnly) => scopeTokens(requestedScope(readOnly));
+/**
+* Whether a grant still covers what this process needs: a flat subset test.
+* Coverage, not equality, so a broader token stays usable and two servers
+* sharing a token file converge. A non-string `granted` is a pre-#283 record,
+* i.e. `read write`. No scope hierarchy: granular scopes (#284) replace this.
+*/
+const grantCovers = (granted, requested) => {
+	if (typeof granted !== "string") return true;
+	const held = new Set(scopeTokens(granted));
+	return scopeTokens(requested).every((token) => held.has(token));
+};
+//#endregion
 //#region src/auth/browser-oauth.ts
 const AUTH_TIMEOUT_MS = 3e5;
 /** Best-effort WSL detection: WSL kernels carry "microsoft" in /proc/version. */
@@ -185,7 +227,7 @@ const generateCodeChallenge = (verifier) => createHash("sha256").update(verifier
 * open for up to the 5-minute timeout.
 */
 const startBrowserAuth = (config, logger = silentLogger) => {
-	const { subdomain, oauthClientId } = config;
+	const { subdomain, oauthClientId, readOnly } = config;
 	const { authorizeUrl: authorizeBase, tokenUrl } = getOAuthUrls(subdomain);
 	const codeVerifier = generateCodeVerifier();
 	const codeChallenge = generateCodeChallenge(codeVerifier);
@@ -308,7 +350,7 @@ const startBrowserAuth = (config, logger = silentLogger) => {
 				response_type: "code",
 				client_id: oauthClientId,
 				redirect_uri: redirectUri,
-				scope: "read write",
+				scope: requestedScope(readOnly),
 				code_challenge: codeChallenge,
 				code_challenge_method: "S256"
 			});
@@ -497,8 +539,18 @@ const createAuthRequiredError = (authorizeUrl) => Object.assign(/* @__PURE__ */
 const expiryFrom = (expiresIn) => typeof expiresIn === "number" ? Date.now() + expiresIn * 1e3 : void 0;
 const createTokenStore = (config, logger = silentLogger) => {
 	const tokenPath = resolveTokenPath(config.subdomain);
+	const requested = requestedScope(config.readOnly);
 	let token = loadToken(tokenPath);
-	if (token) logger.debug("oauth_token_loaded_from_disk");
+	if (token) {
+		if (grantCovers(token.scope, requested)) logger.debug("oauth_token_loaded_from_disk");
+		else {
+			logger.warn("oauth_token_scope_insufficient", {
+				requested,
+				granted: token.scope
+			});
+			token = void 0;
+		}
+	}
 	let authorizeUrl;
 	let starting;
 	let refreshing;
@@ -507,12 +559,20 @@ const createTokenStore = (config, logger = silentLogger) => {
 	const setToken = (accessToken, refreshToken) => {
 		token = {
 			accessToken,
-			refreshToken
+			refreshToken,
+			scope: requested
 		};
 		probedUnknownExpiry = false;
 		persist(token);
 	};
 	const needsRefresh = (t) => typeof t.expiresAt === "number" ? Date.now() >= t.expiresAt - EXPIRY_SKEW_MS : t.refreshToken !== void 0 && !probedUnknownExpiry;
+	const noteGrant = (granted) => {
+		if (!grantCovers(granted, requested)) logger.warn("oauth_token_grant_narrowed", {
+			requested,
+			granted
+		});
+		return granted;
+	};
 	const tryRefresh = async (current, { dropOnFailure = true } = {}) => {
 		if (!current.refreshToken) return void 0;
 		try {
@@ -524,7 +584,8 @@ const createTokenStore = (config, logger = silentLogger) => {
 			token = {
 				accessToken: result.access_token,
 				refreshToken: result.refresh_token ?? current.refreshToken,
-				expiresAt: expiryFrom(result.expires_in)
+				expiresAt: expiryFrom(result.expires_in),
+				scope: noteGrant(result.scope || current.scope)
 			};
 			probedUnknownExpiry = true;
 			persist(token);
@@ -544,14 +605,16 @@ const createTokenStore = (config, logger = silentLogger) => {
 		return startBrowserAuth({
 			subdomain: config.subdomain,
 			oauthClientId: config.oauthClientId,
-			callbackPort: config.callbackPort
+			callbackPort: config.callbackPort,
+			readOnly: config.readOnly
 		}, logger).then((started) => {
 			authorizeUrl = started.authorizeUrl;
 			started.tokenPromise.then((result) => {
 				token = {
 					accessToken: result.access_token,
 					refreshToken: result.refresh_token,
-					expiresAt: expiryFrom(result.expires_in)
+					expiresAt: expiryFrom(result.expires_in),
+					scope: noteGrant(result.scope || requested)
 				};
 				probedUnknownExpiry = true;
 				persist(token);
@@ -593,7 +656,8 @@ const createTokenStore = (config, logger = silentLogger) => {
 			token = {
 				accessToken: token.accessToken,
 				refreshToken: token.refreshToken,
-				expiresAt: 0
+				expiresAt: 0,
+				scope: token.scope
 			};
 			persist(token);
 		} else {
@@ -4791,12 +4855,13 @@ const buildOAuthMetadata = (config, logger = silentLogger) => {
 	const { authorizeUrl, tokenUrl } = getOAuthUrls(config.subdomain);
 	const issuer = `https://${config.subdomain}.zendesk.com`;
 	const resource = resolveResourceUrl(config, logger);
+	const scopes = () => supportedScopes(config.readOnly);
 	return {
 		protectedResource: {
 			authorization_servers: [issuer],
 			resource,
 			bearer_methods_supported: ["header"],
-			scopes_supported: ["read", "write"]
+			scopes_supported: scopes()
 		},
 		authorizationServer: {
 			issuer,
@@ -4806,7 +4871,7 @@ const buildOAuthMetadata = (config, logger = silentLogger) => {
 			grant_types_supported: ["authorization_code", "refresh_token"],
 			code_challenge_methods_supported: ["S256"],
 			token_endpoint_auth_methods_supported: ["none"],
-			scopes_supported: ["read", "write"]
+			scopes_supported: scopes()
 		}
 	};
 };
@@ -5129,7 +5194,8 @@ const installShutdown = (options) => {
 const buildStdioTokenStore = (config, logger) => createTokenStore({
 	subdomain: config.subdomain,
 	oauthClientId: config.oauthClientId,
-	callbackPort: config.callbackPort
+	callbackPort: config.callbackPort,
+	readOnly: config.readOnly
 }, logger);
 const connectStdio = async (config, tokenStore, logger) => {
 	if (config.dev) return startDevServer(config, tokenStore.getToken, logger, tokenStore.invalidate);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fruggr/zendesk-mcp-server",
-  "version": "2.20.2",
+  "version": "2.21.0",
   "mcpName": "io.github.fruggr/zendesk-mcp-server",
   "description": "Deep Zendesk MCP server for your AI assistant: search, draft, update and translate Help Center articles and manage Support tickets end to end — comments, triage and image attachments.",
   "type": "module",