BaseMail - Onchain Email for AI Agents on Base

📬 BaseMail - Onchain Email for AI Agents on Base. Get [e-mail] linked to your Basename (.base.eth). SIWE wallet auth, no CAPTCHA, no passwords....

Security Scan

The skill's requirements, code, and instructions are coherent with its stated purpose (on‑chain email using a Base wallet) — nothing appears designed to do unrelated or hidden actions, though there are minor bugs and usability/security concerns to be aware of.

Purpose & Capability

Name/description (onchain email tied to a Base wallet) aligns with required binary (node), primary env var (BASEMAIL_PRIVATE_KEY), network calls to api.basemail.ai, and included scripts (register, send, inbox). Requiring a wallet private key is expected for SIWE signing during registration.

Instruction Scope

SKILL.md and scripts stay within the expected scope: get a private key (env, file, or managed), sign SIWE messages, call the service API, store an auth token under ~/.basemail/. The scripts explicitly validate wallet paths and key format and avoid scanning unrelated files. Note: the setup script prints the mnemonic to stdout once (documented) — this is expected for creating a recoverable wallet but is a security-sensitive action the user should handle carefully.

Install Mechanism

There is no high-risk remote install URL; dependencies are standard Node packages (ethers and its dependencies) described in package.json/package-lock.json. SKILL.md metadata references an npm install step (ethers), which is proportionate.

Credentials

Only one required environment variable (BASEMAIL_PRIVATE_KEY) is declared and used as the primary credential, which matches the skill's need to sign SIWE messages. Optional variables (BASEMAIL_PASSWORD, BASEMAIL_TOKEN) are documented. This is proportionate, but supplying any private key grants the skill the ability to sign messages with that key — the user should only provide a wallet they trust for this purpose.

Persistence & Privilege

always:false and the skill stores data only under ~/.basemail (token.json, encrypted key file, audit.log). It does not request system-wide privileges or modify other skills. Token and encrypted key are saved with restrictive file modes in code (0o600/0o700).

Assessment

This skill is internally consistent for providing on‑chain email tied to a Base wallet, but it needs your private key (or it will create/manage one). Before installing, consider: 1) only provide a wallet private key you control and are willing to let the skill sign messages for (prefer a dedicated wallet with minimal funds); 2) prefer using the env var method or a managed ephemeral wallet and back up any mnemonic printed by setup.js securely offline; 3) the skill stores an auth token and optionally an encrypted private key under ~/.basemail — inspect or clean that directory if you stop using the skill; 4) there are minor coding issues (e.g., an undefined isEncrypt variable in setup.js) indicating the code may be lightly tested — review/ run in an isolated environment before granting access to a high‑value wallet.

Your agent gets a real email address, linked to its onchain identity. No human needed.

TL;DR: Own a Basename (yourname.base.eth)? Get [e-mail] instantly. Sign with your Base wallet, send emails autonomously.

Why BaseMail?

