@oxy.so/core 1.0.0

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

@@ -0,0 +1,130 @@
+/**
+ * `verifyChallenge` token-planting regression tests.
+ *
+ * `OxyServices.verifyChallenge()` returns a `SessionLoginResponse` carrying the
+ * first `accessToken` minted by `POST /auth/verify`. It must
+ * plant that token internally — mirroring its sibling `claimSessionByToken` —
+ * so callers (e.g. @oxy.so/services' `useAuthOperations.performSignIn`) end up
+ * with an authenticated client. Session IDs are not public token-minting
+ * credentials, so the initial bearer must come from the verify response body.
+ *
+ * These tests stub `makeRequest` so the planting logic is exercised end-to-end
+ * against a real OxyServices instance, with token state observed via the public
+ * `hasValidToken()` / `getAccessToken()` surface.
+ */
+
+import { OxyServices } from '../../OxyServices';
+
+interface VerifyResponse {
+  sessionId: string;
+  deviceId: string;
+  expiresAt: string;
+  accessToken?: string;
+  user: { id: string; username: string };
+}
+
+function makeOxy(): OxyServices {
+  return new OxyServices({ baseURL: 'https://api.oxy.so' });
+}
+
+describe('OxyServices.verifyChallenge token planting', () => {
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  it('plants the access token from the /auth/verify response body', async () => {
+    const oxy = makeOxy();
+    expect(oxy.hasValidToken()).toBe(false);
+
+    jest.spyOn(oxy, 'makeRequest').mockImplementation(async (_method, url) => {
+      if (url === '/auth/verify') {
+        return {
+          sessionId: 'sess_1',
+          deviceId: 'dev_1',
+          expiresAt: new Date(Date.now() + 60_000).toISOString(),
+          accessToken: 'access_verify',
+          user: { id: 'user_1', username: 'tester' },
+        } as never;
+      }
+      throw new Error(`unexpected request to ${url}`);
+    });
+
+    const session = await oxy.verifyChallenge('pubkey', 'challenge', 'sig', 123, 'Device', 'fp');
+
+    // Response still carries the access token for callers that want it.
+    expect(session.accessToken).toBe('access_verify');
+    // ...and it is now planted on the client so subsequent requests are
+    // authenticated without a second round-trip.
+    expect(oxy.hasValidToken()).toBe(true);
+    expect(oxy.getAccessToken()).toBe('access_verify');
+  });
+
+  it('plants the access token when no refresh token is present', async () => {
+    const oxy = makeOxy();
+
+    jest.spyOn(oxy, 'makeRequest').mockImplementation(async (_method, url) => {
+      if (url === '/auth/verify') {
+        return {
+          sessionId: 'sess_2',
+          deviceId: 'dev_2',
+          expiresAt: new Date(Date.now() + 60_000).toISOString(),
+          accessToken: 'access_only',
+          user: { id: 'user_2', username: 'tester2' },
+        } as never;
+      }
+      throw new Error(`unexpected request to ${url}`);
+    });
+
+    const session = await oxy.verifyChallenge('pubkey', 'challenge', 'sig', 456);
+
+    expect(session.accessToken).toBe('access_only');
+    expect(oxy.hasValidToken()).toBe(true);
+    expect(oxy.getAccessToken()).toBe('access_only');
+  });
+
+  it('does NOT plant (and stays unauthenticated) when the response carries no access token', async () => {
+    const oxy = makeOxy();
+
+    jest.spyOn(oxy, 'makeRequest').mockImplementation(async (_method, url) => {
+      if (url === '/auth/verify') {
+        // Token-less new identity (onboarding) — no access token in the body.
+        return {
+          sessionId: 'sess_3',
+          deviceId: 'dev_3',
+          expiresAt: new Date(Date.now() + 60_000).toISOString(),
+          user: { id: 'user_3', username: 'tester3' },
+        } as VerifyResponse as never;
+      }
+      throw new Error(`unexpected request to ${url}`);
+    });
+
+    const session = await oxy.verifyChallenge('pubkey', 'challenge', 'sig', 789);
+
+    expect(session.accessToken).toBeUndefined();
+    // No token to plant — the client stays unauthenticated. Crucially the
+    // method does NOT reach for the bearer-protected session-token endpoint.
+    expect(oxy.hasValidToken()).toBe(false);
+  });
+
+  it('matches claimSessionByToken: both plant access tokens via the same path', async () => {
+    const oxy = makeOxy();
+
+    jest.spyOn(oxy, 'makeRequest').mockImplementation(async (_method, url) => {
+      if (url === '/auth/session/claim') {
+        return {
+          accessToken: 'access_claim',
+          sessionId: 'sess_claim',
+          deviceId: 'dev_claim',
+          expiresAt: new Date(Date.now() + 60_000).toISOString(),
+          user: { id: 'user_claim', username: 'claimed' },
+        } as never;
+      }
+      throw new Error(`unexpected request to ${url}`);
+    });
+
+    await oxy.claimSessionByToken('session-token-abc');
+
+    expect(oxy.hasValidToken()).toBe(true);
+    expect(oxy.getAccessToken()).toBe('access_claim');
+  });
+});

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

