gen3-dataops-toolkit 2.2.0__tar.gz → 3.0.0__tar.gz

{gen3_dataops_toolkit-2.2.0 → gen3_dataops_toolkit-3.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gen3-dataops-toolkit
-Version: 2.2.0
+Version: 3.0.0
 Summary: Gen3 DataOps toolkit (g3dt): operate SSM-published Gen3 data pipeline environments
 License: Apache-2.0
 Author: JoshuaHarris391
@@ -19,6 +19,7 @@ Requires-Dist: gen3 (>=4.27.4,<5.0.0)
 Requires-Dist: gen3-metadata (>=1.4.0,<2.0.0)
 Requires-Dist: gen3_validator (>=2.0.0,<3.0.0)
 Requires-Dist: numpy (<2.0.0)
+Requires-Dist: openpyxl (>=3.1.0)
 Requires-Dist: pyarrow (>=14.0.0,<19.0.0)
 Requires-Dist: pyjwt (>=2.10.1,<3.0.0)
 Requires-Dist: python-dotenv
@@ -112,9 +113,11 @@ structurally impossible.
 
 **Only the dbt template's `ci` target is prefixed.** `g3dt config dbt-env`
 emits, alongside the real names, the CI-isolation variants the template's
-`ci` target consumes: `G3DT_DB_RAW_SILVER_CI` / `G3DT_DB_RAW_GOLD_CI`
+`ci` target consumes: `G3DT_DB_SILVER_CI` / `G3DT_DB_GOLD_CI`
 (`ci_` + the real database name) and `G3DT_S3_SILVER_DATA_DIR_CI` /
-`G3DT_S3_GOLD_DATA_DIR_CI` (`dbt_ci/` under the same buckets). Commit-
+`G3DT_S3_GOLD_DATA_DIR_CI` (`dbt_ci/` under the same buckets). Toolkit
+releases >= 3 read the raw-free medallion SSM keys and therefore require a
+pipeline deployment >= v2.0.0, which publishes them. Commit-
 triggered CI builds land there; every other target (default, local) and the
 release build keep the real, unprefixed names — so CI can never advance the
 warehouse's Iceberg snapshots that releases pin. The library enforces the
@@ -175,6 +178,46 @@ Synthetic data is only schema-valid against the dictionary that generated it, so
 refuses a batch that doesn't match the version being uploaded (override with
 `--allow-version-mismatch`).
 
