@oxyhq/core 9.1.0 → 9.2.1

package/src/mixins/OxyServices.auth.ts

@@ -664,6 +664,7 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
       deviceId: string;
       expiresAt: string;
       user: User;
+      deviceSecret?: string;
     }> {
       try {
         const res = await this.makeRequest<{
@@ -672,6 +673,7 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
           deviceId: string;
           expiresAt: string;
           user: User;
+          deviceSecret?: string;
         }>(
           'POST',
           '/auth/session/claim',
@@ -1136,7 +1138,7 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
     async passwordSignIn(
       identifier: string,
       password: string,
-      options: { deviceName?: string; deviceFingerprint?: string } = {},
+      options: { deviceName?: string; deviceFingerprint?: string; deviceId?: string } = {},
     ): Promise<LoginResult> {
       try {
         const res = await this.makeRequest<unknown>('POST', '/auth/login', {
@@ -1144,6 +1146,7 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
           password,
           deviceName: options.deviceName,
           deviceFingerprint: options.deviceFingerprint,
+          ...(options.deviceId ? { deviceId: options.deviceId } : {}),
         }, { cache: false });
         const parsed = safeParseContract(loginResultSchema, res);
         if (!parsed) {
@@ -1170,6 +1173,7 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
       token?: string;
       backupCode?: string;
       deviceName?: string;
+      deviceId?: string;
     }): Promise<LoginSessionResult> {
       try {
         const res = await this.makeRequest<unknown>('POST', '/security/2fa/verify-login', {
@@ -1177,6 +1181,7 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
           token: params.token,
           backupCode: params.backupCode,
           deviceName: params.deviceName,
+          ...(params.deviceId ? { deviceId: params.deviceId } : {}),
         }, { cache: false });
         const parsed = safeParseContract(loginResultSchema, res);
         if (!parsed || 'twoFactorRequired' in parsed) {
@@ -1190,5 +1195,71 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
         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.
+     * Public first-party clients use PKCE (`codeVerifier`); the access token is
+     * planted immediately on success.
+     */
+    async exchangeOAuthCode(params: {
+      code: string;
+      clientId: string;
+      redirectUri: string;
+      codeVerifier: string;
+    }): Promise<LoginSessionResult> {
+      try {
+        const res = await this.makeRequest<unknown>('POST', '/auth/oauth/token', {
+          code: params.code,
+          clientId: params.clientId,
+          redirectUri: params.redirectUri,
+          codeVerifier: params.codeVerifier,
+        }, { cache: false });
+        const payload =
+          (res as { data?: Record<string, unknown> }).data ??
+          (res as Record<string, unknown>);
+        if (!payload || typeof payload !== 'object') {
+          throw new Error('auth/oauth/token returned an unexpected response shape');
+        }
+        const record = payload as Record<string, unknown>;
+        const accessToken = (record.access_token ?? record.accessToken) as string | undefined;
+        const sessionId = (record.session_id ?? record.sessionId) as string | undefined;
+        const deviceId = (record.deviceId ?? record.device_id) as string | undefined;
+        const deviceSecret = (record.deviceSecret ?? record.device_secret) as string | undefined;
+        const userRaw = record.user;
+        if (!sessionId || !deviceId || !userRaw || typeof userRaw !== 'object') {
+          throw new Error('auth/oauth/token returned an incomplete session payload');
+        }
+        const userObj = userRaw as Record<string, unknown>;
+        const userId = userObj.id as string | undefined;
+        if (!userId) {
+          throw new Error('auth/oauth/token returned a session without user.id');
+        }
+        const expiresInSec =
+          typeof record.expires_in === 'number'
+            ? record.expires_in
+            : typeof record.expiresIn === 'number'
+              ? record.expiresIn
+              : 15 * 60;
+        const expiresAt = new Date(Date.now() + expiresInSec * 1000).toISOString();
+        if (accessToken) {
+          this.setTokens(accessToken);
+        }
+        return {
+          sessionId,
+          deviceId,
+          expiresAt,
+          accessToken,
+          deviceSecret,
+          user: {
+            id: userId,
+            username: typeof userObj.username === 'string' ? userObj.username : undefined,
+            avatar: typeof userObj.avatar === 'string' ? userObj.avatar : undefined,
+          },
+        };
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
   };
 }

package/src/mixins/OxyServices.deviceBoot.ts

@@ -2,7 +2,7 @@
  * Device-first token mint mixin.
  *
  * The client half of the zero-cookie device transport: the single network call
- * the cold boot (`coldBootV2`) and the unified re-mint handler (`refresh.ts`)
+ * the cold boot (`sessionColdBoot`) and the unified re-mint handler (`refresh.ts`)
  * make to turn a first-party `deviceId` + `deviceSecret` into a fresh access
  * token. The response is validated against the `@oxyhq/contracts`
  * `deviceTokenMintResponseSchema`, so producer (oxy-api) and consumer cannot
@@ -15,8 +15,12 @@
  */
 import {
   deviceTokenMintResponseSchema,
+  deviceHubTicketIssueResponseSchema,
+  deviceHubTicketRedeemResponseSchema,
   safeParseContract,
   type DeviceTokenMintResponse,
+  type DeviceHubTicketIssueResponse,
+  type DeviceHubTicketRedeemResponse,
 } from '@oxyhq/contracts';
 import type { OxyServicesBase } from '../OxyServices.base';
 
@@ -57,5 +61,46 @@ export function OxyServicesDeviceBootMixin<T extends typeof OxyServicesBase>(Bas
         throw this.handleError(error);
       }
     }
+
+    /** Mint a one-time hub sync ticket (bearer required). */
+    async issueHubTicket(returnOrigin: string): Promise<DeviceHubTicketIssueResponse> {
+      try {
+        const res = await this.makeRequest<unknown>(
+          'POST',
+          '/session/device/hub-ticket',
+          { returnOrigin },
+          { cache: false },
+        );
+        const parsed = safeParseContract(deviceHubTicketIssueResponseSchema, res);
+        if (!parsed) {
+          throw new Error('session/device/hub-ticket returned an unexpected response shape');
+        }
+        return parsed;
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /** Redeem a hub sync ticket for a fresh device secret (public). */
+    async redeemHubTicket(
+      ticket: string,
+      returnOrigin: string,
+    ): Promise<DeviceHubTicketRedeemResponse> {
+      try {
+        const res = await this.makeRequest<unknown>(
+          'POST',
+          '/session/device/redeem-ticket',
+          { ticket, returnOrigin },
+          { cache: false, skipAuth: true },
+        );
+        const parsed = safeParseContract(deviceHubTicketRedeemResponseSchema, res);
+        if (!parsed) {
+          throw new Error('session/device/redeem-ticket returned an unexpected response shape');
+        }
+        return parsed;
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
   };
 }

package/src/models/interfaces.ts

@@ -1,4 +1,4 @@
-import type { UserNameResponse } from '@oxyhq/contracts';
+import type { OrganizationCategory, UserNameResponse } from '@oxyhq/contracts';
 
 export interface OxyConfig {
   baseURL: string;
@@ -142,6 +142,8 @@ export interface User {
   // Managed account fields
   isManagedAccount?: boolean;
   managedBy?: string;
+  /** Real-estate taxonomy when this user is a `kind: 'organization'` account. */
+  organizationCategory?: OrganizationCategory;
   // User-controlled notification preferences. All channels default to on; users
   // opt out per-channel. Updated via `PUT /users/me`.
   notificationPreferences?: NotificationPreferences;

package/src/models/session.ts

@@ -35,4 +35,10 @@ export interface SessionLoginResponse {
   user: MinimalUserData;
   /** JWT access token for API authentication */
   accessToken?: string;
+  /**
+   * Rotating zero-cookie device credential minted on sign-in / claim. Persisted
+   * first-party alongside `deviceId` so cold boot can re-mint via
+   * `POST /session/device/token`.
+   */
+  deviceSecret?: string;
 }

package/src/server/index.ts

@@ -69,3 +69,11 @@ export { verifySecret } from './verifySecret';
 // Pure host handling (no browser deps), so it is safe on the server subpath and
 // lets `@oxyhq/api` derive `auth.<apex>` without duplicating PSL logic.
 export { registrableApex } from '../utils/registrableApex';
+export {
+  buildIdpHubOrigin,
+  buildHubSyncUrl,
+  isIdpHubOrigin,
+  isOfficialWebOrigin,
+  normalizeOfficialReturnOrigin,
+  parseHubSyncReturnUrl,
+} from '../utils/officialOrigins';

package/src/session/SessionClient.ts

@@ -13,10 +13,17 @@ export interface TokenTransport {
   ensureActiveToken(state: DeviceSessionState): Promise<void>;
 }
 
+export interface DeviceCredential {
+  deviceId: string;
+  deviceSecret: string;
+}
+
 export interface SessionClientHost {
   makeRequest<T>(method: 'GET' | 'POST', url: string, data?: unknown, options?: { cache?: boolean }): Promise<T>;
   getBaseURL(): string;
   getAccessToken(): string | null;
+  /** Zero-cookie device credential for socket handshake when no bearer is planted yet. */
+  getDeviceCredential(): DeviceCredential | null;
   onTokensChanged(listener: (token: string | null) => void): () => void;
   setTokens(accessToken: string): void;
   getCurrentAccountId(): string | null;
@@ -123,20 +130,33 @@ export class SessionClient {
       return false;
     }
     this.state = next;
-    this.notify();
-    if (this.options.transport) {
-      void this.options.transport.ensureActiveToken(next).catch((error) => {
+    const transport = this.options.transport;
+    const needsMintBeforeNotify =
+      transport != null && next.accounts.length > 0 && !this.host.getAccessToken();
+
+    const finishApply = (): void => {
+      this.notify();
+      if (next.accounts.length === 0 && this.options.onUnauthenticated) {
+        try {
+          this.options.onUnauthenticated();
+        } catch (error) {
+          logger.error('[SessionClient] onUnauthenticated threw', error);
+        }
+      }
+    };
+
+    if (needsMintBeforeNotify) {
+      void transport.ensureActiveToken(next).then(finishApply).catch((error) => {
         logger.warn('[SessionClient] ensureActiveToken failed', { component: 'SessionClient' }, error);
+        finishApply();
       });
-    }
-    // A device signout-all leaves zero accounts — tell the provider to clear
-    // the persisted store so a reload does not try to restore a dead session.
-    if (next.accounts.length === 0 && this.options.onUnauthenticated) {
-      try {
-        this.options.onUnauthenticated();
-      } catch (error) {
-        logger.error('[SessionClient] onUnauthenticated threw', error);
+    } else {
+      if (transport) {
+        void transport.ensureActiveToken(next).catch((error) => {
+          logger.warn('[SessionClient] ensureActiveToken failed', { component: 'SessionClient' }, error);
+        });
       }
+      finishApply();
     }
     return true;
   }
@@ -222,18 +242,23 @@ export class SessionClient {
     this.started = true;
     this.tokenUnsub = this.host.onTokensChanged((token) => {
       // A rotated/fresh bearer landed — reconnect a dropped socket so its
-      // handshake re-runs with the current token. Sign-out (null token) is
-      // handled by the consumer calling `stop()`.
-      if (!token || !this.socket) return;
-      if (!this.socket.connected) {
+      // handshake re-runs with the current token. Sign-out (null token) keeps
+      // the device-scoped socket when a device credential is available.
+      if (!this.socket) return;
+      if (token) {
+        if (!this.socket.connected) {
+          this.socket.connect();
+        }
+        return;
+      }
+      const cred = this.host.getDeviceCredential();
+      if (cred && !this.socket.connected) {
         this.socket.connect();
       }
     });
     this.openBroadcastChannel();
-    // `bootstrap` (`GET /session/device/state`) is bearer-authenticated. A
-    // signed-out client opens no socket and runs no bootstrap; a bootstrap
-    // failure is non-fatal — the socket still connects so realtime sync
-    // survives a transient state-fetch error.
+    // Device-scoped socket: bearer when authenticated, else deviceId+deviceSecret so
+    // signed-out tabs still receive `session_state` and can mint on change.
     if (this.host.getAccessToken()) {
       try {
         await this.bootstrap();
@@ -275,24 +300,41 @@ export class SessionClient {
       return;
     }
     if (!this.started) return; // stopped while the dynamic import was in flight
-    // Sockets are BEARER-ONLY: the server rejects any handshake without a valid
-    // bearer, so a signed-out client never opens a socket.
-    if (!this.host.getAccessToken()) return;
+
+    const token = this.host.getAccessToken();
+    const deviceCredential = this.host.getDeviceCredential();
+    if (!token && !deviceCredential) return;
 
     const socket = io(this.host.getBaseURL(), {
       transports: ['websocket'],
       autoConnect: true,
-      auth: (cb: (data: { token: string }) => void) => {
-        cb({ token: this.host.getAccessToken() ?? '' });
+      reconnection: true,
+      reconnectionAttempts: Infinity,
+      reconnectionDelay: 1000,
+      reconnectionDelayMax: 10000,
+      auth: (cb: (data: Record<string, string>) => void) => {
+        const bearer = this.host.getAccessToken();
+        if (bearer) {
+          cb({ token: bearer });
+          return;
+        }
+        const cred = this.host.getDeviceCredential();
+        if (cred) {
+          cb({ deviceId: cred.deviceId, deviceSecret: cred.deviceSecret });
+          return;
+        }
+        cb({ token: '' });
       },
     });
     socket.on('session_state', (payload: unknown) => {
       const applied = this.applyState(payload);
       if (!applied) return;
       // A push changed the active account on another device/tab — re-fetch state
-      // to plant the access token for the newly-active account.
+      // to plant the access token for the newly-active account. When this tab is
+      // still signed out, applyState mints via ensureActiveToken first; bootstrap
+      // requires a bearer and must not run until then.
       const active = this.state?.activeAccountId ?? null;
-      if (active && active !== this.host.getCurrentAccountId()) {
+      if (active && active !== this.host.getCurrentAccountId() && this.host.getAccessToken()) {
         void this.bootstrap().catch((error) => {
           logger.warn('[SessionClient] post-push token fetch failed', { component: 'SessionClient' }, error);
         });

package/src/session/__tests__/SessionClient.additive.test.ts

@@ -16,6 +16,7 @@ function makeHost(makeRequest: jest.Mock, currentAccountId: string | null = null
     makeRequest,
     getBaseURL: () => 'http://test.invalid',
     getAccessToken: () => 't',
+    getDeviceCredential: () => null,
     onTokensChanged: () => () => undefined,
     setTokens: jest.fn(),
     getCurrentAccountId: () => currentAccountId,

package/src/session/__tests__/SessionClient.broadcastChannel.test.ts

@@ -55,6 +55,7 @@ function makeHost(over: Partial<SessionClientHost> = {}): SessionClientHost {
     makeRequest: jest.fn().mockResolvedValue(SYNC(1)),
     getBaseURL: () => 'http://test.invalid',
     getAccessToken: () => 'tok',
+    getDeviceCredential: () => null,
     onTokensChanged: () => () => undefined,
     setTokens: jest.fn(),
     getCurrentAccountId: () => 'a1',

package/src/session/__tests__/SessionClient.diagnostics.test.ts

@@ -11,6 +11,7 @@ function makeHost(makeRequest: jest.Mock): SessionClientHost {
     makeRequest,
     getBaseURL: () => 'http://test.invalid',
     getAccessToken: () => 't',
+    getDeviceCredential: () => null,
     onTokensChanged: () => () => undefined,
     setTokens: jest.fn(),
     getCurrentAccountId: () => null,

package/src/session/__tests__/SessionClient.rest.test.ts

@@ -10,6 +10,7 @@ function makeHost(makeRequest: jest.Mock): SessionClientHost {
     makeRequest,
     getBaseURL: () => 'http://test.invalid',
     getAccessToken: () => 't',
+    getDeviceCredential: () => null,
     onTokensChanged: () => () => undefined,
     setTokens: jest.fn(),
     getCurrentAccountId: () => null,

package/src/session/__tests__/SessionClient.socket.test.ts

@@ -30,6 +30,7 @@ function makeHost(over: Partial<SessionClientHost> = {}): SessionClientHost {
     makeRequest: jest.fn().mockResolvedValue(SYNC(1)),
     getBaseURL: () => 'http://test.invalid',
     getAccessToken: () => 'tok',
+    getDeviceCredential: () => null,
     onTokensChanged: () => () => undefined,
     setTokens: jest.fn(),
     getCurrentAccountId: () => 'a1',

package/src/session/__tests__/SessionClient.socketFactory.test.ts

@@ -32,6 +32,7 @@ function makeHost(over: Partial<SessionClientHost> = {}): SessionClientHost {
     makeRequest: jest.fn().mockResolvedValue(SYNC(1)),
     getBaseURL: () => 'http://test.invalid',
     getAccessToken: () => 'tok',
+    getDeviceCredential: () => null,
     onTokensChanged: () => () => undefined,
     setTokens: jest.fn(),
     getCurrentAccountId: () => 'a1',

package/src/session/__tests__/SessionClient.state.test.ts

@@ -6,6 +6,7 @@ function makeHost(): SessionClientHost {
     makeRequest: jest.fn(),
     getBaseURL: () => 'http://test.invalid',
     getAccessToken: () => 't',
+    getDeviceCredential: () => null,
     onTokensChanged: () => () => undefined,
     setTokens: jest.fn(),
     getCurrentAccountId: () => null,

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

@@ -22,6 +22,7 @@ function host(): SessionClientHost {
     makeRequest: jest.fn(),
     getBaseURL: () => 'http://test.invalid',
     getAccessToken: () => 'token',
+    getDeviceCredential: () => null,
     onTokensChanged: () => () => undefined,
     setTokens: jest.fn(),
     getCurrentAccountId: () => null,
@@ -460,6 +461,7 @@ describe('AccountDialogController — sign in with Oxy', () => {
         accessToken: 'access-1',
         sessionId: 'sess-1',
         deviceId: 'device-1',
+        deviceSecret: 'claimed-secret',
         expiresAt: '2030-01-01T00:00:00Z',
         user: user('a1'),
       });
@@ -472,7 +474,13 @@ describe('AccountDialogController — sign in with Oxy', () => {
 
       await jest.advanceTimersByTimeAsync(1000); // second poll → authorized → claim
       expect(oxy.claimSessionByToken).toHaveBeenCalledWith('secret-tok');
-      expect(commitSession).toHaveBeenCalledWith(expect.objectContaining({ sessionId: 'sess-1', accessToken: 'access-1' }));
+      expect(commitSession).toHaveBeenCalledWith(
+        expect.objectContaining({
+          sessionId: 'sess-1',
+          accessToken: 'access-1',
+          deviceSecret: 'claimed-secret',
+        }),
+      );
       expect(onSignedIn).toHaveBeenCalledWith(expect.objectContaining({ id: 'a1' }));
       expect(controller.getSnapshot().view).toBe('accounts');
     } finally {
@@ -533,7 +541,23 @@ describe('AccountDialogController — sign in with Oxy', () => {
 });
 
 describe('AccountDialogController — openPasswordAtOxyAuth', () => {
-  it('builds the IdP sign-in URL with redirect_uri + client_id and invokes openUrl', () => {
+  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();
@@ -544,17 +568,32 @@ describe('AccountDialogController — openPasswordAtOxyAuth', () => {
       openUrl,
     });
 
-    const url = controller.openPasswordAtOxyAuth({ returnUrl: 'https://mention.earth/', state: 'xyz' });
+    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('redirect_uri')).toBe('https://mention.earth');
     expect(parsed.searchParams.get('client_id')).toBe('oxy_dk_test');
-    expect(parsed.searchParams.get('state')).toBe('xyz');
+    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 an idpApex override', () => {
+  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({
@@ -562,7 +601,7 @@ describe('AccountDialogController — openPasswordAtOxyAuth', () => {
       sessionClient: sc,
       idpApex: 'alia.onl',
     });
-    const url = controller.openPasswordAtOxyAuth({ returnUrl: 'https://alia.onl/' });
+    const url = await controller.openPasswordAtOxyAuth({ returnUrl: 'https://alia.onl/' });
     expect(new URL(url).origin).toBe('https://auth.alia.onl');
   });
 });

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

@@ -44,6 +44,13 @@ describe('createSessionClientHost', () => {
     expect(host.getCurrentAccountId()).toBe('u1');
   });
 
+  test('setDeviceCredential reflects on getDeviceCredential', () => {
+    const host = createSessionClientHost(fakeOxy() as never);
+    expect(host.getDeviceCredential()).toBeNull();
+    host.setDeviceCredential({ deviceId: 'd1', deviceSecret: 's1' });
+    expect(host.getDeviceCredential()).toEqual({ deviceId: 'd1', deviceSecret: 's1' });
+  });
+
   test('onTokensChanged forwards to oxyServices and unsubscribes', () => {
     const oxy = fakeOxy();
     const host = createSessionClientHost(oxy as never);

package/src/session/accountDialogController.ts

@@ -31,6 +31,12 @@ import type { SessionLoginResponse, MinimalUserData } from '../models/session';
 import type { User } from '../models/interfaces';
 import { logger } from '../utils/loggerUtils';
 import { CENTRAL_IDP_APEX } from '../utils/authWebUrl';
+import {
+  generateOAuthState,
+  generatePkcePair,
+  normalizeOAuthRedirectUri,
+  persistOAuthHandshake,
+} from '../utils/oauthPkce';
 import { SessionClient } from './SessionClient';
 import {
   projectSwitchableAccounts,
@@ -111,6 +117,12 @@ export interface AccountDialogControllerOptions {
   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 poll interval in ms (default 3000). */
   pollIntervalMs?: number;
   /**
@@ -145,6 +157,7 @@ export class AccountDialogController {
   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;
 
@@ -181,6 +194,7 @@ export class AccountDialogController {
     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.snapshot = this.computeSnapshot();
@@ -548,18 +562,30 @@ export class AccountDialogController {
    * @param params.state - Optional opaque state echoed back on return.
    * @returns The absolute auth.oxy.so sign-in URL.
    */
-  openPasswordAtOxyAuth(params: { returnUrl?: string; state?: string } = {}): string {
+  async openPasswordAtOxyAuth(
+    params: { returnUrl?: string; state?: string; redirectUri?: string } = {},
+  ): Promise<string> {
     const base = `https://auth.${this.idpApex}`;
     const url = new URL('/login', base);
-    const returnUrl = params.returnUrl ?? currentLocationHref();
-    if (returnUrl) {
-      url.searchParams.set('redirect_uri', returnUrl);
+    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);
     }
-    if (params.state) {
-      url.searchParams.set('state', params.state);
+    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);
@@ -612,7 +638,14 @@ export class AccountDialogController {
 
   private async claimAndComplete(sessionId: string, sessionToken: string): Promise<void> {
     this.setSignIn({ ...this.signIn, phase: 'authorized' });
-    let claimed: { accessToken: string; sessionId: string; deviceId: string; expiresAt: string; user: User };
+    let claimed: {
+      accessToken: string;
+      sessionId: string;
+      deviceId: string;
+      expiresAt: string;
+      user: User;
+      deviceSecret?: string;
+    };
     try {
       claimed = await this.oxyServices.claimSessionByToken(sessionToken);
     } catch (error) {
@@ -640,6 +673,7 @@ export class AccountDialogController {
           expiresAt: claimed.expiresAt ?? '',
           user: minimalUser,
           accessToken: claimed.accessToken,
+          ...(claimed.deviceSecret ? { deviceSecret: claimed.deviceSecret } : {}),
         },
         minimalUser,
       );
@@ -748,8 +782,8 @@ export function createAccountDialogController(
 // Local helpers
 // ---------------------------------------------------------------------------
 
-/** Current document URL on web; empty string where `location` is absent (native/SSR). */
-function currentLocationHref(): string {
-  const location = (globalThis as { location?: { href?: string } }).location;
-  return typeof location?.href === 'string' ? location.href : '';
+/** 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 : '';
 }