Skip to content

Commit 1ff2566

Browse files
CopilotCopilot
authored
Add NLBoot integration docs and validation
Adds NLBoot integration documentation, adapted-output fixture, Makefile validation, and repo maturity metadata. Closes #11.
1 parent cfa419c commit 1ff2566

5 files changed

Lines changed: 251 additions & 0 deletions

File tree

‎.gitignore‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
__pycache__/
2+
*.pyc
3+
*.pyo
4+
*.pyd
5+
.pytest_cache/
6+
*.egg-info/
7+
dist/
8+
build/
9+
.venv/
10+
venv/

‎Makefile‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
.PHONY: validate test
2+
3+
validate:
4+
python src/sourceos_boot/validate_boot_release_set.py examples/boot-release-set.example.json
5+
PYTHONPATH=src python -m sourceos_boot.cli adapt-nlboot \
6+
--manifest examples/nlboot/manifest.json \
7+
--token examples/nlboot/token.json \
8+
--device-id device-demo-m2 \
9+
--public-key-fingerprint sha256:0000000000000000000000000000000000000000000000000000000000000000 \
10+
--platform apple-silicon \
11+
--nonce nonce-demo-1 \
12+
--correlation-id corr-demo-1
13+
14+
test:
15+
python -m pytest

‎docs/NLBOOT_INTEGRATION.md‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
# NLBoot Integration Guide
2+
3+
`sourceos-boot` adapts the [`SociOS-Linux/nlboot`](https://github.com/SociOS-Linux/nlboot) safe planning protocol into SourceOS BootReleaseSet contracts and Prophet Lattice evidence envelopes.
4+
5+
## What nlboot provides
6+
7+
The nlboot reference implementation defines:
8+
9+
| Object | Description |
10+
|---|---|
11+
| `SignedBootManifest` | Signed artifact manifest with kernel/initrd/rootfs refs, boot mode, and crypto profile |
12+
| `EnrollmentToken` | One-time, time-bound, boot-mode-scoped authorization token |
13+
| `BootPlan` | Side-effect-free plan record with `execute=false` and required proof gates |
14+
15+
nlboot enforces RSA-PSS/SHA-256 manifest verification and FIPS-140-3-compatible crypto profile markers before emitting any plan.
16+
17+
## Integration stance
18+
19+
`sourceos-boot` does not fork the nlboot protocol vocabulary. Instead:
20+
21+
- nlboot remains the safe planner and reference protocol lane.
22+
- `sourceos-boot` adapts nlboot manifest/token/plan output into BootReleaseSet patches, BootAuthorization records, and evidence envelopes.
23+
- BootReleaseSet is the handoff object for Prophet Platform, SourceOS, and Lattice.
24+
25+
See [`NLBOOT_COMPATIBILITY.md`](NLBOOT_COMPATIBILITY.md) for the field-level mapping.
26+
27+
## Adapter flow
28+
29+
The `SourceOSBootAdapter` models a five-stage, side-effect-free handshake:
30+
31+
```
32+
announce → authorize → fetch manifest → verify → emit evidence
33+
```
34+
35+
1. **Announce** — build a `SourceOSBootAnnounce` payload from a `DeviceClaim`.
36+
2. **Authorize** — convert an nlboot `EnrollmentToken` document into a `BootAuthorization`.
37+
3. **Fetch** — build a `SourceOSBootFetchRequest` using the `BootAuthorization`.
38+
4. **Verify** — apply the nlboot manifest to produce a `BootReleaseSet` patch.
39+
5. **Evidence** — emit a `BootEvidence` envelope covering device claim, manifest hash, channel, boot mode, and verification result.
40+
41+
All operations are pure and side-effect-free. No disk writes, kexec calls, or network requests are performed.
42+
43+
## Boot mode mapping
44+
45+
| nlboot `boot_mode` | SourceOS channel | SourceOS action |
46+
|---|---|---|
47+
| `installer` | `installer` | `install` |
48+
| `recovery` | `recovery` | `repair` |
49+
| `ephemeral` | `live` | `kexec` |
50+
| `bootstrap` | `live` | `enroll` |
51+
52+
## CLI usage
53+
54+
```bash
55+
PYTHONPATH=src python -m sourceos_boot.cli adapt-nlboot \
56+
--manifest examples/nlboot/manifest.json \
57+
--token examples/nlboot/token.json \
58+
--device-id device-demo-m2 \
59+
--public-key-fingerprint sha256:0000000000000000000000000000000000000000000000000000000000000000 \
60+
--platform apple-silicon \
61+
--nonce nonce-demo-1 \
62+
--correlation-id corr-demo-1
63+
```
64+
65+
The command emits an `NlbootAdapterOutput` JSON object to stdout. See
66+
`examples/nlboot/adapted-output.example.json` for the expected structure.
67+
68+
## Fixture files
69+
70+
| File | Description |
71+
|---|---|
72+
| `examples/nlboot/manifest.json` | Minimal nlboot `SignedBootManifest` fixture |
73+
| `examples/nlboot/token.json` | Minimal nlboot `EnrollmentToken` fixture |
74+
| `examples/nlboot/adapted-output.example.json` | Expected `NlbootAdapterOutput` for the above fixtures |
75+
76+
## Validation
77+
78+
```bash
79+
make validate # validate BootReleaseSet example and exercise the nlboot adapter
80+
make test # run pytest suite
81+
```
82+
83+
The CI workflow (`ci.yml`) also validates `examples/boot-release-set.example.json`
84+
and runs the full pytest suite on every push and pull request.
85+
86+
## Known gaps
87+
88+
- Real nlboot manifest signature verification (RSA-PSS/SHA-256) is not yet wired
89+
into this adapter; the adapter accepts a pre-verified manifest document.
90+
- Artifact fetch, SHA-256 check, and content-addressed cache are implemented in
91+
the Rust `nlboot-client` lane; the Python adapter here covers planning only.
92+
- Host mutation (kexec, install, rollback) remains disabled pending explicit
93+
platform adapter review. See `WORLD_CLASS_TARGETS.md` for the implementation path.
94+
95+
## References
96+
97+
- [`NLBOOT_COMPATIBILITY.md`](NLBOOT_COMPATIBILITY.md) — detailed field mapping
98+
- [`INTEGRATION.md`](INTEGRATION.md) — upstream/downstream dependency contract
99+
- [`WORLD_CLASS_TARGETS.md`](WORLD_CLASS_TARGETS.md) — implementation roadmap
100+
- [`SociOS-Linux/nlboot`](https://github.com/SociOS-Linux/nlboot) — upstream safe planner
101+
- [`src/sourceos_boot/adapter.py`](../src/sourceos_boot/adapter.py) — adapter implementation

‎examples/nlboot/adapted-output.example.json‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
{
2+
"apiVersion": "sourceos.dev/v1",
3+
"kind": "NlbootAdapterOutput",
4+
"authorization": {
5+
"bootReleaseSetRef": "boot/demo",
6+
"correlationId": "corr-demo-1",
7+
"expiresAt": "2026-04-26T01:00:00Z",
8+
"tokenId": "token-demo-1"
9+
},
10+
"bootReleaseSetPatch": {
11+
"artifacts": [
12+
{
13+
"name": "kernel",
14+
"role": "kernel",
15+
"sha256": "0000000000000000000000000000000000000000000000000000000000000000",
16+
"uri": "https://example.invalid/kernel"
17+
},
18+
{
19+
"name": "initrd",
20+
"role": "initrd",
21+
"sha256": "0000000000000000000000000000000000000000000000000000000000000000",
22+
"uri": "https://example.invalid/initrd"
23+
},
24+
{
25+
"name": "rootfs",
26+
"role": "rootfs",
27+
"sha256": "0000000000000000000000000000000000000000000000000000000000000000",
28+
"uri": "https://example.invalid/rootfs"
29+
}
30+
],
31+
"channels": [
32+
"recovery"
33+
],
34+
"policy": {
35+
"allowedActions": [
36+
"announce",
37+
"enroll",
38+
"fetch",
39+
"verify",
40+
"repair",
41+
"attest"
42+
]
43+
},
44+
"provenance": {
45+
"attestations": [
46+
"slsa",
47+
"in-toto"
48+
],
49+
"builderId": "trusted-key-1",
50+
"sourceRefs": [
51+
"manifest-demo-1"
52+
]
53+
},
54+
"releaseSetRef": "release/demo",
55+
"signature": {
56+
"bundleRef": "urn:srcos:signature:demo",
57+
"digest": "sha256:0000000000000000000000000000000000000000000000000000000000000000",
58+
"type": "x509"
59+
}
60+
},
61+
"evidence": {
62+
"bootMode": "recovery",
63+
"correlationId": "corr-demo-1",
64+
"deviceId": "device-demo-m2",
65+
"manifestHash": "sha256:b5014e848fc8ce3acd28a7cc8c2435340bf3871647d298bec102fb7dbe737e1a",
66+
"reports": [
67+
"device-claim",
68+
"manifest-hash",
69+
"verification-result",
70+
"selected-channel",
71+
"boot-mode"
72+
],
73+
"selectedChannel": "recovery",
74+
"verificationResult": "pass"
75+
}
76+
}

‎repo.maturity.yaml‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
schemaVersion: repo-maturity.v1
2+
repository: SourceOS-Linux/sourceos-boot
3+
plane: sourceos-carry
4+
status: active
5+
canonicality: implementation
6+
owners:
7+
- SourceOS-Linux
8+
maturity:
9+
level: M2
10+
targetLevel: M3
11+
evidence:
12+
- README.md describes the BootReleaseSet model and boot/recovery surface.
13+
- schemas/boot-release-set.schema.json is the BootReleaseSet v1 contract.
14+
- examples/boot-release-set.example.json is a minimal valid fixture.
15+
- examples/nlboot/ contains nlboot manifest, token, and adapted-output fixtures.
16+
- src/sourceos_boot/adapter.py implements the nlboot-to-BootReleaseSet adapter.
17+
- src/sourceos_boot/control_plane.py implements the control-plane boot plan builder.
18+
- make validate exercises schema validation and the nlboot adapter CLI path.
19+
- python -m pytest passes all tests.
20+
validation:
21+
commands:
22+
- make validate
23+
- python -m pytest
24+
ciRequired: true
25+
lastKnownStatus: passing
26+
integrations:
27+
- repository: SociOS-Linux/nlboot
28+
relationship: upstream safe planner; sourceos-boot adapts nlboot manifest/token/plan into BootReleaseSet and evidence contracts
29+
required: true
30+
- repository: SourceOS-Linux/sourceos-spec
31+
relationship: should consume normative BootReleaseSet, ReleaseSet, TokenDoor, and Fingerprint schemas once published
32+
required: true
33+
- repository: SocioProphet/prophet-platform
34+
relationship: downstream release service and control-plane UI consumer of BootReleaseSet artifacts
35+
required: false
36+
- repository: SocioProphet/lattice-forge
37+
relationship: downstream runtime/image/kernel artifact producer referenced by BootReleaseSet
38+
required: false
39+
- repository: SocioProphet/agentplane
40+
relationship: downstream agent-plane recovery and runtime repair consumer
41+
required: false
42+
nextActions:
43+
- Wire nlboot RSA-PSS/SHA-256 manifest signature verification into the adapter.
44+
- Add Apple Silicon M2 platform adaptation layer (PAL) design notes and stubs.
45+
- Add UEFI/iPXE PAL design notes for PC/Purism class hardware.
46+
- Align BootReleaseSet v1 with sourceos-spec once shared schemas land.
47+
- Add enrollment-token exchange stub with control-plane endpoint.
48+
- Add artifact digest verification and content-addressed cache path.
49+
- Emit evidence records from the boot/recovery execution boundary.

0 commit comments

Comments
 (0)