1. Introduction

1.1. Document Purpose

This document provides a comprehensive technical reference for implementing WebAuthn (passkeys) as a profile in the Universal Resolver Matrix (URM). It expands the normative specification in WebAuthn Resolver Profile (ENSIP-XX) into a single technical reference for implementing WebAuthn resolution as resolver profiles in the URM.

1.2. Universal Resolver Matrix Framework

The Universal Resolver Matrix (URM) is a systematic framework for mapping resolution pathways across namespaces using four core dimensions:

1. Trust Model,
2. Proof System,
3. Rules & Lifecycle, and
4. Verification Path.

This document structures WebAuthn implementation around these dimensions, with additional sections covering implementation details:

• Contract & Namespace Inventory
• URM Mapping (Resolver Profiles)
• Edge Cases & Client Requirements

2. Scope & Goals

2.1. WebAuthn Overview

WebAuthn enables passkeys as ENS controllers and credential-based authentication for ENS names. It provides a standardized, cryptographically secure way to use WebAuthn ES256 signatures (P-256 ECDSA) for ENS name control and authentication via a two-phase verification process.

2.2. Profile Scope

WebAuthn resolution defines two resolver profiles:

1. Profile 1 (Controller): Passkeys as ENS controllers — enables WebAuthn credentials to control and manage ENS names (update records, set resolver, etc.)
2. Profile 2 (Credential Resolution): WebAuthn credential resolution — enables resolving/verifying ENS names that have WebAuthn credentials stored in their records

2.3. WebAuthn vs Non-WebAuthn Credentials

WebAuthn resolution provides trustless onchain verification on Namechain. For Profile 2, an optional hybrid approach is available for cost-sensitive applications:

Primary Approach (Trustless): Direct onchain verification on Namechain.

Optional Hybrid Approach (Cost-Efficient): Gateway verifies offchain, stores attestations onchain for high-frequency use cases.

2.4. WebAuthn Scope & Algorithm Support

This document focuses exclusively on WebAuthn ES256 (P-256 ECDSA) credential verification. WebAuthn is uniquely positioned for onchain verification because it uses the P-256 elliptic curve, which has dedicated precompile support (EIP-7951) on both Ethereum L1 and Namechain.

Other credential types (RS256, EdDSA, ES384, etc.) cannot be verified onchain without additional precompiles or offchain services, breaking the trustless model that WebAuthn enables.

2.5. Deployment Architecture: Full Namechain

Since Namechain launches with EIP-7951 (P-256 precompile) support, WebAuthn uses a fully onchain deployment on Namechain (ENS L2). The system requires exactly 3 core contracts deployed entirely on Namechain.

2.5.1. Architecture Overview

All WebAuthn infrastructure deploys on Namechain (ENS L2) for cost-effective, trustless operations:

• EIP-7951 at launch: Namechain includes P-256 precompile from day one
• Cost-effectiveness: All operations at Namechain gas prices
• Trustlessness: Full onchain verification with L1 state commitment
• Simplicity: No cross-chain calls, direct onchain operations
• ENSv2 native: Part of the core ENS L2 infrastructure

2.5.2. Contract Inventory (3-Contract Pattern)

• ENS Registry (L1)
• Universal Resolver (L1)

1. WebAuthnVerifier (Namechain) - Validates WebAuthn ES256 signatures using EIP-7951 precompile
2. WebAuthnControllerResolver (Namechain) - Stores public key bindings for passkey control
3. WebAuthnCredentialResolver (Namechain) - Handles credential resolution with direct onchain verification

2.5.3. Roots of Trust & Security

The canonical root of trust consists of:

• ENS Registry on Ethereum L1: Primary source of truth for all name registrations and resolver assignments
• WebAuthnVerifier on Namechain: Trustless cryptographic verification using EIP-7951 P-256 precompile
• Resolver contracts on Namechain: Store public key bindings and handle verification logic

Security is inherited from Ethereum consensus, P-256 cryptographic security, and WebAuthn standard security guarantees. All WebAuthn contracts deploy on Namechain (ENS L2) from launch, with state committed to L1 providing the same security as L1 infrastructure.

2.5.4. Benefits & Tradeoffs

This full Namechain architecture provides:

• Ultra-low costs: All operations at Namechain gas prices
• Simplified architecture: No cross-chain calls, direct onchain verification
• Full trustlessness: All operations on Namechain (ENS L2, state committed to L1)
• Performance: Fast verification without cross-chain bridge delays
• ENSv2 native: Core infrastructure deployed on ENS L2 from launch
• Gateway optional: With virtually free verification costs, gateway approaches may be unnecessary for most use cases

2.5.5. Governance Requirements

While not strictly required for basic resolver operation, a production-ready WebAuthn resolver should go through ENS DAO governance for integration into core ENS infrastructure. DAO approval is required if you want your resolver to be:

• Set as the default resolver for ENS (e.g., for the reverse registrar or for .eth names)
• Integrated at the protocol level (e.g., replacing the public resolver, or being referenced in official ENS contracts)

DAO approval is a matter of governance and trust. If you want your resolver to be widely used, trusted, or set as a default in ENS infrastructure, DAO approval:

• Signals community trust and security review
• Ensures the resolver is maintained and meets ENS standards
• Protects against unauthorized trust anchor modifications during key rollovers

For WebAuthn implementations, governance approval is particularly important due to the novel authentication paradigm and hardware security dependencies. DAO approval ensures that WebAuthn resolvers meet community standards for user experience, security, and compatibility with existing ENS infrastructure while pioneering passkey-based name control.

3. Trust Model

3.1. Roots of Trust

The canonical root of trust for WebAuthn resolution differs between profiles but shares the same cryptographic verification infrastructure:

• ENS name owner's authorization — The ultimate source of trust is the ENS name owner's explicit authorization stored onchain. When a name owner registers a WebAuthn public key via registerWebAuthnKey(), this creates an onchain binding: namehash("alice.eth") → publicKey. This binding is stored in the WebAuthnControllerResolver contract and can only be created or modified by the ENS name owner (verified via ensRegistry.owner(node) == msg.sender).

• ENS record itself — The root of trust is the ENS text record containing the WebAuthn credential. When a name owner sets text(node, "webauthn-credential") = public key, this creates an implicit binding: the credential exists in the ENS record for that name. The name owner controls this record (via standard ENS ownership), so the credential's presence in the record serves as proof of authorization.

• P-256 ECDSA signatures — Both profiles rely on WebAuthn ES256 signatures (ECDSA over P-256 curve) verified onchain via the EIP-7951 P-256 precompile. The cryptographic security of P-256 ECDSA is the foundation for all signature verification.

3.2. Security Guarantees

Security properties include:

• Cryptographic authenticity — WebAuthn signatures prove that assertions originated from the device holding the private key corresponding to the registered public key
• Integrity protection — WebAuthn assertions include authenticatorData and clientDataJSON, which are hashed and signed
• Non-repudiation — Users cannot deny having signed an assertion
• Trust minimization — Security depends only on ENS name ownership, onchain authorization, and Ethereum consensus
• Onchain verification — All cryptographic signature verification happens onchain via the EIP-7951 P-256 precompile

3.3. Trust Assumptions by Profile

3.3.1. Profile 1 (Controller)

Users trust the WebAuthnControllerResolver contract on Namechain correctly stores authorized public keys and only allows authorized passkeys to update ENS records. The resolver verifies name ownership via ENS Registry on L1 and cryptographic signatures via WebAuthnVerifier on Namechain.

3.3.2. Profile 2 (Credential Resolution)

Primary Approach: Users trust the cryptographic verification happens entirely onchain on Namechain using EIP-7951 precompile. Full trustlessness through Namechain (ENS L2, committed to L1).

Optional Hybrid Approach: Users trust that gateway attestations stored onchain provide sufficient audit trail, with cryptographic verification of gateway signatures. Gateway signatures are verifiable onchain, allowing detection of misbehavior.

4. Proof System

4.1. Inputs & Core Definitions

WebAuthn resolution takes a WebAuthn assertion as input, containing:

• authenticatorData: 37+ byte structure containing flags, sign count, RP ID hash
• clientDataJSON: JSON string containing challenge, origin, type
• signature: 64 bytes (32-byte r, 32-byte s) ECDSA P-256 signature
• challenge: Original challenge value for freshness verification
• publicKey: P-256 public key coordinates (X, Y) for signature verification

• authenticatorData: Contains UP/UV flags, sign count, attested credential data, and extensions
• clientDataJSON: JSON containing type, challenge, origin, and optional fields
• challenge: Random nonce to prevent replay attacks, verified for freshness
• signature: P-256 ECDSA signature over SHA-256(authenticatorData || SHA-256(clientDataJSON))
• publicKeyX/Y: P-256 public key coordinates used for signature verification

4.2. Cryptographic Primitives

4.2.1. ECDSA P-256 (ES256)

