@oxy.so/core 1.16.0 → 1.18.0

package/dist/types/crypto/identityLink.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The code both screens show while Commons is being linked to a passkey
+ * account (ADR 0029 D3): 6 digits derived from the link request and the key
+ * Commons signed with. auth.oxy.so derives it from the key the API relayed,
+ * Commons from its own; the person checks they match before the passkey is
+ * asserted, so a photographed QR cannot slip another key in.
+ */
+export declare function deriveIdentityLinkCode(linkId: string, publicKey: string): string;

package/dist/types/index.d.ts

@@ -72,14 +72,11 @@ export { hkdfSha256 } from './crypto/kdf';
 export { encryptAead, decryptAead, AEAD_KEY_LENGTH, AEAD_NONCE_LENGTH, } from './crypto/aead';
 export type { AeadResult } from './crypto/aead';
 export { deriveSharedSecret } from './crypto/ecdh';
-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';
 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';
+export { deriveIdentityLinkCode } from './crypto/identityLink';
 export { DeviceManager } from './utils/deviceManager';
 export type { DeviceFingerprint, StoredDeviceInfo } from './utils/deviceManager';
-export type { OxyConfig, PrivacySettings, NotificationPreferences, UserPreferences, User, LoginResponse, Notification, Wallet, Transaction, BlockedUser, RestrictedUser, TransferFundsRequest, PurchaseRequest, WithdrawalRequest, TransactionResponse, PaginationInfo, SearchProfilesResponse, ApiError, PaymentMethod, PaymentRequest, PaymentResponse, AnalyticsData, FollowerDetails, ContentViewer, FileMetadata, FileUploadResponse, FileListResponse, FileUpdateRequest, FileDeleteResponse, RNFileDescriptor, AssetUploadInput, FileVisibility, AssetLink, AssetMetadata, AssetVariant, Asset, AssetInitRequest, AssetInitResponse, AssetCompleteRequest, AssetLinkRequest, AssetUnlinkRequest, AssetUrlResponse, BatchFileAccessEntry, BatchFileAccessResponse, AssetDeleteSummary, AssetUpdateVisibilityRequest, AssetUpdateVisibilityResponse, ServiceAssetMetadata, ServiceAssetMetadataBySha, AccountStorageCategoryUsage, AccountStorageUsageResponse, SecurityEventType, SecurityEventSeverity, SecurityActivity, SecurityActivityResponse, AssetUploadProgress, DeviceLinkedSession, DeviceLinkedSessionsResponse, DeviceLinkedSessionLogoutResponse, UpdateDeviceNameResponse, } from './models/interfaces';
+export type { OxyConfig, PrivacySettings, NotificationPreferences, UserPreferences, User, LoginResponse, Notification, NotificationActor, NotificationPage, Wallet, Transaction, BlockedUser, RestrictedUser, TransferFundsRequest, PurchaseRequest, WithdrawalRequest, TransactionResponse, PaginationInfo, SearchProfilesResponse, ApiError, PaymentMethod, PaymentRequest, PaymentResponse, AnalyticsData, FollowerDetails, ContentViewer, FileMetadata, FileUploadResponse, FileListResponse, FileUpdateRequest, FileDeleteResponse, RNFileDescriptor, AssetUploadInput, FileVisibility, AssetLink, AssetMetadata, AssetVariant, Asset, AssetInitRequest, AssetInitResponse, AssetCompleteRequest, AssetLinkRequest, AssetUnlinkRequest, AssetUrlResponse, BatchFileAccessEntry, BatchFileAccessResponse, AssetDeleteSummary, AssetUpdateVisibilityRequest, AssetUpdateVisibilityResponse, ServiceAssetMetadata, ServiceAssetMetadataBySha, AccountStorageCategoryUsage, AccountStorageUsageResponse, SecurityEventType, SecurityEventSeverity, SecurityActivity, SecurityActivityResponse, AssetUploadProgress, DeviceLinkedSession, DeviceLinkedSessionsResponse, DeviceLinkedSessionLogoutResponse, UpdateDeviceNameResponse, } from './models/interfaces';
 export { SECURITY_EVENT_SEVERITY_MAP } from './models/interfaces';
 export { TopicType, TopicSource } from './models/Topic';
 export type { TopicData, TopicTranslation, TopicListResult } from './models/Topic';

