From 0e5d9c430f8027829dc4e2b10a1add46ccf73691 Mon Sep 17 00:00:00 2001 From: Christoph Dyllick-Brenzinger Date: Wed, 18 Nov 2026 19:48:45 +0100 Subject: [PATCH] Log why sessions and OAuth authorizations fail, not just that they did (v1.9.8) The production log after v1.9.7 raised three questions it could not answer. "seatable-mcp started" appeared before every session, because buildServer() runs once per HTTP session and logged it. It read like constant restarts and made up half the log. It is now logged once per process, by startHttpServer() (with mode, tool count, host, port) and by the stdio entry point. buildServer() logs "MCP server built" at debug. Most sessions were preceded by "Initialize request ended without a session" with status 400. Every POST without a session ID is treated as initialize; when it is something else, the SDK answers 400 and reports why only through transport.onerror, which was not set. The line now carries the SDK's reason and the JSON-RPC method(s) of the body. Methods that don't look like protocol names are logged as "invalid". "OAuth authorize rejected: unknown or expired client registration" came in bursts with no fields at all. It now logs ip, callback, a fingerprint of the client_id (the same one the refresh log uses) and a reason from the new TokenCipher.inspect(): missing, foreign (not our envelope), invalid (forged or sealed under another secret) or expired. Co-Authored-By: Claude Opus 5.5 --- docs/openai-tunnel.md | 2 +- package-lock.json | 4 +-- package.json | 2 +- src/auth/oauthProvider.ts | 19 +++++++++++--- src/auth/tokenCipher.ts | 35 ++++++++++++++++++++----- src/http/httpServer.ts | 45 ++++++++++++++++++++++++++++++-- src/index.ts | 1 + src/mcp/server.ts | 7 +++-- tests/connectionSlots.spec.ts | 23 +++++++++++++++- tests/oauthObservability.spec.ts | 41 +++++++++++++++++++++++++++++ tests/tokenCipher.spec.ts | 27 +++++++++++++++++++ 11 files changed, 185 insertions(+), 21 deletions(-) diff --git a/docs/openai-tunnel.md b/docs/openai-tunnel.md index 3570139..86be128 100644 --- a/docs/openai-tunnel.md +++ b/docs/openai-tunnel.md @@ -98,7 +98,7 @@ The MCP server can be started and tested before the tunnel exists: ```bash docker compose up -d seatable-mcp -docker compose logs seatable-mcp # expect "Streamable HTTP server listening" +docker compose logs seatable-mcp # expect "seatable-mcp started" docker run --rm --network seatable-mcp_mcp-net curlimages/curl -s \ -X POST http://seatable-mcp:3000/mcp \ diff --git a/package-lock.json b/package-lock.json index 2d8f915..3140cd9 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "@seatable/mcp-seatable", - "version": "1.9.7", + "version": "1.9.8", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "@seatable/mcp-seatable", - "version": "1.9.7", + "version": "1.9.8", "license": "MIT", "dependencies": { "@modelcontextprotocol/sdk": "^1.17.4", diff --git a/package.json b/package.json index d092108..e1cc812 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@seatable/mcp-seatable", - "version": "1.9.7", + "version": "1.9.8", "type": "module", "license": "MIT", "mcpName": "io.github.seatable/seatable", diff --git a/src/auth/oauthProvider.ts b/src/auth/oauthProvider.ts index 6c6629c..776be08 100644 --- a/src/auth/oauthProvider.ts +++ b/src/auth/oauthProvider.ts @@ -383,12 +383,25 @@ export class OAuthProvider { const codeChallenge = pick('code_challenge') const codeChallengeMethod = pick('code_challenge_method') - const client = clientId ? this.cipher.open('client', clientId) : undefined - if (!client) { - logger.warn('OAuth authorize rejected: unknown or expired client registration') + const opened = this.cipher.inspect('client', clientId) + if (!('payload' in opened)) { + // A client that keeps presenting a stale client_id shows up as a burst + // of these. `clientId` (the same fingerprint as in the refresh log) + // groups the burst; `reason` says whether the registration expired, + // was sealed under another secret, or was never ours. + logger.warn( + { + reason: opened.reason, + ip: this.clientIp(req), + ...(clientId && { clientId: fingerprint(clientId) }), + ...(redirectUri && { callback: safeCallback(redirectUri) }), + }, + 'OAuth authorize rejected: unknown or expired client registration' + ) this.authorizeError(res, 'Unknown client', 'This application is not registered with SeaTable MCP, or its registration has expired. Nothing has been sent to it.') return } + const client = opened.payload if (responseType !== 'code') { this.authorizeError(res, 'Unsupported request', 'Only the authorization code flow is supported.') diff --git a/src/auth/tokenCipher.ts b/src/auth/tokenCipher.ts index b656f26..7c78472 100644 --- a/src/auth/tokenCipher.ts +++ b/src/auth/tokenCipher.ts @@ -29,6 +29,8 @@ export interface SealedPayload { [key: string]: unknown } +export type RejectReason = 'missing' | 'foreign' | 'invalid' | 'expired' + export class TokenCipher { private readonly key: Buffer @@ -51,12 +53,31 @@ export class TokenCipher { /** Returns the payload, or undefined if the value is forged, tampered with, of the wrong kind, or expired. */ open = Record>(kind: TokenKind, value: string): (T & SealedPayload) | undefined { + const result = this.inspect(kind, value) + return 'payload' in result ? result.payload : undefined + } + + /** + * Like open(), but says why a value was rejected, for logs: + * - `missing`: empty. + * - `foreign`: not one of our envelopes of this kind — typically a value + * issued by another server, or a different kind of ours. + * - `invalid`: our prefix, but it doesn't authenticate. Forged, truncated, + * or sealed under a different SEATABLE_TOKEN_SECRET. + * - `expired`: genuine, but past its expiry. + */ + inspect = Record>( + kind: TokenKind, + value: string + ): { payload: T & SealedPayload } | { reason: RejectReason } { + if (typeof value !== 'string' || value === '') return { reason: 'missing' } const prefix = PREFIX[kind] - if (typeof value !== 'string' || !value.startsWith(prefix)) return undefined + if (!value.startsWith(prefix)) return { reason: 'foreign' } + let payload: T & SealedPayload try { const raw = Buffer.from(value.slice(prefix.length), 'base64url') - if (raw.length <= NONCE_BYTES + TAG_BYTES) return undefined + if (raw.length <= NONCE_BYTES + TAG_BYTES) return { reason: 'invalid' } const nonce = raw.subarray(0, NONCE_BYTES) const ciphertext = raw.subarray(NONCE_BYTES, raw.length - TAG_BYTES) @@ -66,13 +87,13 @@ export class TokenCipher { decipher.setAAD(Buffer.from(kind)) decipher.setAuthTag(tag) const plaintext = Buffer.concat([decipher.update(ciphertext), decipher.final()]).toString('utf-8') - - const payload = JSON.parse(plaintext) as T & SealedPayload - if (typeof payload.exp !== 'number' || Date.now() >= payload.exp) return undefined - return payload + payload = JSON.parse(plaintext) as T & SealedPayload } catch { // Any failure — bad base64, failed auth tag, malformed JSON — is a rejection. - return undefined + return { reason: 'invalid' } } + if (typeof payload.exp !== 'number') return { reason: 'invalid' } + if (Date.now() >= payload.exp) return { reason: 'expired' } + return { payload } } } diff --git a/src/http/httpServer.ts b/src/http/httpServer.ts index da93eaa..5a57579 100644 --- a/src/http/httpServer.ts +++ b/src/http/httpServer.ts @@ -69,6 +69,28 @@ async function parseJsonBody(req: IncomingMessage): Promise { }) } +/** + * The JSON-RPC method(s) of a request body, for logs. A POST without a session + * ID is treated as initialize; when it is something else the SDK answers 400, + * and the method says what the client was really trying to do. Method names are + * protocol vocabulary, never customer content, but they come from the caller, + * so anything that doesn't look like one is reduced to `invalid`. + */ +export function jsonRpcMethods(body: unknown): string { + const one = (message: unknown): string => { + if (typeof message !== 'object' || message === null) return 'invalid' + const method = (message as { method?: unknown }).method + if (method === undefined) return 'result' in message || 'error' in message ? 'response' : 'invalid' + return typeof method === 'string' && /^[A-Za-z0-9_./-]{1,64}$/.test(method) ? method : 'invalid' + } + if (Array.isArray(body)) { + const methods = body.slice(0, 5).map(one) + if (body.length > 5) methods.push('...') + return methods.join(',') || 'empty' + } + return body === undefined ? 'empty' : one(body) +} + /** * Hosts allowed as remote https callbacks in the OAuth flow. Unset means the * built-in list of hosted MCP clients; '*' disables curation (dangerous). @@ -380,6 +402,13 @@ export async function startHttpServer(options: StartHttpServerOptions = {}) { void cleanup() } + // Set before connect(): the SDK chains its own handler onto this one. + // It is the only place the reason for an SDK-generated 400 surfaces. + let transportError: string | undefined + transport.onerror = (error) => { + transportError ??= error.message.slice(0, 200) + } + /* * An initialize request that never produces a session — a malformed * body the SDK rejects, a client that hangs up, a transport error — @@ -393,7 +422,13 @@ export async function startHttpServer(options: StartHttpServerOptions = {}) { return } logger.info( - { ip: getClientIp(req), status: res.statusCode, ...(apiToken && { token: tokenFingerprint(apiToken) }) }, + { + ip: getClientIp(req), + status: res.statusCode, + method: jsonRpcMethods(body), + ...(transportError && { reason: transportError }), + ...(apiToken && { token: tokenFingerprint(apiToken) }), + }, 'Initialize request ended without a session' ) void cleanup() @@ -603,7 +638,13 @@ export async function startHttpServer(options: StartHttpServerOptions = {}) { server.listen(port, host) }) - logger.info({ host, port, endpoint: '/mcp' }, 'Streamable HTTP server listening') + logger.info({ + mode: env.SEATABLE_MOCK ? 'mock' : mode, + tools: getStaticToolDefinitions().length, + host, + port, + endpoint: '/mcp', + }, 'seatable-mcp started') // Idle session cleanup. Sessions that crowd the connection pool sooner than // this are evicted on demand, see evictIdlestSession(). diff --git a/src/index.ts b/src/index.ts index ebd4e61..b2578c9 100644 --- a/src/index.ts +++ b/src/index.ts @@ -76,6 +76,7 @@ async function main() { } await server.connect(transport) + logger.info({ transport: 'stdio', tools: server.getToolDefinitions().length }, 'seatable-mcp started') } // Exported CLI entry for bin launcher (used by npx) diff --git a/src/mcp/server.ts b/src/mcp/server.ts index 7cdf8b0..eed9219 100644 --- a/src/mcp/server.ts +++ b/src/mcp/server.ts @@ -385,10 +385,9 @@ export function buildServer(options?: BuildServerOptions) { mode = 'selfhosted' } - logger.info({ - mode, - tools: server.getToolDefinitions().length, - }, 'seatable-mcp started') + // Called once per HTTP session, so this is not the startup line: that is + // logged once per process by main() (stdio) and startHttpServer(). + logger.debug({ mode, tools: server.getToolDefinitions().length }, 'MCP server built') return server } diff --git a/tests/connectionSlots.spec.ts b/tests/connectionSlots.spec.ts index 037fd1d..a662f43 100644 --- a/tests/connectionSlots.spec.ts +++ b/tests/connectionSlots.spec.ts @@ -6,7 +6,7 @@ vi.mock('../src/metrics/metricsServer', () => ({ startMetricsServer: vi.fn().mockResolvedValue(undefined), })) -const VALID_TOKENS = new Set(['slot-token-1', 'slot-token-2', 'slot-token-3', 'slot-token-4']) +const VALID_TOKENS = new Set(['slot-token-1', 'slot-token-2', 'slot-token-3', 'slot-token-4', 'slot-token-log']) vi.mock('../src/auth/tokenValidator', () => ({ TokenValidator: class { @@ -106,6 +106,27 @@ describe('Connection slot accounting', () => { expect(res.headers.get('mcp-session-id')).toBeTruthy() }) + /** + * In production most sessions were preceded by one of these 400s, and the + * log said nothing about why. The method and the SDK's reason say whether a + * client is replaying a request without its session or speaking a protocol + * version we don't support. + */ + it('logs the method and reason of a POST without session ID that is not initialize', async () => { + const res = await fetch(`${baseUrl}/mcp`, { + method: 'POST', + headers: { ...JSON_HEADERS, authorization: 'Bearer slot-token-log', 'x-forwarded-for': '198.51.100.9' }, + body: JSON.stringify({ jsonrpc: '2.0', id: 7, method: 'tools/call', params: { name: 'list_tables', arguments: {} } }), + }) + expect(res.status).toBe(400) + await res.text() + await vi.waitFor(() => expect(find('Initialize request ended without a session')).toHaveLength(1)) + + const [entry] = find('Initialize request ended without a session') + expect(entry.fields).toMatchObject({ status: 400, method: 'tools/call', reason: 'Bad Request: Server not initialized' }) + expect(JSON.stringify(entry.fields)).not.toContain('list_tables') + }) + it('releases the slot when a session is closed with DELETE', async () => { const token = 'slot-token-2' const ip = '198.51.100.2' diff --git a/tests/oauthObservability.spec.ts b/tests/oauthObservability.spec.ts index a7bd2b9..5a9bf99 100644 --- a/tests/oauthObservability.spec.ts +++ b/tests/oauthObservability.spec.ts @@ -12,6 +12,7 @@ vi.mock('../src/logger', () => { }) import { OAuthProvider } from '../src/auth/oauthProvider.js' +import { TokenCipher } from '../src/auth/tokenCipher.js' /** * After the external report, the forensic questions could not be answered from @@ -281,3 +282,43 @@ describe('no rejection path is silent', () => { expect(rejected[0].fields.ip).toBe('198.51.100.66') }) }) + +describe('a stale client registration is attributable', () => { + /* + * Production showed bursts of "unknown or expired client registration", + * three every few seconds, with no field at all: neither who sent them nor + * whether the registration had expired or was sealed under another secret. + */ + async function authorizeWith(clientId: string) { + await fetch(base( + `/authorize?response_type=code&client_id=${encodeURIComponent(clientId)}` + + `&redirect_uri=${encodeURIComponent(CB)}&code_challenge=${CHALLENGE}&code_challenge_method=S256`, + ), { headers: { 'x-forwarded-for': '198.51.100.42' } }) + return find('unknown or expired client registration') + } + + it('records reason, IP, callback and a fingerprint of the client_id', async () => { + const stale = new TokenCipher('the-secret-before-it-was-rotated-long-enough') + .seal('client', { n: 'Old Client', r: [CB] }, 60_000) + const rejected = await authorizeWith(stale) + + expect(rejected).toHaveLength(1) + expect(rejected[0].fields).toMatchObject({ reason: 'invalid', ip: '198.51.100.42', callback: CB }) + expect(rejected[0].fields.clientId).toMatch(/^[0-9a-f]{12}$/) + expect(JSON.stringify(rejected[0].fields)).not.toContain(stale) + }) + + it('tells an expired registration apart', async () => { + const expired = new TokenCipher(SECRET).seal('client', { n: 'Old Client', r: [CB] }, -1) + const [rejected] = await authorizeWith(expired) + expect(rejected.fields.reason).toBe('expired') + }) + + it('gives the same client_id the same fingerprint, so a burst groups', async () => { + const [a] = await authorizeWith('not-one-of-ours') + logCalls.length = 0 + const [b] = await authorizeWith('not-one-of-ours') + expect(a.fields.reason).toBe('foreign') + expect(a.fields.clientId).toBe(b.fields.clientId) + }) +}) diff --git a/tests/tokenCipher.spec.ts b/tests/tokenCipher.spec.ts index 150eba8..f64cfdd 100644 --- a/tests/tokenCipher.spec.ts +++ b/tests/tokenCipher.spec.ts @@ -68,4 +68,31 @@ describe('TokenCipher', () => { expect(cipher.open('access', '')).toBeUndefined() expect(cipher.open('access', 'stmcp1.AAAA')).toBeUndefined() }) + + describe('inspect() names the reason for a rejection', () => { + const cipher = new TokenCipher(SECRET) + + it('missing', () => { + expect(cipher.inspect('client', '')).toEqual({ reason: 'missing' }) + }) + + it('foreign: not our envelope, or another kind of ours', () => { + expect(cipher.inspect('client', 'some-other-servers-client-id')).toEqual({ reason: 'foreign' }) + expect(cipher.inspect('client', cipher.seal('access', {}, 60_000))).toEqual({ reason: 'foreign' }) + }) + + it('invalid: sealed under another secret', () => { + const other = new TokenCipher('a-different-secret-that-is-also-long-enough') + expect(cipher.inspect('client', other.seal('client', {}, 60_000))).toEqual({ reason: 'invalid' }) + }) + + it('expired', () => { + expect(cipher.inspect('client', cipher.seal('client', {}, -1))).toEqual({ reason: 'expired' }) + }) + + it('returns the payload of a valid value, like open()', () => { + const result = cipher.inspect('client', cipher.seal('client', { n: 'x' }, 60_000)) + expect('payload' in result && result.payload.n).toBe('x') + }) + }) })