WebAuthn Action Attestation

Certain events in enterprise platforms are irreversible: deleting patient health files, finalizing clinical consent documents, or releasing billing refunds. When auditing high-risk actions, a simple database flag saying “User X approved this” is not sufficient.

Volidator provides WebAuthn Action Attestation to cryptographically link biological human presence to specific, structured payloads.

---

How It Works

Action Attestation is designed to replace traditional friction points like two-factor authentication SMS codes or confirmation dialogs. By using native operating system credentials (TouchID, FaceID, or security keys), the approval check runs in ~300 milliseconds directly within the browser interface.

---

Integration Walkthrough

1. Attesting the Action (Client-Side)

Before executing a sensitive backend mutation, web application requests a cryptographic attestation from the user’s browser.

The SDK triggers the native biometric prompt:

import { volidator } from "@/lib/volidator-client";

// Call this function when the user clicks the "Finalize Consent" button
async function handleFinalizeApproval(formId: string) {
  try {
    // 1. Fetch challenge & sign the structured payload biometrically
    const attestation = await volidator.attestHumanAction({
      action: "consent.finalize",
      target: `form_${formId}`,
      metadata: {
        patientId: "pt_891",
        formVersion: "v3.2"
      }
    });

    // 2. Submit the signature along with your backend API request
    await fetch(`/api/forms/${formId}/finalize`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ attestation })
    });

  } catch (error) {
    console.error("Biometric approval rejected:", error);
  }
}

---

The Handshake Protocol

When volidator.attestHumanAction() is called:

1. Challenge Request: The SDK contacts Volidator’s /v1/attestation/challenge endpoint, passing the payload (action, target, and metadata).
2. Deterministic Hashing: The server canonicalizes the payload using a sorted key-value serialization engine and returns a unique challenge UUID mapped to the payload hash.
3. Biometric Signing: The SDK combines the challenge UUID and the payload hash into a binary byte array and prompts the native OS biometric device (navigator.credentials.get()).
4. API Ingestion: The signed assertion is passed to your server, which forwards it to Volidator inside the log metadata payload.
5. Replay & Concurrency Protection: The Ingestion Worker verifies the signature and immediately destroys the challenge in the strongly consistent challenge store. Any attempt to reuse the same signature or challenge will result in an ingestion error.

---

Cryptographic Canonicalization

To ensure that key ordering in JavaScript objects does not cause signature verification failures, both the client SDK and the ingestion worker serialize the payload using a strict, key-sorted serializer:

// Keys are sorted alphabetically to guarantee identical hashing across nodes
{"action":"consent.finalize","metadata":{"formVersion":"v3.2","patientId":"pt_891"},"target":"form_formId"}

---

Threat Model & UI-Layer Trust

Action Attestation is designed to protect the transport layer, API gateway, and audit trail databases. However, developers should be aware of a fundamental boundary:

[!WARNING] Biometric “Blind Signing” Boundary WebAuthn enclaves and security keys (YubiKeys) sign raw byte arrays; they do not have screens to display the structured payload to the user (e.g. they cannot display “Do you approve Consent Form 4821?”).

Therefore, this signature proves biometric presence and network request integrity, but it assumes the browser DOM has not been compromised by malware. Ensuring a secure client-side execution environment remains the application developer’s responsibility.