@flun/webauthn-browser 2.0.2

package/helpers/index.d.ts

@@ -0,0 +1,203 @@
+import { base64URLStringToBuffer, bufferToBase64URLString } from './base64urlAndBuffer.js';
+import { _browserSupportsWebAuthnInternals, browserSupportsWebAuthn } from './browserSupportsWebAuthn.js';
+import { _browserSupportsWebAuthnAutofillInternals, browserSupportsWebAuthnAutofill } from './browserSupportsWebAuthnAutofill.js';
+import { identifyAuthenticationError } from './identifyAuthenticationError.js';
+import { identifyRegistrationError } from './identifyRegistrationError.js';
+import { isValidDomain } from './isValidDomain.js';
+import { platformAuthenticatorIsAvailable } from './platformAuthenticatorIsAvailable.js';
+import { toAuthenticatorAttachment } from './toAuthenticatorAttachment.js';
+import { toPublicKeyCredentialDescriptor } from './toPublicKeyCredentialDescriptor.js';
+import { WebAuthnAbortService } from './WebAuthnAbortService.js';
+import { WebAuthnError } from './webAuthnError.js';
+
+// ================================ base64urlAndBuffer.js ================================
+/**
+ * ```js
+ * // 文件导出内容
+ * base64URLStringToBuffer(); // 将 Base64URL 编码的字符串转换为 Array Buffer;
+ * bufferToBase64URLString(); // 将给定的数组缓冲区转换为 Base64URL 编码的字符串;
+ * ```
+ * >查看定义:@see {@link base64URLStringToBuffer}、{@link bufferToBase64URLString}
+ */
+declare module './base64urlAndBuffer.js' {
+    export * from './base64urlAndBuffer.js';
+}
+
+// ================================ browserSupportsWebAuthn.js ================================
+/**
+ * ```js
+ * // 文件导出内容
+ * const _browserSupportsWebAuthnInternals={}; // 测试期间对返回值进行桩（stub）处理
+ * browserSupportsWebAuthn();                  // 判断当前浏览器是否支持 WebAuthn
+ * ```
+ * >查看定义:@see {@link _browserSupportsWebAuthnInternals}、{@link browserSupportsWebAuthn}
+ */
+declare module './browserSupportsWebAuthn.js' {
+    export * from './browserSupportsWebAuthn.js';
+}
+
+// ================================ browserSupportsWebAuthnAutofill.js ================================
+/**
+ * ```js
+ * // 文件导出内容
+ * const _browserSupportsWebAuthnAutofillInternals={}; // 测试期间模拟返回值;
+ * browserSupportsWebAuthnAutofill();                  // 判断浏览器是否支持条件式UI;
+ * ```
+ * >查看定义:@see {@link  _browserSupportsWebAuthnAutofillInternals}、{@link browserSupportsWebAuthnAutofill}
+ */
+declare module './browserSupportsWebAuthnAutofill.js' {
+    export * from './browserSupportsWebAuthnAutofill.js';
+}
+
+// ================================ identifyAuthenticationError.js ================================
+/**
+ * ```js
+ * // 文件导出内容
+ * identifyAuthenticationError(); // 尝试推断调用 `navigator.credentials.get()` 后引发错误的原因;
+ * ```
+ * >查看定义:@see {@link identifyAuthenticationError}
+ */
+declare module './identifyAuthenticationError.js' {
+    export * from './identifyAuthenticationError.js';
+}
+
+// ================================ identifyRegistrationError.js ================================
+/**
+ * ```js
+ * // 文件导出内容
+ * identifyRegistrationError(); // 尝试推断调用 `navigator.credentials.create()` 后引发错误的原因;
+ * ```
+ * >查看定义:@see {@link identifyRegistrationError}
+ */
+declare module './identifyRegistrationError.js' {
+    export * from './identifyRegistrationError.js';
+}
+
+// ================================ isValidDomain.js ================================
+/**
+ * ```js
+ * // 文件导出内容
+ * isValidDomain(); // 判断主机名是否符合验证规范;
+ * ```
+ * >查看定义:@see {@link isValidDomain}
+ */
+declare module './isValidDomain.js' {
+    export * from './isValidDomain.js';
+}
+
+// ================================ platformAuthenticatorIsAvailable.js ================================
+/**
+ * ```js
+ * // 文件导出内容
+ * platformAuthenticatorIsAvailable(); // 判断浏览器是否能够与内置身份验证器通信;
+ * ```
+ * >查看定义:@see {@link platformAuthenticatorIsAvailable}
+ */
+declare module './platformAuthenticatorIsAvailable.js' {
+    export * from './platformAuthenticatorIsAvailable.js';
+}
+
+// ================================ toAuthenticatorAttachment.js ================================
+/**
+ * ```js
+ * // 文件导出内容
+ * toAuthenticatorAttachment(); // 尝试将 `string` 值强制转换为已知的 `AuthenticatorAttachment` 类型
+ * ```
+ * >查看定义:@see {@link toAuthenticatorAttachment}
+ */
+declare module './toAuthenticatorAttachment.js' {
+    export * from './toAuthenticatorAttachment.js';
+}
+
+// ================================ toPublicKeyCredentialDescriptor.js ================================
+/**
+ * ```js
+ * // 文件导出内容
+ * toPublicKeyCredentialDescriptor(); // 将描述符中的 Base64URL 字符串 `id` 转换为 ArrayBuffer,以适配 WebAuthn API;
+ * ```
+ * >查看定义:@see {@link toPublicKeyCredentialDescriptor}
+ */
+declare module './toPublicKeyCredentialDescriptor.js' {
+    export * from './toPublicKeyCredentialDescriptor.js';
+}
+
+// ================================ webAuthnAbortService.js ================================
+/**
+ * ```js
+ * // 文件导出内容
+ * const WebAuthnAbortService = new BaseWebAuthnAbortService(); // 服务单例,用于确保同一时间只有一个 WebAuthn 仪式处于活动状态;
+ * ```
+ * >查看定义:@see {@link WebAuthnAbortService}
+ */
+declare module './webAuthnAbortService.js' {
+    export * from './webAuthnAbortService.js';
+}
+
+// ================================ webAuthnError.js ================================
+/**
+ * ```js
+ * // 文件导出内容
+ * class WebAuthnError{}; // 自定义错误,用于更细致地说明规范中八种错误被抛出的原因;
+ * ```
+ * >查看定义:@see {@link WebAuthnError}
+ */
+declare module './webAuthnError.js' {
+    export type WebAuthnErrorCode =
+        | 'ERROR_CEREMONY_ABORTED' | 'ERROR_INVALID_DOMAIN' | 'ERROR_INVALID_RP_ID' | 'ERROR_INVALID_USER_ID_LENGTH'
+        | 'ERROR_MALFORMED_PUBKEYCREDPARAMS' | 'ERROR_AUTHENTICATOR_GENERAL_ERROR'
+        | 'ERROR_AUTHENTICATOR_MISSING_DISCOVERABLE_CREDENTIAL_SUPPORT'
+        | 'ERROR_AUTHENTICATOR_MISSING_USER_VERIFICATION_SUPPORT'
+        | 'ERROR_AUTHENTICATOR_PREVIOUSLY_REGISTERED' | 'ERROR_AUTHENTICATOR_NO_SUPPORTED_PUBKEYCREDPARAMS_ALG'
+        | 'ERROR_AUTO_REGISTER_USER_VERIFICATION_FAILURE' | 'ERROR_PASSTHROUGH_SEE_CAUSE_PROPERTY';
+    export * from './webAuthnError.js';
+}
+
+// ================================ 导出入口 ================================
+/**
+ * 模块导出内容：
+ * ```js
+ * // 类型
+ * type WebAuthnErrorCode;
+ *
+ * // 常量
+ * const _browserSupportsWebAuthnInternals={};         // 测试期间对返回值进行桩（stub）处理
+ * const _browserSupportsWebAuthnAutofillInternals={}; // 测试期间模拟返回值;
+ * const WebAuthnAbortService = new BaseWebAuthnAbortService(); // 服务单例,用于确保同一时间只有一个 WebAuthn 仪式处于活动状态;
+ *
+ * // 函数
+ * base64URLStringToBuffer();                          // 将 Base64URL 编码的字符串转换为 Array Buffer;
+ * bufferToBase64URLString();                          // 将给定的数组缓冲区转换为 Base64URL 编码的字符串;
+ * browserSupportsWebAuthn();                          // 判断当前浏览器是否支持 WebAuthn
+ * browserSupportsWebAuthnAutofill();                  // 判断浏览器是否支持条件式UI;
+ * identifyAuthenticationError();                      // 尝试推断调用 `navigator.credentials.get()` 后引发错误的原因;
+ * identifyRegistrationError();                        // 尝试推断调用 `navigator.credentials.create()` 后引发错误的原因;
+ * isValidDomain();                                    // 判断主机名是否符合验证规范;
+ * platformAuthenticatorIsAvailable();                 // 判断浏览器是否能够与内置身份验证器通信;
+ * toAuthenticatorAttachment();                        // 尝试将 `string` 值强制转换为已知的 `AuthenticatorAttachment` 类型
+ * toPublicKeyCredentialDescriptor();                  // 将描述符中的Base64URL字符串`id`转换为ArrayBuffer,以适配 WebAuthn API;
+ *
+ * // 类
+ * class WebAuthnError{};                              // 自定义错误,用于更细致地说明规范中八种错误被抛出的原因;
+ * ```
+ * >查看定义:@see
+ * - 类型 {@link WebAuthnErrorCode}
+ * - 常量 {@link _browserSupportsWebAuthnInternals}、{@link _browserSupportsWebAuthnAutofillInternals}、{@link WebAuthnAbortService}
+ * - 函数 {@link base64URLStringToBuffer}、{@link bufferToBase64URLString}、 {@link browserSupportsWebAuthn}、
+ * {@link browserSupportsWebAuthnAutofill}、{@link identifyAuthenticationError}、{@link identifyRegistrationError}、
+ * {@link isValidDomain}、{@link platformAuthenticatorIsAvailable}、{@link toAuthenticatorAttachment}、
+ * {@link toPublicKeyCredentialDescriptor}
+ * - 类 {@link WebAuthnError}
+ */
+declare module './index.js' {
+    export * from './base64urlAndBuffer.js';
+    export * from './browserSupportsWebAuthn.js';
+    export * from './browserSupportsWebAuthnAutofill.js';
+    export * from './identifyAuthenticationError.js';
+    export * from './identifyRegistrationError.js';
+    export * from './isValidDomain.js';
+    export * from './platformAuthenticatorIsAvailable.js';
+    export * from './toAuthenticatorAttachment.js';
+    export * from './toPublicKeyCredentialDescriptor.js';
+    export * from './webAuthnAbortService.js';
+    export * from './webAuthnError.js';
+}

