@dxos/plugin-client 0.8.4-main.fd6878d → 0.8.4-staging.60fe92afc8

package/src/index.ts

@@ -2,8 +2,6 @@
 // Copyright 2023 DXOS.org
 //
 
-export * from './ClientPlugin';
-export * from './meta';
-
-export { ClientCapabilities } from './capabilities';
-export { ClientEvents } from './events';
+export { meta } from './meta';
+export * from './types';
+export { ClientOperation } from './operations';

package/src/meta.ts

@@ -2,11 +2,17 @@
 // Copyright 2023 DXOS.org
 //
 
-import { type PluginMeta } from '@dxos/app-framework';
+import { Plugin } from '@dxos/app-framework';
+import { DXN } from '@dxos/keys';
+import { trim } from '@dxos/util';
 
-export const CLIENT_PLUGIN = 'dxos.org/plugin/client';
-
-export const meta: PluginMeta = {
-  id: CLIENT_PLUGIN,
+export const meta = Plugin.makeMeta({
+  key: DXN.make('org.dxos.plugin.client'),
   name: 'Client',
-};
+  author: 'DXOS',
+  description: trim`
+    Core client connectivity and peer-to-peer networking infrastructure.
+    Manages identity, authentication, and real-time synchronization across devices.
+  `,
+  tags: ['system'],
+});

package/src/operations/create-agent.ts

@@ -0,0 +1,26 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Capability } from '@dxos/app-framework';
+import { Operation } from '@dxos/compute';
+import { invariant } from '@dxos/invariant';
+
+import { ClientCapabilities } from '../types';
+import { CreateAgent } from './definitions';
+
+const handler: Operation.WithHandler<typeof CreateAgent> = CreateAgent.pipe(
+  Operation.withHandler(
+    Effect.fnUntraced(function* () {
+      const client = yield* Capability.get(ClientCapabilities.Client);
+      invariant(client.services.services.EdgeAgentService, 'Missing EdgeAgentService');
+      yield* Effect.promise(() =>
+        client.services.services.EdgeAgentService!.createAgent(undefined, { timeout: 10_000 }),
+      );
+    }),
+  ),
+);
+
+export default handler;

package/src/operations/create-identity.ts

@@ -0,0 +1,37 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Capabilities, Capability } from '@dxos/app-framework';
+import { Operation } from '@dxos/compute';
+import { createIdFromSpaceKey } from '@dxos/echo-protocol';
+import { EffectEx } from '@dxos/effect';
+import { IdentityDid } from '@dxos/keys';
+import { ObservabilityOperation } from '@dxos/plugin-observability';
+
+import { ClientEvents } from '../types';
+import { ClientCapabilities } from '../types';
+import { CreateIdentity } from './definitions';
+
+const handler: Operation.WithHandler<typeof CreateIdentity> = CreateIdentity.pipe(
+  Operation.withHandler(
+    Effect.fnUntraced(function* (profile) {
+      const manager = yield* Capability.get(Capabilities.PluginManager);
+      const client = yield* Capability.get(ClientCapabilities.Client);
+      const data = yield* Effect.promise(() => client.halo.createIdentity(profile));
+      const spaceKey = data.spaceKey;
+      const spaceId = spaceKey ? yield* Effect.promise(() => createIdFromSpaceKey(spaceKey)) : undefined;
+      yield* Effect.promise(() => EffectEx.runAndForwardErrors(manager.activate(ClientEvents.IdentityCreated)));
+      yield* Operation.schedule(ObservabilityOperation.SendEvent, { name: 'identity.create' });
+      return {
+        identityDid: IdentityDid.make(data.did),
+        ...(spaceId !== undefined && { spaceId }),
+        ...(data.profile !== undefined && { profile: data.profile }),
+      };
+    }),
+  ),
+);
+
+export default handler;

package/src/operations/create-passkey.ts

