@oxyhq/core 1.11.19 → 1.11.21

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

@@ -21,6 +21,22 @@ export interface FedCMConfig {
  * convenience and normalised internally.
  */
 export type FedCMRequestMode = 'active' | 'passive' | 'button' | 'widget';
+/**
+ * Normalised result of a FedCM credential request: the IdP-issued ID token plus
+ * whether the browser auto-selected the account (no explicit user choice).
+ */
+interface FedCMTokenResult {
+    token: string;
+    isAutoSelected: boolean;
+}
+/**
+ * Test-only reset of the page-load silent-SSO memo. The memo is module-scoped
+ * and never cleared at runtime (a fresh page load resets it naturally), but
+ * tests sharing one module instance need to start from a clean slate.
+ *
+ * @internal
+ */
+export declare function __resetSilentSSOMemoForTests(): void;
 /**
  * Federated Credential Management (FedCM) Authentication Mixin
  *
@@ -105,6 +121,22 @@ export declare function OxyServicesFedCMMixin<T extends typeof OxyServicesBase>(
          * ```
          */
         silentSignInWithFedCM(): Promise<SessionLoginResponse | null>;
+        /**
+         * Build the page-load silent-SSO memo key from the current origin and the
+         * configured API base URL. Two providers pointed at the same API from the
+         * same origin share a single silent attempt per page load.
+         *
+         * @internal
+         */
+        silentSSOMemoKey(): string;
+        /**
+         * Perform the actual silent FedCM sign-in. Always wrapped by
+         * {@link silentSignInWithFedCM}'s page-load memo — never call this directly
+         * (doing so bypasses the run-once guard).
+         *
+         * @internal
+         */
+        _performSilentSignInWithFedCM(): Promise<SessionLoginResponse | null>;
         /**
          * Request identity credential from browser using FedCM API
          *
@@ -130,10 +162,7 @@ export declare function OxyServicesFedCMMixin<T extends typeof OxyServicesBase>(
              * the running browser only understands the old enum.
              */
             mode?: FedCMRequestMode;
-        }): Promise<{
-            token: string;
-            isAutoSelected: boolean;
-        } | null>;
+        }): Promise<FedCMTokenResult | null>;
         /**
          * Exchange FedCM ID token for Oxy session
          *

package/package.json

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

package/src/mixins/OxyServices.auth.ts

@@ -353,7 +353,7 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
       deviceFingerprint?: string
     ): Promise<SessionLoginResponse> {
       try {
-        return await this.makeRequest<SessionLoginResponse>('POST', '/auth/verify', {
+        const res = await this.makeRequest<SessionLoginResponse>('POST', '/auth/verify', {
           publicKey,
           challenge,
           signature,
@@ -361,6 +361,21 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
           deviceName,
           deviceFingerprint,
         }, { cache: false });
+
+        // Plant the freshly-minted tokens, mirroring `claimSessionByToken`.
+        // `/auth/verify` returns the first access token (and refresh token) in
+        // its body, so installing it here means callers get an authenticated
+        // client without a second round-trip — and, critically, without
+        // falling back to the bearer-protected `GET /session/token/:sessionId`
+        // (C1 hardening), which 401s for a brand-new identity that has no
+        // bearer yet. `accessToken`/`refreshToken` are optional on
+        // SessionLoginResponse; only plant when an access token is present and
+        // default the refresh token to an empty string.
+        if (res?.accessToken) {
+          this.setTokens(res.accessToken, res.refreshToken ?? '');
+        }
+
+        return res;
       } catch (error) {
         throw this.handleError(error);
       }

package/src/mixins/OxyServices.fedcm.ts

@@ -99,14 +99,77 @@ interface FedCMCredentialsContainer {
   get(options: FedCMCredentialRequest): Promise<FedCMIdentityCredential | null>;
 }
 
+/**
+ * Normalised result of a FedCM credential request: the IdP-issued ID token plus
+ * whether the browser auto-selected the account (no explicit user choice).
+ */
+interface FedCMTokenResult {
+  token: string;
+  isAutoSelected: boolean;
+}
+
+// Options accepted by the static `IdentityCredential.disconnect()` method
+// (W3C FedCM "disconnect" / sign-out). Not declared in every lib-dom version.
+interface FedCMDisconnectOptions {
+  configURL: string;
+  clientId: string;
+  accountHint: string;
+}
+
+// Minimal structural shape of the global `IdentityCredential` interface object,
+// modelling only the static `disconnect` method this mixin invokes.
+interface FedCMIdentityCredentialStatic {
+  disconnect(options: FedCMDisconnectOptions): Promise<void>;
+}
+
 const FEDCM_LOGIN_HINT_KEY = 'oxy_fedcm_login_hint';
 
 // Global lock to prevent concurrent FedCM requests
 // FedCM only allows one navigator.credentials.get request at a time
 let fedCMRequestInProgress = false;
