@dxos/client-services 0.10.0 → 0.11.1

package/src/packlets/services/spec.md

@@ -0,0 +1,106 @@
+# ServiceContext → Effect Layers
+
+Replace `ServiceContext` (monolithic `Resource`) with a composed stack of Effect layers.
+
+## Conventions
+
+| Item                   | Rule                                                                                                                                                           |
+| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Tag name**           | Prefer interface name + `Service` (`IMetadataStore` → `IMetadataStoreService`). No interface → impl name + `Service` (`SpaceManager` → `SpaceManagerService`). |
+| **Tag placement**      | Top of defining file: after interface/type, before impl class.                                                                                                 |
+| **Layer placement**    | Bottom of defining file.                                                                                                                                       |
+| **Layer options**      | Value-based config (flags, callbacks, runtime props) go in the layer constructor `options` object.                                                             |
+| **Layer requirements** | Injected components go in the layer's `Requirements` type (resolved via `yield*` on sibling tags).                                                             |
+
+```ts
+// Tag (after interface)
+export class IMetadataStoreService extends EffectContext.Tag('...')<
+  IMetadataStoreService,
+  IMetadataStore
+>() {}
+
+// Layer (bottom of file)
+export const SqliteMetadataStoreLayer = (): Layer.Layer<
+  IMetadataStoreService,
+  never,
+  SqlClient.SqlClient | SqlTransactionTag
+> => Layer.effect(IMetadataStoreService, Effect.gen(function* () { ... }));
+```
+
+## Component map
+
+Status: `done` | `todo`
+
+### Storage / persistence
+
+| Component                                | Tag                     | Layer                           | Options | Requirements                  | Status |
+| ---------------------------------------- | ----------------------- | ------------------------------- | ------- | ----------------------------- | ------ |
+| `IMetadataStore` / `SqliteMetadataStore` | `IMetadataStoreService` | `SqliteMetadataStoreLayer()`    | —       | `SqlClient \| SqlTransaction` | done   |
+| `BlobStoreApi` / `SqliteBlobStore`       | `BlobStoreApiService`   | `SqliteBlobStoreLayer()`        | —       | `SqlClient \| SqlTransaction` | done   |
+| `KeyringApi` / `SqliteKeyring`           | `KeyringApiService`     | `SqliteKeyringLayer()`          | —       | `SqlClient \| SqlTransaction` | done   |
+| `SqliteStorage`                          | `SqliteStorageService`  | `SqliteStorageLayer({ path? })` | `path?` | `SqlClient \| SqlTransaction` | done   |
+
+### Feeds
+
+| Component                      | Tag                           | Layer                                 | Options      | Requirements                                       | Status |
+| ------------------------------ | ----------------------------- | ------------------------------------- | ------------ | -------------------------------------------------- | ------ |
+| `FeedFactory`                  | `FeedFactoryService`          | `FeedFactoryLayer({ hypercore? })`    | `hypercore?` | `KeyringApiService`, `FeedStorageDirectoryService` | done   |
+| `FeedStore` (@dxos/feed-store) | `FeedStoreService`            | `FeedStoreLayer()`                    | —            | `FeedFactoryService`                               | done   |
+| `FeedStorageDirectory`         | `FeedStorageDirectoryService` | `FeedStorageDirectoryLayer({ sub? })` | `sub?`       | `SqliteStorageService`                             | done   |
+
+### Spaces / echo
+
+| Component                      | Tag                              | Layer                                                                    | Options                  | Requirements                                                                                     | Status |
+| ------------------------------ | -------------------------------- | ------------------------------------------------------------------------ | ------------------------ | ------------------------------------------------------------------------------------------------ | ------ |
+| `SpaceManager`                 | `SpaceManagerService`            | `SpaceManagerLayer({ disableP2pReplication? })`                          | `disableP2pReplication?` | `FeedStoreService`, `SwarmNetworkManagerService`, `IMetadataStoreService`, `BlobStoreApiService` | done   |
+| `EchoHost`                     | `EchoHostService`                | `EchoHostLayer({ ...callbacks, useSubduction?, assignQueuePositions? })` | callbacks, flags         | `SqlClient \| SqlTransaction`                                                                    | done   |
+| `MeshEchoReplicator`           | `AutomergeReplicatorService`     | `MeshEchoReplicatorLayer()`                                              | —                        | —                                                                                                | done   |
+| `EchoEdgeReplicator`           | `EdgeAutomergeReplicatorService` | `EchoEdgeReplicatorLayer({ disableSharePolicy? })`                       | `disableSharePolicy?`    | `EdgeConnectionService`, `EdgeHttpClientService`                                                 | done   |
+| `EchoEdgeSubductionReplicator` | `EdgeAutomergeReplicatorService` | `EchoEdgeSubductionReplicatorLayer({ disableSharePolicy? })`             | `disableSharePolicy?`    | `EdgeConnectionService`, `EdgeHttpClientService`                                                 | done   |
+
+### Identity / invitations / spaces (client-services)
+
+| Component                      | Tag                                   | Layer                                                                 | Options                                                   | Requirements                                                                                                                                                                                              | Status |
+| ------------------------------ | ------------------------------------- | --------------------------------------------------------------------- | --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ |
+| `IdentityManager`              | `IdentityManagerService`              | `IdentityManagerLayer({ devicePresence*, edgeFeatures? })`            | presence intervals, edge features                         | `IMetadataStoreService`, `KeyringApiService`, `FeedStoreService`, `SpaceManagerService`, `EdgeConnectionService?`                                                                                         | done   |
+| `EdgeIdentityRecoveryManager`  | `EdgeIdentityRecoveryManagerService`  | `EdgeIdentityRecoveryManagerLayer()`                                  | — (wire `setAcceptRecoveredIdentity` after stack compose) | `KeyringApiService`, `EdgeHttpClientService?`, `IdentityManagerService`                                                                                                                                   | done   |
+| `InvitationsHandler`           | `InvitationsHandlerService`           | `InvitationsHandlerLayer({ connectionProps? })`                       | `connectionProps?`                                        | `SwarmNetworkManagerService`, `EdgeHttpClientService?`                                                                                                                                                    | done   |
+| `InvitationsManager`           | `InvitationsManagerService`           | `InvitationsManagerLayer({ getHandler })`                             | `getHandler` callback                                     | `InvitationsHandlerService`, `IMetadataStoreService`                                                                                                                                                      | done   |
+| `DataSpaceManager`             | `DataSpaceManagerService`             | `DataSpaceManagerLayer({ runtimeProps?, edgeFeatures? })`             | runtime props, edge features                              | `SpaceManagerService`, `IMetadataStoreService`, `KeyringApiService`, `SigningContextProviderService`, `FeedStoreService`, `EchoHostService`, `InvitationsManagerService`, edge/replicator deps (optional) | done   |
+| `SigningContextProvider`       | `SigningContextProviderService`       | `SigningContextProviderLayer`                                         | —                                                         | `IdentityProviderService`                                                                                                                                                                                 | done   |
+| `EdgeAgentManager`             | `EdgeAgentManagerService`             | `EdgeAgentManagerLayer({ edgeFeatures? })`                            | edge features                                             | `DataSpaceManagerService`, `IdentityProviderService`, `EdgeHttpClientService?`                                                                                                                            | done   |
+| `CrossDeviceSpaceSynchronizer` | `CrossDeviceSpaceSynchronizerService` | `CrossDeviceSpaceSynchronizerLayer`                                   | —                                                         | `DataSpaceManagerService`                                                                                                                                                                                 | done   |
+| `IdentityProvider`             | `IdentityProviderService`             | supplied at runtime (e.g. `identityProviderFromManager`)              | —                                                         | —                                                                                                                                                                                                         | done   |
+| `FeedSyncer`                   | `FeedSyncerService`                   | `FeedSyncerLayer({ peerId, syncNamespaces, getSpaceIds, ...tuning })` | peer/sync config                                          | `SqlClient \| SqlTransaction`, `FeedStoreService` (@dxos/feed), `EdgeConnectionService`                                                                                                                   | done   |
+
+### External inputs (provided by host, not constructed inside ServiceContext)
+
+| Component             | Tag                                               | Notes                      |
+| --------------------- | ------------------------------------------------- | -------------------------- |
+| `SwarmNetworkManager` | `SwarmNetworkManagerService`                      | host-provided              |
+| `SignalManager`       | `SignalManagerService`                            | todo                       |
+| `EdgeConnection`      | `EdgeConnectionService`                           | host-provided              |
+| `EdgeHttpClient`      | `EdgeHttpClientService`                           | host-provided              |
+| `RuntimeProvider`     | ambient via `SqlClient` + `SqlTransaction` layers | not a ServiceContext field |
+
+## Target layer stack (sketch)
+
+```ts
+const ServiceContextLive = Layer.mergeAll(
+  SqliteMetadataStoreLayer(),
+  SqliteBlobStoreLayer(),
+  SqliteKeyringLayer(),
+  SqliteStorageLayer(),
+  FeedFactoryLayer({ hypercore: { valueEncoding, stats: true } }),
+  FeedStoreLayer(),
+  SpaceManagerLayer({ disableP2pReplication }),
+  EchoHostLayer({ peerIdProvider, getSpaceKeyByRootDocumentId, syncFeed, getSyncState, useSubduction }),
+  // ...identity, invitations, data-space layers
+).pipe(Layer.provideMerge(SqlTransaction.layer), Layer.provideMerge(sqliteLayer));
+```
+
+## Open questions
+
+1. **Lifecycle** — identity-bound services (`DataSpaceManager`, `EdgeAgentManager`, `CrossDeviceSpaceSynchronizer`) are constructed dormant by their layers; `open`/`close` is called explicitly after identity is ready (e.g. in `_initialize`).
+2. **Provider wiring** — `SigningContextProviderLayer` and `IdentityProviderService` must be provided before `DataSpaceManagerLayer` / `EdgeAgentManagerLayer` can run.
+3. **Callbacks** — `EchoHost` and `InvitationsManager` need callbacks that close over other services; pass as layer options or resolve via `Effect.gen` at a higher layer.

