`identity` 非正式提议

本页不属于任何正式 Host API 版本，名字、边界和签名均未冻结。当前宿主只有全局账户流程，会投影全局 ID、显示名或 email，且没有 appId 绑定的单次回跳 nonce；在新的可信壳层流程完成端到端验证前，本提议不得进入 manifest、SDK 或运行时能力表。

identity 让 guest 知道“用户是否已在本应用中完成平台登录”，并触发由可信壳层完成的登录或退出流程。候选契约不向 guest 暴露全局用户对象、email、显示名、token 或可跨应用关联的 ID。

基本示例

const { authenticated } = await host.identity.status();

if (!authenticated) {
  showSignInButton(async () => {
    const result = await host.identity.login();
    if (result) renderSignedInState();
  });
}

login() 返回封闭状态或 null；应用仍可重新调用 status() 获取当前权威状态，不能从回跳 URL 或隐藏载荷推断身份。

适用场景

决定是否显示需要账户同步的功能。
由用户主动进入平台登录界面。
在可信确认后退出当前定义的应用会话范围。

需要稳定的每应用主体标识、显示名或头像时，必须由后续版本另行授权；不得恢复旧 identity.current()。

L1 边界

宿主独占的是平台账户会话、可信登录 UI、回跳 nonce 和 appId 作用域的撤销效果。guest 无法自行建立平台会话；个人资料、账户页面、权限模型和同步身份映射不属于这个最小能力。

能力声明

{
  "capabilities": [
    "host:identity.status",
    "host:identity.login",
    "host:identity.logout"
  ]
}

Reference

identity.status() -> { authenticated: boolean }
identity.login() -> { authenticated: true } | null
identity.logout() -> { authenticated: false } | null

返回值只允许上面的单一布尔字面量或 null；方法不得把 token、URL、全局 ID 或用户资料夹带在返回值中。

登录流程

guest 在用户点击后调用 login()。
宿主显示带应用身份的可信登录 UI。
平台完成 Passkey 或其他账户流程。
壳层用不可由 guest 构造的 nonce 或固定回跳位置恢复应用。
guest 重新调用 status()。

guest 不传 returnTo、URL、provider token 或任意字符串载荷。

两种流程先在一次线性化读取中检查当前 appId 状态：login() 已为 true 时直接返回 { authenticated: true }，logout() 已为 false 时直接返回 { authenticated: false }；两种无操作路径仍要求可信用户激活，但不打开 UI、不消耗 identity.flowsPerMinute。需要改变状态时才打开可信 UI，并在提交点原子改变 appId 状态。

退出示例

async function signOut() {
  // 宿主仍会显示可信确认，并明确影响范围。
  await host.identity.logout();
  const state = await host.identity.status();
  if (state.authenticated) throw new Error('sign-out did not complete');
}

候选契约的 logout() 只撤销当前 appId 的应用会话。它不得销毁其他应用、其他设备或平台网站的全局会话；更广范围的退出不属于 Host API 候选契约。

原生 WASM 示例

IdentityStatus state = host_identity_status();
if (!state.authenticated && user_pressed_login()) {
  host_identity_login();
  state = host_identity_status();
}

原生 guest 在加载完成后通过普通调用触发流程；宿主不能依赖 guest 在加载前注册特殊回跳处理器。

平台托管条件

三种方法固定为 green。符合候选契约的实现必须逐方法满足：目的地固定、输入形状封闭、容量与速率有预算、guest 无额外响应通道、操作有披露与审计。登录/退出还必须有真实的用户激活闸门和可信 UI；缺任一项就是不支持候选契约，而不是运行时把同名方法临时降档。

任何实现若把完整 location.href、全局用户信息或自由 guest 字符串带入平台流程，都不符合本提议，不能以同名方法配合另一档位继续发布。

安全与预算

status 返回 app-context 的布尔状态。
该布尔值由平台在当前 appId 的会话状态变化时物化；status() 不得在调用时读取并投影全局用户对象。
登录授权不会把外部身份资料的来源改成 app-context；候选契约因此根本不返回这些资料。
不回落 email 作为显示名。
不把全局 ID 做普通哈希充当假名；无密钥派生仍可直接比较或枚举关联。
登录 nonce 单次使用、短期有效并绑定 appId 与流程实例。
登录成功只建立当前 appId 的应用会话；退出只撤销同一作用域。平台网站和其他应用会话均不受影响。
审计只记录流程和结果，不向 guest 返回账户标识。
候选契约预算键为 identity.flowsPerMinute，统计 login/logout 可信流程的启动次数。

错误与测试

用户关闭登录或退出确认返回正常取消结果；策略错误使用 activation-required、denied、flow-expired 或 platform-unavailable。一致性测试至少覆盖伪造回跳、重复 nonce、跨应用 nonce、无手势调用、用户取消、全局退出误伤、email 泄露和返回载荷检查。

identity 非正式提议