@flun/webauthn-browser 2.0.2

package/dist/index.js

@@ -0,0 +1,270 @@
+/* 基于[@simplewebauthn/browser@13.3.0] 开发 */
+!function (e, t) {
+    "object" == typeof exports && "undefined" != typeof module ? t(exports) : "function" == typeof define && define.amd
+        ? define(["exports"], t) : t((e = "undefined" != typeof globalThis ? globalThis : e || self).flunWebAuthnBrowser = {})
+}(this, e => {
+    "use strict";
+
+    const defaultPropDescriptor = { enumerable: true, configurable: true, writable: true, value: void 0 },
+        falsePromise = Promise.resolve(false),
+        // 将 ArrayBuffer 转换为 Base64URL 字符串
+        bufferToBase64URLString = (e) => {
+            const t = new Uint8Array(e);
+            let r = "";
+            for (const e of t) r += String.fromCharCode(e);
+            return btoa(r).replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "")
+        },
+        // 将 Base64URL 字符串转换为 ArrayBuffer
+        base64URLStringToBuffer = (e) => {
+            const t = e.replace(/-/g, "+").replace(/_/g, "/"), r = (4 - t.length % 4) % 4, n = t.padEnd(t.length + r, "="),
+                o = atob(n), i = new ArrayBuffer(o.length), a = new Uint8Array(i);
+            for (let e = 0; e < o.length; e++) a[e] = o.charCodeAt(e);
+            return i
+        },
+        o = { stubThis: e => e },
+        // 检查浏览器是否支持 WebAuthn
+        browserSupportsWebAuthn = () =>
+            o.stubThis(void 0 !== globalThis?.PublicKeyCredential && "function" == typeof globalThis.PublicKeyCredential),
+        // 转换允许凭证中的 ID 字段
+        convertAllowCredential = e => {
+            const { id: t } = e;
+            return { ...e, id: base64URLStringToBuffer(t), transports: e.transports }
+        },
+        // 验证域名有效性
+        isValidDomain = e =>
+            "localhost" === e || /^((xn--[a-z0-9-]+|[a-z0-9]+(-[a-z0-9]+)*)\.)+([a-z]{2,}|xn--[a-z0-9-]+)$/i.test(e),
+
+        // WebAuthn 中止服务（用于取消进行中的认证/注册）
+        WebAuthnAbortService = new class {
+            constructor() {
+                Object.defineProperty(this, "controller", defaultPropDescriptor)
+            }
+            createNewAbortSignal() {
+                if (this.controller) {
+                    const e = new Error("正在取消已有的 WebAuthn API 调用,然后进行新的调用");
+                    e.name = "AbortError", this.controller.abort(e)
+                }
+                const e = new AbortController;
+                return this.controller = e, e.signal
+            }
+            cancelCeremony() {
+                if (this.controller) {
+                    const e = new Error("正在取消 WebAuthn API 调用");
+                    e.name = "AbortError", this.controller.abort(e), this.controller = void 0
+                }
+            }
+        },
+
+        authenticatorAttachmentValues = ["cross-platform", "platform"],
+        normalizeAuthenticatorAttachment = (e) => {
+            if (e && !(authenticatorAttachmentValues.indexOf(e) < 0)) return e
+        },
+        warnExtensionMishandling = (e, t) => {
+            console.warn(`拦截此 WebAuthn API 调用的浏览器扩展错误地实现了 ${e};请向扩展开发者报告此问题;\n`, t)
+        },
+        p = { stubThis: e => e },
+        // 检查浏览器是否支持 WebAuthn 自动填充
+        browserSupportsWebAuthnAutofill = () => {
+            if (!browserSupportsWebAuthn()) return p.stubThis(falsePromise);
+            const e = globalThis.PublicKeyCredential;
+            return void 0 === e?.isConditionalMediationAvailable ? p.stubThis(falsePromise)
+                : p.stubThis(e.isConditionalMediationAvailable())
+        };
+
+    // 自定义 WebAuthn 错误类
+    class WebAuthnError extends Error {
+        constructor({ message: e, code: t, cause: r, name: n }) {
+            super(e, { cause: r });
+            Object.defineProperty(this, "code", defaultPropDescriptor), this.name = n ?? r.name, this.code = t
+        }
+    };
+
+    // 导出内部工具（供测试/扩展使用）
+    e.WebAuthnAbortService = WebAuthnAbortService;
+    e._browserSupportsWebAuthnAutofillInternals = p;
+    e._browserSupportsWebAuthnInternals = o;
+    e.base64URLStringToBuffer = base64URLStringToBuffer;
+    e.bufferToBase64URLString = bufferToBase64URLString;
+    e.browserSupportsWebAuthn = browserSupportsWebAuthn;
+    e.browserSupportsWebAuthnAutofill = browserSupportsWebAuthnAutofill;
+    e.platformAuthenticatorIsAvailable = () => {
+        return browserSupportsWebAuthn() ? PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable() : falsePromise;
+    };
+    e.WebAuthnError = WebAuthnError;
+
+    // 开始认证（登录）
+    e.startAuthentication = async e => {
+        if (!e.optionsJSON && e.challenge) {
+            console.warn(`startAuthentication() 调用方式不正确;将尝试继续使用提供的选项,但建议按照正确的调用结构重构;`);
+            e = { optionsJSON: e }
+        }
+        const { optionsJSON: o, useBrowserAutofill: c = !1, verifyBrowserAutofillInput: d = !0 } = e;
+        if (!browserSupportsWebAuthn()) throw new Error("当前浏览器不支持 WebAuthn");
+        let p, R;
+        if (0 !== o.allowCredentials?.length) p = o.allowCredentials?.map(convertAllowCredential);
+        const f = { ...o, challenge: base64URLStringToBuffer(o.challenge), allowCredentials: p }, b = {};
+        if (c) {
+            if (!await browserSupportsWebAuthnAutofill()) throw new Error("当前浏览器不支持 WebAuthn 自动填充");
+            if (document.querySelectorAll("input[autocomplete$='webauthn']").length < 1 && d)
+                throw new Error('未检测到任何 `autocomplete` 属性值以 "webauthn" 结尾的 <input> 元素');
+            b.mediation = "conditional", f.allowCredentials = []
+        }
+        b.publicKey = f, b.signal = WebAuthnAbortService.createNewAbortSignal();
+        try {
+            R = await navigator.credentials.get(b)
+        } catch (error) {
+            throw (({ error: e, options: t }) => {
+                const { publicKey: r } = t;
+                if (!r) throw new Error("options 缺少必需的 publicKey 属性");
+                if ("AbortError" === e.name) {
+                    if (t.signal instanceof AbortSignal) return new WebAuthnError({
+                        message: "认证流程收到了中止信号", code: "ERROR_CEREMONY_ABORTED", cause: e
+                    })
+                } else {
+                    if ("NotAllowedError" === e.name) return new WebAuthnError({
+                        message: e.message, code: "ERROR_PASSTHROUGH_SEE_CAUSE_PROPERTY", cause: e
+                    });
+                    if ("SecurityError" === e.name) {
+                        const t = globalThis.location.hostname;
+                        if (!isValidDomain(t)) return new WebAuthnError({
+                            message: `${globalThis.location.hostname} 是无效域名`, code: "ERROR_INVALID_DOMAIN", cause: e
+                        });
+                        if (r.rpId !== t) return new WebAuthnError({
+                            message: `RP ID "${r.rpId}" 对于当前域名无效`, code: "ERROR_INVALID_RP_ID", cause: e
+                        })
+                    } else if ("UnknownError" === e.name) return new WebAuthnError({
+                        message: "验证器无法处理指定的选项或创建新的断言签名", code: "ERROR_AUTHENTICATOR_GENERAL_ERROR", cause: e
+                    })
+                }
+                return e
+            })({ error, options: b })
+        }
+        if (!R) throw new Error("认证未完成");
+        const { id: g, rawId: w, response: A, type: E } = R;
+        let m;
+        if (A.userHandle) m = bufferToBase64URLString(A.userHandle);
+        return {
+            id: g,
+            rawId: bufferToBase64URLString(w),
+            response: {
+                authenticatorData: bufferToBase64URLString(A.authenticatorData),
+                clientDataJSON: bufferToBase64URLString(A.clientDataJSON),
+                signature: bufferToBase64URLString(A.signature),
+                userHandle: m
+            },
+            type: E,
+            clientExtensionResults: R.getClientExtensionResults(),
+            authenticatorAttachment: normalizeAuthenticatorAttachment(R.authenticatorAttachment)
+        }
+    };
+
+    // 开始注册（创建凭证）
+    e.startRegistration = async e => {
+        if (!e.optionsJSON && e.challenge) {
+            console.warn("startRegistration() 调用方式不正确;将尝试继续使用提供的选项,但建议按照正确的调用结构重构;");
+            e = { optionsJSON: e }
+        }
+        const { optionsJSON: o, useAutoRegister: c = !1 } = e;
+        if (!browserSupportsWebAuthn()) throw new Error("当前浏览器不支持 WebAuthn");
+        const h = {
+            ...o, challenge: base64URLStringToBuffer(o.challenge),
+            user: {
+                ...o.user, id: base64URLStringToBuffer(o.user.id)
+            },
+            excludeCredentials: o.excludeCredentials?.map(convertAllowCredential)
+        }, p = {};
+        let f;
+        if (c) p.mediation = "conditional";
+        p.publicKey = h, p.signal = WebAuthnAbortService.createNewAbortSignal();
+        try {
+            f = await navigator.credentials.create(p)
+        } catch (error) {
+            throw (({ error: e, options: t }) => {
+                const { publicKey: r } = t;
+                if (!r) throw new Error("options 缺少必需的 publicKey 属性");
+                if ("AbortError" === e.name) {
+                    if (t.signal instanceof AbortSignal) return new WebAuthnError({
+                        message: "注册流程收到了中止信号", code: "ERROR_CEREMONY_ABORTED", cause: e
+                    })
+                } else if ("ConstraintError" === e.name) {
+                    if (!0 === r.authenticatorSelection?.requireResidentKey) return new WebAuthnError({
+                        message: "要求使用可发现凭证,但可用的验证器不支持",
+                        code: "ERROR_AUTHENTICATOR_MISSING_DISCOVERABLE_CREDENTIAL_SUPPORT", cause: e
+                    });
+                    if ("conditional" === t.mediation && "required" === r.authenticatorSelection?.userVerification)
+                        return new WebAuthnError({
+                            message: "自动注册时要求用户验证,但无法执行",
+                            code: "ERROR_AUTO_REGISTER_USER_VERIFICATION_FAILURE", cause: e
+                        });
+                    if ("required" === r.authenticatorSelection?.userVerification) return new WebAuthnError({
+                        message: "要求用户验证,但可用的验证器不支持",
+                        code: "ERROR_AUTHENTICATOR_MISSING_USER_VERIFICATION_SUPPORT", cause: e
+                    })
+                } else {
+                    if ("InvalidStateError" === e.name) return new WebAuthnError({
+                        message: "该验证器已被注册过", code: "ERROR_AUTHENTICATOR_PREVIOUSLY_REGISTERED", cause: e
+                    });
+                    if ("NotAllowedError" === e.name) return new WebAuthnError({
+                        message: e.message, code: "ERROR_PASSTHROUGH_SEE_CAUSE_PROPERTY", cause: e
+                    });
+                    if ("NotSupportedError" === e.name) {
+                        if (0 === r.pubKeyCredParams.filter((e => "public-key" === e.type)).length) return new WebAuthnError({
+                            message: 'pubKeyCredParams 中没有 type 为 "public-key" 的条目',
+                            code: "ERROR_MALFORMED_PUBKEYCREDPARAMS", cause: e
+                        });
+                        return new WebAuthnError({
+                            message: "没有可用的验证器支持指定的任何 pubKeyCredParams 算法",
+                            code: "ERROR_AUTHENTICATOR_NO_SUPPORTED_PUBKEYCREDPARAMS_ALG", cause: e
+                        })
+                    }
+                    if ("SecurityError" === e.name) {
+                        const t = globalThis.location.hostname;
+                        if (!isValidDomain(t)) return new WebAuthnError({
+                            message: `${globalThis.location.hostname} 是无效域名`, code: "ERROR_INVALID_DOMAIN", cause: e
+                        });
+                        if (r.rp.id !== t) return new WebAuthnError({
+                            message: `RP ID "${r.rp.id}" 对于当前域名无效`, code: "ERROR_INVALID_RP_ID", cause: e
+                        })
+                    } else if ("TypeError" === e.name) {
+                        if (r.user.id.byteLength < 1 || r.user.id.byteLength > 64) return new WebAuthnError({
+                            message: "用户 ID 长度不在1~64字节之间", code: "ERROR_INVALID_USER_ID_LENGTH", cause: e
+                        })
+                    } else if ("UnknownError" === e.name) return new WebAuthnError({
+                        message: "验证器无法处理指定的选项或创建新的凭证", code: "ERROR_AUTHENTICATOR_GENERAL_ERROR", cause: e
+                    })
+                }
+                return e
+            })({ error, options: p })
+        }
+        if (!f) throw new Error("注册未完成");
+        const { id: b, rawId: R, response: g, type: w } = f;
+        let A, E, m, y;
+        if ("function" == typeof g.getTransports) A = g.getTransports();
+        if ("function" == typeof g.getPublicKeyAlgorithm) {
+            try { E = g.getPublicKeyAlgorithm() }
+            catch (e) { warnExtensionMishandling("getPublicKeyAlgorithm()", e) }
+        }
+        if ("function" == typeof g.getPublicKey) {
+            try {
+                const e = g.getPublicKey();
+                null !== e && (m = bufferToBase64URLString(e))
+            } catch (e) { warnExtensionMishandling("getPublicKey()", e) }
+        }
+        if ("function" == typeof g.getAuthenticatorData) {
+            try { y = bufferToBase64URLString(g.getAuthenticatorData()) }
+            catch (e) { warnExtensionMishandling("getAuthenticatorData()", e) }
+        }
+        return {
+            id: b,
+            rawId: bufferToBase64URLString(R),
+            response: {
+                attestationObject: bufferToBase64URLString(g.attestationObject),
+                clientDataJSON: bufferToBase64URLString(g.clientDataJSON),
+                transports: A, publicKeyAlgorithm: E, publicKey: m, authenticatorData: y
+            },
+            type: w,
+            clientExtensionResults: f.getClientExtensionResults(),
+            authenticatorAttachment: normalizeAuthenticatorAttachment(f.authenticatorAttachment)
+        }
+    }
+});

