toolkit-zero

A feature-selective Rust utility crate. Declare only the modules your project requires via Cargo feature flags; each feature compiles exclusively the code it depends on, with no extraneous overhead.

1. Overview

2. Feature flags

3. Serialization

• Plain routes
• JSON body routes
• Query parameter routes
• Shared state
• Combining state with body / query
• Encrypted routes
• Serving the server
• Graceful shutdown
• Background server
• Building responses
• Sync handlers
• #[mechanism] attribute macro

• Creating a client
• Plain requests
• JSON body requests
• Query parameter requests
• Encrypted requests
• Sync vs async sends
• #[request] attribute macro

• Blocking usage
• Async usage
• #[browser] attribute macro
• Page templates
• LocationData fields
• Errors

• Features
• KDF presets
• Usage

• Sections captured
• Setup
• Usage
• Debug export
• #[dependencies] attribute macro
• Risks and considerations

• CLI launch options
• Rust API — launch functions
• Target variants
• Programmatic control — BrowserHandle
• TabTarget
• ThemeMode
• Downloads panel

Overview

toolkit-zero follows a strict zero-overhead model: only the features you declare are compiled into your binary. Every module is isolated behind an independent feature gate; enabling a feature introduces exactly the dependencies that module requires — nothing more.

Feature flags

Add with cargo add:

# Serialization (ChaCha20-Poly1305) only
cargo add toolkit-zero --features serialization

# HTTP server only
cargo add toolkit-zero --features socket-server

# HTTP client only
cargo add toolkit-zero --features socket-client

# Both sides
cargo add toolkit-zero --features socket

# Geolocation (pulls in socket-server automatically)
cargo add toolkit-zero --features location

# Full time-lock encryption suite
cargo add toolkit-zero --features encryption

# Attach build-time fingerprint in build.rs
cargo add toolkit-zero --build --features dependency-graph-build

# Read build-time fingerprint at runtime
cargo add toolkit-zero --features dependency-graph-capture

# Browser (WebKit window + downloads + programmatic API)
cargo add toolkit-zero --features browser

# Re-export deps alongside socket-server
cargo add toolkit-zero --features socket-server,backend-deps

Serialization

Feature: serialization

ChaCha20-Poly1305 authenticated encryption transforms any bincode-encodable value into an opaque, authenticated byte blob. Without the correct key the ciphertext cannot be decrypted; any bit-level tampering is detected and rejected by the Poly1305 tag.

Keys are moved into seal/open and wrapped in Zeroizing<String> internally, wiping them from memory on drop.

Entry points:

key is Option<String>. Pass None to use the built-in default key.

Types must derive Encode and Decode:

use toolkit_zero::serialization::{seal, open, Encode, Decode};

#[derive(Encode, Decode, Debug, PartialEq)]
struct Config {
    threshold: f64,
    label: String,
}

// With the default key
let cfg = Config { threshold: 0.85, label: "prod".into() };
let blob = seal(&cfg, None).unwrap();
let back: Config = open(&blob, None).unwrap();
assert_eq!(cfg, back);

// With a custom shared key (moved in, zeroized on drop)
let blob2 = seal(&cfg, Some("my-secret".to_string())).unwrap();
let back2: Config = open(&blob2, Some("my-secret".to_string())).unwrap();
assert_eq!(cfg, back2);

#[serializable] — inject methods directly on a struct or enum:

use toolkit_zero::serialization::serializable;

#[serializable]
struct Config { host: String, port: u16 }

let c = Config { host: "localhost".into(), port: 8080 };
let blob = c.seal(None).unwrap();
let back = Config::open(&blob, None).unwrap();

// Per-field encrypted helpers:
#[serializable]
struct Creds {
    pub user: String,
    #[serializable(key = "field-secret")]
    pub password: String,
}
// → Creds::seal_password(&self), Creds::open_password(bytes)

#[serialize] / #[deserialize] — inline seal/open as statements:

use toolkit_zero::serialization::{serialize, deserialize};

// Variable mode
#[serialize(cfg, key = my_key)]
fn blob() -> Vec<u8> {}
// expands to: let blob: Vec<u8> = seal(&cfg, Some(my_key))?;

// File write mode
#[serialize(cfg, path = "config.bin")]
fn _() {}
// expands to: fs::write("config.bin", seal(&cfg, None)?)?;

// Deserialize from file
#[deserialize(path = "config.bin", key = my_key)]
fn cfg() -> Config {}
// expands to: let cfg: Config = open::<Config>(&fs::read("config.bin")?, Some(my_key))?;

Socket — server

Feature: socket-server

A fluent, type-safe builder API for declaring and serving HTTP routes. Each route originates from a ServerMechanism, is optionally enriched with JSON body, query parameter, or shared-state expectations, and is finalised via .onconnect(handler). Registered routes are served through a single .await call on the Server.

Plain routes

No body and no query. The handler receives nothing.

use toolkit_zero::socket::server::{Server, ServerMechanism, reply};

