@igstack/app-catalog-backend-core 0.3.1-alpha-20260403020019 → 0.3.1-alpha-20260405015231

package/src/generated/prisma/models.ts

@@ -12,8 +12,12 @@ export type * from './models/user'
 export type * from './models/session'
 export type * from './models/account'
 export type * from './models/verification'
+export type * from './models/DbPerson'
+export type * from './models/DbGroup'
+export type * from './models/DbGroupMembership'
 export type * from './models/DbApprovalMethod'
 export type * from './models/DbAppForCatalog'
+export type * from './models/DbSubResource'
 export type * from './models/DbAppTagDefinition'
 export type * from './models/DbAsset'
 export type * from './models/Source'

package/src/middleware/featureRegistry.ts

@@ -74,7 +74,10 @@ const FEATURES: FeatureRegistration[] = [
               }
               res.json({ ...session, isAdmin: admin })
             } else {
-              res.status(401).json({ error: 'Not authenticated' })
+              // Return 200 with null session instead of 401 to avoid
+              // browser "Failed to load resource" console errors.
+              // The frontend checks for session.user to determine auth state.
+              res.json({ session: null, user: null, isAuthenticated: false })
             }
           } catch (error) {
             console.error('[Auth Session Error]', error)

package/src/modules/appCatalog/checkLinks.ts

@@ -20,6 +20,59 @@ async function sleep(ms: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms))
 }
 
+function classifyNetworkError(err: unknown): string {
+  // Node's fetch wraps the real error in error.cause
+  const cause =
+    err instanceof Error && 'cause' in err && err.cause instanceof Error
+      ? err.cause
+      : null
+
+  const hasCode = (obj: unknown): obj is { code: string } =>
+    obj != null && typeof obj === 'object' && 'code' in obj
+
+  const code =
+    (hasCode(cause) ? cause.code : null) ?? (hasCode(err) ? err.code : null)
+  const causeMsg = cause?.message ?? ''
+  const topMsg = err instanceof Error ? err.message : String(err)
+
+  if (code) {
+    switch (code) {
+      case 'ENOTFOUND':
+      case 'EAI_AGAIN':
+        return `DNS resolution failed (${code})`
+      case 'ECONNREFUSED':
+        return `Connection refused (${code})`
+      case 'ETIMEDOUT':
+      case 'ECONNRESET':
+        return `Connection timeout (${code})`
+      case 'ENETUNREACH':
+      case 'EHOSTUNREACH':
+        return `Network unreachable (${code})`
+      case 'UNABLE_TO_VERIFY_LEAF_SIGNATURE':
+        return `SSL certificate error: unable to verify certificate (${code})`
+      case 'CERT_HAS_EXPIRED':
+        return `SSL certificate error: certificate expired (${code})`
+      case 'ERR_TLS_CERT_ALTNAME_INVALID':
+        return `SSL certificate error: hostname mismatch (${code})`
+      case 'DEPTH_ZERO_SELF_SIGNED_CERT':
+      case 'SELF_SIGNED_CERT_IN_CHAIN':
+        return `SSL certificate error: self-signed certificate (${code})`
+      default:
+        if (code.startsWith('ERR_TLS') || code.startsWith('CERT'))
+          return `SSL/TLS error (${code}): ${causeMsg || topMsg}`
+        return `Network error (${code}): ${causeMsg || topMsg}`
+    }
+  }
+
+  const msg = causeMsg || topMsg
+  if (/certificate/i.test(msg) || /SSL|TLS/i.test(msg))
+    return `SSL/TLS error: ${msg}`
+  if (/abort|timeout/i.test(msg)) return `Request timeout: ${msg}`
+  if (/dns|resolve/i.test(msg)) return `DNS error: ${msg}`
+
+  return causeMsg || topMsg
+}
+
 async function checkUrlWithRetry(
   url: string,
   options: {
@@ -38,15 +91,15 @@ async function checkUrlWithRetry(
       })
       return { status: response.status }
     } catch (error: unknown) {
-      const errorMessage =
-        error instanceof Error ? error.message : String(error)
+      const errorMessage = classifyNetworkError(error)
       lastError = errorMessage
 
-      // Check if it's a retryable error (timeout or fetch failed)
+      // Check if it's a retryable error (timeout or transient network issues)
       const isRetryable =
-        errorMessage.includes('aborted') ||
         errorMessage.includes('timeout') ||
-        errorMessage.includes('fetch failed')
+        errorMessage.includes('ECONNRESET') ||
+        errorMessage.includes('ETIMEDOUT') ||
+        errorMessage.includes('EAI_AGAIN')
 
       if (isRetryable && attempt < options.maxRetries) {
         // Exponential backoff: 1s, 2s, 4s

package/src/modules/appCatalog/service.ts

@@ -9,9 +9,10 @@ import type {
 } from '../../types/common/appCatalogTypes'
 import type {
   CustomConfig,
-  PersonTeamConfig,
   ServiceConfig,
 } from '../../types/common/approvalMethodTypes'
+import type { Group, Person } from '../../types/common/personGroupTypes'
+import type { SubResource } from '../../types/common/subResourceTypes'
 import { omit } from 'radashi'
 import { parseSourceSlug } from '../../utils/parseSourceSlug'
 
@@ -96,17 +97,34 @@ export async function getApprovalMethodsFromPrisma(): Promise<
       case 'service':
         return {
           ...baseFields,
-          type: 'service',
+          type: 'service' as const,
           config: config as ServiceConfig,
         }
+      case 'custom':
+        return {
+          ...baseFields,
+          type: 'custom' as const,
+          config: config as CustomConfig,
+        }
+      case 'noAccessRequired':
+        return {
+          ...baseFields,
+          type: 'noAccessRequired' as const,
+          config: config as CustomConfig,
+        }
+      case 'unknown':
+        return {
+          ...baseFields,
+          type: 'unknown' as const,
+          config: config as CustomConfig,
+        }
       case 'personTeam':
+        // Legacy: map personTeam to custom
         return {
           ...baseFields,
-          type: 'personTeam',
-          config: config as PersonTeamConfig,
+          type: 'custom' as const,
+          config: config as CustomConfig,
         }
-      case 'custom':
-        return { ...baseFields, type: 'custom', config: config as CustomConfig }
     }
   })
 }
