@oxyhq/core 11.0.0 → 11.0.1

package/dist/types/index.d.ts

@@ -82,6 +82,7 @@ export { buildAccountsArray, createQuickAccount, getAccountDisplayName, getAccou
 export type { QuickAccount, DisplayNameUserShape } from './utils/accountUtils';
 export { registrableApex } from './utils/registrableApex';
 export { CENTRAL_IDP_APEX } from './utils/authWebUrl';
+export { isOxyRpOrigin } from './utils/webauthnOrigin';
 export { runColdBoot } from './utils/coldBoot';
 export type { ColdBootStep, ColdBootStepResult, ColdBootSession, ColdBootSkip, ColdBootOutcome, RunColdBootOptions, } from './utils/coldBoot';
 export { buildOAuthAuthorizeUrl, computeCodeChallenge, generateOAuthState, generatePkcePair, DEFAULT_OAUTH_SCOPE, OXY_AUTHORIZE_URL, OXY_OAUTH_STATE_STORAGE_KEY, OXY_OAUTH_CODE_VERIFIER_STORAGE_KEY, OXY_SILENT_OAUTH_ATTEMPTED_KEY, OXY_CROSS_ORIGIN_RESTORE_ATTEMPTED_KEY, normalizeOAuthRedirectUri, persistOAuthHandshake, readOAuthHandshake, clearOAuthHandshake, } from './utils/oauthPkce';

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

@@ -494,6 +494,64 @@ export declare function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(B
             deviceName?: string;
             deviceId?: string;
         }): Promise<LoginSessionResult>;
+        /**
+         * Begin a WebAuthn / passkey REGISTRATION ceremony. Requests the
+         * `PublicKeyCredentialCreationOptions` the browser's `navigator.credentials
+         * .create()` (or `@simplewebauthn/browser`'s `startRegistration`) needs.
+         *
+         * With a bearer token planted this links a passkey to the signed-in account
+         * (`username` ignored); without one it is a prospective signup and `username`
+         * is the desired handle. The returned options are OPAQUE — Oxy does not own
+         * their shape (the browser / `@simplewebauthn` does), so they pass through
+         * as `unknown` for the caller to hand straight to the ceremony.
+         */
+        webauthnRegisterOptions(username?: string): Promise<unknown>;
+        /**
+         * Finish a WebAuthn / passkey REGISTRATION ceremony. Forwards the opaque
+         * browser `RegistrationResponseJSON` (`response`) alongside the Oxy envelope
+         * (desired `username` for signup + the device-session naming fields).
+         *
+         * Two server branches, disambiguated by the response shape:
+         *  - **Signup** (no bearer): the account is created and a session minted —
+         *    the response carries `sessionId`, is the SAME {@link LoginResult}
+         *    contract as `POST /auth/verify`, and its access token is planted here.
+         *  - **Link** (bearer present): the passkey is attached to the signed-in
+         *    account and the server returns `{ success, message }` with no session,
+         *    which is returned verbatim (no token planting).
+         */
+        webauthnRegisterVerify(response: unknown, envelope?: {
+            username?: string;
+            deviceName?: string;
+            deviceFingerprint?: string;
+            deviceId?: string;
+        }): Promise<{
+            success: true;
+            message: string;
+        } | LoginResult>;
+        /**
+         * Begin a WebAuthn / passkey AUTHENTICATION ceremony. Requests the
+         * `PublicKeyCredentialRequestOptions` the browser's `navigator.credentials
+         * .get()` (or `@simplewebauthn/browser`'s `startAuthentication`) needs.
+         *
+         * When `username` is present the server scopes `allowCredentials` to that
+         * user's passkeys (username-first); when omitted it returns an empty
+         * allow-list for the usernameless / discoverable-credential flow. The
+         * returned options are OPAQUE and pass through as `unknown`.
+         */
+        webauthnLoginOptions(username?: string): Promise<unknown>;
+        /**
+         * Finish a WebAuthn / passkey AUTHENTICATION ceremony. Forwards the opaque
+         * browser `AuthenticationResponseJSON` (`response`) alongside the
+         * device-session envelope. Resolves to the SAME {@link LoginResult} contract
+         * as `POST /auth/verify`; on the session arm the access token is planted
+         * immediately (mirroring {@link passwordSignIn}), and the response's
+         * `deviceId` + `deviceSecret` are the zero-cookie restore credential.
+         */
+        webauthnLoginVerify(response: unknown, envelope?: {
+            deviceName?: string;
+            deviceFingerprint?: string;
+            deviceId?: string;
+        }): Promise<LoginResult>;
         /**
          * Exchange an OAuth authorization code (returned to the RP redirect URI
          * after password sign-in at auth.oxy.so) for a device-first session.

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

@@ -0,0 +1,32 @@
+/**
+ * WebAuthn relying-party origin guard (client side).
+ *
+ * The passkey ceremonies (`OxyServices.webauthn*`) are only meaningful when the
+ * page is served from a first-party Oxy web origin: a credential minted with
+ * `WEBAUTHN_RP_ID=oxy.so` can only be created/asserted from `oxy.so`, one of its
+ * subdomains, or a loopback dev server. This is the browser-side mirror of the
+ * server's `isOxyApexOrigin` (`packages/api/src/utils/origin.ts`), which forms
+ * the server's `expectedOrigin` allow-set — consumers use it to decide whether to
+ * even offer the passkey UI on the current page.
+ *
+ * It reads `globalThis.location` directly (no argument) because that is the only
+ * origin the browser will let a WebAuthn ceremony run against. On native / SSR /
+ * any environment without a DOM `location`, it returns `false` (there is no
+ * relying-party origin, so passkeys are not applicable).
+ */
+/**
+ * True iff the current page's host is a first-party Oxy relying-party origin:
+ * `oxy.so`, any `*.oxy.so` subdomain, or a loopback dev host
+ * (`localhost` / `127.0.0.1` / `[::1]`).
+ *
+ * Fails closed: no `location` (native/SSR), a non-string/empty hostname, or a
+ * host that merely ends in the literal `oxy.so` without the dot boundary
+ * (`evil-oxy.so`, `oxy.so.evil.com`) all return `false`.
+ *
+ * @example
+ *   isOxyRpOrigin() // true  on https://accounts.oxy.so
+ *   isOxyRpOrigin() // true  on http://localhost:8081
+ *   isOxyRpOrigin() // false on https://evil.com
+ *   isOxyRpOrigin() // false in a React Native / SSR context (no location)
+ */
+export declare function isOxyRpOrigin(): boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/core",
-  "version": "11.0.0",
+  "version": "11.0.1",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -109,7 +109,7 @@
     }
   },
   "dependencies": {
-    "@oxyhq/contracts": "^0.14.1",
+    "@oxyhq/contracts": "^0.14.2",
     "@oxyhq/protocol": "^0.1.5",
     "bip39": "^3.1.0",
     "buffer": "^6.0.3",

package/src/index.ts

@@ -517,6 +517,11 @@ export type { QuickAccount, DisplayNameUserShape } from './utils/accountUtils';
 export { registrableApex } from './utils/registrableApex';
 export { CENTRAL_IDP_APEX } from './utils/authWebUrl';
 
+// WebAuthn relying-party origin guard (client side). Mirrors the server's
+// `isOxyApexOrigin` so consumers can decide whether to offer passkey UI on the
+// current page (first-party Oxy origin / loopback only).
+export { isOxyRpOrigin } from './utils/webauthnOrigin';
+
 export { runColdBoot } from './utils/coldBoot';
 export type {
     ColdBootStep,

package/src/mixins/OxyServices.auth.ts

@@ -1196,6 +1196,139 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
       }
     }
 
