fix(remote): translate jose token errors to InvalidTokenError (401) (#398)

* fix(remote): translate jose token errors to InvalidTokenError for RFC-compliant 401

When a Remote mode access token expires, jose's `JWTExpired` (and related
errors like `JWSSignatureVerificationFailed`, `JWTInvalid`, `JWSInvalid`,
`JWTClaimValidationFailed`) propagated from `verifyAccessToken` uncaught.
MCP SDK's `bearerAuth` maps unknown exceptions to a generic 500 `server_error`,
breaking RFC 6750 clients (e.g. Anthropic Managed Agents Vault) that rely on
a 401 `invalid_token` response to trigger transparent `refresh_token` reuse.

- Catch jose errors in `FreeeOAuthProvider.verifyAccessToken` and translate
  them to `InvalidTokenError` so `bearerAuth` emits HTTP 401 +
  `WWW-Authenticate: Bearer error="invalid_token"` as required by RFC 6750
- Call `getCurrentRecorder()?.recordError({ source: 'auth', ... })` before
  throwing so the canonical log captures the real jose error name/message
  instead of the PR #392 `UnrecordedError` safety net fallback
- Add 5 test cases covering expired / wrong-signature / malformed /
  wrong-issuer paths and the `RequestRecorder` enrichment

Fixes #394

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* chore: resolve conflicts with main (gh skill section + contributors)

- README.md: restore gh skill / APM install section added in #397
- README.md: add Kitamura777 and yuyohi contributors from main
- CLAUDE.md: add FREEE_API_BASE_URL env var entry from #407

Co-authored-by: Hiroki Nakashima <him0@users.noreply.github.com>

* docs(changeset): CHANGELOG ガイドラインに合わせて要約に整理

* docs(changeset): Fixes 行を削除（既存 CHANGELOG の慣習に揃える）

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>
Co-authored-by: Hiroki Nakashima <him0@users.noreply.github.com>
Co-authored-by: him0 <him0@freee.co.jp>

Author: 4 people

.changeset/fix-expired-token-401.md

@@ -0,0 +1,8 @@
+---
+"freee-mcp": patch
+---
+
+Remote モードで期限切れアクセストークンが 500 ではなく 401 を返すように修正
+
+- jose のトークン検証例外を `InvalidTokenError` に変換し、`WWW-Authenticate: Bearer error="invalid_token"` 付き HTTP 401 を返す
+- これにより RFC 6750 準拠クライアント（Anthropic Managed Agents Vault など）の `refresh_token` 自動再発行が動作するようになる

README.md

@@ -283,6 +283,7 @@ npx --package=freee-mcp -- freee-sign-mcp configure
 <a href="https://github.com/ryuuuuma"><img src="https://github.com/ryuuuuma.png" width="40" height="40" alt="@ryuuuuma"></a>
 <a href="https://github.com/toyamagu-2021"><img src="https://github.com/toyamagu-2021.png" width="40" height="40" alt="@toyamagu-2021"></a>
 <a href="https://github.com/YasuakiOmokawa"><img src="https://github.com/YasuakiOmokawa.png" width="40" height="40" alt="@YasuakiOmokawa"></a>
+<a href="https://github.com/Ryosuke-Watanabe9"><img src="https://github.com/Ryosuke-Watanabe9.png" width="40" height="40" alt="@Ryosuke-Watanabe9"></a>
 <a href="https://github.com/Kitamura777"><img src="https://github.com/Kitamura777.png" width="40" height="40" alt="@Kitamura777"></a>
 <a href="https://github.com/yuyohi"><img src="https://github.com/yuyohi.png" width="40" height="40" alt="@yuyohi"></a>
 <!-- CONTRIBUTORS-END -->

src/server/oauth-provider.test.ts

@@ -1,12 +1,17 @@
-import { InvalidGrantError } from '@modelcontextprotocol/sdk/server/auth/errors.js';
+import {
+  InvalidGrantError,
+  InvalidTokenError,
+} from '@modelcontextprotocol/sdk/server/auth/errors.js';
 import type { AuthorizationParams } from '@modelcontextprotocol/sdk/server/auth/provider.js';
 import type { OAuthClientInformationFull } from '@modelcontextprotocol/sdk/shared/auth.js';
