ikiprotect 1.0.0__py3-none-any.whl

iki_protect/__init__.py

@@ -0,0 +1,5 @@
+"""iki-protect package."""
+
+from .facade import HPKE_AVAILABLE, IkiProtect
+
+__all__ = ["IkiProtect", "HPKE_AVAILABLE"]

iki_protect/__main__.py

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

iki_protect/cli/__init__.py

@@ -0,0 +1 @@
+"""CLI package."""

iki_protect/cli/app.py

@@ -0,0 +1,47 @@
+"""Root Typer application — the `ikiprotect` entrypoint."""
+
+from __future__ import annotations
+
+import typer
+from rich.console import Console
+
+from iki_protect.cli.commands import decrypt as decrypt_cmd
+from iki_protect.cli.commands import detect as detect_cmd
+from iki_protect.cli.commands import encrypt as encrypt_cmd
+from iki_protect.cli.commands import hash_cmd
+from iki_protect.cli.commands import jwt_cmd
+from iki_protect.cli.commands import keys as keys_cmd
+from iki_protect.cli.commands import mask as mask_cmd
+from iki_protect.cli.commands import sign as sign_cmd
+from iki_protect.version import __version__
+
+app = typer.Typer(
+    name="ikiprotect",
+    help="Portable content protection CLI: detect, mask, hash, encrypt, sign, JWT.",
+    no_args_is_help=True,
+)
+console = Console()
+
+app.command("detect")(detect_cmd.detect)
+app.command("mask")(mask_cmd.mask)
+app.add_typer(hash_cmd.hash_app, name="hash")
+app.command("encrypt")(encrypt_cmd.encrypt)
+app.command("decrypt")(decrypt_cmd.decrypt)
+app.command("sign")(sign_cmd.sign)
+app.command("verify-signature")(sign_cmd.verify_signature)
+app.command("generate-keypair")(keys_cmd.generate_keypair)
+app.add_typer(jwt_cmd.jwt_app, name="jwt")
+
+
+@app.callback()
+def version_callback(version: bool = typer.Option(False, "--version")) -> None:
+    if version:
+        console.print(__version__)
+
+
+def main() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    main()

iki_protect/cli/commands/__init__.py

@@ -0,0 +1,3 @@
+from __future__ import annotations
+
+from iki_protect.cli.commands import decrypt, detect, encrypt, hash_cmd, jwt_cmd, mask, sign  # noqa: F401

iki_protect/cli/commands/decrypt.py

@@ -0,0 +1,152 @@
+"""`ikiprotect decrypt` — reverse of `ikiprotect encrypt` for ONE file."""
+
+from __future__ import annotations
+
+import base64
+import os
+import sys
+from pathlib import Path
+from typing import Optional
+
+import typer
+from rich.console import Console
+
+from iki_protect.core.config import get_config_value
+from iki_protect.core.errors import DecryptionError
+from iki_protect.cli.facade import protect
+
+console = Console()
+PASSPHRASE_MAGIC = b"PHS1"
+
+
+def _unwrap_passphrase_ciphertext(data: bytes) -> tuple[bytes, bytes]:
+    if not data.startswith(PASSPHRASE_MAGIC):
+        raise ValueError("Not a passphrase-wrapped ciphertext")
+    if len(data) < 5:
+        raise ValueError("Truncated passphrase wrapper")
+    salt_len = data[4]
+    if len(data) < 5 + salt_len:
+        raise ValueError("Truncated passphrase wrapper")
+    salt = data[5:5 + salt_len]
+    return salt, data[5 + salt_len:]
+
+
+def _prompt_passphrase() -> str:
+    return typer.prompt("Passphrase", hide_input=True)
+
+
+def _resolve_passphrase(passphrase: Optional[str]) -> Optional[str]:
+    if passphrase is not None:
+        return passphrase
+    return os.getenv("IKIPROTECT_PASSPHRASE")
+
+
+def _derive_key(
+    key_ref: Optional[str],
+    passphrase: Optional[str],
+    kdf: str,
+    salt: Optional[str],
+    salt_bytes: bytes | None = None,
+) -> bytes:
+    if passphrase is not None:
+        if key_ref is not None:
+            raise typer.BadParameter(
+                "Use either --key-ref or --passphrase, not both")
+        if salt_bytes is None:
+            salt_bytes = bytes.fromhex(salt) if salt else b""
+        return protect.derive_passphrase_key(passphrase, kdf, salt_bytes)
+
+    if key_ref is None:
+        raise typer.BadParameter("--key-ref or --passphrase is required")
+    return protect.resolve_key(key_ref)
+
+
+def decrypt(
+    input_file: Optional[typer.FileBinaryRead] = typer.Argument(
+        None, help="Read raw bytes from a file. Defaults to stdin."),
+    algo: str = typer.Option(
+        get_config_value("default_algo", "aes-256-gcm"),
+        "--algo",
+        help="Decryption algorithm or comma-separated algorithm chain for non-layered ciphertext.",
+    ),
+    key_ref: Optional[str] = typer.Option(
+        get_config_value("default_key_ref", None),
+        "--key-ref",
+        help="Key reference, like env:NAME or file:path.",
+    ),
+    passphrase: Optional[str] = typer.Option(
+        None,
+        "--passphrase",
+        help="Passphrase to derive the decryption key. Discouraged on the CLI; use IKI_PROTECT_PASSPHRASE or leave blank to prompt.",
+    ),
+    kdf: str = typer.Option(
+        "argon2id",
+        "--kdf",
+        help="KDF for passphrase-derived keys: sha256 | pbkdf2-sha256 | argon2id.",
+    ),
+    salt: Optional[str] = typer.Option(
+        None,
+        "--salt",
+        help="Hex-encoded salt for passphrase KDF. Omit if the ciphertext embeds the salt.",
+    ),
+    aad: Optional[str] = typer.Option(
+        None,
+        "--aad",
+        help="Additional authenticated data to validate during decryption.",
+    ),
+    input_format: str = typer.Option(
+        "raw",
+        "--input-format",
+        help="raw | base64",
+    ),
+    output: Optional[str] = typer.Option(None, "--output", "-o"),
+) -> None:
+    data = input_file.read() if input_file else sys.stdin.buffer.read()
+    if input_format not in {"raw", "base64"}:
+        raise typer.BadParameter("--input-format must be raw or base64")
+    if input_format == "base64":
+        data = base64.b64decode(data)
+
+    embedded_salt: bytes | None = None
+    if data.startswith(PASSPHRASE_MAGIC):
+        try:
+            embedded_salt, data = _unwrap_passphrase_ciphertext(data)
+        except ValueError as exc:
+            raise typer.BadParameter(str(exc)) from exc
+
+    if passphrase is None and key_ref is None:
+        passphrase = _prompt_passphrase()
+    passphrase = _resolve_passphrase(passphrase)
+
+    if salt is not None and embedded_salt is not None:
+        raise typer.BadParameter(
+            "Cannot provide --salt when the ciphertext already embeds salt"
+        )
+
+    key = _derive_key(key_ref, passphrase, kdf, salt, salt_bytes=embedded_salt)
+    aad_bytes = aad.encode("utf-8") if aad is not None else None
+
+    try:
+        if protect.is_envelope(data):
+            plaintext = protect.envelope_decrypt(key, data, aad=aad_bytes)
+        elif data.startswith(b"ILYR"):
+            plaintext = protect.layered_decrypt(key, data, aad=aad_bytes)
+        else:
+            try:
+                algos = protect.parse_algorithm_chain(algo, layers=1)
+            except ValueError as exc:
+                raise typer.BadParameter(str(exc)) from exc
+            if len(algos) > 1:
+                raise typer.BadParameter(
+                    "Cannot decrypt raw ciphertext with multiple algorithms unless it is layered."
+                )
+            plaintext = protect.decrypt(
+                data, key, algorithm=algos[0], aad=aad_bytes)
+    except DecryptionError as exc:
+        raise typer.Exit(code=1) from exc
+
+    if output:
+        Path(output).write_bytes(plaintext)
+        console.print(f"Decrypted output written to {output}")
+    else:
+        sys.stdout.buffer.write(plaintext)

iki_protect/cli/commands/detect.py

@@ -0,0 +1,123 @@
+"""`ikiprotect detect` — scan ONE string or ONE file for PII/secrets."""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Optional
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from iki_protect.cli.facade import protect
+from pathlib import Path
+import os
+import fnmatch
+
+console = Console()
+err_console = Console(stderr=True)
+
+
+def detect(
+    input_file: Optional[typer.FileText] = typer.Argument(
+        None, help="Read text from a file. Defaults to stdin."),
+    types: str = typer.Option("pii,secrets", "--types",
+                              help="Comma-separated detector groups or names."),
+    output_format: str = typer.Option(
+        "text", "--format", help="text | json | ndjson"),
+) -> None:
+    text = input_file.read() if input_file else sys.stdin.read()
+    findings = sorted(protect.detect(text, types=types),
+                      key=lambda f: (f.start, f.end))
+
+    if output_format == "json":
+        console.print_json(json.dumps([_dict(f) for f in findings]))
+    elif output_format == "ndjson":
+        for f in findings:
+            console.print_json(json.dumps(_dict(f)))
+    else:
+        table = Table(title="Findings")
+        table.add_column("Type")
+        table.add_column("Value")
+        table.add_column("Start")
+        table.add_column("End")
+        for f in findings:
+            table.add_row(f.type, f.hint(), str(f.start), str(f.end))
+        console.print(table)
+
+
+def _dict(f) -> dict:
+    return {"type": f.type, "value_hint": f.hint(), "start": f.start, "end": f.end, "confidence": f.confidence}
+
+
+def _load_ignore(path: Path) -> list[str]:
+    ignore_file = path / ".ikiprotectignore"
+    patterns: list[str] = []
+    if ignore_file.exists():
+        for line in ignore_file.read_text(encoding="utf-8").splitlines():
+            line = line.strip()
+            if not line or line.startswith("#"):
+                continue
+            patterns.append(line)
+    return patterns
+
+
+def scan(
+    path: Path = typer.Argument(Path("."), help="File or directory to scan."),
+    types: str = typer.Option("pii,secrets", "--types",
+                              help="Comma-separated detector groups or names."),
+    recursive: bool = typer.Option(True, "--recursive/--no-recursive"),
+    output_format: str = typer.Option(
+        "text", "--format", help="text | json | ndjson"),
+    fail_on: int = typer.Option(
+        1, "--fail-on", help="Fail CI with exit code if findings >= this."),
+) -> None:
+    total_findings = []
+    patterns = _load_ignore(path if path.is_dir() else path.parent)
+
+    def _should_ignore(rel: str) -> bool:
+        for p in patterns:
+            if fnmatch.fnmatch(rel, p):
+                return True
+        return False
+
+    if path.is_file():
+        text = path.read_text(encoding="utf-8")
+        total_findings.extend(protect.detect(text, types=types))
+    else:
+        for root, dirs, files in os.walk(path):
+            relroot = os.path.relpath(root, path)
+            if relroot == ".":
+                relroot = ""
+            if _should_ignore(os.path.join(relroot, "")):
+                continue
+            for name in files:
+                rel = os.path.join(relroot, name) if relroot else name
+                if _should_ignore(rel):
+                    continue
+                try:
+                    text = Path(root, name).read_text(encoding="utf-8")
+                except Exception:
+                    continue
+                total_findings.extend(protect.detect(text, types=types))
+
+    if output_format == "json":
+        console.print_json(json.dumps([_dict(f) for f in total_findings]))
+    elif output_format == "ndjson":
+        for f in total_findings:
+            console.print_json(json.dumps(_dict(f)))
+    else:
+        table = Table(title="Scan Findings")
+        table.add_column("File/Location")
+        table.add_column("Type")
+        table.add_column("Value")
+        table.add_column("Start")
+        table.add_column("End")
+        for f in total_findings:
+            table.add_row(getattr(f, "file", "<stdin>"), f.type,
+                          f.hint(), str(f.start), str(f.end))
+        console.print(table)
+
+    if fail_on is not None and len(total_findings) >= fail_on:
+        raise typer.Exit(code=2)

iki_protect/cli/commands/encrypt.py

@@ -0,0 +1,172 @@
+"""`ikiprotect encrypt` — reversible AEAD encryption of ONE file or stdin stream."""
+
+from __future__ import annotations
+
+import base64
+import os
+import sys
+from pathlib import Path
+from typing import Optional
+
+import typer
+from rich.console import Console
+
+from iki_protect.core.config import get_config_value
+from iki_protect.cli.facade import protect
+
+console = Console()
+PASSPHRASE_MAGIC = b"PHS1"
+
+
+def _wrap_passphrase_ciphertext(ciphertext: bytes, salt: bytes) -> bytes:
+    if len(salt) > 255:
+        raise ValueError("Salt is too long for embedded metadata")
+    return PASSPHRASE_MAGIC + bytes([len(salt)]) + salt + ciphertext
+
+
+def _prompt_passphrase() -> str:
+    return typer.prompt("Passphrase", hide_input=True)
+
+
+def _resolve_passphrase(passphrase: Optional[str]) -> Optional[str]:
+    if passphrase is not None:
+        return passphrase
+    return os.getenv("IKIPROTECT_PASSPHRASE")
+
+
+def _derive_key(
+    key_ref: Optional[str],
+    passphrase: Optional[str],
+    kdf: str,
+    salt: Optional[str],
+    salt_bytes: bytes | None = None,
+) -> bytes:
+    if passphrase is not None:
+        if key_ref is not None:
+            raise typer.BadParameter(
+                "Use either --key-ref or --passphrase, not both")
+        if salt_bytes is None:
+            salt_bytes = bytes.fromhex(salt) if salt else b""
+        return protect.derive_passphrase_key(passphrase, kdf, salt_bytes)
+
+    if key_ref is None:
+        raise typer.BadParameter("--key-ref or --passphrase is required")
+    return protect.resolve_key(key_ref)
+
+
+def encrypt(
+    input_file: Optional[typer.FileBinaryRead] = typer.Argument(
+        None, help="Read raw bytes from a file. Defaults to stdin."),
+    algo: str = typer.Option(
+        get_config_value("default_algo", "aes-256-gcm"),
+        "--algo",
+        help="Encryption algorithm or comma-separated layered algorithm chain.",
+    ),
+    layers: int = typer.Option(
+        get_config_value("default_layers", 1),
+        "--layers",
+        help="Repeat a single algorithm this many times to create layered encryption.",
+    ),
+    key_ref: Optional[str] = typer.Option(
+        None,
+        "--key-ref",
+        help="Key reference, like env:NAME or file:path.",
+    ),
+    passphrase: Optional[str] = typer.Option(
+        None,
+        "--passphrase",
+        help="Passphrase to derive the encryption key. Discouraged on the CLI; use IKI_PROTECT_PASSPHRASE or leave blank to prompt.",
+    ),
+    kdf: str = typer.Option(
+        "argon2id",
+        "--kdf",
+        help="KDF for passphrase-derived keys: sha256 | pbkdf2-sha256 | argon2id.",
+    ),
+    salt: Optional[str] = typer.Option(
+        None,
+        "--salt",
+        help="Hex-encoded salt for passphrase KDF. Omit to embed a random salt in ciphertext.",
+    ),
+    aad: Optional[str] = typer.Option(
+        None,
+        "--aad",
+        help="Additional authenticated data to bind to ciphertext.",
+    ),
+    output_format: str = typer.Option(
+        "raw",
+        "--output-format",
+        help="raw | base64",
+    ),
+    envelope: bool = typer.Option(
+        False, "--envelope", help="Use DEK/KEK envelope encryption (wrap DEK under KEK)."),
+    output: Optional[str] = typer.Option(None, "--output", "-o"),
+) -> None:
+    data = input_file.read() if input_file else sys.stdin.buffer.read()
+    try:
+        algos = protect.parse_algorithm_chain(algo, layers=layers)
+    except ValueError as exc:
+        raise typer.BadParameter(str(exc)) from exc
+
+    if passphrase is None and key_ref is None:
+        passphrase = _prompt_passphrase()
+    passphrase = _resolve_passphrase(passphrase)
+
+    salt_bytes = None
+    if passphrase is not None:
+        if salt is None:
+            salt_bytes = os.urandom(16)
+        else:
+            salt_bytes = bytes.fromhex(salt)
+
+    key = _derive_key(key_ref, passphrase, kdf, salt, salt_bytes=salt_bytes)
+    aad_bytes = aad.encode("utf-8") if aad is not None else None
+
+    if envelope:
+        ciphertext = protect.envelope_encrypt(key, data, algos, aad=aad_bytes)
+    else:
+        if len(algos) == 1:
+            ciphertext = protect.encrypt(
+                data, key, algorithm=algos[0], aad=aad_bytes)
+        else:
+            ciphertext = protect.layered_encrypt(
+                key, data, algos, aad=aad_bytes)
+
+    if passphrase is not None:
+        ciphertext = _wrap_passphrase_ciphertext(ciphertext, salt_bytes or b"")
+
+    if output_format not in {"raw", "base64"}:
+        raise typer.BadParameter("--output-format must be raw or base64")
+
+    if output_format == "base64":
+        encoded = base64.b64encode(ciphertext).decode("ascii")
+        if output:
+            Path(output).write_text(encoded)
+            console.print(f"Encrypted output written to {output}")
+        else:
+            console.print(encoded)
+        return
+
+    if output:
+        Path(output).write_bytes(ciphertext)
+        console.print(f"Encrypted output written to {output}")
+    else:
+        sys.stdout.buffer.write(ciphertext)
+
+
+def rewrap(
+    input_file: typer.FileBinaryRead = typer.Argument(
+        ..., help="Existing envelope file."),
+    old_key_ref: str = typer.Option(..., "--old-key-ref"),
+    new_key_ref: str = typer.Option(..., "--new-key-ref"),
+    output: Optional[str] = typer.Option(None, "--output", "-o"),
+) -> None:
+    data = input_file.read()
+
+    old_kek = protect.resolve_key(old_key_ref)
+    new_kek = protect.resolve_key(new_key_ref)
+    new_env = protect.rewrap_envelope(data, old_kek, new_kek)
+    if output:
+        Path(output).write_bytes(new_env)
+        console.print(f"Rewrapped envelope written to {output}")
+    else:
+        sys.stdout.buffer.write(new_env)