@oxyhq/core 8.0.0 → 9.0.0

package/dist/types/HttpService.d.ts

@@ -30,13 +30,13 @@ export interface RequestOptions {
      * Skip BOTH the bearer auth header (and its near-expiry preflight refresh)
      * AND the 401-driven auto-refresh/retry for this request.
      *
-     * Required for the body-authenticated refresh endpoint (`POST
-     * /auth/refresh-token`): it does not need a bearer, and — critically — it is
+     * Required for the body-authenticated device-secret mint (`POST
+     * /session/device/token`): it does not need a bearer, and — critically — it is
      * itself invoked from inside the registered `AuthRefreshHandler`. If it went
      * through the normal preflight, `getAuthHeader` would call
      * `refreshAccessToken` while the handler-owning `tokenRefreshPromise` is
      * still in flight and await ITSELF (deadlock). Skipping auth makes the
-     * refresh call fully independent of the current (near-expired) bearer.
+     * mint call fully independent of the current (near-expired) bearer.
      */
     skipAuth?: boolean;
 }

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

@@ -1,36 +1,32 @@
+/**
+ * coldBootV2 — one device-first cold boot for every consumer.
+ *
+ * On a fresh page load / app launch this resolves the device's session in a
+ * deterministic order, built on the pure `runColdBoot` primitive. It NEVER
+ * redirects to a login page: an unresolved boot ends in a signed-out state that
+ * the app renders with a "Sign in with Oxy" button.
+ *
+ * Ordered steps (first to yield a session wins):
+ *   1. `device-secret-mint` (web + native) — the zero-cookie transport: when the
+ *      origin persisted a `deviceId` + `deviceSecret`, mint a short access token
+ *      with a single bearer-less POST to `/session/device/token` (no cookie, no
+ *      navigation) and rotate the secret in-use.
+ *   2. `shared-key-signin` (native) — re-mint from the shared-keychain identity.
+ *   3. Signed out.
+ *
+ * ESM-safe (no `require()`); no react/react-native/expo imports.
+ */
 import { type ColdBootOutcome } from '../utils/coldBoot';
 import type { OxyServices } from '../OxyServices';
 import type { AuthStateStore } from '../session/authStateStore';
