@oxy.so/core 1.0.0

package/src/boot/sessionColdBoot.ts

@@ -0,0 +1,529 @@
+/**
+ * Device-first session cold boot for every consumer.
+ *
+ * On a fresh page load / app launch this resolves the device's session in a
+ * deterministic order, built on the pure `runColdBoot` primitive. It NEVER
+ * redirects to a login page: an unresolved boot ends in a signed-out state that
+ * the app renders with a "Sign in with Oxy" button.
+ *
+ * Ordered steps (first to yield a session wins):
+ *   1. `warm-token-plant` (web + native) — the fastest path: when the persisted
+ *      store still holds a warm access token that is valid for more than the
+ *      refresh lead window, plant it and yield the session with NO network
+ *      round-trip. The background scheduler rotates it shortly after.
+ *   2. `device-secret-mint` (web + native) — the zero-cookie transport: when the
+ *      origin persisted a `deviceId` + `deviceSecret`, mint a short access token
+ *      with a single bearer-less POST to `/session/device/token` (no cookie, no
+ *      navigation) and rotate the secret in-use.
+ *   3. `shared-device-adopt` (native, ACCOUNT mode) — this app has no credential
+ *      of its own but a sibling official app already put one in the shared native
+ *      slot: adopt it and mint. This is how a newly installed official app joins
+ *      the device's existing session WITHOUT another QR and without ever touching
+ *      the Commons private key.
+ *   4. `shared-key-signin` (native, ACCOUNT mode) — the legacy lane: re-mint by
+ *      signing with the shared-keychain IDENTITY key. Retained as a recovery /
+ *      compatibility path for devices whose apps have not yet published a shared
+ *      device credential — OR `identity-key-signin` (IDENTITY mode) — re-mint
+ *      from THIS device's primary identity key.
+ *   5. Signed out.
+ *
+ * Two session modes (see {@link RunSessionColdBootOptions.sessionMode}):
+ *   - `account` (default) — the device's ACTIVE account owns the session. Every
+ *     Oxy app but the identity vault boots this way; behaviour is unchanged.
+ *   - `identity` — the owner of the local PRIMARY identity key owns the session,
+ *     permanently, regardless of which account the device is switched to. Each
+ *     step above is bound to the persisted identity pin, and the shared-keychain
+ *     lane is replaced by the primary-key one (the shared slot is a CROSS-APP
+ *     slot that may hold a different identity).
+ *
+ * ESM-safe (no `require()`); no react/react-native/expo imports.
+ */
+import { runColdBoot, type ColdBootOutcome, type ColdBootStep } from '../utils/coldBoot';
+import { isNative as detectNative } from '../utils/platform';
+import { logger } from '../logger';
+import { computeIdentityTag } from '../utils/cacheKey';
+import { TOKEN_REFRESH_LEAD_MS, refreshDeviceSecretArm } from '../session/refresh';
+import {
+  establishIdentitySession,
+  resolveIdentityPin,
+  type IdentityBinding,
+} from '../session/identitySession';
+import type { IdentityPin } from '../session/identityPin';
+import {
+  decideSharedDeviceJoin,
+  type SharedDeviceCredentialStore,
+} from '../session/sharedDeviceCredential';
+import type { OxyServices } from '../OxyServices';
+import type { AuthStateStore, PersistedAuthState } from '../session/authStateStore';
+import type { DeviceSessionState } from '@oxy.so/contracts';
+
+/**
+ * Who owns the session this boot resolves.
+ *
+ * - `account` — the device's active account (every ordinary Oxy app).
+ * - `identity` — the owner of the device's primary identity key (the identity
+ *   vault). Requires {@link RunSessionColdBootOptions.identity}.
+ */
+export type SessionMode = 'account' | 'identity';
+
+/** The winning session shape a cold-boot step reports. */
+export interface DeviceBootSession {
+  sessionId: string;
+  userId: string;
+  accessToken: string;
+  /** Server state already returned by the mint; absent on warm-token restore. */
+  state?: DeviceSessionState;
+}
+
+/** Why a cold boot ended without a session. */
+export type SignedOutReason = 'no_session' | 'error';
+
+export interface RunSessionColdBootOptions {
+  oxy: OxyServices;
+  store: AuthStateStore;
+  /** Platform hints; default derived from `@oxy.so/core`'s platform detection. */
+  platform?: { isWeb?: boolean; isNative?: boolean };
+  /** Invoked with the winning session (token already planted). */
+  onSession?: (session: DeviceBootSession & { via: string }) => void | Promise<void>;
+  /** Invoked when the boot ended signed out. */
+  onSignedOut?: (reason: SignedOutReason) => void | Promise<void>;
+  onStepError?: (id: string, error: unknown) => void;
+  /**
+   * HARD overall deadline (ms) for the whole ordered step chain, forwarded to
+   * {@link runColdBoot}. Defense-in-depth so a single non-settling network step
+   * (a black-hole network that neither connects nor rejects) can NEVER hang the
+   * boot — and therefore app routing — indefinitely. Inert on healthy loads
+   * (every step settles well under it); only trips on pathological networks.
+   * When omitted there is no overall deadline (unchanged behavior).
+   */
+  overallDeadlineMs?: number;
+  /**
+   * Invoked once per step abandoned because {@link overallDeadlineMs} expired
+   * before it settled. Forwarded to {@link runColdBoot}. Must not throw.
+   */
+  onStepDeadline?: (stepId: string) => void;
+  /**
+   * Best-effort connectivity hint. When it returns `true` the two NETWORK steps
+   * (`device-secret-mint`, `shared-key-signin`) are skipped — an offline device
+   * cannot mint, and attempting to would burn the whole deadline on a doomed
+   * request before routing settles. The pure-local `warm-token-plant` step is
+   * NEVER gated by this: an offline returning user with an unexpired persisted
+   * token must still boot authenticated. Only an EXPLICIT offline verdict should
+   * be returned; the caller resolves unknown/timeout to `false` (assume online)
+   * so a flaky probe can never falsely skip a real sign-in.
+   */
+  isOffline?: () => boolean;
+  /**
+   * Who owns the resolved session. Defaults to `'account'` — the device's active
+   * account — which is the behaviour every ordinary Oxy app has today and which
+   * this option leaves byte-for-byte unchanged.
+   *
+   * `'identity'` binds the boot to the owner of this device's PRIMARY identity
+   * key and REQUIRES {@link identity}. When it is missing the boot refuses to
+   * run any lane (an identity-bound client silently falling back to the device's
+   * active account is precisely the bug this mode exists to prevent) and
+   * resolves signed out.
+   */
+  sessionMode?: SessionMode;
+  /**
+   * The identity binding (pin store + key/signature access) used by
+   * `sessionMode: 'identity'`. Ignored in `'account'` mode.
+   */
+  identity?: IdentityBinding;
+  /**
+   * The cross-app native slot holding this device's shared DeviceSession
+   * credential, enabling the `shared-device-adopt` lane. Supplied by
+   * `@oxy.so/services` on native; absent on web, where each origin is its own
+   * device by design.
+   *
+   * IGNORED in `sessionMode: 'identity'`. The shared slot belongs to whichever
+   * principal signed in on this device; an identity-bound client must resolve
+   * its session from the local key alone, and adopting a device credential is
+   * exactly the drift that mode exists to prevent.
+   */
+  sharedDeviceCredential?: SharedDeviceCredentialStore;
+}
+
+/**
+ * Run the device-first cold boot. Resolves to the `runColdBoot` outcome and, as
+ * a side effect, invokes `onSession` (winning session, token already planted) or
+ * `onSignedOut` (no session).
+ */
+export async function runSessionColdBoot(
+  opts: RunSessionColdBootOptions,
+): Promise<ColdBootOutcome<DeviceBootSession>> {
+  const { oxy, store } = opts;
+  const isNative = opts.platform?.isNative ?? detectNative();
+
+  // Non-null ONLY in identity mode; every `!== null` test below therefore reads
+  // as "is this boot identity-bound?" while also narrowing the binding.
+  const identityBinding = opts.sessionMode === 'identity' ? opts.identity ?? null : null;
+  if (opts.sessionMode === 'identity' && identityBinding === null) {
+    logger.error(
+      'runSessionColdBoot: sessionMode "identity" requires an `identity` binding — refusing to run any lane (an identity-bound client must never adopt the device active account)',
+      undefined,
+      { component: 'sessionColdBoot', method: 'runSessionColdBoot' },
+    );
+    await opts.onSignedOut?.('error');
+    return { kind: 'unauthenticated' };
+  }
+
+  // Best-effort connectivity gate for the NETWORK steps only. A missing hint or
+  // any non-`true` verdict means "assume online" — never falsely skip a real
+  // sign-in on an ambiguous probe.
+  const isOffline = (): boolean => opts.isOffline?.() ?? false;
+
+  // Boot-local (not module-level) so it cannot leak across boots or break under
+  // bundler re-evaluation.
+  let signedOutReason: SignedOutReason = 'no_session';
+
+  // Boot-local memo for the identity pin. Resolved lazily INSIDE a step so the
+  // (local, but storage-backed) read is covered by `overallDeadlineMs`, and
+  // resolved at most once per boot so two steps cannot disagree. Always `null`
+  // in account mode.
+  let pinResolved = false;
+  let cachedPin: IdentityPin | null = null;
+  const getIdentityPin = async (): Promise<IdentityPin | null> => {
+    if (identityBinding === null) {
+      return null;
+    }
+    if (!pinResolved) {
+      cachedPin = await resolveIdentityPin(identityBinding);
+      pinResolved = true;
+    }
+    return cachedPin;
+  };
+
+  const steps: Array<ColdBootStep<DeviceBootSession>> = [];
+
+  // 1. warm-token-plant (web + native) — the fastest path. When the persisted
+  //    store already holds a still-valid warm access token (its expiry more than
+  //    the refresh lead window away) plus its owning session identity, plant it
+  //    and yield the session IMMEDIATELY, skipping the blocking mint round-trip on
+  //    first paint. The token is used AS-IS: this step NEVER mints, rotates, or
+  //    persists anything. The proactive `startTokenRefreshScheduler` + the
+  //    request-time preflight (both wired in the services provider) rotate it in
+  //    the background; a revoked token self-heals via the 401 -> re-mint -> clear
+  //    path. This exposure is sanctioned by `authStateStore.ts` (~L30-36): the
+  //    warm token is short-lived and adds nothing over the already-persisted
+  //    `deviceSecret`.
+  steps.push({
+    id: 'warm-token-plant',
+    run: async () => {
+      const persisted = await store.load();
+      if (!persisted?.accessToken || !persisted.sessionId || !persisted.userId || !persisted.expiresAt) {
+        return { kind: 'skip' };
+      }
+      // Guard a malformed `expiresAt` (Date.parse -> NaN): treat as not-valid and
+      // fall through to the mint lane. A token still inside the refresh lead
+      // window (or already expired) is likewise skipped — let the mint lane get a
+      // fresh one rather than plant a token about to expire.
+      const expiresAtMs = new Date(persisted.expiresAt).getTime();
+      if (!Number.isFinite(expiresAtMs) || expiresAtMs <= Date.now() + TOKEN_REFRESH_LEAD_MS) {
+        return { kind: 'skip' };
+      }
+      if (identityBinding !== null) {
+        // Identity-bound: a persisted token is only acceptable when it belongs to
+        // the PINNED account. Both the token's own claim (`computeIdentityTag`,
+        // the same derivation `SessionClient.applyState` uses) and the owning
+        // session identity must match — a token planted for another account by an
+        // earlier account-mode write is exactly the durable drift this gate stops.
+        const pin = await getIdentityPin();
+        if (
+          pin === null ||
+          persisted.userId !== pin.accountId ||
+          computeIdentityTag(persisted.accessToken) !== pin.accountId
+        ) {
+          return { kind: 'skip' };
+        }
+      }
+      oxy.setTokens(persisted.accessToken);
+      return {
+        kind: 'session',
+        session: {
+          sessionId: persisted.sessionId,
+          userId: persisted.userId,
+          accessToken: persisted.accessToken,
+        },
+      };
+    },
+  });
+
+  // 2. device-secret-mint (web + native) — the zero-cookie fast path. When the
+  //    origin persisted a deviceId + deviceSecret, mint a short access token with
+  //    a single bearer-less POST (no cookie, no navigation). The mint itself runs
+  //    through `refreshDeviceSecretArm`, which acquires the client's PROCESS-WIDE
+  //    single-flight, persists `nextDeviceSecret` BEFORE planting the token, and
+  //    returns a classified outcome — so concurrent mint lanes share one in-flight
+  //    request and the durable store always converges on the server's credential.
+  steps.push({
+    id: 'device-secret-mint',
+    // Network step — skip entirely when the caller reports the device offline so
+    // a doomed mint cannot burn the overall deadline before routing settles.
+    enabled: () => !isOffline(),
+    run: async () => {
+      const pin = await getIdentityPin();
+      if (identityBinding !== null && pin === null) {
+        // Identity-bound with no verified pin (never written, or cleared because
+        // the local key changed/vanished). An UNPINNED mint would adopt whichever
+        // account the device is currently switched to — the exact drift this mode
+        // exists to prevent. Fall through to `identity-key-signin`, which
+        // re-derives the account from the local key and rewrites the pin.
+        return { kind: 'skip' };
+      }
+      const result = await refreshDeviceSecretArm({ oxy, store, pin });
+      switch (result.status) {
+        case 'ok':
+          // The arm persisted nextDeviceSecret and planted the token.
+          return {
+            kind: 'session',
+            session: {
+              sessionId: result.sessionId,
+              userId: result.userId,
+              accessToken: result.token,
+              state: result.state,
+            },
+          };
+        case 'invalid-secret': {
+          // Stale/diverged secret — drop it so the mint lane stops firing. On
+          // native the shared-key step below can still recover; on web this ends
+          // signed out. Setting it undefined drops the key on the store's JSON
+          // serialization, and the mint guard treats undefined as absent.
+          const persisted = await store.load();
+          if (persisted) {
+            await store.save({ ...persisted, deviceSecret: undefined });
+          }
+          return { kind: 'skip' };
+        }
+        case 'no-session':
+          // Device known, no live session — authoritative signed-out. Keep the
+          // secret (the device may sign in again).
+          signedOutReason = 'no_session';
+          return { kind: 'skip' };
+        case 'persist-failed':
+          // The mint rotated the secret but it could not be durably persisted —
+          // refuse to advertise a session that will not survive a reload. Keep
+          // the secret; a later boot/attempt re-mints once storage recovers.
+          logger.error(
+            'device-secret mint rotated the secret but it could not be durably persisted — not planting',
+            undefined,
+            { component: 'sessionColdBoot', method: 'device-secret-mint' },
+          );
+          return { kind: 'skip' };
+        case 'account-not-on-device':
+          // Pinned mint rejected: the pinned account is no longer a live account
+          // of this device session. The secret is healthy — keep it untouched and
+          // let `identity-key-signin` re-establish from the local key.
+          logger.debug(
+            'pinned device-secret mint rejected (account_not_on_device) — keeping secret, re-establishing from the identity key',
+            { component: 'sessionColdBoot', method: 'device-secret-mint' },
+          );
+          return { kind: 'skip' };
+        case 'transient':
+          // Network / 5xx: keep the secret; a later attempt can succeed.
+          logger.debug(
+            'device-secret mint failed (transient) — keeping secret',
+            { component: 'sessionColdBoot', method: 'device-secret-mint' },
+          );
+          return { kind: 'skip' };
+        case 'no-secret':
+          return { kind: 'skip' };
+      }
+    },
+  });
+
+  if (identityBinding !== null) {
+    // 3-identity. identity-key-signin — re-mint from THIS device's PRIMARY
+    //    identity key (`getPublicKey` → challenge → sign → verify). It REPLACES
+    //    `shared-key-signin`, which reads the CROSS-APP shared keychain slot and
+    //    may therefore hold a different identity than the device's primary — the
+    //    one thing an identity-bound client must never adopt. The server resolves
+    //    the account from the verified signer, so the winning session is
+    //    identity-authoritative and the pin is (re)written from it.
+    //
+    //    Online-gated like every network step; `{ retry: false }` keeps the two
+    //    round-trips single attempts (the refresh scheduler / 401 lane own later
+    //    retries) so this step cannot multiply boot latency. On web
+    //    `KeyManager.getPublicKey()` resolves to `null`, so it skips.
+    steps.push({
+      id: 'identity-key-signin',
+      enabled: () => !isOffline(),
+      run: async () => {
+        const established = await establishIdentitySession({
+          oxy,
+          store,
+          binding: identityBinding,
+          requestOptions: { retry: false },
+        });
+        const accessToken = established?.session.accessToken;
+        if (!established || !accessToken) {
+          return { kind: 'skip' };
+        }
+        return {
+          kind: 'session',
+          session: {
+            sessionId: established.session.sessionId,
+            userId: established.session.user.id,
+            accessToken,
+          },
+        };
+      },
+    });
+  } else if (opts.sharedDeviceCredential) {
+    // 3. shared-device-adopt (native, ACCOUNT mode) — join the device's existing
+    //    session through the shared native credential slot.
+    //
+    //    This is the lane that separates identity from session transport. What it
+    //    reads is an ordinary, individually revocable `deviceId` + `deviceSecret`
+    //    put there by a sibling official app — never the Commons private key. It
+    //    is what lets a freshly installed official app land signed in with no QR,
+    //    and it is why an ordinary app never needs identity-key access at all.
+    //
+    //    `decideSharedDeviceJoin` gates it: an app that already holds its own
+    //    credential is never moved, and an UNREADABLE slot is never mistaken for
+    //    an empty one. The lane therefore cannot sign anyone out, in either
+    //    upgrade order.
+    const sharedSlot = opts.sharedDeviceCredential;
+    steps.push({
+      id: 'shared-device-adopt',
+      // The adoption itself is local, but it is only worth committing alongside
+      // a mint that proves the credential — so the whole lane is online-gated
+      // like every other network step.
+      enabled: () => isNative && !isOffline(),
+      run: async () => {
+        const before = await store.load();
+        const decision = decideSharedDeviceJoin(before, await sharedSlot.read());
+        if (decision.action === 'skip') {
+          logger.debug(
+            `shared device credential not adopted (${decision.reason})`,
+            { component: 'sessionColdBoot', method: 'shared-device-adopt' },
+          );
+          return { kind: 'skip' };
+        }
+
+        // Restore the store to exactly what it held before this lane touched it.
+        // A credential we adopted and could not prove must not be left behind for
+        // the next boot's mint lane to keep retrying.
+        const revert = async (): Promise<void> => {
+          if (before) {
+            await store.save(before);
+          } else {
+            await store.clear();
+          }
+        };
+
+        const adopted: PersistedAuthState = {
+          // The mint fills both in from the device's live state; carrying the
+          // previous session's ids into a different device session would be a
+          // lie for however long the mint takes.
+          sessionId: '',
+          userId: '',
+          deviceId: decision.credential.deviceId,
+          deviceSecret: decision.credential.deviceSecret,
+        };
+        if (!(await store.save(adopted))) {
+          logger.error(
+            'adopted the shared device credential but it could not be durably persisted — reverting',
+            undefined,
+            { component: 'sessionColdBoot', method: 'shared-device-adopt' },
+          );
+          await revert();
+          return { kind: 'skip' };
+        }
+
+        const result = await refreshDeviceSecretArm({ oxy, store, pin: null });
+        if (result.status === 'ok') {
+          return {
+            kind: 'session',
+            session: {
+              sessionId: result.sessionId,
+              userId: result.userId,
+              accessToken: result.token,
+            },
+          };
+        }
+
+        if (result.status === 'invalid-secret') {
+          // The one place we hold POSITIVE proof that the exact bytes in the
+          // shared slot are dead — the server rejected them by name. Clearing it
+          // signs nobody out (a credential the server does not recognise cannot
+          // be minting for anyone) and it is what stops a dead credential from
+          // blocking every future install: a stale slot owned by a different
+          // `deviceId` is otherwise never overwritten, by design.
+          await sharedSlot.clear();
+        } else if (result.status === 'no-session') {
+          signedOutReason = 'no_session';
+        }
+        await revert();
+        return { kind: 'skip' };
+      },
+    });
+  }
+
+  if (identityBinding === null) {
+    // 4. shared-key-signin (native) — the RECOVERY / COMPATIBILITY lane: sign a
+    //    challenge with the shared-keychain IDENTITY key to re-mint a session.
+    //
+    //    It runs LAST on purpose. Using the self-custody key to obtain an ordinary
+    //    session is the over-sharing #937 sets out to end, so it is now reachable
+    //    only on a device where no sibling app has published a shared device
+    //    credential yet — an install that predates this lane, or one where the
+    //    shared slot is unreadable. Its own `store.save` below feeds the shared
+    //    slot through the mirroring store, so the FIRST boot that takes this lane
+    //    is also the last one that needs to: every later app joins by credential.
+    //
+    //    Native AND online: it is a network step (challenge + verify round-trips),
+    //    so it is gated by the same offline hint as the mint lane. `{ retry: false }`
+    //    keeps the two round-trips as single attempts — the refresh scheduler /
+    //    401 lane own later retries — so this step cannot multiply boot latency.
+    steps.push({
+      id: 'shared-key-signin',
+      enabled: () => isNative && !isOffline(),
+      run: async () => {
+        const session = await oxy.signInWithSharedIdentity({ requestOptions: { retry: false } });
+        if (!session?.accessToken) {
+          return { kind: 'skip' };
+        }
+        // `verifyChallenge` mints a rotating deviceSecret; persist it so the next
+        // boot can use the faster device-secret-mint lane (sockets + tab-focus
+        // re-mint depend on the credential being in the store).
+        if (session.deviceId && session.deviceSecret) {
+          await store.save({
+            sessionId: session.sessionId,
+            userId: session.user.id,
+            deviceId: session.deviceId,
+            deviceSecret: session.deviceSecret,
+            accessToken: session.accessToken,
+            expiresAt: session.expiresAt,
+          });
+        }
+        return {
+          kind: 'session',
+          session: {
+            sessionId: session.sessionId,
+            userId: session.user.id,
+            accessToken: session.accessToken,
+          },
+        };
+      },
+    });
+  }
+
+  const outcome = await runColdBoot<DeviceBootSession>({
+    steps,
+    overallDeadlineMs: opts.overallDeadlineMs,
+    onStepDeadline: opts.onStepDeadline,
+    onStepError: (id, error) => {
+      signedOutReason = 'error';
+      opts.onStepError?.(id, error);
+    },
+  });
+
+  if (outcome.kind === 'session') {
+    await opts.onSession?.({ ...outcome.session, via: outcome.via });
+    return outcome;
+  }
+
+  await opts.onSignedOut?.(signedOutReason);
+  return outcome;
+}

