@oxyhq/core 8.0.0 → 8.1.0

package/dist/types/mixins/OxyServices.deviceBoot.d.ts

@@ -15,7 +15,7 @@
  * and `setTokens`, so the same network primitive can be reused from either
  * without double-planting.
  */
-import { type AuthTokenBundle, type TokenRefreshResponse, type WebSessionResult } from '@oxyhq/contracts';
+import { type AuthTokenBundle, type DeviceTokenMintResponse, type TokenRefreshResponse, type WebSessionResult } from '@oxyhq/contracts';
 import type { OxyServicesBase } from '../OxyServices.base';
 export declare function OxyServicesDeviceBootMixin<T extends typeof OxyServicesBase>(Base: T): {
     new (...args: any[]): {
@@ -51,6 +51,22 @@ export declare function OxyServicesDeviceBootMixin<T extends typeof OxyServicesB
          * @throws if the response does not match {@link deviceTokenIssueResponseSchema}.
          */
         issueNativeDeviceToken(): Promise<string>;
+        /**
+         * 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.
+         *
+         * @throws if the response does not match {@link deviceTokenMintResponseSchema}.
+         */
+        mintFromDeviceSecret(deviceId: string, deviceSecret: string): Promise<DeviceTokenMintResponse>;
         /**
          * 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

package/dist/types/session/authStateStore.d.ts

@@ -38,6 +38,26 @@ export interface PersistedAuthState {
     refreshToken: string;
     userId: string;
     deviceToken?: string;
+    /**
+     * The stable device identifier this session is bound to (phase 2c —
+     * zero-cookie transport). Persisted alongside {@link deviceSecret} because the
+     * `POST /session/device/token` mint presents BOTH — the secret is the proof,
+     * the deviceId selects the device doc. Sourced from the lanes that carry it
+     * (password login / 2FA / QR claim / challenge verify); the cookie-bootstrap
+     * lanes (`AuthTokenBundle`) omit it and preserve any prior value. Additive: a
+     * blob without it simply never takes the mint lane and falls back to the
+     * refresh family.
+     */
+    deviceId?: string;
+    /**
+     * The rotating device secret (phase 2c — zero-cookie transport). Possession of
+     * it mints a short access token for the device's active account via
+     * `POST /session/device/token`, replacing the cookie lane. Rotated in-use: the
+     * mint returns `nextDeviceSecret`, which the cold boot persists BEFORE planting
+     * the minted access token (multi-tab anti-loss). Additive and optional — same
+     * XSS risk profile as the already-persisted `refreshToken`.
+     */
+    deviceSecret?: string;
     /** Optional warm-boot access token (short-lived; see interface docs). */
     accessToken?: string;
     /** Optional warm-boot access-token expiry, ISO-8601. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/core",
-  "version": "8.0.0",
+  "version": "8.1.0",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -94,7 +94,7 @@
     }
   },
   "dependencies": {
-    "@oxyhq/contracts": "^0.11.0",
+    "@oxyhq/contracts": "^0.12.0",
     "@oxyhq/protocol": "^0.1.2",
     "bip39": "^3.1.0",
     "buffer": "^6.0.3",

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/mixins/OxyServices.deviceBoot.ts

@@ -19,9 +19,11 @@ import {
   authTokenBundleSchema,
   tokenRefreshResponseSchema,
   deviceTokenIssueResponseSchema,
+  deviceTokenMintResponseSchema,
   webSessionResultSchema,
   safeParseContract,
   type AuthTokenBundle,
+  type DeviceTokenMintResponse,
   type TokenRefreshResponse,
   type WebSessionResult,
 } from '@oxyhq/contracts';
@@ -132,6 +134,42 @@ export function OxyServicesDeviceBootMixin<T extends typeof OxyServicesBase>(Bas
       }
     }
 
+    /**
+     * 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.
+     *
+     * @throws if the response does not match {@link deviceTokenMintResponseSchema}.
+     */
+    async mintFromDeviceSecret(
+      deviceId: string,
+      deviceSecret: string,
+    ): Promise<DeviceTokenMintResponse> {
+      try {
+        const res = await this.makeRequest<unknown>(
+          'POST',
+          '/session/device/token',
+          { deviceId, deviceSecret },
+          { cache: false, skipAuth: true },
+        );
+        const parsed = safeParseContract(deviceTokenMintResponseSchema, res);
+        if (!parsed) {
+          throw new Error('session/device/token returned an unexpected response shape');
+        }
+        return parsed;
+      } 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

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

@@ -3,7 +3,12 @@
  * and asserts each method's route/shape, contract validation, and the
  * `skipAuth` flag on the refresh call.
  */
-import type { AuthTokenBundle, TokenRefreshResponse, WebSessionResult } from '@oxyhq/contracts';
+import type {
+  AuthTokenBundle,
+  DeviceTokenMintResponse,
+  TokenRefreshResponse,
+  WebSessionResult,
+} from '@oxyhq/contracts';
 import { OxyServices } from '../../OxyServices';
 
 const BUNDLE: AuthTokenBundle = {
@@ -96,6 +101,44 @@ describe('OxyServices.deviceBoot', () => {
     });
   });
 
+  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 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',
+        '/session/device/token',
+        { deviceId: 'dev-1', deviceSecret: 'ds-current-secret' },
+        { cache: false, skipAuth: true },
+      );
+    });
+
+    it('throws on an unexpected response shape', 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');