kp2bw 2.0.0__tar.gz

kp2bw-2.0.0/PKG-INFO

@@ -0,0 +1,127 @@
+Metadata-Version: 2.3
+Name: kp2bw
+Version: 2.0.0
+Summary: Imports and existing KeePass db with REF fields into Bitwarden
+Keywords: bitwarden,cli,keepass,migration,password-manager
+Author: Kaj Kowalski
+Author-email: Kaj Kowalski <info@kajkowalski.nl>
+Classifier: Environment :: Console
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Security
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Dist: pykeepass>=4.1.1.post1
+Requires-Python: >=3.14
+Project-URL: Changelog, https://github.com/kjanat/kp2bw/blob/master/CHANGELOG.md
+Project-URL: Issues, https://github.com/kjanat/kp2bw/issues
+Project-URL: Repository, https://github.com/kjanat/kp2bw
+Description-Content-Type: text/markdown
+
+# KP2BW - KeePass 2.x to Bitwarden Converter
+
+> Fork of [jampe/kp2bw], modernized.
+
+Migrates KeePass databases to Bitwarden via the `bw` CLI, with advantages over
+the built-in Bitwarden importer:
+
+- **Encrypted in-memory transfer** -- data never hits disk unencrypted (except
+  attachments, which are cleaned up after upload)
+- **KeePass REF resolution** -- username/password references are resolved:
+  matching credentials merge URLs into one entry; differing ones create new
+  entries
+- **Passkey migration** -- KeePassXC FIDO2/passkey credentials
+  (`KPEX_PASSKEY_*`) are converted to Bitwarden `fido2Credentials`
+- **Custom properties & attachments** -- imported as Bitwarden custom fields or
+  attachments (values > 10k chars auto-upload as files)
+- **Long notes handling** -- notes exceeding 10k chars are uploaded as
+  `notes.txt` attachments
+- **Idempotent** -- safe to run multiple times without duplicating entries
+- **Nested folders** -- KeePass folder hierarchy is recreated in Bitwarden
+- **Recycle Bin filtering** -- deleted entries are automatically excluded
+- **Expiry awareness** -- expired entries are marked `[EXPIRED]` in notes;
+  optionally skip them entirely with `--skip-expired`
+- **Metadata preservation** -- KeePass tags, expiry dates, and created/modified
+  timestamps are stored as Bitwarden custom fields
+- **Tag filtering** -- import only entries matching specific tags
+- **Organization & collection support** -- upload into a Bitwarden organization
+  with automatic or manual collection assignment
+- **Full UTF-8 & cross-platform** -- works on Windows, macOS, and Linux
+
+## Installation
+
+```bash
+# install with:
+uv tool install kp2bw
+kp2bw passwords.kdbx
+
+# or run directly without installing:
+uvx kp2bw
+```
+
+or from a GitHub URL:
+
+```bash
+# install with:
+uv tool install git+https://github.com/kjanat/kp2bw
+kp2bw passwords.kdbx
+
+# run directly without installing:
+uvx --from git+https://github.com/kjanat/kp2bw kp2bw passwords.kdbx
+```
+
+## Prerequisites
+
+Install the [Bitwarden CLI] and log in once before using `kp2bw`:
+
+```bash
+# optional: point to a self-hosted instance
+bw config server https://your-domain.com/
+
+# log in (only needed once; kp2bw uses `bw unlock` afterwards)
+bw login <user>
+```
+
+## Usage
+
+```console
+kp2bw [-h] [-k KEEPASS_PASSWORD] [-K KEEPASS_KEYFILE] [-b BITWARDEN_PASSWORD]
+       [-o BITWARDEN_ORG] [-c BITWARDEN_COLLECTION] [-t TAG [TAG ...]]
+       [--path-to-name | --no-path-to-name] [--path-to-name-skip N]
+       [--skip-expired | --no-skip-expired]
+       [--include-recycle-bin | --no-include-recycle-bin]
+       [--metadata | --no-metadata] [-y] [-v] [-V | --version] keepass_file
+```
+
+| Flag                                   | Description                                                    | Env var                               |
+| -------------------------------------- | -------------------------------------------------------------- | ------------------------------------- |
+| `keepass_file`                         | Path to your KeePass 2.x database                              | -                                     |
+| `-k, --keepass-password`               | KeePass password (prompted if omitted)                         | `KP2BW_KEEPASS_PASSWORD`              |
+| `-K, --keepass-keyfile`                | KeePass key file                                               | `KP2BW_KEEPASS_KEYFILE`               |
+| `-b, --bitwarden-password`             | Bitwarden password (prompted if omitted)                       | `KP2BW_BITWARDEN_PASSWORD`            |
+| `-o, --bitwarden-org`                  | Bitwarden Organization ID                                      | `KP2BW_BITWARDEN_ORG`                 |
+| `-c, --bitwarden-collection`           | Collection ID, or `auto` to derive from top-level folder names | `KP2BW_BITWARDEN_COLLECTION`          |
+| `-t, --import-tags`                    | Only import entries with these tags                            | `KP2BW_IMPORT_TAGS` (comma-separated) |
+| `--path-to-name` / `--no-path-to-name` | Prepend folder path to entry names (default: off)              | `KP2BW_PATH_TO_NAME`                  |
+| `--path-to-name-skip`                  | Skip first N folders in path prefix (default: 1)               | `KP2BW_PATH_TO_NAME_SKIP`             |
+| `--skip-expired`                       | Skip entries that have expired in KeePass                      | `KP2BW_SKIP_EXPIRED`                  |
+| `--include-recycle-bin`                | Include Recycle Bin entries (excluded by default)              | `KP2BW_INCLUDE_RECYCLE_BIN`           |
+| `--metadata` / `--no-metadata`         | Toggle KeePass metadata as custom fields (default: on)         | `KP2BW_MIGRATE_METADATA`              |
+| `-y, --yes`                            | Skip the Bitwarden CLI setup confirmation prompt               | `KP2BW_YES`                           |
+| `-v, --verbose`                        | Verbose output                                                 | `KP2BW_VERBOSE`                       |
+| `-V, --version`                        | Print the installed `kp2bw` version and exit                   | -                                     |
+
+Configuration precedence is always: CLI flag > environment variable > built-in default.
+
+## Troubleshooting
+
+### "Invalid master password" on `bw unlock`
+
+If your password contains special shell characters (`?`, `>`, `&`, etc.), wrap
+it in double quotes when prompted. See jampe/kp2bw#10 and
+libkeepass/pykeepass#254 for details.
+
+[jampe/kp2bw]: https://github.com/jampe/kp2bw
+[Bitwarden CLI]: https://bitwarden.com/help/cli/

