@oxyhq/core 3.4.1 → 3.4.3

package/src/mixins/OxyServices.silent.ts

@@ -0,0 +1,272 @@
+import type { OxyServicesBase } from "../OxyServices.base";
+import type { SessionLoginResponse } from "../models/session";
+import { createDebugLogger } from "../shared/utils/debugUtils";
+
+const debug = createDebugLogger("SilentAuth");
+
+export interface SilentAuthOptions {
+	timeout?: number;
+	/**
+	 * Override the auth-web (IdP) origin used for the silent iframe, instead of
+	 * the instance's configured `resolveAuthUrl()`.
+	 *
+	 * Why this exists: an instance configured with the CENTRAL IdP
+	 * (`authWebUrl=https://auth.oxy.so`, for the opaque-code `/sso` bounce and
+	 * FedCM) cannot read the DURABLE per-apex `fedcm_session` cookie via the
+	 * central host — that cookie is first-party only on `auth.<rp-apex>` (e.g.
+	 * `auth.mention.earth`). The cross-domain reload-restore path must point the
+	 * `/auth/silent` iframe at the PER-APEX host so the cookie is same-site to
+	 * the RP page (first-party under Safari ITP / Firefox TCP) and the restore
+	 * is NOT a top-level navigation (no flash, works in a backgrounded tab).
+	 *
+	 * When provided this value is used BOTH for the iframe `src` AND for the
+	 * `postMessage` origin validation in {@link waitForIframeAuth}, so the
+	 * security check still matches the exact origin the iframe was loaded from.
+	 * Must be an absolute origin (`https://auth.<apex>`); ignored if empty.
+	 */
+	authWebUrlOverride?: string;
+}
+
+/**
+ * Cross-domain silent browser auth helpers.
+ *
+ * The clean session model supports FedCM, tokenless redirect SSO, and silent
+ * iframe SSO. Bearer-token callback URLs are not part of this surface.
+ */
+export function OxyServicesSilentAuthMixin<T extends typeof OxyServicesBase>(
+	Base: T,
+) {
+	return class extends Base {
+		constructor(...args: any[]) {
+			super(...(args as [any]));
+		}
+		public static readonly DEFAULT_AUTH_URL = "https://auth.oxy.so";
+
+		/** Resolve auth URL from config or static default (method, not getter — getters break in TS mixins) */
+		public resolveAuthUrl(): string {
+			return (
+				this.config.authWebUrl || (this.constructor as any).DEFAULT_AUTH_URL
+			);
+		}
+
+		public static readonly SILENT_TIMEOUT = 5000; // 5 seconds
+
+		/**
+		 * Silent sign-in using hidden iframe
+		 *
+		 * Attempts to automatically re-authenticate the user without any UI.
+		 * This is what enables seamless SSO across all Oxy domains.
+		 *
+		 * How it works:
+		 * 1. Creates hidden iframe pointing to auth.oxy.so/silent-auth
+		 * 2. If user has valid session at auth.oxy.so, it exchanges an opaque SSO code
+		 * 3. If not, iframe responds with null (no error thrown)
+		 *
+		 * This should be called on app startup to check for existing sessions.
+		 *
+		 * @param options - Silent auth options
+		 * @returns Session if user is signed in, null otherwise
+		 *
+		 * @example
+		 * ```typescript
+		 * useEffect(() => {
+		 *   const checkAuth = async () => {
+		 *     const session = await oxyServices.silentSignIn();
+		 *     if (session) {
+		 *       setUser(session.user);
+		 *     }
+		 *   };
+		 *   checkAuth();
+		 * }, []);
+		 * ```
+		 */
+		async silentSignIn(
+			options: SilentAuthOptions = {},
+		): Promise<SessionLoginResponse | null> {
+			if (typeof window === "undefined") {
+				return null;
+			}
+
+			const timeout =
+				options.timeout || (this.constructor as any).SILENT_TIMEOUT;
+			const nonce = this.generateNonce();
+			const clientId = window.location.origin;
+
+			// Resolve the IdP origin for the iframe. An explicit per-apex override (the
+			// durable cross-domain reload path — see `SilentAuthOptions.authWebUrlOverride`)
+			// wins over the instance's configured central auth URL. The SAME origin is
+			// handed to `waitForIframeAuth` so the postMessage origin check matches the
+			// exact host the iframe was loaded from.
+			const authOrigin =
+				options.authWebUrlOverride && options.authWebUrlOverride.length > 0
+					? options.authWebUrlOverride
+					: this.resolveAuthUrl();
+
+			const iframe = document.createElement("iframe");
+			iframe.style.display = "none";
+			iframe.style.position = "absolute";
+			iframe.style.width = "0";
+			iframe.style.height = "0";
+			iframe.style.border = "none";
+
+			const silentUrl =
+				`${authOrigin}/auth/silent?` +
+				`client_id=${encodeURIComponent(clientId)}&` +
+				`nonce=${nonce}`;
+
+			iframe.src = silentUrl;
+			document.body.appendChild(iframe);
+
+			try {
+				const session = await this.waitForIframeAuth(
+					iframe,
+					timeout,
+					authOrigin,
+				);
+
+				// Bail early on incomplete responses. The iframe contract requires
+				// both an access token and a session id; anything less is unusable.
+				// Returning `null` here (without installing the token) prevents a
+				// stale credential from being committed to HttpService when the
+				// user is actually signed out — that pattern caused a `getCurrentUser`
+				// -> 401 -> token-clear loop in consumer apps because callers gated
+				// on `session?.user` and never installed the user via
+				// `handleAuthSuccess`, while HttpService quietly held the token.
+				const accessToken = session
+					? (session as { accessToken?: string }).accessToken
+					: undefined;
+				if (!session || !accessToken || !session.sessionId) {
+					return null;
+				}
+
+				// Snapshot the previous token so we can roll back if the user
+				// lookup below fails — this avoids leaving a half-committed session
+				// (token installed, user missing) which would let the next
+				// authenticated request 401 with no way to recover.
+				const previousAccessToken = this.httpService.getAccessToken();
+				this.httpService.setTokens(accessToken);
+
+				// The iframe typically returns `{ sessionId, accessToken }` without
+				// user data. Fetch the user explicitly so callers receive a
+				// fully-formed session and never need a second `/users/me` round
+				// trip. If this fails the session is unusable — revert the token
+				// and return null so the caller treats this exactly like a
+				// missing-session response.
+				if (!session.user) {
+					try {
+						const userData = await this.makeRequest<unknown>(
+							"GET",
+							`/session/user/${session.sessionId}`,
+							undefined,
+							{ cache: false, retry: false },
+						);
+						if (!userData) {
+							throw new Error("Empty user response");
+						}
+						(session as { user?: unknown }).user = userData;
+					} catch (userError) {
+						debug.warn(
+							"silentSignIn: failed to fetch user data, rolling back token",
+							userError,
+						);
+						if (previousAccessToken) {
+							this.httpService.setTokens(previousAccessToken);
+						} else {
+							this.httpService.clearTokens();
+						}
+						return null;
+					}
+				}
+
+				return session;
+			} catch (error) {
+				return null;
+			} finally {
+				document.body.removeChild(iframe);
+			}
+		}
+
+		/**
+		 * Wait for authentication response from iframe
+		 *
+		 * @private
+		 */
+		public async waitForIframeAuth(
+			iframe: HTMLIFrameElement,
+			timeout: number,
+			expectedOrigin: string,
+		): Promise<SessionLoginResponse | null> {
+			return new Promise((resolve) => {
+				const timeoutId = setTimeout(() => {
+					cleanup();
+					resolve(null); // Silent failure - don't throw
+				}, timeout);
+
+				const messageHandler = (event: MessageEvent) => {
+					// Verify origin against the EXACT host the iframe was loaded from
+					// (`expectedOrigin`). For the per-apex durable-restore path this is
+					// `auth.<rp-apex>`, not the instance's central `resolveAuthUrl()` — so
+					// we must honour the caller-supplied origin, never re-derive it here.
+					if (event.origin !== expectedOrigin) {
+						return;
+					}
+
+					const { type, session } = event.data;
+
+					if (type !== "oxy_silent_auth") {
+						return;
+					}
+
+					cleanup();
+					resolve(session || null);
+				};
+
+				// Fail-fast on a load failure. When the per-apex `/auth/silent` host is
+				// unreachable, blocked by CSP `frame-ancestors`/`X-Frame-Options`, or the
+				// network drops, the iframe never posts a message — without this handler
+				// the silent restore would block for the FULL `timeout` (dead latency in
+				// the cold-boot critical path). `onerror`/`onabort` fire on a failed load,
+				// so resolve `null` immediately and let the next cold-boot step run. The
+				// success path posts a message and is handled above; these only catch the
+				// no-message failure modes.
+				const failFast = () => {
+					cleanup();
+					resolve(null);
+				};
+				iframe.onerror = failFast;
+				iframe.onabort = failFast;
+
+				const cleanup = () => {
+					clearTimeout(timeoutId);
+					iframe.onerror = null;
+					iframe.onabort = null;
+					window.removeEventListener("message", messageHandler);
+				};
+
+				window.addEventListener("message", messageHandler);
+			});
+		}
+
+		/**
+		 * Generate nonce for replay attack prevention
+		 *
+		 * @private
+		 */
+		public generateNonce(): string {
+			if (typeof crypto !== "undefined" && crypto.randomUUID) {
+				return crypto.randomUUID();
+			}
+			if (typeof crypto !== "undefined" && crypto.getRandomValues) {
+				const bytes = new Uint8Array(16);
+				crypto.getRandomValues(bytes);
+				return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join(
+					"",
+				);
+			}
+			throw new Error("No secure random source available for nonce generation");
+		}
+	};
+}
+
+// Export the mixin function as both named and default
+export { OxyServicesSilentAuthMixin as SilentAuthMixin };

