@oxy.so/core 1.16.0 → 1.18.0

package/src/mixins/OxyServices.auth.ts

@@ -9,7 +9,15 @@ import type {
   LoginResult,
   CommonsDenyReason,
 } from '@oxy.so/contracts';
-import { loginResultSchema, safeParseContract, type IdentityProof, type WebIdentityEnvelope } from '@oxy.so/contracts';
+import {
+  emailVerificationConfirmResponseSchema,
+  emailVerificationStartResponseSchema,
+  loginResultSchema,
+  safeParseContract,
+  type EmailVerificationConfirmResponse,
+  type EmailVerificationStartRequest,
+  type EmailVerificationStartResponse,
+} from '@oxy.so/contracts';
 import type { SessionLoginResponse } from '../models/session';
 import type { OxyServicesBase } from '../OxyServices.base';
 import type { PublicApplication } from './OxyServices.connectedApps';
@@ -1692,12 +1700,43 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
     }
 
     /**
-     * Check email availability
+     * Send a 6-digit code to an email (ADR 0029 D3): the recovery email of a
+     * new passkey account (`purpose: 'signup'`), or — named by username or
+     * email — the recovery email of an account being recovered
+     * (`purpose: 'recovery'`). The answer is the same whether or not an
+     * account exists; nothing is revealed about who has one.
      */
