PSSP connects the OXRecorder system

Download PSSP

Broker and desktop packages: 1.0.5. Management SDK: 1.0.0. Protocol: v1. The source snapshot records revision d8d0e4980ec132d47aed3c6a6d4b4218da29355b.

Windows downloads target x64; Mac downloads require Apple Silicon. Linux desktop and Intel Mac builds are available through the source instructions. The Windows development binaries are unsigned and were cross-compiled on macOS; the broker was checked under Wine and the installer payload was inspected. Native Windows UI and WebView2 setup have not been validated here.

SHA-256 checksums · Build and validation notes · SDK packaging guide

Use shasum -a 256 FILE on macOS, sha256sum FILE on Linux, or Get-FileHash FILE -Algorithm SHA256 in Windows PowerShell and compare with the checksum list. Packages contain code and documentation; your broker creates its own credentials and state during bootstrap.

How device-to-server communication works

Both ends are PSSP clients. The broker is the service they connect to; your server application is a separate program that receives and processes data. A connection to the broker does not require the device to open a direct connection to the receiving application.

1. Prepare access. The administrator creates a separate identity for each participant and authorizes the operations it needs.
2. Establish a session. Each participant connects to the broker, verifies its identity and authenticates with its assigned credentials.
3. Prepare reception. The receiving application registers its administrator-approved subscription before the sender transmits.
4. Exchange data. The sender publishes a payload. The broker delivers it to authorized receivers without interpreting its contents.
5. Process and acknowledge. The receiver validates the application data and completes its required storage or processing handoff before acknowledging reliable delivery.

Communication can work in either direction. Device and server software can each send and receive. Use the desktop client to learn and test these operations before integrating them into your application.

Step 1 — Install and start the broker service

Windows: runnable broker ZIP

1. Download the Windows broker ZIP, right-click it and select Extract All.
2. Open its PSSP-Broker folder and double-click Start-PSSP-Broker.cmd.
3. On first run, save the generated administrator password before continuing. Open http://127.0.0.1:8080 and sign in as pssp-admin / admin with that password.
4. Keep the console open; Ctrl+C stops the broker. Configuration and state are stored in %LOCALAPPDATA%\PSSP and preserved on subsequent runs.

You can also run the included executable directly from PowerShell in the extracted folder:

.\pssp-broker.exe bootstrap --data-dir "$env:LOCALAPPDATA/PSSP" --portal-bind 127.0.0.1:8080
.\pssp-broker.exe serve --data-dir "$env:LOCALAPPDATA/PSSP"

This is a foreground console broker. It does not register itself with Windows Service Control Manager.

Linux server: Debian package

1. Copy the amd64 .deb to an x64 Debian/Ubuntu server with systemd, then install it as your regular administrator account:

sudo apt install ./pssp-broker_1.0.5_amd64.deb
sudo systemctl status pssp-broker
sudo journalctl -u pssp-broker -n 100 --no-pager

First installation creates the pssp system account, bootstraps /var/lib/pssp, prints a one-time administrator password, and starts the service. Save that password when it is displayed. Existing configuration and SQLite state are preserved on upgrades.

2. Open a secure tunnel from your development computer, replacing ubuntu@SERVER with your account and host:

ssh -L 8080:127.0.0.1:8080 ubuntu@SERVER

Visit http://127.0.0.1:8080 on your computer. Sign in with Client ID pssp-admin, Username admin and the generated password. The portal is separate from PSSP traffic on TCP/UDP 6688.

macOS: local broker

Extract the Mac broker ZIP and run these commands from its extracted folder:

./pssp-broker bootstrap --data-dir "$HOME/Library/Application Support/PSSP" --portal-bind 127.0.0.1:8080
./pssp-broker serve --data-dir "$HOME/Library/Application Support/PSSP"

Save the first-run administrator password and open http://127.0.0.1:8080. Keep the terminal running; Ctrl+C stops this foreground development service. Re-running bootstrap preserves existing settings and credentials. If macOS blocks a downloaded app, review its per-app approval in Privacy & Security before proceeding.

Broker settings and access

Use the browser portal's Principals page for identities and access permissions, Services for management automation, and Settings for listener/security configuration. Connections, Audit and Logs help diagnose activity. Source bootstrap without an explicit portal bind defaults to 0.0.0.0:8080; the commands here explicitly choose loopback. Generated pssp.toml, SQLite and runtime logs belong in the broker's private data directory.

The default broker setup uses AES-only mode: TLS off, AES on, and a pinned broker X25519 public key. Obtain the public pin from the service startup line containing PSSP_AES_ONLY_PUBLIC_KEY and deliver it through a trusted administrator process. Never give clients the broker's private key. If enabling TLS for other PSSP clients, configure matching certificates and client settings. Portal TLS is an independent setting; configure HTTPS before public portal exposure.

