lib-privatebin/README.md

# PrivateBin API Library

A C++ library for interacting with PrivateBin servers via the JSON API v1.3.

## Features

- **Text Paste Creation**: Create encrypted text pastes with multiple formats
- **File Upload**: Upload files as encrypted pastes
- **Paste Retrieval**: Retrieve and decrypt pastes
- **Paste Deletion**: Delete pastes with deletion tokens
- **End-to-End Encryption**: Client-side encryption with AES-256-GCM
- **Cross-Platform**: Support for Windows and Linux
- **Complete API**: Implementation of all PrivateBin v1.3 API functions
- **Automated Builds**: Platform-specific build scripts for easy compilation
- **Text Formatting**: Support for plaintext, syntax highlighting, and markdown

## Text Formatting Support

The library supports multiple text formats as defined in the [PrivateBin API v1.3](https://github.com/PrivateBin/PrivateBin/wiki/API):

### Available Formats

- **`plaintext`** - Plain text (default format)
- **`syntaxhighlighting`** - Syntax highlighting for code snippets
- **`markdown`** - Markdown formatting for rich text

### Format Usage

```c
#include "privatebinapi.h"

// Plain text format
create_paste(server, content, password, expiration, "plaintext", 0, 0, &url, &token);

// Syntax highlighting for code
create_paste(server, code_content, password, expiration, "syntaxhighlighting", 0, 0, &url, &token);

// Markdown formatting
create_paste(server, markdown_content, password, expiration, "markdown", 0, 0, &url, &token);
```

## File Upload Functionality

The library includes an `upload_file` function that allows you to securely upload files to PrivateBin servers:

```c
int upload_file(const char* server_url, const char* file_path,
                const char* password, const char* expiration,
                int burn_after_reading, int open_discussion,
                char** paste_url, char** delete_token);
```

### File Upload Parameters

- **`server_url`**: The URL of the PrivateBin server
- **`file_path`**: The path to the file to upload
- **`password`**: Optional password for the paste (can be NULL)
- **`expiration`**: Expiration time ("5min", "10min", "1hour", "1day", "1week", "1month", "1year", "never")
- **`burn_after_reading`**: 1 for "burn after reading", 0 for "keep"
- **`open_discussion`**: 1 for allow discussion, 0 for disable discussion
- **`paste_url`**: Output parameter for the URL of the created paste
- **`delete_token`**: Output parameter for the deletion token

### File Upload Features

- **Binary Files**: Support for all file types
- **Size Limitation**: Maximum file size 100MB
- **Secure Encryption**: Same cryptography as text pastes
- **Compression**: Automatic zlib compression before encryption
- **Metadata**: File name, size, and type are added to metadata
- **Key Derivation**: PBKDF2-HMAC-SHA256 with 100,000 iterations

### How File Upload Works

1. **File Reading**: The file is read in binary mode
2. **Size Check**: Maximum file size is limited to 100MB
3. **Encryption**: 
   - Generation of a random 32-byte key
   - File compression with zlib
   - Encryption with AES-256-GCM
   - Key derivation with PBKDF2-HMAC-SHA256 (100,000 iterations)
4. **Metadata**: File name, size, and type are added to metadata
5. **Upload**: Encrypted data is sent to the PrivateBin server
6. **URL Generation**: The URL is created with the Base58-encoded key

## Build Scripts

The project includes several build scripts in the `scripts/` directory for different platforms and use cases.

### Windows Build Scripts

#### PowerShell Build (Recommended)
**File:** `scripts/build_windows.ps1`  
**Requirements:** PowerShell, Visual Studio 2022 Build Tools (C++), vcpkg (will be bootstrapped), Git

```powershell
# Run from project root
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\build_windows.ps1
```

This script:
- Automatically bootstraps vcpkg if not present
- Configures CMake with Visual Studio 2022 generator
- Builds the project in Release configuration
- Creates a Windows distribution package with all artifacts

#### Command Line Build
**File:** `scripts/build_thinkpad.bat`  
**Requirements:** Visual Studio 2022 Build Tools/Community with C++ workload, vcpkg

```cmd
# Run from project root
scripts\build_thinkpad.bat
```

This script:
- Automatically detects and initializes Visual Studio environment
- Handles vcpkg bootstrapping
- Configures CMake with proper toolchain
- Builds the project using MSVC compiler

### Linux/macOS Build Script
**File:** `scripts/build.sh`  
**Requirements:** CMake, C++17 compiler, vcpkg

```bash
# Make executable and run from project root
chmod +x scripts/build.sh
./scripts/build.sh
```

This script:
- Bootstraps vcpkg if not present
- Configures CMake with Unix Makefiles
- Builds the project in Release configuration

## Installation

### Dependencies

- CMake 3.10+
- C++17 compatible compiler
- Crypto++ (via vcpkg)
- nlohmann/json (via vcpkg)

### Compilation

#### Windows (PowerShell) - Build via scripts/build_windows.ps1
```powershell
# Requires: PowerShell, Visual Studio 2022 Build Tools (C++), vcpkg (will be bootstrapped), Git
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\build_windows.ps1
```

#### Windows (Command Line) - Build via scripts/build_thinkpad.bat
```cmd
# Requires: Visual Studio 2022 Build Tools/Community with C++ workload, vcpkg
scripts\build_thinkpad.bat
```

#### Linux/macOS - Build via scripts/build.sh
```bash
# Requires: CMake, C++17 compiler, vcpkg
chmod +x scripts/build.sh
./scripts/build.sh
```

#### Manual Build
```bash
mkdir build
cd build
cmake ..
cmake --build . --config Release
```

**Note:** The manual build method requires you to have all dependencies (CMake, compiler, vcpkg) properly configured. For most users, the platform-specific build scripts are recommended.

## Usage

### Text Paste with Formatting

The library supports multiple text formats as defined in the [PrivateBin API v1.3](https://github.com/PrivateBin/PrivateBin/wiki/API):

#### Available Formats

- **`plaintext`** - Plain text (default)
- **`syntaxhighlighting`** - Syntax highlighting for code
- **`markdown`** - Markdown formatting

#### Basic Example

```c
#include "privatebinapi.h"

char* paste_url = nullptr;
char* delete_token = nullptr;

int result = create_paste(
    "https://privatebin.net",
    "Hello, World!",
    NULL,           // no password
    "1day",         // expiration
    "plaintext",    // format
    0,              // don't burn after reading
    0               // no discussion
);

if (result == 0) {
    printf("Paste created: %s\n", paste_url);
    free_string(paste_url);
    free_string(delete_token);
}
```

#### Syntax Highlighting Example

```c
const char* code_content = R"(
#include <iostream>

int main() {
    std::cout << "Hello, World!" << std::endl;
    return 0;
}
)";

int result = create_paste(
    "https://privatebin.net",
    code_content,
    NULL,                    // no password
    "1week",                 // expiration
    "syntaxhighlighting",    // syntax highlighting format
    0,                       // don't burn after reading
    0                        // no discussion
);
```

#### Markdown Example

```c
const char* markdown_content = R"(
# Header

This is **bold** and *italic* text.

## Code Block
```cpp
int x = 42;
std::cout << x << std::endl;
```

> This is a blockquote.
)";

int result = create_paste(
    "https://privatebin.net",
    markdown_content,
    NULL,           // no password
    "1month",       // expiration
    "markdown",     // markdown format
    0,              // don't burn after reading
    0               // no discussion
);
```

### File Upload

```c
char* paste_url = nullptr;
char* delete_token = nullptr;

int result = upload_file(
    "https://privatebin.net",
    "/path/to/file.txt",
    "mypassword",   // optional password
    "1week",        // expiration
    0,              // don't burn after reading
    0               // no discussion
);

if (result == 0) {
    printf("Successfully uploaded!\n");
    printf("URL: %s\n", paste_url);
    printf("Delete Token: %s\n", delete_token);
    
    // Free memory
    free_string(paste_url);
    free_string(delete_token);
}
```

## Examples

The library contains a comprehensive example program that demonstrates both text paste and file upload functionality:

### Running the Example

```bash
# Run basic example (tests all text formats)
./example

# Upload a file
./example --upload https://privatebin.net test.txt

# Upload with password and expiration
./example --upload https://privatebin.net test.txt mypassword 1week

# Upload with all options
./example --upload https://privatebin.net test.txt mypassword 1day 1 0
```

The basic example now demonstrates:
- **Plaintext format** - Simple text pastes
- **Syntax highlighting format** - Code with syntax highlighting
- **Markdown format** - Rich text formatting
- **Interactive format selection** - Shows available options

### Example Output

The example program demonstrates:
- Creating text pastes
- Retrieving paste content
- Deleting pastes
- File upload with various options
- Error handling for all operations

## API Reference

### Functions

- `create_paste()` - Creates a text paste with optional formatting
- `upload_file()` - Uploads a file
- `get_paste()` - Retrieves a paste
- `delete_paste()` - Deletes a paste
- `free_string()` - Frees memory

### Format Support

The `create_paste()` function supports the following formats as defined in the [PrivateBin API v1.3](https://github.com/PrivateBin/PrivateBin/wiki/API):

- **`plaintext`** - Default format for simple text
- **`syntaxhighlighting`** - Syntax highlighting for code snippets
- **`markdown`** - Markdown formatting for rich text

### Error Codes

- `0` - Success
- `1` - Network error
- `2` - Cryptographic error
- `3` - Invalid input (e.g., file not found or too large)
- `4` - Server error
- `5` - JSON parsing error

## Security

- **Client-Side Encryption**: All data is encrypted before upload
- **AES-256-GCM**: Modern encryption with authentication
- **PBKDF2**: Secure key derivation with 100,000 iterations
- **Random Keys**: Each paste receives a unique key
- **No Server Logs**: Server cannot read encrypted data
- **File Compression**: Automatic zlib compression before encryption
- **Binary Support**: All file types are treated as encrypted binary data

## Limitations

- **File Size**: Maximum file size is 100MB
- **File Type**: All file types are treated as binary data
- **Server Compatibility**: Works with PrivateBin v1.3+ servers
- **Format**: Files are always treated as "plaintext" (even if they are binary data)

## Error Handling

The library returns detailed error codes and logs errors to the console. Common errors:

- **File not found**: Check the file path
- **File too large**: Reduce file size or split it up
- **Network error**: Check server URL and internet connection
- **Server error**: The server might be temporarily unavailable

## License

See [LICENSE](LICENSE) for details.

## Changelog

### v0.1.1.5 (2025-08-28)
- **NEW**: Enhanced text format support (plaintext, syntax highlighting, markdown)
- **NEW**: Comprehensive format testing in examples and integration tests
- **IMPROVED**: Better API documentation with format examples
- **IMPROVED**: Enhanced test coverage for all supported formats

### v0.1.1.4 (2025-08-28)
- **NEW**: Automated release creation script (`scripts/create_release.ps1`)
- **NEW**: Build scripts moved to `scripts/` directory for better organization
- **IMPROVED**: Enhanced build documentation with platform-specific instructions
- **IMPROVED**: Better project structure and organization

### v0.1.1.1 (2025-08-28)
- **NEW**: Combined example program with both text and file upload functionality
- **IMPROVED**: Unified command-line interface for examples
- **IMPROVED**: Better error handling and user experience

### v0.1.1 (2025-08-28)
- **NEW**: File upload functionality added
- **NEW**: `upload_file()` function implemented
- **NEW**: Comprehensive example program
- **NEW**: Extended documentation for file upload
- **IMPROVED**: Better error handling
- **IMPROVED**: Cross-platform compatibility