sci-protocol 0.2.0__py3-none-any.whl

pysci/_cli/commands/protocol.py

@@ -0,0 +1,72 @@
+"""``sci spec``: print the SCI protocol specification bundled with this CLI."""
+
+from __future__ import annotations
+
+import argparse
+
+from pysci import PROTOCOL_VERSION
+from pysci.specification import (
+    PROTOCOL_SPEC_SHA256,
+    protocol_specification,
+    specification_section,
+    specification_sections,
+)
+
+from ..context import Context
+from ..errors import CliError
+from ..output import Result
+from ..spec import Command, arg
+
+
+def run(args: argparse.Namespace, ctx: Context) -> Result:
+    if args.list and args.section:
+        raise CliError("conflicting_options", "--list and --section cannot be combined")
+    result = Result("spec")
+    result.data = {"protocol": PROTOCOL_VERSION, "sha256": PROTOCOL_SPEC_SHA256}
+    if args.list:
+        sections = specification_sections()
+        result.data["sections"] = [{"number": n, "title": t} for n, t in sections]
+        for number, title in sections:
+            result.say(f"{'  ' * number.count('.')}{number}  {title}")
+        return result
+    if args.section:
+        text = specification_section(args.section.rstrip("."))
+        if text is None:
+            raise CliError(
+                "unknown_section",
+                f"the protocol has no section {args.section}; run `sci spec --list`",
+                observed=args.section,
+            )
+        result.data["section"] = args.section.rstrip(".")
+    else:
+        text = protocol_specification()
+    result.data["text"] = text
+    result.lines.extend(text.rstrip("\n").split("\n"))
+    return result
+
+
+COMMAND = Command(
+    name="spec",
+    usage_hint="spec [--section N | --list] [--json]",
+    summary="Print the SCI protocol specification.",
+    description="""
+Prints the complete SCI protocol specification (Markdown) that this CLI and
+its pysci library implement. The text is bundled with the installed package
+and checked against the hash pinned by the conformance corpus, so it matches
+the installed version exactly and needs no network access.
+
+Use --section to print one numbered section with its subsections, for
+example `--section 4` for publication metadata or `--section 4.4` for
+citations. --list prints the section numbers and titles.
+""",
+    args=(
+        arg("--section", metavar="N", help="print only section N, e.g. 4 or 4.4"),
+        arg("--list", action="store_true", help="list numbered sections and their titles"),
+    ),
+    outputs="Specification Markdown, one section, or the section list; --json adds its SHA-256.",
+    files="None.",
+    network="None.",
+    exit_codes={2: "unknown section, or --list combined with --section"},
+    examples=("sci spec --section 4", "sci spec --list", "sci spec > sci-protocol.md"),
+    run=run,
+)

pysci/_cli/commands/publish.py

