@oxyhq/services 23.2.0 → 24.0.1

package/src/ui/session/__tests__/backgroundSession.test.ts

@@ -0,0 +1,387 @@
+/**
+ * The background credential's ORDERING and REVOCATION rules, which are the parts
+ * that can leak one account's data to another or leave a live credential behind.
+ *
+ * The native store and the mint are exercised on a device (see the design note);
+ * what is tested here is every decision JS makes about when to clear, when to
+ * provision, and — most importantly — when NOT to write.
+ */
+const requireOptionalNativeModule = jest.fn();
+
+jest.mock('expo-modules-core', () => ({
+  requireOptionalNativeModule: (...args: unknown[]) => requireOptionalNativeModule(...args),
+}));
+
+interface NativeCalls {
+  order: string[];
+  put: jest.Mock;
+  clear: jest.Mock;
+  peek: jest.Mock;
+}
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+function fakeNative(peekValue: { accountId: string; expiresAt: number } | null): NativeCalls {
+  const order: string[] = [];
+  return {
+    order,
+    put: jest.fn(async () => {
+      order.push('put');
+      return true;
+    }),
+    clear: jest.fn(async () => {
+      order.push('clear');
+      return true;
+    }),
+    peek: jest.fn(async () => {
+      order.push('peek');
+      return peekValue;
+    }),
+  };
+}
+
+function fakeOxy(
+  provision: jest.Mock,
+  baseURL = 'https://api.oxy.so',
+): Parameters<typeof import('../backgroundSession').syncBackgroundSession>[0]['oxyServices'] {
+  return {
+    provisionBackgroundCredential: provision,
+    getBaseURL: () => baseURL,
+  } as unknown as Parameters<
+    typeof import('../backgroundSession').syncBackgroundSession
+  >[0]['oxyServices'];
+}
+
+/**
+ * Re-import the module per test: it memoises the resolved native module, which is
+ * correct in production (one resolution per process) and must not leak between
+ * cases here.
+ *
+ * `platform` is explicit because the react-native stub defaults `Platform.OS` to
+ * `'web'`, where this feature is gated OFF by design. Every case therefore has to
+ * say which platform it is describing — defaulting to `'android'` here, since that
+ * is the only platform the feature ships on.
+ */
+async function loadModule(native: NativeCalls | null, platform: 'android' | 'web' = 'android') {
+  jest.resetModules();
+  requireOptionalNativeModule.mockClear();
+  requireOptionalNativeModule.mockReturnValue(
+    native ? { put: native.put, clear: native.clear, peek: native.peek } : null,
+  );
+  const { Platform } = await import('react-native');
+  Platform.OS = platform;
+  return import('../backgroundSession');
+}
+
+function provisioned(overrides: Partial<Record<string, unknown>> = {}) {
+  return {
+    deviceId: 'device-1',
+    secret: 'bg-secret',
+    accountId: 'user-1',
+    expiresAt: new Date(Date.now() + 30 * DAY_MS).toISOString(),
+    ...overrides,
+  };
+}
+
+describe('syncBackgroundSession', () => {
+  test('signed out clears the credential and never calls the network', async () => {
+    const native = fakeNative({ accountId: 'user-1', expiresAt: Date.now() + 30 * DAY_MS });
+    const { syncBackgroundSession } = await loadModule(native);
+    const provision = jest.fn();
+
+    await syncBackgroundSession({
+      oxyServices: fakeOxy(provision),
+      userId: null,
+      canUsePrivateApi: true,
+      isCurrent: () => true,
+    });
+
+    expect(native.clear).toHaveBeenCalledTimes(1);
+    expect(provision).not.toHaveBeenCalled();
+    // Not even a read: signing out must not depend on anything succeeding first.
+    expect(native.peek).not.toHaveBeenCalled();
+  });
+
+  test('a credential for a DIFFERENT account is cleared BEFORE any network call', async () => {
+    const native = fakeNative({ accountId: 'previous-user', expiresAt: Date.now() + 30 * DAY_MS });
+    const { syncBackgroundSession } = await loadModule(native);
+    const provision = jest.fn(async () => {
+      native.order.push('provision');
+      return provisioned();
+    });
+
+    await syncBackgroundSession({
+      oxyServices: fakeOxy(provision),
+      userId: 'user-1',
+      canUsePrivateApi: true,
+      isCurrent: () => true,
+    });
+
+    // The ordering IS the guarantee: a crash after the clear leaves background
+    // code signed out, never serving the previous account's data.
+    expect(native.order).toEqual(['peek', 'clear', 'provision', 'put']);
+  });
+
+  test('a healthy credential for the signed-in account makes no network call', async () => {
+    const native = fakeNative({ accountId: 'user-1', expiresAt: Date.now() + 30 * DAY_MS });
+    const { syncBackgroundSession } = await loadModule(native);
+    const provision = jest.fn();
+
+    await syncBackgroundSession({
+      oxyServices: fakeOxy(provision),
+      userId: 'user-1',
+      canUsePrivateApi: true,
+      isCurrent: () => true,
+    });
+
+    expect(provision).not.toHaveBeenCalled();
+    expect(native.clear).not.toHaveBeenCalled();
+    expect(native.put).not.toHaveBeenCalled();
+  });
+
+  test('renews a credential inside the renewal window', async () => {
+    const native = fakeNative({ accountId: 'user-1', expiresAt: Date.now() + 2 * DAY_MS });
+    const { syncBackgroundSession } = await loadModule(native);
+    const expiresAt = new Date(Date.now() + 30 * DAY_MS).toISOString();
+    const provision = jest.fn(async () => provisioned({ expiresAt }));
+
+    await syncBackgroundSession({
+      oxyServices: fakeOxy(provision),
+      userId: 'user-1',
+      canUsePrivateApi: true,
+      isCurrent: () => true,
+    });
+
+    expect(provision).toHaveBeenCalledTimes(1);
+    expect(native.put).toHaveBeenCalledWith({
+      baseUrl: 'https://api.oxy.so',
+      deviceId: 'device-1',
+      secret: 'bg-secret',
+      accountId: 'user-1',
+      expiresAt: Date.parse(expiresAt),
+    });
+    // Same account, so nothing was revoked on the way.
+    expect(native.clear).not.toHaveBeenCalled();
+  });
+
+  test('waits for a bearer instead of provisioning without one', async () => {
+    const native = fakeNative(null);
+    const { syncBackgroundSession } = await loadModule(native);
+    const provision = jest.fn();
+
+    await syncBackgroundSession({
+      oxyServices: fakeOxy(provision),
+      userId: 'user-1',
+      canUsePrivateApi: false,
+      isCurrent: () => true,
+    });
+
+    expect(provision).not.toHaveBeenCalled();
+    expect(native.put).not.toHaveBeenCalled();
+  });
+
+  test('a not-yet-deployed endpoint (null) is quiet and writes nothing', async () => {
+    const native = fakeNative(null);
+    const { syncBackgroundSession } = await loadModule(native);
+    const provision = jest.fn(async () => null);
+
+    await syncBackgroundSession({
+      oxyServices: fakeOxy(provision),
+      userId: 'user-1',
+      canUsePrivateApi: true,
+      isCurrent: () => true,
+    });
+
+    expect(provision).toHaveBeenCalledTimes(1);
+    expect(native.put).not.toHaveBeenCalled();
+    expect(native.clear).not.toHaveBeenCalled();
+  });
+
+  test('a credential minted for another account mid-flight is dropped, not stored', async () => {
+    const native = fakeNative(null);
+    const { syncBackgroundSession } = await loadModule(native);
+    // The active account moved while the request was in flight, so the server
+    // answered for someone other than the account this run is syncing.
+    const provision = jest.fn(async () => provisioned({ accountId: 'other-user' }));
+
+    await syncBackgroundSession({
+      oxyServices: fakeOxy(provision),
+      userId: 'user-1',
+      canUsePrivateApi: true,
+      isCurrent: () => true,
+    });
+
+    expect(native.put).not.toHaveBeenCalled();
+    expect(native.clear).toHaveBeenCalledTimes(1);
+  });
+
+  test('a superseded run does not write the credential it fetched', async () => {
+    const native = fakeNative(null);
+    const { syncBackgroundSession } = await loadModule(native);
+    const provision = jest.fn(async () => provisioned());
+
+    await syncBackgroundSession({
+      oxyServices: fakeOxy(provision),
+      userId: 'user-1',
+      canUsePrivateApi: true,
+      // Superseded while the request was in flight (unmount, or a newer run).
+      isCurrent: () => false,
+    });
+
+    expect(native.put).not.toHaveBeenCalled();
+  });
+
+  test('an unparseable expiry is rejected rather than stored as garbage', async () => {
+    const native = fakeNative(null);
+    const { syncBackgroundSession } = await loadModule(native);
+    const provision = jest.fn(async () => provisioned({ expiresAt: 'not-a-date' }));
+
+    await syncBackgroundSession({
+      oxyServices: fakeOxy(provision),
+      userId: 'user-1',
+      canUsePrivateApi: true,
+      isCurrent: () => true,
+    });
+
+    expect(native.put).not.toHaveBeenCalled();
+  });
+
+  test('a provisioning failure never escapes to the caller', async () => {
+    const native = fakeNative(null);
+    const { syncBackgroundSession } = await loadModule(native);
+    const provision = jest.fn(async () => {
+      throw new Error('network down');
+    });
+
+    await expect(
+      syncBackgroundSession({
+        oxyServices: fakeOxy(provision),
+        userId: 'user-1',
+        canUsePrivateApi: true,
+        isCurrent: () => true,
+      }),
+    ).resolves.toBeUndefined();
+    expect(native.put).not.toHaveBeenCalled();
+  });
+});
+
+describe('a @oxyhq/core too old to provision', () => {
+  /**
+   * The ONE failure that must not be quiet. Every other failure here is caught and
+   * logged at warn, which is right for a flaky network — but a version skew means
+   * background refreshes never work at all, and hiding that behind a warning is how
+   * it would go unnoticed indefinitely.
+   */
+  function oxyWithoutProvisioning(): Parameters<
+    typeof import('../backgroundSession').syncBackgroundSession
+  >[0]['oxyServices'] {
+    return { getBaseURL: () => 'https://api.oxy.so' } as unknown as Parameters<
+      typeof import('../backgroundSession').syncBackgroundSession
+    >[0]['oxyServices'];
+  }
+
+  test('rejects loudly and logs at error rather than warning quietly', async () => {
+    const native = fakeNative(null);
+    const { syncBackgroundSession } = await loadModule(native);
+    const { logger } = await import('@oxyhq/core');
+    const errorSpy = jest.spyOn(logger, 'error').mockImplementation(() => undefined);
+    const warnSpy = jest.spyOn(logger, 'warn').mockImplementation(() => undefined);
+
+    try {
+      await expect(
+        syncBackgroundSession({
+          oxyServices: oxyWithoutProvisioning(),
+          userId: 'user-1',
+          canUsePrivateApi: true,
+          isCurrent: () => true,
+        }),
+      ).rejects.toThrow(/provisionBackgroundCredential/);
+
+      expect(errorSpy).toHaveBeenCalledTimes(1);
+      // If this ever becomes a warn, the skew is silent again.
+      expect(warnSpy).not.toHaveBeenCalled();
+      expect(native.put).not.toHaveBeenCalled();
+    } finally {
+      errorSpy.mockRestore();
+      warnSpy.mockRestore();
+    }
+  });
+
+  test('still lets a signed-out user clear, since that needs no core method', async () => {
+    const native = fakeNative({ accountId: 'user-1', expiresAt: Date.now() + 30 * DAY_MS });
+    const { syncBackgroundSession } = await loadModule(native);
+
+    // A sign-out must never be blocked by a dependency problem.
+    await expect(
+      syncBackgroundSession({
+        oxyServices: oxyWithoutProvisioning(),
+        userId: null,
+        canUsePrivateApi: false,
+        isCurrent: () => true,
+      }),
+    ).resolves.toBeUndefined();
+    expect(native.clear).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe('on web', () => {
+  /**
+   * Web must never provision. The credential is non-rotating and long-lived, which
+   * is only safe because native background code is its sole consumer; a browser
+   * origin already holds the ROTATING deviceSecret and has no background worker, so
+   * a successful provision there is a security DOWNGRADE. The harm lands at the
+   * network call, which mints a live server-side credential, so "storage failed
+   * anyway" is not a defence.
+   *
+   * These tests present a native module that IS available, which is the whole
+   * point: they fail if the gate ever relies on `requireOptionalNativeModule`
+   * returning null on web rather than on the platform check.
+   */
+  test('does not provision even when a native module IS present', async () => {
+    const native = fakeNative(null);
+    const { syncBackgroundSession, isBackgroundSessionSupported } = await loadModule(native, 'web');
+    const provision = jest.fn(async () => provisioned());
+
+    expect(isBackgroundSessionSupported()).toBe(false);
+    await syncBackgroundSession({
+      oxyServices: fakeOxy(provision),
+      userId: 'user-1',
+      canUsePrivateApi: true,
+      isCurrent: () => true,
+    });
+
+    expect(provision).not.toHaveBeenCalled();
+    expect(native.put).not.toHaveBeenCalled();
+    // Not even a read, so nothing in a browser origin is touched at all.
+    expect(native.peek).not.toHaveBeenCalled();
+    expect(native.clear).not.toHaveBeenCalled();
+  });
+
+  test('never asks the native registry on web', async () => {
+    const { isBackgroundSessionSupported } = await loadModule(fakeNative(null), 'web');
+    expect(isBackgroundSessionSupported()).toBe(false);
+    // The platform decides BEFORE the registry is consulted, so a web-build
+    // native-module mock or a future web shim cannot reopen the gate.
+    expect(requireOptionalNativeModule).not.toHaveBeenCalled();
+  });
+});
+
+describe('without the native module', () => {
+  test('every entry point is an inert no-op', async () => {
+    const { syncBackgroundSession, clearBackgroundSession, isBackgroundSessionSupported } =
+      await loadModule(null);
+    const provision = jest.fn();
+
+    expect(isBackgroundSessionSupported()).toBe(false);
+    await expect(clearBackgroundSession()).resolves.toBeUndefined();
+    await expect(
+      syncBackgroundSession({
+        oxyServices: fakeOxy(provision),
+        userId: 'user-1',
+        canUsePrivateApi: true,
+        isCurrent: () => true,
+      }),
+    ).resolves.toBeUndefined();
+    expect(provision).not.toHaveBeenCalled();
+  });
+});

package/src/ui/session/backgroundSession.ts

@@ -0,0 +1,299 @@
+/**
+ * The JS half of the native background session credential.
+ *
+ * A home-screen widget or a sync job refreshes while the app process is dead:
+ * there is no JS runtime, so it cannot go through this SDK's normal session lane
+ * at all. Native code needs its own way to obtain a bearer, and this module is
+ * what gives it one — while the app runs, it provisions a purpose-built
+ * credential and hands it to the native store that `so.oxy.session.OxyBackgroundSession`
+ * reads.
+ *
+ * ## Why a separate credential rather than the device secret
+ *
+ * `POST /session/device/token` ROTATES the device secret on every mint, and the
+ * presented secret dies 60 seconds later. Native code minting with it would be a
+ * second writer to the value this SDK's whole session depends on — and since
+ * `createNativeAuthStateStore` serves JS from an in-process mirror that never
+ * re-reads storage, JS would be blind to that rotation. A worker killed between
+ * the server's rotation and its local write would sign the user out of the app.
+ * A credential that nobody rotates removes that failure mode instead of managing
+ * it.
+ *
+ * ## What this does NOT do
+ *
+ * It never reads or writes `oxy.auth.v1` / expo-secure-store. The two credentials
+ * live in different stores with one writer each, so there is nothing to keep in
+ * lockstep and no state that can disagree.
+ *
+ * ## Android only, and web is refused rather than merely unsupported
+ *
+ * Web is gated off by an explicit platform check, not by the native module being
+ * absent — provisioning in a browser origin would be a security downgrade, so it
+ * must not depend on an incidental fact. See {@link loadNativeModule}. iOS has no
+ * implementation yet and resolves to no module, so every function here degrades to
+ * a no-op: an app can enable this and lose nothing on other platforms.
+ */
+import { requireOptionalNativeModule } from 'expo-modules-core';
+import { Platform } from 'react-native';
+import type { OxyServices } from '@oxyhq/core';
+import { logger } from '@oxyhq/core';
+
+/**
+ * The native module's surface. Deliberately write-mostly: there is no `get`,
+ * because JS has no use for the secret it just wrote and keeping native as the
+ * secret's only reader is one less place it can leak from.
+ */
+interface OxyBackgroundSessionNativeModule {
+  /** Store (replacing) the credential. Resolves `false` when it was rejected or storage failed. */
+  put(credential: {
+    baseUrl: string;
+    deviceId: string;
+    secret: string;
+    accountId: string;
+    /** Epoch millis — parsed from the server's ISO-8601 string here, not natively. */
+    expiresAt: number;
+  }): Promise<boolean>;
+  /** Drop the credential and any cached access token. */
+  clear(): Promise<boolean>;
+  /** What is stored: the owning account and its expiry (epoch millis), or `null`. */
+  peek(): Promise<{ accountId: string; expiresAt: number } | null>;
+}
+
+/**
+ * Re-provision once the remaining lifetime drops below this.
+ *
+ * The server issues a 30-day credential; renewing with a week to spare means an
+ * app opened even occasionally always holds a live one, while an app left unopened
+ * for a month lets it lapse — which is the intended outcome, not a failure.
+ */
+const RENEW_WHEN_REMAINING_MS = 7 * 24 * 60 * 60 * 1000;
+
+let nativeModule: OxyBackgroundSessionNativeModule | null | undefined;
+
+/**
+ * Resolve the native module once — and refuse outright on web.
+ *
+ * ## Web is excluded on purpose, and not merely because the module is absent
+ *
+ * The credential is deliberately NON-ROTATING and long-lived, which is safe only
+ * because native background code is its sole consumer and nobody rotates it. A
+ * browser origin already holds the ROTATING `deviceSecret`, and it has no
+ * background worker to serve — so provisioning there would add a strictly weaker
+ * long-lived secret alongside a stronger short-lived one. That is a downgrade, not
+ * a harmless no-op, and the harm lands at the PROVISION CALL (which mints a live
+ * server-side credential) regardless of whether anything manages to store it.
+ *
+ * That property must not rest on `requireOptionalNativeModule` happening to return
+ * `null` on web. It does today — the module is registered for android only — but
+ * that is an incidental fact a future web shim or a web-build native-module mock
+ * would quietly reverse. So the platform is checked FIRST, before we even ask the
+ * registry, and every entry point in this module inherits the gate.
+ *
+ * (A pre-deploy server makes this visible too: oxy-api's `sessionDevice` router
+ * applies `requireSameSiteOrigin` path-agnostically, so an unmatched path answers
+ * `404` to a native caller but `403 BAD_ORIGIN` to a browser one. Core's degrade is
+ * deliberately narrow — `404 → null` only — because a real origin misconfiguration
+ * on a CURRENT server also returns 403, and swallowing that would hide a genuine
+ * bug. Platform gating belongs here, where the platform is actually known.)
+ *
+ * `requireOptionalNativeModule` (a static import Metro always resolves) rather
+ * than a dynamic `import(moduleName)`: the latter compiles to `require(variable)`
+ * in the CJS build, which Metro cannot resolve inside a consuming app — it
+ * silently returned `null` there, which is exactly how the cross-app SSO bridge
+ * broke once. Same reasoning as `loadSharedIdentityBridge` in `@oxyhq/protocol`.
+ */
+function loadNativeModule(): OxyBackgroundSessionNativeModule | null {
+  if (nativeModule === undefined) {
+    if (Platform.OS === 'web') {
+      nativeModule = null;
+      return nativeModule;
+    }
+    const native = requireOptionalNativeModule<Partial<OxyBackgroundSessionNativeModule>>(
+      'OxyBackgroundSession',
+    );
+    nativeModule =
+      native &&
+      typeof native.put === 'function' &&
+      typeof native.clear === 'function' &&
+      typeof native.peek === 'function'
+        ? {
+            put: native.put.bind(native),
+            clear: native.clear.bind(native),
+            peek: native.peek.bind(native),
+          }
+        : null;
+  }
+  return nativeModule;
+}
+
+/** Whether this platform/app can hold a background credential at all. */
+export function isBackgroundSessionSupported(): boolean {
+  return loadNativeModule() !== null;
+}
+
+/**
+ * Drop the stored credential. No-op where unsupported, and never throws.
+ *
+ * Called on sign-out and BEFORE an account switch's network work, so the window
+ * in which background code could still serve the previous account is as short as
+ * one local write.
+ */
+export async function clearBackgroundSession(): Promise<void> {
+  const native = loadNativeModule();
+  if (!native) {
+    return;
+  }
+  try {
+    await native.clear();
+  } catch (error) {
+    logger.warn('[backgroundSession] could not clear the native background credential', {
+      component: 'backgroundSession',
+      error,
+    });
+  }
+}
+
+export interface BackgroundSessionSyncInput {
+  oxyServices: OxyServices;
+  /** The signed-in account, or `null` when signed out. */
+  userId: string | null;
+  /** Whether a bearer is available yet — provisioning requires one. */
+  canUsePrivateApi: boolean;
+  /**
+   * Whether this run is still the current one. A run that loses its relevance
+   * mid-flight (unmount, or another identity change) must not write the
+   * credential it was about to write.
+   */
+  isCurrent: () => boolean;
+}
+
+/**
+ * Fail LOUDLY when the installed `@oxyhq/core` predates
+ * `provisionBackgroundCredential`.
+ *
+ * This is the one failure here that is a build/dependency mistake rather than a
+ * runtime condition, and it is the one that must never be quiet. Everything else
+ * in `syncBackgroundSession` is caught and logged at warn, which is right for a
+ * flaky network — but applying that to a version skew would leave background
+ * refreshes permanently non-functional behind a warning nobody reads. So this
+ * throws, and logs at ERROR first so it is still visible in a release build whose
+ * rejection handler is silent.
+ *
+ * Reachable only through a runtime skew: the declared `@oxyhq/core` range covers
+ * the method, so a correctly-resolved install cannot get here, and TypeScript
+ * rules it out at compile time.
+ */
+function assertProvisioningAvailable(oxyServices: OxyServices): void {
+  if (typeof oxyServices.provisionBackgroundCredential === 'function') {
+    return;
+  }
+  const message =
+    '[backgroundSession] the installed @oxyhq/core has no provisionBackgroundCredential, ' +
+    'so no background credential can be provisioned and native background refreshes will ' +
+    'never authenticate. Install a @oxyhq/core that satisfies this package\'s declared range.';
+  logger.error(message, undefined, { component: 'backgroundSession' });
+  throw new Error(message);
+}
+
+/**
+ * Bring the native credential in line with the session JS currently holds.
+ *
+ * Ordering is the load-bearing part: a credential belonging to a DIFFERENT
+ * account is cleared before any network call, so a crash mid-provision leaves
+ * background code signed out rather than serving the previous account's data
+ * under the new account's name. The server enforces the same rule independently
+ * (a mint is re-authorized against the live device session, and against its ACTIVE
+ * account), so this is the fast local half of a belt-and-braces pair, not the only
+ * guard.
+ *
+ * Throws for exactly one thing — a `@oxyhq/core` too old to provision (see
+ * {@link assertProvisioningAvailable}). Every other failure is caught and logged:
+ * a background credential is an enhancement, and failing to provision one must
+ * not disturb the session that is working.
+ */
+export async function syncBackgroundSession(input: BackgroundSessionSyncInput): Promise<void> {
+  const native = loadNativeModule();
+  if (!native) {
+    return;
+  }
+  const { oxyServices, userId, canUsePrivateApi, isCurrent } = input;
+
+  // Before the try, so the catch below cannot turn a dependency skew into a
+  // warning. Signed-out is exempt: clearing needs no core method, and a sign-out
+  // must never be blocked by one.
+  if (userId) {
+    assertProvisioningAvailable(oxyServices);
+  }
+
+  try {
+    if (!userId) {
+      // Signed out. Local-only, so it works with no bearer and no network.
+      await native.clear();
+      return;
+    }
+
+    const stored = await native.peek();
+    if (stored && stored.accountId !== userId) {
+      // Identity changed under a live credential — clear FIRST, provision after.
+      await native.clear();
+    }
+
+    const isForCurrentAccount = stored?.accountId === userId;
+    const hasLifeLeft =
+      isForCurrentAccount && stored.expiresAt - Date.now() > RENEW_WHEN_REMAINING_MS;
+    if (hasLifeLeft) {
+      return;
+    }
+
+    // Everything below needs a bearer. Without one yet (cold boot still
+    // resolving) there is nothing to do but wait for the next run — the token
+    // landing re-triggers this.
+    if (!canUsePrivateApi || !isCurrent()) {
+      return;
+    }
+
+    const provisioned = await oxyServices.provisionBackgroundCredential();
+    if (!provisioned) {
+      // `null` means the endpoint is not deployed yet. Expected during the
+      // rollout window (api leads the SDK) and deliberately quiet.
+      return;
+    }
+    if (!isCurrent()) {
+      return;
+    }
+    if (provisioned.accountId !== userId) {
+      // The active account moved while the request was in flight, so this
+      // credential is already for the wrong account. Drop it; the next run
+      // provisions for the account that is actually signed in.
+      await native.clear();
+      return;
+    }
+
+    const expiresAt = Date.parse(provisioned.expiresAt);
+    if (!Number.isFinite(expiresAt)) {
+      logger.warn('[backgroundSession] server returned an unparseable credential expiry', {
+        component: 'backgroundSession',
+      });
+      return;
+    }
+
+    const persisted = await native.put({
+      baseUrl: oxyServices.getBaseURL(),
+      deviceId: provisioned.deviceId,
+      secret: provisioned.secret,
+      accountId: provisioned.accountId,
+      expiresAt,
+    });
+    if (!persisted) {
+      logger.warn(
+        '[backgroundSession] the native store did not retain the background credential; background refreshes stay signed out until the next attempt',
+        { component: 'backgroundSession' },
+      );
+    }
+  } catch (error) {
+    logger.warn('[backgroundSession] could not sync the native background credential', {
+      component: 'backgroundSession',
+      error,
+    });
+  }
+}

package/src/ui/session/index.ts

@@ -13,6 +13,7 @@
 export { createSessionClient } from './createSessionClient';
 export { createTokenTransport } from './tokenTransport';
 export { createPlatformAuthStateStore } from './authStore';
+export { useBackgroundSessionSync } from './useBackgroundSessionSync';
 export { createIdentitySessionBinding, IdentityBoundSessionError } from './identityBinding';
 export type { IdentitySessionBinding } from './identityBinding';
 export {