DriverKit — a Windows driver updater built on Snappy Driver Installer's packs
=============================================================================

  Version   0.1.3
  Licence   GPL-3.0-or-later. Source: this build was made from the DriverKit
            workspace; the driver packs are SDIO's and carry their own vendor
            terms.
  Mascot    A kit — a young fox — with a wrench. Hence the name.

RUNNING IT
----------
Unzip this folder anywhere and run DriverKit.exe.

Windows will ask for administrator rights before it starts. Installing a
driver needs them, and asking at the start beats failing at the last step of
a run you have already waited for.

The first run downloads the driver catalogue — about 23 MB, over BitTorrent,
usually a couple of minutes. It names each stage as it goes. After that it
opens straight onto the list; the catalogue is only re-checked once a day,
and that happens behind the list rather than in front of it.

WHAT IT WRITES
--------------
Everything goes in a "data" folder beside the exe:

  data/SDIO_Update.torrent     the catalogue
  data/SDI_Update.torrent      SDI's, used only to find packs faster
  data/sdio/indexes/           what drivers exist (~23 MB)
  data/sdio/drivers/           only the packs you actually chose
  data/sdi/                    staging, emptied after each download
  data/machine-index.dkmi      the list built for this machine, so the
                               second launch is instant
  data/trackers.txt            extra torrent trackers, refreshed daily
  data/work/                   drivers unpacked ready to install

Nothing goes into %APPDATA%, Program Files, or the registry. There is no
installer and no uninstaller: delete the folder.

EDITIONS
--------
Three downloads, same app:

  DriverKit-x.y.z-win64.zip            the app. Needs the internet.
  DriverKit-x.y.z-win64-wired.zip      + every Ethernet driver pack
  DriverKit-x.y.z-win64-wireless.zip   + the Wi-Fi pack as well

The last two exist for the machine that cannot download a network driver
because it has no working network driver. Everything they need is already in
the data folder, so a machine with no connection at all can install its own
Ethernet or Wi-Fi driver and then use the ordinary app for the rest.

If you are reading this on a working machine, the plain edition is the one
you want; the packs it needs are a few dozen megabytes each, fetched when you
tick them.

SETTINGS
--------
"Settings" has the handful of things worth changing: download speed, how fast
to share back, whether to share at all, the language, and whether to look for
a new version of DriverKit. They are kept in data/settings.txt, which can be
edited by hand.

If your network blocks BitTorrent — some company and campus networks do — the
same file takes an HTTP mirror of SDIO's files:

  http_mirror = https://example.com/sdio/
  prefer_http = yes

Nothing is trusted about a mirror. Every byte fetched over HTTP is checked
against the piece hashes in SDIO's own catalogue, which came over TLS from
SDIO, and anything that does not match is thrown away rather than installed.

LANGUAGES
---------
DriverKit speaks fourteen languages and follows Windows by default. Pick one
in Settings, or set it by hand:

  language = de

en, de, fr, es, pt, it, pl, ru, uk, tr, ja, ko, vi, id. Anything else falls
back to English, one string at a time — a language that is only part done is
part done, never blank.

The translations are ours and they are not perfect. To fix one, or to add a
language that is not here, put a file beside the exe:

  data/lang/cs.txt      cs = the language code
  headline-uptodate = Vse je aktualni

Only the lines you write are changed; everything else stays as shipped. An
update never touches data/lang, so a translation you wrote survives one.
Corrections are welcome — send the file.

UPDATING DRIVERKIT ITSELF
-------------------------
Once a day, in the background, DriverKit asks whether a newer version of
itself has been published, and says so if there is one. Nothing is downloaded
or installed until you press the button. "Check for updates" in Settings asks
immediately. To switch it off:

  update_check = no

What arrives is checked before it is allowed to run. The release is described
by a manifest signed with a key that has never been on the machine that
publishes the website, so taking over the website is not enough to push a
fake update — key id 664c97da009f1b1c, also printed in the source README.
Each file is then checked against the SHA-256 in that signed manifest.

The update replaces DriverKit.exe, driverkit-cli.exe and this README, and
nothing else. Your driver packs, settings and translations in data/ are left
exactly where they are: that is the whole difference between an update and a
reinstall.

The previous DriverKit.exe is kept beside the new one as DriverKit.exe.old
until the next start, so a bad update can be undone by hand. If the folder
cannot be written to — unzipped into Program Files, or on a read-only stick —
DriverKit says so and points at the download instead of failing halfway.

WHERE THE PACKS COME FROM
-------------------------
The catalogue — the list of what drivers exist and which device each one is
for — always comes from SDIO. That never changes and nothing else is ever
read in its place.