package/src/packlets/services/sqlite-storage.test.ts

@@ -0,0 +1,48 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, expect, test } from 'vitest';
+
+import { isClosedConnectionError } from './sqlite-storage';
+
+// `SqliteRandomAccessFile._loadFromDb` swallows a read that races client teardown only when the
+// error signals a closed connection. Getting this predicate wrong reintroduces the flake where a
+// background load rejects unhandled after the SQL connection closed, crashing the whole test
+// worker (exit 1 with no failing test).
+describe('isClosedConnectionError', () => {
+  test('matches the raw sqlite closed-connection error', () => {
+    expect(isClosedConnectionError(new TypeError('The database connection is not open'))).toBe(true);
+  });
+
+  test('matches when wrapped in an effect SqlError cause chain', () => {
+    const wrapped = Object.assign(new Error('Failed to execute statement'), {
+      _tag: 'SqlError',
+      cause: new TypeError('The database connection is not open'),
+    });
+    expect(isClosedConnectionError(wrapped)).toBe(true);
+  });
+
+  test('matches a plain string message', () => {
+    expect(isClosedConnectionError('SqliteError: the database connection is not open')).toBe(true);
+  });
+
+  test('does not match a genuine query error against a live connection', () => {
+    const real = Object.assign(new Error('Failed to execute statement'), {
+      cause: new Error('no such table: hypercore_files'),
+    });
+    expect(isClosedConnectionError(real)).toBe(false);
+  });
+
+  test('is safe on null / undefined / non-error values', () => {
+    expect(isClosedConnectionError(null)).toBe(false);
+    expect(isClosedConnectionError(undefined)).toBe(false);
+    expect(isClosedConnectionError(42)).toBe(false);
+  });
+
+  test('terminates on a self-referential cause chain', () => {
+    const cyclic: any = new Error('boom');
+    cyclic.cause = cyclic;
+    expect(isClosedConnectionError(cyclic)).toBe(false);
+  });
+});

