diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index df3570a6b..0cf8a5012 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -152,7 +152,7 @@ jobs: # RELEASE_TOKEN's release fires `release: published` in them already if: env.EXISTING != 'true' && env.HAS_RELEASE_TOKEN != 'true' run: | - for workflow in cloudron.yml qnap.yml synology.yml launchers.yml browser-extension.yml; do + for workflow in cloudron.yml qnap.yml synology.yml launchers.yml browser-extension.yml safari-clipper.yml; do if [ ! -f ".github/workflows/$workflow" ]; then echo "$workflow isn't in $TAG; skipped" elif gh workflow run "$workflow" --ref "$TAG" -f tag="$TAG"; then diff --git a/.github/workflows/safari-clipper.yml b/.github/workflows/safari-clipper.yml new file mode 100644 index 000000000..aa94e1eab --- /dev/null +++ b/.github/workflows/safari-clipper.yml @@ -0,0 +1,62 @@ +name: Safari clipper + +# The web clipper wrapped as a Safari Web Extension (a macOS app carrying it), built on macOS with Xcode. On a pull +# request that changes the extension it's built and kept with the run; on a release, or a workflow_dispatch with +# `tag`, it's attached to the release and, when the App Store Connect secrets are set (APPLE_TEAM_ID, APPLE_API_KEY_ID, +# APPLE_API_ISSUER, APPLE_API_KEY_P8), signed and uploaded there, which is how Safari users get updates. The zip is +# unsigned; without the secrets the upload is skipped. +on: + release: + types: [published] + workflow_dispatch: + inputs: + tag: + description: "Release tag to attach the Safari clipper to; blank: build this ref" + default: "" + pull_request: + paths: + - extensions/browser/** + - .github/workflows/safari-clipper.yml + +permissions: + contents: read + +jobs: + safari: + name: Build the Safari clipper + runs-on: macos-latest + permissions: + contents: write # to attach it to the release + env: + APPLE_API_KEY_ID: ${{ secrets.APPLE_API_KEY_ID }} + steps: + - uses: actions/checkout@v4 + with: + ref: ${{ inputs.tag || github.ref }} + - uses: actions/setup-node@v7 + with: + node-version: 22 + cache: npm + cache-dependency-path: extensions/browser/package-lock.json + - name: Build + env: + EXT_VERSION: ${{ github.event.release.tag_name || inputs.tag }} + run: extensions/browser/safari/build.sh "$RUNNER_TEMP/safari" + - uses: actions/upload-artifact@v7 + with: + name: lens-clipper-safari + path: ${{ runner.temp }}/safari/lens-clipper-safari-app.zip + - name: Attach to the release + if: github.event_name == 'release' || inputs.tag != '' + env: + GH_TOKEN: ${{ github.token }} + TAG: ${{ github.event.release.tag_name || inputs.tag }} + run: gh release upload "$TAG" "$RUNNER_TEMP/safari/lens-clipper-safari-app.zip" --clobber --repo "${{ github.repository }}" + - name: Upload to App Store Connect + if: (github.event_name == 'release' || inputs.tag != '') && env.APPLE_API_KEY_ID != '' + env: + APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }} + APPLE_API_ISSUER: ${{ secrets.APPLE_API_ISSUER }} + APPLE_API_KEY_P8: ${{ secrets.APPLE_API_KEY_P8 }} + BUILD_NUMBER: ${{ github.run_number }}.${{ github.run_attempt }} + run: extensions/browser/safari/app-store.sh "$RUNNER_TEMP/safari" diff --git a/docs/web-clipper.md b/docs/web-clipper.md index c773cc966..c2679b7a5 100644 --- a/docs/web-clipper.md +++ b/docs/web-clipper.md @@ -116,7 +116,7 @@ are set, and is skipped otherwise: | Edge | Microsoft Edge Add-ons: each release is uploaded and submitted | `EDGE_PRODUCT_ID`, `EDGE_CLIENT_ID`, `EDGE_API_KEY` | | Chrome, Edge (self-hosted) | `lens-clipper-.crx`, which checks `lens-clipper--updates.xml` on the newest release | `CRX_PRIVATE_KEY` | | Firefox | the Mozilla-signed `lens-clipper-firefox.xpi`, which checks `lens-clipper-firefox-updates.json` on the newest release | `AMO_JWT_ISSUER`, `AMO_JWT_SECRET` | -| Safari | the App Store, from the Safari build | see the Safari section | +| Safari | the App Store, from the Safari build | `APPLE_*`, see [Safari](#safari) | - Chrome and Edge only install a `.crx` from outside their stores through policy (`ExtensionInstallForcelist` with the update XML's address) or on Linux. For everyone else the stores are the way to get updates. @@ -124,3 +124,26 @@ are set, and is skipped otherwise: key makes a different extension. - The self-hosted builds are `dist/-selfhosted`. They are built when `EXT_UPDATE_BASE` is set, which a release sets to its `releases/latest/download` address, so every installed copy finds the newest version. + +## Safari + +Safari runs the same clipper, carried inside a small macOS app (**Lens Clipper.app**). Each release has +`lens-clipper-safari-app.zip` attached; to build it yourself on a Mac with Xcode, run `extensions/browser/safari/build.sh`. + +To install the zip: unzip it, move **Lens Clipper.app** to Applications and open it once. In Safari, turn on +**Settings > Advanced > Show features for web developers** and **Develop > Allow Unsigned Extensions**, then enable +Lens Clipper in **Settings > Extensions**. The zip is unsigned, so Safari forgets that allowance each time it restarts. +Safari asks before the clipper reads a site; allow your Lens server and the pages you clip. + +**Updates:** Safari extensions update only through the App Store. When the repository has the App Store Connect +secrets, the Safari clipper workflow signs each release and uploads it there: + +| Secret | What it is | +| --- | --- | +| `APPLE_TEAM_ID` | Your Apple Developer team id | +| `APPLE_API_KEY_ID`, `APPLE_API_ISSUER` | An App Store Connect API key with the Admin role (Users and Access > Integrations), and its issuer id | +| `APPLE_API_KEY_P8` | The contents of that key's `AuthKey_….p8` file | + +Create the app's record in App Store Connect once, with the bundle id `dev.lens.clipper`. Each upload then shows up in +TestFlight, which keeps testers up to date; submit a build for review to release it on the Mac App Store, where Safari +updates it for everyone. Without the secrets the upload is skipped and only the zip is attached. diff --git a/extensions/browser/safari/README.md b/extensions/browser/safari/README.md new file mode 100644 index 000000000..0c5d54ab6 --- /dev/null +++ b/extensions/browser/safari/README.md @@ -0,0 +1,27 @@ +# Lens web clipper for Safari + +Safari runs the same clipper as Chrome and Firefox; `targets/safari.json` is all that changes in its manifest, and +`build.sh` wraps that build in the small macOS app Safari needs to carry an extension. + +```sh +extensions/browser/safari/build.sh # macOS with Xcode; writes dist/safari-app/lens-clipper-safari-app.zip +``` + +To use it: unzip, move **Lens Clipper.app** to Applications and open it once, then in Safari turn on +**Settings > Advanced > Show features for web developers**, **Develop > Allow Unsigned Extensions**, and enable +Lens Clipper in **Settings > Extensions**. Safari asks before the clipper reads a site; allow your Lens server and the +pages you clip. + +The CI build (the Safari clipper workflow) runs on every pull request that touches the extension and attaches the +zip to each release. + +- **Updates:** Safari extensions update only through the App Store. With the App Store Connect secrets set + (`APPLE_TEAM_ID`, `APPLE_API_KEY_ID`, `APPLE_API_ISSUER`, `APPLE_API_KEY_P8`), each release is signed and uploaded by + `app-store.sh`; testers get it through TestFlight, everyone else once it's released on the Mac App Store. See + [the Safari section of the docs](../../../docs/web-clipper.md#safari). +- **Signing:** the zip is unsigned and has to be re-allowed each time Safari restarts. +- **Permissions:** Safari grants hosts per site whatever the manifest says, so the Safari build lists them as + `host_permissions` rather than optional ones; the options page still asks for your Lens server. +- **Settings:** `SAFARI_APP_NAME` and `SAFARI_BUNDLE_ID` (default `dev.lens.clipper`) change the app's name and id. + +Refine later: ship it inside the Lens macOS app, an iOS/iPadOS build, App Store listing. diff --git a/extensions/browser/safari/app-store.sh b/extensions/browser/safari/app-store.sh new file mode 100755 index 000000000..50b4508a2 --- /dev/null +++ b/extensions/browser/safari/app-store.sh @@ -0,0 +1,45 @@ +#!/bin/sh +# Archives the Xcode project build.sh generated and uploads it to App Store Connect, the only way Safari extensions +# update: testers get each upload through TestFlight, everyone else once it's released on the Mac App Store. Signs with +# Xcode's cloud signing through an App Store Connect API key (Admin role), so no certificates need importing: +# APPLE_TEAM_ID, APPLE_API_KEY_ID, APPLE_API_ISSUER, APPLE_API_KEY_P8 (the contents of the AuthKey_….p8 file) +# The app's record (bundle id dev.lens.clipper, or SAFARI_BUNDLE_ID) has to exist in App Store Connect first. +# +# safari/app-store.sh [out-dir] (the one build.sh wrote; default: dist/safari-app) +set -eu + +here=$(cd "$(dirname "$0")/.." && pwd) +out=$(cd "${1:-$here/dist/safari-app}" && pwd) +app_name=${SAFARI_APP_NAME:-Lens Clipper} +: "${APPLE_TEAM_ID:?}" "${APPLE_API_KEY_ID:?}" "${APPLE_API_ISSUER:?}" "${APPLE_API_KEY_P8:?}" + +project=$(find "$out/xcode" -maxdepth 2 -name '*.xcodeproj' | head -n 1) +version=$(cd "$here" && node -p 'require("./dist/safari/manifest.json").version') +build=${BUILD_NUMBER:-$(date -u +%Y%m%d%H%M)} # App Store Connect wants every upload's build number to be higher + +key="$out/AuthKey_$APPLE_API_KEY_ID.p8" +trap 'rm -f "$key"' EXIT +(umask 077 && printf '%s\n' "$APPLE_API_KEY_P8" >"$key") +set -- -allowProvisioningUpdates -authenticationKeyPath "$key" -authenticationKeyID "$APPLE_API_KEY_ID" \ + -authenticationKeyIssuerID "$APPLE_API_ISSUER" + +xcodebuild archive -project "$project" -scheme "$app_name" -configuration Release -destination 'generic/platform=macOS' \ + -archivePath "$out/LensClipper.xcarchive" DEVELOPMENT_TEAM="$APPLE_TEAM_ID" CODE_SIGN_STYLE=Automatic \ + MARKETING_VERSION="$version" CURRENT_PROJECT_VERSION="$build" \ + INFOPLIST_KEY_LSApplicationCategoryType=public.app-category.productivity "$@" + +cat >"$out/ExportOptions.plist" < + + + + methodapp-store-connect + destinationupload + teamID$APPLE_TEAM_ID + signingStyleautomatic + + +PLIST +xcodebuild -exportArchive -archivePath "$out/LensClipper.xcarchive" -exportOptionsPlist "$out/ExportOptions.plist" \ + -exportPath "$out/export" "$@" +echo "uploaded $app_name $version ($build) to App Store Connect" diff --git a/extensions/browser/safari/build.sh b/extensions/browser/safari/build.sh new file mode 100755 index 000000000..9e774a8ff --- /dev/null +++ b/extensions/browser/safari/build.sh @@ -0,0 +1,36 @@ +#!/bin/sh +# Wraps dist/safari (the clipper built for Safari) into a Safari Web Extension: a small macOS app that carries the +# extension, generated with Apple's safari-web-extension-converter and built with xcodebuild. Needs macOS with Xcode. +# The build is unsigned (Safari loads it only with Develop > Allow Unsigned Extensions); app-store.sh signs and +# uploads the same project. +# +# safari/build.sh [out-dir] (default: dist/safari-app; writes lens-clipper-safari-app.zip there) +set -eu + +here=$(cd "$(dirname "$0")/.." && pwd) +out=${1:-$here/dist/safari-app} +app_name=${SAFARI_APP_NAME:-Lens Clipper} +bundle_id=${SAFARI_BUNDLE_ID:-dev.lens.clipper} + +cd "$here" +[ -d node_modules/esbuild ] || npm ci --include=dev +node scripts/build.mjs --target safari --check + +rm -rf "$out" && mkdir -p "$out" +out=$(cd "$out" && pwd) +xcrun safari-web-extension-converter "$here/dist/safari" \ + --project-location "$out/xcode" --app-name "$app_name" --bundle-identifier "$bundle_id" \ + --macos-only --swift --copy-resources --no-open --no-prompt --force + +project=$(find "$out/xcode" -maxdepth 2 -name '*.xcodeproj' | head -n 1) +# The converter gives the extension $bundle_id.Extension but names the app from the app name (dev.lens.Lens-Clipper), +# and Xcode refuses an extension whose id doesn't start with its app's; make the app $bundle_id. +bundle_id=$bundle_id perl -pi -e 's/(PRODUCT_BUNDLE_IDENTIFIER = )(?!"?[^;]*\.Extension"?;)[^;]*;/$1"$ENV{bundle_id}";/' \ + "$project/project.pbxproj" +version=$(node -p 'require("./dist/safari/manifest.json").version') +xcodebuild -project "$project" -scheme "$app_name" -configuration Release -destination 'generic/platform=macOS' \ + -derivedDataPath "$out/derived" MARKETING_VERSION="$version" CODE_SIGNING_ALLOWED=NO CODE_SIGN_IDENTITY= build + +app=$(find "$out/derived/Build/Products/Release" -maxdepth 1 -name '*.app' | head -n 1) +ditto -c -k --keepParent "$app" "$out/lens-clipper-safari-app.zip" +echo "built $out/lens-clipper-safari-app.zip ($app_name $version)" diff --git a/extensions/browser/targets/safari.json b/extensions/browser/targets/safari.json new file mode 100644 index 000000000..f4769ad24 --- /dev/null +++ b/extensions/browser/targets/safari.json @@ -0,0 +1,5 @@ +{ + "host_permissions": ["https://*/*", "http://*/*"], + "optional_host_permissions": null, + "browser_specific_settings": { "safari": { "strict_min_version": "16.4" } } +}