@dxos/halo-adapter-client 0.0.0

package/moon.yml

@@ -0,0 +1,11 @@
+layer: library
+language: typescript
+tags:
+  - ts-build
+  - pack
+tasks:
+  compile:
+    args:
+      - '--entryPoint=src/index.ts'
+      - '--injectGlobals'
+      - '--platform=neutral'

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@dxos/halo-adapter-client",
+  "version": "0.0.0",
+  "description": "Implements the @dxos/halo services over a @dxos/client instance.",
+  "homepage": "https://github.com/dxos/dxos/tree/main/packages/core/halo/halo-adapter-client#readme",
+  "bugs": "https://github.com/dxos/dxos/issues",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dxos/dxos"
+  },
+  "license": "FSL-1.1-Apache-2.0",
+  "author": "info@dxos.org",
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./dist/types/src/index.d.ts",
+      "default": "./dist/lib/neutral/index.mjs"
+    }
+  },
+  "types": "dist/types/src/index.d.ts",
+  "dependencies": {
+    "effect": "3.21.4",
+    "@dxos/async": "0.10.0",
+    "@dxos/halo": "0.0.0",
+    "@dxos/invariant": "0.10.0",
+    "@dxos/client": "0.10.0",
+    "@dxos/client-protocol": "0.10.0",
+    "@dxos/protocols": "0.10.0",
+    "@dxos/keys": "0.10.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/identity.ts

@@ -0,0 +1,143 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as Option from 'effect/Option';
+import * as Stream from 'effect/Stream';
+
+import { type Client } from '@dxos/client';
+import { InvitationEncoder } from '@dxos/client/invitations';
+import { Identity as HaloIdentity, IdentityError } from '@dxos/halo';
+import { IdentityDid } from '@dxos/keys';
+import {
+  type Device as ClientDevice,
+  type Identity as ClientIdentity,
+  DeviceKind,
+} from '@dxos/protocols/proto/dxos/client/services';
+import { type Credential } from '@dxos/protocols/proto/dxos/halo/credentials';
+
+import { makeFlow, streamFromObservable, toShareOptions } from './util';
+
+const toInfo = (identity: ClientIdentity): HaloIdentity.Info => ({
+  did: IdentityDid.make(identity.did),
+  identityKey: identity.identityKey?.toHex(),
+  displayName: identity.profile?.displayName,
+  data: identity.profile?.data,
+});
+
+const toDeviceInfo = (device: ClientDevice): HaloIdentity.DeviceInfo => ({
+  key: device.deviceKey.toHex(),
+  label: device.profile?.label,
+  current: device.kind === DeviceKind.CURRENT,
+});
+
+const toCredential = (credential: Credential): HaloIdentity.Credential => ({
+  id: credential.id?.toHex(),
+  type: credential.subject.assertion['@type'],
+  issuanceDate: credential.issuanceDate,
+});
+
+/**
+ * Builds the {@link HaloIdentity.Service} implementation over a client's `halo` proxy.
+ */
+export const makeIdentityService = (client: Client): Context.Tag.Service<HaloIdentity.Service> => ({
+  identity: streamFromObservable(client.halo.identity).pipe(
+    Stream.map((identity) => (identity ? Option.some(toInfo(identity)) : Option.none())),
+  ),
+
+  getSnapshot: () => {
+    const identity = client.halo.identity.get();
+    return identity ? Option.some(toInfo(identity)) : Option.none();
+  },
+
+  subscribe: (callback) => {
+    const subscription = client.halo.identity.subscribe((identity) =>
+      callback(identity ? Option.some(toInfo(identity)) : Option.none()),
+    );
+    return () => subscription.unsubscribe();
+  },
+
+  create: (options) =>
+    Effect.tryPromise({
+      try: async () =>
+        toInfo(
+          await client.halo.createIdentity(
+            options?.displayName !== undefined ? { displayName: options.displayName } : {},
+            options?.deviceLabel !== undefined ? { label: options.deviceLabel } : undefined,
+          ),
+        ),
+      catch: (error) => new IdentityError({ context: { error } }),
+    }),
+
+  recover: (args) =>
+    Effect.tryPromise({
+      try: async () => toInfo(await client.halo.recoverIdentity(args)),
+      catch: (error) => new IdentityError({ context: { error } }),
+    }),
+
+  updateProfile: (profile) =>
+    Effect.tryPromise({
+      try: async () => toInfo(await client.halo.updateProfile(profile)),
+      catch: (error) => new IdentityError({ context: { error } }),
+    }),
+
+  devices: streamFromObservable(client.halo.devices).pipe(Stream.map((devices) => devices.map(toDeviceInfo))),
+
+  getDevicesSnapshot: () => client.halo.devices.get().map(toDeviceInfo),
+
+  credentials: streamFromObservable(client.halo.credentials).pipe(
+    Stream.map((credentials) => credentials.map(toCredential)),
+  ),
+
+  grantServiceAccess: (options) =>
+    Effect.tryPromise({
+      try: async () => {
+        const identityKey = client.halo.identity.get()?.identityKey;
+        if (!identityKey) {
+          throw new Error('No identity.');
+        }
+        await client.halo.writeCredentials([
+          {
+            issuer: identityKey,
+            issuanceDate: new Date(),
+            subject: {
+              id: identityKey,
+              assertion: {
+                '@type': 'dxos.halo.credentials.ServiceAccess',
+                'serverName': options.serverName,
+                'serverKey': identityKey,
+                identityKey,
+                'capabilities': [...options.capabilities],
+              },
+            },
+          },
+        ]);
+      },
+      catch: (error) => new IdentityError({ context: { error } }),
+    }),
+
+  share: (options) =>
+    Effect.try({
+      try: () => makeFlow(client.halo.share(toShareOptions(options)), 'device'),
+      catch: (error) => new IdentityError({ context: { error } }),
+    }),
+
+  join: (code) =>
+    Effect.try({
+      try: () => makeFlow(client.halo.join(InvitationEncoder.decode(code)), 'device'),
+      catch: (error) => new IdentityError({ context: { error } }),
+    }),
+
+  invitations: streamFromObservable(client.halo.invitations).pipe(
+    Stream.map((invitations) => invitations.map((invitation) => makeFlow(invitation, 'device'))),
+  ),
+});
+
+/**
+ * Layer providing {@link HaloIdentity.Service} backed by the given client.
+ */
+export const layerIdentity = (client: Client): Layer.Layer<HaloIdentity.Service> =>
+  Layer.succeed(HaloIdentity.Service, makeIdentityService(client));

package/src/index.ts

@@ -0,0 +1,23 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Layer from 'effect/Layer';
+
+import { type Client } from '@dxos/client';
+import { type Identity, type Space } from '@dxos/halo';
+
+import { layerIdentity } from './identity';
+import { layerSpace } from './space';
+
+export { layerIdentity, makeIdentityService } from './identity';
+export { layerSpace, makeSpaceService } from './space';
+
+/**
+ * A single layer providing both HALO services ({@link Identity.Service}, {@link Space.Service})
+ * backed by one {@link Client}. This is the composition-root layer that replaces direct
+ * `@dxos/client` access for HALO concerns. Invitation querying lives on these two services;
+ * flow-level verbs need no service.
+ */
+export const layerClient = (client: Client): Layer.Layer<Identity.Service | Space.Service> =>
+  Layer.mergeAll(layerIdentity(client), layerSpace(client));

package/src/space.ts

@@ -0,0 +1,203 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as Option from 'effect/Option';
+import * as Stream from 'effect/Stream';
+
+import { type Client } from '@dxos/client';
+import { type Space as ClientSpace, SpaceState } from '@dxos/client/echo';
+import { Space as HaloSpace, SpaceError } from '@dxos/halo';
+import { IdentityDid, type SpaceId } from '@dxos/keys';
+import { SpaceArchive, type SpaceMember } from '@dxos/protocols/proto/dxos/client/services';
+import { EdgeReplicationSetting } from '@dxos/protocols/proto/dxos/echo/metadata';
+import { SpaceMember as HaloSpaceMember, MembershipPolicy } from '@dxos/protocols/proto/dxos/halo/credentials';
+
+import { fromAccess, isOnline, makeFlow, streamFromObservable, toAccess, toShareOptions } from './util';
+
+const toState = (state: SpaceState): HaloSpace.State => {
+  switch (state) {
+    case SpaceState.SPACE_READY:
+      return 'ready';
+    case SpaceState.SPACE_CLOSED:
+      return 'closed';
+    default:
+      return 'inactive';
+  }
+};
+
+const toSpaceInfo = (space: ClientSpace): HaloSpace.Info => ({
+  id: space.id,
+  name: space.state.get() === SpaceState.SPACE_READY ? space.properties.name : undefined,
+  state: toState(space.state.get()),
+});
+
+const toMembers = (members: readonly SpaceMember[]): HaloSpace.Member[] =>
+  members.flatMap((member) => {
+    const role = toAccess(member.role);
+    if (role === undefined) {
+      // Skip removed members.
+      return [];
+    }
+    return [
+      {
+        did: member.identity?.did !== undefined ? IdentityDid.make(member.identity.did) : undefined,
+        identityKey: member.identity?.identityKey?.toHex(),
+        displayName: member.identity?.profile?.displayName,
+        data: member.identity?.profile?.data,
+        role,
+        online: isOnline(member),
+      },
+    ];
+  });
+
+const toMembershipPolicy = (policy: HaloSpace.MembershipPolicy): MembershipPolicy =>
+  policy === 'locked' ? MembershipPolicy.LOCKED : MembershipPolicy.INVITE;
+
+const toEdgeReplicationSetting = (setting: HaloSpace.EdgeReplication): EdgeReplicationSetting =>
+  setting === 'enabled' ? EdgeReplicationSetting.ENABLED : EdgeReplicationSetting.DISABLED;
+
+const resolveSpace = (client: Client, id: SpaceId): ClientSpace => {
+  const space = client.spaces.get(id);
+  if (!space) {
+    throw new Error(`Space not found: ${id}`);
+  }
+  return space;
+};
+
+// The HALO API addresses members by DID; the legacy proxy needs the identity key, resolved here
+// from the materialized membership.
+const setMemberRole = async (
+  client: Client,
+  id: SpaceId,
+  subject: IdentityDid,
+  newRole: HaloSpaceMember.Role,
+): Promise<void> => {
+  const space = resolveSpace(client, id);
+  const member = space.members.get().find((entry) => entry.identity?.did === subject);
+  if (!member) {
+    throw new Error(`Member not found: ${subject}`);
+  }
+  await space.updateMemberRole({ memberKey: member.identity.identityKey, newRole });
+};
+
+/**
+ * Builds the {@link HaloSpace.Service} implementation over a client's `spaces` proxy.
+ */
+export const makeSpaceService = (client: Client): Context.Tag.Service<HaloSpace.Service> => ({
+  spaces: streamFromObservable(client.spaces).pipe(Stream.map((spaces) => (spaces ?? []).map(toSpaceInfo))),
+
+  get: (id) =>
+    Effect.sync(() => {
+      const space = client.spaces.get(id);
+      return space ? Option.some(toSpaceInfo(space)) : Option.none();
+    }),
+
+  create: (options) =>
+    Effect.tryPromise({
+      try: async () => {
+        const createOptions: { tags?: string[]; membershipPolicy?: MembershipPolicy } = {};
+        if (options?.tags !== undefined) {
+          createOptions.tags = [...options.tags];
+        }
+        if (options?.membershipPolicy !== undefined) {
+          createOptions.membershipPolicy = toMembershipPolicy(options.membershipPolicy);
+        }
+        return toSpaceInfo(
+          await client.spaces.create(options?.name !== undefined ? { name: options.name } : {}, createOptions),
+        );
+      },
+      catch: (error) => new SpaceError({ context: { error } }),
+    }),
+
+  waitReady: (id) =>
+    Effect.tryPromise({
+      try: async () => {
+        await resolveSpace(client, id).waitUntilReady();
+      },
+      catch: (error) => new SpaceError({ context: { error } }),
+    }),
+
+  setEdgeReplication: (id, setting) =>
+    Effect.tryPromise({
+      try: async () => {
+        await resolveSpace(client, id).internal.setEdgeReplicationPreference(toEdgeReplicationSetting(setting));
+      },
+      catch: (error) => new SpaceError({ context: { error } }),
+    }),
+
+  members: (id) => {
+    const space = client.spaces.get(id);
+    return space ? streamFromObservable(space.members).pipe(Stream.map(toMembers)) : Stream.empty;
+  },
+
+  updateMemberRole: (id, subject, role) =>
+    Effect.tryPromise({
+      try: async () => {
+        const newRole = fromAccess(role);
+        if (newRole === undefined) {
+          throw new Error(`No legacy role for access level: ${role}`);
+        }
+        await setMemberRole(client, id, subject, newRole);
+      },
+      catch: (error) => new SpaceError({ context: { error } }),
+    }),
+
+  removeMember: (id, subject) =>
+    Effect.tryPromise({
+      try: () => setMemberRole(client, id, subject, HaloSpaceMember.Role.REMOVED),
+      catch: (error) => new SpaceError({ context: { error } }),
+    }),
+
+  share: (id, options) =>
+    Effect.try({
+      try: () => makeFlow(resolveSpace(client, id).share(toShareOptions(options)), 'space'),
+      catch: (error) => new SpaceError({ context: { error } }),
+    }),
+
+  join: (code) =>
+    Effect.try({
+      try: () => makeFlow(client.spaces.join(code), 'space'),
+      catch: (error) => new SpaceError({ context: { error } }),
+    }),
+
+  invitations: (id) => {
+    const space = client.spaces.get(id);
+    return space
+      ? streamFromObservable(space.invitations).pipe(
+          Stream.map((invitations) => invitations.map((invitation) => makeFlow(invitation, 'space'))),
+        )
+      : Stream.empty;
+  },
+
+  export: (id) =>
+    Effect.tryPromise({
+      try: async () => {
+        const archive = await resolveSpace(client, id).internal.export();
+        return { filename: archive.filename, contents: archive.contents };
+      },
+      catch: (error) => new SpaceError({ context: { error } }),
+    }),
+
+  import: (archive, options) =>
+    Effect.tryPromise({
+      try: async () => {
+        const format = archive.filename.endsWith('.json') ? SpaceArchive.Format.JSON : SpaceArchive.Format.BINARY;
+        const space = await client.spaces.import(
+          { filename: archive.filename, contents: archive.contents, format },
+          options?.tags !== undefined ? { tags: [...options.tags] } : undefined,
+        );
+        return toSpaceInfo(space);
+      },
+      catch: (error) => new SpaceError({ context: { error } }),
+    }),
+});
+
+/**
+ * Layer providing {@link HaloSpace.Service} backed by the given client.
+ */
+export const layerSpace = (client: Client): Layer.Layer<HaloSpace.Service> =>
+  Layer.succeed(HaloSpace.Service, makeSpaceService(client));

package/src/util.ts

@@ -0,0 +1,183 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import * as Stream from 'effect/Stream';
+
+import { type MulticastObservable } from '@dxos/async';
+import {
+  AuthenticatingInvitationObservable,
+  type CancellableInvitationObservable,
+  Invitation as ClientInvitation,
+  InvitationEncoder,
+} from '@dxos/client/invitations';
+import { Invitation as HaloInvitation, Space as HaloSpace, InvitationError } from '@dxos/halo';
+import { SpaceMember } from '@dxos/protocols/proto/dxos/client/services';
+import { SpaceMember as HaloSpaceMember } from '@dxos/protocols/proto/dxos/halo/credentials';
+
+/**
+ * Bridges a {@link MulticastObservable} into an Effect {@link Stream}. The current value is
+ * emitted on subscription (matching the observable's semantics); the stream runs until the
+ * consumer stops or the observable errors.
+ */
+export const streamFromObservable = <T>(observable: MulticastObservable<T>): Stream.Stream<T> =>
+  Stream.async<T, Error>((emit) => {
+    const subscription = observable.subscribe(
+      (value: T) => void emit.single(value),
+      (err: Error) => void emit.fail(err),
+    );
+    return Effect.sync(() => subscription.unsubscribe());
+  }).pipe(Stream.orDie);
+
+const TERMINAL_STATES: ReadonlySet<ClientInvitation.State> = new Set([
+  ClientInvitation.State.SUCCESS,
+  ClientInvitation.State.CANCELLED,
+  ClientInvitation.State.TIMEOUT,
+  ClientInvitation.State.ERROR,
+  ClientInvitation.State.EXPIRED,
+]);
+
+const toEvent = (invitation: ClientInvitation): HaloInvitation.Event | undefined => {
+  switch (invitation.state) {
+    case ClientInvitation.State.CONNECTING:
+      return { _tag: 'connecting' };
+    case ClientInvitation.State.CONNECTED:
+      return { _tag: 'connected' };
+    case ClientInvitation.State.READY_FOR_AUTHENTICATION:
+      return { _tag: 'readyForAuthentication', authCode: invitation.authCode };
+    case ClientInvitation.State.AUTHENTICATING:
+      return { _tag: 'authenticating' };
+    case ClientInvitation.State.SUCCESS:
+      return { _tag: 'success', result: {} };
+    case ClientInvitation.State.CANCELLED:
+      return { _tag: 'cancelled' };
+    case ClientInvitation.State.TIMEOUT:
+    case ClientInvitation.State.ERROR:
+    case ClientInvitation.State.EXPIRED:
+      return { _tag: 'error', message: `Invitation ${ClientInvitation.State[invitation.state]}` };
+    default:
+      // INIT and any unmodeled state — not surfaced.
+      return undefined;
+  }
+};
+
+/**
+ * Maps an invitation observable's state transitions to the {@link HaloInvitation.Event} stream,
+ * completing after a terminal event.
+ */
+export const invitationEvents = (observable: CancellableInvitationObservable): Stream.Stream<HaloInvitation.Event> =>
+  Stream.async<HaloInvitation.Event>((emit) => {
+    const subscription = observable.subscribe(
+      (invitation: ClientInvitation) => {
+        const event = toEvent(invitation);
+        if (event) {
+          void emit.single(event);
+          if (TERMINAL_STATES.has(invitation.state)) {
+            void emit.end();
+          }
+        }
+      },
+      (err: Error) => {
+        void emit.single({ _tag: 'error', message: err.message });
+        void emit.end();
+      },
+    );
+    return Effect.sync(() => subscription.unsubscribe());
+  });
+
+/**
+ * Wraps a client invitation observable as a {@link HaloInvitation.Flow}.
+ */
+export const makeFlow = (
+  observable: CancellableInvitationObservable,
+  kind: HaloInvitation.Kind,
+): HaloInvitation.Flow => ({
+  id: observable.get().invitationId,
+  kind,
+  events: invitationEvents(observable),
+  authenticate: (code: string) =>
+    observable instanceof AuthenticatingInvitationObservable
+      ? Effect.tryPromise({
+          try: () => observable.authenticate(code),
+          catch: (error) => new InvitationError({ context: { error } }),
+        })
+      : Effect.fail(new InvitationError({ context: { reason: 'flow is not awaiting authentication' } })),
+  cancel: () => Effect.promise(() => observable.cancel()),
+  code: Effect.sync(() => InvitationEncoder.encode(observable.get())),
+});
+
+/**
+ * Maps {@link HaloInvitation.ShareOptions} to the client invitation options. Defaults to a
+ * no-auth interactive invitation so programmatic flows complete without an auth code.
+ */
+export const toShareOptions = (options?: HaloInvitation.ShareOptions): Partial<ClientInvitation> => ({
+  authMethod: toAuthMethod(options?.authMethod),
+  type: toType(options?.type),
+  ...(options?.multiUse !== undefined ? { multiUse: options.multiUse } : {}),
+  ...(options?.target !== undefined ? { target: options.target } : {}),
+});
+
+const toAuthMethod = (method?: HaloInvitation.AuthMethod): ClientInvitation.AuthMethod => {
+  switch (method) {
+    case 'shared-secret':
+      return ClientInvitation.AuthMethod.SHARED_SECRET;
+    case 'known-public-key':
+      return ClientInvitation.AuthMethod.KNOWN_PUBLIC_KEY;
+    case 'none':
+    default:
+      return ClientInvitation.AuthMethod.NONE;
+  }
+};
+
+const toType = (type?: HaloInvitation.Type): ClientInvitation.Type => {
+  switch (type) {
+    case 'delegated':
+      return ClientInvitation.Type.DELEGATED;
+    case 'multiuse':
+      return ClientInvitation.Type.MULTIUSE;
+    case 'interactive':
+    default:
+      return ClientInvitation.Type.INTERACTIVE;
+  }
+};
+
+/**
+ * Maps a legacy space-member role to the Keyhive-aligned {@link HaloSpace.Access} level.
+ * Returns `undefined` for `REMOVED` (not a current member).
+ */
+export const toAccess = (role: HaloSpaceMember.Role): HaloSpace.Access | undefined => {
+  switch (role) {
+    case HaloSpaceMember.Role.OWNER:
+    case HaloSpaceMember.Role.ADMIN:
+      return 'admin';
+    case HaloSpaceMember.Role.EDITOR:
+      return 'edit';
+    case HaloSpaceMember.Role.READER:
+      return 'read';
+    default:
+      return undefined;
+  }
+};
+
+/**
+ * Maps a Keyhive-aligned {@link HaloSpace.Access} level to a legacy space-member role.
+ * Returns `undefined` for `pull` (no legacy equivalent — reject at the call site).
+ */
+export const fromAccess = (access: HaloSpace.Access): HaloSpaceMember.Role | undefined => {
+  switch (access) {
+    case 'admin':
+      return HaloSpaceMember.Role.ADMIN;
+    case 'edit':
+      return HaloSpaceMember.Role.EDITOR;
+    case 'read':
+      return HaloSpaceMember.Role.READER;
+    default:
+      return undefined;
+  }
+};
+
+/**
+ * Whether a member is currently online.
+ */
+export const isOnline = (member: SpaceMember): boolean => member.presence === SpaceMember.PresenceState.ONLINE;

package/tsconfig.json

@@ -0,0 +1,34 @@
+{
+  "extends": "../../../../tsconfig.base.json",
+  "compilerOptions": {
+    "types": [
+      "node"
+    ]
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../common/async"
+    },
+    {
+      "path": "../../../common/invariant"
+    },
+    {
+      "path": "../../../common/keys"
+    },
+    {
+      "path": "../../../sdk/client"
+    },
+    {
+      "path": "../../../sdk/client-protocol"
+    },
+    {
+      "path": "../../protocols"
+    },
+    {
+      "path": "../halo"
+    }
+  ]
+}