Chibisafe

Chibisafe is a lightweight, self‑hosted file transfer service written entirely in TypeScript. It exposes a RESTful API that accepts arbitrary files, photos, documents and even large media streams via chunked uploads. The service returns a short URL that can be shared publicly or embedded in other applications. Internally, Chibisafe decouples the web server from storage by supporting both local file system and Amazon S3‑compatible object stores, making it suitable for a wide range of deployment environments.

• Runtime: Node.js (v18+) with Express‑like routing powered by Fastify for low latency.
• Language: TypeScript, compiled to JavaScript with strict type checking and ESLint integration.
• Storage: Abstracted via a pluggable IStorage interface; default implementation writes to the local file system, while an S3 module allows off‑site storage on any S3‑compatible endpoint.
• Database: PostgreSQL (recommended) or SQLite for lightweight setups, accessed through Prisma ORM. The schema stores file metadata, user accounts, API keys, rate‑limit counters and configuration overrides.
• WebSocket / SSE: Optional real‑time progress updates for the UI and ShareX integrations.
• Containerization: A single Docker image exposes one port (default 3000) and mounts a volume for persistent data. The image can be run behind a reverse proxy (NGINX, Traefik) with TLS termination.

• Chunked Uploads: Splits large files into 5 MB segments, retries on failure and reassembles server‑side. This reduces memory usage and improves resilience over flaky networks.
• API Keys & Webhooks: Generate per‑user keys to automate uploads. The service can emit webhook events on upload completion, deletion or quota breach.
• User Management: Three modes—public, invite‑only and account‑based. Quota enforcement per user, rate limiting (per IP & per key), and password reset flows are built‑in.
• URL Shortener: Optional short URL generation that can be customized or disabled via the admin panel.
• Dashboard API: All configuration (max file size, accepted extensions, rate limits) is exposed through a GraphQL‑like REST API that the web UI consumes. This allows programmatic configuration in CI/CD pipelines.
• Extensibility Hooks: The core exposes lifecycle hooks (onUploadStart, onUploadComplete) that plugins can subscribe to. A simple plugin loader reads TS/JS files from a plugins directory.

Chibisafe’s minimal footprint (≈ 200 MB Docker image) makes it ideal for Raspberry Pi, VPS or cloud instances. The single‑port architecture simplifies firewall rules; all traffic passes through the reverse proxy which can handle HTTPS, HTTP/2 and load‑balancing. For horizontal scaling, each instance shares the same database and S3 bucket; uploads are idempotent thanks to deterministic file naming ({hash}-{timestamp}) and atomic move operations. Auto‑scaling can be achieved with Kubernetes deployments using a StatefulSet for the database and a Deployment for the service, with persistent volumes for local storage or an external object store.

• ShareX / S3 Uploaders: The default ShareX configuration file demonstrates how to point an external tool directly at Chibisafe’s /api/upload endpoint.
• iOS Shortcuts & Browser Extensions: The public API is CORS‑enabled, allowing web extensions and mobile shortcuts to post files directly.
• Custom Plugins: Developers can ship small TS modules that hook into upload events to perform image processing, virus scanning or metadata enrichment.
• Webhook Consumers: Any service that can consume JSON POSTs (e.g., Zapier, IFTTT) can listen to upload events for downstream automation.

The codebase follows a clean modular structure: src/server for HTTP routes, src/storage for adapters, and src/api for business logic. TypeScript interfaces are exported in a single package (@chibisafe/types) enabling third‑party SDKs. The documentation site (https://chibisafe.app) provides comprehensive guides, API references and example configuration snippets. Community support is active via Discord, where contributors discuss feature requests and troubleshooting.

1. Internal Documentation Hub – Teams can host a private instance, upload PDFs and code snippets, and share links with colleagues.
2. Developer Tooling – CI pipelines can push build artifacts to Chibisafe and embed the download link in Slack or email.
3. Personal Media Vault – Users can upload photos, videos and music with a friendly UI and share direct links via social media.
4. Educational Platforms – Instructors can distribute assignments or lecture recordings while controlling access through invite‑only mode.

• Performance: Fastify + chunked uploads keep memory usage low even for 10 GB files.
• Flexibility: The pluggable storage layer and plugin hooks let you adapt the service to any backend.
• Open Source & MIT: No licensing costs, full source visibility, and the ability to audit security.
• Zero‑Ads: Pure focus on