kp2bw-2.0.0/README.md

@@ -0,0 +1,105 @@
+# KP2BW - KeePass 2.x to Bitwarden Converter
+
+> Fork of [jampe/kp2bw], modernized.
+
+Migrates KeePass databases to Bitwarden via the `bw` CLI, with advantages over
+the built-in Bitwarden importer:
+
+- **Encrypted in-memory transfer** -- data never hits disk unencrypted (except
+  attachments, which are cleaned up after upload)
+- **KeePass REF resolution** -- username/password references are resolved:
+  matching credentials merge URLs into one entry; differing ones create new
+  entries
+- **Passkey migration** -- KeePassXC FIDO2/passkey credentials
+  (`KPEX_PASSKEY_*`) are converted to Bitwarden `fido2Credentials`
+- **Custom properties & attachments** -- imported as Bitwarden custom fields or
+  attachments (values > 10k chars auto-upload as files)
+- **Long notes handling** -- notes exceeding 10k chars are uploaded as
+  `notes.txt` attachments
+- **Idempotent** -- safe to run multiple times without duplicating entries
+- **Nested folders** -- KeePass folder hierarchy is recreated in Bitwarden
+- **Recycle Bin filtering** -- deleted entries are automatically excluded
+- **Expiry awareness** -- expired entries are marked `[EXPIRED]` in notes;
+  optionally skip them entirely with `--skip-expired`
+- **Metadata preservation** -- KeePass tags, expiry dates, and created/modified
+  timestamps are stored as Bitwarden custom fields
+- **Tag filtering** -- import only entries matching specific tags
+- **Organization & collection support** -- upload into a Bitwarden organization
+  with automatic or manual collection assignment
+- **Full UTF-8 & cross-platform** -- works on Windows, macOS, and Linux
+
+## Installation
+
+```bash
+# install with:
+uv tool install kp2bw
+kp2bw passwords.kdbx
+
+# or run directly without installing:
+uvx kp2bw
+```
+
+or from a GitHub URL:
+
+```bash
+# install with:
+uv tool install git+https://github.com/kjanat/kp2bw
+kp2bw passwords.kdbx
+
+# run directly without installing:
+uvx --from git+https://github.com/kjanat/kp2bw kp2bw passwords.kdbx
+```
+
+## Prerequisites
+
+Install the [Bitwarden CLI] and log in once before using `kp2bw`:
+
+```bash
+# optional: point to a self-hosted instance
+bw config server https://your-domain.com/
+
+# log in (only needed once; kp2bw uses `bw unlock` afterwards)
+bw login <user>
+```
+
+## Usage
+
+```console
+kp2bw [-h] [-k KEEPASS_PASSWORD] [-K KEEPASS_KEYFILE] [-b BITWARDEN_PASSWORD]
+       [-o BITWARDEN_ORG] [-c BITWARDEN_COLLECTION] [-t TAG [TAG ...]]
+       [--path-to-name | --no-path-to-name] [--path-to-name-skip N]
+       [--skip-expired | --no-skip-expired]
+       [--include-recycle-bin | --no-include-recycle-bin]
+       [--metadata | --no-metadata] [-y] [-v] [-V | --version] keepass_file
+```
+
+| Flag                                   | Description                                                    | Env var                               |
+| -------------------------------------- | -------------------------------------------------------------- | ------------------------------------- |
+| `keepass_file`                         | Path to your KeePass 2.x database                              | -                                     |
+| `-k, --keepass-password`               | KeePass password (prompted if omitted)                         | `KP2BW_KEEPASS_PASSWORD`              |
+| `-K, --keepass-keyfile`                | KeePass key file                                               | `KP2BW_KEEPASS_KEYFILE`               |
+| `-b, --bitwarden-password`             | Bitwarden password (prompted if omitted)                       | `KP2BW_BITWARDEN_PASSWORD`            |
+| `-o, --bitwarden-org`                  | Bitwarden Organization ID                                      | `KP2BW_BITWARDEN_ORG`                 |
+| `-c, --bitwarden-collection`           | Collection ID, or `auto` to derive from top-level folder names | `KP2BW_BITWARDEN_COLLECTION`          |
+| `-t, --import-tags`                    | Only import entries with these tags                            | `KP2BW_IMPORT_TAGS` (comma-separated) |
+| `--path-to-name` / `--no-path-to-name` | Prepend folder path to entry names (default: off)              | `KP2BW_PATH_TO_NAME`                  |
+| `--path-to-name-skip`                  | Skip first N folders in path prefix (default: 1)               | `KP2BW_PATH_TO_NAME_SKIP`             |
+| `--skip-expired`                       | Skip entries that have expired in KeePass                      | `KP2BW_SKIP_EXPIRED`                  |
+| `--include-recycle-bin`                | Include Recycle Bin entries (excluded by default)              | `KP2BW_INCLUDE_RECYCLE_BIN`           |
+| `--metadata` / `--no-metadata`         | Toggle KeePass metadata as custom fields (default: on)         | `KP2BW_MIGRATE_METADATA`              |
+| `-y, --yes`                            | Skip the Bitwarden CLI setup confirmation prompt               | `KP2BW_YES`                           |
+| `-v, --verbose`                        | Verbose output                                                 | `KP2BW_VERBOSE`                       |
+| `-V, --version`                        | Print the installed `kp2bw` version and exit                   | -                                     |
+
+Configuration precedence is always: CLI flag > environment variable > built-in default.
+
+## Troubleshooting
+
+### "Invalid master password" on `bw unlock`
+
+If your password contains special shell characters (`?`, `>`, `&`, etc.), wrap
+it in double quotes when prompted. See jampe/kp2bw#10 and
+libkeepass/pykeepass#254 for details.
+
+[jampe/kp2bw]: https://github.com/jampe/kp2bw
+[Bitwarden CLI]: https://bitwarden.com/help/cli/

