@oxyhq/core 11.0.0 → 12.0.0

package/src/mixins/OxyServices.identity.ts

@@ -53,7 +53,7 @@ const OXY_IDENTITY_APEX = 'oxy.so';
 export type IdentityRecordType = OxySignedRecordType;
 
 /** Auth-method types that can be unlinked via {@link OxyServicesIdentityMixin}. */
-export type UnlinkableAuthMethodType = 'identity' | 'password' | 'google' | 'apple' | 'github';
+export type UnlinkableAuthMethodType = 'identity' | 'webauthn';
 
 /**
  * Result of a link/unlink auth-method mutation (`POST /auth/link`,
@@ -207,18 +207,18 @@ export function OxyServicesIdentityMixin<T extends typeof OxyServicesBase>(Base:
     }
 
     /**
-     * Link password authentication to the current account. Adds a `password`
-     * auth method (does not remove existing methods).
+     * Unlink an authentication method from the current account. The server
+     * refuses to remove the last remaining method (the account would become
+     * inaccessible). Unlinking `identity` downgrades the account to custodial.
      *
-     * @param email - The email to associate with password auth.
-     * @param password - The new password (server enforces strength rules).
+     * @param type - The auth-method type to remove.
      */
-    async linkPassword(email: string, password: string): Promise<LinkAuthMethodResult> {
+    async unlinkAuthMethod(type: UnlinkableAuthMethodType): Promise<LinkAuthMethodResult> {
       try {
         const result = await this.makeRequest<LinkAuthMethodResult>(
-          'POST',
-          '/auth/link',
-          { type: 'password', email, password },
+          'DELETE',
+          `/auth/link/${encodeURIComponent(type)}`,
+          undefined,
           { cache: false },
         );
         this._invalidateIdentityCaches(this.getCurrentUserId());
@@ -229,17 +229,21 @@ export function OxyServicesIdentityMixin<T extends typeof OxyServicesBase>(Base:
     }
 
     /**
-     * Unlink an authentication method from the current account. The server
-     * refuses to remove the last remaining method (the account would become
-     * inaccessible). Unlinking `identity` downgrades the account to custodial.
+     * Remove ONE passkey (WebAuthn credential) from the current account.
      *
-     * @param type - The auth-method type to remove.
+     * Passkeys are per-credential, so unlike {@link unlinkAuthMethod} (which
+     * removes an auth method by type) this targets a specific credential id.
+     * The server refuses to remove the last remaining auth method (the account
+     * would become inaccessible) and deletes the stored `WebauthnCredential`.
+     *
+     * @param credentialId - The passkey's public credential id
+     *   (`AuthMethodEntry.credentialId`).
      */
-    async unlinkAuthMethod(type: UnlinkableAuthMethodType): Promise<LinkAuthMethodResult> {
+    async removePasskey(credentialId: string): Promise<LinkAuthMethodResult> {
       try {
         const result = await this.makeRequest<LinkAuthMethodResult>(
           'DELETE',
-          `/auth/link/${encodeURIComponent(type)}`,
+          `/auth/link/webauthn/${encodeURIComponent(credentialId)}`,
           undefined,
           { cache: false },
         );

package/src/mixins/__tests__/OxyServices.identity.test.ts

@@ -186,37 +186,49 @@ describe('OxyServices.identity', () => {
     });
   });
 
-  describe('linkPassword', () => {
-    it('POSTs /auth/link with the password method and sweeps cache', async () => {
-      makeRequestSpy.mockResolvedValue({ success: true, message: 'Password auth linked successfully' });
+  describe('unlinkAuthMethod', () => {
+    it('DELETEs /auth/link/:type and sweeps cache', async () => {
+      makeRequestSpy.mockResolvedValue({ success: true, message: 'identity auth unlinked successfully' });
 
-      await oxy.linkPassword('nate@oxy.so', 'sup3r-secret');
+      await oxy.unlinkAuthMethod('identity');
 
       expect(makeRequestSpy).toHaveBeenCalledWith(
-        'POST',
-        '/auth/link',
-        { type: 'password', email: 'nate@oxy.so', password: 'sup3r-secret' },
+        'DELETE',
+        '/auth/link/identity',
+        undefined,
         expect.objectContaining({ cache: false }),
       );
-      expect(clearPrefixSpy).toHaveBeenCalledWith('GET:/users/me');
-      expect(clearEntrySpy).toHaveBeenCalledWith('GET:/auth/methods');
+      expect(clearEntrySpy).toHaveBeenCalledWith('GET:/u/user-123/did.json');
     });
   });
 
-  describe('unlinkAuthMethod', () => {
-    it('DELETEs /auth/link/:type and sweeps cache', async () => {
-      makeRequestSpy.mockResolvedValue({ success: true, message: 'identity auth unlinked successfully' });
+  describe('removePasskey', () => {
+    it('DELETEs /auth/link/webauthn/:credentialID and sweeps cache', async () => {
+      makeRequestSpy.mockResolvedValue({ success: true, message: 'Passkey unlinked successfully' });
 
-      await oxy.unlinkAuthMethod('identity');
+      await oxy.removePasskey('cred-abc');
 
       expect(makeRequestSpy).toHaveBeenCalledWith(
         'DELETE',
-        '/auth/link/identity',
+        '/auth/link/webauthn/cred-abc',
         undefined,
         expect.objectContaining({ cache: false }),
       );
       expect(clearEntrySpy).toHaveBeenCalledWith('GET:/u/user-123/did.json');
     });
+
+    it('URL-encodes the credential id', async () => {
+      makeRequestSpy.mockResolvedValue({ success: true, message: 'Passkey unlinked successfully' });
+
+      await oxy.removePasskey('a/b+c=');
+
+      expect(makeRequestSpy).toHaveBeenCalledWith(
+        'DELETE',
+        '/auth/link/webauthn/a%2Fb%2Bc%3D',
+        undefined,
+        expect.objectContaining({ cache: false }),
+      );
+    });
   });
 
   describe('signRecord (client-only)', () => {

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

@@ -0,0 +1,206 @@
+/**
+ * WebAuthn / passkey auth methods on OxyServices
+ * (`webauthnRegisterOptions` / `webauthnRegisterVerify` /
+ * `webauthnLoginOptions` / `webauthnLoginVerify`).
+ *
+ * Stubs `makeRequest` (HTTP-mock style) and
+ * asserts: each method hits the right endpoint with the right body; the opaque
+ * ceremony `response` is forwarded verbatim; the login/verify + register/verify
+ * (signup) paths parse the login contract and plant the access token on the
+ * session arm; register/verify (link) returns `{ success, message }` WITHOUT
+ * planting a token.
+ */
+import type { LoginResult } from '@oxyhq/contracts';
+import { OxyServices } from '../../OxyServices';
+
+const SESSION_ARM: LoginResult = {
+  sessionId: 'sess-1',
+  deviceId: 'dev-1',
+  expiresAt: '2030-01-01T00:00:00.000Z',
+  accessToken: 'access-1',
+  deviceSecret: 'ds-secret-1',
+  user: { id: 'user-1', username: 'u' },
+};
+
+const LINK_RESULT = { success: true as const, message: 'Passkey registered successfully' };
+
+// Opaque browser ceremony payloads — Oxy never inspects these, so shape is
+// irrelevant beyond "forwarded verbatim under `response`".
+const CREATE_RESPONSE = { id: 'cred-abc', rawId: 'cred-abc', response: { attestationObject: 'ao' }, type: 'public-key' };
+const GET_RESPONSE = { id: 'cred-abc', rawId: 'cred-abc', response: { signature: 'sig' }, type: 'public-key' };
+
+describe('webauthnRegisterOptions', () => {
+  let oxy: OxyServices;
+  let makeRequest: jest.SpyInstance;
+
+  beforeEach(() => {
+    oxy = new OxyServices({ baseURL: 'http://test.invalid' });
+    makeRequest = jest.spyOn(oxy, 'makeRequest');
+  });
+  afterEach(() => jest.restoreAllMocks());
+
+  it('POSTs to /auth/webauthn/register/options with the username', async () => {
+    const options = { challenge: 'c', rp: { id: 'oxy.so' } };
+    makeRequest.mockResolvedValueOnce(options);
+    const result = await oxy.webauthnRegisterOptions('alice');
+    expect(result).toBe(options);
+    expect(makeRequest).toHaveBeenCalledWith(
+      'POST',
+      '/auth/webauthn/register/options',
+      { username: 'alice' },
+      { cache: false },
+    );
+  });
+
+  it('omits username from the body when not provided (link flow)', async () => {
+    makeRequest.mockResolvedValueOnce({ challenge: 'c' });
+    await oxy.webauthnRegisterOptions();
+    expect(makeRequest).toHaveBeenCalledWith(
+      'POST',
+      '/auth/webauthn/register/options',
+      {},
+      { cache: false },
+    );
+  });
+});
+
+describe('webauthnLoginOptions', () => {
+  let oxy: OxyServices;
+  let makeRequest: jest.SpyInstance;
+
+  beforeEach(() => {
+    oxy = new OxyServices({ baseURL: 'http://test.invalid' });
+    makeRequest = jest.spyOn(oxy, 'makeRequest');
+  });
+  afterEach(() => jest.restoreAllMocks());
+
+  it('POSTs to /auth/webauthn/login/options with the username (username-first)', async () => {
+    const options = { challenge: 'c', allowCredentials: [{ id: 'cred-abc' }] };
+    makeRequest.mockResolvedValueOnce(options);
+    const result = await oxy.webauthnLoginOptions('alice');
+    expect(result).toBe(options);
+    expect(makeRequest).toHaveBeenCalledWith(
+      'POST',
+      '/auth/webauthn/login/options',
+      { username: 'alice' },
+      { cache: false },
+    );
+  });
+
+  it('omits username for the usernameless / discoverable flow', async () => {
+    makeRequest.mockResolvedValueOnce({ challenge: 'c', allowCredentials: [] });
+    await oxy.webauthnLoginOptions();
+    expect(makeRequest).toHaveBeenCalledWith(
+      'POST',
+      '/auth/webauthn/login/options',
+      {},
+      { cache: false },
+    );
+  });
+});
+
+describe('webauthnRegisterVerify', () => {
+  let oxy: OxyServices;
+  let makeRequest: jest.SpyInstance;
+  let setTokens: jest.SpyInstance;
+
+  beforeEach(() => {
+    oxy = new OxyServices({ baseURL: 'http://test.invalid' });
+    makeRequest = jest.spyOn(oxy, 'makeRequest');
+    setTokens = jest.spyOn(oxy, 'setTokens').mockImplementation(() => undefined);
+  });
+  afterEach(() => jest.restoreAllMocks());
+
+  it('signup branch: parses LoginSessionResult, plants the token, threads the envelope', async () => {
+    makeRequest.mockResolvedValueOnce(SESSION_ARM);
+    const result = await oxy.webauthnRegisterVerify(CREATE_RESPONSE, {
+      username: 'alice',
+      deviceName: 'Phone',
+      deviceFingerprint: 'fp-1',
+    });
+    expect(result).toEqual(SESSION_ARM);
+    expect('twoFactorRequired' in result).toBe(false);
+    if (!('twoFactorRequired' in result) && 'sessionId' in result) {
+      expect(result.deviceId).toBe('dev-1');
+      expect(result.deviceSecret).toBe('ds-secret-1');
+    }
+    expect(setTokens).toHaveBeenCalledWith('access-1');
+    expect(makeRequest).toHaveBeenCalledWith(
+      'POST',
+      '/auth/webauthn/register/verify',
+      { response: CREATE_RESPONSE, username: 'alice', deviceName: 'Phone', deviceFingerprint: 'fp-1' },
+      { cache: false },
+    );
+  });
+
+  it('link branch: returns { success, message } WITHOUT planting a token', async () => {
+    makeRequest.mockResolvedValueOnce(LINK_RESULT);
+    const result = await oxy.webauthnRegisterVerify(CREATE_RESPONSE, { deviceName: 'Laptop' });
+    expect(result).toEqual(LINK_RESULT);
+    expect(setTokens).not.toHaveBeenCalled();
+    expect(makeRequest).toHaveBeenCalledWith(
+      'POST',
+      '/auth/webauthn/register/verify',
+      { response: CREATE_RESPONSE, deviceName: 'Laptop' },
+      { cache: false },
+    );
+  });
+
+  it('throws on an unexpected response shape', async () => {
+    makeRequest.mockResolvedValueOnce({ nope: true });
+    await expect(oxy.webauthnRegisterVerify(CREATE_RESPONSE)).rejects.toThrow();
+    expect(setTokens).not.toHaveBeenCalled();
+  });
+});
+
+describe('webauthnLoginVerify', () => {
+  let oxy: OxyServices;
+  let makeRequest: jest.SpyInstance;
+  let setTokens: jest.SpyInstance;
+
+  beforeEach(() => {
+    oxy = new OxyServices({ baseURL: 'http://test.invalid' });
+    makeRequest = jest.spyOn(oxy, 'makeRequest');
+    setTokens = jest.spyOn(oxy, 'setTokens').mockImplementation(() => undefined);
+  });
+  afterEach(() => jest.restoreAllMocks());
+
+  it('parses LoginSessionResult, plants the token, and threads the device envelope', async () => {
+    makeRequest.mockResolvedValueOnce(SESSION_ARM);
+    const result = await oxy.webauthnLoginVerify(GET_RESPONSE, {
+      deviceName: 'Phone',
+      deviceFingerprint: 'fp-1',
+      deviceId: 'dev-persisted',
+    });
+    expect(result).toEqual(SESSION_ARM);
+    expect('twoFactorRequired' in result).toBe(false);
+    if (!('twoFactorRequired' in result)) {
+      expect(result.deviceId).toBe('dev-1');
+      expect(result.deviceSecret).toBe('ds-secret-1');
+    }
+    expect(setTokens).toHaveBeenCalledWith('access-1');
+    expect(makeRequest).toHaveBeenCalledWith(
+      'POST',
+      '/auth/webauthn/login/verify',
+      { response: GET_RESPONSE, deviceName: 'Phone', deviceFingerprint: 'fp-1', deviceId: 'dev-persisted' },
+      { cache: false },
+    );
+  });
+
+  it('POSTs the bare response body when no envelope is passed', async () => {
+    makeRequest.mockResolvedValueOnce(SESSION_ARM);
+    await oxy.webauthnLoginVerify(GET_RESPONSE);
+    expect(makeRequest).toHaveBeenCalledWith(
+      'POST',
+      '/auth/webauthn/login/verify',
+      { response: GET_RESPONSE },
+      { cache: false },
+    );
+  });
+
+  it('throws on an unexpected response shape', async () => {
+    makeRequest.mockResolvedValueOnce({ nope: true });
+    await expect(oxy.webauthnLoginVerify(GET_RESPONSE)).rejects.toThrow();
+    expect(setTokens).not.toHaveBeenCalled();
+  });
+});

package/src/session/__tests__/accountDialogController.test.ts

@@ -664,72 +664,6 @@ describe('AccountDialogController — Commons deep-link (canOpenApp)', () => {
   });
 });
 
-describe('AccountDialogController — openPasswordAtOxyAuth', () => {
-  beforeEach(() => {
-    const store = new Map<string, string>();
-    Object.defineProperty(globalThis, 'sessionStorage', {
-      value: {
-        getItem: (key: string) => store.get(key) ?? null,
-        setItem: (key: string, value: string) => {
-          store.set(key, value);
-        },
-        removeItem: (key: string) => {
-          store.delete(key);
-        },
-      },
-      configurable: true,
-    });
-  });
-
-  it('builds the IdP sign-in URL with redirect_uri + client_id and invokes openUrl', async () => {
-    const oxy = makeOxy();
-    const sc = new TestSessionClient(host());
-    const openUrl = jest.fn();
-    const controller = new AccountDialogController({
-      oxyServices: oxy as unknown as OxyServices,
-      sessionClient: sc,
-      clientId: 'oxy_dk_test',
-      openUrl,
-    });
-
-    const url = await controller.openPasswordAtOxyAuth({ returnUrl: 'https://mention.earth/dashboard' });
-    const parsed = new URL(url);
-    expect(parsed.origin).toBe('https://auth.oxy.so');
-    expect(parsed.pathname).toBe('/login');
-    expect(parsed.searchParams.get('redirect_uri')).toBe('https://mention.earth');
-    expect(parsed.searchParams.get('client_id')).toBe('oxy_dk_test');
-    expect(parsed.searchParams.get('state')).toBeTruthy();
-    expect(parsed.searchParams.get('code_challenge')).toBeTruthy();
-    expect(parsed.searchParams.get('code_challenge_method')).toBe('S256');
-    expect(openUrl).toHaveBeenCalledWith(url);
-  });
-
-  it('honors authRedirectUri over returnUrl', async () => {
-    const oxy = makeOxy();
-    const sc = new TestSessionClient(host());
-    const controller = new AccountDialogController({
-      oxyServices: oxy as unknown as OxyServices,
-      sessionClient: sc,
-      authRedirectUri: 'https://inbox.oxy.so',
-    });
-
-    const url = await controller.openPasswordAtOxyAuth({ returnUrl: 'https://inbox.oxy.so/mail' });
-    expect(new URL(url).searchParams.get('redirect_uri')).toBe('https://inbox.oxy.so');
-  });
-
-  it('honors an idpApex override', async () => {
-    const oxy = makeOxy();
-    const sc = new TestSessionClient(host());
-    const controller = new AccountDialogController({
-      oxyServices: oxy as unknown as OxyServices,
-      sessionClient: sc,
-      idpApex: 'alia.onl',
-    });
-    const url = await controller.openPasswordAtOxyAuth({ returnUrl: 'https://alia.onl/' });
-    expect(new URL(url).origin).toBe('https://auth.alia.onl');
-  });
-});
-
 describe('AccountDialogController — /auth-session socket (instant QR wake)', () => {
   type Handler = (...args: unknown[]) => void;
   class FakeAuthSocket implements MinimalSocket {

package/src/session/accountDialogController.ts

@@ -21,9 +21,8 @@
  *     `oxyServices.signInWithSharedIdentity`, else the cross-device QR handoff
  *     via `startCommonsSignIn` → poll → `claimSessionByToken`).
  *
- * It deliberately owns NO password/2FA logic — those live at the IdP
- * (auth.oxy.so). {@link AccountDialogController.openPasswordAtOxyAuth} only
- * builds the hand-off URL; device-first convergence syncs the session back.
+ * Sign-in is passkey (WebAuthn) or the Commons QR / shared-keychain handoff —
+ * password, social login, and 2FA were removed ecosystem-wide.
  */
 
 import type { OxyServices } from '../OxyServices';
@@ -31,13 +30,6 @@ import type { SessionLoginResponse, MinimalUserData } from '../models/session';
 import type { User } from '../models/interfaces';
 import { logger } from '../logger';
 import { extractErrorStatus } from '../utils/errorUtils';
-import { CENTRAL_IDP_APEX } from '../utils/authWebUrl';
-import {
-  generateOAuthState,
-  generatePkcePair,
-  normalizeOAuthRedirectUri,
-  persistOAuthHandshake,
-} from '../utils/oauthPkce';
 import type { SessionClient } from './SessionClient';
 import type { MinimalSocket, SocketIOFactory } from './socketLoader';
 import {
@@ -117,14 +109,6 @@ export interface AccountDialogControllerOptions {
   commitSession?: (session: SessionLoginResponse) => Promise<void>;
   /** Notified after a completed sign-in (bearer planted + session committed). */
   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 FALLBACK poll interval in ms (default 12000). The primary
    * approval signal is the `/auth-session` socket's `auth_update` event (instant);
@@ -140,8 +124,8 @@ export interface AccountDialogControllerOptions {
    */
   socketFactory?: SocketIOFactory;
   /**
-   * Optional URL opener. When provided, `openPasswordAtOxyAuth` invokes it with
-   * the built URL in addition to returning it (web: `location.assign`; native:
+   * Optional URL opener. When provided, the controller invokes it to deep-link
+   * the Commons app for the QR handoff (web: `location.assign`; native:
    * `Linking.openURL`). Headless core never touches `window`/`Linking` itself.
    */
   openUrl?: (url: string) => void;
@@ -196,8 +180,6 @@ export class AccountDialogController {
   private readonly locale?: string;
   private readonly commitSession?: (session: SessionLoginResponse) => Promise<void>;
   private readonly onSignedIn?: (user: MinimalUserData) => void;
-  private readonly idpApex: string;
-  private readonly authRedirectUri: string | null;
   private readonly pollIntervalMs: number;
   private readonly openUrl?: (url: string) => void;
   private readonly canOpenApp?: (url: string) => Promise<boolean>;
@@ -247,8 +229,6 @@ export class AccountDialogController {
     this.locale = options.locale;
     this.commitSession = options.commitSession;
     this.onSignedIn = options.onSignedIn;
-    this.idpApex = options.idpApex ?? CENTRAL_IDP_APEX;
-    this.authRedirectUri = options.authRedirectUri ?? null;
     this.pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
     this.openUrl = options.openUrl;
     this.canOpenApp = options.canOpenApp;
@@ -652,50 +632,6 @@ export class AccountDialogController {
     }
   }
 
-  /**
-   * Build (and, when an `openUrl` handler was supplied, open) the auth.oxy.so
-   * password sign-in URL. Password + 2FA are NOT in the SDK — they live at the
-   * IdP; this only hands off. Device-first: after login at the IdP the device
-   * session converges and the caller is woken via the device socket /
-   * `BroadcastChannel`, so the URL only needs to point at the IdP sign-in with
-   * the right return.
-   *
-   * @param params.returnUrl - Where the IdP returns after login. Defaults to the
-   *   current document URL on web (`globalThis.location.href`); pass explicitly
-   *   on native (no `location`).
-   * @param params.state - Optional opaque state echoed back on return.
-   * @returns The absolute auth.oxy.so sign-in URL.
-   */
-  async openPasswordAtOxyAuth(
-    params: { returnUrl?: string; state?: string; redirectUri?: string } = {},
-  ): Promise<string> {
-    const base = `https://auth.${this.idpApex}`;
-    const url = new URL('/login', base);
-    const rawRedirect =
-      params.redirectUri ??
-      this.authRedirectUri ??
-      params.returnUrl ??
-      currentLocationOrigin();
-    const redirectUri = rawRedirect ? normalizeOAuthRedirectUri(rawRedirect) : '';
-    if (redirectUri) {
-      url.searchParams.set('redirect_uri', redirectUri);
-    }
-    if (this.clientId) {
-      url.searchParams.set('client_id', this.clientId);
-    }
-    const state = params.state ?? (await generateOAuthState());
-    url.searchParams.set('state', state);
-    const { codeChallenge, codeVerifier } = await generatePkcePair();
-    url.searchParams.set('code_challenge', codeChallenge);
-    url.searchParams.set('code_challenge_method', 'S256');
-    if (!persistOAuthHandshake(state, codeVerifier)) {
-      throw new Error('Could not persist OAuth handshake for password sign-in');
-    }
-    const href = url.toString();
-    this.openUrl?.(href);
-    return href;
-  }
-
   // =========================================================================
   // Internal sign-in helpers
   // =========================================================================
@@ -961,13 +897,3 @@ export function createAccountDialogController(
 ): AccountDialogController {
   return new AccountDialogController(options);
 }
-
-// ---------------------------------------------------------------------------
-// Local helpers
-// ---------------------------------------------------------------------------
-
-/** Current document origin on web; empty string where `location` is absent (native/SSR). */
-function currentLocationOrigin(): string {
-  const location = (globalThis as { location?: { origin?: string } }).location;
-  return typeof location?.origin === 'string' ? location.origin : '';
-}

package/src/utils/__tests__/officialOrigins.test.ts

@@ -3,6 +3,7 @@ import {
   buildIdpHubOrigin,
   isAllowedDeviceJoinOrigin,
   isIdpHubOrigin,
+  isLoopbackOrigin,
   isOfficialWebOrigin,
   normalizeOfficialReturnOrigin,
   parseHubSyncReturnUrl,
@@ -19,6 +20,19 @@ describe('officialOrigins', () => {
     expect(isOfficialWebOrigin('https://evil.example')).toBe(false);
   });
 
+  it('flags loopback / local-dev origins on any port', () => {
+    expect(isLoopbackOrigin('http://localhost:3000')).toBe(true);
+    expect(isLoopbackOrigin('http://127.0.0.1:8081')).toBe(true);
+    expect(isLoopbackOrigin('http://[::1]:19006')).toBe(true);
+    expect(isLoopbackOrigin('https://localhost')).toBe(true);
+    expect(isLoopbackOrigin('https://accounts.oxy.so')).toBe(false);
+    expect(isLoopbackOrigin('https://evil.example')).toBe(false);
+  });
+
+  it('treats loopback as an official origin (loopback dev is trusted)', () => {
+    expect(isOfficialWebOrigin('http://localhost:3000')).toBe(true);
+  });
+
   it('keeps the deprecated alias in sync with isOfficialWebOrigin', () => {
     expect(isAllowedDeviceJoinOrigin('https://accounts.oxy.so')).toBe(true);
     expect(isAllowedDeviceJoinOrigin('https://evil.example')).toBe(false);

package/src/utils/__tests__/webauthnOrigin.test.ts

@@ -0,0 +1,83 @@
+/**
+ * `isOxyRpOrigin()` — client-side WebAuthn relying-party origin guard.
+ *
+ * Runs under the `node` test environment, where `globalThis.location` is
+ * genuinely absent by default (mirroring native/SSR). Each case defines a fake
+ * `location` with the host under test and restores the original afterwards.
+ */
+import { isOxyRpOrigin } from '../webauthnOrigin';
+
+describe('isOxyRpOrigin', () => {
+  const originalLocation = globalThis.location;
+
+  const setHostname = (hostname: unknown): void => {
+    Object.defineProperty(globalThis, 'location', {
+      configurable: true,
+      value: hostname === undefined ? undefined : { hostname },
+    });
+  };
+
+  afterEach(() => {
+    Object.defineProperty(globalThis, 'location', {
+      configurable: true,
+      value: originalLocation,
+    });
+  });
+
+  it('returns true on the apex oxy.so', () => {
+    setHostname('oxy.so');
+    expect(isOxyRpOrigin()).toBe(true);
+  });
+
+  it('returns true on an oxy.so subdomain', () => {
+    setHostname('accounts.oxy.so');
+    expect(isOxyRpOrigin()).toBe(true);
+  });
+
+  it('returns true on a deep oxy.so subdomain', () => {
+    setHostname('sub.accounts.oxy.so');
+    expect(isOxyRpOrigin()).toBe(true);
+  });
+
+  it('returns true on loopback hosts', () => {
+    for (const host of ['localhost', '127.0.0.1', '[::1]']) {
+      setHostname(host);
+      expect(isOxyRpOrigin()).toBe(true);
+    }
+  });
+
+  it('is case-insensitive on the host', () => {
+    setHostname('Accounts.OXY.So');
+    expect(isOxyRpOrigin()).toBe(true);
+  });
+
+  it('returns false on an unrelated origin', () => {
+    setHostname('evil.com');
+    expect(isOxyRpOrigin()).toBe(false);
+  });
+
+  it('returns false on a look-alike suffix without the dot boundary', () => {
+    setHostname('evil-oxy.so');
+    expect(isOxyRpOrigin()).toBe(false);
+  });
+
+  it('returns false when oxy.so is only a subdomain label of an attacker apex', () => {
+    setHostname('oxy.so.evil.com');
+    expect(isOxyRpOrigin()).toBe(false);
+  });
+
+  it('returns false when there is no location (native / SSR)', () => {
+    setHostname(undefined);
+    expect(isOxyRpOrigin()).toBe(false);
+  });
+
+  it('returns false when the hostname is not a string', () => {
+    setHostname(123);
+    expect(isOxyRpOrigin()).toBe(false);
+  });
+
+  it('returns false when the hostname is empty', () => {
+    setHostname('');
+    expect(isOxyRpOrigin()).toBe(false);
+  });
+});

package/src/utils/officialOrigins.ts

@@ -41,7 +41,12 @@ export function isIdpHubOrigin(): boolean {
   }
 }
 
-function isLoopbackOrigin(origin: string): boolean {
+/**
+ * Whether an origin is a loopback / local-dev origin (`localhost`, `127.0.0.1`,
+ * or `[::1]` on any port, http or https). Local dev must never be bounced to a
+ * hosted IdP for cross-origin session restore.
+ */
+export function isLoopbackOrigin(origin: string): boolean {
   try {
     const parsed = new URL(origin);
     if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {