@nuxt-customer-portal/core 0.3.0

package/server/utils/openapi-auth.ts

@@ -0,0 +1,67 @@
+import type { OpenApiDocument } from './openapi-order'
+
+type OpenApiObject = Record<string, unknown>
+
+const AUTH_TAG = 'Authentication'
+const AUTH_PATH_PREFIX = '/api/auth'
+
+const mergeObjects = (left: unknown, right: unknown): OpenApiObject => ({
+  ...(left as OpenApiObject | undefined),
+  ...(right as OpenApiObject | undefined)
+})
+
+const prefixAuthPath = (path: string): string => `${AUTH_PATH_PREFIX}${path.startsWith('/') ? path : `/${path}`}`
+
+const tagAuthenticationOperations = (pathItem: OpenApiObject): OpenApiObject =>
+  Object.fromEntries(
+    Object.entries(pathItem).map(([method, value]) => {
+      if (!value || typeof value !== 'object' || method === 'parameters') {
+        return [method, value]
+      }
+      return [
+        method,
+        {
+          ...(value as OpenApiObject),
+          tags: [AUTH_TAG]
+        }
+      ]
+    })
+  )
+
+export const mergeBetterAuthOpenApi = (document: OpenApiDocument, authDocument: OpenApiDocument): OpenApiDocument => {
+  const components = mergeObjects(document.components, authDocument.components)
+  components.schemas = mergeObjects(
+    (document.components as OpenApiObject | undefined)?.schemas,
+    (authDocument.components as OpenApiObject | undefined)?.schemas
+  )
+  components.securitySchemes = mergeObjects(
+    (document.components as OpenApiObject | undefined)?.securitySchemes,
+    (authDocument.components as OpenApiObject | undefined)?.securitySchemes
+  )
+
+  const authPaths = Object.fromEntries(
+    Object.entries(authDocument.paths ?? {}).map(([path, pathItem]) => [
+      prefixAuthPath(path),
+      tagAuthenticationOperations(pathItem)
+    ])
+  )
+
+  const tags = Array.isArray(document.tags) ? document.tags : []
+
+  return {
+    ...document,
+    components,
+    tags: [
+      {
+        name: AUTH_TAG,
+        description:
+          'Authentication, session, account, administration, email verification, and organization membership endpoints provided by Better Auth.'
+      },
+      ...tags.filter((tag) => (tag as OpenApiObject)?.name !== AUTH_TAG)
+    ],
+    paths: {
+      ...document.paths,
+      ...authPaths
+    } as OpenApiDocument['paths']
+  }
+}

package/server/utils/openapi-contracts.ts