let mut server = Server::default();
server.mechanism(
    ServerMechanism::get("/health")
        .onconnect(|| async { reply!() })
);

All standard HTTP methods are available: get, post, put, delete, patch, head, and options.

JSON body routes

Call .json::<T>() on the mechanism. The request body is deserialised as T before the handler is invoked; the handler always receives a validated, typed value. T must implement serde::Deserialize. A missing or malformed body automatically yields a 400 Bad Request response.

use serde::Deserialize;
use toolkit_zero::socket::server::{Server, ServerMechanism, reply, Status};

#[derive(Deserialize)]
struct CreateItem { name: String }

#[derive(serde::Serialize)]
struct Item { id: u32, name: String }

let mut server = Server::default();
server.mechanism(
    ServerMechanism::post("/items")
        .json::<CreateItem>()
        .onconnect(|body: CreateItem| async move {
            let item = Item { id: 1, name: body.name };
            reply!(json => item, status => Status::Created)
        })
);

Query parameter routes

Call .query::<T>() on the mechanism. Incoming query parameters are deserialised as T before the handler is invoked; the handler always receives a validated, typed value. T must implement serde::Deserialize.

URL shape the server expects:

GET /search?q=hello&page=2

Each field of T maps to one key=value pair. Nested structs are not supported by serde_urlencoded; keep query types flat.

use serde::Deserialize;
use toolkit_zero::socket::server::{Server, ServerMechanism, reply};

#[derive(Deserialize)]
struct SearchParams {
    q:    String,  // ?q=hello
    page: u32,     // &page=2
}

let mut server = Server::default();
server.mechanism(
    // Listens on GET /search?q=<string>&page=<u32>
    ServerMechanism::get("/search")
        .query::<SearchParams>()
        .onconnect(|params: SearchParams| async move {
            // params.q  == "hello"
            // params.page == 2
            reply!()
        })
);

Missing or malformed query parameters cause the server to return 400 Bad Request before the handler is invoked.

Shared state

Call .state(value) on the mechanism. A cloned instance of the state is provided to each request handler. The state type must satisfy Clone + Send + Sync + 'static. Wrap mutable shared state in Arc<Mutex<_>> or Arc<RwLock<_>>.

use std::sync::{Arc, Mutex};
use serde::Serialize;
use toolkit_zero::socket::server::{Server, ServerMechanism, reply};

#[derive(Serialize, Clone)]
struct Item { id: u32, name: String }

let store: Arc<Mutex<Vec<Item>>> = Arc::new(Mutex::new(vec![]));

let mut server = Server::default();
server.mechanism(
    ServerMechanism::get("/items")
        .state(store.clone())
        .onconnect(|state: Arc<Mutex<Vec<Item>>>| async move {
            let items = state.lock().unwrap().clone();
            reply!(json => items)
        })
);

Combining state with body / query

State may be combined with a body or query expectation. The call order of .state() and .json() / .query() is not significant; the handler always receives (state: S, body_or_query: T).

use std::sync::{Arc, Mutex};
use serde::{Deserialize, Serialize};
use toolkit_zero::socket::server::{Server, ServerMechanism, reply, Status};

#[derive(Deserialize)]
struct NewItem { name: String }

#[derive(Serialize, Clone)]
struct Item { id: u32, name: String }

let store: Arc<Mutex<Vec<Item>>> = Arc::new(Mutex::new(vec![]));

let mut server = Server::default();
server.mechanism(
    ServerMechanism::post("/items")
        .json::<NewItem>()
        .state(store.clone())
        .onconnect(|state: Arc<Mutex<Vec<Item>>>, body: NewItem| async move {
            let id = {
                let mut s = state.lock().unwrap();
                let id = s.len() as u32 + 1;
                s.push(Item { id, name: body.name.clone() });
                id
            };
            reply!(json => Item { id, name: body.name }, status => Status::Created)
        })
);

Encrypted routes

Call .encryption::<T>(key) (body) or .encrypted_query::<T>(key) (query) on the mechanism. Provide a SerializationKey::Default (built-in key) or SerializationKey::Value("your-key") (custom key).

Before the handler is called, the body or query is decrypted (ChaCha20-Poly1305) using the supplied key. A wrong key, mismatched secret, or corrupt payload returns 403 Forbidden without ever reaching the handler. The T the closure receives is always a trusted, fully-decrypted value.

T must implement bincode::Decode<()>.

use bincode::{Encode, Decode};
use toolkit_zero::socket::SerializationKey;
use toolkit_zero::socket::server::{Server, ServerMechanism, reply};

#[derive(Decode)]
struct SealedRequest { value: i32 }

#[derive(Encode)]
struct SealedResponse { result: i32 }

let mut server = Server::default();
server.mechanism(
    ServerMechanism::post("/compute")
        .encryption::<SealedRequest>(SerializationKey::Default)
        .onconnect(|req: SealedRequest| async move {
            reply!(sealed => SealedResponse { result: req.value * 2 })
        })
);

