feat(saas): SquareMCP v2 — multi-tenant MCP platform complete

Steps 0–10 of the v2 plan, 194 tests passing.

Core infrastructure
- Shared Redis client (src/redis.ts); all four Redis consumers migrated
- Vitest test harness with vitest.config.ts and npm test/test:watch scripts

Billing & invoicing (Steps 1–2)
- Monthly invoice generation with idempotency (MySQL uq_customer_period unique key)
- Cron job with Redis distributed lock (Lua compare-delete, 1-hr TTL)
- Invoice emailer via nodemailer (FETCHERPAY SMTP)
- Billing middleware: checkLimit gate in handleToolCall; platform attribution fix

Email multi-tenancy (Step 3)
- EmailCtx = Account | EmailCredentials; imap.ts + smtp.ts accept both
- resolveEmailCtx helper in tools.ts; all email tools use customer credentials

Analytics + platform health (Steps 4–5)
- Chart.js bar charts for platform breakdown and daily activity
- Token expiry check in getCredential with dynamic import refresh
- platform-health.ts: per-platform health probe with 10-min Redis cache
- GET /api/health/platforms; "Token expired" amber badge in dashboard

Tool schema filtering (Step 6)
- stripAccountParam deep-clones tool schemas; multi-tenant sessions never
  see the internal account enum

OAuth hardening (Step 7)
- Atomic auth code consumption: UPDATE SET used=TRUE, check affectedRows
- customer_id threaded through oauth_auth_codes → oauth_tokens
- getTokenCustomer(); requireAuth resolves req.customer from Bearer token
- Consent page requires authenticated session; redirect_uri validated
  against registered URIs; http://localhost:* loopback wildcard

DCR browser flow (Step 8)
- ensureOAuthAppRegistered() upserts pre-registered SquareMCP OAuth app
  on startup with redirect URIs for mcp-callback, localhost:*, claude-desktop,
  opencode
- GET /oauth/connect-mcp → server-side redirect (client_id off frontend)
- GET /oauth/mcp-callback → exchanges code, renders config snippet page
  with copy buttons for Claude Desktop and Codex CLI

Webhooks (Step 9)
- webhook_url + webhook_secret columns on customers
- deliverWebhook(): HMAC-SHA256 signing, 3× exponential retry (1s/4s/16s),
  Redis DLQ with 7-day TTL on total failure
- isValidWebhookUrl(): SSRF protection (blocks RFC-1918, localhost, .local)
- POST /api/webhooks/config (secret returned once), GET, DELETE
- GET /api/admin/webhooks/dlq/:customerId
- WhatsApp POST route uses express.raw() for raw body preservation
- Dashboard Webhooks tab with secret-once display and copy button

Developer docs (Step 10)
- docs/ static HTML site (GitHub Pages, no build pipeline)
- index.html: landing page with client + platform overview
- getting-started.html: tabbed MCP config for Claude Desktop, Codex CLI, opencode
- platforms.html: LinkedIn, TikTok, WhatsApp, Instagram, Twitter, Telegram guides
- agent-tutorial.html: complete Node.js agent (Anthropic SDK + MCP SDK),
  LinkedIn posting loop, extensions for multi-platform + inbound webhook reaction

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

src/multitenancy/platform-health.ts

@@ -0,0 +1,72 @@
+import redis from '../redis.js';
+import { getCredential, type Platform } from './credential-store.js';
+
+const HEALTH_TTL = 600; // 10 minutes
+
+type HealthStatus = 'healthy' | 'expired' | 'disconnected' | 'unknown';
+
+interface PlatformHealth {
+  platform: Platform;
+  status: HealthStatus;
+}
+
+const OAUTH_PLATFORMS: Platform[] = ['linkedin', 'twitter', 'tiktok', 'instagram', 'facebook', 'snapchat'];
+const ALL_PLATFORMS: Platform[] = ['email', 'whatsapp', 'linkedin', 'telegram', 'discord', 'instagram', 'twitter', 'tiktok', 'snapchat', 'facebook', 'obsidian'];
+
+async function checkPlatformHealth(customerId: string, platform: Platform): Promise<HealthStatus> {
+  const cacheKey = `health:${customerId}:${platform}`;
+  const cached = await redis.get(cacheKey);
+  if (cached) return cached as HealthStatus;
+
+  const cred = await getCredential(customerId, platform);
+  let status: HealthStatus;
+
+  if (!cred) {
+    // getCredential returns null for both "not stored" and "expired with no refresh"
+    // Check if there was a stored (but expired) credential by looking at the raw key
+    const rawKey = `creds:${customerId}:${platform}`;
+    const raw = await redis.get(rawKey);
+    status = raw ? 'expired' : 'disconnected';
+  } else if (OAUTH_PLATFORMS.includes(platform)) {
+    // Credential exists and is not expired — probe the API
+    status = await probeOAuthPlatform(platform, cred as { accessToken: string });
+  } else {
+    status = 'healthy';
+  }
+
+  await redis.setEx(cacheKey, HEALTH_TTL, status);
+  return status;
+}
+
+async function probeOAuthPlatform(platform: Platform, cred: { accessToken: string }): Promise<HealthStatus> {
+  const probeUrls: Partial<Record<Platform, string>> = {
+    linkedin: 'https://api.linkedin.com/v2/userinfo',
+    twitter: 'https://api.twitter.com/2/users/me',
+    tiktok: 'https://open.tiktokapis.com/v2/user/info/?fields=open_id',
+    instagram: 'https://graph.instagram.com/me?fields=id',
+    facebook: 'https://graph.facebook.com/me?fields=id',
+    snapchat: 'https://adsapi.snapchat.com/v1/me',
+  };
+
+  const url = probeUrls[platform];
+  if (!url) return 'unknown';
+
+  try {
+    const res = await fetch(url, {
+      headers: { Authorization: `Bearer ${cred.accessToken}` },
+      signal: AbortSignal.timeout(8000),
+    });
+    return res.ok ? 'healthy' : 'expired';
+  } catch {
+    return 'unknown';
+  }
+}
+
+export async function getAllPlatformHealth(customerId: string): Promise<PlatformHealth[]> {
+  return Promise.all(
+    ALL_PLATFORMS.map(async (platform) => ({
+      platform,
+      status: await checkPlatformHealth(customerId, platform),
+    }))
+  );
+}