backlog-mcp-server 0.20.2 → 0.20.4

package/build/auth/backlogOAuthClient.d.ts

@@ -1,5 +1,55 @@
 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);
+}
+/**
+ * Whether the failure is Backlog stating the grant is gone.
+ *
+ * The one answer that means the client should stop retrying and start a fresh
+ * authorization. Everything else leaves the grant's fate unknown, and a client
+ * told to re-authorize on a transient failure throws away a grant that was
+ * still alive.
+ *
+ * Read from `errorCode` rather than inferred from the status, because the
+ * status cannot separate the two rejections a token endpoint makes:
+ * `invalid_client` rejects the *server's* own credentials, which is the
+ * operator's misconfiguration and not the client's grant — re-authorizing would
+ * fail at the same wall. A bare 400 with no readable code is still a dead
+ * grant: that is what the status means on this endpoint when nothing more
+ * specific is said.
+ */
+export declare function isGrantGone(err: unknown): boolean;
+/**
+ * Whether Backlog rejected the credential, as opposed to failing to answer.
+ *
+ * Only a rejection means the caller should authenticate again. An outage
+ * treated as a rejection sends every connected client through the whole
+ * authorization flow, and the credential that flow produces fails the same way
+ * — after the client has already lost the one it had.
+ */
+export declare function isTokenRejected(err: unknown): boolean;
 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,89 @@
 // 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;
+}
+/**
+ * Whether the failure is Backlog stating the grant is gone.
+ *
+ * The one answer that means the client should stop retrying and start a fresh
+ * authorization. Everything else leaves the grant's fate unknown, and a client
+ * told to re-authorize on a transient failure throws away a grant that was
+ * still alive.
+ *
+ * Read from `errorCode` rather than inferred from the status, because the
+ * status cannot separate the two rejections a token endpoint makes:
+ * `invalid_client` rejects the *server's* own credentials, which is the
+ * operator's misconfiguration and not the client's grant — re-authorizing would
+ * fail at the same wall. A bare 400 with no readable code is still a dead
+ * grant: that is what the status means on this endpoint when nothing more
+ * specific is said.
+ */
+export function isGrantGone(err) {
+    return (err instanceof BacklogTokenError &&
+        (err.errorCode === 'invalid_grant' ||
+            (err.status === 400 && err.errorCode === undefined)));
+}
+/**
+ * Whether Backlog rejected the credential, as opposed to failing to answer.
+ *
+ * Only a rejection means the caller should authenticate again. An outage
+ * treated as a rejection sends every connected client through the whole
+ * authorization flow, and the credential that flow produces fails the same way
+ * — after the client has already lost the one it had.
+ */
+export function isTokenRejected(err) {
+    return (err instanceof BacklogTokenError &&
+        (err.status === 401 || err.status === 403));
+}
 export function buildBacklogAuthorizationUrl(config, redirectUri, state) {
     const params = new URLSearchParams({
         response_type: 'code',
@@ -35,23 +119,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 { isTokenRejected, 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,24 @@ 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; `isTokenRejected` holds why the distinction
+                // matters.
+                if (!isTokenRejected(err)) {
+                    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 { buildBacklogAuthorizationUrl, exchangeBacklogCode, isGrantGone, 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,19 @@ export function createOAuthRoutes(config, store, mcpPath) {
                 });
             }
             catch (err) {
+                // A dead grant is the one failure the client can act on, and
+                // `isGrantGone` holds the reasoning for which failures those are. The
+                // consumed entry stays consumed here: 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.
+                //
+                // 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.
+                if (isGrantGone(err)) {
+                    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/build/lib.d.ts

@@ -11,6 +11,12 @@
  * is the counter-example worth remembering: it reads the override file from disk,
  * so it belongs to the CLI and is deliberately absent below. Consumers on other
  * runtimes pass their own overrides to `createDescriptionHelper`.
+ *
+ * The OAuth exports are the token calls and the two predicates that say what a
+ * failure means. The routes and the middleware are absent: they are built
+ * against this package's synchronous `TokenStore` and Hono, so a consumer on
+ * its own storage cannot reuse them. The judgement travels, the plumbing does
+ * not.
  */
 export { allTools } from './tools/tools.js';
 export { composeToolHandler } from './handlers/builders/composeToolHandler.js';
@@ -19,9 +25,12 @@ export { createDescriptionHelper } from './createDescriptionHelper.js';
 export { backlogErrorHandler } from './backlog/backlogErrorHandler.js';
 export { buildToolSchema } from './types/tool.js';
 export { isErrorLike } from './types/result.js';
+export { BacklogTokenError, buildBacklogAuthorizationUrl, exchangeBacklogCode, isGrantGone, isTokenRejected, refreshBacklogToken, verifyBacklogToken, } from './auth/backlogOAuthClient.js';
 export type { ComposeOptions } from './handlers/builders/composeToolHandler.js';
 export type { ComposeNativeContentOptions } from './handlers/builders/composeNativeContentToolHandler.js';
 export type { DescriptionHelper } from './createDescriptionHelper.js';
 export type { ToolDefinition, NativeContentToolDefinition, } from './types/tool.js';
 export type { Toolset, ToolsetGroup } from './types/toolsets.js';
 export type { ErrorLike, SafeResult } from './types/result.js';
+export type { BacklogOAuthConfig } from './auth/backlogOAuthConfig.js';
+export type { BacklogTokenData } from './auth/tokenStore.js';

package/build/lib.js

@@ -11,6 +11,12 @@
  * is the counter-example worth remembering: it reads the override file from disk,
  * so it belongs to the CLI and is deliberately absent below. Consumers on other
  * runtimes pass their own overrides to `createDescriptionHelper`.
+ *
+ * The OAuth exports are the token calls and the two predicates that say what a
+ * failure means. The routes and the middleware are absent: they are built
+ * against this package's synchronous `TokenStore` and Hono, so a consumer on
+ * its own storage cannot reuse them. The judgement travels, the plumbing does
+ * not.
  */
 export { allTools } from './tools/tools.js';
 export { composeToolHandler } from './handlers/builders/composeToolHandler.js';
@@ -19,3 +25,4 @@ export { createDescriptionHelper } from './createDescriptionHelper.js';
 export { backlogErrorHandler } from './backlog/backlogErrorHandler.js';
 export { buildToolSchema } from './types/tool.js';
 export { isErrorLike } from './types/result.js';
+export { BacklogTokenError, buildBacklogAuthorizationUrl, exchangeBacklogCode, isGrantGone, isTokenRejected, refreshBacklogToken, verifyBacklogToken, } from './auth/backlogOAuthClient.js';

package/package.json

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