WebAuthn uses ECDSA over the P-256 (secp256r1) curve for signature verification. The P-256 precompile (EIP-7951) enables efficient onchain verification (~3,000 gas). Signatures are computed over the hash: SHA-256(authenticatorData || SHA-256(clientDataJSON)).

4.2.2. SHA-256

Secure Hash Algorithm 256-bit, used for hashing authenticatorData and clientDataJSON. Implemented in Solidity for onchain verification (~2,000-3,000 gas per hash).

4.2.3. Keccak256

Ethereum's native hash function, used for challenge hashing and gateway attestation verification. Native precompile, very cheap (~30 gas).

4.3. Proof Types (URM Terms)

4.3.1. webauthn_proof(es256)

• Profile 1: When updating ENS records using passkey authentication
• Profile 2: When authenticating to dApps or proving control of an ENS name

1. User generates WebAuthn assertion using passkey
2. Resolver on Namechain calls WebAuthnVerifier directly on Namechain
3. Namechain verifier reconstructs hash: SHA-256(authenticatorData || SHA-256(clientDataJSON))
4. Verifies ECDSA P-256 signature using EIP-7951 precompile on Namechain
5. Validates challenge freshness, origin/RP ID
6. Returns verification result directly on Namechain

4.3.2. gateway_attestation

• Profile 2: Optional hybrid gateway + attestations for cost-sensitive applications

1. Gateway verifies WebAuthn signature offchain (free)
2. Gateway creates attestation: (node, challengeHash, timestamp, gatewaySignature)
3. Gateway stores attestation onchain via resolver
4. Resolver verifies gateway signature using ecrecover
5. dApp reads attestation and verifies freshness

4.4. Proof Formats

4.4.1. WebAuthn Assertion

{
  authenticatorData: bytes,    // 37+ bytes - includes flags, counter, RP ID hash
  clientDataJSON: string,       // JSON string - includes challenge, origin, type
  signature: bytes,             // 64 bytes - ECDSA P-256 signature (r, s)
  challenge: bytes32,           // SHA-256 hash of challenge
  publicKeyX: uint256,         // P-256 public key X coordinate
  publicKeyY: uint256          // P-256 public key Y coordinate
}

4.4.2. Gateway Attestation (Hybrid Approach)

{
  node: bytes32,                // namehash("alice.eth")
  challengeHash: bytes32,       // keccak256(challenge)
  timestamp: uint256,           // block.timestamp when verified
  gatewaySignature: bytes       // Gateway's ECDSA signature over the attestation
}

4.5. Algorithms

4.5.1. WebAuthn Signature Verification

1. Input: authenticatorData, clientDataJSON, signature, publicKeyX, publicKeyY, challenge
2. Process:
   • Reconstruct message hash: hash = SHA-256(authenticatorData || SHA-256(clientDataJSON))
   • Verify ECDSA P-256 signature using precompile
   • Extract challenge from clientDataJSON and verify freshness
   • Verify origin/RP ID matches expected value
3. Output: bool valid, bytes32 challenge

4.5.2. Challenge Freshness Check

1. Input: challengeTimestamp, currentTimestamp
2. Process: Check age ≤ CHALLENGE_FRESHNESS_WINDOW (5 minutes)
3. Output: bool isFresh

4.6. Proof Generation & Validation Flow

4.6.1. WebAuthn Proof Generation

1. Client generates challenge: challenge = keccak256(nonce + timestamp + random)
2. User signs via WebAuthn API: navigator.credentials.get()
3. Browser/device returns assertion: {authenticatorData, clientDataJSON, signature}

1. Resolver calls WebAuthnVerifier.verify() directly on Namechain
2. Namechain verifier performs cryptographic validation
3. Returns result directly on Namechain

4.6.2. Gateway Attestation Generation (Hybrid)

1. Gateway receives WebAuthn assertion
2. Gateway verifies signature offchain using cryptographic libraries
3. Gateway creates attestation with secp256k1 signature
4. Gateway stores attestation onchain via resolver

1. Resolver verifies gateway signature using ecrecover
2. Checks attestation timestamp freshness
3. dApp reads attestation for authentication

5. Rules & Lifecycle

5.1. High-Level Rules for WebAuthn Credentials

To establish a verified WebAuthn credential:

1. Create WebAuthn credential: User creates a passkey using their device
2. Register credential onchain: Name owner registers the public key onchain (Profile 1) or sets in text record (Profile 2)
3. Credential verified and ready: Once registered, the credential is available for verification

