modelferry 0.1.0__tar.gz → 0.2.0__tar.gz

{modelferry-0.1.0 → modelferry-0.2.0}/.github/workflows/ci.yml

@@ -2,7 +2,7 @@ name: ci
 
 on:
   push:
-    branches: [main]
+    branches: ['**']
   pull_request:
 
 concurrency:
@@ -119,3 +119,33 @@ jobs:
           "$mf" unpack "$bundle" ./out
           test -f ./out/model.safetensors
           echo "wheel-install round trip OK"
+      - name: Signed pack + verify-signature round trip through the installed wheel (network)
+        env:
+          HF_HUB_DISABLE_PROGRESS_BARS: "1"
+        run: |
+          mf=/tmp/wenv/bin/modelferry
+          py=/tmp/wenv/bin/python
+          work="$(mktemp -d)"
+          cd "$work"
+          # Ephemeral keypair, job-only: never committed, never a repo secret. Uses
+          # the installed modelferry's own generate_keypair so producer and verifier
+          # agree on the key format.
+          "$py" -c "from modelferry.signing import Ed25519Signer; Ed25519Signer.generate_keypair('key.sec','key.pub')"
+          MODELFERRY_SIGNING_KEY="$PWD/key.sec" "$mf" pack hf-internal-testing/tiny-random-gpt2 --dest ./bs --chunk-size 200K --exclude "*.bin" --exclude "*.h5" --sign
+          bundle="$(echo ./bs/tiny-random-gpt2__*)"
+          echo "signed bundle: $bundle"
+          # The signed bundle carries a signing block and the detached signature.
+          test -f "$bundle/manifest.json.sig"
+          "$py" -c "import json,sys; s=json.loads(open(sys.argv[1]).read())['signing']; assert s['algorithm']=='ed25519' and s['signature_file']=='manifest.json.sig', s; print('signing block:', s)" "$bundle/manifest.json"
+          # Positive: the installed verifier reports VALID / exit 0.
+          out="$("$mf" verify-signature "$bundle" --public-key key.pub)"
+          echo "$out"
+          echo "$out" | grep -q '^VALID:'
+          # Negative: tamper a manifest value (still valid JSON) so the signature no
+          # longer covers these bytes; verify-signature must now exit non-zero. Proves
+          # the installed verifier actually verifies, not just prints VALID.
+          "$py" -c "import json,sys; from modelferry import manifest; p=sys.argv[1]; m=json.loads(open(p,'rb').read()); m['created_at']='1999-01-01T00:00:00Z'; open(p,'wb').write(manifest.serialize(m))" "$bundle/manifest.json"
+          if "$mf" verify-signature "$bundle" --public-key key.pub; then
+            echo "ERROR: verify-signature passed on a tampered manifest"; exit 1
+          fi
+          echo "signed wheel-install round trip OK (VALID, then tamper rejected)"

{modelferry-0.1.0 → modelferry-0.2.0}/.github/workflows/release.yml

@@ -90,10 +90,16 @@ jobs:
           GH_TOKEN: ${{ github.token }}
         run: |
           sha="$(sha256sum src/modelferry/offline.py | cut -d' ' -f1)"
-          # Lead with the CHANGELOG 0.1.0 section so the release page says what this
-          # is, then append the verifier block. The awk prints from the 0.1.0 header
-          # up to (not including) the link-reference lines at the end of the file.
-          awk '/^## \[0\.1\.0\]/{f=1} f && /^\[.*\]: /{exit} f{print}' CHANGELOG.md > notes.md
+          # Lead with this tag's CHANGELOG section so the release page says what this
+          # is, then append the verifier block. Extraction is tag-driven: it prints
+          # from the "## [<version>]" header for this exact tag up to (not including)
+          # the next "## [" section header or the link-reference lines at the end.
+          # The second awk trims trailing blank lines from the section, so the
+          # heredoc's one leading blank line is the single separator before Verifier.
+          ver="${GITHUB_REF_NAME#v}"
+          awk -v hdr="## [$ver]" 'index($0, hdr)==1 {f=1; print; next} f && (/^## \[/ || /^\[.*\]: /) {exit} f {print}' CHANGELOG.md \
+            | awk 'NF {last=NR} {line[NR]=$0} END {for (i=1; i<=last; i++) print line[i]}' > notes.md
+          test -s notes.md || { echo "no CHANGELOG section for $ver"; exit 1; }
           cat >> notes.md <<EOF
 
           ## Verifier

{modelferry-0.1.0 → modelferry-0.2.0}/.gitignore

@@ -24,6 +24,12 @@ htmlcov/
 # OS cruft
 .DS_Store
 
+# Secrets and signing key material (never committed; the repo is public)
+.env
+*.key
+sec.key
+*.pem
+
 # Local Claude Code state (personal, not shared)
 .claude/
 

modelferry-0.2.0/BUILD_PLAN.md

