`identity`

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

基本示例

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

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

login() 完成表示平台流程结束；应用应重新调用 status()，而不是从回跳 URL 或隐藏载荷推断身份。

适用场景

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

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

能力声明

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

Reference

identity.status() -> { authenticated: boolean }
identity.login() -> void
identity.logout() -> void

纯 { ok: true } 确认不算信息回程；方法不得把 token、checkout URL、全局 ID 或用户资料夹带在返回值中。

登录流程

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

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

退出示例

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

一次应用调用不能无确认地销毁所有应用、所有设备或平台账户的全局会话。

原生 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 的布尔状态。
登录授权不会把外部身份资料的来源改成 app-context；v0.1 因此根本不返回这些资料。
不回落 email 作为显示名。
不把全局 ID 做普通哈希充当假名；无密钥派生仍可直接比较或枚举关联。
登录 nonce 单次使用、短期有效并绑定 appId 与流程实例。
审计只记录流程和结果，不向 guest 返回账户标识。

错误与测试

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