@igstack/app-catalog-backend-core 0.0.1

package/src/modules/assets/upsertAsset.ts

@@ -0,0 +1,46 @@
+import { parseAssetMeta } from './assetUtils'
+import type { AssetType, PrismaClient } from '@prisma/client'
+
+export interface UpsertAssetParams {
+  prisma: PrismaClient
+  buffer: Buffer
+  name: string
+  originalFilename: string
+  assetType: AssetType
+}
+
+export async function upsertAsset({
+  prisma,
+  buffer,
+  name,
+  originalFilename,
+  assetType,
+}: UpsertAssetParams) {
+  const { checksum, fileSize, width, height, mimeType } = await parseAssetMeta({
+    buffer,
+    originalFilename,
+  })
+
+  // If an asset with the same checksum already exists, reuse it instead of storing duplicate binary.
+  const existing = await prisma.dbAsset.findUnique({
+    where: { name },
+  })
+
+  if (existing) {
+    return existing.id
+  }
+
+  const asset = await prisma.dbAsset.create({
+    data: {
+      name,
+      checksum,
+      assetType,
+      content: new Uint8Array(buffer),
+      mimeType,
+      fileSize,
+      width,
+      height,
+    },
+  })
+  return asset.id
+}

package/src/modules/auth/auth.ts

@@ -0,0 +1,51 @@
+import type { BetterAuthOptions, BetterAuthPlugin } from 'better-auth'
+import { betterAuth } from 'better-auth'
+import { prismaAdapter } from 'better-auth/adapters/prisma'
+import { getDbClient } from '../../db'
+
+export interface AuthConfig {
+  appName?: string
+  baseURL: string
+  secret: string
+  providers?: BetterAuthOptions['socialProviders']
+  plugins?: Array<BetterAuthPlugin>
+  /** Session expiration in seconds. Default: 7 days (604800) */
+  sessionExpiresIn?: number
+  /** Session update age in seconds. Default: 1 day (86400) */
+  sessionUpdateAge?: number
+}
+
+export function createAuth(config: AuthConfig) {
+  const prisma = getDbClient()
+  const isProduction = process.env.NODE_ENV === 'production'
+
+  const auth = betterAuth({
+    appName: config.appName || 'EnvHopper',
+    baseURL: config.baseURL,
+    basePath: '/api/auth',
+    secret: config.secret,
+    database: prismaAdapter(prisma, {
+      provider: 'postgresql',
+    }),
+    socialProviders: config.providers || {},
+    plugins: config.plugins || [],
+    emailAndPassword: {
+      enabled: true,
+    },
+    session: {
+      expiresIn: config.sessionExpiresIn ?? 60 * 60 * 24 * 30,
+      updateAge: config.sessionUpdateAge ?? 60 * 60 * 24,
+      cookieCache: {
+        enabled: true,
+        maxAge: 300,
+      },
+    },
+    advanced: {
+      useSecureCookies: isProduction,
+    },
+  })
+
+  return auth
+}
+
+export type BetterAuth = ReturnType<typeof createAuth>

package/src/modules/auth/authProviders.ts

@@ -0,0 +1,40 @@
+/**
+ * Auth provider types and utilities
+ *
+ * Note: app-catalog backend-core does not read environment variables directly.
+ * Auth configuration (providers, plugins, admin groups) should be passed via
+ * middleware parameters by the client application.
+ *
+ * Example client-side configuration:
+ *
+ * ```typescript
+ * import { genericOAuth, okta } from 'better-auth/plugins'
+ *
+ * const authConfig = {
+ *   baseURL: process.env.BETTER_AUTH_URL,
+ *   secret: process.env.BETTER_AUTH_SECRET,
+ *   providers: {
+ *     github: {
+ *       clientId: process.env.AUTH_GITHUB_CLIENT_ID,
+ *       clientSecret: process.env.AUTH_GITHUB_CLIENT_SECRET,
+ *     },
+ *     google: {
+ *       clientId: process.env.AUTH_GOOGLE_CLIENT_ID,
+ *       clientSecret: process.env.AUTH_GOOGLE_CLIENT_SECRET,
+ *     },
+ *   },
+ *   plugins: [
+ *     genericOAuth({
+ *       config: [
+ *         okta({
+ *           clientId: process.env.AUTH_OKTA_CLIENT_ID,
+ *           clientSecret: process.env.AUTH_OKTA_CLIENT_SECRET,
+ *           issuer: process.env.AUTH_OKTA_ISSUER,
+ *         }),
+ *       ],
+ *     }),
+ *   ],
+ *   adminGroups: ['env_hopper_ui_super_admins'],
+ * }
+ * ```
+ */

package/src/modules/auth/authRouter.ts