@@ -0,0 +1,88 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import * as Match from 'effect/Match';
+
+import { Capability } from '@dxos/app-framework';
+import { supportsNativePasskeys, createNativePasskey, extractPublicKeyFromAttestation } from '@dxos/app-toolkit';
+import { PublicKey } from '@dxos/client';
+import { Operation } from '@dxos/compute';
+import { invariant } from '@dxos/invariant';
+
+import { ClientCapabilities } from '../types';
+import { CreatePasskey } from './definitions';
+
+const handler: Operation.WithHandler<typeof CreatePasskey> = CreatePasskey.pipe(
+  Operation.withHandler(
+    Effect.fnUntraced(function* () {
+      const client = yield* Capability.get(ClientCapabilities.Client);
+      const identity = client.halo.identity.get();
+      invariant(identity, 'Identity not available');
+
+      const lookupKey = PublicKey.random();
+
+      const { recoveryKey, algorithm } = yield* Match.value(supportsNativePasskeys()).pipe(
+        Match.when(true, () =>
+          Effect.gen(function* () {
+            const result = yield* Effect.promise(() =>
+              createNativePasskey({
+                username: identity.did,
+                userId: lookupKey.asUint8Array(),
+              }),
+            );
+            const { publicKey, algorithm: alg } = extractPublicKeyFromAttestation(result.attestation_object);
+            return {
+              recoveryKey: PublicKey.from(publicKey),
+              algorithm: alg === -7 ? 'ES256' : 'ED25519',
+            };
+          }),
+        ),
+        Match.orElse(() =>
+          Effect.gen(function* () {
+            const credential = yield* Effect.promise(() =>
+              navigator.credentials.create({
+                publicKey: {
+                  challenge: new Uint8Array(),
+                  rp: { id: location.hostname, name: 'Composer' },
+                  user: {
+                    id: lookupKey.asUint8Array() as Uint8Array<ArrayBuffer>,
+                    name: identity.did,
+                    displayName: identity.profile?.displayName ?? '',
+                  },
+                  pubKeyCredParams: [
+                    { type: 'public-key', alg: -8 },
+                    { type: 'public-key', alg: -7 },
+                  ],
+                  authenticatorSelection: {
+                    residentKey: 'required',
+                    requireResidentKey: true,
+                  },
+                },
+              }),
+            );
+            invariant(credential, 'Credential not available');
+            return {
+              recoveryKey: PublicKey.from(new Uint8Array((credential as any).response.getPublicKey())),
+              algorithm: (credential as any).response.getPublicKeyAlgorithm() === -7 ? 'ES256' : 'ED25519',
+            };
+          }),
+        ),
+      );
+
+      invariant(client.services.services.IdentityService, 'IdentityService not available');
+      yield* Effect.promise(() =>
+        client.services.services.IdentityService!.createRecoveryCredential({
+          data: {
+            recoveryKey,
+            algorithm,
+            lookupKey,
+          },
+        }),
+      );
+    }),
+  ),
+);
+
+export default handler;

package/src/operations/create-recovery-code.ts

@@ -0,0 +1,34 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Capability } from '@dxos/app-framework';
+import { LayoutOperation } from '@dxos/app-toolkit';
+import { Operation } from '@dxos/compute';
+import { invariant } from '@dxos/invariant';
+
+import { RECOVERY_CODE_DIALOG } from '../constants';
+import { ClientCapabilities } from '../types';
+import { CreateRecoveryCode } from './definitions';
+
+const handler: Operation.WithHandler<typeof CreateRecoveryCode> = CreateRecoveryCode.pipe(
+  Operation.withHandler(
+    Effect.fnUntraced(function* () {
+      const client = yield* Capability.get(ClientCapabilities.Client);
+      invariant(client.services.services.IdentityService, 'IdentityService not available');
+      const { recoveryCode } = yield* Effect.promise(() =>
+        client.services.services.IdentityService!.createRecoveryCredential({}),
+      );
+      yield* Operation.invoke(LayoutOperation.UpdateDialog, {
+        subject: RECOVERY_CODE_DIALOG,
+        blockAlign: 'start',
+        type: 'alert',
+        props: { code: recoveryCode },
+      });
+    }),
+  ),
+);
+
+export default handler;