kp2bw-2.0.0/pyproject.toml

@@ -0,0 +1,64 @@
+[project]
+name            = "kp2bw"
+version         = "2.0.0"
+description     = "Imports and existing KeePass db with REF fields into Bitwarden"
+readme          = "README.md"
+requires-python = ">=3.14"
+keywords        = ["bitwarden", "cli", "keepass", "migration", "password-manager"]
+classifiers     = [
+  "Environment :: Console",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Security",
+  "Topic :: Utilities",
+  "Typing :: Typed",
+]
+dependencies    = ["pykeepass>=4.1.1.post1"]
+
+[[project.authors]]
+name  = "Kaj Kowalski"
+email = "info@kajkowalski.nl"
+
+[project.urls]
+Changelog  = "https://github.com/kjanat/kp2bw/blob/master/CHANGELOG.md"
+Issues     = "https://github.com/kjanat/kp2bw/issues"
+Repository = "https://github.com/kjanat/kp2bw"
+
+[project.scripts]
+kp2bw = "kp2bw.cli:main"
+
+[dependency-groups]
+dev   = [
+  { include-group = "lint" },
+  { include-group = "stubs" },
+]
+lint  = [
+  "basedpyright>=1.38.1",
+  "ruff>=0.15.2",
+  "tombi>=0.7.32",
+  "ty>=0.0.18",
+]
+stubs = ["pykeepass-stubs"]
+
+[build-system]
+requires      = ["uv_build>=0.10.4,<0.11.0"]
+build-backend = "uv_build"
+
+[tool.pyright]
+venvPath         = "."
+venv             = ".venv"
+typeCheckingMode = "strict"
+pythonVersion    = "3.14"
+
+[tool.ruff]
+preview        = true
+target-version = "py314"
+
+[tool.uv.sources]
+pykeepass-stubs = { workspace = true }
+
+[tool.uv.workspace]
+members = ["packages/*"]
+exclude = []

