backlog-mcp-server 0.20.2 → 0.20.3

package/build/auth/backlogOAuthClient.d.ts

@@ -1,5 +1,29 @@
 import type { BacklogOAuthConfig } from './backlogOAuthConfig.js';
 import type { BacklogTokenData } from './tokenStore.js';
+/**
+ * A failed Backlog token call, carrying what the caller needs to decide what to
+ * tell the client.
+ *
+ * Whether Backlog rejected the credential or could not be reached decides
+ * whether the client should authorize again or back off and retry. Folded into
+ * a message string the two are the same exception, and the caller is left
+ * parsing prose to tell them apart.
+ *
+ * `status` is absent when the request never produced a response — DNS failure,
+ * refused connection, timeout — which is unambiguously the retry case, so "no
+ * status" reads as "not a rejection" without having to guess.
+ *
+ * `errorCode` is the OAuth error code from the response body, which is where
+ * RFC 6749 §5.2 puts the reason. It is the more precise of the two: the status
+ * alone cannot separate `invalid_grant` from `invalid_client`, and those ask
+ * the caller for opposite behaviour. Absent when the body is not an OAuth error
+ * object, which is every response outside the token endpoint.
+ */
+export declare class BacklogTokenError extends Error {
+    readonly status?: number | undefined;
+    readonly errorCode?: string | undefined;
+    constructor(message: string, status?: number | undefined, errorCode?: string | undefined);
+}
 export declare function buildBacklogAuthorizationUrl(config: BacklogOAuthConfig, redirectUri: string, state: string): string;
 export declare function exchangeBacklogCode(config: BacklogOAuthConfig, code: string, redirectUri: string): Promise<BacklogTokenData>;
 export declare function refreshBacklogToken(config: BacklogOAuthConfig, refreshToken: string): Promise<BacklogTokenData>;

package/build/auth/backlogOAuthClient.js

@@ -1,5 +1,56 @@
 // Copyright (c) 2025 Nulab inc.
 // Licensed under the MIT License.
+/**
+ * A failed Backlog token call, carrying what the caller needs to decide what to
+ * tell the client.
+ *
+ * Whether Backlog rejected the credential or could not be reached decides
+ * whether the client should authorize again or back off and retry. Folded into
+ * a message string the two are the same exception, and the caller is left
+ * parsing prose to tell them apart.
+ *
+ * `status` is absent when the request never produced a response — DNS failure,
+ * refused connection, timeout — which is unambiguously the retry case, so "no
+ * status" reads as "not a rejection" without having to guess.
+ *
+ * `errorCode` is the OAuth error code from the response body, which is where
+ * RFC 6749 §5.2 puts the reason. It is the more precise of the two: the status
+ * alone cannot separate `invalid_grant` from `invalid_client`, and those ask
+ * the caller for opposite behaviour. Absent when the body is not an OAuth error
+ * object, which is every response outside the token endpoint.
+ */
+export class BacklogTokenError extends Error {
+    status;
+    errorCode;
+    constructor(message, status, errorCode) {
+        super(message);
+        this.status = status;
+        this.errorCode = errorCode;
+        this.name = 'BacklogTokenError';
+    }
+}
+/**
+ * The `error` field of an RFC 6749 §5.2 error response, if the body is one.
+ *
+ * Best effort by design: a proxy or a WAF can answer the token endpoint with
+ * HTML, and a body that is not an OAuth error object simply carries no code.
+ */
+function readOAuthErrorCode(body) {
+    try {
+        const parsed = JSON.parse(body);
+        if (typeof parsed === 'object' &&
+            parsed !== null &&
+            'error' in parsed &&
+            typeof parsed.error === 'string') {
+            return parsed.error;
+        }
+    }
+    catch {
+        // Not JSON. Nothing to read, and nothing worth reporting either: the
+        // status and the raw text are already in the message.
+    }
+    return undefined;
+}
 export function buildBacklogAuthorizationUrl(config, redirectUri, state) {
     const params = new URLSearchParams({
         response_type: 'code',
@@ -35,23 +86,35 @@ export async function refreshBacklogToken(config, refreshToken) {
         client_secret: config.clientSecret,
         refresh_token: refreshToken,
     });
-    const response = await fetch(`https://${config.backlogDomain}/api/v2/oauth2/token`, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
-        body: params.toString(),
-    });
+    let response;
+    try {
+        response = await fetch(`https://${config.backlogDomain}/api/v2/oauth2/token`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+            body: params.toString(),
+        });
+    }
+    catch (err) {
+        throw new BacklogTokenError(`Could not reach Backlog to refresh the token: ${String(err)}`);
+    }
     if (!response.ok) {
         const text = await response.text();
-        throw new Error(`Backlog token refresh failed (${response.status}): ${text}`);
+        throw new BacklogTokenError(`Backlog token refresh failed (${response.status}): ${text}`, response.status, readOAuthErrorCode(text));
     }
     return await response.json();
 }
 export async function verifyBacklogToken(domain, accessToken) {
-    const response = await fetch(`https://${domain}/api/v2/users/myself`, {
-        headers: { Authorization: `Bearer ${accessToken}` },
-    });
+    let response;
+    try {
+        response = await fetch(`https://${domain}/api/v2/users/myself`, {
+            headers: { Authorization: `Bearer ${accessToken}` },
+        });
+    }
+    catch (err) {
+        throw new BacklogTokenError(`Could not reach Backlog to verify the token: ${String(err)}`);
+    }
     if (!response.ok) {
-        throw new Error(`Backlog token verification failed (${response.status})`);
+        throw new BacklogTokenError(`Backlog token verification failed (${response.status})`, response.status);
     }
     return await response.json();
 }

