@oxyhq/core 9.1.0 → 9.2.0

package/dist/types/boot/{coldBootV2.d.ts → sessionColdBoot.d.ts}

@@ -1,5 +1,5 @@
 /**
- * coldBootV2 — one device-first cold boot for every consumer.
+ * Device-first session 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

package/dist/types/index.d.ts

@@ -83,10 +83,13 @@ export { registrableApex } from './utils/registrableApex';
 export { CENTRAL_IDP_APEX } from './utils/authWebUrl';
 export { runColdBoot } from './utils/coldBoot';
 export type { ColdBootStep, ColdBootStepResult, ColdBootSession, ColdBootSkip, ColdBootOutcome, RunColdBootOptions, } from './utils/coldBoot';
-export { buildOAuthAuthorizeUrl, computeCodeChallenge, generateOAuthState, generatePkcePair, DEFAULT_OAUTH_SCOPE, OXY_AUTHORIZE_URL, } from './utils/oauthPkce';
+export { buildOAuthAuthorizeUrl, computeCodeChallenge, generateOAuthState, generatePkcePair, DEFAULT_OAUTH_SCOPE, OXY_AUTHORIZE_URL, OXY_OAUTH_STATE_STORAGE_KEY, OXY_OAUTH_CODE_VERIFIER_STORAGE_KEY, OXY_SILENT_OAUTH_ATTEMPTED_KEY, OXY_CROSS_ORIGIN_RESTORE_ATTEMPTED_KEY, normalizeOAuthRedirectUri, persistOAuthHandshake, readOAuthHandshake, clearOAuthHandshake, } from './utils/oauthPkce';
 export type { PkcePair, BuildOAuthAuthorizeUrlParams } from './utils/oauthPkce';
+export { buildIdpHubOrigin, buildHubSyncUrl, isIdpHubOrigin, isOfficialWebOrigin, isAllowedDeviceJoinOrigin, normalizeOfficialReturnOrigin, parseHubSyncReturnUrl, } from './utils/officialOrigins';
+export { syncHubAfterSignIn, redeemHubTicketOnHub, } from './session/hubSync';
+export type { SyncHubAfterSignInOptions } from './session/hubSync';
 export { SessionClient } from './session/SessionClient';
-export type { TokenTransport, SessionClientHost, SessionClientOptions } from './session/SessionClient';
+export type { TokenTransport, SessionClientHost, SessionClientOptions, DeviceCredential } from './session/SessionClient';
 export type { SocketIOFactory, MinimalSocket } from './session/socketLoader';
 export { createSessionClientHost } from './session/sessionClientHost';
 export { createSessionClient } from './session/createSessionClient';
@@ -99,8 +102,8 @@ export { createWebAuthStateStore, createNativeAuthStateStore, createMemoryAuthSt
 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 } from './boot/coldBootV2';
-export type { RunSessionColdBootOptions, SignedOutReason, DeviceBootSession, } from './boot/coldBootV2';
+export { runSessionColdBoot } from './boot/sessionColdBoot';
+export type { RunSessionColdBootOptions, SignedOutReason, DeviceBootSession, } from './boot/sessionColdBoot';
 export { packageInfo } from './constants/version';
 import { OxyServices } from './OxyServices';
 export default OxyServices;

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

@@ -477,6 +477,7 @@ export declare function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(B
         passwordSignIn(identifier: string, password: string, options?: {
             deviceName?: string;
             deviceFingerprint?: string;
+            deviceId?: string;
         }): Promise<LoginResult>;
         /**
          * Complete a 2FA-gated sign-in started by {@link passwordSignIn}. Presents
@@ -490,6 +491,19 @@ export declare function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(B
             token?: string;
             backupCode?: string;
             deviceName?: string;
+            deviceId?: string;
+        }): Promise<LoginSessionResult>;
+        /**
+         * Exchange an OAuth authorization code (returned to the RP redirect URI
+         * after password sign-in at auth.oxy.so) for a device-first session.
+         * Public first-party clients use PKCE (`codeVerifier`); the access token is
+         * planted immediately on success.
+         */
+        exchangeOAuthCode(params: {
+            code: string;
+            clientId: string;
+            redirectUri: string;
+            codeVerifier: string;
         }): Promise<LoginSessionResult>;
         httpService: import("../HttpService").HttpService;
         cloudURL: string;

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

