anear-js-api 2.2.0 → 2.3.0

package/lib/state_machines/AnearEventMachine.js

@@ -132,6 +132,48 @@ const getPresenceEventName = (participant, presenceAction) => {
   return `${role}_${presenceAction}`;
 };
 
+const FORM_PAYLOAD_MARKER = '__anearForm'
+
+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
+  if (payload[FORM_PAYLOAD_MARKER] !== true) return null
+
+  const cleanedPayload = { ...payload }
+  delete cleanedPayload[FORM_PAYLOAD_MARKER]
+  return { appEventName: parsed.appEventName, payload: cleanedPayload, source: 'form' }
+}
+
 const RealtimeMessaging = require('../utils/RealtimeMessaging')
 const EventStats = require('../utils/EventStats')
 const AppMachineTransition = require('../utils/AppMachineTransition')
@@ -195,6 +237,7 @@ const AnearEventMachineContext = (
   participantPrivateChannels: {},
   exitedParticipantPrivateChannels: [],
   participantsActionTimeout: null,
+  participantActionLookup: {}, // Per-render ephemeral action token lookup by participant ID.
   eachParticipantCancelActionType: null,  // ACTION type that triggers cancellation for eachParticipant timeouts
   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
@@ -240,15 +283,19 @@ const ActiveEventStatesConfig = {
           invoke: {
             src: 'getAttachedCreatorOrHost',
             input: ({ context, event }) => ({ context, event }),
-            onDone: {
-              // v5 note: onDone of a fromPromise actor provides the resolved value on `event.output`.
-              // event.output.anearParticipant will be null if no presence enter
-              // was available on actions channel via get().  We must wait for
-              // the undeferred PARTICIPANT_ENTER instead.  But if get() DID
-              // return the creator presence, register the participant and continue.
-              actions: ['startNewParticipantSession', 'sendEnterToAppMachine'],
-              target: '#eventCreated'
-            },
+            onDone: [
+              {
+                // If actions-channel presence.get() found creator/host, register now.
+                guard: 'hasAttachedCreatorOrHost',
+                actions: ['startNewParticipantSession', 'sendEnterToAppMachine'],
+                target: '#eventCreated'
+              },
+              {
+                // No creator/host found yet via presence.get(); wait for PARTICIPANT_ENTER.
+                actions: ['logWaitingForCreatorPresence'],
+                target: '#waiting'
+              }
+            ],
             onError: {
               target: '#failure'
             }
@@ -775,8 +822,9 @@ 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'],
@@ -1392,7 +1440,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) {
@@ -1871,8 +1930,12 @@ const AnearEventMachineFunctions = ({
       //   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}`)
@@ -1890,8 +1953,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}`)
@@ -1914,8 +1981,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)`)
@@ -2143,6 +2214,7 @@ const AnearEventMachineFunctions = ({
       context.coreServiceMachine.send({ type: 'EVENT_MACHINE_EXIT', eventId: context.anearEvent.id })
     },
     logCreatorEnter: ({ event }) => logger.debug("[AEM] got creator PARTICIPANT_ENTER: ", event.data.id),
+    logWaitingForCreatorPresence: ({ context }) => logger.debug(`[AEM] Event ${context.anearEvent.id} creator/host not found via actions presence.get(); waiting for PARTICIPANT_ENTER`),
     logAPMReady: () => logger.debug('[AEM] participant session registered'),
     logInvalidParticipantEnter: ({ context, event }) => logger.info(`[AEM] Event ${context.anearEvent.id} unexpected PARTICIPANT_ENTER participantId=${event.data.id}`),
     logDeferringAppmFinal: ({ context }) => logger.info(`[AEM] Event ${context.anearEvent.id} deferring APPM_FINAL (already transitioning to terminated)`),
@@ -2533,6 +2605,10 @@ const AnearEventMachineFunctions = ({
     })
   },
   guards: {
+    hasAttachedCreatorOrHost: ({ event }) => {
+      const anearParticipant = event?.output?.anearParticipant ?? event?.data?.anearParticipant
+      return !!anearParticipant
+    },
     isReconnectUpdate: ({ context, event }) => {
       // participant exists and event.data.type is undefined
       return context.participants[event.data.id] && !event.data.type

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.0",
+  "version": "2.3.0",
   "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({})
+  })
+})
+