package/build/auth/bearerAuthMiddleware.js

@@ -1,6 +1,6 @@
 // Copyright (c) 2025 Nulab inc.
 // Licensed under the MIT License.
-import { verifyBacklogToken } from './backlogOAuthClient.js';
+import { BacklogTokenError, verifyBacklogToken } from './backlogOAuthClient.js';
 import { hasBacklogAuthErrorBeenReported, runWithAccessToken, } from './backlogAuthContext.js';
 import { logger } from '../utils/logger.js';
 const CACHE_TTL_MS = 5 * 60 * 1000;
@@ -44,7 +44,27 @@ export function createBearerAuthMiddleware(store, config, mcpPath) {
                 store.cacheVerification(mcpToken, authInfo, CACHE_TTL_MS);
             }
             catch (err) {
-                logger.warn({ err }, 'Bearer token verification failed');
+                // Only Backlog rejecting the token means this client should
+                // authenticate again. A Backlog outage answered with 401 would send
+                // every connected client through the whole authorization flow, and the
+                // token that flow produced would fail verification just the same.
+                const rejected = err instanceof BacklogTokenError &&
+                    (err.status === 401 || err.status === 403);
+                if (!rejected) {
+                    logger.error({ err }, 'Could not verify the bearer token with Backlog');
+                    c.header('Retry-After', '30');
+                    return c.json({
+                        error: 'temporarily_unavailable',
+                        error_description: 'Could not verify the token with Backlog',
+                    }, 503);
+                }
+                // A rejection here is the same fact `onAuthError` below acts on — the
+                // stored Backlog token is spent — so it gets the same treatment.
+                // Dropping the entry is what makes this recoverable: the client's next
+                // request fails the `getMcpToken` check above, and it reaches for its
+                // refresh token instead of replaying a credential that cannot work.
+                logger.warn({ err, clientId: tokenEntry.clientId }, 'Backlog rejected the stored access token during verification; revoking the MCP token');
+                store.revokeMcpToken(mcpToken);
                 return unauthorized('Token verification failed');
             }
         }

package/build/auth/oauthRoutes.js

@@ -2,7 +2,7 @@
 // Licensed under the MIT License.
 import { randomUUID, randomBytes, createHash } from 'node:crypto';
 import { Hono } from 'hono';
-import { buildBacklogAuthorizationUrl, exchangeBacklogCode, refreshBacklogToken, } from './backlogOAuthClient.js';
+import { BacklogTokenError, buildBacklogAuthorizationUrl, exchangeBacklogCode, refreshBacklogToken, } from './backlogOAuthClient.js';
 import { logger } from '../utils/logger.js';
 const AUTH_CODE_TTL_MS = 10 * 60 * 1000;
 const REFRESH_TOKEN_TTL_MS = 30 * 24 * 60 * 60 * 1000; // 30 days
@@ -392,6 +392,34 @@ export function createOAuthRoutes(config, store, mcpPath) {
                 });
             }
             catch (err) {
+                // `invalid_grant` is Backlog stating the grant is gone: revoked from
+                // the user's settings, or a refresh token it no longer recognises.
+                // That is the one answer that moves the client to a fresh
+                // authorization. Reported as 503 the same failure asks it to back off
+                // and retry a grant that can never come back, so it retries on a
+                // schedule forever. The consumed entry stays consumed in this branch:
+                // what it holds is a refresh token Backlog has already disowned, and
+                // keeping it until its TTL lapses only hands the next attempt the same
+                // dead credential.
+                //
+                // The code is read from the body rather than inferred from the status,
+                // because the status cannot separate the two rejections the token
+                // endpoint makes: `invalid_client` rejects *this server's* credentials,
+                // which is the operator's misconfiguration and not the client's grant,
+                // and re-authorizing would fail at the same wall. A bare 400 with no
+                // readable code is still treated as a dead grant — that is what the
+                // status means on this endpoint when nothing more specific is said.
+                //
+                // Everything else leaves the grant's fate unknown — unreachable, a
+                // timeout, a 5xx, a rejected client secret — so the entry goes back and
+                // the client is told to retry.
+                const grantIsGone = err instanceof BacklogTokenError &&
+                    (err.errorCode === 'invalid_grant' ||
+                        (err.status === 400 && err.errorCode === undefined));
+                if (grantIsGone) {
+                    logger.warn({ err, clientId }, 'Backlog no longer recognizes the refresh grant; the client must authorize again');
+                    return c.json(oauthError('invalid_grant', 'Backlog no longer recognizes this grant. A new authorization is required.'), 400);
+                }
                 logger.error({ err }, 'Failed to refresh Backlog token');
                 store.storeMcpRefreshToken(refreshToken, refreshEntry);
                 return c.json(oauthError('server_error', 'Failed to refresh upstream token'), 503);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backlog-mcp-server",
-  "version": "0.20.2",
+  "version": "0.20.3",
   "type": "module",
   "bin": {
     "backlog-mcp-server": "./build/index.js"