package/helpers/index.js

@@ -0,0 +1,11 @@
+export * from './base64urlAndBuffer.js';
+export * from './browserSupportsWebAuthn.js';
+export * from './browserSupportsWebAuthnAutofill.js';
+export * from './identifyAuthenticationError.js';
+export * from './identifyRegistrationError.js';
+export * from './isValidDomain.js';
+export * from './platformAuthenticatorIsAvailable.js';
+export * from './toAuthenticatorAttachment.js';
+export * from './toPublicKeyCredentialDescriptor.js';
+export * from './WebAuthnAbortService.js';
+export * from './WebAuthnError.js';

package/helpers/isValidDomain.js

@@ -0,0 +1,18 @@
+/**
+ * 一个简单的测试,用于判断主机名是否为格式正确的域名
+ * - 查看定义:@see {@link isValidDomain}
+ * - “有效域名”的定义参见：https://url.spec.whatwg.org/#valid-domain
+ *
+ * - 正则表达式最初来源于此处,后经改编以增加 punycode 支持：
+ * https://www.oreilly.com/library/view/regular-expressions-cookbook/9781449327453/ch08s15.html
+ *
+ * @param {string} hostname - 待验证的主机名
+ * @returns {boolean} 如果主机名是 localhost 或符合有效域名格式则返回 true，否则 false
+ */
+const isValidDomain = hostname => {
+    return (
+        // 将 localhost 视为有效,因为它在安全上下文方面是没问题的,支持 punycode (ACE) 或 ASCII 标签和域名
+        hostname === 'localhost' || /^((xn--[a-z0-9-]+|[a-z0-9]+(-[a-z0-9]+)*)\.)+([a-z]{2,}|xn--[a-z0-9-]+)$/i.test(hostname));
+}
+
+export { isValidDomain };

