Release 1.10.0

[github-actions]

Release 1.10.0

This PR was created by the Create Release Branch workflow.

Checklist

• Release notes reviewed and finalized
• All SDK versions bumped
• RC published and validated
• Final release published via Release workflow

Note: This PR will be merged automatically by the Release workflow upon final release.

Note

Release v1.10.0 with Backend builder API and unified environment configuration

• Adds BackendBuilder and Backend types to Node and WASM bindings, replacing discrete host/gateway parameters across createClient, getInboxIdByIdentity, revokeInstallationsSignatureRequest, applySignatureRequest, and fetchInboxStatesByInboxIds
• Introduces a new xmtp_macro::napi_builder, wasm_builder, and uniffi_builder proc-macro attribute that generates binding-specific constructors and chainable setters from annotated structs
• Adds XmtpEnv enum to node/wasm bindings and xmtp_configuration crate with centralized/decentralized variants and a validate_and_resolve config helper
• ClientBundleBuilder now supports D14n mode with gateway-only configuration; V3 and D14n are selected automatically based on which hosts are provided
• On WASM, GrpcUrlsProduction::NODE now resolves to https://api.production.xmtp.network:5558 instead of the gRPC endpoint
• Improves device sync test coverage on Android, iOS, and mobile bindings for archive upload, processing, and message visibility
• Behavioral Change: all Node and WASM public functions that previously accepted v3_host/gatewayHost/isSecure now require a Backend instance; the encryptionKey parameter is ignored in WASM client creation with a warning logged when provided

^{Macroscope summarized 5c42da5.}

[macroscopeapp]

Re-evaluating approvability for da3a7ef

Dismissing my prior approval and re-evaluating approvability for da3a7ef

[claude]

Claude finished @github-actions[bot]'s task —— View job

---

PR Review Complete

Review Date: March 3, 2026, 21:24 UTC

This release PR (1.10.0) contains significant architectural changes beyond version bumps, contrary to the macroscopeapp review. I've identified several important concerns:

---

🔴 Critical Issues

1. Security: Mutex Poison Handling in Node Bindings (bindings/node/src/client/backend.rs:36-42)

The code uses .expect("lock poisoned") when mutex poisoning occurs, which will panic and crash the Node.js process. Since AuthCallback and AuthHandle contain sensitive authentication data, a panic could leak sensitive information in panic messages or logs.

*self.auth_callback.lock().expect("lock poisoned") = Some(callback.clone());

Recommendation: Return a proper error instead of panicking:

.map_err(|_| napi::Error::from_reason("Failed to acquire lock"))?

2. Security: TLS Validation Logic (crates/xmtp_api_d14n/src/config/backend_config.rs:22-25)

