jkey 0.1.2__tar.gz

jkey-0.1.2/PKG-INFO

@@ -0,0 +1,105 @@
+Metadata-Version: 2.4
+Name: jkey
+Version: 0.1.2
+Summary: Python library for password management and TOTP verification.
+Author-email: jiaoyuan <imjiaoyuan@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/imjiaoyuan/jkey
+Project-URL: Repository, https://github.com/imjiaoyuan/jkey
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: opencv-python-headless>=4.9.0
+
+# jkey
+
+Python library for password management and TOTP verification.
+
+## Install
+
+```bash
+uv tool install jkey
+```
+
+Or run without installing:
+
+```bash
+uv run jkey --help
+```
+
+## Quick Start
+
+```bash
+# Initialize vault (set master password)
+jkey pv init
+
+# Add a 2FA account
+jkey 2fa add github JBSWY3DPEHPK3PXP
+
+# Get current TOTP code
+jkey 2fa get github
+
+# Import from QR code image
+jkey 2fa qr ./github.jpg
+
+# Generate a random password
+jkey pm gen -L 24
+
+# Store a password
+jkey pm add my-site
+
+# List all stored passwords
+jkey pm ls
+
+# Encrypt/decrypt any file
+jkey pv encrypt secret.pdf
+jkey pv decrypt secret.pdf.jkey -o secret.pdf
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `jkey 2fa ls [keyword]` | List TOTP accounts and codes |
+| `jkey 2fa get <account>` | Show TOTP code for an account |
+| `jkey 2fa add <name> <secret>` | Add a TOTP account |
+| `jkey 2fa qr <image>` | Import from QR code image |
+| `jkey 2fa rm <account>` | Remove a TOTP account |
+| `jkey pm gen [-L N]` | Generate a random password |
+| `jkey pm ls [keyword]` | List stored passwords |
+| `jkey pm get <name>` | Show a stored password |
+| `jkey pm add <name>` | Store a password (prompts for input) |
+| `jkey pm rm <name>` | Delete a stored password |
+| `jkey pm import <csv>` | Import passwords from CSV (name,password) |
+| `jkey pv init` | Initialize the encrypted vault |
+| `jkey pv unlock` | Unlock the vault |
+| `jkey pv lock` | Lock the vault |
+| `jkey pv set-pw` | Change master password |
+| `jkey pv encrypt <file>` | Encrypt a file |
+| `jkey pv decrypt <file>` | Decrypt a `.jkey` file |
+| `jkey pv export totp` | Export TOTP secrets (re-enters master password) |
+| `jkey pv export passwords` | Export passwords as CSV |
+| `jkey pv export recovery` | Export recovery codes |
+| `jkey pv export qr -o <dir>` | Export QR code images |
+| `jkey pv export all -o <dir>` | Export everything |
+
+Set `JKEY_PASS` environment variable to skip the password prompt.
+
+## How It Works
+
+Data is encrypted with AES-256-CBC + HMAC-SHA256 and stored in `~/.config/jkey/`:
+
+```
+~/.config/jkey/
+├── totp.jkey        # Encrypted TOTP secrets
+├── passwords.jkey   # Encrypted passwords
+├── recovery.jkey    # Encrypted recovery codes
+└── qr/              # Encrypted QR images
+```
+
+Back up `~/.config/jkey/` to migrate to another machine.
+
+## Dependencies
+
+- `opencv-python-headless` — QR code scanning
+
+Pure Python, no OpenSSL or libsodium required.

jkey-0.1.2/README.md

@@ -0,0 +1,93 @@
+# jkey
+
+Python library for password management and TOTP verification.
+
+## Install
+
+```bash
+uv tool install jkey
+```
+
+Or run without installing:
+
+```bash
+uv run jkey --help
+```
+
+## Quick Start
+
+```bash
+# Initialize vault (set master password)
+jkey pv init
+
+# Add a 2FA account
+jkey 2fa add github JBSWY3DPEHPK3PXP
+
+# Get current TOTP code
+jkey 2fa get github
+
+# Import from QR code image
+jkey 2fa qr ./github.jpg
+
+# Generate a random password
+jkey pm gen -L 24
+
+# Store a password
+jkey pm add my-site
+
+# List all stored passwords
+jkey pm ls
+
+# Encrypt/decrypt any file
+jkey pv encrypt secret.pdf
+jkey pv decrypt secret.pdf.jkey -o secret.pdf
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `jkey 2fa ls [keyword]` | List TOTP accounts and codes |
+| `jkey 2fa get <account>` | Show TOTP code for an account |
+| `jkey 2fa add <name> <secret>` | Add a TOTP account |
+| `jkey 2fa qr <image>` | Import from QR code image |
+| `jkey 2fa rm <account>` | Remove a TOTP account |
+| `jkey pm gen [-L N]` | Generate a random password |
+| `jkey pm ls [keyword]` | List stored passwords |
+| `jkey pm get <name>` | Show a stored password |
+| `jkey pm add <name>` | Store a password (prompts for input) |
+| `jkey pm rm <name>` | Delete a stored password |
+| `jkey pm import <csv>` | Import passwords from CSV (name,password) |
+| `jkey pv init` | Initialize the encrypted vault |
+| `jkey pv unlock` | Unlock the vault |
+| `jkey pv lock` | Lock the vault |
+| `jkey pv set-pw` | Change master password |
+| `jkey pv encrypt <file>` | Encrypt a file |
+| `jkey pv decrypt <file>` | Decrypt a `.jkey` file |
+| `jkey pv export totp` | Export TOTP secrets (re-enters master password) |
+| `jkey pv export passwords` | Export passwords as CSV |
+| `jkey pv export recovery` | Export recovery codes |
+| `jkey pv export qr -o <dir>` | Export QR code images |
+| `jkey pv export all -o <dir>` | Export everything |
+
+Set `JKEY_PASS` environment variable to skip the password prompt.
+
+## How It Works
+
+Data is encrypted with AES-256-CBC + HMAC-SHA256 and stored in `~/.config/jkey/`:
+
+```
+~/.config/jkey/
+├── totp.jkey        # Encrypted TOTP secrets
+├── passwords.jkey   # Encrypted passwords
+├── recovery.jkey    # Encrypted recovery codes
+└── qr/              # Encrypted QR images
+```
+
+Back up `~/.config/jkey/` to migrate to another machine.
+
+## Dependencies
+
+- `opencv-python-headless` — QR code scanning
+
+Pure Python, no OpenSSL or libsodium required.

jkey-0.1.2/pyproject.toml

@@ -0,0 +1,36 @@
+[project]
+name = "jkey"
+version = "0.1.2"
+description = "Python library for password management and TOTP verification."
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [{name = "jiaoyuan", email = "imjiaoyuan@gmail.com"}]
+license = {text = "MIT"}
+dependencies = ["opencv-python-headless>=4.9.0"]
+
+[project.urls]
+Homepage = "https://github.com/imjiaoyuan/jkey"
+Repository = "https://github.com/imjiaoyuan/jkey"
+
+[project.scripts]
+jkey = "jkey.cli:main"
+
+[build-system]
+requires = ["setuptools>=64"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[dependency-groups]
+dev = ["pytest>=8", "ruff>=0.11"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

jkey-0.1.2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

jkey-0.1.2/src/jkey/2fa/core.py

@@ -0,0 +1,124 @@
+import base64
+import hashlib
+import hmac
+import os
+import struct
+import time
+
+from jkey.pv.core import load_recovery, load_totp, save_recovery, save_totp
+
+
+def _hotp(secret: bytes, counter: int, digits: int = 6) -> str:
+    msg = struct.pack(">Q", counter)
+    h = hmac.new(secret, msg, hashlib.sha1).digest()
+    offset = h[-1] & 0xf
+    truncated = struct.unpack(">I", h[offset:offset+4])[0] & 0x7fffffff
+    return str(truncated % (10 ** digits)).zfill(digits)
+
+
+def _b32_decode(s: str) -> bytes:
+    s = s.upper().replace(" ", "")
+    remainder = len(s) % 8
+    if remainder:
+        s += "=" * (8 - remainder)
+    return base64.b32decode(s)
+
+
+def _validate_b32_secret(s: str) -> bool:
+    try:
+        _b32_decode(s)
+        return True
+    except Exception:
+        return False
+
+
+def totp(secret_key: str, digits: int = 6, interval: int = 30) -> str:
+    secret = _b32_decode(secret_key)
+    counter = int(time.time()) // interval
+    return _hotp(secret, counter, digits)
+
+
+def _import_recovery_file(account: str, recovery_path: str | None):
+    if not recovery_path:
+        return
+    if not os.path.exists(recovery_path):
+        print(f"Warning: Recovery file not found: {recovery_path}")
+        return
+    try:
+        with open(recovery_path, "r", encoding="utf-8") as f:
+            codes = [line.strip() for line in f if line.strip()]
+        if codes:
+            data = load_recovery()
+            if data is None:
+                return
+            data[account] = codes
+            save_recovery(data)
+            print(f"Imported {len(codes)} recovery codes for {account}")
+    except OSError as e:
+        print(f"Warning: Could not read recovery file: {e}")
+
+
+def list_accounts(keyword: str | None = None):
+    data = load_totp()
+    if data is None:
+        return
+    if not data:
+        print("No 2FA accounts found.")
+        return
+    keys = sorted(data.keys())
+    if keyword:
+        keys = [k for k in keys if keyword.lower() in k.lower()]
+        if not keys:
+            print(f"No accounts matching '{keyword}'.")
+            return
+    for acc_id in keys:
+        secret = data[acc_id]
+        try:
+            print(f"{acc_id}: {totp(secret)}")
+        except Exception as e:
+            print(f"Error processing '{acc_id}': {e}")
+
+
+def show_code(account: str):
+    data = load_totp()
+    if data is None:
+        return
+    if account not in data:
+        print(f"Error: Account '{account}' not found.")
+        return
+    secret = data[account]
+    try:
+        print(f"{account}: {totp(secret)}")
+    except Exception as e:
+        print(f"Error processing '{account}': {e}")
+
+
+def add_account(name: str, secret: str, recovery_path: str | None = None):
+    if not _validate_b32_secret(secret):
+        print(f"Error: Invalid base32 secret for '{name}'.")
+        return
+    data = load_totp()
+    if data is None:
+        return
+    data[name] = secret
+    save_totp(data)
+    print(f"Added 2FA account: {name}")
+    _import_recovery_file(name, recovery_path)
+
+
+def remove_account(account: str):
+    data = load_totp()
+    if data is None:
+        return
+    if account not in data:
+        print(f"Error: Account '{account}' not found.")
+        return
+    del data[account]
+    save_totp(data)
+
+    rc = load_recovery()
+    if rc and account in rc:
+        del rc[account]
+        save_recovery(rc)
+
+    print(f"Removed 2FA account: {account}")

jkey-0.1.2/src/jkey/2fa/qr.py

@@ -0,0 +1,65 @@
+import importlib
+import os
+from urllib.parse import parse_qs, unquote, urlparse
+
+import cv2
+
+from jkey.pv.core import load_totp, save_qr_image, save_totp
+
+_core = importlib.import_module("jkey.2fa.core")
+_import_recovery_file = _core._import_recovery_file
+
+
+def scan_and_add(image_path: str, recovery_path: str | None = None):
+    if not os.path.exists(image_path):
+        print(f"Error: File not found: {image_path}")
+        return
+
+    img = cv2.imread(image_path)
+    if img is None:
+        print(f"Error: Could not read image: {image_path}")
+        return
+
+    detector = cv2.QRCodeDetector()
+    data, _, _ = detector.detectAndDecode(img)
+    if not data:
+        print("Error: No QR code found in the image.")
+        return
+
+    parsed = urlparse(data)
+    if parsed.scheme != "otpauth":
+        print(f"Error: Not a valid otpauth:// URL: {data}")
+        return
+
+    params = parse_qs(parsed.query)
+    secret = params.get("secret", [None])[0]
+    if not secret:
+        print("Error: No secret found in QR code.")
+        return
+
+    path = unquote(parsed.path).lstrip("/")
+    issuer = params.get("issuer", [None])[0]
+
+    if issuer and path.startswith(issuer + ":"):
+        name = path[len(issuer) + 1:]
+    elif issuer and ":" in path:
+        name = path
+    else:
+        name = path
+
+    if not name:
+        name = issuer or "unknown"
+
+    data = load_totp()
+    if data is None:
+        return
+    data[name] = secret
+    save_totp(data)
+    print(f"Added 2FA account: {name}")
+
+    try:
+        save_qr_image(name, cv2.imencode(".jpg", img)[1].tobytes())
+    except Exception:
+        pass
+
+    _import_recovery_file(name, recovery_path)

jkey-0.1.2/src/jkey/__main__.py

@@ -0,0 +1,4 @@
+from jkey.cli import main
+
+if __name__ == "__main__":
+    main()