@dxos/halo 0.0.0

package/MIGRATION.md

@@ -0,0 +1,254 @@
+# HALO → Keyhive Migration
+
+Plan for rewriting HALO — replacing the protocol-buffer credential definitions and the hypercore-backed keyring/feed machinery — on top of [Keyhive](https://www.inkandswitch.com/keyhive/notebook/), the capability/encryption layer being developed as part of the Automerge ecosystem.
+
+Status: draft. Backwards compatibility is explicitly out of scope at this stage.
+
+See [API_AUDIT.md](./API_AUDIT.md) for the consumer-side audit (Composer/plugins) and the proposed Effect service surface that fronts this migration.
+
+## 1. Current HALO implementation
+
+### 1.1 Architecture
+
+HALO is a credential system layered over append-only, signed hypercore feeds. Every identity owns a **HALO space** (a special space whose control feed carries the identity's credentials). Regular (ECHO) spaces carry their own credential stream in their **control feed**, separate from the **data feed** (database mutations).
+
+| Package                                       | Role                                                                                       |
+| --------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| `@dxos/protocols` (`proto/dxos/halo/*.proto`) | Protobuf definitions: `Credential`, `Claim`, `Proof`, assertions, invitations, keys        |
+| `@dxos/credentials`                           | Credential factory/verifier, presentations, state machines, credential DAG                 |
+| `@dxos/keyring`                               | ECDSA-P256 key storage (RAM/file or SQLite), signing; private keys never leave the keyring |
+| `@dxos/client-services`                       | `IdentityManager`, invitation host/guest state machines, contacts service                  |
+| `@dxos/echo-host`                             | Pipelines that feed credentials from feeds into the state machines                         |
+
+### 1.2 Key types
+
+**Credential** (the universal envelope):
+
+```protobuf
+message Credential {
+  PublicKey id;                                 // SHA-256 of signed payload.
+  PublicKey issuer;                             // Space, identity, or device key.
+  Timestamp issuance_date;
+  Claim subject;                                // { id: PublicKey, assertion: Any }
+  Proof proof;                                  // { type, signer, nonce, value, chain? }
+  repeated PublicKey parent_credential_ids;     // DAG for concurrent updates.
+}
+```
+
+A `Proof.chain` carries a nested credential (`AuthorizedDevice`) proving a device may sign on behalf of an identity. `Presentation` bundles credentials + proofs (with nonces) for challenge/response.
+
+**Assertions** (payload of `Claim.assertion`):
+
+| Assertion                                               | Purpose                                                                           |
+| ------------------------------------------------------- | --------------------------------------------------------------------------------- |
+| `SpaceGenesis`                                          | First message in a space's genesis feed; sets tags + membership policy            |
+| `SpaceMember`                                           | Admit/remove identity; role: `OWNER`, `ADMIN`, `EDITOR`, `READER`, `REMOVED`      |
+| `MemberProfile`                                         | Per-space member profile update                                                   |
+| `AdmittedFeed`                                          | Permit a feed to replicate in a space (`CONTROL` \| `DATA`)                       |
+| `AuthorizedDevice`                                      | Authorize device key to sign for identity (device chain)                          |
+| `DeviceProfile`                                         | Device metadata (`label`, `platform`, `os`, `type`: BROWSER/NATIVE/AGENT/MOBILE…) |
+| `IdentityProfile`                                       | Identity profile (`display_name`, `avatar_cid`, custom `data`)                    |
+| `HaloSpace`                                             | Links identity key → its HALO space key                                           |
+| `IdentityRecovery`                                      | Recovery key (passkey/seedphrase) for identity                                    |
+| `DelegateSpaceInvitation` / `CancelDelegatedInvitation` | Offline-redeemable invitations                                                    |
+| `Epoch`                                                 | Snapshot/GC markers                                                               |
+
+**Keyring**: `KeyRecord { public_key, secret_key }`; keys typed IDENTITY / DEVICE / SPACE / FEED. ECDSA-P256 via SubtleCrypto; storage is file-per-key or SQLite.
+
+**Contacts**: not stored — `ContactsService` derives `Contact { identityKey, profile, commonSpaces }` on the fly from space memberships.
+
+### 1.3 Key flows
+
+**Identity creation** (`IdentityManager.createIdentity`):
+
+1. Generate identity, device, control-feed, data-feed, and HALO-space keys.
+2. Write to the HALO control feed: `SpaceGenesis`, `SpaceMember(identity, ADMIN)`, `AdmittedFeed(data)`, `AuthorizedDevice(identity → device)`, `DeviceProfile`, optional `IdentityProfile`.
+3. Identity is ready when the device chain (`AuthorizedDevice`) has been processed.
+
+**Device join (HALO invitation)**: host and guest run an interactive state machine (INIT → CONNECTING → … → SUCCESS) over a swarm keyed by the invitation. Guest introduces itself, authenticates (shared secret or known-key challenge), sends its device + feed keys; host writes `AuthorizedDevice` + `AdmittedFeed` credentials and returns them with genesis hints.
+
+**Space invitation**: same interactive machinery, but host writes `SpaceMember` (+ `AdmittedFeed`) for the guest identity. **Delegated** invitations write a `DelegateSpaceInvitation` credential replicated to all members, so any admin device — or, for `KNOWN_PUBLIC_KEY` auth, the guest itself — can complete admission offline; redemption is linked via `parent_credential_ids`.
+
+**Access control / credential processing**: each space runs a `SpaceStateMachine` that verifies signatures (and delegation chains), then dispatches to `MemberStateMachine`, `FeedStateMachine`, `InvitationStateMachine`, plus identity-level `DeviceStateMachine` / `ProfileStateMachine`. Concurrent conflicting updates (e.g. two admins removing each other) are resolved via a **credential DAG** (`parent_credential_ids`): merge points wait for all paths, `tryPickWinningUpdate` breaks ties (OWNER wins), losing paths are replayed with overrides.
+
+**Replication auth**: on connection, peers exchange signed auth messages; `TrustedKeySetAuthVerifier` checks the peer device is in the authorized set; feeds then replicate. Credentials gate replication (membership) but **content is not end-to-end encrypted** — possession of feeds implies readability.
+
+## 2. Keyhive
+
+Keyhive is a local-first authorization and encryption layer from Ink & Switch (Rust core, WASM/TS bindings; pre-alpha). It provides group membership as a CRDT, continuous group key agreement (BeeKEM), and end-to-end encryption designed to compose with Automerge sync (Beelay → **Subduction**).
+
+### 2.1 Core concepts
+
+- **Everything is a public key.** All principals — users, devices, groups, documents — are identified by Ed25519 keys. `Agent` = `Active` (local user) | `Individual` | `Group` | `Document`. A `Document` is a `Group` that also owns content; `Membered` = Group | Document.
+- **Convergent capabilities**: a certificate-capability model compatible with CRDTs. Authority flows through signed **delegations** between keys; no consensus, no central authority, verification is offline.
+- **`Access` levels** (ordered; each implies the previous): `Pull` (replicate ciphertext only — what sync servers get) < `Read` (decrypt) < `Edit` (append ops) < `Admin` (manage membership; revoke anyone).
+- **Membership ops** (`Delegation` / `Revocation`) form a hash-linked DAG requiring only causal order — the same consistency model as Automerge. Non-admins may only revoke members they have _causal seniority_ over; admins may revoke anyone. Members may sub-delegate (attenuated) capabilities.
+- **No global identity.** An `Individual` is one immutable Ed25519 key. A _person_ is modeled as a `Group` over their device keys; device add/remove is ordinary delegation/revocation. There is no built-in recovery — recovery keys are modeled as group members.
+- **`ContactCard`**: a shareable signed credential (individual id + fresh prekey + signature) used to introduce identities and add them to groups/documents — including **while they are offline**, via published X25519 **prekeys**.
+
+### 2.2 Cryptography
+
+- **BeeKEM** — a concurrent TreeKEM/CGKA variant. Binary tree: leaves are member keys, inner nodes carry DH public keys + encrypted path secrets; the root secret keys the document. Removal blanks the member's path (removal wins over concurrent updates); concurrent updates keep _conflict keys_ and encrypt to both forks' resolutions. Needs only causal ordering (no MLS-style sequencing server).
+- **Primitives**: Ed25519 (signing/identity), X25519 (ECDH "share keys", rotating), BLAKE3 (KDF), XChaCha20-Poly1305 (AEAD).
+- **PCS**: leaf rotations + blanking give post-compromise security (`force_pcs_update`); `PcsKey` derives from the tree root.
+- **Causal encryption**: content is encrypted per change/chunk; each chunk embeds the keys of its causal ancestors, so one head key grants access back through history (deliberately trades forward secrecy at the content layer for late-joiner history access). `ApplicationSecret` = KDF(PcsKey, content ref).
+- **Sedimentree**: hierarchical chunking of the encrypted commit graph so servers sync ciphertext efficiently (~2 round trips) without plaintext.
+
+### 2.3 Data flows
+
+- **Membership propagation**: delegations/revocations/CGKA ops are signed events replicated as grow-only sets; per-peer visibility computed (`events_for_agent`); ingestion buffers events until causal dependencies arrive; set reconciliation via rateless IBLT (RIBLT).
+- **Auth handshake**: every sync message is signed by a non-extractable local key and audience-bound (recipient key or hostname hash) + timestamped — no session handshake state.
+- **Automerge integration**: Keyhive plugs into Automerge Repo as an _auth provider_; **Subduction** is the successor sync protocol with explicit Keyhive + Automerge integration (sedimentree chunking, E2EE-friendly). DXOS already vendors subduction-flavored automerge packages.
+- **Persistence**: `Keyhive` state serializes via `Archive`; signer is pluggable (fits WebCrypto non-extractable keys — replacing our keyring's role).
+
+## 3. Concept mapping: HALO → Keyhive
+
+| HALO (current)                                                   | Keyhive analogue                                                                                          | Notes                                                                                                                                     |
+| ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| Identity (identity key + HALO space)                             | `Group` over device keys ("identity group")                                                               | Identity DID derives from the group's key. The HALO space's _credential_ role dissolves into the group's membership DAG.                  |
+| Device (device key + `AuthorizedDevice` chain)                   | `Individual` (leaf Ed25519 key) member of the identity group                                              | Device admission = delegation into the identity group; no bespoke chain verification.                                                     |
+| `AuthorizedDevice` credential                                    | `Delegation` (identity group → device key)                                                                |                                                                                                                                           |
+| Device removal (not well supported today)                        | `Revocation` + BeeKEM path blanking                                                                       | Gains PCS: removed devices lose access to future content.                                                                                 |
+| Space (space key + control/data feeds)                           | `Document` (group + content) — or a `Group` owning many Automerge docs                                    | Space membership = document/group membership.                                                                                             |
+| `SpaceGenesis`                                                   | Document/group creation (self-certifying root)                                                            |                                                                                                                                           |
+| `SpaceMember` role: READER / EDITOR / ADMIN / OWNER              | `Access`: `Read` / `Edit` / `Admin` (+ `Pull`)                                                            | OWNER ≈ root delegation holder. `Pull` is new: trust-minimized relays. REMOVED = revocation.                                              |
+| `AdmittedFeed`                                                   | — (obsolete)                                                                                              | Feeds disappear; Automerge/Subduction sync replaces hypercore replication.                                                                |
+| Credential DAG (`parent_credential_ids`, `tryPickWinningUpdate`) | Membership op DAG (`auth_pred`, causal seniority rules)                                                   | Keyhive natively resolves concurrent membership changes.                                                                                  |
+| Keyring (ECDSA-P256, exportable records)                         | Pluggable `AsyncSigner` + `ShareKeyMap` / prekeys                                                         | Ed25519/X25519; supports non-extractable WebCrypto keys.                                                                                  |
+| Credential feed (hypercore, append-only)                         | Signed event sets (delegations/revocations/CGKA ops) + RIBLT sync                                         | Causal DAG instead of per-feed total order.                                                                                               |
+| Interactive invitation state machines                            | Out of band for Keyhive: `ContactCard` exchange + delegation                                              | Swarm/QR/PIN UX stays ours (MESH); admission becomes "receive contact card → delegate access". Offline invitations come free via prekeys. |
+| `DelegateSpaceInvitation`                                        | Delegation to a not-yet-online individual (prekeys), or to an ephemeral invitation key that sub-delegates | Sub-delegation is a first-class Keyhive feature.                                                                                          |
+| `IdentityProfile` / `MemberProfile` credentials                  | Application data (ECHO objects) — e.g. `Profile` in an identity-owned document                            | Profiles stop being credentials; they become replicated data governed by capabilities.                                                    |
+| `DeviceProfile`                                                  | Application data (`Device` object)                                                                        | Same.                                                                                                                                     |
+| Contacts (derived by `ContactsService`)                          | `AddressBook` of `Profile` objects + stored `ContactCard`s                                                | Becomes explicit, persistent application data.                                                                                            |
+| `IdentityRecovery`                                               | Recovery key as member of the identity group                                                              | Delegation with high access; no special-case credential.                                                                                  |
+| Replication auth (`TrustedKeySetAuthVerifier`)                   | Signed, audience-bound sync messages + `Pull` capability                                                  | Also gains E2EE — servers only ever see ciphertext.                                                                                       |
+| `Presentation` / nonce challenge                                 | Signed messages / capability `Invocation`                                                                 |                                                                                                                                           |
+| `Epoch`                                                          | Sedimentree strata / compaction                                                                           | Different mechanism, same GC intent.                                                                                                      |
+
+## 4. Migration path (high level)
+
+Phased; no backwards compatibility. Each phase lands behind the new `@dxos/halo` package so the legacy stack keeps working until cut-over.
+
+1. **Schema layer (this package).** Define Effect schemas for the durable, application-visible types — `Profile`, `Device`, `Group`, `AddressBook` — as ECHO object types addressable by EID, with identities/devices addressed by DID (`@dxos/keys`). These replace `ProfileDocument`, `DeviceProfileDocument`, and derived contacts, and are independent of the credential machinery.
+2. **Keyhive service.** Wrap `keyhive_wasm` in an Effect service (`Keyhive.Service`): identity-group creation, delegation/revocation, contact cards, prekeys, archive persistence. Adapt `@dxos/keyring` usage to the pluggable signer (Ed25519, ideally non-extractable WebCrypto).
+3. **Identity rewrite.** `createIdentity` → create identity `Group` + first device `Individual`; DID derived from the group key. Profile becomes a `Profile` object in an identity-owned document (HALO "space" becomes a plain Keyhive document group).
+4. **Device join.** Keep the MESH invitation UX (swarm, QR, auth code) as pure transport for `ContactCard` exchange; admission = delegation of the new device key into the identity group. Device removal = revocation (new capability we cannot express today without re-keying).
+5. **Space membership / access control.** Spaces become Keyhive `Document` groups over their Automerge docs (via Subduction, already vendored). Map roles to `Access` levels; delete `SpaceStateMachine`, `MemberStateMachine`, the credential DAG, and `AdmittedFeed` entirely — Keyhive's membership DAG subsumes them. Introduce `Pull`-level membership for edge/relay services.
+6. **Invitations.** Interactive invitations → contact-card exchange + immediate delegation. Delegated/offline invitations → prekey-based delegation or ephemeral invitation keys with attenuated sub-delegation. Delete `DelegateSpaceInvitation` credentials and the invitation state machine's credential plumbing.
+7. **Decommission.** Remove hypercore feeds, protobuf credential definitions, `@dxos/credentials` state machines, and the ECDSA keyring. Contacts UI reads `AddressBook`/`Profile` objects instead of `ContactsService`.
+
+**Open questions / risks:**
+
+- Keyhive is pre-alpha and unaudited; API churn is certain. Isolate it behind the `@dxos/halo` service boundary.
+- Concurrent admin-vs-admin revocation semantics differ from HALO's OWNER-wins rule; product implications need review.
+- Content-layer forward secrecy is deliberately absent in Keyhive (causal encryption); confirm this matches our threat model.
+- Agent/server ("AGENT" device type) key custody with non-extractable keys needs a story (e.g. `Pull`-only relays + delegated agent keys).
+
+## 5. Prototype service and HALO shim feasibility
+
+> Note: the pure-TypeScript Keyhive prototype (`Keyhive.ts`) has been **removed from
+> `@dxos/halo`** to keep that package definitions-only (see `API_AUDIT.md` §3.5); its runtime is
+> destined for a separate `@dxos/halo-keyhive`. The feasibility analysis below is retained as
+> design rationale.
+
+The prototype implemented a pure-TypeScript, in-memory model of the Keyhive membership layer
+(Keyhive is not published to npm). Its `Keyhive.Service` interface mirrored the `keyhive_wasm`
+bindings so a WASM-backed layer could replace `layerMemory()` unchanged.
+
+**Can the existing HALO implementation be shimmed behind this API?**
+Mostly yes for the membership core; no for encryption. A `layerLegacy()` backed by `@dxos/credentials` +
+`@dxos/client-services` would map:
+
+| Service operation    | Legacy backing                                          | Fidelity                                                                                                                                       |
+| -------------------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `active`             | Device key (DID from device public key)                 | Good — devices are already key-identified principals.                                                                                          |
+| `createGroup`        | Space genesis (`SpaceGenesis` + `SpaceMember(OWNER)`)   | Good — both are self-certifying roots.                                                                                                         |
+| `delegate`           | `SpaceMember` credential with role mapped from `Access` | Partial — `admin→ADMIN`, `edit→EDITOR`, `read→READER`; **`pull` has no legacy equivalent** (no E2EE, membership implies readability) — reject. |
+| `revoke`             | `SpaceMember(REMOVED)`                                  | Partial — legacy resolves conflicts via credential DAG + OWNER-wins, not causal seniority; semantics differ under concurrency.                 |
+| `members`            | `MemberStateMachine` output                             | Good — both are materialized views.                                                                                                            |
+| `contactCard`        | Identity key + `ProfileDocument` (as a `Presentation`)  | Partial — legacy has no prekeys, so offline admission needs `DelegateSpaceInvitation` instead of prekey delegation.                            |
+| `receiveContactCard` | Verify presentation; record identity key                | Good.                                                                                                                                          |
+| `ops` / `receiveOps` | Credential feed messages                                | Partial — legacy ops are totally ordered per feed (hypercore), not a causal DAG; export is possible, import must be replayed in feed order.    |
+
+Structural gaps that cannot be shimmed:
+
+1. **Nested groups.** Legacy members are identities only; a `delegate` whose subject is another
+   group/space has no credential representation. Shim must reject group subjects.
+2. **Attenuated sub-delegation.** Legacy `EDITOR`/`READER` cannot invite at all
+   (`_canInviteNewMembers` requires ADMIN/OWNER); Keyhive lets any member delegate up to their
+   own access. Shim must restrict delegation to admins, which is _stricter_ than the API implies.
+3. **Encryption surface.** Anything CGKA-related (`ApplicationSecret`, PCS rotation) is
+   unimplementable over plaintext feeds; the service deliberately excludes it so the membership
+   API stays shimmable.
+4. **Signer.** Legacy keyring is ECDSA-P256, prototype is Ed25519 — the op envelope carries the
+   algorithm implicitly via the author key, so a shim needs an algorithm tag or must reuse the
+   keyring's P-256 keys for signing ops.
+
+Conclusion: a legacy shim is feasible as a _transition layer_ — same API, reduced semantics
+(no `pull`, no nested groups, admin-only delegation, feed-ordered sync) — which would let
+`client-services` code migrate to the `Keyhive.Service` API before the Keyhive/Subduction
+backend lands. The prototype's in-memory layer and a future `layerLegacy()` are then two
+implementations of one seam, and cut-over is a layer swap.
+
+### 5.1 EDGE service specification
+
+How the EDGE service (`@dxos/edge-client`, `EdgeService` in `@dxos/protocols`) participates in
+the Keyhive model — both under the legacy shim and after cut-over.
+
+**Identity.** Each EDGE deployment is a first-class principal: an Ed25519 key with a DID, like
+any device. The current `EdgeIdentity` challenge/`Presentation` handshake (`presentCredentials`
+with nonce, `/ws/<identityDid>/<peerKey>`) is replaced by Keyhive/Subduction message auth:
+every message signed by the sender's key and audience-bound to the EDGE hostname hash
+(anti-MITM, anti-replay) — no session handshake state.
+
+**Admission.** EDGE is admitted to a space/group like any member:
+`delegate({ group, subject: <edge did>, access: 'pull' })`. This makes relay access explicit,
+auditable, and revocable in the membership DAG — today EDGE access is implicit in feed
+replication auth. Server-side capabilities that require plaintext (AI, search/indexing) must be
+admitted as explicit `read`-level members, making that trust decision visible per space rather
+than ambient.
+
+**Capabilities at `pull` level.** EDGE may: store and forward ciphertext (the `CiphertextStore`
+role; Sedimentree strata + commit-graph hashes, which stay outside the encryption envelope for
+sync); relay membership ops (delegations/revocations/CGKA ops are signed, self-verifying
+events); serve set-reconciliation (RIBLT) exchanges. EDGE cannot: decrypt content, author or
+forge membership ops, or build plaintext indexes.
+
+**Service mapping** (`EdgeService` enum):
+
+| Service                 | Disposition under Keyhive                                                               |
+| ----------------------- | --------------------------------------------------------------------------------------- |
+| `SUBDUCTION_REPLICATOR` | Primary sync path; EDGE acts as a `pull`-level Subduction peer.                         |
+| `AUTOMERGE_REPLICATOR`  | Superseded by Subduction; retire with the migration.                                    |
+| `FEED_REPLICATOR`       | Deleted — already `TODO(mykola): Remove once we migrate to keyhive for access control`. |
+| `QUEUE_REPLICATOR`      | Retained (renamed per existing TODO); queue payloads become ciphertext under `pull`.    |
+| `SWARM` / `SIGNAL`      | Unchanged — pure transport; requires message auth but no group capability.              |
+| `STATUS`                | Unchanged.                                                                              |
+
+**Hub duties layered on EDGE** (require no `read` access):
+
+1. **Offline invitation mailbox.** Prekey-based admission means delegations can be issued for
+   offline invitees; EDGE parks the signed ops (and encrypted welcome payloads) until the
+   invitee connects — replacing `DelegateSpaceInvitation` availability semantics.
+2. **Contact directory.** Handle/email → DID + `ContactCard` resolution (comparable to atproto
+   handle resolution). Contact cards are signed and self-verifying, so the directory is
+   untrusted for integrity — it can withhold but not forge.
+3. **Agent key custody.** `agent-managed` devices become distinct principals whose access is
+   explicitly delegated (`read`/`edit` as needed) rather than inherited from feed replication;
+   custody of those keys is an EDGE responsibility and revocation is an ordinary membership op.
+
+**Under the legacy shim.** `layerLegacy()` cannot grant `pull` (feeds are plaintext), so EDGE
+remains read-equivalent until the Keyhive backend lands. The shim-era spec is therefore:
+adopt the delegation-based admission and signed message auth now (both expressible over
+credentials), and treat `pull` enforcement as activated by the backend swap, not by an EDGE
+API change.
+
+## A. ISSUES
+
+1. Migration from protobuf?
+2. Alt:
+   - a. Old API => Old Hypercore impl.
+   - b. New API => Old Hypercore impl.
+   - c. New API => New EDGE endpoint impl (shim).
+   - d. New API => Keyhive service impl.

package/MIGRATION_PLAN.md

@@ -0,0 +1,217 @@
+# HALO consumer migration — plan & decisions
+
+Working plan for migrating Composer/plugins off direct `@dxos/client` HALO access
+onto the `@dxos/halo` Effect services. Tracks the settled preferences so scope
+does not need to be re-litigated.
+
+## Settled preferences (do not re-ask)
+
+- **One big PR.** Land as much of the migration as cleanly possible in a single
+  PR (#12229) on branch `claude/halo-api-audit-migration-w5al1i`, rather than a
+  string of small follow-ups. The one acknowledged exception is the deferred
+  service verbs (see Phase 2 / Status below): the consumers that depend on them
+  cannot migrate until those verbs exist, so they remain outstanding regardless
+  of PR count.
+- **Extend the HALO API as needed.** Where a consumer needs something the
+  DID-only `Identity.Info` dropped, extend the HALO service/adapter rather than
+  leaving the consumer on `@dxos/client`. Planned extensions:
+  - `Identity.Info`: add `identityKey` (hex) back, and `profile` data
+    (`{ displayName?, data? }`) so Profile UI (emoji/hue) works.
+  - `Identity.updateProfile`: accept `{ displayName?, data? }`.
+  - `Identity`: add `updateDevice`, credential query/write, recovery-credential
+    creation (`createRecoveryCredential` / `requestRecoveryChallenge`), and EDGE
+    attest (`createEdgeIdentity`/`presentCredentials`) verbs.
+  - `Identity.create`: expose the personal `spaceId` (or add `Space.personal`).
+  - `useCredentials` hook in `@dxos/halo-react`.
+- **ECHO stays separate.** `space.db` / `useQuery` / properties remain on
+  `@dxos/echo` / `@dxos/react-client/echo` — that is the ECHO track, not
+  `@dxos/client` HALO. `useSpaces`/`useSpace` sites that exist only to reach
+  `space.db` are NOT migrated to `@dxos/halo-react`.
+- **Mutations route through Operations** (app-framework), handlers use the
+  services; components dispatch operations.
+
+## Known external blocker (not fixable from here)
+
+CI `check-packages-published` requires `@dxos/halo`, `@dxos/halo-adapter-client`,
+`@dxos/halo-react` to be published to npm with OIDC trusted publishing. That is a
+maintainer/release action. The PR stays red on that one check until a maintainer
+publishes the packages; all other checks should be green.
+
+## Phases (all in the one PR)
+
+1. **plugin-client foundation** — DONE: `IdentityLayerSpec`/`SpaceLayerSpec`,
+   `HaloProvider`, deps. Packages made publishable.
+2. **Extend HALO API + adapter** — add the verbs/fields above to `@dxos/halo`
+   and implement in `@dxos/halo-adapter-client`; add `useCredentials` and any
+   missing hooks to `@dxos/halo-react`.
+3. **plugin-client operations** — `create-identity`, `update-profile` (new),
+   recovery/passkey, device update: declare + use `Identity.Service`.
+4. **plugin-client containers** — Account (DONE), Profile, Devices, Recovery.
+5. **Other plugins** — swap `useIdentity`/`useDevices`/`useMembers`/
+   space-invitation hooks to `@dxos/halo-react`; leave ECHO `space.db` sites.
+6. **Cleanup** — drop now-unused `@dxos/react-client/halo` imports; changeset.
+
+## Migration outcome — what moved and what stays
+
+The migration decision is: **plugins consume HALO via `@dxos/halo` /
+`@dxos/halo-react`, never `@dxos/client` HALO APIs.** ECHO `space.db` stays on
+`@dxos/echo`. The only place the client backs HALO is the adapter
+(`@dxos/halo-adapter-client`) and plugin-client's client provider + the
+`IdentityService`/`SpaceService` capabilities it contributes.
+
+### HALO API added to support consumers
+
+- `Identity.Info` gained `identityKey` (hex) + `data`; `Space.Member` gained
+  `identityKey` (hex), `displayName`, `data`.
+- `Identity`: `credentials` stream + `Credential` type, `grantServiceAccess`
+  verb, synchronous `getSnapshot()` / `getDevicesSnapshot()` and imperative
+  `subscribe()` for non-React/non-Effect callers.
+- `@dxos/halo-react`: `useCredentials` (plus existing useIdentity/useDevices/
+  useMembers/useSpaces/useInvitations).
+- plugin-client contributes `ClientCapabilities.IdentityService` / `SpaceService`
+  (the service instances) for imperative capability singletons.
+
+### Migrated (off `@dxos/client` HALO)
+
+- **React consumers** — plugin-client (Account/Profile/Recovery containers,
+  UpdateProfile operation), plugin-assistant (Chat/ChatThread),
+  plugin-comments (CommentsArticle, CommentThread + `getMessageMetadata`),
+  plugin-transcription (useTranscriptionRecording, TranscriptionArticle),
+  plugin-markdown / plugin-code / plugin-script editors, plugin-thread
+  (MessageThread/ThreadArticle/ChannelArticle), plugin-space (SpacePresence).
+  Enabled by narrowing shared UI signatures to structural types
+  (`DataExtensionsIdentity` in `@dxos/ui-editor`, `BylineIdentity` in
+  `@dxos/react-ui-transcription`, `MessageAuthor` in thread/comments) that the
+  HALO `Identity.Info` / `Space.Member` satisfy — no `@dxos/halo` dependency
+  pushed into foundational UI packages.
+- **Imperative capability singletons** — plugin-iroh-beacon (beacon-service),
+  plugin-assistant (edge-model-resolver identity reads), plugin-calls
+  (call-manager + CallSwarmSynchronizer), plugin-meeting (call-extension),
+  plugin-space (navigation-handler, spaces-ready, join operation),
+  plugin-transcription (transcriber) — all read identity/devices via the
+  `IdentityService` capability (`getSnapshot`/`getDevicesSnapshot`/`subscribe`).
+
+## Missing APIs
+
+The end goal (per maintainer direction) is to **eliminate all `@dxos/client` and
+`@dxos/react-client` imports from `packages/plugins/*` and `packages/ui/*`**. The
+following APIs do not yet exist and block that; every plugin line below that is
+not "complete" references one of these numbers.
+
+### HALO (this PR's surface)
+
+1. **Personal space id from identity creation.** `Identity.create` must return
+   the personal `spaceId` (or add `Identity.personalSpaceId` / `Space.personal`).
+   Today consumers read `client.halo.identity.get()?.spaceKey`.
+2. **Recovery-credential creation.** `Identity.createRecoveryCredential({ recoveryKey,
+algorithm, lookupKey })` (+ `requestRecoveryChallenge`). The WebAuthn/passkey
+   ceremony stays at the call site; only the credential write moves to HALO.
+3. **EDGE identity / VP-auth verb.** A HALO replacement for
+   `createEdgeIdentity(client)` (`@dxos/client/edge`) + `presentCredentials`, so a
+   consumer can attach the signed-in identity to an EDGE/Hub HTTP client.
+4. **Device-invitation share for non-client UI.** `Identity.share()` must surface a
+   flow/observable the UI can render without `@dxos/client/invitations`, plus a
+   HALO-typed device that `@dxos/shell`'s `DeviceListItem` accepts (or a
+   halo-typed list item). Today: `client.halo.share()` + client `Device`.
+5. **Operation/hook to invoke `grantServiceAccess` from React.** The verb exists;
+   a `ClientOperation` (or `useGrantServiceAccess`) is needed so components can
+   call it without `client.halo.writeCredentials`.
+6. **Identity atom for graph builders.** An `Atom`/observable bridge (or documented
+   `Atom.make(Identity.identity…)` recipe) to replace
+   `CreateAtom.fromObservable(client.halo.identity)` in app-graph builders.
+
+### ECHO track (separate, much larger — ~340 imports)
+
+7. **`@dxos/echo` / `@dxos/echo-client` React bindings** replacing
+   `@dxos/react-client/echo` (and `@dxos/client/echo`): `useQuery`, `useSpace`,
+   `useSpaces`, `useObject`, `getSpace`, and the `Space` / `SpaceMember` value
+   types. This is the single biggest blocker to dropping `@dxos/react-client`.
+8. **Space-invitation UI via HALO.** Migrate `@dxos/react-client/invitations` +
+   `@dxos/client/invitations` UIs onto `Space.share` / `Space.join` /
+   `Space.invitations` (the verbs exist; the React/observable surface does not).
+
+### Platform / root client
+
+9. **Config / mesh / services access** without the `@dxos/client` root export or
+   `useClient` — e.g. `client.config`, `client.mesh.networkStatus`,
+   `client.services`. Needed by app-graph-builder, DevicesContainer (network
+   status), plugin-debug, and every `useClient()`/`Client`/`Config` site.
+10. **Test harness.** A replacement for `@dxos/react-client/testing`
+    (`withClientProvider`, `useClientStory`) used by plugin stories/tests. Low
+    priority; unblocks the last imports after 7–9 land.
+
+## Composer plugins
+
+HALO column: status of _this_ migration (HALO off `@dxos/client`). Blockers:
+what still pins `@dxos/client` / `@dxos/react-client`, by Missing-API number
+above. **Any plugin not listed here imports neither `@dxos/client` nor
+`@dxos/react-client` in non-test/story source — complete.** `(story)` = the only
+remaining import is in a `*.stories.tsx`.
+
+| Plugin                                                                                                                                                                                                                                                                                                                                                                         | HALO     | Remaining `@dxos/client` / `@dxos/react-client` pins                                                                                                                                                                         |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| plugin-client                                                                                                                                                                                                                                                                                                                                                                  | partial  | create-identity (1), create-passkey (2), useHubClient (3), DevicesContainer (4, 9), app-graph-builder (6, 9), invitations UI (8), the client provider + `IdentityService`/`SpaceService` capabilities (intentional boundary) |
+| plugin-onboarding                                                                                                                                                                                                                                                                                                                                                              | partial  | WelcomeScreen/onboarding-manager/util/oauth (1, 2), ECHO (7)                                                                                                                                                                 |
+| plugin-script                                                                                                                                                                                                                                                                                                                                                                  | partial  | react-surface credential write (5), deploy/functions helpers take a `client` param, EDGE (3), ECHO (7)                                                                                                                       |
+| plugin-assistant                                                                                                                                                                                                                                                                                                                                                               | complete | edge-model-resolver EDGE identity (3), ECHO (7)                                                                                                                                                                              |
+| plugin-connector                                                                                                                                                                                                                                                                                                                                                               | n/a      | EDGE (3), ECHO (7)                                                                                                                                                                                                           |
+| plugin-payments                                                                                                                                                                                                                                                                                                                                                                | n/a      | EDGE (3)                                                                                                                                                                                                                     |
+| plugin-comments                                                                                                                                                                                                                                                                                                                                                                | complete | ECHO (7)                                                                                                                                                                                                                     |
+| plugin-thread                                                                                                                                                                                                                                                                                                                                                                  | complete | ECHO (7); `useIdentity` (story)                                                                                                                                                                                              |
+| plugin-space                                                                                                                                                                                                                                                                                                                                                                   | complete | ECHO (7), invitations (8), config/mesh (9)                                                                                                                                                                                   |
+| plugin-transcription                                                                                                                                                                                                                                                                                                                                                           | complete | ECHO (7)                                                                                                                                                                                                                     |
+| plugin-markdown                                                                                                                                                                                                                                                                                                                                                                | complete | ECHO (7)                                                                                                                                                                                                                     |
+| plugin-code                                                                                                                                                                                                                                                                                                                                                                    | complete | ECHO (7)                                                                                                                                                                                                                     |
+| plugin-calls                                                                                                                                                                                                                                                                                                                                                                   | complete | config/services (9)                                                                                                                                                                                                          |
+| plugin-meeting                                                                                                                                                                                                                                                                                                                                                                 | complete | ECHO (7)                                                                                                                                                                                                                     |
+| plugin-iroh-beacon                                                                                                                                                                                                                                                                                                                                                             | complete | — (off client)                                                                                                                                                                                                               |
+| plugin-observability                                                                                                                                                                                                                                                                                                                                                           | n/a      | config/telemetry (9)                                                                                                                                                                                                         |
+| plugin-registry                                                                                                                                                                                                                                                                                                                                                                | n/a      | CLI commands construct the client                                                                                                                                                                                            |
+| plugin-debug, plugin-devtools                                                                                                                                                                                                                                                                                                                                                  | n/a      | mesh/devtools (9), ECHO (7)                                                                                                                                                                                                  |
+| plugin-space (CLI), plugin-client (CLI)                                                                                                                                                                                                                                                                                                                                        | n/a      | `src/commands/**` construct the client — separate execution model                                                                                                                                                            |
+| plugin-board, -bookmarks, -chess, -chess-com, -conductor, -crm, -explorer, -file, -freeq, -heygen, -ibkr, -inbox, -kanban, -magazine, -map, -outliner, -preview, -sample, -search, -sequencer, -sheet, -spacetime, -stack, -status-bar, -studio, -support, -table, -trip, -video, -wnfs, -zen, -bluesky, -commerce, -pipeline, -routine, -native-filesystem, -sandbox, -doctor | n/a      | ECHO (7), and `/testing` (10) where present — no HALO usage                                                                                                                                                                  |
+
+## `@dxos/client` / `@dxos/react-client` usage inventory (snapshot)
+
+Import counts across `packages/plugins/*/src` + `packages/ui/*/src`
+(non-test/story), to size the elimination effort:
+
+| Import                           | Count | Track                                         |
+| -------------------------------- | ----- | --------------------------------------------- |
+| `@dxos/react-client/echo`        | 288   | ECHO (7)                                      |
+| `@dxos/client` (root)            | 102   | platform (9)                                  |
+| `@dxos/react-client/testing`     | 67    | test harness (10)                             |
+| `@dxos/react-client` (root)      | 64    | platform (9)                                  |
+| `@dxos/client/echo`              | 52    | ECHO (7)                                      |
+| `@dxos/react-client/halo`        | 8     | HALO — plugin-client + plugin-onboarding only |
+| `@dxos/client/invitations`       | 7     | invitations (8)                               |
+| `@dxos/client/edge`              | 6     | EDGE (3)                                      |
+| `@dxos/react-client/invitations` | 4     | invitations (8)                               |
+| `@dxos/react-client/mesh`        | 3     | platform (9)                                  |
+| `@dxos/client/halo`              | 3     | HALO — plugin-client + plugin-onboarding      |
+| `@dxos/react-client/devtools`    | 1     | devtools (9)                                  |
+| `@dxos/client/testing`           | 1     | test harness (10)                             |
+
+**`react-ui*` packages still importing the client** (all ECHO/root, none HALO
+after this PR): `@dxos/client` → `react-ui-editor`, `react-ui-masonry`,
+`ui-editor`; `@dxos/react-client` → `react-ui-canvas-compute`,
+`react-ui-canvas-editor`, `react-ui-chat`, `react-ui-components`,
+`react-ui-editor`, `react-ui-form`, `react-ui-markdown`, `react-ui-masonry`,
+`react-ui-mosaic`, `react-ui-table`, `react-ui-transcription`. These block on
+Missing API 7 (ECHO React bindings), not on HALO.
+
+## Status
+
+- **HALO React consumer tier: complete.**
+- **HALO imperative singleton tier: complete** except the EDGE-auth (3) and
+  script/onboarding cases.
+- **HALO remaining tier: outstanding** — Missing APIs 1–6 (identity-creation
+  verbs, recovery credential, EDGE verb, device-invitation/Shell, script write-op,
+  graph-builder atom). Only `plugin-client`, `plugin-onboarding`, `plugin-script`,
+  and the EDGE consumers (`plugin-assistant`, `plugin-connector`, `plugin-payments`)
+  still touch the client for HALO/EDGE. Tracked as task #7.
+- **Full `@dxos/client`/`@dxos/react-client` elimination: future scope** — gated on
+  Missing APIs 7–10 (ECHO React bindings dominate at ~340 imports), tracked
+  separately from this HALO PR.
+- **External blocker unchanged**: `check-packages-published` stays red until a
+  maintainer publishes the three `@dxos/halo*` packages + OIDC.

package/README.md

@@ -0,0 +1,25 @@
+# @dxos/halo
+
+DXOS HALO
+
+- [MIGRATION.md](./MIGRATION.md) — HALO → Keyhive migration plan.
+- [API_AUDIT.md](./API_AUDIT.md) — audit of HALO API usage across Composer/plugins and the proposed Effect service replacement.
+- [CONSUMER_MIGRATION.md](./CONSUMER_MIGRATION.md) — cookbook for moving consumers off `@dxos/client` onto the HALO services.
+
+## Installation
+
+```bash
+pnpm i @dxos/halo
+```
+
+## DXOS Resources
+
+- [Website](https://dxos.org)
+- [Developer Documentation](https://docs.dxos.org)
+- Talk to us on [Discord](https://dxos.org/discord)
+
+## Contributions
+
+Your ideas, issues, and code are most welcome. Please take a look at our [community code of conduct](https://github.com/dxos/dxos/blob/main/CODE_OF_CONDUCT.md), the [issue guide](https://github.com/dxos/dxos/blob/main/CONTRIBUTING.md#submitting-issues), and the [PR contribution guide](https://github.com/dxos/dxos/blob/main/CONTRIBUTING.md#submitting-prs).
+
+License: [FSL-1.1-Apache-2.0](./LICENSE) Copyright 2026 © DXOS