Sync API

Endpoints for encrypted settings and data sync. Available to Pro and Studio tier users.

Overview

The Sync module stores encrypted blobs uploaded by NexusCore CLI and NexusIDE. All data is encrypted on the client before transmission — the server never sees plaintext content (zero-knowledge architecture).

Namespaces

Sync data is organized into namespaces:

Namespace	Description
settings	NexusCore configuration and preferences
skills	Installed skills and their configuration
memory	Persistent agent memory entries

Storage Quotas

Tier	Quota
Pro	100 MB
Studio	1 GB

Upload Sync Data

Upload an encrypted blob for the given namespace.

PUT /v1/sync/:namespace
Authorization: Bearer <jwt>
Content-Type: application/octet-stream

Headers:

Header	Required	Description
X-Vector-Clock	Yes	JSON vector clock for conflict resolution
X-Checksum	Yes	SHA-256 checksum of the encrypted blob

Body: Raw encrypted binary data.

Response: 200 OK

{
  "data": {
    "namespace": "settings",
    "blob_size": 15360,
    "checksum": "sha256:a1b2c3d4...",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}

Errors:

Code	Condition
TIER_REQUIRED	User is on Core tier
QUOTA_EXCEEDED	Upload would exceed storage quota
VALIDATION_ERROR	Missing headers or checksum mismatch

Download Sync Data

Download the encrypted blob for the given namespace.

GET /v1/sync/:namespace
Authorization: Bearer <jwt>

Response: 200 OK

Returns the raw encrypted binary data with headers:

Header	Description
X-Vector-Clock	JSON vector clock of the stored blob
X-Checksum	SHA-256 checksum for verification
Content-Type	application/octet-stream

Get Sync Status

Check sync status and quota usage.

GET /v1/sync/status
Authorization: Bearer <jwt>

Response: 200 OK

{
  "data": {
    "quota_used_bytes": 5242880,
    "quota_limit_bytes": 104857600,
    "namespaces": [
      {
        "name": "settings",
        "size_bytes": 2048000,
        "last_synced": "2024-01-15T10:30:00Z"
      },
      {
        "name": "skills",
        "size_bytes": 3194880,
        "last_synced": "2024-01-14T18:00:00Z"
      }
    ]
  }
}

Delete Sync Data

Delete the encrypted blob for a specific namespace.

DELETE /v1/sync/:namespace
Authorization: Bearer <jwt>

Response: 204 No Content

Conflict Resolution

The Sync module uses last-write-wins with vector clock timestamps for conflict resolution:

1. Each client maintains a vector clock that increments on every write
2. When uploading, the client sends its vector clock in the X-Vector-Clock header
3. If the server's vector clock is newer, the upload is rejected with a conflict error
4. The client can then download the latest version, merge locally, and retry

Encryption

All sync data is encrypted on the client side before transmission:

1. An encryption key is derived from the user's password using a key derivation function
2. Data is encrypted with AES-256-GCM before upload
3. The server stores only the encrypted blob — it cannot decrypt the contents
4. On download, the client decrypts the blob locally

This zero-knowledge architecture means that even if the server is compromised, your data remains encrypted and unreadable.