@api-client/core 0.19.30 → 0.19.32

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@api-client/core",
   "description": "The API Client's core client library. Works in NodeJS and in a ES enabled browser.",
-  "version": "0.19.30",
+  "version": "0.19.32",
   "license": "UNLICENSED",
   "exports": {
     "./browser.js": {

package/src/modeling/ApiModel.ts

@@ -6,9 +6,7 @@ import type {
   AuthenticationStrategy,
   AuthorizationStrategy,
   ExposedEntitySchema,
-  RolesBasedAccessControl,
   SessionConfiguration,
-  UsernamePasswordConfiguration,
   ExposeOptions,
   OffsetPaginationStrategy,
   CursorPaginationStrategy,
@@ -668,14 +666,6 @@ export class ApiModel extends DependentModel {
     if (this.session) {
       this.session.properties = []
     }
-    if (this.authentication && this.authentication.strategy === 'UsernamePassword') {
-      const typed = this.authentication as UsernamePasswordConfiguration
-      typed.passwordKey = undefined
-    }
-    if (this.authorization && this.authorization.strategy == 'RBAC') {
-      const typed = this.authorization as RolesBasedAccessControl
-      typed.roleKey = ''
-    }
   }
 
   /**

package/src/modeling/DomainAssociation.ts

@@ -8,7 +8,7 @@ import type { DomainEntity } from './DomainEntity.js'
 import type { Shapes } from '@api-client/amf-core'
 import type { AssociationBinding, AssociationBindings, AssociationWebBindings } from './Bindings.js'
 import { DomainAttributeAttribute, DomainAttributeAttributes } from './DataFormat.js'
-import type { AssociationTarget, DomainGraphEdge } from './types.js'
+import type { AssociationSchema, AssociationTarget, DomainGraphEdge } from './types.js'
 import { ShapeGenerator } from './amf/ShapeGenerator.js'
 import { DataSemantics, isAssociationSemantic, type SemanticType, type AppliedDataSemantic } from './Semantics.js'
 
@@ -53,7 +53,7 @@ export interface DomainAssociationSchema extends DomainElementSchema {
    * referenced entities schemas. Note, changes in the referenced entities may not be propagated
    * to schemas altered by the user.
    */
-  schema?: Shapes.IApiAssociationShape
+  schema?: AssociationSchema
   /**
    * The list of bindings for this property.
    *
@@ -153,7 +153,7 @@ export class DomainAssociation extends DomainElement {
    * The schema allowing to translate the model into a
    * specific format (like JSON, RAML, XML, etc.)
    */
-  @observed({ deep: true }) accessor schema: Shapes.IApiAssociationShape | undefined
+  @observed({ deep: true }) accessor schema: AssociationSchema | undefined
 
   /**
    * The list of bindings for this property.
@@ -351,7 +351,7 @@ export class DomainAssociation extends DomainElement {
    * const schema = association.ensureSchema();
    * ```
    */
-  ensureSchema(): Shapes.IApiAssociationShape {
+  ensureSchema(): AssociationSchema {
     if (!this.schema) {
       this.schema = {}
     }

package/src/modeling/RuntimeApiModel.ts

@@ -4,6 +4,9 @@ import type { DataDomainSchema } from './DataDomain.js'
 import type { ActionKind } from './actions/index.js'
 import type { ExposedEntity } from './ExposedEntity.js'
 import type { Action } from './actions/Action.js'
+import { SemanticType } from './Semantics.js'
+import type { DomainEntity } from './DomainEntity.js'
+import type { DomainProperty } from './DomainProperty.js'
 
 /**
  * Identifies a specific exposed entity and its action kind.
@@ -55,12 +58,55 @@ export class RuntimeApiModel extends ApiModel {
    */
   #definitions = new WeakMap<RouteToken[], RouteDefinition>()
 
+  /**
+   * Cached references to commonly used entities for fast runtime lookup.
+   */
+  cachedEntities: {
+    user?: DomainEntity
+  } = {}
+
+  /**
+   * Cached references to commonly used properties for fast runtime lookup.
+   */
+  cachedProperties: {
+    username?: DomainProperty
+    password?: DomainProperty
+    role?: DomainProperty
+  } = {}
+
   constructor(schema: RuntimeApiModelSchema, domainSchema: DataDomainSchema) {
     super(schema, domainSchema)
 
     if (schema.routingMap) {
       this.#initializeRouter(schema.routingMap)
     }
+
+    this.#cacheEntitiesAndProperties()
+  }
+
+  #cacheEntitiesAndProperties() {
+    if (!this.user || !this.domain) {
+      return
+    }
+
+    const userEntity = this.domain.findEntity(this.user.key, this.user.domain)
+    if (!userEntity) {
+      return
+    }
+
+    this.cachedEntities.user = userEntity
+
+    for (const prop of userEntity.properties) {
+      if (prop.hasSemantic(SemanticType.Username)) {
+        this.cachedProperties.username = prop
+      }
+      if (prop.hasSemantic(SemanticType.Password)) {
+        this.cachedProperties.password = prop
+      }
+      if (prop.hasSemantic(SemanticType.UserRole)) {
+        this.cachedProperties.role = prop
+      }
+    }
   }
 
   #initializeRouter(routingMap: RoutingMap) {

package/src/modeling/ai/domain_response_schema.ts

@@ -94,7 +94,7 @@ const PropertySchema = {
 const AssociationSchemaShape = {
   type: Type.OBJECT,
   properties: {
-    linked: { type: Type.BOOLEAN },
+    embedded: { type: Type.BOOLEAN, description: 'Whether the association should be embedded in the target entity' },
     unionType: { type: Type.STRING, description: 'Enum: allOf, anyOf, oneOf, not' },
   },
 }

package/src/modeling/ai/types.ts

@@ -1,10 +1,9 @@
-import type { Shapes } from '@api-client/amf-core'
 import type { Exception } from '../../exceptions/exception.js'
 import type { AiSessionSchema } from '../../models/AiSession.js'
 import type { DomainPropertyType } from '../DataFormat.js'
 import type { OnDeleteRule } from '../index.js'
 import { SemanticType } from '../Semantics.js'
-import type { AssociationTarget, PropertySchema } from '../types.js'
+import type { AssociationSchema, AssociationTarget, PropertySchema } from '../types.js'
 import type { AiModelMessageSchema, AiModelMessage, AiUserMessageSchema } from '../../models/AiMessage.js'
 
 /**
@@ -150,7 +149,7 @@ export interface AiDomainAssociation {
   multiple?: boolean
   onDelete?: OnDeleteRule
   semantics?: AiDomainSemantic[]
-  schema?: Shapes.IApiAssociationShape
+  schema?: AssociationSchema
 }
 
 /**

package/src/modeling/amf/ShapeGenerator.ts

@@ -199,7 +199,7 @@ export class ShapeGenerator {
    */
   associationShape(input: DomainAssociation, visited: Set<string> = new Set<string>()): Shapes.IShapeUnion | undefined {
     const schema = input.schema
-    if (schema && schema.linked) {
+    if (!schema?.embedded) {
       return this.createLinkedShape(input)
     }
     const items = this.associationUnion(input, visited)

package/src/modeling/generators/oas_312/OasGenerator.ts

@@ -439,7 +439,7 @@ export class OasGenerator {
       }
       const links: Record<string, LinkObject> = {}
       for (const assoc of domainEntity.associations) {
-        if (assoc.schema?.linked === false) {
+        if (assoc.schema?.embedded === true) {
           continue
         }
         const targets = Array.from(assoc.listTargets())

package/src/modeling/generators/oas_312/OasSchemaGenerator.ts

@@ -105,12 +105,12 @@ export class OasSchemaGenerator {
       const targets = Array.from(assoc.listTargets())
       if (targets.length === 0) continue
 
-      const linked = assoc.schema?.linked === true
+      const linked = !assoc.schema?.embedded
       const targetRefs: (SchemaObject | ReferenceObject)[] = []
 
       for (const targetEntity of targets) {
         if (linked) {
-          // When an entity is linked then we treat it as a regular property, which value is a key to
+          // When an entity is not embedded then we treat it as a regular property, which value is a key to
           // the target entity. The consuming application has to construct the endpoint manually.
           const targetName = targetEntity.info.displayName || targetEntity.info.name || targetEntity.key
           targetRefs.push({
@@ -118,7 +118,7 @@ export class OasSchemaGenerator {
             description: `The ID of the linked ${targetName}.`,
           })
         } else {
-          // If not linked, embed the resource as a reference to the schema.
+          // If "embedded", add the resource as a reference to the schema.
           if (targetEntity !== entity) {
             this.generateEntity(targetEntity)
           }

package/src/modeling/generators/oas_320/OasSchemaGenerator.ts

@@ -78,12 +78,12 @@ export class OasSchemaGenerator {
       const targets = Array.from(assoc.listTargets())
       if (targets.length === 0) continue
 
-      const linked = assoc.schema?.linked === true
+      const linked = !assoc.schema?.embedded
       const targetRefs: (SchemaObject | ReferenceObject)[] = []
 
       for (const targetEntity of targets) {
         if (linked) {
-          // When an entity is linked then we treat it as a regular property, which value is a key to
+          // When an entity is not embedded then we treat it as a regular property, which value is a key to
           // the target entity. The consuming application has to construct the endpoint manually.
           const targetName = targetEntity.info.displayName || targetEntity.info.name || targetEntity.key
           targetRefs.push({
@@ -91,7 +91,7 @@ export class OasSchemaGenerator {
             description: `The ID of the linked ${targetName}.`,
           })
         } else {
-          // If not linked, embed the resource as a reference to the schema.
+          // If "embedded", add the resource as a reference to the schema.
           if (targetEntity !== entity) {
             this.generateEntity(targetEntity)
           }

package/src/modeling/readme.md

@@ -187,8 +187,8 @@ apiModel.attachDataDomain(domain)
 
 // 4. Configure security
 apiModel.user = { key: userEntity.key }
-apiModel.authentication = { strategy: 'UsernamePassword', passwordKey: 'password' }
-apiModel.authorization = { strategy: 'RBAC', roleKey: 'role' }
+apiModel.authentication = { strategy: 'UsernamePassword' }
+apiModel.authorization = { strategy: 'RBAC' }
 apiModel.session = { 
   secret: 'your-secure-secret',
   properties: ['email', 'role'],

package/src/modeling/types.ts

@@ -393,14 +393,6 @@ export interface AuthorizationConfiguration {
 
 export interface RolesBasedAccessControl extends AuthorizationConfiguration {
   strategy: 'RBAC'
-  /**
-   * The property within the designated "User" entity that defines the user's role.
-   * This field is used in access rules to grant permissions.
-   *
-   * This property must be marked with the "Role" data semantic in the Data Modeler.
-   * It is required to publish the API.
-   */
-  roleKey: string
 }
 
 export type AuthorizationStrategy = RolesBasedAccessControl
@@ -424,13 +416,6 @@ export interface AuthenticationConfiguration {
  */
 export interface UsernamePasswordConfiguration extends AuthenticationConfiguration {
   strategy: 'UsernamePassword'
-  /**
-   * The specific property within the User entity that holds the password.
-   * This property must be marked with the "Password" data semantic in the Data Modeler.
-   *
-   * This property is required to publish the API.
-   */
-  passwordKey?: string
 }
 
 export type AuthenticationStrategy = UsernamePasswordConfiguration
@@ -897,3 +882,59 @@ export interface ApiModelValidationResult {
    */
   issues: ApiModelValidationItem[]
 }
+
+/**
+ * Schema definition for an association.
+ *
+ * This is used to define how an association is represented in the schema.
+ */
+export interface AssociationSchema {
+  /**
+   * Whether the target entity should be embedded under the property name.
+   * When false, this association is just an information that one entity depend on another.
+   * When true, it changes the definition of the schema having this association to
+   * add the target schema properties inline with this property.
+   *
+   * **When true**
+   *
+   * ```javascript
+   * // generated schema for `address` association
+   * {
+   *  "name": "example value",
+   *  "address": {
+   *    "city": "example value",
+   *    ...
+   *  }
+   * }
+   * ```
+   *
+   * **When false**
+   *
+   * ```javascript
+   * // generated schema for `address` association
+   * {
+   *  "name": "example value",
+   *  "address": "the key of the referenced schema"
+   * }
+   * ```
+   */
+  embedded?: boolean
+  /**
+   * When the association has multiple targets the union type should be
+   * set to describe which union this is.
+   *
+   * Possible values are:
+   *
+   * - allOf - To validate against `allOf`, the given data must be valid against
+   *   all of the given sub-schemas. When generating, it's a sum of all properties.
+   * - anyOf - To validate against `anyOf`, the given data must be valid against
+   *   any (one or more) of the given sub-schemas. When generation a schema, it takes first union schema.
+   * - oneOf - To validate against `oneOf`, the given data must be valid against
+   *   exactly one of the given sub-schemas. It behaves the same as `anyOf` when generating a schema
+   * - not - The `not` keyword declares that an instance validates if it doesn’t
+   *   validate against the given sub-schema. It has no use when generating a schema.
+   *
+   * @default anyOf
+   */
+  unionType?: 'allOf' | 'anyOf' | 'oneOf' | 'not'
+}

package/src/modeling/validation/api_model_rules.ts

@@ -5,10 +5,10 @@ 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, ApiModelValidationContext } from '../types.js'
 import { ApiModelKind, ExposedEntityKind } from '../../models/kinds.js'
 import { SemanticType } from '../Semantics.js'
+import { DomainProperty } from '../DomainProperty.js'
 
 /**
  * Creates a unique validation code.
@@ -127,35 +127,32 @@ export function validateApiModelSecurity(model: ApiModel): ApiModelValidationIte
       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)) {
+    if (userEntity) {
+      let passwordProp: DomainProperty | undefined
+      for (const prop of userEntity.properties) {
+        if (prop.hasSemantic(SemanticType.Password)) {
+          passwordProp = prop
+          break
+        }
+      }
+      if (!passwordProp) {
         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.',
+          message: 'The selected user model requires a property with the Password data semantic for authentication.',
+          suggestion: 'Go to the Data Modeler and add the "Password" semantic to the password property.',
           severity: 'error',
-          context: { ...context, property: 'authentication.passwordKey' },
+          context: { ...context, property: 'user' },
         })
       }
-    }
 
-    if (userEntity) {
-      const hasUsernameSemantic = Array.from(userEntity.properties).some(
-        (p) => typeof p.hasSemantic === 'function' && p.hasSemantic(SemanticType.Username)
-      )
-      if (!hasUsernameSemantic) {
+      let usernameProp: DomainProperty | undefined
+      for (const prop of userEntity.properties) {
+        if (prop.hasSemantic(SemanticType.Username)) {
+          usernameProp = prop
+          break
+        }
+      }
+      if (!usernameProp) {
         issues.push({
           code: createCode('API', 'MISSING_USERNAME_SEMANTIC'),
           message: 'Username & Password authentication requires a field with the Username data semantic.',
@@ -177,24 +174,21 @@ export function validateApiModelSecurity(model: ApiModel): ApiModelValidationIte
       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)) {
+    if (userEntity) {
+      let roleProp: DomainProperty | undefined
+      for (const prop of userEntity.properties) {
+        if (prop.hasSemantic(SemanticType.UserRole)) {
+          roleProp = prop
+          break
+        }
+      }
+      if (!roleProp) {
         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.',
+          message: 'Role-based access control requires a property with the User Role data semantic on the user model.',
+          suggestion: 'Go to the Data Modeler and add the "User Role" semantic to the property used for roles.',
           severity: 'error',
-          context: { ...context, property: 'authorization.roleKey' },
+          context: { ...context, property: 'user' },
         })
       }
     }
@@ -229,15 +223,23 @@ export function validateApiModelSecurity(model: ApiModel): ApiModelValidationIte
         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' },
-        })
+      if (userEntity) {
+        let roleProp: DomainProperty | undefined
+        for (const prop of userEntity.properties) {
+          if (prop.hasSemantic(SemanticType.UserRole)) {
+            roleProp = prop
+            break
+          }
+        }
+        if (roleProp && !model.session.properties.includes(roleProp.key)) {
+          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 property is checked in the session settings.',
+            severity: 'error',
+            context: { ...context, property: 'session.properties' },
+          })
+        }
       }
     }
 

package/src/modeling/validation/api_model_validation_rules.md

@@ -23,9 +23,9 @@ Validations are evaluated with one of three severity levels:
 ## 3. Security & Access Control
 
 - **Authentication** [Error]: The `authentication` configuration is required.
-  - If the strategy is `UsernamePassword`, the `passwordKey` must be defined.
+  - If the strategy is `UsernamePassword`, the user entity must contain a property with the `Username` semantic.
 - **Authorization** [Error]: The `authorization` configuration is required.
-  - If the strategy is `RBAC`, the `roleKey` must be defined.
+  - If the strategy is `RBAC`, the user entity must contain a property with the `UserRole` semantic.
 - **Session Configuration** [Error]: The `session` configuration is required and must meet the following criteria:
   - **Secret**: A session encryption token (`secret`) is required.
   - **Properties**: The `session.properties` array must have at least one property set (e.g. to identify the User ID).

package/tests/unit/modeling/RuntimeApiModel.spec.ts

@@ -2,6 +2,7 @@ import { test } from '@japa/runner'
 import { ApiModel } from '../../../src/modeling/ApiModel.js'
 import { RuntimeApiModel, type RuntimeApiModelSchema } from '../../../src/modeling/RuntimeApiModel.js'
 import { DataDomain } from '../../../src/modeling/DataDomain.js'
+import { SemanticType } from '../../../src/modeling/Semantics.js'
 
 test.group('RuntimeApiModel', () => {
   test('initializes from schema', ({ assert }) => {
@@ -119,4 +120,34 @@ test.group('RuntimeApiModel', () => {
     const missingActionResult = runtimeModel.lookupAction('GET', '/missing-action')
     assert.isUndefined(missingActionResult)
   }).tags(['@modeling', '@runtime'])
+
+  test('caches user entity and properties based on semantics', ({ assert }) => {
+    const domain = new DataDomain({ info: { version: '1.0.0' } })
+    const modelNode = domain.addModel({ key: 'users' })
+    const userEntity = modelNode.addEntity({ info: { name: 'User' }, semantics: [{ id: SemanticType.User }] })
+
+    const passwordProp = userEntity.addProperty({
+      info: { name: 'Password' },
+      semantics: [{ id: SemanticType.Password }],
+    })
+    const roleProp = userEntity.addProperty({ info: { name: 'Role' }, semantics: [{ id: SemanticType.UserRole }] })
+    const usernameProp = userEntity.addProperty({
+      info: { name: 'Username' },
+      semantics: [{ id: SemanticType.Username }],
+    })
+
+    const schema = {
+      key: 'api-1',
+      info: { name: 'Test API' },
+      user: { key: userEntity.key, domain: domain.key },
+      routingMap: {},
+    }
+
+    const runtimeModel = new RuntimeApiModel(schema as any, domain.toJSON())
+
+    assert.equal(runtimeModel.cachedEntities.user?.key, userEntity.key)
+    assert.equal(runtimeModel.cachedProperties.password?.key, passwordProp.key)
+    assert.equal(runtimeModel.cachedProperties.role?.key, roleProp.key)
+    assert.equal(runtimeModel.cachedProperties.username?.key, usernameProp.key)
+  }).tags(['@modeling', '@runtime'])
 })