Web IDL support 3/N: response JSON serialization by AlfioEmanueleFresta · Pull Request #155 · linux-credentials/libwebauthn

AlfioEmanueleFresta · 2025-12-19T00:07:09Z

⚠️ AI-Assisted PR: This pull request was developed with the assistance of an AI coding agent (Claude Opus 4.5).

Summary

This PR is the second in a series (follows #138) and adds JSON serialization for WebAuthn responses - the inverse of the existing JSON request parsing functionality.

Changes

New Response Serialization Infrastructure

Add WebAuthnIDLResponse trait - Provides to_json() and to_inner_model() methods for converting responses to JSON format
Add JsonFormat enum - Supports both minified and prettified JSON output
Add ResponseSerializationError - Error type for serialization failures

New JSON Response Models (per WebAuthn Level 3 spec)

RegistrationResponseJSON - For MakeCredentialResponse serialization
AuthenticationResponseJSON - For Assertion serialization
AuthenticatorAttestationResponseJSON - Attestation response details
AuthenticatorAssertionResponseJSON - Assertion response details
AuthenticationExtensionsClientOutputsJSON - Extension output serialization

Request Structure Refactoring

Refactored MakeCredentialRequest and GetAssertionRequest to enable client data generation on-the-fly:

Replaced hash: Vec<u8> with challenge: Vec<u8> - Store raw challenge instead of pre-computed hash
Added origin: String field - Store origin explicitly
Added cross_origin: Option<bool> field - Optional cross-origin flag
Removed client_data: ClientData field - No longer needed as separate field
Added helper methods:
- client_data() - Builds ClientData internally
- client_data_hash() - Computes SHA-256 hash on demand
- client_data_json() - Returns JSON bytes for response serialization

Implementation Details

Implemented WebAuthnIDLResponse for MakeCredentialResponse with full attestation object CBOR serialization
Implemented WebAuthnIDLResponse for Assertion with signature and authenticator data handling
Support for extension outputs: credProps, hmacCreateSecret, hmacGetSecret, largeBlob, prf
Added Serialize derives to attestation statement types for CBOR encoding

Updated Files

All example files updated to use new request structure
All test files updated
CTAP2 model conversions updated to use client_data_hash()
U2F fallback code updated
WebAuthn preflight logic updated

Testing

All 85 existing tests pass
New unit tests added for response serialization
Updated webauthn_json_hid.rs example to demonstrate JSON response output

Example Usage

use libwebauthn::ops::webauthn::{WebAuthnIDLResponse, JsonFormat};

// After a MakeCredential operation
let response = channel.webauthn_make_credential(&request).await?;
let json = response.to_json(&request, JsonFormat::Prettified)?;
println!("{}", json);

// After a GetAssertion operation  
for assertion in &response.assertions {
    let json = assertion.to_json(&request, JsonFormat::Minified)?;
    println!("{}", json);
}

AlfioEmanueleFresta · 2025-12-19T00:25:36Z

@msirringhaus — Following up on your review comment on PR #138 regarding clientExtensionResults handling:

I investigated the WebAuthn Level 3 specification and found that clientExtensionResults is marked as required in both response types:

RegistrationResponseJSON: required AuthenticationExtensionsClientOutputsJSON clientExtensionResults;
AuthenticationResponseJSON: required AuthenticationExtensionsClientOutputsJSON clientExtensionResults;

This matches the behavior observed on demo.yubico.com, which always returns "clientExtensionResults": {} even when no extensions produce output.

So the current implementation in this PR is correct — we always include clientExtensionResults (as an empty object {} if no extensions produced output). The two cases you mentioned:

Extensions absent in request → Response includes "clientExtensionResults": {}
Extensions present but empty (extensions: {}) → Response includes "clientExtensionResults": {}

Both cases result in the same output per the spec, since clientExtensionResults is always required.

This comment was written by GitHub Copilot (Claude) operating on @AlfioEmanueleFresta's instructions.

This adds the inverse of JSON request parsing - serializing WebAuthn responses back to JSON format per WebAuthn Level 3 specification. Changes: - Add WebAuthnIDLResponse trait for response-to-JSON conversion - Add RegistrationResponseJSON and AuthenticationResponseJSON models - Implement to_json() for MakeCredentialResponse and Assertion - Refactor requests to store challenge/origin/cross_origin separately - Add client_data_hash() and client_data_json() helper methods - Update all examples and tests to use new request structure - Add unit tests for response serialization

msirringhaus

Looking good to me. Some minor comments and questions inline.

msirringhaus · 2026-01-08T12:26:19Z

libwebauthn/src/ops/webauthn/client_data.rs

 impl ClientData {
-    pub fn hash(&self) -> Vec<u8> {
+    /// Returns the canonical JSON representation of the client data.
+    pub fn to_json_bytes(&self) -> Vec<u8> {


I wonder if it would be more versatile to make this to_json() and return a String. Those who need the bytes can then call into_bytes() on the result.

msirringhaus · 2026-01-08T12:27:03Z

libwebauthn/examples/webauthn_prf_hid.rs

-        hash: Vec::from(challenge),
+        challenge: Vec::from(challenge),
+        origin: "example.org".to_string(),
+        cross_origin: None,


Do we have any tests where cross_origin is not None?

msirringhaus · 2026-01-08T12:28:25Z

libwebauthn/src/ops/webauthn/get_assertion.rs

+        self.client_data().hash()
+    }
+
+    pub fn client_data_json(&self) -> Vec<u8> {


Same question as above. More so here: The naming client_data_json() would lead me to expect a String.

I agree; we should also add the comment that it produces canonical JSON so that users don't have to guess whether they can use the bytes directly or not.

libwebauthn/src/ops/webauthn/get_assertion.rs

msirringhaus · 2026-01-08T12:36:09Z

libwebauthn/src/ops/webauthn/get_assertion.rs

+        let parsed: serde_json::Value = serde_json::from_str(&json_str).unwrap();
+
+        // Verify required fields
+        assert!(parsed.get("id").is_some());


Do we want to also check the contents of the fields, not just if they are Some()?

msirringhaus · 2026-01-08T12:46:07Z

libwebauthn/src/ops/webauthn/idl/response.rs

+
+/// JSON output format options.
+#[derive(Debug, Clone, Copy, Default)]
+pub enum JsonFormat {


Is it intentional to 'reimplement' this, instead of exposing a serde_json-Value, which the user can then use and format according to whatever serde_json offers?
I don't have a strong preference for either way, just wanting to understand the reasoning better, if there is any.

msirringhaus · 2026-01-08T12:57:32Z

libwebauthn/src/ops/webauthn/make_credential.rs

+        request: &Self::Context,
+    ) -> Result<Self::InnerModel, ResponseSerializationError> {
+        // Get credential ID from attested credential data
+        let credential_id_bytes = self


Same comment as for the GetAssertion-case regarding crential IDs.

msirringhaus · 2026-01-08T12:59:49Z

libwebauthn/src/ops/webauthn/make_credential.rs

+            },
+            authenticator_attachment: None,
+            client_extension_results,
+            r#type: "public-key".to_string(),


I'm ok with this for now, as we do it in lots of places, but somehow my engineering mind would feel more at ease, if we could make this a transparent enum instead of a hardcoded string in a bunch of places, to avoid typos. But this doesn't have to be in this PR.

msirringhaus · 2026-01-08T13:25:37Z

libwebauthn/src/ops/webauthn/make_credential.rs

+        let parsed: serde_json::Value = serde_json::from_str(&json_str).unwrap();
+
+        // Verify required fields
+        assert!(parsed.get("id").is_some());


Same as with GetAssertion: Can we check the contents as well for those that are easy/obvious?

iinuwa

Overall, this looks good. I agree with @msirringhaus's comments. Once those are cleaned up, we should merge this and start using it

- Rename 'uv_requirement' to 'user_verification' to match WebAuthn IDL - Add Default derive for UserVerificationRequirement (required by serde) - Update references in get_assertion.rs

iinuwa · 2026-01-27T22:12:28Z

I believe that I have properly rebased the code here and pushed it to the json-2a branch.

Sorry for the trouble :/

AlfioEmanueleFresta changed the title ~~feat(idl): Add WebAuthn response JSON serialization~~ Web IDL support 2/N: response JSON serialization Dec 19, 2025

AlfioEmanueleFresta changed the base branch from master to json December 19, 2025 00:08

AlfioEmanueleFresta force-pushed the json-2 branch from 41fbcff to 68c78a6 Compare December 19, 2025 00:15

AlfioEmanueleFresta force-pushed the json-2 branch from 68c78a6 to d3c31bb Compare December 19, 2025 00:28

AlfioEmanueleFresta marked this pull request as ready for review December 25, 2025 15:51

AlfioEmanueleFresta added 14 commits December 26, 2025 20:14

[WIP] Web IDL support (make credentials); next: extension parsing

1014412

[WIP] More progress

b86385d

Make Credential parsing seems working; added example

4e3ee42

Clean up warnings

80ba702

GetAssertion IDL implementation

c094136

Change back CTAP2 credential model to ByteBuf

560cf98

Fixes and test for MC

56f3436

Minor fix to test

e12fe3f

Rebase: Fix use of HmacOrPrf::None variant

294eed6

Adds basic parsing tests

fa44ab8

Add tests for get assertion

9fc6f61

Update example to use JSON

e948e2c

Address PR comments (AI assisted)

437c6af

Rebased

39cca52

AlfioEmanueleFresta force-pushed the json branch from fbb40b2 to 39cca52 Compare December 26, 2025 20:31

AlfioEmanueleFresta added 5 commits December 26, 2025 20:41

[WIP] More progress

885b452

Make Credential parsing seems working; added example

06ee7c0

Change back CTAP2 credential model to ByteBuf

0ac3bb7

Rebased

d97c80d

AlfioEmanueleFresta force-pushed the json-2 branch from d3c31bb to d97c80d Compare December 26, 2025 20:56

AlfioEmanueleFresta mentioned this pull request Dec 26, 2025

Use libwebauthn for JSON request parsing linux-credentials/credentialsd#116

Open

AlfioEmanueleFresta requested a review from msirringhaus December 27, 2025 00:00

msirringhaus requested changes Jan 8, 2026

View reviewed changes

iinuwa approved these changes Jan 18, 2026

View reviewed changes

AlfioEmanueleFresta added 8 commits January 24, 2026 15:42

Fix: hmac_get_secret typo

7933f7c

Feedback: From rather than Into

acf8b7b

Feedback: use rename_all=camelCase

509a22f

Feedback: Other minor fixes

93f6b3b

Feedback: Other minor fixex, simplfiied parsing chain

f39c9ca

Feedback: More rename_all

3da4043

Feedback: Fix UV field naming for JSON IDL conformance

69794ff

- Rename 'uv_requirement' to 'user_verification' to match WebAuthn IDL - Add Default derive for UserVerificationRequirement (required by serde) - Update references in get_assertion.rs

Feedback: Fix build.

9c51e1a

AlfioEmanueleFresta changed the title ~~Web IDL support 2/N: response JSON serialization~~ Web IDL support 3/N: response JSON serialization Jan 24, 2026

AlfioEmanueleFresta marked this pull request as draft January 24, 2026 22:04

AlfioEmanueleFresta added 2 commits January 24, 2026 17:15

Web IDL support 2/N: drop HMAC from WebAuthn ops

e57fbc0

Merge branch 'json-prf-only' into json-2

1b405c2

AlfioEmanueleFresta changed the base branch from json to json-prf-only January 25, 2026 19:49

iinuwa force-pushed the json-prf-only branch from e57fbc0 to dab337e Compare January 26, 2026 22:16

Base automatically changed from json-prf-only to master January 26, 2026 22:22

Conversation

AlfioEmanueleFresta commented Dec 19, 2025

Summary

Changes

New Response Serialization Infrastructure

New JSON Response Models (per WebAuthn Level 3 spec)

Request Structure Refactoring

Implementation Details

Updated Files

Testing

Example Usage

Uh oh!

AlfioEmanueleFresta commented Dec 19, 2025

Uh oh!

msirringhaus 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!

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!

iinuwa left a comment

Choose a reason for hiding this comment

Uh oh!

iinuwa commented Jan 27, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants