@oxy.so/core 1.13.0 → 1.18.0

package/src/i18n/locales/zh-CN.json

@@ -1,53 +1,48 @@
 {
   "signin": {
     "title": "登录",
-    "subtitle": "登录以继续",
-    "addAccountTitle": "添加另一个账户",
+    "subtitle": "使用你的 Oxy 账号",
+    "addAccountTitle": "添加其他账号",
     "addAccountSubtitle": "使用另一个账户登录",
     "username": {
       "label": "用户名",
-      "placeholder": "输入您的用户名",
-      "helper": "3-30个字符，仅字母和数字",
-      "required": "请输入您的用户名。",
-      "minLength": "用户名必须至少包含3个字符。"
-    },
-    "password": {
-      "label": "密码",
-      "placeholder": "输入您的密码",
-      "required": "请输入您的密码。",
-      "hint": "输入您的密码以登录"
+      "placeholder": "yourname",
+      "required": "请输入您的用户名。"
     },
     "actions": {
       "continue": "继续",
-      "back": "返回",
-      "signIn": "登录",
-      "verify": "验证",
-      "openAccountSwitcher": "切换到另一个账户",
-      "openAccountSwitcherSubtitle": "{{count}}个其他账户可用",
-      "openAccountSwitcherSubtitle_singular": "1个其他账户可用",
-      "openAccountSwitcherSubtitle_zero": "查看您保存的账户",
-      "manageAccounts": "管理保存的账户",
-      "manageAccountsSubtitle": "查看会话、删除或登出",
-      "loadingOtherAccounts": "加载其他账户中…",
-      "switchAccountFailed": "无法切换账户。请重试。"
+      "back": "返回"
     },
-    "forgotPrompt": "忘记密码？",
-    "security": {
-      "dataSecure": "您的数据已加密且安全"
-    },
-    "currentlySignedInAs": "当前登录为",
-    "alreadySignedInWith": "已登录",
-    "alreadySignedIn": "已登录",
-    "alreadySignedInMessage": "此账户已登录。继续使用此账户？",
-    "continueWithAccount": "继续",
-    "currentAccount": "当前",
-    "or": "或",
-    "viewAllAccounts": "查看更多{{count}}个",
     "createAccountLink": "初次使用 Oxy？创建账户",
     "status": {
-      "accountSwitched": "正在使用{{name}}",
       "signingIn": "正在登录…"
-    }
+    },
+    "subtitleToApp": "以继续前往 {{app}}",
+    "orContinueWith": "或使用以下方式继续",
+    "qr": {
+      "caption": "使用 Commons 扫码登录",
+      "renew": "显示新的二维码"
+    },
+    "methods": {
+      "passkey": "使用通行密钥登录"
+    },
+    "errors": {
+      "rateLimited": "尝试次数过多。请在 {{seconds}} 秒后重试。",
+      "passkeyCancelled": "通行密钥提示已关闭。准备好后请重试。",
+      "passkeyFailed": "无法完成通行密钥验证。请重试。"
+    },
+    "chooser": {
+      "subtitleToApp": "以继续前往 {{app}}"
+    },
+    "terms": {
+      "before": "继续即表示你同意我们的",
+      "termsLink": "服务条款",
+      "and": "和",
+      "privacyLink": "隐私政策"
+    },
+    "noAccount": "还没有账号？",
+    "createAccount": "创建账号",
+    "recoverLink": "丢失了通行密钥？恢复你的账号"
   },
   "signup": {
     "title": "创建您的账户",
@@ -55,56 +50,28 @@
     "createInCommons": "在 Commons 中创建您的身份",
     "createAccount": "创建账户",
     "backToSignInLink": "已有账户？登录",
-    "welcome": {
-      "title": "欢迎使用Oxy！",
-      "subtitle": "只需几步即可创建您的账户",
-      "haveAccount": "已有账户？",
-      "signInCta": "登录"
-    },
-    "identity": {
-      "title": "您是谁？",
-      "subtitle": "选择您的用户名并输入您的电子邮件"
-    },
+    "webSubtitle": "无需密码：你的设备会创建一个通行密钥，丢失时可通过恢复邮箱重新进入。",
     "username": {
-      "helper": "3-30个字符，仅字母和数字",
-      "required": "请输入用户名",
-      "minLength": "用户名必须至少包含3个字符"
+      "label": "用户名",
+      "placeholder": "yourname",
+      "required": "请选择用户名。",
+      "taken": "该用户名已被占用。"
     },
     "email": {
-      "required": "请输入电子邮件地址",
-      "invalid": "请输入有效的电子邮件地址",
-      "helper": "我们绝不会分享您的电子邮件"
-    },
-    "security": {
-      "title": "保护您的账户",
-      "subtitle": "创建强密码以保护您的账户"
+      "title": "你的恢复邮箱",
+      "subtitle": "如果你丢失了通行密钥，我们会向这里发送验证码让你重新进入。它不作其他用途。",
+      "label": "邮箱",
+      "placeholder": "you@example.com",
+      "invalid": "请输入有效的邮箱地址。"
     },
-    "password": {
-      "helper": "至少8个字符",
-      "required": "请输入密码",
-      "minLength": "密码必须至少包含8个字符",
-      "confirmRequired": "请确认您的密码",
-      "mismatch": "密码不匹配",
-      "confirmHint": "重新输入您的密码以确认"
+    "passkey": {
+      "title": "创建你的通行密钥",
+      "subtitle": "用指纹、面容或屏幕锁登录，无需记住任何东西。",
+      "action": "创建通行密钥"
     },
-    "summary": {
-      "title": "快完成了！",
-      "subtitle": "查看您的信息并创建账户",
-      "sectionTitle": "账户信息",
-      "fields": {
-        "username": "用户名",
-        "email": "电子邮件",
-        "password": "密码"
-      },
-      "notSet": "未设置",
-      "securityTip": "为了更强的安全性，创建账户后，请在账户设置中启用生物识别身份验证。",
-      "legalReminder": "创建账户即表示您同意我们的服务条款和隐私政策。"
-    }
+    "commonsInstead": "想自己保管密钥？改用 Commons"
   },
   "accountSwitcher": {
-    "sections": {
-      "yourAccounts": "你的账户"
-    },
     "loading": "正在加载账户...",
     "qrHeadline": "使用您的 Oxy 身份登录",
     "signInWithOxy": "使用 Oxy 登录",
@@ -136,10 +103,7 @@
       "claimFailed": "登录已获批准，但未能完成。请重试。",
       "generic": "登录失败，请重试。"
     },
-    "linkOpenFailed": "无法打开链接，请重试。",
-    "continueWithPasskey": "继续",
-    "passkeyHint": "使用指纹、面容或设备 PIN 码。",
-    "otherDeviceCommons": "账号在其他设备上？用 Commons 扫码"
+    "linkOpenFailed": "无法打开链接，请重试。"
   },
   "common": {
     "actions": {
@@ -280,7 +244,63 @@
     "help": "帮助与反馈",
     "signOut": "退出登录",
     "privacy": "隐私政策",
-    "terms": "服务条款",
-    "identity": "你的身份"
+    "terms": "服务条款"
+  },
+  "recover": {
+    "title": "恢复你的账户",
+    "subtitle": "输入你的用户名或恢复邮箱。我们会向该账户的恢复邮箱发送验证码。",
+    "identifier": {
+      "label": "用户名或邮箱",
+      "placeholder": "yourname",
+      "required": "请输入用户名或邮箱。"
+    },
+    "commonsNote": "你的账户使用 Commons？请在 Commons 中用恢复短语恢复。",
+    "passkey": {
+      "title": "添加新的通行密钥",
+      "subtitle": "用于 @{{username}}。丢失的通行密钥可稍后在账户安全设置中移除。",
+      "action": "创建通行密钥"
+    },
+    "backToSignIn": "返回登录"
+  },
+  "emailCode": {
+    "title": "查看你的邮箱",
+    "sentTo": "我们已向 {{email}} 发送了 6 位验证码。",
+    "sentIfAccount": "如果该账户有恢复邮箱，我们已向其发送 6 位验证码。",
+    "label": "验证码",
+    "resend": "发送新验证码",
+    "resent": "我们已发送新验证码。",
+    "changeEmail": "使用其他邮箱",
+    "errors": {
+      "codeInvalid": "验证码不正确或已过期。",
+      "tooManyAttempts": "错误次数过多，请重新获取验证码。",
+      "expired": "耗时过长，请重新开始。",
+      "unavailable": "Oxy 暂时无法发送邮件，请稍后再试。",
+      "rateLimited": "验证码请求过多，请稍后再试。"
+    }
+  },
+  "deleteAccount": {
+    "passkey": {
+      "subtitle": "请用通行密钥确认。@{{username}} 及其中的一切将被永久删除。",
+      "action": "用通行密钥删除",
+      "done": "你的账户已删除。",
+      "closeWindow": "你可以关闭此窗口。",
+      "commons": "此账户使用 Commons：请在 Oxy Commons 的“设置 > 删除账户”中用其密钥删除。"
+    }
+  },
+  "linkCommons": {
+    "title": "关联 Commons",
+    "subtitle": "自己保管密钥：关联 Commons 后，此账户只属于你。它的恢复邮箱会被删除，今后用 Commons 中的恢复短语找回账户。",
+    "scan": "在手机上打开 Commons，选择“我在网页上有 Oxy 账户”，然后扫描此码。",
+    "waiting": "正在等待 Commons…",
+    "compareTitle": "核对代码",
+    "compare": "Commons 会显示相同的代码。如果不同，请取消。",
+    "confirm": "是的，关联 Commons",
+    "cancel": "取消",
+    "doneTitle": "Commons 已关联",
+    "done": "此账户现在由你自己保管。它的恢复邮箱已删除：今后用 Commons 中的恢复短语找回账户。",
+    "already": "此账户已在使用 Commons。",
+    "expired": "此代码已过期。",
+    "renew": "显示新代码",
+    "failed": "无法关联 Commons，请重试。"
   }
 }

