PKPass manifest and package structure explained

The package is a ZIP archive with a different extension. At minimum, a distributable pass contains pass.json, manifest.json, signature, and the artwork required by its design. Files belong at the archive root; localization resources live in language-specific .lproj directories beneath that root.

Each manifest key is the relative path of a packaged file and each value is its SHA-1 digest. That digest changes when metadata, compression, color profiles, JSON whitespace, or any other byte changes. Generate hashes from the exact files that will be zipped.

The manifest normally excludes itself and signature. It includes pass.json, images, localized strings, and every other resource the pass relies on. A verifier should reject missing referenced files and mismatched hashes.

The detached PKCS#7 signature covers manifest.json. Because the manifest covers the other files, the signature indirectly protects the complete package. This chain only works when both checks are performed: signature against manifest, and every manifest digest against its file.

This is why changing an image after signing invalidates the pass even though the signature file itself still parses. The manifest no longer describes the current image bytes.

Wrapper folders happen when the directory is zipped rather than its contents. Case mismatches happen when development runs on a case-insensitive filesystem but verification is case-sensitive. Hidden macOS metadata adds files that may not belong in the manifest, and duplicate filenames can cause different ZIP libraries to resolve different bytes.