@@ -0,0 +1,254 @@
+# modelferry — Build Plan
+
+**The signed, compliant supply chain for open AI models running inside air-gapped and regulated networks.**
+
+This is the execution plan, handed to Claude Code one task at a time. Every phase lists numbered tasks, the files each touches, the key interfaces, named acceptance tests, and a definition of done. The acceptance tests are how "works offline" and "detects tampering" become things CI proves rather than things a README claims.
+
+## The one strategic decision that shapes everything
+
+We build the full platform, but we **ship each phase as a real release** instead of hiding five months of work on a long-lived branch. Same architecture, same destination. The difference is that every phase becomes a public milestone that ships, gets a launch post, and gathers feedback, rather than a held breath that decays.
+
+Why: a solo, side-of-desk build does not die from bad code. It dies in month three when nothing has shipped, no user has reacted, and the reason to keep going has quietly evaporated. Phased releases refuel that reason from outside your own head, and each release is also free market validation. If a phase lands and people care, that is the signal to build the next. If it lands flat, you learned it before sinking two more months in.
+
+Release map:
+
+- **0.2.0 — Signing** (Phase 0 here). Closes the authenticity gap the launch post named. 2–3 weeks. Ships.
+- **0.3.0 — Closure engine** (Phase 1). Bundles that actually run offline: wheels, image, model, one command. A large user-facing win and a second launch.
+- **0.4.0 — Registry preview** (Phase 2). The appliance that admits, versions, serves, audits. The thing that turns a design-partner conversation into a pilot.
+- **0.5.0 / 1.0 — Trust, compliance, delta, hardening** (Phases 3–5). SBOM, policy, CVE scanning, delta transport, clean-room install.
+
+A parallel, non-code track runs alongside Phase 0–1 and is as important as any task in it: **turn one real disconnected environment into a named design partner.** See Section 12.
+
+## How to drive Claude Code with this doc
+
+- Keep `BUILD_PLAN.md`, `RESOURCES.md`, `SPEC.md`, and `CLAUDE.md` in the repo root so the plan is always in context.
+- Give Claude Code one task at a time, addressed as "Phase N, Task M." Paste the task, its files, and its acceptance test, and ask for the test first, then the implementation.
+- Definition of done for every task: the named test passes, it runs under the air-gap harness where the task is an inside-gap step, and the checkbox here is ticked.
+- House rule, the most important constraint in this document: **the embedded offline verifier (`src/modelferry/offline.py`) stays standard-library only, forever, and verifies integrity only.** It never gains a crypto dependency, never verifies a signature itself, never grows toward hand-rolled cryptography. If a task would add a dependency to it, the task is wrong. A CI test enforces this mechanically (`test_offline_stdlib_lint`), proven to fail on a real non-stdlib import.
+
+## Repository and git workflow
+
+Work in the existing modelferry repo. The core primitives are extracted from code already validated on a real 65GB model, and the repo's history from packer to platform is part of the story a design partner and a YC reviewer read.
+
+- `main` is the launched CLI, currently at v0.1.0. It advances only at each release, by merging `develop`.
+- `develop` is the long-lived integration trunk, cut from `main` once. Every phase lands here.
+- `phase-*` branches are cut from `develop` and merged back when that phase's acceptance tests pass.
+- At each release milestone, `develop` merges to `main` and a version is tagged. Unlike the original "one merge at the end" plan, we merge and tag at every phase boundary, because shipping is the point.
+
+CI (secret scanner, unit tests, the stdlib guard, the harness) runs on all branches. Branch protection required on `main` and `develop`.
+
+The repo is public, so every branch is public the moment it is pushed. Anything that must stay private goes in a separate private repo, never a branch.
+
+## Secret hygiene (non-negotiable, because the repo is public)
+
+- Never commit a secret. Bots scrape public pushes within minutes, and git history keeps a secret even after a later commit deletes the file. Any secret that reaches a public branch is burned and must be rotated.
+- All config reads from environment variables. Commit a `.env.example` with placeholders only. `.gitignore` covers `.env`, `*.key`, `sec.key`, `*.pem`, and credential files.
+- A pre-commit secret scanner (gitleaks or trufflehog) blocks a commit containing a secret, and the same scan runs in CI.
+- **The minisign signing key never touches the repo.** It is generated and stored outside version control. A leaked signing key lets anyone forge a bundle the appliance trusts, which breaks the entire trust model.
+
+---
+
+## Phase 0 — Signing (ships as 0.2.0)
+
+**Goal:** a bundle's manifest is cryptographically signed on the connected side, and the signature is verifiable wherever a trusted key and a crypto library exist (pack-time self-check, and later the appliance), **without adding any dependency or crypto to the frozen offline.py integrity verifier.**
+
+**The load-bearing design decision, settled after reading the real offline.py:**
+
+Integrity and authenticity are separate concerns handled by separate tools.
+
+- `offline.py` answers "did these bytes arrive intact." That is **integrity**. It stays stdlib-only, runs on the bare air-gap host, and is unchanged except to accept schema 2 for integrity checking. No crypto ever enters it.
+- A new, separate tool answers "was this manifest signed by a key I trust." That is **authenticity**. It is allowed dependencies (PyNaCl, with the `minisign` binary as documented interop), and it runs where a key and a crypto library live: pack-time, and the appliance at admission.
+
+Why this is correct and not a dodge: the two questions have different trust models and different environments. The bare air-gap host verifies integrity against a manifest whose hash was approved out-of-band (exactly what MANIFEST.md already instructs). The signature protects that **approval chain** upstream; it is not part of the unpack step on the disconnected host. This is why offline.py barely moves.
+
+Branch: `phase-signing` off `develop`.
+
+- [x] **0.1** Branch setup and make the stdlib guard load-bearing. Cut `develop` from `main`, cut `phase-signing` from `develop`. Confirm `test_offline_stdlib_lint` asserts offline.py imports only stdlib, confirm CI runs on all branches, and prove the guard fails on a deliberate `import nacl` before reverting. *(Done: commit c122e20 broadened CI push trigger to all branches; guard proven to fail on real non-stdlib import.)*
+
+- [x] **0.2** The `Signer` interface. New `src/modelferry/signing.py`: `class Signer(Protocol)` with `sign(manifest_bytes) -> bytes` and `key_id() -> str`, plus a `MinisignSigner` (or PyNaCl-backed) implementation. Connected side, so dependencies allowed. Design so a KMS/HSM signer drops in later. Key path read from env var, never a flag, never committed. *(Done: commit 2cec6ac. `Ed25519Signer` (PyNaCl) is the concrete impl; pynacl added as a runtime dep, SPEC §12 and CLAUDE.md updated to match; stdlib guard on offline.py still green on Linux CI.)*
+
+  **Decision — native key format (settled at 0.2):** the ed25519 signer uses a **raw hex-encoded 32-byte seed** as its on-disk key format (`generate_keypair` writes seed hex + public hex). This is deliberately **not** minisign's format. Rationale: 0.2.0 controls both ends (PyNaCl produces the signature and the pack-time self-check / `verify_signature.py` consume it); nothing this release hands a key or signature to the `minisign` binary, so matching minisign now buys zero working interop and pulls in its full envelope (base64 key blobs with algorithm tag + key id, scrypt-encrypted secret keys, the `.minisig` signature format with a signed trusted-comment). True minisign interop is deferred to a later `MinisignSigner` behind the same Protocol (see §8, "minisign as the documented interop path"). **Consequence for 0.3:** the manifest `algorithm` string must name what is actually produced (`"ed25519"`, not `"minisign-ed25519"`) until a real minisign signer lands; `minisign-ed25519` is reserved for that.
+
+- [ ] **0.3** Manifest schema 2. Bump `MANIFEST_VERSION` to 2 in `manifest.py`. Add a `signing` block: `{"algorithm": "minisign-ed25519", "key_id": "<id>", "signature_file": "manifest.json.minisig"}`. Payload structure unchanged. The manifest never contains its own signature (circular); the signature is always the external `.minisig` sidecar, computed over the final serialized manifest bytes. Serialization stays deterministic.
+
+- [ ] **0.4** offline.py accepts schema 2 for integrity — the one careful edit to the frozen file. Change `SUPPORTED_MANIFEST_VERSION` to accept `{1, 2}`. That is the only functional change: offline.py verifies integrity for both schemas, imports no crypto, does not verify signatures, stays under the line cap. Update the frozen-file rationale and SPEC to state the split explicitly. The stdlib guard from 0.1 must stay green.
+
+- [ ] **0.5** The signature verifier — a separate tool, not offline.py. New `src/modelferry/verify_signature.py`: takes a bundle and a trusted public key, checks `manifest.json.minisig` against `manifest.json`. Dependencies allowed. This is what the appliance calls at admission and what a security officer runs connected-side. It is explicitly not copied into the bundle as a bare-host requirement.
+
+- [ ] **0.6** Pack-time signing and self-check. In `pack.py`/`cli.py`: after writing the manifest, if a signing key is configured, sign it, write `manifest.json.minisig`, then run 0.5's verify as a pack-time self-check (mirrors the existing post-pack integrity self-verify). Gated by `--sign` or `MODELFERRY_SIGNING_KEY`. Unsigned packing still works; signing is additive.
+
+- [ ] **0.7** MANIFEST.md and README reflect signing. MANIFEST.md gains a signing section when signed. The README's honest-limit paragraph flips: authenticity is covered when the bundle is signed and the verifier has the trusted key, with the boundary stated precisely (the bare-host integrity check still does not verify the signature; that is done at approval/admission where the key lives).
+
+- [ ] **0.8** Release 0.2.0. Tag, publish to PyPI, GitHub release. The release notes publish the canonical `offline.py` **verifier hash** (as every release has since 0.1.0). They do NOT publish any signing key fingerprint: modelferry has no signing key of its own. `pack --sign` is a capability for users to sign THEIR bundles with THEIR keys, distributed out-of-band by whoever operates the approval authority for the receiving environment. There is no canonical modelferry signing key, so no release publishes one.
+
+**Acceptance tests (Phase 0):**
+- `test_offline_stdlib_lint` — offline.py imports only stdlib; fails on a real non-stdlib import. *(passing)*
+- `test_signer_roundtrip` — sign a fixed byte string, verify against the public key in-process.
+- `test_signing_key_never_in_repo` — no key material or key path literal committed.
+- `test_manifest_v2_deterministic` — same inputs, byte-identical v2 manifest.
+- `test_v2_bundle_verifies_integrity` — a v2 bundle passes `verify` on the unchanged integrity verifier.
+- `test_v1_bundle_still_verifies` — no regression for existing bundles.
+- `test_good_signature_verifies` / `test_tampered_manifest_fails_signature` / `test_wrong_key_fails` / `test_missing_signature_fails`.
+- `test_pack_signs_when_key_present` / `test_pack_unsigned_without_key` / `test_packed_signature_self_verifies`.
+
+**Done when:** a real model packs to a signed bundle, the signature verifies where the key lives, integrity still verifies on the bare stdlib host for both schemas, the guard holds, and 0.2.0 is published with the canonical offline.py verifier hash in the release notes (no signing key is published; there is no canonical modelferry signing key).
+
+---
+
+## Phase 1 — Closure engine (ships as 0.3.0)
+
+**Goal:** a bundle carries everything to run the model offline, and a real model goes from Hugging Face to serving inside `--network none` using only the bundle.
+
+- [ ] **1.1** `core/closure/resolve.py`: given a target (repo, revision, extras), produce a pinned `lock.txt` with `uv pip compile`. Record exact index URLs.
+- [ ] **1.2** `core/closure/wheelhouse.py`: build the wheelhouse for the target platform. See Section 7 for flags and sdist handling.
+- [ ] **1.3** `core/closure/image.py`: `docker save` the inference-server image into `payload/images/`. Record image digest in `compat.json`.
+- [ ] **1.4** `core/closure/model.py`: fetch model artifacts from HF pinned to `revision`, honoring an HF token for gated repos. **The hash of record is computed post-fetch** — the manifest describes the bytes actually fetched, never claims byte-identity to HF (LFS re-uploads and mirror differences happen).
+- [ ] **1.5** `core/compat.py`: emit `compat.json` (arch, minimum NVIDIA driver / compute capability, python version, footprint, image digest, torch build).
+- [ ] **1.6** CLI: `modelferry pack <repo> --revision <sha> --server vllm --out bundle/`.
+- [ ] **1.7** Offline reconstruction: verify, `pip install --no-index --find-links payload/wheelhouse -r payload/lock.txt`, `docker load`, load model, serve one completion.
+- [ ] **1.8** Preflight: read `compat.json` and fail clearly if host driver or compute capability is below requirement, before any transfer or load.
+- [ ] **1.9** Driver compatibility matrix (added, load-bearing). Ship a documented "these bundles run on driver X and up" table, and pack at least one bundle targeting an older CUDA (12.1, driver ~530) as a fallback. The first pilot's disconnected host often runs a frozen old driver IT will not touch; without a fallback, day one is a driver argument, not a demo.
+
+**Acceptance tests:**
+- `test_wheelhouse_offline_install` (GPU runner) — in `--network none`, install from wheelhouse succeeds and imports torch with CUDA.
+- `test_model_serves_offline` (GPU runner) — vLLM loads the bundled model and returns a completion offline.
+- `test_sdist_only_dependency_flagged` — a target pulling an sdist-only non-prebuilt dependency is caught at pack time, not load time.
+- `test_compat_preflight_fails_on_mismatch` — a fabricated low-driver compat.json fails preflight.
+- `test_older_cuda_bundle_serves` — the 12.1 fallback bundle serves on an older-driver host.
+
+**Done when:** Qwen2.5-14B goes HF → served inside a network-isolated container using only the bundle, the driver fallback works, and the tests pass. Ships as 0.3.0.
+
+**Honesty call to settle here:** is the wheelhouse a real independent install path, or a fallback with the image as primary runtime? flash-attn plus the torch/CUDA/Python matrix is the most common reason offline vLLM installs fail, and "prefer the image path" quietly means the image, not the wheelhouse, carries such models. Pick the honest story and make `test_wheelhouse_offline_install` match it, so it does not fail on exactly the models people want.
+
+---
+
+## Phase 2 — Registry as the product (ships as 0.4.0 preview)
+
+**Goal:** an appliance that admits, versions, serves three ways, and audits.
+
+- [ ] **2.1** Ingest: chunked upload to `POST /bundles/`, store chunks in the CAS with refcounting, create a `pending` version. Reject on manifest hash mismatch.
+- [ ] **2.2** Admission verification: check the minisign signature against the appliance's trusted key (this is where 0.2.0's `verify_signature` runs server-side) and validate the manifest before accepting. Failures never create an approved version.
+- [ ] **2.3** RBAC and approval state machine: `pending → approved | rejected`, `approved → revoked`. Enforce separation of duties (creator cannot approve).
+- [ ] **2.4** Serve models: materialize an approved version to a verified directory an inference host mounts.
+- [ ] **2.5** Serve offline PyPI: static PEP 503 index from the CAS wheels.
+- [ ] **2.6** Serve OCI: embed zot, load the bundled image, proxy `/v2/`.
+- [ ] **2.7** Audit log — a **hash chain** (not a Merkle tree): `entry_hash = sha256(prev_hash || canonical(actor, action, target, detail, created_at))`, fixed genesis. Detects tampering of past rows. Known limitation stated in one sentence: a full-history rewrite by someone who controls the appliance is only caught if the genesis hash or a periodic anchor is recorded off-box. It is tamper-evident, not tamper-proof.
+- [ ] **2.8** Revocation boundary (added, load-bearing). Revocation blocks future admission and serving from the appliance; it does not reach already-deployed inference hosts, which are re-verified on next materialize. Use the `deployments` table as the enforcement surface: a reconciliation check flags running deployments of a now-revoked version. Document this boundary explicitly — a CISO will find it otherwise.
+- [ ] **2.9** Web UI (templates + HTMX): catalog, version detail, approval queue, audit view.
+
+**Acceptance tests:**
+- `test_ingest_rejects_bad_manifest` / `test_admission_rejects_bad_signature` / `test_separation_of_duties`.
+- `test_pip_install_from_registry_offline` / `test_docker_pull_from_registry_offline`.
+- `test_audit_chain_detects_tamper`.
+- `test_revoked_deployment_flagged` — a running deployment of a revoked version is surfaced by reconciliation.
+
+**Done when:** two versions ingested, approval enforced, an isolated host pulls wheels and image from the registry and serves, revocation reconciliation works, and the tests pass. Ships as 0.4.0 preview — the release you take to a design partner.
+
+---
+
+## Phase 3 — Trust and compliance (folds into 0.5.0)
+
+**Goal:** the appliance speaks auditor and CISO language and refuses non-compliant models.
+
+- [ ] **3.1** Signing hardening: KMS/HSM-backed signer via the 0.2.0 `Signer` interface. cosign as the enterprise implementation.
+- [ ] **3.2** in-toto: signed provenance statement (builder, modelferry source commit, model source and digest, scanner and policy results).
+- [ ] **3.3** SBOM: `core/sbom.py` runs syft over the wheelhouse and image, injects model metadata, produces CycloneDX and SPDX. Verify current spec support for the ML fields when implementing — they are evolving.
+- [ ] **3.4** License detection: read model-card metadata and LICENSE files, map to SPDX ids, classify permissive / copyleft / non-commercial / restrictive. Expect this to be heuristic and fiddly; model-card license metadata is wildly inconsistent.
+- [ ] **3.5** CVE scanning: pip-audit or osv-scanner over `lock.txt`, trivy or grype over the image, aggregated into a signed `vuln-report.json`. Scanners run connected-side against a snapshotted vulnerability DB; only the signed report crosses the gap.
+- [ ] **3.6** Policy engine: `core/policy.py` evaluates `policy.yaml` at two gates (pack and admission).
+
+**Acceptance tests:** `test_policy_refuses_bad_license`, `test_policy_refuses_critical_cve`, `test_admission_reruns_policy`, `test_sbom_contains_model_and_deps`, `test_compliance_export_signed`.
+
+**Sizing note:** this phase slips more than any other in a side-of-desk build. syft's CycloneDX ML extension is in flux and license classification is hand-tuned heuristics. Budget double the naive estimate.
+
+---
+
+## Phase 4 — Delta and transport (folds into 0.5.0)
+
+**Goal:** updates ship megabytes not gigabytes, and higher-security transports work. Respect the one-way constraint: only a small, **exact** (never probabilistic — a Bloom filter over a diode silently drops chunks) inventory crosses outward; the larger delta comes inward.
+
+- [ ] **4.1** Exact inventory export: `GET /inventory/chunks`, sorted held-chunk hashes, varint-delta-encoded, zstd-compressed.
+- [ ] **4.2** Delta pack: diff a new version's chunk set against an imported inventory, write a bundle of only missing chunks plus the full manifest.
+- [ ] **4.3** Reconstruction: rebuild from held chunks plus delta, verify byte-identical against the manifest before `pending`.
+- [ ] **4.4** Diode reconciliation manifest: completeness proof with no back-channel.
+- [ ] **4.5** OCI export path for registry-to-registry ingest without USB.
+- [ ] **4.6** Optional AES-256 media encryption (age or libsodium), documented key handling.
+- [ ] **4.7** Resumable unpack via a receipt tracking applied chunks.
+
+**Acceptance tests:** `test_delta_ships_only_missing_chunks`, `test_delta_reconstructs_byte_identical`, `test_delta_inventory_is_exact`, `test_resumable_unpack`. Record the size ratio — it is a YC application number.
+
+---
+
+## Phase 5 — Appliance packaging and pilot hardening (ships as 1.0)
+
+**Goal:** something a real security review passes, installed from media into a clean room.
+
+- [ ] **5.1** Package the appliance itself as an offline-installable, signed modelferry bundle (dogfood).
+- [ ] **5.2** Install, upgrade, backup, restore procedures with scripts.
+- [ ] **5.3** Observability on the Celery workers (dogfood celerypeek).
+- [ ] **5.4** Hardening: secrets, TLS, least-privilege, air-gap install verification.
+- [ ] **5.5** Promote to 1.0.
+
+**Acceptance tests:** `test_clean_room_offline_install`, `test_full_loop_e2e`.
+
+---
+
+## Section 7 — Closure engine, in detail
+
+The part that makes a bundle runnable and the part clones skip.
+
+Wheelhouse build (connected side):
+```bash
+uv pip compile requirements.in -o lock.txt
+pip download -r lock.txt -d payload/wheelhouse \
+  --only-binary=:all: --platform manylinux_2_28_x86_64 \
+  --python-version 311 --implementation cp
+pip download torch --index-url https://download.pytorch.org/whl/cu124 \
+  --only-binary=:all: --platform manylinux_2_28_x86_64 \
+  --python-version 311 --implementation cp -d payload/wheelhouse
+```
+
+Inside the gap:
+```bash
+pip install --no-index --find-links payload/wheelhouse -r payload/lock.txt
+docker load -i payload/images/vllm.tar
+vllm serve /path/to/materialized/model --host 0.0.0.0 --port 8000
+```
+
+Gotchas, each with a test: sdist-only / build-required deps (flash-attn is the classic; prefer the image path and detect the gap at pack time), sharded safetensors (hash every shard and the index), custom-code models (`trust_remote_code`; fetch the `.py`, flag in policy), gated repos (HF token, restrictive license into classification), quantized/alternate formats (AWQ/GPTQ and GGUF, since buyers do not all run vLLM), FAT32 (chunk parts ≤ 4GiB — the 4MiB CAS chunk and the 4GiB FAT32 part-file cap are two different numbers; do not conflate them).
+
+Documented limitation: modelferry bundles the CUDA userspace (torch wheels, server image), not the kernel driver. The gap host must have a compatible driver. `compat.json` plus preflight plus the 1.9 fallback bundle turn this into an early, clear failure and a documented workaround, not a runtime crash.
+
+## Section 8 — Trust, signing, SBOM, policy
+
+Keyless Sigstore needs a live CA and transparency log, so it cannot be the inside-gap verification path. Key-based signing, verified offline against a bundled trust root. minisign for v1, `Signer` interface designed for KMS/HSM cosign later. If a customer wants Sigstore bundles, produce them connected-side and verify offline with a bundled trust root; never depend on Rekor reachability inside the gap.
+
+Policy schema (`policy.yaml`):
+```yaml
+version: 1
+require_signature: true
+allowed_licenses: [Apache-2.0, MIT, BSD-3-Clause, "class:permissive"]
+denied_licenses: ["class:non-commercial"]
+flag_remote_code: true
+max_cve_severity: high
+allowed_sources: [huggingface.co]
+```
+Evaluator returns `{passed, violations}`, runs at pack time (fail fast) and admission (enforcement of record).
+
+## Section 10 — The air-gap test harness
+
+Every inside-gap step runs inside `docker run --network none` with the bundle mounted read-only. Any accidental network call fails the test. Add an explicit egress probe the tests call to assert a socket is refused. Two modes: a CPU Python container for wheel reconstruction and a tiny model load, and the actual server image for the offline serve proof (GPU runner).
+
+## Section 11 — End-to-end acceptance matrix
+
+Positive: (1) pack Qwen2.5-14B, FAT32 transfer, admit, serve in `--network none`. (2) isolated client installs wheels via the registry index and pulls the image. (3) small-change delta transfers a fraction and reconstructs byte-identically. (4) compliance report verifies against the appliance key.
+
+Negative, each failing in the right way: (5) flipped payload byte → integrity exit code. (6) tampered `manifest.json` → signature verification fails, admission refuses. (7) unsigned or wrong-key bundle → never approved. (8) missing wheel → flagged at pack time. (9) non-commercial model under permissive-only policy → refused at pack gate. (10) fabricated low-driver compat.json → preflight fails. (11) corrupt delta chunk → byte-identical check fails. (12) edited audit row → chain verify false. (13) any inside-gap network call → harness fails it.
+
+## Section 12 — The design-partner track (as important as the code)
+
+The plan's value as a YC application depends entirely on turning one real disconnected environment into a named design partner who will say "yes, we need this." The most valuable asset here is access to a real air-gapped government environment with a real model need. Have that conversation during Phase 0–1, not deferred to Phase 5. See the conversation script kept alongside this plan. Spend as much energy on that one conversation as on any single phase.
+
+## Section 13 — What to cut for v1
+
+No Kubernetes operator (docker-compose is enough). No multi-node HA or web-scale multi-tenancy. No React UI until a design partner needs it (templates, HTMX, Django admin). No OPA/Rego (the YAML evaluator suffices). No keyless Sigstore.