package/src/packlets/services/sqlite-storage.ts

@@ -4,10 +4,13 @@
 
 import * as SqlClient from '@effect/sql/SqlClient';
 import type * as SqlError from '@effect/sql/SqlError';
+import * as EffectContext from 'effect/Context';
 import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
 import type { Callback, FileStat, RandomAccessStorage } from 'random-access-storage';
 
 import { RuntimeProvider } from '@dxos/effect';
+import { FeedStorageDirectoryService } from '@dxos/feed-store';
 import { log } from '@dxos/log';
 import { Directory, type File, type Storage, StorageType, wrapFile } from '@dxos/random-access-storage';
 import { SqlTransaction } from '@dxos/sql-sqlite';
@@ -15,10 +18,33 @@ import { SqlTransaction } from '@dxos/sql-sqlite';
 // SqlTransaction.SqlTransaction is the Tag class exported from the SqlTransaction namespace.
 type SqlTransactionTag = SqlTransaction.SqlTransaction;
 
+/**
+ * True when a rejected SQL op failed because its connection was already closed — the message
+ * `The database connection is not open` (raised by `@effect/sql-sqlite-node`), which arrives
+ * wrapped as an effect `SqlError`, so walk the `cause` chain. Signals teardown, not a real fault.
+ */
+export const isClosedConnectionError = (err: unknown): boolean => {
+  for (let cur: any = err, depth = 0; cur != null && depth < 5; cur = cur.cause, depth++) {
+    const message = typeof cur === 'string' ? cur : cur.message;
+    if (typeof message === 'string' && /connection is not open/i.test(message)) {
+      return true;
+    }
+  }
+  return false;
+};
+
 export type SqliteStorageOptions = {
   runtime: RuntimeProvider.RuntimeProvider<SqlClient.SqlClient | SqlTransactionTag>;
 };
 
