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
2 changes: 1 addition & 1 deletion .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
62 changes: 62 additions & 0 deletions .github/workflows/safari-clipper.yml
Original file line number Diff line number Diff line change
@@ -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"
25 changes: 24 additions & 1 deletion docs/web-clipper.md
Original file line number Diff line number Diff line change
Expand Up @@ -116,11 +116,34 @@ 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-<browser>.crx`, which checks `lens-clipper-<browser>-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.
- `CRX_PRIVATE_KEY` is a PEM RSA key (`openssl genrsa 2048`), and it fixes the extension's ID: keep it, because a new
key makes a different extension.
- The self-hosted builds are `dist/<browser>-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.
27 changes: 27 additions & 0 deletions extensions/browser/safari/README.md
Original file line number Diff line number Diff line change
@@ -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.
45 changes: 45 additions & 0 deletions extensions/browser/safari/app-store.sh
Original file line number Diff line number Diff line change
@@ -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" <<PLIST
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>method</key><string>app-store-connect</string>
<key>destination</key><string>upload</string>
<key>teamID</key><string>$APPLE_TEAM_ID</string>
<key>signingStyle</key><string>automatic</string>
</dict>
</plist>
PLIST
xcodebuild -exportArchive -archivePath "$out/LensClipper.xcarchive" -exportOptionsPlist "$out/ExportOptions.plist" \
-exportPath "$out/export" "$@"
echo "uploaded $app_name $version ($build) to App Store Connect"
36 changes: 36 additions & 0 deletions extensions/browser/safari/build.sh
Original file line number Diff line number Diff line change
@@ -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)"
5 changes: 5 additions & 0 deletions extensions/browser/targets/safari.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
{
"host_permissions": ["https://*/*", "http://*/*"],
"optional_host_permissions": null,
"browser_specific_settings": { "safari": { "strict_min_version": "16.4" } }
}
Loading