π« Toolkit to help you get started with SDD or any other process!
Clarify extension catalog trust model in docs, help, and messaging (#4177)
Manfred Riemfa3a5c5ce724
diff --git a/docs/reference/extensions.md b/docs/reference/extensions.mdindex 919617a08..8de2c18c8 100644--- a/docs/reference/extensions.md+++ b/docs/reference/extensions.md@@ -96,6 +96,25 @@ Changes the resolution priority of an extension. When multiple extensions providExtension catalogs control where `search` and `add` look for extensions. Catalogs are checked in priority order (lower number = higher precedence).+### Trust model: discovery-only vs. install sources++Catalogs come in two kinds, and the distinction is a **security boundary**, not a limitation:++- **Install sources** (`install_allowed: true`) β catalogs you trust as a place to install from. The built-in `default` (official) catalog is one, as is any catalog you author and vet yourself.+- **Discovery-only** catalogs (`install_allowed: false`) β searchable surfaces for *finding* extensions, but not installable. The built-in `community` catalog is discovery-only and is already active for `search` out of the box; you do not need to add it.++`community` is intentionally discovery-only because it is an open, unvetted list. Making everything in it one-command-installable would mean pulling arbitrary third-party code with no review.++> **Do not flip a discovery-only catalog to `install_allowed`.** That defeats the entire point of separating discovery from installation. There are two correct ways to install something you found via `community`:+>+> 1. **Install a single vetted extension directly** with `--from` (no catalog authoring needed). Get the candidate archive URL from `specify extension info <name>` β for a discovery-only entry it prints a "Candidate archive" URL. Review that release archive, then install it:+> ```bash+> specify extension info <name> # shows the candidate archive URL+> specify extension add <name> --from <archive-url>+> ```+> Treat the URL as untrusted until you have vetted it β it comes from an unvetted catalog.+> 2. **Curate your own catalog** you control and vet, and mark *that* catalog `install_allowed: true` β for when you want a governed, reusable install source (e.g. for an org).+### List Catalogs```bash@@ -114,7 +133,7 @@ specify extension catalog add <url>| ------------------------------------ | -------------------------------------------------- || `--name <name>` | Required. Unique name for the catalog || `--priority <N>` | Priority (default: 10; lower = higher precedence) |-| `--install-allowed / --no-install-allowed` | Whether extensions can be installed from this catalog |+| `--install-allowed / --no-install-allowed` | Mark the catalog as a trusted install source. Only enable for a catalog you own and vet; leave off (the default) for discovery-only sources. Never enable it for an unvetted public catalog. || `--description <text>` | Optional description |Adds a catalog to the project's `.specify/extension-catalogs.yml`.@@ -134,9 +153,9 @@ Catalogs are resolved in this order (first match wins):1. **Environment variable** β `SPECKIT_CATALOG_URL` overrides all catalogs2. **Project config** β `.specify/extension-catalogs.yml`3. **User config** β `~/.specify/extension-catalogs.yml`-4. **Built-in defaults** β official catalog + community catalog+4. **Built-in defaults** β official `default` catalog (install-allowed) + `community` catalog (discovery-only)-Example `.specify/extension-catalogs.yml`:+Example `.specify/extension-catalogs.yml` for a catalog you own and vet:```yamlcatalogs:diff --git a/src/specify_cli/extensions/_commands.py b/src/specify_cli/extensions/_commands.pyindex 1e78ee811..7f7933e93 100644--- a/src/specify_cli/extensions/_commands.py+++ b/src/specify_cli/extensions/_commands.py@@ -43,7 +43,15 @@ extension_app = typer.Typer(catalog_app = typer.Typer(name="catalog",- help="Manage extension catalogs",+ help=(+ "Manage extension catalogs.\n\n"+ "Catalogs are either install sources (install_allowed) or discovery-only "+ "search surfaces. The built-in 'community' catalog is discovery-only by "+ "design: it is unvetted, so it is searchable but not installable. To install "+ "something you found there, either use 'specify extension add <name> --from "+ "<url>' after vetting it, or curate your own catalog you control. Never flip a "+ "discovery-only catalog to install_allowed β that is the vetting boundary."+ ),add_completion=False,)extension_app.add_typer(catalog_app, name="catalog")@@ -71,6 +79,33 @@ def _display_project_path(*args, **kwargs):return _f(*args, **kwargs)+def _command_safe_id(raw_id: object, placeholder: str = "<extension-id>") -> str:+ """Return an extension ID that is safe to embed in a suggested shell command.++ Catalog entries (especially from discovery-only catalogs) are untrusted:+ their keys are not validated during catalog merge, so an ``id`` like+ ``foo; rm -rf ~`` could otherwise be interpolated into a command we+ explicitly encourage the user to copy and run. ``rich.markup.escape`` only+ neutralizes Rich markup, not shell metacharacters, so it is not sufficient+ here. Only emit the real ID when it matches the same+ lowercase-alphanumeric-and-hyphen rule ``ExtensionManifest`` enforces+ (``^[a-z0-9-]+$``); otherwise fall back to a literal placeholder so the+ printed command never carries catalog-controlled shell text.++ A leading hyphen is additionally rejected: an ID like ``--force`` satisfies+ the pattern but Typer would parse it as an option rather than the positional+ extension argument, yielding a non-copyable or option-altering command.+ """+ from . import VALID_EXTENSION_ARTIFACT_NAME_PATTERN++ text = str(raw_id)+ if text.startswith("-"):+ return placeholder+ if VALID_EXTENSION_ARTIFACT_NAME_PATTERN.match(text):+ return text+ return placeholder++def _refresh_events_and_warn(project_root: Path) -> None:"""Refresh native event config and surface failures (R3).@@ -444,6 +479,14 @@ def catalog_list():console.print(f" Install: {install_str}")console.print()+ if any(not entry.install_allowed for entry in active_catalogs):+ console.print(+ "[dim]Discovery-only catalogs are searchable but not installable by design "+ "(unvetted sources). To install something you found in one, vet it and run "+ "'specify extension add <name> --from <url>', or add it to a catalog you "+ "control. Don't flip a discovery-only catalog to install_allowed.[/dim]\n"+ )+config_path = project_root / ".specify" / "extension-catalogs.yml"user_config_path = Path.home() / ".specify" / "extension-catalogs.yml"if os.environ.get("SPECKIT_CATALOG_URL"):@@ -477,7 +520,11 @@ def catalog_add(priority: int = typer.Option(10, "--priority", help="Priority (lower = higher priority)"),install_allowed: bool = typer.Option(False, "--install-allowed/--no-install-allowed",- help="Allow extensions from this catalog to be installed",+ help=(+ "Mark this catalog as a trusted install source. Only enable this for a "+ "catalog you own and vet; leave it off (the default) for discovery-only "+ "search surfaces. Never enable it for an unvetted public catalog."+ ),),description: str = typer.Option("", "--description", help="Description of the catalog"),):@@ -903,8 +950,8 @@ def extension_add(# Warn about untrusted sources β default-deny confirmationconsole.print()console.print(Panel(- f"[bold]You are installing an extension from an external URL that is not\n"- f"listed in any of your configured extension catalogs.[/bold]\n\n"+ f"[bold]You are installing an extension directly from an external URL,\n"+ f"bypassing your trusted (install-allowed) extension catalogs.[/bold]\n\n"f"URL: {safe_url}\n\n"f"Only install extensions from sources you trust.",title="[bold yellow]β Untrusted Source[/bold yellow]",@@ -1007,13 +1054,25 @@ def extension_add(# Enforce install_allowed policyif not ext_info.get("_install_allowed", True):catalog_name = _escape_markup(str(ext_info.get("_catalog_name", "community")))+ resolved_id = _command_safe_id(ext_info["id"])console.print(- f"[red]Error:[/red] '{safe_extension}' is available in the "- f"'{catalog_name}' catalog but installation is not allowed from that catalog."+ f"[red]Error:[/red] '{safe_extension}' was found in the "+ f"'{catalog_name}' catalog, which is discovery-only β a search "+ f"surface, not an install source.")console.print(- f"\nTo enable installation, add '{safe_extension}' to an approved catalog "- f"(install_allowed: true) in .specify/extension-catalogs.yml."+ "\nDiscovery-only catalogs are intentionally not installable so "+ "unvetted extensions can't be pulled in without review. Don't flip "+ "such a catalog to install_allowed. Instead, once you've vetted this "+ "extension:"+ )+ console.print(+ f" β’ install it directly from its archive URL:\n"+ f" specify extension add {resolved_id} --from <archive-url>"+ )+ console.print(+ " β’ or add it to a catalog you curate and control "+ "(install_allowed: true).")raise typer.Exit(1)@@ -1256,14 +1315,16 @@ def extension_search(console.print(f" [dim]Repository:[/dim] {_escape_markup(str(ext['repository']))}")# Install command (show warning if not installable)- safe_id = _escape_markup(str(ext['id']))+ cmd_id = _command_safe_id(ext['id'])if install_allowed:- console.print(f"\n [cyan]Install:[/cyan] specify extension add {safe_id}")+ console.print(f"\n [cyan]Install:[/cyan] specify extension add {cmd_id}")else:- console.print(f"\n [yellow]β [/yellow] Not directly installable from '{catalog_name}'.")+ console.print(f"\n [yellow]β [/yellow] Not directly installable from '{catalog_name}' (discovery-only).")+ console.print(+ f" Once vetted, install it directly: specify extension add {cmd_id} --from <archive-url>"+ )console.print(- f" Add to an approved catalog with install_allowed: true, "- f"or install from an archive URL: specify extension add {safe_id} --from <archive-url>"+ " Don't flip a discovery-only catalog to install_allowed β that's the vetting boundary.")console.print()@@ -1485,22 +1546,39 @@ def _print_extension_info(ext_info: dict, manager):is_installed = manager.registry.is_installed(ext_info['id'])install_allowed = ext_info.get("_install_allowed", True)safe_id = _escape_markup(str(ext_info['id']))+ cmd_id = _command_safe_id(ext_info['id'])if is_installed:console.print("[green]β Installed[/green]")metadata = manager.registry.get(ext_info['id'])priority = normalize_priority(metadata.get("priority") if isinstance(metadata, dict) else None)console.print(f"[dim]Priority:[/dim] {priority}")- console.print(f"\nTo remove: specify extension remove {safe_id}")+ console.print(f"\nTo remove: specify extension remove {cmd_id}")elif install_allowed:console.print("[yellow]Not installed[/yellow]")- console.print(f"\n[cyan]Install:[/cyan] specify extension add {safe_id}")+ console.print(f"\n[cyan]Install:[/cyan] specify extension add {cmd_id}")else:catalog_name = _escape_markup(str(ext_info.get("_catalog_name", "community")))console.print("[yellow]Not installed[/yellow]")console.print(- f"\n[yellow]β [/yellow] '{safe_id}' is available in the '{catalog_name}' catalog "- f"but not in your approved catalog. Add it to .specify/extension-catalogs.yml "- f"with install_allowed: true to enable installation."+ f"\n[yellow]β [/yellow] '{safe_id}' is in the '{catalog_name}' catalog, which is "+ f"discovery-only (a search surface, not an install source)."+ )+ download_url = ext_info.get("download_url")+ if download_url:+ console.print(+ f"Candidate archive (vet before installing): {_escape_markup(str(download_url))}"+ )+ console.print(+ f"Once vetted, install directly: specify extension add {cmd_id} --from <archive-url>"+ )+ else:+ console.print(+ f"Once you've vetted its release archive, install directly: "+ f"specify extension add {cmd_id} --from <archive-url>"+ )+ console.print(+ "Discovery-only catalogs are intentionally not install sources β don't set "+ "install_allowed on them.")diff --git a/tests/test_extensions.py b/tests/test_extensions.pyindex 36e7d67aa..6642da2b0 100644--- a/tests/test_extensions.py+++ b/tests/test_extensions.py@@ -7492,6 +7492,88 @@ class TestExtensionAddCLI:assert result.exit_code == 0, result.outputassert f"Config: {display_path}" in result.output+ def test_catalog_list_shows_discovery_only_guidance(self, tmp_path):+ """A discovery-only catalog should trigger the trust-model guidance,+ steering users to --from / their own catalog and away from flipping+ install_allowed."""+ from typer.testing import CliRunner+ from unittest.mock import patch+ from specify_cli import app+ import yaml++ project_dir = tmp_path / "test-project"+ project_dir.mkdir()+ specify_dir = project_dir / ".specify"+ specify_dir.mkdir()+ (specify_dir / "extension-catalogs.yml").write_text(+ yaml.safe_dump(+ {+ "catalogs": [+ {+ "name": "community",+ "url": "https://example.com/catalog.json",+ "priority": 10,+ "install_allowed": False,+ }+ ]+ }+ ),+ encoding="utf-8",+ )++ runner = CliRunner()+ with patch.object(Path, "cwd", return_value=project_dir):+ result = runner.invoke(+ app,+ ["extension", "catalog", "list"],+ catch_exceptions=True,+ )++ assert result.exit_code == 0, result.output+ output = " ".join(result.output.split())+ assert "not installable by design" in output+ assert "--from <url>" in output+ assert "Don't flip a discovery-only catalog to install_allowed" in output++ def test_catalog_list_omits_guidance_when_all_installable(self, tmp_path):+ """When every catalog is an install source, the discovery-only guidance+ should not appear."""+ from typer.testing import CliRunner+ from unittest.mock import patch+ from specify_cli import app+ import yaml++ project_dir = tmp_path / "test-project"+ project_dir.mkdir()+ specify_dir = project_dir / ".specify"+ specify_dir.mkdir()+ (specify_dir / "extension-catalogs.yml").write_text(+ yaml.safe_dump(+ {+ "catalogs": [+ {+ "name": "my-org",+ "url": "https://example.com/catalog.json",+ "priority": 10,+ "install_allowed": True,+ }+ ]+ }+ ),+ encoding="utf-8",+ )++ runner = CliRunner()+ with patch.object(Path, "cwd", return_value=project_dir):+ result = runner.invoke(+ app,+ ["extension", "catalog", "list"],+ catch_exceptions=True,+ )++ assert result.exit_code == 0, result.output+ assert "not installable by design" not in result.output+def test_catalog_add_escapes_config_read_exception_markup(self, tmp_path):"""Catalog config parse errors can include user-controlled file content."""import yaml@@ -7827,6 +7909,186 @@ class TestExtensionAddCLI:f"but was called with '{download_called_with[0]}'")+ def test_add_discovery_only_error_suggests_resolved_id(self, tmp_path):+ """The not-installable error must suggest a copy-pasteable command using+ the resolved catalog ID, not a display name that may contain spaces."""+ from typer.testing import CliRunner+ from unittest.mock import patch, MagicMock+ from specify_cli import app++ runner = CliRunner()++ project_dir = tmp_path / "test-project"+ project_dir.mkdir()+ (project_dir / ".specify").mkdir()+ (project_dir / ".specify" / "extensions").mkdir(parents=True)++ mock_catalog = MagicMock()+ mock_catalog.get_extension_info.return_value = None # ID lookup fails+ mock_catalog.search.return_value = [+ {+ "id": "acme-jira-integration",+ "name": "Jira Integration",+ "version": "1.0.0",+ "description": "Jira integration extension",+ "_install_allowed": False,+ "_catalog_name": "community",+ }+ ]++ with patch("specify_cli.extensions.ExtensionCatalog", return_value=mock_catalog), \+ patch.object(Path, "cwd", return_value=project_dir):+ result = runner.invoke(+ app,+ ["extension", "add", "Jira Integration"],+ catch_exceptions=True,+ )++ assert result.exit_code == 1, result.output+ output = " ".join(result.output.split())+ # Suggested command uses the resolved ID and stays a single token.+ assert "add acme-jira-integration --from" in output+ # It must not emit the space-containing display name as the command target.+ assert "add Jira Integration --from" not in output++ def test_add_discovery_only_error_neutralizes_unsafe_id(self, tmp_path):+ """A catalog-controlled ID with shell metacharacters must never be+ interpolated into the suggested command; it is replaced by a literal+ placeholder so copying the command can't execute injected shell text."""+ from typer.testing import CliRunner+ from unittest.mock import patch, MagicMock+ from specify_cli import app++ runner = CliRunner()++ project_dir = tmp_path / "test-project"+ project_dir.mkdir()+ (project_dir / ".specify").mkdir()+ (project_dir / ".specify" / "extensions").mkdir(parents=True)++ malicious_id = "foo; rm -rf ~"+ mock_catalog = MagicMock()+ mock_catalog.get_extension_info.return_value = {+ "id": malicious_id,+ "name": "Evil Ext",+ "version": "1.0.0",+ "description": "malicious",+ "_install_allowed": False,+ "_catalog_name": "community",+ }+ mock_catalog.search.return_value = []++ with patch("specify_cli.extensions.ExtensionCatalog", return_value=mock_catalog), \+ patch.object(Path, "cwd", return_value=project_dir):+ result = runner.invoke(+ app,+ ["extension", "add", malicious_id],+ catch_exceptions=True,+ )++ assert result.exit_code == 1, result.output+ output = " ".join(result.output.split())+ # The runnable command uses a literal placeholder, never the raw ID.+ assert "add <extension-id> --from" in output+ # The malicious ID is never rendered as the target of an install command.+ assert f"add {malicious_id} --from" not in output+ assert "add foo; rm" not in output++ def test_command_safe_id_rejects_leading_hyphen(self):+ """An ID like ``--force`` matches the manifest character rule but Typer+ would parse it as an option, not the positional extension argument, so+ the helper must fall back to the placeholder."""+ from specify_cli.extensions._commands import _command_safe_id++ assert _command_safe_id("--force") == "<extension-id>"+ assert _command_safe_id("-x") == "<extension-id>"+ # A normal slug is still returned verbatim.+ assert _command_safe_id("acme-thing") == "acme-thing"++ def test_info_discovery_only_shows_candidate_archive_url(self, tmp_path):+ """For a discovery-only entry that carries a ``download_url``, ``info``+ surfaces the candidate archive URL (flagged for vetting) and the vetted+ ``--from`` install guidance, so users have a CLI path to the URL."""+ from typer.testing import CliRunner+ from unittest.mock import patch, MagicMock+ from specify_cli import app++ runner = CliRunner()++ project_dir = tmp_path / "test-project"+ project_dir.mkdir()+ (project_dir / ".specify").mkdir()+ (project_dir / ".specify" / "extensions").mkdir(parents=True)++ archive_url = "https://example.com/acme-thing-1.0.0.zip"+ mock_catalog = MagicMock()+ mock_catalog.get_extension_info.return_value = {+ "id": "acme-thing",+ "name": "Acme Thing",+ "version": "1.0.0",+ "description": "A thing",+ "download_url": archive_url,+ "_install_allowed": False,+ "_catalog_name": "community",+ }+ mock_catalog.search.return_value = []++ with patch("specify_cli.extensions.ExtensionCatalog", return_value=mock_catalog), \+ patch("specify_cli.extensions.ExtensionManager") as mock_mgr, \+ patch.object(Path, "cwd", return_value=project_dir):+ mock_mgr.return_value.registry.is_installed.return_value = False+ result = runner.invoke(+ app,+ ["extension", "info", "acme-thing"],+ catch_exceptions=True,+ )++ output = " ".join(result.output.split())+ assert "discovery-only" in output+ assert f"Candidate archive (vet before installing): {archive_url}" in output+ assert "specify extension add acme-thing --from <archive-url>" in output++ def test_info_discovery_only_without_url_falls_back(self, tmp_path):+ """A discovery-only entry lacking ``download_url`` still gets vetted+ ``--from`` guidance, without claiming a candidate archive it doesn't+ have."""+ from typer.testing import CliRunner+ from unittest.mock import patch, MagicMock+ from specify_cli import app++ runner = CliRunner()++ project_dir = tmp_path / "test-project"+ project_dir.mkdir()+ (project_dir / ".specify").mkdir()+ (project_dir / ".specify" / "extensions").mkdir(parents=True)++ mock_catalog = MagicMock()+ mock_catalog.get_extension_info.return_value = {+ "id": "acme-thing",+ "name": "Acme Thing",+ "version": "1.0.0",+ "description": "A thing",+ "_install_allowed": False,+ "_catalog_name": "community",+ }+ mock_catalog.search.return_value = []++ with patch("specify_cli.extensions.ExtensionCatalog", return_value=mock_catalog), \+ patch("specify_cli.extensions.ExtensionManager") as mock_mgr, \+ patch.object(Path, "cwd", return_value=project_dir):+ mock_mgr.return_value.registry.is_installed.return_value = False+ result = runner.invoke(+ app,+ ["extension", "info", "acme-thing"],+ catch_exceptions=True,+ )++ output = " ".join(result.output.split())+ assert "Candidate archive" not in output+ assert "vetted its release archive" in output+ assert "specify extension add acme-thing --from <archive-url>" in output+def test_info_by_name_tolerates_non_string_catalog_name(self, tmp_path):"""Display-name resolution must not crash on a non-string catalog name.