-let fedCMRequestPromise: Promise<any> | null = null;
+let fedCMRequestPromise: Promise<FedCMTokenResult | null> | null = null;
 let currentMediationMode: string | null = null;
 
+/**
+ * Page-load-persistent memo for SILENT FedCM sign-in.
+ *
+ * Silent SSO (`mediation: 'silent'`) is the one FedCM flow that runs WITHOUT a
+ * user gesture — on app startup / provider mount. Multiple consumers
+ * (`@oxyhq/auth`'s `WebOxyProvider` / `useWebSSO`, `@oxyhq/services`'
+ * `useWebSSO`) can each mount and trigger it, and a remount storm (route churn,
+ * React StrictMode double-invoke, error-boundary recovery) previously turned
+ * into a `navigator.credentials.get` storm. This memo collapses every silent
+ * attempt for a given `origin + baseURL` into AT MOST ONE browser credential
+ * request per page load:
+ *
+ *   - the FIRST silent call runs the real flow and stores its in-flight promise;
+ *   - concurrent silent calls share that same in-flight promise;
+ *   - once it settles, the memo retains the resolved value (a session OR `null`)
+ *     and every subsequent silent call returns it WITHOUT re-invoking the
+ *     browser.
+ *
+ * Keyed on `origin + baseURL` (not the OxyServices instance) so it survives
+ * instance churn across remounts. Intentionally never cleared: only a fresh
+ * page load — which starts a fresh module scope — can change the IdP session
+ * state that silent mediation observes.
+ *
+ * This guard is SILENT-ONLY. Interactive flows (`signInWithFedCM`,
+ * `mediation: 'optional'|'required'`, `mode: 'active'|'passive'`) must always
+ * be able to re-prompt and are never memoized here.
+ */
+const silentSSOMemo = new Map<string, Promise<SessionLoginResponse | null>>();
+
+/**
+ * Test-only reset of the page-load silent-SSO memo. The memo is module-scoped
+ * and never cleared at runtime (a fresh page load resets it naturally), but
+ * tests sharing one module instance need to start from a clean slate.
+ *
+ * @internal
+ */
+export function __resetSilentSSOMemoForTests(): void {
+  silentSSOMemo.clear();
+}
+
 /**
  * Federated Credential Management (FedCM) Authentication Mixin
  *
@@ -224,9 +287,11 @@ export function OxyServicesFedCMMixin<T extends typeof OxyServicesBase>(Base: T)
       // Exchange FedCM ID token for Oxy session
       const session = await this.exchangeIdTokenForSession(credential.token);
 
-      // Store access token in HttpService (extract from response or get from session)
-      if (session && (session as any).accessToken) {
-        this.httpService.setTokens((session as any).accessToken);
+      // Store access token in HttpService. `accessToken`/`refreshToken` are
+      // declared optional on SessionLoginResponse; default the refresh token to
+      // an empty string when the exchange did not return one.
+      if (session?.accessToken) {
+        this.httpService.setTokens(session.accessToken, session.refreshToken ?? '');
       }
 
       // Store the user ID as loginHint for future FedCM requests
@@ -234,17 +299,20 @@ export function OxyServicesFedCMMixin<T extends typeof OxyServicesBase>(Base: T)
         this.storeLoginHint(session.user.id);
       }
 
-      debug.log('Interactive sign-in: Success!', { userId: (session as any)?.user?.id });
+      debug.log('Interactive sign-in: Success!', { userId: session?.user?.id });
 
       return session;
     } catch (error) {
       debug.log('Interactive sign-in failed:', error);
       const errorMessage = error instanceof Error ? error.message : String(error);
+      // FedCM aborts/network failures surface as DOMException/Error instances,
+      // both of which carry a `name`. Anything else has no meaningful name.
+      const errorName = error instanceof Error ? error.name : '';
 
-      if ((error as any).name === 'AbortError') {
+      if (errorName === 'AbortError') {
         throw new OxyAuthenticationError('Sign-in was cancelled by user');
       }
-      if ((error as any).name === 'NetworkError') {
+      if (errorName === 'NetworkError') {
         throw new OxyAuthenticationError('Network error during sign-in. Please check your connection.');
       }
       if (errorMessage.includes('multiple accounts')) {
@@ -294,6 +362,49 @@ export function OxyServicesFedCMMixin<T extends typeof OxyServicesBase>(Base: T)
       return null;
     }
 
+    // Page-load run-once guard. The first silent attempt for this
+    // origin + API runs; concurrent callers share the in-flight promise; once
+    // it settles, every later caller gets the memoized result (session OR
+    // null) WITHOUT re-invoking `navigator.credentials.get`. This is the single
+    // chokepoint for silent SSO across all consumers and remounts.
+    const memoKey = this.silentSSOMemoKey();
+    const existing = silentSSOMemo.get(memoKey);
+    if (existing) {
+      debug.log('Silent SSO: Returning memoized page-load result (no re-invocation)');
+      return existing;
+    }
+
+    const attempt = this._performSilentSignInWithFedCM();
+    silentSSOMemo.set(memoKey, attempt);
+    return attempt;
+  }
+
+  /**
+   * Build the page-load silent-SSO memo key from the current origin and the
+   * configured API base URL. Two providers pointed at the same API from the
+   * same origin share a single silent attempt per page load.
+   *
+   * @internal
+   */
+  public silentSSOMemoKey(): string {
+    const origin = typeof window !== 'undefined' ? window.location.origin : 'no-origin';
+    let baseURL = '';
+    try {
+      baseURL = this.getBaseURL();
+    } catch {
+      baseURL = '';
+    }
+    return `${origin}|${baseURL}`;
+  }
+
+  /**
+   * Perform the actual silent FedCM sign-in. Always wrapped by
+   * {@link silentSignInWithFedCM}'s page-load memo — never call this directly
+   * (doing so bypasses the run-once guard).
+   *
+   * @internal
+   */
+  public async _performSilentSignInWithFedCM(): Promise<SessionLoginResponse | null> {
     const clientId = this.getClientId();
     debug.log('Silent SSO: Starting for', clientId);
 
@@ -301,7 +412,7 @@ export function OxyServicesFedCMMixin<T extends typeof OxyServicesBase>(Base: T)
     // We intentionally do NOT fall back to optional mediation here because
     // this runs on app startup — showing browser UI without user action is bad UX.
     // Optional/interactive mediation should only happen when the user clicks "Sign In".
-    let credential: { token: string; isAutoSelected: boolean } | null = null;
+    let credential: FedCMTokenResult | null = null;
 
     const loginHint = this.getStoredLoginHint();
 
@@ -368,9 +479,11 @@ export function OxyServicesFedCMMixin<T extends typeof OxyServicesBase>(Base: T)
       return null;
     }
 