@@ -138,6 +156,10 @@ function rowToAppForCatalog(row: AppRowWithSourceRefs): AppForCatalog {
   const urlIssues = (row.urlIssues as unknown as string[] | null)?.length
     ? (row.urlIssues as unknown as string[])
     : undefined
+  const tiers =
+    row.tiers == null
+      ? undefined
+      : (row.tiers as unknown as AppForCatalog['tiers'])
 
   return {
     id: row.id,
@@ -157,6 +179,7 @@ function rowToAppForCatalog(row: AppRowWithSourceRefs): AppForCatalog {
     deprecated,
     aiPrompt,
     urlIssues,
+    tiers,
   }
 }
 
@@ -265,6 +288,54 @@ export function deriveCategories(apps: AppForCatalog[]): AppCategory[] {
   return categories
 }
 
+export async function getPersonsFromPrisma(): Promise<Person[]> {
+  const prisma = getDbClient()
+  const rows = await prisma.dbPerson.findMany()
+  return rows.map((row) => ({
+    slug: row.slug,
+    firstName: row.firstName,
+    lastName: row.lastName,
+    email: row.email ?? undefined,
+  }))
+}
+
+export async function getGroupsFromPrisma(): Promise<Group[]> {
+  const prisma = getDbClient()
+  const rows = await prisma.dbGroup.findMany({
+    include: { memberships: true },
+  })
+  return rows.map((row) => ({
+    slug: row.slug,
+    displayName: row.displayName ?? undefined,
+    email: row.email ?? undefined,
+    memberSlugs: row.memberships.map((m) => m.personSlug),
+  }))
+}
+
+export async function getSubResourcesFromPrisma(): Promise<SubResource[]> {
+  const prisma = getDbClient()
+  const rows = await prisma.dbSubResource.findMany()
+  return rows.map((row) => ({
+    slug: row.slug,
+    displayName: row.displayName,
+    description: row.description ?? undefined,
+    appSlug: row.appSlug,
+    familySlug: row.familySlug ?? undefined,
+    tierSlug: row.tierSlug ?? undefined,
+    aliases: row.aliases as unknown as string[],
+    ownerPersonSlug: row.ownerPersonSlug ?? undefined,
+    accessMaintainerGroupSlugs:
+      row.accessMaintainerGroupSlugs as unknown as string[],
+    accessRequest: row.accessRequest
+      ? (row.accessRequest as unknown as SubResource['accessRequest'])
+      : undefined,
+    accessComments: row.accessComments ?? undefined,
+    extra: row.extra
+      ? (row.extra as unknown as Record<string, unknown>)
+      : undefined,
+  }))
+}
+
 export async function getAppCatalogData(
   getAppsOptional?: () => Promise<AppForCatalog[]>,
 ): Promise<AppCatalogData> {
@@ -276,5 +347,8 @@ export async function getAppCatalogData(
     apps,
     tagsDefinitions: await getGroupingTagDefinitionsFromPrisma(),
     approvalMethods: await getApprovalMethodsFromPrisma(),
+    persons: await getPersonsFromPrisma(),
+    groups: await getGroupsFromPrisma(),
+    subResources: await getSubResourcesFromPrisma(),
   }
 }

package/src/modules/auth/registerAuthRoutes.ts

@@ -38,7 +38,10 @@ export function registerAuthRoutes(
         }
         res.json({ ...session, isAdmin: admin })
       } else {
-        res.status(401).json({ error: 'Not authenticated' })
+        // Return 200 with null session instead of 401 to avoid
+        // browser "Failed to load resource" console errors.
+        // The frontend checks for session.user to determine auth state.
+        res.json({ session: null, user: null, isAuthenticated: false })
       }
     } catch (error) {
       console.error('[Auth Session Error]', error)

package/src/modules/lighthouseKeeper/tools.ts

@@ -112,7 +112,7 @@ Return the updated card as a structured JSON object matching the card format:
 - appUrl: Main application URL
 - links: Array of {url, title} objects for related links
 - sources: Array of source URLs (documentation, Confluence pages, etc.)
-- accessRequest: Object with approvalMethodId, comments, requestPrompt, postApprovalInstructions, roles, approvers, urls, whoToReachOut
+- accessRequest: Object with approvalMethodSlug, comments, requestPrompt, postApprovalInstructions, roles, approverPersonSlugs, urls
 - notes: Additional notes
 - deprecated: Optional deprecation info with type, replacementSlug, comment
 

package/src/prisma-json-types.d.ts

@@ -28,6 +28,12 @@ declare global {
 
     // AppRole used within accessRequest
     type AppRole = import('./types/index').AppRole
+
+    // DbAppForCatalog.tiers - Tier variants (prod/dev)
+    type AppTierVariant = import('./types/index').AppTierVariant
+
+    // DbSubResource.extra - Arbitrary extra data
+    type SubResourceExtra = Record<string, unknown>
   }
 }
 