@@ -0,0 +1,75 @@
+import type { BetterAuthPlugin } from 'better-auth'
+import type { TRPCRootObject } from '@trpc/server'
+import type { EhTrpcContext } from '../../server/ehTrpcContext'
+import type { BetterAuth } from './auth'
+
+/**
+ * Create auth tRPC procedures
+ * @param t - tRPC instance
+ * @param auth - Better Auth instance (optional, for future extensions)
+ * @returns tRPC router with auth procedures
+ */
+export function createAuthRouter(
+  t: TRPCRootObject<EhTrpcContext, {}, {}>,
+  auth?: BetterAuth,
+) {
+  const router = t.router
+  const publicProcedure = t.procedure
+
+  return router({
+    getSession: publicProcedure.query(async ({ ctx }) => {
+      // User is now extracted in the tRPC context creation
+      return {
+        user: ctx.user ?? null,
+        isAuthenticated: !!ctx.user,
+      }
+    }),
+    getProviders: publicProcedure.query(() => {
+      // Return configured social providers and OAuth providers from plugins
+      const providers: Array<string> = []
+      const authOptions = auth?.options
+
+      // Add built-in social providers (github, google, etc.)
+      if (authOptions?.socialProviders) {
+        const socialProviders = authOptions.socialProviders as Record<
+          string,
+          unknown
+        >
+        Object.keys(socialProviders).forEach((key) => {
+          if (socialProviders[key]) {
+            providers.push(key)
+          }
+        })
+      }
+
+      // Add OAuth providers from plugins (like Okta via genericOAuth)
+      if (authOptions?.plugins) {
+        const plugins = authOptions.plugins
+        plugins.forEach((plugin) => {
+          const pluginWithConfig = plugin as BetterAuthPlugin & {
+            options?: {
+              config?: Array<{ providerId?: string }>
+            }
+          }
+          if (
+            pluginWithConfig.id === 'generic-oauth' &&
+            pluginWithConfig.options?.config
+          ) {
+            const configs = Array.isArray(pluginWithConfig.options.config)
+              ? pluginWithConfig.options.config
+              : [pluginWithConfig.options.config]
+            configs.forEach((config) => {
+              if (config.providerId) {
+                providers.push(config.providerId)
+              }
+            })
+          }
+        })
+      }
+
+      return { providers }
+    }),
+  })
+}
+
+export type AuthRouter = ReturnType<typeof createAuthRouter>

package/src/modules/auth/authorizationUtils.ts

@@ -0,0 +1,132 @@
+/**
+ * Authorization utilities for checking user permissions based on groups
+ *
+ * Groups are automatically included in the user session when:
+ * 1. Okta auth server has a "groups" claim configured
+ * 2. The auth policy rule includes "groups" in scope_whitelist
+ *
+ * Example usage in tRPC procedures:
+ * ```typescript
+ * myProcedure: protectedProcedure.query(async ({ ctx }) => {
+ *   if (requireAdmin(ctx.user)) {
+ *     // Admin-only logic
+ *   }
+ *   // Regular user logic
+ * })
+ * ```
+ */
+
+export interface UserWithGroups {
+  id: string
+  email: string
+  name?: string
+  // Groups from Okta (or other identity provider)
+  // This will be populated if groups claim is configured
+  [key: string]: any
+}
+
+/**
+ * Extract groups from user object
+ * Groups can be stored in different locations depending on the OAuth provider
+ */
+export function getUserGroups(
+  user: UserWithGroups | null | undefined,
+): Array<string> {
+  if (!user) {
+    console.log('[getUserGroups] No user provided')
+    return []
+  }
+
+  // Debug: Log all user properties to see what's available
+  console.log('[getUserGroups] === USER OBJECT DEBUG ===')
+  console.log('[getUserGroups] User ID:', user.id)
+  console.log('[getUserGroups] User email:', user.email)
+  console.log(
+    '[getUserGroups] User.env_hopper_groups:',
+    (user as any).env_hopper_groups,
+  )
+  console.log('[getUserGroups] User.groups:', user.groups)
+  console.log('[getUserGroups] User.oktaGroups:', (user as any).oktaGroups)
+  console.log('[getUserGroups] User.roles:', (user as any).roles)
+  console.log('[getUserGroups] All user keys:', Object.keys(user))
+  console.log(
+    '[getUserGroups] Full user object:',
+    JSON.stringify(user, null, 2),
+  )
+
+  // Check common locations for group information
+  // Order of preference: custom env_hopper_groups first
+  const groups =
+    (user as any).env_hopper_groups || // Custom env_hopper_groups claim (stores natera.env_hopper_ui.groups)
+    user.groups || // Standard "groups" claim
+    (user as any).oktaGroups || // Okta-specific
+    (user as any).roles || // Some providers use "roles"
+    []
+
+  const result = Array.isArray(groups) ? groups : []
+  console.log('[getUserGroups] Final groups result:', result)
+
+  return result
+}
+
+/**
+ * Check if user is a member of any of the specified groups
+ */
+export function isMemberOfAnyGroup(
+  user: UserWithGroups | null | undefined,
+  allowedGroups: Array<string>,
+): boolean {
+  const userGroups = getUserGroups(user)
+  return allowedGroups.some((group) => userGroups.includes(group))
+}
+
+/**
+ * Check if user is a member of all specified groups
+ */
+export function isMemberOfAllGroups(
+  user: UserWithGroups | null | undefined,
+  requiredGroups: Array<string>,
+): boolean {
+  const userGroups = getUserGroups(user)
+  return requiredGroups.every((group) => userGroups.includes(group))
+}
+
+/**
+ * Check if user has admin permissions
+ * @param user User object with groups
+ * @param adminGroups List of admin group names (default: ['env_hopper_ui_super_admins'])
+ */
+export function isAdmin(
+  user: UserWithGroups | null | undefined,
+  adminGroups: Array<string> = ['env_hopper_ui_super_admins'],
+): boolean {
+  return isMemberOfAnyGroup(user, adminGroups)
+}
+
+/**
+ * Require admin permissions - throws error if not admin
+ * @param user User object with groups
+ * @param adminGroups List of admin group names (default: ['env_hopper_ui_super_admins'])
+ */
+export function requireAdmin(
+  user: UserWithGroups | null | undefined,
+  adminGroups: Array<string> = ['env_hopper_ui_super_admins'],
+): void {
+  if (!isAdmin(user, adminGroups)) {
+    throw new Error('Forbidden: Admin access required')
+  }
+}
+
+/**
+ * Require membership in specific groups - throws error if not member
+ */
+export function requireGroups(
+  user: UserWithGroups | null | undefined,
+  groups: Array<string>,
+): void {
+  if (!isMemberOfAnyGroup(user, groups)) {
+    throw new Error(
+      `Forbidden: Membership in one of these groups required: ${groups.join(', ')}`,
+    )
+  }
+}

