{"id":44488455,"url":"https://github.com/deadsec-security/family-vault","last_synced_at":"2026-02-22T08:01:33.063Z","repository":{"id":338106170,"uuid":"1155001613","full_name":"DEADSEC-SECURITY/family-vault","owner":"DEADSEC-SECURITY","description":"A self-hosted family vault for securely managing IDs, insurance, business documents, and important records. AES-256-GCM encrypted. Docker-ready.","archived":false,"fork":false,"pushed_at":"2026-02-13T00:57:04.000Z","size":1724,"stargazers_count":11,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-02-13T05:31:14.969Z","etag":null,"topics":["aes-256","docker","document-management","encryption","family","fastapi","insurance","nextjs","personal-finance","postgresql","privacy","python","self-hosted","typescript"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DEADSEC-SECURITY.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-11T02:28:27.000Z","updated_at":"2026-02-13T05:15:49.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/DEADSEC-SECURITY/family-vault","commit_stats":null,"previous_names":["deadsec-security/family-vault"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/DEADSEC-SECURITY/family-vault","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DEADSEC-SECURITY%2Ffamily-vault","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DEADSEC-SECURITY%2Ffamily-vault/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DEADSEC-SECURITY%2Ffamily-vault/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DEADSEC-SECURITY%2Ffamily-vault/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DEADSEC-SECURITY","download_url":"https://codeload.github.com/DEADSEC-SECURITY/family-vault/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DEADSEC-SECURITY%2Ffamily-vault/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29706572,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-22T05:59:28.568Z","status":"ssl_error","status_checked_at":"2026-02-22T05:58:46.208Z","response_time":110,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aes-256","docker","document-management","encryption","family","fastapi","insurance","nextjs","personal-finance","postgresql","privacy","python","self-hosted","typescript"],"created_at":"2026-02-13T02:21:43.058Z","updated_at":"2026-02-22T08:01:33.051Z","avatar_url":"https://github.com/DEADSEC-SECURITY.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Family Vault\n\n\u003e A self-hostable \"Family Operating System\" for securely managing IDs, insurance, business documents, and important family information.\n\n[![Docker](https://img.shields.io/badge/Docker-Ready-blue)](https://hub.docker.com/r/elgon2003/family-vault)\n[![License: BSL 1.1](https://img.shields.io/badge/License-BSL%201.1-orange.svg)](LICENSE)\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/screenshots/dashboard.png\" alt=\"Family Vault Dashboard\" width=\"800\"\u003e\n\u003c/p\u003e\n\n## Overview\n\nFamily Vault is a secure, self-hosted digital vault that helps families organize and manage their important documents and information in one centralized place. Think of it as your family's personal operating system for managing IDs, insurance policies, business documents, and more.\n\n### Key Features\n\n- **📇 Digital ID Management** - Driver's licenses, passports, visas, social security cards, birth certificates\n- **🏥 Insurance Tracking** - Health, auto, home, and life insurance with coverage details and reminders\n- **💼 Business Documents** - LLCs, corporations, licenses, tax documents\n- **🔔 Smart Reminders** - Automatic expiration tracking and custom reminder system with email notifications\n- **🔐 Zero-Knowledge Encryption** - Client-side AES-256-GCM encryption; server never sees plaintext\n- **👥 Multi-User Organizations** - Share access with family members with role-based permissions\n- **🌍 Visa Management** - Track visas with automatic country-specific help contact information\n- **📎 File Attachments** - Securely store card images and documents with built-in image editing\n- **🔍 Powerful Search** - Find anything across all your items instantly\n\n## Quick Start\n\n### Prerequisites\n\n- [Docker](https://www.docker.com/get-started) and Docker Compose\n- 2GB RAM minimum (4GB recommended)\n- 10GB disk space for data storage\n\n### Option A: Docker Hub (Fastest)\n\nPre-built images are available on [Docker Hub](https://hub.docker.com/r/elgon2003/family-vault):\n\n```bash\n# Download the compose file and env template\ncurl -LO https://raw.githubusercontent.com/DEADSEC-SECURITY/family-vault/master/docker-compose.yml\ncurl -LO https://raw.githubusercontent.com/DEADSEC-SECURITY/family-vault/master/.env.example\ncp .env.example .env\n# Edit .env and set SECRET_KEY (run: openssl rand -hex 32)\n# Optionally set API_URL if the backend isn't on localhost\ndocker-compose up -d\n```\n\nThe frontend image supports runtime API URL configuration via the `API_URL` environment variable. Set it in `.env` to point to your backend (e.g., `API_URL=http://192.168.1.10:8000/api` for a NAS deployment).\n\n### Option B: Build from Source\n\n1. **Clone the repository**\n   ```bash\n   git clone https://github.com/DEADSEC-SECURITY/family-vault.git\n   cd family-vault\n   ```\n\n2. **Configure environment variables**\n   ```bash\n   cp .env.example .env\n   # Edit .env and change SECRET_KEY and any other settings\n   ```\n\n3. **Start the application**\n   ```bash\n   docker-compose -f docker-compose.dev.yml up -d\n   ```\n\n4. **Access Family Vault**\n   - Open your browser to `http://localhost:3000`\n   - Register a new account (first user becomes the organization owner)\n\nThat's it! Your Family Vault is now running locally.\n\n## Architecture\n\nFamily Vault consists of four main services:\n\n- **Frontend** - Next.js 16 with React, TypeScript, and Tailwind CSS\n- **Backend** - Python FastAPI with SQLAlchemy 2.0\n- **Database** - PostgreSQL 17\n- **File Storage** - MinIO (S3-compatible object storage)\n\nAll services run in Docker containers and can be easily deployed together or scaled independently.\n\n## Tech Stack\n\n| Component | Technology |\n|-----------|-----------|\n| Frontend Framework | Next.js 16 (App Router) |\n| UI Components | shadcn/ui + Tailwind CSS |\n| Backend API | Python FastAPI |\n| Database | PostgreSQL 17 |\n| ORM | SQLAlchemy 2.0 |\n| Migrations | Alembic |\n| File Storage | MinIO (S3-compatible) |\n| Authentication | Zero-knowledge (PBKDF2 + bcrypt) |\n| Encryption | Client-side AES-256-GCM + RSA-OAEP key wrapping |\n| Email | SMTP (optional, for reminders) |\n\n## Configuration\n\n### Environment Variables\n\nCopy `.env.example` to `.env` and customize:\n\n```bash\n# Database\nPOSTGRES_DB=familyvault\nPOSTGRES_USER=familyvault\nPOSTGRES_PASSWORD=change_me_in_production\n\n# MinIO (S3)\nS3_ACCESS_KEY=minioadmin\nS3_SECRET_KEY=change_me_in_production\nS3_BUCKET=familyvault\n\n# Backend\nSECRET_KEY=change_me_to_a_long_random_string\nCORS_ORIGINS=[\"http://localhost:3000\"]\n\n# Optional: Email for reminder notifications\nSMTP_HOST=smtp.gmail.com\nSMTP_PORT=587\nSMTP_USER=your_email@gmail.com\nSMTP_PASSWORD=your_app_password\nSMTP_FROM=noreply@familyvault.local\n```\n\n### Using External Services\n\nFamily Vault can use external PostgreSQL and S3-compatible storage:\n\n```bash\n# Use external PostgreSQL\nPOSTGRES_HOST=mydb.example.com\nPOSTGRES_PORT=5432\n\n# Use AWS S3 instead of MinIO\nS3_ENDPOINT_URL=https://s3.amazonaws.com\nS3_ACCESS_KEY=your_aws_access_key\nS3_SECRET_KEY=your_aws_secret_key\nS3_REGION=us-east-1\n```\n\nThen remove the `postgres` and `minio` services from `docker-compose.yml`.\n\n## Security\n\n### Zero-Knowledge Architecture\n\nFamily Vault is designed so the server **never** sees your plaintext data. All encryption and decryption happens client-side in the browser using the [Web Crypto API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API). A fully compromised server — database dump, file storage, and application code — reveals nothing but encrypted blobs.\n\n### Key Hierarchy\n\n```\nMaster Password\n│\n├─► PBKDF2 (600,000 iterations, salt = email)\n│   └─► Master Key (256-bit)\n│       ├─► HKDF (\"enc\") ──► Symmetric Key ── encrypts your RSA private key\n│       ├─► HKDF (\"mac\") ──► MAC Key (reserved for future integrity checks)\n│       └─► PBKDF2 (1 iteration) ──► Master Password Hash ── sent to server\n│\n├─► Per-User RSA-OAEP 2048-bit Keypair\n│   ├─► Public key: stored plaintext on server\n│   └─► Private key: AES-256-GCM encrypted with Symmetric Key, stored on server\n│\n└─► Organization Key (AES-256-GCM, 256-bit)\n    └─► Wrapped per-member with their RSA public key ── stored in org_member_keys\n```\n\n**What the server stores**: encrypted private keys, public keys, encrypted org keys, and encrypted data blobs. **What the server never sees**: your master password, master key, symmetric key, plaintext private key, plaintext org key, or any plaintext item/file data.\n\n### How Data Is Protected\n\n| Data | Encryption | Where |\n|------|-----------|-------|\n| Item fields (names, IDs, policy numbers) | AES-256-GCM with org key | Encrypted in browser, ciphertext stored in DB |\n| File attachments (card images, documents) | AES-256-GCM with org key (unique IV per file) | Encrypted in browser, ciphertext stored in MinIO |\n| User's RSA private key | AES-256-GCM with user's symmetric key | Encrypted blob stored in DB |\n| Org key (per member) | RSA-OAEP wrapped with member's public key | Wrapped blob stored in DB |\n| Master password | PBKDF2 → hash-of-hash → bcrypt | Only bcrypt hash stored in DB |\n\n### Multi-User Key Sharing\n\nWhen a new member joins an organization:\n\n1. New member generates their RSA keypair on registration\n2. An existing member fetches the new member's public key\n3. Existing member unwraps the org key with their own private key, then re-wraps it with the new member's public key\n4. The newly wrapped org key is stored — the new member can now decrypt all org data\n\nNo plaintext keys ever transit the server during this ceremony.\n\n### Authentication Flow\n\n```\nBrowser                                          Server\n  │                                                 │\n  ├─ GET /prelogin?email=...  ─────────────────────►│\n  │◄──────────────────── { kdf_iterations: 600000 } │\n  │                                                 │\n  │  derive masterKey = PBKDF2(password, email)     │\n  │  derive masterPasswordHash = PBKDF2(masterKey)  │\n  │                                                 │\n  ├─ POST /login { masterPasswordHash } ───────────►│\n  │                                       bcrypt ── │ ── verify\n  │◄──── { token, encrypted_private_key, pub_key }  │\n  │                                                 │\n  │  decrypt private key with symmetric key         │\n  │  unwrap org key with private key                │\n  │  store keys in memory only (never to disk)      │\n  │                                                 │\n  ├─ GET /items (Authorization: Bearer token) ─────►│\n  │◄──────────────────────── { encrypted fields }   │\n  │  decrypt fields in browser with org key         │\n```\n\n- The server only receives a **hash-of-hash** — never your password or master key\n- Password verification uses **bcrypt** on the master password hash\n- Session tokens are **opaque 256-bit random values**, expiring after 72 hours\n- Keys are held **in memory only** — closing the browser tab wipes them\n\n### Recovery Key\n\nOn registration, a 24-word recovery key is generated and shown once. This key independently encrypts a copy of your RSA private key. If you forget your master password, the recovery key can restore access to your data. **Store it offline** — if both are lost, your data is unrecoverable by design.\n\n### Best Practices\n\n1. **Change the SECRET_KEY** - Use a long random string (`openssl rand -hex 32`)\n2. **Use strong passwords** - The master password protects all your data\n3. **Save your recovery key** - Write it down and store it physically; it cannot be regenerated\n4. **Enable HTTPS** - Use a reverse proxy (nginx, Caddy) with SSL certificates\n5. **Regular backups** - Back up PostgreSQL database and MinIO data regularly\n6. **Keep updated** - Pull the latest Docker images regularly for security patches\n\n## Features in Detail\n\n### Family IDs\n\nManage all your family's identification documents:\n- Driver's Licenses\n- Passports\n- Visas (with passport linking and automatic country contact info)\n- Social Security Cards\n- Birth Certificates\n- Custom ID Types\n\nEach ID card displays with a specialized layout and automatic security number masking.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/screenshots/ids.png\" alt=\"Family IDs\" width=\"800\"\u003e\n\u003c/p\u003e\n\n### Insurance\n\nTrack all insurance policies with comprehensive coverage details:\n- **Health Insurance** - Plan limits, copays, coinsurance, in-network providers\n- **Auto Insurance** - Link vehicles, track coverage types and limits\n- **Home Insurance** - Property coverage and liability details\n- **Life Insurance** - Beneficiaries and policy details\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/screenshots/insurance.png\" alt=\"Insurance Tracking\" width=\"800\"\u003e\n\u003c/p\u003e\n\n### Business Documents\n\nManage your business entities, licenses, and commercial insurance:\n- LLCs, Corporations, Partnerships, Sole Proprietorships\n- Business licenses and permits with expiration tracking\n- General liability, professional liability, workers' comp, and more\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/screenshots/business.png\" alt=\"Business Documents\" width=\"800\"\u003e\n\u003c/p\u003e\n\n### Reminders\n\nNever miss an expiration date:\n- **Auto-detected Reminders** - Automatically tracks expiration dates from your items\n- **Custom Reminders** - Set manual reminders for any item\n- **Email Notifications** - Optional hourly check sends emails when reminders are due\n- **Repeating Reminders** - Set reminders to repeat annually\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/screenshots/reminders.png\" alt=\"Smart Reminders\" width=\"800\"\u003e\n\u003c/p\u003e\n\n### Item Detail \u0026 File Management\n\nEach item has a full detail view with editable fields, file upload slots, linked contacts, people, and reminders.\n\n- **Drag \u0026 Drop Upload** - Easy file attachment\n- **Image Editor** - Built-in crop and rotate for card images\n- **Auto-orientation** - Portrait images automatically rotate to landscape\n- **Multiple File Slots** - Front/back of cards, policy documents, etc.\n- **Secure Download** - Files are decrypted on-the-fly when you download\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/screenshots/item-detail.png\" alt=\"Item Detail View\" width=\"800\"\u003e\n\u003c/p\u003e\n\n## Development\n\n### Prerequisites\n\n- Node.js 20+\n- Python 3.12+\n- Docker and Docker Compose\n\n### Local Development Setup\n\n1. **Backend**\n   ```bash\n   cd backend\n   python -m venv venv\n   source venv/bin/activate  # On Windows: venv\\Scripts\\activate\n   pip install -r requirements.txt\n\n   # Run migrations\n   alembic upgrade head\n\n   # Start dev server\n   uvicorn app.main:app --reload\n   ```\n\n2. **Frontend**\n   ```bash\n   cd frontend\n   npm install\n   npm run dev\n   ```\n\n3. **Database \u0026 MinIO**\n   ```bash\n   docker-compose up postgres minio\n   ```\n\n### Running Tests\n\n```bash\n# Backend tests\ncd backend\npytest\n\n# Frontend tests\ncd frontend\nnpm test\n```\n\n## Deployment\n\n### Docker Compose (Recommended)\n\nSee Quick Start section above. For production:\n\n1. Use a reverse proxy (nginx/Caddy) with SSL\n2. Change all default passwords and keys\n3. Set up regular backups\n4. Enable SMTP for email notifications\n\n### Manual Deployment\n\nSee [DEPLOYMENT.md](docs/DEPLOYMENT.md) for detailed deployment instructions for various platforms (AWS, Google Cloud, DigitalOcean, etc.).\n\n## Contributing\n\nWe welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.\n\n### Development Workflow\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Make your changes\n4. Write or update tests\n5. Commit your changes (`git commit -m 'Add amazing feature'`)\n6. Push to the branch (`git push origin feature/amazing-feature`)\n7. Open a Pull Request\n\n## Roadmap\n\n- [ ] Mobile apps (iOS/Android)\n- [ ] Document OCR for automatic field extraction\n- [ ] Shared item permissions (granular access control)\n- [x] Audit log for all changes\n- [ ] Export/import functionality\n- [ ] Two-factor authentication\n- [ ] API key authentication for automation\n- [ ] Webhook integrations\n\n## License\n\nThis project is licensed under the **Business Source License 1.1** (BSL 1.1).\n\n- **Personal / non-commercial use**: Free, no restrictions\n- **Commercial use**: Requires a commercial license — [contact us](https://github.com/DEADSEC-SECURITY/family-vault/issues)\n- **Change Date**: February 12, 2030 — on this date, the code automatically converts to **GPL v2.0** (fully open-source)\n\nSee the [LICENSE](LICENSE) file for full details.\n\n## Support\n\n- **Documentation**: [docs/](docs/)\n- **Issues**: [GitHub Issues](https://github.com/DEADSEC-SECURITY/family-vault/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/DEADSEC-SECURITY/family-vault/discussions)\n\n## Acknowledgments\n\n- Built with [Next.js](https://nextjs.org/), [FastAPI](https://fastapi.tiangolo.com/), and [shadcn/ui](https://ui.shadcn.com/)\n- Inspired by [Trustworthy](https://www.trustworthy.com/)\n- Icons by [Lucide](https://lucide.dev/)\n\n---\n\n**Made with ❤️ for families who value security and organization**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdeadsec-security%2Ffamily-vault","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdeadsec-security%2Ffamily-vault","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdeadsec-security%2Ffamily-vault/lists"}