{"id":31582144,"url":"https://github.com/nao1215/horcrux","last_synced_at":"2026-05-07T15:41:49.947Z","repository":{"id":318006218,"uuid":"1069506658","full_name":"nao1215/horcrux","owner":"nao1215","description":"splitting files into encrypted fragments (horcruxes) inspired by Harry Potter","archived":false,"fork":false,"pushed_at":"2025-10-04T13:59:09.000Z","size":855,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-10-04T14:00:35.696Z","etag":null,"topics":["library","node","nodejs","react-native","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nao1215.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","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},"funding":{"github":"nao1215"}},"created_at":"2025-10-04T04:15:31.000Z","updated_at":"2025-10-04T13:55:47.000Z","dependencies_parsed_at":"2025-10-04T14:00:41.073Z","dependency_job_id":null,"html_url":"https://github.com/nao1215/horcrux","commit_stats":null,"previous_names":["nao1215/horcrux"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/nao1215/horcrux","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nao1215%2Fhorcrux","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nao1215%2Fhorcrux/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nao1215%2Fhorcrux/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nao1215%2Fhorcrux/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nao1215","download_url":"https://codeload.github.com/nao1215/horcrux/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nao1215%2Fhorcrux/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278322146,"owners_count":25967874,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-04T02:00:05.491Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["library","node","nodejs","react-native","typescript"],"created_at":"2025-10-05T22:31:57.793Z","updated_at":"2025-10-05T22:32:53.861Z","avatar_url":"https://github.com/nao1215.png","language":"TypeScript","funding_links":["https://github.com/sponsors/nao1215"],"categories":[],"sub_categories":[],"readme":"# Horcrux\n\n![logo](./doc/img/horcrux-small.png)\n\nHorcrux is TypeScript library for splitting files into encrypted fragments (horcruxes) inspired by Harry Potter. Split your files into multiple pieces where only a subset is needed to restore the original - no password required!!\n\nIf you have a file you want to keep secret, you can split it with Horcrux and hide the horcruxes so that only you can restore the original file. Horcrux works on both Node.js and React Native platforms.\n\n## Features\n\n- **With Encryption**: AES-256-OFB encryption for data protection\n- **Shamir's Secret Sharing**: Split encryption keys using mathematical secret sharing\n- **Flexible Thresholds**: Choose how many pieces are needed for restoration\n- **Cross-Platform**: Works with Node.js and React Native\n- **No Password Needed**: Keys are split across horcruxes\n\n![example](./doc/img/horcrux_example.jpg)\n\n## Installation\n\n```bash\nnpm install @nao1215/horcrux\n```\n\n## Quick Start\n\n```typescript\nimport { split, bind, nodeAdapter } from '@nao1215/horcrux';\nimport { saveHorcruxes } from '@nao1215/horcrux/core/split';\n\n// Split a file into 5 pieces, need 3 to restore\nconst result = await split('secret.pdf', 5, 3);\n\n// Save horcruxes (creates secret_1_of_5.horcrux, etc.)\nconst files = await saveHorcruxes(result.horcruxes, './output', nodeAdapter);\n\n// Later: Restore from any 3 horcruxes\nawait bind(files.slice(0, 3), 'restored_secret.pdf');\n```\n\n\n### Two Modes\n\n- **Redundant Mode** (threshold \u003c total): Each horcrux contains the full encrypted file\n- **Space-Efficient Mode** (threshold = total): Encrypted data is distributed across horcruxes\n\n## API Documentation\n\n### Basic Functions\n\n#### `split(inputPath, total, threshold)`\nSplit a file into horcruxes.\n\n```typescript\nconst result = await split('document.pdf', 5, 3);\n// Creates 5 horcruxes, need any 3 to restore\n```\n\n#### `bind(horcruxPaths, outputPath)`\nRestore a file from horcruxes.\n\n```typescript\nawait bind(['horcrux1.horcrux', 'horcrux2.horcrux', 'horcrux3.horcrux'], 'restored.pdf');\n```\n\n### Advanced Usage\n\n#### Buffer Operations\n\n```typescript\nimport { splitBuffer } from '@nao1215/horcrux';\nimport { bindHorcruxes } from '@nao1215/horcrux/core/bind';\n\n// Split in-memory data\nconst data = Buffer.from('Secret message');\nconst result = await splitBuffer(data, 'message.txt', {\n  total: 4,\n  threshold: 2\n});\n\n// Restore from horcruxes\nconst restored = await bindHorcruxes(result.horcruxes.slice(0, 2));\nconsole.log(restored.data.toString()); // 'Secret message'\n```\n\n#### Custom Platform Adapters\n\n```typescript\nimport { splitFile, nodeAdapter } from '@nao1215/horcrux';\n\n// Use specific adapter\nconst result = await splitFile('file.txt', {\n  total: 5,\n  threshold: 3\n}, nodeAdapter);\n```\n\n#### Auto-Discovery\n\n```typescript\nimport { autoBind, nodeAdapter } from '@nao1215/horcrux';\n\n// Automatically find and restore horcruxes from a directory\nconst result = await autoBind('./horcrux_directory', nodeAdapter);\n```\n\n## Platform Support\n\n### Node.js\nFull support out of the box using native `crypto` and `fs` modules.\n\n### React Native\nRequires additional setup:\n\n```bash\nnpm install react-native-fs react-native-crypto\n# or\nnpm install expo-crypto expo-file-system\n```\n\nThen configure:\n\n```typescript\nimport { configureReactNative } from '@nao1215/horcrux/adapters/react-native';\nimport RNFS from 'react-native-fs';\nimport Crypto from 'react-native-crypto';\n\nconfigureReactNative(RNFS, Crypto);\n```\n\n## Security Considerations\n\n- Keys are generated using cryptographically secure random number generators\n- Each horcrux includes metadata (filename, timestamp) in plaintext\n- The encryption uses AES-256 in OFB mode with a zero IV\n- Horcruxes from different split operations cannot be mixed\n\n## Use Cases\n\n- **Long-term Storage**: Store files without worrying about forgetting passwords\n- **Distributed Backup**: Store horcruxes across multiple locations/services\n- **Secure Sharing**: Share files where multiple parties must cooperate to access\n- **Secret file**: Create a file that can only be viewed by following a specific procedure\n\n## Contributing\n\nContributions are welcome! Please see the [Contributing Guide](./CONTRIBUTING.md) for more details.\n\n## Testing\n\n```bash\n# Run all tests\nnpm test\n\n# Run with coverage\nnpm run test:coverage\n\n# React Native adapter contract tests\nnpm run test:react-native\n\n# Watch mode\nnpm run test:watch\n```\n\n## Development\n\n```bash\n# Install dependencies\nnpm install\n\n# Build the project\nnpm run build\n\n# Run linter\nnpm run lint\n\n# Type checking\nnpm run typecheck\n```\n\n## License\n\n[MIT LICENCE](./LICENSE)\n\n## Acknowledgments\n\nInspired by:\n- J.K. Rowling's Harry Potter series\n- The [horcrux CLI tool written in Go](https://github.com/jesseduffield/horcrux)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnao1215%2Fhorcrux","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnao1215%2Fhorcrux","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnao1215%2Fhorcrux/lists"}