infusion_ffi #

Public Flutter FFI plugin for Infusion without Rust sources.

• Android: bundled jniLibs in the package (no download).
• iOS: bundled XCFramework in the package (no download).
• Desktop: downloads prebuilt binaries from public GitHub Releases on first use and caches per version.

Core code remains private. This repository exposes only the public Dart/Flutter wrapper and minimal platform glue. InfusionLoader downloads from GitHub Releases, so no manual INFUSION_LIB_PATH setup is required for normal usage. Releases must be public; private releases return 404 without auth.

Platform Support #

Usage #

dependencies:
  infusion_ffi: ^1.3.16

Ensure releases host platform binaries named:

• macOS: libinfusion_ffi.dylib
• Linux x86_64: libinfusion_ffi-linux-x64.so
• Linux arm64: libinfusion_ffi-linux-arm64.so
• Windows x86_64: infusion_ffi-windows-x64.dll
• Windows arm64: infusion_ffi-windows-arm64.dll

API #

Import and call the loader before FFI symbol lookups:

import 'package:infusion_ffi/infusion_ffi.dart';

final lib = await InfusionLoader.load();

Zero-config Loading #

InfusionLoader.load() resolves the native library in this order:

1. INFUSION_LIB_PATH environment override (local builds)
2. Bundled assets if present (SHA-256 verified)
3. GitHub Release download (desktop), cached in systemTemp/infusion_ffi/<version> with SHA-256 verification

Testing / Local Development #

If you need to override the native binary (e.g. custom local build), you can point to a specific shared library with INFUSION_LIB_PATH:

export INFUSION_LIB_PATH=/path/to/libinfusion_ffi.dylib  # or .so / .dll
flutter test

Advanced Security #

Encryption (Seal/Open) #

Encrypt data into a sealed "frame" that contains the ciphertext, an authentication tag (AEAD), and metadata headers (like algorithm ID and key derivation info).

// Seal (Encrypt)
final plaintext = Uint8List.fromList(utf8.encode('Top Secret'));
final frame = await infusion.seal(
  data: plaintext,
  policyId: 0, // 0 = default policy
);

// Open (Decrypt)
final decrypted = await infusion.open(frame); // Throws if auth fails
print(utf8.decode(decrypted)); // "Top Secret"

Capabilities (Access Control) #

Infusion uses "Capability Tokens" (CapTokens) to delegate access rights.

// Issue a capability
final capToken = await infusion.issueCap(
  scopeCid: myScopeCid, // CID of the resource/scope
  rights: 0x01,         // Bitmask (e.g., READ permission)
  expTs: 1735689600,    // Expiration timestamp (Unix)
  delegatedPub32: recipientPublicKey, // 32-byte Ed25519 public key
);

// Verify a capability
// Checks signature, expiration, and if 'requesterPub32' matches the delegate
final isValid = await infusion.verifyCap(
  capToken: capToken,
  requesterPub32: recipientPublicKey,
);

Key Derivation #

Derive deterministic sub-keys from your vault's master seed using a context string. Useful for generating keys for other systems (e.g., Hive encryption keys) without storing them.

final contextInfo = Uint8List.fromList(utf8.encode('hive_box_encryption'));
final derivedKey = await infusion.deriveKey(contextInfo);