@dxos/edge-client 0.6.12 → 0.6.13-main.548ca8d

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-client';
+
+/**
+ * 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,18 @@ 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 { randomBytes } from '@dxos/crypto';
 import { log } from '@dxos/log';
 import { buf } from '@dxos/protocols/buf';
 import { type Message, MessageSchema } from '@dxos/protocols/buf/dxos/edge/messenger_pb';
+import { schema } from '@dxos/protocols/proto';
+import { type Presentation } from '@dxos/protocols/proto/dxos/halo/credentials';
 
 import { protocol } from './defs';
-import { WebsocketClosedError } from './errors';
+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 +25,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 +42,26 @@ export type MessengerConfig = {
   socketEndpoint: string;
   timeout?: number;
   protocol?: Protocol;
+  disableAuth?: boolean;
 };
 
+export interface EdgeIdentity {
+  peerKey: string;
+  identityKey: string;
+  /**
+   * Returns credential presentation issued by the identity key.
+   * Presentation must have the provided challenge.
+   * Presentation may include ServiceAccess credentials.
+   */
+  presentCredentials({ challenge }: { challenge: Uint8Array }): Promise<Presentation>;
+}
+
 /**
  * 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,41 +69,44 @@ 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 _baseUrl: string;
+
   constructor(
-    private _identityKey: string,
-    private _peerKey: string,
+    private _identity: EdgeIdentity,
     private readonly _config: MessengerConfig,
   ) {
     super();
-    this._protocol = this._config.protocol ?? protocol;
+    this._baseUrl = getEdgeUrlWithProtocol(_config.socketEndpoint, 'ws');
   }
 
   // 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;
+  setIdentity(identity: EdgeIdentity) {
+    this._identity = identity;
     this._persistentLifecycle.scheduleRestart();
   }
 
@@ -108,17 +129,32 @@ 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);
+    let protocolHeader: string | undefined;
+
+    if (!this._config.disableAuth) {
+      // TODO(dmaretskyi): Get challenge from the WWW-Authenticate header returned by the endpoint.
+      const challenge = randomBytes(32);
+      const credential = await this._identity.presentCredentials({ challenge });
+      protocolHeader = encodePresentationIntoAuthHeader(credential);
+    }
+
+    if (this._ctx.disposed) {
+      return;
+    }
+
+    const url = new URL(`/ws/${this._identity.identityKey}/${this._identity.peerKey}`, this._baseUrl);
+    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 +174,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 +186,10 @@ 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 });
+
+    // TODO(dmaretskyi): Potential leak: context re-assigned without disposing the previous one.
     this._keepaliveCtx = new Context();
     scheduleTaskInterval(
       this._keepaliveCtx,
@@ -170,7 +209,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 +236,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));
   }
 
@@ -220,3 +268,11 @@ export class EdgeClient extends Resource implements EdgeConnection {
     );
   }
 }
+
+const encodePresentationIntoAuthHeader = (presentation: Presentation): string => {
+  const encoded = schema.getCodecForType('dxos.halo.credentials.Presentation').encode(presentation);
+  // = and / characters are not allowed in the WebSocket subprotocol header.
+  const encodedToken = Buffer.from(encoded).toString('base64').replace(/=*$/, '').replaceAll('/', '|');
+
+  return `base64url.bearer.authorization.dxos.org.${encodedToken}`;
+};

package/src/edge-http-client.ts

@@ -0,0 +1,151 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { sleep } from '@dxos/async';
+import { Context } from '@dxos/context';
+import { type SpaceId } from '@dxos/keys';
+import { log } from '@dxos/log';
+import {
+  EdgeCallFailedError,
+  type EdgeHttpResponse,
+  type GetNotarizationResponseBody,
+  type PostNotarizationRequestBody,
+  type JoinSpaceRequest,
+  type JoinSpaceResponseBody,
+  EdgeAuthChallengeError,
+} from '@dxos/protocols';
+
+import { getEdgeUrlWithProtocol } from './utils';
+
+const DEFAULT_RETRY_TIMEOUT = 1500;
+const DEFAULT_RETRY_JITTER = 500;
+const DEFAULT_MAX_RETRIES_COUNT = 3;
+
+export class EdgeHttpClient {
+  private readonly _baseUrl: string;
+
+  constructor(baseUrl: string) {
+    this._baseUrl = getEdgeUrlWithProtocol(baseUrl, 'http');
+    log('created', { url: this._baseUrl });
+  }
+
+  public getCredentialsForNotarization(spaceId: SpaceId, args?: EdgeHttpGetArgs): Promise<GetNotarizationResponseBody> {
+    return this._call(`/spaces/${spaceId}/notarization`, { ...args, method: 'GET' });
+  }
+
+  public async notarizeCredentials(
+    spaceId: SpaceId,
+    body: PostNotarizationRequestBody,
+    args?: EdgeHttpGetArgs,
+  ): Promise<void> {
+    await this._call(`/spaces/${spaceId}/notarization`, { ...args, body, method: 'POST' });
+  }
+
+  public async joinSpaceByInvitation(
+    spaceId: SpaceId,
+    body: JoinSpaceRequest,
+    args?: EdgeHttpGetArgs,
+  ): Promise<JoinSpaceResponseBody> {
+    return this._call(`/spaces/${spaceId}/join`, { ...args, body, method: 'POST' });
+  }
+
+  private async _call<T>(path: string, args: EdgeHttpCallArgs): Promise<T> {
+    const requestContext = args.context ?? new Context();
+    const shouldRetry = createRetryHandler(args);
+    const request = createRequest(args);
+    const url = `${this._baseUrl}${path.startsWith('/') ? path.slice(1) : path}`;
+
+    log.info('call', { method: args.method, path });
+
+    while (true) {
+      let processingError: EdgeCallFailedError;
+      let retryAfterHeaderValue: number = Number.NaN;
+      try {
+        const response = await fetch(url, request);
+
+        retryAfterHeaderValue = Number(response.headers.get('Retry-After'));
+
+        if (response.ok) {
+          const body = (await response.json()) as EdgeHttpResponse<T>;
+          if (body.success) {
+            return body.data;
+          }
+
+          if (body.errorData?.type === 'auth_challenge' && typeof body.errorData?.challenge === 'string') {
+            processingError = new EdgeAuthChallengeError(body.errorData.challenge, body.errorData);
+          } else {
+            processingError = EdgeCallFailedError.fromUnsuccessfulResponse(response, body);
+          }
+        } else {
+          processingError = EdgeCallFailedError.fromHttpFailure(response);
+        }
+      } catch (error: any) {
+        processingError = EdgeCallFailedError.fromProcessingFailureCause(error);
+      }
+
+      if (processingError.isRetryable && (await shouldRetry(requestContext, retryAfterHeaderValue))) {
+        log.info('retrying edge request', { path, processingError });
+      } else {
+        throw processingError;
+      }
+    }
+  }
+}
+
+const createRequest = (args: EdgeHttpCallArgs): RequestInit => {
+  return {
+    method: args.method,
+    body: args.body && JSON.stringify(args.body),
+  };
+};
+
+const createRetryHandler = (args: EdgeHttpCallArgs) => {
+  if (!args.retry || args.retry.count < 1) {
+    return async () => false;
+  }
+  let retries = 0;
+  const maxRetries = args.retry.count ?? DEFAULT_MAX_RETRIES_COUNT;
+  const baseTimeout = args.retry.timeout ?? DEFAULT_RETRY_TIMEOUT;
+  const jitter = args.retry.jitter ?? DEFAULT_RETRY_JITTER;
+  return async (ctx: Context, retryAfter: number) => {
+    if (++retries > maxRetries || ctx.disposed) {
+      return false;
+    }
+
+    if (retryAfter) {
+      await sleep(retryAfter);
+    } else {
+      const timeout = baseTimeout + Math.random() * jitter;
+      await sleep(timeout);
+    }
+
+    return true;
+  };
+};
+
+export type RetryConfig = {
+  /**
+   * A number of call retries, not counting the initial request.
+   */
+  count: number;
+  /**
+   * Delay before retries in ms.
+   */
+  timeout?: number;
+  /**
+   * A random amount of time before retrying to help prevent large bursts of requests.
+   */
+  jitter?: number;
+};
+
+export type EdgeHttpGetArgs = { context?: Context; retry?: RetryConfig };
+
+export type EdgeHttpPostArgs = { context?: Context; body?: any; retry?: RetryConfig };
+
+type EdgeHttpCallArgs = {
+  method: string;
+  body?: any;
+  context?: Context;
+  retry?: RetryConfig;
+};

