@aauth/bootstrap
Advanced tools
@aauth/bootstrap - npm Package Compare versions
+1
-1
| { | ||
| "name": "@aauth/bootstrap", | ||
| "version": "1.1.0", | ||
| "version": "1.1.1", | ||
| "description": "CLI for bootstrapping AAuth agent keys and configuration", | ||
@@ -5,0 +5,0 @@ "type": "module", |
@@ -76,11 +76,18 @@ --- | ||
| Field names follow the AAuth spec (`(#agent-provider-metadata)` in | ||
| `draft-hardt-oauth-aauth-protocol.md`): `issuer`, `jwks_uri`, `client_name`, | ||
| `logo_uri`, optional `logo_dark_uri`, `description`, `tos_uri`, `policy_uri`. | ||
| ```json | ||
| { | ||
| "id": "https://project-name.pages.dev", | ||
| "name": "Agent Name", | ||
| "jwks_uri": "https://project-name.pages.dev/.well-known/jwks.json" | ||
| "issuer": "https://project-name.pages.dev", | ||
| "jwks_uri": "https://project-name.pages.dev/.well-known/jwks.json", | ||
| "client_name": "Agent Name" | ||
| } | ||
| ``` | ||
| Replace the URLs with the custom domain if using one. Optionally add `logo_uri`, `tos_uri`, `policy_uri`. | ||
| Replace the URLs with the custom domain if using one. Optionally add `logo_uri`, | ||
| `logo_dark_uri`, `description`, `tos_uri`, `policy_uri`. **Do NOT use `id` or | ||
| `name`** — older skill versions used those, but the spec is `issuer` and | ||
| `client_name`. | ||
@@ -87,0 +94,0 @@ ### 6. Deploy |
@@ -47,2 +47,33 @@ --- | ||
| ### 3a. Sync the local clone with the remote — REQUIRED before editing | ||
| **Skipping this step has resurrected uninstalled keys in the past.** If the | ||
| remote was modified from another machine (in particular, if `uninstall` ran on a | ||
| different device and deleted `.well-known/jwks.json` / `aauth-agent.json`), the | ||
| local clone is stale, and the "read existing JWKS and append" step below will | ||
| silently re-publish keys the user intentionally removed. | ||
| In the clone: | ||
| ``` | ||
| git fetch origin | ||
| git log --oneline -n 10 origin/HEAD -- .well-known/ | ||
| ``` | ||
| Then: | ||
| - `git pull --ff-only` (or `--rebase` if needed) so local matches the remote | ||
| default branch. Do NOT proceed if the pull fails — investigate first. | ||
| - Scan the recent commit log printed above for `uninstall`, `Remove AAuth`, or | ||
| any deletion of `.well-known/jwks.json` / `.well-known/aauth-agent.json`. If | ||
| you find any: | ||
| - **Treat the current install as a fresh start** — do not "merge" the new key | ||
| into a locally-cached JWKS. The intended remote state is "no keys." | ||
| - If `.well-known/` no longer exists on the remote, the local copy after `git | ||
| pull` will also not have it. Recreate from scratch with just the new key, | ||
| not by reading whatever stale tree you remember. | ||
| - Surface what you found to the user before editing anything ("the remote shows | ||
| an uninstall commit at <SHA> — proceeding will set up a fresh identity with | ||
| only the new key, not restore the old ones — confirm?"). | ||
| ### 4. Ensure `.nojekyll` exists | ||
@@ -65,3 +96,7 @@ | ||
| This file publishes the agent's metadata. Use the GitHub user/org avatar as the agent logo: | ||
| This file publishes the agent's metadata. Field names follow the AAuth spec | ||
| (see `(#agent-provider-metadata)` in `draft-hardt-oauth-aauth-protocol.md`): | ||
| `issuer`, `jwks_uri`, `client_name`, `logo_uri`, optional `logo_dark_uri`, | ||
| `description`, `tos_uri`, `policy_uri`. Use the GitHub user/org avatar as the | ||
| agent logo: | ||
| - Get the GitHub avatar URL by running: `gh api /users/username --jq '.avatar_url'` | ||
@@ -72,12 +107,17 @@ - If `.well-known/aauth-agent.json` exists, read it and update the fields below. | ||
| { | ||
| "id": "https://username.github.io", | ||
| "name": "Username", | ||
| "logo_uri": "https://avatars.githubusercontent.com/u/USER_ID?v=4", | ||
| "jwks_uri": "https://username.github.io/.well-known/jwks.json" | ||
| "issuer": "https://username.github.io", | ||
| "jwks_uri": "https://username.github.io/.well-known/jwks.json", | ||
| "client_name": "Username", | ||
| "logo_uri": "https://avatars.githubusercontent.com/u/USER_ID?v=4" | ||
| } | ||
| ``` | ||
| - Set `logo_uri` to the avatar URL from `gh api`. | ||
| - Set `name` to a human-readable agent name — ask the user, or default to the GitHub username/org name. | ||
| - Optionally add `logo_uri_dark`, `tos_uri`, `policy_uri`. | ||
| - Set `client_name` to a human-readable agent name — ask the user, or default to | ||
| the GitHub username/org name. | ||
| - Optionally add `logo_dark_uri`, `description`, `tos_uri`, `policy_uri`. | ||
| **Do NOT use `id` or `name`** — earlier versions of this skill used those | ||
| field names, but the spec is `issuer` and `client_name`. If you find an existing | ||
| file with `id`/`name`, migrate it to `issuer`/`client_name` while you're here. | ||
| ### 7. Commit and push | ||
@@ -132,6 +172,6 @@ | ||
| { | ||
| "id": "https://dickhardt.github.io", | ||
| "name": "Dick Hardt", | ||
| "logo_uri": "https://avatars.githubusercontent.com/u/322034?v=4", | ||
| "jwks_uri": "https://dickhardt.github.io/.well-known/jwks.json" | ||
| "issuer": "https://dickhardt.github.io", | ||
| "jwks_uri": "https://dickhardt.github.io/.well-known/jwks.json", | ||
| "client_name": "Dick Hardt", | ||
| "logo_uri": "https://avatars.githubusercontent.com/u/322034?v=4" | ||
| } | ||
@@ -138,0 +178,0 @@ ``` |
@@ -77,11 +77,15 @@ --- | ||
| Field names follow the AAuth spec (`(#agent-provider-metadata)` in | ||
| `draft-hardt-oauth-aauth-protocol.md`): `issuer`, `jwks_uri`, `client_name`, | ||
| `logo_uri`, optional `logo_dark_uri`, `description`, `tos_uri`, `policy_uri`. | ||
| ```json | ||
| { | ||
| "id": "https://username.gitlab.io", | ||
| "name": "Username", | ||
| "jwks_uri": "https://username.gitlab.io/.well-known/jwks.json" | ||
| "issuer": "https://username.gitlab.io", | ||
| "jwks_uri": "https://username.gitlab.io/.well-known/jwks.json", | ||
| "client_name": "Username" | ||
| } | ||
| ``` | ||
| Optionally add `logo_uri` (GitLab avatar: `https://gitlab.com/uploads/-/system/user/avatar/USER_ID/avatar.png`), `tos_uri`, `policy_uri`. | ||
| Optionally add `logo_uri` (GitLab avatar: `https://gitlab.com/uploads/-/system/user/avatar/USER_ID/avatar.png`), `logo_dark_uri`, `description`, `tos_uri`, `policy_uri`. **Do NOT use `id` or `name`** — older skill versions used those, but the spec is `issuer` and `client_name`. | ||
@@ -88,0 +92,0 @@ ### 6. Create `.gitlab-ci.yml` |
@@ -75,11 +75,18 @@ --- | ||
| Field names follow the AAuth spec (`(#agent-provider-metadata)` in | ||
| `draft-hardt-oauth-aauth-protocol.md`): `issuer`, `jwks_uri`, `client_name`, | ||
| `logo_uri`, optional `logo_dark_uri`, `description`, `tos_uri`, `policy_uri`. | ||
| ```json | ||
| { | ||
| "id": "https://site-name.netlify.app", | ||
| "name": "Agent Name", | ||
| "jwks_uri": "https://site-name.netlify.app/.well-known/jwks.json" | ||
| "issuer": "https://site-name.netlify.app", | ||
| "jwks_uri": "https://site-name.netlify.app/.well-known/jwks.json", | ||
| "client_name": "Agent Name" | ||
| } | ||
| ``` | ||
| Replace the URLs with the custom domain if using one. Optionally add `logo_uri`, `tos_uri`, `policy_uri`. | ||
| Replace the URLs with the custom domain if using one. Optionally add `logo_uri`, | ||
| `logo_dark_uri`, `description`, `tos_uri`, `policy_uri`. **Do NOT use `id` or | ||
| `name`** — older skill versions used those, but the spec is `issuer` and | ||
| `client_name`. | ||
@@ -86,0 +93,0 @@ ### 6. Add a `_redirects` file (important) |
+21
-6
@@ -36,5 +36,13 @@ --- | ||
| Confirm with the user before reusing — they may want a different URL. If | ||
| `backups` is empty, this is a first-time setup. | ||
| Confirm with the user before reusing — they may want a different URL. | ||
| **`backups` is local-only — an empty array does NOT mean "no prior install | ||
| anywhere."** It only reflects uninstalls that ran on THIS machine. A previous | ||
| install + uninstall on a different device, or a manually-cleared | ||
| `~/.aauth/backups/` directory, will leave `backups: []` here even though the | ||
| hosting repo's git history may show prior AAuth commits. Before treating this as | ||
| first-time setup, if the user names a hosting repo, also check the remote — see | ||
| the platform skill (e.g. `github-pages`), which now pulls first and warns on | ||
| recent uninstall commits. | ||
| ## What `create` does | ||
@@ -56,9 +64,16 @@ | ||
| Prefer hardware over software (the private key never leaves the device): | ||
| Prefer hardware over software (the private key never leaves the device). When | ||
| multiple hardware keystores are available, prefer the one that's always present | ||
| and doesn't require plugging anything in: | ||
| 1. **`yubikey-piv`** — YubiKey PIV slot 9e, no PIN, ES256. | ||
| 2. **`secure-enclave`** — macOS Secure Enclave (Apple Silicon), ES256. | ||
| 1. **`secure-enclave`** — macOS Secure Enclave (Apple Silicon), ES256. Always | ||
| present on Apple Silicon, non-exportable, no hardware to insert. | ||
| 2. **`yubikey-piv`** — YubiKey PIV slot 9e, no PIN, ES256. Portable across | ||
| machines, but requires the YubiKey to be plugged in to sign. Prefer when the | ||
| user explicitly wants a portable hardware key. | ||
| 3. **`software`** — OS keychain, EdDSA (default) or ES256. Use only if no hardware is present. | ||
| Pick the keystore from the `keystores` array that `list` reported. | ||
| Pick the keystore from the `keystores` array that `list` reported. If both | ||
| `secure-enclave` and `yubikey-piv` are available, default to `secure-enclave` | ||
| and offer YubiKey as an alternative for users who want a portable key. | ||
@@ -65,0 +80,0 @@ ## Determining the agent provider URL |
+22
-0
@@ -96,1 +96,23 @@ --- | ||
| fresh keys). | ||
| ## Cross-machine note: this uninstall is only visible on the remote, not on other machines | ||
| Uninstalling here removes: | ||
| - 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/`. | ||
| 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. |
New alerts
URL strings
Supply chain riskPackage contains fragments of external URLs or IP addresses, which the package may be accessing at runtime.
Fixed alerts
URL strings
Supply chain riskPackage contains fragments of external URLs or IP addresses, which the package may be accessing at runtime.
Improved metrics
- Total package byte prevSize
162694
3.35%No dependency changes