package/helpers/base64urlAndBuffer.js

@@ -0,0 +1,43 @@
+/**
+ * 将 Base64URL 编码的字符串转换为数组缓冲区; 最适合在将凭据 ID 从 JSON 字符串转换为 ArrayBuffer 时使用,
+ * 例如在 allowCredentials 或 excludeCredentials 中;
+ * 与 `bufferToBase64URLString` 配对使用;
+ * - 查看定义:@see {@link base64URLStringToBuffer}
+ * @param {string} base64URLString - Base64URL 编码的字符串
+ * @returns {ArrayBuffer} 转换后的 ArrayBuffer
+ */
+const base64URLStringToBuffer = base64URLString => {
+    // 从 Base64URL 转换为标准 Base64
+    const base64 = base64URLString.replace(/-/g, '+').replace(/_/g, '/'),
+        /**
+         * 用 '=' 填充，直到长度是 4 的倍数
+         * (4 - (85 % 4 = 1) = 3) % 4 = 3 个填充
+         * (4 - (86 % 4 = 2) = 2) % 4 = 2 个填充
+         * (4 - (87 % 4 = 3) = 1) % 4 = 1 个填充
+         * (4 - (88 % 4 = 0) = 4) % 4 = 0 个填充
+         */
+        padLength = (4 - (base64.length % 4)) % 4, padded = base64.padEnd(base64.length + padLength, '='),
+        // 转换为二进制字符串并将二进制字符串转换为缓冲区
+        binary = atob(padded), buffer = new ArrayBuffer(binary.length), bytes = new Uint8Array(buffer);
+    for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+    return buffer;
+}
+
+/**
+ * 将给定的数组缓冲区转换为 Base64URL 编码的字符串;适用于将各种凭证响应的 ArrayBuffer
+ * 转换为字符串,以便作为 JSON 发送回服务器;
+ * 与 `base64URLStringToBuffer` 搭配使用
+ * - 查看定义:@see {@link bufferToBase64URLString}
+ * @param {BufferSource} buffer - 要转换的 ArrayBuffer 或 ArrayBufferView
+ * @returns {string} Base64URL 编码的字符串（不含填充符）
+ */
+const bufferToBase64URLString = buffer => {
+    const bytes = new Uint8Array(buffer);
+    let str = '';
+    for (const charCode of bytes) str += String.fromCharCode(charCode);
+
+    const base64String = btoa(str);
+    return base64String.replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '');
+}
+
+export { base64URLStringToBuffer, bufferToBase64URLString };