Step 2 — Learn PSSP with the desktop client

1. Request a development identity. Ask the broker administrator for a Client ID, Username, generated Password, broker address, security mode, verified public pin when needed, and authorized publish/subscribe settings. The administrator creates this identity on the portal's Principals page and saves its generated password when displayed.
2. Open the application. On Windows, run the downloaded .exe installer (or extract the setup ZIP first), finish installation, then launch PSSP Client from the Start menu. On Mac, extract the client ZIP, copy PSSP Client.app into Applications and launch it. Linux desktop users can build from the source package.
3. Enter connection settings. In Settings → Connection, enter Broker host and Port (normally 6688). Use the exact Client ID and Username assigned to you and enter the generated Password.
4. Match the security mode. For an AES-only broker, leave TLS 1.3 transport off and enter the verified Broker AES-only X25519 public key. For a TLS-enabled broker, enable TLS and use a hostname matching its trusted certificate.
5. Connect and verify. Select Connect and wait for authentication success. Check the displayed session state. TCP Ping can confirm that the broker responds over the established session.
6. Prepare a receiver. Under Subscriptions, enter the subscription settings supplied by the administrator. Select Latest for a new-data test and assign a stable Worker ID to this logical receiver. Select Subscribe and wait for success.
7. Send a sample. Under Publish QoS 1, enter the administrator-approved publish setting and a short Opaque UTF-8 payload such as Hello from my device. Select Publish and wait for acknowledgement.
8. Inspect the result. Open Events to confirm receipt and inspect the payload. Monitor shows protocol activity and errors. For a device-to-server simulation, use a second client session with its own authorized identity as the receiver.
9. Test the reverse direction. With both identities authorized appropriately, prepare a subscription on the first participant and send from the second. Verify the data at the receiving end.
10. Test reconnection. Disconnect and reconnect using the same receiver identity and Worker ID. Choose Resume after ACK when continuing an existing receiver, or Earliest available when intentionally reading retained data. Retention limits still apply.

The Windows client uses Microsoft Edge WebView2 Runtime. Its installer includes Microsoft's bootstrapper and installs the runtime when needed; allow internet access for that step. The app requires no Rust, Node.js or Python installation.

A successful Publish result confirms broker acceptance. Confirm a corresponding receive event separately, and verify application processing in your actual server. The desktop client is a test application; account administration is performed in the browser portal.

Step 3 — Apply PSSP to an end device and server

1. Define your application data

Choose a payload format both ends understand: for example, UTF-8 JSON for a small sample, or a documented binary format for structured data. Include an application format version and a unique message identifier when deduplication matters. PSSP transports bytes; your application implements encoding, validation and interpretation.

{
  "formatVersion": 1,
  "messageId": "sample-0001",
  "value": "Hello from my device"
}

2. Prepare separate device and server identities

Create the identities in the broker portal and grant only the publish/subscribe access each application needs. Deliver each participant's credentials through your existing provisioning process. Store credentials in protected device storage or the server's secret configuration. The broker authenticates the exact Client ID and Username pair.

3. Select or implement the client connection

The downloaded source includes a Rust implementation in client/src-tauri/src/lib.rs and framing/security support in client/src-tauri/src/protocol.rs. These are implementation references, not a standalone embedded-device SDK. Your device firmware and server application need their own compatible PSSP integration. The Node.js management SDK below handles account administration, not application-data transfer.

Configure the reachable broker hostname, port, client identity, password and security settings on each end. A device outside the server's private network needs an address it can reach. Verify the broker's public pin through a trusted provisioning process before connecting in AES-only mode.

4. Establish and maintain the session

Open TCP, negotiate the protocol and security settings, then authenticate. Complete the required encrypted-session setup before sending application data. Wait for success at each stage; a TCP connection alone does not mean authentication succeeded. See the connection and delivery explanation for the sequence.

5. Start the receiving application

Register its approved subscription and wait for acceptance before the device sends the first test payload. Decode incoming data, validate the format version and reject malformed values. For reliable delivery, acknowledge only after the application's required durable handoff succeeds. Keep processing idempotent so a repeated delivery does not repeat an external effect.

6. Send from the device and confirm receipt

Encode a small sample payload, publish it using reliable delivery and wait for broker acknowledgement. On the server, record the application message identifier and verify the decoded value. If the application needs confirmation of completed processing, implement an application-level response and verify it on the device; broker acceptance alone does not prove completed server processing.

7. Recover from an interrupted connection

Reconnect with bounded retry delays, authenticate again and establish a fresh encrypted session. Restore the receiver's subscription with the same logical receiver identity when resuming. Persist your own processing state where needed. If retained data has expired, use the application's recovery mechanism instead of assuming the broker can recover unlimited history.

8. Verify before deployment

