Merge branch 'rc-v1' of ssh://ansible.subtype.internal:2424/subtype/subspace-api into rc-v1

Author: asubowo

package-lock.json

@@ -24,14 +24,17 @@
     "@modelcontextprotocol/sdk": "^1.9.0",
     "express-jwt": "^8.5.1",
     "express-rate-limit": "^7.5.0",
+    "express-session": "^1.18.1",
     "jose": "^6.0.10",
+    "keycloak-connect": "^26.1.1",
     "prettier": "3.5.3",
     "yahoo-finance2": "^2.13.3",
     "zod": "^3.24.2"
   },
   "devDependencies": {
     "@types/express": "^5.0.1",
     "@types/express-jwt": "^6.0.4",
+    "@types/express-session": "^1.18.1",
     "@types/jsonwebtoken": "^9.0.9",
     "@types/node": "^22.14.1",
     "dotenv": "^16.5.0",

package.json

@@ -0,0 +1,11 @@
+// Keycloak config file
+// Edit this file or update .env file
+export const keycloakConfig = {
+    realm: process.env.KEYCLOAK_REALM || 'subspace',
+    'auth-server-url': process.env.KEYCLOAK_AUTH_URL || 'https://auth.subtype.space',
+    resource: process.env.KEYCLOAK_RESOURCE || 'subspace-api',
+    'ssl-required': 'external',
+    'confidential-port': 443,
+    'bearer-only': true,
+  }
+  

src/configs/keycloakConfig.ts

@@ -5,13 +5,17 @@ import { Request } from 'express-jwt'
 import trmnlRouter from './v1/routers/trmnlRouter.js'
 import statusRouter from './v1/routers/statusRouter.js'
 import helmet from 'helmet'
+import session from 'express-session'
+
+import KeycloakConnect from 'keycloak-connect'
+import { keycloakConfig } from './configs/keycloakConfig.js'
 
 // MCP import shenanigans
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
 import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js'
 import { registerTools } from './v1/mcp/registerTools.js'
 
-import { logIncomingAuth, authRequired, authOptional } from './utils/auth.js'
+import { logIncomingAuth } from './utils/auth.js'
 import { rateLimiter } from './utils/rateLimiter.js'
 
 logger.info('Initializing MCP server...')
@@ -29,16 +33,28 @@ const PORT = process.env.PORT || 9595
 const ACTIVE_VERSION = process.env.API_VERSION || 'v1'
 // Register and enable model context protocol tools
 const transports: { [sessionId: string]: SSEServerTransport } = {}
+const memoryStore = new session.MemoryStore()
+const keycloak = new KeycloakConnect({ store: memoryStore }, keycloakConfig)
 
 logger.info('Registering tools with MCP server...')
 registerTools(mcpServer)
 
 logger.info('Setting up middleware...')
+// SESSION_SECRET should just be a super long random base64 encoded string
+server.use(
+  session({
+    secret: process.env.SESSION_SECRET!,
+    resave: false,
+    saveUninitialized: true,
+    store: memoryStore,
+  })
+)
+server.use(keycloak.middleware())
 server.use(helmet())
-logger.info('Initializing routes...')
+server.use(rateLimiter)
 
 // Declare regular REST API routing
-server.use(authOptional, rateLimiter)
+logger.info('Initializing routes...')
 
 //server.use('/v1/trmnl', express.json(), trmnlRouter) disable this route because it's just not active right now
 server.use('/', statusRouter)
@@ -48,6 +64,8 @@ server.use('/health', express.json(), statusRouter)
 server.set('trust proxy', 1)
 
 server.use(function (err: any, req: Request, res: Response, next: NextFunction) {
+  logger.debug(err)
+
   if (err.name === 'UnauthorizedError') {
     logger.warn('JWT failed authentication')
     res.status(401).send({ message: 'Unauthorized' })
@@ -61,7 +79,7 @@ server.use(function (err: any, req: Request, res: Response, next: NextFunction)
 
 // MCP Setup
 // Discovery endpoint
-server.get('/sse', logIncomingAuth, authRequired, async (req: Request, res: Response) => {
+server.get('/sse', logIncomingAuth, keycloak.protect(), async (req: Request, res: Response) => {
   const transport = new SSEServerTransport('/messages', res)
   transports[transport.sessionId] = transport
   logger.info('New MCP session created:', transport.sessionId)
@@ -73,7 +91,7 @@ server.get('/sse', logIncomingAuth, authRequired, async (req: Request, res: Resp
 })
 
 // MCP Handler
-server.post('/messages', logIncomingAuth, authRequired, async (req: Request, res: Response) => {
+server.post('/messages', logIncomingAuth, keycloak.protect(), async (req: Request, res: Response) => {
   const sessionId = req.query.sessionId as string
 
   if (typeof sessionId != 'string') {
@@ -90,6 +108,15 @@ server.post('/messages', logIncomingAuth, authRequired, async (req: Request, res
   }
 })
 
+// oauth
+server.get('/.well-known/oauth-protected-resource', async (_: Request, res: Response) => {
+  const baseURL = `https://api.subtype.space`
+  res.json({
+    resource: baseURL,
+    authorization_servers: [`https://auth.subtype.space`],
+  })
+})
+
 server.listen(PORT, () => {
   logger.info(`Using log level: ${process.env.LOG_LEVEL || 'info'}`)
   logger.info('Using API version:', ACTIVE_VERSION)

src/server.ts

@@ -0,0 +1,21 @@
+import 'express'
+
+declare module 'express-serve-static-core' {
+  interface Request {
+    kauth?: {
+      grant: {
+        access_token: {
+          content: {
+            preferred_username?: string
+            clientId?: string
+            sub: string
+            realm_access?: {
+              roles?: string[]
+            }
+            [key: string]: any
+          }
+        }
+      }
+    }
+  }
+}

src/types/express/index.d.ts

@@ -1,25 +1,46 @@
+// TODO: fine-grained tool access
+// https://developers.cloudflare.com/agents/model-context-protocol/authorization/
+
 import { expressjwt } from 'express-jwt'
 import { Request, Response, NextFunction } from 'express'
 import { logger } from './logger.js'
 
 const JWT_SECRET = process.env.JWT_SECRET
 
+// all of this may change due to keycloak oauth support
 export function logIncomingAuth(req: Request, res: Response, next: NextFunction) {
-  logger.debug('Incoming headers:', req.headers)
+  logger.info(
+    `[AUTH] Connection from ${req.headers['cf-connecting-ip'] ?? req.ip} - ${req.headers['cf-ipcountry'] ?? 'unknown country'}`
+  )
 
+  // For "manual" JWT
   const authHeader = req.headers.authorization
   if (!authHeader?.startsWith('Bearer ')) {
-    logger.warn('No auth header or bad format')
+    logger.warn('[AUTH] No auth header or bad format')
+    logger.debug('[AUTH] Incoming headers:', req.headers)
   } else {
     const token = authHeader.split(' ')[1]
-    logger.debug('Inspecting token:', token)
+    logger.debug('[AUTH] Inspecting token:', token)
+  }
+
+  // For Keycloak-specific OIDC
+  // TODO -- users may not want Keycloak, make this optional/toggle disable
+  const user = req.kauth?.grant?.access_token?.content
+  if (user) {
+    logger.info(`[AUTH] Authenticated as ${user.preferred_username ?? user.clientId ?? 'unknown'} (${user.sub})`)
+  } else {
+    logger.warn('[AUTH] No grant found on request')
+    logger.warn('[AUTH] Possible auth failure')
   }
 
   next()
 }
 
+// Deprecated exports, or present to support basic JWT authentication w/ shared secret
 export const authRequired = expressjwt({
   secret: JWT_SECRET!,
+  issuer: 'https://auth.subtype.space',
+  audience: 'https://api.subtype.space',
   algorithms: ['HS256'],
   credentialsRequired: true,
 })

src/utils/auth.ts

@@ -3,17 +3,29 @@ import { Request } from 'express-jwt' // this ideally should come after the cust
 import { logger } from './logger.js'
 import { Response } from 'express'
 
+function isAuthenticated(req: Request): boolean {
+  return Boolean(req.auth?.sub || req?.kauth?.grant?.access_token?.content?.sub)
+}
+
+function getSessionId(req: Request): string {
+  return req.auth?.sub ? `session-${req.auth.sub}` : (req.kauth?.grant?.access_token?.content?.sub ?? `anon-session-${req.ip}`)
+}
+
 export const rateLimiter: RateLimitRequestHandler = rateLimit({
   windowMs: 60 * 1000,
   limit: (req: Request): number => {
-    logger.debug(`Rate limit check ${req.auth ? 'authenticated' : 'anon'} - ${req.headers['cf-connecting-ip'] ?? req.ip}`)
-    return req.auth ? 60 : 5 // 60 req/min for auth, 5 for anon
+    const ip = req.headers['cf-connecting-ip'] ?? req.ip
+    const authed = isAuthenticated(req)
+    logger.info(`Rate limit check for ${authed ? 'authenticated' : 'anon'} - ${ip}`)
+    return authed ? 60 : 5 // 60 req/min for auth, 5 for anon
   },
   keyGenerator: (req: Request): string => {
-    return req.auth?.sub ? `session-${req.auth.sub}` : req.ip!
+    const ip = req.headers['cf-connecting-ip'] ?? req.ip
+    return getSessionId(req) ?? ip
   },
   handler: (req: Request, res: Response) => {
-    logger.warn('Rate limiting IP address:', req.ip)
+    const ip = req.headers['cf-connecting-ip'] ?? req.ip
+    logger.warn('Rate limiting IP address:', ip)
     res.status(429).send({ message: 'Rate limited' })
   },
 })

src/utils/rateLimiter.ts

@@ -1,10 +1,12 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { CallToolRequest, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js'
 import { z } from 'zod'
 import { getAlerts, getForecast } from './weather.js'
 import { getStockDetails } from './stocks.js'
 import { getIncidents, getStationInfo, getBusInfo } from './metro.js'
 import { logger } from '../../utils/logger.js'
 
+
 export function registerTools(mcpServer: McpServer) {
   mcpServer.tool(
     'get-alerts',

src/v1/mcp/registerTools.ts

@@ -8,7 +8,8 @@
       "strict": true,
       "esModuleInterop": true,
       "skipLibCheck": true,
-      "forceConsistentCasingInFileNames": false
+      "forceConsistentCasingInFileNames": false,
+      "typeRoots": ["./types", "./node_modules/@types"]
     },
     "include": ["src/**/*"],
     "exclude": ["node_modules"]