Bridge debugging Report by soamdesai-tfh · Pull Request #282 · worldcoin/idkit

soamdesai-tfh · 2026-06-15T17:44:15Z

Adds structured debug reporting across the bridge (URL/QR + invite-code), WASM, and
World App native (mini_app) request flows. When IDKit debug mode is enabled, each
request builds a report tracking transport, status, timestamps, request/connector
metadata, the pre-encryption request payload, bridge create/poll response snapshots,
and errors including bridge-creation failures that throw before a request object
exists. Integrators read reports via getDebugReport() on request objects, or by
registering setDebugReportHandler() for live lifecycle updates.

Note

Medium Risk
Debug reports can include sensitive RP context and verification payloads when enabled; production paths are unchanged when debug is off.

Overview
Adds opt-in debug reporting when setDebug(true) or window.IDKIT_DEBUG is set. Integrators can call getDebugReport() on bridge (URL/QR and invite-code) and World App native requests to get a structured snapshot: package version, transport (bridge | mini_app), timestamps, request_id, connector_uri, optional request/response payloads, and mini-app metadata (World App version, platform) for native flows only.

The JS layer introduces createIDKitDebugReport and exports IDKitDebugReport / IDKitDebugTransport. Bridge reports pull the pre-encryption request JSON from WASM via new debugPayload() on request handles; Rust BridgeConnection now retains that payload at create time (keys, IVs, and encrypted bodies are explicitly not included). Native transport stores the raw host response for response_payload after verify completes.

Tests cover disabled debug (no report), bridge vs mini_app shape, and native lifecycle snapshots.

^{Reviewed by Cursor Bugbot for commit 41beb9c. Bugbot is set up for automated code reviews on this repo. Configure here.}

vercel · 2026-06-15T17:44:20Z

@soamdesai-tfh is attempting to deploy a commit to the Worldcoin Team on Vercel.

A member of the Team first needs to authorize it.

vercel · 2026-06-15T19:13:28Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
idkit-js-example	Ready	Preview, Comment	Jun 15, 2026 7:17pm

Takaros999 · 2026-06-15T19:13:44Z

@codex review

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 253d109d51

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-06-15T19:20:14Z

+  report: IDKitDebugReport | undefined,
+): T {
+  if (
+    !report ||


Remove raw debug payload when reports are disabled

When debug mode is off, createIDKitDebugReport() returns undefined, so this !report branch rethrows the original WASM BridgeRequestFailed error without calling deleteRawDebugPayload(). Since wasm_bindings.rs now attaches the pre-encryption request as error.debugPayload for bridge-create failures, any production bridge /request failure exposes that sensitive payload on the thrown error even though debug reporting is disabled; clean up debugPayload regardless of whether a report is created, or only attach it from WASM when debug is enabled.

Useful? React with 👍 / 👎.

Takaros999

high level, i believe we can avoid the log changed and simplify the debug report

once we nail this, you can add it to the kotlin and swift SDK as well

Takaros999 · 2026-06-15T20:09:05Z

    cached_signal_hashes: CachedSignalHashes,
+    /// Request payload built by `IDKit` before bridge encryption/wrapping.
+    /// Stored unconditionally because Rust does not know whether JS debug mode is enabled.
+    debug_payload: serde_json::Value,


This is the request payload we sent to the bridge. We need to include the bridge response (if it exists as well)

Takaros999 · 2026-06-15T20:10:42Z

    Other(Error),
 }

+fn bridge_request_failed(message: impl Into<String>, debug_payload: &serde_json::Value) -> Error {


im not very convinced adding the request payload into every single error will help here.

I would reduce it down to a single point, where if the debug flag is enabled we log the debug payload. Otherwise the RP can request it via getDebugReport

Takaros999 · 2026-06-15T20:11:10Z

    });
 }

