Security

Release installation verifies the signed programs Link publishes. A module from outside Link is checked against the maker's key you trusted.

Which program runs

lnk <group> runs lnk-<module> from lnk's own folder first, then from the PATH, the way git does. So whoever can write to a folder on the user's PATH can already replace what the command runs. Empty and relative PATH entries, such as the current folder, are skipped: lnk drops them from the PATH it runs with and hands its modules, so neither runs a tar or systemctl from the folder it was started in.

What installs modules

Release installs check signatures and checksums. A source installation builds the selected checkout instead, so its trust comes from that source.

  • lnk up, lnk module add, a missing module's install offer and lnk upgrade install Link's modules only from a release whose SHA256SUMS is signed by the keys built into lnk, and check each archive against it.
  • lnk module add takes the release of lnk's own version, so modules and core match.
  • In a terminal, a missing-module offer asks first unless the command already names the module. Outside a terminal, a direct command can install the modules its declared operation needs. A module's nested call installs nothing and names the missing prerequisite.
  • When an enabled agent tool is missing, a release build can install lnk-run-tool, lnk-file-tool, or lnk-code-tool from the signed release of lnk's own version. A source build requires the tool's executable to be available from the same checkout.
  • install.sh installs lnk alone.
  • Link's modules come only from Link's own releases. Prebuilt programs exist for macOS (Apple Silicon, Intel) and Linux (x86_64, arm64) only; other platforms build from source.

A module Link doesn't build is checked against its maker's key, which you trust once and lnk pins.

  • lnk module add --url <url> takes a GitHub repository's latest release (https://github.com/<owner>/<repo> only), its SHA256SUMS signed with that repository's own key in the link-release namespace, and each archive checked against it. Link's keys never vouch for it.
  • The first add trusts the key the release itself offers (release-key.pub), after showing its fingerprint and asking, or --yes. Whoever controls the repository on that first day is trusted: compare the fingerprint with one its maker publishes elsewhere.
  • lnk pins the repository and the key in ~/Link/Safe/settings.toml (600). Every later add and lnk upgrade of it verifies against the pinned key alone: a release signed by another key is refused, and a key is only replaced by remove, then add again.
  • It must describe itself as a module (--link-describe), never a program of its own, before it's installed, and its name can't be one of Link's modules'.
  • An outside module runs as you, outside any sandbox, like any program you install: the harness module asks it what to run, and lnk asks its version. Link's sandbox confines the harness it installs and runs, not the adapter's own answers.
  • On a box, lnk agent move adds it with --key, the key this computer pinned, so the box trusts nothing the release offers.
  • lnk upgrade, and add again (as a box does on every move), take its latest release and install it only when it is newer than the one installed; one whose version, or the installed one's, can't be compared is refused. A release whose signed VERSION file says it is no newer is neither downloaded nor run.
  • A SHA256SUMS line naming anything but letters, digits, ., _ and - is dropped, so the names a release not yet trusted lists reach the terminal only as plain text.

Uninstall

An uninstall deletes only inside Link's two folders, and shows what goes before it asks.

  • lnk uninstall deletes only inside ~/.lnk and ~/Link. A path a module names outside them, with .. or relative, is left out. A path whose folder leads out of them through a link is left out too.
  • Before asking, it lists every path each picked part deletes.
  • Before asking, it runs only Link's own modules. Another program named lnk-* in lnk's folder is listed, then told to uninstall and removed once you say yes. It's never asked to delete a part.
  • lnk module remove keeps a module that fails to stop what it runs, and shows what the module said, so its services never outlive the program that stops them.

Releases and updates

How a release is signed, who checks it, and what keeps an older one from coming back.

Signing

Every release's SHA256SUMS is signed by Link's signer, link (ssh-keygen -Y sign, namespace link-release). Its public line is in scripts/release/link-signers. It is built into lnk and embedded in install.sh. Repository checks keep those public-key copies aligned. No release carries the signer's secret.

Who checks

lnk upgrade and the default install.sh path require a valid signature, so controlling the releases repository or its token alone does not authorize a new program.

  • lnk upgrade uses its own SSHSIG verifier, link_core::release.
  • lnk upgrade --check, which lnk up and lnk agent show start in the background at most once a day, reads the latest release's VERSION only through its signed SHA256SUMS, so a notice can't name a version Link didn't release. It asks the releases host for three small files and sends nothing but lnk's version, as its user agent; LNK_UPDATE_NOTICE=off turns it off.
  • install.sh uses ssh-keygen, and refuses to run without it unless LNK_INSECURE=1.

The installer

curl -fsSL https://local.link/install.sh | sh fetches the bootstrap over HTTPS. Its source is core/cli/install.sh, and it checks the downloaded release against its embedded signer. The first script fetched still relies on its host's HTTPS and trusted build.

Downgrades

No signed release older than the one installed is put back, unless you ask for that version.

  • lnk upgrade refuses a release older than itself unless that version is requested, and refuses a version it can't parse.
  • lnk upgrade <version> installs only that version: the lnk it downloads must report it, so an older signed release moved under the tag is refused.
  • Releases carry a VERSION file inside the signed SHA256SUMS. A release without one is refused by lnk upgrade, lnk box create and install.sh alike (lnk module add asks for its own version).
  • lnk upgrade checks the VERSION file against the version asked for and the lnk it holds; lnk module add checks it against its own version; lnk box create checks it as lnk upgrade does, the latest no older than a released lnk making the box, and has the box install the version it checked.
  • install.sh checks the VERSION file against LNK_VERSION, and the lnk it installs must report that version. A stamped minimum version also refuses an older latest.
  • lnk module add also runs each module's --version, which must match, and must answer when a release has no VERSION file.

Download limits

Downloads give up after 15 s connecting or 60 s without data. They stop past 64 KiB for SHA256SUMS, its signature and VERSION, and past 200 MiB for an archive.

CI

The release's workflows keep the signer away from third-party code:

  • Workflow actions are pinned to commit hashes.
  • Jobs that run third-party actions get no secrets.
  • Signing and publishing run in separate jobs that use only actions/*.
  • Default permissions are read-only.
  • A publish fails if the signature doesn't verify against scripts/release/link-signers.

Gaps

What these checks don't cover.

  • The first lnk module add --url <url> trusts whatever key the repository serves that day; nothing in lnk vouches for an outside module's key.
  • An outside module can go back to an older release signed by the same key only if its maker publishes it as the latest; lnk upgrade refuses a version older than the installed one.
  • An outside module's release without a VERSION file, or whose VERSION says newer than its program does, has its program run (contract, then --version) before it's refused as older. It is signed by the pinned key, so this runs nothing its maker couldn't run already.
  • Link's signer is a GitHub Actions secret; see Known limitations.
  • A source checkout's install.sh has no version floor, so latest pointed at an older signed release with a VERSION file is installed. Website builds and sealed releases stamp their own minimum version; the first script fetched still relies on its host's HTTPS and trusted build.