@pinchpass/cli 1.0.0

package/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: pinchpass
+description: Generate one-time E2E-encrypted secret request links via pinchpass. Use when an agent needs to collect API keys, tokens, passwords, connection strings, or any sensitive value from the user. Trigger on keywords: API key, secret, token, credentials, password, .env.
+version: 1.0.0
+homepage: https://github.com/rubybear-lgtm/PinchPass
+metadata: { "openclaw": { "requires": { "bins": ["pinchpass"] } } }
+---
+
+# pinchpass
+
+Securely collect sensitive values from users with end-to-end encryption. The
+relay never sees the secret — encryption happens in the browser, the key lives
+only in the URL fragment.
+
+## When to use
+
+- An agent needs a value it does not have (API key, token, password, etc.)
+- The user says "I need to give you a secret" or "where do I put my key?"
+- A `.env` file needs to be populated with credentials
+
+Do **not** use for non-sensitive plaintext — there is no reason to go through
+E2E encryption for a public value.
+
+## CLI
+
+```bash
+pinchpass request <secret-name>... [flags]
+```
+
+Bare `pinchpass <name>` also works (auto-detects missing subcommand).
+
+### Flags
+
+| Flag          | Default       | Description                              |
+|---------------|---------------|------------------------------------------|
+| `-tunnel`     | false         | Open a bore.pub tunnel for a public URL  |
+| `-note`       | —             | Description shown on the form            |
+| `-out`        | `.env`        | Output .env file path                    |
+| `-ttl`        | 30            | Minutes until the link expires           |
+| `-port`       | random        | Local port to bind                       |
+| `-listen-addr`| `127.0.0.1`   | Address to listen on                     |
+| `-json`       | false         | Machine-readable JSON output             |
+
+## Workflow
+
+1. Run `pinchpass request <name> -json` to get a link
+2. Give the link to the user (the fragment `#k=<hex>` is the decryption key)
+3. User opens the link in a browser, fills in the value, submits
+4. Server waits for the submission or TTL expiry
+5. On success, the value is decrypted and written to `.env`
+
+### JSON output mode
+
+Use `-json` for machine parsing. The JSON is printed twice:
+- **Before waiting**: `{ "success": true, "url": "...", "port": N }`
+- **After completion**: `{ "success": true/false, "names": [...], "message": "..." }`
+
+## Workflow example
+
+```bash
+# Collect an API key via public tunnel
+pinchpass request GEMINI_API_KEY -tunnel -json
+# → Prints link object with url field
+# → Agent gives url to user
+# → Agent waits for result
+# → On completion, value in .env
+```
+
+## Edge cases
+
+- **One-time use**: after the first POST, the token is consumed. Retry
+  generates a 404. If it fails, generate a new link.
+- **TTL expiry**: server shuts down after the TTL. No value is saved and exit
+  code is 1. Generate a new link with a longer `-ttl` if needed.
+- **No tunnel**: without `-tunnel`, the link is only reachable on
+  `127.0.0.1:<port>`. Use for local-only workflows or when the user is on the
+  same machine.
+- **Bore.pub unreachable**: tunnel startup fails if bore.pub is down. Fall
+  back to local mode or retry.
+- **Shell escaping**: values written to `.env` are shell-escaped for `\`,
+  `"`, `$`, and backtick.

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+declare const _default: () => Promise<{
+    tool: {
+        request_secret: {
+            description: string;
+            args: {
+                names: import("zod").ZodArray<import("zod").ZodString>;
+                tunnel: import("zod").ZodOptional<import("zod").ZodBoolean>;
+                note: import("zod").ZodOptional<import("zod").ZodString>;
+                ttl: import("zod").ZodOptional<import("zod").ZodNumber>;
+            };
+            execute(args: {
+                names: string[];
+                tunnel?: boolean | undefined;
+                note?: string | undefined;
+                ttl?: number | undefined;
+            }, context: import("@opencode-ai/plugin/tool").ToolContext): Promise<import("@opencode-ai/plugin/tool").ToolResult>;
+        };
+    };
+}>;
+export default _default;

package/dist/index.js

@@ -0,0 +1,52 @@
+import { tool } from "@opencode-ai/plugin/tool";
+import { execSync } from "child_process";
+export default async () => {
+    return {
+        tool: {
+            request_secret: tool({
+                description: "Generate a one-time E2E-encrypted secret request link. " +
+                    "Use when you need to collect sensitive values (API keys, tokens, passwords) from the user. " +
+                    "The tool starts a local server, prints a link, and blocks until the user submits or the TTL expires. " +
+                    "On success the secret is saved to .env and the tool returns the result.",
+                args: {
+                    names: tool.schema
+                        .array(tool.schema.string())
+                        .min(1)
+                        .describe("Secret name(s) to collect, e.g. ['GEMINI_API_KEY']"),
+                    tunnel: tool.schema
+                        .boolean()
+                        .optional()
+                        .describe("Create a public URL via bore.pub tunnel (default: false)"),
+                    note: tool.schema
+                        .string()
+                        .optional()
+                        .describe("Description shown on the form to help the user"),
+                    ttl: tool.schema
+                        .number()
+                        .optional()
+                        .describe("Minutes until the link expires (default: 30)"),
+                },
+                async execute(args) {
+                    const cmd = ["pinchpass", "request", ...args.names, "-json"];
+                    if (args.tunnel)
+                        cmd.push("-tunnel");
+                    if (args.note)
+                        cmd.push("-note", args.note);
+                    if (args.ttl)
+                        cmd.push("-ttl", String(args.ttl));
+                    try {
+                        const stdout = execSync(cmd.join(" "), {
+                            encoding: "utf-8",
+                            timeout: (args.ttl ?? 30) * 60 * 1000,
+                        });
+                        return stdout;
+                    }
+                    catch (err) {
+                        const msg = err instanceof Error ? err.message : String(err);
+                        return `Failed to generate secret request: ${msg}`;
+                    }
+                },
+            }),
+        },
+    };
+};

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@pinchpass/cli",
+  "version": "1.0.0",
+  "description": "One-time E2E-encrypted secret request links for OpenClaw agents",
+  "type": "module",
+  "main": "./dist/index.js",
+  "files": [
+    "dist",
+    "SKILL.md"
+  ],
+  "openclaw": {
+    "extensions": [
+      "./dist/index.js"
+    ]
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@opencode-ai/plugin": "^1.16.2"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.2",
+    "typescript": "^5.9.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}