@oxyhq/core 12.10.6 → 12.11.1

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

@@ -0,0 +1,143 @@
+/**
+ * Push Notification Registration Mixin
+ *
+ * Registers this installation's push token with Oxy so the platform can reach
+ * the signed-in identity — most importantly to deliver a "Sign in with Oxy"
+ * approval request to a known Commons installation (issue #691, Phase 4)
+ * instead of forcing the user onto a QR.
+ *
+ * This lives in `@oxyhq/core` because push registration is cross-cutting: every
+ * Oxy app that wants to receive platform notifications performs the exact same
+ * bearer-authenticated register/unregister pair. App-local copies drift (see the
+ * token-kind hazard below), so there is ONE implementation here.
+ *
+ * ## The token is an EXPO PUSH TOKEN
+ *
+ * `registerPushToken` takes the token returned by
+ * `Notifications.getExpoPushTokenAsync()` — the `ExponentPushToken[…]` handle —
+ * because the server delivers through Expo's push service, which only accepts
+ * that form.
+ *
+ * It does NOT take `getDevicePushTokenAsync()`'s raw APNs/FCM device token.
+ * Registering one of those looks completely successful (the row is stored, the
+ * endpoint returns 200) and then every push silently fails at delivery time,
+ * which is exactly the failure mode this surface is written to make impossible:
+ * the token is validated here, at the call site, so a raw device token is
+ * rejected immediately with an explicit error rather than becoming a dead
+ * registration nobody notices.
+ *
+ * Acquiring the token (permission prompt, `expo-notifications`) is the app's
+ * job — `@oxyhq/core` never imports an `expo-*` module.
+ */
+import type { OxyServicesBase } from '../OxyServices.base';
+/**
+ * Platform the push token was minted on. Mirrors the enum the server accepts;
+ * a value outside it is rejected server-side.
+ */
+export type PushTokenPlatform = 'ios' | 'android' | 'web';
+/** Registration input for {@link OxyServicesNotificationsMixin.registerPushToken}. */
+export interface RegisterPushTokenInput {
+    /**
+     * The **Expo push token** for this installation — `ExponentPushToken[…]`,
+     * from `Notifications.getExpoPushTokenAsync()`.
+     *
+     * NOT the raw APNs/FCM token from `getDevicePushTokenAsync()`; that form is
+     * rejected before any request is sent.
+     */
+    expoPushToken: string;
+    /** Platform this token was minted on. */
+    platform: PushTokenPlatform;
+    /**
+     * Optional device-first `deviceId` this installation is registered under, so
+     * the server can retire the token when that device session goes away instead
+     * of pushing to an installation that has signed out.
+     */
+    deviceId?: string;
+    /**
+     * Optional registered OAuth client id (the caller's credential `publicKey`,
+     * `oxy_dk_…`) identifying WHICH application this installation is. The server
+     * resolves it to the registering `Application` and rejects an unusable one.
+     *
+     * This is what makes "deliver the approval request to a known Commons
+     * installation" possible: delivery targets the Commons application's
+     * registrations, never every push token the identity owns.
+     */
+    clientId?: string;
+}
+export declare function OxyServicesNotificationsMixin<T extends typeof OxyServicesBase>(Base: T): {
+    new (...args: any[]): {
+        /**
+         * Register this installation's **Expo** push token for the authenticated
+         * identity (`POST /notifications/push-token`, bearer required).
+         *
+         * Idempotent server-side: re-registering the same token for the same
+         * identity refreshes the existing row rather than creating a duplicate, so
+         * callers can safely re-register on every cold boot.
+         *
+         * @throws When `expoPushToken` is not an Expo push token — a raw APNs/FCM
+         *   device token fails here rather than becoming a silently undeliverable
+         *   registration.
+         */
+        registerPushToken(input: RegisterPushTokenInput): Promise<void>;
+        /**
+         * Retire an **Expo** push token for the authenticated identity
+         * (`DELETE /notifications/push-token`, bearer required).
+         *
+         * Call it when the user turns notifications off, when the vault identity is
+         * replaced, and on sign-out — otherwise the installation keeps receiving
+         * approval requests for an identity it no longer holds.
+         *
+         * @param expoPushToken - The exact token previously registered.
+         */
+        unregisterPushToken(expoPushToken: string): Promise<void>;
+        httpService: import("../HttpService").HttpService;
+        cloudURL: string;
+        config: import("../OxyServices.base").OxyConfig;
+        __resetTokensForTests(): void;
+        makeRequest<T_1>(method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE", url: string, data?: any, options?: import("../HttpService").RequestOptions): Promise<T_1>;
+        getBaseURL(): string;
+        getClient(): import("../HttpService").HttpService;
+        createLinkedClient(config: import("../OxyServices.base").OxyConfig): import("..").LinkedHttpClient;
+        getMetrics(): {
+            totalRequests: number;
+            successfulRequests: number;
+            failedRequests: number;
+            cacheHits: number;
+            cacheMisses: number;
+            averageResponseTime: number;
+        };
+        clearCache(): void;
+        clearCacheEntry(key: string): void;
+        clearCacheByPrefix(prefix: string): number;
+        getCacheStats(): {
+            size: number;
+            hits: number;
+            misses: number;
+            hitRate: number;
+        };
+        getCloudURL(): string;
+        setTokens(accessToken: string): void;
+        clearTokens(): void;
+        onTokensChanged(listener: (accessToken: string | null) => void): () => void;
+        _cachedUserId: string | null | undefined;
+        _cachedAccessToken: string | null;
+        getCurrentUserId(): string | null;
+        hasValidToken(): boolean;
+        getAccessToken(): string | null;
+        getAccessTokenExpiry(): number | null;
+        waitForAuth(timeoutMs?: number): Promise<boolean>;
+        withAuthRetry<T_1>(operation: () => Promise<T_1>, operationName: string, options?: {
+            maxRetries?: number;
+            retryDelay?: number;
+            authTimeoutMs?: number;
+        }): Promise<T_1>;
+        validate(): Promise<boolean>;
+        handleError(error: unknown): Error;
+        healthCheck(): Promise<{
+            status: string;
+            users?: number;
+            timestamp?: string;
+            [key: string]: any;
+        }>;
+    };
+} & T;

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

@@ -55,6 +55,8 @@ export interface ViewerGraph {
     mutualIds: string[];
     /** Accounts the viewer has blocked (bounded). */
     blockedIds: string[];
+    /** Accounts the viewer has restricted (bounded). */
+    restrictedIds: string[];
 }
 /** Per-user outcome returned by `POST /users/unfollow/bulk`. */
 export interface BulkUnfollowEntry {

package/dist/types/mixins/index.d.ts

@@ -24,6 +24,7 @@ import { OxyServicesUtilityMixin } from './OxyServices.utility';
 import { OxyServicesFeaturesMixin } from './OxyServices.features';
 import { OxyServicesTopicsMixin } from './OxyServices.topics';
 import { OxyServicesContactsMixin } from './OxyServices.contacts';
+import { OxyServicesNotificationsMixin } from './OxyServices.notifications';
 import { OxyServicesAppDataMixin } from './OxyServices.appData';
 import { OxyServicesCivicMixin } from './OxyServices.civic';
 import { OxyServicesNodesMixin } from './OxyServices.nodes';
@@ -39,7 +40,7 @@ import { OxyServicesDeviceTransferMixin } from './OxyServices.deviceTransfer';
  * If you add a new mixin to `MIXIN_PIPELINE`, add it here too so its methods
  * are visible without a cast.
  */
-type AllMixinInstances = InstanceType<ReturnType<typeof OxyServicesAuthMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesUserMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesIdentityMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesIdentityBackupMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesPrivacyMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLanguageMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesPaymentMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesReputationMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAssetsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAccountsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesConnectedAppsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLocationMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAnalyticsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesDevicesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesSecurityMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesFeaturesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesTopicsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesContactsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAppDataMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesCivicMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesNodesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLinksMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesDeviceBootMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesDeviceTransferMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesUtilityMixin<typeof OxyServicesBase>>>;
+type AllMixinInstances = InstanceType<ReturnType<typeof OxyServicesAuthMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesUserMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesIdentityMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesIdentityBackupMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesPrivacyMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLanguageMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesPaymentMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesReputationMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAssetsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAccountsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesConnectedAppsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLocationMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAnalyticsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesDevicesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesSecurityMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesFeaturesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesTopicsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesContactsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesNotificationsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAppDataMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesCivicMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesNodesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLinksMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesDeviceBootMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesDeviceTransferMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesUtilityMixin<typeof OxyServicesBase>>>;
 /**
  * Constructor type for the fully composed mixin pipeline. Each mixin returns
  * a new constructor that augments its input; reducing across the pipeline

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

@@ -66,6 +66,22 @@ export interface SessionClientOptions {
      * absent it falls back to `getSocketIO()`.
      */
     socketFactory?: SocketIOFactory;
+    /**
+     * The PINNED account id for an IDENTITY-BOUND client (the identity vault),
+     * or `null` for every ordinary account-mode client. Read as a function because
+     * the pin is resolved asynchronously at boot and can move when the identity
+     * session is re-established.
+     *
+     * While pinned this client tracks device state TRUTHFULLY — other apps'
+     * accounts and the device's real `activeAccountId` stay visible in `getState()`
+     * — but it NEVER re-binds its bearer to that active account: no `activeToken`
+     * is planted for a non-pinned account (from a sync response or a pushed
+     * `session_state`), the `TokenTransport` (whose entire job is converging on
+     * `activeAccountId`) is bypassed, and a push that switches the device does not
+     * trigger a token re-fetch. The pinned token's lifecycle belongs solely to the
+     * cold boot / re-mint lane, which mints it with an explicit `accountId`.
+     */
+    getPinnedAccountId?: () => string | null;
 }
 type StateListener = (state: DeviceSessionState | null) => void;
 export declare class SessionClient {
@@ -84,6 +100,13 @@ export declare class SessionClient {
     private readonly boundServerEvents;
     constructor(host: SessionClientHost, options?: SessionClientOptions);
     getState(): DeviceSessionState | null;
+    /**
+     * The account this client's bearer is pinned to, or `null` when it follows the
+     * device's active account (the default). Resolvers are expected to be a plain
+     * synchronous read of already-resolved state (see
+     * {@link SessionClientOptions.getPinnedAccountId}).
+     */
+    private pinnedAccountId;
     subscribe(listener: StateListener): () => void;
     /**
      * Subscribe to a named server-pushed Socket.IO event (e.g. `civic:attested`).
@@ -138,6 +161,11 @@ export declare class SessionClient {
      * sign-in. This adds, then switches to the target so the UI lands on the
      * account the user just authenticated.
      *
+     * An identity-bound (pinned) client only ADDS: its own session is minted for
+     * the pinned account explicitly, so switching the device would gratuitously
+     * re-elect the active account under every OTHER app on this device — a
+     * mutation a pinned client must never make.
+     *
      * @param accountId - The signed-in account id (e.g. `session.user.id`). When
      *   omitted, falls back to the host's current-account ref. If neither
      *   resolves, the add still applies and no switch is performed.

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

@@ -21,6 +21,17 @@
  *   - the "Sign in with Oxy" device flow (same-device shared-keychain via
  *     `oxyServices.signInWithSharedIdentity`, else the cross-device QR handoff
  *     via `startCommonsSignIn` → poll → `claimSessionByToken`);
+ *   - AUTOMATIC delivery selection for that flow (issue #691): the user presses
+ *     ONE primary action and the controller — not the user — picks how the
+ *     request reaches their Commons identity, by gathering the facts
+ *     (`platform`, `commonsAvailability`, and the `targets` a bearer-authorized
+ *     `deliverCommonsSignIn` reached) and handing them to the pure
+ *     `selectCommonsDelivery`. Exactly one route is primary; alternatives are
+ *     never chained behind it, they are state (`signIn.route`,
+ *     `signIn.routeFailed`) the UI reveals on its own terms;
+ *   - honest, non-sensitive PROGRESS for that flow (`signIn.progress`), derived
+ *     only from real signals — the chosen route, `pushSentAt`, `openedAt`,
+ *     `authorized`, and the commit — never from an optimistic timeline;
  *   - `commonsAvailability` — whether Commons is installed on this device
  *     (native only, via the injected `canOpenApp` probe), so the QR view can
  *     offer a "Get Commons" fallback instead of a same-device dead end.
@@ -48,6 +59,7 @@ import type { SessionLoginResponse, MinimalUserData } from '../models/session';
 import type { SessionClient } from './SessionClient';
 import type { SocketIOFactory } from './socketLoader';
 import { type SwitchableAccount } from './accountProjection';
+import { type CommonsDeliveryPlatform, type CommonsDeliveryRoute } from '../utils/commonsDelivery';
 /** The dialog's top-level view. */
 export type AccountDialogView = 'accounts' | 'signin' | 'qr' | 'add' | 'signup';
 /**
@@ -62,8 +74,40 @@ export type AccountDialogView = 'accounts' | 'signin' | 'qr' | 'add' | 'signup';
  *     (native only). A probe error is treated as `'unavailable'` (fail-closed).
  */
 export type CommonsAvailability = 'unknown' | 'checking' | 'available' | 'unavailable';
-/** Lifecycle phase of the "Sign in with Oxy" device flow. */
-export type SignInFlowPhase = 'idle' | 'starting' | 'waiting' | 'authorized' | 'error';
+/**
+ * Lifecycle phase of the "Sign in with Oxy" device flow — the RESOURCE state
+ * (is there a live request, a claim in flight, a terminal outcome), as opposed
+ * to {@link SignInProgress}, which is what the user is told.
+ *
+ * `'completed'` is terminal-but-successful: the session was claimed and
+ * committed, nothing is in flight, and the surface may show "Identity
+ * confirmed" before it goes away. It is cleared back to `'idle'` the moment the
+ * dialog moves to another view (a new intention), so a later sign-in entry can
+ * never inherit the previous flow's terminal state.
+ */
+export type SignInFlowPhase = 'idle' | 'starting' | 'waiting' | 'authorized' | 'completed' | 'error';
+/**
+ * Ordered, non-sensitive progress of the active request — the ONE thing the
+ * sign-in surface renders its status line from (issue #691, Phase 5).
+ *
+ * Every step is DERIVED from a real fact the controller observed; there is no
+ * optimistic sequence and no timer that advances it. The mapping the UI is
+ * expected to render (copy lives in the UI layer, never here):
+ *
+ * | value                  | shown as                       | advanced by |
+ * |------------------------|--------------------------------|-------------|
+ * | `idle`                 | (nothing)                      | no live request, or a terminal error |
+ * | `preparing`            | "Preparing request"            | the request is being created / its route is still being resolved |
+ * | `awaiting-approval`    | route-specific waiting copy    | the primary route is known (`qr` → the QR itself, `open-commons` → "Continue in Commons") |
+ * | `delivered-to-commons` | "Check Commons on your phone"  | the server confirmed a push to ≥1 known Commons install (`await-push`, or `pushSentAt`) |
+ * | `opened-in-commons`    | "Opened in Commons"            | the approver reported `openedAt` |
+ * | `confirming-identity`  | "Confirming identity"          | the request reported `authorized`; the claim/commit is running |
+ * | `identity-confirmed`   | "Identity confirmed"           | the session was claimed and committed |
+ *
+ * `opened-in-commons` and `delivered-to-commons` are PROGRESS only — neither is
+ * 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';
 /**
  * Minimal structural handle over a popup `Window` — just enough for the
  * cross-origin passkey hub flow ({@link AccountDialogController.startPasskeyHubSignIn}):
@@ -79,7 +123,14 @@ export interface PopupWindowHandle {
         href: string;
     };
 }
-/** State of the "Sign in with Oxy" (shared-key / QR) device flow. */
+/**
+ * State of the "Sign in with Oxy" (shared-key / QR) device flow.
+ *
+ * Everything here is safe to render. The flow's SECRET credential (the
+ * device-flow `sessionToken`) is deliberately absent — it never leaves the
+ * controller's private field, so no surface, log, or serialized snapshot can
+ * leak it.
+ */
 export interface SignInFlowState {
     phase: SignInFlowPhase;
     /**
@@ -96,6 +147,46 @@ export interface SignInFlowState {
     expiresAt: number | null;
     /** Human-readable error for the retry UI, or `null`. */
     error: string | null;
+    /**
+     * The ONE primary delivery route the controller chose for this request
+     * ({@link selectCommonsDelivery}), or `null` while it is still being resolved.
+     *
+     * There is no chain: exactly one route is primary, and the UI renders exactly
+     * one action for it. Alternatives stay behind a "Having trouble?" affordance
+     * that the UI reveals on its own terms — see {@link routeFailed}.
+     */
+    route: CommonsDeliveryRoute | null;
+    /**
+     * `true` when the chosen primary route could NOT be carried out on this
+     * device — today only `'open-commons'` can fail this way (no URL opener was
+     * injected, or opening the verified Commons link threw). It is the signal the
+     * UI needs to reveal its alternatives; the controller never cascades to
+     * another route by itself.
+     *
+     * A push that reached zero installations is NOT a failure: no capable Commons
+     * install is a normal outcome that simply resolves the primary route to
+     * `'qr'`.
+     */
+    routeFailed: boolean;
+    /**
+     * Server-reported ISO-8601 timestamp of when the request was pushed to a
+     * known Commons installation, or `null`. Progress only — never evidence of an
+     * approval. Monotone: once observed it is never cleared by a later, emptier
+     * poll response.
+     */
+    pushSentAt: string | null;
+    /**
+     * Server-reported ISO-8601 timestamp of when the approval route was OPENED in
+     * Commons, or `null`. Progress only — never evidence of an approval. Monotone,
+     * like {@link pushSentAt}.
+     */
+    openedAt: string | null;
+    /**
+     * The derived, ordered progress the surface renders. Always computed from the
+     * facts above by {@link deriveSignInProgress} — never assigned directly, so it
+     * cannot drift from them or run ahead of a real signal.
+     */
+    progress: SignInProgress;
 }
 /** Immutable snapshot consumed by `useSyncExternalStore`. */
 export interface AccountDialogSnapshot {
@@ -208,6 +299,18 @@ export interface AccountDialogControllerOptions {
      * `https://auth.${CENTRAL_IDP_APEX}`). Overridable for local/staging testing.
      */
     hubBaseUrl?: string;
+    /**
+     * Which surface the sign-in is initiated from — a FACT supplied by the
+     * consumer, because only the consumer can classify its own environment
+     * (native → `'mobile'`; web → `'mobile'` for a mobile browser, `'desktop'`
+     * otherwise). Headless core never sniffs a user agent or a platform global.
+     *
+     * Feeds {@link selectCommonsDelivery} verbatim. Defaults to `'unknown'`,
+     * which is a first-class value there: an unclassified surface never opts into
+     * the deep-link route, because a custom-scheme navigation that does not
+     * resolve is a dead end with no automatic way back.
+     */
+    platform?: CommonsDeliveryPlatform;
 }
 type SnapshotListener = (snapshot: AccountDialogSnapshot) => void;
 export declare class AccountDialogController {
@@ -224,6 +327,7 @@ export declare class AccountDialogController {
     private readonly socketFactory?;
     private readonly openPopup?;
     private readonly hubBaseUrl;
+    private readonly platform;
     private readonly listeners;
     private view;
     private graph;
@@ -375,8 +479,57 @@ export declare class AccountDialogController {
      * 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`).
+     *
+     * @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
+     *   passkey hub popup), where the request's Commons route is simply the QR.
      */
     private startDeviceFlowSession;
+    /**
+     * Choose and carry out the ONE primary delivery route for the active request
+     * (issue #691, "Automatic delivery selection").
+     *
+     * The controller gathers the facts — is a verified Commons link openable on
+     * THIS device, and how many known Commons installations did Oxy actually push
+     * to — and hands them to the pure {@link selectCommonsDelivery}. The selector
+     * owns the decision; this method owns only the observations and the single
+     * action the chosen route implies. It never cascades: a route that yields
+     * nothing resolves to QR *before* a route is chosen, never after.
+     */
+    private resolveDeliveryRoute;
+    /**
+     * Whether `sessionToken` is still THE request this surface is waiting on.
+     *
+     * Guards every step of the asynchronous route resolution: a cancelled,
+     * superseded, failed, or already-approved flow must neither open Commons nor
+     * mutate the surface — an approval that lands mid-resolution would otherwise
+     * be followed by a pointless app switch.
+     */
+    private isAwaitingApproval;
+    /**
+     * Ask Oxy to deliver the pending request to the identity's known Commons
+     * installations, returning how many it reached (`0` when delivery is not
+     * applicable, not permitted, or reached nobody).
+     *
+     * Two hard rules, both from the issue:
+     *  - **Never push from an unauthenticated surface.** `deliverCommonsSignIn`
+     *    is bearer-required precisely because a request that merely carries a
+     *    typed-in username must never be able to ring somebody's phone. Without a
+     *    planted bearer the call is not made AT ALL — not made-and-failed.
+     *  - **Zero targets and a failed delivery are the same normal outcome.** Both
+     *    return `0`, which resolves the primary route to QR silently. Neither is
+     *    surfaced as an error: there is nothing the user did wrong and nothing for
+     *    them to fix.
+     */
+    private deliverToKnownCommons;
+    /**
+     * Open the verified Commons link for the `'open-commons'` route. Returns
+     * whether the navigation was actually handed off, so a missing opener or a
+     * throwing one becomes an observable `routeFailed` instead of a silent dead
+     * end the user stares at.
+     */
+    private openCommonsLink;
     /**
      * Poll {@link PopupWindowHandle.closed} so a user who dismisses the hub
      * popup without completing sign-in gets prompt feedback (there is no DOM
@@ -402,14 +555,22 @@ export declare class AccountDialogController {
      */
     private resolveCommonsAvailability;
     /**
-     * When Commons is confirmed installed, deep-link straight into its approve
-     * screen via the injected `openUrl` with the same `oxycommons://approve?...`
-     * payload the QR encodes. Best-effort and non-blocking — the QR/polling
-     * fallback stays live regardless of the outcome here.
+     * Tear down the active sign-in device flow (timers + socket + popup + token),
+     * WITHDRAW the request server-side, and reset to idle.
+     *
+     * Cancellation has to converge in both directions: the surface closing must
+     * 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.
      */
-    private deepLinkIntoCommonsIfAvailable;
-    /** Tear down the active sign-in device flow (timers + socket + popup + token) and reset to idle. */
     cancelSignIn(): void;
+    /**
+     * Best-effort server-side withdrawal of a request this surface abandoned
+     * (`POST /auth/session/deny/:authorizeCode`). Fire-and-forget by design: the
+     * local teardown already happened, and a race with an approval that just
+     * landed legitimately rejects here — neither outcome is worth surfacing.
+     */
+    private withdrawRequest;
     private scheduleNextPoll;
     /**
      * Run one status check + (on approval) claim. Triggered by the fallback timer
@@ -419,6 +580,15 @@ export declare class AccountDialogController {
      * re-checks the authoritative status via `pollCommonsSignIn`.
      */
     private pollOnce;
+    /**
+     * Record server-reported delivery progress on the active flow.
+     *
+     * Monotone and additive: a timestamp is only ever adopted, never replaced or
+     * cleared, so an older API build (or a partial payload) that omits a field can
+     * at most fail to advance the surface — it can never walk it backwards.
+     * Emits only on a real change, so a steady poll does not churn the snapshot.
+     */
+    private recordDeliveryProgress;
     private claimAndComplete;
     /**
      * Commit an authorized session, notify, and return to the account list. Shared
@@ -454,7 +624,15 @@ export declare class AccountDialogController {
     private openAuthSessionSocket;
     /** Tear down the `/auth-session` socket, if any. Idempotent. */
     private closeAuthSessionSocket;
+    /**
+     * Replace the device-flow state from its FACTS, re-deriving `progress`. The
+     * only writer of `this.signIn` besides the two terminal constants — which is
+     * what keeps `progress` impossible to set by hand, and therefore impossible
+     * to advance without a fact behind it.
+     */
     private setSignIn;
+    /** Update a subset of the device-flow facts, re-deriving `progress`. */
+    private patchSignIn;
     private computeSnapshot;
     /** Recompute the snapshot and notify subscribers. */
     private emit;

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

@@ -0,0 +1,87 @@
+/**
+ * Identity pin — the durable binding between THIS device's PRIMARY identity key
+ * and the account that key authenticates as.
+ *
+ * An identity-bound client (Commons, the identity vault) must always act as the
+ * owner of the local signing key — permanently. The `DeviceSession` it shares
+ * with every other Oxy app on the same device tracks a MUTABLE `activeAccountId`
+ * that any sibling app can switch; following it silently changes both the user
+ * such a client renders and the bearer it sends. The pin is the client-side
+ * record that breaks that coupling: `{ publicKey, accountId }`, written when an
+ * identity-mode session is established (the only moment both facts are known
+ * first-hand), read on every boot, and reconciled against the live
+ * `KeyManager.getPublicKey()` before it is trusted (see
+ * `resolveIdentityPin` in `identitySession.ts`).
+ *
+ * It holds NO secret — a public key and an account id, both already known to the
+ * server — so it lives in the same per-origin storage as {@link PersistedAuthState}
+ * (`authStateStore.ts`) rather than the keychain, and mirrors that module's
+ * store shape: `load / save / clear`, an in-memory mirror, a read-back-verified
+ * durable write, and graceful degradation when storage is unavailable.
+ *
+ * ESM-safe (no `require()`); no react/react-native/expo imports.
+ */
+import type { NativeKeyValueStorage } from './authStateStore';
+/**
+ * The persisted identity binding.
+ *
+ * `publicKey` is the device's PRIMARY identity public key (lower-case hex, as
+ * `KeyManager` stores it) — never the cross-app shared-slot key, which may hold
+ * a different identity. `accountId` is the account the server resolved for that
+ * key when the session was established.
+ */
+export interface IdentityPin {
+    publicKey: string;
+    accountId: string;
+}
+/**
+ * The storage seam for {@link IdentityPin}. Async throughout so one interface
+ * fits both synchronous web `localStorage` and asynchronous native
+ * SecureStore/AsyncStorage.
+ */
+export interface IdentityPinStore {
+    load(): Promise<IdentityPin | null>;
+    /**
+     * Persist the pin and report whether it durably landed.
+     *
+     * `true` means the value is retained consistent with this store's durability
+     * guarantee (a durable backing whose read-back matched, or a degraded/in-memory
+     * store that held it in memory). `false` means a DURABLE backing was expected
+     * but the write did not land — the in-memory mirror keeps this process pinned,
+     * but the next cold boot will have to re-establish the identity session (which
+     * rewrites the pin) instead of taking the fast pinned-mint lane.
+     */
+    save(pin: IdentityPin): Promise<boolean>;
+    clear(): Promise<void>;
+}
+/**
+ * Versioned storage key. Deliberately distinct from the `oxy.auth.*` keys so a
+ * session sign-out (which clears the auth blob) and an identity change (which
+ * clears the pin) can never take each other down.
+ */
+export declare const IDENTITY_PIN_STORAGE_KEY = "oxy.identity.pin.v1";
+/**
+ * Whether `pin` still describes the identity currently on this device.
+ *
+ * `publicKey` comparison is case-insensitive (hex). A `null` local key is a
+ * definitive "no identity here" and therefore never a match — the caller clears
+ * the pin rather than binding to an account whose key is gone.
+ */
+export declare function identityPinMatches(pin: IdentityPin | null, localPublicKey: string | null): boolean;
+/**
+ * A process-lifetime, in-memory {@link IdentityPinStore}. Used directly for
+ * tests/SSR and as the degraded fallback of the web store.
+ */
+export declare function createMemoryIdentityPinStore(): IdentityPinStore;
+/**
+ * A `localStorage`-backed {@link IdentityPinStore}. Degrades to an in-memory
+ * store when `localStorage` is unreachable, and keeps an in-memory mirror so a
+ * failed persist still pins THIS page's lifetime.
+ */
+export declare function createWebIdentityPinStore(): IdentityPinStore;
+/**
+ * A native {@link IdentityPinStore} over an injected async key/value store —
+ * the same seam `createNativeAuthStateStore` uses, so `@oxyhq/core` never
+ * imports `expo-secure-store`.
+ */
+export declare function createNativeIdentityPinStore(storage: NativeKeyValueStorage): IdentityPinStore;