The is_url_secure() function only checks URL prefixes (https://, grpcs://) without validating the actual TLS configuration. This is insufficient for security-critical decisions.

Recommendation: Rename to has_secure_scheme() or add documentation clarifying this only checks the URL scheme, not actual TLS security.

3. Confusing Error Recovery Pattern (crates/xmtp_api_d14n/src/queries/client_bundle.rs:184-248)

The build() method silently ignores v3_host when gateway_host is set (line 186). This could confuse developers who set both parameters expecting hybrid mode.

Recommendation: Add a warning log or return an error when both are set to make the behavior explicit.

---

⚠️ High Priority Issues

4. Race Condition: consumed Flag Check (bindings/node/src/client/backend.rs:46-57)

The consumed flag check has a TOCTOU (time-of-check-time-of-use) race condition. Two threads could pass the check before either sets the flag.

let mut consumed = self.consumed.lock().map_err(...)?;
if *consumed { return Err(...); }
*consumed = true;

While unlikely in typical Node.js usage, this could cause issues in concurrent scenarios.

Recommendation: Use atomic operations or keep the lock held throughout the entire build process.

5. Missing Validation: Empty String Checks (crates/xmtp_api_d14n/src/config/backend_config.rs:35-46)

The validation accepts empty strings for api_url and gateway_host. This could lead to runtime errors when attempting connections.

Recommendation: Validate that strings are non-empty when provided.

---

📋 Medium Priority Issues

6. Test Coverage Gap

While the new builder macros have good test coverage (bindings/node/test/Builder.test.ts:20-24), the critical security path (auth + gateway validation) lacks dedicated tests.

Recommendation: Add tests for:

• Auth callback/handle with missing gateway_host (should error)
• Empty string validation
• Concurrent build() calls

7. Inconsistent Error Messages

crates/xmtp_api_d14n/src/config/backend_config.rs:16-18 defines specific error types, but the Node.js binding translates these to generic strings, losing error context.

---

✅ Positive Observations

• Well-structured builder macro architecture with clear separation of concerns
• Comprehensive tests for builder patterns across all three bindings (Node/WASM/Mobile)
• Good documentation in macro code
• Type-safe API design with proper Option handling

---

📊 Summary

While this PR introduces a solid builder pattern architecture, the security-critical sections (authentication, TLS validation, mutex handling) need attention before release. The issues are fixable, but given this is a release PR, I recommend addressing the critical issues first.

Recommendation: Address critical issues #1-3 before merging to main.

---

[codecov]

Codecov Report

❌ Patch coverage is 73.14991% with 283 lines in your changes missing coverage. Please review.
✅ Project coverage is 73.38%. Comparing base (319b2e4) to head (da3a7ef).
⚠️ Report is 10 commits behind head on main.

Files with missing lines	Patch %	Lines
bindings/node/src/client/create_client.rs	0.00%	106 Missing ⚠️
bindings/node/src/client/backend.rs	0.00%	84 Missing ⚠️
crates/xmtp_macro/src/lib.rs	63.63%	24 Missing ⚠️
crates/xmtp_api_d14n/src/queries/client_bundle.rs	80.76%	15 Missing ⚠️
bindings/node/src/inbox_id.rs	0.00%	12 Missing ⚠️
bindings/node/src/client/options.rs	0.00%	11 Missing ⚠️
crates/xmtp_macro/src/builder.rs	94.11%	11 Missing ⚠️
bindings/node/src/signatures.rs	0.00%	8 Missing ⚠️
bindings/node/src/inbox_state.rs	0.00%	4 Missing ⚠️
crates/xmtp_api_d14n/src/queries/builder.rs	0.00%	4 Missing ⚠️
... and 2 more

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3261      +/-   ##
==========================================
- Coverage   73.52%   73.38%   -0.15%     
==========================================
  Files         452      452              
  Lines       56677    56832     +155     
==========================================
+ Hits        41673    41705      +32     
- Misses      15004    15127     +123     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[macroscopeapp]

🟢 Low library/HistorySyncTest.kt:307

In testDisablingHistoryTransferDoesNotTransfer, alixClient and alixClient2 are created via direct Client.create() calls instead of the createClient() helper. This skips the cleanup tracking in createdClients, so dropLocalDatabaseConnection() is never called during tearDown(), leaving database connections and files leaked. Consider using createClient() to ensure automatic cleanup.

            val localApi = ClientOptions.Api(XMTPEnvironment.LOCAL, false)
-            val alixClient =
-                Client.create(
-                    account = alixWallet,
-                    options = createClientOptions(api = localApi, deviceSyncEnabled = false),
-                )
+            val alixClient = createClient(alixWallet, api = localApi, deviceSyncEnabled = false)
             val alixGroup = alixClient.conversations.newGroup(listOf(boClient.inboxId))
             val messageIdNotExpectedOnClient2 = alixGroup.send("hi")
             delay(2000)
             val initialMessageCount = alixGroup.messages().size
             assertEquals(initialMessageCount, 2)
-            val alixClient2 =
-                Client.create(
-                    account = alixWallet,
-                    options = createClientOptions(api = localApi, deviceSyncEnabled = true),
-                )
+            val alixClient2 = createClient(alixWallet, api = localApi, deviceSyncEnabled = true)

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file sdks/android/library/src/androidTest/java/org/xmtp/android/library/HistorySyncTest.kt around lines 307-320:

In `testDisablingHistoryTransferDoesNotTransfer`, `alixClient` and `alixClient2` are created via direct `Client.create()` calls instead of the `createClient()` helper. This skips the cleanup tracking in `createdClients`, so `dropLocalDatabaseConnection()` is never called during `tearDown()`, leaving database connections and files leaked. Consider using `createClient()` to ensure automatic cleanup.

Evidence trail:
- HistorySyncTest.kt lines 306-310 and 318-322: Direct `Client.create()` calls creating `alixClient` and `alixClient2`
- BaseInstrumentedTest.kt line 25: `private val createdClients = mutableListOf<Client>()` - tracking list
- BaseInstrumentedTest.kt lines 67-74: `createClient()` helper that adds to tracking list via `createdClients.add(client)` at line 73
- BaseInstrumentedTest.kt lines 40-60: `tearDown()` method that calls `dropLocalDatabaseConnection()` only on clients in `createdClients` (line 45)

[macroscopeapp]

Approvability

Verdict: Needs human review

This release PR (1.10.0) includes version bumps, new BackendBuilder abstractions, new builder macros, API surface changes, and documented breaking changes to history sync behavior. The automated release bot author has no code ownership of the modified files, so designated owners should verify this release before merging.

^{You can customize Macroscope's approvability policy. Learn more.}

[cameronvoell]

release changes merged to main via #3327