+import { SignJWT } from 'jose';
 import { describe, expect, it, vi } from 'vitest';
 import type { TokenStore } from '../storage/token-store.js';
 import type { RedisClientStore } from './client-store.js';
 import type { FreeeOAuthProviderDeps } from './oauth-provider.js';
 import { FreeeOAuthProvider } from './oauth-provider.js';
 import type { AuthCodeData, OAuthStateStore, RefreshTokenData } from './oauth-store.js';
+import { RequestRecorder, withRequestRecorder } from './request-context.js';
 
 const TEST_SECRET = 'test-jwt-secret-long-enough-for-hmac-signing';
 const TEST_ISSUER = 'https://mcp.example.com';
@@ -287,10 +292,91 @@ describe('FreeeOAuthProvider', () => {
       expect(authInfo.extra?.tokenStore).toBe(tokenStore);
     });
 
-    it('rejects invalid JWT', async () => {
+    it('rejects a malformed (non-JWT) token as InvalidTokenError', async () => {
       const { provider } = createProvider();
 
-      await expect(provider.verifyAccessToken('invalid-jwt')).rejects.toThrow();
+      await expect(provider.verifyAccessToken('invalid-jwt')).rejects.toThrow(InvalidTokenError);
+    });
+
+    it('maps jose JWTExpired to InvalidTokenError("Token has expired")', async () => {
+      const { provider } = createProvider();
+      const pastTime = Math.floor(Date.now() / 1000) - 7200;
+      const expiredToken = await new SignJWT({ scope: 'mcp:read', client_id: 'test-client-id' })
+        .setProtectedHeader({ alg: 'HS256' })
+        .setSubject('user-1')
+        .setIssuer(TEST_ISSUER)
+        .setIssuedAt(pastTime)
+        .setExpirationTime(pastTime + 3600)
+        .sign(new TextEncoder().encode(TEST_SECRET));
+
+      await expect(provider.verifyAccessToken(expiredToken)).rejects.toThrow(
+        new InvalidTokenError('Token has expired'),
+      );
+    });
+
+    it('maps jose JWSSignatureVerificationFailed to InvalidTokenError', async () => {
+      const { provider } = createProvider();
+      const foreignToken = await new SignJWT({ scope: 'mcp:read', client_id: 'test-client-id' })
+        .setProtectedHeader({ alg: 'HS256' })
+        .setSubject('user-1')
+        .setIssuer(TEST_ISSUER)
+        .setIssuedAt()
+        .setExpirationTime('1h')
+        .sign(new TextEncoder().encode('different-jwt-secret-long-enough-for-hmac-signing'));
+
+      await expect(provider.verifyAccessToken(foreignToken)).rejects.toThrow(
+        new InvalidTokenError('Invalid token signature'),
+      );
+    });
+
+    it('maps jose JWTClaimValidationFailed (wrong issuer) to InvalidTokenError', async () => {
+      const { provider } = createProvider();
+      const wrongIssuerToken = await new SignJWT({ scope: 'mcp:read', client_id: 'test-client-id' })
+        .setProtectedHeader({ alg: 'HS256' })
+        .setSubject('user-1')
+        .setIssuer('https://wrong.example.com')
+        .setIssuedAt()
+        .setExpirationTime('1h')
+        .sign(new TextEncoder().encode(TEST_SECRET));
+
+      await expect(provider.verifyAccessToken(wrongIssuerToken)).rejects.toThrowError(
+        InvalidTokenError,
+      );
+    });
+
+    it('records auth error to the current RequestRecorder on expired token', async () => {
+      const { provider } = createProvider();
+      const pastTime = Math.floor(Date.now() / 1000) - 7200;
+      const expiredToken = await new SignJWT({ scope: 'mcp:read', client_id: 'test-client-id' })
+        .setProtectedHeader({ alg: 'HS256' })
+        .setSubject('user-1')
+        .setIssuer(TEST_ISSUER)
+        .setIssuedAt(pastTime)
+        .setExpirationTime(pastTime + 3600)
+        .sign(new TextEncoder().encode(TEST_SECRET));
+
+      const recorder = new RequestRecorder({
+        request_id: 'req-1',
+        source_ip: '127.0.0.1',
+        method: 'POST',
+        path: '/mcp',
+      });
+
+      await withRequestRecorder(recorder, async () => {
+        await expect(provider.verifyAccessToken(expiredToken)).rejects.toThrow(InvalidTokenError);
+      });
+
+      const payload = recorder.buildPayload({ status: 401, duration_ms: 1 });
+      expect(payload.errors).toHaveLength(1);
+      expect(payload.errors[0]).toMatchObject({
+        source: 'auth',
+        status_code: 401,
+        error_type: 'invalid_token',
+      });
+      expect(payload.errors[0]?.chain[0]).toMatchObject({
+        name: 'JWTExpired',
+        message: 'Token has expired',
+      });
     });
   });
 