+/**
+ * Effect service tag for {@link SqliteStorage}.
+ */
+export class SqliteStorageService extends EffectContext.Tag('@dxos/client-services/SqliteStorage')<
+  SqliteStorageService,
+  SqliteStorage
+>() {}
+
 /** Minimal cross-platform EventEmitter needed by the RandomAccessStorage contract. */
 class BaseEventEmitter {
   readonly #events: Record<string, ((...args: unknown[]) => void)[]> = Object.create(null);
@@ -135,7 +161,11 @@ class SqliteRandomAccessFile extends BaseEventEmitter implements RandomAccessSto
 
   #buffer: Buffer = Buffer.alloc(0);
   #loaded = false;
+  // The one-shot initial DB read (populates `#buffer`); set once, on first access.
   #loading: Promise<void> | null = null;
+  // The latest in-flight DB write (from `write`/`del`); replaced on each save, so it always
+  // tracks the most recent one. `close()` drains both before reporting closed.
+  #saving: Promise<void> | null = null;
 
   constructor(
     private readonly filePath: string,
@@ -161,6 +191,11 @@ class SqliteRandomAccessFile extends BaseEventEmitter implements RandomAccessSto
     }
     if (!this.#loading) {
       this.#loading = this._loadFromDb();
+      // Mark the cached load promise as handled so that if it rejects after every awaiter is gone
+      // (e.g. the SQL runtime is disposed at teardown without close() being called on this file),
+      // the rejection is never surfaced as an unhandled rejection. Legitimate awaiters still observe
+      // the error through their own `.then`/`.catch` on the same promise returned below.
+      this.#loading.catch(() => {});
     }
     return this.#loading;
   }
