@dxos/edge-client 0.6.13 → 0.6.14-main.69511f5

package/package.json

@@ -1,23 +1,31 @@
 {
   "name": "@dxos/edge-client",
-  "version": "0.6.13",
+  "version": "0.6.14-main.69511f5",
   "description": "EDGE Client",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
   "license": "MIT",
   "author": "DXOS.org",
+  "sideEffects": true,
   "exports": {
     ".": {
+      "types": "./dist/types/src/index.d.ts",
       "browser": "./dist/lib/browser/index.mjs",
-      "node": {
-        "default": "./dist/lib/node/index.cjs"
-      },
-      "types": "./dist/types/src/index.d.ts"
+      "node": "./dist/lib/node-esm/index.mjs"
+    },
+    "./testing": {
+      "types": "./dist/types/src/testing/index.d.ts",
+      "browser": "./dist/lib/browser/testing/index.mjs",
+      "node": "./dist/lib/node-esm/testing/index.mjs"
     }
   },
   "types": "dist/types/src/index.d.ts",
   "typesVersions": {
-    "*": {}
+    "*": {
+      "testing": [
+        "dist/types/src/testing/index.d.ts"
+      ]
+    }
   },
   "files": [
     "dist",
@@ -25,21 +33,23 @@
     "README.md"
   ],
   "dependencies": {
-    "@bufbuild/protobuf": "^2.0.0",
     "isomorphic-ws": "^5.0.0",
     "ws": "^8.14.2",
-    "@dxos/async": "0.6.13",
-    "@dxos/context": "0.6.13",
-    "@dxos/debug": "0.6.13",
-    "@dxos/log": "0.6.13",
-    "@dxos/invariant": "0.6.13",
-    "@dxos/node-std": "0.6.13",
-    "@dxos/protocols": "0.6.13",
-    "@dxos/util": "0.6.13"
+    "@dxos/context": "0.6.14-main.69511f5",
+    "@dxos/credentials": "0.6.14-main.69511f5",
+    "@dxos/async": "0.6.14-main.69511f5",
+    "@dxos/crypto": "0.6.14-main.69511f5",
+    "@dxos/debug": "0.6.14-main.69511f5",
+    "@dxos/invariant": "0.6.14-main.69511f5",
+    "@dxos/keys": "0.6.14-main.69511f5",
+    "@dxos/log": "0.6.14-main.69511f5",
+    "@dxos/keyring": "0.6.14-main.69511f5",
+    "@dxos/node-std": "0.6.14-main.69511f5",
+    "@dxos/protocols": "0.6.14-main.69511f5",
+    "@dxos/util": "0.6.14-main.69511f5"
   },
   "devDependencies": {
-    "jest-websocket-mock": "^2.5.0",
-    "@dxos/keys": "0.6.13"
+    "@dxos/test-utils": "0.6.14-main.69511f5"
   },
   "publishConfig": {
     "access": "public"

package/src/auth.ts

@@ -0,0 +1,135 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { createCredential, signPresentation } from '@dxos/credentials';
+import { type Signer } from '@dxos/crypto';
+import { Keyring } from '@dxos/keyring';
+import { PublicKey } from '@dxos/keys';
+import { type Chain, type Credential } from '@dxos/protocols/proto/dxos/halo/credentials';
+
+import type { EdgeIdentity } from './edge-identity';
+
+/**
+ * Edge identity backed by a device key without a credential chain.
+ */
+export const createDeviceEdgeIdentity = async (signer: Signer, key: PublicKey): Promise<EdgeIdentity> => {
+  return {
+    identityKey: key.toHex(),
+    peerKey: key.toHex(),
+    presentCredentials: async ({ challenge }) => {
+      return signPresentation({
+        presentation: {
+          credentials: [
+            // Verifier requires at least one credential in the presentation to establish the subject.
+            await createCredential({
+              assertion: {
+                '@type': 'dxos.halo.credentials.Auth',
+              },
+              issuer: key,
+              subject: key,
+              signer,
+            }),
+          ],
+        },
+        signer,
+        signerKey: key,
+        nonce: challenge,
+      });
+    },
+  };
+};
+
+/**
+ * Edge identity backed by a chain of credentials.
+ */
+export const createChainEdgeIdentity = async (
+  signer: Signer,
+  identityKey: PublicKey,
+  peerKey: PublicKey,
+  chain: Chain,
+  credentials: Credential[],
+): Promise<EdgeIdentity> => {
+  const credentialsToSign =
+    credentials.length > 0
+      ? credentials
+      : [
+          await createCredential({
+            assertion: {
+              '@type': 'dxos.halo.credentials.Auth',
+            },
+            issuer: identityKey,
+            subject: identityKey,
+            signer,
+            chain,
+            signingKey: peerKey,
+          }),
+        ];
+
+  return {
+    identityKey: identityKey.toHex(),
+    peerKey: peerKey.toHex(),
+    presentCredentials: async ({ challenge }) => {
+      return signPresentation({
+        presentation: {
+          credentials: credentialsToSign,
+        },
+        signer,
+        nonce: challenge,
+        signerKey: peerKey,
+        chain,
+      });
+    },
+  };
+};
+
+/**
+ * Edge identity backed by a random ephemeral key without HALO.
+ */
+export const createEphemeralEdgeIdentity = async (): Promise<EdgeIdentity> => {
+  const keyring = new Keyring();
+  const key = await keyring.createKey();
+  return createDeviceEdgeIdentity(keyring, key);
+};
+
+/**
+ * Creates a HALO chain of credentials to act as an edge identity.
+ */
+export const createTestHaloEdgeIdentity = async (
+  signer: Signer,
+  identityKey: PublicKey,
+  deviceKey: PublicKey,
+): Promise<EdgeIdentity> => {
+  const deviceAdmission = await createCredential({
+    assertion: {
+      '@type': 'dxos.halo.credentials.AuthorizedDevice',
+      deviceKey,
+      identityKey,
+    },
+    issuer: identityKey,
+    subject: deviceKey,
+    signer,
+  });
+  return createChainEdgeIdentity(signer, identityKey, deviceKey, { credential: deviceAdmission }, [
+    await createCredential({
+      assertion: {
+        '@type': 'dxos.halo.credentials.Auth',
+      },
+      issuer: identityKey,
+      subject: identityKey,
+      signer,
+    }),
+  ]);
+};
+
+export const createStubEdgeIdentity = (): EdgeIdentity => {
+  const identityKey = PublicKey.random();
+  const deviceKey = PublicKey.random();
+  return {
+    identityKey: identityKey.toHex(),
+    peerKey: deviceKey.toHex(),
+    presentCredentials: async () => {
+      throw new Error('Stub identity does not support authentication.');
+    },
+  };
+};

package/src/defs.ts

@@ -2,10 +2,9 @@
 // Copyright 2024 DXOS.org
 //
 
-import { AnySchema } from '@bufbuild/protobuf/wkt';
-
+import { bufWkt } from '@dxos/protocols/buf';
 import { SwarmRequestSchema, SwarmResponseSchema, TextMessageSchema } from '@dxos/protocols/buf/dxos/edge/messenger_pb';
 
 import { Protocol } from './protocol';
 
-export const protocol = new Protocol([SwarmRequestSchema, SwarmResponseSchema, TextMessageSchema, AnySchema]);
+export const protocol = new Protocol([SwarmRequestSchema, SwarmResponseSchema, TextMessageSchema, bufWkt.AnySchema]);

package/src/edge-client.test.ts

@@ -2,49 +2,81 @@
 // Copyright 2024 DXOS.org
 //
 
-import chai, { expect } from 'chai';
-import chaiAsPromised from 'chai-as-promised';
+import { describe, expect, onTestFinished, test } from 'vitest';
 
-import { PublicKey } from '@dxos/keys';
+import { Trigger } from '@dxos/async';
+import { Keyring } from '@dxos/keyring';
 import { TextMessageSchema } from '@dxos/protocols/buf/dxos/edge/messenger_pb';
-import { test, describe, openAndClose } from '@dxos/test';
+import { openAndClose } from '@dxos/test-utils';
 
+import { createEphemeralEdgeIdentity, createTestHaloEdgeIdentity } from './auth';
 import { protocol } from './defs';
 import { EdgeClient } from './edge-client';
-import { createTestWsServer } from './test-utils';
-
-chai.use(chaiAsPromised);
+import { createTestEdgeWsServer } from './testing';
 
 describe('EdgeClient', () => {
   const textMessage = (message: string) => protocol.createMessage(TextMessageSchema, { payload: { message } });
 
   test('reconnects on error', async () => {
-    const { error: serverError, endpoint } = await createTestWsServer();
-    const id = PublicKey.random().toHex();
-    const client = new EdgeClient(id, id, { socketEndpoint: endpoint });
+    const { closeConnection, endpoint, cleanup } = await createTestEdgeWsServer(8001);
+    onTestFinished(cleanup);
+
+    const client = new EdgeClient(await createEphemeralEdgeIdentity(), { socketEndpoint: endpoint });
     await openAndClose(client);
     await client.send(textMessage('Hello world 1'));
     expect(client.isOpen).is.true;
 
     const reconnected = client.reconnect.waitForCount(1);
-    await serverError();
+    await closeConnection();
     await reconnected;
-    await expect(client.send(textMessage('Hello world 2'))).to.be.fulfilled;
+    await expect(client.send(textMessage('Hello world 2'))).resolves.not.toThrow();
+  });
+
+  test('isConnected', async () => {
+    const admitConnection = new Trigger();
+    const { closeConnection, endpoint, cleanup } = await createTestEdgeWsServer(8001, { admitConnection });
+    onTestFinished(cleanup);
+
+    const client = new EdgeClient(await createEphemeralEdgeIdentity(), { socketEndpoint: endpoint });
+    await openAndClose(client);
+
+    expect(client.isConnected).toBeFalsy();
+    admitConnection.wake();
+    await expect.poll(() => client.isConnected).toBeTruthy();
+
+    admitConnection.reset();
+    await closeConnection();
+    expect(client.isOpen).is.true;
+    await expect.poll(() => client.isConnected).toBeFalsy();
+
+    admitConnection.wake();
+    await expect.poll(() => client.isConnected).toBeTruthy();
   });
 
   test('set identity reconnects', async () => {
-    const { endpoint } = await createTestWsServer();
+    const { endpoint, cleanup } = await createTestEdgeWsServer(8002);
+    onTestFinished(cleanup);
 
-    const id = PublicKey.random().toHex();
-    const client = new EdgeClient(id, id, { socketEndpoint: endpoint });
+    const client = new EdgeClient(await createEphemeralEdgeIdentity(), { socketEndpoint: endpoint });
     await openAndClose(client);
     await client.send(textMessage('Hello world 1'));
     expect(client.isOpen).is.true;
 
-    const newId = PublicKey.random().toHex();
     const reconnected = client.reconnect.waitForCount(1);
-    client.setIdentity({ peerKey: newId, identityKey: newId });
+    client.setIdentity(await createEphemeralEdgeIdentity());
     await reconnected;
-    await expect(client.send(textMessage('Hello world 2'))).to.be.fulfilled;
+    await expect(client.send(textMessage('Hello world 2'))).resolves.not.toThrow();
+  });
+
+  test.skipIf(!process.env.EDGE_ENDPOINT)('connect to local edge server', async () => {
+    // const identity = await createEphemeralEdgeIdentity();
+
+    const keyring = new Keyring();
+    const identity = await createTestHaloEdgeIdentity(keyring, await keyring.createKey(), await keyring.createKey());
+
+    const client = new EdgeClient(identity, { socketEndpoint: process.env.EDGE_ENDPOINT! });
+    await openAndClose(client);
+    await client.send(textMessage('Hello world 1'));
+    expect(client.isOpen).is.true;
   });
 });

package/src/edge-client.ts

@@ -6,15 +6,16 @@ import WebSocket from 'isomorphic-ws';
 
 import { Trigger, Event, scheduleTaskInterval, scheduleTask, TriggerState } from '@dxos/async';
 import { Context, LifecycleState, Resource, type Lifecycle } from '@dxos/context';
-import { invariant } from '@dxos/invariant';
 import { log } from '@dxos/log';
 import { buf } from '@dxos/protocols/buf';
 import { type Message, MessageSchema } from '@dxos/protocols/buf/dxos/edge/messenger_pb';
 
 import { protocol } from './defs';
-import { WebsocketClosedError } from './errors';
+import { type EdgeIdentity, handleAuthChallenge } from './edge-identity';
+import { EdgeConnectionClosedError, EdgeIdentityChangedError } from './errors';
 import { PersistentLifecycle } from './persistent-lifecycle';
 import { type Protocol, toUint8Array } from './protocol';
+import { getEdgeUrlWithProtocol } from './utils';
 
 const DEFAULT_TIMEOUT = 10_000;
 const SIGNAL_KEEPALIVE_INTERVAL = 5_000;
@@ -22,13 +23,15 @@ const SIGNAL_KEEPALIVE_INTERVAL = 5_000;
 export type MessageListener = (message: Message) => void | Promise<void>;
 
 export interface EdgeConnection extends Required<Lifecycle> {
+  connected: Event;
   reconnect: Event;
 
   get info(): any;
   get identityKey(): string;
   get peerKey(): string;
   get isOpen(): boolean;
-  setIdentity(params: { peerKey: string; identityKey: string }): void;
+  get isConnected(): boolean;
+  setIdentity(identity: EdgeIdentity): void;
   addListener(listener: MessageListener): () => void;
   send(message: Message): Promise<void>;
 }
@@ -37,13 +40,15 @@ export type MessengerConfig = {
   socketEndpoint: string;
   timeout?: number;
   protocol?: Protocol;
+  disableAuth?: boolean;
 };
 
 /**
  * Messenger client.
  */
 export class EdgeClient extends Resource implements EdgeConnection {
-  public reconnect = new Event();
+  public readonly reconnect = new Event();
+  public readonly connected = new Event();
   private readonly _persistentLifecycle = new PersistentLifecycle({
     start: async () => this._openWebSocket(),
     stop: async () => this._closeWebSocket(),
@@ -51,42 +56,50 @@ export class EdgeClient extends Resource implements EdgeConnection {
   });
 
   private readonly _listeners = new Set<MessageListener>();
-  private readonly _protocol: Protocol;
   private _ready = new Trigger();
   private _ws?: WebSocket = undefined;
   private _keepaliveCtx?: Context = undefined;
   private _heartBeatContext?: Context = undefined;
 
+  private _baseWsUrl: string;
+  private _baseHttpUrl: string;
+
   constructor(
-    private _identityKey: string,
-    private _peerKey: string,
+    private _identity: EdgeIdentity,
     private readonly _config: MessengerConfig,
   ) {
     super();
-    this._protocol = this._config.protocol ?? protocol;
+    this._baseWsUrl = getEdgeUrlWithProtocol(_config.socketEndpoint, 'ws');
+    this._baseHttpUrl = getEdgeUrlWithProtocol(_config.socketEndpoint, 'http');
   }
 
   // TODO(burdon): Attach logging.
   public get info() {
     return {
       open: this.isOpen,
-      identity: this._identityKey,
-      device: this._peerKey,
+      identity: this._identity.identityKey,
+      device: this._identity.peerKey,
     };
   }
 
+  get isConnected() {
+    return Boolean(this._ws) && this._ready.state === TriggerState.RESOLVED;
+  }
+
   get identityKey() {
-    return this._identityKey;
+    return this._identity.identityKey;
   }
 
   get peerKey() {
-    return this._peerKey;
+    return this._identity.peerKey;
   }
 
-  setIdentity({ peerKey, identityKey }: { peerKey: string; identityKey: string }) {
-    this._peerKey = peerKey;
-    this._identityKey = identityKey;
-    this._persistentLifecycle.scheduleRestart();
+  setIdentity(identity: EdgeIdentity) {
+    if (identity.identityKey !== this._identity.identityKey || identity.peerKey !== this._identity.peerKey) {
+      log('Edge identity changed', { identity, oldIdentity: this._identity });
+      this._identity = identity;
+      this._persistentLifecycle.scheduleRestart();
+    }
   }
 
   public addListener(listener: MessageListener): () => void {
@@ -108,17 +121,25 @@ export class EdgeClient extends Resource implements EdgeConnection {
    * Close connection and free resources.
    */
   protected override async _close() {
-    log('closing...', { peerKey: this._peerKey });
+    log('closing...', { peerKey: this._identity.peerKey });
     await this._persistentLifecycle.close();
   }
 
   private async _openWebSocket() {
-    const url = new URL(`/ws/${this._identityKey}/${this._peerKey}`, this._config.socketEndpoint);
-    this._ws = new WebSocket(url);
+    if (this._ctx.disposed) {
+      return;
+    }
+    const path = `/ws/${this._identity.identityKey}/${this._identity.peerKey}`;
+    const protocolHeader = this._config.disableAuth ? undefined : await this._createAuthHeader(path);
+
+    const url = new URL(path, this._baseWsUrl);
+    log('Opening websocket', { url: url.toString(), protocolHeader });
+    this._ws = new WebSocket(url, protocolHeader ? [protocolHeader] : []);
 
     this._ws.onopen = () => {
       log('opened', this.info);
       this._ready.wake();
+      this.connected.emit();
     };
     this._ws.onclose = () => {
       log('closed', this.info);
@@ -138,7 +159,7 @@ export class EdgeClient extends Resource implements EdgeConnection {
       }
       const data = await toUint8Array(event.data);
       const message = buf.fromBinary(MessageSchema, data);
-      log('received', { peerKey: this._peerKey, payload: protocol.getPayloadType(message) });
+      log('received', { peerKey: this._identity.peerKey, payload: protocol.getPayloadType(message) });
       if (message) {
         for (const listener of this._listeners) {
           try {
@@ -150,7 +171,11 @@ export class EdgeClient extends Resource implements EdgeConnection {
       }
     };
 
+    // TODO(dmaretskyi): Potential race condition here since web socket errors don't resolve this trigger.
     await this._ready.wait({ timeout: this._config.timeout ?? DEFAULT_TIMEOUT });
+    log('Websocket is ready', { identity: this._identity.identityKey, peer: this._identity.peerKey });
+
+    // TODO(dmaretskyi): Potential leak: context re-assigned without disposing the previous one.
     this._keepaliveCtx = new Context();
     scheduleTaskInterval(
       this._keepaliveCtx,
@@ -170,7 +195,7 @@ export class EdgeClient extends Resource implements EdgeConnection {
       return;
     }
     try {
-      this._ready.throw(new WebsocketClosedError());
+      this._ready.throw(this.isOpen ? new EdgeIdentityChangedError() : new EdgeConnectionClosedError());
       this._ready.reset();
       void this._keepaliveCtx?.dispose();
       this._keepaliveCtx = undefined;
@@ -197,11 +222,20 @@ export class EdgeClient extends Resource implements EdgeConnection {
    */
   public async send(message: Message): Promise<void> {
     if (this._ready.state !== TriggerState.RESOLVED) {
+      log('waiting for websocket to become ready');
       await this._ready.wait({ timeout: this._config.timeout ?? DEFAULT_TIMEOUT });
     }
-    invariant(this._ws);
-    invariant(!message.source || message.source.peerKey === this._peerKey);
-    log('sending...', { peerKey: this._peerKey, payload: protocol.getPayloadType(message) });
+    if (!this._ws) {
+      throw new EdgeConnectionClosedError();
+    }
+    if (
+      message.source &&
+      (message.source.peerKey !== this._identity.peerKey || message.source.identityKey !== this.identityKey)
+    ) {
+      throw new EdgeIdentityChangedError();
+    }
+
+    log('sending...', { peerKey: this._identity.peerKey, payload: protocol.getPayloadType(message) });
     this._ws.send(buf.toBinary(MessageSchema, message));
   }
 
@@ -219,4 +253,22 @@ export class EdgeClient extends Resource implements EdgeConnection {
       2 * SIGNAL_KEEPALIVE_INTERVAL,
     );
   }
+
+  private async _createAuthHeader(path: string): Promise<string | undefined> {
+    const httpUrl = new URL(path, this._baseHttpUrl);
+    httpUrl.protocol = getEdgeUrlWithProtocol(this._baseWsUrl.toString(), 'http');
+    const response = await fetch(httpUrl, { method: 'GET' });
+    if (response.status === 401) {
+      return encodePresentationWsAuthHeader(await handleAuthChallenge(response, this._identity));
+    } else {
+      log.warn('no auth challenge from edge', { status: response.status, statusText: response.statusText });
+      return undefined;
+    }
+  }
 }
+
+const encodePresentationWsAuthHeader = (encodedPresentation: Uint8Array): string => {
+  // = and / characters are not allowed in the WebSocket subprotocol header.
+  const encodedToken = Buffer.from(encodedPresentation).toString('base64').replace(/=*$/, '').replaceAll('/', '|');
+  return `base64url.bearer.authorization.dxos.org.${encodedToken}`;
+};