@dxos/edge-client 0.13.0 → 0.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/edge-client",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "EDGE Client",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -61,23 +61,23 @@
     "@bufbuild/protobuf": "2.11.0",
     "isomorphic-ws": "^5.0.0",
     "ws": "^8.17.1",
-    "@dxos/async": "0.13.0",
-    "@dxos/context": "0.13.0",
-    "@dxos/credentials": "0.13.0",
-    "@dxos/crypto": "0.13.0",
-    "@dxos/effect": "0.13.0",
-    "@dxos/errors": "0.13.0",
-    "@dxos/invariant": "0.13.0",
-    "@dxos/keyring": "0.13.0",
-    "@dxos/keys": "0.13.0",
-    "@dxos/log": "0.13.0",
-    "@dxos/node-std": "0.13.0",
-    "@dxos/protocols": "0.13.0",
-    "@dxos/tracing": "0.13.0",
-    "@dxos/util": "0.13.0"
+    "@dxos/async": "0.14.0",
+    "@dxos/context": "0.14.0",
+    "@dxos/credentials": "0.14.0",
+    "@dxos/crypto": "0.14.0",
+    "@dxos/effect": "0.14.0",
+    "@dxos/errors": "0.14.0",
+    "@dxos/invariant": "0.14.0",
+    "@dxos/keyring": "0.14.0",
+    "@dxos/keys": "0.14.0",
+    "@dxos/log": "0.14.0",
+    "@dxos/node-std": "0.14.0",
+    "@dxos/protocols": "0.14.0",
+    "@dxos/tracing": "0.14.0",
+    "@dxos/util": "0.14.0"
   },
   "devDependencies": {
-    "@dxos/test-utils": "0.13.0"
+    "@dxos/test-utils": "0.14.0"
   },
   "peerDependencies": {
     "effect": "4.0.0"

package/src/auth-challenge.test.ts

@@ -5,8 +5,10 @@
 import { create } from '@bufbuild/protobuf';
 import { afterEach, describe, test, vi } from 'vitest';
 
+import { EDGE_CLIENT_TOO_OLD, EDGE_CLIENT_VERSION_HEADER, EdgeClientTooOldError, EdgeResponse } from '@dxos/protocols';
 import { type Presentation, PresentationSchema } from '@dxos/protocols/buf/dxos/halo/credentials_pb';
 
+import { version as packageVersion } from '../package.json';
 import {
   authenticateViaChallengeEndpoint,
   fetchAuthChallenge,
@@ -135,15 +137,28 @@ describe('fetchAuthChallenge', () => {
     vi.unstubAllGlobals();
   });
 
-  test('GETs /auth relative to the base URL', async ({ expect }) => {
+  test('GETs /auth relative to the base URL, advertising the SDK version', async ({ expect }) => {
     // Typed with the input parameter so `mock.calls[0][0]` is a tuple element rather than `never`.
-    const fetchMock = vi.fn(async (_input: URL | RequestInfo) =>
+    const fetchMock = vi.fn(async (_input: URL | RequestInfo, _init?: RequestInit) =>
       jsonResponse({ success: true, data: { challenge: CHALLENGE } }),
     );
     vi.stubGlobal('fetch', fetchMock);
 
     expect(await fetchAuthChallenge('https://edge.example.com')).toBe(CHALLENGE);
     expect(String(fetchMock.mock.calls[0][0])).toBe('https://edge.example.com/auth');
+    expect(new Headers(fetchMock.mock.calls[0][1]?.headers).get(EDGE_CLIENT_VERSION_HEADER)).toBe(packageVersion);
+  });
+
+  test('throws when EDGE refuses the SDK as too old, rather than falling back', async ({ expect }) => {
+    // Every fallback carries the same version, so swallowing the refusal would only retry into it.
+    vi.stubGlobal('fetch', async () =>
+      EdgeResponse.failure({
+        message: 'Client too old: SDK 0.12.0 is older than 0.13.0. Update the app (reload it) to continue.',
+        status: 426,
+        data: { type: EDGE_CLIENT_TOO_OLD, clientVersion: '0.12.0', minimumVersion: '0.13.0' },
+      }),
+    );
+    await expect(fetchAuthChallenge('https://edge.example.com')).rejects.toBeInstanceOf(EdgeClientTooOldError);
   });
 
   test('still works against a server whose /auth only answers 401', async ({ expect }) => {

package/src/auth-challenge.ts

@@ -7,8 +7,10 @@ import { base64Decode } from '@bufbuild/protobuf/wire';
 
 import { invariant } from '@dxos/invariant';
 import { log } from '@dxos/log';
+import { EdgeClientTooOldError } from '@dxos/protocols';
 import { PresentationSchema } from '@dxos/protocols/buf/dxos/halo/credentials_pb';
 
+import { assertClientSupported, clientVersionHeaders } from './client-version.ts';
 import { type EdgeIdentity } from './edge-identity.ts';
 
 /**
@@ -165,11 +167,13 @@ export type AuthChallengeInfo = {
  * console and records a routine auth failure server-side on each client boot.
  *
  * Returns undefined if the endpoint is unreachable or answers in neither known shape; callers fall
- * back to the 401 path, which still works against every server.
+ * back to the 401 path, which still works against every server. Throws {@link EdgeClientTooOldError} when EDGE refuses
+ * this SDK, which no fallback can get past.
  */
 export const fetchAuthChallengeInfo = async (baseHttpUrl: string | URL): Promise<AuthChallengeInfo | undefined> => {
   try {
-    const response = await fetch(new URL('/auth', baseHttpUrl));
+    const response = await fetch(new URL('/auth', baseHttpUrl), { headers: clientVersionHeaders() });
+    await assertClientSupported(response);
     const challenge = await readAuthChallenge(response);
     if (!challenge) {
       log.verbose('no challenge in /auth response', { status: response.status });
@@ -186,6 +190,9 @@ export const fetchAuthChallengeInfo = async (baseHttpUrl: string | URL): Promise
     }
     return { challenge, expiresInMs };
   } catch (error) {
+    if (error instanceof EdgeClientTooOldError) {
+      throw error;
+    }
     log.verbose('failed to fetch auth challenge', { error });
     return undefined;
   }

package/src/base-http-client.ts

@@ -6,7 +6,14 @@ import { sleep } from '@dxos/async';
 import { Context, TRACE_SPAN_ATTRIBUTE, type TraceContextData } from '@dxos/context';
 import { invariant } from '@dxos/invariant';
 import { log } from '@dxos/log';
-import { EDGE_CLIENT_TAG_HEADER, EdgeAuthChallengeError, EdgeCallFailedError, type EdgeFailure } from '@dxos/protocols';
+import {
+  EDGE_CLIENT_TAG_HEADER,
+  EDGE_CLIENT_TOO_OLD,
+  EdgeAuthChallengeError,
+  EdgeCallFailedError,
+  EdgeClientTooOldError,
+  type EdgeFailure,
+} from '@dxos/protocols';
 
 import { authenticateViaChallengeEndpoint, handleAuthChallenge, parseChallengeHeader } from './auth-challenge.ts';
 import { type EdgeIdentity } from './edge-identity.ts';
@@ -193,6 +200,8 @@ export abstract class BaseHttpClient {
 
         if (body?.data?.type === 'auth_challenge' && typeof body?.data?.challenge === 'string') {
           processingError = new EdgeAuthChallengeError(body.data.challenge, body.data);
+        } else if (body?.success === false && body.data?.type === EDGE_CLIENT_TOO_OLD) {
+          processingError = new EdgeClientTooOldError(body, response.status);
         } else if (body?.success === false) {
           processingError = EdgeCallFailedError.fromUnsuccessfulResponse(response, body);
         } else {
@@ -293,12 +302,16 @@ export abstract class BaseHttpClient {
    * device with no HALO chain (mid-invitation), and without this the rejection would surface from
    * `_call` as a failed request — turning a call that used to succeed unauthenticated into an error.
    */
-  private _prefetchAuthHeader(): Promise<void> {
+  protected _prefetchAuthHeader(): Promise<void> {
     if (this._authPrefetch) {
       return this._authPrefetch;
     }
     const prefetch: Promise<void> = this._prefetchAuthHeaderOnce()
       .catch((err) => {
+        // Unauthenticated would only be refused again, and silently; the caller has to see it.
+        if (err instanceof EdgeClientTooOldError) {
+          throw err;
+        }
         log.verbose('auth prefetch failed; proceeding unauthenticated', { err });
       })
       .finally(() => {

package/src/client-version.ts

@@ -0,0 +1,44 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import {
+  EDGE_CLIENT_TOO_OLD,
+  EDGE_CLIENT_VERSION_HEADER,
+  EDGE_CLIENT_VERSION_PROTOCOL_PREFIX,
+  EdgeClientTooOldError,
+  type EdgeFailure,
+} from '@dxos/protocols';
+
+import { version } from '../package.json';
+
+/**
+ * This SDK's version, which EDGE checks against the oldest it serves. It releases in lockstep with the rest of the
+ * SDK, and Vite tree-shakes the import to this one field.
+ */
+export const CLIENT_SDK_VERSION: string = version;
+
+/** Headers advertising {@link CLIENT_SDK_VERSION} on a request of the EDGE connect flow (`/auth` and its fallback). */
+export const clientVersionHeaders = (): Record<string, string> => ({
+  [EDGE_CLIENT_VERSION_HEADER]: CLIENT_SDK_VERSION,
+});
+
+/** The same advertisement for the WebSocket upgrade, where a browser can set no header but the subprotocol list. */
+export const clientVersionProtocol = (): string => `${EDGE_CLIENT_VERSION_PROTOCOL_PREFIX}${CLIENT_SDK_VERSION}`;
+
+/**
+ * Throws {@link EdgeClientTooOldError} when `response` is EDGE's failure envelope refusing this SDK. Matched on the
+ * envelope's `data.type`, as any WebSocket endpoint answers a plain GET with a bare 426 "Upgrade Required".
+ */
+export const assertClientSupported = async (response: Response): Promise<void> => {
+  if (response.ok || !response.headers.get('Content-Type')?.startsWith('application/json')) {
+    return;
+  }
+  const body: EdgeFailure | undefined = await response
+    .clone()
+    .json()
+    .catch(() => undefined);
+  if (body?.success === false && body.data?.type === EDGE_CLIENT_TOO_OLD) {
+    throw new EdgeClientTooOldError(body, response.status);
+  }
+};

package/src/edge-client.test.ts

@@ -2,11 +2,12 @@
 // Copyright 2024 DXOS.org
 //
 
-import { describe, expect, onTestFinished, test } from 'vitest';
+import { describe, expect, onTestFinished, test, vi } from 'vitest';
 
-import { Trigger } from '@dxos/async';
+import { Trigger, sleep } from '@dxos/async';
 import { Context } from '@dxos/context';
 import { Keyring } from '@dxos/keyring';
+import { EDGE_CLIENT_TOO_OLD, EdgeClientTooOldError, EdgeResponse } from '@dxos/protocols';
 import { EdgeStatus_ConnectionState } from '@dxos/protocols/buf/dxos/client/services_pb';
 import { TextMessageSchema } from '@dxos/protocols/buf/dxos/edge/messenger_pb';
 import { openAndClose } from '@dxos/test-utils';
@@ -179,6 +180,31 @@ describe('EdgeClient', () => {
     expect(client.isOpen).is.true;
   });
 
+  // Every retry would carry the same version and be refused the same way, so the client must stop and say why.
+  test('a refusal at /auth stops reconnecting and fails sends with the refusal', async () => {
+    const fetchMock = vi.fn(async (_input: URL | RequestInfo) =>
+      EdgeResponse.failure({
+        message: 'Client too old: SDK 0.12.0 is older than 0.13.0. Update the app (reload it) to continue.',
+        status: 426,
+        data: { type: EDGE_CLIENT_TOO_OLD, clientVersion: '0.12.0', minimumVersion: '0.13.0' },
+      }),
+    );
+    vi.stubGlobal('fetch', fetchMock);
+    onTestFinished(() => {
+      vi.unstubAllGlobals();
+    });
+
+    const client = new EdgeClient(await createEphemeralEdgeIdentity(), { socketEndpoint: 'ws://127.0.0.1:1' });
+    await openAndClose(client);
+
+    await expect(client.send(Context.default(), textMessage('Hello'))).rejects.toBeInstanceOf(EdgeClientTooOldError);
+    // Several backoff periods (100 ms, doubling): a retrying client would have fetched /auth again by now.
+    await sleep(1_000);
+    // Counted by host: an earlier test's client may still be reconnecting through the same stub.
+    expect(fetchMock.mock.calls.filter((call) => new URL(String(call[0])).host === '127.0.0.1:1')).toHaveLength(1);
+    await expect(client.send(Context.default(), textMessage('Hello'))).rejects.toBeInstanceOf(EdgeClientTooOldError);
+  });
+
   const textMessage = (message: string, source?: EdgeIdentity) =>
     protocol.createMessage(TextMessageSchema, {
       source: source && { peerKey: source.peerKey, identityDid: source.identityDid },

package/src/edge-client.ts

@@ -17,7 +17,7 @@ import {
 import { Context, TRACE_SPAN_ATTRIBUTE, type TraceContextData } from '@dxos/context';
 import { type Lifecycle, Resource } from '@dxos/context';
 import { log, logInfo } from '@dxos/log';
-import { EdgeCredentialsHeaderCodec } from '@dxos/protocols';
+import { EdgeClientTooOldError, EdgeCredentialsHeaderCodec } from '@dxos/protocols';
 import {
   type EdgeStatus,
   EdgeStatus_ConnectionState,
@@ -31,6 +31,7 @@ import {
   presentCredentialsForChallenge,
   readAuthChallenge,
 } from './auth-challenge.ts';
+import { assertClientSupported, clientVersionHeaders } from './client-version.ts';
 import { protocol } from './defs.ts';
 import { type EdgeIdentity } from './edge-identity.ts';
 import { EdgeWsConnection } from './edge-ws-connection.ts';
@@ -120,6 +121,8 @@ export class EdgeClient extends Resource implements EdgeConnection {
   private readonly _baseHttpUrl: string;
   private _currentConnection?: EdgeWsConnection = undefined;
   private _ready = new Trigger();
+  /** Set when EDGE refused this SDK as outdated; a retry would carry the same version, so none is made. */
+  #refusal: EdgeClientTooOldError | undefined = undefined;
 
   constructor(
     private _identity: EdgeIdentity,
@@ -177,6 +180,9 @@ export class EdgeClient extends Resource implements EdgeConnection {
    * NOTE: The message is guaranteed to be delivered but the service must respond with a message to confirm processing.
    */
   public async send(ctx: Context, message: Message) {
+    if (this.#refusal) {
+      throw this.#refusal;
+    }
     if (this._ready.state !== TriggerState.RESOLVED) {
       log('waiting for websocket');
       await this._ready.wait({ timeout: this._config.timeout ?? DEFAULT_TIMEOUT });
@@ -289,7 +295,22 @@ export class EdgeClient extends Resource implements EdgeConnection {
 
     const identity = this._identity;
     const path = `/ws/${identity.identityDid}/${identity.peerKey}`;
-    const protocolHeader = this._config.disableAuth ? undefined : await this._createAuthHeader(path);
+    this.#refusal = undefined;
+    let protocolHeader: string | undefined;
+    try {
+      protocolHeader = this._config.disableAuth ? undefined : await this._createAuthHeader(path);
+    } catch (err) {
+      if (!(err instanceof EdgeClientTooOldError)) {
+        throw err;
+      }
+      // Returning, not throwing, ends PersistentLifecycle's backoff loop: every retry would be refused the same way.
+      log.warn('EDGE refused this SDK as outdated; not reconnecting until the app is updated', { data: err.data });
+      this.#refusal = err;
+      this._ready.throw(err);
+      this._ready.reset();
+      this.statusChanged.emit(this.status);
+      return undefined;
+    }
     if (this._identity !== identity) {
       log('identity changed during auth header request');
       return undefined;
@@ -446,7 +467,8 @@ export class EdgeClient extends Resource implements EdgeConnection {
       return encodePresentationWsAuthHeader(authentication.presentation);
     }
 
-    const response = await fetch(new URL(path, this._baseHttpUrl), { method: 'GET' });
+    const response = await fetch(new URL(path, this._baseHttpUrl), { method: 'GET', headers: clientVersionHeaders() });
+    await assertClientSupported(response);
     // Gate on a parsed VP challenge, not merely on a 401. A 401 forwarded from upstream can carry
     // an unrelated `WWW-Authenticate` (or none), and signing a challenge that isn't there would
     // throw instead of degrading to an unauthenticated attempt.

package/src/edge-http-client.test.ts

@@ -6,6 +6,7 @@ import { create } from '@bufbuild/protobuf';
 import { afterEach, describe, it, test, vi } from 'vitest';
 
 import { Context } from '@dxos/context';
+import { EDGE_CLIENT_TOO_OLD, EdgeClientTooOldError, EdgeResponse } from '@dxos/protocols';
 import { type Presentation, PresentationSchema } from '@dxos/protocols/buf/dxos/halo/credentials_pb';
 
 import { createEphemeralEdgeIdentity } from './auth.ts';
@@ -329,6 +330,48 @@ describe('EdgeHttpClient auth refresh', () => {
   });
 });
 
+describe('EdgeHttpClient outdated SDK', () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  // Built by EDGE's own envelope producer, exactly as `requireClientSdkVersion` answers.
+  const refusal = () =>
+    EdgeResponse.failure({
+      message: 'Client too old: SDK 0.12.0 is older than 0.13.0. Update the app (reload it) to continue.',
+      status: 426,
+      data: { type: EDGE_CLIENT_TOO_OLD, clientVersion: '0.12.0', minimumVersion: '0.13.0' },
+    });
+
+  // The prefetch swallows other failures to proceed unauthenticated, which here would only be refused again, silently.
+  test('a refusal at the /auth prefetch fails the call once, without sending it', async ({ expect }) => {
+    const fetchMock = vi.fn(async (_input: any, _init?: RequestInit) => refusal());
+    vi.stubGlobal('fetch', fetchMock);
+    const client = new EdgeHttpClient('https://edge.example.com');
+    client.setIdentity({
+      peerKey: 'peer-key',
+      identityDid: 'did:halo:test',
+      presentCredentials: async (): Promise<Presentation> => create(PresentationSchema, {}),
+    });
+
+    const error = await client.getStatus(Context.default()).catch((error: unknown) => error);
+    expect(error).toBeInstanceOf(EdgeClientTooOldError);
+    expect(error).toMatchObject({ status: 426, isRetryable: false, data: { minimumVersion: '0.13.0' } });
+    expect(fetchMock.mock.calls.map((call) => new URL(String(call[0])).pathname)).toEqual(['/auth']);
+  });
+
+  test('a route refusing the SDK fails with the typed error and is not retried', async ({ expect }) => {
+    const fetchMock = vi.fn(async (_input: any, _init?: RequestInit) => refusal());
+    vi.stubGlobal('fetch', fetchMock);
+    const client = new EdgeHttpClient('https://edge.example.com');
+
+    await expect(client.request(Context.default(), '/status', { method: 'GET' })).rejects.toBeInstanceOf(
+      EdgeClientTooOldError,
+    );
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+  });
+});
+
 describe('EdgeHttpClient blobs', () => {
   afterEach(() => {
     vi.unstubAllGlobals();

package/src/edge-http-client.ts

@@ -840,10 +840,7 @@ export class EdgeHttpClient extends BaseHttpClient {
     let handledAuth = false;
     while (true) {
       if (!this._authHeader) {
-        const authResponse = await fetch(new URL('/auth', this.baseUrl));
-        if (authResponse.status === 401) {
-          this._authHeader = await this._handleUnauthorized(authResponse);
-        }
+        await this._prefetchAuthHeader();
       }
 
       const headers = new Headers(request.headers);

package/src/edge-ws-connection.ts

@@ -8,11 +8,11 @@ import { Mutex, scheduleTask, scheduleTaskInterval } from '@dxos/async';
 import { Context, Resource } from '@dxos/context';
 import { invariant } from '@dxos/invariant';
 import { log, logInfo } from '@dxos/log';
-import { EDGE_CLIENT_VERSION_PROTOCOL_PREFIX, EdgeWebsocketProtocol } from '@dxos/protocols';
+import { EdgeWebsocketProtocol } from '@dxos/protocols';
 import { buf } from '@dxos/protocols/buf';
 import { type Message, MessageSchema } from '@dxos/protocols/buf/dxos/edge/messenger_pb';
 
-import { version } from '../package.json';
+import { clientVersionProtocol } from './client-version.ts';
 import { protocol } from './defs.ts';
 import { type EdgeIdentity } from './edge-identity.ts';
 import { CLOUDFLARE_MESSAGE_MAX_BYTES, WebSocketClosedError, WebSocketMuxer } from './edge-ws-muxer.ts';
@@ -181,8 +181,7 @@ export class EdgeWsConnection extends Resource {
   }
 
   protected override async _open(): Promise<void> {
-    // Browsers cannot set WebSocket headers, so the SDK version rides in the subprotocol list.
-    const baseProtocols = [...Object.values(EdgeWebsocketProtocol), `${EDGE_CLIENT_VERSION_PROTOCOL_PREFIX}${version}`];
+    const baseProtocols = [...Object.values(EdgeWebsocketProtocol), clientVersionProtocol()];
     this._ws = new WebSocket(
       this._connectionInfo.url.toString(),
       this._connectionInfo.protocolHeader