🌐 Dwield Device Intelligence, Behavioural Biometrics & Passkey SDK

Next-Gen Browser Intelligence · Behavioural Biometrics · FIDO2 WebAuthn Passkeys · Adaptive Risk Step-Up

The Dwield SDK (@dwield/device-biometrics-sdk) provides a unified, production-ready JavaScript client for:

• 🖥️ Device Intelligence: Hardware fingerprinting, Canvas, WebGL, Audio context, screen resolution, and bot signal detection.
• 🎯 Behavioural Biometrics: Keystroke dynamics (dwell time, flight time) and mouse velocity tracking.
• 🔑 FIDO2 WebAuthn Passkeys: Browser-native passkey registration and assertion verification via the Dwield Passkey Server.
• 🛡️ Adaptive Authentication: Automated risk score evaluation and step-up binding (ALLOW, STEP_UP, DENY).

📦 Installation

npm install @dwield/device-biometrics-sdk

🚀 Quick Start & Initialization Modes

The SDK can be initialized in three tailored modes depending on your application requirements:

1. Device Info + Behavioural Biometrics + Passkeys (Full Suite - Recommended)

import { initDeviceInfoWithBiometrics } from "@dwield/device-biometrics-sdk";

const sdk = await initDeviceInfoWithBiometrics({
  apiKey: "YOUR_DW_API_KEY",                  // Dwield API Key
  passkeyServerUrl: "http://localhost:3000",   // Dwield Passkey Server URL
  userToken: "dev:user_123",                   // User identity context token
  verbose: true,
});

// Start tracking behavioural dynamics
sdk.initKeyStrokeDynamics();
sdk.initMouseDynamics();

2. Device Info Only + Passkeys

import { initDeviceInfo } from "@dwield/device-biometrics-sdk";

const sdk = await initDeviceInfo({
  apiKey: "YOUR_DW_API_KEY",
  passkeyServerUrl: "http://localhost:3000",
  userToken: "user_123",
});

const deviceData = await sdk.getDeviceData();

3. Biometrics Only + Passkeys

import { initBiometrics } from "@dwield/device-biometrics-sdk";

const sdk = await initBiometrics({
  apiKey: "YOUR_DW_API_KEY",
  userToken: "user_123",
});

sdk.initKeyStrokeDynamics();
sdk.initMouseDynamics();

🔑 Passkey Enrollment (Registration)

Register a new WebAuthn passkey (TouchID, FaceID, Windows Hello, Security Key) for an authenticated user:

// 1. Check browser WebAuthn support
if (sdk.isPasskeySupported()) {
  try {
    const result = await sdk.registerPasskey({
      userName: "[email protected]",
      displayName: "John Doe",
      credentialName: "MacBook TouchID",
      authenticatorSelection: {
        userVerification: "preferred",
        authenticatorAttachment: "platform",
      },
    });

    console.log("✅ Passkey Enrolled:", result.credentialId);
  } catch (err) {
    if (err.code === "USER_CANCELLED") {
      console.log("ℹ️ User cancelled passkey registration");
    } else {
      console.error("❌ Registration error:", err.message);
    }
  }
}

🛡️ Risk-Based Adaptive Authentication & Step-Up

Connect risk evaluation signals with FIDO2 passkey step-up authentication:

Manual Step-Up Authentication

// 1. Generate risk assessment via Dwield Risk Engine
const riskAssessment = await sdk.generateFingerPrint({ userId: "user_123" });

// 2. Perform step-up passkey authentication based on risk decision
const authResult = await sdk.authenticatePasskey({
  riskDecision: riskAssessment.decision, // "ALLOW" | "STEP_UP" | "DENY"
  assessmentId: riskAssessment.assessmentId,
  userVerification: "required",
});

if (authResult.bypassPasskey) {
  console.log("🟢 Risk decision ALLOW: Passkey prompt bypassed.");
} else if (authResult.verified) {
  console.log("🟢 Step-Up Passkey Verified!");
  console.log("Verification Token:", authResult.stepUpVerificationToken);
  
  // Transmit authResult.stepUpVerificationToken to your backend for final redemption
}

Combined Automatic Risk + Passkey Step-Up (evaluateAndAuthenticate)

const result = await sdk.evaluateAndAuthenticate(
  { userId: "user_123", firstName: "John", lastName: "Doe" },
  { userVerification: "preferred" }
);

console.log("Risk Assessment:", result.riskAssessment);
console.log("Passkey Result:", result.passkeyResult);
if (result.stepUpVerificationToken) {
  console.log("Step-Up Verification Token:", result.stepUpVerificationToken);
}

🚦 Risk Decision Policy Semantics