-    async checkEmailAvailability(email: string): Promise<{ available: boolean; message: string }> {
+    async startEmailVerification(request: EmailVerificationStartRequest): Promise<EmailVerificationStartResponse> {
       try {
-        // Public availability lookup (pre-session) — skip the bearer preflight.
-        return await this.makeRequest('GET', `/auth/check-email/${email}`, undefined, { cache: false, skipAuth: true });
+        const res = await this.makeRequest<unknown>('POST', '/auth/email/verify/start', request, {
+          cache: false,
+          skipAuth: true,
+        });
+        const parsed = safeParseContract(emailVerificationStartResponseSchema, res);
+        if (!parsed) throw new Error('auth/email/verify/start returned an unexpected response shape');
+        return parsed;
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Confirm the code {@link startEmailVerification} sent. Resolves to a
+     * short-lived one-use ticket: a sign-up passes it (with the email) to
+     * {@link webauthnRegisterVerify}; a recovery passes it as `recoveryTicket`
+     * to {@link webauthnRegisterOptions} and {@link webauthnRegisterVerify}.
+     */
+    async confirmEmailVerification(verificationId: string, code: string): Promise<EmailVerificationConfirmResponse> {
+      try {
+        const res = await this.makeRequest<unknown>(
+          'POST',
+          '/auth/email/verify/confirm',
+          { verificationId, code },
+          { cache: false, skipAuth: true },
+        );
+        const parsed = safeParseContract(emailVerificationConfirmResponseSchema, res);
+        if (!parsed) throw new Error('auth/email/verify/confirm returned an unexpected response shape');
+        return parsed;
       } catch (error) {
         throw this.handleError(error);
       }
@@ -1708,19 +1747,24 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
      * `PublicKeyCredentialCreationOptions` the browser's `navigator.credentials
      * .create()` (or `@simplewebauthn/browser`'s `startRegistration`) needs.
      *
-     * With a bearer token planted this links a passkey to the signed-in account
-     * (`username` ignored); without one it is a prospective signup and `username`
-     * is the desired handle. The returned options are OPAQUE — Oxy does not own
-     * their shape (the browser / `@simplewebauthn` does), so they pass through
-     * as `unknown` for the caller to hand straight to the ceremony.
+     * With a bearer token planted this adds a passkey to the signed-in account.
+     * Without one, `username` is a prospective sign-up's handle, and
+     * `recoveryTicket` a recovery's new passkey for the account it names. The
+     * returned options are OPAQUE — Oxy does not own their shape (the browser /
+     * `@simplewebauthn` does), so they pass through as `unknown` for the caller
+     * to hand straight to the ceremony.
      */
-    async webauthnRegisterOptions(username?: string): Promise<unknown> {
+    async webauthnRegisterOptions(request: { username?: string; recoveryTicket?: string } = {}): Promise<unknown> {
+      const signedOut = request.username !== undefined || request.recoveryTicket !== undefined;
       try {
         return await this.makeRequest<unknown>(
           'POST',
           '/auth/webauthn/register/options',
-          { ...(username !== undefined ? { username } : {}) },
-          { cache: false, ...(username !== undefined ? { skipAuth: true } : {}) },
+          {
+            ...(request.username !== undefined ? { username: request.username } : {}),
+            ...(request.recoveryTicket !== undefined ? { recoveryTicket: request.recoveryTicket } : {}),
+          },
+          { cache: false, ...(signedOut ? { skipAuth: true } : {}) },
         );
       } catch (error) {
         throw this.handleError(error);
@@ -1732,10 +1776,12 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
      * browser `RegistrationResponseJSON` (`response`) alongside the Oxy envelope
      * (desired `username` for signup + the device-session naming fields).
      *
-     * Two server branches, disambiguated by the response shape:
-     *  - **Signup** (no bearer): the account is created and a session minted —
-     *    the response carries `sessionId`, is the SAME {@link LoginResult}
-     *    contract as `POST /auth/verify`, and its access token is planted here.
+     * Server branches, disambiguated by the response shape:
+     *  - **Sign-up** (no bearer; `username`, `email`, `emailTicket`) and
+     *    **recovery** (no bearer; `recoveryTicket`): the account is created, or
+     *    gains the passkey, and a session is minted — the response carries
+     *    `sessionId`, is the SAME {@link LoginResult} contract as
+     *    `POST /auth/verify`, and its access token is planted here.
      *  - **Link** (bearer present): the passkey is attached to the signed-in
      *    account and the server returns `{ success, message }` with no session,
      *    which is returned verbatim (no token planting).
@@ -1744,14 +1790,13 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
       response: unknown,
       envelope: {
         username?: string;
+        /** Sign-up: the recovery email, confirmed with `emailTicket`. */
+        email?: string;
+        emailTicket?: string;
+        /** Recovery: the ticket {@link confirmEmailVerification} returned. */
+        recoveryTicket?: string;
         deviceName?: string;
         deviceFingerprint?: string;
-        /**
-         * Sign-up only: the root created on the holder before this call, sealed
-         * under the passkey being registered, plus its `enroll_identity` proof
-         * (ADR 0024 D4). The account is created WITH it or not at all.
-         */
-        identity?: { envelope: WebIdentityEnvelope; proof: IdentityProof };
       } = {},
     ): Promise<{ success: true; message: string } | LoginResult> {
       try {
@@ -1759,7 +1804,10 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
           'POST',
           '/auth/webauthn/register/verify',
           { response, ...envelope },
-          { cache: false, ...(envelope.username !== undefined ? { skipAuth: true } : {}) },
+          {
+            cache: false,
+            ...(envelope.username !== undefined || envelope.recoveryTicket !== undefined ? { skipAuth: true } : {}),
+          },
         );
         if (res && typeof res === 'object') {
           const record = res as Record<string, unknown>;

package/src/mixins/OxyServices.identity.ts

@@ -23,8 +23,16 @@
  * on-device identity and throw on web (where `KeyManager.getPublicKey()` is
  * always `null`).
  */
+import {
+  IDENTITY_PROOF_ACTIONS,
+  identityLinkCreateResponseSchema,
+  identityLinkStateSchema,
+  safeParseContract,
+} from '@oxy.so/contracts';
 import type {
   AuthMethodsResponse,
+  IdentityLinkCreateResponse,
+  IdentityLinkState,
   IdentityRootStatus,
   DidDocument,
   DomainVerificationInstructions,
@@ -38,6 +46,8 @@ import type {
 import { signMessage } from '@oxy.so/protocol';
 import type { OxyServicesBase } from '../OxyServices.base';
 import { KeyManager } from '../crypto/keyManager';
+import { deriveIdentityLinkCode } from '../crypto/identityLink';
+import { signIdentityProof } from '../crypto/identityProof';
 import { SignatureService } from '../crypto/signatureService';
 import { RecoveryPhraseService, type PendingIdentityResult } from '../crypto/recoveryPhrase';
 import { isWeb } from '../utils/platform';
@@ -219,11 +229,9 @@ export function OxyServicesIdentityMixin<T extends typeof OxyServicesBase>(Base:
     }
 
     /**
-     * The signed-in account's root readiness (ADR 0024 D5): whether a root is
-     * linked, how many passkeys can open the web holder, whether the root has a
-     * phrase and whether it is saved and was shown to recover it. Metadata only —
-     * nothing here can open the root — so any first-party surface may show a
-     * "save your recovery phrase" reminder from it.
+     * How the signed-in account is kept (ADR 0029 D3): whether Commons' root is
+     * linked (self-custody), or the recovery email of a passkey account. Any
+     * first-party surface may read it to recommend linking Commons.
      */
     async getIdentityRootStatus(): Promise<IdentityRootStatus> {
       try {
@@ -233,15 +241,125 @@ export function OxyServicesIdentityMixin<T extends typeof OxyServicesBase>(Base:
       }
     }
 
+    /**
+     * Open a request to link Commons to the signed-in passkey account (ADR 0029
+     * D3). auth.oxy.so shows its `qrPayload`; Commons scans it and signs with
+     * {@link signIdentityLink}.
+     */
+    async createIdentityLink(): Promise<IdentityLinkCreateResponse> {
+      try {
+        const res = await this.makeRequest<unknown>('POST', '/identity/link', undefined, { cache: false });
+        const parsed = safeParseContract(identityLinkCreateResponseSchema, res);
+        if (!parsed) throw new Error('identity/link returned an unexpected response shape');
+        return parsed;
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /** Where a link request stands. Both devices poll it; it needs no session. */
+    async getIdentityLink(linkId: string): Promise<IdentityLinkState> {
+      try {
+        const res = await this.makeRequest<unknown>('GET', `/identity/link/${encodeURIComponent(linkId)}`, undefined, {
+          cache: false,
+          skipAuth: true,
+        });
+        const parsed = safeParseContract(identityLinkStateSchema, res);
+        if (!parsed) throw new Error('identity/link returned an unexpected response shape');
+        return parsed;
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Commons' half: sign the scanned request's `link_identity` proof with THIS
+     * device's identity key and post it. NATIVE-ONLY (the key lives in native
+     * secure storage). Resolves to the key and the 6-digit code auth.oxy.so will
+     * show for it, for the person to compare.
+     */
+    async signIdentityLink(linkId: string, challenge: string): Promise<{ publicKey: string; code: string; username: string | null }> {
+      try {
+        const [privateKey, publicKey] = await Promise.all([KeyManager.getPrivateKey(), KeyManager.getPublicKey()]);
+        if (!privateKey || !publicKey) {
+          throw new Error('No identity on this device to link');
+        }
+        const root = publicKey.trim().toLowerCase();
+        const state = await this.getIdentityLink(linkId);
+        const proof = await signIdentityProof(
+          { privateKey, publicKey: root },
+          {
+            action: IDENTITY_PROOF_ACTIONS.link,
+            subject: state.userId,
+            actor: state.userId,
+            rootPublicKey: root,
+            payloadDigest: null,
+            expectedRevision: null,
+            audience: state.audience,
+            challenge,
+            expiresAt: state.expiresAt,
+          },
+        );
+        await this.makeRequest<unknown>(
+          'POST',
+          `/identity/link/${encodeURIComponent(linkId)}/proof`,
+          { publicKey: root, proof },
+          { cache: false, skipAuth: true },
+        );
+        return { publicKey: root, code: deriveIdentityLinkCode(linkId, root), username: state.username };
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /** WebAuthn request options over the account's passkeys, whose challenge is the link's. Opaque. */
+    async getIdentityLinkAssertionOptions(linkId: string, challenge: string): Promise<unknown> {
+      try {
+        return await this.makeRequest<unknown>(
+          'POST',
+          `/identity/link/${encodeURIComponent(linkId)}/options`,
+          { challenge },
+          { cache: false },
+        );
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * auth.oxy.so's half: the passkey assertion over the link's challenge. The
+     * account gains Commons' root and loses its recovery email.
+     */
+    async completeIdentityLink(linkId: string, assertion: unknown): Promise<{ success: true }> {
+      try {
+        const result = await this.makeRequest<{ success: true }>(
+          'POST',
+          `/identity/link/${encodeURIComponent(linkId)}/complete`,
+          { assertion },
+          { cache: false },
+        );
+        this._invalidateIdentityCaches(this.getCurrentUserId());
+        return result;
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /** Withdraw a link request that has not completed. */
+    async cancelIdentityLink(linkId: string): Promise<void> {
+      try {
+        await this.makeRequest<unknown>('DELETE', `/identity/link/${encodeURIComponent(linkId)}`, undefined, { cache: false });
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
     /**
      * Remove ONE passkey (WebAuthn credential) from the current account.
      *
      * Passkeys are per-credential, so this targets a specific credential id.
      * The server refuses to remove the last remaining auth method (the account
      * would become inaccessible) and deletes the stored `WebauthnCredential`.
-     * A passkey that also opens the account's root on the web takes its wrap with
-     * it, and the ONLY such passkey is refused with
-     * `code: 'IDENTITY_LAST_WEB_HOLDER'` (ADR 0024 D6).
      *
      * @param credentialId - The passkey's public credential id
      *   (`AuthMethodEntry.credentialId`).

package/src/mixins/OxyServices.user.ts

@@ -5,6 +5,7 @@ import type { CreateOxyNotificationRequest } from '@oxy.so/contracts';
 import type {
   User,
   Notification,
+  NotificationPage,
   NotificationPreferences,
   UserPreferences,
   SearchProfilesResponse,
@@ -755,6 +756,35 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
     }
 
 
+    /**
+     * WebAuthn request options to delete a PASSKEY account (ADR 0029 D3): its own
+     * passkeys, user verification required, and a challenge bound to it. Opaque —
+     * hand them to the browser's authentication ceremony, on auth.oxy.so. An
+     * account with a Commons key deletes with {@link deleteAccount} instead.
+     */
+    async getAccountDeletionOptions(): Promise<unknown> {
+      try {
+        return await this.makeRequest<unknown>('POST', '/users/me/delete/options', undefined, { cache: false });
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Delete a PASSKEY account permanently, with an assertion by one of its
+     * passkeys over {@link getAccountDeletionOptions}' challenge.
+     *
+     * @param confirmText - Must equal the user's username (verified server-side)
+     * @param assertion - The ceremony's opaque `AuthenticationResponseJSON`
+     */
+    async deleteAccountWithPasskey(confirmText: string, assertion: unknown): Promise<{ message: string }> {
+      try {
+        return await this.makeRequest<{ message: string }>('DELETE', '/users/me', { confirmText, assertion }, { cache: false });
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
     /**
      * Invalidate every cached read a follow/unfollow write invalidates.
      *
@@ -1092,11 +1122,13 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
     }
 
     /**
-     * Get notifications
+     * One page of the signed-in user's Oxy notifications, newest first
+     * (`GET /notifications`), with the unread count across all pages.
      */
-    async getNotifications(): Promise<Notification[]> {
+    async getNotifications(params: { page?: number; limit?: number } = {}): Promise<NotificationPage> {
+      const query = buildQueryParams({ page: params.page, limit: params.limit });
       return this.withAuthRetry(async () => {
-        return await this.makeRequest<Notification[]>('GET', '/notifications', undefined, {
+        return await this.makeRequest<NotificationPage>('GET', '/notifications', query, {
           cache: false, // Don't cache notifications - always get fresh data
         });
       }, 'getNotifications');
@@ -1107,10 +1139,10 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
      */
     async getUnreadCount(): Promise<number> {
       try {
-        const res = await this.makeRequest<{ count: number }>('GET', '/notifications/unread-count', undefined, {
+        const res = await this.makeRequest<{ unreadCount: number }>('GET', '/notifications/unread-count', undefined, {
           cache: false, // Don't cache unread count - always get fresh data
         });
-        return res.count;
+        return res.unreadCount;
       } catch (error) {
         throw this.handleError(error);
       }
@@ -1123,20 +1155,29 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
      * from an Oxy service about the recipient's own account, with the recipient
      * as actor and their profile as the entity.
      */
-    async createNotification(data: CreateOxyNotificationRequest | Partial<Notification>): Promise<Notification> {
+    async createNotification(data: CreateOxyNotificationRequest): Promise<Notification> {
       try {
-        return await this.makeRequest<Notification>('POST', '/notifications', data, { cache: false });
+        const res = await this.makeRequest<{ notification: Notification }>('POST', '/notifications', data, { cache: false });
+        return res.notification;
       } catch (error) {
         throw this.handleError(error);
       }
     }
 
     /**
-     * Mark notification as read
+     * Mark one of the signed-in user's notifications read and return it as
+     * stored. Scoped to the recipient server-side, so it is also the
+     * authoritative read of a notification by id: a foreign or unknown id 404s.
      */
-    async markNotificationAsRead(notificationId: string): Promise<void> {
+    async markNotificationAsRead(notificationId: string): Promise<Notification> {
       try {
-        await this.makeRequest('PUT', `/notifications/${notificationId}/read`, undefined, { cache: false });
+        const res = await this.makeRequest<{ notification: Notification }>(
+          'PUT',
+          `/notifications/${encodeURIComponent(notificationId)}/read`,
+          undefined,
+          { cache: false },
+        );
+        return res.notification;
       } catch (error) {
         throw this.handleError(error);
       }

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

@@ -0,0 +1,89 @@
+/**
+ * Linking Commons to a passkey account (ADR 0029 D3): what each device sends.
+ * `makeRequest` is stubbed; the proof Commons signs is verified for real.
+ */
+import { buildIdentityProofMessage } from '@oxy.so/contracts';
+import { deriveSecp256k1PublicKey } from '@oxy.so/protocol/secp256k1';
+import { verifySignature } from '@oxy.so/protocol';
+import { OxyServices } from '../../OxyServices';
+import { KeyManager } from '../../crypto/keyManager';
+import { deriveIdentityLinkCode } from '../../crypto/identityLink';
+
+const LINK_ID = 'ab'.repeat(16);
+const CHALLENGE = 'cd'.repeat(32);
+const PRIVATE_KEY = '3a'.repeat(32);
+const PUBLIC_KEY = deriveSecp256k1PublicKey(PRIVATE_KEY).toLowerCase();
+const STATE = {
+  status: 'pending',
+  userId: 'user-1',
+  username: 'ada',
+  publicKey: null,
+  audience: 'oxy-api/identity',
+  expiresAt: 1_900_000_000_000,
+};
+
+describe('linking Commons', () => {
+  let oxy: OxyServices;
+  let makeRequest: jest.SpyInstance;
+
+  beforeEach(() => {
+    oxy = new OxyServices({ baseURL: 'http://test.invalid' });
+    makeRequest = jest.spyOn(oxy, 'makeRequest');
+  });
+  afterEach(() => jest.restoreAllMocks());
+
+  it('Commons signs the link proof for the account the request names, with its own key', async () => {
+    jest.spyOn(KeyManager, 'getPrivateKey').mockResolvedValue(PRIVATE_KEY);
+    jest.spyOn(KeyManager, 'getPublicKey').mockResolvedValue(PUBLIC_KEY.toUpperCase());
+    makeRequest.mockResolvedValueOnce(STATE).mockResolvedValueOnce({ status: 'signed' });
+
+    const result = await oxy.signIdentityLink(LINK_ID, CHALLENGE);
+
+    expect(result).toEqual({ publicKey: PUBLIC_KEY, code: deriveIdentityLinkCode(LINK_ID, PUBLIC_KEY), username: 'ada' });
+    expect(makeRequest).toHaveBeenNthCalledWith(1, 'GET', `/identity/link/${LINK_ID}`, undefined, { cache: false, skipAuth: true });
+    const [, path, body, options] = makeRequest.mock.calls[1] as [string, string, { publicKey: string; proof: { signature: string; challenge: string; expiresAt: number } }, unknown];
+    expect(path).toBe(`/identity/link/${LINK_ID}/proof`);
+    expect(options).toEqual({ cache: false, skipAuth: true });
+    expect(body.publicKey).toBe(PUBLIC_KEY);
+    expect(body.proof).toMatchObject({ v: 2, challenge: CHALLENGE, expiresAt: STATE.expiresAt });
+    const message = buildIdentityProofMessage({
+      action: 'link_identity',
+      subject: 'user-1',
+      actor: 'user-1',
+      rootPublicKey: PUBLIC_KEY,
+      payloadDigest: null,
+      expectedRevision: null,
+      audience: STATE.audience,
+      challenge: CHALLENGE,
+      expiresAt: STATE.expiresAt,
+    });
+    expect(await verifySignature(message, body.proof.signature, PUBLIC_KEY)).toBe(true);
+  });
+
+  it('refuses to sign without an identity on this device', async () => {
+    jest.spyOn(KeyManager, 'getPrivateKey').mockResolvedValue(null);
+    jest.spyOn(KeyManager, 'getPublicKey').mockResolvedValue(null);
+    await expect(oxy.signIdentityLink(LINK_ID, CHALLENGE)).rejects.toThrow('No identity');
+    expect(makeRequest).not.toHaveBeenCalled();
+  });
+
+  it('the web opens, asks for the assertion options, completes and cancels', async () => {
+    makeRequest
+      .mockResolvedValueOnce({ linkId: LINK_ID, challenge: CHALLENGE, expiresAt: 1, qrPayload: `oxycommons://link?id=${LINK_ID}&c=${CHALLENGE}` })
+      .mockResolvedValueOnce({ challenge: 'x' })
+      .mockResolvedValueOnce({ success: true })
+      .mockResolvedValueOnce({});
+
+    await expect(oxy.createIdentityLink()).resolves.toMatchObject({ linkId: LINK_ID });
+    await oxy.getIdentityLinkAssertionOptions(LINK_ID, CHALLENGE);
+    await oxy.completeIdentityLink(LINK_ID, { id: 'cred' });
+    await oxy.cancelIdentityLink(LINK_ID);
+
+    expect(makeRequest.mock.calls.map(([method, path, body]) => [method, path, body])).toEqual([
+      ['POST', '/identity/link', undefined],
+      ['POST', `/identity/link/${LINK_ID}/options`, { challenge: CHALLENGE }],
+      ['POST', `/identity/link/${LINK_ID}/complete`, { assertion: { id: 'cred' } }],
+      ['DELETE', `/identity/link/${LINK_ID}`, undefined],
+    ]);
+  });
+});