package/helpers/platformAuthenticatorIsAvailable.js

@@ -0,0 +1,14 @@
+import { browserSupportsWebAuthn } from './browserSupportsWebAuthn.js';
+
+/**
+ * 判断浏览器是否能够与内置身份验证器（如 Touch ID、Android 指纹扫描器或 Windows Hello）通信;
+ * 该方法无法告知平台身份验证器的具体名称;
+ * - 查看定义:@see {@link platformAuthenticatorIsAvailable}
+ * @returns {Promise<boolean>} 如果平台身份验证器可用,则解析为 true,否则为 false;
+ */
+const platformAuthenticatorIsAvailable = () => {
+    if (!browserSupportsWebAuthn()) return new Promise(resolve => resolve(false));
+    return PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable();
+}
+
+export { platformAuthenticatorIsAvailable };

package/helpers/toAuthenticatorAttachment.js

@@ -0,0 +1,15 @@
+const attachments = ['cross-platform', 'platform'];
+
+/**
+ * 尝试将 `string` 值强制转换为已知的 `AuthenticatorAttachment` 类型
+ * - 查看定义:@see {@link toAuthenticatorAttachment}
+ * @param {string} attachment - 待转换的字符串
+ * @returns {'cross-platform' | 'platform' | undefined} 如果是合法的认证器附着类型则返回对应字符串,否则返回 undefined;
+ */
+const toAuthenticatorAttachment = attachment => {
+    if (!attachment) return;
+    if (attachments.indexOf(attachment) < 0) return;
+    return attachment;
+}
+
+export { toAuthenticatorAttachment };