@@ -0,0 +1,129 @@
+import { z } from 'zod'
+import type { OpenApiDocument } from './openapi-order'
+
+type JsonSchema = Record<string, unknown>
+type OpenApiOperation = Record<string, unknown>
+
+export interface PortalOpenApiContracts {
+  owner: string
+  query?: Record<string, z.ZodType>
+  body?: Record<string, z.ZodType>
+  requestBody?: Record<string, Record<string, unknown>>
+}
+
+const contractRegistryKey = Symbol.for('nuxt-customer-portal.openapi-contracts')
+const contractRegistry = globalThis as typeof globalThis & {
+  [contractRegistryKey]?: PortalOpenApiContracts[]
+}
+
+export const registerPortalOpenApiContracts = (contracts: PortalOpenApiContracts): void => {
+  const registry = (contractRegistry[contractRegistryKey] ??= [])
+  const index = registry.findIndex((item) => item.owner === contracts.owner)
+  if (index === -1) {
+    registry.push(contracts)
+  } else {
+    registry[index] = contracts
+  }
+}
+
+const id = z.string().min(1).max(128)
+const userQuerySchema = z.object({ search: z.string().trim().max(200).optional() })
+const genericUserQuerySchema = z.object({
+  take: z.coerce.number().int().min(1).optional(),
+  skip: z.coerce.number().int().min(0).optional(),
+  sortField: z.string().optional(),
+  sortDirection: z.enum(['asc', 'desc']).optional(),
+  filters: z.string().describe('JSON-encoded array of field, operator, and value filter objects.').optional()
+})
+
+const querySchemas: Record<string, z.ZodType> = {
+  generalAdminUsersGet: userQuerySchema,
+  generalAdminUsersQueryGet: genericUserQuerySchema,
+  generalOrganizationsGetInvitationGet: z.object({ id })
+}
+
+const bodySchemas: Record<string, z.ZodType> = {
+  generalAdminOrganizationsPost: z.object({
+    name: z.string().min(1),
+    slug: z.string().regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/)
+  }),
+  generalAdminOrganizationsByIdPatch: z.object({
+    name: z.string().min(1),
+    slug: z.string().regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/),
+    officialCompanyName: z.string().min(1).max(200),
+    logo: z.string().max(2_800_000)
+  }),
+  generalAdminOrganizationsByIdInvitationsPost: z.object({
+    email: z.string().email(),
+    role: z.enum(['member', 'admin', 'owner'])
+  }),
+  generalAdminUsersByIdRolePatch: z.object({ role: z.enum(['user', 'admin']) }),
+  generalOrganizationsAcceptInvitationPost: z.object({ invitationId: id }),
+  generalProfilePatch: z.object({
+    name: z.string().min(1).max(255).optional(),
+    image: z.string().url().nullable().optional()
+  })
+}
+
+const parameterDescriptions: Record<string, string> = {
+  search: 'Free-text search term.',
+  page: 'One-based page number.',
+  pageSize: 'Number of records per page.',
+  sortBy: 'Field used to sort the results.',
+  sortDir: 'Sort direction.',
+  refresh: 'Set to 1 to refresh external provider status.',
+  locale: 'Locale used to render localized invoice content.',
+  week: 'Any date in the requested ISO week (YYYY-MM-DD).',
+  section: 'Administration section whose supporting data should be loaded.',
+  id: 'Invitation identifier.'
+}
+
+const jsonSchema = (schema: z.ZodType): JsonSchema => {
+  const result = z.toJSONSchema(schema, { io: 'input', unrepresentable: 'any' }) as JsonSchema
+  delete result.$schema
+  return result
+}
+
+const queryParameters = (schema: z.ZodType): Array<Record<string, unknown>> => {
+  const converted = jsonSchema(schema)
+  const properties = (converted.properties ?? {}) as Record<string, JsonSchema>
+  const required = new Set((converted.required ?? []) as string[])
+  return Object.entries(properties).map(([name, property]) => ({
+    name,
+    in: 'query',
+    required: required.has(name),
+    description: property.description ?? parameterDescriptions[name],
+    schema: property
+  }))
+}
+
+const addContract = (operation: OpenApiOperation): void => {
+  const operationId = String(operation.operationId ?? '')
+  const registered = contractRegistry[contractRegistryKey] ?? []
+  const querySchema =
+    querySchemas[operationId] ?? registered.find((item) => item.query?.[operationId])?.query?.[operationId]
+  if (querySchema) {
+    operation.parameters = [...((operation.parameters ?? []) as unknown[]), ...queryParameters(querySchema)]
+  }
+  const bodySchema =
+    bodySchemas[operationId] ?? registered.find((item) => item.body?.[operationId])?.body?.[operationId]
+  if (bodySchema) {
+    operation.requestBody = {
+      required: true,
+      content: { 'application/json': { schema: jsonSchema(bodySchema) } }
+    }
+  }
+  const requestBody = registered.find((item) => item.requestBody?.[operationId])?.requestBody?.[operationId]
+  if (requestBody) {
+    operation.requestBody = requestBody
+  }
+}
+
+export const enrichOpenApiContracts = <T extends OpenApiDocument>(document: T): T => {
+  for (const pathItem of Object.values(document.paths ?? {})) {
+    for (const operation of Object.values(pathItem)) {
+      addContract(operation)
+    }
+  }
+  return document
+}

package/server/utils/openapi-order.ts

