51 lines
2.8 KiB
Markdown
51 lines
2.8 KiB
Markdown
# Environment lock and draft
|
|
|
|
`plan-environment` accepts strict JSON `{ "lock": <Lock> }`, collects local
|
|
preflight observations itself, and emits a non-executable draft. It does not
|
|
accept caller-supplied host observations, download anything, run apt, configure
|
|
sources or start services.
|
|
|
|
Lock fields, all required:
|
|
|
|
- protocolVersion: 1.
|
|
- repository: exactly `https://download.docker.com/linux/ubuntu`.
|
|
- suite: jammy, noble or resolute; architecture: amd64 or arm64.
|
|
- releaseDigest: `sha256:` plus 64 lowercase hex digits, supplied by the caller.
|
|
- packages: exactly docker-ce, docker-ce-cli, containerd.io,
|
|
docker-buildx-plugin and docker-compose-plugin, once each.
|
|
- Each package has name, version, filename, digest and size. Version is explicit
|
|
digit-leading Debian-style syntax (optional numeric epoch), at most 128 bytes;
|
|
digest uses the above SHA-256 format; size is 1 through 512 MiB.
|
|
- Filename must equal
|
|
`dists/<suite>/pool/stable/<architecture>/<name>_<version-without-epoch>_<architecture>.deb`.
|
|
Encoded paths, absolute paths, alternate domains, query strings and traversal
|
|
are not accepted. docker-ce and docker-ce-cli must use the same version.
|
|
|
|
This is a deliberately limited Docker lock format, not a complete Debian version
|
|
parser. A Linux host's observed distribution/suite and architecture must match;
|
|
unknown observations remain blockers. On a non-Linux machine a syntactically
|
|
valid lock can be reviewed, but unsupported-platform blockers remain.
|
|
|
|
## Digests and remaining trust boundary
|
|
|
|
lockDigest binds Go JSON encoding of the validated Lock in struct/array order.
|
|
observationDigest binds Go JSON encoding of the collected Report. These are
|
|
content hashes, not signatures, stable host IDs, freshness tokens or authorization.
|
|
The local observation is not atomic and changes (including free disk space) can
|
|
change its hash. No writing consumer may treat it as an approved plan.
|
|
|
|
The draft returns requestedPackages, not a complete APT dependency transaction.
|
|
It never proposes automatic removal or upgrade of existing installations.
|
|
RepositoryAuthenticated and executable are always false. There is no signature
|
|
verification, Release-to-Packages-to-deb digest chain verification, metadata
|
|
freshness policy, artifact download, package dependency resolution, or installation
|
|
executor yet. Matching a URL allowlist and a caller-provided hash proves none of
|
|
those. No actual versions are recommended or locked from live metadata in this batch.
|
|
|
|
Blockers explicitly retain these gaps along with host/network/runtime checks.
|
|
Potential APT database changes, dependency changes, service starts and network
|
|
rule effects are reported. Exit 0 only means a draft was produced.
|
|
|
|
Reference for package names and repository layout:
|
|
[Docker Ubuntu installation](https://docs.docker.com/engine/install/ubuntu/).
|