lib-privatebin/README.md

# PrivateBin API C++ DLL

A cross-platform C++ library for interacting with PrivateBin servers.

## Overview

This library provides a simple C++ interface for interacting with PrivateBin services. PrivateBin is a minimalist, open-source online pastebin where the server has zero knowledge of stored data. All data is encrypted and decrypted in the browser using 256-bit AES encryption.

## Features

- Create new pastes with optional expiration, formatting, and security settings
- Retrieve existing pastes by ID
- Delete pastes using the deletion token
- Cross-platform compatibility (Windows and Linux)
- Support for PrivateBin API versions 1.3 and later

## Development & Build

### Prerequisites

- CMake 3.10+
- C++17-capable compiler (MSVC 2022 or GCC/Clang)
- Git
- vcpkg (automatically bootstrapped by the Makefile)

### Dependencies

- cryptopp (Crypto++)
- nlohmann-json
- Windows: WinHTTP (SDK)
- Linux: libcurl (used automatically via vcpkg)

### Quick start with Makefile (Windows & Linux)

1) Install dependencies, configure, and build:

```
make
```

2) Build and run the example:

```
make example
```

The Makefile does:
- clone and bootstrap vcpkg
- install packages from `vcpkg.json`
- configure CMake with the vcpkg toolchain
- build the library and the example

### Manual with CMake

```
# clone and bootstrap vcpkg
git clone https://github.com/microsoft/vcpkg.git "$HOME/vcpkg"
"$HOME/vcpkg/bootstrap-vcpkg.sh"   # Linux/macOS
# Windows (PowerShell):
# powershell -NoProfile -ExecutionPolicy Bypass -Command "& '$env:USERPROFILE\vcpkg\bootstrap-vcpkg.bat'"

# Configure
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DCMAKE_TOOLCHAIN_FILE="$HOME/vcpkg/scripts/buildsystems/vcpkg.cmake"

# Build
cmake --build build --config Release

# Example
cmake -S example -B example/build -DCMAKE_BUILD_TYPE=Release
cmake --build example/build --config Release
```

### Linux (WSL/Ubuntu) – Quick start

Prerequisites (Ubuntu/Debian):

```bash
sudo apt-get update -y && sudo apt-get install -y \
  build-essential cmake git pkg-config libcurl4-openssl-dev \
  curl zip unzip tar ninja-build ca-certificates
```

Bootstrap vcpkg (once):

```bash
git clone https://github.com/microsoft/vcpkg.git "$HOME/vcpkg"
"$HOME/vcpkg/bootstrap-vcpkg.sh" -disableMetrics
```

Build (library, tests, example):

```bash
export VCPKG_ROOT="$HOME/vcpkg"
cmake -S . -B build -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Release -DCMAKE_TOOLCHAIN_FILE="$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake"
cmake --build build --config Release
```

Or simply use the helper script:

```bash
bash ./build.sh
```

Run the example:

```bash
./build/example/example
```

Run tests:

```bash
ctest --test-dir build --output-on-failure
```

Artifacts:

- Library: `build/libprivatebinapi.so`
- Example binary: `build/example/example`

Notes:

- vcpkg dependencies (`cryptopp`, `nlohmann-json`) are installed automatically during CMake configure when the toolchain file is provided.
- On Linux the example links directly against the in-tree target `privatebinapi`. On Windows it additionally copies the DLL next to the example executable after build.
- PrivateBin delete operation is performed via HTTP POST (per API), not HTTP DELETE.

### Windows (PowerShell) – Build via build_thinkpad.bat

For systems with Visual Studio 2022 Build Tools (C++ workload) and vcpkg in the user profile, there is a robust build script:

```
cd C:\Users\mbusc\source\repos\lib-privatebin
./build_thinkpad.bat
```

Notes:
- Requires Visual Studio 2022 Build Tools with C++ tools and the Windows 11 SDK. If `VsDevCmd.bat` is found, the script automatically initializes the MSVC environment.
- vcpkg is bootstrapped if needed; missing dependencies (`cryptopp`, `nlohmann-json`) are installed.
- If vcpkg requires a baseline, the script sets it automatically.

Edition/Path notes:
- If you use another VS edition (e.g., Professional/Enterprise), adjust the paths in `build_thinkpad.bat`:
  - `C:\Program Files\Microsoft Visual Studio\2022\Professional\Common7\Tools\VsDevCmd.bat`
  - `C:\Program Files\Microsoft Visual Studio\2022\Enterprise\Common7\Tools\VsDevCmd.bat`
- Alternatively, you can use `vswhere.exe` to discover the installation path:
  ```powershell
  & 'C:\Program Files\Microsoft Visual Studio\Installer\vswhere.exe' -latest -products * -requires Microsoft.VisualStudio.Component.VC.Tools.x86.x64 -property installationPath
  ```

## Usage

### API Functions

```cpp
// Create a new paste
int create_paste(const char* server_url, const char* content, 
                 const char* password, const char* expiration,
                 const char* format, int burn_after_reading, 
                 int open_discussion, char** paste_url, 
                 char** delete_token);

// Retrieve a paste
int get_paste(const char* server_url, const char* paste_id, 
              const char* key, char** content);

// Delete a paste
int delete_paste(const char* server_url, const char* paste_id, 
                 const char* delete_token);

// Free memory allocated by the API functions
void free_string(char* str);
```

### Example

```cpp
#include "privatebinapi.h"
#include <iostream>

int main() {
    char* paste_url = nullptr;
    char* delete_token = nullptr;
    
    int result = create_paste(
        "https://privatebin.net",
        "Hello, PrivateBin!",
        nullptr,           // No password
        "1hour",           // Expire in 1 hour
        "plaintext",       // Plain text format
        0,                 // Don't burn after reading
        0,                 // No discussion
        &paste_url,
        &delete_token
    );
    
    if (result == 0) {
        std::cout << "Paste created: " << paste_url << std::endl;
        std::cout << "Delete token: " << delete_token << std::endl;
        
        // Free allocated memory
        free_string(paste_url);
        free_string(delete_token);
    } else {
        std::cout << "Failed to create paste: " << result << std::endl;
    }
    
    return 0;
}
```

## Error Codes

- 0: Success
- 1: Network error
- 2: Encryption/decryption error
- 3: Invalid input
- 4: Server error
- 5: JSON parsing error

## License

This project is licensed under the MIT License - see the LICENSE file for details.

## Troubleshooting

- vcpkg requires a baseline / "this vcpkg instance requires a manifest with a specified baseline"
  - Run in the repo root to add an initial builtin baseline to `vcpkg.json`:
    ```powershell
    $env:VCPKG_ROOT = "$env:USERPROFILE\vcpkg"
    & "$env:VCPKG_ROOT\vcpkg.exe" x-update-baseline --add-initial-baseline
    ```
  - Then configure/build again.

- Visual Studio instance not found / "could not find specified instance of Visual Studio"
  - Ensure VS 2022 Build Tools or Community with C++ tools and Windows 11 SDK are installed.
  - Use the Developer Command Prompt (VsDevCmd):
    ```powershell
    cmd /c "call `"C:\\Program Files (x86)\\Microsoft Visual Studio\\2022\\BuildTools\\Common7\\Tools\\VsDevCmd.bat`" -arch=x64 && build.bat"
    ```
  - Or delete the build folder to clear stale CMake cache and reconfigure:
    ```powershell
    Remove-Item -Recurse -Force build
    ```

- `vswhere.exe` not found
  - Add the VS Installer directory to PATH for the current session:
    ```powershell
    $env:PATH = 'C:\\Program Files\\Microsoft Visual Studio\\Installer;' + $env:PATH
    ```
  - Or install/download `vswhere` from Microsoft and place it under the Installer folder.

- `cryptoppConfig.cmake` / `cryptopp-config.cmake` not found during CMake configure
  - Make sure CMake uses vcpkg's toolchain file and that the ports are installed for the active triplet:
    ```powershell
    $env:VCPKG_ROOT = "$env:USERPROFILE\vcpkg"
    cmake -S . -B build -DCMAKE_TOOLCHAIN_FILE="$env:VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake"
    & "$env:VCPKG_ROOT\vcpkg.exe" install cryptopp nlohmann-json --triplet x64-windows
    ```

- PowerShell line continuation issues / parser errors
  - Prefer single-line commands in PowerShell (avoid backticks if unsure). The README uses single-line examples for reliability.

## LLVM/clang-cl Coverage (Windows)

Requirements:
- clang/clang-cl toolchain installed
- LLVM tools on PATH (`llvm-profdata`, `llvm-cov`)

Configure with coverage:
```powershell
cmd /c "call ""C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\Common7\Tools\VsDevCmd.bat"" -arch=x64 && cmake -S . -B build-llvm -G "Ninja" -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang-cl -DENABLE_LLVM_COVERAGE=ON -DCMAKE_BUILD_TYPE=Release -DCMAKE_TOOLCHAIN_FILE=""%USERPROFILE%\vcpkg\scripts\buildsystems\vcpkg.cmake"" && cmake --build build-llvm --config Release"
```

Run coverage target (executes tests, merges profiles, generates HTML report):
```powershell
cmd /c "call ""C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\Common7\Tools\VsDevCmd.bat"" -arch=x64 && cmake --build build-llvm --target coverage_llvm --config Release && start build-llvm\coverage\html\index.html"
```

Notes:
- If Ninja is not available, you can use the VS generator, but Ninja is recommended for clang.
- You can override `LLVM_PROFDATA` and `LLVM_COV` cache variables to absolute tool paths if needed.

### Windows – Quick start (vcpkg + VS 2022)

Build and package using the helper script:

```powershell
$env:VCPKG_ROOT = "$env:USERPROFILE\vcpkg"
if (-not (Test-Path $env:VCPKG_ROOT)) { git clone https://github.com/microsoft/vcpkg $env:VCPKG_ROOT; & "$env:VCPKG_ROOT\bootstrap-vcpkg.bat" }
powershell -NoProfile -ExecutionPolicy Bypass -File .\build_windows.ps1
```

Artifacts:

- DLL/LIB in `build\Release` and packaged zip at `dist\lib-privatebin-v0.1.1.3-windows-x64.zip`
- Example: `build\example\Release\example.exe` (also included in the zip if present)

Notes:

- Ensure Visual Studio 2022 Build Tools (C++ workload) and Windows 11 SDK are installed.
- The example links against the in-tree library target. The script copies DLL/LIB/PDB (if available), headers, README, and LICENSE into the package.