@env-hopper/backend-core 2.0.1-alpha → 2.0.1-alpha.2

package/src/modules/assets/syncAssets.ts

@@ -0,0 +1,261 @@
+import { readFileSync, readdirSync } from 'node:fs'
+import { extname, join } from 'node:path'
+import { getDbClient } from '../../db'
+import { generateChecksum, getImageDimensions } from './assetUtils'
+
+export interface SyncAssetsConfig {
+  /**
+   * Directory containing icon files to sync
+   */
+  iconsDir?: string
+
+  /**
+   * Directory containing screenshot files to sync
+   */
+  screenshotsDir?: string
+}
+
+/**
+ * Sync local asset files (icons and screenshots) from directories into the database.
+ * 
+ * This function allows consuming applications to sync asset files without directly
+ * exposing the Prisma client. It handles:
+ * - Icon files: Assigned to apps by matching filename to icon name patterns
+ * - Screenshot files: Assigned to apps by matching filename to app ID (format: <app-id>_screenshot_<no>.<ext>)
+ * 
+ * @param config Configuration with paths to icon and screenshot directories
+ */
+export async function syncAssets(config: SyncAssetsConfig): Promise<{
+  iconsUpserted: number
+  screenshotsUpserted: number
+}> {
+  const prisma = getDbClient()
+  let iconsUpserted = 0
+  let screenshotsUpserted = 0
+
+  // Sync icons from local/icons directory
+  if (config.iconsDir) {
+    console.log(`📁 Syncing icons from ${config.iconsDir}...`)
+    iconsUpserted = await syncIconsFromDirectory(prisma, config.iconsDir)
+    console.log(`   ✓ Upserted ${iconsUpserted} icons`)
+  }
+
+  // Sync screenshots from local/screenshots directory
+  if (config.screenshotsDir) {
+    console.log(`📷 Syncing screenshots from ${config.screenshotsDir}...`)
+    screenshotsUpserted = await syncScreenshotsFromDirectory(prisma, config.screenshotsDir)
+    console.log(`   ✓ Upserted ${screenshotsUpserted} screenshots and assigned to apps`)
+  }
+
+  return {
+    iconsUpserted,
+    screenshotsUpserted,
+  }
+}
+
+/**
+ * Sync icon files from a directory
+ */
+async function syncIconsFromDirectory(
+  prisma: ReturnType<typeof getDbClient>,
+  iconsDir: string,
+): Promise<number> {
+  let count = 0
+
+  try {
+    const files = readdirSync(iconsDir)
+
+    for (const file of files) {
+      const filePath = join(iconsDir, file)
+      const ext = extname(file).toLowerCase().slice(1) // Remove leading dot
+
+      // Skip non-image files
+      if (!['png', 'jpg', 'jpeg', 'gif', 'webp', 'svg'].includes(ext)) {
+        continue
+      }
+
+      try {
+        const content = readFileSync(filePath)
+        const buffer = Buffer.from(content)
+        const checksum = generateChecksum(buffer)
+        const iconName = file.replace(/\.[^/.]+$/, '') // Remove extension
+
+        // Check if asset with same checksum already exists
+        const existing = await prisma.dbAsset.findFirst({
+          where: { checksum, assetType: 'icon' },
+        })
+
+        if (existing) {
+          continue // Already synced
+        }
+
+        // Extract dimensions for raster images
+        let width: number | null = null
+        let height: number | null = null
+        if (!ext.includes('svg')) {
+          const { width: w, height: h } = await getImageDimensions(buffer)
+          width = w
+          height = h
+        }
+
+        // Determine MIME type
+        const mimeType = {
+          png: 'image/png',
+          jpg: 'image/jpeg',
+          jpeg: 'image/jpeg',
+          gif: 'image/gif',
+          webp: 'image/webp',
+          svg: 'image/svg+xml',
+        }[ext] || 'application/octet-stream'
+
+        await prisma.dbAsset.create({
+          data: {
+            name: iconName,
+            assetType: 'icon',
+            content: new Uint8Array(buffer),
+            checksum,
+            mimeType,
+            fileSize: buffer.length,
+            width,
+            height,
+          },
+        })
+
+        count++
+      } catch (error) {
+        console.warn(`  ⚠ Failed to sync icon ${file}:`, error)
+      }
+    }
+  } catch (error) {
+    console.error(`  ❌ Error reading icons directory:`, error)
+  }
+
+  return count
+}
+
+/**
+ * Sync screenshot files from a directory and assign to apps
+ */
+async function syncScreenshotsFromDirectory(
+  prisma: ReturnType<typeof getDbClient>,
+  screenshotsDir: string,
+): Promise<number> {
+  let count = 0
+
+  try {
+    const files = readdirSync(screenshotsDir)
+
+    // Group screenshots by app ID
+    const screenshotsByApp = new Map<string, Array<{ path: string; ext: string }>>()
+
+    for (const file of files) {
+      // Parse filename: <app-id>_screenshot_<no>.<ext>
+      const match = file.match(/^(.+?)_screenshot_(\d+)\.([^.]+)$/)
+      if (!match || !match[1] || !match[3]) {
+        continue
+      }
+
+      const appId = match[1]
+      const ext = match[3]
+      if (!screenshotsByApp.has(appId)) {
+        screenshotsByApp.set(appId, [])
+      }
+      screenshotsByApp.get(appId)!.push({
+        path: join(screenshotsDir, file),
+        ext,
+      })
+    }
+
+    // Process each app's screenshots
+    for (const [appId, screenshots] of screenshotsByApp) {
+      try {
+        // Check if app exists
+        const app = await prisma.dbAppForCatalog.findUnique({
+          where: { slug: appId },
+          select: { id: true },
+        })
+
+        if (!app) {
+          console.warn(`  ⚠ App not found: ${appId}`)
+          continue
+        }
+
+        // Sync screenshots for this app
+        for (const screenshot of screenshots) {
+          try {
+            const content = readFileSync(screenshot.path)
+            const buffer = Buffer.from(content)
+            const checksum = generateChecksum(buffer)
+
+            // Check if screenshot with same checksum already exists
+            const existing = await prisma.dbAsset.findFirst({
+              where: { checksum, assetType: 'screenshot' },
+            })
+
+            if (existing) {
+              // Link to app via screenshotIds array if not already linked
+              const existingApp = await prisma.dbAppForCatalog.findUnique({
+                where: { slug: appId },
+              })
+              if (existingApp && !existingApp.screenshotIds.includes(existing.id)) {
+                await prisma.dbAppForCatalog.update({
+                  where: { slug: appId },
+                  data: {
+                    screenshotIds: [...existingApp.screenshotIds, existing.id],
+                  },
+                })
+              }
+              continue
+            }
+
+            // Extract dimensions
+            const { width, height } = await getImageDimensions(buffer)
+
+            // Determine MIME type
+            const mimeType = {
+              png: 'image/png',
+              jpg: 'image/jpeg',
+              jpeg: 'image/jpeg',
+              gif: 'image/gif',
+              webp: 'image/webp',
+            }[screenshot.ext.toLowerCase()] || 'application/octet-stream'
+
+            // Create screenshot asset
+            const asset = await prisma.dbAsset.create({
+              data: {
+                name: `${appId}-screenshot-${Date.now()}`,
+                assetType: 'screenshot',
+                content: new Uint8Array(buffer),
+                checksum,
+                mimeType,
+                fileSize: buffer.length,
+                width,
+                height,
+              },
+            })
+
+            // Link screenshot to app via screenshotIds array
+            await prisma.dbAppForCatalog.update({
+              where: { slug: appId },
+              data: {
+                screenshotIds: {
+                  push: asset.id,
+                },
+              },
+            })
+
+            count++
+          } catch (error) {
+            console.warn(`  ⚠ Failed to sync screenshot ${screenshot.path}:`, error)
+          }
+        }
+      } catch (error) {
+        console.warn(`  ⚠ Failed to process app ${appId}:`, error)
+      }
+    }
+  } catch (error) {
+    console.error(`  ❌ Error reading screenshots directory:`, error)
+  }
+
+  return count
+}

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,108 @@
+/**
+ * Auth provider configuration from environment variables
+ * This is the recommended way to configure auth providers.
+ *
+ * Supports: GitHub, Google via environment variables
+ * For Okta and other custom providers, use getAuthPluginsFromEnv()
+ *
+ * Example .env:
+ * AUTH_GITHUB_CLIENT_ID=your_github_client_id
+ * AUTH_GITHUB_CLIENT_SECRET=your_github_client_secret
+ * AUTH_GOOGLE_CLIENT_ID=your_google_client_id
+ * AUTH_GOOGLE_CLIENT_SECRET=your_google_client_secret
+ */
+
+import type { BetterAuthOptions, BetterAuthPlugin } from 'better-auth'
+import { genericOAuth, okta } from 'better-auth/plugins'
+
+export function getAuthProvidersFromEnv(): BetterAuthOptions['socialProviders'] {
+  const providers: BetterAuthOptions['socialProviders'] = {}
+
+  // GitHub OAuth
+  if (
+    process.env.AUTH_GITHUB_CLIENT_ID &&
+    process.env.AUTH_GITHUB_CLIENT_SECRET
+  ) {
+    providers.github = {
+      clientId: process.env.AUTH_GITHUB_CLIENT_ID,
+      clientSecret: process.env.AUTH_GITHUB_CLIENT_SECRET,
+    }
+  }
+
+  // Google OAuth
+  if (
+    process.env.AUTH_GOOGLE_CLIENT_ID &&
+    process.env.AUTH_GOOGLE_CLIENT_SECRET
+  ) {
+    providers.google = {
+      clientId: process.env.AUTH_GOOGLE_CLIENT_ID,
+      clientSecret: process.env.AUTH_GOOGLE_CLIENT_SECRET,
+    }
+  }
+
+  return providers
+}
+
+/**
+ * Get auth plugins from environment variables
+ * Currently supports: Okta
+ *
+ * Example .env:
+ * AUTH_OKTA_CLIENT_ID=your_okta_client_id
+ * AUTH_OKTA_CLIENT_SECRET=your_okta_client_secret
+ * AUTH_OKTA_ISSUER=https://your-org.okta.com/oauth2/ausxb83g4wY1x09ec0h7
+ *
+ * Note: If you get "User is not assigned to the client application" errors,
+ * you need to configure your Okta application to allow all users:
+ * 1. In Okta Admin Console, go to Applications → Your App
+ * 2. Assignments tab → Assign to Groups → Add "Everyone" group
+ * OR
+ * 3. Edit the application → In "User consent" section, enable appropriate settings
+ *
+ * For group-based authorization:
+ * 1. Add "groups" scope to your auth server policy rule
+ * 2. Create a groups claim in your auth server
+ * 3. Groups will be available in the user object after authentication
+ */
+export function getAuthPluginsFromEnv(): Array<BetterAuthPlugin> {
+  const plugins: Array<BetterAuthPlugin> = []
+  const oktaConfig: Array<ReturnType<typeof okta>> = []
+
+  if (
+    process.env.AUTH_OKTA_CLIENT_ID &&
+    process.env.AUTH_OKTA_CLIENT_SECRET &&
+    process.env.AUTH_OKTA_ISSUER
+  ) {
+    oktaConfig.push(
+      okta({
+        clientId: process.env.AUTH_OKTA_CLIENT_ID,
+        clientSecret: process.env.AUTH_OKTA_CLIENT_SECRET,
+        issuer: process.env.AUTH_OKTA_ISSUER,
+      }),
+    )
+  }
+
+  if (oktaConfig.length > 0) {
+    plugins.push(genericOAuth({ config: oktaConfig }))
+  }
+
+  return plugins
+}
+
+/**
+ * Validate required auth environment variables
+ */
+export function validateAuthConfig(): void {
+  const secret = process.env.BETTER_AUTH_SECRET
+  const baseUrl = process.env.BETTER_AUTH_URL
+
+  if (!secret) {
+    console.warn(
+      'BETTER_AUTH_SECRET not set. Using development fallback. Set this in production!',
+    )
+  }
+
+  if (!baseUrl) {
+    console.info('BETTER_AUTH_URL not set. Using default http://localhost:3000')
+  }
+}

