# 嵌入式 Passkey 接入（0.7.0）

业务 Web 页面可原地完成 Passkey 注册、登录和管理；iOS / macOS 使用 AuthenticationServices，Android 使用 Credential Manager。它们调用客户自己的后端（BFF），不要求为了 Passkey 仪式跳转 Auth 托管页。托管 OIDC 仍是独立可用的路线。**`@virtneu/auth@0.7.0` 已在npm公开发布。** 使用前须匹配API、租户迁移 `0020_embedded_passkeys.sql` 和已验证的RP配置；生产切流与真实设备验收分别记录，包安装不能代替这些检查。已公开的0.6.0包不会自动获得 `/browser` 子路径。

## 先确定 RP 与关联范围

每个 App / 环境只有一份 embedded 配置；租户策略的 `passkeys_enabled` 仍须开启。选择客户拥有的 RP 域名，例如 `example.com` 或 `login.example.com`，并列出精确 HTTPS Web origins、iOS `TEAMID.bundle-id` 及 Android package / 签名证书 SHA-256。Web origin 必须等于 RP 或属于其子域；不接受通配符、任意第三方 origin 或 browser 自选 RP。开发用 `localhost` 只允许 test 环境显式启用，且不能包含 native app。

在 Studio 对应 App / 环境的 Passkey configuration 中保存配置。管理接口为：

`/api/management/applications/{applicationId}/environments/{environment}/passkey-configuration`

| 操作 | 合同 |
| --- | --- |
| `GET` | `data:{configuration:Config|null}`；配置包含 revision、验证状态及未消费 verification_challenge |
| `PUT` | 完整 `{revision,enabled,rp_id,rp_name,web_origins,ios_apps,android_apps,allow_localhost}`，首次 revision=0 |
| `POST /verification-challenge` | `{revision}`，返回10分钟DNS TXT挑战 `{revision,dns_name,dns_type,dns_value,expires_at}` |
| `POST /verify` | `{revision}`，验证当前精确配置的域名所有权；成功返回配置 |
| `GET /association-files` | 返回AASA / assetlinks的path、content_type和JSON body，`deployment_required:true` |

所有管理 mutation 都需要既有管理权限与 `Idempotency-Key`。先保存 disabled 配置，生成TXT，在客户DNS发布并验证，再启用。安全字段变化会禁用配置、清除旧证明并增加 revision；旧浏览器仪式失败关闭。localhost 的 test 验证流程不会访问公网DNS；它不能用作生产域名或原生关联的替代品。

Auth 只生成已验证配置对应的关联文件，**不会把文件部署到客户域名，也不把Auth域的文件当成客户域已关联的证据**：

- iOS / macOS：在 RP 域的 `/.well-known/apple-app-site-association` 发布 `{"webcredentials":{"apps":["TEAMID.bundle-id"]}}`。应用开启 Associated Domains，加入 `webcredentials:<rp-domain>`，使用对应 Team / Bundle 签名。Apple 系统检查关联；应用声明的 `app_id` 本身不是服务器独立的 App Attest 证明。
- Android：在 RP 域的 `/.well-known/assetlinks.json` 发布生成内容，包含 `delegate_permission/common.get_login_creds`、精确 package 和实际发行签名证书指纹。区分debug、release和Play App Signing证书。应用声明同一HTTPS站点关联，运行时由Credential Manager及凭据提供方检查。签名证书origin不是Play Integrity验收。

