From e84818ed267c69af409ce3af1177fa0e2aa1bc7e Mon Sep 17 00:00:00 2001 From: Yuri Iozzelli Date: Wed, 14 Oct 2026 11:08:21 +0200 Subject: [PATCH 1/2] cheerpx-for-flash: Document Native Bridge token authentication Describe how to start the bridge with a key and how the host application generates tokens for bridgeURL, add the version 42 changelog entry and use the 20261014_prod42 image in the examples. Co-Authored-By: Claude Opus 5.5 --- .../20-native-bridge/index.md | 63 ++++++++++++++++++- .../20-native-bridge/tutorial.md | 4 +- .../docs/cheerpx-for-flash/80-changelog.md | 4 ++ 3 files changed, 69 insertions(+), 2 deletions(-) diff --git a/sites/labs/src/content/docs/cheerpx-for-flash/20-native-bridge/index.md b/sites/labs/src/content/docs/cheerpx-for-flash/20-native-bridge/index.md index 3dc360819..f192e3b07 100644 --- a/sites/labs/src/content/docs/cheerpx-for-flash/20-native-bridge/index.md +++ b/sites/labs/src/content/docs/cheerpx-for-flash/20-native-bridge/index.md @@ -35,7 +35,7 @@ You then run the image, with the configuration options of your own choosing. The Although everyone's own Docker environments will differ, and you are at your own discretion to run the image however you may wish to, an example `docker run` command could be: -`docker run -p 28083:28083 --init --rm -v /path/to/harman/binary/ppdeploy/ppfp/:/flash localhost/ppfp_bridge:20251203_prod40` +`docker run -p 28083:28083 --init --rm -v /path/to/harman/binary/ppdeploy/ppfp/:/flash localhost/ppfp_bridge:20261014_prod42` Here, we are using a few flags: @@ -62,6 +62,67 @@ Simply become something that looks like this: As long as the URL specified can be reached by CheerpX, your installation of CheerpX for Flash will now be talking to the Websocket server, and your performance should be massively improved. +## How do I restrict who can connect to the Native Bridge? + +The browser of every end user must reach the Websockets server, so in most deployments anyone can connect to it. From version 42, the Native Bridge can optionally validate a token on every connection. We recommend enabling it for any bridge reachable from outside a trusted network. + +### Start the bridge with a key + +Choose a long random secret, the **key**, and pass it as the last argument of `docker run`: + +`docker run -p 28083:28083 --init --rm -v /path/to/harman/binary/ppdeploy/ppfp/:/flash localhost/ppfp_bridge:20261014_prod42 ` + +Without a key, the bridge accepts every connection, as in previous versions, and logs `no key given, connections are not authenticated` at startup. + +### Generate a token on your server + +When your server renders a page that uses the bridge, it generates a short-lived **token** from the key: + +1. Pick an expiry time, as Unix seconds, a few minutes in the future. +2. Compute the HMAC-SHA256 of the string `v1.`, with the expiry written in decimal, using the key. +3. Encode the resulting string in hexadecimal +4. The token is `v1..`. + +For example, in JavaScript, using the Web Crypto API available in browsers, Node.js 19+, Deno, Bun and Cloudflare Workers: + +```js +async function bridgeToken(key, validForSeconds = 300) { + const enc = new TextEncoder(); + const payload = `v1.${Math.floor(Date.now() / 1000) + validForSeconds}`; + const hmacKey = await crypto.subtle.importKey( + "raw", + enc.encode(key), + { name: "HMAC", hash: "SHA-256" }, + false, + ["sign"] + ); + const mac = new Uint8Array( + await crypto.subtle.sign("HMAC", hmacKey, enc.encode(payload)) + ); + const hex = Array.from(mac, (b) => b.toString(16).padStart(2, "0")).join(""); + return `${payload}.${hex}`; +} +``` + +Or in Python: + +```python +import hashlib, hmac, time + +def bridge_token(key: str, valid_for_seconds: int = 300) -> str: + payload = f"v1.{int(time.time()) + valid_for_seconds}" + mac = hmac.new(key.encode(), payload.encode(), hashlib.sha256).hexdigest() + return f"{payload}.{mac}" +``` + +### Pass the token to CheerpX + +Add the token to `bridgeURL` as the `token` query parameter: + +`` + +The bridge checks the token only when the connection opens, so a token only needs to stay valid until the page has loaded the Flash content. Connections with a missing, invalid or expired token are rejected with HTTP status 403. + --- To read more about Docker, take a look at their official docs [here](https://docs.docker.com/). diff --git a/sites/labs/src/content/docs/cheerpx-for-flash/20-native-bridge/tutorial.md b/sites/labs/src/content/docs/cheerpx-for-flash/20-native-bridge/tutorial.md index 36ebf4365..307ddd25c 100644 --- a/sites/labs/src/content/docs/cheerpx-for-flash/20-native-bridge/tutorial.md +++ b/sites/labs/src/content/docs/cheerpx-for-flash/20-native-bridge/tutorial.md @@ -16,7 +16,7 @@ Once you have the bridge downloaded, load it in to Docker using `docker load`. Run the image while ensuring to mount the `ppfp/` volume to `/flash`. The location of your hosted `ppfp/` folder can be directly referenced from where you are hosting CheerpX, or copied to another location for easier access. Depending on your machine, this could differ greatly, but for this tutorial, we will run the container using the following run command: - docker run -p 28083:28083 --init --rm -v /mnt/c/xampp/htdocs/cheerpx/ppdeploy/ppfp/:/flash localhost/ppfp_bridge:20251203_prod40 + docker run -p 28083:28083 --init --rm -v /mnt/c/xampp/htdocs/cheerpx/ppdeploy/ppfp/:/flash localhost/ppfp_bridge:20261014_prod42 The flags that we have set are: @@ -27,6 +27,8 @@ The flags that we have set are: For more information about `docker run`, read the official [Docker docs](https://docs.docker.com/engine/reference/run/). +This tutorial runs the bridge without authentication, so anyone who can reach port 28083 can connect to it. For a deployment reachable from outside a trusted network, start the bridge with a key and pass a token from your server, as described in [restricting who can connect](/cheerpx-for-flash/native-bridge#how-do-i-restrict-who-can-connect-to-the-native-bridge). + Our Websockets server should now be running on port :28083:

diff --git a/sites/labs/src/content/docs/cheerpx-for-flash/80-changelog.md b/sites/labs/src/content/docs/cheerpx-for-flash/80-changelog.md index 2ff446774..4c3870b82 100644 --- a/sites/labs/src/content/docs/cheerpx-for-flash/80-changelog.md +++ b/sites/labs/src/content/docs/cheerpx-for-flash/80-changelog.md @@ -2,6 +2,10 @@ title: Changelog --- +Version 42 - October 14th, 2026: + + * Optional Native Bridge authentication: when started with a key, the bridge requires a token on every connection. + Version 35 - March 28th, 2023: * Rebase on up-to-date CheerpX JIT engine. From be81aef299cdbbb64a1f70563515a97267aa25f7 Mon Sep 17 00:00:00 2001 From: Yuri Iozzelli Date: Wed, 14 Oct 2026 16:29:20 +0200 Subject: [PATCH 2/2] cheerpx-for-flash: Add missing changelog entries --- .../docs/cheerpx-for-flash/80-changelog.md | 32 +++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/sites/labs/src/content/docs/cheerpx-for-flash/80-changelog.md b/sites/labs/src/content/docs/cheerpx-for-flash/80-changelog.md index 4c3870b82..4ec9d44b5 100644 --- a/sites/labs/src/content/docs/cheerpx-for-flash/80-changelog.md +++ b/sites/labs/src/content/docs/cheerpx-for-flash/80-changelog.md @@ -6,6 +6,38 @@ Version 42 - October 14th, 2026: * Optional Native Bridge authentication: when started with a key, the bridge requires a token on every connection. +Version 41 - April 1st, 2026: + + * Rebase on up-to-date CheerpX engine. + * Native Bridge updated to the reworked networking. + * Disk access fixes. + * General bug fixes. + +Version 40 - December 3rd, 2025: + + * Native Bridge connection handling fixes. + * General bug fixes. + +Version 39 - November 21st, 2025: + + * Networking fixes. + * General bug fixes. + +Version 38 - November 14th, 2025: + + * Rebase on up-to-date CheerpX engine. + * New networking implementation. + * Faster communication between the Native Bridge and the Flash player. + * General bug fixes. + +Version 37 - June 17th, 2025: + + * Rebase on up-to-date CheerpX engine. + * Improved keyboard, mouse and touch input. + * Workaround for a Firefox 138+ regression affecting SharedArrayBuffer and WebAssembly. + * Native Bridge fixes. + * General bug fixes. + Version 35 - March 28th, 2023: * Rebase on up-to-date CheerpX JIT engine.