@oxyhq/core 9.2.0 → 9.2.2

package/dist/types/index.d.ts

@@ -34,7 +34,8 @@ export type { CanonicalUserHandleInput, UserHandleInput } from './utils/userHand
 export { normalizeProfileLinks } from './utils/profileLinks';
 export type { ProfileLink, ProfileLinkMetadata } from './utils/profileLinks';
 export type { PublicApplication, ConnectedApp, } from './mixins/OxyServices.connectedApps';
-export type { AccountKind, AccountRelationship, AccountRole, AccountMemberStatus, AccountMemberSource, AccountMember, AccountNode, AccountCredentialType, AccountCredentialEnvironment, AccountCredentialStatus, AccountCredential, AccountCredentialWithSecret, RotateAccountCredentialResult, ListAccountsOptions, CreateAccountInput, UpdateAccountInput, InviteAccountMemberInput, UpdateAccountMemberInput, TransferAccountOwnershipInput, CreateAccountCredentialInput, AccountSuccessResult, SwitchAccountResult, Application, ApplicationType, ApplicationStatus, ApplicationCredential, ApplicationCredentialType, ApplicationCredentialStatus, ApplicationEnvironment, CreateApplicationInput, UpdateApplicationInput, CreateApplicationCredentialInput, ApplicationCredentialWithSecret, RotateApplicationCredentialResult, ApplicationUsagePeriod, ApplicationUsageSummary, ApplicationUsageByDay, ApplicationUsageByEndpoint, ApplicationUsageStats, } from './mixins/OxyServices.accounts';
+export type { AccountKind, OrganizationCategory, AccountRelationship, AccountRole, AccountMemberStatus, AccountMemberSource, AccountMember, AccountNode, AccountCredentialType, AccountCredentialEnvironment, AccountCredentialStatus, AccountCredential, AccountCredentialWithSecret, RotateAccountCredentialResult, ListAccountsOptions, CreateAccountInput, UpdateAccountInput, InviteAccountMemberInput, UpdateAccountMemberInput, TransferAccountOwnershipInput, CreateAccountCredentialInput, AccountSuccessResult, SwitchAccountResult, Application, ApplicationType, ApplicationStatus, ApplicationCredential, ApplicationCredentialType, ApplicationCredentialStatus, ApplicationEnvironment, CreateApplicationInput, UpdateApplicationInput, CreateApplicationCredentialInput, ApplicationCredentialWithSecret, RotateApplicationCredentialResult, ApplicationUsagePeriod, ApplicationUsageSummary, ApplicationUsageByDay, ApplicationUsageByEndpoint, ApplicationUsageStats, } from './mixins/OxyServices.accounts';
+export { ORGANIZATION_CATEGORIES } from './mixins/OxyServices.accounts';
 export type { ReputationCategory, TrustTier, ReputationTransactionStatus, ReputationTargetEntityType, ReputationDisputeStatus, ReputationInfluenceContext, ReputationTransaction, ReputationBalanceBreakdown, ReputationInfluence, ReputationReliability, ReputationBalance, ReputationDispute, ReputationRule, ReputationLeaderboardEntry, ReputationInfluenceResult, ReverseReputationTransactionResult, AwardReputationInput, CreateReputationDisputeInput, ResolveReputationDisputeInput, UpsertReputationRuleInput, ReverseReputationTransactionInput, } from './mixins/OxyServices.reputation';
 export { buildUserDid } from './mixins/OxyServices.identity';
 export type { IdentityRecordType, UnlinkableAuthMethodType, LinkAuthMethodResult, PublishRecordResult, VerifyRecordResult, VerifyDomainResult, RemoveDomainResult, } from './mixins/OxyServices.identity';

package/dist/types/mixins/OxyServices.accounts.d.ts

@@ -33,6 +33,7 @@
  * registers the switched session into the operator's device-set directly).
  */
 import type { User } from '../models/interfaces';