-import { type DeviceBootSession } from './deviceBootReturn';
-/**
- * localStorage flag marking that the cross-apex bootstrap navigation has fired
- * once for this origin. Persistent (not session) so the visible redirect
- * happens AT MOST ONCE EVER per browser+origin — a signed-out user is never
- * bounced again; they sign in explicitly.
- */
-export declare const BOOT_ATTEMPTED_KEY = "oxy.boot.attempted";
-/** Why a cold boot ended without a session. */
-export type SignedOutReason = 'no_session' | 'new_device' | 'state-mismatch' | 'error';
-/**
- * The DOM/storage seam. All access is injected so the boot is unit-testable
- * under the jest `node` environment; {@link createBrowserColdBootDom} provides
- * the guarded real-globals implementation used in production.
- */
-export interface ColdBootDom {
-    getHash(): string;
-    stripFragment(): void;
-    getSessionItem(key: string): string | null;
-    setSessionItem(key: string, value: string): void;
-    removeSessionItem(key: string): void;
-    getLocalItem(key: string): string | null;
-    setLocalItem(key: string, value: string): void;
-    getLocationHostname(): string | null;
-    /** Current href WITHOUT its hash fragment (the bootstrap `return_to`). */
-    getReturnToHref(): string | null;
-    navigate(url: string): void;
-    /** A fresh high-entropy CSRF state token. */
-    randomState(): string;
+/** The winning session shape a cold-boot step reports. */
+export interface DeviceBootSession {
+    sessionId: string;
+    userId: string;
+    accessToken: string;
 }
+/** Why a cold boot ended without a session. */
+export type SignedOutReason = 'no_session' | 'error';
 export interface RunSessionColdBootOptions {
     oxy: OxyServices;
     store: AuthStateStore;
@@ -39,38 +35,17 @@ export interface RunSessionColdBootOptions {
         isWeb?: boolean;
         isNative?: boolean;
     };
-    /**
-     * The RP return URL for the cross-apex hop. Defaults to the current href
-     * (sans fragment) via the DOM seam.
-     */
-    returnTo?: string;
     /** Invoked with the winning session (token already planted). */
     onSession?: (session: DeviceBootSession & {
         via: string;
     }) => void | Promise<void>;
-    /** Invoked when the boot ended signed out (not while navigating away). */
+    /** Invoked when the boot ended signed out. */
     onSignedOut?: (reason: SignedOutReason) => void | Promise<void>;
     onStepError?: (id: string, error: unknown) => void;
-    /** DOM/storage seam; defaults to the guarded browser implementation. */
-    dom?: ColdBootDom;
 }
-/**
- * The guarded real-globals {@link ColdBootDom}. Every accessor tolerates a
- * missing/throwing global (SSR, sandboxed iframe) by returning a neutral value
- * or no-op, so the boot degrades to signed-out rather than crashing.
- */
-export declare function createBrowserColdBootDom(): ColdBootDom;
-/**
- * True when both hosts are same-site / same-apex. For a normal multi-label host
- * pair, that means sharing a registrable domain. For an IP literal or a
- * single-label host (no registrable domain), same-apex requires the two hosts
- * to be EXACTLY equal — never grouped by a spurious trailing-label match.
- */
-export declare function isSameApex(pageHost: string, apiHost: string): boolean;
 /**
  * Run the device-first cold boot. Resolves to the `runColdBoot` outcome and, as
- * a side effect, invokes `onSession` (winning session, token already planted)
- * or `onSignedOut` (no session — unless the boot is navigating away for the
- * cross-apex hop, in which case neither fires).
+ * a side effect, invokes `onSession` (winning session, token already planted) or
+ * `onSignedOut` (no session).
  */
 export declare function runSessionColdBoot(opts: RunSessionColdBootOptions): Promise<ColdBootOutcome<DeviceBootSession>>;

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

@@ -157,27 +157,6 @@ export declare class KeyManager {
      * @returns True if migration was successful, false if no local identity exists
      */
     static migrateToSharedIdentity(): Promise<boolean>;
-    /**
-     * Store the opaque device-attribution token in the SHARED keychain so every
-     * Oxy app on this device reads the SAME token and therefore resolves to one
-     * server-side DeviceSession.
-     *
-     * Mirrors the shared-session storage options exactly (iOS keychain access
-     * group `group.so.oxy.shared`; Android shared secure store). Native-only —
-     * a no-op on web (the shared keychain does not exist there; web persists its
-     * deviceToken in the per-origin {@link AuthStateStore} instead).
-     */
-    static setSharedDeviceToken(deviceToken: string): Promise<void>;
-    /**
-     * Read the shared device-attribution token, or `null` when none is set (or
-     * on web). Mirrors {@link getSharedSession}'s keychain-access-group read.
-     */
-    static getSharedDeviceToken(): Promise<string | null>;
-    /**
-     * Delete the shared device-attribution token (device signout-all). Best-effort:
-     * a keychain failure is logged, not thrown, so it cannot block a sign-out.
-     */
-    static clearSharedDeviceToken(): Promise<void>;
     /**
      * Atomically persist a key pair to secure storage with verification + backup.
      *

package/dist/types/index.d.ts

@@ -95,14 +95,12 @@ export { projectSwitchableAccounts, switchableAccountIds, } from './session/acco
 export type { SwitchableAccount, SwitchableAccountUser, ProjectSwitchableAccountsInput, } from './session/accountProjection';
 export { AccountDialogController, createAccountDialogController, } from './session/accountDialogController';
 export type { AccountDialogControllerOptions, AccountDialogSnapshot, AccountDialogView, SignInFlowPhase, SignInFlowState, } from './session/accountDialogController';
-export { createWebAuthStateStore, createNativeAuthStateStore, createMemoryAuthStateStore, AUTH_STATE_STORAGE_KEY, DEVICE_TOKEN_STORAGE_KEY, } from './session/authStateStore';
+export { createWebAuthStateStore, createNativeAuthStateStore, createMemoryAuthStateStore, AUTH_STATE_STORAGE_KEY, } from './session/authStateStore';
 export type { PersistedAuthState, AuthStateStore, NativeKeyValueStorage, } from './session/authStateStore';
 export { refreshPersistedSession, createAuthRefreshHandler, installAuthRefreshHandler, startTokenRefreshScheduler, TOKEN_REFRESH_LEAD_MS, } from './session/refresh';
 export type { RefreshDeps, TokenRefreshSchedulerHandle } from './session/refresh';
-export { runSessionColdBoot, createBrowserColdBootDom, isSameApex, BOOT_ATTEMPTED_KEY, } from './boot/coldBootV2';
-export type { RunSessionColdBootOptions, ColdBootDom, SignedOutReason, } from './boot/coldBootV2';
-export { consumeDeviceBootReturn, parseDeviceBootFragment, hashHasBootFragment, BOOT_FRAGMENT_PARAM, BOOT_STATE_SESSION_KEY, } from './boot/deviceBootReturn';
-export type { DeviceBootSession, DeviceBootReturnOutcome, ConsumeDeviceBootReturnDeps, } from './boot/deviceBootReturn';
+export { runSessionColdBoot } from './boot/coldBootV2';
+export type { RunSessionColdBootOptions, SignedOutReason, DeviceBootSession, } from './boot/coldBootV2';
 export { packageInfo } from './constants/version';
 import { OxyServices } from './OxyServices';
 export default OxyServices;

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

@@ -469,14 +469,12 @@ export declare function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(B
          * (`{ twoFactorRequired, loginToken }`) to complete via
          * {@link completeTwoFactorSignIn}, or a session arm.
          *
-         * `options.deviceToken` attributes the new session to the caller's existing
-         * device set (so an in-app login from a cross-apex, cookie-less web app
-         * still joins the same DeviceSession). On the session arm, a returned access
-         * token is planted immediately (mirroring {@link verifyChallenge}), so the
-         * caller has an authenticated client without a second round-trip.
+         * On the session arm, a returned access token is planted immediately
+         * (mirroring {@link verifyChallenge}), so the caller has an authenticated
+         * client without a second round-trip. The response's `deviceId` +
+         * `deviceSecret` are the zero-cookie restore credential the caller persists.
          */
         passwordSignIn(identifier: string, password: string, options?: {
-            deviceToken?: string;
             deviceName?: string;
             deviceFingerprint?: string;
         }): Promise<LoginResult>;
@@ -491,7 +489,6 @@ export declare function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(B
             loginToken: string;
             token?: string;
             backupCode?: string;
-            deviceToken?: string;
             deviceName?: string;
         }): Promise<LoginSessionResult>;
         httpService: import("../HttpService").HttpService;

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

@@ -1,62 +1,38 @@
 /**
- * Device-first bootstrap mixin (auth centralization, wave 1).
+ * Device-first token mint mixin.
  *
- * The client half of the new device-first session bootstrap: the four network
- * calls the cold boot (`coldBootV2`) and the unified refresh handler
- * (`refresh.ts`) make, plus the URL builder for the cross-apex bootstrap hop.
- * Every response is validated against the `@oxyhq/contracts` `deviceBoot`
- * schemas via `safeParseContract`, so producer (oxy-api) and consumer cannot
+ * The client half of the zero-cookie device transport: the single network call
+ * the cold boot (`coldBootV2`) and the unified re-mint handler (`refresh.ts`)
+ * make to turn a first-party `deviceId` + `deviceSecret` into a fresh access
+ * token. The response is validated against the `@oxyhq/contracts`
+ * `deviceTokenMintResponseSchema`, so producer (oxy-api) and consumer cannot
  * drift — an unexpected shape throws here rather than silently corrupting the
  * persisted store.
  *
- * These methods are ADDITIVE and carry NO persistence or token-planting side
- * effects of their own (except the bearer-authenticated calls that naturally
- * flow through `HttpService`). The cold boot / refresh handler own persistence
- * and `setTokens`, so the same network primitive can be reused from either
- * without double-planting.
+ * This method carries NO persistence or token-planting side effects of its own;
+ * the cold boot / re-mint handler own persistence and `setTokens`, so the same
+ * primitive can be reused from either without double-planting.
  */
-import { type AuthTokenBundle, type TokenRefreshResponse, type WebSessionResult } from '@oxyhq/contracts';
+import { type DeviceTokenMintResponse } from '@oxyhq/contracts';
 import type { OxyServicesBase } from '../OxyServices.base';
 export declare function OxyServicesDeviceBootMixin<T extends typeof OxyServicesBase>(Base: T): {
     new (...args: any[]): {
         /**
-         * Exchange a single-use boot `code` (from the `#oxy_boot` return fragment)
-         * for a token bundle. Origin-bound + GETDEL-burned server-side.
+         * Zero-cookie mint. Present the first-party `deviceId` + `deviceSecret` to
+         * `POST /session/device/token` — NO bearer, NO cookies: possession of the
+         * secret IS the device-ownership proof. Returns a fresh short access token
+         * for the device's active account plus `nextDeviceSecret` (rotation-in-use)
+         * and the projected device-session `state`.
          *
-         * @throws if the response does not match {@link authTokenBundleSchema}.
-         */
-        exchangeBootCode(code: string): Promise<AuthTokenBundle>;
-        /**
-         * Same-site fast path (`*.oxy.so` apps). Reads the first-party `oxy_device`
-         * cookie via a credentialed same-origin fetch and either resolves a full
-         * session bundle or reports the device is known-but-signed-out. Never
-         * redirects.
-         *
-         * @throws if the response matches neither arm of {@link webSessionResultSchema}.
-         */
-        requestWebSession(): Promise<WebSessionResult>;
-        /**
-         * Rotate the persisted refresh-token family (web + native, one call). The
-         * caller (refresh handler / cold boot) plants + persists the rotated pair.
+         * `skipAuth`: this call carries no bearer, so a 401 must surface DIRECTLY —
+         * never trigger `HttpService`'s 401→refresh→retry dance. The cold boot / re-
+         * mint handler read the 401 body (`invalid_device_secret` vs
+         * `no_active_session`) to decide whether to drop the secret and fall back or
+         * resolve signed-out.
          *
-         * @throws if the response does not match {@link tokenRefreshResponseSchema}.
-         */
-        refreshWithToken(refreshToken: string): Promise<TokenRefreshResponse>;
-        /**
-         * Issue (or rotate) the native channel's opaque device token. Bearer-gated —
-         * the server derives the deviceId from the JWT. Native apps mirror the
-         * returned token into the shared keychain via
-         * `KeyManager.setSharedDeviceToken`.
-         *
-         * @throws if the response does not match {@link deviceTokenIssueResponseSchema}.
-         */
-        issueNativeDeviceToken(): Promise<string>;
-        /**
-         * Build the top-level `GET /auth/device/bootstrap` URL for the cross-apex
-         * hop. The server validates `return_to` against the trusted-origin lane and
-         * echoes `state` back in the return fragment for CSRF verification.
+         * @throws if the response does not match {@link deviceTokenMintResponseSchema}.
          */
-        buildBootstrapUrl(returnTo: string, state: string): string;
+        mintFromDeviceSecret(deviceId: string, deviceSecret: string): Promise<DeviceTokenMintResponse>;
         httpService: import("../HttpService").HttpService;
         cloudURL: string;
         config: import("../OxyServices.base").OxyConfig;

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

@@ -38,30 +38,6 @@ export interface SessionClientOptions {
      * absent it falls back to `getSocketIO()`.
      */
     socketFactory?: SocketIOFactory;
-    /**
-     * Gate + credential for opening the realtime socket while SIGNED OUT (no
-     * access token), so an idle tab still joins its `device:<id>` room and can
-     * self-acquire the moment a sibling app/tab signs in on the same device.
-     * Returns:
-     *   - `true`   → connect and rely on the first-party `oxy_device` cookie
-     *     riding the same-site handshake (web `*.oxy.so`; the cookie is HttpOnly
-     *     so JS cannot read it, but the browser sends it automatically).
-     *   - a string → connect and present it as `deviceToken` in the handshake
-     *     auth (native shared-keychain device token; RN has no cookie jar).
-     *   - `false`/`null` → do NOT open a signed-out socket (the default — e.g. a
-     *     native app with no known device yet).
-     * Called at connect time (and each reconnect); may be async (keychain read).
-     */
-    signedOutSocketAuth?: () => boolean | string | null | Promise<boolean | string | null>;
-    /**
-     * Invoked when a `session_state` push (or a same-origin BroadcastChannel wake)
-     * arrives while this tab is SIGNED OUT and the pushed device state has at
-     * least one account — i.e. a sibling just signed in on this device. The
-     * consumer runs its session acquisition (cold boot / `requestWebSession`),
-     * which plants a token and flips the tab to signed-in. Guarded + idempotent:
-     * only one acquisition runs at a time, and a returned promise gates the next.
-     */
-    onSessionAppeared?: () => void | Promise<void>;
 }
 type StateListener = (state: DeviceSessionState | null) => void;
 export declare class SessionClient {
@@ -72,11 +48,7 @@ export declare class SessionClient {
     protected socket: MinimalSocket | null;
     private tokenUnsub;
     private started;
-    /** In-flight guard so a burst of pushes triggers at most ONE acquisition. */
-    private acquiring;
-    /** True while the live socket is an anonymous (signed-out) device connection. */
-    private socketAnonymous;
-    /** Same-origin cross-tab wake channel; null on platforms without BroadcastChannel. */
+    /** Same-origin cross-tab state-propagation channel; null on platforms without BroadcastChannel. */
     private channel;
     constructor(host: SessionClientHost, options?: SessionClientOptions);
     getState(): DeviceSessionState | null;
@@ -118,17 +90,11 @@ export declare class SessionClient {
     start(): Promise<void>;
     stop(): void;
     private connectSocket;
-    /**
-     * Run the consumer's session acquisition at most once at a time. A returned
-     * promise gates the next attempt (reset on settle), so a failed acquisition
-     * can retry on the NEXT push while a burst of identical pushes cannot pile up.
-     */
-    private requestAcquisition;
     /**
      * Open the same-origin `BroadcastChannel` (web only). A sibling tab that
-     * commits a session posts a wake ping; on receipt a signed-in tab re-syncs its
-     * device state and a signed-out tab self-acquires — instant + network-free for
-     * the common "two tabs of the same origin" case, with no state (and no tokens)
+     * commits an account switch / sign-out posts a wake ping; on receipt an
+     * authenticated tab re-syncs its device state — instant + network-free for the
+     * common "two tabs of the same origin" case, with no state (and no tokens)
      * ever crossing the channel. No-op on native (no BroadcastChannel).
      */
     private openBroadcastChannel;

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

@@ -92,9 +92,7 @@ export interface AccountDialogControllerOptions {
      * falls back to `SessionClient.registerAndActivate` (registration + activation
      * only — no provider-side durable persist/hydration).
      */
-    commitSession?: (session: SessionLoginResponse & {
-        refreshToken?: string;
-    }) => Promise<void>;
+    commitSession?: (session: SessionLoginResponse) => Promise<void>;
     /** Notified after a completed sign-in (bearer planted + session committed). */
     onSignedIn?: (user: MinimalUserData) => void;
     /** Central IdP apex for `openPasswordAtOxyAuth` (defaults to `CENTRAL_IDP_APEX`). */

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

@@ -1,12 +1,12 @@
 /**
  * Persisted auth state — ONE shape, web + native.
  *
- * The device-first session model (auth-centralization wave 1) persists the
- * rotating refresh-token family head per ORIGIN so a reload restores the
- * session locally without a redirect. This module is the storage seam: a tiny
- * `load / save / clear` interface plus platform factories, so the cold boot
- * (`coldBootV2`) and the unified refresh handler (`refresh.ts`) never touch a
- * platform storage API directly.
+ * The zero-cookie device transport persists the device credential per ORIGIN so
+ * a reload restores the session locally without a redirect: `deviceId` +
+ * `deviceSecret` mint a fresh access token via `POST /session/device/token`.
+ * This module is the storage seam: a tiny `load / save / clear` interface plus
+ * platform factories, so the cold boot (`coldBootV2`) and the unified re-mint
+ * handler (`refresh.ts`) never touch a platform storage API directly.
  *
  * Platform-agnostic — the native factory takes an INJECTED key/value store
  * (`@oxyhq/services` passes a SecureStore-backed adapter) so `@oxyhq/core`
@@ -19,52 +19,53 @@
 /**
  * The persisted session credential set for a single origin.
  *
- * `refreshToken` is the rotating single-use family head; `sessionId` + `userId`
- * identify the owning device session and account. `deviceToken` is the opaque,
- * add-only device attribution token (mirrored to the shared keychain on native
- * so every Oxy app on one phone shares one DeviceSession).
+ * `sessionId` + `userId` identify the owning device session and active account.
+ * `deviceId` + `deviceSecret` are the zero-cookie mint credential: the client
+ * presents BOTH at `POST /session/device/token` — the secret is the proof, the
+ * deviceId selects the device doc. The secret is rotated in-use: the mint returns
+ * `nextDeviceSecret`, which the cold boot / re-mint handler persist BEFORE
+ * planting the minted access token (multi-tab anti-loss).
  *
- * `accessToken` + `expiresAt` are OPTIONAL warm-boot fields. Persisting them
- * lets the cold boot plant a still-valid access token on the very first paint
- * WITHOUT a blocking `/auth/refresh-token` round-trip — the proactive scheduler
- * then rotates it in the background. They are a strict optimization: the store
- * is fully functional (via `refreshToken`) when they are absent or stale, and
- * the access token is short-lived, so persisting it adds no exposure the
- * already-persisted refresh token does not (see the plan's XSS risk note — the
- * refresh token is the dominant secret either way).
+ * `accessToken` + `expiresAt` are OPTIONAL warm-boot fields. Persisting them lets
+ * the cold boot plant a still-valid access token on the very first paint WITHOUT
+ * a blocking mint round-trip — the proactive scheduler then rotates it in the
+ * background. They are a strict optimization: the store is fully functional (via
+ * `deviceSecret`) when they are absent or stale, and the access token is
+ * short-lived, so persisting it adds no exposure the already-persisted
+ * `deviceSecret` does not.
  */
 export interface PersistedAuthState {
     sessionId: string;
-    refreshToken: string;
     userId: string;
-    deviceToken?: string;
+    /**
+     * The stable device identifier this session is bound to (zero-cookie
+     * transport). Persisted alongside {@link deviceSecret} because the
+     * `POST /session/device/token` mint presents BOTH. Sourced from every login
+     * lane (password / 2FA / QR claim / challenge verify) via the response's
+     * `deviceId`.
+     */
+    deviceId?: string;
+    /**
+     * The rotating device secret (zero-cookie transport). Possession of it mints a
+     * short access token for the device's active account via
+     * `POST /session/device/token`. Rotated in-use.
+     */
+    deviceSecret?: string;
     /** Optional warm-boot access token (short-lived; see interface docs). */
     accessToken?: string;
     /** Optional warm-boot access-token expiry, ISO-8601. */
     expiresAt?: string;
 }
 /**
- * The storage seam consumed by the cold boot and the refresh handler. Async
+ * The storage seam consumed by the cold boot and the re-mint handler. Async
  * throughout so one interface fits both synchronous web `localStorage` and
- * asynchronous native SecureStore/AsyncStorage.
- *
- * Two lifetimes:
- *  - The SESSION credential blob (`load`/`save`/`clear`) is per-sign-in and is
- *    wiped on `clear()` (sign-out).
- *  - The DEVICE token (`loadDeviceToken`/`saveDeviceToken`/`clearDeviceToken`)
- *    is long-lived device attribution that SURVIVES `clear()`: a signed-out
- *    browser is still the same device, and a later in-app (cross-apex,
- *    cookie-less) login sends this token so the new session joins the SAME
- *    server-side DeviceSession. Only an explicit device signout-all
- *    (`clearDeviceToken`) removes it.
+ * asynchronous native SecureStore/AsyncStorage. `clear()` (sign-out) wipes the
+ * per-sign-in credential blob.
  */
 export interface AuthStateStore {
     load(): Promise<PersistedAuthState | null>;
     save(state: PersistedAuthState): Promise<void>;
     clear(): Promise<void>;
-    loadDeviceToken(): Promise<string | null>;
-    saveDeviceToken(token: string): Promise<void>;
-    clearDeviceToken(): Promise<void>;
 }
 /**
  * The minimal async key/value surface a native store must provide. Matches
@@ -81,12 +82,6 @@ export interface NativeKeyValueStorage {
  * `oxy_shared_*` keychain keys in `KeyManager`, so it never collides.
  */
 export declare const AUTH_STATE_STORAGE_KEY = "oxy.auth.v1";
-/**
- * Storage key for the long-lived device-attribution token. Separate from
- * {@link AUTH_STATE_STORAGE_KEY} because it must OUTLIVE a session `clear()`
- * (sign-out) — the device is unchanged across sign-ins.
- */
-export declare const DEVICE_TOKEN_STORAGE_KEY = "oxy.device.v1";
 /**
  * A process-lifetime, in-memory {@link AuthStateStore}. Used directly for
  * tests/SSR and as the degraded fallback of the web store when `localStorage`
@@ -104,8 +99,8 @@ export declare function createMemoryAuthStateStore(): AuthStateStore;
  *    for this page's lifetime — never throws on construction.
  *  - Individual `getItem`/`setItem`/`removeItem` are each wrapped: a read that
  *    throws yields `null`; a write that throws (quota, private mode) is
- *    swallowed. The persisted-refresh lane treats a failed persist as "no
- *    durable state" (falls back to the bootstrap hop) rather than crashing.
+ *    swallowed. The re-mint lane treats a failed persist as "no durable state"
+ *    rather than crashing.
  */
 export declare function createWebAuthStateStore(): AuthStateStore;
 /**

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

@@ -1,5 +1,5 @@
 import type { OxyServices } from '../OxyServices';
-import { SessionClient, type SessionClientOptions, type TokenTransport } from './SessionClient';
+import { SessionClient, type TokenTransport } from './SessionClient';
 import type { SocketIOFactory } from './socketLoader';
 import { createSessionClientHost } from './sessionClientHost';
 /**
@@ -24,14 +24,7 @@ import { createSessionClientHost } from './sessionClientHost';
  * specifier (bundler-fragile in Metro/Expo-web and Vite against the published
  * dist). When omitted, the client falls back to the lazy loader.
  */
-export declare function createSessionClient(oxyServices: OxyServices, transport: TokenTransport, socketFactory?: SocketIOFactory, 
-/**
- * Optional signed-out realtime wiring: `signedOutSocketAuth` (open the socket
- * while signed out so an idle tab receives its device pushes) and
- * `onSessionAppeared` (self-acquire when a sibling signs in). See
- * {@link SessionClientOptions}.
- */
-extra?: Pick<SessionClientOptions, 'signedOutSocketAuth' | 'onSessionAppeared'>): {
+export declare function createSessionClient(oxyServices: OxyServices, transport: TokenTransport, socketFactory?: SocketIOFactory): {
     client: SessionClient;
     host: ReturnType<typeof createSessionClientHost>;
 };

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

@@ -1,21 +1,22 @@
 /**
- * Unified token refresh — THE single refresh implementation for web + native.
+ * Unified token refresh — THE single access-token re-mint for web + native.
  *
- * ONE persisted-refresh-token rotation shared by every consumer (it replaced
- * the pre-device-first per-platform duplicates):
+ * The access token is short-lived; there is no refresh token. To keep a session
+ * alive past the access token's TTL the client re-mints via the zero-cookie
+ * device transport:
  *
- *  - `refreshPersistedSession` — arm 1 rotates the stored refresh-token family
- *    (`POST /auth/refresh-token`), planting + persisting the rotated pair; arm 2
- *    (native only) re-mints via the shared-keychain identity when there is no
- *    live refresh token. It is used BOTH reactively (wrapped as the
- *    `AuthRefreshHandler` installed on `HttpService`) AND proactively (the
- *    cold-boot `stored-tokens` step calls it directly).
+ *  - `refreshPersistedSession` — arm 1 mints a fresh access token from the
+ *    persisted `deviceId` + `deviceSecret` (`POST /session/device/token`),
+ *    planting + persisting the rotated secret; arm 2 (native only) re-mints via
+ *    the shared-keychain identity when there is no usable secret. It is used BOTH
+ *    reactively (wrapped as the `AuthRefreshHandler` installed on `HttpService`)
+ *    AND proactively (the scheduler below calls it).
  *  - `createAuthRefreshHandler` / `installAuthRefreshHandler` wire arm 1+2 into
  *    `HttpService.setAuthRefreshHandler`, keeping that layer's single-flight
  *    dedup + cooldown (this module does NOT reimplement them).
  *  - `startTokenRefreshScheduler` — a proactive scheduler decoupled from any
- *    React type: refreshes ~60s before `exp`,
- *    re-arms on token change + web tab-focus, `.unref?.()`s its timer in Node.
+ *    React type: re-mints ~60s before `exp`, re-arms on token change + web
+ *    tab-focus, `.unref?.()`s its timer in Node.
  *
  * Framework-free; no module-level mutable state.
  */
@@ -24,33 +25,36 @@ import type { AuthRefreshHandler } from '../HttpService';
 import type { AuthStateStore } from './authStateStore';
 /**
  * Lead time (ms) before access-token expiry at which the proactive scheduler
- * refreshes. Mirrors `HttpService`'s per-request `TOKEN_REFRESH_LEAD_SECONDS`
- * (60s) so the scheduled refresh and the request-time preflight refresh use
- * the same window — the scheduler just fires it during idle/background.
+ * re-mints. Mirrors `HttpService`'s per-request `TOKEN_REFRESH_LEAD_SECONDS`
+ * (60s) so the scheduled re-mint and the request-time preflight use the same
+ * window — the scheduler just fires it during idle/background.
  */
 export declare const TOKEN_REFRESH_LEAD_MS = 60000;
 export interface RefreshDeps {
     oxy: OxyServices;
     store: AuthStateStore;
     /**
-     * Whether to fall back to the native shared-keychain re-mint (arm 2) when
-     * there is no live refresh token / arm 1 is revoked. Defaults to `isNative()`
-     * — web has no shared keychain. Exposed for tests.
+     * Whether to fall back to the native shared-keychain re-mint (arm 2) when the
+     * persisted secret is absent / rejected. Defaults to `isNative()` — web has no
+     * shared keychain. Exposed for tests.
      */
     allowSharedKeyFallback?: boolean;
 }
 /**
- * Rotate the persisted session and return the fresh access token, or `null`
+ * Re-mint the persisted session and return the fresh access token, or `null`
  * when no arm could produce one.
  *
- * Arm 1 (`POST /auth/refresh-token`): if the store holds a refresh token, rotate
- * it — on success plant + persist the rotated pair; on a REVOKED error clear the
- * store; on a transient error leave the store and return `null`.
+ * Arm 1 (`POST /session/device/token`): if the store holds a `deviceId` +
+ * `deviceSecret`, mint — on success plant + persist the rotated secret. A 401
+ * means the secret is diverged (`invalid_device_secret`) or the device has no
+ * live session (`no_active_session`): drop the secret so the mint lane stops (or
+ * clear the store on web, where there is no fallback). A transient error leaves
+ * the store and returns `null`.
  *
- * Arm 2 (native shared-keychain): when there is no refresh token or arm 1 was
- * revoked, re-mint via `signInWithSharedIdentity` (which plants tokens). The
- * shared keychain — not the per-origin store — is the durable native credential,
- * so this arm does not write the store.
+ * Arm 2 (native shared-keychain): when the secret is absent or was just rejected,
+ * re-mint via `signInWithSharedIdentity` (which plants tokens). The shared
+ * keychain — not the per-origin store — is the durable native credential, so this
+ * arm does not write the store.
  */
 export declare function refreshPersistedSession(deps: RefreshDeps): Promise<string | null>;
 /**
@@ -71,7 +75,7 @@ export interface TokenRefreshSchedulerHandle {
     dispose(): void;
 }
 /**
- * Start the proactive refresh scheduler against `oxy`.
+ * Start the proactive re-mint scheduler against `oxy`.
  *
  * Schedules a single timer to fire {@link TOKEN_REFRESH_LEAD_MS} before the
  * current access token's `exp`, calling
@@ -79,11 +83,11 @@ export interface TokenRefreshSchedulerHandle {
  * handler; deduped + cooldown-guarded). After every attempt it reschedules
  * from the possibly-rotated token. It also reschedules whenever the token
  * changes (a sign-out that clears the token cancels the timer) and, on web
- * tab-focus, refreshes immediately if already inside the lead window (a
+ * tab-focus, re-mints immediately if already inside the lead window (a
  * long-hidden tab throttles timers, so the token can be expired on return).
  *
  * No-ops cleanly when there is no token or an opaque/no-`exp` token — the
- * reactive 401 path stays the only refresh trigger in that case. The timer is
+ * reactive 401 path stays the only re-mint trigger in that case. The timer is
  * `.unref?.()`-ed so it never keeps a Node/Jest event loop alive.
  */
 export declare function startTokenRefreshScheduler(oxy: OxyServices): TokenRefreshSchedulerHandle;