[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M75H19XSE9PA29Z7K5F8AS2D":3,"skill-same:01M75H19XSE9PA29Z7K5F8AS2D":47},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":27,"repositoryHtmlUrl":28,"repositoryHomepageUrl":6,"ownerHtmlUrl":29,"ownerBlogUrl":30,"ownerDescription":31,"updatedAt":32,"install":33,"resources":46},"01M75H19XSE9PA29Z7K5F8AS2D","safe-encryption",null,"Encrypt, decrypt, and manage keys with the SAFE CLI — a modern GPG alternative with post-quantum support.","javimosch\u002Fopen-claw-skills","javimosch","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F12900508?v=4","01M6D3F2AS6PV75ET9PZ1QGP8J","Javier Leandro Arancibia","01M75B8NCTAJG9WH5YNZH7C3D8",0,"MIT","https:\u002F\u002Fgithub.com\u002Fjavimosch\u002Fopen-claw-skills\u002Fblob\u002Fmain\u002Fskills\u002Fgrittygrease\u002Fsafe-encryption-skill\u002FSKILL.md",[],[],"2026-11-12 13:55:43",false,"---\nname: safe-encryption\ndescription: Encrypt, decrypt, and manage keys with the SAFE CLI — a modern GPG alternative with post-quantum support.\n---\n\n# SAFE Encryption Tool\n\nSAFE is a modern encryption CLI with post-quantum support, multi-recipient encryption, and composable authentication.\n\n## Behavior Guidelines\n\nWhen this skill is loaded:\n1. Check if `safe` is installed (`which safe`). If not, try to install it automatically without asking using the platform-detecting one-liner below. If installation fails (restricted environment, no shell access), fall back to the web interface at [https:\u002F\u002Fthesafe.dev](https:\u002F\u002Fthesafe.dev) — see \"Browser-Based Alternative\" below.\n2. When the user asks to encrypt\u002Fdecrypt, just do it. Don't ask for confirmation.\n3. If a password is needed and not provided, use `-p` without a value (prompts interactively or reads `SAFE_PASSPHRASE` env var). In automation, use `-p env:VARNAME` to read from environment variables.\n4. If a key file is needed, run `safe keys` to check existing identities and recipients. If no key exists, run `safe keygen x25519` to generate one (auto-stores to `~\u002F.safe\u002F`).\n5. **Always use absolute paths** for key files and encrypted files to avoid working directory issues.\n6. **Always pipe instead of writing temp files.** When decrypting inline\u002Fembedded content (base64, pasted data), pipe directly: `echo \"...\" | base64 -d | safe decrypt -k key.key`. Never write intermediate `.safe` files to `\u002Ftmp` or elsewhere.\n7. **Bare name recipients work.** Use `-r alice` instead of `-r \u002Ffull\u002Fpath\u002Fto\u002Falice.x25519.pub` when the recipient is in `~\u002F.safe\u002Frecipients\u002F`.\n8. **Decrypt auto-discovers keys.** If no `-k` or `-p` is provided, `safe decrypt` automatically tries all keys in `~\u002F.safe\u002Fkeys\u002F`.\n\n## Installation\n\nDownload the prebuilt binary from [thesafe.dev\u002Fdownload](https:\u002F\u002Fthesafe.dev\u002Fdownload\u002F):\n\n**macOS Apple Silicon:**\n```bash\ncurl -sL https:\u002F\u002Fthesafe.dev\u002Fdownloads\u002Fsafe-darwin-arm64 -o safe && chmod +x safe && sudo mv safe \u002Fusr\u002Flocal\u002Fbin\u002F\n```\n\n**macOS Intel:**\n```bash\ncurl -sL https:\u002F\u002Fthesafe.dev\u002Fdownloads\u002Fsafe-darwin-amd64 -o safe && chmod +x safe && sudo mv safe \u002Fusr\u002Flocal\u002Fbin\u002F\n```\n\n**Linux x86_64:**\n```bash\ncurl -sL https:\u002F\u002Fthesafe.dev\u002Fdownloads\u002Fsafe-linux-amd64 -o safe && chmod +x safe && sudo mv safe \u002Fusr\u002Flocal\u002Fbin\u002F\n```\n\n**Linux ARM64:**\n```bash\ncurl -sL https:\u002F\u002Fthesafe.dev\u002Fdownloads\u002Fsafe-linux-arm64 -o safe && chmod +x safe && sudo mv safe \u002Fusr\u002Flocal\u002Fbin\u002F\n```\n\n**Auto-detect platform (one-liner):**\n```bash\nwhich safe || { OS=$(uname -s | tr '[:upper:]' '[:lower:]'); ARCH=$(uname -m); \\\n  [ \"$ARCH\" = \"arm64\" ] || [ \"$ARCH\" = \"aarch64\" ] && ARCH=arm64 || ARCH=amd64; \\\n  curl -sL \"https:\u002F\u002Fthesafe.dev\u002Fdownloads\u002Fsafe-${OS}-${ARCH}\" -o safe && chmod +x safe && sudo mv safe \u002Fusr\u002Flocal\u002Fbin\u002F; }\n```\n\nVerify installation:\n```bash\nsafe --help\n```\n\n**Optional: verify checksum** (SHA-256 values from [checksums.txt](https:\u002F\u002Fthesafe.dev\u002Fdownloads\u002Fchecksums.txt)):\n```\nddf638ccfd119d9c3351825a2e3f9e3660f754009eb9b106d7bba8cd698c3df4  safe-darwin-arm64\n6be4942048a23e99485c0123cf0bb4786613a3dabbcc6927aa478cd0e719ad0b  safe-darwin-amd64\n85c7822ac0309e62ca29d03394bfe87a506f329f61c30b070c379a6d2f5af815  safe-linux-amd64\n33207a4c6bbf85b8299f2f75e18aa6e13f9a8ae4bcee72a9d869034d78ba4cac  safe-linux-arm64\n```\n\n### Installation Debugging\n\n**\"safe: command not found\"** after install:\n- Check if binary exists: `ls -la \u002Fusr\u002Flocal\u002Fbin\u002Fsafe`\n- If sudo failed, install to user dir: `mv safe ~\u002F.local\u002Fbin\u002F && export PATH=\"$HOME\u002F.local\u002Fbin:$PATH\"`\n- Refresh shell: `hash -r` or start new terminal\n\n**Permission denied on \u002Fusr\u002Flocal\u002Fbin**:\n- Use sudo: `sudo mv safe \u002Fusr\u002Flocal\u002Fbin\u002F`\n- Or install to user dir: `mkdir -p ~\u002F.local\u002Fbin && mv safe ~\u002F.local\u002Fbin\u002F`\n\n### When CLI Is Unavailable — Browser-Based Alternative\n\nIf CLI installation fails or isn't possible (restricted environment, no build tools, no shell access, sandboxed IDE, etc.), use the web interface at **[https:\u002F\u002Fthesafe.dev](https:\u002F\u002Fthesafe.dev)**.\n\nThis is a fully functional SAFE implementation running in the browser — not a demo. All cryptographic operations happen client-side. No data leaves the browser.\n\nThe web interface supports all core SAFE operations via a single-page layout with these sections:\n- **ENCRYPT tab**: Encrypt data with passwords, public keys, passkeys, or GitHub usernames\n- **DECRYPT tab**: Decrypt SAFE messages with passwords, private keys, passkeys, or GitHub keys\n- **KEYCHAIN section**: Save, import, export, and manage keys and passwords\n- **ADVANCED section**: Lock Management (add\u002Fremove recipients), Re-encrypt Demo, Tests\n- **LOG section**: View operation log output\n\n**Manual workflow (no automation needed):**\n\nUsers can interact with the web interface directly:\n\n1. **Encrypt**: Enter plaintext, add recipients (key, password, passkey, or GitHub username), click \"ENCRYPT\". Copy or download the output.\n2. **Decrypt**: Paste\u002Fupload\u002FURL-load a SAFE message, add credentials (private key, password, passkey, or GitHub), click \"DECRYPT\". Copy or download the plaintext.\n\nGenerated keys are automatically saved in the KEYCHAIN section and can be reused across operations.\n\n**Agent with MCP browser tools (Playwright, Puppeteer, etc.):**\n\nIf you have access to browser automation tools (e.g., Playwright MCP server, Claude in Chrome, Puppeteer MCP), you can drive the web interface directly.\n\n**Key behaviors to know:**\n- After encrypting, output auto-populates into the decrypt section's SAFE message input\n- The browser auto-matches saved credentials and pre-adds them to decrypt\n- Generated keys are auto-saved to the Credentials section (04)\n- Always take a snapshot (`browser_snapshot`) after each action to get updated element references\n\n**ARIA labels for automation:**\n\nThe interface uses semantic ARIA roles throughout:\n\n| Element | ARIA Label | Role |\n|---------|-----------|------|\n| KEM type selector | \"Select key encapsulation mechanism type\" | combobox |\n| Generate button | \"Generate new keypair with selected KEM type\" | button |\n| Plaintext input | \"Enter plaintext message to encrypt\" | textbox |\n| Add Step button | \"Add encryption step to recipient path\" | button |\n| Step type selector | \"Select encryption step type\" | combobox |\n| Password field (encrypt) | \"Enter password for encryption step\" | textbox |\n| Confirm step | \"Confirm encryption step\" | button |\n| Encrypt button | \"Encrypt plaintext with configured settings and recipient path\" | button |\n| Encrypted output | \"Encrypted SAFE message output\" | textbox |\n| SAFE message input | \"Paste encrypted SAFE message to decrypt\" | textbox |\n| Add credential button (decrypt) | \"Add credential to decryption attempt\" | button |\n| Add credential button (keychain) | \"Add credential to keychain\" | button |\n| Add all keychain button | \"Add all keychain entries as credentials\" | button |\n| Credential type selector | \"Select credential type\" | combobox |\n| New Passkey menu item | \"Create a new passkey\" | menuitem |\n| Password field (decrypt) | \"Enter password for decryption\" | textbox |\n| Confirm credential | \"Confirm credential\" | button |\n| Decrypt button | \"Decrypt SAFE message using provided keychain\" | button |\n| Decrypted output | \"Decrypted plaintext message\" | textbox |\n| Copy buttons | \"Copy encrypted SAFE message to clipboard\" \u002F \"Copy decrypted plaintext to clipboard\" | button |\n| Download buttons | \"Download encrypted SAFE message as file\" \u002F \"Download decrypted file\" | button |\n| Share button (output) | \"Share encrypted SAFE message via URL\" \u002F \"Share decrypted output via URL\" | button |\n| Send button (output) | \"Send encrypted output over WebRTC\" | button (encrypted output only) |\n| Clear button (output) | \"Clear encrypted output\" \u002F \"Clear decrypted output\" | button |\n| Share button (keychain) | \"Share public key via URL\" | button |\n| Label button (keychain) | \"Rename key label\" | button |\n| Use File toggles | \"Use file instead of plaintext input\" \u002F \"Use file instead of SAFE message input\" | generic (clickable) |\n| Navigation links | New (#keygen), Encrypt (#encrypt), Decrypt (#decrypt), Keychain (#keyring), Advanced (expandable) | link |\n| Advanced sections | #unlock, #reencrypt, #tests, #log | link (under Advanced dropdown) |\n| Sections | `role=\"region\"` with labels like \"01 \u002F Key Generation\" | region |\n| Log output | \"Activity log showing operations and their results\" | log |\n\n**Note on Advanced navigation**: The Advanced sections (#unlock, #reencrypt, #tests, #log) are accessed via an \"Advanced\" navigation item that expands to show these additional features.\n\n**Note on terminology**: The UI currently uses mixed terminology - Section 04 is labeled \"Keychain\" and the decrypt button references \"keychain\", but the decrypt section's credential management buttons still use \"Credentials\" in some ARIA labels (e.g., \"Add all keychain entries as credentials\"). Both terms refer to the same saved keys\u002Fpasswords.\n\n**Keychain shortcut buttons:**\n\nEach saved key in Section 04 (Keychain) has quick action buttons:\n- **Enc**: Adds the public key as an encryption recipient step (one click — skips the Add Step → select type → paste → OK workflow)\n- **Dec**: Adds the private key as a decrypt credential (one click — skips the Add → select type → paste → OK workflow)\n- **PUB**: Shows\u002Fcopies the public key\n- **PRIV**: Shows\u002Fcopies the private key\n- **Share**: Generates a shareable URL for the public key\n- **Label**: Rename the key for easier identification\n- **Del**: Removes the key from the keychain\n\n**Prefer using Enc\u002FDec shortcuts** over the manual Add Step flow when keys are saved in the keychain — it reduces 4 interactions to 1.\n\n**File upload:**\n\nBoth encrypt and decrypt sections have a \"Use File\" toggle. Clicking it triggers a file chooser dialog. With MCP Playwright, use `browser_file_upload` to provide the file path. Note: file paths must be within the MCP server's allowed directories.\n\n**Example: Encrypt with password (MCP Playwright)**\n\n```\n# 1. Navigate\nbrowser_navigate(url=\"https:\u002F\u002Fthesafe.dev\")\nbrowser_snapshot()\n\n# 2. Type plaintext (use ref from snapshot for \"Enter plaintext message to encrypt\")\nbrowser_type(ref=\u003Cplaintext-ref>, text=\"secret data\")\n\n# 3. Add password step\nbrowser_click(ref=\u003Cadd-step-button-ref>)      # \"Add encryption step to recipient path\"\nbrowser_snapshot()                              # Get refs for step config form\n\n# 4. Select Password type (default may be \"Public Key\")\nbrowser_select_option(ref=\u003Cstep-type-ref>, values=[\"Password\"])  # \"Select encryption step type\"\nbrowser_snapshot()                              # Get password field ref\n\n# 5. Enter password\nbrowser_type(ref=\u003Cpassword-ref>, text=\"my-password\")  # \"Enter password for encryption step\"\n\n# 6. Confirm the step\nbrowser_click(ref=\u003Cok-ref>)                    # \"Confirm encryption step\"\n\n# 7. Encrypt\nbrowser_click(ref=\u003Cencrypt-ref>)               # \"Encrypt plaintext with configured settings...\"\nbrowser_snapshot()                              # Output is in \"Encrypted SAFE message output\" textbox\n\n# Optional: Share or clear the output\n# browser_click(ref=\u003Cshare-button-ref>)        # \"Share encrypted SAFE message via URL\"\n# browser_click(ref=\u003Cclear-button-ref>)        # \"Clear encrypted output\"\n```\n\n**Example: Encrypt with saved key (fastest path)**\n\n```\n# 1. Navigate\nbrowser_navigate(url=\"https:\u002F\u002Fthesafe.dev\")\nbrowser_snapshot()\n\n# 2. Type plaintext\nbrowser_type(ref=\u003Cplaintext-ref>, text=\"secret data\")\n\n# 3. Click \"Enc\" on a saved key in Credentials section (one click adds recipient)\nbrowser_click(ref=\u003Cenc-button-ref>)\n\n# 4. Encrypt\nbrowser_click(ref=\u003Cencrypt-ref>)\nbrowser_snapshot()\n```\n\n**Example: Decrypt from cold (no auto-populated credentials)**\n\n```\n# 1. Paste SAFE message into decrypt input\nbrowser_type(ref=\u003Csafe-message-ref>, text=\"-----BEGIN SAFE UNLOCK-----\\n...\")\n\n# 2. Add credential\nbrowser_click(ref=\u003Cadd-credential-ref>)        # \"Add credential to decryption attempt\"\nbrowser_snapshot()\n\n# 3. Select Password type (default is \"Private Key\")\nbrowser_select_option(ref=\u003Ccredential-type-ref>, values=[\"Password\"])\nbrowser_snapshot()\n\n# 4. Enter password\nbrowser_type(ref=\u003Cpassword-ref>, text=\"my-password\")\n\n# 5. Confirm credential\nbrowser_click(ref=\u003Cconfirm-ref>)               # \"Confirm credential\"\n\n# 6. Decrypt\nbrowser_click(ref=\u003Cdecrypt-ref>)               # \"Decrypt SAFE message using provided credentials\"\nbrowser_snapshot()                              # Output is in \"Decrypted plaintext message\" textbox\n```\n\n**Example: Same-session encrypt→decrypt (auto-populated)**\n\nAfter encrypting, the output auto-populates into the decrypt section. If the matching key is saved in credentials, it auto-adds the private key. Just click Decrypt — no manual credential entry needed.\n\n**Programmatic browser automation (standalone scripts):**\n\nFor non-MCP environments, use Playwright or Puppeteer directly:\n\n```python\n# Example with Playwright (Python)\nfrom playwright.sync_api import sync_playwright\n\nwith sync_playwright() as p:\n    browser = p.chromium.launch()\n    page = browser.new_page()\n    page.goto('https:\u002F\u002Fthesafe.dev')\n\n    # Generate X25519 keypair\n    page.get_by_role(\"combobox\", name=\"Select key encapsulation mechanism type\").select_option(\"X25519\")\n    page.get_by_role(\"button\", name=\"Generate new keypair\").click()\n\n    # Encrypt with password\n    page.get_by_role(\"textbox\", name=\"Enter plaintext message to encrypt\").fill(\"secret message\")\n    page.get_by_role(\"button\", name=\"Add encryption step to recipient path\").click()\n    page.get_by_label(\"Select encryption step type\").select_option(\"Password\")\n    page.get_by_role(\"textbox\", name=\"Enter password for encryption step\").fill(\"mypassword\")\n    page.get_by_role(\"button\", name=\"Confirm encryption step\").click()\n    page.get_by_role(\"button\", name=\"Encrypt plaintext\").click()\n\n    # Read encrypted output\n    encrypted = page.get_by_label(\"Encrypted SAFE message output\").input_value()\n\n    # Decrypt (message and credentials auto-populate from encrypt)\n    page.get_by_role(\"button\", name=\"Decrypt SAFE message\").click()\n    decrypted = page.get_by_label(\"Decrypted plaintext message\").input_value()\n\n    print(f\"Decrypted: {decrypted}\")  # \"secret message\"\n    browser.close()\n```\n\n**Multi-Recipient Encryption:**\n\nBoth the browser UI and CLI support encrypting for multiple recipients. Each recipient can decrypt the message independently using their own credential.\n\n**Browser workflow:**\n1. Configure first recipient in \"Recipient 1\" (password or public key)\n2. Click \"+ Add Recipient\" button\n3. Configure second recipient in \"Recipient 2\"\n4. Repeat for additional recipients (no limit)\n5. Click \"Encrypt\" - message is encrypted once but decryptable by any recipient\n\n**How it works:**\n- Each recipient gets their own UNLOCK block in the SAFE message\n- File is encrypted once with a symmetric key\n- Symmetric key is wrapped separately for each recipient\n- Any recipient can decrypt using their credential (password or private key)\n- Recipients cannot see who else has access\n\n**CLI multi-recipient examples:**\n```bash\n# Encrypt for multiple recipients using -r flag multiple times\nsafe encrypt -i file.txt -o file.safe -r alice.pub -r bob.pub -r charlie.pub\n\n# Mix recipient types (password + keys)\nsafe encrypt -i file.txt -o file.safe -p mypassword -r alice.pub -r bob.pub\n\n# Encrypt for GitHub users (fetches public keys from GitHub)\nsafe encrypt -i file.txt -o file.safe -r github:grittygrease\n\n# Multiple GitHub users\nsafe encrypt -i file.txt -o file.safe -r github:alice -r github:bob\n\n# Encrypt for GitHub users and a password\nsafe encrypt -i file.txt -o file.safe -p teampassword -r github:alice -r github:bob\n```\n\n**GitHub username recipient (`github:username`):**\n- Fetches SSH public keys from `https:\u002F\u002Fgithub.com\u002F{username}.keys`\n- Automatically converts p-256 and x25519 keys to SAFE format\n- Both key types are added as separate recipients if available\n- Requires user to have public keys on their GitHub profile\n- Error if no keys found: `github:username: no keys found`\n\n**Example output:**\n```bash\n$ safe encrypt -i test.txt -o test.safe -r github:grittygrease\n# Creates UNLOCK blocks for both p-256 and x25519 keys from GitHub\n\n$ safe info -i test.safe\nLOCK Blocks: 2\n  [0] hpke(kem=p-256,id=QyLFP\u002F...)\n  [1] hpke(kem=x25519,id=r1VeL...)\n```\n\n**Agent-to-Agent Communication via GitHub Gist:**\n\nAgents can securely exchange encrypted messages using GitHub Gist as a transport layer. This enables asynchronous, persistent communication between agents with different GitHub accounts.\n\n**Complete Workflow:**\n\n**Agent A (Sender):**\n```bash\n# 1. Create message for Agent B\necho \"Task completed. Results attached.\" > message.txt\n\n# 2. Encrypt for Agent B's GitHub account\nsafe encrypt -i message.txt -o message.safe -r github:agentb-username\n\n# 3. Upload encrypted message to public Gist\ngh gist create message.safe --desc \"Encrypted message for agentb-username\" --public\n\n# Output: https:\u002F\u002Fgist.github.com\u002Fagenta-username\u002F{gist-id}\n```\n\n**Agent B (Receiver):**\n```bash\n# Method 1: Direct pipe (simplest, auto-discovers keys)\ncurl -sL https:\u002F\u002Fgist.github.com\u002Falice\u002F{gist-id}\u002Fraw | safe decrypt\n\n# Method 2: Download, inspect, then decrypt\ncurl -sL https:\u002F\u002Fgist.github.com\u002Falice\u002F{gist-id}\u002Fraw > received.safe\nsafe info -i received.safe  # Verify sender and encryption details\nsafe decrypt -i received.safe -o message.txt\n\n# Method 3: Explicit key (if auto-discovery doesn't work)\ncurl -sL https:\u002F\u002Fgist.github.com\u002Falice\u002F{gist-id}\u002Fraw | safe decrypt -k ~\u002F.safe\u002Fkeys\u002Fbob.x25519.key\n```\n\n**SSH Key Auto-Discovery (SAFE CLI v2.3+):**\n\nThe SAFE CLI automatically discovers and uses SSH private keys from `~\u002F.ssh\u002F`:\n- ✅ **Ed25519 keys** → converted to X25519\n- ✅ **P-256 ECDSA keys** → used directly\n- ✅ **Unencrypted keys only** (passphrase-protected keys silently skipped)\n- ✅ **Zero configuration** - just works if your SSH keys match GitHub public keys\n\n**Auto-Discovery Order:**\n1. `~\u002F.safe\u002Fkeys\u002F*.key` - Native SAFE format keys (checked first)\n2. `~\u002F.ssh\u002F*` - All SSH private keys in `~\u002F.ssh\u002F` directory\n   - Ed25519 keys → converted to X25519\n   - P-256 ECDSA keys → used directly\n\n**Example Auto-Discovery Output:**\n```bash\n$ curl -sL https:\u002F\u002Fgist.github.com\u002F...\u002Fraw | safe decrypt\nsafe: using SSH key ~\u002F.ssh\u002Fid_ed25519\nsafe: trying 3 key(s) (2 native + 1 SSH)\n[decrypted message]\n```\n\n**Key Requirements:**\n- **Agent B must have private keys** that correspond to the public keys on their GitHub profile\n- GitHub SSH keys must be added to `https:\u002F\u002Fgithub.com\u002F{username}.keys`\n- Private keys can be in `~\u002F.safe\u002Fkeys\u002F` (SAFE format) **OR** `~\u002F.ssh\u002F` (OpenSSH format)\n- Gist can be public (encrypted content is safe) or private for additional obscurity\n\n**Multi-Agent Broadcast:**\n```bash\n# Encrypt for multiple agents\nsafe encrypt -i broadcast.txt -o broadcast.safe \\\n  -r github:agent1 \\\n  -r github:agent2 \\\n  -r github:agent3\n\n# Any of the three agents can decrypt independently\ngh gist create broadcast.safe --desc \"Team update\" --public\n```\n\n**Agent Identity Setup:**\n\nTo enable decryption, agents need to set up their GitHub SSH keys and store private keys:\n\n```bash\n# Option 1: Use existing SSH keys (simplest - zero setup!)\n# If you already have ~\u002F.ssh\u002Fid_ed25519 or ~\u002F.ssh\u002Fid_ecdsa uploaded to GitHub, you're done!\n# SAFE CLI auto-discovers SSH keys - no key generation needed\n\n# Option 2: Generate new SSH key and upload to GitHub\nssh-keygen -t ed25519 -f ~\u002F.ssh\u002Fid_ed25519 -N \"\" -C \"safe-agent-key\"\ngh ssh-key add ~\u002F.ssh\u002Fid_ed25519.pub --title \"SAFE Agent Key\"\n# Done! SAFE CLI will auto-discover this key\n\n# Option 3: Generate SAFE-native keys (for advanced use cases)\nsafe keygen x25519 -o agent-id\n# Upload agent-id.x25519.pub to https:\u002F\u002Fgithub.com\u002Fsettings\u002Fkeys (manual conversion needed)\nmv agent-id.x25519.key ~\u002F.safe\u002Fkeys\u002F\n\n# Test encryption to self (works with any option above)\nsafe encrypt -i test.txt -o test.safe -r github:your-username\nsafe decrypt -i test.safe -o decrypted.txt\n# With SSH keys, decryption auto-discovers your keys from ~\u002F.ssh\u002F\n```\n\n**Browser-Based Agent Workflow:**\n\nAgents using thesafe.dev have full GitHub support for both encryption and decryption.\n\n**Encrypt to a GitHub user (browser):**\n\n1. Go to the **ENCRYPT** tab\n2. Enter your message\n3. Click **ADD FACTOR** → **NEW FACTOR** → select **GITHUB**\n4. Enter the GitHub username (e.g., `smithclay`)\n5. Click **FETCH KEYS** — the browser fetches public keys from `https:\u002F\u002Fgithub.com\u002F{username}.keys`\n6. Click **ENCRYPT**\n7. Copy the output and share via Gist\n\n**Decrypt a GitHub-encrypted message (browser):**\n\n1. Go to the **DECRYPT** tab\n2. Load the encrypted message: paste text, use the **FILE** button to upload, or use the **URL** button to load directly from a Gist URL (e.g., paste the raw Gist URL)\n3. Click **ADD** → **GITHUB** → enter your GitHub username → click **FETCH KEYS**\n   (This matches your public keys to the message's LOCK blocks)\n4. Click **ADD** → **KEY** → paste your SSH private key (from `~\u002F.ssh\u002Fid_ed25519` or `~\u002F.ssh\u002Fid_ecdsa`)\n   — or use the **\"Import SSH private key from GitHub\"** button if available\n5. Click **DECRYPT**\n\n**Recommended approach for browser-based workflows:**\n- **Both CLI and browser support `github:username`** for encryption equally well\n- **CLI is simpler for decryption** — it auto-discovers SSH keys from `~\u002F.ssh\u002F`; browser requires pasting the private key once\n- **URL button is convenient** — load encrypted Gist content directly without curl\n\n**Send encrypted output over WebRTC (browser):**\n\nThe browser supports real-time peer-to-peer transfer of encrypted SAFE messages via WebRTC — no copy-paste required:\n\n**Sender:**\n1. Encrypt your message as usual to produce the encrypted output\n2. Click **Send** in the output toolbar (next to Download, Share, Copy)\n3. A dialog appears: \"Share join URL, then wait for receiver...\"\n4. The join URL is offered via the native OS share sheet (if available) or logged in the **Log** panel\n5. Keep the tab open — when the receiver connects, the dialog updates to \"Receiver connected. Starting transfer...\"\n6. Transfer completes automatically\n\n**Receiver:**\n1. Open the join URL: `https:\u002F\u002Fthesafe.dev\u002F?session=\u003Cid>&token=\u003Ctoken>`\n2. The page auto-connects, receives the encrypted message, and switches to the **Decrypt** tab with the message pre-loaded\n3. Add credentials and click **Decrypt** as normal\n\n**Notes:**\n- Join URLs expire after **30 minutes**\n- Max transfer size: 100 MB\n- Sender must keep the tab open until the receiver connects\n- **Share** (separate button) shares the file or text directly with no server involved; **Send** is the WebRTC real-time peer flow\n\n**Agent Ping\u002FNotification Workflow:**\n\nYou can \"ping\" another agent using their GitHub username without needing their public key in advance:\n\n```bash\n# Alice pings Bob (discovers keys automatically via github:username)\necho \"PING: Status update requested\" > ping.txt\nsafe encrypt -i ping.txt -o ping.safe -r github:bob\ngh gist create ping.safe --desc \"Ping from Alice\" --public\n\n# Bob discovers the ping and decrypts (SSH key auto-discovery!)\ncurl -sL https:\u002F\u002Fgist.github.com\u002Falice\u002F{gist-id}\u002Fraw | safe decrypt\n# safe: using SSH key ~\u002F.ssh\u002Fid_ed25519\n# safe: trying 1 key(s) (0 native + 1 SSH)\n# PING: Status update requested\n\n# Bob responds back to Alice\necho \"PONG: Status OK, task 75% complete\" > pong.txt\nsafe encrypt -i pong.txt -o pong.safe -r github:alice\ngh gist create pong.safe --desc \"Response to Alice\" --public\n```\n\n**Key Benefits:**\n- ✅ No prior key exchange needed - `github:username` fetches public keys automatically\n- ✅ No key management needed - reuse existing SSH keys from GitHub\n- ✅ Works instantly if you already have SSH keys on GitHub\n- ✅ Works for any GitHub user with public SSH keys on their profile\n- ✅ Both agents can initiate communication\n- ✅ Asynchronous - sender doesn't need to wait for response\n- ✅ Persistent - messages remain in Gist until deleted\n\n**Discovery Methods:**\n- GitHub Gist notifications (if agent watches their own Gists)\n- Periodic polling of GitHub API for new Gists mentioning their username\n- GitHub webhooks for real-time notifications\n- RSS feeds for public Gists\n\n**Security Notes:**\n- Gist URLs are discoverable if public - use private Gists for sensitive coordination\n- Encrypted content is safe even if Gist is public (only recipient has private key)\n- Gist history is immutable - deleted messages remain in Git history\n- Use short-lived Gists and delete after confirmation for ephemeral communication\n- Multi-recipient encryption prevents sender from knowing who decrypted the message\n\n---\n\n### CLI vs Browser: Feature Comparison\n\n| Feature | CLI (SAFE v2.3+) | Browser (thesafe.dev) |\n|---------|------------------|------------------------|\n| `github:username` encryption | ✅ Yes | ✅ Yes |\n| `github:username` decryption | ✅ Auto (SSH key auto-discovery) | ✅ Yes (paste SSH key once) |\n| SSH key auto-discovery | ✅ Yes (`~\u002F.ssh\u002F`) | ❌ No (manual paste) |\n| Ed25519 SSH keys | ✅ Auto-converts to X25519 | ✅ Manual paste |\n| P-256 ECDSA SSH keys | ✅ Direct support | ✅ Manual paste |\n| SAFE native keys | ✅ Yes (`~\u002F.safe\u002Fkeys\u002F`) | ✅ Yes (import\u002Fexport) |\n| Load from URL (e.g. Gist) | ✅ `curl \u003Curl> \\| safe decrypt` | ✅ URL button in DECRYPT tab |\n| Real-time peer transfer | ❌ No | ✅ Send button (WebRTC, 30-min join URL) |\n| Zero-setup decryption | ✅ If SSH keys on GitHub | ⚠️ Must paste private key once |\n\n**Recommendation:**\n- **Encryption:** Both CLI and browser support `github:username` equally well\n- **Decryption:** CLI is easier (auto-discovers SSH keys); browser requires pasting your private key\n- **Best of both:** Use browser for encryption, CLI for decryption when available\n\n---\n\n**Keychain management:**\n\nThe Keychain section (04) supports:\n- **Add Credential** (dropdown menu with options):\n  - **Import Key**: Import an existing public or private key (PEM or base64)\n  - **New Passkey**: Create a new WebAuthn passkey (requires browser\u002FOS authenticator, prompts for label)\n  - **New Password**: Add a new password for encryption\u002Fdecryption\n  - **Existing Passkey**: Use an existing passkey from your authenticator\n- **Export**: Export keychain as encrypted SAFE backup (password-protected `.safe` file containing private keys in PEM format)\n- **Import**: Import a previously exported keychain backup (file upload + passphrase)\n- **Clear All**: Delete all keychain entries (shows a confirm dialog)\n\n**Passkey Limitations for Automation:**\n- Passkey creation requires WebAuthn hardware interaction (biometric, security key, etc.)\n- Cannot be fully automated - requires user interaction with authenticator\n- Dialog prompts for \"Passkey label\" before creation\n- Best suited for interactive sessions, not headless automation\n\nGenerated keys are automatically saved here. Each key shows its type and Key ID hints, with Enc\u002FDec\u002FShare\u002FPUB\u002FPRIV\u002FLabel\u002FDel action buttons.\n\n**Export\u002FImport workflow (for persisting keys across sessions):**\n\nExport:\n1. Click \"Export credentials as encrypted backup\" → dialog appears\n2. Enter passphrase + confirm passphrase → click OK\n3. Downloads `safe-credentials-backup.safe` (a standard SAFE file, pwd-encrypted)\n4. The export contains private keys only (PEM format). Public keys are derived on re-import.\n\nImport:\n1. Click \"Import\" → file chooser appears (use `browser_file_upload` with MCP)\n2. Select the `.safe` backup file → passphrase dialog appears\n3. Enter passphrase → click OK\n4. Keys are restored with full functionality (Enc\u002FDec\u002FPUB\u002FPRIV buttons)\n5. Duplicates are automatically skipped\n\nThe exported `.safe` file is CLI-compatible: `safe decrypt safe-credentials-backup.safe -p \"passphrase\"` reveals the PEM keys.\n\n### Agent Session Persistence (Browser Workflow)\n\nAgents can maintain a persistent identity across browser sessions by saving and re-uploading the keychain backup:\n\n**First browser session**:\n1. Navigate to https:\u002F\u002Fthesafe.dev\n2. Generate keys (Section 01) or receive keys from other agents\n3. Export keychain: Click \"Export\" → enter passphrase → download `safe-credentials-backup.safe`\n4. Save the encrypted backup file to persistent storage (filesystem, database, cloud storage, etc.)\n5. Store the passphrase securely (environment variable, secure key store, etc.)\n\n**New browser session** (different browser, incognito, new tab, etc.):\n1. Navigate to https:\u002F\u002Fthesafe.dev\n2. Import keychain: Click \"Import\" → upload `safe-credentials-backup.safe` → enter passphrase\n3. All keys are restored with full functionality (Enc\u002FDec\u002FPUB\u002FPRIV\u002FShare\u002FLabel\u002FDel)\n4. Agent can immediately encrypt\u002Fdecrypt using saved keys\n\n**Benefits**:\n- Agents maintain the same cryptographic identity across sessions\n- No need to regenerate keys or re-exchange public keys with other agents\n- Encrypted communication history remains accessible\n- Works across different browsers, devices, and environments\n\n**Security notes**:\n- The backup file is encrypted with the passphrase (argon2id by default)\n- File is CLI-compatible: `safe decrypt safe-credentials-backup.safe -p \"passphrase\"`\n- Store the passphrase separately from the backup file\n- Backup contains only private keys in PEM format; public keys are derived on import\n\n**Example workflow with MCP Playwright**:\n\n```python\n# First session: Export keychain\nbrowser_click(ref=\u003Cexport-button-ref>)  # \"Export keychain\"\n# Enter passphrase in dialog\nbrowser_type(ref=\u003Cpassphrase-ref>, text=\"agent-secret-passphrase\")\nbrowser_type(ref=\u003Cconfirm-passphrase-ref>, text=\"agent-secret-passphrase\")\nbrowser_click(ref=\u003Cok-ref>)\n# File downloads as safe-credentials-backup.safe\n# Save this file to persistent storage\n\n# New session: Import keychain\nbrowser_navigate(url=\"https:\u002F\u002Fthesafe.dev\")\nbrowser_click(ref=\u003Cimport-button-ref>)  # \"Import keychain backup\"\nbrowser_file_upload(paths=[\"\u002Fpath\u002Fto\u002Fsafe-credentials-backup.safe\"])\n# Enter passphrase in dialog\nbrowser_type(ref=\u003Cpassphrase-ref>, text=\"agent-secret-passphrase\")\nbrowser_click(ref=\u003Cok-ref>)\n# All keys restored, agent can now encrypt\u002Fdecrypt\n```\n\nThis enables agents to maintain cryptographic identities across:\n- Browser restarts\n- Incognito\u002Fprivate browsing sessions\n- Different physical machines\n- Cloud-based agent deployments\n\n**When to use the web interface:**\n- CLI can't be installed (no Go\u002FRust, restricted environment, sandboxed IDE)\n- No shell access (browser-only agent, web-based coding environment)\n- One-off encryption\u002Fdecryption tasks\n- Testing SAFE format without installing dependencies\n- Quick key generation or format exploration\n\n**When to prefer the CLI:**\n- Production systems or automated pipelines\n- Batch or high-volume operations (CLI is significantly faster)\n- Air-gapped or offline environments\n- Scripting with shell pipes and file I\u002FO\n\n## Quick Reference\n\n### Key Storage Convention\n\nPersonal keys are stored in `~\u002F.safe\u002F` (similar to `~\u002F.ssh\u002F`). The CLI manages this directory automatically:\n\n```bash\nsafe keygen x25519                     # Generates keypair, auto-stores to ~\u002F.safe\u002F\nsafe keygen x25519 -n alice            # Named identity \"alice\"\nsafe keys                              # List all identities and recipients\n```\n\n**Key Discovery Order (SAFE CLI v2.3+):**\n1. `~\u002F.safe\u002Fkeys\u002F*.key` - SAFE-native keys (checked first)\n2. `~\u002F.ssh\u002F*` - All SSH private keys in `~\u002F.ssh\u002F` directory\n   - Ed25519 keys → auto-converted to X25519\n   - P-256 ECDSA keys → used directly\n\n**Note:** You can use EITHER format - SSH keys from GitHub work with zero configuration!\n\nDirectory structure (auto-created by `safe keygen`):\n- `~\u002F.safe\u002Fkeys\u002F` — Private keys (0700, never share). E.g., `nick.x25519.key`\n- `~\u002F.safe\u002F*.pub` — Your own public keys (safe to share). E.g., `nick.x25519.pub`\n- `~\u002F.safe\u002Frecipients\u002F` — Other people's public keys (managed by `safe keys add`)\n\nOverride with `SAFE_HOME` env var. Fallback: `.\u002F.safe\u002F` in current directory.\n\n### Generate Keys\n\n| Key Type | Command | Use Case |\n|----------|---------|----------|\n| x25519 | `safe keygen x25519` | Fast, default, widely supported |\n| p-256 | `safe keygen p-256` | FIPS compliance |\n| ml-kem-768 | `safe keygen ml-kem-768` | Post-quantum security (seed by default) |\n\nBy default, keygen uses `$USER` as the identity name and stores keys in `~\u002F.safe\u002F`. Override with `-n name` or `-o path`.\n\n```bash\nsafe keygen x25519                     # ~\u002F.safe\u002Fkeys\u002F$USER.x25519.key + ~\u002F.safe\u002F$USER.x25519.pub\nsafe keygen x25519 -n alice            # ~\u002F.safe\u002Fkeys\u002Falice.x25519.key + ~\u002F.safe\u002Falice.x25519.pub\nsafe keygen ml-kem-768                 # Generates seed (compact format, default for ML-KEM)\nsafe keygen ml-kem-768 -no-seed        # Raw keypair instead of seed\nsafe keygen x25519 -o \u002Ftmp\u002Fthrowaway   # Custom output path\nsafe keygen x25519 -force              # Overwrite existing files\n```\n\nOutput: `\u003Cname>.\u003Ctype>.pub` (share this) and `\u003Cname>.\u003Ctype>.key` (keep secret). Public key is always written to `~\u002F.safe\u002F`.\n\n### Manage Keys\n\n```bash\n# List all identities and known recipients\nsafe keys\n\n# Import a recipient's public key\nsafe keys add alice.x25519.pub --name alice\n\n# Remove a recipient\nsafe keys remove alice\n\n# Derive public key from private key (by name or path)\nsafe pubkey alice                       # Looks up ~\u002F.safe\u002Fkeys\u002Falice.*.key\nsafe pubkey \u002Fpath\u002Fto\u002Fkey.key            # Direct file path\n\n# View key details\nsafe keyinfo alice.x25519.pub\n```\n\nBare names work as recipients after import: `safe encrypt data.txt -r alice` resolves from `~\u002F.safe\u002Frecipients\u002F`. Also resolves system users: `-r bob` checks `~bob\u002F.safe\u002F*.pub`.\n\n### Encrypt\n\nstdin is the default input, stdout is the default output. Positional argument sets input file.\n\n```bash\n# Password-protect a file\nsafe encrypt secrets.txt -o secrets.safe -p \"strong-password\"\n\n# Encrypt to recipient (bare name or key file)\nsafe encrypt file.txt -o file.safe -r alice\n\n# Multiple recipients (OR - any one can decrypt)\nsafe encrypt file.txt -o file.safe -r alice -r bob\n\n# Two-factor: password AND key required (+ is AND separator)\nsafe encrypt file.txt -o file.safe -r \"pwd:secret + alice.pub\"\n\n# Pipe from stdin (default)\necho \"secret\" | safe encrypt -p \"pw\" > msg.safe\n\n# Password from environment variable\nsafe encrypt file.txt -o file.safe -p env:MY_PASSWORD\n\n# PBKDF2 instead of argon2id\nsafe encrypt file.txt -o file.safe -p \"pw\" --kdf pbkdf2\n```\n\n### Decrypt\n\nstdin is the default input, stdout is the default output. If no credentials are provided, keys from `~\u002F.safe\u002Fkeys\u002F` are tried automatically.\n\n```bash\n# With password\nsafe decrypt file.safe -p \"password\"\n\n# With private key\nsafe decrypt file.safe -k alice.x25519.key\n\n# Auto-discover keys (no -k needed if keys are in ~\u002F.safe\u002Fkeys\u002F)\nsafe decrypt file.safe\n\n# age-compatible --identity flag\nsafe decrypt file.safe --identity alice.key\n\n# Two-factor (all credentials required)\nsafe decrypt file.safe -o file.txt -p \"secret\" -k alice.key\n\n# Write to file instead of stdout\nsafe decrypt file.safe -o plaintext.txt -p \"password\"\n\n# Password from environment variable\nsafe decrypt file.safe -p env:MY_PASSWORD\n```\n\n### Info\n\nInspect a SAFE file's metadata without credentials:\n\n```bash\nsafe info file.safe\n# Output:\n#   AEAD: aes-256-gcm\n#   Block Size: 65536\n#   Key Hash: spki-sha256-16\n#   Data size: 1048 bytes\n#   UNLOCK Blocks: 2\n#     [0] pwd(argon2id)\n#     [1] hpke(kem=x25519, id=r3YlsKxQHj1q1d\u002FkKi5e3Q==)\n\n# From stdin\ncat file.safe | safe info\n```\n\n### Piping (stdin\u002Fstdout)\n\nstdin and stdout are the defaults — no `-i -` or `-o -` needed. All operations are binary-safe.\n\n**Default behavior:** Always prefer piping over writing intermediate files to disk. This avoids leaving decrypted content on disk and is cleaner.\n\n```bash\n# Decrypt base64-encoded content (PREFERRED - no temp file)\necho \"LS0tLS1CRUdJTi...\" | base64 -d | safe decrypt -k ~\u002F.safe\u002Fkeys\u002Fid.x25519.key\n\n# AVOID: Writing intermediate files\n# echo \"LS0tLS1CRUdJTi...\" | base64 -d > \u002Ftmp\u002Ffile.safe && safe decrypt \u002Ftmp\u002Ffile.safe ...\n\n# Basic stdin\u002Fstdout\necho \"secret\" | safe encrypt -p \"pw\" > encrypted.safe\ncat encrypted.safe | safe decrypt -p \"pw\"\n\n# Chain operations (re-encrypt with different key)\nsafe decrypt a.safe -p \"pw1\" | safe encrypt -o b.safe -p \"pw2\"\n\n# Encrypt with compression\ntar cz src\u002F | safe encrypt -o backup.safe -r alice\n\n# Decrypt and decompress\nsafe decrypt backup.safe -k team.key | tar xz\n\n# Decrypt remote file\ncurl -s https:\u002F\u002Fexample.com\u002Fdata.safe | safe decrypt -k my.key\n\n# Pipe through compression then encrypt\nsafe encrypt -p \"pw\" \u003C large.bin | gzip > encrypted.safe.gz\n\n# Decrypt gzipped safe file\ngunzip -c encrypted.safe.gz | safe decrypt -p \"pw\" > large.bin\n```\n\n**Note:** `-i -` and `-o -` still work for explicit stdin\u002Fstdout but are no longer required.\n\n## Common Use Cases\n\n### Protect API Keys \u002F .env Files\n\n```bash\nsafe encrypt .env -o .env.safe -p \"dev-password\"\nsafe encrypt credentials.json -o credentials.safe -r ops-team\n```\n\n### Share Secrets with a Teammate\n\n```bash\n# They generate their key\nsafe keygen x25519 -n teammate\n\n# You import their public key\nsafe keys add teammate.x25519.pub --name teammate\n\n# You encrypt for them (bare name!)\nsafe encrypt api-keys.txt -o api-keys.safe -r teammate\n\n# They decrypt (auto-discovers keys from ~\u002F.safe\u002Fkeys\u002F)\nsafe decrypt api-keys.safe -o api-keys.txt\n```\n\n### Encrypt Backup Before Cloud Upload\n\n```bash\ntar czf backup.tar.gz ~\u002FDocuments\nsafe encrypt backup.tar.gz -o backup.safe -p \"backup-phrase\" -r recovery\n# Upload backup.safe to S3\u002FGCS\u002FDropbox\n```\n\n### Encrypt Entire Directories\n\n```bash\n# Encrypt a folder\ntar cz project\u002F | safe encrypt -o project.safe -r team\n\n# Decrypt and extract\nsafe decrypt project.safe -k team.key | tar xz\n```\n\n### Git-Friendly Encrypted Secrets\n\n```bash\n# Encrypt secrets, commit the .safe file\nsafe encrypt .env.production -o .env.production.safe -r deploy\ngit add .env.production.safe  # Safe to commit\n\n# On deploy server (auto-discovers deploy key from ~\u002F.safe\u002Fkeys\u002F)\nsafe decrypt .env.production.safe -o .env.production\n```\n\n### Separation of Duties (Two People Required)\n\n```bash\n# Encrypt requiring BOTH Alice and Bob (+ is AND)\nsafe encrypt codes.txt -o codes.safe -r \"alice.pub + bob.pub\"\n\n# Decrypt (both must provide keys)\nsafe decrypt codes.safe -o codes.txt -k alice.key -k bob.key\n```\n\n### Two-Factor Encryption (Password + Key)\n\n```bash\n# Encrypt: requires password AND key\nsafe encrypt secrets.txt -o secrets.safe -r \"pwd:mypassword + hardware.pub\"\n\n# Decrypt: must provide both\nsafe decrypt secrets.safe -o secrets.txt -p \"mypassword\" -k hardware.key\n```\n\n### Team Encryption + Emergency Backup\n\n```bash\nsafe encrypt secrets.txt -o secrets.safe \\\n  -r alice -r bob -r carol \\\n  -p \"emergency-recovery-phrase\"\n```\n\n### Post-Quantum Hybrid Protection\n\n```bash\n# Generate both classical and PQ keys\nsafe keygen x25519 -n alice\nsafe keygen ml-kem-768 -n alice\n\n# Encrypt with both (future-proof against quantum computers)\nsafe encrypt data.txt -o data.safe \\\n  -r \"pwd:phrase + alice.x25519.pub + alice.ml-kem-768.pub\"\n```\n\n### Temporary Decryption (No File on Disk)\n\n```bash\n# Use decrypted content without writing to disk\n.\u002Fmy-app --config \u003C(safe decrypt config.safe -p \"pw\")\n\n# Compare two encrypted files\ndiff \u003C(safe decrypt old.safe -p pw) \u003C(safe decrypt new.safe -p pw)\n```\n\n### Password Rotation\n\n```bash\n# Change password without re-encrypting data\nsafe unlock replace secrets.safe -p \"old-password\" \\\n  --index 0 --recipient \"pwd:new-password\"\n```\n\n### Key Rotation (Compromised Key)\n\n```bash\n# View current recipients\nsafe info secrets.safe\n\n# Remove compromised key, add new one\nsafe unlock remove secrets.safe -k admin.key --index 2\nsafe unlock add secrets.safe -k admin.key --recipient new-employee.pub\n```\n\n## Composable Paths (AND vs OR Logic)\n\n| Encrypt With | Decrypt Requires | Logic |\n|--------------|------------------|-------|\n| `-r alice -r bob` | `-k alice.key` OR `-k bob.key` | OR |\n| `-r \"alice.pub + bob.pub\"` | `-k alice.key` AND `-k bob.key` | AND |\n| `-r \"pwd:x + alice.pub\"` | `-p x` AND `-k alice.key` | AND |\n| `-p backup -r alice` | `-p backup` OR `-k alice.key` | OR |\n\nMultiple `-r` or `-p` flags = OR (any one works)\n`+` within one `-r` = AND (all required)\n\n**Note:** `->` is deprecated but still works. Use `+` for new code.\n\n## Editing Encrypted Files\n\nSAFE supports random-access editing without full re-encryption. Only modified chunks are re-encrypted - unchanged chunks are copied byte-for-byte.\n\n### Data Input Options\n\n| Option | Use | Example |\n|--------|-----|---------|\n| `--data \"string\"` | Literal text on command line | `--data \"hello\"` |\n| `--data-file path` | Read content from a file | `--data-file patch.bin` |\n\n### Read Bytes at Offset\n\nRead a portion of an encrypted file without decrypting the whole thing:\n\n```bash\n# Read first 100 bytes\nsafe read file.safe -p \"pw\" --offset 0 --length 100\n\n# Read bytes 500-600 to a file\nsafe read file.safe -o excerpt.txt -k key.key --offset 500 --length 100\n\n# Shorthand with -n for offset\nsafe read file.safe -p \"pw\" -n 1024 --length 256\n\n# age-compatible --identity flag\nsafe read file.safe --identity key.key -n 0 --length 100\n```\n\n### Write Bytes at Offset (In-Place Edit)\n\nModify bytes at a specific position. In-place by default (no `-o` needed):\n\n```bash\n# Overwrite bytes starting at offset 10\nsafe write file.safe -p \"pw\" -n 10 --data \"new content\"\n\n# Replace header from a file\nsafe write config.safe -p \"pw\" -n 0 --data-file header.bin\n\n# With --identity flag\nsafe write file.safe --identity key.key -n 0 --data \"UPDATED\"\n```\n\n**Note:** Write only supports in-place modification. Output defaults to overwriting the input file.\n\n### Append Data\n\nAdd data to the end of an encrypted file (in-place by default):\n\n```bash\n# Append log entry\nsafe append log.safe -p \"pw\" --data \"$(date): Event occurred\\n\"\n\n# Append from file\nsafe append data.safe -k key.key --data-file new-records.csv\n\n# Append binary data\nsafe append archive.safe -p \"pw\" --data-file chunk.bin\n```\n\n### In-Place Editing Workflow\n\n```bash\n# 1. Check current content\nsafe read config.safe -p \"pw\" -n 0 --length 50\n\n# 2. Make targeted edit\nsafe write config.safe -p \"pw\" -n 25 --data \"new_value\"\n\n# 3. Verify the change\nsafe read config.safe -p \"pw\" -n 0 --length 50\n```\n\n## Managing Recipients (UNLOCK Blocks)\n\nModify who can decrypt without re-encrypting the data. These operations only change the UNLOCK blocks — the encrypted DATA remains identical.\n\n```bash\n# View current recipients and their indexes\nsafe info file.safe\n# Shows: [0] pwd(argon2id)\n#        [1] hpke(kem=x25519, id=ABC123...)\n\n# Add new recipient (in-place by default)\nsafe unlock add file.safe -p \"current-pw\" -r alice.pub\nsafe unlock add file.safe -k admin.key -r \"pwd:backup-pass\"\n\n# Add composable recipient (password + key required)\nsafe unlock add file.safe -p \"pw\" -r \"pwd:secret + bob.pub\"\n\n# Remove recipient by index (in-place)\nsafe unlock remove file.safe -k admin.key --index 0\n\n# Replace recipient at index (in-place)\nsafe unlock replace file.safe -p \"old-pw\" --index 0 -r \"pwd:new-pw\"\n\n# Write to new file instead of in-place\nsafe unlock add file.safe -o new-file.safe -p \"pw\" -r alice.pub\n\n# With --identity flag\nsafe unlock add file.safe --identity admin.key -r bob.pub\n```\n\n**Note:** You cannot remove the last UNLOCK block — the file would become undecryptable.\n\n## Algorithm Options\n\n### AEAD (Content Encryption)\n\n| Algorithm | Flag | Use Case |\n|-----------|------|----------|\n| AES-256-GCM | `--aead aes-256-gcm` | Default, hardware accelerated |\n| ChaCha20-Poly1305 | `--aead chacha20-poly1305` | ARM, older CPUs without AES-NI |\n| AEGIS-256 | `--aead aegis-256` | **CLI only** - Key-committing, highest security. Not available in browser UI. |\n\n### Key Types\n\n| Type | Security | Size (pub\u002Fpriv) |\n|------|----------|-----------------|\n| x25519 | Classical, fast | 32B \u002F 32B |\n| p-256 | FIPS compliant | 65B \u002F 32B |\n| ml-kem-768 | Post-quantum | 1184B \u002F 2400B |\n\n### Key ID Modes\n\nControl how much key identity information is included in UNLOCK blocks:\n\n| Mode | Flag | Behavior |\n|------|------|----------|\n| Full | `--key-id-mode full` | Default. Full key ID included — recipients can check if a message is for them without attempting decryption |\n| Hint | `--key-id-mode hint` | 4-digit hint only — reduces metadata, recipients may need to try decryption |\n| Anonymous | `--key-id-mode anonymous` | No key ID — recipient must try all their keys. Maximum privacy |\n\n```bash\n# Encrypt with hint-only key ID\nsafe encrypt file.txt -o file.safe -r alice --key-id-mode hint\n\n# Encrypt with no key ID (anonymous recipient)\nsafe encrypt file.txt -o file.safe -r alice --key-id-mode anonymous\n```\n\nUse `hint` or `anonymous` when you want to hide *who* can decrypt a message. The encrypted data is identical — only the metadata changes.\n\n### Password KDF\n\n| Algorithm | Flag | Use Case |\n|-----------|------|----------|\n| Argon2id | `--kdf argon2id` | Default. Memory-hard, GPU-resistant (64 MiB, 2 iterations) |\n| PBKDF2 | `--kdf pbkdf2` | Constrained environments (600,000 iterations) |\n\n```bash\nsafe encrypt file.txt -o file.safe -p \"pw\" --kdf pbkdf2\n```\n\n### Key Hash Algorithm\n\n| Algorithm | Flag | Use Case |\n|-----------|------|----------|\n| SPKI-SHA256-16 | `--key-hash spki-sha256-16` | Default. 16-byte truncated SHA-256 |\n| SPKI-TurboSHAKE256 | `--key-hash spki-turboshake256` | Alternative hash function |\n\n```bash\nsafe encrypt file.txt -o file.safe -r alice --key-hash spki-turboshake256\n```\n\n## Migration from GPG\u002FPGP\n\n```bash\n# Decrypt old GPG file, re-encrypt with SAFE\ngpg -d old-secrets.gpg | safe encrypt -o secrets.safe -r newkey\n```\n\n## Edge Cases & Tips\n\n**Empty files:** Encrypting empty files works correctly and produces valid .safe output.\n\n**Binary data:** SAFE handles all byte values (0x00-0xFF) correctly. No text encoding issues.\n\n**Unicode passwords:** Passwords are UTF-8 encoded. Multi-byte characters work correctly.\n\n**Large files:** Files are encrypted in 64KB chunks by default. Only modified chunks are re-encrypted during edits.\n\n**Block size options:** Use `--block-size` flag (16384, 32768, or 65536 bytes) to tune for your use case.\n\n## Troubleshooting\n\n**Decryption fails:**\n1. Check password\u002Fkey is correct\n2. For composable paths, ALL credentials must be provided (partial won't work)\n3. Verify file integrity: `safe info file.safe`\n4. Wrong key type? Check with `safe keyinfo mykey.key`\n5. Check available keys: `safe keys`\n\n**\"safe: command not found\":**\nRun installation steps above. Verify with `which safe`.\n\n**Composable path errors:**\n- `pwd:secret + alice.pub` requires BOTH `-p secret` AND `-k alice.key` to decrypt\n- Providing only the password or only the key will fail\n- Order of `-k` flags doesn't matter, but all must be present\n\n## Security Notes\n\n- `.key` files are secret — never share them\n- `.pub` files are safe to distribute\n- Composable paths (`+`) provide defense-in-depth\n- ML-KEM-768 protects against future quantum computers\n- Argon2id password hashing is memory-hard and GPU-resistant (64 MiB memory, 2 iterations)\n\n### Password Security\n\n**Warning:** Passwords passed via `-p` are visible in shell history and process listings.\n\nMitigations:\n```bash\n# 1. Prefix with space to skip history (bash\u002Fzsh with HISTCONTROL=ignorespace)\n safe encrypt file.txt -o file.safe -p \"secret\"\n\n# 2. Use a key file instead of password\nsafe encrypt file.txt -o file.safe -r alice\n\n# 3. Read password from environment variable (RECOMMENDED for automation)\nMY_PW=\"secret\" safe encrypt file.txt -o file.safe -p env:MY_PW\n\n# 4. Use SAFE_PASSPHRASE env var with bare -p\nexport SAFE_PASSPHRASE=\"secret\"\nsafe encrypt file.txt -o file.safe -p\n\n# 5. Read password from file (careful with permissions)\nsafe encrypt file.txt -o file.safe -p \"$(cat ~\u002F.safe\u002F.password)\"\n\n# 6. Clear history after use\nhistory -d $(history 1 | awk '{print $1}')\n```\n\n**`env:VARNAME` security:** Environment variables are visible to the current process and child processes. They're safer than command-line args (not in `\u002Fproc\u002F*\u002Fcmdline`) but still visible via `\u002Fproc\u002F*\u002Fenviron` on Linux. For maximum security, use key-based encryption.\n\n## Agent-to-Agent Encrypted Communication\n\nAgents can exchange encrypted messages across any text-based channel: email, forums, GitHub issues, Slack, shared files, etc.\n\nThe key management system makes agent-to-agent communication simple:\n- **`safe keygen`** — generates identity keys (auto-stored in `~\u002F.safe\u002F`)\n- **`safe keys add`** — imports other agents' public keys as named recipients\n- **`safe encrypt -r name`** — encrypts to any known recipient by name\n- **`safe decrypt`** — auto-discovers keys, no `-k` flag needed\n\n### First-Run Setup\n\nOn first use, check for existing keys and generate if missing:\n\n```bash\n# Check if any agent identities exist\nsafe keys 2>\u002Fdev\u002Fnull || true\n\n# Generate if missing\nif [ ! -f ~\u002F.safe\u002Fkeys\u002F*.key ]; then\n    safe keygen x25519\n    echo \"Generated new agent identity\"\n    safe keys\nfi\n```\n\nThis creates:\n- `~\u002F.safe\u002Fkeys\u002F$USER.x25519.key` — your private key (never share)\n- `~\u002F.safe\u002F$USER.x25519.pub` — your public key (share freely)\n\n### Exchanging Keys Between Agents\n\nAgents discover each other by sharing public keys. The `safe keys add` command imports keys into the recipients directory:\n\n```bash\n# Agent A: Share your public key\ncat ~\u002F.safe\u002F$USER.x25519.pub\n# Copy this to the other agent (paste, file, AGENTS.md, etc.)\n\n# Agent B: Import Agent A's public key\nsafe keys add \u002Fpath\u002Fto\u002Fagent-a.x25519.pub --name agent-a\n\n# Verify import\nsafe keys\n# Shows:\n#   Identities:\n#     nick         x25519         \u002FUsers\u002Fnick\u002F.safe\u002Fkeys\u002Fnick.x25519.key\n#   Recipients:\n#     agent-a      x25519         \u002FUsers\u002Fnick\u002F.safe\u002Frecipients\u002Fagent-a.x25519.pub\n\n# Now Agent B can encrypt to Agent A by name\nsafe encrypt message.txt -o message.safe -r agent-a\n```\n\n**Advertising your keys directory:** Agents should make their `~\u002F.safe\u002F*.pub` files discoverable. Common approaches:\n\n| Location | How |\n|----------|-----|\n| `AGENTS.md` in repo | Include PEM block in markdown |\n| `~\u002F.safe\u002F*.pub` files | Other agents on same system: `-r username` resolves `~username\u002F.safe\u002F*.pub` |\n| GitHub gist | Post PEM key, recipient imports with `curl \\| safe keys add` |\n| Forum\u002Femail signature | Include PEM block or link to public key |\n\n### Convention: Reply-To Keys\n\nTo enable replies, prepend your public key(s) to the message before encrypting:\n\n```\n-----BEGIN X25519 PUBLIC KEY-----\nfBhEEEB+CepxNQIfPtxnIhWbDUyo+Z\u002FW17cYKlCbsDg=\n-----END X25519 PUBLIC KEY-----\n\nHere is the secret data you requested...\n```\n\nWhen an agent decrypts a message and finds PEM public key blocks at the top, it saves them with `safe keys add` and encrypts the reply to that name.\n\n**Multiple reply-to keys:** If the sender wants multiple agents\u002Fidentities to decrypt the reply:\n\n```\n-----BEGIN X25519 PUBLIC KEY-----\nfBhEEEB+CepxNQIfPtxnIhWbDUyo+Z\u002FW17cYKlCbsDg=\n-----END X25519 PUBLIC KEY-----\n-----BEGIN ML-KEM-768 PUBLIC KEY-----\n\u003Cbase64...>\n-----END ML-KEM-768 PUBLIC KEY-----\n\nMessage body here...\n```\n\nThe receiving agent extracts all key blocks, imports them with `safe keys add`, and encrypts the reply to all of them.\n\n### Workflow: Send a Message\n\n```bash\n# 1. Create message with your public key as reply address\nsafe pubkey $USER > message.txt\necho \"\" >> message.txt\necho \"Here are the API credentials you requested...\" >> message.txt\n\n# 2. Encrypt to recipient (bare name from recipients dir)\nsafe encrypt message.txt -o message.safe -r recipient\n\n# 3. Share message.safe via any channel (email, forum, git, shared folder, etc.)\n```\n\n### Checking if a Message is For You\n\nBefore attempting to decrypt, check if your key ID matches any unlock block:\n\n```bash\n# Get Key IDs from the encrypted file\nsafe info message.safe\n# Output includes:\n#   UNLOCK Blocks: 2\n#   [0] hpke(kem=x25519, id=1SB5W2LJ8\u002FDNu8rn+vaGHA==)\n#   [1] hpke(kem=ml-kem-768, id=abc123...)\n\n# Get your key info\nsafe keyinfo ~\u002F.safe\u002F$USER.x25519.pub\n\n# Or just try to decrypt — auto-key discovery handles it\nsafe decrypt message.safe -o message.txt\n```\n\n**Note on key ID modes:** If the sender used `--key-id-mode hint`, you'll see `hint=XXXX` instead of a full ID. If they used `--key-id-mode anonymous`, there will be no key ID at all — you'll need to try decrypting (auto-discovery handles this).\n\n### Workflow: Receive and Reply\n\n```bash\n# 1. Decrypt the message (auto-discovers keys from ~\u002F.safe\u002Fkeys\u002F)\nsafe decrypt message.safe -o message.txt\n\n# 2. Extract reply-to keys and import them\n# Save PEM blocks to a temp file, then import:\ngrep -A2 'BEGIN.*PUBLIC KEY' message.txt > \u002Ftmp\u002Fsender.pub\nsafe keys add \u002Ftmp\u002Fsender.pub --name sender\n\n# 3. Create and encrypt reply\nsafe pubkey $USER > reply.txt\necho \"\" >> reply.txt\necho \"Thanks, here's my response...\" >> reply.txt\n\n# Encrypt to sender (bare name!)\nsafe encrypt reply.txt -o reply.safe -r sender\n```\n\n### Publishing Your Public Key\n\nShare your public key so others can send you encrypted messages:\n\n| Location | Use Case |\n|----------|----------|\n| `AGENTS.md` in repo | Project-specific agent identity |\n| GitHub profile \u002F gist | Personal agent key |\n| Forum signature | Community communication |\n| Shared team folder | Internal team use |\n| Email signature | Email-based exchange |\n\nExample `AGENTS.md`:\n\n```markdown\n## Agent Keys\n\n### Deploy Agent\n\\`\\`\\`\n-----BEGIN X25519 PUBLIC KEY-----\nfBhEEEB+CepxNQIfPtxnIhWbDUyo+Z\u002FW17cYKlCbsDg=\n-----END X25519 PUBLIC KEY-----\n\\`\\`\\`\n\nTo send encrypted data to this agent:\n\\`\\`\\`bash\n# Import the key\nsafe keys add deploy-agent.pub --name deploy\n\n# Encrypt\nsafe encrypt data.txt -o data.safe -r deploy\n\\`\\`\\`\n```\n\n### Handling Multiple Identities\n\nAgents may have different keys for different contexts:\n\n```bash\nsafe keygen x25519 -n personal     # ~\u002F.safe\u002Fkeys\u002Fpersonal.x25519.key\nsafe keygen x25519 -n work         # ~\u002F.safe\u002Fkeys\u002Fwork.x25519.key\nsafe keygen ml-kem-768 -n pq       # ~\u002F.safe\u002Fkeys\u002Fpq.ml-kem-768.key\n\n# List all\nsafe keys\n```\n\nWhen sending, choose the appropriate reply-to key for the context. When receiving, auto-discovery tries all keys in `~\u002F.safe\u002Fkeys\u002F`.\n\n### Error Handling\n\nIf decryption fails even though key ID matched:\n1. The file may be corrupted — check with `safe info file.safe`\n2. For composable paths, ALL required credentials must be provided\n3. Report the error clearly; don't silently fail\n\n### Checking All Identities\n\nWith auto-key discovery, this is usually unnecessary. But for manual checking:\n\n```bash\n# List all your identities\nsafe keys\n\n# Check message recipients\nsafe info message.safe\n\n# Just try to decrypt — auto-discovers all keys\nsafe decrypt message.safe -o message.txt\n# If successful, prints: \"safe: trying N key(s) from ~\u002F.safe\u002Fkeys\"\n```\n\n### Auto-Generate AGENTS.md\n\nWhen setting up a project for agent communication, create an AGENTS.md:\n\n```bash\n# Generate AGENTS.md for current project\ncat > AGENTS.md \u003C\u003C 'EOF'\n# Agent Keys\n\nThis project supports encrypted agent-to-agent communication using [SAFE](https:\u002F\u002Fgithub.com\u002Fgrittygrease\u002Fsafe).\n\n## Available Agents\n\n### Primary Agent\nEOF\n\n# Add the public key\necho '```' >> AGENTS.md\nsafe pubkey $USER >> AGENTS.md\necho '```' >> AGENTS.md\n\ncat >> AGENTS.md \u003C\u003C 'EOF'\n\n## How to Send Encrypted Messages\n\n1. Save the public key block above to a file and import it:\n   ```bash\n   safe keys add agent.pub --name agent\n   ```\n2. Create your message with your reply-to key:\n   ```bash\n   safe pubkey $USER > message.txt\n   echo \"\" >> message.txt\n   echo \"Your message here...\" >> message.txt\n   ```\n3. Encrypt and send:\n   ```bash\n   safe encrypt message.txt -o message.safe -r agent\n   ```\n4. Share `message.safe` via any channel (email, issue, PR, pastebin, etc.)\n\n## Verifying Messages\n\n```bash\n# Check message recipients\nsafe info message.safe\n\n# Decrypt (auto-discovers keys from ~\u002F.safe\u002Fkeys\u002F)\nsafe decrypt message.safe -o message.txt\n```\nEOF\n\necho \"Created AGENTS.md with your public key\"\n```\n\n### Sharing via Pastebin\n\nFor quick, ephemeral encrypted message sharing:\n\n```bash\n# Encrypt and post to termbin\nsafe encrypt message.txt -r recipient | nc termbin.com 9999\n# Returns URL like: https:\u002F\u002Ftermbin.com\u002Fabc123\n\n# Recipient fetches and decrypts (auto-discovers keys)\ncurl -s https:\u002F\u002Ftermbin.com\u002Fabc123 | safe decrypt\n```\n\n### Posting a Public Message (Forum\u002FMailing List)\n\nWhen posting an encrypted message publicly, include your reply-to key AND instructions:\n\n```bash\n# Create a complete public post\ncat > post.txt \u003C\u003C 'EOF'\n## Encrypted Message\n\nTo decrypt this message and reply, install the safe-encryption skill:\n\n```\nmkdir -p ~\u002F.claude\u002Fskills\ngit clone https:\u002F\u002Fgithub.com\u002Fgrittygrease\u002Fsafe-encryption-skill.git ~\u002F.claude\u002Fskills\u002Fsafe-encryption\n```\n\nThen ask your agent: \"Decrypt the message below and reply encrypted to the sender\"\n\n### My Public Key (for replies)\nEOF\n\nsafe pubkey $USER >> post.txt\n\ncat >> post.txt \u003C\u003C 'EOF'\n\n### Encrypted Message\nEOF\n\n# Encrypt your message (with your reply-to key embedded in plaintext)\nsafe pubkey $USER > message.txt\necho \"\" >> message.txt\necho \"Your actual message content here...\" >> message.txt\n\nsafe encrypt message.txt -r recipient >> post.txt\n\necho \"\" >> post.txt\ncat >> post.txt \u003C\u003C 'EOF'\n\n---\n*This message was encrypted with [SAFE](https:\u002F\u002Fgithub.com\u002Fgrittygrease\u002Fsafe)*\nEOF\n\ncat post.txt\n```\n\nThis produces a self-contained post that any agent with the skill can decrypt and reply to.\n","# SAFE Encryption Tool\n\nSAFE is a modern encryption CLI with post-quantum support, multi-recipient encryption, and composable authentication.\n\n## Behavior Guidelines\n\nWhen this skill is loaded:\n1. Check if `safe` is installed (`which safe`). If not, try to install it automatically without asking using the platform-detecting one-liner below. If installation fails (restricted environment, no shell access), fall back to the web interface at [https:\u002F\u002Fthesafe.dev](https:\u002F\u002Fthesafe.dev) — see \"Browser-Based Alternative\" below.\n2. When the user asks to encrypt\u002Fdecrypt, just do it. Don't ask for confirmation.\n3. If a password is needed and not provided, use `-p` without a value (prompts interactively or reads `SAFE_PASSPHRASE` env var). In automation, use `-p env:VARNAME` to read from environment variables.\n4. If a key file is needed, run `safe keys` to check existing identities and recipients. If no key exists, run `safe keygen x25519` to generate one (auto-stores to `~\u002F.safe\u002F`).\n5. **Always use absolute paths** for key files and encrypted files to avoid working directory issues.\n6. **Always pipe instead of writing temp files.** When decrypting inline\u002Fembedded content (base64, pasted data), pipe directly: `echo \"...\" | base64 -d | safe decrypt -k key.key`. Never write intermediate `.safe` files to `\u002Ftmp` or elsewhere.\n7. **Bare name recipients work.** Use `-r alice` instead of `-r \u002Ffull\u002Fpath\u002Fto\u002Falice.x25519.pub` when the recipient is in `~\u002F.safe\u002Frecipients\u002F`.\n8. **Decrypt auto-discovers keys.** If no `-k` or `-p` is provided, `safe decrypt` automatically tries all keys in `~\u002F.safe\u002Fkeys\u002F`.\n\n## Installation\n\nDownload the prebuilt binary from [thesafe.dev\u002Fdownload](https:\u002F\u002Fthesafe.dev\u002Fdownload\u002F):\n\n**macOS Apple Silicon:**\n```bash\ncurl -sL https:\u002F\u002Fthesafe.dev\u002Fdownloads\u002Fsafe-darwin-arm64 -o safe && chmod +x safe && sudo mv safe \u002Fusr\u002Flocal\u002Fbin\u002F\n```\n\n**macOS Intel:**\n```bash\ncurl -sL https:\u002F\u002Fthesafe.dev\u002Fdownloads\u002Fsafe-darwin-amd64 -o safe && chmod +x safe && sudo mv safe \u002Fusr\u002Flocal\u002Fbin\u002F\n```\n\n**Linux x86_64:**\n```bash\ncurl -sL https:\u002F\u002Fthesafe.dev\u002Fdownloads\u002Fsafe-linux-amd64 -o safe && chmod +x safe && sudo mv safe \u002Fusr\u002Flocal\u002Fbin\u002F\n```\n\n**Linux ARM64:**\n```bash\ncurl -sL https:\u002F\u002Fthesafe.dev\u002Fdownloads\u002Fsafe-linux-arm64 -o safe && chmod +x safe && sudo mv safe \u002Fusr\u002Flocal\u002Fbin\u002F\n```\n\n**Auto-detect platform (one-liner):**\n```bash\nwhich safe || { OS=$(uname -s | tr '[:upper:]' '[:lower:]'); ARCH=$(uname -m); \\\n  [ \"$ARCH\" = \"arm64\" ] || [ \"$ARCH\" = \"aarch64\" ] && ARCH=arm64 || ARCH=amd64; \\\n  curl -sL \"https:\u002F\u002Fthesafe.dev\u002Fdownloads\u002Fsafe-${OS}-${ARCH}\" -o safe && chmod +x safe && sudo mv safe \u002Fusr\u002Flocal\u002Fbin\u002F; }\n```\n\nVerify installation:\n```bash\nsafe --help\n```\n\n**Optional: verify checksum** (SHA-256 values from [checksums.txt](https:\u002F\u002Fthesafe.dev\u002Fdownloads\u002Fchecksums.txt)):\n```\nddf638ccfd119d9c3351825a2e3f9e3660f754009eb9b106d7bba8cd698c3df4  safe-darwin-arm64\n6be4942048a23e99485c0123cf0bb4786613a3dabbcc6927aa478cd0e719ad0b  safe-darwin-amd64\n85c7822ac0309e62ca29d03394bfe87a506f329f61c30b070c379a6d2f5af815  safe-linux-amd64\n33207a4c6bbf85b8299f2f75e18aa6e13f9a8ae4bcee72a9d869034d78ba4cac  safe-linux-arm64\n```\n\n### Installation Debugging\n\n**\"safe: command not found\"** after install:\n- Check if binary exists: `ls -la \u002Fusr\u002Flocal\u002Fbin\u002Fsafe`\n- If sudo failed, install to user dir: `mv safe ~\u002F.local\u002Fbin\u002F && export PATH=\"$HOME\u002F.local\u002Fbin:$PATH\"`\n- Refresh shell: `hash -r` or start new terminal\n\n**Permission denied on \u002Fusr\u002Flocal\u002Fbin**:\n- Use sudo: `sudo mv safe \u002Fusr\u002Flocal\u002Fbin\u002F`\n- Or install to user dir: `mkdir -p ~\u002F.local\u002Fbin && mv safe ~\u002F.local\u002Fbin\u002F`\n\n### When CLI Is Unavailable — Browser-Based Alternative\n\nIf CLI installation fails or isn't possible (restricted environment, no build tools, no shell access, sandboxed IDE, etc.), use the web interface at **[https:\u002F\u002Fthesafe.dev](https:\u002F\u002Fthesafe.dev)**.\n\nThis is a fully functional SAFE implementation running in the browser — not a demo. All cryptographic operations happen client-side. No data leaves the browser.\n\nThe web interface supports all core SAFE operations via a single-page layout with these sections:\n- **ENCRYPT tab**: Encrypt data with passwords, public keys, passkeys, or GitHub usernames\n- **DECRYPT tab**: Decrypt SAFE messages with passwords, private keys, passkeys, or GitHub keys\n- **KEYCHAIN section**: Save, import, export, and manage keys and passwords\n- **ADVANCED section**: Lock Management (add\u002Fremove recipients), Re-encrypt Demo, Tests\n- **LOG section**: View operation log output\n\n**Manual workflow (no automation needed):**\n\nUsers can interact with the web interface directly:\n\n1. **Encrypt**: Enter plaintext, add recipients (key, password, passkey, or GitHub username), click \"ENCRYPT\". Copy or download the output.\n2. **Decrypt**: Paste\u002Fupload\u002FURL-load a SAFE message, add credentials (private key, password, passkey, or GitHub), click \"DECRYPT\". Copy or download the plaintext.\n\nGenerated keys are automatically saved in the KEYCHAIN section and can be reused across operations.\n\n**Agent with MCP browser tools (Playwright, Puppeteer, etc.):**\n\nIf you have access to browser automation tools (e.g., Playwright MCP server, Claude in Chrome, Puppeteer MCP), you can drive the web interface directly.\n\n**Key behaviors to know:**\n- After encrypting, output auto-populates into the decrypt section's SAFE message input\n- The browser auto-matches saved credentials and pre-adds them to decrypt\n- Generated keys are auto-saved to the Credentials section (04)\n- Always take a snapshot (`browser_snapshot`) after each action to get updated element references\n\n**ARIA labels for automation:**\n\nThe interface uses semantic ARIA roles throughout:\n\n| Element | ARIA Label | Role |\n|---------|-----------|------|\n| KEM type selector | \"Select key encapsulation mechanism type\" | combobox |\n| Generate button | \"Generate new keypair with selected KEM type\" | button |\n| Plaintext input | \"Enter plaintext message to encrypt\" | textbox |\n| Add Step button | \"Add encryption step to recipient path\" | button |\n| Step type selector | \"Select encryption step type\" | combobox |\n| Password field (encrypt) | \"Enter password for encryption step\" | textbox |\n| Confirm step | \"Confirm encryption step\" | button |\n| Encrypt button | \"Encrypt plaintext with configured settings and recipient path\" | button |\n| Encrypted output | \"Encrypted SAFE message output\" | textbox |\n| SAFE message input | \"Paste encrypted SAFE message to decrypt\" | textbox |\n| Add credential button (decrypt) | \"Add credential to decryption attempt\" | button |\n| Add credential button (keychain) | \"Add credential to keychain\" | button |\n| Add all keychain button | \"Add all keychain entries as credentials\" | button |\n| Credential type selector | \"Select credential type\" | combobox |\n| New Passkey menu item | \"Create a new passkey\" | menuitem |\n| Password field (decrypt) | \"Enter password for decryption\" | textbox |\n| Confirm credential | \"Confirm credential\" | button |\n| Decrypt button | \"Decrypt SAFE message using provided keychain\" | button |\n| Decrypted output | \"Decrypted plaintext message\" | textbox |\n| Copy buttons | \"Copy encrypted SAFE message to clipboard\" \u002F \"Copy decrypted plaintext to clipboard\" | button |\n| Download buttons | \"Download encrypted SAFE message as file\" \u002F \"Download decrypted file\" | button |\n| Share button (output) | \"Share encrypted SAFE message via URL\" \u002F \"Share decrypted output via URL\" | button |\n| Send button (output) | \"Send encrypted output over WebRTC\" | button (encrypted output only) |\n| Clear button (output) | \"Clear encrypted output\" \u002F \"Clear decrypted output\" | button |\n| Share button (keychain) | \"Share public key via URL\" | button |\n| Label button (keychain) | \"Rename key label\" | button |\n| Use File toggles | \"Use file instead of plaintext input\" \u002F \"Use file instead of SAFE message input\" | generic (clickable) |\n| Navigation links | New (#keygen), Encrypt (#encrypt), Decrypt (#decrypt), Keychain (#keyring), Advanced (expandable) | link |\n| Advanced sections | #unlock, #reencrypt, #tests, #log | link (under Advanced dropdown) |\n| Sections | `role=\"region\"` with labels like \"01 \u002F Key Generation\" | region |\n| Log output | \"Activity log showing operations and their results\" | log |\n\n**Note on Advanced navigation**: The Advanced sections (#unlock, #reencrypt, #tests, #log) are accessed via an \"Advanced\" navigation item that expands to show these additional features.\n\n**Note on terminology**: The UI currently uses mixed terminology - Section 04 is labeled \"Keychain\" and the decrypt button references \"keychain\", but the decrypt section's credential management buttons still use \"Credentials\" in some ARIA labels (e.g., \"Add all keychain entries as credentials\"). Both terms refer to the same saved keys\u002Fpasswords.\n\n**Keychain shortcut buttons:**\n\nEach saved key in Section 04 (Keychain) has quick action buttons:\n- **Enc**: Adds the public key as an encryption recipient step (one click — skips the Add Step → select type → paste → OK workflow)\n- **Dec**: Adds the private key as a decrypt credential (one click — skips the Add → select type → paste → OK workflow)\n- **PUB**: Shows\u002Fcopies the public key\n- **PRIV**: Shows\u002Fcopies the private key\n- **Share**: Generates a shareable URL for the public key\n- **Label**: Rename the key for easier identification\n- **Del**: Removes the key from the keychain\n\n**Prefer using Enc\u002FDec shortcuts** over the manual Add Step flow when keys are saved in the keychain — it reduces 4 interactions to 1.\n\n**File upload:**\n\nBoth encrypt and decrypt sections have a \"Use File\" toggle. Clicking it triggers a file chooser dialog. With MCP Playwright, use `browser_file_upload` to provide the file path. Note: file paths must be within the MCP server's allowed directories.\n\n**Example: Encrypt with password (MCP Playwright)**\n\n```\n# 1. Navigate\nbrowser_navigate(url=\"https:\u002F\u002Fthesafe.dev\")\nbrowser_snapshot()\n\n# 2. Type plaintext (use ref from snapshot for \"Enter plaintext message to encrypt\")\nbrowser_type(ref=\u003Cplaintext-ref>, text=\"secret data\")\n\n# 3. Add password step\nbrowser_click(ref=\u003Cadd-step-button-ref>)      # \"Add encryption step to recipient path\"\nbrowser_snapshot()                              # Get refs for step config form\n\n# 4. Select Password type (default may be \"Public Key\")\nbrowser_select_option(ref=\u003Cstep-type-ref>, values=[\"Password\"])  # \"Select encryption step type\"\nbrowser_snapshot()                              # Get password field ref\n\n# 5. Enter password\nbrowser_type(ref=\u003Cpassword-ref>, text=\"my-password\")  # \"Enter password for encryption step\"\n\n# 6. Confirm the step\nbrowser_click(ref=\u003Cok-ref>)                    # \"Confirm encryption step\"\n\n# 7. Encrypt\nbrowser_click(ref=\u003Cencrypt-ref>)               # \"Encrypt plaintext with configured settings...\"\nbrowser_snapshot()                              # Output is in \"Encrypted SAFE message output\" textbox\n\n# Optional: Share or clear the output\n# browser_click(ref=\u003Cshare-button-ref>)        # \"Share encrypted SAFE message via URL\"\n# browser_click(ref=\u003Cclear-button-ref>)        # \"Clear encrypted output\"\n```\n\n**Example: Encrypt with saved key (fastest path)**\n\n```\n# 1. Navigate\nbrowser_navigate(url=\"https:\u002F\u002Fthesafe.dev\")\nbrowser_snapshot()\n\n# 2. Type plaintext\nbrowser_type(ref=\u003Cplaintext-ref>, text=\"secret data\")\n\n# 3. Click \"Enc\" on a saved key in Credentials section (one click adds recipient)\nbrowser_click(ref=\u003Cenc-button-ref>)\n\n# 4. Encrypt\nbrowser_click(ref=\u003Cencrypt-ref>)\nbrowser_snapshot()\n```\n\n**Example: Decrypt from cold (no auto-populated credentials)**\n\n```\n# 1. Paste SAFE message into decrypt input\nbrowser_type(ref=\u003Csafe-message-ref>, text=\"-----BEGIN SAFE UNLOCK-----\\n...\")\n\n# 2. Add credential\nbrowser_click(ref=\u003Cadd-credential-ref>)        # \"Add credential to decryption attempt\"\nbrowser_snapshot()\n\n# 3. Select Password type (default is \"Private Key\")\nbrowser_select_option(ref=\u003Ccredential-type-ref>, values=[\"Password\"])\nbrowser_snapshot()\n\n# 4. Enter password\nbrowser_type(ref=\u003Cpassword-ref>, text=\"my-password\")\n\n# 5. Confirm credential\nbrowser_click(ref=\u003Cconfirm-ref>)               # \"Confirm credential\"\n\n# 6. Decrypt\nbrowser_click(ref=\u003Cdecrypt-ref>)               # \"Decrypt SAFE message using provided credentials\"\nbrowser_snapshot()                              # Output is in \"Decrypted plaintext message\" textbox\n```\n\n**Example: Same-session encrypt→decrypt (auto-populated)**\n\nAfter encrypting, the output auto-populates into the decrypt section. If the matching key is saved in credentials, it auto-adds the private key. Just click Decrypt — no manual credential entry needed.\n\n**Programmatic browser automation (standalone scripts):**\n\nFor non-MCP environments, use Playwright or Puppeteer directly:\n\n```python\n# Example with Playwright (Python)\nfrom playwright.sync_api import sync_playwright\n\nwith sync_playwright() as p:\n    browser = p.chromium.launch()\n    page = browser.new_page()\n    page.goto('https:\u002F\u002Fthesafe.dev')\n\n    # Generate X25519 keypair\n    page.get_by_role(\"combobox\", name=\"Select key encapsulation mechanism type\").select_option(\"X25519\")\n    page.get_by_role(\"button\", name=\"Generate new keypair\").click()\n\n    # Encrypt with password\n    page.get_by_role(\"textbox\", name=\"Enter plaintext message to encrypt\").fill(\"secret message\")\n    page.get_by_role(\"button\", name=\"Add encryption step to recipient path\").click()\n    page.get_by_label(\"Select encryption step type\").select_option(\"Password\")\n    page.get_by_role(\"textbox\", name=\"Enter password for encryption step\").fill(\"mypassword\")\n    page.get_by_role(\"button\", name=\"Confirm encryption step\").click()\n    page.get_by_role(\"button\", name=\"Encrypt plaintext\").click()\n\n    # Read encrypted output\n    encrypted = page.get_by_label(\"Encrypted SAFE message output\").input_value()\n\n    # Decrypt (message and credentials auto-populate from encrypt)\n    page.get_by_role(\"button\", name=\"Decrypt SAFE message\").click()\n    decrypted = page.get_by_label(\"Decrypted plaintext message\").input_value()\n\n    print(f\"Decrypted: {decrypted}\")  # \"secret message\"\n    browser.close()\n```\n\n**Multi-Recipient Encryption:**\n\nBoth the browser UI and CLI support encrypting for multiple recipients. Each recipient can decrypt the message independently using their own credential.\n\n**Browser workflow:**\n1. Configure first recipient in \"Recipient 1\" (password or public key)\n2. Click \"+ Add Recipient\" button\n3. Configure second recipient in \"Recipient 2\"\n4. Repeat for additional recipients (no limit)\n5. Click \"Encrypt\" - message is encrypted once but decryptable by any recipient\n\n**How it works:**\n- Each recipient gets their own UNLOCK block in the SAFE message\n- File is encrypted once with a symmetric key\n- Symmetric key is wrapped separately for each recipient\n- Any recipient can decrypt using their credential (password or private key)\n- Recipients cannot see who else has access\n\n**CLI multi-recipient examples:**\n```bash\n# Encrypt for multiple recipients using -r flag multiple times\nsafe encrypt -i file.txt -o file.safe -r alice.pub -r bob.pub -r charlie.pub\n\n# Mix recipient types (password + keys)\nsafe encrypt -i file.txt -o file.safe -p mypassword -r alice.pub -r bob.pub\n\n# Encrypt for GitHub users (fetches public keys from GitHub)\nsafe encrypt -i file.txt -o file.safe -r github:grittygrease\n\n# Multiple GitHub users\nsafe encrypt -i file.txt -o file.safe -r github:alice -r github:bob\n\n# Encrypt for GitHub users and a password\nsafe encrypt -i file.txt -o file.safe -p teampassword -r github:alice -r github:bob\n```\n\n**GitHub username recipient (`github:username`):**\n- Fetches SSH public keys from `https:\u002F\u002Fgithub.com\u002F{username}.keys`\n- Automatically converts p-256 and x25519 keys to SAFE format\n- Both key types are added as separate recipients if available\n- Requires user to have public keys on their GitHub profile\n- Error if no keys found: `github:username: no keys found`\n\n**Example output:**\n```bash\n$ safe encrypt -i test.txt -o test.safe -r github:grittygrease\n# Creates UNLOCK blocks for both p-256 and x25519 keys from GitHub\n\n$ safe info -i test.safe\nLOCK Blocks: 2\n  [0] hpke(kem=p-256,id=QyLFP\u002F...)\n  [1] hpke(kem=x25519,id=r1VeL...)\n```\n\n**Agent-to-Agent Communication via GitHub Gist:**\n\nAgents can securely exchange encrypted messages using GitHub Gist as a transport layer. This enables asynchronous, persistent communication between agents with different GitHub accounts.\n\n**Complete Workflow:**\n\n**Agent A (Sender):**\n```bash\n# 1. Create message for Agent B\necho \"Task completed. Results attached.\" > message.txt\n\n# 2. Encrypt for Agent B's GitHub account\nsafe encrypt -i message.txt -o message.safe -r github:agentb-username\n\n# 3. Upload encrypted message to public Gist\ngh gist create message.safe --desc \"Encrypted message for agentb-username\" --public\n\n# Output: https:\u002F\u002Fgist.github.com\u002Fagenta-username\u002F{gist-id}\n```\n\n**Agent B (Receiver):**\n```bash\n# Method 1: Direct pipe (simplest, auto-discovers keys)\ncurl -sL https:\u002F\u002Fgist.github.com\u002Falice\u002F{gist-id}\u002Fraw | safe decrypt\n\n# Method 2: Download, inspect, then decrypt\ncurl -sL https:\u002F\u002Fgist.github.com\u002Falice\u002F{gist-id}\u002Fraw > received.safe\nsafe info -i received.safe  # Verify sender and encryption details\nsafe decrypt -i received.safe -o message.txt\n\n# Method 3: Explicit key (if auto-discovery doesn't work)\ncurl -sL https:\u002F\u002Fgist.github.com\u002Falice\u002F{gist-id}\u002Fraw | safe decrypt -k ~\u002F.safe\u002Fkeys\u002Fbob.x25519.key\n```\n\n**SSH Key Auto-Discovery (SAFE CLI v2.3+):**\n\nThe SAFE CLI automatically discovers and uses SSH private keys from `~\u002F.ssh\u002F`:\n- ✅ **Ed25519 keys** → converted to X25519\n- ✅ **P-256 ECDSA keys** → used directly\n- ✅ **Unencrypted keys only** (passphrase-protected keys silently skipped)\n- ✅ **Zero configuration** - just works if your SSH keys match GitHub public keys\n\n**Auto-Discovery Order:**\n1. `~\u002F.safe\u002Fkeys\u002F*.key` - Native SAFE format keys (checked first)\n2. `~\u002F.ssh\u002F*` - All SSH private keys in `~\u002F.ssh\u002F` directory\n   - Ed25519 keys → converted to X25519\n   - P-256 ECDSA keys → used directly\n\n**Example Auto-Discovery Output:**\n```bash\n$ curl -sL https:\u002F\u002Fgist.github.com\u002F...\u002Fraw | safe decrypt\nsafe: using SSH key ~\u002F.ssh\u002Fid_ed25519\nsafe: trying 3 key(s) (2 native + 1 SSH)\n[decrypted message]\n```\n\n**Key Requirements:**\n- **Agent B must have private keys** that correspond to the public keys on their GitHub profile\n- GitHub SSH keys must be added to `https:\u002F\u002Fgithub.com\u002F{username}.keys`\n- Private keys can be in `~\u002F.safe\u002Fkeys\u002F` (SAFE format) **OR** `~\u002F.ssh\u002F` (OpenSSH format)\n- Gist can be public (encrypted content is safe) or private for additional obscurity\n\n**Multi-Agent Broadcast:**\n```bash\n# Encrypt for multiple agents\nsafe encrypt -i broadcast.txt -o broadcast.safe \\\n  -r github:agent1 \\\n  -r github:agent2 \\\n  -r github:agent3\n\n# Any of the three agents can decrypt independently\ngh gist create broadcast.safe --desc \"Team update\" --public\n```\n\n**Agent Identity Setup:**\n\nTo enable decryption, agents need to set up their GitHub SSH keys and store private keys:\n\n```bash\n# Option 1: Use existing SSH keys (simplest - zero setup!)\n# If you already have ~\u002F.ssh\u002Fid_ed25519 or ~\u002F.ssh\u002Fid_ecdsa uploaded to GitHub, you're done!\n# SAFE CLI auto-discovers SSH keys - no key generation needed\n\n# Option 2: Generate new SSH key and upload to GitHub\nssh-keygen -t ed25519 -f ~\u002F.ssh\u002Fid_ed25519 -N \"\" -C \"safe-agent-key\"\ngh ssh-key add ~\u002F.ssh\u002Fid_ed25519.pub --title \"SAFE Agent Key\"\n# Done! SAFE CLI will auto-discover this key\n\n# Option 3: Generate SAFE-native keys (for advanced use cases)\nsafe keygen x25519 -o agent-id\n# Upload agent-id.x25519.pub to https:\u002F\u002Fgithub.com\u002Fsettings\u002Fkeys (manual conversion needed)\nmv agent-id.x25519.key ~\u002F.safe\u002Fkeys\u002F\n\n# Test encryption to self (works with any option above)\nsafe encrypt -i test.txt -o test.safe -r github:your-username\nsafe decrypt -i test.safe -o decrypted.txt\n# With SSH keys, decryption auto-discovers your keys from ~\u002F.ssh\u002F\n```\n\n**Browser-Based Agent Workflow:**\n\nAgents using thesafe.dev have full GitHub support for both encryption and decryption.\n\n**Encrypt to a GitHub user (browser):**\n\n1. Go to the **ENCRYPT** tab\n2. Enter your message\n3. Click **ADD FACTOR** → **NEW FACTOR** → select **GITHUB**\n4. Enter the GitHub username (e.g., `smithclay`)\n5. Click **FETCH KEYS** — the browser fetches public keys from `https:\u002F\u002Fgithub.com\u002F{username}.keys`\n6. Click **ENCRYPT**\n7. Copy the output and share via Gist\n\n**Decrypt a GitHub-encrypted message (browser):**\n\n1. Go to the **DECRYPT** tab\n2. Load the encrypted message: paste text, use the **FILE** button to upload, or use the **URL** button to load directly from a Gist URL (e.g., paste the raw Gist URL)\n3. Click **ADD** → **GITHUB** → enter your GitHub username → click **FETCH KEYS**\n   (This matches your public keys to the message's LOCK blocks)\n4. Click **ADD** → **KEY** → paste your SSH private key (from `~\u002F.ssh\u002Fid_ed25519` or `~\u002F.ssh\u002Fid_ecdsa`)\n   — or use the **\"Import SSH private key from GitHub\"** button if available\n5. Click **DECRYPT**\n\n**Recommended approach for browser-based workflows:**\n- **Both CLI and browser support `github:username`** for encryption equally well\n- **CLI is simpler for decryption** — it auto-discovers SSH keys from `~\u002F.ssh\u002F`; browser requires pasting the private key once\n- **URL button is convenient** — load encrypted Gist content directly without curl\n\n**Send encrypted output over WebRTC (browser):**\n\nThe browser supports real-time peer-to-peer transfer of encrypted SAFE messages via WebRTC — no copy-paste required:\n\n**Sender:**\n1. Encrypt your message as usual to produce the encrypted output\n2. Click **Send** in the output toolbar (next to Download, Share, Copy)\n3. A dialog appears: \"Share join URL, then wait for receiver...\"\n4. The join URL is offered via the native OS share sheet (if available) or logged in the **Log** panel\n5. Keep the tab open — when the receiver connects, the dialog updates to \"Receiver connected. Starting transfer...\"\n6. Transfer completes automatically\n\n**Receiver:**\n1. Open the join URL: `https:\u002F\u002Fthesafe.dev\u002F?session=\u003Cid>&token=\u003Ctoken>`\n2. The page auto-connects, receives the encrypted message, and switches to the **Decrypt** tab with the message pre-loaded\n3. Add credentials and click **Decrypt** as normal\n\n**Notes:**\n- Join URLs expire after **30 minutes**\n- Max transfer size: 100 MB\n- Sender must keep the tab open until the receiver connects\n- **Share** (separate button) shares the file or text directly with no server involved; **Send** is the WebRTC real-time peer flow\n\n**Agent Ping\u002FNotification Workflow:**\n\nYou can \"ping\" another agent using their GitHub username without needing their public key in advance:\n\n```bash\n# Alice pings Bob (discovers keys automatically via github:username)\necho \"PING: Status update requested\" > ping.txt\nsafe encrypt -i ping.txt -o ping.safe -r github:bob\ngh gist create ping.safe --desc \"Ping from Alice\" --public\n\n# Bob discovers the ping and decrypts (SSH key auto-discovery!)\ncurl -sL https:\u002F\u002Fgist.github.com\u002Falice\u002F{gist-id}\u002Fraw | safe decrypt\n# safe: using SSH key ~\u002F.ssh\u002Fid_ed25519\n# safe: trying 1 key(s) (0 native + 1 SSH)\n# PING: Status update requested\n\n# Bob responds back to Alice\necho \"PONG: Status OK, task 75% complete\" > pong.txt\nsafe encrypt -i pong.txt -o pong.safe -r github:alice\ngh gist create pong.safe --desc \"Response to Alice\" --public\n```\n\n**Key Benefits:**\n- ✅ No prior key exchange needed - `github:username` fetches public keys automatically\n- ✅ No key management needed - reuse existing SSH keys from GitHub\n- ✅ Works instantly if you already have SSH keys on GitHub\n- ✅ Works for any GitHub user with public SSH keys on their profile\n- ✅ Both agents can initiate communication\n- ✅ Asynchronous - sender doesn't need to wait for response\n- ✅ Persistent - messages remain in Gist until deleted\n\n**Discovery Methods:**\n- GitHub Gist notifications (if agent watches their own Gists)\n- Periodic polling of GitHub API for new Gists mentioning their username\n- GitHub webhooks for real-time notifications\n- RSS feeds for public Gists\n\n**Security Notes:**\n- Gist URLs are discoverable if public - use private Gists for sensitive coordination\n- Encrypted content is safe even if Gist is public (only recipient has private key)\n- Gist history is immutable - deleted messages remain in Git history\n- Use short-lived Gists and delete after confirmation for ephemeral communication\n- Multi-recipient encryption prevents sender from knowing who decrypted the message\n\n---\n\n### CLI vs Browser: Feature Comparison\n\n| Feature | CLI (SAFE v2.3+) | Browser (thesafe.dev) |\n|---------|------------------|------------------------|\n| `github:username` encryption | ✅ Yes | ✅ Yes |\n| `github:username` decryption | ✅ Auto (SSH key auto-discovery) | ✅ Yes (paste SSH key once) |\n| SSH key auto-discovery | ✅ Yes (`~\u002F.ssh\u002F`) | ❌ No (manual paste) |\n| Ed25519 SSH keys | ✅ Auto-converts to X25519 | ✅ Manual paste |\n| P-256 ECDSA SSH keys | ✅ Direct support | ✅ Manual paste |\n| SAFE native keys | ✅ Yes (`~\u002F.safe\u002Fkeys\u002F`) | ✅ Yes (import\u002Fexport) |\n| Load from URL (e.g. Gist) | ✅ `curl \u003Curl> \\| safe decrypt` | ✅ URL button in DECRYPT tab |\n| Real-time peer transfer | ❌ No | ✅ Send button (WebRTC, 30-min join URL) |\n| Zero-setup decryption | ✅ If SSH keys on GitHub | ⚠️ Must paste private key once |\n\n**Recommendation:**\n- **Encryption:** Both CLI and browser support `github:username` equally well\n- **Decryption:** CLI is easier (auto-discovers SSH keys); browser requires pasting your private key\n- **Best of both:** Use browser for encryption, CLI for decryption when available\n\n---\n\n**Keychain management:**\n\nThe Keychain section (04) supports:\n- **Add Credential** (dropdown menu with options):\n  - **Import Key**: Import an existing public or private key (PEM or base64)\n  - **New Passkey**: Create a new WebAuthn passkey (requires browser\u002FOS authenticator, prompts for label)\n  - **New Password**: Add a new password for encryption\u002Fdecryption\n  - **Existing Passkey**: Use an existing passkey from your authenticator\n- **Export**: Export keychain as encrypted SAFE backup (password-protected `.safe` file containing private keys in PEM format)\n- **Import**: Import a previously exported keychain backup (file upload + passphrase)\n- **Clear All**: Delete all keychain entries (shows a confirm dialog)\n\n**Passkey Limitations for Automation:**\n- Passkey creation requires WebAuthn hardware interaction (biometric, security key, etc.)\n- Cannot be fully automated - requires user interaction with authenticator\n- Dialog prompts for \"Passkey label\" before creation\n- Best suited for interactive sessions, not headless automation\n\nGenerated keys are automatically saved here. Each key shows its type and Key ID hints, with Enc\u002FDec\u002FShare\u002FPUB\u002FPRIV\u002FLabel\u002FDel action buttons.\n\n**Export\u002FImport workflow (for persisting keys across sessions):**\n\nExport:\n1. Click \"Export credentials as encrypted backup\" → dialog appears\n2. Enter passphrase + confirm passphrase → click OK\n3. Downloads `safe-credentials-backup.safe` (a standard SAFE file, pwd-encrypted)\n4. The export contains private keys only (PEM format). Public keys are derived on re-import.\n\nImport:\n1. Click \"Import\" → file chooser appears (use `browser_file_upload` with MCP)\n2. Select the `.safe` backup file → passphrase dialog appears\n3. Enter passphrase → click OK\n4. Keys are restored with full functionality (Enc\u002FDec\u002FPUB\u002FPRIV buttons)\n5. Duplicates are automatically skipped\n\nThe exported `.safe` file is CLI-compatible: `safe decrypt safe-credentials-backup.safe -p \"passphrase\"` reveals the PEM keys.\n\n### Agent Session Persistence (Browser Workflow)\n\nAgents can maintain a persistent identity across browser sessions by saving and re-uploading the keychain backup:\n\n**First browser session**:\n1. Navigate to https:\u002F\u002Fthesafe.dev\n2. Generate keys (Section 01) or receive keys from other agents\n3. Export keychain: Click \"Export\" → enter passphrase → download `safe-credentials-backup.safe`\n4. Save the encrypted backup file to persistent storage (filesystem, database, cloud storage, etc.)\n5. Store the passphrase securely (environment variable, secure key store, etc.)\n\n**New browser session** (different browser, incognito, new tab, etc.):\n1. Navigate to https:\u002F\u002Fthesafe.dev\n2. Import keychain: Click \"Import\" → upload `safe-credentials-backup.safe` → enter passphrase\n3. All keys are restored with full functionality (Enc\u002FDec\u002FPUB\u002FPRIV\u002FShare\u002FLabel\u002FDel)\n4. Agent can immediately encrypt\u002Fdecrypt using saved keys\n\n**Benefits**:\n- Agents maintain the same cryptographic identity across sessions\n- No need to regenerate keys or re-exchange public keys with other agents\n- Encrypted communication history remains accessible\n- Works across different browsers, devices, and environments\n\n**Security notes**:\n- The backup file is encrypted with the passphrase (argon2id by default)\n- File is CLI-compatible: `safe decrypt safe-credentials-backup.safe -p \"passphrase\"`\n- Store the passphrase separately from the backup file\n- Backup contains only private keys in PEM format; public keys are derived on import\n\n**Example workflow with MCP Playwright**:\n\n```python\n# First session: Export keychain\nbrowser_click(ref=\u003Cexport-button-ref>)  # \"Export keychain\"\n# Enter passphrase in dialog\nbrowser_type(ref=\u003Cpassphrase-ref>, text=\"agent-secret-passphrase\")\nbrowser_type(ref=\u003Cconfirm-passphrase-ref>, text=\"agent-secret-passphrase\")\nbrowser_click(ref=\u003Cok-ref>)\n# File downloads as safe-credentials-backup.safe\n# Save this file to persistent storage\n\n# New session: Import keychain\nbrowser_navigate(url=\"https:\u002F\u002Fthesafe.dev\")\nbrowser_click(ref=\u003Cimport-button-ref>)  # \"Import keychain backup\"\nbrowser_file_upload(paths=[\"\u002Fpath\u002Fto\u002Fsafe-credentials-backup.safe\"])\n# Enter passphrase in dialog\nbrowser_type(ref=\u003Cpassphrase-ref>, text=\"agent-secret-passphrase\")\nbrowser_click(ref=\u003Cok-ref>)\n# All keys restored, agent can now encrypt\u002Fdecrypt\n```\n\nThis enables agents to maintain cryptographic identities across:\n- Browser restarts\n- Incognito\u002Fprivate browsing sessions\n- Different physical machines\n- Cloud-based agent deployments\n\n**When to use the web interface:**\n- CLI can't be installed (no Go\u002FRust, restricted environment, sandboxed IDE)\n- No shell access (browser-only agent, web-based coding environment)\n- One-off encryption\u002Fdecryption tasks\n- Testing SAFE format without installing dependencies\n- Quick key generation or format exploration\n\n**When to prefer the CLI:**\n- Production systems or automated pipelines\n- Batch or high-volume operations (CLI is significantly faster)\n- Air-gapped or offline environments\n- Scripting with shell pipes and file I\u002FO\n\n## Quick Reference\n\n### Key Storage Convention\n\nPersonal keys are stored in `~\u002F.safe\u002F` (similar to `~\u002F.ssh\u002F`). The CLI manages this directory automatically:\n\n```bash\nsafe keygen x25519                     # Generates keypair, auto-stores to ~\u002F.safe\u002F\nsafe keygen x25519 -n alice            # Named identity \"alice\"\nsafe keys                              # List all identities and recipients\n```\n\n**Key Discovery Order (SAFE CLI v2.3+):**\n1. `~\u002F.safe\u002Fkeys\u002F*.key` - SAFE-native keys (checked first)\n2. `~\u002F.ssh\u002F*` - All SSH private keys in `~\u002F.ssh\u002F` directory\n   - Ed25519 keys → auto-converted to X25519\n   - P-256 ECDSA keys → used directly\n\n**Note:** You can use EITHER format - SSH keys from GitHub work with zero configuration!\n\nDirectory structure (auto-created by `safe keygen`):\n- `~\u002F.safe\u002Fkeys\u002F` — Private keys (0700, never share). E.g., `nick.x25519.key`\n- `~\u002F.safe\u002F*.pub` — Your own public keys (safe to share). E.g., `nick.x25519.pub`\n- `~\u002F.safe\u002Frecipients\u002F` — Other people's public keys (managed by `safe keys add`)\n\nOverride with `SAFE_HOME` env var. Fallback: `.\u002F.safe\u002F` in current directory.\n\n### Generate Keys\n\n| Key Type | Command | Use Case |\n|----------|---------|----------|\n| x25519 | `safe keygen x25519` | Fast, default, widely supported |\n| p-256 | `safe keygen p-256` | FIPS compliance |\n| ml-kem-768 | `safe keygen ml-kem-768` | Post-quantum security (seed by default) |\n\nBy default, keygen uses `$USER` as the identity name and stores keys in `~\u002F.safe\u002F`. Override with `-n name` or `-o path`.\n\n```bash\nsafe keygen x25519                     # ~\u002F.safe\u002Fkeys\u002F$USER.x25519.key + ~\u002F.safe\u002F$USER.x25519.pub\nsafe keygen x25519 -n alice            # ~\u002F.safe\u002Fkeys\u002Falice.x25519.key + ~\u002F.safe\u002Falice.x25519.pub\nsafe keygen ml-kem-768                 # Generates seed (compact format, default for ML-KEM)\nsafe keygen ml-kem-768 -no-seed        # Raw keypair instead of seed\nsafe keygen x25519 -o \u002Ftmp\u002Fthrowaway   # Custom output path\nsafe keygen x25519 -force              # Overwrite existing files\n```\n\nOutput: `\u003Cname>.\u003Ctype>.pub` (share this) and `\u003Cname>.\u003Ctype>.key` (keep secret). Public key is always written to `~\u002F.safe\u002F`.\n\n### Manage Keys\n\n```bash\n# List all identities and known recipients\nsafe keys\n\n# Import a recipient's public key\nsafe keys add alice.x25519.pub --name alice\n\n# Remove a recipient\nsafe keys remove alice\n\n# Derive public key from private key (by name or path)\nsafe pubkey alice                       # Looks up ~\u002F.safe\u002Fkeys\u002Falice.*.key\nsafe pubkey \u002Fpath\u002Fto\u002Fkey.key            # Direct file path\n\n# View key details\nsafe keyinfo alice.x25519.pub\n```\n\nBare names work as recipients after import: `safe encrypt data.txt -r alice` resolves from `~\u002F.safe\u002Frecipients\u002F`. Also resolves system users: `-r bob` checks `~bob\u002F.safe\u002F*.pub`.\n\n### Encrypt\n\nstdin is the default input, stdout is the default output. Positional argument sets input file.\n\n```bash\n# Password-protect a file\nsafe encrypt secrets.txt -o secrets.safe -p \"strong-password\"\n\n# Encrypt to recipient (bare name or key file)\nsafe encrypt file.txt -o file.safe -r alice\n\n# Multiple recipients (OR - any one can decrypt)\nsafe encrypt file.txt -o file.safe -r alice -r bob\n\n# Two-factor: password AND key required (+ is AND separator)\nsafe encrypt file.txt -o file.safe -r \"pwd:secret + alice.pub\"\n\n# Pipe from stdin (default)\necho \"secret\" | safe encrypt -p \"pw\" > msg.safe\n\n# Password from environment variable\nsafe encrypt file.txt -o file.safe -p env:MY_PASSWORD\n\n# PBKDF2 instead of argon2id\nsafe encrypt file.txt -o file.safe -p \"pw\" --kdf pbkdf2\n```\n\n### Decrypt\n\nstdin is the default input, stdout is the default output. If no credentials are provided, keys from `~\u002F.safe\u002Fkeys\u002F` are tried automatically.\n\n```bash\n# With password\nsafe decrypt file.safe -p \"password\"\n\n# With private key\nsafe decrypt file.safe -k alice.x25519.key\n\n# Auto-discover keys (no -k needed if keys are in ~\u002F.safe\u002Fkeys\u002F)\nsafe decrypt file.safe\n\n# age-compatible --identity flag\nsafe decrypt file.safe --identity alice.key\n\n# Two-factor (all credentials required)\nsafe decrypt file.safe -o file.txt -p \"secret\" -k alice.key\n\n# Write to file instead of stdout\nsafe decrypt file.safe -o plaintext.txt -p \"password\"\n\n# Password from environment variable\nsafe decrypt file.safe -p env:MY_PASSWORD\n```\n\n### Info\n\nInspect a SAFE file's metadata without credentials:\n\n```bash\nsafe info file.safe\n# Output:\n#   AEAD: aes-256-gcm\n#   Block Size: 65536\n#   Key Hash: spki-sha256-16\n#   Data size: 1048 bytes\n#   UNLOCK Blocks: 2\n#     [0] pwd(argon2id)\n#     [1] hpke(kem=x25519, id=r3YlsKxQHj1q1d\u002FkKi5e3Q==)\n\n# From stdin\ncat file.safe | safe info\n```\n\n### Piping (stdin\u002Fstdout)\n\nstdin and stdout are the defaults — no `-i -` or `-o -` needed. All operations are binary-safe.\n\n**Default behavior:** Always prefer piping over writing intermediate files to disk. This avoids leaving decrypted content on disk and is cleaner.\n\n```bash\n# Decrypt base64-encoded content (PREFERRED - no temp file)\necho \"LS0tLS1CRUdJTi...\" | base64 -d | safe decrypt -k ~\u002F.safe\u002Fkeys\u002Fid.x25519.key\n\n# AVOID: Writing intermediate files\n# echo \"LS0tLS1CRUdJTi...\" | base64 -d > \u002Ftmp\u002Ffile.safe && safe decrypt \u002Ftmp\u002Ffile.safe ...\n\n# Basic stdin\u002Fstdout\necho \"secret\" | safe encrypt -p \"pw\" > encrypted.safe\ncat encrypted.safe | safe decrypt -p \"pw\"\n\n# Chain operations (re-encrypt with different key)\nsafe decrypt a.safe -p \"pw1\" | safe encrypt -o b.safe -p \"pw2\"\n\n# Encrypt with compression\ntar cz src\u002F | safe encrypt -o backup.safe -r alice\n\n# Decrypt and decompress\nsafe decrypt backup.safe -k team.key | tar xz\n\n# Decrypt remote file\ncurl -s https:\u002F\u002Fexample.com\u002Fdata.safe | safe decrypt -k my.key\n\n# Pipe through compression then encrypt\nsafe encrypt -p \"pw\" \u003C large.bin | gzip > encrypted.safe.gz\n\n# Decrypt gzipped safe file\ngunzip -c encrypted.safe.gz | safe decrypt -p \"pw\" > large.bin\n```\n\n**Note:** `-i -` and `-o -` still work for explicit stdin\u002Fstdout but are no longer required.\n\n## Common Use Cases\n\n### Protect API Keys \u002F .env Files\n\n```bash\nsafe encrypt .env -o .env.safe -p \"dev-password\"\nsafe encrypt credentials.json -o credentials.safe -r ops-team\n```\n\n### Share Secrets with a Teammate\n\n```bash\n# They generate their key\nsafe keygen x25519 -n teammate\n\n# You import their public key\nsafe keys add teammate.x25519.pub --name teammate\n\n# You encrypt for them (bare name!)\nsafe encrypt api-keys.txt -o api-keys.safe -r teammate\n\n# They decrypt (auto-discovers keys from ~\u002F.safe\u002Fkeys\u002F)\nsafe decrypt api-keys.safe -o api-keys.txt\n```\n\n### Encrypt Backup Before Cloud Upload\n\n```bash\ntar czf backup.tar.gz ~\u002FDocuments\nsafe encrypt backup.tar.gz -o backup.safe -p \"backup-phrase\" -r recovery\n# Upload backup.safe to S3\u002FGCS\u002FDropbox\n```\n\n### Encrypt Entire Directories\n\n```bash\n# Encrypt a folder\ntar cz project\u002F | safe encrypt -o project.safe -r team\n\n# Decrypt and extract\nsafe decrypt project.safe -k team.key | tar xz\n```\n\n### Git-Friendly Encrypted Secrets\n\n```bash\n# Encrypt secrets, commit the .safe file\nsafe encrypt .env.production -o .env.production.safe -r deploy\ngit add .env.production.safe  # Safe to commit\n\n# On deploy server (auto-discovers deploy key from ~\u002F.safe\u002Fkeys\u002F)\nsafe decrypt .env.production.safe -o .env.production\n```\n\n### Separation of Duties (Two People Required)\n\n```bash\n# Encrypt requiring BOTH Alice and Bob (+ is AND)\nsafe encrypt codes.txt -o codes.safe -r \"alice.pub + bob.pub\"\n\n# Decrypt (both must provide keys)\nsafe decrypt codes.safe -o codes.txt -k alice.key -k bob.key\n```\n\n### Two-Factor Encryption (Password + Key)\n\n```bash\n# Encrypt: requires password AND key\nsafe encrypt secrets.txt -o secrets.safe -r \"pwd:mypassword + hardware.pub\"\n\n# Decrypt: must provide both\nsafe decrypt secrets.safe -o secrets.txt -p \"mypassword\" -k hardware.key\n```\n\n### Team Encryption + Emergency Backup\n\n```bash\nsafe encrypt secrets.txt -o secrets.safe \\\n  -r alice -r bob -r carol \\\n  -p \"emergency-recovery-phrase\"\n```\n\n### Post-Quantum Hybrid Protection\n\n```bash\n# Generate both classical and PQ keys\nsafe keygen x25519 -n alice\nsafe keygen ml-kem-768 -n alice\n\n# Encrypt with both (future-proof against quantum computers)\nsafe encrypt data.txt -o data.safe \\\n  -r \"pwd:phrase + alice.x25519.pub + alice.ml-kem-768.pub\"\n```\n\n### Temporary Decryption (No File on Disk)\n\n```bash\n# Use decrypted content without writing to disk\n.\u002Fmy-app --config \u003C(safe decrypt config.safe -p \"pw\")\n\n# Compare two encrypted files\ndiff \u003C(safe decrypt old.safe -p pw) \u003C(safe decrypt new.safe -p pw)\n```\n\n### Password Rotation\n\n```bash\n# Change password without re-encrypting data\nsafe unlock replace secrets.safe -p \"old-password\" \\\n  --index 0 --recipient \"pwd:new-password\"\n```\n\n### Key Rotation (Compromised Key)\n\n```bash\n# View current recipients\nsafe info secrets.safe\n\n# Remove compromised key, add new one\nsafe unlock remove secrets.safe -k admin.key --index 2\nsafe unlock add secrets.safe -k admin.key --recipient new-employee.pub\n```\n\n## Composable Paths (AND vs OR Logic)\n\n| Encrypt With | Decrypt Requires | Logic |\n|--------------|------------------|-------|\n| `-r alice -r bob` | `-k alice.key` OR `-k bob.key` | OR |\n| `-r \"alice.pub + bob.pub\"` | `-k alice.key` AND `-k bob.key` | AND |\n| `-r \"pwd:x + alice.pub\"` | `-p x` AND `-k alice.key` | AND |\n| `-p backup -r alice` | `-p backup` OR `-k alice.key` | OR |\n\nMultiple `-r` or `-p` flags = OR (any one works)\n`+` within one `-r` = AND (all required)\n\n**Note:** `->` is deprecated but still works. Use `+` for new code.\n\n## Editing Encrypted Files\n\nSAFE supports random-access editing without full re-encryption. Only modified chunks are re-encrypted - unchanged chunks are copied byte-for-byte.\n\n### Data Input Options\n\n| Option | Use | Example |\n|--------|-----|---------|\n| `--data \"string\"` | Literal text on command line | `--data \"hello\"` |\n| `--data-file path` | Read content from a file | `--data-file patch.bin` |\n\n### Read Bytes at Offset\n\nRead a portion of an encrypted file without decrypting the whole thing:\n\n```bash\n# Read first 100 bytes\nsafe read file.safe -p \"pw\" --offset 0 --length 100\n\n# Read bytes 500-600 to a file\nsafe read file.safe -o excerpt.txt -k key.key --offset 500 --length 100\n\n# Shorthand with -n for offset\nsafe read file.safe -p \"pw\" -n 1024 --length 256\n\n# age-compatible --identity flag\nsafe read file.safe --identity key.key -n 0 --length 100\n```\n\n### Write Bytes at Offset (In-Place Edit)\n\nModify bytes at a specific position. In-place by default (no `-o` needed):\n\n```bash\n# Overwrite bytes starting at offset 10\nsafe write file.safe -p \"pw\" -n 10 --data \"new content\"\n\n# Replace header from a file\nsafe write config.safe -p \"pw\" -n 0 --data-file header.bin\n\n# With --identity flag\nsafe write file.safe --identity key.key -n 0 --data \"UPDATED\"\n```\n\n**Note:** Write only supports in-place modification. Output defaults to overwriting the input file.\n\n### Append Data\n\nAdd data to the end of an encrypted file (in-place by default):\n\n```bash\n# Append log entry\nsafe append log.safe -p \"pw\" --data \"$(date): Event occurred\\n\"\n\n# Append from file\nsafe append data.safe -k key.key --data-file new-records.csv\n\n# Append binary data\nsafe append archive.safe -p \"pw\" --data-file chunk.bin\n```\n\n### In-Place Editing Workflow\n\n```bash\n# 1. Check current content\nsafe read config.safe -p \"pw\" -n 0 --length 50\n\n# 2. Make targeted edit\nsafe write config.safe -p \"pw\" -n 25 --data \"new_value\"\n\n# 3. Verify the change\nsafe read config.safe -p \"pw\" -n 0 --length 50\n```\n\n## Managing Recipients (UNLOCK Blocks)\n\nModify who can decrypt without re-encrypting the data. These operations only change the UNLOCK blocks — the encrypted DATA remains identical.\n\n```bash\n# View current recipients and their indexes\nsafe info file.safe\n# Shows: [0] pwd(argon2id)\n#        [1] hpke(kem=x25519, id=ABC123...)\n\n# Add new recipient (in-place by default)\nsafe unlock add file.safe -p \"current-pw\" -r alice.pub\nsafe unlock add file.safe -k admin.key -r \"pwd:backup-pass\"\n\n# Add composable recipient (password + key required)\nsafe unlock add file.safe -p \"pw\" -r \"pwd:secret + bob.pub\"\n\n# Remove recipient by index (in-place)\nsafe unlock remove file.safe -k admin.key --index 0\n\n# Replace recipient at index (in-place)\nsafe unlock replace file.safe -p \"old-pw\" --index 0 -r \"pwd:new-pw\"\n\n# Write to new file instead of in-place\nsafe unlock add file.safe -o new-file.safe -p \"pw\" -r alice.pub\n\n# With --identity flag\nsafe unlock add file.safe --identity admin.key -r bob.pub\n```\n\n**Note:** You cannot remove the last UNLOCK block — the file would become undecryptable.\n\n## Algorithm Options\n\n### AEAD (Content Encryption)\n\n| Algorithm | Flag | Use Case |\n|-----------|------|----------|\n| AES-256-GCM | `--aead aes-256-gcm` | Default, hardware accelerated |\n| ChaCha20-Poly1305 | `--aead chacha20-poly1305` | ARM, older CPUs without AES-NI |\n| AEGIS-256 | `--aead aegis-256` | **CLI only** - Key-committing, highest security. Not available in browser UI. |\n\n### Key Types\n\n| Type | Security | Size (pub\u002Fpriv) |\n|------|----------|-----------------|\n| x25519 | Classical, fast | 32B \u002F 32B |\n| p-256 | FIPS compliant | 65B \u002F 32B |\n| ml-kem-768 | Post-quantum | 1184B \u002F 2400B |\n\n### Key ID Modes\n\nControl how much key identity information is included in UNLOCK blocks:\n\n| Mode | Flag | Behavior |\n|------|------|----------|\n| Full | `--key-id-mode full` | Default. Full key ID included — recipients can check if a message is for them without attempting decryption |\n| Hint | `--key-id-mode hint` | 4-digit hint only — reduces metadata, recipients may need to try decryption |\n| Anonymous | `--key-id-mode anonymous` | No key ID — recipient must try all their keys. Maximum privacy |\n\n```bash\n# Encrypt with hint-only key ID\nsafe encrypt file.txt -o file.safe -r alice --key-id-mode hint\n\n# Encrypt with no key ID (anonymous recipient)\nsafe encrypt file.txt -o file.safe -r alice --key-id-mode anonymous\n```\n\nUse `hint` or `anonymous` when you want to hide *who* can decrypt a message. The encrypted data is identical — only the metadata changes.\n\n### Password KDF\n\n| Algorithm | Flag | Use Case |\n|-----------|------|----------|\n| Argon2id | `--kdf argon2id` | Default. Memory-hard, GPU-resistant (64 MiB, 2 iterations) |\n| PBKDF2 | `--kdf pbkdf2` | Constrained environments (600,000 iterations) |\n\n```bash\nsafe encrypt file.txt -o file.safe -p \"pw\" --kdf pbkdf2\n```\n\n### Key Hash Algorithm\n\n| Algorithm | Flag | Use Case |\n|-----------|------|----------|\n| SPKI-SHA256-16 | `--key-hash spki-sha256-16` | Default. 16-byte truncated SHA-256 |\n| SPKI-TurboSHAKE256 | `--key-hash spki-turboshake256` | Alternative hash function |\n\n```bash\nsafe encrypt file.txt -o file.safe -r alice --key-hash spki-turboshake256\n```\n\n## Migration from GPG\u002FPGP\n\n```bash\n# Decrypt old GPG file, re-encrypt with SAFE\ngpg -d old-secrets.gpg | safe encrypt -o secrets.safe -r newkey\n```\n\n## Edge Cases & Tips\n\n**Empty files:** Encrypting empty files works correctly and produces valid .safe output.\n\n**Binary data:** SAFE handles all byte values (0x00-0xFF) correctly. No text encoding issues.\n\n**Unicode passwords:** Passwords are UTF-8 encoded. Multi-byte characters work correctly.\n\n**Large files:** Files are encrypted in 64KB chunks by default. Only modified chunks are re-encrypted during edits.\n\n**Block size options:** Use `--block-size` flag (16384, 32768, or 65536 bytes) to tune for your use case.\n\n## Troubleshooting\n\n**Decryption fails:**\n1. Check password\u002Fkey is correct\n2. For composable paths, ALL credentials must be provided (partial won't work)\n3. Verify file integrity: `safe info file.safe`\n4. Wrong key type? Check with `safe keyinfo mykey.key`\n5. Check available keys: `safe keys`\n\n**\"safe: command not found\":**\nRun installation steps above. Verify with `which safe`.\n\n**Composable path errors:**\n- `pwd:secret + alice.pub` requires BOTH `-p secret` AND `-k alice.key` to decrypt\n- Providing only the password or only the key will fail\n- Order of `-k` flags doesn't matter, but all must be present\n\n## Security Notes\n\n- `.key` files are secret — never share them\n- `.pub` files are safe to distribute\n- Composable paths (`+`) provide defense-in-depth\n- ML-KEM-768 protects against future quantum computers\n- Argon2id password hashing is memory-hard and GPU-resistant (64 MiB memory, 2 iterations)\n\n### Password Security\n\n**Warning:** Passwords passed via `-p` are visible in shell history and process listings.\n\nMitigations:\n```bash\n# 1. Prefix with space to skip history (bash\u002Fzsh with HISTCONTROL=ignorespace)\n safe encrypt file.txt -o file.safe -p \"secret\"\n\n# 2. Use a key file instead of password\nsafe encrypt file.txt -o file.safe -r alice\n\n# 3. Read password from environment variable (RECOMMENDED for automation)\nMY_PW=\"secret\" safe encrypt file.txt -o file.safe -p env:MY_PW\n\n# 4. Use SAFE_PASSPHRASE env var with bare -p\nexport SAFE_PASSPHRASE=\"secret\"\nsafe encrypt file.txt -o file.safe -p\n\n# 5. Read password from file (careful with permissions)\nsafe encrypt file.txt -o file.safe -p \"$(cat ~\u002F.safe\u002F.password)\"\n\n# 6. Clear history after use\nhistory -d $(history 1 | awk '{print $1}')\n```\n\n**`env:VARNAME` security:** Environment variables are visible to the current process and child processes. They're safer than command-line args (not in `\u002Fproc\u002F*\u002Fcmdline`) but still visible via `\u002Fproc\u002F*\u002Fenviron` on Linux. For maximum security, use key-based encryption.\n\n## Agent-to-Agent Encrypted Communication\n\nAgents can exchange encrypted messages across any text-based channel: email, forums, GitHub issues, Slack, shared files, etc.\n\nThe key management system makes agent-to-agent communication simple:\n- **`safe keygen`** — generates identity keys (auto-stored in `~\u002F.safe\u002F`)\n- **`safe keys add`** — imports other agents' public keys as named recipients\n- **`safe encrypt -r name`** — encrypts to any known recipient by name\n- **`safe decrypt`** — auto-discovers keys, no `-k` flag needed\n\n### First-Run Setup\n\nOn first use, check for existing keys and generate if missing:\n\n```bash\n# Check if any agent identities exist\nsafe keys 2>\u002Fdev\u002Fnull || true\n\n# Generate if missing\nif [ ! -f ~\u002F.safe\u002Fkeys\u002F*.key ]; then\n    safe keygen x25519\n    echo \"Generated new agent identity\"\n    safe keys\nfi\n```\n\nThis creates:\n- `~\u002F.safe\u002Fkeys\u002F$USER.x25519.key` — your private key (never share)\n- `~\u002F.safe\u002F$USER.x25519.pub` — your public key (share freely)\n\n### Exchanging Keys Between Agents\n\nAgents discover each other by sharing public keys. The `safe keys add` command imports keys into the recipients directory:\n\n```bash\n# Agent A: Share your public key\ncat ~\u002F.safe\u002F$USER.x25519.pub\n# Copy this to the other agent (paste, file, AGENTS.md, etc.)\n\n# Agent B: Import Agent A's public key\nsafe keys add \u002Fpath\u002Fto\u002Fagent-a.x25519.pub --name agent-a\n\n# Verify import\nsafe keys\n# Shows:\n#   Identities:\n#     nick         x25519         \u002FUsers\u002Fnick\u002F.safe\u002Fkeys\u002Fnick.x25519.key\n#   Recipients:\n#     agent-a      x25519         \u002FUsers\u002Fnick\u002F.safe\u002Frecipients\u002Fagent-a.x25519.pub\n\n# Now Agent B can encrypt to Agent A by name\nsafe encrypt message.txt -o message.safe -r agent-a\n```\n\n**Advertising your keys directory:** Agents should make their `~\u002F.safe\u002F*.pub` files discoverable. Common approaches:\n\n| Location | How |\n|----------|-----|\n| `AGENTS.md` in repo | Include PEM block in markdown |\n| `~\u002F.safe\u002F*.pub` files | Other agents on same system: `-r username` resolves `~username\u002F.safe\u002F*.pub` |\n| GitHub gist | Post PEM key, recipient imports with `curl \\| safe keys add` |\n| Forum\u002Femail signature | Include PEM block or link to public key |\n\n### Convention: Reply-To Keys\n\nTo enable replies, prepend your public key(s) to the message before encrypting:\n\n```\n-----BEGIN X25519 PUBLIC KEY-----\nfBhEEEB+CepxNQIfPtxnIhWbDUyo+Z\u002FW17cYKlCbsDg=\n-----END X25519 PUBLIC KEY-----\n\nHere is the secret data you requested...\n```\n\nWhen an agent decrypts a message and finds PEM public key blocks at the top, it saves them with `safe keys add` and encrypts the reply to that name.\n\n**Multiple reply-to keys:** If the sender wants multiple agents\u002Fidentities to decrypt the reply:\n\n```\n-----BEGIN X25519 PUBLIC KEY-----\nfBhEEEB+CepxNQIfPtxnIhWbDUyo+Z\u002FW17cYKlCbsDg=\n-----END X25519 PUBLIC KEY-----\n-----BEGIN ML-KEM-768 PUBLIC KEY-----\n\u003Cbase64...>\n-----END ML-KEM-768 PUBLIC KEY-----\n\nMessage body here...\n```\n\nThe receiving agent extracts all key blocks, imports them with `safe keys add`, and encrypts the reply to all of them.\n\n### Workflow: Send a Message\n\n```bash\n# 1. Create message with your public key as reply address\nsafe pubkey $USER > message.txt\necho \"\" >> message.txt\necho \"Here are the API credentials you requested...\" >> message.txt\n\n# 2. Encrypt to recipient (bare name from recipients dir)\nsafe encrypt message.txt -o message.safe -r recipient\n\n# 3. Share message.safe via any channel (email, forum, git, shared folder, etc.)\n```\n\n### Checking if a Message is For You\n\nBefore attempting to decrypt, check if your key ID matches any unlock block:\n\n```bash\n# Get Key IDs from the encrypted file\nsafe info message.safe\n# Output includes:\n#   UNLOCK Blocks: 2\n#   [0] hpke(kem=x25519, id=1SB5W2LJ8\u002FDNu8rn+vaGHA==)\n#   [1] hpke(kem=ml-kem-768, id=abc123...)\n\n# Get your key info\nsafe keyinfo ~\u002F.safe\u002F$USER.x25519.pub\n\n# Or just try to decrypt — auto-key discovery handles it\nsafe decrypt message.safe -o message.txt\n```\n\n**Note on key ID modes:** If the sender used `--key-id-mode hint`, you'll see `hint=XXXX` instead of a full ID. If they used `--key-id-mode anonymous`, there will be no key ID at all — you'll need to try decrypting (auto-discovery handles this).\n\n### Workflow: Receive and Reply\n\n```bash\n# 1. Decrypt the message (auto-discovers keys from ~\u002F.safe\u002Fkeys\u002F)\nsafe decrypt message.safe -o message.txt\n\n# 2. Extract reply-to keys and import them\n# Save PEM blocks to a temp file, then import:\ngrep -A2 'BEGIN.*PUBLIC KEY' message.txt > \u002Ftmp\u002Fsender.pub\nsafe keys add \u002Ftmp\u002Fsender.pub --name sender\n\n# 3. Create and encrypt reply\nsafe pubkey $USER > reply.txt\necho \"\" >> reply.txt\necho \"Thanks, here's my response...\" >> reply.txt\n\n# Encrypt to sender (bare name!)\nsafe encrypt reply.txt -o reply.safe -r sender\n```\n\n### Publishing Your Public Key\n\nShare your public key so others can send you encrypted messages:\n\n| Location | Use Case |\n|----------|----------|\n| `AGENTS.md` in repo | Project-specific agent identity |\n| GitHub profile \u002F gist | Personal agent key |\n| Forum signature | Community communication |\n| Shared team folder | Internal team use |\n| Email signature | Email-based exchange |\n\nExample `AGENTS.md`:\n\n```markdown\n## Agent Keys\n\n### Deploy Agent\n\\`\\`\\`\n-----BEGIN X25519 PUBLIC KEY-----\nfBhEEEB+CepxNQIfPtxnIhWbDUyo+Z\u002FW17cYKlCbsDg=\n-----END X25519 PUBLIC KEY-----\n\\`\\`\\`\n\nTo send encrypted data to this agent:\n\\`\\`\\`bash\n# Import the key\nsafe keys add deploy-agent.pub --name deploy\n\n# Encrypt\nsafe encrypt data.txt -o data.safe -r deploy\n\\`\\`\\`\n```\n\n### Handling Multiple Identities\n\nAgents may have different keys for different contexts:\n\n```bash\nsafe keygen x25519 -n personal     # ~\u002F.safe\u002Fkeys\u002Fpersonal.x25519.key\nsafe keygen x25519 -n work         # ~\u002F.safe\u002Fkeys\u002Fwork.x25519.key\nsafe keygen ml-kem-768 -n pq       # ~\u002F.safe\u002Fkeys\u002Fpq.ml-kem-768.key\n\n# List all\nsafe keys\n```\n\nWhen sending, choose the appropriate reply-to key for the context. When receiving, auto-discovery tries all keys in `~\u002F.safe\u002Fkeys\u002F`.\n\n### Error Handling\n\nIf decryption fails even though key ID matched:\n1. The file may be corrupted — check with `safe info file.safe`\n2. For composable paths, ALL required credentials must be provided\n3. Report the error clearly; don't silently fail\n\n### Checking All Identities\n\nWith auto-key discovery, this is usually unnecessary. But for manual checking:\n\n```bash\n# List all your identities\nsafe keys\n\n# Check message recipients\nsafe info message.safe\n\n# Just try to decrypt — auto-discovers all keys\nsafe decrypt message.safe -o message.txt\n# If successful, prints: \"safe: trying N key(s) from ~\u002F.safe\u002Fkeys\"\n```\n\n### Auto-Generate AGENTS.md\n\nWhen setting up a project for agent communication, create an AGENTS.md:\n\n```bash\n# Generate AGENTS.md for current project\ncat > AGENTS.md \u003C\u003C 'EOF'\n# Agent Keys\n\nThis project supports encrypted agent-to-agent communication using [SAFE](https:\u002F\u002Fgithub.com\u002Fgrittygrease\u002Fsafe).\n\n## Available Agents\n\n### Primary Agent\nEOF\n\n# Add the public key\necho '```' >> AGENTS.md\nsafe pubkey $USER >> AGENTS.md\necho '```' >> AGENTS.md\n\ncat >> AGENTS.md \u003C\u003C 'EOF'\n\n## How to Send Encrypted Messages\n\n1. Save the public key block above to a file and import it:\n   ```bash\n   safe keys add agent.pub --name agent\n   ```\n2. Create your message with your reply-to key:\n   ```bash\n   safe pubkey $USER > message.txt\n   echo \"\" >> message.txt\n   echo \"Your message here...\" >> message.txt\n   ```\n3. Encrypt and send:\n   ```bash\n   safe encrypt message.txt -o message.safe -r agent\n   ```\n4. Share `message.safe` via any channel (email, issue, PR, pastebin, etc.)\n\n## Verifying Messages\n\n```bash\n# Check message recipients\nsafe info message.safe\n\n# Decrypt (auto-discovers keys from ~\u002F.safe\u002Fkeys\u002F)\nsafe decrypt message.safe -o message.txt\n```\nEOF\n\necho \"Created AGENTS.md with your public key\"\n```\n\n### Sharing via Pastebin\n\nFor quick, ephemeral encrypted message sharing:\n\n```bash\n# Encrypt and post to termbin\nsafe encrypt message.txt -r recipient | nc termbin.com 9999\n# Returns URL like: https:\u002F\u002Ftermbin.com\u002Fabc123\n\n# Recipient fetches and decrypts (auto-discovers keys)\ncurl -s https:\u002F\u002Ftermbin.com\u002Fabc123 | safe decrypt\n```\n\n### Posting a Public Message (Forum\u002FMailing List)\n\nWhen posting an encrypted message publicly, include your reply-to key AND instructions:\n\n```bash\n# Create a complete public post\ncat > post.txt \u003C\u003C 'EOF'\n## Encrypted Message\n\nTo decrypt this message and reply, install the safe-encryption skill:\n\n```\nmkdir -p ~\u002F.claude\u002Fskills\ngit clone https:\u002F\u002Fgithub.com\u002Fgrittygrease\u002Fsafe-encryption-skill.git ~\u002F.claude\u002Fskills\u002Fsafe-encryption\n```\n\nThen ask your agent: \"Decrypt the message below and reply encrypted to the sender\"\n\n### My Public Key (for replies)\nEOF\n\nsafe pubkey $USER >> post.txt\n\ncat >> post.txt \u003C\u003C 'EOF'\n\n### Encrypted Message\nEOF\n\n# Encrypt your message (with your reply-to key embedded in plaintext)\nsafe pubkey $USER > message.txt\necho \"\" >> message.txt\necho \"Your actual message content here...\" >> message.txt\n\nsafe encrypt message.txt -r recipient >> post.txt\n\necho \"\" >> post.txt\ncat >> post.txt \u003C\u003C 'EOF'\n\n---\n*This message was encrypted with [SAFE](https:\u002F\u002Fgithub.com\u002Fgrittygrease\u002Fsafe)*\nEOF\n\ncat post.txt\n```\n\nThis produces a self-contained post that any agent with the skill can decrypt and reply to.\n",{"name":5,"description":7},"main","f9d3fe7cf9ac8f1ea63a0d96e98e1f510a3814db","skills\u002Fgrittygrease\u002Fsafe-encryption-skill",1,"https:\u002F\u002Fgithub.com\u002Fjavimosch\u002Fopen-claw-skills","https:\u002F\u002Fgithub.com\u002Fjavimosch","intrane.fr","Building robust, open-source infrastructure for the commons. AI-leveraged, self-hosted, built to last.","2026-06-07 03:34:58",{"source":8,"skillName":5,"commands":34,"prompt":44,"zipAvailable":45},[35,38,41],{"tool":36,"command":37},"npx","npx skills add javimosch\u002Fopen-claw-skills --skill safe-encryption",{"tool":39,"command":40},"bunx","bunx skills add javimosch\u002Fopen-claw-skills --skill safe-encryption",{"tool":42,"command":43},"pnpm","pnpm dlx skills add javimosch\u002Fopen-claw-skills --skill safe-encryption","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fjavimosch\u002Fopen-claw-skills\u002Fblob\u002Fmain\u002Fskills\u002Fgrittygrease\u002Fsafe-encryption-skill\u002FSKILL.md",true,[],[48,56,63,70,77,84],{"skillNo":49,"name":50,"nameZh":6,"description":51,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":52,"categories":53,"keywords":54,"publishedAt":55},"01M778GGXG2VQ0YF31W2MKGMQZ","crowd-prompting","A marketplace where AI agents improve prompts, system instructions, tool descriptions, and other text-based content with domain expertise from real-world operations — and earn tokens for valuable contributions.","https:\u002F\u002Fgithub.com\u002Fjavimosch\u002Fopen-claw-skills\u002Fblob\u002Fmain\u002Fskills\u002Fzzadrian\u002Fcrowd-prompting\u002FSKILL.md",[],[],"2026-11-15 14:19:17",{"skillNo":57,"name":58,"nameZh":6,"description":59,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":60,"categories":61,"keywords":62,"publishedAt":55},"01M778G7BH8SBJ9FJ6C3G7CB1K","ceaser","Interact with the Ceaser privacy protocol on Base L2 using the ceaser-mcp MCP tools. This skill uses the ceaser-mcp npm package for ALL operations -- shield, unshield, note management, and protocol queries. All ceaser tool calls use CLI subcommands (npx -y ceaser-mcp \u003Csubcommand>). Ceaser is a privacy-preserving ETH wrapper using Noir\u002FUltraHonk zero-knowledge proofs on Base L2 (chain ID 8453).","https:\u002F\u002Fgithub.com\u002Fjavimosch\u002Fopen-claw-skills\u002Fblob\u002Fmain\u002Fskills\u002Fzyra-v21\u002Fceaser\u002FSKILL.md",[],[],{"skillNo":64,"name":65,"nameZh":6,"description":66,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":67,"categories":68,"keywords":69,"publishedAt":55},"01M778FYCJQZWFKKX5FYMK3S47","ceaser-send","Fully automated private ETH transfer via Ceaser Protocol on Base L2 using the ceaser-mcp MCP tools. This skill uses the ceaser-mcp npm package for ALL operations -- all ceaser tool calls use CLI subcommands (npx -y ceaser-mcp \u003Csubcommand>). WARNING -- creates observable on-chain links between user wallet and hot wallet (see Privacy Warning). Generates an ephemeral hot wallet with BIP-39 mnemonic recovery, user funds it, agent signs and broadcasts the Shield TX automatically. Exactly one manual step required (funding the hot wallet with ETH). Uses Noir\u002FUltraHonk zero-knowledge proofs.","https:\u002F\u002Fgithub.com\u002Fjavimosch\u002Fopen-claw-skills\u002Fblob\u002Fmain\u002Fskills\u002Fzyra-v21\u002Fceaser-send\u002FSKILL.md",[],[],{"skillNo":71,"name":72,"nameZh":6,"description":73,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":74,"categories":75,"keywords":76,"publishedAt":55},"01M778FQQNSEYA3HJKZBPQ4M9Z","dilemm-ai","Compete in DilemmAI, the prisoner's dilemma AI arena at dilemm.ai. Use when an OpenClaw agent wants to create an account, design and submit strategy prompts for their bot, enter matchmaking, analyze historical matches and leaderboards, and iterate on bot strategy. Requires headless browser automation (no API available yet).","https:\u002F\u002Fgithub.com\u002Fjavimosch\u002Fopen-claw-skills\u002Fblob\u002Fmain\u002Fskills\u002Fzyori\u002Fdilemm-ai\u002FSKILL.md",[],[],{"skillNo":78,"name":79,"nameZh":6,"description":80,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":81,"categories":82,"keywords":83,"publishedAt":55},"01M778FGVZX7QA2TF9BFMM37FY","moldium","Post and manage content on the Moldium blog platform. Triggered by \"post to Moldium\", \"write a blog post\", \"publish an article\", etc.","https:\u002F\u002Fgithub.com\u002Fjavimosch\u002Fopen-claw-skills\u002Fblob\u002Fmain\u002Fskills\u002Fzyom45\u002Fmoldium\u002FSKILL.md",[],[],{"skillNo":85,"name":86,"nameZh":6,"description":87,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":88,"categories":89,"keywords":90,"publishedAt":55},"01M778F88D8PQ9MQ0KNW2TJ8ZH","arxiv-paper-reviews","Interact with arXiv Crawler API to fetch papers, read reviews, submit comments, search papers, and import papers. Use when working with arXiv papers, fetching paper lists by date\u002Fcategory\u002Finterest, viewing paper details with comments, submitting paper reviews, searching papers by title, or importing papers from arXiv URLs via API at http:\u002F\u002Fweakaccept.top:8000\u002F.","https:\u002F\u002Fgithub.com\u002Fjavimosch\u002Fopen-claw-skills\u002Fblob\u002Fmain\u002Fskills\u002Fzxrys\u002Farxiv-paper-reviews\u002FSKILL.md",[],[]]