chore: add external policy example by marcos-cereijo-pexip · Pull Request #36 · pexip/webapp3-plugin-interpretation

marcos-cereijo-pexip · 2026-04-22T14:40:24Z

Closes #35

Copilot

Pull request overview

Adds a self-contained “external policy” Node.js example that mirrors the repository’s local policy logic, addressing Issue #35.

Changes:

Introduces an Express-based external policy server with service configuration and participant properties endpoints.
Implements WebCrypto-based hashing helpers to support deterministic/dynamic PIN generation.
Adds standalone example packaging/docs and excludes the example directory from root ESLint scanning.

Reviewed changes

Copilot reviewed 6 out of 7 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
external-policy-example/src/policy.mjs	Implements policy decision logic for routing and dynamic PIN derivation.
external-policy-example/src/index.mjs	Express server exposing the external policy endpoints.
external-policy-example/src/hash.mjs	WebCrypto-based `pex_hash`/`pex_tail` equivalents used by the example.
external-policy-example/package.json	Defines the example’s Node.js package and Express dependency.
external-policy-example/package-lock.json	Locks dependency versions for the example package.
external-policy-example/README.md	Documents endpoints, routing behavior, and setup instructions.
eslint.config.js	Adds `external-policy-example` to ESLint ignore list.

Files not reviewed (1)

external-policy-example/package-lock.json: Language not supported

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-22T14:46:08Z

+  const response = await handleParticipantProperties(localAlias, remoteDisplayName, vendor)
+
+  console.log(
+    `[participant] local_alias=${localAlias} remote_display_name=${remoteDisplayName ?? ''} → call_tag=${response.result.call_tag ?? '(none)'}`


The log line dereferences response.result.call_tag, but handleParticipantProperties can return a response without a result field. This will throw at runtime for non-main-room aliases. Use optional chaining (response.result?.call_tag) or ensure the policy handler always includes result: {}.

Suggested change

`[participant] local_alias=${localAlias} remote_display_name=${remoteDisplayName ?? ''} → call_tag=${response.result.call_tag ?? '(none)'}`

`[participant] local_alias=${localAlias} remote_display_name=${remoteDisplayName ?? ''} → call_tag=${response.result?.call_tag ?? '(none)'}`

Copilot · 2026-04-22T14:46:09Z

+  const { local_alias: localAlias, remote_display_name: remoteDisplayName, vendor } = req.query
+
+  const response = await handleServiceConfiguration(localAlias, remoteDisplayName, vendor)
+
+  console.log(
+    `[service-config] local_alias=${localAlias} → action=${response.action}, result=${JSON.stringify(response.result)}`
+  )
+
+  return res.json(response)
+})
+
+app.get('/policy/v1/participant/properties', async (req, res) => {
+  const {local_alias: localAlias, remote_display_name: remoteDisplayName, vendor } = req.query
+
+  const response = await handleParticipantProperties(localAlias, remoteDisplayName, vendor)
+
+  console.log(
+    `[participant] local_alias=${localAlias} remote_display_name=${remoteDisplayName ?? ''} → call_tag=${response.result.call_tag ?? '(none)'}`
+
+
+  )
+
+  return res.json(response)


These route handlers are async and can throw/reject (e.g., hashing failures). In Express 4, rejected promises in route handlers are not reliably forwarded to error middleware, which can lead to unhandled rejections and no HTTP response. Wrap the handler body in try/catch and return a 5xx (or call next(err) with an error-handling middleware).

Suggested change

const { local_alias: localAlias, remote_display_name: remoteDisplayName, vendor } = req.query

const response = await handleServiceConfiguration(localAlias, remoteDisplayName, vendor)

console.log(

`[service-config] local_alias=${localAlias} → action=${response.action}, result=${JSON.stringify(response.result)}`

)

return res.json(response)

})

app.get('/policy/v1/participant/properties', async (req, res) => {

const {local_alias: localAlias, remote_display_name: remoteDisplayName, vendor } = req.query

const response = await handleParticipantProperties(localAlias, remoteDisplayName, vendor)

console.log(

`[participant] local_alias=${localAlias} remote_display_name=${remoteDisplayName ?? ''} → call_tag=${response.result.call_tag ?? '(none)'}`

)

return res.json(response)

try {

const { local_alias: localAlias, remote_display_name: remoteDisplayName, vendor } = req.query

const response = await handleServiceConfiguration(localAlias, remoteDisplayName, vendor)

console.log(

`[service-config] local_alias=${localAlias} → action=${response.action}, result=${JSON.stringify(response.result)}`

)

return res.json(response)

} catch (error) {

console.error('[service-config] request failed', error)

return res.status(500).json({ error: 'Internal Server Error' })

}

})

