zipctl 0.1.0__py3-none-any.whl

zipctl/cli/commands/policy.py

@@ -0,0 +1,104 @@
+"""The ``policy`` command group."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Protocol
+
+from zipctl.cli.commands.helpers.command import Subparsers, add_command, add_subcommands
+from zipctl.cli.commands.helpers.output_options import OutputArgs, add_output_options
+from zipctl.cli.commands.helpers.policy_options import (
+    PolicyArgs,
+    add_policy_options,
+    load_policy,
+)
+from zipctl.cli.commands.helpers.sources import read_text_source
+from zipctl.cli.context import Context
+from zipctl.cli.errors import EXIT_OK, EXIT_USAGE, CliError, UsageError
+from zipctl.cli.output import count, printable, write_json
+from zipctl.zipfile.extract import (
+    ExtractPolicy,
+)
+from zipctl.zipfile.policy_config import (
+    PolicyConfigError,
+    policy_from_json,
+    policy_to_json,
+)
+
+
+class ValidateArgs(OutputArgs, Protocol):
+    files: list[str]
+
+
+@dataclass(frozen=True)
+class _FileReport:
+    """One policy file as ``policy validate --json`` reports it."""
+
+    file: str
+    valid: bool
+    issues: list[dict[str, str]]
+
+
+def cmd_policy_show(args: PolicyArgs, ctx: Context) -> int:
+    policy: ExtractPolicy = load_policy(args, ctx)
+    ctx.out(policy_to_json(policy))
+    return EXIT_OK
+
+
+def cmd_policy_validate(args: ValidateArgs, ctx: Context) -> int:
+    if args.files.count("-") > 1:
+        raise UsageError("standard input can only be given once")
+    reports: list[_FileReport] = []
+    for source in args.files:
+        issues: list[dict[str, str]] = []
+        try:
+            policy_from_json(read_text_source(source, ctx, "policy file"))
+        except PolicyConfigError as exc:
+            issues = [
+                {"path": issue.path, "message": issue.message} for issue in exc.issues
+            ]
+        except CliError as exc:  # unreadable file: report it and check the others
+            issues = [{"path": "", "message": exc.message}]
+        reports.append(_FileReport(source, not issues, issues))
+
+    invalid = [report for report in reports if not report.valid]
+    if args.json:
+        write_json(ctx.stdout, {"ok": not invalid, "files": reports})
+    else:
+        for report in reports:
+            name = printable(report.file)
+            if report.valid:
+                ctx.out(f"{'OK':<8}{name}")
+                continue
+            ctx.out(f"{'FAILED':<8}{name}: {count(len(report.issues), 'issue')}")
+            for issue in report.issues:
+                where = issue["path"] or "<policy>"
+                ctx.out(f"  {printable(where)}: {printable(issue['message'])}")
+        ctx.out()
+        text = f"Checked {count(len(reports), 'policy file')}: "
+        ctx.out(text + (f"{len(invalid)} failed" if invalid else "all OK"))
+    return EXIT_USAGE if invalid else EXIT_OK
+
+
+def register(subparsers: Subparsers) -> None:
+    parser = add_command(
+        subparsers, "policy", None, "show or validate extraction policies"
+    )
+    actions = add_subcommands(parser, "policy_command")
+    show = add_command(
+        actions, "show", cmd_policy_show, "print the effective policy as JSON"
+    )
+    add_policy_options(show)
+    validate = add_command(
+        actions,
+        "validate",
+        cmd_policy_validate,
+        "check policy files without needing an archive",
+    )
+    validate.add_argument(
+        "files",
+        nargs="+",
+        metavar="FILE",
+        help="policy file ('-' reads standard input)",
+    )
+    add_output_options(validate)

zipctl/cli/commands/rewrite.py

@@ -0,0 +1,113 @@
+"""The ``rewrite`` 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.copying.copy import read_passwords, run_copy
+from zipctl.cli.commands.helpers.copying.options import (
+    CopyArgs,
+    add_copy_options,
+    check_paths,
+    copy_job,
+)
+from zipctl.cli.commands.helpers.copying.targets import (
+    PLAIN,
+    Target,
+    keep_target,
+    target_for_method,
+)
+from zipctl.cli.commands.helpers.encryption.options import (
+    EncryptionArgs,
+    EncryptionOptions,
+    add_encryption_options,
+    build_plan,
+)
+from zipctl.cli.commands.helpers.encryption.plan import warn_if_weak
+from zipctl.cli.commands.helpers.passwords.options import (
+    OldPasswordArgs,
+    add_old_password_options,
+    add_password_options,
+    old_password_pool,
+)
+from zipctl.cli.context import Context
+from zipctl.cli.errors import UsageError
+from zipctl.cli.methods import COMPRESSION, require_compression, require_level
+
+
+class RewriteArgs(CopyArgs, EncryptionArgs, OldPasswordArgs, Protocol):
+    compression: str | None
+    level: int | None
+
+
+def cmd_rewrite(args: RewriteArgs, ctx: Context) -> int:
+    job = copy_job(args)
+    check_paths(job)
+    if args.compression is not None:
+        require_compression(args.compression)
+        require_level(args.compression, args.level)
+    elif args.level is not None:
+        raise UsageError("--level needs --compression")
+    encryption = EncryptionOptions.from_args(args)
+    plan = build_plan(encryption, ctx)
+    with open_archive(job.input) as src:
+        infos = src.infolist()
+        assignment = plan.assign([info.filename for info in infos if not info.is_dir()])
+        if not job.report.quiet:
+            warn_if_weak(assignment.methods, ctx)
+        old_pool = old_password_pool(args, ctx)
+        passwords = read_passwords(src, infos, old_pool)
+        plan.resolve_prompts(assignment, ctx)
+        targets: list[Target] = []
+        for info, password in zip(infos, passwords, strict=True):
+            if info.is_dir():
+                targets.append(PLAIN)
+            elif rule := assignment.chosen.get(info.filename):
+                targets.append(
+                    target_for_method(
+                        rule.method, rule.password, encryption.wz_aes_version
+                    )
+                )
+            else:
+                targets.append(keep_target(info, password))
+        return run_copy(
+            ctx,
+            src,
+            passwords,
+            targets,
+            job,
+            verb="Rewrote",
+            compress_type=None
+            if args.compression is None
+            else COMPRESSION[args.compression],
+            level=args.level,
+        )
+
+
+def register(subparsers: Subparsers) -> None:
+    parser = add_command(
+        subparsers,
+        "rewrite",
+        cmd_rewrite,
+        "copy an archive into a new one, changing its encryption or compression",
+    )
+    add_copy_options(parser)
+    parser.add_argument(
+        "--compression",
+        metavar="METHOD",
+        choices=list(COMPRESSION),
+        help=f"Compression method for every member: {', '.join(COMPRESSION)}. "
+        "Default: each member keeps its own",
+    )
+    parser.add_argument(
+        "-L",
+        "--level",
+        type=int,
+        metavar="N",
+        help="Compression level. Needs --compression",
+    )
+    add_encryption_options(parser)
+    add_old_password_options(parser)
+    add_password_options(parser)

zipctl/cli/commands/test.py

@@ -0,0 +1,154 @@
+"""The ``test`` command."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Protocol
+
+from zipctl.cli.archive import CHUNK, 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,
+    password_pool,
+)
+from zipctl.cli.commands.helpers.passwords.pool import PasswordPool, PasswordProblem
+from zipctl.cli.commands.helpers.progress import (
+    ProgressArgs,
+    ProgressRenderer,
+    StepReporter,
+    add_progress_option,
+    progress_renderer,
+)
+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
+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
+
+
+class TestArgs(OutputArgs, PasswordArgs, ProgressArgs, Protocol):
+    archive: str
+    members: list[str]
+
+
+@dataclass(frozen=True)
+class Tested:
+    """The outcome for one member; *detail* says what is wrong when it is not *ok*."""
+
+    name: str
+    ok: bool
+    detail: str | None = None
+
+    @property
+    def status(self) -> str:
+        return "ok" if self.ok else "failed"
+
+
+def _test_member(zf: ZipFile, info: ZipInfo, pool: PasswordPool) -> Tested:
+    """Read *info* to its end."""
+    password = None
+    if info.is_encrypted:
+        resolved = pool.resolve(zf, info)
+        if isinstance(resolved, PasswordProblem):
+            return Tested(info.filename, False, resolved.text)
+        password = resolved
+    try:
+        with zf.open(info, pwd=password) as stream:
+            while stream.read(CHUNK):
+                pass
+    except Exception as exc:  # any failure to read a member means it is bad
+        return Tested(info.filename, False, _read_error_text(exc, info))
+    return Tested(info.filename, True)
+
+
+def _read_error_text(exc: Exception, info: ZipInfo) -> str:
+    text = str(exc) or type(exc).__name__
+    if isinstance(exc, BadZipFile) and info.is_encrypted:
+        return f"{text} (corrupt data, or the password is wrong)"
+    if isinstance(exc, EOFError):
+        return "data is truncated"
+    if isinstance(exc, (NotImplementedError, RuntimeError)):
+        return f"unsupported: {text}"
+    if isinstance(exc, BadZipFile):
+        return text
+    return f"{type(exc).__name__}: {text}"
+
+
+def _test_members(
+    zf: ZipFile,
+    infos: list[ZipInfo],
+    pool: PasswordPool,
+    renderer: ProgressRenderer | None,
+) -> list[Tested]:
+    steps = StepReporter(renderer, ((i.filename, i.file_size) for i in infos))
+    results: list[Tested] = []
+    for index, info in enumerate(infos):
+        steps.start(index)
+        if renderer is not None and info.is_encrypted:
+            renderer.clear()  # keep a prompt from colliding with the status line
+        result = _test_member(zf, info, pool)
+        results.append(result)
+        steps.finish(index, ok=result.ok)
+    return results
+
+
+def cmd_test(args: TestArgs, ctx: Context) -> int:
+    with progress_renderer(ctx.stderr, args.progress) as renderer:
+        with open_archive(args.archive) as zf:
+            pool = password_pool(PasswordOptions.from_args(args), ctx)
+            infos = select_infos(zf.infolist(), args.members)
+            results = _test_members(zf, infos, pool, renderer)
+
+    failed = [result for result in results if not result.ok]
+    if args.json:
+        write_json(
+            ctx.stdout,
+            {
+                "ok": not failed,
+                "archive": args.archive,
+                "tested": len(results),
+                "failed": len(failed),
+                "members": [
+                    {"name": r.name, "status": r.status, "detail": r.detail}
+                    for r in results
+                ],
+            },
+        )
+    else:
+        lines: list[str] = []
+        for result in results:
+            if not result.ok:
+                name, detail = printable(result.name), printable(result.detail or "")
+                lines.append(f"FAILED  {name}: {detail}")
+            elif args.verbose:
+                lines.append(f"OK      {printable(result.name)}")
+        for line in lines:
+            ctx.out(line)
+        if failed or not args.quiet:
+            if lines:
+                ctx.out("")
+            tested = f"Tested {count(len(results), 'member')}"
+            ctx.out(
+                f"{tested}: {len(failed)} failed" if failed else f"{tested}: all OK"
+            )
+    return EXIT_FAILURE if failed else EXIT_OK
+
+
+def register(subparsers: Subparsers) -> None:
+    parser = add_command(
+        subparsers, "test", cmd_test, "read every member and check its integrity"
+    )
+    parser.add_argument("archive", metavar="ARCHIVE", help="the archive to test")
+    parser.add_argument("members", nargs="*", metavar="MEMBER", help=MEMBER_HELP)
+    add_progress_option(parser)
+    add_output_options(parser, verbose_help="also list members that pass", quiet=True)
+    add_password_options(parser)

zipctl/cli/context.py

@@ -0,0 +1,57 @@
+"""The streams and environment a command runs against."""
+
+from __future__ import annotations
+
+import os
+import sys
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import BinaryIO, TextIO
+
+from zipctl.cli.errors import UsageError
+
+__all__ = ["Context"]
+
+
+@dataclass
+class Context:
+    """The streams and environment a command runs against."""
+
+    stdin: TextIO
+    stdout: TextIO
+    stderr: TextIO
+    environ: Mapping[str, str]
+    _stdin_user: str | None = field(default=None, init=False, repr=False)
+    warned: bool = field(default=False, init=False, repr=False)
+
+    @classmethod
+    def from_process(cls) -> Context:
+        """Bind to the current ``sys`` streams (looked up at call time)."""
+        return cls(sys.stdin, sys.stdout, sys.stderr, os.environ)
+
+    def claim_stdin(self, purpose: str) -> None:
+        """Reserve standard input for *purpose*; it can only be read once."""
+        if self._stdin_user is not None:
+            raise UsageError(
+                f"standard input cannot be used for both {self._stdin_user} "
+                f"and {purpose}",
+            )
+        self._stdin_user = purpose
+
+    def read_stdin(self, *, line: bool = False) -> bytes:
+        """The rest of standard input, or only its next line, as bytes."""
+        binary: BinaryIO | None = getattr(self.stdin, "buffer", None)
+        if binary is not None:
+            return binary.readline() if line else binary.read()
+        text = self.stdin.readline() if line else self.stdin.read()
+        return text.encode("utf-8")
+
+    def out(self, line: str = "") -> None:
+        print(line, file=self.stdout)
+
+    def err(self, line: str = "") -> None:
+        print(line, file=self.stderr)
+
+    def warn(self, text: str) -> None:
+        self.warned = True
+        self.err(f"zipctl: warning: {text}")

zipctl/cli/errors.py

@@ -0,0 +1,58 @@
+"""Exit codes and the error type command handlers raise."""
+
+from __future__ import annotations
+
+from zipctl.cli.output import format_table
+
+EXIT_OK = 0
+EXIT_FAILURE = 1  # the operation ran and failed (bad member, violations, ...)
+EXIT_USAGE = 2  # bad command line or bad configuration file
+EXIT_BROKEN_PIPE = 141  # 128 + SIGPIPE: the reader of our output went away
+EXIT_INTERRUPTED = 130  # 128 + SIGINT
+
+EXIT_CODES = (
+    (EXIT_OK, "success"),
+    (EXIT_FAILURE, "the operation ran and failed (bad member, policy violations, ...)"),
+    (
+        EXIT_USAGE,
+        "bad command line, bad configuration file or a pattern matching nothing",
+    ),
+    (EXIT_INTERRUPTED, "interrupted"),
+    (EXIT_BROKEN_PIPE, "the reader of the output went away"),
+)
+
+
+def exit_codes_table() -> str:
+    """The exit codes and their meaning, as printed by ``zipctl --exit-codes``."""
+    rows = [[str(code), meaning] for code, meaning in EXIT_CODES]
+    return "\n".join(format_table(["CODE", "MEANING"], rows))
+
+
+class CliError(Exception):
+    """A failure to report as ``zipctl: error: MESSAGE`` and exit with *code*."""
+
+    def __init__(
+        self, message: str, code: int = EXIT_FAILURE, details: tuple[str, ...] = ()
+    ) -> None:
+        super().__init__(message)
+        self.message: str = message
+        self.code: int = code
+        self.details: tuple[str, ...] = details
+
+
+class UsageError(CliError):
+    """A bad command line or configuration: exit code :data:`EXIT_USAGE`."""
+
+    def __init__(self, message: str, details: tuple[str, ...] = ()) -> None:
+        super().__init__(message, EXIT_USAGE, details)
+
+
+def os_error_text(exc: OSError) -> str:
+    """The system's wording for *exc* (its message when it has no error code)."""
+    return exc.strerror or str(exc)
+
+
+def os_error_filename(exc: OSError) -> str | None:
+    """The path *exc* is about, or ``None`` when it names none."""
+    name: object = exc.filename  # pyright: ignore[reportAny]  # typeshed: Any
+    return str(name) if name else None