关联文件应通过公开HTTPS直接返回正确JSON，核对目标域、内容与证书，不依赖登录或重定向。[Apple关联域说明](https://developer.apple.com/documentation/xcode/supporting-associated-domains)、[Android Digital Asset Links](https://developer.android.com/identity/credential-manager/associate-apps-and-websites)。

已有 hosted key 仍属于平台 canonical RP，例如 `auth-api.virtneu.com`。新 embedded RP 的 key 与其明确区分，返回 `rp_id` 和 `binding_kind`。**改 RP 需要重新绑定，不能无感搬迁或复用旧 RP 私钥。** 让已有用户先通过仍有效的 hosted / password / MFA 路线证明身份，再注册新 RP；确认新凭据可用后才移除旧因素。旧账户、会话和key记录不会因生成配置而自动迁移。

## 后端与浏览器的分工

客户后端持有服务凭据、Auth session、flow token、continuation token。浏览器和原生应用只得到随机 `attempt_id` 与标准 `public_key`，完成系统仪式后只提交 `{attempt_id,response:<WebAuthn JSON>}`。注册管理的目标用户取自已经在线验证的客户会话；不根据浏览器的 email、userHandle 或自报user_id选择 owner。

后端使用0.7.0 SDK 的 `beginPasskeyRegistration({...source,name?,client_context})` 或 `beginEmbeddedPasskeyLogin({client_context}, requestOptions?)`。旧 `beginPasskeyLogin(requestOptions?)` 保持原 hosted 语义，不把其第一个参数改成含糊的 input。`client_context` 必须由后端的固定应用配置映射，不能原样接受客户端输入：

```ts
{ platform: 'web', origin: 'https://app.example.com' }
{ platform: 'ios', app_id: 'TEAMID.com.example.app' }
{ platform: 'android', package_name: 'com.example.app', certificate_sha256: '<configured fingerprint>' }
```

后端 resolver 用已启用、已验证的 App / 环境配置确定 RP 和预期 origin。iOS origin 对应 RP 的 HTTPS origin；Android 对应已配置证书的 `android:apk-key-hash:<base64url digest>`。不传 `client_context` 继续使用平台 hosted RP，不能通过任意 origin/RP 输入越权。

## 可运行 Web BFF 与组件

[Fetch BFF handler](../examples/embedded-passkey-bff.ts)导出 `createEmbeddedPasskeyBff`，可在客户现有HTTPS服务器 / Worker中调用 `await bff.handle(request)`；返回null表示交给客户其他路由。它要求注入真实服务端SDK、固定origin、CSRF验证、持久化attempt与客户会话适配器。没有把不安全内存store当生产实现。为所有端点配置业务限速。

| 同源POST（默认 `/auth/passkeys`） | 浏览器请求 | 公有返回 |
| --- | --- | --- |
| `/registration/options` | `{name?,continuation_id?}` | `{attempt_id,public_key}` |
| `/authentication/options` | `{}` | `{attempt_id,public_key}` |
| `/registration/verify`、`/authentication/verify` | `{attempt_id,response}` | 完整认证 / 重新认证要求，或202 continuation handle |
| `/list` | `{}` | `{passkeys:[...]}` |
| `/rename` | `{passkey_id,name}` | `{passkey}` |
| `/delete` | `{passkey_id}` | `{reauthentication_required:true}` |

所有请求都检查精确Origin、JSON、CSRF，并使用Secure / HttpOnly / SameSite客户cookie。注册和登录 attempt 单次、短期，绑定 HttpOnly browser binding、kind、generation与预期用户。`takeAttempt` 必须事务比较活跃binding、generation、purpose、subject再消费，失败不能消费他人的attempt。

**session finalize与logout/reset必须共享同一持久化事务边界。** `sessions.finalize` 在一次事务内校验binding、消费、创建/轮换客户session，记录binding→issued-handles family；`sessions.reset` 同事务取消binding及该family全部handles，包括并发请求刚生成者，再返回私有Auth token供BFF撤销。不能以两个独立KV get/put、先消费再异步建session代替。适配器必须清理到期材料，保留终态family guard直到过期，避免旧请求在logout后复活会话。普通认证完成后不留下账号pin；只有安全管理中的因素变更保留同用户重认证要求。

客户已有密码 / 注册handler在完成其CSRF与真实认证后，可调用 `continueAuthentication(request, result, expectedUser?)`。202只存私有continuation，返回随机 `continuation_id`、`next_step`、`methods`，不能签已登录cookie。根据实际methods继续客户已有MFA BFF；同样绑定浏览器和预期用户。明确logout/reset时调用 `resetAuthentication(request)`，不能只清除浏览器cookie而遗留活跃binding或服务端session。

```ts
import { BrowserPasskeyClient, mountPasskeyPanel } from '@virtneu/auth/browser';

const passkeys = new BrowserPasskeyClient({
  basePath: '/auth/passkeys',
  csrfToken: () => document.querySelector<HTMLMetaElement>('meta[name=csrf-token]')!.content,
});
const panel = mountPasskeyPanel(document.querySelector<HTMLElement>('#passkeys')!, passkeys, {
  allowLogin: true,
  onReauthenticationRequired: () => showSameAccountSignIn(),
});
await panel.refresh();
// 显式点击时调用 register/login；不会在构造或mount时自动弹出系统验证器。
// 卸载页面组件：panel.dispose(); 完全释放客户端：passkeys.dispose();
```

客户端只允许同源BFF路径，不接受Auth API baseURL或服务密钥。请求使用same-origin credentials、redirect:error、no-store、JSON与CSRF hook；响应流限制64KiB。类提供 register/login/list/rename/delete/cancel/dispose；面板使用DOM/textContent，提供pending/error、取消、改名、移除确认与重认证事件。若需conditional UI，由客户显式调用 `login({conditional:true})`，并提供浏览器需要的 `autocomplete="username webauthn"` 输入；支持取决于系统与浏览器，按钮回退仍需保留。

普通注册 / 删除推进安全版本，BFF清理旧客户session并要求原账户重新认证；rename不撤销session。初次绑定只允许真正无既有Passkey和verified TOTP且策略允许的primary continuation。已存在因素不能靠password/email/social第一因素重绑替代品。每次仪式均要求UV，`passkey_satisfies_mfa=false`时仍需按策略完成其他因素。对202监听 `authenticationrequired`，对安全变更和失效监听 `reauthenticationrequired`；只有 `{authenticated:true}` 才代表BFF已建立完整客户会话。

取消或网络失败不自动重放verify / 因素变更。不确定的结果可能已提交，先重新认证、读取实际凭据列表再决定下一步；不要把取消解释成服务器回滚。BFF的finalize若落盘后报错，会尝试reset family与撤销Auth session，错误响应不返回成功cookie。

## Native 适配源码与验收范围

[Swift package](../examples/native-passkeys/swift)提供真实 `ASAuthorizationPlatformPublicKeyCredentialProvider` 注册/认证和同一个 `PasskeyBackendTransport`。目标 iOS16+ / macOS13+；把已绑定的窗口作为presentation anchor，显式调用，不使用WKWebView冒充系统Passkey SDK。旧系统不支持排除列表时由服务器继续防重复；Swift调用取消会取消系统controller。客户实现自己的HTTPS API transport，用应用自己的受保护身份调用BFF，不把Auth服务密钥、Auth session或flow token存进App。HTTP202的continuation handle仍不是登录成功。

[Android adapter](../examples/native-passkeys/android)使用真实 AndroidX Credential Manager `createCredential/getCredential`，直接转发系统生成的标准JSON响应，没有软件私钥或自造签名。示例锁定credentials1.5.0，minSdk28；由界面lifecycle coroutine负责取消。依赖与测试源码已提供，编译/模拟器/真机结果必须分别记录，不能把JSON单元测试当作设备仪式通过。

Native端点属于客户自己的API，**Web同源Origin/CSRF规则不能原样当作native客户端身份证明**。[可复用native Fetch handler](../examples/embedded-passkey-native-bff.ts)使用同一受测core，但构造时固定 `mode:'native'`、ios / Android `clientContext` 和必填 `verifyNativeCaller` / `authenticateNativeRequest`。该hook验证客户API认证或受保护的匿名bootstrap attempt，配合重放预算及设备策略；不能仅比较请求自报的App ID、package或Origin。native路由不接受Web Origin；浏览器默认路由继续检查同源Origin+CSRF，不允许在请求中切换platform。

原生HTTP transport必须跨begin/finish/202/reset保留客户BFF的opaque Secure / HttpOnly binding cookie jar，并使用客户API自己的受保护凭据；不把Auth service/session/flow token传入App。共享core仍检查短期attempt、预期用户和原子finalize/reset family。Swift / Android的backend transport同时提供list/rename/delete与公有metadata；管理本身不启动OS仪式，增删后的同账户重新认证才调用平台adapter。OS域名关联、当前发行签名和实际设备都要单独核验。服务器接受某一 `app_id` 声明不等于验证了Apple App Attest；Android证书origin也不等于Play Integrity。

本地Android源码已使用临时JDK17、Kotlin2.1.20、Google credentials1.5.0与Android15/API35 android-all实编译，并运行JVM wire tests；这不等于Gradle / APK构建、Android系统CredentialManager调用或设备UI验收。Swift的真实AuthenticationServices库以macOS13 deployment target编译；CLT环境缺少XCTest，标准XCTest测试源码保留，独立SwiftPackage executable用于执行无设备的codec / 公有options / pending / 管理metadata检查。具体最终数量以本轮报告为准。

本地编译、虚拟浏览器、软件签名和序列化测试仅证明各自覆盖范围。真实Touch ID/Face ID/Windows Hello、硬件密钥、iCloud/Google同步、手机跨设备扫码、实际AASA/DAL网络发布、生产配置、npm0.7.0发布和客户业务接入仍需独立证据。
