Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 2 additions & 3 deletions distribution/homebrew/Casks/contextlens-preview.rb.in
Original file line number Diff line number Diff line change
@@ -1,9 +1,8 @@
cask "contextlens-preview" do
version "__VERSION__,__ASSET_ID__"
version "__VERSION__"
sha256 "__SHA256__"

url "https://api.github.com/repos/bstack-tools/ContextLens/releases/assets/#{version.csv.second}",
header: "Accept: application/octet-stream"
url "https://github.com/bstack-tools/ContextLens/releases/download/v#{version}/ContextLens-#{version}-arm64.zip"
name "ContextLens Preview"
desc "Unnotarized preview of local window capture for coding agents"
homepage "https://github.com/bstack-tools/ContextLens/"
Expand Down
11 changes: 6 additions & 5 deletions distribution/homebrew/scripts/validate.py
Original file line number Diff line number Diff line change
Expand Up @@ -47,21 +47,22 @@
preview_template = root / 'Casks/contextlens-preview.rb.in'
if preview_template.exists():
preview = preview_template.read_text()
assert preview.count('__VERSION__') == preview.count('__SHA256__') == preview.count('__ASSET_ID__') == 1
assert preview.count('__VERSION__') == preview.count('__SHA256__') == 1 and '__ASSET_ID__' not in preview
for stanza in ['cask "contextlens-preview"', 'conflicts_with cask: "contextlens"',
'depends_on arch: :arm64', 'depends_on macos: :sonoma',
'app "ContextLens.app"', 'binary "#{appdir}/ContextLens.app/Contents/MacOS/contextlens-cli"',
'Unnotarized', 'Open Anyway', 'header: "Accept: application/octet-stream"', 'container type: :zip']:
'Unnotarized', 'Open Anyway', 'container type: :zip',
'url "https://github.com/bstack-tools/ContextLens/releases/download/v#{version}/ContextLens-#{version}-arm64.zip"']:
assert stanza in preview, stanza
for forbidden in [':no_check', 'zap ', 'xattr ', 'spctl ', '--no-quarantine']:
assert forbidden not in preview, forbidden
subprocess.run(['ruby', '-c', str(preview_template)], check=True)
actual_path = root / 'Casks/contextlens-preview.rb'
if actual_path.exists():
actual = actual_path.read_text()
version = re.search(r'^ version "([0-9]+\.[0-9]+\.[0-9]+-preview\.[1-9][0-9]*),([1-9][0-9]*)"$', actual, re.M)
version = re.search(r'^ version "([0-9]+\.[0-9]+\.[0-9]+-preview\.[1-9][0-9]*)"$', actual, re.M)
checksum = re.search(r'^ sha256 "([a-f0-9]{64})"$', actual, re.M)
assert version and checksum, 'Real preview version, SHA-256 and asset ID required'
assert actual == preview.replace('__VERSION__', version[1]).replace('__SHA256__', checksum[1]).replace('__ASSET_ID__', version[2])
assert version and checksum, 'Real preview version and SHA-256 required'
assert actual == preview.replace('__VERSION__', version[1]).replace('__SHA256__', checksum[1])
subprocess.run(['ruby', '-c', str(actual_path)], check=True)
print('Preview cask syntax/metadata validated; installation and authorization are separate checks.')
4 changes: 2 additions & 2 deletions docs/preview-releases.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ Verified on a disposable arm64 macOS 15.8.2 runner with Homebrew 7.0.12. After i

Public archive SHA-256: `42373a29db99f592583d5dcaff1574ae6d75b34481b1fb8a3fa44e1217ea2a2d`.

During verification GitHub's browser asset URL returned HTTP 504, while the official public asset API served the identical ZIP without credentials. The preview cask uses that immutable asset ID with `Accept: application/octet-stream` and the same SHA-256. Its Homebrew version combines preview version and asset ID as `0.3.1-preview.2,776028347`. No account, token or compiler is required. If the release page download fails, this credential-free download was tested:
The cask downloads the release's normal browser URL with the same SHA-256. No account, token or compiler is required. Earlier casks used the REST asset API (`api.github.com/…/releases/assets/ID`) because the browser URL returned HTTP 504 once during the 0.3.0 verification. That API allows only 60 anonymous requests per hour per IP address, so installs failed with HTTP 403 on shared runners and could fail on shared networks; the browser URL has no such limit. Because the cask now names the prerelease tag directly, the tap lists `contextlens-preview` in `audit_exceptions/github_prerelease_allowlist.json` so `brew audit --online` accepts a preview-only cask. If the release page download fails, the same file is also available without credentials from the asset API:

```sh
curl --fail --location --header 'Accept: application/octet-stream' \
Expand Down Expand Up @@ -67,7 +67,7 @@ gh repo clone Brendan-Lim/homebrew-tap /tmp/contextlens-preview-tap
python3 scripts/preview-release.py update-tap 0.3.1-preview.3 /tmp/contextlens-preview-tap
```

