@oxyhq/core 12.10.6 → 12.11.0

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;

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

@@ -0,0 +1,105 @@
+/**
+ * Identity-bound session — pin reconciliation + establishment.
+ *
+ * This is the SDK half of "an identity vault's authenticated user is whoever
+ * owns the local primary key". Two operations, both consumed by the cold boot
+ * (`boot/sessionColdBoot.ts`) and the re-mint lane (`session/refresh.ts`):
+ *
+ *  - {@link resolveIdentityPin} — read the persisted `{publicKey, accountId}`
+ *    pin and reconcile it against the identity currently on this device. A
+ *    definitive mismatch (the key was replaced, or is gone) CLEARS the pin; an
+ *    INDETERMINATE read (keychain locked / storage threw) leaves it untouched.
+ *  - {@link establishIdentitySession} — mint a session from the PRIMARY local
+ *    key (`getPublicKey` → `requestChallenge` → `signChallenge` →
+ *    `verifyChallenge`), persist the resulting device credential, and write the
+ *    pin. This is the identity-mode replacement for the shared-keychain lane,
+ *    which reads the CROSS-APP shared slot and may therefore hold a different
+ *    identity than this device's primary.
+ *
+ * Both take their key/signature functions from an injectable {@link IdentityBinding}
+ * (defaulting to `KeyManager` / `SignatureService`) so the lanes above stay
+ * testable without a keychain.
+ *
+ * ESM-safe (no `require()`); no react/react-native/expo imports.
+ */
+import type { OxyServices } from '../OxyServices';
+import type { AuthStateStore } from './authStateStore';
+import type { SessionLoginResponse } from '../models/session';
+import { type AuthChallenge } from '../crypto/signatureService';
+import { type IdentityPin, type IdentityPinStore } from './identityPin';
+/** Per-call transport overrides forwarded to the challenge/verify round-trips. */
+export interface IdentityRequestOptions {
+    retry?: boolean;
+    timeout?: number;
+}
+/**
+ * Everything an identity-bound client needs to resolve and re-establish its
+ * session. `@oxyhq/services` builds one of these (platform-appropriate pin
+ * store) and passes it to the cold boot and the refresh handler.
+ */
+export interface IdentityBinding {
+    /** Where the `{publicKey, accountId}` pin is persisted. */
+    pinStore: IdentityPinStore;
+    /**
+     * Reads this device's PRIMARY identity public key. Defaults to
+     * `KeyManager.getPublicKey()`. NEVER the shared-slot key.
+     */
+    readPublicKey?: () => Promise<string | null>;
+    /**
+     * Signs a server challenge with the PRIMARY local private key. Defaults to
+     * `SignatureService.signChallenge`.
+     */
+    signChallenge?: (challenge: string) => Promise<AuthChallenge>;
+    /** Optional device labels forwarded to `verifyChallenge`. */
+    deviceName?: string;
+    deviceFingerprint?: string;
+}
+/** The result of a successful {@link establishIdentitySession}. */
+export interface EstablishedIdentitySession {
+    session: SessionLoginResponse;
+    /** The pin as written: the local key plus the account the server resolved for it. */
+    pin: IdentityPin;
+}
+/**
+ * Read the persisted pin and reconcile it against the identity on this device.
+ *
+ * Returns the pin ONLY when the local primary public key still matches it — that
+ * is the single condition under which a client may bind its token and its
+ * rendered user to that account.
+ *
+ * Outcomes:
+ *  - no pin stored → `null` (nothing to clear).
+ *  - local key MATCHES → the pin (trusted).
+ *  - local key read succeeded and differs / is absent → the identity was
+ *    replaced or lost: CLEAR the pin and return `null`. Keeping it would pin the
+ *    client to an account it can no longer prove control of.
+ *  - the local key read THREW (keychain locked, storage unavailable) → return
+ *    `null` WITHOUT clearing. A read that produced no verdict is never evidence
+ *    of an identity change (the same rule `KeyManager` applies to its own
+ *    transient errors); the caller falls through to the identity sign-in lane,
+ *    which fails closed on a locked keychain rather than adopting a foreign
+ *    account.
+ */
+export declare function resolveIdentityPin(binding: IdentityBinding): Promise<IdentityPin | null>;
+/**
+ * Establish a session for the device's PRIMARY identity key and pin it.
+ *
+ * `requestChallenge` → `signChallenge` → `verifyChallenge`; `verifyChallenge`
+ * plants the access token itself. The server resolves the account from the
+ * VERIFIED SIGNER, so the returned session is identity-authoritative — it
+ * ignores the device's `activeAccountId` entirely.
+ *
+ * Side effects on success: the durable device credential is persisted (so the
+ * next boot can take the fast pinned-mint lane) and the pin is written.
+ *
+ * Returns `null` — never throws — for the two "nothing to do" cases: no local
+ * identity (including every web caller, where `KeyManager` has no key), and a
+ * verify that produced no access token. Network/crypto failures propagate so the
+ * caller can classify them.
+ */
+export declare function establishIdentitySession(args: {
+    oxy: OxyServices;
+    store: AuthStateStore;
+    binding: IdentityBinding;
+    requestOptions?: IdentityRequestOptions;
+}): Promise<EstablishedIdentitySession | null>;

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

@@ -1,17 +1,6 @@
 import type { DeviceSessionState } from '@oxyhq/contracts';
 import type { ClientSession } from '../models/session';
 import type { User } from '../models/interfaces';
-/**
- * Pure projection helpers: `DeviceSessionState` (the device-scoped
- * multi-account session-sync state produced by `SessionClient`) -> the
- * shapes `@oxyhq/services` consumers render today
- * (`ClientSession[]`, an active session id, an active `User`).
- *
- * No I/O. The caller fetches profiles via
- * `oxyServices.getUsersByIds(accountIdsOf(state))` and builds `usersById`
- * from the result before calling `deviceStateToClientSessions` /
- * `activeUserOf`.
- */
 /**
  * Maps every `SessionAccount` in `state.accounts` to a `ClientSession`.
  *
@@ -23,19 +12,32 @@ import type { User } from '../models/interfaces';
  * though `ClientSession` only stores `userId` — a session is still
  * projected for an account whose id is absent from `usersById` (no
  * placeholder user is fabricated).
+ *
+ * `isCurrent` marks the PINNED account when one is supplied, so it can never
+ * disagree with {@link activeSessionIdOf} / {@link activeUserOf} for the same
+ * pin.
  */
-export declare function deviceStateToClientSessions(state: DeviceSessionState, usersById: Map<string, User>): ClientSession[];
+export declare function deviceStateToClientSessions(state: DeviceSessionState, usersById: Map<string, User>, pinnedAccountId?: string | null): ClientSession[];
 /**
- * The active account's `sessionId`, or `null` when there is no state or no
- * active account is set.
+ * The bound account's `sessionId`, or `null` when there is no state, no bound
+ * account, or that account has no session on this device.
+ *
+ * A pinned account that is ABSENT from `state.accounts` yields `null` — the
+ * honest signal that this device no longer carries a session for the pinned
+ * identity, which the caller answers by re-establishing the identity session
+ * (never by adopting the device's active account).
  */
-export declare function activeSessionIdOf(state: DeviceSessionState | null): string | null;
+export declare function activeSessionIdOf(state: DeviceSessionState | null, pinnedAccountId?: string | null): string | null;
 /**
- * The active account's `User`, resolved from `usersById`. `null` when there
- * is no state, no active account is set, or the active account id is absent
- * from `usersById`.
+ * The bound account's `User`, resolved from `usersById`. `null` when there is no
+ * state, no bound account, or the bound account id is absent from `usersById`.
+ *
+ * A pinned user is resolved from `usersById` alone — deliberately NOT gated on
+ * device membership — so a transient device-state gap cannot flicker the
+ * identity vault's rendered user. Whether the pinned session still exists on the
+ * device is answered by {@link activeSessionIdOf}.
  */
-export declare function activeUserOf(state: DeviceSessionState | null, usersById: Map<string, User>): User | null;
+export declare function activeUserOf(state: DeviceSessionState | null, usersById: Map<string, User>, pinnedAccountId?: string | null): User | null;
 /**
  * All account ids in `state`, suitable for an `oxyServices.getUsersByIds(...)`
  * fetch. `[]` for `null` state.