@@ -0,0 +1,282 @@
+"""``sci publish``: store signed bundles in local folders or external archives."""
+
+from __future__ import annotations
+
+import argparse
+import shutil
+import tempfile
+from pathlib import Path
+from typing import Any
+
+from ..clients.credentials import github_token, huggingface_token
+from ..clients.github import GitHubArchive
+from ..clients.hosting import Prepared
+from ..clients.huggingface import HuggingFaceArchive
+from ..context import Context
+from ..destinations import Destination, resolve_destinations
+from ..errors import CliError, ErrorRecord, Exit, combine_exits
+from ..output import Result
+from ..spec import Command, arg
+from ..storage.files import InputChanged, sha256_file, store_no_clobber
+from ..storage.inputs import (
+    SignedInput,
+    collect_signed_inputs,
+    invalid_exit,
+    reader_files,
+    write_zip,
+)
+from ..storage.local_publish import publish_to_folder, remember_folder
+
+
+def _snapshot(item: SignedInput, workdir: Path) -> SignedInput:
+    """Copy a verified input's canonical ZIP (and sidecar) into the work directory."""
+    target = workdir / f"{item.digest}.zip"
+    try:
+        store_no_clobber(target, lambda handle: write_zip(item, handle), item.zip_sha256)
+    except InputChanged:
+        raise CliError(
+            "input_changed",
+            f"{item.path} changed after verification",
+            Exit.INCOMPLETE,
+            retryable=True,
+        ) from None
+    sidecar = item.sidecar
+    if sidecar is not None:
+        shutil.copyfile(sidecar, workdir / f"{item.digest}.tsr")
+    return SignedInput(target, "zip", item.result)
+
+
+def _plan_folder(item: SignedInput, destination: Destination) -> str:
+    assert destination.path is not None
+    target = destination.path / f"{item.digest}.zip"
+    if not target.exists():
+        return "write"
+    return "keep identical" if sha256_file(target) == item.zip_sha256 else "conflict"
+
+
+def run(args: argparse.Namespace, ctx: Context) -> Result:
+    destinations = resolve_destinations(args.to or [], list(ctx.config.folders), ctx.cwd)
+    paths = [ctx.resolve(p) for p in args.paths]
+    inputs, invalid, duplicates = collect_signed_inputs(paths)
+    result = Result("publish")
+    result.data = {
+        "destinations": [d.display for d in destinations],
+        "publications": [i.publication_id for i in inputs],
+        "invalid_candidates": invalid,
+        "duplicates": duplicates,
+        "results": [],
+    }
+    for candidate in invalid:
+        first = candidate["issues"][0]["message"] if candidate["issues"] else ""
+        result.say(f"not published (invalid): {candidate['path']} - {first}")
+    if not inputs:
+        result.exit_code = invalid_exit(invalid) if invalid else Exit.USAGE
+        result.errors.append(ErrorRecord("no_valid_inputs", "no valid signed publications found"))
+        return result
+
+    if args.dry_run:
+        plan: list[dict[str, Any]] = []
+        for destination in destinations:
+            for item in inputs:
+                action = (
+                    _plan_folder(item, destination)
+                    if destination.kind == "folder"
+                    else "upload reader files and bundle (repository must be public"
+                    + ("; created if missing)" if args.create else ")")
+                )
+                plan.append(
+                    {
+                        "destination": destination.display,
+                        "publication_id": item.publication_id,
+                        "action": action,
+                    }
+                )
+                result.say(f"{destination.display}: {item.publication_id}: {action}")
+        result.data["plan"] = plan
+        result.data["dry_run"] = True
+        if invalid:
+            result.exit_code = Exit.INCOMPLETE
+            result.partial = True
+        return result
+
+    exits: list[int] = [invalid_exit(invalid)] if invalid else []
+    workdir = Path(tempfile.mkdtemp(prefix="sci-publish-"))
+    try:
+        snapshots = [_snapshot(item, workdir) for item in inputs]
+        prepared: list[Prepared] | None = None
+        for destination in destinations:
+            if destination.kind == "folder":
+                assert destination.path is not None
+                stored_any = False
+                for item in snapshots:
+                    report, code = publish_to_folder(item, destination.path)
+                    exits.append(code)
+                    result.data["results"].append(report)
+                    stored_any = stored_any or code == Exit.OK
+                    if code == Exit.OK:
+                        result.say(
+                            f"{destination.display}: {item.publication_id}: {report['bundle']}"
+                        )
+                    else:
+                        error = report["error"]
+                        result.errors.append(
+                            ErrorRecord(error["code"], error["message"], error["retryable"])
+                        )
+                        result.say(f"{destination.display}: {item.publication_id}: failed")
+                if stored_any and remember_folder(ctx.config, destination.path):
+                    ctx.save_config()
+                continue
+            if prepared is None:
+                prepared = []
+                for item in snapshots:
+                    reader = reader_files(item)
+                    sidecar = item.sidecar
+                    if sidecar is not None:
+                        reader["manifest.json.sig.tsr"] = sidecar.read_bytes()
+                    prepared.append(Prepared(item, item.path, reader))
+            _hosted(ctx, args, destination, prepared, result, exits)
+    finally:
+        shutil.rmtree(workdir, ignore_errors=True)
+    result.exit_code = combine_exits(exits)
+    result.partial = result.exit_code == Exit.INCOMPLETE and Exit.OK in exits
+    return result
+
+
+def _hosted(
+    ctx: Context,
+    args: argparse.Namespace,
+    destination: Destination,
+    prepared: list[Prepared],
+    result: Result,
+    exits: list[int],
+) -> None:
+    assert destination.owner is not None
+    assert destination.repo is not None
+    try:
+        archive: GitHubArchive | HuggingFaceArchive
+        if destination.kind == "github":
+            token = github_token(ctx.env, ctx.runner)
+            archive = GitHubArchive(
+                ctx.http,
+                destination.owner,
+                destination.repo,
+                token,
+                notice=lambda message: print(message, file=ctx.stderr, flush=True),
+            )
+        else:
+            token = huggingface_token(ctx.env)
+            archive = HuggingFaceArchive(ctx.http, destination.owner, destination.repo, token)
+        summary, reports = archive.publish(prepared, create=args.create, timeout=args.timeout)
+    except CliError as exc:
+        exits.append(exc.exit_code)
+        result.errors.append(exc.records[0])
+        for pub in prepared:
+            result.data["results"].append(
+                {
+                    "publication_id": pub.item.publication_id,
+                    "destination": destination.display,
+                    "kind": destination.kind,
+                    "status": "failed",
+                    "error": exc.records[0].to_json(),
+                }
+            )
+        result.say(f"{destination.display}: failed - {exc.records[0].message}")
+        return
+    availability = summary["availability"]
+    for report in reports:
+        entry = report.to_json()
+        entry.update({"destination": destination.display, "kind": destination.kind})
+        result.data["results"].append(entry)
+        exits.append(report.exit_code if report.status != "hosted" else Exit.OK)
+        if report.error is not None:
+            result.errors.append(report.error)
+        result.say(f"{destination.display}: {report.publication_id}: {report.status}")
+    result.data.setdefault("archives", []).append({"destination": destination.display, **summary})
+    result.say(f"  descriptor: {summary['descriptor_url']}")
+    if not availability["confirmed"]:
+        exits.append(Exit.INCOMPLETE)
+        result.errors.append(
+            ErrorRecord(
+                "availability_unconfirmed",
+                f"{destination.display}: public availability of reader files is not yet confirmed "
+                "(CDN caches may lag); retry later",
+                True,
+            )
+        )
+    elif not availability["reader_cors"]:
+        result.warn(f"{destination.display}: reader files lack CORS headers for browser readers")
+    bundle_cors = [c for c in availability["checks"] if c["label"] == "bundle"]
+    if bundle_cors and not all(c.get("cors") for c in bundle_cors):
+        result.warn(
+            f"{destination.display}: bundle downloads lack CORS headers; browser readers use "
+            "entry_url instead"
+        )
+
+
+COMMAND = Command(
+    name="publish",
+    usage_hint=(
+        "publish PATH ... --to DESTINATION [--to DESTINATION ...] [--create] [--dry-run] [--json]"
+    ),
+    summary="Store signed bundles in local folders or external archives.",
+    description="""
+PATH is a signed ZIP, a signed directory, or a folder of *.zip bundles. Each
+candidate is verified completely (SCI protocol §6.4) and deduplicated by ID;
+invalid candidates are reported and not published. Publishing never
+contacts an indexer (see `sci submit`).
+
+Destinations (repeat --to; equivalent addresses are merged):
+  DIR                                   store <digest>.zip (+ <digest>.tsr)
+  @local                                all known folders
+  https://github.com/OWNER/REPO         reader files on main + release assets
+  https://huggingface.co/datasets/OWNER/REPO   reader files + ZIPs (Git LFS)
+SSH forms (git@github.com:OWNER/REPO.git, git@hf.co:datasets/OWNER/REPO) and
+ssh:// URLs are accepted; file or branch URLs, queries, and fragments are not.
+
+Local folders: <digest>.zip is written atomically; identical files are kept and
+conflicting bytes rejected. Hosted archives: the repository must be public
+(or created public with --create; visibility is never changed). Reader files
+(manifest, signature, sci.json, README, LICENSE, display files, timestamp
+sidecar) go to sci/publications/<id2>/<id>/ on main; sci/archive.json and a
+sorted sci/publications.txt are maintained in batched commits without
+force-pushing. GitHub stores <id>.zip as an asset of the shared release
+sci-<id2>, named for the first two ID characters (never marked latest);
+Hugging Face stores
+bundles/<id2>/<id>.zip via LFS. Retries compare remote digests and reuse
+matching content. Credentials: `gh auth login` or GH_TOKEN/GITHUB_TOKEN;
+`hf auth login` or HF_TOKEN.
+""",
+    args=(
+        arg(
+            "paths",
+            metavar="PATH",
+            nargs="+",
+            help="signed ZIP, signed directory, or campaign folder",
+        ),
+        arg(
+            "--to",
+            metavar="DESTINATION",
+            action="append",
+            help="destination (repeatable, required)",
+        ),
+        arg("--create", action="store_true", help="create a missing hosted repository as public"),
+        arg("--dry-run", action="store_true", help="list the plan without writes or uploads"),
+    ),
+    outputs="""One result per publication and destination (stored/hosted/failed, reused or
+uploaded files), hosted descriptor URLs, and public-availability and CORS
+checks.""",
+    files="""Writes <digest>.zip and <digest>.tsr in folder destinations and remembers those
+folders in config.json. Hosted destinations change only their repositories.""",
+    network="None for folders. GitHub REST API / Hugging Face Hub API uploads for hosted "
+    "destinations, then unauthenticated availability checks.",
+    exit_codes={
+        3: "an input failed verification, or a destination holds conflicting bytes",
+        5: "an upload or availability check did not complete, or results are mixed",
+        6: "the provider refused the operation (permissions)",
+    },
+    examples=(
+        "sci publish ./campaign --to ./mirror --to https://github.com/lab/research --create",
+    ),
+    run=run,
+    timeout=True,
+)

