From 2cf8fe8dc545492a61542104fa736a7aefddd7bf Mon Sep 17 00:00:00 2001 From: Claude Code Date: Thu, 24 Sep 2026 19:11:54 +0000 Subject: [PATCH] docs: install from the CI build; the artifact is the unpacked extension There are no tagged releases, so the README's 'releases page' step led nowhere. README, USAGE and the site now point at the latest successful CI build of main and its podkey-extension artifact, with the update path (same folder keeps the key; a different folder starts a fresh Podkey). CI uploads the staged extension folder instead of a zip: GitHub zips an artifact once, so the download unzips straight to the folder Chrome loads rather than to another zip. The completeness check runs on that folder. Co-Authored-By: jjohare --- .github/workflows/ci.yml | 21 +++++++++++++-------- README.md | 34 ++++++++++++++++++++++------------ USAGE.md | 6 ++++++ site/index.html | 6 ++++-- 4 files changed, 45 insertions(+), 22 deletions(-) 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.