@oxy.so/core 1.2.1 → 1.3.1

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

@@ -0,0 +1,59 @@
+/**
+ * Identity move — the crypto of taking a web identity into Commons.
+ *
+ * Both carriers run this: `id.oxy.so` (the initiator, holding the identity) and
+ * Commons (the responder, receiving it). The relay in between sees two ephemeral
+ * public keys and ciphertext; the 6-digit SAS both screens show is what makes a
+ * relay that swapped a key visible to the person.
+ *
+ * PURE: no storage, no network. Contract: `@oxy.so/contracts` `identityMove`.
+ */
+import './polyfill';
+import { type OpenedWebIdentity } from './webIdentityCarrier';
+/** Actions the identity key signs during a move. */
+export declare const IDENTITY_MOVE_ACTIONS: {
+    readonly seal: "identity_move_seal";
+    readonly received: "identity_move_received";
+};
+/** A fresh ephemeral key pair for one move. Keep the private key in memory only. */
+export declare function generateMoveEphemeralKeyPair(): {
+    privateKey: string;
+    publicKey: string;
+};
+/** The symmetric key both sides derive: HKDF(ECDH, salt = moveId). */
+export declare function deriveMoveKey(ownEphemeralPrivateKey: string, otherEphemeralPublicKey: string, moveId: string): Uint8Array;
+/** The 6-digit code both screens show, bound to the move and both ephemeral keys in their roles. */
+export declare function deriveMoveSas(moveId: string, initiatorEphemeralPublicKey: string, responderEphemeralPublicKey: string): string;
+/** Initiator: seal the identity's entropy for the responder. */
+export declare function sealIdentityForMove(identity: Pick<OpenedWebIdentity, 'mnemonic' | 'publicKey'>, moveKey: Uint8Array, moveId: string): {
+    nonce: string;
+    ciphertext: string;
+};
+/**
+ * Responder: open the sealed identity. The derived public key must be the one
+ * the move declared — anything else is refused, never imported.
+ */
+export declare function openMovedIdentity(sealed: {
+    nonce: string;
+    ciphertext: string;
+}, moveKey: Uint8Array, moveId: string, expectedPublicKey: string): OpenedWebIdentity;
+/** The exact bytes a move proof or receipt signs. */
+export declare function buildMoveMessage(action: string, moveId: string, timestamp: number): string;
+/** Sign a move action with the identity key. */
+export declare function signMoveAction(identity: Pick<OpenedWebIdentity, 'privateKey'>, action: string, moveId: string, timestamp?: number): Promise<{
+    signature: string;
+    timestamp: number;
+}>;
+/**
+ * Initiator: is this receipt really from the identity? Checked locally with the
+ * identity's public key, so a server that claims "completed" without Commons
+ * having the key cannot make the web destroy its copy.
+ */
+export declare function verifyMoveReceipt(publicKey: string, moveId: string, receipt: {
+    signature: string;
+    timestamp: number;
+}): Promise<boolean>;
+/** The QR payload for a move. */
+export declare function buildMoveQrPayload(moveId: string): string;
+/** The move id in a scanned payload, or `null` when it is not a move QR. */
+export declare function parseMoveQrPayload(raw: string): string | null;

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

@@ -230,6 +230,32 @@ export declare class KeyManager {
      * @returns Shared private key or null if no shared identity exists
      */
     static getSharedPrivateKey(): Promise<string | null>;
+    /**
+     * Which identity key this device is actually acting as, per slot.
+     *
+     * There are two slots and they can disagree. The shared slot is what every
+     * cross-app reader takes first — `deriveScopedSeed` (so: the FairCoin wallet
+     * Peable derives) and `getSharedPrivateKey` — while the primary slot is what
+     * signing and the server-facing identity use. A disagreement is invisible to
+     * both sides on its own, and it is money: a wallet derived from a stale
+     * shared key watches addresses that the key published in the DID will never
+     * produce, so payments land where the recipient cannot see them.
+     *
+     * `activePublicKey` is the one money derives from — the same `shared ?? primary`
+     * order `deriveScopedSeed` uses, so a caller can compare it against the key
+     * published for the account and refuse to receive rather than watch the wrong
+     * addresses.
+     *
+     * Public keys are canonicalized, so two encodings of the same key compare
+     * equal. On web both slots are null and `inSync` is true: nothing is stored,
+     * so nothing can disagree.
+     */
+    static getIdentityKeyState(): Promise<{
+        primaryPublicKey: string | null;
+        sharedPublicKey: string | null;
+        activePublicKey: string | null;
+        inSync: boolean;
+    }>;
     /**
      * Check if a shared identity exists (accessible across all Oxy apps)
      *
@@ -279,14 +305,18 @@ export declare class KeyManager {
      */
     static clearSharedSession(): Promise<void>;
     /**
-     * Migrate local identity to shared identity
+     * Make the shared slot hold THIS device's identity key.
      *
-     * Call this when upgrading existing apps to use shared identities.
-     * Copies the device-specific identity to shared storage so it can
-     * be accessed by other Oxy apps.
+     * The shared slot is the one every Oxy app on the device reads, so it has to
+     * agree with the primary slot. This creates it when it is empty (the original
+     * migration, for apps that predate the shared identity) and repairs it when it
+     * holds a different key.
      *
-     * @returns True if migration was successful, false if no local identity exists
+     * @returns True when the shared slot ends up holding the device's key, false
+     *          when there is no identity to share.
      */
+    static syncSharedIdentity(): Promise<boolean>;
+    /** @deprecated Renamed to {@link KeyManager.syncSharedIdentity}. */
     static migrateToSharedIdentity(): Promise<boolean>;
     /**
      * Atomically persist a key pair to secure storage with verification + backup.

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

@@ -0,0 +1,123 @@
+/**
+ * Web identity carrier — the crypto of "one identity, two carriers".
+ *
+ * An Oxy identity is a BIP-39 mnemonic; its seed's first 32 bytes are the
+ * secp256k1 key (`recoveryPhrase.ts`). Commons keeps that key in the device
+ * keychain. This module lets a browser carry the SAME identity without Oxy ever
+ * being able to use it:
+ *
+ *   entropy ──AEAD(DEK)──▶ sealedEntropy
+ *   DEK     ──AEAD(KEK_i)─▶ wraps[i]            KEK_i = HKDF(PRF output of passkey i)
+ *
+ * The PRF output is produced inside the user's authenticator, behind user
+ * verification, and never leaves the page that asked for it. The envelope is
+ * therefore safe to store anywhere — the identity origin's IndexedDB and the
+ * server copy alike — and opens only with a registered passkey or the phrase.
+ *
+ * PURE: no storage, no network, no WebAuthn call, no platform globals beyond the
+ * CSPRNG the AEAD polyfill guarantees. The caller runs the ceremony and hands the
+ * PRF output in; everything here is deterministic given its inputs, so it is
+ * identical on web, Node and React Native, and fully unit-testable.
+ *
+ * Contract: `WebIdentityEnvelope` in `@oxy.so/contracts`.
+ */
+import './polyfill';
+import { type WebIdentityEnvelope, type WebIdentityWrap } from '@oxy.so/contracts';
+/**
+ * The PRF input every identity-carrier ceremony evaluates (`prf.eval.first`).
+ *
+ * Fixed rather than per-wrap: discoverable sign-in has no credential list to key
+ * `evalByCredential` by, and each passkey's output is already distinct. A future
+ * scheme change bumps the label — and with it every KEK — instead of mutating it.
+ */
+export declare const WEB_IDENTITY_PRF_INPUT: Uint8Array;
+/** Why an envelope did not open. Every value is a normal outcome a UI can explain. */
+export type WebIdentityUnlockFailure = 
+/** The passkey used is not one of the envelope's wraps. */
+'unknown-credential'
+/**
+ * The passkey IS listed but its PRF output does not open its wrap — a synced
+ * copy returning a different PRF value, or a provider that silently changed it.
+ * Recoverable with another passkey or the phrase.
+ */
+ | 'prf-mismatch'
+/** The envelope itself is malformed or tampered with. */
+ | 'corrupt';
+export declare class WebIdentityUnlockError extends Error {
+    readonly failure: WebIdentityUnlockFailure;
+    constructor(failure: WebIdentityUnlockFailure, message: string);
+}
+/** The identity in usable form. Hold it for one operation, then {@link wipeBytes}. */
+export interface OpenedWebIdentity {
+    mnemonic: string;
+    /** 32-byte secp256k1 private key, lowercase hex. */
+    privateKey: string;
+    /** Uncompressed SEC1 public key, lowercase hex (Oxy's canonical form). */
+    publicKey: string;
+}
+/** Overwrite a buffer holding secret material. Best effort — JS gives no stronger guarantee. */
+export declare function wipeBytes(bytes: Uint8Array): void;
+/**
+ * Derive the identity from a mnemonic exactly as Commons does
+ * (`RecoveryPhraseService`): seed → first 32 bytes → secp256k1.
+ */
+export declare function deriveIdentityFromMnemonic(mnemonic: string): OpenedWebIdentity;
+/** A brand-new 12-word identity. Nothing is persisted. */
+export declare function generateWebIdentity(): OpenedWebIdentity;
+/** A fresh random data key for a new envelope. */
+export declare function generateDataKey(): Uint8Array;
+/** The key-encryption key a passkey's PRF output yields for its own wrap. */
+export declare function deriveKeyEncryptionKey(prfOutput: Uint8Array, credentialId: string): Uint8Array;
+/** Wrap `dataKey` for one passkey. */
+export declare function wrapDataKey(dataKey: Uint8Array, prfOutput: Uint8Array, credentialId: string, publicKey: string, now?: Date): WebIdentityWrap;
+/**
+ * Seal an identity into a new envelope that opens with the given passkey.
+ *
+ * Returns the data key too, so the caller can add further wraps in the same
+ * session; wipe it when done.
+ */
+export declare function sealWebIdentity(identity: Pick<OpenedWebIdentity, 'mnemonic' | 'publicKey'>, firstWrap: {
+    prfOutput: Uint8Array;
+    credentialId: string;
+}, now?: Date): {
+    envelope: WebIdentityEnvelope;
+    dataKey: Uint8Array;
+};
+/** Recover the data key with one passkey's PRF output. */
+export declare function unwrapDataKey(envelope: WebIdentityEnvelope, prfOutput: Uint8Array, credentialId: string): Uint8Array;
+/**
+ * Open an envelope with its data key.
+ *
+ * The derived public key is checked against the envelope's own: a sealed entropy
+ * that decrypts into a different identity is treated as corruption, never used.
+ */
+export declare function openWebIdentity(envelope: WebIdentityEnvelope, dataKey: Uint8Array): OpenedWebIdentity;
+/** Unwrap and open in one step. */
+export declare function unlockWebIdentity(envelope: WebIdentityEnvelope, prfOutput: Uint8Array, credentialId: string): OpenedWebIdentity;
+/** Add (or replace) one passkey's wrap. Requires the data key of an unlocked envelope. */
+export declare function addWrap(envelope: WebIdentityEnvelope, dataKey: Uint8Array, prfOutput: Uint8Array, credentialId: string, now?: Date): WebIdentityEnvelope;
+/** Remove one passkey's wrap. The last wrap can never be removed — an envelope nobody can open is a loss. */
+export declare function removeWrap(envelope: WebIdentityEnvelope, credentialId: string): WebIdentityEnvelope;
+/**
+ * The message an identity key signs to authorize an account action
+ * (`link_identity`, `web_envelope_delete`, …): `JSON.stringify({ action, userId,
+ * timestamp })`, byte-identical to what the API reconstructs.
+ */
+export declare function buildIdentityActionMessage(action: string, userId: string, timestamp: number): string;
+/** Sign an identity-action message with an opened identity's key. */
+export declare function signIdentityAction(identity: Pick<OpenedWebIdentity, 'privateKey'>, action: string, userId: string, timestamp?: number): Promise<{
+    signature: string;
+    timestamp: number;
+}>;
+/**
+ * The 6-digit short authentication string both sides of an identity transfer show.
+ *
+ * Bound to the pairing and to BOTH ephemeral public keys in their roles, so a relay
+ * that substitutes either key produces a different code on each screen. The user
+ * comparing the two codes is what makes the transfer safe against the relay itself.
+ */
+export declare function deriveTransferSas(input: {
+    pairingId: string;
+    initiatorEphemeralPublicKey: string;
+    responderEphemeralPublicKey: string;
+}): string;

package/dist/types/index.d.ts

@@ -70,6 +70,9 @@ 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, addWrap, buildIdentityActionMessage, deriveIdentityFromMnemonic, deriveKeyEncryptionKey, deriveTransferSas, generateDataKey, generateWebIdentity, openWebIdentity, removeWrap, sealWebIdentity, signIdentityAction, unlockWebIdentity, unwrapDataKey, wipeBytes, wrapDataKey, } from './crypto/webIdentityCarrier';
+export type { OpenedWebIdentity, WebIdentityUnlockFailure } from './crypto/webIdentityCarrier';
+export { IDENTITY_MOVE_ACTIONS, buildMoveMessage, buildMoveQrPayload, deriveMoveKey, deriveMoveSas, generateMoveEphemeralKeyPair, openMovedIdentity, parseMoveQrPayload, sealIdentityForMove, signMoveAction, verifyMoveReceipt, } from './crypto/identityMove';
 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';