modelferry-0.2.0/CHANGELOG.md

@@ -0,0 +1,109 @@
+# Changelog
+
+All notable changes to modelferry are recorded here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.0] - 2026-07-22
+
+Signing. A bundle's manifest can now be signed, and its authenticity checked
+against a trusted key, without adding anything to the bare-host integrity
+verifier. Signing is additive: unsigned bundles pack and verify exactly as before.
+
+### Added
+
+- `modelferry pack --sign`: produce a signed bundle. The manifest gains a
+  `signing` block (algorithm, key id, signature filename), and a detached ed25519
+  signature over the exact `manifest.json` bytes is written to `manifest.json.sig`.
+  The signing key is read from the `MODELFERRY_SIGNING_KEY` environment variable
+  (a path), never a flag and never written into any bundle, manifest, sidecar, or
+  log. `--sign` without a key configured is a usage error, never a silent unsigned
+  pack, and pack self-verifies the signature it just wrote before the bundle ships.
+- `modelferry verify-signature BUNDLE_DIR --public-key PATH`: check a bundle's
+  authenticity against a trusted public key. Reports VALID (exit 0), or UNSIGNED /
+  BAD_SIGNATURE / KEY_MISMATCH / MISSING_SIG (exit 1) or MALFORMED (exit 2). It is
+  connected-side / appliance-side, holds the trusted key, and is never copied into
+  a bundle. The trusted key comes from `--public-key` or `MODELFERRY_PUBLIC_KEY`.
+- `manifest.json` schema 2: an optional top-level `signing` block. Version 2 is a
+  strict superset of version 1. An unsigned bundle is a version-2 manifest with no
+  signing block, byte-for-byte what version 1 was plus the bumped version number.
+- `MANIFEST.md` gains a Signature section for signed bundles, telling the reviewer
+  how to check authenticity with `verify-signature` and stating that it augments,
+  not replaces, the approved-copy checksum comparison.
+- `src/modelferry/signing.py` and `src/modelferry/verify_signature.py`: the
+  connected-side signer and signature verifier, ed25519 via PyNaCl.
+
+### Changed
+
+- `src/modelferry/offline.py` accepts manifest schema 1 and 2 for integrity. That
+  is its only change: it still imports no crypto, never verifies a signature, and
+  ignores the signing block (which is not under `payload.files`, so the integrity
+  hashing never touches it). The bundled verifier stays standard-library only and
+  runs on CPython 3.9. Its canonical sha256 therefore differs from 0.1.0; the new
+  hash is published in these release notes.
+- Runtime dependency added: `pynacl`, for connected-side signing only. It never
+  enters `offline.py`.
+
+### Security
+
+- The trust model, stated in the README and SPEC section 9: integrity (the arrived
+  bytes match the manifest) is checked on the bare disconnected host by the bundled
+  `offline.py`, with no network and no key. Authenticity (the manifest was signed
+  by a trusted key) is checked by `verify-signature` on the connected / approval
+  side, where the key lives. A bundle an attacker rebuilt from scratch passes its
+  own integrity check but fails signature verification against the real key.
+- modelferry has no signing key of its own. `pack --sign` signs a user's bundles
+  with the user's key; the trusted public key is distributed out-of-band by the
+  approval authority for the receiving environment, not by modelferry. The `key_id`
+  in the manifest tells a verifier which key a bundle claims; trust in that key
+  comes from the operator's out-of-band distribution. This release publishes the
+  canonical `offline.py` verifier hash, as every release does, and no signing key.
+
+## [0.1.0] - 2026-07-16
+
+First release.
+
+### Added
+
+- `modelferry pack REPO_ID --dest DIR`: download a Hugging Face model repo pinned
+  to a commit, split oversized files into `.mfpartNNNN` parts, hash everything
+  with sha256, and write a bundle with `manifest.json`, `MANIFEST.md`, the
+  payload, and a copy of the offline verifier.
+- `modelferry verify`, `unpack`, and `inspect`: thin wrappers over the exact
+  standard-library verifier that ships inside every bundle, so the installed CLI
+  and the bundled tool behave identically.
+- `src/modelferry/offline.py`: the self-contained verifier and unpacker. Standard
+  library only, runs on CPython 3.9, no network, no third-party packages. Copied
+  verbatim into every bundle at `tools/modelferry_offline.py`.
+- `manifest.json` (version 1): deterministic, `sort_keys` serialization with
+  whole-file and per-part sha256 hashes, source repo and resolved commit SHA,
+  license, gated flag, and the verifier hash.
+- `MANIFEST.md`: human-readable approval document for security review.
+- Chunking sized for FAT32 by default (`--chunk-size 3900M`), with `--include` /
+  `--exclude` fnmatch filtering and resumable downloads via `--staging`.
+- Streamed IO with a fixed 8 MiB buffer throughout, so bundles larger than RAM
+  pack and verify with flat memory use.
+- Zip-slip-safe unpack: absolute paths, `..` segments, and anything resolving
+  outside the destination are rejected, and symlinks are never created.
+- Post-pack read-back self-verify, so disk-level write errors surface before the
+  bundle leaves the connected side.
+- Exit codes per SPEC section 10 (0 success, 1 integrity, 2 usage, 3 source,
+  4 filesystem).
+
+### Security
+
+- `HF_TOKEN` is read from the environment only and is never written into a
+  bundle, manifest, receipt, or log. A test packs with a fake token and asserts
+  the token bytes appear nowhere in the output.
+- The trust model is documented in the README. v1 covers accidental corruption,
+  incomplete transfers, media errors, and casual tampering. It does not cover a
+  coordinated adversary who rewrites payload, manifest, and verifier together;
+  that needs out-of-band signature verification, planned for v1.1. Each release
+  publishes the canonical `offline.py` sha256 so a receiving site can check the
+  bundled verifier out-of-band.
+
+[Unreleased]: https://github.com/HamzaAhmedWajeeh/modelferry/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/HamzaAhmedWajeeh/modelferry/releases/tag/v0.2.0
+[0.1.0]: https://github.com/HamzaAhmedWajeeh/modelferry/releases/tag/v0.1.0

