iec-builder 0.1.0

package/src/config/env.ts

@@ -0,0 +1,117 @@
+import { z } from 'zod'
+import { config } from 'dotenv'
+import { fileURLToPath } from 'node:url'
+import { dirname, resolve } from 'node:path'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+config({ path: resolve(__dirname, '../../.env'), override: true })
+
+const envSchema = z.object({
+  NODE_ENV: z.enum(['development', 'staging', 'production', 'test']).default('development'),
+  PORT: z.string().transform(Number).default('3002'),
+  LOG_LEVEL: z.enum(['fatal', 'error', 'warn', 'info', 'debug', 'trace']).default('info'),
+
+  // Database
+  MONGODB_URI: z.string().default('mongodb://localhost:27017/builder'),
+  BIO_MONGODB_URI: z.string().default('mongodb://localhost:27017/bio'),
+  REDIS_URL: z.string().default('redis://localhost:6379'),
+
+  // Database provisioning hosts (used by db-provisioner for tenant DBs)
+  DB_MONGODB_ADMIN_URI: z.string().default(''),  // Admin connection for per-service credential management
+  DB_MONGODB_HOST: z.string().default('localhost'),
+  DB_MONGODB_PUBLIC_HOST: z.string().default(''),  // Public IP for external DB connections (whitelist feature)
+  DB_MONGODB_PORT: z.string().transform(Number).default('27017'),
+  DB_REDIS_ADMIN_URL: z.string().default(''),  // Admin connection for per-service Redis ACL management
+  DB_REDIS_HOST: z.string().default('localhost'),
+  DB_REDIS_PORT: z.string().transform(Number).default('6379'),
+  DB_NEO4J_ADMIN_URI: z.string().default(''),  // Admin connection for per-service Neo4j auth management
+  DB_NEO4J_ADMIN_USER: z.string().default(''),
+  DB_NEO4J_ADMIN_PASSWORD: z.string().default(''),
+  DB_NEO4J_HOST: z.string().default('localhost'),
+  DB_NEO4J_PORT: z.string().transform(Number).default('7687'),
+
+  // MinIO object storage (Vault-managed — admin creds live in Vault KV only)
+  MINIO_HOST: z.string().default('64.23.181.20'),
+  MINIO_PORT: z.string().transform(Number).default('9000'),
+
+  // Koko integration
+  KOKO_URL: z.string().default('https://koko.tawa.insureco.io'),
+
+  // Bio-ID OAuth provider
+  BIO_ID_URL: z.string().default('https://bio.tawa.insureco.io'),
+  BIO_INTERNAL_KEY: z.string().default(''),
+
+  // Build configuration
+  WORKSPACE_DIR: z.string().default('/tmp/iec-builds'),
+  DOCKER_REGISTRY: z.string().default('registry.insureco.io/insureco'),
+  DOCKER_REGISTRY_USER: z.string().default(''),  // Username for Docker registry auth
+  DOCKER_REGISTRY_TOKEN: z.string().default(''),  // Token/password for Docker registry auth
+
+  // Tarball upload limits
+  MAX_UPLOAD_SIZE_MB: z.string().transform(Number).default('500'),
+
+  // Framework detection and Dockerfile generation
+  ENABLE_AUTO_DOCKERFILE: z.string().default('true'),
+
+  // Catalog version enforcement (reject deploys below minimum catalog schema version)
+  ENFORCE_MINIMUM_CATALOG_VERSION: z.string().default('false'),
+
+  // Kubernetes
+  KUBECONFIG: z.string().default(''),
+  K8S_NAMESPACE: z.string().default('iec-platform'),
+  ENABLE_K8S_DEPLOY: z.string().default('false'),
+
+  // Cloudflare DNS
+  CLOUDFLARE_API_TOKEN: z.string().default(''),
+  CLOUDFLARE_ZONE_ID: z.string().default('0945f68a0f28faa9d93721b572586737'),
+  INGRESS_TARGET: z.string().default(''),
+  ENABLE_DNS_MANAGEMENT: z.string().default('false'),
+
+  // Forgejo (git.insureco.io) access for cloning private repos
+  FORGEJO_URL: z.string().default('https://git.insureco.io'),
+  FORGEJO_TOKEN: z.string().default(''),
+  FORGEJO_ADMIN_USER: z.string().default(''),
+  FORGEJO_ADMIN_PASSWORD: z.string().default(''),
+
+  // GitHub access for cloning private repos (PAT with repo scope)
+  GITHUB_TOKEN: z.string().default(''),
+
+  // Webhook secrets (for verifying GitHub/GitLab signatures)
+  GITHUB_WEBHOOK_SECRET: z.string().default(''),
+  GITLAB_WEBHOOK_SECRET: z.string().default(''),
+
+  // Wallet (deploy gate)
+  WALLET_URL: z.string().default(''),
+  INTERNAL_SERVICE_KEY: z.string().default(''),
+
+  // Build worker concurrency (max parallel builds)
+  BUILD_CONCURRENCY: z.string().transform(Number).default('3'),
+
+  // HashiCorp Vault (Phase 2: dynamic credentials)
+  VAULT_ADDR: z.string().default(''),      // Vault API address (e.g., http://vault.vault.svc.cluster.local:8200)
+  VAULT_TOKEN: z.string().default(''),     // Builder's Vault token for role management
+  VAULT_ENABLED: z.string().default('false'),  // Feature flag: 'true' to use Vault dynamic credentials
+
+  // Credential rotation
+  ROTATION_TTL_DAYS: z.string().transform(Number).default('30'),
+  RELAY_DIRECT_URL: z.string().default(''),      // InsureRelay URL for rotation notifications
+  RELAY_INTERNAL_KEY: z.string().default(''),     // Auth key for relay service
+
+  // AI proxy
+  ANTHROPIC_API_KEY: z.string().default(''),
+})
+
+export type Env = z.infer<typeof envSchema>
+
+export function loadEnv(): Env {
+  const result = envSchema.safeParse(process.env)
+
+  if (!result.success) {
+    const formatted = result.error.format()
+    throw new Error(`Invalid environment configuration: ${JSON.stringify(formatted, null, 2)}`)
+  }
+
+  return result.data
+}
+
+export const env = loadEnv()

