# SDK npm 分发与发布验收

## 0.7.0 嵌入式 Passkey 发布（2026-11-17）

状态：**`@virtneu/auth@0.7.0` 已公开发布，registry空缓存独立消费验收通过。** npm记录的发布时间为2026-11-17 02:23:28（北京时间），本次核对时latest为0.7.0。来源为干净提交 `2fc022bf78cd7385054152a308e7b0b1649d675e`（`dirty=false`），归档48,251字节、七个文件，SHA-256为 `3daf3a125558fad39cfe3966eab84f9770b8054d980079ca10abddc487672f08`，SHA-512 integrity为 `sha512-NSiS/hm8U2O7MF816QJTGFYy7KcfuGHgf1LT01APup5c/uo4QoPQQWq+V6PrlOymFELOrYvIhl+9n94KR807WQ==`。详见[公开registry回执](../reports/evidence/embedded-passkeys-2026-11-17/sdk-registry-release.json)、[七文件逐字节比对](../reports/evidence/embedded-passkeys-2026-11-17/sdk-registry-byte-comparison.json)及[真实包冷消费](../reports/evidence/embedded-passkeys-2026-11-17/sdk-registry-consumer.json)。

0.7.0增加独立 `@virtneu/auth/browser` bundle / 声明、客户BFF浏览器类与DOM面板、固定 `client_context` 以及后端 `beginEmbeddedPasskeyLogin` 方法。原 `beginPasskeyLogin(RequestOptions)` 不变；16项后端安全方法仍对应41项HTTP操作。空缓存从npm安装精确版本，锁文件指向公共registry归档；七个文件与批准归档逐字节一致。严格TypeScript声明、浏览器ESM入口、默认fetch和真实loopback workerd / 临时D1共25项检查通过，覆盖MFA、hosted及embedded Web/iOS/Android origin、注册/登录/管理、配置revision失效与上下文隔离。原生origin使用软件签名，不代表真实设备仪式。

Swift / Android为仓库中的真实平台adapter源码，不包含在七文件npm归档中，也不是原生二进制SDK；编译与序列化检查结果见[原生检查记录](../reports/2026-11-17-embedded-passkey-client.md)。API/schema、[独立生产迁移回执](../reports/evidence/embedded-passkeys-2026-11-17/production-migration.json)、应用切流及客户真实设备验收各自保留证据，不用npm发布代替。域名验证、RP重新绑定、客户发布OS关联文件、原子BFF store和202分流见[嵌入式Passkey接入](embedded-passkeys.md)。原已发布0.6.0及其归档字节保持不变。

## 0.6.0 账户安全与 Passkey 管理发布（2026-11-16）

状态：**`@virtneu/auth@0.6.0` 已公开发布，registry空缓存独立消费验收通过。** 2026-11-16 16:22:32（北京时间）的回执确认版本和当时的latest均为0.6.0。来源为干净提交 `5d3923e983c73acf4407324342ae8508f74237e0`（`dirty=false`），归档37,339字节、五个文件，SHA-256为 `f4b33ee13df7661da01451e64ad7a50281a8ddea6692855cc0682769753b7f49`，SHA-512 integrity为 `sha512-+Bti545Bj8faAPnVKJzJrJyENp9EaHyuO1Du5HSDi4DPNn8LyjIZ0BuqvCTe0TlJyEpuO+2CSL9b5iKwWnB7dw==`。详见[registry发布与归档核对](../reports/evidence/passkey-account-security-2026-11-16/sdk-registry-release.json)和[独立消费结果](../reports/evidence/passkey-account-security-2026-11-16/sdk-registry-consumer.json)。采用新能力仍需匹配本次API / schema；应用生产切流、控制库 / 租户DDL、发布器信任策略升级与npm发布各自保留结果，不能相互代替。

