软件认证器

配置软件 WebAuthn 凭据、处理注册保存回调，并管理本地或外部签名计数器。

能力：softwareAuthenticator。EP：internal.software_authenticator。网站使用标准 navigator.credentials.create() 和 get()，没有 chrovia.softwareAuthenticator JS 域。注册保存回复还需要 messaging 和负责处理的 Provision 插件。

配置认证器

{
  "internal": {
    "software_authenticator": {
      "config": {
        "disguise_as": "windows_hello",
        "display_name": "SDK Passkey Vault",
        "counter_source": "local"
      }
    }
  }
}

字段	可选值与默认值
`config.disguise_as`	`windows_hello`、`icloud_keychain`、`gpm_phone`；默认 `gpm_phone`
`config.display_name`	非空界面名称，默认 `Passkey Vault`
`config.counter_source`	`external` 为会递增的预设向插件申请计数器，其他值使用本地
`credentials`	导入此前保存凭据时使用的序列化记录数组

选择新注册的通行密钥向网站呈现的方式。这些预设不会将通行密钥保存到真实 Windows Hello、iCloud 或手机，也不提供硬件凭据。更改预设影响后续注册，不改变已有通行密钥。

测试时，安装配置和保存处理器后完全重启，打开网站账号安全设置并选择添加通行密钥。出现选项时选择配置的凭据库名称，然后完成网站确认。退出网站账号，再选择通行密钥登录，并在提示时选择已保存账号。测试期间应保留其他登录方式。

注册需要保存回复

每次 Provision Service Worker 启动时注册。以下最小例子批准本地测试注册，内核收到批准后才保存记录：

const messaging = globalThis.chrovia?.messaging;
if (messaging) {
  messaging.on('chrovia.software_authenticator.credential.save', data => {
    const channel = data?.callback_channel;
    if (data?.action !== 'save_credential'
        || typeof channel !== 'string'
        || !channel.startsWith('chrovia.software_authenticator.credential.save.reply.')) {
      return;
    }
    messaging.emit(channel, { success: true });
  });
}

请求包含完整凭据记录、action: "save_credential" 和 callback_channel。回复 {success: true} 接受，或 {success: false} 拒绝。失败或 30 秒未回复会拒绝注册。监听器直接 return 一个值不等于回复。

接入受控凭据库时，应先验证并持久化记录，再回复成功。载荷包含敏感登录数据，不要记录日志。不要安装两个同时响应注册通道的插件。

使用 HTTPS/localhost 依赖方测试站点，或 Chrovia Studio 软件认证器演示进行注册和登录。仍需遵守普通 WebAuthn 的 origin、RP、challenge 和服务端验证要求。只有浏览器端凭据不等于服务端已注册账号，也不保证每个网站或 headless 流程都能无人值守成功。

备份、恢复与移除通行密钥

将每条凭据视为不可拆解的完整记录：保留所有字段和值，不要解码或重新构造内容。使用 rp_id 识别网站、user_id 识别账号、credential_id 识别通行密钥，可选的 user_name / user_display_name 用于展示。标识值应原样保留。

保存请求的顶层包含这些记录字段，以及 action 和 callback_channel。存入凭据库时去掉这两个消息路由字段。同一 rp_id 和 user_id 注册新通行密钥，会替换此前的本地通行密钥，因此应替换凭据库中该账号的条目，不要直接追加。网站确认注册成功后，再依赖新通行密钥登录。

恢复或移除本地通行密钥：

完全退出实例，备份当前 Extended Preferences 文件。保留 internal.software_authenticator.credentials 中近期的完整凭据列表，其中可能包含注册后产生的更新。通过 chrovia.prefs 读取还需要 extendedPrefs。
用已保存记录准备完整的目标 credentials 数组。移除某个通行密钥时省略对应记录；全部移除时使用空数组。保留文档的其他内容和认证器配置。
未签名偏好可以在实例关闭时替换文件中的 internal.software_authenticator.credentials。已签名偏好需要获取包含目标列表的新签名文件。
重启实例，在原网站测试登录。修改列表不会刷新已运行的实例。

格式错误或不完整的记录可能被跳过，不要编造占位值。恢复浏览器记录不会在网站注册账号；本地移除也不会撤销网站上的注册，或删除其他凭据库中的副本。应在网站账号安全设置中另行管理。备份和保存载荷应保密，不要交给网站脚本。

外部计数器

使用 counter_source: "external" 时，内核可发送 chrovia.software_authenticator.counter.claim，包含 action: "claim_counter"、rp_id、base64 credential_id 和 callback_channel。在该通道回复 {success: true, counter: "42"}，计数器应是由凭据库原子分配的非负 uint32 十进制字符串。

同一凭据跨实例必须协调分配，不要复用示例常量。失败、无效或缺失的回复会在最多 30 秒后回退本地计数行为，不会自动拒绝登录。

外部计数请求适用于使用 windows_hello 或 icloud_keychain 注册的通行密钥。默认 gpm_phone 预设报告零，不请求外部计数器。需要分配计数器时，应在注册前选择会递增的预设。之后修改 disguise_as 不会改变已有通行密钥。

使用已签名配置

开启 signedExtendedPrefs 后，注册或使用通行密钥可能使当前 EP 文件在下次启动时不可用。重启前应获取包含最新凭据列表的已签名 EP。回复保存成功不会更新已签名文件。

未签名本地测试应使用不含 signedExtendedPrefs 的已签发 License。

TOTP 秘密和已保存密码使用不同数据和协议，不要作为软件 WebAuthn 凭据存储。