package/src/types/common/appCatalogTypes.ts

@@ -7,6 +7,24 @@
  */
 
 import type { AppAccessRequest, ApprovalMethod } from './approvalMethodTypes'
+import type { Group, Person } from './personGroupTypes'
+import type { SubResource } from './subResourceTypes'
+
+// ============================================================================
+// APP TIER VARIANT
+// ============================================================================
+
+/**
+ * A tier variant of an app (e.g., prod/dev environments).
+ * Each tier can have its own URL and access process.
+ */
+export interface AppTierVariant {
+  tierSlug: string
+  displayName?: string
+  description?: string
+  appUrl?: string
+  accessRequest?: AppAccessRequest
+}
 
 // ============================================================================
 // APP CATALOG TYPES
@@ -53,6 +71,8 @@ export interface AppForCatalog {
   aiPrompt?: string
   /** URL health issues detected by automated scanning */
   urlIssues?: string[]
+  /** Optional tier variants (e.g., prod/dev) with per-tier URLs and access */
+  tiers?: AppTierVariant[]
 }
 
 // Derived catalog data returned by backend
@@ -98,5 +118,8 @@ export interface AppCatalogData {
   apps: AppForCatalog[]
   tagsDefinitions: GroupingTagDefinition[]
   approvalMethods: AppApprovalMethod[]
+  persons: Person[]
+  groups: Group[]
+  subResources: SubResource[]
   versions?: AppVersionInfo
 }

package/src/types/common/approvalMethodTypes.ts

@@ -2,22 +2,19 @@
  * Approval Method Types
  *
  * Global approval method templates that apps can link to.
- * Each method has a type (service, personTeam, custom) with type-specific config.
+ * Each method has a type (service, custom, noAccessRequired, unknown) with type-specific config.
  */
 
 // ============================================================================
 // APPROVAL METHOD TYPES (Global Templates)
 // ============================================================================
 
-export type ApprovalMethodType = 'service' | 'personTeam' | 'custom'
-
-/**
- * Contact for reaching out (not necessarily the approver)
- */
-export interface ReachOutContact {
-  displayName: string
-  contact: string // email, slack handle, etc.
-}
+export type ApprovalMethodType =
+  | 'service'
+  | 'personTeam'
+  | 'custom'
+  | 'noAccessRequired'
+  | 'unknown'
 
 /**
  * Service type config - for bots, ticketing systems, self-service portals
@@ -28,10 +25,11 @@ export interface ServiceConfig {
 }
 
 /**
- * Person/Team type config - for human approvers
+ * PersonTeam type config - for person/group-based approval
  */
 export interface PersonTeamConfig {
-  reachOutContacts?: ReachOutContact[]
+  personSlugs?: string[] // Person references
+  groupSlugs?: string[] // Group references
 }
 
 /**
@@ -52,19 +50,15 @@ export type ApprovalMethodConfig =
 /**
  * Approval Method - stored in DbApprovalMethod
  */
-// export interface ApprovalMethod {
-//   slug: string
-//   type: ApprovalMethodType
-//   displayName: string
-//   config?: ApprovalMethodConfig
-//   createdAt?: Date
-//   updatedAt?: Date
-// }
-
 export type ApprovalMethod = {
   slug: string
+  /**
+   * Displayed approval method
+   */
   displayName: string
-  /** Old/migrated URLs that map to this approval method (e.g., jira.natera.com → natera.atlassian.net) */
+  /**
+   * Optionally - older name of approval method if there were migration in organization.
+   */
   deprecatedAliases?: string[]
   createdAt?: Date
   updatedAt?: Date
@@ -81,6 +75,14 @@ export type ApprovalMethod = {
       type: 'custom'
       config: CustomConfig
     }
+  | {
+      type: 'noAccessRequired'
+      config: CustomConfig
+    }
+  | {
+      type: 'unknown'
+      config: CustomConfig
+    }
 )
 
 // ============================================================================
@@ -91,19 +93,20 @@ export type ApprovalMethod = {
  * Role that can be requested for an app
  */
 export interface AppRole {
+  /**
+   * User-friendly role name.
+   */
   displayName: string
+  /**
+   * Description of role.
+   */
   description?: string
+  /**
+   * Notes for admins/approvers (Not for requestores)
+   */
   adminNotes?: string
 }
 
-/**
- * Approver contact (person who approves, may differ from reach-out contact)
- */
-export interface ApproverContact {
-  displayName: string
-  contact?: string
-}
-
 /**
  * URL link with optional label
  */
@@ -113,39 +116,38 @@ export interface ApprovalUrl {
 }
 
 /**
- * Per-app approval details - stored as JSON in DbAppForCatalog
- * All comment/text-like strings are markdown
+ * Used to store ONLY instructions related to access request
  */
 export interface AppAccessRequest {
-  approvalMethodId: string // FK to DbApprovalMethod
-
-  // Common fields (all types) - markdown text
+  /**
+   * Method of asking for access.
+   */
+  approvalMethodSlug: string // FK to DbApprovalMethod
+
+  /**
+   * Additional comments, if no other fields are fit.
+   */
   comments?: string
+  /**
+   * A template to put into a request ask.
+   */
   requestPrompt?: string
+  /**
+   * Recommended steps post approvel to get access to specific resources.
+   */
   postApprovalInstructions?: string
 
-  // Lists
+  /**
+   * Available roles for given resource.
+   */
   roles?: AppRole[]
-  approvers?: ApproverContact[]
-  urls?: ApprovalUrl[]
-
-  // Type-specific (Person/Team only)
-  whoToReachOut?: string // markdown
-}
 
-// ============================================================================
-// INPUT TYPES FOR API
-// ============================================================================
-
-export interface CreateApprovalMethodInput {
-  type: ApprovalMethodType
-  displayName: string
-  config?: ApprovalMethodConfig
-}
-
-export interface UpdateApprovalMethodInput {
-  id: string
-  type?: ApprovalMethodType
-  displayName?: string
-  config?: ApprovalMethodConfig
+  /**
+   * Individuals that will approve request within given approval method. No need to reach them directly unless specified.
+   */
+  approverPersonSlugs?: string[] // slugs referencing Person entities
+  /**
+   * Additional instructions to get approvals
+   */
+  urls?: ApprovalUrl[]
 }

package/src/types/common/personGroupTypes.ts

@@ -0,0 +1,20 @@
+/**
+ * Person & Group Types
+ *
+ * Persons represent individuals (employees, contacts).
+ * Groups represent named sets of persons (teams, distribution lists).
+ */
+
+export interface Person {
+  slug: string
+  firstName: string
+  lastName: string
+  email?: string
+}
+
+export interface Group {
+  slug: string
+  displayName?: string
+  email?: string
+  memberSlugs: string[]
+}

package/src/types/common/subResourceTypes.ts

@@ -0,0 +1,20 @@
+import type { AppAccessRequest } from './approvalMethodTypes'
+
+/**
+ * A sub-resource within an app.
+ * Example: an AWS account under the "AWS Console" app.
+ */
+export interface SubResource {
+  slug: string
+  displayName: string
+  description?: string
+  appSlug: string
+  familySlug?: string
+  tierSlug?: string
+  aliases: string[]
+  ownerPersonSlug?: string
+  accessMaintainerGroupSlugs: string[]
+  accessRequest?: AppAccessRequest
+  accessComments?: string
+  extra?: Record<string, unknown>
+}

package/src/types/index.ts

@@ -3,6 +3,8 @@ export * from './common/sharedTypes.js'
 export * from './common/resourceTypes.js'
 export * from './common/appCatalogTypes.js'
 export * from './common/approvalMethodTypes.js'
+export * from './common/personGroupTypes.js'
+export * from './common/subResourceTypes.js'
 export * from './common/env/envTypes.js'
 export * from './common/app/appTypes.js'
 export * from './common/app/ui/appUiTypes.js'