@akalsey/openclaw-gatepass 0.1.0

package/README.md

@@ -0,0 +1,30 @@
+# @akalsey/openclaw-gatepass
+
+OpenClaw plugin for [gatepass](https://github.com/akalsey/gatepass) secrets management.
+
+Installs the `gatepass` CLI and the `secrets-management` skill in one step.
+
+## Installation
+
+```
+clawhub install @akalsey/openclaw-gatepass
+```
+
+Or via npm:
+
+```
+npm install @akalsey/openclaw-gatepass
+```
+
+## What it installs
+
+- **`gatepass` CLI** — decrypt and retrieve secrets stored in `pass`
+- **`secrets-management` skill** — agent instructions for retrieving credentials at the moment of use
+
+## Updating skills
+
+Skills are pulled from the installed `@akalsey/gatepass` package at install time. To get updated skills, update the plugin:
+
+```
+npm update @akalsey/openclaw-gatepass
+```

package/openclaw.plugin.json

@@ -0,0 +1,6 @@
+{
+  "name": "@akalsey/openclaw-gatepass",
+  "description": "Secrets management for OpenClaw agents via gatepass",
+  "skills": ["skills/secrets-management"],
+  "pluginApi": "1.0"
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@akalsey/openclaw-gatepass",
+  "version": "0.1.0",
+  "description": "OpenClaw plugin for gatepass secrets management",
+  "keywords": ["openclaw", "plugin", "secrets", "gatepass", "credentials"],
+  "license": "MIT",
+  "author": "Adam Kalsey",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/akalsey/openclaw-gatepass.git"
+  },
+  "files": [
+    "scripts",
+    "openclaw.plugin.json",
+    "skills",
+    "README.md"
+  ],
+  "scripts": {
+    "postinstall": "node scripts/postinstall.js",
+    "test": "node --test 'test/**/*.test.js'"
+  },
+  "dependencies": {
+    "@akalsey/gatepass": "*"
+  },
+  "openclaw": {
+    "compat": {
+      "pluginApi": "1.0"
+    }
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/scripts/copy-skills.js

@@ -0,0 +1,26 @@
+const fs = require('fs');
+const path = require('path');
+
+function copySkills(src, dest) {
+  if (!fs.existsSync(src)) {
+    process.stderr.write(`openclaw-gatepass: skills source not found at ${src} — skipping\n`);
+    return;
+  }
+  copyDir(src, dest);
+  process.stdout.write('openclaw-gatepass: gatepass skills installed\n');
+}
+
+function copyDir(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyDir(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+module.exports = { copySkills };

package/scripts/postinstall.js

@@ -0,0 +1,11 @@
+const path = require('path');
+const { copySkills } = require('./copy-skills');
+
+try {
+  const gatepassPkg = require.resolve('@akalsey/gatepass/package.json');
+  const sourceSkills = path.join(path.dirname(gatepassPkg), 'skills');
+  const destSkills = path.join(__dirname, '..', 'skills');
+  copySkills(sourceSkills, destSkills);
+} catch (err) {
+  process.stderr.write(`openclaw-gatepass: could not install skills: ${err.message}\n`);
+}

package/skills/secrets-management/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: secrets-management
+description: Retrieve credentials at the moment of use for authenticating to web services, APIs, or browser-based logins. Use whenever a task requires a password, API token, or other secret. Credentials are retrieved through the `gatepass` CLI, which decrypts them with a bot GPG key that is unlocked once at boot.
+---
+
+# Secrets Management
+
+## When to use
+
+Whenever a task requires authenticating to a service — typing a password into a browser form, calling an API that needs a token, or anything else that requires a secret. Retrieve credentials only at the moment they are needed, never speculatively or in advance.
+
+## Retrieving a credential
+
+```bash
+gatepass get <service>
+```
+
+Example: `gatepass get metabase`
+
+The output follows an opinionated format:
+
+- **Line 1** is the password, with no prefix.
+- **Subsequent lines** are `key: value` fields, lowercase keys.
+
+```
+the-actual-password
+user: alice@example.com
+url: https://metabase.example.com
+note: anything else relevant
+```
+
+Standard field names you may encounter:
+
+| Field | Meaning |
+|---|---|
+| `user` | Username or login. Type into the username field. |
+| `url` | Service URL. Navigate here for browser logins. |
+| `email` | Email, when distinct from `user` (e.g. recovery email). |
+| `otp` | TOTP secret (otpauth:// URI or base32). Use `gatepass get --otp` to generate a current code — never try to compute one yourself. |
+| `passkey` | WebAuthn credential blob (base64 JSON). When present, use passkey authentication — do not type a password. Decode and load into your browser automation tool's virtual authenticator before navigating to the login page. See `docs/passkey-automation.md` for examples. |
+| `note` | Free-form text. |
+
+Other keys may appear — they follow the same `key: value` form and are always lowercase.
+
+For browser-based logins: navigate to the `url`, type the `user` into the username field, and type the first line into the password field.
+
+## Getting a TOTP code
+
+If a service requires a one-time password (2FA) and the entry has an `otp`
+field, ask gatepass for a current code instead of trying to compute one yourself:
+
+```bash
+gatepass get --otp <service>
+```
+
+Example: `gatepass get --otp metabase` prints a single 6-digit code on one line and
+nothing else. Use it immediately — TOTP codes rotate every 30 seconds.
+
+If the credential isn't stored, or it exists but has no `otp` field, the
+command exits with code 2 and tells you what `gatepass add` invocation to suggest
+to the human. Treat it the same way as a missing credential: stop and ask.
+
+## Listing what's available
+
+```bash
+gatepass list
+```
+
+## When a credential is missing
+
+If `gatepass get <service>` exits with code 2, the credential is either not
+stored, or (when called with `--otp`) is stored without an `otp` field. The
+error message on stderr will name the missing piece and quote the exact
+command the user should run, e.g.:
+
+```
+gatepass: credential '<service>' is not stored.
+Ask the user to add it by running:
+  gatepass add <service>
+```
+
+Stop the task at that point. Tell the user which service is missing and quote the `gatepass add` command back to them. Do not try to authenticate by other means, do not guess credentials, and do not retry.
+
+## Rules
+
+- **Retrieve credentials only at the moment you need them.** Do not fetch them in advance "to have them ready."
+- **Never include credential values in messages to the user.** Not in summaries, not in confirmations, not in error reports.
+- **Never write credential values to memory files, daily notes, or any workspace file.** Including `MEMORY.md`, scratchpads, logs, or transcripts you control.
+- **Never pass credential values into sub-agent task instructions.** If a sub-agent needs a credential, the sub-agent should retrieve it itself using this skill.
+- **If `gatepass get` exits non-zero with code 2,** the credential is missing — ask the user to add it. Do not try alternatives.
+- **If `gatepass get` exits non-zero with any other code,** something is wrong with the runtime (key not unlocked, config missing, etc.). Run `gatepass doctor` to diagnose, and report the result to the user rather than working around it.
+- **If authentication fails after `gatepass get` succeeded,** report which service failed and the error message — never the credential value.
+- **If a browser session expires mid-task,** stop and ask the user to re-authenticate. Do not silently retrieve the credential and re-login without telling them.
+- **If a credential has a `passkey:` field,** authenticate using the passkey credential rather than the password. The `passkey:` value is a base64-encoded JSON blob. Load it into your browser automation tool's virtual authenticator before navigating to the login page. The password field may also be present but should be ignored for login.
+
+## Why these rules matter
+
+For API-based auth, credentials can sometimes be injected without the agent seeing them. For browser-based auth, the agent must see the credential to type it into a form — that's unavoidable. The mitigation is to minimize where the value appears: it shows up in exactly one tool result (the `gatepass get` call) and is never copied into any other artifact.
+
+## Adding new credentials
+
+This is a human task, not an agent task. `gatepass add` is interactive only and refuses to run without a TTY. If a credential is missing, ask the user to run `gatepass add <service>` themselves.
+
+## Reference
+
+- `setup.md` — what `gatepass setup` does under the hood, and how to debug it
+- `security.md` — trust assumptions, threat model, rejected alternatives

package/skills/secrets-management/security.md

@@ -0,0 +1,64 @@
+# Security Model
+
+## Trust assumptions
+
+- Host machine is trusted.
+- Disk encryption (FileVault on macOS, LUKS on Linux) is enabled.
+- The bot user is isolated from other users on the system.
+
+## Tradeoffs
+
+This system prioritizes unattended automation over interactive security. The bot must run across reboots without anyone present to type a passphrase, which forces some compromises:
+
+- The bot's GPG passphrase is stored on disk in `~/.bot-pass.txt`.
+- The GPG key is unlocked automatically at boot.
+- `gpg-agent` holds the decrypted key in memory indefinitely (cache TTL is one year).
+
+`~/.bot-pass.txt` is the weakest link: any process running as the bot user can read it.
+
+## Protection layers
+
+| Layer | Protects |
+|---|---|
+| GPG encryption | secrets at rest |
+| Passphrase file permissions (`chmod 600`) | the GPG passphrase |
+| OS user isolation | the passphrase file from other users |
+| Disk encryption | the entire system from offline attack |
+| Per-file recipient lists | bot from decrypting human-only secrets |
+
+## Why the bot can't decrypt human-only secrets
+
+Even though the bot user can read the encrypted files in `~/.password-store/personal/`, they're encrypted only to `my-key`. The bot's `bot-key` is not a recipient, so GPG cannot decrypt them. This is enforced cryptographically, not by filesystem permissions.
+
+## Why browser auth requires LLM credential visibility
+
+For API-based services, credentials can be injected server-side without the LLM ever seeing the value. For browser-based authentication, the LLM must see the credential to type it into a form field. This is unavoidable.
+
+The mitigation is to minimize exposure: the credential is retrieved at the moment of use via `pass show`, appears in exactly one tool result (the turn where it's typed), and is never stored in workspace files, memory, or messages. See `SKILL.md` for the rules the agent follows.
+
+Preferred direction: move services from browser-based login to API-based access wherever possible, so credentials never need to enter the LLM context at all.
+
+## Rejected alternatives
+
+**Plaintext credentials file** (e.g. `~/.openclaw/credentials.json`)
+Works, but credentials are unencrypted at rest. Any process running as the bot user can read them. No access scoping.
+
+**OpenClaw native secrets** (`openclaw secrets configure`)
+Interactive wizard limited to credentials OpenClaw itself needs (provider API keys, bot tokens). No support for arbitrary secrets. `openclaw secrets set <key> <value>` is an open feature request, not implemented.
+
+**AgentSecrets**
+Sound local architecture (OS keychain storage, `agentsecrets call` for zero-knowledge API calls). Rejected due to dependency on a cloud backend of uncertain operational status. Alpha software.
+
+**Python `keyring` library**
+Cross-platform and mature. But on macOS the Keychain prompts for the user's password after timeout or reboot; in a headless VM with no one to click "Allow," credential retrieval fails silently. On headless Linux, requires `keyrings.alt` fallback backend.
+
+**`age` encryption**
+Simpler than GPG, modern cryptography, portable. But `pass` provides directory structure, git integration, `pass ls` / `pass grep`, and a mature ecosystem. Since GPG is already part of the workflow, `pass` wins on organizational features.
+
+## Future work
+
+- Secret rotation workflows.
+- Automated re-encryption of namespaces when keys change.
+- Auditability — who can decrypt what.
+- Guardrails to prevent accidental over-sharing (wrong recipient sets on insert).
+- Atomic wrapper for dual-recipient insert (`pass init` / `insert` / revert) so a human can't leave the store in dual-recipient mode by accident.

package/skills/secrets-management/setup.md

@@ -0,0 +1,216 @@
+# Setup
+
+The fast path is `gatepass setup`. This document covers what that wizard does under the hood and how to debug it.
+
+## Fast path
+
+```bash
+npm install -g gatepass   # or: npm install -g github:akalsey/Gatepass
+gatepass setup
+```
+
+The wizard:
+
+1. Verifies `gpg` and `pass` are installed (prints platform-specific install commands if not).
+2. Picks or generates your **personal** GPG key.
+3. Picks or generates a **bot** GPG key. If one or more keys with a `Gatepass Bot` name or `gatepass-bot@…` email already exist in your keyring, the wizard offers to reuse one (prompting for its passphrase, which it verifies by unlocking the key in `gpg-agent`). Otherwise it generates a new bot key with a strong random passphrase.
+4. Writes the (verified or generated) passphrase to `~/.bot-pass.txt` (mode 600).
+5. Configures `~/.gnupg/gpg.conf` (`pinentry-mode loopback`) and `~/.gnupg/gpg-agent.conf` (`allow-loopback-pinentry`, one-year cache TTL).
+6. Initializes the password store: default recipient is your personal key; the bot-readable namespace (default `bot/`) is dual-recipient (bot key + your key).
+7. Saves `~/.config/gatepass/config.json` with the namespace, both fingerprints, the passphrase file path, and the password store location.
+8. Unlocks the bot key in `gpg-agent`.
+9. Inserts a test secret, retrieves it, and removes it — to confirm the pipeline works.
+10. Offers to install boot-time unlock as a launchd agent (macOS) or systemd user service (Linux).
+
+After setup, the runtime calls `gatepass get <service>` and gets the credential without prompting.
+
+## Storage layout
+
+`pass` stores each secret as an individually GPG-encrypted file. Paths represent namespaces:
+
+```
+~/.password-store/
+  bot/                    # bot-readable (dual-recipient)
+    metabase.gpg
+    posthog.gpg
+  personal/                 # human-only (single-recipient)
+    bank.gpg
+```
+
+Access control is enforced by *which GPG keys each file is encrypted to*, not filesystem permissions alone. The bot's key physically cannot decrypt entries it isn't a recipient of. `gatepass setup` configures the bot-readable namespace so that everything inserted under it is automatically encrypted to both keys — there's no insert-time dance.
+
+## Configuration
+
+`~/.config/gatepass/config.json`:
+
+```json
+{
+  "namespace": "bot",
+  "botKeyId":  "ABCDEF0123456789...",
+  "humanKeyId":"FEDCBA9876543210...",
+  "passphraseFile": "/Users/alice/.bot-pass.txt",
+  "passwordStore": "/Users/alice/.password-store",
+  "bootUnlockInstalled": true
+}
+```
+
+Environment overrides:
+
+- `ZUUL_NAMESPACE` — bot-readable namespace
+- `ZUUL_CONFIG_DIR` — config directory (default `~/.config/gatepass`)
+- `PASSWORD_STORE_DIR` — pass storage location
+
+## Boot-time unlock
+
+`gatepass setup` offers to install one of:
+
+- **macOS**: `~/Library/LaunchAgents/ai.openclaw.gatepass-unlock.plist`, loaded with `launchctl`.
+- **Linux**: `~/.config/systemd/user/gatepass-unlock.service`, enabled with `systemctl --user`.
+
+Either runs `gatepass unlock` at every login, which seeds `gpg-agent` so subsequent `gatepass get` calls don't prompt. If the service isn't installed, the bot will need `gatepass unlock` manually after every reboot.
+
+## Importing existing keys
+
+Three common cases:
+
+### 1. You already have a personal GPG key in this machine's keyring
+
+Just run `gatepass setup`. The personal-key picker lists every secret key in your keyring (`gpg --list-secret-keys`) and lets you reuse one. Nothing is regenerated, and your existing key isn't modified — it just becomes the recipient for everything you store under `pass`.
+
+The only side-effect on your existing GPG setup: `gatepass setup` appends `pinentry-mode loopback` to `~/.gnupg/gpg.conf` and `allow-loopback-pinentry`, `default-cache-ttl`, and `max-cache-ttl` to `~/.gnupg/gpg-agent.conf`. These are required for the bot to decrypt without a TTY. If that conflicts with how you use GPG day-to-day (e.g., you rely on a graphical pinentry for signing email), run gatepass under a dedicated keyring:
+
+```bash
+export GNUPGHOME="$HOME/.gnupg-gatepass"
+mkdir -p -m 700 "$GNUPGHOME"
+gatepass setup
+```
+
+Then export `GNUPGHOME=$HOME/.gnupg-gatepass` in whatever environment runs `gatepass get` (the agent's launchd/systemd unit, your shell rc, etc.). Gatepass, gpg-agent, and pass all honour `GNUPGHOME`, so this fully isolates the two keyrings.
+
+### 2. You have a personal key in a backup file (not yet in the keyring)
+
+```bash
+gatepass import-key /path/to/my-key.asc
+gatepass setup           # the imported key now shows up in the picker
+```
+
+`gatepass import-key` with no role flag is a friendly wrapper around `gpg --import` — it imports the file and reports the new fingerprints. After that, `gatepass setup` treats the key like any other in-keyring key.
+
+### 3. You're moving a bot key from another machine
+
+```bash
+gatepass import-key bot-key.asc --as-bot --passphrase-file old-bot-pass.txt
+```
+
+This:
+
+1. Imports the key file into the GPG keyring.
+2. Reads the bot passphrase from the file you pass (or prompts if the flag is omitted).
+3. Writes it to `~/.bot-pass.txt` (mode 600, replacing any prior file — backed up in memory and restored if the unlock test fails).
+4. Verifies by unlocking the key in `gpg-agent`.
+5. Saves `botKeyId` (and `passphraseFile`) to `~/.config/gatepass/config.json`.
+
+If the new machine has never run `gatepass setup`, follow up with `gatepass setup` — it will skip bot-key generation (sees the configured key) and just configure the personal key, pass store, and boot-time unlock.
+
+### `gatepass import-key` flags
+
+| Flag | Purpose |
+|---|---|
+| `--as-bot` | Configure the imported key as the Gatepass bot key. |
+| `--as-personal` | Configure the imported key as your personal recipient. |
+| `--passphrase-file FILE` | Read the bot passphrase from a file (otherwise prompted). |
+| `--fingerprint FPR` | Pick a specific fingerprint when the file holds more than one key, or to assign a key that's already in the keyring. |
+
+Switching keys when the password store already has entries: changing `humanKeyId` orphans every existing entry until you re-run `pass init <new-fingerprint>` and `pass init --path <namespace> <bot-fpr> <new-fingerprint>`, which re-encrypts the store. `gatepass import-key --as-personal` warns about this and asks for confirmation before updating config.
+
+## Cross-machine replication
+
+`~/.password-store/` syncs between machines via Syncthing (or any tool that copies files). Files in transit are GPG-encrypted blobs — safe even if the sync channel is compromised. Both machines need the same bot key imported.
+
+To migrate to a new machine using the import command:
+
+```bash
+# on the old machine
+gpg --export-secret-keys <bot-fingerprint> > bot-key.asc
+scp bot-key.asc ~/.bot-pass.txt ~/.config/gatepass/config.json new-machine:
+
+# on the new machine
+mkdir -p ~/.config/gatepass && mv config.json ~/.config/gatepass/
+gatepass import-key bot-key.asc --as-bot --passphrase-file .bot-pass.txt
+rm .bot-pass.txt           # the import wrote ~/.bot-pass.txt for you
+gatepass doctor
+```
+
+Or, if you'd rather do the steps by hand:
+
+```bash
+# on the new machine
+gpg --import bot-key.asc
+mkdir -p ~/.config/gatepass && mv config.json ~/.config/gatepass/
+mv .bot-pass.txt ~/.bot-pass.txt
+chmod 600 ~/.bot-pass.txt
+gatepass unlock
+gatepass doctor
+```
+
+## Debugging
+
+`gatepass doctor` checks every prerequisite individually: tools installed, config present, both keys in keyring, passphrase file mode, password store initialized, namespace recipients, agent unlocked, boot-time unlock installed. Run it whenever something feels off.
+
+If `gatepass get` fails:
+
+- Exit code 2 — credential not stored. Run `gatepass add <service>`.
+- Exit code 3 — `gatepass setup` hasn't been run.
+- Exit code other — check `gatepass doctor`.
+
+## Manual install (if `gatepass setup` won't work)
+
+If you need to do this by hand, the commands `gatepass setup` runs under the hood are roughly:
+
+```bash
+# Generate bot key
+gpg --batch --pinentry-mode loopback --gen-key <<EOF
+Key-Type: RSA
+Key-Length: 4096
+Name-Real: Gatepass Bot
+Name-Email: gatepass-bot@$(hostname)
+Expire-Date: 0
+Passphrase: <generated>
+%commit
+EOF
+
+# Configure agent
+echo 'pinentry-mode loopback' >> ~/.gnupg/gpg.conf
+cat >> ~/.gnupg/gpg-agent.conf <<EOF
+allow-loopback-pinentry
+default-cache-ttl 31536000
+max-cache-ttl 31536000
+EOF
+gpgconf --reload gpg-agent
+
+# Initialize pass
+pass init <your-fingerprint>
+pass init --path bot <bot-fingerprint> <your-fingerprint>
+
+# Stash passphrase
+echo '<bot-passphrase>' > ~/.bot-pass.txt
+chmod 600 ~/.bot-pass.txt
+
+# Unlock
+gpg --batch --yes --pinentry-mode loopback \
+    --passphrase-file ~/.bot-pass.txt \
+    --local-user <bot-fingerprint> \
+    --sign <<< gatepass-unlock
+```
+
+## Dependencies
+
+`pass` requires `gpg` and standard Unix tools. `gatepass` itself requires Node 18+.
+For TOTP support (`gatepass add --otp` verification and `gatepass get --otp`), install
+`oathtool` from the `oath-toolkit` package.
+
+| Platform | Install |
+|---|---|
+| macOS | `brew install pass gnupg oath-toolkit` |
+| Debian/Ubuntu | `apt install pass gnupg oathtool` |
+| Fedora/RHEL | `dnf install pass gnupg2 oathtool` |