Skip to content

πŸ’« 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.md
index 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 provid
Extension 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 catalogs
2. **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:
```yaml
catalogs:
diff --git a/src/specify_cli/extensions/_commands.py b/src/specify_cli/extensions/_commands.py
index 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 confirmation
console.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 policy
if 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.py
index 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.output
assert 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.