@oxyhq/core 7.1.1 → 8.1.0

package/src/boot/__tests__/coldBootV2.test.ts

@@ -1,5 +1,10 @@
 import type { OxyServices } from '../../OxyServices';
-import type { AuthTokenBundle, TokenRefreshResponse, WebSessionResult } from '@oxyhq/contracts';
+import type {
+  AuthTokenBundle,
+  DeviceTokenMintResponse,
+  TokenRefreshResponse,
+  WebSessionResult,
+} from '@oxyhq/contracts';
 import type { SessionLoginResponse } from '../../models/session';
 import {
   runSessionColdBoot,
@@ -34,6 +39,7 @@ interface OxyOverrides {
   signInWithSharedIdentity?: OxyServices['signInWithSharedIdentity'];
   issueNativeDeviceToken?: OxyServices['issueNativeDeviceToken'];
   requestWebSession?: OxyServices['requestWebSession'];
+  mintFromDeviceSecret?: OxyServices['mintFromDeviceSecret'];
 }
 
 function makeOxy(overrides: OxyOverrides = {}): { oxy: OxyServices; setTokens: jest.Mock } {
@@ -48,12 +54,37 @@ function makeOxy(overrides: OxyOverrides = {}): { oxy: OxyServices; setTokens: j
     requestWebSession:
       overrides.requestWebSession
       ?? (async () => ({ reason: 'no_session', deviceToken: 'dt-web' }) as WebSessionResult),
+    // Default: no persisted secret in these fixtures, so the mint step skips
+    // before ever calling this. Tests that exercise the mint pass an override.
+    mintFromDeviceSecret:
+      overrides.mintFromDeviceSecret
+      ?? (async () => {
+        throw new Error('mintFromDeviceSecret not stubbed');
+      }),
     buildBootstrapUrl: (returnTo: string, state: string) =>
       `https://api.oxy.so/auth/device/bootstrap?return_to=${encodeURIComponent(returnTo)}&state=${state}`,
   } as unknown as OxyServices;
   return { oxy, setTokens };
 }
 
+const MINT: DeviceTokenMintResponse = {
+  accessToken: 'access-minted',
+  expiresAt: new Date(Date.now() + 3_600_000).toISOString(),
+  nextDeviceSecret: 'ds-next-secret',
+  state: {
+    deviceId: 'dev-mint',
+    accounts: [{ accountId: 'user-mint', sessionId: 'sess-mint', authuser: 0 }],
+    activeAccountId: 'user-mint',
+    revision: 2,
+    updatedAt: 1_700_000_000_000,
+  },
+};
+
+/** A 401 error shaped like `HttpService`/`handleError` output for the given body. */
+function mint401(body: string): Error & { status: number } {
+  return Object.assign(new Error(body), { status: 401 });
+}
+
 interface DomHandle {
   dom: ColdBootDom;
   navigate: jest.Mock;
@@ -183,6 +214,189 @@ describe('runSessionColdBoot — step ordering', () => {
   });
 });
 