+    /**
+     * Begin a WebAuthn / passkey REGISTRATION ceremony. Requests the
+     * `PublicKeyCredentialCreationOptions` the browser's `navigator.credentials
+     * .create()` (or `@simplewebauthn/browser`'s `startRegistration`) needs.
+     *
+     * With a bearer token planted this links a passkey to the signed-in account
+     * (`username` ignored); without one it is a prospective signup and `username`
+     * is the desired handle. The returned options are OPAQUE — Oxy does not own
+     * their shape (the browser / `@simplewebauthn` does), so they pass through
+     * as `unknown` for the caller to hand straight to the ceremony.
+     */
+    async webauthnRegisterOptions(username?: string): Promise<unknown> {
+      try {
+        return await this.makeRequest<unknown>(
+          'POST',
+          '/auth/webauthn/register/options',
+          { ...(username !== undefined ? { username } : {}) },
+          { cache: false },
+        );
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Finish a WebAuthn / passkey REGISTRATION ceremony. Forwards the opaque
+     * browser `RegistrationResponseJSON` (`response`) alongside the Oxy envelope
+     * (desired `username` for signup + the device-session naming fields).
+     *
+     * Two server branches, disambiguated by the response shape:
+     *  - **Signup** (no bearer): the account is created and a session minted —
+     *    the response carries `sessionId`, is the SAME {@link LoginResult}
+     *    contract as `POST /auth/verify`, and its access token is planted here.
+     *  - **Link** (bearer present): the passkey is attached to the signed-in
+     *    account and the server returns `{ success, message }` with no session,
+     *    which is returned verbatim (no token planting).
+     */
+    async webauthnRegisterVerify(
+      response: unknown,
+      envelope: {
+        username?: string;
+        deviceName?: string;
+        deviceFingerprint?: string;
+        deviceId?: string;
+      } = {},
+    ): Promise<{ success: true; message: string } | LoginResult> {
+      try {
+        const res = await this.makeRequest<unknown>(
+          'POST',
+          '/auth/webauthn/register/verify',
+          { response, ...envelope },
+          { cache: false },
+        );
+        if (res && typeof res === 'object') {
+          const record = res as Record<string, unknown>;
+          // Signup branch: mints a session (LoginSessionResult, carries
+          // `sessionId`). Parse against the login contract and plant the token.
+          if ('sessionId' in record) {
+            const parsed = safeParseContract(loginResultSchema, record);
+            if (!parsed) {
+              throw new Error('auth/webauthn/register/verify returned an unexpected response shape');
+            }
+            if (!('twoFactorRequired' in parsed) && parsed.accessToken) {
+              this.setTokens(parsed.accessToken);
+            }
+            return parsed;
+          }
+          // Link branch: passkey attached to the signed-in account, no session.
+          if (record.success === true && typeof record.message === 'string') {
+            return { success: true, message: record.message };
+          }
+        }
+        throw new Error('auth/webauthn/register/verify returned an unexpected response shape');
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Begin a WebAuthn / passkey AUTHENTICATION ceremony. Requests the
+     * `PublicKeyCredentialRequestOptions` the browser's `navigator.credentials
+     * .get()` (or `@simplewebauthn/browser`'s `startAuthentication`) needs.
+     *
+     * When `username` is present the server scopes `allowCredentials` to that
+     * user's passkeys (username-first); when omitted it returns an empty
+     * allow-list for the usernameless / discoverable-credential flow. The
+     * returned options are OPAQUE and pass through as `unknown`.
+     */
+    async webauthnLoginOptions(username?: string): Promise<unknown> {
+      try {
+        return await this.makeRequest<unknown>(
+          'POST',
+          '/auth/webauthn/login/options',
+          { ...(username !== undefined ? { username } : {}) },
+          { cache: false },
+        );
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Finish a WebAuthn / passkey AUTHENTICATION ceremony. Forwards the opaque
+     * browser `AuthenticationResponseJSON` (`response`) alongside the
+     * device-session envelope. Resolves to the SAME {@link LoginResult} contract
+     * as `POST /auth/verify`; on the session arm the access token is planted
+     * immediately (mirroring {@link passwordSignIn}), and the response's
+     * `deviceId` + `deviceSecret` are the zero-cookie restore credential.
+     */
+    async webauthnLoginVerify(
+      response: unknown,
+      envelope: { deviceName?: string; deviceFingerprint?: string; deviceId?: string } = {},
+    ): Promise<LoginResult> {
+      try {
+        const res = await this.makeRequest<unknown>(
+          'POST',
+          '/auth/webauthn/login/verify',
+          { response, ...envelope },
+          { cache: false },
+        );
+        const parsed = safeParseContract(loginResultSchema, res);
+        if (!parsed) {
+          throw new Error('auth/webauthn/login/verify returned an unexpected response shape');
+        }
+        if (!('twoFactorRequired' in parsed) && parsed.accessToken) {
+          this.setTokens(parsed.accessToken);
+        }
+        return parsed;
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
     /**
      * Exchange an OAuth authorization code (returned to the RP redirect URI
      * after password sign-in at auth.oxy.so) for a device-first session.

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, like `passwordSignIn.test.ts`) 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/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/webauthnOrigin.ts

@@ -0,0 +1,52 @@
+/**
+ * WebAuthn relying-party origin guard (client side).
+ *
+ * The passkey ceremonies (`OxyServices.webauthn*`) are only meaningful when the
+ * page is served from a first-party Oxy web origin: a credential minted with
+ * `WEBAUTHN_RP_ID=oxy.so` can only be created/asserted from `oxy.so`, one of its
+ * subdomains, or a loopback dev server. This is the browser-side mirror of the
+ * server's `isOxyApexOrigin` (`packages/api/src/utils/origin.ts`), which forms
+ * the server's `expectedOrigin` allow-set — consumers use it to decide whether to
+ * even offer the passkey UI on the current page.
+ *
+ * It reads `globalThis.location` directly (no argument) because that is the only
+ * origin the browser will let a WebAuthn ceremony run against. On native / SSR /
+ * any environment without a DOM `location`, it returns `false` (there is no
+ * relying-party origin, so passkeys are not applicable).
+ */
+
+/**
+ * True iff the current page's host is a first-party Oxy relying-party origin:
+ * `oxy.so`, any `*.oxy.so` subdomain, or a loopback dev host
+ * (`localhost` / `127.0.0.1` / `[::1]`).
+ *
+ * Fails closed: no `location` (native/SSR), a non-string/empty hostname, or a
+ * host that merely ends in the literal `oxy.so` without the dot boundary
+ * (`evil-oxy.so`, `oxy.so.evil.com`) all return `false`.
+ *
+ * @example
+ *   isOxyRpOrigin() // true  on https://accounts.oxy.so
+ *   isOxyRpOrigin() // true  on http://localhost:8081
+ *   isOxyRpOrigin() // false on https://evil.com
+ *   isOxyRpOrigin() // false in a React Native / SSR context (no location)
+ */
+export function isOxyRpOrigin(): boolean {
+  // `globalThis.location` is typed `Location` by the DOM lib, but is genuinely
+  // `undefined` on native/SSR — widen to a nullable local so the guard is a real
+  // runtime check, not a type-level no-op.
+  const location: Location | undefined = globalThis.location;
+  if (!location || typeof location.hostname !== 'string') {
+    return false;
+  }
+
+  const hostname = location.hostname.toLowerCase();
+  if (hostname.length === 0) {
+    return false;
+  }
+
+  if (hostname === 'oxy.so' || hostname.endsWith('.oxy.so')) {
+    return true;
+  }
+
+  return hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '[::1]';
+}