-    // Set the access token
-    if ((session as any).accessToken) {
-      this.httpService.setTokens((session as any).accessToken);
+    // Set the access token. `accessToken`/`refreshToken` are declared optional
+    // on SessionLoginResponse; default the refresh token to an empty string when
+    // the exchange did not return one.
+    if (session.accessToken) {
+      this.httpService.setTokens(session.accessToken, session.refreshToken ?? '');
       debug.log('Silent SSO: Access token set');
     } else {
       debug.warn('Silent SSO: No accessToken in session response');
@@ -414,7 +527,7 @@ export function OxyServicesFedCMMixin<T extends typeof OxyServicesBase>(Base: T)
      * the running browser only understands the old enum.
      */
     mode?: FedCMRequestMode;
-  }): Promise<{ token: string; isAutoSelected: boolean } | null> {
+  }): Promise<FedCMTokenResult | null> {
     const requestedMediation = options.mediation || 'optional';
     const isInteractive = requestedMediation !== 'silent';
 
@@ -589,9 +702,17 @@ export function OxyServicesFedCMMixin<T extends typeof OxyServicesBase>(Base: T)
     }
 
     try {
-      if ('IdentityCredential' in window && 'disconnect' in (window as any).IdentityCredential) {
+      // The DOM lib does not declare the global `IdentityCredential` interface
+      // object (with its static `disconnect`) in every TypeScript version we
+      // build against. Read it off `window` through the minimal structural type
+      // (not `any`), guarding that `disconnect` is actually present at runtime.
+      const fedCMWindow = window as unknown as {
+        IdentityCredential?: Partial<FedCMIdentityCredentialStatic>;
+      };
+      const identityCredential = fedCMWindow.IdentityCredential;
+      if (identityCredential && typeof identityCredential.disconnect === 'function') {
         const clientId = this.getClientId();
-        await (window as any).IdentityCredential.disconnect({
+        await identityCredential.disconnect({
           configURL: this.resolveFedcmConfigUrl(),
           clientId,
           accountHint: accountHint || '*',

package/src/mixins/__tests__/fedcm.test.ts

@@ -19,6 +19,7 @@
  */
 
 import { OxyServices } from '../../OxyServices';
+import { __resetSilentSSOMemoForTests } from '../OxyServices.fedcm';
 
 interface CredentialGetCall {
   identity: {
@@ -69,6 +70,11 @@ describe('OxyServices FedCM nonce binding', () => {
   afterEach(() => {
     clearBrowserGlobals();
     jest.restoreAllMocks();
+    // The silent-SSO memo is module-scoped and survives between `it` blocks.
+    // Each test that calls `silentSignInWithFedCM` expects a fresh browser
+    // invocation, so reset the memo (a real page load would do the same by
+    // starting a fresh module scope).
+    __resetSilentSSOMemoForTests();
   });
 
   it('silent SSO mints a server nonce and forwards it to the browser', async () => {
@@ -225,6 +231,7 @@ describe('OxyServices FedCM mode enum (active/passive)', () => {
   afterEach(() => {
     clearBrowserGlobals();
     jest.restoreAllMocks();
+    __resetSilentSSOMemoForTests();
   });
 
   it('interactive sign-in requests the modern mode: "active"', async () => {
@@ -321,3 +328,178 @@ describe('OxyServices FedCM mode enum (active/passive)', () => {
     expect(call.identity.mode).toBeUndefined();
   });
 });
+
+/**
+ * Page-load silent-SSO run-once guard.
+ *
+ * Silent SSO must invoke `navigator.credentials.get` AT MOST ONCE per page
+ * load, even when multiple consumers / remounts / StrictMode call
+ * `silentSignInWithFedCM()` repeatedly. The guard lives at the chokepoint in
+ * core: the first silent attempt for an `origin + baseURL` runs; concurrent
+ * callers share the in-flight promise; later callers get the memoized result
+ * (session OR null) without re-invoking the browser.
+ *
+ * Interactive sign-in (`signInWithFedCM`) is NOT memoized — a user clicking the
+ * sign-in button must always be able to re-prompt. That is asserted too.
+ */
+describe('OxyServices FedCM silent-SSO page-load guard', () => {
+  afterEach(() => {
+    clearBrowserGlobals();
+    jest.restoreAllMocks();
+    __resetSilentSSOMemoForTests();
+  });
+
+  it('invokes the browser at most once across repeated silent calls and returns the memoized result', async () => {
+    let getCallCount = 0;
+    installBrowserGlobals({
+      credentialsGet: async () => {
+        getCallCount += 1;
+        return { type: 'identity', token: 'idp-token', isAutoSelected: true };
+      },
+    });
+
+    const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+    let exchangeCount = 0;
+    jest.spyOn(oxy, 'makeRequest').mockImplementation(async (_method: string, url: string) => {
+      if (url === '/fedcm/nonce') {
+        return { nonce: 'n', expiresAt: new Date(Date.now() + 60000).toISOString() } as never;
+      }
+      if (url === '/fedcm/exchange') {
+        exchangeCount += 1;
+        return {
+          sessionId: 'sess_guard',
+          deviceId: 'dev_guard',
+          expiresAt: new Date(Date.now() + 60000).toISOString(),
+          accessToken: 'access_guard',
+          user: { id: 'user_guard', username: 'tester' },
+        } as never;
+      }
+      throw new Error(`unexpected request to ${url}`);
+    });
+
+    const first = await oxy.silentSignInWithFedCM();
+    const second = await oxy.silentSignInWithFedCM();
+    const third = await oxy.silentSignInWithFedCM();
+
+    // The browser credential request fired exactly once.
+    expect(getCallCount).toBe(1);
+    // The token exchange ran exactly once too (the whole flow is memoized).
+    expect(exchangeCount).toBe(1);
+    // Every caller received the same memoized session.
+    expect(first?.sessionId).toBe('sess_guard');
+    expect(second).toBe(first);
+    expect(third).toBe(first);
+  });
+
+  it('shares a single in-flight browser call across concurrent silent callers', async () => {
+    let getCallCount = 0;
+    let resolveGet: ((value: unknown) => void) | null = null;
+    installBrowserGlobals({
+      credentialsGet: () =>
+        new Promise((resolve) => {
+          getCallCount += 1;
+          resolveGet = resolve;
+        }),
+    });
+
+    const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+    jest.spyOn(oxy, 'makeRequest').mockImplementation(async (_method: string, url: string) => {
+      if (url === '/fedcm/nonce') {
+        return { nonce: 'n', expiresAt: new Date(Date.now() + 60000).toISOString() } as never;
+      }
+      if (url === '/fedcm/exchange') {
+        return {
+          sessionId: 'sess_concurrent',
+          deviceId: 'dev_concurrent',
+          expiresAt: new Date(Date.now() + 60000).toISOString(),
+          accessToken: 'access_concurrent',
+          user: { id: 'user_concurrent', username: 'tester' },
+        } as never;
+      }
+      throw new Error(`unexpected request to ${url}`);
+    });
+
+    // Fire three silent calls before the first browser request resolves.
+    const p1 = oxy.silentSignInWithFedCM();
+    const p2 = oxy.silentSignInWithFedCM();
+    const p3 = oxy.silentSignInWithFedCM();
+
+    // Let the in-flight nonce/get chain start, then release the browser call.
+    await Promise.resolve();
+    await new Promise((r) => setTimeout(r, 0));
+    expect(getCallCount).toBe(1);
+    expect(resolveGet).not.toBeNull();
+    (resolveGet as unknown as (value: unknown) => void)({
+      type: 'identity',
+      token: 'idp-token',
+      isAutoSelected: true,
+    });
+
+    const [r1, r2, r3] = await Promise.all([p1, p2, p3]);
+
+    // Only one browser invocation despite three concurrent callers.
+    expect(getCallCount).toBe(1);
+    expect(r1?.sessionId).toBe('sess_concurrent');
+    expect(r2).toBe(r1);
+    expect(r3).toBe(r1);
+  });
+
+  it('memoizes a null result (user not signed in) without re-invoking the browser', async () => {
+    let getCallCount = 0;
+    installBrowserGlobals({
+      credentialsGet: async () => {
+        getCallCount += 1;
+        return null; // user not logged in at IdP
+      },
+    });
+
+    const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+    jest.spyOn(oxy, 'makeRequest').mockImplementation(async (_method: string, url: string) => {
+      if (url === '/fedcm/nonce') {
+        return { nonce: 'n', expiresAt: new Date(Date.now() + 60000).toISOString() } as never;
+      }
+      throw new Error(`unexpected request to ${url}`);
+    });
+
+    const first = await oxy.silentSignInWithFedCM();
+    const second = await oxy.silentSignInWithFedCM();
+
+    expect(first).toBeNull();
+    expect(second).toBeNull();
+    // The null verdict is memoized — the browser is not asked again.
+    expect(getCallCount).toBe(1);
+  });
+
+  it('does NOT memoize interactive sign-in (each click can re-prompt the browser)', async () => {
+    let getCallCount = 0;
+    installBrowserGlobals({
+      credentialsGet: async () => {
+        getCallCount += 1;
+        return { type: 'identity', token: `idp-token-${getCallCount}`, isAutoSelected: false };
+      },
+    });
+
+    const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+    jest.spyOn(oxy, 'makeRequest').mockImplementation(async (_method: string, url: string) => {
+      if (url === '/fedcm/nonce') {
+        return { nonce: 'n', expiresAt: new Date(Date.now() + 60000).toISOString() } as never;
+      }
+      if (url === '/fedcm/exchange') {
+        return {
+          sessionId: 'sess_interactive',
+          deviceId: 'dev_interactive',
+          expiresAt: new Date(Date.now() + 60000).toISOString(),
+          accessToken: 'access_interactive',
+          user: { id: 'user_interactive', username: 'tester' },
+        } as never;
+      }
+      throw new Error(`unexpected request to ${url}`);
+    });
+
+    await oxy.signInWithFedCM();
+    await oxy.signInWithFedCM();
+
+    // Interactive flow is never gated by the silent memo.
+    expect(getCallCount).toBe(2);
+  });
+});

package/src/mixins/__tests__/verifyChallenge.test.ts

@@ -0,0 +1,135 @@
+/**
+ * `verifyChallenge` token-planting regression tests.
+ *
+ * `OxyServices.verifyChallenge()` returns a `SessionLoginResponse` carrying the
+ * first `accessToken`/`refreshToken` minted by `POST /auth/verify`. It must
+ * PLANT those tokens internally — mirroring its sibling `claimSessionByToken` —
+ * so callers (e.g. @oxyhq/services' `useAuthOperations.performSignIn`) end up
+ * with an authenticated client WITHOUT falling back to the bearer-protected
+ * `GET /session/token/:sessionId`. That fallback 401s for a brand-new identity
+ * that has no bearer yet and previously broke the entire new-identity
+ * onboarding flow.
+ *
+ * These tests stub `makeRequest` so the planting logic is exercised end-to-end
+ * against a real OxyServices instance, with token state observed via the public
+ * `hasValidToken()` / `getAccessToken()` surface.
+ */
+
+import { OxyServices } from '../../OxyServices';
+
+interface VerifyResponse {
+  sessionId: string;
+  deviceId: string;
+  expiresAt: string;
+  accessToken?: string;
+  refreshToken?: string;
+  user: { id: string; username: string };
+}
+
+function makeOxy(): OxyServices {
+  return new OxyServices({ baseURL: 'https://api.oxy.so' });
+}
+
+describe('OxyServices.verifyChallenge token planting', () => {
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  it('plants the access + refresh token from the /auth/verify response body', async () => {
+    const oxy = makeOxy();
+    expect(oxy.hasValidToken()).toBe(false);
+
+    jest.spyOn(oxy, 'makeRequest').mockImplementation(async (_method, url) => {
+      if (url === '/auth/verify') {
+        return {
+          sessionId: 'sess_1',
+          deviceId: 'dev_1',
+          expiresAt: new Date(Date.now() + 60_000).toISOString(),
+          accessToken: 'access_verify',
+          refreshToken: 'refresh_verify',
+          user: { id: 'user_1', username: 'tester' },
+        } as never;
+      }
+      throw new Error(`unexpected request to ${url}`);
+    });
+
+    const session = await oxy.verifyChallenge('pubkey', 'challenge', 'sig', 123, 'Device', 'fp');
+
+    // Response still carries the tokens for callers that want them.
+    expect(session.accessToken).toBe('access_verify');
+    // ...and they are now planted on the client so subsequent requests are
+    // authenticated without a second round-trip.
+    expect(oxy.hasValidToken()).toBe(true);
+    expect(oxy.getAccessToken()).toBe('access_verify');
+  });
+
+  it('defaults the refresh token to an empty string when the response omits it', async () => {
+    const oxy = makeOxy();
+
+    jest.spyOn(oxy, 'makeRequest').mockImplementation(async (_method, url) => {
+      if (url === '/auth/verify') {
+        return {
+          sessionId: 'sess_2',
+          deviceId: 'dev_2',
+          expiresAt: new Date(Date.now() + 60_000).toISOString(),
+          accessToken: 'access_only',
+          user: { id: 'user_2', username: 'tester2' },
+        } as never;
+      }
+      throw new Error(`unexpected request to ${url}`);
+    });
+
+    const session = await oxy.verifyChallenge('pubkey', 'challenge', 'sig', 456);
+
+    expect(session.accessToken).toBe('access_only');
+    expect(oxy.hasValidToken()).toBe(true);
+    expect(oxy.getAccessToken()).toBe('access_only');
+  });
+
+  it('does NOT plant (and stays unauthenticated) when the response carries no access token', async () => {
+    const oxy = makeOxy();
+
+    jest.spyOn(oxy, 'makeRequest').mockImplementation(async (_method, url) => {
+      if (url === '/auth/verify') {
+        // Token-less new identity (onboarding) — no access token in the body.
+        return {
+          sessionId: 'sess_3',
+          deviceId: 'dev_3',
+          expiresAt: new Date(Date.now() + 60_000).toISOString(),
+          user: { id: 'user_3', username: 'tester3' },
+        } as VerifyResponse as never;
+      }
+      throw new Error(`unexpected request to ${url}`);
+    });
+
+    const session = await oxy.verifyChallenge('pubkey', 'challenge', 'sig', 789);
+
+    expect(session.accessToken).toBeUndefined();
+    // No token to plant — the client stays unauthenticated. Crucially the
+    // method does NOT reach for the bearer-protected session-token endpoint.
+    expect(oxy.hasValidToken()).toBe(false);
+  });
+
+  it('matches claimSessionByToken: both plant tokens via the same path', async () => {
+    const oxy = makeOxy();
+
+    jest.spyOn(oxy, 'makeRequest').mockImplementation(async (_method, url) => {
+      if (url === '/auth/session/claim') {
+        return {
+          accessToken: 'access_claim',
+          refreshToken: 'refresh_claim',
+          sessionId: 'sess_claim',
+          deviceId: 'dev_claim',
+          expiresAt: new Date(Date.now() + 60_000).toISOString(),
+          user: { id: 'user_claim', username: 'claimed' },
+        } as never;
+      }
+      throw new Error(`unexpected request to ${url}`);
+    });
+
+    await oxy.claimSessionByToken('session-token-abc');
+
+    expect(oxy.hasValidToken()).toBe(true);
+    expect(oxy.getAccessToken()).toBe('access_claim');
+  });
+});