zipctl 0.1.0__py3-none-any.whl

zipctl/cli/commands/helpers/encryption/options.py

@@ -0,0 +1,192 @@
+"""The encryption options of ``create`` and ``rewrite``, and the plan they build."""
+
+from __future__ import annotations
+
+import argparse
+from collections.abc import Iterable
+from dataclasses import dataclass
+from typing import Protocol
+
+from zipctl.cli.commands.helpers.encryption.plan import EncryptionPlan, Rule
+from zipctl.cli.commands.helpers.encryption.spec import plan_from_spec
+from zipctl.cli.commands.helpers.passwords.options import (
+    PasswordArgs,
+    PasswordOptions,
+    given_password,
+)
+from zipctl.cli.commands.helpers.passwords.sources import (
+    readers_for,
+    require_tty_for_prompt,
+)
+from zipctl.cli.commands.helpers.sources import read_text_source
+from zipctl.cli.context import Context
+from zipctl.cli.errors import UsageError
+from zipctl.cli.methods import (
+    ENCRYPTION_METHODS,
+    METHOD_CHOICES,
+    NO_ENCRYPTION,
+    EncryptionMethod,
+)
+from zipctl.cli.output import did_you_mean, printable
+from zipctl.cryptography import WZ_AES_DEFAULT_VERSION
+
+
+class EncryptionArgs(PasswordArgs, Protocol):
+    """What :func:`add_encryption_options` leaves on the parsed arguments."""
+
+    encryption: str | None
+    protect: list[str]
+    encryption_spec: str | None
+    wz_aes_version: int | None
+
+
+@dataclass(frozen=True)
+class EncryptionOptions:
+    """The options of :func:`add_encryption_options`, with the password options."""
+
+    encryption: str | None
+    protect: list[str]
+    spec: str | None
+    wz_aes_version: int | None
+    passwords: PasswordOptions
+
+    @classmethod
+    def from_args(cls, args: EncryptionArgs) -> EncryptionOptions:
+        return cls(
+            args.encryption,
+            args.protect,
+            args.encryption_spec,
+            args.wz_aes_version,
+            PasswordOptions.from_args(args),
+        )
+
+
+def plan_from_options(options: EncryptionOptions, ctx: Context) -> EncryptionPlan:
+    """The plan for ``--encryption`` and ``--protect`` (passwords come later)."""
+    rules: list[Rule] = []
+    for text in options.protect:
+        pattern, name = _split_protect(text)
+        if not pattern:
+            raise UsageError("--protect needs a pattern")
+        method = ENCRYPTION_METHODS[name]
+        typed = method.is_encrypted
+        rules.append(
+            Rule(
+                pattern,
+                method,
+                prompt=f"Password for {pattern}" if typed else None,
+                hint=(
+                    f"the password for {printable(pattern)} can only be typed at a "
+                    "terminal; use --encryption-spec to script it"
+                    if typed
+                    else None
+                ),
+            )
+        )
+    default = options.encryption
+    passwords = options.passwords
+    sources = passwords.file is not None or passwords.stdin
+    if default in (None, "none"):
+        if sources or passwords.prompt:
+            raise UsageError(
+                "a password option was given but --encryption names nothing to "
+                "protect with it (--protect rules ask for their own passwords)",
+            )
+        if default == "none":
+            rules.append(Rule(None, NO_ENCRYPTION))
+    else:
+        if passwords.prompt:
+            require_tty_for_prompt(ctx)
+        password = given_password(passwords, ctx)
+        rules.append(
+            Rule(
+                None,
+                ENCRYPTION_METHODS[default],
+                password=password,
+                prompt=None if password else "Password",
+            )
+        )
+    return EncryptionPlan(rules)
+
+
+def _split_protect(text: str) -> tuple[str, str]:
+    """Split ``GLOB[=METHOD]``; the method is only taken if it is a known one.
+
+    A suffix that is not a method but nearly is (``=aes265``) is a typo, not
+    part of the glob.
+    """
+    pattern, _, method = text.rpartition("=")
+    if pattern and method in ENCRYPTION_METHODS:
+        return pattern, method
+    guess = did_you_mean(method, list(ENCRYPTION_METHODS)) if pattern else ""
+    if guess:
+        raise UsageError(
+            f"--protect {printable(text)!r}: unknown method {printable(method)!r}"
+            f"{guess} (choose from {METHOD_CHOICES})",
+        )
+    return text, "aes256"
+
+
+def build_plan(options: EncryptionOptions, ctx: Context) -> EncryptionPlan:
+    """The plan for ``--encryption``/``--protect`` or for ``--encryption-spec``."""
+    if options.spec is None:
+        plan = plan_from_options(options, ctx)
+    else:
+        if options.encryption is not None or options.protect:
+            raise UsageError(
+                "--encryption-spec cannot be combined with --encryption or --protect; "
+                "put those rules in the spec",
+            )
+        passwords = options.passwords
+        if passwords.file is not None or passwords.stdin or passwords.prompt:
+            raise UsageError(
+                "password options do not apply with --encryption-spec; the spec says "
+                "where each password comes from",
+            )
+        text = read_text_source(options.spec, ctx, "encryption spec")
+        plan = plan_from_spec(text, options.spec, readers_for(ctx))
+    require_aes_for_version(options.wz_aes_version, plan.methods)
+    return plan
+
+
+def require_aes_for_version(
+    version: int | None, methods: Iterable[EncryptionMethod]
+) -> None:
+    """Refuse ``--wz-aes-version`` when none of *methods* is an AES one."""
+    if version is not None and not any(method.is_aes for method in methods):
+        raise UsageError("--wz-aes-version only applies to AES encryption")
+
+
+def add_wz_aes_version(parser: argparse.ArgumentParser) -> None:
+    """Add ``--wz-aes-version`` to *parser*."""
+    parser.add_argument(
+        "--wz-aes-version",
+        type=int,
+        choices=(1, 2),
+        metavar="VERSION",
+        help=f"WinZip AES version to write: 1 or 2. Default: {WZ_AES_DEFAULT_VERSION}",
+    )
+
+
+def add_encryption_options(parser: argparse.ArgumentParser) -> None:
+    """Add the encryption options: method, per-member rules, spec file, AES version."""
+    parser.add_argument(
+        "--encryption",
+        metavar="METHOD",
+        choices=list(ENCRYPTION_METHODS),
+        help=f"Encryption method: {METHOD_CHOICES}",
+    )
+    parser.add_argument(
+        "--protect",
+        action="append",
+        default=[],
+        metavar="GLOB[=METHOD]",
+        help="Encrypt members matching GLOB, or leave them plain with GLOB=none. "
+        "Repeatable. Default: aes256",
+    )
+    parser.add_argument(
+        "--encryption-spec",
+        metavar="FILE",
+        help="JSON file with the rules and password references ('-' is standard input)",
+    )
+    add_wz_aes_version(parser)