@@ -2,7 +2,7 @@
  * Device-first token mint mixin.
  *
  * 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`)
+ * the cold boot (`sessionColdBoot`) 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
@@ -13,7 +13,7 @@
  * the cold boot / re-mint handler own persistence and `setTokens`, so the same
  * primitive can be reused from either without double-planting.
  */
-import { type DeviceTokenMintResponse } from '@oxyhq/contracts';
+import { type DeviceTokenMintResponse, type DeviceHubTicketIssueResponse, type DeviceHubTicketRedeemResponse } from '@oxyhq/contracts';
 import type { OxyServicesBase } from '../OxyServices.base';
 export declare function OxyServicesDeviceBootMixin<T extends typeof OxyServicesBase>(Base: T): {
     new (...args: any[]): {
@@ -33,6 +33,10 @@ export declare function OxyServicesDeviceBootMixin<T extends typeof OxyServicesB
          * @throws if the response does not match {@link deviceTokenMintResponseSchema}.
          */
         mintFromDeviceSecret(deviceId: string, deviceSecret: string): Promise<DeviceTokenMintResponse>;
+        /** Mint a one-time hub sync ticket (bearer required). */
+        issueHubTicket(returnOrigin: string): Promise<DeviceHubTicketIssueResponse>;
+        /** Redeem a hub sync ticket for a fresh device secret (public). */
+        redeemHubTicket(ticket: string, returnOrigin: string): Promise<DeviceHubTicketRedeemResponse>;
         httpService: import("../HttpService").HttpService;
         cloudURL: string;
         config: import("../OxyServices.base").OxyConfig;

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

@@ -24,3 +24,4 @@ export { createOxyCors } from './cors';
 export type { OxyCorsOptions } from './cors';
 export { verifySecret } from './verifySecret';
 export { registrableApex } from '../utils/registrableApex';
+export { buildIdpHubOrigin, buildHubSyncUrl, isIdpHubOrigin, isOfficialWebOrigin, normalizeOfficialReturnOrigin, parseHubSyncReturnUrl, } from '../utils/officialOrigins';

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

@@ -4,12 +4,18 @@ export interface TokenTransport {
     /** Ensure this app holds a per-domain access token for state.activeAccountId (mint via the persisted refresh family / shared keychain). Best-effort. */
     ensureActiveToken(state: DeviceSessionState): Promise<void>;
 }
+export interface DeviceCredential {
+    deviceId: string;
+    deviceSecret: string;
+}
 export interface SessionClientHost {
     makeRequest<T>(method: 'GET' | 'POST', url: string, data?: unknown, options?: {
         cache?: boolean;
     }): Promise<T>;
     getBaseURL(): string;
     getAccessToken(): string | null;
+    /** Zero-cookie device credential for socket handshake when no bearer is planted yet. */
+    getDeviceCredential(): DeviceCredential | null;
     onTokensChanged(listener: (token: string | null) => void): () => void;
     setTokens(accessToken: string): void;
     getCurrentAccountId(): string | null;

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

@@ -97,6 +97,12 @@ export interface AccountDialogControllerOptions {
     onSignedIn?: (user: MinimalUserData) => void;
     /** Central IdP apex for `openPasswordAtOxyAuth` (defaults to `CENTRAL_IDP_APEX`). */
     idpApex?: string;
+    /**
+     * Registered OAuth redirect URI for this RP (exact match against
+     * `Application.redirectUris`). When set, wins over `returnUrl` /
+     * `location.origin` normalization in {@link openPasswordAtOxyAuth}.
+     */
+    authRedirectUri?: string | null;
     /** QR device-flow poll interval in ms (default 3000). */
     pollIntervalMs?: number;
     /**
@@ -115,6 +121,7 @@ export declare class AccountDialogController {
     private readonly commitSession?;
     private readonly onSignedIn?;
     private readonly idpApex;
+    private readonly authRedirectUri;
     private readonly pollIntervalMs;
     private readonly openUrl?;
     private readonly listeners;
@@ -244,7 +251,8 @@ export declare class AccountDialogController {
     openPasswordAtOxyAuth(params?: {
         returnUrl?: string;
         state?: string;
-    }): string;
+        redirectUri?: string;
+    }): Promise<string>;
     private scheduleNextPoll;
     private pollOnce;
     private claimAndComplete;

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

@@ -5,7 +5,7 @@
  * 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
+ * platform factories, so the cold boot (`sessionColdBoot`) 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

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

@@ -0,0 +1,20 @@
+/**
+ * Post-sign-in hub sync — plant device credentials on auth.oxy.so via a
+ * one-time server ticket (no secrets in URL fragments).
+ */
+import type { OxyServices } from '../OxyServices';
+import type { AuthStateStore } from './authStateStore';
+export interface SyncHubAfterSignInOptions {
+    /** Skip sync when false (OxyProvider hubSync prop). @default true */
+    enabled?: boolean;
+}
+/**
+ * After a successful sign-in on an official web app, mint a hub ticket and
+ * redirect to auth.oxy.so/sync so the IdP hub can redeem it and persist the
+ * shared device credential for silent OAuth restore on other origins.
+ *
+ * No-op on native, non-official origins, and when already on the IdP hub.
+ */
+export declare function syncHubAfterSignIn(oxy: Pick<OxyServices, 'issueHubTicket'>, opts?: SyncHubAfterSignInOptions): Promise<boolean>;
+/** Redeem a hub ticket on auth.oxy.so and persist credentials locally. */
+export declare function redeemHubTicketOnHub(oxy: Pick<OxyServices, 'redeemHubTicket'>, store: AuthStateStore, ticket: string): Promise<boolean>;

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

@@ -1,5 +1,5 @@
 import type { OxyServices } from '../OxyServices';
-import type { SessionClientHost } from './SessionClient';
+import type { DeviceCredential, SessionClientHost } from './SessionClient';
 /**
  * Thin `SessionClientHost` adapter over an `OxyServices` instance.
  *
@@ -14,4 +14,5 @@ import type { SessionClientHost } from './SessionClient';
  */
 export declare function createSessionClientHost(oxyServices: OxyServices): SessionClientHost & {
     setCurrentAccountId(id: string | null): void;
+    setDeviceCredential(credential: DeviceCredential | null): void;
 };

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

@@ -16,7 +16,7 @@
  *     web bundle — the reason any run-once guard for a step must live in the
  *     calling consumer, never in a core module-level singleton).
  *   - Architecture-agnostic: it knows nothing about HOW a step resolves a
- *     session; `runSessionColdBoot` (`boot/coldBootV2.ts`) is the current
+ *     session; `runSessionColdBoot` (`boot/sessionColdBoot.ts`) is the current
  *     device-first consumer.
  *
  * A step is skipped (without running) when its `enabled` predicate returns
@@ -94,7 +94,7 @@ export interface RunColdBootOptions<S> {
      * fails to settle before the deadline, the runner abandons the await for that
      * step (reporting it via `onStepDeadline`) and CONTINUES to the next step,
      * each now racing against an already-expired deadline. This is deliberate:
-     * the runner keeps iterating so the TERMINAL step (e.g. `coldBootV2`'s
+     * the runner keeps iterating so the TERMINAL step (e.g. `sessionColdBoot`'s
      * `bootstrap-hop`, whose `run()` performs its navigation side effect
      * synchronously before its first `await`) still gets to fire. A step that
      * has nothing to contribute after the deadline simply doesn't settle and is

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

@@ -42,6 +42,11 @@ export interface BuildOAuthAuthorizeUrlParams {
     state: string;
     /** The PKCE `codeChallenge` from {@link generatePkcePair}. */
     codeChallenge: string;
+    /**
+     * OAuth `prompt` parameter. Use `none` for silent cross-origin session restore
+     * (no UI when the IdP hub already has a session + grant).
+     */
+    prompt?: 'none' | 'login' | 'consent';
 }
 /**
  * Compute the PKCE S256 `code_challenge` for a given verifier:
@@ -72,3 +77,25 @@ export declare function generateOAuthState(): Promise<string>;
  * All values are percent-encoded by `URL.searchParams`.
  */
 export declare function buildOAuthAuthorizeUrl(params: BuildOAuthAuthorizeUrlParams): string;
+/** `sessionStorage` key for the OAuth CSRF `state` across an authorize redirect. */
+export declare const OXY_OAUTH_STATE_STORAGE_KEY = "oxy_oauth_state";
+/** `sessionStorage` key for the PKCE `code_verifier` across an authorize redirect. */
+export declare const OXY_OAUTH_CODE_VERIFIER_STORAGE_KEY = "oxy_oauth_code_verifier";
+/** `sessionStorage` key — at most one silent OAuth attempt per navigation. */
+export declare const OXY_SILENT_OAUTH_ATTEMPTED_KEY = "oxy.silent_oauth_attempted";
+/** `sessionStorage` key — blocks further cross-origin auto-restore in this tab. */
+export declare const OXY_CROSS_ORIGIN_RESTORE_ATTEMPTED_KEY = "oxy.cross_origin_restore_attempted";
+/**
+ * Normalize a redirect URI to its origin. Official Oxy apps register apex
+ * origins (`https://inbox.oxy.so`) — never path-qualified URLs.
+ */
+export declare function normalizeOAuthRedirectUri(input: string): string;
+/** Persist the OAuth handshake for a full-page redirect return (web only). */
+export declare function persistOAuthHandshake(state: string, codeVerifier: string): boolean;
+/** Read the persisted OAuth handshake, or `null` when absent. */
+export declare function readOAuthHandshake(): {
+    state: string;
+    codeVerifier: string;
+} | null;
+/** Drop persisted OAuth handshake keys after a successful or aborted return. */
+export declare function clearOAuthHandshake(): void;

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

