@platf/bridge 0.0.2

package/src/lib/authMiddleware.ts

@@ -0,0 +1,58 @@
+/**
+ * OAuth 2.0 JWT auth middleware for the bridge.
+ *
+ * - Fetches JWKS from `{issuer}/jwks` using jose's createRemoteJWKSet (auto-caches).
+ * - Validates Bearer token: signature, `iss`, `exp`.
+ * - On failure returns 401 with RFC 9728–compliant `WWW-Authenticate` header
+ *   pointing at the OAuth Protected Resource Metadata document.
+ */
+
+import { createRemoteJWKSet, jwtVerify } from 'jose'
+import type { RequestHandler } from 'express'
+import type { AuthConfig, Logger } from '../types.js'
+
+/** Build a reusable auth middleware for the given auth config */
+export function createAuthMiddleware(auth: AuthConfig, logger: Logger): RequestHandler {
+  const jwksUri = new URL('/jwks', auth.issuer)
+  const JWKS = createRemoteJWKSet(jwksUri)
+
+  return async (req, res, next) => {
+    const authHeader = req.headers.authorization
+    if (!authHeader || !authHeader.startsWith('Bearer ')) {
+      return unauthorized(req, res, auth, 'missing or malformed Authorization header')
+    }
+
+    const token = authHeader.slice(7)
+
+    try {
+      const { payload } = await jwtVerify(token, JWKS, {
+        issuer: auth.issuer,
+      })
+
+      // Attach token payload to request for downstream use
+      ;(req as any).tokenPayload = payload
+      next()
+    } catch (err: any) {
+      logger.error('[auth] JWT verification failed:', err.message ?? err)
+      return unauthorized(req, res, auth, 'invalid_token')
+    }
+  }
+}
+
+function unauthorized(
+  req: import('express').Request,
+  res: import('express').Response,
+  auth: AuthConfig,
+  error: string,
+) {
+  // RFC 9728: include resource_metadata URI in WWW-Authenticate
+  const scheme = req.protocol
+  const host = req.get('host')
+  const resourceMetadataUri = `${scheme}://${host}/.well-known/oauth-protected-resource`
+
+  res.setHeader(
+    'WWW-Authenticate',
+    `Bearer realm="mcp", error="${error}", resource_metadata="${resourceMetadataUri}"`,
+  )
+  res.status(401).json({ error: 'unauthorized', message: error })
+}

package/src/lib/cors.ts

@@ -0,0 +1,30 @@
+import type { CorsOptions } from 'cors'
+
+export function parseCorsOrigin(
+  corsValues: (string | number)[] | undefined,
+): CorsOptions['origin'] | false {
+  if (!corsValues) return false
+  if (corsValues.length === 0) return '*'
+
+  const origins = corsValues.map((item) => `${item}`)
+  if (origins.includes('*')) return '*'
+
+  return origins.map((origin) => {
+    if (/^\/.*\/$/.test(origin)) {
+      const pattern = origin.slice(1, -1)
+      try {
+        return new RegExp(pattern)
+      } catch {
+        return origin
+      }
+    }
+    return origin
+  })
+}
+
+export function serializeCorsOrigin(corsOrigin: CorsOptions['origin']): string {
+  return JSON.stringify(corsOrigin, (_key, value) => {
+    if (value instanceof RegExp) return value.toString()
+    return value
+  })
+}

package/src/lib/discoveryRoutes.ts

