nid-webauthn-emulator 0.2.8 → 0.2.9

package/README.ja.md

@@ -201,13 +201,32 @@ test.describe("Passkeys Tests", { tag: ["@daily"] }, () => {
 await page.evaluate(BrowserInjection.HookWebAuthnApis);
 ```
 
-`BrowserInjection.HookWebAuthnApis` は JavaScript 関数のシリアライズされた文字列であり、評価すると下記のような処理を行います。
+## ユニットテストでの WebAuthn API フック
 
-- `navigator.credentials.get` の定義を上書きし、`window.webAuthnEmulatorGet` を呼び出す
-- `navigator.credentials.create` の定義を上書きし、`window.webAuthnEmulatorCreate` を呼び出す
-- `PublicKeyCredential.signalUnknownCredential` の定義を追加し、`window.webAuthnEmulatorSignalUnknownCredential` を呼び出す
+Vitest/Jest などで WebAuthn API を差し替えたい場合は、`src/test-utils/unit-test.ts` の `createPasskeysEmulator` を使うと `PublicKeyCredential` / `navigator.credentials` を簡単にモックできます。
 
-これにより先ほどの `exposeFunction` で定義した `WebAuthnEmulator` のメソッドが、`navigator.credentials.get` および `navigator.credentials.create` 呼び出し時に実行されるようになります。これらの処理中にはテストコンテキストと Playwright のコンテキスト間の通信のためにデータのシリアライズおよびデシリアライズが行われるため、そのための処理も含まれています。
+```TypeScript
+import { createPasskeysEmulator } from "nid-webauthn-emulator";
+
+const { interface: methods, addPasskey } = createPasskeysEmulator({
+  origin: "http://localhost",
+  rpId: "localhost",
+  autofill: true, // false にすると isConditionalMediationAvailable が false を返す
+  // creationException / requestException を指定すると DOMException が発生する挙動を注入できます
+});
+
+params?.existingPasskeys?.forEach((passkey) => {
+  addPasskey(passkey); // テスト開始前に登録済みパスキーを追加
+});
+
+// 既存の実装を消し、エミュレータを差し込む
+const undefinedProperty = { value: undefined, configurable: true };
+Object.defineProperty(window, "PublicKeyCredential", undefinedProperty);
+Object.defineProperty(window.navigator, "credentials", undefinedProperty);
+
+vi.spyOn(window, "PublicKeyCredential", "get").mockReturnValue(methods.publicKeyCredentials);
+vi.spyOn(window.navigator, "credentials", "get").mockReturnValue(methods.credentialsContainer);
+```
 
 ## ライセンス
 

package/README.md

@@ -210,8 +210,35 @@ await page.evaluate(BrowserInjection.HookWebAuthnApis);
 
 This ensures that the `WebAuthnEmulator` methods defined earlier with `exposeFunction` are executed when `navigator.credentials.get` and `navigator.credentials.create` are called. These processes include serialization and deserialization of data for communication between the test context and Playwright context.
 
+## Hooking WebAuthn APIs in Unit Tests
+
+If you want to swap out WebAuthn APIs in Vitest/Jest, you can mock `PublicKeyCredential` / `navigator.credentials` using `createPasskeysEmulator` from `src/test-utils/unit-test.ts`.
+
+```TypeScript
+import { createPasskeysEmulator } from "nid-webauthn-emulator";
+
+const { interface: methods, addPasskey } = createPasskeysEmulator({
+  origin: "http://localhost",
+  rpId: "localhost",
+  autofill: true, // returns false from isConditionalMediationAvailable when set to false
+  // specify creationException / requestException to inject a DOMException
+});
+
+params?.existingPasskeys?.forEach((passkey) => {
+  addPasskey(passkey); // add pre-registered passkeys before the test starts
+});
+
+// remove existing implementations and inject the emulator
+const undefinedProperty = { value: undefined, configurable: true };
+Object.defineProperty(window, "PublicKeyCredential", undefinedProperty);
+Object.defineProperty(window.navigator, "credentials", undefinedProperty);
+
+vi.spyOn(window, "PublicKeyCredential", "get").mockReturnValue(methods.publicKeyCredentials);
+vi.spyOn(window.navigator, "credentials", "get").mockReturnValue(methods.credentialsContainer);
+```
+
 ## License
 
 MIT License
 
-Copyright (C) 2024 Nikkei Inc.
+Copyright (C) 2024 Nikkei Inc.

package/dist/spec/test-utils/unit-test.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/spec/test-utils/unit-test.spec.js

@@ -0,0 +1,116 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const globals_1 = require("@jest/globals");
+const authenticator_emulator_1 = require("../../src/authenticator/authenticator-emulator");
+const encode_utils_1 = __importDefault(require("../../src/libs/encode-utils"));
+const unit_test_1 = require("../../src/test-utils/unit-test");
+const webauthn_model_json_1 = require("../../src/webauthn/webauthn-model-json");
+const globalScope = globalThis;
+const originalLocation = globalScope.location;
+const originalBtoa = globalScope.btoa;
+const originalAtob = globalScope.atob;
+(0, globals_1.beforeAll)(() => {
+    if (!globalScope.btoa) {
+        globalScope.btoa = (data) => Buffer.from(data, "binary").toString("base64");
+    }
+    if (!globalScope.atob) {
+        globalScope.atob = (base64) => Buffer.from(base64, "base64").toString("binary");
+    }
+});
+const clearDefaultRepository = () => {
+    const repository = new authenticator_emulator_1.AuthenticatorEmulator().params.credentialsRepository;
+    repository?.loadCredentials().forEach((credential) => {
+        repository.deleteCredential(credential);
+    });
+};
+(0, globals_1.beforeEach)(() => {
+    clearDefaultRepository();
+});
+(0, globals_1.afterEach)(() => {
+    globalScope.location = originalLocation;
+    clearDefaultRepository();
+});
+(0, globals_1.afterAll)(() => {
+    globalScope.location = originalLocation;
+    globalScope.btoa = originalBtoa;
+    globalScope.atob = originalAtob;
+});
+(0, globals_1.describe)("createPasskeysEmulator", () => {
+    (0, globals_1.test)("exposes default passkeys-like interfaces", async () => {
+        const emulator = (0, unit_test_1.createPasskeysEmulator)();
+        (0, globals_1.expect)(await emulator.methods.publicKeyCredentials.isConditionalMediationAvailable?.()).toBe(true);
+        (0, globals_1.expect)(await emulator.methods.publicKeyCredentials.getClientCapabilities()).toEqual({ conditionalGet: true });
+        (0, globals_1.expect)(await emulator.methods.publicKeyCredentials.isUserVerifyingPlatformAuthenticatorAvailable()).toBe(true);
+        (0, globals_1.expect)(emulator.methods.publicKeyCredentials.parseCreationOptionsFromJSON).toBe(webauthn_model_json_1.parseCreationOptionsFromJSON);
+        (0, globals_1.expect)(emulator.methods.publicKeyCredentials.parseRequestOptionsFromJSON).toBe(webauthn_model_json_1.parseRequestOptionsFromJSON);
+    });
+    (0, globals_1.test)("addPasskey stores credentials for custom rpId and allows authentication", async () => {
+        globalScope.location = { origin: "https://example.com" };
+        const emulator = (0, unit_test_1.createPasskeysEmulator)({ origin: "https://example.com", rpId: "example.com" });
+        emulator.addPasskey("user-123");
+        const repository = emulator.instance.authenticator.params.credentialsRepository;
+        const credentials = repository?.loadCredentials() ?? [];
+        (0, globals_1.expect)(credentials).toHaveLength(1);
+        (0, globals_1.expect)(credentials[0].publicKeyCredentialSource.rpId.value).toBe("example.com");
+        const credentialId = encode_utils_1.default.encodeBase64Url(credentials[0].publicKeyCredentialSource.id);
+        const requestOptions = emulator.methods.publicKeyCredentials.parseRequestOptionsFromJSON({
+            challenge: encode_utils_1.default.encodeBase64Url(Buffer.from("challenge")),
+            rpId: "example.com",
+            allowCredentials: [{ type: "public-key", id: credentialId }],
+        });
+        const assertion = (await emulator.methods.credentialsContainer.get({
+            publicKey: requestOptions,
+        }));
+        (0, globals_1.expect)(assertion.id).toBe(credentialId);
+        const userHandle = assertion.response.userHandle;
+        (0, globals_1.expect)(encode_utils_1.default.encodeBase64Url(new Uint8Array(userHandle ?? new ArrayBuffer(0)))).toBe(encode_utils_1.default.encodeBase64Url(Buffer.from("user-123")));
+    });
+    (0, globals_1.test)("creationException bubbles up as DOMException", async () => {
+        globalScope.location = { origin: "http://localhost" };
+        const emulator = (0, unit_test_1.createPasskeysEmulator)({ creationException: "AbortError" });
+        const creationOptions = emulator.methods.publicKeyCredentials.parseCreationOptionsFromJSON({
+            challenge: encode_utils_1.default.encodeBase64Url(Buffer.from("challenge")),
+            rp: { name: "Test RP", id: "localhost" },
+            user: {
+                id: encode_utils_1.default.encodeBase64Url(Buffer.from("creation-user")),
+                name: "creation-user",
+                displayName: "",
+            },
+            pubKeyCredParams: [{ alg: -7, type: "public-key" }],
+        });
+        const createCall = emulator.methods.credentialsContainer.create({ publicKey: creationOptions });
+        await (0, globals_1.expect)(createCall).rejects.toThrow(DOMException);
+        await (0, globals_1.expect)(createCall).rejects.toMatchObject({ name: "AbortError" });
+    });
+    (0, globals_1.test)("requestException is thrown when fetching assertions", async () => {
+        globalScope.location = { origin: "http://localhost" };
+        const emulator = (0, unit_test_1.createPasskeysEmulator)({ requestException: "InvalidStateError" });
+        emulator.addPasskey("auth-user");
+        const repository = emulator.instance.authenticator.params.credentialsRepository;
+        const credentials = repository?.loadCredentials() ?? [];
+        (0, globals_1.expect)(credentials).toHaveLength(1);
+        const credentialId = encode_utils_1.default.encodeBase64Url(credentials[0].publicKeyCredentialSource.id);
+        const requestOptions = emulator.methods.publicKeyCredentials.parseRequestOptionsFromJSON({
+            challenge: encode_utils_1.default.encodeBase64Url(Buffer.from("request")),
+            rpId: "localhost",
+            allowCredentials: [{ type: "public-key", id: credentialId }],
+        });
+        const parsedId = encode_utils_1.default.encodeBase64Url(new Uint8Array(requestOptions.allowCredentials?.[0].id ?? new ArrayBuffer(0)));
+        (0, globals_1.expect)(parsedId).toBe(credentialId);
+        try {
+            await emulator.methods.credentialsContainer.get({ publicKey: requestOptions });
+            throw new Error("Expected DOMException");
+        }
+        catch (error) {
+            (0, globals_1.expect)(error).toBeInstanceOf(DOMException);
+            (0, globals_1.expect)(error.name).toBe("InvalidStateError");
+        }
+    });
+    (0, globals_1.test)("disables conditional mediation when autofill flag is false", async () => {
+        const emulator = (0, unit_test_1.createPasskeysEmulator)({ autofill: false });
+        await (0, globals_1.expect)(emulator.methods.publicKeyCredentials.isConditionalMediationAvailable?.()).resolves.toBe(false);
+    });
+});

package/dist/src/index.d.ts

@@ -5,6 +5,7 @@ export * from "./authenticator/ctap-model";
 export * from "./repository/credentials-file-repository";
 export * from "./repository/credentials-memory-repository";
 export * from "./repository/credentials-repository";
+export * from "./test-utils/unit-test";
 export * from "./webauthn/cose-key";
 export * from "./webauthn/webauthn-emulator";
 export * from "./webauthn/webauthn-model";

package/dist/src/index.js

@@ -23,6 +23,7 @@ __exportStar(require("./authenticator/ctap-model"), exports);
 __exportStar(require("./repository/credentials-file-repository"), exports);
 __exportStar(require("./repository/credentials-memory-repository"), exports);
 __exportStar(require("./repository/credentials-repository"), exports);
+__exportStar(require("./test-utils/unit-test"), exports);
 __exportStar(require("./webauthn/cose-key"), exports);
 __exportStar(require("./webauthn/webauthn-emulator"), exports);
 __exportStar(require("./webauthn/webauthn-model"), exports);

package/dist/src/libs/encode-utils.js

@@ -46,7 +46,7 @@ function encodeCbor(data) {
         if (typeof value === "object" && value !== null) {
             const encodedData = new Map();
             for (const [k, v] of Object.entries(value)) {
-                const ki = Number.parseInt(k);
+                const ki = Number.parseInt(k, 10);
                 if (Number.isNaN(ki)) {
                     encodedData.set(k, encoder(v));
                 }

package/dist/src/test-utils/unit-test.d.ts

@@ -0,0 +1,31 @@
+import { WebAuthnEmulator } from "../webauthn/webauthn-emulator";
+import { type AllAcceptedCredentialsOptionsJSON, type CurrentUserDetailsOptionsJSON, type UnknownCredentialOptionsJSON } from "../webauthn/webauthn-model-json";
+type PasskeysEmulatorParams = {
+    origin?: string;
+    autofill?: boolean;
+    creationException?: string;
+    requestException?: string;
+    rpId?: string;
+};
+export declare const createPasskeysEmulator: (params?: PasskeysEmulatorParams) => {
+    instance: WebAuthnEmulator;
+    addPasskey: (userId: string) => import("../webauthn/webauthn-model-json").RegistrationResponseJSON;
+    methods: {
+        credentialsContainer: CredentialsContainer;
+        publicKeyCredentials: {
+            new (): PublicKeyCredential;
+            prototype: PublicKeyCredential;
+            getClientCapabilities(): Promise<PublicKeyCredentialClientCapabilities>;
+            isConditionalMediationAvailable(): Promise<boolean>;
+            isUserVerifyingPlatformAuthenticatorAvailable(): Promise<boolean>;
+            parseCreationOptionsFromJSON(options: PublicKeyCredentialCreationOptionsJSON): PublicKeyCredentialCreationOptions;
+            parseRequestOptionsFromJSON(options: PublicKeyCredentialRequestOptionsJSON): PublicKeyCredentialRequestOptions;
+        } & {
+            signalUnknownCredential(options: UnknownCredentialOptionsJSON): Promise<void>;
+            signalAllAcceptedCredentials(options: AllAcceptedCredentialsOptionsJSON): Promise<void>;
+            signalCurrentUserDetails(options: CurrentUserDetailsOptionsJSON): Promise<void>;
+            isConditionalMediationAvailable?(): Promise<boolean>;
+        };
+    };
+};
+export {};

package/dist/src/test-utils/unit-test.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createPasskeysEmulator = void 0;
+const authenticator_emulator_1 = require("../authenticator/authenticator-emulator");
+const webauthn_emulator_1 = require("../webauthn/webauthn-emulator");
+const webauthn_model_json_1 = require("../webauthn/webauthn-model-json");
+const createInteraction = (exception) => exception
+    ? () => {
+        throw new DOMException("test", exception);
+    }
+    : undefined;
+const addTestPasskey = (emulator, origin, userId, rpId = "localhost") => {
+    const creationOption = {
+        challenge: "EA3d-yrkJAfNWICZ7It5ErO0XngxTe32L0t8IjEj9r8",
+        rp: { name: "Test RP", id: rpId },
+        user: {
+            id: (0, webauthn_model_json_1.encodeBase64Url)(Buffer.from(userId)),
+            name: "test",
+            displayName: "",
+        },
+        pubKeyCredParams: [
+            { alg: -8, type: "public-key" },
+            { alg: -7, type: "public-key" },
+            { alg: -257, type: "public-key" },
+        ],
+    };
+    return emulator.createJSON(origin, creationOption);
+};
+const createPasskeysEmulator = (params) => {
+    const authenticator = new authenticator_emulator_1.AuthenticatorEmulator({
+        userMakeCredentialInteraction: createInteraction(params?.creationException),
+        userGetAssertionInteraction: createInteraction(params?.requestException),
+    });
+    const instance = new webauthn_emulator_1.WebAuthnEmulator(authenticator);
+    const origin = params?.origin ?? "http://localhost";
+    const publicKeyCredentials = {
+        isConditionalMediationAvailable: async () => Promise.resolve(params?.autofill ?? true),
+        signalUnknownCredential: async (options) => instance.signalUnknownCredential(options),
+        signalAllAcceptedCredentials: async (options) => instance.signalAllAcceptedCredentials(options),
+        signalCurrentUserDetails: async (options) => instance.signalCurrentUserDetails(options),
+        getClientCapabilities: async () => ({ conditionalGet: true }),
+        isUserVerifyingPlatformAuthenticatorAvailable: async () => true,
+        parseCreationOptionsFromJSON: webauthn_model_json_1.parseCreationOptionsFromJSON,
+        parseRequestOptionsFromJSON: webauthn_model_json_1.parseRequestOptionsFromJSON,
+    };
+    const credentialsContainer = {
+        get: async (options) => instance.get(origin, options ?? {}),
+        create: async (options) => instance.create(origin, options ?? {}),
+    };
+    const addPasskey = (userId) => addTestPasskey(instance, origin, userId, params?.rpId);
+    return {
+        instance,
+        addPasskey,
+        methods: {
+            credentialsContainer,
+            publicKeyCredentials,
+        },
+    };
+};
+exports.createPasskeysEmulator = createPasskeysEmulator;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nid-webauthn-emulator",
-  "version": "0.2.8",
+  "version": "0.2.9",
   "keywords": [
     "test",
     "e2e",
@@ -15,11 +15,11 @@
   "main": "dist/src/index.js",
   "types": "dist/src/index.d.ts",
   "devDependencies": {
-    "@biomejs/biome": "^2.2.6",
+    "@biomejs/biome": "^2.3.8",
     "@jest/globals": "^30.2.0",
-    "@simplewebauthn/server": "^13.2.1",
-    "@tsconfig/recommended": "^1.0.10",
-    "@types/node": "^24.7.2",
+    "@simplewebauthn/server": "^13.2.2",
+    "@tsconfig/recommended": "^1.0.13",
+    "@types/node": "^24.10.1",
     "jest": "^30.2.0",
     "ts-jest": "^29.4.5",
     "ts-node": "^10.9.2",
@@ -27,7 +27,7 @@
   },
   "dependencies": {
     "cbor": "^10.0.11",
-    "tldts": "^7.0.17"
+    "tldts": "^7.0.19"
   },
   "scripts": {
     "check": "biome check .",