@@ -0,0 +1,17 @@
+/**
+ * Official first-party web origin allowlist — shared by hub-ticket issuance,
+ * OAuth redirect validation, and cross-origin session restore.
+ */
+export declare function buildIdpHubOrigin(): string;
+/** Whether the current web origin is the central IdP hub (`auth.oxy.so`). */
+export declare function isIdpHubOrigin(): boolean;
+/** Whether an origin belongs to the official Oxy web ecosystem. */
+export declare function isOfficialWebOrigin(origin: string): boolean;
+/** Normalize and validate a return URL against official origins. Returns origin only. */
+export declare function normalizeOfficialReturnOrigin(raw: string): string | null;
+/** Validate a hub-sync return URL; returns the full normalized URL string. */
+export declare function parseHubSyncReturnUrl(raw: string | null): string | null;
+/** Build auth.oxy.so/sync redirect URL with a one-time hub ticket. */
+export declare function buildHubSyncUrl(ticket: string, returnUrl?: string): string;
+/** @deprecated Use {@link isOfficialWebOrigin}. */
+export declare const isAllowedDeviceJoinOrigin: typeof isOfficialWebOrigin;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/core",
-  "version": "9.1.0",
+  "version": "9.2.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.13.0",
+    "@oxyhq/contracts": "^0.13.1",
     "@oxyhq/protocol": "^0.1.3",
     "bip39": "^3.1.0",
     "buffer": "^6.0.3",

