@api-client/core 0.20.1 → 0.20.2

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.20.1",
+  "version": "0.20.2",
   "license": "UNLICENSED",
   "exports": {
     "./browser.js": {

package/src/modeling/RuntimeApiModel.ts

@@ -39,19 +39,20 @@ export interface RuntimeApiModelSchema extends ApiModelSchema {
 }
 
 export interface RuntimeResolvedAction {
-  entity: ExposedEntity
+  exposure: ExposedEntity
+  entity: DomainEntity
   action: Action
   params: Record<string, string>
 }
 
 export type RuleEvaluator = (rule: AccessRule) => Promise<boolean | undefined> | boolean | undefined
 
-interface PhaseRules {
+export interface PhaseRules {
   permissionRules: AccessRule[]
   mandatoryRules: AccessRule[]
 }
 
-interface ActionRulesCache {
+export interface ActionRulesCache {
   preFetch: PhaseRules
   fetch: PhaseRules
   postFetch: PhaseRules
@@ -281,17 +282,23 @@ export class RuntimeApiModel extends ApiModel {
 
     const params = exec(path, matchedRoute)
 
-    const entity = this.exposes.get(def.lookup.exposedEntityKey)
-    if (!entity) {
-      return undefined
+    const exposure = this.exposes.get(def.lookup.exposedEntityKey)
+    if (!exposure) {
+      throw new Exception('Missing exposure ' + def.lookup.exposedEntityKey, { code: 'API_MODEL_ERROR', status: 500 })
     }
 
-    const action = entity.actions.find((a) => a.kind === def.lookup.actionKind)
+    const action = exposure.actions.find((a) => a.kind === def.lookup.actionKind)
     if (!action) {
-      return undefined
+      throw new Exception('Missing action ' + def.lookup.actionKind, { code: 'API_MODEL_ERROR', status: 500 })
+    }
+
+    const entity = this.domain?.findEntity(exposure.entity.key, exposure.entity.domain)
+    if (!entity) {
+      throw new Exception('Missing entity ' + exposure.entity.key, { code: 'API_MODEL_ERROR', status: 500 })
     }
 
     return {
+      exposure,
       entity,
       action,
       params,
@@ -299,64 +306,15 @@ export class RuntimeApiModel extends ApiModel {
   }
 
   /**
-   * Evaluates access rules for a given action and phase.
-   *
-   * The evaluation process follows two phases per execution phase (PRE_FETCH, FETCH, POST_FETCH):
-   * 1. Mandatory Phase: All rules marked as `mandatory: true` across all levels must return true.
-   *    If any fail, the request is immediately rejected.
-   * 2. Permission Phase: Evaluation follows the hierarchy from most specific to most general:
-   *    Action -> Endpoint (ExposedEntity) -> API Model.
-   *    If an explicit allow (true) or deny (false) is hit, evaluation stops and returns the result.
-   *    If no rules match (all return undefined), the request is rejected by default.
-   *
-   * @param action The resolved action to evaluate.
-   * @param evaluator A callback that evaluates a single rule. Should return true (allow),
-   *                  false (deny), or undefined (no hit).
-   * @param phase The execution phase to evaluate.
-   * @returns A promise that resolves to true if access is granted, false if denied.
+   * Retrieves the precomputed and shadowed effective rules for a given action.
    */
-  async evaluateAccess(
-    action: RuntimeResolvedAction,
-    evaluator: RuleEvaluator,
-    phase: AccessRuleExecutionPhase
-  ): Promise<boolean> {
+  getEffectiveRules(action: RuntimeResolvedAction): ActionRulesCache {
     let cachedRules = this.#actionRulesCache.get(action.action)
     if (!cachedRules) {
-      // Fallback if somehow action is not cached (e.g. dynamically added after initialization or in tests)
-      cachedRules = this.#computeEffectiveRules(action.action, action.entity)
+      cachedRules = this.#computeEffectiveRules(action.action, action.exposure)
       this.#actionRulesCache.set(action.action, cachedRules)
     }
-
-    let rulesForPhase
-    if (phase === AccessRuleExecutionPhase.POST_FETCH) {
-      rulesForPhase = cachedRules.postFetch
-    } else if (phase === AccessRuleExecutionPhase.FETCH) {
-      rulesForPhase = cachedRules.fetch
-    } else {
-      rulesForPhase = cachedRules.preFetch
-    }
-
-    // Step 1: Mandatory Phase
-    for (const rule of rulesForPhase.mandatoryRules) {
-      const result = await evaluator(rule)
-      if (result !== true) {
-        return false // Immediately reject if any mandatory rule fails
-      }
-    }
-
-    // Step 2-4: Permission Phase
-    for (const rule of rulesForPhase.permissionRules) {
-      const result = await evaluator(rule)
-      if (result === true) {
-        return true
-      }
-      if (result === false) {
-        return false
-      }
-    }
-
-    // Default: no hit
-    return false
+    return cachedRules
   }
 
   override toJSON(): RuntimeApiModelSchema {

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

@@ -10,11 +10,10 @@ test.group('RuntimeApiModel', () => {
   test('initializes from schema', ({ assert }) => {
     const domain = new DataDomain({ info: { version: '1.0.0' } })
     const model = domain.addModel({ info: { name: 'Test Model' } })
-    const entity = model.addEntity({ key: 'ent-1', info: { name: 'User' } })
+    const entity = model.addEntity({ info: { name: 'User' } })
 
     const baseModel = new ApiModel(
       {
-        key: 'api-1',
         info: { name: 'Test API' },
       },
       domain
@@ -37,13 +36,15 @@ test.group('RuntimeApiModel', () => {
 
   test('resolves path with matchit', ({ assert }) => {
     const domain = new DataDomain({ info: { version: '1.0.0' } })
+    const model = domain.addModel({ info: { name: 'Test Model' } })
+    const entity = model.addEntity({ info: { name: 'User' } })
     const schema = {
       key: 'api-1',
       info: { name: 'Test API' },
       exposes: [
         {
           key: 'expose-1',
-          entity: { key: 'ent-1', type: 'association' },
+          entity: { key: entity.key, domain: domain.key },
           actions: [
             { kind: 'read', type: 'crud' },
             { kind: 'list', type: 'crud' },
@@ -92,7 +93,7 @@ test.group('RuntimeApiModel', () => {
     assert.isUndefined(getResult)
   }).tags(['@modeling', '@runtime'])
 
-  test('returns undefined when entity or action is missing', ({ assert }) => {
+  test('throws error when entity or action is missing', ({ assert }) => {
     const domain = new DataDomain({ info: { version: '1.0.0' } })
     const schema = {
       key: 'api-1',
@@ -115,12 +116,14 @@ test.group('RuntimeApiModel', () => {
     const runtimeModel = new RuntimeApiModel(schema as any, domain.toJSON())
 
     // Exposed entity not found
-    const missingEntityResult = runtimeModel.lookupAction('GET', '/missing-entity')
-    assert.isUndefined(missingEntityResult)
+    assert.throws(() => {
+      runtimeModel.lookupAction('GET', '/missing-entity')
+    }, 'Missing exposure missing-expose')
 
     // Action not found on entity
-    const missingActionResult = runtimeModel.lookupAction('GET', '/missing-action')
-    assert.isUndefined(missingActionResult)
+    assert.throws(() => {
+      runtimeModel.lookupAction('GET', '/missing-action')
+    }, 'Missing action read')
   }).tags(['@modeling', '@runtime'])
 
   test('caches user entity and properties based on semantics', ({ assert }) => {
@@ -211,7 +214,7 @@ test.group('RuntimeApiModel', () => {
     assert.equal(runtimeModel.sessionProperties.size, 0)
   }).tags(['@modeling', '@runtime'])
 
-  test('evaluateAccess - rejects if any mandatory rule fails', async ({ assert }) => {
+  test('getEffectiveRules - separates mandatory and permission rules', async ({ assert }) => {
     const domain = new DataDomain({ info: { version: '1.0.0' } })
     const baseModel = new ApiModel(
       { key: 'api-1', accessRule: [{ type: 'allowAuthenticated', mandatory: true }] },
@@ -220,40 +223,41 @@ test.group('RuntimeApiModel', () => {
     const runtimeModel = new RuntimeApiModel(baseModel.toJSON() as any, domain.toJSON())
 
     const mockAction = {
-      entity: { accessRule: [], parent: undefined },
+      exposure: { accessRule: [], parent: undefined },
       action: { kind: 'read', accessRule: [] },
     } as any
 
-    const evaluator: RuleEvaluator = async (_rule: AccessRule): Promise<boolean> => false // Mandatory rule fails
-    const result = await runtimeModel.evaluateAccess(mockAction, evaluator, AccessRuleExecutionPhase.PRE_FETCH)
-    assert.isFalse(result)
+    const rules = runtimeModel.getEffectiveRules(mockAction)
+    assert.equal(rules.preFetch.mandatoryRules.length, 1)
+    assert.equal(rules.preFetch.mandatoryRules[0].type, 'allowAuthenticated')
+    assert.equal(rules.preFetch.permissionRules.length, 0)
   }).tags(['@modeling', '@runtime', '@authorization'])
 
-  test('evaluateAccess - rejects by default if no rules hit', async ({ assert }) => {
+  test('getEffectiveRules - defaults to preFetch phase if none specified', async ({ assert }) => {
     const domain = new DataDomain({ info: { version: '1.0.0' } })
     const baseModel = new ApiModel({ key: 'api-1' }, domain)
     const runtimeModel = new RuntimeApiModel(baseModel.toJSON() as any, domain.toJSON())
 
     const mockAction = {
-      entity: {
+      exposure: {
         accessRule: [{ type: 'allowPublic', metadata: { read: AccessRuleExecutionPhase.PRE_FETCH } }],
         parent: undefined,
       },
       action: { kind: 'read', accessRule: [] },
     } as any
 
-    const evaluator: RuleEvaluator = async (_rule: AccessRule): Promise<undefined> => undefined // No rules match
-    const result = await runtimeModel.evaluateAccess(mockAction, evaluator, AccessRuleExecutionPhase.PRE_FETCH)
-    assert.isFalse(result)
+    const rules = runtimeModel.getEffectiveRules(mockAction)
+    assert.equal(rules.preFetch.permissionRules.length, 1)
+    assert.equal(rules.preFetch.permissionRules[0].type, 'allowPublic')
   }).tags(['@modeling', '@runtime', '@authorization'])
 
-  test('evaluateAccess - evaluates from most specific to most general in permission phase', async ({ assert }) => {
+  test('getEffectiveRules - orders from most specific to most general', async ({ assert }) => {
     const domain = new DataDomain({ info: { version: '1.0.0' } })
-    const baseModel = new ApiModel({ key: 'api-1', accessRule: [{ type: 'allowAuthenticated' }] }, domain)
+    const baseModel = new ApiModel({ accessRule: [{ type: 'allowAuthenticated' }] }, domain)
     const runtimeModel = new RuntimeApiModel(baseModel.toJSON() as any, domain.toJSON())
 
     const mockAction = {
-      entity: {
+      exposure: {
         accessRule: [{ type: 'allowPublic', metadata: { read: AccessRuleExecutionPhase.PRE_FETCH } }],
         parent: undefined,
       },
@@ -263,77 +267,19 @@ test.group('RuntimeApiModel', () => {
       },
     } as any
 
-    const evaluatedOrder: string[] = []
-    const evaluator: RuleEvaluator = async (rule: AccessRule): Promise<undefined> => {
-      evaluatedOrder.push(rule.type)
-      return undefined // Continue to next rule
-    }
-
-    await runtimeModel.evaluateAccess(mockAction, evaluator, AccessRuleExecutionPhase.PRE_FETCH)
-    assert.deepEqual(evaluatedOrder, ['matchEmailDomain', 'allowPublic', 'allowAuthenticated'])
-  }).tags(['@modeling', '@runtime', '@authorization'])
-
-  test('evaluateAccess - short-circuits on explicit allow or deny in permission phase', async ({ assert }) => {
-    const domain = new DataDomain({ info: { version: '1.0.0' } })
-    const baseModel = new ApiModel({ key: 'api-1', accessRule: [{ type: 'allowAuthenticated' }] }, domain)
-    const runtimeModel = new RuntimeApiModel(baseModel.toJSON() as any, domain.toJSON())
-
-    const mockAction = {
-      entity: {
-        accessRule: [{ type: 'allowPublic', metadata: { read: AccessRuleExecutionPhase.PRE_FETCH } }],
-        parent: undefined,
-      },
-      action: {
-        kind: 'read',
-        accessRule: [{ type: 'matchEmailDomain', metadata: { read: AccessRuleExecutionPhase.PRE_FETCH } }],
-      },
-    } as any
-
-    const evaluatedOrder: string[] = []
-    const evaluator = async (rule: any) => {
-      evaluatedOrder.push(rule.type)
-      if (rule.type === 'allowPublic') return true
-      return undefined
-    }
-
-    const result = await runtimeModel.evaluateAccess(mockAction, evaluator, AccessRuleExecutionPhase.PRE_FETCH)
-    assert.isTrue(result)
-    // Should not reach the api-rule
-    assert.deepEqual(evaluatedOrder, ['matchEmailDomain', 'allowPublic'])
-  }).tags(['@modeling', '@runtime', '@authorization'])
-
-  test('evaluateAccess - passes mandatory phase and uses permission phase result', async ({ assert }) => {
-    const domain = new DataDomain({ info: { version: '1.0.0' } })
-    const baseModel = new ApiModel(
-      { key: 'api-1', accessRule: [{ type: 'allowAuthenticated', mandatory: true }] },
-      domain
+    const rules = runtimeModel.getEffectiveRules(mockAction)
+    assert.equal(rules.preFetch.permissionRules.length, 3)
+    assert.deepEqual(
+      rules.preFetch.permissionRules.map((r) => r.type),
+      ['matchEmailDomain', 'allowPublic', 'allowAuthenticated']
     )
-    const runtimeModel = new RuntimeApiModel(baseModel.toJSON() as any, domain.toJSON())
-
-    const mockAction = {
-      entity: {
-        accessRule: [{ type: 'allowPublic', metadata: { read: AccessRuleExecutionPhase.PRE_FETCH } }],
-        parent: undefined,
-      },
-      action: { kind: 'read', accessRule: [] },
-    } as any
-
-    const evaluator = async (rule: any) => {
-      if (rule.mandatory) return true // passes mandatory check
-      if (rule.type === 'allowPublic') return false // explicitly denies
-      return undefined
-    }
-
-    const result = await runtimeModel.evaluateAccess(mockAction, evaluator, AccessRuleExecutionPhase.PRE_FETCH)
-    assert.isFalse(result) // Denied by permission rule
   }).tags(['@modeling', '@runtime', '@authorization'])
 
-  test('evaluateAccess - shadows parent rules of the same type', async ({ assert }) => {
+  test('getEffectiveRules - shadows parent rules of the same type', async ({ assert }) => {
     const domain = new DataDomain({ info: { version: '1.0.0' } })
     const model = domain.addModel({ key: 'mod-1' })
     const entity = model.addEntity({ key: 'ent-1' })
 
-    // Create base model with exposing and actions directly in schema
     const baseModel = new ApiModel(
       {
         key: 'api-1',
@@ -361,19 +307,6 @@ test.group('RuntimeApiModel', () => {
       domain
     )
 
-    // Hierarchy will be:
-    // Action: allowAuthenticated (mandatory)
-    // Entity: allowPublic, matchEmailDomain (mandatory)
-    // API: allowAuthenticated, matchEmailDomain
-
-    // Effective Rules (with shadowing):
-    // Action's allowAuthenticated (mandatory) shadows API's allowAuthenticated
-    // Entity's matchEmailDomain (mandatory) shadows API's matchEmailDomain
-    // Entity's allowPublic is kept
-
-    // Mandatory: allowAuthenticated, matchEmailDomain
-    // Permission: allowPublic
-
     const schema: RuntimeApiModelSchema = {
       ...baseModel.toJSON(),
       routingMap: {
@@ -384,16 +317,15 @@ test.group('RuntimeApiModel', () => {
     const runtimeModel = new RuntimeApiModel(schema, domain.toJSON())
     const mockAction = runtimeModel.lookupAction('GET', '/test')!
 
-    const evaluatedOrder: string[] = []
-    const evaluator: RuleEvaluator = async (rule: AccessRule): Promise<boolean | undefined> => {
-      evaluatedOrder.push(`${rule.type}${rule.mandatory ? '-mandatory' : ''}`)
-      if (rule.mandatory) return true
-      return undefined
-    }
-
-    await runtimeModel.evaluateAccess(mockAction, evaluator, AccessRuleExecutionPhase.PRE_FETCH)
+    const rules = runtimeModel.getEffectiveRules(mockAction)
 
-    // Check that we only evaluate the shadowed rules, exactly once per phase
-    assert.deepEqual(evaluatedOrder, ['allowAuthenticated-mandatory', 'matchEmailDomain-mandatory', 'allowPublic'])
+    assert.deepEqual(
+      rules.preFetch.mandatoryRules.map((r) => r.type),
+      ['allowAuthenticated', 'matchEmailDomain']
+    )
+    assert.deepEqual(
+      rules.preFetch.permissionRules.map((r) => r.type),
+      ['allowPublic']
+    )
   }).tags(['@modeling', '@runtime', '@authorization'])
 })