package/src/modules/auth/devMockUserUtils.ts

@@ -0,0 +1,49 @@
+import type { EhDevMockUser } from '../../middleware/types'
+import type { User } from 'better-auth/types'
+
+/**
+ * Extended User type with app-catalog specific fields
+ */
+type EhUser = User & {
+  env_hopper_groups?: Array<string>
+}
+
+/**
+ * Creates a complete User object from basic dev mock user details
+ */
+export function createMockUserFromDevConfig(devUser: EhDevMockUser): EhUser {
+  return {
+    id: devUser.id,
+    email: devUser.email,
+    name: devUser.name,
+    emailVerified: true,
+    createdAt: new Date(),
+    updatedAt: new Date(),
+    env_hopper_groups: devUser.groups,
+  }
+}
+
+/**
+ * Creates a mock session response for /api/auth/session endpoint
+ */
+export function createMockSessionResponse(devUser: EhDevMockUser) {
+  return {
+    user: {
+      id: devUser.id,
+      email: devUser.email,
+      name: devUser.name,
+      emailVerified: true,
+      createdAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+      env_hopper_groups: devUser.groups,
+    },
+    session: {
+      id: `${devUser.id}-session`,
+      userId: devUser.id,
+      expiresAt: new Date(Date.now() + 1000 * 60 * 60 * 24 * 30).toISOString(), // 30 days
+      token: `${devUser.id}-token`,
+      createdAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+    },
+  }
+}

package/src/modules/auth/registerAuthRoutes.ts

@@ -0,0 +1,33 @@
+import { toNodeHandler } from 'better-auth/node'
+import type { Express, Request, Response } from 'express'
+import type { BetterAuth } from './auth'
+
+/**
+ * Register Better Auth routes with Express
+ * @param app - Express application instance
+ * @param auth - Better Auth instance
+ */
+export function registerAuthRoutes(app: Express, auth: BetterAuth) {
+  // Explicit session endpoint handler
+  // Better Auth's toNodeHandler doesn't expose a direct /session endpoint
+  app.get('/api/auth/session', async (req: Request, res: Response) => {
+    try {
+      const session = await auth.api.getSession({
+        headers: req.headers as HeadersInit,
+      })
+      if (session) {
+        res.json(session)
+      } else {
+        res.status(401).json({ error: 'Not authenticated' })
+      }
+    } catch (error) {
+      console.error('[Auth Session Error]', error)
+      res.status(500).json({ error: 'Internal server error' })
+    }
+  })
+
+  // Use toNodeHandler to adapt better-auth for Express/Node.js
+  // Express v5 wildcard syntax: /{*any} (also works with Express v4)
+  const authHandler = toNodeHandler(auth)
+  app.all('/api/auth/{*any}', authHandler)
+}

package/src/modules/icons/iconRestController.ts

