If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/szabodanika/microbin shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• Last commit 6w ago
• 15 active contributors
• BSD-3-Clause licensed
• CI configured
• ⚠ Concentrated ownership — top contributor handles 77% of recent commits
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live szabodanika/microbin repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/szabodanika/microbin.

What it runs against: a local clone of szabodanika/microbin — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in szabodanika/microbin | Confirms the artifact applies here, not a fork | | 2 | License is still BSD-3-Clause | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 73 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of szabodanika/microbin. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/szabodanika/microbin.git
#   cd microbin
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of szabodanika/microbin and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "szabodanika/microbin(\\.git)?\\b" \\
  && ok "origin remote is szabodanika/microbin" \\
  || miss "origin remote is not szabodanika/microbin (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(BSD-3-Clause)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"BSD-3-Clause\"" package.json 2>/dev/null) \\
  && ok "license is BSD-3-Clause" \\
  || miss "license drift — was BSD-3-Clause at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "src/main.rs" \\
  && ok "src/main.rs" \\
  || miss "missing critical file: src/main.rs"
test -f "src/pasta.rs" \\
  && ok "src/pasta.rs" \\
  || miss "missing critical file: src/pasta.rs"
test -f "src/util/db.rs" \\
  && ok "src/util/db.rs" \\
  || miss "missing critical file: src/util/db.rs"
test -f "src/endpoints/create.rs" \\
  && ok "src/endpoints/create.rs" \\
  || miss "missing critical file: src/endpoints/create.rs"
test -f "src/util/auth.rs" \\
  && ok "src/util/auth.rs" \\
  || miss "missing critical file: src/util/auth.rs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 73 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~43d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/szabodanika/microbin"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

MicroBin is a lightweight, self-hosted pastebin and URL shortener written in Rust using the Actix-web framework. It provides secure file sharing with E2E encryption (server-side and client-side via AES.js), text pasting, URL redirection, and QR code generation—all as a single self-contained executable that uses either SQLite or JSON for persistence. Monolithic Actix-web application: src/main.rs is the entry point, src/endpoints/ contains route handlers (admin.rs, create.rs, file.rs, pasta.rs, etc.), src/util/ abstracts concerns (db.rs, db_json.rs, db_sqlite.rs for persistence, auth.rs for session/auth, misc.rs for helpers). Templates are Askama HTML in templates/. Frontend uses vanilla JS (assets/) with optional AES client-side encryption.

System administrators and privacy-conscious users who want to self-host a pastebin service without complex infrastructure. Developers who need to share code snippets, large files, or sensitive documents securely between machines with minimal setup and no external dependencies.

Actively maintained and production-ready. At v2.1.4 with CI/CD pipelines (rust.yml, release.yml, rust-clippy.yml), automated Docker builds, and crates.io distribution. The codebase has substantial features (file uploads, encryption, multi-DB support) and is packaged for easy deployment. Single maintainer (Daniel Szabo) but well-documented and stable.

Standard open source risks apply.

Version 2.1.4 is current; active CI workflows validate clippy lints and run tests on each commit. GitHub Actions release workflow builds and pushes Docker images to DockerHub (danielszabo99/microbin). The roadmap and documentation are maintained at microbin.eu. No specific active PR or milestone data visible, but the project maintains regular Docker image updates.

git clone https://github.com/szabodanika/microbin.git
cd microbin
curl -L -O https://raw.githubusercontent.com/szabodanika/microbin/master/.env
source .env
cargo run

