@oxyhq/core 8.1.0 → 9.1.0

package/src/index.ts

@@ -582,18 +582,17 @@ export type {
 } from './session/accountDialogController';
 
 // ---------------------------------------------------------------------------
-// Device-first session machinery (auth centralization, wave 1) — additive.
-// Persisted auth-state store, the unified refresh handler + scheduler, the
-// cold-boot v2 runner, and the device-boot return-fragment consumer. Built ON
-// the existing `runColdBoot` primitive + `SessionClient`; the legacy
-// FedCM/SSO/CrossDomainAuth surface is untouched (cutover happens in F4).
+// Device-first session machinery (zero-cookie transport).
+// Persisted auth-state store, the unified re-mint handler + scheduler, and the
+// cold-boot runner. Built ON the `runColdBoot` primitive + `SessionClient`. The
+// device credential is `deviceId` + `deviceSecret`; the access token is re-minted
+// via `POST /session/device/token`.
 // ---------------------------------------------------------------------------
 export {
     createWebAuthStateStore,
     createNativeAuthStateStore,
     createMemoryAuthStateStore,
     AUTH_STATE_STORAGE_KEY,
-    DEVICE_TOKEN_STORAGE_KEY,
 } from './session/authStateStore';
 export type {
     PersistedAuthState,
@@ -610,34 +609,12 @@ export {
 } from './session/refresh';
 export type { RefreshDeps, TokenRefreshSchedulerHandle } from './session/refresh';
 
-export {
-    runSessionColdBoot,
-    createBrowserColdBootDom,
-    isSameApex,
-    BOOT_ATTEMPTED_KEY,
-} from './boot/coldBootV2';
+export { runSessionColdBoot } from './boot/coldBootV2';
 export type {
     RunSessionColdBootOptions,
-    ColdBootDom,
     SignedOutReason,
-} from './boot/coldBootV2';
-
-export {
-    consumeDeviceBootReturn,
-    parseDeviceBootFragment,
-    hashHasBootFragment,
-    BOOT_FRAGMENT_PARAM,
-    BOOT_STATE_SESSION_KEY,
-} from './boot/deviceBootReturn';
-export type {
     DeviceBootSession,
-    DeviceBootReturnOutcome,
-    ConsumeDeviceBootReturnDeps,
-} from './boot/deviceBootReturn';
-
-// The web-session result contract (`WebSessionResult`) is owned by
-// `@oxyhq/contracts` — import it directly from there; `@oxyhq/core` does not
-// re-export contract types.
+} from './boot/coldBootV2';
 
 // API response contracts (request/response Zod schemas + inferred types) live in
 // `@oxyhq/contracts` — the single source of truth shared by the backend and every

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,151 +1,39 @@
 /**
- * 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,
   deviceTokenMintResponseSchema,
-  webSessionResultSchema,
   safeParseContract,
-  type AuthTokenBundle,
   type DeviceTokenMintResponse,
-  type TokenRefreshResponse,
-  type WebSessionResult,
 } 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.
-     *
-     * @throws if the response matches neither arm of {@link webSessionResultSchema}.
-     */
-    async requestWebSession(): Promise<WebSessionResult> {
-      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.
-          { cache: false, skipAuth: true },
-        );
-        const parsed = safeParseContract(tokenRefreshResponseSchema, res);
-        if (!parsed) {
-          throw new Error('auth/refresh-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);
-      }
-    }
-
-    /**
-     * Zero-cookie mint (phase 2c). 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`.
-     *
-     * `skipAuth` (like {@link refreshWithToken}): this call carries no bearer, so
-     * a 401 must surface DIRECTLY — never trigger `HttpService`'s 401→refresh→
-     * retry dance (which would pointlessly rotate the refresh family). The cold
-     * boot reads the 401 body (`invalid_device_secret` vs `no_active_session`) to
-     * decide whether to drop the secret and fall back or resolve signed-out.
+     * `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 does not match {@link deviceTokenMintResponseSchema}.
      */
@@ -169,16 +57,5 @@ export function OxyServicesDeviceBootMixin<T extends typeof OxyServicesBase>(Bas
         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,31 +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,
-  DeviceTokenMintResponse,
-  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;
@@ -37,70 +17,6 @@ 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);
-      expect(makeRequest).toHaveBeenCalledWith(
-        'POST',
-        '/auth/refresh-token',
-        { refreshToken: 'refresh-abcdefghijkl' },
-        { 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 });
-    });
-  });
-
   describe('mintFromDeviceSecret', () => {
     const MINT: DeviceTokenMintResponse = {
       accessToken: 'access-minted',
@@ -115,7 +31,7 @@ describe('OxyServices.deviceBoot', () => {
       },
     };
 
-    it('POSTs deviceId + deviceSecret with skipAuth and returns the validated mint', async () => {
+    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);
@@ -127,7 +43,7 @@ describe('OxyServices.deviceBoot', () => {
       );
     });
 
-    it('throws on an unexpected response shape', async () => {
+    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();
     });
@@ -137,14 +53,11 @@ describe('OxyServices.deviceBoot', () => {
       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)

package/src/models/interfaces.ts

@@ -520,6 +520,16 @@ export interface ServiceAssetMetadata {
   mime: string;
   size: number;
   status: 'active' | 'trash';
+  /** Intrinsic width in pixels when variant/metadata extraction has run. */
+  width?: number;
+  /** Intrinsic height in pixels when variant/metadata extraction has run. */
+  height?: number;
+  /** Playback duration in seconds for video/audio assets. */
+  durationSec?: number;
+  /** Derived once from width/height at asset processing time. */
+  orientation?: 'portrait' | 'landscape' | 'square';
+  /** width / height, derived at asset processing time. */
+  aspectRatio?: number;
 }
 
 /**
@@ -544,6 +554,11 @@ export interface ServiceAssetMetadataBySha {
   size: number;
   status: 'active' | 'trash';
   url?: string;
+  width?: number;
+  height?: number;
+  durationSec?: number;
+  orientation?: 'portrait' | 'landscape' | 'square';
+  aspectRatio?: number;
 }
 
 /**