@dxos/halo 0.0.0

package/src/Identity.ts

@@ -0,0 +1,195 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// @import-as-namespace
+
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import * as Option from 'effect/Option';
+import * as Schema from 'effect/Schema';
+import * as Stream from 'effect/Stream';
+
+import { IdentityDid } from '@dxos/keys';
+
+import { type IdentityError } from './errors';
+import * as Invitation from './Invitation';
+
+/**
+ * Device kind (platform / host class). Replaces the legacy protobuf `DeviceType` enum;
+ * `agent`/`agent-managed` denote EDGE- or Hub-hosted agent devices.
+ */
+export const DeviceKind = Schema.Literal('unknown', 'browser', 'native', 'mobile', 'agent', 'agent-managed');
+export type DeviceKind = typeof DeviceKind.Type;
+
+/**
+ * Public view of the local identity. Keyed by the DID; `identityKey` (hex) is retained for
+ * consumers that seed deterministic UI (avatar/hue) or address the legacy credential key.
+ * `data` carries arbitrary profile metadata (e.g. avatar emoji, hue).
+ */
+export const Info = Schema.Struct({
+  did: IdentityDid,
+  /** Hex-encoded identity (credential) key, when known. */
+  identityKey: Schema.optional(Schema.String),
+  displayName: Schema.optional(Schema.String),
+  /** Arbitrary profile metadata. */
+  data: Schema.optional(Schema.Record({ key: Schema.String, value: Schema.Any })),
+});
+export type Info = typeof Info.Type;
+
+/**
+ * Public view of a device belonging to the local identity. Replaces the legacy `Device` proxy
+ * type (`deviceKey` → `key`).
+ */
+export const DeviceInfo = Schema.Struct({
+  /** Hex-encoded device key. */
+  key: Schema.String,
+  kind: Schema.optional(DeviceKind),
+  label: Schema.optional(Schema.String),
+  /** Whether this device is the local (current) device. */
+  current: Schema.Boolean,
+});
+export type DeviceInfo = typeof DeviceInfo.Type;
+
+/**
+ * Public view of a HALO credential. Replaces direct consumption of the protobuf `Credential`:
+ * `type` is the subject assertion's `@type`, `id` its hex-encoded credential id.
+ */
+export const Credential = Schema.Struct({
+  /** Hex-encoded credential id, when assigned. */
+  id: Schema.optional(Schema.String),
+  /** The subject assertion's `@type` (e.g. `dxos.halo.credentials.IdentityRecovery`). */
+  type: Schema.String,
+  issuanceDate: Schema.optional(Schema.DateFromSelf),
+});
+export type Credential = typeof Credential.Type;
+
+/**
+ * Options for a self-issued `ServiceAccess` credential granting the identity access to an
+ * EDGE/Hub service.
+ */
+export type ServiceAccessOptions = {
+  /** Target server name (e.g. `hub.dxos.network`). */
+  readonly serverName: string;
+  /** Capabilities to grant (e.g. `['composer:beta']`). */
+  readonly capabilities: readonly string[];
+};
+
+/**
+ * Recovery credential presented to re-admit a device to an existing identity.
+ */
+export type RecoverArgs =
+  | { readonly recoveryCode: string }
+  | { readonly token: string }
+  | { readonly recoveryProof: string };
+
+/**
+ * Identity and device management, plus device invitations. `share`/`join` construct
+ * {@link Invitation.Flow}s driven through the {@link Invitation} flow verbs; `invitations`
+ * observes the active (host-created) device-invitation flows.
+ */
+export class Service extends Context.Tag('@dxos/halo/Identity')<
+  Service,
+  {
+    /**
+     * The local identity (`Option.none` when none exists) as a stream that emits the current
+     * value immediately on subscription. Take the first element for a one-shot read; subscribe
+     * for updates.
+     */
+    readonly identity: Stream.Stream<Option.Option<Info>>;
+    /**
+     * Synchronous snapshot of the local identity (`Option.none` when none exists). For imperative
+     * callers (non-React, non-Effect) that need the current value without subscribing.
+     */
+    readonly getSnapshot: () => Option.Option<Info>;
+    /**
+     * Subscribe to local-identity changes (imperative). Invokes `callback` immediately with the
+     * current value, then on each change. Returns an unsubscribe function.
+     */
+    readonly subscribe: (callback: (identity: Option.Option<Info>) => void) => () => void;
+    /** Create the local identity (and its first device). */
+    readonly create: (options?: { displayName?: string; deviceLabel?: string }) => Effect.Effect<Info, IdentityError>;
+    /** Re-admit this device to an existing identity via a recovery credential. */
+    readonly recover: (args: RecoverArgs) => Effect.Effect<Info, IdentityError>;
+    /** Update the identity profile. */
+    readonly updateProfile: (profile: {
+      displayName?: string;
+      data?: Record<string, unknown>;
+    }) => Effect.Effect<Info, IdentityError>;
+    /** Devices belonging to the local identity; emits the current set immediately. */
+    readonly devices: Stream.Stream<readonly DeviceInfo[]>;
+    /** Synchronous snapshot of the local identity's devices, for imperative callers. */
+    readonly getDevicesSnapshot: () => readonly DeviceInfo[];
+    /** HALO credentials of the local identity; emits the current set immediately. */
+    readonly credentials: Stream.Stream<readonly Credential[]>;
+    /**
+     * Grant this identity access to an EDGE/Hub service by writing a `ServiceAccess` credential
+     * (self-issued). Replaces hand-constructing the protobuf credential at the call site.
+     */
+    readonly grantServiceAccess: (options: ServiceAccessOptions) => Effect.Effect<void, IdentityError>;
+    /** Initiate a device invitation (host side). */
+    readonly share: (options?: Invitation.ShareOptions) => Effect.Effect<Invitation.Flow, IdentityError>;
+    /** Redeem a device-invitation code on a new device (guest side). */
+    readonly join: (code: string) => Effect.Effect<Invitation.Flow, IdentityError>;
+    /** Active (host-created) device-invitation flows; emits the current set immediately. */
+    readonly invitations: Stream.Stream<readonly Invitation.Flow[]>;
+  }
+>() {}
+
+/** The local identity as a current-value stream (requires {@link Service}). */
+export const identity: Stream.Stream<Option.Option<Info>, never, Service> = Stream.unwrap(
+  Effect.map(Service, (service) => service.identity),
+);
+
+/** Synchronous snapshot of the local identity (requires {@link Service}). */
+export const getSnapshot: Effect.Effect<Option.Option<Info>, never, Service> = Effect.map(Service, (service) =>
+  service.getSnapshot(),
+);
+
+/** Create the local identity (requires {@link Service}). */
+export const create = (options?: {
+  displayName?: string;
+  deviceLabel?: string;
+}): Effect.Effect<Info, IdentityError, Service> => Effect.flatMap(Service, (service) => service.create(options));
+
+/** Re-admit this device via a recovery credential (requires {@link Service}). */
+export const recover = (args: RecoverArgs): Effect.Effect<Info, IdentityError, Service> =>
+  Effect.flatMap(Service, (service) => service.recover(args));
+
+/** Update the identity profile (requires {@link Service}). */
+export const updateProfile = (profile: {
+  displayName?: string;
+  data?: Record<string, unknown>;
+}): Effect.Effect<Info, IdentityError, Service> => Effect.flatMap(Service, (service) => service.updateProfile(profile));
+
+/** Devices belonging to the local identity as a current-value stream (requires {@link Service}). */
+export const devices: Stream.Stream<readonly DeviceInfo[], never, Service> = Stream.unwrap(
+  Effect.map(Service, (service) => service.devices),
+);
+
+/** Synchronous snapshot of the local identity's devices (requires {@link Service}). */
+export const getDevicesSnapshot: Effect.Effect<readonly DeviceInfo[], never, Service> = Effect.map(Service, (service) =>
+  service.getDevicesSnapshot(),
+);
+
+/** HALO credentials as a current-value stream (requires {@link Service}). */
+export const credentials: Stream.Stream<readonly Credential[], never, Service> = Stream.unwrap(
+  Effect.map(Service, (service) => service.credentials),
+);
+
+/** Grant the identity access to an EDGE/Hub service (requires {@link Service}). */
+export const grantServiceAccess = (options: ServiceAccessOptions): Effect.Effect<void, IdentityError, Service> =>
+  Effect.flatMap(Service, (service) => service.grantServiceAccess(options));
+
+/** Initiate a device invitation (requires {@link Service}). */
+export const share = (options?: Invitation.ShareOptions): Effect.Effect<Invitation.Flow, IdentityError, Service> =>
+  Effect.flatMap(Service, (service) => service.share(options));
+
+/** Redeem a device-invitation code (requires {@link Service}). */
+export const join = (code: string): Effect.Effect<Invitation.Flow, IdentityError, Service> =>
+  Effect.flatMap(Service, (service) => service.join(code));
+
+/** Active device-invitation flows as a current-value stream (requires {@link Service}). */
+export const invitations: Stream.Stream<readonly Invitation.Flow[], never, Service> = Stream.unwrap(
+  Effect.map(Service, (service) => service.invitations),
+);

