openappx 0.6.0__tar.gz

openappx-0.6.0/CHANGELOG.md

@@ -0,0 +1,183 @@
+# Changelog
+
+Notable changes per release. Dates are the day the work landed.
+
+## 0.6.0 — 2026-08-01
+
+First release published to PyPI.
+
+### Added
+
+- **`openappx bundle`** — combine `.msix` packages into an `.msixbundle`, the
+  last big gap in the tool. A bundle built and signed here installs on an Xbox
+  One dev kit. `inspect` reads bundles too, and reports Microsoft's own
+  deliberately-broken reference bundles exactly as upstream labels them.
+
+  Five things differ from a package, and every one was found by a device
+  refusing a bundle that looked correct — see [docs/format.md](docs/format.md):
+  - the signature uses a **different SIP GUID**. A bundle signed with the
+    package GUID verifies locally and is rejected as unsigned.
+  - **every payload in a signed bundle must be signed too.** The device blames
+    the bundle, so the error points at the wrong file.
+  - a package is a resource package because `Identity/@ResourceId` is set, not
+    because it has no `<Applications>`.
+  - application packages carry **no** `ResourceId`; one there stops the device
+    matching them by architecture.
+  - `Package/@Offset` is where the payload's _data_ starts, not its record.
+
+- `inspect` rejects an `Application/@Executable` that is not linked for the app
+  container. MSBuild sets `IMAGE_DLLCHARACTERISTICS_APPCONTAINER` from
+  `<AppContainerApplication>`; cross-compiling you have to ask the linker for
+  it, and forgetting is silent — the binary still runs on a desktop. The flag is
+  readable from the PE stored in the archive, so this is a local check. It
+  reports only the confident no: an `Executable` that is not a parseable PE is
+  left alone.
+- `validate` reports a managed `EntryPoint="ns.Class"` with no `ns.winmd` in the
+  layout. The activation lookup needs that file; without it the package
+  installs and then refuses to start, which reads like an application bug.
+- `validate` reports build artefacts (`*.obj`, `*.pch`, `*.pdb`, …) in a layout.
+  Everything in the directory gets packed, and a stray precompiled header is
+  around 190 MB.
+
+### Fixed
+
+- The manifest greps no longer match the manifest's own comments. These files
+  document themselves, and the attributes worth explaining are exactly the ones
+  being searched for, so a comment mentioning `Executable=` was read as markup.
+
+### Established
+
+- `0x8d160120` on app launch is a property of this console, not of any packer —
+  and this is now settled rather than suspected. Device Portal refuses to launch
+  **every** sideloaded package on it, **Microsoft Edge included**. Four packages
+  with nothing in common but the hardware behave identically: xllama built on
+  Windows with MSBuild, the same xllama repackaged here, a UWP application
+  compiled from scratch on Linux, and Edge as Microsoft signed and shipped it.
+  All install, none launches, same code.
+
+  This retires an open question, and does not replace it with a better one: it
+  says nothing about whether a repackaged application runs correctly once
+  started, only that this particular failure cannot be read as evidence.
+
+## 0.5.0 — 2026-08-01
+
+### Added
+
+- `openappx sign --timestamp` — RFC 3161 countersignature, so a signature
+  outlives its certificate. The token covers the RSA signature (Authenticode's
+  arrangement) and `openssl ts -verify` accepts it against exactly those bytes;
+  a timestamped package still installs. Unlike the rest of the format work this
+  was not copied from a reference package — neither available Microsoft package
+  is timestamped — so what remains unproven is that Windows honours it after
+  expiry.
+- `inspect` now reports the signer: subject, self-signed or issued, expiry, and
+  whether a timestamp is present. It checks publisher agreement and validity
+  dates, never chain of trust.
+
+- `openappx unpack` — extract a layout a packer can consume again, the missing
+  half of repackaging. Round-trips a real 19 MB package to byte-identical
+  output. Archive member names are validated, so a crafted package cannot write
+  outside the destination.
+- `openappx deploy --start/--stop` — launch and stop apps through
+  `/api/taskmanager/app`.
+- [docs/format.md](docs/format.md) — the container and blockmap rules in one
+  place, each with the measurement that established it.
+- `CONTRIBUTING.md`, `SECURITY.md`, Dependabot, `.editorconfig`.
+
+### Fixed
+
+- **Non-ASCII entry names were corrupted.** Names were written as UTF-8 without
+  flag bit 11, so every reader decoded them as CP437: `città-日本.png` became
+  `città-日本.png`.
+- **Files above 4 GiB now fail with an explanation.** Describing one needs ZIP64
+  extra fields on the record, and a package carrying those is refused by a
+  device with `0x8007000B` — the same code a ZIP32 archive gets, measured
+  against a package that installs without them. Appx wants the ZIP64
+  end-of-central-directory and nothing on the entries.
+- Nine type errors, mypy never having been run: a dataclass holding the
+  certificate and private key as bare `object`, and a check that summed values
+  it had just established could be `None`.
+- An empty `--uninstall` value fell through to the install branch and crashed.
+
+### Testing and CI
+
+- The two command-line entry points had no tests at all; they now have 26.
+  Coverage 90% → 95%, tests 106 → 170.
+- CI installs `[dev,sign]` — without it every signature test skipped itself —
+  and now runs ruff, mypy and a coverage gate.
+- `actions/checkout` v4 → v5, `setup-python` v5 → v6, Python matrix gains 3.14.
+- The makemsix backend, previously the only code nobody had ever run, is covered
+  by a stub binary.
+
+### Known limits
+
+- A repackaged application has been proven to **install**, not to **run**:
+  launching it fails on the console, but so does the original Windows-built
+  package, so the two are at parity and neither has been seen to start.
+- No timestamping, so signatures expire with the certificate.
+- No `.msixbundle`, and `CodeIntegrity.cat` is read but not generated.
+- `pack` holds the archive in memory; fine at 47 MB, not at 2 GB.
+
+## 0.4.0 — 2026-08-01
+
+The whole chain now works from Linux, with no Windows tooling: **pack → sign →
+deploy**. A real 47 MB UWP application, repackaged and signed by this project,
+installs on an Xbox One dev kit.
+
+### Added
+
+- `openappx sign` — creates `AppxSignature.p7x`. The CMS/PKCS#7 structure was
+  copied from a decoded Microsoft signature; the DER encoder is ours
+  (`sign/asn1.py`). `cryptography` sits behind the optional `[sign]` extra for
+  RSA and PKCS#12; packing, inspecting and verifying stay stdlib-only.
+- `openappx sign --make-test-cert` — mint a self-signed certificate whose subject
+  matches `Identity/@Publisher`.
+- `openappx deploy` — Windows Device Portal client (install, list, uninstall,
+  `--install-cert`). The same REST API serves Xbox, HoloLens, IoT and desktop.
+- `openappx inspect` — contents, blockmap summary and signature verification for
+  any `.msix`, not only ours (`--json` for machine output).
+- `openappx.sign.digest` — parse the `APPX` digest blob and recompute
+  `AXPC`/`AXCD`/`AXCT`/`AXBM`/`AXCI` from an archive.
+- `examples/resource-only/` — a layout that genuinely installs on a device.
+- Golden tests against Microsoft's own signed packages, fetched on demand
+  (`OPENAPPX_NO_NETWORK=1` to skip).
+
+### Fixed — format conformance
+
+Comparing our output with a Microsoft-signed package, and then with what a
+console accepts, exposed four ways the packer was wrong:
+
+- **Appx archives must be ZIP64.** Not a size question: a ZIP32 package of any
+  size fails to open with `0x8007000B`.
+- **`Block/@Size` is the _compressed_ length** of each 64 KiB block, and is
+  omitted entirely for stored parts. Emitting it required deflating block by
+  block (`Z_FULL_FLUSH`), which `zipfile.writestr` cannot express — so the
+  archive is now written by hand.
+- **An empty file has zero `<Block>` elements**, not one hashing `b""`.
+- `inspect` wrongly expected `AppxMetadata/CodeIntegrity.cat` in the blockmap;
+  the signature covers it through `AXCI`.
+
+### Fixed — false documentation
+
+- `makemsix` cannot sign. `makemsix pack` accepts only `-d`/`-p`, and upstream
+  ships a signature _validator_, not a creator. The documented
+  `--cert`/`--cert-password` flow never worked and now fails with an explanation.
+- The README quickstart did not run: the package lives under `src/`.
+
+### Added — local checks for opaque device errors
+
+Each of these was first seen as a hex code from a console:
+
+- `Windows.FullTrustApplication` without the `runFullTrust` capability
+  (`0x80080204`, reported with only a line number).
+- A certificate subject differing from `Identity/@Publisher` — refused before
+  signing instead of failing on the device.
+- Malformed manifest XML (`0xC00CEE23`). `--` inside a comment is invalid XML and
+  easy to introduce while documenting a manifest.
+- Real per-attribute checks for `Identity` `Name`/`Publisher`/`Version`,
+  replacing a check whose outer condition made it unreachable.
+
+## 0.1.0
+
+Initial skeleton: blockmap generation, pure-Python pack, layout validation,
+minimal example, optional makemsix backend hook.