The packs themselves are a different question. Most of them are published
byte for byte identically by SDI, the older project SDIO was forked from,
whose torrent ships inside a tool far more people leave running; its swarm is
around twenty times the size. So a pack SDI also has is fetched from there,
and it is kept only if it hashes to what SDIO's catalogue says it should be.
A pack that does not match is thrown away and fetched from SDIO instead.

This is the same rule the HTTP mirrors follow: where bytes come from is not a
question of trust, because the bytes are checked. Set

  sdi_swarm = no

in data/settings.txt for a machine that should talk to SDIO's swarm and
nothing else.

The 36 packs SDIO has built since SDI's last release — the newer Intel and
NVIDIA display packs among them — exist only in SDIO's torrent and always
come from there.

Pressing "Check again" always asks SDIO for a new catalogue, however
recently the last one was fetched — that is the button for "SDIO published
new packs today". The once-a-day reuse only applies to launches.

Sharing is on by default. The packs come from other people sharing them;
taking tens of gigabytes and giving nothing back degrades the swarm for
everyone who keeps it alive. Turning it off is your choice to make.

USING IT
--------
The list shows what can be updated. "Show all devices" adds everything else
this machine has, with the driver and version it is on now — that view is
read-only, because there is nothing to do to a device that is already on the
best driver available.

Ticked rows are ones where a newer driver looks like a genuine improvement.
Unticked rows with an amber note are offered but not recommended — usually
because Windows supplied the current driver and the vendor's may or may not
be better. Nothing is installed unless you tick it and press the button.

Drivers are never forced. If Windows decides the driver you have is a better
match, it keeps it and the row says so. That is the ranking working, not a
failure.

While a run is going, each row says what it is doing and which pack it is
waiting on, with the speed that pack is getting:

  Downloading DP_LAN_Realtek-XP_26040.7z · 96.0 MB/s · 61.0 MB of 118 MB

and the line above the list gives the combined speed and the time left for
everything still outstanding. Those two numbers differ because packs download
together: four rows at 100 MB/s each is 400 MB/s of connection in use, and
only the top line will tell you so.

The status line is blue while something is happening, green when a step went
well, grey when it did nothing, red when it failed. The row's fill and its
border take the same colour from the same decision, so they cannot disagree
about how a row is doing.

GRAPHICS DRIVERS
----------------
If a graphics driver is in the run, it is installed last, and while it goes in
the screen will go black for a few seconds. Windows is restarting the display
adapter; the desktop may come back at the wrong size until you restart. The
row says so while it happens.

Nothing has crashed and nothing needs rescuing. Do not turn the machine off
during it — that is the one thing that can genuinely leave a device without a
working driver.

The app draws its own window on the CPU rather than the GPU, so that it keeps
running through exactly this. It costs nothing you would notice on a list and
a button, and it means the app still works on a machine whose graphics driver
is the thing being fixed. `DriverKit.exe --gpu` opts back into GPU rendering
if you would rather; it will fall back on its own if the GPU cannot do it.

"Undo" appears after a run and puts back exactly the drivers this app
installed, one device at a time, whether or not System Restore is available.
On Windows Server it is the only undo there is — Server has no System
Restore, and the app says so rather than pretending.

It puts back whatever is still ticked. Every driver the run installed stays
ticked afterwards, so pressing it once reverses the whole run; untick the ones
that are fine and only the rest go back.

Some drivers cannot be put back, because there was no driver on the device
before the run and there is nothing to return to. Windows only answers that
when actually asked, so the button counts everything the run changed rather
than promising a smaller number it cannot know in advance. Once it has the
answer, the run says how many had nothing to go back to and stops offering
them.

"Details" shows what actually happened, in order. It is worth opening if
anything goes wrong.

WITHOUT THE WINDOW
------------------
driverkit-cli.exe does the same things from a command prompt:

  driverkit-cli check              scan and list what could be updated
  driverkit-cli check --refresh    check for a newer catalogue first
  driverkit-cli install 3 5        install those numbered drivers
  driverkit-cli rollback <id>      put a device back

KNOWN LIMITS IN THIS BUILD
--------------------------
- No public HTTP mirror of SDIO's files exists. The mechanism is here and
  works against any mirror you point it at, including one of your own, but
  SDIO's published web seed has been dead for some time, so out of the box
  the packs come from the swarm.
- The catalogue is authenticated by TLS and the torrent's piece hashes, which
  is SDIO's chain of trust rather than ours. The window says "SDIO catalogue"
  and never "signed", because those mean different things.
- A pack taken from SDI's swarm is proved against SDIO's piece hashes except
  for one piece at each end, which straddle the neighbouring files in SDIO's
  layout and cannot be hashed from the pack alone. Those bytes are covered by
  SDI's own hashes, delivered over TLS from sdi-tool.org, and by the archive's
  CRCs when it is unpacked. It is a smaller claim than the one made about the
  rest of the file, and it is written here rather than glossed over.
