@aauth/bootstrap - npm Package Compare versions

Comparing version 1.1.1 to 1.2.0

skills/platforms/cloudflare-pages-uninstall.md

+---
+name: cloudflare-pages-uninstall
+description: Remove the published AAuth JWKS and agent metadata from Cloudflare Pages
+when: User is uninstalling an AAuth agent provider whose JWKS is published to Cloudflare Pages — the bootstrap uninstall skill loads this skill to take down the remote files before deleting local keys
+agentUrlPattern: project.pages.dev or custom domain
+---
+
+# Skill: Remove AAuth keys from Cloudflare Pages
+
+The bootstrap `uninstall` skill loads this skill BEFORE deleting local keys, so the published JWKS goes down before the local signing key does. End state: both `<agent-url>/.well-known/jwks.json` and `aauth-agent.json` return 404.
+
+## Prerequisites
+
+- `wrangler` CLI is authenticated (`npx wrangler whoami` succeeds), OR a git repo connected to the Cloudflare Pages project
+- The agent URL (from `npx @aauth/bootstrap list`) — either `https://project-name.pages.dev` or a custom domain
+
+## Path A — git-connected project (preferred when available)
+
+### 1. Locate or clone the source repo
+
+Find the local clone of the repo that Cloudflare Pages deploys from. The hosting metadata in `~/.aauth/config.json` may name it; otherwise ask the user.
+
+### 2. Sync, verify, delete
+
+```bash
+cd <repo>
+git fetch origin
+git pull --ff-only
+ls -la .well-known/ 2>/dev/null
+git rm .well-known/jwks.json .well-known/aauth-agent.json
+git commit -m "Remove AAuth JWKS and agent metadata (uninstall)"
+git push origin <default-branch>
+```
+
+If both files are already absent, the remote is already clean — skip to step 4. If only one is present, surface to the user before proceeding.
+
+### 3. Wait for Cloudflare Pages to redeploy
+
+```bash
+until ! curl -sI <agent-url>/.well-known/jwks.json | head -1 | grep -q "200"; do sleep 5; done
+curl -I <agent-url>/.well-known/jwks.json | head -1
+curl -I <agent-url>/.well-known/aauth-agent.json | head -1
+```
+
+A deploy typically lands in under a minute. If it takes much longer, surface to the user — there may be a build hook failure.
+
+### 4. Report the world-state change, not the command
+
+> "JWKS at <agent-url>/.well-known/jwks.json now returns 404 — resources can no longer verify signatures from this agent."
+
+## Path B — direct wrangler upload (no source repo)
+
+If the project is uploaded with `wrangler pages deploy` from a local directory:
+
+### 1. Locate the staging directory
+
+Find or recreate the directory that was used for the last `wrangler pages deploy`. If unknown, the cleanest move is to deploy an empty directory:
+
+```bash
+mkdir -p /tmp/aauth-uninstall && cd /tmp/aauth-uninstall
+```
+
+### 2. Deploy the empty/cleaned content
+
+```bash
+wrangler pages deploy . --project-name <project-name>
+```
+
+If the original staging directory contained other content the user wants to keep, ask first — deploying an empty directory will take it down too. In that case have the user point you at the right directory; delete only `.well-known/jwks.json` and `.well-known/aauth-agent.json` from it, then redeploy.
+
+### 3. BLOCK until 404 (same as Path A step 3 + 4)
+
+## Notes
+
+- This skill is invoked by the bootstrap `uninstall` skill. Do not publish fresh AAuth files from it — that's the `cloudflare-pages` skill's job.
+- Custom domains: the 404 must come back on the agent URL the user actually used (custom or `.pages.dev`), not just one of them.
+- If you can't authenticate `wrangler` or find a connected repo, surface that as a blocker. Do not offer to have the user delete the files manually — without your verification step, "I'll do it" effectively means "leave them published."

skills/platforms/github-pages-uninstall.md

