Add experimental user verification API contracts (#43265)

## What changed

Add `userVerification/status`, `userVerification/enroll`, `userVerification/delete`, and `userVerification/verify` behind the `experimentalApi` capability. Define request, response, proof, and typed error contracts, export their schemas, and document the API.

All four methods currently return `unavailable` with reason `providerUnavailable`; native verification operations are not implemented by this change.

## Testing

Add tests for experimental opt-in, typed provider unavailability, readiness serialization, and rejection of mismatched error reasons and native diagnostic payloads.

GitOrigin-RevId: a858ab41523c5acec7dbf3cfa7fcab693ac44a8c
This commit is contained in:
riley-oai authored and copyberry committed 2026-09-06 18:39:32 +00:00
1 parent 7bab4526f9
commit ad931a45b2
12 files changed
+368

No files matched your search

@@ -518,6 +518,34 @@ client_request_definitions! {
response: v2::ServerDiagnosticsResponse,
},
#[experimental("userVerification/status")]
UserVerificationStatus => "userVerification/status" {
params: v2::UserVerificationStatusParams,
serialization: None,
response: v2::UserVerificationStatusResponse,
},
#[experimental("userVerification/enroll")]
UserVerificationEnroll => "userVerification/enroll" {
params: v2::UserVerificationEnrollParams,
serialization: None,
response: v2::UserVerificationEnrollResponse,
},
#[experimental("userVerification/delete")]
UserVerificationDelete => "userVerification/delete" {
params: v2::UserVerificationDeleteParams,
serialization: None,
response: v2::UserVerificationDeleteResponse,
},
#[experimental("userVerification/verify")]
UserVerificationVerify => "userVerification/verify" {
params: v2::UserVerificationVerifyParams,
serialization: None,
response: v2::UserVerificationVerifyResponse,
},
/// NEW APIs
// Thread lifecycle
// Uses `inspect_params` because only some fields are experimental.
@@ -33,6 +33,7 @@ mod thread;
mod thread_data;
mod thread_usage;
mod turn;
mod user_verification;
mod windows_sandbox;
pub use account::*;
@@ -69,6 +70,7 @@ pub use thread::*;
pub use thread_data::*;
pub use thread_usage::*;
pub use turn::*;
pub use user_verification::*;
pub use windows_sandbox::*;
#[cfg(test)]
@@ -0,0 +1,150 @@
//! Experimental user-verification APIs for trusted UI clients.
//! Native implementation and registration transport are independent of these contracts.
use crate::JsonSchema;
use crate::TS;
use serde::Deserialize;
use serde::Serialize;
/// A signature over the exact decoded challenge. The verifier validates and consumes it.
#[derive(Serialize, Deserialize, Clone, PartialEq, Eq, JsonSchema, TS)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
#[ts(export_to = "v2/")]
pub struct UserVerificationProof {
pub credential_id: String,
/// Unpadded base64url DER ECDSA signature using P-256 and SHA-256.
pub signature: String,
}
impl std::fmt::Debug for UserVerificationProof {
fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
formatter
.debug_struct("UserVerificationProof")
.finish_non_exhaustive()
}
}
#[derive(Serialize, Deserialize, Debug, Clone, Copy, PartialEq, Eq, JsonSchema, TS)]
#[serde(rename_all = "camelCase")]
#[ts(rename_all = "camelCase", export_to = "v2/")]
pub enum UserVerificationUnavailableReason {
CredentialMissing,
BiometricsUnavailable,
ProviderUnavailable,
}
#[derive(Serialize, Deserialize, Debug, Clone, Copy, PartialEq, Eq, JsonSchema, TS)]
#[serde(rename_all = "camelCase")]
#[ts(rename_all = "camelCase", export_to = "v2/")]
pub enum UserVerificationCancellationReason {
UserCancelled,
Interrupted,
}
#[derive(Serialize, Deserialize, Debug, Clone, Copy, PartialEq, Eq, JsonSchema, TS)]
#[serde(rename_all = "camelCase")]
#[ts(rename_all = "camelCase", export_to = "v2/")]
pub enum UserVerificationFailureReason {
AuthenticationFailed,
Timeout,
ProviderError,
ServiceError,
}
#[derive(Serialize, Deserialize, Debug, Clone, Copy, PartialEq, Eq, JsonSchema, TS)]
#[serde(rename_all = "camelCase")]
#[ts(rename_all = "camelCase", export_to = "v2/")]
pub enum UserVerificationInvalidRequestReason {
InvalidParams,
}
/// Closed error categories; native diagnostic payloads must not cross this boundary.
#[derive(Serialize, Deserialize, Debug, Clone, Copy, PartialEq, Eq, JsonSchema, TS)]
#[serde(tag = "type", rename_all = "camelCase", deny_unknown_fields)]
#[ts(tag = "type", rename_all = "camelCase", export_to = "v2/")]
pub enum UserVerificationErrorDetails {
InvalidRequest {
reason: UserVerificationInvalidRequestReason,
},
Unavailable {
reason: UserVerificationUnavailableReason,
},
Cancelled {
reason: UserVerificationCancellationReason,
},
Failed {
reason: UserVerificationFailureReason,
},
}
/// The error object inside the normal JSON-RPC envelope.
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, JsonSchema, TS)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
#[ts(export_to = "v2/")]
pub struct UserVerificationRpcError {
#[ts(type = "number")]
pub code: i64,
pub message: String,
pub data: UserVerificationErrorDetails,
}
#[derive(Serialize, Deserialize, Debug, Default, Clone, PartialEq, Eq, JsonSchema, TS)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
#[ts(export_to = "v2/")]
pub struct UserVerificationStatusParams {}
/// Local readiness only; this neither prompts nor queries server registration.
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, JsonSchema, TS)]
#[serde(rename_all = "camelCase")]
#[ts(export_to = "v2/")]
pub struct UserVerificationStatusResponse {
pub credential_id: Option<String>,
pub unavailable_reason: Option<UserVerificationUnavailableReason>,
pub unavailable_message: Option<String>,
}
#[derive(Serialize, Deserialize, Debug, Default, Clone, PartialEq, Eq, JsonSchema, TS)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
#[ts(export_to = "v2/")]
pub struct UserVerificationEnrollParams {}
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, JsonSchema, TS)]
#[serde(rename_all = "camelCase")]
#[ts(export_to = "v2/")]
pub struct UserVerificationEnrollResponse {
pub credential_id: String,
}
#[derive(Serialize, Deserialize, Debug, Default, Clone, PartialEq, Eq, JsonSchema, TS)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
#[ts(export_to = "v2/")]
pub struct UserVerificationDeleteParams {}
#[derive(Serialize, Deserialize, Debug, Default, Clone, PartialEq, Eq, JsonSchema, TS)]
#[serde(rename_all = "camelCase")]
#[ts(export_to = "v2/")]
pub struct UserVerificationDeleteResponse {}
/// Local signing primitive, independent of any pending elicitation.
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, JsonSchema, TS)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
#[ts(export_to = "v2/")]
pub struct UserVerificationVerifyParams {
/// Unpadded base64url encoding of 1–4096 challenge bytes.
pub challenge: String,
/// Display context already approved by the UI; 1–256 UTF-8 bytes.
pub title: String,
/// Additional display context; at most 4096 UTF-8 bytes.
pub description: String,
}
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, JsonSchema, TS)]
#[serde(rename_all = "camelCase")]
#[ts(export_to = "v2/")]
pub struct UserVerificationVerifyResponse {
pub proof: UserVerificationProof,
}
#[cfg(test)]
#[path = "user_verification_tests.rs"]
mod tests;
@@ -0,0 +1,44 @@
use super::*;
use pretty_assertions::assert_eq;
use serde_json::json;
#[test]
fn local_readiness_retains_credential_during_biometric_unavailability() {
let status = UserVerificationStatusResponse {
credential_id: Some("credential".into()),
unavailable_reason: Some(UserVerificationUnavailableReason::BiometricsUnavailable),
unavailable_message: Some("Unlock biometrics to continue.".into()),
};
assert_eq!(
serde_json::to_value(&status).unwrap(),
json!({
"credentialId": "credential",
"unavailableReason": "biometricsUnavailable",
"unavailableMessage": "Unlock biometrics to continue."
})
);
assert_eq!(
serde_json::from_value::<UserVerificationStatusResponse>(
serde_json::to_value(&status).unwrap()
)
.unwrap(),
status
);
}
#[test]
fn error_details_reject_cross_category_reasons_and_native_payloads() {
let details = UserVerificationErrorDetails::Cancelled {
reason: UserVerificationCancellationReason::UserCancelled,
};
assert_eq!(
serde_json::to_value(details).unwrap(),
json!({"type": "cancelled", "reason": "userCancelled"})
);
for invalid in [
json!({"type": "failed", "reason": "userCancelled"}),
json!({"type": "unavailable", "reason": "providerUnavailable", "nativeError": {"code": 1}}),
] {
assert!(serde_json::from_value::<UserVerificationErrorDetails>(invalid).is_err());
}
}