zipctl/cli/commands/helpers/encryption/plan.py

@@ -0,0 +1,119 @@
+"""The rules that decide how each member is protected."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable, Sequence
+from dataclasses import dataclass
+
+from zipctl.cli.commands.helpers.passwords.sources import (
+    prompt_new_password,
+    prompt_password,
+)
+from zipctl.cli.commands.helpers.selection import glob_matcher
+from zipctl.cli.context import Context
+from zipctl.cli.errors import UsageError
+from zipctl.cli.methods import EncryptionMethod
+from zipctl.cli.output import printable
+from zipctl.cryptography import ZIP_CRYPTO
+
+
+@dataclass(eq=False)  # compared by identity: two equal rules are still two rules
+class Rule:
+    """One line of the plan: members matching *pattern* get *method*.
+
+    *pattern* is ``None`` for the default rule, which matches every member.
+    A rule whose password is to be typed keeps its prompt in *prompt* until
+    :meth:`EncryptionPlan.resolve_prompts` asks for it; *hint* is what to say
+    when there is no terminal to ask at.
+    """
+
+    pattern: str | None
+    method: EncryptionMethod
+    password: bytes | None = None
+    prompt: str | None = None
+    hint: str | None = None
+
+
+@dataclass(frozen=True)
+class PlanAssignment:
+    """The rule chosen for each member (``None``: no rule covers it)."""
+
+    chosen: dict[str, Rule | None]
+
+    @property
+    def used(self) -> set[Rule]:
+        """Every rule that decides at least one member."""
+        return {rule for rule in self.chosen.values() if rule is not None}
+
+    @property
+    def methods(self) -> set[EncryptionMethod]:
+        return {rule.method for rule in self.chosen.values() if rule is not None}
+
+
+class EncryptionPlan:
+    """An ordered list of :class:`Rule`; the default rule (if any) comes last."""
+
+    def __init__(self, rules: Iterable[Rule] = ()) -> None:
+        self.rules: list[Rule] = list(rules)
+
+    @property
+    def methods(self) -> set[EncryptionMethod]:
+        return {rule.method for rule in self.rules}
+
+    def assign(self, names: Sequence[str]) -> PlanAssignment:
+        """Pick a rule for each of *names*, refusing rules that would do nothing.
+
+        A typo in a pattern must not silently leave files unprotected, so every
+        non-default rule has to be the deciding one for at least one member.
+        """
+        matchers = [
+            (rule, None if rule.pattern is None else glob_matcher(rule.pattern))
+            for rule in self.rules
+        ]
+        chosen: dict[str, Rule | None] = {}
+        for name in names:
+            chosen[name] = next(
+                (
+                    rule
+                    for rule, matches in matchers
+                    if matches is None or matches(name)
+                ),
+                None,
+            )
+        assignment = PlanAssignment(chosen)
+        used = assignment.used
+        idle = [
+            rule for rule in self.rules if rule.pattern is not None and rule not in used
+        ]
+        if idle:
+            listed = ", ".join(f"'{printable(rule.pattern or '')}'" for rule in idle)
+            raise UsageError(
+                f"no member is decided by the rule for {listed} (nothing matches, "
+                "or an earlier rule already covers everything it matches)",
+            )
+        return assignment
+
+    def resolve_prompts(
+        self,
+        assignment: PlanAssignment,
+        ctx: Context,
+        prompt: Callable[[str], str] = prompt_password,
+    ) -> None:
+        """Ask for the passwords of the used rules that are still missing one."""
+        used = assignment.used
+        for rule in self.rules:
+            if rule.prompt is not None and rule.password is None and rule in used:
+                rule.password = prompt_new_password(
+                    rule.prompt,
+                    ctx,
+                    hint=rule.hint,
+                    prompt=prompt,
+                )
+
+
+def warn_if_weak(methods: Iterable[EncryptionMethod], ctx: Context) -> None:
+    if any(method.scheme == ZIP_CRYPTO for method in methods):
+        ctx.warn(
+            "ZipCrypto is a weak legacy cipher; prefer aes256 "
+            "unless a tool needs ZipCrypto"
+        )

zipctl/cli/commands/helpers/encryption/spec.py

@@ -0,0 +1,256 @@
+"""The JSON encryption spec: rules whose passwords are references, not values."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Sequence
+from typing import cast
+
+from zipctl.cli.commands.helpers.encryption.plan import EncryptionPlan, Rule
+from zipctl.cli.commands.helpers.passwords.sources import (
+    PasswordReaders,
+    password_bytes,
+)
+from zipctl.cli.commands.helpers.selection import glob_matcher
+from zipctl.cli.errors import CliError, UsageError
+from zipctl.cli.methods import ENCRYPTION_METHODS, METHOD_CHOICES
+from zipctl.cli.output import did_you_mean, printable
+
+_SPEC_KEYS = ("version", "default", "rules")
+_RULE_KEYS = ("match", "method", "password")
+_DEFAULT_KEYS = ("method", "password")
+_REFERENCES = ("env", "file", "prompt", "stdin")
+
+
+class _Issues:
+    def __init__(self) -> None:
+        self.items: list[str] = []
+
+    def add(self, path: str, message: str) -> None:
+        self.items.append(f"{path or '<spec>'}: {message}")
+
+
+def _as_object(data: object) -> dict[str, object] | None:
+    """*data* as a JSON object, whose keys ``json.loads`` makes strings."""
+    return cast("dict[str, object]", data) if isinstance(data, dict) else None
+
+
+def _check_keys(
+    data: dict[str, object], known: Sequence[str], path: str, issues: _Issues
+) -> None:
+    for key in data:
+        if key not in known:
+            issues.add(path, f"unknown key {key!r}{did_you_mean(key, known)}")
+
+
+def _reference_entry(
+    data: object, path: str, issues: _Issues
+) -> tuple[str, object] | None:
+    """The ``(kind, value)`` a password reference names, or ``None`` if malformed."""
+    reference = _as_object(data)
+    if reference is None:
+        issues.add(path, 'expected an object like {"env": "NAME"}')
+        return None
+    if "value" in reference or "password" in reference:
+        issues.add(
+            path, "inline passwords are not allowed; use env, file, prompt or stdin"
+        )
+        return None
+    if len(reference) != 1 or next(iter(reference)) not in _REFERENCES:
+        issues.add(path, f"expected exactly one of: {', '.join(_REFERENCES)}")
+        return None
+    ((kind, value),) = reference.items()
+    return kind, value
+
+
+def _stdin_password(
+    value: object,
+    path: str,
+    readers: PasswordReaders,
+    issues: _Issues,
+    stdin_uses: list[str],
+) -> bytes | None:
+    if value is not True:
+        issues.add(f"{path}.stdin", "must be true")
+        return None
+    if stdin_uses:
+        issues.add(path, "standard input can only be used by one password")
+        return None
+    stdin_uses.append(path)
+    try:
+        return readers.stdin()
+    except CliError as exc:
+        issues.add(path, exc.message)
+        return None
+
+
+def _reference(
+    data: object,
+    path: str,
+    readers: PasswordReaders,
+    issues: _Issues,
+    stdin_uses: list[str],
+) -> tuple[bytes | None, str | None]:
+    """Resolve a password reference to ``(password, prompt_label)``."""
+    entry = _reference_entry(data, path, issues)
+    if entry is None:
+        return None, None
+    kind, value = entry
+    if kind == "stdin":
+        return _stdin_password(value, path, readers, issues, stdin_uses), None
+    if not isinstance(value, str) or not value:
+        issues.add(f"{path}.{kind}", "expected a non-empty string")
+        return None, None
+    if kind == "prompt":
+        return None, value
+    if kind == "env":
+        text = readers.env.get(value)
+        if not text:
+            issues.add(
+                f"{path}.env", f"environment variable {value} is not set or is empty"
+            )
+            return None, None
+        return password_bytes(text), None
+    try:
+        return readers.file(value), None
+    except CliError as exc:
+        issues.add(f"{path}.file", exc.message)
+        return None, None
+
+
+def _match_pattern(fields: dict[str, object], path: str, issues: _Issues) -> str | None:
+    """The rule's ``match`` glob, or ``None`` if it is missing or invalid."""
+    given = fields.get("match")
+    if not isinstance(given, str) or not given:
+        issues.add(f"{path}.match", "required: a non-empty pattern string")
+        return None
+    try:
+        glob_matcher(given)
+    except CliError as exc:
+        issues.add(f"{path}.match", exc.message)
+        return None
+    return given
+
+
+def _rule(
+    data: object,
+    path: str,
+    readers: PasswordReaders,
+    issues: _Issues,
+    stdin_uses: list[str],
+    *,
+    is_default: bool,
+) -> Rule | None:
+    fields = _as_object(data)
+    if fields is None:
+        issues.add(path, "expected an object")
+        return None
+    _check_keys(fields, _DEFAULT_KEYS if is_default else _RULE_KEYS, path, issues)
+    pattern: str | None = None
+    if not is_default:
+        pattern = _match_pattern(fields, path, issues)
+        if pattern is None:
+            return None
+    name = fields.get("method")
+    if not isinstance(name, str) or name not in ENCRYPTION_METHODS:
+        issues.add(f"{path}.method", f"required: one of {METHOD_CHOICES}")
+        return None
+    method = ENCRYPTION_METHODS[name]
+    if not method.is_encrypted:
+        if "password" in fields:
+            issues.add(f"{path}.password", 'not allowed with method "none"')
+        return Rule(pattern, method)
+    if "password" not in fields:
+        issues.add(f"{path}.password", "required for an encrypting method")
+        return None
+    password, prompt = _reference(
+        fields["password"], f"{path}.password", readers, issues, stdin_uses
+    )
+    if password is None and prompt is None:
+        return None
+    hint = None
+    if prompt is not None:
+        hint = (
+            f"the password for {printable(pattern) if pattern else 'the default rule'} "
+            'can only be typed at a terminal; use an {"env": ...}, {"file": ...} or '
+            '{"stdin": true} reference in the spec to script it'
+        )
+    return Rule(pattern, method, password=password, prompt=prompt, hint=hint)
+
+
+def _no_duplicates(pairs: list[tuple[str, object]]) -> dict[str, object]:
+    keys = [key for key, _ in pairs]
+    dupes = sorted({key for key in keys if keys.count(key) > 1})
+    if dupes:
+        raise ValueError(f"duplicate key {dupes[0]!r} in a JSON object")
+    return dict(pairs)
+
+
+def _rule_items(data: dict[str, object], issues: _Issues) -> list[object]:
+    given = data.get("rules", [])
+    if isinstance(given, list):
+        return cast("list[object]", given)
+    issues.add("rules", "expected a list")
+    return []
+
+
+def _list_rules(
+    items: list[object],
+    readers: PasswordReaders,
+    issues: _Issues,
+    stdin_uses: list[str],
+) -> list[Rule]:
+    rules: list[Rule] = []
+    seen: set[str] = set()
+    for index, item in enumerate(items):
+        rule = _rule(
+            item,
+            f"rules[{index}]",
+            readers,
+            issues,
+            stdin_uses,
+            is_default=False,
+        )
+        if rule is None:
+            continue
+        if rule.pattern in seen:
+            issues.add(f"rules[{index}].match", f"duplicate pattern {rule.pattern!r}")
+        seen.add(rule.pattern or "")
+        rules.append(rule)
+    return rules
+
+
+def plan_from_spec(text: str, origin: str, readers: PasswordReaders) -> EncryptionPlan:
+    """Parse an encryption spec; every problem is reported together."""
+    where = f"invalid encryption spec ({printable(origin)})"
+    try:
+        # json.loads is typed to return Any
+        document: object = json.loads(text, object_pairs_hook=_no_duplicates)  # pyright: ignore[reportAny]
+    except ValueError as exc:
+        raise UsageError(where, (printable(f"not valid JSON: {exc}"),)) from None
+    issues = _Issues()
+    data = _as_object(document)
+    if data is None:
+        raise UsageError(where, ("<spec>: expected a JSON object",))
+    _check_keys(data, _SPEC_KEYS, "", issues)
+    if data.get("version", 1) != 1:
+        issues.add("version", "unsupported; this zipctl reads version 1")
+    stdin_uses: list[str] = []
+    listed = _rule_items(data, issues)
+    rules = _list_rules(listed, readers, issues, stdin_uses)
+    if "default" in data:
+        default = _rule(
+            data["default"],
+            "default",
+            readers,
+            issues,
+            stdin_uses,
+            is_default=True,
+        )
+        if default is not None:
+            rules.append(default)
+    if not listed and "default" not in data and not issues.items:
+        issues.add("", "defines no rules and no default, so nothing would be encrypted")
+    if issues.items:
+        raise UsageError(where, tuple(printable(item) for item in issues.items))
+    return EncryptionPlan(rules)