Web and mobile bindings
Browser WASM SDK, demo application, Android Kotlin JNI wrapper, Swift SPM package, and Gate
Browser and mobile targets run the same Rust protocol core as desktop targets. Browsers execute a sans-I/O WebAssembly build over WebSocket, while Android and Apple targets call crates/tendril-ffi (tendril.h) with platform keychain and network-transition integration.
Architecture across targets
| Target | Bridge Crate / Layer | Transport Path | Secure Storage & Platform Integration |
|---|---|---|---|
Browser (bindings/web) |
crates/tendril-wasm (#![forbid(unsafe_code)], wasm-bindgen = "=0.2.130", opt-in p2p-iroh feature) |
Browser WebSocket (spec/relay-v1.md) and opt-in iroh over ws_stream_wasm + n0_dns |
TendrilWebClient, dialIrohStream, computeCodeMacWorker Web Worker Argon2 offload |
Android (bindings/kotlin) |
JNI C shim (bindings/kotlin/jni/tendril_jni.c) -> libtendril_ffi.so |
Rust P2pListener / RelayDialer / DirectDialer (serveP2p via p2p-iroh) |
KeystoreStateCipher (AndroidKeyStore AES-256-GCM), TendrilForegroundService (NetworkCallback) |
Apple (bindings/swift) |
SwiftPM C target (CTendril) -> libtendril_ffi |
Rust P2pListener / RelayDialer / DirectDialer (serveP2p via p2p-iroh) |
TendrilKeychainStore (Security Keychain + CryptoKit AES-GCM) |
WebAssembly core and browser SDK
crates/tendril-wasm
crates/tendril-wasm compiles cleanly for wasm32-unknown-unknown using .cargo/config.toml (getrandom_backend="wasm_js"). Its default build (bindings/web/pkg) remains strictly sans-I/O and exports four stateful types plus nine helper functions; enabling the opt-in p2p-iroh feature (bindings/web/pkg-p2p) adds WasmIrohStream and parse_p2p_endpoint_json over iroh 1.5 (ws_stream_wasm + ring):
WasmIdentity: generates, exports, and restores client hybrid Ed25519 + ML-DSA-65 signing keys (signing_pub,signing_pub_hash,relay_pub) and X25519 static keys without touching host storage directly, mints single-use M2M enrollment tokens viamint_enrollment_token, and mints Tier 3 relay tickets viamint_relay_ticket_json.WasmRoster: serializes and atomically replaces (replace_from_json) pinned hosts, pairing state, verified CRL sequence tracking, M2M trust anchors (add_trust_anchor,revoke_trust_anchor), and v2 peer metadata (pairing_floor,peer_v2_summary,derive_v2_relay_dial_for_peer_json).WasmPairInitiatorandWasmV2PakePairInitiator: sans-I/OIntent::Pairhandshake state machines (start,feed_bytes).WasmPairInitiatordrives v1 pairing and M2M enrollment (WasmPairInitiator.new_m2m), withnew_with_rosterandnew_m2m_with_rosterenforcing persistedmin_wire_versionupgrade floors;WasmV2PakePairInitiatordrives Wire0x02PAKE pairing.WasmSessionClientandWasmV2SessionInitiator: sans-I/OIntent::Sessioninitiators (v1WasmSessionClient:send_data,send_ping,send_rekey,send_close,tick,authorize; v2WasmV2SessionInitiator:send_data,rekey,close,tick,authorize,send_dummy_cover,next_ping_delay_msfor Wire0x02pseudonymous reconnect with padded/jittered frames).- Vector and verification helpers:
device_id,fingerprint_host,fingerprint_device,pairing_sas,compute_code_mac,compute_code_mac_bytes(zeroizing the caller byte slice after hashing),verify_rotation_chain_json,verify_grant_json,parse_pairing_uri_json,compute_relay_auth_hmac_b64,derive_v2_relay_dial_json, andv2_epoch_within_skew. - Opt-in browser P2P (
p2p-irohfeature):WasmIrohStream(dial,dial_with_options,send_chunk,recv_chunk,close) andparse_p2p_endpoint_json.
@tendril-sdk/web (bindings/web)
bindings/web/src/relay.jsimplementsspec/relay-v1.md(/v1/relay) andspec/relay-v2.md(/v2/relayviadialRelayV2Stream, requiringderiveV2Dialfor epoch-blindeddial_tokenproofs) client WebSocket handshakes (challenge,dial,ready, plus Tier 2 HMACcomputeRelayAuthHmacB64and Tier 3RelayTicketadmission proofs), URL validation (validateRelayWsUrl: rejecting control characters, userinfo, fragments, metadata/link-local/unspecified hosts, and cleartextws://off-loopback unlessallowInsecureWs: trueis passed), binary frame bounds (65,521bytes max), and bounded receive queueing (MAX_QUEUED_BYTES = 16 * 65521,MAX_QUEUED_FRAMES = 256, late post-close frame drops, and queue cleanup onclose()).bindings/web/src/index.jsdynamically imports./iroh.js(bindings/web/pkg-p2p/on demand foriroh://, supportingp2pRelayUrlsandp2pRelayAuthTokenfor managediroh-relaypools while rejectingp2pApiSecretin the browser so API secrets are never embedded in client JS), serializes cipher-state advances and multi-chunk frame flushes via#sendChain(#recvChainforpollEvent) while keepingstream.recv()unblocked, rolls back roster changes ononPersistRosterfailure (and fails closed if revocation persistence fails), guardsTendrilWebClient.free()by aborting active sessions and deferring WASMfree()until in-flight holds release, zeroizesUint8Arraysecret inputs infinallyblocks, exports top-level@tendril-sdk/webhelpers (computeRelayAuthHmacB64,deriveV2RelayDial,v2EpochWithinSkew), and exposesTendrilWebClient.{pairV2, connectV2, mintRelayTicket, addTrustAnchor, revokeTrustAnchor, mintEnrollmentToken, enroll}for Wire0x02and browser M2M workflows.bindings/web/src/worker.jsandcomputeCodeMacWorker(code: string | Uint8Array,handshakeHash,{ timeoutMs }) move Argon2id pairing-code proof computation off the UI thread, transferring and zeroingUint8Arraysecret code inputs and terminating hung or unserializable workers on timeout ormessageerror;computeCodeMacBytesexposes the synchronous zeroizing path directly.bindings/web/demo/provides an interactive pairing/session web page supporting bothwss://.../v1/relayandiroh://...endpoints, serving strictContent-Security-Policy(frame-ancestors 'none','wasm-unsafe-eval'),X-Frame-Options: DENY, andReferrer-Policy: no-referrerheaders, allowlisting static/demo/assets (404on/demo/server.mjs), enforcing RFC 6455 WebSocket upgrade header/timeout validation inserver.mjs, enforcing/demo-config.jsonprecedence + URL secret scrubbing + third-party override warnings inapp.js, and sealing identity/roster JSON in IndexedDB (tendril-demo-vault-v1) under a non-extractable WebCrypto AES-256-GCM key rather than plaintextlocalStorage.bindings/web/test/security.test.mjsandbindings/web/test/browser_e2e.mjsverify URL/queue/concurrency/persistence/lifecycle hardening, zeroizing worker MAC helpers, M2M enrollment/replay/anchor-revocation flows over live WSS relay,spec/vectors/,parseP2pEndpointvalidation, and live headless ChromeNoise_XXhfsrelay flows againsttendril-relayandtendril-conformance-peer(plus liveiroh://browser-to-host E2E over n0 public relays whenTENDRIL_WEB_P2P_LIVE=1).
Android Kotlin JNI (bindings/kotlin)
bindings/kotlin/jni/tendril_jni.cbridgesdev.tendril.TendrilNativemethods (includingendpointAddTrustAnchor,endpointRevokeTrustAnchor,endpointMintEnrollmentToken, andendpointEnrollInitiate) tocrates/tendril-ffi/include/tendril.h, converts standard UTF-8 <-> UTF-16 directly (preserving non-BMP characters and formatting dynamic full-length FFI error messages), rejects embedded NUL bytes in string inputs, validates non-negative integer inputs and0..=65535close codes, mapsTENDRIL_WOULD_BLOCKandTENDRIL_EOFinto JSON status sentinels, and frees all returned C strings withtendril_string_free.TendrilEndpointandTendrilSessioninTendrilClient.ktexpose full M2M enrollment (addTrustAnchor,revokeTrustAnchor,mintEnrollmentToken,enrollInitiate) and implementjava.io.CloseablewithReentrantReadWriteLockhandle synchronization, callingtendril_endpoint_close/tendril_session_shutdownoutside exclusive native free so concurrentclose()calls unblock and serialize safely against active FFI polls or sends.KeystoreStateCipher.kt(SealedStateStore) seals and unseals identity and roster JSON via anAndroidKeyStoreAES-256-GCM key (12-byte random IV prefix, version0x01, domain AAD, verifying Keystore key presence), wired directly intoTendrilEndpoint.create/TendrilSessionviatendril_endpoint_new_from_statewhileAndroidManifest.xmldisables cloud/ADB backups (android:allowBackup="false",tendril_backup_rules.xml,tendril_data_extraction_rules.xml).TendrilForegroundService.ktmaintains adataSyncforeground notification and monitorsConnectivityManager.registerDefaultNetworkCallbackacross Wi-Fi and cellular handoffs.bindings/kotlin/test/TendrilJniConformanceTest.javavalidates all four helper vectors (fingerprints.json,pairing_mac.json,rotation.json,grants.json), NUL/close hardening, bidirectional live interop againsttendril-conformance-peer, and M2M enrollment/replay/anchor-revocation on host Linux JVM (make bindings/jnitests the C JNI bridge and Java declarations; compiling.ktAndroid sources requires Gradle and the Android SDK).
Apple Swift (bindings/swift)
bindings/swift/Package.swiftdeclaresCTendril(module.modulemap+shim.hreferencingcrates/tendril-ffi/include/tendril.h), theTendrilwrapper module (TendrilCrypto,TendrilEndpointincludingaddTrustAnchor,revokeTrustAnchor,mintEnrollmentToken, andenrollInitiate, plusTendrilSession, validating strings against embedded NUL bytes and usingNSConditionactive-call refcounting withtendril_endpoint_close/tendril_session_shutdown),TendrilKeychainStore(SealedSwiftStateStorehandlingerrSecDuplicateItem, key buffer zeroization, version0x01+ domain AADCryptoKitAES-GCM sealing wired intoTendrilEndpoint/TendrilSession), andTendrilTests(offline vectors, fork rejection, local endpoint lifecycle, and M2M enrollment/replay checks).- Verification note:
swift test(TendrilConformanceTests, 4/4 tests) andaarch64-apple-darwin(macOS arm64) release builds pass on macOS arm64; cross-compilingaarch64-apple-iosrequires fullXcode.app(iphoneosSDK) forringrather than Command Line Tools alone.
Gate #7 baselines
| Artifact | Target | Raw Size | Stripped / Compressed | Measurement Method |
|---|---|---|---|---|
bindings/web/pkg/tendril_wasm_bg.wasm |
wasm32-unknown-unknown (release, default sans-I/O, hybrid PQ) |
1,027,782 bytes (1003.7 KiB) | 363,831 bytes (355.3 KiB) gzipped | wasm-bindgen --target web + gzip -c -9 |
bindings/web/pkg-p2p/tendril_wasm_bg.wasm |
wasm32-unknown-unknown (release, --features p2p-iroh, hybrid PQ) |
4,279,199 bytes (4.08 MiB) | 1,565,110 bytes (1.49 MiB) gzipped | wasm-bindgen --target web (p2p-iroh) + gzip -c -9 |
target/aarch64-linux-android/release/libtendril_ffi.so |
aarch64-linux-android (release, API 26, --no-default-features, hybrid PQ) |
4,095,168 bytes (3.91 MiB) | 4,095,160 bytes (3.91 MiB) | stat -c%s before and after llvm-strip |
target/aarch64-linux-android/release/libtendril_ffi.so |
aarch64-linux-android (release, API 26, default p2p-iroh, hybrid PQ) |
12,761,016 bytes (12.17 MiB) | 12,761,008 bytes (12.17 MiB) | stat -c%s before and after llvm-strip |
Android Gradle release AAR (bindings/kotlin) |
aarch64-linux-android (release, hybrid PQ) |
5,800,485 bytes (5.53 MiB) | Packaged AAR | Gradle assembleRelease |
target/release/libtendril_ffi.{dylib,a} |
aarch64-apple-darwin (release, --no-default-features, hybrid PQ) |
3,984,240 B .dylib / 56,631,288 B .a |
3,984,304 B (strip -x) / 12,489,976 B (strip -S) |
macOS arm64 release build + strip |
target/release/libtendril_ffi.{dylib,a} |
aarch64-apple-darwin (release, default p2p-iroh, hybrid PQ) |
11,255,888 B .dylib / 124,318,248 B .a |
11,255,976 B (strip -x) / 29,375,784 B (strip -S) |
macOS arm64 release build + strip |
aarch64-apple-ios static archive |
aarch64-apple-ios |
Not measured | Not measured | Requires full Xcode.app (iphoneos SDK) for ring |
Gate #8 WASM Argon2id timings
Measured via benchmarkArgon2 (t=3, m=64 MiB, p=1) in headless desktop Google Chrome (bindings/web/test/browser_e2e.mjs) and on a physical mobile phone browser over TLS relay demo:
| Execution Context | Runs | Min (ms) | Median (ms) | Max (ms) | Notes |
|---|---|---|---|---|---|
| Desktop headless Chrome (main thread) | 3 | 135.2 | 148.5 | 158.7 | Single-call compute_code_mac (useWorker: false, post-ADR 0004) |
| Desktop headless Chrome (Web Worker) | 2 | 183.7 | 218.7 | 218.7 | Includes worker spawn and WASM init (useWorker: true, post-ADR 0004) |
| Mobile phone browser (main thread) | 3 | 153.8 | 155.8 | 171.7 | Physical phone run against hosted demo (useWorker: false) |
| Mobile phone browser (Web Worker) | 3 | 402.6 | 665.7 | 1030.9 | Includes worker spawn and WASM init per call (useWorker: true) |
Gate #9 pairing and reconnect baselines
Desktop headless Chrome WebSocket relay (post-ADR 0004 Noise_XXhfs)
Measured in headless desktop Google Chrome against tendril-conformance-peer over a loopback tendril-relay (Noise_XXhfs_25519+MLKEM768_ChaChaPoly_SHA256, 1216 B msg1, and 3373 B hybrid Ed25519 + ML-DSA-65 signatures):
- Remote pairing (
TendrilWebClient.pair):269.4 msend-to-end (includesNoise_XXhfspairhandshake and Argon2idcode_mac). - Authenticated session connect (
TendrilWebClient.connect):18.0 msinitialNoise_XXhfshandshake over loopback relay (14.6 msrepeat connect). - Encrypted control and data round-trip:
25.5 msencrypted0x05 PING->0x06 PONGRTT,0.2 msclient0x04 REKEYdispatch, and verified21-byte plaintext delivery on the Rust conformance peer.
These desktop headless figures are local loopback baselines and are not directly comparable to WAN physical-phone latencies.
Historical pre-ADR 0004 physical-phone baselines
The two physical-phone subsections below are historical pre-ADR 0004 baselines measured under classical Noise_XX before 1216 B Noise_XXhfs msg1 and 3373 B hybrid Ed25519 + ML-DSA-65 signatures landed in wire v1. Physical-phone re-measurement under Noise_XXhfs is pending.
WebSocket relay baseline (physical phone, pre-ADR 0004 classical Noise_XX)
Observed between a physical mobile browser and the desktop Rust tendril CLI host over the WebSocket relay demo (< 30 s pairing target):
- Remote pairing:
0.59 send-to-end with verified 16-character SAS match and hosttendril confirm. - Authenticated session connect:
332.1 msinitial pre-ADR 0004classicalNoise_XXhandshake over relay (164.5 msrepeat connect). - Encrypted control and data round-trip:
27 msencrypted0x05 PING->0x06 PONG, followed by0x04 REKEYand verified plaintext delivery (21bytes) decoded on the Rust host. - Disconnect and reconnect recovery: Re-established authenticated relay sessions in
526.5 ms,520.4 ms, and418.0 msacross manual reconnect and connectivity restoration tests.
Zero-setup iroh:// baseline (physical phone, Tailscale OFF, pre-ADR 0004 classical Noise_XX)
Observed between a physical mobile browser (Tailscale OFF, zero self-hosted Tendril relay) and tendril serve --p2p --issue-code remote over bare iroh:// routed via public n0 relay (euc1-1.relay.n0.iroh.link.):
- Warm remote pairing:
0.87 swith verified 16-character SAS match and hosttendril confirm(a cold first tap timed out while downloading the uncompressed3.93 MiBpkg-p2pbundle inside the shared15 stimeout, motivatinginitTendrilP2p()pre-warming and gzip compression indemo/server.mjs). - Authenticated session connect (
provider: P2p):634.9 msinitial pre-ADR 0004classicalNoise_XXQUIC establish. - Encrypted control and data round-trip:
63 ms,67 ms, and post-rekey69 ms0x05 PING->0x06 PONGRTTs, followed by0x04 REKEYand21-byte plaintext verified on the Rust host. - Disconnect and reconnect recovery: Clean session close (
code=1000,reason="reconnect") and re-establishment in392.9 msoverprovider: P2p.
Verification commands
make bindings/wasm # Build sans-I/O release WASM and generate bindings/web/pkg
make bindings/wasm-p2p # Build opt-in p2p-iroh WASM and generate bindings/web/pkg-p2p
make bindings/web # Run headless Chrome vector + benchmark + live relay E2E suite
TENDRIL_WEB_P2P_LIVE=1 node bindings/web/test/browser_e2e.mjs # Also run live bare iroh:// Chrome E2E
make bindings/jni # Compile libtendril_jni.so and run JVM vector + interop tests
make bindings/android # Cross-compile release libtendril_ffi.so for aarch64-linux-android
make bindings/check # Run Go, Python, Node, Web WASM, and Kotlin JNI suites
Connections
Local graphLinked from
- Node.js (bindings/node)“Web and mobile bindings”
- Gate #7 baselines (Linux x86_64 release)“Web and mobile bindings”
- Harden bindings, FFI concurrency, mobile storage, and web SDK (Audit Batch 2B)Logs“Web and mobile bindings”