{modelferry-0.1.0 → modelferry-0.2.0}/CLAUDE.md

@@ -18,7 +18,7 @@ CLI that packs Hugging Face models into chunked, sha256-manifested bundles for t
 - All payload IO is streamed with a fixed 8 MiB buffer. Never read a payload file fully into memory.
 - Unpack rejects absolute paths, `..` segments, and anything resolving outside the destination. Never create symlinks.
 - Exit codes exactly per SPEC.md §10. Do not invent new ones.
-- Runtime dependencies are typer, rich, huggingface_hub. Do not add a fourth without asking.
+- Runtime dependencies are typer, rich, huggingface_hub, and pynacl (added in 0.2.0 for connected-side signing in signing.py; it must never enter offline.py). Do not add another without asking.
 - Never weaken a corruption, path-safety, or token-leak test to make it pass. Fix the code instead.
 - Every bugfix ships with a regression test.
 

{modelferry-0.1.0 → modelferry-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: modelferry
-Version: 0.1.0
+Version: 0.2.0
 Summary: Pack Hugging Face models into chunked, hashed, self-verifying bundles for air-gapped transfer.
 Project-URL: Homepage, https://github.com/HamzaAhmedWajeeh/modelferry
 Project-URL: Repository, https://github.com/HamzaAhmedWajeeh/modelferry
@@ -21,6 +21,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: System :: Archiving :: Packaging
 Requires-Python: >=3.10
 Requires-Dist: huggingface-hub<2,>=1.0.0
+Requires-Dist: pynacl>=1.5.0
 Requires-Dist: rich>=13
 Requires-Dist: typer>=0.24.0
 Description-Content-Type: text/markdown
@@ -176,23 +177,49 @@ flagged at the top of the document.
 
 ## Trust model
 
-Stated honestly, because this is the part a security review turns on.
-
-v1 protects against accidental corruption, incomplete transfers, media errors,
-and casual tampering with payload files. Any of those shows up as a hash
-mismatch, a missing part, or an extra file, and verify exits non-zero and names
-what failed.
-
-v1 does not protect against an adversary who can modify the payload, the
-manifest, and the bundled verifier together. Defending against that requires
-signature verification with a key held out-of-band, which is planned for v1.1
-(minisign).
-
-The mitigation available today is out-of-band verification of the verifier.
-`manifest.json` records the sha256 of the bundled `offline.py`, and every
-release publishes the canonical `offline.py` hash in its release notes. A
-receiving site can check the bundled verifier against that published hash before
-trusting it, or ignore the bundled copy and bring its own known-good verifier.
+Stated honestly, because this is the part a security review turns on. modelferry
+checks two different things with two different tools.
+
+Integrity is whether the bytes that arrived match the manifest. It protects
+against accidental corruption, incomplete transfers, media errors, and casual
+tampering with payload files. Any of those shows up as a hash mismatch, a missing
+part, or an extra file, and verify exits non-zero and names what failed. Integrity
+is checked by the bundled `offline.py`, standard library only, on the bare
+disconnected host with no network and no key.
+
+Authenticity is whether the manifest was signed by a key you trust. When a bundle
+is signed (`pack --sign`) and the verifier has the trusted public key, authenticity
+is checkable: `modelferry verify-signature` checks the detached signature over
+`manifest.json` against that key. A bundle an attacker rebuilt from scratch, with
+its own internally consistent payload, manifest, and hashes, would pass its own
+integrity check but fail signature verification against the real key, because the
+attacker cannot produce that key's signature.
+
+The boundary, stated precisely so it isn't oversold: the bare-host integrity
+verifier does not check the signature. Signature verification is a separate
+connected-side tool that holds the trusted key, and it is not copied into the
+bundle. So on a truly bare air-gap host with only system Python and no trusted key
+on hand, you get integrity, and authenticity is established upstream, at the
+approval or admission step where the key lives. Signing protects that approval
+chain. The trusted public key has to reach verifiers out-of-band, and it is the
+approval authority for the receiving environment that distributes it, the same
+people who already approve the manifest checksum. modelferry has no signing key of
+its own and does not distribute keys: `pack --sign` signs your bundles with your
+key, for your environment. The `key_id` in the manifest lets a verifier confirm
+which key a bundle claims to be signed by, but trust in that key comes from the
+operator's out-of-band distribution, not from modelferry. This is key-based
+signing verified against a known key, not end-to-end authenticity on a bare host
+that has no key.
+
+Signing is additive. An unsigned bundle still packs and still verifies for
+integrity; it just carries no authenticity claim, which verify-signature reports
+as UNSIGNED rather than as valid.
+
+The verifier itself is also checkable out-of-band. `manifest.json` records the
+sha256 of the bundled `offline.py`, and every release publishes the canonical
+`offline.py` hash in its release notes. A receiving site can check the bundled
+verifier against that published hash before trusting it, or ignore the bundled
+copy and bring its own known-good verifier.
 
 ## Exit codes
 

{modelferry-0.1.0 → modelferry-0.2.0}/README.md

@@ -149,23 +149,49 @@ flagged at the top of the document.
 
 ## Trust model
 
-Stated honestly, because this is the part a security review turns on.
-
-v1 protects against accidental corruption, incomplete transfers, media errors,
-and casual tampering with payload files. Any of those shows up as a hash
-mismatch, a missing part, or an extra file, and verify exits non-zero and names
-what failed.
-
-v1 does not protect against an adversary who can modify the payload, the
-manifest, and the bundled verifier together. Defending against that requires
-signature verification with a key held out-of-band, which is planned for v1.1
-(minisign).
-
-The mitigation available today is out-of-band verification of the verifier.
-`manifest.json` records the sha256 of the bundled `offline.py`, and every
-release publishes the canonical `offline.py` hash in its release notes. A
-receiving site can check the bundled verifier against that published hash before
-trusting it, or ignore the bundled copy and bring its own known-good verifier.
+Stated honestly, because this is the part a security review turns on. modelferry
+checks two different things with two different tools.
+
+Integrity is whether the bytes that arrived match the manifest. It protects
+against accidental corruption, incomplete transfers, media errors, and casual
+tampering with payload files. Any of those shows up as a hash mismatch, a missing
+part, or an extra file, and verify exits non-zero and names what failed. Integrity
+is checked by the bundled `offline.py`, standard library only, on the bare
+disconnected host with no network and no key.
+
+Authenticity is whether the manifest was signed by a key you trust. When a bundle
+is signed (`pack --sign`) and the verifier has the trusted public key, authenticity
+is checkable: `modelferry verify-signature` checks the detached signature over
+`manifest.json` against that key. A bundle an attacker rebuilt from scratch, with
+its own internally consistent payload, manifest, and hashes, would pass its own
+integrity check but fail signature verification against the real key, because the
+attacker cannot produce that key's signature.
+
+The boundary, stated precisely so it isn't oversold: the bare-host integrity
+verifier does not check the signature. Signature verification is a separate
+connected-side tool that holds the trusted key, and it is not copied into the
+bundle. So on a truly bare air-gap host with only system Python and no trusted key
+on hand, you get integrity, and authenticity is established upstream, at the
+approval or admission step where the key lives. Signing protects that approval
+chain. The trusted public key has to reach verifiers out-of-band, and it is the
+approval authority for the receiving environment that distributes it, the same
+people who already approve the manifest checksum. modelferry has no signing key of
+its own and does not distribute keys: `pack --sign` signs your bundles with your
+key, for your environment. The `key_id` in the manifest lets a verifier confirm
+which key a bundle claims to be signed by, but trust in that key comes from the
+operator's out-of-band distribution, not from modelferry. This is key-based
+signing verified against a known key, not end-to-end authenticity on a bare host
+that has no key.
+
+Signing is additive. An unsigned bundle still packs and still verifies for
+integrity; it just carries no authenticity claim, which verify-signature reports
+as UNSIGNED rather than as valid.
+
+The verifier itself is also checkable out-of-band. `manifest.json` records the
+sha256 of the bundled `offline.py`, and every release publishes the canonical
+`offline.py` hash in its release notes. A receiving site can check the bundled
+verifier against that published hash before trusting it, or ignore the bundled
+copy and bring its own known-good verifier.
 
 ## Exit codes