kp2bw-2.0.0/src/kp2bw/__init__.py

@@ -0,0 +1,3 @@
+from importlib.metadata import version
+
+__version__ = version("kp2bw")

kp2bw-2.0.0/src/kp2bw/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+main()

kp2bw-2.0.0/src/kp2bw/bitwardenclient.py

@@ -0,0 +1,247 @@
+import base64
+import json
+import logging
+import os
+import platform
+import shutil
+from itertools import groupby
+from subprocess import STDOUT, CalledProcessError, check_output
+from typing import Any
+
+from pykeepass import Attachment
+
+from .exceptions import BitwardenClientError
+
+logger = logging.getLogger(__name__)
+
+
+class BitwardenClient:
+    TEMPORARY_ATTACHMENT_FOLDER: str = "attachment-temp"
+
+    _orgId: str | None
+    _key: str
+    _folders: dict[str, str]
+    _folder_entries: dict[str | None, list[str]]
+    _colls: dict[str, str] | None
+
+    def __init__(self, password: str, org_id: str | None) -> None:
+        # check for bw cli installation
+        if "bitwarden" not in self._exec("bw"):
+            raise BitwardenClientError(
+                "Bitwarden Cli not installed! See https://help.bitwarden.com/article/cli/#download--install for help"
+            )
+
+        # save org
+        self._orgId = org_id
+
+        # login
+        self._key = self._exec(f'bw unlock "{password}" --raw')
+        if "error" in self._key:
+            raise BitwardenClientError(
+                "Could not unlock the Bitwarden db. Is the Master Password correct and are bw cli tools set up correctly?"
+            )
+
+        # make sure data is up to date
+        if "Syncing complete." not in self._exec_with_session("bw sync"):
+            raise BitwardenClientError(
+                "Could not sync the local state to your Bitwarden server"
+            )
+
+        # get folder list
+        self._folders = {
+            folder["name"]: folder["id"]
+            for folder in json.loads(self._exec_with_session("bw list folders"))
+        }
+
+        # get existing entries
+        self._folder_entries = self._get_existing_folder_entries()
+
+        # get existing collections
+        if org_id:
+            self._colls = {
+                coll["name"]: coll["id"]
+                for coll in json.loads(
+                    self._exec_with_session(
+                        f"bw list org-collections --organizationid {org_id}"
+                    )
+                )
+            }
+        else:
+            self._colls = None
+
+    def __del__(self) -> None:
+        # cleanup temp directory
+        self._remove_temporary_attachment_folder()
+
+    def _create_temporary_attachment_folder(self) -> None:
+        if not os.path.isdir(self.TEMPORARY_ATTACHMENT_FOLDER):
+            os.mkdir(self.TEMPORARY_ATTACHMENT_FOLDER)
+
+    def _remove_temporary_attachment_folder(self) -> None:
+        if os.path.isdir(self.TEMPORARY_ATTACHMENT_FOLDER):
+            shutil.rmtree(self.TEMPORARY_ATTACHMENT_FOLDER)
+
+    def _exec(self, command: str) -> str:
+        output: bytes
+        try:
+            logger.debug("-- Executing Bitwarden CLI command")
+            output = check_output(command, stderr=STDOUT, shell=True)
+        except CalledProcessError as e:
+            logger.debug(
+                f"  |- Bitwarden CLI command failed with exit code {e.returncode}"
+            )
+            if isinstance(e.output, bytes):
+                output = e.output
+            else:
+                output = str(e.output).encode("utf-8", "ignore")
+
+        logger.debug(f"  |- Received {len(output)} bytes from Bitwarden CLI")
+        return output.decode("utf-8", "ignore")
+
+    def _get_existing_folder_entries(self) -> dict[str | None, list[str]]:
+        folder_id_lookup_helper: dict[str, str] = {
+            folder_id: folder_name for folder_name, folder_id in self._folders.items()
+        }
+        items: list[dict[str, Any]] = json.loads(
+            self._exec_with_session("bw list items")
+        )
+
+        # fix None folderIds for entries without folders
+        for item in items:
+            if not item["folderId"]:
+                item["folderId"] = ""
+
+        items.sort(key=lambda item: item["folderId"])
+        return {
+            folder_id_lookup_helper.get(folder_id): [entry["name"] for entry in entries]
+            for folder_id, entries in groupby(items, key=lambda item: item["folderId"])
+        }
+
+    def _exec_with_session(self, command: str) -> str:
+        return self._exec(f"{command} --session '{self._key}'")
+
+    def has_folder(self, folder: str | None) -> bool:
+        return folder in self._folders
+
+    def _get_platform_dependent_echo_str(self, string: str) -> str:
+        if platform.system() == "Windows":
+            return f"echo {string}"
+        else:
+            return f"echo '{string}'"
+
+    def create_folder(self, folder: str | None) -> None:
+        if not folder or self.has_folder(folder):
+            return
+
+        data: dict[str, str] = {"name": folder}
+        data_b64 = base64.b64encode(json.dumps(data).encode("UTF-8")).decode("UTF-8")
+
+        output = self._exec_with_session(
+            f"{self._get_platform_dependent_echo_str(data_b64)} | bw create folder"
+        )
+
+        output_obj: dict[str, str] = json.loads(output)
+
+        self._folders[output_obj["name"]] = output_obj["id"]
+
+    def create_entry(self, folder: str | None, entry: dict[str, Any]) -> str:
+        # check if already exists
+        if (
+            folder in self._folder_entries
+            and entry["name"] in self._folder_entries[folder]
+        ):
+            logger.info(
+                f"-- Entry {entry['name']} already exists in folder {folder}. skipping..."
+            )
+            return "skip"
+
+        # create folder if exists
+        if folder:
+            self.create_folder(folder)
+
+            # set id
+            entry["folderId"] = self._folders[folder]
+
+        json_str = json.dumps(entry)
+
+        # convert string to base64
+        json_b64 = base64.b64encode(json_str.encode("UTF-8")).decode("UTF-8")
+
+        return self._exec_with_session(
+            f"{self._get_platform_dependent_echo_str(json_b64)} | bw create item"
+        )
+
+    def create_attachment(
+        self, item_id: str, attachment: tuple[str, str] | Attachment
+    ) -> str:
+        # store attachment on disk
+        filename: str
+        data: bytes
+        if not isinstance(attachment, Attachment):
+            # long custom property — tuple[str, str]
+            filename = attachment[0] + ".txt"
+            data = attachment[1].encode("UTF-8")
+        else:
+            # real kp attachment
+            if attachment.filename is None:
+                logger.warning("Attachment has no filename, using fallback")
+                filename = "attachment"
+            else:
+                filename = attachment.filename
+            data = attachment.data
+
+        # make sure temporary attachment folder exists
+        self._create_temporary_attachment_folder()
+
+        path_to_file_on_disk = os.path.join(self.TEMPORARY_ATTACHMENT_FOLDER, filename)
+        with open(path_to_file_on_disk, "wb") as f:
+            _ = f.write(data)
+
+        try:
+            output = self._exec_with_session(
+                f'bw create attachment --file "{path_to_file_on_disk}" --itemid {item_id}'
+            )
+        finally:
+            os.remove(path_to_file_on_disk)
+
+        return output
+
+    def create_org_get_collection(self, collectionname: str | None) -> str | None:
+        if not collectionname:
+            return None
+
+        if self._colls is None:
+            self._colls = {}
+
+        # check for existing
+        if self._colls.get(collectionname):
+            return self._colls.get(collectionname)
+
+        # get template
+        entry: dict[str, Any] = json.loads(
+            self._exec_with_session("bw get template org-collection")
+        )
+
+        # set org and Name
+        entry["name"] = collectionname
+        entry["organizationId"] = self._orgId
+
+        json_str = json.dumps(entry)
+
+        # convert string to base64
+        json_b64 = base64.b64encode(json_str.encode("UTF-8")).decode("UTF-8")
+
+        output = self._exec_with_session(
+            f"{self._get_platform_dependent_echo_str(json_b64)} | bw create  org-collection --organizationid {self._orgId}"
+        )
+        if not output:
+            return None
+        data: dict[str, Any] = json.loads(output)
+        if not data["id"]:
+            return None
+        new_coll_id: str = data["id"]
+
+        # store in cache
+        self._colls[collectionname] = new_coll_id
+
+        return new_coll_id