{"id":30860672,"url":"https://github.com/nucypher/taco-storage-sdk","last_synced_at":"2026-01-20T16:54:25.929Z","repository":{"id":306267152,"uuid":"1025498428","full_name":"nucypher/taco-storage-sdk","owner":"nucypher","description":"TypeScript SDK for encrypted data storage with TACo (Threshold Access Control), supporting multiple storage providers including IPFS and SQLite","archived":false,"fork":false,"pushed_at":"2025-07-26T09:26:37.000Z","size":444,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-08-09T12:40:12.043Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nucypher.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"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}},"created_at":"2025-07-24T10:47:51.000Z","updated_at":"2025-07-26T09:26:40.000Z","dependencies_parsed_at":"2025-07-24T18:33:45.175Z","dependency_job_id":"6d23a0f6-cbed-45cb-9fcb-62d875199629","html_url":"https://github.com/nucypher/taco-storage-sdk","commit_stats":null,"previous_names":["nucypher/taco-storage-sdk"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/nucypher/taco-storage-sdk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nucypher%2Ftaco-storage-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nucypher%2Ftaco-storage-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nucypher%2Ftaco-storage-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nucypher%2Ftaco-storage-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nucypher","download_url":"https://codeload.github.com/nucypher/taco-storage-sdk/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nucypher%2Ftaco-storage-sdk/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274059977,"owners_count":25215408,"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-09-07T02:00:09.463Z","response_time":67,"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":[],"created_at":"2025-09-07T16:14:14.037Z","updated_at":"2026-01-20T16:54:25.889Z","avatar_url":"https://github.com/nucypher.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# TACo Storage SDK\n\nTypeScript SDK for encrypted data storage with TACo (Threshold Access Control), supporting multiple storage providers including IPFS and SQLite.\n\n## Overview\n\nThis TypeScript SDK provides a high-level interface for storing and retrieving encrypted data using NuCypher's TACo (Threshold Access Control) system. It features a pluggable adapter architecture supporting multiple storage providers including IPFS for decentralized storage and SQLite for local/centralized storage.\n\n## Features\n\n- **Threshold Encryption**: Secure data encryption using TACo's threshold access control\n- **Multiple Storage Adapters**: Support for IPFS (Kubo \u0026 Helia) and SQLite storage\n- **IPFS Flexibility**: Choose between Kubo (external node) or Helia (embedded node) IPFS implementations - both fully functional\n- **Flexible Access Control**: Time-based, NFT ownership, and custom condition support\n- **Professional Architecture**: Clean separation of concerns with adapter pattern\n- **TypeScript Support**: Full type safety and excellent developer experience\n- **Comprehensive Testing**: Unit tests and integration tests included\n\n## Installation\n\n```bash\nnpm install nucypher-experimental-taco-storage\n```\n\n## Quick Start\n\n### Basic Usage with IPFS (Kubo)\n\n```typescript\nimport { TacoStorage } from 'nucypher-experimental-taco-storage';\nimport { ethers } from 'ethers';\n\n// Create storage instance with Kubo IPFS adapter (external node)\nconst storage = TacoStorage.createWithKubo({\n  domain: 'devnet',\n  ritualId: 123,\n});\n\n// Initialize signer\nconst provider = new ethers.providers.JsonRpcProvider('YOUR_RPC_URL');\nconst signer = new ethers.Wallet('YOUR_PRIVATE_KEY', provider);\n\n// Store encrypted data\nconst data = new TextEncoder().encode('Hello, encrypted world!');\nconst result = await storage.store(data, signer, {\n  contentType: 'text/plain',\n  expiresAt: new Date(Date.now() + 24 * 60 * 60 * 1000), // 24 hours\n});\n\nconsole.log('Stored with ID:', result.id);\n\n// Retrieve and decrypt data\nconst retrieved = await storage.retrieve(result.id, signer);\nconst decryptedText = new TextDecoder().decode(retrieved.data);\nconsole.log('Decrypted:', decryptedText);\n```\n\n### Basic Usage with IPFS (Helia)\n\n```typescript\nimport { TacoStorage } from 'nucypher-experimental-taco-storage';\nimport { ethers } from 'ethers';\n\n// Create storage instance with Helia IPFS adapter (embedded node)\nconst storage = await TacoStorage.createWithHelia({\n  domain: 'devnet',\n  ritualId: 123,\n}, {\n  timeout: 30000,\n  autoStart: true,\n});\n\n// Initialize signer\nconst provider = new ethers.providers.JsonRpcProvider('YOUR_RPC_URL');\nconst signer = new ethers.Wallet('YOUR_PRIVATE_KEY', provider);\n\n// Store encrypted data (same API as Kubo)\nconst data = new TextEncoder().encode('Hello, encrypted world!');\nconst result = await storage.store(data, signer, {\n  contentType: 'text/plain',\n  expiresAt: new Date(Date.now() + 24 * 60 * 60 * 1000), // 24 hours\n});\n\nconsole.log('Stored with ID:', result.id);\n\n// Retrieve and decrypt data\nconst retrieved = await storage.retrieve(result.id, signer);\nconst decryptedText = new TextDecoder().decode(retrieved.data);\nconsole.log('Decrypted:', decryptedText);\n```\n\n### Basic Usage with SQLite\n\n```typescript\nimport { TacoStorage } from 'nucypher-experimental-taco-storage';\n\n// Create storage instance with SQLite adapter\nconst storage = TacoStorage.createWithSQLite(\n  {\n    domain: 'devnet',\n    ritualId: 123,\n  },\n  {\n    databasePath: './data.db',\n    enableWAL: true,\n  }\n);\n\n// Use the same store/retrieve API\nconst result = await storage.store(data, signer);\nconst retrieved = await storage.retrieve(result.id, signer);\n```\n\n## Advanced Usage\n\n### Custom Access Conditions\n\n```typescript\nimport { conditions } from '@nucypher/taco';\n\n// Create NFT ownership condition\nconst nftCondition = storage.encryptionService.createNFTCondition(\n  '0x1234...', // NFT contract address\n  '123'        // Token ID (optional)\n);\n\nawait storage.store(data, signer, {\n  conditions: nftCondition,\n  contentType: 'application/json',\n});\n```\n\n### Custom Storage Adapter\n\n```typescript\nimport { BaseStorageAdapter, StorageMetadata, StorageResult } from 'nucypher-experimental-taco-storage';\n\nclass CustomAdapter extends BaseStorageAdapter {\n  async store(encryptedData: Uint8Array, metadata: StorageMetadata): Promise\u003cStorageResult\u003e {\n    // Implement your custom storage logic\n    // ...\n  }\n\n  async retrieve(id: string) {\n    // Implement your custom retrieval logic\n    // ...\n  }\n\n  // Implement other required methods...\n}\n\n// Use with TacoStorage\nconst adapter = new CustomAdapter(config);\nconst storage = new TacoStorage(adapter, tacoConfig);\n```\n\n## API Reference\n\n### TacoStorage\n\nThe main class for encrypted storage operations.\n\n#### Methods\n\n- `store(data, signer, options?)` - Store encrypted data\n- `retrieve(id, signer)` - Retrieve and decrypt data\n- `delete(id)` - Delete stored data\n- `exists(id)` - Check if data exists\n- `getMetadata(id)` - Get metadata without decrypting\n- `list(limit?, offset?)` - List stored data IDs (adapter dependent)\n- `getHealth()` - Get storage system health status\n- `cleanup()` - Clean up resources\n\n#### Static Methods\n\n- `TacoStorage.createWithKubo(config, kuboConfig?)` - Create instance with Kubo IPFS adapter (external node)\n- `TacoStorage.createWithHelia(config, heliaConfig?)` - Create instance with Helia IPFS adapter (embedded node)\n- `TacoStorage.createWithPinata(config, pinataConfig)` - Create instance with Pinata IPFS adapter (hosted service)\n- `TacoStorage.createWithSQLite(config, sqliteConfig?)` - Create instance with SQLite adapter\n\n### Storage Adapters\n\n#### KuboAdapter (External IPFS Node)\n\nDecentralized storage using external Kubo IPFS node.\n\n**Configuration:**\n```typescript\ninterface KuboAdapterConfig {\n  url?: string;        // IPFS node URL (default: http://localhost:5001)\n  timeout?: number;    // Operation timeout in ms\n  pin?: boolean;       // Whether to pin content (default: true)\n}\n```\n\n#### HeliaAdapter (Embedded IPFS Node)\n\nDecentralized storage using embedded Helia IPFS node.\n\n**Configuration:**\n```typescript\ninterface HeliaAdapterConfig {\n  timeout?: number;    // Operation timeout in ms (default: 30000)\n  autoStart?: boolean; // Auto-start libp2p node (default: true)\n  heliaOptions?: {     // Custom Helia configuration\n    libp2p?: any;      // Custom libp2p options\n    // ... other Helia options\n  };\n}\n```\n\n#### PinataAdapter (Hosted IPFS Service)\n\nDecentralized storage using [Pinata](https://pinata.cloud/) hosted IPFS service. Pinata provides a user-friendly API for IPFS storage with additional features like pinning guarantees and analytics.\n\n**Configuration:**\n```typescript\ninterface PinataAdapterConfig {\n  url: string;    // Pinata gateway URL (e.g., \"gateway.pinata.cloud\")\n  jwt: string;    // Pinata JWT token for authentication\n}\n```\n\n**Usage:**\n```typescript\nconst storage = await TacoStorage.createWithPinata(\n  config,\n  provider,\n  {\n    url: 'gateway.pinata.cloud',\n    jwt: 'your-pinata-jwt-token'\n  }\n);\n```\n\n#### SQLiteAdapter\n\nLocal/centralized storage using SQLite.\n\n**Configuration:**\n```typescript\ninterface SQLiteAdapterConfig {\n  databasePath?: string;  // Database file path (default: in-memory)\n  enableWAL?: boolean;    // Enable WAL mode (default: false)\n  timeout?: number;       // Connection timeout in ms\n}\n```\n\n## Error Handling\n\nThe SDK provides comprehensive error handling with specific error types:\n\n```typescript\nimport { TacoStorageError, TacoStorageErrorType } from 'nucypher-experimental-taco-storage';\n\ntry {\n  await storage.store(data, signer);\n} catch (error) {\n  if (error instanceof TacoStorageError) {\n    switch (error.type) {\n      case TacoStorageErrorType.ENCRYPTION_ERROR:\n        console.log('Encryption failed:', error.message);\n        break;\n      case TacoStorageErrorType.STORAGE_ERROR:\n        console.log('Storage failed:', error.message);\n        break;\n      // Handle other error types...\n    }\n  }\n}\n```\n\n## Development\n\n### Prerequisites\n\n- Node.js 16+\n- npm or yarn\n- IPFS Desktop or Kubo node (for IPFS adapter testing)\n\n### IPFS Integration Tests\n\nThe SDK includes separate test suites for both IPFS adapters:\n\n#### Kubo Adapter Tests\n**Requirements:**\n- IPFS Desktop or Kubo node running on `http://localhost:5001`\n- Tests use `kubo-rpc-client` for modern IPFS communication\n- No mocking - all tests run against real IPFS operations\n\n#### Helia Adapter Tests\n**Requirements:**\n- Uses embedded Helia IPFS node (no external dependencies)\n- Includes both unit tests (mocked) and integration tests (real Helia node)\n- Unit tests are fast and suitable for CI/CD\n\n**Setup for Kubo Tests:**\n1. Download and install [IPFS Desktop](https://github.com/ipfs/ipfs-desktop)\n2. Start IPFS Desktop (default API at `http://localhost:5001`)\n3. Run tests: `npm run test:ipfs`\n\n**Or Setup Kubo CLI:**\n```bash\n# Install Kubo\nbrew install ipfs  # macOS\n# or download from https://github.com/ipfs/kubo/releases\n\n# Initialize and start daemon\nipfs init\nipfs daemon\n\n# Run Kubo tests\nnpm run test:ipfs\n```\n\n**Run Helia Tests:**\n```bash\n# Run Helia unit tests (fast, no external dependencies)\nnpm run test:helia-unit\n\n# Run Helia integration tests (requires Node.js experimental VM modules)\nnpm run test:helia-integration\n\n# Run both Helia unit and integration tests\nnpm run test:helia-all\n```\n\n**Status:** ✅ All Helia integration tests are passing. The adapter is fully functional with embedded IPFS node support.\n\n**Note:** IPFS tests are excluded from the main test suite (`npm test`) because they:\n- May require Node.js experimental VM modules (`--experimental-vm-modules`)\n- Kubo tests need a running external IPFS node\n- Use real network operations (not mocked)\n\n### Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/nucypher/taco-storage-sdk.git\ncd taco-storage-sdk\n\n# Install dependencies\nnpm install\n\n# Build the project\nnpm run build\n\n# Run tests (excludes IPFS tests)\nnpm test\n\n# Run Kubo IPFS tests (requires local IPFS node)\nnpm run test:kubo-all\n\n# Run Helia IPFS tests\nnpm run test:helia-all\n\n# Run ALL tests (main + IPFS integration)\nnpm run test:all\n\n# Run all tests with coverage\nnpm run test:coverage\n\n# Run linting\nnpm run lint\n```\n\n### Project Structure\n\n```\nsrc/\n├── adapters/           # Storage adapter implementations\n│   ├── base.ts        # Base adapter interface and abstract class\n│   ├── ipfs/          # IPFS adapter implementations\n│   │   ├── base.ts    # Base IPFS adapter with shared functionality\n│   │   ├── kubo.ts    # Kubo IPFS adapter (external node)\n│   │   ├── helia.ts   # Helia IPFS adapter (embedded node)\n│   │   └── index.ts   # IPFS adapter exports\n│   ├── sqlite.ts      # SQLite adapter\n│   └── index.ts       # Adapter exports\n├── core/              # Core functionality\n│   ├── encryption.ts  # TACo encryption service\n│   └── storage.ts     # Main TacoStorage class\n├── types/             # TypeScript type definitions\n│   └── index.ts       # Type exports\n├── __tests__/         # Test files\n│   └── setup.ts       # Test setup and utilities\n└── index.ts           # Main entry point\n```\n\n## Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\n\n## License\n\nThis project is licensed under the GPL-3.0 License - see the [LICENSE](LICENSE) file for details.\n\n## Support\n\n- [Documentation](https://docs.nucypher.com/taco)\n- [GitHub Issues](https://github.com/nucypher/taco-storage-sdk/issues)\n- [Discord Community](https://discord.gg/nucypher)\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md) for release history and changes.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnucypher%2Ftaco-storage-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnucypher%2Ftaco-storage-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnucypher%2Ftaco-storage-sdk/lists"}