@oxyhq/core 8.1.0 → 9.1.0

package/dist/types/boot/deviceBootReturn.d.ts

@@ -1,83 +0,0 @@
-/**
- * Device-boot return-fragment consumption (web cross-apex hop).
- *
- * After the top-level `GET /auth/device/bootstrap` hop, the API 303s back to the
- * RP with a `#oxy_boot=<base64url(JSON)>` fragment. This module parses and
- * consumes it: it strips the fragment from the URL FIRST (so the opaque
- * deviceToken / code never linger in history or a `Referer`), verifies the
- * echoed CSRF `state` against the value the initiator stashed in
- * `sessionStorage`, persists the deviceToken, and — when a session resolved —
- * exchanges the single-use `code` for a token bundle.
- *
- * Pure/injectable: all DOM access (hash, `history.replaceState`,
- * `sessionStorage`) is passed in as callbacks so the logic is unit-testable
- * under the jest `node` environment and reusable by `coldBootV2`.
- *
- * ESM-safe (no `require()`).
- */
-import { type AuthTokenBundle, type DeviceBootFragment, type DeviceBootReason } from '@oxyhq/contracts';
-import type { AuthStateStore } from '../session/authStateStore';
-/** The `#oxy_boot=` fragment parameter name the API appends on the return hop. */
-export declare const BOOT_FRAGMENT_PARAM = "oxy_boot";
-/**
- * `sessionStorage` key under which the bootstrap-hop initiator stashes the
- * 128-bit CSRF `state` before navigating, and which the return step reads back
- * (single-use).
- */
-export declare const BOOT_STATE_SESSION_KEY = "oxy.boot.state";
-/** True when a location hash carries the `oxy_boot` return fragment. */
-export declare function hashHasBootFragment(hash: string): boolean;
-/**
- * Extract + decode + validate the `oxy_boot` fragment from a location hash.
- * Returns the parsed {@link DeviceBootFragment}, or `null` when the parameter
- * is absent, not valid base64url, not JSON, or fails the contract schema.
- */
-export declare function parseDeviceBootFragment(hash: string): DeviceBootFragment | null;
-/** The winning session shape a cold-boot step reports. */
-export interface DeviceBootSession {
-    sessionId: string;
-    userId: string;
-    accessToken: string;
-}
-/** Outcome of {@link consumeDeviceBootReturn}. */
-export type DeviceBootReturnOutcome = {
-    kind: 'none';
-} | {
-    kind: 'state-mismatch';
-} | {
-    kind: 'session';
-    session: DeviceBootSession;
-} | {
-    kind: 'no-session';
-    reason: DeviceBootReason;
-};
-export interface ConsumeDeviceBootReturnDeps {
-    /** The current location hash (e.g. `window.location.hash`). */
-    hash: string;
-    /** Strip the fragment from the URL (e.g. `history.replaceState`). */
-    stripFragment: () => void;
-    /** Read the expected CSRF state (e.g. `sessionStorage.getItem(BOOT_STATE_SESSION_KEY)`). */
-    readExpectedState: () => string | null;
-    /** Clear the expected CSRF state (single-use). */
-    clearExpectedState: () => void;
-    store: AuthStateStore;
-    /** Exchange the single-use boot code for a token bundle (`oxy.exchangeBootCode`). */
-    exchangeBootCode: (code: string) => Promise<AuthTokenBundle>;
-    /** Plant the freshly-minted access token on the owner client (`oxy.setTokens`). */
-    plantAccessToken: (accessToken: string) => void;
-}
-/**
- * Consume the device-boot return fragment.
- *
- * Order is load-bearing:
- *   1. If no fragment is present, return `none` (no URL mutation).
- *   2. STRIP the fragment from the URL immediately — before validation or any
- *      network — so the deviceToken/code never persist in history/referrer.
- *   3. Verify the echoed `state` against the stashed (single-use) value; a
- *      mismatch returns `state-mismatch` without persisting or exchanging.
- *   4. Persist the deviceToken (survives sign-out).
- *   5. If a session resolved (`reason:'session'` + `code`), exchange the code,
- *      persist the rotated session, plant the token, and return `session`.
- *      Otherwise return `no-session` with the reason.
- */
-export declare function consumeDeviceBootReturn(deps: ConsumeDeviceBootReturnDeps): Promise<DeviceBootReturnOutcome>;

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