@@ -104,7 +107,7 @@ export { updateAvatarVisibility } from './utils/avatarUtils';
 export { buildAccountsArray, createQuickAccount, getAccountDisplayName, getAccountFallbackHandle, formatPublicKeyHandle, getAccountColor, } from './utils/accountUtils';
 export type { QuickAccount, DisplayNameUserShape } from './utils/accountUtils';
 export { registrableApex } from './utils/registrableApex';
-export { CENTRAL_IDP_APEX } from './utils/authWebUrl';
+export { CENTRAL_IDP_APEX, IDENTITY_WEB_ORIGIN } from './utils/authWebUrl';
 export { isOxyRpOrigin } from './utils/webauthnOrigin';
 export { runColdBoot } from './utils/coldBoot';
 export type { ColdBootStep, ColdBootStepResult, ColdBootSession, ColdBootSkip, ColdBootOutcome, RunColdBootOptions, } from './utils/coldBoot';
@@ -125,7 +128,7 @@ export { isSwitchTargetAccount, canSwitchIntoAccount, } from './session/accountS
 export { resolveAccountDelegationAccess } from './session/accountDelegationAccess';
 export type { AccountDelegationAccess, AccountDelegationNode, } from './session/accountDelegationAccess';
 export { AccountDialogController, createAccountDialogController, } from './session/accountDialogController';
