github nilsteampassnet/TeamPass 3.2.4.4

one hour ago

What's Changed

This is a maintenance release on the 3.2.4 line. It fixes an upgrade that stopped with an HTTP 500 error, Data truncated for column 'item_id', on installations holding Secure Send notes, a warning shown by the Secure Send journal of the logs page, and accented letters of the settings that reached e-mails and authenticator apps as HTML entities (Société). Imports from other password managers no longer alter passwords or shift values, and the CSV export no longer breaks on descriptions that hold a line break. It also lets the recipient of a protected Secure Send link check the passphrase they type, and lets API clients such as the browser extension send Secure Send notes, list their links and revoke them. Backups and restores are hardened: the SQL dump no longer turns line breaks into \n, SFTP checks the server's identity before sending credentials, and a restore validates the whole archive before changing anything. Network whitelists and blacklists now filter every application request and can no longer be bypassed through a forged proxy header. The CSV import reads the documented comments column again, the folder tree follows its counter option again, and API logins no longer slow down as the system log grows. The Secure Send fixes, the passphrase toggle, the folder counter fix, the network access control fix and the backup hardening come from @guerricv, the settings fix from @MarMarAba, the CSV import and export fixes from @jayhemnani9910. Upgrading is recommended for all installations, and required for any installation whose upgrade stopped with this error.

This release does not change the database schema. UPGRADE_MIN_DATE is deliberately left at its 3.2.4.3 value, so installations already running 3.2.4.3 are not sent back through the upgrade wizard.

Some installations need an administrator's action. If a network whitelist or blacklist is enabled, if TeamPass runs behind a reverse proxy, if you use SFTP, WebDAV or S3 externalized backups, or if you plan to restore a backup, read the Breaking changes section below before upgrading.

