pw-connector 0.3.0__tar.gz

pw_connector-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+Лицензия MIT
+
+Авторские права (c) 2026 ООО Пассворк
+
+Настоящим предоставляется бесплатное разрешение любому лицу, получившему копию
+данного программного обеспечения и сопутствующей документации (далее — «Программное обеспечение»),
+использовать Программное обеспечение без ограничений, включая, но не ограничиваясь,
+права на использование, копирование, изменение, объединение, публикацию, распространение,
+сублицензирование и/или продажу копий Программного обеспечения, а также лицам, которым
+предоставляется данное Программное обеспечение, при соблюдении следующих условий:
+
+Указанное выше уведомление об авторских правах и данное разрешение должны быть включены
+во все копии или значимые части Программного обеспечения.
+
+ПРОГРАММНОЕ ОБЕСПЕЧЕНИЕ ПРЕДОСТАВЛЯЕТСЯ «КАК ЕСТЬ», БЕЗ КАКИХ-ЛИБО ГАРАНТИЙ,
+ЯВНЫХ ИЛИ ПОДРАЗУМЕВАЕМЫХ, ВКЛЮЧАЯ, НО НЕ ОГРАНИЧИВАЯСЬ, ГАРАНТИИ ТОВАРНОЙ ПРИГОДНОСТИ,
+СООТВЕТСТВИЯ ПО ЕГО КОНКРЕТНОМУ НАЗНАЧЕНИЮ И ОТСУТСТВИЯ НАРУШЕНИЙ ПРАВ. НИ В КАКОМ СЛУЧАЕ
+АВТОРЫ ИЛИ ПРАВООБЛАДАТЕЛИ НЕ НЕСУТ ОТВЕТСТВЕННОСТИ ПО ИСКАМ О ВОЗМЕЩЕНИИ УЩЕРБА, УБЫТКОВ
+ИЛИ ДРУГИХ ТРЕБОВАНИЙ ПО ДЕЙСТВУЮЩИМ КОНТРАКТАМ, ДЕЛИКТАМ ИЛИ ИНОМУ, ВОЗНИКШИМ ИЗ, ИМЕЮЩИМ
+ПРИЧИНОЙ ИЛИ СВЯЗАННЫМ С ПРОГРАММНЫМ ОБЕСПЕЧЕНИЕМ ИЛИ ИСПОЛЬЗОВАНИЕМ ПРОГРАММНОГО ОБЕСПЕЧЕНИЯ
+ИЛИ ИНЫМИ ДЕЙСТВИЯМИ С ПРОГРАММНЫМ ОБЕСПЕЧЕНИЕМ.

pw_connector-0.3.0/PKG-INFO

@@ -0,0 +1,39 @@
+Metadata-Version: 2.4
+Name: pw-connector
+Version: 0.3.0
+Summary: Python SDK and CLI for a zero-knowledge password vault API
+Home-page: https://gitverse.ru/passwork-ru/passwork-python
+Author: pw-connector
+License: MIT
+Project-URL: Issues, https://gitverse.ru/passwork-ru/passwork-python/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Security :: Cryptography
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests<3.0,>=2.31
+Requires-Dist: python-dotenv<2.0,>=1.0
+Requires-Dist: cryptography<49,>=48.0.1
+Requires-Dist: pbkdf2<2.0,>=1.3
+Requires-Dist: horcrux==1.3.0
+Dynamic: author
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license
+Dynamic: license-file
+Dynamic: project-url
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# pw-connector
+
+Python SDK and CLI for a zero-knowledge password vault API (client-side encryption, vault/item operations, DevOps secret injection).

pw_connector-0.3.0/README.md

