Add support for parseCreationOptionsFromJSON and parseRequestOptionsFromJSON (issue #39)

[peterferguson]

Summary

Fixes #39 - Support new static methods parseCreationOptionsFromJSON & parseRequestOptionsFromJSON

This PR implements comprehensive support for the browser's native parseCreationOptionsFromJSON and parseRequestOptionsFromJSON static methods introduced in WebAuthn Level 3, enabling seamless JSON-to-WebAuthn conversion on the web platform.

Changes

New JSON Conversion Utilities (src/utils/json.ts)

• Implements comprehensive JSON conversion functions matching Chromium's implementation
• Provides publicKeyCredentialCreationOptionsFromJSON and publicKeyCredentialRequestOptionsFromJSON for internal use
• Handles all credential fields including challenge, user, excludeCredentials, allowCredentials
• Properly converts base64url strings to ArrayBuffers and vice versa
• Supports all WebAuthn extensions (PRF, largeBlob, credProps)

Web Module Refactor (src/ReactNativePasskeysModule.web.ts)

• Before: Manual conversion of each field from JSON to ArrayBuffer (~115 lines of conversion logic)
• After: Uses browser's native PublicKeyCredential.parseCreationOptionsFromJSON and parseRequestOptionsFromJSON (~10 lines)
• Removed redundant imports and manual conversion code
• Uses authenticationExtensionsClientOutputsToJSON for cleaner extension result handling
• Extracted extension warning logic to separate module

Additional Utilities

• Added isJSONFormat utility (src/utils/is-json-format.ts) to detect JSON vs binary format
• Extracted warnUserOfMissingWebauthnExtensions to separate file for better organization

Benefits

• ✨ Cleaner code: ~100 fewer lines in the web module
• 📋 Spec compliance: Better adherence to WebAuthn Level 3 specification
• 🔧 Maintainability: Centralized JSON conversion logic
• 🎯 Reliability: Uses battle-tested Chromium implementation patterns
• 🚀 Performance: Leverages native browser methods when available

Testing

The changes maintain backward compatibility while enabling the new JSON parsing methods. All existing functionality continues to work as expected.

Files Changed

• src/utils/json.ts - New comprehensive JSON conversion utilities (354 lines)
• src/utils/is-json-format.ts - New utility to detect JSON format (34 lines)
• src/ReactNativePasskeysModule.web.ts - Refactored to use native parsing methods (-100 lines)
• src/utils/warn-user-of-missing-webauthn-extensions.ts - Extracted extension warning logic

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added cross-platform JSON parsing utilities for WebAuthn options and input detection, plus improved handling and validation of WebAuthn extension output.
  • Returned authentication responses now provide extension results as standardized JSON and use a safe JSON fallback when available.

• Refactor

  • Web flow now leverages native WebAuthn JSON parsing for creation/get flows and centralizes extension warning logic for consistency and smaller client surface.

[coderabbitai]

Walkthrough

The changes add cross-platform JSON parsing utilities for WebAuthn, expose parseCreationOptionsFromJSON and parseRequestOptionsFromJSON, introduce isJSONFormat detection, and refactor the web module to use native PublicKeyCredential.parseCreationOptionsFromJSON/parseRequestOptionsFromJSON while centralizing extension-warning logic.

Changes

Cohort / File(s)	Summary
Changeset metadata \.changeset/feat-parse-json-options-39.md``	Documents feature addition of native WebAuthn JSON parsing and related utility modules.
JSON utilities src/utils/json.ts, src/utils/is-json-format.ts	Adds comprehensive JSON↔WebAuthn option conversion utilities, base64url encode/decode, WebAuthnJSONError, publicKeyCredentialCreationOptionsFromJSON, publicKeyCredentialRequestOptionsFromJSON, authenticationExtensionsClientOutputsToJSON, and isJSONFormat detection.
Public exports src/index.ts	Re-exports parseCreationOptionsFromJSON and parseRequestOptionsFromJSON from the new JSON utilities.
Web module refactor src/ReactNativePasskeysModule.web.ts	Replaces manual publicKey construction with PublicKeyCredential.parseCreationOptionsFromJSON / parseRequestOptionsFromJSON, uses authenticationExtensionsClientOutputsToJSON for clientExtensionResults, imports external warnUserOfMissingWebauthnExtensions, and removes manual base64/PRF conversions.

Sequence Diagram(s)

sequenceDiagram
    participant Client
    participant WebModule
    participant BrowserWebAuthn
    participant JSONUtils

    rect rgb(220,240,255)
      Note over Client,WebModule: Before (manual parsing)
      Client->>WebModule: send JSON request
      WebModule->>WebModule: manually convert fields (base64, descriptors, user)
      WebModule->>BrowserWebAuthn: navigator.credentials.create({ publicKey })
      BrowserWebAuthn-->>WebModule: credential + extensions
    end

    rect rgb(220,255,220)
      Note over Client,BrowserWebAuthn: After (native parse)
      Client->>WebModule: send JSON request
      WebModule->>BrowserWebAuthn: PublicKeyCredential.parseCreationOptionsFromJSON(request)
      BrowserWebAuthn-->>WebModule: Parsed PublicKeyCredentialCreationOptions
      WebModule->>BrowserWebAuthn: navigator.credentials.create(options)
      BrowserWebAuthn-->>WebModule: credential + extensions
    end

    rect rgb(255,245,200)
      Note over WebModule,JSONUtils: Extension conversion
      WebModule->>JSONUtils: authenticationExtensionsClientOutputsToJSON(extensions)
      JSONUtils-->>WebModule: clientExtensionResults (JSON)
      WebModule-->>Client: AuthenticationResponseJSON
    end

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~50 minutes

• Pay extra attention to src/utils/json.ts (base64url handling, PRF and largeBlob extension mappings, error cases).
• Verify src/ReactNativePasskeysModule.web.ts changes keep response shapes consistent (early credential.toJSON() return, clientExtensionResults).
• Confirm public exports in src/index.ts and interoperability across native platforms.

Possibly related PRs

• feat: add support for PRF (eval) #51 — related PRF input/output handling and plumbing that this change consolidates or replaces.
• Feat: Improved error logs on android and remove logs #53 — touches the extracted warnUserOfMissingWebauthnExtensions module used by this refactor.

Suggested reviewers

• renanmav

Poem

🐰 I nibbled through JSON leaves so fine,

Parsed challenges, user blobs, and line by line.
Native parsers now hop in with grace,
No more manual base64 chase.
Hooray — smoother hops across the WebAuthn place!

Pre-merge checks and finishing touches

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately and concisely describes the main change: adding support for parseCreationOptionsFromJSON and parseRequestOptionsFromJSON methods.
Linked Issues check	✅ Passed	The PR implements all core requirements from issue #39: parseCreationOptionsFromJSON and parseRequestOptionsFromJSON support with spec-compliant field handling, extensions, and base64url encoding.
Out of Scope Changes check	✅ Passed	All changes are directly related to implementing JSON parsing support. The extraction of extension warnings and is-json-format utilities are necessary supporting components aligned with the issue objectives.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feat/parse-json-options-39

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 3198a18 and f779f8f.

📒 Files selected for processing (2)

• .changeset/feat-parse-json-options-39.md (1 hunks)
• src/index.ts (1 hunks)

🚧 Files skipped from review as they are similar to previous changes (1)

• .changeset/feat-parse-json-options-39.md

🔇 Additional comments (1)

src/index.ts (1)

54-58: No issues found—code is correctly implemented.

The re-exported functions parseCreationOptionsFromJSON and parseRequestOptionsFromJSON are properly sourced from src/utils/json.ts (lines 272 and 318), correctly aliased to match WebAuthn Level 3 specification naming, and are part of the standard PublicKeyCredential API. The cross-platform availability is accurate—these methods have implementations recommended as replacements for libraries and are supported across modern browsers and polyfills. The public API addition is sound.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 12f498a and 3198a18.

📒 Files selected for processing (4)

• .changeset/feat-parse-json-options-39.md (1 hunks)
• src/ReactNativePasskeysModule.web.ts (5 hunks)
• src/utils/is-json-format.ts (1 hunks)
• src/utils/json.ts (1 hunks)

🧰 Additional context used

🧬 Code graph analysis (2)

src/ReactNativePasskeysModule.web.ts (3)

src/utils/json.ts (1)

• authenticationExtensionsClientOutputsToJSON (218-267)

src/ReactNativePasskeys.types.ts (2)

• AuthenticationExtensionsClientOutputs (168-180)
• AuthenticationResponseJSON (96-103)

src/utils/warn-user-of-missing-webauthn-extensions.ts (1)

• warnUserOfMissingWebauthnExtensions (9-22)

src/utils/json.ts (3)

src/ReactNativePasskeys.types.ts (15)

• Base64URLString (35-35)
• PublicKeyCredentialUserEntityJSON (39-39)
• PublicKeyCredentialUserEntity (29-29)
• PublicKeyCredentialDescriptorJSON (38-38)
• PublicKeyCredentialDescriptor (24-24)
• AuthenticationExtensionsPRFValuesJSON (226-229)
• AuthenticationExtensionsClientInputs (142-146)
• AuthenticationExtensionsLargeBlobInputs (153-163)
• AuthenticationExtensionsPRFInputs (121-133)
• AuthenticationExtensionsClientOutputs (168-180)
• AuthenticationExtensionsClientOutputsJSON (182-191)
• PublicKeyCredentialCreationOptionsJSON (51-61)
• PublicKeyCredentialCreationOptions (23-23)
• PublicKeyCredentialRequestOptionsJSON (66-73)
• PublicKeyCredentialRequestOptions (26-26)

src/utils/base64.ts (1)

• base64URLStringToBuffer (9-34)

android/src/main/java/expo/modules/passkeys/PasskeyOptions.kt (1)

• challenge (69-88)