package/helpers/toPublicKeyCredentialDescriptor.js

@@ -0,0 +1,23 @@
+import { base64URLStringToBuffer } from './base64urlAndBuffer.js';
+
+/**
+ * 将描述符中的 Base64URL 字符串 `id` 转换为 ArrayBuffer,以适配 WebAuthn API;
+ * - 查看定义:@see {@link toPublicKeyCredentialDescriptor}
+ * @param {Object} descriptor - 包含 `id` (Base64URL 字符串) 的凭证描述符;
+ * @param {string} descriptor.id - 凭证 ID（Base64URL 编码）
+ * @param {string[]} [descriptor.transports] - 可选的传输方式列表（如 ['usb', 'nfc']）
+ * @returns {PublicKeyCredentialDescriptor} 转换后的描述符,可直接用于 WebAuthn;
+ */
+const toPublicKeyCredentialDescriptor = descriptor => {
+    const { id } = descriptor;
+    return {
+        ...descriptor, id: base64URLStringToBuffer(id),
+        /**
+         * `descriptor.transports` 是一个包含较新传输方式的数组,这些传输方式属于我们的 `AuthenticatorTransportFuture` 类型,
+         * 而 TypeScript 的 DOM 库对此尚不了解;让 TS 相信我们的传输方式列表可以传递给 WebAuthn,因为浏览器会识别这些新值;
+         */
+        transports: descriptor.transports,
+    };
+}
+
+export { toPublicKeyCredentialDescriptor };

package/helpers/webAuthnAbortService.js