• Register: Name owner registers passkey (one-time setup, requires wallet/gas)
• Update: Use passkey to update ENS records (ongoing, may require gas or use meta-transactions)
• Remove: Revoke passkey authorization
• Expiry: Challenges expire after 5 minutes to prevent replay attacks

5.2. WebAuthn-Specific Rules

• Challenge must match exactly between clientDataJSON and provided challenge
• Challenge must be fresh (within 5-minute window)

• Origin from clientDataJSON must match expected relying party
• RP ID hash in authenticatorData must match expected identifier

• Profile 1: Public key must match authorized key in resolver contract
• Profile 2: Public key must match credential in ENS text record

• Signature must be valid ECDSA P-256 signature over the computed hash
• Only ES256 algorithm supported (other algorithms require offchain verification)

5.3. Credential Types

6. Verification Path

6.1. Component Responsibilities

• Validates WebAuthn ES256 signatures using EIP-7951 P-256 precompile
• Performs SHA-256 hashing, challenge validation, freshness checks
• Returns verification results to calling resolvers

• Stores authorized public keys for ENS names
• Verifies name ownership via ENS Registry
• Calls Namechain verifier for signature verification before executing ENS updates

• Fetches WebAuthn credentials from ENS text records
• Supports direct onchain verification with optional hybrid gateway + attestations
• Provides authentication success/failure to dApps

• Fetches credentials via CCIP-Read (if needed)
• Verifies signatures offchain for optional hybrid approach
• Creates and stores attestations onchain

6.2. Generic WebAuthn Verification Flow

Given a WebAuthn assertion:

1. Client generates challenge with timestamp
2. User signs challenge with passkey via WebAuthn API
3. Returns assertion containing authenticatorData, clientDataJSON, signature

1. Resolver fetches public key (Profile 1: from contract storage, Profile 2: from text record)
2. Prepares verification request with assertion data

1. Direct Verification: Resolver calls Namechain verifier directly
2. Hybrid Approach: Gateway verifies offchain, stores attestation onchain
3. Verification succeeds if signature valid and all checks pass

6.3. Resolver / Gateway Topology

The WebAuthn system consists of:

• ENS Registry (L1): Manages resolver assignments
• WebAuthnVerifier (Namechain): Cryptographic verification
• WebAuthnControllerResolver (Namechain): Profile 1 implementation
• WebAuthnCredentialResolver (Namechain): Profile 2 implementation
• CCIP-Read Gateways: Data fetching and attestation services

6.4. Minimal Client-Side Pseudocode

async function verifyWebAuthnAssertion(
  node: string,
  resolverAddress: string,
  profile: 'controller' | 'credential',
  action?: { type: 'setText', params: any }
): Promise<boolean> {
  // Generate challenge
  const challenge = keccak256(nonce + timestamp + random);
  
  // Get WebAuthn assertion from user
  const assertion = await navigator.credentials.get({
    publicKey: { challenge: challengeBytes, rpId, timeout: 60000 }
  });
  
  // Extract assertion components
  const { authenticatorData, clientDataJSON, signature } = assertion.response;
  
  // Fetch credential
  const publicKey = await fetchCredential(node, resolverAddress);
  
  // Call resolver verification
  const resolver = new ethers.Contract(resolverAddress, ABI, signer);
  const result = await resolver.verifyCredential(
    node, authenticatorData, clientDataJSON, signature, 
    publicKey.x, publicKey.y, challenge
  );
  
  return result.valid;
}

6.5. Example Implementation Flow

1. User creates passkey: navigator.credentials.create()
2. User registers public key: registerWebAuthnKey(node, publicKeyX, publicKeyY)
3. Binding stored onchain: authorizedKeys[node] = (publicKeyX, publicKeyY)
4. User can now update ENS records using passkey authentication

1. dApp requests authentication for "alice.eth"
2. Client generates challenge and prompts user for passkey
3. User signs with passkey
4. Resolver verifies signature (direct onchain or optional hybrid)
5. dApp grants access if verification succeeds

7. Contract & Namespace Inventory

7.1. Core Constants & Helpers

• ALGORITHM_ES256 = "ES256"
• CURVE_P256 = "P-256"
• SIGNATURE_LENGTH = 64
• PUBLIC_KEY_LENGTH = 64
• CHALLENGE_FRESHNESS_WINDOW = 300 (5 minutes)
• ATTESTATION_FRESHNESS_WINDOW = 300 (5 minutes)
• TEXT_KEY_WEBAUTHN_CREDENTIAL = "webauthn-credential"

7.2. Namespaces