+---
+name: github-pages-uninstall
+description: Remove the published AAuth JWKS and agent metadata from GitHub Pages
+when: User is uninstalling an AAuth agent provider whose JWKS is published to GitHub Pages — the bootstrap uninstall skill loads this skill to take down the remote files before deleting local keys
+agentUrlPattern: username.github.io
+---
+
+# Skill: Remove AAuth keys from GitHub Pages
+
+The bootstrap `uninstall` skill loads this skill BEFORE deleting local keys, so the published JWKS goes down before the local signing key does. End state: both `https://username.github.io/.well-known/jwks.json` and `aauth-agent.json` return 404.
+
+## Prerequisites
+
+- `gh` CLI is authenticated as the user who owns `username.github.io`
+- The agent URL (from `npx @aauth/bootstrap list`) is `https://username.github.io`
+
+## Steps
+
+### 1. Locate or clone the GitHub Pages repo
+
+Look for an existing `username.github.io` clone first (the user may already have one — common locations: `~/github/`, `~/code/`, `~/src/`). If none:
+
+```bash
+gh repo clone username/username.github.io
+```
+
+### 2. Sync with the remote
+
+```bash
+cd username.github.io
+git fetch origin
+git pull --ff-only
+```
+
+Do NOT proceed if the pull fails — investigate first. A non-fast-forward means someone else changed the repo; bring it up to date before deleting anything.
+
+### 3. Check what's actually there
+
+```bash
+ls -la .well-known/ 2>/dev/null
+```
+
+- **Both files present** → continue to step 4.
+- **Both absent** → the remote is already clean; report to the user and skip to step 7.
+- **One present, one absent** → surface this to the user before proceeding. The published state is inconsistent with the local config.
+
+### 4. Delete the two AAuth files
+
+```bash
+git rm .well-known/jwks.json .well-known/aauth-agent.json
+```
+
+Delete ONLY these two files. Do not touch other content in `.well-known/` or anywhere else in the repo — many users host real content here.
+
+### 5. Commit with the canonical uninstall message
+
+```bash
+git commit -m "Remove AAuth JWKS and agent metadata (uninstall)"
+```
+
+This exact phrasing is what the `github-pages` publish skill scans for when it decides whether to treat a future install as "first-time" — i.e. to avoid silently resurrecting deleted keys from a stale local clone on another machine. Don't change the wording.
+
+### 6. Push and BLOCK until both URLs return 404
+
+```bash
+git push origin <default-branch>
+```
+
+GitHub Pages can take up to a minute to update its cache. Poll until both URLs return 404 before reporting success — a successful `git push` is NOT proof the world has changed:
+
+```bash
+until ! curl -sI https://username.github.io/.well-known/jwks.json | head -1 | grep -q "200"; do sleep 5; done
+curl -I https://username.github.io/.well-known/jwks.json | head -1
+curl -I https://username.github.io/.well-known/aauth-agent.json | head -1
+```
+
+### 7. Report the world-state change, not the command
+
+Tell the user concretely what changed in the world. Not the commit SHA — the URL that now 404s:
+
+> "JWKS at https://username.github.io/.well-known/jwks.json now returns 404 — resources can no longer verify signatures from this agent."
+
+Then return to the bootstrap `uninstall` skill to continue with local teardown.
+
+## Notes
+
+- This skill is invoked by the bootstrap `uninstall` skill. Do not publish fresh AAuth files from it — that's the `github-pages` skill's job.
+- The GitHub Pages repo itself, `.nojekyll`, and any non-AAuth content are left alone.
+- If the user can't authenticate `gh` here (no auth, wrong account), surface that as a blocker. Do not offer to have the user delete the files manually — without your verification step, "I'll do it" effectively means "leave them published."

skills/platforms/gitlab-pages-uninstall.md

+---
+name: gitlab-pages-uninstall
+description: Remove the published AAuth JWKS and agent metadata from GitLab Pages
+when: User is uninstalling an AAuth agent provider whose JWKS is published to GitLab Pages — the bootstrap uninstall skill loads this skill to take down the remote files before deleting local keys
+agentUrlPattern: username.gitlab.io
+---
+
+# Skill: Remove AAuth keys from GitLab Pages
+
+The bootstrap `uninstall` skill loads this skill BEFORE deleting local keys, so the published JWKS goes down before the local signing key does. End state: both `https://username.gitlab.io/.well-known/jwks.json` and `aauth-agent.json` return 404.
+
+## Prerequisites
+
+- `glab` CLI is authenticated as the user who owns `username.gitlab.io`
+- The agent URL (from `npx @aauth/bootstrap list`) is `https://username.gitlab.io`
+
+## Steps
+
+### 1. Locate or clone the GitLab Pages repo
+
+Look for an existing `username.gitlab.io` clone first. If none:
+
+```bash
+glab repo clone username/username.gitlab.io
+```
+
+### 2. Sync with the remote
+
+```bash
+cd username.gitlab.io
+git fetch origin
+git pull --ff-only
+```
+
+Do NOT proceed if the pull fails — bring the working tree up to date first.
+
+### 3. Check what's actually there
+
+```bash
+ls -la public/.well-known/ 2>/dev/null
+```
+
+GitLab Pages typically serves out of `public/`, so the files live at `public/.well-known/` (unlike GitHub Pages where they're at the repo root). If your project uses a different structure, ask the user.
+
+- **Both files present** → continue to step 4.
+- **Both absent** → the remote is already clean; report to the user and skip to step 7.
+- **One present, one absent** → surface to the user before proceeding.
+
+### 4. Delete the two AAuth files
+
+```bash
+git rm public/.well-known/jwks.json public/.well-known/aauth-agent.json
+```
+
+Delete ONLY these two files. The pipeline config (`.gitlab-ci.yml`) and any other content in `public/` are left alone.
+
+### 5. Commit with the canonical uninstall message
+
+```bash
+git commit -m "Remove AAuth JWKS and agent metadata (uninstall)"
+```
+
+Same exact phrasing as the other platforms — this is what the `gitlab-pages` publish skill scans for when deciding whether to treat a future install as "first-time."
+
+### 6. Push and BLOCK until the GitLab Pages pipeline redeploys
+
+```bash
+git push origin <default-branch>
+```
+
+GitLab Pages republishes via the pipeline configured in `.gitlab-ci.yml`. Watch for the pipeline:
+
+```bash
+glab ci view
+```
+
+Then BLOCK until both URLs return 404:
+
+```bash
+until ! curl -sI https://username.gitlab.io/.well-known/jwks.json | head -1 | grep -q "200"; do sleep 10; done
+curl -I https://username.gitlab.io/.well-known/jwks.json | head -1
+curl -I https://username.gitlab.io/.well-known/aauth-agent.json | head -1
+```
+
+Pipelines can take a few minutes. If a deploy fails (pipeline red), surface to the user — the published files won't have updated.
+
+### 7. Report the world-state change, not the command
+
+> "JWKS at https://username.gitlab.io/.well-known/jwks.json now returns 404 — resources can no longer verify signatures from this agent."
+
+Then return to the bootstrap `uninstall` skill to continue with local teardown.
+
+## Notes
+
+- This skill is invoked by the bootstrap `uninstall` skill. Do not publish fresh AAuth files from it — that's the `gitlab-pages` skill's job.
+- If the user can't authenticate `glab` here, surface that as a blocker. Do not offer to have the user delete the files manually — without your verification step, "I'll do it" effectively means "leave them published."

skills/platforms/netlify-uninstall.md

+---
+name: netlify-uninstall
+description: Remove the published AAuth JWKS and agent metadata from Netlify
+when: User is uninstalling an AAuth agent provider whose JWKS is published to Netlify — the bootstrap uninstall skill loads this skill to take down the remote files before deleting local keys
+agentUrlPattern: project.netlify.app or custom domain
+---
+
+# Skill: Remove AAuth keys from Netlify
+
+The bootstrap `uninstall` skill loads this skill BEFORE deleting local keys, so the published JWKS goes down before the local signing key does. End state: both `<agent-url>/.well-known/jwks.json` and `aauth-agent.json` return 404.
+
+## Prerequisites
+
+- `netlify` CLI is authenticated (`npx netlify status` succeeds), OR a git repo connected to the Netlify site
+- The agent URL (from `npx @aauth/bootstrap list`) — either `https://project.netlify.app` or a custom domain
+
+## Path A — git-connected site (preferred when available)
+
+### 1. Locate or clone the source repo
+
+Find the local clone of the repo that Netlify deploys from. If unknown, ask the user.
+
+### 2. Sync, verify, delete
+
+```bash
+cd <repo>
+git fetch origin
+git pull --ff-only
+ls -la .well-known/ 2>/dev/null
+git rm .well-known/jwks.json .well-known/aauth-agent.json
+git commit -m "Remove AAuth JWKS and agent metadata (uninstall)"
+git push origin <default-branch>
+```
+
+If both files are already absent, the remote is already clean — skip to step 4. If only one is present, surface to the user before proceeding.
+
+### 3. Wait for Netlify to redeploy
+
+Watch the build:
+
+```bash
+npx netlify watch
+```
+
+Then BLOCK until both URLs return 404:
+
+```bash
+until ! curl -sI <agent-url>/.well-known/jwks.json | head -1 | grep -q "200"; do sleep 5; done
+curl -I <agent-url>/.well-known/jwks.json | head -1
+curl -I <agent-url>/.well-known/aauth-agent.json | head -1
+```
+
+If a deploy fails, surface to the user — the published files won't have updated.
+
+### 4. Report the world-state change, not the command
+
+> "JWKS at <agent-url>/.well-known/jwks.json now returns 404 — resources can no longer verify signatures from this agent."
+
+## Path B — direct CLI deploy (no source repo)
+
+If the site is deployed with `netlify deploy --dir` from a local directory:
+
+### 1. Locate the staging directory
+
+Find the directory the user last deployed from. If unknown, ask — deploying an empty directory will take down any other content.
+
+### 2. Delete only the AAuth files
+
+```bash
+cd <staging-dir>
+rm .well-known/jwks.json .well-known/aauth-agent.json
+```
+
+### 3. Redeploy to production
+
+```bash
+npx netlify deploy --dir . --prod
+```
+
+### 4. BLOCK until 404 (same as Path A step 3 + 4)
+
+## Notes
+
+- This skill is invoked by the bootstrap `uninstall` skill. Do not publish fresh AAuth files from it — that's the `netlify` skill's job.
+- Custom domains: the 404 must come back on the agent URL the user actually used (custom or `.netlify.app`), not just one of them.
+- If you can't authenticate `netlify` or find a connected repo, surface that as a blocker. Do not offer to have the user delete the files manually — without your verification step, "I'll do it" effectively means "leave them published."

package.json

 {
   "name": "@aauth/bootstrap",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "CLI for bootstrapping AAuth agent keys and configuration",
@@ -5,0 +5,0 @@ "type": "module",

skills/uninstall.md

@@ -9,28 +9,13 @@ ---
 
-This returns the machine to a clean, pre-bootstrap state. There are three kinds
-of artifact, in two places:
+This returns the machine to a clean, pre-bootstrap state. There are two kinds of artifact, in two places:
 
-- **Remote** — the `.well-known/jwks.json` and `aauth-agent.json` files published
-  to a hosting platform (GitHub Pages, Cloudflare Pages, …). Only the hosting
-  platform's tooling can remove these.
-- **Local** — signing keys (in the OS keychain / Secure Enclave / YubiKey) and
-  the `~/.aauth` config dir. The `uninstall` command removes these.
+- **Remote** — the `.well-known/jwks.json` and `aauth-agent.json` files published to a hosting platform (GitHub Pages, Cloudflare Pages, …). Each platform has its own `<platform>-uninstall` skill (e.g. `github-pages-uninstall`) that knows how to take its files down.
+- **Local** — signing keys (in the OS keychain / Secure Enclave / YubiKey) and the `~/.aauth` config dir. The `uninstall` command removes these.
 
-## ⚠️ Before you start: this breaks running agents
+## How this skill flows
 
-Tearing down an identity will break **any running agent or MCP server that uses
-it**, on two independent layers:
+The whole walkthrough is **one named confirmation, then two automatic teardown steps**. Don't stack additional yes/no questions in front of it — the user already knows the consequence they're agreeing to.
 
-1. Once the local keys/config are gone, the agent can no longer **sign** requests
-   — the next call fails.
-2. Once the published JWKS is removed, resources can no longer **verify** the
-   agent's existing signatures — even a server that cached its key in memory
-   starts getting rejected.
+## 1. See what's there (and decide whether to proceed)
 
-**Confirm with the user** that no production service depends on this identity,
-and that any running agents/MCP servers using it have been stopped, before doing
-anything destructive. Confirm again before each destructive step.
-
-## 1. See what's there
-
 ```
@@ -40,25 +25,35 @@ npx @aauth/bootstrap list
 
-If there are no agent providers, the machine is already clean — stop. Otherwise
-the output is the map for everything below: each agent's `hosting`, `jwksUri`,
-and `keys`.
+If `agentProviders` is empty, the machine is already clean — say so and stop.
 
+Otherwise build the consequence statement from the `list` output. For each agent provider, name:
+
+- The remote URLs that will go down (`<jwksUri>` and the matching `aauth-agent.json` URL)
+- The local key(s) being deleted (kid + keystore)
+- That the local `~/.aauth/config.json` will be removed
+- That **anything currently using this identity will break** — running agents, MCP servers, scripts
+
+Ask the user ONE question: *"Proceed with all of the above?"* Yes / No. Do not ask whether the user wants to handle remote files themselves — they don't; that's not an option this skill offers. If you can't take the remote files down (no platform auth, no connected repo), surface that as a blocker and stop, do not silently leave files published.
+
 ## 2. Remove the remote `.well-known` files FIRST
 
-Do this **before** wiping config — the config holds the `hosting` pointers you
-need to find the files. For each agent provider in `list`:
+Do this **before** wiping local config — the config holds the `hosting` pointers you need to find the files.
 
-- Read its `hosting.platform` and `hosting.repo`.
-- Load the matching platform skill (`npx @aauth/bootstrap skill <platform>`,
-  e.g. `github-pages`) and use that platform's tooling (`gh`, `wrangler`, …) to
-  delete `.well-known/jwks.json` and `.well-known/aauth-agent.json` (or remove
-  the whole `.well-known/` directory) and push.
+For each agent provider in `list`:
 
-Confirm the files are gone (e.g. `curl -I <jwksUri>` returns 404) before
-continuing.
+- Read its `hosting.platform` (e.g. `github-pages`).
+- Load the matching uninstall skill: `npx @aauth/bootstrap skill <platform>-uninstall` (e.g. `github-pages-uninstall`). That skill is the source of truth for *how* to take the files down on that platform — clone/sync the repo, delete the two files, commit, push, BLOCK until 404.
+- Run it. Do not improvise from the publish skill; the publish skill describes how to *put files up*, which is the wrong shape for taking them down.
 
-## 3. Preview the local teardown (dry-run)
+The uninstall skill's exit condition is **both URLs return 404 from the public agent URL**. That is the world-state change. A successful `git push` is not proof; a 404 is. Report it like:
 
-`uninstall` is dry-run by default — it prints exactly what it WOULD delete and
-removes nothing:
+> "JWKS at `https://username.github.io/.well-known/jwks.json` now returns 404 — resources can no longer verify signatures from this agent."
 
+Not the commit SHA, not the deploy ID — what changed in the world the user actually sees.
+
+If a platform doesn't have a `<platform>-uninstall` skill yet, surface that as a blocker. Don't fall back to "the user can delete the files themselves" — without your 404 verification step, that's just leaving files published.
+
+## 3. Tear down local state
+
+`uninstall` is dry-run by default — it prints exactly what it WOULD delete and removes nothing:
+
 ```
@@ -68,9 +63,4 @@ npx @aauth/bootstrap uninstall
 
-Review `agents[].keysToDelete`, `orphanedKeychainUrls`, and `willRemoveConfigDir`
-with the user.
+Then run for real with `--force`:
 
-## 4. Perform the teardown
-
-After the user confirms, run it for real with `--force`:
-
 ```
@@ -80,13 +70,10 @@ npx @aauth/bootstrap uninstall --force
 
-This **backs up the config first** (agent URL, person server, hosting, key
-metadata — never private keys) to `~/.aauth/backups/`, then deletes every agent's
-keys across all keystores, sweeps orphaned keychain entries, and removes the
-active `config.json`. The output's `backupPath` points at the snapshot.
+This **backs up the config first** (agent URL, person server, hosting, key metadata — never private keys) to `~/.aauth/backups/`, then deletes every agent's keys across all keystores, sweeps orphaned keychain entries, and removes the active `config.json`. The output's `backupPath` points at the snapshot. Mention the backup path to the user — they may want to know where their old agent URL / person server settings are recorded, for a future re-install.
 
-- A YubiKey PIV key (slot 9e) can't be wiped programmatically yet — it appears
-  under `hardwareKeysRetained` with a manual command (`ykman piv keys delete 9e`).
-  Relay that to the user.
+- A YubiKey PIV key (slot 9e) can't be wiped programmatically yet — it appears under `hardwareKeysRetained` with a manual command (`ykman piv keys delete 9e`). Relay that to the user.
 
-## 5. Verify
+## 4. Report final state, not commands
 
+Verify and tell the user what's true in the world now:
+
 ```
@@ -96,7 +83,13 @@ npx @aauth/bootstrap list
 
-No agent providers means the machine is clean and ready to bootstrap fresh. The
-backup remains under `backups` in the `list` output — next time the user sets up,
-the `setup` skill can reuse the same agent URL, person server, and hosting (with
-fresh keys).
+Confirm `agentProviders: []` and report:
 
+- Local: "Signing key `<kid>` deleted from `<keystore>`. Local config removed; backup saved at `<path>`."
+- Remote (already reported in step 2): each `<url>` returns 404.
+
+That's the whole signal — the user shouldn't have to read the commit log or grep the keychain to know it worked.
+
+## No dangling background work
+
+If you started any background task or monitor during this skill (e.g. tailing a deploy log, polling for 404), stop it before ending the turn. The user should never inherit a running task from a previous step.
+
 ## Cross-machine note: this uninstall is only visible on the remote, not on other machines
@@ -106,18 +99,7 @@
 
-- The published `.well-known/` files from the hosting repo (step 2).
-- This machine's local keys, config, and adds a backup entry under
-  `~/.aauth/backups/`.
+- The published `.well-known/` files from the hosting platform (step 2).
+- This machine's local keys, config, and adds a backup entry under `~/.aauth/backups/`.
 
-It does **not** modify any other machine that previously cloned the hosting
-repo. Another laptop with the GitHub Pages repo checked out will still have a
-stale local copy of `.well-known/jwks.json` containing the keys you just
-removed. If `setup` runs there and follows the (older) "read existing JWKS and
-append" instruction, it can silently resurrect the deleted keys when it pushes.
+It does **not** modify any other machine that previously cloned the hosting repo. Another laptop with the GitHub Pages repo checked out will still have a stale local copy of `.well-known/jwks.json` containing the keys you just removed. If `setup` runs there and follows the (older) "read existing JWKS and append" instruction, it can silently resurrect the deleted keys when it pushes.
 
-The `github-pages` platform skill now requires `git pull` + a check for recent
-uninstall commits before publishing, which catches this. But if you wrote
-custom tooling around AAuth or are running an out-of-date skill version,
-remember: an empty `backups: []` on another machine does NOT mean the user
-never installed; it only means *that* machine never uninstalled. Confirm with
-the user before treating any setup as "first-time" when a hosting repo with
-git history exists.
+The platform publish skills (e.g. `github-pages`) require `git pull` + a check for recent uninstall commits before publishing, which catches this. But if you wrote custom tooling around AAuth or are running an out-of-date skill version, remember: an empty `backups: []` on another machine does NOT mean the user never installed; it only means *that* machine never uninstalled. Confirm with the user before treating any setup as "first-time" when a hosting repo with git history exists.

New alerts

URL strings

Supply chain risk

Package contains fragments of external URLs or IP addresses, which the package may be accessing at runtime.

Fixed alerts

URL strings

Supply chain risk

Package contains fragments of external URLs or IP addresses, which the package may be accessing at runtime.

Improved metrics

Total package byte prevSize

178103

9.47%

Number of package files

64

6.67%

No dependency changes