openappx-0.6.0/CONTRIBUTING.md

@@ -0,0 +1,52 @@
+# Contributing
+
+## Setup
+
+```bash
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev,sign]"
+pytest -q
+```
+
+`[sign]` matters: without `cryptography`, the signature tests skip themselves
+and the least forgiving code in the project goes unexercised.
+
+## Before opening a pull request
+
+```bash
+ruff check src tests
+mypy
+coverage run -m pytest && coverage report   # fails below 90%
+```
+
+CI runs exactly these on Python 3.10 through 3.14.
+
+`ruff format` is **not** part of the contract, deliberately: a couple of places
+here are laid out by hand because the automatic result reads worse — a `zip()`
+over two long expressions, a CLI argument list written two-per-line. Match the
+surrounding style; `ruff check` enforces what actually matters.
+
+## How this codebase learns things
+
+Nearly every serious defect here was found by comparing against something real —
+a Microsoft-signed package, or a device accepting or rejecting an install — not
+by reasoning about the specification. Two examples, both of which looked correct
+and were not:
+
+- `Block/@Size` is the _compressed_ length of a block, not the uncompressed one.
+- Appx requires a ZIP64 end-of-central-directory but rejects ZIP64 extra fields
+  on the records. `zipfile` and `unzip` accept either.
+
+So: **when a format detail is in doubt, check it against an artefact, and write
+the check down as a test.** `tests/test_signature.py` fetches Microsoft's own
+signed packages on demand for this purpose (`OPENAPPX_NO_NETWORK=1` skips them).
+`docs/signing.md` records which install error corresponds to which mistake.
+
+## Conventions
+
+- The default pack path stays dependency-free. Anything needing a library goes
+  behind an optional extra, as signing does.
+- `validate` runs before packing and must tolerate broken input; `inspect` runs
+  after and must not. Keep them apart.
+- No branding, real application names, or third-party binaries in `examples/`.
+- Never commit `.pfx`/`.p12` material. Public `.cer` files are fine.

