The on-device client: .pkg & .pkg-inst

The client runs on the Spectrum itself as two ordinary dot commands. Splitting it in two keeps each half within the tight size limit classic esxDOS puts on a dot command, so the same pair works on a 48K machine with divMMC as well as on the Next.

• .pkg answers questions: what's installed, what's in the registry, what has an update.
• .pkg-inst changes things: it installs and updates packages, and refuses any file that fails signature verification (Rabin-Williams over SHA-256, checked on the Z80 itself).

Install in one line (ZX Spectrum Next)

On a Next with WiFi, the built-in .http command can fetch the installer for you:

.http get -h pkg.zx.in.net -u /install.bas -f install.bas
LOAD "install.bas": RUN

The installer downloads both dots, creates the folders, fetches and verifies the package index, and runs a first scan of your /dot folder.

Manual setup (classic machines, or no WiFi)

1. Copy PKG and PKG-INST into /dot on your SD card.
2. Run .pkg-inst setup. It creates the /ZXPKG folder, which holds the registry index, the download cache and the installed-package database.

.pkg (query)

• .pkg scan: CRCs every file in /DOT, identifies each one against the registry, and writes the installed-package database (/ZXPKG/INSTALL.DAT). Run it once after setup and again whenever you change /DOT by hand.
• .pkg (or .pkg status): a quick report from that database. Each managed package shows as "name vVER ok", or "update" when the registry has a newer version, followed by a count of unmanaged files.
• .pkg list: everything in the registry that your machine can run.
• .pkg search <term>: search the registry by name.
• .pkg info <name>: details for one package: version, command, machine, size, description.
• .pkg remove <name>: deletes /DOT/<name>. It refuses to remove the client itself.
• .pkg help: usage summary.

.pkg-inst (install & update)

• .pkg-inst update: fetches the registry index (or uses a staged copy), verifies the signature, and stores it as the trusted /ZXPKG/INDEX.DAT only if the signature is good.
• .pkg-inst install <name>: looks <name> up in the local index, fetches the signed file over WiFi (or takes a staged copy from /ZXPKG/CACHE), verifies it, and installs to /DOT only when the check passes. A tampered or corrupt file is refused.

Over WiFi the client talks to the registry's gopher server. The address lives in /ZXPKG/SERVER as a single "host port prefix" line and defaults to "gopher.zx.in.net 70 /pkg", so an ordinary Next needs no configuration at all. See "Installing packages over WiFi" for the full walkthrough. Without WiFi you can still install: stage files into /ZXPKG/CACHE from any other machine and run the same commands offline.

The trust model

Downloads are never trusted on their own. Everything the client installs, the index included, carries a signature from the registry, and .pkg-inst checks it on the Spectrum against a public key built into the binary before accepting anything. CRC-32C is only used for the fast identification pass in scan; installing always requires the signature. That is why plain HTTP, gopher and hand-copied SD cards are all acceptable transports: however a file gets mangled or swapped on the way, the check fails and the file is refused.