package/src/constants/version.ts

@@ -0,0 +1,15 @@
+/**
+ * Package version and metadata constants
+ * This file is auto-generated to avoid runtime dependency on package.json
+ */
+
+export const packageInfo = {
+    name: "@oxy.so/services",
+    version: "5.2.1",
+    description: "Reusable OxyHQ module to handle authentication, user management, reputation system (Oxy Trust) and more 🚀",
+    main: "lib/commonjs/node/index.js",
+    module: "lib/module/node/index.js",
+    types: "lib/typescript/node/index.d.ts"
+} as const;
+
+export const { name, version, description } = packageInfo;

package/src/crypto/__tests__/backupMaterial.test.ts

@@ -0,0 +1,86 @@
+/**
+ * RecoveryPhraseService.deriveBackupMaterial — encrypted off-device backup key
+ * schedule (b3 Feature 1).
+ *
+ * The two outputs are derived from the FULL 64-byte BIP-39 seed via HKDF-SHA256
+ * with domain-separated `info` labels. These tests PIN the derivation against a
+ * fixed phrase so an accidental algorithm/library/label swap is caught as a
+ * regression, and assert the domain separation is real (backup key ≠ lookup id ≠
+ * the raw private key, all from the same seed).
+ *
+ * The fixed phrase is the canonical BIP-39 all-zero-entropy vector
+ * ("abandon…about"), whose seed is the published `5eb00bbd…ce9e38e4` — so the
+ * pinned outputs below are reproducible from any independent HKDF-SHA256
+ * implementation over that seed.
+ */
+import { RecoveryPhraseService } from '../recoveryPhrase';
+import { KeyManager } from '../keyManager';
+
+const FIXED_PHRASE =
+  'abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about';
+
+// Pinned outputs (independently reproducible — see file header).
+const EXPECTED_BACKUP_KEY_HEX = 'c6bb29585610550e2667a9d05f35d081f67dd8ccee20a04488c39b25f47a9e74';
+const EXPECTED_LOOKUP_ID = '8cad137ca961bfc62a2ef329869e8369777737c7c5353a8d94bb70d888c0ad0d';
+// The raw private key = seed[0:32] (the FROZEN phrase→privateKey derivation).
+const EXPECTED_PRIVATE_KEY = '5eb00bbddcf069084889a8ab9155568165f5c453ccb85e70811aaed6f6da5fc1';
+
+const toHex = (bytes: Uint8Array): string => Buffer.from(bytes).toString('hex');
+
+describe('RecoveryPhraseService.deriveBackupMaterial (KDF vectors)', () => {
+  it('derives the pinned backupKey + lookupId for the fixed phrase', async () => {
+    const { backupKey, lookupId } = await RecoveryPhraseService.deriveBackupMaterial(FIXED_PHRASE);
+
+    expect(backupKey).toBeInstanceOf(Uint8Array);
+    expect(backupKey).toHaveLength(32);
+    expect(toHex(backupKey)).toBe(EXPECTED_BACKUP_KEY_HEX);
+
+    expect(lookupId).toBe(EXPECTED_LOOKUP_ID);
+    expect(lookupId).toMatch(/^[0-9a-f]{64}$/);
+  });
+
+  it('is deterministic (same phrase → identical material)', async () => {
+    const a = await RecoveryPhraseService.deriveBackupMaterial(FIXED_PHRASE);
+    const b = await RecoveryPhraseService.deriveBackupMaterial(FIXED_PHRASE);
+    expect(toHex(a.backupKey)).toBe(toHex(b.backupKey));
+    expect(a.lookupId).toBe(b.lookupId);
+  });
+
+  it('normalizes case/whitespace like the other phrase helpers', async () => {
+    const messy = `  ${FIXED_PHRASE.toUpperCase()}  `;
+    const { backupKey, lookupId } = await RecoveryPhraseService.deriveBackupMaterial(messy);
+    expect(toHex(backupKey)).toBe(EXPECTED_BACKUP_KEY_HEX);
+    expect(lookupId).toBe(EXPECTED_LOOKUP_ID);
+  });
+
+  it('enforces real domain separation (backupKey ≠ lookupId ≠ raw private key)', async () => {
+    const { backupKey, lookupId } = await RecoveryPhraseService.deriveBackupMaterial(FIXED_PHRASE);
+    const privateKey = await RecoveryPhraseService.derivePrivateKeyFromPhrase(FIXED_PHRASE);
+
+    // Sanity: the frozen phrase→privateKey path is unchanged.
+    expect(privateKey).toBe(EXPECTED_PRIVATE_KEY);
+
+    // The three derivations from the SAME seed are mutually distinct — a device
+    // compromise leaking only the 32-byte private key reveals nothing about the
+    // backup key or lookup id (both need the full 64-byte seed).
+    expect(toHex(backupKey)).not.toBe(lookupId);
+    expect(toHex(backupKey)).not.toBe(privateKey);
+    expect(lookupId).not.toBe(privateKey);
+  });
+
+  it('produces a valid signing key material that is NOT the backup key', async () => {
+    // Extra guard: the backupKey must never coincide with a usable identity key
+    // for this phrase.
+    const { backupKey } = await RecoveryPhraseService.deriveBackupMaterial(FIXED_PHRASE);
+    const privateKey = await RecoveryPhraseService.derivePrivateKeyFromPhrase(FIXED_PHRASE);
+    const publicKey = KeyManager.derivePublicKey(privateKey);
+    expect(publicKey).toMatch(/^04[0-9a-f]+$/);
+    expect(toHex(backupKey)).not.toBe(privateKey);
+  });
+
+  it('rejects an invalid recovery phrase', async () => {
+    await expect(RecoveryPhraseService.deriveBackupMaterial('not a real phrase')).rejects.toThrow(
+      /Invalid recovery phrase/,
+    );
+  });
+});