thumbgate 1.27.19 → 1.27.20

package/scripts/mcp-oauth.js

@@ -0,0 +1,293 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * mcp-oauth.js — OAuth 2.1 (PKCE) authorization-server machinery for the remote
+ * ThumbGate MCP connector, required by the Claude Connectors Directory
+ * ("Use OAuth 2.0 for authenticated services").
+ *
+ * Pure, dependency-free, IO-free functions + an injectable store, so the full
+ * flow is unit-testable without a network. The HTTP wiring (in src/api/server.js)
+ * is a thin shell over these.
+ *
+ * Implements:
+ *   - RFC 9728 protected-resource metadata
+ *   - RFC 8414 authorization-server metadata
+ *   - RFC 7591 dynamic client registration (open registration)
+ *   - Authorization-code grant with mandatory PKCE S256 (RFC 7636)
+ *   - Bearer access tokens bound to a ThumbGate API key (so existing gating is unchanged)
+ *
+ * SECURITY NOTES:
+ *   - PKCE S256 is mandatory; the plain method is rejected.
+ *   - Auth codes are single-use and short-lived (60s); access tokens TTL-bound.
+ *   - redirect_uri is matched exactly against the registered set.
+ *   - The token never exposes the bound ThumbGate key; it maps server-side only.
+ */
+
+const crypto = require('crypto');
+
+const AUTH_CODE_TTL_MS = 60 * 1000; // 1 minute
+const ACCESS_TOKEN_TTL_MS = 60 * 60 * 1000; // 1 hour
+const DEFAULT_SCOPE = 'mcp:read mcp:write';
+
+// Upper bounds on the in-memory store. The registration and authorization
+// endpoints are reachable pre-auth, so without a cap a malicious caller could
+// grow these Maps unboundedly and exhaust server memory. When a Map is full we
+// evict the oldest entry (FIFO) rather than deny service to legitimate clients.
+const MAX_CLIENTS = 10000;
+const MAX_CODES = 10000;
+const MAX_TOKENS = 50000;
+
+function now() {
+  return Date.now();
+}
+
+function randomToken(bytes = 32) {
+  return crypto.randomBytes(bytes).toString('base64url');
+}
+
+function base64UrlSha256(input) {
+  return crypto.createHash('sha256').update(String(input)).digest('base64url');
+}
+
+/**
+ * Create a fresh in-memory store.
+ *
+ * DURABILITY (known limitation): this uses plain Maps, so a process restart or a
+ * multi-instance / load-balanced deployment will drop issued tokens and
+ * registered clients (clients see 401s, in-flight authorizations break). For
+ * single-instance use this is fine; production multi-tenancy needs a durable,
+ * shared backing (Redis/DB) — tracked as the per-user-data-scoping follow-up.
+ * Entry counts are bounded (see MAX_* and capInsert) to prevent memory
+ * exhaustion from anonymous calls to the registration/authorization endpoints.
+ */
+function createStore() {
+  return {
+    clients: new Map(),
+    codes: new Map(),
+    tokens: new Map(),
+  };
+}
+
+/** Insert into a Map, evicting the oldest entry (FIFO) once `max` is reached. */
+function capInsert(map, key, value, max) {
+  if (map.size >= max && !map.has(key)) {
+    const oldest = map.keys().next().value;
+    if (oldest !== undefined) map.delete(oldest);
+  }
+  map.set(key, value);
+}
+
+// ---------------------------------------------------------------------------
+// Metadata (RFC 9728 / RFC 8414)
+// ---------------------------------------------------------------------------
+
+function trimSlash(u) {
+  // Non-regex trailing-slash strip (avoids a SonarCloud S5852 false-positive on a
+  // provably-linear pattern).
+  let s = String(u || '');
+  while (s.endsWith('/')) s = s.slice(0, -1);
+  return s;
+}
+
+function buildProtectedResourceMetadata(baseUrl) {
+  const base = trimSlash(baseUrl);
+  return {
+    resource: `${base}/mcp`,
+    authorization_servers: [base],
+    bearer_methods_supported: ['header'],
+    scopes_supported: ['mcp:read', 'mcp:write'],
+    resource_documentation: `${base}/docs/connectors`,
+  };
+}
+
+function buildAuthServerMetadata(baseUrl) {
+  const base = trimSlash(baseUrl);
+  return {
+    issuer: base,
+    authorization_endpoint: `${base}/oauth/authorize`,
+    token_endpoint: `${base}/oauth/token`,
+    registration_endpoint: `${base}/oauth/register`,
+    scopes_supported: ['mcp:read', 'mcp:write'],
+    response_types_supported: ['code'],
+    grant_types_supported: ['authorization_code'],
+    code_challenge_methods_supported: ['S256'],
+    token_endpoint_auth_methods_supported: ['none'],
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Dynamic client registration (RFC 7591)
+// ---------------------------------------------------------------------------
+
+// The MCP authorization spec is explicit: "All redirect URIs MUST be either
+// `localhost` or use HTTPS." We therefore accept only HTTPS and loopback
+// (http://localhost | http://127.0.0.1) and reject every other scheme —
+// including native-app custom schemes (myapp://, intent://, etc.), which the MCP
+// profile does not sanction and the real client (Claude) does not use.
+function isAllowedRedirectUri(uri) {
+  const u = String(uri || '');
+  if (/^https:\/\//i.test(u)) return true;
+  if (/^http:\/\/(localhost|127\.0\.0\.1)(:\d+)?(\/|$)/i.test(u)) return true;
+  return false;
+}
+
+function registerClient(store, body = {}) {
+  const redirectUris = Array.isArray(body.redirect_uris) ? body.redirect_uris.filter(Boolean) : [];
+  if (redirectUris.length === 0) {
+    return { error: 'invalid_redirect_uri', error_description: 'redirect_uris is required' };
+  }
+  for (const uri of redirectUris) {
+    if (!isAllowedRedirectUri(uri)) {
+      return { error: 'invalid_redirect_uri', error_description: `unsupported redirect_uri: ${uri}` };
+    }
+  }
+  const clientId = `tg_${randomToken(16)}`;
+  const record = {
+    client_id: clientId,
+    redirect_uris: redirectUris,
+    token_endpoint_auth_method: 'none',
+    grant_types: ['authorization_code'],
+    response_types: ['code'],
+    client_name: typeof body.client_name === 'string' ? body.client_name.slice(0, 200) : 'mcp-client',
+    created_at: now(),
+  };
+  capInsert(store.clients, clientId, record, MAX_CLIENTS);
+  return record;
+}
+
+function getClient(store, clientId) {
+  return store.clients.get(clientId) || null;
+}
+
+// ---------------------------------------------------------------------------
+// Authorization code (PKCE S256)
+// ---------------------------------------------------------------------------
+
+/**
+ * Issue an auth code. `boundKey` is the ThumbGate API key the resulting access
+ * token will act as (resolved by the authorize step once the user consents).
+ */
+function createAuthorizationCode(store, {
+  clientId, redirectUri, codeChallenge, codeChallengeMethod, scope, boundKey, state, resource,
+} = {}) {
+  const client = getClient(store, clientId);
+  if (!client) return { error: 'invalid_client' };
+  if (!client.redirect_uris.includes(redirectUri)) return { error: 'invalid_request', error_description: 'redirect_uri mismatch' };
+  if (codeChallengeMethod !== 'S256') return { error: 'invalid_request', error_description: 'code_challenge_method must be S256' };
+  if (!codeChallenge || String(codeChallenge).length < 16) return { error: 'invalid_request', error_description: 'code_challenge required' };
+
+  const code = randomToken(24);
+  capInsert(store.codes, code, {
+    clientId,
+    redirectUri,
+    codeChallenge,
+    scope: scope || DEFAULT_SCOPE,
+    boundKey: boundKey || '',
+    resource: resource || '', // RFC 8707 resource indicator (the MCP server URL)
+    expiresAt: now() + AUTH_CODE_TTL_MS,
+    used: false,
+  }, MAX_CODES);
+  return { code, state };
+}
+
+function verifyPkce(codeChallenge, codeVerifier) {
+  if (!codeChallenge || !codeVerifier) return false;
+  // RFC 7636: verifier 43–128 chars.
+  if (String(codeVerifier).length < 43 || String(codeVerifier).length > 128) return false;
+  try {
+    return crypto.timingSafeEqual(
+      Buffer.from(base64UrlSha256(codeVerifier)),
+      Buffer.from(String(codeChallenge)),
+    );
+  } catch {
+    return false;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Token exchange + validation
+// ---------------------------------------------------------------------------
+
+function exchangeCode(store, { code, codeVerifier, clientId, redirectUri, resource } = {}) {
+  const entry = store.codes.get(code);
+  if (!entry) return { error: 'invalid_grant', error_description: 'unknown code' };
+  // Single-use + expiry: consume regardless of outcome.
+  store.codes.delete(code);
+  if (entry.used) return { error: 'invalid_grant', error_description: 'code already used' };
+  if (now() > entry.expiresAt) return { error: 'invalid_grant', error_description: 'code expired' };
+  if (entry.clientId !== clientId) return { error: 'invalid_grant', error_description: 'client mismatch' };
+  if (entry.redirectUri !== redirectUri) return { error: 'invalid_grant', error_description: 'redirect_uri mismatch' };
+  if (!verifyPkce(entry.codeChallenge, codeVerifier)) return { error: 'invalid_grant', error_description: 'PKCE verification failed' };
+  // RFC 8707: the resource at token time must match the one bound at authorize time.
+  if (entry.resource && resource && entry.resource !== resource) {
+    return { error: 'invalid_target', error_description: 'resource indicator mismatch' };
+  }
+
+  const accessToken = `tgat_${randomToken(32)}`;
+  capInsert(store.tokens, accessToken, {
+    boundKey: entry.boundKey,
+    scope: entry.scope,
+    clientId,
+    aud: entry.resource || resource || '',
+    expiresAt: now() + ACCESS_TOKEN_TTL_MS,
+  }, MAX_TOKENS);
+  return {
+    access_token: accessToken,
+    token_type: 'Bearer',
+    expires_in: Math.floor(ACCESS_TOKEN_TTL_MS / 1000),
+    scope: entry.scope,
+  };
+}
+
+/** Resolve an access token to its session, or null if invalid/expired. */
+function resolveAccessToken(store, token) {
+  if (!token) return null;
+  const entry = store.tokens.get(token);
+  if (!entry) return null;
+  if (now() > entry.expiresAt) {
+    store.tokens.delete(token);
+    return null;
+  }
+  return { boundKey: entry.boundKey, scope: entry.scope, clientId: entry.clientId, aud: entry.aud };
+}
+
+/**
+ * RFC 8707 audience validation: a token is valid for `expectedResource` only if it
+ * was issued for it (or carries no audience, for back-compat). MCP servers MUST
+ * reject tokens minted for a different resource.
+ */
+function tokenAudienceValid(session, expectedResource) {
+  if (!session) return false;
+  if (!session.aud) return true; // no audience recorded — accept (back-compat)
+  return session.aud === expectedResource;
+}
+
+/** Best-effort GC of expired codes/tokens (call opportunistically). */
+function pruneExpired(store) {
+  const t = now();
+  for (const [k, v] of store.codes) if (t > v.expiresAt) store.codes.delete(k);
+  for (const [k, v] of store.tokens) if (t > v.expiresAt) store.tokens.delete(k);
+}
+
+module.exports = {
+  createStore,
+  buildProtectedResourceMetadata,
+  buildAuthServerMetadata,
+  registerClient,
+  getClient,
+  createAuthorizationCode,
+  verifyPkce,
+  exchangeCode,
+  resolveAccessToken,
+  tokenAudienceValid,
+  pruneExpired,
+  isAllowedRedirectUri,
+  base64UrlSha256,
+  AUTH_CODE_TTL_MS,
+  ACCESS_TOKEN_TTL_MS,
+  DEFAULT_SCOPE,
+  MAX_CLIENTS,
+  MAX_CODES,
+  MAX_TOKENS,
+};

package/scripts/noop-detect.js

@@ -0,0 +1,285 @@
+'use strict';
+
+// scripts/noop-detect.js
+//
+// No-op / redundant-action detection for ThumbGate.
+//
+// Given an action's pre/post state (file diff, command exit code + output),
+// this module decides whether the action actually changed anything OR whether
+// it is byte-identical to an attempt already seen this session. Both are strong,
+// cheap "the agent is looping" repeat signals that plug into
+// track_action -> prevention_rules.
+//
+// Design goals:
+//   * Pure / file-local. No edits to shared modules from inside here.
+//   * Normalize volatile fields (timestamps, shas, ANSI, trailing whitespace)
+//     before hashing so non-deterministic output does not defeat detection.
+//   * Guard partial writes: a truncated after-state that is a strict prefix of
+//     the before-state must NOT be reported as a no-op.
+//
+// Persistence lives beside session-actions.json (derived from
+// gates-engine.SESSION_ACTIONS_PATH) so it picks up THUMBGATE_STATE_DIR
+// overrides and shares the same TTL semantics.
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+
+const gatesEngine = require('./gates-engine');
+
+// Match the same 1h session window the engine uses for session actions.
+const ATTEMPT_TTL_MS = 60 * 60 * 1000;
+
+// -- volatile-field normalization ------------------------------------------
+//
+// Each pattern strips a class of non-deterministic noise so that two outputs
+// which differ only by a timestamp / sha / uuid / ANSI color / trailing
+// whitespace hash-equal. Exported so the test suite can assert the contract.
+const VOLATILE_PATTERNS = [
+  // ANSI escape / color codes (e.g. \x1b[0m). Strip first so later patterns
+  // see clean text.
+  { name: 'ansi', re: /\x1b\[[0-9;]*[A-Za-z]/g, replacement: '' },
+  // ISO-8601 timestamps: 2026-05-31T12:34:56(.123)?(Z|+00:00)
+  {
+    name: 'iso8601',
+    re: /\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:?\d{2})?/g,
+    replacement: '<TS>',
+  },
+  // UUIDs (dashed form) — must run before the hexblob pattern, otherwise the
+  // trailing 12-char hex segment gets rewritten first and the UUID never matches.
+  {
+    name: 'uuid',
+    re: /\b[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}\b/g,
+    replacement: '<UUID>',
+  },
+  // Epoch integers wider than 10 digits (ms/ns timestamps) — run before the
+  // hexblob pattern so all-decimal epochs are not swallowed as hex first.
+  { name: 'epoch', re: /\b\d{11,}\b/g, replacement: '<EPOCH>' },
+  // Long hex blobs (commit shas, uuids without dashes, content hashes): 12+ hex chars.
+  { name: 'hexblob', re: /\b[0-9a-fA-F]{12,}\b/g, replacement: '<HEX>' },
+  // Trailing whitespace is stripped in normalizeVolatile() via a bounded linear
+  // scan (not a regex) to avoid super-linear backtracking on adversarial input.
+];
+
+// Strip trailing spaces/tabs from a single line via a bounded reverse scan.
+// Linear in line length; replaces /[ \t]+$/ without any regex backtracking.
+function stripTrailingSpaceTab(line) {
+  let end = line.length;
+  while (end > 0) {
+    const c = line.charCodeAt(end - 1);
+    if (c !== 32 && c !== 9) break; // 32 = space, 9 = tab
+    end -= 1;
+  }
+  return line.slice(0, end);
+}
+
+// Normalize a string by applying every volatile pattern, then trimming a
+// trailing newline so "foo\n" and "foo" are equivalent.
+function normalizeVolatile(value) {
+  if (value === null || value === undefined) return '';
+  let out = String(value);
+  for (const pattern of VOLATILE_PATTERNS) {
+    out = out.replace(pattern.re, pattern.replacement);
+  }
+  // Strip trailing space/tab per line without a backtracking-prone regex.
+  out = out.split('\n').map(stripTrailingSpaceTab).join('\n');
+  // Normalize CRLF, then strip the trailing run of newlines via a bounded
+  // linear scan (replaces /\n+$/ without regex backtracking).
+  out = out.replace(/\r\n/g, '\n');
+  let end = out.length;
+  while (end > 0 && out.charCodeAt(end - 1) === 10) end -= 1; // 10 = \n
+  return out.slice(0, end);
+}
+
+function sha256(value) {
+  return crypto.createHash('sha256').update(value, 'utf8').digest('hex');
+}
+
+// -- state hashing ----------------------------------------------------------
+//
+// computeActionStateHash produces a single stable fingerprint for an action's
+// observable state. For file actions the fingerprint is the normalized content;
+// for command actions it is exit code + normalized stdout/stderr.
+function computeActionStateHash(action = {}) {
+  const kind = action.kind === 'command' ? 'command' : 'file';
+
+  if (kind === 'command') {
+    const exitCode = action.exitCode === undefined || action.exitCode === null
+      ? ''
+      : String(action.exitCode);
+    const parts = [
+      'command',
+      `exit:${exitCode}`,
+      `stdout:${normalizeVolatile(action.stdout)}`,
+      `stderr:${normalizeVolatile(action.stderr)}`,
+    ];
+    return sha256(parts.join('\x00'));
+  }
+
+  // file kind: hash the relevant content (after-content is the canonical state
+  // for a single snapshot; for diff comparisons detectNoop compares before/after
+  // separately). Include filePath so two unrelated files never collide.
+  const content = action.afterContent !== undefined && action.afterContent !== null
+    ? action.afterContent
+    : action.beforeContent;
+  const parts = [
+    'file',
+    `path:${action.filePath || ''}`,
+    `content:${normalizeVolatile(content)}`,
+  ];
+  return sha256(parts.join('\x00'));
+}
+
+// Hash just a content blob for before/after comparison (no path/kind framing).
+function contentHash(content) {
+  return sha256(normalizeVolatile(content));
+}
+
+// -- no-op detection --------------------------------------------------------
+//
+// detectNoop({ before, after }) returns { noop, reason }.
+//   before/after: { kind, filePath, beforeContent/afterContent OR content,
+//                   exitCode, stdout, stderr }
+//
+// We accept a flexible shape: the caller may pass a single action object with
+// beforeContent/afterContent, or split before/after sub-objects. Both forms
+// resolve to the same decision.
+function detectNoop(input = {}) {
+  const before = input.before || {};
+  const after = input.after || {};
+
+  // Determine kind from whichever side declares it (default file).
+  const kind = (before.kind || after.kind || input.kind) === 'command'
+    ? 'command'
+    : 'file';
+
+  if (kind === 'command') {
+    const beforeExit = before.exitCode;
+    const afterExit = after.exitCode;
+    if (beforeExit !== undefined && afterExit !== undefined && beforeExit !== afterExit) {
+      return { noop: false, reason: 'exit-code-changed' };
+    }
+    const beforeOut = contentHash(`${normalizeVolatile(before.stdout)}\x00${normalizeVolatile(before.stderr)}`);
+    const afterOut = contentHash(`${normalizeVolatile(after.stdout)}\x00${normalizeVolatile(after.stderr)}`);
+    if (beforeOut === afterOut) {
+      return { noop: true, reason: 'command-output-unchanged' };
+    }
+    return { noop: false, reason: 'command-output-changed' };
+  }
+
+  // file kind.
+  const beforeContent = before.content !== undefined ? before.content
+    : (before.beforeContent !== undefined ? before.beforeContent : input.beforeContent);
+  const afterContent = after.content !== undefined ? after.content
+    : (after.afterContent !== undefined ? after.afterContent : input.afterContent);
+
+  const beforeStr = beforeContent === undefined || beforeContent === null ? '' : String(beforeContent);
+  const afterStr = afterContent === undefined || afterContent === null ? '' : String(afterContent);
+
+  // Partial-write guard: an after-state that is a strict, shorter prefix of the
+  // before-state is a truncation, not a no-op — even though hashes differ, we
+  // make the intent explicit so callers never mistake it.
+  if (afterStr.length > 0 && afterStr.length < beforeStr.length && beforeStr.startsWith(afterStr)) {
+    return { noop: false, reason: 'partial-write-truncation' };
+  }
+
+  if (contentHash(beforeStr) === contentHash(afterStr)) {
+    return { noop: true, reason: 'file-content-unchanged' };
+  }
+  return { noop: false, reason: 'file-content-changed' };
+}
+
+// -- attempt persistence ----------------------------------------------------
+//
+// Stores (sessionId -> { "actionId\x00stateHash": timestamp }) so a repeated
+// (actionId, stateHash) tuple within the TTL window is a strong repeat signal.
+function attemptsPath() {
+  const sessionActionsPath = gatesEngine.SESSION_ACTIONS_PATH;
+  return path.join(path.dirname(sessionActionsPath), 'noop-attempts.json');
+}
+
+function loadAttempts() {
+  try {
+    const raw = fs.readFileSync(attemptsPath(), 'utf8');
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== 'object') return {};
+    return parsed;
+  } catch (e) {
+    return {};
+  }
+}
+
+function pruneExpired(store, now) {
+  let changed = false;
+  for (const sessionId of Object.keys(store)) {
+    const bucket = store[sessionId];
+    if (!bucket || typeof bucket !== 'object') {
+      delete store[sessionId];
+      changed = true;
+      continue;
+    }
+    for (const key of Object.keys(bucket)) {
+      const ts = bucket[key];
+      if (typeof ts !== 'number' || now - ts >= ATTEMPT_TTL_MS) {
+        delete bucket[key];
+        changed = true;
+      }
+    }
+    if (Object.keys(bucket).length === 0) {
+      delete store[sessionId];
+      changed = true;
+    }
+  }
+  return changed;
+}
+
+function saveAttempts(store) {
+  const file = attemptsPath();
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify(store, null, 2) + '\n');
+}
+
+function attemptKey(actionId, stateHash) {
+  return `${String(actionId)}\x00${String(stateHash)}`;
+}
+
+// recordActionAttempt persists that (sessionId, actionId, stateHash) was seen.
+// Returns { recorded: boolean, alreadySeen: boolean }.
+function recordActionAttempt(sessionId, actionId, stateHash) {
+  const sid = String(sessionId || 'default');
+  const now = Date.now();
+  const store = loadAttempts();
+  pruneExpired(store, now);
+
+  if (!store[sid] || typeof store[sid] !== 'object') store[sid] = {};
+  const key = attemptKey(actionId, stateHash);
+  const alreadySeen = Object.prototype.hasOwnProperty.call(store[sid], key);
+  store[sid][key] = now;
+  saveAttempts(store);
+  return { recorded: true, alreadySeen };
+}
+
+// isRepeatAttempt returns true when this exact (actionId, stateHash) tuple was
+// already recorded for this session within the TTL window.
+function isRepeatAttempt(sessionId, actionId, stateHash) {
+  const sid = String(sessionId || 'default');
+  const now = Date.now();
+  const store = loadAttempts();
+  const bucket = store[sid];
+  if (!bucket || typeof bucket !== 'object') return false;
+  const ts = bucket[attemptKey(actionId, stateHash)];
+  if (typeof ts !== 'number') return false;
+  return now - ts < ATTEMPT_TTL_MS;
+}
+
+module.exports = {
+  VOLATILE_PATTERNS,
+  ATTEMPT_TTL_MS,
+  normalizeVolatile,
+  computeActionStateHash,
+  detectNoop,
+  recordActionAttempt,
+  isRepeatAttempt,
+  // Exposed for tests / introspection.
+  attemptsPath,
+};