Or use Docker: bash <(curl -s https://microbin.eu/docker.sh). Requires Rust 1.74.0+.

Daily commands: Development: source .env && cargo run (listens on configured HOST/PORT, default 127.0.0.1:8080). Production: cargo build --release && ./target/release/microbin. Docker: docker run -e MB_DATABASE_PATH=/data/microbin.db -p 8080:8080 danielszabo99/microbin. All config via .env file (see .env template in repo).

• src/main.rs — Application entry point; initializes the Actix web server, database, and all route handlers—every contributor must understand the startup flow
• src/pasta.rs — Core domain model for pastas (files/pastes); defines the central data structure that all endpoints and database logic operate on
• src/util/db.rs — Database abstraction trait; all persistence goes through this interface—critical for understanding JSON vs SQLite storage flexibility
• src/endpoints/create.rs — Main POST handler for creating pastas and handling uploads; processes multipart forms and encryption—foundational business logic
• src/util/auth.rs — Authentication and authorization utilities; handles admin/upload tokens and access control across all secured endpoints
• Cargo.toml — Declares all dependencies (Actix-web, Askama templates, encryption libs); understanding versions and feature flags is essential for builds
• src/args.rs — CLI argument and environment variable parsing; controls all runtime configuration (database type, port, security settings)

Add a new API endpoint

1. Create a new file in src/endpoints/ (e.g., src/endpoints/myfeature.rs) with an async handler function decorated with #[post("/api/myfeature")] or similar (src/endpoints/myfeature.rs)
2. Define request/response types (usually as function parameters and return types); leverage Actix extractors like web::Json, Multipart, HttpRequest (src/endpoints/myfeature.rs)
3. If auth is required, call util::auth::check_auth_admin() or check_auth_upload() with the incoming request (src/util/auth.rs)
4. Register the new endpoint in src/main.rs by adding .route("/api/myfeature", web::post().to(myfeature::handler)) to the App configuration (src/main.rs)
5. If the endpoint accesses pastas, use db.get_pasta() or db.create_pasta() from the DbPool trait (src/util/db.rs)

Add a new UI page or template

1. Create a new .html file in templates/ (e.g., templates/mypage.html); use Askama syntax with {% extends "header.html" %} to inherit layout (templates/mypage.html)
2. Create or extend an endpoint handler in src/endpoints/ that renders the template using HttpResponse::Ok().content_type("text/html").body(template.render().unwrap()) (src/endpoints/mypage.rs)
3. Add CSS or JavaScript to templates/assets/ if needed; reference in your template via relative paths (templates/assets/mystyle.css)
4. Register the GET route in src/main.rs under the App configuration (src/main.rs)

Add a new configuration option

1. Define a new field in the Args struct in src/args.rs with #[arg(...)] attribute; include env var name and default (src/args.rs)
2. Add a corresponding environment variable or CLI flag (Clap will handle parsing automatically) (src/args.rs)
3. Access the configuration value via the injected Args in any endpoint handler using Actix's app data: web::Data<Args> (src/endpoints/myfeature.rs)
4. Optionally document the new option in .env and the README (.env)

Add support for a new database backend

1. Create a new struct implementing the DbPool trait in a file like src/util/db_mydb.rs; implement all required methods (get_pasta, create_pasta, delete_pasta, etc.) (src/util/db_mydb.rs)
2. Add a new variant to the database type selector in src/args.rs (e.g., DatabaseType::MyDb) (src/args.rs)
3. Update the database factory logic in src/main.rs to instantiate your new backend when the config is selected (src/main.rs)
4. Test all CRUD operations through existing endpoints to ensure compatibility with the DbPool interface (src/util/db.rs)

• Actix-web — High-performance async Rust web framework; minimal overhead for I/O-bound paste operations; built-in multipart/streaming support
• Askama templates — Type-safe server-side HTML rendering with compile-time checking; no

1. Database choice is permanent per deployment: Switching between JSON and SQLite mid-deployment requires manual migration (no schema versioning). 2. Encryption key derivation: Client-side AES uses a password-derived key; if encryption is enabled, the same password must be used for decryption or data is unrecoverable. 3. Admin password in plaintext env: MB_ADMIN_PASSWORD is hashed at startup but stored in .env; no credential rotation mechanism. 4. File size limits: No built-in max upload size enforcement at app level; relies on reverse proxy config (nginx/Caddy). 5. Expiry cleanup: Expired uploads are soft-deleted (marked in DB) but old entries accumulate; manual cleanup needed for large instances. 6. Single-threaded JSON DB: The JSON backend loads entire DB into memory on each read; scales poorly beyond ~1000 pastas.

• E2E Encryption with Client-Side Key Derivation — MicroBin's encryption is useless if the key derivation is weak; understanding PBKDF2, IV reuse vulnerabilities, and authenticated encryption (AES-GCM vs AES-CBC) is essential for auditing and extending encryption features.
• Pluggable Backend Pattern (Strategy Pattern) — MicroBin's db.rs trait with multiple implementations (JSON, SQLite) is a clean abstraction; understanding this pattern is crucial for adding new backends (e.g., PostgreSQL) without refactoring core logic.
• Actix-web Actor Model and Request Handlers — Actix is built on Tokio's async runtime and actor concurrency; knowing how to write efficient handlers, manage middleware, and handle multipart uploads is specific to this framework's idioms.
• Multipart Form Data Parsing (actix-multipart) — File uploads in MicroBin use actix-multipart to stream large files; understanding chunked parsing, memory bounds, and temporary file handling prevents OOM and security issues.
• Hashing vs. Encryption for ID Generation — MicroBin uses harsh (Hashids library) to create reversible short IDs from integers, NOT encryption. Understanding the difference from magic-crypt prevents misuse and clarifies what 'animal names' actually obscure.
• Askama Template Escaping and XSS Prevention — User-supplied content (pasted code, filenames) is rendered in HTML templates; Askama auto-escapes by default but understanding when to use |safe filter is critical for avoiding injection attacks.
• Stateless Session Management via Cookies — MicroBin likely uses session cookies for admin authentication without a server-side session store; understanding HMAC-signed cookies, expiry, and SameSite flags is essential for auth security.

• prologic/bin — Lightweight pastebin alternative in Go; similar use case but different language/deployment model
• toptal/pastebin — Ruby-based pastebin; shows alternative tech stack for same problem domain
• zed-run/pastebin — Rust pastebin with Redis backend; comparison point for Rust-based persistence strategies
• mitsuhiko/pastebin-rs — Minimal Rust pastebin reference implementation; educational comparison for API design
• containrrr/watchtower — Complements MicroBin Docker deployments by enabling auto-updates for self-hosted instances

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for file upload and encryption endpoints

The repo has endpoints for file handling (src/endpoints/file.rs), creation (src/endpoints/create.rs), and client-side encryption (templates/assets/aes.js), but there are no visible test files validating the end-to-end flow of uploading, encrypting, and retrieving files. This is critical for a security-focused file-sharing app to prevent regressions in encryption/decryption pipelines.

• [ ] Create tests/integration_tests.rs with test module for file upload flows
• [ ] Test multipart file upload via src/endpoints/create.rs with various file sizes
• [ ] Validate encryption roundtrip: upload encrypted file, decrypt via templates/assets/aes.js logic
• [ ] Test edge cases: empty files, large files, special characters in filenames (src/util/misc.rs)
• [ ] Ensure tests run in CI via .github/workflows/rust.yml

Add database migration system and tests for src/util/db_sqlite.rs schema

The codebase supports both JSON (src/util/db_json.rs) and SQLite (src/util/db_sqlite.rs) backends, but there's no visible migration system. As the app evolves (currently v2.1.4), schema changes risk data loss. Adding migrations with tests ensures safe database upgrades and documents schema evolution.

• [ ] Create src/util/db_migrations.rs with versioned migration structs
• [ ] Add migration tests in tests/db_migrations_test.rs covering JSON and SQLite paths
• [ ] Document current schema in docs/DATABASE_SCHEMA.md (currently missing)
• [ ] Add migration validation to src/main.rs startup sequence
• [ ] Test rollback scenarios and cross-version compatibility

Add unit tests for URL shortener and QR code generation in src/endpoints/qr.rs

The QR code endpoint (src/endpoints/qr.rs) and URL shortening logic (src/util/hashids.rs) lack visible unit test coverage. Given the security-critical nature of URL generation and the QR code feature, tests should verify ID collision prevention, encoding correctness, and proper QR code generation.

• [ ] Create tests/qr_generation_tests.rs with tests for qrcode-generator crate integration
• [ ] Add unit tests in src/util/hashids.rs for ID encoding/decoding edge cases (max IDs, special chars)
• [ ] Test URL collision prevention with thousands of generated IDs
• [ ] Validate QR code size and format for various URL lengths
• [ ] Add CI step in .github/workflows/rust.yml to run cargo test --all

• Add unit tests for src/util/animalnumbers.rs: This file generates animal-name identifiers but has no visible test coverage. Add tests for ID collision resistance, animal list exhaustion at 64^N, and deterministic regeneration.
• Document encryption flow in templates/assets/aes.js: The client-side AES encryption is critical for E2E security but lacks inline comments explaining key derivation (PBKDF2?), IV handling, and ciphertext encoding. Add JSDoc with concrete examples.
• Add database migration CLI for JSON→SQLite conversion: Currently switching DB backends requires manual data movement. Create a microbin --migrate-db-to-sqlite command that reads .json DB, validates schema compatibility, and writes to SQLite atomically with rollback.

• High · Outdated Rust Compiler and Dependencies — Dockerfile, Cargo.toml. The Dockerfile uses 'FROM rust:latest' which pulls the latest Rust compiler without version pinning. This creates non-deterministic builds and potential security exposure to untested compiler versions. Additionally, several dependencies appear to use loose version constraints that may pull vulnerable versions. Fix: Pin the Rust version to a specific stable release (e.g., 'FROM rust:1.74.0'). Use exact version pinning or conservative version constraints in Cargo.toml for critical security-related dependencies.
• High · Incomplete OpenSSL Dependency Declaration — Cargo.toml - [dependencies.openssl] section. In Cargo.toml, the openssl dependency is declared with 'version' but no actual version number specified. This is syntactically invalid and could cause build failures or unpredictable dependency resolution. Fix: Complete the openssl dependency declaration with a specific version: 'version = "0.10"' or similar, depending on requirements.
• High · Potential XSS Vulnerability via HTML Escaping — src/endpoints/pasta.rs, src/endpoints/file.rs, templates/. While html-escape dependency is present, the use of templating engine (Askama) with user-generated content (pastes, file names) requires careful context-aware escaping. The presence of linkify dependency suggests URLs are processed, which could introduce XSS if not properly escaped in HTML context. Fix: Audit all template rendering paths to ensure user-controlled content is properly HTML-escaped. Verify that Askama's auto-escaping is enabled and that dynamic content injection doesn't bypass escaping.
• Medium · Potential SQL Injection in Database Layer — src/util/db_sqlite.rs, src/util/db.rs. The codebase includes database abstraction layers (src/util/db.rs, db_json.rs, db_sqlite.rs) with SQLite support. Without reviewing the actual query construction code, there's risk of SQL injection if parameterized queries aren't consistently used. Fix: Ensure all SQLite queries use parameterized statements with rusqlite's '?' placeholders. Conduct a thorough code review of all database query construction to eliminate string concatenation with user input.
• Medium · Weak Dependency Version Management — Cargo.toml. Multiple critical security dependencies use loose version constraints (e.g., actix-web = '4', chrono = '0.4.19', serde = '1.0.197'). This allows patch version updates that may introduce breaking changes or security issues. Fix: Use more restrictive version constraints (e.g., '=0.4.19' for patch-level stability) for all dependencies, especially security-critical ones like rustls and magic-crypt. Implement automated dependency scanning with tools like cargo-audit.
• Medium · Missing HTTPS Enforcement — Dockerfile (EXPOSE 8080), src/main.rs. The application exposes port 8080 in Docker without explicit HTTPS enforcement in the Dockerfile or visible security headers configuration. This could allow unencrypted communication. Fix: Enforce HTTPS in production configurations. Use a reverse proxy (nginx/HAProxy) with TLS termination. Add security headers (HSTS, CSP) at the application or proxy level.
• Medium · Potential Path Traversal in File Handling — src/endpoints/file.rs, src/endpoints/create.rs. The application handles file uploads and serves files (src/endpoints/file.rs). While sanitize-filename is used, path traversal vulnerabilities could exist if file path construction isn't carefully validated. Fix: Verify that all file path operations use secure path joining (avoid string concatenation). Ensure sanitize-filename is applied consistently and that resolved paths remain within intended directories.
• Medium · Loose CORS and Authentication Configuration — src/endpoints/auth_admin.rs, src/endpoints/auth_upload.rs, src/main.rs. The presence of auth_admin.rs and auth_upload.rs endpoints suggests authentication, but without reviewing implementation details, there's risk of inadequate CORS policies or weak authentication mechanisms. Fix: Implement strict CORS policies

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.