openappx-0.6.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gianluca Mazza
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

openappx-0.6.0/MANIFEST.in

@@ -0,0 +1,8 @@
+# setuptools puts tests/test_*.py in the sdist on its own, but neither
+# conftest.py nor anything the tests read. Without these, an sdist ships a suite
+# that cannot run: every golden test errors on a missing fixture, test_pack.py
+# packs examples/, and test_docs.py asserts against docs/ and CHANGELOG.md.
+include tests/conftest.py
+recursive-include examples *
+recursive-include docs *.md
+include CHANGELOG.md CONTRIBUTING.md SECURITY.md

openappx-0.6.0/PKG-INFO

@@ -0,0 +1,345 @@
+Metadata-Version: 2.4
+Name: openappx
+Version: 0.6.0
+Summary: Linux-first open-source Appx/MSIX layout validation and packing
+Author-email: Gianluca Mazza <info@gianlucamazza.it>
+License: MIT
+Project-URL: Homepage, https://github.com/gianlucamazza/openappx
+Project-URL: Repository, https://github.com/gianlucamazza/openappx
+Project-URL: Changelog, https://github.com/gianlucamazza/openappx/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/gianlucamazza/openappx/issues
+Keywords: msix,appx,packaging,windows,linux
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: coverage>=7.0; extra == "dev"
+Requires-Dist: mypy>=1.11; extra == "dev"
+Provides-Extra: sign
+Requires-Dist: cryptography>=43.0; extra == "sign"
+Dynamic: license-file
+
+# openappx
+
+**Build, sign, bundle and install Windows app packages — from Linux, without Windows tooling.**
+
+`openappx` replaces the `makeappx` and `signtool` half of a Windows app pipeline:
+it turns a layout directory into a signed `.msix` or `.msixbundle`, checks it,
+and installs it on a real device over the Windows Device Portal. Pure Python,
+standard library only — signing is the one optional extra.
+
+> **Status: beta.** The whole chain works and is verified on hardware:
+> **pack → sign → deploy, from Linux, with no Windows tooling**. A real 47 MB
+> UWP application, repackaged and signed by this project, installs on an Xbox
+> One dev kit. Compiling PE/UWP binaries stays **out of scope** (see
+> [Non-goals](#non-goals)) — [uwp-crossbuild](https://github.com/gianlucamazza/uwp-crossbuild)
+> is the companion project that does that part.
+
+```bash
+pip install openappx           # signing needs the extra: openappx[sign]
+```
+
+---
+
+## What this is
+
+| You have                                                           | openappx gives you                                                                     |
+| ------------------------------------------------------------------ | -------------------------------------------------------------------------------------- |
+| A **layout directory** (manifest, assets, binaries, payload files) | A valid **`.msix` / Appx-style ZIP** with `AppxBlockMap.xml` and `[Content_Types].xml` |
+| A code-signing certificate (or none — one can be minted)           | A **signed** `.msix` that a real device installs                                       |
+| A signed `.msix` from anyone                                       | Verification that the package matches the digests its signature covers                 |
+| Packages for several architectures                                 | An `.msixbundle` carrying them all                                                     |
+| A device in developer mode                                         | Installation over the Windows Device Portal, and the error if it is refused            |
+| CI on Linux                                                        | Deterministic pack tests without Windows                                               |
+
+It is **not** a replacement for MSBuild and the Windows SDK: it does not compile
+anything. It replaces the packaging half — `makeappx`, `signtool`, and the
+sideload step — of a Windows app pipeline.
+
+---
+
+## Goals
+
+- Pack an Appx/MSIX layout on Linux, macOS, or any host with Python 3.10+
+- Generate a conformant `AppxBlockMap` (64 KiB SHA-256 blocks, compressed block
+  sizes) — checked against Microsoft-signed reference packages, not guessed
+- Sign packages without Windows, and prove it by installing them on a device
+- Validate common layout mistakes before pack (missing `AppxManifest.xml`, missing `Executable`, missing logos)
+- Stay **dependency-light** (default path: Python standard library only)
+- Produce **byte-reproducible** packages (fixed timestamps; same layout → same `.msix`)
+- Remain **product-agnostic**: any app that ships as Appx/MSIX layout can use it
+
+## Non-goals
+
+| Non-goal                                   | Why                                                                                                         |
+| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------- |
+| Compiling Win32/UWP C++/C# into PE         | A separate problem, with a separate tool: [uwp-crossbuild](https://github.com/gianlucamazza/uwp-crossbuild) |
+| Emulating Windows or ReactOS as a build OS | Different problem domain                                                                                    |
+| Guaranteeing Store certification           | Store has additional policies beyond package shape                                                          |
+| Replacing a device lab                     | `deploy` drives one device over Device Portal; orchestration is yours                                       |
+
+---
+
+## Architecture (host tools)
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Your app build (elsewhere)                                 │
+│  produces: PE/DLLs + assets + AppxManifest.xml              │
+└────────────────────────────┬────────────────────────────────┘
+                             │ layout directory
+                             ▼
+┌─────────────────────────────────────────────────────────────┐
+│  openappx                                                   │
+│  validate → blockmap → content types → zip (.msix)          │
+│  [optional] sign → AppxSignature.p7x → deploy to a device   │
+└────────────────────────────┬────────────────────────────────┘
+                             │ .msix
+                             ▼
+┌─────────────────────────────────────────────────────────────┐
+│  Install / sideload / store upload (your process)           │
+└─────────────────────────────────────────────────────────────┘
+```
+
+See [docs/architecture.md](docs/architecture.md) for the layers and extension
+points, and [docs/format.md](docs/format.md) for the container and blockmap rules
+— each recorded with the measurement that established it, since several are not
+what the specification suggests.
+
+---
+
+## Quickstart
+
+```bash
+# From repo root (no install required)
+./scripts/pack.sh --root examples/minimal-layout --out /tmp/example.msix
+
+unzip -l /tmp/example.msix | head
+```
+
+`scripts/pack.sh` is a thin wrapper that puts `src/` on `PYTHONPATH`. The equivalent
+without the wrapper:
+
+```bash
+PYTHONPATH=src python3 -m openappx.pack --root examples/minimal-layout --out /tmp/example.msix
+```
+
+With an editable install:
+
+```bash
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+openappx pack --root examples/minimal-layout --out /tmp/example.msix
+pytest -q
+```
+
+### Layout contract
+
+A pack root must contain at least:
+
+```
+AppxManifest.xml
+…payload files referenced by the manifest (exe, logos, etc.)
+```
+
+openappx **writes** (do not pre-seed):
+
+- `[Content_Types].xml`
+- `AppxBlockMap.xml`
+- `AppxSignature.p7x` — written by `openappx sign`, never by `pack`
+
+---
+
+## CLI
+
+```text
+openappx pack --root DIR --out FILE.msix [options]
+
+  --backend python|makemsix   default: python (unsigned)
+  --makemsix PATH             makemsix binary (default: tools/bin/makemsix)
+  --allow-missing             pack even if validation reports gaps
+```
+
+```text
+openappx sign --package FILE.msix --pfx CERT.pfx
+openappx sign --make-test-cert "CN=Publisher" --cert-out mycert
+openappx validate --root DIR      # check a layout before packing
+openappx unpack --package FILE.msix --out DIR
+openappx inspect --package FILE.msix [--json]
+openappx deploy --device URL --user NAME --package FILE.msix [--insecure]
+openappx bundle --package A.msix --package B.msix --out X.msixbundle
+```
+
+A bundle carries one application across architectures, plus any resource
+packages. **Sign the packages first, then the bundle** — signing only the
+container is rejected as if the container were unsigned:
+
+```bash
+openappx sign --package app-x64.msix --pfx cert.pfx
+openappx sign --package app-x86.msix --pfx cert.pfx
+openappx bundle --package app-x64.msix --package app-x86.msix --out app.msixbundle
+openappx sign --package app.msixbundle --pfx cert.pfx
+```
+
+`inspect` is the read side of `pack`: it re-derives every block hash from the bytes
+stored in the archive and compares them with `AppxBlockMap.xml`, checks `LfhSize`
+against the ZIP local headers actually written, and verifies that `[Content_Types].xml`
+covers every part. On a signed package it also recomputes the digests the signature
+covers and reports any mismatch — see [docs/signing.md](docs/signing.md). It works on
+packages produced by any tool, not just openappx.
+
+```text
+Package: /tmp/example.msix (3139 bytes)
+Identity: Name=OpenAppx.Example  Publisher=CN=OpenAppx-Example  Version=0.1.0.0  ProcessorArchitecture=x64
+Signature: absent
+
+Part                        Size      Stored   Method  Blocks
+app.exe                       31          31    store       1
+AppxManifest.xml            1659         737  deflate       1
+Assets/StoreLogo.png          67          66  deflate       1
+[Content_Types].xml         1061        1061    store       -
+AppxBlockMap.xml             610         610    store       -
+
+OK: blockmap and content types are consistent with the archive
+```
+
+### Deploying to a device
+
+`deploy` talks to the [Windows Device Portal](https://learn.microsoft.com/en-us/windows/uwp/debug-test-perf/device-portal),
+the same REST service on Xbox, HoloLens, IoT and Windows desktop — so a real
+device tells you whether a package is actually installable:
+
+```bash
+export OPENAPPX_DEVICE_PASSWORD='…'        # keeps it out of `ps`
+openappx deploy --device https://192.168.1.50:11443 --user devuser \
+  --package example.msix --insecure
+```
+
+- The device must be in **Developer Mode** with Device Portal enabled
+  (on Xbox: Dev Home → Home → Remote Access → Remote Access Settings).
+- `--insecure` is required because devices serve a self-signed certificate.
+- CSRF is handled by the cookie-to-header handshake the Device Portal UI uses
+  (`CSRF-Token` cookie → `X-CSRF-Token` header). `--csrf-bypass` switches to
+  Microsoft's `auto-<username>` escape hatch instead; that account must then
+  never be used in the web UI.
+- `--list` shows installed packages, `--uninstall PACKAGE_FULL_NAME` removes one,
+  `--install-cert CERT.cer` trusts a certificate on the device.
+
+**Sideloading requires a signed package** and a certificate the device trusts.
+The full loop, entirely from Linux:
+
+```bash
+openappx sign --make-test-cert "CN=OpenAppx-Example" --cert-out mycert
+openappx deploy --device https://<ip>:11443 --user NAME --install-cert mycert.cer
+openappx pack --root examples/resource-only --out app.msix
+openappx sign --package app.msix --pfx mycert.pfx --timestamp
+openappx deploy --device https://<ip>:11443 --user NAME --package app.msix
+```
+
+`examples/resource-only/` is the layout this loop was verified with: it installs
+on an Xbox One dev kit. `examples/minimal-layout/` shows a desktop full-trust
+manifest instead, and deliberately ships a placeholder executable, so it packs
+and signs but stops at the deployment stage.
+
+Signing needs `pip install 'openappx[sign]'`; everything else is stdlib-only.
+[docs/signing.md](docs/signing.md) has the format details and the console
+responses that verify each step.
+
+Exit codes: `0` success, `1` failure (pack error, a failed deploy, or problems
+found by `validate` / `inspect`), `2` bad usage or an unreadable input.
+
+Without an editable install, replace `openappx pack` with
+`PYTHONPATH=src python3 -m openappx.pack` (same for `validate` and `inspect`).
+
+---
+
+## Optional: makemsix backend
+
+Microsoft’s open-source MSIX SDK can pack on Linux when built with pack support:
+
+```bash
+./scripts/bootstrap-makemsix.sh   # may fail on bleeding-edge toolchains
+openappx pack --backend makemsix --root … --out …
+```
+
+It produces **unsigned** packages, exactly like the Python backend: `makemsix pack`
+takes only `-d`/`-p`, and upstream implements signature _validation_, not creation.
+See [docs/signing.md](docs/signing.md). The pure-Python backend remains the default
+and is the one covered by the test suite.
+
+---
+
+## Project layout
+
+```
+openappx/
+├── src/openappx/
+│   ├── cli.py         # the `openappx` entry point; dispatches lazily
+│   ├── blockmap.py    # block hashing, XML rendering, ZIP header parsing
+│   ├── pack_core.py   # the ZIP writer and the two pack backends
+│   ├── pack.py        # pack CLI
+│   ├── bundle.py      # .msixbundle assembly
+│   ├── validate.py    # pre-pack layout checks
+│   ├── inspect.py     # post-pack package and bundle checks
+│   ├── unpack.py      # extract a layout back out of a package
+│   ├── deploy.py      # Windows Device Portal client
+│   └── sign/          # digests, DER encoder, signature creation
+├── docs/
+│   ├── architecture.md   # the layers and where to extend them
+│   ├── format.md         # container and blockmap rules, with their evidence
+│   ├── signing.md        # what AppxSignature.p7x contains, decoded
+│   └── roadmap.md        # done, not done, and why
+├── examples/
+│   ├── minimal-layout/   # desktop, full-trust; placeholder exe, so it never installs
+│   └── resource-only/    # installs on a device — used to prove the chain
+├── tests/
+└── scripts/
+```
+
+---
+
+## Known limits
+
+| Limit             | Detail                                                                                                                                                                                                         |
+| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Files above 4 GiB | Cannot be carried. Describing one needs ZIP64 extra fields on the record, and a device refuses a package with those (`0x8007000B`) — see [docs/format.md](docs/format.md). `pack` fails with that explanation. |
+| Memory            | `pack` builds the archive in memory: fine for tens of MB, not for GB.                                                                                                                                          |
+| Running an app    | Packages are proven to **install**. None has been seen to run: the test console refuses to launch every sideloaded package, Microsoft Edge included, so it cannot answer the question either way.              |
+| Timestamping      | `--timestamp` implemented; that Windows honours it past certificate expiry is untestable here.                                                                                                                 |
+| Bundles           | A bundle mixing an application and a language pack registers only if both `resources.pri` merge; ours do not yet (`0x80070002`).                                                                               |
+| CodeIntegrity     | `AppxMetadata/CodeIntegrity.cat` is verified when present, never generated. It matters only where Device Guard is enforced.                                                                                    |
+| Certificate trust | `inspect` reports the signer and checks publisher agreement and expiry, but never the chain of trust.                                                                                                          |
+
+## Roadmap
+
+Pack, sign, bundle and deploy are done and verified on hardware. What remains is
+in [docs/roadmap.md](docs/roadmap.md), with the reason for each: streaming pack,
+`CodeIntegrity.cat`, and merged resource bundles.
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for setup and the checks CI runs, and
+[SECURITY.md](SECURITY.md) for how keys, device credentials and untrusted
+archives are handled.
+
+The short version: keep the default pack path dependency-free, and when a format
+detail is in doubt, verify it against a real package or a real device rather than
+against the specification — that is how every serious bug here was found.
+
+## License
+
+MIT — see [LICENSE](LICENSE).