@@ -0,0 +1,51 @@
+/**
+ * WebAuthn 中止服务的基础类
+ */
+class BaseWebAuthnAbortService {
+    constructor() {
+        /**
+         * 当前活动的 AbortController 实例
+         * @type {AbortController | undefined}
+         */
+        this.controller = undefined;
+    }
+
+    /**
+     * 创建新的 AbortSignal,并中止任何进行中的 WebAuthn 仪式
+     *
+     * @returns {AbortSignal} 可用于 `navigator.credentials.create()` 或 `navigator.credentials.get()` 的 `signal` 选项
+     */
+    createNewAbortSignal() {
+        // 中止任何现有的 navigator.credentials.create() 或 navigator.credentials.get() 调用
+        if (this.controller) {
+            const abortError = new Error('取消当前 WebAuthn API 调用,使用新的调用');
+            abortError.name = 'AbortError', this.controller.abort(abortError);
+        }
+        const newController = new AbortController();
+        this.controller = newController;
+        return newController.signal;
+    }
+
+    /**
+     * 手动取消当前正在进行的 WebAuthn 仪式
+     * @returns {void}
+     */
+    cancelCeremony() {
+        if (this.controller) {
+            const abortError = new Error('手动取消现有的 WebAuthn API 调用');
+            abortError.name = 'AbortError', this.controller.abort(abortError), this.controller = undefined;
+        }
+    }
+}
+
+/**
+ * 服务单例,用于确保同一时间只有一个 WebAuthn 仪式处于活动状态;
+ * **@flun/webauthn-browser** 的使用者通常不需要使用此服务,但它可以帮助
+ * 使用客户端路由的项目开发者更好地控制其用户体验以响应路由导航事件;
+ * - 查看定义:@see {@link WebAuthnAbortService}
+ *
+ * @type {BaseWebAuthnAbortService}
+ */
+const WebAuthnAbortService = new BaseWebAuthnAbortService();
+
+export { BaseWebAuthnAbortService, WebAuthnAbortService };

package/helpers/webAuthnError.js

@@ -0,0 +1,30 @@
+/**
+ * 自定义错误,用于在调用 `navigator.credentials.create()` 或 `navigator.credentials.get()` 后,
+ * 更细致地说明规范中描述的八种错误之一被抛出的原因：
+ *
+ * - `AbortError`
+ * - `ConstraintError`
+ * - `InvalidStateError`
+ * - `NotAllowedError`
+ * - `NotSupportedError`
+ * - `SecurityError`
+ * - `TypeError`
+ * - `UnknownError`
+ *
+ * 错误消息通过研究规范确定,以了解在哪些场景下会抛出特定错误;
+ * - 查看定义:@see {@link WebAuthnError}
+ */
+class WebAuthnError extends Error {
+    /**
+     * @param {Object} params - 错误配置参数
+     * @param {string} params.message - 错误消息
+     * @param {string} params.code - 错误码（规范中定义的错误名称之一）
+     * @param {Error} [params.cause] - 导致此错误的原始错误对象
+     * @param {string} [params.name] - 自定义错误名称,默认使用 cause 的 name
+     */
+    constructor({ message, code, cause, name }) {
+        super(message, { cause }), this.name = name ?? cause.name, this.code = code;
+    }
+}
+
+export { WebAuthnError };

package/index.d.ts

@@ -0,0 +1,42 @@
+import {
+    bufferToBase64URLString, base64URLStringToBuffer, _browserSupportsWebAuthnInternals, browserSupportsWebAuthn,
+    _browserSupportsWebAuthnAutofillInternals, browserSupportsWebAuthnAutofill, platformAuthenticatorIsAvailable,
+    WebAuthnAbortService, WebAuthnError
+} from './helpers/index.js';
+import { startAuthentication, startRegistration } from './methods/index.js';
+
+/**
+ * 模块导出内容：
+ * ```js
+ * // 登录和注册处理函数
+ * startAuthentication(); // 通过 WebAuthn 断言开始身份验证器“登录”
+ * startRegistration();   // 通过 WebAuthn 证明开始认证器“注册”
+ *
+ * // 工具
+ * const _browserSupportsWebAuthnInternals={};         // 测试期间对返回值进行桩（stub）处理
+ * const _browserSupportsWebAuthnAutofillInternals={}; // 测试期间模拟返回值;
+ * const WebAuthnAbortService = new BaseWebAuthnAbortService(); // 服务单例,用于确保同一时间只有一个 WebAuthn 仪式处于活动状态;
+ *
+ * base64URLStringToBuffer();                          // 将 Base64URL 编码的字符串转换为 Array Buffer;
+ * bufferToBase64URLString();                          // 将给定的数组缓冲区转换为 Base64URL 编码的字符串;
+ * browserSupportsWebAuthn();                          // 判断当前浏览器是否支持 WebAuthn
+ * browserSupportsWebAuthnAutofill();                  // 判断浏览器是否支持条件式UI;
+ * platformAuthenticatorIsAvailable();                 // 判断浏览器是否能够与内置身份验证器通信;
+ *
+ * class WebAuthnError{};                              // 自定义错误,用于更细致地说明规范中八种错误被抛出的原因;
+ * ```
+ * >查看定义:@see
+ *- 登录和注册处理: {@link startAuthentication}、{@link startRegistration}
+ *- 工具: {@link _browserSupportsWebAuthnInternals}、{@link _browserSupportsWebAuthnAutofillInternals}、{@link WebAuthnAbortService}、
+ * {@link base64URLStringToBuffer}、{@link bufferToBase64URLString}、 {@link browserSupportsWebAuthn}、
+ * {@link browserSupportsWebAuthnAutofill}、{@link platformAuthenticatorIsAvailable}
+ * >{@link WebAuthnError}
+ */
+declare module './index.js' {
+    export {
+        bufferToBase64URLString, base64URLStringToBuffer, _browserSupportsWebAuthnInternals, browserSupportsWebAuthn,
+        _browserSupportsWebAuthnAutofillInternals, browserSupportsWebAuthnAutofill, platformAuthenticatorIsAvailable,
+        WebAuthnAbortService, WebAuthnError
+    } from './helpers/index.js';
+    export * from './methods/index.js';
+}