+describe('runSessionColdBoot — device-secret-mint (phase 2c)', () => {
+  function makeCredStore(extra: Partial<import('../../session/authStateStore').PersistedAuthState> = {}) {
+    const store = createMemoryAuthStateStore();
+    return { store, seed: async () => {
+      await store.save({
+        sessionId: 'sess-old',
+        refreshToken: 'r-abcdefghij',
+        userId: 'user-old',
+        deviceId: 'dev-mint',
+        deviceSecret: 'ds-secret-orig',
+        ...extra,
+      });
+    } };
+  }
+
+  it('wins FIRST via the mint, persisting nextDeviceSecret BEFORE planting the token', async () => {
+    const { store, seed } = makeCredStore();
+    await seed();
+    const mintFromDeviceSecret = jest.fn(async () => MINT);
+    const { oxy, setTokens } = makeOxy({ mintFromDeviceSecret });
+    const saveSpy = jest.spyOn(store, 'save');
+    const onSession = jest.fn();
+
+    const outcome = await runSessionColdBoot({ oxy, store, platform: WEB, dom: makeDom().dom, onSession });
+
+    expect(outcome).toEqual({ kind: 'session', via: 'device-secret-mint', session: expect.any(Object) });
+    expect(mintFromDeviceSecret).toHaveBeenCalledWith('dev-mint', 'ds-secret-orig');
+    expect(setTokens).toHaveBeenCalledWith('access-minted');
+    // Session identity comes from the mint's authoritative active account.
+    expect(onSession).toHaveBeenCalledWith(
+      expect.objectContaining({ sessionId: 'sess-mint', userId: 'user-mint', via: 'device-secret-mint' }),
+    );
+    // Rotation-in-use anti-loss: the store held the NEXT secret before the plant.
+    const lastSaveOrder = Math.max(...saveSpy.mock.invocationCallOrder);
+    const firstPlantOrder = Math.min(...setTokens.mock.invocationCallOrder);
+    expect(lastSaveOrder).toBeLessThan(firstPlantOrder);
+    expect(await store.load()).toMatchObject({
+      deviceSecret: 'ds-next-secret',
+      sessionId: 'sess-mint',
+      userId: 'user-mint',
+      accessToken: 'access-minted',
+    });
+  });
+
+  it('skips (no mint) when only one of deviceId / deviceSecret is persisted', async () => {
+    const store = createMemoryAuthStateStore();
+    await store.save({ sessionId: 's', refreshToken: 'r-abcdefghij', userId: 'u', deviceSecret: 'ds-only' });
+    const mintFromDeviceSecret = jest.fn(async () => MINT);
+    const { oxy } = makeOxy({ mintFromDeviceSecret });
+
+    const outcome = await runSessionColdBoot({ oxy, store, platform: WEB, dom: makeDom().dom });
+
+    expect(mintFromDeviceSecret).not.toHaveBeenCalled();
+    // Falls through to the migratory refresh family.
+    expect(outcome).toEqual({ kind: 'session', via: 'stored-tokens', session: expect.any(Object) });
+  });
+
+  it('401 invalid_device_secret → drops the secret (keeps deviceId) and falls through', async () => {
+    const { store, seed } = makeCredStore();
+    await seed();
+    const mintFromDeviceSecret = jest.fn(async () => {
+      throw mint401('invalid_device_secret');
+    });
+    const { oxy } = makeOxy({ mintFromDeviceSecret });
+
+    const outcome = await runSessionColdBoot({ oxy, store, platform: WEB, dom: makeDom().dom });
+
+    expect(mintFromDeviceSecret).toHaveBeenCalled();
+    // The migratory refresh lane recovers the session.
+    expect(outcome.kind).toBe('session');
+    expect(outcome).toMatchObject({ via: 'stored-tokens' });
+    const persisted = await store.load();
+    expect(persisted?.deviceSecret).toBeUndefined();
+    expect(persisted?.deviceId).toBe('dev-mint');
+  });
+
+  it('401 no_active_session → keeps the secret, signed out, NEVER falls to the hop', async () => {
+    const { store, seed } = makeCredStore();
+    await seed();
+    const mintFromDeviceSecret = jest.fn(async () => {
+      throw mint401('no_active_session');
+    });
+    const { oxy } = makeOxy({ mintFromDeviceSecret });
+    const refreshWithToken = jest.spyOn(oxy, 'refreshWithToken');
+    const requestWebSession = jest.spyOn(oxy, 'requestWebSession');
+    const domHandle = makeDom();
+    const onSignedOut = jest.fn();
+
+    const outcome = await runSessionColdBoot({
+      oxy, store, platform: WEB, dom: domHandle.dom, onSignedOut,
+    });
+
+    expect(outcome).toEqual({ kind: 'unauthenticated' });
+    expect(onSignedOut).toHaveBeenCalledWith('no_session');
+    // The known-signed-out device is not bounced and no fallback lane runs.
+    expect(refreshWithToken).not.toHaveBeenCalled();
+    expect(requestWebSession).not.toHaveBeenCalled();
+    expect(domHandle.navigate).not.toHaveBeenCalled();
+    // The secret is retained — the device may sign in again.
+    expect((await store.load())?.deviceSecret).toBe('ds-secret-orig');
+  });
+
+  it('classifies a PLAIN-OBJECT 401 (no Error prototype) — no_active_session still keeps the secret', async () => {
+    const { store, seed } = makeCredStore();
+    await seed();
+    // Cross-realm / ApiError-shaped throw: not `instanceof Error`. Must still be
+    // read as no_active_session — misreading it as a stale secret would drop it.
+    const mintFromDeviceSecret = jest.fn(async () => {
+      throw { status: 401, message: 'no_active_session' };
+    });
+    const { oxy } = makeOxy({ mintFromDeviceSecret });
+    const onSignedOut = jest.fn();
+
+    const outcome = await runSessionColdBoot({
+      oxy, store, platform: WEB, dom: makeDom().dom, onSignedOut,
+    });
+
+    expect(outcome).toEqual({ kind: 'unauthenticated' });
+    expect((await store.load())?.deviceSecret).toBe('ds-secret-orig');
+  });
+
+  it('transient (non-401) mint error → keeps the secret and falls through', async () => {
+    const { store, seed } = makeCredStore();
+    await seed();
+    const mintFromDeviceSecret = jest.fn(async () => {
+      throw new Error('network down');
+    });
+    const { oxy } = makeOxy({ mintFromDeviceSecret });
+
+    const outcome = await runSessionColdBoot({ oxy, store, platform: WEB, dom: makeDom().dom });
+
+    expect(outcome).toMatchObject({ kind: 'session', via: 'stored-tokens' });
+    // The secret survives a transient failure (rotation preserved through refresh).
+    expect((await store.load())?.deviceSecret).toBe('ds-secret-orig');
+  });
+
+  it('transient mint + cookie-lane hop whose bundle omits a secret → prior secret preserved', async () => {
+    const { store, seed } = makeCredStore();
+    await seed();
+    // Mint down, refresh family down → the chain lands on bootstrap-hop, whose
+    // web-session BUNDLE carries no deviceSecret. The still-valid prior secret
+    // must survive the store overwrite (else the mint lane is orphaned forever).
+    const mintFromDeviceSecret = jest.fn(async () => {
+      throw new Error('network down');
+    });
+    const refreshWithToken = jest.fn(async () => {
+      throw new Error('refresh down');
+    });
+    const requestWebSession = jest.fn(
+      async () => ({ reason: 'session', session: BUNDLE, deviceToken: 'dt-rotated' }) as WebSessionResult,
+    );
+    const { oxy } = makeOxy({ mintFromDeviceSecret, refreshWithToken, requestWebSession });
+    const domHandle = makeDom({ hostname: 'accounts.oxy.so' });
+
+    const outcome = await runSessionColdBoot({ oxy, store, platform: WEB, dom: domHandle.dom });
+
+    expect(outcome).toMatchObject({ kind: 'session', via: 'bootstrap-hop' });
+    const persisted = await store.load();
+    expect(persisted?.deviceSecret).toBe('ds-secret-orig');
+    expect(persisted?.deviceId).toBe('dev-mint');
+  });
+
+  it('is gated OFF while a #oxy_boot return fragment is present (bootstrap-return wins)', async () => {
+    const { store, seed } = makeCredStore();
+    await seed();
+    const frag = { v: 1, state: 'state-match', reason: 'session', code: 'c'.repeat(24), deviceToken: 'd'.repeat(24) };
+    const b64 = Buffer.from(JSON.stringify(frag), 'utf-8')
+      .toString('base64')
+      .replace(/\+/g, '-')
+      .replace(/\//g, '_')
+      .replace(/=+$/, '');
+    const domHandle = makeDom({ hash: `#oxy_boot=${b64}`, sessionState: 'state-match' });
+    const mintFromDeviceSecret = jest.fn(async () => MINT);
+    const { oxy } = makeOxy({ mintFromDeviceSecret });
+
+    const outcome = await runSessionColdBoot({ oxy, store, platform: WEB, dom: domHandle.dom });
+
+    expect(outcome).toMatchObject({ via: 'bootstrap-return' });
+    expect(mintFromDeviceSecret).not.toHaveBeenCalled();
+    expect(domHandle.strip).toHaveBeenCalled();
+  });
+});
+
 describe('runSessionColdBoot — bootstrap-hop (web)', () => {
   it('same-apex: resolves a session via the inline web-session fetch (no navigation)', async () => {
     const store = createMemoryAuthStateStore();

package/src/boot/__tests__/deviceBootReturn.test.ts

@@ -119,6 +119,38 @@ describe('consumeDeviceBootReturn', () => {
     expect(await store.loadDeviceToken()).toBe(DEVICE_TOKEN);
   });
 
+  it('captures the bundle deviceSecret (phase 2c) and preserves a prior deviceId', async () => {
+    const { deps, store } = makeDeps(encodeHash(fragmentObject()), {
+      exchangeBootCode: async () => ({ ...BUNDLE, deviceSecret: 'ds-from-exchange' }),
+    });
+    // A prior deviceId-bearing login persisted a deviceId; the bundle carries no
+    // deviceId, so the overwrite must preserve it to keep the mint lane usable.
+    await store.save({ sessionId: 'prev', refreshToken: 'r-prevabcdefghij', userId: 'user-1', deviceId: 'dev-prev' });
+
+    await consumeDeviceBootReturn(deps);
+
+    const persisted = await store.load();
+    expect(persisted?.deviceSecret).toBe('ds-from-exchange');
+    expect(persisted?.deviceId).toBe('dev-prev');
+  });
+
+  it('preserves a prior deviceSecret when the bundle omits one (never orphans the mint lane)', async () => {
+    const { deps, store } = makeDeps(encodeHash(fragmentObject()));
+    await store.save({
+      sessionId: 'prev',
+      refreshToken: 'r-prevabcdefghij',
+      userId: 'user-1',
+      deviceId: 'dev-prev',
+      deviceSecret: 'ds-still-valid',
+    });
+
+    await consumeDeviceBootReturn(deps);
+
+    const persisted = await store.load();
+    expect(persisted?.deviceSecret).toBe('ds-still-valid');
+    expect(persisted?.deviceId).toBe('dev-prev');
+  });
+
   it('rejects a state mismatch without persisting or exchanging', async () => {
     const { deps, calls, store } = makeDeps(encodeHash(fragmentObject()), { expectedState: 'WRONG' });
     expect(await consumeDeviceBootReturn(deps)).toEqual({ kind: 'state-mismatch' });

package/src/boot/coldBootV2.ts

@@ -28,6 +28,7 @@
 import { resolveUserId } from '@oxyhq/contracts';
 import { runColdBoot, type ColdBootOutcome, type ColdBootStep } from '../utils/coldBoot';
 import { isWeb as detectWeb, isNative as detectNative } from '../utils/platform';
+import { extractErrorStatus } from '../utils/errorUtils';
 import { KeyManager } from '../crypto/keyManager';
 import { logger } from '../utils/loggerUtils';
 import type { OxyServices } from '../OxyServices';
@@ -225,6 +226,34 @@ function sessionFromPersisted(state: PersistedAuthState, accessToken: string): D
   return { sessionId: state.sessionId, userId: state.userId, accessToken };
 }
 
+/**
+ * How a `mintFromDeviceSecret` (phase 2c) call failed, distinguished so the cold
+ * boot can react per the transport contract:
+ *  - `invalid_secret` — the presented secret no longer matches (another tab/
+ *    device rotated it, or theft divergence). Drop it and fall back.
+ *  - `no_active_session` — the device is known but has no live session.
+ *    Authoritative signed-out; keep the secret, do not fall back to the hop.
+ *  - `transient` — network / 5xx. Keep the secret and let the fallback lanes try.
+ *
+ * The mint is bearer-less (`skipAuth`), so `HttpService` surfaces the server's
+ * 401 body string (`invalid_device_secret` | `no_active_session`) as the thrown
+ * error's `message`; any non-401 is transport/server failure.
+ */
+type MintFailure = 'invalid_secret' | 'no_active_session' | 'transient';
+
+function classifyMintFailure(error: unknown): MintFailure {
+  if (extractErrorStatus(error) === 401) {
+    // Structural read (not `instanceof Error`): the thrown value can be a plain
+    // ApiError-shaped object or come from another realm, where instanceof fails
+    // and a `no_active_session` would be misread as a stale secret and dropped.
+    const message = (error as { message?: unknown })?.message;
+    return typeof message === 'string' && message.includes('no_active_session')
+      ? 'no_active_session'
+      : 'invalid_secret';
+  }
+  return 'transient';
+}
+
 /**
  * Run the device-first cold boot. Resolves to the `runColdBoot` outcome and, as
  * a side effect, invokes `onSession` (winning session, token already planted)
@@ -243,9 +272,79 @@ export async function runSessionColdBoot(
   // they cannot leak across boots or break under bundler re-evaluation.
   let signedOutReason: SignedOutReason = 'no_session';
   let navigating = false;
+  // Set when the zero-cookie mint reports `no_active_session` (phase 2c): the
+  // device is authoritatively signed out, so the migratory fallback lanes below
+  // (stored-tokens / shared-key / bootstrap-hop) must NOT run — we already know
+  // there is no session and must not bounce a known-signed-out device.
+  let deviceKnownSignedOut = false;
 
   const steps: Array<ColdBootStep<DeviceBootSession>> = [];
 
+  // 0. device-secret-mint (phase 2c) — the zero-cookie fast path. When the
+  //    origin persisted a deviceId + deviceSecret, mint a short access token with
+  //    a single bearer-less POST (no cookie, no navigation). FIRST in the chain
+  //    so it wins over the migratory cookie lanes below. Gated OFF while a
+  //    #oxy_boot return fragment is present so `bootstrap-return` still consumes
+  //    + strips it first (a device holding a secret never triggers that hop, so
+  //    this only defers a rare stale/forged fragment). The rest of the chain
+  //    stays as the additive migratory fallback for devices not yet on the secret.
+  steps.push({
+    id: 'device-secret-mint',
+    enabled: () => !(isWeb && hashHasBootFragment(dom.getHash())),
+    run: async () => {
+      const persisted = await store.load();
+      if (!persisted?.deviceId || !persisted?.deviceSecret) {
+        return { kind: 'skip' };
+      }
+      try {
+        const mint = await oxy.mintFromDeviceSecret(persisted.deviceId, persisted.deviceSecret);
+        // Rotation-in-use anti-loss: persist the NEXT secret (+ refreshed warm
+        // fields, + the server's authoritative active account) BEFORE planting
+        // the minted access token, so a multi-tab race that rotates again can
+        // never strand this tab with a superseded secret.
+        const active = mint.state.accounts.find((a) => a.accountId === mint.state.activeAccountId);
+        const next: PersistedAuthState = {
+          ...persisted,
+          deviceId: mint.state.deviceId,
+          deviceSecret: mint.nextDeviceSecret,
+          accessToken: mint.accessToken,
+          expiresAt: mint.expiresAt,
+          ...(active ? { sessionId: active.sessionId, userId: active.accountId } : {}),
+        };
+        await store.save(next);
+        oxy.setTokens(mint.accessToken);
+        return {
+          kind: 'session',
+          session: { sessionId: next.sessionId, userId: next.userId, accessToken: mint.accessToken },
+        };
+      } catch (error) {
+        const failure = classifyMintFailure(error);
+        if (failure === 'invalid_secret') {
+          // Stale/diverged secret — drop it so the mint lane stops firing, then
+          // fall through to the migratory refresh/cookie lanes. Setting it
+          // undefined drops the key on the store's JSON serialization, and the
+          // mint guard treats undefined as absent.
+          await store.save({ ...persisted, deviceSecret: undefined });
+          return { kind: 'skip' };
+        }
+        if (failure === 'no_active_session') {
+          // Device known, no live session — authoritative signed-out. KEEP the
+          // secret and stop the chain (do not bounce a known-signed-out device).
+          deviceKnownSignedOut = true;
+          signedOutReason = 'no_session';
+          return { kind: 'skip' };
+        }
+        // Transient (network / 5xx): keep the secret, let the fallback lanes try.
+        logger.debug(
+          'device-secret mint failed (transient) — keeping secret, falling back',
+          { component: 'coldBootV2', method: 'device-secret-mint' },
+          error,
+        );
+        return { kind: 'skip' };
+      }
+    },
+  });
+
   // 1. bootstrap-return (web) — consume a #oxy_boot fragment.
   steps.push({
     id: 'bootstrap-return',
@@ -279,6 +378,7 @@ export async function runSessionColdBoot(
   // 2. stored-tokens — warm-plant or rotate the persisted refresh family.
   steps.push({
     id: 'stored-tokens',
+    enabled: () => !deviceKnownSignedOut,
     run: async () => {
       const persisted = await store.load();
       if (!persisted) {
@@ -308,7 +408,7 @@ export async function runSessionColdBoot(
   // 3. shared-key-signin (native) — re-mint from the shared identity.
   steps.push({
     id: 'shared-key-signin',
-    enabled: () => isNative,
+    enabled: () => isNative && !deviceKnownSignedOut,
     run: async () => {
       const session = await oxy.signInWithSharedIdentity();
       if (!session?.accessToken) {
@@ -345,7 +445,7 @@ export async function runSessionColdBoot(
   // 4. bootstrap-hop (web, terminal) — same-apex inline fetch OR cross-apex nav.
   steps.push({
     id: 'bootstrap-hop',
-    enabled: () => isWeb,
+    enabled: () => isWeb && !deviceKnownSignedOut,
     run: async () => {
       const pageHost = dom.getLocationHostname();
       let apiHost: string | null = null;
@@ -378,6 +478,21 @@ export async function runSessionColdBoot(
             accessToken: bundle.accessToken,
             expiresAt: bundle.expiresAt,
           };
+          // Phase 2c: the web-session bundle may carry a rotating `deviceSecret`
+          // but NOT a deviceId. Persist the secret and carry any prior deviceId
+          // (from a deviceId-bearing login lane) forward so the mint lane stays
+          // usable — this overwrite must not orphan it.
+          const prior = await store.load();
+          if (prior?.deviceId) {
+            next.deviceId = prior.deviceId;
+          }
+          // Prefer the bundle's secret (the server just rotated onto it); keep the
+          // prior one when the bundle omits it — this lane also runs as the
+          // TRANSIENT-mint fallback, and must not orphan a still-valid secret.
+          const carriedSecret = bundle.deviceSecret ?? prior?.deviceSecret;
+          if (carriedSecret) {
+            next.deviceSecret = carriedSecret;
+          }
           await store.save(next);
           oxy.setTokens(bundle.accessToken);
           return { kind: 'session', session: sessionFromPersisted(next, bundle.accessToken) };

package/src/boot/deviceBootReturn.ts

@@ -178,6 +178,21 @@ export async function consumeDeviceBootReturn(
         accessToken: bundle.accessToken,
         expiresAt: bundle.expiresAt,
       };
+      // Phase 2c: the cookie-bootstrap bundle may carry a rotating `deviceSecret`
+      // but NOT a deviceId. Persist the secret, and carry any prior deviceId
+      // forward (from a deviceId-bearing login lane) so the pair stays usable by
+      // the zero-cookie mint — an overwrite here must not orphan the mint lane.
+      const prior = await deps.store.load();
+      if (prior?.deviceId) {
+        next.deviceId = prior.deviceId;
+      }
+      // Prefer the bundle's secret (the server just rotated onto it); keep the
+      // prior one when the bundle omits it so a cookie-lane boot can never orphan
+      // a still-valid secret captured by an earlier login lane.
+      const carriedSecret = bundle.deviceSecret ?? prior?.deviceSecret;
+      if (carriedSecret) {
+        next.deviceSecret = carriedSecret;
+      }
       await deps.store.save(next);
       deps.plantAccessToken(bundle.accessToken);
       return {

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

@@ -384,7 +384,11 @@
       "subtitle": "Add another account to switch between them quickly"
     },
     "label": "Account switcher",
-    "searchPlaceholder": "Search accounts"
+    "searchPlaceholder": "Search accounts",
+    "scanTitle": "Scan to sign in",
+    "scanSubtitle": "Open the Oxy app on your phone and scan this code",
+    "scanWithOxy": "Scan with the Oxy app to continue",
+    "scanQr": "Scan QR code"
   },
   "reputation": {
     "faq": {
@@ -1905,5 +1909,44 @@
       "earlyAdopter": "Early Adopter",
       "earlyAdopterDesc": "Been part of the community from the start"
     }
+  },
+  "consent": {
+    "title": "Continue to {{app}}",
+    "subtitle": "Use your Oxy account to sign in to {{app}}. Review what this connection means before you continue.",
+    "provenance": {
+      "title": "Who is requesting access",
+      "official": "Official Oxy application",
+      "developer": "Published by {{developer}}",
+      "thirdParty": "Third-party application"
+    },
+    "permissions": {
+      "title": "Permissions requested",
+      "basic": "Sign you in and read your basic profile"
+    },
+    "scopes": {
+      "openid": "Confirm your identity",
+      "profile": "Read your basic profile",
+      "email": "Read your email address",
+      "offlineAccess": "Keep you signed in when you're away",
+      "userRead": "Read your basic profile",
+      "filesRead": "Read your files",
+      "filesWrite": "Upload and modify your files",
+      "filesDelete": "Delete your files",
+      "webhooksReceive": "Receive webhooks",
+      "chatCompletions": "Use AI chat on your behalf",
+      "modelsRead": "List available AI models",
+      "federationWrite": "Act across federated services"
+    },
+    "account": {
+      "title": "Signing in as"
+    },
+    "links": {
+      "website": "Website",
+      "privacy": "Privacy Policy",
+      "terms": "Terms of Service"
+    },
+    "allow": "Continue to {{app}}",
+    "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

@@ -581,7 +581,11 @@
       "subtitle": "Añade otra cuenta para cambiar rápidamente entre ellas"
     },
     "label": "Selector de cuentas",
-    "searchPlaceholder": "Buscar cuentas"
+    "searchPlaceholder": "Buscar cuentas",
+    "scanTitle": "Escanea para iniciar sesión",
+    "scanSubtitle": "Abre la app de Oxy en tu móvil y escanea este código",
+    "scanWithOxy": "Escanea con la app de Oxy para continuar",
+    "scanQr": "Escanear código QR"
   },
   "feedback": {
     "type": {
@@ -1905,5 +1909,44 @@
       "earlyAdopter": "Pionero",
       "earlyAdopterDesc": "Has formado parte de la comunidad desde el principio"
     }
+  },
+  "consent": {
+    "title": "Continuar a {{app}}",
+    "subtitle": "Usa tu cuenta de Oxy para iniciar sesión en {{app}}. Revisa qué implica esta conexión antes de continuar.",
+    "provenance": {
+      "title": "Quién solicita acceso",
+      "official": "Aplicación oficial de Oxy",
+      "developer": "Publicada por {{developer}}",
+      "thirdParty": "Aplicación de terceros"
+    },
+    "permissions": {
+      "title": "Permisos solicitados",
+      "basic": "Iniciar sesión y leer tu perfil básico"
+    },
+    "scopes": {
+      "openid": "Confirmar tu identidad",
+      "profile": "Leer tu perfil básico",
+      "email": "Leer tu dirección de correo",
+      "offlineAccess": "Mantener tu sesión iniciada cuando no estés",
+      "userRead": "Leer tu perfil básico",
+      "filesRead": "Leer tus archivos",
+      "filesWrite": "Subir y modificar tus archivos",
+      "filesDelete": "Eliminar tus archivos",
+      "webhooksReceive": "Recibir webhooks",
+      "chatCompletions": "Usar el chat con IA en tu nombre",
+      "modelsRead": "Ver los modelos de IA disponibles",
+      "federationWrite": "Actuar en servicios federados"
+    },
+    "account": {
+      "title": "Iniciando sesión como"
+    },
+    "links": {
+      "website": "Sitio web",
+      "privacy": "Política de privacidad",
+      "terms": "Términos del servicio"
+    },
+    "allow": "Continuar a {{app}}",
+    "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

@@ -304,9 +304,9 @@ export type {
     SecurityActivity,
     SecurityActivityResponse,
     AssetUploadProgress,
-    DeviceSession,
-    DeviceSessionsResponse,
-    DeviceSessionLogoutResponse,
+    DeviceLinkedSession,
+    DeviceLinkedSessionsResponse,
+    DeviceLinkedSessionLogoutResponse,
     UpdateDeviceNameResponse,
 } from './models/interfaces';
 export { SECURITY_EVENT_SEVERITY_MAP } from './models/interfaces';
@@ -494,20 +494,13 @@ export type { QuickAccount, DisplayNameUserShape } from './utils/accountUtils';
 // ---------------------------------------------------------------------------
 // Registrable-domain + central-IdP-apex helpers.
 //
-// The client SSO-bounce / silent-iframe / FedCM machinery was removed in the
-// device-first cutover (wave 2, ecosystem-wide bump complete). `registrableApex`
-// (eTLD+1) and `CENTRAL_IDP_APEX` are still genuinely used: `registrableApex`
-// via the `@oxyhq/core/server` re-export consumed by
-// `packages/api/src/utils/sameSite.ts` for same-site origin checks, and
-// `CENTRAL_IDP_APEX` by `server/cors.ts`'s `createOxyCors` (auto-allows
-// `*.oxy.so`). `SSO_CALLBACK_PATH` has no remaining importer outside this
-// module as of wave 2 — kept exported for now rather than removed here (an
-// export deletion is a logic change, out of scope for a comment sweep); flag
-// for a follow-up dead-export cleanup pass.
+// `registrableApex` (eTLD+1) is consumed via the `@oxyhq/core/server`
+// re-export by `packages/api/src/utils/sameSite.ts` for same-site origin
+// checks; `CENTRAL_IDP_APEX` by `server/cors.ts`'s `createOxyCors` (auto-allows
+// `*.oxy.so`).
 // ---------------------------------------------------------------------------
 export { registrableApex } from './utils/registrableApex';
 export { CENTRAL_IDP_APEX } from './utils/authWebUrl';
-export { SSO_CALLBACK_PATH } from './utils/ssoBounce';
 
 export { runColdBoot } from './utils/coldBoot';
 export type {
@@ -519,6 +512,20 @@ export type {
     RunColdBootOptions,
 } from './utils/coldBoot';
 
+// ---------------------------------------------------------------------------
+// OAuth 2.0 Authorization Code + PKCE helpers ("Sign in with Oxy" third party).
+// Standard OAuth against auth.oxy.so/authorize — no FedCM/cookies/SSO bounce.
+// ---------------------------------------------------------------------------
+export {
+    buildOAuthAuthorizeUrl,
+    computeCodeChallenge,
+    generateOAuthState,
+    generatePkcePair,
+    DEFAULT_OAUTH_SCOPE,
+    OXY_AUTHORIZE_URL,
+} from './utils/oauthPkce';
+export type { PkcePair, BuildOAuthAuthorizeUrlParams } from './utils/oauthPkce';
+
 // ---------------------------------------------------------------------------
 // Session sync (device-scoped multi-account session client)
 // ---------------------------------------------------------------------------
@@ -531,7 +538,7 @@ export type { SocketIOFactory, MinimalSocket } from './session/socketLoader';
 
 // Shared SessionClient integration layer: the host adapter, the pure
 // DeviceSessionState projection helpers, and the client factory are defined
-// ONCE here so `@oxyhq/services` and `@oxyhq/auth` both reuse them instead of
+// ONCE here so every `@oxyhq/services` platform variant reuses them instead of
 // duplicating a local copy. Each consumer supplies its own `TokenTransport`
 // (native vs. web mint strategies differ) to `createSessionClient`.
 export { createSessionClientHost } from './session/sessionClientHost';
@@ -546,7 +553,7 @@ export {
 // Unified account-list projection (THE single source of truth for the account
 // chooser: device sign-ins ∪ account graph, deduped by accountId). Pure +
 // I/O-free — the caller hydrates profiles via `getUsersByIds`. Shared by
-// `@oxyhq/services`, `@oxyhq/auth`, and auth.oxy.so so the list can't diverge.
+// `@oxyhq/services` and auth.oxy.so so the list can't diverge.
 export {
     projectSwitchableAccounts,
     switchableAccountIds,