@oxy.so/core 1.16.0 → 1.18.1

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',

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

@@ -42,7 +42,7 @@ describe('webauthnRegisterOptions', () => {
   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');
+    const result = await oxy.webauthnRegisterOptions({ username: 'alice' });
     expect(result).toBe(options);
     expect(makeRequest).toHaveBeenCalledWith(
       'POST',
@@ -52,6 +52,17 @@ describe('webauthnRegisterOptions', () => {
     );
   });
 
+  it('sends a recovery ticket signed out', async () => {
+    makeRequest.mockResolvedValueOnce({ challenge: 'c' });
+    await oxy.webauthnRegisterOptions({ recoveryTicket: 't'.repeat(43) });
+    expect(makeRequest).toHaveBeenCalledWith(
+      'POST',
+      '/auth/webauthn/register/options',
+      { recoveryTicket: 't'.repeat(43) },
+      { cache: false, skipAuth: true },
+    );
+  });
+
   it('omits username from the body when not provided (link flow)', async () => {
     makeRequest.mockResolvedValueOnce({ challenge: 'c' });
     await oxy.webauthnRegisterOptions();
@@ -64,6 +75,48 @@ describe('webauthnRegisterOptions', () => {
   });
 });
 
+describe('email verification', () => {
+  let oxy: OxyServices;
+  let makeRequest: jest.SpyInstance;
+
+  beforeEach(() => {
+    oxy = new OxyServices({ baseURL: 'http://test.invalid' });
+    makeRequest = jest.spyOn(oxy, 'makeRequest');
+  });
+  afterEach(() => jest.restoreAllMocks());
+
+  it('starts a verification signed out and parses its id', async () => {
+    makeRequest.mockResolvedValueOnce({ verificationId: 'v-1', expiresAt: 1_900_000_000_000 });
+    await expect(oxy.startEmailVerification({ purpose: 'signup', email: 'ada@example.com' })).resolves.toEqual({
+      verificationId: 'v-1',
+      expiresAt: 1_900_000_000_000,
+    });
+    expect(makeRequest).toHaveBeenCalledWith(
+      'POST',
+      '/auth/email/verify/start',
+      { purpose: 'signup', email: 'ada@example.com' },
+      { cache: false, skipAuth: true },
+    );
+  });
+
+  it('confirms a code into a ticket', async () => {
+    const confirmed = { ticket: 'T'.repeat(43), expiresAt: 1_900_000_000_000, username: 'ada' };
+    makeRequest.mockResolvedValueOnce(confirmed);
+    await expect(oxy.confirmEmailVerification('v-1', '123456')).resolves.toEqual(confirmed);
+    expect(makeRequest).toHaveBeenCalledWith(
+      'POST',
+      '/auth/email/verify/confirm',
+      { verificationId: 'v-1', code: '123456' },
+      { cache: false, skipAuth: true },
+    );
+  });
+
+  it('refuses a malformed answer rather than handing on a ticket it cannot read', async () => {
+    makeRequest.mockResolvedValueOnce({ ticket: 'short', expiresAt: 1 });
+    await expect(oxy.confirmEmailVerification('v-1', '123456')).rejects.toThrow();
+  });
+});
+
 describe('webauthnLoginOptions', () => {
   let oxy: OxyServices;
   let makeRequest: jest.SpyInstance;
@@ -203,3 +256,24 @@ describe('webauthnLoginVerify', () => {
     expect(setTokens).not.toHaveBeenCalled();
   });
 });
+
+describe('deleting a passkey account', () => {
+  let oxy: OxyServices;
+  let makeRequest: jest.SpyInstance;
+
+  beforeEach(() => {
+    oxy = new OxyServices({ baseURL: 'http://test.invalid' });
+    makeRequest = jest.spyOn(oxy, 'makeRequest');
+  });
+  afterEach(() => jest.restoreAllMocks());
+
+  it('asks for the options, then deletes with the assertion and the confirmation', async () => {
+    makeRequest.mockResolvedValueOnce({ challenge: 'c' }).mockResolvedValueOnce({ message: 'deleted' });
+
+    await expect(oxy.getAccountDeletionOptions()).resolves.toEqual({ challenge: 'c' });
+    await expect(oxy.deleteAccountWithPasskey('ada', GET_RESPONSE)).resolves.toEqual({ message: 'deleted' });
+
+    expect(makeRequest).toHaveBeenNthCalledWith(1, 'POST', '/users/me/delete/options', undefined, { cache: false });
+    expect(makeRequest).toHaveBeenNthCalledWith(2, 'DELETE', '/users/me', { confirmText: 'ada', assertion: GET_RESPONSE }, { cache: false });
+  });
+});

package/src/models/interfaces.ts

@@ -4,6 +4,8 @@ import type {
   UserNameResponse,
   UserRelationship,
   ThemePreference,
+  OxyNotificationEntityType,
+  OxyNotificationType,
 } from '@oxy.so/contracts';
 
 export interface OxyConfig {
@@ -20,6 +22,27 @@ export interface OxyConfig {
    * bounce (which uses the RP origin, not this registered client id).
    */
   clientId?: string;
+  /**
+   * How a BACKEND identifies itself on requests that carry no user session.
+   *
+   * - `'never'` (default): such requests go out anonymous. Right for browsers
+   *   and apps, which have no service identity to offer.
+   * - `'when-anonymous'`: they carry this process's service token instead —
+   *   from `configureServiceAuth()`'s key pair, or, with none, from workload
+   *   attestation (ADR 0026). A user session, when there is one, still wins,
+   *   and a process that can produce no service token (a local checkout) keeps
+   *   sending the request anonymous.
+   *
+   * Why a server wants it: oxy-api charges anonymous traffic to the SOURCE
+   * ADDRESS (`rl:general`, and a +500 ms `slowDown` per request past 100 in 15
+   * minutes), and a fleet leaves through one NAT address, so every anonymous
+   * read a backend makes shares — and past the threshold pays for — one budget.
+   * A first-party service token is exempt from both and charged to its own
+   * application's budget instead. Measured from Mention's task (2026-09-25):
+   * `GET /users/:id` 543–575 ms anonymous past the threshold, `POST
+   * /users/by-ids` 19–24 ms with the service token.
+   */
+  serviceIdentity?: 'never' | 'when-anonymous';
   // Performance & caching options
   /**
    * Enable the per-instance GET response cache. Defaults to `true` (5-minute
@@ -267,25 +290,57 @@ export interface LoginResponse {
   message?: string;
 }
 
+/**
+ * The actor of a notification as `GET /notifications` populates it — the raw
+ * stored name, not a composed display name.
+ */
+export interface NotificationActor {
+  _id: string;
+  username?: string;
+  name?: { first: string; last: string };
+  avatar?: string;
+}
+
+/**
+ * One Oxy notification exactly as the API serializes it
+ * (`packages/api/src/controllers/notification.controller.ts`). `_id` — not
+ * `id` — is the key every notification endpoint addresses it by.
+ */
 export interface Notification {
-  id: string;
-  message: string;
+  _id: string;
+  recipientId: string;
+  /** Populated on a list read; the bare id on a create or a mark-read. */
+  actorId: string | NotificationActor;
   /** One of `OXY_NOTIFICATION_TYPES` (`@oxy.so/contracts`). */
-  type?: string;
+  type: OxyNotificationType;
   /**
-   * `system` notifications only (with `message`): the text an Oxy service sent
-   * about the recipient's own account. Render these two instead of composing a
-   * sentence from actor + entity.
+   * What `entityId` names: `post` | `reply` | `profile`, or `app` — an opaque id
+   * in the notifying application's namespace (`system` notifications only).
+   */
+  entityType: OxyNotificationEntityType;
+  entityId: string;
+  /**
+   * `system` notifications only: the text an Oxy service sent about the
+   * recipient's own account. Render these instead of composing a sentence from
+   * actor + entity.
    */
   title?: string;
+  message?: string;
   /** `system` notifications only: an optional deep link (https or the sending app's scheme). */
   url?: string;
-  /**
-   * What `entityId` names: `post` | `reply` | `profile`, or `app` — an opaque id
-   * in the notifying application's namespace (`system` notifications only).
-   */
-  entityType?: string;
-  entityId?: string;
+  read: boolean;
+  createdAt: string;
+  updatedAt: string;
+}
+
+/** One page of `GET /notifications`, newest first. */
+export interface NotificationPage {
+  notifications: Notification[];
+  /** Unread notifications across ALL pages. */
+  unreadCount: number;
+  hasMore: boolean;
+  page: number;
+  limit: number;
 }
 
 export interface Wallet {