Documentazione Tecnica
& Architettura di Sicurezza

Request Body:

{
  "email": "user@example.com",
  "password_hash": "pbkdf2_sha256_hash",  // PBKDF2 client-side
  "salt": "base64_encoded_salt",
  "rsa_public_key": "-----BEGIN PUBLIC KEY-----...",
  "rsa_encrypted_private_key": "base64_encrypted_private_key",
  "rsa_private_key_iv": "base64_iv"
}

Response (201 Created):

{
  "message": "User registered successfully",
  "user_id": "uuid-v4",
  "email": "user@example.com"
}

Errors:

400 Bad Request: "Email already exists"
400 Bad Request: "Invalid RSA public key format"
500 Internal Server Error

Request Body:

{
  "email": "user@example.com",
  "password_hash": "pbkdf2_sha256_hash"
}

Response (200 OK):

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user_id": "uuid-v4",
  "email": "user@example.com",
  "rsa_encrypted_private_key": "base64_encrypted",
  "rsa_private_key_iv": "base64_iv"
}

Errors:

401 Unauthorized: "Invalid credentials"
404 Not Found: "User not found"

Headers:

Authorization: Bearer {jwt_token}

Response (200 OK):

{
  "message": "Logged out successfully"
}

Headers:

Authorization: Bearer {jwt_token}
Content-Type: application/json

Request Body:

{
  "encrypted_file": "base64_encrypted_blob",
  "encrypted_metadata": {
    "encrypted_filename": "base64_encrypted_name",
    "encrypted_filetype": "base64_encrypted_type",
    "file_size_encrypted": 123456,  // Size of encrypted blob
    "iv": "base64_iv",
    "tag": "base64_gcm_tag"
  },
  "encrypted_dek_with_kek": "base64_wrapped_dek",
  "file_hash": "sha256_hex_digest"
}

Response (201 Created):

{
  "file_id": "uuid-v4",
  "s3_path": "tenant_id/file_id.enc",
  "uploaded_at": "2025-12-23T10:30:00Z"
}

Errors:

400 Bad Request: "Missing encrypted metadata"
401 Unauthorized: "Invalid or expired token"
413 Payload Too Large: "File exceeds 5GB limit"
507 Insufficient Storage: "Storage quota exceeded"

Headers:

Authorization: Bearer {jwt_token}

Query Parameters:

?folder_id=uuid           // Filter by folder (optional)
&limit=50                 // Pagination limit (default: 100)
&offset=0                 // Pagination offset (default: 0)
&sort_by=created_at       // Sort field (created_at, size, name)
&order=desc               // Sort order (asc, desc)

Response (200 OK):

{
  "files": [
    {
      "file_id": "uuid-v4",
      "encrypted_metadata": {
        "encrypted_filename": "base64...",
        "encrypted_filetype": "base64...",
        "file_size_encrypted": 123456,
        "iv": "base64...",
        "tag": "base64..."
      },
      "encrypted_dek_with_kek": "base64...",
      "s3_path": "tenant_id/file_id.enc",
      "created_at": "2025-12-23T10:30:00Z",
      "is_favorite": false
    }
  ],
  "total": 42,
  "limit": 50,
  "offset": 0
}

Headers:

Authorization: Bearer {jwt_token}

Response (200 OK):

{
  "encrypted_file": "base64_blob",
  "encrypted_metadata": { /* ... */ },
  "encrypted_dek_with_kek": "base64...",
  "file_hash": "sha256..."
}

Errors:

404 Not Found: "File not found"
403 Forbidden: "Access denied"

Headers:

Authorization: Bearer {jwt_token}

Response (200 OK):

{
  "message": "File deleted successfully",
  "file_id": "uuid-v4"
}

Errors:

404 Not Found: "File not found"
403 Forbidden: "Cannot delete shared file"

Request Body:

{
  "file_id": "uuid-v4",
  "encrypted_dek_share": "base64_dek_wrapped_with_share_password",
  "share_salt": "base64_salt_for_share_password",
  "expiration_days": 7,
  "max_downloads": 10
}

Response (201 Created):

{
  "share_id": "uuid-v4",
  "share_url": "https://onionedcloud.onion/share/uuid-v4",
  "expires_at": "2025-12-30T10:30:00Z"
}

Query Parameters:

?password_hash=pbkdf2_hash   // Hash della share password

Response (200 OK):

{
  "encrypted_file": "base64_blob",
  "encrypted_dek_share": "base64...",
  "share_salt": "base64...",
  "encrypted_metadata": { /* ... */ },
  "downloads_remaining": 9
}

Errors:

401 Unauthorized: "Invalid password"
404 Not Found: "Share expired or not found"
429 Too Many Requests: "Max downloads reached"

Request Body:

{
  "file_id": "uuid-v4",
  "recipient_email": "recipient@example.com",
  "encrypted_dek_rsa": "base64_dek_encrypted_with_recipient_public_key",
  "permissions": "read"  // Future: "read", "write", "admin"
}

Response (201 Created):

{
  "share_id": "uuid-v4",
  "recipient_id": "uuid-v4",
  "created_at": "2025-12-23T10:30:00Z"
}

Errors:

404 Not Found: "Recipient not found"
400 Bad Request: "Cannot share with yourself"
403 Forbidden: "File already shared with this user"

Response (200 OK):

{
  "shares": [
    {
      "share_id": "uuid-v4",
      "file_id": "uuid-v4",
      "sender_email": "sender@example.com",
      "encrypted_dek_rsa": "base64...",
      "encrypted_metadata": { /* ... */ },
      "shared_at": "2025-12-23T10:30:00Z",
      "permissions": "read"
    }
  ]
}

Response (200 OK):

{
  "message": "Share revoked successfully"
}

Response (200 OK):

{
  "email": "user@example.com",
  "rsa_public_key": "-----BEGIN PUBLIC KEY-----\nMIICIjANBgkqhki...\n-----END PUBLIC KEY-----",
  "user_id": "uuid-v4"
}

Errors:

404 Not Found: "User not found"

Headers:

Authorization: Bearer {jwt_token}

Response (200 OK):

{
  "rsa_encrypted_private_key": "base64_encrypted_private_key_pkcs8",
  "rsa_private_key_iv": "base64_iv"
}

Response (200 OK):

{
  "used_bytes": 1234567890,
  "quota_bytes": 5368709120,  // 5 GB
  "percentage_used": 23.0,
  "file_count": 42
}