boilstream

22.2k downloads this week 12 stars Extension descriptor

Secure remote secrets storage with OPAQUE PAKE authentication, email/password registration, MFA login, and automatic ducklake mounting

Compatibility Matrix

This table covers all DuckDB releases that have not reached end-of-life, including LTS releases, and shows the 2 most recent patch releases of each. Older patch releases are not listed, but the extension may be available for them as well.

Installing and Loading

INSTALL boilstream FROM community;
LOAD boilstream;

Example

-- Setup: Install and load boilstream extension
INSTALL httpfs; LOAD httpfs;
INSTALL boilstream FROM community;
LOAD boilstream;

-- Option 1: Login with email/password/MFA (establishes OPAQUE session)
--     NOTE: Remember to clean up your ~/.duckdb/history
PRAGMA boilstream_login('https://api.example.com/[email protected]', 'password', '123456');
┌────────────────────────┬─────────────────────┬────────────────────┐
│         status         │     expires_at      │ ducklakes_attached │
├────────────────────────┼─────────────────────┼────────────────────┤
│ Session token obtained │ 2025-11-21 10:30:00 │                  2 │
└────────────────────────┴─────────────────────┴────────────────────┘

-- Option 2: Authenticate with bootstrap token (from SSO/web UI)
PRAGMA boilstream_bootstrap_session('https://api.example.com/secrets:TOKEN');
┌────────────────────────┬─────────────────────┬────────────────────┐
│         status         │     expires_at      │ ducklakes_attached │
├────────────────────────┼─────────────────────┼────────────────────┤
│ Session token obtained │ 2025-11-21 10:30:00 │                  2 │
└────────────────────────┴─────────────────────┴────────────────────┘

-- List all available ducklakes
FROM boilstream_ducklakes();
┌──────────────┬──────────────┬─────────────────┐
│ catalog_id   │ catalog_name │   description   │
├──────────────┼──────────────┼─────────────────┤
│ 5a805647-... │ my_analytics │ Sales analytics │
└──────────────┴──────────────┴─────────────────┘

-- List all cached secrets with expiration
FROM boilstream_secrets();
┌─────────────────────┬──────────┬─────────────────────┐
│        name         │   type   │     expires_at      │
├─────────────────────┼──────────┼─────────────────────┤
│ my_analytics        │ ducklake │ 2026-11-19 20:00:00 │
│ my_analytics_s3     │ s3       │ 2026-11-19 20:00:00 │
│ my_analytics_pg     │ postgres │ 2026-11-19 20:00:00 │
└─────────────────────┴──────────┴─────────────────────┘

-- Create new ducklake
PRAGMA boilstream_create_ducklake('new_catalog', 'My new ducklake');

-- Query ducklake (automatically attached)
USE my_analytics;
SHOW TABLES;

-- Create persistent secret onto BoilStream server
CREATE PERSISTENT SECRET s3_minio IN boilstream (
    TYPE S3,
    KEY_ID 'minioadmin',
    SECRET 'minioadmin',
    REGION 'eu-west-1',
    ENDPOINT 'localhost:9000',
    USE_SSL false,
    URL_STYLE 'path',
    SCOPE 's3://ingestion-data/'
);

About boilstream

Boilstream extension provides enterprise-grade remote secrets storage for multi-tenant DuckDB deployments.

Features:

• 🔐 OPAQUE PAKE Authentication - Password-less authentication (IETF RFC 9807)
• 🔒 End-to-end Encryption - AES-256-GCM/ChaCha20-Poly1305 for secrets and responses
• 🔑 Cryptographic Key Derivation - HKDF-SHA256 with domain separation
• 🛡️ Defense in Depth - HMAC verification before AEAD decryption
• 🎯 Session Protection - Lock-step sequence protocol prevents hijacking
• 🗄️ Ducklake Support - Auto-attach multi-tenant data catalogs
• 🌐 SSO Integration - Bootstrap token exchange for web environments

Security:

• Facebook's audited OPAQUE implementation (Rust + C++ FFI)
• Protects against MITM attacks even if TLS is compromised
• One-time bootstrap tokens with anonymous authentication
• Session resumption with encrypted refresh tokens
• Comprehensive test vectors and security specification

API Functions:

• PRAGMA boilstream_register_user(url_with_email, password) - Register new user with MFA (displays QR code)
• PRAGMA boilstream_verify_mfa(totp_code) - Complete registration and get backup codes
• PRAGMA boilstream_login(url_with_email, password, mfa_code) - Email/password/MFA login
• PRAGMA boilstream_bootstrap_session(url_with_token) - Authenticate with bootstrap token
• boilstream_ducklakes() - List available ducklakes
• boilstream_secrets() - List cached secrets with expiration
• boilstream_buckets() - List available storage buckets
• PRAGMA boilstream_create_ducklake(name, description) - Create new ducklake
• PRAGMA boilstream_help - Show all available commands

Requirements:

• httpfs extension (auto-loaded)
• postgres_scanner extension (auto-loaded)
• ducklake extension (auto-loaded)
• Compatible REST API server (see API specification)

For detailed documentation, security specification, and setup instructions, visit the extension repository.

Added Functions

Overloaded Functions

This extension does not add any function overloads.

Added Types

This extension does not add any types.

Added Settings