package/src/Invitation.ts

@@ -0,0 +1,95 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// @import-as-namespace
+
+import * as Effect from 'effect/Effect';
+import * as Stream from 'effect/Stream';
+
+import { type IdentityDid, type SpaceId } from '@dxos/keys';
+
+import { type InvitationError } from './errors';
+
+/**
+ * Whether an invitation admits a device to an identity or a member to a space.
+ */
+export type Kind = 'device' | 'space';
+
+/**
+ * How a guest proves it may redeem the invitation.
+ * Mirrors the legacy `Invitation.AuthMethod` protobuf enum.
+ */
+export type AuthMethod = 'none' | 'shared-secret' | 'known-public-key';
+
+/**
+ * Interactive (online host+guest handshake) vs delegated (offline-redeemable) invitation.
+ * Mirrors the legacy `Invitation.Type` protobuf enum.
+ */
+export type Type = 'interactive' | 'delegated' | 'multiuse';
+
+/**
+ * Options for initiating an invitation. Passed to {@link Identity.share} / {@link Space.share}.
+ */
+export type ShareOptions = {
+  readonly authMethod?: AuthMethod;
+  readonly type?: Type;
+  readonly multiUse?: boolean;
+  /** Restrict a `known-public-key` invitation to a specific guest (key/DID). */
+  readonly target?: string;
+};
+
+/**
+ * Outcome of a completed invitation flow.
+ */
+export type Result = {
+  readonly spaceId?: SpaceId;
+  readonly identityDid?: IdentityDid;
+};
+
+/**
+ * A lifecycle event emitted by an invitation {@link Flow}. Terminal events are `success`,
+ * `cancelled`, and `error`. Replaces polling on the legacy `Invitation.State` enum.
+ */
+export type Event =
+  | { readonly _tag: 'connecting' }
+  | { readonly _tag: 'connected' }
+  | { readonly _tag: 'readyForAuthentication'; readonly authCode?: string }
+  | { readonly _tag: 'authenticating' }
+  | { readonly _tag: 'success'; readonly result: Result }
+  | { readonly _tag: 'cancelled' }
+  | { readonly _tag: 'error'; readonly message: string };
+
+/**
+ * An in-flight invitation, host or guest side. Produced by {@link Identity.share}/`join` and
+ * {@link Space.share}/`join`; its lifecycle is then driven through this handle and the
+ * {@link Service}.
+ */
+export interface Flow {
+  readonly id: string;
+  readonly kind: Kind;
+  /** Hot stream of lifecycle events; completes after a terminal event. */
+  readonly events: Stream.Stream<Event>;
+  /** Supply the auth code when the flow reaches `readyForAuthentication`. */
+  authenticate(code: string): Effect.Effect<void, InvitationError>;
+  /** Abort the flow. */
+  cancel(): Effect.Effect<void>;
+  /** Encoded, shareable invitation code (host side). */
+  readonly code: Effect.Effect<string>;
+}
+
+/**
+ * Supply the auth code to a flow awaiting authentication. Flow verbs operate on a {@link Flow}
+ * handle directly and require no service; the active-flow set is queried through
+ * {@link Identity} (device invitations) and {@link Space} (space invitations).
+ */
+export const authenticate = (flow: Flow, code: string): Effect.Effect<void, InvitationError> => flow.authenticate(code);
+
+/** Abort a flow. */
+export const cancel = (flow: Flow): Effect.Effect<void> => flow.cancel();
+
+/** Lifecycle event stream of a flow. */
+export const events = (flow: Flow): Stream.Stream<Event> => flow.events;
+
+/** Encoded, shareable code for a flow. */
+export const code = (flow: Flow): Effect.Effect<string> => flow.code;