package/helpers/browserSupportsWebAuthn.js

@@ -0,0 +1,19 @@
+/**
+ * 使得在测试期间可以模拟返回值
+ * - 查看定义:@see {@link _browserSupportsWebAuthnInternals}
+ * @ignore 不要将其包含在文档输出中
+ * @type {{ stubThis: <T>(value: T) => T }}
+ */
+const _browserSupportsWebAuthnInternals = { stubThis: value => value };
+
+/**
+ * 判断浏览器是否支持 WebAuthn
+ * - 查看定义:@see {@link browserSupportsWebAuthn}
+ * @returns {boolean} 如果浏览器支持 WebAuthn 则返回 true,否则返回 false
+ */
+const browserSupportsWebAuthn = () => {
+    return _browserSupportsWebAuthnInternals.stubThis(globalThis?.PublicKeyCredential !== undefined &&
+        typeof globalThis.PublicKeyCredential === 'function');
+}
+
+export { _browserSupportsWebAuthnInternals, browserSupportsWebAuthn };

package/helpers/browserSupportsWebAuthnAutofill.js

@@ -0,0 +1,30 @@
+import { browserSupportsWebAuthn } from './browserSupportsWebAuthn.js';
+
+/**
+ * 使得在测试期间可以模拟返回值
+ * - 查看定义:@see {@link  _browserSupportsWebAuthnAutofillInternals}
+ * @ignore 不要将其包含在文档输出中
+ * @type {{ stubThis: <T>(value: T) => T }}
+ */
+const _browserSupportsWebAuthnAutofillInternals = { stubThis: value => value };
+
+/**
+ * 判断浏览器是否支持条件式 UI,以便在浏览器的密码填充弹窗中向用户显示 WebAuthn 凭证;
+ * - 查看定义:@see {@link browserSupportsWebAuthnAutofill}
+ * @returns {Promise<boolean>} 一个解析为布尔值的 Promise,表示是否支持条件式 UI
+ */
+const browserSupportsWebAuthnAutofill = () => {
+    if (!browserSupportsWebAuthn())
+        return _browserSupportsWebAuthnAutofillInternals.stubThis(Promise.resolve(false));
+
+    // 由于 TypeScript DOM 类型定义尚未包含 isConditionalMediationAvailable,这里直接通过属性访问进行检测,避免类型断言;
+    const globalPublicKeyCredential = globalThis.PublicKeyCredential;
+    if (globalPublicKeyCredential?.isConditionalMediationAvailable === undefined)
+        return _browserSupportsWebAuthnAutofillInternals.stubThis(Promise.resolve(false));
+
+    return _browserSupportsWebAuthnAutofillInternals.stubThis(
+        globalPublicKeyCredential.isConditionalMediationAvailable()
+    );
+}
+
+export { _browserSupportsWebAuthnAutofillInternals, browserSupportsWebAuthnAutofill };

package/helpers/identifyAuthenticationError.js

@@ -0,0 +1,50 @@
+import { isValidDomain } from './isValidDomain.js';
+import { WebAuthnError } from './webAuthnError.js';
+
+/**
+ * 尝试推断调用 `navigator.credentials.get()` 后引发错误的原因;
+ * - 查看定义:@see {@link identifyAuthenticationError}
+ *
+ * @param {Object} params - 参数对象
+ * @param {Error|DOMException} params.error - 原始错误对象
+ * @param {CredentialRequestOptions} params.options - navigator.credentials.get() 传入的选项
+ * @returns {Error|WebAuthnError} 解析后的错误对象（WebAuthnError 或原始错误）
+ */
+const identifyAuthenticationError = ({ error, options }) => {
+    const { publicKey } = options;
+    if (!publicKey) throw Error('options 参数缺少必需的 publicKey 属性');
+
+    if (error.name === 'AbortError') {
+        if (options.signal instanceof AbortSignal)
+            // https://www.w3.org/TR/webauthn-2/#sctn-createCredential (第 16 步)
+            return new WebAuthnError({ message: '身份验证收到了中止信号', code: 'ERROR_CEREMONY_ABORTED', cause: error });
+    }
+    else if (error.name === 'NotAllowedError')
+        /**
+         * 直接传递错误，平台对该错误的定义超出了规范范围，我们不想覆盖可能更有用的错误消息；
+         */
+        return new WebAuthnError({ message: error.message, code: 'ERROR_PASSTHROUGH_SEE_CAUSE_PROPERTY', cause: error });
+    else if (error.name === 'SecurityError') {
+        const effectiveDomain = globalThis.location.hostname;
+        if (!isValidDomain(effectiveDomain))
+            // https://www.w3.org/TR/webauthn-2/#sctn-discover-from-external-source (第 5 步)
+            return new WebAuthnError({
+                message: `${globalThis.location.hostname} 是一个无效的域名`, code: 'ERROR_INVALID_DOMAIN', cause: error
+            });
+        else if (publicKey.rpId !== effectiveDomain)
+            // https://www.w3.org/TR/webauthn-2/#sctn-discover-from-external-source (第 6 步)
+            return new WebAuthnError({
+                message: `信赖方 ID“${publicKey.rpId}”对此域名无效`, code: 'ERROR_INVALID_RP_ID', cause: error
+            });
+    }
+    else if (error.name === 'UnknownError')
+        // https://www.w3.org/TR/webauthn-2/#sctn-op-get-assertion (第 1 步)
+        // https://www.w3.org/TR/webauthn-2/#sctn-op-get-assertion (第 12 步)
+        return new WebAuthnError({
+            message: '身份验证器无法处理指定的选项或创建新的断言签名', code: 'ERROR_AUTHENTICATOR_GENERAL_ERROR', cause: error
+        });
+
+    return error;
+}
+
+export { identifyAuthenticationError };

