• Syncraft

Defining the Goal

With the core concept established, the architecture crystallized into a clear set of decisions. The goal became evident: build a sync library that’s secure, scalable, and simple to use.

Data Model: Encrypted by Design

Every document in Synccraft is encrypted at rest. The model looks like this:

{
  "id": "ULID",
  "enc": {
    "kid": "UUID v7",
    "collection": "encrypted",
    "data": "encrypted",
    "nonce": "base64"
  },
  "meta": {
    "version": 3,
    "modified": "ISO timestamp",
    "author": "UUID v4",
    "deleted": false
  }
}

• Document ID: ULID (time-ordered, globally unique)
• Key ID: UUID v7 (time-ordered, sortable by creation time)
• Device ID: UUID v4 (globally unique, no time ordering needed)
• Collection and Data: AES-256-GCM encrypted
• Metadata: Plaintext (needed for sync operations)

Scalable File Paths: Two-Level ULID Bucketing

To avoid too many files in a single directory, ULIDs are split into two-level buckets:

{collection}/{ulid[10:12]}/{ulid[12:14]}/{ulid}.json

Example: items/A7/3F/01ARZ3NDEKTSV4RRFFQ69G5FAV.json

This gives 65,536 possible paths per collection—plenty of scale.

Key Management: Secure and Rotatable

The encryption model uses per-scope symmetric keys (K) with asymmetric key wrapping:

• Each device has a key pair (public/private)
• The symmetric key is encrypted (wrapped) for each device using their public key
• Multiple keys are supported via Key IDs (KIDs)
• Key rotation is built-in: generate new K, wrap for all devices, optional re-encryption

The encryption architecture reflects a “zero trust” approach to data storage. Even if the storage backend (cloud drive, API server) is compromised, the data remains encrypted. The key management system—with its per-device wrapping and rotation support—provides enterprise-grade security without complexity.