anear-js-api 2.2.1 → 2.3.1

package/README.md

@@ -77,7 +77,7 @@ The AppM developer is responsible for everything related to the specific event's
 
 - **Game/Event Logic:** Controls the flow, rules, and state of the interactive event.
 - **User Experience (UX/UI):** Defines what the user sees at every stage via `meta` display properties in its state nodes. All display content is the AppM's responsibility.
-- **Decision Maker:** The AppM is the decision-maker. When the JSAPI notifies it of an event (e.g., "a participant timed out"), the AppM decides what to do. Should the game end? Should the participant be removed? Should the state change? That is application-level logic.
+- **Decision Maker:** The AppM is the decision-maker. When the JSAPI notifies it of an event (e.g., an `ACTION`/`ACTIONS_TIMEOUT`), the AppM decides what to do. Should the game end? Should the participant be removed? Should the state change? That is application-level logic.
 
 This strict separation allows AppM developers to focus entirely on their application logic without needing to manage the complexities of real-time infrastructure.
 
@@ -169,6 +169,36 @@ Your AppM state names are completely independent of these AEM states. You can st
 2. **Action Events**: Participant clicks → `actionsChannel` → App logic
 3. **Display Events**: App state transitions → `AppMachineTransition` → Channel rendering
 
+## Action Payload Tokenization
+
+JSAPI tokenizes `anear-action` payloads for participant-private displays to prevent client-side payload inspection/tampering.
+
+### Render-time behavior
+
+- App templates still use `action(...)` in Pug.
+- For private participant renders, `DisplayEventProcessor` replaces action JSON with short opaque tokens.
+- JSAPI stores an ephemeral lookup map per participant and render cycle:
+  - `participantActionLookup[participantId][token] = { APP_EVENT: payload }`
+- The lookup map is replaced on each render cycle.
+
+### Action-ingest behavior (AEM)
+
+When an `ACTION` is received on the actions channel:
+
+1. AEM tries token resolution from `participantActionLookup`.
+2. If token lookup fails, AEM accepts JSON payloads marked as trusted ABR client payloads (`__anearClient: true`, forms also include `__anearForm: true`).
+3. Any unrecognized/unmarked payload is dropped and not forwarded to AppM.
+
+### Forms
+
+`anear-form` submissions remain JSON-based (they carry user-entered values). ABR marks form payloads with `__anearForm: true` and `__anearClient: true`; AEM strips these markers before forwarding payload to AppM.
+
+### Security model
+
+- Tokenized button actions remove app-specific payload details from client-visible markup.
+- Forged/replayed unknown tokens are rejected by default.
+- AppM guards are still required for domain correctness (turn validity, ownership checks, ranges, etc.).
+
 ## Participant Presence Events
 
 The JSAPI handles participant lifecycle through presence events:
@@ -196,7 +226,7 @@ meta: {
   allParticipants: 'TemplateName',           // String template name
   spectators: 'TemplateName',                 // String template name
   
-  // Object format with timeout
+  // Object format (timeout metadata is legacy; prefer <anear-timeout> in PUG for participant-local UX)
   eachParticipant: { 
     view: 'TemplateName', 
     timeout: (appContext, participantId) => 30000,
@@ -231,21 +261,12 @@ PUG templates receive rich context including:
 
 ### Participant-local Timeouts
 
-Participant-local timeout UX is handled by browser runtime (`<anear-timeout>`). JSAPI does not emit `PARTICIPANT_TIMEOUT`.
+Participant-local timeout UX is handled by browser runtime (`<anear-timeout>`). JSAPI does not emit `PARTICIPANT_TIMEOUT`; timeout-driven actions should arrive as normal `ACTION` payloads (for example `ACTION_TIMEOUT` if your app uses that event name).
 
-```javascript
-meta: {
-  eachParticipant: {
-    view: 'PlayableGameBoard',
-    timeout: (context, participant) => {
-      // Only current player gets timeout
-      return context.currentPlayerId === participant.info.id ? 30000 : null
-    }
-  }
-},
-on: {
-  MOVE: 'nextTurn'
-}
+```pug
+//- Active player's controls wrapped with browser-owned timeout UX
+anear-timeout(duration='30000')
+  anear-action(payload=action("MOVE")) Move
 ```
 
 ### Group Timeouts
@@ -328,8 +349,8 @@ await anearEvent.startEvent()     // Transition to live
 await anearEvent.closeEvent()     // Transition to complete
 await anearEvent.cancelEvent()    // Transition to cancelled
 
-// Participant timeout management
-anearEvent.cancelAllParticipantTimeouts()  // Cancel all active timeouts
+// allParticipants timeout management
+anearEvent.cancelAllParticipantsTimeout()  // Cancel active allParticipants timeout orchestration
 ```
 
 ## XState Integration

package/lib/models/AnearEvent.js

@@ -110,10 +110,14 @@ class AnearEvent extends JsonApiResource {
     this.send({ type: "BOOT_PARTICIPANT", data: { participantId, reason } })
   }
 
-  cancelAllParticipantTimeouts() {
+  cancelAllParticipantsTimeout() {
     // Cancels active allParticipants timeout tracking in AEM.
-    // Participant-local timeout ownership now lives in the browser runtime.
-    this.send({ type: "CANCEL_ALL_PARTICIPANT_TIMEOUTS" })
+    this.send({ type: "CANCEL_ALL_PARTICIPANTS_TIMEOUT" })
+  }
+
+  // Backward-compatible alias (legacy misspelling/wording).
+  cancelAllParticipantTimeouts() {
+    this.cancelAllParticipantsTimeout()
   }
 
   render(viewPath, displayType, appContext, event, timeout = null, props = {}) {

package/lib/state_machines/AnearEventMachine.js

@@ -132,6 +132,61 @@ const getPresenceEventName = (participant, presenceAction) => {
   return `${role}_${presenceAction}`;
 };
 
+/**
+ * ACTION payload tokenization contract
+ * -----------------------------------
+ * - For participant-private displays, DisplayEventProcessor tokenizes anear-action payloads:
+ *   participantActionLookup[participantId][token] = { APP_EVENT_NAME: payloadObject }
+ * - Incoming ACTION messages are first resolved by token lookup.
+ * - Raw JSON payloads are accepted when ABR marks them as trusted client payloads
+ *   (for example forms and web-component actions).
+ * - Unknown/unmarked payloads are dropped (not forwarded to AppM).
+ */
+const FORM_PAYLOAD_MARKER = '__anearForm'
+const CLIENT_PAYLOAD_MARKER = '__anearClient'
+const TRUSTED_CLIENT_PAYLOAD_MARKERS = [FORM_PAYLOAD_MARKER, CLIENT_PAYLOAD_MARKER]
+
+const parseActionEnvelopeObject = (payloadObject) => {
+  if (!payloadObject || typeof payloadObject !== 'object' || Array.isArray(payloadObject)) return null
+  const entries = Object.entries(payloadObject)
+  if (entries.length < 1) return null
+  const [appEventName, payload] = entries[0]
+  if (!appEventName || typeof appEventName !== 'string') return null
+  return { appEventName, payload: payload ?? {} }
+}
+
+const parseActionEnvelope = (rawPayload) => {
+  if (rawPayload && typeof rawPayload === 'object') {
+    return parseActionEnvelopeObject(rawPayload)
+  }
+  if (typeof rawPayload !== 'string') return null
+  try {
+    return parseActionEnvelopeObject(JSON.parse(rawPayload))
+  } catch (_e) {
+    return null
+  }
+}
+
+const resolveIncomingActionEnvelope = (context, participantId, rawPayload) => {
+  const participantLookup = context.participantActionLookup?.[participantId]
+  if (participantLookup && typeof rawPayload === 'string' && participantLookup[rawPayload]) {
+    const parsed = parseActionEnvelopeObject(participantLookup[rawPayload])
+    if (!parsed) return null
+    return { ...parsed, source: 'token' }
+  }
+
+  const parsed = parseActionEnvelope(rawPayload)
+  if (!parsed) return null
+  const payload = parsed.payload
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) return null
+  const hasTrustedMarker = TRUSTED_CLIENT_PAYLOAD_MARKERS.some(marker => payload[marker] === true)
+  if (!hasTrustedMarker) return null
+
+  const cleanedPayload = { ...payload }
+  TRUSTED_CLIENT_PAYLOAD_MARKERS.forEach(marker => delete cleanedPayload[marker])
+  return { appEventName: parsed.appEventName, payload: cleanedPayload, source: 'client' }
+}
+
 const RealtimeMessaging = require('../utils/RealtimeMessaging')
 const EventStats = require('../utils/EventStats')
 const AppMachineTransition = require('../utils/AppMachineTransition')
@@ -195,7 +250,8 @@ const AnearEventMachineContext = (
   participantPrivateChannels: {},
   exitedParticipantPrivateChannels: [],
   participantsActionTimeout: null,
-  eachParticipantCancelActionType: null,  // ACTION type that triggers cancellation for eachParticipant timeouts
+  participantActionLookup: {}, // Per-render ephemeral action token lookup by participant ID.
+  eachParticipantCancelActionType: null,  // ACTION type that can cancel active allParticipants timeout orchestration
   pendingCancelAction: null,  // ACTION to forward after cancellation completes: { participantId, appEventName, payload }
   consecutiveTimeoutCount: 0,  // Global counter tracking consecutive timeouts across all participants for dead-man switch
   consecutiveAllParticipantsTimeoutCount: 0,  // Counter tracking consecutive allParticipants timeouts where ALL participants timed out
@@ -524,8 +580,12 @@ const ActiveEventStatesConfig = {
         BOOT_PARTICIPANT: {
           actions: 'sendBootEventToParticipant'
         },
+        CANCEL_ALL_PARTICIPANTS_TIMEOUT: {
+          actions: 'cancelAllParticipantsTimeout'
+        },
+        // Backward-compatible alias.
         CANCEL_ALL_PARTICIPANT_TIMEOUTS: {
-          actions: 'cancelAllParticipantTimeouts'
+          actions: 'cancelAllParticipantsTimeout'
         },
         SPECTATOR_ENTER: {
           actions: 'sendSpectatorEnterToAppEventMachine'
@@ -651,6 +711,8 @@ const ActiveEventStatesConfig = {
         BOOT_PARTICIPANT: {
           actions: 'sendBootEventToParticipant'
         },
+        CANCEL_ALL_PARTICIPANTS_TIMEOUT: {},
+        // Backward-compatible alias.
         CANCEL_ALL_PARTICIPANT_TIMEOUTS: {}
       },
       states: {
@@ -683,6 +745,8 @@ const ActiveEventStatesConfig = {
             ACTION: {
               actions: ['resetParticipantTimeoutCount', 'processParticipantAction']
             },
+            CANCEL_ALL_PARTICIPANTS_TIMEOUT: {},
+            // Backward-compatible alias.
             CANCEL_ALL_PARTICIPANT_TIMEOUTS: {}
           }
         },
@@ -779,20 +843,30 @@ const ActiveEventStatesConfig = {
                 guard: ({ context, event }) => {
                   const { cancelActionType } = context.participantsActionTimeout || {}
                   if (!cancelActionType) return false
-                  const eventMessagePayload = JSON.parse(event.data.payload)
-                  const [appEventName] = Object.entries(eventMessagePayload)[0]
+                  const actionEnvelope = resolveIncomingActionEnvelope(context, event.data.participantId, event.data.payload)
+                  if (!actionEnvelope) return false
+                  const { appEventName } = actionEnvelope
                   return cancelActionType === appEventName
                 },
                 actions: ['storeCancelActionForAllParticipants'],
                 target: 'handleParticipantsTimeoutCanceled'
               },
               {
+                guard: 'isRecognizedActionPayload',
                 actions: ['resetParticipantTimeoutCount', 'processAndForwardAction', 'processParticipantResponse'],
                 // v5 note: internal transitions are the default (v4 had `internal: true`)
+              },
+              {
+                actions: ['logDroppedUnrecognizedAction']
               }
             ],
+            CANCEL_ALL_PARTICIPANTS_TIMEOUT: {
+              actions: ['cancelAllParticipantsTimeout'],
+              target: 'handleParticipantsTimeoutCanceled'
+            },
+            // Backward-compatible alias.
             CANCEL_ALL_PARTICIPANT_TIMEOUTS: {
-              actions: ['cancelAllParticipantTimeouts'],
+              actions: ['cancelAllParticipantsTimeout'],
               target: 'handleParticipantsTimeoutCanceled'
             },
             RENDER_DISPLAY: {
@@ -1396,7 +1470,18 @@ const AnearEventMachineFunctions = ({
     }),
     setLastRenderResult: assign(({ event }) => {
       const output = event?.output ?? event?.data
-      return { lastRenderResult: output && typeof output === 'object' ? output : null }
+      if (!output || typeof output !== 'object') {
+        return {
+          lastRenderResult: null,
+          participantActionLookup: {}
+        }
+      }
+      return {
+        lastRenderResult: output,
+        participantActionLookup: output.participantActionLookup && typeof output.participantActionLookup === 'object'
+          ? output.participantActionLookup
+          : {}
+      }
     }),
     notifyAppMachineRendered: ({ context }) => {
       if (context.appEventMachine) {
@@ -1772,7 +1857,7 @@ const AnearEventMachineFunctions = ({
         participantPrivateChannels: context.participantPrivateChannels
       }
     }),
-    cancelAllParticipantTimeouts: assign(() => ({
+    cancelAllParticipantsTimeout: assign(() => ({
       participantsActionTimeout: null,
       pendingCancelAction: null
     })),
@@ -1789,7 +1874,7 @@ const AnearEventMachineFunctions = ({
       }
     }),
     setupPendingCancelConfirmationsForManualCancel: assign(({ context }) => {
-      // Get all active participants (for manual cancelAllParticipantTimeouts call)
+      // Get all active participants (for manual cancelAllParticipantsTimeout call)
       const activeParticipantIds = getActiveParticipantIds(context)
       const pendingConfirmations = new Set(activeParticipantIds)
 
@@ -1835,7 +1920,7 @@ const AnearEventMachineFunctions = ({
         null
 
       if (cancelActionType) {
-        logger.debug(`[AEM] Setting up cancel action type for eachParticipant timeout: ${cancelActionType}`)
+        logger.debug(`[AEM] Setting up cancel action type for allParticipants timeout orchestration: ${cancelActionType}`)
       }
 
       return {
@@ -1869,14 +1954,22 @@ const AnearEventMachineFunctions = ({
       }
       return updates
     }),
+    logDroppedUnrecognizedAction: ({ context, event }) => {
+      const participantId = event?.data?.participantId
+      logger.warn(`[AEM] Event ${context.anearEvent.id} dropping ACTION with unrecognized payload from participantId=${participantId}`)
+    },
     processParticipantAction: ({ context, event }) => {
       // event.data.participantId,
       // event.data.payload: {"appEventMachineACTION": {action event keys and values}}
       //   e.g.  {"MOVE":{"x":1, "y":2}}
       // send to the ParticipantMachine to handle state of participant (idle, active, timed-out, etc)
       const participantId = event.data.participantId
-      const eventMessagePayload = JSON.parse(event.data.payload) // { eventName: {eventObject} }
-      const [appEventName, payload] = Object.entries(eventMessagePayload)[0]
+      const actionEnvelope = resolveIncomingActionEnvelope(context, participantId, event.data.payload)
+      if (!actionEnvelope) {
+        logger.warn(`[AEM] Event ${context.anearEvent.id} dropping ACTION with unrecognized payload from participantId=${participantId}`)
+        return
+      }
+      const { appEventName, payload } = actionEnvelope
       const participantName = getParticipantName(context, participantId)
 
       logger.info(`[AEM] Event ${context.anearEvent.id} ACTION participantId=${participantId} name=${participantName} action=${appEventName}`)
@@ -1894,8 +1987,12 @@ const AnearEventMachineFunctions = ({
       const { nonResponders } = context.participantsActionTimeout;
 
       // Forward to AppM with the finalAction flag
-      const eventMessagePayload = JSON.parse(event.data.payload);
-      const [appEventName, payload] = Object.entries(eventMessagePayload)[0];
+      const actionEnvelope = resolveIncomingActionEnvelope(context, participantId, event.data.payload)
+      if (!actionEnvelope) {
+        logger.warn(`[AEM] Event ${context.anearEvent.id} dropping ACTION with unrecognized payload from participantId=${participantId}`)
+        return
+      }
+      const { appEventName, payload } = actionEnvelope
       const participantName = getParticipantName(context, participantId);
 
       logger.info(`[AEM] Event ${context.anearEvent.id} ACTION participantId=${participantId} name=${participantName} action=${appEventName}`)
@@ -1918,8 +2015,12 @@ const AnearEventMachineFunctions = ({
     },
     storeCancelActionForAllParticipants: assign(({ context, event }) => {
       const participantId = event.data.participantId
-      const eventMessagePayload = JSON.parse(event.data.payload)
-      const [appEventName, payload] = Object.entries(eventMessagePayload)[0]
+      const actionEnvelope = resolveIncomingActionEnvelope(context, participantId, event.data.payload)
+      if (!actionEnvelope) {
+        logger.warn(`[AEM] Event ${context.anearEvent.id} dropping cancel ACTION with unrecognized payload from participantId=${participantId}`)
+        return {}
+      }
+      const { appEventName, payload } = actionEnvelope
       const participantName = getParticipantName(context, participantId)
 
       logger.info(`[AEM] Event ${context.anearEvent.id} intercepting cancel ACTION ${appEventName} from participantId=${participantId} name=${participantName} (allParticipants timeout)`)
@@ -2592,6 +2693,10 @@ const AnearEventMachineFunctions = ({
       const isTimeoutAlreadyRunning = context.participantsActionTimeout !== null;
       return isStartingNewTimeout || isTimeoutAlreadyRunning;
     },
+    isRecognizedActionPayload: ({ context, event }) => {
+      const participantId = event?.data?.participantId
+      return !!resolveIncomingActionEnvelope(context, participantId, event?.data?.payload)
+    },
     allParticipantsResponded: ({ context }) => {
       return context.participantsActionTimeout && context.participantsActionTimeout.nonResponders.size === 0
     },

package/lib/utils/Constants.js

@@ -17,7 +17,8 @@ module.exports = {
     BOOT_EXIT: 2 * 1000 // 5 seconds
   },
   DEAD_MAN_SWITCH: {
-    // Maximum consecutive timeouts per participant before auto-canceling event
+    // Maximum consecutive allParticipants timeouts (where everyone timed out)
+    // before auto-canceling the event.
     MAX_CONSECUTIVE_PARTICIPANT_TIMEOUTS: 4
   },
   EventStates: {

package/lib/utils/DisplayEventProcessor.js

@@ -42,6 +42,7 @@ const logger = require('./Logger')
 const RealtimeMessaging = require('./RealtimeMessaging')
 const EventStats = require('./EventStats')
 const C = require('./Constants')
+const { randomBytes } = require('crypto')
 
 class DisplayEventProcessor {
   constructor(anearEventMachineContext) {
@@ -56,6 +57,9 @@ class DisplayEventProcessor {
     this.participants = anearEventMachineContext.participants
     this.participantsIndex = this._buildParticipantsIndex(anearEventMachineContext.participants)
     this.eventStats = anearEventMachineContext.eventStats ?? null
+    // Ephemeral map generated per render batch:
+    // { [participantId]: { [token]: { APP_EVENT: payloadObject } } }
+    this.participantActionLookup = {}
   }
 
   processAndPublish(displayEvents, cancelActionType = null) {
@@ -92,10 +96,54 @@ class DisplayEventProcessor {
     })
 
     return Promise.all(publishPromises).then(() => {
-      return { participantsTimeout, cancelActionType, anyDisplaySent }
+      return {
+        participantsTimeout,
+        cancelActionType,
+        anyDisplaySent,
+        participantActionLookup: this.participantActionLookup
+      }
     })
   }
 
+  _normalizeActionPayload(payload) {
+    if (typeof payload === 'string') {
+      return { [payload]: {} }
+    }
+    if (typeof payload === 'object' && payload !== null) {
+      return payload
+    }
+    throw new Error("Invalid payload for action(): must be a string or an object.")
+  }
+
+  _createActionToken(existingTokens) {
+    // 6 random bytes encoded as base64url produce 8 chars.
+    for (let i = 0; i < 6; i += 1) {
+      const token = randomBytes(6).toString('base64url')
+      if (!existingTokens[token]) return token
+    }
+    // Extremely unlikely fallback on repeated collisions.
+    return randomBytes(9).toString('base64url')
+  }
+
+  _encodeParticipantActionPayload(participantId, payload) {
+    const normalizedPayload = this._normalizeActionPayload(payload)
+    if (!this.participantActionLookup[participantId]) {
+      this.participantActionLookup[participantId] = {}
+    }
+    const participantLookup = this.participantActionLookup[participantId]
+    const token = this._createActionToken(participantLookup)
+    participantLookup[token] = normalizedPayload
+    return token
+  }
+
+  _buildPugHelpersForParticipant(participantId) {
+    if (!participantId) return this.pugHelpers
+    return {
+      ...this.pugHelpers,
+      action: (payload) => this._encodeParticipantActionPayload(participantId, payload)
+    }
+  }
+
   _buildParticipantsIndex(participants) {
     const participantStructs = Object.fromEntries(
       Object.entries(participants).map(([id, info]) => [ id, { info, context: null } ])
@@ -414,7 +462,8 @@ class DisplayEventProcessor {
     }
     const privateRenderContext = {
       ...templateRenderContext,
-      participant: participantStruct
+      participant: participantStruct,
+      ...this._buildPugHelpersForParticipant(participantId)
     }
 
     let visualTimeout = null

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "anear-js-api",
-  "version": "2.2.1",
+  "version": "2.3.1",
   "description": "Javascript Developer API for Anear Apps",
   "main": "lib/index.js",
   "scripts": {

package/tests/DisplayEventProcessor.test.js

@@ -10,7 +10,10 @@ const makeProcessor = (overrides = {}) => {
     anearEvent: {},
     participantsActionTimeout: null,
     pugTemplates: {},
-    pugHelpers: {},
+    pugHelpers: {
+      action: (payload) => JSON.stringify(payload),
+      cdnImg: (filename) => `https://cdn.example/${filename}`
+    },
     participantPrivateChannels: { p1: 'private-channel-p1' },
     participantsDisplayChannel: 'participants-channel',
     spectatorsDisplayChannel: null,
@@ -98,3 +101,60 @@ describe('DisplayEventProcessor anchor updates', () => {
   })
 })
 
+describe('DisplayEventProcessor secure action tokens', () => {
+  beforeEach(() => {
+    jest.clearAllMocks()
+  })
+
+  test('encodes participant anear-action payloads into ephemeral tokens', async () => {
+    const { processor } = makeProcessor({
+      pugTemplates: {
+        'board.pug': (ctx) => `<anear-action payload="${ctx.action({ PLAY_CARD: { cardId: 'c1' } })}">PLAY</anear-action>`
+      }
+    })
+
+    const result = await processor.processAndPublish([
+      {
+        viewPath: 'board',
+        appRenderContext: { app: {}, meta: { viewer: 'eachParticipant', timeoutFn: null } },
+        viewer: 'eachParticipant',
+        participantId: 'p1',
+        props: {}
+      }
+    ])
+
+    expect(RealtimeMessaging.publish).toHaveBeenCalledTimes(1)
+    const [, , payload] = RealtimeMessaging.publish.mock.calls[0]
+    const html = payload.content
+    const tokenMatch = html.match(/payload="([^"]+)"/)
+    expect(tokenMatch).toBeTruthy()
+    const token = tokenMatch[1]
+    expect(token).toMatch(/^[A-Za-z0-9_-]{8,12}$/)
+
+    expect(result.participantActionLookup.p1[token]).toEqual({
+      PLAY_CARD: { cardId: 'c1' }
+    })
+  })
+
+  test('keeps allParticipants action helper backward-compatible with JSON payloads', async () => {
+    const { processor } = makeProcessor({
+      pugTemplates: {
+        'public_view.pug': (ctx) => `<anear-action payload="${ctx.action({ PLAY: {} })}">PLAY</anear-action>`
+      }
+    })
+
+    const result = await processor.processAndPublish([
+      {
+        viewPath: 'public_view',
+        appRenderContext: { app: {}, meta: { viewer: 'allParticipants', timeoutFn: null } },
+        viewer: 'allParticipants',
+        props: {}
+      }
+    ])
+
+    const [, , payload] = RealtimeMessaging.publish.mock.calls[0]
+    expect(payload.content).toMatch(/payload=".*PLAY.*"/)
+    expect(result.participantActionLookup).toEqual({})
+  })
+})
+