pysci/_cli/commands/pull.py

@@ -0,0 +1,337 @@
+"""``sci pull``: save a complete verified publication."""
+
+from __future__ import annotations
+
+import argparse
+import contextlib
+import os
+import shutil
+import tempfile
+from pathlib import Path
+from typing import Any
+
+from pysci.bundle import VerificationResult, extract_verified, verify_directory
+from pysci.der import frame_values
+from pysci.errors import Outcome
+from pysci.keys import PublicKey
+from pysci.manifest import MANIFEST_PATH, SIGNATURE_PATH, TIMESTAMP_SIDECAR_PATH
+from pysci.timestamps import ProofResult
+
+from ..checks import baseline_check, bundle_check, checks, describe_checks, timestamps_check
+from ..clients.archive import ArchiveSource, SourceFailure, failure_exit
+from ..clients.index import IndexClient
+from ..clients.tsa import merge_proofs, read_sidecar, verify_sidecar_bytes
+from ..context import Context
+from ..errors import CliError, ErrorRecord, Exit, exit_for_outcome
+from ..output import Result
+from ..retrieval import resolve_sources
+from ..spec import Command, arg
+from ..storage.files import atomic_write_bytes, directory_is_empty
+from ..storage.inputs import SignedInput, signature_of
+from ..storage.keys import load_public_key_file
+from ..storage.local_publish import publish_to_folder, remember_folder
+from .common import parse_id, trust
+
+
+def _existing(output: Path, digest: str, zip_mode: bool) -> VerificationResult | None:
+    """A complete verified copy already at the destination, else None; conflicts raise."""
+    if zip_mode:
+        target = output / f"{digest}.zip"
+        if not target.exists():
+            return None
+        from pysci.bundle import verify_zip
+
+        result = verify_zip(target, expected_id=digest)
+        if result.ok:
+            return result
+        raise CliError(
+            "destination_conflict",
+            f"{target} exists but is not a verified copy of sha256:{digest}",
+            Exit.INVALID,
+            file=str(target),
+        )
+    if not output.exists():
+        return None
+    if not output.is_dir():
+        raise CliError("destination_conflict", f"{output} exists and is not a directory")
+    if directory_is_empty(output):
+        return None
+    result = verify_directory(output, expected_id=digest)
+    if result.ok:
+        return result
+    raise CliError(
+        "destination_not_empty",
+        f"{output} is not empty and is not a complete verified copy of sha256:{digest}",
+        Exit.USAGE,
+        file=str(output),
+    )
+
+
+def _retrieve(
+    archive: ArchiveSource, ctx: Context, deadline: Any, workdir: Path
+) -> tuple[str, Path, VerificationResult]:
+    """Retrieve a complete bundle from one archive: complete ZIP, else individual files."""
+    descriptor = archive.descriptor(deadline)
+    if descriptor.bundle_url is not None:
+        got = archive.verify_complete_zip(deadline)
+        if got is not None:
+            path, result = got
+            if not result.ok:
+                record = ErrorRecord(
+                    result.issues[0].code if result.issues else "invalid",
+                    result.issues[0].requirement if result.issues else "bundle failed checks",
+                    result.outcome is Outcome.INCOMPLETE,
+                    extra={"route": "bundle_url"},
+                )
+                raise SourceFailure(record, exit_for_outcome(result.outcome))
+            return "zip", path, result
+    manifest = archive.manifest(deadline)
+    loose = Path(tempfile.mkdtemp(dir=workdir, prefix=".sci-tmp-loose-"))
+    (loose / MANIFEST_PATH).write_bytes(manifest.raw)
+    (loose / SIGNATURE_PATH).write_bytes(archive.signature(deadline))
+    for member in manifest.sorted_paths():
+        data = archive.file(member, deadline)
+        target = loose / member
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_bytes(data)
+    result = verify_directory(loose, expected_id=manifest.digest, compute_zip_sha256=True)
+    if not result.ok:
+        raise SourceFailure(
+            ErrorRecord(
+                "invalid", "assembled bundle failed complete checks", extra={"route": "entry_url"}
+            ),
+            exit_for_outcome(result.outcome),
+        )
+    return "directory", loose, result
+
+
+def _proofs(
+    ctx: Context,
+    archives: list[ArchiveSource],
+    index: IndexClient | None,
+    digest: str,
+    deadline: Any,
+    signature: bytes,
+    warnings: list[str],
+) -> tuple[bytes | None, dict[str, Any]]:
+    combined = b""
+    sources: list[str] = []
+    for archive in archives:
+        data = archive.sidecar(deadline)
+        if data:
+            combined, problems = merge_proofs(combined, data)
+            sources.append(archive.descriptor_url)
+            warnings.extend(f"proofs from {archive.descriptor_url}: {p.message}" for p in problems)
+    if index is not None:
+        try:
+            data = index.timestamps(digest, deadline)
+        except CliError as exc:
+            warnings.append(f"timestamp lookup failed: {exc}")
+            data = None
+        if data:
+            combined, problems = merge_proofs(combined, data)
+            sources.append(f"{index.origin} timestamp lookup")
+            warnings.extend(f"index proofs: {p.message}" for p in problems)
+    if not combined:
+        return None, timestamps_check(
+            None,
+            source=None,
+            online=False,
+            absent_reason="no proofs were retrieved from the sources",
+        )
+    verification = verify_sidecar_bytes(combined, signature, trust(ctx))
+    kept = b"".join(
+        combined[p.offset : p.offset + p.length]
+        for p in verification.proofs
+        if p.result is not ProofResult.INVALID
+    )
+    report = timestamps_check(verification, source=", ".join(sources), online=False)
+    report["kept_proofs"] = len(frame_values(kept).values) if kept else 0
+    return kept or None, report
+
+
+def run(args: argparse.Namespace, ctx: Context) -> Result:
+    digest = parse_id(args.id)
+    expected_key: PublicKey | None = None
+    if args.public_key:
+        expected_key = load_public_key_file(ctx.resolve(args.public_key))
+    zip_mode = bool(args.zip)
+    if zip_mode:
+        output = ctx.resolve(args.output or ".")
+    else:
+        output = ctx.resolve(args.output) if args.output else ctx.cwd / digest
+    result = Result("pull")
+    result.data = {"publication_id": "sha256:" + digest, "output": str(output)}
+    existing = _existing(output, digest, zip_mode)
+    if existing is not None and existing.manifest is not None:
+        if expected_key is not None and existing.manifest.public_key != expected_key:
+            raise CliError(
+                "public_key_mismatch", "signer does not match --public-key", Exit.INVALID
+            )
+        result.data.update(
+            {
+                "status": "already_present",
+                "checks": checks(bundle=bundle_check(existing), baseline=baseline_check(existing)),
+            }
+        )
+        result.say(f"sha256:{digest} is already present and verified at {output}")
+        return result
+
+    deadline = ctx.deadline(args.timeout)
+    sources = resolve_sources(
+        ctx, digest, archives=args.archive, index_url=args.in_, deadline=deadline
+    )
+    parent = output if zip_mode else output.parent
+    parent.mkdir(parents=True, exist_ok=True)
+    workdir = Path(tempfile.mkdtemp(dir=parent, prefix=".sci-tmp-pull-"))
+    archives: list[ArchiveSource] = []
+    try:
+        failures: list[SourceFailure] = []
+        retrieved: tuple[str, Path, VerificationResult] | None = None
+        used: ArchiveSource | None = None
+        for url in sources.descriptors:
+            archive = ArchiveSource(ctx.http, url, digest, workdir)
+            archives.append(archive)
+            try:
+                retrieved = _retrieve(archive, ctx, deadline, workdir)
+                used = archive
+                break
+            except SourceFailure as exc:
+                exc.record.extra["descriptor"] = url
+                failures.append(exc)
+            except CliError as exc:
+                if exc.code == "deadline_exceeded":
+                    raise
+                failures.append(SourceFailure(exc.records[0], exc.exit_code))
+        if retrieved is None or used is None:
+            code = failure_exit(failures)
+            error = CliError(
+                "retrieval_failed",
+                f"no source provided a complete verified copy of sha256:{digest}",
+                code,
+                retryable=code == Exit.INCOMPLETE,
+            )
+            error.records.extend(f.record for f in failures)
+            raise error
+        kind, path, verification = retrieved
+        assert verification.manifest is not None
+        if expected_key is not None and verification.manifest.public_key != expected_key:
+            raise CliError(
+                "public_key_mismatch",
+                "signer does not match --public-key",
+                Exit.INVALID,
+                field="/public_key/x",
+                observed=verification.manifest.public_key.x,
+                requirement=f"x = {expected_key.x}",
+            )
+        item = SignedInput(path, "zip" if kind == "zip" else "directory", verification)
+        proofs, ts_report = _proofs(
+            ctx, archives, sources.index, digest, deadline, signature_of(item), result.warnings
+        )
+        if zip_mode:
+            stored, store_code = publish_to_folder(item, output)
+            result.data["stored"] = stored
+            if store_code != Exit.OK:
+                error = stored["error"]
+                raise CliError(error["code"], error["message"], store_code)
+            if remember_folder(ctx.config, output):
+                ctx.save_config()
+            if proofs:
+                tsr = output / f"{digest}.tsr"
+                merged, _ = merge_proofs(read_sidecar(tsr) or b"", proofs)
+                atomic_write_bytes(tsr, merged)
+                ts_report["written"] = str(tsr)
+            result.say(f"saved {stored['path']} ({stored['bundle']})")
+        else:
+            staging = workdir / "final"
+            if kind == "zip":
+                extracted = extract_verified(path, staging, expected_id=digest)
+                if not extracted.ok:
+                    raise CliError(
+                        "extraction_failed", "bundle changed during extraction", Exit.INCOMPLETE
+                    )
+            else:
+                os.rename(path, staging)
+            if proofs:
+                atomic_write_bytes(staging / TIMESTAMP_SIDECAR_PATH, proofs)
+                ts_report["written"] = str(output / TIMESTAMP_SIDECAR_PATH)
+            if output.exists():
+                output.rmdir()  # empty, checked above
+            os.rename(staging, output)
+            result.say(f"saved sha256:{digest} to {output}")
+        result.data.update(
+            {
+                "status": "retrieved",
+                "source": {"descriptor": used.descriptor_url, "routes": used.routes},
+                "source_failures": [f.record.to_json() for f in failures],
+                "signer": verification.manifest.public_key.to_jwk(),
+                "checks": checks(
+                    bundle=bundle_check(verification),
+                    baseline=baseline_check(verification),
+                    timestamps=ts_report,
+                ),
+            }
+        )
+        result.lines.extend(describe_checks(result.data["checks"]))
+        if failures:
+            result.warn(f"{len(failures)} source(s) failed before {used.descriptor_url} succeeded")
+        return result
+    finally:
+        for archive in archives:
+            archive.close()
+        with contextlib.suppress(OSError):
+            shutil.rmtree(workdir)
+
+
+COMMAND = Command(
+    name="pull",
+    usage_hint=(
+        "pull ID [--output DIR] [--zip] [--in URL | --archive ARCHIVE ...] "
+        "[--public-key PATH] [--json]"
+    ),
+    summary="Save a complete verified publication.",
+    description="""
+Finds sources through the configured index or --in URL (SCI protocol
+§8.1.1), or uses repeated --archive descriptor URLs or GitHub/Hugging Face
+repository addresses without an index. Each
+source is tried in turn against the same expected ID. The complete ZIP
+(bundle_url) is preferred; otherwise files are fetched individually
+(entry_url, blob_url). Downloads are verified completely (§6.4) in a
+temporary location before extraction. No catalog admission is required.
+
+The default output is ./<digest>/. An existing complete verified copy is
+kept; other nonempty destinations are rejected. --zip stores <digest>.zip in
+--output DIR (default: current folder) under the local publishing rules.
+Timestamp proofs are retrieved from archive entry_url and the index's
+timestamp lookup and reported separately; proof retrieval failure does not
+fail the download.
+""",
+    args=(
+        arg("id", metavar="ID", help="publication ID: sha256:<digest> or sci:sha256:<digest>"),
+        arg("--output", metavar="DIR", help="destination directory (default: ./<digest>/)"),
+        arg(
+            "--zip", action="store_true", help="store <digest>.zip in --output DIR instead of files"
+        ),
+        arg("--in", dest="in_", metavar="URL", help="index origin (default: configured index)"),
+        arg(
+            "--archive",
+            metavar="ARCHIVE",
+            action="append",
+            help="descriptor URL or GitHub/Hugging Face repository address (repeatable)",
+        ),
+        arg("--public-key", metavar="PATH", help="require the signer to match this public PEM key"),
+    ),
+    outputs="Destination, source used, source failures, and the checks object.",
+    files="""Creates the destination directory (or <digest>.zip and <digest>.tsr with --zip);
+temporary files use .sci-tmp- names and are removed.""",
+    network="Index lookup (unless --archive), archive descriptor and file or bundle GETs, "
+    "and timestamp lookups.",
+    exit_codes={
+        3: "every source served content failing verification, or the signer does not match",
+        4: "unsupported descriptor or bundle schema",
+        5: "no known sources (index 404 or empty list), sources unreachable, or deadline",
+    },
+    examples=("sci pull sha256:<digest> --in https://sciscape.io --output ./paper",),
+    run=run,
+    timeout=True,
+)