feat: invite-code mode core API (WDP-73 / APP-9428)

Adds a code-based discovery channel to the existing Bridge proof flow.
The RP shows the user a 6-character code; the user types it into World
App on their phone and completes the existing Selfie Check / proof
flow. Same proof flow, same poll loop, same Status enum — only the
discovery channel changes.

Wire shape (matches wallet-bridge APP-9425 and world-app-ios APP-9424):

- Code is canonical 6-char Crockford Base32 (5 random data chars + 1
  mod-32 weighted check digit, weights 1/3/5/7/9 — all coprime to 32,
  so 100% of single-char substitutions are caught). UI may format as
  "ABC-DEF" but the canonical form has no separator.
- HKDF-SHA256, no salt, 32-byte output, IKM = canonical code's UTF-8
  bytes. info="dx" → lookup index (lowercase hex on the wire);
  info="key" → AES-256-GCM key. The encryption key never reaches the
  bridge — only the index and ciphertext do.
- POST /request body has the new `request_code_enabled: true, iv,
  payload, index` shape with `iv`/`payload` as standard base64 (same
  as the URL/QR path).
- Response carries `session_nonce` and `code_expires_at`. Polling
  attaches `Authorization: Bearer <session_nonce>` so we're forward-
  compatible with the bridge's session_nonce gate (release-blocking
  follow-up on Bridge). URL-mode connections keep `session_nonce: None`
  and the header is omitted, so existing bridge behavior is unchanged.

Cross-device implications:

- Original WDP-73 mermaid minted a `delivery_token` ferried back via
  universal link. Universal links route to the device that opened them,
  so a desktop browser ↔ phone flow never receives the token. We drop
  delivery_token from idkit's surface entirely. Anti-collusion in the
  code path now degrades to "10-min TTL + one-shot redeem + per-IP
  rate limit."

API surface (mirrors existing URL-mode):

- Rust: `BridgeConnection::create_for_invite_code` (retry-once-on-409),
  `.invite_code()` / `.code_expires_at()` accessors. New crypto.rs
  primitives: `generate_invite_code`, `parse_invite_code`,
  `hkdf_invite_index_hex`, `hkdf_invite_key`, `generate_nonce`.
- FFI: `IDKitInviteCodeRequest` sibling to `IDKitRequestWrapper`. New
  builder methods `constraints_with_invite_code` /
  `preset_with_invite_code` on `IDKitBuilder`.
- WASM: `IDKitInviteCodeRequest` sibling to `IDKitRequest`,
  `constraintsWithInviteCode` / `presetWithInviteCode` on the WASM
  builder.
- TypeScript: `IDKitInviteCodeRequest` interface + impl,
  `IDKitInviteCodeBuilder`, `IDKit.requestWithInviteCode(...)` entry
  point. Code mode is bridge-only by definition (user is on a different
  device than World App), so the builder skips the `isInWorldApp()`
  branch.
- React: `IDKitInviteCodeRequestWidget`, `useIDKitInviteCodeRequest`,
  `useIDKitInviteCodeFlow` hooks. New `InviteCodeState` UI component.
- Swift: `presetWithInviteCode(_:)` / `constraintsWithInviteCode(_:)`
  on the builder; `IDKitInviteCodeRequest` wrapper exposing `code` and
  `expiresAt: Date`.

Adopter diff is two lines per integration:

  // before
  const req = await IDKit.request(config).constraints(...);
  showQR(req.connectorURI);
  // after
  const req = await IDKit.requestWithInviteCode(config).constraints(...);
  showCode(req.code);

Tests:
- 9 new Rust unit tests covering code generation, parser (round-trip,
  separator stripping, lowercase normalization, Crockford ambiguity
  collapse, U-rejection, length validation, check-digit validation,
  exhaustive single-char substitution detection), HKDF determinism,
  hex output shape, index/key differentiation across info strings.
