electron-windows-hello 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 huhuanming
+
+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

@@ -1,3 +1,88 @@
-# Temporary Holding Version
+# electron-windows-hello
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Windows Hello verification associated with an Electron `BrowserWindow`.
+Independent Node-API implementation for Windows x64 and ARM64, with no runtime npm dependencies.
+
+```sh
+npm install electron-windows-hello
+```
+
+## API
+
+```ts
+import {
+  Availability,
+  VerificationResult,
+  allowSetForegroundWindow,
+  checkAvailability,
+  requestVerification,
+} from "electron-windows-hello";
+
+const availability = await checkAvailability();
+const result = await requestVerification({
+  windowHandle: mainWindow.getNativeWindowHandle(),
+  message: "OneKey requests verification to unlock your wallet",
+});
+const verified = result === VerificationResult.Verified;
+```
+
+`checkAvailability()` resolves to a value in `Availability`: `Available`, `DeviceNotPresent`, `NotConfiguredForUser`, `DisabledByPolicy`, or `DeviceBusy`.
+It first probes the window-owned `IUserConsentVerifierInterop` interface at runtime, without showing a verification dialog. It returns `DeviceNotPresent` on unsupported operating systems and architectures, without loading a native binary. An unavailable interop interface or Windows API failure rejects the promise; applications should offer their normal password authentication instead.
+
+`requestVerification({ windowHandle, message })` requires a fresh, 8-byte `Buffer` from `BrowserWindow.getNativeWindowHandle()` and a non-empty message. It resolves to a value in `VerificationResult`: `Verified`, `Canceled`, `DeviceBusy`, `DeviceNotPresent`, `NotConfiguredForUser`, `DisabledByPolicy`, or `RetriesExhausted`.
+Only `Verified` authorizes the operation. An overlapping request returns `DeviceBusy` and does not share another request's authorization.
+Invalid or destroyed owner windows and Windows API errors reject the promise. Native errors retain the Windows HRESULT in the error message.
+
+`allowSetForegroundWindow(processId)` grants a specific process permission to set the foreground window, when Windows permits the caller to grant it. It returns whether Windows accepted the grant. Call it from the foreground Electron main process before dispatching verification to a utility process. Zero, wildcard, and non-integer process IDs are rejected.
+
+## Electron utility process and focus
+
+In the main process, restore and activate the actual owner window before dispatching:
+
+```ts
+if (mainWindow.isMinimized()) mainWindow.restore();
+mainWindow.show();
+mainWindow.focus();
+allowSetForegroundWindow(helloProcess.pid);
+helloProcess.postMessage({
+  message: "OneKey requests verification to unlock your wallet",
+  windowHandle: Array.from(mainWindow.getNativeWindowHandle()),
+});
+```
+
+Wait for the owner to be focused before dispatching. If `mainWindow.isFocused()` is false, defer verification until a user-initiated window activation. `show()` and `focus()` alone do not guarantee that Windows grants foreground permission.
+
+In the utility process, reconstruct the handle with `Buffer.from(data.windowHandle)` and call `requestVerification` with that buffer. Always send a result or error back to the caller.
+Do not convert the handle to a JavaScript number or discover the owner by querying an unrelated foreground window.
+
+WinRT is initialized and awaited on a libuv worker, so verification does not block Electron's JavaScript thread. Windows controls foreground policy, title, icon, taskbar presentation, and the authentication method. An owner handle and foreground grant do not guarantee a particular icon or force focus against operating-system policy.
+
+## Support
+
+- Windows x64 and ARM64; both native binaries ship in the same package and are selected using `process.arch`.
+- Node.js 20.17 or later, including Electron runtimes with Node-API 8 support.
+- Windows 10 and 11 use the same window-owned `IUserConsentVerifierInterop::RequestVerificationForWindowAsync` path, selected by runtime interface availability rather than an OS version check. Microsoft's method documentation lists build 22000, while its [CsWinRT implementation](https://github.com/microsoft/CsWinRT/blob/master/src/cswinrt/strings/ComInteropHelpers.cs) and [Electron sample](https://github.com/microsoft/dynwinrt/tree/main/samples/js/windows-hello) indicate Windows 10 support. Windows 11 interaction has been manually verified; Windows 10 interaction testing is still pending, so no minimum Windows 10 build is claimed.
+- There is no silent fallback to an unowned verification dialog. If availability fails, offer the application's normal password authentication. Cancellation, unsuccessful verification, and native errors never cause an automatic retry; a new Hello attempt must be explicitly initiated by the user.
+- No credential storage, account management, key generation, signing, PIN collection, or custom authentication UI.
+
+## Development and release
+
+Install Rust 1.88 or later and the Windows MSVC toolchain, then run:
+
+```sh
+npm ci --ignore-scripts
+npm run build
+npm test
+npm run test:types
+```
+
+Build a specific target with `npm run build -- x86_64-pc-windows-msvc` or `npm run build -- aarch64-pc-windows-msvc`.
+CI builds and tests each architecture on a native Windows runner, then checks and packs the combined npm package. `npm pack` refuses missing binaries or a PE machine type that does not match the advertised architecture. Only the runtime entrypoint, declarations, native binaries, README, license, and package metadata are published.
+
+With Electron installed in the development environment, `npm run test:electron` checks the real HWND and utility-process path without an authentication prompt. `npm run test:electron -- --interactive` opens a visible owner window and requests Windows Hello; verify focus, cancellation, multi-monitor placement, and taskbar presentation in a logged-in desktop session. Headless CI cannot establish those interaction results.
+
+The publish workflow supports npm trusted publishing with provenance after configuring this repository and `.github/workflows/publish.yml` as a trusted publisher in npm. Alternatively, configure an npm publish token as the repository's `NPM_TOKEN` secret. Release tags must match the package version. Initial publication may require an authenticated local npm session.
+
+## References
+
+The API choice was informed by [Microsoft's desktop interoperability documentation](https://learn.microsoft.com/en-us/windows/win32/api/userconsentverifierinterop/nf-userconsentverifierinterop-iuserconsentverifierinterop-requestverificationforwindowasync) and investigation of [passport-desktop](https://github.com/MarkusJx/passport-desktop). This project has its own source, API, tests, and release pipeline; it does not include Passport account or cryptographic APIs.

package/index.cjs

@@ -0,0 +1,112 @@
+"use strict";
+
+const availability = Object.freeze({
+  Available: "available",
+  DeviceNotPresent: "device_not_present",
+  NotConfiguredForUser: "not_configured_for_user",
+  DisabledByPolicy: "disabled_by_policy",
+  DeviceBusy: "device_busy",
+});
+const verificationResult = Object.freeze({
+  Verified: "verified",
+  DeviceNotPresent: "device_not_present",
+  NotConfiguredForUser: "not_configured_for_user",
+  DisabledByPolicy: "disabled_by_policy",
+  DeviceBusy: "device_busy",
+  RetriesExhausted: "retries_exhausted",
+  Canceled: "canceled",
+});
+let nativeBinding;
+let verifying = false;
+
+function errorWithCode(code, message) {
+  return Object.assign(new Error(message), { code });
+}
+
+function supportedPlatform() {
+  return (
+    process.platform === "win32" && ["x64", "arm64"].includes(process.arch)
+  );
+}
+
+function binding() {
+  if (!supportedPlatform()) {
+    throw errorWithCode(
+      "ERR_WINDOWS_HELLO_PLATFORM",
+      "Windows Hello requires Windows x64 or ARM64",
+    );
+  }
+  nativeBinding ??= require(`./electron-windows-hello.win32-${process.arch}-msvc.node`);
+  return nativeBinding;
+}
+
+function mapResult(values, value) {
+  if (!Number.isInteger(value) || value < 0 || value >= values.length) {
+    throw errorWithCode(
+      "ERR_WINDOWS_HELLO_RESULT",
+      "Windows returned an unknown verification result",
+    );
+  }
+  return values[value];
+}
+
+exports.Availability = availability;
+exports.VerificationResult = verificationResult;
+exports.checkAvailability = async function checkAvailability() {
+  if (!supportedPlatform()) return availability.DeviceNotPresent;
+  return mapResult(
+    Object.values(availability),
+    await binding().checkAvailability(),
+  );
+};
+exports.requestVerification = async function requestVerification(options) {
+  if (
+    !options ||
+    !Buffer.isBuffer(options.windowHandle) ||
+    options.windowHandle.length !== 8
+  ) {
+    throw errorWithCode(
+      "ERR_WINDOWS_HELLO_HANDLE",
+      "windowHandle must be the 8-byte Buffer returned by BrowserWindow.getNativeWindowHandle()",
+    );
+  }
+  if (
+    typeof options.message !== "string" ||
+    options.message.trim().length === 0
+  ) {
+    throw errorWithCode(
+      "ERR_WINDOWS_HELLO_MESSAGE",
+      "A non-empty verification message is required",
+    );
+  }
+  if (verifying) return verificationResult.DeviceBusy;
+  const native = binding();
+  verifying = true;
+  try {
+    return mapResult(
+      Object.values(verificationResult),
+      await native.requestVerification(
+        Buffer.from(options.windowHandle),
+        options.message,
+      ),
+    );
+  } finally {
+    verifying = false;
+  }
+};
+exports.allowSetForegroundWindow = function allowSetForegroundWindow(
+  processId,
+) {
+  if (
+    !Number.isInteger(processId) ||
+    processId <= 0 ||
+    processId >= 0xffffffff
+  ) {
+    throw errorWithCode(
+      "ERR_WINDOWS_HELLO_PROCESS",
+      "A specific positive process ID is required",
+    );
+  }
+  if (!supportedPlatform()) return false;
+  return binding().allowSetForegroundWindow(processId);
+};

package/index.d.ts

@@ -0,0 +1,31 @@
+export declare const Availability: {
+  readonly Available: "available";
+  readonly DeviceNotPresent: "device_not_present";
+  readonly NotConfiguredForUser: "not_configured_for_user";
+  readonly DisabledByPolicy: "disabled_by_policy";
+  readonly DeviceBusy: "device_busy";
+};
+export type Availability = (typeof Availability)[keyof typeof Availability];
+
+export declare const VerificationResult: {
+  readonly Verified: "verified";
+  readonly DeviceNotPresent: "device_not_present";
+  readonly NotConfiguredForUser: "not_configured_for_user";
+  readonly DisabledByPolicy: "disabled_by_policy";
+  readonly DeviceBusy: "device_busy";
+  readonly RetriesExhausted: "retries_exhausted";
+  readonly Canceled: "canceled";
+};
+export type VerificationResult =
+  (typeof VerificationResult)[keyof typeof VerificationResult];
+
+export interface VerificationOptions {
+  windowHandle: import("node:buffer").Buffer;
+  message: string;
+}
+
+export declare function checkAvailability(): Promise<Availability>;
+export declare function requestVerification(
+  options: VerificationOptions,
+): Promise<VerificationResult>;
+export declare function allowSetForegroundWindow(processId: number): boolean;

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "electron-windows-hello",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Window-owned Windows Hello verification for Electron, with x64 and ARM64 prebuilds",
+  "main": "index.cjs",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "index.cjs",
+    "index.d.ts",
+    "electron-windows-hello.win32-x64-msvc.node",
+    "electron-windows-hello.win32-arm64-msvc.node"
+  ],
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "test": "node --test test/*.test.cjs",
+    "test:electron": "electron test/electron.cjs",
+    "test:types": "tsc --noEmit --strict --skipLibCheck --module node16 --moduleResolution node16 test/types.ts",
+    "prepack": "node scripts/check-package.mjs"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/huhuanming/electron-windows-hello.git"
+  },
+  "bugs": "https://github.com/huhuanming/electron-windows-hello/issues",
+  "homepage": "https://github.com/huhuanming/electron-windows-hello#readme",
+  "keywords": [
+    "electron",
+    "windows-hello",
+    "biometrics",
+    "windows",
+    "arm64"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "node": ">=20.17.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  }
+}