AgentBin - Secure Secret Sharing for Agents

Overview

AgentBin is a self-destructing, encrypted secret sharing service designed for agent-to-agent communication. Like PrivateBin but built specifically for AI agents, with agent identity, signing, and sync capabilities.

Product Vision: Enable secure, ephemeral sharing of secrets (API keys, tokens, credentials) between AI agents without requiring accounts or centralized trust.

Target Users: AI agents, SRE automation, CI/CD pipelines, multi-agent systems.

---

Success Metrics

Metric	Target	Measurement
Paste creation latency	< 100ms	P95 response time
Paste retrieval latency	< 50ms	P95 response time
Encryption overhead	< 10ms	Client-side encryption time
Storage efficiency	< 1KB per paste	Average encrypted size
Availability	99.9%	Uptime SLA
Security audit	Pass	No vulnerabilities in dependencies

---

Phase 1: Core Paste Service

Goal: Basic create/read with client-side encryption and burn-after-reading.

Step 1.1: Project Setup

Tasks:

• Create GitHub repo hyper63/agentbin
• Initialize Bun project with TypeScript
• Set up Hono API framework
• Configure ESLint, Prettier, TypeScript strict mode
• Add Jest/Vitest for testing
• Set up CI/CD with GitHub Actions

Success Criteria:

• bun run dev starts development server
• bun test runs passing test suite
• TypeScript compiles with no errors
• ESLint passes with strict rules

Files:

agentbin/
├── src/
│   ├── index.ts           # Entry point
│   ├── routes/
│   │   └── paste.ts       # Paste API routes
│   ├── lib/
│   │   ├── encryption.ts  # XChaCha20-Poly1305 encryption
│   │   └── storage.ts     # LMDB storage layer
│   └── types.ts          # TypeScript types
├── tests/
│   ├── encryption.test.ts
│   └── paste.test.ts
├── package.json
├── tsconfig.json
└── README.md

Step 1.2: Encryption Layer

Tasks:

• Install libsodium-wrappers or tweetnacl
• Implement encrypt(content: string, key?: Uint8Array): { ciphertext, nonce, key }
• Implement decrypt(ciphertext: string, nonce: string, key: Uint8Array): string
• Implement generateKey(): Uint8Array (32 bytes)
• Add base64 encoding/decoding helpers

Success Criteria:

• Encrypt/decrypt roundtrip works
• Different keys produce different ciphertexts
• Key is never included in ciphertext
• Nonce is unique per encryption
• Tests cover: empty content, large content, unicode

Example:

const { ciphertext, nonce, key } = encrypt("secret content");
const decrypted = decrypt(ciphertext, nonce, key);
assert(decrypted === "secret content");

Step 1.3: Storage Layer (LMDB)

Tasks:

• Install lmdb package
• Implement storePaste(id: string, paste: PasteRecord): Promise<void>
• Implement getPaste(id: string): Promise<PasteRecord | null>
• Implement deletePaste(id: string): Promise<void>
• Implement cleanupExpired(): Promise<number> (delete expired pastes)

Success Criteria:

• Paste can be stored and retrieved
• Expired pastes are cleaned up
• Burns after reading (delete on retrieval if flag set)
• Concurrent reads handled safely

Data Model:

interface PasteRecord {
  id: string;                    // UUID
  ciphertext: string;            // Base64 encrypted content
  nonce: string;                 // Base64 nonce
  burn_after_reading: boolean;
  expires_at: number;            // Unix timestamp
  created_at: number;
  read_at?: number;
}

Step 1.4: API Endpoints

Tasks:

• POST /api/v1/paste - Create paste
• GET /api/v1/paste/:id - Retrieve paste
• DELETE /api/v1/paste/:id - Delete paste (for cleanup)
• Add rate limiting (100 requests/minute per IP)
• Add CORS headers for browser clients

Success Criteria:

• POST returns { id, url } with decryption key in URL fragment
• GET returns paste content and deletes if burn_after_reading=true
• Expired pastes return 410 Gone
• Non-existent pastes return 404
• Rate limiting prevents abuse

API Examples:

# Create paste
curl -X POST https://bin.hyper.io/api/v1/paste \
  -H "Content-Type: application/json" \
  -d '{"ciphertext":"...","nonce":"...","burn_after_reading":true,"expires_in":3600}'
# Response: {"id":"abc123","url":"https://bin.hyper.io/abc123#key"}

# Read paste
curl https://bin.hyper.io/api/v1/paste/abc123
# Response: {"ciphertext":"...","nonce":"..."}
# (Paste deleted immediately after if burn_after_reading)