- 86 existing rust tests pass; 54 core JS tests pass; 23 React tests
  pass. Clippy clean on native + ffi feature combos.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: SeanROlszewski

Cargo.lock

@@ -28,6 +28,8 @@ strum = { version = "0.27", features = ["derive"] }
 # Cryptography
 aes-gcm = "0.10"
 getrandom = { version = "0.2", features = ["js"] }
+hkdf = "0.12"
+sha2 = "0.10"
 tiny-keccak = { version = "2.0", features = ["keccak"] }
 
 # Encoding

Cargo.toml

@@ -20,6 +20,7 @@ export {
   selfieCheckLegacy,
   // Types
   type IDKitRequest,
+  type IDKitInviteCodeRequest,
   type IDKitCompletionResult,
   type WaitOptions,
   type RpContext,

js/packages/core/src/index.ts

@@ -72,6 +72,46 @@ export interface IDKitRequest {
   pollUntilCompletion(options?: WaitOptions): Promise<IDKitCompletionResult>;
 }
 
+/**
+ * Shared poll loop. Used by both URL-mode and invite-code-mode request impls;
+ * the loop body is identical between the two paths because the bridge
+ * `Status` shape is mode-agnostic.
+ */
+async function pollUntilCompletionLoop(
+  pollOnce: () => Promise<Status>,
+  options?: WaitOptions,
+): Promise<IDKitCompletionResult> {
+  const pollInterval = options?.pollInterval ?? 1000;
+  const timeout = options?.timeout ?? 900_000; // 15 minutes default
+  const startTime = Date.now();
+
+  while (true) {
+    if (options?.signal?.aborted) {
+      return { success: false, error: IDKitErrorCodes.Cancelled };
+    }
+
+    if (Date.now() - startTime > timeout) {
+      return { success: false, error: IDKitErrorCodes.Timeout };
+    }
+
+    const status = await pollOnce();
+
+    if (status.type === "confirmed" && status.result) {
+      return { success: true, result: status.result };
+    }
+
+    if (status.type === "failed") {
+      return {
+        success: false,
+        error:
+          (status.error as IDKitErrorCodes) ?? IDKitErrorCodes.GenericError,
+      };
+    }
+
+    await new Promise((resolve) => setTimeout(resolve, pollInterval));
+  }
+}
+
 /**
  * Internal request implementation (bridge/WASM path)
  */
@@ -98,38 +138,70 @@ class IDKitRequestImpl implements IDKitRequest {
     return (await this.wasmRequest.pollForStatus()) as Status;
   }
 
-  async pollUntilCompletion(
-    options?: WaitOptions,
-  ): Promise<IDKitCompletionResult> {
-    const pollInterval = options?.pollInterval ?? 1000;
-    const timeout = options?.timeout ?? 900_000; // 15 minutes default
-    const startTime = Date.now();
+  pollUntilCompletion(options?: WaitOptions): Promise<IDKitCompletionResult> {
+    return pollUntilCompletionLoop(() => this.pollOnce(), options);
+  }
+}
 
-    while (true) {
-      if (options?.signal?.aborted) {
-        return { success: false, error: IDKitErrorCodes.Cancelled };
-      }
+/**
+ * An invite-code mode World ID verification request (WDP-73).
+ *
+ * Sibling shape to {@link IDKitRequest}, but discovery happens through a
+ * 6-character code the user types into World App instead of a QR scan. The
+ * polling lifecycle is byte-identical to URL mode — same `Status`, same
+ * `IDKitCompletionResult` — so adopters write the same poll loop.
+ *
+ * Only the constructor and the displayable `code` differ between modes.
+ */
+export interface IDKitInviteCodeRequest {
+  /** Canonical 6-char Crockford Base32 code (no separator). UI may format as "ABC-DEF" for display. */
+  readonly code: string;
+  /** Unix-seconds expiry of the unredeemed code. After this point bridge will reject the redeem. */
+  readonly expiresAt: number;
+  /** Unique request ID for this verification */
+  readonly requestId: string;
+  /** Poll once for current status (for manual polling) */
+  pollOnce(): Promise<Status>;
+  /** Poll continuously until completion or timeout */
+  pollUntilCompletion(options?: WaitOptions): Promise<IDKitCompletionResult>;
+}
 
-      if (Date.now() - startTime > timeout) {
-        return { success: false, error: IDKitErrorCodes.Timeout };
-      }
+/**
+ * Internal invite-code request implementation (bridge/WASM only — code mode
+ * has no in-app native postMessage path by design; the user is on a different
+ * device than World App).
+ */
+class IDKitInviteCodeRequestImpl implements IDKitInviteCodeRequest {
+  private wasmRequest: WasmModule.IDKitInviteCodeRequest;
+  private _code: string;
+  private _expiresAt: number;
+  private _requestId: string;
+
+  constructor(wasmRequest: WasmModule.IDKitInviteCodeRequest) {
+    this.wasmRequest = wasmRequest;
+    this._code = wasmRequest.code();
+    this._expiresAt = wasmRequest.expiresAt();
+    this._requestId = wasmRequest.requestId();
+  }
 
-      const status = await this.pollOnce();
+  get code(): string {
+    return this._code;
+  }
 
-      if (status.type === "confirmed" && status.result) {
-        return { success: true, result: status.result };
-      }
+  get expiresAt(): number {
+    return this._expiresAt;
+  }
 
-      if (status.type === "failed") {
-        return {
-          success: false,
-          error:
-            (status.error as IDKitErrorCodes) ?? IDKitErrorCodes.GenericError,
-        };
-      }
+  get requestId(): string {
+    return this._requestId;
+  }
 
-      await new Promise((resolve) => setTimeout(resolve, pollInterval));
-    }
+  async pollOnce(): Promise<Status> {
+    return (await this.wasmRequest.pollForStatus()) as Status;
+  }
+
+  pollUntilCompletion(options?: WaitOptions): Promise<IDKitCompletionResult> {
+    return pollUntilCompletionLoop(() => this.pollOnce(), options);
   }
 }
 
@@ -547,6 +619,82 @@ class IDKitBuilder {
   }
 }
 
