@oxyhq/core 12.8.0 → 12.9.0

package/dist/types/boot/sessionColdBoot.d.ts

@@ -46,6 +46,31 @@ export interface RunSessionColdBootOptions {
     /** Invoked when the boot ended signed out. */
     onSignedOut?: (reason: SignedOutReason) => void | Promise<void>;
     onStepError?: (id: string, error: unknown) => void;
+    /**
+     * HARD overall deadline (ms) for the whole ordered step chain, forwarded to
+     * {@link runColdBoot}. Defense-in-depth so a single non-settling network step
+     * (a black-hole network that neither connects nor rejects) can NEVER hang the
+     * boot — and therefore app routing — indefinitely. Inert on healthy loads
+     * (every step settles well under it); only trips on pathological networks.
+     * When omitted there is no overall deadline (unchanged behavior).
+     */
+    overallDeadlineMs?: number;
+    /**
+     * Invoked once per step abandoned because {@link overallDeadlineMs} expired
+     * before it settled. Forwarded to {@link runColdBoot}. Must not throw.
+     */
+    onStepDeadline?: (stepId: string) => void;
+    /**
+     * Best-effort connectivity hint. When it returns `true` the two NETWORK steps
+     * (`device-secret-mint`, `shared-key-signin`) are skipped — an offline device
+     * cannot mint, and attempting to would burn the whole deadline on a doomed
+     * request before routing settles. The pure-local `warm-token-plant` step is
+     * NEVER gated by this: an offline returning user with an unexpired persisted
+     * token must still boot authenticated. Only an EXPLICIT offline verdict should
+     * be returned; the caller resolves unknown/timeout to `false` (assume online)
+     * so a flaky probe can never falsely skip a real sign-in.
+     */
+    isOffline?: () => boolean;
 }
 /**
  * Run the device-first cold boot. Resolves to the `runColdBoot` outcome and, as

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

@@ -0,0 +1,94 @@
+/**
+ * Identity marker — a NON-secret, AndroidKeyStore-independent record that an
+ * identity exists (or existed) on this device.
+ *
+ * WHY THIS EXISTS: the identity private/public keys live in expo-secure-store,
+ * whose Android backing (a single `key_v1` AndroidKeyStore key by default) can be
+ * invalidated by an OS/vendor keystore event. When that happens SDK 57's
+ * expo-secure-store DELETES the undecryptable ciphertext on the read path and
+ * returns `null` — indistinguishable, from the keys alone, from a genuinely
+ * fresh install. That ambiguity is what lets a real identity get silently
+ * replaced by the onboarding "create" flow.
+ *
+ * The marker breaks the tie. It is written to AsyncStorage (RN) / localStorage
+ * (web) — storage that is NOT protected by the identity's AndroidKeyStore key —
+ * so it SURVIVES a keystore death. `getIdentityStatus()` reads it: keys empty +
+ * marker present ⇒ `lost` (route to recovery, NEVER welcome/create); keys empty
+ * + no marker ⇒ `absent` (the only path to fresh onboarding).
+ *
+ * It holds only the PUBLIC key plus provenance metadata — never any secret — so
+ * persisting it in plain KV storage adds no exposure.
+ *
+ * Every operation fails OPEN (returns null / false / resolves): the marker is a
+ * best-effort disambiguation signal layered on top of the authoritative
+ * secure-store reads, never a gate that can itself lock the user out.
+ *
+ * ESM-safe (no `require()`); zero React/RN static imports — the RN AsyncStorage
+ * module is reached only through `@oxyhq/protocol`'s per-platform dynamic loader.
+ */
+/**
+ * AsyncStorage / localStorage key holding the serialized {@link IdentityMarker}.
+ * `.v1` lets a future shape change ship a `.v2` key without misreading a stale
+ * blob. Distinct from every `oxy_identity_*` secure-store key so it never
+ * collides with the keychain material it disambiguates.
+ */
+export declare const IDENTITY_MARKER_STORAGE_KEY = "oxy_identity_marker_v1";
+/**
+ * A durable, non-secret record that an identity was provisioned on this device.
+ *
+ * `publicKey` is the identity's public key (NOT secret) — it lets recovery
+ * validate that whatever it restores is the SAME account this marker records,
+ * never a silent account switch. `origin` records how the identity came to be.
+ * `onboardingComplete` mirrors the onboarding milestone (Workstream 3.4) so a
+ * lost SecureStore milestone flag cannot re-route a real identity into the
+ * onboarding wizard.
+ */
+export interface IdentityMarker {
+    v: 1;
+    /** The identity's PUBLIC key — never secret. */
+    publicKey: string;
+    createdAt: number;
+    origin: 'create' | 'import' | 'restore' | 'backfill';
+    /** Milestone mirror: `true` once onboarding has completed for this identity. */
+    onboardingComplete?: boolean;
+}
+/** Fields accepted when creating a marker; `createdAt` defaults to now. */
+export interface WriteIdentityMarkerInput {
+    publicKey: string;
+    origin: IdentityMarker['origin'];
+    createdAt?: number;
+    onboardingComplete?: boolean;
+}
+/**
+ * Read the identity marker. Fails OPEN: returns `null` on any storage error,
+ * missing entry, or malformed blob — the caller treats "no marker" as the safe
+ * default (fresh install), and the authoritative secure-store read decides the
+ * rest.
+ */
+export declare function readIdentityMarker(): Promise<IdentityMarker | null>;
+/**
+ * Write (create/replace) the marker. Returns `true` when it durably landed,
+ * `false` when storage was unavailable or the write threw. Callers treat a
+ * `false` as non-fatal — the marker is best-effort and a subsequent read
+ * re-backfills it from the healthy key pair.
+ */
+export declare function writeIdentityMarker(input: WriteIdentityMarkerInput): Promise<boolean>;
+/**
+ * Merge a partial update into the existing marker, preserving every field the
+ * caller does not override (notably `createdAt` and `onboardingComplete`). When
+ * no marker exists yet, a partial carrying at least `publicKey` + `origin`
+ * creates one; otherwise the update is a no-op returning `false`.
+ *
+ * Used to (a) mirror the onboarding milestone (`{ onboardingComplete: true }`)
+ * without disturbing provenance, and (b) refresh `origin` on a same-identity
+ * re-persist without resetting `createdAt`.
+ */
+export declare function updateIdentityMarker(partial: Partial<Omit<IdentityMarker, 'v'>>): Promise<boolean>;
+/**
+ * Remove the marker. Called ONLY after the identity's keys have been
+ * successfully deleted (`KeyManager.deleteIdentity`), so a marker never outlives
+ * the identity it records. Fails open (swallows errors) — a leftover marker
+ * simply routes a truly-absent identity to `recovery` instead of `welcome`,
+ * which is the safe direction.
+ */
+export declare function clearIdentityMarker(): Promise<void>;

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