0.6.0 内置41项 `/v1` HTTP操作和15项安全方法，新增 `renamePasskey`，扩展 Passkey 安全元数据、首绑 continuation 和完成认证分支。原0.5.0的40项合同保持不可变，不以旧版本号发布新字节。OIDC账户安全入口属于独立协议，不要求OIDC客户端引入服务端SDK；使用 `POST I/account-security-request`、新 state / nonce / PKCE 和同用户callback校验，见[接入指南](oidc.md#从应用设置打开-account-security)。

消费者升级必须按 `next_step` 和实际 `methods` 分流：只有真正无既有因素的账户可首次绑定；已有Passkey但无TOTP的密码 / 邮箱 / 社交第一因素不能绑定替代品；验证已有Passkey后再按策略补TOTP。处理 `finishPasskeyRegistration` 的 `reauthentication_required` 判别联合，不能把options、202或普通添加结果当作session。UV始终必需，旧UV0会话拒绝；名称 / 最近使用字段不会暴露内部UV标记或私钥。

发布前完成完整本地检查、干净来源和 `pnpm sdk:release` 产物校验；候选tgz与公开registry包均通过独立实体安装、默认fetch、真实loopback workerd / 临时D1的15方法 / 18组安全分流检查。registry阶段使用空缓存安装精确 `@virtneu/auth@0.6.0`，五个文件与批准归档逐字节一致，版本、integrity、ESM、严格TypeScript声明和41操作合同均通过。可重复命令为 `node scripts/verify-sdk-security-consumer.mjs --consumer /absolute/path/to/independent-consumer --output /absolute/path/to/safe-verification.json`。真实设备、第三方账户和跨设备扫码验收另记，软件签名 / 虚拟验证器不证明它们通过。

## 0.5.0 MFA、Passkeys 与社交关联发布（2026-11-13）

`@virtneu/auth@0.5.0` 已公开发布，该历史发布当时的npm latest为0.5.0。registry正式发布时间为北京时间2026-11-13 00:00:23.996，来源为干净提交 `c3a702b00e908a15e523829bd7d59d8e88faf99c`。新增14个方法，内置40项HTTP操作合同：6个MFA、6个Passkeys和2个社交关联接口。`createSession`、`registerUserAndSession`及因素完成方法返回 `Session | AuthenticationContinuation`；消费者必须处理HTTP202，不得在完整认证前设置会话或认定用户归属。升级需要在后端检查并缩窄该union，原0.4.0包及其26项合同保持不变。

Google、GitHub、Apple登录和显式关联继续使用托管OIDC；SDK新增 `listSocialConnections`、`unlinkSocialConnection`，不提供浏览器提交provider token的直接登录接口。Passkey仪式必须在固定的Auth托管域完成，SDK调用方不能选择RP或origin。生产API在应用提交 `157648ecfe06e85c3a0c6999d7664bea0c88c013` 已包含对应路由；此次npm分发与网站部署独立。

发布前要求干净的确切源码、完整 `pnpm check`、`pnpm sdk:release` 及实际冷消费验收。可重复的验收命令为：

```sh
node scripts/verify-sdk-security-consumer.mjs \
  --consumer /absolute/path/to/independent-consumer \
  --output /absolute/path/to/safe-verification.json
```

consumer先从候选tgz安装，发布后再使用空缓存从npm安装精确版本。脚本从该目录导入真实安装包，使用默认fetch和真实loopback HTTP访问隔离workerd/D1，验证全部14个方法、严格TypeScript声明、202与会话的区别、TOTP / 恢复码、签名Passkey / UV策略、社交关联解除、撤销及App/环境/凭据隔离。测试的TOTP、恢复码、会话和服务凭据不进入证据；软件签名与fixture社交关联不代表硬件、外部账号授权或真实邮件收件。

npm公开归档33,822字节、五个文件，SHA-512 integrity为 `sha512-Lk5gkwHjTwBx8agYCyD5Oz7/mlMTawAUO0ekhgClfhctrYls0vkjQImITeVoBcfvhQ32q+8qdDO54ZJbZNJkxQ==`。完整本地检查1,101项测试、16项类型检查、5项构建通过；公开registry空缓存安装与五文件逐字节比较、严格声明、真实HTTP/workerd/D1的14新增方法 / 16组功能验收均通过。详见[完整发布报告](../reports/2026-11-12-sdk-0.5.0-release.md)与[公开冷消费机器证据](../reports/evidence/sdk-0.5.0-2026-11-12/registry-functional.json)。应用网站未重复部署，其SDK版本文案随后续网站发布更新。已发布包不能原地覆盖；修复使用新版本，回退消费者仍须保留已启用MFA所需的202处理。

## 0.4.0 npm 发布与冷消费验收（2026-11-10）

`@virtneu/auth@0.4.0` 已发布到 npm：CLI 于北京时间21:33:38接受发布，registry 于21:36:09确认该版本可用。发布包来自干净提交 `17bc9f6e0fa79f8cac677a5f182917e1b04bdde4`，仅含5个白名单文件，归档为23543字节。原0.3.0及其23项内置合同保持不变。

```sh
npm install @virtneu/auth@0.4.0
```

[npm 0.4.0 包页面](https://www.npmjs.com/package/@virtneu/auth/v/0.4.0)是该版本分发入口。0.4.0新增 `getSessionContext`，内置匹配的26项 HTTP 操作合同；26是合同操作数量，并非SDK方法数量。runtime / tenant readiness 尚无专用 SDK 方法。既有注册、登录、session_token、显式同令牌续期和撤销语义保持兼容。

发布前完整检查通过914项测试、16项类型检查和5项构建；`pnpm sdk:release` 确认来源干净、包结构与源码合同一致。公开 registry 冷安装的 SHA-512 integrity 与已验收归档完全一致：

```text
sha512-pANji1UiQfSOTZu/+e6HR6a82EU3eIjG16S+Vio014n3jChc6vn65GtEFqbFzGHgozpLYjHZEQBaOkknWab0IQ==
```

独立消费目录使用空 npm 缓存，仅从 registry 安装精确版本；锁文件指向 `https://registry.npmjs.org/@virtneu/auth/-/auth-0.4.0.tgz`，没有 workspace 链接或本地归档替代。ESM、严格 TypeScript、26项内置合同以及三个 dist 文件与批准候选的逐字节比较全部通过。

安装后的 SDK 使用默认真实 fetch，经 Node HTTP 和独立 Worker HTTP 连接真实 workerd / D1 / Auth 引擎，验证密码登录、会话上下文、同令牌续期、绝对期限、撤销、App / 环境 / 服务凭据隔离、账号停用 / 恢复、密码重设失效与新密码登录。未使用源码 SDK 或自定义合成 transport，未修改生产数据、未创建新的生产 fixture，也未将外部邮件投递记为已验收。安全机器证据见[0.4.0 发布记录](evidence/sdk-0.4.0-2026-11-10/release.json)。

独立 registry 查询已确认 npm `latest` 为0.4.0。官网、Studio 与管理 MCP 的安装命令从 SDK package 读取同一版本。上述 npm 冷消费验收检查点为北京时间21:38，当时尚未切换生产入口；后续生产切换使用独立发布器记录具体源码、产物、版本与线上探测，不能将包发布回执视为网站部署回执。

SDK 保持仅供后端服务凭据调用 `/v1`。Web / 原生系统浏览器登录使用独立的 [OIDC 协议](oidc.md)和成熟 OIDC 客户端库；不能把后端服务密钥放入原生应用，也不能将 OIDC 令牌当作 session_token。复用会话方案见[浏览器长会话与按需续期](https://auth.virtneu.com/docs/browser-sessions)。

## 发布步骤

1. 发布新增 SDK 前，先选择未发布的新版本，同步 SDK package 与 OpenAPI generator 的版本，完成 `pnpm check`，核对权限、合同与示例。源码增量尚未升级版本时，只能进行隔离检查。
2. 从干净源码运行 `pnpm sdk:release`，构建独立 ESM、TypeScript 声明和当版 OpenAPI，并生成本地发布包及验收清单。该命令只打包和检查，不发布 npm。
3. 核对待发布产物的版本、内容白名单及摘要，使用有发布权限的 npm 账号发布已验收的确切产物。npm 发布是独立步骤，不由网站构建或 Git push 代替。
4. 使用 npm 查询确认待发布新版本的版本号、分发 integrity 和包元数据。在隔离消费目录从 registry 安装该确切版本，检查 ESM、严格 TypeScript 声明及 `@virtneu/auth/openapi.json`；锁文件应引用 npm 包。以下0.3.0历史记录只验证原23项合同。
5. 核对匹配的API和官网部署，页面 / Studio / MCP的版本元数据应匹配实际已发布的npm版本。0.7.0和0.6.0内置41项合同，0.5.0为40项，0.4.0为26项，历史0.3.0为23项，各版本独立验收。独立记录部署修订及真实接入验证，不以包安装成功代替登录验收。

## 0.3.0 npm 发布验收（2026-11-06）

`@virtneu/auth@0.3.0` 于该历史阶段发布，当时 npm `latest` 为0.3.0。发布包来源为干净提交 `155d160ef5181036e2664087b4a2ccad6108e50e`，包含5个白名单文件、23项HTTP操作；后续官网响应头和旧下载路径补丁不修改已发布包。registry 的 SHA-512 integrity 与本地验收产物一致：

```text
sha512-3VuzFontUms0QzhQYBDs6M7tXuca/asdJoAr+qs5JNwkLLQasorzfPU2t443CONaTYYs7usk7c66DXVfV+0Svg==
```

使用空 npm 缓存在隔离目录从 registry 安装0.3.0，ESM新方法、严格TypeScript声明及内置OpenAPI与源码逐字节对比通过。SDK测试传输为合成HTTP响应，没有发送真实邮件或完成新的用户登录；这些结果不能替代消费项目的真实接入验收。API已同步上传，保留所有租户D1与Secret绑定。官网不再分发SDK归档，文档保持npm安装方式；生产部署记录独立保存。

## 从旧 SDK 切换

registry已确认0.7.0发布并通过独立冷消费验收；消费项目采用新能力时须先匹配本次API / schema，再升级到精确版本、核对内置41操作OpenAPI，并提交包管理器锁文件。0.5.0引入MFA / Passkey基础方法；0.6.0新增rename与安全首绑分流；0.7.0增加浏览器入口与embedded客户RP上下文，旧hosted key仍需在新RP重新绑定。必须按 `Session | AuthenticationContinuation` 和实际methods处理，HTTP202不能建立会话。元数据请求和响应继续使用 `profile_metadata`、`managed_metadata`；服务不接受旧字段或旧上下文头。既有密钥不会自动获得 `users:read`、`users:status`，按实际用途显式签发相应权限的新密钥并在客户后端轮换。接口范围与错误语义见[用户目录](https://auth.virtneu.com/docs/users)及[业务用户安全](end-user-security.md)。

历史官网URL安装、旧版本CI产物及本地打包缓存不作为当前消费项目的安装入口。已发布版本的内容不能原地覆盖；后续变化应发布新版本。

## 本地发布包检查

`pnpm sdk:pack` 先构建 ESM / TypeScript 声明并复制当版 OpenAPI，在 `output/sdk` 生成待发布包及 `release.json`。此清单仅用于维护者核对包名、版本、Git修订、未提交状态、字节数、SHA-256 / SHA-512 integrity、文件白名单和 OpenAPI 摘要，不再复制到官网作为分发渠道。

`pnpm sdk:verify` 核对现有产物；`pnpm sdk:release` 重新构建并要求干净源码与当前 HEAD 一致。不读取 npm 凭据、不创建 Git 标签或 GitHub Release。清单没有数字签名，不等于 npm provenance。npm 发布结果须独立查询确认。

0.7.0发布包只允许 package.json、README.md、dist/index.js、dist/index.d.ts、dist/browser.js、dist/browser.d.ts、dist/openapi.json，拒绝额外文件、重复路径、符号链接、特殊条目、安装 / 发布钩子和运行时依赖。JS必须独立，服务端声明不引用外部包；浏览器声明只可引用同包公开的 `./index.js` 类型。OpenAPI 必须与源码合同一致；包大小上限2MB，解包检查有输出及执行时限。调用密钥不进入发布包或前端。

## 网站交付与历史 CI

`.githooks/pre-push` 运行完整 `pnpm check`。网站构建提供文档、HTTP 合同与 npm 安装入口；网站构建不再生成 SDK 官网下载包。代码部署和 npm 包发布分别验收。

早期 CI 曾在完整检查后保存带提交 SHA 的私有 artifact，保留期为30天；2026-11-05核对时仓库已无 GitHub Actions workflow。历史 artifact 需要 GitHub 授权，不能替代当前 npm 版本验收。

## 功能发布验收快照（2026-11-05）

以下记录对应 `c384201` 功能发布时的0.2.0生产归档，属于历史证据。官网归档分发已从当前安装流程移除；历史摘要不能用来验证0.3.0 npm包。

四项目最终发布提交为 `c384201ed80a3c31ebebb53b5ce4760fa8682ad9`，Studio Pages canonical 与 SDK manifest.source.revision 均匹配该提交，dirty=false。生产 HTTP 下载的0.2.0归档为18115字节，SHA-256为 `8700928dc26809d2ccff9effd7fb7538689702b1c9e28ea6decf52d25c0f3e2a`；清单同时提供 SHA-512 integrity。官网及归档内 OpenAPI 与源码逐字节相同，包含21项操作。

真实下载归档在隔离目录离线安装后，ESM的新5个方法与严格 TypeScript 声明检查通过，旧元数据字段的负向类型检查通过；最终归档与首次完整冷消费的字节摘要相同。官网 / 指南安装地址、公开用户文档及两条已退役资源404均完成公网验证。Studio 安装入口核对了实际发布 JavaScript，未进行生产登录交互。该次发布清单的验证结果保留在历史记录；仓库内完整证据与边界位于 `docs/cloudflare.md` 的用户目录与注册租户集中发布记录。

## 验证范围

隔离临时消费目录离线安装真正 tgz，执行 ESM 和严格声明检查、核对内置 OpenAPI。安装包同时在 Node 与仓库兼容日期的真实 workerd 中向本机 HTTP 服务发送会话校验，核对 App / 环境 / 凭据、active=false、503错误及 Retry-After、无自动重试。该服务使用合成凭据，不访问线上 App 或真实用户。

原有 auth-api SDK 集成测试继续覆盖真实 Better Auth / D1 的 proof 注册、密码及验证码登录、刷新 / 撤销、禁用、密码重置、永久删除、认证事件与 App / 环境隔离；用户查询回归还覆盖精确匹配、批量边界、字段白名单、基础筛选、同条件总数、签名游标绑定与隔离；账号状态覆盖安全版本失配、禁用 / 恢复、改密和全部撤销，以及故障503。用户目录示例的独立回归通过真实 SDK 的合成 transport 验证签发前真实会话二次校验、禁用恢复竞态、跨身份及503传播，不调用线上用户或供应商。候选包检查不能替代真实邮件、客户业务接入、npm公开发布和具体第三方宿主验收。
