@api-client/core 0.19.9 → 0.19.10

package/src/modeling/validation/api_model_rules.ts

@@ -0,0 +1,640 @@
+import type { ApiModel } from '../ApiModel.js'
+import type { ExposedEntity } from '../ExposedEntity.js'
+import type { Action } from '../actions/Action.js'
+import { ListAction } from '../actions/ListAction.js'
+import { DeleteAction } from '../actions/DeleteAction.js'
+import { UpdateAction } from '../actions/UpdateAction.js'
+import { SearchAction } from '../actions/SearchAction.js'
+import type { RolesBasedAccessControl, UsernamePasswordConfiguration } from '../types.js'
+import type { ApiModelValidationItem, ApiModelValidationResult, ApiModelValidationContext } from '../types.js'
+import { ApiModelKind, ExposedEntityKind } from '../../models/kinds.js'
+import { SemanticType } from '../Semantics.js'
+
+/**
+ * Creates a unique validation code.
+ * @param entity The entity type (e.g., 'API', 'EXPOSURE', 'ACTION')
+ * @param issue The issue identifier (e.g., 'MISSING_NAME')
+ */
+function createCode(entity: string, issue: string): string {
+  return `${entity}_${issue}`
+}
+
+/**
+ * Validates the core properties and metadata of an ApiModel.
+ */
+export function validateApiModelInfo(model: ApiModel): ApiModelValidationItem[] {
+  const issues: ApiModelValidationItem[] = []
+  const context: ApiModelValidationContext = {
+    apiModelKey: model.key,
+    kind: ApiModelKind,
+    key: model.key,
+  }
+
+  if (model.kind !== ApiModelKind) {
+    issues.push({
+      code: createCode('API', 'INVALID_KIND'),
+      message: 'The API model type is incorrect.',
+      suggestion: 'Set the model type to "ApiModel".',
+      severity: 'error',
+      context: { ...context, property: 'kind' },
+    })
+  }
+
+  if (!model.key || typeof model.key !== 'string' || model.key.trim() === '') {
+    issues.push({
+      code: createCode('API', 'MISSING_KEY'),
+      message: 'The API model is missing a unique identifier.',
+      suggestion: 'Provide a valid name to use as a unique identifier.',
+      severity: 'error',
+      context: { ...context, property: 'key' },
+    })
+  }
+
+  if (!model.info || !model.info.name || model.info.name.trim() === '') {
+    issues.push({
+      code: createCode('API', 'MISSING_NAME'),
+      message: 'The API model has no defined name.',
+      suggestion: 'Provide a descriptive name for your API.',
+      severity: 'error',
+      context: { ...context, property: 'info.name' },
+    })
+  }
+
+  if (!model.info || !model.info.description || model.info.description.trim() === '') {
+    issues.push({
+      code: createCode('API', 'MISSING_DESCRIPTION'),
+      message: 'Adding a description helps others understand your API.',
+      suggestion: 'Add a description to clarify the purpose of this API.',
+      severity: 'warning',
+      context: { ...context, property: 'info.description' },
+    })
+  }
+
+  return issues
+}
+
+export function validateApiModelDependency(model: ApiModel): ApiModelValidationItem[] {
+  const issues: ApiModelValidationItem[] = []
+  const context: ApiModelValidationContext = {
+    apiModelKey: model.key,
+    kind: ApiModelKind,
+    key: model.key,
+  }
+
+  const domain = model.domain
+  if (!domain) {
+    issues.push({
+      code: createCode('API', 'MISSING_DOMAIN'),
+      message: 'No Data Domain is attached to the API.',
+      suggestion: 'Select a Data Domain from the settings to power your API.',
+      severity: 'error',
+      context,
+    })
+    return issues // Can't validate version if it doesn't exist
+  }
+
+  if (!domain.info || !domain.info.version) {
+    issues.push({
+      code: createCode('API', 'MISSING_DOMAIN_VERSION'),
+      message: 'The selected Data Domain is missing a version number.',
+      suggestion: 'Specify a version for the attached Data Domain.',
+      severity: 'error',
+      context,
+    })
+  }
+
+  return issues
+}
+
+export function validateApiModelSecurity(model: ApiModel): ApiModelValidationItem[] {
+  const issues: ApiModelValidationItem[] = []
+  const context: ApiModelValidationContext = {
+    apiModelKey: model.key,
+    kind: ApiModelKind,
+    key: model.key,
+  }
+
+  // Resolve User target
+  const userEntity = model.domain && model.user ? model.domain.findEntity(model.user.key, model.user.domain) : undefined
+
+  // Authentication
+  if (!model.authentication) {
+    issues.push({
+      code: createCode('API', 'MISSING_AUTHENTICATION'),
+      message: 'The API is missing authentication settings.',
+      suggestion: 'Go to the security settings and configure how users authenticate.',
+      severity: 'error',
+      context: { ...context, property: 'authentication' },
+    })
+  } else if (model.authentication.strategy === 'UsernamePassword') {
+    const auth = model.authentication as UsernamePasswordConfiguration
+    if (!auth.passwordKey) {
+      issues.push({
+        code: createCode('API', 'MISSING_PASSWORD_KEY'),
+        message: 'Username & Password authentication requires a specific field for the password.',
+        suggestion:
+          'Select which field in your user profile should store the password. ' +
+          'The data domain model should have a password data semantic on that property.',
+        severity: 'error',
+        context: { ...context, property: 'authentication.passwordKey' },
+      })
+    } else if (userEntity) {
+      const passwordProp = Array.from(userEntity.properties).find((p) => p.key === auth.passwordKey)
+      if (passwordProp && !passwordProp.hasSemantic(SemanticType.Password)) {
+        issues.push({
+          code: createCode('API', 'MISSING_PASSWORD_SEMANTIC'),
+          message: 'The selected password field is missing the Password data semantic.',
+          suggestion: 'Go to the Data Modeler and add the "Password" semantic to this property.',
+          severity: 'error',
+          context: { ...context, property: 'authentication.passwordKey' },
+        })
+      }
+    }
+
+    if (userEntity) {
+      const hasUsernameSemantic = Array.from(userEntity.properties).some(
+        (p) => typeof p.hasSemantic === 'function' && p.hasSemantic(SemanticType.Username)
+      )
+      if (!hasUsernameSemantic) {
+        issues.push({
+          code: createCode('API', 'MISSING_USERNAME_SEMANTIC'),
+          message: 'Username & Password authentication requires a field with the Username data semantic.',
+          suggestion: 'Go to the Data Modeler and add the "Username" semantic to the property used for login.',
+          severity: 'error',
+          context: { ...context, property: 'user' },
+        })
+      }
+    }
+  }
+
+  // Authorization
+  if (!model.authorization) {
+    issues.push({
+      code: createCode('API', 'MISSING_AUTHORIZATION'),
+      message: 'The API is missing authorization settings.',
+      suggestion: 'Go to the security settings and configure how to handle user permissions.',
+      severity: 'error',
+      context: { ...context, property: 'authorization' },
+    })
+  } else if (model.authorization.strategy === 'RBAC') {
+    const rbac = model.authorization as RolesBasedAccessControl
+    if (!rbac.roleKey) {
+      issues.push({
+        code: createCode('API', 'MISSING_ROLE_KEY'),
+        message: 'Role-based access control is selected but no role field has been defined.',
+        suggestion: "Select which field in your user profile determines the user's role.",
+        severity: 'error',
+        context: { ...context, property: 'authorization.roleKey' },
+      })
+    } else if (userEntity) {
+      const roleProp = Array.from(userEntity.properties).find((p) => p.key === rbac.roleKey)
+      if (roleProp && !roleProp.hasSemantic(SemanticType.UserRole)) {
+        issues.push({
+          code: createCode('API', 'MISSING_ROLE_SEMANTIC'),
+          message: 'The selected role field is missing the User Role data semantic.',
+          suggestion: 'Go to the Data Modeler and add the "User Role" semantic to this property.',
+          severity: 'error',
+          context: { ...context, property: 'authorization.roleKey' },
+        })
+      }
+    }
+  }
+
+  // Session
+  if (!model.session) {
+    issues.push({
+      code: createCode('API', 'MISSING_SESSION'),
+      message: 'The API is missing session configuration.',
+      suggestion: 'Configure how user sessions will be handled.',
+      severity: 'error',
+      context: { ...context, property: 'session' },
+    })
+  } else {
+    if (!model.session.secret) {
+      issues.push({
+        code: createCode('API', 'MISSING_SESSION_SECRET'),
+        message: 'A secure encryption key is required for sessions.',
+        suggestion: 'Provide a strong security key in the session settings.',
+        severity: 'error',
+        context: { ...context, property: 'session.secret' },
+      })
+    }
+
+    if (!model.session.properties || model.session.properties.length === 0) {
+      issues.push({
+        code: createCode('API', 'MISSING_SESSION_PROPERTIES'),
+        message: 'The session token needs to include at least one piece of user information, like an ID.',
+        suggestion: 'Select fields that should be stored securely inside the session payload.',
+        severity: 'error',
+        context: { ...context, property: 'session.properties' },
+      })
+    } else if (model.authorization && model.authorization.strategy === 'RBAC') {
+      const rbac = model.authorization as RolesBasedAccessControl
+      if (rbac.roleKey && !model.session.properties.includes(rbac.roleKey)) {
+        issues.push({
+          code: createCode('API', 'MISSING_RBAC_SESSION_PROPERTY'),
+          message: 'The user role must be included in the session data for permissions to work.',
+          suggestion: 'Make sure your selected role field is checked in the session settings.',
+          severity: 'error',
+          context: { ...context, property: 'session.properties' },
+        })
+      }
+    }
+
+    const { cookie, jwt } = model.session
+    if ((!cookie || !cookie.enabled) && (!jwt || !jwt.enabled)) {
+      issues.push({
+        code: createCode('API', 'MISSING_SESSION_TRANSPORT'),
+        message: 'No delivery method for sessions (like cookies or tokens) is enabled.',
+        suggestion: 'Enable at least one session delivery mechanism in the security settings.',
+        severity: 'error',
+        context: { ...context, property: 'session' },
+      })
+    }
+  }
+
+  // User Target
+  if (!model.user) {
+    issues.push({
+      code: createCode('API', 'MISSING_USER_ENTITY'),
+      message: 'You need to specify what kind of object represents your users.',
+      suggestion: 'Select a model from your domain that stores your user accounts.',
+      severity: 'error',
+      context: { ...context, property: 'user' },
+    })
+  } else if (model.domain && !model.domain.findEntity(model.user.key, model.user.domain)) {
+    issues.push({
+      code: createCode('API', 'INVALID_USER_ENTITY'),
+      message: 'The selected user model no longer exists in your data domain.',
+      suggestion: 'Please navigate to security settings and select a valid user model.',
+      severity: 'error',
+      context: { ...context, property: 'user' },
+    })
+  }
+
+  return issues
+}
+
+export function validateApiModelMetadata(model: ApiModel): ApiModelValidationItem[] {
+  const issues: ApiModelValidationItem[] = []
+  const context: ApiModelValidationContext = {
+    apiModelKey: model.key,
+    kind: ApiModelKind,
+    key: model.key,
+  }
+
+  const urlRegex = /^https?:\/\//i
+  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/
+
+  if (model.contact) {
+    if (model.contact.email && !emailRegex.test(model.contact.email)) {
+      issues.push({
+        code: createCode('API', 'INVALID_CONTACT_EMAIL'),
+        message: 'The contact email address looks invalid.',
+        suggestion: 'Please double check the email address formatting.',
+        severity: 'error',
+        context: { ...context, property: 'contact.email' },
+      })
+    }
+    if (model.contact.url && !urlRegex.test(model.contact.url)) {
+      issues.push({
+        code: createCode('API', 'INVALID_CONTACT_URL'),
+        message: 'The contact link looks invalid.',
+        suggestion: 'Provide a working link, starting with http:// or https://.',
+        severity: 'error',
+        context: { ...context, property: 'contact.url' },
+      })
+    }
+  } else {
+    issues.push({
+      code: createCode('API', 'MISSING_CONTACT'),
+      message: 'A contact email or link is highly recommended for API consumers.',
+      suggestion: 'Add an email or help desk link in the metadata tab.',
+      severity: 'info',
+      context: { ...context, property: 'contact' },
+    })
+  }
+
+  if (model.license) {
+    if (model.license.url && !urlRegex.test(model.license.url)) {
+      issues.push({
+        code: createCode('API', 'INVALID_LICENSE_URL'),
+        message: 'The license link looks invalid.',
+        suggestion: 'Provide a working link, starting with http:// or https://.',
+        severity: 'error',
+        context: { ...context, property: 'license.url' },
+      })
+    }
+  } else {
+    issues.push({
+      code: createCode('API', 'MISSING_LICENSE'),
+      message: 'Adding a license to your API helps users understand its usage rights.',
+      suggestion: 'Add the name and a link to your API license terms.',
+      severity: 'info',
+      context: { ...context, property: 'license' },
+    })
+  }
+
+  if (!model.termsOfService) {
+    issues.push({
+      code: createCode('API', 'MISSING_TOS'),
+      message: 'Terms of Service help legal compliance.',
+      suggestion: 'Add a link to the terms of your API service.',
+      severity: 'info',
+      context: { ...context, property: 'termsOfService' },
+    })
+  }
+
+  return issues
+}
+
+export function validateAction(action: Action, parent: ExposedEntity, apiModelKey: string): ApiModelValidationItem[] {
+  const issues: ApiModelValidationItem[] = []
+  const context: ApiModelValidationContext = {
+    apiModelKey,
+    kind: 'Action',
+    key: action.kind, // Actions lack nanoids, kind represents its type
+    parentExposedEntityKey: parent.key,
+  }
+
+  if (ListAction.isListAction(action)) {
+    if (!action.pagination || !action.pagination.kind) {
+      issues.push({
+        code: createCode('ACTION', 'LIST_MISSING_PAGINATION'),
+        message: 'A List action must have a defined pagination strategy.',
+        suggestion: 'Configure how results are loaded (e.g. by page or by a continuous cursor).',
+        severity: 'error',
+        context: { ...context, property: 'pagination' },
+      })
+    }
+    if (
+      (!action.filterableFields || action.filterableFields.length === 0) &&
+      (!action.sortableFields || action.sortableFields.length === 0)
+    ) {
+      issues.push({
+        code: createCode('ACTION', 'LIST_MISSING_FILTERS'),
+        message: 'Listing all elements without filters or sorting could be overwhelming for large tables.',
+        suggestion: 'Select a few important fields to allow sorting and searching by.',
+        severity: 'warning',
+        context,
+      })
+    }
+  }
+
+  if (SearchAction.isSearchAction(action)) {
+    if (!action.fields || action.fields.length === 0) {
+      issues.push({
+        code: createCode('ACTION', 'SEARCH_MISSING_FIELDS'),
+        message: 'A Search action needs to know which fields to look in.',
+        suggestion: 'Select the properties (like names or emails) that the search will run on.',
+        severity: 'error',
+        context: { ...context, property: 'fields' },
+      })
+    }
+  }
+
+  if (DeleteAction.isDeleteAction(action)) {
+    if (!action.strategy) {
+      issues.push({
+        code: createCode('ACTION', 'DELETE_MISSING_STRATEGY'),
+        message: 'A Delete action must know if you want to completely erase the record, or just hide it.',
+        suggestion: 'Configure the deletion type (permanent or soft).',
+        severity: 'error',
+        context: { ...context, property: 'strategy' },
+      })
+    } else if (action.strategy === 'hard') {
+      issues.push({
+        code: createCode('ACTION', 'DELETE_HARD_WARNING'),
+        message: 'Permanent delete is active. There will be no way to restore deleted data.',
+        suggestion: 'Consider switching to "soft delete" if users might need to undo mistakes.',
+        severity: 'info',
+        context: { ...context, property: 'strategy' },
+      })
+    }
+  }
+
+  if (UpdateAction.isUpdateAction(action)) {
+    if (!action.allowedMethods || action.allowedMethods.length === 0) {
+      issues.push({
+        code: createCode('ACTION', 'UPDATE_MISSING_METHODS'),
+        message:
+          'An Update action must define how the data is sent (PUT replaces everything; PATCH applies partial changes).',
+        suggestion: 'Select at least one allowed HTTP method.',
+        severity: 'error',
+        context: { ...context, property: 'allowedMethods' },
+      })
+    }
+  }
+
+  const allRateLimiters = action.getAllRateLimiters()
+  const oneHasRules = allRateLimiters.some((i) => i.rules.length)
+  if (!oneHasRules) {
+    issues.push({
+      code: createCode('ACTION', 'MISSING_RATE_LIMITS'),
+      message: 'It is best practice to configure a rate limit so your API is not overwhelmed.',
+      suggestion: 'Set a reasonable maximum request speed for this operation.',
+      severity: 'warning',
+      context,
+    })
+  }
+
+  return issues
+}
+
+export function validateExposedEntity(entity: ExposedEntity, apiModel: ApiModel): ApiModelValidationItem[] {
+  const issues: ApiModelValidationItem[] = []
+  const context: ApiModelValidationContext = {
+    apiModelKey: apiModel.key,
+    kind: ExposedEntityKind,
+    key: entity.key,
+  }
+
+  // Valid Entity Reference
+  if (!entity.entity || !entity.entity.key) {
+    issues.push({
+      code: createCode('EXPOSURE', 'MISSING_ENTITY_REF'),
+      message: 'This exposed endpoint does not point to a specific data model.',
+      suggestion: 'Select which database entity this endpoint should serve.',
+      severity: 'error',
+      context: { ...context, property: 'entity' },
+    })
+  } else if (apiModel.domain && !apiModel.domain.findEntity(entity.entity.key, entity.entity.domain)) {
+    issues.push({
+      code: createCode('EXPOSURE', 'INVALID_ENTITY_REF'),
+      message: 'This endpoint points to a data model that no longer exists.',
+      suggestion: 'Select a new valid database model or delete this endpoint.',
+      severity: 'error',
+      context: { ...context, property: 'entity' },
+    })
+  }
+
+  // Path Integrity
+  if (entity.hasCollection) {
+    if (!entity.collectionPath) {
+      issues.push({
+        code: createCode('EXPOSURE', 'MISSING_COLLECTION_PATH'),
+        message: 'When an endpoint exposes a collection, it must define what its base URL path is.',
+        suggestion: 'Add a path (e.g., "/items").',
+        severity: 'error',
+        context: { ...context, property: 'collectionPath' },
+      })
+    } else {
+      const parts = entity.collectionPath.split('/').filter(Boolean)
+      if (parts.length !== 1 || !entity.collectionPath.startsWith('/')) {
+        issues.push({
+          code: createCode('EXPOSURE', 'INVALID_COLLECTION_PATH'),
+          message: 'The collection URL should start with "/" and have no extra slashes.',
+          suggestion: `Ensure the path looks like exactly "/${parts[0] || 'subresource'}".`,
+          severity: 'error',
+          context: { ...context, property: 'collectionPath' },
+        })
+      }
+    }
+
+    if (!entity.resourcePath) {
+      issues.push({
+        code: createCode('EXPOSURE', 'MISSING_RESOURCE_PATH'),
+        message: 'You need an identifier to locate single items.',
+        suggestion: 'Specify the identification parameter format, like "{id}".',
+        severity: 'error',
+        context: { ...context, property: 'resourcePath' },
+      })
+    } else if (entity.collectionPath) {
+      const colRegex = new RegExp(`^${entity.collectionPath}/\\{[a-zA-Z0-9_]+\\}$`)
+      if (!colRegex.test(entity.resourcePath)) {
+        issues.push({
+          code: createCode('EXPOSURE', 'INVALID_RESOURCE_PATH_FORMAT'),
+          message: 'The single item route should match exactly your collection path plus one identifier variable.',
+          suggestion: `Make sure the item path is formatted exactly like "${entity.collectionPath}/{id}".`,
+          severity: 'error',
+          context: { ...context, property: 'resourcePath' },
+        })
+      }
+    }
+  } else {
+    if (!entity.resourcePath) {
+      issues.push({
+        code: createCode('EXPOSURE', 'MISSING_RESOURCE_PATH'),
+        message: 'Endpoints representing a single item must declare their URL route.',
+        suggestion: 'Set the URL path (such as "/profile").',
+        severity: 'error',
+        context: { ...context, property: 'resourcePath' },
+      })
+    } else {
+      const parts = entity.resourcePath.split('/').filter(Boolean)
+      if (parts.length !== 2 || !entity.resourcePath.startsWith('/')) {
+        issues.push({
+          code: createCode('EXPOSURE', 'INVALID_RESOURCE_PATH_FORMAT'),
+          message: 'The URL route must only contain two exact parts or levels.',
+          suggestion: 'Simplify the endpoint URL to prevent deep-nesting.',
+          severity: 'error',
+          context: { ...context, property: 'resourcePath' },
+        })
+      }
+    }
+  }
+
+  // Path Collisions
+  if (entity.isRoot) {
+    if (entity.collectionPath) {
+      const collectionCollision = apiModel.findCollectionPathCollision(entity.collectionPath, entity.key)
+      if (collectionCollision) {
+        issues.push({
+          code: createCode('EXPOSURE', 'ROOT_COLLECTION_COLLISION'),
+          message: `The route "${entity.collectionPath}" is already used by another view.`,
+          suggestion: 'Give this resource a different path to avoid conflicts.',
+          severity: 'error',
+          context: { ...context, property: 'collectionPath' },
+        })
+      }
+    }
+
+    if (entity.resourcePath) {
+      const resourceCollision = apiModel.findResourcePathCollision(entity.resourcePath, entity.key)
+      if (resourceCollision) {
+        issues.push({
+          code: createCode('EXPOSURE', 'ROOT_RESOURCE_COLLISION'),
+          message: `The route "${entity.resourcePath}" is already used by another view.`,
+          suggestion: 'Give this single-item resource a different path to avoid conflicts.',
+          severity: 'error',
+          context: { ...context, property: 'resourcePath' },
+        })
+      }
+    }
+  }
+
+  // Minimum Actions
+  if (!entity.actions || entity.actions.length === 0) {
+    issues.push({
+      code: createCode('EXPOSURE', 'MISSING_ACTIONS'),
+      message: 'This exposed view does not let users do anything.',
+      suggestion: 'Enable at least one operation like Create, Read, or Update.',
+      severity: 'error',
+      context: { ...context, property: 'actions' },
+    })
+  } else {
+    for (const action of entity.actions) {
+      issues.push(...validateAction(action, entity, apiModel.key))
+
+      // Check inheritance of access rules
+      // For a rule to exist, it might be on the action, the exposure, any parent, or the apiModel.
+      let hasAuth = false
+      if (action.accessRule && action.accessRule.length > 0) hasAuth = true
+      if (!hasAuth && entity.accessRule && entity.accessRule.length > 0) hasAuth = true
+
+      let curr = entity.parent?.key
+      while (curr && !hasAuth) {
+        const p = apiModel.exposes.get(curr)
+        if (p && p.accessRule && p.accessRule.length > 0) {
+          hasAuth = true
+          break
+        }
+        curr = p?.parent?.key
+      }
+
+      if (!hasAuth && apiModel.accessRule && apiModel.accessRule.length > 0) hasAuth = true
+
+      if (!hasAuth) {
+        issues.push({
+          code: createCode('ACTION', 'MISSING_ACCESS_RULES'),
+          message: `The ${action.kind} action has no security rules attached, making it entirely inaccessible or open.`,
+          suggestion: 'Allow specific user roles to access this operation.',
+          severity: 'error',
+          context: { ...context, kind: 'Action', key: action.kind }, // using action.kind as the key context equivalent
+        })
+      }
+    }
+  }
+
+  return issues
+}
+
+export function validateApiModel(model: ApiModel): ApiModelValidationResult {
+  const issues: ApiModelValidationItem[] = []
+
+  issues.push(...validateApiModelInfo(model))
+  issues.push(...validateApiModelDependency(model))
+  issues.push(...validateApiModelSecurity(model))
+  issues.push(...validateApiModelMetadata(model))
+
+  if (!model.exposes || model.exposes.size === 0) {
+    issues.push({
+      code: createCode('API', 'NO_EXPOSURES'),
+      message: 'Your API currently has no exposed data for external clients to request.',
+      suggestion: 'Expose a data model so apps can communicate with it.',
+      severity: 'warning',
+      context: { apiModelKey: model.key, kind: ApiModelKind, key: model.key, property: 'exposes' },
+    })
+  } else {
+    for (const exposure of model.exposes.values()) {
+      issues.push(...validateExposedEntity(exposure, model))
+    }
+  }
+
+  const hasErrors = issues.some((i) => i.severity === 'error')
+
+  return {
+    isValid: !hasErrors,
+    issues,
+  }
+}