package/src/operations/definitions.ts

@@ -0,0 +1,115 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+import { Capability } from '@dxos/app-framework';
+import { Operation } from '@dxos/compute';
+import { DXN, IdentityDid, SpaceId } from '@dxos/keys';
+
+import { meta } from '#meta';
+
+const makeKey = (name: string) => DXN.make(`${meta.id}.operation.${name}`);
+
+const IdentitySchema = Schema.Struct({
+  identityDid: IdentityDid,
+  spaceId: Schema.optional(SpaceId),
+  profile: Schema.optional(
+    Schema.Struct({
+      displayName: Schema.optional(Schema.String),
+      avatarCid: Schema.optional(Schema.String),
+      data: Schema.optional(Schema.Record({ key: Schema.String, value: Schema.Any })),
+    }),
+  ),
+});
+
+const ProfileSchema = Schema.Struct({
+  displayName: Schema.optional(Schema.String),
+  avatarCid: Schema.optional(Schema.String),
+  data: Schema.optional(Schema.Record({ key: Schema.String, value: Schema.Any })),
+});
+
+export const CreateIdentity = Operation.make({
+  meta: { key: makeKey('createIdentity'), name: 'Create Identity', icon: 'ph--user--regular' },
+  services: [Capability.Service],
+  input: ProfileSchema,
+  output: IdentitySchema,
+});
+
+export const JoinIdentity = Operation.make({
+  meta: { key: makeKey('joinIdentity'), name: 'Join Identity', icon: 'ph--sign-in--regular' },
+  services: [Capability.Service],
+  input: Schema.Struct({
+    invitationCode: Schema.optional(Schema.String),
+  }),
+  output: Schema.Void,
+});
+
+export const ShareIdentity = Operation.make({
+  meta: {
+    key: makeKey('shareIdentity'),
+    name: 'Share Identity',
+    icon: 'ph--share-network--regular',
+  },
+  services: [Capability.Service],
+  input: Schema.Void,
+  output: Schema.Void,
+});
+
+export const RecoverIdentity = Operation.make({
+  meta: { key: makeKey('recoverIdentity'), name: 'Recover Identity', icon: 'ph--key--regular' },
+  services: [Capability.Service],
+  input: Schema.Void,
+  output: Schema.Void,
+});
+
+export const ResetStorage = Operation.make({
+  meta: { key: makeKey('resetStorage'), name: 'Reset Storage', icon: 'ph--warning--regular' },
+  services: [Capability.Service],
+  input: Schema.Struct({
+    mode: Schema.optional(Schema.String),
+  }),
+  output: Schema.Void,
+});
+
+export const CreateAgent = Operation.make({
+  meta: { key: makeKey('createAgent'), name: 'Create Agent', icon: 'ph--brain--regular' },
+  services: [Capability.Service],
+  input: Schema.Void,
+  output: Schema.Void,
+});
+
+export const CreateRecoveryCode = Operation.make({
+  meta: {
+    key: makeKey('createRecoveryCode'),
+    name: 'Create Recovery Code',
+    icon: 'ph--key--regular',
+  },
+  services: [Capability.Service],
+  input: Schema.Void,
+  output: Schema.Void,
+});
+
+export const CreatePasskey = Operation.make({
+  meta: { key: makeKey('createPasskey'), name: 'Create Passkey', icon: 'ph--key--regular' },
+  services: [Capability.Service],
+  input: Schema.Void,
+  output: Schema.Void,
+});
+
+export const RedeemPasskey = Operation.make({
+  meta: { key: makeKey('redeemPasskey'), name: 'Redeem Passkey', icon: 'ph--key--regular' },
+  services: [Capability.Service],
+  input: Schema.Void,
+  output: Schema.Void,
+});
+
+export const RedeemToken = Operation.make({
+  meta: { key: makeKey('redeemToken'), name: 'Redeem Token', icon: 'ph--lock--regular' },
+  services: [Capability.Service],
+  input: Schema.Struct({
+    token: Schema.String,
+  }),
+  output: Schema.Void,
+});

