electron-webauthn 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Evan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,266 @@
+# electron-webauthn
+
+A high-performance, cross-platform WebAuthn/Passkey implementation for Electron applications, built with Rust and native platform APIs.
+
+## Overview
+
+This library provides seamless WebAuthn (Web Authentication) and Passkey support for Electron applications across multiple platforms. It leverages native platform authenticators including Touch ID, Face ID, Windows Hello, and security keys to deliver a secure and user-friendly authentication experience.
+
+### Key Features
+
+- **Native Platform Integration**: Uses platform-specific APIs for optimal performance and security
+- **Cross-Platform Support**: Works on macOS, Windows, and Linux
+- **WebAuthn Level 2 Compliance**: Full support for the latest WebAuthn specifications
+- **Biometric Authentication**: Touch ID, Face ID, Windows Hello, and Apple Watch support
+- **Secure Enclave Integration**: Hardware-backed key storage on supported platforms
+- **TypeScript Support**: Complete type definitions included
+
+## Requirements
+
+### macOS
+
+- **macOS 13+ (Ventura or later)** - Required for ASAuthorization framework
+- Touch ID, Face ID, or Apple Watch for biometric authentication
+- Valid code signing certificate for production use
+
+### Windows
+
+- **Windows 10 version 1903+ or Windows 11**
+- Windows Hello capable device (fingerprint, face recognition, or PIN)
+
+### Linux
+
+- Modern Linux distribution with WebAuthn support
+- Compatible authenticator device
+
+## Installation
+
+```bash
+npm install electron-webauthn
+# or
+yarn add electron-webauthn
+```
+
+## Usage
+
+### Basic Registration (Creating a Credential)
+
+```typescript
+import { createCredential } from "electron-webauthn";
+
+const options = {
+  rp: {
+    id: "example.com",
+    name: "Example Corp",
+  },
+  user: {
+    id: new Uint8Array([1, 2, 3, 4]),
+    name: "user@example.com",
+    displayName: "John Doe",
+  },
+  challenge: new Uint8Array(32), // Generate random 32 bytes
+  pubKeyCredParams: [
+    { type: "public-key", alg: -7 }, // ES256
+    { type: "public-key", alg: -257 }, // RS256
+  ],
+  authenticatorSelection: {
+    authenticatorAttachment: "platform",
+    userVerification: "required",
+  },
+};
+
+try {
+  const credential = await createCredential(options);
+  console.log("Registration successful:", credential);
+} catch (error) {
+  console.error("Registration failed:", error);
+}
+```
+
+### Basic Authentication (Getting a Credential)
+
+```typescript
+import { getCredential } from "electron-webauthn";
+
+const options = {
+  rpId: "example.com",
+  challenge: new Uint8Array(32), // Generate random 32 bytes
+  allowCredentials: [
+    {
+      type: "public-key",
+      id: credentialId, // From previous registration
+    },
+  ],
+  userVerification: "required",
+};
+
+try {
+  const assertion = await getCredential(options);
+  console.log("Authentication successful:", assertion);
+} catch (error) {
+  console.error("Authentication failed:", error);
+}
+```
+
+## Platform Support
+
+| Platform | Architecture  | Status | Notes                          |
+| -------- | ------------- | ------ | ------------------------------ |
+| macOS    | arm64         | ✅     | Native ASAuthorization support |
+| macOS    | x64           | ✅     | Native ASAuthorization support |
+| macOS    | universal     | ✅     | Universal binary               |
+| Windows  | x64           | ✅     | Windows Hello integration      |
+| Windows  | arm64         | ✅     | Windows Hello integration      |
+| Windows  | ia32          | ✅     | Windows Hello integration      |
+| Linux    | x64 (GNU)     | ✅     | Generic WebAuthn support       |
+| Linux    | x64 (musl)    | ✅     | Alpine Linux compatible        |
+| Linux    | arm64 (GNU)   | ✅     | ARM64 Linux support            |
+| Linux    | arm64 (musl)  | ✅     | ARM64 Alpine support           |
+| Linux    | riscv64 (GNU) | ✅     | RISC-V architecture            |
+
+## macOS Entitlements
+
+For macOS applications, you need to include the following entitlements in your `entitlements.plist` file:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <!-- Required for WebAuthn/Passkey support -->
+    <key>com.apple.developer.authentication-services.autofill-credential-provider</key>
+    <true/>
+
+    <!-- Required for platform authenticator access -->
+    <key>com.apple.developer.web-browser</key>
+    <true/>
+
+    <!-- Required for Touch ID/Face ID/Apple Watch access -->
+    <key>com.apple.security.device.biometry</key>
+    <true/>
+
+    <!-- Required for keychain access -->
+    <key>keychain-access-groups</key>
+    <array>
+        <string>$(AppIdentifierPrefix)com.yourcompany.yourapp</string>
+    </array>
+
+    <!-- Optional: For network requests to verify credentials -->
+    <key>com.apple.security.network.client</key>
+    <true/>
+</dict>
+</plist>
+```
+
+### Electron Builder Configuration
+
+If using `electron-builder`, add the entitlements to your `package.json`:
+
+```json
+{
+  "build": {
+    "mac": {
+      "entitlements": "build/entitlements.mac.plist",
+      "entitlementsInherit": "build/entitlements.mac.plist",
+      "hardenedRuntime": true
+    }
+  }
+}
+```
+
+## Development
+
+### Prerequisites
+
+- Node.js 16+
+- Rust 1.70+
+- Platform-specific build tools:
+  - **macOS**: Xcode Command Line Tools
+  - **Windows**: Visual Studio Build Tools
+  - **Linux**: build-essential
+
+### Building from Source
+
+```bash
+# Clone the repository
+git clone https://github.com/your-org/electron-webauthn.git
+cd electron-webauthn
+
+# Install dependencies
+npm install
+
+# Build the native module
+npm run build
+
+# Run tests
+npm test
+```
+
+### Architecture
+
+This library uses:
+
+- **Rust** for high-performance native implementations
+- **NAPI-RS** for seamless Node.js bindings
+- **Platform-specific APIs**:
+  - macOS: ASAuthorization framework
+  - Windows: Windows Hello APIs
+  - Linux: Generic WebAuthn implementation
+
+## Error Handling
+
+The library provides detailed error messages for common scenarios:
+
+```typescript
+try {
+  const credential = await createCredential(options);
+} catch (error) {
+  switch (error.code) {
+    case "NotSupportedError":
+      console.log("WebAuthn not supported on this platform");
+      break;
+    case "SecurityError":
+      console.log("Security requirements not met");
+      break;
+    case "NotAllowedError":
+      console.log("User cancelled or timeout occurred");
+      break;
+    default:
+      console.log("Unexpected error:", error.message);
+  }
+}
+```
+
+## Security Considerations
+
+- Always validate challenges on your server
+- Use HTTPS in production environments
+- Implement proper CORS policies
+- Store credentials securely on your backend
+- Regularly update the library for security patches
+
+## Contributing
+
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
+
+### Development Setup
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests for new functionality
+5. Submit a pull request
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Support
+
+- **Issues**: [GitHub Issues](https://github.com/your-org/electron-webauthn/issues)
+- **Documentation**: [API Documentation](https://docs.your-org.com/electron-webauthn)
+- **Community**: [Discussions](https://github.com/your-org/electron-webauthn/discussions)
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for a detailed history of changes.

package/index.d.ts

@@ -0,0 +1,68 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/* auto-generated by NAPI-RS */
+
+export interface PublicKeyCredentialRpEntity {
+  id?: string | undefined
+  name: string
+}
+export interface PublicKeyCredentialUserEntity {
+  id: Buffer
+  name: string
+  displayName: string
+}
+export interface PublicKeyCredentialParameters {
+  type: string
+  alg: number
+}
+export interface AuthenticatorSelectionCriteria {
+  authenticatorAttachment?: string | undefined
+  requireResidentKey?: boolean | undefined
+  residentKey?: string | undefined
+  userVerification?: string | undefined
+}
+export interface PublicKeyCredentialDescriptor {
+  type: string
+  id: Buffer
+  transports?: Array<string> | undefined
+}
+export interface PublicKeyCredentialCreationOptions {
+  rp: PublicKeyCredentialRpEntity
+  user: PublicKeyCredentialUserEntity
+  challenge: Buffer
+  pubKeyCredParams: Array<PublicKeyCredentialParameters>
+  timeout?: number | undefined
+  excludeCredentials?: Array<PublicKeyCredentialDescriptor> | undefined
+  authenticatorSelection?: AuthenticatorSelectionCriteria | undefined
+  attestation?: string | undefined
+}
+export interface PublicKeyCredentialRequestOptions {
+  challenge: Buffer
+  timeout?: number | undefined
+  rpId?: string | undefined
+  allowCredentials?: Array<PublicKeyCredentialDescriptor> | undefined
+  userVerification?: string | undefined
+}
+export interface AuthenticatorAttestationResponse {
+  clientDataJson: Buffer
+  attestationObject: Buffer
+  transports: Array<string>
+}
+export interface AuthenticatorAssertionResponse {
+  clientDataJson: Buffer
+  authenticatorData: Buffer
+  signature: Buffer
+  userHandle?: Buffer | undefined
+}
+export interface PublicKeyCredential {
+  id: string
+  rawId: Buffer
+  response: AuthenticatorAttestationResponse | AuthenticatorAssertionResponse
+  authenticatorAttachment?: string | undefined
+  type: string
+}
+/** Create a new WebAuthn credential */
+export declare function create(options: PublicKeyCredentialCreationOptions): PublicKeyCredential
+/** Get/authenticate with an existing WebAuthn credential */
+export declare function get(options: PublicKeyCredentialRequestOptions): PublicKeyCredential

package/index.js

@@ -0,0 +1,316 @@
+/* tslint:disable */
+/* eslint-disable */
+/* prettier-ignore */
+
+/* auto-generated by NAPI-RS */
+
+const { existsSync, readFileSync } = require('fs')
+const { join } = require('path')
+
+const { platform, arch } = process
+
+let nativeBinding = null
+let localFileExisted = false
+let loadError = null
+
+function isMusl() {
+  // For Node 10
+  if (!process.report || typeof process.report.getReport !== 'function') {
+    try {
+      const lddPath = require('child_process').execSync('which ldd').toString().trim()
+      return readFileSync(lddPath, 'utf8').includes('musl')
+    } catch (e) {
+      return true
+    }
+  } else {
+    const { glibcVersionRuntime } = process.report.getReport().header
+    return !glibcVersionRuntime
+  }
+}
+
+switch (platform) {
+  case 'android':
+    switch (arch) {
+      case 'arm64':
+        localFileExisted = existsSync(join(__dirname, 'electron-webauthn.android-arm64.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./electron-webauthn.android-arm64.node')
+          } else {
+            nativeBinding = require('electron-webauthn-android-arm64')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'arm':
+        localFileExisted = existsSync(join(__dirname, 'electron-webauthn.android-arm-eabi.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./electron-webauthn.android-arm-eabi.node')
+          } else {
+            nativeBinding = require('electron-webauthn-android-arm-eabi')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on Android ${arch}`)
+    }
+    break
+  case 'win32':
+    switch (arch) {
+      case 'x64':
+        localFileExisted = existsSync(
+          join(__dirname, 'electron-webauthn.win32-x64-msvc.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./electron-webauthn.win32-x64-msvc.node')
+          } else {
+            nativeBinding = require('electron-webauthn-win32-x64-msvc')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'ia32':
+        localFileExisted = existsSync(
+          join(__dirname, 'electron-webauthn.win32-ia32-msvc.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./electron-webauthn.win32-ia32-msvc.node')
+          } else {
+            nativeBinding = require('electron-webauthn-win32-ia32-msvc')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'arm64':
+        localFileExisted = existsSync(
+          join(__dirname, 'electron-webauthn.win32-arm64-msvc.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./electron-webauthn.win32-arm64-msvc.node')
+          } else {
+            nativeBinding = require('electron-webauthn-win32-arm64-msvc')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on Windows: ${arch}`)
+    }
+    break
+  case 'darwin':
+    localFileExisted = existsSync(join(__dirname, 'electron-webauthn.darwin-universal.node'))
+    try {
+      if (localFileExisted) {
+        nativeBinding = require('./electron-webauthn.darwin-universal.node')
+      } else {
+        nativeBinding = require('electron-webauthn-darwin-universal')
+      }
+      break
+    } catch {}
+    switch (arch) {
+      case 'x64':
+        localFileExisted = existsSync(join(__dirname, 'electron-webauthn.darwin-x64.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./electron-webauthn.darwin-x64.node')
+          } else {
+            nativeBinding = require('electron-webauthn-darwin-x64')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'arm64':
+        localFileExisted = existsSync(
+          join(__dirname, 'electron-webauthn.darwin-arm64.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./electron-webauthn.darwin-arm64.node')
+          } else {
+            nativeBinding = require('electron-webauthn-darwin-arm64')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on macOS: ${arch}`)
+    }
+    break
+  case 'freebsd':
+    if (arch !== 'x64') {
+      throw new Error(`Unsupported architecture on FreeBSD: ${arch}`)
+    }
+    localFileExisted = existsSync(join(__dirname, 'electron-webauthn.freebsd-x64.node'))
+    try {
+      if (localFileExisted) {
+        nativeBinding = require('./electron-webauthn.freebsd-x64.node')
+      } else {
+        nativeBinding = require('electron-webauthn-freebsd-x64')
+      }
+    } catch (e) {
+      loadError = e
+    }
+    break
+  case 'linux':
+    switch (arch) {
+      case 'x64':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'electron-webauthn.linux-x64-musl.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./electron-webauthn.linux-x64-musl.node')
+            } else {
+              nativeBinding = require('electron-webauthn-linux-x64-musl')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'electron-webauthn.linux-x64-gnu.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./electron-webauthn.linux-x64-gnu.node')
+            } else {
+              nativeBinding = require('electron-webauthn-linux-x64-gnu')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 'arm64':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'electron-webauthn.linux-arm64-musl.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./electron-webauthn.linux-arm64-musl.node')
+            } else {
+              nativeBinding = require('electron-webauthn-linux-arm64-musl')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'electron-webauthn.linux-arm64-gnu.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./electron-webauthn.linux-arm64-gnu.node')
+            } else {
+              nativeBinding = require('electron-webauthn-linux-arm64-gnu')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 'arm':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'electron-webauthn.linux-arm-musleabihf.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./electron-webauthn.linux-arm-musleabihf.node')
+            } else {
+              nativeBinding = require('electron-webauthn-linux-arm-musleabihf')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'electron-webauthn.linux-arm-gnueabihf.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./electron-webauthn.linux-arm-gnueabihf.node')
+            } else {
+              nativeBinding = require('electron-webauthn-linux-arm-gnueabihf')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 'riscv64':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'electron-webauthn.linux-riscv64-musl.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./electron-webauthn.linux-riscv64-musl.node')
+            } else {
+              nativeBinding = require('electron-webauthn-linux-riscv64-musl')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'electron-webauthn.linux-riscv64-gnu.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./electron-webauthn.linux-riscv64-gnu.node')
+            } else {
+              nativeBinding = require('electron-webauthn-linux-riscv64-gnu')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 's390x':
+        localFileExisted = existsSync(
+          join(__dirname, 'electron-webauthn.linux-s390x-gnu.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./electron-webauthn.linux-s390x-gnu.node')
+          } else {
+            nativeBinding = require('electron-webauthn-linux-s390x-gnu')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on Linux: ${arch}`)
+    }
+    break
+  default:
+    throw new Error(`Unsupported OS: ${platform}, architecture: ${arch}`)
+}
+
+if (!nativeBinding) {
+  if (loadError) {
+    throw loadError
+  }
+  throw new Error(`Failed to load native binding`)
+}
+
+const { create, get } = nativeBinding
+
+module.exports.create = create
+module.exports.get = get

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "electron-webauthn",
+  "version": "0.0.1",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "napi": {
+    "name": "electron-webauthn",
+    "triples": {
+      "additional": [
+        "aarch64-apple-darwin",
+        "aarch64-pc-windows-msvc"
+      ]
+    }
+  },
+  "license": "MIT",
+  "files": [
+    "dist",
+    "index.d.ts",
+    "index.js"
+  ],
+  "devDependencies": {
+    "@napi-rs/cli": "^2.18.4",
+    "ava": "^6.0.1"
+  },
+  "ava": {
+    "timeout": "3m"
+  },
+  "engines": {
+    "node": ">= 10"
+  },
+  "scripts": {
+    "artifacts": "napi artifacts",
+    "build": "napi build --platform --release",
+    "build:debug": "napi build --platform",
+    "prepublishOnly": "napi prepublish -t npm",
+    "test": "ava",
+    "universal": "napi universal",
+    "version": "napi version"
+  },
+  "packageManager": "yarn@4.9.2",
+  "repository": "https://github.com/iamEvanYT/electron-webauthn-native",
+  "description": "Add support for WebAuthn for Electron.",
+  "optionalDependencies": {
+    "electron-webauthn-win32-x64-msvc": "0.0.1",
+    "electron-webauthn-darwin-x64": "0.0.1",
+    "electron-webauthn-linux-x64-gnu": "0.0.1",
+    "electron-webauthn-darwin-arm64": "0.0.1",
+    "electron-webauthn-win32-arm64-msvc": "0.0.1"
+  }
+}