Step 1.5: Web UI (Minimal)

Tasks:

• Create simple HTML page with JavaScript encryption
• Add paste creation form (textarea, burn checkbox, expiry dropdown)
• Add paste retrieval page (parse URL fragment for key)
• Client-side decryption using libsodium.js
• Dark mode, mobile-friendly

Success Criteria:

• User can paste content and get shareable link
• Recipient can open link and see decrypted content
• Content is never sent to server in plaintext
• UI works on mobile browsers

Files:

src/
├── public/
│   ├── index.html      # Create paste page
│   ├── paste.html      # View paste page
│   └── js/
│       └── app.ts     # Client-side encryption

---

Phase 2: Agent Identity

Goal: Add agent signing and verification for trusted communication.

Step 2.1: Key Generation

Tasks:

• Implement generateKeyPair(): { publicKey, privateKey }
• Use Ed25519 for signing
• Implement encodePublicKey(key): string (base64 or multibase)
• Implement decodePublicKey(encoded): Uint8Array
• Add DID format: did:agent:<base64-public-key>

Success Criteria:

• Key generation produces valid Ed25519 key pair
• Public key can be encoded/decoded
• DID format is valid and parseable

Example:

const { publicKey, privateKey } = generateKeyPair();
const did = encodePublicKey(publicKey);
// did:agent:z6MkhaXgBVZG... (multibase encoded)

Step 2.2: Paste Signing

Tasks:

• Add author_did and author_signature to PasteRecord
• Implement signPaste(paste: Paste, privateKey: Uint8Array): string
• Implement verifyPasteSignature(paste: Paste): boolean
• Add signature to API request body

Success Criteria:

• Signed paste includes author DID
• Signature verification succeeds
• Tampered paste fails verification
• Unsigned pastes still supported (optional field)

Step 2.3: Read Receipts

Tasks:

• Add read_at and read_receipt to PasteRecord
• Implement POST /api/v1/paste/:id/read-receipt
• Include reader DID and timestamp in receipt
• Store read receipt with paste

Success Criteria:

• Read receipt is signed by reading agent
• Author can verify who read their paste
• Read receipts are optional but verifiable

---

Phase 3: Recipient Allowlist

Goal: Encrypt for specific agents using their public keys.

Step 3.1: Sealed Boxes

Tasks:

• Implement encryptForRecipients(content: string, recipients: string[]): EncryptedPaste
• Use NaCl sealed boxes (libsodium)
• Store recipients array in paste metadata
• Only listed recipients can decrypt

Success Criteria:

• Paste encrypted for multiple recipients
• Each recipient gets unique sealed box
• Non-recipients cannot decrypt
• Key derivation from recipient's public key

Step 3.2: Recipient Verification

Tasks:

• Add GET /api/v1/paste/:id/verify/:did endpoint
• Check if DID is in recipient list
• Return 403 if not authorized
• Add decryption endpoint that checks recipient

Success Criteria:

• Unauthorized recipients get 403 Forbidden
• Authorized recipients can decrypt
• Burn-after-reading still works

---

Phase 4: Sync & Pub/Sub

Goal: Real-time notifications and persistent storage sync.

Step 4.1: PostgreSQL Sync

Tasks:

• Add PostgreSQL connection (using Bun's native client or pg)
• Implement syncPaste(paste: PasteRecord): Promise<void>
• Sync LMDB writes to PostgreSQL
• Add migration for pastes table
• Index on expires_at for efficient cleanup

Success Criteria:

• All pastes stored in both LMDB and PostgreSQL
• LMDB used for fast reads
• PostgreSQL used for queries and persistence
• Graceful degradation if PostgreSQL is down

Step 4.2: WebSocket Pub/Sub

Tasks:

• Implement WS /api/v1/subscribe/:agent_did
• Subscribe to paste events for specific agent
• Events: paste_created, paste_read, paste_expired
• Add heartbeat for connection keep-alive

Success Criteria:

• WebSocket connection established successfully
• Events delivered in real-time
• Reconnection handled gracefully
• Multiple subscriptions per agent supported

Step 4.3: Event Types

Tasks:

• Define event schemas (JSON)
• paste_created: When paste is created for agent
• paste_read: When paste is read (with read receipt)
• paste_expired: When paste expires
• Add optional webhook callback per agent

Success Criteria:

• Events have consistent schema
• Events are signed by server
• Webhooks delivered with retry logic

---

Phase 5: Hyper Integration

Goal: Deploy on Hyper.io infrastructure.

Step 5.1: Durable Objects

Tasks:

• Create Durable Object for paste storage
• Implement in-memory caching
• Add replication for high availability
• Configure limits (max pastes per agent, max size)

Success Criteria:

• Durable Object stores pastes persistently
• In-memory cache improves read performance
• Replication survives DO restarts

Step 5.2: D1 Database

Tasks:

• Configure D1 for PostgreSQL sync
• Add migrations to D1
• Query optimization for paste lookup
• Add indexes for recipient lookups

Success Criteria:

• D1 handles all PostgreSQL queries
• Query latency < 10ms P95
• Migrations run automatically on deploy

Step 5.3: Cloudflare Workers

Tasks:

• Deploy API to Cloudflare Workers
• Configure edge caching for static assets
• Add rate limiting at edge
• Configure custom domain (bin.hyper.io)

Success Criteria:

• API accessible from bin.hyper.io
• Edge caching reduces latency
• Rate limiting prevents abuse
• SSL certificate valid

Step 5.4: CLI Tool

Tasks:

• Create agentbin CLI tool
• agentbin create [content] - Create paste from stdin
• agentbin read [url] - Read and decrypt paste
• agentbin keygen - Generate key pair
• agentbin sign [id] - Sign a paste
• agentbin subscribe [did] - Subscribe to events

Success Criteria:

• CLI works on macOS, Linux, Windows
• Installable via bun install -g agentbin
• All API features accessible from CLI

---

Phase 6: Security & Audit

Goal: Production-ready security posture.

Step 6.1: Security Audit

Tasks:

• Run npm audit and fix vulnerabilities
• Add security headers (CSP, HSTS, etc.)
• Add request validation with Zod
• Add input sanitization
• Add rate limiting per agent DID

Success Criteria:

• No high/critical vulnerabilities
• Security headers present in all responses
• Input validation prevents injection attacks
• Rate limiting prevents DoS

Step 6.2: Audit Trail

Tasks:

• Log all paste creations, reads, deletions
• Include actor DID, timestamp, IP (hashed)
• Store logs in PostgreSQL (append-only)
• Add GET /api/v1/audit/:paste_id for authors

Success Criteria:

• All actions logged
• Logs immutable (append-only)
• Author can view audit trail for their pastes

Step 6.3: Penetration Testing

Tasks:

• Test for timing attacks on encryption
• Test for side-channel leaks
• Test for ID enumeration
• Test for replay attacks
• Add security.txt and /.well-known/security.txt

Success Criteria:

• No timing leaks in encryption
• No side-channel vulnerabilities
• ID enumeration mitigated
• Replay attacks prevented

---

Dependencies

Package	Purpose	Version
hono	API framework	^4.0.0
libsodium-wrappers	Encryption	^0.7.0
lmdb	Storage	^2.5.0
pg	PostgreSQL client	^8.11.0
zod	Validation	^3.23.0
uuid	ID generation	^9.0.0

---

Timeline

Phase	Duration	Milestone
Phase 1	2 weeks	Core paste service working
Phase 2	2 weeks	Agent signing and verification
Phase 3	1 week	Recipient allowlist
Phase 4	2 weeks	PostgreSQL sync + Pub/Sub
Phase 5	2 weeks	Hyper.io deployment
Phase 6	1 week	Security audit
Total	10 weeks	Production-ready AgentBin

---

Risk Mitigation

Risk	Mitigation
Key management complexity	Use DID format, auto-generate keys
Storage growth	Strict expiry limits, automatic cleanup
Performance bottleneck	LMDB for hot path, PostgreSQL for sync
Security vulnerabilities	Regular audits, dependency updates
Scaling issues	Edge deployment, stateless design

---

Success Criteria (Overall)

• Agent can create encrypted paste and share URL
• Recipient can decrypt paste without server knowing content
• Paste burns after reading (if enabled)
• Paste expires after time limit
• Author can sign paste with agent identity
• Author can restrict to specific recipients
• Author receives read receipt when paste is read
• All operations logged for audit
• API latency < 100ms P95
• Zero security vulnerabilities in dependencies
• Deployed on bin.hyper.io

---

Next Steps

1. Create GitHub repo: hyper63/agentbin
2. Initialize project with bun init
3. Set up CI/CD with GitHub Actions
4. Implement Phase 1.1 (Project Setup)
5. Continue through phases sequentially

---

This plan is designed to be handed to a coding agent for implementation.