package/src/operations/index.ts

@@ -0,0 +1,20 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { OperationHandlerSet } from '@dxos/compute';
+
+export * as ClientOperation from './definitions';
+
+export const ClientOperationHandlerSet = OperationHandlerSet.lazy(
+  () => import('./create-agent'),
+  () => import('./create-identity'),
+  () => import('./create-passkey'),
+  () => import('./create-recovery-code'),
+  () => import('./join-identity'),
+  () => import('./recover-identity'),
+  () => import('./redeem-passkey'),
+  () => import('./redeem-token'),
+  () => import('./reset-storage'),
+  () => import('./share-identity'),
+);

package/src/operations/join-identity.ts

@@ -0,0 +1,28 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { LayoutOperation } from '@dxos/app-toolkit';
+import { Operation } from '@dxos/compute';
+
+import { JOIN_DIALOG } from '../constants';
+import { JoinIdentity } from './definitions';
+
+const handler: Operation.WithHandler<typeof JoinIdentity> = JoinIdentity.pipe(
+  Operation.withHandler(
+    Effect.fnUntraced(function* (data) {
+      yield* Operation.invoke(LayoutOperation.UpdateDialog, {
+        subject: JOIN_DIALOG,
+        blockAlign: 'start',
+        props: {
+          initialInvitationCode: data.invitationCode,
+          initialDisposition: 'accept-halo-invitation',
+        },
+      });
+    }),
+  ),
+);
+
+export default handler;

package/src/operations/recover-identity.ts

@@ -0,0 +1,28 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { LayoutOperation } from '@dxos/app-toolkit';
+import { Operation } from '@dxos/compute';
+import type { JoinPanelProps } from '@dxos/shell/react';
+
+import { JOIN_DIALOG } from '../constants';
+import { RecoverIdentity } from './definitions';
+
+const handler: Operation.WithHandler<typeof RecoverIdentity> = RecoverIdentity.pipe(
+  Operation.withHandler(
+    Effect.fnUntraced(function* () {
+      yield* Operation.invoke(LayoutOperation.UpdateDialog, {
+        subject: JOIN_DIALOG,
+        blockAlign: 'start',
+        props: {
+          initialDisposition: 'recover-identity',
+        } satisfies Partial<JoinPanelProps>,
+      });
+    }),
+  ),
+);
+
+export default handler;

package/src/operations/redeem-passkey.ts