For encrypted query parameters, the client sends ?data=<base64url> where the value is URL-safe base64 of the ChaCha20-Poly1305-sealed struct bytes.

Serving the server

// Bind to a specific address — runs until the process exits
server.serve(([0, 0, 0, 0], 8080)).await;

Note: Routes are evaluated in registration order — the first matching route wins. serve(), serve_with_graceful_shutdown(), and serve_from_listener() all panic immediately if called on a Server with no routes registered.

Graceful shutdown

use tokio::sync::oneshot;

let (tx, rx) = oneshot::channel::<()>();

// Shut down later by calling: tx.send(()).ok();
server.serve_with_graceful_shutdown(([127, 0, 0, 1], 8080), async move {
    rx.await.ok();
}).await;

To use an OS-assigned port (e.g. to know the port before the server starts):

use tokio::net::TcpListener;
use tokio::sync::oneshot;

let listener = TcpListener::bind("127.0.0.1:0").await?;
let port = listener.local_addr()?.port();

let (tx, rx) = oneshot::channel::<()>();
server.serve_from_listener(listener, async move { rx.await.ok(); }).await;

Background server

Call serve_managed(addr) instead of serve(addr) to get a BackgroundServer handle. The server starts immediately; the handle lets you inspect and mutate the running instance:

use toolkit_zero::socket::server::{Server, ServerMechanism, reply};
use serde::Serialize;

#[derive(Serialize)] struct Pong   { ok:  bool   }
#[derive(Serialize)] struct Status { msg: String }

#[tokio::main]
async fn main() {
    let mut server = Server::default();
    server.mechanism(
        ServerMechanism::get("/ping")
            .onconnect(|| async { reply!(json => Pong { ok: true }) })
    );

    let mut bg = server.serve_managed(([127, 0, 0, 1], 8080));
    println!("Listening on {}", bg.addr());

    // Hot-plug a new route — no restart, no port gap
    bg.mechanism(
        ServerMechanism::get("/status")
            .onconnect(|| async { reply!(json => Status { msg: "ok".into() }) })
    ).await;

    // Migrate to a different port — in-flight requests finish first
    bg.rebind(([127, 0, 0, 1], 9090)).await;
    println!("Rebound to {}", bg.addr());

    bg.stop().await;
}

All routes registered before serve_managed and those added via bg.mechanism are automatically carried over when rebind is called.

Building responses

Use the reply! macro:

Status re-exports the most common HTTP status codes as named variants (Status::Ok, Status::Created, Status::NoContent, Status::BadRequest, Status::Forbidden, Status::NotFound, Status::InternalServerError).

Sync handlers

Every route finaliser (onconnect) provides an unsafe blocking counterpart, onconnect_sync, for cases where an existing synchronous API cannot readily be made asynchronous. This variant is not recommended for production traffic.

use toolkit_zero::socket::server::{Server, ServerMechanism, reply};

let mut server = Server::default();

// SAFETY: handler is fast; no shared mutable state; backpressure applied externally
unsafe {
    server.mechanism(
        ServerMechanism::get("/ping").onconnect_sync(|| {
            reply!()
        })
    );
}

unsafe is required because onconnect_sync dispatches work to Tokio's blocking thread pool, which carries important caveats:

• The pool limits live OS threads to 512 (default), but the waiting-task queue is unbounded. Under sustained traffic, queued tasks can accumulate without bound, risking out-of-memory conditions or severe latency before any task executes.
• Panics inside the handler are silently converted to a 500 Internal Server Error response, masking runtime errors.
• Handlers that hold a lock (e.g. Arc<Mutex<_>>) can stall the thread pool indefinitely under contention from concurrent blocking tasks.

onconnect_sync is available on every builder variant: plain, .json, .query, .state, and their combinations. All have identical safety requirements.

#[mechanism] attribute macro

The #[mechanism] attribute is a concise alternative to the builder calls above. It replaces the decorated async fn in-place with the equivalent server.mechanism(…) statement — no separate registration step required.

use toolkit_zero::socket::server::{Server, mechanism, reply, Status};
use serde::{Deserialize, Serialize};
use std::sync::{Arc, Mutex};

#[derive(Deserialize)]                  struct NewItem  { name: String }
#[derive(Serialize, Clone)]             struct Item     { id: u32, name: String }

#[tokio::main]
async fn main() {
    let mut server = Server::default();
    let db: Arc<Mutex<Vec<Item>>> = Arc::new(Mutex::new(vec![]));

    // No body, no state
    #[mechanism(server, GET, "/health")]
    async fn health() { reply!() }

    // JSON body
    #[mechanism(server, POST, "/items", json)]
    async fn create_item(body: NewItem) {
        reply!(json => Item { id: 1, name: body.name }, status => Status::Created)
    }

    // State + JSON body
    #[mechanism(server, POST, "/items/add", state(db.clone()), json)]
    async fn add_item(db: Arc<Mutex<Vec<Item>>>, body: NewItem) {
        let id = db.lock().unwrap().len() as u32 + 1;
        let item = Item { id, name: body.name };
        db.lock().unwrap().push(item.clone());
        reply!(json => item, status => Status::Created)
    }

    server.serve(([127, 0, 0, 1], 8080)).await;
}