@@ -0,0 +1,136 @@
+type OpenApiOperation = Record<string, unknown>
+type OpenApiPathItem = Record<string, OpenApiOperation>
+
+export interface OpenApiDocument {
+  paths?: Record<string, OpenApiPathItem>
+  [key: string]: unknown
+}
+
+const METHOD_ORDER = ['get', 'post', 'put', 'patch', 'delete', 'options', 'head', 'trace']
+
+const timesheetsSectionRank = (path: string): number => {
+  if (path === '/api/timesheets/bootstrap') {
+    return 0
+  }
+  if (path.includes('/api/timesheets/timer')) {
+    return 10
+  }
+  if (path.includes('/api/timesheets/entries')) {
+    return 20
+  }
+  if (path.includes('/api/timesheets/weeks')) {
+    return 30
+  }
+  if (path.includes('/api/timesheets/admin/bootstrap')) {
+    return 40
+  }
+  if (path.includes('/api/timesheets/admin/approvals')) {
+    return 100
+  }
+  if (path.includes('/api/timesheets/admin/clients') || path.includes('/api/timesheets/admin/organizations')) {
+    return 200
+  }
+  if (path.includes('/api/timesheets/admin/projects')) {
+    return 300
+  }
+  if (path.includes('/api/timesheets/admin/activities')) {
+    return 400
+  }
+  if (path.includes('/api/timesheets/admin/tariffs')) {
+    return 600
+  }
+  if (path.includes('/api/timesheets/admin/settings') || path.includes('/api/timesheets/admin/email-domain')) {
+    return 700
+  }
+  if (path.includes('/api/timesheets/admin/report')) {
+    return 800
+  }
+  return 900
+}
+
+const invoiceActionRank = (path: string): number => {
+  if (path.endsWith('/attachments')) {
+    return 10
+  }
+  if (path.includes('/attachments/')) {
+    return 20
+  }
+  if (path.endsWith('/pdf')) {
+    return 30
+  }
+  if (path.endsWith('/issue')) {
+    return 40
+  }
+  if (path.endsWith('/email-preview')) {
+    return 50
+  }
+  if (path.endsWith('/email')) {
+    return 60
+  }
+  if (path.endsWith('/email-status')) {
+    return 70
+  }
+  if (path.endsWith('/reminder-preview')) {
+    return 80
+  }
+  if (path.endsWith('/reminder')) {
+    return 90
+  }
+  if (path.endsWith('/payments')) {
+    return 100
+  }
+  return 0
+}
+
+const pathRank = (path: string): number => {
+  if (path.startsWith('/api/auth')) {
+    return 500
+  }
+  if (path.startsWith('/api/timesheets')) {
+    return 2000 + timesheetsSectionRank(path) * 100
+  }
+  if (path.startsWith('/api/invoices')) {
+    return 3000 + invoiceActionRank(path)
+  }
+  if (path.startsWith('/api/invoice-timesheets')) {
+    return 3100
+  }
+  if (path.startsWith('/api/service-requests/admin')) {
+    return 1100
+  }
+  if (path.startsWith('/api/service-requests')) {
+    return 1000
+  }
+  if (path.startsWith('/api/')) {
+    return 0
+  }
+  return 3000
+}
+
+const pathDepth = (path: string): number => path.split('/').filter(Boolean).length
+
+const comparePaths = ([left]: [string, OpenApiPathItem], [right]: [string, OpenApiPathItem]): number =>
+  pathRank(left) - pathRank(right) || pathDepth(left) - pathDepth(right) || left.localeCompare(right)
+
+const orderMethods = (pathItem: OpenApiPathItem): OpenApiPathItem =>
+  Object.fromEntries(
+    Object.entries(pathItem).sort(([left], [right]) => {
+      const leftRank = METHOD_ORDER.indexOf(left)
+      const rightRank = METHOD_ORDER.indexOf(right)
+      return (leftRank === -1 ? METHOD_ORDER.length : leftRank) - (rightRank === -1 ? METHOD_ORDER.length : rightRank)
+    })
+  )
+
+export const orderOpenApiDocument = <T extends OpenApiDocument>(document: T): T => {
+  if (!document.paths) {
+    return document
+  }
+  return {
+    ...document,
+    paths: Object.fromEntries(
+      Object.entries(document.paths)
+        .sort(comparePaths)
+        .map(([path, item]) => [path, orderMethods(item)])
+    )
+  }
+}

package/server/utils/permissions.ts