package/src/index.ts

@@ -0,0 +1,153 @@
+import express from 'express'
+import { pinoHttp } from 'pino-http'
+import { env } from './config/env.js'
+import { logger } from './utils/logger.js'
+import { apiError } from './utils/response.js'
+import { authenticate } from './middleware/auth.js'
+import { connectDatabase, connectRedis, checkConnections, closeConnections } from './services/database.js'
+import { recoverStaleBuilds } from './services/builder.js'
+import { initBuildQueue, initBuildWorker, closeBuildQueue } from './services/build-queue.js'
+import { webhooksRouter } from './routes/webhooks.js'
+import { buildsRouter } from './routes/builds.js'
+import { servicesRouter } from './routes/services.js'
+import { oauthRouter } from './routes/oauth.js'
+import { configRouter } from './routes/config.js'
+import { aiRouter } from './routes/ai.js'
+import { usersRouter } from './routes/users.js'
+import { domainsRouter } from './routes/domains.js'
+import { databasesRouter } from './routes/databases.js'
+import { clusterRouter } from './routes/cluster.js'
+import { orgsRouter } from './routes/orgs.js'
+import { dbWhitelistRouter } from './routes/db-whitelist.js'
+import { storageRouter } from './routes/storage.js'
+import { rotationRouter, rotationDashboardRouter } from './routes/rotation.js'
+import { observabilityRouter } from './routes/observability.js'
+import { auditRouter } from './routes/audit.js'
+import { platformRouter } from './routes/platform.js'
+import { reconcileOnStartup } from './services/db-whitelist.js'
+import { startRotationScheduler } from './services/rotation-scheduler.js'
+
+const app = express()
+
+// Middleware
+app.use(express.json({ limit: `${env.MAX_UPLOAD_SIZE_MB}mb` }))
+app.use(pinoHttp({ logger }))
+
+// Health check
+app.get('/health', (_req, res) => {
+  res.json({ status: 'ok', service: 'iec-builder' })
+})
+
+// Readiness check
+app.get('/ready', async (_req, res) => {
+  const connections = await checkConnections()
+  if (connections.mongodb && connections.redis) {
+    res.json({ status: 'ready', connections })
+  } else {
+    res.status(503).json({ status: 'not ready', connections })
+  }
+})
+
+// Routes
+app.use('/webhooks', webhooksRouter)
+app.use('/builds', authenticate, buildsRouter)
+app.use('/services', authenticate, servicesRouter)
+app.use('/oauth', authenticate, oauthRouter)
+app.use('/services', authenticate, configRouter)  // Config sub-routes: /services/:name/config
+app.use('/ai', authenticate, aiRouter)
+app.use('/users', authenticate, usersRouter)
+app.use('/domains', authenticate, domainsRouter)
+app.use('/services', authenticate, databasesRouter)  // Database credential sub-routes: /services/:name/databases
+app.use('/cluster', authenticate, clusterRouter)
+app.use('/orgs', authenticate, orgsRouter)
+app.use('/services', authenticate, dbWhitelistRouter)  // DB whitelist sub-routes: /services/:name/databases/whitelist
+app.use('/databases', authenticate, dbWhitelistRouter)  // Global whitelist: /databases/whitelist
+app.use('/services', authenticate, storageRouter)       // Storage sub-routes: /services/:name/storage
+app.use('/services', authenticate, rotationRouter)      // Rotation sub-routes: /services/:name/rotation
+app.use('/rotation', authenticate, rotationDashboardRouter)  // Platform-wide: /rotation/upcoming
+app.use('/services', authenticate, observabilityRouter)  // Observability sub-routes: /services/:name/pods, /pods/logs, /troubleshoot
+app.use('/audit', authenticate, auditRouter)  // Audit log: /audit/events
+app.use('/platform', authenticate, platformRouter)  // Platform admin: /platform/dashboard
+
+// Error handler
+app.use((err: Error, _req: express.Request, res: express.Response, _next: express.NextFunction) => {
+  logger.error({ err }, 'Unhandled error')
+  res.status(500).json(apiError('INTERNAL_ERROR', 'Internal server error'))
+})
+
+// Start server
+async function start(): Promise<void> {
+  try {
+    logger.info('Connecting to MongoDB...')
+    await connectDatabase()
+    logger.info('MongoDB connected ✓')
+    logger.info('GridFS initialized for tarball storage ✓')
+
+    logger.info('Connecting to Redis...')
+    await connectRedis()
+    logger.info('Redis connected ✓')
+
+    // Recover builds left in active states from previous crash/restart
+    const recovered = await recoverStaleBuilds(0)
+    if (recovered > 0) {
+      logger.info({ recovered }, 'Recovered stale builds on startup')
+    }
+
+    // Initialize BullMQ build queue and worker
+    await initBuildQueue()
+    initBuildWorker()
+
+    // Graceful shutdown: drain active builds before exiting
+    const shutdown = async () => {
+      logger.info('Shutdown signal received — draining builds...')
+      await closeBuildQueue()
+      await closeConnections()
+      process.exit(0)
+    }
+    process.once('SIGTERM', shutdown)
+    process.once('SIGINT', shutdown)
+
+    // Reconcile ipset whitelist entries with DB records
+    reconcileOnStartup().catch(err => {
+      logger.error({ err }, 'Whitelist reconciliation failed')
+    })
+
+    // Start credential rotation scheduler
+    startRotationScheduler().catch(err => {
+      logger.error({ err }, 'Rotation scheduler crashed')
+    })
+
+    // Validate critical env vars at startup
+    const criticalWarnings: string[] = []
+    if (!process.env.CONFIG_ENCRYPTION_KEY) criticalWarnings.push('CONFIG_ENCRYPTION_KEY not set — managed secrets will fail')
+    if (!env.BIO_INTERNAL_KEY) criticalWarnings.push('BIO_INTERNAL_KEY not set — OAuth provisioning will fail')
+    if (!env.CLOUDFLARE_API_TOKEN) criticalWarnings.push('CLOUDFLARE_API_TOKEN not set — DNS management will fail')
+    if (!env.KUBECONFIG) criticalWarnings.push('KUBECONFIG not set — K8s deployments may fail')
+    if (!env.DB_MONGODB_ADMIN_URI) criticalWarnings.push('DB_MONGODB_ADMIN_URI not set — MongoDB credentials will not be provisioned')
+    if (!env.DB_REDIS_ADMIN_URL) criticalWarnings.push('DB_REDIS_ADMIN_URL not set — Redis credentials will not be provisioned')
+    if (!env.DB_NEO4J_ADMIN_URI) criticalWarnings.push('DB_NEO4J_ADMIN_URI not set — Neo4j credentials will not be provisioned')
+    if (env.VAULT_ENABLED !== 'true') criticalWarnings.push('VAULT_ENABLED not set — storage provisioning (MinIO) will not be available')
+    for (const warning of criticalWarnings) {
+      logger.warn(`STARTUP: ${warning}`)
+    }
+
+    app.listen(env.PORT, () => {
+      logger.info(`iec-builder running on port ${env.PORT}`)
+      logger.info(`Environment: ${env.NODE_ENV}`)
+      logger.info(`Workspace: ${env.WORKSPACE_DIR}`)
+      logger.info(`Registry: ${env.DOCKER_REGISTRY}`)
+      logger.info(`K8s deploy: ${env.ENABLE_K8S_DEPLOY}`)
+      logger.info(`DNS management: ${env.ENABLE_DNS_MANAGEMENT}`)
+      logger.info(`Auto-Dockerfile: ${env.ENABLE_AUTO_DOCKERFILE}`)
+      logger.info(`Max upload size: ${env.MAX_UPLOAD_SIZE_MB}MB`)
+      if (criticalWarnings.length > 0) {
+        logger.warn(`${criticalWarnings.length} critical warning(s) — check logs above`)
+      }
+    })
+  } catch (error) {
+    logger.error({ error }, 'Failed to start server')
+    process.exit(1)
+  }
+}
+
+start()