Supported forms:

The keywords after the path (json, query, state, encrypted, encrypted_query) may appear in any order.

Socket — client

Feature: socket-client

A fluent, type-safe builder API for issuing HTTP requests. Construct a Client from a Target, select an HTTP method, optionally attach a body or query parameters, and call .send().await (async) or .send_sync() (blocking).

Creating a client

use toolkit_zero::socket::client::{Client, Target};

// Async-only — safe to create inside #[tokio::main]
let client = Client::new_async(Target::Localhost(8080));

// Sync-only — must be created before entering any async runtime
let client = Client::new_sync(Target::Localhost(8080));

// Both async and blocking — must be created before entering any async runtime
let client = Client::new(Target::Localhost(8080));

// Remote target
let client = Client::new_async(Target::Remote("https://api.example.com".into()));

Why Client::new() and Client::new_sync() panic inside an async context: reqwest::blocking::Client creates its own single-threaded Tokio runtime internally. Tokio does not allow a runtime to start while another is already running on the same thread. Client::new() proactively detects this via tokio::runtime::Handle::try_current() and panics at construction time with an actionable message before any field is initialised. Client::new_sync() fails the same way through reqwest during construction.

Guidance:

• Async programs (#[tokio::main]) — use Client::new_async().
• Synchronous programs with no runtime — use Client::new_sync() or Client::new().
• Programs combining a synchronous entry point with a manual tokio::Runtime — construct the Client before starting the runtime.

Plain requests

use serde::Deserialize;

#[derive(Deserialize)]
struct Item { id: u32, name: String }

// Async
let item: Item = client.get("/items/1").send().await?;

// Sync
let item: Item = client.get("/items/1").send_sync()?;

All standard HTTP methods are available: get, post, put, delete, patch, head, and options.

JSON body requests

Attach a request body with .json(value). value must implement serde::Serialize; the response is deserialised as R: serde::Deserialize.

use serde::{Deserialize, Serialize};

#[derive(Serialize)]
struct NewItem { name: String }

#[derive(Deserialize)]
struct Item { id: u32, name: String }

let created: Item = client
    .post("/items")
    .json(NewItem { name: "widget".into() })
    .send()
    .await?;

Query parameter requests

Attach query parameters with .query(value). value must implement serde::Serialize; the fields are serialised by serde_urlencoded and appended to the request URL as ?key=value&....

URL the client will send:

GET /items?status=active&page=1

use serde::{Deserialize, Serialize};

#[derive(Serialize)]
struct Filter {
    status: String,  // becomes ?status=active
    page:   u32,     // becomes &page=1
}

#[derive(Deserialize)]
struct Item { id: u32, name: String }

// Sends: GET /items?status=active&page=1
let items: Vec<Item> = client
    .get("/items")
    .query(Filter { status: "active".into(), page: 1 })
    .send()
    .await?;

URL parameter ordering follows struct field declaration order. Nested structs are not supported by serde_urlencoded; keep query types flat.

Encrypted requests

Attach a ChaCha20-Poly1305-sealed body with .encryption(value, key). The body is sealed prior to transmission; the response bytes are unsealed automatically. Both the request (T) and response (R) use bincode encoding: T must implement bincode::Encode and R must implement bincode::Decode<().

use bincode::{Encode, Decode};
use toolkit_zero::socket::SerializationKey;
use toolkit_zero::socket::client::ClientError;

#[derive(Encode)]
struct Req { value: i32 }

#[derive(Decode)]
struct Resp { result: i32 }

let resp: Resp = client
    .post("/compute")
    .encryption(Req { value: 21 }, SerializationKey::Default)
    .send()
    .await?;

For encrypted query parameters, use .encrypted_query(value, key). The params are sealed (ChaCha20-Poly1305) and sent as ?data=<base64url>.

let resp: Resp = client
    .get("/compute")
    .encrypted_query(Req { value: 21 }, SerializationKey::Default)
    .send()
    .await?;

Both .send() and .send_sync() are available on encrypted builders, returning Result<R, ClientError>.

Sync vs async sends

Using the wrong variant panics at the call site with an explicit message pointing to the correct constructor:

• Calling .send() on a new_sync() client → "Client was created with new_sync() — call new_async() or new() to use async sends"
• Calling .send_sync() on a new_async() client → "Client was created with new_async() — call new_sync() or new() to use sync sends"

These call-site panics are distinct from the construction-time panic that Client::new() (and Client::new_sync()) raises when constructed inside an active Tokio runtime — see Creating a client.

#[request] attribute macro

The #[request] attribute is a concise alternative to the builder calls above. It replaces the decorated fn in-place with a let binding that performs the HTTP request — no separate variable declaration required. The function name becomes the binding name; the return type becomes R in the .send::<R>() turbofish. The function body is discarded.

use toolkit_zero::socket::client::{Client, Target, request};
use serde::{Deserialize, Serialize};

#[derive(Deserialize, Serialize, Clone)] struct Item    { id: u32, name: String }
#[derive(Serialize)]                     struct NewItem  { name: String }
#[derive(Serialize)]                     struct Filter   { page: u32 }

async fn example() -> Result<(), reqwest::Error> {
    let client = Client::new_async(Target::Localhost(8080));

    // Plain async GET
    #[request(client, GET, "/items", async)]
    async fn items() -> Vec<Item> {}

    // POST with JSON body
    #[request(client, POST, "/items", json(NewItem { name: "widget".into() }), async)]
    async fn created() -> Item {}

    // GET with query params
    #[request(client, GET, "/items", query(Filter { page: 2 }), async)]
    async fn page() -> Vec<Item> {}

    // Synchronous DELETE
    #[request(client, DELETE, "/items/1", sync)]
    fn deleted() -> Item {}

    Ok(())
}

Supported forms:

The return type annotation on the fn is required — omitting it is a compile error.

Location

Feature: location (or location-browser)

Acquires the device's geographic coordinates by opening a locally served consent page in the system default browser. The browser requests location permission through the standard Web Geolocation API; on approval, the coordinates are submitted to the local HTTP server. The server shuts itself down once a result is received and returns the data to the caller.

No external services are contacted. All network activity is confined to 127.0.0.1.

Blocking usage

Compatible with both synchronous entry points and active Tokio runtimes. When invoked within an existing runtime, an OS thread is spawned to avoid nesting runtimes.

use toolkit_zero::location::browser::{__location__, PageTemplate, LocationError};

match __location__(PageTemplate::default()) {
    Ok(data) => {
        println!("Latitude:  {:.6}", data.latitude);
        println!("Longitude: {:.6}", data.longitude);
        println!("Accuracy:  {:.0} m", data.accuracy);
    }
    Err(LocationError::PermissionDenied) => eprintln!("User denied location access"),
    Err(e) => eprintln!("Error: {e}"),
}

Async usage

Recommended when executing within an active Tokio runtime — eliminates the OS thread spawn required by the blocking variant.

use toolkit_zero::location::browser::{__location_async__, PageTemplate};

#[tokio::main]
async fn main() {
    match __location_async__(PageTemplate::default()).await {
        Ok(data) => println!("lat={:.6}  lon={:.6}", data.latitude, data.longitude),
        Err(e)   => eprintln!("Error: {e}"),
    }
}

#[browser] attribute macro

The #[browser] macro is a concise alternative to calling __location__ / __location_async__ directly. It replaces the decorated fn item with an inline location-capture statement. The function name becomes the binding; the PageTemplate is built from the macro arguments. A ? propagates any LocationError to the enclosing function.

All arguments are optional and may appear in any order:

use toolkit_zero::location::browser::{browser, LocationData, LocationError};

// Async, Default template — all built-in text
async fn run1() -> Result<LocationData, LocationError> {
    #[browser]
    fn loc() {}
    Ok(loc)
}

// Async, Tickbox with consent text
async fn run2() -> Result<LocationData, LocationError> {
    #[browser(tickbox, title = "Verify Location", consent = "I agree to share my location")]
    fn loc() {}
    Ok(loc)
}

// Async, completely custom HTML page
async fn run3() -> Result<LocationData, LocationError> {
    #[browser(html = "<!DOCTYPE html><html><body><h1>Grant access</h1>{}</body></html>")]
    fn loc() {}
    Ok(loc)
}

// Blocking, custom title
fn run4() -> Result<LocationData, LocationError> {
    #[browser(sync, title = "My App")]
    fn loc() {}
    Ok(loc)
}

Page templates

PageTemplate controls what the user sees in the browser.

use toolkit_zero::location::browser::{__location__, PageTemplate};

// Custom title only
let _data = __location__(PageTemplate::Default {
    title:     Some("My App — Verify Location".into()),
    body_text: None,
});

// Tick-box consent
let _data = __location__(PageTemplate::Tickbox {
    title:        None,
    body_text:    None,
    consent_text: Some("I agree to share my location with this app.".into()),
});

// Fully custom HTML
let html = r#"<!DOCTYPE html>
<html><body>
  <h1>Grant access</h1>
  {}
</body></html>"#;
let _data = __location__(PageTemplate::Custom(html.into()));

LocationData fields

LocationError variants

Encryption — Timelock

Feature: encryption (or any enc-timelock-* sub-feature)

Derives a deterministic 32-byte time-locked key through a three-pass, memory-hard KDF chain:

Argon2id (pass 1) → scrypt (pass 2) → Argon2id (pass 3)

The key is only reproducible at the right time with the right salts. Paired with a passphrase (joint KDF), the search space becomes time-window × passphrase-space — extremely expensive to brute-force.

Timelock features

KDF presets

KdfPreset provides named parameter sets calibrated per platform:

Timelock usage

use toolkit_zero::encryption::timelock::*;

// ── Encryption side ── caller sets the unlock time ─────────────────────────
let salts = TimeLockSalts::generate();
let kdf   = KdfPreset::BalancedMac.params();      // ~2 s on M2
let at    = TimeLockTime::new(14, 30).unwrap();
// params = None → _at (encryption) path
let enc_key = timelock(
    Some(TimeLockCadence::None),
    Some(at),
    Some(TimePrecision::Minute),
    Some(TimeFormat::Hour24),
    Some(salts.clone()),
    Some(kdf),
    None,
).unwrap();

// Pack all settings — including salts and KDF params — into a self-contained
// header.  Salts and KDF params are not secret; store the header in plaintext
// alongside the ciphertext so the decryption side can reconstruct the key.
let header = pack(TimePrecision::Minute, TimeFormat::Hour24,
                  &TimeLockCadence::None, salts, kdf);

// ── Decryption side ── re-derives from the live clock ───────────────────────
// Load header from ciphertext; call at 14:30 local time.
// params = Some(header) → _now (decryption) path
let dec_key = timelock(
    None, None, None, None, None, None,
    Some(header),
).unwrap();
assert_eq!(enc_key.as_bytes(), dec_key.as_bytes());

For async usage replace timelock with timelock_async and .await the result. All arguments are taken by value. Requires the matching enc-timelock-async-keygen-* feature(s).

Dependency Graph — BuildTimeFingerprint

Features: dependency-graph-build · dependency-graph-capture

BuildTimeFingerprint attaches a normalised, deterministic snapshot of the build environment to the compiled binary. The snapshot is written to $OUT_DIR/fingerprint.json at compile time and embedded via include_str!; no runtime I/O is required.

The two features are intentionally independent so that each can be declared in the appropriate Cargo.toml section.

Sections captured

Setup

[dependencies]
toolkit-zero = { features = ["dependency-graph-capture"] }

[build-dependencies]
toolkit-zero = { features = ["dependency-graph-build"] }

build.rs:

fn main() {
    // Pass true to also export a pretty-printed copy alongside Cargo.toml.
    toolkit_zero::dependency_graph::build::generate_fingerprint(cfg!(debug_assertions))
        .expect("fingerprint generation failed");
}

BuildTimeFingerprint usage

Embed and read the snapshot in your binary:

use toolkit_zero::dependency_graph::capture;

const BUILD_TIME_FINGERPRINT: &str = include_str!(concat!(env!("OUT_DIR"), "/fingerprint.json"));

fn main() {
    let data = capture::parse(BUILD_TIME_FINGERPRINT).expect("failed to parse fingerprint");

    println!("{} v{}", data.package.name, data.package.version);
    println!("profile  : {}", data.build.profile);
    println!("target   : {}", data.build.target);
    println!("rustc    : {}", data.build.rustc_version);
    println!("lock sha : {}", data.cargo_lock_sha256);

    for (file, hash) in &data.source {
        println!("{file} -> {hash}");
    }

    // raw bytes of the normalised JSON
    let raw: &[u8] = BUILD_TIME_FINGERPRINT.as_bytes();
    println!("{} bytes", raw.len());
}

BuildTimeFingerprintData fields:

Debug export

generate_fingerprint(true) (or the standalone export(true)) writes a pretty-printed fingerprint.json alongside the crate's Cargo.toml for local inspection. This file is distinct from the compact version written to $OUT_DIR; the binary always embeds the $OUT_DIR copy.

Passing true to generate_fingerprint only runs cargo metadata once, which is more efficient than calling generate_fingerprint(false) + export(true) separately.

Add fingerprint.json to .gitignore. The exported file contains the full dependency graph, per-file source hashes, target triple, and compiler version. Although the contents are not secret, committing the file adds repository noise and may expose build-environment details beyond what is intended.

#[dependencies] attribute macro

The #[dependencies] macro is a concise alternative to the include_str! + capture::parse() boilerplate. It requires the dependency-graph-capture feature.

Apply it to an empty fn inside a function body; the function name becomes the let binding:

use toolkit_zero::dependency_graph::capture::dependencies;

fn show() -> Result<(), Box<dyn std::error::Error>> {
    #[dependencies]          // → let data: BuildTimeFingerprintData = parse(...)?;
    fn data() {}
    println!("{} v{}", data.package.name, data.package.version);
    Ok(())
}

fn raw_bytes() -> &'static [u8] {
    #[dependencies(bytes)]   // → let raw: &'static [u8] = as_bytes(...);
    fn raw() {}
    raw
}

