Skip to content

YC (S26) | Open Computer History | Continuously record your company computer work, map your workflows, help you find work worth automating, and power your agents' context

8.8 KB
Raw Blame

Acquisition handoff

The website companion saves the original, consented browser source and places an opaque download grant in a platform carrier. The app persists a verifier, claims the grant, and binds it using the verified Clerk session. This runs in a background task, independent of recording. All platforms use the same claim, retry, account-boundary, and retirement protocol.

signed/notarized app -> unsigned DMG template -> Worker personalizes app xattr and DMG checksums
  -> Finder copies app -> existing native proof -> claim -> authenticated bind

signed EXE -> untrusted certificate extension -> Worker patches fixed UUID bytes
  -> ordinary browser EXE download -> renamed installer -> installed token
  -> Windows credential-store proof -> claim -> authenticated bind

signed screenpipe-<UUID>.AppImage -> APPIMAGE filename -> credential-store proof
  -> claim -> authenticated bind

AppImage -> PAX tar with user.screenpipe.acquisition-grant -> Worker personalizes xattr
  -> extract preserving xattrs -> APPIMAGE xattr -> existing credential-store proof
  -> claim -> authenticated bind

Retries reuse the same request and verifier. Saved proof survives app updates that remove the xattr. Account switch/logout invalidates in-flight work and saves a retirement marker before changing accounts, without waiting for credential storage. The native settings-store listener also retires immediately on analytics opt-out, including rapid off/on toggles and requests already in flight. A late credential write cannot erase a persisted marker, so restart remains retired. If the filesystem rejects the marker write, retirement is guaranteed only for the current process. Same-account JWT refresh wakes the worker without retiring the acquisition. Missing account provisioning is retried. No token, source data or HTTP error body is logged.

The consumer macOS release job prepares a schema-2 DMG template and manifest for each architecture, alongside the ordinary signed DMG and updater. It builds Mozilla libdmg-hfsplus at e18579b391950589b9ed16ee630c54ce4319bb29 on the existing macOS runner, then runs:

python3 scripts/package-attribution-dmg.py \
  --source /path/to/versioned.dmg --platform macos-arm --release VERSION \
  --dmg-tool /path/to/libdmg-build/dmg/dmg --output /path/to/new-output-directory

The app signature and stapled ticket are validated before and after rebuilding; the rebuilt DMG's checksums and exact app xattr are checked without launching it. The outer DMG is unsigned. The scoped uploader admits only the exact consumer Mac manifest filename; publication pointers and all other JSON names remain forbidden. The website separately evaluates its PostHog rollout and consent/visit proof.

The legacy ZIP carrier remains available for compatibility. Prepare it locally from an already signed/notarized app:

python3 scripts/package-attribution-carrier.py \
  --app /path/to/screenpipe.app --platform macos-arm \
  --release VERSION --output /path/to/new-output-directory

The script checks app version, architecture, signature and metadata round-trip, then writes screenpipe-attribution.zip and screenpipe-attribution.json. For Linux or Windows, pass the original versioned release artifact instead:

python3 scripts/package-attribution-carrier.py \
  --artifact /path/to/versioned-installer \
  --platform linux \
  --release VERSION --output /path/to/new-output-directory

Linux writes screenpipe-attribution.AppImage; Windows and Windows ARM write screenpipe-attribution.exe. Each has a screenpipe-attribution.json manifest containing the original byte length and SHA-256. Windows preparation requires a Windows host and checks Authenticode, version metadata, and architecture evidence in the versioned release filename. The NSIS bootstrap PE machine is not treated as payload architecture. Filename personalization preserves the signed bytes. Use --platform windows for x86_64 and --platform windows-arm for ARM64. The release job additionally prepares screenpipe-attribution-windows.exe and schema-4 screenpipe-attribution-windows.json with --windows-certificate. The EXE contains a fixed placeholder in a noncritical extension of an extra untrusted certificate under UUID-derived OID 2.25.190389607246623950780965390285594181377. The original signed image digest, signer, code and NSIS payload remain unchanged; whole-file SHA-256 changes when the website patches only the manifest's 36-byte range. The installer validates that embedded UUID first, so ordinary browser download, rename, SmartScreen handoff and normal installation require no additional user step.

Legacy browser HostUrl and canonical filename carriers remain fallbacks for already prepared releases. Windows may consume Zone.Identifier before NSIS starts, so origin metadata is not considered durable. The incremental parser still rejects malformed, duplicated, oversized, query-like, or non-HTTPS origin metadata. A closed, privacy-safe diagnostic records the fixed cause, measured boundary or Windows I/O error when applicable, and the actual fallback and persistence outcome; the app validates that protocol before logging it and never logs the URL, grant, installer path, or marker text. ZoneId is not authorization, and the installed app never searches download directories.

For Linux xattr downloads, use the same versioned AppImage with --linux-xattr:

python3 scripts/package-attribution-carrier.py \
  --artifact /path/to/screenpipe_VERSION_amd64.AppImage --platform linux \
  --release VERSION --linux-xattr --output /path/to/new-output-directory

This prepares screenpipe-attribution.tar and screenpipe-attribution-linux.json. The schema-3 manifest identifies carrier: linux-xattr, platform, release, tar size/SHA-256, the placeholder and absolute grant_offset, and the enclosed AppImage name/size/SHA-256. The archive has one executable screenpipe.AppImage with PAX SCHILY.xattr.user.screenpipe.acquisition-grant metadata. The website replaces only the 36-byte opaque UUID in that metadata. AppImage bytes remain unchanged. The consumer Linux release job prepares and uploads these versioned artifacts alongside the ordinary AppImage; dry runs retain both as CI artifacts.

A browser cannot directly set this custom xattr on a raw HTTP download. Extract the personalized tar with an extractor that preserves Linux xattrs; GNU tar requires the explicit flag:

tar --xattrs -xf screenpipe-attribution.tar
./screenpipe.AppImage

The app reads the original path from APPIMAGE, preferring its xattr to the legacy filename grant. Renaming on the same filesystem preserves the xattr. Extraction without xattrs or copying to a filesystem that strips them loses optional attribution for this archive. Existing personalized raw AppImages continue to use their filenames. Missing or malformed carriers do not prevent recording; unreadable or invalid attributes report the failure category and expected UUID width without logging the grant or local file path. The saved proof, consent, account and retirement rules are unchanged.

The script never uploads artifacts or changes publication pointers. Production activation and versioned-artifact publication have not been performed. Human publication remains required. An ordinary, unpersonalized download installs and runs normally without optional attribution. A same-volume rename preserves Windows attribution when the browser attached a valid origin stream; filesystems or transfer tools that strip the stream fall back to the renamed filename. Renaming a personalized raw Linux download before its first launch can lose attribution.

The signature-exempt xattr and ZIP extraction behavior are documented by Apple Developer Technical Support. There is no ZIP or user-supplied sidecar for Windows. NSIS saves the first valid grant beside the installed executable and updates never replace it. Linux reads only the original AppImage path supplied by APPIMAGE.

Before enabling website carrier admission, verify actual production artifacts, app startup, restart, login/logout, trial/purchase, updater recovery, and provider readback. The macOS test uses an ad-hoc signed fixture; Windows NSIS tests exercise the real grant macro but mock installer signature/version metadata boundaries; Linux packaging uses a synthetic AppImage header. The Linux carrier regression also runs GNU tar with and without xattrs and checks rename and fresh-process readback. Native reader tests exercise filesystem attributes, UUID validation, rename and filename compatibility on Unix. These tests do not prove the full production download or signing path.