Offline bundles and slices
Carrying a lock file's packages to another machine, and static repositories
Some machines cannot reach your hub: a build server behind an air gap, a customer's network, a laptop on a plane. Some people should receive a few of your packages and nothing else. For both, Gritpack moves an exact, already resolved set of packages, the ones a lock file names, in a signed form the receiver can check. This chapter covers the two shapes that takes: a bundle, one signed file you carry across, and a slice, a small signed repository of plain files that needs no server.
What you will be able to do
- pack a project's locked packages into one signed bundle file;
- check a bundle you were given, and refuse one signed by the wrong key;
- install a project on a machine with no network, from a bundle;
- publish a bundle as a static repository, update it, and let others fetch from it safely;
- move a bundle's packages onto another hub in one transaction.
The idea: move what the lock says, nothing more
A bundle does not resolve versions, build anything, or run package code. It
carries exactly the package files your gritpack.lock names, taken from your
download cache and checked against the digests in the lock, plus a signature
saying who assembled it. The receiver checks the signature and every file
before anything is used, and installs from the same lock you have.
So the starting point is a project that has been synced normally, here one that
depends on @bea/report:
$ gritpack list
@ada/greet 0.2.0 dialect=c/c23 transitive source=https://packages.example.com:443 dependencies=-
@bea/core 0.1.0 dialect=c/c23 transitive source=https://packages.example.com:443 dependencies=-
@bea/fmt 0.1.0 dialect=c/c23 transitive source=https://packages.example.com:443 dependencies=@bea/core
@bea/report 0.1.0 dialect=c/c23 direct source=https://packages.example.com:443 dependencies=@ada/greet,@bea/core,@bea/fmt
Packages that are still editable workspace members cannot go into a bundle; publish them first (Releasing a workspace).
A key to sign with
A bundle is signed with a key you keep for that purpose. Make a seed and its public key once (Evidence and receipts explains both):
openssl rand -out bundle.seed 32
chmod 600 bundle.seed
gritpack evidence public-key --signing-seed bundle.seed --output bundle-public.key
Keep bundle.seed in your secret store. Give bundle-public.key to whoever
will receive your bundles, over a channel they trust: that file is how they
know a bundle came from you.
Making a bundle
From the project directory:
$ gritpack bundle export --output release.gritbundle --signing-seed bundle.seed --actor bea@example.com
bundle=a0df3ba662a218d232421b44c537b1da35ed104b847db226bca6a1e3123ecf5a packages=4 objects=5 bytes=7768 roots=@bea/report actor=bea@example.com signers=4b03790910e059ca675622bc0db2721d130fa483cf79cc1f07d43211005eb3e0
--locknames another lock file; the default isgritpack.lockhere.--actorrecords who made the bundle, in words that mean something to you: an email, a service name.- The packages come from your cache. If one is missing, run
gritpack syncfirst.
A bundle can also carry evidence, so the receiver can check more than your
signature: --root and --lifecycle for a hub's saved keys and checkpoint,
--evidence for signed records, and --consumer for any JSON file of your own
that should travel with it unchanged. --destination-repository binds the
bundle to one destination, so it cannot be published anywhere else by mistake.
gritpack bundle export --output release.gritbundle \
--signing-seed bundle.seed --actor bea@example.com \
--root root.json --lifecycle checkpoint.json
Checking a bundle
bundle inspect shows what a bundle holds and checks that it is well formed,
but deliberately says nothing about who made it:
$ gritpack bundle inspect release.gritbundle
bundle=a0df3ba662a218d232421b44c537b1da35ed104b847db226bca6a1e3123ecf5a packages=4 objects=5 bytes=7768 roots=@bea/report actor=bea@example.com signers=4b03790910e059ca675622bc0db2721d130fa483cf79cc1f07d43211005eb3e0
bundle verify is the real check. You name the public keys you trust:
$ gritpack bundle verify release.gritbundle --trusted-key bundle-public.key
verified bundle=a0df3ba662a218d232421b44c537b1da35ed104b847db226bca6a1e3123ecf5a packages=4 objects=5 roots=@bea/report signers=4b03790910e059ca675622bc0db2721d130fa483cf79cc1f07d43211005eb3e0 lifecycle_expired=0 offline=false
It checked the signature, re-read the lock inside the bundle, matched every package file to it, and checked any evidence carried along. A bundle signed by any other key is refused:
$ gritpack bundle verify release.gritbundle --trusted-key other-public.key
signed envelope does not meet signature threshold 1
Exit code 7, "integrity". Repeat --trusted-key to trust several keys, and
--threshold to require that more than one of them signed.
Installing on a machine with no network
On the receiving machine you need three things: the bundle, the project's
gritpack.toml and gritpack.lock, and the public key. Copy them across. An
offline install before importing fails, because the packages are not there yet:
Gritpack names the first package it cannot find in the local cache, and exits
with code 5, "not found".
Import the bundle into the cache:
$ gritpack bundle import release.gritbundle --trusted-key bundle-public.key
imported bundle=a0df3ba662a218d232421b44c537b1da35ed104b847db226bca6a1e3123ecf5a packages=4 changed=4 unchanged=0 signers=4b03790910e059ca675622bc0db2721d130fa483cf79cc1f07d43211005eb3e0 lifecycle_expired=0 offline=false
Import verifies everything first, then copies the package files into the
download cache. It installs nothing and activates nothing. If any check fails,
nothing is imported. Importing the same bundle again changes nothing
(changed=0 unchanged=4).
Now install, without the network:
$ gritpack sync --offline
synchronized 4 packages into ./packages status=changed
$ gritpack verify
verified 4 packages and 11 files universe=897a8c7d0b1e04aae0fe32bf58161860431abad2ce4d2fc494aaa4930d65a0a6
--offline uses only the lock and the cache: no login, no hub. The result is
the same set of files, byte for byte, that sync gave on the connected machine.
Careful. A bundle that carries a lifecycle checkpoint is checked for freshness, and checkpoints expire after a week. On a machine that is truly disconnected, pass
--offlinetobundle verifyandbundle import: an expired checkpoint is then reported as out of date (lifecycle_expired) instead of refused. Every other check still applies.
Static slices: a repository made of plain files
A bundle suits one delivery. When someone needs to fetch your packages again and again, give them a slice: a directory of plain files, made from a bundle, signed, and updated one numbered generation at a time. It needs no database and no Gritpack server; any directory, file share, or web server that serves files over HTTPS will do.
A slice has its own identity and its own key, separate from the bundle key:
- a repository UUID that names the slice for good (make one with
uuidgen); - a destination seed and public key, made the same way as the bundle key.
openssl rand -out slice.seed 32
gritpack evidence public-key --signing-seed slice.seed --output slice-public.key
Plan, verify, promote
Publishing to a slice is three steps, so you can look before anything is written. Plan checks the bundle and the destination and changes nothing:
$ gritpack slice plan --bundle release.gritbundle --bundle-key bundle-public.key \
--destination /srv/slices/customer-a --repository 7d3c9a52-0b7e-4c1e-9a55-2f1d5c6e8a10 \
--destination-key slice-public.key --actor bea@example.com --output slice-plan.json
planned slice plan=f3b5b56c212db6b464c419786a5aa7cbcda43f0da871bd12f2e10ecb97711c2d repository=7d3c9a52-0b7e-4c1e-9a55-2f1d5c6e8a10 bundle=a0df3ba662a218d232421b44c537b1da35ed104b847db226bca6a1e3123ecf5a packages=4 previous=none
previous=none: the destination is empty, and this will be generation 1.
Verify re-checks the plan, the bundle, and that the destination has not
changed since:
gritpack slice verify --plan slice-plan.json --bundle release.gritbundle \
--bundle-key bundle-public.key --destination /srv/slices/customer-a \
--repository 7d3c9a52-0b7e-4c1e-9a55-2f1d5c6e8a10 --destination-key slice-public.key
Promote writes it, signed with the destination seed:
$ gritpack slice promote --plan slice-plan.json --bundle release.gritbundle --bundle-key bundle-public.key \
--destination /srv/slices/customer-a --repository 7d3c9a52-0b7e-4c1e-9a55-2f1d5c6e8a10 \
--destination-key slice-public.key --signing-seed slice.seed
promoted repository=7d3c9a52-0b7e-4c1e-9a55-2f1d5c6e8a10 generation=1 digest=2f0fd203227ef2b6cf95176ac566b7077f8fcb045777eb2e17a2105b9cd0be8a receipt=52907facb0fca22985910db7a05dd612f765daa31247f04fff0ed2c9bd94a23b changed=8 unchanged=0
The directory now holds objects/ (the package files, by digest), bundles/,
generations/, promotions/ (a signed record of each promotion) and
current.envelope.json, the signed pointer to the newest generation. Promotion
writes everything else first and replaces that pointer last, so a reader never
sees half a generation. slice status checks what is visible now:
$ gritpack slice status --destination /srv/slices/customer-a --repository 7d3c9a52-0b7e-4c1e-9a55-2f1d5c6e8a10 --destination-key slice-public.key
repository=7d3c9a52-0b7e-4c1e-9a55-2f1d5c6e8a10 generation=1 digest=2f0fd203227ef2b6cf95176ac566b7077f8fcb045777eb2e17a2105b9cd0be8a bundle=a0df3ba662a218d232421b44c537b1da35ed104b847db226bca6a1e3123ecf5a packages=4 expires_at=1794987106 offline=false
A generation is valid for a day by default (--lifetime-seconds on promote),
so a slice that stops being updated is noticed rather than trusted forever.
The next generation
For the next delivery, export a new bundle and plan from the slice as it is now
with slice reconcile. Like plan, it only writes a plan file:
$ gritpack slice reconcile --bundle release3.gritbundle --bundle-key bundle-public.key \
--destination /srv/slices/customer-a --repository 7d3c9a52-0b7e-4c1e-9a55-2f1d5c6e8a10 \
--destination-key slice-public.key --actor bea@example.com --output slice-plan-2.json
planned slice plan=a96704b79ceb271731d0b9250941d903f9732f02ae92c308c880aa7cf44a52f3 repository=7d3c9a52-0b7e-4c1e-9a55-2f1d5c6e8a10 bundle=087492966f6d592ba9a2cc2eaa70dce5fe8d50a758e146fc1245447d539329ce packages=4 previous=1
Promote that plan as before and the slice moves to generation 2. Files already
present are reused (changed=4 unchanged=4).
The steps protect each other. Promoting an old plan after the slice has moved
on is refused (distribution slice destination changed after planning, exit
code 6), and a bundle made with --destination-repository for somewhere else is
refused at planning (bundle closure is bound to another destination).
Fetching from a slice
The receiver pins the slice's identity and key, and fetches into their cache:
$ gritpack slice acquire --from /srv/slices/customer-a --repository 7d3c9a52-0b7e-4c1e-9a55-2f1d5c6e8a10 --trusted-key slice-public.key --save-state slice-state.json
acquired repository=7d3c9a52-0b7e-4c1e-9a55-2f1d5c6e8a10 generation=1 packages=4 changed=4 unchanged=0 offline=false expired=false signers=5384e4f20a5fd12a3a90f206eb5034ce7bdb4b3d5a82feb35941991688385651
Then gritpack sync --offline installs from the cache, as with a bundle.
--from takes an absolute directory (a relative path is refused) or an
https:// URL without credentials in it. For a web server with a private
certificate authority, add --ca with its certificate.
Keep the state file and pass it back each time:
gritpack slice acquire --from https://packages.customer.example/slice/ \
--repository 7d3c9a52-0b7e-4c1e-9a55-2f1d5c6e8a10 --trusted-key slice-public.key \
--state slice-state.json --save-state slice-state.json
With it, Gritpack refuses a slice that has gone backwards, for example a copy restored from an old backup:
$ gritpack slice acquire --from /mnt/old-copy --repository 7d3c9a52-0b7e-4c1e-9a55-2f1d5c6e8a10 --trusted-key slice-public.key --state slice-state.json
distribution slice generation is older than the highest accepted generation
It also refuses a slice whose repository UUID is not the one you pinned, files
that do not match their digests, redirects and plain http://. An expired
generation is refused too, unless you pass --offline, which accepts it and
reports expired=true.
Careful. A slice has no login. Anyone who can read the files can read the packages. The signature proves where they came from, not who may see them, so serve a slice only on a network its readers are meant to have. Put a slice on the public internet only when every package in it is meant to be public.
Under the hood. Gritpack 1.2.63 writes slices to a directory. To serve one from object storage or a web server, copy the directory there with your usual tools, and upload
current.envelope.jsonlast, so readers never see a pointer to files that are not there yet.
Moving a bundle onto another hub
When the receiver runs a hub rather than a directory, for example a separate
private hub for a customer, slice promote-live publishes a bundle's packages
to it in one all-or-nothing publication, with the same checks as
gritpack publish. It uses an ordinary login for the receiving hub, and the
hub's own ownership rules and licence rules apply:
$ gritpack slice promote-live --bundle customer.gritbundle --bundle-key bundle-public.key --repository 550e8400-e29b-41d4-a716-446655440000 --profile customer --dry-run
planned live slice repository=550e8400-e29b-41d4-a716-446655440000 bundle=f5a79842a687fcd9e167d99bbaab04ad6fe9ce0ceccb37052f663b26aeb7d080 packages=4 plan=sha256:43dfe1c8281f263c92ea4867a99c04a1bac36e267351ad0f5649a1ff48c23375
--repository must be the receiving hub's UUID (gritpack evidence root shows
it), so a bundle cannot land on the wrong hub. Without --dry-run it publishes,
and --format json returns a report with the hub's signed receipt.
What just happened
- A bundle is one signed file holding exactly the packages a lock names.
bundle verifychecks who signed it and every file;bundle importfills the cache;sync --offlineinstalls with no network. - A slice is a signed, numbered repository of plain files made from bundles, planned, verified and promoted one generation at a time.
- Receivers pin the slice's identity and key, and a saved state stops anyone from serving them an older generation.
slice promote-livemoves a bundle onto another hub as one transaction.
You can stop here
If you deliver packages across a network boundary, to an air-gapped machine or to another organisation, you now have the full path. Everyone else can skip this chapter until they need it.
Next
- Scripting with JSON: every command here takes
--json, which makes bundles and slices easy to automate. - Optional: Evidence and receipts, for the hub evidence a bundle can carry.