[FEATURE] URL-based marketplace work Extension

[Vicente-Pastor]

Overview

This issue tracks the future extension of the URL-based marketplace work (#676) to support installing full APM packages directly from a URL — without requiring the package to be hosted on GitHub or registered in a marketplace.

Not in scope for #676. The current implementation must not foreclose this direction. Design decisions in Steps 1–8 of #676 should stay compatible with the constraints listed here.

---

Motivation

Issue #676 teaches APM to discover skills from a URL-based index. The natural next step is to allow installing any full APM package (apm.yml-bearing repository) directly from a URL:

# Hypothetical future UX
apm install https://example.com/packages/my-agent.tar.gz
apm install https://cdn.corp.com/apm/packages/my-toolkit@2.1.0
apm install https://example.com  # origin autodiscovery, analogous to marketplace add

---

Capabilities Required

Capability	Notes
URL install source type	apm install <url> resolved the same way as apm install owner/repo
Package manifest fetch	Download + parse apm.yml from a URL endpoint or inside an archive
Archive extraction	.tar.gz / .zip with safety checks (path traversal, decompression bombs) — overlaps Step 7 of #676
Digest / integrity pinning	apm install https://…#sha256:<hex> syntax for reproducible installs
Lockfile provenance	source_url + source_digest fields in LockedDependency — overlaps Step 5 of #676
Transitive resolution	Dependencies declared in apm.yml resolved recursively, same as GitHub installs
Auth for private endpoints	Bearer token or API key in ~/.apm/auth.json, analogous to GHE token support

---

Design Constraints for #676

The following decisions in #676 must remain compatible with this direction:

1. source_type discriminator on MarketplaceSource — the "github" / "url" pattern should be extended (not replaced). Avoid hardcoding a two-value enum; leave it open for "url-package" or similar.

2. _fetch_url_direct() in client.py — keep it generic (plain HTTPS GET, no Agent Skills assumptions). Future callers can reuse it for package manifest and archive fetches. Do not embed Agent Skills index logic inside this function.

3. _detect_index_format() heuristic — the detection pattern (inspect a key, dispatch to a parser) is the right abstraction for detecting apm.yml vs Agent Skills vs legacy marketplace.json. Keep it extensible.

4. LockedDependency fields added in Step 5 (marketplace_index_url, marketplace_index_digest) — name and design these to generalise to any URL-sourced install. Consider source_url / source_digest as more neutral names.

5. Archive support in Step 7 — implement extraction as a standalone utility (apm_cli/utils/archive.py) decoupled from the marketplace layer, so the package installer can reuse it without importing marketplace internals.

6. Resolver changes in Step 8 — design the resolver interface so that a future resolve_url_package() is a parallel code path, not a special-case fork inside existing functions.

---

Security Considerations

• All URL installs MUST use HTTPS — enforced at the fetch layer (_fetch_url_direct), not just at the command layer.
• Self-signed / internal CA certificates: document REQUESTS_CA_BUNDLE env var — no APM-specific --ca-bundle flag needed.
• Skill artifact URLs per the Agent Skills RFC may point to a different domain than the index (e.g. CDN). Both the index fetch and downstream artifact fetches must enforce HTTPS independently.
• Per the RFC Security Considerations: clients SHOULD maintain a configurable domain allowlist for skill artifacts. This applies equally to package URLs.
• Digest verification is meaningless over plain HTTP — integrity guarantees only hold when transport is authenticated.

---

Related

• Marketplace add source parity with the Anthropic spec #676 — feat: support URL-based marketplace registration for Agent Skills discovery indexes
• Agent Skills Discovery RFC: https://github.com/cloudflare/agent-skills-discovery-rfc
• RFC 8615 (Well-Known URIs): https://datatracker.ietf.org/doc/html/rfc8615

[sergio-sisternes-epam]

Cross-reference: This issue is part of a related set of URL-based dependency features being discussed together:

• [FEATURE] Skills from .well-known URIs #554 -- Direct URL dependencies in apm.yml
• Marketplace add source parity with the Anthropic spec #676 -- URL-based marketplace registration via .well-known
• [FEATURE] URL-based marketplace work Extension #692 -- apm install URL for full packages (this issue)

Design discussion is being coordinated in #676, which has been moved to needs-design to address the HTTPS authentication gap before implementation. See the comment there for context and open questions.

[github-actions]

Triage decision

needs-design

Proposed labels

theme/portability
area/marketplace
area/docs-site
type/architecture
status/needs-design

Milestone

null

Suggested next action

Ensure the source_type discriminator on MarketplaceSource and the source_url / source_digest fields in LockedDependency being designed for #676 are left extensible for URL-based installs; link this issue as a design constraint in the #676 PR.

Suggested issue comment

Thanks for filing this as a forward-compatibility design document, `@Vicente-Pastor`! This is exactly the kind of issue that prevents #676 from accidentally foreclosing a valuable future direction.

The capabilities table is well-constructed. A few things to note as the #676 design progresses:

1. **`source_type` discriminator**: The enum should not be a two-value closed set (`"github"` / `"url"`). Leave it open-ended (a string with validated values) so future source types (OCI, private registries, etc.) do not require a schema migration.

2. **`source_url` + `source_digest` in `LockedDependency`**: These fields are the right provenance primitives. The digest must use a content-addressing scheme (`sha256:<hex>`) so installs from URLs are as reproducible as GitHub commit-SHA installs.

3. **Archive extraction**: Path traversal protection is non-negotiable (this aligns with `src/apm_cli/utils/path_security.py`'s `ensure_path_within` guardrail). The design for #676's Step 7 should explicitly reference this.

This issue will remain `needs-design` until a concrete implementation proposal for URL-based installs is drafted. In the meantime, please add a note in the #676 PR description referencing this issue so reviewers keep the compatibility constraints in view.

Per-lens notes (collapsed)

DevX UX Expert -- User-Need Reviewer

This is a design-constraint issue, not an immediate feature request. The user task being protected is "install any APM package from any URL without being forced to GitHub". The capabilities table (URL source type, manifest fetch, archive extraction, digest pinning, lockfile provenance, transitive resolution, auth for private endpoints) is comprehensive and well-framed. The issue correctly identifies that the critical design decisions live inside #676, not in a future PR.

Supply Chain Security Expert -- Risk-Surface Reviewer

URL-based package installs are a significant supply chain surface. The issue explicitly calls out the two most critical controls: (1) digest pinning (sha256:<hex> syntax) for reproducibility and (2) path traversal protection for archive extraction. Both are required, not optional. The source_url + source_digest provenance fields in LockedDependency align with APM's existing commit-SHA integrity model. The theme/portability primary theme is correct; security is a design constraint embedded in the capability requirements.

OSS Growth Hacker -- Contributor-Tone Reviewer

Vicente-Pastor has author_association=NONE on microsoft/apm, activating this lens. This is their second issue and it demonstrates increasing depth of engagement with the codebase (referencing #676, LockedDependency, MarketplaceSource). The reply should acknowledge the quality of the design document and make the contributor feel like a valued voice in the architecture discussion, not just a feature requester.

Python Architect -- Architecture Reviewer

The cross-cutting impact is real: LockedDependency schema change (two new fields), MarketplaceSource discriminator extension, a new download pipeline branch, archive extraction module, and auth resolver extension. These touch lockfile, marketplace, distribution, and auth surfaces. The issue is valuable as a forward-compatibility anchor. type/architecture is correct. The design cannot land until a concrete proposal for the full URL install pipeline is written -- status/needs-design is appropriate.

Doc Writer -- Documentation Reviewer

A URL-based install source type would require a new section in the install reference (cli-commands.md) and possibly a new guide page on URL-based package authoring and distribution. area/docs-site as a secondary label ensures the eventual implementing PR is reminded to update docs.

APM CEO -- Triage Arbiter

This is a valuable design-constraint document that protects APM's future flexibility. The ask is not to implement URL installs now, but to keep #676 compatible. needs-design with no milestone is correct -- this is forward-planning work. Primary theme: theme/portability (install from any source). The security constraints (digest, path traversal) are design requirements, not a reason to apply theme/security as the primary theme.

{
  "decision": "needs-design",
  "decision_detail": "Full URL install pipeline (manifest fetch, archive extraction, integrity pinning, transitive resolution, auth for private endpoints) must be designed before implementation. This issue serves as a forward-compatibility constraint anchor for #676.",
  "theme": "theme/portability",
  "areas": ["area/marketplace", "area/docs-site"],
  "type": "type/architecture",
  "status": "status/needs-design",
  "priority": null,
  "preserved_labels": [],
  "milestone": null,
  "next_action": "Ensure source_type discriminator and source_url/source_digest fields being designed for #676 remain extensible; link this issue as a design constraint in the #676 PR description.",
  "comment_markdown": "Thanks for filing this as a forward-compatibility design document, `@Vicente-Pastor`! This is exactly the kind of issue that prevents #676 from accidentally foreclosing a valuable future direction.\n\nThe capabilities table is well-constructed. A few things to note as the #676 design progresses:\n\n1. **`source_type` discriminator**: The enum should not be a two-value closed set. Leave it open-ended (a string with validated values) so future source types (OCI, private registries, etc.) do not require a schema migration.\n\n2. **`source_url` + `source_digest` in `LockedDependency`**: These fields are the right provenance primitives. The digest must use a content-addressing scheme (`sha256:<hex>`) so installs from URLs are as reproducible as GitHub commit-SHA installs.\n\n3. **Archive extraction**: Path traversal protection is non-negotiable (aligns with `src/apm_cli/utils/path_security.py`'s `ensure_path_within` guardrail). The design for #676's Step 7 should explicitly reference this.\n\nThis issue will remain `needs-design` until a concrete implementation proposal for URL-based installs is drafted. In the meantime, please add a note in the #676 PR description referencing this issue so reviewers keep the compatibility constraints in view."
}

---

Triage status: agentic proposal pending human ratification.
Silence is approval. Maintainers can:

• Override any label or milestone above by editing it directly --
  human edits are authoritative and will not be reverted on
  subsequent runs.
• Re-trigger triage by applying the status/needs-triage label, or
  by removing status/triaged to enroll the issue in the next
  daily sweep.

Posted by the Triage Panel workflow. See .apm/skills/apm-triage-panel for the panel skill.

Generated by Triage Panel · ● 2.2M · ◷