package/src/mixins/OxyServices.sso.ts

@@ -31,7 +31,7 @@ const debug = createDebugLogger('SSO');
 
 /**
  * Wire shape of `POST /sso/exchange`. `expiresAt` and `authuser` are optional
- * (the central store may omit them for legacy single-slot sessions).
+ * because the central SSO store may omit them.
  */
 interface SsoExchangeWireResponse {
   accessToken: string;
@@ -51,8 +51,7 @@ interface SsoExchangeWireResponse {
  *
  * Exposed as a module-level helper (in addition to the instance method below)
  * so consumers that do not yet hold an `OxyServices` instance can still mint a
- * bounce state. Reuses the same `crypto.randomUUID`-based generator the popup
- * mixin uses for its CSRF state, with a `getRandomValues` fallback.
+ * bounce state. Uses `crypto.randomUUID` with a `getRandomValues` fallback.
  */
 export function generateSsoState(): string {
   if (typeof crypto !== 'undefined' && crypto.randomUUID) {
@@ -75,8 +74,8 @@ export function OxyServicesSsoMixin<T extends typeof OxyServicesBase>(Base: T) {
     /**
      * Generate cryptographically secure state for the SSO bounce (CSRF
      * protection). Delegates to the module-level {@link generateSsoState}
-     * helper, which uses the same `crypto.randomUUID`-based generator the popup
-     * mixin's `generateState()` uses — one shared secure-random implementation.
+     * helper, which uses `crypto.randomUUID` when available and falls back to
+     * `crypto.getRandomValues`.
      */
     public generateSsoState(): string {
       return generateSsoState();
@@ -154,7 +153,7 @@ export function OxyServicesSsoMixin<T extends typeof OxyServicesBase>(Base: T) {
       // Plant the access token exactly like exchangeIdTokenForSession does.
       // The SSO exchange does not return a refresh token (the central store
       // holds the refresh credential), so default it to an empty string.
-      this.httpService.setTokens(payload.accessToken, '');
+      this.httpService.setTokens(payload.accessToken);
 
       debug.log('SSO exchange complete:', { hasSession: !!payload.sessionId });
 

package/src/mixins/OxyServices.utility.ts

@@ -62,13 +62,8 @@ export interface ServiceApp {
   appId: string;
   appName: string;
   scopes: string[];
-  /**
-   * The credentialId of the specific service credential that minted this token.
-   * Carried by newer service-token JWTs alongside `appId`; absent on tokens
-   * issued before credential-level audit linking. Use for per-credential audit
-   * trails and rotation alignment (GitHub #215).
-   */
-  credentialId?: string;
+  /** The credentialId of the specific service credential that minted this token. */
+  credentialId: string;
 }
 
 /**
@@ -409,19 +404,12 @@ export function OxyServicesUtilityMixin<T extends typeof OxyServicesBase>(Base:
         };
 
         try {
-          // Extract token from Authorization header or query params.
+          // Extract token from Authorization header.
           // Node/Express normalizes `Authorization` to a string; we guard
           // against the (legal but unusual) string[] case anyway.
           const rawAuthHeader = req.headers.authorization;
           const authHeader = Array.isArray(rawAuthHeader) ? rawAuthHeader[0] : rawAuthHeader;
-          let token = authHeader?.startsWith('Bearer ') ? authHeader.substring(7) : null;
-
-          // Fallback to query params (useful for WebSocket upgrades)
-          if (!token) {
-            const q = req.query || {};
-            if (typeof q.token === 'string' && q.token) token = q.token;
-            else if (typeof q.access_token === 'string' && q.access_token) token = q.access_token;
-          }
+          const token = authHeader?.startsWith('Bearer ') ? authHeader.substring(7) : null;
 
           if (debug) {
             logger.debug(`[oxy.auth] ${req.method} ${req.path} | token: ${!!token}`, {
@@ -573,13 +561,14 @@ export function OxyServicesUtilityMixin<T extends typeof OxyServicesBase>(Base:
 
             // Validate required service token fields
             const appId = decoded.appId;
-            if (!appId) {
+            const credentialId = decoded.credentialId;
+            if (!appId || typeof credentialId !== 'string' || credentialId.length === 0) {
               if (optional) {
                 req.userId = null;
                 req.user = null;
                 return next();
               }
-              const error = { error: 'INVALID_SERVICE_TOKEN', message: 'Invalid service token: missing appId', code: 'INVALID_SERVICE_TOKEN', status: 401 };
+              const error = { error: 'INVALID_SERVICE_TOKEN', message: 'Invalid service token: missing required claims', code: 'INVALID_SERVICE_TOKEN', status: 401 };
               if (onError) return onError(error);
               return res.status(401).json(error);
             }
@@ -625,10 +614,8 @@ export function OxyServicesUtilityMixin<T extends typeof OxyServicesBase>(Base:
             req.serviceApp = {
               appId,
               appName: decoded.appName || 'unknown',
+              credentialId,
               scopes: Array.isArray(decoded.scopes) ? decoded.scopes : [],
-              ...(typeof decoded.credentialId === 'string' && decoded.credentialId.length > 0
-                ? { credentialId: decoded.credentialId }
-                : {}),
             };
 
             if (debug) {
@@ -1133,7 +1120,7 @@ interface OxyAuthInstance {
     [key: string]: unknown;
   } | null>;
   getAccessToken(): string | null;
-  setTokens(accessToken: string, refreshToken?: string): void;
+  setTokens(accessToken: string): void;
   clearTokens(): void;
   getCurrentUser(): Promise<User | null>;
   handleError(error: unknown): Error;

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

@@ -19,7 +19,7 @@ const setAccessTokenForTest = (oxy: OxyServices): void => {
   // `withAuthRetry` loop polls. Reaching in via the public httpService and
   // calling setTokens with a dummy avoids us needing to expose new test
   // hooks just for this.
-  oxy.httpService.setTokens('test-token', '');
+  oxy.httpService.setTokens('test-token');
 };
 
 describe('OxyServices.appData', () => {

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

@@ -29,7 +29,7 @@ describe('OxyServices.onTokensChanged', () => {
     const listener = jest.fn();
     oxy.onTokensChanged(listener);
 
-    oxy.setTokens('access_1', 'refresh_1');
+    oxy.setTokens('access_1');
 
     expect(listener).toHaveBeenCalledTimes(1);
     expect(listener).toHaveBeenCalledWith('access_1');

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

@@ -20,7 +20,7 @@ import type {
 } from '../OxyServices.reputation';
 
 const setAccessTokenForTest = (oxy: OxyServices): void => {
-  oxy.httpService.setTokens('test-token', '');
+  oxy.httpService.setTokens('test-token');
 };
 
 const balanceFixture: ReputationBalance = {

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

@@ -48,6 +48,7 @@ const signServiceToken = (claims: ServiceTokenClaims, secret: string): string =>
     type: 'service',
     aud: 'oxy-api',
     iss: 'oxy-auth',
+    credentialId: 'cred-1',
     ...claims,
   };
   const headerB64 = b64url(JSON.stringify(header));
@@ -180,6 +181,7 @@ describe('C3: service-token acting-as enforcement', () => {
     expect(req.serviceApp).toEqual({
       appId: 'app-1',
       appName: 'trusted-service',
+      credentialId: 'cred-1',
       scopes: ['user:read'],
     });
   });
@@ -202,7 +204,7 @@ describe('C3: service-token acting-as enforcement', () => {
     expect(verifySpy).not.toHaveBeenCalled();
     expect(next).toHaveBeenCalledTimes(1);
     expect(req.userId).toBeNull();
-    expect(req.serviceApp).toMatchObject({ appId: 'app-1' });
+    expect(req.serviceApp).toMatchObject({ appId: 'app-1', credentialId: 'cred-1' });
   });
 
   it('caches positive grants per (appId, userId) — avoids hammering verify endpoint', async () => {
@@ -620,7 +622,7 @@ describe('H4: aud / iss / type claim verification', () => {
     await mw(req as unknown as never, res as unknown as never, next as unknown as never);
 
     expect(next).toHaveBeenCalledTimes(1);
-    expect(req.serviceApp).toMatchObject({ appId: 'a' });
+    expect(req.serviceApp).toMatchObject({ appId: 'a', credentialId: 'cred-1' });
   });
 
   it('honors expectedAudience and expectedIssuer overrides', async () => {
@@ -660,7 +662,7 @@ describe('requireScope() middleware', () => {
       // Simulate a fully-authenticated service request — auth() has already
       // attached `serviceApp`. requireScope() only reads from that field.
     });
-    req.serviceApp = { appId: 'a', appName: 'svc', scopes: ['files:write'] };
+    req.serviceApp = { appId: 'a', appName: 'svc', credentialId: 'cred-1', scopes: ['files:write'] };
     const res = makeRes();
     const next = jest.fn();
 
@@ -672,7 +674,7 @@ describe('requireScope() middleware', () => {
 
   it('allows requests where the delegation grant carries the required scope', () => {
     const req = makeReq();
-    req.serviceApp = { appId: 'a', appName: 'svc', scopes: [] };
+    req.serviceApp = { appId: 'a', appName: 'svc', credentialId: 'cred-1', scopes: [] };
     req.serviceActingAs = { userId: 'u-1', scopes: ['user:read'] };
     const res = makeRes();
     const next = jest.fn();
@@ -684,7 +686,7 @@ describe('requireScope() middleware', () => {
 
   it('rejects requests missing the required scope with 403', () => {
     const req = makeReq();
-    req.serviceApp = { appId: 'a', appName: 'svc', scopes: ['user:read'] };
+    req.serviceApp = { appId: 'a', appName: 'svc', credentialId: 'cred-1', scopes: ['user:read'] };
     const res = makeRes();
     const next = jest.fn();
 

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

@@ -0,0 +1,102 @@
+/**
+ * Silent iframe auth tests.
+ *
+ * The cross-domain durable-restore iframe (`/auth/silent` at the per-apex host)
+ * posts a message on success. On a failed load, it never posts, so
+ * `waitForIframeAuth` must resolve `null` immediately instead of waiting for
+ * the full timeout.
+ */
+
+import { OxyServices } from '../../OxyServices';
+
+const ORIGIN = 'https://mention.earth';
+
+function installBrowserGlobals(options: {
+  postMessageDispatcher?: { current: ((event: { origin: string; data: unknown }) => void) | null };
+} = {}): void {
+  const store = new Map<string, string>();
+  const sessionStorageStub = {
+    getItem: (k: string) => (store.has(k) ? (store.get(k) as string) : null),
+    setItem: (k: string, v: string) => { store.set(k, v); },
+    removeItem: (k: string) => { store.delete(k); },
+  };
+  const messageHandlers: Array<(event: { origin: string; data: unknown }) => void> = [];
+  const win = {
+    location: { origin: ORIGIN, hostname: 'mention.earth' },
+    sessionStorage: sessionStorageStub,
+    addEventListener: (event: string, handler: (e: { origin: string; data: unknown }) => void) => {
+      if (event === 'message') {
+        messageHandlers.push(handler);
+        if (options.postMessageDispatcher) {
+          options.postMessageDispatcher.current = handler;
+        }
+      }
+    },
+    removeEventListener: (event: string, handler: (e: { origin: string; data: unknown }) => void) => {
+      if (event === 'message') {
+        const idx = messageHandlers.indexOf(handler);
+        if (idx >= 0) messageHandlers.splice(idx, 1);
+      }
+    },
+  };
+  (globalThis as unknown as { window: unknown }).window = win;
+  (globalThis as unknown as { sessionStorage: unknown }).sessionStorage = sessionStorageStub;
+}
+
+function clearBrowserGlobals(): void {
+  for (const key of ['window', 'sessionStorage'] as const) {
+    delete (globalThis as Record<string, unknown>)[key];
+  }
+}
+
+interface FakeIframe {
+  onerror: ((this: unknown, ...args: unknown[]) => unknown) | null;
+  onabort: ((this: unknown, ...args: unknown[]) => unknown) | null;
+}
+
+describe('OxyServices waitForIframeAuth fail-fast on iframe load error', () => {
+  afterEach(() => {
+    clearBrowserGlobals();
+    jest.restoreAllMocks();
+  });
+
+  it('resolves null immediately when the iframe fires onerror', async () => {
+    installBrowserGlobals();
+
+    const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+    const iframe: FakeIframe = { onerror: null, onabort: null };
+
+    const settled = oxy.waitForIframeAuth(
+      iframe as unknown as HTMLIFrameElement,
+      100000,
+      'https://auth.mention.earth',
+    );
+
+    await Promise.resolve();
+    expect(typeof iframe.onerror).toBe('function');
+    iframe.onerror?.call(iframe);
+
+    await expect(settled).resolves.toBeNull();
+    expect(iframe.onerror).toBeNull();
+    expect(iframe.onabort).toBeNull();
+  });
+
+  it('resolves null immediately when the iframe fires onabort', async () => {
+    installBrowserGlobals();
+
+    const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+    const iframe: FakeIframe = { onerror: null, onabort: null };
+
+    const settled = oxy.waitForIframeAuth(
+      iframe as unknown as HTMLIFrameElement,
+      100000,
+      'https://auth.mention.earth',
+    );
+
+    await Promise.resolve();
+    expect(typeof iframe.onabort).toBe('function');
+    iframe.onabort?.call(iframe);
+
+    await expect(settled).resolves.toBeNull();
+  });
+});

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

@@ -2,13 +2,11 @@
  * `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` —
+ * first `accessToken` minted by `POST /auth/verify`. It must
+ * plant that token 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.
+ * with an authenticated client. Session IDs are not public token-minting
+ * credentials, so the initial bearer must come from the verify response body.
  *
  * 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
@@ -22,7 +20,6 @@ interface VerifyResponse {
   deviceId: string;
   expiresAt: string;
   accessToken?: string;
-  refreshToken?: string;
   user: { id: string; username: string };
 }
 
@@ -35,7 +32,7 @@ describe('OxyServices.verifyChallenge token planting', () => {
     jest.restoreAllMocks();
   });
 
-  it('plants the access + refresh token from the /auth/verify response body', async () => {
+  it('plants the access token from the /auth/verify response body', async () => {
     const oxy = makeOxy();
     expect(oxy.hasValidToken()).toBe(false);
 
@@ -46,7 +43,6 @@ describe('OxyServices.verifyChallenge token planting', () => {
           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;
       }
@@ -55,15 +51,15 @@ describe('OxyServices.verifyChallenge token planting', () => {
 
     const session = await oxy.verifyChallenge('pubkey', 'challenge', 'sig', 123, 'Device', 'fp');
 
-    // Response still carries the tokens for callers that want them.
+    // Response still carries the access token for callers that want it.
     expect(session.accessToken).toBe('access_verify');
-    // ...and they are now planted on the client so subsequent requests are
+    // ...and it is 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 () => {
+  it('plants the access token when no refresh token is present', async () => {
     const oxy = makeOxy();
 
     jest.spyOn(oxy, 'makeRequest').mockImplementation(async (_method, url) => {
@@ -110,14 +106,13 @@ describe('OxyServices.verifyChallenge token planting', () => {
     expect(oxy.hasValidToken()).toBe(false);
   });
 
-  it('matches claimSessionByToken: both plant tokens via the same path', async () => {
+  it('matches claimSessionByToken: both plant access 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(),