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 andlnk upgradeinstall Link's modules only from a release whoseSHA256SUMSis signed by the keys built intolnk, and check each archive against it.lnk module addtakes the release oflnk'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, orlnk-code-toolfrom the signed release oflnk's own version. A source build requires the tool's executable to be available from the same checkout. install.shinstallslnkalone.- 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.
Modules from outside Link
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), itsSHA256SUMSsigned with that repository's own key in thelink-releasenamespace, and each archive checked against it. Link's keys never vouch for it.- The first
addtrusts 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. lnkpins the repository and the key in~/Link/Safe/settings.toml(600). Every lateraddandlnk upgradeof it verifies against the pinned key alone: a release signed by another key is refused, and a key is only replaced byremove, thenaddagain.- 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
lnkasks its version. Link's sandbox confines the harness it installs and runs, not the adapter's own answers. - On a box,
lnk agent moveadds it with--key, the key this computer pinned, so the box trusts nothing the release offers. lnk upgrade, andaddagain (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 signedVERSIONfile says it is no newer is neither downloaded nor run.- A
SHA256SUMSline 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 uninstalldeletes only inside~/.lnkand~/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-*inlnk's folder is listed, then told to uninstall and removed once you say yes. It's never asked to delete a part. lnk module removekeeps 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 upgradeuses its own SSHSIG verifier,link_core::release.lnk upgrade --check, whichlnk upandlnk agent showstart in the background at most once a day, reads the latest release'sVERSIONonly through its signedSHA256SUMS, so a notice can't name a version Link didn't release. It asks the releases host for three small files and sends nothing butlnk's version, as its user agent;LNK_UPDATE_NOTICE=offturns it off.install.shusesssh-keygen, and refuses to run without it unlessLNK_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 upgraderefuses 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: thelnkit downloads must report it, so an older signed release moved under the tag is refused.- Releases carry a
VERSIONfile inside the signedSHA256SUMS. A release without one is refused bylnk upgrade,lnk box createandinstall.shalike (lnk module addasks for its own version). lnk upgradechecks theVERSIONfile against the version asked for and thelnkit holds;lnk module addchecks it against its own version;lnk box createchecks it aslnk upgradedoes, the latest no older than a releasedlnkmaking the box, and has the box install the version it checked.install.shchecks theVERSIONfile againstLNK_VERSION, and thelnkit installs must report that version. A stamped minimum version also refuses an olderlatest.lnk module addalso runs each module's--version, which must match, and must answer when a release has noVERSIONfile.
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 inlnkvouches 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 upgraderefuses a version older than the installed one. - An outside module's release without a
VERSIONfile, or whoseVERSIONsays 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.shhas no version floor, solatestpointed at an older signed release with aVERSIONfile 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.