package/src/Space.ts

@@ -0,0 +1,192 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// @import-as-namespace
+
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import * as Option from 'effect/Option';
+import * as Schema from 'effect/Schema';
+import * as Stream from 'effect/Stream';
+
+import { IdentityDid, SpaceId } from '@dxos/keys';
+
+import { type SpaceError } from './errors';
+import * as Invitation from './Invitation';
+
+/**
+ * Capability level granted to a space member, matching the Keyhive `Access` enum. Ordered; each
+ * implies the previous: `pull` < `read` < `edit` < `admin`. Replaces the legacy
+ * `SpaceMember.Role` enum.
+ */
+export const Access = Schema.Literal('pull', 'read', 'edit', 'admin');
+export type Access = typeof Access.Type;
+
+/**
+ * Lifecycle state of a space. Replaces the legacy `SpaceState` protobuf enum (subset relevant to
+ * consumers).
+ */
+export const State = Schema.Literal('inactive', 'closed', 'ready');
+export type State = typeof State.Type;
+
+/**
+ * Who may join a space. Replaces the legacy `MembershipPolicy` protobuf enum: `invite` admits
+ * members via invitation only; `locked` admits no new members.
+ */
+export const MembershipPolicy = Schema.Literal('invite', 'locked');
+export type MembershipPolicy = typeof MembershipPolicy.Type;
+
+/**
+ * Whether a space replicates through EDGE. Replaces the legacy `EdgeReplicationSetting` protobuf
+ * enum.
+ */
+export const EdgeReplication = Schema.Literal('disabled', 'enabled');
+export type EdgeReplication = typeof EdgeReplication.Type;
+
+/**
+ * A space membership entry. Membership (HALO) only — liveness/presence is a separate concern
+ * (see API_AUDIT.md §3.6).
+ */
+export const Member = Schema.Struct({
+  /** DID of the member identity, when known. */
+  did: Schema.optional(IdentityDid),
+  /** Hex-encoded identity key of the member, for avatar/presence keying. */
+  identityKey: Schema.optional(Schema.String),
+  displayName: Schema.optional(Schema.String),
+  /** Arbitrary profile metadata (e.g. avatar emoji, hue). */
+  data: Schema.optional(Schema.Record({ key: Schema.String, value: Schema.Any })),
+  role: Access,
+  /** Whether the member is currently online. */
+  online: Schema.Boolean,
+});
+export type Member = typeof Member.Type;
+
+/**
+ * Public view of a space. A plain snapshot — database access stays on the ECHO `Database`
+ * service keyed by {@link SpaceId}, not on this value.
+ */
+export const Info = Schema.Struct({
+  id: SpaceId,
+  name: Schema.optional(Schema.String),
+  state: State,
+});
+export type Info = typeof Info.Type;
+
+/**
+ * A serialized space archive (export/import payload).
+ */
+export type Archive = {
+  readonly filename: string;
+  readonly contents: Uint8Array;
+};
+
+export type CreateOptions = {
+  readonly name?: string;
+  /** Tags applied to the new space. */
+  readonly tags?: readonly string[];
+  /** Who may join the space (defaults to `invite`). */
+  readonly membershipPolicy?: MembershipPolicy;
+};
+
+/**
+ * Space management and membership, plus space invitations. `share`/`join` construct
+ * {@link Invitation.Flow}s driven through the {@link Invitation} flow verbs; `invitations`
+ * observes the active (host-created) space-invitation flows.
+ */
+export class Service extends Context.Tag('@dxos/halo/Space')<
+  Service,
+  {
+    /**
+     * All spaces known to the local identity as a stream that emits the current set immediately
+     * on subscription. Take the first element for a one-shot read; subscribe for updates.
+     */
+    readonly spaces: Stream.Stream<readonly Info[]>;
+    /** Resolve a space by id. */
+    readonly get: (id: SpaceId) => Effect.Effect<Option.Option<Info>>;
+    /** Create a new space. */
+    readonly create: (options?: CreateOptions) => Effect.Effect<Info, SpaceError>;
+    /** Resolve once the space has reached the `ready` state. */
+    readonly waitReady: (id: SpaceId) => Effect.Effect<void, SpaceError>;
+    /** Enable or disable EDGE replication for a space. */
+    readonly setEdgeReplication: (id: SpaceId, setting: EdgeReplication) => Effect.Effect<void, SpaceError>;
+    /** A space's membership; emits the current set immediately, then on join/leave/role/presence. */
+    readonly members: (id: SpaceId) => Stream.Stream<readonly Member[]>;
+    /** Change a member's access level (Keyhive delegation). */
+    readonly updateMemberRole: (id: SpaceId, subject: IdentityDid, role: Access) => Effect.Effect<void, SpaceError>;
+    /** Remove a member (Keyhive revocation). */
+    readonly removeMember: (id: SpaceId, subject: IdentityDid) => Effect.Effect<void, SpaceError>;
+    /** Initiate a space invitation (host side). */
+    readonly share: (id: SpaceId, options?: Invitation.ShareOptions) => Effect.Effect<Invitation.Flow, SpaceError>;
+    /** Redeem a space-invitation code (guest side). */
+    readonly join: (code: string) => Effect.Effect<Invitation.Flow, SpaceError>;
+    /** A space's active (host-created) invitation flows; emits the current set immediately. */
+    readonly invitations: (id: SpaceId) => Stream.Stream<readonly Invitation.Flow[]>;
+    /** Export a space to an archive. */
+    readonly export: (id: SpaceId) => Effect.Effect<Archive, SpaceError>;
+    /** Import a space from an archive. */
+    readonly import: (archive: Archive, options?: { tags?: readonly string[] }) => Effect.Effect<Info, SpaceError>;
+  }
+>() {}
+
+/** All spaces as a current-value stream (requires {@link Service}). */
+export const spaces: Stream.Stream<readonly Info[], never, Service> = Stream.unwrap(
+  Effect.map(Service, (service) => service.spaces),
+);
+
+/** Resolve a space by id (requires {@link Service}). */
+export const get = (id: SpaceId): Effect.Effect<Option.Option<Info>, never, Service> =>
+  Effect.flatMap(Service, (service) => service.get(id));
+
+/** Create a new space (requires {@link Service}). */
+export const create = (options?: CreateOptions): Effect.Effect<Info, SpaceError, Service> =>
+  Effect.flatMap(Service, (service) => service.create(options));
+
+/** Resolve once the space is ready (requires {@link Service}). */
+export const waitReady = (id: SpaceId): Effect.Effect<void, SpaceError, Service> =>
+  Effect.flatMap(Service, (service) => service.waitReady(id));
+
+/** Enable or disable EDGE replication for a space (requires {@link Service}). */
+export const setEdgeReplication = (id: SpaceId, setting: EdgeReplication): Effect.Effect<void, SpaceError, Service> =>
+  Effect.flatMap(Service, (service) => service.setEdgeReplication(id, setting));
+
+/** A space's membership as a current-value stream (requires {@link Service}). */
+export const members = (id: SpaceId): Stream.Stream<readonly Member[], never, Service> =>
+  Stream.unwrap(Effect.map(Service, (service) => service.members(id)));
+
+/** Change a member's access level (requires {@link Service}). */
+export const updateMemberRole = (
+  id: SpaceId,
+  subject: IdentityDid,
+  role: Access,
+): Effect.Effect<void, SpaceError, Service> =>
+  Effect.flatMap(Service, (service) => service.updateMemberRole(id, subject, role));
+
+/** Remove a member (requires {@link Service}). */
+export const removeMember = (id: SpaceId, subject: IdentityDid): Effect.Effect<void, SpaceError, Service> =>
+  Effect.flatMap(Service, (service) => service.removeMember(id, subject));
+
+/** Initiate a space invitation (requires {@link Service}). */
+export const share = (
+  id: SpaceId,
+  options?: Invitation.ShareOptions,
+): Effect.Effect<Invitation.Flow, SpaceError, Service> =>
+  Effect.flatMap(Service, (service) => service.share(id, options));
+
+/** Redeem a space-invitation code (requires {@link Service}). */
+export const join = (code: string): Effect.Effect<Invitation.Flow, SpaceError, Service> =>
+  Effect.flatMap(Service, (service) => service.join(code));
+
+/** A space's active invitation flows as a current-value stream (requires {@link Service}). */
+export const invitations = (id: SpaceId): Stream.Stream<readonly Invitation.Flow[], never, Service> =>
+  Stream.unwrap(Effect.map(Service, (service) => service.invitations(id)));
+
+/** Export a space to an archive (requires {@link Service}). */
+export const exportSpace = (id: SpaceId): Effect.Effect<Archive, SpaceError, Service> =>
+  Effect.flatMap(Service, (service) => service.export(id));
+
+/** Import a space from an archive (requires {@link Service}). */
+export const importSpace = (
+  archive: Archive,
+  options?: { tags?: readonly string[] },
+): Effect.Effect<Info, SpaceError, Service> => Effect.flatMap(Service, (service) => service.import(archive, options));

