@api-client/core 0.19.31 → 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.31",
+  "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/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/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

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'])
 })

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

@@ -53,7 +53,7 @@ test.group('ApiModel.createSchema()', () => {
       user: { key: 'user-entity' },
       dependencyList: [{ key: 'domain1', version: '1.0.0' }],
       authentication: { strategy: 'UsernamePassword' },
-      authorization: { strategy: 'RBAC', roleKey: 'role' } as RolesBasedAccessControl,
+      authorization: { strategy: 'RBAC' } as RolesBasedAccessControl,
       session: { secret: 'secret', properties: ['email'] },
       accessRule: [{ type: 'public' }],
       rateLimiting: { rules: [] },
@@ -72,7 +72,7 @@ test.group('ApiModel.createSchema()', () => {
     assert.deepEqual(schema.user, { key: 'user-entity' })
     assert.deepEqual(schema.dependencyList, [{ key: 'domain1', version: '1.0.0' }])
     assert.deepEqual(schema.authentication, { strategy: 'UsernamePassword' })
-    assert.deepEqual(schema.authorization, { strategy: 'RBAC', roleKey: 'role' })
+    assert.deepEqual(schema.authorization, { strategy: 'RBAC' })
     assert.deepEqual(schema.session, { secret: 'secret', properties: ['email'] })
     assert.deepEqual(schema.accessRule, [{ type: 'public' }])
     assert.deepEqual(schema.rateLimiting, { rules: [] })
@@ -132,7 +132,7 @@ test.group('ApiModel.constructor()', () => {
       user: { key: 'user-entity' },
       dependencyList: [{ key: 'domain1', version: '1.0.0' }],
       authentication: { strategy: 'UsernamePassword' },
-      authorization: { strategy: 'RBAC', roleKey: 'role' } as RolesBasedAccessControl,
+      authorization: { strategy: 'RBAC' } as RolesBasedAccessControl,
       session: { secret: 'secret', properties: ['email'] },
       accessRule: [{ type: 'allowPublic' }],
       rateLimiting: { rules: [] },
@@ -150,7 +150,7 @@ test.group('ApiModel.constructor()', () => {
     assert.deepEqual(model.user, { key: 'user-entity' })
     assert.deepEqual(model.dependencyList, [{ key: 'domain1', version: '1.0.0' }])
     assert.deepEqual(model.authentication, { strategy: 'UsernamePassword' })
-    assert.deepEqual(model.authorization, { strategy: 'RBAC', roleKey: 'role' })
+    assert.deepEqual(model.authorization, { strategy: 'RBAC' })
     assert.deepEqual(model.session, { secret: 'secret', properties: ['email'] })
     assert.deepEqual(model.accessRule, [new AllowPublicAccessRule(model)])
     assert.deepEqual(model.rateLimiting, new RateLimitingConfiguration())
@@ -289,7 +289,7 @@ test.group('ApiModel.toJSON()', () => {
       user: { key: 'user-entity' },
       dependencyList: [{ key: 'domain1', version: '1.0.0' }],
       authentication: { strategy: 'UsernamePassword' },
-      authorization: { strategy: 'RBAC', roleKey: 'role' } as RolesBasedAccessControl,
+      authorization: { strategy: 'RBAC' } as RolesBasedAccessControl,
       session: { secret: 'secret', properties: ['email'] },
       accessRule: [{ type: 'allowPublic' }],
       rateLimiting: { rules: [] },
@@ -308,7 +308,7 @@ test.group('ApiModel.toJSON()', () => {
     assert.deepEqual(json.user, { key: 'user-entity' })
     assert.deepEqual(json.dependencyList, [{ key: 'domain1', version: '1.0.0' }])
     assert.deepEqual(json.authentication, { strategy: 'UsernamePassword' })
-    assert.deepEqual(json.authorization, { strategy: 'RBAC', roleKey: 'role' })
+    assert.deepEqual(json.authorization, { strategy: 'RBAC' })
     assert.deepEqual(json.session, { secret: 'secret', properties: ['email'] })
     assert.deepEqual(json.accessRule, [{ type: 'allowPublic' }])
     assert.deepEqual(json.rateLimiting, { rules: [] })

package/tests/unit/modeling/generators/OasGenerator.spec.ts

@@ -32,7 +32,7 @@ test.group('OasGenerator', (group) => {
       info: { name: 'email' },
       semantics: [{ id: SemanticType.Email }, { id: SemanticType.Username }],
     })
-    const passwd = user.addProperty({
+    user.addProperty({
       type: 'string',
       required: true,
       info: { name: 'password' },
@@ -148,11 +148,9 @@ test.group('OasGenerator', (group) => {
     }
     api.authentication = {
       strategy: 'UsernamePassword',
-      passwordKey: passwd.key,
     }
     api.authorization = {
       strategy: 'RBAC',
-      roleKey: role.key,
     }
     api.pagination = { kind: 'cursor', defaultLimit: 50, maxLimit: 70 }
     const userExposure = api.exposeEntity({ key: user.key })

package/tests/unit/modeling/validation/api_model_rules.spec.ts

@@ -63,8 +63,8 @@ test.group('ApiModel Validation', () => {
 
     const model = new ApiModel(
       {
-        authentication: { strategy: 'UsernamePassword', passwordKey: 'pass' } as UsernamePasswordConfiguration,
-        authorization: { strategy: 'RBAC', roleKey: 'role' } as RolesBasedAccessControl,
+        authentication: { strategy: 'UsernamePassword' } as UsernamePasswordConfiguration,
+        authorization: { strategy: 'RBAC' } as RolesBasedAccessControl,
         session: {
           secret: 'super-secret',
           properties: ['id', 'role'],
@@ -91,8 +91,8 @@ test.group('ApiModel Validation', () => {
     const domain = new DataDomain({ info: { version: '1.0.0' } })
     const model = new ApiModel(
       {
-        authentication: { strategy: 'UsernamePassword', passwordKey: 'pass' } as UsernamePasswordConfiguration,
-        authorization: { strategy: 'RBAC', roleKey: 'role' } as RolesBasedAccessControl,
+        authentication: { strategy: 'UsernamePassword' } as UsernamePasswordConfiguration,
+        authorization: { strategy: 'RBAC' } as RolesBasedAccessControl,
         session: {
           secret: 'super-secret',
           properties: [],
@@ -126,8 +126,8 @@ test.group('ApiModel Validation', () => {
 
     const model = new ApiModel(
       {
-        authentication: { strategy: 'UsernamePassword', passwordKey: 'pass' } as UsernamePasswordConfiguration,
-        authorization: { strategy: 'RBAC', roleKey: 'role' } as RolesBasedAccessControl,
+        authentication: { strategy: 'UsernamePassword' } as UsernamePasswordConfiguration,
+        authorization: { strategy: 'RBAC' } as RolesBasedAccessControl,
         session: { secret: 'secret', properties: [] },
         user: { key: userEntity.key, domain: domain.key },
       },
@@ -148,8 +148,8 @@ test.group('ApiModel Validation', () => {
 
     const model = new ApiModel(
       {
-        authentication: { strategy: 'UsernamePassword', passwordKey: 'pass' } as UsernamePasswordConfiguration,
-        authorization: { strategy: 'RBAC', roleKey: 'role' } as RolesBasedAccessControl,
+        authentication: { strategy: 'UsernamePassword' } as UsernamePasswordConfiguration,
+        authorization: { strategy: 'RBAC' } as RolesBasedAccessControl,
         session: { secret: 'secret', properties: [] },
         user: { key: userEntity.key, domain: domain.key },
       },
@@ -170,8 +170,8 @@ test.group('ApiModel Validation', () => {
 
     const model = new ApiModel(
       {
-        authentication: { strategy: 'UsernamePassword', passwordKey: 'pass' } as UsernamePasswordConfiguration,
-        authorization: { strategy: 'RBAC', roleKey: 'role' } as RolesBasedAccessControl,
+        authentication: { strategy: 'UsernamePassword' } as UsernamePasswordConfiguration,
+        authorization: { strategy: 'RBAC' } as RolesBasedAccessControl,
         session: { secret: 'secret', properties: [] },
         user: { key: userEntity.key, domain: domain.key },
       },
@@ -397,8 +397,8 @@ test.group('ApiModel Validation', () => {
     const model = new ApiModel(
       {
         info: { name: 'Valid API', description: 'A test definition' },
-        authentication: { strategy: 'UsernamePassword', passwordKey: 'pass' } as UsernamePasswordConfiguration,
-        authorization: { strategy: 'RBAC', roleKey: 'role' } as RolesBasedAccessControl,
+        authentication: { strategy: 'UsernamePassword' } as UsernamePasswordConfiguration,
+        authorization: { strategy: 'RBAC' } as RolesBasedAccessControl,
         session: {
           secret: 'super-secret',
           properties: ['id', 'role'],