package/dist/types/mixins/OxyServices.auth.d.ts

@@ -5,7 +5,7 @@
  */
 import type { User } from '../models/interfaces';
 import type { LoginResult, CommonsDenyReason } from '@oxy.so/contracts';
-import { type IdentityProof, type WebIdentityEnvelope } from '@oxy.so/contracts';
+import { 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';
@@ -790,50 +790,60 @@ export declare function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(B
             message: string;
         }>;
         /**
-         * 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.
          */
-        checkEmailAvailability(email: string): Promise<{
-            available: boolean;
-            message: string;
-        }>;
+        startEmailVerification(request: EmailVerificationStartRequest): Promise<EmailVerificationStartResponse>;
+        /**
+         * 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}.
+         */
+        confirmEmailVerification(verificationId: string, code: string): Promise<EmailVerificationConfirmResponse>;
         /**
          * Begin a WebAuthn / passkey REGISTRATION ceremony. Requests the
          * `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.
          */
-        webauthnRegisterOptions(username?: string): Promise<unknown>;
+        webauthnRegisterOptions(request?: {
+            username?: string;
+            recoveryTicket?: string;
+        }): Promise<unknown>;
         /**
          * Finish a WebAuthn / passkey REGISTRATION ceremony. Forwards the opaque
          * 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).
          */
         webauthnRegisterVerify(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;

package/dist/types/mixins/OxyServices.identity.d.ts

@@ -1,29 +1,4 @@
-/**
- * Identity Methods Mixin (self-sovereign identity layer)
- *
- * Provides typed access to Oxy's AtProto/Bluesky-flavoured identity &
- * portability layer:
- *  - DID resolution (`did:web:oxy.so:u:<userId>`, derived on demand by the API).
- *  - The auth-method ↔ DID verification-method mapping (`GET /auth/methods`) and
- *    passkey removal. A root is linked by the holder flows (ADR 0024) and never
- *    unlinked; it is replaced by rotation.
- *  - Signed records: clients sign an envelope with their own cryptographic key
- *    (`SignatureService.signRecord` + the shared `canonicalize`) and publish it;
- *    anyone can fetch and verify it.
- *  - The signed data-export ("credible exit") bundle.
- *  - Verified-domain badges (prove ownership of `nate.com`).
- *
- * Wire shapes come from `@oxy.so/contracts` (`DidDocument`,
- * `SignedRecordEnvelope`, `AuthMethodsResponse`, `VerifiedDomain`,
- * `DomainVerificationInstructions`, `ExportBundle`) — the single source of truth
- * the API validates its output against, so producer and consumer cannot drift.
- *
- * Identity signing is NATIVE-ONLY: the private key lives in native secure
- * storage, so `signRecord` and `publishRecord` require an
- * on-device identity and throw on web (where `KeyManager.getPublicKey()` is
- * always `null`).
- */
-import type { AuthMethodsResponse, IdentityRootStatus, DidDocument, DomainVerificationInstructions, ExportBundle, OxySignedRecordType, SignedRecordEnvelope, VerifiedDomain } from '@oxy.so/contracts';
+import type { AuthMethodsResponse, IdentityLinkCreateResponse, IdentityLinkState, IdentityRootStatus, DidDocument, DomainVerificationInstructions, ExportBundle, OxySignedRecordType, SignedRecordEnvelope, VerifiedDomain } from '@oxy.so/contracts';
 import type { OxyServicesBase } from '../OxyServices.base';
 import { type PendingIdentityResult } from '../crypto/recoveryPhrase';
 /**
@@ -140,22 +115,47 @@ export declare function OxyServicesIdentityMixin<T extends typeof OxyServicesBas
          */
         listAuthMethods(): Promise<AuthMethodsResponse>;
         /**
-         * 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.
          */
         getIdentityRootStatus(): Promise<IdentityRootStatus>;
+        /**
+         * 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}.
+         */
+        createIdentityLink(): Promise<IdentityLinkCreateResponse>;
+        /** Where a link request stands. Both devices poll it; it needs no session. */
+        getIdentityLink(linkId: string): Promise<IdentityLinkState>;
+        /**
+         * 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.
+         */
+        signIdentityLink(linkId: string, challenge: string): Promise<{
+            publicKey: string;
+            code: string;
+            username: string | null;
+        }>;
+        /** WebAuthn request options over the account's passkeys, whose challenge is the link's. Opaque. */
+        getIdentityLinkAssertionOptions(linkId: string, challenge: string): Promise<unknown>;
+        /**
+         * auth.oxy.so's half: the passkey assertion over the link's challenge. The
+         * account gains Commons' root and loses its recovery email.
+         */
+        completeIdentityLink(linkId: string, assertion: unknown): Promise<{
+            success: true;
+        }>;
+        /** Withdraw a link request that has not completed. */
+        cancelIdentityLink(linkId: string): Promise<void>;
         /**
          * 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`).

package/dist/types/mixins/OxyServices.user.d.ts

@@ -2,7 +2,7 @@
  * User Management Methods Mixin
  */
 import type { CreateOxyNotificationRequest } from '@oxy.so/contracts';
-import type { User, Notification, NotificationPreferences, UserPreferences, SearchProfilesResponse, PrivacySettings } from '../models/interfaces';
+import type { User, Notification, NotificationPage, NotificationPreferences, UserPreferences, SearchProfilesResponse, PrivacySettings } from '../models/interfaces';
 import type { UserNameResponse, UserProfileUpdate, RecommendationRequest, RecommendationItem, ThemePreference } from '@oxy.so/contracts';
 import type { OxyServicesBase } from '../OxyServices.base';
 import { type PaginationParams, type FollowGraphParams } from '../utils/apiUtils';
@@ -350,6 +350,23 @@ export declare function OxyServicesUserMixin<T extends typeof OxyServicesBase>(B
         deleteAccount(confirmText: string): Promise<{
             message: string;
         }>;
+        /**
+         * WebAuthn request options to delete a PASSKEY account (ADR 0029 D3): its own
+         * passkeys, user verification required, and a challenge bound to it. Opaque —
+         * hand them to the browser's authentication ceremony, on auth.oxy.so. An
+         * account with a Commons key deletes with {@link deleteAccount} instead.
+         */
+        getAccountDeletionOptions(): Promise<unknown>;
+        /**
+         * Delete a PASSKEY account permanently, with an assertion by one of its
+         * passkeys over {@link getAccountDeletionOptions}' challenge.
+         *
+         * @param confirmText - Must equal the user's username (verified server-side)
+         * @param assertion - The ceremony's opaque `AuthenticationResponseJSON`
+         */
+        deleteAccountWithPasskey(confirmText: string, assertion: unknown): Promise<{
+            message: string;
+        }>;
         /**
          * Invalidate every cached read a follow/unfollow write invalidates.
          *
@@ -497,9 +514,13 @@ export declare function OxyServicesUserMixin<T extends typeof OxyServicesBase>(B
          */
         getViewerGraph(): Promise<ViewerGraph>;
         /**
-         * Get notifications
+         * One page of the signed-in user's Oxy notifications, newest first
+         * (`GET /notifications`), with the unread count across all pages.
          */
-        getNotifications(): Promise<Notification[]>;
+        getNotifications(params?: {
+            page?: number;
+            limit?: number;
+        }): Promise<NotificationPage>;
         /**
          * Get unread notification count
          */
@@ -511,11 +532,13 @@ export declare function OxyServicesUserMixin<T extends typeof OxyServicesBase>(B
          * from an Oxy service about the recipient's own account, with the recipient
          * as actor and their profile as the entity.
          */
-        createNotification(data: CreateOxyNotificationRequest | Partial<Notification>): Promise<Notification>;
+        createNotification(data: CreateOxyNotificationRequest): Promise<Notification>;
         /**
-         * Mark notification as read
+         * Mark one of the signed-in user's notifications read and return it as
+         * stored. Scoped to the recipient server-side, so it is also the
+         * authoritative read of a notification by id: a foreign or unknown id 404s.
          */
-        markNotificationAsRead(notificationId: string): Promise<void>;
+        markNotificationAsRead(notificationId: string): Promise<Notification>;
         /**
          * Mark all notifications as read
          */

package/dist/types/models/interfaces.d.ts

@@ -1,4 +1,4 @@
-import type { AccountKind, AccountCategoryId, UserNameResponse, UserRelationship, ThemePreference } from '@oxy.so/contracts';
+import type { AccountKind, AccountCategoryId, UserNameResponse, UserRelationship, ThemePreference, OxyNotificationEntityType, OxyNotificationType } from '@oxy.so/contracts';
 export interface OxyConfig {
     baseURL: string;
     cloudURL?: string;
@@ -241,25 +241,58 @@ export interface LoginResponse {
     user: User;
     message?: string;
 }
+/**
+ * The actor of a notification as `GET /notifications` populates it — the raw
+ * stored name, not a composed display name.
+ */
+export interface NotificationActor {
+    _id: string;
+    username?: string;
+    name?: {
+        first: string;
+        last: string;
+    };
+    avatar?: string;
+}
+/**
+ * One Oxy notification exactly as the API serializes it
+ * (`packages/api/src/controllers/notification.controller.ts`). `_id` — not
+ * `id` — is the key every notification endpoint addresses it by.
+ */
 export interface Notification {
-    id: string;
-    message: string;
+    _id: string;
+    recipientId: string;
+    /** Populated on a list read; the bare id on a create or a mark-read. */
+    actorId: string | NotificationActor;
     /** One of `OXY_NOTIFICATION_TYPES` (`@oxy.so/contracts`). */
-    type?: string;
+    type: OxyNotificationType;
+    /**
+     * What `entityId` names: `post` | `reply` | `profile`, or `app` — an opaque id
+     * in the notifying application's namespace (`system` notifications only).
+     */
+    entityType: OxyNotificationEntityType;
+    entityId: string;
     /**
-     * `system` notifications only (with `message`): the text an Oxy service sent
-     * about the recipient's own account. Render these two instead of composing a
-     * sentence from actor + entity.
+     * `system` notifications only: the text an Oxy service sent about the
+     * recipient's own account. Render these instead of composing a sentence from
+     * actor + entity.
      */
     title?: string;
+    message?: string;
     /** `system` notifications only: an optional deep link (https or the sending app's scheme). */
     url?: string;
-    /**
-     * What `entityId` names: `post` | `reply` | `profile`, or `app` — an opaque id
-     * in the notifying application's namespace (`system` notifications only).
-     */
-    entityType?: string;
-    entityId?: string;
+    read: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+/** One page of `GET /notifications`, newest first. */
+export interface NotificationPage {
+    notifications: Notification[];
+    /** Unread notifications across ALL pages. */
+    unreadCount: number;
+    hasMore: boolean;
+    page: number;
+    limit: number;
 }
 export interface Wallet {
     id: string;

package/dist/types/server/securityHeaders.d.ts

@@ -167,9 +167,9 @@ export interface OxyPagesHeadersOptions {
      * violation for a script we never asked for. The rest of the value is Pages'
      * own default, so caching is unchanged.
      *
-     * And, because this origin is the web identity carrier — where a person's
-     * self-custody root is created, opened, recovered and moved (ADR 0028) — the
-     * rest of the holder policy: no `<base>` and no form posts (`base-uri` /
+     * And, because this origin is where a web account is created, recovered and
+     * deleted and every Oxy passkey is asserted (ADR 0028, ADR 0029) — the rest
+     * of the holder policy: no `<base>` and no form posts (`base-uri` /
      * `form-action 'none'`), no Referer to anyone, passkeys for this origin only
      * with every other powerful feature off (`Permissions-Policy`), and its
      * responses readable by no other origin (`Cross-Origin-Resource-Policy`).

package/dist/types/utils/authWebUrl.d.ts

@@ -15,10 +15,9 @@
  */
 export declare const CENTRAL_IDP_APEX = "oxy.so";
 /**
- * The IdP's origin, `auth.oxy.so` — the OAuth authorize/consent surface AND the
- * web identity carrier: where a person signs in or creates an account with a
- * passkey from another origin's popup, and the one origin that may create,
- * open, recover or move their self-custody identity (one identity, two
- * carriers). Apps open it; they never handle the identity themselves.
+ * The IdP's origin, `auth.oxy.so` — the OAuth authorize/consent surface and the
+ * one origin that asserts Oxy passkeys: where a person signs in, creates,
+ * recovers or deletes a web account, in the window an app opens (ADR 0029).
+ * Apps open it; they never run the passkey themselves.
  */
 export declare const AUTH_WEB_ORIGIN = "https://auth.oxy.so";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxy.so/core",
-  "version": "1.16.0",
+  "version": "1.18.0",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -118,8 +118,8 @@
     "@oxy.so/telemetry": "^1.1.1",
     "@noble/ciphers": "^1.3.0",
     "@noble/hashes": "^1.8.0",
-    "@oxy.so/contracts": "^2.0.0",
-    "@oxy.so/protocol": "^1.1.1",
+    "@oxy.so/contracts": "^2.2.0",
+    "@oxy.so/protocol": "^1.1.2",
     "@scure/bip39": "^1.6.0",
     "buffer": "^6.0.3",
     "express-rate-limit": "^8.6.0",

package/src/crypto/__tests__/identityLink.test.ts

@@ -0,0 +1,18 @@
+import { deriveIdentityLinkCode } from '../identityLink';
+
+const LINK_ID = 'ab'.repeat(16);
+const KEY = `04${'1f'.repeat(64)}`;
+
+describe('deriveIdentityLinkCode', () => {
+  it('is 6 digits, the same on both devices whatever the key spelling', () => {
+    const code = deriveIdentityLinkCode(LINK_ID, KEY);
+    expect(code).toMatch(/^\d{6}$/);
+    expect(deriveIdentityLinkCode(LINK_ID, ` ${KEY.toUpperCase()} `)).toBe(code);
+  });
+
+  it('changes with the key and with the request', () => {
+    const code = deriveIdentityLinkCode(LINK_ID, KEY);
+    expect(deriveIdentityLinkCode(LINK_ID, `04${'2e'.repeat(64)}`)).not.toBe(code);
+    expect(deriveIdentityLinkCode('cd'.repeat(16), KEY)).not.toBe(code);
+  });
+});

package/src/crypto/__tests__/identityProof.test.ts

@@ -6,12 +6,13 @@
 import { buildIdentityProofMessage, canonicalJson, type IdentityProofClaims } from '@oxy.so/contracts';
 import { verifySignature } from '@oxy.so/protocol';
 import { digestIdentityPayload, signIdentityProof } from '../identityProof';
-import { deriveIdentityFromMnemonic } from '../webIdentityCarrier';
+import { deriveSecp256k1PublicKey } from '@oxy.so/protocol/secp256k1';
 
-const identity = deriveIdentityFromMnemonic('abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about');
+const keyPair = (privateKey: string) => ({ privateKey, publicKey: deriveSecp256k1PublicKey(privateKey) });
+const identity = keyPair('11'.repeat(32));
 
 const claims = (overrides: Partial<IdentityProofClaims> = {}): IdentityProofClaims => ({
-  action: 'web_envelope_put',
+  action: 'link_identity',
   subject: 'user-1',
   actor: 'user-1',
   rootPublicKey: identity.publicKey,
@@ -42,7 +43,7 @@ describe('canonical JSON', () => {
 describe('the signed bytes', () => {
   it('are a fixed, versioned, domain-separated shape', () => {
     expect(buildIdentityProofMessage(claims())).toBe(
-      `{"action":"web_envelope_put","actor":"user-1","audience":"oxy-api/identity","challenge":"${'ab'.repeat(32)}","domain":"oxy-identity-proof","expectedRevision":3,"expiresAt":1800000000000,"payloadDigest":"${claims().payloadDigest}","rootPublicKey":"${identity.publicKey}","subject":"user-1","v":2}`,
+      `{"action":"link_identity","actor":"user-1","audience":"oxy-api/identity","challenge":"${'ab'.repeat(32)}","domain":"oxy-identity-proof","expectedRevision":3,"expiresAt":1800000000000,"payloadDigest":"${claims().payloadDigest}","rootPublicKey":"${identity.publicKey}","subject":"user-1","v":2}`,
     );
   });
 
@@ -61,7 +62,6 @@ describe('signing', () => {
 
     expect(await verifySignature(buildIdentityProofMessage(claims()), proof.signature, identity.publicKey)).toBe(true);
     for (const changed of [
-      claims({ action: 'web_envelope_delete' }),
       claims({ subject: 'user-2' }),
       claims({ actor: 'user-2' }),
       claims({ payloadDigest: digestIdentityPayload({ b: 2 }) }),
@@ -75,7 +75,7 @@ describe('signing', () => {
   });
 
   it('will not sign claims naming a different root', async () => {
-    const other = deriveIdentityFromMnemonic('legal winner thank year wave sausage worth useful legal winner thank yellow');
+    const other = keyPair('22'.repeat(32));
     await expect(signIdentityProof(identity, claims({ rootPublicKey: other.publicKey }))).rejects.toThrow('different root');
   });
 });

package/src/crypto/identityLink.ts

@@ -0,0 +1,18 @@
+/**
+ * The code both screens show while Commons is being linked to a passkey
+ * account (ADR 0029 D3): 6 digits derived from the link request and the key
+ * Commons signed with. auth.oxy.so derives it from the key the API relayed,
+ * Commons from its own; the person checks they match before the passkey is
+ * asserted, so a photographed QR cannot slip another key in.
+ */
+
+import { sha256 } from '@noble/hashes/sha256';
+import { utf8ToBytes } from '@noble/hashes/utils';
+
+const DOMAIN = 'oxy-identity-link-code/v1';
+
+export function deriveIdentityLinkCode(linkId: string, publicKey: string): string {
+  const digest = sha256(utf8ToBytes(`${DOMAIN}|${linkId}|${publicKey.trim().toLowerCase()}`));
+  const value = ((digest[0] << 24) | (digest[1] << 16) | (digest[2] << 8) | digest[3]) >>> 0;
+  return String(value % 1_000_000).padStart(6, '0');
+}

package/src/i18n/locales/ar-SA.json

@@ -50,7 +50,26 @@
     "createInCommons": "أنشئ هويتك في Commons",
     "createAccount": "إنشاء حساب",
     "backToSignInLink": "لديك حساب بالفعل؟ سجّل الدخول",
-    "webSubtitle": "بلا كلمة مرور. ينشئ جهازك مفتاح مرور، ويحصل حسابك على عبارة استرداد تحتفظ بها أنت وحدك."
+    "webSubtitle": "بلا كلمة مرور: ينشئ جهازك مفتاح مرور، ويعيدك بريد الاسترداد إذا فقدته.",
+    "username": {
+      "label": "اسم المستخدم",
+      "placeholder": "yourname",
+      "required": "اختر اسم مستخدم.",
+      "taken": "اسم المستخدم هذا مستخدم بالفعل."
+    },
+    "email": {
+      "title": "بريد الاسترداد",
+      "subtitle": "إذا فقدت مفتاح المرور، نرسل إلى هنا رمزًا لتعود. لا يُستخدم لأي شيء آخر.",
+      "label": "البريد الإلكتروني",
+      "placeholder": "you@example.com",
+      "invalid": "أدخل بريدًا إلكترونيًا صالحًا."
+    },
+    "passkey": {
+      "title": "أنشئ مفتاح المرور",
+      "subtitle": "تسجّل الدخول به: ببصمتك أو وجهك أو قفل الشاشة. لا شيء تتذكره.",
+      "action": "إنشاء مفتاح مرور"
+    },
+    "commonsInstead": "تريد الاحتفاظ بمفتاحك بنفسك؟ استخدم Commons"
   },
   "accountSwitcher": {
     "loading": "جارٍ تحميل الحسابات...",
@@ -225,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": "أرسلنا رمزًا من 6 أرقام إلى {{email}}.",
+    "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. حاول مجددًا."
   }
 }