+import type { OrganizationCategory } from '@oxyhq/contracts';
 import type { SessionLoginResponse } from '../models/session';
 import type { OxyServicesBase } from '../OxyServices.base';
 /**
@@ -42,6 +43,9 @@ import type { OxyServicesBase } from '../OxyServices.base';
  * and have no direct login.
  */
 export type AccountKind = 'personal' | 'organization' | 'project' | 'bot';
+/** Real-estate / team taxonomy for `kind: 'organization'` accounts. */
+export type { OrganizationCategory } from '@oxyhq/contracts';
+export { ORGANIZATION_CATEGORIES } from '@oxyhq/contracts';
 /**
  * The calling user's relationship to an account node, as resolved by the API:
  * - `self` — the caller's own personal (root) account.
@@ -143,6 +147,8 @@ export interface CreateAccountInput {
     };
     bio?: string;
     avatar?: string;
+    /** Meaningful only when `kind` is `organization`. */
+    organizationCategory?: OrganizationCategory;
 }
 /** Input accepted by `updateAccount`. Tree placement changes go through `/move`. */
 export interface UpdateAccountInput {
@@ -153,6 +159,8 @@ export interface UpdateAccountInput {
     };
     bio?: string | null;
     avatar?: string | null;
+    /** Clears the category when `null`; only valid on `kind: 'organization'`. */
+    organizationCategory?: OrganizationCategory | null;
 }
 /** Input accepted by `inviteAccountMember`. The owner role cannot be invited. */
 export interface InviteAccountMemberInput {

package/dist/types/mixins/OxyServices.auth.d.ts

@@ -319,6 +319,7 @@ export declare function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(B
             deviceId: string;
             expiresAt: string;
             user: User;
+            deviceSecret?: string;
         }>;
         /**
          * MECHANISM A — same-device shared-keychain SSO.

package/dist/types/models/interfaces.d.ts

@@ -1,4 +1,4 @@
-import type { UserNameResponse } from '@oxyhq/contracts';
+import type { OrganizationCategory, UserNameResponse } from '@oxyhq/contracts';
 export interface OxyConfig {
     baseURL: string;
     cloudURL?: string;
@@ -129,6 +129,8 @@ export interface User {
     };
     isManagedAccount?: boolean;
     managedBy?: string;
+    /** Real-estate taxonomy when this user is a `kind: 'organization'` account. */
+    organizationCategory?: OrganizationCategory;
     notificationPreferences?: NotificationPreferences;
     userPreferences?: UserPreferences;
     [key: string]: unknown;

package/dist/types/models/session.d.ts

@@ -31,4 +31,10 @@ export interface SessionLoginResponse {
     user: MinimalUserData;
     /** JWT access token for API authentication */
     accessToken?: string;
+    /**
+     * Rotating zero-cookie device credential minted on sign-in / claim. Persisted
+     * first-party alongside `deviceId` so cold boot can re-mint via
+     * `POST /session/device/token`.
+     */
+    deviceSecret?: string;
 }

package/dist/types/session/SessionClient.d.ts

@@ -56,9 +56,20 @@ export declare class SessionClient {
     private started;
     /** Same-origin cross-tab state-propagation channel; null on platforms without BroadcastChannel. */
     private channel;
+    /** App-facing subscriptions to named server-pushed socket events. */
+    private readonly serverEvents;
+    /** Event names already bound on the CURRENT socket instance. */
+    private readonly boundServerEvents;
     constructor(host: SessionClientHost, options?: SessionClientOptions);
     getState(): DeviceSessionState | null;
     subscribe(listener: StateListener): () => void;
+    /**
+     * Subscribe to a named server-pushed Socket.IO event (e.g. `civic:attested`).
+     * Listeners survive reconnects and socket re-creation; the returned function
+     * unsubscribes. Payloads are delivered as-is — callers validate shape.
+     */
+    onServerEvent(event: string, listener: (payload: unknown) => void): () => void;
+    private bindServerEvent;
     protected notify(): void;
     /** Validate + last-writer-wins by revision. Returns true if applied. */
     protected applyState(raw: unknown): boolean;

package/dist/types/session/accountDialogController.d.ts

@@ -111,6 +111,16 @@ export interface AccountDialogControllerOptions {
      * `Linking.openURL`). Headless core never touches `window`/`Linking` itself.
      */
     openUrl?: (url: string) => void;
+    /**
+     * Optional "can this app open this URL scheme?" probe, symmetric to
+     * {@link openUrl}. When provided, `showQr` uses it to detect an installed
+     * Commons (`oxycommons://`) and, if present, deep-links straight into its
+     * approve screen via {@link openUrl} — while KEEPING the QR/polling active as
+     * the fallback. Injected by the provider (native: `Linking.canOpenURL`; web:
+     * absent/false). Headless core never touches `Linking` itself; when absent
+     * `showQr` behaves exactly as before (render QR only).
+     */
+    canOpenApp?: (url: string) => Promise<boolean>;
 }
 type SnapshotListener = (snapshot: AccountDialogSnapshot) => void;
 export declare class AccountDialogController {
@@ -124,6 +134,7 @@ export declare class AccountDialogController {
     private readonly authRedirectUri;
     private readonly pollIntervalMs;
     private readonly openUrl?;
+    private readonly canOpenApp?;
     private readonly listeners;
     private view;
     private graph;
@@ -232,6 +243,12 @@ export declare class AccountDialogController {
      * session committed. Requires `clientId`.
      */
     showQr(): Promise<void>;
+    /**
+     * When a `canOpenApp` probe is injected and reports Commons installed, open the
+     * approve deep link via the injected `openUrl`. Best-effort and non-blocking: a
+     * probe/open failure is logged and swallowed — the QR/polling fallback remains.
+     */
+    private maybeOpenCommons;
     /** Tear down the active sign-in device flow (timers + token) and reset to idle. */
     cancelSignIn(): void;
     /**

package/dist/types/session/authStateStore.d.ts

@@ -77,11 +77,32 @@ export interface NativeKeyValueStorage {
     removeItem(key: string): Promise<void>;
 }
 /**
- * Versioned storage key. The `.v1` suffix lets a future shape change ship a
- * `.v2` key without reading a stale/incompatible `.v1` blob. Distinct from the
- * `oxy_shared_*` keychain keys in `KeyManager`, so it never collides.
+ * Versioned DURABLE storage key. Holds ONLY the small, re-mint-critical fields
+ * (`sessionId`, `userId`, `deviceId`, `deviceSecret`) — never the large JWT
+ * `accessToken`. Keeping this blob small (<2KB) matters on Android
+ * `expo-secure-store`, whose backing store can silently fail to persist an
+ * oversize value; bundling the token here previously took the mint credential
+ * down with it on every write, losing the session on cold restart.
+ *
+ * The `.v1` suffix lets a future shape change ship a `.v2` key without reading a
+ * stale/incompatible `.v1` blob. Distinct from the `oxy_shared_*` keychain keys
+ * in `KeyManager`, so it never collides.
+ *
+ * BACK-COMPAT: pre-split builds wrote the WHOLE state (including `accessToken` /
+ * `expiresAt`) into this single key. `load()` still reads those token fields
+ * from here when the warm key ({@link AUTH_STATE_TOKEN_STORAGE_KEY}) is absent,
+ * so upgrading users are not signed out; the next `save()` splits them apart.
  */
 export declare const AUTH_STATE_STORAGE_KEY = "oxy.auth.v1";
+/**
+ * Versioned BEST-EFFORT warm-token storage key. Holds the short-lived
+ * `{ accessToken, expiresAt }` pair only. Its write is genuinely non-fatal — a
+ * failure (quota / oversize keychain value) is swallowed because the session is
+ * fully re-mintable from the durable `deviceSecret`. Kept separate from
+ * {@link AUTH_STATE_STORAGE_KEY} so a failed token write can NEVER abort or
+ * corrupt the durable credential write.
+ */
+export declare const AUTH_STATE_TOKEN_STORAGE_KEY = "oxy.auth.token.v1";
 /**
  * A process-lifetime, in-memory {@link AuthStateStore}. Used directly for
  * tests/SSR and as the degraded fallback of the web store when `localStorage`
@@ -90,8 +111,9 @@ export declare const AUTH_STATE_STORAGE_KEY = "oxy.auth.v1";
  */
 export declare function createMemoryAuthStateStore(): AuthStateStore;
 /**
- * A `localStorage`-backed {@link AuthStateStore} under the versioned
- * {@link AUTH_STATE_STORAGE_KEY}.
+ * A `localStorage`-backed {@link AuthStateStore} split across the durable
+ * {@link AUTH_STATE_STORAGE_KEY} (mint credential) and the best-effort
+ * {@link AUTH_STATE_TOKEN_STORAGE_KEY} (warm access token).
  *
  * Resilience:
  *  - If `localStorage` is unreachable (sandboxed-iframe `SecurityError`, SSR),
@@ -107,8 +129,11 @@ export declare function createWebAuthStateStore(): AuthStateStore;
  * A native {@link AuthStateStore} over an injected async key/value store.
  *
  * `@oxyhq/core` never imports `expo-secure-store`; `@oxyhq/services` constructs
- * the SecureStore-backed adapter and passes it here. Every operation is wrapped
- * so a storage exception degrades gracefully (read → `null`, write → swallowed)
- * exactly like the web store.
+ * the SecureStore-backed adapter and passes it here. Persistence is split across
+ * the durable {@link AUTH_STATE_STORAGE_KEY} (mint credential) and the
+ * best-effort {@link AUTH_STATE_TOKEN_STORAGE_KEY} (warm access token) — the
+ * durable write is read-back-verified and its failure surfaced (not swallowed),
+ * while the warm-token write and all reads degrade gracefully exactly like the
+ * web store.
  */
 export declare function createNativeAuthStateStore(storage: NativeKeyValueStorage): AuthStateStore;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/core",
-  "version": "9.2.0",
+  "version": "9.2.2",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -94,7 +94,7 @@
     }
   },
   "dependencies": {
-    "@oxyhq/contracts": "^0.13.1",
+    "@oxyhq/contracts": "^0.13.2",
     "@oxyhq/protocol": "^0.1.3",
     "bip39": "^3.1.0",
     "buffer": "^6.0.3",

package/src/boot/__tests__/sessionColdBoot.test.ts

@@ -258,6 +258,26 @@ describe('runSessionColdBoot — shared-key-signin (native)', () => {
     );
   });
 
+  it('persists deviceSecret from shared-key verifyChallenge for the next mint lane', async () => {
+    const store = createMemoryAuthStateStore();
+    const signInWithSharedIdentity = jest.fn(async () => ({
+      ...sharedSession,
+      deviceSecret: 'shared-mint-secret',
+    }));
+    const { oxy } = makeOxy({ signInWithSharedIdentity });
+
+    await runSessionColdBoot({ oxy, store, platform: NATIVE });
+
+    const persisted = await store.load();
+    expect(persisted).toMatchObject({
+      sessionId: 'sess-shared',
+      userId: 'user-shared',
+      deviceId: 'dev-1',
+      deviceSecret: 'shared-mint-secret',
+      accessToken: 'access-shared',
+    });
+  });
+
   it('does NOT run the shared-key lane on web', async () => {
     const store = createMemoryAuthStateStore();
     const signInWithSharedIdentity = jest.fn(async () => sharedSession);

package/src/boot/sessionColdBoot.ts

@@ -156,6 +156,19 @@ export async function runSessionColdBoot(
       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: {

package/src/index.ts

@@ -86,6 +86,7 @@ export type {
 // ---------------------------------------------------------------------------
 export type {
     AccountKind,
+    OrganizationCategory,
     AccountRelationship,
     AccountRole,
     AccountMemberStatus,
@@ -127,6 +128,8 @@ export type {
     ApplicationUsageStats,
 } from './mixins/OxyServices.accounts';
 
+export { ORGANIZATION_CATEGORIES } from './mixins/OxyServices.accounts';
+
 // ---------------------------------------------------------------------------
 // Reputation (Oxy Trust: ledger, balances, disputes, rules, influence)
 // ---------------------------------------------------------------------------

package/src/mixins/OxyServices.accounts.ts

@@ -33,6 +33,7 @@
  * registers the switched session into the operator's device-set directly).
  */
 import type { User } from '../models/interfaces';
+import type { OrganizationCategory } from '@oxyhq/contracts';
 import type { SessionLoginResponse } from '../models/session';
 import type { OxyServicesBase } from '../OxyServices.base';
 import { normalizeUserIdentity } from '../utils/userIdentity';
@@ -50,6 +51,10 @@ import { CACHE_TIMES } from './mixinHelpers';
  */
 export type AccountKind = 'personal' | 'organization' | 'project' | 'bot';
 
+/** Real-estate / team taxonomy for `kind: 'organization'` accounts. */
+export type { OrganizationCategory } from '@oxyhq/contracts';
+export { ORGANIZATION_CATEGORIES } from '@oxyhq/contracts';
+
 /**
  * The calling user's relationship to an account node, as resolved by the API:
  * - `self` — the caller's own personal (root) account.
@@ -155,6 +160,8 @@ export interface CreateAccountInput {
   name?: { first?: string; last?: string };
   bio?: string;
   avatar?: string;
+  /** Meaningful only when `kind` is `organization`. */
+  organizationCategory?: OrganizationCategory;
 }
 
 /** Input accepted by `updateAccount`. Tree placement changes go through `/move`. */
@@ -163,6 +170,8 @@ export interface UpdateAccountInput {
   name?: { first?: string; last?: string };
   bio?: string | null;
   avatar?: string | null;
+  /** Clears the category when `null`; only valid on `kind: 'organization'`. */
+  organizationCategory?: OrganizationCategory | null;
 }
 
 /** Input accepted by `inviteAccountMember`. The owner role cannot be invited. */

package/src/mixins/OxyServices.auth.ts

@@ -664,6 +664,7 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
       deviceId: string;
       expiresAt: string;
       user: User;
+      deviceSecret?: string;
     }> {
       try {
         const res = await this.makeRequest<{
@@ -672,6 +673,7 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
           deviceId: string;
           expiresAt: string;
           user: User;
+          deviceSecret?: string;
         }>(
           'POST',
           '/auth/session/claim',

package/src/mixins/OxyServices.utility.ts

@@ -5,9 +5,11 @@
  * and Express.js authentication middleware
  */
 import { jwtDecode } from 'jwt-decode';
+import type { LinkPreview } from '@oxyhq/contracts';
 import type { ApiError, User } from '../models/interfaces';
 import type { OxyServicesBase } from '../OxyServices.base';
 import { loadNodeCrypto } from '@oxyhq/protocol';
+import { buildUrl } from '../utils/apiUtils';
 import { logger } from '../utils/loggerUtils';
 import { CACHE_TIMES } from './mixinHelpers';
 
@@ -217,15 +219,14 @@ export function OxyServicesUtilityMixin<T extends typeof OxyServicesBase>(Base:
       image?: string;
     }> {
       try {
-        return await this.makeRequest<{
-          url: string;
-          title: string;
-          description: string;
-          image?: string;
-        }>('GET', '/link-metadata', { url }, {
-          cache: true,
-          cacheTTL: CACHE_TIMES.EXTRA_LONG,
-        });
+        const path = buildUrl('/links/preview', { url, wait: 1 });
+        const preview = await this.makeRequest<LinkPreview>('GET', path, undefined, { cache: false });
+        return {
+          url: preview.url,
+          title: preview.title?.trim() || preview.url.replace(/^https?:\/\//, '').replace(/\/$/, ''),
+          description: preview.description?.trim() || 'Link',
+          image: preview.image,
+        };
       } catch (error) {
         throw this.handleError(error);
       }

package/src/models/interfaces.ts

@@ -1,4 +1,4 @@
-import type { UserNameResponse } from '@oxyhq/contracts';
+import type { OrganizationCategory, UserNameResponse } from '@oxyhq/contracts';
 
 export interface OxyConfig {
   baseURL: string;
@@ -142,6 +142,8 @@ export interface User {
   // Managed account fields
   isManagedAccount?: boolean;
   managedBy?: string;
+  /** Real-estate taxonomy when this user is a `kind: 'organization'` account. */
+  organizationCategory?: OrganizationCategory;
   // User-controlled notification preferences. All channels default to on; users
   // opt out per-channel. Updated via `PUT /users/me`.
   notificationPreferences?: NotificationPreferences;

package/src/models/session.ts

@@ -35,4 +35,10 @@ export interface SessionLoginResponse {
   user: MinimalUserData;
   /** JWT access token for API authentication */
   accessToken?: string;
+  /**
+   * Rotating zero-cookie device credential minted on sign-in / claim. Persisted
+   * first-party alongside `deviceId` so cold boot can re-mint via
+   * `POST /session/device/token`.
+   */
+  deviceSecret?: string;
 }

package/src/session/SessionClient.ts

@@ -82,6 +82,10 @@ export class SessionClient {
   private started = false;
   /** Same-origin cross-tab state-propagation channel; null on platforms without BroadcastChannel. */
   private channel: SessionBroadcastChannel | null = null;
+  /** App-facing subscriptions to named server-pushed socket events. */
+  private readonly serverEvents = new Map<string, Set<(payload: unknown) => void>>();
+  /** Event names already bound on the CURRENT socket instance. */
+  private readonly boundServerEvents = new Set<string>();
 
   constructor(
     protected readonly host: SessionClientHost,
@@ -99,6 +103,40 @@ export class SessionClient {
     };
   }
 
+  /**
+   * Subscribe to a named server-pushed Socket.IO event (e.g. `civic:attested`).
+   * Listeners survive reconnects and socket re-creation; the returned function
+   * unsubscribes. Payloads are delivered as-is — callers validate shape.
+   */
+  onServerEvent(event: string, listener: (payload: unknown) => void): () => void {
+    let listeners = this.serverEvents.get(event);
+    if (!listeners) {
+      listeners = new Set();
+      this.serverEvents.set(event, listeners);
+    }
+    listeners.add(listener);
+    this.bindServerEvent(event);
+    return () => {
+      listeners.delete(listener);
+    };
+  }
+
+  private bindServerEvent(event: string): void {
+    if (!this.socket || this.boundServerEvents.has(event)) return;
+    this.boundServerEvents.add(event);
+    this.socket.on(event, (payload: unknown) => {
+      const listeners = this.serverEvents.get(event);
+      if (!listeners) return;
+      for (const listener of [...listeners]) {
+        try {
+          listener(payload);
+        } catch (error) {
+          logger.warn('[SessionClient] server-event listener threw', { component: 'SessionClient' }, error);
+        }
+      }
+    });
+  }
+
   protected notify(): void {
     for (const listener of this.listeners) {
       try {
@@ -287,6 +325,7 @@ export class SessionClient {
     if (this.socket) {
       this.socket.disconnect();
       this.socket = null;
+      this.boundServerEvents.clear();
     }
   }
 
@@ -341,6 +380,11 @@ export class SessionClient {
       }
     });
     this.socket = socket;
+    // (Re)bind app-facing server-event subscriptions on the fresh socket.
+    this.boundServerEvents.clear();
+    for (const event of this.serverEvents.keys()) {
+      this.bindServerEvent(event);
+    }
   }
 
   /**

package/src/session/__tests__/SessionClient.serverEvents.test.ts

@@ -0,0 +1,71 @@
+import type { DeviceSessionState } from '@oxyhq/contracts';
+import type { MinimalSocket, SocketIOFactory } from '../socketLoader';
+import { SessionClient, type SessionClientHost } from '../SessionClient';
+
+type Handler = (...args: unknown[]) => void;
+class FakeSocket implements MinimalSocket {
+  connected = false;
+  handlers = new Map<string, Handler[]>();
+  on(event: string, cb: Handler) { const l = this.handlers.get(event) ?? []; l.push(cb); this.handlers.set(event, l); }
+  off(event: string, cb?: Handler) { if (!cb) { this.handlers.delete(event); return; } this.handlers.set(event, (this.handlers.get(event) ?? []).filter((h) => h !== cb)); }
+  connect() { this.connected = true; }
+  disconnect() { this.connected = false; }
+  emitServer(event: string, payload: unknown) { for (const h of this.handlers.get(event) ?? []) h(payload); }
+}
+
+const STATE = (rev: number): DeviceSessionState => ({ deviceId: 'd1', accounts: [{ accountId: 'a1', sessionId: 's1', authuser: 0 }], activeAccountId: 'a1', revision: rev, updatedAt: 1720000000000 });
+const SYNC = (rev: number) => ({ state: STATE(rev), activeToken: { accessToken: `jwt-${rev}`, expiresAt: 'x' } });
+
+function makeHost(over: Partial<SessionClientHost> = {}): SessionClientHost {
+  return {
+    makeRequest: jest.fn().mockResolvedValue(SYNC(1)),
+    getBaseURL: () => 'http://test.invalid',
+    getAccessToken: () => 'tok',
+    getDeviceCredential: () => null,
+    onTokensChanged: () => () => undefined,
+    setTokens: jest.fn(),
+    getCurrentAccountId: () => 'a1',
+    ...over,
+  };
+}
+
+describe('SessionClient.onServerEvent', () => {
+  it('delivers a server event to a listener registered BEFORE the socket exists', async () => {
+    let created: FakeSocket | null = null;
+    const factory: SocketIOFactory = jest.fn(() => { created = new FakeSocket(); created.connected = true; return created; });
+    const client = new SessionClient(makeHost(), { socketFactory: factory });
+    const seen: unknown[] = [];
+    client.onServerEvent('civic:attested', (p) => seen.push(p));
+    await client.start();
+    created?.emitServer('civic:attested', { byUserId: 'u2' });
+    expect(seen).toEqual([{ byUserId: 'u2' }]);
+    client.stop();
+  });
+
+  it('delivers to a listener registered AFTER the socket exists, and unsubscribe stops delivery', async () => {
+    let created: FakeSocket | null = null;
+    const factory: SocketIOFactory = jest.fn(() => { created = new FakeSocket(); created.connected = true; return created; });
+    const client = new SessionClient(makeHost(), { socketFactory: factory });
+    await client.start();
+    const seen: unknown[] = [];
+    const unsub = client.onServerEvent('civic:attested', (p) => seen.push(p));
+    created?.emitServer('civic:attested', 1);
+    unsub();
+    created?.emitServer('civic:attested', 2);
+    expect(seen).toEqual([1]);
+    client.stop();
+  });
+
+  it('one listener throwing does not break the others', async () => {
+    let created: FakeSocket | null = null;
+    const factory: SocketIOFactory = jest.fn(() => { created = new FakeSocket(); created.connected = true; return created; });
+    const client = new SessionClient(makeHost(), { socketFactory: factory });
+    await client.start();
+    const seen: unknown[] = [];
+    client.onServerEvent('civic:attested', () => { throw new Error('boom'); });
+    client.onServerEvent('civic:attested', (p) => seen.push(p));
+    created?.emitServer('civic:attested', 'ok');
+    expect(seen).toEqual(['ok']);
+    client.stop();
+  });
+});