package/src/index.ts

@@ -344,55 +344,11 @@ export {
 export type { AeadResult } from './crypto/aead';
 export { deriveSharedSecret } from './crypto/ecdh';
 
-// Web identity holder — the same root as Commons, sealed under a passkey's PRF
-// output; identity proofs; transfer to Commons (docs/adr/0024-one-oxy-account-root-holders.md)
-export {
-    WEB_IDENTITY_PRF_INPUT,
-    WebIdentityUnlockError,
-    WEB_IDENTITY_PRF_OUTPUT_LENGTH,
-    addWrap,
-    deriveIdentityFromMnemonic,
-    deriveIdentityFromPrivateKey,
-    deriveIdentityFromRecoveryMaterial,
-    deriveKeyEncryptionKey,
-    generateDataKey,
-    generateWebIdentity,
-    isUsablePrfOutput,
-    markWrapVerified,
-    normalizeMnemonic,
-    openWebIdentity,
-    parseRecoveryMaterial,
-    removeWrap,
-    sealWebIdentity,
-    unlockWebIdentity,
-    unwrapDataKey,
-    wipeBytes,
-    wipeOpenedIdentity,
-} from './crypto/webIdentityCarrier';
-export type {
-    OpenedMnemonicIdentity,
-    OpenedRawKeyIdentity,
-    OpenedWebIdentity,
-    WebIdentityRecoveryMaterial,
-    WebIdentityUnlockFailure,
-    WrapInput,
-} from './crypto/webIdentityCarrier';
+// Identity proofs — the one signed format for operations on a personal root
+// (docs/adr/0024-one-oxy-account-root-holders.md D7)
 export { digestIdentityPayload, signIdentityProof } from './crypto/identityProof';
-export {
-    buildMoveQrPayload,
-    createMoveCommitment,
-    deriveMoveKey,
-    deriveMoveSas,
-    digestMoveCiphertext,
-    generateMoveEphemeralKeyPair,
-    openMovedIdentity,
-    parseMoveQrPayload,
-    sealIdentityForMove,
-    signMoveReceipt,
-    verifyMoveCommitment,
-    verifyMoveReceipt,
-} from './crypto/identityMove';
-export type { MoveReceiptClaims } from './crypto/identityMove';
+// Linking Commons to a passkey account: the code both screens compare (ADR 0029 D3)
+export { deriveIdentityLinkCode } from './crypto/identityLink';
 
 // ---------------------------------------------------------------------------
 // Devices
@@ -411,6 +367,8 @@ export type {
     User,
     LoginResponse,
     Notification,
+    NotificationActor,
+    NotificationPage,
     Wallet,
     Transaction,
     BlockedUser,
@@ -682,7 +640,7 @@ export type { QuickAccount, DisplayNameUserShape } from './utils/accountUtils';
 // `*.oxy.so`).
 // ---------------------------------------------------------------------------
 export { registrableApex } from './utils/registrableApex';
-export { CENTRAL_IDP_APEX, IDENTITY_WEB_ORIGIN } from './utils/authWebUrl';
+export { AUTH_WEB_ORIGIN, CENTRAL_IDP_APEX } from './utils/authWebUrl';
 
 // WebAuthn relying-party origin guard (client side). Mirrors the server's
 // `isOxyApexOrigin` so consumers can decide whether to offer passkey UI on the
@@ -722,7 +680,7 @@ export {
     persistOAuthReturnPath,
     consumeOAuthReturnPath,
 } from './utils/oauthPkce';
-export type { PkcePair, BuildOAuthAuthorizeUrlParams } from './utils/oauthPkce';
+export type { PkcePair, BuildOAuthAuthorizeUrlParams, OxyAuthScreen } from './utils/oauthPkce';
 
 export {
     isLoopbackOrigin,
@@ -827,7 +785,6 @@ export type {
     AccountDialogView,
     CommonsAvailability,
     ContextChoiceOutcome,
-    PopupWindowHandle,
     SignInFailureReason,
     SignInFlowPhase,
     SignInFlowState,

package/src/mixins/OxyServices.auth.ts

@@ -9,7 +9,15 @@ import type {
   LoginResult,
   CommonsDenyReason,
 } from '@oxy.so/contracts';
-import { loginResultSchema, safeParseContract, type IdentityProof, type WebIdentityEnvelope } from '@oxy.so/contracts';
+import {
+  emailVerificationConfirmResponseSchema,
+  emailVerificationStartResponseSchema,
+  loginResultSchema,
+  safeParseContract,
+  type EmailVerificationConfirmResponse,
+  type EmailVerificationStartRequest,
+  type EmailVerificationStartResponse,
+} from '@oxy.so/contracts';
 import type { SessionLoginResponse } from '../models/session';
 import type { OxyServicesBase } from '../OxyServices.base';
 import type { PublicApplication } from './OxyServices.connectedApps';
@@ -1692,12 +1700,43 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
     }
 
     /**
-     * Check email availability
+     * Send a 6-digit code to an email (ADR 0029 D3): the recovery email of a
+     * new passkey account (`purpose: 'signup'`), or — named by username or
+     * email — the recovery email of an account being recovered
+     * (`purpose: 'recovery'`). The answer is the same whether or not an
+     * account exists; nothing is revealed about who has one.
      */
-    async checkEmailAvailability(email: string): Promise<{ available: boolean; message: string }> {
+    async startEmailVerification(request: EmailVerificationStartRequest): Promise<EmailVerificationStartResponse> {
       try {
-        // Public availability lookup (pre-session) — skip the bearer preflight.
-        return await this.makeRequest('GET', `/auth/check-email/${email}`, undefined, { cache: false, skipAuth: true });
+        const res = await this.makeRequest<unknown>('POST', '/auth/email/verify/start', request, {
+          cache: false,
+          skipAuth: true,
+        });
+        const parsed = safeParseContract(emailVerificationStartResponseSchema, res);
+        if (!parsed) throw new Error('auth/email/verify/start returned an unexpected response shape');
+        return parsed;
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Confirm the code {@link startEmailVerification} sent. Resolves to a
+     * short-lived one-use ticket: a sign-up passes it (with the email) to
+     * {@link webauthnRegisterVerify}; a recovery passes it as `recoveryTicket`
+     * to {@link webauthnRegisterOptions} and {@link webauthnRegisterVerify}.
+     */
+    async confirmEmailVerification(verificationId: string, code: string): Promise<EmailVerificationConfirmResponse> {
+      try {
+        const res = await this.makeRequest<unknown>(
+          'POST',
+          '/auth/email/verify/confirm',
+          { verificationId, code },
+          { cache: false, skipAuth: true },
+        );
+        const parsed = safeParseContract(emailVerificationConfirmResponseSchema, res);
+        if (!parsed) throw new Error('auth/email/verify/confirm returned an unexpected response shape');
+        return parsed;
       } catch (error) {
         throw this.handleError(error);
       }
@@ -1708,19 +1747,24 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
      * `PublicKeyCredentialCreationOptions` the browser's `navigator.credentials
      * .create()` (or `@simplewebauthn/browser`'s `startRegistration`) needs.
      *
-     * With a bearer token planted this links a passkey to the signed-in account
-     * (`username` ignored); without one it is a prospective signup and `username`
-     * is the desired handle. The returned options are OPAQUE — Oxy does not own
-     * their shape (the browser / `@simplewebauthn` does), so they pass through
-     * as `unknown` for the caller to hand straight to the ceremony.
+     * With a bearer token planted this adds a passkey to the signed-in account.
+     * Without one, `username` is a prospective sign-up's handle, and
+     * `recoveryTicket` a recovery's new passkey for the account it names. The
+     * returned options are OPAQUE — Oxy does not own their shape (the browser /
+     * `@simplewebauthn` does), so they pass through as `unknown` for the caller
+     * to hand straight to the ceremony.
      */
-    async webauthnRegisterOptions(username?: string): Promise<unknown> {
+    async webauthnRegisterOptions(request: { username?: string; recoveryTicket?: string } = {}): Promise<unknown> {
+      const signedOut = request.username !== undefined || request.recoveryTicket !== undefined;
       try {
         return await this.makeRequest<unknown>(
           'POST',
           '/auth/webauthn/register/options',
-          { ...(username !== undefined ? { username } : {}) },
-          { cache: false, ...(username !== undefined ? { skipAuth: true } : {}) },
+          {
+            ...(request.username !== undefined ? { username: request.username } : {}),
+            ...(request.recoveryTicket !== undefined ? { recoveryTicket: request.recoveryTicket } : {}),
+          },
+          { cache: false, ...(signedOut ? { skipAuth: true } : {}) },
         );
       } catch (error) {
         throw this.handleError(error);
@@ -1732,10 +1776,12 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
      * browser `RegistrationResponseJSON` (`response`) alongside the Oxy envelope
      * (desired `username` for signup + the device-session naming fields).
      *
-     * Two server branches, disambiguated by the response shape:
-     *  - **Signup** (no bearer): the account is created and a session minted —
-     *    the response carries `sessionId`, is the SAME {@link LoginResult}
-     *    contract as `POST /auth/verify`, and its access token is planted here.
+     * Server branches, disambiguated by the response shape:
+     *  - **Sign-up** (no bearer; `username`, `email`, `emailTicket`) and
+     *    **recovery** (no bearer; `recoveryTicket`): the account is created, or
+     *    gains the passkey, and a session is minted — the response carries
+     *    `sessionId`, is the SAME {@link LoginResult} contract as
+     *    `POST /auth/verify`, and its access token is planted here.
      *  - **Link** (bearer present): the passkey is attached to the signed-in
      *    account and the server returns `{ success, message }` with no session,
      *    which is returned verbatim (no token planting).
@@ -1744,14 +1790,13 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
       response: unknown,
       envelope: {
         username?: string;
+        /** Sign-up: the recovery email, confirmed with `emailTicket`. */
+        email?: string;
+        emailTicket?: string;
+        /** Recovery: the ticket {@link confirmEmailVerification} returned. */
+        recoveryTicket?: string;
         deviceName?: string;
         deviceFingerprint?: string;
-        /**
-         * Sign-up only: the root created on the holder before this call, sealed
-         * under the passkey being registered, plus its `enroll_identity` proof
-         * (ADR 0024 D4). The account is created WITH it or not at all.
-         */
-        identity?: { envelope: WebIdentityEnvelope; proof: IdentityProof };
       } = {},
     ): Promise<{ success: true; message: string } | LoginResult> {
       try {
@@ -1759,7 +1804,10 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
           'POST',
           '/auth/webauthn/register/verify',
           { response, ...envelope },
-          { cache: false, ...(envelope.username !== undefined ? { skipAuth: true } : {}) },
+          {
+            cache: false,
+            ...(envelope.username !== undefined || envelope.recoveryTicket !== undefined ? { skipAuth: true } : {}),
+          },
         );
         if (res && typeof res === 'object') {
           const record = res as Record<string, unknown>;

package/src/mixins/OxyServices.identity.ts

@@ -23,8 +23,16 @@
  * on-device identity and throw on web (where `KeyManager.getPublicKey()` is
  * always `null`).
  */
+import {
+  IDENTITY_PROOF_ACTIONS,
+  identityLinkCreateResponseSchema,
+  identityLinkStateSchema,
+  safeParseContract,
+} from '@oxy.so/contracts';
 import type {
   AuthMethodsResponse,
+  IdentityLinkCreateResponse,
+  IdentityLinkState,
   IdentityRootStatus,
   DidDocument,
   DomainVerificationInstructions,
@@ -38,6 +46,8 @@ import type {
 import { signMessage } from '@oxy.so/protocol';
 import type { OxyServicesBase } from '../OxyServices.base';
 import { KeyManager } from '../crypto/keyManager';
+import { deriveIdentityLinkCode } from '../crypto/identityLink';
+import { signIdentityProof } from '../crypto/identityProof';
 import { SignatureService } from '../crypto/signatureService';
 import { RecoveryPhraseService, type PendingIdentityResult } from '../crypto/recoveryPhrase';
 import { isWeb } from '../utils/platform';
@@ -219,11 +229,9 @@ export function OxyServicesIdentityMixin<T extends typeof OxyServicesBase>(Base:
     }
 
     /**
-     * The signed-in account's root readiness (ADR 0024 D5): whether a root is
-     * linked, how many passkeys can open the web holder, whether the root has a
-     * phrase and whether it is saved and was shown to recover it. Metadata only —
-     * nothing here can open the root — so any first-party surface may show a
-     * "save your recovery phrase" reminder from it.
+     * How the signed-in account is kept (ADR 0029 D3): whether Commons' root is
+     * linked (self-custody), or the recovery email of a passkey account. Any
+     * first-party surface may read it to recommend linking Commons.
      */
     async getIdentityRootStatus(): Promise<IdentityRootStatus> {
       try {
@@ -233,15 +241,125 @@ export function OxyServicesIdentityMixin<T extends typeof OxyServicesBase>(Base:
       }
     }
 
+    /**
+     * Open a request to link Commons to the signed-in passkey account (ADR 0029
+     * D3). auth.oxy.so shows its `qrPayload`; Commons scans it and signs with
+     * {@link signIdentityLink}.
+     */
+    async createIdentityLink(): Promise<IdentityLinkCreateResponse> {
+      try {
+        const res = await this.makeRequest<unknown>('POST', '/identity/link', undefined, { cache: false });
+        const parsed = safeParseContract(identityLinkCreateResponseSchema, res);
+        if (!parsed) throw new Error('identity/link returned an unexpected response shape');
+        return parsed;
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /** Where a link request stands. Both devices poll it; it needs no session. */
+    async getIdentityLink(linkId: string): Promise<IdentityLinkState> {
+      try {
+        const res = await this.makeRequest<unknown>('GET', `/identity/link/${encodeURIComponent(linkId)}`, undefined, {
+          cache: false,
+          skipAuth: true,
+        });
+        const parsed = safeParseContract(identityLinkStateSchema, res);
+        if (!parsed) throw new Error('identity/link returned an unexpected response shape');
+        return parsed;
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Commons' half: sign the scanned request's `link_identity` proof with THIS
+     * device's identity key and post it. NATIVE-ONLY (the key lives in native
+     * secure storage). Resolves to the key and the 6-digit code auth.oxy.so will
+     * show for it, for the person to compare.
+     */
+    async signIdentityLink(linkId: string, challenge: string): Promise<{ publicKey: string; code: string; username: string | null }> {
+      try {
+        const [privateKey, publicKey] = await Promise.all([KeyManager.getPrivateKey(), KeyManager.getPublicKey()]);
+        if (!privateKey || !publicKey) {
+          throw new Error('No identity on this device to link');
+        }
+        const root = publicKey.trim().toLowerCase();
+        const state = await this.getIdentityLink(linkId);
+        const proof = await signIdentityProof(
+          { privateKey, publicKey: root },
+          {
+            action: IDENTITY_PROOF_ACTIONS.link,
+            subject: state.userId,
+            actor: state.userId,
+            rootPublicKey: root,
+            payloadDigest: null,
+            expectedRevision: null,
+            audience: state.audience,
+            challenge,
+            expiresAt: state.expiresAt,
+          },
+        );
+        await this.makeRequest<unknown>(
+          'POST',
+          `/identity/link/${encodeURIComponent(linkId)}/proof`,
+          { publicKey: root, proof },
+          { cache: false, skipAuth: true },
+        );
+        return { publicKey: root, code: deriveIdentityLinkCode(linkId, root), username: state.username };
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /** WebAuthn request options over the account's passkeys, whose challenge is the link's. Opaque. */
+    async getIdentityLinkAssertionOptions(linkId: string, challenge: string): Promise<unknown> {
+      try {
+        return await this.makeRequest<unknown>(
+          'POST',
+          `/identity/link/${encodeURIComponent(linkId)}/options`,
+          { challenge },
+          { cache: false },
+        );
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * auth.oxy.so's half: the passkey assertion over the link's challenge. The
+     * account gains Commons' root and loses its recovery email.
+     */
+    async completeIdentityLink(linkId: string, assertion: unknown): Promise<{ success: true }> {
+      try {
+        const result = await this.makeRequest<{ success: true }>(
+          'POST',
+          `/identity/link/${encodeURIComponent(linkId)}/complete`,
+          { assertion },
+          { cache: false },
+        );
+        this._invalidateIdentityCaches(this.getCurrentUserId());
+        return result;
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /** Withdraw a link request that has not completed. */
+    async cancelIdentityLink(linkId: string): Promise<void> {
+      try {
+        await this.makeRequest<unknown>('DELETE', `/identity/link/${encodeURIComponent(linkId)}`, undefined, { cache: false });
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
     /**
      * Remove ONE passkey (WebAuthn credential) from the current account.
      *
      * Passkeys are per-credential, so this targets a specific credential id.
      * The server refuses to remove the last remaining auth method (the account
      * would become inaccessible) and deletes the stored `WebauthnCredential`.
-     * A passkey that also opens the account's root on the web takes its wrap with
-     * it, and the ONLY such passkey is refused with
-     * `code: 'IDENTITY_LAST_WEB_HOLDER'` (ADR 0024 D6).
      *
      * @param credentialId - The passkey's public credential id
      *   (`AuthMethodEntry.credentialId`).