@@ -176,11 +211,14 @@ class SqliteRandomAccessFile extends BaseEventEmitter implements RandomAccessSto
       );
       this.#buffer = rows.length > 0 ? Buffer.from(rows[0].data) : Buffer.alloc(0);
     } catch (err) {
-      // The SQL connection may close mid-read during teardown (the `#closed` guard in `_ensureLoaded`
-      // only catches reads that have not yet started). A read racing teardown rejects with
-      // "database connection is not open"; swallow it once closed and fall back to the empty buffer,
-      // otherwise surface the genuine error.
-      if (!this.#closed) {
+      // A read racing teardown rejects with "database connection is not open". The `#closed` guard
+      // in `_ensureLoaded` only catches reads not yet started, and `#closed` covers only this file
+      // being closed — during client disposal the shared SQL connection can be torn down while this
+      // file's `#closed` is still false (the container closed the connection without closing every
+      // file first). In either case a closed connection means there is nothing to load, so fall back
+      // to the empty `#buffer`; rethrow only a genuine error against a live connection. Swallowing an
+      // unhandled rejection here otherwise crashes the whole test worker (exit 1, no test failure).
+      if (!this.#closed && !isClosedConnectionError(err)) {
         throw err;
       }
     }
@@ -190,16 +228,27 @@ class SqliteRandomAccessFile extends BaseEventEmitter implements RandomAccessSto
   private async _saveToDb(): Promise<void> {
     const filePath = this.filePath;
     const data = this.#buffer;
-    await RuntimeProvider.runPromise(this.runtime)(
-      Effect.gen(function* () {
-        const sql = yield* SqlClient.SqlClient;
-        yield* sql`INSERT OR REPLACE INTO hypercore_files (path, data) VALUES (${filePath}, ${data})`;
-      }),
-    );
+    try {
+      await RuntimeProvider.runPromise(this.runtime)(
+        Effect.gen(function* () {
+          const sql = yield* SqlClient.SqlClient;
+          yield* sql`INSERT OR REPLACE INTO hypercore_files (path, data) VALUES (${filePath}, ${data})`;
+        }),
+      );
+    } catch (err) {
+      // Symmetric with `_loadFromDb`: a write racing teardown rejects (as `SqlError: Failed to
+      // execute statement` wrapping "connection is not open") when the shared SQL connection is
+      // torn down before this file's `#closed` flips. Persisting to a dead connection is moot
+      // during disposal, so swallow it; rethrow only a genuine failure against a live connection.
+      // An unswallowed rejection here surfaces as an unhandled rejection that fails the test worker.
+      if (!this.#closed && !isClosedConnectionError(err)) {
+        throw err;
+      }
+    }
   }
 
   write(offset: number, data: Buffer, cb: Callback<any>): void {
-    this._ensureLoaded()
+    const saving = this._ensureLoaded()
       .then(() => {
         const end = offset + data.length;
         if (end > this.#buffer.length) {
@@ -210,8 +259,14 @@ class SqliteRandomAccessFile extends BaseEventEmitter implements RandomAccessSto
         data.copy(this.#buffer, offset);
         return this._saveToDb();
       })
-      .then(() => cb(null))
-      .catch((err) => cb(err));
+      .then(
+        () => cb(null),
+        (err) => cb(err),
+      );
+    // Track the in-flight save so `close()` can drain it before reporting closed — otherwise a
+    // write racing `close()` (e.g. a background sync write racing `client.reset()`'s teardown)
+    // keeps running against a connection the container may tear down immediately after.
+    this.#saving = saving.catch(() => {});
   }
 
   read(offset: number, size: number, cb: Callback<Buffer>): void {
@@ -231,7 +286,7 @@ class SqliteRandomAccessFile extends BaseEventEmitter implements RandomAccessSto
   }
 
   del(offset: number, size: number, cb: Callback<any>): void {
-    this._ensureLoaded()
+    const saving = this._ensureLoaded()
       .then(() => {
         const end = Math.min(offset + size, this.#buffer.length);
         if (offset < end) {
@@ -239,8 +294,12 @@ class SqliteRandomAccessFile extends BaseEventEmitter implements RandomAccessSto
         }
         return this._saveToDb();
       })
-      .then(() => cb(null))
-      .catch((err) => cb(err));
+      .then(
+        () => cb(null),
+        (err) => cb(err),
+      );
+    // See `write()`: track the in-flight save so `close()` can drain it before reporting closed.
+    this.#saving = saving.catch(() => {});
   }
 
   stat(cb: Callback<FileStat>): void {
@@ -253,9 +312,11 @@ class SqliteRandomAccessFile extends BaseEventEmitter implements RandomAccessSto
 
   close(cb: Callback<Error>): void {
     this.#closed = true;
-    // Drain any in-flight initial load before reporting closed, so a read never races a
-    // torn-down SQL connection (avoids "database connection is not open" unhandled rejections).
-    (this.#loading ?? Promise.resolve()).then(
+    // Drain any in-flight initial load and any in-flight write/del before reporting closed, so
+    // neither races a torn-down SQL connection (avoids "database connection is not open" errors,
+    // and the resulting stall in callers — e.g. `client.reset()`'s feed teardown — that wait on
+    // this file's `close()` to settle before tearing down the connection itself).
+    Promise.all([this.#loading ?? Promise.resolve(), this.#saving ?? Promise.resolve()]).then(
       () => cb(null),
       () => cb(null),
     );
@@ -398,3 +459,39 @@ export class SqliteStorage implements Storage {
     this.#nativeFiles.clear();
   }
 }
+
+export type SqliteStorageLayerOptions = {
+  path?: string;
+};
+
+/**
+ * Effect Layer constructing a {@link SqliteStorage} from the ambient SQL runtime.
+ */
+export const SqliteStorageLayer = (
+  options: SqliteStorageLayerOptions = {},
+): Layer.Layer<SqliteStorageService, never, SqlClient.SqlClient | SqlTransactionTag> =>
+  Layer.effect(
+    SqliteStorageService,
+    Effect.gen(function* () {
+      const runtime = yield* RuntimeProvider.currentRuntime<SqlClient.SqlClient | SqlTransactionTag>();
+      return new SqliteStorage({ runtime }, options.path);
+    }),
+  );
+
+export type FeedStorageDirectoryLayerOptions = {
+  sub?: string;
+};
+
+/**
+ * Effect Layer providing the hypercore feeds root directory from {@link SqliteStorage}.
+ */
+export const FeedStorageDirectoryLayer = (
+  options: FeedStorageDirectoryLayerOptions = {},
+): Layer.Layer<FeedStorageDirectoryService, never, SqliteStorageService> =>
+  Layer.effect(
+    FeedStorageDirectoryService,
+    Effect.gen(function* () {
+      const storage = yield* SqliteStorageService;
+      return storage.createDirectory(options.sub ?? 'feeds');
+    }),
+  );

package/src/packlets/space/admission-discovery-extension.ts

@@ -0,0 +1,91 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { type Trigger, scheduleTask } from '@dxos/async';
+import { Context } from '@dxos/context';
+import { ProtocolError } from '@dxos/protocols';
+import { schema } from '@dxos/protocols/proto';
+import { type Credential } from '@dxos/protocols/proto/dxos/halo/credentials';
+import {
+  type AdmissionDiscoveryService,
+  type GetAdmissionCredentialRequest,
+  type GetAdmissionCredentialResponse,
+} from '@dxos/protocols/proto/dxos/mesh/teleport';
+import { type ExtensionContext, RpcExtension } from '@dxos/teleport';
+
+import { type Space } from './space';
+
+/**
+ * Guest's side for a connection to a concrete peer in p2p network during invitation.
+ */
+export class CredentialRetrieverExtension extends RpcExtension<
+  { AdmissionDiscoveryService: AdmissionDiscoveryService },
+  {}
+> {
+  private _ctx = new Context();
+
+  constructor(
+    private readonly _request: GetAdmissionCredentialRequest,
+    private readonly _onResult: Trigger<Credential>,
+  ) {
+    super({
+      requested: {
+        AdmissionDiscoveryService: schema.getService('dxos.mesh.teleport.AdmissionDiscoveryService'),
+      },
+    });
+  }
+
+  protected override async getHandlers(): Promise<{}> {
+    return {};
+  }
+
+  override async onOpen(context: ExtensionContext): Promise<void> {
+    await super.onOpen(context);
+    scheduleTask(this._ctx, async () => {
+      try {
+        const result = await this.rpc.AdmissionDiscoveryService.getAdmissionCredential(this._request);
+        this._onResult.wake(result.admissionCredential);
+      } catch (err: any) {
+        context.close(err);
+      }
+    });
+  }
+
+  override async onClose(): Promise<void> {
+    await this._ctx.dispose();
+  }
+
+  override async onAbort(): Promise<void> {
+    await this._ctx.dispose();
+  }
+}
+
+export class CredentialServerExtension extends RpcExtension<
+  {},
+  { AdmissionDiscoveryService: AdmissionDiscoveryService }
+> {
+  constructor(private readonly _space: Space) {
+    super({
+      exposed: {
+        AdmissionDiscoveryService: schema.getService('dxos.mesh.teleport.AdmissionDiscoveryService'),
+      },
+    });
+  }
+
+  protected override async getHandlers(): Promise<{ AdmissionDiscoveryService: AdmissionDiscoveryService }> {
+    return {
+      AdmissionDiscoveryService: {
+        getAdmissionCredential: async (
+          request: GetAdmissionCredentialRequest,
+        ): Promise<GetAdmissionCredentialResponse> => {
+          const memberInfo = this._space.spaceState.members.get(request.memberKey);
+          if (!memberInfo?.credential) {
+            throw new ProtocolError({ message: 'Space member not found.', context: { ...request } });
+          }
+          return { admissionCredential: memberInfo.credential };
+        },
+      },
+    };
+  }
+}

package/src/packlets/space/auth.ts

@@ -0,0 +1,92 @@
+//
+// Copyright 2019 DXOS.org
+//
+
+import { runInContext, scheduleTask } from '@dxos/async';
+import { Context } from '@dxos/context';
+import { randomBytes } from '@dxos/crypto';
+import { invariant } from '@dxos/invariant';
+import { log } from '@dxos/log';
+import { schema } from '@dxos/protocols/proto';
+import { type AuthService } from '@dxos/protocols/proto/dxos/mesh/teleport/auth';
+import { type ExtensionContext, RpcExtension } from '@dxos/teleport';
+
+export type AuthProvider = (nonce: Uint8Array) => Promise<Uint8Array | undefined>;
+
+export type AuthVerifier = (nonce: Uint8Array, credential: Uint8Array) => Promise<boolean>;
+
+export type AuthExtensionProps = {
+  provider: AuthProvider;
+  verifier: AuthVerifier;
+  onAuthSuccess: () => void;
+  onAuthFailure: () => void;
+};
+
+export class AuthExtension extends RpcExtension<Services, Services> {
+  private readonly _ctx = new Context({
+    onError: (err) => {
+      log.catch(err);
+    },
+  });
+
+  constructor(private readonly _authProps: AuthExtensionProps) {
+    super({
+      requested: {
+        AuthService: schema.getService('dxos.mesh.teleport.auth.AuthService'),
+      },
+      exposed: {
+        AuthService: schema.getService('dxos.mesh.teleport.auth.AuthService'),
+      },
+      timeout: 60 * 1000, // Long timeout because auth can wait for sync in certain cases.
+    });
+  }
+
+  protected async getHandlers(): Promise<Services> {
+    return {
+      AuthService: {
+        authenticate: async ({ challenge }) => {
+          try {
+            const credential = await this._authProps.provider(challenge);
+            if (!credential) {
+              throw new Error('auth rejected');
+            }
+            return { credential };
+          } catch (err) {
+            log.error('failed to generate auth credentials', err);
+            throw new Error('auth rejected');
+          }
+        },
+      },
+    };
+  }
+
+  override async onOpen(context: ExtensionContext): Promise<void> {
+    await super.onOpen(context);
+    scheduleTask(this._ctx, async () => {
+      try {
+        const challenge = randomBytes(32);
+        const { credential } = await this.rpc.AuthService.authenticate({ challenge });
+        invariant(credential?.length > 0, 'invalid credential');
+        const success = await this._authProps.verifier(challenge, credential);
+        invariant(success, 'credential not verified');
+        runInContext(this._ctx, () => this._authProps.onAuthSuccess());
+      } catch (err) {
+        log('auth failed', err);
+        this.close();
+        this._authProps.onAuthFailure();
+      }
+    });
+  }
+
+  override async onClose(): Promise<void> {
+    await this._ctx.dispose();
+    await super.onClose();
+  }
+
+  override async onAbort(): Promise<void> {
+    await this._ctx.dispose();
+    await super.onAbort();
+  }
+}
+
+type Services = { AuthService: AuthService };