Risks and considerations

Backend deps

Feature: backend-deps

When combined with any other feature, backend-deps appends a backend_deps sub-module to each active module. Each such sub-module re-exports (via pub use) every third-party crate used internally by the parent module, allowing downstream crates to access those dependencies without separate Cargo.toml declarations.

Each re-export is individually gated on its parent feature; only the dependencies that are currently compiled appear in backend_deps. Enabling backend-deps without any other feature compiles successfully but exposes no symbols.

# Example: socket-server + dep re-exports
toolkit-zero = { features = ["socket-server", "backend-deps"] }

Then in your code:

// Access hyper directly through toolkit-zero
use toolkit_zero::socket::backend_deps::hyper;

// Access bincode through serialization
use toolkit_zero::serialization::backend_deps::bincode;

Browser — duct-tape

Feature: browser

duct-tape is a full-featured, WebKit-native browser window built on iced (GPU-accelerated UI) and wry (cross-platform WebView). It ships as a standalone binary (duct-tape) and as a fully programmable Rust library API, making it trivial to embed a production-grade browser into any Rust application.

The name reflects the philosophy: high-performance plumbing assembled from best-in-class components, with our own parallel download engine layered on top where the platform would otherwise bottleneck you.

Native WebKit — zero rendering overhead

duct-tape delegates all page rendering to the platform's own WebKit engine:

There is no Electron, no embedded Chromium, no extra process: the OS WebView is embedded directly inside the iced window via raw window handle. This means:

• Sub-millisecond page-layout and compositing (platform compositor handles it)
• Zero additional memory overhead for the renderer — the OS engine is already in RAM
• Full hardware acceleration — CSS transitions, WebGL, Canvas, video all run at native speed
• Every future platform WebKit security patch and performance improvement is inherited automatically, with no crate update required

The iced layer handles only the chrome (tabs, address bar, loading indicator, panels). It never touches the rendered web content.

Custom parallel download engine

By default, WebKit downloads files over a single TCP connection. duct-tape intercepts every download before WebKit touches it, cancels the native transfer, and routes it through our own parallel engine built on reqwest.

How it works

1. HEAD request — probes Content-Length and Accept-Ranges: bytes headers.
2. Threshold check — files below 4 MiB use a single streaming connection (HEAD overhead is not worth it).
3. Byte-range splitting — files ≥ 4 MiB are divided into 8 equal-size chunks. Each chunk is fetched with its own Range: bytes=X-Y HTTP request, in parallel, on separate TCP connections.
4. Streaming write — each chunk streams directly to its slice of the output file via .chunk() iteration (no full-chunk buffer). Memory usage stays flat regardless of file size.
5. Atomic rename — while downloading, the file lives at <name>.tkz (preventing accidental opens). On completion it is renamed to the final path atomically.
6. Fallback — servers without Accept-Ranges fall back to a single streaming connection automatically.

Performance comparison

In real-world benchmarks on CDN-hosted files (GitHub releases, package registries, etc.) duct-tape consistently achieves 3–8× higher throughput than a single-connection download.

Download resilience — stash and resume

Every in-flight download is persisted to a stash file (~/toolkit-zero/.browser-stash) the moment it starts. If the browser is closed mid-download the stash is read on the next launch and all interrupted transfers are automatically restarted from the beginning (byte-range resume is attempted for partially-written .tkz files).

Progress reporting

Progress flows from eight concurrent background tokio tasks through a process-global Mutex<Vec<ProgressUpdate>> queue. The iced Tick handler drains the queue every 16 ms (while downloads are active), applying updates directly to state so the UI paint picks them up in the same frame with no extra message-round-trip.

The downloads panel shows, per download:

• Filename and source URL
• ⬇ bytes downloaded / total size (e.g. ⬇ 124.3 MB / 550.0 MB)
• Live speed indicator (1.5 MB/s) computed as Δbytes / elapsed_since_last_tick
• Blacklight-purple progress bar (same colour as the window border trace)
• Action buttons: cancel (in-progress), open / reveal in Finder (completed), or clear (done)

Duplicate downloads

Re-clicking a link that is already being downloaded does not replace the existing entry. Each new click produces a new entry with a -2, -3, … suffix appended to the file stem (e.g. archive.zip, archive-2.zip, archive-3.zip). A 500 ms debounce window filters out WebKit's spurious double-fire of the download callback.

UI features

Tab system

• Floating squircle tabs with smooth pill-style activation glow
• Per-tab independent back / forward navigation history — switching tabs restores the correct page without re-requesting the server
• Two-finger horizontal swipe on macOS triggers browser back/forward natively via WebKit
• Tab groups with colour-coded indicators — create, rename, assign, delete groups; members can be cycled between groups with a right-click
• Opening a new tab always loads the built-in homepage

Address bar and URL resolution

The address bar (and all programmatic navigate calls) apply the same resolution logic:

Loading indicator

A thin perimeter-tracing line (the "border trace" / loader) animates around the window edge while a page is loading. The line is the same blacklight purple as the progress bar. Once the page finishes loading, the line fades out smoothly.

