@oxyhq/core 8.1.0 → 9.0.0

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;

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

@@ -4,12 +4,8 @@
  * The client FAPI auto-detection helper was removed in the device-first cutover
  * (which is why this file is now named for what it actually is, not the old
  * `fapiAutoDetect`). What survives is the pure registrable-domain kernel, still
- * used server-side by the api's device-first same-apex trust checks
- * (`deviceAuth.ts`'s `POST /auth/device/web-session`, via `sameSite.ts`'s
- * `isSameSiteTrustedRequest`) and the `@oxyhq/core/server` CORS/re-export layer.
- *
- * `registrableApex` is NOT legacy — the device-first same-apex check is a live
- * consumer, so this kernel stays regardless of the SSO/FedCM removal.
+ * used by the `@oxyhq/core/server` CORS layer (the `*.oxy.so` same-apex trust
+ * check) and its re-export surface.
  */
 /**
  * Compute the bare registrable apex (eTLD+1) of a hostname using the Public

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/core",
-  "version": "8.1.0",
+  "version": "9.0.0",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -94,7 +94,7 @@
     }
   },
   "dependencies": {
-    "@oxyhq/contracts": "^0.12.0",
+    "@oxyhq/contracts": "^0.13.0",
     "@oxyhq/protocol": "^0.1.2",
     "bip39": "^3.1.0",
     "buffer": "^6.0.3",

package/src/HttpService.ts

@@ -74,13 +74,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;
 }