FlashPaper

Documentation

Welcome to the FlashPaper documentation. Select a topic below or scroll down for comprehensive reference material.

1. Installation

1.1 Docker (Recommended)

The simplest way to deploy FlashPaper is using Docker Compose:

# Clone the repository
git clone https://github.com/liskl/flashpaper.git
cd flashpaper

# Start with PostgreSQL backend
docker-compose up -d

# View logs
docker-compose logs -f

# Access the application
open http://localhost:8080

1.2 Docker with SQLite

For simpler deployments without an external database:

docker run -d \
  --name flashpaper \
  -p 8080:8080 \
  -v flashpaper-data:/data \
  -e FLASHPAPER_MODEL_CLASS=Database \
  -e FLASHPAPER_MODEL_DRIVER=sqlite3 \
  -e FLASHPAPER_MODEL_DSN=/data/flashpaper.db \
  flashpaper:latest

1.3 Build from Source

Requires Go 1.21+ and CGO for SQLite support:

# Clone and build
git clone https://github.com/liskl/flashpaper.git
cd flashpaper
CGO_ENABLED=1 go build -o flashpaper ./cmd/flashpaper

# Run with default configuration
./flashpaper

# Run with custom config file
./flashpaper -config /path/to/config.ini

1.4 System Requirements

• Memory: 64MB minimum, 128MB recommended
• Storage: Depends on usage; ~1KB per paste average
• CPU: Any modern processor; single core sufficient for most deployments
• Network: HTTPS termination recommended (via reverse proxy)

2. Configuration

FlashPaper can be configured via INI file or environment variables. Environment variables override file settings and use the format: FLASHPAPER_SECTION_KEY

2.1 Core Settings

2.2 Storage Backend

DSN Examples

# SQLite
FLASHPAPER_MODEL_DSN=/data/flashpaper.db

# PostgreSQL
FLASHPAPER_MODEL_DSN=postgres://user:password@localhost:5432/flashpaper?sslmode=disable

# MySQL
FLASHPAPER_MODEL_DSN=user:password@tcp(localhost:3306)/flashpaper?charset=utf8mb4

2.3 Expiration Settings

Available expiration options: 5min, 10min, 1hour, 1day, 1week, 1month, 1year, never

2.4 Rate Limiting

2.5 INI File Example

[main]
name = "FlashPaper"
host = "0.0.0.0"
port = 8080
basepath = "/"
discussion = true
sizelimit = 10485760

[model]
class = "Database"
driver = "postgres"
dsn = "postgres://flashpaper:password@db:5432/flashpaper?sslmode=disable"

[expire]
default = "1week"

[traffic]
limit = 10

[purge]
limit = 300
batchsize = 10

3. API Reference

FlashPaper implements a PrivateBin-compatible REST API. All responses use JSON format with a status field (0 = success, 1 = error).

3.1 Create Paste

{
  "v": 2,
  "ct": "base64_encoded_ciphertext",
  "adata": [
    ["IV_base64", "salt_base64", 100000, 256, 128, "aes", "gcm", "none"],
    "plaintext",
    0,
    0
  ],
  "meta": {
    "expire": "1week"
  }
}

{
  "status": 0,
  "id": "f468483c313401e8",
  "url": "/?f468483c313401e8",
  "deletetoken": "a1b2c3d4e5f6..."
}

3.2 Retrieve Paste

{
  "status": 0,
  "id": "f468483c313401e8",
  "url": "/?f468483c313401e8",
  "v": 2,
  "ct": "base64_encoded_ciphertext",
  "adata": [...],
  "meta": {
    "postdate": 1703001234,
    "opendiscussion": false
  },
  "comments": []
}

3.3 Delete Paste

{
  "pasteid": "f468483c313401e8",
  "deletetoken": "a1b2c3d4e5f6..."
}

{
  "status": 0,
  "id": "f468483c313401e8"
}

3.4 Health Check

{"status": "ok"}

3.5 Error Responses

All error responses follow this format:

{
  "status": 1,
  "message": "Error description"
}

4. Client Integration

4.1 Encryption Requirements

Clients must implement client-side encryption before sending data to the API. See the Implementation Details for cryptographic specifications.

4.2 URL Structure

https://example.com/?{pasteId}#{key}
                    │           │         │
                    │           │         └── Base58-encoded encryption key (never sent to server)
                    │           └── 16-character hex paste ID
                    └── Server origin

4.3 AData Structure

The adata array contains encryption parameters and paste settings:

[
  [
    "IV_base64",      // Initialization vector
    "salt_base64",    // PBKDF2 salt
    100000,           // Iteration count
    256,              // Key size in bits
    128,              // Authentication tag size
    "aes",            // Algorithm
    "gcm",            // Mode
    "none"            // Compression ("none" or "zlib")
  ],
  "plaintext",        // Formatter: "plaintext", "syntaxhighlighting", "markdown"
  0,                  // Open discussion: 0 or 1
  0                   // Burn after reading: 0 or 1
]

5. Troubleshooting

5.1 Common Issues

Database Connection Errors

• Verify the DSN format matches your database driver
• Ensure FLASHPAPER_MODEL_DRIVER is set correctly
• Check network connectivity to the database server
• For PostgreSQL, ensure the database exists and user has permissions

Decryption Failures

• Ensure the complete URL including fragment (#key) is shared
• Verify the paste hasn't expired or been deleted
• Check if password protection was enabled (requires correct password)

Container Won't Start

• Check logs: docker-compose logs flashpaper
• Verify environment variables are correctly formatted
• Ensure the data volume has correct permissions

5.2 Debug Mode

Enable verbose logging by checking container logs:

docker-compose logs -f flashpaper

5.3 Getting Help

• GitHub Issues: Report bugs or request features
• Source Code: View the source