controlled-text-transfer 0.1.0__py3-none-any.whl

controlled_text_transfer/__init__.py

@@ -0,0 +1,3 @@
+"""Safe, auditable text-only transfer packaging."""
+
+__version__ = "0.1.0"

controlled_text_transfer/__main__.py

@@ -0,0 +1,8 @@
+"""Run the CTT CLI with ``python -m controlled_text_transfer``."""
+
+from __future__ import annotations
+
+from controlled_text_transfer.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

controlled_text_transfer/cleanup.py

@@ -0,0 +1,179 @@
+"""Remove reproducible caches and build artifacts from this repository."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import shutil
+import sys
+from collections.abc import Sequence
+from dataclasses import dataclass
+from pathlib import Path
+
+TOP_LEVEL_ARTIFACTS = frozenset(
+    {
+        "build",
+        "dist",
+        ".pytest_cache",
+        ".mypy_cache",
+        ".ruff_cache",
+        ".coverage",
+        "reports",
+    }
+)
+PRUNED_DIRECTORIES = frozenset({".git", ".venv"}) | TOP_LEVEL_ARTIFACTS
+
+
+class CleanupError(RuntimeError):
+    """Report an unsafe or unsuccessful cleanup request."""
+
+
+@dataclass(frozen=True)
+class CleanupResult:
+    """Describe the deterministic outcome of a cleanup operation."""
+
+    planned: tuple[Path, ...]
+    removed: tuple[Path, ...]
+
+
+def _sort_paths(paths: set[Path]) -> tuple[Path, ...]:
+    return tuple(sorted(paths, key=lambda path: path.as_posix()))
+
+
+def discover_targets(root: Path, *, include_environment: bool = False) -> tuple[Path, ...]:
+    """Return reproducible artifacts below ``root`` without following symlinks."""
+    repository = root.resolve(strict=True)
+    if not repository.is_dir():
+        raise CleanupError(f"repository root is not a directory: {repository}")
+
+    targets = {
+        repository / name
+        for name in TOP_LEVEL_ARTIFACTS
+        if (repository / name).exists() or (repository / name).is_symlink()
+    }
+    if include_environment:
+        environment = repository / ".venv"
+        if environment.exists() or environment.is_symlink():
+            targets.add(environment)
+
+    for current, directories, _files in os.walk(repository, followlinks=False):
+        current_path = Path(current)
+        safe_directories: list[str] = []
+        for name in directories:
+            candidate = current_path / name
+            if candidate.is_symlink() or candidate.is_junction():
+                if name == "__pycache__" or name.endswith(".egg-info"):
+                    targets.add(candidate)
+                continue
+            if name == "__pycache__" or name.endswith(".egg-info"):
+                targets.add(candidate)
+                continue
+            if current_path == repository and name in PRUNED_DIRECTORIES:
+                continue
+            safe_directories.append(name)
+        directories[:] = safe_directories
+
+    return _sort_paths(targets)
+
+
+def _assert_safe_target(root: Path, target: Path, *, include_environment: bool) -> None:
+    repository = root.resolve(strict=True)
+    absolute_target = target.absolute()
+    try:
+        relative = absolute_target.relative_to(repository)
+    except ValueError as exc:
+        raise CleanupError(f"cleanup target is outside repository: {target}") from exc
+    if len(relative.parts) == 1 and relative.name in TOP_LEVEL_ARTIFACTS:
+        return
+    if include_environment and relative == Path(".venv"):
+        return
+    if relative.name == "__pycache__" or relative.name.endswith(".egg-info"):
+        return
+    raise CleanupError(f"cleanup target is not an approved artifact: {target}")
+
+
+def _remove_target(target: Path) -> None:
+    if target.is_symlink() or target.is_file():
+        target.unlink()
+    elif target.is_junction():
+        target.rmdir()
+    elif target.is_dir():
+        shutil.rmtree(target)
+
+
+def clean_repository(
+    root: Path,
+    *,
+    dry_run: bool = False,
+    include_environment: bool = False,
+    executable: Path | None = None,
+) -> CleanupResult:
+    """Remove approved generated artifacts and return the operation result."""
+    repository = root.resolve(strict=True)
+    targets = discover_targets(repository, include_environment=include_environment)
+    environment = repository / ".venv"
+    active_executable = (executable or Path(sys.executable)).resolve()
+    if include_environment and environment in targets:
+        try:
+            active_executable.relative_to(environment.resolve())
+        except ValueError:
+            pass
+        else:
+            raise CleanupError(
+                "refusing to remove the active Python environment; "
+                "run this script with a system Python interpreter"
+            )
+
+    for target in targets:
+        _assert_safe_target(repository, target, include_environment=include_environment)
+    if dry_run:
+        return CleanupResult(planned=targets, removed=())
+
+    removed: list[Path] = []
+    for target in targets:
+        try:
+            _remove_target(target)
+        except OSError as exc:
+            raise CleanupError(f"failed to remove {target}: {exc}") from exc
+        removed.append(target)
+    return CleanupResult(planned=targets, removed=tuple(removed))
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="Remove reproducible repository caches and build artifacts."
+    )
+    parser.add_argument("--dry-run", action="store_true", help="list targets without deleting")
+    parser.add_argument(
+        "--environment",
+        action="store_true",
+        help="also remove .venv; invoke with a Python interpreter outside .venv",
+    )
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Run repository cleanup from the command line."""
+    args = _parser().parse_args(argv)
+    repository = Path(__file__).resolve().parents[2]
+    try:
+        result = clean_repository(
+            repository,
+            dry_run=args.dry_run,
+            include_environment=args.environment,
+        )
+    except CleanupError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+    if not result.planned:
+        print("No generated artifacts found.")
+        return 0
+    action = "Would remove" if args.dry_run else "Removed"
+    for target in result.planned:
+        print(f"{action}: {target.relative_to(repository)}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

controlled_text_transfer/cli.py

@@ -0,0 +1,221 @@
+"""Command-line interface for Controlled Text Transfer workflows."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import logging
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Optional
+
+from .core import Policy, TransferError, diff, preflight, prepare, restore, verify
+from .signing import ManifestSigner
+
+
+def _add_policy_option(parser: argparse.ArgumentParser) -> None:
+    """Add source-policy selection to a policy-aware command."""
+    parser.add_argument(
+        "--policy", type=Path, help="load compatibility and content rules from YAML"
+    )
+
+
+def _add_log_option(parser: argparse.ArgumentParser) -> None:
+    """Add structured audit logging to a command that emits audit events."""
+    parser.add_argument(
+        "--log-json", action="store_true", help="write one JSON audit event to stderr"
+    )
+
+
+class JsonFormatter(logging.Formatter):
+    """Format supported audit fields as JSON."""
+
+    def format(self, record: logging.LogRecord) -> str:
+        """Return one JSON object for a log record."""
+        return json.dumps(
+            {
+                "timestamp": datetime.now(UTC).isoformat(),
+                "level": record.levelname,
+                "event": record.getMessage(),
+                **{
+                    k: v for k, v in record.__dict__.items() if k in {"files", "skipped", "dry_run"}
+                },
+            }
+        )
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="ctt", description="Prepare, verify, and restore text-only transfer packages."
+    )
+    parser.set_defaults(policy=None, log_json=False)
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    prepare_parser = commands.add_parser(
+        "prepare", help="create and self-verify a transfer package"
+    )
+    _add_policy_option(prepare_parser)
+    _add_log_option(prepare_parser)
+    prepare_parser.add_argument("source", type=Path, help="directory containing source text files")
+    prepare_parser.add_argument("transfer", type=Path, help="new package path")
+    prepare_parser.add_argument(
+        "--dry-run", action="store_true", help="validate without writing a package"
+    )
+    prepare_parser.add_argument(
+        "--strict", action="store_true", help="fail if any file is rejected"
+    )
+    prepare_parser.add_argument(
+        "--json-report", type=Path, help="write the preflight report to a file"
+    )
+    prepare_parser.add_argument(
+        "--sign", action="store_true", help="sign with a trusted injected signer"
+    )
+    prepare_parser.add_argument(
+        "--key-label",
+        default="external-managed-key",
+        help="record a non-secret signer label in the manifest",
+    )
+
+    preflight_parser = commands.add_parser(
+        "preflight", help="evaluate source files without packaging"
+    )
+    _add_policy_option(preflight_parser)
+    preflight_parser.add_argument("source", type=Path, help="directory to evaluate")
+    preflight_parser.add_argument(
+        "--json", action="store_true", help="write the full report as JSON"
+    )
+
+    verify_parser = commands.add_parser("verify", help="check package integrity and authenticity")
+    _add_log_option(verify_parser)
+    verify_parser.add_argument("transfer", type=Path, help="package directory or archive")
+    verify_parser.add_argument(
+        "--require-signature", action="store_true", help="reject packages without a signature"
+    )
+    verify_parser.add_argument(
+        "--allow-unverified-signature",
+        action="store_true",
+        help="permit a signed package without an available trusted verifier",
+    )
+
+    restore_parser = commands.add_parser("restore", help="verify and reconstruct original files")
+    _add_log_option(restore_parser)
+    restore_parser.add_argument("transfer", type=Path, help="package directory or archive")
+    restore_parser.add_argument("destination", type=Path, help="new directory for restored files")
+    restore_parser.add_argument(
+        "--dry-run", action="store_true", help="verify without writing restored files"
+    )
+    restore_parser.add_argument(
+        "--require-signature", action="store_true", help="reject packages without a signature"
+    )
+    restore_parser.add_argument(
+        "--allow-unverified-signature",
+        action="store_true",
+        help="permit a signed package without an available trusted verifier",
+    )
+
+    diff_parser = commands.add_parser("diff", help="compare a package with a source directory")
+    _add_policy_option(diff_parser)
+    diff_parser.add_argument("transfer", type=Path, help="package directory or archive")
+    diff_parser.add_argument("source", type=Path, help="current source directory")
+    diff_parser.add_argument("--json", action="store_true", help="write comparison results as JSON")
+    diff_parser.add_argument(
+        "--require-signature", action="store_true", help="reject packages without a signature"
+    )
+    diff_parser.add_argument(
+        "--allow-unverified-signature",
+        action="store_true",
+        help="permit a signed package without an available trusted verifier",
+    )
+    return parser
+
+
+def main(
+    argv: list[str] | None = None,
+    *,
+    signer: Optional[ManifestSigner] = None,
+) -> int:
+    """Run the CLI and return a process-compatible status code.
+
+    Trusted hosts may inject a signer; transferred data never selects commands.
+    """
+    args = _parser().parse_args(argv)
+    log = logging.getLogger("controlled_text_transfer")
+    log.setLevel(logging.INFO)
+    h = logging.StreamHandler()
+    h.setFormatter(
+        JsonFormatter() if args.log_json else logging.Formatter("%(levelname)s: %(message)s")
+    )
+    log.handlers[:] = [h]
+    try:
+        policy = Policy.from_file(args.policy)
+        if args.command == "preflight":
+            report = preflight(args.source, policy)
+            output = json.dumps(report.to_dict(), indent=2)
+            if args.json:
+                print(output)
+            else:
+                print(
+                    f"accepted: {report.accepted_count}\n"
+                    f"rejected: {report.rejected_count}\n"
+                    f"total bytes: {report.total_bytes}"
+                )
+            return 0
+        if args.command == "prepare":
+            report = preflight(args.source, policy)
+            if args.json_report:
+                args.json_report.write_text(
+                    json.dumps(report.to_dict(), indent=2) + "\n",
+                    encoding="utf-8",
+                )
+            if args.sign and signer is None:
+                raise TransferError("trusted signer is required")
+            m = prepare(
+                args.source,
+                args.transfer,
+                policy,
+                dry_run=args.dry_run,
+                strict=args.strict,
+                signer=signer if args.sign else None,
+                key_label=args.key_label,
+                logger=log,
+            )
+        elif args.command == "verify":
+            m = verify(
+                args.transfer,
+                signer=signer,
+                require_signature=args.require_signature,
+                allow_unverified_signature=args.allow_unverified_signature,
+                logger=log,
+            )
+        elif args.command == "diff":
+            result = diff(
+                args.transfer,
+                args.source,
+                policy,
+                signer=signer,
+                require_signature=args.require_signature,
+                allow_unverified_signature=args.allow_unverified_signature,
+            )
+            if args.json:
+                print(json.dumps(result, indent=2))
+            else:
+                for category, paths in result.items():
+                    print(f"{category}: {len(paths)}")
+                    for path in paths:
+                        print(f"  {path}")
+            return 0
+        else:
+            m = restore(
+                args.transfer,
+                args.destination,
+                dry_run=args.dry_run,
+                signer=signer,
+                require_signature=args.require_signature,
+                allow_unverified_signature=args.allow_unverified_signature,
+                logger=log,
+            )
+        print(json.dumps({"files": len(m.files), "skipped": m.skipped}, indent=2))
+        return 0
+    except (TransferError, OSError, ValueError) as exc:
+        log.error(str(exc))
+        return 2