backlog-mcp-server 0.20.3 → 0.20.4

package/build/auth/backlogOAuthClient.d.ts

@@ -24,6 +24,32 @@ export declare class BacklogTokenError extends Error {
     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

@@ -51,6 +51,39 @@ function readOAuthErrorCode(body) {
     }
     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',

package/build/auth/bearerAuthMiddleware.js

@@ -1,6 +1,6 @@
 // Copyright (c) 2025 Nulab inc.
 // Licensed under the MIT License.
-import { BacklogTokenError, 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;
@@ -45,12 +45,9 @@ export function createBearerAuthMiddleware(store, config, mcpPath) {
             }
             catch (err) {
                 // 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) {
+                // 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({

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 { BacklogTokenError, 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,31 +392,16 @@ 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.
+                // 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.
-                const grantIsGone = err instanceof BacklogTokenError &&
-                    (err.errorCode === 'invalid_grant' ||
-                        (err.status === 400 && err.errorCode === undefined));
-                if (grantIsGone) {
+                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);
                 }

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.3",
+  "version": "0.20.4",
   "type": "module",
   "bin": {
     "backlog-mcp-server": "./build/index.js"