Desktop management application

Use the PSSP Client app

The cross-platform Tauri app connects to a broker, authenticates a session, inspects topics, publishes test QoS 1 data, checks TCP/UDP liveness, and displays protocol events. It is not an OX Device or WebService adapter.

Delivery mode comes from the Broker

The client sends a durable workerID, but cannot make itself a shared worker or broadcast viewer. Configure the principal's structured delivery grant as described in Brocker configuration.

On this page

Start or package
Connect and authenticate
Find the AES-only Broker public key
Manage access
Subscribe and replay
Publish QoS 1 data
Verify TCP/UDP
Read events
Troubleshooting

Start the application

cd client
npm install
npm run tauri:dev

To create installers on the current operating system:

npm run tauri:build

Platform	Support
Windows	Supported Tauri target; build the installer on Windows or a suitable CI target.
Linux	Supported Tauri target; package on the intended Linux build environment.
macOS	Supported Tauri target; package on macOS.

1. Connect and authenticate

Ask the broker administrator to create your exact client ID, username, password, and ACLs in the broker SQLite database.
Open the Connection section and enter broker host and port. The default PSSP port is 6688.
Enter the broker-created client ID, username, and password. The client sends standard PSSP AUTH; it does not call a WebService or open SQLite.
Set TLS 1.3 transport to match the broker.
- For the included plaintext development profile, leave it off.
- For the TLS production profile, turn it on. The broker hostname must match a certificate trusted by the operating system.
- For TLS-off AES mode, leave TLS off and paste the pre-provisioned Broker X25519 public key into Broker AES-only X25519 public key. The client rejects a missing or mismatched pin.
Select Connect.

Successful connection

The status block changes to Connected, shows the broker-issued connection ID, and indicates whether an AES session is active. Passwords are used for the active connection only; the initial app does not save them to disk.

Local connection values	Value
Host / port	`127.0.0.1:6688`
Client ID / username / password	The exact principal created by `pssp-broker setup` or `create-principal`.
TLS	Off only for the local plaintext or AES-only profile.

Never use the example credentials outside a private test environment.

The development broker sends credentials and payloads without TLS/AES. Use TLS + AES or AES-only with a securely provisioned X25519 pin for an untrusted network.

Find the Broker X25519 public key for AES-only connections

This key is required specifically when the Broker runs with tls.enabled = false and encryption.enabled = true. The Broker administrator generates a long-lived X25519 private key once, keeps it secret, and derives the matching public key that every client pins. The public key is not a client credential and is not stored in the Broker's SQLite database.

If the deployment does not already have a private key, generate one from the repository root. The command prints the private value but does not automatically save it anywhere.
```
cargo run -p pssp-broker -- generate-aes-only-private-key
```
Store that value securely as encryption.static_private_key in the Broker configuration, or as the only content of a protected secret file. Generate it once for the Broker deployment; replacing it changes the public key and requires every client pin to be updated.
Derive the public key from a protected key file:
```
cargo run -p pssp-broker -- aes-only-public-key \
  --private-key-file /protected/path/aes-only-private-key
```
If the private key is stored directly in encryption.static_private_key, omit the input option and paste that private value at the hidden prompt:
```
cargo run -p pssp-broker -- aes-only-public-key
```
Copy the command's single-line output—not the private key—into Broker AES-only X25519 public key in the client, then connect with TLS 1.3 transport turned off.

Installed Broker command

On a deployed system where pssp-broker is installed in PATH, use pssp-broker generate-aes-only-private-key and pssp-broker aes-only-public-key instead of the repository cargo run -p pssp-broker -- prefix.

Key material	Where it is kept	Who receives it
X25519 private key	Protected Broker configuration under `encryption.static_private_key`, or a protected administrator-managed secret file used to provision that setting.	Broker administrator and Broker process only. Never copy it into the client.
X25519 public key	Derived from the private key when requested; the Broker also derives and advertises it during AES-only setup.	Provision it to clients through a trusted channel and pin it in the client connection settings.
Per-connection AES key	Derived in memory from X25519 + HKDF for the active session; it is not stored or sent over TCP.	Used internally by the Broker and client for that connection.

Do not trust an unverified public key learned over the same connection.

Compare or deliver the public key through a trusted administrator channel. The client rejects a missing or mismatched pin because accepting a substituted key would permit a man-in-the-middle attack.

Manage PSSP access

The Access tab uses the Broker's separate encrypted management listener (normally 127.0.0.1:6690), not the ordinary PSSP listener on port 6688. Enter the management host/port, the pinned management X25519 public key, the management service ID, and its matching Ed25519 private PEM.

