Crate qualia2fa_ffi

Expand description

FFI layer of Qualia2FA: exposes qualia2fa-core as UniFFI bindings.

§Responsibility of this crate

This crate only moves data: it converts the primitive types passed in from Kotlin/Swift into core types, calls the core, and converts the results back. Any cryptography, parsing or validation logic in this file is a design regression — such logic must stay inside qualia2fa-core, the only layer that is free of unsafe code and can be audited on its own.

A review of this crate has a single checklist item: has any core logic been moved in here?

uniffi::setup_scaffolding!() expands the unsafe code the FFI boundary needs inside this crate (raw pointer dereferences, catch_unwind, transfer of string ownership), so this crate is not forbid(unsafe_code). The safety boundary runs between crates: the core is forbid(unsafe_code), and this crate is the only place allowed to contain unsafe code, which must stay thin. Cargo.toml sets unsafe_code to warn rather than allow, so new unsafe code is reported at build time.

§Handling of secret material

The core’s OtpSecret deliberately implements neither Clone nor a raw byte accessor, and its Debug does not even print the length. Across the FFI boundary a seed is always represented as a Base32 string:

inbound: &str -> OtpSecret::from_base32
outbound: OtpSecret::to_base32

Seed bytes therefore never cross the FFI boundary as a Vec<u8>, which would leave one copy on each side outside the control of any erasure. Base32 is the single narrow exit already chosen by the core, and this layer reuses it.

Known residual risk: on the Kotlin/Swift side a Base32 string is an ordinary String, not protected by secrecy’s erasure, and it may be copied by the garbage collector or stored in a string pool. That is an inherent limitation of managed languages, so the client side must adopt its own discipline: a seed’s Base32 exists only in the scope that needs it, is dropped immediately afterwards, and is never logged or persisted.

Structs§

FfiAuthBoundKeyStore: The platform auth-bound key store used by master.key.bio.
FfiConflict: One disagreement a human has to settle.
FfiConflictSide: One side of a conflict, as far as it can be shown.
FfiCoreError: Summary of a core error, carried across the FFI boundary.
FfiDirectMasterKeyStore: The application’s master key held directly by the platform key store.
FfiDroppedSummary: What was dropped or assumed across a whole export.
FfiEntryIcon: The picture an entry shows beside its name.
FfiFrameCollector: Collects the codes of a multi-frame payload, in any order and with repeats.
FfiFrameStep: What one read code was, and what it did to the set it belongs to.
FfiGroup: A group: its name and the ordered list of its children.
FfiImport: One export, read and waiting for a decision.
FfiImportApplied: What an applied import did.
FfiImportChoice: One answer, keyed by the position the entry had in the export.
FfiImportMatch: What the vault already holds that relates to one imported entry.
FfiImportProblem: One entry of an export that could not be read.
FfiImportedEntry: One entry an export holds, as the preview shows it.
FfiImportedGroup: A group the export defined.
FfiJoiner: The joiner of a login: a new device that does not have the master key yet.
FfiLanChannel: The LAN channel: one endpoint on this network segment, and the peers it sends to.
FfiLanLobby: The lobby: which devices are announcing themselves on this network segment.
FfiLanPeer: One device the lobby has heard announcing itself on this network segment.
FfiLogin: The initiator of a login: a device that is already logged in and holds the master key.
FfiOrderingConflict: Two arrangements of the same group, for the user to choose between.
FfiOtpAuth: A parsed otpauth:// entry.
FfiPlatformKeys: The device identity key store of the current platform, exported to the host side.
FfiPortableRestore: What opening a portable vault file produced.
FfiQrFrame: One image of a payload that needs more than one code.
FfiQrImage: A rendered QR code, as pixels the host can draw.
FfiReceivedMessage: One message taken off a channel, together with the sender the channel claims.
FfiResponder: The responder: holds the master key and proves it to the verifier.
FfiSyncOutcome: The result of one receive.
FfiSyncSession: One synchronization session against one channel.
FfiTransportCapabilities: What a channel can do.
FfiVault: An unlocked vault.
FfiVaultEntry: A 2FA entry, as represented across the FFI boundary.
FfiVerifier: The verifier: confirms that the other side actually holds the master key.
FfiWrappedMasterKeyStore: The application’s master key held wrapped by a key-encryption key inside the platform key store.
UniFfiTraitVtableFfiDeviceKeys
UniFfiTraitVtableFfiPlatformSealer
UniFfiTraitVtableFfiSecureStore
UniFfiTraitVtableFfiTransport