@@ -0,0 +1,167 @@
+/**
+ * `verifyServiceActingAs` — the SDK half of the delegation check.
+ *
+ * `serviceAuth.test.ts` covers what the MIDDLEWARE does with this method's
+ * answer, and it does so by stubbing the method out. So nothing there exercises
+ * the method itself: how it authenticates, what it sends, and what it does when
+ * the answer is no or never arrives. That is this file.
+ *
+ * The property under test throughout is fail-closed. `null` is the only value
+ * this method may return when it is not certain, because the middleware turns
+ * `null` into a 403 and anything else into an attached `req.userId`.
+ */
+
+import { OxyServices } from '../../OxyServices';
+import type { RequestOptions } from '../../types';
+
+const APP = 'delegating-app';
+const USER = 'subject-user';
+
+interface CapturedCall {
+  method: string;
+  url: string;
+  data: unknown;
+  options: RequestOptions | undefined;
+}
+
+/**
+ * Stub `makeRequest` and record what it was handed.
+ *
+ * Deliberately not a network mock: the assertion that matters is the exact
+ * request the SDK composes — an unauthenticated one now gets a 403 from the API
+ * rather than an answer, so the Authorization header is part of the contract and
+ * not an implementation detail.
+ */
+function captureRequests(oxy: OxyServices, result: unknown) {
+  const calls: CapturedCall[] = [];
+  jest
+    .spyOn(oxy, 'makeRequest')
+    .mockImplementation(async (method, url, data, options) => {
+      calls.push({ method, url, data, options });
+      if (result instanceof Error) throw result;
+      return result as never;
+    });
+  return calls;
+}
+
+describe('verifyServiceActingAs', () => {
+  let oxy: OxyServices;
+
+  beforeEach(() => {
+    oxy = new OxyServices({ baseURL: 'http://test.invalid' });
+    jest.spyOn(oxy, 'getServiceToken').mockResolvedValue('verifier-service-token');
+  });
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  it("authenticates with the VERIFIER's own service token", async () => {
+    const calls = captureRequests(oxy, { authorized: true, scopes: ['podcasts:write'] });
+
+    await oxy.verifyServiceActingAs(APP, USER);
+
+    expect(calls).toHaveLength(1);
+    expect(calls[0].options?.headers).toEqual({
+      Authorization: 'Bearer verifier-service-token',
+    });
+  });
+
+  it('sends the pair as query params, with retries off and a bounded timeout', async () => {
+    // This runs inside request-handling middleware. A retry loop here multiplies
+    // the latency of every delegated request by the number of attempts, and a
+    // cached GET would serve a revoked grant.
+    const calls = captureRequests(oxy, { authorized: true, scopes: [] });
+
+    await oxy.verifyServiceActingAs(APP, USER);
+
+    expect(calls[0].method).toBe('GET');
+    expect(calls[0].url).toBe('/internal/service-acting-as/verify');
+    expect(calls[0].data).toEqual({ appId: APP, userId: USER });
+    expect(calls[0].options).toMatchObject({ cache: false, retry: false, timeout: 5000 });
+  });
+
+  it('returns the grant when the API authorizes, carrying the scopes through', async () => {
+    captureRequests(oxy, { authorized: true, scopes: ['acting-as:offline', 'podcasts:write'] });
+
+    const grant = await oxy.verifyServiceActingAs(APP, USER);
+
+    expect(grant).toEqual({
+      authorized: true,
+      scopes: ['acting-as:offline', 'podcasts:write'],
+    });
+  });
+
+  it('returns null when the API answers authorized:false', async () => {
+    captureRequests(oxy, { authorized: false, scopes: [] });
+
+    await expect(oxy.verifyServiceActingAs(APP, USER)).resolves.toBeNull();
+  });
+
+  it('returns null when the API answers with scopes but NO authorized flag', async () => {
+    // A truthy `scopes` array must never stand in for authorization: a caller
+    // reading the array and skipping the boolean is the mistake, and the SDK
+    // refuses to produce a value that would reward it.
+    captureRequests(oxy, { scopes: ['podcasts:write'] });
+
+    await expect(oxy.verifyServiceActingAs(APP, USER)).resolves.toBeNull();
+  });
+
+  it('returns null when the endpoint is UNREACHABLE — there is no fail-open path', async () => {
+    captureRequests(oxy, new Error('ECONNREFUSED'));
+
+    await expect(oxy.verifyServiceActingAs(APP, USER)).resolves.toBeNull();
+  });
+
+  it('returns null, and never calls the endpoint, when the verifier has no service credentials', async () => {
+    // A host that cannot prove who it is has no business being told which users
+    // delegated to which applications. `getServiceToken()` throws, and that is
+    // the whole outcome.
+    jest
+      .spyOn(oxy, 'getServiceToken')
+      .mockRejectedValue(new Error('Service credentials not provided.'));
+    const calls = captureRequests(oxy, { authorized: true, scopes: ['podcasts:write'] });
+
+    await expect(oxy.verifyServiceActingAs(APP, USER)).resolves.toBeNull();
+    expect(calls).toHaveLength(0);
+  });
+
+  describe('caching', () => {
+    it('serves a positive grant from cache rather than re-asking', async () => {
+      const calls = captureRequests(oxy, { authorized: true, scopes: ['podcasts:write'] });
+
+      await oxy.verifyServiceActingAs(APP, USER);
+      await oxy.verifyServiceActingAs(APP, USER);
+
+      expect(calls).toHaveLength(1);
+    });
+
+    it('caches a REFUSAL too, so a misconfigured caller cannot hammer the endpoint', async () => {
+      const calls = captureRequests(oxy, { authorized: false, scopes: [] });
+
+      await expect(oxy.verifyServiceActingAs(APP, USER)).resolves.toBeNull();
+      await expect(oxy.verifyServiceActingAs(APP, USER)).resolves.toBeNull();
+
+      expect(calls).toHaveLength(1);
+    });
+
+    it('keys the cache on BOTH app and user — one grant never answers for another', async () => {
+      // The cache key is the whole security boundary of this method. Keyed on
+      // the user alone, one application's grant would authorize every other
+      // application for that user; keyed on the app alone, one user's grant
+      // would authorize acting as everybody.
+      const calls = captureRequests(oxy, { authorized: true, scopes: ['podcasts:write'] });
+
+      await oxy.verifyServiceActingAs(APP, USER);
+      await oxy.verifyServiceActingAs('other-app', USER);
+      await oxy.verifyServiceActingAs(APP, 'other-user');
+
+      expect(calls).toHaveLength(3);
+      expect(calls.map((c) => c.data)).toEqual([
+        { appId: APP, userId: USER },
+        { appId: 'other-app', userId: USER },
+        { appId: APP, userId: 'other-user' },
+      ]);
+    });
+  });
+});

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