This checks official browser/API URLs and asset IDs, uploaded assets, downloaded checksum, preview trust label, signatures, portable arm64 bundle, receipt and matching source tag before rendering `Casks/contextlens-preview.rb`. It cannot generate a cask for a draft or stable release or a fabricated checksum. It never changes `Casks/contextlens.rb` or its template. Run tap validation, `brew style`, online audit, download verification and the disposable hosted installation check on a candidate branch before publishing the tap's main branch. Then update the status here with evidence. No cross-repository secret is needed; use existing maintainer authorization.
This checks official browser/API URLs, uploaded assets, downloaded checksum, preview trust label, signatures, portable arm64 bundle, receipt and matching source tag before rendering `Casks/contextlens-preview.rb`. It cannot generate a cask for a draft or stable release or a fabricated checksum. It never changes `Casks/contextlens.rb` or its template. Run tap validation, `brew style`, online audit, download verification and the disposable hosted installation check on a candidate branch before publishing the tap's main branch. Then update the status here with evidence. No cross-repository secret is needed; use existing maintainer authorization.

## Installation verification

Expand Down
10 changes: 5 additions & 5 deletions scripts/preview-release.py
Original file line number Diff line number Diff line change
Expand Up @@ -175,12 +175,13 @@ def published_assets(info, version):
f'https://api.github.com/repos/{REPO}/releases/assets/{asset_id}', 'Unexpected preview API asset URL')


def render_cask(version, checksum, asset_id):
def render_cask(version, checksum):
# The cask downloads the release's browser URL (verified by published_assets),
# not the REST asset API, whose anonymous limit is 60 requests/hour per IP.
preview_version(version)
require(re.fullmatch(r'[0-9a-f]{64}', checksum), 'Actual SHA-256 required')
require(type(asset_id) is int and asset_id > 0, 'Actual positive GitHub asset ID required')
return (ROOT / 'distribution/homebrew/Casks/contextlens-preview.rb.in').read_text().replace(
'__VERSION__', version).replace('__SHA256__', checksum).replace('__ASSET_ID__', str(asset_id))
'__VERSION__', version).replace('__SHA256__', checksum)


def update_tap(tap, version):
Expand All @@ -199,8 +200,7 @@ def update_tap(tap, version):
receipt = verify_archive(Path(temporary) / name, version)
commit = json.loads(run('gh', 'api', f'repos/{REPO}/commits/v{version}'))
require(receipt['sourceCommit'] == commit['sha'], 'Preview tag differs from archive source')
asset = next(a for a in info['assets'] if a['name'] == name)
contents = render_cask(version, receipt['sha256'], asset['id'])
contents = render_cask(version, receipt['sha256'])
target = tap / 'Casks/contextlens-preview.rb'
if target.exists():
old = re.search(r'^ version "(.+)"$', target.read_text(), re.M)
Expand Down
18 changes: 10 additions & 8 deletions scripts/tests/test_preview_release.py
Original file line number Diff line number Diff line change
Expand Up @@ -79,15 +79,17 @@ def test_preview_receipt_cannot_claim_stable_trust(self):
execute.assert_not_called()

def test_cask_requires_actual_sha_and_discloses_trust(self):
with self.assertRaises(ValueError): preview.render_cask(VERSION, 'fake', 123)
for asset_id in [0, -1, True, '123/../456', '123;echo x']:
with self.subTest(asset_id=asset_id), self.assertRaises(ValueError):
preview.render_cask(VERSION, 'a' * 64, asset_id)
text = preview.render_cask(VERSION, 'a' * 64, 123)
with self.assertRaises(ValueError): preview.render_cask(VERSION, 'fake')
for version in ['0.3.1', '0.3.1-preview.0', '0.3.1-preview.1;echo x']:
with self.subTest(version=version), self.assertRaises(ValueError):
preview.render_cask(version, 'a' * 64)
text = preview.render_cask(VERSION, 'a' * 64)
self.assertIn('cask "contextlens-preview"', text)
self.assertIn(f'version "{VERSION},123"', text)
self.assertIn('https://api.github.com/repos/bstack-tools/ContextLens/releases/assets/#{version.csv.second}', text)
self.assertIn('Accept: application/octet-stream', text)
self.assertIn(f'version "{VERSION}"', text)
# Browser download URL, not the rate-limited anonymous REST asset API.
self.assertIn('url "https://github.com/bstack-tools/ContextLens/releases/download/v#{version}/ContextLens-#{version}-arm64.zip"', text)
self.assertNotIn('api.github.com', text)
self.assertNotIn('__', text)
self.assertIn('conflicts_with cask: "contextlens"', text)
self.assertIn('Unnotarized', text)
self.assertIn('Open Anyway', text)
Expand Down
Loading