Theme system

Three modes selectable per-session (not persisted across restarts yet):

The theme is pushed into the embedded homepage via JavaScript (window.__tkzSetTheme) so the built-in page always matches the shell.

Persistent history

Every page visit is appended to ~/toolkit-zero/history.hist (toggle-able in the UI). The history panel supports:

• Time-based deletion with a slider + Hours / Days / Weeks / Months unit picker
• Delete all history in one click
• Click any entry to navigate

Quicklinks

The built-in homepage displays a grid of configurable quicklinks loaded from ~/toolkit-zero/quicklinks.json. Inject/update your quicklinks programmatically or edit the JSON directly.

macOS Dock icon

On macOS, the Dock tile icon is set at runtime via NSApplication::setApplicationIconImage: using objc2. Winit's window::Settings::icon is a no-op on macOS (per-window icons are not a platform concept), so duct-tape calls the AppKit API directly after the window is fully initialised.

CLI launch options

The duct-tape binary accepts optional arguments:

# Open the built-in homepage (default)
duct-tape

# Open a URL — back button returns to the homepage
duct-tape --url=https://example.com

# Address-bar resolution: adds https:// if no scheme; falls back to Google search
duct-tape --url=rust-lang.org
duct-tape --url="rust programming"

# Explicit Google search
duct-tape --search="cargo build flags"

# Open a local HTML file
duct-tape --file=/path/to/page.html

All flags perform safety checks — an empty value prints a usage message and exits with code 1.

Rust API — launch functions

All entry points block the calling thread (iced's event loop must run on the main thread). When called inside a tokio::task::block_in_place closure the async executor keeps running on other threads.

Target variants

Programmatic control — launch_with_controller (recommended)

The cleanest way to drive the browser programmatically. Pass an async closure; duct-tape creates the channel pair, spawns your closure as a tokio task, and starts the window — all in a single call.

use toolkit_zero::browser::{self, Target, api::{BrowserHandle, TabTarget, ThemeMode}};

#[tokio::main(flavor = "multi_thread")]
async fn main() -> Result<(), browser::BrowserError> {
    browser::launch_with_controller(Target::Default, |handle: BrowserHandle| async move {
        // Wait for the window to fully initialise before sending commands.
        tokio::time::sleep(std::time::Duration::from_secs(1)).await;

        // Navigate the active (visible) tab
        handle.navigate(TabTarget::Active, "https://docs.rs");

        // Open a brand-new tab at a URL
        handle.navigate(TabTarget::New, "https://crates.io");

        // Navigate an existing tab by 0-based index
        // (creates a new tab if the index is out of range)
        handle.navigate(TabTarget::Index(1), "https://example.com");

        // Open a new tab at the homepage
        handle.open_new_tab::<&str>(None);

        // Open a new tab at a URL
        handle.open_new_tab(Some("https://rust-lang.org"));

        // Trigger a parallel download — appears in the downloads panel
        handle.start_download("https://example.com/archive.zip");

        // Switch the colour theme
        handle.set_theme(ThemeMode::Dark);
    })
}

How launch_with_controller works internally

1. Creates a (BrowserHandle, ApiReceiver) pair.
2. Installs the receiver into the browser's process-global command queue.
3. Calls tokio::runtime::Handle::current().spawn(controller(handle)) — your closure starts running on the tokio runtime's worker threads.
4. Calls tokio::task::block_in_place(|| launch(target)) — blocks the calling thread for the event loop while keeping the tokio executor alive for your spawned task.

Programmatic control — launch_with_api (explicit)

For cases where you need to manage the channel pair yourself — e.g. storing the handle in shared state, passing it to multiple tasks with different lifetimes, or integrating with an existing tokio setup.

use toolkit_zero::browser::{self, Target, api::{BrowserHandle, TabTarget, ThemeMode}};

#[tokio::main(flavor = "multi_thread")]
async fn main() {
    let (handle, receiver) = BrowserHandle::new();

    // Clone the handle for each task that needs it.
    let h1 = handle.clone();
    let h2 = handle.clone();

    tokio::spawn(async move {
        tokio::time::sleep(std::time::Duration::from_secs(2)).await;
        h1.navigate(TabTarget::Active, "https://docs.rs");
    });

    tokio::spawn(async move {
        tokio::time::sleep(std::time::Duration::from_secs(10)).await;
        h2.set_theme(ThemeMode::Dark);
        h2.start_download("https://example.com/file.tar.gz");
    });

    // receiver is consumed here; handle stays alive as long as any clone exists.
    tokio::task::block_in_place(|| {
        browser::launch_with_api(Target::Default, receiver)
    }).unwrap();
}

BrowserHandle API reference

All methods are fire-and-forget — they enqueue a command and return immediately. The browser processes the queue on the next Tick (≤ 16 ms). BrowserHandle is Clone + Send; clone it freely across threads and tasks.

TabTarget

ThemeMode

License

MIT — see LICENSE.