From 6c13b279fb4df02473b906e54ca90d783063f242 Mon Sep 17 00:00:00 2001 From: Brendan-Lim Date: Mon, 9 Nov 2026 21:22:14 +0800 Subject: [PATCH 1/3] fix: keep Finder installer clean when hidden files are visible --- distribution/dmg/README.md | 8 +++- distribution/dmg/dmg.py | 28 +++++------ docs/dmg-hidden-files-verification.md | 67 +++++++++++++++++++++++++++ scripts/build-app.sh | 8 ++++ scripts/tests/test_dmg.py | 37 ++++++++++++++- 5 files changed, 131 insertions(+), 17 deletions(-) create mode 100644 docs/dmg-hidden-files-verification.md diff --git a/distribution/dmg/README.md b/distribution/dmg/README.md index 616139c..97687d7 100644 --- a/distribution/dmg/README.md +++ b/distribution/dmg/README.md @@ -33,7 +33,11 @@ CONTEXTLENS_SIGN_IDENTITY=- scripts/build-app.sh --output .build/dmg-build Choose a fresh output path. Development images are local engineering artifacts, not accepted official releases. Official candidates use [the separate gated workflow](../../docs/official-release-preparation.md). -The builder verifies the original bundle, copies with `ditto`, adds a real `/Applications` symlink and hidden multi-resolution background, creates an HFS+ UDRW staging image, and mounts it at a unique canonical `/private/tmp` path with `-nobrowse -noautoopen`. It writes only that volume's `.DS_Store`, detaches it, and converts to read-only UDZO (zlib level 9). Final promotion uses an exclusive hard link, so even a concurrent build cannot overwrite published bytes. +`build-app.sh` combines the unchanged 1× and 2× artwork into `ContextLens.app/Contents/Resources/InstallerBackground.tiff` **before signing**, for every build channel. Both ZIP and DMG contain that same signed bundle. The DMG builder never adds resources to or re-signs an existing app; rebuild an older bundle before packaging it with this builder. + +The builder verifies the original bundle, copies with `ditto`, adds a real `/Applications` symlink, creates an HFS+ UDRW staging image, and mounts it at a unique canonical `/private/tmp` path with `-nobrowse -noautoopen`. It writes only that volume's `.DS_Store`, whose background alias references the TIFF inside the app package, detaches it, and converts to read-only UDZO (zlib level 9). Final promotion uses an exclusive hard link, so even a concurrent build cannot overwrite published bytes. + +The exact root inventory is `ContextLens.app`, `Applications` and `.DS_Store`. Verification rejects any other entry, including `.background`, `.metadata_never_index`, loose artwork and indexing directories. `.DS_Store` holds Finder's required layout metadata; Finder does not display it even with Show Hidden Files enabled. The old empty `.metadata_never_index` marker was redundant for this read-only disk image. Apple documents that [disk images are not indexed by Spotlight](https://developer.apple.com/library/archive/documentation/Carbon/Conceptual/SpotlightQuery/Concepts/QueryingMetadata.html). The marker was never inside the app and cannot control indexing of an installed copy. Validation checks the UDIF checksum (`hdiutil verify`), filesystem (`diskutil verifyVolume`), bundle identity/version/deployment/architecture, strict signature, executable CLI and help, background alias, complete Finder picture settings and icon locations. Finder requires the fallback `backgroundColorRed`, `backgroundColorGreen` and `backgroundColorBlue` fields even with `backgroundType=2`. Omitting them causes Finder to ignore the picture and icon-size settings despite a valid alias. Verification rejects missing or malformed components. A throwaway `ditto` install copy is verified and compared with the original. Inventory comparison includes every file's SHA-256, executable bit and signed resource/Finder metadata. It ignores timestamps and quarantine, which are container/download properties. Attach and detach happen within a cleanup context even on validation failure; a forced detach fallback can target only the unique mount created by that context. No personal volume is searched by name. @@ -47,7 +51,7 @@ python3 distribution/dmg/generate-background.py /tmp/contextlens-new-designs ## Real Finder checks -Metadata verification does **not** verify Finder rendering. On a disposable GUI Mac, open the actual DMG in light and dark appearances at 1× and Retina where available. Inspect text, precise icons/labels, arrow clearance, window bounds and background sharpness. Drag onto the actual Applications shortcut, eject and launch the installed copy. Record results against the exact candidate hashes using [isolated acceptance](../../docs/beta-acceptance.md). Do not overwrite the owner's installation or capture private desktop content. +Metadata verification does **not** verify Finder rendering. On a disposable GUI Mac, open the actual DMG in light and dark appearances, with Show Hidden Files both disabled and enabled, at 1× and Retina where available. Inspect text, precise icons/labels, arrow clearance, window bounds and background sharpness. Drag onto the actual Applications shortcut, eject and launch the installed copy. Restore the disposable environment's original Finder and appearance settings afterward. Record results against the exact candidate hashes using [isolated acceptance](../../docs/beta-acceptance.md). Do not change the owner's settings, overwrite their installation or capture private desktop content. After capturing only the actual Finder installer window without its shadow, check the rendered artwork as well: diff --git a/distribution/dmg/dmg.py b/distribution/dmg/dmg.py index f350b65..3c3bd39 100644 --- a/distribution/dmg/dmg.py +++ b/distribution/dmg/dmg.py @@ -11,7 +11,7 @@ sys.path.insert(0, str(ROOT / 'scripts')) from release import require, run, verify -ASSETS = Path(__file__).with_name('assets') +BACKGROUND = Path('ContextLens.app/Contents/Resources/InstallerBackground.tiff') POSITIONS = {'ContextLens.app': (214, 254), 'Applications': (506, 254)} BOUNDS = '{{160, 120}, {720, 440}}' @@ -66,7 +66,7 @@ def mounted(image, readonly=True): def configure(mount): from ds_store import DSStore from mac_alias import Alias - alias = Alias.for_file(str((mount / '.background/background.tiff').resolve())).to_bytes() + alias = Alias.for_file(str((mount / BACKGROUND).resolve())).to_bytes() with DSStore.open(str(mount / '.DS_Store'), 'w+') as store: store['.']['vSrn'] = ('long', 1) store['.']['icvl'] = ('type', b'icnv') @@ -99,23 +99,31 @@ def verify_layout(mount): ['backgroundColorRed', 'backgroundColorGreen', 'backgroundColorBlue']), 'Finder picture settings require fallback RGB color components') alias = Alias.from_bytes(options['backgroundImageAlias']) - require(alias.target.posix_path == '/.background/background.tiff' + require(alias.target.posix_path == '/' + BACKGROUND.as_posix() and alias.volume.name == 'ContextLens', 'Background alias points outside this volume') for name, position in POSITIONS.items(): require(tuple(store[name]['Iloc']) == position, 'Finder icon position differs') +def verify_root(mount): + # These are the only authored root entries. Fail closed if artwork, indexing + # markers or any other file/directory would become visible with hidden files on. + require({path.name for path in Path(mount).iterdir()} == + {'ContextLens.app', 'Applications', '.DS_Store'}, 'Unexpected or missing DMG top-level entries') + + def verify_dmg(image, app=None, install_copy=False): image = Path(image).resolve() run('hdiutil', 'verify', image) # Validates the UDIF checksum, separately from SHA-256. with mounted(image) as mount: run('diskutil', 'verifyVolume', mount) + verify_root(mount) shortcut = mount / 'Applications' require(shortcut.is_symlink() and os.readlink(shortcut) == '/Applications' and shortcut.resolve() == Path('/Applications'), 'Applications must be the real destination') bundle = mount / 'ContextLens.app' data = verify(bundle, 'development') - require((mount / '.background/background.tiff').stat().st_size > 0, 'Missing Retina background') + require((mount / BACKGROUND).stat().st_size > 0, 'Missing signed Retina background') verify_layout(mount) contents = inventory(bundle) if app is not None: @@ -130,7 +138,7 @@ def verify_dmg(image, app=None, install_copy=False): return dict(version=data['version'], build=data['build'], architecture='arm64', minimumMacOS=data['minimumMacOS'], sha256=sha256(image), bundleInventorySHA256=hashlib.sha256( __import__('json').dumps(contents, sort_keys=True).encode()).hexdigest(), - mount='pass', filesystem='pass', signature='pass', layoutMetadata='pass', + mount='pass', filesystem='pass', signature='pass', layoutMetadata='pass', rootEntries='pass', copyRoundTrip='pass' if install_copy else 'not-run', finderAppearance='pending-isolated-GUI', applicationFirstLaunch='pending-isolated-GUI') @@ -139,6 +147,7 @@ def build(app, target): app, target = Path(app).resolve(), Path(target).resolve() require(target.suffix == '.dmg' and not target.exists(), 'Choose a new .dmg; replacement is forbidden') verify(app, 'development') + require((app.parent / BACKGROUND).is_file(), 'Build the signed app with its installer background first') original = inventory(app) target.parent.mkdir(parents=True, exist_ok=True) with tempfile.TemporaryDirectory(prefix='.contextlens-dmg-', dir=target.parent) as temporary: @@ -146,19 +155,12 @@ def build(app, target): stage = work / 'root'; stage.mkdir() run('ditto', app, stage / 'ContextLens.app') os.symlink('/Applications', stage / 'Applications') - (stage / '.background').mkdir() - run('sips', '-s', 'format', 'tiff', '-s', 'dpiWidth', '72', '-s', 'dpiHeight', '72', - ASSETS / 'background@1x.png', '--out', work / '1x.tiff') - run('sips', '-s', 'format', 'tiff', '-s', 'dpiWidth', '144', '-s', 'dpiHeight', '144', - ASSETS / 'background.png', '--out', work / '2x.tiff') - run('tiffutil', '-cathidpicheck', work / '1x.tiff', work / '2x.tiff', - '-out', stage / '.background/background.tiff') - (stage / '.metadata_never_index').touch() rw = work / 'staging.dmg' run('hdiutil', 'create', '-srcfolder', stage, '-volname', 'ContextLens', '-fs', 'HFS+', '-format', 'UDRW', rw) with mounted(rw, readonly=False) as mount: configure(mount) verify_layout(mount) + verify_root(mount) compressed = work / 'final.dmg' run('hdiutil', 'convert', rw, '-format', 'UDZO', '-imagekey', 'zlib-level=9', '-o', compressed) result = verify_dmg(compressed, app, install_copy=True) diff --git a/docs/dmg-hidden-files-verification.md b/docs/dmg-hidden-files-verification.md new file mode 100644 index 0000000..8d3f2b3 --- /dev/null +++ b/docs/dmg-hidden-files-verification.md @@ -0,0 +1,67 @@ +# Finder installer hidden-file verification + +Tested on 2026-11-09. This is development packaging evidence, not official release acceptance. No remaining human security case is marked passed. + +## Cause and change + +The old builder explicitly created `.background/background.tiff` and an empty `.metadata_never_index` at the volume root. Finder exposed both root entries when Show Hidden Files was enabled. Hidden flags would not solve that setting. + +`scripts/build-app.sh` now creates `Contents/Resources/InstallerBackground.tiff` inside the app before any signing. The DMG layout alias points into that bundle on the mounted volume. The packager copies the already signed app without modifying or re-signing it. ZIP and DMG therefore share the same resource and signatures. No artwork, positions, labels, version/build, app behavior or production dependency changed. + +The indexing marker is removed. No app or packaging code consumes it. The final image is read-only UDZO, and Apple documents that [disk images are excluded from Spotlight indexing](https://developer.apple.com/library/archive/documentation/Carbon/Conceptual/SpotlightQuery/Concepts/QueryingMetadata.html). The old marker applied to the mounted volume, not an installed app copy. Actual mounting, Finder use, installation and eject were tested without it. + +`verify_root` runs on both the configured staging volume and the final mounted image. Its exact allowed inventory is `ContextLens.app`, `Applications` and `.DS_Store`. It rejects auxiliary artwork, indexing markers, indexing directories and any other extra entry. Finder needs `.DS_Store` for the layout and does not display it with hidden files enabled in the tested GUI. + +## Genuine Finder evidence + +The [disposable prototype run](https://github.com/Brendan-Lim/ContextLens/actions/runs/42623934612) used an ephemeral GitHub-hosted arm64 Mac, macOS 15.8.2, Xcode 26.3, and its real 1024 × 768 desktop at scale 1. The diagnostic branch `qa/dmg-hidden-prototype` applied `qa/prototype.patch` to main `b4453baa79ffe7280ae8af04da13a99ab4b29656` at runtime; production packaging changes remained uncommitted until all four screenshots had been opened and inspected. That patch contains the same packaging implementation and regression tests as this change. + +| Show Hidden Files | Appearance | Actual Finder screenshot inspection | Rendered artwork check | +|---|---|---|---| +| Off | Light | Pass: only real app and Applications icons; complete design | Pass; all five sampled artwork regions exactly match | +| Off | Dark | Pass: correct dark titlebar, unchanged design and labels | Pass; all five regions exactly match | +| On | Light | Pass: no auxiliary icons or overlapping text | Pass; all five regions exactly match | +| On | Dark | Pass: no auxiliary icons or overlapping text | Pass; all five regions exactly match | + +Each setting had successful preference readback. Finder was restarted when changing hidden-file visibility; each case mounted the real read-only DMG at a fresh private mountpoint. Screenshots captured only the actual Finder window using its verified process/window ID. No Finder window or background was simulated. Finder labels, the owned app icon, icon positions, arrow clearance and full visible design were inspected. Original hidden-file and appearance preferences were restored successfully on the disposable runner. The owner's preferences, installation and privacy permissions were not changed. + +The development DMG SHA-256 for this run was `66c077f9c90009fe2f62271f4b046a6618611cd8015a1f4b0c37c58e176ccf25`; its ZIP was `542d0a9156f4dd0b0c37650a5e0e33159ec53a761a6657fabc1d74dc76286dcf`. These are disposable development artifacts, not replacement official candidates. Raw screenshots and diagnostic output were encrypted before upload and decrypted for local inspection. They are not committed as public media. + +The prototype also passed UDIF/filesystem checks, strict signatures, exact root inventory, Finder alias/options/positions, real `/Applications` symlink, normal copy round trip, ZIP/DMG bundle inventory equality, real Finder drag installation, clean mount-context detach and normal launch of the installed copy with one window. Installed version/build was 0.3.1/6. The inventory comparison includes every file's bytes, executable bit, signatures and signed Finder/resource metadata. Archive container bytes are intentionally different. + +On the local arm64 macOS 26.6.2/Xcode 26.6 build, the relocated TIFF was **byte-identical** to the existing mounted candidate's TIFF: SHA-256 `0efcdaf541cbc70bf00b550ae776dca03bba88e4b582cd06952fc32322422a7b`, 952,400 bytes. ImageIO confirmed two representations, 720 × 440 and 1440 × 880, each with decoded pixels exactly matching its source PNG. The combination command is unchanged. A new live Retina-display Finder matrix was not run; retaining both representations is proven separately from the 1× GUI result. + +## Installed-app discovery, investigated separately + +Read-only diagnostics on the owner's Mac confirmed the installed app exists with bundle ID `dev.contextlens.app`, version 0.3.1/build 6, package type `APPL`, display name, executable and icon metadata. `codesign --verify --deep --strict` passed. No `.metadata*` or `.noindex` marker was found inside the app. + +Outside the execution sandbox, `lsregister -dump` contains a correct `/Applications/ContextLens.app` record, with the expected identifier, display name, executable, arm64 slice, icon and version. Launch Services registration is therefore present. The initial sandbox-only lookup could not see that record and is not used as the conclusion. + +`mdls` returned null for bundle identifier, display name and content type. `mdfind` omitted the installed path while returning three other matching paths. `mdutil -s /` and `mdutil -s /System/Volumes/Data` reported `Index is read-only.` Most decisively, `mdimport -t -d2 /Applications/ContextLens.app` successfully used Apple's Application importer and returned the correct identifier, display name and `com.apple.application-bundle` content type. Test mode does not write the index. + +This establishes that bundle metadata is extractable and Launch Services knows the app; it points to Spotlight index state rather than an installer metadata defect. The precise reason for the read-only index/stale result was not established. No Spotlight reset, reindex, registration write, quarantine change or owner configuration change was attempted. + +Reproduce the diagnostics read-only: + +```sh +codesign --verify --deep --strict /Applications/ContextLens.app +plutil -p /Applications/ContextLens.app/Contents/Info.plist +mdls -name kMDItemCFBundleIdentifier -name kMDItemDisplayName -name kMDItemContentType /Applications/ContextLens.app +mdfind 'kMDItemCFBundleIdentifier == "dev.contextlens.app"' +mdutil -s / +mdutil -s /System/Volumes/Data +mdimport -t -d2 /Applications/ContextLens.app +/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister -dump +``` + +Inspect only the relevant Launch Services record; keep raw system diagnostics private. + +## Automated checks and release boundary + +Local `scripts/ci.sh` passed: 117 Swift tests, 49 benchmark Python tests, 82 script tests, 13 package fixtures, 10 deterministic replays, real signed packaging and portability regression, Homebrew syntax/validation, and browser fixtures reproducing 10 defects with 10 passing controls. The two new DMG regression tests failed before the fix and passed afterward. They cover the in-bundle alias and rejection of unexpected top-level entries. + +The initial baseline `scripts/verify.sh` stopped because a fresh worktree had no built `dist/contextlens-cli`. After building the baseline and supplying that CLI, the unchanged baseline gate passed. A sandboxed DMG creation attempt was denied; the same operation succeeded with authorized native tool access. These setup limitations are not reported as product failures. + +Tracked-file, staged-file, full reachable-history and public-link audits passed with zero findings, as did pinned Gitleaks 8.30.1. No approval hashes or security/freshness rules were changed. CI and Publication Security must also pass on the PR before integration. + +The existing unpublished official candidate from prepare run `42614894584`, source `b4453baa79ffe7280ae8af04da13a99ab4b29656`, DMG SHA-256 `e8e7d63c5d604a14f24cffe9596f32fbdcc6eb5d9f4cddfe0643316e039c7cc2`, remains untouched. Integrating these protected packaging inputs requires a **new official preparation and exact-byte acceptance**. No release, stable Homebrew update, auto-merge or human security acceptance is authorized by these development results. diff --git a/scripts/build-app.sh b/scripts/build-app.sh index f89164f..aecb60d 100755 --- a/scripts/build-app.sh +++ b/scripts/build-app.sh @@ -45,6 +45,14 @@ cp "$bin_dir/ContextLens" "$APP/Contents/MacOS/ContextLens" cp "$bin_dir/contextlens-cli" "$APP/Contents/MacOS/contextlens-cli" cp Brand/AppIcon.icns "$APP/Contents/Resources/AppIcon.icns" cp LICENSE "$APP/Contents/Resources/LICENSE" +# Keep Finder artwork inside the package, before signing, so hidden files do not +# expose an auxiliary artwork directory in the installer. ZIP and DMG share it. +sips -s format tiff -s dpiWidth 72 -s dpiHeight 72 \ + distribution/dmg/assets/background@1x.png --out "$build_stage/1x.tiff" >/dev/null +sips -s format tiff -s dpiWidth 144 -s dpiHeight 144 \ + distribution/dmg/assets/background.png --out "$build_stage/2x.tiff" >/dev/null +tiffutil -cathidpicheck "$build_stage/1x.tiff" "$build_stage/2x.tiff" \ + -out "$APP/Contents/Resources/InstallerBackground.tiff" python3 scripts/release.py plist "$APP/Contents/Info.plist" if [[ "$mode" == preview ]]; then python3 scripts/preview-release.py provenance "$preview_version" "$APP" diff --git a/scripts/tests/test_dmg.py b/scripts/tests/test_dmg.py index db8b1b1..535dc1b 100644 --- a/scripts/tests/test_dmg.py +++ b/scripts/tests/test_dmg.py @@ -67,11 +67,16 @@ def setUp(self): self.records = {'.': {}, 'ContextLens.app': {}, 'Applications': {}} store = MagicMock() store.__enter__.return_value = self.records - alias = SimpleNamespace(target=SimpleNamespace(posix_path='/.background/background.tiff'), + self.alias_paths = [] + alias = SimpleNamespace(target=SimpleNamespace(posix_path='/ContextLens.app/Contents/Resources/InstallerBackground.tiff'), volume=SimpleNamespace(name='ContextLens'), to_bytes=lambda: b'alias') + self.alias = alias + def for_file(path): + self.alias_paths.append(path) + return alias modules = { 'ds_store': SimpleNamespace(DSStore=SimpleNamespace(open=lambda *args: store)), - 'mac_alias': SimpleNamespace(Alias=SimpleNamespace(for_file=lambda path: alias, + 'mac_alias': SimpleNamespace(Alias=SimpleNamespace(for_file=for_file, from_bytes=lambda value: alias)), } self.modules = patch.dict(sys.modules, modules) @@ -80,6 +85,13 @@ def setUp(self): configure(Path('/tmp/synthetic-volume')) self.records['.']['icvl'] = (b'type', b'icnv') + def test_background_alias_uses_the_signed_bundle_resource(self): + self.assertEqual(self.alias_paths, [str(Path('/tmp/synthetic-volume/ContextLens.app/Contents/Resources/InstallerBackground.tiff').resolve())]) + verify_layout(Path('/tmp/synthetic-volume')) + self.alias.target.posix_path = '/.background/background.tiff' + with self.assertRaisesRegex(ValueError, 'Background alias'): + verify_layout(Path('/tmp/synthetic-volume')) + def test_picture_requires_every_fallback_color_component(self): options = self.records['.']['icvp'] # This is the original blank-background layout despite a valid alias and artwork. @@ -102,4 +114,25 @@ def test_complete_picture_settings_and_each_missing_or_malformed_component(self) options[channel] = 1.0 +class InstallerRootTests(unittest.TestCase): + def test_only_the_app_shortcut_and_finder_store_are_allowed(self): + from dmg import verify_root + with tempfile.TemporaryDirectory() as temporary: + mount = Path(temporary) + (mount / 'ContextLens.app').mkdir() + (mount / 'Applications').symlink_to('/Applications') + (mount / '.DS_Store').touch() + verify_root(mount) + for name in ['.background', '.metadata_never_index', 'background.tiff', 'README.txt', '.Spotlight-V100']: + with self.subTest(name=name): + extra = mount / name + extra.touch() + with self.assertRaisesRegex(ValueError, 'top-level'): + verify_root(mount) + extra.unlink() + (mount / '.DS_Store').unlink() + with self.assertRaisesRegex(ValueError, 'top-level'): + verify_root(mount) + + if __name__ == '__main__': unittest.main() From dbeb4d05699c796711c981093bb6ce596f59bf83 Mon Sep 17 00:00:00 2001 From: Brendan-Lim Date: Mon, 9 Nov 2026 21:25:18 +0800 Subject: [PATCH 2/3] docs: record post-eject launch and candidate freshness evidence --- distribution/dmg/README.md | 4 +++- docs/dmg-hidden-files-verification.md | 4 +++- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/distribution/dmg/README.md b/distribution/dmg/README.md index 97687d7..ef93396 100644 --- a/distribution/dmg/README.md +++ b/distribution/dmg/README.md @@ -13,7 +13,7 @@ The selected **Twin Glass** design is a 720 × 440 point icy-blue surface with t | App icon center | (214, 254) | | Applications center | (506, 254) | | Real icon size | 104; labels below, 13 point | -| Background | 720 × 440 at 72 DPI + 1440 × 880 at 144 DPI, combined TIFF | +| Background | 720 × 440 and 1440 × 880 representations, combined TIFF | `assets/background.png` is the chosen 2× artwork; `background@1x.png` is 1×; `composition-b.png` is the alternative. The background has **no app or Applications icons**. The genuine Finder screenshots above show the installed layout. The renderer can also produce an optional labeled design proof in a new output directory; no diagrammatic folder is included in the disk background. Only the real app and `/Applications` symlink supply Finder icons. @@ -51,6 +51,8 @@ python3 distribution/dmg/generate-background.py /tmp/contextlens-new-designs ## Real Finder checks +See the [hidden-file verification report](../../docs/dmg-hidden-files-verification.md) for the disposable Finder matrix and the separate installed-app discovery investigation. + Metadata verification does **not** verify Finder rendering. On a disposable GUI Mac, open the actual DMG in light and dark appearances, with Show Hidden Files both disabled and enabled, at 1× and Retina where available. Inspect text, precise icons/labels, arrow clearance, window bounds and background sharpness. Drag onto the actual Applications shortcut, eject and launch the installed copy. Restore the disposable environment's original Finder and appearance settings afterward. Record results against the exact candidate hashes using [isolated acceptance](../../docs/beta-acceptance.md). Do not change the owner's settings, overwrite their installation or capture private desktop content. After capturing only the actual Finder installer window without its shadow, check the rendered artwork as well: diff --git a/docs/dmg-hidden-files-verification.md b/docs/dmg-hidden-files-verification.md index 8d3f2b3..e89c567 100644 --- a/docs/dmg-hidden-files-verification.md +++ b/docs/dmg-hidden-files-verification.md @@ -29,6 +29,8 @@ The development DMG SHA-256 for this run was `66c077f9c90009fe2f62271f4b046a6618 The prototype also passed UDIF/filesystem checks, strict signatures, exact root inventory, Finder alias/options/positions, real `/Applications` symlink, normal copy round trip, ZIP/DMG bundle inventory equality, real Finder drag installation, clean mount-context detach and normal launch of the installed copy with one window. Installed version/build was 0.3.1/6. The inventory comparison includes every file's bytes, executable bit, signatures and signed Finder/resource metadata. Archive container bytes are intentionally different. +The [follow-up disposable run](https://github.com/Brendan-Lim/ContextLens/actions/runs/42624676375) repeated all four Finder configurations, then explicitly confirmed the tested image was absent from `hdiutil info -plist` after clean detach **before** launching the drag-installed app. That installed copy finished launching with one window and the expected 0.3.1/build 6 metadata. Its four screenshots were also opened and inspected. + On the local arm64 macOS 26.6.2/Xcode 26.6 build, the relocated TIFF was **byte-identical** to the existing mounted candidate's TIFF: SHA-256 `0efcdaf541cbc70bf00b550ae776dca03bba88e4b582cd06952fc32322422a7b`, 952,400 bytes. ImageIO confirmed two representations, 720 × 440 and 1440 × 880, each with decoded pixels exactly matching its source PNG. The combination command is unchanged. A new live Retina-display Finder matrix was not run; retaining both representations is proven separately from the 1× GUI result. ## Installed-app discovery, investigated separately @@ -64,4 +66,4 @@ The initial baseline `scripts/verify.sh` stopped because a fresh worktree had no Tracked-file, staged-file, full reachable-history and public-link audits passed with zero findings, as did pinned Gitleaks 8.30.1. No approval hashes or security/freshness rules were changed. CI and Publication Security must also pass on the PR before integration. -The existing unpublished official candidate from prepare run `42614894584`, source `b4453baa79ffe7280ae8af04da13a99ab4b29656`, DMG SHA-256 `e8e7d63c5d604a14f24cffe9596f32fbdcc6eb5d9f4cddfe0643316e039c7cc2`, remains untouched. Integrating these protected packaging inputs requires a **new official preparation and exact-byte acceptance**. No release, stable Homebrew update, auto-merge or human security acceptance is authorized by these development results. +The existing unpublished official candidate from prepare run `42614894584`, source `b4453baa79ffe7280ae8af04da13a99ab4b29656`, DMG SHA-256 `e8e7d63c5d604a14f24cffe9596f32fbdcc6eb5d9f4cddfe0643316e039c7cc2`, remains untouched; the already-mounted image's supplied checksum was confirmed read-only. The unchanged freshness checker rejects that source's release-input identity against this packaging commit. Integrating these protected packaging inputs requires a **new official preparation and exact-byte acceptance**. No release, stable Homebrew update, auto-merge or human security acceptance is authorized by these development results. From 5b31ae55c676974fa2db8e9396643473dde266ee Mon Sep 17 00:00:00 2001 From: Brendan-Lim Date: Mon, 9 Nov 2026 22:02:03 +0800 Subject: [PATCH 3/3] docs: keep one-off DMG verification report private --- distribution/dmg/README.md | 2 - docs/dmg-hidden-files-verification.md | 69 --------------------------- 2 files changed, 71 deletions(-) delete mode 100644 docs/dmg-hidden-files-verification.md diff --git a/distribution/dmg/README.md b/distribution/dmg/README.md index ef93396..622ee92 100644 --- a/distribution/dmg/README.md +++ b/distribution/dmg/README.md @@ -51,8 +51,6 @@ python3 distribution/dmg/generate-background.py /tmp/contextlens-new-designs ## Real Finder checks -See the [hidden-file verification report](../../docs/dmg-hidden-files-verification.md) for the disposable Finder matrix and the separate installed-app discovery investigation. - Metadata verification does **not** verify Finder rendering. On a disposable GUI Mac, open the actual DMG in light and dark appearances, with Show Hidden Files both disabled and enabled, at 1× and Retina where available. Inspect text, precise icons/labels, arrow clearance, window bounds and background sharpness. Drag onto the actual Applications shortcut, eject and launch the installed copy. Restore the disposable environment's original Finder and appearance settings afterward. Record results against the exact candidate hashes using [isolated acceptance](../../docs/beta-acceptance.md). Do not change the owner's settings, overwrite their installation or capture private desktop content. After capturing only the actual Finder installer window without its shadow, check the rendered artwork as well: diff --git a/docs/dmg-hidden-files-verification.md b/docs/dmg-hidden-files-verification.md deleted file mode 100644 index e89c567..0000000 --- a/docs/dmg-hidden-files-verification.md +++ /dev/null @@ -1,69 +0,0 @@ -# Finder installer hidden-file verification - -Tested on 2026-11-09. This is development packaging evidence, not official release acceptance. No remaining human security case is marked passed. - -## Cause and change - -The old builder explicitly created `.background/background.tiff` and an empty `.metadata_never_index` at the volume root. Finder exposed both root entries when Show Hidden Files was enabled. Hidden flags would not solve that setting. - -`scripts/build-app.sh` now creates `Contents/Resources/InstallerBackground.tiff` inside the app before any signing. The DMG layout alias points into that bundle on the mounted volume. The packager copies the already signed app without modifying or re-signing it. ZIP and DMG therefore share the same resource and signatures. No artwork, positions, labels, version/build, app behavior or production dependency changed. - -The indexing marker is removed. No app or packaging code consumes it. The final image is read-only UDZO, and Apple documents that [disk images are excluded from Spotlight indexing](https://developer.apple.com/library/archive/documentation/Carbon/Conceptual/SpotlightQuery/Concepts/QueryingMetadata.html). The old marker applied to the mounted volume, not an installed app copy. Actual mounting, Finder use, installation and eject were tested without it. - -`verify_root` runs on both the configured staging volume and the final mounted image. Its exact allowed inventory is `ContextLens.app`, `Applications` and `.DS_Store`. It rejects auxiliary artwork, indexing markers, indexing directories and any other extra entry. Finder needs `.DS_Store` for the layout and does not display it with hidden files enabled in the tested GUI. - -## Genuine Finder evidence - -The [disposable prototype run](https://github.com/Brendan-Lim/ContextLens/actions/runs/42623934612) used an ephemeral GitHub-hosted arm64 Mac, macOS 15.8.2, Xcode 26.3, and its real 1024 × 768 desktop at scale 1. The diagnostic branch `qa/dmg-hidden-prototype` applied `qa/prototype.patch` to main `b4453baa79ffe7280ae8af04da13a99ab4b29656` at runtime; production packaging changes remained uncommitted until all four screenshots had been opened and inspected. That patch contains the same packaging implementation and regression tests as this change. - -| Show Hidden Files | Appearance | Actual Finder screenshot inspection | Rendered artwork check | -|---|---|---|---| -| Off | Light | Pass: only real app and Applications icons; complete design | Pass; all five sampled artwork regions exactly match | -| Off | Dark | Pass: correct dark titlebar, unchanged design and labels | Pass; all five regions exactly match | -| On | Light | Pass: no auxiliary icons or overlapping text | Pass; all five regions exactly match | -| On | Dark | Pass: no auxiliary icons or overlapping text | Pass; all five regions exactly match | - -Each setting had successful preference readback. Finder was restarted when changing hidden-file visibility; each case mounted the real read-only DMG at a fresh private mountpoint. Screenshots captured only the actual Finder window using its verified process/window ID. No Finder window or background was simulated. Finder labels, the owned app icon, icon positions, arrow clearance and full visible design were inspected. Original hidden-file and appearance preferences were restored successfully on the disposable runner. The owner's preferences, installation and privacy permissions were not changed. - -The development DMG SHA-256 for this run was `66c077f9c90009fe2f62271f4b046a6618611cd8015a1f4b0c37c58e176ccf25`; its ZIP was `542d0a9156f4dd0b0c37650a5e0e33159ec53a761a6657fabc1d74dc76286dcf`. These are disposable development artifacts, not replacement official candidates. Raw screenshots and diagnostic output were encrypted before upload and decrypted for local inspection. They are not committed as public media. - -The prototype also passed UDIF/filesystem checks, strict signatures, exact root inventory, Finder alias/options/positions, real `/Applications` symlink, normal copy round trip, ZIP/DMG bundle inventory equality, real Finder drag installation, clean mount-context detach and normal launch of the installed copy with one window. Installed version/build was 0.3.1/6. The inventory comparison includes every file's bytes, executable bit, signatures and signed Finder/resource metadata. Archive container bytes are intentionally different. - -The [follow-up disposable run](https://github.com/Brendan-Lim/ContextLens/actions/runs/42624676375) repeated all four Finder configurations, then explicitly confirmed the tested image was absent from `hdiutil info -plist` after clean detach **before** launching the drag-installed app. That installed copy finished launching with one window and the expected 0.3.1/build 6 metadata. Its four screenshots were also opened and inspected. - -On the local arm64 macOS 26.6.2/Xcode 26.6 build, the relocated TIFF was **byte-identical** to the existing mounted candidate's TIFF: SHA-256 `0efcdaf541cbc70bf00b550ae776dca03bba88e4b582cd06952fc32322422a7b`, 952,400 bytes. ImageIO confirmed two representations, 720 × 440 and 1440 × 880, each with decoded pixels exactly matching its source PNG. The combination command is unchanged. A new live Retina-display Finder matrix was not run; retaining both representations is proven separately from the 1× GUI result. - -## Installed-app discovery, investigated separately - -Read-only diagnostics on the owner's Mac confirmed the installed app exists with bundle ID `dev.contextlens.app`, version 0.3.1/build 6, package type `APPL`, display name, executable and icon metadata. `codesign --verify --deep --strict` passed. No `.metadata*` or `.noindex` marker was found inside the app. - -Outside the execution sandbox, `lsregister -dump` contains a correct `/Applications/ContextLens.app` record, with the expected identifier, display name, executable, arm64 slice, icon and version. Launch Services registration is therefore present. The initial sandbox-only lookup could not see that record and is not used as the conclusion. - -`mdls` returned null for bundle identifier, display name and content type. `mdfind` omitted the installed path while returning three other matching paths. `mdutil -s /` and `mdutil -s /System/Volumes/Data` reported `Index is read-only.` Most decisively, `mdimport -t -d2 /Applications/ContextLens.app` successfully used Apple's Application importer and returned the correct identifier, display name and `com.apple.application-bundle` content type. Test mode does not write the index. - -This establishes that bundle metadata is extractable and Launch Services knows the app; it points to Spotlight index state rather than an installer metadata defect. The precise reason for the read-only index/stale result was not established. No Spotlight reset, reindex, registration write, quarantine change or owner configuration change was attempted. - -Reproduce the diagnostics read-only: - -```sh -codesign --verify --deep --strict /Applications/ContextLens.app -plutil -p /Applications/ContextLens.app/Contents/Info.plist -mdls -name kMDItemCFBundleIdentifier -name kMDItemDisplayName -name kMDItemContentType /Applications/ContextLens.app -mdfind 'kMDItemCFBundleIdentifier == "dev.contextlens.app"' -mdutil -s / -mdutil -s /System/Volumes/Data -mdimport -t -d2 /Applications/ContextLens.app -/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister -dump -``` - -Inspect only the relevant Launch Services record; keep raw system diagnostics private. - -## Automated checks and release boundary - -Local `scripts/ci.sh` passed: 117 Swift tests, 49 benchmark Python tests, 82 script tests, 13 package fixtures, 10 deterministic replays, real signed packaging and portability regression, Homebrew syntax/validation, and browser fixtures reproducing 10 defects with 10 passing controls. The two new DMG regression tests failed before the fix and passed afterward. They cover the in-bundle alias and rejection of unexpected top-level entries. - -The initial baseline `scripts/verify.sh` stopped because a fresh worktree had no built `dist/contextlens-cli`. After building the baseline and supplying that CLI, the unchanged baseline gate passed. A sandboxed DMG creation attempt was denied; the same operation succeeded with authorized native tool access. These setup limitations are not reported as product failures. - -Tracked-file, staged-file, full reachable-history and public-link audits passed with zero findings, as did pinned Gitleaks 8.30.1. No approval hashes or security/freshness rules were changed. CI and Publication Security must also pass on the PR before integration. - -The existing unpublished official candidate from prepare run `42614894584`, source `b4453baa79ffe7280ae8af04da13a99ab4b29656`, DMG SHA-256 `e8e7d63c5d604a14f24cffe9596f32fbdcc6eb5d9f4cddfe0643316e039c7cc2`, remains untouched; the already-mounted image's supplied checksum was confirmed read-only. The unchanged freshness checker rejects that source's release-input identity against this packaging commit. Integrating these protected packaging inputs requires a **new official preparation and exact-byte acceptance**. No release, stable Homebrew update, auto-merge or human security acceptance is authorized by these development results.