@mmapp/player-core 0.1.0-alpha.1

package/src/__tests__/frontend-context.test.ts

@@ -0,0 +1,182 @@
+/**
+ * Frontend Expression Context Tests — verifies evaluator resolves
+ * event, local, viewport, and $domain() context fields.
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import { createEvaluator, WEB_FAILURE_POLICIES, clearExpressionCache } from '../expression';
+import type { Evaluator, ExpressionContext } from '../expression';
+
+describe('Frontend Expression Context', () => {
+  let evaluator: Evaluator;
+
+  beforeEach(() => {
+    clearExpressionCache();
+  });
+
+  it('resolves event payload fields', () => {
+    evaluator = createEvaluator({
+      functions: [],
+      failurePolicy: WEB_FAILURE_POLICIES.VIEW_BINDING,
+    });
+
+    const ctx: ExpressionContext = {
+      state_data: {},
+      memory: {},
+      current_state: 'listening',
+      status: 'ACTIVE',
+      event: {
+        instance_id: 'i-123',
+        from_state: 'pending',
+        to_state: 'completed',
+        changed_fields: ['status', 'result'],
+      },
+    };
+
+    expect(evaluator.evaluate('event.to_state', ctx).value).toBe('completed');
+    expect(evaluator.evaluate('event.instance_id', ctx).value).toBe('i-123');
+  });
+
+  it('resolves local state fields', () => {
+    evaluator = createEvaluator({
+      functions: [],
+      failurePolicy: WEB_FAILURE_POLICIES.VIEW_BINDING,
+    });
+
+    const ctx: ExpressionContext = {
+      state_data: {},
+      memory: {},
+      current_state: 'active',
+      status: 'ACTIVE',
+      local: {
+        selected_tab: 'details',
+        filter_active: true,
+      },
+    };
+
+    expect(evaluator.evaluate('local.selected_tab', ctx).value).toBe('details');
+    expect(evaluator.evaluate('local.filter_active', ctx).value).toBe(true);
+  });
+
+  it('resolves viewport dimensions via custom functions', () => {
+    evaluator = createEvaluator({
+      functions: [
+        { name: 'viewport_width', fn: () => 1920, arity: 0 },
+        { name: 'viewport_height', fn: () => 1080, arity: 0 },
+        { name: 'is_online', fn: () => true, arity: 0 },
+      ],
+      failurePolicy: WEB_FAILURE_POLICIES.VIEW_BINDING,
+    });
+
+    const ctx: ExpressionContext = {
+      state_data: {},
+      memory: {},
+      current_state: 'active',
+      status: 'ACTIVE',
+    };
+
+    expect(evaluator.evaluate('viewport_width()', ctx).value).toBe(1920);
+    expect(evaluator.evaluate('viewport_height()', ctx).value).toBe(1080);
+    expect(evaluator.evaluate('is_online()', ctx).value).toBe(true);
+  });
+
+  it('resolves $domain() via custom function', () => {
+    evaluator = createEvaluator({
+      functions: [
+        {
+          name: '$domain',
+          fn: (slug: unknown, field: unknown) => {
+            if (slug === 'user-stats' && field === 'points') return 42;
+            if (slug === 'user-stats' && field === 'level') return 5;
+            return undefined;
+          },
+          arity: 2,
+        },
+      ],
+      failurePolicy: WEB_FAILURE_POLICIES.VIEW_BINDING,
+    });
+
+    const ctx: ExpressionContext = {
+      state_data: {},
+      memory: {},
+      current_state: 'dashboard',
+      status: 'ACTIVE',
+    };
+
+    expect(evaluator.evaluate("$domain('user-stats', 'points')", ctx).value).toBe(42);
+    expect(evaluator.evaluate("$domain('user-stats', 'level')", ctx).value).toBe(5);
+  });
+
+  it('resolves $fe_ref() via custom function', () => {
+    evaluator = createEvaluator({
+      functions: [
+        {
+          name: '$fe_ref',
+          fn: (instanceId: unknown, path: unknown) => {
+            if (instanceId === 'nav-1' && path === 'active_page') return '/dashboard';
+            return undefined;
+          },
+          arity: 2,
+        },
+      ],
+      failurePolicy: WEB_FAILURE_POLICIES.VIEW_BINDING,
+    });
+
+    const ctx: ExpressionContext = {
+      state_data: {},
+      memory: {},
+      current_state: 'nav',
+      status: 'ACTIVE',
+    };
+
+    expect(evaluator.evaluate("$fe_ref('nav-1', 'active_page')", ctx).value).toBe('/dashboard');
+  });
+
+  it('resolves $local() via custom function', () => {
+    evaluator = createEvaluator({
+      functions: [
+        {
+          name: '$local',
+          fn: (key: unknown) => {
+            const store: Record<string, unknown> = { theme: 'dark', lang: 'en' };
+            return store[key as string];
+          },
+          arity: 1,
+        },
+      ],
+      failurePolicy: WEB_FAILURE_POLICIES.VIEW_BINDING,
+    });
+
+    const ctx: ExpressionContext = {
+      state_data: {},
+      memory: {},
+      current_state: 'settings',
+      status: 'ACTIVE',
+    };
+
+    expect(evaluator.evaluate("$local('theme')", ctx).value).toBe('dark');
+    expect(evaluator.evaluate("$local('lang')", ctx).value).toBe('en');
+  });
+
+  it('combines event + state_data + functions in one context', () => {
+    evaluator = createEvaluator({
+      functions: [
+        { name: 'viewport_width', fn: () => 800, arity: 0 },
+      ],
+      failurePolicy: WEB_FAILURE_POLICIES.VIEW_BINDING,
+    });
+
+    const ctx: ExpressionContext = {
+      state_data: { total: 100 },
+      memory: { last_seen: 'yesterday' },
+      current_state: 'dashboard',
+      status: 'ACTIVE',
+      total: 100,
+      event: { new_points: 10 },
+    };
+
+    // Expression using state_data field + event field + function
+    expect(evaluator.evaluate('add(total, event.new_points)', ctx).value).toBe(110);
+    expect(evaluator.evaluate('gt(viewport_width(), 768)', ctx).value).toBe(true);
+  });
+});

package/src/__tests__/integration.test.ts

@@ -0,0 +1,256 @@
+/**
+ * Integration Tests — full chain from domain event through browser engine to action dispatch.
+ *
+ * Tests the complete pipeline:
+ * 1. Create state machine with on_event subscription
+ * 2. Wire event bus to action handler
+ * 3. Publish domain event matching the pattern
+ * 4. Verify action fires with correct context
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { StateMachine } from '../state-machine/interpreter';
+import { EventBus } from '../events/event-bus';
+import { ActionDispatcher } from '../actions/dispatcher';
+import { createEvaluator, WEB_FAILURE_POLICIES, clearExpressionCache } from '../expression';
+import type { PlayerWorkflowDefinition, PlayerAction } from '../state-machine/types';
+import type { Evaluator, ExpressionContext } from '../expression/types';
+
+describe('Integration: Domain Event → Engine → Action', () => {
+  let evaluator: Evaluator;
+  let eventBus: EventBus;
+  let dispatcher: ActionDispatcher;
+
+  beforeEach(() => {
+    clearExpressionCache();
+    evaluator = createEvaluator({
+      functions: [],
+      failurePolicy: WEB_FAILURE_POLICIES.EVENT_REACTION,
+    });
+    eventBus = new EventBus();
+    dispatcher = new ActionDispatcher();
+  });
+
+  it('full chain: domain event → pattern match → toast action fires', async () => {
+    // 1. Define workflow with on_event subscription
+    const definition: PlayerWorkflowDefinition = {
+      id: 'dashboard-experience',
+      slug: 'dashboard',
+      states: [
+        {
+          name: 'active',
+          type: 'START',
+          on_event: [
+            {
+              match: 'project:*:*:complete_task.transitioned',
+              actions: [
+                {
+                  type: 'toast',
+                  config: { variant: 'success', message: 'Task completed!' },
+                },
+              ],
+            },
+          ],
+        },
+      ],
+      transitions: [],
+    };
+
+    // 2. Create state machine
+    const sm = new StateMachine(definition, {}, {
+      evaluator,
+      actionHandlers: new Map(),
+    });
+
+    // 3. Register toast handler
+    const toastHandler = vi.fn();
+    dispatcher.register('toast', toastHandler);
+
+    // 4. Wire on_event subscriptions to event bus → action dispatcher
+    const stateDef = sm.getCurrentStateDefinition();
+    if (stateDef?.on_event) {
+      for (const sub of stateDef.on_event) {
+        eventBus.subscribe(sub.match, async (event) => {
+          const ctx: ExpressionContext = {
+            ...sm.stateData,
+            state_data: sm.stateData,
+            memory: sm.getSnapshot().memory,
+            current_state: sm.currentState,
+            status: sm.status,
+            event: event.payload,
+          };
+          await dispatcher.execute(sub.actions, ctx, evaluator);
+        });
+      }
+    }
+
+    // 5. Publish domain event (simulating WebSocket delivery)
+    await eventBus.publish('project:stakeholder:s1:complete_task.transitioned', {
+      instance_id: 'i-999',
+      from_state: 'in_progress',
+      to_state: 'done',
+      trigger: 'user',
+    });
+
+    // 6. Verify toast action was called
+    expect(toastHandler).toHaveBeenCalledOnce();
+    expect(toastHandler).toHaveBeenCalledWith(
+      { variant: 'success', message: 'Task completed!' },
+      expect.objectContaining({
+        current_state: 'active',
+        status: 'ACTIVE',
+      }),
+    );
+  });
+
+  it('full chain: domain event with conditions — action fires only when condition met', async () => {
+    const definition: PlayerWorkflowDefinition = {
+      id: 'vote-watcher',
+      slug: 'vote-experience',
+      states: [
+        {
+          name: 'watching',
+          type: 'START',
+          on_event: [
+            {
+              match: 'investment:*:*:vote.transitioned',
+              conditions: ['gte(vote_count, threshold)'],
+              actions: [
+                {
+                  type: 'toast',
+                  config: { variant: 'info', message: 'Funding threshold reached!' },
+                },
+              ],
+            },
+          ],
+        },
+      ],
+      transitions: [],
+    };
+
+    const sm = new StateMachine(definition, { vote_count: 5, threshold: 10 }, {
+      evaluator,
+      actionHandlers: new Map(),
+    });
+
+    const toastHandler = vi.fn();
+    dispatcher.register('toast', toastHandler);
+
+    // Wire subscriptions
+    const stateDef = sm.getCurrentStateDefinition()!;
+    for (const sub of stateDef.on_event!) {
+      eventBus.subscribe(sub.match, async (event) => {
+        const ctx: ExpressionContext = {
+          ...sm.stateData,
+          state_data: sm.stateData,
+          memory: sm.getSnapshot().memory,
+          current_state: sm.currentState,
+          status: sm.status,
+          event: event.payload,
+        };
+
+        // Check conditions
+        if (sub.conditions) {
+          for (const condition of sub.conditions) {
+            const result = evaluator.evaluate<boolean>(condition, ctx);
+            if (!result.value) return; // Skip
+          }
+        }
+
+        await dispatcher.execute(sub.actions, ctx, evaluator);
+      });
+    }
+
+    // Publish event — vote_count (5) < threshold (10), should NOT fire
+    await eventBus.publish('investment:stakeholder:s1:vote.transitioned', {});
+    expect(toastHandler).not.toHaveBeenCalled();
+
+    // Update vote_count past threshold
+    sm.setField('vote_count', 15);
+
+    // Publish again — now vote_count (15) >= threshold (10), should fire
+    await eventBus.publish('investment:stakeholder:s1:vote.transitioned', {});
+    expect(toastHandler).toHaveBeenCalledOnce();
+  });
+
+  it('full chain: multiple subscriptions, only matching patterns fire', async () => {
+    const definition: PlayerWorkflowDefinition = {
+      id: 'multi-sub',
+      slug: 'multi',
+      states: [
+        {
+          name: 'active',
+          type: 'START',
+          on_event: [
+            {
+              match: 'project:*:*:created.transitioned',
+              actions: [{ type: 'action_a', config: {} }],
+            },
+            {
+              match: 'task:*:*:completed.transitioned',
+              actions: [{ type: 'action_b', config: {} }],
+            },
+          ],
+        },
+      ],
+      transitions: [],
+    };
+
+    const sm = new StateMachine(definition, {}, { evaluator, actionHandlers: new Map() });
+    const handlerA = vi.fn();
+    const handlerB = vi.fn();
+    dispatcher.register('action_a', handlerA);
+    dispatcher.register('action_b', handlerB);
+
+    const stateDef = sm.getCurrentStateDefinition()!;
+    for (const sub of stateDef.on_event!) {
+      eventBus.subscribe(sub.match, async (event) => {
+        const ctx: ExpressionContext = {
+          ...sm.stateData, state_data: sm.stateData, memory: {},
+          current_state: sm.currentState, status: sm.status,
+        };
+        await dispatcher.execute(sub.actions, ctx, evaluator);
+      });
+    }
+
+    // Only task event should fire action_b
+    await eventBus.publish('task:s:1:completed.transitioned', {});
+    expect(handlerA).not.toHaveBeenCalled();
+    expect(handlerB).toHaveBeenCalledOnce();
+
+    // Only project event should fire action_a
+    await eventBus.publish('project:s:1:created.transitioned', {});
+    expect(handlerA).toHaveBeenCalledOnce();
+  });
+
+  it('full chain: auto-transition + on_enter actions', async () => {
+    const onEnterHandler = vi.fn();
+    const definition: PlayerWorkflowDefinition = {
+      id: 'auto-chain',
+      slug: 'auto',
+      states: [
+        { name: 'init', type: 'START' },
+        { name: 'processing', type: 'REGULAR', on_enter: [{ type: 'notify', config: { step: 'processing' } }] },
+        { name: 'done', type: 'END', on_enter: [{ type: 'notify', config: { step: 'done' } }] },
+      ],
+      transitions: [
+        { name: 'start', from: ['init'], to: 'processing' },
+        { name: 'auto_complete', from: ['processing'], to: 'done', auto: true },
+      ],
+    };
+
+    const sm = new StateMachine(definition, {}, {
+      evaluator,
+      actionHandlers: new Map([['notify', onEnterHandler]]),
+    });
+
+    // Should auto-chain: init → processing (on_enter fires) → done (on_enter fires)
+    const result = await sm.transition('start');
+    expect(result.success).toBe(true);
+    expect(sm.currentState).toBe('done');
+    expect(sm.status).toBe('COMPLETED');
+    expect(onEnterHandler).toHaveBeenCalledTimes(2);
+    expect(onEnterHandler.mock.calls[0][0]).toEqual({ type: 'notify', config: { step: 'processing' } });
+    expect(onEnterHandler.mock.calls[1][0]).toEqual({ type: 'notify', config: { step: 'done' } });
+  });
+});

package/src/__tests__/security.test.ts

@@ -0,0 +1,190 @@
+/**
+ * Security Tests — Verify that the recursive descent parser
+ * blocks all known sandbox escape vectors.
+ *
+ * These tests confirm that the old new Function() + with() RCE
+ * vulnerabilities are no longer exploitable.
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import {
+  createEvaluator,
+  WEB_FAILURE_POLICIES,
+  clearExpressionCache,
+} from '../expression';
+import type { Evaluator, ExpressionContext } from '../expression';
+
+describe('Security: Expression Evaluator RCE Prevention', () => {
+  let evaluator: Evaluator;
+  let ctx: ExpressionContext;
+
+  beforeEach(() => {
+    clearExpressionCache();
+    evaluator = createEvaluator({
+      functions: [],
+      failurePolicy: WEB_FAILURE_POLICIES.VIEW_BINDING,
+    });
+    ctx = {
+      state_data: { title: 'Test' },
+      memory: {},
+      current_state: 'active',
+      status: 'ACTIVE',
+    };
+  });
+
+  describe('Prototype chain escape prevention', () => {
+    it('constructor.constructor cannot access global scope', () => {
+      // Old vulnerability: constructor.constructor("return this")() gave globalThis
+      const result = evaluator.evaluate('constructor.constructor("return this")()', ctx);
+      // Should NOT return global/window — should be undefined or error
+      expect(result.value).not.toBe(globalThis);
+      // In the safe parser, "constructor" is just an identifier lookup
+      // that resolves from context (undefined), so member access fails
+    });
+
+    it('__proto__ resolves from context but cannot execute code', () => {
+      const result = evaluator.evaluate('__proto__', ctx);
+      // __proto__ may resolve from the context object's prototype,
+      // but it's safe — there's no way to call constructors or execute code
+      expect(result.status).toBe('ok');
+    });
+
+    it('prototype chain traversal is blocked', () => {
+      const result = evaluator.evaluate('state_data.__proto__.constructor', ctx);
+      // The parser resolves this as member access, but __proto__ should
+      // NOT give access to Object constructor in a meaningful way
+      expect(result.status).toBe('ok');
+      // Even if it resolves, it cannot execute arbitrary code
+    });
+  });
+
+  describe('Code injection prevention', () => {
+    it('eval() is not available (returns undefined)', () => {
+      const result = evaluator.evaluate('eval("1+1")', ctx);
+      // eval is just an unknown function — returns undefined
+      expect(result.value).toBeUndefined();
+    });
+
+    it('Function() constructor is not available', () => {
+      // In old code: Function("return process")() could access Node globals
+      // Now: Function("return 42") is a function call on "Function" (an identifier)
+      // that resolves from context. The result of that call cannot be invoked
+      // because the parser sees Function(...)() as a double-call which fails
+      const result = evaluator.evaluate('Function("return 42")()', ctx);
+      // Hits "Cannot call non-function" → fallback ('' for VIEW_BINDING)
+      expect(result.status).toBe('fallback');
+    });
+
+    it('import() is not executable', () => {
+      // import("malicious-module") should fail to parse or be inert
+      const result = evaluator.evaluate('import("fs")', ctx);
+      expect(result.value).toBeUndefined();
+    });
+
+    it('require() is not available', () => {
+      const result = evaluator.evaluate('require("child_process")', ctx);
+      expect(result.value).toBeUndefined();
+    });
+
+    it('globalThis access returns undefined', () => {
+      const result = evaluator.evaluate('globalThis', ctx);
+      expect(result.value).toBeUndefined();
+    });
+
+    it('window access returns undefined', () => {
+      const result = evaluator.evaluate('window', ctx);
+      expect(result.value).toBeUndefined();
+    });
+
+    it('document access returns undefined', () => {
+      const result = evaluator.evaluate('document', ctx);
+      expect(result.value).toBeUndefined();
+    });
+
+    it('process access returns undefined', () => {
+      const result = evaluator.evaluate('process', ctx);
+      expect(result.value).toBeUndefined();
+    });
+  });
+
+  describe('No arbitrary JavaScript execution', () => {
+    it('assignment operators are not supported (parse error)', () => {
+      const result = evaluator.evaluate('x = 42', ctx);
+      // This should either fail to parse or return the identifier value
+      // It should NOT actually assign anything
+      expect(ctx['x']).toBeUndefined();
+    });
+
+    it('semicolons cannot chain statements', () => {
+      // Semicolons should cause a parse error
+      const result = evaluator.validate('a; b');
+      expect(result.valid).toBe(false);
+    });
+
+    it('template literals (backticks) are not supported', () => {
+      const result = evaluator.validate('`${process.env}`');
+      expect(result.valid).toBe(false);
+    });
+
+    it('arrow functions cannot be created', () => {
+      const result = evaluator.validate('() => 42');
+      expect(result.valid).toBe(false);
+    });
+
+    it('for/while/if statements cannot be injected', () => {
+      expect(evaluator.validate('for(;;){}').valid).toBe(false);
+      expect(evaluator.validate('while(1){}').valid).toBe(false);
+    });
+  });
+
+  describe('Depth limit protection', () => {
+    it('deeply nested expressions are rejected', () => {
+      // Create an expression nested 60 levels deep
+      const nested = '(' .repeat(60) + '1' + ')'.repeat(60);
+      const result = evaluator.evaluate(nested, ctx);
+      // Should fail with depth limit
+      expect(result.status).toBe('fallback');
+    });
+  });
+
+  describe('Legitimate expressions still work', () => {
+    it('function calls work normally', () => {
+      expect(evaluator.evaluate('add(1, 2)', ctx).value).toBe(3);
+      expect(evaluator.evaluate('multiply(3, 4)', ctx).value).toBe(12);
+    });
+
+    it('comparisons work normally', () => {
+      expect(evaluator.evaluate('5 > 3', ctx).value).toBe(true);
+      expect(evaluator.evaluate('1 == 1', ctx).value).toBe(true);
+    });
+
+    it('ternary works normally', () => {
+      expect(evaluator.evaluate("true ? 'yes' : 'no'", ctx).value).toBe('yes');
+    });
+
+    it('nested function calls work', () => {
+      expect(evaluator.evaluate('add(multiply(2, 3), 4)', ctx).value).toBe(10);
+    });
+
+    it('logical operators work', () => {
+      expect(evaluator.evaluate('true && false', ctx).value).toBe(false);
+      expect(evaluator.evaluate('true || false', ctx).value).toBe(true);
+      expect(evaluator.evaluate('!false', ctx).value).toBe(true);
+    });
+
+    it('path resolution works', () => {
+      expect(evaluator.evaluate('state_data.title', ctx).value).toBe('Test');
+      expect(evaluator.evaluate('current_state', ctx).value).toBe('active');
+    });
+
+    it('string literals work', () => {
+      expect(evaluator.evaluate("'hello'", ctx).value).toBe('hello');
+      expect(evaluator.evaluate('"world"', ctx).value).toBe('world');
+    });
+
+    it('templates still work', () => {
+      const r = evaluator.evaluateTemplate('State: {{current_state}}', ctx);
+      expect(r.value).toBe('State: active');
+    });
+  });
+});