@@ -0,0 +1,179 @@
+import { db } from './db'
+import { member as memberTable, organization as organizationTable } from '../db/schema/auth-schema'
+import { eq, and } from 'drizzle-orm'
+import { user as userRole } from '../../shared/permissions'
+import type { MemberRole, Organization } from '@nuxt-customer-portal/core/shared/types/index'
+
+// Type for role statements structure
+type RoleStatements = Record<string, readonly string[]>
+
+// Helper to extract statements from a role object
+const getRoleStatements = (role: unknown): RoleStatements => {
+  // Roles created with ac.newRole() may have a statements property or be the statements object itself
+  if (role && typeof role === 'object' && 'statements' in role) {
+    return (role as { statements: RoleStatements }).statements
+  }
+  return role as RoleStatements
+}
+
+/**
+ * Get organization role permissions mapping
+ * Organization owners get full permissions including organization management
+ * Organization admins get most permissions except organization deletion
+ * Members get basic service-request permissions (same as user role)
+ */
+export const getOrganizationRolePermissions = (orgRole: MemberRole | null | undefined): RoleStatements => {
+  if (!orgRole) {
+    // No organization role, return user role permissions
+    return getRoleStatements(userRole)
+  }
+
+  // Get base user role permissions
+  const userStatements = getRoleStatements(userRole)
+  const permissions: RoleStatements = { ...userStatements }
+
+  if (orgRole === 'owner') {
+    // Owners get full organization management permissions
+    permissions['organization'] = ['read', 'update', 'delete']
+    permissions['member'] = ['read', 'list', 'create', 'update', 'delete', 'update-name']
+    permissions['invitation'] = ['list', 'create', 'cancel', 'resend']
+  } else if (orgRole === 'admin') {
+    // Admins can manage members and invitations but not delete organization
+    permissions['organization'] = ['read', 'update'] // No 'delete' for admins
+    permissions['member'] = ['read', 'list', 'create', 'update', 'delete', 'update-name']
+    permissions['invitation'] = ['list', 'create', 'cancel', 'resend']
+  } else if (orgRole === 'member') {
+    // Members can see the organization they belong to, but the member and
+    // invitation directories are administrative data.
+    permissions['organization'] = ['read']
+  }
+
+  return permissions
+}
+
+/**
+ * Get the effective permissions for a user based on their system role and organization role
+ */
+export const getUserPermissions = async (
+  userId: string,
+  _systemRole: string | null | undefined,
+  organizationId: string | null | undefined
+): Promise<{ permissions: RoleStatements; orgRole: MemberRole | null; organization: Organization | null }> => {
+  let roleDefinition: unknown = userRole
+  let orgRole: MemberRole | null = null
+  let organization: Organization | null = null
+
+  if (organizationId) {
+    try {
+      // Get the user's role in the organization
+      const [member] = await db
+        .select({ role: memberTable.role })
+        .from(memberTable)
+        .where(and(eq(memberTable.userId, userId), eq(memberTable.organizationId, organizationId)))
+        .limit(1)
+
+      if (member) {
+        orgRole = member.role as MemberRole
+        roleDefinition = getOrganizationRolePermissions(orgRole)
+      }
+
+      // Get organization details
+      const [org] = await db.select().from(organizationTable).where(eq(organizationTable.id, organizationId)).limit(1)
+
+      if (org) {
+        organization = org as Organization
+      }
+    } catch (error) {
+      console.error('Error fetching organization role or details:', error)
+      // Fall back to default role if there's an error
+    }
+  }
+
+  const roleStatements = getRoleStatements(roleDefinition)
+  return {
+    permissions: roleStatements,
+    orgRole,
+    organization
+  }
+}
+
+/**
+ * Check if a user has a specific permission
+ * @param userId The user ID to check
+ * @param systemRole The user's system role (from user.role)
+ * @param organizationId The organization ID to check permissions for (optional)
+ * @param subject The permission subject (e.g., 'organization', 'member', 'invitation')
+ * @param action The permission action (e.g., 'read', 'update', 'delete')
+ * @returns true if the user has the permission, false otherwise
+ */
+export const hasPermission = async (
+  userId: string,
+  systemRole: string | null | undefined,
+  organizationId: string | null | undefined,
+  subject: string,
+  action: string
+): Promise<boolean> => {
+  const { permissions } = await getUserPermissions(userId, systemRole, organizationId)
+  const subjectPermissions = permissions[subject] || []
+  return Array.isArray(subjectPermissions) && subjectPermissions.includes(action)
+}
+
+/**
+ * Check if a user has permission for an organization operation
+ * This is a convenience function that extracts user info from session and checks permission
+ * @param session The Better Auth session object
+ * @param organizationId The organization ID to check permissions for
+ * @param subject The permission subject
+ * @param action The permission action
+ * @returns true if the user has the permission, false otherwise
+ */
+export const checkOrganizationPermission = async (
+  session: { user: { id: string; role?: string } },
+  organizationId: string,
+  subject: string,
+  action: string
+): Promise<boolean> => {
+  if (!session?.user) {
+    return false
+  }
+
+  return await hasPermission(session.user.id, session.user.role, organizationId, subject, action)
+}
+
+/**
+ * Get user's organization role for a specific organization
+ * @param userId The user ID
+ * @param organizationId The organization ID
+ * @returns The organization role or null if not a member
+ */
+export const getUserOrganizationRole = async (userId: string, organizationId: string): Promise<MemberRole | null> => {
+  try {
+    const [member] = await db
+      .select({ role: memberTable.role })
+      .from(memberTable)
+      .where(and(eq(memberTable.userId, userId), eq(memberTable.organizationId, organizationId)))
+      .limit(1)
+
+    return member ? (member.role as MemberRole) : null
+  } catch (error) {
+    console.error('Error fetching organization role:', error)
+    return null
+  }
+}
+
+/**
+ * Check if a user is a member of an organization
+ * System admins are considered to have access to all organizations
+ * @param userId The user ID
+ * @param organizationId The organization ID
+ * @param systemRole The user's system role (optional, for admin check)
+ * @returns true if the user is a member or is a system admin
+ */
+export const isOrganizationMember = async (
+  userId: string,
+  organizationId: string,
+  _systemRole?: string | null
+): Promise<boolean> => {
+  const role = await getUserOrganizationRole(userId, organizationId)
+  return role !== null
+}