@oxyhq/core 12.10.3 → 12.10.5

package/dist/types/index.d.ts

@@ -93,7 +93,7 @@ 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';
+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, OXY_OAUTH_RETURN_PATH_STORAGE_KEY, normalizeOAuthRedirectUri, persistOAuthHandshake, readOAuthHandshake, clearOAuthHandshake, persistOAuthReturnPath, consumeOAuthReturnPath, } from './utils/oauthPkce';
 export type { PkcePair, BuildOAuthAuthorizeUrlParams } from './utils/oauthPkce';
 export { buildIdpHubOrigin, buildHubSyncUrl, isIdpHubOrigin, isLoopbackOrigin, isOfficialWebOrigin, isAllowedDeviceJoinOrigin, normalizeOfficialReturnOrigin, parseHubSyncReturnUrl, } from './utils/officialOrigins';
 export { syncHubAfterSignIn, redeemHubTicketOnHub, } from './session/hubSync';

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

@@ -85,11 +85,43 @@ export declare const OXY_OAUTH_CODE_VERIFIER_STORAGE_KEY = "oxy_oauth_code_verif
 export declare const OXY_SILENT_OAUTH_ATTEMPTED_KEY = "oxy.silent_oauth_attempted";
 /** `sessionStorage` key — blocks further cross-origin auto-restore in this tab. */
 export declare const OXY_CROSS_ORIGIN_RESTORE_ATTEMPTED_KEY = "oxy.cross_origin_restore_attempted";
+/**
+ * `sessionStorage` key for the in-app path to return to after an authorize
+ * round trip. See {@link persistOAuthReturnPath}.
+ */
+export declare const OXY_OAUTH_RETURN_PATH_STORAGE_KEY = "oxy.oauth_return_path";
 /**
  * Normalize a redirect URI to its origin. Official Oxy apps register apex
  * origins (`https://inbox.oxy.so`) — never path-qualified URLs.
+ *
+ * This is why the path cannot ride along in `redirect_uri`, and why
+ * {@link persistOAuthReturnPath} exists: the authorize round trip always lands
+ * back on the bare origin, so the page the user was on has to be carried
+ * out-of-band and restored on return.
  */
 export declare function normalizeOAuthRedirectUri(input: string): string;
+/**
+ * Remember the page the user was on before a full-page authorize redirect.
+ *
+ * Silent cross-origin restore navigates the whole tab to the IdP and back, and
+ * `redirect_uri` must be a registered apex origin, so the browser returns to
+ * `/` no matter which page the visit started on. Without this, every deep link
+ * — a shared URL, a search result, an ad landing page — silently became the
+ * home page for signed-out visitors on their first navigation in a tab.
+ *
+ * Stored next to the PKCE handshake it belongs to, and cleared by
+ * {@link clearOAuthHandshake} so a stale entry can never be applied to an
+ * unrelated later navigation.
+ */
+export declare function persistOAuthReturnPath(path: string): void;
+/**
+ * Read and remove the persisted return path, or `null` when there is none or
+ * it failed validation.
+ *
+ * Single-use by design: it is consumed on the first return so a leftover value
+ * cannot redirect a later navigation in the same tab.
+ */
+export declare function consumeOAuthReturnPath(): string | null;
 /** Persist the OAuth handshake for a full-page redirect return (web only). */
 export declare function persistOAuthHandshake(state: string, codeVerifier: string): boolean;
 /** Read the persisted OAuth handshake, or `null` when absent. */

package/package.json

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

package/src/i18n/locales/en-US.json

@@ -1552,6 +1552,7 @@
       "fileEmpty": "File \"{{name}}\" is empty",
       "fileTooLarge": "\"{{name}}\" is too large. Maximum file size is {{maxSize}}",
       "noValidFiles": "No valid files to upload",
+      "imagesOnlyRequired": "Only image files can be selected",
       "waitForSelection": "Please wait for the current file selection to complete",
       "noFilesSelected": "No files were selected",
       "loadSomeFailed": "Failed to load some files:\n{{errors}}",
@@ -1761,7 +1762,9 @@
       "toasts": {
         "success": "Account created",
         "failed": "Failed to create account"
-      }
+      },
+      "typeSection": "Account type",
+      "detailsSection": "Details"
     },
     "manage": {
       "create": {
@@ -2071,4 +2074,4 @@
     "deny": "Cancel",
     "disclaimer": "By continuing, {{app}} will be able to sign in with your Oxy account. You can manage connected apps anytime in your Oxy account settings."
   }
-}
+}

package/src/i18n/locales/es-ES.json

@@ -1552,6 +1552,7 @@
       "fileEmpty": "El archivo \"{{name}}\" está vacío",
       "fileTooLarge": "\"{{name}}\" es demasiado grande. El tamaño máximo es {{maxSize}}",
       "noValidFiles": "No hay archivos válidos para subir",