package/src/boot/__tests__/{coldBootV2.test.ts → sessionColdBoot.test.ts}

@@ -9,7 +9,7 @@
 import type { OxyServices } from '../../OxyServices';
 import type { DeviceTokenMintResponse } from '@oxyhq/contracts';
 import type { SessionLoginResponse } from '../../models/session';
-import { runSessionColdBoot } from '../coldBootV2';
+import { runSessionColdBoot } from '../sessionColdBoot';
 import { createMemoryAuthStateStore, type PersistedAuthState } from '../../session/authStateStore';
 
 interface OxyOverrides {

package/src/boot/{coldBootV2.ts → sessionColdBoot.ts}

@@ -1,5 +1,5 @@
 /**
- * coldBootV2 — one device-first cold boot for every consumer.
+ * Device-first session 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
@@ -139,7 +139,7 @@ export async function runSessionColdBoot(
         // Transient (network / 5xx): keep the secret; a later attempt can succeed.
         logger.debug(
           'device-secret mint failed (transient) — keeping secret',
-          { component: 'coldBootV2', method: 'device-secret-mint' },
+          { component: 'sessionColdBoot', method: 'device-secret-mint' },
           error,
         );
         return { kind: 'skip' };

package/src/index.ts

@@ -523,14 +523,38 @@ export {
     generatePkcePair,
     DEFAULT_OAUTH_SCOPE,
     OXY_AUTHORIZE_URL,
+    OXY_OAUTH_STATE_STORAGE_KEY,
+    OXY_OAUTH_CODE_VERIFIER_STORAGE_KEY,
+    OXY_SILENT_OAUTH_ATTEMPTED_KEY,
+    OXY_CROSS_ORIGIN_RESTORE_ATTEMPTED_KEY,
+    normalizeOAuthRedirectUri,
+    persistOAuthHandshake,
+    readOAuthHandshake,
+    clearOAuthHandshake,
 } from './utils/oauthPkce';
 export type { PkcePair, BuildOAuthAuthorizeUrlParams } from './utils/oauthPkce';
 
+export {
+    buildIdpHubOrigin,
+    buildHubSyncUrl,
+    isIdpHubOrigin,
+    isOfficialWebOrigin,
+    isAllowedDeviceJoinOrigin,
+    normalizeOfficialReturnOrigin,
+    parseHubSyncReturnUrl,
+} from './utils/officialOrigins';
+
+export {
+    syncHubAfterSignIn,
+    redeemHubTicketOnHub,
+} from './session/hubSync';
+export type { SyncHubAfterSignInOptions } from './session/hubSync';
+
 // ---------------------------------------------------------------------------
 // Session sync (device-scoped multi-account session client)
 // ---------------------------------------------------------------------------
 export { SessionClient } from './session/SessionClient';
-export type { TokenTransport, SessionClientHost, SessionClientOptions } from './session/SessionClient';
+export type { TokenTransport, SessionClientHost, SessionClientOptions, DeviceCredential } from './session/SessionClient';
 // The injectable socket factory type: consumers that bundle socket.io-client
 // (services/auth-sdk) pass its `io` export as `socketFactory` so realtime sync
 // never relies on core's lazy dynamic import of a bare specifier.
@@ -609,12 +633,12 @@ export {
 } from './session/refresh';
 export type { RefreshDeps, TokenRefreshSchedulerHandle } from './session/refresh';
 
-export { runSessionColdBoot } from './boot/coldBootV2';
+export { runSessionColdBoot } from './boot/sessionColdBoot';
 export type {
     RunSessionColdBootOptions,
     SignedOutReason,
     DeviceBootSession,
-} from './boot/coldBootV2';
+} from './boot/sessionColdBoot';
 
 // API response contracts (request/response Zod schemas + inferred types) live in
 // `@oxyhq/contracts` — the single source of truth shared by the backend and every

package/src/mixins/OxyServices.auth.ts

@@ -1136,7 +1136,7 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
     async passwordSignIn(
       identifier: string,
       password: string,
-      options: { deviceName?: string; deviceFingerprint?: string } = {},
+      options: { deviceName?: string; deviceFingerprint?: string; deviceId?: string } = {},
     ): Promise<LoginResult> {
       try {
         const res = await this.makeRequest<unknown>('POST', '/auth/login', {
@@ -1144,6 +1144,7 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
           password,
           deviceName: options.deviceName,
           deviceFingerprint: options.deviceFingerprint,
+          ...(options.deviceId ? { deviceId: options.deviceId } : {}),
         }, { cache: false });
         const parsed = safeParseContract(loginResultSchema, res);
         if (!parsed) {
@@ -1170,6 +1171,7 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
       token?: string;
       backupCode?: string;
       deviceName?: string;
+      deviceId?: string;
     }): Promise<LoginSessionResult> {
       try {
         const res = await this.makeRequest<unknown>('POST', '/security/2fa/verify-login', {
@@ -1177,6 +1179,7 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
           token: params.token,
           backupCode: params.backupCode,
           deviceName: params.deviceName,
+          ...(params.deviceId ? { deviceId: params.deviceId } : {}),
         }, { cache: false });
         const parsed = safeParseContract(loginResultSchema, res);
         if (!parsed || 'twoFactorRequired' in parsed) {
@@ -1190,5 +1193,71 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
         throw this.handleError(error);
       }
     }
+
+    /**
+     * Exchange an OAuth authorization code (returned to the RP redirect URI
+     * after password sign-in at auth.oxy.so) for a device-first session.
+     * Public first-party clients use PKCE (`codeVerifier`); the access token is
+     * planted immediately on success.
+     */
+    async exchangeOAuthCode(params: {
+      code: string;
+      clientId: string;
+      redirectUri: string;
+      codeVerifier: string;
+    }): Promise<LoginSessionResult> {
+      try {
+        const res = await this.makeRequest<unknown>('POST', '/auth/oauth/token', {
+          code: params.code,
+          clientId: params.clientId,
+          redirectUri: params.redirectUri,
+          codeVerifier: params.codeVerifier,
+        }, { cache: false });
+        const payload =
+          (res as { data?: Record<string, unknown> }).data ??
+          (res as Record<string, unknown>);
+        if (!payload || typeof payload !== 'object') {
+          throw new Error('auth/oauth/token returned an unexpected response shape');
+        }
+        const record = payload as Record<string, unknown>;
+        const accessToken = (record.access_token ?? record.accessToken) as string | undefined;
+        const sessionId = (record.session_id ?? record.sessionId) as string | undefined;
+        const deviceId = (record.deviceId ?? record.device_id) as string | undefined;
+        const deviceSecret = (record.deviceSecret ?? record.device_secret) as string | undefined;
+        const userRaw = record.user;
+        if (!sessionId || !deviceId || !userRaw || typeof userRaw !== 'object') {
+          throw new Error('auth/oauth/token returned an incomplete session payload');
+        }
+        const userObj = userRaw as Record<string, unknown>;
+        const userId = userObj.id as string | undefined;
+        if (!userId) {
+          throw new Error('auth/oauth/token returned a session without user.id');
+        }
+        const expiresInSec =
+          typeof record.expires_in === 'number'
+            ? record.expires_in
+            : typeof record.expiresIn === 'number'
+              ? record.expiresIn
+              : 15 * 60;
+        const expiresAt = new Date(Date.now() + expiresInSec * 1000).toISOString();
+        if (accessToken) {
+          this.setTokens(accessToken);
+        }
+        return {
+          sessionId,
+          deviceId,
+          expiresAt,
+          accessToken,
+          deviceSecret,
+          user: {
+            id: userId,
+            username: typeof userObj.username === 'string' ? userObj.username : undefined,
+            avatar: typeof userObj.avatar === 'string' ? userObj.avatar : undefined,
+          },
+        };
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
   };
 }

package/src/mixins/OxyServices.deviceBoot.ts

@@ -2,7 +2,7 @@
  * Device-first token mint mixin.
  *
  * 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`)
+ * the cold boot (`sessionColdBoot`) 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
@@ -15,8 +15,12 @@
  */
 import {
   deviceTokenMintResponseSchema,
+  deviceHubTicketIssueResponseSchema,
+  deviceHubTicketRedeemResponseSchema,
   safeParseContract,
   type DeviceTokenMintResponse,
+  type DeviceHubTicketIssueResponse,
+  type DeviceHubTicketRedeemResponse,
 } from '@oxyhq/contracts';
 import type { OxyServicesBase } from '../OxyServices.base';
 
@@ -57,5 +61,46 @@ export function OxyServicesDeviceBootMixin<T extends typeof OxyServicesBase>(Bas
         throw this.handleError(error);
       }
     }
+
+    /** Mint a one-time hub sync ticket (bearer required). */
+    async issueHubTicket(returnOrigin: string): Promise<DeviceHubTicketIssueResponse> {
+      try {
+        const res = await this.makeRequest<unknown>(
+          'POST',
+          '/session/device/hub-ticket',
+          { returnOrigin },
+          { cache: false },
+        );
+        const parsed = safeParseContract(deviceHubTicketIssueResponseSchema, res);
+        if (!parsed) {
+          throw new Error('session/device/hub-ticket returned an unexpected response shape');
+        }
+        return parsed;
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /** Redeem a hub sync ticket for a fresh device secret (public). */
+    async redeemHubTicket(
+      ticket: string,
+      returnOrigin: string,
+    ): Promise<DeviceHubTicketRedeemResponse> {
+      try {
+        const res = await this.makeRequest<unknown>(
+          'POST',
+          '/session/device/redeem-ticket',
+          { ticket, returnOrigin },
+          { cache: false, skipAuth: true },
+        );
+        const parsed = safeParseContract(deviceHubTicketRedeemResponseSchema, res);
+        if (!parsed) {
+          throw new Error('session/device/redeem-ticket returned an unexpected response shape');
+        }
+        return parsed;
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
   };
 }

package/src/server/index.ts

@@ -69,3 +69,11 @@ export { verifySecret } from './verifySecret';
 // Pure host handling (no browser deps), so it is safe on the server subpath and
 // lets `@oxyhq/api` derive `auth.<apex>` without duplicating PSL logic.
 export { registrableApex } from '../utils/registrableApex';
+export {
+  buildIdpHubOrigin,
+  buildHubSyncUrl,
+  isIdpHubOrigin,
+  isOfficialWebOrigin,
+  normalizeOfficialReturnOrigin,
+  parseHubSyncReturnUrl,
+} from '../utils/officialOrigins';