@@ -0,0 +1,85 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import * as Match from 'effect/Match';
+
+import { Capability } from '@dxos/app-framework';
+import { decodeUrlSafeBase64, supportsNativePasskeys, loginNativePasskey } from '@dxos/app-toolkit';
+import { PublicKey } from '@dxos/client';
+import { Operation } from '@dxos/compute';
+import { invariant } from '@dxos/invariant';
+
+import { ClientCapabilities } from '../types';
+import { RedeemPasskey } from './definitions';
+
+const handler: Operation.WithHandler<typeof RedeemPasskey> = RedeemPasskey.pipe(
+  Operation.withHandler(
+    Effect.fnUntraced(function* () {
+      const client = yield* Capability.get(ClientCapabilities.Client);
+      invariant(client.services.services.IdentityService, 'IdentityService not available');
+      const { deviceKey, controlFeedKey, challenge } = yield* Effect.promise(() =>
+        client.services.services.IdentityService!.requestRecoveryChallenge(),
+      );
+
+      const { lookupKey, signature, clientDataJson, authenticatorData } = yield* Match.value(
+        supportsNativePasskeys(),
+      ).pipe(
+        Match.when(true, () =>
+          Effect.gen(function* () {
+            const result = yield* Effect.promise(() =>
+              loginNativePasskey({ challenge: Uint8Array.from(Buffer.from(challenge, 'base64')) }),
+            );
+            invariant(result, 'Native passkey login returned no result');
+            return {
+              lookupKey: PublicKey.from(decodeUrlSafeBase64(result.user_handle)),
+              signature: Buffer.from(decodeUrlSafeBase64(result.signature)),
+              clientDataJson: Buffer.from(decodeUrlSafeBase64(result.client_data_json)),
+              authenticatorData: Buffer.from(decodeUrlSafeBase64(result.authenticator_data)),
+            };
+          }),
+        ),
+        Match.orElse(() =>
+          Effect.gen(function* () {
+            const credential = yield* Effect.promise(() =>
+              navigator.credentials.get({
+                publicKey: {
+                  challenge: Buffer.from(challenge, 'base64'),
+                  rpId: location.hostname,
+                  userVerification: 'required',
+                },
+              }),
+            );
+            return {
+              lookupKey: PublicKey.from(new Uint8Array((credential as any).response.userHandle)),
+              signature: Buffer.from((credential as any).response.signature),
+              clientDataJson: Buffer.from((credential as any).response.clientDataJSON),
+              authenticatorData: Buffer.from((credential as any).response.authenticatorData),
+            };
+          }),
+        ),
+      );
+
+      yield* Effect.promise(() =>
+        client.services.services.IdentityService!.recoverIdentity(
+          {
+            external: {
+              lookupKey,
+              deviceKey,
+              controlFeedKey,
+              signature,
+              clientDataJson,
+              authenticatorData,
+            },
+          },
+          { timeout: RECOVER_IDENTITY_RPC_TIMEOUT },
+        ),
+      );
+    }),
+  ),
+);
+
+export default handler;
+
+const RECOVER_IDENTITY_RPC_TIMEOUT = 20_000;

package/src/operations/redeem-token.ts

@@ -0,0 +1,31 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Capability } from '@dxos/app-framework';
+import { Operation } from '@dxos/compute';
+import { invariant } from '@dxos/invariant';
+
+import { ClientCapabilities } from '../types';
+import { RedeemToken } from './definitions';
+
+const handler: Operation.WithHandler<typeof RedeemToken> = RedeemToken.pipe(
+  Operation.withHandler(
+    Effect.fnUntraced(function* (data) {
+      const client = yield* Capability.get(ClientCapabilities.Client);
+      invariant(client.services.services.IdentityService, 'IdentityService not available');
+      yield* Effect.promise(() =>
+        client.services.services.IdentityService!.recoverIdentity(
+          { token: data.token },
+          { timeout: RECOVER_IDENTITY_RPC_TIMEOUT },
+        ),
+      );
+    }),
+  ),
+);
+
+export default handler;
+
+const RECOVER_IDENTITY_RPC_TIMEOUT = 20_000;

package/src/operations/reset-storage.ts

@@ -0,0 +1,27 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { LayoutOperation } from '@dxos/app-toolkit';
+import { Operation } from '@dxos/compute';
+
+import { RESET_DIALOG } from '../constants';
+import { ResetStorage } from './definitions';
+
+const handler: Operation.WithHandler<typeof ResetStorage> = ResetStorage.pipe(
+  Operation.withHandler(
+    Effect.fnUntraced(function* (data) {
+      yield* Operation.invoke(LayoutOperation.UpdateDialog, {
+        subject: RESET_DIALOG,
+        blockAlign: 'start',
+        props: {
+          mode: data.mode ?? 'reset-storage',
+        },
+      });
+    }),
+  ),
+);
+
+export default handler;

package/src/operations/share-identity.ts