@@ -0,0 +1,171 @@
+import type { Request, Response, Router } from 'express'
+import multer from 'multer'
+import { createHash } from 'node:crypto'
+import { getDbClient } from '../../db'
+import { getExtensionFromFilename, getExtensionFromMimeType } from './iconUtils'
+
+// Configure multer for memory storage
+const upload = multer({
+  storage: multer.memoryStorage(),
+  limits: {
+    fileSize: 10 * 1024 * 1024, // 10MB limit
+  },
+  fileFilter: (_req, file, cb) => {
+    // Accept images only
+    if (!file.mimetype.startsWith('image/')) {
+      cb(new Error('Only image files are allowed'))
+      return
+    }
+    cb(null, true)
+  },
+})
+
+export interface IconRestControllerConfig {
+  /**
+   * Base path for icon endpoints (e.g., '/api/icons')
+   */
+  basePath: string
+}
+
+/**
+ * Registers REST endpoints for icon upload and retrieval
+ *
+ * Endpoints:
+ * - POST {basePath}/upload - Upload a new icon (multipart/form-data with 'icon' field and 'name' field)
+ * - GET {basePath}/:id - Get icon binary by ID
+ * - GET {basePath}/:id/metadata - Get icon metadata only
+ */
+export function registerIconRestController(
+  router: Router,
+  config: IconRestControllerConfig,
+): void {
+  const { basePath } = config
+
+  // Upload endpoint - accepts multipart/form-data
+  router.post(
+    `${basePath}/upload`,
+    upload.single('icon'),
+    async (req: Request, res: Response) => {
+      try {
+        if (!req.file) {
+          res.status(400).json({ error: 'No file uploaded' })
+          return
+        }
+
+        let name = req.body['name'] as string
+        if (!name) {
+          res.status(400).json({ error: 'Name is required' })
+          return
+        }
+
+        // Extract extension from original filename or derive from MIME type
+        const extension =
+          getExtensionFromFilename(req.file.originalname) ||
+          getExtensionFromMimeType(req.file.mimetype)
+
+        // Add extension to name if not already present
+        if (!name.includes('.')) {
+          name = `${name}.${extension}`
+        }
+
+        const prisma = getDbClient()
+        const checksum = createHash('sha256')
+          .update(req.file.buffer)
+          .digest('hex')
+        const icon = await prisma.dbAsset.create({
+          data: {
+            name,
+            assetType: 'icon',
+            content: new Uint8Array(req.file.buffer),
+            mimeType: req.file.mimetype,
+            fileSize: req.file.size,
+            checksum,
+          },
+        })
+
+        res.status(201).json({
+          id: icon.id,
+          name: icon.name,
+          mimeType: icon.mimeType,
+          fileSize: icon.fileSize,
+          createdAt: icon.createdAt,
+        })
+      } catch (error) {
+        console.error('Error uploading icon:', error)
+        res.status(500).json({ error: 'Failed to upload icon' })
+      }
+    },
+  )
+
+  // Get icon binary by name (e.g., /api/icons/jira.svg)
+  router.get(`${basePath}/:name`, async (req: Request, res: Response) => {
+    try {
+      const { name } = req.params
+
+      const prisma = getDbClient()
+      const icon = await prisma.dbAsset.findFirst({
+        where: {
+          name,
+          assetType: 'icon',
+        },
+        select: {
+          content: true,
+          mimeType: true,
+          name: true,
+        },
+      })
+
+      if (!icon) {
+        res.status(404).json({ error: 'Icon not found' })
+        return
+      }
+
+      // Set appropriate headers
+      res.setHeader('Content-Type', icon.mimeType)
+      res.setHeader('Content-Disposition', `inline; filename="${icon.name}"`)
+      res.setHeader('Cache-Control', 'public, max-age=86400') // Cache for 1 day
+
+      // Send binary content
+      res.send(icon.content)
+    } catch (error) {
+      console.error('Error fetching icon:', error)
+      res.status(500).json({ error: 'Failed to fetch icon' })
+    }
+  })
+
+  // Get icon metadata only (no binary content)
+  router.get(
+    `${basePath}/:name/metadata`,
+    async (req: Request, res: Response) => {
+      try {
+        const { name } = req.params
+
+        const prisma = getDbClient()
+        const icon = await prisma.dbAsset.findFirst({
+          where: {
+            name,
+            assetType: 'icon',
+          },
+          select: {
+            id: true,
+            name: true,
+            mimeType: true,
+            fileSize: true,
+            createdAt: true,
+            updatedAt: true,
+          },
+        })
+
+        if (!icon) {
+          res.status(404).json({ error: 'Icon not found' })
+          return
+        }
+
+        res.json(icon)
+      } catch (error) {
+        console.error('Error fetching icon metadata:', error)
+        res.status(500).json({ error: 'Failed to fetch icon metadata' })
+      }
+    },
+  )
+}