+fn bridge_create_error_to_js(error: crate::Error) -> JsValue {


Takaros999 · 2026-06-15T20:15:56Z

+  | "world_app_android"
+  | "unknown";
+
+export type IDKitDebugReport = {


Since this v1 i would avoid strong typing here, to start with you can try:

request + response bridge payload (type: object)

version

package version is useful

timestamps

transport: keep it simple (bridge | mini_app)

if we're inside a mini app, you can also add world app version + platform https://github.com/worldcoin/minikit-js/blob/main/packages/core/src/global.d.ts if window.WorldApp is defined

Simplify the debug report and tighten its handling per review: - Capture the bridge response (create + poll) alongside the request via a new debug_response_payload on BridgeConnection, exposed through WASM as debugResponsePayload and surfaced as report.response_payload. - Stop threading the request payload into every bridge error: remove the Error::BridgeRequestFailed variant and the unconditional debugPayload attachment at the WASM boundary. The payload is now obtained at a single isDebug()-gated point (getBridgeDebugPayload), closing the off-state leak. - Flatten IDKitDebugReport to the loose v1 shape (version, package_version, timestamps, transport: bridge|mini_app, request/response payloads, mini_app from window.WorldApp); drop sha256 fingerprinting and the curated native log helpers. - Update the report on timeout/cancelled poll-loop exits for both bridge and invite-code paths. Follow-up hardening: - getDebugReport() short-circuits on !isDebug() so disabling debug stops stored-proof egress. - "failed" poll status only stamps response_received_at when a poll response actually arrived (matches the exception path). - Omit the rebuilt, non-correlatable proof_request.id from creation-error reports while keeping the real id on the live path. - Fix cloneValue JSON fallback to use "null" instead of invalid "undefined". Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

- Drop the curated `request` summary object (mode/app_id/action/environment/ return_to/flags), the IDKitDebugRequestMode type, and requestModeFromConfig; every field is already carried by request_payload. - Guard getWasmDebugPayload/getWasmDebugResponsePayload behind isDebug() so debugPayload()/debugResponsePayload() no longer run on the default-off path (previously fired once per poll for all users). - Capture the HTTP status on a failed bridge poll instead of collapsing every non-2xx into connection_failed; surfaces at response_payload.poll.http_status. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

A failed bridge POST /request previously folded the HTTP status and body into an opaque error message string, leaving the report's response side unstructured on the creation path (unlike the poll path, which now carries http_status). Add an Error::BridgeRequestFailed { status, body } variant; the WASM boundary attaches the namespaced { create: { http_status, body } } object as a single debugResponsePayload property on the JS error, and request.ts lifts it as-is into response_payload.create. This mirrors the existing create/poll namespacing (bridge.rs success path + poll fix) and keeps the bridge-specific shape defined in Rust rather than reconstructed in TS. Raw body is stored (no "no error details" placeholder) so the structured field is truthful: an empty body is reported as empty. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Restore the three console.debug calls in the native transport to their original full-payload form, per review feedback to avoid changing the existing logging. The full request/response payloads remain available through the structured debug report (getDebugReport), so no debug data is lost. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Takaros999 · 2026-06-16T16:02:48Z

 use std::str::FromStr;
 #[cfg(feature = "ffi")]
 use std::sync::Arc;
+use std::sync::Mutex;


using a sync mutex will block the thread, in async rust we usually use mutex from tokio

Takaros999 · 2026-06-16T16:07:06Z

    });
 }

+fn bridge_create_error_to_js(error: crate::Error) -> JsValue {


what is the benefit of this? the debug report should have everything

Takaros999 · 2026-06-16T16:10:19Z

+    /// Request payload built by `IDKit` before bridge encryption/wrapping.
+    /// Stored unconditionally because Rust does not know whether JS debug mode is enabled.
+    debug_payload: serde_json::Value,
+    debug_response_payload: Mutex<Option<serde_json::Value>>,


seeing this again is a bit confusing. Since we have all the types defined we could change it to:

request_payload: BridgeRequestPayload response_payload: Option<Serde::Value>

the response can remain a serde value because we dont know what is coming from the bridge

Takaros999 · 2026-06-16T16:14:08Z

  _debug = enabled;
 }