@@ -0,0 +1,205 @@
+/**
+ * WebAuthn / passkey auth methods on OxyServices
+ * (`webauthnRegisterOptions` / `webauthnRegisterVerify` /
+ * `webauthnLoginOptions` / `webauthnLoginVerify`).
+ *
+ * Stubs `makeRequest` (HTTP-mock style) and
+ * asserts: each method hits the right endpoint with the right body; the opaque
+ * ceremony `response` is forwarded verbatim; the login/verify + register/verify
+ * (signup) paths parse the login contract and plant the access token on the
+ * session arm; register/verify (link) returns `{ success, message }` WITHOUT
+ * planting a token.
+ */
+import type { LoginResult } from '@oxy.so/contracts';
+import { OxyServices } from '../../OxyServices';
+
+const SESSION_ARM: LoginResult = {
+  sessionId: 'sess-1',
+  deviceId: 'dev-1',
+  expiresAt: '2030-01-01T00:00:00.000Z',
+  accessToken: 'access-1',
+  deviceSecret: 'ds-secret-1',
+  user: { id: 'user-1', username: 'u' },
+};
+
+const LINK_RESULT = { success: true as const, message: 'Passkey registered successfully' };
+
+// Opaque browser ceremony payloads — Oxy never inspects these, so shape is
+// irrelevant beyond "forwarded verbatim under `response`".
+const CREATE_RESPONSE = { id: 'cred-abc', rawId: 'cred-abc', response: { attestationObject: 'ao' }, type: 'public-key' };
+const GET_RESPONSE = { id: 'cred-abc', rawId: 'cred-abc', response: { signature: 'sig' }, type: 'public-key' };
+
+describe('webauthnRegisterOptions', () => {
+  let oxy: OxyServices;
+  let makeRequest: jest.SpyInstance;
+
+  beforeEach(() => {
+    oxy = new OxyServices({ baseURL: 'http://test.invalid' });
+    makeRequest = jest.spyOn(oxy, 'makeRequest');
+  });
+  afterEach(() => jest.restoreAllMocks());
+
+  it('POSTs to /auth/webauthn/register/options with the username', async () => {
+    const options = { challenge: 'c', rp: { id: 'oxy.so' } };
+    makeRequest.mockResolvedValueOnce(options);
+    const result = await oxy.webauthnRegisterOptions('alice');
+    expect(result).toBe(options);
+    expect(makeRequest).toHaveBeenCalledWith(
+      'POST',
+      '/auth/webauthn/register/options',
+      { username: 'alice' },
+      { cache: false, skipAuth: true },
+    );
+  });
+
+  it('omits username from the body when not provided (link flow)', async () => {
+    makeRequest.mockResolvedValueOnce({ challenge: 'c' });
+    await oxy.webauthnRegisterOptions();
+    expect(makeRequest).toHaveBeenCalledWith(
+      'POST',
+      '/auth/webauthn/register/options',
+      {},
+      { cache: false },
+    );
+  });
+});
+
+describe('webauthnLoginOptions', () => {
+  let oxy: OxyServices;
+  let makeRequest: jest.SpyInstance;
+
+  beforeEach(() => {
+    oxy = new OxyServices({ baseURL: 'http://test.invalid' });
+    makeRequest = jest.spyOn(oxy, 'makeRequest');
+  });
+  afterEach(() => jest.restoreAllMocks());
+
+  it('POSTs to /auth/webauthn/login/options with the username (username-first)', async () => {
+    const options = { challenge: 'c', allowCredentials: [{ id: 'cred-abc' }] };
+    makeRequest.mockResolvedValueOnce(options);
+    const result = await oxy.webauthnLoginOptions('alice');
+    expect(result).toBe(options);
+    expect(makeRequest).toHaveBeenCalledWith(
+      'POST',
+      '/auth/webauthn/login/options',
+      { username: 'alice' },
+      { cache: false, skipAuth: true },
+    );
+  });
+
+  it('omits username for the usernameless / discoverable flow', async () => {
+    makeRequest.mockResolvedValueOnce({ challenge: 'c', allowCredentials: [] });
+    await oxy.webauthnLoginOptions();
+    expect(makeRequest).toHaveBeenCalledWith(
+      'POST',
+      '/auth/webauthn/login/options',
+      {},
+      { cache: false, skipAuth: true },
+    );
+  });
+});
+
+describe('webauthnRegisterVerify', () => {
+  let oxy: OxyServices;
+  let makeRequest: jest.SpyInstance;
+  let setTokens: jest.SpyInstance;
+
+  beforeEach(() => {
+    oxy = new OxyServices({ baseURL: 'http://test.invalid' });
+    makeRequest = jest.spyOn(oxy, 'makeRequest');
+    setTokens = jest.spyOn(oxy, 'setTokens').mockImplementation(() => undefined);
+  });
+  afterEach(() => jest.restoreAllMocks());
+
+  it('signup branch: parses LoginSessionResult, plants the token, threads the envelope', async () => {
+    makeRequest.mockResolvedValueOnce(SESSION_ARM);
+    const result = await oxy.webauthnRegisterVerify(CREATE_RESPONSE, {
+      username: 'alice',
+      deviceName: 'Phone',
+      deviceFingerprint: 'fp-1',
+    });
+    expect(result).toEqual(SESSION_ARM);
+    expect('twoFactorRequired' in result).toBe(false);
+    if (!('twoFactorRequired' in result) && 'sessionId' 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/webauthn/register/verify',
+      { response: CREATE_RESPONSE, username: 'alice', deviceName: 'Phone', deviceFingerprint: 'fp-1' },
+      { cache: false, skipAuth: true },
+    );
+  });
+
+  it('link branch: returns { success, message } WITHOUT planting a token', async () => {
+    makeRequest.mockResolvedValueOnce(LINK_RESULT);
+    const result = await oxy.webauthnRegisterVerify(CREATE_RESPONSE, { deviceName: 'Laptop' });
+    expect(result).toEqual(LINK_RESULT);
+    expect(setTokens).not.toHaveBeenCalled();
+    expect(makeRequest).toHaveBeenCalledWith(
+      'POST',
+      '/auth/webauthn/register/verify',
+      { response: CREATE_RESPONSE, deviceName: 'Laptop' },
+      { cache: false },
+    );
+  });
+
+  it('throws on an unexpected response shape', async () => {
+    makeRequest.mockResolvedValueOnce({ nope: true });
+    await expect(oxy.webauthnRegisterVerify(CREATE_RESPONSE)).rejects.toThrow();
+    expect(setTokens).not.toHaveBeenCalled();
+  });
+});
+
+describe('webauthnLoginVerify', () => {
+  let oxy: OxyServices;
+  let makeRequest: jest.SpyInstance;
+  let setTokens: jest.SpyInstance;
+
+  beforeEach(() => {
+    oxy = new OxyServices({ baseURL: 'http://test.invalid' });
+    makeRequest = jest.spyOn(oxy, 'makeRequest');
+    setTokens = jest.spyOn(oxy, 'setTokens').mockImplementation(() => undefined);
+  });
+  afterEach(() => jest.restoreAllMocks());
+
+  it('parses LoginSessionResult, plants the token, and threads the device envelope', async () => {
+    makeRequest.mockResolvedValueOnce(SESSION_ARM);
+    const result = await oxy.webauthnLoginVerify(GET_RESPONSE, {
+      deviceName: 'Phone',
+      deviceFingerprint: 'fp-1',
+    });
+    expect(result).toEqual(SESSION_ARM);
+    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/webauthn/login/verify',
+      { response: GET_RESPONSE, deviceName: 'Phone', deviceFingerprint: 'fp-1' },
+      { cache: false, skipAuth: true },
+    );
+  });
+
+  it('POSTs the bare response body when no envelope is passed', async () => {
+    makeRequest.mockResolvedValueOnce(SESSION_ARM);
+    await oxy.webauthnLoginVerify(GET_RESPONSE);
+    expect(makeRequest).toHaveBeenCalledWith(
+      'POST',
+      '/auth/webauthn/login/verify',
+      { response: GET_RESPONSE },
+      { cache: false, skipAuth: true },
+    );
+  });
+
+  it('throws on an unexpected response shape', async () => {
+    makeRequest.mockResolvedValueOnce({ nope: true });
+    await expect(oxy.webauthnLoginVerify(GET_RESPONSE)).rejects.toThrow();
+    expect(setTokens).not.toHaveBeenCalled();
+  });
+});