S3xx

S3XX provides an S3-compatible API backed by IPFS/Filecoin. Developers can use it like any S3 storage service, while behind the scenes all data is stored on decentralized IPFS with persistence guaranteed by Filecoin deals.

Architecture

• MinIO (S3-compatible object storage)
• Synapse SDK (@filoz/synapse-sdk) for Filecoin/IPFS persistence and payments
• Docker Compose for orchestration
• PostgreSQL as the ledger DB for key→CID mapping
• TypeScript/Node.js for Synapse service and API gateway

s3xx/
├─ package.json
├─ .env.example
│
├─ infra/                          # Infrastructure (docker-compose, quickstart)
│  ├─ docker-compose.yml
│  └─ README.md
│
├─ synapse-service/                 # MinIO webhook handler + Synapse SDK uploader
│  ├─ package.json
│  ├─ tsconfig.json
│  ├─ Dockerfile
│  └─ src/
│     ├─ index.ts                   # Hono app entrypoint (/minio/webhook)
│     └─ synapse.ts                 # Synapse SDK wrapper
│
├─ gateway/                         # Ledger API (Hono on Cloudflare Workers)
│  ├─ wrangler.toml
│  ├─ package.json
│  ├─ tsconfig.json
│  ├─ schema.sql                    # D1 schema (objects/e2ee_meta/shares)
   └─ src/
      └─ index.ts                   # Hono app (internal upsert, /cid, /meta, /share)

Flowchart

flowchart LR
client[Client - Webapp or SDK - E2EE encrypt and decrypt]
minio[MinIO - S3 frontend]
synapse[Synapse Service - Node TS - webhook and upload via Synapse SDK - get CID]
gateway[Gateway - Hono on Cloudflare Workers - Ledger API - CID and E2EE meta - share and usage]
ledger[Ledger DB - D1 or Postgres - bucket key to CID and meta]
ipfs[IPFS and Filecoin - persistent storage]

client -->|S3 PUT ciphertext and GET ciphertext| minio
minio -->|Webhook ObjectCreated| synapse
synapse -->|Upload via Synapse SDK then deal and CID| ipfs
synapse -->|Internal API with CID and metadata| gateway
gateway --> ledger
ledger --> gateway
client -->|GET cid, meta, share - E2EE keys and meta| gateway
client -.->|optional direct fetch by CID| ipfs

Loading

Sequence Diagram

sequenceDiagram
    %% Participants
    participant U as User (Webapp / SDK)
    participant M as MinIO (S3 Frontend)
    participant S as Synapse Service
    participant G as Gateway (Ledger API)
    participant L as Ledger DB (D1/Postgres)
    participant F as IPFS/Filecoin

    %% Upload flow
    U->>U: Encrypt file (E2EE AES-GCM)
    U->>M: PUT object (ciphertext)
    M-->>U: 200 OK (PUT accepted)
    M->>S: Webhook: ObjectCreated
    S->>M: GET object (ciphertext)
    M-->>S: Return ciphertext
    S->>F: Upload via Synapse SDK (deal)
    F-->>S: CID / CommP
    S->>G: POST /internal/ledger/upsert (CID + metadata)
    G->>L: Insert/Update bucket/key → CID/meta
    L-->>G: OK
    G-->>S: OK

    %% Download flow
    U->>G: GET /v1/objects/:bucket/:key/cid
    G->>L: Query mapping
    L-->>G: Return CID + meta
    G-->>U: CID + E2EE metadata
    U->>F: (Optional) Fetch data by CID
    F-->>U: Ciphertext
    U->>U: Decrypt with own key → Plain data

Loading