app.get('/policy/v1/participant/properties', async (req, res) => {

try {

const {local_alias: localAlias, remote_display_name: remoteDisplayName, vendor } = req.query

const response = await handleParticipantProperties(localAlias, remoteDisplayName, vendor)

console.log(

`[participant] local_alias=${localAlias} remote_display_name=${remoteDisplayName ?? ''} → call_tag=${response.result.call_tag ?? '(none)'}`

)

return res.json(response)

} catch (error) {

console.error('[participant] request failed', error)

return res.status(500).json({ error: 'Internal Server Error' })

}

Copilot · 2026-04-22T14:46:09Z

+      const callTag = pexTail(
+        await pexHash(SECRET + mainRoomAlias + cleanVendor + cleanDisplayName),
+        20
+      )
+      pin = pexTail(await pexHash(callTag + 'interpreter'), 20)
+      guestPin = pexTail(await pexHash(callTag + 'listener'), 20)
+    }


pexHash can return undefined on error, but the result is passed into pexTail(...) (and later concatenated) which will throw when attempting .slice()/string concatenation. Handle the undefined case explicitly (e.g., return a policy reject/continue response, or throw a controlled error) before calling pexTail or building derived PINs.

Copilot · 2026-04-22T14:46:09Z

+const PORT = process.env.PORT ?? 3000
+


PORT comes from process.env.PORT which is a string; passing a numeric string to app.listen() is interpreted as a pipe/path in Node’s net.Server.listen, not a TCP port. Convert it to a number (and validate/handle NaN) before calling listen.

Suggested change

const PORT = process.env.PORT ?? 3000

const rawPort = process.env.PORT

const PORT = rawPort == null ? 3000 : Number(rawPort)

if (!Number.isInteger(PORT)) {

throw new Error(`Invalid PORT: ${rawPort}`)

}

Copilot · 2026-04-22T14:46:10Z

+
+  return {
+    status: 'success',
+    action: 'continue'


This function returns an object without result, while other branches return result: {...}. Since the server code assumes result exists, either always include result: {} here (for consistency) or ensure all consumers handle an absent result safely.

Suggested change

action: 'continue'

action: 'continue',

result: {}

Copilot · 2026-04-22T14:46:10Z

+ *   - Otherwise      → continue and let the system handle it with default settings.
+ *
+ * @param {string} localAlias - The alias of the incoming call.
+ * @returns {{ action: string, result: object }}


The JSDoc for handleServiceConfiguration is out of sync with the implementation: the signature accepts (localAlias, remoteDisplayName, vendor) and the function returns status as well, but only localAlias and { action, result } are documented. Update the JSDoc params/return type to match the actual contract.

Suggested change

* @returns {{ action: string, result: object }}

* @param {string} remoteDisplayName - The display name of the participant.

* @param {string} vendor - The vendor string from the SIP User-Agent header.

* @returns {{ status: string, action: string, result?: object }}

Copilot · 2026-04-22T14:46:10Z

+// Changing this value invalidates all previously generated call tags.
+const SECRET = 'my_secret_value'
+


This example hardcodes SECRET in source control. To avoid accidental reuse in real deployments, read the secret from an environment variable (and fail fast if missing) or make it clearly a placeholder value that must be replaced.

Suggested change

// Changing this value invalidates all previously generated call tags.

const SECRET = 'my_secret_value'

// Read it from the environment so it is not committed to source control.

// Changing this value invalidates all previously generated call tags.

const SECRET = DYNAMIC_PINS ? process.env.PEX_POLICY_SECRET?.trim() : undefined

if (DYNAMIC_PINS && !SECRET) {

throw new Error('PEX_POLICY_SECRET must be set when DYNAMIC_PINS is enabled')

}

Copilot · 2026-04-22T14:46:11Z

+    // Convert to byte
+    const encoder = new TextEncoder()
+    const data = encoder.encode(input)
+
+    // Use crypto of navigator
+    const hashBuffer = await crypto.subtle.digest('SHA-256', data)
+


pexHash relies on global crypto.subtle and TextEncoder. In Node.js these globals depend on the Node version; since package.json doesn’t declare an engines.node constraint, this example can fail at runtime on older Node versions. Either import WebCrypto explicitly from node:crypto or document/enforce the minimum Node version in package.json.

Copilot · 2026-04-22T14:46:11Z

+| Alias format | Example  | Behavior                                             |
+| ------------ | -------- | ---------------------------------------------------- |
+| 2 digits     | `01`     | Main conference room with static PINs.               |
+| 6 digits     | `010033` | Interpretation room (audio). PINs static or dynamic. |
+| Other        | —        | Pass-through (if known) or reject.                   |


The routing table says "Other → Pass-through (if known) or reject", but the implementation always returns action: 'continue' for unknown alias formats and never rejects. Align the documentation with the actual behavior, or change the policy to reject unknown aliases if that’s the intended behavior.

Suggested change

| Alias format | Example | Behavior |

| ------------ | -------- | ---------------------------------------------------- |

| 2 digits | `01` | Main conference room with static PINs. |

| 6 digits | `010033` | Interpretation room (audio). PINs static or dynamic. |

| Other | — | Pass-through (if known) or reject. |

| Alias format | Example | Behavior |

| ------------ | -------- | ------------------------------------------------------------- |

| 2 digits | `01` | Main conference room with static PINs. |

| 6 digits | `010033` | Interpretation room (audio). PINs static or dynamic. |

| Other | — | Pass-through (`action: 'continue'`); this example does not reject unknown aliases. |

chore: add external policy example

fac10b2

marcos-cereijo-pexip linked an issue Apr 22, 2026 that may be closed by this pull request

Add external policy example #35

Open

marcos-cereijo-pexip requested a review from Copilot April 22, 2026 14:40

Copilot started reviewing on behalf of marcos-cereijo-pexip April 22, 2026 14:41 View session

Copilot AI reviewed Apr 22, 2026

View reviewed changes

marcos-cereijo-pexip marked this pull request as draft April 27, 2026 11:26

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

chore: add external policy example#36

chore: add external policy example#36
marcos-cereijo-pexip wants to merge 1 commit into
masterfrom
feat/add-external-policy-example

marcos-cereijo-pexip commented Apr 22, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Apr 22, 2026

Uh oh!

Copilot AI Apr 22, 2026

Uh oh!

Copilot AI Apr 22, 2026

Uh oh!

Copilot AI Apr 22, 2026

Uh oh!

Copilot AI Apr 22, 2026

Uh oh!

Copilot AI Apr 22, 2026

Uh oh!

Copilot AI Apr 22, 2026

Uh oh!

Copilot AI Apr 22, 2026

Uh oh!

Copilot AI Apr 22, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	`[participant] local_alias=${localAlias} remote_display_name=${remoteDisplayName ?? ''} → call_tag=${response.result.call_tag ?? '(none)'}`
	`[participant] local_alias=${localAlias} remote_display_name=${remoteDisplayName ?? ''} → call_tag=${response.result?.call_tag ?? '(none)'}`

-const PORT = process.env.PORT ?? 3000
+const rawPort = process.env.PORT
+const PORT = rawPort == null ? 3000 : Number(rawPort)
+if (!Number.isInteger(PORT)) {
+  throw new Error(`Invalid PORT: ${rawPort}`)
+}

- * @returns {{ action: string, result: object }}
+ * @param {string} remoteDisplayName - The display name of the participant.
+ * @param {string} vendor - The vendor string from the SIP User-Agent header.
+ * @returns {{ status: string, action: string, result?: object }}

		// Changing this value invalidates all previously generated call tags.
		const SECRET = 'my_secret_value'

-// Changing this value invalidates all previously generated call tags.
-const SECRET = 'my_secret_value'
+// Read it from the environment so it is not committed to source control.
+// Changing this value invalidates all previously generated call tags.
+const SECRET = DYNAMIC_PINS ? process.env.PEX_POLICY_SECRET?.trim() : undefined
+if (DYNAMIC_PINS && !SECRET) {
+  throw new Error('PEX_POLICY_SECRET must be set when DYNAMIC_PINS is enabled')
+}

Conversation

marcos-cereijo-pexip commented Apr 22, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Apr 22, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 22, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 22, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 22, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 22, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 22, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 22, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 22, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 22, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants