Verdict: Go.
Hypercore is a viable P2P data layer for Workspace across Node, macOS, and (by extension) mobile. The permissions, addressing, and discovery layers on top are designed and partially implemented.
Hypercore + Hyperswarm run cleanly under Node 22.6+ (we use --experimental-strip-types for TypeScript execution without a transpile step, which needs that version). Two runtimes on the same machine replicated a log in ~260ms via the real DHT. Corestore v7 requires a filesystem path (RocksDB-backed); :memory: is a test shim over a temp directory.
A parent process drives a NodeRuntime in a child process over line-delimited JSON-RPC on stdin/stdout. Full round-trip: init → createLog → append → get → events → shutdown. 8 integration tests, all green. The protocol is platform-neutral — the child code is unchanged regardless of who spawns it.
Swift's Process (= NSTask) spawns the Node child and speaks the same protocol without modification. The Obj-C++ TurboModule (P2PRuntimeModule.mm) is written and ready to drop into any RN-macOS project. The Swift probe passed all checks cold.
Bonus: Hypercore's append events crossed the NSTask boundary unprompted. The "zero-cost change signal" from issue #1 — a peer learning a log grew without fetching the payload — works out of the box. No extra wiring required.
wrap.ts— X25519 ECDH sealed envelopes for symmetric key deliveryseal.ts— XSalsa20-Poly1305 symmetric AEAD (seal/open) for content under a workspace/tier keyencrypted-log.ts—encryptedLog(log, key)wraps anyLogso blocks seal on append / open on get; tier-gated content rides the same replication path as ciphertextattestation.ts— root attestation sign/verify (ed25519)did.tsextensions —did:key:z6Mk…encode + decode (bidirectional)
UCAN delegation boundary module — every UCAN library call confined to one file, so a library swap stays a small change (it has already made one: UCAN 1.0 through iso-ucan replaced ucanto, ADR 0001). Surface: issueDelegation, validateDelegation (every chain link's signature, the chain to the root, a segment-bounded command and a resource policy), toBytes / fromBytes for transport, WHOLE_SECOND_FLOOR named constant for the expiry gotcha.
Two-carrier permissions delivery, sharing one envelope atom:
- Bundle (offline first-contact) —
createBundle/consumeBundlecompose wrap + ucan + attestation into the.workspaceenvelope flow, pluswriteBundleFolder/readBundleFolderfor disk round-trip. A recipient validates the attestation, unwraps the keys, joins. - Live key delivery log (#9, steady-state) —
publishDelivery/scanDeliveriesover a replicated Hypercore: an admin appends a sealed envelope addressed to a peer who joined after creation; that peer scans from a cursor, validates the UCAN against the workspace root, and unwraps. SamecreateEnvelope/consumeEnvelopeas the bundle. - Topic-layer membership auth (#10) —
verifyMembershipbinds a presented UCAN to the connection's authenticated Noise key, checks revocation, and validates the chain to the workspace root. Wired into the runtime viaCreateRuntimeOptions.auth(gate replication behind a proof exchange) +identitySeed(Noise key == DID). Verified live: members replicate, a wrong-root peer is rejected at connect.
The surface the Workspace app is built against. One object composes everything: Workspace.create (identity, K0_org, logs, bundle, topic, auth gate — one call), .open (attestation + envelope + K0_org recovery + gate + replication), .invite (sealed envelope to both carriers), .write / .entries (transparent encrypted log), .on('change'). Platform-agnostic — the runtime is injected, so the package is native-dep-free and unit-testable. v1 is single-writer; Autobase multi-writer (#11), the document/section model, and workspace:// join are deferred behind the same API. The demo:workspace runs the Acme flow end-to-end over a private swarm in ~10 lines (vs ~200 hand-wired).
110 tests green across the four packages, typecheck clean.
did:key:z6Mk… derivation from Corestore's primaryKey is now implemented (packages/p2p-runtime/src/did.ts). The format is the one UCAN delegation chains use. One keypair, one identity, no translation layer.
Nine design docs in docs/, all consistent and cross-referenced:
| Doc | Role |
|---|---|
workspace-format.md |
.workspace on-disk format, policy.json, hidden fields, external-edits watcher |
uri-scheme.md |
workspace:// URI scheme, path namespaces, locator alphabets per format |
discovery.md |
DNS TXT + .well-known/workspace for domain-based discovery |
discovery-layers.md |
Local-first / LAN / WAN peer-discovery hierarchy |
lighthouse.md |
Trusted always-on node a workspace opts into for availability |
permissions-model.md |
UCAN + Hypercore protocol, two-carrier envelope delivery, revocation, scaling |
threat-model.md |
What Workspace protects / doesn't, forward-only revocation, cooperative-client policy, audit-trail = capability-chain |
risks.md |
Failure modes, mitigations, identity-fusion migration cost, successor-chain |
ucan-prior-research.md |
UCAN library notes, gotchas, library comparison |
Validated as workable; every cryptographic component is either in production today (Autobase, Hypercore/Hyperswarm, sodium-universal, and UCAN, whose 1.0 specification is final) or has a well-trodden standards-based answer (MLS / RFC 9420 for enterprise scale). No research-grade cryptography required.
The consumer-facing view of the permissions model lives in table-file-format/docs/PERMISSIONS.md.
React Native JS
└── @workspace.sh/p2p-runtime (runtime.macos.ts)
└── SpawnedRuntime ← MacOSTransport
└── P2PRuntimeModule (Obj-C++ TurboModule)
└── NSTask → node child-bin.ts
└── NodeRuntime
└── Corestore + Hyperswarm
Per-platform JS surface (P2PRuntime interface) is identical. Only the spawning mechanism changes per platform.
On top of the runtime sits the permissions layer (wrap + UCAN + attestation + portable bootstrap), the URI addressing scheme (workspace://), and optional discovery (DNS TXT + .well-known).
Live key delivery log (#9)— implemented; remaining: scan-efficiency tuning + GC of superseded blocksTopic-layer authentication (#10)— implemented: connection-time membership gate (Noise key bound to DID, UCAN verified to root before replication); remaining: topic rotation on departure- Autobase wrapper (#11) + merge strategy (#12) — multi-writer document API
- Identity recovery / device linking (#17)
- MLS upgrade-path placeholder (#18)
- UCAN library choice ADR (#19)
.workspacefolder + archive shape (#24)- DNS discovery design (#25) — doc done; implementation pending
- LAN discovery via mDNS — designed in
docs/network/discovery-layers.md; implementation deferred (~200 lines on top of Holepunch'smulticast-dns) - PAN discovery (Bluetooth / Wi-Fi Direct / AWDL) — backlogged; revisit when mobile is in scope
- Mobile path (#6) — separate workstream
Project board: https://github.com/orgs/workspace-sh/projects/6
- Node binary on macOS — development uses the system
node; a production RN-macOS app needs a bundled static binary or an assumption that Node is present. Either is tractable. Corestore persistence— resolved (ADR 0003): the store has two forms. The RocksDB working store lives in app-private storage (macOS Application Support; mobile app containers);.workspace/store/carries an append-only serialised transport form, flushed on close/share and hydrated on open. Normative detail inworkspace-format.md§store/; app-side implementation tracked in workspace#249.
- Copy
packages/p2p-runtime→ Workspace monorepo as@workspace.sh/p2p-runtime. - Copy
packages/ucan-boundary→@workspace.sh/ucan-boundary. - Copy
packages/portable-bootstrap→@workspace.sh/portable-bootstrap. - Add
apps/macos/native/P2PRuntimeModule.h+.mmto the macOS Xcode target. - Wire
runtime.macos.tsexport in the package — Metro resolves.macos.tsautomatically. - Set
childScriptPath+nodeBinin the macOS app bootstrap. - The mobile path is a separate spike —
react-native-bare-kitreplaces the NSTask path on iOS/Android. - Lift the nine design docs into the main monorepo (or keep them in the spike repo with cross-references).