package/src/middleware/auth.ts

@@ -0,0 +1,294 @@
+import { Request, Response, NextFunction } from 'express'
+import { env } from '../config/env.js'
+import { logger } from '../utils/logger.js'
+import { apiError } from '../utils/response.js'
+
+export interface AuthenticatedUser {
+  id: string
+  email: string
+  name?: string
+  roles: string[]
+  org?: string      // Org slug (for service ownership, wallet derivation)
+  orgId?: string    // Canonical ORG-xxx identifier (for Bio-ID admin calls)
+}
+
+export type OrgRole = 'viewer' | 'member' | 'admin'
+
+export const ORG_ROLE_HIERARCHY: Record<OrgRole, number> = {
+  viewer: 1,
+  member: 2,
+  admin: 3,
+}
+
+/**
+ * Derive the effective org role from a user's roles array.
+ * Explicit org:admin > admin > org:member > member > default viewer
+ */
+export function deriveOrgRole(roles: string[]): OrgRole {
+  if (roles.includes('org:admin') || roles.includes('admin')) return 'admin'
+  if (roles.includes('org:member') || roles.includes('member')) return 'member'
+  if (roles.includes('org:viewer') || roles.includes('viewer')) return 'viewer'
+  return 'viewer'
+}
+
+export interface AuthenticatedRequest extends Request {
+  user?: AuthenticatedUser
+}
+
+/**
+ * Validate Bearer token from Authorization header
+ * Tries Koko CLI token verification first, then bio-id JWT introspection
+ */
+export async function validateToken(
+  req: AuthenticatedRequest,
+  res: Response,
+  next: NextFunction
+): Promise<void> {
+  const authHeader = req.headers.authorization
+
+  if (!authHeader || !authHeader.startsWith('Bearer ')) {
+    res.status(401).json(apiError('UNAUTHORIZED', 'Missing or invalid authorization header'))
+    return
+  }
+
+  const token = authHeader.substring(7)
+
+  try {
+    // Try Koko CLI token verification first (iec CLI uses these)
+    const kokoUrl = env.KOKO_URL || 'https://koko.tawa.insureco.io'
+    const kokoResponse = await fetch(`${kokoUrl}/api/auth/verify`, {
+      headers: {
+        Authorization: `Bearer ${token}`,
+      },
+    })
+
+    if (kokoResponse.ok) {
+      const kokoResult = await kokoResponse.json() as {
+        success: boolean
+        data?: { id: string; email: string; name: string; org?: string; orgId?: string; roles?: string[] }
+      }
+
+      if (kokoResult.success && kokoResult.data) {
+        req.user = {
+          id: kokoResult.data.id,
+          email: kokoResult.data.email,
+          name: kokoResult.data.name,
+          roles: kokoResult.data.roles || ['admin'],
+          org: kokoResult.data.org,
+          orgId: kokoResult.data.orgId,
+        }
+        next()
+        return
+      }
+    }
+
+    // Fall back to bio-id JWT introspection
+    const bioIdUrl = env.BIO_ID_URL || 'https://bio.tawa.insureco.io'
+    const response = await fetch(`${bioIdUrl}/api/auth/introspect`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({ token }),
+    })
+
+    if (!response.ok) {
+      logger.warn({ status: response.status }, 'Token validation failed (both Koko and bio-id)')
+      res.status(401).json(apiError('UNAUTHORIZED', 'Invalid or expired token'))
+      return
+    }
+
+    const result = await response.json() as {
+      active: boolean
+      user?: AuthenticatedUser
+      org_id?: string    // ORG-xxx (canonical)
+      org_slug?: string  // URL-friendly slug
+      organization_name?: string
+    }
+
+    if (!result.active || !result.user) {
+      res.status(401).json(apiError('UNAUTHORIZED', 'Token is not active'))
+      return
+    }
+
+    // Populate org (slug) and orgId (ORG-xxx) from introspection response.
+    const org = result.user.org
+      || result.org_slug
+    const orgId = result.org_id
+
+    req.user = { ...result.user, org, orgId }
+    next()
+  } catch (error) {
+    logger.error({ error }, 'Token validation error')
+    res.status(500).json(apiError('AUTH_ERROR', 'Failed to validate token'))
+  }
+}
+
+/**
+ * Simple API key authentication for CLI tools
+ * API keys are scoped to services and stored in the service record
+ */
+export async function validateApiKey(
+  req: AuthenticatedRequest,
+  res: Response,
+  next: NextFunction
+): Promise<void> {
+  const apiKey = req.headers['x-api-key'] as string
+
+  if (!apiKey) {
+    res.status(401).json(apiError('UNAUTHORIZED', 'Missing API key'))
+    return
+  }
+
+  try {
+    // Validate API key format: iec_<service-id>_<random-bytes>
+    if (!apiKey.startsWith('iec_')) {
+      res.status(401).json(apiError('UNAUTHORIZED', 'Invalid API key format'))
+      return
+    }
+
+    // Extract service ID from API key
+    const parts = apiKey.split('_')
+    if (parts.length < 3) {
+      res.status(401).json(apiError('UNAUTHORIZED', 'Invalid API key format'))
+      return
+    }
+
+    const serviceId = parts[1]
+
+    // Validate with koko service registry
+    const kokoUrl = env.KOKO_URL || 'https://koko.tawa.insureco.io'
+    const response = await fetch(`${kokoUrl}/api/services/${serviceId}/validate-key`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({ apiKey }),
+    })
+
+    if (!response.ok) {
+      logger.warn({ serviceId, status: response.status }, 'API key validation failed')
+      res.status(401).json(apiError('UNAUTHORIZED', 'Invalid API key'))
+      return
+    }
+
+    const result = await response.json() as { valid: boolean; serviceId: string; serviceName: string }
+
+    if (!result.valid) {
+      res.status(401).json(apiError('UNAUTHORIZED', 'API key is not valid'))
+      return
+    }
+
+    // Set user info from API key validation
+    const user: AuthenticatedUser = {
+      id: `service:${result.serviceId}`,
+      email: `${result.serviceName}@services.iec`,
+      name: result.serviceName,
+      roles: ['service'],
+    }
+    req.user = user
+
+    // Store service info for downstream use
+    ;(req as Request & { serviceId: string }).serviceId = result.serviceId
+
+    next()
+  } catch (error) {
+    logger.error({ error }, 'API key validation error')
+    res.status(500).json(apiError('AUTH_ERROR', 'Failed to validate API key'))
+  }
+}
+
+/**
+ * Combined auth middleware - accepts internal key, Bearer token, or API key.
+ * Internal key is used for trusted platform services (tawa-web, etc).
+ */
+export async function authenticate(
+  req: AuthenticatedRequest,
+  res: Response,
+  next: NextFunction
+): Promise<void> {
+  // Platform service-to-service auth via shared internal key
+  const internalKey = req.headers['x-internal-key'] as string
+  if (internalKey && env.INTERNAL_SERVICE_KEY && internalKey === env.INTERNAL_SERVICE_KEY) {
+    req.user = {
+      id: 'service:platform',
+      email: 'platform@internal.iec',
+      name: 'Platform Service',
+      roles: ['admin', 'service'],
+    }
+    next()
+    return
+  }
+
+  const authHeader = req.headers.authorization
+  const apiKey = req.headers['x-api-key']
+
+  if (authHeader && authHeader.startsWith('Bearer ')) {
+    return validateToken(req, res, next)
+  }
+
+  if (apiKey) {
+    return validateApiKey(req, res, next)
+  }
+
+  res.status(401).json(apiError('UNAUTHORIZED', 'Authentication required'))
+}
+
+/**
+ * Require specific roles
+ */
+export function requireRoles(...roles: string[]) {
+  return (req: AuthenticatedRequest, res: Response, next: NextFunction): void => {
+    if (!req.user) {
+      res.status(401).json(apiError('UNAUTHORIZED', 'Authentication required'))
+      return
+    }
+
+    const hasRole = roles.some(role => req.user!.roles.includes(role))
+    if (!hasRole) {
+      res.status(403).json(apiError('FORBIDDEN', `Required roles: ${roles.join(', ')}`))
+      return
+    }
+
+    next()
+  }
+}
+
+/**
+ * Validate webhook signature from GitHub
+ */
+export function validateGitHubWebhook(
+  req: Request,
+  res: Response,
+  next: NextFunction
+): void {
+  const signature = req.headers['x-hub-signature-256'] as string
+  const secret = env.GITHUB_WEBHOOK_SECRET
+
+  if (!secret) {
+    logger.warn('GitHub webhook secret not configured')
+    next()
+    return
+  }
+
+  if (!signature) {
+    res.status(401).json(apiError('UNAUTHORIZED', 'Missing webhook signature'))
+    return
+  }
+
+  const payload = JSON.stringify(req.body)
+  const expectedSignature = `sha256=${createHmacSignature(payload, secret)}`
+
+  if (signature !== expectedSignature) {
+    logger.warn('Invalid GitHub webhook signature')
+    res.status(401).json(apiError('UNAUTHORIZED', 'Invalid webhook signature'))
+    return
+  }
+
+  next()
+}
+
+function createHmacSignature(payload: string, secret: string): string {
+  const { createHmac } = require('crypto')
+  return createHmac('sha256', secret).update(payload).digest('hex')
+}