+      "imagesOnlyRequired": "Solo se pueden seleccionar archivos de imagen",
       "waitForSelection": "Espera a que se complete la selección actual",
       "noFilesSelected": "No se seleccionaron archivos",
       "loadSomeFailed": "Error al cargar algunos archivos:\n{{errors}}",
@@ -1761,7 +1762,9 @@
       "toasts": {
         "success": "Cuenta creada",
         "failed": "No se pudo crear la cuenta"
-      }
+      },
+      "typeSection": "Tipo de cuenta",
+      "detailsSection": "Detalles"
     },
     "manage": {
       "create": {
@@ -2071,4 +2074,4 @@
     "deny": "Cancelar",
     "disclaimer": "Al continuar, {{app}} podrá iniciar sesión con tu cuenta de Oxy. Puedes gestionar las apps conectadas cuando quieras en los ajustes de tu cuenta de Oxy."
   }
-}
+}

package/src/index.ts

@@ -583,10 +583,13 @@ export {
     OXY_OAUTH_CODE_VERIFIER_STORAGE_KEY,
     OXY_SILENT_OAUTH_ATTEMPTED_KEY,
     OXY_CROSS_ORIGIN_RESTORE_ATTEMPTED_KEY,
+    OXY_OAUTH_RETURN_PATH_STORAGE_KEY,
     normalizeOAuthRedirectUri,
     persistOAuthHandshake,
     readOAuthHandshake,
     clearOAuthHandshake,
+    persistOAuthReturnPath,
+    consumeOAuthReturnPath,
 } from './utils/oauthPkce';
 export type { PkcePair, BuildOAuthAuthorizeUrlParams } from './utils/oauthPkce';
 

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

@@ -6,6 +6,10 @@ import {
   generateOAuthState,
   generatePkcePair,
   OXY_AUTHORIZE_URL,
+  OXY_OAUTH_RETURN_PATH_STORAGE_KEY,
+  clearOAuthHandshake,
+  consumeOAuthReturnPath,
+  persistOAuthReturnPath,
 } from '../oauthPkce';
 
 /** RFC 7636 unreserved subset produced by base64url (no `+`, `/`, `=`). */
@@ -152,3 +156,66 @@ describe('buildOAuthAuthorizeUrl', () => {
     expect(new URL(url).searchParams.get('redirect_uri')).toBe(redirectUri);
   });
 });
+
+describe('OAuth return path', () => {
+  /** Minimal sessionStorage stand-in — jsdom is not assumed by this suite. */
+  function installSessionStorage(): Map<string, string> {
+    const map = new Map<string, string>();
+    (globalThis as { sessionStorage?: Storage }).sessionStorage = {
+      getItem: (k: string) => (map.has(k) ? (map.get(k) as string) : null),
+      setItem: (k: string, v: string) => void map.set(k, v),
+      removeItem: (k: string) => void map.delete(k),
+      clear: () => map.clear(),
+      key: (i: number) => [...map.keys()][i] ?? null,
+      get length() {
+        return map.size;
+      },
+    } as unknown as Storage;
+    return map;
+  }
+
+  afterEach(() => {
+    delete (globalThis as { sessionStorage?: Storage }).sessionStorage;
+  });
+
+  it('round-trips a deep path through persist/consume', () => {
+    installSessionStorage();
+    persistOAuthReturnPath('/company/team?tab=eng#lead');
+    expect(consumeOAuthReturnPath()).toBe('/company/team?tab=eng#lead');
+  });
+
+  it('is single-use, so a stale value cannot redirect a later navigation', () => {
+    installSessionStorage();
+    persistOAuthReturnPath('/pricing');
+    expect(consumeOAuthReturnPath()).toBe('/pricing');
+    expect(consumeOAuthReturnPath()).toBeNull();
+  });
+
+  it('rejects protocol-relative and absolute values (open-redirect guard)', () => {
+    const store = installSessionStorage();
+    for (const hostile of ['//evil.com', '/\\evil.com', 'https://evil.com/x', 'evil.com']) {
+      persistOAuthReturnPath(hostile);
+      expect(store.get(OXY_OAUTH_RETURN_PATH_STORAGE_KEY)).toBeUndefined();
+    }
+  });
+
+  it('rejects a hostile value written directly into storage', () => {
+    const store = installSessionStorage();
+    store.set(OXY_OAUTH_RETURN_PATH_STORAGE_KEY, '//evil.com');
+    expect(consumeOAuthReturnPath()).toBeNull();
+    // Consumed even when rejected, so it cannot be retried.
+    expect(store.get(OXY_OAUTH_RETURN_PATH_STORAGE_KEY)).toBeUndefined();
+  });
+
+  it('is cleared with the handshake it belongs to', () => {
+    const store = installSessionStorage();
+    persistOAuthReturnPath('/newsroom');
+    clearOAuthHandshake();
+    expect(store.get(OXY_OAUTH_RETURN_PATH_STORAGE_KEY)).toBeUndefined();
+  });
+
+  it('no-ops without sessionStorage instead of throwing', () => {
+    expect(() => persistOAuthReturnPath('/pricing')).not.toThrow();
+    expect(consumeOAuthReturnPath()).toBeNull();
+  });
+});