@@ -0,0 +1,27 @@
+## Python-коннектор, CLI и Docker для Пассворка
+
+Официальный репозиторий Python-коннектора, CLI-утилиты и Docker-образов для интеграции с API Пассворка. Используйте Python-коннектор для программного доступа и клиентского шифрования, CLI для DevOps-задач и прямых вызовов API, а Docker — для запуска инструментов в пайплайнах.
+
+### Компоненты
+
+- `passwork_client/` — Python-библиотека для программной интеграции с Пассворком. Обеспечивает клиентское шифрование (работа с мастер-ключом), управление сессиями и удобные API для CRUD-операций над объектами Пассворка (паролями, сейфами, пользователями, ярлыками, снимками). Подходит для бэкенд-сервисов, скриптов автоматизации и кастомных инструментов.
+- `cli/` — `passwork-cli`, консольная утилита для DevOps и SRE, позволяющая использовать Пассворк в качестве менеджера секретов. Получайте и внедряйте секреты в переменные окружения или параметры команд, ищите по тегам и папкам, работайте с пользовательскими полями, обновляйте токены и выполняйте прямые вызовы API. Предназначена для локального использования, серверов и эфемерных CI-агентов.
+- `docker/` — Docker-образы для запуска CLI в контейнерах в рамках CI/CD (GitHub Actions, GitLab CI, Bitbucket Pipelines и др.). Обеспечивает изолированную среду выполнения без локальных зависимостей Python; включает Dockerfile и примеры конфигурации пайплайнов для быстрой интеграции.
+
+### Документация
+
+- [Введение в API и интеграции](https://passwork.ru/docs/api-and-integrations/intro/)
+- [Руководство по Python-коннектору](https://passwork.ru/docs/api-and-integrations/python-connector/)
+- [Руководство по CLI-утилите](https://passwork.ru/docs/api-and-integrations/cli-utility/)
+- [Docker-контейнер для CLI](https://passwork.ru/docs/api-and-integrations/docker-container-for-cli/)
+- [Восстановление доступа по схеме Шамира](https://passwork.ru/docs/recovery/intro)
+
+### Примеры использования
+
+Примеры работы с Python-коннектором и CLI находятся в отдельном репозитории:
+
+- Примеры интеграции с API Пассворка (включая восстановление по схеме Шамира): [passwork-ru/passwork-integration-examples](https://gitverse.ru/passwork-ru/passwork-integration-examples)
+
+### Восстановление по схеме Шамира
+
+Пороговое восстановление доступа администратора к сейфу (M из N): `passwork-cli shamir` / `rsa` / `users create-service-account` / `recovery grant-admin`. Требуются клиентское шифрование и Python ≥ 3.11 (`horcrux==1.3.0`). Подробности — в документации и примерах выше.

pw_connector-0.3.0/cli/__init__.py

@@ -0,0 +1,2 @@
+# This file marks the directory as a Python package
+from .main import main

pw_connector-0.3.0/cli/commands/__init__.py

@@ -0,0 +1,20 @@
+from .exec_command import ExecuteCommandStrategy
+from .api_command import ApiCallStrategy
+from .get_command import GetCommandStrategy
+from .update_command import UpdateCommandStrategy
+from .shamir_command import ShamirCommand
+from .rsa_command import RsaCommand
+from .users_command import UsersCommand
+from .recovery_command import RecoveryCommand
+
+# Create a mapping of command names to strategy classes
+COMMAND_STRATEGIES = {
+    "exec": ExecuteCommandStrategy,
+    "api": ApiCallStrategy,
+    "get": GetCommandStrategy,
+    "update": UpdateCommandStrategy,
+    "shamir": ShamirCommand,
+    "rsa": RsaCommand,
+    "users": UsersCommand,
+    "recovery": RecoveryCommand,
+}

pw_connector-0.3.0/cli/commands/api_command.py

@@ -0,0 +1,106 @@
+#!/usr/bin/env python3
+import sys
+import json
+from .base import PassworkCommand
+
+
+class ApiCallStrategy(PassworkCommand):
+    """
+    Strategy for making direct API calls to the Passwork API.
+    """
+    def execute(self, client, args):
+        try:
+            # Parse the parameters if provided
+            payload = {}
+            if args.params:
+                try:
+                    payload = json.loads(args.params)
+                except json.JSONDecodeError as e:
+                    print(f"Error parsing parameters JSON: {e}", file=sys.stderr)
+                    return 1
+
+            # Format the endpoint correctly (add /api/ prefix)
+            endpoint = args.endpoint
+            # Remove leading slash if present
+            if endpoint.startswith('/'):
+                endpoint = endpoint[1:]
+            # Add /api/ prefix
+            endpoint = f"/api/{endpoint}"
+
+            # Execute the API call using the updated call method
+            response = client.call(
+                method=args.method,
+                endpoint=endpoint,
+                payload=payload
+            )
+
+            # Extract field from response if specified
+            if args.field:
+                extracted_data = self._extract_field(response, args.field)
+                # Print the extracted data
+                print(json.dumps(extracted_data, indent=2))
+            else:
+                # Print the full response as JSON
+                print(json.dumps(response, indent=2))
+
+            return 0
+
+        except Exception as e:
+            print(f"Error making API call: {e}", file=sys.stderr)
+            return 1
+
+    def _extract_field(self, data, field_name):
+        """
+        Extract a specific field from the API response.
+        If the response is an array, extract the field from each item.
+        Args:
+            data: The API response data (dict or list)
+            field_name: Name of the field to extract
+        Returns:
+            The extracted field value or list of values
+        """
+        # If data is a list, extract field from each item
+        if isinstance(data, list):
+            result = []
+            for item in data:
+                if isinstance(item, dict) and field_name in item:
+                    result.append(item[field_name])
+            return result
+
+        # If data is a dict, extract the field
+        elif isinstance(data, dict):
+            # Handle nested fields using dot notation (e.g., "user.name")
+            if "." in field_name:
+                parts = field_name.split(".", 1)  # Split into first part and rest
+                if parts[0] in data and isinstance(data[parts[0]], (dict, list)):
+                    return self._extract_field(data[parts[0]], parts[1])
+                return None
+
+            # Handle extracting from a nested array using brackets (e.g., "items[0]")
+            elif "[" in field_name and field_name.endswith("]"):
+                base_name, index_str = field_name.split("[", 1)
+                index = int(index_str[:-1])  # Remove the closing bracket and convert to int
+
+                if base_name in data and isinstance(data[base_name], list) and 0 <= index < len(data[base_name]):
+                    return data[base_name][index]
+                return None
+
+            # Simple field extraction
+            elif field_name in data:
+                return data[field_name]
+
+        # Field not found or data type not supported
+        return None
+
+    @staticmethod
+    def add_command(subparsers):
+        params = PassworkCommand.base_params() | {
+            "--method": {"required": True, "choices": ["GET", "POST", "PUT", "PATCH", "DELETE"], "help": "HTTP method"},
+            "--endpoint": {"required": True, "help": "API endpoint (e.g. v1/items) without leading /api/"},
+            "--params": {"help": "JSON string of parameters to pass to the API call"},
+            "--field": {"help": "Field to extract from the API response"}
+        }
+
+        parser = subparsers.add_parser("api", help="Make a direct API call to Passwork")
+        for key, value in params.items():
+            parser.add_argument(key, **value)

pw_connector-0.3.0/cli/commands/base.py

@@ -0,0 +1,79 @@
+#!/usr/bin/env python3
+from abc import ABC, abstractmethod
+
+
+class PassworkCommand(ABC):
+    """
+    Abstract base class for Passwork CLI command strategies.
+    """
+    requires_client = True
+
+    @abstractmethod
+    def execute(self, client, args):
+        """
+        Execute the command strategy.
+        Args:
+            client (PassworkClient): Initialized Passwork client
+            args (Namespace): Command line arguments
+        Returns:
+            int: Exit code
+        """
+        pass
+
+    @staticmethod
+    def add_command(subparsers):
+        pass
+
+    @staticmethod
+    def base_params():
+        return {
+            "--host": {"help": "Passwork API host URL"},
+            "--token": {"help": "Passwork access token"},
+            "--refresh-token": {"help": "Passwork refresh token"},
+            "--master-key": {"help": "Passwork master key for decryption"},
+            "--no-ssl-verify": {
+                "action": "store_true",
+                "help": "Disable SSL certificate verification. DEPRECATED: use --ssl-verify (boolean mode)",
+            },
+            "--ssl-verify": {
+                "help": "Enable SSL verification (or provide CA bundle path)",
+                "nargs": "?",
+                "const": True,
+            },
+        }
+
+
+class ItemBaseCommand:
+    def _get_password(self, client, args):
+        """
+        Get password based on the provided arguments.
+        Strategy: If password_id is provided, get a single password
+        If shortcut_id is provided, get a single password
+        Returns:
+            dict: password object or shortcut object
+        """
+        # Case 1: Password ID
+        if hasattr(args, 'password_id') and args.password_id:
+            # Trim the parameter
+            password_id = args.password_id.strip()
+            if not password_id:
+                return {}
+
+            # Single ID
+            return client.get_item(password_id)
+
+        # Case 1: Shortcut ID(s)
+        if hasattr(args, 'shortcut_id') and args.shortcut_id:
+            # Trim the parameter
+            shortcut_id = args.shortcut_id.strip()
+            if not shortcut_id:
+                return {}
+
+            # Single ID
+            shortcut = client.get_shortcut(shortcut_id)
+            if shortcut['password']:
+                return shortcut['password']
+
+            return {}
+
+        raise ValueError("No password ID or shortcut ID criteria provided")

pw_connector-0.3.0/cli/commands/exec_command.py

@@ -0,0 +1,220 @@
+#!/usr/bin/env python3
+import os
+import re
+import sys
+import subprocess
+from .base import PassworkCommand
+
+
+class ExecuteCommandStrategy(PassworkCommand):
+    """
+    Strategy for retrieving passwords and executing a command with them
+    as environment variables.
+    Supports:
+    1. Single password by ID
+    2. Multiple passwords by IDs
+    3. Password search by vault ID, folder ID, or tags
+    """
+    def execute(self, client, args):
+        try:
+            # Get passwords based on provided parameters
+            passwords = self._get_passwords(client, args)
+
+            if not passwords:
+                print("Error: No passwords found", file=sys.stderr)
+                return 1
+
+            # Set up environment with passwords
+            env = os.environ.copy()
+
+            # Add each password to environment variables
+            for password_item in passwords:
+                # Use sanitized password name as environment variable name
+                env_var_name = self._sanitize_env_var_name(password_item.get("name", "PASSWORD"))
+
+                item = password_item
+                if "password" in password_item and type(password_item["password"]) is dict:
+                    item = password_item["password"]
+
+                # Set password as environment variable
+                if "password" in item:
+                    env[env_var_name] = item["password"]
+
+                # Process custom fields of type "text" or "password"
+                if "customs" in item and item["customs"]:
+                    for custom in item["customs"]:
+                        if custom.get("type") in ["text", "password"] and "name" in custom and "value" in custom:
+                            # Sanitize custom field name to make a valid environment variable
+                            custom_env_var = self._sanitize_env_var_name(custom["name"])
+                            env[custom_env_var] = custom["value"]
+
+            # Execute the command
+            process = subprocess.run(args.cmd, shell=True, env=env)
+
+            return process.returncode
+
+        except Exception as e:
+            print(f"Error executing command: {e}", file=sys.stderr)
+            return 1
+
+    def _get_passwords(self, client, args):
+        """
+        Get passwords based on the provided arguments.
+        Strategy:
+        1. If password_id is provided, get a single password or multiple (if comma-separated)
+        2. If search parameters are provided, search for passwords
+        Returns:
+            list: List of password objects
+        """
+        # Case 1: Password ID(s)
+        if hasattr(args, 'password_id') and args.password_id:
+            # Trim the parameter
+            password_id = args.password_id.strip()
+            if not password_id:
+                return []
+
+            # Check if it contains multiple IDs (comma-separated)
+            if ',' in password_id:
+                # Split by comma, clean each value and filter out empty ones
+                id_list = [id.strip() for id in password_id.split(',')]
+                id_list = [id for id in id_list if id]
+
+                if not id_list:
+                    return []
+
+                # If we have multiple IDs, get all of them
+                if len(id_list) > 1:
+                    return client.get_items(id_list)
+                # If we only have one ID after cleaning, use it as a single ID
+                else:
+                    password = client.get_item(id_list[0])
+                    return [password] if password else []
+
+            # Single ID
+            password = client.get_item(password_id)
+            return [password] if password else []
+
+        # Case 1: Shortcut ID(s)
+        if hasattr(args, 'shortcut_id') and args.shortcut_id:
+            # Trim the parameter
+            shortcut_id = args.shortcut_id.strip()
+            if not shortcut_id:
+                return []
+
+            # Check if it contains multiple IDs (comma-separated)
+            if ',' in shortcut_id:
+                # Split by comma, clean each value and filter out empty ones
+                id_list = [id.strip() for id in shortcut_id.split(',')]
+                id_list = [id for id in id_list if id]
+
+                if not id_list:
+                    return []
+
+                # If we have multiple IDs, get all of them
+                if len(id_list) > 1:
+                    return client.get_shortcut_items(id_list)
+                # If we only have one ID after cleaning, use it as a single ID
+                else:
+                    shortcut = client.get_shortcut(id_list[0])
+                    return [shortcut] if shortcut else []
+
+            # Single ID
+            shortcut = client.get_shortcut(shortcut_id)
+            return [shortcut] if shortcut else []
+
+        # Case 2: Search parameters
+        search_params = {}
+
+        # Check if any search parameter is provided and process it
+        # Vault IDs
+        if hasattr(args, 'vault_id') and args.vault_id:
+            # Trim and validate
+            vault_id = args.vault_id.strip()
+            if vault_id:
+                # Process as list if contains commas
+                if ',' in vault_id:
+                    values = [item.strip() for item in vault_id.split(',')]
+                    values = [item for item in values if item]
+                    if values:
+                        search_params['vault_ids'] = values
+                else:
+                    search_params['vault_ids'] = [vault_id]
+
+        # Folder IDs
+        if hasattr(args, 'folder_id') and args.folder_id:
+            # Trim and validate
+            folder_id = args.folder_id.strip()
+            if folder_id:
+                # Process as list if contains commas
+                if ',' in folder_id:
+                    values = [item.strip() for item in folder_id.split(',')]
+                    values = [item for item in values if item]
+                    if values:
+                        search_params['folder_ids'] = values
+                else:
+                    search_params['folder_ids'] = [folder_id]
+
+        # Tags
+        if hasattr(args, 'tags') and args.tags:
+            # Trim and validate
+            tags = args.tags.strip()
+            if tags:
+                # Process as list if contains commas
+                if ',' in tags:
+                    values = [item.strip() for item in tags.split(',')]
+                    values = [item for item in values if item]
+                    if values:
+                        search_params['tags'] = values
+                else:
+                    search_params['tags'] = [tags]
+
+        # If no search parameters, throw error
+        if not search_params:
+            raise ValueError("No password ID or search criteria provided")
+
+        # Search and decrypt
+        items = client.search_and_decrypt(**search_params)
+        items.extend(client.search_and_decrypt_shortcut(**search_params))
+        return items
+
+    def _sanitize_env_var_name(self, name):
+        """
+        Sanitize a name to make it a valid environment variable name.
+        Rules:
+        1. Replace non-alphanumeric with underscore
+        2. Ensure starts with a letter
+        Args:
+            name (str): Original name
+        Returns:
+            str: Sanitized environment variable name
+        """
+        # Replace non-alphanumeric with underscore
+        sanitized = re.sub(r'[^a-zA-Z0-9]', '_', name)
+
+        # Ensure starts with a letter
+        if not sanitized[0].isalpha():
+            sanitized = 'P_' + sanitized
+
+        return sanitized
+
+    @staticmethod
+    def add_command(subparsers):
+        parser = subparsers.add_parser("exec", help="Execute a command with passwords as environment variables")
+
+        params = PassworkCommand.base_params()
+        for key, value in params.items():
+            parser.add_argument(key, **value)
+
+        group_param = {
+            "--password-id": {"help": "ID of password(s) to retrieve (comma-separated for multiple)"},
+            "--shortcut-id": {"help": "ID of shortcut(s) to retrieve (comma-separated for multiple)"},
+            "--vault-id": {"help": "ID(s) of vault(s) to search in (comma-separated for multiple)"},
+            "--folder-id": {"help": "ID(s) of folder(s) to search in (comma-separated for multiple)"},
+            "--tags": {"help": "Tag(s) to search for (comma-separated for multiple)"},
+        }
+
+        group = parser.add_argument_group("Password identification (at least one required)")
+        for key, value in group_param.items():
+            group.add_argument(key, **value)
+
+        parser.add_argument("--cmd", help="Command to execute")

pw_connector-0.3.0/cli/commands/get_command.py

@@ -0,0 +1,80 @@
+#!/usr/bin/env python3
+import sys
+from .base import PassworkCommand, ItemBaseCommand
+from passwork_client.utils import generate_totp, generate_totp_by_url
+
+
+class GetCommandStrategy(PassworkCommand, ItemBaseCommand):
+
+    def execute(self, client, args):
+        try:
+            # Get passwords based on provided parameters
+            password = self._get_password(client, args)
+            if not password:
+                print("Error: Password not found", file=sys.stderr)
+                return 1
+
+            if args.totp_code:
+                secret = self._extract_field(password, args.totp_code)
+                if not secret:
+                    print("Error: TOTP secret not found", file=sys.stderr)
+                    return 1
+
+                print(self._generate_totp(secret))
+                return 0
+
+            if args.field:
+                print(self._extract_field(password, args.field))
+            else:
+
+                if "password" in password and password["password"]:
+                    print(password["password"])
+                else:
+                    print("The password is not filled in or is empty", file=sys.stderr)
+                    return 1
+
+            return 0
+
+        except Exception as e:
+            print(f"Error getting password command: {e}", file=sys.stderr)
+            return 1
+
+    def _extract_field(self, data, field_name):
+        customs = data.get("customs") or []
+        if customs:
+            for custom in customs:
+                if custom["name"] == field_name:
+                    return custom["value"]
+
+        if field_name in data:
+            return data[field_name]
+
+        # Field not found
+        return None
+
+    def _generate_totp(self, secret: str):
+
+        if "otpauth://" in secret.lower():
+            return generate_totp_by_url(secret)
+
+        return generate_totp(secret)
+
+    @staticmethod
+    def add_command(subparsers):
+        parser = subparsers.add_parser("get", help="Get password/shortcut from Passwork")
+
+        params = PassworkCommand.base_params() | {
+            "--field": {"help": "Show item field"},
+            "--totp-code": {"help": "Returned TOTP code"}
+        }
+        for key, value in params.items():
+            parser.add_argument(key, **value)
+
+        group_param = {
+            "--password-id": {"help": "ID of password to retrieve"},
+            "--shortcut-id": {"help": "ID of shortcut to retrieve"},
+        }
+
+        group = parser.add_argument_group("Password identification (at least one required)")
+        for key, value in group_param.items():
+            group.add_argument(key, **value)