+## Verifying download access (check-download)
+
+Registration alone does not prove a file can be downloaded. Two failure modes
+are invisible until a user clicks the file in the portal: an Indexd record
+with no storage URL (nothing to download, ever), and a record Fence refuses
+to sign a URL for. `g3dt indexd check-download` walks the exact chain the
+portal hits — Indexd record → storage URL → DRS object → access methods →
+Fence signed URL — and reports PASS/FAIL per object, exiting non-zero if any
+object fails so it can gate a deployment step.
+
+Run it before a release, and after registering new files. The env selects the
+API key secret and the key's JWT selects the commons, so there is no URL to
+pass (and none to get wrong).
+
+```bash
+g3dt indexd check-download --env staging                    # sample the 25 newest
+g3dt indexd check-download --env staging --limit 50
+g3dt indexd check-download --env prod PREFIX/<uuid-1> PREFIX/<uuid-2>
+```
+
+With no GUIDs, the newest objects for the env's commons are sampled from the
+indexd registry (latest revision per baseid). The registry may live in a
+different AWS account than the commons being checked; if the env's AWS
+profile cannot reach it, pass GUIDs explicitly.
+
+Reading a failure:
+
+| Symptom | Meaning |
+|---|---|
+| `Indexd status: 404` | the object is not registered — a registration problem, not a download one |
+| `urls: []` / no access methods | registered but with no storage location; it can never download |
+| `Access endpoint … 401` | authorization: the API key's user lacks `read-storage` on the record's `authz` resource — an authz gap, not a broken key |
+| `Access endpoint … 500` | Fence has the permission but failed to sign — a service-side fault |
+
+On a 401, compare what the record requires
+(`https://commons.example.org/index/<did>`, the `authz` field) with what the
+key's user actually holds (`https://commons.example.org/user/user`):
+downloads require `read-storage` on the record's authz resource, which a user
+holding only `create` does not have.
+
 ## Development
 
 ```bash

{gen3_dataops_toolkit-2.2.0 → gen3_dataops_toolkit-3.0.0}/README.md

@@ -79,9 +79,11 @@ structurally impossible.
 
 **Only the dbt template's `ci` target is prefixed.** `g3dt config dbt-env`
 emits, alongside the real names, the CI-isolation variants the template's
-`ci` target consumes: `G3DT_DB_RAW_SILVER_CI` / `G3DT_DB_RAW_GOLD_CI`
+`ci` target consumes: `G3DT_DB_SILVER_CI` / `G3DT_DB_GOLD_CI`
 (`ci_` + the real database name) and `G3DT_S3_SILVER_DATA_DIR_CI` /
-`G3DT_S3_GOLD_DATA_DIR_CI` (`dbt_ci/` under the same buckets). Commit-
+`G3DT_S3_GOLD_DATA_DIR_CI` (`dbt_ci/` under the same buckets). Toolkit
+releases >= 3 read the raw-free medallion SSM keys and therefore require a
+pipeline deployment >= v2.0.0, which publishes them. Commit-
 triggered CI builds land there; every other target (default, local) and the
 release build keep the real, unprefixed names — so CI can never advance the
 warehouse's Iceberg snapshots that releases pin. The library enforces the
@@ -142,6 +144,46 @@ Synthetic data is only schema-valid against the dictionary that generated it, so
 refuses a batch that doesn't match the version being uploaded (override with
 `--allow-version-mismatch`).
 
+## Verifying download access (check-download)
+
+Registration alone does not prove a file can be downloaded. Two failure modes
+are invisible until a user clicks the file in the portal: an Indexd record
+with no storage URL (nothing to download, ever), and a record Fence refuses
+to sign a URL for. `g3dt indexd check-download` walks the exact chain the
+portal hits — Indexd record → storage URL → DRS object → access methods →
+Fence signed URL — and reports PASS/FAIL per object, exiting non-zero if any
+object fails so it can gate a deployment step.
+
+Run it before a release, and after registering new files. The env selects the
+API key secret and the key's JWT selects the commons, so there is no URL to
+pass (and none to get wrong).
+
+```bash
+g3dt indexd check-download --env staging                    # sample the 25 newest
+g3dt indexd check-download --env staging --limit 50
+g3dt indexd check-download --env prod PREFIX/<uuid-1> PREFIX/<uuid-2>
+```
+
+With no GUIDs, the newest objects for the env's commons are sampled from the
+indexd registry (latest revision per baseid). The registry may live in a
+different AWS account than the commons being checked; if the env's AWS
+profile cannot reach it, pass GUIDs explicitly.
+
+Reading a failure:
+
+| Symptom | Meaning |
+|---|---|
+| `Indexd status: 404` | the object is not registered — a registration problem, not a download one |
+| `urls: []` / no access methods | registered but with no storage location; it can never download |
+| `Access endpoint … 401` | authorization: the API key's user lacks `read-storage` on the record's `authz` resource — an authz gap, not a broken key |
+| `Access endpoint … 500` | Fence has the permission but failed to sign — a service-side fault |
+
+On a 401, compare what the record requires
+(`https://commons.example.org/index/<did>`, the `authz` field) with what the
+key's user actually holds (`https://commons.example.org/user/user`):
+downloads require `read-storage` on the record's authz resource, which a user
+holding only `create` does not have.
+
 ## Development
 
 ```bash

{gen3_dataops_toolkit-2.2.0 → gen3_dataops_toolkit-3.0.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "gen3-dataops-toolkit"
-version = "2.2.0"
+version = "3.0.0"
 description = "Gen3 DataOps toolkit (g3dt): operate SSM-published Gen3 data pipeline environments"
 authors = ["JoshuaHarris391 <harjo391@gmail.com>"]
 readme = "README.md"
@@ -28,6 +28,7 @@ awswrangler = ">=3.14.0,<4.0.0"
 pyarrow = ">=14.0.0,<19.0.0"
 gen3-metadata = ">=1.4.0,<2.0.0"
 typer = ">=0.12"
+openpyxl = ">=3.1.0"
 
 [tool.poetry.scripts]
 g3dt = "g3dt.cli.main:main"

{gen3_dataops_toolkit-2.2.0 → gen3_dataops_toolkit-3.0.0}/src/g3dt/cli/_internal/safety.py

@@ -33,18 +33,6 @@ def require_test_env(env: str) -> None:
         raise typer.Exit(2)
 
 
-def abort_if_prod(env: str) -> None:
-    """Hard abort for bulk operations that must never touch production."""
-    if is_prod(env):
-        typer.secho(
-            f"Refusing bulk operation against a production environment "
-            f"('{env}').",
-            fg=typer.colors.RED,
-            err=True,
-        )
-        raise typer.Exit(2)
-
-
 def confirm_destructive(action: str, target: str, env: str, assume_yes: bool) -> None:
     """Gate a destructive operation with an appropriate confirmation.
 

{gen3_dataops_toolkit-2.2.0 → gen3_dataops_toolkit-3.0.0}/src/g3dt/cli/config_cmds.py

@@ -25,6 +25,27 @@ app = typer.Typer(
 )
 
 
+def _req_key(rc, key: str) -> str:
+    """Return the SSM leaf ``key`` from ``rc``, failing loudly if absent.
+
+    The medallion names (``buckets/silver|gold``, ``glue/db/bronze|silver|gold``)
+    are published under these raw-free keys by pipeline deployments >= v2.0.0.
+    Before this guard, a missing key propagated as ``None``: dbt-env silently
+    dropped the G3DT_DB_* vars and emitted ``s3://None/dbt/`` data dirs, and
+    the release search silently fell back to an account-wide catalog walk.
+    """
+    value = rc.get(key)
+    if value is None:
+        raise config.ConfigError(
+            f"SSM parameter /{rc.project}/{rc.env}/{key} is missing. "
+            f"gen3-dataops-toolkit >= 3 reads the raw-free medallion keys "
+            f"published by gen3-aws-data-pipeline >= v2.0.0; a pipeline "
+            f"deployment older than v2.0.0 still publishes raw-prefixed keys. "
+            f"Upgrade the pipeline deployment (or pin gen3-dataops-toolkit<3)."
+        )
+    return value
+
+
 @app.command()
 def envs() -> None:
     """List the environments with a deployed SSM tree for this project."""
@@ -208,28 +229,31 @@ def dbt_env(
     profile = None if env.endswith("_ec2") else config.aws_profile_for(base, marker)
     try:
         rc = resolver.resolve(project, base, profile=profile)
+        silver_db = _req_key(rc, "glue/db/silver")
+        gold_db = _req_key(rc, "glue/db/gold")
+        silver_bucket = _req_key(rc, "buckets/silver")
+        gold_bucket = _req_key(rc, "buckets/gold")
+        bronze_db = _req_key(rc, "glue/db/bronze")
     except config.ConfigError as exc:
         typer.secho(str(exc), fg=typer.colors.RED, err=True)
         raise typer.Exit(1)
 
-    raw_silver_db = rc.get("glue/db/rawSilver")
-    raw_gold_db = rc.get("glue/db/rawGold")
     values = {
         "G3DT_REGION": rc.region,
         "G3DT_ATHENA_WORKGROUP": rc.athena_workgroup,
         "G3DT_ATHENA_OUTPUT": rc.athena_output_location,
-        "G3DT_DB_RAW_BRONZE": rc.get("glue/db/rawBronze"),
-        "G3DT_DB_RAW_SILVER": raw_silver_db,
-        "G3DT_DB_RAW_GOLD": raw_gold_db,
-        "G3DT_S3_SILVER_DATA_DIR": f"s3://{rc.get('buckets/rawSilver')}/dbt/",
-        "G3DT_S3_GOLD_DATA_DIR": f"s3://{rc.get('buckets/rawGold')}/dbt/",
+        "G3DT_DB_BRONZE": bronze_db,
+        "G3DT_DB_SILVER": silver_db,
+        "G3DT_DB_GOLD": gold_db,
+        "G3DT_S3_SILVER_DATA_DIR": f"s3://{silver_bucket}/dbt/",
+        "G3DT_S3_GOLD_DATA_DIR": f"s3://{gold_bucket}/dbt/",
         # CI isolation: the dbt template's `ci` target builds into these
         # instead — same grammar as the CDK's ci_ databases, same buckets
         # under a dbt_ci/ prefix. Real names above are never prefixed.
-        "G3DT_DB_RAW_SILVER_CI": f"ci_{raw_silver_db}" if raw_silver_db else None,
-        "G3DT_DB_RAW_GOLD_CI": f"ci_{raw_gold_db}" if raw_gold_db else None,
-        "G3DT_S3_SILVER_DATA_DIR_CI": f"s3://{rc.get('buckets/rawSilver')}/dbt_ci/",
-        "G3DT_S3_GOLD_DATA_DIR_CI": f"s3://{rc.get('buckets/rawGold')}/dbt_ci/",
+        "G3DT_DB_SILVER_CI": f"ci_{silver_db}",
+        "G3DT_DB_GOLD_CI": f"ci_{gold_db}",
+        "G3DT_S3_SILVER_DATA_DIR_CI": f"s3://{silver_bucket}/dbt_ci/",
+        "G3DT_S3_GOLD_DATA_DIR_CI": f"s3://{gold_bucket}/dbt_ci/",
     }
     if profile:
         # A named profile means a laptop run: select the dbt target that

gen3_dataops_toolkit-3.0.0/src/g3dt/cli/delete_cmds.py

@@ -0,0 +1,212 @@
+"""`g3dt delete` — destructive metadata removal (data-plane).
+
+A single ``delete metadata`` command handles one or many studies, sequentially,
+in a single job. ``--version`` is required: pass a specific version (e.g.
+``0.9.8``) to remove just that version (resolved via an Athena GUID lookup), or
+``all`` to remove every version.
+
+Every command confirms before acting. Production always requires typing the
+target id, even with ``--yes``. Deleting ALL versions always prompts, even with
+``--yes``. Confirmation happens locally before any EC2 dispatch (SSM has no
+TTY), after which the remote job runs non-interactively.
+"""
+from __future__ import annotations
+
+import re
+
+import typer
+
+from g3dt.cli._internal import dispatch, safety
+from g3dt.cli._internal.dispatch import Target
+from g3dt.cli._internal.resolve import study_of
+
+app = typer.Typer(no_args_is_help=True, help="Delete metadata from Gen3 (destructive).")
+
+_DELETE_METADATA = "services/delete/delete_metadata.sh"
+
+#: A version token in the form the Athena ``version`` column stores it. The
+#: uploader writes ``group(1)`` of this same pattern (metadata_submitter's
+#: ``_find_version_from_path``), i.e. WITHOUT any leading ``v``. The delete
+#: query interpolates the string straight into SQL, so a ``v``-prefixed version
+#: matches zero rows and is reported as "skipped" rather than as an error — a
+#: silent no-op that reads as a clean run. Normalising here closes that.
+_VERSION_RE = re.compile(r"^v?(\d+\.\d+\.\d+)$", re.IGNORECASE)
+
+
+def _normalise_version(raw: str, where: str) -> str:
+    """Canonicalise one version token to the form stored in Athena.
+
+    ``all`` in any case becomes ``all``; ``v1.5.4`` and ``1.5.4`` both become
+    ``1.5.4``. Anything else is a usage error: the column only ever holds
+    three-part semver, so a truncated version like ``0.9`` would match nothing
+    and be counted as a skip.
+    """
+    token = raw.strip()
+    if token.lower() == "all":
+        return "all"
+    match = _VERSION_RE.match(token)
+    if not match:
+        typer.secho(
+            f"Invalid version '{raw}' {where}: expected x.y.z (e.g. 0.9.8) "
+            "or 'all'.",
+            fg=typer.colors.RED,
+            err=True,
+        )
+        raise typer.Exit(2)
+    return match.group(1)
+
+
+def _parse_study_specs(studies: str, fallback, env: str):
+    """Turn ``--studies`` into ``[(resolved_study_key, version), ...]``.
+
+    Each comma-separated entry is ``name`` or ``name:version``. A bare name
+    takes *fallback* (the ``--version`` default); *fallback* is ``None`` when
+    ``--version`` was not given, which makes a bare name a usage error.
+
+    Every entry is validated before anything is dispatched, so a typo in the
+    last study cannot leave the earlier ones already deleted.
+    """
+    specs = []
+    for entry in studies.split(","):
+        entry = entry.strip()
+        if not entry:
+            continue
+
+        # partition() rather than split(), so a trailing colon ("ausdiab:") is
+        # distinguishable from a bare name and can be rejected instead of
+        # silently taking the fallback.
+        name, sep, raw_version = entry.partition(":")
+        name = name.strip()
+
+        if not name:
+            typer.secho(
+                f"Invalid --studies entry '{entry}': missing study name.",
+                fg=typer.colors.RED,
+                err=True,
+            )
+            raise typer.Exit(2)
+
+        if sep and not raw_version.strip():
+            typer.secho(
+                f"Invalid --studies entry '{entry}': ':' with no version. "
+                f"Use '{name}:0.9.8', '{name}:all', or a bare '{name}' to take "
+                "the --version default.",
+                fg=typer.colors.RED,
+                err=True,
+            )
+            raise typer.Exit(2)
+
+        if sep:
+            version = _normalise_version(raw_version, f"for study '{name}'")
+        elif fallback is not None:
+            version = fallback
+        else:
+            typer.secho(
+                f"No version for study '{name}': add ':<version>' to it "
+                f"(e.g. '{name}:0.9.8'), or pass --version as the default for "
+                "every study. Use 'all' to delete every version.",
+                fg=typer.colors.RED,
+                err=True,
+            )
+            raise typer.Exit(2)
+
+        specs.append((study_of(name, env).key, version))
+
+    if not specs:
+        typer.secho("--studies is empty.", fg=typer.colors.RED, err=True)
+        raise typer.Exit(2)
+    return specs
+
+
+@app.command()
+def metadata(
+    studies: str = typer.Option(
+        ...,
+        "--studies",
+        help="Comma-separated studies, each optionally 'name:version', "
+             "e.g. ausdiab:0.7.5,cdah:0.8.1,edcad.",
+    ),
+    env: str = typer.Option(..., "--env", "-e", help="Environment, e.g. test."),
+    version: str = typer.Option(
+        None,
+        "--version",
+        help="Default version for studies written without their own "
+             "':version', e.g. 0.9.8, or 'all' for every version.",
+    ),
+    node: str = typer.Option(None, "--node", help="Delete only this node type."),
+    yes: bool = typer.Option(
+        False, "--yes", "-y", help="Skip the non-prod prompt (specific-version only)."
+    ),
+    on: Target = typer.Option(Target.local, "--on", help="Run local or on ec2."),
+) -> None:
+    """Delete study metadata for one or more studies, sequentially, in one job.
+
+    Studies are processed one at a time. A study that exists but has no data at
+    the requested version is skipped, and the job continues to the next study.
+
+    Each study may carry its own version as ``name:version``; ``--version``
+    supplies the default for any study written bare. Examples:
+
+      g3dt delete metadata --studies "ausdiab:0.7.5,cdah:0.8.1" --env staging
+      g3dt delete metadata --studies "ausdiab:all,cdah" --version 0.9.8 --env staging
+    """
+    fallback = (
+        _normalise_version(version, "for --version") if version is not None else None
+    )
+    specs = _parse_study_specs(studies, fallback, env)
+    versions = [v for _, v in specs]
+
+    # The typed production confirmation stays the study keys alone: short
+    # enough to retype accurately, while the per-study versions are spelled
+    # out in the action line printed directly above the prompt.
+    target = ",".join(key for key, _ in specs)
+    uniform = len(set(versions)) == 1
+    any_all = "all" in versions
+
+    if uniform and versions[0] == "all":
+        action = "deletion of ALL VERSIONS"
+    elif uniform:
+        action = f"deletion of v{versions[0]}"
+    else:
+        plan = ", ".join(f"{key}:{v}" for key, v in specs)
+        action = f"deletion of per-study versions [{plan}]"
+
+    # Deleting every version is the most destructive path: always prompt (pass
+    # assume_yes=False so --yes can't bypass it; prod still types the target).
+    # One 'all' anywhere in the list is enough to force the prompt, so an 'all'
+    # buried mid-list cannot ride along on a batch marked unattended.
+    safety.confirm_destructive(action, target, env, False if any_all else yes)
+
+    def build_args(env_name):
+        if uniform:
+            # Canonical (and historical) shape: one --version for every study.
+            # Emitting it keeps a newer CLI compatible with an older installed
+            # service script on the box, which can lag a pip upgrade.
+            a = ["--studies", target, "--env", env_name, "--version", versions[0]]
+        else:
+            a = [
+                "--studies",
+                ",".join(f"{key}:{v}" for key, v in specs),
+                "--env",
+                env_name,
+            ]
+        if node:
+            a += ["--node", node]
+        return a
+
+    def remote_cli(env_name):
+        # --yes: confirmation already happened locally; the remote job must
+        # not prompt (SSM has no TTY). The raw --studies string is forwarded
+        # verbatim — the remote re-entry re-parses and re-validates it.
+        a = ["delete", "metadata", "--studies", studies, "--env", env_name]
+        if version is not None:
+            a += ["--version", version]
+        a.append("--yes")
+        if node:
+            a += ["--node", node]
+        return a
+
+    dispatch.run_or_dispatch(
+        on, env, _DELETE_METADATA, build_args, "delete-metadata",
+        interpreter="bash", remote_cli=remote_cli,
+    )

gen3_dataops_toolkit-3.0.0/src/g3dt/cli/indexd_cmds.py

@@ -0,0 +1,126 @@
+"""`g3dt indexd` — register S3 files with Gen3 indexd, and verify they download.
+
+``register`` is a long data-plane op, so it supports ``--on ec2``.
+``check-download`` is a read-only HTTP check that takes seconds and whose
+whole value is the PASS/FAIL in your terminal, so it is local-only.
+"""
+from __future__ import annotations
+
+from typing import List, Optional
+
+import typer
+
+from g3dt.cli._internal import dispatch, runner
+from g3dt.cli._internal.dispatch import Target
+from g3dt.cli._internal.resolve import env_of, study_of
+
+app = typer.Typer(
+    no_args_is_help=True,
+    help="Register files with Gen3 indexd and verify download access.",
+)
+
+_REGISTER = "services/indexd/register_indexd.py"
+_CHECK_DOWNLOAD = "services/indexd/verify_file_access.py"
+
+
+@app.command()
+def register(
+    s3_paths: List[str] = typer.Option(
+        ..., "--s3-paths", help="One or more S3 prefixes to scan (repeatable)."
+    ),
+    study: str = typer.Option(..., "--study", "-s", help="Study, e.g. edcad."),
+    env: str = typer.Option(..., "--env", "-e", help="Environment, e.g. test."),
+    dry_run: bool = typer.Option(
+        False, "--dry-run", help="Scan + write file_metadata only; skip indexd."
+    ),
+    force: bool = typer.Option(
+        False, "--force",
+        help="Re-register files already in the registry with the same md5.",
+    ),
+    on: Target = typer.Option(Target.local, "--on", help="Run local or on ec2."),
+) -> None:
+    """Scan S3 prefixes and register the files with Gen3 indexd.
+
+    Files already registered for this study at this endpoint with an unchanged
+    md5 are skipped (each re-registration would create a new indexd revision
+    and duplicate the registry). ``--force`` re-registers everything.
+
+    Examples:
+      g3dt indexd register --s3-paths s3://bucket/edcad/ --study edcad --env staging
+      g3dt indexd register --s3-paths s3://b/a/ --s3-paths s3://b/c/ --study edcad --env staging --on ec2
+    """
+    s = study_of(study, env)
+
+    def build_args(env_name):
+        a = ["--s3-paths", *s3_paths, "--study", s.key, "--env", env_name]
+        if dry_run:
+            a.append("--dry-run")
+        if force:
+            a.append("--force")
+        return a
+
+    def remote_cli(env_name):
+        a: list = ["indexd", "register"]
+        for p in s3_paths:
+            a += ["--s3-paths", p]
+        a += ["--study", study, "--env", env_name]
+        if dry_run:
+            a.append("--dry-run")
+        if force:
+            a.append("--force")
+        return a
+
+    dispatch.run_or_dispatch(
+        on, env, _REGISTER, build_args, "indexd-register", remote_cli=remote_cli,
+    )
+
+
+@app.command(name="check-download")
+def check_download(
+    guids: Optional[List[str]] = typer.Argument(
+        None,
+        help="Object GUIDs, e.g. PREFIX/<uuid>. Omit to sample the most "
+             "recently registered objects from the indexd registry.",
+    ),
+    env: str = typer.Option(..., "--env", "-e", help="Environment, e.g. test."),
+    limit: int = typer.Option(
+        25, "--limit", "-n",
+        help="How many objects to sample when no GUIDs are given.",
+    ),
+    key_path: Optional[str] = typer.Option(
+        None, "--key-path",
+        help="Break-glass: local Gen3 API key JSON file, instead of the "
+             "env's secret.",
+    ),
+) -> None:
+    """Prove registered objects are downloadable end to end.
+
+    Walks Indexd -> DRS -> Fence signed URL for each GUID and exits non-zero
+    if any object fails, so it can gate a deployment step. Read-only and
+    local-only (seconds, not a long job — there is nothing to dispatch to EC2).
+
+    The env selects the API key secret and the key's JWT selects the commons,
+    so a staging env checks staging. There is no URL to pass.
+
+    With no GUIDs, the newest --limit objects for this commons are sampled
+    from the indexd registry (latest revision per baseid). The registry may
+    live in a different AWS account than the commons — sampling needs an env
+    whose AWS profile can reach it; otherwise pass GUIDs explicitly.
+
+    Examples:
+      g3dt indexd check-download --env staging                 # sample 25 newest
+      g3dt indexd check-download --env staging --limit 50
+      g3dt indexd check-download --env prod PREFIX/aaa PREFIX/bbb
+    """
+    # Validate the env before spawning a subprocess: an unknown env should
+    # fail here with the config error, not deep inside the script.
+    e = env_of(env)
+
+    args: List[str] = ["--env", e.name]
+    if key_path:
+        args += ["--key-path", key_path]
+    if guids:
+        args += list(guids)
+    else:
+        args += ["--limit", str(limit)]
+    runner.run(runner.python_script(_CHECK_DOWNLOAD, *args))