@@ -1,190 +0,0 @@
-import type { AuthTokenBundle } from '@oxyhq/contracts';
-import {
-  parseDeviceBootFragment,
-  hashHasBootFragment,
-  consumeDeviceBootReturn,
-  type ConsumeDeviceBootReturnDeps,
-} from '../deviceBootReturn';
-import { createMemoryAuthStateStore } from '../../session/authStateStore';
-
-const STATE = 'st-1234567890';
-const CODE = 'c'.repeat(24);
-const DEVICE_TOKEN = 'd'.repeat(24);
-
-// A loose record (fed to `encodeHash(unknown)` and validated by the schema) so
-// tests can build the session arm plus invalid variants (missing/extra `code`,
-// `v: 2`) without fighting the discriminated-union type.
-function fragmentObject(overrides: Record<string, unknown> = {}): Record<string, unknown> {
-  return { v: 1, state: STATE, reason: 'session', code: CODE, deviceToken: DEVICE_TOKEN, ...overrides };
-}
-
-function encodeHash(obj: unknown): string {
-  const b64 = Buffer.from(JSON.stringify(obj), 'utf-8')
-    .toString('base64')
-    .replace(/\+/g, '-')
-    .replace(/\//g, '_')
-    .replace(/=+$/, '');
-  return `#oxy_boot=${b64}`;
-}
-
-const BUNDLE: AuthTokenBundle = {
-  sessionId: 'sess-1',
-  accessToken: 'access-jwt',
-  refreshToken: 'refresh-abcdefghijklmnop',
-  expiresAt: '2030-01-01T00:00:00.000Z',
-  user: { id: 'user-1', name: {} } as AuthTokenBundle['user'],
-};
-
-/** Build the injectable deps around a memory store, recording call order. */
-function makeDeps(
-  hash: string,
-  overrides: Partial<ConsumeDeviceBootReturnDeps> & { expectedState?: string | null } = {},
-): { deps: ConsumeDeviceBootReturnDeps; calls: string[]; store: ReturnType<typeof createMemoryAuthStateStore> } {
-  const calls: string[] = [];
-  const store = createMemoryAuthStateStore();
-  const deps: ConsumeDeviceBootReturnDeps = {
-    hash,
-    stripFragment: () => calls.push('strip'),
-    readExpectedState: () => (overrides.expectedState !== undefined ? overrides.expectedState : STATE),
-    clearExpectedState: () => calls.push('clearState'),
-    store,
-    exchangeBootCode: overrides.exchangeBootCode
-      ?? (async () => {
-        calls.push('exchange');
-        return BUNDLE;
-      }),
-    plantAccessToken: overrides.plantAccessToken ?? ((token) => calls.push(`plant:${token}`)),
-  };
-  return { deps, calls, store };
-}
-
-describe('parseDeviceBootFragment', () => {
-  it('parses a valid base64url fragment', () => {
-    expect(parseDeviceBootFragment(encodeHash(fragmentObject()))).toEqual(fragmentObject());
-  });
-
-  it('returns null when the parameter is absent', () => {
-    expect(parseDeviceBootFragment('#something=else')).toBeNull();
-    expect(parseDeviceBootFragment('')).toBeNull();
-  });
-
-  it('returns null for malformed base64 / non-JSON / wrong shape', () => {
-    expect(parseDeviceBootFragment('#oxy_boot=!!!not-base64!!!')).toBeNull();
-    expect(parseDeviceBootFragment(encodeHash({ nope: true }))).toBeNull();
-    // v must be the literal 1
-    expect(parseDeviceBootFragment(encodeHash(fragmentObject({ v: 2 })))).toBeNull();
-  });
-
-  it('returns null for a session fragment missing its code (discriminated union)', () => {
-    expect(parseDeviceBootFragment(encodeHash(fragmentObject({ code: undefined })))).toBeNull();
-  });
-});
-
-describe('hashHasBootFragment', () => {
-  it('detects the fragment regardless of position', () => {
-    expect(hashHasBootFragment('#oxy_boot=abc')).toBe(true);
-    expect(hashHasBootFragment('#x=1&oxy_boot=abc')).toBe(true);
-    expect(hashHasBootFragment('#other=1')).toBe(false);
-    expect(hashHasBootFragment('')).toBe(false);
-  });
-});
-
-describe('consumeDeviceBootReturn', () => {
-  it('returns none and does not touch the URL when no fragment is present', async () => {
-    const { deps, calls } = makeDeps('#unrelated=1');
-    expect(await consumeDeviceBootReturn(deps)).toEqual({ kind: 'none' });
-    expect(calls).not.toContain('strip');
-  });
-
-  it('strips the fragment BEFORE exchanging the code', async () => {
-    const { deps, calls } = makeDeps(encodeHash(fragmentObject()));
-    const outcome = await consumeDeviceBootReturn(deps);
-    expect(outcome.kind).toBe('session');
-    expect(calls.indexOf('strip')).toBeLessThan(calls.indexOf('exchange'));
-  });
-
-  it('resolves a session, persists it, and plants the token', async () => {
-    const { deps, store } = makeDeps(encodeHash(fragmentObject()));
-    const outcome = await consumeDeviceBootReturn(deps);
-    expect(outcome).toEqual({
-      kind: 'session',
-      session: { sessionId: 'sess-1', userId: 'user-1', accessToken: 'access-jwt' },
-    });
-    expect(await store.load()).toMatchObject({
-      sessionId: 'sess-1',
-      refreshToken: 'refresh-abcdefghijklmnop',
-      userId: 'user-1',
-      deviceToken: DEVICE_TOKEN,
-    });
-    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' });
-    expect(calls).toContain('strip');
-    expect(calls).not.toContain('exchange');
-    expect(await store.loadDeviceToken()).toBeNull();
-  });
-
-  it('rejects when there is no expected state stashed at all', async () => {
-    const { deps } = makeDeps(encodeHash(fragmentObject()), { expectedState: null });
-    expect(await consumeDeviceBootReturn(deps)).toEqual({ kind: 'state-mismatch' });
-  });
-
-  it('persists the deviceToken but returns no-session for a signed-out device', async () => {
-    const { deps, store, calls } = makeDeps(
-      encodeHash(fragmentObject({ reason: 'new_device', code: undefined })),
-    );
-    expect(await consumeDeviceBootReturn(deps)).toEqual({ kind: 'no-session', reason: 'new_device' });
-    expect(calls).not.toContain('exchange');
-    expect(await store.loadDeviceToken()).toBe(DEVICE_TOKEN);
-  });
-
-  it('returns no-session when the code exchange fails (burned/expired code)', async () => {
-    const { deps } = makeDeps(encodeHash(fragmentObject()), {
-      exchangeBootCode: async () => {
-        throw new Error('code already burned');
-      },
-    });
-    expect(await consumeDeviceBootReturn(deps)).toEqual({ kind: 'no-session', reason: 'no_session' });
-  });
-
-  it('strips even a malformed fragment and returns none', async () => {
-    const { deps, calls } = makeDeps('#oxy_boot=!!!malformed!!!');
-    expect(await consumeDeviceBootReturn(deps)).toEqual({ kind: 'none' });
-    expect(calls).toContain('strip');
-  });
-});

package/src/boot/deviceBootReturn.ts

@@ -1,210 +0,0 @@
-/**
- * Device-boot return-fragment consumption (web cross-apex hop).
- *
- * After the top-level `GET /auth/device/bootstrap` hop, the API 303s back to the
- * RP with a `#oxy_boot=<base64url(JSON)>` fragment. This module parses and
- * consumes it: it strips the fragment from the URL FIRST (so the opaque
- * deviceToken / code never linger in history or a `Referer`), verifies the
- * echoed CSRF `state` against the value the initiator stashed in
- * `sessionStorage`, persists the deviceToken, and — when a session resolved —
- * exchanges the single-use `code` for a token bundle.
- *
- * Pure/injectable: all DOM access (hash, `history.replaceState`,
- * `sessionStorage`) is passed in as callbacks so the logic is unit-testable
- * under the jest `node` environment and reusable by `coldBootV2`.
- *
- * ESM-safe (no `require()`).
- */
-import {
-  deviceBootFragmentSchema,
-  resolveUserId,
-  safeParseContract,
-  type AuthTokenBundle,
-  type DeviceBootFragment,
-  type DeviceBootReason,
-} from '@oxyhq/contracts';
-import type { AuthStateStore, PersistedAuthState } from '../session/authStateStore';
-
-/** The `#oxy_boot=` fragment parameter name the API appends on the return hop. */
-export const BOOT_FRAGMENT_PARAM = 'oxy_boot';
-
-/**
- * `sessionStorage` key under which the bootstrap-hop initiator stashes the
- * 128-bit CSRF `state` before navigating, and which the return step reads back
- * (single-use).
- */
-export const BOOT_STATE_SESSION_KEY = 'oxy.boot.state';
-
-/**
- * Decode a base64url string to UTF-8 text, or `null` on any malformed input.
- * Handles both web (`atob` + `TextDecoder`) and Node (`Buffer`) without a
- * `require()` — the ESM build stays clean.
- */
-function base64UrlDecode(input: string): string | null {
-  try {
-    let b64 = input.replace(/-/g, '+').replace(/_/g, '/');
-    while (b64.length % 4 !== 0) {
-      b64 += '=';
-    }
-    if (typeof atob === 'function') {
-      const binary = atob(b64);
-      const bytes = Uint8Array.from(binary, (c) => c.charCodeAt(0));
-      if (typeof TextDecoder !== 'undefined') {
-        return new TextDecoder().decode(bytes);
-      }
-      return binary;
-    }
-    if (typeof Buffer !== 'undefined') {
-      return Buffer.from(b64, 'base64').toString('utf-8');
-    }
-    return null;
-  } catch {
-    return null;
-  }
-}
-
-/** True when a location hash carries the `oxy_boot` return fragment. */
-export function hashHasBootFragment(hash: string): boolean {
-  return new RegExp(`(^|[#&])${BOOT_FRAGMENT_PARAM}=`).test(hash);
-}
-
-/**
- * Extract + decode + validate the `oxy_boot` fragment from a location hash.
- * Returns the parsed {@link DeviceBootFragment}, or `null` when the parameter
- * is absent, not valid base64url, not JSON, or fails the contract schema.
- */
-export function parseDeviceBootFragment(hash: string): DeviceBootFragment | null {
-  const withoutHash = hash.startsWith('#') ? hash.slice(1) : hash;
-  const params = new URLSearchParams(withoutHash);
-  const raw = params.get(BOOT_FRAGMENT_PARAM);
-  if (!raw) {
-    return null;
-  }
-  const json = base64UrlDecode(raw);
-  if (!json) {
-    return null;
-  }
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(json);
-  } catch {
-    return null;
-  }
-  return safeParseContract(deviceBootFragmentSchema, parsed);
-}
-
-/** The winning session shape a cold-boot step reports. */
-export interface DeviceBootSession {
-  sessionId: string;
-  userId: string;
-  accessToken: string;
-}
-
-/** Outcome of {@link consumeDeviceBootReturn}. */
-export type DeviceBootReturnOutcome =
-  | { kind: 'none' }
-  | { kind: 'state-mismatch' }
-  | { kind: 'session'; session: DeviceBootSession }
-  | { kind: 'no-session'; reason: DeviceBootReason };
-
-export interface ConsumeDeviceBootReturnDeps {
-  /** The current location hash (e.g. `window.location.hash`). */
-  hash: string;
-  /** Strip the fragment from the URL (e.g. `history.replaceState`). */
-  stripFragment: () => void;
-  /** Read the expected CSRF state (e.g. `sessionStorage.getItem(BOOT_STATE_SESSION_KEY)`). */
-  readExpectedState: () => string | null;
-  /** Clear the expected CSRF state (single-use). */
-  clearExpectedState: () => void;
-  store: AuthStateStore;
-  /** Exchange the single-use boot code for a token bundle (`oxy.exchangeBootCode`). */
-  exchangeBootCode: (code: string) => Promise<AuthTokenBundle>;
-  /** Plant the freshly-minted access token on the owner client (`oxy.setTokens`). */
-  plantAccessToken: (accessToken: string) => void;
-}
-
-/**
- * Consume the device-boot return fragment.
- *
- * Order is load-bearing:
- *   1. If no fragment is present, return `none` (no URL mutation).
- *   2. STRIP the fragment from the URL immediately — before validation or any
- *      network — so the deviceToken/code never persist in history/referrer.
- *   3. Verify the echoed `state` against the stashed (single-use) value; a
- *      mismatch returns `state-mismatch` without persisting or exchanging.
- *   4. Persist the deviceToken (survives sign-out).
- *   5. If a session resolved (`reason:'session'` + `code`), exchange the code,
- *      persist the rotated session, plant the token, and return `session`.
- *      Otherwise return `no-session` with the reason.
- */
-export async function consumeDeviceBootReturn(
-  deps: ConsumeDeviceBootReturnDeps,
-): Promise<DeviceBootReturnOutcome> {
-  if (!hashHasBootFragment(deps.hash)) {
-    return { kind: 'none' };
-  }
-
-  // Strip FIRST — even a forged/malformed fragment must not linger in the URL.
-  deps.stripFragment();
-
-  const fragment = parseDeviceBootFragment(deps.hash);
-  if (!fragment) {
-    return { kind: 'none' };
-  }
-
-  const expected = deps.readExpectedState();
-  deps.clearExpectedState();
-  if (!expected || expected !== fragment.state) {
-    return { kind: 'state-mismatch' };
-  }
-
-  await deps.store.saveDeviceToken(fragment.deviceToken);
-
-  // `code` is guaranteed present on the `session` arm (the contract's
-  // discriminated union requires it; a session fragment without a code fails to
-  // parse and never reaches here).
-  if (fragment.reason === 'session') {
-    try {
-      const bundle = await deps.exchangeBootCode(fragment.code);
-      const userId = resolveUserId(bundle.user);
-      if (!userId) {
-        return { kind: 'no-session', reason: 'no_session' };
-      }
-      const next: PersistedAuthState = {
-        sessionId: bundle.sessionId,
-        refreshToken: bundle.refreshToken,
-        userId,
-        deviceToken: fragment.deviceToken,
-        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 {
-        kind: 'session',
-        session: { sessionId: bundle.sessionId, userId, accessToken: bundle.accessToken },
-      };
-    } catch {
-      // The code burned/expired between hop and exchange — resolve signed-out
-      // rather than throwing (the once-ever hop already fired; do not retry).
-      return { kind: 'no-session', reason: 'no_session' };
-    }
-  }
-
-  return { kind: 'no-session', reason: fragment.reason };
-}

package/src/crypto/__tests__/sharedDeviceToken.test.ts

@@ -1,24 +0,0 @@
-/**
- * Shared device-token contract on web. Under the jest `node` environment
- * `getPlatformOS()` resolves to `'web'`, so the shared-keychain device-token
- * methods are no-ops (web persists its deviceToken in the per-origin
- * AuthStateStore instead of a keychain). The native keychain plumbing is
- * exercised via spies in the coldBootV2 suite.
- */
-import { KeyManager } from '../keyManager';
-
-describe('KeyManager shared device token (web)', () => {
-  it('getSharedDeviceToken returns null on web', async () => {
-    expect(await KeyManager.getSharedDeviceToken()).toBeNull();
-  });
-
-  it('setSharedDeviceToken is a no-op that does not throw on web', async () => {
-    await expect(KeyManager.setSharedDeviceToken('dt-web')).resolves.toBeUndefined();
-    // Still null — nothing was persisted on web.
-    expect(await KeyManager.getSharedDeviceToken()).toBeNull();
-  });
-
-  it('clearSharedDeviceToken is a no-op that does not throw on web', async () => {
-    await expect(KeyManager.clearSharedDeviceToken()).resolves.toBeUndefined();
-  });
-});