Enums§

FfiAlgorithm: Hash algorithm selection passed in over FFI.
FfiAuthAvailability: What the platform’s auth-bound key store can do, asked before offering the path.
FfiDecision: What the user decided about one conflict.
FfiDigits: Number of digits in a generated code.
FfiEcLevel: The error correction level of a code, named by what it survives.
FfiEntryKind: The kind of an entry, with the parameters that belong to it.
FfiError: Errors originating in the FFI boundary itself.
FfiExportFormat: An export format the host side can choose.
FfiGroupCarrying: How much of the group tree an export format carries.
FfiGroupChild: One child of a group: an entry or another group.
FfiIconMime: The image format of an FfiEntryIcon.
FfiImportDecision: What to do with one imported entry.
FfiImportFormat: An export format the host side can name.
FfiPayloadKind: What a payload asks the peer to do.
FfiPortableKind: What a .q2fa file turned out to be, judged by its magic.
FfiRecipient: The recipient of one message.
FfiRoster: How many parties take part in one sync.
FfiSharePlan: Which route one share takes.

Traits§

FfiDeviceKeys: Source of the device identity key pair: forwarded by the host side to the platform hardware key store.
FfiPlatformSealer: The platform half of master.key.bio, implemented by the host application.
FfiSecureStore: Where the master key is persisted: forwarded by the host side to the platform hardware key store.
FfiTransport: A channel that can move sync payloads.

Functions§

codes_match: Compares two code strings for equality in constant time.
conflict_kind: Names the shape of a conflict, in the form the host side branches on.
core_error_kind: Maps a core error to a stable machine-readable identifier.
core_version: The core library version, for compatibility checks and diagnostics.
detect_import_format: Guesses the format of an export from its content.
detect_portable_file: Recognizes a portable vault file without opening it.
export_format_carries_groups: Whether this format carries the groups at all.
export_format_extension: The file name extension for this format, without the dot.
export_format_group_carrying: How much of the group tree this format carries.
export_format_needs_password: Whether this format is written with a password.
export_recovery_key_from_master: Opens a vault with the master key held by an FfiVault.
generate_secret_base32: Generates a random 256-bit secret and returns its Base32 representation.
hotp_code: Computes an HOTP code.
import_recovery_key: Recovers the master key from a recovery key file with a passphrase and writes it into the platform key store.
is_lock_marker: Whether bytes are a valid lock.marker.
is_lock_password_wrap: Whether bytes are a structurally valid password wrap, without running Argon2id.
is_lock_pending: Whether bytes are a valid lock.pending.
is_secret_shorter_than_recommended: Reports whether the secret is shorter than the recommended length.
lock_marker: Builds the lock.marker contents.
lock_pending: Builds the lock.pending contents.
lock_wrap_len: Length of a password-wrapped master key (master.key.pw).
max_group_depth: The deepest a named group may be nested; the top group is depth zero.
open_portable_file: Restores an account from a portable .q2fa file.
parse_otpauth_uri: Parses an otpauth:// URI.
qr_decode: Reads the text back out of a grayscale image.
qr_decode_text: Reads any text out of a grayscale image, whichever application drew the code.
qr_encode: Encodes text into a single QR code and renders it as grayscale pixels.
qr_encode_frames: Draws a payload as a sequence of codes, for payloads that one code cannot carry.
qr_frame_capacity: What one code of a multi-frame payload holds, in bytes.
qr_unwrap_text: Takes the envelope off a single-frame code, answering with what was put in.
recommended_min_secret_len: Recommended minimum secret length in bytes for the given algorithm.
secret_byte_len: The byte length of the secret (not the Base32 string length).
serialize_otpauth_uri: Serializes an FfiOtpAuth back into an otpauth:// URI.
steam_guard_code: Computes a Steam Guard code (5 characters, custom alphabet).
store_master_key: Writes a master key into the platform key store.
totp_code: Computes a TOTP code.
uniffi_qualia2fa_ffi_fn_init_callback_vtable_ffidevicekeys
uniffi_qualia2fa_ffi_fn_init_callback_vtable_ffiplatformsealer
uniffi_qualia2fa_ffi_fn_init_callback_vtable_ffisecurestore
uniffi_qualia2fa_ffi_fn_init_callback_vtable_ffitransport
unwrap_master_key_with_password: Opens a password-wrapped master key and returns the 32-byte key.
verify_code_with_drift: Verifies a user-supplied code, allowing for clock drift.
wrap_master_key_with_password: Wraps a 32-byte master key with the unlock password.