zipctl/cli/formatter.py

@@ -0,0 +1,62 @@
+"""The help formatter every ``zipctl`` parser uses."""
+
+from __future__ import annotations
+
+import argparse
+from collections.abc import Iterable
+
+from typing_extensions import override
+
+__all__ = ["HelpFormatter"]
+
+
+def _capitalize(text: str) -> str:
+    """Upper-case the first letter only (``str.capitalize`` would lower the rest)."""
+    return text[:1].upper() + text[1:]
+
+
+def _option_name(action: argparse.Action) -> str:
+    """The name options are sorted by: the long option, without its dashes."""
+    strings = action.option_strings
+    return next((s for s in strings if s.startswith("--")), strings[0]).lstrip("-")
+
+
+class HelpFormatter(argparse.RawDescriptionHelpFormatter):
+    """Capitalise headings and descriptions; list the options alphabetically."""
+
+    _options_section: bool = False
+
+    def __init__(self, prog: str) -> None:
+        # a wider help column leaves room for "-d, --destination DIR"
+        super().__init__(prog, max_help_position=30)
+
+    @override
+    def start_section(self, heading: str | None) -> None:
+        self._options_section = heading == "options"
+        if heading == "positional arguments":
+            heading = "arguments"
+        super().start_section(_capitalize(heading) if heading else heading)
+
+    @override
+    def add_arguments(self, actions: Iterable[argparse.Action]) -> None:
+        if self._options_section:
+            actions = sorted(actions, key=lambda action: _option_name(action).lower())
+        super().add_arguments(actions)
+
+    @override
+    def _format_action(self, action: argparse.Action) -> str:
+        """List subcommands directly, without argparse's ``COMMAND`` header line."""
+        if isinstance(action, argparse._SubParsersAction):  # pyright: ignore[reportPrivateUsage]
+            return "".join(
+                super(HelpFormatter, self)._format_action(sub)
+                for sub in action._get_subactions()
+            )
+        return super()._format_action(action)
+
+    @override
+    def _format_text(self, text: str) -> str:
+        return super()._format_text(_capitalize(text))
+
+    @override
+    def _expand_help(self, action: argparse.Action) -> str:
+        return _capitalize(super()._expand_help(action))