-export type { AccountDialogControllerOptions, AccountDialogSnapshot, AccountDialogView, CommonsAvailability, PopupWindowHandle, SignInFlowPhase, SignInFlowState, SignInProgress, } from './session/accountDialogController';
+export type { AccountDialogControllerOptions, AccountDialogSnapshot, AccountDialogView, CommonsAvailability, PopupWindowHandle, SignInFailureReason, SignInFlowPhase, SignInFlowState, SignInProgress, } from './session/accountDialogController';
 export { createWebAuthStateStore, createNativeAuthStateStore, createMemoryAuthStateStore, AUTH_STATE_STORAGE_KEY, } from './session/authStateStore';
 export type { PersistedAuthState, AuthStateStore, NativeKeyValueStorage, } from './session/authStateStore';
 export { createSharedMirroringAuthStateStore, decideSharedDeviceJoin, decideSharedDevicePublish, normalizeSharedDeviceSessionRead, publishProvenDeviceCredential, readLocalDeviceCredential, } from './session/sharedDeviceCredential';

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

@@ -471,10 +471,16 @@ export declare function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(B
          *   `timeout`). Interactive callers omit it (defaults keep retries); the
          *   cold-boot `shared-key-signin` step passes `{ retry: false }` so a slow
          *   network cannot multiply boot latency via the inner retry loop.