package/src/errors.ts

@@ -2,8 +2,14 @@
 // Copyright 2024 DXOS.org
 //
 
-export class WebsocketClosedError extends Error {
+export class EdgeConnectionClosedError extends Error {
   constructor() {
-    super('WebSocket connection closed');
+    super('Edge connection closed.');
+  }
+}
+
+export class EdgeIdentityChangedError extends Error {
+  constructor() {
+    super('Edge identity changed.');
   }
 }

package/src/index.ts

@@ -7,3 +7,6 @@ export * from '@dxos/protocols/buf/dxos/edge/messenger_pb';
 export * from './edge-client';
 export * from './defs';
 export * from './protocol';
+export * from './errors';
+export * from './auth';
+export * from './edge-http-client';

package/src/persistent-lifecycle.test.ts

@@ -2,11 +2,11 @@
 // Copyright 2024 DXOS.org
 //
 
-import { expect } from 'chai';
+import { describe, expect, test } from 'vitest';
 
 import { sleep, Trigger } from '@dxos/async';
 import { log } from '@dxos/log';
-import { describe, openAndClose, test } from '@dxos/test';
+import { openAndClose } from '@dxos/test-utils';
 
 import { PersistentLifecycle } from './persistent-lifecycle';
 

package/src/protocol.test.ts

@@ -2,7 +2,7 @@
 // Copyright 2024 DXOS.org
 //
 
-import { expect } from 'chai';
+import { describe, expect, test } from 'vitest';
 
 import { buf } from '@dxos/protocols/buf';
 import {
@@ -11,7 +11,6 @@ import {
   SwarmRequestSchema,
   SwarmResponseSchema,
 } from '@dxos/protocols/buf/dxos/edge/messenger_pb';
-import { describe, test } from '@dxos/test';
 
 import { Protocol } from './protocol';