diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index eefe807..a4e24d2 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -34,17 +34,22 @@ jobs: - name: Lint run: npm run lint - - name: Package extension (sideloadable unpacked zip) + # The artefact is the unpacked extension itself: GitHub zips an uploaded + # folder once, so the download unzips straight to the folder Chrome loads + # (uploading a .zip would hand people a zip inside a zip). + - name: Stage extension (unpacked folder) run: | - mkdir -p dist + mkdir -p dist/podkey # vendor/ holds the sidestr engine the spend window imports (MV3 forbids remote code) - zip -r dist/podkey-extension.zip manifest.json src popup vendor $([ -d icons ] && echo icons) -x '*.test.js' + cp -r manifest.json src popup vendor $([ -d icons ] && echo icons) LICENSE PRIVACY.md dist/podkey/ + find dist/podkey -name '*.test.js' -delete - - name: Check the package holds every file the extension loads + - name: Check the folder holds every file the extension loads run: | python3 - <<'PY' - import json, re, zipfile - z = set(zipfile.ZipFile('dist/podkey-extension.zip').namelist()) + import json, os, re + root = 'dist/podkey' + have = {os.path.relpath(os.path.join(d, f), root).replace(os.sep, '/') for d, _, fs in os.walk(root) for f in fs} m = json.load(open('manifest.json')) need = [m['background']['service_worker'], m['action']['default_popup'], *m['icons'].values()] need += [f for c in m['content_scripts'] for f in c['js']] @@ -54,7 +59,7 @@ jobs: # the spend window's engine: every vendored file PINS.json records for pin in json.load(open('vendor/sidestr/PINS.json'))['pins']: need += [f"vendor/sidestr/{pin['name']}/{f}" for f in pin['files']] - missing = sorted(set(need) - z) + missing = sorted(set(need) - have) if missing: raise SystemExit('missing from the package: ' + ', '.join(missing)) print(f'package holds all {len(set(need))} files the extension loads') @@ -64,5 +69,5 @@ jobs: uses: actions/upload-artifact@v4 with: name: podkey-extension - path: dist/podkey-extension.zip + path: dist/podkey/ if-no-files-found: error diff --git a/README.md b/README.md index 8165c61..7e609bb 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ > Browser extension for **did:nostr** and **Solid** authentication -[![Version](https://img.shields.io/badge/version-0.0.8-blue.svg)](https://github.com/JavaScriptSolidServer/podkey/releases) +[![Version](https://img.shields.io/badge/version-0.0.9-blue.svg)](https://github.com/JavaScriptSolidServer/podkey/actions/workflows/ci.yml?query=branch%3Amain+is%3Asuccess) [![License](https://img.shields.io/badge/license-AGPL--3.0-green.svg)](LICENSE) [![NIP-07](https://img.shields.io/badge/NIP--07-compatible-purple.svg)](https://github.com/nostr-protocol/nips/blob/master/07.md) [![Test Page](https://img.shields.io/badge/test--page-live-brightgreen)](https://javascriptsolidserver.github.io/podkey/test-page/) @@ -52,15 +52,24 @@ stays inside the extension and never reaches the page. ## Install -### From a packaged release +### Download the build -1. Download the latest `podkey-extension` build from the - [releases page](https://github.com/JavaScriptSolidServer/podkey/releases) and - unzip it. -2. Open `chrome://extensions` (or `edge://extensions`). -3. Enable **Developer mode** (top-right). -4. Click **Load unpacked** and select the unzipped folder containing - `manifest.json`. +Every push to `main` is built, tested and packaged by CI. There are no tagged +releases yet: the latest build is the download. + +1. Open the [latest successful build of `main`](https://github.com/JavaScriptSolidServer/podkey/actions/workflows/ci.yml?query=branch%3Amain+is%3Asuccess) + and click the top run. +2. Under **Artifacts**, download **podkey-extension** (you need to be signed in + to GitHub; each build is kept for 90 days) and unzip it. The folder it + gives you holds `manifest.json`. +3. Open `chrome://extensions` (or `edge://extensions`), turn on + **Developer mode** (top right), click **Load unpacked** and pick that folder. + +To update, download a newer build, replace the contents of the **same folder** +and click the reload arrow on Podkey's card in `chrome://extensions`. Chrome +ties an unpacked extension's storage to its folder, so this keeps your key; +loading a build from a different folder starts a fresh Podkey with no key. +Export a backup from the popup before you move it. ### From source @@ -71,7 +80,7 @@ npm install npm run build # bundles the background worker and passkey-enabled popup ``` -Then load the `podkey` directory as an unpacked extension (steps 2โ€“4 above). +Then load the `podkey` directory as an unpacked extension (step 3 above). Pin the toolbar icon (๐Ÿ”‘), open it, and generate or import a 64-character hex key, choosing an **encryption passphrase**. The key is sealed under that @@ -266,8 +275,9 @@ podkey/ Tests cover the consent flow, NIP-44 against the official spec vectors, NIP-98 token shape, the content-script message whitelist, and signature self-verify. -CI runs build, test and lint on every pull request and push to `main`, and -uploads a sideloadable extension zip. +CI runs build, test and lint on every pull request and push to `main`, checks +that the package holds every file the extension loads, and uploads the unpacked +extension as the `podkey-extension` artifact (see [Install](#install)). ## Roadmap diff --git a/USAGE.md b/USAGE.md index 9d0dc3d..4cd0c19 100644 --- a/USAGE.md +++ b/USAGE.md @@ -4,6 +4,12 @@ ## Quick Start Guide +**Quickest:** download the ready-built extension instead of building it. Open the +[latest successful build of `main`](https://github.com/JavaScriptSolidServer/podkey/actions/workflows/ci.yml?query=branch%3Amain+is%3Asuccess), +click the top run, download **podkey-extension** under **Artifacts** (signed in to +GitHub), unzip it, and go to [Step 3](#step-3-load-extension-in-chrome), picking the +unzipped folder. The steps below build it from source. + ### Step 1: Install Dependencies ```bash diff --git a/site/index.html b/site/index.html index 55fdc83..73870fe 100644 --- a/site/index.html +++ b/site/index.html @@ -131,12 +131,14 @@

Security model

Install

-

From source, or a packaged release:

+

Download the build: open the latest successful build of main, click the top run, and download podkey-extension under Artifacts (signed in to GitHub; each build is kept for 90 days). Unzip it, open chrome://extensions, enable Developer mode, click Load unpacked, and select the folder containing manifest.json. Pin the ๐Ÿ”‘ icon, then generate or import a key and set an encryption passphrase.

+

To update, replace that same folder's contents with a newer build and reload Podkey in chrome://extensions; a different folder starts a fresh Podkey with no key.

+

Or from source:

git clone https://github.com/JavaScriptSolidServer/podkey.git
 cd podkey
 npm install
 npm run build      # bundles deps into the service worker
-

Then open chrome://extensions, enable Developer mode, click Load unpacked, and select the folder containing manifest.json. Pin the ๐Ÿ”‘ icon, then generate or import a key and set an encryption passphrase.

+

then load the podkey folder the same way.

Manifest V3 ยท bundles all code (no remotely-hosted scripts) ยท script-src 'self' CSP ยท AGPL-3.0.