+/**
+ * Builder for invite-code mode requests (WDP-73).
+ *
+ * Code mode is bridge-only by definition: the user is on a different device
+ * than World App (e.g. desktop browser ↔ phone), so there's no in-app native
+ * postMessage path to branch on. This builder skips the `isInWorldApp()`
+ * check that {@link IDKitBuilder} performs.
+ */
+class IDKitInviteCodeBuilder {
+  private config: BuilderConfig;
+
+  constructor(config: BuilderConfig) {
+    this.config = config;
+  }
+
+  /**
+   * Creates an invite-code mode IDKit request with the given constraints.
+   *
+   * @param constraints - Constraint tree (CredentialRequest or any/all/enumerate combinators)
+   * @returns A new IDKitInviteCodeRequest instance
+   *
+   * @example
+   * ```typescript
+   * const request = await IDKit.requestWithInviteCode({ app_id, action, rp_context, allow_legacy_proofs: false })
+   *   .constraints(any(CredentialRequest('proof_of_human'), CredentialRequest('face')));
+   * showCode(request.code);
+   * ```
+   */
+  async constraints(
+    constraints: ConstraintNode,
+  ): Promise<IDKitInviteCodeRequest> {
+    await initIDKit();
+
+    const wasmBuilder = createWasmBuilderFromConfig(this.config);
+    const wasmRequest = (await (
+      wasmBuilder as unknown as {
+        constraintsWithInviteCode: (
+          c: ConstraintNode,
+        ) => Promise<unknown>;
+      }
+    ).constraintsWithInviteCode(
+      constraints,
+    )) as unknown as WasmModule.IDKitInviteCodeRequest;
+    return new IDKitInviteCodeRequestImpl(wasmRequest);
+  }
+
+  /**
+   * Creates an invite-code mode IDKit request from a preset.
+   *
+   * @param preset - A preset object from orbLegacy(), secureDocumentLegacy(), documentLegacy(), selfieCheckLegacy(), or deviceLegacy()
+   * @returns A new IDKitInviteCodeRequest instance
+   */
+  async preset(preset: Preset): Promise<IDKitInviteCodeRequest> {
+    if (
+      this.config.type === "createSession" ||
+      this.config.type === "proveSession"
+    ) {
+      throw new Error(
+        "Presets are not supported for session flows. Use .constraints() instead.",
+      );
+    }
+
+    await initIDKit();
+
+    const wasmBuilder = createWasmBuilderFromConfig(this.config);
+    const wasmRequest = (await (
+      wasmBuilder as unknown as {
+        presetWithInviteCode: (p: Preset) => Promise<unknown>;
+      }
+    ).presetWithInviteCode(
+      preset,
+    )) as unknown as WasmModule.IDKitInviteCodeRequest;
+    return new IDKitInviteCodeRequestImpl(wasmRequest);
+  }
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Entry points
 // ─────────────────────────────────────────────────────────────────────────────
@@ -623,6 +771,63 @@ function createRequest(config: IDKitRequestConfig): IDKitBuilder {
   });
 }
 
+/**
+ * Creates an invite-code mode IDKit request builder (WDP-73).
+ *
+ * Sibling entry point to {@link createRequest}. Validates the same required
+ * fields, returns a {@link IDKitInviteCodeBuilder} whose `.constraints()` /
+ * `.preset()` methods produce {@link IDKitInviteCodeRequest} handles.
+ *
+ * @example
+ * ```typescript
+ * const request = await IDKit.requestWithInviteCode({
+ *   app_id: 'app_staging_xxxxx',
+ *   action: 'my-action',
+ *   rp_context: { ... },
+ *   allow_legacy_proofs: false,
+ * }).constraints(any(CredentialRequest('proof_of_human'), CredentialRequest('face')));
+ *
+ * showCode(request.code);                     // user types this into World App
+ * const proof = await request.pollUntilCompletion();
+ * ```
+ */
+function createRequestWithInviteCode(
+  config: IDKitRequestConfig,
+): IDKitInviteCodeBuilder {
+  // Validate required fields — mirror createRequest exactly so integrators
+  // don't get different validation between the two paths.
+  if (!config.app_id) {
+    throw new Error("app_id is required");
+  }
+  if (!config.action) {
+    throw new Error("action is required");
+  }
+  if (!config.rp_context) {
+    throw new Error(
+      "rp_context is required. Generate it on your backend using signRequest().",
+    );
+  }
+  if (typeof config.allow_legacy_proofs !== "boolean") {
+    throw new Error(
+      "allow_legacy_proofs is required. Set to true to accept v3 proofs during migration, " +
+        "or false to only accept v4 proofs.",
+    );
+  }
+
+  return new IDKitInviteCodeBuilder({
+    type: "request",
+    app_id: config.app_id,
+    action: String(config.action),
+    rp_context: config.rp_context,
+    action_description: config.action_description,
+    bridge_url: config.bridge_url,
+    return_to: config.return_to,
+    allow_legacy_proofs: config.allow_legacy_proofs,
+    override_connect_base_url: config.override_connect_base_url,
+    environment: config.environment,
+  });
+}
+
 /**
  * Creates a new session builder (no action, no existing session_id)
  *
@@ -757,6 +962,8 @@ function proveSession(
 export const IDKit = {
   /** Create a new verification request */
   request: createRequest,
+  /** Create a new invite-code mode verification request (WDP-73) */
+  requestWithInviteCode: createRequestWithInviteCode,
   /** Create a new session (no action, no existing session_id) */
   createSession,
   /** Prove an existing session (no action, has session_id) */