@oxyhq/core 8.0.0 → 9.0.0

package/src/mixins/OxyServices.auth.ts

@@ -1128,16 +1128,15 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
      * (`{ twoFactorRequired, loginToken }`) to complete via
      * {@link completeTwoFactorSignIn}, or a session arm.
      *
-     * `options.deviceToken` attributes the new session to the caller's existing
-     * device set (so an in-app login from a cross-apex, cookie-less web app
-     * still joins the same DeviceSession). On the session arm, a returned access
-     * token is planted immediately (mirroring {@link verifyChallenge}), so the
-     * caller has an authenticated client without a second round-trip.
+     * On the session arm, a returned access token is planted immediately
+     * (mirroring {@link verifyChallenge}), so the caller has an authenticated
+     * client without a second round-trip. The response's `deviceId` +
+     * `deviceSecret` are the zero-cookie restore credential the caller persists.
      */
     async passwordSignIn(
       identifier: string,
       password: string,
-      options: { deviceToken?: string; deviceName?: string; deviceFingerprint?: string } = {},
+      options: { deviceName?: string; deviceFingerprint?: string } = {},
     ): Promise<LoginResult> {
       try {
         const res = await this.makeRequest<unknown>('POST', '/auth/login', {
@@ -1145,7 +1144,6 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
           password,
           deviceName: options.deviceName,
           deviceFingerprint: options.deviceFingerprint,
-          deviceToken: options.deviceToken,
         }, { cache: false });
         const parsed = safeParseContract(loginResultSchema, res);
         if (!parsed) {
@@ -1171,7 +1169,6 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
       loginToken: string;
       token?: string;
       backupCode?: string;
-      deviceToken?: string;
       deviceName?: string;
     }): Promise<LoginSessionResult> {
       try {
@@ -1179,7 +1176,6 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
           loginToken: params.loginToken,
           token: params.token,
           backupCode: params.backupCode,
-          deviceToken: params.deviceToken,
           deviceName: params.deviceName,
         }, { cache: false });
         const parsed = safeParseContract(loginResultSchema, res);

package/src/mixins/OxyServices.deviceBoot.ts

@@ -1,146 +1,61 @@
 /**
- * Device-first bootstrap mixin (auth centralization, wave 1).
+ * Device-first token mint mixin.
  *
- * The client half of the new device-first session bootstrap: the four network
- * calls the cold boot (`coldBootV2`) and the unified refresh handler
- * (`refresh.ts`) make, plus the URL builder for the cross-apex bootstrap hop.
- * Every response is validated against the `@oxyhq/contracts` `deviceBoot`
- * schemas via `safeParseContract`, so producer (oxy-api) and consumer cannot
+ * 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`)
+ * 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
  * drift — an unexpected shape throws here rather than silently corrupting the
  * persisted store.
  *
- * These methods are ADDITIVE and carry NO persistence or token-planting side
- * effects of their own (except the bearer-authenticated calls that naturally
- * flow through `HttpService`). The cold boot / refresh handler own persistence
- * and `setTokens`, so the same network primitive can be reused from either
- * without double-planting.
+ * This method carries NO persistence or token-planting side effects of its own;
+ * the cold boot / re-mint handler own persistence and `setTokens`, so the same
+ * primitive can be reused from either without double-planting.
  */
 import {
-  authTokenBundleSchema,
-  tokenRefreshResponseSchema,
-  deviceTokenIssueResponseSchema,
-  webSessionResultSchema,
+  deviceTokenMintResponseSchema,
   safeParseContract,
-  type AuthTokenBundle,
-  type TokenRefreshResponse,
-  type WebSessionResult,
+  type DeviceTokenMintResponse,
 } from '@oxyhq/contracts';
 import type { OxyServicesBase } from '../OxyServices.base';
 
 export function OxyServicesDeviceBootMixin<T extends typeof OxyServicesBase>(Base: T) {
   return class extends Base {
     /**
-     * Exchange a single-use boot `code` (from the `#oxy_boot` return fragment)
-     * for a token bundle. Origin-bound + GETDEL-burned server-side.
+     * Zero-cookie mint. Present the first-party `deviceId` + `deviceSecret` to
+     * `POST /session/device/token` — NO bearer, NO cookies: possession of the
+     * secret IS the device-ownership proof. Returns a fresh short access token
+     * for the device's active account plus `nextDeviceSecret` (rotation-in-use)
+     * and the projected device-session `state`.
      *
-     * @throws if the response does not match {@link authTokenBundleSchema}.
-     */
-    async exchangeBootCode(code: string): Promise<AuthTokenBundle> {
-      try {
-        const res = await this.makeRequest<unknown>(
-          'POST',
-          '/auth/device/exchange',
-          { code },
-          { cache: false },
-        );
-        const parsed = safeParseContract(authTokenBundleSchema, res);
-        if (!parsed) {
-          throw new Error('device/exchange returned an unexpected response shape');
-        }
-        return parsed;
-      } catch (error) {
-        throw this.handleError(error);
-      }
-    }
-
-    /**
-     * Same-site fast path (`*.oxy.so` apps). Reads the first-party `oxy_device`
-     * cookie via a credentialed same-origin fetch and either resolves a full
-     * session bundle or reports the device is known-but-signed-out. Never
-     * redirects.
+     * `skipAuth`: this call carries no bearer, so a 401 must surface DIRECTLY —
+     * never trigger `HttpService`'s 401→refresh→retry dance. The cold boot / re-
+     * mint handler read the 401 body (`invalid_device_secret` vs
+     * `no_active_session`) to decide whether to drop the secret and fall back or
+     * resolve signed-out.
      *
-     * @throws if the response matches neither arm of {@link webSessionResultSchema}.
+     * @throws if the response does not match {@link deviceTokenMintResponseSchema}.
      */
-    async requestWebSession(): Promise<WebSessionResult> {
+    async mintFromDeviceSecret(
+      deviceId: string,
+      deviceSecret: string,
+    ): Promise<DeviceTokenMintResponse> {
       try {
         const res = await this.makeRequest<unknown>(
           'POST',
-          '/auth/device/web-session',
-          undefined,
-          { cache: false },
-        );
-        const parsed = safeParseContract(webSessionResultSchema, res);
-        if (!parsed) {
-          throw new Error('device/web-session returned an unexpected response shape');
-        }
-        return parsed;
-      } catch (error) {
-        throw this.handleError(error);
-      }
-    }
-
-    /**
-     * Rotate the persisted refresh-token family (web + native, one call). The
-     * caller (refresh handler / cold boot) plants + persists the rotated pair.
-     *
-     * @throws if the response does not match {@link tokenRefreshResponseSchema}.
-     */
-    async refreshWithToken(refreshToken: string): Promise<TokenRefreshResponse> {
-      try {
-        const res = await this.makeRequest<unknown>(
-          'POST',
-          '/auth/refresh-token',
-          { refreshToken },
-          // `skipAuth`: refresh-token is body-authenticated and is called from
-          // inside the refresh handler — sending the near-expired bearer through
-          // the preflight would deadlock. See RequestOptions.skipAuth.
+          '/session/device/token',
+          { deviceId, deviceSecret },
           { cache: false, skipAuth: true },
         );
-        const parsed = safeParseContract(tokenRefreshResponseSchema, res);
+        const parsed = safeParseContract(deviceTokenMintResponseSchema, res);
         if (!parsed) {
-          throw new Error('auth/refresh-token returned an unexpected response shape');
+          throw new Error('session/device/token returned an unexpected response shape');
         }
         return parsed;
       } catch (error) {
         throw this.handleError(error);
       }
     }
-
-    /**
-     * Issue (or rotate) the native channel's opaque device token. Bearer-gated —
-     * the server derives the deviceId from the JWT. Native apps mirror the
-     * returned token into the shared keychain via
-     * `KeyManager.setSharedDeviceToken`.
-     *
-     * @throws if the response does not match {@link deviceTokenIssueResponseSchema}.
-     */
-    async issueNativeDeviceToken(): Promise<string> {
-      try {
-        const res = await this.makeRequest<unknown>(
-          'POST',
-          '/auth/device/token',
-          undefined,
-          { cache: false },
-        );
-        const parsed = safeParseContract(deviceTokenIssueResponseSchema, res);
-        if (!parsed) {
-          throw new Error('auth/device/token returned an unexpected response shape');
-        }
-        return parsed.deviceToken;
-      } catch (error) {
-        throw this.handleError(error);
-      }
-    }
-
-    /**
-     * Build the top-level `GET /auth/device/bootstrap` URL for the cross-apex
-     * hop. The server validates `return_to` against the trusted-origin lane and
-     * echoes `state` back in the return fragment for CSRF verification.
-     */
-    buildBootstrapUrl(returnTo: string, state: string): string {
-      const base = this.getBaseURL().replace(/\/+$/, '');
-      const params = new URLSearchParams({ return_to: returnTo, state });
-      return `${base}/auth/device/bootstrap?${params.toString()}`;
-    }
   };
 }

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

@@ -1,26 +1,11 @@
 /**
  * Device-boot mixin tests. Stubs `makeRequest` so the tests run with no network
- * and asserts each method's route/shape, contract validation, and the
- * `skipAuth` flag on the refresh call.
+ * and asserts `mintFromDeviceSecret`'s route/shape, contract validation, and the
+ * `skipAuth` flag on the bearer-less mint call.
  */
-import type { AuthTokenBundle, TokenRefreshResponse, WebSessionResult } from '@oxyhq/contracts';
+import type { DeviceTokenMintResponse } from '@oxyhq/contracts';
 import { OxyServices } from '../../OxyServices';
 
-const BUNDLE: AuthTokenBundle = {
-  sessionId: 'sess-1',
-  accessToken: 'access-1',
-  refreshToken: 'refresh-abcdefghijkl',
-  expiresAt: '2030-01-01T00:00:00.000Z',
-  user: { id: 'user-1', name: {} } as AuthTokenBundle['user'],
-};
-
-const ROTATED: TokenRefreshResponse = {
-  accessToken: 'access-2',
-  refreshToken: 'refresh-mnopqrstuvwx',
-  expiresAt: '2030-01-01T00:00:00.000Z',
-  sessionId: 'sess-1',
-};
-
 describe('OxyServices.deviceBoot', () => {
   let oxy: OxyServices;
   let makeRequest: jest.SpyInstance;
@@ -32,76 +17,47 @@ describe('OxyServices.deviceBoot', () => {
 
   afterEach(() => jest.restoreAllMocks());
 
-  describe('exchangeBootCode', () => {
-    it('POSTs the code and returns the validated bundle', async () => {
-      makeRequest.mockResolvedValueOnce(BUNDLE);
-      const result = await oxy.exchangeBootCode('code-123');
-      expect(result).toEqual(BUNDLE);
-      expect(makeRequest).toHaveBeenCalledWith('POST', '/auth/device/exchange', { code: 'code-123' }, { cache: false });
-    });
-
-    it('throws on an unexpected response shape', async () => {
-      makeRequest.mockResolvedValueOnce({ nope: true });
-      await expect(oxy.exchangeBootCode('code-123')).rejects.toThrow();
-    });
-  });
-
-  describe('requestWebSession', () => {
-    it('returns the session arm (bundle nested under `session` + deviceToken)', async () => {
-      const sessionArm: WebSessionResult = { reason: 'session', session: BUNDLE, deviceToken: 'device-abcdefghij' };
-      makeRequest.mockResolvedValueOnce(sessionArm);
-      const result = await oxy.requestWebSession();
-      expect(result).toEqual(sessionArm);
-      expect(makeRequest).toHaveBeenCalledWith('POST', '/auth/device/web-session', undefined, { cache: false });
-    });
-
-    it('returns the no-session arm', async () => {
-      const noSession: WebSessionResult = { reason: 'no_session', deviceToken: 'device-abcdefghij' };
-      makeRequest.mockResolvedValueOnce(noSession);
-      const result = await oxy.requestWebSession();
-      expect(result.reason).toBe('no_session');
-      expect(result).toEqual(noSession);
-    });
-
-    it('throws on the OLD bare-bundle shape (regression: server now wraps in a reason envelope)', async () => {
-      makeRequest.mockResolvedValueOnce(BUNDLE);
-      await expect(oxy.requestWebSession()).rejects.toThrow();
-    });
-
-    it('throws when the response matches neither arm', async () => {
-      makeRequest.mockResolvedValueOnce({ reason: 'weird' });
-      await expect(oxy.requestWebSession()).rejects.toThrow();
-    });
-  });
-
-  describe('refreshWithToken', () => {
-    it('POSTs with skipAuth and returns the rotated pair', async () => {
-      makeRequest.mockResolvedValueOnce(ROTATED);
-      const result = await oxy.refreshWithToken('refresh-abcdefghijkl');
-      expect(result).toEqual(ROTATED);
+  describe('mintFromDeviceSecret', () => {
+    const MINT: DeviceTokenMintResponse = {
+      accessToken: 'access-minted',
+      expiresAt: '2030-01-01T00:00:00.000Z',
+      nextDeviceSecret: 'ds-next-secret',
+      state: {
+        deviceId: 'dev-1',
+        accounts: [{ accountId: 'user-1', sessionId: 'sess-1', authuser: 0 }],
+        activeAccountId: 'user-1',
+        revision: 3,
+        updatedAt: 1_700_000_000_000,
+      },
+    };
+
+    it('POSTs deviceId + deviceSecret with skipAuth (no bearer, no cache) and returns the validated mint', async () => {
+      makeRequest.mockResolvedValueOnce(MINT);
+      const result = await oxy.mintFromDeviceSecret('dev-1', 'ds-current-secret');
+      expect(result).toEqual(MINT);
       expect(makeRequest).toHaveBeenCalledWith(
         'POST',
-        '/auth/refresh-token',
-        { refreshToken: 'refresh-abcdefghijkl' },
+        '/session/device/token',
+        { deviceId: 'dev-1', deviceSecret: 'ds-current-secret' },
         { cache: false, skipAuth: true },
       );
     });
-  });
 
-  describe('issueNativeDeviceToken', () => {
-    it('POSTs and returns just the token string', async () => {
-      makeRequest.mockResolvedValueOnce({ deviceToken: 'native-dt' });
-      expect(await oxy.issueNativeDeviceToken()).toBe('native-dt');
-      expect(makeRequest).toHaveBeenCalledWith('POST', '/auth/device/token', undefined, { cache: false });
+    it('throws on an unexpected response shape (missing state / nextDeviceSecret)', async () => {
+      makeRequest.mockResolvedValueOnce({ accessToken: 'a', expiresAt: 'b' });
+      await expect(oxy.mintFromDeviceSecret('dev-1', 'ds')).rejects.toThrow();
+    });
+
+    it('propagates a rejected request (e.g. 401 invalid_device_secret)', async () => {
+      const err = Object.assign(new Error('invalid_device_secret'), { status: 401 });
+      makeRequest.mockRejectedValueOnce(err);
+      await expect(oxy.mintFromDeviceSecret('dev-1', 'ds')).rejects.toThrow('invalid_device_secret');
     });
-  });
 
-  describe('buildBootstrapUrl', () => {
-    it('builds the bootstrap URL with encoded params', () => {
-      const url = oxy.buildBootstrapUrl('https://accounts.oxy.so/home', 'st-1');
-      expect(url).toContain('http://test.invalid/auth/device/bootstrap?');
-      expect(url).toContain('return_to=https%3A%2F%2Faccounts.oxy.so%2Fhome');
-      expect(url).toContain('state=st-1');
+    it('propagates a 401 no_active_session so the caller can resolve signed-out', async () => {
+      const err = Object.assign(new Error('no_active_session'), { status: 401 });
+      makeRequest.mockRejectedValueOnce(err);
+      await expect(oxy.mintFromDeviceSecret('dev-1', 'ds')).rejects.toThrow('no_active_session');
     });
   });
 });

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

@@ -115,7 +115,6 @@ describe('OxyServices.onTokensChanged', () => {
           deviceId: 'dev_1',
           expiresAt: new Date(Date.now() + 60_000).toISOString(),
           accessToken: 'access_verify',
-          refreshToken: 'refresh_verify',
           user: { id: 'user_1', username: 'tester' },
         } as never;
       }

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

@@ -1,9 +1,10 @@
 /**
  * Device-first password sign-in (`passwordSignIn` + `completeTwoFactorSignIn`).
  * Stubs `makeRequest` and asserts the login-result contract handling: the 2FA
- * arm passes through un-planted, the session arm plants its access token, the
- * deviceToken is threaded into the request, and a 2FA arm from verify-login is
- * a protocol error.
+ * arm passes through un-planted, the session arm plants its access token and
+ * carries the zero-cookie `deviceId` + `deviceSecret` restore credential,
+ * `deviceName` / `deviceFingerprint` are threaded into the request, and a 2FA
+ * arm returned from verify-login is a protocol error.
  */
 import type { LoginResult } from '@oxyhq/contracts';
 import { OxyServices } from '../../OxyServices';
@@ -13,7 +14,7 @@ const SESSION_ARM: LoginResult = {
   deviceId: 'dev-1',
   expiresAt: '2030-01-01T00:00:00.000Z',
   accessToken: 'access-1',
-  refreshToken: 'refresh-1',
+  deviceSecret: 'ds-secret-1',
   user: { id: 'user-1', username: 'u' },
 };
 
@@ -39,19 +40,42 @@ describe('passwordSignIn', () => {
     expect(setTokens).not.toHaveBeenCalled();
   });
 
-  it('plants the access token on the session arm and threads the deviceToken', async () => {
+  it('plants the access token on the session arm, exposes the mint credential, and threads deviceName + deviceFingerprint', async () => {
     makeRequest.mockResolvedValueOnce(SESSION_ARM);
-    const result = await oxy.passwordSignIn('alice', 'pw', { deviceToken: 'dt-1', deviceName: 'Phone' });
+    const result = await oxy.passwordSignIn('alice', 'pw', { deviceName: 'Phone', deviceFingerprint: 'fp-1' });
     expect(result).toEqual(SESSION_ARM);
+    // The zero-cookie restore credential is on the session arm the caller persists.
+    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/login',
-      { identifier: 'alice', password: 'pw', deviceName: 'Phone', deviceFingerprint: undefined, deviceToken: 'dt-1' },
+      { identifier: 'alice', password: 'pw', deviceName: 'Phone', deviceFingerprint: 'fp-1' },
       { cache: false },
     );
   });
 
+  it('preserves the securityAlert on the session arm (contract parse must not strip it)', async () => {
+    const withAlert: LoginResult = {
+      ...SESSION_ARM,
+      securityAlert: {
+        message: 'Unusual activity detected on your account',
+        anomalies: [{ type: 'new_device', reason: 'first seen', details: 'Chrome / macOS' }],
+      },
+    };
+    makeRequest.mockResolvedValueOnce(withAlert);
+    const result = await oxy.passwordSignIn('alice', 'pw');
+    expect('twoFactorRequired' in result).toBe(false);
+    if (!('twoFactorRequired' in result)) {
+      expect(result.securityAlert?.message).toBe('Unusual activity detected on your account');
+      expect(result.securityAlert?.anomalies[0]?.type).toBe('new_device');
+    }
+  });
+
   it('throws on an unexpected response shape', async () => {
     makeRequest.mockResolvedValueOnce({ nope: true });
     await expect(oxy.passwordSignIn('alice', 'pw')).rejects.toThrow();
@@ -73,13 +97,13 @@ describe('completeTwoFactorSignIn', () => {
 
   it('verifies the login token, plants the session, and POSTs to /security/2fa/verify-login', async () => {
     makeRequest.mockResolvedValueOnce(SESSION_ARM);
-    const result = await oxy.completeTwoFactorSignIn({ loginToken: 'lt', token: '123456', deviceToken: 'dt-1' });
+    const result = await oxy.completeTwoFactorSignIn({ loginToken: 'lt', token: '123456', deviceName: 'Phone' });
     expect(result).toEqual(SESSION_ARM);
     expect(setTokens).toHaveBeenCalledWith('access-1');
     expect(makeRequest).toHaveBeenCalledWith(
       'POST',
       '/security/2fa/verify-login',
-      { loginToken: 'lt', token: '123456', backupCode: undefined, deviceToken: 'dt-1', deviceName: undefined },
+      { loginToken: 'lt', token: '123456', backupCode: undefined, deviceName: 'Phone' },
       { cache: false },
     );
   });

package/src/mixins/index.ts

@@ -129,9 +129,8 @@ const MIXIN_PIPELINE: MixinFunction[] = [
     // so apps stop scraping link metadata locally.
     OxyServicesLinksMixin,
 
-    // Device-first session bootstrap: the client half of the new
-    // /auth/device/* + /auth/refresh-token surface (exchange, web-session,
-    // refresh, native device-token, bootstrap-url builder).
+    // Device-first token mint: the client half of the zero-cookie transport
+    // (`mintFromDeviceSecret` → `POST /session/device/token`).
     OxyServicesDeviceBootMixin,
 
     // Utility (last, can use all above)