• Check both directions with the intended device and server software.
• Confirm invalid credentials and unauthorized operations are rejected.
• Test a temporary disconnection, reconnection and repeated delivery.
• Check how the application handles expired retained data and server restarts.
• Verify payload limits and processing throughput under your expected load.

Management SDK for backend developers

The SDK requires Node.js 18 or newer and exposes PsspManagementClient. Download the .tgz into your Node project and install it locally:

npm install ./oxrecorder-pssp-management-1.0.0.tgz

Register the provisioning service and its Ed25519 public key in the broker portal, grant only the required identity and operation scope, and keep its private key on the provisioning server. This read-only example checks the connection and lists principals allowed by that scope:

import { PsspManagementClient } from '@oxrecorder/pssp-management';

const management = new PsspManagementClient({
  host: process.env.PSSP_MANAGEMENT_HOST,
  port: Number(process.env.PSSP_MANAGEMENT_PORT || 6690),
  serviceId: process.env.PSSP_MANAGEMENT_SERVICE_ID,
  privateKeyFile: process.env.PSSP_MANAGEMENT_PRIVATE_KEY_FILE,
  brokerPublicKey: process.env.PSSP_MANAGEMENT_BROKER_PUBLIC_KEY,
});
await management.checkConnection();
const { principals } = await management.listPrincipals();
console.log(`Visible principals: ${principals.length}`);

The other methods are provisionPrincipal, updatePrincipal and deletePrincipal; their input types are in the package's index.d.ts. Provisioning returns generated credentials, so pass them directly to the intended recipient's secret mechanism. Ordinary device and application processes should not receive broad management keys. The management SDK is not a PSSP streaming-data client.

Build the service and client from source

Extract the source archive and open its PSSP-1.0.5 folder. Install Rust supporting edition 2024 (this snapshot was checked with Rust 1.97.1), Node.js/npm for the client, and your target platform's desktop build prerequisites. Keep the Cargo and npm lockfiles.

Service build (macOS, Linux or Windows)

cargo test --locked --workspace
cargo build --locked --release -p pssp-broker
# macOS / Linux
./target/release/pssp-broker bootstrap --data-dir ./local-data --portal-bind 127.0.0.1:8080
./target/release/pssp-broker serve --data-dir ./local-data
# Windows PowerShell
.\target\release\pssp-broker.exe bootstrap --data-dir .\local-data --portal-bind 127.0.0.1:8080
.\target\release\pssp-broker.exe serve --data-dir .\local-data

On a headless Linux broker builder, use cargo test --locked -p pssp-broker to avoid the desktop client's GUI build dependencies. To create a .deb on Debian/Ubuntu with dpkg-deb installed, run ./packaging/debian/build-deb.sh. On macOS with Docker Desktop, ./packaging/debian/build-deb-macos.sh amd64 targets x64 Linux; arm64 targets Linux ARM64.

Desktop client build

cd client
npm ci --include=optional
npm run tauri:dev
# Stop the development app, then create the current platform's package:
npm run tauri:build -- --config '{"version":"1.0.5"}'

The explicit version aligns the installer with the Rust workspace; the original frontend/Tauri configuration still labels itself 1.0.0. On Windows PowerShell, if native-command JSON quoting causes trouble, set version to 1.0.5 in src-tauri/tauri.conf.json and run npm run tauri:build.

Build on the intended OS and architecture. Windows requires its native C++ toolchain and WebView2; macOS requires Xcode command-line tools; Linux requires development packages for WebKitGTK 4.1, GTK 3 and related Tauri dependencies. The web-only npm run build output is not a runnable PSSP desktop client: its Rust backend owns the sockets and protocol session. Tauri packages appear under target/release/bundle/ (or the corresponding target-specific directory).

The source package's PACKAGE-README.md records packaging provenance. Use this website guide for the current portal-based administration workflow.

Delivery behavior and troubleshooting

Detailed explanation of connections, security and delivery →

• Reliable delivery: TCP QoS 1 uses acknowledgements and publisher deduplication. Receivers must still make application processing idempotent.
• Best-effort delivery: UDP QoS 0 depends on an active authenticated TCP session and provides no delivery acknowledgement or replay guarantee.
• Retention: the broker keeps bounded data in memory. A restart loses buffered data; persistent application storage belongs in your server application.
• GAP: requested data has expired or been evicted. Recover required data through your application's storage or recovery process.
• Authentication failure: verify the exact Client ID, Username, Password and Enabled state in the portal.
• Operation rejected: have the administrator verify the identity's permissions and confirm that you used its assigned settings.
• Security mismatch: verify the broker hostname, TLS mode and public pin. Management and application connections use separate security settings.
• Lost administrator access: version 1.0.5 includes recover-admin. Inspect pssp-broker recover-admin --help and stop the broker before using this local recovery procedure.

Package validation results are available in the download notes. Test the complete device-to-server flow in your own deployment before relying on it.