zipctl/cli/methods.py

@@ -0,0 +1,136 @@
+"""The compression and encryption methods the CLI knows, in one place."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from zipctl.cli.errors import UsageError
+from zipctl.compression import (
+    ZIP_BZIP2,
+    ZIP_DEFLATED,
+    ZIP_LZMA,
+    ZIP_STORED,
+    ZIP_ZSTANDARD,
+    compressor_names,
+    registry,
+)
+from zipctl.cryptography import WZ_AES, ZIP_CRYPTO
+from zipctl.zipfile.file import ZipFileExtra
+from zipctl.zipfile.info import ZipInfo
+
+__all__ = [
+    "COMPRESSION",
+    "ENCRYPTABLE",
+    "ENCRYPTION_METHODS",
+    "EncryptionMethod",
+    "METHOD_CHOICES",
+    "NO_ENCRYPTION",
+    "UNKNOWN_AES",
+    "compression_label",
+    "extra_for",
+    "method_of",
+    "require_compression",
+    "require_level",
+]
+
+
+@dataclass(frozen=True)
+class EncryptionMethod:
+    """One name a user can give for how a member is protected."""
+
+    name: str
+    scheme: str | None  # the ZipFile encryption scheme; None for plain
+    aes_bits: int  # AES key size; 0 when the scheme is not AES
+    label: str  # how listings and reports call it
+
+    @property
+    def is_aes(self) -> bool:
+        return self.scheme == WZ_AES
+
+    @property
+    def is_encrypted(self) -> bool:
+        return self.scheme is not None
+
+
+ENCRYPTION_METHODS = {
+    method.name: method
+    for method in (
+        EncryptionMethod("aes256", WZ_AES, 256, "AES-256"),
+        EncryptionMethod("aes192", WZ_AES, 192, "AES-192"),
+        EncryptionMethod("aes128", WZ_AES, 128, "AES-128"),
+        EncryptionMethod("zipcrypto", ZIP_CRYPTO, 0, "ZipCrypto"),
+        EncryptionMethod("none", None, 0, "none"),
+    )
+}
+METHOD_CHOICES = ", ".join(ENCRYPTION_METHODS)  # for messages and help
+ENCRYPTABLE = tuple(name for name in ENCRYPTION_METHODS if name != "none")
+NO_ENCRYPTION = ENCRYPTION_METHODS["none"]
+# An AES strength this tool does not know; readable in a listing, never written.
+UNKNOWN_AES = EncryptionMethod("aes", WZ_AES, 0, "AES")
+
+# Method names the CLI takes -> ZIP compression ids.
+COMPRESSION = {
+    compressor_names[compress_type]: compress_type
+    for compress_type in (
+        ZIP_STORED,
+        ZIP_DEFLATED,
+        ZIP_BZIP2,
+        ZIP_LZMA,
+        ZIP_ZSTANDARD,
+    )
+}
+
+# Compression levels each method accepts (the registry does not record them);
+# store and lzma take none.
+_LEVELS = {
+    "deflate": range(10),
+    "bzip2": range(1, 10),
+    "zstd": range(-131072, 23),
+}
+
+
+def method_of(info: ZipInfo) -> EncryptionMethod:
+    """How the member described by *info* is protected in its archive."""
+    scheme = info.encryption_scheme
+    if scheme is None:
+        return NO_ENCRYPTION
+    if scheme == ZIP_CRYPTO:
+        return ENCRYPTION_METHODS["zipcrypto"]
+    bits = info.aes_bits
+    return ENCRYPTION_METHODS[f"aes{bits}"] if bits else UNKNOWN_AES
+
+
+def extra_for(method: EncryptionMethod, aes_version: int | None) -> ZipFileExtra | None:
+    """The per-entry AES settings for *method* (``None`` when it has none)."""
+    if not method.is_aes:
+        return None
+    return ZipFileExtra(force_wz_aes_version=aes_version, wz_aes_nbits=method.aes_bits)
+
+
+def require_compression(method: str) -> None:
+    """Refuse a *method* (a key of :data:`COMPRESSION`) this install cannot run."""
+    try:
+        registry.check_compression(COMPRESSION[method])
+    except (RuntimeError, NotImplementedError):
+        extra = " (install zipctl[zstd])" if method == "zstd" else ""
+        raise UsageError(
+            f"compression method {method!r} is not available{extra}"
+        ) from None
+
+
+def require_level(method: str, level: int | None) -> None:
+    """Refuse a *level* the compression *method* cannot use."""
+    if level is None:
+        return
+    levels = _LEVELS.get(method)
+    if levels is None:
+        raise UsageError(f"compression method {method!r} takes no --level")
+    if level not in levels:
+        raise UsageError(
+            f"--level {level} is out of range for {method} "
+            f"({levels[0]} to {levels[-1]})",
+        )
+
+
+def compression_label(info: ZipInfo) -> str:
+    return compressor_names.get(info.compress_type, str(info.compress_type))