Dependency policy

Every third-party component Apollo Download Manager builds with or ships is approved, pinned, verified, recorded and credited in its notices. This page is the policy (#9). What the licences require is assessed in LICENSING.md.

The rule in AGENTS.md is short: a new crate, npm package, native library, service or background process needs Product Owner approval. This page says what that approval needs, and what happens afterwards.

What counts as a dependency

Approving a new dependency

Who: the Product Owner approves every new direct dependency, every new native library, toolchain, service or background process, and every exception to this policy. An agent or contributor proposes; the PO decides (AGENTS.md).

When: before the code that uses it is merged, in the issue or the PR that introduces it. A new major version of a direct dependency counts as a new approval.

The request states:

1. Need: what it's for, and why the current stack can't do it. Check first that nothing already in Cargo.lock or pnpm-lock.yaml does the job (AGENTS.md, "Reuse before you add").

2. Licence: the SPDX expression, and for an OR licence, the option Apollo Download Manager uses. Compare it with the allowed list below.

3. Maintenance: the latest release and its date, recent activity, and the maintainers.

4. Security: known advisories (RustSec, GitHub advisories, the vendor's own list such as curl's) and how fixes are released.

5. Weight: the transitive dependencies it adds (cargo tree -p <crate>, pnpm why <package>), and native build requirements.

6. Platforms: Windows, Linux and macOS support.

7. For native libraries: the exact source (official release URL), version, SHA-256, signature status and build options. A wrapper crate's version doesn't prove the native version it bundles: curl-sys 0.4.91 bundles curl 8.22.0 (research report, section 8.1).

After approval: add the dependency to the register in the same PR.

Transitive dependencies don't need individual approval, but they must pass the licence rules below. The notices generator lists every one, and pnpm check:notices fails on any that don't (LICENSING.md, #76).

Allowed licences

No aria2: Apollo Download Manager never includes aria2 or its source (ADR-0001), so its GPL obligations don't arise for Apollo Download Manager.

Pinning and updates

• Lockfiles are committed and authoritative. Cargo.lock and pnpm-lock.yaml change only in a PR that says why. Changing either selects every CI check (CI.md).

• Toolchains are pinned exactly. A change is its own PR with a full pnpm check:full run.

• GitHub Actions are pinned to full SHAs. Dependabot proposes updates monthly, grouped into one PR (CI.md).

• Rust and npm updates aren't automated, except Dependabot's security-fix PRs (PO decision on #75). Each update is a PR stating the reason (a fix, an advisory, a needed feature), with the full check level. Advisory monitoring and response times are in SECURITY.md.

• Native libraries are updated only by changing the native lock file, never by fetching "latest" at build time.

Native libraries

Lock file

Every native library Apollo Download Manager builds or bundles has one line in the native lock file, scripts/native/deps.lock (#35). The format follows V1's scripts/aria2/deps.lock and adds the signature status and licence. Two lines from it:

# name  version  source-url  sha256  signature  licence
zlib    1.3.2   https://github.com/madler/zlib/releases/download/v1.3.2/zlib-1.3.2.tar.xz  d7a0654783a4da529d1bb793b7ad9c3318020af77667bcae35f95d0e42a792f3  verified:5ED46A6721D365587791E2AA783FCD8E58BCAFBA  Zlib
curl    8.23.0  https://curl.se/download/curl-8.23.0.tar.xz  8dadd7d2536a314f982ad05a651b713f426bf7d02cc2c76cffb9796f2218e6c5  verified:27EDEAF22F3ABCEB50DB9A125CC908FDB71E12C2  curl

• One line per library, with a comment header saying when and how the hashes were computed.

• sha256 is computed from the downloaded file. The build refuses to continue if a download doesn't match.

• signature is verified:<fingerprint>, unverifiable:<reason>, or none-published. An unverifiable signature is recorded honestly, never assumed fine.

  • For verified, the fingerprint is the signer's primary key, and that project's published release-signing key is committed as scripts/native/keys/<name>.asc. The lock file's header says where each key came from.

  • The build checks the detached <source-url>.asc with gpg against that one key only, and refuses a signature from any other key, an expired or revoked key, or a file with more than one signature.

• Licence is an SPDX identifier from the permissive class in the table above. A line with any other licence is refused until the PO records an exception.

• Enforced by scripts/native/native-lib.mjs (unit tested), which pnpm native:fetch and pnpm native:build use (BUILDING_NATIVE.md).

• Licence text: each native library's own licence file, copied from its verified source, is scripts/notices/native/<name>.txt, outside scripts/native/ so that it doesn't change the native libraries' CI cache key. The notices generator refuses a library without one (#76).

Libraries from vcpkg

The torrent bridge's libraries, libtorrent, Boost and OpenSSL, aren't in the lock file yet. They are built with vcpkg, pinned by the registry's baseline commit and by overlay ports with each source's SHA-512 (PO decision on #62). Their own record is libtorrent-info.json (BUILDING_NATIVE.md). Building them from verified sources like libcurl is a release blocker below.

Build identity record

Each native build writes target/native/<target>/build-info.json (#35), and release packaging copies it next to its artefacts (#84). The fields are listed in BUILDING_NATIVE.md. For every native library it records:

• the source URL, SHA-256 and signature result (the release archive identifies the upstream release);

• the configure or CMake options;

• the TLS backend and the versions of every linked library (nghttp2, zlib, libssh2…);

• the SHA-256 of every built library and of the curl tool;

• the Rust and Node toolchain versions;

• the Apollo Download Manager commit.

The build also runs its own curl tool (curl -V), records what was actually linked, and fails unless it matches the lock file: libcurl at or above the version floor (8.23.0, research report section 8.1), the pinned nghttp2, zlib and TLS backend, the required protocols and features, and no protocol Apollo Download Manager doesn't use.

At run time, velocity-curl reads what is actually linked (curl_version_info: version, TLS backend, protocols, features), and refuses to start libcurl when it fails the same checks (BUILDING_NATIVE.md). pnpm native:verify enforces items 3 to 5 of the release blockers below, and pnpm tauri build runs it first.

Distribution packages

A distribution's own dynamic libraries bring their own dependency closure. Ubuntu 24.04's libcurl 8.5.0 links libssh 0.10.6 (LGPL-2.1), librtmp (LGPL-2.1) and libidn2 (LGPLv3+ or GPLv2+), as the curl -V line in V1's saved benchmark results shows (research report section 8.2). So:

• Never bundle distribution libraries into a self-contained package (an AppImage, or a Windows or macOS installer) without a licensing review and PO approval. Release builds link the libraries from the native lock file.

• Distribution packagers may link the system libcurl, but the runtime capability check (#35) still applies.

Release blockers related to provenance

A release or release candidate isn't built while any of these is true (#17, #18, #78):

1. A dependency without approval: a direct dependency, native library, toolchain or action without an approval record.

2. A licence outside the allowed list, or an unknown licence, without a PO exception recorded in LICENSING.md.

3. A native library not in the lock file, or whose download doesn't match its SHA-256.

4. A missing or incomplete build-info.json.

5. libcurl below the version floor, or a native library with a known unfixed advisory rated Medium or higher affecting an enabled feature (#35, #75).

6. Out-of-date third-party notices (#76): not regenerated for this build, or with unreviewed new entries.

7. The torrent bridge's libraries from vcpkg (#62): libtorrent, Boost and OpenSSL must come from Apollo Download Manager's own build of verified sources, as libcurl does, and be checked by pnpm native:verify. Until then they are for development and tests only (PO decision on #62).

Approved direct dependencies

The register of direct dependencies and how each was approved. Transitive dependencies are listed in THIRD_PARTY_NOTICES.md (#76).