@oxyhq/core 5.5.0 → 6.0.0

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

@@ -0,0 +1,317 @@
+import type { OxyServices } from '../../OxyServices';
+import type { AuthTokenBundle, TokenRefreshResponse, WebSessionResult } from '@oxyhq/contracts';
+import type { SessionLoginResponse } from '../../models/session';
+import {
+  runSessionColdBoot,
+  createBrowserColdBootDom,
+  isSameApex,
+  BOOT_ATTEMPTED_KEY,
+  type ColdBootDom,
+} from '../coldBootV2';
+import { BOOT_STATE_SESSION_KEY } from '../deviceBootReturn';
+import { createMemoryAuthStateStore, type AuthStateStore } from '../../session/authStateStore';
+import { KeyManager } from '../../crypto/keyManager';
+
+const BUNDLE: AuthTokenBundle = {
+  sessionId: 'sess-boot',
+  accessToken: 'access-boot',
+  refreshToken: 'refresh-boot-abcdefghij',
+  expiresAt: '2030-01-01T00:00:00.000Z',
+  user: { id: 'user-boot', name: {} } as AuthTokenBundle['user'],
+};
+
+const ROTATED: TokenRefreshResponse = {
+  accessToken: 'access-rot',
+  refreshToken: 'refresh-rot-abcdefghij',
+  expiresAt: '2030-01-01T00:00:00.000Z',
+  sessionId: 'sess-rot',
+};
+
+interface OxyOverrides {
+  baseURL?: string;
+  exchangeBootCode?: OxyServices['exchangeBootCode'];
+  refreshWithToken?: OxyServices['refreshWithToken'];
+  signInWithSharedIdentity?: OxyServices['signInWithSharedIdentity'];
+  issueNativeDeviceToken?: OxyServices['issueNativeDeviceToken'];
+  requestWebSession?: OxyServices['requestWebSession'];
+}
+
+function makeOxy(overrides: OxyOverrides = {}): { oxy: OxyServices; setTokens: jest.Mock } {
+  const setTokens = jest.fn();
+  const oxy = {
+    getBaseURL: () => overrides.baseURL ?? 'https://api.oxy.so',
+    setTokens,
+    exchangeBootCode: overrides.exchangeBootCode ?? (async () => BUNDLE),
+    refreshWithToken: overrides.refreshWithToken ?? (async () => ROTATED),
+    signInWithSharedIdentity: overrides.signInWithSharedIdentity ?? (async () => null),
+    issueNativeDeviceToken: overrides.issueNativeDeviceToken ?? (async () => 'native-device-token'),
+    requestWebSession:
+      overrides.requestWebSession
+      ?? (async () => ({ reason: 'no_session', deviceToken: 'dt-web' }) as WebSessionResult),
+    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 };
+}
+
+interface DomHandle {
+  dom: ColdBootDom;
+  navigate: jest.Mock;
+  strip: jest.Mock;
+  session: Map<string, string>;
+  local: Map<string, string>;
+}
+
+function makeDom(opts: { hash?: string; hostname?: string; sessionState?: string; attempted?: boolean } = {}): DomHandle {
+  const session = new Map<string, string>();
+  const local = new Map<string, string>();
+  if (opts.sessionState !== undefined) session.set(BOOT_STATE_SESSION_KEY, opts.sessionState);
+  if (opts.attempted) local.set(BOOT_ATTEMPTED_KEY, '1');
+  const navigate = jest.fn();
+  const strip = jest.fn();
+  const dom: ColdBootDom = {
+    getHash: () => opts.hash ?? '',
+    stripFragment: strip,
+    getSessionItem: (k) => session.get(k) ?? null,
+    setSessionItem: (k, v) => {
+      session.set(k, v);
+    },
+    removeSessionItem: (k) => {
+      session.delete(k);
+    },
+    getLocalItem: (k) => local.get(k) ?? null,
+    setLocalItem: (k, v) => {
+      local.set(k, v);
+    },
+    getLocationHostname: () => opts.hostname ?? 'accounts.oxy.so',
+    getReturnToHref: () => 'https://accounts.oxy.so/home',
+    navigate,
+    randomState: () => 'state-fixed-1234',
+  };
+  return { dom, navigate, strip, session, local };
+}
+
+const WEB = { isWeb: true, isNative: false };
+const NATIVE = { isWeb: false, isNative: true };
+
+describe('isSameApex', () => {
+  it('groups by registrable domain', () => {
+    expect(isSameApex('accounts.oxy.so', 'api.oxy.so')).toBe(true);
+    expect(isSameApex('oxy.so', 'api.oxy.so')).toBe(true);
+    expect(isSameApex('app.mention.earth', 'api.oxy.so')).toBe(false);
+    expect(isSameApex('homiio.com', 'api.oxy.so')).toBe(false);
+  });
+
+  it('does NOT collapse distinct IPv4 hosts that share trailing octets', () => {
+    // The last-2-labels heuristic would map both to "1.1" — must be exact.
+    expect(isSameApex('192.168.1.1', '10.0.1.1')).toBe(false);
+    expect(isSameApex('192.168.1.10', '192.168.1.5')).toBe(false);
+    expect(isSameApex('192.168.1.5', '192.168.1.5')).toBe(true);
+  });
+
+  it('requires exact equality for single-label / IPv6 / localhost hosts', () => {
+    expect(isSameApex('localhost', 'localhost')).toBe(true);
+    expect(isSameApex('localhost', 'api.oxy.so')).toBe(false);
+    expect(isSameApex('::1', '::1')).toBe(true);
+    expect(isSameApex('fe80::1', 'fe80::2')).toBe(false);
+  });
+});
+
+describe('runSessionColdBoot — step ordering', () => {
+  it('stored-tokens warm-plants a still-valid access token before any hop', async () => {
+    const store = createMemoryAuthStateStore();
+    await store.save({
+      sessionId: 'sess-warm',
+      refreshToken: 'r-abcdefghij',
+      userId: 'user-warm',
+      accessToken: 'warm-token',
+      expiresAt: new Date(Date.now() + 3_600_000).toISOString(),
+    });
+    const { oxy, setTokens } = makeOxy();
+    const requestWebSession = jest.spyOn(oxy, 'requestWebSession');
+    const onSession = jest.fn();
+
+    const outcome = await runSessionColdBoot({
+      oxy, store, platform: WEB, dom: makeDom().dom, onSession,
+    });
+
+    expect(outcome).toEqual({ kind: 'session', via: 'stored-tokens', session: expect.any(Object) });
+    expect(setTokens).toHaveBeenCalledWith('warm-token');
+    expect(onSession).toHaveBeenCalledWith(expect.objectContaining({ userId: 'user-warm', via: 'stored-tokens' }));
+    expect(requestWebSession).not.toHaveBeenCalled();
+  });
+
+  it('stored-tokens rotates when the warm token is absent/expired', async () => {
+    const store = createMemoryAuthStateStore();
+    await store.save({ sessionId: 'sess-old', refreshToken: 'r-abcdefghij', userId: 'user-1' });
+    const { oxy, setTokens } = makeOxy();
+
+    const outcome = await runSessionColdBoot({ oxy, store, platform: WEB, dom: makeDom().dom });
+
+    expect(outcome.kind).toBe('session');
+    expect(setTokens).toHaveBeenCalledWith('access-rot');
+    expect(await store.load()).toMatchObject({ sessionId: 'sess-rot', refreshToken: 'refresh-rot-abcdefghij' });
+  });
+
+  it('bootstrap-return wins over later steps when a valid fragment is present', async () => {
+    const store = createMemoryAuthStateStore();
+    // A base64url fragment carrying reason:session + matching state.
+    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 { oxy, setTokens } = makeOxy();
+    const onSession = jest.fn();
+
+    const outcome = await runSessionColdBoot({
+      oxy, store, platform: WEB, dom: domHandle.dom, onSession,
+    });
+
+    expect(outcome).toEqual({ kind: 'session', via: 'bootstrap-return', session: expect.any(Object) });
+    expect(domHandle.strip).toHaveBeenCalled();
+    expect(setTokens).toHaveBeenCalledWith('access-boot');
+    expect(onSession).toHaveBeenCalledWith(expect.objectContaining({ via: 'bootstrap-return' }));
+  });
+});
+
+describe('runSessionColdBoot — bootstrap-hop (web)', () => {
+  it('same-apex: resolves a session via the inline web-session fetch (no navigation)', async () => {
+    const store = createMemoryAuthStateStore();
+    // The EXACT post-unwrap server shape (PR #526): a reason-`session` envelope
+    // nesting the bundle under `session` plus the rotated deviceToken.
+    const sessionEnvelope: WebSessionResult = { reason: 'session', session: BUNDLE, deviceToken: 'dt-rotated' };
+    const requestWebSession = jest.fn(async () => sessionEnvelope);
+    const { oxy, setTokens } = makeOxy({ requestWebSession });
+    const domHandle = makeDom({ hostname: 'accounts.oxy.so' });
+
+    const outcome = await runSessionColdBoot({ oxy, store, platform: WEB, dom: domHandle.dom });
+
+    expect(outcome).toEqual({ kind: 'session', via: 'bootstrap-hop', session: expect.any(Object) });
+    expect(requestWebSession).toHaveBeenCalledTimes(1);
+    expect(setTokens).toHaveBeenCalledWith('access-boot');
+    expect(domHandle.navigate).not.toHaveBeenCalled();
+    expect(await store.load()).toMatchObject({ sessionId: 'sess-boot', refreshToken: 'refresh-boot-abcdefghij' });
+    // deviceToken from the SAME envelope is persisted on the session arm too.
+    expect(await store.loadDeviceToken()).toBe('dt-rotated');
+  });
+
+  it('same-apex: signed-out device persists the deviceToken and reports signed out', async () => {
+    const store = createMemoryAuthStateStore();
+    const requestWebSession = jest.fn(async () => ({ reason: 'no_session', deviceToken: 'dt-web' }) as WebSessionResult);
+    const { oxy } = makeOxy({ requestWebSession });
+    const domHandle = makeDom({ hostname: 'accounts.oxy.so' });
+    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');
+    expect(await store.loadDeviceToken()).toBe('dt-web');
+    expect(domHandle.navigate).not.toHaveBeenCalled();
+  });
+
+  it('cross-apex: navigates ONCE, stashing state + the attempted flag', async () => {
+    const store = createMemoryAuthStateStore();
+    const { oxy } = makeOxy();
+    const domHandle = makeDom({ hostname: 'app.mention.earth' });
+    const onSignedOut = jest.fn();
+    const onSession = jest.fn();
+
+    await runSessionColdBoot({ oxy, store, platform: WEB, dom: domHandle.dom, onSignedOut, onSession });
+
+    expect(domHandle.navigate).toHaveBeenCalledTimes(1);
+    expect(domHandle.navigate).toHaveBeenCalledWith(expect.stringContaining('/auth/device/bootstrap?return_to='));
+    expect(domHandle.session.get(BOOT_STATE_SESSION_KEY)).toBe('state-fixed-1234');
+    expect(domHandle.local.get(BOOT_ATTEMPTED_KEY)).toBe('1');
+    // Navigating away — neither callback fires (no signed-out flash).
+    expect(onSignedOut).not.toHaveBeenCalled();
+    expect(onSession).not.toHaveBeenCalled();
+  });
+
+  it('cross-apex: NEVER navigates a second time once the attempted flag is set', async () => {
+    const store = createMemoryAuthStateStore();
+    const { oxy } = makeOxy();
+    const domHandle = makeDom({ hostname: 'app.mention.earth', attempted: true });
+    const onSignedOut = jest.fn();
+
+    const outcome = await runSessionColdBoot({ oxy, store, platform: WEB, dom: domHandle.dom, onSignedOut });
+
+    expect(domHandle.navigate).not.toHaveBeenCalled();
+    expect(outcome).toEqual({ kind: 'unauthenticated' });
+    expect(onSignedOut).toHaveBeenCalledWith('no_session');
+  });
+});
+
+describe('runSessionColdBoot — native shared-key', () => {
+  afterEach(() => jest.restoreAllMocks());
+
+  it('re-mints via shared identity and issues + mirrors a deviceToken the first time', async () => {
+    const store = createMemoryAuthStateStore();
+    const sharedSession: SessionLoginResponse = {
+      sessionId: 'sess-shared',
+      deviceId: 'dev-1',
+      expiresAt: '2030-01-01T00:00:00.000Z',
+      user: { id: 'user-shared', username: 'u', name: {}, avatar: undefined },
+      accessToken: 'access-shared',
+    };
+    const issueNativeDeviceToken = jest.fn(async () => 'fresh-device-token');
+    const { oxy } = makeOxy({
+      signInWithSharedIdentity: async () => sharedSession,
+      issueNativeDeviceToken,
+    });
+    const getShared = jest.spyOn(KeyManager, 'getSharedDeviceToken').mockResolvedValue(null);
+    const setShared = jest.spyOn(KeyManager, 'setSharedDeviceToken').mockResolvedValue(undefined);
+    const requestWebSession = jest.spyOn(oxy, 'requestWebSession');
+
+    const outcome = await runSessionColdBoot({ oxy, store, platform: NATIVE, dom: makeDom().dom });
+
+    expect(outcome).toEqual({ kind: 'session', via: 'shared-key-signin', session: expect.any(Object) });
+    expect(getShared).toHaveBeenCalled();
+    expect(issueNativeDeviceToken).toHaveBeenCalled();
+    expect(setShared).toHaveBeenCalledWith('fresh-device-token');
+    expect(await store.loadDeviceToken()).toBe('fresh-device-token');
+    // bootstrap-hop is web-only — never runs on native.
+    expect(requestWebSession).not.toHaveBeenCalled();
+  });
+
+  it('skips device-token issuance when the shared token already exists', async () => {
+    const store = createMemoryAuthStateStore();
+    const issueNativeDeviceToken = jest.fn(async () => 'unused');
+    const { oxy } = makeOxy({
+      signInWithSharedIdentity: async () => ({
+        sessionId: 'sess-shared',
+        deviceId: 'dev-1',
+        expiresAt: '2030-01-01T00:00:00.000Z',
+        user: { id: 'user-shared', username: 'u', name: {}, avatar: undefined },
+        accessToken: 'access-shared',
+      }),
+      issueNativeDeviceToken,
+    });
+    jest.spyOn(KeyManager, 'getSharedDeviceToken').mockResolvedValue('already-there');
+
+    await runSessionColdBoot({ oxy, store, platform: NATIVE, dom: makeDom().dom });
+
+    expect(issueNativeDeviceToken).not.toHaveBeenCalled();
+  });
+});
+
+describe('createBrowserColdBootDom', () => {
+  it('returns neutral values under the jest node environment (no window)', () => {
+    const dom = createBrowserColdBootDom();
+    expect(dom.getHash()).toBe('');
+    expect(dom.getLocationHostname()).toBeNull();
+    expect(dom.getSessionItem('x')).toBeNull();
+    expect(() => dom.stripFragment()).not.toThrow();
+    expect(() => dom.navigate('https://x')).not.toThrow();
+    expect(dom.randomState()).toMatch(/^[0-9a-f]+$/);
+  });
+});

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

@@ -0,0 +1,158 @@
+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('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');
+  });
+});