| Decision | SDK Behaviour | Passkey Server Action | | :--- | :--- | :--- | | ALLOW | WebAuthn prompt is bypasssed (bypassPasskey: true). Returns success immediately. | No challenge issued. | | STEP_UP | Initiates a 5-minute single-use step-up session bound to assessmentId. Prompts WebAuthn ceremony. | Verifies passkey assertion signature & issues stepUpVerificationToken. | | DENY | Throws PasskeyError with code RISK_DENIED. Authentication is strictly blocked. | Step-up passkey authentication is prohibited. |

⚠️ Authorization Security Notice:
WebAuthn passkey completion on the browser client does not grant final application access by itself. Your backend must submit the stepUpVerificationToken to the Passkey Server (POST /v1/step-up/verify-token) for redemption before granting privileged application access.

📋 Credential Management

Query and manage enrolled passkeys for the current user session:

// List enrolled credentials for user
const credentials = await sdk.listPasskeys();
console.log("Enrolled Passkeys:", credentials);
// Output: [{ credentialId: "...", credentialName: "MacBook TouchID", createdAt: "..." }]

// Revoke an enrolled credential
const revokeResult = await sdk.revokePasskey(credentials[0].credentialId);
console.log("Credential Revoked:", revokeResult.revoked);

🚨 Error Handling

All passkey methods throw typed PasskeyError objects containing standardized error codes:

import { PasskeyErrorCode } from "@dwield/device-biometrics-sdk";

try {
  await sdk.authenticatePasskey({ riskDecision: "STEP_UP", assessmentId: "asm_123" });
} catch (err) {
  switch (err.code) {
    case PasskeyErrorCode.NOT_SUPPORTED:
      console.warn("Browser does not support WebAuthn passkeys");
      break;
    case PasskeyErrorCode.USER_CANCELLED:
      console.info("User dismissed the WebAuthn prompt");
      break;
    case PasskeyErrorCode.RISK_DENIED:
      console.error("Step-up authentication denied by risk engine");
      break;
    case PasskeyErrorCode.CHALLENGE_EXPIRED:
      console.error("Passkey ceremony or step-up session timed out");
      break;
    case PasskeyErrorCode.SESSION_MISMATCH:
      console.error("Missing required assessmentId for STEP_UP decision");
      break;
    default:
      console.error(`Passkey Error (${err.code}):`, err.message);
  }
}

Complete Error Code Reference

• NOT_SUPPORTED: WebAuthn API unavailable in browser environment.
• USER_CANCELLED: User cancelled WebAuthn biometrics prompt or closed the dialog.
• NETWORK_ERROR: Network connectivity failure when reaching Passkey Server.
• CHALLENGE_EXPIRED: WebAuthn challenge or step-up session expired.
• VERIFICATION_FAILED: Server-side assertion verification failed.
• RISK_DENIED: Step-up request rejected due to DENY risk policy.
• INVALID_RESPONSE: Malformed JSON or invalid server response structure.
• UNAUTHORIZED: Invalid tenant API key or missing user token context (X-Dwield-User-Token).
• CONFIG_ERROR: Missing SDK configuration.
• SESSION_MISMATCH: STEP_UP decision passed without valid assessmentId.

🛠️ Complete API Reference

Initialization Functions

• initDeviceInfo(config: SDKConfig): Promise<DeviceInfoSDK>
• initBiometrics(config: SDKConfig): Promise<BiometricsSDK>
• initDeviceInfoWithBiometrics(config: SDKConfig): Promise<DeviceInfoWithBiometricsSDK>

Standalone Exported Passkey Functions

• isPasskeySupported(): boolean
• isPlatformAuthenticatorAvailable(): Promise<boolean>
• registerPasskey(options?: PasskeyRegistrationOptions, config?: SDKConfig): Promise<PasskeyRegistrationResult>
• authenticatePasskey(options?: PasskeyAuthenticationOptions, config?: SDKConfig): Promise<PasskeyAuthenticationResult>
• evaluateAndAuthenticate(userInfo: UserInfo, options?: PasskeyAuthenticationOptions, config?: SDKConfig): Promise<{ riskAssessment: any, passkeyResult: PasskeyAuthenticationResult, stepUpVerificationToken?: string }>
• listPasskeys(options?: { userToken?: string }, config?: SDKConfig): Promise<PasskeyCredential[]>
• revokePasskey(credentialId: string, options?: { userToken?: string }, config?: SDKConfig): Promise<{ revoked: boolean, credentialId: string }>

💻 Interactive Demo

An interactive demonstration is located in example/index.html. Open it directly in any WebAuthn-compatible browser (Chrome, Safari, Edge, Firefox) or serve via local web server to test live fingerprinting, passkey registration, and adaptive step-up authentication.

📄 License

Proprietary — Dwield Technologies.