anear-js-api 2.3.0 → 2.3.2

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,7 +132,19 @@ 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
@@ -167,11 +179,12 @@ const resolveIncomingActionEnvelope = (context, participantId, rawPayload) => {
   if (!parsed) return null
   const payload = parsed.payload
   if (!payload || typeof payload !== 'object' || Array.isArray(payload)) return null
-  if (payload[FORM_PAYLOAD_MARKER] !== true) return null
+  const hasTrustedMarker = TRUSTED_CLIENT_PAYLOAD_MARKERS.some(marker => payload[marker] === true)
+  if (!hasTrustedMarker) return null
 
   const cleanedPayload = { ...payload }
-  delete cleanedPayload[FORM_PAYLOAD_MARKER]
-  return { appEventName: parsed.appEventName, payload: cleanedPayload, source: 'form' }
+  TRUSTED_CLIENT_PAYLOAD_MARKERS.forEach(marker => delete cleanedPayload[marker])
+  return { appEventName: parsed.appEventName, payload: cleanedPayload, source: 'client' }
 }
 
 const RealtimeMessaging = require('../utils/RealtimeMessaging')
@@ -238,7 +251,7 @@ const AnearEventMachineContext = (
   exitedParticipantPrivateChannels: [],
   participantsActionTimeout: null,
   participantActionLookup: {}, // Per-render ephemeral action token lookup by participant ID.
-  eachParticipantCancelActionType: null,  // ACTION type that triggers cancellation for eachParticipant timeouts
+  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
@@ -567,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'
@@ -694,6 +711,8 @@ const ActiveEventStatesConfig = {
         BOOT_PARTICIPANT: {
           actions: 'sendBootEventToParticipant'
         },
+        CANCEL_ALL_PARTICIPANTS_TIMEOUT: {},
+        // Backward-compatible alias.
         CANCEL_ALL_PARTICIPANT_TIMEOUTS: {}
       },
       states: {
@@ -726,6 +745,8 @@ const ActiveEventStatesConfig = {
             ACTION: {
               actions: ['resetParticipantTimeoutCount', 'processParticipantAction']
             },
+            CANCEL_ALL_PARTICIPANTS_TIMEOUT: {},
+            // Backward-compatible alias.
             CANCEL_ALL_PARTICIPANT_TIMEOUTS: {}
           }
         },
@@ -831,12 +852,21 @@ const ActiveEventStatesConfig = {
                 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: {
@@ -1438,19 +1468,31 @@ const AnearEventMachineFunctions = ({
         return { ...s, liveDurationMs: (s.liveDurationMs || 0) + add, liveStartedAt: null }
       }
     }),
-    setLastRenderResult: assign(({ event }) => {
+    setLastRenderResult: assign(({ context, event }) => {
       const output = event?.output ?? event?.data
       if (!output || typeof output !== 'object') {
         return {
           lastRenderResult: null,
-          participantActionLookup: {}
+          participantActionLookup: context.participantActionLookup || {}
         }
       }
-      return {
-        lastRenderResult: output,
-        participantActionLookup: output.participantActionLookup && typeof output.participantActionLookup === 'object'
+      const incomingLookup =
+        output.participantActionLookup && typeof output.participantActionLookup === 'object'
           ? output.participantActionLookup
           : {}
+      // Merge token maps by participant so a selective/private re-render does not
+      // invalidate untouched participants' existing action tokens.
+      // For participants present in this render batch, replace their token map
+      // atomically with the fresh map generated during render.
+      const participantActionLookup = {
+        ...(context.participantActionLookup || {}),
+      }
+      Object.keys(incomingLookup).forEach((participantId) => {
+        participantActionLookup[participantId] = incomingLookup[participantId]
+      })
+      return {
+        lastRenderResult: output,
+        participantActionLookup
       }
     }),
     notifyAppMachineRendered: ({ context }) => {
@@ -1827,7 +1869,7 @@ const AnearEventMachineFunctions = ({
         participantPrivateChannels: context.participantPrivateChannels
       }
     }),
-    cancelAllParticipantTimeouts: assign(() => ({
+    cancelAllParticipantsTimeout: assign(() => ({
       participantsActionTimeout: null,
       pendingCancelAction: null
     })),
@@ -1844,7 +1886,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)
 
@@ -1890,7 +1932,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 {
@@ -1924,6 +1966,10 @@ 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}}
@@ -2659,6 +2705,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/package.json

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