@oxy.so/core 1.10.0 → 1.12.0

package/src/crypto/keyManager.ts

@@ -26,6 +26,13 @@ import {
   updateIdentityMarker,
   writeIdentityMarker,
 } from './identityMarker';
+import {
+  DEVICE_BACKUP_VERSION,
+  type DeviceBackupRecord,
+  type IdentityDeviceBackupStore,
+  parseDeviceBackup,
+  serializeDeviceBackup,
+} from './deviceBackup';
 
 /**
  * Options for expo-secure-store calls made by KeyManager.
@@ -138,9 +145,13 @@ export type IdentityStatus =
  * which independent, `key_v1`-surviving source restored the identity. On failure
  * `reason` distinguishes "wasn't lost", "no surviving source", "a source held a
  * DIFFERENT account" (never silently switched), and "storage unavailable".
+ *
+ * `device-backup` is the copy held outside this app's keystore (Android Block
+ * Store in Commons, see {@link KeyManager.setDeviceBackupStore}); it is the only
+ * source that survives a wipe of the whole shared-UID keystore.
  */
 export type IdentityRecoveryResult =
-  | { recovered: true; source: 'backup' | 'shared'; publicKey: string }
+  | { recovered: true; source: 'backup' | 'shared' | 'device-backup'; publicKey: string }
   | { recovered: false; reason: 'not-lost' | 'no-sources' | 'mismatch' | 'unavailable' };
 
 /**
@@ -393,6 +404,27 @@ export class KeyManager {
   private static slotMigrationPromise: Promise<SlotMigrationResult> | null = null;
   private static slotMigrationResult: SlotMigrationResult | null = null;
 
+  /**
+   * The keystore-independent device backup, registered by the app that owns the
+   * identity (Commons). `null` in every other app, which makes every device
+   * backup path a no-op there. See `./deviceBackup`.
+   */
+  private static deviceBackupStore: IdentityDeviceBackupStore | null = null;
+
+  /**
+   * Register (or, with `null`, unregister) where the identity's device backup is
+   * kept. Call once at startup, before the first identity read, ONLY from the
+   * app that holds the self-custody identity: the backup is a full copy of the
+   * private key, and it belongs to exactly one app.
+   *
+   * From then on every create, import, rotation and restore refreshes the
+   * backup, a forced delete clears it, and {@link attemptIdentityRecovery}
+   * restores from it when the keystore copies are gone.
+   */
+  static setDeviceBackupStore(store: IdentityDeviceBackupStore | null): void {
+    KeyManager.deviceBackupStore = store;
+  }
+
   /**
    * Invalidate cached identity state
    * Called internally when identity is created/deleted/imported
@@ -1524,6 +1556,149 @@ export class KeyManager {
     // persist (a subsequent healthy read re-backfills it). Rollback paths above
     // return before reaching here, so they never touch the marker.
     await KeyManager._syncMarkerAfterPersist(canonicalPublic, origin);
+
+    // Mirror the durable identity into the keystore-independent device backup,
+    // so a wipe of this UID's keystore can be undone without the phrase. Every
+    // identity change (create, import, rotation, restore) flows through here.
+    // Best-effort like the marker: `ensureDeviceBackup` retries on next launch.
+    await KeyManager._writeDeviceBackup(canonicalPrivate, canonicalPublic);
+  }
+
+  /**
+   * Write the device backup for `(privateKey, publicKey)`, keeping the phrase an
+   * existing record already carries for the SAME identity. `mnemonic` replaces
+   * it, and must already be verified against `publicKey` by the caller.
+   * Best-effort: never throws, returns whether the store now holds this pair.
+   *
+   * @internal
+   */
+  private static async _writeDeviceBackup(
+    privateKey: string,
+    publicKey: string,
+    mnemonic?: string,
+  ): Promise<boolean> {
+    const store = KeyManager.deviceBackupStore;
+    if (!store) {
+      return false;
+    }
+    try {
+      let existing: DeviceBackupRecord | null = null;
+      try {
+        existing = parseDeviceBackup(await store.read());
+      } catch {
+        existing = null;
+      }
+      const sameIdentity = existing?.publicKey === publicKey;
+      const keptMnemonic = mnemonic ?? (sameIdentity ? existing?.mnemonic : undefined);
+      if (sameIdentity && existing?.privateKey === privateKey && existing?.mnemonic === keptMnemonic) {
+        return true; // Already current; do not churn the store.
+      }
+      await store.write(
+        serializeDeviceBackup({
+          version: DEVICE_BACKUP_VERSION,
+          privateKey,
+          publicKey,
+          mnemonic: keptMnemonic,
+          updatedAt: new Date().toISOString(),
+        }),
+      );
+      return true;
+    } catch (error) {
+      logger.warn(
+        `Failed to write the identity device backup (${store.name}); retried on next launch`,
+        { component: 'KeyManager' },
+        error,
+      );
+      return false;
+    }
+  }
+
+  /** Remove the device backup. Best-effort: never throws. @internal */
+  private static async _clearDeviceBackup(): Promise<void> {
+    const store = KeyManager.deviceBackupStore;
+    if (!store) {
+      return;
+    }
+    try {
+      await store.clear();
+    } catch (error) {
+      logger.warn(`Failed to clear the identity device backup (${store.name})`, { component: 'KeyManager' }, error);
+    }
+  }
+
+  /** True when `phrase` is a valid BIP-39 phrase that derives `publicKey`. @internal */
+  private static async _phraseDerivesPublicKey(phrase: string, publicKey: string): Promise<boolean> {
+    try {
+      // Imported lazily: `./recoveryPhrase` imports this module, and the phrase
+      // derivation is frozen there, so it is reused rather than copied.
+      const { RecoveryPhraseService } = await import('./recoveryPhrase');
+      const derived = await RecoveryPhraseService.derivePublicKeyFromPhrase(phrase);
+      return derived.toLowerCase() === publicKey.toLowerCase();
+    } catch {
+      return false;
+    }
+  }
+
+  /** The primary pair when it reads back healthy, else `null`. Never throws. @internal */
+  private static async _readHealthyPrimary(): Promise<{ privateKey: string; publicKey: string } | null> {
+    try {
+      const direct = await KeyManager._readPrimaryDirect();
+      if (KeyManager._isHealthyPair(direct.privateKey, direct.publicKey) && direct.privateKey && direct.publicKey) {
+        return {
+          privateKey: KeyManager.canonicalPrivateKey(direct.privateKey),
+          publicKey: direct.publicKey.toLowerCase(),
+        };
+      }
+      return null;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Make sure the device backup holds the identity on this device, writing it
+   * when it is missing or stale. Commons calls this once per launch once the
+   * identity reads back healthy: it backfills identities created before the
+   * device backup existed, and repairs a backup whose last write failed (a
+   * failed write after a key rotation would otherwise leave the OLD key there).
+   *
+   * Carries the stored recovery phrase along only when it provably derives the
+   * current key. Resolves `true` when the backup is current, `false` when there
+   * is no store, no healthy identity, or the write failed. Never throws.
+   */
+  static async ensureDeviceBackup(): Promise<boolean> {
+    if (isWebPlatform() || !KeyManager.deviceBackupStore) {
+      return false;
+    }
+    const primary = await KeyManager._readHealthyPrimary();
+    if (!primary) {
+      return false;
+    }
+    let existing: DeviceBackupRecord | null = null;
+    try {
+      existing = parseDeviceBackup(await KeyManager.deviceBackupStore.read());
+    } catch {
+      existing = null;
+    }
+    const pairCurrent =
+      existing?.publicKey === primary.publicKey && existing?.privateKey === primary.privateKey;
+    if (pairCurrent && existing?.mnemonic) {
+      return true; // The common launch: one read, no write, no phrase derivation.
+    }
+
+    let mnemonic: string | undefined;
+    try {
+      const stored = await KeyManager.getRecoveryMnemonic();
+      if (stored && (await KeyManager._phraseDerivesPublicKey(stored, primary.publicKey))) {
+        mnemonic = stored;
+      }
+    } catch {
+      mnemonic = undefined;
+    }
+    if (pairCurrent && !mnemonic) {
+      return true;
+    }
+    return KeyManager._writeDeviceBackup(primary.privateKey, primary.publicKey, mnemonic);
   }
 
   /**
@@ -1866,6 +2041,16 @@ export class KeyManager {
       }
       throw new IdentityUnavailableError('Failed to persist recovery mnemonic.', error);
     }
+
+    // The phrase slot above dies with the keystore too, so the device backup
+    // carries the phrase as well — but only one that derives the identity on
+    // this device. Best-effort: never fails the store.
+    if (KeyManager.deviceBackupStore) {
+      const primary = await KeyManager._readHealthyPrimary();
+      if (primary && (await KeyManager._phraseDerivesPublicKey(mnemonic, primary.publicKey))) {
+        await KeyManager._writeDeviceBackup(primary.privateKey, primary.publicKey, mnemonic.trim().toLowerCase());
+      }
+    }
   }
 
   /**
@@ -2165,6 +2350,11 @@ export class KeyManager {
       await KeyManager._clearSharedSlot(store);
     }
 
+    // The device backup goes on EVERY delete, forced or not: it is restored
+    // silently, so leaving it would bring a deleted identity back on the next
+    // launch. Best-effort, like the other recovery sources.
+    await KeyManager._clearDeviceBackup();
+
     // Clear the marker AFTER key deletion succeeds — a marker must never outlive
     // its identity (a leftover marker would route a truly-absent device to
     // `recovery` instead of `welcome`).
@@ -2416,19 +2606,29 @@ export class KeyManager {
   }
 
   /**
-   * Recovery ladder — restore a `lost` identity from an independent,
-   * `key_v1`-surviving source WITHOUT the user re-entering their recovery phrase.
-   *
-   * Gated on {@link getIdentityStatus} being `lost` (marker present, keys empty):
-   *   - `present` / `absent` → `not-lost` (nothing to recover / nothing lost)
-   *   - `unavailable`        → `unavailable` (keychain locked; retry later)
+   * Recovery ladder — restore an identity whose keys are gone from an
+   * independent source WITHOUT the user re-entering their recovery phrase.
    *
-   * Rungs, tried in order, each fully validated (well-formed + derive-match +
-   * `publicKey === marker.publicKey`, so a source holding a DIFFERENT account is
-   * SKIPPED, never restored):
-   *   1. the v2 backup slot (independent keychain key from the primary), then
+   * For a `lost` verdict (marker present, keys empty) the rungs are tried in
+   * order, each fully validated (well-formed + derive-match + `publicKey ===
+   * marker.publicKey`, so a source holding a DIFFERENT account is SKIPPED, never
+   * restored):
+   *   1. the v2 backup slot (independent keychain key from the primary),
    *   2. the cross-app shared slot (Android bridge `getShared` / iOS keychain
-   *      group) — the copy that survives a primary+backup `key_v1` death.
+   *      group) — the copy that survives a primary+backup `key_v1` death,
+   *   3. the device backup ({@link setDeviceBackupStore}; Android Block Store in
+   *      Commons) — the only copy that survives a wipe of the whole shared-UID
+   *      Android Keystore, which takes rungs 1 and 2 with it (oxy#1388).
+   *
+   * For an `absent` verdict (no keys AND no marker: this app's own data was
+   * cleared, or it was reinstalled) only rung 3 applies: a device backup there
+   * means an identity lived on this device and was never deleted (every delete
+   * clears the backup), so it is restored instead of letting onboarding create a
+   * new identity over it. Without a registered store the result stays
+   * `not-lost`, exactly as before.
+   *
+   * `present` → `not-lost`; `unavailable` (keychain locked) → `unavailable`.
+   * Everything here is on-device: no network, so it works offline.
    *
    * On success it re-persists via {@link _persistIdentityAtomic} (origin
    * `'restore'`) and invalidates the cache so routing re-reads `present`. When no
@@ -2440,12 +2640,24 @@ export class KeyManager {
     }
 
     const status = await KeyManager.getIdentityStatus({ bypassCache: true });
-    if (status.state === 'present' || status.state === 'absent') {
+    if (status.state === 'present') {
       return { recovered: false, reason: 'not-lost' };
     }
     if (status.state === 'unavailable') {
       return { recovered: false, reason: 'unavailable' };
     }
+    if (status.state === 'absent') {
+      if (!KeyManager.deviceBackupStore) {
+        return { recovered: false, reason: 'not-lost' };
+      }
+      const candidate = await KeyManager._readDeviceBackupCandidate();
+      if (!candidate) {
+        return { recovered: false, reason: 'not-lost' };
+      }
+      return (await KeyManager._commitDeviceBackupRecovery(candidate))
+        ? { recovered: true, source: 'device-backup', publicKey: candidate.publicKey }
+        : { recovered: false, reason: 'no-sources' };
+    }
 
     // status.state === 'lost'
     const expectedPublic = status.marker.publicKey.toLowerCase();
@@ -2475,11 +2687,64 @@ export class KeyManager {
       }
     }
 
+    // Rung 3: device backup, outside this UID's keystore.
+    const deviceCandidate = await KeyManager._readDeviceBackupCandidate();
+    if (deviceCandidate) {
+      if (deviceCandidate.publicKey === expectedPublic) {
+        if (await KeyManager._commitDeviceBackupRecovery(deviceCandidate)) {
+          return { recovered: true, source: 'device-backup', publicKey: deviceCandidate.publicKey };
+        }
+      } else {
+        sawMismatch = true;
+      }
+    }
+
     // A source existed but identified a DIFFERENT account — never silently
     // switched. Report `mismatch` so the UI can require explicit confirmation.
     return { recovered: false, reason: sawMismatch ? 'mismatch' : 'no-sources' };
   }
 
+  /** Read the device backup as a healthy, canonical candidate, or null. Never throws. @internal */
+  private static async _readDeviceBackupCandidate(): Promise<DeviceBackupRecord | null> {
+    const store = KeyManager.deviceBackupStore;
+    if (!store) {
+      return null;
+    }
+    try {
+      const record = parseDeviceBackup(await store.read());
+      if (!record || !KeyManager._isHealthyPair(record.privateKey, record.publicKey)) {
+        return null;
+      }
+      return {
+        ...record,
+        privateKey: KeyManager.canonicalPrivateKey(record.privateKey),
+        publicKey: record.publicKey.toLowerCase(),
+      };
+    } catch (error) {
+      logger.warn(`Recovery: failed to read the device backup (${store.name})`, { component: 'KeyManager' }, error);
+      return null;
+    }
+  }
+
+  /**
+   * Persist a device-backup candidate, then put its phrase back in the
+   * re-reveal slot (which died with the keystore) when it derives the key.
+   * @internal
+   */
+  private static async _commitDeviceBackupRecovery(record: DeviceBackupRecord): Promise<boolean> {
+    if (!(await KeyManager._commitRecovery(record.privateKey, record.publicKey))) {
+      return false;
+    }
+    if (record.mnemonic && (await KeyManager._phraseDerivesPublicKey(record.mnemonic, record.publicKey))) {
+      try {
+        await KeyManager.storeRecoveryMnemonic(record.mnemonic);
+      } catch (error) {
+        logger.warn('Recovery: restored the identity but not its phrase slot', { component: 'KeyManager' }, error);
+      }
+    }
+    return true;
+  }
+
   /** Read the active-layout backup slot as a healthy candidate, or null. @internal */
   private static async _readBackupCandidate(): Promise<{ privateKey: string; publicKey: string } | null> {
     try {

package/src/index.ts

@@ -320,6 +320,7 @@ export {
     updateIdentityMarker,
 } from './crypto/identityMarker';
 export type { IdentityMarker } from './crypto/identityMarker';
+export type { IdentityDeviceBackupStore } from './crypto/deviceBackup';
 export { SignatureService } from './crypto/signatureService';
 export type { SignedMessage, AuthChallenge } from './crypto/signatureService';
 export { RecoveryPhraseService } from './crypto/recoveryPhrase';
@@ -818,6 +819,7 @@ export type {
     AccountDialogSnapshot,
     AccountDialogView,
     CommonsAvailability,
+    ContextChoiceOutcome,
     PopupWindowHandle,
     SignInFailureReason,
     SignInFlowPhase,

package/src/mixins/OxyServices.linkedAccounts.ts

@@ -0,0 +1,129 @@
+/**
+ * Linked Accounts Methods Mixin
+ *
+ * External accounts (any Mastodon-API server, Bluesky) the current user has
+ * PROVEN they own by completing an OAuth authorization there. Oxy uses that
+ * authorization only to learn which account granted it and then discards the
+ * token — nothing here ever carries a third-party token.
+ *
+ * The flow is a top-level browser navigation: {@link startLinkedAccount} returns
+ * the other network's `authorizeUrl`; open it (a new tab, or
+ * `expo-web-browser`'s auth session on native); the network sends the browser
+ * to Oxy's callback, and Oxy sends it to `returnTo` with `?link_code=<code>` or
+ * `?link_error=<code>`. Pass the code to {@link completeLinkedAccount} with the
+ * same user signed in: that call, not the callback, creates the link, so an
+ * authorization someone else started can never link to them. `returnTo` must
+ * be a redirect URI registered on the first-party application `clientId` names.
+ *
+ * Wire types live in `@oxy.so/contracts` (`linkedAccounts.ts`).
+ */
+import type {
+  CompleteLinkedAccountResponse,
+  LinkedAccount,
+  LinkedAccountListResponse,
+  LinkedAccountNetwork,
+  ServiceLinkedAccountListResponse,
+  StartLinkedAccountRequest,
+  StartLinkedAccountResponse,
+} from '@oxy.so/contracts';
+import type { OxyServicesBase } from '../OxyServices.base';
+
+export function OxyServicesLinkedAccountsMixin<T extends typeof OxyServicesBase>(Base: T) {
+  return class extends Base {
+    /** Inherited from the auth mixin at runtime. */
+    declare makeServiceRequest: <R = unknown>(
+      method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE',
+      url: string,
+      data?: unknown,
+      userId?: string,
+    ) => Promise<R>;
+
+    /**
+     * Begin linking an external account for the current user.
+     *
+     * @param network - `'activitypub'` (any Mastodon-API server) or `'atproto'` (Bluesky).
+     * @param options - `instance` for ActivityPub (`mastodon.social`, or
+     *   `@user@mastodon.social`), `handle` for atproto; `clientId` + `returnTo`
+     *   to be sent back to your app afterwards.
+     * @returns The URL to open, and when the attempt expires (ten minutes).
+     */
+    async startLinkedAccount(
+      network: LinkedAccountNetwork,
+      options: StartLinkedAccountRequest,
+    ): Promise<StartLinkedAccountResponse> {
+      try {
+        return await this.makeRequest<StartLinkedAccountResponse>(
+          'POST',
+          `/linked-accounts/${encodeURIComponent(network)}/start`,
+          options,
+          { cache: false },
+        );
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Finish a link with the `link_code` the callback appended to `returnTo`.
+     * Must be the user who started the flow: for anyone else the API answers
+     * 403 and burns the code. 409 when the account is already someone else's
+     * link. Repeating it within the code's five minutes returns the same link.
+     */
+    async completeLinkedAccount(code: string): Promise<LinkedAccount> {
+      try {
+        const response = await this.makeRequest<CompleteLinkedAccountResponse>(
+          'POST',
+          '/linked-accounts/complete',
+          { code },
+          { cache: false },
+        );
+        return response.linkedAccount;
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /** The current user's live linked accounts, oldest first. */
+    async listLinkedAccounts(): Promise<LinkedAccount[]> {
+      try {
+        const response = await this.makeRequest<LinkedAccountListResponse>('GET', '/linked-accounts', undefined, {
+          cache: false,
+        });
+        return response.linkedAccounts;
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Unlink one of the current user's accounts. An ActivityPub link stops being
+     * published as an `alsoKnownAs` alias, and the external account can then be
+     * linked to another Oxy account.
+     */
+    async revokeLinkedAccount(linkedAccountId: string): Promise<void> {
+      try {
+        await this.makeRequest<void>('DELETE', `/linked-accounts/${encodeURIComponent(linkedAccountId)}`, undefined, {
+          cache: false,
+        });
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * SERVICE: a user's live linked accounts, each with the federated shadow
+     * user Oxy already holds for it (`federatedUserId`). Requires a service
+     * credential whose application holds the privileged `linked-accounts:read`.
+     */
+    async getLinkedAccountsForUser(userId: string): Promise<ServiceLinkedAccountListResponse> {
+      try {
+        return await this.makeServiceRequest<ServiceLinkedAccountListResponse>(
+          'GET',
+          `/linked-accounts/by-user/${encodeURIComponent(userId)}`,
+        );
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+  };
+}

package/src/mixins/OxyServices.user.ts

@@ -1,6 +1,7 @@
 /**
  * User Management Methods Mixin
  */
+import type { CreateOxyNotificationRequest } from '@oxy.so/contracts';
 import type {
   User,
   Notification,
@@ -1099,9 +1100,13 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
     }
 
     /**
-     * Create notification
+     * Create a notification (`POST /notifications`; the API requires a service
+     * token whose application holds `notifications:write`). `type` is one of
+     * `OXY_NOTIFICATION_TYPES` from `@oxy.so/contracts` — `system` for a message
+     * from an Oxy service about the recipient's own account, with the recipient
+     * as actor and their profile as the entity.
      */
-    async createNotification(data: Partial<Notification>): Promise<Notification> {
+    async createNotification(data: CreateOxyNotificationRequest | Partial<Notification>): Promise<Notification> {
       try {
         return await this.makeRequest<Notification>('POST', '/notifications', data, { cache: false });
       } catch (error) {

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

@@ -0,0 +1,109 @@
+/**
+ * Linked-accounts SDK surface: the paths, methods and bodies it sends, and the
+ * `{ data }` unwrapping. The flow itself is exercised in the API's route tests.
+ */
+
+import { OxyServices } from '../../OxyServices';
+
+function makeJwt(payload: Record<string, unknown>): string {
+  const b64url = (obj: Record<string, unknown>): string => Buffer.from(JSON.stringify(obj)).toString('base64url');
+  const fullPayload = { exp: Math.floor(Date.now() / 1000) + 3600, ...payload };
+  return `${b64url({ alg: 'none', typ: 'JWT' })}.${b64url(fullPayload)}.sig`;
+}
+
+function jsonResponse(data: unknown, status = 200): Response {
+  return new Response(status === 204 ? null : JSON.stringify({ data }), {
+    status,
+    headers: { 'content-type': 'application/json' },
+  });
+}
+
+const LINK = {
+  id: 'link-1',
+  network: 'activitypub' as const,
+  accountKey: 'nate@mastodon.social',
+  actorUri: 'https://mastodon.social/users/nate',
+  handle: '@nate@mastodon.social',
+  host: 'mastodon.social',
+  proofMethod: 'oauth' as const,
+  verifiedAt: '2026-09-25T00:00:00.000Z',
+  createdAt: '2026-09-25T00:00:00.000Z',
+};
+
+describe('linked accounts', () => {
+  let originalFetch: typeof globalThis.fetch;
+  let fetchMock: jest.Mock<Promise<Response>, [RequestInfo | URL, RequestInit?]>;
+  let oxy: OxyServices;
+
+  beforeEach(() => {
+    originalFetch = globalThis.fetch;
+    fetchMock = jest.fn();
+    globalThis.fetch = fetchMock as unknown as typeof globalThis.fetch;
+    oxy = new OxyServices({ baseURL: 'http://test.invalid' });
+    oxy.httpService.setTokens(makeJwt({ userId: 'me' }));
+  });
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+    jest.clearAllMocks();
+  });
+
+  it('starts a link with POST /linked-accounts/:network/start and returns the authorize URL', async () => {
+    fetchMock.mockResolvedValueOnce(
+      jsonResponse({ authorizeUrl: 'https://mastodon.social/oauth/authorize?x=1', expiresAt: '2026-09-25T00:10:00.000Z' }),
+    );
+    const started = await oxy.startLinkedAccount('activitypub', {
+      instance: 'mastodon.social',
+      clientId: 'oxy_dk_move',
+      returnTo: 'https://move.oxy.so/linked',
+    });
+    expect(started.authorizeUrl).toBe('https://mastodon.social/oauth/authorize?x=1');
+    const [url, init] = fetchMock.mock.calls[0];
+    expect(String(url)).toBe('http://test.invalid/linked-accounts/activitypub/start');
+    expect(init?.method).toBe('POST');
+    expect(JSON.parse(String(init?.body))).toEqual({
+      instance: 'mastodon.social',
+      clientId: 'oxy_dk_move',
+      returnTo: 'https://move.oxy.so/linked',
+    });
+  });
+
+  it('completes a link with POST /linked-accounts/complete and returns the link', async () => {
+    fetchMock.mockImplementation(async (url) =>
+      String(url).endsWith('/linked-accounts/complete') ? jsonResponse({ linkedAccount: LINK }) : jsonResponse({ csrfToken: 't'.repeat(32) }),
+    );
+    expect(await oxy.completeLinkedAccount('one-time-code')).toEqual(LINK);
+    const completion = fetchMock.mock.calls.find(([url]) => String(url).endsWith('/linked-accounts/complete'));
+    expect(completion?.[1]?.method).toBe('POST');
+    expect(JSON.parse(String(completion?.[1]?.body))).toEqual({ code: 'one-time-code' });
+  });
+
+  it('lists the live links, unwrapping the envelope, without caching', async () => {
+    fetchMock.mockImplementation(async () => jsonResponse({ linkedAccounts: [LINK] }));
+    expect(await oxy.listLinkedAccounts()).toEqual([LINK]);
+    await oxy.listLinkedAccounts();
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+    expect(String(fetchMock.mock.calls[0][0])).toBe('http://test.invalid/linked-accounts');
+  });
+
+  it('revokes with DELETE /linked-accounts/:id', async () => {
+    // A state-changing request may first fetch a CSRF token; answer anything.
+    fetchMock.mockImplementation(async (_url, init) =>
+      init?.method === 'DELETE' ? new Response(null, { status: 204 }) : jsonResponse({ csrfToken: 't'.repeat(32) }),
+    );
+    await oxy.revokeLinkedAccount('link-1');
+    const deletion = fetchMock.mock.calls.find(([, init]) => init?.method === 'DELETE');
+    expect(String(deletion?.[0])).toBe('http://test.invalid/linked-accounts/link-1');
+  });
+
+  it('reads a user\'s links on the service lane with a service token', async () => {
+    const service = new OxyServices({ baseURL: 'http://test.invalid' });
+    jest.spyOn(service, 'getServiceToken').mockResolvedValue('service-token');
+    fetchMock.mockResolvedValueOnce(jsonResponse({ userId: 'u1', linkedAccounts: [{ ...LINK, federatedUserId: null }] }));
+    const result = await service.getLinkedAccountsForUser('u1');
+    expect(result.linkedAccounts[0].federatedUserId).toBeNull();
+    const [url, init] = fetchMock.mock.calls[0];
+    expect(String(url)).toBe('http://test.invalid/linked-accounts/by-user/u1');
+    expect(new Headers(init?.headers).get('authorization')).toBe('Bearer service-token');
+  });
+});

package/src/mixins/index.ts

@@ -35,6 +35,7 @@ import { OxyServicesNodesMixin } from './OxyServices.nodes';
 import { OxyServicesFollowGraphMixin } from './OxyServices.followGraph';
 import { OxyServicesInferenceMixin } from './OxyServices.inference';
 import { OxyServicesDeviceBootMixin } from './OxyServices.deviceBoot';
+import { OxyServicesLinkedAccountsMixin } from './OxyServices.linkedAccounts';
 
 /**
  * Instance shape of every mixin in the pipeline, intersected. The runtime
@@ -74,6 +75,7 @@ type AllMixinInstances =
   & InstanceType<ReturnType<typeof OxyServicesFollowGraphMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesInferenceMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesDeviceBootMixin<typeof OxyServicesBase>>>
+  & InstanceType<ReturnType<typeof OxyServicesLinkedAccountsMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesUtilityMixin<typeof OxyServicesBase>>>;
 
 /**
@@ -165,6 +167,10 @@ const MIXIN_PIPELINE: MixinFunction[] = [
     // (`mintFromDeviceSecret` → `POST /session/device/token`).
     OxyServicesDeviceBootMixin,
 
+    // Linked external accounts (Mastodon-API, Bluesky) proven by OAuth; the
+    // service read uses the auth mixin's `makeServiceRequest`.
+    OxyServicesLinkedAccountsMixin,
+
     // Device-to-device identity transfer ("add a device"): E2E-encrypted key
     // clone over a short-lived relay (b3 Feature 2).