zipctl 0.1.0__py3-none-any.whl

zipctl/__init__.py

@@ -0,0 +1,108 @@
+from zipctl.compression import (
+    ZIP_BZIP2,
+    ZIP_DEFLATED,
+    ZIP_LZMA,
+    ZIP_STORED,
+    ZIP_ZSTANDARD,
+    Registry,
+)
+from zipctl.cryptography import WZ_AES, WZ_AES_V1, WZ_AES_V2, ZIP_CRYPTO
+from zipctl.exceptions import BadPassword, PasswordError, PasswordRequired
+from zipctl.zipfile.assessment import ArchiveAssessment, ExtractionContext
+from zipctl.zipfile.exceptions import (
+    ExtractionFailure,
+    ExtractionMaterializationError,
+    ExtractionQuotaExceeded,
+    ExtractionSecurityError,
+)
+from zipctl.zipfile.extract import (
+    ExtractionError,
+    ExtractMemberResult,
+    ExtractPolicy,
+    ExtractPolicyRule,
+    ExtractResult,
+    ExtractViolation,
+    MemberAssessment,
+    MemberStatus,
+    OverwritePolicy,
+    ViolationAction,
+)
+from zipctl.zipfile.file import (
+    INHERIT_ENCRYPTION,
+    EncryptionOverride,
+    PasswordProvider,
+    ZipFile,
+    ZipFileExtra,
+    is_zipfile,
+)
+from zipctl.zipfile.info import WzAesExtra
+from zipctl.zipfile.inspection import InspectionMember, InspectionResult
+from zipctl.zipfile.password import (
+    MemberPasswordCheck,
+    PasswordCheckResult,
+    PasswordStatus,
+)
+from zipctl.zipfile.path import Path
+from zipctl.zipfile.policy_config import (
+    PolicyConfigError,
+    PolicyIssue,
+    policy_from_json,
+    policy_from_mapping,
+    policy_to_json,
+    policy_to_mapping,
+)
+from zipctl.zipfile.progress import ProgressCallback, ProgressEvent, ProgressPhase
+
+__all__ = [
+    "WZ_AES",
+    "WZ_AES_V1",
+    "WZ_AES_V2",
+    "WzAesExtra",
+    "ZipFileExtra",
+    "ZIP_CRYPTO",
+    "ZIP_STORED",
+    "ZIP_DEFLATED",
+    "ZIP_BZIP2",
+    "ZIP_LZMA",
+    "ZIP_ZSTANDARD",
+    "Registry",
+    "ZipFile",
+    "is_zipfile",
+    "INHERIT_ENCRYPTION",
+    "EncryptionOverride",
+    "ExtractMemberResult",
+    "ExtractPolicy",
+    "ExtractPolicyRule",
+    "ExtractResult",
+    "ExtractViolation",
+    "ExtractionError",
+    "ExtractionFailure",
+    "ExtractionMaterializationError",
+    "ExtractionQuotaExceeded",
+    "ExtractionSecurityError",
+    "MemberStatus",
+    "MemberAssessment",
+    "ArchiveAssessment",
+    "BadPassword",
+    "MemberPasswordCheck",
+    "PasswordCheckResult",
+    "PasswordError",
+    "PasswordProvider",
+    "PasswordRequired",
+    "PasswordStatus",
+    "PolicyConfigError",
+    "PolicyIssue",
+    "ProgressCallback",
+    "ProgressEvent",
+    "ProgressPhase",
+    "policy_from_json",
+    "policy_from_mapping",
+    "policy_to_json",
+    "policy_to_mapping",
+    "ExtractionContext",
+    "OverwritePolicy",
+    "ViolationAction",
+    "InspectionMember",
+    "InspectionResult",
+    "Path",
+]

zipctl/__main__.py

@@ -0,0 +1,5 @@
+"""Run the command-line interface with ``python -m zipctl``."""
+
+from zipctl.cli import main
+
+raise SystemExit(main())

zipctl/cli/__init__.py

@@ -0,0 +1,108 @@
+"""Command-line interface: ``zipctl`` and ``python -m zipctl``."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+import traceback
+from collections.abc import Sequence
+
+from zipctl.cli.commands.helpers.command import Handler
+from zipctl.cli.context import Context
+from zipctl.cli.errors import (
+    EXIT_BROKEN_PIPE,
+    EXIT_FAILURE,
+    EXIT_INTERRUPTED,
+    EXIT_OK,
+    CliError,
+    os_error_filename,
+    os_error_text,
+)
+from zipctl.cli.output import printable, write_json
+from zipctl.cli.parser import build_parser
+
+__all__ = ["main"]
+
+
+class _Parsed(argparse.Namespace):
+    """The parsed arguments, with the handler the chosen command registered."""
+
+    handler: Handler  # pyright: ignore[reportUninitializedInstanceVariable]  # set by argparse
+
+
+def _exit_code(code: object) -> int:
+    if code is None:
+        return EXIT_OK
+    return code if isinstance(code, int) else 1
+
+
+def _quiet_broken_pipe() -> None:
+    """Stop Python complaining again about the closed pipe when it exits."""
+    try:
+        devnull = os.open(os.devnull, os.O_WRONLY)
+        os.dup2(devnull, sys.stdout.fileno())
+    except (OSError, ValueError):
+        pass
+
+
+def _fail(
+    ctx: Context,
+    args: argparse.Namespace,
+    exc: Exception,
+    message: str,
+    code: int,
+    details: tuple[str, ...] = (),
+) -> int:
+    """Report *message* on standard error (and as JSON with ``--json``)."""
+    if ctx.environ.get("ZIPCTL_DEBUG"):
+        exc.__suppress_context__ = False  # show the error a ``from None`` hid
+        traceback.print_exception(exc, file=ctx.stderr)
+    ctx.err(f"zipctl: error: {message}")
+    for line in details:
+        ctx.err(f"  {line}")
+    wants_json: bool = getattr(args, "json", False)  # not every command has --json
+    if wants_json:
+        error = {"ok": False, "error": message, "code": code, "details": list(details)}
+        write_json(ctx.stdout, error)
+    return code
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Run the CLI with *argv* (default: ``sys.argv[1:]``); return the exit code."""
+    ctx = Context.from_process()
+    for stream in (ctx.stdout, ctx.stderr):
+        reconfigure = getattr(stream, "reconfigure", None)
+        if reconfigure is not None:
+            reconfigure(errors="backslashreplace")
+
+    parser = build_parser()
+    try:
+        args = parser.parse_args(
+            sys.argv[1:] if argv is None else argv, namespace=_Parsed()
+        )
+    except SystemExit as exc:
+        return _exit_code(exc.code)
+
+    try:
+        code = args.handler(args, ctx)
+        ctx.stdout.flush()
+        return int(code)
+    except CliError as exc:
+        return _fail(ctx, args, exc, exc.message, exc.code, exc.details)
+    except KeyboardInterrupt:
+        ctx.err("zipctl: interrupted")
+        return EXIT_INTERRUPTED
+    except BrokenPipeError:
+        _quiet_broken_pipe()
+        return EXIT_BROKEN_PIPE
+    except OSError as exc:  # whatever a command did not translate itself
+        filename = os_error_filename(exc)
+        where = f"{printable(filename)}: " if filename else ""
+        message = f"{where}{printable(os_error_text(exc))}"
+        return _fail(ctx, args, exc, message, EXIT_FAILURE)
+    except Exception as exc:  # a bug: name it, and offer the traceback
+        message = f"unexpected {type(exc).__name__}: {printable(str(exc))}"
+        if not ctx.environ.get("ZIPCTL_DEBUG"):
+            message += " (set ZIPCTL_DEBUG=1 for the traceback)"
+        return _fail(ctx, args, exc, message, EXIT_FAILURE)

zipctl/cli/archive.py

@@ -0,0 +1,23 @@
+"""Opening archives."""
+
+from __future__ import annotations
+
+from zipctl.cli.errors import CliError, os_error_text
+from zipctl.cli.output import printable
+from zipctl.exceptions import BadZipFile
+from zipctl.zipfile.file import ZipFile
+
+__all__ = ["CHUNK", "open_archive"]
+
+CHUNK = 1 << 20  # bytes read at a time when streaming a member
+
+
+def open_archive(path: str) -> ZipFile:
+    try:
+        return ZipFile(path)
+    except BadZipFile:
+        raise CliError(f"{printable(path)}: not a valid ZIP archive") from None
+    except NotImplementedError as exc:
+        raise CliError(f"{printable(path)}: unsupported ZIP feature ({exc})") from None
+    except OSError as exc:
+        raise CliError(f"cannot open {printable(path)}: {os_error_text(exc)}") from None

zipctl/cli/atomic.py

@@ -0,0 +1,77 @@
+"""Writing an archive so that a failed run leaves nothing behind."""
+
+from __future__ import annotations
+
+import os
+import secrets
+import shutil
+from collections.abc import Generator
+from contextlib import contextmanager
+
+from zipctl.cli.errors import CliError, os_error_text
+from zipctl.cli.output import printable
+
+__all__ = ["replacing"]
+
+
+def _sync_directory(directory: str) -> None:
+    """Make the rename durable; best effort (not every platform can do it)."""
+    try:
+        handle = os.open(directory, os.O_RDONLY)
+        try:
+            os.fsync(handle)
+        finally:
+            os.close(handle)
+    except OSError:
+        pass
+
+
+@contextmanager
+def replacing(path: str, *, overwrite: bool, seed: bool = False) -> Generator[str]:
+    """Yield a scratch path beside *path*; move it onto *path* if the block succeeds.
+
+    The scratch file is removed if the block raises (Ctrl-C included), so *path*
+    is either untouched or complete.  An existing *path* keeps its permission
+    bits.  With *seed*, the scratch file starts as a copy of it (for
+    appending).  Unless *overwrite*, an
+    existing *path* is refused, both up front and again just before the move.
+    """
+    target = os.path.realpath(path)  # through a symlink, so the link survives
+    exists = os.path.lexists(target)
+    if exists and not overwrite:
+        raise CliError(f"{printable(path)} already exists (use --force to replace it)")
+    directory = os.path.dirname(target)
+    scratch = os.path.join(directory, f".zipctl-{secrets.token_hex(8)}.tmp")
+    try:
+        # 0o666 here: the kernel applies the umask, without touching ours
+        handle = os.open(scratch, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o666)
+    except OSError as exc:
+        raise CliError(
+            f"cannot create {printable(path)}: {os_error_text(exc)}"
+        ) from None
+    os.close(handle)
+    try:
+        if seed and exists:
+            shutil.copyfile(target, scratch)
+        if exists:
+            shutil.copymode(target, scratch)  # a 0600 archive stays 0600
+        yield scratch
+        with open(scratch, "rb+") as written:
+            os.fsync(written.fileno())
+        # ponytail: check-then-replace, so a file created in this instant is
+        # replaced; os.link would be exclusive but is not portable.
+        if not overwrite and os.path.lexists(target):
+            raise CliError(f"{printable(path)} already exists")
+        try:
+            os.replace(scratch, target)
+        except OSError as exc:
+            raise CliError(
+                f"cannot replace {printable(path)}: {os_error_text(exc)}"
+            ) from None
+        _sync_directory(directory)
+    except BaseException:
+        try:
+            os.unlink(scratch)
+        except FileNotFoundError:
+            pass
+        raise

zipctl/cli/commands/__init__.py

@@ -0,0 +1,8 @@
+"""The ``zipctl`` subcommands, one module each.
+
+Every module exposes ``register(subparsers)``, which adds its parser and binds
+the handler, so a command's arguments and behaviour live side by side.  What
+only commands share lives in :mod:`zipctl.cli.commands.helpers`; so does what
+a single command needs beyond its handler (``collect`` and ``create_report`` for
+``create``, ``extract_report`` for ``extract``), to keep one module per command.
+"""

zipctl/cli/commands/check_password.py

@@ -0,0 +1,133 @@
+"""The ``check-password`` command."""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+from zipctl.cli.archive import open_archive
+from zipctl.cli.commands.helpers.command import Subparsers, add_command
+from zipctl.cli.commands.helpers.output_options import OutputArgs, add_output_options
+from zipctl.cli.commands.helpers.passwords.options import (
+    PasswordArgs,
+    PasswordOptions,
+    add_password_options,
+    single_password,
+)
+from zipctl.cli.commands.helpers.selection import MEMBER_HELP, select_infos
+from zipctl.cli.context import Context
+from zipctl.cli.errors import EXIT_FAILURE, EXIT_OK, CliError
+from zipctl.cli.output import count, printable, write_json
+from zipctl.exceptions import BadZipFile
+from zipctl.zipfile.file import ZipFile
+from zipctl.zipfile.info import ZipInfo
+from zipctl.zipfile.password import (
+    MemberPasswordCheck,
+    PasswordCheckResult,
+    PasswordStatus,
+)
+
+_LINES = {
+    PasswordStatus.ACCEPTED: ("OK", ""),
+    PasswordStatus.REJECTED: ("FAILED", ": password does not match"),
+    PasswordStatus.CORRUPT: ("FAILED", ": password matches but the data is corrupt"),
+    PasswordStatus.UNENCRYPTED: ("SKIP", ": not encrypted"),
+}
+
+
+class CheckPasswordArgs(OutputArgs, PasswordArgs, Protocol):
+    archive: str
+    members: list[str]
+    full: bool
+
+
+def _summary(encrypted: int, accepted: int, full: bool) -> str:
+    if not encrypted:
+        return "No encrypted members to check"
+    text = f"Checked {count(encrypted, 'encrypted member')}: "
+    text += "all OK" if accepted == encrypted else f"{encrypted - accepted} failed"
+    if accepted and not full:
+        text += " (verifier only; use --full to authenticate the data)"
+    return text
+
+
+def _check(
+    zf: ZipFile, infos: list[ZipInfo], args: CheckPasswordArgs, ctx: Context
+) -> PasswordCheckResult:
+    if not any(info.is_encrypted for info in infos):
+        # Nothing to unlock, so do not ask for (or insist on) a password.
+        plain = PasswordStatus.UNENCRYPTED
+        return PasswordCheckResult(
+            tuple(MemberPasswordCheck(info.filename, plain) for info in infos)
+        )
+    password = single_password(PasswordOptions.from_args(args), ctx)
+    try:
+        return zf.check_password(password, members=infos, full=args.full)
+    except (BadZipFile, NotImplementedError) as exc:
+        raise CliError(f"cannot check the password: {printable(str(exc))}") from None
+
+
+def cmd_check_password(args: CheckPasswordArgs, ctx: Context) -> int:
+    with open_archive(args.archive) as zf:
+        result = _check(zf, select_infos(zf.infolist(), args.members), args, ctx)
+
+    checks = result.members
+    encrypted = sum(check.status is not PasswordStatus.UNENCRYPTED for check in checks)
+    accepted = len(result.accepted)
+    if args.json:
+        write_json(
+            ctx.stdout,
+            {
+                "ok": result.ok,
+                "archive": args.archive,
+                "full": args.full,
+                "encrypted": encrypted,
+                "accepted": accepted,
+                "rejected": len(result.rejected),
+                "corrupt": len(result.corrupt),
+                "members": [
+                    {"name": check.member, "status": check.status.value}
+                    for check in checks
+                ],
+            },
+        )
+    else:
+        listed = False
+        for check in checks:
+            label, detail = _LINES[check.status]
+            if check.status in (PasswordStatus.REJECTED, PasswordStatus.CORRUPT) or (
+                args.verbose
+            ):
+                ctx.out(f"{label:<8}{printable(check.member)}{detail}")
+                listed = True
+        if listed:
+            ctx.out()
+        ctx.out(_summary(encrypted, accepted, args.full))
+    return EXIT_OK if result.ok else EXIT_FAILURE
+
+
+def register(subparsers: Subparsers) -> None:
+    parser = add_command(
+        subparsers,
+        "check-password",
+        cmd_check_password,
+        "check whether one password matches the encrypted members",
+    )
+    parser.add_argument(
+        "archive",
+        metavar="ARCHIVE",
+        help="the encrypted archive to check the password against",
+    )
+    parser.add_argument(
+        "members",
+        nargs="*",
+        metavar="MEMBER",
+        help=MEMBER_HELP,
+    )
+    parser.add_argument(
+        "--full",
+        action="store_true",
+        help="also authenticate each member's data (definitive, but reads the "
+        "members). Default: check only the password verifier",
+    )
+    add_output_options(parser, verbose_help="also list members that match")
+    add_password_options(parser)