package/src/utils/oauthPkce.ts

@@ -208,9 +208,20 @@ export const OXY_SILENT_OAUTH_ATTEMPTED_KEY = 'oxy.silent_oauth_attempted';
 /** `sessionStorage` key — blocks further cross-origin auto-restore in this tab. */
 export const OXY_CROSS_ORIGIN_RESTORE_ATTEMPTED_KEY = 'oxy.cross_origin_restore_attempted';
 
+/**
+ * `sessionStorage` key for the in-app path to return to after an authorize
+ * round trip. See {@link persistOAuthReturnPath}.
+ */
+export const OXY_OAUTH_RETURN_PATH_STORAGE_KEY = 'oxy.oauth_return_path';
+
 /**
  * Normalize a redirect URI to its origin. Official Oxy apps register apex
  * origins (`https://inbox.oxy.so`) — never path-qualified URLs.
+ *
+ * This is why the path cannot ride along in `redirect_uri`, and why
+ * {@link persistOAuthReturnPath} exists: the authorize round trip always lands
+ * back on the bare origin, so the page the user was on has to be carried
+ * out-of-band and restored on return.
  */
 export function normalizeOAuthRedirectUri(input: string): string {
   try {
@@ -220,6 +231,69 @@ export function normalizeOAuthRedirectUri(input: string): string {
   }
 }
 
+/**
+ * Is this a safe same-origin path to restore into the address bar?
+ *
+ * Only site-relative paths are accepted. `//evil.com` and `/\evil.com` are
+ * rejected because browsers resolve both as protocol-relative *absolute* URLs —
+ * without this check, anything able to write one key of `sessionStorage` could
+ * turn the post-authorize restore into an open redirect.
+ */
+function isSafeReturnPath(value: string): boolean {
+  if (!value.startsWith('/')) return false;
+  if (value.startsWith('//') || value.startsWith('/\\')) return false;
+  if (value.length > 2048) return false;
+  return true;
+}
+
+/**
+ * Remember the page the user was on before a full-page authorize redirect.
+ *
+ * Silent cross-origin restore navigates the whole tab to the IdP and back, and
+ * `redirect_uri` must be a registered apex origin, so the browser returns to
+ * `/` no matter which page the visit started on. Without this, every deep link
+ * — a shared URL, a search result, an ad landing page — silently became the
+ * home page for signed-out visitors on their first navigation in a tab.
+ *
+ * Stored next to the PKCE handshake it belongs to, and cleared by
+ * {@link clearOAuthHandshake} so a stale entry can never be applied to an
+ * unrelated later navigation.
+ */
+export function persistOAuthReturnPath(path: string): void {
+  const store = (globalThis as { sessionStorage?: Storage }).sessionStorage;
+  if (!store || !isSafeReturnPath(path)) return;
+  try {
+    store.setItem(OXY_OAUTH_RETURN_PATH_STORAGE_KEY, path);
+  } catch (error) {
+    // Non-fatal: the round trip still completes, it just lands on the origin.
+    logger.warn(
+      'Could not persist OAuth return path to sessionStorage',
+      { component: 'oauthPkce' },
+      error,
+    );
+  }
+}
+
+/**
+ * Read and remove the persisted return path, or `null` when there is none or
+ * it failed validation.
+ *
+ * Single-use by design: it is consumed on the first return so a leftover value
+ * cannot redirect a later navigation in the same tab.
+ */
+export function consumeOAuthReturnPath(): string | null {
+  const store = (globalThis as { sessionStorage?: Storage }).sessionStorage;
+  if (!store) return null;
+  try {
+    const value = store.getItem(OXY_OAUTH_RETURN_PATH_STORAGE_KEY);
+    store.removeItem(OXY_OAUTH_RETURN_PATH_STORAGE_KEY);
+    if (!value || !isSafeReturnPath(value)) return null;
+    return value;
+  } catch {
+    return null;
+  }
+}
+
 /** Persist the OAuth handshake for a full-page redirect return (web only). */
 export function persistOAuthHandshake(state: string, codeVerifier: string): boolean {
   const store = (globalThis as { sessionStorage?: Storage }).sessionStorage;
@@ -254,6 +328,9 @@ export function clearOAuthHandshake(): void {
   try {
     store?.removeItem(OXY_OAUTH_STATE_STORAGE_KEY);
     store?.removeItem(OXY_OAUTH_CODE_VERIFIER_STORAGE_KEY);
+    // The return path belongs to this handshake. Leaving it behind would let a
+    // later, unrelated navigation in the same tab be redirected by it.
+    store?.removeItem(OXY_OAUTH_RETURN_PATH_STORAGE_KEY);
   } catch {
     // Best-effort cleanup only.
   }