WebAuthn works with standard ENS namespaces:

• .eth primary names
• Subdomains at any level
• Reverse resolution support

7.3. Contract Types

• Validates WebAuthn ES256 signatures
• Uses EIP-7951 P-256 precompile
• Shared by both profiles

• Stores public key bindings for passkey control
• Implements ENS resolver interface with WebAuthn verification

• Fetches credentials from ENS records
• Supports dual verification approaches

7.4. Implementation Requirements (3-Contract Pattern)

1. WebAuthnVerifier on Namechain (cryptographic verification using EIP-7951 at launch)
2. WebAuthnControllerResolver on Namechain (Profile 1 with direct verifier calls)
3. WebAuthnCredentialResolver on Namechain (Profile 2 with direct verifier calls)

• All contracts deploy on Namechain from launch
• Direct onchain verification calls
• Gateway + attestations optional for cost-sensitive applications
• Full trustlessness through Namechain (ENS L2, committed to L1)

8. URM Mapping (Resolver Profiles)

WebAuthn defines two resolver profiles:

8.1. Profile 1 – WebAuthn Controller (webauthn-controller)

Enables passkeys to control ENS names. Requires onchain binding via registerWebAuthnKey(). Uses webauthn_proof(es256) with cross-chain verification to L1.

8.2. Profile 2 – WebAuthn Credential Resolution (webauthn-credential-resolution)

Enables authentication using WebAuthn credentials stored in ENS records. Since all verification happens on Namechain, the approach is simplified:

• Direct onchain verification (~$0.01-0.05 per verification)
• Full trustlessness through Namechain (ENS L2, committed to L1)
• No cross-chain calls required

• Gateway + attestations
• Useful when frequent verifications are needed
• Maintains onchain audit trail

9.4. Architecture Rationale

9.5.1. Why Full Namechain Architecture?

• Namechain launches with P-256 precompile (EIP-7951) support
• No need for cross-chain verification architecture
• Direct onchain verification from day one

• All operations at Namechain gas prices
• ~50x cheaper than L1-only deployment
• Enables practical WebAuthn adoption for consumer applications

• Full onchain verification on Namechain (ENS L2)
• State committed to L1 provides same security guarantees
• No additional trust assumptions beyond Namechain itself

9.5.2. Architecture Advantages

This full Namechain architecture provides:

• Ultra-low costs: Virtually free verification using EIP-7951 precompile
• Simplified deployment: All contracts on Namechain from launch
• Instant verification: Direct onchain calls without cross-chain delays
• Trustless security: Full verification on Namechain (ENS L2, state committed to L1)
• Optional gateway support: Hybrid approaches available for cost-sensitive high-frequency applications
• ENSv2 native: Core infrastructure leveraging Namechain's P-256 precompile

9.5.3. Implementation Strategy

• All 3 contracts deploy on Namechain from launch
• Direct verifier calls between contracts
• CCIP-Read support for credential fetching (if needed)

• Resolvers call WebAuthnVerifier directly on Namechain
• No cross-chain bridge interactions
• All verification logic executes on Namechain EVM

• Gateway + attestations available for applications needing sub-cent costs
• Useful for high-frequency authentication scenarios
• Maintains onchain audit trail while reducing per-verification costs

9. Edge Cases & Client Requirements

9.1. Algorithm Support

• WebAuthn resolvers only support ES256 (P-256 ECDSA)
• Other algorithms require offchain verification
• Clients should filter credentials during selection

9.2. Challenge Expiry

• Default: 5 minutes for challenges
• Extended: 10 minutes for some use cases
• Expired challenges are rejected onchain

• Generate fresh challenges for each authentication
• Handle expiry gracefully by regenerating challenges
• Don't submit expired assertions

9.3. Credential Revocation

• Revoke via removeWebAuthnKey() or register new key
• Immediate effect onchain

• Update text record to remove credential
• Old credential invalid immediately

9.4. Client Requirements

Clients must:

• Generate fresh challenges with timestamps
• Validate challenge format and freshness
• Handle OffchainLookup errors for CCIP-Read
• Verify assertion format before submission
• Respect freshness windows

Clients must not:

• Reuse challenges
• Submit invalid signature formats
• Skip challenge validation
• Trust gateway verification without onchain checks (for full trustless mode)

9.5. URM Implementation Notes

• WebAuthn profiles build on existing ENS infrastructure
• ES256 requirement ensures onchain verifiability
• Dual verification paths in Profile 2 enable cost/security tradeoffs
• Gateway attestations provide audit trail for hybrid approach