@@ -0,0 +1,95 @@
+/**
+ * OAuth 2.0 discovery endpoints for the bridge.
+ *
+ * When auth is enabled these routes expose:
+ *  - GET  /.well-known/oauth-protected-resource[/*]  (RFC 9728)
+ *  - GET  /.well-known/oauth-authorization-server[/*] (RFC 8414 — proxied from issuer)
+ *  - POST /oauth/register                             (Pseudo-DCR — RFC 7591)
+ *
+ * These endpoints are unauthenticated — they must be accessible to
+ * any client performing OAuth discovery before obtaining a token.
+ */
+
+import { Router, type Request, type Response } from 'express'
+import type { AuthConfig, Logger } from '../types.js'
+
+export function createDiscoveryRouter(auth: AuthConfig, logger: Logger): Router {
+  const router = Router()
+
+  /**
+   * RFC 9728 — OAuth Protected Resource Metadata
+   *
+   * Tells the client:
+   *  - which authorization server protects this resource
+   *  - which scopes are available
+   *  - where to find the authorization server metadata
+   *
+   * Handles both root and path-suffixed variants (e.g. /.well-known/oauth-protected-resource/mcp)
+   * as required by the MCP SDK for path-based resource discovery.
+   */
+  router.get('/.well-known/oauth-protected-resource*', (req: Request, res: Response) => {
+    const scheme = req.protocol
+    const host = req.get('host')
+    const resourceMetadata = {
+      resource: `${scheme}://${host}/`,
+      authorization_servers: [auth.issuer],
+      scopes_supported: ['openid', 'profile', 'email'],
+      bearer_methods_supported: ['header'],
+    }
+    res.json(resourceMetadata)
+  })
+
+  /**
+   * RFC 8414 — Authorization Server Metadata (proxied)
+   *
+   * We proxy the issuer's .well-known/oauth-authorization-server document
+   * and patch `registration_endpoint` to point to our local pseudo-DCR.
+   *
+   * Handles both root and path-suffixed variants.
+   */
+  router.get('/.well-known/oauth-authorization-server*', async (req: Request, res: Response) => {
+    try {
+      const metadataUrl = `${auth.issuer}/.well-known/oauth-authorization-server`
+      const upstream = await fetch(metadataUrl)
+
+      if (!upstream.ok) {
+        logger.error(`[discovery] Failed to fetch AS metadata: ${upstream.status}`)
+        return res.status(502).json({ error: 'upstream_error' })
+      }
+
+      const metadata = (await upstream.json()) as Record<string, unknown>
+
+      // Patch registration_endpoint to point to our pseudo-DCR
+      const scheme = req.protocol
+      const host = req.get('host')
+      metadata.registration_endpoint = `${scheme}://${host}/oauth/register`
+
+      res.json(metadata)
+    } catch (err: any) {
+      logger.error('[discovery] Error proxying AS metadata:', err.message ?? err)
+      res.status(502).json({ error: 'upstream_error' })
+    }
+  })
+
+  /**
+   * Pseudo–Dynamic Client Registration (RFC 7591)
+   *
+   * Always returns the same pre-registered client_id — no new client
+   * is actually created.  This lets standards-based OAuth clients
+   * (e.g., VS Code Copilot) discover the correct client_id through
+   * the normal DCR flow without requiring out-of-band configuration.
+   */
+  router.post('/oauth/register', (_req: Request, res: Response) => {
+    res.status(201).json({
+      client_id: auth.clientId,
+      client_name: 'platf-bridge',
+      // No client_secret — public client using PKCE
+      token_endpoint_auth_method: 'none',
+      grant_types: ['authorization_code'],
+      response_types: ['code'],
+      redirect_uris: [], // Client provides its own redirect_uri
+    })
+  })
+
+  return router
+}

package/src/lib/getLogger.ts

@@ -0,0 +1,49 @@
+import util from 'node:util'
+import type { Logger } from '../types.js'
+
+const defaultFormatArgs = (args: unknown[]) => args
+
+const log =
+  ({ formatArgs = defaultFormatArgs }: { formatArgs?: typeof defaultFormatArgs } = {}) =>
+  (...args: unknown[]) =>
+    console.log('[platf-bridge]', ...formatArgs(args))
+
+const logStderr =
+  ({ formatArgs = defaultFormatArgs }: { formatArgs?: typeof defaultFormatArgs } = {}) =>
+  (...args: unknown[]) =>
+    console.error('[platf-bridge]', ...formatArgs(args))
+
+const noneLogger: Logger = {
+  info: () => {},
+  error: () => {},
+}
+
+const infoLogger: Logger = {
+  info: log(),
+  error: logStderr(),
+}
+
+const debugFormatArgs = (args: unknown[]) =>
+  args.map((arg) => {
+    if (typeof arg === 'object') {
+      return util.inspect(arg, {
+        depth: null,
+        colors: process.stderr.isTTY,
+        compact: false,
+      })
+    }
+    return arg
+  })
+
+const debugLogger: Logger = {
+  info: log({ formatArgs: debugFormatArgs }),
+  error: logStderr({ formatArgs: debugFormatArgs }),
+}
+
+export type LogLevel = 'none' | 'info' | 'debug'
+
+export function getLogger(logLevel: LogLevel): Logger {
+  if (logLevel === 'none') return noneLogger
+  if (logLevel === 'debug') return debugLogger
+  return infoLogger
+}

package/src/lib/headers.ts

@@ -0,0 +1,26 @@
+import type { Logger } from '../types.js'
+
+export function parseHeaders(
+  rawHeaders: (string | number)[],
+  logger: Logger,
+): Record<string, string> {
+  return rawHeaders.reduce<Record<string, string>>((acc, rawHeader) => {
+    const header = `${rawHeader}`
+    const colonIndex = header.indexOf(':')
+    if (colonIndex === -1) {
+      logger.error(`Invalid header format: ${header}, ignoring`)
+      return acc
+    }
+
+    const key = header.slice(0, colonIndex).trim()
+    const value = header.slice(colonIndex + 1).trim()
+
+    if (!key || !value) {
+      logger.error(`Invalid header format: ${header}, ignoring`)
+      return acc
+    }
+
+    acc[key] = value
+    return acc
+  }, {})
+}

package/src/lib/onSignals.ts

@@ -0,0 +1,24 @@
+import type { Logger } from '../types.js'
+
+export interface OnSignalsOptions {
+  logger: Logger
+  cleanup?: () => void
+}
+
+export function onSignals({ logger, cleanup }: OnSignalsOptions): void {
+  const handleSignal = (signal: string) => {
+    logger.info(`Caught ${signal}. Exiting...`)
+    cleanup?.()
+    process.exit(0)
+  }
+
+  process.on('SIGINT', () => handleSignal('SIGINT'))
+  process.on('SIGTERM', () => handleSignal('SIGTERM'))
+  process.on('SIGHUP', () => handleSignal('SIGHUP'))
+
+  process.stdin.on('close', () => {
+    logger.info('stdin closed. Exiting...')
+    cleanup?.()
+    process.exit(0)
+  })
+}

package/src/lib/sessionAccessCounter.ts

@@ -0,0 +1,98 @@
+import type { Logger } from '../types.js'
+
+export class SessionAccessCounter {
+  private sessions = new Map<
+    string,
+    { accessCount: number } | { timeout: Timer }
+  >()
+
+  constructor(
+    private readonly timeoutMs: number,
+    private readonly cleanup: (sessionId: string) => unknown,
+    private readonly logger: Logger,
+  ) {}
+
+  inc(sessionId: string, reason: string) {
+    this.logger.info(`SessionAccessCounter.inc() ${sessionId}, caused by ${reason}`)
+
+    const session = this.sessions.get(sessionId)
+
+    if (!session) {
+      this.logger.info(`Session access count 0 -> 1 for ${sessionId} (new session)`)
+      this.sessions.set(sessionId, { accessCount: 1 })
+      return
+    }
+
+    if ('timeout' in session) {
+      this.logger.info(`Session access count 0 -> 1, clearing cleanup timeout for ${sessionId}`)
+      clearTimeout(session.timeout)
+      this.sessions.set(sessionId, { accessCount: 1 })
+    } else {
+      this.logger.info(
+        `Session access count ${session.accessCount} -> ${session.accessCount + 1} for ${sessionId}`,
+      )
+      session.accessCount++
+    }
+  }
+
+  dec(sessionId: string, reason: string) {
+    this.logger.info(`SessionAccessCounter.dec() ${sessionId}, caused by ${reason}`)
+
+    const session = this.sessions.get(sessionId)
+
+    if (!session) {
+      this.logger.error(`Called dec() on non-existent session ${sessionId}, ignoring`)
+      return
+    }
+
+    if ('timeout' in session) {
+      this.logger.error(
+        `Called dec() on session ${sessionId} that is already pending cleanup, ignoring`,
+      )
+      return
+    }
+
+    if (session.accessCount <= 0) {
+      throw new Error(`Invalid access count ${session.accessCount} for session ${sessionId}`)
+    }
+
+    session.accessCount--
+    this.logger.info(
+      `Session access count ${session.accessCount + 1} -> ${session.accessCount} for ${sessionId}`,
+    )
+
+    if (session.accessCount === 0) {
+      this.logger.info(
+        `Session access count reached 0, setting cleanup timeout for ${sessionId}`,
+      )
+
+      this.sessions.set(sessionId, {
+        timeout: setTimeout(() => {
+          this.logger.info(`Session ${sessionId} timed out, cleaning up`)
+          this.sessions.delete(sessionId)
+          this.cleanup(sessionId)
+        }, this.timeoutMs),
+      })
+    }
+  }
+
+  clear(sessionId: string, runCleanup: boolean, reason: string) {
+    this.logger.info(`SessionAccessCounter.clear() ${sessionId}, caused by ${reason}`)
+
+    const session = this.sessions.get(sessionId)
+    if (!session) {
+      this.logger.info(`Attempted to clear non-existent session ${sessionId}`)
+      return
+    }
+
+    if ('timeout' in session) {
+      clearTimeout(session.timeout)
+    }
+
+    this.sessions.delete(sessionId)
+
+    if (runCleanup) {
+      this.cleanup(sessionId)
+    }
+  }
+}

package/src/types.ts

@@ -0,0 +1,12 @@
+export interface Logger {
+  info: (...args: unknown[]) => void
+  error: (...args: unknown[]) => void
+}
+
+/** OAuth auth config passed when --authIssuer is set */
+export interface AuthConfig {
+  /** OAuth issuer URL (e.g. https://auth.platf.ai) */
+  issuer: string
+  /** OAuth client_id for this bridge instance */
+  clientId: string
+}