@moejay/pi-secure 0.1.0 → 0.1.4

package/README.md

@@ -4,25 +4,33 @@
 
 Private secret entry, stdout capture, local reveal/copy, and redacted shell execution for [Pi](https://pi.dev). Transcript hygiene—not a sandbox or secret manager.
 
-[Website](https://moejay.github.io/pi-secure/) · [Security](SECURITY.md) · [Release process](RELEASING.md)
+[Website](https://moejay.github.io/pi-secure/) · [Security](SECURITY.md) · [Deployment & releases](RELEASING.md)
+
+> **Not protection against a malicious or compromised model.** A model acting on a prompt injection can still use its tools to obtain or leak secrets. pi-secure reduces accidental transcript exposure; it does not prevent prompt injection or enforce secret isolation.
+
+## Watch it work
+
+[![Check a private build with pi-secure](https://moejay.github.io/pi-secure/media/preview.png?v=0.1.3)](https://moejay.github.io/pi-secure/#watch-demo)
+
+[Watch the walkthrough →](https://moejay.github.io/pi-secure/#watch-demo)
 
 ## Install
 
 Requires Node.js 22.19+ and Pi 1.4+; interactive terminal mode is required for private entry and local reveal/copy. Shell execution supports macOS and Linux, not native Windows.
 
-Install from GitHub now:
+Install from npm:
 
 ```sh
-pi install git:github.com/moejay/pi-secure
+pi install npm:@moejay/pi-secure
 ```
 
-After the first npm release (not published yet):
+Or install from GitHub:
 
 ```sh
-pi install npm:@moejay/pi-secure
+pi install git:github.com/moejay/pi-secure
 ```
 
-Restart or `/reload` after installing. Reload clears in-memory secrets. For local development, use `pi -e ./index.ts` or `pi install /absolute/path/to/pi-secure`.
+**Fully restart Pi after installing or updating.** On affected Pi versions, `/reload` refreshes the TypeScript entry point but can retain cached `.mjs` helpers. A full restart loads a consistent version and clears in-memory secrets. If capture reports that no secret was stored, restart before retrying; do not use real credentials to diagnose it. For local development, use `pi -e ./index.ts` or `pi install /absolute/path/to/pi-secure`.
 
 ## Quick start
 
@@ -83,6 +91,8 @@ Output is buffered, then exact known secret values are redacted from stdout/stde
 
 ## Security boundary
 
+**A malicious model—or one following a prompt injection—can still obtain or exfiltrate secrets.** For example, it could use a secret-bearing command to write a value to a file and read it with another tool, send it to an external destination, or transform it to evade exact-value redaction. There is no per-command approval or policy enforcement in `secure_exec`; confirmations on local reveal/copy do not protect other tool paths. Use only credentials and tasks you trust the agent to handle, preferably with external sandboxing, network restrictions, and least-privilege, short-lived tokens.
+
 **Transcript hygiene, not a sandbox or secret manager.** Commands can use secrets arbitrarily for authorized tasks. There are no destination or file-access restrictions. Keep values out of chat: do not read secret-bearing files through ordinary tools, include values in messages, or encode them to bypass redaction. These are agent instructions, not enforced isolation. Other tools' output is not redacted.
 
 Names, reasons, commands, availability, and redacted execution output are logged normally. Host extensions, process inspection, terminal input/debug recording, crash dumps, and the operating system are outside this protection. Only approve credentials for trusted tasks and destinations. Prefer short-lived, least-privilege tokens. Clear does not revoke credentials or erase copies held by running subprocesses.
@@ -95,7 +105,18 @@ npm run check
 npm pack --dry-run --ignore-scripts
 ```
 
-The package ships source directly, with no build step or runtime dependencies beyond Pi. CI checks Node 22 and 24. See [RELEASING.md](RELEASING.md) for the disabled-by-default OIDC publishing workflow and human setup checkpoint.
+The package ships source directly, with no build step or runtime dependencies beyond Pi. CI checks the minimum Node 22.19.0 plus current Node 22 and 24. See [RELEASING.md](RELEASING.md) for the manually approved OIDC publishing workflow and release checklist.
+
+### Dependency maintenance
+
+Dependabot checks weekly. GitHub Actions updates are grouped into one PR; routine compiler/type updates are grouped separately, while compiler major upgrades get explicit review. Keep `@types/node` on Node 22 to match the minimum supported runtime—upgrading CI tooling does not raise the package's runtime requirement. Actions remain SHA-pinned, and dependency PRs still require passing CI and maintainer review.
+
+## Deployment and releases
+
+- **Website:** merge changes under `docs/` through a PR; GitHub Pages deploys automatically from `main` with no build step.
+- **npm:** bump the version in a PR, wait for CI, merge, then tag and manually dispatch `publish.yml` from `main`. The `npm` environment requires human approval; publishing uses OIDC and provenance, not a stored npm token.
+
+See [RELEASING.md](RELEASING.md) for preview, deployment, release, verification, and recovery commands. Documentation-only website updates do not require an npm release; the npm README changes only when a new package version is published.
 
 ## License
 

package/RELEASING.md

@@ -1,32 +1,156 @@
-# Releasing
+# Deployment and releases
 
-## Current state
+## What deploys where
 
-The npm workflow is deliberately disabled by default. No npm credential belongs in this repo, GitHub secrets, chat, or an agent tool argument.
+| Target | Source | Trigger | Approval |
+| --- | --- | --- | --- |
+| [Website](https://moejay.github.io/pi-secure/) | Static files in `docs/` | Merge changes to `docs/**` or `pages.yml` into `main`; or manual Pages dispatch | Protected `github-pages` environment |
+| [npm package](https://www.npmjs.com/package/@moejay/pi-secure) | Files allowed by `package.json` | Manual `publish.yml` dispatch from `main`, with an existing `vX.Y.Z` tag | Required human reviewer on `npm` environment |
+| [GitHub release](https://github.com/moejay/pi-secure/releases) | Existing release tag and notes | Maintainer creates it after verifying npm | Maintainer |
 
-- Package: `@moejay/pi-secure`
-- Repository: `moejay/pi-secure`
-- Workflow: `publish.yml`
-- GitHub environment: `npm`
+The website has no build step. npm ships source directly. A website-only update needs no version bump or npm release. Changes to the README shipped on npm require a new npm version; existing versions cannot be overwritten.
 
-## First release (human checkpoint)
+Version 0.1.0 was bootstrapped manually with 2FA; 0.1.1 verified the GitHub OIDC release path and provenance. Subsequent releases should use CI, not local `npm publish`.
 
-1. Confirm ownership of the npm `moejay` scope and enable 2FA.
-2. Run `npm ci --ignore-scripts && npm run check` and inspect `npm pack --dry-run --ignore-scripts`. Smoke-test the dialogs and native clipboard on your platform.
-3. Bootstrap the package if npm requires it before trusted publisher configuration: use interactive `npm login` and `npm publish --access public` locally with 2FA. Do not give the agent a token or OTP. This first manual upload may not have provenance.
-4. In npm package settings, configure GitHub Actions trusted publishing: owner `moejay`, repo `pi-secure`, workflow filename `publish.yml`, environment `npm`. Allow direct `npm publish` (staged-only permissions will not work with this workflow).
-5. In GitHub, protect the `npm` environment with a required human reviewer; restrict its deployment branch to `main`. Protect main and release tags with rulesets. Require CI and review for workflow/code changes.
-6. Set package publishing access to **Require two-factor authentication and disallow tokens**. Revoke obsolete publishing tokens. Do not add an npm token to Actions.
-7. Set repository Actions variable `NPM_PUBLISH_ENABLED=true` only once the above is complete. Newly configured npm trust must be used within its documented expiry window (currently 2 days). If you bootstrapped 0.1.0, use a new version for the first OIDC release—npm versions cannot be overwritten.
+## Prerequisites and protections
 
-## Subsequent releases
+- Node.js 22.19+ and npm for local checks; authenticated `gh` and Git write access for PRs/tags.
+- `main` requires a PR and passing `check (22)` / `check (24)` checks, including for admins. Force pushes and deletion are disabled. The current solo-maintainer setup requires zero independent PR approvals; the release environment still requires explicit human approval.
+- `v*` release tags cannot be updated or deleted. Use a new version/tag to correct a release.
+- npm trusted publisher: GitHub owner `moejay`, repository `pi-secure`, workflow filename `publish.yml`, environment `npm`, with direct `npm publish` allowed.
+- The `npm` environment permits only the `main` deployment branch, requires reviewer `moejay`, and disables admin bypass. Self-review is permitted for the solo maintainer; an agent must leave this approval to the human.
+- Repository Actions variable `NPM_PUBLISH_ENABLED` must be `true`. Disable it to stop future publish jobs. This does not stop an already-running job or revoke credentials.
+- npm publishing access should require 2FA and disallow traditional tokens. No npm credential belongs in GitHub secrets, the repo, chat, or agent tool arguments.
 
-1. Update version and lockfile in a reviewed commit; merge into main after CI.
-2. Create and push the matching `vX.Y.Z` tag at the reviewed main commit.
-3. Run **Publish npm** from main, supplying the existing tag.
-4. Approve the `npm` environment deployment after reviewing the tag.
-5. Verify npm version, tarball files, and provenance before creating a GitHub release.
+CI uses GitHub-hosted Node 24 for publishing, npm >=11.5.1, SHA-pinned Actions, no dependency caching, and disabled install/publish lifecycle scripts. Tests and typechecks run explicitly before publishing. OIDC permission is scoped to the protected publish job. PRs, tag pushes, and GitHub releases do not trigger npm publishing.
 
-The workflow uses GitHub-hosted Node 24 (npm >=11.5.1 required), SHA-pinned Actions, read-only repository permissions, no dependency caching, no install lifecycle scripts, exact tag/version checks, and OIDC only. Publish permission is scoped to the protected job. It is manual, not triggered by PRs, tags, or GitHub releases.
+## Website: preview and deploy
 
-Reference: https://docs.npmjs.com/trusted-publishers/
+Start from up-to-date main and use a PR:
+
+```sh
+git switch main
+git pull --ff-only
+git switch -c docs/update-site
+# Edit docs/, then preview:
+python3 -m http.server 8080 --directory docs
+```
+
+Open http://localhost:8080. Check narrow/mobile and desktop layouts, keyboard navigation, links, and security wording. Stop the server with Ctrl+C, then:
+
+```sh
+npm ci --ignore-scripts
+npm run check
+git diff --check
+git add docs/
+git commit -m "docs: update website"
+git push -u origin HEAD
+gh pr create --repo moejay/pi-secure --base main --fill
+```
+
+Wait for CI, review and merge the PR. The **Pages** workflow uploads `docs/` and deploys it through the `github-pages` environment. Check the [Pages runs](https://github.com/moejay/pi-secure/actions/workflows/pages.yml) and the live site.
+
+To redeploy current main without another commit:
+
+```sh
+gh workflow run pages.yml --repo moejay/pi-secure --ref main
+```
+
+Keep Pages configured to use **GitHub Actions**, not a branch/Jekyll build. README-only changes do not trigger Pages.
+
+## Gallery previews and demo media
+
+`package.json` uses `pi.image` and `pi.video` to give the Pi gallery public HTTPS preview URLs. The PNG, MP4, captions, and transcript are hosted under `docs/media/` on Pages, not bundled in the npm tarball. See [scripts/demo/README.md](https://github.com/moejay/pi-secure/blob/main/scripts/demo/README.md) for the isolated, scripted capture process.
+
+When updating media:
+
+1. Use only an obviously fake credential in an isolated session with no model calls or inherited authentication. Never record your normal terminal session or clipboard history.
+2. Keep simulated clipboard behavior explicitly labeled; do not silently replace the user's clipboard while recording. Include the malicious-model/prompt-injection limitation.
+3. Regenerate the thumbnail, captioned MP4, WebVTT captions, and text transcript together. Check readability, captions, and playback on mobile and desktop.
+4. Merge the media changes and verify the public Pages URLs before publishing npm metadata that points to them. Preserve old URLs when renaming assets so existing package versions do not get broken previews.
+5. A new npm version is needed for updated `pi.image` / `pi.video` metadata or the packaged README. Gallery indexing can lag behind npm; verify the published manifest instead of repeatedly republishing.
+
+## npm: prepare a release PR
+
+Use a release branch. The example uses a patch increment; choose minor/major deliberately for feature/breaking changes.
+
+```sh
+git switch main
+git pull --ff-only
+git switch -c release/next
+npm ci --ignore-scripts
+npm version patch --no-git-tag-version --ignore-scripts
+# Update documentation/release notes as needed.
+npm run check
+npm pack --dry-run --ignore-scripts
+git diff --check
+git add package.json package-lock.json
+# Explicitly stage any documentation changes too.
+git commit -m "chore: prepare release"
+git push -u origin HEAD
+gh pr create --repo moejay/pi-secure --base main --fill
+```
+
+Inspect the tarball allowlist: only the intended source, package metadata, license, README, security policy, and release guide should ship. Do not include credentials or local configuration. Fully restart Pi after helper changes or upgrades; on affected Pi versions `/reload` can retain cached native `.mjs` imports. Smoke-test `capture_secret` → `show_secret` with a disposable value (capture must return only name/availability), then masked entry, cancellation, reveal/hide, and native clipboard copy both masked and visible on a supported platform; automated clipboard tests mock native utilities.
+
+Review the PR and wait for both Node 22/24 CI checks before merging. Do not bypass branch protections.
+
+## npm: tag, dispatch, and approve
+
+After the release PR is merged, use the merged main commit, not the release branch's pre-merge commit:
+
+```sh
+git switch main
+git pull --ff-only
+VERSION=$(node -p "JSON.parse(require('fs').readFileSync('package.json', 'utf8')).version")
+git tag -a "v$VERSION" -m "pi-secure $VERSION"
+git push origin "v$VERSION"
+gh workflow run publish.yml --repo moejay/pi-secure --ref main -f "tag=v$VERSION"
+gh run list --repo moejay/pi-secure --workflow publish.yml --limit 5
+```
+
+The workflow requires a stable `vX.Y.Z` tag, checks that its commit is an ancestor of main, and checks the package name/version. It checks out the tagged source, runs checks, and publishes through OIDC with provenance.
+
+Open the new run in GitHub. The human maintainer must select **Review deployments → npm → Approve and deploy**, after checking the tag and commit. Do not approve a release merely because a model requests it. No OTP or npm token should be supplied to CI.
+
+## Verify before announcing
+
+Once the run succeeds, npm may take several minutes to expose the package. A temporary 404 is not a reason to republish or reuse the version.
+
+```sh
+# VERSION is the version just released, set in the previous step.
+npm view "@moejay/pi-secure@$VERSION" version dist --prefer-online --json
+```
+
+Check `dist.attestations` for SLSA provenance. Verify the registry signature and provenance in an isolated temporary install, without running lifecycle scripts or installing Pi peers:
+
+```sh
+VERIFY_DIR=$(mktemp -d)
+printf '{"name":"pi-secure-verification","version":"1.0.0","private":true}\n' > "$VERIFY_DIR/package.json"
+npm install --prefix "$VERIFY_DIR" --cache "$VERIFY_DIR/cache" \
+  --prefer-online --ignore-scripts --legacy-peer-deps --no-audit --no-fund \
+  "@moejay/pi-secure@$VERSION"
+npm audit signatures --prefix "$VERIFY_DIR" --cache "$VERIFY_DIR/cache"
+# Inspect the installed files and package.json in $VERIFY_DIR/node_modules/@moejay/pi-secure.
+```
+
+Expect a verified registry signature and verified attestation. Check that provenance identifies `moejay/pi-secure`, the intended source commit, and the publishing workflow. Inspect the tarball contents and compare its integrity hash with registry metadata. Then create release notes:
+
+```sh
+gh release create "v$VERSION" --repo moejay/pi-secure --verify-tag \
+  --title "v$VERSION" --notes-file /path/to/reviewed-release-notes.md
+```
+
+Do not claim security isolation: pi-secure does not stop a malicious or prompt-injected model from obtaining or leaking secrets. Keep this boundary explicit in release notes when describing security behavior.
+
+## Failure and recovery
+
+- **Skipped job:** confirm dispatch was from `main` and `NPM_PUBLISH_ENABLED=true`.
+- **Waiting:** the human reviewer must approve the `npm` environment deployment.
+- **OIDC authentication failure:** verify exact, case-sensitive trusted-publisher fields above, direct publish permission, environment name, and repository URL in `package.json`. Do not work around it by adding a token. Newly configured npm trust can expire before its first successful publish; see current npm documentation.
+- **Publish step failed:** check npm first. If the version is absent and npm did not accept it, fix the underlying issue and rerun the reviewed workflow with a fresh human approval. If it already exists, verify it instead of republishing.
+- **Bad published release:** never move/delete a release tag or overwrite an npm version. Fix forward with a new patch release. For an actual secret exposure, revoke affected credentials first; deleting a release does not erase copies.
+- **Bad website deployment:** revert the site change through a PR and let Pages redeploy. This does not affect the npm package.
+- **Stop publishing:** set `NPM_PUBLISH_ENABLED=false` and cancel any active publish run separately. Remove npm trust if compromised, revoke affected credentials, and review tags/workflows before re-enabling.
+
+Trusted-publishing reference: https://docs.npmjs.com/trusted-publishers/

package/SECURITY.md

@@ -10,6 +10,7 @@ Only the latest release receives fixes. Use short-lived, least-privilege credent
 
 ## Important limits
 
+- A malicious or prompt-injected model can still obtain or exfiltrate secrets through its tools. pi-secure does not prevent prompt injection or enforce secret isolation; local reveal/copy confirmations do not secure other tool paths.
 - Shell commands can transmit or persist secrets; approve only trusted tasks.
 - Exact-value output redaction does not cover transformed, encoded, partial, or already-logged values, or other tools' output.
 - Terminal recording, input logging, clipboard managers/sync, process inspection, crash dumps, and other extensions are outside the boundary.

package/index.ts

@@ -207,14 +207,30 @@ export default function (pi: ExtensionAPI) {
       timeout: Type.Optional(Type.Integer({ minimum: 1, maximum: 300 })),
     }),
     async execute(_id, params, signal, _update, ctx) {
+      if (!validName(params.name) || vault.has(params.name)) {
+        return { ...reply({ available: false, error: "Capture name is invalid or already exists. Choose a new name." }), isError: true };
+      }
       const lifetime = lifecycle;
-      const result = await secureExec({
-        isCurrent: () => lifecycle === lifetime && !lifetime.signal.aborted,
-        command: params.command, names: params.secrets ?? [], vault, cwd: ctx.cwd,
-        signal: operationSignal(signal), timeout: (params.timeout ?? 60) * 1000,
-        captureName: params.name, trimNewline: params.trimNewline ?? true,
-      });
-      return { ...reply(result), isError: !!result.error };
+      let result: Awaited<ReturnType<typeof secureExec>>;
+      try {
+        result = await secureExec({
+          isCurrent: () => lifecycle === lifetime && !lifetime.signal.aborted,
+          command: params.command, names: params.secrets ?? [], vault, cwd: ctx.cwd,
+          signal: operationSignal(signal), timeout: (params.timeout ?? 60) * 1000,
+          captureName: params.name, trimNewline: params.trimNewline ?? true,
+        });
+      } catch {
+        return { ...reply({ name: params.name, available: false, error: "Secret capture failed; output discarded." }), isError: true };
+      }
+      // Never forward helper results from capture mode. A stale native ESM
+      // helper can survive Pi reload and return ordinary execution output.
+      if (result.error || result.available !== true || result.name !== params.name || !vault.has(params.name)) {
+        const error = result.error
+          ? "Secret capture failed; output discarded."
+          : "Capture did not store a secret. Fully restart Pi before retrying.";
+        return { ...reply({ name: params.name, available: false, error }), isError: true };
+      }
+      return reply({ name: params.name, available: true });
     },
   }));
 

package/package.json

@@ -1,18 +1,51 @@
 {
   "name": "@moejay/pi-secure",
-  "version": "0.1.0",
+  "version": "0.1.4",
   "type": "module",
-  "description": "Request secrets privately and use them in subprocesses without putting values in Pi transcripts.",
-  "keywords": ["pi-package", "pi-extension", "secrets", "security", "privacy", "credentials", "clipboard", "developer-tools"],
+  "description": "Private secret entry, capture, local reveal/copy, and redacted shell execution for Pi. Transcript hygiene, not a sandbox.",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "secrets",
+    "security",
+    "privacy",
+    "credentials",
+    "clipboard",
+    "developer-tools"
+  ],
   "license": "MIT",
   "author": "moejay",
-  "repository": { "type": "git", "url": "git+https://github.com/moejay/pi-secure.git" },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/moejay/pi-secure.git"
+  },
   "homepage": "https://moejay.github.io/pi-secure/",
-  "bugs": { "url": "https://github.com/moejay/pi-secure/issues" },
-  "engines": { "node": ">=22.19.0" },
-  "publishConfig": { "access": "public", "registry": "https://registry.npmjs.org/" },
-  "files": ["index.ts", "secure.mjs", "clipboard.mjs", "README.md", "SECURITY.md", "RELEASING.md", "LICENSE"],
-  "pi": { "extensions": ["./index.ts"] },
+  "bugs": {
+    "url": "https://github.com/moejay/pi-secure/issues"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "files": [
+    "index.ts",
+    "secure.mjs",
+    "clipboard.mjs",
+    "README.md",
+    "SECURITY.md",
+    "RELEASING.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "image": "https://moejay.github.io/pi-secure/media/preview.png",
+    "video": "https://moejay.github.io/pi-secure/media/demo.mp4"
+  },
   "scripts": {
     "test": "node --test",
     "typecheck": "tsc --noEmit",
@@ -24,7 +57,7 @@
     "@earendil-works/pi-coding-agent": "1.4.0",
     "@earendil-works/pi-tui": "1.4.0",
     "@types/node": "22.20.5",
-    "typescript": "5.9.3"
+    "typescript": "7.0.2"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "*",