@@ -5,6 +5,7 @@
  * Private keys are stored securely using expo-secure-store and never leave the device.
  */
 import type { ECKeyPair } from 'elliptic';
+import { type IdentityMarker } from './identityMarker';
 /**
  * Thrown when an identity-mutating operation (createIdentity / importKeyPair)
  * is invoked while a valid identity already exists on the device.
@@ -30,6 +31,64 @@ export declare class IdentityPersistError extends Error {
     readonly name = "IdentityPersistError";
     constructor(message: string, cause?: unknown | undefined);
 }
+/**
+ * Thrown when identity storage cannot be read/written right now — the keychain
+ * is locked, the module failed to load, or a read threw — as opposed to the
+ * identity being genuinely absent.
+ *
+ * This is the crux of the corruption-vs-fresh-install fix: a storage THROW must
+ * NEVER be flattened into "no identity" (the old behavior, which let onboarding
+ * treat a momentarily-locked keystore as a blank device). Callers that used to
+ * tolerate a `false`/`null` from `hasIdentity()`/`getPublicKey()` on error must
+ * now treat this typed error as "cannot determine" — retry, surface a locked
+ * state, or abort a destructive path — never as "safe to create/overwrite".
+ */
+export declare class IdentityUnavailableError extends Error {
+    readonly cause?: unknown | undefined;
+    readonly name = "IdentityUnavailableError";
+    constructor(message: string, cause?: unknown | undefined);
+}
+/**
+ * Authoritative tri-state (plus `unavailable`) verdict on the on-device
+ * identity, from {@link KeyManager.getIdentityStatus}.
+ *
+ * - `present`  — a healthy, round-tripping key pair exists.
+ * - `absent`   — storage read succeeded and returned nothing, AND no marker
+ *                records a prior identity → a genuine fresh device. The ONLY
+ *                state that may route to create/onboarding.
+ * - `lost`     — storage read succeeded but the keys are empty/unreadable while
+ *                the independent {@link IdentityMarker} records that an identity
+ *                DID exist here → corruption/keystore death. Route to recovery,
+ *                NEVER to create.
+ * - `unavailable` — a storage read THREW (keychain locked, module load failure).
+ *                Transient by assumption; NEVER cached; callers retry.
+ */
+export type IdentityStatus = {
+    state: 'present';
+    publicKey: string;
+} | {
+    state: 'absent';
+} | {
+    state: 'lost';
+    marker: IdentityMarker;
+} | {
+    state: 'unavailable';
+    cause: unknown;
+};
+/**
+ * Result of {@link KeyManager.attemptIdentityRecovery}. On success it reports
+ * which independent, `key_v1`-surviving source restored the identity. On failure
+ * `reason` distinguishes "wasn't lost", "no surviving source", "a source held a
+ * DIFFERENT account" (never silently switched), and "storage unavailable".
+ */
+export type IdentityRecoveryResult = {
+    recovered: true;
+    source: 'backup' | 'shared';
+    publicKey: string;
+} | {
+    recovered: false;
+    reason: 'not-lost' | 'no-sources' | 'mismatch' | 'unavailable';
+};
 export interface KeyPair {
     publicKey: string;
     privateKey: string;
@@ -39,11 +98,86 @@ export declare class KeyManager {
     private static cachedHasIdentity;
     private static cachedSharedPublicKey;
     private static cachedHasSharedIdentity;
+    /**
+     * Distinguishes "public key genuinely absent (a successful empty read, safe to
+     * cache)" from "never resolved / storage threw (must NOT be cached)". A `null`
+     * {@link cachedPublicKey} alone is ambiguous — this flag makes the genuine
+     * absence cacheable WITHOUT ever caching a null produced by a thrown read.
+     */
+    private static cachedPublicKeyResolved;
+    /** Listeners notified synchronously whenever the identity verdict may have changed. */
+    private static readonly identityChangeListeners;
+    /**
+     * Memoized one-run-per-process slot migration. `slotMigrationResult` caches a
+     * STABLE outcome (`v2`/`legacy`); a `deferred` outcome is intentionally not
+     * cached (the in-flight promise is cleared) so a later call retries once the
+     * keychain unlocks.
+     */
+    private static slotMigrationPromise;
+    private static slotMigrationResult;
     /**
      * Invalidate cached identity state
      * Called internally when identity is created/deleted/imported
      */
     private static invalidateCache;
+    /**
+     * Subscribe to identity-verdict changes (create / import / delete / restore /
+     * cache invalidation). Fires synchronously; the returned function unsubscribes.
+     * Consumed via `useOxyEvent`-style hooks in commons to invalidate the routing
+     * queries the instant the identity state moves, without polling.
+     */
+    static subscribeIdentityChanged(listener: () => void): () => void;
+    /** Synchronous fan-out with per-listener isolation (one throwing listener never blocks the rest). */
+    private static notifyIdentityChanged;
+    /** Build `getItemAsync`/`deleteItemAsync` options for a given keychain service (read/delete). */
+    private static _slotOpts;
+    /** Build private-key write options (device-only accessibility) for a given keychain service. */
+    private static _privateWriteOpts;
+    /** True only when both keys are present, well-formed, AND the public derives from the private. */
+    private static _isHealthyPair;
+    /**
+     * Resolve the AsyncStorage-backed KV store for the advisory migration flag, or
+     * `null` off-RN / when unavailable. Independent of the keychain, so the flag
+     * cannot be taken down by the keystore event this whole subsystem defends
+     * against.
+     */
+    private static _advisoryStorage;
+    private static _readSlotsMigratedFlag;
+    private static _setSlotsMigratedFlag;
+    /**
+     * Ensure the identity has been migrated onto the isolated v2 slots (or that we
+     * know we must read legacy this session). Memoized so concurrent callers share
+     * ONE run; a `deferred` (read-threw) outcome is not cached so a later call
+     * retries after the keychain unlocks. Every identity-slot accessor awaits this
+     * before touching storage.
+     */
+    private static _ensureIdentitySlotsMigrated;
+    /**
+     * One-shot slot migration state machine. All reads are DIRECT and a thrown
+     * read defers everything (zero writes/deletes) so a locked keychain is never
+     * mistaken for an empty one. INVARIANT: at every instant ≥1 readable copy of a
+     * previously-existing identity remains — legacy is deleted ONLY after the v2
+     * copy is verified re-readable in its new (non-aliasable) location.
+     */
+    private static _runSlotMigration;
+    /**
+     * Seed the v2 backup slot during migration. Prefers a healthy legacy backup;
+     * otherwise mirrors the (already-verified) v2 primary material so a v2 backup
+     * always exists on an independent keychain key. Best-effort — a failure just
+     * defers backup population to the next {@link _persistIdentityAtomic}.
+     */
+    private static _migrateBackupSlotToV2;
+    /** Best-effort single delete under an optional keychain service. Cleanup only — never surfaces. */
+    private static _bestEffortDelete;
+    private static _bestEffortDeleteV2Primary;
+    private static _bestEffortDeleteLegacyPrimaryAndBackup;
+    private static _bestEffortDeleteBackupsAllGenerations;
+    /**
+     * Clear the cross-app shared identity slot (force-delete only) so a deleted
+     * identity cannot be resurrected via the recovery ladder's shared rung.
+     * Best-effort — the shared slot is a redundant convenience copy.
+     */
+    private static _clearSharedSlot;
     /**
      * Invalidate cached shared identity state
      * Called internally when shared identity is created/deleted/imported
@@ -186,6 +320,15 @@ export declare class KeyManager {
      * @internal
      */
     private static _persistIdentityAtomic;
+    /**
+     * Write/refresh the identity marker after a successful persist. A same-identity
+     * re-persist (e.g. backup refresh, idempotent re-import) preserves `createdAt`
+     * and the `onboardingComplete` milestone by only updating `origin`; a NEW or
+     * switched identity writes a fresh marker. Best-effort — never throws.
+     *
+     * @internal
+     */
+    private static _syncMarkerAfterPersist;
     /**
      * Restore the backup slot to a previously-snapshotted state. Best-effort so
      * the original persistence error remains the one surfaced to the caller.
@@ -215,6 +358,15 @@ export declare class KeyManager {
     static createIdentity(options?: {
         overwrite?: boolean;
     }): Promise<string>;
+    /**
+     * Read the primary key pair DIRECTLY from storage, bypassing the in-memory
+     * cache (which a prior transient failure could have poisoned). Awaits slot
+     * migration first. Throws {@link IdentityUnavailableError} if storage is
+     * deferred/locked or a read throws — so overwrite guards never write blind.
+     *
+     * @internal
+     */
+    private static _readPrimaryDirect;
     /**
      * Import an existing key pair (e.g., from recovery phrase).
      *
@@ -229,10 +381,19 @@ export declare class KeyManager {
     /**
      * Get the stored private key
      * WARNING: Only use this for signing operations within the app
+     *
+     * Preserves the "return null on any storage failure" contract signing paths
+     * rely on (a locked keychain simply means "cannot sign now"); unlike
+     * {@link getPublicKey}, it does NOT throw {@link IdentityUnavailableError}.
      */
     static getPrivateKey(): Promise<string | null>;
     /**
-     * Get the stored public key (cached for performance)
+     * Get the stored public key (cached for performance).
+     *
+     * Returns the public key, or `null` when a read SUCCEEDS and finds none.
+     * THROWS {@link IdentityUnavailableError} when storage is unreadable (keychain
+     * locked / module load failure) — a thrown read is NEVER flattened to `null`
+     * and NEVER cached, so a poisoned "no identity" verdict can no longer stick.
      */
     static getPublicKey(): Promise<string | null>;
     /**
@@ -240,13 +401,35 @@ export declare class KeyManager {
      *
      * Returns `true` only when BOTH the private and public keys are present,
      * both are well-formed, AND the public key derives from the private key.
-     * A partially-written or corrupted identity returns `false` so that
-     * downstream code can resume the create / restore flow correctly.
+     * A partially-written or corrupted identity (read succeeded, bytes empty/bad)
+     * returns `false` so that downstream code can resume the create / restore flow.
+     * THROWS {@link IdentityUnavailableError} when storage is unreadable — a locked
+     * keychain must never be mistaken for "no identity" (the old behavior that let
+     * onboarding treat a transient lock as a blank device).
      *
      * Note: this does NOT perform the full sign/verify roundtrip — call
      * `verifyIdentityIntegrity()` for that.
      */
     static hasIdentity(): Promise<boolean>;
+    /**
+     * Authoritative identity verdict — the corruption-vs-fresh-install
+     * disambiguator that routing (commons) keys off of.
+     *
+     * - Healthy pair → `present` (and the marker is backfilled if missing or
+     *   pointing at a different key, `origin: 'backfill'`).
+     * - Read succeeded but no healthy pair, WITH a marker → `lost` (keystore death
+     *   / corruption; route to recovery, NEVER to create).
+     * - Read succeeded, no pair, NO marker → `absent` (a genuine fresh device; the
+     *   only state that may route to onboarding/create).
+     * - A read THREW → `unavailable` (keychain locked); this verdict is NEVER
+     *   cached, so a later call re-reads.
+     *
+     * @param opts.bypassCache When true, never reads OR writes the in-memory cache
+     *   — a pure, fresh storage verdict for the auto-create interlock preflight.
+     */
+    static getIdentityStatus(opts?: {
+        bypassCache?: boolean;
+    }): Promise<IdentityStatus>;
     /**
      * Delete the stored identity (both keys)
      * Use with EXTREME caution - this is irreversible without a recovery phrase
@@ -290,6 +473,32 @@ export declare class KeyManager {
      * conflicting key material is present) do we rebuild it from the backup.
      */
     static restoreIdentityFromBackup(): Promise<boolean>;
+    /**
+     * Recovery ladder — restore a `lost` identity from an independent,
+     * `key_v1`-surviving source WITHOUT the user re-entering their recovery phrase.
+     *
+     * Gated on {@link getIdentityStatus} being `lost` (marker present, keys empty):
+     *   - `present` / `absent` → `not-lost` (nothing to recover / nothing lost)
+     *   - `unavailable`        → `unavailable` (keychain locked; retry later)
+     *
+     * Rungs, tried in order, each fully validated (well-formed + derive-match +
+     * `publicKey === marker.publicKey`, so a source holding a DIFFERENT account is
+     * SKIPPED, never restored):
+     *   1. the v2 backup slot (independent keychain key from the primary), then
+     *   2. the cross-app shared slot (Android bridge `getShared` / iOS keychain
+     *      group) — the copy that survives a primary+backup `key_v1` death.
+     *
+     * On success it re-persists via {@link _persistIdentityAtomic} (origin
+     * `'restore'`) and invalidates the cache so routing re-reads `present`. When no
+     * rung matches, the UI proceeds to recovery-phrase entry.
+     */
+    static attemptIdentityRecovery(): Promise<IdentityRecoveryResult>;
+    /** Read the active-layout backup slot as a healthy candidate, or null. @internal */
+    private static _readBackupCandidate;
+    /** Read the cross-app shared slot as a healthy candidate, or null. @internal */
+    private static _readSharedCandidate;
+    /** Persist a validated recovery candidate + refresh caches/subscribers. @internal */
+    private static _commitRecovery;
     /**
      * Get the elliptic curve key object from the stored private key
      * Used internally for signing operations

package/dist/types/index.d.ts

@@ -47,8 +47,10 @@ export { SessionSyncRequiredError, AuthenticationFailedError, ensureValidToken,
 export type { HandleApiErrorOptions } from './utils/authHelpers';
 export { mergeSessions, normalizeAndSortSessions, sessionsArraysEqual, } from './utils/sessionUtils';
 export type { ClientSession, StorageKeys, MinimalUserData, SessionLoginResponse, } from './models/session';
-export { KeyManager, IdentityAlreadyExistsError, IdentityPersistError, } from './crypto/keyManager';
-export type { KeyPair } from './crypto/keyManager';
+export { KeyManager, IdentityAlreadyExistsError, IdentityPersistError, IdentityUnavailableError, } from './crypto/keyManager';
+export type { KeyPair, IdentityStatus, IdentityRecoveryResult } from './crypto/keyManager';
+export { readIdentityMarker, updateIdentityMarker, } from './crypto/identityMarker';
+export type { IdentityMarker } from './crypto/identityMarker';
 export { SignatureService } from './crypto/signatureService';
 export type { SignedMessage, AuthChallenge } from './crypto/signatureService';
 export { RecoveryPhraseService } from './crypto/recoveryPhrase';

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

@@ -258,8 +258,15 @@ export declare function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(B
          * The client must sign this challenge with their private key
          *
          * @param publicKey - The user's public key
+         * @param requestOptions - Optional per-call transport overrides (`retry`,
+         *   `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.
          */
-        requestChallenge(publicKey: string): Promise<ChallengeResponse>;
+        requestChallenge(publicKey: string, requestOptions?: {
+            retry?: boolean;
+            timeout?: number;
+        }): Promise<ChallengeResponse>;
         /**
          * Verify a signed challenge and create a session
          *
@@ -269,8 +276,15 @@ export declare function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(B
          * @param timestamp - Timestamp when the signature was created
          * @param deviceName - Optional device name
          * @param deviceFingerprint - Optional device fingerprint
+         * @param requestOptions - Optional per-call transport overrides (`retry`,
+         *   `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.
          */
-        verifyChallenge(publicKey: string, challenge: string, signature: string, timestamp: number, deviceName?: string, deviceFingerprint?: string): Promise<SessionLoginResponse>;
+        verifyChallenge(publicKey: string, challenge: string, signature: string, timestamp: number, deviceName?: string, deviceFingerprint?: string, requestOptions?: {
+            retry?: boolean;
+            timeout?: number;
+        }): Promise<SessionLoginResponse>;
         /**
          * Check if a public key is already registered
          */
@@ -333,10 +347,21 @@ export declare function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(B
          *
          * The cold-boot wiring that CALLS this lives in `OxyContext`
          * (`@oxyhq/services`); this method just performs the exchange.
+         *
+         * @param opts.requestOptions - Optional per-call transport overrides
+         *   (`retry`, `timeout`) forwarded to BOTH the `requestChallenge` and
+         *   `verifyChallenge` round-trips. Interactive flows omit it (defaults keep
+         *   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.
          */
         signInWithSharedIdentity(opts?: {
             deviceName?: string;
             deviceFingerprint?: string;
+            requestOptions?: {
+                retry?: boolean;
+                timeout?: number;
+            };
         }): Promise<SessionLoginResponse | null>;
         /**
          * MECHANISM B (relying party) — begin a "Sign in with Oxy" handoff.

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

@@ -30,6 +30,14 @@ export declare function OxyServicesDeviceBootMixin<T extends typeof OxyServicesB
          * `no_active_session`) to decide whether to drop the secret and fall back or
          * resolve signed-out.
          *
+         * `retry: false`: the mint is a single logical attempt. The proactive
+         * token-refresh scheduler and the reactive 401 lane already own backoff and
+         * re-arm, so `HttpService`'s inner retry loop here would only multiply the
+         * mint's latency on a slow/black-hole network (3 retries × 5s timeout ≈ 20s
+         * per lane) with no correctness benefit — it is the dominant term in the cold
+         * boot's worst-case time-to-route. A transient failure surfaces once and the
+         * scheduler/401 path retries it later.
+         *
          * @throws if the response does not match {@link deviceTokenMintResponseSchema}.
          */
         mintFromDeviceSecret(deviceId: string, deviceSecret: string): Promise<DeviceTokenMintResponse>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/core",
-  "version": "12.8.0",
+  "version": "12.9.0",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",

package/src/boot/__tests__/sessionColdBoot.test.ts

@@ -455,3 +455,116 @@ describe('runSessionColdBoot — signed out', () => {
     expect(setTokens).not.toHaveBeenCalled();
   });
 });
+
+describe('runSessionColdBoot — offline gating (isOffline)', () => {
+  /** Comfortably beyond the 60s refresh lead window. */
+  const farFuture = () => new Date(Date.now() + 3_600_000).toISOString();
+
+  const sharedSession: SessionLoginResponse = {
+    sessionId: 'sess-shared',
+    deviceId: 'dev-1',
+    expiresAt: '2030-01-01T00:00:00.000Z',
+    user: { id: 'user-shared', username: 'u', name: {}, avatar: undefined },
+    accessToken: 'access-shared',
+  };
+
+  it('offline: skips BOTH network steps (no mint, no shared-key) → signed out', async () => {
+    // Credential present, no warm token — the ONLY things that could resolve are
+    // the two network steps, which the offline hint must gate off.
+    const { store, seed } = seedCredStore();
+    await seed();
+    const mintFromDeviceSecret = jest.fn(async () => MINT);
+    const signInWithSharedIdentity = jest.fn(async () => sharedSession);
+    const { oxy } = makeOxy({ mintFromDeviceSecret, signInWithSharedIdentity });
+    const onSignedOut = jest.fn();
+
+    const outcome = await runSessionColdBoot({
+      oxy,
+      store,
+      platform: NATIVE,
+      isOffline: () => true,
+      onSignedOut,
+    });
+
+    expect(outcome).toEqual({ kind: 'unauthenticated' });
+    expect(mintFromDeviceSecret).not.toHaveBeenCalled();
+    expect(signInWithSharedIdentity).not.toHaveBeenCalled();
+    expect(onSignedOut).toHaveBeenCalledWith('no_session');
+  });
+
+  it('offline: the pure-local warm-token-plant STILL runs (returning user boots authenticated offline)', async () => {
+    const { store, seed } = seedCredStore({ accessToken: 'warm-access', expiresAt: farFuture() });
+    await seed();
+    const mintFromDeviceSecret = jest.fn(async () => MINT);
+    const { oxy, setTokens } = makeOxy({ mintFromDeviceSecret });
+
+    const outcome = await runSessionColdBoot({
+      oxy,
+      store,
+      platform: NATIVE,
+      isOffline: () => true,
+    });
+
+    // Warm plant is a pure-local read — never gated by the offline hint.
+    expect(outcome).toMatchObject({ kind: 'session', via: 'warm-token-plant' });
+    expect(setTokens).toHaveBeenCalledWith('warm-access');
+    expect(mintFromDeviceSecret).not.toHaveBeenCalled();
+  });
+
+  it('online (isOffline:()=>false): the network mint runs as normal', async () => {
+    const { store, seed } = seedCredStore();
+    await seed();
+    const mintFromDeviceSecret = jest.fn(async () => MINT);
+    const { oxy } = makeOxy({ mintFromDeviceSecret });
+
+    const outcome = await runSessionColdBoot({
+      oxy,
+      store,
+      platform: WEB,
+      isOffline: () => false,
+    });
+
+    expect(outcome).toMatchObject({ kind: 'session', via: 'device-secret-mint' });
+    expect(mintFromDeviceSecret).toHaveBeenCalledWith('dev-mint', 'ds-secret-orig');
+  });
+
+  it('shared-key-signin passes { requestOptions: { retry: false } } (cold-boot single-attempt)', async () => {
+    const store = createMemoryAuthStateStore(); // no mint credential → mint step no-secret skip
+    const signInWithSharedIdentity = jest.fn(async () => sharedSession);
+    const { oxy } = makeOxy({ signInWithSharedIdentity });
+
+    const outcome = await runSessionColdBoot({ oxy, store, platform: NATIVE });
+
+    expect(outcome).toMatchObject({ kind: 'session', via: 'shared-key-signin' });
+    expect(signInWithSharedIdentity).toHaveBeenCalledWith({ requestOptions: { retry: false } });
+  });
+});
+
+describe('runSessionColdBoot — overall deadline (overallDeadlineMs + onStepDeadline)', () => {
+  it('forwards the deadline: a non-settling mint step is abandoned via onStepDeadline and the boot ends bounded', async () => {
+    const { store, seed } = seedCredStore();
+    await seed();
+    // A mint that NEVER settles — without the overall deadline this hangs the
+    // whole boot (and therefore app routing) forever.
+    const mintFromDeviceSecret = jest.fn(
+      () => new Promise<DeviceTokenMintResponse>(() => undefined),
+    );
+    const { oxy } = makeOxy({ mintFromDeviceSecret });
+    const onStepDeadline = jest.fn();
+    const onSignedOut = jest.fn();
+
+    const outcome = await runSessionColdBoot({
+      oxy,
+      store,
+      platform: WEB,
+      overallDeadlineMs: 50,
+      onStepDeadline,
+      onSignedOut,
+    });
+
+    expect(outcome).toEqual({ kind: 'unauthenticated' });
+    expect(onStepDeadline).toHaveBeenCalledWith('device-secret-mint');
+    // A deadline trip is not an error — the boot resolves signed-out, not `error`.
+    expect(onSignedOut).toHaveBeenCalledWith('no_session');
+  });
+});