package/src/mixins/__tests__/notifications.read.test.ts

@@ -0,0 +1,82 @@
+/**
+ * The notification READ methods against the wire bodies `GET /notifications`,
+ * `GET /notifications/unread-count` and `PUT /notifications/:id/read` actually
+ * send (`packages/api/src/controllers/notification.controller.ts`), driven
+ * through the real HTTP stack with only `fetch` stubbed.
+ *
+ * They used to be typed against a shape the API never sent: `getNotifications`
+ * claimed an array while the server answers a page object, `getUnreadCount`
+ * read `count` from a body that carries `unreadCount` (so it always returned
+ * `undefined`), and `markNotificationAsRead` dropped the stored notification the
+ * server returns — the one authoritative read of a notification by id.
+ */
+
+import { OxyServices } from '../../OxyServices';
+
+const SYSTEM_NOTIFICATION = {
+  _id: '0192f0c4-7b1e-7000-8000-000000000001',
+  recipientId: 'user-1',
+  actorId: 'user-1',
+  type: 'system',
+  entityId: 'job-42',
+  entityType: 'app',
+  title: 'Your Mastodon account moved',
+  message: '312 followers came with you.',
+  url: 'https://move.oxy.so/jobs/job-42',
+  read: false,
+  createdAt: '2026-09-26T10:00:00.000Z',
+  updatedAt: '2026-09-26T10:00:00.000Z',
+};
+
+describe('OxyServices notification reads', () => {
+  const originalFetch = globalThis.fetch;
+  let fetchMock: jest.Mock;
+
+  function answer(body: unknown): void {
+    fetchMock.mockResolvedValueOnce(
+      new Response(JSON.stringify(body), { status: 200, headers: { 'content-type': 'application/json' } }),
+    );
+  }
+
+  let oxy: OxyServices;
+  beforeEach(() => {
+    fetchMock = jest.fn();
+    globalThis.fetch = fetchMock as unknown as typeof fetch;
+    oxy = new OxyServices({ baseURL: 'http://api.test.invalid' });
+    oxy.setTokens('test-token');
+  });
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+  });
+
+  it('getNotifications returns the page the API sends, with the paging it asked for', async () => {
+    const page = { notifications: [SYSTEM_NOTIFICATION], unreadCount: 1, hasMore: false, page: 2, limit: 10 };
+    answer({ data: page });
+
+    await expect(oxy.getNotifications({ page: 2, limit: 10 })).resolves.toEqual(page);
+
+    const url = new URL(String(fetchMock.mock.calls[0][0]));
+    expect(url.pathname).toBe('/notifications');
+    expect(url.searchParams.get('page')).toBe('2');
+    expect(url.searchParams.get('limit')).toBe('10');
+  });
+
+  it('getUnreadCount reads `unreadCount`', async () => {
+    answer({ data: { unreadCount: 3 } });
+
+    await expect(oxy.getUnreadCount()).resolves.toBe(3);
+  });
+
+  it('markNotificationAsRead returns the stored notification', async () => {
+    answer({ data: { notification: { ...SYSTEM_NOTIFICATION, read: true } } });
+
+    await expect(oxy.markNotificationAsRead(SYSTEM_NOTIFICATION._id)).resolves.toEqual({
+      ...SYSTEM_NOTIFICATION,
+      read: true,
+    });
+    expect(String(fetchMock.mock.calls[0][0])).toBe(
+      `http://api.test.invalid/notifications/${SYSTEM_NOTIFICATION._id}/read`,
+    );
+  });
+});

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

@@ -86,7 +86,7 @@ describe('pre-session public endpoints use skipAuth', () => {
   });
 
   it('webauthnRegisterOptions skips auth preflight on signup (username provided)', async () => {
-    await oxy.webauthnRegisterOptions('alice');
+    await oxy.webauthnRegisterOptions({ username: 'alice' });
     expect(makeRequest).toHaveBeenCalledWith(
       'POST',
       '/auth/webauthn/register/options',