@@ -0,0 +1,26 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { LayoutOperation, getSpacePath } from '@dxos/app-toolkit';
+import { Operation } from '@dxos/compute';
+import { ObservabilityOperation } from '@dxos/plugin-observability';
+
+import { Account } from '../types';
+import { ShareIdentity } from './definitions';
+
+const handler: Operation.WithHandler<typeof ShareIdentity> = ShareIdentity.pipe(
+  Operation.withHandler(
+    Effect.fnUntraced(function* () {
+      yield* Operation.invoke(LayoutOperation.SwitchWorkspace, { subject: getSpacePath(Account.id) });
+      yield* Operation.invoke(LayoutOperation.Open, {
+        subject: [`${getSpacePath(Account.id)}/${Account.Profile}`],
+      });
+      yield* Operation.schedule(ObservabilityOperation.SendEvent, { name: 'identity.share' });
+    }),
+  ),
+);
+
+export default handler;

package/src/plugin.ts

@@ -0,0 +1,11 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { Plugin } from '@dxos/app-framework';
+
+import { meta } from './meta';
+
+export const ClientPlugin = Plugin.lazy(meta, () => import('#plugin'));
+
+export { ClientOperationHandlerSet } from './operations';

package/src/state/account-cache.ts

@@ -0,0 +1,33 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+const AccountCacheValue = Schema.Struct({
+  identityDid: Schema.String,
+  email: Schema.String,
+  emailVerified: Schema.Boolean,
+  /** ISO timestamp. */
+  createdAt: Schema.String,
+  invitationsRemaining: Schema.Number,
+});
+export type AccountCacheValue = Schema.Schema.Type<typeof AccountCacheValue>;
+
+const AccountCacheInvitation = Schema.Struct({
+  code: Schema.String,
+  /** ISO timestamp. */
+  createdAt: Schema.String,
+  redeemedByIdentityDid: Schema.optional(Schema.String),
+  /** ISO timestamp. */
+  redeemedAt: Schema.optional(Schema.String),
+});
+export type AccountCacheInvitation = Schema.Schema.Type<typeof AccountCacheInvitation>;
+
+export const AccountCache = Schema.Struct({
+  account: Schema.optional(AccountCacheValue),
+  invitations: Schema.optional(Schema.Array(AccountCacheInvitation)),
+  /** Epoch ms when the cache was last refreshed. */
+  fetchedAt: Schema.optional(Schema.Number),
+});
+export type AccountCache = Schema.Schema.Type<typeof AccountCache>;

package/src/state/use-hub-http.ts

@@ -0,0 +1,32 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { useEffect } from 'react';
+
+import { useCapabilities } from '@dxos/app-framework/ui';
+import { createEdgeIdentity } from '@dxos/client/edge';
+import { type HubHttpClient } from '@dxos/edge-client';
+import { useClient } from '@dxos/react-client';
+import { useIdentity } from '@dxos/react-client/halo';
+
+import { ClientCapabilities } from '#types';
+
+/**
+ * Returns the shared `HubHttpClient` singleton for hub-service API calls.
+ * Updates the VP-auth identity whenever the signed-in user changes.
+ * Returns `undefined` when the hub URL is unconfigured (no HubHttpClient capability).
+ */
+export const useHubHttpClient = (): HubHttpClient | undefined => {
+  const client = useClient();
+  const identity = useIdentity();
+  const [hubHttpClient] = useCapabilities(ClientCapabilities.HubHttpClient);
+
+  useEffect(() => {
+    if (hubHttpClient && identity) {
+      hubHttpClient.setIdentity(createEdgeIdentity(client));
+    }
+  }, [client, identity, hubHttpClient]);
+
+  return hubHttpClient ?? undefined;
+};

package/src/testing/index.ts

@@ -0,0 +1,6 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from '#plugin';
+export { initializeIdentity } from './initializeIdentity';