package/helpers/identifyRegistrationError.js

@@ -0,0 +1,99 @@
+import { isValidDomain } from './isValidDomain.js';
+import { WebAuthnError } from './webAuthnError.js';
+
+/**
+ * 尝试推断调用 `navigator.credentials.create()` 后引发错误的原因
+ * - 查看定义: @see {@link identifyRegistrationError}
+ *
+ * @param {Object} params - 参数对象
+ * @param {Error} params.error - 原始错误对象
+ * @param {CredentialCreationOptions} params.options - 传递给 `navigator.credentials.create()` 的选项
+ * @returns {WebAuthnError|Error} 如果错误能被识别则返回包含更详细信息的 WebAuthnError，否则返回原始错误
+ */
+const identifyRegistrationError = ({ error, options }) => {
+    const { publicKey } = options;
+    if (!publicKey) throw Error('options 参数缺少必需的 publicKey 属性');
+
+    if (error.name === 'AbortError') {
+        if (options.signal instanceof AbortSignal)
+            // https://www.w3.org/TR/webauthn-2/#sctn-createCredential (第 16 步)
+            return new WebAuthnError({
+                message: '注册仪式收到了中止信号', code: 'ERROR_CEREMONY_ABORTED', cause: error,
+            });
+    }
+    else if (error.name === 'ConstraintError') {
+        if (publicKey.authenticatorSelection?.requireResidentKey === true)
+            // https://www.w3.org/TR/webauthn-2/#sctn-op-make-cred (第 4 步)
+            return new WebAuthnError({
+                message: '需要可发现凭证，但没有可用的身份验证器支持该功能',
+                code: 'ERROR_AUTHENTICATOR_MISSING_DISCOVERABLE_CREDENTIAL_SUPPORT', cause: error,
+            });
+        // `mediation` 在 CredentialCreationOptions 中尚不存在，但截至 2024 年 9 月已有可能
+        else if (options.mediation === 'conditional' && publicKey.authenticatorSelection?.userVerification === 'required')
+            // https://w3c.github.io/webauthn/#sctn-createCredential (第 22.4 步)
+            return new WebAuthnError({
+                message: '自动注册期间要求用户验证，但无法执行', code: 'ERROR_AUTO_REGISTER_USER_VERIFICATION_FAILURE', cause: error
+            });
+
+        else if (publicKey.authenticatorSelection?.userVerification === 'required')
+            // https://www.w3.org/TR/webauthn-2/#sctn-op-make-cred (第 5 步)
+            return new WebAuthnError({
+                message: '需要用户验证，但没有可用的身份验证器支持该功能',
+                code: 'ERROR_AUTHENTICATOR_MISSING_USER_VERIFICATION_SUPPORT', cause: error
+            });
+    }
+    else if (error.name === 'InvalidStateError')
+        // https://www.w3.org/TR/webauthn-2/#sctn-createCredential (第 20 步)
+        // https://www.w3.org/TR/webauthn-2/#sctn-op-make-cred (第 3 步)
+        return new WebAuthnError({
+            message: '该身份验证器此前已注册', code: 'ERROR_AUTHENTICATOR_PREVIOUSLY_REGISTERED', cause: error
+        });
+    else if (error.name === 'NotAllowedError')
+        /**
+         * 直接传递错误；平台对该错误的定义超出了规范范围，保留原始错误消息；
+         */
+        return new WebAuthnError({ message: error.message, code: 'ERROR_PASSTHROUGH_SEE_CAUSE_PROPERTY', cause: error });
+    else if (error.name === 'NotSupportedError') {
+        const validPubKeyCredParams = publicKey.pubKeyCredParams.filter(param => param.type === 'public-key');
+        if (validPubKeyCredParams.length === 0)
+            // https://www.w3.org/TR/webauthn-2/#sctn-createCredential (第 10 步)
+            return new WebAuthnError({
+                message: 'pubKeyCredParams 中没有类型为 "public-key" 的条目', code: 'ERROR_MALFORMED_PUBKEYCREDPARAMS', cause: error
+            });
+        // https://www.w3.org/TR/webauthn-2/#sctn-op-make-cred (第 2 步)
+        return new WebAuthnError({
+            message: '身份验证器不支持指定的任何 pubKeyCredParams 算法',
+            code: 'ERROR_AUTHENTICATOR_NO_SUPPORTED_PUBKEYCREDPARAMS_ALG', cause: error,
+        });
+    }
+    else if (error.name === 'SecurityError') {
+        const effectiveDomain = globalThis.location.hostname;
+        if (!isValidDomain(effectiveDomain))
+            // https://www.w3.org/TR/webauthn-2/#sctn-createCredential (第 7 步)
+            return new WebAuthnError({
+                message: `${globalThis.location.hostname} 是一个无效的域名`, code: 'ERROR_INVALID_DOMAIN', cause: error
+            });
+        else if (publicKey.rp.id !== effectiveDomain)
+            // https://www.w3.org/TR/webauthn-2/#sctn-createCredential (第 8 步)
+            return new WebAuthnError({
+                message: `信赖方 ID“${publicKey.rp.id}”对此域名无效`, code: 'ERROR_INVALID_RP_ID', cause: error
+            });
+    }
+    else if (error.name === 'TypeError') {
+        if (publicKey.user.id.byteLength < 1 || publicKey.user.id.byteLength > 64)
+            // https://www.w3.org/TR/webauthn-2/#sctn-createCredential (第 5 步)
+            return new WebAuthnError({
+                message: '用户 ID 长度不在 1~64 字节之间', code: 'ERROR_INVALID_USER_ID_LENGTH', cause: error
+            });
+    }
+    else if (error.name === 'UnknownError')
+        // https://www.w3.org/TR/webauthn-2/#sctn-op-make-cred (第 1 步)
+        // https://www.w3.org/TR/webauthn-2/#sctn-op-make-cred (第 8 步)
+        return new WebAuthnError({
+            message: '身份验证器无法处理指定的选项，或无法创建新的凭证', code: 'ERROR_AUTHENTICATOR_GENERAL_ERROR', cause: error
+        });
+
+    return error;
+}
+
+export { identifyRegistrationError };