package/index.js

@@ -0,0 +1,5 @@
+export {
+    bufferToBase64URLString, base64URLStringToBuffer, browserSupportsWebAuthn, browserSupportsWebAuthnAutofill,
+    platformAuthenticatorIsAvailable, WebAuthnAbortService, WebAuthnError
+} from './helpers/index.js';
+export * from './methods/index.js';

package/methods/index.d.ts

@@ -0,0 +1,40 @@
+import { startAuthentication } from './startAuthentication.js';
+import { startRegistration } from './startRegistration.js';
+
+// =================================== startAuthentication.js ===================================
+/**
+ * ```js
+ * // 文件导出内容
+ * startAuthentication(); // 通过 WebAuthn 断言开始身份验证器“登录”
+ * ```
+ * >查看定义:@see {@link startAuthentication}
+ */
+declare module './startAuthentication.js' {
+    export * from './startAuthentication.js';
+}
+
+// =================================== startRegistration.js ===================================
+/**
+ * ```js
+ * // 文件导出内容
+ * startRegistration(); // 通过 WebAuthn 证明开始认证器“注册”
+ * ```
+ * >查看定义:@see {@link startRegistration}
+ */
+declare module './startRegistration.js' {
+    export * from './startRegistration.js';
+}
+
+// ================================ 导出入口 ================================
+/**
+ * 模块导出内容：
+ * ```js
+ * startAuthentication(); // 通过 WebAuthn 断言开始身份验证器“登录”
+ * startRegistration();   // 通过 WebAuthn 证明开始认证器“注册”
+ * ```
+ * >查看定义:@see {@link startAuthentication}、{@link startRegistration}
+ */
+declare module './index.js' {
+    export * from './startAuthentication.js';
+    export * from './startRegistration.js';
+}

package/methods/index.js

@@ -0,0 +1,2 @@
+export * from './startAuthentication.js';
+export * from './startRegistration.js';

package/methods/startAuthentication.js