+
+export function setDebugReportHandler(


high level. I think this can be simplified even more.

i would avoid the debug handler unless there is a real need for it. the getDebugReport method should be enough

Takaros999 · 2026-06-16T16:15:32Z

+  return value;
+}
+
+function cloneValue(value: unknown): unknown {


why do we need this?

Takaros999 · 2026-06-16T16:16:01Z

+  });
+}
+
+function normalizeForJson(value: unknown): unknown {


do we have bigints in the payload? where exactly are they coming from?

Takaros999 · 2026-06-16T16:16:42Z

+  return report;
+}
+
+function compact<T extends Record<string, unknown>>(value: T): T {


why do we need this?

Takaros999 · 2026-06-16T16:19:13Z

+  return report;
+}
+
+export function updateDebugReport(


If you wanted to make the debug report stateful and keep changing the status you should use a class and have method .create, .update

i wouldn't track status to begin with, lets make it something that you initialize once

cursor

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 41beb9c. Configure here.}

cursor · 2026-06-16T22:07:18Z

+    requestPayload: readBridgeDebugPayload(wasmRequest),
+    requestId,
+    connectorURI,
+  });


Bridge debug payload not cached

Medium Severity

Bridge getDebugReport() loads request_payload via live debugPayload() while request_id and connector_uri are fixed at construction. During an in-flight pollOnce(), WASM temporarily clears the connection, debugPayload() fails, and the report can omit request_payload even in debug mode.

Additional Locations (1)

js/packages/core/src/request.ts#L125-L137

^{Reviewed by Cursor Bugbot for commit 41beb9c. Configure here.}

soamdesai-tfh added 3 commits June 15, 2026 00:49

Add safe bridge debug reports

5e5d83e

Make debug reports include raw debug data

4927213

Remove debug report test additions

86cea46

soamdesai-tfh requested review from Gr1dlock, Guardiola31337, SeanROlszewski, Takaros999, andy-t-wang, chipp, murph and paolodamico as code owners June 15, 2026 17:44

Merge branch 'main' into bridge_debugging

bbb5a50

cursor Bot reviewed Jun 15, 2026

View reviewed changes

Comment thread js/packages/core/src/request.ts

soamdesai-tfh added 3 commits June 15, 2026 10:53

Fix bridge debug doc markdown

6a0a18e

Tidy debug report payload handling

b7177d3

Update debug reports on bridge poll exits

253d109

chatgpt-codex-connector Bot reviewed Jun 15, 2026

View reviewed changes

Takaros999 reviewed Jun 15, 2026

View reviewed changes

cursor Bot reviewed Jun 16, 2026

View reviewed changes

Comment thread js/packages/core/src/request.ts Outdated

Comment thread js/packages/core/src/request.ts Outdated

soamdesai-tfh and others added 2 commits June 15, 2026 18:38

cursor Bot reviewed Jun 16, 2026

View reviewed changes

Comment thread rust/core/src/bridge.rs Outdated

Fix invite-code bridge debug response payload

553736e

soamdesai-tfh force-pushed the bridge_debugging branch from fb33bcb to 553736e Compare June 16, 2026 02:49

kchaw2005 mentioned this pull request Jun 16, 2026

Expose swift debug payload #283

Open

vercel Bot deployed to Preview June 16, 2026 08:46 View deployment

Takaros999 reviewed Jun 16, 2026

View reviewed changes

Simplify debug report snapshots

41beb9c

cursor Bot reviewed Jun 16, 2026

View reviewed changes

soamdesai-tfh mentioned this pull request Jun 16, 2026

Simplify debug report snapshots #285

Draft

vercel Bot deployed to Preview June 16, 2026 22:11 View deployment

Conversation

soamdesai-tfh commented Jun 15, 2026 • edited by cursor Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vercel Bot commented Jun 15, 2026

Uh oh!

Uh oh!

vercel Bot commented Jun 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Takaros999 commented Jun 15, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot Jun 15, 2026

Choose a reason for hiding this comment

Uh oh!

Takaros999 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

cursor Bot Jun 16, 2026

Choose a reason for hiding this comment

Bridge debug payload not cached

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

soamdesai-tfh commented Jun 15, 2026 •

edited by cursor Bot

Loading

vercel Bot commented Jun 15, 2026 •

edited

Loading