+         * @param options.plantTokens - Install the returned bearer on this client
+         *   (default `true`). A caller that must decide LATER whether the session is
+         *   still wanted (the account dialog, whose user may have cancelled while the
+         *   request was in flight) passes `false` and plants it itself.
          */
         verifyChallenge(publicKey: string, challenge: string, signature: string, timestamp: number, deviceName?: string, deviceFingerprint?: string, requestOptions?: {
             retry?: boolean;
             timeout?: number;
+        }, options?: {
+            plantTokens?: boolean;
         }): Promise<SessionLoginResponse>;
         /**
          * Check if a public key is already registered
@@ -515,9 +521,13 @@ export declare function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(B
          *   `POST /auth/session/create` at the start of the flow.
          * @param options.deviceFingerprint - Optional fingerprint of the
          *   originating client device.
+         * @param options.plantTokens - Install the claimed bearer on this client
+         *   (default `true`). Pass `false` to install it yourself once you know the
+         *   session is still wanted — see `verifyChallenge`.
          */
         claimSessionByToken(sessionToken: string, options?: {
             deviceFingerprint?: string;
+            plantTokens?: boolean;
         }): Promise<{
             accessToken: string;
             sessionId: string;
@@ -545,6 +555,7 @@ export declare function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(B
          *   retries); the cold-boot `shared-key-signin` step passes `{ retry: false }`
          *   so this network step cannot multiply boot latency via the inner retry
          *   loop. The token-refresh scheduler / 401 lane still retry later.
+         * @param opts.plantTokens - Forwarded to `verifyChallenge` (default `true`).
          */
         signInWithSharedIdentity(opts?: {
             deviceName?: string;
@@ -553,6 +564,7 @@ export declare function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(B
                 retry?: boolean;
                 timeout?: number;
             };
+            plantTokens?: boolean;
         }): Promise<SessionLoginResponse | null>;
         /**
          * MECHANISM B (relying party) — begin a "Sign in with Oxy" handoff.

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

@@ -101,7 +101,22 @@ export interface User {
     description?: string;
     phone?: string;
     address?: string;
+    /** Legacy free-text birthday, kept for backward compatibility. Prefer `dateOfBirth`. */
     birthday?: string;
+    /**
+     * The structured date of birth, `YYYY-MM-DD`. The new source of truth going
+     * forward — `birthday` above is unparsed free text with no guaranteed
+     * shape. Present only on the account's OWN profile (never on another
+     * account's public profile), same visibility as `phone`/`address`/`birthday`.
+     */
+    dateOfBirth?: string | null;
+    /**
+     * Derived, non-PII signal: whether the account holder is at least 18.
+     * `undefined` when `dateOfBirth` is unset ("unknown"), distinct from
+     * `false` ("known, not yet 18"). Never stored — computed fresh by the API
+     * on every read of the owner's own profile.
+     */
+    isAdult?: boolean;
     website?: string;
     createdAt?: string;
     updatedAt?: string;

package/dist/types/session/accountDialogController.d.ts

@@ -110,6 +110,21 @@ export type SignInFlowPhase = 'idle' | 'starting' | 'waiting' | 'authorized' | '
  * evidence of an approval. Only `authorized` moves the flow forward.
  */
 export type SignInProgress = 'idle' | 'preparing' | 'awaiting-approval' | 'delivered-to-commons' | 'opened-in-commons' | 'confirming-identity' | 'identity-confirmed';
+/**
+ * WHY a sign-in attempt ended in `'error'` — a machine-readable reason the UI
+ * turns into localized copy (the controller ships no user-facing prose).
+ *
+ *  - `'cancelled'` — the USER walked away (closed the passkey hub popup). A
+ *    voluntary outcome, not a failure to report.
+ *  - `'denied'` — the approver declined the request in Commons.
+ *  - `'expired'` — the request outlived its server-authoritative expiry.
+ *  - `'network'` — Oxy could not be reached (no response, timeout).
+ *  - `'not-configured'` — the app has no registered `clientId`.
+ *  - `'unsupported-flow'` — an OAuth-bound request, which this surface cannot finalize.
+ *  - `'claim-failed'` — the request WAS approved, but the session could not be claimed.
+ *  - `'unknown'` — anything else; the raw message stays on `error` for logs.
+ */
+export type SignInFailureReason = 'cancelled' | 'denied' | 'expired' | 'network' | 'not-configured' | 'unsupported-flow' | 'claim-failed' | 'unknown';
 /**
  * Minimal structural handle over a popup `Window` — just enough for the
  * cross-origin passkey hub flow ({@link AccountDialogController.startPasskeyHubSignIn}):
@@ -147,8 +162,13 @@ export interface SignInFlowState {
     qrPayload: string | null;
     /** Server-authoritative expiry (epoch ms), or `null`. */
     expiresAt: number | null;
-    /** Human-readable error for the retry UI, or `null`. */
+    /**
+     * The raw, UNLOCALIZED failure message (diagnostics only), or `null`. A surface
+     * renders {@link failure} instead — this string is English or a server message.
+     */
     error: string | null;
+    /** Why the attempt failed, set together with `phase: 'error'`; `null` otherwise. */
+    failure: SignInFailureReason | null;
     /**
      * The ONE primary delivery route the controller chose for this request
      * ({@link selectCommonsDelivery}), or `null` while it is still being resolved.
@@ -189,6 +209,14 @@ export interface SignInFlowState {
      * cannot drift from them or run ahead of a real signal.
      */
     progress: SignInProgress;
+    /**
+     * Identity of the sign-in ATTEMPT this state belongs to — a counter that moves
+     * whenever an attempt is started, cancelled, or the controller is destroyed.
+     * Not a secret. It lets a surface treat "this attempt failed" as one event (a
+     * re-notification of the same failure is not a second failure, while a new
+     * attempt failing with the same message is).
+     */
+    attempt: number;
 }
 /** Immutable snapshot consumed by `useSyncExternalStore`. */
 export interface AccountDialogSnapshot {
@@ -290,8 +318,16 @@ export interface AccountDialogControllerOptions {
      */
     openPopup?: () => PopupWindowHandle | null;
     /**
-     * Base origin of the auth.oxy.so passkey hub (defaults to
-     * `https://auth.${CENTRAL_IDP_APEX}`). Overridable for local/staging testing.
+     * Origin of the web identity carrier (default `IDENTITY_WEB_ORIGIN`,
+     * `https://id.oxy.so`) — where a passkey sign-in or sign-up runs
+     * and the account's identity is kept sealed under the passkey. The popup opens
+     * `<identityOrigin>/continue?code=…`. Overridable for local/staging testing.
+     */
+    identityOrigin?: string;
+    /**
+     * @deprecated Alias of {@link identityOrigin}, kept for existing
+     * configuration. The popup used to open `auth.oxy.so/hub-passkey`; it now opens
+     * the identity origin's `/continue`, so a value here must be that origin.
      */
     hubBaseUrl?: string;
     /**
@@ -319,7 +355,7 @@ export declare class AccountDialogController {
     private readonly canOpenApp?;
     private readonly socketFactory?;
     private readonly openPopup?;
-    private readonly hubBaseUrl;
+    private readonly identityOrigin;
     private readonly platform;
     private readonly listeners;
     private view;
@@ -328,8 +364,24 @@ export declare class AccountDialogController {
     private activatingContextId;
     private removingContextId;
     private removingPrincipalId;
+    /**
+     * `true` while an operation run through {@link runDeviceMutation} (a host
+     * sign-out) is in flight. The fourth member of the ONE device-mutation gate,
+     * alongside the three flags above.
+     */
+    private exclusiveMutationInFlight;
     private signIn;
     private commonsAvailability;
+    /**
+     * The CURRENT sign-in attempt. Every asynchronous step of a sign-in captures
+     * it before awaiting and re-checks it after (`isCurrentAttempt`); cancelling,
+     * starting another attempt, or destroying the controller moves it, so a late
+     * response from an abandoned attempt can neither update the surface nor
+     * install a session.
+     */
+    private signInAttempt;
+    /** How the current attempt was started, so a retry repeats the user's choice. */
+    private signInMethod;
     /** The secret device-flow token of the active QR flow (never surfaced). */
     private signInToken;
     private pollTimer;
@@ -342,9 +394,10 @@ export declare class AccountDialogController {
     /**
      * Guards {@link pollOnce} against re-entrancy: the fallback timer and a socket
      * `auth_update` wake can fire together — without this both could claim the
-     * single-use token concurrently.
+     * single-use token concurrently. Keyed by token, so a poll still running for an
+     * ABANDONED request never blocks the next request's first poll.
      */
-    private pollInFlight;
+    private pollInFlightToken;
     /** The popup opened by {@link startPasskeyHubSignIn}, or `null`. */
     private activePopup;
     /** Watches {@link activePopup}'s `closed` state; see {@link watchPopup}. */
@@ -412,8 +465,11 @@ export declare class AccountDialogController {
      * — and the reconstruction was not merely redundant: it enumerated the
      * CALLER's account graph, which on a device holding two people is one
      * person's answer presented as the device's.
+     *
+     * Resolves `false` when THIS read failed (a 401 is the signed-out edge, not a
+     * failure). Never rejects.
      */
-    refresh(): Promise<void>;
+    refresh(): Promise<boolean>;
     /**
      * Activate one `principal acting as account` context — the ADR 0002 switch,
      * and the one that can express what an account id cannot: WHICH person's
@@ -427,6 +483,11 @@ export declare class AccountDialogController {
      * A context id is not stable across a removal, so a stale one is an ordinary
      * outcome rather than a bug: the server answers 404 or 403, heals the row, and
      * the refresh below re-reads a directory that no longer offers it.
+     *
+     * Resolves `true` once the SWITCH happened — even if the directory re-read
+     * after it fails (that failure lands on `error`, but the subject did change).
+     * Resolves `false` when the switch failed, or was refused because another
+     * device mutation is in flight ({@link isDeviceMutationInFlight}).
      */
     activateContext(contextId: string): Promise<boolean>;
     /**
@@ -451,11 +512,46 @@ export declare class AccountDialogController {
      * and elects a replacement active context in one transition.
      */
     signOutPrincipal(principalId: string): Promise<boolean>;
+    /**
+     * Whether ANY operation that changes who is on this device, or which of them
+     * is active, is in flight: an activation, either removal, or a host operation
+     * run through {@link runDeviceMutation}.
+     *
+     * They share ONE gate because they mutate the same device set: a removal that
+     * elects a replacement active context racing a switch could leave either one
+     * active. A refused call is refused, never queued — a press that could not run
+     * must not fire later, after the user has moved on.
+     */
+    isDeviceMutationInFlight(): boolean;
+    /**
+     * Run a device mutation the controller does not own (the host's sign-out)
+     * under the same gate as {@link activateContext} and the removals.
+     *
+     * Resolves `{ ran: false }` without calling `operation` when another mutation
+     * is in flight; otherwise `{ ran: true, value }`. A rejection from `operation`
+     * propagates, after the gate is released.
+     */
+    runDeviceMutation<T>(operation: () => Promise<T>): Promise<{
+        ran: true;
+        value: T;
+    } | {
+        ran: false;
+    }>;
+    /**
+     * The shared body of the three controller-owned device mutations: take the
+     * gate, run the mutation, then re-read the directory.
+     *
+     * The mutation's outcome and the re-read's are kept apart. Once `operation`
+     * has resolved the device HAS changed, so this resolves `true` even when the
+     * re-read fails — that failure is the directory's (`error`), and reporting it
+     * as a failed switch would invite the user to repeat something that happened.
+     */
+    private mutateDevice;
     /**
      * Start "Sign in with Oxy". Native devices with a shared identity mint a
      * session silently (`signInWithSharedIdentity`); everything else (web, or a
      * native device without a shared identity) falls through to the cross-device
-     * QR handoff.
+     * QR handoff — as the SAME attempt, so cancelling during either half stops both.
      */
     signInWithOxy(): Promise<void>;
     /**
@@ -466,11 +562,24 @@ export declare class AccountDialogController {
      */
     showQr(): Promise<void>;
     /**
-     * Web-only: "Sign in with a passkey" on a non-Oxy origin cannot run the
-     * WebAuthn ceremony locally — a credential minted with `WEBAUTHN_RP_ID=oxy.so`
-     * can only be asserted from `oxy.so`/a subdomain/loopback, a browser-enforced
-     * boundary `isOxyRpOrigin()` (consumer-side) already gates on. Instead, open
-     * a popup at the auth.oxy.so passkey hub, scoped to the SAME device-flow
+     * Start a NEW attempt the same way the last one was started — "Try again"
+     * repeats the user's choice rather than silently switching method. A failed
+     * passkey-hub attempt reopens the hub popup; a failed "Sign in with Oxy"
+     * retries that; an explicit QR request shows the QR.
+     *
+     * Call it straight from the press handler: the hub route opens its popup
+     * synchronously, before this method's first `await`, so the browser still
+     * attributes it to the click.
+     */
+    retrySignIn(): Promise<void>;
+    /**
+     * Web-only: sign in (or create an account) with a passkey at the web identity
+     * carrier. The ceremony runs on `id.oxy.so`, never on the calling origin, for
+     * two reasons: a credential minted with `WEBAUTHN_RP_ID=oxy.so` can only be
+     * asserted from `oxy.so`/a subdomain/loopback (a browser-enforced boundary),
+     * and only the identity origin may unseal or create the account's identity
+     * (one identity, two carriers). Opens a popup at `<identityOrigin>/continue`,
+     * scoped to the SAME device-flow
      * session {@link showQr} would create (same `authorizeCode`/`sessionToken`
      * pair), and let the SAME poll/socket/claim engine complete it once the hub
      * authorizes the session (`POST /auth/session/authorize-code/:authorizeCode`,
@@ -485,13 +594,26 @@ export declare class AccountDialogController {
      * `showQr`'s plain QR rendering — no dead end.
      */
     startPasskeyHubSignIn(): Promise<void>;
+    /**
+     * End whatever attempt is running (withdrawing its request) and begin a new
+     * one. Returns the new attempt's identity for the caller to re-check after
+     * every `await`.
+     */
+    private beginSignInAttempt;
+    /** Whether `attempt` is still the one the surface is waiting on. */
+    private isCurrentAttempt;
     /**
      * Shared device-flow session creation for both {@link showQr} (renders the
      * QR) and {@link startPasskeyHubSignIn} (also opens the hub popup) — the
      * same `startCommonsSignIn` → poll/socket wiring either way. Returns the
-     * handle on success (already reflected in `signIn`), or `null` on failure
-     * (already set as `signIn.error`).
+     * handle on success (already reflected in `signIn`), or `null` when the
+     * attempt failed (already set as `signIn.failure`) or was abandoned while the
+     * request was being created.
      *
+     * @param attempt - The attempt this request belongs to. A request that comes
+     *   back for an abandoned attempt is withdrawn server-side and never wired up:
+     *   closing the dialog on a slow connection must not leave an approvable
+     *   request, a socket, and a poll behind it.
      * @param opts.deliver - Whether to run automatic Commons delivery selection
      *   ({@link resolveDeliveryRoute}). `true` for the normal one-primary-action
      *   entry; `false` when the caller already owns the primary surface (the
@@ -574,6 +696,12 @@ export declare class AccountDialogController {
      * cancel the request, not just stop listening to it. Without the withdrawal a
      * dismissed QR would stay approvable until it expired, so a later scan of a
      * stale code could authorize a session nobody is waiting for.
+     *
+     * It also ENDS the attempt: anything of it still awaiting a response (the
+     * request being created, a shared-identity mint, a claim) finds itself
+     * superseded when that response arrives, and neither touches the surface nor
+     * installs a session. The withdrawal itself is best effort — cancelling
+     * locally is not proof the server received it (see {@link withdrawRequest}).
      */
     cancelSignIn(): void;
     /**
@@ -603,8 +731,28 @@ export declare class AccountDialogController {
     private recordDeliveryProgress;
     private claimAndComplete;
     /**
-     * Commit an authorized session, notify, and return to the account list. Shared
-     * by the shared-key, QR, and mint-switch paths so they cannot drift.
+     * Install an authorized session, notify, and return to the account list.
+     * Shared by the shared-key and QR paths so they cannot drift.
+     *
+     * THE install point, and so the last place an abandoned attempt is stopped:
+     * the bearer is planted and the session committed only while `attempt` is
+     * still current. A commit that fails restores the bearer the client had
+     * before, so a half-installed session never leaves requests going out as an
+     * account the device does not hold.
+     *
+     * A failed commit REJECTS (after that restore), so each caller keeps its own
+     * policy: the QR path fails the attempt, the shared-identity path falls
+     * through to the QR handoff.
+     *
+     * Once the commit has resolved the session IS this device's, whether or not
+     * the user moved on while it ran. It is reported (`onSignedIn`, re-read) either
+     * way; only the surface bookkeeping is skipped for a superseded attempt, so a
+     * newer attempt's state is never overwritten.
+     *
+     * Residual: an attempt abandoned after the server minted its session (a claim
+     * or shared-identity mint that was already in flight) leaves that server
+     * session un-installed on this device — it is never planted or committed here,
+     * but it is not revoked either.
      */
     private completeSignIn;
     /**
@@ -613,6 +761,10 @@ export declare class AccountDialogController {
      * `SessionClient.registerAndActivate` (registration + activation only).
      */
     private commitAuthorizedSession;
+    /**
+     * End the CURRENT attempt as failed. The attempt keeps its identity (the
+     * failure belongs to it); only a new attempt or a cancel moves it on.
+     */
     private failSignIn;
     private clearPollTimer;
     /**

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

@@ -14,3 +14,10 @@
  * the CORS helper (and anything else that needs the central apex) never drifts.
  */
 export declare const CENTRAL_IDP_APEX = "oxy.so";
+/**
+ * The web identity carrier's origin — where a person signs in or creates an
+ * account with a passkey, and where their self-custody identity is kept sealed
+ * under that passkey (one identity, two carriers). Apps open it; they never
+ * handle the identity themselves.
+ */
+export declare const IDENTITY_WEB_ORIGIN = "https://id.oxy.so";