Configure an enabled [[management.allowed_services]] entry for the desktop operator. Its public key must match the private PEM entered in the app. See create the Ed25519 service key.
Grant only the permissions needed: principal.list to review accounts, principal.provision to add, principal.update to edit, and principal.delete to remove them.
Select Load principals. The Broker authenticates the service and returns only principals within its configured client ID, username, principal-kind, topic, and delivery-mode scopes.
Select a principal to edit its enabled state, payload limit, and publish/subscribe ACLs, or select New principal. New principal passwords are generated by the Broker and shown once; save them before closing the notice.

Protect the desktop operator PEM.

It authorizes management requests and is more sensitive than a normal PSSP password. The app retains it only in memory for the current session, never puts it in a PSSP record, and never saves it to disk. Do not grant all four permissions unless the operator is intended to administer accounts.

In the Subscriptions section, enter a topic filter and select its start position.

Control	What to enter	Effect
Filter	For example `#`, `devices/+/audio/#`, or `control/room-7/#`	Only matching authorized topics are delivered. `+` matches one segment; final `#` matches descendants.
Replay: Latest	`latest`	Skip existing retained messages; receive data published after the subscription is created.
Replay: Earliest available	`earliest`	Receive currently retained messages in matching topic rings, then new messages.
Replay: Resume after ACK	`resume`	Reuse the same `workerID` after reconnecting and receive retained messages after the last `MSGACK`.
Worker ID	A stable name such as `desktop-operator`	Part of the resume identity. Keep it unchanged when reconnecting for the same logical consumer.

Select Subscribe. The broker returns a subscription acknowledgement. Messages appear in the protocol-events list. The management app acknowledges a message after accepting it into its in-memory diagnostic log; a production application client must persist or durably queue payloads before its MSGACK.

3. Publish a QoS 1 test payload

Enter a concrete topic in Publish QoS 1, for example demo/topic. Do not use wildcard characters in a publish topic.
Enter the opaque UTF-8 test payload.
Select Publish.

The app sends a TCP QoS 1 PUBLISH with an automatically managed publisher session ID and sequence. The broker returns PUBACK after it accepts the payload into the topic buffer. Any matching subscription—including one in the same desktop app—receives a MESSAGE.

Opaque means application-defined

The desktop GUI publishes UTF-8 to make testing convenient. PSSP itself accepts any bytes. Future application clients can send encoded media chunks, binary files, protocol buffers, command data, or synchronization data without broker changes.

4. Verify TCP and UDP liveness

Button	Protocol action	Expected result
TCP Ping	TCP `PING`	A `PONG` protocol event appears. This works for any active PSSP TCP connection.
Bind UDP	`UDP_BIND` with the session association token	Broker binds the client UDP source endpoint. Status changes from “UDP: not bound” to “UDP: bound”.
UDP Ping	UDP `PING`	The command completes after the client verifies the broker's UDP `PONG`. Bind UDP first.

When AES is enabled, bind and ping use the AES-protected session created either inside TLS or by pinned X25519 + HKDF key agreement. In intentionally plain Broker mode, UDP uses the temporary authenticated-session token but has no TLS/AES protection.

5. Read the event log

Event	Meaning	Action
`connected`	Login and required session setup completed.	Subscribe or publish.
`message`	A QoS 1 delivery arrived. Topic, sequence, metadata summary, and base64url payload are available.	Inspect payload or use a dedicated application client for actual processing.
`pong`	Broker answered a TCP ping.	Connection is live at the protocol level.
`gap`	Data requested for replay was evicted from finite broker memory.	Recover from your application’s archive, or review retention limits.
`error`	Broker rejected an operation or a local operation failed.	Read the displayed code/detail and check ACL, credentials, security-mode, or network configuration.
`disconnected`	The TCP session ended; session keys and UDP binding no longer apply.	Reconnect. Use the same `workerID` with `resume` if appropriate.

Troubleshooting checklist

For detailed diagnostic commands, security-mode setup, and step-by-step recovery procedures, use the dedicated PSSP troubleshooting guide.

Problem	Check
Connect fails immediately	Confirm the broker is running, host/port is correct, and TCP 6688 is reachable.
TLS handshake fails	Enable TLS in the app only when it is enabled in broker config; use a certificate trusted by the OS and a host that matches its name.
Authentication fails	Verify all three fields: client ID, username, and password. The broker permits a client ID to have multiple user records, but each exact pair must exist.
Subscribe/publish unauthorized	Use the Access tab if the connected management service has `principal.list`, or review the principal's SQLite ACLs with the broker CLI. Publishing must use a concrete topic; filters are valid only for subscription/ACL use.
Access tab is denied or empty	Confirm the management host/port and pinned management public key, then verify that the service's Ed25519 public key, PEM, and `principal.list` permission match the Broker configuration. Empty means no principals fall within that service scope.
UDP ping times out	Keep TCP active, click Bind UDP first, and allow UDP 6688 through local firewalls, NAT, and network policy.
No old data after resume	Use the same `workerID`, reconnect before the resume TTL expires, and ensure data was not evicted or lost in a broker restart.