🔒 Security fixes

  • Network whitelists and blacklists could be bypassed (GHSA-6q46-mfmg-f8ph, PR #5464, @guerricv) — the lists were checked when a page was opened and by the REST API, but not by login processing, AJAX actions or file downloads. A blocked address could still authenticate, and a session opened from an allowed network kept reading and changing data from any address. Behind a reverse proxy, TeamPass took the leftmost address of X-Forwarded-For. With the $proxy_add_x_forwarded_for setting that our documentation recommended, that address is the one the client sends, so a client could claim an allowed address. When the rules could not be read, filtering was silently switched off. Every application request is now checked, the forwarded chain is read from the trusted proxy back towards the client, and an unreadable rule table refuses access. Installations running 3.1.7.1 or later with a list enabled are affected. See Breaking changes for what to check before upgrading.
  • SFTP externalized backups now verify the server before sending credentials (PR #5468, @guerricv) — TeamPass connected to the SFTP server without checking its host key. A machine able to pose as that server on the network received the SFTP password, when password authentication is used, and the encrypted archives. The connection now checks the server's OpenSSH SHA256 fingerprint before any authentication. Existing SFTP destinations stop transferring until the fingerprint is entered: see Breaking changes. Installations using SFTP externalized backups are affected.

⚠️ Breaking changes

Two areas change behaviour in ways that can block access, stop backup transfers or change how a restore ends until an administrator acts.

Network access control

PR #5464 (@guerricv) closes the bypasses described under Security fixes. Check the following in Admin → Options → Networks if a whitelist or blacklist is enabled, or if IP detection mode is set to Reverse proxy / WAF.

  • Every application request is now filtered. Before, only page loads and the API checked the lists. Now login processing, AJAX actions and file downloads check them too, as does the API, CORS preflight requests included. A session opened from an allowed network stops working as soon as the client's address leaves it. Requests from an excluded address that used to get through are now refused with 403. These lists still do not filter Secure Send recipient pages (on the main or the public address), the installation and upgrade scripts, or command-line scripts. Static files and the WebSocket connection are not filtered either: restrict them on the web server, the reverse proxy or a firewall if needed.

  • An unreadable rule table now blocks access. When a list is enabled and its table is missing or cannot be read, every request gets 503 instead of passing unfiltered. The installation and upgrade scripts stay reachable to repair it.

  • Behind a reverse proxy, the client address is now read from the right. TeamPass reads X-Forwarded-For from right to left, skips the addresses listed in Trusted proxies, and takes the first one that is not listed. Before, it took the leftmost address, which the client can write itself. Before upgrading:

    • list every intermediary in Trusted proxies: each internal proxy or load balancer, and the outgoing ranges published by your CDN or WAF provider. An intermediary left out becomes the detected address of every user behind it;
    • never list a client network there;
    • on a single Nginx proxy facing the Internet, replace proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; with proxy_set_header X-Forwarded-For $remote_addr;. With several proxies, the outer one must drop the forwarding headers sent by the client.

    A missing header, or an invalid or IPv6 hop, now gives no usable address. An enabled list then refuses access instead of using the proxy's own address. X-Real-IP must hold a single IPv4 address. The address read this way also feeds the brute-force counters, the logs and the device-pairing rate limits, so these change behind a proxy even when both lists are disabled. After the upgrade, check Detected client IP in the Detected connection context panel before enabling or changing a whitelist. If you are locked out, the network ACL documentation gives the query that disables the whitelist.

Backups and restore

The backup module was reviewed end to end (PR #5468, @guerricv). The changes below stop transfers or change how a restore behaves until an administrator acts.

  • SFTP externalized backups need the server's host key fingerprint. TeamPass connected to the SFTP server without checking its identity. A machine posing as that server on the network could receive the SFTP password, when password authentication is used, and the encrypted archives. The connection now checks the server's OpenSSH SHA256 fingerprint before sending any credential. Existing SFTP destinations have no fingerprint yet. Their transfers fail, without sending any credential, until an administrator enters it in Backups > Externalized > Server host key fingerprint (SHA256). Obtain it from the server's administrator through a trusted channel, for example by running ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub -E sha256 on that server, and copy only the SHA256:… part. If the server has several host keys, use the fingerprint of the key the connection negotiates. A wrong or changed fingerprint is reported as a mismatch and blocks the transfer until the new one has been verified and saved.

  • WebDAV and S3-compatible endpoints over plain HTTP need an explicit opt-in. An http:// endpoint is now refused, and its transfers stop, unless it points to the machine itself (localhost, 127.0.0.1, ::1). This covers private services such as a MinIO container (http://minio:9000) or a NAS on the local network. Switch the endpoint to HTTPS or, on a trusted private network only, tick Allow an unencrypted HTTP endpoint in the same tab. Over HTTP, anyone observing the network sees the traffic and the WebDAV password. The archives stay encrypted. An endpoint URL holding credentials (https://user:password@host) is now always refused: use the dedicated fields. AWS S3, with an empty endpoint, is not affected.

  • A manual backup needs an encryption key. Earlier releases accepted an empty key on the on-the-fly backup and then wrote the database dump unencrypted. An empty key, or one longer than 4,096 bytes, is now refused. The key is used exactly as typed. Earlier releases turned & < > " ' into HTML entities before using it. A restore tries both forms, so an older archive opens with the key as it was typed. Those releases could also drop a tag-like part of a key, such as <…>; the backups documentation explains what to do then. A manual backup now also refuses to start while background tasks are running: retry once they have finished.

  • A restore refuses a backup made under another master key. Before changing anything, the restore command checks that the backup matches the database schema of this installation and was made under the master key of this instance, the key file in secrets/. A backup from another instance, or from this instance before its key was replaced, is refused. Once restored, the data encrypted under the other key could no longer be read. Use the disaster-recovery procedure with the original Recovery Package instead. Use another decryption key remains available for a backup encrypted with another backup key. A backup taken on an earlier patch release of the same schema can now be restored.

  • A successful restore leaves the instance closed and signs everyone out. The restored database dates from the backup, and the sessions, tokens and queued work it holds may have been revoked since. After the import, the restore command therefore:

    • keeps maintenance mode on;
    • disables scheduled backups, externalized backups and LAPR;
    • signs every user out and deletes API sessions, personal access tokens, paired devices, the users' legacy API keys, queued background tasks and Secure Send links, whose deletion is recorded in the Secure Send journal;
    • resets the offline-sync generation, so offline clients download everything again.

    Check the restored instance, then turn maintenance mode off, re-enable the schedules and LAPR, and let users generate new API keys and tokens. The browser extension and paired mobile devices must be set up again.

  • The web interface and the API are closed during a restore. While the import runs, every web page and API call answers 503, administrators included, and background tasks do not run. The restore command refuses to start while a backup or a background task is running. If the import is interrupted, the instance stays closed. Run the same command again with --resume, from the same system account, with the original archive and token. Never delete storage/logs/teampass_restore.pending to reopen a partially restored database. A restore prepared before the upgrade must be prepared again.

🛠️ Improvements

  • Secure Send recipients can check the passphrase they type (PR #5462, @guerricv) — an eye button beside the passphrase field of a protected link shows and masks the typed phrase. The field starts masked. The button never submits the form, so it consumes neither a view nor a passphrase attempt. It is a native toggle button: it works from the keyboard and announces its state to screen readers. The recipient page still runs no other script: its security policy allows only this toggle's exact code, identified by its SHA-256 digest, including on the page that shows the revealed content. Without JavaScript the button stays hidden and the form works as before.
  • Secure Send from API clients: notes, list and revocation — the browser extension, paired mobile devices and API scripts can now send notes as well as items, list their links and revoke them. POST secureSend/create accepts "type": "note" with the content to share: a title, a secret, a text, a login and a URL. The web rule applies: Allow sending ad-hoc notes/secrets must be enabled. A note is encrypted for the link only, is not saved in the vault, and its creation decrypts nothing from the vault. GET secureSend/policy now tells the client whether notes are allowed and how large a note may be (16,000 bytes). GET secureSend/list returns the user's links that can still be opened, including those created from the web interface, with what My secure sends shows. It never returns a link address, which the server does not keep, a recipient's email address or the content of a note. DELETE secureSend/revoke deletes one of these links at once and records the revocation in the audit journal. An email invitation still waiting to be sent is then not sent. A link of another user gets the same answer as a link that does not exist, so link identifiers cannot be probed. Item sends work as before, and their answer gains a type member. See the Secure Send API documentation.
  • Translations — thirteen new strings and two reworded strings, all translated into French, are on POEditor. The Brazilian Portuguese translation is now complete apart from these new strings, and Estonian gains 162 translations.

🐛 Bug fixes

  • The upgrade failed on installations holding Secure Send notes (PR #5460, @guerricv) — every upgrade replays the migration steps from 3.0.0 onwards. One of the first steps made the item_id column of the otv table mandatory again, before the 3.2.1 step made it optional. A Secure Send note is not bound to an item and leaves item_id empty. As soon as one note was stored, that first step failed on a database in strict SQL mode, the MySQL and MariaDB default, and the upgrade stopped with an HTTP 500 error and Data truncated for column 'item_id' at row 1. The step now keeps the column optional, as a fresh installation creates it. Existing links and notes are kept unchanged. On a database without strict mode, the step did not fail but stored 0 instead of an empty value for each note. TeamPass identifies a note by its type, not by this column, so these links kept working and need no repair. Installations running 3.2.1.0 or later are affected when Allow sending ad-hoc notes/secrets (not only items) is enabled. It is off by default.
  • The Secure Send journal of the logs page showed a DataTables warning (PR #5461, @guerricv) — in Monitoring > Logs, the Secure Send source raised the alert Requested unknown parameter 'policy' for row 0, column 5 when the journal loaded and after each filter change. The Details column is built from the whole log row and has no field of its own, but the table still asked for one. The column now reads the row the way the Actions column already does, and the alert no longer appears. The details shown are unchanged. The Secure Send source is new in 3.2.4.3 and is shown to administrators only.
  • Accented letters of the settings were stored as HTML entities (PR #5465, @MarMarAba) — a text setting saved from the administration pages stored each accented letter as an HTML entity: Société became Soci&eacute;t&eacute;. Pages hid it, but some places show the value as text. E-mails arrived from Soci&eacute;t&eacute; Passwords, authenticator apps added the account under that issuer name, and the Custom login text field of the Options page displayed Inicio de sesi&oacute;n. Accented and other non-ASCII letters are now stored as typed. The HTML special characters (& < > " ') are still escaped as before, so a setting printed into a page is as safe as it was. The upgrade repairs the values stored by earlier releases. It decodes only the entities that stand for those letters, leaves credentials and encrypted values alone, and writes nothing when no setting needs it.
  • Imports from KeePassXC, LastPass and 1Password could save wrong values (PR #5471, @jayhemnani9910) — when a quoted value of the exported CSV file ended with a backslash, as a generated password or a Windows path in the notes can, the import did not see the end of the value. The value took in the fields after it: a password ending in \ was saved with the URL appended, and the URL and notes were shifted or lost. A value near the end of a line could take in the following lines, and those entries were not imported at all. The import still reported success. These files mark a quote inside a value by doubling it, and a backslash is now kept as a plain character, as the generic CSV import already did. Bitwarden imports were not affected. Installations running 3.2.1.0 or later are affected. Entries imported earlier keep the values they were saved with: if an imported password, URL or note looks wrong, correct it or import the file again.
  • Imports from Bitwarden, KeePassXC, LastPass and 1Password altered passwords — the import from other password managers cleaned each password as if it were text shown in a page. Spaces at the start or end were removed, &, " and ' were stored as HTML entities (a&b became a&amp;b), characters outside the ISO-8859-1 set, such as €, ł, Greek or Cyrillic letters, and emoji were replaced by spaces, tabs became line breaks, and some sequences such as <…> or javascript: were deleted. A password made only of such characters was imported empty. Passwords are now imported exactly as exported, as the CSV and KeePass imports already did. Labels, logins, URLs and notes are cleaned as before. Installations running 3.2.1.0 or later are affected. Entries imported earlier keep the passwords they were saved with: if an imported password does not work, type it again or import the file again.
  • The CSV import dropped every description (issue #5470, @githubpromat) — the documentation names the description column comments, but the import read a column named description. A file built from the documentation was imported without any description, and the import still reported success. A file exported from TeamPass names its columns description and pw, so it was imported back without passwords. Both names are now accepted for each column: comments or description, password or pw. Column names are matched regardless of case, and the byte order mark that Excel writes in CSV UTF-8 files is ignored. A file without a label column is now rejected with an error instead of importing nothing. A password is imported exactly as written, leading and trailing spaces included. Installations running 3.1.3 or later are affected. Items imported earlier keep their empty description: fill it in, or delete them and import the file again.
  • The CSV export broke on values holding a line break (PR #5472, @jayhemnani9910) — when the description of an item held a line break, as descriptions imported from KeePass or Bitwarden can, the export kept that item only up to the break. The rest of its description, its password, login, URL and folder were lost, and the quote left open pulled the following items into its description. A value holding a backslash followed by a quote, such as the password ab\"cd, also broke its line for any CSV reader. Each item is now written whole, line breaks included, and a quote inside a value is marked by doubling it, the CSV rule that the TeamPass import and other password managers read. Every 3.x release is affected. A CSV file exported earlier from such items is incomplete: export it again before relying on it as a backup or to move to another password manager.
  • An item saved to another folder than the one being browsed could get the wrong encryption keys (issue #5469, @alienpenguin) — the item form told the server whether the folder was personal from the folder open in the tree, while the item went to the folder picked in the form. Opening the form from a personal folder and picking a shared one stored the new item as personal. Only its creator held a key for it, and it was not listed in the shared folder, neither for the creator nor for the other users. The other way round, a new item saved into a personal folder had its keys sent to every user, until the background task removed them again. The server now reads this from the folder the item is saved to. Changing the folder in the edit form between a personal and a shared folder now does what Move does. An item leaving a personal folder gets keys for the users of the shared folder. An item entering a personal folder keeps keys for its owner only. Before, the first stayed readable by its owner alone and the second kept the keys of every user. A LAPR-managed item or SSH credential can no longer be saved into a personal folder this way, which Move already refused. Items saved earlier this way are not repaired by the upgrade. An item moved from the edit form is repaired by Monitoring > Tools > Restore missing sharekeys. An item created from a personal folder also needs its personal flag reset in the database first: the troubleshooting guide gives the query that lists these items and the steps.
  • The Show counters in folder tree option was not applied consistently (PR #5463, @guerricv) — each user's folder tree is cached, and the cache did not record whether it had been built with counters. After an administrator changed the option, users kept the previous display until their cache was rebuilt for another reason: counters stayed after the option was turned off, or stayed missing after it was turned on. Opening a folder also added its counter back with the option off, and a folder reached through individual item access always showed its item count. The cached tree now records the setting it was built with and is rebuilt when the setting changes, and an Items page already open refreshes its tree at the next folder it loads. The option now applies to every folder, read-only folders and folders reached through individual item access included. The item count shown above the item list is unchanged.
  • API logins slowed down as the system log grew (issue #5466, @speelman-git) — before recording an API connection, TeamPass checks whether the same user was recorded in the last two seconds. That check compared text columns of the log_system table with numbers, so MySQL could not use its index and read the whole table on every /authorize call: about five seconds per login with 1.4 million rows. The check also never matched, so it never prevented a duplicate entry. It now uses its index and works as intended. The same kind of mistake left the backup task lists of the System Health page always empty; they now show the backup tasks. Installations running 3.1.6.0 or later are affected.
  • Backups could silently change data or report incomplete work as successful (PR #5468, @guerricv) — the SQL dump wrote each line break of a value as the two characters \n. A restore therefore turned multi-line descriptions and other text values into a single line holding a literal \n. Line breaks, backslashes and binary values are now kept as they are. This cannot repair values already changed by restoring an older dump. A backup that was asked to include documents reported success even when some files were missing or unreadable. It now fails and names the problem. A failed backup run no longer purges the previous archives, and a retention failure is now reported without preventing the off-site copy of the new archive. Backup archives stored directly in the files folder were deleted after seven days by the temporary-file cleanup; only the backup retention removes them now. In a database shared with other applications, the backup also captured their tables; it now holds the TeamPass tables only. The externalized backup run after a scheduled backup now copies that exact encrypted archive, checked by its SHA-256 digest, instead of dumping the database a second time and disconnecting users again. After a disaster recovery, the backup schedules stayed enabled. They are now disabled like the other scheduled work. Releases since 3.1.1 are affected by the line-break loss.
  • A restore could leave a partial database or write files outside the documents folder (PR #5468, @guerricv) — the restore imported the dump statement by statement and stopped at the first error, leaving a half-restored database. The whole archive is now validated before any table is changed: its SQL, its tables, its schema and its master key. A truncated or foreign archive is refused with nothing changed. The restore authorization is bound to the SHA-256 digest of the archive, so a file replaced after preparation is refused. A restored package could write any file name into the public avatars folder. Only image files are accepted there now. The temporary decrypted copies of a restore are kept in private folders and removed after use. Only administrators can prepare a restore.
  • The issuer name of Google 2-Step Verification was printed unescaped — the Multi-Factor Authentication settings page printed the stored value of Name displayed in Google 2-step Verification for Teampass into its field as is. This was safe only because the settings pages store it HTML-escaped. A legacy server action, unused since 3.0, could still store it unescaped, so an administrator could inject markup into the page through it. The action is removed, and the page now escapes the value itself. The field shows the same text as before. Only administrators could reach that action and open that page.

⬆️ Upgrade notes

  • Schema. No schema change. Installations already running 3.2.4.3 deploy the new files and are not sent through the upgrade wizard.
  • Settings stored with HTML entities. The upgrade repairs them each time it runs. Installations upgrading from 3.2.4.2 or earlier go through it and are repaired. Installations already running 3.2.4.3 are not sent through the wizard: the next upgrade that runs it repairs their values. Until then, type the affected value again in its field and save it, and it is stored as typed. An account already added to an authenticator app keeps the issuer name it was added with. Its codes keep working, and the app can rename it. A value in which an administrator deliberately typed an entity, such as &eacute;, becomes é: the two cases cannot be told apart.
  • Secure Send behind a reverse proxy. The recipient page sends its own Content-Security-Policy, which now allows the passphrase toggle by its digest. A proxy that replaces this header, or adds a second policy restricting scripts, blocks the toggle: the eye button stays hidden, and the link still works. Leave the page's own policy in place rather than copying it, since the digest changes whenever the toggle changes.
  • Secure Send list and revocation through the API. They need no new setting and are available as soon as a user has API access with the read right, even when Allow Secure Send from API clients is off. That switch still governs link creation only. Listing and revoking can only reduce exposure, and the list stays empty while User can propose One-Time-View links is off.
  • Network access control. Before upgrading, read the Breaking changes section if a whitelist or blacklist is enabled or if TeamPass runs behind a reverse proxy. The upgrade wizard is not filtered by these lists, but the application is as soon as the new files are in place. Keep database access at hand to disable the whitelist if your address is now detected differently.
  • Backups. Before upgrading, read the Breaking changes section if you use SFTP, WebDAV or S3 externalized backups. An externalized backup queued after a scheduled backup by the previous release fails once after the upgrade, because it does not carry the archive digest. The next scheduled backup queues it again.
  • Folder tree. The first time each user's folder tree loads after the upgrade, it is rebuilt once, as after a folder change. With Show counters in folder tree off, folders reached through individual item access no longer show their item count.
  • An upgrade stopped by Data truncated for column 'item_id'. Deploy the 3.2.4.4 files, then run the upgrade again, from the web wizard or the command-line upgrade. It starts over from the first step and completes. No manual database change is needed.
  • Back up your database before upgrading, as always.

Full Changelog: 3.2.4.3...3.2.4.4

Important

  • Requires at least PHP 8.2

Languages

Please join Teampass v3 translation project on Poeditor and translate it for your language.

Installation

Follow instructions from Documentation.

Upgrade

Follow instructions from Documentation.

Ideas and comments

Are welcome ... please use Discussions.

Help others find TeamPass

If TeamPass serves your team well, a ⭐ on this repository, a like on AlternativeTo or a short review on SourceForge helps other administrators find it.

Download TeamPass

Don't miss a new TeamPass release

NewReleases is sending notifications on new releases.