• Built on Base Chain — Email identity tied to your onchain wallet on Base (Coinbase's L2)
• Basename integration — .base.eth holders get matching @basemail.ai addresses automatically
• SIWE authentication — Sign-In with Ethereum, no passwords or CAPTCHA needed
• Autonomous for AI agents — Register for services, submit forms, receive confirmations without human help
• Verifiable identity — Your email is cryptographically linked to your Base wallet address

BaseMail gives AI agents verifiable email identities on Base Chain:

• ✨ Basename holders → yourname.base.eth → [e-mail]
• 🔗 Any Base wallet → [e-mail]

How it works

Base Wallet → SIWE Signature → BaseMail Registration → [e-mail]
     ↑                                                        ↓
Basename (.base.eth)                              Send & receive email autonomously

---

🔐 Wallet Setup (Choose One)

Option A: Environment Variable (Recommended ✅)

If you already have a wallet, just set the env var — no private key stored to file:

export BASEMAIL_PRIVATE_KEY="0x..."
node scripts/register.js

✅ Safest method: private key exists only in memory.

---

Option B: Specify Wallet Path

Point to your existing private key file:

node scripts/register.js --wallet /path/to/your/private-key

✅ Uses your existing wallet, no copying.

---

Option C: Managed Mode (Beginners)

Let the skill generate and manage a wallet for you:

node scripts/setup.js --managed
node scripts/register.js

✅ Always encrypted — Private key protected with AES-256-GCM

• You'll set a password during setup (min 8 chars, must include letter + number)
• Password required each time you use the wallet
• Mnemonic displayed once for manual backup (never saved to file)
• Password input is masked (hidden) in terminal

---

⚠️ Security Guidelines

1. Never commit private keys to git
2. Never share private keys or mnemonics publicly
3. Never add ~/.basemail/ to version control
4. Private key files should be chmod 600 (owner read/write only)
5. Prefer environment variables (Option A) over file storage
6. --wallet paths are validated: must be under $HOME, no traversal, max 1KB file size
7. Private key format is validated (0x + 64 hex chars) before use
8. Password input is masked in terminal (characters hidden)
9. This skill only signs SIWE authentication messages — it never sends funds or on-chain transactions

Recommended .gitignore

# BaseMail - NEVER commit!
.basemail/
**/private-key.enc

---

🚀 Quick Start

1️⃣ Register

# Using environment variable
export BASEMAIL_PRIVATE_KEY="0x..."
node scripts/register.js

# Or with Basename
node scripts/register.js --basename yourname.base.eth

2️⃣ Send Email

node scripts/send.js "[e-mail]" "Hello!" "Nice to meet you 🦞"

3️⃣ Check Inbox

node scripts/inbox.js              # List emails
node scripts/inbox.js <email_id>   # Read specific email

---

📦 Scripts

Script	Purpose	Needs Private Key
setup.js	Show help	❌
setup.js --managed	Generate wallet (always encrypted)	❌
register.js	Register email address	✅
send.js	Send email	❌ (uses token)
inbox.js	Check inbox	❌ (uses token)
audit.js	View audit log	❌

---

📍 File Locations

~/.basemail/
├── private-key.enc   # Encrypted private key (AES-256-GCM, chmod 600)
├── wallet.json       # Wallet info (public address only)
├── token.json        # Auth token (chmod 600)
└── audit.log         # Operation log (no sensitive data)

---

🎨 Get a Basename-Linked Email

Want [e-mail] instead of [e-mail]?

1. Register a Basename (.base.eth) at https://www.base.org/names
2. Link it: node scripts/register.js --basename yourname.base.eth

Your Basename is your onchain identity on Base — and BaseMail turns it into a working email address.

---

🔧 API Reference

Endpoint	Method	Purpose
/api/auth/start	POST	Start SIWE auth
/api/auth/verify	POST	Verify wallet signature
/api/register	POST	Register email
/api/register/upgrade	PUT	Upgrade to Basename
/api/send	POST	Send email
/api/inbox	GET	List inbox
/api/inbox/:id	GET	Read email content

Full docs: https://api.basemail.ai/api/docs

---

🌐 Links

• Website: https://basemail.ai
• API: https://api.basemail.ai
• API Docs: https://api.basemail.ai/api/docs
• Get a Basename: https://www.base.org/names
• Base Chain: https://base.org
• Source: https://github.com/dAAAb/BaseMail-Skill

---

📝 Changelog

v1.8.0 (2026-02-18)

• 📝 Enhanced description: emphasize Base Chain and Basename (.base.eth) integration
• 📝 Added architecture diagram showing wallet → SIWE → email flow
• 📝 Better explanation of onchain identity and verifiable email
• 🔗 Added source repo and Base Chain links

v1.7.0 (2026-02-18)

• 🔐 Security hardening (addresses ClawHub "Suspicious" classification):
  • Added OpenClaw metadata: declares BASEMAIL_PRIVATE_KEY in requires.env
  • Password input now masked in terminal (characters hidden as *)
  • Stronger password requirements: min 8 chars, must include letter + number
  • --wallet path validation: must be under $HOME, no .. traversal, max 1KB, regular file only
  • Private key format validation (0x + 64 hex chars) on all input sources
  • Removed --no-encrypt option — managed wallets are always encrypted
  • Mnemonic is displayed once and never saved to file (removed save-to-file prompt)
  • Removed legacy plaintext key file references
• 📝 Added notes in metadata clarifying: this skill only signs SIWE messages, never sends funds
• 📝 Updated security guidelines and file locations documentation

v1.4.0 (2026-02-08)

• ✨ Better branding and descriptions
• 📝 Full English documentation

v1.1.0 (2026-02-08)

• 🔐 Security: opt-in private key storage
• ✨ Support env var, path, auto-detect
• 🔒 Encrypted storage option (--encrypt)
• 📊 Audit logging

v1.6.0 (Security Update)

• 🔐 Breaking: --managed now encrypts by default
• 🔐 Removed auto-detection of external wallet paths (security improvement)
• 🔐 Mnemonic no longer auto-saved; displayed once for manual backup
• 📝 Updated documentation for clarity

v1.0.0

• 🎉 Initial release