package/src/middleware/org-access.ts

@@ -0,0 +1,126 @@
+import { Response, NextFunction } from 'express'
+import { getServicesCollection } from '../services/database.js'
+import { apiError } from '../utils/response.js'
+import { logger } from '../utils/logger.js'
+import type { AuthenticatedRequest, OrgRole } from './auth.js'
+import { deriveOrgRole, ORG_ROLE_HIERARCHY } from './auth.js'
+import type { Service } from '../models/types.js'
+
+export interface ServiceScopedRequest extends AuthenticatedRequest {
+  service?: Service
+}
+
+/**
+ * Extract a service identifier from the request.
+ * Checks route params first, then request body.
+ */
+function extractServiceIdentifier(req: ServiceScopedRequest): string | undefined {
+  return (
+    req.params.serviceId ||
+    req.params.serviceName ||
+    req.body?.serviceId ||
+    req.body?.serviceName
+  )
+}
+
+/**
+ * Middleware: Verify the authenticated user belongs to the same org as the service.
+ *
+ * - Loads the service from DB and attaches it to `req.service`
+ * - Super admins and platform services bypass the check
+ * - Legacy services without `org` allow access (will be backfilled)
+ */
+export function requireOrgAccess() {
+  return async (req: ServiceScopedRequest, res: Response, next: NextFunction): Promise<void> => {
+    if (!req.user) {
+      res.status(401).json(apiError('UNAUTHORIZED', 'Authentication required'))
+      return
+    }
+
+    // Platform service and super_admin bypass
+    if (req.user.roles.includes('super_admin') || req.user.roles.includes('service')) {
+      next()
+      return
+    }
+
+    const serviceId = extractServiceIdentifier(req)
+    if (!serviceId) {
+      // Let the route handler deal with missing params
+      next()
+      return
+    }
+
+    try {
+      const services = getServicesCollection()
+      const service = await services.findOne({
+        $or: [{ id: serviceId }, { name: serviceId }],
+      })
+
+      if (!service) {
+        res.status(404).json(apiError('NOT_FOUND', 'Service not found'))
+        return
+      }
+
+      // Legacy services without org: allow access, log for visibility
+      if (!service.org) {
+        logger.debug({ serviceName: service.name }, 'Service has no org set — allowing access (legacy)')
+        req.service = service
+        next()
+        return
+      }
+
+      // Org match check
+      if (req.user.org !== service.org) {
+        res.status(403).json(apiError('FORBIDDEN', 'Service belongs to a different organization'))
+        return
+      }
+
+      req.service = service
+      next()
+    } catch (error) {
+      logger.error({ error }, 'Error in requireOrgAccess middleware')
+      next(error)
+    }
+  }
+}
+
+/**
+ * Middleware: Require a minimum org role level.
+ *
+ * Role hierarchy: viewer (1) < member (2) < admin (3)
+ * Roles are derived from the user's JWT/token claims:
+ *   - org:admin or admin → admin
+ *   - org:member or member → member
+ *   - org:viewer or viewer → viewer
+ *   - default → viewer
+ *
+ * Super admins and platform services always pass.
+ */
+export function requireOrgRole(minimumRole: OrgRole) {
+  const minimumLevel = ORG_ROLE_HIERARCHY[minimumRole]
+
+  return (req: ServiceScopedRequest, res: Response, next: NextFunction): void => {
+    if (!req.user) {
+      res.status(401).json(apiError('UNAUTHORIZED', 'Authentication required'))
+      return
+    }
+
+    // Super admin and platform service bypass
+    if (req.user.roles.includes('super_admin') || req.user.roles.includes('service')) {
+      next()
+      return
+    }
+
+    const effectiveRole = deriveOrgRole(req.user.roles)
+    const effectiveLevel = ORG_ROLE_HIERARCHY[effectiveRole]
+
+    if (effectiveLevel < minimumLevel) {
+      res.status(403).json(
+        apiError('FORBIDDEN', `Requires org role: ${minimumRole} (you have: ${effectiveRole})`)
+      )
+      return
+    }
+
+    next()
+  }
+}