package/src/errors.ts

@@ -0,0 +1,41 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { BaseError } from '@dxos/errors';
+
+/**
+ * The acting principal lacks the capability required for the operation
+ * (e.g. delegating access above their own level, or revoking without causal seniority).
+ */
+export class NotAuthorizedError extends BaseError.extend('NotAuthorizedError', 'Not authorized') {}
+
+/**
+ * The referenced principal (individual or group) is not known to the service.
+ */
+export class UnknownPrincipalError extends BaseError.extend('UnknownPrincipalError', 'Unknown principal') {}
+
+/**
+ * A signed payload failed signature verification or its id does not match its key.
+ */
+export class InvalidSignatureError extends BaseError.extend('InvalidSignatureError', 'Invalid signature') {}
+
+/**
+ * A membership operation references causal predecessors that have not been received.
+ */
+export class MissingDependencyError extends BaseError.extend('MissingDependencyError', 'Missing dependency') {}
+
+/**
+ * An identity/device operation (create, recover, profile/device update, device invitation) failed.
+ */
+export class IdentityError extends BaseError.extend('IdentityError', 'Identity operation failed') {}
+
+/**
+ * A space operation (create, query, membership, invitation, export/import) failed.
+ */
+export class SpaceError extends BaseError.extend('SpaceError', 'Space operation failed') {}
+
+/**
+ * An invitation-lifecycle operation (authenticate, cancel) failed.
+ */
+export class InvitationError extends BaseError.extend('InvitationError', 'Invitation operation failed') {}

package/src/index.ts

@@ -0,0 +1,9 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * as Identity from './Identity';
+export * as Invitation from './Invitation';
+export * as Space from './Space';
+
+export * from './errors';

package/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "extends": "../../../../tsconfig.base.json",
+  "compilerOptions": {
+    "types": [
+      "node"
+    ]
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../common/errors"
+    },
+    {
+      "path": "../../../common/keys"
+    }
+  ]
+}