@moejay/pi-secure 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 moejay
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,102 @@
-# Temporary Holding Version
+# pi-secure
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Secrets for your tools. Not your transcript.**
+
+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)
+
+## 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:
+
+```sh
+pi install git:github.com/moejay/pi-secure
+```
+
+After the first npm release (not published yet):
+
+```sh
+pi install npm:@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`.
+
+## Quick start
+
+Ask Pi: “Ask me securely for my API token, then use it to call the service.” Enter the value only in the masked dialog—not in chat, a command, or a tool argument. The agent receives a name and availability status, never the entered value.
+
+## Tools
+
+### `request_secret({ name, reason })`
+
+The agent requests a secret; you enter it in a masked terminal dialog. Only name/availability is returned. Enter submits; Escape/Ctrl+C cancels. Empty, NUL, and multiline input cannot be submitted. Existing names are reused.
+
+### `capture_secret({ name, command, secrets?, trimNewline?, timeout? })`
+
+Capture a command's stdout directly into extension memory. Neither stdout nor stderr reaches the agent, even on failure. Use this to read files or fetch API responses without exposing the value in tool results:
+
+```js
+capture_secret({ name: "APP_TOKEN", command: "cat /private/path/token" })
+// Returns { name: "APP_TOKEN", available: true } only.
+show_secret({ name: "APP_TOKEN" })
+```
+
+Commands and paths are logged normally: **never embed literal secret values in arguments**. For an authenticated API request, `secrets` injects already-stored credentials as environment variables. The command should output only the value you want to capture (e.g. use `curl -f` and `jq -er .token`). Nonzero exit, empty output, NUL, timeout, cancellation, and overflow fail without returning captured output. Existing names cannot be overwritten. Removes one trailing newline by default; set `trimNewline: false` to preserve it. This replaces the earlier `generate_secret` tool; a command can still generate random values if needed.
+
+### `show_secret({ name })`
+
+Opens a local overlay **masked by default**, never a tool result:
+
+- **R**: reveal or hide. Revealing requires **Y** confirmation.
+- **C**: copy to clipboard, whether masked or visible. Copying requires **Y** confirmation.
+- **N/Escape**: dismiss an action confirmation.
+- **Enter/Escape/Ctrl+C**: close the dialog (Ctrl+C also closes during confirmation).
+
+Auto-closes after 30 seconds, including while confirming or copying. Only name/shown/copied status returns to the agent. Control characters are escaped for terminal safety; large values have a truncated display but copy in full.
+
+Clipboard support: macOS uses `/usr/bin/pbcopy`; Linux uses `wl-copy` on Wayland or `xclip`/`xsel` on X11 (install a helper separately). Values are sent through stdin, never shell arguments or terminal escape sequences. Unsupported/headless environments fail closed; there is no OSC 52, chat, or RPC fallback.
+
+**Local display and clipboard are not recording-proof:** terminal recordings, screen capture, debug logging, clipboard managers, other apps, or clipboard sync may retain values. Hiding/closing does not erase them. The clipboard is not automatically cleared—clear clipboard/history yourself after pasting.
+
+### `secure_exec({ command, secrets, timeout? })`
+
+Use named secrets for arbitrary user-authorized tasks, including saving files or credentials elsewhere:
+
+```js
+secure_exec({
+  command: 'curl -sS -H "Authorization: Bearer $GITHUB_TOKEN" https://api.github.com/user',
+  secrets: ["GITHUB_TOKEN"]
+})
+```
+
+Output is buffered, then exact known secret values are redacted from stdout/stderr. No streaming or raw-output temporary files. Only child processes receive the injected environment; Pi's global environment is unchanged.
+
+## Storage and limits
+
+- `/secret list` shows names; `/secret clear` forgets values.
+- Values live in extension memory only, not session entries, result details, or model context. They disappear on reload, session start, shutdown, or clear. JavaScript cannot guarantee memory zeroization.
+- Commands default to a 60-second timeout (configurable up to 300 seconds), with a 1 MiB combined output limit. Timeout, cancellation, and overflow discard all output.
+- Concurrent private dialogs are queued. Clearing secrets or ending the session cancels active operations and invalidates queued dialogs; clear does not revoke credentials or erase external copies.
+
+## Security boundary
+
+**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.
+
+## Development
+
+```sh
+npm ci --ignore-scripts
+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.
+
+## License
+
+[MIT](LICENSE). Independent community extension; not an official Pi product.

package/RELEASING.md

@@ -0,0 +1,32 @@
+# Releasing
+
+## Current state
+
+The npm workflow is deliberately disabled by default. No npm credential belongs in this repo, GitHub secrets, chat, or an agent tool argument.
+
+- Package: `@moejay/pi-secure`
+- Repository: `moejay/pi-secure`
+- Workflow: `publish.yml`
+- GitHub environment: `npm`
+
+## First release (human checkpoint)
+
+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.
+
+## Subsequent releases
+
+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.
+
+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.
+
+Reference: https://docs.npmjs.com/trusted-publishers/

package/SECURITY.md

@@ -0,0 +1,18 @@
+# Security policy
+
+pi-secure protects a narrow boundary: secret values stay out of its own model-facing tool results and session entries. It is not an OS sandbox, encrypted vault, or defense against malicious agents, commands, extensions, or local observers.
+
+## Report a vulnerability
+
+Please use [GitHub private vulnerability reporting](https://github.com/moejay/pi-secure/security/advisories/new) when enabled. If unavailable, open an issue asking for a private contact channel **without exploit details or credentials**. Never submit real secrets in issues, logs, screenshots, or reproductions.
+
+Only the latest release receives fixes. Use short-lived, least-privilege credentials and revoke anything you suspect was exposed.
+
+## Important limits
+
+- 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.
+- Clipboard contents are not automatically cleared: overwriting later could destroy something else you copied. Clear your clipboard and history yourself.
+- Memory is process-local; JavaScript does not guarantee zeroization.
+- Names, commands, reasons, statuses, and redacted execution output are public to the agent and normal session logs.

package/clipboard.mjs

@@ -0,0 +1,68 @@
+import { spawn } from "node:child_process";
+
+const FAILED = "Clipboard unavailable or copy failed.";
+
+/** Native clipboard only: never OSC 52 (which can leak into terminal logs).
+ * Values go only to stdin, never argv, environment, diagnostics, or results.
+ * Linux helpers may retain a background selection owner; we do not clear the
+ * clipboard automatically, since that could erase a newer clipboard value.
+ * spawnImpl/platform/env are injectable so tests never touch a real clipboard.
+ * @param {string} value
+ * @param {{signal?: AbortSignal, timeout?: number, spawnImpl?: typeof spawn,
+ *   platform?: NodeJS.Platform, env?: NodeJS.ProcessEnv}} [options]
+ */
+export async function copyToClipboard(value, {
+  signal, timeout = 5000, spawnImpl = spawn,
+  platform = process.platform, env = process.env,
+} = {}) {
+  if (signal?.aborted) return { copied: false, error: "Copy cancelled." };
+  const candidates = platform === "darwin" ? [["/usr/bin/pbcopy", []]] :
+    platform === "linux" ? [
+      ...(env.WAYLAND_DISPLAY ? [["wl-copy", ["--type", "text/plain;charset=utf-8"]]] : []),
+      ...(env.DISPLAY ? [["xclip", ["-selection", "clipboard", "-in"]], ["xsel", ["--clipboard", "--input"]]] : []),
+    ] : [];
+  // Preserve display/session connectivity, but do not pass unrelated credentials.
+  const childEnv = {};
+  for (const key of ["PATH", "HOME", "LANG", "LC_ALL", "DISPLAY", "WAYLAND_DISPLAY", "XDG_RUNTIME_DIR", "XAUTHORITY", "DBUS_SESSION_BUS_ADDRESS"]) {
+    if (typeof env[key] === "string") childEnv[key] = env[key];
+  }
+  const duration = Number.isFinite(timeout) ? Math.min(10000, Math.max(1, timeout)) : 5000;
+  const deadline = Date.now() + duration;
+  for (const [command, args] of candidates) {
+    if (signal?.aborted) return { copied: false, error: "Copy cancelled." };
+    if (Date.now() >= deadline) return { copied: false, error: "Copy timed out." };
+    const result = await new Promise((resolve) => {
+      let child, settled = false, timer;
+      const finish = (result, kill = false) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        signal?.removeEventListener("abort", abort);
+        if (kill) {
+          // Do not wait for close: a broken helper must not keep the UI alive.
+          try { child?.kill("SIGKILL"); } catch { /* Best effort. */ }
+        }
+        child?.stdin?.destroy();
+        resolve(result);
+      };
+      const abort = () => finish({ copied: false, error: "Copy cancelled." }, true);
+      try {
+        child = spawnImpl(command, args, { shell: false, stdio: ["pipe", "ignore", "ignore"], env: childEnv });
+        child.on("error", (error) => finish({ copied: false, missing: error?.code === "ENOENT" }, true));
+        // stdout/stderr are discarded at the OS boundary, including on failure.
+        child.on("exit", (code, exitSignal) => finish({ copied: code === 0 && !exitSignal }));
+        child.stdin.on("error", () => finish({ copied: false }, true));
+        timer = setTimeout(() => finish({ copied: false, error: "Copy timed out." }, true), Math.max(1, deadline - Date.now()));
+        signal?.addEventListener("abort", abort, { once: true });
+        if (signal?.aborted) abort();
+        else child.stdin.end(value, "utf8");
+      } catch (error) {
+        finish({ copied: false, missing: error?.code === "ENOENT" }, true);
+      }
+    });
+    if (result.copied) return { copied: true };
+    // Only absent executables trigger fallback. A failed write is not retried.
+    if (!result.missing) return { copied: false, error: result.error ?? FAILED };
+  }
+  return { copied: false, error: FAILED };
+}

package/index.ts

@@ -0,0 +1,271 @@
+import { Type } from "@earendil-works/pi-ai";
+import { defineTool, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Input, Key, matchesKey, truncateToWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+import { secureExec, validName } from "./secure.mjs";
+import { copyToClipboard } from "./clipboard.mjs";
+
+/** A fresh, local-only component per interaction. Confirmation never leaves the
+ * component, and neither rendering nor copying changes the tool's private data.
+ * Results describe completed actions only; masking cannot undo terminal logs.
+ */
+export function createSecretDialog({ name, value, tui, theme, done, signal, copy = copyToClipboard }: {
+  name: string; value: string | undefined; tui: { requestRender(): void }; theme: { fg(color: any, text: string): string };
+  done(result: { shown: boolean; copied: boolean }): void; signal?: AbortSignal;
+  copy?: typeof copyToClipboard;
+}) {
+  let visible = false, shown = false, copied = false, closed = false, busy = false;
+  let confirmation: "reveal" | "copy" | undefined;
+  let status = "";
+  const controller = new AbortController();
+  const cleanup = () => {
+    closed = true;
+    value = undefined;
+    visible = false;
+    clearTimeout(timer);
+    signal?.removeEventListener("abort", close);
+    controller.abort();
+  };
+  const close = () => {
+    if (closed) return;
+    cleanup();
+    done({ shown, copied });
+  };
+  // One absolute lifetime, not extended by keypresses, confirmations, or copies.
+  const timer = setTimeout(close, 30_000);
+  signal?.addEventListener("abort", close, { once: true });
+  if (signal?.aborted) close();
+  const performCopy = async () => {
+    busy = true;
+    status = "Copying…";
+    tui.requestRender();
+    try {
+      const result = await copy(value ?? "", { signal: controller.signal });
+      if (closed) return;
+      copied ||= result.copied;
+      status = result.copied ? "Copied. Clipboard is not automatically cleared." : "Copy failed. Native clipboard utility unavailable or failed.";
+    } catch {
+      if (!closed) status = "Copy failed."; // Never expose helper exceptions.
+    } finally {
+      busy = false;
+      if (!closed) tui.requestRender();
+    }
+  };
+  return {
+    render(width: number) {
+      if (closed) return [];
+      const lines = [`Secret: ${name}`];
+      if (visible) {
+        // Do not interpret control bytes, including OSC/CSI escape sequences.
+        const safe = (value ?? "").replace(/[\x00-\x1f\x7f-\x9f]/g, ch => `\\x${ch.charCodeAt(0).toString(16).padStart(2, "0")}`);
+        shown = true;
+        // Keep the controls reachable even for large captured secrets.
+        const wrapped = wrapTextWithAnsi(safe, Math.max(1, width));
+        lines.push(...wrapped.slice(0, 8));
+        if (wrapped.length > 8) lines.push("[Display truncated; copy uses the full value.]");
+      } else lines.push("******** (masked)");
+      if (confirmation) {
+        lines.push(confirmation === "reveal"
+          ? "Reveal? Terminal recordings/scrollback may retain the value."
+          : "Copy? Other apps/clipboard history or sync may retain the value.");
+        lines.push("Y: confirm • N/Esc: back");
+      } else lines.push("R: reveal/hide • C: copy • Enter/Esc/Ctrl+C: close");
+      if (status) lines.push(status);
+      lines.push("Auto-closes after 30 seconds. Hiding does not erase recordings.");
+      return lines.map((line, i) => i === 0 ? theme.fg("accent", truncateToWidth(line, width)) : truncateToWidth(line, width));
+    },
+    handleInput(data: string) {
+      if (closed) return;
+      if (matchesKey(data, Key.ctrl("c"))) { close(); return; }
+      if (confirmation) {
+        if (data === "y" || data === "Y") {
+          const action = confirmation;
+          confirmation = undefined;
+          if (action === "reveal") visible = true;
+          else void performCopy();
+        } else if (data === "n" || data === "N" || matchesKey(data, Key.escape)) confirmation = undefined;
+      } else if (matchesKey(data, Key.escape) || matchesKey(data, Key.enter)) close();
+      else if (data === "r" || data === "R") {
+        if (visible) visible = false;
+        else if (!busy) confirmation = "reveal";
+      } else if (!busy && (data === "c" || data === "C")) confirmation = "copy";
+      tui.requestRender();
+    },
+    invalidate() {},
+    dispose() { if (!closed) close(); },
+  };
+}
+
+export default function (pi: ExtensionAPI) {
+  const vault = new Map<string, string>();
+  // Every in-flight operation belongs to one vault lifetime. Forget/reload must
+  // cancel pending input, queued dialogs, and captures before clearing the vault.
+  let lifecycle = new AbortController();
+  const operationSignal = (signal?: AbortSignal) => signal
+    ? AbortSignal.any([signal, lifecycle.signal]) : lifecycle.signal;
+  const resetOperations = () => {
+    lifecycle.abort();
+    lifecycle = new AbortController();
+  };
+  let dialogQueue: Promise<unknown> = Promise.resolve();
+  const reply = (data: object) => ({
+    content: [{ type: "text" as const, text: JSON.stringify(data) }],
+    details: undefined,
+  });
+
+  pi.on("session_start", () => { resetOperations(); vault.clear(); });
+  pi.on("session_shutdown", () => { resetOperations(); vault.clear(); });
+
+  pi.registerCommand("secret", {
+    description: "List secret names or clear them: /secret list | /secret clear (never enter values here)",
+    handler: async (args, ctx) => {
+      if (args.trim() === "clear") {
+        resetOperations();
+        vault.clear();
+        ctx.ui.notify("Secrets forgotten.", "info");
+      } else if (args.trim() === "list") {
+        ctx.ui.notify([...vault.keys()].join(", ") || "No secrets stored.", "info");
+      } else {
+        ctx.ui.notify("Use /secret list or /secret clear. Never paste values into commands or chat.", "warning");
+      }
+    },
+  });
+
+  pi.registerTool(defineTool({
+    name: "request_secret",
+    label: "Request secret",
+    exposure: "model-only",
+    description: "Ask the user for a secret in a private masked dialog. Only its name and availability are returned. Use secure_exec with that name to use it. Never ask the user to paste secrets into chat. Cancelled requests must not be retried without permission.",
+    parameters: Type.Object({
+      name: Type.String({ pattern: "^[A-Za-z_][A-Za-z0-9_]*$", description: "Environment variable name, e.g. GITHUB_TOKEN" }),
+      reason: Type.String({ maxLength: 500, description: "Why the credential is needed and where it will be used" }),
+    }),
+    async execute(_id, { name, reason }, signal, _update, ctx) {
+      signal = operationSignal(signal);
+      if (signal.aborted) return reply({ name, available: false });
+      if (!validName(name)) return reply({ available: false, error: "Invalid secret name." });
+      if (vault.has(name)) return reply({ name, available: true });
+      if (ctx.mode !== "tui") return reply({ name, available: false, error: "A private terminal dialog is required." });
+      // Tools may run in parallel. Never open two secret dialogs at once.
+      const request = dialogQueue.then(async () => {
+        if (signal?.aborted) return reply({ name, available: false });
+        if (vault.has(name)) return reply({ name, available: true });
+        const value = await ctx.ui.custom<string | undefined>((tui, theme, _kb, done) => {
+          let input: Input | undefined = new Input();
+          let closed = false;
+          const finish = (value?: string) => {
+            if (closed) return;
+            closed = true;
+            input = undefined;
+            signal?.removeEventListener("abort", cancel);
+            done(value);
+          };
+          const cancel = () => finish();
+          input.onSubmit = (value) => {
+            if (value && !value.includes("\0") && !/[\r\n]/.test(value)) finish(value);
+          };
+          input.onEscape = cancel;
+          signal?.addEventListener("abort", cancel, { once: true });
+          if (signal?.aborted) cancel();
+          return {
+            render(width) {
+              const cleanReason = reason.replace(/[\x00-\x1f\x7f-\x9f]/g, " ");
+              return [
+                theme.fg("accent", truncateToWidth(`Secret requested: ${name}`, width)),
+                truncateToWidth(cleanReason, width),
+                truncateToWidth("Value: " + (input?.getValue() ? "********" : ""), width),
+                truncateToWidth("Enter: submit • Esc/Ctrl+C: cancel • single-line only", width),
+                truncateToWidth("Held in memory. Commands may use or save it; not a sandbox.", width),
+              ];
+            },
+            handleInput(data) {
+              if (matchesKey(data, Key.ctrl("c"))) cancel();
+              else input?.handleInput(data);
+              tui.requestRender();
+            },
+            invalidate() {},
+            dispose() { input = undefined; signal?.removeEventListener("abort", cancel); },
+          };
+        });
+        if (value === undefined || signal?.aborted) return reply({ name, available: false });
+        vault.set(name, value);
+        return reply({ name, available: true });
+      });
+      dialogQueue = request.catch(() => {});
+      return request;
+    },
+  }));
+
+  pi.registerTool(defineTool({
+    name: "capture_secret",
+    label: "Capture secret",
+    description: "Run a command and privately store its stdout as a named secret. Neither stdout nor stderr is returned, even on failure. Read a file or fetch an API response with the command; never put literal secret values in tool arguments. Existing names cannot be overwritten. Use show_secret to reveal locally or secure_exec to use the value.",
+    parameters: Type.Object({
+      name: Type.String({ pattern: "^[A-Za-z_][A-Za-z0-9_]*$" }),
+      command: Type.String({ description: "Command whose stdout is the value to capture. Never embed a literal secret." }),
+      secrets: Type.Optional(Type.Array(Type.String({ pattern: "^[A-Za-z_][A-Za-z0-9_]*$" }), { description: "Existing secrets to inject for authentication" })),
+      trimNewline: Type.Optional(Type.Boolean({ description: "Remove one trailing newline (default true)" })),
+      timeout: Type.Optional(Type.Integer({ minimum: 1, maximum: 300 })),
+    }),
+    async execute(_id, params, signal, _update, ctx) {
+      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 };
+    },
+  }));
+
+  pi.registerTool(defineTool({
+    name: "show_secret",
+    label: "Show secret locally",
+    exposure: "model-only",
+    description: "Open a masked local dialog for a named secret. R reveals/hides and C copies without requiring reveal; both actions require explicit confirmation. Returns only shown/copied status, never the value. Requires interactive terminal mode. Terminal recordings and clipboard history/sync may retain values.",
+    parameters: Type.Object({ name: Type.String({ pattern: "^[A-Za-z_][A-Za-z0-9_]*$" }) }),
+    async execute(_id, { name }, signal, _update, ctx) {
+      if (!validName(name)) return reply({ shown: false, copied: false, error: "Invalid secret name." });
+      if (ctx.mode !== "tui") return reply({ name, shown: false, copied: false, error: "A local terminal dialog is required." });
+      signal = operationSignal(signal);
+      const request = dialogQueue.then(async () => {
+        if (signal.aborted || !vault.has(name)) return reply({ name, shown: false, copied: false });
+        const controller = new AbortController();
+        const abort = () => controller.abort();
+        signal?.addEventListener("abort", abort, { once: true });
+        if (signal?.aborted) abort();
+        try {
+          const result = await ctx.ui.custom<{ shown: boolean; copied: boolean }>((tui, theme, _kb, done) =>
+            createSecretDialog({ name, value: vault.get(name), tui, theme, done, signal: controller.signal }),
+          { overlay: true });
+          return reply({ name, shown: result.shown, copied: result.copied });
+        } finally {
+          controller.abort();
+          signal?.removeEventListener("abort", abort);
+        }
+      });
+      dialogQueue = request.catch(() => {});
+      return request;
+    },
+  }));
+
+  pi.registerTool(defineTool({
+    name: "secure_exec",
+    label: "Secure exec",
+    description: "Run an arbitrary shell command with named secrets injected as environment variables. Use secrets for user-authorized tasks, including saving them to files or external secret stores. Reference values as quoted environment variables, never literal values in tool arguments. Keep values out of chat: do not return them through other tools, encode them to bypass redaction, or include them in messages. Output is buffered and exact known secret values are redacted. This tool is not a sandbox and does not restrict destinations or file access.",
+    parameters: Type.Object({
+      command: Type.String(),
+      secrets: Type.Array(Type.String({ pattern: "^[A-Za-z_][A-Za-z0-9_]*$" }), { minItems: 1 }),
+      timeout: Type.Optional(Type.Integer({ minimum: 1, maximum: 300, description: "Timeout in seconds (default 60)" })),
+    }),
+    async execute(_id, params, signal, _update, ctx) {
+      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,
+      });
+      return { ...reply(result), isError: !!result.error || result.exitCode !== 0 };
+    },
+  }));
+}

package/package.json

@@ -1,6 +1,34 @@
 {
   "name": "@moejay/pi-secure",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "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"],
+  "license": "MIT",
+  "author": "moejay",
+  "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"] },
+  "scripts": {
+    "test": "node --test",
+    "typecheck": "tsc --noEmit",
+    "check": "npm run typecheck && npm test",
+    "prepublishOnly": "npm run check"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "1.4.0",
+    "@earendil-works/pi-coding-agent": "1.4.0",
+    "@earendil-works/pi-tui": "1.4.0",
+    "@types/node": "22.20.5",
+    "typescript": "5.9.3"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  }
+}

package/secure.mjs

@@ -0,0 +1,115 @@
+import { spawn } from "node:child_process";
+
+export const validName = (name) => typeof name === "string" && /^[A-Za-z_][A-Za-z0-9_]*$/.test(name);
+
+export function redact(text, values) {
+  const secrets = [...new Set(values)].filter(Boolean).sort((a, b) => b.length - a.length);
+  if (!secrets.length) return text;
+  const pattern = secrets.map((s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|");
+  return text.replace(new RegExp(pattern, "g"), "[REDACTED]");
+}
+
+// No raw output, command, environment, or exception is returned to the caller.
+// Lifecycle owners should abort in-flight work and invalidate isCurrent before
+// clearing/replacing the vault. The guard also protects the capture commit.
+export async function secureExec({ command, names, vault, cwd, signal, timeout = 60_000, maxBytes = 1_048_576, captureName = /** @type {string | undefined} */ (undefined), trimNewline = true, isCurrent = () => true }) {
+  if (typeof command !== "string" || !Array.isArray(names) ||
+      !Number.isSafeInteger(timeout) || timeout < 1 || timeout > 2_147_483_647 ||
+      !Number.isSafeInteger(maxBytes) || maxBytes < 0) {
+    return { error: "Invalid command options." };
+  }
+  if (captureName !== undefined && (!validName(captureName) || vault.has(captureName))) {
+    return { error: "Capture name is invalid or already exists. Choose a new name." };
+  }
+  if (signal?.aborted || !isCurrent()) return { error: "Command cancelled." };
+  const env = Object.assign(Object.create(null), process.env);
+  const values = [...vault.values()];
+  for (const name of names) {
+    if (!validName(name) || !vault.has(name)) return { error: "A requested secret is unavailable. Use request_secret first." };
+    env[name] = vault.get(name);
+  }
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawn("/bin/sh", ["-c", command], { cwd, env, detached: true, stdio: ["ignore", "pipe", "pipe"] });
+    } catch {
+      resolve({ error: "Could not start command." });
+      return;
+    }
+    let stdout = [], stderr = [], size = 0, failure, finished = false;
+    const killGroup = () => {
+      if (!child.pid) return;
+      try { process.kill(-child.pid, "SIGKILL"); } catch { /* Already exited. */ }
+    };
+    const stop = (reason) => {
+      if (finished) return;
+      failure ??= reason;
+      stdout.length = 0; stderr.length = 0;
+      killGroup();
+      // An escaped descendant can retain these pipes after the shell dies.
+      // Never wait for it to close them after cancellation/overflow/timeout.
+      child.stdout.destroy();
+      child.stderr.destroy();
+    };
+    const abort = () => stop("Command cancelled.");
+    const timer = setTimeout(() => stop("Command timed out."), timeout);
+    signal?.addEventListener("abort", abort, { once: true });
+    if (signal?.aborted) abort();
+    const collect = (target) => (chunk) => {
+      if (failure || finished) return;
+      size += chunk.length;
+      if (size > maxBytes) {
+        stop("Command output limit exceeded; output discarded.");
+        return;
+      }
+      target.push(chunk);
+    };
+    child.stdout.on("data", collect(stdout));
+    child.stderr.on("data", collect(stderr));
+    child.stdout.on("error", () => stop("Could not read command output."));
+    child.stderr.on("error", () => stop("Could not read command output."));
+    const finish = (code) => {
+      if (finished) return;
+      finished = true;
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", abort);
+      let result;
+      try {
+        if (signal?.aborted || !isCurrent()) failure ??= "Command cancelled.";
+        if (failure) result = { error: failure };
+        else if (captureName !== undefined) {
+          // Never return stdout OR stderr in capture mode, including on failure.
+          let value = Buffer.concat(stdout).toString("utf8");
+          if (trimNewline) value = value.replace(/\r?\n$/, "");
+          if (code !== 0) result = { error: "Capture command failed; output discarded." };
+          else if (!value || value.includes("\0")) result = { error: "Captured output is empty or contains NUL; discarded." };
+          else if (vault.has(captureName)) result = { error: "Secret name already exists; captured output discarded." };
+          else {
+            vault.set(captureName, value);
+            result = { name: captureName, available: true };
+          }
+        } else if (code === null) result = { error: "Command terminated by signal; output discarded." };
+        else {
+          // Preserve launch-time values even if forgotten/replaced, but also
+          // protect secrets captured by concurrent commands before this result.
+          const redactions = [...values, ...vault.values()];
+          result = {
+            exitCode: code,
+            stdout: redact(Buffer.concat(stdout).toString("utf8"), redactions),
+            stderr: redact(Buffer.concat(stderr).toString("utf8"), redactions),
+          };
+        }
+      } catch {
+        // Fail closed if output decoding/redaction cannot be completed.
+        result = { error: "Could not process command output; output discarded." };
+      }
+      stdout.length = 0; stderr.length = 0;
+      resolve(result);
+    };
+    // A successful shell must not leave background jobs running, even when
+    // they redirect their output and therefore do not delay the close event.
+    child.on("exit", killGroup);
+    child.on("error", () => { stop("Could not run command."); finish(null); });
+    child.on("close", finish);
+  });
+}