src/server/oauth-provider.ts

@@ -1,6 +1,9 @@
 import { randomUUID } from 'node:crypto';
 import type { OAuthRegisteredClientsStore } from '@modelcontextprotocol/sdk/server/auth/clients.js';
-import { InvalidGrantError } from '@modelcontextprotocol/sdk/server/auth/errors.js';
+import {
+  InvalidGrantError,
+  InvalidTokenError,
+} from '@modelcontextprotocol/sdk/server/auth/errors.js';
 import type {
   AuthorizationParams,
   OAuthServerProvider,
@@ -16,8 +19,10 @@ import { generatePKCE } from '../auth/oauth.js';
 import { FREEE_CALLBACK_PATH } from '../constants.js';
 import type { TokenStore } from '../storage/token-store.js';
 import type { RedisClientStore } from './client-store.js';
-import { signAccessToken, verifyAccessToken as verifyJwt } from './jwt.js';
+import { makeErrorChain } from './error-serializer.js';
+import { joseErrors, signAccessToken, verifyAccessToken as verifyJwt } from './jwt.js';
 import type { OAuthStateStore } from './oauth-store.js';
+import { getCurrentRecorder } from './request-context.js';
 
 export interface FreeeOAuthProviderDeps {
   clientStore: RedisClientStore;
@@ -138,7 +143,27 @@ export class FreeeOAuthProvider implements OAuthServerProvider {
   }
 
   async verifyAccessToken(token: string): Promise<AuthInfo> {
-    const payload = await verifyJwt(token, this.deps.jwtSecret, this.deps.issuerUrl);
+    let payload: Awaited<ReturnType<typeof verifyJwt>>;
+    try {
+      payload = await verifyJwt(token, this.deps.jwtSecret, this.deps.issuerUrl);
+    } catch (err) {
+      const mapped = mapJoseErrorToInvalidToken(err);
+      if (mapped) {
+        // Explicitly record so the canonical log surfaces the real jose cause
+        // instead of the PR #392 `UnrecordedError` safety net fallback.
+        getCurrentRecorder()?.recordError({
+          source: 'auth',
+          status_code: 401,
+          error_type: 'invalid_token',
+          chain: makeErrorChain(
+            err instanceof Error ? err.name : 'UnknownJoseError',
+            mapped.message,
+          ),
+        });
+        throw mapped;
+      }
+      throw err;
+    }
     return {
       token,
       clientId: payload.client_id,
@@ -186,3 +211,23 @@ export class FreeeOAuthProvider implements OAuthServerProvider {
     };
   }
 }
+
+// jose throws its own error classes that the MCP SDK bearerAuth middleware
+// does not recognize, so we translate the common token-validity failures into
+// `InvalidTokenError` to produce a spec-compliant 401 + WWW-Authenticate
+// response. See issue #394.
+function mapJoseErrorToInvalidToken(err: unknown): InvalidTokenError | null {
+  if (err instanceof joseErrors.JWTExpired) {
+    return new InvalidTokenError('Token has expired');
+  }
+  if (err instanceof joseErrors.JWSSignatureVerificationFailed) {
+    return new InvalidTokenError('Invalid token signature');
+  }
+  if (err instanceof joseErrors.JWTInvalid || err instanceof joseErrors.JWSInvalid) {
+    return new InvalidTokenError('Malformed token');
+  }
+  if (err instanceof joseErrors.JWTClaimValidationFailed) {
+    return new InvalidTokenError(`Invalid token claim: ${err.message}`);
+  }
+  return null;
+}