Bouncer 0.5.7
Published as a private GitLab release, v0.5.7+34, from commit
b329764d1b909dc6cc5fbd560d018933d14ab8e0. It has 21 files, all checked
against their SHA256 hashes after upload. The source repository and release
are private. The Android internal build is on Firebase App Distribution and
iOS 0.5.7 is in internal TestFlight, both for S6 Studios' own testing.
Neither has been installed on a real device yet. Updating a client doesn't
upgrade its server, and the Bouncer project's own production server still
runs build 0.3.8+25.
Changes in the apps
- A brief "Reconnecting…" notice after unlock or resume (#285). While Bouncer reconnects, it shows this notice instead of a server-error banner. A real response error still has its own message.
- Notification settings on iPhone (#288). Settings > Notifications > Notification settings opens iOS notification settings, or the app's settings on iOS 15. If iOS cannot open it, Bouncer shows the manual path through Settings > Notifications > Bouncer.
- Clearer Library ownership and sharing. Credential details show who owns the credential and how you have access. The information shown depends on your role; it does not reveal everyone else's access.
- Android launcher and round icons. The packages include square and round PNG icons at all five standard densities, alongside the unchanged adaptive and themed monochrome artwork. The in-app credential icons, app label and package identity stay the same. Emulator checks passed; the icon still needs checking in Firebase App Distribution and App Tester after the next signed build is distributed. Install over the earlier app to keep pairing; do not uninstall for this fix.
- Which keys meet a resource's settings. Apps explain the key requirement. New Windows Hello enrolments send available TPM evidence and show the server's verification result in Settings. Existing keys gain no evidence through an update. No real PC has passed an attested enrolment yet.
Changes for command-line users and administrators
- Requester listings, JSON and key-issuance log details have a non-secret 12-hex-character key identifier to distinguish rapid key rotations.
- Resource provisioning errors explain the operator repair, with exit 7 and no immediate CLI/MCP retries. Database outages use exit 16.
- The admin log export includes token issuance, backend revoke, provisioning and CA-change records. The matching admin client preserves future kinds and fields. The compatibility and evidence limits below matter to exporters.
- The server checks resource provisioning separately and offers
bouncer-server --check-config. The role kit adds narrow metadata reads. - After it has read a CA public key once, the server can serve new SSH revocations during an OpenBao outage, including after a restart.
- The manual has new or expanded guidance on credential lifecycle, installation, audit matching, outages, SSH host delivery and restores. Each chapter's "How this was checked" note says what was tested.
Versions and build status
| Component | Version in this source | Distribution status |
|---|---|---|
| Server, Linux and Windows CLI, admin and MCP | 0.5.7 | Private GitLab release; production remains on build 0.3.8+25 |
| Android | versionName 0.5.7, versionCode 34; internal versionName 0.5.7-internal | Private GitLab release; the internal build is on Firebase App Distribution for S6 Studios' own testing; no Play submission |
| iOS | short version 0.5.7, build 34 | Internal TestFlight for S6 Studios' own testing; no App Review submission |
| Windows app | 0.5.7; beta MSIX 0.5.34.0, internal 0.5.34.1, Store 1.0.34.0 | MSIX and ZIP in the private GitLab release; no Microsoft Store submission |
The App Tester icon check, checks on real phones and PCs, and a real PC's Windows Hello TPM enrolment are still to do.
See Get Bouncer for the release files and the separate availability of earlier builds. The 0.5.6 build's files and checksums stay unchanged.
For operators
- Role kit: you can upgrade the server before the kit: it keeps issuing tokens as before, as described below. Resources whose provisioning metadata cannot be checked show
upgrade_needed, and--check-configexits 4. The P1 to P6 upgrade with this release's kit is recommended, and is required before turning on credential lifecycle. After the kit upgrade, require exit 0 before adding resources. - Rollback: restore the pre-upgrade backup; never edit the migration table. Migrations 0017 to 0019 are new. After a restore or rollback, reset each SSH host's KRL version state as the manual's "Reset host version state" section describes, after waiting the longest SSH
credential_ttlplus five minutes from the server stop. - SSH revocation lists while OpenBao is down: Bouncer now serves them from its database, including after a restart, once the CA public key has been read once. A CA rotation is logged as a warning and an
ssh_ca_changedapproval-log entry. An upgraded installation with no observed CA still needs one successful read before it can publish a list. - Audit export: a stand-alone
bouncer-adminfrom 0.5.6 or earlier stops at the firsttoken_issued,backend_revoke,resource_provisioning_changedorssh_ca_changedentry. Earlier entries, including entries on that failed page, may already have been written; the cursor file is unchanged. Use the matching CLI, resume from the saved cursor and remove repeats byid. The new CLI may reorder JSON keys. - Audit log noise: until the kit upgrade, OpenBao's audit log gets about one permission-denied entry per resource per minute from the provisioning checks.
- Health:
/v1/healthis unauthenticated and now shows counts of unprovisioned resources and checks needing a kit upgrade, without resource names. These are last-known counts, not a new synchronous probe or a list of resources. - Exit 7: with this release's CLI and MCP, exit 7 now also covers a server-side provisioning gap,
resource_not_provisioned, with an operator repair message and no immediate retries. A 0.5.6 or earlier CLI or MCP doesn't know this code: it sees an HTTP 503 server error, exits 1 and may retry. Upgrade agent hosts' CLI and MCP with the server, and update any wrapper that reads exit codes. - Android: the launcher and round icons are fixed in this release. The release keeps the same package and must use the same signer, with versionCode 34, so the in-place update preserves existing pairing. The icon resources do not change pairing storage. Signed in-place update verification is still a release-build check. The 0.5.6 build's files and checksum pins must not be replaced.
- Attestation limit (#282):
android_attestation: requiredapplies only to devices that declare Android; it is not a requirement for verified hardware evidence on every platform. The limit also affects existing servers that setpairing.allow_user_verified_keys: true. See Known limits below. No policy change is included here.
Upgrading the server first keeps an older kit working, but the older kit hasn't passed the new checks. The server retains earlier issuance checks when metadata permissions or an exact older policy format prevent full inspection; create capability and token vetting still apply. A metadata 403 with a live login means upgrade_needed, not a proven missing object. A definite missing or unsuitable role or policy is a per-resource refusal. A seal, unreachable OpenBao or failed login remains a backend outage. Lifecycle stays off by default, and a kit from before 0.5.3 (policy format 1) must be upgraded before lifecycle is turned on.
Token records are admin-export-only and contain non-secret accessors, never token values or stored secrets. Feed the full accessor to sys/audit-hash for the same OpenBao audit device to obtain its matching HMAC. Records are not a complete account of every external call: a failed database commit can follow a backend call, older records are not backfilled, and missing or uncertain issuance evidence does not prove that a token was released.
require_hardware_key is off by default. It accepts a per-use hardware key without requiring the check itself to be biometric; require_hardware_uv retains its biometric requirement, and both must pass if both are set. Replacing the biometric setting with the hardware-key setting is a named policy loosening, not an automatic upgrade step. Read #282 below before treating a platform label as verified hardware evidence.
Upgrade order
- Save the pre-upgrade database backup and matching config and release files. Prepare matching CLI/admin binaries and pause any scheduled export that still runs an older stand-alone admin client.
- Upgrade the role kit first. Use this release's kit for the P1 to P6 procedure, preserving the existing
resources,kit.envand SSH resource settings. Review the dry run, apply the kit, and complete its checks and verification. If P1 to P6 used the 0.5.6 kit already, run the new kit's dry run again: it adds the provisioning reads tobouncer-server. Investigate unrelated policy drift. - Run the candidate server's
--check-confignext, as its service user with the intended config and OpenBao settings. Require exit 0 before adding resources or proceeding with the new setup. The preflight does not open the database, migrate it, apply the config or start listeners; its AppRole login can create an expiring server-session token, never a resource credential. Exit 1 means global setup/login failure, 2 usage, 3 a definite resource gap, and 4 an upgrade-needed or transient check. A definite gap takes precedence over an incomplete check. - Upgrade the server after the successful check. It applies the new migrations at startup. Verify health and the resource counts, and confirm an intended request and revoke. If PostgreSQL becomes unavailable while the server runs, it answers 503
database_unavailablewithRetry-Afterand recovers without a restart; CLI/MCP use outage exit 16. A resource provisioning gap can leave health 200 while that resource is refused. - Resume exporters with the matching
bouncer-admin, then update CLI/MCP and apps. Upgrade the server before apps that send the new enrolment fields. A config that setsrequire_hardware_keyrequires the new server; 0.5.6 or earlier refuses that setting. Existing Windows Hello keys do not acquire TPM evidence by upgrade; verified evidence can be attached only during a new enrolment.
| Migration | What it adds |
|---|---|
0017_token_audit.sql | Token audit metadata for issuance and backend revoke export records. |
0018_event_resource.sql | The resource association for provisioning events. |
0019_ssh_ca_keys.sql | Retained CA public keys, sequenced observations and per-issuance CA identity for durable KRL delivery. |
Rollback and SSH host recovery
Use the matching pre-upgrade backup, config and older image. An older server cannot simply use the migrated database. Never remove migration records or change their checksums to make it start. A restore also returns device, requester, grant, key and lifecycle state to the backup, so keep outside access closed and reconcile changes made since the backup using the restore runbook.
For SSH, wait until the longest credential_ttl used by the SSH host resources, plus five minutes, has elapsed since stopping the server for the restore or rollback. The restored database cannot revoke certificates for grants it never recorded. Confirm the intended restored publisher, reconcile revokes and keep independent recovery access. Then reset each destination's version state deliberately. Follow the five-step Reset host version state procedure on each destination host. Stop its timer and service, then remove only its version file. Keep the installed KRL, trusted CA and last_ok; use the configured state directory if it differs from the default. If outside access is still closed, defer the fetch until it is reopened. Start a manual service fetch, inspect its successful log and version, and only then resume the timer.
If the fetch fails, keep the timer stopped, fix the cause and check freshness with bouncer-krl-pull --check using the service's state-directory and age settings. A successful fetch alone does not repair missing revoke history; keep affected principals removed until expiry if that history cannot be reconstructed. Never clear state merely to silence an unexplained older-version error. Follow the full restore procedure. Nobody has yet run a 0.5.7 rollback end to end.
Known limits
- #282 remains open. Bouncer can't verify every device's description of its own key:
android_attestation: requiredapplies only to devices that declare Android, andrequire_hardware_uvandrequire_hardware_keycan't by themselves prove hardware on every platform. This affects existing servers and earlier versions too, whereverpairing.allow_user_verified_keysistrue. Until it's fixed, give pairing codes only to the intended person, and review which resources rely on those two settings. This release changes no enforcement or approval eligibility for this limit. - #283 remains open. Restoring or rolling back the database can move the publisher's KRL revision below the revision hosts hold. Automatic continuity is not implemented; the deliberate, reconciled host reset above is still required. Using the clock to keep revisions moving forward would not be enough on its own, because the clock can be set back and an older binary would not know the rule.
- #284 is postponed. This release has no gateway, session recording or gateway-enforced session cutoff.
- Open sessions stay open (D29). An expired certificate can't start a new login, and a revoked one can't once the host has fetched a list that includes the revoke. Neither ends an SSH session that is already open. Until a host fetches the new list, a previously issued certificate can still log in until it expires. With the stale policy
keep, the host keeps its last list, reportsSTALEand exits 2 after the configured age, rather than locking everyone out. A host that has never fetched a list refuses every certificate login until its first successful fetch. - #287 remains open. After a push service outage recovers, a phone can receive a burst of notifications that are no longer current, such as closures for requests that were already handled. Open Bouncer to see which requests still need a decision.
- #289 remains open. On Android, a notification can stay on the phone after its request was handled or dismissed on another device. Open the request in Bouncer and check its current state before acting on it.
- CA and TPM evidence have limits. An old CA never observed by Bouncer cannot be reconstructed, and certificates issued before the upgrade are matched to the first CA Bouncer reads after it; upgrade and let that read succeed before rotating. Observed CAs are retained without pruning. Windows TPM verification is covered by automated tests. No real PC has completed an attested enrolment yet.