@@ -0,0 +1,94 @@
+import {
+    bufferToBase64URLString, base64URLStringToBuffer, browserSupportsWebAuthn, browserSupportsWebAuthnAutofill,
+    identifyAuthenticationError, toAuthenticatorAttachment, toPublicKeyCredentialDescriptor, WebAuthnAbortService
+} from '../helpers/index.js';
+
+/**
+ * 通过 WebAuthn 断言开始身份验证器“登录”
+ * - 查看定义:@see {@link startAuthentication}
+ * @param {Object} options - 配置选项
+ * @param {Object} options.optionsJSON - 来自 **@flun/webauthn-server** 的 `generateAuthenticationOptions()` 的输出
+ * @param {boolean} [options.useBrowserAutofill=false] - 初始化条件式 UI,以支持通过浏览器自动填充提示进行登录
+ * @param {boolean} [options.verifyBrowserAutofillInput=true] - 当 `useBrowserAutofill` 为 `true` 时,确保存在合适的 `<input>` 元素
+ * @returns {Promise<{
+ *   id: string,
+ *   rawId: string,
+ *   response: {
+ *     authenticatorData: string,
+ *     clientDataJSON: string,
+ *     signature: string,
+ *     userHandle?: string
+ *   },
+ *   type: string,
+ *   clientExtensionResults: AuthenticationExtensionsClientOutputs,
+ *   authenticatorAttachment: string
+ * }>}
+ */
+const startAuthentication = async options => {
+    // 有意检查旧的调用结构,以警告不正确的 API 调用
+    if (!options.optionsJSON && options.challenge) {
+        console.warn("startAuthentication() 调用方式不正确；它将尝试使用提供的选项继续执行,但应重构此调用以使用预期的调用结构；");
+        options = { optionsJSON: options }; // 将作为位置参数传入的 options 重新赋值给预期变量
+    }
+    if (!browserSupportsWebAuthn()) throw new Error('此浏览器不支持 WebAuthn');
+
+    const { optionsJSON, useBrowserAutofill = false, verifyBrowserAutofillInput = true } = options;
+    // 需要避免传递空数组,以免阻止公钥的检索
+    let allowCredentials;
+    if (optionsJSON.allowCredentials?.length !== 0)
+        allowCredentials = optionsJSON.allowCredentials?.map(toPublicKeyCredentialDescriptor);
+
+    // 在将凭证传递给 navigator 之前，需要将某些值转换为 Uint8Array
+    const publicKey = { ...optionsJSON, challenge: base64URLStringToBuffer(optionsJSON.challenge), allowCredentials }
+        , getOptions = {}; // 为 `.get()` 准备选项
+
+    /**
+     * 设置页面，通过浏览器的输入自动填充机制提示用户选择用于身份验证的凭证；
+     */
+    if (useBrowserAutofill) {
+        if (!(await browserSupportsWebAuthnAutofill())) throw Error('浏览器不支持 WebAuthn 自动填充');
+
+        // 检查是否存在 `autocomplete` 属性中包含 "webauthn" 的 <input>
+        const eligibleInputs = document.querySelectorAll("input[autocomplete$='webauthn']");
+
+        // WebAuthn 自动填充要求至少有一个有效的输入框
+        if (eligibleInputs.length < 1 && verifyBrowserAutofillInput)
+            throw Error('未检测到任何 `autocomplete` 属性中包含 "webauthn"（作为唯一值或最后一个值）的 <input> 元素');
+
+        // 截至 typescript@4.6.3，`CredentialMediationRequirement` 尚不识别 "conditional"
+        getOptions.mediation = 'conditional', publicKey.allowCredentials = []; // 条件式 UI 要求 allowCredentials 为空列表
+    }
+
+    getOptions.publicKey = publicKey; // 最终确定选项
+    getOptions.signal = WebAuthnAbortService.createNewAbortSignal(); // 设置取消此请求的能力,以防用户尝试另一个请求
+
+    // 等待用户完成断言
+    let credential;
+    try {
+        credential = await navigator.credentials.get(getOptions);
+    } catch (err) {
+        throw identifyAuthenticationError({ error: err, options: getOptions });
+    }
+    if (!credential) throw new Error('身份验证未完成');
+
+    const { id, rawId, response, type } = credential;
+    let userHandle = undefined;
+    if (response.userHandle) userHandle = bufferToBase64URLString(response.userHandle);
+
+    // 将值转换为 base64，以便更容易发送回服务器
+    return {
+        id,
+        rawId: bufferToBase64URLString(rawId),
+        response: {
+            authenticatorData: bufferToBase64URLString(response.authenticatorData),
+            clientDataJSON: bufferToBase64URLString(response.clientDataJSON),
+            signature: bufferToBase64URLString(response.signature),
+            userHandle,
+        },
+        type,
+        clientExtensionResults: credential.getClientExtensionResults(),
+        authenticatorAttachment: toAuthenticatorAttachment(credential.authenticatorAttachment),
+    };
+}
+
+export { startAuthentication };