package/src/modules/auth/authRouter.ts

@@ -0,0 +1,77 @@
+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 }) => {
+      // Session will be extracted from cookies by better-auth middleware
+      // For now, return user info if available in context
+      const contextWithUser = ctx as EhTrpcContext & { user?: unknown }
+      return {
+        user: contextWithUser.user ?? null,
+        isAuthenticated: !!contextWithUser.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,114 @@
+/**
+ * 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) {
+    return []
+  }
+
+  // Check common locations for group information
+  const groups =
+    user.groups || // Standard "groups" claim
+    (user as any).env_hopper_groups || // Custom env_hopper_groups claim
+    (user as any).oktaGroups || // Okta-specific
+    (user as any).roles || // Some providers use "roles"
+    []
+
+  return Array.isArray(groups) ? groups : []
+}
+
+/**
+ * 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))
+}
+
+/**
+ * Get admin group names from environment variables
+ * Default: env_hopper_ui_super_admins
+ */
+export function getAdminGroupsFromEnv(): Array<string> {
+  const adminGroups =
+    process.env.AUTH_ADMIN_GROUPS || 'env_hopper_ui_super_admins'
+  return adminGroups
+    .split(',')
+    .map((g) => g.trim())
+    .filter(Boolean)
+}
+
+/**
+ * Check if user has admin permissions
+ */
+export function isAdmin(user: UserWithGroups | null | undefined): boolean {
+  const adminGroups = getAdminGroupsFromEnv()
+  return isMemberOfAnyGroup(user, adminGroups)
+}
+
+/**
+ * Require admin permissions - throws error if not admin
+ */
+export function requireAdmin(user: UserWithGroups | null | undefined): void {
+  if (!isAdmin(user)) {
+    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/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)
+}