# xNet Documentation > Complete documentation for xNet, a local-first framework for building multiplayer React applications. Data lives on the device, syncs peer-to-peer via CRDTs, and works offline. No backend required. ## Important: xNet is NOT a Client-Server Architecture Before reading this documentation, understand that xNet works differently: - **No backend needed**: Data lives on the device, not a server - **No API endpoints**: Use React hooks (useQuery, useMutate) instead of fetch/axios - **No auth flows**: Identity is cryptographic (DID:key) and built-in - **No state management**: Hooks are reactive and handle this automatically - **Offline by default**: Everything works offline, syncs when online ## Table of Contents - What is xNet? - Connect Your Agent - Quick Start - Core Concepts - Agent Interfaces - Understanding xNet (For AI Assistants) - Hooks Overview - useQuery - useMutate - useNode - useIdentity - Hook Patterns - Languages & SDKs - Swift — XNetKit - Rust — xnet-core - Schemas Overview - defineSchema - Property Types - Relations - Type Inference - Extending Schemas - The xNet Protocol - Data Model (L1) - Replication (L2) - Authorization (L3) - Implement xNet in Your Language - Conformance - The Workbench - The Quiet Shell & the Desk - Tasks - Dashboards & Widgets - Chat, Presence & Calls - Notifications & Inbox - Rich Text Editor - Infinite Canvas - Forms - DevTools - Authorization - Sync Guide - Version Compatibility - Offline Patterns - Identity & Keys - Real-time Collaboration - Plugin Development - Hub Setup - Your Own Server - Use xNet From Any Framework - Connect to xNet Cloud - Electron Setup - Testing - Local-First - CRDTs - Sync Architecture - Identity Model - Cryptography - Data Model - Network & Transport - Architecture Overview - Architecture Decisions - Package Graph - Getting Started - Code Style - Testing Guide --- ## What is xNet? **In this article** - What xNet is and what problem it solves - The core mental model: three hooks, zero backend - When to use xNet (and when not to) **xNet is alpha software** Not pre-release — released, but early. The `@xnetjs/*` packages are on npm, the desktop app is downloadable, and the hub image ships. But APIs, schemas and wire formats still change between releases, sometimes without a migration path. Pin your versions, keep your own `.xnetpack` backups, and expect rough edges. ## The problem Building a modern collaborative app requires assembling a stack of 6+ services: a database, an API layer, auth, real-time sync, file storage, and deployment infrastructure. Each comes with its own SDK, its own data model, and its own failure modes. Most of this infrastructure exists to solve one problem: **getting data from one device to another**. xNet eliminates that problem entirely. ## What xNet does xNet is a **local-first framework** for React. Your data lives on the user's device. It syncs peer-to-peer via WebRTC. There is no server, no API, no database to manage. You interact with xNet through **three hooks**: | Hook | Purpose | | ------------------------------------- | ------------------------------------------------------ | | [`useQuery`](/docs/hooks/usequery/) | Read data reactively. Filter, sort, paginate. | | [`useMutate`](/docs/hooks/usemutate/) | Create, update, delete with full type safety. | | [`useNode`](/docs/hooks/usenode/) | Open a single node for collaborative editing with Yjs. | That's the entire API surface for most apps. Define a schema, use the hooks, and your app works offline, syncs in real-time, and never touches a server. ## The architecture in 30 seconds ``` Your React App └── useQuery / useMutate / useNode / useCan / useGrants └── NodeStore (schema-validated, type-safe, encrypted) ├── SQLite (OPFS in browser) / SQLite (desktop/mobile) ├── Authorization engine (PolicyEvaluator + GrantStore) └── P2P Sync (WebRTC via signaling server) └── Yjs CRDT (rich text) + Lamport LWW (structured data) ``` Everything below the hooks is invisible to you. You write React components. xNet handles storage, sync, conflict resolution, cryptographic signing, and end-to-end encryption. ## When to use xNet **Good fit:** - Productivity apps (notes, tasks, databases, wikis) - Collaborative tools (documents, whiteboards, spreadsheets) - Personal tools (journals, habit trackers, budgets) - Internal tools where you control the client - Apps where data ownership and privacy matter **Not a good fit (yet):** - Apps that need a centralized server of record (banking, e-commerce) - Apps with millions of users sharing a single dataset - Apps that need server-side rendering of user data - Apps that need complex server-side business logic ## What's in the box xNet is a monorepo of focused packages: | Package | Purpose | | ---------------- | ------------------------------------------------------------------------------------- | | `@xnetjs/react` | React hooks: `useQuery`, `useMutate`, `useNode`, `useCan`, `useGrants`, `useSecurity` | | `@xnetjs/data` | Schema system, NodeStore, 15 property types, authorization engine | | `@xnetjs/sync` | Lamport clocks, `Change` v3 (hybrid signatures), Yjs security | | `@xnetjs/crypto` | BLAKE3, Ed25519, ML-DSA-65, X25519, ML-KEM-768, XChaCha20-Poly1305 | | `@xnetjs/identity` | DID:key, HybridKeyBundle, PQ Key Registry, UCAN tokens, key recovery | | `@xnetjs/storage` | SQLite adapter | | `@xnetjs/canvas` | Infinite canvas with spatial indexing | | `@xnetjs/editor` | TipTap rich text editor | | `@xnetjs/devtools` | 9 debug panels + AuthZ panel + Security panel | For most apps, you only install `@xnetjs/react` and `@xnetjs/data`. Everything else is pulled in as needed. ## Next steps --- ## Connect Your Agent **You will learn** - How to connect a coding agent to your workspace with one command - The three lanes an agent uses, cheapest first - How writes stay safe when the app and the agent touch the same data The same way people point Claude Code at an Obsidian vault, you can point it at your **xNet workspace** — and read, search, query, and edit your pages, databases, and canvases without leaving the terminal. The [Agent Interfaces](/docs/guides/agent-interfaces/) guide covers the surfaces in depth; this one is the quick on-ramp. ## One-step connect No install needed — `npx` runs the published CLI directly: ```bash npx @xnetjs/cli connect claude-code # zero-install, project scope, read-only ``` Or, with the CLI installed (`npm install -g @xnetjs/cli`): ```bash xnet connect claude-code # project scope, read-only xnet connect claude-code --user # also install the skill for all projects xnet connect claude-code --writes # register the MCP server with write access xnet connect codex # Codex: AGENTS.md + .codex/config.toml ``` `xnet connect` is **idempotent** — it installs the `SKILL.md`, registers the xNet MCP server, writes a `CLAUDE.md`/`AGENTS.md` contract, and (with `--vault `) bootstraps a scoped checkout with an index. Re-running it reports what is already in place and changes nothing. It finishes by running `xnet doctor --agent-access`, which confirms the backend, full-text search, and signing identity are all reachable. The registered server launches however the CLI is actually available: as `xnet` when the bin is on your PATH, or as `npx -y @xnetjs/cli` after a zero-install connect — so the registration keeps working either way. ## Works whether or not the app is running The agent verbs resolve a backend automatically: 1. the desktop app's local API (`:31415`) when it is running, otherwise 2. a standalone SQLite store — discovered from the app's data directory, or pointed at explicitly with `--db ` (or `$XNET_DB`). So an agent can work against your data even with the app closed, and web-only users can point at any local store. Writes made this way are signed by a key you provide (`--key`, `$XNET_SIGNING_KEY`) or by an [enrolled agent passport](/docs/guides/identity/) (`--agent `); the CLI refuses to persist a write under a silent throwaway identity. ## Three lanes, cheapest first ```mermaid flowchart LR A[Agent in Claude Code / Codex] -->|Bash| CLI[1 · xnet CLI] A -->|Read / Edit / Grep| V[2 · Vault checkout] A -->|MCP client| M[3 · xnet mcp serve] CLI --> Core[(xNet store · signed change log)] V <-->|checkout / commit| CLI M --> Core ``` 1. **CLI** — `xnet search`/`query`/`db get` print plain stdout. Reach here first: it costs far fewer tokens than loading a wall of MCP tool schemas. 2. **Vault** — `xnet checkout --query "…"` materializes a **scoped** slice as Markdown you edit, then `xnet commit` lifts the edits back through validated mutation plans. Never check out the whole workspace. 3. **MCP** — the registered `xnet` server is the fallback for shell-less clients (Claude Desktop, browser). It is **read-only** unless you connected with `--writes`. ## Safe when the app and the agent collide The store stays the source of truth, and every edit becomes a validated plan — never a blind file-to-database sync. If the app writes a node after you checked it out, committing your now-stale vault edit surfaces a **conflict** instead of overwriting the newer value: ```bash $ xnet status conflict Pages/shared-page.md stale-export based on updatedAt:10, live is updatedAt:11 ``` Fix the file against the current value and commit again. Stale edits never silently win. ## Further reading - [Agent Interfaces](/docs/guides/agent-interfaces/) — the checkout layout, the full CLI, `SKILL.md`, and the slim MCP surface - [Identity](/docs/guides/identity/) — agent passports and signing --- ## Quick Start **You will learn** - How to define a schema with `defineSchema()` - How to query data reactively with `useQuery()` - How to create and update nodes with `useMutate()` - How offline-first works (spoiler: you don't have to do anything) ## Prerequisites - Node.js 22+ - pnpm (or npm/yarn) - Basic React knowledge ## What you'll build A task manager that works offline, syncs peer-to-peer, and persists to local SQLite storage. No server required. 1. **Create a React project and install xNet** ```bash pnpm create vite my-app --template react-ts cd my-app pnpm add @xnetjs/react @xnetjs/data ``` 2. **Define your schema** Create a file that describes the shape of your data: ```ts title="src/schema.ts" import { defineSchema, text, select, checkbox } from '@xnetjs/data' export const TaskSchema = defineSchema({ name: 'Task', namespace: 'xnet://my-app/', properties: { title: text({ required: true }), status: select({ options: [ { id: 'todo', name: 'To Do', color: '#6366f1' }, { id: 'doing', name: 'Doing', color: '#f59e0b' }, { id: 'done', name: 'Done', color: '#10b981' } ] as const }), completed: checkbox({ default: false }) } }) ``` The `as const` on the options array gives you literal type inference — `status` is typed as `'todo' | 'doing' | 'done'`, not just `string`. **Automatic timestamps** You don't need to define `createdAt` or `updatedAt` — every node gets these automatically. You can query and sort by them out of the box. 3. **Wrap your app in `XNetProvider`** The provider initializes the NodeStore, storage, and sync system: ```tsx title="src/App.tsx" import { XNetProvider } from '@xnetjs/react' import { XNetDevToolsProvider } from '@xnetjs/devtools' import { TaskList } from './TaskList' // In production, generate and persist these securely const authorDID = 'did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK' const signingKey = new Uint8Array(32) // Replace with real Ed25519 key export function App() { return ( ) } ``` **Identity in production** For a real app, use `@xnetjs/identity` to generate a DID:key pair and store it securely. The Quick Start uses hardcoded values for simplicity. 4. **Read data with `useQuery`** ```tsx title="src/TaskList.tsx" import { useQuery, useMutate } from '@xnetjs/react' import { TaskSchema } from './schema' export function TaskList() { const { data: tasks } = useQuery(TaskSchema, { orderBy: { createdAt: 'desc' } }) const { create, update, remove } = useMutate() const addTask = () => { create(TaskSchema, { title: 'New task', status: 'todo' }) } return (
    {tasks.map((task) => (
  • update(TaskSchema, task.id, { completed: !task.completed, status: task.completed ? 'todo' : 'done' }) } /> {task.title}
  • ))}
) } ``` That's it. `useQuery` returns reactive data that auto-updates when you (or a peer) mutate. `useMutate` gives you type-safe create, update, and remove methods. 5. **Run it** ```bash pnpm dev ``` Open `http://localhost:5173`. Create some tasks. Refresh the page — they persist. Open a second tab — they sync. ## What just happened Without writing a single line of backend code, you got: - **Persistent storage** — data lives in local SQLite storage, survives refreshes - **Reactive queries** — UI updates automatically when data changes - **Type safety** — `task.status` is `'todo' | 'doing' | 'done'`, not `string` - **Schema validation** — invalid data is rejected at creation time - **Offline-first** — works without any network connection - **Cryptographic signing** — every change is signed with Ed25519 ## Project structure - src/ - schema.ts defineSchema() definitions - App.tsx XNetProvider - TaskList.tsx useQuery + useMutate ## Go multiplayer in two commands Everything above is one keystroke away from being a shared app. Point the provider at a sync hub and give everyone the same room string — whoever shares the room sees the same data: ```tsx ``` To run your own hub locally (dev only — auth off accepts anyone): ```bash docker run --rm -p 4444:4444 -e HUB_AUTH=false ghcr.io/crs48/xnet-hub:latest ``` Open the app in two browser windows — changes appear in both. The room string is the entire join flow: put it in a URL (`?room=standup`) and the URL becomes an invitation. The smallest complete example of this is [`examples/minimal-app`](https://github.com/crs48/xNet/tree/main/examples/minimal-app) in the repo (~60 lines, copy-paste ready), and you can watch it run live on the [demos page](/demos/). ## Next steps Use [`useNode`](/docs/hooks/usenode/) to add a collaborative rich text editor to each task: ```tsx const { doc } = useNode(TaskSchema, taskId) // Pass doc to TipTap's Collaboration extension ``` Pass signaling servers to `XNetProvider` to sync across devices: ```tsx ``` - [Core Concepts](/docs/core-concepts/) — understand the mental model - [useQuery reference](/docs/hooks/usequery/) — filtering, sorting, pagination - [defineSchema reference](/docs/schemas/defineschema/) — all schema options - [Property Types](/docs/schemas/property-types/) — all 15 property types --- ## Core Concepts **In this article** - How data is structured (schemas and nodes) - How you interact with data (the three hooks) - How sync and conflict resolution work - How identity and signing work - How authorization and encryption work ## Schemas define your data Every piece of data in xNet is a **node**. Every node conforms to a **schema**. A schema is defined once in TypeScript and describes the shape of your data: ```ts export const ProjectSchema = defineSchema({ name: 'Project', namespace: 'xnet://my-app/', properties: { title: text({ required: true }), priority: number({ min: 1, max: 5 }), status: select({ options: [ { id: 'active', name: 'Active' }, { id: 'archived', name: 'Archived' } ] as const }) } }) ``` Schemas give you: - **Type inference** — `project.status` is `'active' | 'archived'`, not `string` - **Validation** — invalid data is rejected at creation time - **Identity** — each schema has a unique IRI like `xnet://my-app/Project` See [defineSchema](/docs/schemas/defineschema/) and [Property Types](/docs/schemas/property-types/) for full reference. ## Nodes are your data A node is an instance of a schema. When you create a task, you create a node: ```ts const { create } = useMutate() const task = await create(TaskSchema, { title: 'Ship it', status: 'todo' }) ``` Every node has system fields managed automatically by the store — you never need to define or set these yourself: | Field | Type | Description | | ----------- | --------- | --------------------------------------- | | `id` | `string` | Unique identifier (nanoid, 21 chars) | | `schemaId` | `string` | Schema IRI (e.g., `xnet://my-app/Task`) | | `createdAt` | `number` | Set automatically at creation time | | `createdBy` | `string` | Author's DID (e.g., `did:key:z6Mk...`) | | `updatedAt` | `number` | Updated automatically on every change | | `updatedBy` | `string` | Last modifier's DID | | `deleted` | `boolean` | Soft-delete flag | Your schema properties are merged alongside these fields into a **flat node** — you access `task.title` directly, not `task.properties.title`. You can filter and sort by any system field (e.g., `orderBy: { createdAt: 'desc' }`) without defining them in your schema. ## Three hooks for everything ### useQuery — read data ```tsx const { data: tasks } = useQuery(TaskSchema, { where: { status: 'todo' }, orderBy: { createdAt: 'desc' }, limit: 20 }) ``` Returns reactive data that auto-updates when the underlying store changes — whether from your own mutations, a peer's sync, or a background process. ### useMutate — write data ```tsx const { create, update, remove, restore, mutate } = useMutate() await create(TaskSchema, { title: 'New' }) await update(TaskSchema, id, { status: 'done' }) await remove(id) await restore(id) await mutate([ { type: 'create', schema: TaskSchema, data: { title: 'A' } }, { type: 'create', schema: TaskSchema, data: { title: 'B' } } ]) ``` All mutations are type-safe, validated against the schema, and automatically synced. ### useNode — edit a single node with CRDT ```tsx const { data, doc, update, syncStatus, presence } = useNode(PageSchema, pageId, { createIfMissing: { title: 'Untitled' }, did: currentUserDID }) ``` `useNode` is the powerhouse hook for collaborative editing. It gives you: - **Structured data** via `data` (the node's properties) - **A Yjs document** via `doc` (for rich text, bind to TipTap) - **Sync status** and **presence** for collaborator UI - **Automatic persistence** with debounced saves ## Two conflict resolution strategies xNet uses different strategies for different data types: | Data Type | Strategy | How It Works | | ---------------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------- | | Structured data (properties) | **Lamport LWW** (Last Writer Wins) | Each property change carries a Lamport timestamp. Higher timestamp wins. | | Rich text (documents) | **Yjs CRDT** | Character-level merge. Two users typing in the same paragraph are merged without data loss. | This dual strategy means structured fields like `title` or `status` use simple, predictable conflict resolution, while collaborative text editing uses the industry-standard Yjs CRDT for seamless merging. ## Every change is signed When you create or update a node, xNet: 1. Signs the change with a **hybrid signature** (Ed25519 + ML-DSA-65 by default) 2. Hashes the change with **BLAKE3** 3. Stores the signed change locally 4. Syncs the signed change to peers When a peer receives a change, they **verify the hybrid signature** before applying it. This means: - You can prove who made every change - Tampered data is rejected - No server is needed to enforce trust - Changes are protected against quantum forgery attacks The default **Level 1 (Hybrid)** signature carries both an Ed25519 component (64 bytes) and an ML-DSA-65 component (~3.3 KB). Both must verify — if either is invalid, the change is rejected. Level 0 (Ed25519 only) is available for high-frequency paths where the smaller signature size matters more than quantum resistance. ## Identity is a key pair Your identity in xNet is a **DID:key** — a decentralized identifier derived from an Ed25519 public key: ``` did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK ``` No accounts. No passwords. No auth server. Your key pair is your identity. You can delegate permissions to other keys using **UCAN tokens** (capability-based authorization). ## Authorization is encryption xNet enforces read access cryptographically. Every private node is encrypted with a **per-node content key**. Only users in the **recipients list** can unwrap the key and read the node — the hub never decrypts anything. You define access control in the schema itself: ```ts const TaskSchema = defineSchema({ // ... authorization: { roles: { owner: role.creator(), editor: role.property('editors') }, actions: { read: allow('owner', 'editor'), write: allow('owner', 'editor'), share: allow('owner') } } }) ``` Then check permissions in components: ```tsx const { canWrite, canShare } = useCan(taskId) const { grants, grant, revoke } = useGrants(taskId) ``` Grants are stored as ordinary nodes — they sync, replicate, and inherit the same CRDT conflict resolution as all your data. See the [Authorization Guide](/docs/guides/authorization/) for the full model including delegation, key recovery, and offline policy. ## Next steps --- ## Agent Interfaces **You will learn** - Why the filesystem is the primary agent surface - The checkout layout and how edits flow back safely - The `xnet` CLI verbs and the ~500-token SKILL.md - When to fall back to MCP ## Files first Coding agents are already excellent at reading, grepping, and editing files — so xNet's primary agent interface is a **filesystem projection of the workspace**, not a wall of tool definitions. The store stays the source of truth; the checkout is a working tree. Every surface (files, CLI, MCP) funnels into the same plan → validate → apply core, so an agent can never corrupt the workspace with a malformed write. Measured on a 15-task benchmark, the files+CLI surface completes the same work at **~0.11x the tokens** of a traditional MCP toolset (0.05x on synthesis tasks), with equal task success. The [methodology and how to reproduce it](#benchmark-methodology) are below. ## The checkout `xnet checkout` materializes a scoped slice of the workspace into a folder: ``` Pages/q3-planning.md # Markdown + YAML frontmatter (xnet.id, revision) Databases/tasks.schema.json # the schema Databases/tasks.rows.jsonl # one JSON object per line — edit/append/delete Databases/tasks.tsv # read-only fast-read sidecar (large tables) Canvases/roadmap.canvas # JSON Canvas projection SKILL.md # the agent contract (~500 tokens) .xnet/ # manifest, conflict notes ``` Filenames are semantic slugs; identity lives in frontmatter and the manifest, never in filenames. Wikilinks (`[[Title]]`), `xnet-database` blocks, and `{{xnet-ref}}` directives are live references and survive round-trips. Checkouts are **scoped and incremental** — by query, schema, kind, or node (`xnet checkout --query "roadmap"`); repeated checkouts merge. Agents never need (and are told not to) export the whole workspace. ### Edits become validated plans File edits are diffed into **mutation plans**, validated against schemas, and applied to the store — automatically with `xnet daemon` running, or on `xnet commit`. Anything that doesn't validate, or collides with a newer revision, is **quarantined as a conflict**: a Markdown note in `.xnet/conflicts/` explains what happened and how to resolve it. Stale edits never silently overwrite newer data. ## The xnet CLI | Command | Purpose | | --- | --- | | `xnet checkout` | Materialize / extend a scoped checkout | | `xnet status` | Pending plans and conflicts | | `xnet commit [--apply]` | Turn file edits into applied mutations | | `xnet search ""` | Ranked full-text search (TSV: id, slug, title, snippet) | | `xnet query --where field=value` | Query tables (TSV default; `jsonl`/`json`/`md`) | | `xnet db get/set` | Single-cell reads and writes | | `xnet run ` | Sandboxed bulk work over a bounded `api` object | | `xnet daemon` | Watch the checkout and auto-apply valid edits | | `xnet skill` | Print SKILL.md | Output is TSV-first and concise by default (`--detailed` to opt out) — built for being read by a model, not a human. `xnet run` executes scripts in a sandbox with bounded reads and **write proposals** (`api.proposeUpdate`, `api.proposeCreate`) that flow through the same validated plan pipeline as file edits. ## SKILL.md Every checkout ships a cross-harness `SKILL.md` (~500 tokens) that teaches any agent — Claude Code, Codex, Gemini CLI, Cursor — the layout and workflow above. That's the entire standing context cost, versus ~5k tokens of always-loaded tool definitions for a typical MCP server. Print it any time with `xnet skill`. ## Slim MCP MCP remains as the **no-shell fallback** for harnesses that can't run a CLI. It's deliberately slim: five stable core tools are loaded eagerly and everything else defers (the non-deferred payload is test-guarded at ≤1.5k tokens). Responses are compact JSON by default with `response_format: concise | detailed` on every tool. The doctrine, in order: **files for reading and editing, the CLI for what files can't express, MCP only when there's no shell.** ## Benchmark methodology The "~0.11x the tokens" claim comes from an in-repo, reproducible benchmark — not a one-off measurement. What it is, precisely: - **The suite**: 15 tasks (read a page, edit a page, query a database, bulk update, cross-node synthesis) run against a seeded workspace fixture. Every task really executes against the same plan → validate → apply core the product uses; **success is measured, not assumed**. - **Three surfaces**: `files-cli` (vault checkout + file tools + `xnet` CLI), `mcp-legacy` (all tool definitions standing, pretty-printed JSON), and `mcp-slim` (core tools standing, compact JSON — today's MCP fallback). - **What's counted**: a token cost model (~4 chars/token) over the *actual bytes* each surface moves through model context — standing tool/skill definitions, request arguments, tool responses, file contents read, edit diffs, CLI commands and their outputs. - **What's not counted**: model reasoning tokens. This is an **interface cost model** — it measures what each surface forces into context, not how a specific model thinks. Live harness runs with pinned versions are tracked separately (exploration 0161). - **Result**: files+CLI at 0.111x the total tokens of the legacy MCP surface overall, 0.050x on synthesis tasks, 15/15 task success on every surface. Reproduce it from a repo checkout: ```bash pnpm bench:agent-surfaces ``` Source: `packages/plugins/src/benchmarks/agent-surface-benchmark.ts`. The ratios are **regression-guarded in CI** by `agent-surface-benchmark.test.ts`, so the numbers quoted here fail the build if the surfaces drift. ## Further reading - [For AI Assistants](/docs/ai/understanding-xnet/) — the mental model for agents writing *app code* against xNet - [Plugins](/docs/guides/plugins/) — the integration layer MCP belongs to --- ## Understanding xNet (For AI Assistants) # Understanding xNet: A Guide for AI Assistants If you're an AI assistant helping a developer build with xNet, this guide will help you understand the fundamental paradigm differences. **Working inside a user's workspace?** This page is about writing *application code* against xNet. If you are an agent operating on a user's actual data — reading pages, editing databases, searching their workspace — use the **files-first agent surface** instead: a scoped checkout of the workspace plus the `xnet` CLI, taught by a ~500-token `SKILL.md` (printable with `xnet skill`). It completes the same work at roughly a tenth of the tokens of an MCP toolset. See [Agent Interfaces](/docs/guides/agent-interfaces/). ## The Key Insight **xNet has no backend.** This is not a simplification or a limitation — it's the core design principle. Data lives on the user's device and syncs peer-to-peer. ## Mental Model Comparison ### Traditional Architecture ``` User → Frontend → API → Backend → Database ↑ Auth Service ``` ### xNet Architecture ``` User → React Hooks → Local Storage ←→ P2P Sync ←→ Other Devices ↑ Cryptographic Identity (built-in) ``` ## What This Means Practically ### There Are No API Endpoints When a user asks "create an API to save tasks", the correct response is: ```typescript // Don't create this: // app.post('/api/tasks', handler) // Do this instead: const { create } = useMutate() await create(TaskSchema, { title: 'New task' }) ``` The `create` function writes to local storage. Sync happens automatically. ### There Is No Auth System to Implement When a user asks "add authentication", the correct response is: ```typescript // Don't create OAuth/JWT flows // Identity is already built-in: const { did, displayName } = useIdentity() // DID is a cryptographic identifier like: // did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK ``` ### Offline Just Works When a user asks "handle offline mode", the correct response is: ```typescript // Don't add service workers or cache layers // It already works: const { data } = useQuery(TaskSchema) // This reads from local storage // Works whether online or offline // Syncs when connectivity returns ``` ### Real-time Is Built-in When a user asks "add real-time updates", the correct response is: ```typescript // Don't create WebSocket connections // Hooks are already reactive: const { data: tasks } = useQuery(TaskSchema) // When another device syncs changes, // this component re-renders automatically ``` ## Common Mistakes to Avoid | User Request | Wrong Approach | Correct Approach | | ---------------- | ------------------ | -------------------------- | | "Save data" | Create REST API | Use `useMutate().create()` | | "Fetch data" | Use fetch/axios | Use `useQuery()` | | "Add auth" | Implement OAuth | Use `useIdentity()` | | "Handle offline" | Add service worker | Already works | | "Real-time sync" | Add WebSockets | Already built-in | | "Manage state" | Add Redux/Zustand | Hooks handle this | | "Optimistic UI" | Manual rollback | Built into mutations | ## The Schema System Schemas are central to xNet. They define data shapes AND provide type inference: ```typescript const TaskSchema = defineSchema({ name: 'Task', namespace: 'xnet://myapp/', properties: { title: text({ required: true }), status: select({ options: ['todo', 'done'] as const }), assignee: relation({ schema: 'xnet://myapp/Person' }) } }) // Now hooks are fully typed: const { data } = useQuery(TaskSchema) data[0].title // string data[0].status // 'todo' | 'done' ``` ## When to Suggest Server Code The only times server code is appropriate: 1. **Hub setup** — If deploying an always-on relay (optional) 2. **External integrations** — Webhooks, third-party APIs 3. **Heavy computation** — AI/ML that can't run on device Even then, the Hub is just a relay — it doesn't process or store application logic. ## Quick Reference ### Reading Data ```typescript // Single item const { data: task } = useQuery(TaskSchema, taskId) // All items const { data: tasks } = useQuery(TaskSchema) // Filtered const { data: todos } = useQuery(TaskSchema, { where: { status: 'todo' } }) ``` ### Writing Data ```typescript const { create, update, remove } = useMutate() // Create const id = await create(TaskSchema, { title: 'New task' }) // Update await update(TaskSchema, id, { status: 'done' }) // Delete await remove(id) ``` ### Collaborative Editing ```typescript const { data: page, doc } = useNode(PageSchema, pageId) // doc is a Y.Doc for Yjs collaborative editing ``` ### User Identity ```typescript const { did, displayName, avatarUrl } = useIdentity() // did:key:z6Mk... is the user's cryptographic identity ``` ## Summary When helping with xNet: 1. **Never suggest API endpoints** — Use hooks 2. **Never implement auth** — It's cryptographic and built-in 3. **Never manage state** — Hooks are reactive 4. **Never handle offline** — It just works 5. **Always use schemas** — They're the source of truth The paradigm shift: **data is local, sync is automatic, identity is cryptographic**. --- ## Hooks Overview **You will learn** - Which hook to use for which task - How the hooks relate to each other - The flow of data through the system ## The three core hooks | Hook | When to use it | Returns | | ------------------------------------- | ------------------------------------------------ | -------------------------------------------------- | | [`useQuery`](/docs/hooks/usequery/) | List or find nodes. Read-only. | `{ data, loading, error, reload }` | | [`useMutate`](/docs/hooks/usemutate/) | Create, update, delete nodes. | `{ create, update, remove, restore, mutate }` | | [`useNode`](/docs/hooks/usenode/) | Edit a single node with collaborative rich text. | `{ data, doc, update, syncStatus, presence, ... }` | ### When to use which - **Listing data** (tables, lists, grids, search results) — `useQuery` - **Reading a single node by ID** (detail views, cards) — `useQuery(schema, id)` - **Creating or deleting** — `useMutate` - **Updating properties** on a detail page — `useMutate().update` or `useNode().update` - **Rich text editing** (TipTap, collaborative docs) — `useNode` (gives you a `Y.Doc`) - **Showing who's online** (presence, cursors) — `useNode` (gives you `presence` and `awareness`) ### The decision tree ``` Do you need a Yjs document (rich text, canvas)? ├── Yes → useNode └── No ├── Reading data? → useQuery └── Writing data? → useMutate ``` `useNode` is the only hook that manages a Yjs document and P2P sync connection. If you don't need collaborative editing, `useQuery` + `useMutate` are simpler and more efficient. ## Supporting hooks | Hook | Purpose | | ----------------------------------------- | ------------------------------------------ | | [`useIdentity`](/docs/hooks/useidentity/) | Get the current user's DID and auth status | | `useCan` / `useGrants` | Permission checks and grant management — see the [Authorization guide](/docs/guides/authorization/) | | `useComments` | Thread-based comments on any node | | `useHistory` | Change history for a node | | `useUndo` | Undo/redo for node changes | ## All hooks require `XNetProvider` Every hook reads from a React context provided by `XNetProvider`. If you call a hook outside the provider, it throws: ```tsx function App() { return ( {/* All hooks work inside here */} ) } ``` ## Data flow ``` React Component │ ├── useQuery(TaskSchema, filter) │ └── NodeStore.list() → SQLite │ └── subscribes to NodeChangeEvents │ ├── useMutate() │ └── NodeStore.create/update/delete() │ ├── validates against schema │ ├── signs change (Ed25519) │ ├── persists to SQLite │ ├── emits NodeChangeEvent → useQuery re-renders │ └── syncs to peers (via SyncManager) │ └── useNode(PageSchema, id) ├── NodeStore (structured properties) └── Y.Doc (rich text) ├── WebRTC sync (via SyncManager or WebSocketSyncProvider) ├── debounced persistence to SQLite └── awareness (presence, cursors) ``` ## Next steps --- ## useQuery **You will learn** - The full API signature and all three overloads - How to filter, sort, and paginate results - How reactive updates work under the hood - Common gotchas and edge cases **What useQuery replaces** In a traditional React app, `useQuery` replaces: - **React Query / SWR** — reactive data fetching - **REST/GraphQL client** — API calls - **Database queries** — Prisma/Drizzle on the backend - **WebSocket subscriptions** — real-time updates With xNet, all of this is one hook. Data is local, so queries are instant. ## Quick example ```tsx function TaskList() { const { data: tasks, loading } = useQuery(TaskSchema, { where: { status: 'todo' }, orderBy: { createdAt: 'desc' }, limit: 20 }) if (loading) return

Loading...

return (
    {tasks.map((t) => (
  • {t.title}
  • ))}
) } ``` ## Signature `useQuery` has three overloads: ```ts // Overload 1: List all nodes of a schema function useQuery(schema: DefinedSchema): QueryListResult // Overload 2: Get a single node by ID function useQuery(schema: DefinedSchema, id: string): QuerySingleResult // Overload 3: Query with filters function useQuery(schema: DefinedSchema, filter: QueryFilter): QueryListResult ``` The second argument determines the overload: pass a `string` for single-node lookup, an object for filtered queries, or omit it to get all nodes. ## Parameters | Parameter | Type | Description | | --------- | ------------------ | ---------------------------------------------------------------------------------- | | `schema` | `DefinedSchema` | The schema to query. Created with [`defineSchema()`](/docs/schemas/defineschema/). | | `id` | `string` | _(Overload 2)_ Node ID to fetch. | | `filter` | `QueryFilter` | _(Overload 3)_ Filter, sort, and pagination options. | ### QueryFilter | Field | Type | Default | Description | | ---------------- | --------------------------------- | ------- | ---------------------------------------------------- | | `where` | `Partial>` | — | Filter by property values. Strict equality matching. | | `includeDeleted` | `boolean` | `false` | Include soft-deleted nodes in results. | | `orderBy` | `Record` | — | Sort by any property, `createdAt`, or `updatedAt`. | | `limit` | `number` | — | Maximum results to return. | | `offset` | `number` | — | Skip N results (for pagination). | ## Return value ### List result (overloads 1 and 3) | Field | Type | Description | | --------- | --------------- | ----------------------------------------------------------------- | | `data` | `FlatNode[]` | The query results. Properties are spread to top level. | | `loading` | `boolean` | `true` during initial load, `false` once data is available. | | `error` | `Error \| null` | Any error during query execution. | | `reload` | `() => void` | Force re-run the subscription. Rarely needed — data auto-updates. | ### Single result (overload 2) | Field | Type | Description | | --------- | --------------------- | -------------------------------------------- | | `data` | `FlatNode \| null` | The node, or `null` if not found or deleted. | | `loading` | `boolean` | `true` during initial load. | | `error` | `Error \| null` | Any error during query execution. | | `reload` | `() => void` | Force re-run the subscription. | ### FlatNode Every node includes system fields (managed automatically) plus your schema properties: ```ts interface FlatNode { id: string schemaId: string // e.g., 'xnet://my-app/Task' createdAt: number // Auto-set at creation time createdBy: string // DID of creator updatedAt: number // Auto-updated on every change updatedBy: string // DID of last modifier deleted: boolean // ... plus all your schema properties } ``` You can filter and sort by any of these system fields without defining them in your schema. ## Usage patterns ### List all nodes The simplest query — returns every node of a schema: ```tsx const { data: tasks } = useQuery(TaskSchema) // tasks: FlatNode[] ``` ### Filter and sort ```tsx const { data: activeTasks } = useQuery(TaskSchema, { where: { status: 'doing' }, orderBy: { updatedAt: 'desc' }, limit: 50 }) ``` ### Single node by ID ```tsx const { data: task } = useQuery(TaskSchema, taskId) // task: FlatNode | null ``` ### Conditional query (skip when ID is null) When `id` is null or undefined, use a guard: ```tsx function TaskDetail({ id }: { id: string | null }) { // Only query when id is available const { data: task } = useQuery(TaskSchema, id ?? '') if (!id || !task) return

No task selected

return

{task.title}

} ``` ### Pagination ```tsx const [page, setPage] = useState(0) const PAGE_SIZE = 20 const { data: tasks } = useQuery(TaskSchema, { orderBy: { createdAt: 'desc' }, limit: PAGE_SIZE, offset: page * PAGE_SIZE }) ``` ## Gotchas **Memoize your `where` object** The `where` filter uses `JSON.stringify()` for dependency tracking. If you create a new object on every render, the subscription re-fires unnecessarily. Define the filter outside the component or memoize it: ```tsx // Bad — new object every render const { data } = useQuery(TaskSchema, { where: { status: 'todo' } }) // Good — stable reference const filter = useMemo(() => ({ where: { status: 'todo' } }), []) const { data } = useQuery(TaskSchema, filter) // Also good — defined outside component const TODO_FILTER = { where: { status: 'todo' as const } } function TaskList() { const { data } = useQuery(TaskSchema, TODO_FILTER) } ``` **No loading spinners for local data** Since data is stored locally, `loading` transitions from `true` to `false` almost instantly. You usually don't need a loading state for local queries — the data is already there. **Filtering is in-memory** `where` filtering happens in JavaScript after loading from the store. For large datasets (1000+ nodes), consider using `limit` and `offset` rather than loading everything and filtering client-side. **Deleted nodes are excluded by default** Single-node queries return `null` for deleted nodes. List queries exclude deleted nodes unless you pass `includeDeleted: true`. ## Related - [`useMutate`](/docs/hooks/usemutate/) — write data that `useQuery` reads - [`useNode`](/docs/hooks/usenode/) — when you need a Yjs document for one node - [`defineSchema`](/docs/schemas/defineschema/) — define the schemas you query --- ## useMutate **You will learn** - Every method on the `useMutate` return object - How to batch operations in a transaction - How to track pending mutations - Edge cases around optimistic updates **What useMutate replaces** In a traditional app, `useMutate` replaces: - **Prisma / Drizzle** — database writes - **REST POST/PUT/DELETE** — API mutations - **Redux actions / Zustand mutations** — state updates - **Optimistic updates** — the local-first model is inherently optimistic Every mutation is validated, signed, persisted, and synced — automatically. ## Quick example ```tsx function AddTaskButton() { const { create, isPending } = useMutate() return ( ) } ``` ## Signature ```ts function useMutate(): UseMutateResult ``` Takes no parameters. Returns methods for all mutation operations. ## Return value ### Mutation methods | Method | Signature | Description | | --------- | -------------------------------------------------- | --------------------------------------------------------------------------- | | `create` | `(schema, data, id?) => Promise` | Create a new node. Returns the created node or `null` if store isn't ready. | | `update` | `(schema, id, data) => Promise` | Update properties. Only changed fields are written. | | `remove` | `(id) => Promise` | Soft-delete a node. Recoverable via `restore`. | | `restore` | `(id) => Promise` | Restore a soft-deleted node. | | `mutate` | `(ops[]) => Promise` | Execute a batch of operations through the active data bridge. | ### Status fields | Field | Type | Description | | -------------- | --------- | ---------------------------------------------- | | `isPending` | `boolean` | `true` if any mutation is currently in flight. | | `pendingCount` | `number` | Number of concurrent mutations in flight. | ## Usage patterns ### Basic CRUD ```tsx const { create, update, remove, restore } = useMutate() // Create const task = await create(TaskSchema, { title: 'Ship v1', status: 'todo' }) // Update (sparse — only changed fields) await update(TaskSchema, task.id, { status: 'doing' }) // Soft-delete await remove(task.id) // Restore await restore(task.id) ``` ### Custom ID Pass an optional third argument to `create` to specify the node ID: ```tsx const task = await create(TaskSchema, { title: 'Known ID' }, 'my-custom-id') // task.id === 'my-custom-id' ``` ### Transactions (batch operations) Use `mutate()` to execute multiple operations in one call: ```tsx const { mutate } = useMutate() const result = await mutate([ { type: 'create', schema: TaskSchema, data: { title: 'Task A' } }, { type: 'create', schema: TaskSchema, data: { title: 'Task B' } }, { type: 'update', id: existingId, data: { status: 'done' } }, { type: 'delete', id: oldTaskId } ]) ``` ### MutateResult ```ts interface MutateResult { results: (NodeState | null)[] // One result per operation (null for deletes) } ``` ### Form integration ```tsx function TaskForm({ taskId }: { taskId: string }) { const { data: task } = useQuery(TaskSchema, taskId) const { update } = useMutate() const [title, setTitle] = useState('') useEffect(() => { if (task) setTitle(task.title) }, [task]) const save = () => update(TaskSchema, taskId, { title }) return (
{ e.preventDefault() save() }} > setTitle(e.target.value)} />
) } ``` ### Tracking pending state ```tsx const { create, isPending, pendingCount } = useMutate() // Disable UI during mutations // Show count for batch operations {pendingCount > 0 && {pendingCount} operations pending...} ``` ## Gotchas **`null` means the store isn't ready** All mutation methods return `null` if the NodeStore hasn't initialized yet (e.g., `XNetProvider` is still mounting). This is rare but possible if you call a mutation immediately on mount. **Updates are sparse** `update()` only writes the fields you pass. Other properties are untouched. This is important for conflict resolution — you're only claiming ownership of the fields you change. ```tsx // This only updates `status`, not `title` await update(TaskSchema, id, { status: 'done' }) ``` **Mutations trigger useQuery updates** When you call `create`, `update`, `remove`, or `restore`, the NodeStore emits a `NodeChangeEvent`. Any `useQuery` hook watching the same schema will automatically re-render with the new data. You don't need to manually invalidate queries. ## Related - [`useQuery`](/docs/hooks/usequery/) — read the data you mutate - [`useNode`](/docs/hooks/usenode/) — alternative for single-node editing with Yjs - [`defineSchema`](/docs/schemas/defineschema/) — define the schemas you write to --- ## useNode **You will learn** - All options and the full return type (grouped by category) - How to bind a Yjs document to TipTap - How the dual-write model works (NodeStore + Y.Doc) - Sync lifecycle, presence, and error handling **What useNode replaces** In a traditional app, `useNode` replaces: - **WebSocket connection** — real-time sync per document - **Yjs provider setup** — WebRTC/WebSocket provider, awareness, persistence - **Autosave logic** — debounced persistence - **Presence system** — who's online, cursor positions - **Document loading** — fetch, cache, conflict handling One hook. All of it. ## Quick example ```tsx function PageEditor({ pageId }: { pageId: string }) { const { data, doc, update, syncStatus, presence } = useNode(PageSchema, pageId, { createIfMissing: { title: 'Untitled' }, did: currentUserDID }) const editor = useEditor( { extensions: [ // ... your extensions Collaboration.configure({ document: doc }) ] }, [doc] ) if (!data) return

Loading...

return (
update({ title: e.target.value })} />
{syncStatus === 'connected' ? `${presence.length} collaborator(s)` : syncStatus}
) } ``` ## Signature ```ts function useNode>( schema: DefinedSchema, id: string | null, options?: UseNodeOptions ): UseNodeResult ``` Passing `null` for `id` disables the hook — `data` and `doc` will be `null`. ## Parameters | Parameter | Type | Description | | --------- | ------------------- | -------------------------------------------------------------------- | | `schema` | `DefinedSchema` | The schema for this node. Must have `document: 'yjs'` for rich text. | | `id` | `string \| null` | The node ID to load. `null` disables the hook. | | `options` | `UseNodeOptions` | Configuration for sync, persistence, and auto-creation. | ### UseNodeOptions | Option | Type | Default | Description | | ------------------ | --------------------- | ------------------------- | ------------------------------------------------------- | | `signalingServers` | `string[]` | `['ws://localhost:4444']` | WebSocket servers for peer discovery. | | `disableSync` | `boolean` | `false` | Disable P2P sync (local-only mode). | | `persistDebounce` | `number` | `1000` | Milliseconds to debounce Y.Doc saves to storage. | | `createIfMissing` | `InferCreateProps` | — | Auto-create the node if it doesn't exist. | | `did` | `string` | — | User's DID for presence awareness (cursors, user list). | ## Return value ### Data | Field | Type | Description | | ------ | --------------------- | ---------------------------------------------------------------------------------- | | `data` | `FlatNode \| null` | The node's structured properties (flattened). `null` if loading or not found. | | `doc` | `Y.Doc \| null` | Yjs document for collaborative editing. `null` if schema has no `document: 'yjs'`. | ### Mutations | Field | Type | Description | | -------- | -------------------------------------------------------- | ------------------------------------------------------------------------------- | | `update` | `(props: Partial>) => Promise` | Update structured properties. Dual-writes to both NodeStore and Y.Doc meta map. | | `remove` | `() => Promise` | Soft-delete this node. | ### State | Field | Type | Description | | ------------- | ---------------- | -------------------------------------------------------------------- | | `loading` | `boolean` | `true` during initial load. | | `error` | `Error \| null` | Any error during loading, sync, or persistence. | | `isDirty` | `boolean` | `true` if the Y.Doc has unsaved changes (debounce timer is pending). | | `lastSavedAt` | `number \| null` | Timestamp of last successful persistence. | | `wasCreated` | `boolean` | `true` if the node was auto-created via `createIfMissing`. | ### Sync | Field | Type | Description | | ------------ | ---------------- | ------------------------------------------------------------ | | `syncStatus` | `SyncStatus` | `'offline' \| 'connecting' \| 'connected' \| 'error'` | | `syncError` | `string \| null` | Human-readable error message when `syncStatus` is `'error'`. | | `peerCount` | `number` | Number of currently connected peers editing this document. | ### Presence | Field | Type | Description | | ----------- | ------------------- | --------------------------------------------------------------------------------------------------------------------- | | `presence` | `PresenceUser[]` | Other users from live awareness + hub snapshots. Each has `did`, optional `name`, `color`, `lastSeen`, and `isStale`. | | `awareness` | `Awareness \| null` | Yjs Awareness instance. Pass to TipTap's `CollaborationCursor` extension. | ### Actions | Field | Type | Description | | -------- | --------------------- | ------------------------------------------------------- | | `save` | `() => Promise` | Manually flush pending changes (bypass debounce timer). | | `reload` | `() => Promise` | Reload node and document from storage. | ## Usage patterns ### Structured properties only (no rich text) If your schema doesn't have `document: 'yjs'`, `doc` will be `null` and useNode behaves like a single-node version of useQuery + useMutate: ```tsx const { data, update } = useNode(TaskSchema, taskId) // Update properties await update({ status: 'done', title: 'Shipped!' }) ``` ### Rich text with TipTap ```tsx const { doc, awareness, presence } = useNode(PageSchema, id, { did }) const editor = useEditor( { extensions: [ StarterKit.configure({ history: false }), // Disable built-in history Collaboration.configure({ document: doc }), CollaborationCursor.configure({ provider: awareness, user: { name: 'You', color: '#6366f1' } }) ] }, [doc] ) ``` **Disable TipTap's built-in history** When using `Collaboration`, you must disable TipTap's built-in `history` extension. Yjs has its own undo manager. Using both causes conflicts. ### Presence awareness Pass `did` to enable presence. Users are reported with a deterministic color derived from their DID: ```tsx const { presence, syncStatus } = useNode(PageSchema, id, { did: currentUserDID }) return (
{presence.map((user) => ( {user.did.slice(8, 16)}... ))} {syncStatus}
) ``` ### Auto-create with `createIfMissing` For "new document" flows, pass default properties. If the node doesn't exist, it's created automatically: ```tsx const { data, wasCreated } = useNode(PageSchema, newPageId, { createIfMissing: { title: 'Untitled', content: '' } }) if (wasCreated) { // Focus the title input, show onboarding, etc. } ``` If the node exists but is soft-deleted, `createIfMissing` restores it instead of creating a duplicate. ### Manual save The debounced persistence timer (default: 1000ms) means there's a window where changes exist in memory but not on disk. For critical moments, flush manually: ```tsx const { save, isDirty } = useNode(PageSchema, id) const handleNavigateAway = async () => { if (isDirty) await save() router.push('/home') } ``` ## The dual-write model This is the most important thing to understand about `useNode`: When you call `update({ title: 'New Title' })`, it writes to **two places**: 1. **NodeStore** — structured data with Lamport timestamps (for `useQuery` and persistence) 2. **Y.Doc meta map** — a `Y.Map('meta')` inside the Yjs document (for P2P sync) When a remote peer changes the Y.Doc meta map, a `metaObserver` picks up the change and writes it back to the NodeStore. This bidirectional bridge keeps both stores in sync. **Direct Y.Doc edits don't update NodeStore** If you modify the Y.Doc's text content directly (e.g., via TipTap), that content syncs fine through Yjs. But if you modify the Y.Doc's `meta` map directly (bypassing `update()`), the change will NOT be written to the NodeStore unless it comes from a remote peer. Always use the `update()` method for structured properties. ## Lifecycle 1. **Mount** — NodeStore lookup. If not found and `createIfMissing` is set, create the node. 2. **Init Y.Doc** — If schema has `document: 'yjs'`, load stored content and initialize the Yjs document. 3. **Connect** — Acquire a sync connection from `SyncManager` (or create a `WebSocketSyncProvider` as fallback). 4. **Editing** — User and peer changes flow through Yjs CRDT. Property changes go through the dual-write bridge. 5. **Persist** — Y.Doc changes are debounced and saved to SQLite as `Y.encodeStateAsUpdate()`. 6. **Unmount** — Flush all pending changes immediately, release the sync connection. **Navigation flush** When the component unmounts, `useNode` immediately flushes the Y.Doc to storage. If you navigate back to the same node quickly, the new instance waits for the previous flush to complete before loading. This prevents data loss but can cause a brief delay. ## Gotchas **Pass `did` for presence** Without the `did` option, awareness broadcasts are disabled and presence data is usually empty: ```tsx const { did } = useIdentity() const { presence } = useNode(PageSchema, id, { did }) ``` **Sync timeout on new documents** When `wasCreated` is true (you're joining a shared document that was created by someone else), a 10-second timeout checks if any sync content was received. If not, `syncStatus` changes to `'error'` with a descriptive message. This helps surface connectivity issues. **Debug logging** Enable sync debug logs in the browser console: ```js localStorage.setItem('xnet:sync:debug', 'true') ``` ## Related - [`useQuery`](/docs/hooks/usequery/) — for reading multiple nodes (no Yjs) - [`useMutate`](/docs/hooks/usemutate/) — for mutations without a Yjs document - [`useIdentity`](/docs/hooks/useidentity/) — get the current DID for presence - [Collaboration guide](/docs/guides/collaboration/) — full walkthrough of building a collaborative editor --- ## useIdentity **You will learn** - How to access the current user's identity - The difference between `identity`, `did`, and `isAuthenticated` ## Quick example ```tsx function UserBadge() { const { did, isAuthenticated } = useIdentity() if (!isAuthenticated) return

Not signed in

return

Signed in as {did?.slice(0, 20)}...

} ``` ## Signature ```ts function useIdentity(): UseIdentityResult ``` Takes no parameters. Reads from the `XNetProvider` context. ## Return value | Field | Type | Description | | ----------------- | ------------------ | --------------------------------------------------------------------- | | `identity` | `Identity \| null` | The full Identity object from `XNetProvider` config, or `null`. | | `isAuthenticated` | `boolean` | `true` if either `identity` or `authorDID` is set. | | `did` | `string \| null` | The user's DID. Resolved from `identity.did` first, then `authorDID`. | ## Usage patterns ### Pass DID to useNode for presence ```tsx const { did } = useIdentity() const { presence } = useNode(PageSchema, pageId, { did: did ?? undefined }) ``` ### Conditional rendering ```tsx const { isAuthenticated } = useIdentity() if (!isAuthenticated) { return } return ``` ## Gotchas **`isAuthenticated` doesn't mean full identity** `isAuthenticated` is `true` if either `identity` or `authorDID` was passed to `XNetProvider`. You can be "authenticated" with just a DID and no full Identity object — this is common during development. **Throws outside XNetProvider** Like all xNet hooks, `useIdentity` throws if called outside `XNetProvider`. ## Related - [`useNode`](/docs/hooks/usenode/) — pass `did` for presence awareness - [Identity guide](/docs/guides/identity/) — generating and managing key pairs --- ## Hook Patterns **You will learn** - Patterns for combining hooks effectively - Performance tips and memoization - Error handling strategies - Testing approaches ## List + detail pattern The most common pattern: a list view with a detail editor. ```tsx function App() { const [selectedId, setSelectedId] = useState(null) return (
{selectedId && }
) } function TaskList({ onSelect }: { onSelect: (id: string) => void }) { const { data: tasks } = useQuery(TaskSchema, { orderBy: { createdAt: 'desc' } }) return (
    {tasks.map((task) => (
  • onSelect(task.id)}> {task.title}
  • ))}
) } function TaskDetail({ id }: { id: string }) { const { data, doc, update } = useNode(TaskSchema, id) if (!data) return null return (
update({ title: e.target.value })} /> {doc && }
) } ``` ## Create and navigate Create a node and immediately navigate to it: ```tsx function NewPageButton() { const { create } = useMutate() const navigate = useNavigate() const handleCreate = async () => { const page = await create(PageSchema, { title: 'Untitled' }) if (page) navigate(`/pages/${page.id}`) } return } ``` ## Stable filter references Avoid re-creating filter objects on every render: ```tsx // Option 1: Module-level constant const ACTIVE_FILTER = { where: { status: 'active' as const }, orderBy: { updatedAt: 'desc' as const } } satisfies QueryFilter function ActiveProjects() { const { data } = useQuery(ProjectSchema, ACTIVE_FILTER) // ... } // Option 2: useMemo for dynamic filters function FilteredTasks({ status }: { status: string }) { const filter = useMemo(() => ({ where: { status } }), [status]) const { data } = useQuery(TaskSchema, filter) // ... } ``` ## Debounced updates For frequently changing values (like text inputs), debounce the update: ```tsx function TitleInput({ id }: { id: string }) { const { data, update } = useNode(TaskSchema, id) const [local, setLocal] = useState(data?.title ?? '') const timeoutRef = useRef() // Sync from remote changes useEffect(() => { if (data?.title !== undefined) setLocal(data.title) }, [data?.title]) const handleChange = (e: React.ChangeEvent) => { const value = e.target.value setLocal(value) clearTimeout(timeoutRef.current) timeoutRef.current = window.setTimeout(() => { update({ title: value }) }, 300) } return } ``` ## Error boundaries Wrap xNet-powered components in error boundaries for resilience: ```tsx function App() { return ( Something went wrong

}> ) } ``` ## Conditional hooks When you might not have an ID yet: ```tsx // useNode accepts null to disable function MaybeEditor({ id }: { id: string | null }) { const { data } = useNode(PageSchema, id) if (!data) return

Select a page

return } ``` ## Sync status indicator A reusable component showing connection state: ```tsx function SyncIndicator({ id }: { id: string }) { const { syncStatus, peerCount, syncError } = useNode(PageSchema, id) const statusMap = { offline: { color: 'gray', label: 'Offline' }, connecting: { color: 'yellow', label: 'Connecting...' }, connected: { color: 'green', label: `${peerCount} peer(s)` }, error: { color: 'red', label: syncError ?? 'Error' } } const { color, label } = statusMap[syncStatus] return {label} } ``` ## Related - [`useQuery`](/docs/hooks/usequery/) — reading data - [`useMutate`](/docs/hooks/usemutate/) — writing data - [`useNode`](/docs/hooks/usenode/) — collaborative editing --- ## Languages & SDKs xNet is a **protocol** first and an app second. The same signed, hash-chained, last-write-wins data model can be implemented — and **proven byte-for-byte** — in more than one language, and the JavaScript runtime binds to more than one UI framework. This page is the honest map of what exists today and how mature it is. Every implementation below passes the **same [golden vectors](/docs/protocol/conformance/)**: identity (`did:key`), the canonical-JSON BLAKE3 change hash, signing, and LWW convergence. That shared corpus is the difference between "supported" and "verifiably interoperable." ## The two axes There are two different "multi-X" stories, and they mean different things: - **Languages** implement the [protocol](/docs/protocol/overview/) (identity, change hashing, replication, authorization) and interoperate over the wire. - **JavaScript UI frameworks** bind the same JS [runtime](/docs/architecture/package-graph/) (`createXNetClient` + `liveQuery`) into React, Vue, Svelte, or Solid. ## Maturity matrix What the badges mean: the canonical implementation the vectors are generated from · first-class and app-ready · real and conformance-pinned, still evolving · a thin binding published when asked for · a verifier / teaching implementation. ### Languages | Language | What you get | Maturity | Where | | ---------------- | ---------------------------------------------------------------- | --------------------------------------------------- | ---------------------------------------------------------- | | **TypeScript** | The full runtime + React SDK, published to npm | | [Quickstart](/docs/quickstart/) | | **Swift** | Native SDK — schemas, store, query, SwiftUI live binding, SQLite | | [Swift](/docs/languages/swift/) | | **Rust** | Portable interop kernel + C/UniFFI binding surface | | [Rust](/docs/languages/rust/) | | **Python** | ~100-line reference kernel + vector verifier | | [Implement it](/docs/protocol/implement-in-your-language/) | | **Any language** | Build a conforming impl from the spec + vectors | | [Implement it](/docs/protocol/implement-in-your-language/) | ### JavaScript UI frameworks | Framework | What you get | Maturity | Where | | --------------------------- | ---------------------------------------------------------- | ------------------------------------------------------ | -------------------------------------- | | **React** | Hooks **and** components — the toolkit the app itself uses | | [React hooks](/docs/hooks/overview/) | | **Vue** | `useQuery` / `useMutate` data binding (no components) | | [Frameworks](/docs/guides/frameworks/) | | **Svelte** | `liveQuery` is already a Svelte store | | [Frameworks](/docs/guides/frameworks/) | | **Solid** | `createQuery` via `from()` | | [Frameworks](/docs/guides/frameworks/) | | **Vanilla / Lit / Angular** | Subscribe to `liveQuery` directly | | [Frameworks](/docs/guides/frameworks/) | Only **React** ships UI components; the component kit is React by design (see the [framework support policy](/docs/guides/frameworks/)). The Swift and Rust packages live **in the repo** (SwiftPM / Cargo), not on a public registry yet — the per-language pages show how to depend on them today. ## Pick your path --- ## Swift — XNetKit

[**XNetKit**](https://github.com/crs48/xNet/tree/main/swift/XNetKit) is a native Swift SDK for xNet's local-first graph database. Define schemas in Swift, write and query the database in Swift, and bind results into a SwiftUI re-rendering loop — no JavaScript, no React. It's built directly on the conformance-pinned [protocol kernel](/docs/protocol/overview/), so it interoperates with the TypeScript reference **byte-for-byte** where it matters: identity, canonical change hashes, and LWW convergence. ## Quick look ```swift // Identity — an Ed25519 did:key (would live in the Keychain in a real app). let me = Identity() // Define a schema in Swift (the analogue of TS `defineSchema`). let Task = Schema(name: "Task", namespace: "xnet://xnet.fyi/", authorization: .spaceCascade(relation: "space")) { text("title", required: true, maxLength: 200) select("status", options: ["todo", "doing", "done"], default: "todo") relation("space", target: "xnet://xnet.fyi/Space@1.0.0") money("bounty", currency: "USD") } Task.id // "xnet://xnet.fyi/Task@1.0.0" // A local store owned by `me`. Every write signs a Change and folds it via LWW. // Pass a SQLiteChangeLog to persist — state replays from it on next launch. let store = NodeStore(identity: me, persistence: SQLiteChangeLog(path: dbPath)) let task = store.create(Task, ["title": "Ship the Swift SDK", "status": "todo"]) store.update(task.id, ["status": "doing"]) // Query the database in Swift. let todo = store.query(Query(Task, where: .equals("status", "todo")).ordered(by: "title")) ``` ## The native re-render loop (SwiftUI) `LiveQueryModel` is an `@Observable` analogue of React's `useQuery`: a SwiftUI view reads `model.rows` and re-renders automatically whenever the result changes — no hooks, no manual subscriptions. ```swift struct TaskListView: View { @State private var model: LiveQueryModel init(store: NodeStore, schema: Schema) { _model = State(initialValue: LiveQueryModel( store, Query(schema, where: .equals("status", "todo")).ordered(by: "title"))) } var body: some View { List(model.rows) { node in Text(node["title"]?.stringValue ?? "") } } } ``` Headless, the same reactivity is the framework-agnostic `LiveQuery` — `subscribe(_:)` fires immediately and on every change, a 1:1 port of [`packages/runtime/src/live-query.ts`](https://github.com/crs48/xNet/blob/main/packages/runtime/src/live-query.ts). ## Live sync with an xNet hub `HubConnection` speaks the L2 [replication wire protocol](/docs/protocol/replication/) over a WebSocket — and it's proven against the **real TypeScript hub**. The `xnet-sync-demo` target has a Swift client sign a change, publish it to the hub (which verifies the hash + Ed25519 signature), a second Swift client catch up and materialize the node, then receive a **live relayed update** the moment the writer publishes — a true cross-language, real-time round-trip. ```swift let conn = HubConnection(url: URL(string: "wss://hub.xnet.app")!, did: identity.did) try await conn.connect() store.onLocalChange = { change in Task { try await conn.publish(change, room: docId) } } conn.onRemoteChange = { change in store.apply(change) } // verifies hash + signature try await conn.subscribe(room: docId) conn.startStreaming() ``` ## Install XNetKit is a SwiftPM package that lives **in the repository** (not yet on a public index). Platforms: macOS 14, iOS 17, visionOS 1. 1. Add it as a local or git package dependency in your `Package.swift`: ```swift dependencies: [ .package(url: "https://github.com/crs48/xNet.git", branch: "main") // then reference the "XNetKit" product from swift/XNetKit ] ``` 2. Build and run the bundled demos: ```bash cd swift/XNetKit swift run xnet-demo # schema → signed writes → query → reactive loop swift test # 18 tests incl. golden vectors, wire codec, persistence ``` ## Scope & status XNetKit covers identity, schemas, signed-change + LWW store, query, the SwiftUI live binding, SQLite persistence, and **live node-change hub sync**. The collaborative **Yjs rich-text document body** is the remaining piece — it travels the wire as opaque bytes, so a Swift node can relay and store it, but in-Swift CRDT editing is future work. See [exploration 0210](https://github.com/crs48/xNet/blob/main/docs/explorations/0210_%5B_%5D_NATIVE_SWIFT_SDK_AND_PORTABLE_MULTI_LANGUAGE_CORE.md). --- ## Rust — xnet-core

[**xnet-core**](https://github.com/crs48/xNet/tree/main/rust/xnet-core) is a portable Rust implementation of the xNet **interop kernel** — the byte-exact core of the [protocol](/docs/protocol/overview/): `did:key` identity, the canonical-JSON change hash, Ed25519 sign/verify, per-property LWW convergence, and the pure L2/L3 decision functions (version negotiation, authorization expression evaluation). Unlike a full app SDK, `xnet-core` is the **kernel + a binding surface**. It's Phase 2 of [exploration 0210](https://github.com/crs48/xNet/blob/main/docs/explorations/0210_%5B_%5D_NATIVE_SWIFT_SDK_AND_PORTABLE_MULTI_LANGUAGE_CORE.md): one portable core that can back the Swift, Kotlin, and .NET SDKs via UniFFI / a C ABI, instead of each language re-implementing the kernel. ## Conformance `cargo test` runs the **shared golden-vector corpus** ([`conformance/vectors/`](/docs/protocol/conformance/)) — the same vectors the TypeScript reference and the Python/Swift kernels pass: ```text test l0_identity ... ok # did:key derivation + round-trip test l1_change ... ok # canonical JSON, BLAKE3 hash, verify, AND re-sign test l1_lww ... ok # per-property LWW convergence test l2_replication ... ok # version-handshake negotiation + catch-up filter test l3_authz ... ok # authorization expression-AST evaluation ``` `xnet-core` reproduces a TypeScript-produced signature **exactly** — Ed25519 here is the deterministic RFC-8032 construction on `curve25519-dalek` + `sha2`, so the only crypto dependencies are audited group-math and hash primitives (base58btc and canonical JSON are inline). That makes Rust a candidate for **regenerating** the golden vectors, not just verifying them. ```bash cd rust/xnet-core cargo test # 5 conformance suites + 1 FFI round-trip ``` ## The binding surface [`src/ffi.rs`](https://github.com/crs48/xNet/blob/main/rust/xnet-core/src/ffi.rs) exposes the kernel across a `String` / `Vec` / `bool` boundary — the shape a UniFFI or C-ABI consumer wants — so a native SDK (Swift, Kotlin, .NET) can call the verified kernel instead of porting it. The crate is dependency-light by design: ```toml [dependencies] curve25519-dalek = "4.1" # RFC-8032 Ed25519 (deterministic) sha2 = "0.10" blake3 = "1" # the change-hash digest serde_json = "1" ``` ## Scope & status xnet-core is the **L0/L1 + L2/L3 decision core** — identity, change hashing, LWW, and the pure decision functions. It is not (yet) an application SDK with storage, a live-sync transport, or a query engine; those live in the native SDKs it's meant to back. The crate lives **in the repository** (not yet on crates.io). --- ## Schemas Overview **In this article** - What schemas are and why they matter - The relationship between schemas, nodes, and hooks - How type inference flows from schema to component ## What is a schema? A schema is a TypeScript definition that describes the shape of your data. Every node in xNet conforms to a schema. ```ts export const TaskSchema = defineSchema({ name: 'Task', namespace: 'xnet://my-app/', properties: { title: text({ required: true }), status: select({ options: [ { id: 'todo', name: 'To Do' }, { id: 'done', name: 'Done' } ] as const }), dueDate: date({ includeTime: true }) } }) ``` This gives you: - **Type safety** — `task.status` is `'todo' | 'done'`, not `string` - **Validation** — required fields are enforced, values are range-checked - **Identity** — the schema has a unique IRI: `xnet://my-app/Task` - **Coercion** — values are normalized on creation (trimming, type conversion) ## Schemas are the source of truth The type inference flows from schema definition through every hook: ``` defineSchema({ properties: { title: text(), ... } }) ↓ useQuery(TaskSchema) → { data: { id, title, ... }[] } useMutate().create(TaskSchema, { title: '...' }) useNode(TaskSchema, id) → { data: { id, title, ... } } ``` You define types once. Every hook infers from the schema. ## Schema anatomy Every schema has: | Field | Required | Description | | ------------ | -------- | ------------------------------------------------------------- | | `name` | Yes | Display name (e.g., `'Task'`, `'Page'`). | | `namespace` | Yes | Must match `` `xnet://${string}/` ``. Groups related schemas. | | `properties` | Yes | Record of property builders (e.g., `text()`, `select()`). | | `extends` | No | Parent schema to inherit properties from. | | `document` | No | CRDT document type: `'yjs'` for rich text editing. | The schema IRI is computed as `${namespace}${name}` — e.g., `xnet://my-app/Task`. ## Next steps --- ## defineSchema **You will learn** - The full `defineSchema()` API - All options and what they do - What a `DefinedSchema` gives you - How validation and coercion work ## Quick example ```ts export const TaskSchema = defineSchema({ name: 'Task', namespace: 'xnet://my-app/', properties: { title: text({ required: true, maxLength: 500 }), status: select({ options: [ { id: 'todo', name: 'To Do', color: '#6366f1' }, { id: 'doing', name: 'Doing', color: '#f59e0b' }, { id: 'done', name: 'Done', color: '#10b981' } ] as const }), completed: checkbox({ default: false }), project: relation({ target: 'xnet://my-app/Project' }) } }) ``` **Automatic fields** Every node automatically gets `id`, `schemaId`, `createdAt`, `updatedAt`, `createdBy`, and `updatedBy`. You don't need to define these in your schema — they're managed by the store and available on every node when you read it. ## Signature ```ts function defineSchema>( options: DefineSchemaOptions ): DefinedSchema ``` ## Options | Field | Type | Required | Description | | --------------- | --------------------------------- | -------- | ---------------------------------------------------------------------------------------- | | `name` | `string` | Yes | Schema name (e.g., `'Task'`). Used in the schema IRI. | | `namespace` | `` `xnet://${string}/` `` | Yes | Namespace for grouping. Must end with `/`. | | `properties` | `Record` | Yes | Property definitions using builder functions. | | `extends` | `DefinedSchema` | No | Parent schema to inherit properties from. | | `document` | `'yjs' \| 'automerge'` | No | CRDT document type. Required for [`useNode`](/docs/hooks/usenode/) rich text. | | `authorization` | `AuthorizationBlock` | No | Roles, actions, and encryption policy. See [Authorization](/docs/guides/authorization/). | ### Schema IRI The schema's unique identifier is `${namespace}${name}`: ```ts defineSchema({ name: 'Task', namespace: 'xnet://my-app/' }) // Schema IRI: 'xnet://my-app/Task' ``` Each property also gets an IRI: `${schemaId}#${propertyName}`: ``` xnet://my-app/Task#title xnet://my-app/Task#status ``` ## Return value: DefinedSchema | Field/Method | Type | Description | | ------------------------ | ------------------------------- | ------------------------------------------------- | | `schema` | `Schema` | The JSON-LD compatible schema object. | | `validate(node)` | `(unknown) => ValidationResult` | Validate a node against this schema. | | `create(props, options)` | `(props, options) => Node` | Create a new node (used internally). | | `is(node)` | `(node) => boolean` | Type guard — check if a node matches this schema. | | `_schemaId` | `string` | The computed schema IRI. | | `_properties` | `P` | Property builders (for type inference). | ### ValidationResult ```ts interface ValidationResult { valid: boolean errors: ValidationError[] // { path, message, value? } } ``` Validation checks: - Required system fields (`id`, `schemaId`, `createdAt`, `createdBy`) - `schemaId` matches the schema - `createdBy` starts with `did:key:` - Each property's constraints (required, min/max, pattern, etc.) ## Adding authorization Add an `authorization` block to define who can read, write, delete, and share nodes of this schema. The mutation policy can optionally be split into `create` (who may add nodes) and `update` (who may modify existing ones) — each falls back to `write` when not declared: ```ts export const TaskSchema = defineSchema({ name: 'Task', namespace: 'xnet://my-app/', properties: { title: text({ required: true }), assignee: person(), project: relation({ target: 'xnet://my-app/Project' as const }) }, authorization: { roles: { owner: role.creator(), assignee: role.property('assignee'), admin: role.relation('project', 'admin') }, actions: { read: allow('owner', 'assignee', 'admin'), write: allow('owner', 'admin'), delete: allow('owner', 'admin'), share: allow('owner', 'admin') }, publicProps: ['title'] // these fields are readable without decryption } }) ``` Nodes are encrypted with a **per-node content key** and only users in the recipient list can decrypt them. The hub stores encrypted envelopes and filters queries by recipient list without ever decrypting content. See the [Authorization Guide](/docs/guides/authorization/) for the full model including presets, `useCan`, `useGrants`, delegation, and key recovery. ## Adding rich text support Add `document: 'yjs'` to enable collaborative editing via [`useNode`](/docs/hooks/usenode/): ```ts export const PageSchema = defineSchema({ name: 'Page', namespace: 'xnet://my-app/', properties: { title: text({ required: true }), icon: text() }, document: 'yjs' }) ``` When `document: 'yjs'` is set, `useNode` creates a `Y.Doc` for the node and manages P2P sync for its content. ## Schema inheritance Use `extends` to inherit properties from a parent schema: ```ts const BaseSchema = defineSchema({ name: 'Base', namespace: 'xnet://my-app/', properties: { title: text({ required: true }), tags: multiSelect({ options: ['draft', 'published'] as const }) } }) const ArticleSchema = defineSchema({ name: 'Article', namespace: 'xnet://my-app/', extends: BaseSchema, properties: { body: text(), publishedAt: date() } }) // ArticleSchema has: title, tags, body, publishedAt ``` ## Coercion When you create or update a node, property values are **coerced** through the property builder: - `text()` — calls `String(value)`, trims whitespace - `number()` — calls `Number(value)`, applies `Math.round()` if `integer` - `select()` — validates against option IDs, tries case-insensitive name matching as fallback - `date()` — accepts `number`, `Date`, or ISO string; normalizes to timestamp - `email()` — trims and lowercases - `url()` — auto-prepends `https://` if no protocol This means your data is always normalized regardless of what the user types. ## Dev-time warnings In development, `defineSchema` warns if: - A `text()` property has a name that looks like a reference (e.g., `targetId`, `parentId`), suggesting you use `relation()` instead ## Related - [Property Types](/docs/schemas/property-types/) — all 15 property builders - [Relations](/docs/schemas/relations/) — linking nodes together - [Type Inference](/docs/schemas/type-inference/) — how TypeScript types flow - [Authorization](/docs/guides/authorization/) — roles, grants, encryption, and key recovery --- ## Property Types **You will learn** - Every property type and its options - What TypeScript type each property infers to - Validation rules and coercion behavior xNet provides 15 property types organized into five categories. ## Basic types ### text A string property with optional length and pattern constraints. ```ts title: text({ required: true, maxLength: 500 }) draft: false description: text({ placeholder: 'Enter a description...' }) slug: text({ pattern: /^[a-z0-9-]+$/ }) ``` | Option | Type | Default | Description | | ------------- | --------- | ------- | ----------------------------- | | `required` | `boolean` | `false` | Reject null/undefined values. | | `minLength` | `number` | — | Minimum string length. | | `maxLength` | `number` | — | Maximum string length. | | `pattern` | `RegExp` | — | Regex pattern to match. | | `placeholder` | `string` | — | UI hint (not enforced). | **Infers to:** `string` **Coercion:** `String(value)`. Returns `null` for null/undefined. --- ### number A numeric property with optional range and integer constraints. ```ts priority: number({ min: 1, max: 5 }) score: number({ min: 0, integer: true }) ``` | Option | Type | Default | Description | | ---------- | --------- | ------- | ------------------------- | | `required` | `boolean` | `false` | | | `min` | `number` | — | Minimum value. | | `max` | `number` | — | Maximum value. | | `integer` | `boolean` | `false` | Round to nearest integer. | **Infers to:** `number` **Coercion:** `Number(value)`. If `integer`, applies `Math.round()`. Returns `null` for NaN. --- ### checkbox A boolean property with an optional default. ```ts completed: checkbox({ default: false }) isPublic: checkbox({ default: true }) ``` | Option | Type | Default | Description | | ---------- | --------- | ------- | --------------------------------- | | `required` | `boolean` | `false` | | | `default` | `boolean` | — | Default value for null/undefined. | **Infers to:** `boolean` **Coercion:** `'true'`/`1` to `true`, `'false'`/`0` to `false`, else `Boolean(value)`. --- ## Temporal types ### date A timestamp stored as Unix milliseconds. ```ts dueDate: date() scheduledAt: date({ includeTime: true }) ``` | Option | Type | Default | Description | | ------------- | --------- | ------- | -------------------------------- | | `required` | `boolean` | `false` | | | `includeTime` | `boolean` | `false` | UI hint for showing time picker. | **Infers to:** `number` (Unix timestamp in ms) **Coercion:** Accepts `number`, `Date` objects (`.getTime()`), ISO strings (`Date.parse()`). Returns `null` if unparseable. **Validation:** Must be between 0 and year 3000 (`32503680000000`). --- ### dateRange A range with a start and optional end date. ```ts timeline: dateRange() sprint: dateRange({ includeTime: true }) ``` | Option | Type | Default | Description | | ------------- | --------- | ------- | ----------- | | `required` | `boolean` | `false` | | | `includeTime` | `boolean` | `false` | UI hint. | **Infers to:** `{ start: string; end?: string }` (ISO 8601 strings) **Coercion:** Parses `start` and `end` through `new Date()` and converts to ISO strings. --- ## Selection types ### select A single choice from a predefined list. ```ts status: select({ options: [ { id: 'todo', name: 'To Do', color: '#6366f1' }, { id: 'doing', name: 'Doing', color: '#f59e0b' }, { id: 'done', name: 'Done', color: '#10b981' } ] as const, default: 'todo' }) ``` | Option | Type | Default | Description | | ---------- | ---------------- | ------- | ----------------------------------------------------------- | | `options` | `SelectOption[]` | — | Available choices. Each has `id`, `name`, optional `color`. | | `required` | `boolean` | `false` | | | `default` | `string` | — | Default option ID. | **Infers to:** Union of option IDs (e.g., `'todo' | 'doing' | 'done'`). Requires `as const` on the options array. **Coercion:** Returns `default` for null/undefined. Tries case-insensitive name matching as fallback. **Use `as const` for literal types** Without `as const`, the type is just `string`. With it, you get exact literal types: ```ts // Without as const → string select({ options: [{ id: 'todo', name: 'To Do' }] }) // With as const → 'todo' select({ options: [{ id: 'todo', name: 'To Do' }] as const }) ``` --- ### multiSelect Multiple choices from a predefined list. ```ts tags: multiSelect({ options: [ { id: 'bug', name: 'Bug', color: '#ef4444' }, { id: 'feature', name: 'Feature', color: '#3b82f6' }, { id: 'docs', name: 'Docs', color: '#8b5cf6' } ] as const }) ``` | Option | Type | Default | Description | | ---------- | ---------------- | ------- | ------------------- | | `options` | `SelectOption[]` | — | Available choices. | | `required` | `boolean` | `false` | | | `default` | `string[]` | — | Default option IDs. | **Infers to:** Union of option IDs as array (e.g., `('bug' | 'feature' | 'docs')[]`) **Coercion:** Returns `default ?? []` for null/undefined. Coerces single string to `[value]`. Filters invalid entries. --- ## Reference types ### relation A reference to another node by ID. ```ts project: relation({ target: 'xnet://my-app/Project' }) children: relation({ multiple: true }) ``` | Option | Type | Default | Description | | ---------- | ----------- | ------- | ------------------------------------------ | | `target` | `SchemaIRI` | — | Constrain to a specific schema (optional). | | `required` | `boolean` | `false` | | | `multiple` | `boolean` | `false` | Allow array of references. | **Infers to:** `string` (single) or `string[]` (multiple) **Coercion:** Returns `null`/`[]` for null/undefined. Filters empty strings. See [Relations](/docs/schemas/relations/) for patterns and temp ID resolution in transactions. --- ### person A reference to a user by DID. ```ts assignee: person() collaborators: person({ multiple: true }) ``` | Option | Type | Default | Description | | ---------- | --------- | ------- | -------------------- | | `required` | `boolean` | `false` | | | `multiple` | `boolean` | `false` | Allow array of DIDs. | **Infers to:** `string` (DID) or `string[]` (multiple DIDs) **Validation:** Must match DID pattern: `/^did:[a-z]+:[a-zA-Z0-9._:-]+$/` **Coercion:** Returns `null`/`[]` for null/undefined. Filters invalid DIDs. --- ## Rich types ### url A validated URL string. ```ts website: url() repository: url({ placeholder: 'https://github.com/...' }) ``` | Option | Type | Default | Description | | ------------- | --------- | ------- | ----------- | | `required` | `boolean` | `false` | | | `placeholder` | `string` | — | UI hint. | **Infers to:** `string` **Validation:** Must match `/^https?:\/\/.+/i` **Coercion:** Trims whitespace. Auto-prepends `https://` if no protocol present. --- ### email A validated email string. ```ts contactEmail: email() ``` | Option | Type | Default | Description | | ------------- | --------- | ------- | ----------- | | `required` | `boolean` | `false` | | | `placeholder` | `string` | — | UI hint. | **Infers to:** `string` **Validation:** Must match `/^[^\s@]+@[^\s@]+\.[^\s@]+$/` **Coercion:** Trims and lowercases. --- ### phone A validated phone number string. ```ts contactPhone: phone() ``` | Option | Type | Default | Description | | ------------- | --------- | ------- | ----------- | | `required` | `boolean` | `false` | | | `placeholder` | `string` | — | UI hint. | **Infers to:** `string` **Validation:** Must match `/^[+]?[(]?[0-9]{1,4}[)]?[-\s./0-9]*$/` with at least 7 digits. **Coercion:** Trims, collapses whitespace. Preserves formatting. --- ### file A content-addressed file reference. ```ts avatar: file({ accept: ['image/*'], maxSize: 5 * 1024 * 1024 }) attachments: file({ multiple: true }) ``` | Option | Type | Default | Description | | ---------- | ---------- | ------- | ------------------------------------------------------------ | | `required` | `boolean` | `false` | | | `multiple` | `boolean` | `false` | Allow array of files. | | `accept` | `string[]` | — | Allowed MIME types (e.g., `['image/*', 'application/pdf']`). | | `maxSize` | `number` | — | Maximum file size in bytes. | **Infers to:** `FileRef` or `FileRef[]` ```ts interface FileRef { cid: string // Content-addressed ID name: string // Original filename mimeType: string // MIME type size: number // File size in bytes width?: number // Intrinsic width, images and video height?: number // Intrinsic height, images and video thumbCid?: string // Small preview, stored as its own blob } ``` In a database, a `file` field renders each attachment as a chip — a thumbnail for images, an icon otherwise — and clicking one opens a full-screen viewer with paging and download. Set `multiple` to keep several files in one cell. Only the `FileRef` travels through the change log; the bytes are stored content-addressed and moved separately, uploaded to the hub in the background after attaching and fetched by peers on first view. An attachment whose bytes haven't reached this device yet reads "on another device" rather than appearing broken. --- ## Auto-populated types **Usually not needed** Every node automatically gets `createdAt`, `updatedAt`, `createdBy`, and `updatedBy` as system fields — you don't need to define them in your schema. These property builders exist for cases where you want timestamps or authorship to appear as **formal schema properties** (e.g., for generic table UIs that render columns from schema definitions). For most schemas, skip these entirely. These are read-only fields populated automatically by the system. ### created Timestamp of when the node was created. ```ts createdAt: created() ``` **Infers to:** `number` (Unix timestamp in ms) **Behavior:** Set to `Date.now()` at creation time. Read-only afterward. --- ### updated Timestamp of the last modification. ```ts updatedAt: updated() ``` **Infers to:** `number` (Unix timestamp in ms) **Behavior:** Set to `Date.now()` on every update. Read-only. --- ### createdBy DID of the user who created the node. ```ts author: createdBy() ``` **Infers to:** `string` (DID) **Behavior:** Set to the author's DID at creation time. Read-only afterward. --- ## Summary table | Type | Infers to | Validates | Notable | | ------------- | ---------------------- | ------------------------- | ---------------------- | | `text` | `string` | length, pattern | | | `number` | `number` | min, max, integer | | | `checkbox` | `boolean` | | has `default` | | `date` | `number` | 0 to year 3000 | stored as ms timestamp | | `dateRange` | `{ start, end? }` | valid dates | ISO 8601 strings | | `select` | literal union | option IDs | use `as const` | | `multiSelect` | literal union[] | option IDs | use `as const` | | `relation` | `string \| string[]` | non-empty | supports temp IDs | | `person` | `string \| string[]` | DID pattern | `did:*:*` | | `url` | `string` | http(s) | auto-prepends https | | `email` | `string` | email pattern | lowercased | | `phone` | `string` | phone pattern | 7+ digits | | `file` | `FileRef \| FileRef[]` | cid, name, mimeType, size | content-addressed | | `created` | `number` | | auto, read-only | | `updated` | `number` | | auto, read-only | | `createdBy` | `string` (DID) | | auto, read-only | ## Related - [`defineSchema`](/docs/schemas/defineschema/) — using these types in a schema - [Relations](/docs/schemas/relations/) — patterns for linking nodes - [Type Inference](/docs/schemas/type-inference/) — how types flow to hooks --- ## Relations Relations are how you connect nodes together in xNet. Instead of embedding nested objects, you store references between nodes using two specialized property types: `relation()` and `person()`. ## relation() The `relation()` property stores a reference to another node by its ID. You can think of it like a foreign key in a relational database, except it works across peers in a local-first system. When you need to link a task to a project, or a comment to a post, `relation()` is the right choice. ```ts const TaskSchema = defineSchema({ name: 'Task', namespace: 'xnet://my-app/', properties: { title: text(), project: relation({ target: 'xnet://my-app/Project@1.0.0' }), // single reference blockedBy: relation({ multiple: true }) // multiple references } }) ``` Relations support both single and multiple cardinality. Use `relation()` for a single link and `relation({ multiple: true })` for an array of links. ## person() The `person()` property links to a user by their DID (Decentralized Identifier) rather than a node ID. This is useful for ownership, assignment, and authorship fields where you need to reference an identity rather than a piece of data. ```ts const TaskSchema = defineSchema({ name: 'Task', namespace: 'xnet://my-app/', properties: { title: text(), assignee: person(), // single DID reference watchers: person({ multiple: true }) // multiple DID references } }) ``` ## Related creates in one mutate call When creating multiple related nodes at once, use explicit IDs so later operations can reference earlier creates in the same mutate call: ```ts const { mutate } = useMutate() await mutate([ { type: 'create', schema: ProjectSchema, id: 'project-acme', data: { name: 'Acme' } }, { type: 'create', schema: TaskSchema, data: { title: 'Setup', project: 'project-acme' } } ]) ``` Because the project node is created first (with a known ID), the task can safely reference it in the next operation. --- ## Type Inference One of xNet's key design goals is end-to-end type safety: you define a schema once and TypeScript carries those types all the way through to your React hooks. No manual type annotations, no `as` casts, no runtime surprises. ## How It Works The type inference pipeline has three stages: 1. **`defineSchema`** captures the property builder functions you pass in and preserves their types as a generic parameter. Each builder (like `text()`, `number()`, `relation()`) returns a typed descriptor that encodes the property's value type, default, and cardinality. 2. **`InferCreateProps`** maps over the schema's property descriptors to produce the type you pass to `createNode()`. Required properties (no default) become required fields; optional properties (with defaults) become optional fields. This is the "write" side of the type. 3. **`FlatNode`** merges the automatic system fields (`id`, `schemaId`, `createdAt`, `updatedAt`, `createdBy`, `updatedBy`) with the inferred property types to produce the "read" side. These system fields are managed by the store — you don't define them in your schema. This is what you get back from `useQuery` and `useNode`. ## From Schema to Hook ```ts // 1. Define schema — types are captured here const TaskSchema = defineSchema({ name: 'Task', namespace: 'xnet://my-app/', properties: { title: text(), done: checkbox({ default: false }), assignee: person() } }) // 2. Create — TypeScript knows title is required, done is optional const { create } = useMutate() create(TaskSchema, { title: 'Ship it' }) // ✅ create(TaskSchema, {}) // ❌ missing title // 3. Read — TypeScript knows the full shape const { data: tasks } = useQuery(TaskSchema) tasks[0].title // string tasks[0].done // boolean tasks[0].id // string (from base fields) ``` ## Extending the Type System Because schemas are plain objects with typed descriptors, you can compose them, create utility types around them, and build higher-level abstractions without losing type information. The property builder pattern ensures that new property types automatically flow through `InferCreateProps` and `FlatNode` without any changes to the inference machinery. If you're building a custom property type, implement the `PropertyBuilder` interface and the inference pipeline will pick it up automatically. --- ## Extending Schemas xNet ships typed schemas like `Task`, `Contact`, and `Page` with a fixed set of properties. When you need to track something they don't model — a `leadScore` on a contact, a `billableRate` on a task — you have three ways to extend them, from lightest to heaviest. ## 1. Overlay fields (the everyday path) An **overlay** stores custom attributes directly on the node under a reserved, namespaced key: `ext:/`. The `authority` (a Space id, a DID, or a domain) keeps two parties from colliding. Overlay values are ordinary node properties, so they sync and conflict-resolve per-key (LWW) and inherit the node's authorization automatically — no join, no schema fork. Add a field with `createExtensionField`: ```ts const { key } = await createExtensionField(store, { targetSchema: 'xnet://xnet.fyi/Contact@1.0.0', authority: 'acme.com', name: 'leadScore', type: 'number', config: { min: 0, max: 100 } }) // key === 'ext:acme.com/leadScore' ``` Read and write the value like any other property — the overlay key rides along on the node: ```ts const { update } = useMutate() await update(ContactSchema, contact.id, { 'ext:acme.com/leadScore': 87 }) // Filtering uses the standard where path (it pushes down like any property): const hot = useQuery(ContactSchema, { where: { 'ext:acme.com/leadScore': 87 } }) ``` The grid composes the **effective schema** — core columns plus your overlay columns — via `useEffectiveSchema`. Schema-defined (core) columns are structurally **locked**: you can edit their values but not rename, retype, or delete them. Only overlay columns are restructurable. ```ts const { schema } = useEffectiveSchema('xnet://xnet.fyi/Contact@1.0.0') // schema.properties includes 'name' (readonly) … 'ext:acme.com/leadScore' ``` ## 2. Sidecar extensions (when access differs) An overlay inherits the target node's authorization. When the attributes need their **own** owner or access — say, _your_ private notes on a `Contact` someone else shares with you — use a **sidecar**: a separate node that references the target and carries its own `authorization` (typically `presets.private()`). ```ts const ContactNotes = defineSchema({ name: 'ContactNotes', namespace: 'xnet://did:key:.../', properties: { target: relation({ target: 'xnet://xnet.fyi/Contact@1.0.0', required: true }), notes: text({}) }, authorization: presets.private() }) // one sidecar per (authority, target): id = sidecarId(authority, contactId) ``` The grid folds a sidecar's attributes into the same `ext:/` column space as overlays via `mergeSidecarsIntoRow`, so both render uniformly. ## 3. A new schema version (custom objects) When you're really creating a new _type_ — not just decorating an existing one — define a new schema (optionally `extends` the base) and migrate existing nodes with a **lens**. To graduate an overlay into a first-class property, use `promoteOverlay`: ```ts const v1ToV2 = composeLens( 'xnet://xnet.fyi/Contact@1.0.0', 'xnet://xnet.fyi/Contact@2.0.0', promoteOverlay('acme.com', 'leadScore', 'leadScore') ) // { 'ext:acme.com/leadScore': 87 } → { leadScore: 87 } (lossless) ``` ## Which one? | Need | Use | | ----------------------------------------- | --------------------------------- | | A custom field, same record + permissions | **Overlay** (`ext:` key) | | A field with its own owner / access | **Sidecar** (join node) | | A distinct, fully-typed type | **New schema** (`extends` + lens) | Overlay is the default — it's the cheapest to store and query. Reach for a sidecar only when access must differ, and a new schema only when you're authoring a genuinely new type. --- ## The xNet Protocol The `xNet` repository is **one implementation** of xNet. xNet itself is a **protocol** — a written interface you can re‑implement in any language, over any database, and still interoperate with every other conforming implementation. Like Matrix, the AT Protocol, or ActivityPub, the standard is separate from any one codebase. This page is the friendly tour. The **normative source of truth** is [`docs/specs/protocol/`](https://github.com/crs48/xNet/tree/main/docs/specs/protocol) — versioned with the code, backed by a machine‑checked conformance corpus. ## The boundary in one sentence > A conforming xNet implementation agrees on the **cryptographic primitives**, > the **data model** (especially the byte‑exact canonicalization of a change), > the **replication wire format**, and the **authorization semantics** — and > treats everything above (query, storage layout, UI, the built‑in app schemas) > as private. ## Four normative layers ```mermaid flowchart TB L4["L4 · Application Profile — NON-NORMATIVE\nbuilt-in schemas, spaces, query, UI"] L3["L3 · Authorization\nschema rules, roles, grants, UCAN"] L2["L2 · Replication\nchange relay, signed Yjs envelope, handshake, transports"] L1["L1 · Data Model\nNode, SchemaIRI, properties, Change, canonicalization, LWW, document codec"] L0["L0 · Primitives\ndid:key/Ed25519, XChaCha20, X25519, BLAKE3, UCAN"] L4 --> L3 --> L2 --> L1 --> L0 ``` ## The interop kernel (the part that makes it xNet) The irreducible core is small. An implementation that does **only L0 + L1** can already create, sign, verify, and converge nodes — fully participating in the graph: 1. A **`did:key`** identity from an Ed25519 key. 2. A **Node** = four universal fields (`id`, `schemaId`, `createdAt`, `createdBy`) plus schema‑defined properties. 3. A **Change** = a signed, hash‑chained, Lamport‑stamped mutation whose canonical bytes and BLAKE3 hash are specified exactly. 4. **Last‑Write‑Wins** per‑property conflict resolution on the Lamport clock. ## Yjs is _not_ the protocol A common misconception: "xNet is built on Yjs, so I'd have to port a CRDT." Not so. Yjs is used only for the optional rich‑text **document body** of certain nodes, and it travels the wire as **opaque bytes inside a signed envelope**. A second implementation can relay and store that blob without parsing it, and still participate fully. The CRDT is a **pluggable document codec**, not the interop kernel. (See [data model](/docs/protocol/data-model/).) ## One umbrella version Peers negotiate a single named bundle — `xnet/1.0` — exactly as Matrix bundles breaking changes into _room versions_. It expands to the per‑subsystem versions (change record, sync envelope, awareness, schema, crypto level). The machine‑readable constant is `XNET_PROTOCOL_VERSION`, exported by `@xnetjs/sdk`. ## Prove it, don't just read it Every claim in the spec is backed by a **language‑agnostic golden‑vector corpus** shipped _with_ the spec and re‑checked in CI — so the prose can't drift from reality. A ~100‑line Python kernel reproduces the same DIDs and verifies TypeScript‑signed changes. Want to build your own implementation? --- ## Data Model (L1) This is the heart of the protocol. Get it right and your implementation can participate in the node graph. The normative text is [`02-data-model.md`](https://github.com/crs48/xNet/blob/main/docs/specs/protocol/02-data-model.md). ## The Node Every node, in every implementation, has exactly four universal fields; all others are schema‑defined: ```ts interface Node { id: string // opaque, collision-resistant (nanoid in the reference impl) schemaId: SchemaIRI // "xnet://authority/Name@version" createdAt: number // Unix ms, set on first change createdBy: DID // did:key of the creator — immutable [key: string]: unknown // schema-defined properties } ``` `createdBy` is the root of a node's provenance and never changes. Nodes are **soft‑deleted** (tombstoned), never hard‑deleted. ## Schema references ``` SchemaIRI = "xnet://" authority "/" Name ( "@" semver )? ``` The `authority` names who governs the schema — `xnet.fyi` for built‑ins, a domain for organizations, or a DID for personal schemas. Nodes are self‑describing via `schemaId`, so relays and stores can process them without resolving the schema. Schemas are JSON‑Schema‑shaped — **not** JSON‑LD/RDF (a deliberate choice; full JSON‑LD is the reason ActivityPub implementations diverge). ## The Change A node is never mutated in place. Its state is the fold of an append‑only log of signed **Change** records: ```ts interface Change { protocolVersion: 3 id: string type: 'node-change' payload: { nodeId, schemaId?, properties, deleted? } // sparse hash: string // "cid:blake3:" parentHash: string | null // the causal hash chain authorDID: DID signature: Uint8Array // Ed25519 over UTF-8(hash) wallTime: number lamport: number // ordering / LWW } ``` The **first** change for a node carries `schemaId`; later changes carry only the properties that changed. ## The byte‑exact contract Two implementations that disagree on these bytes cannot verify each other's signatures. The reference impl hashes with **BLAKE3** (not SHA‑256) and signs the **UTF‑8 bytes of the hash string** `cid:blake3:` — not the raw digest. 1. Take the unsigned change (all fields except `hash`/`signature`). 2. **Canonical JSON:** sort object keys lexicographically and recursively, no whitespace, arrays in order, `undefined` omitted, UTF‑8 bytes. 3. **Hash:** `"cid:blake3:" + hex(BLAKE3(bytes))`. 4. **Sign:** `Ed25519(UTF8(hash_string), key)`. ```js const sorted = sortKeysRecursively(unsigned) // recursive key sort const bytes = utf8(JSON.stringify(sorted)) // compact const hash = "cid:blake3:" + hex(blake3(bytes)) const sig = ed25519.sign(utf8(hash), signingKey) // sign the STRING bytes ``` This exact transform is pinned by the [golden vectors](/docs/protocol/conformance/), so any implementation can check itself byte‑for‑byte. ## Conflict resolution: Lamport + LWW Materialized state keeps a `{ lamport, wallTime }` timestamp **per property**. When two changes touch the same property: 1. higher **`lamport`** wins; 2. tie → higher `wallTime`; 3. tie → higher `authorDID` (lexicographic) — a deterministic final tiebreak so all peers converge identically. Because LWW is per‑property, concurrent edits to *different* properties of the same node both survive. ## The document codec (where Yjs lives — and why it's opaque) A schema may declare a collaborative body with `document: 'yjs'`. Such nodes carry a `documentContent` blob identified by a `documentCodec` discriminator (`yjs-v1`, `automerge-2`, `none`). Implementations **must transport and persist** the blob faithfully, but **interpreting it is optional** — a peer that can't parse `yjs-v1` still fully participates in the graph. This is the seam that makes xNet portable without porting a CRDT byte format across languages. Next: [Replication (L2) →](/docs/protocol/replication/) --- ## Replication (L2) How nodes and document bodies move between peers. The message *semantics* are defined once and bind to multiple transports. Normative text: [`03-replication.md`](https://github.com/crs48/xNet/blob/main/docs/specs/protocol/03-replication.md). ## Two streams per document A document (room) carries two complementary streams. An implementation must relay both faithfully; it need only *interpret* the first. ```mermaid flowchart LR P1["Peer A"] <-->|relay / P2P| Room Room["Room = one document (docId)"] <-->|relay / P2P| P2["Peer B"] Room --- A["Structured node sync\nsigned Change records"] Room --- B["Document body sync\nsigned Yjs envelope (opaque)"] ``` ## Structured node sync ```ts { type: "node-change", room, change } // one new signed change { type: "node-sync-request", room, sinceLamport } // catch-up request { type: "node-sync-response", room, changes, highWaterMark } // catch-up batch ``` A receiver verifies each change's signature, applies idempotently (re‑applying a known `hash` is a no‑op), and orders by `lamport`. `highWaterMark` enables resumable catch‑up. ## The signed Yjs envelope Document bodies sync with [y‑protocols](https://github.com/yjs/y-protocols) sync v1, each update wrapped so the relay can authenticate authorship **without parsing the CRDT**: ```jsonc { "v": 2, "u": "base64(Yjs update bytes)", // OPAQUE codec payload "m": { "a": "did:key:…", "c": 12345, "t": 1718641200000, "d": "" }, "s": { "ed25519": "base64", "mlDsa": null, "level": 0 } } ``` The signature covers `BLAKE3(update || JSON(meta))` and is verified against the author DID. Relays forward the envelope byte‑preserving; a peer that doesn't implement `yjs-v1` still forwards and stores `u`. ## Awareness Ephemeral presence (cursor, selection, online status) uses y‑protocols awareness. It is **not** persisted as node data and is exempt from the hash chain; relays should rate‑limit and expire it. ## The version handshake ```mermaid sequenceDiagram participant C as Client participant H as Hub H->>C: handshake { xnetProtocol:["xnet/1.0"], minXnetProtocol, hubDid } C->>H: client-handshake { did, xnetProtocol:["xnet/1.0"] } alt no shared umbrella version H-->>C: version-mismatch { suggestion } else compatible C->>H: subscribe { topics:["xnet-doc-…"] } H-->>C: relays node-change / sync-* / awareness end ``` Two peers are compatible iff their `xnetProtocol` sets intersect; a peer with no acceptable version refuses with a typed `version-mismatch` rather than partially syncing. The token is `XNET_PROTOCOL_VERSION.id` (`"xnet/1.0"`) from `@xnetjs/sdk`. ## Transport bindings The same logical messages bind to two transports: **WebSocket** (JSON frames, browser ↔ hub) and **libp2p** (length‑prefixed msgpack over `/xnet/sync/1.0.0`, P2P). A relay may bridge between them. Next: [Authorization (L3) →](/docs/protocol/authorization/) --- ## Authorization (L3) In xNet, authorization is **data, not application logic**: rules are declared on schemas and delegated through grant nodes and UCAN tokens, and enforced at the sync boundary. Because two implementations that disagree on policy make different read/write decisions on the same graph, the decision *semantics* are normative. Normative text: [`04-authorization.md`](https://github.com/crs48/xNet/blob/main/docs/specs/protocol/04-authorization.md). ## Actions and decisions ``` action ∈ { read, create, update, write, delete, share, admin } can(subject: DID, action, nodeId) → { allowed, reasons } ``` `create` and `update` are **refinements of `write`**: `create` governs bringing a node into existence, `update` governs mutating one that exists. A schema may declare either; when absent, each falls back to the schema's `write` expression (and a legacy `write` check follows the `update` rule), so schemas that only declare `write` behave exactly as before. Create checks evaluate against the *draft* node built from the payload — container relations in the payload (e.g. `space`, `channel`) resolve membership roles, which is how creation into a shared container is gated. A grant carrying `write` satisfies both refinements; a granular grant covers only itself. ```ts actions: { read: allow('owner', 'spaceMember'), create: allow('spaceMember'), // members may add… update: allow('owner', 'spaceAdmin'), // …only the author (or admins) may edit write: allow('owner', 'spaceMember'), // fallback for engines without the split delete: allow('owner', 'spaceAdmin'), share: allow('owner', 'spaceAdmin') } ``` ## Schema authorization A schema may carry an `authorization` block defining **roles** (how a subject earns a role on a node) and **actions** (which roles may perform each action): ```ts interface AuthorizationDefinition { roles: Record actions: Record publicProps?: string[] fieldRules?: Record } ``` ## Role resolvers | Kind | Subject earns the role when… | |---|---| | **creator** | `subject == node.createdBy` | | **property** | it appears in a named `person`/`relation` property (e.g. `editors`) | | **relation** | it holds a role on a *related* node (inheritance) | | **membership** | a membership edge (e.g. `SpaceMembership`) links it to a container with a role ≥ `minRole`, cascading to nested containers | Resolution walks relations/memberships with a bounded depth and must terminate. ## The expression AST ``` expr ::= allow(role…) | deny(role…) | roleRef(name) | and(expr…) | or(expr…) | not(expr) | PUBLIC | AUTHENTICATED ``` **Deny wins:** if any matching `deny` is true, the action is denied regardless of any `allow`. Evaluation is total and deterministic. ## Encryption as access control For private nodes, **the ability to decrypt is the read‑control mechanism**: content keys are wrapped per recipient (X25519 + XChaCha20). A subject not in the recipient set can't read encrypted properties even if it receives the bytes. `publicProps` and the four universal node fields stay readable for indexing and attribution. ## Grants and UCAN - **Grant nodes** — ordinary xNet nodes recording `{ issuer, grantee, resource, actions, expiresAt, revokedAt }`. Active iff not revoked and not expired. - **UCAN tokens** — capability tokens (JWT/EdDSA) with a proof chain. Each capability must be an attenuation of its proof; child expiry ≤ parent; chains acyclic. ## Deterministic pipeline ```mermaid flowchart TB Q["can(subject, action, node)"] --> ND{node-level deny?} ND -->|yes| DENY ND -->|no| RR["resolve roles (depth-bounded)"] RR --> SE["evaluate schema expression (deny-wins)"] SE -->|allowed| ALLOW SE -->|no| GR{active grant / UCAN?} GR -->|yes| ALLOW GR -->|no| PUB{PUBLIC / publicProps?} PUB -->|yes| ALLOW PUB -->|no| DENY ``` Caching and indexing are private; the *decisions* must match the decision‑trace [conformance vectors](/docs/protocol/conformance/). Next: [Implement it in your language →](/docs/protocol/implement-in-your-language/) --- ## Implement xNet in Your Language You don't need to port the whole `xNet` codebase to build a compatible implementation. You need the **interop kernel** (L0 + L1) — and the [golden vectors](/docs/protocol/conformance/) tell you exactly when you've got it right. The proof this is real: a ~100‑line Python kernel reproduces the same DIDs and verifies — and re‑signs byte‑for‑byte — changes signed by the TypeScript reference implementation. The full kernel is at [`conformance/reference/python`](https://github.com/crs48/xNet/tree/main/conformance/reference/python). ## The path 1. **Identity — `did:key` over Ed25519.** Generate an Ed25519 key, prefix the public key with multicodec `0xed 0x01`, base58btc‑encode, prepend `did:key:z`. Check against `conformance/vectors/identity/`. 2. **Canonicalize a change.** Sort keys lexicographically and recursively, serialize to compact UTF‑8 JSON. Check against the `canonicalJson` field in `conformance/vectors/change/`. 3. **Hash & sign.** `"cid:blake3:" + hex(BLAKE3(bytes))`, then Ed25519‑sign the **UTF‑8 bytes of that hash string**. Reproduce `hash` and `signatureBase64`. 4. **Last‑Write‑Wins.** Fold a change sequence with per‑property `{lamport, wallTime, authorDID}` resolution (higher wins, author breaks ties). Check against `conformance/vectors/lww/`. 5. **(Optional) Replication & authorization.** Implement the [wire messages](/docs/protocol/replication/) and [policy evaluation](/docs/protocol/authorization/) to join live rooms. ## The kernel, in ~30 lines This is the entire L0 + L1 verify path in Python — proof that the spec, not the TypeScript source, is enough to interoperate: ```python from blake3 import blake3 from nacl.signing import SigningKey, VerifyKey ED25519_MULTICODEC = b"\xed\x01" def did_from_public_key(pub: bytes) -> str: # L0 §1 return "did:key:z" + base58.b58encode(ED25519_MULTICODEC + pub).decode() def canonical_json(value) -> bytes: # L1 §6 return json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=False).encode("utf-8") def change_hash(unsigned: dict) -> str: # L1 §6 to_hash = {k: v for k, v in unsigned.items() if k != "protocolVersion"} \ if unsigned.get("protocolVersion", 0) in (0, None) else unsigned return "cid:blake3:" + blake3(canonical_json(to_hash)).hexdigest() def verify_change(unsigned: dict, sig: bytes, pub: bytes) -> bool: try: VerifyKey(pub).verify(change_hash(unsigned).encode(), sig); return True except Exception: return False ``` ## Run the proof ```bash git clone https://github.com/crs48/xNet && cd xNet pip install pynacl blake3 base58 python conformance/reference/python/verify_vectors.py # → 18 passed, 0 failed ``` ## Claim conformance Reproduce a layer's [golden vectors](/docs/protocol/conformance/) byte‑for‑byte, then open a PR adding a row to the [conformance matrix](https://github.com/crs48/xNet/blob/main/conformance/README.md). Proposing a change to the protocol itself? File an [XPP](https://github.com/crs48/xNet/tree/main/docs/specs/protocol/xpp) — the lightweight, "prove‑it‑before‑you‑spec‑it" proposal process. --- ## Conformance A specification without a conformance suite drifts — independent implementations diverge silently. (ActivityPub shipped a W3C Recommendation with no test suite for ~5 years; the fediverse is still paying for it.) xNet ships a **language‑agnostic golden‑vector corpus alongside the spec, from day one**, and re‑verifies it in CI. The corpus lives at [`conformance/`](https://github.com/crs48/xNet/tree/main/conformance). ## What conformance means You claim conformance to a layer by **reproducing that layer's vectors byte‑for‑byte**. The vectors are plain JSON `{ description, input, expected }` — any language can load them. | Suite | Layer | Proves | |---|---|---| | `vectors/identity/` | L0 | seed → `did:key` + public key | | `vectors/change/` | L1 | unsigned change → canonical bytes → BLAKE3 hash → Ed25519 signature | | `vectors/lww/` | L1 | change sequence → converged state (order‑independent) | | `vectors/replication/` | L2 | version handshake, catch‑up filtering, signed Yjs envelope | | `vectors/authz/` | L3 | authorization expression (AST) evaluation | | `vectors/authz-actions/` | L3 | action‑expression resolution (`create`/`update` → `write` fallback) | `xnet/1.0`'s first corpus covers the **interop kernel** (L0 + L1). Full L3 decision‑trace suites are tracked as [XPPs](https://github.com/crs48/xNet/tree/main/docs/specs/protocol/xpp). ## Example vector ```jsonc { "description": "First change for a Page node, fixed author seed", "input": { "authorSeedHex": "aaaa…", "unsignedChange": { /* … */ } }, "expected": { "authorDID": "did:key:z6Mkv1o2…", "canonicalJson": "{\"authorDID\":\"did:key:z6Mkv1o2…\",…}", "hash": "cid:blake3:76fdfa20…", "signatureBase64": "UcVsz+sh…==" } } ``` ## The drift guard The reference implementation re‑derives every vector from its own code and asserts equality in CI. A change to canonicalization, hashing, or DID derivation that isn't reflected in the corpus **fails the build** — the spec's central claim is executable, not aspirational. ```bash # verify (CI drift guard) pnpm exec vitest run --project runtime packages/runtime/src/conformance.test.ts # the second-language proof pip install pynacl blake3 base58 python conformance/reference/python/verify_vectors.py ``` ## The conformance matrix Following [Willow](https://willowprotocol.org/)'s lightweight model, conforming implementations are tracked per layer: | Implementation | Language | L0 identity | L1 change | L1 lww | L2 | L3 | |---|---|:--:|:--:|:--:|:--:|:--:| | `xNet` (reference) | TypeScript | ✅ | ✅ | ✅ | reference | reference | | `reference/python` | Python | ✅ | ✅ | — | — | — | | _add yours_ | | | | | | | To add your implementation, reproduce the vectors and open a PR against [`conformance/README.md`](https://github.com/crs48/xNet/blob/main/conformance/README.md). --- ## The Workbench **You will learn** - The workbench regions and what lives in each - How tabs work (preview tabs, pinning, splits, deep links) - The command palette and core keyboard map - How plugins contribute to the shell ## Overview The web app's shell is a fixed-region workbench in the VS Code mold: predictable named regions, everything opens as a tab, one command palette, one drag model. The chrome is monochrome by design — hue is reserved for your data (status dots, charts), so the interface recedes and the work reads first. ## Regions | Region | What lives there | | ------------ | ----------------------------------------------------------------------------------- | | Rail (left) | Search, Explorer, Tasks, Data, Chats, plugin items; identity and settings below | | Left Panel | One view at a time: Explorer, Tasks, Data, Chats, or a plugin view | | Editor Area | Tabbed documents — pages, databases, canvases, dashboards, channels, saved views | | Right Panel | Contextual sections published by the active tab (properties, comments, backlinks…) | | Bottom Panel | Tray: Shelf, quick capture, Notifications, sync activity, and a query console | | Status Bar | Left = workspace scope (sync, presence), right = view scope (save state, theme) | Layout, open tabs, pins, recents, and zen-mode snapshots persist locally and survive reloads bit-for-bit. ## Tabs Everything opens as a tab, and **the router stays authoritative**: navigating opens-or-activates the matching tab, so deep links, back/forward, and old bookmarks keep working. - **Preview tabs** — a single click from the Explorer or palette opens an italic _preview_ tab that is replaced by the next preview. Editing the content or double-clicking promotes it to a real tab. - **Pinning** — pinned tabs stay put and survive "close others". - **Splits** — one optional second editor group: drag a tab to the editor edge or press `⌘⇧\`. - **Performance** — background tabs are unmounted entirely; they hold no live document subscriptions. ## Command palette `⌘K` (or `⌘P`) opens quick-open: recents first, then full-text page matches and every node type. Type `>` to switch to command mode — every command in the registry is listed with its keyboard chord. Escape restores focus to where you were. ## Keyboard map | Chord | Action | | -------------- | ----------------------------------------------------- | | `⌘K` / `⌘P` | Palette / quick-open (`>` = command mode) | | `⌘B`, `⌘\`, `⌘J` | Toggle left / right / bottom panel | | `⌘.` | Zen mode (Esc Esc exits; layout restored bit-for-bit) | | `⌘T` / `⌘W` | New page / close tab | | `⌃Tab` / `⌃⇧Tab` | Cycle tabs | | `⌘1` / `⌘2` | Focus editor group | | `⌘⇧\` | Split editor | | `F6` / `⇧F6` | Cycle focus through shell regions | ## Drag model Every draggable entity — explorer rows, tabs, task rows, database row chips, canvas selections — carries the same node payload. Drops create **references, never copies**: - onto the editor → a wikilink chip at the drop point - onto a relation cell → a link - onto a canvas → a source-backed card - onto the tab bar → a tab - onto an editor edge → a split - onto the Shelf (bottom tray) → a held reference for later ## Theme The token system is a single APCA-contrast-tuned monochrome ramp per mode (`surface-0/1/2`, `ink-1/2/3`, `hairline`, `accent-ink`). Chrome sits on dimmer surfaces than the work; the editor area is the only brightest-surface region. A `true-black` variant collapses dark surfaces to `#000` for OLED displays — toggle it from the status bar theme control. ## Extending the shell Plugins contribute _items_ into fixed containers; they cannot invent new chrome: - **Rail items / left-panel views** — `SidebarContribution` (a `panel` component becomes a left-panel view) - **Status bar items** — `StatusBarContribution` (workspace scope or view scope) - **Palette commands** — `CommandContribution`, chords included - **Context sections** — views publish sections to the Right Panel - **Dashboard widgets** — `WidgetContribution` (see the [Dashboards guide](/docs/guides/dashboards/)) See the [Plugins guide](/docs/guides/plugins/) for the contribution API. ## Further reading - [Tasks](/docs/guides/tasks/) — the task surfaces hosted by the shell - [Dashboards](/docs/guides/dashboards/) — widget boards as tabs - [Chat & Calls](/docs/guides/chat-and-calls/) — channels as tabs, calls in a dock --- ## The Quiet Shell & the Desk **You will learn** - What the quiet chrome posture is and how to switch into it - The disclosure ladder: corners, edges, chords, and Esc - The Desk — your bounded home canvas — and how pinning works - The SurfaceDock, and how it maps to the pinned shell's tray ## Overview The quiet shell inverts the calm shell's composition: at rest the screen is just your work — a document, a database, or the Desk canvas — and the chrome is *summoned*, never pinned. Glyph clusters sit dimmed in the corners; the navigator and the contextual canvas slide in from the edges; the dock expands from the bottom-right the way devtools always has. Nothing is removed — every drawer is reachable three ways: pointer (hover an edge, or swipe on a phone), keyboard chord, or the ⌘K palette. Switch postures any time with **⌘K → "View: Quiet chrome"** (and back with "View: Pinned chrome"). The setting is per-device and changes nothing about your data or routes. ## The disclosure ladder | Level | What you see | How you got here | | ----- | --------------------------- | -------------------------------------------- | | L0 | Bare surface, dimmed glyphs | Rest state | | L1 | Glyphs lit | Pointer near an edge, or a touch | | L2 | One overlay open | Edge hover-dwell, swipe, ⌘B / ⌘\ / ⌘J / ⌘K | | L3 | Pinned chrome | "View: Pinned chrome" or the workbench grid | **Esc always walks down one rung.** Dismissing an overlay returns you to the bare surface; it never dead-ends. | Surface | Pointer / touch | Chord | Palette | | --------- | ------------------------ | ----- | ------------------- | | Navigator | left edge hover / swipe | ⌘B | Toggle left panel | | Context | right edge hover / swipe | ⌘\ | Toggle right panel | | Dock | corner launcher / FAB | ⌘J | `Dock: ` | | Palette | corner search glyph | ⌘K | — | ## The Desk The Desk is a personal home canvas with a deterministic, identity-derived id — it is created the first time you visit it, and the same identity gets the same Desk on every device. It is **bounded but growable**: panning clamps near your content (you can't strand yourself in empty space), and the board grows as cards land outside it. **Fit to content** (Ctrl/Cmd 1) is the home anchor. Build your workspace by pinning: - **Drag** anything from the navigator onto the Desk. - **Pin to Desk** from a document via ⌘K, or the desk icon that appears when you hover a navigator row. Pins queue up and land the next time the Desk is on screen — you don't have to be looking at it. - **Go to Desk** (`g k`) from anywhere. Pinned cards are live views of the real nodes — edit the source and the card follows. On a phone the Desk renders as an ordered list (reading order of the board), which is also how screen readers traverse it. ## The SurfaceDock The bottom-right launcher is the devtools grammar for everyone: a single glyph that expands into the *hero* panels (Shelf, Capture, Notifications) with the rest behind **More** and the palette. It reuses the pinned shell's bottom tray state, so ⌘J toggles the same panels in either posture. Plugins add panels through the `surfaceDock` contribution point in `@xnetjs/plugins`. ## Rollout Quiet chrome ships opt-in. New identities boot straight to the Desk under quiet chrome once the staged-rollout flag flips; existing workspaces keep whatever posture they chose. --- ## Tasks **You will learn** - Where tasks live in the app and how the surfaces connect - Inline editing and quick-add with `@mention` - Deep links (`/tasks?task=`, `/tasks?project=`) - Why some task fields are read-only outside their hosting page ## Overview Tasks are first-class nodes (`TaskSchema`) with status, priority, assignees, due dates, and project membership. They show up — and are **editable in place** — on every surface that renders them: the Tasks view, the sidebar mini-dashboard, page checklists, kanban boards, and the right context panel. ## Surfaces ### The Tasks view (`/tasks`) The main surface: list and board layouts with keyboard verbs — `j`/`k` to move, `x` to complete, `s` for status, `p` for priority, `Enter` to edit. Clicking a row expands an editor beneath it; board cards open a peek overlay; the right context panel hosts the same live editor for the focused task. Deep links are first-class: - `/tasks?task=` opens that task's editor directly. - `/tasks?project=` scopes the surface to a project (with a clearable chip); quick-added tasks join that project. ### The sidebar Tasks panel A personal mini-dashboard in the left panel: - **Pinned** — tasks you pinned, surfaced first - **In progress** — your tasks in a started status - **Assigned to me** — priority-ordered (urgent → low, then nearest due date), paginated - **Projects** — projects you follow, with open-task counts; click one to scope the Tasks view to it Rows are draggable onto canvases and deep-link into the Tasks view. ### Everywhere else Task checklists inside pages, task widgets on dashboards, and task rows in database views all expand the same shared editor — title with **@mention-to-assign**, status/priority pickers, a due-date popover (Today / Tomorrow / Next week / pick a date / clear), an assignee picker, and a pin toggle. ## Quick-add Every task surface has a quick-add input. Type `@` while entering the title to assign as you type — pending assignees render as removable chips before the task is created. ## Field authority: pages own their checklists A task can be **hosted by a page** (created from a checklist item in a document). The hosting page is the source of truth for the fields it renders inline: | Field | Owner | | ------------------------------ | -------------------------------------- | | Title, assignees, due date | The hosting page (document content) | | Status, priority, completion, pins | The task node — editable everywhere | On the page itself, edits to doc-owned fields **write through the live document** (mention nodes, due chips) and the page then reconciles the task node. On other surfaces (e.g. `/tasks`), doc-owned fields of hosted tasks render read-only with an *Open page* affordance — a node-side write would be silently overwritten by the page's next snapshot, so the app doesn't offer one. Tasks created outside a page (quick-add, Tasks view, widgets) have no hosting page and every field is editable everywhere. ## Querying tasks in your own code Tasks are ordinary nodes — the same hooks apply: ```tsx const { data: myTasks } = useQuery(TaskSchema, { filter: { assignees: { contains: me }, status: { not: 'done' } }, sort: [{ field: 'priority' }, { field: 'dueDate' }] }) const { update } = useMutate() await update(TaskSchema, taskId, { status: 'in-progress' }) ``` ## Further reading - [The Workbench](/docs/guides/workbench/) — where the task surfaces live - [Dashboards](/docs/guides/dashboards/) — task-list and metric widgets - [Quickstart](/docs/quickstart/) — build your own task schema from scratch --- ## Dashboards & Widgets **You will learn** - How dashboards, widgets, and dashboard variables fit together - The built-in widget catalog (metrics, tables, charts, feeds) - The widget contract for plugin authors - How user-written widgets are sandboxed ## Overview A dashboard is a node like any other: a grid of **widget instances** with per-breakpoint layouts, opened as a workbench tab (`/dashboard/$dashboardId`). Widgets are declarative — a widget describes *what data it needs* as a saved-view query and *how to render it*; the runtime executes the query reactively, so a task created anywhere in the workspace updates a live widget immediately. Widgets never touch the store directly. ## Dashboard variables Dashboards carry variables — most importantly a **time range** — that the runtime interpolates into every widget's query (`$name` placeholders). Change the range once and every widget on the board re-queries. ## Built-in widgets | Widget | Shows | | ----------------- | ----------------------------------------------------------- | | Metric | A single aggregate (count, sum, average) over a query | | Task list | Tasks matching a filter, editable inline | | Saved-view table | Any saved view, in compact table form | | Bar / line / area / pie charts | Aggregates by property, via ECharts | | Social feed | Recent items from the saved-content graph | | Page links | A curated set of page references | | Recent items | Recently touched nodes across the workspace | | Pin board | Your pinned nodes | | Mini calendar | A month view of dated items | Add widgets from the picker; each widget's configuration panel is auto-generated from its declared config fields (property pickers, query filters, display options). ## The widget contract A widget definition is Grafana-shaped — manifest, config fields, query, renderer: ```ts const taskCountWidget: WidgetDefinition = { manifest: { id: 'task-count', name: 'Open task count', icon: 'check' }, configFields: [ { key: 'project', type: 'node-ref', label: 'Project', schema: 'project' } ], query: (config, vars) => ({ schema: 'task', filter: { project: config.project, status: { not: 'done' } }, range: vars.timeRange }), Renderer: ({ rows }) => } ``` Plugins register widgets with a `WidgetContribution`. The same definition also renders **on canvases** — any widget can be dropped onto a canvas as a live card. ## Trust tiers and sandboxing The widget *host* assigns a trust tier — a widget can never self-declare one: | Tier | Source | Isolation | | ------------- | ------------------------- | ------------------------------------------------------ | | `built-in` | Ships with the app | None needed | | `plugin` | Installed extension | Plugin permission model | | `user` | Written in the in-app editor | SES `lockdown()` + per-widget `Compartment` in a Web Worker | | `marketplace` | Third-party | Sandboxed iframe (`allow-scripts` only) | User-tier widgets render through **safe node trees** materialized via tag and style allowlists — no `window`, `document`, `fetch`, or store access; runaway code is terminated and the worker respawned. Permission prompts appear when you add a widget that requests capabilities. ## Writing your own widget in-app The widget editor (a regular tab) persists your code as a node and registers it as a `user`-tier widget — edit, save, and watch it render sandboxed on the board. It syncs like any other node, so your custom widgets follow you across devices. ## Further reading - [The Workbench](/docs/guides/workbench/) — dashboards as tabs - [Plugins](/docs/guides/plugins/) — registering `WidgetContribution`s - [Canvas](/docs/guides/canvas/) — widget cards on the infinite canvas --- ## Chat, Presence & Calls **You will learn** - How channels, DMs, and voice rooms are modeled as nodes - How presence rooms work (who's here, typing, in a call) - How peer-to-peer calls connect and their mesh limits - What the hub adds (signaling relay, mention validation) ## Overview `@xnetjs/comms` brings real-time communication to the workspace using the same local-first machinery as everything else: **messages are signed nodes**, not a separate protocol. A channel is a `Channel` node (`channel`, `dm`, or `voice`), each message is a `ChatMessage` node signed by its author, and read state is your own private `InboxState` node. Everything syncs peer-to-peer, works offline, and lands in the same store your queries already read. ## Channels and DMs - **Channels** open as workbench tabs (`/channel/$channelId`) with typing indicators, an `@`-mention autocomplete composer, and call join controls. - **DMs** need no coordination to create: the channel ID is derived deterministically from the sorted member DIDs, so both sides materialize the same conversation independently. - **Per-document chat** — a channel can target any node, which powers the Room section in the right panel: every page, canvas, or database gets a discussion thread alongside a who's-here roster. - **Voice rooms** are channels with `kind: 'voice'`; opening one joins the call automatically (the Discord model), and occupancy shows in the Chats panel. Display names and avatars resolve through `Profile` nodes (DID → name / avatar / status), editable in Settings. ### Mentions are structured Mentions are never parsed out of message text. Composers populate a `mentions: { dids, room? }` field on the message — the model used by Matrix's intentional-mentions spec — so notification logic is deterministic and a hostile client can't sneak a mention past a renderer difference. ## Presence rooms Presence is built on **rooms**: refcounted awareness sessions over any node ID with typed fields — `user`, `viewing`, `status`, `typing`, `call`. The workspace presence room drives the global roster (the "◉ n here" chip in the status bar); per-node rooms drive who's-viewing-this-page and typing indicators. Open the same room from five components and they share one session. ## Calls Calls are **full-mesh WebRTC**: - Offer initiation is deterministic (ordered by DID), so two peers never glare. - The mesh ceiling is enforced reactively: **4 participants with video, 8 audio-only**. Beyond that, a selective-forwarding tier is on the roadmap. - Screen sharing replaces your video track — no renegotiation hiccup. - The call UI lives in a **floating dock** mounted outside the router, so navigating tabs never drops a call (the Slack-huddle property). Signaling is a pluggable transport. With a hub, call setup reuses the hub's existing pub/sub broker — no new server protocol; an in-memory loopback transport exists for tests and same-device flows. ## What the hub adds A [hub](/docs/guides/hub/) is optional for chat as for everything else, but when present it: - relays call signaling (`call/join`, `call/signal`) over its existing WebSocket broker - validates mention declarations at relay time (shape checks and a 50-DID cap) so clients can't mention-bomb a channel - will carry push notification delivery (in progress) For larger calls, deploy a TURN server alongside the hub — see the deployment recipes in the repository (`docs/deployment/REALTIME_CALLS.md`). ## Current limits Chat content is signed and syncs over encrypted transports, but **per-channel end-to-end encryption phases are still in progress** — treat channel content like the rest of your workspace data today. SFU-tier large calls and push delivery are also on the roadmap (see the [roadmap](/#roadmap)). ## Further reading - [Notifications & Inbox](/docs/guides/notifications/) — how messages become notifications - [Collaboration](/docs/guides/collaboration/) — document presence and cursors - [Hub](/docs/guides/hub/) — running an always-on relay --- ## Notifications & Inbox **You will learn** - How notifications are derived locally from synced changes - The rule priority order and its edge semantics - How read state works (watermarks + mention acks) - Badges, mutes, do-not-disturb, and inbox triage ## Overview There is no notification server. Because every change in the workspace syncs to your device anyway, notifications are **derived locally**: a notifier runs one evaluation per applied change and decides whether it deserves your attention. Your read state is itself a private, user-owned node (`InboxState`), so the inbox follows you across devices without anyone else seeing what you've read. ## The rules Rules run in priority order — the highest matching reason wins: ``` mention > dm > assigned > reply > comment > room-mention > keyword ``` Three details keep this trustworthy: - **Edge semantics** — assignment notifies on the *transition* into being assigned. A re-sync or replay of the same change never re-notifies. - **Own-change suppression** — your own edits never notify you. - **Tombstone suppression** — deleted content doesn't resurrect a notification. ## Read state: watermarks + mention acks Read state is the Zulip-style hybrid: - a **per-channel watermark** ("read up to here") advances as you view a channel, clearing activity in bulk; - **explicit mention acks** track each mention individually, so a mention can't be accidentally swept away by scrolling past it. On top of that, inbox items can be triaged: **done**, **saved**, or **snoozed**. ## Badges and alerting Badging is two-tier so the urgent never drowns in the ambient: - a **number** counts things aimed at you — mentions and DMs - a **dot** means there's other activity — replies, comments, room chatter Channels can be **muted**, and a mention **overrides the mute** (you can silence a busy channel without becoming unreachable). **Do-not-disturb windows** suppress alerting overnight; items still accumulate in the inbox. ## The Inbox The Notifications tray (bottom panel) is the triage surface: reason-chip filters (mentions / DMs / assigned / replies…), done/snooze actions, and deep links that jump straight to the message, task, or comment in its own tab. The status-bar bell carries the two-tier badge. ## Delivery to other surfaces Because derivation is local, anything that syncs can notify. Push delivery to closed apps (Web Push, Electron, mobile) rides the hub and is in progress — see the [roadmap](/#roadmap). ## Further reading - [Chat, Presence & Calls](/docs/guides/chat-and-calls/) — where mentions and DMs come from - [Tasks](/docs/guides/tasks/) — assignment notifications - [The Workbench](/docs/guides/workbench/) — the tray and status bar --- ## Rich Text Editor **You will learn** - The editor component and its props - All built-in extensions (20+) - Slash commands and the floating toolbar - How plugins contribute editor extensions - Yjs collaboration and cursor presence ## Overview `@xnetjs/editor` is a collaborative rich text editor built on TipTap v3 with Yjs for real-time CRDT sync. It provides three entry points: | Import | Contents | | ------------------------- | ---------------------------------------- | | `@xnetjs/editor` | Core `Editor` class (framework-agnostic) | | `@xnetjs/editor/react` | React components, hooks, node views | | `@xnetjs/editor/extensions` | All TipTap extensions and utilities | ## RichTextEditor component ```tsx router.push(`/doc/${docId}`)} onImageUpload={handleImageUpload} onFileUpload={handleFileUpload} onEditorReady={(editor) => { ... }} /> ``` ## Built-in extensions ### Block types | Block | Description | Input | | --------------- | ------------------------------------------------------------------------- | ----------------- | | Paragraph | Default text block | — | | Heading (1-6) | Section headings with `#` syntax preview | `# `, `## `, etc. | | Code Block | Syntax-highlighted code with language selector | ` ``` ` | | Blockquote | Quote with `>` prefix preview | `> ` | | Bullet List | Unordered list | `- ` or `* ` | | Ordered List | Numbered list | `1. ` | | Task List | Checkbox list with nesting | `[ ] ` | | Horizontal Rule | Divider | `---` | | Image | CID-based with paste/drop upload, resize handles, alignment | Paste or `/image` | | File | Generic file attachment with upload progress | Drop or `/file` | | Embed | Auto-embed for YouTube, Vimeo, Spotify, Twitter, Figma, CodeSandbox, Loom | Paste URL | | Callout | 6 types (info, tip, warning, caution, note, quote), collapsible | `> [!info]` | | Toggle | Collapsible details/summary sections | `> [toggle]` | | Database Embed | Inline database views (table/board/list/calendar/gallery/timeline) | `/database` | | Mermaid | Diagram blocks (via plugin) | ` ```mermaid ` | ### Marks Bold, italic, strikethrough, code, link, wikilink (`[[page-name]]`), and comment. ### Live preview Obsidian-style inline markdown syntax rendering — bold markers (`**`), italic (`*`), strikethrough (`~~`), and code (`` ` ``) are shown as decorations while typing and hidden when the cursor moves away. ## Slash commands Type `/` to open the command palette. Built-in command groups: - **Basic Blocks** — Text, H1, H2, H3 - **Lists** — Bullet, Numbered, Task - **Blocks** — Quote, Code Block, Divider - **Media** — Image, File, Embed - **Callouts** — Info, Tip, Warning, Caution, Note - **Toggles** — Toggle section - **Data** — Database Plugins can add custom slash commands via `contributes.slashCommands`. ## Floating toolbar The toolbar appears on text selection: - **Desktop** — Bubble menu floating near the selection - **Mobile** — Fixed bottom bar, horizontally scrollable Built-in buttons: Bold, Italic, Strike, Code, Comment | H1, H2, H3 | Bullet, Ordered, Task | Quote, Code Block, Divider. Plugins can add toolbar buttons via `EditorContribution.toolbar`. ## Drag and drop Three integrated plugins handle block-level drag and drop: - **DragHandle** — Shows a grip icon on hover at the left edge of blocks - **DragDropPlugin** — Handles block reordering via drag - **DropIndicator** — Shows a visual insertion line during drag ## Yjs collaboration The editor binds to a `Y.XmlFragment` inside the Y.Doc via TipTap's `Collaboration` extension. When you pass an `awareness` instance, cursor presence is shown automatically: - Remote cursors rendered as colored carets with DID-derived identicon avatars - Selections shown as translucent highlights in the user's color - Hover over a cursor to see the user label ### Comment anchors Comments are positioned using Yjs relative positions (`captureTextAnchor` / `resolveTextAnchor`). This means comment positions survive concurrent edits — if someone inserts text before your comment, the anchor moves with the text. ## Plugin extensions Plugins contribute editor extensions through the contribution system: ```ts // In a plugin manifest contributes: { editorExtensions: [{ id: 'my-extension', extension: MyTipTapExtension, priority: 100, toolbar: { icon: MyIcon, title: 'My Tool', group: 'insert', action: (editor) => editor.chain().focus().insertMyThing().run() } }], slashCommands: [{ id: 'my-command', name: 'My Block', execute: ({ editor, range }) => { ... } }] } ``` The Electron app collects plugin extensions via `useEditorExtensionsSafe()` and passes them to ``. Plugin extensions are loaded before the editor mounts to prevent crashes when Yjs content contains nodes from unregistered extensions. ## Embed providers URLs pasted into the editor are automatically detected and embedded for 7 services: | Provider | URL Pattern | | ----------- | ------------------------------- | | YouTube | `youtube.com/watch`, `youtu.be` | | Vimeo | `vimeo.com` | | Spotify | `open.spotify.com` | | Twitter/X | `twitter.com`, `x.com` | | Figma | `figma.com` | | CodeSandbox | `codesandbox.io` | | Loom | `loom.com` | ## Further reading - [Collaboration Guide](/docs/guides/collaboration/) — Real-time editing patterns - [Plugin Development](/docs/guides/plugins/) — Contributing editor extensions - [useNode](/docs/hooks/usenode/) — The hook that provides the editor --- ## Infinite Canvas **You will learn** - How the infinite canvas works - The spatial index (R-tree) for viewport culling - Layout algorithms (ELK.js, grid, circle) - The Canvas component and useCanvas hook - How canvas state syncs via Yjs ## Overview `@xnetjs/canvas` provides an infinite, zoomable 2D surface where users can place, connect, and arrange nodes. The canvas supports real-time collaboration via Yjs — multiple users can simultaneously add, move, and connect nodes. ## Canvas component ```tsx ; } // Custom node content onNodeDoubleClick={(id) => open(id)} onBackgroundClick={() => deselect()} config={{ minZoom: 0.1, maxZoom: 3, gridSize: 20, showGrid: true }} /> ``` ### Keyboard shortcuts | Shortcut | Action | | ---------------------- | --------------------- | | `Delete` / `Backspace` | Delete selected nodes | | `Cmd+A` | Select all | | `Escape` | Clear selection | | `Cmd+1` | Fit to content | | `Cmd+0` | Reset view | ### Mouse and touch interaction - **Scroll** — Pan the canvas - **Ctrl/Cmd + Scroll** — Zoom - **Two-finger pinch** — Zoom (trackpads and touch screens, including Safari gestures) - **Click node** — Select it - **Click edge** — Select it (edges have generous invisible hit areas) - **Shift/Cmd + Click** — Additive selection - **Drag node** — Move it - **Drag resize handles** — Resize (8 handles on selection) - **Drag a connector handle** — Draw a new edge to another node (handles appear on hover) - **Double-click** — Open node, or edit its text in place ## Editing on the canvas Nodes and edges are directly editable without leaving the canvas: - **Edges** — click to select; a floating toolbar offers a label input, an edge-kind picker, reverse direction, and delete. - **Drag-to-connect** — drag from a node's connector handle (shown on hover) and drop on another node to create an edge. - **Node text** — double-click a canvas-native node (shape, note) to edit its text inline. Source-backed cards (a page or database dropped onto the canvas) keep their source's title; press `F2` or use the Rename action to give the card a local alias instead. All edits go through Yjs transactions and sync live to collaborators. ## useCanvas hook The primary hook that wires together the store, viewport, and layout engine: ```ts const { // State nodes, edges, selectedNodeIds, viewport, // Node operations addNode, updateNodePosition, removeNode, // Edge operations addEdge, removeEdge, // Selection selectNode, selectAll, clearSelection, deleteSelected, // Viewport pan, zoomAt, fitToContent, resetView, // Layout autoLayout, layoutSelected, // Queries findNodeAt, findNodesInRect, getVisibleNodes } = useCanvas({ doc: ydoc, config }) ``` ## Spatial index The canvas uses an R-tree (`rbush`) for efficient spatial queries. This enables viewport culling — only nodes visible on screen need to be rendered. ```ts // Find all nodes in the current viewport const visibleIds = store.getVisibleNodes(viewport.getVisibleRect()) // Find the topmost node at a point const nodeId = store.findNodeAt(point) // Find all nodes overlapping with a given node const overlapping = store.findIntersecting(nodeId) ``` The spatial index is automatically updated when nodes are added, moved, or removed. ## Layout algorithms The `LayoutEngine` supports automatic layout via ELK.js and two built-in algorithms: ### ELK.js layouts ```ts await autoLayout({ algorithm: 'layered', // Sugiyama/hierarchical direction: 'RIGHT', // RIGHT, LEFT, DOWN, UP nodeSpacing: 50, layerSpacing: 100, edgeRouting: 'ORTHOGONAL' // POLYLINE, ORTHOGONAL, SPLINES }) ``` Available algorithms: `layered`, `force`, `mrtree`, `radial`, `stress`, `box`. ### Grid layout ```ts layoutEngine.layoutGrid(nodes, { columns: 4, spacing: 20, padding: 50 }) ``` ### Circle layout ```ts layoutEngine.layoutCircle(nodes, { radius: 300 // Auto-calculated if omitted }) ``` Nodes with `properties.fixed = true` keep their positions during layout. ## Viewport The `Viewport` class manages the camera: - **`pan(dx, dy)`** — Move by screen-space delta - **`zoomAt(x, y, factor)`** — Zoom while keeping the point under cursor stationary - **`fitToRect(rect, padding)`** — Fit viewport to show a rectangle (never zooms beyond 100%) - **`reset()`** — Return to origin at zoom 1 - **`screenToCanvas(x, y)`** — Convert screen coordinates to canvas space - **`canvasToScreen(x, y)`** — Convert canvas coordinates to screen space - **`getVisibleRect()`** — The canvas-space rectangle currently on screen ## Data storage Canvas state is stored in three Yjs maps inside the Y.Doc: | Map | Contents | | ---------- | --------------------------------- | | `metadata` | Title, created/updated timestamps | | `nodes` | `CanvasNode` objects keyed by ID | | `edges` | `CanvasEdge` objects keyed by ID | All mutations go through Yjs transactions, so changes sync automatically to other peers. The spatial index updates reactively when the Yjs maps change. ## Node types ```ts interface CanvasNode { id: string type: string // 'page', 'database', 'note', etc. position: { x: number y: number width: number // Default: 200 height: number // Default: 100 rotation?: number zIndex?: number collapsed?: boolean } properties: Record linkedNodeId?: string // Link to a page/database node } ``` Edges connect nodes with optional labels, arrow markers, and routing styles (bezier or orthogonal). ## Comments The canvas supports spatial comments via `useCanvasComments`: - **Position pins** — Fixed canvas coordinates. Never orphaned. - **Object-attached pins** — Follow a node's position. Become orphaned when the node is deleted. ## Further reading - [Collaboration Guide](/docs/guides/collaboration/) — Real-time editing patterns - [Sync Guide](/docs/guides/sync/) — How Yjs sync works --- ## Forms **You will learn** - How a form is just another database view - Building questions, show-if rules, and the confirmation screen - Sharing a public link that needs no xNet account - How anonymous submissions become signed rows (the drain model) ## A form is a view Open any database and add a view of type **Form** (the `+` next to the view tabs). Like Notion, the form belongs to the database: every question maps to a field, and every submission becomes a new row. The form view has two tabs: - **Build** — pick which fields are asked, reorder them, override labels and helper text, mark questions required, and add per-question *show only when…* rules (for example, ask for a deadline only when priority is "High"). You also set the submit-button label, the confirmation screen, and the **Accepting responses** toggle here. - **Preview** — the live form. Submitting from Preview creates a real row, so workspace members can use it for internal intake immediately. Show-if rules use the same operators as view filters and are evaluated against the in-progress answers, so hidden questions never block submission: a required question that is hidden by its rule is simply not required. Computed and automatic fields (formula, rollup, created, …) can never be asked. Person, relation, and file questions work on workspace forms but are excluded from public ones. ## Sharing a public link Click **Share form publicly** in the strip above the form. Your device mints a high-entropy token on your hub and publishes a *sanitized snapshot* of the form — just the questions, types, and select options, never your workspace data. The public URL looks like: ``` https://your-app.example/form/?hub= ``` Anyone with the link can respond — no account, no app install. The page is completely session-less. The hub stores only a **hash** of the token (like share-link secrets), so the full URL exists only on the device that created it. Revoke the link at any time from the same strip; flip **Accepting responses** off to close the form while keeping the link alive. Public submissions pass a layered anti-spam gate on the hub: an invisible honeypot field, per-IP rate limits, and a payload size cap. ## How responses become rows xNet's hub never writes workspace data — every change in the log is signed by a user device. Public form submissions therefore land in a durable **inbox** on the hub, and one of your signed-in devices *drains* it: each pending submission is validated against the current fields, written as a `DatabaseRow` under your identity, and acknowledged. This usually happens within a minute of your app being open. Two properties of the drain are worth knowing: - **Idempotent end to end.** The respondent's browser keeps an idempotency nonce, the inbox dedupes on it, and the row id is derived from it — a retried submit, a crashed drain, or two of your devices racing all converge on exactly one row. - **Nothing is silently dropped.** If a field was deleted or retyped after someone submitted, the submission is marked *rejected* and kept on the hub for review; the status bar shows a `📥` chip whenever pending or rejected submissions exist. Rows created by a form carry a `submissionMeta` property (`via: 'form'`, the view id, the receive time, and the nonce), so you can filter or audit form-created rows like any other data. --- ## DevTools **You will learn** - How to enable and use the debug panels (9 core + AuthZ panel) - What each panel shows and how to read it - The event bus instrumentation system - How to integrate DevTools into your app ## Quick start Wrap your app with `XNetDevToolsProvider`. In production builds, it tree-shakes to zero bytes. ```tsx ``` **Toggle:** `Ctrl+Shift+D` (or `Cmd+Shift+D` on Mac), or click the floating wrench button. ## The panels ### Nodes Browse every node in the NodeStore. Features: - Full-text search across IDs, schemas, and properties - Filter by schema type - Show/hide deleted nodes - Click a node to see its full properties, timestamps, and author DID - Copy all nodes as JSON Data refreshes every 2 seconds and on live store events. ### Changes Chronological timeline of all mutations with Lamport clock ordering: - Color-coded by operation: green (create), blue (update), red (delete), yellow (restore), purple (remote), amber (conflict) - Filter by node ID or event type - Auto-scroll toggle to follow new events - Click any change for the full JSON payload Keeps the last 1000 events. ### Sync P2P connection status and peer monitoring: - Connection status indicator (connected/connecting/disconnected/error) - Peer list with connection times - Sent/received/error counters - Scrolling event log with timestamps - Toggle sync debug logging (`localStorage xnet:sync:debug`) ### Yjs Y.Doc structure inspector with three sub-views: - **Updates** — Live stream of Yjs update events with local/remote indicators and byte sizes - **Structure** — Interactive tree view of Y.Doc shared types (Map, Array, Text, XmlFragment). Expandable nodes, color-coded by type, depth-limited to 5 levels. - **State Vectors** — ClientID clock values with progress bars. Shows how far each peer has synced. Select a document from the sidebar to inspect its internals. ### Queries Performance profiler for all active hooks: - Lists every `useQuery`, `useMutate`, and `useNode` instance - Shows schema, mode (list/single/filtered/document), caller source location - Tracks update count, result count, average and peak render time - Warnings: amber for >16ms (dropped frame), red for >50ms - Sort by most updates, slowest render, or most recent Source locations are extracted from stack traces automatically. ### Telemetry Security events and performance metrics, split into three tabs: - **Security** — Network health score, crash entries, security events by severity, peer reputation scores with breakdown - **Performance** — Metric groups with bucket distribution charts (time ranges: \<10ms, 10-50ms, 50-100ms, etc.) - **Consent** — Current telemetry tier (off/local/crashes/anonymous) ### Schemas All registered schemas and their properties: - Schema list with node counts and property counts - Property details: type (color-coded), required flag, config summary - Raw schema JSON dump - Built-in vs. user-defined badges ### Seed Create sample data for testing: - **Create Sample Page** — Rich document with headings, lists, callouts, code blocks, Mermaid diagrams, comments with text anchors, and change history - **Create Sample Database** — 15-column database with all property types, 5 rows, view configs, and comments ### History Full change history and time travel for individual nodes. Seven sub-tabs: - **Timeline** — Scrub through all changes with a slider. See materialized state at any point. - **Diff** — Compare two points in time. Shows added/modified/removed properties with before/after values. - **Blame** — Per-property attribution: who last changed each field, when, and how many times. - **Audit** — Filterable audit log with operation breakdown (create/update/delete/restore). - **Verification** — Check hash chain integrity. Reports valid/invalid, verified hashes, chain links, forks. - **Storage** — Storage metrics, prunable changes, estimated recovery bytes. - **Document** — Yjs snapshot timeline. Compare snapshots with size deltas and content diffs. ### AuthZ Live authorization inspector for the [encryption-first access control system](/docs/guides/authorization/). Five sub-tabs: - **Playground** — Test `store.auth.can()` interactively. Select a node and action, see the decision with a full explanation trace including role resolution steps. - **Grants** — All active grants for the selected node: grantee DID, actions, expiry, and revocation controls. Create new grants directly from this panel. - **Timeline** — Chronological log of grant changes — created, revoked, expired — with timestamps and actor DIDs. - **Delegation tree** — Visual tree of UCAN delegation chains. Shows the full proof hierarchy with depth indicators and attenuation warnings. - **Revocation propagation** — Tracks revocation events across peers: which peers have received and applied a revocation, with timing deltas. ## Configuration ```tsx ``` ### Toggle methods | Method | Description | | ------------------------ | --------------------------------- | | `Ctrl+Shift+D` | Keyboard shortcut | | Floating button | Click the wrench icon (draggable) | | 4-finger tap | Mobile | | `useDevTools().toggle()` | Programmatic | ### Persistence The panel remembers its state in `localStorage`: - `xnet:devtools:open` — open/closed - `xnet:devtools:panel` — last active tab - `xnet:devtools:position` — dock position ## Event bus All instrumentation flows through a `DevToolsEventBus` — a typed ring buffer (default 10,000 events): ```ts const { eventBus } = useDevTools() // Subscribe to all events eventBus.subscribe((event) => console.log(event)) // Subscribe to a specific type eventBus.on('sync:peer-connected', (event) => { ... }) // Query eventBus.getEventsByType('store:create') eventBus.getEventsForNode(nodeId) eventBus.getRecent(50) ``` ### Event categories | Category | Events | | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | Store (7) | `store:create`, `store:update`, `store:delete`, `store:restore`, `store:transaction`, `store:remote-change`, `store:conflict` | | Sync (6) | `sync:status-change`, `sync:peer-connected`, `sync:peer-disconnected`, `sync:change-received`, `sync:broadcast`, `sync:error` | | Yjs (4) | `yjs:update`, `yjs:meta-change`, `yjs:state-vector`, `yjs:provider-status` | | Query (6) | `query:subscribe`, `query:unsubscribe`, `query:result`, `query:error`, `mutate:start`, `mutate:complete` | | Telemetry (6) | `telemetry:crash`, `telemetry:usage`, `telemetry:security`, `telemetry:performance`, `telemetry:consent-change`, `telemetry:peer-scores` | ### Instrumentation wiring Instrumentation functions connect data sources to the event bus: ```ts instrumentStore(store, eventBus) // NodeStore events instrumentSync(provider, room, bus) // SyncProvider events instrumentYDoc(doc, docId, bus) // Y.Doc updates instrumentTelemetry(collector, consent, bus) // Telemetry ``` React hooks (`useQuery`, `useNode`) automatically report to DevTools when the provider is present, via `InstrumentationContext`. No manual wiring needed. ## useDevTools hook ```ts const { isOpen, toggle, eventBus, activeNodeId, setActiveNodeId, activePanel, setActivePanel, store, yDocRegistry } = useDevTools() ``` ## Production behavior When `NODE_ENV` is `production`, the DevTools provider renders children unchanged and `useDevTools()` returns inert stubs. The full panel code is tree-shaken out of the bundle — zero bytes in production. --- ## Authorization **You will learn** - The core insight: encryption IS authorization - How to define roles and actions in your schema - How to grant, revoke, and delegate access - How to check permissions with `useCan` and `useGrants` - How key recovery and multi-device access work - The trust model and its security tradeoffs ## The core insight In a decentralized system, the only meaningful access control is **the ability to decrypt**: ``` Can you decrypt it? → You can read it. In the recipients list? → The hub will serve it to you. Schema says you can write? → The client will let you sign a change. ``` Roles, relations, and UCAN delegation are all machinery for deciding **who gets the content key**. Once a user has the key, cryptography enforces their access — no server policy engine required. ## Defining authorization in a schema Add an `authorization` block to any schema to define who can do what: ```ts export const TaskSchema = defineSchema({ name: 'Task', namespace: 'xnet://my-app/', properties: { title: text({ required: true }), assignee: person(), project: relation({ target: 'xnet://my-app/Project' as const }), editors: person({ multiple: true }) }, authorization: { roles: { owner: role.creator(), // whoever created the node assignee: role.property('assignee'), // person() property value editor: role.property('editors'), // person({ multiple: true }) value admin: role.relation('project', 'admin'), // role from a related node viewer: role.relation('project', 'viewer') // role from a related node }, actions: { read: allow('viewer', 'editor', 'admin', 'owner', 'assignee'), write: allow('editor', 'admin', 'owner'), delete: allow('admin', 'owner'), share: allow('admin', 'owner') }, publicProps: ['title'] // properties readable without decryption } }) ``` ### Role types | Builder | Resolves to | | -------------------------------- | -------------------------------------------- | | `role.creator()` | The DID that created the node | | `role.property('field')` | The DID(s) in a `person()` property | | `role.relation('field', 'role')` | Anyone who has that role on the related node | ### Actions | Action | Covers | | -------- | ------------------------------------------------- | | `read` | `store.get`, `useQuery`, hub queries | | `create` | `store.create` (refines `write`) | | `update` | `store.update`, `store.restore` (refines `write`) | | `write` | Coarse mutation policy — the fallback for `create`/`update` when they aren't declared | | `delete` | `store.delete` | | `share` | `store.auth.grant`, `store.auth.revoke` | | `admin` | Hub operational controls | #### Splitting `write`: who may add vs. who may edit `create` and `update` are optional refinements of `write`. Declaring only `write` keeps the classic behavior (one mutation policy). Declaring the refinements expresses **contributor semantics** — "anyone here may post, but only the author may edit": ```ts actions: { read: allow('owner', 'spaceMember'), create: allow('spaceMember'), // members may add new nodes… update: allow('owner', 'spaceAdmin'), // …only the author or an admin edits one write: allow('owner', 'spaceMember'), // fallback for engines without the split delete: allow('owner', 'spaceAdmin'), share: allow('owner', 'spaceAdmin') } ``` Two rules to remember: - **Create checks run against the draft node** (its `createdBy` is the caller), so `role.creator()` always matches on create — leave it out of `create` if you want membership to actually gate who may add. Container relations in the draft (`space`, `channel`, …) resolve normally. - **A `write` grant covers both refinements**; a `create`-only or `update`-only grant covers just itself. The built-in `spaceContributorAuthorization()` block packages this pattern for Space content (chat messages and comments use it). Explicit `deny()` always wins over `allow()`: ```ts actions: { read: allow('viewer').deny('blocked'), // 'blocked' role can never read } ``` ### Public nodes Set `publicProps` to expose specific fields without encryption, or use `PUBLIC` to make the entire node readable by anyone: ```ts authorization: { // ...roles and actions... publicProps: ['title', 'status'], // these fields are unencrypted } ``` For fully public nodes (no access control), use the built-in preset: ```ts export const ArticleSchema = defineSchema({ // ... authorization: presets.public }) ``` ### Permission presets ```ts // Full owner control — only creator can do anything authorization: presets.ownerOnly // Owner + share — owner shares explicit read/write with others via grants authorization: presets.ownerWithShare // Collaborative — creator is owner, any member of a 'workspace' relation can read/write authorization: presets.collaborative({ relation: 'workspace' }) // Fully public — all content is unencrypted and anyone can read authorization: presets.public ``` ## Checking permissions ### `useCan` hook ```tsx function TaskCard({ taskId }: { taskId: string }) { const { canRead, canWrite, canDelete, canShare, loading } = useCan(taskId) if (loading) return null return (
{canWrite && } {canDelete && } {canShare && }
) } ``` `useCan` is reactive — it re-evaluates when grants change or when you switch users. ### `store.auth.can()` ```ts const decision = await store.auth.can({ action: 'write', nodeId: taskId }) // { allowed: true, reason: 'role:owner', cached: false } const decision = await store.auth.can({ action: 'delete', nodeId: taskId }) // { allowed: false, reason: 'no matching role or grant' } ``` ### Explaining a decision For debugging or AI-assisted introspection, use `explain()`: ```ts const trace = await store.auth.explain({ action: 'write', nodeId: taskId }) // { // allowed: true, // subject: 'did:key:z6Mk...', // action: 'write', // nodeId: 'task_abc', // roles: ['owner'], // grants: [], // policyTrace: [ // { rule: 'allow(editor, admin, owner)', matched: 'owner' } // ] // } ``` ## Granting and revoking access ### `useGrants` hook ```tsx function ShareDialog({ taskId }: { taskId: string }) { const { grants, grant, revoke, loading } = useGrants(taskId) return (
{grants.map((g) => (
{g.grantee} — {g.actions.join(', ')}
))}
) } ``` ### `store.auth` API ```ts // Grant access with optional expiry await store.auth.grant({ to: bobDid, actions: ['read', 'write'], resource: taskId, expiresIn: '7d' // or expiresAt: timestamp }) // Revoke a grant (last-admin protection prevents locking yourself out) await store.auth.revoke({ grantId }) // List all grants for a node const grants = await store.auth.listGrants({ nodeId: taskId }) ``` Grants are stored as signed nodes in the NodeStore — they sync, replicate, and benefit from the same CRDT conflict resolution as all other data. ### Delegation (UCAN chains) Any user with the `share` action can delegate their access to another user via UCAN proof chains. Delegation is **attenuated** — you can only delegate up to (not beyond) your own permissions: ```ts // Alice (owner) grants Bob write access await store.auth.grant({ to: bob, actions: ['write'], resource: docId }) // Bob can delegate read access to Carol (subset of Bob's write) await store.auth.grant({ to: carol, actions: ['read'], resource: docId // Bob's grant to Alice is automatically included as proof }) ``` Delegation chains are capped at depth 4 (`maxProofDepth = 4`). Revoking a parent grant cascades to all derived grants. ### Grant expiration Grants with `expiresIn` or `expiresAt` automatically become inactive after their expiry time. A background `GrantExpirationCleaner` prunes expired grants and re-encrypts affected nodes with updated recipient lists. ## How enforcement works ### Local mutations When you call `store.create()`, `store.update()`, or `store.delete()`, the store checks authorization first: ```ts try { await store.update(TaskSchema, taskId, { title: 'New title' }) } catch (err) { if (err instanceof PermissionError) { // err.message: "denied: action=write, subject=did:key:..., role context: [viewer]" } } ``` ### Remote changes When a remote peer's change arrives via sync, the store silently rejects unauthorized changes and emits a `change:rejected` event. The peer also receives a scoring penalty to protect against abuse. ### Yjs documents Collaborative editing (via `useNode`) uses a layered auth model: 1. **Room gate** — only authorized users can join a sync room 2. **Per-update gate** — each incoming Yjs update is checked against `PolicyEvaluator` 3. **At-rest encryption** — Y.Doc state is encrypted with the node's content key Revoking a user from a document immediately kicks them from the room and rotates the content key, so all future updates are encrypted for the new recipient set. ### Hub filtering The hub never decrypts data — it filters queries by recipient lists stored in node metadata. If your DID isn't in the recipients list, the hub doesn't return the node. This is transparent to your app: you write normal queries, unauthorized data is silently excluded. ## Failure modes | Context | When auth fails | Why | | ---------------------------- | ------------------------------------------- | -------------------------------------- | | `store.create/update/delete` | Throws `PermissionError` | Developer should see and handle errors | | `applyRemoteChange` | Silently rejected + `change:rejected` event | Don't crash on bad remote data | | Yjs update | Silently rejected + peer scoring penalty | Don't interrupt editing flow | | Hub query | Node excluded from results (no error) | Transparent access control | ## Trust model **Read access is cryptographically enforced.** If you don't have the content key, you cannot decrypt the data. The hub can't help you because it doesn't hold keys. **Write access is enforced client-side.** A malicious client could skip the `can()` check and broadcast a signed change. The hub and honest peers accept it because the Ed25519 signature is valid. This is an intentional tradeoff: - All changes are signed and part of a tamper-evident hash chain — unauthorized writes are attributable and detectable - Peer scoring penalizes unauthorized write attempts, leading to automatic blocking - Key rotation on revocation means revoked users lose future read access regardless of write-side enforcement For apps where write enforcement must be stronger, self-hosted hubs can add custom policy validation. ## Key resolution When encrypting a node for a recipient, xNet needs their X25519 public key to perform key wrapping. It resolves this in two steps: 1. **Birational conversion** — Ed25519 public keys (from DID:key) can be mathematically converted to X25519 keys without any additional lookup. This works for any DID:key holder. 2. **Hub registry fallback** — For cases where the key holder has registered a separate X25519 key (unusual), the hub maintains a public key registry. This means sharing data with any DID:key holder requires no out-of-band key exchange. ## Key recovery & multi-device ### Seed phrase Your signing key can be derived deterministically from a seed phrase (BIP-39 format). The seed phrase is the root of your identity — back it up carefully. ```ts // Generate a new identity with a recoverable seed const { mnemonic, bundle } = deriveSeedPhrase() // mnemonic: "correct horse battery staple ..." // Recover identity on a new device const recoveredBundle = recoverFromSeedPhrase(mnemonic) // Produces the same DID and key pair ``` ### Multi-device Each device derives the same primary key from the seed, so your DID is the same across devices. When you add a second device: 1. The new device generates its own device-specific encryption key 2. It registers in a device registry (synchronized via the Hub) 3. Your primary key wraps the content keys for each device ### Social recovery As a fallback when the seed phrase is unavailable, xNet supports Shamir's Secret Sharing: split the seed across trusted contacts, any threshold (e.g., 3 of 5) can reconstruct it. ### Encrypted hub backup The hub can store an encrypted backup of your key bundle, unlocked by a passphrase or WebAuthn credential. This is opt-in and the hub never sees the plaintext key. ## Offline authorization By default, authorization decisions are cached with a 5-minute TTL. This means: - The app works offline — cached decisions are used while disconnected - Revocations take at most 5 minutes to propagate to offline users - On reconnect, the cache is revalidated against the current grant state Configure offline behavior per-schema: ```ts authorization: { // ... offlinePolicy: { cacheTTL: 300_000, // 5 minutes (default) maxStaleness: 3_600_000, // 1 hour — refuse to use older cached decisions revalidateOnReconnect: true // (default) revalidate immediately when online } } ``` ## Migration from unencrypted schemas Schemas without an `authorization` block continue to work but emit a console warning in development. To add authorization to an existing schema: 1. Add the `authorization` block with your desired roles and actions 2. Run the `AuthMigrator` utility to batch-encrypt existing nodes: ```ts const migrator = new AuthMigrator(store, encryptionLayer) await migrator.migrateSchema(MySchema, { batchSize: 50, onProgress: ({ done, total }) => console.log(`${done}/${total}`) }) ``` The migration re-encrypts nodes in batches and updates their recipient lists. Existing peers will receive the re-encrypted versions via normal sync. ## Related - [defineSchema](/docs/schemas/defineschema/) — Full schema API reference - [Identity & Keys](/docs/guides/identity/) — DID:key, UCAN tokens, key management - [Cryptography](/docs/concepts/cryptography/) — BLAKE3, Ed25519, XChaCha20, X25519 - [Offline Patterns](/docs/guides/offline/) — Offline cache behavior and sync - [DevTools](/docs/guides/devtools/) — AuthZ panel for live inspection --- ## Sync Guide **You will learn** - How xNet's dual-CRDT sync model works - The signaling server and WebSocket transport - How Yjs updates are signed, rate-limited, and verified - The SyncManager lifecycle and configuration - How to debug sync issues ## The dual-CRDT model xNet uses two complementary sync strategies, each optimized for a different data shape: | Data type | Mechanism | Conflict resolution | | ---------------------------- | ----------------------------- | ---------------------------------------------- | | Rich text (editor content) | Yjs CRDT | Character-level merge — no conflicts by design | | Structured data (properties) | NodeStore with Lamport clocks | Field-level Last-Writer-Wins (LWW) | Both strategies sync over the same multiplexed WebSocket connection. ### Yjs for rich text Each node with editor content gets a `Y.Doc`. Yjs handles character-level CRDT merging internally — two users typing in the same paragraph at the same time will see their edits merge without conflict. The sync protocol exchanges state vectors and diffs: 1. Peer A sends sync-step1 (its state vector) 2. Peer B responds with sync-step2 (the diff A is missing), plus its own sync-step1 3. After the initial exchange, incremental updates flow as `sync-update` messages ### NodeStore for structured data Property changes (title, status, assignee, etc.) go through the `Change` pipeline: ```ts interface Change { id: string type: string payload: T hash: ContentId // cid:blake3:... content-addressed parentHash: ContentId | null // Hash chain linkage authorDID: DID signature: Uint8Array // Ed25519 over hash lamport: LamportTimestamp // Causal ordering } ``` Each change is signed with Ed25519, content-addressed with BLAKE3, and linked into a hash chain. Conflicts are resolved by comparing Lamport timestamps — higher time wins, with DID string as a deterministic tie-breaker. ### MetaBridge: the one-way bridge The `MetaBridge` keeps the Y.Doc's metadata map in sync with NodeStore properties, but the data flow is intentionally **one-directional**: ``` NodeStore → MetaBridge → Y.Doc meta map (write) Y.Doc meta → Editor UI (read-only display) Editor UI → mutate() → NodeStore (signed writes) ``` This prevents malicious Yjs updates from poisoning structured data. Property changes always go through `mutate()` → signed Change pipeline, never through the Yjs document directly. ## Yjs security Every Yjs update transmitted over the network is wrapped in a `SignedYjsEnvelope`: ```ts interface SignedYjsEnvelope { update: Uint8Array // Raw Yjs update bytes authorDID: string // did:key:... signature: Uint8Array // Ed25519 over BLAKE3(update) timestamp: number clientId: number // Yjs clientID bound to this DID } ``` ### Signing and verification flow ```mermaid flowchart LR subgraph Signing A["Yjs update bytes"] --> B["BLAKE3 hash"] B --> C["Ed25519 sign\n(private key)"] C --> D["SignedYjsEnvelope\n+ DID, clientId, ts"] end subgraph Verification E["Receive envelope"] --> F["Parse DID →\npublic key"] E --> G["BLAKE3 hash\nupdate bytes"] F --> H["Ed25519 verify\nsig vs hash"] G --> H H -->|valid| I["Apply update"] H -->|invalid| J["Reject + penalize"] end D -.->|network| E ``` **Signing:** BLAKE3 hash the raw Yjs update bytes → Ed25519 sign the hash with the author's private key → attach envelope metadata (DID, clientId, timestamp). **Verification:** Parse the author's DID to extract their Ed25519 public key (self-certifying — no resolver needed) → BLAKE3 hash the update bytes → verify the Ed25519 signature against the hash. ### Rate limiting The `YjsRateLimiter` enforces per-peer limits: | Limit | Value | | ------------------ | --------------- | | Max update size | 1 MB | | Updates per second | 30 (+ 10 burst) | | Updates per minute | 600 | | Max document size | 50 MB | | Sync chunk size | 256 KB | Large initial syncs are automatically chunked into 256 KB pieces and reassembled on the receiving end. ### Peer scoring The `YjsPeerScorer` tracks peer behavior. Peers start at score 100: | Violation | Penalty | | ------------------- | ------------------------ | | Invalid signature | -30 (auto-block after 3) | | Unsigned update | -20 | | Unattested clientId | -15 | | Oversized update | -10 | | Rate exceeded | -5 | Score thresholds: **warn** at 50, **throttle** at 30, **block** at 10. Peers recover +1 per tick if they have no violations for 60 seconds. ### ClientID attestation Yjs assigns random integer clientIDs with no identity binding. xNet fixes this with signed attestations: ```ts interface ClientIdAttestation { clientId: number did: string signature: Uint8Array // Ed25519 over BLAKE3("clientid-bind:{clientId}:{did}:{room}:{expiresAt}") expiresAt: number room: string } ``` A `ClientIdMap` maintains bidirectional `clientId ↔ DID` mappings. When an envelope arrives, `validateClientIdOwnership` checks that the envelope's clientID matches the attested DID. ### Update batching The `YjsBatcher` collects individual Yjs updates (around 5/second from keystrokes) and flushes them in batches every 2 seconds (or at most 50 updates per batch). This reduces signature operations from ~5/sec to ~0.5/sec. Batches flush early on paragraph breaks. ### Hash-at-rest integrity Persisted Yjs state is BLAKE3-hashed before writing to storage. On load, the hash is re-verified to detect storage-level corruption before it propagates to peers. After 100 incremental updates or 1 hour, the document is compacted (re-encoded from scratch). ## SyncManager The `SyncManager` is the top-level orchestrator that wires everything together. ### Configuration ```ts interface SyncManagerConfig { nodeStore: NodeStore storage: NodeStorageAdapter signalingUrl: string // WebSocket URL, e.g., 'wss://hub.xnet.dev' poolSize?: number // Default: 50 warm documents trackTTL?: number // Default: 7 days authorDID?: string blobStore?: BlobStoreForSync } ``` ### Lifecycle ``` start → connected → drainOfflineQueue → sync ↕ disconnected → enqueueLocally ↕ stop → flushDirtyDocs → pruneRegistry → save ``` 1. **`start()`** — Load registry and offline queue from storage, connect WebSocket, join rooms for all tracked nodes, start blob sync. 2. **On connected** — Drain offline queue (broadcast queued updates), re-send sync-step1 for all pooled documents. 3. **`acquire(nodeId)`** — Load Y.Doc from pool or storage, set up broadcast listener, join room, send sync-step1. Used by `useNode`. 4. **`release(nodeId)`** — Decrement refcount. Doc stays warm in the pool and continues syncing in the background. 5. **`track(nodeId, schemaId)`** — Add to the persistent registry for background sync. Tracked nodes are synced even when no component has them open. 6. **`stop()`** — Leave all rooms, disconnect, flush dirty docs to storage, prune expired registry entries, save state. ### NodePool The pool manages Y.Doc instances in three states: - **Active** (refCount > 0) — Currently used by a component. Never evicted. - **Warm** (refCount = 0) — Released but kept in memory for quick re-acquisition. Evicted via LRU when pool is full. - **Cold** — Evicted to storage. Loaded on next `acquire()`. Dirty documents are persisted on a debounced 2-second timer. ### Registry The persistent tracked-node set that survives app restarts: ```ts interface TrackedNode { nodeId: string schemaId: string lastOpened: number lastSynced: number pinned: boolean // Pinned nodes never expire } ``` Tracked nodes with no activity for `trackTTL` (default 7 days) are pruned on shutdown, unless pinned. ### OfflineQueue When the WebSocket is disconnected, local Y.Doc updates are enqueued: ```ts interface OfflineQueue { enqueue(nodeId: string, update: Uint8Array): Promise drain(handler): Promise readonly size: number } ``` - Max 1000 entries (FIFO — oldest dropped if full) - Persisted immediately on enqueue for crash resilience - Drained in order on reconnect; stops on first error (entry stays at front for retry) ## Transport ### ConnectionManager A single multiplexed WebSocket connection handles all documents (O(1) connections, not O(N) per doc): - Room-based pub/sub: `subscribe(topics)`, `publish(topic, data)` - Auto-reconnect with configurable delay and max attempts - On reconnect: automatically re-subscribes to all rooms ### WebSocketSyncProvider A per-document provider that implements the Yjs sync protocol over the shared connection: 1. On connect — subscribe to room, broadcast sync-step1 (state vector) 2. On sync-step1 from peer — respond with sync-step2 (diff) 3. On sync-step2 — apply update, mark synced 4. On sync-update — apply incremental update 5. Awareness updates (cursor position, user name) flow alongside document updates ## Lamport clocks xNet uses Lamport clocks for causal ordering of structured data changes: ```ts interface LamportTimestamp { time: number author: DID } ``` - `tick(clock)` — increment time by 1, return `[newClock, timestamp]` - `receive(clock, receivedTime)` — set time to `max(ours, received)` (no increment) - `compareLamportTimestamps(a, b)` — compare by time first, then DID string as tie-breaker - `serializeTimestamp()` — zero-padded 16-digit time + DID for lexicographic sorting - All functions are pure — they return new objects, never mutate ### Hash chains Changes link to their parent via `parentHash`, forming a directed acyclic graph: - `validateChain()` — verify all hashes are correct - `detectFork()` — find where two changes share a parent - `topologicalSort()` — deterministic replay order (parents before children) - `getForks()` — returns detailed fork info with branches sorted by Lamport Forks are valid — they represent concurrent edits, not errors. Field-level LWW resolves them deterministically. ## Debugging Enable debug logging in the browser console: ```js localStorage.setItem('xnet:sync:debug', 'true') ``` The DevTools sync panel shows: - Connection status and peer count - Document pool state (active, warm, cold) - Registry entries with last-synced timestamps - Offline queue size - Per-peer scoring data Use `pnpm dev:both` in the Electron app to run two instances for testing sync behavior locally. --- ## Version Compatibility **You will learn** - How protocol versioning and schema versioning work - How to create migrations with lenses - How version negotiation keeps peers compatible - How to use CLI tools for schema management - How to diagnose and repair data issues ## Overview xNet uses a **translate-on-read** approach to version compatibility: ```mermaid flowchart LR subgraph Storage V1["v1 data"] V2["v2 data"] V3["v3 data"] end subgraph "Read Path" L1["Lens v1→v2"] L2["Lens v2→v3"] end subgraph App Current["Current Schema (v3)"] end V1 --> L1 --> L2 --> Current V2 --> L2 V3 --> Current ``` 1. Data is stored in its original format 2. Migrations are applied when reading, not when writing 3. Old clients can still read new data (graceful degradation) 4. No batch migrations required This means you can ship schema changes incrementally without breaking existing clients. ## Protocol versioning The sync protocol is versioned separately from schemas. Every `Change` includes a `protocolVersion`: ```ts interface Change { id: string type: string payload: T protocolVersion: number // Currently: 1 hash: ContentId parentHash: ContentId | null authorDID: DID signature: Uint8Array lamport: LamportTimestamp } ``` ### Version compatibility | Your Version | Peer Version | Behavior | | ------------ | ------------ | -------------------------------------------------- | | v1 | v1 | Full compatibility | | v1 | v0 (legacy) | Full backward compatibility | | v1 | v2+ | Partial — unknown fields preserved, warning logged | ### Feature negotiation When peers connect, they negotiate a common feature set: ```mermaid sequenceDiagram participant A as Client A (v1.2) participant B as Client B (v1.0) A->>B: Hello {features: [yjs, change_v2, compression]} B->>A: Hello {features: [yjs, change_v1]} Note over A,B: Negotiate intersection A->>B: Using {features: [yjs, change_v1]} Note over A,B: A downgrades to v1 format ``` ```ts // Handshake exchange { clientVersion: '1.2.0', protocolVersion: 1, features: ['yjs_sync', 'change_v2', 'signatures', 'compression'] } ``` The negotiator finds the intersection of features both peers support. If a required feature is missing, the connection is downgraded or rejected. ## Schema versioning Every schema should have a semantic version: ```ts const TaskSchema = defineSchema({ name: 'Task', version: '2.0.0', // Major.Minor.Patch properties: { title: { type: 'text' }, status: { type: 'select', options: ['todo', 'doing', 'done'] }, priority: { type: 'select', options: ['low', 'medium', 'high'] } } }) ``` ### Version bump rules | Change Type | Version Bump | Example | | ------------------------------- | ------------ | ----------------- | | Add optional field | Minor | `1.0.0` → `1.1.0` | | Add required field with default | Minor | `1.0.0` → `1.1.0` | | Remove field | Major | `1.0.0` → `2.0.0` | | Rename field | Major | `1.0.0` → `2.0.0` | | Change field type | Major | `1.0.0` → `2.0.0` | | Fix bug in migration | Patch | `1.0.1` → `1.0.2` | ### Schema change classification Every schema change falls into one of three risk categories: ```mermaid flowchart TB subgraph "SAFE - Ship Anytime" SAFE1["Add optional properties"] SAFE2["Add new schemas"] SAFE3["Add new change types"] SAFE4["Add new select options"] SAFE5["Make required → optional"] end subgraph "CAUTION - Plan Ahead" CAUTION1["Add required properties"] CAUTION2["Remove properties"] CAUTION3["Make optional → required"] CAUTION4["Change property defaults"] end subgraph "BREAKING - Requires Migration" DANGER1["Change property type"] DANGER2["Rename properties"] DANGER3["Change schema namespace"] DANGER4["Remove select options"] end style SAFE1 fill:#c8e6c9 style SAFE2 fill:#c8e6c9 style SAFE3 fill:#c8e6c9 style SAFE4 fill:#c8e6c9 style SAFE5 fill:#c8e6c9 style CAUTION1 fill:#fff3e0 style CAUTION2 fill:#fff3e0 style CAUTION3 fill:#fff3e0 style CAUTION4 fill:#fff3e0 style DANGER1 fill:#ffcdd2 style DANGER2 fill:#ffcdd2 style DANGER3 fill:#ffcdd2 style DANGER4 fill:#ffcdd2 ``` #### Classification matrix | Change Type | Forward Safe | Backward Safe | Auto-Migrate | Manual Action | | ---------------------- | ------------ | ------------- | ------------ | ---------------- | | Add optional property | Yes | Yes | N/A | None | | Add required property | No | Yes | Yes | Define default | | Remove property | Yes | No | Yes | None | | Change property type | No | No | Maybe | Define transform | | Rename property | No | No | Yes | Define mapping | | Add select option | Yes | Yes | N/A | None | | Remove select option | No | No | Maybe | Define fallback | | Make optional→required | No | Yes | Yes | Define default | | Make required→optional | Yes | Yes | N/A | None | **Legend:** - **Forward Safe**: Old clients can read data created by new clients - **Backward Safe**: New clients can read data created by old clients - **Auto-Migrate**: The system can generate migration code automatically #### Migration wizard Use the **Migrate** panel in DevTools to: 1. **Analyze** - Scan your store for schema changes 2. **Review** - See changes grouped by risk level 3. **Generate** - Auto-generate lens code for migrations 4. **Test** - Validate migrations on sample data 5. **Apply** - Apply migrations to your store ```mermaid flowchart TB START["Schema Change Detected"] ANALYZE["Analyze Changes"] CLASSIFY["Classify Risk"] START --> ANALYZE ANALYZE --> CLASSIFY CLASSIFY -->|"Safe"| AUTO["Auto-apply"] CLASSIFY -->|"Caution"| REVIEW["Review & Confirm"] CLASSIFY -->|"Breaking"| WIZARD["Migration Wizard"] WIZARD --> LENS["Generate Lens Code"] LENS --> TEST["Test Migration"] TEST -->|"Pass"| APPLY["Apply to Store"] TEST -->|"Fail"| EDIT["Edit Lens"] EDIT --> TEST AUTO --> DONE["Done"] REVIEW --> APPLY APPLY --> DONE style AUTO fill:#c8e6c9 style REVIEW fill:#fff3e0 style WIZARD fill:#ffcdd2 ``` ## Migrations with lenses Lenses transform data between schema versions. They're bidirectional — you can upgrade and downgrade. ```mermaid flowchart LR subgraph "Lens" UP["up()"] DOWN["down()"] end V1["v1.0.0"] -->|upgrade| UP --> V2["v2.0.0"] V2 -->|downgrade| DOWN --> V1 ``` ### Creating a lens ```ts const taskV1ToV2: SchemaLens = createLens({ from: '1.0.0', to: '2.0.0', // Transform v1 → v2 up(node) { return { ...node, priority: node.priority ?? 'medium' // Add default } }, // Transform v2 → v1 down(node) { const { priority, ...rest } = node return rest // Remove new field } }) ``` ### Registering lenses ```ts const registry = new LensRegistry() // Register all lenses for a schema registry.register('Task', taskV1ToV2) registry.register('Task', taskV2ToV3) // The registry automatically chains lenses // v1 → v2 → v3 happens automatically ``` ```mermaid flowchart LR V1["v1.0.0"] --> L1["Lens 1"] --> V2["v2.0.0"] --> L2["Lens 2"] --> V3["v3.0.0"] style V1 fill:#fee style V2 fill:#ffe style V3 fill:#efe ``` The registry finds the shortest path between any two versions and chains the lenses automatically. ### Reading with migration ```ts const store = new NodeStore({ lensRegistry: registry }) // Read with automatic migration const task = await store.getWithMigration(taskId, { targetVersion: '3.0.0' }) // Data is transformed to v3 format // Original data unchanged in storage const original = await store.get(taskId) // Still in its original version ``` ## Common migration patterns ### Adding a field ```ts const addPriority = createLens({ from: '1.0.0', to: '1.1.0', up: (node) => ({ ...node, priority: 'medium' // Sensible default }), down: (node) => { const { priority, ...rest } = node return rest } }) ``` ### Renaming a field ```ts const renameDueDate = createLens({ from: '1.0.0', to: '2.0.0', up: (node) => { const { due_date, ...rest } = node return { ...rest, dueDate: due_date } }, down: (node) => { const { dueDate, ...rest } = node return { ...rest, due_date: dueDate } } }) ``` ### Splitting a field ```ts const splitName = createLens({ from: '1.0.0', to: '2.0.0', up: (node) => { const [firstName, ...rest] = (node.name || '').split(' ') return { ...node, firstName, lastName: rest.join(' ') } }, down: (node) => ({ ...node, name: `${node.firstName} ${node.lastName}`.trim() }) }) ``` ## React integration ### useQuery with migrations ```tsx function TaskList() { const { data: tasks } = useQuery({ type: 'Task', targetVersion: '3.0.0' // Migrate to this version }) // All tasks are v3 format, regardless of storage version return tasks.map((task) => ) } ``` ## CLI tools ### Extract schemas ```bash # Extract current schema to JSON xnet schema extract --output schemas/ # Creates schemas/Task.v2.0.0.json ``` ### Compare schemas ```bash # Compare two versions xnet schema diff Task 1.0.0 2.0.0 # Output: # + priority: select (added) # ~ status: text → select (type changed) ``` ### Validate migrations ```bash # Check that lenses are registered for all version pairs xnet migrate validate # Output: # ✓ Task: 1.0.0 → 2.0.0 (lens registered) # ✓ Task: 2.0.0 → 3.0.0 (lens registered) # ✗ Contact: 1.0.0 → 2.0.0 (no lens!) ``` ### Diagnose issues ```bash # Full diagnostic xnet doctor # Output: # Checking nodes... # ✓ 1,234 nodes checked # ✓ All hashes valid # ⚠ 3 nodes have unknown schema types # # Summary: # Errors: 0 # Warnings: 3 # Status: HEALTHY (with warnings) ``` ### Repair data ```bash # Preview what would be fixed xnet repair --dry-run # Apply fixes xnet repair ``` ### Export and import ```bash # Export all data to JSON xnet export --output backup.json # Import with migration xnet import backup.json --migrate-to-current ``` ## Graceful degradation When encountering unknown data, xNet preserves it rather than discarding it: ```mermaid flowchart TD subgraph "New Client (v2)" N1["Create node with\nnew 'priority' field"] end subgraph "Old Client (v1)" O1["Receive node"] O2["Unknown field\n'priority'"] O3["Store as-is\n(preserve field)"] O4["Edit 'title'"] O5["Save node\n(priority intact)"] end N1 --> O1 --> O2 --> O3 --> O4 --> O5 ``` ### Unknown schema type ```ts // Node with unknown schema type const node = { '@type': 'xnet://example.com/FutureType', title: 'Something new', unknownField: { complex: 'data' } } // Old client behavior: // - Stores node as-is // - Can display raw data // - Preserves unknown fields on save ``` ### Unknown property type ```ts // Property with future type const property = { name: 'location', type: 'geo-polygon', // Unknown type value: { points: [...] } } // Old client behavior: // - Preserves value // - Displays as JSON in UI // - Round-trips correctly ``` ## Deprecation policy Features follow a deprecation lifecycle: ```mermaid flowchart LR A["Active"] --> D["Deprecated\n(warning)"] D --> X["Discouraged\n(error)"] X --> R["Removed"] D -.- |"6+ months"| X X -.- |"3+ months"| R ``` | Stage | Behavior | Duration | | ----------- | ---------------------- | ------------ | | Active | Works normally | Indefinite | | Deprecated | Works, warning logged | Min 6 months | | Discouraged | Works, error logged | Min 3 months | | Removed | Feature does not exist | Permanent | Check for deprecations programmatically: ```ts const warnings = checkDeprecations({ protocolVersion: 0, features: ['change_v1'] }) warnings.forEach((w) => { console.warn(`${w.feature}: ${w.message}`) console.warn(` Deadline: ${w.deadline}`) }) ``` ## DevTools panel The Version DevTools panel shows: - Current protocol version - Connected peer versions - Feature negotiation results - Deprecation warnings - Schema version distribution Enable it in the DevTools: ```tsx function App() { return ( ) } ``` ## Best practices 1. **Always provide defaults** when adding fields: ```ts up: (node) => ({ ...node, priority: node.priority ?? 'medium' }) ``` 2. **Test both directions** — migrations should round-trip: ```ts const roundTripped = lens.down(lens.up(original)) expect(roundTripped.title).toBe(original.title) ``` 3. **Keep lenses simple** — one concern per lens, chain for complex migrations 4. **Version bumps are cheap** — don't be afraid to bump minor versions for additive changes 5. **Run `xnet doctor`** in CI to catch issues early ## Further reading - [Sync Guide](/docs/guides/sync/) — How sync works - [Schemas Overview](/docs/schemas/overview/) — Defining schemas - [DevTools](/docs/guides/devtools/) — Debugging tools --- ## Offline Patterns **You will learn** - Why xNet apps work offline by default - How the offline queue captures changes - How changes merge when connectivity returns - Patterns for building resilient offline UIs ## Local-first by default xNet apps don't fetch data from a server — they read from a local database (SQLite, OPFS-backed in modern browsers). This means: - **Queries are instant** — no loading spinners for cached data - **Mutations are immediate** — writes go to local storage first - **The app works offline** — no network required for core functionality - **Sync is eventual** — changes propagate to peers when a connection is available You don't need to add special offline handling. The architecture is offline-first from the ground up. ## How offline sync works ### Normal operation (connected) ``` User edits → Local Y.Doc update → Broadcast via WebSocket → Peers apply → Persist to SQLite ``` ### Offline operation ``` User edits → Local Y.Doc update → OfflineQueue (persisted) → Persist to SQLite ``` ### Reconnection ``` WebSocket connects → OfflineQueue drains → Broadcast queued updates → Exchange state vectors → Merge remote changes ``` The `OfflineQueue` holds up to 1000 entries, persisted to SQLite immediately for crash resilience. On reconnect, entries are drained in order. If a broadcast fails, the entry stays at the front of the queue for retry. ## Patterns ### Optimistic UI Since mutations write to local storage first, the UI updates immediately. No optimistic update logic is needed — the data is already local: ```tsx function TaskList() { const { data: tasks } = useQuery(TaskSchema) const mutate = useMutate() const addTask = () => { // This writes locally and returns immediately mutate.create(TaskSchema, { title: 'New task', status: 'todo' }) // useQuery re-renders with the new task — no loading state } return (
{tasks.map((t) => ( ))}
) } ``` ### Connection status indicator ```tsx function NetworkBadge() { const sync = useSyncManager() return ( {sync.status === 'connected' ? 'Online' : 'Offline'} {sync.queueSize > 0 && ` (${sync.queueSize} pending)`} ) } ``` ### Background sync for important nodes Track nodes so they sync even when no component has them open: ```tsx const sync = useSyncManager() // Pin a node — it syncs in the background and never expires from the registry sync.track(nodeId, schemaId) ``` Tracked nodes stay in the sync registry for 7 days by default. Pinned nodes never expire. ### Handling merge results When offline changes merge with remote changes, both Yjs (rich text) and the NodeStore (properties) resolve conflicts automatically: - **Rich text** — Yjs CRDT merges character-by-character. Both users' edits appear. - **Properties** — Field-level LWW. The change with the higher Lamport timestamp wins. If two users edit different fields on the same node, both changes are preserved. There are no merge conflict dialogs. The system is designed so that all peers converge to the same state deterministically. ### Offline-aware forms For forms that create multiple related nodes, use `mutate([...])` to execute a batched write: ```tsx const { mutate } = useMutate() const createProjectWithTasks = async () => { const result = await mutate([ { type: 'create', schema: ProjectSchema, id: 'project-acme', data: { name: 'Acme' } }, { type: 'create', schema: TaskSchema, data: { title: 'Setup', project: 'project-acme' } }, { type: 'create', schema: TaskSchema, data: { title: 'Launch', project: 'project-acme' } } ]) // All three writes run through one mutate call. // The known project ID keeps references stable while offline and after sync. } ``` ## Storage xNet uses SQLite through the `@xnetjs/storage` adapter. Data is organized per-node: - **Y.Doc state** — Full Yjs document state, BLAKE3-hashed for integrity - **Node properties** — Structured data from the NodeStore - **Offline queue** — Pending updates waiting to sync - **Registry** — Tracked node set with last-synced timestamps - **Blobs** — File attachments stored locally The storage layer handles serialization, compression, and integrity checks. You don't interact with SQLite directly. ## Durable storage In the browser, xNet's SQLite database lives in the Origin Private File System, which starts out as **best-effort** storage: the browser may evict it under pressure. xNet asks the browser to upgrade the origin to **persistent** via `navigator.storage.persist()`, but each browser decides that request differently: | Browser | Prompt? | When it grants | Eviction while best-effort | | --------------- | ------- | ------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------- | | Chrome / Edge | No | Silently, once the site is installed, has notification permission, is regularly used, or is a top bookmark — re-evaluated on every request | Only under disk pressure (least-recently-used origins) | | Safari | No | Only when xNet runs as an installed web app (Add to Dock / Add to Home Screen) | Site data is deleted after 7 days of Safari use without visiting the site | | Firefox desktop | Yes | When you click **Allow** in its permission prompt | Only under disk pressure | What xNet does about it: - On Chromium and WebKit browsers the request is silent and never penalized, so xNet re-requests durable storage on every startup. Regular use typically flips Chrome to granted within days; enabling desktop alerts in the Notifications panel or installing the app grants it immediately. - On Safari in a browser tab, durable storage cannot be granted and even a granted request would not stop the 7-day cleanup — installing xNet from the Share menu is the only full protection. Visiting at least weekly resets the cleanup timer. - On Firefox, xNet only asks when you click **Enable durable storage**, so the prompt appears from a deliberate action. Durable storage protects against automatic eviction only. Clearing site data in the browser always removes local data — hub sync and exports are the real safety net for important work. ## Limits | Resource | Limit | | ------------------ | ----------------------------------- | | Offline queue | 1000 entries (FIFO, oldest dropped) | | Y.Doc size | 50 MB per document | | Warm document pool | 50 documents in memory | | Registry TTL | 7 days (configurable) | If the offline queue fills up during an extended offline period, the oldest entries are dropped. The Y.Doc state in SQLite is still preserved — only the incremental updates that haven't been broadcast are lost. On reconnect, a full state-vector exchange with peers will reconcile any gaps. --- ## Identity & Keys **You will learn** - How to generate Ed25519 key pairs and DID:key identifiers - The HybridKeyBundle (classical + post-quantum keys) - The PQ Key Registry: associating ML-DSA keys with DIDs - How to use `useSecurity()` to control signature level - How to create and verify UCAN authorization tokens - Key recovery via seed phrase and multi-device access - How identity flows through the stack (provider → hooks → sync) ## DID:key identifiers Every xNet user has a **Decentralized Identifier** (DID) derived from their Ed25519 public key. The format follows the W3C DID:key method: ``` did:key:z6Mk... ``` The public key is embedded directly in the DID, making it **self-certifying** — you can extract the public key and verify signatures without any external resolver or blockchain. ### How it's constructed 1. Take the 32-byte Ed25519 public key 2. Prepend the multicodec prefix `0xed01` (Ed25519 public key) 3. Encode with base58btc (multibase prefix `z`) 4. Prefix with `did:key:` ### Generate an identity ```ts const { identity, privateKey } = generateIdentity() // identity.did = "did:key:z6Mk..." // identity.publicKey = Uint8Array (32 bytes) // identity.created = Date.now() isValidDID(identity.did) // true ``` ### Parse a DID ```ts const publicKey = parseDID('did:key:z6Mk...') // Returns the 32-byte Ed25519 public key ``` ## Key bundles Every xNet identity uses a **HybridKeyBundle** — classical keys (Ed25519 + X25519) bundled with post-quantum keys (ML-DSA-65) to protect against both current and future quantum attacks. | Key | Algorithm | Size (bytes) | Purpose | | --------------- | --------- | ------------ | -------------------------------------- | | `signingKey` | Ed25519 | 32 | Sign changes, Yjs updates, UCAN tokens | | `encryptionKey` | X25519 | 32 | Classical key exchange | | `pqSigningKey` | ML-DSA-65 | 4,032 | Post-quantum signatures (Level 1/2) | | `pqPublicKey` | ML-DSA-65 | 1,952 | PQ verification key (cached) | The DID is derived from the Ed25519 public key only — the DID format is unchanged and stays compact. ```ts // Random generation — includes PQ keys by default const bundle = generateHybridKeyBundle() // bundle.signingKey — Ed25519 private key (32 bytes) // bundle.encryptionKey — X25519 private key (32 bytes) // bundle.pqSigningKey — ML-DSA-65 private key (4,032 bytes) // bundle.pqPublicKey — ML-DSA-65 public key (1,952 bytes) // bundle.identity — { did, publicKey, created } // Deterministic from a seed (same seed = same identity on every device) const bundle2 = deriveHybridKeyBundle(masterSeed) ``` ### Storage Key bundles are serialized, encrypted with XChaCha20-Poly1305, and stored via `PasskeyStorage`. In production, the encryption key is derived from WebAuthn/passkey credentials. ```ts const storage = new BrowserPasskeyStorage() const storedKey = await storage.store(bundle, credentialId) const recovered = await storage.retrieve(storedKey, credentialId) ``` ### Resumable sessions Unlocking with a passkey on every page load would mean a biometric prompt per reload. Instead, after a successful `create()`/`unlock()` the key bundle is re-encrypted (AES-GCM) under a freshly generated **non-extractable** WebCrypto key and stored in IndexedDB, bound to the identity's DID. On boot, `identityManager.resume()` restores the session silently — no prompt. - Sessions expire after **7 days**; expiry forces a fresh passkey unlock. - Expired, tampered, or DID-mismatched session records are deleted and fall back to a normal unlock. - The wrapping key's bytes cannot be exported by script, so an exfiltrated IndexedDB dump is undecryptable off-device. Raw private keys are never stored in plaintext. ### Logging out `identityManager.lock()` clears the session and cached keys but keeps the identity — the next visit shows the unlock screen. In the app this is **Settings → Account → Log out**. `clear()` additionally removes the identity itself. ### X25519 from Ed25519 The Ed25519 signing key can be birationally converted to an X25519 encryption key, so a single DID:key embeds both capabilities. xNet uses this conversion throughout the authorization system — the hub and other users can derive your X25519 public key directly from your DID, with no additional key exchange ceremony: ```ts // Derive the X25519 public key from an Ed25519 public key const x25519Pub = edwardsToMontgomeryPub(ed25519PublicKey) ``` ## PQ Key Registry The DID:key format stays Ed25519-based (compact, human-readable). To support Level 1/2 verification, the **PQ Key Registry** associates each DID with its ML-DSA public key via a `PQKeyAttestation` — a self-signed proof binding the two keys together. ```ts // Create an attestation binding your DID to your PQ public key const attestation = await createPQKeyAttestation({ did: bundle.identity.did, pqPublicKey: bundle.pqPublicKey, signingKey: bundle.signingKey, // Ed25519 signs the attestation pqSigningKey: bundle.pqSigningKey // ML-DSA also signs for cross-attestation }) // Store in registry const registry = new MemoryPQKeyRegistry() await registry.store(attestation) // Look up during verification const pqPub = await registry.lookup(someUserDid) ``` The hub maintains a public PQ Key Registry for all registered users. When another user encrypts data for you, they look up your ML-DSA public key here to wrap the content key at Level 1/2. ## Security level in React Use `XNetProvider` to set the default signing level for your app, and `useSecurity()` to inspect or override it per-operation: ```tsx // Configure default security level ; ``` ```ts function HighSecurityAction() { const { level, setLevel, canSignAtLevel } = useSecurity() return ( ) } ``` `useSecurity()` also exposes stats visible in the DevTools Security panel: current level, signature counts by level, and verification cache hit rate. ## Key recovery ### Seed phrase Your identity can be derived deterministically from a BIP-39 seed phrase. Back up the seed phrase and you can always restore your identity — and regain access to all your encrypted data — on any device: ```ts // Generate a new identity with a recoverable seed const { mnemonic, bundle } = deriveSeedPhrase() // mnemonic: "correct horse battery staple ..." // Recover on a new device — produces the same DID and key pair const recoveredBundle = recoverFromSeedPhrase(mnemonic) ``` The seed phrase generates the Ed25519 signing key, and the X25519 encryption key is derived from it via birational conversion — not independently. This ensures the DID, signing key, and encryption key are always consistent. ### Social recovery As a fallback when the seed phrase is unavailable, xNet supports Shamir's Secret Sharing. Split the seed across trusted contacts (e.g., 3-of-5 threshold) so any quorum can reconstruct your identity: ```ts const shares = splitSeed(mnemonic, { threshold: 3, total: 5 }) // Distribute shares to trusted contacts const recovered = reconstructSeed(anyThreeShares) // any 3 of 5 work ``` ### Encrypted hub backup With opt-in hub backup, your key bundle is stored encrypted on a hub, unlocked by a passphrase or WebAuthn credential. The hub never sees the plaintext key: ```ts const backup = new HubKeyBackup(hubUrl) await backup.store(bundle, { passphrase: 'my-secret-passphrase' }) const restored = await backup.retrieve({ passphrase: 'my-secret-passphrase' }) ``` ## Multi-device access When you sign in on a second device: 1. The new device generates a device-specific key pair 2. It derives the same primary key from your seed phrase 3. Your primary key wraps content keys for each device All devices share the same DID — collaborators don't need to know which device you're on. ## Cryptographic primitives The `@xnetjs/crypto` package provides all the low-level operations: ### Hashing (BLAKE3) ```ts const digest = hash(data) // Uint8Array const hex = hashHex(data) // hex string const b64 = hashBase64(data) // base64url string const sha = hash(data, 'sha256') // SHA-256 fallback ``` ### Signing (Ed25519) ```ts const { publicKey, privateKey } = generateSigningKeyPair() const signature = sign(message, privateKey) const valid = verify(message, signature, publicKey) // boolean ``` ### Encryption (XChaCha20-Poly1305) ```ts const key = generateKey() // 32 bytes const encrypted = encrypt(plaintext, key) // { nonce, ciphertext } const decrypted = decrypt(encrypted, key) // Uint8Array ``` ### Key exchange (X25519 + HKDF) ```ts const alice = generateKeyPair() const bob = generateKeyPair() const shared = deriveSharedSecret(alice.privateKey, bob.publicKey) // Both sides derive the same 32-byte shared secret ``` ## UCAN tokens UCANs (User Controlled Authorization Networks) are self-signed capability tokens for decentralized authorization. They replace traditional API keys or OAuth tokens. UCAN tokens are signed with the hybrid signature at whatever level the signer's `SecurityContext` specifies. ### Structure ```ts interface UCANToken { iss: string // Issuer DID aud: string // Audience DID exp: number // Expiration (Unix seconds) att: UCANCapability[] // Capabilities granted prf: string[] // Proof chain (parent tokens) sig: Uint8Array // Ed25519 signature } interface UCANCapability { with: string // Resource URI: 'xnet://doc/123' or '*' can: string // Action: 'read', 'write', or '*' } ``` ### Create a token ```ts const token = createUCAN({ issuer: alice.did, issuerKey: alice.privateKey, audience: bob.did, capabilities: [ { with: 'xnet://doc/123', can: 'write' }, { with: 'xnet://doc/*', can: 'read' } ], expiration: Date.now() / 1000 + 3600, // 1 hour (default) proofs: [] // Parent tokens for delegation }) ``` ### Verify a token ```ts const result = verifyUCAN(token) if (result.valid) { const canWrite = hasCapability(result.payload, 'xnet://doc/123', 'write') } ``` Verification extracts the issuer's public key from their DID (no external resolver), checks expiration, and verifies the Ed25519 signature. ### Delegation chains ```mermaid flowchart LR A["Alice\n(document owner)"] -->|"grants write\n(signs UCAN)"| B["Bob"] B -->|"delegates read\n(cites Alice's UCAN as proof)"| C["Carol"] C -->|"verifies chain"| D["Alice → Bob → Carol"] ``` UCANs support transitive delegation via the `prf` (proofs) field: ```ts // Alice grants Bob write access const aliceToBob = createUCAN({ issuer: alice.did, issuerKey: alice.privateKey, audience: bob.did, capabilities: [{ with: 'xnet://doc/123', can: 'write' }] }) // Bob delegates read access to Carol, citing Alice's grant as proof const bobToCarol = createUCAN({ issuer: bob.did, issuerKey: bob.privateKey, audience: carol.did, capabilities: [{ with: 'xnet://doc/123', can: 'read' }], proofs: [aliceToBob] }) ``` ## Integration with React Identity is provided to the app through `XNetProvider`: ```tsx ; ``` The `useIdentity` hook exposes identity state to components: ```ts function Profile() { const { identity, isAuthenticated, did } = useIdentity() if (!isAuthenticated) return return

Signed in as {did}

} ``` ## Related - [Authorization](/docs/guides/authorization/) — Roles, grants, and encryption-first access control - [Cryptography](/docs/concepts/cryptography/) — Ed25519, X25519, and the encrypted envelope model ## How identity flows through the stack ```mermaid flowchart TD A["XNetProvider\n(authorDID + signingKey)"] --> B["NodeStore"] A --> C["SyncManager"] B --> D["mutate.create() / update()"] D --> E["Ed25519 sign Change‹T›"] C --> F["BSM\n(Background Sync Manager)"] F --> G["signYjsUpdate()\nSignedYjsEnvelope"] F --> H["ClientID attestation\n(clientId → DID binding)"] G --> I["Broadcast to peers"] I --> J["Remote peer\nverify all signatures"] ``` 1. `XNetProvider` creates a `NodeStore` with `authorDID` and `signingKey` 2. Every `mutate.create()` / `mutate.update()` call signs the change with Ed25519 3. `SyncManager` receives the signing credentials and passes them to the BSM 4. Yjs updates are signed as `SignedYjsEnvelope` before broadcast 5. ClientID attestations bind the Yjs clientID to the DID 6. Remote peers verify all signatures before applying changes --- ## Real-time Collaboration **You will learn** - How `useNode` enables real-time collaborative editing - How Yjs CRDTs handle concurrent text edits - How to display cursor presence with awareness - The dual-write model for properties vs. rich text ## How it works When two users open the same node, xNet automatically synchronizes their edits in real time. Rich text goes through Yjs (character-level CRDT), while properties go through the NodeStore (field-level LWW). Both channels share the same WebSocket connection. ```tsx function DocumentEditor({ nodeId }) { const { editor, properties, mutate, peers } = useNode(nodeId) return (

{properties.title}

) } ``` ### The dual-write model `useNode` manages two sync channels simultaneously: | Channel | Data | CRDT | How to write | | -------------- | ----------------------------- | ------------------- | ------------------------- | | Editor content | Rich text, blocks, embeds | Yjs `Y.XmlFragment` | Type in the TipTap editor | | Properties | Title, status, assignee, etc. | Lamport LWW | Call `mutate.update()` | These channels are bridged one-way by the MetaBridge: property changes in NodeStore are reflected in the Y.Doc's metadata map, but Yjs updates never write back to NodeStore. This prevents malicious Yjs payloads from corrupting structured data. ## Yjs CRDT merging Yjs uses a character-level CRDT algorithm that handles concurrent edits without conflicts: - **Same paragraph, different positions** — edits merge cleanly - **Same character position** — Yjs uses internal ordering rules (clientID + sequence number) to produce a deterministic result - **Delete + edit at same position** — the edit wins (insert beats delete in Yjs) You don't need to handle conflicts for rich text — Yjs resolves everything automatically. ## Cursor awareness Yjs provides an `Awareness` protocol for sharing ephemeral state like cursor positions and user information. xNet hooks into this through `useNode`: ```tsx function DocumentEditor({ nodeId }) { const { editor, awareness } = useNode(nodeId) // TipTap's collaboration extension handles awareness rendering // automatically when you provide the awareness instance } ``` Awareness data includes: - Cursor position and selection range - User name and color - Online/offline status Awareness state is ephemeral — it's not persisted and not signed. It's purely for real-time presence display. ## Property collaboration When multiple users edit the same property simultaneously, the last write wins based on Lamport timestamp ordering: ```tsx function TaskHeader({ nodeId }) { const { properties, mutate } = useNode(nodeId) const updateTitle = (newTitle: string) => { mutate.update({ title: newTitle }) // This creates a signed Change with a Lamport timestamp // If another peer writes at the same time, the higher // timestamp wins. DID breaks ties deterministically. } return updateTitle(e.target.value)} /> } ``` tip For title fields and other frequently-edited properties, consider debouncing updates to reduce change volume: ```ts const debouncedUpdate = useDebouncedCallback((title: string) => { mutate.update({ title }) }, 300) ``` ## Multi-user patterns ### Sync indicator Show users when their changes are synced: ```tsx function SyncStatus({ nodeId }) { const { syncState } = useNode(nodeId) switch (syncState) { case 'synced': return All changes saved case 'syncing': return Syncing... case 'offline': return Working offline } } ``` ### List + detail with background sync Track nodes so they sync even when the editor isn't open: ```tsx function TaskList() { const { data: tasks } = useQuery(TaskSchema) const sync = useSyncManager() // Track all visible tasks for background sync useEffect(() => { tasks.forEach((t) => sync.track(t.id, TaskSchema._schemaId)) }, [tasks]) return tasks.map((t) => ) } ``` ### Handling offline → online transitions When connectivity is restored, the offline queue drains automatically. You don't need to handle this manually — `useNode` and `useQuery` will re-render with the merged state. See the [Offline Patterns](/docs/guides/offline/) guide for details. ## TipTap integration xNet's editor package (`@xnetjs/editor`) wraps TipTap with Yjs collaboration pre-configured. When you use the editor through `useNode`, the following extensions are active: - **Collaboration** — Yjs document binding - **CollaborationCursor** — Remote cursor rendering - **All standard TipTap extensions** — Headings, lists, code blocks, etc. - **Plugin-contributed extensions** — Any `EditorContribution` from the plugin system The editor instance returned by `useNode` is a standard TipTap `Editor` — you can use any TipTap API on it. ## Security model All collaborative data is cryptographically secured: 1. **Signed changes** — Every property mutation is signed with Ed25519 and linked into a hash chain 2. **Signed Yjs updates** — Editor content updates are wrapped in `SignedYjsEnvelope` with BLAKE3 + Ed25519 3. **ClientID attestation** — Yjs clientIDs are cryptographically bound to DIDs 4. **Peer scoring** — Peers that send invalid data get penalized and eventually blocked 5. **Rate limiting** — Per-peer limits prevent flooding (30 updates/sec, 1 MB max size) See the [Sync Guide](/docs/guides/sync/) for the full security architecture. --- ## Plugin Development **You will learn** - The four plugin layers and when to use each one - How to define, register, and distribute an extension - All eleven contribution types with working examples - The middleware system for intercepting data operations - The script sandbox for safe user-authored expressions - Platform compatibility across Electron, Web, and Mobile ## The four layers xNet's plugin system is organized into four layers of increasing complexity: | Layer | Name | Description | Platform | | ----- | ---------------- | ------------------------------------------------------------------- | --------------------------------- | | 1 | **Scripts** | Sandboxed expressions. Safe for AI-generated code. | All | | 2 | **Extensions** | Developer-built packages with views, commands, editor integrations. | All (some features Electron-only) | | 3 | **Services** | Background processes managed by a process supervisor. | Electron only | | 4 | **Integrations** | HTTP API, MCP server, webhooks for external tools. | Electron only | Most plugin development happens at Layer 2. Layers 3 and 4 are for advanced use cases that need OS-level access. ## Quick start: your first extension 1. **Define the manifest** Every extension starts with an `XNetExtension` manifest. Use `defineExtension()` for validation: ```ts import { defineExtension } from '@xnetjs/plugins' export const MyPlugin = defineExtension({ id: 'com.example.my-plugin', // reverse-domain format name: 'My Plugin', version: '1.0.0', description: 'Adds a custom view and slash command.', platforms: ['electron', 'web'], contributes: { // Static contributions declared here }, activate(ctx) { // Dynamic contributions registered here }, deactivate() { // Cleanup (optional — subscriptions auto-dispose) } }) ``` 2. **Register it** In your app setup, install the plugin with the registry: ```ts import { usePluginRegistry } from '@xnetjs/react' import { MyPlugin } from './plugins/my-plugin' function App() { const registry = usePluginRegistry() useEffect(() => { registry.install(MyPlugin) }, []) } ``` 3. **Consume contributions in your UI** ```tsx import { useViews, useCommands } from '@xnetjs/react' function Sidebar() { const views = useViews() const commands = useCommands() // Render plugin-contributed views and commands } ``` ## Manifest reference The `XNetExtension` interface: ```ts interface XNetExtension { id: string // Reverse-domain: 'com.example.my-plugin' name: string version: string // Semver: '1.0.0' description?: string author?: string xnetVersion?: string // Minimum compatible xNet version platforms?: Platform[] // 'web' | 'electron' | 'mobile' (default: all) permissions?: PluginPermissions contributes?: PluginContributions // Static contributions activate?(ctx: ExtensionContext): void | Promise deactivate?(): void | Promise } ``` **Validation rules** enforced by `defineExtension()`: - `id` must match `/^[a-z][a-z0-9]*(\.[a-z][a-z0-9-]*)+$/i` (reverse-domain) - `version` must be valid semver - `platforms` values must be `'web'`, `'electron'`, or `'mobile'` - `activate` and `deactivate` must be functions if present ## Lifecycle ``` install → activate → contribute → deactivate → uninstall ``` 1. **Install** — Manifest is validated, platform compatibility checked, plugin persisted as a node in the store (syncs to peers). Status: `'installed'`. Activation happens immediately. 2. **Activate** — An `ExtensionContext` is created. Static contributions from `contributes` are registered. Then `activate(ctx)` is called if defined — this is where you register dynamic contributions, subscribe to data changes, or add middleware. 3. **Contribute** — All `ctx.register*()` calls return `Disposable` objects tracked in `ctx.subscriptions`. Contributions are visible to React hooks immediately. 4. **Deactivate** — `deactivate()` is called, then all subscriptions are disposed. Contributions are unregistered, middleware removed, store subscriptions cancelled. 5. **Uninstall** — Plugin node deleted from the store. tip You rarely need a `deactivate()` function. All resources registered through `ExtensionContext` are automatically cleaned up when the plugin is deactivated. ## ExtensionContext The context object passed to `activate()` provides the full plugin API: ```ts interface ExtensionContext { readonly pluginId: string readonly platform: Platform readonly store: NodeStore readonly storage: ExtensionStorage // Key-value storage scoped to this plugin readonly capabilities: PlatformCapabilities readonly subscriptions: Disposable[] // Data access query(schema: SchemaIRI, filter?: QueryFilter): Promise subscribe(schema: SchemaIRI | null, callback): Disposable // Registration (all return Disposable) registerSchema(schema): Disposable registerView(view: ViewContribution): Disposable registerCommand(command: CommandContribution): Disposable registerSlashCommand(cmd: SlashCommandContribution): Disposable registerEditorExtension(ext: EditorContribution): Disposable registerSidebarItem(item: SidebarContribution): Disposable registerPropertyHandler(type, handler): Disposable registerBlockType(block: BlockContribution): Disposable addMiddleware(middleware: NodeStoreMiddleware): Disposable } ``` ## Contribution types xNet supports eleven contribution types. Each can be declared statically in `contributes` or registered dynamically in `activate()`. ### Views Custom UI panels for displaying node data: ```ts interface ViewContribution { type: string // Unique view type identifier name: string icon?: string | ComponentType component: ComponentType // React component supportedSchemas?: string[] // Restrict to specific schemas } interface ViewProps { nodeId: string schemaId: string } ``` ```tsx const KanbanView: ViewContribution = { type: 'kanban', name: 'Kanban Board', icon: 'columns', supportedSchemas: ['xnet://app/Task'], component: ({ nodeId, schemaId }) => { const { data } = useQuery(schemaId) return } } ``` ### Commands Actions triggered by keyboard shortcuts or the command palette: ```ts interface CommandContribution { id: string name: string description?: string keybinding?: string // e.g., 'Mod-Shift-P' (Mod = Cmd on Mac, Ctrl elsewhere) keywords?: string[] // For command palette search icon?: string execute: () => void | Promise when?: () => boolean // Show/enable condition } ``` ```ts ctx.registerCommand({ id: 'my-plugin.export-csv', name: 'Export as CSV', keybinding: 'Mod-Shift-E', keywords: ['export', 'csv', 'download'], execute: async () => { const nodes = await ctx.query('xnet://app/Task') downloadCSV(nodes) } }) ``` ### Slash commands In-editor commands triggered by typing `/`: ```ts interface SlashCommandContribution { id: string name: string description?: string aliases?: string[] // Alternative trigger words icon?: string execute: (props: SlashCommandContext) => void } interface SlashCommandContext { editor: unknown // TipTap Editor instance range: { from: number; to: number } } ``` ### Editor extensions TipTap editor extensions (nodes, marks, plugins): ```ts interface EditorContribution { id: string extension: Extension // TipTap Extension/Node/Mark priority?: number // Default: 100. Lower runs first. toolbar?: ToolbarContribution } interface ToolbarContribution { icon: string | ComponentType title: string group?: 'format' | 'insert' | 'block' | 'custom' isActive?: (editor) => boolean action: (editor) => void shortcut?: string } ``` ### Sidebar items Add items to the application sidebar: ```ts interface SidebarContribution { id: string name: string icon: string | ComponentType position?: 'top' | 'bottom' | 'section' section?: string priority?: number badge?: () => string | number | null action: (() => void) | string // Function or route string panel?: ComponentType // Expandable panel content } ``` In the workbench shell, a `SidebarContribution` becomes a rail item; a contribution with a `panel` component becomes a left-panel view. See [The Workbench](/docs/guides/workbench/) for the container model. ### Status bar items Add items to the workbench status bar — workspace scope on the left, view scope on the right: ```ts interface StatusBarContribution { id: string alignment: 'left' | 'right' priority?: number item: ComponentType // Rendered in the 24px mono status bar } ``` ### Dashboard widgets Register widgets users can add to dashboards (and drop onto canvases) with a `WidgetContribution`. The trust tier is host-assigned — a plugin can never self-declare one. See [Dashboards & Widgets](/docs/guides/dashboards/) for the widget contract. ### Property handlers Custom renderers for property types in table cells and editors: ```ts interface PropertyHandlerContribution { type: string // Property type identifier handler: { Cell: ComponentType<{ value; config? }> // Read-only display Editor: ComponentType<{ value; onChange; config? }> // Edit mode parse?: (input: string) => unknown format?: (value: unknown) => string validate?: (value: unknown) => boolean } } ``` ### Block types Custom block-level elements inside the editor: ```ts interface BlockContribution { type: string name: string component: ComponentType<{ node: unknown updateAttributes: (attrs: Record) => void }> } ``` ### Settings panels Add sections to the application settings UI: ```ts interface SettingContribution { id: string title: string description?: string icon?: string section?: 'general' | 'appearance' | 'plugins' | 'data' | 'network' component: ComponentType<{ storage: ExtensionStorage }> } ``` ### Schema contributions Register new schemas from a plugin: ```ts interface SchemaContribution { schema: unknown // A defineSchema() result } ``` ## React hooks Use these hooks to consume plugin contributions in your components: | Hook | Returns | Description | | --------------------------- | ---------------------------------- | -------------------------------------------------- | | `usePlugins()` | `RegisteredPlugin[]` | All registered plugins with status | | `useViews()` | `ViewContribution[]` | All view contributions | | `useCommands()` | `CommandContribution[]` | All command contributions | | `useSlashCommands()` | `SlashCommandContribution[]` | All slash commands | | `useSidebarItems()` | `SidebarContribution[]` | All sidebar items | | `useEditorExtensions()` | `EditorContribution[]` | All editor extensions (throws if no plugin system) | | `useEditorExtensionsSafe()` | `EditorContribution[]` | Same, returns `[]` if no plugin system | | `useContributions(type)` | `Contribution[]` | Generic — pass `'views'`, `'commands'`, etc. | | `useView(type)` | `ViewContribution \| undefined` | Find a specific view by type | | `useCommand(id)` | `CommandContribution \| undefined` | Find a specific command by ID | | `usePluginRegistry()` | `PluginRegistry` | Direct registry access (throws if missing) | All hooks are reactive — they re-render when contributions change. ## Middleware Middleware lets you intercept NodeStore operations. This is useful for validation, audit logging, computed fields, or cross-plugin data transformation. ```ts interface NodeStoreMiddleware { id: string priority?: number // Lower runs first. Default: 100. beforeChange?(change: PendingChange, next: () => Promise): Promise afterChange?(event: NodeChangeEvent): void } ``` ### Example: audit log middleware ```ts ctx.addMiddleware({ id: 'my-plugin.audit-log', priority: 50, // Run early async beforeChange(change, next) { // Pass through — let the operation proceed const result = await next() return result }, afterChange({ change, node, isRemote }) { if (!isRemote) { console.log(`[audit] ${change.type} on ${change.nodeId}`) } } }) ``` ### Middleware capabilities - **Pass through**: Call `next()` to continue the chain - **Modify**: Mutate the `change` object before calling `next()` - **Reject**: Throw an error to abort the operation - **Short-circuit**: Return a value without calling `next()` The `MiddlewareChain` executes `beforeChange` hooks in priority order (lowest first). After the store operation completes, `afterChange` hooks run for all middleware — one failing hook does not prevent others. ## Layer 1: Scripts Scripts are sandboxed expressions for safe, user-authored (or AI-generated) logic. They run in a restricted JavaScript subset with no access to the DOM, network, or Node.js APIs. ### Script node Scripts are stored as nodes with schema `xnet://xnet.dev/Script`: ```ts interface ScriptNode { name: string description?: string code: string // The script body triggerType: 'manual' | 'onChange' | 'onView' | 'scheduled' triggerProperty?: string // For onChange: which property triggers re-run inputSchema?: string // SchemaIRI to filter triggers outputType: 'value' | 'mutation' | 'decoration' | 'void' enabled: boolean lastError?: string lastRun?: number } ``` ### Script context Scripts receive a frozen context with helper libraries: ```ts interface ScriptContext { node: Readonly // Current node nodes: (schemaIRI?) => ReadonlyArray // Query siblings now: () => number // Current timestamp format: { date; number; currency; relativeTime; bytes } math: { sum; avg; min; max; round; clamp; abs; floor; ceil } text: { slugify; truncate; capitalize; titleCase; contains; template; trim; lower; upper } array: { first; last; sortBy; groupBy; unique; count; compact } } ``` ### Example script ```js // Compute a "progress" value from subtask completion const tasks = nodes('xnet://app/Task') const done = array.count(tasks, (t) => t.status === 'done') const total = tasks.length total > 0 ? math.round((done / total) * 100) : 0 ``` ### AST validation Before execution, scripts are parsed with `acorn` and validated against a strict allowlist. Blocked patterns include: - 60+ forbidden globals (`window`, `document`, `fetch`, `eval`, `require`, `process`, `setTimeout`, etc.) - Forbidden property access (`__proto__`, `constructor`, `prototype`) - Import/export statements and dynamic `import()` - `async`/`await`, `new Function()`, `with` statements ### Sandbox execution ```ts const sandbox = new ScriptSandbox({ timeoutMs: 1000 }) const context = createScriptContext(node, queryFn) const result = await sandbox.execute(code, context) ``` The sandbox wraps code in a `new Function()` with all dangerous globals shadowed to `undefined`. Output is sanitized — functions, symbols, circular references, and non-plain objects are stripped. ### AI script generation xNet includes an AI script generator that produces validated scripts: ```ts const provider = createAIProvider({ type: 'anthropic', // or 'openai', 'ollama' options: { apiKey: '...' } }) const result = await generateScript(provider, { intent: 'Calculate total price from quantity and unit price', schema: { name: 'LineItem', schemaIRI: '...', properties: [...] }, outputType: 'value' }) if (result.validated) { // result.code is safe to execute in the sandbox } ``` The generator builds a structured prompt with schema context and helper documentation, then validates the output through the AST validator. It retries up to 2 times if validation fails. ## Layer 3: Services Services are background processes managed by `ProcessManager` in the Electron main process. Think of them as supervised daemons. ```ts interface ServiceDefinition { id: string name: string process: { command: string // e.g., 'python', 'node' args?: string[] cwd?: string env?: Record } lifecycle: { restart: 'always' | 'on-failure' | 'never' maxRestarts?: number restartDelayMs?: number healthCheck?: { type: 'http' | 'tcp' | 'stdout' url?: string port?: number intervalMs?: number } } communication: { protocol: 'stdio' | 'http' | 'websocket' | 'ipc' port?: number } } ``` From the renderer, use the `ServiceClient`: ```ts const services = createServiceClient() await services.start(myServiceDef) const status = await services.status('my-service') // { state: 'running', pid: 12345, uptime: 60000, ... } const result = await services.call('my-service', 'POST', '/analyze', { data }) ``` The service client communicates with the main process via IPC. It is only available in Electron. ## Layer 4: Integrations ### Local HTTP API A REST API on `localhost:31415` for external tools: ``` GET /api/v1/nodes?schema=&limit=&offset= POST /api/v1/nodes { schema, properties } GET /api/v1/nodes/:id PATCH /api/v1/nodes/:id DELETE /api/v1/nodes/:id POST /api/v1/query { schema, limit?, offset? } GET /api/v1/events?since= Polling endpoint GET /api/v1/schemas ``` Optional Bearer token authentication. CORS enabled. ### MCP server Exposes xNet data to AI agents via the Model Context Protocol: | Tool | Description | | -------------- | ---------------------- | | `xnet_query` | Query nodes by schema | | `xnet_get` | Get a node by ID | | `xnet_create` | Create a node | | `xnet_update` | Update node properties | | `xnet_delete` | Delete a node | | `xnet_schemas` | List all schemas | The MCP server reads from stdin and writes JSON-RPC 2.0 responses to stdout. tip MCP is the fallback surface for agents. The primary agent interface is the files-first workspace checkout plus the `xnet` CLI — dramatically cheaper in tokens. See [Agent Interfaces](/docs/guides/agent-interfaces/). ### Webhooks Push notifications on store changes: ```ts const emitter = createWebhookEmitter(store) emitter.register({ id: 'notify-slack', url: 'https://hooks.slack.com/...', events: ['created', 'updated'], schema: 'xnet://app/Task', secret: 'hmac-secret', retries: 3 }) emitter.start() ``` Payloads are signed with HMAC-SHA256 (`x-xnet-signature-256` header). Failed deliveries retry with exponential backoff. ## Worked example: Mermaid plugin Here is the complete source for the built-in Mermaid diagram plugin: ```ts export const MermaidPlugin: XNetExtension = { id: 'fyi.xnet.mermaid', name: 'Mermaid Diagrams', version: '1.0.0', description: 'Add flowcharts, sequence diagrams, and more using Mermaid syntax.', author: 'xNet', platforms: ['electron', 'web'], contributes: { editorExtensions: [ { id: 'mermaid', extension: MermaidExtension, priority: 100 } ], slashCommands: [ { id: 'mermaid', name: 'Mermaid Diagram', description: 'Insert a Mermaid diagram', aliases: ['diagram', 'flowchart', 'sequence', 'chart'], icon: 'git-branch', execute: ({ editor, range }) => { ;(editor as any).chain().focus().deleteRange(range).setMermaid().run() } } ] } } ``` Key takeaways: - **No `activate`/`deactivate`** — simple plugins only need `contributes` - **Two contributions** — an editor extension and a slash command that work together - **Platform restriction** — excluded from mobile where the editor isn't available - **Bundled plugins** are installed from `BUNDLED_PLUGINS` in the app entry point and rehydrated on restart using `registry.rehydrate()` to restore live function references after deserialization ## Permissions Plugins can declare the permissions they need: ```ts permissions: { schemas: { read: ['xnet://app/Task', 'xnet://app/Project'], write: ['xnet://app/Task'], create: ['xnet://app/Task'] }, capabilities: { network: ['https://api.example.com'], // or true for all storage: 'local', // or 'shared' clipboard: true, notifications: true, processes: true // Electron only } } ``` ## Platform compatibility | Feature | Electron | Web | Mobile | | -------------------- | -------- | --- | ------ | | Views | Yes | Yes | Yes | | Commands | Yes | Yes | Yes | | Slash commands | Yes | Yes | No | | Editor extensions | Yes | Yes | No | | Sidebar items | Yes | Yes | Yes | | Property handlers | Yes | Yes | Yes | | Block types | Yes | Yes | No | | Settings panels | Yes | Yes | Yes | | Scripts (sandbox) | Yes | Yes | Yes | | Services (processes) | Yes | No | No | | Local API | Yes | No | No | | MCP server | Yes | No | No | | Webhooks | Yes | Yes | Yes | If a plugin specifies `platforms` and the current platform isn't included, installation is rejected. Use `ctx.capabilities` to check feature availability at runtime. ## Ecosystem APIs: capabilities, marketplace, testing The `@xnetjs/plugins` ecosystem layer turns a [`FeatureModule`](#the-four-layers) manifest into something installable, trustworthy, and testable. Every export below is available from `@xnetjs/plugins`. ### Declared capabilities are enforced A `FeatureModule` declares a `capabilities` grant. At install, the registry hands the plugin a `NodeStore` wrapped by a guard, so a write outside the grant throws a `CapabilityError` — the declaration is a runtime gate, not a label. ```ts export const KanbanModule = defineFeatureModule({ id: 'com.acme.kanban', name: 'Kanban Board', version: '1.0.0', capabilities: { schemaWrite: ['xnet://xnet.fyi/Task@*'], // may write any Task version… network: ['api.acme.com'] // …and reach only this host } }) // Inside activate(ctx): ctx.store.create({ schemaId: 'xnet://xnet.fyi/Secret@1.0.0' }) // → throws CapabilityError — Secret is outside the grant. ``` Patterns: exact (`…/Task@1.0.0`), version-wildcard (`…/Task@*`), authority-wildcard (`…/fyi/*`), or `*` (all — rendered as a danger in the consent dialog). Reads default open; declare `schemaRead` to restrict them. ### Provenance, trust tier, and install consent A plugin's trust tier follows its **provenance** (where it came from), never anything it declares about itself. Pass `provenance` to `install`; the registry derives the tier and prompts for consent when needed. ```ts await registry.install(manifest, { provenance: 'marketplace', // → marketplace tier (iframe sandbox) hostVersion: '0.7.0', // gates on manifest.xnetVersion onConsent: async (decision) => { // decision.lines describes each requested capability (danger-flagged) return confirm(decision.lines.map((l) => l.text).join('\n')) } }) ``` `deriveTrustTier`/`requiresCapabilityReprompt` map provenance to tier and consent: `builtin`→first-party, `authored`/`ai-generated`/`imported`/`synced`→user, `marketplace`→marketplace. Synced and marketplace installs always re-prompt — sync is not consent. ### Version compatibility and dependencies Declare a host requirement with `xnetVersion` (a semver range) and other plugins with `dependencies`. Install gates on both. ```ts defineFeatureModule({ id: 'com.acme.app', name: 'App', version: '1.0.0', xnetVersion: '>=0.6.0', // satisfiesRange / isHostCompatible dependencies: { 'com.acme.core': '^1.2.0' } // resolveInstallOrder / findMissingDependencies }) ``` ### Marketplace index and supply-chain provenance The marketplace is a GitHub-hosted `registry.json` of `MarketplaceEntry`s. `MarketplaceClient` fetches once and searches in memory; `verifyProvenance` checks a Sigstore-style attestation and **fails closed** (no verifier configured ⇒ "unverified", never a false green). ```ts const market = new MarketplaceClient({ indexUrl: REGISTRY_URL }) const results = await market.search('tasks', { sort: 'installs', category: 'productivity' }) const { verified, reason } = await verifyProvenance({ artifactDigest, provenance }) ``` ### Testing a plugin `createTestPluginHarness` wires an in-memory store into a real `PluginRegistry`, so you can install a manifest and assert on its contributions without the app. ```ts const harness = createTestPluginHarness() await harness.install(KanbanModule) expect(harness.registry.get('com.acme.kanban')?.status).toBe('active') expect(harness.registry.getContributions().slashCommands.getAll()).toHaveLength(1) ``` ### Scaffolding a new plugin `xnet plugin scaffold` writes a ready-to-edit project (manifest, harness test, `package.json`, README) from one of three templates — `client`, `two-sided`, or `ai-script`: ```bash xnet plugin scaffold com.acme.kanban --name "Kanban Board" --template client # → com.acme.kanban/{package.json,tsconfig.json,src/index.ts,src/index.test.ts,README.md} ``` The pure core, `scaffoldPlugin(spec)`, returns the project as a path→content map, so tooling can generate plugins without touching disk: ```ts const { files } = scaffoldPlugin({ id: 'com.acme.kanban', name: 'Kanban', template: 'client' }) // files['src/index.ts'] is a defineFeatureModule(...) ; files['src/index.test.ts'] uses the harness ``` ### Authoring a plugin with AI The AI generators in `@xnetjs/plugins/ai` turn natural language into an AST-validated script. `scriptToPluginManifest` wraps a **validated** generated script into an installable plugin stamped with `ai-generated` provenance (so the install path sandboxes it at the `user` tier and still routes its capability requests through consent). It refuses unvalidated code — "the AI made it" never bypasses the gate. ```ts const { manifest, provenance } = scriptToPluginManifest({ id: 'com.me.counter', script: generated, // { code, suggestedName, validated, explanation } from the AI generator run: (code) => runInSandbox(code) // how the command executes the script }) await registry.install(manifest, { provenance }) // provenance === 'ai-generated' ``` ### Reaching the network safely A plugin that declares `network` hosts is handed a `guardedFetch` instead of the ambient `fetch`. Every request is checked against the allowlist before it leaves; an undeclared host rejects with `CapabilityError`, and a plugin with no `network` grant gets no egress at all. ```ts const fetch = guardedFetch({ network: ['api.acme.com'] }, 'com.acme.kanban') await fetch('https://api.acme.com/cards') // ok await fetch('https://evil.example.com') // rejects: CapabilityError ``` ## Publishing to the marketplace Your plugin's code stays in **your own repo** — getting listed on the [plugins marketplace](/plugins) is a one-line pull request, not a code dump into the monorepo. 1. **Ship a Release.** Build your plugin into a single `plugin.js` and attach it, with `manifest.json`, to a GitHub Release. (A copyable template with a release workflow lives in [`examples/xnet-plugin-template`](https://github.com/crs48/xNet/tree/main/examples/xnet-plugin-template).) 2. **Add one entry** to [`registry/community.json`](https://github.com/crs48/xNet/tree/main/registry): ```jsonc [{ "repo": "you/xnet-plugin-kanban", "category": "views" }] ``` 3. **Open a PR.** CI validates the submission; after merge, a daily job enriches your entry from the GitHub API and points the install link at your Release's `manifest.json`. Updates you ship afterward are picked up automatically. The app installs community plugins in a sandbox scoped to their trust tier, after showing the user the capabilities the plugin requests and verifying its provenance. See [`registry/README.md`](https://github.com/crs48/xNet/tree/main/registry) for the full flow. --- ## Hub Setup **You will learn** - What the Hub does and why you might want one - How to deploy a Hub in under 2 minutes - How to connect your app to a Hub - How to monitor and manage your Hub ## What is the Hub? xNet works fully peer-to-peer — no server required. A Hub improves availability and adds services that are hard on mobile devices: | Without Hub | With Hub | | ------------------------------------ | ---------------------------------- | | Sync only when both peers are online | Sync anytime — Hub bridges the gap | | No backup | Encrypted backup (zero-knowledge) | | No full-text search across devices | Server-side FTS5 search | | P2P only | P2P when possible, Hub when not | The Hub never sees your plaintext data. It stores encrypted updates and relays them to your devices. ```mermaid flowchart LR A[Device A] <-->|P2P| B[Device B] A <-->|Hub Relay| H[Hub] B <-->|Hub Relay| H ``` ## Quick Start: Deploy on Railway The fastest way to get a Hub running. No Docker, no SSH, no TLS setup. [![Deploy on Railway](https://railway.app/button.svg)](https://railway.com/deploy/xnet-hub) **What happens:** 1. Railway clones the xNet repo 2. Builds the Hub from its Dockerfile 3. Creates a persistent volume for SQLite + blobs 4. Gives you a URL: `hub-xyz.up.railway.app` **Cost:** $0-2/month for a personal Hub (covered by Railway's $5 Hobby credit). ### After Deploying Your Hub is live. Copy the URL and configure your app: ```tsx ; ``` ## Platform Comparison | Platform | Best for | Typical cost | Notes | | -------- | -------------------------- | ------------ | ------------------------------- | | Railway | One-click, lowest friction | $0-2/mo | Ideal default for personal Hubs | | Fly.io | Auto-suspend, global edge | $2-6/mo | Suspend/resume adds ~2s wake | | VPS | Full control | $4-5/mo | You manage TLS + upgrades | ## Alternative Deployments Best for auto-suspend cost savings or multi-region experiments. ```bash # Install Fly CLI curl -L https://fly.io/install.sh | sh fly auth login # Deploy cd packages/hub fly launch --no-deploy fly volumes create xnet_hub_data --size 1 --region sjc fly deploy ``` Cost: ~$2-6/month depending on usage. Machines can auto-suspend when idle. For multi-region (future), add additional regions and volumes, then enable hub federation for query routing. Best for full control or predictable cost. ```bash docker run -d \ --name xnet-hub \ -p 4444:4444 \ -v xnet-hub-data:/data \ --restart unless-stopped \ ghcr.io/crs48/xnet-hub:latest ``` You'll need to configure TLS yourself (Caddy, nginx, or Cloudflare Tunnel). Cost: $4-5/month for a basic VPS (Hetzner, DigitalOcean). Best for development and testing. ```bash npx @xnetjs/hub --port 4444 --data ~/.xnet-hub ``` No TLS, no persistence guarantees. Use for local development only. ## Configuration ### Environment Variables | Variable | Default | Description | | --------------------------- | ----------------- | --------------------------------------------- | | `PORT` | `4444` | Listen port (Railway injects this) | | `HUB_DATA_DIR` | `./xnet-hub-data` | SQLite + blob storage directory | | `HUB_LOG_LEVEL` | `info` | Log verbosity: debug, info, warn, error | | `HUB_PUBLIC_URL` | — | Public URL for discovery + federation | | `RAILWAY_VOLUME_MOUNT_PATH` | — | Auto-set by Railway when a volume is attached | | `XNET_DIAGNOSTICS_URL` | — | Opt-in: upstream sink for scrubbed crash reports (see below) | | `XNET_DIAGNOSTICS_SECRET` | — | Opt-in: shared secret for diagnostics sharing | | `XNET_DIAGNOSTICS_INBOX` | `open` | Crash inbox mode: `open`, `authed`, or `off` | | `XNET_SHARE_CRASH_COUNTS` | — | Opt-in: tee fingerprint-level crash *counts* upstream | ### Your hub is your crash console (default on) Every hub runs a first-party **diagnostics inbox**: your deployment's own clients report crashes to `POST /diagnostics/ingest` on *your* hub, and the reports go nowhere else. The quarantine lives in its own `diagnostics.db` (8 KB per report, deduplicated by fingerprint, 30-day retention for handled reports, hard row cap), and the operator drains it from the app — **Settings → Privacy & Diagnostics → Import reports** — into a Diagnostics Space where the workbench is the triage console (Inbox / By release / By fingerprint saved views, a `new → acked → fixed → released` status field, comments). The ingest is rate-limited per client IP and accepts only allowlisted, length-bounded, twice-scrubbed fields. Set `XNET_DIAGNOSTICS_INBOX=authed` to require authentication for it on hubs exposed to the open internet, or `off` to disable the inbox entirely. Escalation to xNet is a separate, layered choice — three switches, each off by default: 1. **Send one report** — from the console, "Send to xNet" previews the exact payload and forwards it through the sharing route below. Requires sharing to be configured; without it, the route does not exist. 2. **Share crash counts** — `XNET_SHARE_CRASH_COUNTS=on` (plus the sharing config below) tees *fingerprint-level* data upstream on each automatic crash: error name, release, surface, grouping hash, and count. Never the message, stack, breadcrumbs, or any identifier. 3. **Let xNet help debug** — grant xNet's support identity time-boxed, read-only access to your Diagnostics Space from the same settings panel. It expires on its own and can be revoked in one click. ### Diagnostics sharing (opt-in, off by default) Your hub keeps its own errors to itself. If you'd like xNet to help debug your hub, set both `XNET_DIAGNOSTICS_URL` and `XNET_DIAGNOSTICS_SECRET` to enable the `POST /diagnostics/report` route, which forwards **scrubbed, content-free** crash reports upstream — the sender's DID is hashed (never sent raw) and document content is never included. Leave them unset (the default) and nothing is forwarded; `GET /diagnostics/health` simply reports `sharing: false`. The upstream sink is xNet Cloud's first-party `POST /diagnostics` ingest (exploration 0315): reports land in a quarantine and are drained into `debug-report` nodes in the operator's own xNet workspace, where the workbench _is_ the triage console — filterable tables, a `new → acked → fixed → released` status field, and comments. **xNet does not use a third-party error service such as Sentry.** The client keeps a dormant, vendor-neutral Sentry seam (no `@sentry/*` SDK is installed and no DSN is minted), so if you self-host a Sentry-compatible backend you can point that seam at it — [Bugsink][bugsink] (single container, SQLite) or [GlitchTip][glitchtip] (MIT, Sentry-SDK compatible) are the proven small-footprint options — but nothing ships enabled. [bugsink]: https://www.bugsink.com/ [glitchtip]: https://glitchtip.com/ ### CLI Flags | Flag | Description | | ------------------- | -------------------------------- | | `--port` | Listen port | | `--data` | Data directory | | `--no-auth` | Disable UCAN authentication | | `--storage` | Storage backend: sqlite, memory | | `--public-url` | Public hub URL for discovery | | `--max-connections` | Max concurrent WebSocket clients | | `--max-blob-size` | Max backup blob size | | `--awareness-ttl` | Awareness TTL in ms | | `--discovery-ttl` | Peer discovery TTL in ms | ## Connect Your App ### React (Renderer) ```tsx ; ``` ### Electron (Main) ```ts const manager = new SyncManager({ hubUrl: 'wss://your-hub.example.com' }) ``` ## Operations ### Health & Metrics | Endpoint | Purpose | | -------------- | -------------------------------------- | | `GET /health` | JSON status, uptime, platform metadata | | `GET /metrics` | Prometheus metrics | ### Core Endpoints | Endpoint | Purpose | | --------------------------- | ----------------------------- | | `PUT /backup/:docId` | Upload encrypted backup | | `GET /backup/:docId` | Download encrypted backup | | `GET /backup` | List backups for your DID | | `PUT /files/:cid` | Upload content-addressed file | | `GET /files/:cid` | Download file | | `POST /schemas` | Publish schema | | `GET /schemas/resolve/:iri` | Resolve schema | | `POST /dids/register` | Register peer discovery | | `GET /dids/:did` | Resolve peer | ### Backups The Hub stores encrypted blobs. Your app encrypts before upload. | Endpoint | Purpose | | -------------------- | ------------------------- | | `PUT /backup/:docId` | Upload encrypted backup | | `GET /backup/:docId` | Download encrypted backup | | `GET /backup` | List backups for your DID | ### Query + Search Queries run locally first, with Hub results filling in the gaps: ```ts const results = await queryClient.search('budget', { federate: true, limit: 20 }) ``` ## Migration Moving between platforms is straightforward: 1. Stop the old Hub (`SIGTERM` flushes SQLite) 2. Copy the data directory (`/data` or your `HUB_DATA_DIR`) 3. Start the new Hub with the same data dir 4. Update your app's `hubUrl` Railway → VPS/Fly.io is just a volume export + upload. Fly.io → Railway is the same process in reverse. ## Further Reading - [Your Own Server](/docs/guides/server/) — run xNet on your own backend with your own auth instead of a Hub - [Sync Guide](/docs/guides/sync/) - [Sync Architecture](/docs/concepts/sync-architecture/) - [Electron Setup](/docs/guides/electron/) --- ## Your Own Server **You will learn** - When to use a managed Hub vs. your own server - How `@xnetjs/server` maps **your** auth onto xNet's data layer - The three hooks: `authenticate`, `authorizeRead`, `authorizeWrite` - The trust spectrum: `server`, `custodial`, `signed` - How to wire it to the React hooks with no client changes ## Two paths to a backend xNet React works against two kinds of backend, and **the React hooks (`useQuery` / `useMutate` / `useNode`) are identical either way**: | Path | What you run | Identity & auth | | -------------------- | ------------------------------------ | ---------------------------------- | | **Managed Hub** | Nothing — point at a Hub URL | xNet identity (DIDs), works out of the box | | **Your own server** | `@xnetjs/server` in your Node backend | **Your** auth (session/JWT/Clerk/…) | If you want the decentralized, user-owned defaults, use a [Hub](/docs/guides/hub/). If you want a centralized app on your own infrastructure, gated by your existing auth and stored in your own database, use `@xnetjs/server`. ## What `@xnetjs/server` is A small, framework-agnostic engine you mount in your Node backend (Express, Hono, Fastify, a Next.js route handler). It owns a server-side node store over a pluggable storage adapter and exposes: - **`server.query(request)`** — the server side of the remote-query protocol: a structured-query executor that authenticates, scopes the read, runs it, and returns results. - **`server.mutate(token, input)`** — backend-authoritative writes: authenticate, validate, then apply. - **`server.createRemoteQueryClient(getToken)`** — an in-process client that drops into `XNetProvider`'s `remoteNodeQueryClient`, so React reads route to your server unchanged. ## Install ```bash pnpm add @xnetjs/server ``` ```bash npm install @xnetjs/server ``` ```bash yarn add @xnetjs/server ``` ## Three hooks map your auth onto the data layer You wire your existing auth through three callbacks. No UCAN, no `did:key` required from your users. ```ts const xnet = await createXNetServer({ trust: 'custodial', // 1. Exchange a token/cookie for your own principal. Return null to reject. authenticate: async (token) => { const session = await verifyMySession(token) return session ? { subject: session.userId, tenant: session.orgId } : null }, // 2. Scope what a subject can read (row-level security). authorizeRead: (ctx, query) => query.and({ tenant: ctx.tenant }), // 3. Validate writes in your own terms. For update/delete, authorize against // the STORED node (`write.existing`), not the client-supplied data. authorizeWrite: (ctx, write) => { const tenant = write.op === 'create' ? write.payload.properties.tenant : write.existing?.properties.tenant return tenant === ctx.tenant ? { ok: true } : { ok: false, reason: 'wrong tenant' } } }) ``` `authenticate` returns a `ServerAuthContext` — `{ subject, ...claims }` — where `subject` is your own user id (or a `did:key` in `signed` mode). Extra claims (roles, orgs, tenant) ride along for the authorize hooks. `authorizeRead` receives a narrowable query; `query.and({ … })` ANDs equality filters into the read (the canonical "only this tenant's rows" move). `authorizeWrite` receives a normalized `PendingWrite`. For `update`/`delete` it includes `existing` — the **stored** node snapshot — so ownership checks and schema allow-lists can't be bypassed by a by-id write. Return `{ ok: false, reason }` to deny; the client receives a typed rejection. ## The trust spectrum How an end-user's identity maps onto xNet's signed-change model: | Mode | Who signs | `authorDID` is | Best for | | ------------- | ------------------------------- | --------------------------- | ------------------------------------- | | `server` | the server (one identity) | the server | centralized apps, maximum simplicity | | `custodial` | the server, per-user derived key | a stable per-user DID | mainstream apps wanting per-user attribution, no key UX | | `signed` | the client | the client's DID (bound to the authenticated subject) | tamper-evident, user-owned data | In `signed` mode the server verifies the client's signature **and** that the change's author matches the authenticated subject — a forged author is rejected (`IDENTITY_MISMATCH`), and a tampered change is rejected (`SIGNATURE_INVALID`). ## Wire it to React — no hook changes Reads route through the existing `remoteNodeQueryClient` seam: ```tsx const remoteNodeQueryClient = xnet.createRemoteQueryClient(getToken) export function App() { return ( ) } function Todos() { // Exactly the same hooks as a managed-Hub app: const { data: todos } = useQuery(TodoSchema, { where: { done: false } }) const { create, update } = useMutate() // … } ``` ## Mounting in your server `createXNetServer` is transport-agnostic — call `query`/`mutate` from any HTTP or WebSocket handler. A minimal Express sketch: ```ts const app = express() app.use(express.json()) // Reads app.post('/xnet/query', async (req, res) => { res.json(await xnet.query(req.body)) }) // Writes app.post('/xnet/mutate', async (req, res) => { const token = req.headers.authorization?.replace('Bearer ', '') res.json(await xnet.mutate(token, req.body)) }) ``` ## Storage By default `@xnetjs/server` keeps an in-memory store (great for tests). Pass any `NodeStorageAdapter` via the `storage` option to persist — for example a SQLite adapter — so your data lives in your own database. ## Status The engine — structured-query executor, backend-authoritative mutations, the auth hooks, and the trust spectrum — is shipped and tested. Networked transports (a built-in WebSocket relay, framework adapters, a Postgres adapter, live streaming), and the full offline write client are tracked as follow-ups in exploration `0223`. ## See also - [React Hooks overview](/docs/hooks/overview/) - [Hub Setup](/docs/guides/hub/) — the managed path - [Authorization](/docs/guides/authorization/) — xNet's built-in model (opt-in) --- ## Use xNet From Any Framework **You will learn** - That the full xNet data model runs **outside React** as a plain object - How `client.query()` and `liveQuery()` bind to Vue, Svelte, Solid, or vanilla JS - What each framework "support tier" actually promises - How to validate a binding with `runAdapterConformance` ## The data model is framework-agnostic The React hooks (`useQuery` / `useMutate` / `useNode`) are a thin binding over a headless runtime, not the only way in. [`@xnetjs/runtime`](/docs/architecture/package-graph/)'s `createXNetClient()` constructs and owns the entire data model — authorization, validation, signing, encryption, SQLite-backed storage, and the live query/mutate/subscribe loop — and imports React **nowhere**: ```ts const { identity, privateKey } = generateIdentity() const client = await createXNetClient({ nodeStorage: new MemoryNodeStorageAdapter(), // or a SQLite adapter authorDID: identity.did, signingKey: privateKey }) ``` `client.query(schema, options)` returns the universal **`{ getSnapshot, subscribe }`** contract — the exact pair that React's `useSyncExternalStore`, a Svelte store, a Vue `shallowRef`, a Solid signal, and Angular's `toSignal` all consume. `liveQuery()` wraps that pair as a **Svelte store** (`subscribe(run) => unsubscribe`, called immediately and on every change), which every other framework can adapt in a few lines. ## Bind it to your framework ```ts export function useQuery(client, schema, options) { const lq = liveQuery(client, schema, options) const data = shallowRef(lq.get()) const stop = lq.subscribe((v) => (data.value = v)) onScopeDispose(() => { stop() lq.destroy() }) return data // Ref } export function useMutate(client) { return client.mutate // { create, update, delete, restore, transaction } } ``` `liveQuery` already **is** a Svelte store, so `$`-auto-subscription works with no adapter at all: ```svelte {#each $tasks ?? [] as task}
  • {task.properties.title}
  • {/each} ``` In Svelte 5 you can wrap the same store in a rune for idiomatic `$state` ergonomics. ```ts export function createQuery(client, schema, options) { const lq = liveQuery(client, schema, options) return from((set) => { const stop = lq.subscribe(set) return () => { stop() lq.destroy() } }) } ``` No framework, no adapter package — subscribe directly: ```ts const tasks = liveQuery(client, TaskSchema, { where: { status: 'todo' } }) const stop = tasks.subscribe((rows) => render(rows ?? [])) await client.mutate.create(TaskSchema, { title: 'Ship it' }) // re-renders // later stop() tasks.destroy() await client.destroy() ``` ## Validate a binding once, everywhere The expensive part of multi-framework support isn't _writing_ a binding — it's proving every binding behaves identically, forever. So the behaviour is tested **once**, framework-agnostically. `runAdapterConformance(makeClient)` runs the reactive data contract against any client factory and **throws on the first failed check**: ```ts await runAdapterConformance((overrides) => createXNetClient({ nodeStorage: new MemoryNodeStorageAdapter(), authorDID, signingKey, ...overrides }) ) ``` It asserts that: - a live query delivers an **immediate** snapshot, then **updates on `mutate`** - it **stops delivering after unsubscribe** - a one-shot `fetch` **round-trips** a write - the **authorization surface is reachable and denial surfaces** - **`destroy()` is idempotent** A framework adapter reuses this suite and adds only a tiny render-harness test ("the ref/store/signal reflects the snapshot and re-renders") — it never re-tests xNet's semantics. ## What "supported" means Binding the data layer is cheap; carrying a full per-framework **component** library is not. So support is layered, and the layers promise different things: | Tier | Surface | What you get | | ---------- | ---------------------------------------------------- | --------------------------------------------------------------------------------------- | | **Tier 0** | `@xnetjs/runtime` — `createXNetClient` + `liveQuery` | Works with **every** framework, headless and conformance-gated. This page. | | **Tier 1** | `@xnetjs/react` — hooks **and** components | First-class: the full hook + component toolkit the app itself uses. | | **Tier 2** | thin Vue / Svelte data-binding adapters | `useQuery` / `useMutate` only — **data binding, not components** — published on demand. | | **—** | components in non-React frameworks | **Not offered.** The component kit is React by design. | tip Building UI in Vue or Svelte? You get the **data** — live queries, mutations, auth, sync — through the runtime. You build (or bring) your own components. The React app's components are not portable, and that's intentional: it keeps one component ecosystem honest rather than three half-maintained ones. See [`docs/explorations/0237`](https://github.com/crs48/xNet/tree/main/docs/explorations) for the full cost/benefit analysis behind this policy. **Not using JavaScript at all?** xNet also has native **Swift** and **Rust** implementations of the protocol. See [Languages & SDKs](/docs/languages/overview/) for the full picture. --- ## Connect to xNet Cloud **You will learn** - How the two identities (billing vs. passkey) fit together - How to connect the **web**, **desktop**, and **mobile** apps to your managed hub - What the short device code is and how approval works - How to troubleshoot a connection that won't complete After you subscribe at [xnet.fyi/cloud](https://xnet.fyi/cloud), xNet Cloud provisions a dedicated, always-on **hub** for your data. Your apps still hold the plaintext — the hub only ever stores encrypted updates and relays them between your devices. This guide links an app to that hub. You can open the relevant steps any time from the **Connect your apps** card on your [dashboard](https://cloud.xnet.fyi/dashboard). ## Two identities, one account xNet keeps the *who pays* and *whose data* questions separate on purpose: - **Billing identity** — the email you sign in to the dashboard with. Custodial and recoverable (a normal password/passkey reset). - **Data identity (your passkey)** — a `did:key` created **on your device** when you first open the app. Non-custodial: it never leaves the device, and it's what proves a device may read and write your data. We never see its private key. Connecting a device is the moment these two are bound together: you prove the billing side (you're signed in to the dashboard) **and** the data side (your app holds the passkey) at the same time. ## Connect your app 1. Open the [web app](https://xnet.fyi/app) (or click **Open web app** on your dashboard). 2. When prompted, **create your passkey**. This is your data identity — it stays on your device. 3. Choose **Connect xNet Cloud hub**. The app shows a short code like `ABCD-7K2P`. 4. On your dashboard, open **Connect your apps → Enter a code**, type the code, and approve. The app finishes connecting automatically. The desktop app connects to your hub by its URL. 1. On your dashboard, copy your **hub URL** (the **Connect your apps → Desktop** tab, or the **Endpoint** row — it looks like `wss://…hub.xnet.fyi`). 2. In the desktop app, open **Settings → Network** and paste it into the **Signaling server** field. 3. Restart the app, then create your passkey and choose **Connect xNet Cloud hub**. 4. Approve the short code it shows on your dashboard under **Enter a code**. note One-click desktop connect (an `xnet://` link that fills this in for you) is on the way. Until then, the copy-and-paste step above is all that's needed. 1. Install xNet on your phone and open it. 2. Create your passkey, then choose **Connect xNet Cloud hub**. 3. Approve the short code it shows on your dashboard under **Connect your apps → Enter a code**. ## What the device code is The short code is a standard [device authorization](https://datatracker.ietf.org/doc/html/rfc8628) flow — the same pattern you've used to sign a TV or a CLI into an account: ```mermaid sequenceDiagram participant App as Your app participant Cloud as xNet Cloud participant You as You (dashboard) App->>Cloud: I'm did:key:… — start a connection Cloud-->>App: Show code ABCD-7K2P You->>Cloud: Approve ABCD-7K2P (you're signed in) loop until approved App->>Cloud: Is ABCD-7K2P approved yet? end Cloud-->>App: Approved — here's your hub URL App->>App: Connect & sync ``` The code is short-lived (about 10 minutes). If it expires, just restart the connection from your app to get a fresh one. ## Troubleshooting - **"Code not found or expired."** Codes last ~10 minutes. Restart **Connect xNet Cloud hub** in your app for a new one, then enter it promptly. - **Desktop app won't connect after pasting the URL.** Make sure you pasted the full `wss://…` hub URL into **Signaling server**, then fully restart the app. You still need to create your passkey and approve a code — pasting the URL alone only points the app at the hub. - **Hub shows "Sleeping" on the dashboard.** Cold hubs wake on the next connection; give it a few seconds after your app reconnects. - **Still stuck?** See the [pricing FAQ](https://xnet.fyi/cloud/pricing#faq) or check the [status page](https://xnet.fyi/status). ## Related - [Hub & Signaling](/docs/guides/hub/) — self-host your own hub instead - [Identity & Keys](/docs/guides/identity/) — how passkeys and `did:key` work - [Electron Setup](/docs/guides/electron/) — the desktop app --- ## Electron Setup **You will learn** - How the Electron app architecture works (main process, renderer, IPC) - How to run the dev server and test sync with two instances - How the Background Sync Manager (BSM) provides process-level sync - How plugin services and the Local API work in Electron ## Architecture The xNet Electron app splits work between two processes: ``` ┌─────────────────────┐ IPC / MessagePort ┌────────────────────────┐ │ Main Process │◄─────────────────────────►│ Renderer Process │ │ │ │ │ │ BSM (sync manager) │ │ React app + hooks │ │ ProcessManager │ │ TipTap editor │ │ LocalAPIServer │ │ IPCSyncManager │ │ MCPServer │ │ ServiceClient │ │ WebSocket client │ │ DevTools panels │ └─────────────────────┘ └────────────────────────┘ ``` **Main process** — Runs the Background Sync Manager, manages child processes, hosts the Local API and MCP servers. Maintains its own Y.Doc pool and WebSocket connection to the signaling server. **Renderer process** — Runs the React UI. Communicates with the main process via IPC for sync operations. Maintains mirror Y.Docs for editor binding. ### Why this split? Sync is CPU-intensive (BLAKE3 hashing, Ed25519 signing, Yjs encoding). Running it in the main process keeps the renderer responsive. The BSM also survives renderer crashes and can sync in the background when no window is open. ## Running the dev server ```bash cd apps/electron && pnpm dev ``` This starts: 1. The Vite dev server on `http://localhost:5177` 2. The signaling server on port `4444` 3. The Electron app ### Two-instance sync testing ```bash cd apps/electron && pnpm dev:both ``` This launches two Electron windows connected to the same signaling server. Edits in one window appear in the other in real time. ## Background Sync Manager (BSM) The BSM (`apps/electron/src/main/bsm.ts`) is the Electron-specific sync engine. It runs independently of the renderer lifecycle. ### IPC channels | Channel | Direction | Purpose | | ------------------ | --------------- | ------------------------------------------------- | | `xnet:bsm:start` | Renderer → Main | Connect to signaling URL, set signing credentials | | `xnet:bsm:acquire` | Renderer → Main | Get a Y.Doc for editing; returns a MessagePort | | `xnet:bsm:release` | Renderer → Main | Done editing a document | | `xnet:bsm:track` | Renderer → Main | Add node to background sync set | | `xnet:bsm:untrack` | Renderer → Main | Remove from background sync | | `xnet:bsm:status` | Renderer → Main | Pool/tracked/queue stats | ### Document flow When a component calls `useNode(nodeId)`: 1. **Renderer** calls `window.xnetBSM.acquire(nodeId)` via IPC 2. **BSM** creates a Y.Doc, joins the sync room, creates a `MessageChannelMain` 3. **Renderer** gets the `MessagePort` and creates a local mirror Y.Doc 4. **Edits** flow through the MessagePort as binary Yjs updates (zero-copy transfer) 5. **BSM** signs updates with `signYjsUpdate()` and broadcasts via WebSocket 6. **Remote updates** are verified (`verifyYjsEnvelope`), applied to BSM doc, forwarded to renderer ### Identity setup The renderer passes signing credentials to the BSM on startup: ```ts // In the renderer const syncManager = new IPCSyncManager() await syncManager.start(signalingUrl) syncManager.setIdentity(authorDID, signingKey) ``` The BSM uses these credentials to sign all outgoing Yjs envelopes. ## IPCSyncManager The renderer-side `IPCSyncManager` implements the same `SyncManager` interface as the web version, but routes everything through IPC: ```ts interface SyncManager { start(): Promise stop(): Promise acquire(nodeId): Promise release(nodeId): void track(nodeId, schemaId): void untrack(nodeId): void getAwareness(nodeId): Awareness | null readonly status: ConnectionStatus readonly poolSize: number readonly trackedCount: number readonly queueSize: number } ``` The API is identical whether you're building for Electron or Web. React hooks and components work the same way — the sync manager is swapped at the provider level. ## Plugin services Electron enables Layer 3 (Services) and Layer 4 (Integrations) of the plugin system: ### ProcessManager Runs in the main process. Manages child processes with health checks and restart policies: ```ts // From a plugin's activate() function const services = createServiceClient() await services.start({ id: 'my-analysis-service', name: 'Data Analysis', process: { command: 'python', args: ['server.py'] }, lifecycle: { restart: 'on-failure', maxRestarts: 3 }, communication: { protocol: 'http', port: 8080 } }) const result = await services.call('my-analysis-service', 'POST', '/analyze', data) ``` ### Local API REST API on `localhost:31415` for external tools (Raycast, Alfred, shell scripts, etc.): ```bash curl http://localhost:31415/api/v1/nodes?schema=xnet://app/Task curl -X POST http://localhost:31415/api/v1/nodes \ -H "Content-Type: application/json" \ -d '{"schema": "xnet://app/Task", "properties": {"title": "New task"}}' ``` ### MCP server Exposes xNet data to AI agents via stdin/stdout JSON-RPC: ```bash echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | xnet-mcp ``` See the [Plugin Development](/docs/guides/plugins/) guide for full details on services and integrations. ## DevTools The Electron app includes 7 debug panels accessible from the app: - **Sync** — Connection status, pool state, peer scoring - **Store** — NodeStore contents, change history - **Schema** — Registered schemas and property types - **Identity** — Current DID, key info - **Network** — WebSocket messages, peer connections - **Plugins** — Registered plugins, contributions, middleware - **Performance** — Render timing, sync latency Enable verbose sync logging: ```js localStorage.setItem('xnet:sync:debug', 'true') ``` ## Experimental spatial Library viewer The Library graph's **Spatial viewer** control shares the saved links in the current view with a separate, read-only browser viewer. Search and source/group filters remain available in its flat view. A supported headset can request a stationary WebXR overview with a selected-resource card, Home, Back and explicit travel. To connect a headset, put it and the Mac on a trusted private network. Provide the Mac's HTTPS address with a port above 1023, then select a valid certificate for that address and its private key. Establish certificate trust on both devices through their operating systems; do not bypass browser warnings. The key stays on the Mac. Open the copied pairing link within five minutes. It can be used once, expires within one hour, and loses its capability on reload. **Revoke access** or quitting the desktop app stops access. Previously viewed content cannot be recalled. The viewer exposes scoped graph data, saved details and thumbnails. It does not expose private conversation records, the development debugger or the general Local API. A preview or written caption remains distinct from a spoken transcript. Vision Pro and PlayStation VR2 Sense support, headset performance and comfort are **not yet physically verified**. Experimental flight requires observed tracked position, rotation and analog trigger range, explicit arming and trigger release. Full-pose flight is not enabled. Choose **Exit / search** to leave immersion and use normal browser text input; an immersive DOM overlay is not assumed. Developers can run the synthetic 1,000, 10,000 and 56,000-link fixtures with `pnpm --filter xnet-desktop spatial:dev`. The development server is loopback-only; use the paired HTTPS path for a headset. The device review procedure is in `apps/electron/src/spatial/README.md` in the repository. ## Building for production ```bash cd apps/electron && pnpm build ``` This produces platform-specific binaries. The signaling server URL and other configuration are set via environment variables or the app's settings panel. --- ## Testing **You will learn** - How to run the xNet test suite - How to write tests for schemas, stores, and sync - Common patterns for mocking crypto and storage - How to test multi-peer sync scenarios ## Running tests ```bash # All tests (~4,700 tests across all packages) pnpm test # Single package pnpm --filter @xnetjs/sync test pnpm --filter @xnetjs/data test pnpm --filter @xnetjs/canvas test # Single file pnpm --filter @xnetjs/sync vitest run src/clock.test.ts # Pattern match pnpm --filter @xnetjs/data vitest run -t "NodeStore" # Watch mode pnpm --filter @xnetjs/sync test:watch ``` All tests use Vitest with the standard `describe` / `it` / `expect` structure. ## Test structure Follow the Arrange-Act-Assert pattern: ```ts describe('ModuleName', () => { describe('functionName', () => { it('should do expected behavior', () => { // Arrange const input = createTestData() // Act const result = functionName(input) // Assert expect(result).toBe(expected) }) }) }) ``` ## Testing schemas ```ts describe('TaskSchema', () => { const TaskSchema = defineSchema({ name: 'Task', namespace: 'xnet://example/', properties: { title: text(), priority: number({ default: 0 }), done: checkbox({ default: false }) } }) it('should have the correct schema ID', () => { expect(TaskSchema._schemaId).toContain('xnet://example/Task@') }) it('should define expected properties', () => { expect(TaskSchema._properties.title).toBeDefined() expect(TaskSchema._properties.priority).toBeDefined() expect(TaskSchema._properties.done).toBeDefined() }) }) ``` ## Testing crypto and signing Generate keys in tests using `@xnetjs/crypto` and `@xnetjs/identity`: ```ts describe('Signing', () => { it('should sign and verify a message', () => { const { publicKey, privateKey } = generateSigningKeyPair() const message = new TextEncoder().encode('hello') const signature = sign(message, privateKey) expect(verify(message, signature, publicKey)).toBe(true) }) it('should reject tampered messages', () => { const { publicKey, privateKey } = generateSigningKeyPair() const message = new TextEncoder().encode('hello') const tampered = new TextEncoder().encode('world') const signature = sign(message, privateKey) expect(verify(tampered, signature, publicKey)).toBe(false) }) }) ``` ## Testing Lamport clocks ```ts describe('LamportClock', () => { it('should increment on tick', () => { const clock = createLamportClock('did:key:alice') const [newClock, timestamp] = tick(clock) expect(newClock.time).toBe(1) expect(timestamp.time).toBe(1) expect(timestamp.author).toBe('did:key:alice') }) it('should fast-forward on receive', () => { const clock = createLamportClock('did:key:alice') const updated = receive(clock, 10) expect(updated.time).toBe(10) }) it('should break ties by DID', () => { const a = { time: 5, author: 'did:key:alice' } const b = { time: 5, author: 'did:key:bob' } // Deterministic: string comparison on DID expect(compareLamportTimestamps(a, b)).not.toBe(0) }) }) ``` ## Testing Change\ and hash chains ```ts describe('Change', () => { it('should sign and verify a change', () => { const { identity, privateKey } = generateIdentity() const { publicKey } = generateSigningKeyPair() const unsigned = { id: 'change-1', type: 'create-task', payload: { title: 'Test' }, parentHash: null, authorDID: identity.did, wallTime: Date.now(), lamport: { time: 1, author: identity.did } } const signed = signChange(unsigned, privateKey) expect(signed.hash).toMatch(/^cid:blake3:/) expect(signed.signature).toBeInstanceOf(Uint8Array) }) }) ``` ## Testing Yjs security ```ts describe('YjsEnvelope', () => { it('should round-trip sign and verify', async () => { const { identity, privateKey } = generateIdentity() const update = new Uint8Array([1, 2, 3, 4]) const envelope = signYjsUpdate(update, identity.did, privateKey, 12345) const result = await verifyYjsEnvelope(envelope) expect(result.valid).toBe(true) }) it('should reject tampered updates', async () => { const { identity, privateKey } = generateIdentity() const update = new Uint8Array([1, 2, 3, 4]) const envelope = signYjsUpdate(update, identity.did, privateKey, 12345) envelope.update = new Uint8Array([5, 6, 7, 8]) // Tamper const result = await verifyYjsEnvelope(envelope) expect(result.valid).toBe(false) }) }) ``` ## Testing sync scenarios For multi-peer sync tests, create separate clock instances and simulate message exchange: ```ts describe('Two-peer sync', () => { it('should converge after message exchange', () => { let alice = createLamportClock('did:key:alice') let bob = createLamportClock('did:key:bob') // Alice makes two changes let ts1 ;[alice, ts1] = tick(alice) let ts2 ;[alice, ts2] = tick(alice) // Bob receives Alice's second change bob = receive(bob, ts2.time) // Bob's next tick is higher than Alice's let ts3 ;[bob, ts3] = tick(bob) expect(ts3.time).toBe(3) }) }) ``` ## Testing plugins ```ts describe('PluginRegistry', () => { it('should install and activate a plugin', async () => { const activate = vi.fn() const registry = new PluginRegistry(mockStore, 'electron') await registry.install({ id: 'com.test.plugin', name: 'Test Plugin', version: '1.0.0', activate }) expect(activate).toHaveBeenCalled() const plugins = registry.getAll() expect(plugins[0].status).toBe('active') }) }) ``` ## Testing middleware ```ts describe('MiddlewareChain', () => { it('should execute in priority order', async () => { const chain = new MiddlewareChain() const order: number[] = [] chain.add({ id: 'second', priority: 200, async beforeChange(change, next) { order.push(2) return next() } }) chain.add({ id: 'first', priority: 100, async beforeChange(change, next) { order.push(1) return next() } }) await chain.executeBefore(mockChange, async () => { order.push(3) }) expect(order).toEqual([1, 2, 3]) }) }) ``` ## Common patterns ### Suppressing console noise ```ts vi.spyOn(console, 'error').mockImplementation(() => {}) vi.spyOn(console, 'warn').mockImplementation(() => {}) ``` ### Immutability assertions ```ts it('should not mutate the original clock', () => { const original = createLamportClock('did:key:alice') const originalTime = original.time tick(original) // Returns new object expect(original.time).toBe(originalTime) // Original unchanged }) ``` ### Test DIDs Use typed DID strings in tests: ```ts const testDID = 'did:key:z6MkTest123' as DID ``` Or generate real ones: ```ts const { identity } = generateIdentity() const did = identity.did // Real did:key:z6Mk... ``` --- ## Local-First ## What is local-first? Local-first software stores data on the user's device as the primary copy. The network is used for synchronization, not access. This is the opposite of the traditional client-server model where data lives on a remote server and the client is a thin view layer. ### The key principles 1. **Data ownership** — Your data lives on your device. You can read, write, and delete it without permission from any server. 2. **Offline by default** — The app works without a network connection. Queries are instant because they read from local storage, not a remote API. 3. **Sync, not fetch** — When a network is available, peers exchange changes directly. There's no single server that all clients depend on. 4. **No spinners** — Since data is local, reads are synchronous. The UI never shows a loading state for cached data. 5. **Longevity** — If the company behind the software disappears, your data survives. It's in a local database you control. ## How xNet implements this xNet stores all data in SQLite on the user's device. When you call `useQuery` or `useNode`, you're reading from a local database — not making a network request. ``` Traditional app: Client → Server → Database → Server → Client xNet app: Client → SQLite (done) ``` Sync happens in the background via WebSocket connections to a signaling server, which relays messages between peers. The signaling server never stores your data — it only forwards encrypted messages. ### The tradeoff Local-first requires solving conflict resolution. When two users edit the same data offline and then reconnect, the system must merge their changes without data loss. xNet uses two strategies: - **Yjs CRDTs** for rich text — character-level merge, no conflicts possible - **Lamport clock LWW** for structured data — field-level last-writer-wins with deterministic tie-breaking These are well-studied algorithms that guarantee all peers converge to the same state, regardless of the order they receive updates. ## Why it matters ### Performance Reads from local SQLite take microseconds. Reads from a server take 50-500ms. Local-first apps feel instant because the data is already there. ### Reliability The app keeps working when the wifi drops, the server goes down, or the user is on a plane. Changes queue up locally and sync when connectivity returns. ### Privacy Data can be encrypted end-to-end because the server never needs to read it. xNet signs every change with Ed25519 and can encrypt data with XChaCha20-Poly1305 for private content. ### User agency Users own their data in a concrete sense — it's in a database on their device. They can export it, back it up, or move it to a different app. No vendor lock-in. ## Further reading - [CRDTs](/docs/concepts/crdts/) — How conflict-free data types work - [Sync Architecture](/docs/concepts/sync-architecture/) — How xNet syncs peer-to-peer - [Offline Patterns](/docs/guides/offline/) — Building resilient offline UIs --- ## CRDTs ## What are CRDTs? A Conflict-free Replicated Data Type (CRDT) is a data structure that can be modified independently on different devices and merged automatically without conflicts. No central server is needed to coordinate — the mathematical properties of the data structure guarantee that all replicas converge to the same state. ## xNet's dual-CRDT model xNet uses two complementary CRDT strategies, each optimized for a different data shape: | Data type | CRDT | Resolution | Package | | --------------- | ----------- | ---------------------------- | ------------------------------ | | Rich text | Yjs | Character-level merge | `@xnetjs/sync` (Yjs integration) | | Structured data | Lamport LWW | Field-level last-writer-wins | `@xnetjs/sync` (clock + change) | ### Why two strategies? Rich text has complex structure — characters, paragraphs, formatting ranges, embedded objects. A general-purpose LWW register would lose edits when two users type in the same paragraph. Yjs solves this by tracking every character's position and identity in a sequence CRDT. Structured data (title, status, assignee) doesn't need character-level merging. A simple last-writer-wins strategy at the field level is sufficient and much simpler to implement and reason about. ## Yjs for rich text [Yjs](https://yjs.dev) is a high-performance CRDT implementation for collaborative editing. xNet uses Yjs to sync editor content: - Each node's rich text is stored in a `Y.Doc` containing a `Y.XmlFragment` - Yjs tracks every character with a unique ID (clientID + sequence number) - Concurrent inserts at the same position are ordered deterministically by clientID - Deletions are tombstoned (marked as deleted but kept for merge correctness) ### How merging works **Two users typing in different paragraphs** — edits are independent, merge trivially. **Two users typing at the same cursor position** — Yjs uses internal ordering rules (based on clientID, which is bound to a DID in xNet) to produce a deterministic interleaving. Both users see the same final text. **One user deletes text while another edits nearby** — Yjs preserves the edit. In general, inserts survive concurrent deletes. You don't need to handle any of this manually. The TipTap editor integration applies Yjs updates automatically. ## Lamport clocks for structured data For node properties (title, status, priority, etc.), xNet uses Lamport clocks with field-level last-writer-wins: ```ts interface LamportTimestamp { time: number // Logical clock value author: DID // Tie-breaker } ``` ### How it works 1. Each peer maintains a logical clock that starts at 0 2. On every mutation, the clock increments by 1 and the timestamp is attached to the change 3. When receiving a remote change, the local clock fast-forwards to `max(local, remote)` 4. On conflict (two changes to the same field), the one with the **higher** Lamport time wins 5. If times are equal (rare), the DID string is compared lexicographically as a deterministic tie-breaker ### Field-level resolution LWW is applied per-field, not per-node. If Alice changes `title` while Bob changes `status`, both changes are preserved — there's no conflict because they modified different fields. ``` Alice: { title: "New title" } @ time=5 Bob: { status: "done" } @ time=5 Result: { title: "New title", status: "done" } ← both win ``` If both change the same field: ``` Alice: { title: "Alice's title" } @ time=5, did:key:alice Bob: { title: "Bob's title" } @ time=5, did:key:bob Result: { title: "Bob's title" } ← Bob wins (DID tie-breaker) ``` ## Hash chains Changes are linked into a hash chain via `parentHash`. This provides: - **Causality** — you can trace the full history of a node - **Integrity** — tampering with a change breaks the chain - **Fork detection** — two changes with the same parent indicate concurrent edits Forks are valid — they represent concurrent modifications, not errors. The LWW resolver picks the winning value for each field deterministically. ## Convergence guarantee Both CRDT strategies guarantee **strong eventual consistency**: if two peers have received the same set of changes (in any order), they will have the same state. This is a mathematical property of the algorithms, not a best-effort heuristic. The practical implication is that xNet never shows merge conflict dialogs. The system always converges automatically. ## Further reading - [Sync Guide](/docs/guides/sync/) — How to configure and debug sync - [Sync Architecture](/docs/concepts/sync-architecture/) — The full sync stack - [Collaboration Guide](/docs/guides/collaboration/) — Building collaborative editors --- ## Sync Architecture ## Architecture overview xNet's sync system has four layers: ``` ┌──────────────────────────────────────┐ │ React hooks (useNode, useQuery) │ Application layer ├──────────────────────────────────────┤ │ SyncManager │ Orchestration │ NodePool · Registry · OfflineQueue │ │ MetaBridge · BlobSync │ ├──────────────────────────────────────┤ │ Yjs security layer │ Security │ Envelopes · Rate limits · Scoring │ │ ClientID attestation · Batching │ ├──────────────────────────────────────┤ │ ConnectionManager │ Transport │ WebSocket (multiplexed, room-based) │ └──────────────────────────────────────┘ ``` ## Transport layer A single multiplexed WebSocket connection handles all documents. Messages are routed by room (one room per document): - `subscribe(topics)` — join rooms - `publish(topic, data)` — broadcast to room - Auto-reconnect with configurable delay This is O(1) connections regardless of how many documents are open — not O(N) per document. ## Security layer Every Yjs update is wrapped in a `SignedYjsEnvelope` before transmission: 1. **BLAKE3 hash** the update bytes 2. **Ed25519 sign** the hash 3. Attach author DID, clientId, and timestamp On the receiving side: 1. **Rate limit check** — per-peer sliding window (30/sec, 600/min) 2. **Size check** — max 1 MB per update, 50 MB per document 3. **Signature verification** — extract public key from DID, verify Ed25519 4. **ClientID validation** — check attestation binding (clientId → DID) 5. **Peer scoring** — track violations, throttle/block bad peers ### Peer scoring Peers start at score 100. Violations deduct points: - Invalid signature: **-30** (auto-block after 3 occurrences) - Unsigned update: **-20** - Unattested clientId: **-15** - Oversized update: **-10** - Rate exceeded: **-5** Thresholds: warn at 50, throttle at 30, block at 10. Recovery: +1 per tick if clean for 60 seconds. ### Update batching Individual keystrokes produce ~5 Yjs updates per second. The `YjsBatcher` collects them and flushes every 2 seconds (or when the batch hits 50 updates). This reduces signing overhead from ~5/sec to ~0.5/sec without adding perceptible latency. ## Orchestration layer ### SyncManager The top-level orchestrator that wires everything together: - **`start()`** — connect, load state, join rooms - **`acquire(nodeId)`** — get a Y.Doc for editing (used by `useNode`) - **`release(nodeId)`** — done editing; doc stays warm - **`track(nodeId)`** — add to background sync set - **`stop()`** — disconnect, flush, save state ### NodePool Manages Y.Doc instances in three tiers: | State | Condition | Behavior | | ------ | ------------- | ------------------------------------------ | | Active | refCount > 0 | In use by a component. Never evicted. | | Warm | refCount = 0 | Released but cached. Evicted via LRU. | | Cold | Not in memory | Persisted in SQLite. Loaded on acquire. | Default warm pool size: 50 documents. ### Registry Persistent set of tracked nodes that survives app restarts. Tracked nodes sync in the background even when no component has them open. Entries expire after 7 days unless pinned. ### OfflineQueue When disconnected, local updates queue up (max 1000 entries, persisted for crash resilience). On reconnect, the queue drains in order. The Yjs state-vector exchange after reconnect reconciles any gaps. ### MetaBridge One-way bridge from NodeStore properties to Y.Doc metadata. Prevents malicious Yjs updates from corrupting structured data. Property writes always go through the signed `Change` pipeline. ## Electron architecture In Electron, sync is split across two processes: ``` Renderer (React UI) ←— IPC / MessagePort —→ Main (BSM) ←— WebSocket —→ Peers ``` The **Background Sync Manager (BSM)** runs in the main process: - Manages its own Y.Doc pool and WebSocket connection - Signs outgoing updates, verifies incoming ones - Survives renderer crashes - Streams binary updates to renderer via MessagePort (zero-copy) The renderer maintains mirror Y.Docs for editor binding. The `IPCSyncManager` implements the same `SyncManager` interface, so React hooks work identically on Electron and Web. ## Data flow: an edit ```mermaid sequenceDiagram participant User as User (TipTap) participant Renderer as Renderer Y.Doc participant BSM as BSM (Main Process) participant WS as WebSocket participant Remote as Remote BSM participant RemoteUI as Remote Renderer User->>Renderer: Type in editor Renderer->>BSM: MessagePort update BSM->>BSM: Apply to Y.Doc copy BSM->>BSM: Batch → BLAKE3 → Ed25519 sign BSM->>WS: SignedYjsEnvelope WS->>Remote: Broadcast to room Remote->>Remote: Rate limit → Size check → Verify sig Remote->>Remote: Apply to Y.Doc Remote->>RemoteUI: MessagePort (origin: remote) RemoteUI->>RemoteUI: Render merged text ``` 1. User types in TipTap editor → local Y.Doc update in renderer 2. Update forwarded to BSM via MessagePort 3. BSM applies to its Y.Doc copy 4. BSM batches, BLAKE3 hashes, Ed25519 signs → `SignedYjsEnvelope` 5. Envelope broadcast via WebSocket to room subscribers 6. Remote BSM receives: rate-limit check → size check → verify signature → apply 7. Remote BSM forwards to its renderer → applied with `'remote'` origin 8. Both renderers show the same text ## Further reading - [Sync Guide](/docs/guides/sync/) — Configuration, debugging, and API - [CRDTs](/docs/concepts/crdts/) — How conflict-free merging works - [Cryptography](/docs/concepts/cryptography/) — The primitives behind signatures - [Electron Setup](/docs/guides/electron/) — The BSM architecture in detail --- ## Identity Model ## Decentralized identity xNet uses **self-certifying identifiers** — your identity is derived from a cryptographic key pair, not assigned by a server. No registration, no email, no password. You generate a key pair and that's your identity. ## DID:key Every user is identified by a DID (Decentralized Identifier) in the `did:key` format: ``` did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK ``` This DID is derived from the user's Ed25519 public key: 1. Take the 32-byte Ed25519 public key 2. Prepend the multicodec prefix `0xed01` (Ed25519 identifier) 3. Encode with base58btc (multibase prefix `z`) 4. Prefix with `did:key:` The public key is **embedded in the DID itself**. To verify a signature, you parse the DID to extract the key — no external resolver, blockchain, or directory service is needed. ## Key pairs Each user has two key pairs: | Key | Algorithm | Purpose | | -------------- | --------- | -------------------------------------- | | Signing key | Ed25519 | Sign changes, UCAN tokens, Yjs updates | | Encryption key | X25519 | Key exchange, encrypt private data | The DID is derived from the signing public key. Both keys are bundled together as a `KeyBundle` and stored encrypted on the device. ## UCAN authorization UCANs (User Controlled Authorization Networks) are self-signed capability tokens. They replace traditional API keys, OAuth tokens, and ACL systems with a decentralized model where any user can grant capabilities to any other user. ### Token structure ```ts { iss: "did:key:z6Mk...", // Issuer aud: "did:key:z6Mk...", // Audience (who can use this token) exp: 1706003600, // Expiration (Unix seconds) att: [ // Capabilities granted { with: "xnet://doc/123", can: "write" }, { with: "xnet://doc/*", can: "read" } ], prf: [], // Proof chain (parent tokens) sig: Uint8Array // Ed25519 signature } ``` ### Delegation UCANs support transitive delegation. Alice can grant Bob access, and Bob can delegate a subset of that access to Carol: ``` Alice → Bob: { with: "xnet://doc/123", can: "write" } Bob → Carol: { with: "xnet://doc/123", can: "read" } (proof: Alice's token) ``` Each token in the chain is self-verifying — you extract the issuer's public key from their DID and check the signature. No server lookup required. ### Capability model - **Resources** are identified by URI: `xnet://doc/123`, `xnet://doc/*`, `*` - **Actions** are strings: `read`, `write`, `*` (wildcard) - Wildcards grant broad access; specific URIs grant narrow access ## How identity flows through xNet 1. **App startup** — Key bundle loaded from encrypted storage, identity provided via `XNetProvider` 2. **Data mutations** — Every `mutate.create()` / `mutate.update()` signs a `Change` with Ed25519 3. **Rich text editing** — Yjs updates are signed as `SignedYjsEnvelope` before broadcast 4. **Sync** — Remote peers verify all signatures before applying changes 5. **ClientID binding** — Yjs clientIDs are cryptographically bound to DIDs via attestations ## No accounts, no servers The identity system has no concept of "creating an account" or "logging in" to a server. Identity is: - **Generated locally** — a random Ed25519 key pair - **Self-certifying** — the public key is the identity - **Portable** — export your key bundle and use it on any device - **Verifiable offline** — signatures can be checked without network access ## Further reading - [Identity & Keys Guide](/docs/guides/identity/) — Practical API usage - [Cryptography](/docs/concepts/cryptography/) — The primitives behind identity - [Sync Guide](/docs/guides/sync/) — How signed updates propagate --- ## Cryptography ## Overview xNet uses a **hybrid classical + post-quantum** cryptographic stack, hardened against both current threats and future quantum attacks. NIST finalized the post-quantum standards in August 2024 (FIPS 203/204/205). Because xNet is still alpha, hybrid security ships as a clean implementation — no migration debt. | Algorithm | Role | Standard | Package | | ------------------ | ------------------------ | ------------- | --------------------- | | BLAKE3 | Hashing | — | `@noble/hashes` | | Ed25519 | Classical signing | RFC 8037 | `@noble/curves` | | ML-DSA-65 | Post-quantum signing | NIST FIPS 204 | `@noble/post-quantum` | | X25519 | Classical key exchange | RFC 7748 | `@noble/curves` | | ML-KEM-768 | Post-quantum KEM | NIST FIPS 203 | `@noble/post-quantum` | | XChaCha20-Poly1305 | Authenticated encryption | — | `@noble/ciphers` | All implementations are from the `@noble` library family — audited, pure TypeScript, no WASM, no native dependencies. ## Three security levels Every signed operation in xNet carries a `SecurityLevel` field. The three levels cover the full quantum threat spectrum: | Level | Name | Algorithms | Signature size | Threat protection | | ----- | ---------------- | ------------------- | -------------- | ---------------------- | | 0 | Fast | Ed25519 only | 64 bytes | Classical attacks | | 1 | Hybrid (default) | Ed25519 + ML-DSA-65 | ~3.4 KB | Classical + quantum | | 2 | Post-Quantum | ML-DSA-65 only | ~3.3 KB | Quantum (max security) | **Level 1 is the default.** Both signatures must verify (strict mode) — if either the Ed25519 or the ML-DSA component fails, the signature is rejected. This satisfies the NIST-recommended hybrid approach: if either algorithm is later broken, the other still provides protection. Level 0 is available for high-frequency, low-latency paths (e.g., per-keystroke Yjs updates) where the quantum threat model is low-risk. Switching the app-wide default is a single constant change. ### Signature structure A `UnifiedSignature` carries one or both signature components, plus the level tag: ```ts interface UnifiedSignature { level: 0 | 1 | 2 // Present at Level 0 and 1 ed25519?: Uint8Array // 64 bytes // Present at Level 1 and 2 mlDsa?: Uint8Array // ~3,293 bytes } ``` ### Signing and verifying ```ts // Sign at Level 1 (default) — requires both keys const signature = hybridSign(message, { ed25519: signingKey, mlDsa: pqSigningKey }) // { level: 1, ed25519: Uint8Array(64), mlDsa: Uint8Array(3293) } // Verify — returns structured result const result = hybridVerify(message, signature, { ed25519: publicKey, mlDsa: pqPublicKey }) // { valid: true, level: 1, details: { ed25519: { verified: true }, mlDsa: { verified: true } } } // Enforce minimum level const result = hybridVerify(message, signature, publicKeys, { minLevel: 1 }) ``` ### Threat model | Threat | Level 0 | Level 1 | Level 2 | | ------------------------- | ---------- | --------- | --------- | | Classical forgery | Protected | Protected | Protected | | Quantum forgery | Vulnerable | Protected | Protected | | Harvest-now-decrypt-later | Vulnerable | Protected | Protected | | Downgrade attack | N/A | Blocked | Blocked | At Level 1, both components must be compromised simultaneously to forge a signature — a property no currently known attack achieves. ## BLAKE3 BLAKE3 is used throughout xNet for content addressing and integrity: - **Change hashing** — Every `Change` is content-addressed with `cid:blake3:` - **Yjs update signing** — The BLAKE3 hash of the update bytes is what gets signed - **Storage integrity** — Persisted Y.Doc state is BLAKE3-hashed to detect corruption - **ClientID attestation** — The attestation message is BLAKE3-hashed before signing BLAKE3 is 3–5x faster than SHA-256. SHA-256 is available as a fallback for external system interoperability. ## Ed25519 Ed25519 is the classical signing algorithm: - Small keys (32-byte public, 32-byte private) and 64-byte signatures - Deterministic — same message + key always produces the same signature - The DID:key method spec uses Ed25519 as its primary key type ### Birational conversion to X25519 Ed25519 keys serve dual duty. The same keypair, via birational curve conversion, yields X25519 keys for Diffie-Hellman key exchange — no additional key material required: ```ts const x25519Pub = edwardsToMontgomeryPub(ed25519Pub) // for key wrapping const x25519Priv = edwardsToMontgomeryPriv(ed25519Priv) // for unwrapping ``` Any holder of a `did:key:` can have their X25519 key derived directly from their DID — no out-of-band key exchange. ## ML-DSA-65 (Dilithium3) ML-DSA-65 is xNet's post-quantum signing algorithm, standardized as NIST FIPS 204 (Module-Lattice Digital Signature Algorithm, formerly Dilithium3): | Property | Value | | ----------- | --------------------- | | Public key | 1,952 bytes | | Private key | 4,032 bytes | | Signature | 3,293 bytes | | Security | ~128-bit post-quantum | ### Performance | Operation | Ed25519 | ML-DSA-65 | Ratio | | --------- | ------- | --------- | ---------- | | Sign | ~0.1ms | ~2.5ms | 25× slower | | Verify | ~0.2ms | ~0.8ms | 4× slower | Level 1 combined: ~2.6ms sign, ~1.0ms verify. Verification caching reduces repeated verifications by 90%+. ## ML-KEM-768 (Kyber768) ML-KEM-768 is the post-quantum key encapsulation mechanism used for hybrid key exchange in the authorization system, standardized as NIST FIPS 203: | Property | Value | | ------------- | ----------- | | Public key | 1,184 bytes | | Private key | 2,400 bytes | | Ciphertext | 1,088 bytes | | Shared secret | 32 bytes | Used alongside X25519 for hybrid key wrapping: a content key is encapsulated with both X25519 and ML-KEM-768, so a peer must break both to recover it. ## XChaCha20-Poly1305 XChaCha20-Poly1305 is the authenticated encryption cipher: - **Per-node content encryption** — Every private node is encrypted before leaving the device - **Y.Doc state at rest** — Encrypted Yjs document state stored locally - **Key bundle storage** — Encrypting the user's private keys at rest ### Why XChaCha20? - 24-byte nonce (vs. 12 for AES-GCM) — safe to use random nonces without collision risk - Constant-time by design (no timing side-channels) - Poly1305 authentication tag detects any tampering ### Key wrapping (hybrid) Content keys are wrapped with X25519 + ML-KEM-768 in hybrid mode. An authorized recipient must have both classical and post-quantum private keys to unwrap: ``` Alice derives X25519 sharedSecret from her private key + Bob's Ed25519 DID Alice encapsulates with ML-KEM-768 → kem_ciphertext + kem_secret wrappedKey = XChaCha20(contentKey, hkdf(sharedSecret || kem_secret)) ``` ## Where crypto is used in xNet | Operation | Hash | Signature | Encryption | | -------------------- | ------------------------ | ------------------------- | -------------------------------- | | Create/update node | BLAKE3 (change hash) | hybridSign (Level 1) | XChaCha20 (per-node content key) | | Rich text edit | BLAKE3 (update hash) | hybridSign (configurable) | XChaCha20 (Y.Doc at rest) | | Store Y.Doc state | BLAKE3 (integrity check) | — | XChaCha20 (encrypted Yjs state) | | ClientID attestation | BLAKE3 (message hash) | Ed25519 (Level 0) | — | | UCAN token | — | hybridSign (Level 1) | — | | Key storage | — | — | XChaCha20 (encrypt bundle) | | Grant nodes | BLAKE3 (change hash) | hybridSign (Level 1) | XChaCha20 (per-node content key) | | Key wrapping | HKDF-SHA256 | — | X25519 + ML-KEM-768 → XChaCha20 | ## Security properties - **Authenticity** — Every change is signed. You can verify who made it. - **Integrity** — Hash chains detect tampering. Altering a change breaks the chain. - **Confidentiality** — Private data is encrypted end-to-end. No server sees plaintext. - **Non-repudiation** — Signatures prove authorship. The author cannot deny making a change. - **Quantum resistance** — Level 1 signatures require breaking both Ed25519 and ML-DSA-65 simultaneously. - **Harvest-now-decrypt-later protection** — Data encrypted today remains safe against future quantum computers. ## Further reading - [Authorization Guide](/docs/guides/authorization/) — Encryption-first access control, key wrapping - [Identity & Keys Guide](/docs/guides/identity/) — HybridKeyBundle, PQ registry, key recovery - [Sync Guide](/docs/guides/sync/) — How hybrid signatures protect sync --- ## Data Model ## Overview xNet's data model has three layers: 1. **Schemas** — Define the shape of your data (property types, defaults, validation) 2. **Nodes** — Individual data records conforming to a schema 3. **Changes** — Signed, hash-chained mutations that form an audit trail ## Schemas A schema declares the properties a node can have, using typed builder functions: ```ts const TaskSchema = defineSchema({ name: 'Task', namespace: 'xnet://my-app/', properties: { title: text({ required: true }), priority: number({ default: 0 }), done: checkbox({ default: false }), status: select({ options: [{ id: 'todo', name: 'To Do' }] as const }), project: relation({ target: 'xnet://my-app/Project@1.0.0' }) } }) ``` Each builder returns a typed descriptor that encodes the value type, default, and cardinality. TypeScript infers the full type from the schema definition — no manual type annotations needed. xNet provides 15 property types: | Type | Value | Notes | | ------------------------------ | ---------- | -------------------------- | | `text()` | `string` | Plain text | | `number()` | `number` | Numeric value | | `checkbox()` | `boolean` | True/false | | `date()` | `number` | Unix timestamp | | `select()` | `string` | Single choice from options | | `multiSelect()` | `string[]` | Multiple choices | | `url()` | `string` | URL string | | `email()` | `string` | Email address | | `phone()` | `string` | Phone number | | `relation()` | `string` | Reference to another node | | `relation({ multiple: true })` | `string[]` | Multiple references | | `person()` | `string` | Reference to a DID | | `person({ multiple: true })` | `string[]` | Multiple DID references | | `file()` | `object` | File attachment | See [Property Types](/docs/schemas/property-types/) for full details on each type. ## Nodes A node is an instance of a schema. Every node has base fields that are managed automatically by the store — you never define or set these yourself: ```ts interface NodeBase { id: string // Unique node ID (auto-generated) schemaId: string // Schema identifier createdAt: number // Set at creation time updatedAt: number // Updated on every change createdBy: string // Author DID updatedBy: string // Last modifier's DID } ``` When you read a node via `useQuery` or `useNode`, you get a `FlatNode` — the base fields merged with the schema properties: ```ts // FlatNode { id: 'abc123', schemaId: 'xnet://app/task@1.0.0', createdAt: 1706000000, updatedAt: 1706000100, createdBy: 'did:key:z6Mk...', title: 'Ship the feature', priority: 1, done: false, status: 'doing', project: 'project-456' } ``` ## NodeStore The `NodeStore` is the central data layer that manages CRUD operations and change tracking: - **Create** — `store.create(schema, properties)` → new node with signed change - **Read** — `store.get(id)` or `store.query(schema, filter)` → node(s) - **Update** — `store.update(id, changes)` → signed change with Lamport timestamp - **Delete** — `store.delete(id)` → soft delete with signed change Every mutation creates a `Change` record that is signed, hash-chained, and propagated to peers. ## Change\ The `Change` type is the fundamental unit of sync: ```ts interface Change { id: string // Unique change ID type: string // e.g., 'create-task', 'update-task' payload: T // The actual data hash: ContentId // cid:blake3:... content-addressed parentHash: ContentId | null // Previous change in the chain authorDID: DID // Who made this change signature: Uint8Array // Ed25519 over the hash wallTime: number // Wall clock (display only) lamport: LamportTimestamp // Causal ordering } ``` Changes form a hash chain — each change references its parent's hash. This creates a verifiable audit trail where: - **Tampering is detectable** — altering a change invalidates its hash and breaks the chain - **Authorship is provable** — every change is signed with Ed25519 - **Ordering is deterministic** — Lamport timestamps provide causal ordering across peers ## Batched mutations For multi-node operations, use `useMutate().mutate(...)`: ```ts await mutate([ { type: 'create', schema: ProjectSchema, id: 'project-acme', data: { name: 'Acme' } }, { type: 'create', schema: TaskSchema, data: { title: 'Setup', project: 'project-acme' } }, { type: 'create', schema: TaskSchema, data: { title: 'Launch', project: 'project-acme' } } ]) ``` The current `mutate()` API returns per-operation results and runs through the active data bridge. ## Further reading - [defineSchema](/docs/schemas/defineschema/) — Schema definition API - [Property Types](/docs/schemas/property-types/) — All 15 property types - [Type Inference](/docs/schemas/type-inference/) — How TypeScript types flow from schemas to hooks - [Relations](/docs/schemas/relations/) — Linking nodes together --- ## Network & Transport ## Overview `@xnetjs/network` handles getting data between peers. It sits below the sync layer — sync decides _what_ to send, network decides _how_ to get it there. The package provides: - A libp2p node with WebRTC and WebSocket transports - A layered security stack (connection gating, rate limiting, peer scoring, auto-blocking) - A custom sync protocol over libp2p streams - A y-webrtc provider for real-time document sync ## Transport stack ``` ┌─────────────────────────────┐ │ y-webrtc provider │ Real-time document sync ├─────────────────────────────┤ │ Custom sync protocol │ /xnet/sync/1.0.0 ├─────────────────────────────┤ │ libp2p │ Peer management, DHT ├─────────────────────────────┤ │ WebRTC · WebSocket · Relay │ Transports ├─────────────────────────────┤ │ Noise encryption · Yamux mux │ Security + multiplexing └─────────────────────────────┘ ``` ### Transports - **WebRTC** — Browser-to-browser peer connections via data channels - **WebSocket** — Signaling server connections, relay fallback - **Circuit Relay v2** — NAT traversal via relay nodes when direct P2P fails ### Connection security - **Noise protocol** — Authenticated encryption for all connections - **Yamux** — Stream multiplexing over a single connection ## Security stack ```mermaid flowchart TD A["Incoming connection"] --> B["1. Connection Limits\n(max connections, per-IP)"] B -->|allowed| C["2. Connection Gating\n(denylist, allowlist)"] C -->|allowed| D["3. Rate Limiting\n(token bucket per peer)"] D -->|allowed| E["4. Peer Scoring\n(reputation: -100 to +100)"] E -->|above threshold| F["5. Auto-Blocking\n(ban on repeated violations)"] F -->|passed| G["Process message"] B -->|denied| X["Reject"] C -->|denied| X D -->|exceeded| X E -->|below threshold| X F -->|blocked| X ``` Five layers of defense, each operating independently: ### 1. Connection limits The `ConnectionTracker` enforces hard limits: | Limit | Default | Strict | Relaxed | | ---------------------- | ------- | ------ | ------- | | Max connections | 100 | 50 | 200 | | Per peer | 2 | 1 | 4 | | Per IP | 5 | 3 | 10 | | Max pending | 20 | 10 | 50 | | Streams per connection | 100 | 50 | 200 | | Connections per minute | 30 | 15 | 60 | Three presets: `DEFAULT_LIMITS`, `STRICT_LIMITS` (mobile/constrained), `RELAXED_LIMITS` (trusted network). ### 2. Connection gating The `DefaultConnectionGater` intercepts connections at four points: 1. **Before accepting** — Check IP denylist 2. **Before dialing** — Check peer denylist 3. **After handshake** — Check limits, denylist, allowlist bypass 4. **Before stream** — Check stream limits Allowlisted peers bypass all connection limits. ### 3. Rate limiting Token bucket rate limiting at two levels: **Per-peer sync rate:** ```ts const limiter = new SyncRateLimiter() // 10 tokens/sec, 50 capacity limiter.canSync(peerId) // consume 1 token limiter.penalize(peerId, 'major') // reduce rate to 0.5x limiter.restore(peerId) // reset to default ``` **Per-protocol rate:** | Protocol | Rate | Capacity | | --------------------- | ------ | -------- | | `/xnet/sync/1.0.0` | 10/sec | 50 | | `/xnet/changes/1.0.0` | 20/sec | 100 | | `/xnet/query/1.0.0` | 5/sec | 20 | Penalized peers get dynamically reduced rates. ### 4. Peer scoring Reputation-based scoring inspired by GossipSub v1.1. Peers start at 0, range is -100 to +100: **Positive factors:** | Factor | Weight | |--------|--------| | Sync success | +0.5 | | Valid change | +0.1 | | Uptime (per minute) | +0.01 (cap +10) | | Low latency (\<100ms) | +5 | **Negative factors:** | Factor | Weight | |--------|--------| | Sync failure | -2 | | Invalid signature | **-50** | | Invalid data | -10 | | Rate limit violation | -5 | **Thresholds:** warn at 0, throttle at -20, disconnect at -50. Scores decay by 1% per minute toward zero. ### 5. Auto-blocking The `AutoBlocker` bans peers that exceed event count thresholds: | Event | Count | Window | Block Duration | | ------------------- | ----- | ------ | -------------- | | Invalid signature | 3 | 60s | **24 hours** | | Rate limit exceeded | 10 | 60s | 1 hour | | Connection flood | 20 | 60s | 1 hour | | Invalid data | 5 | 5 min | 12 hours | Blocks auto-expire. The auto-blocker integrates with the peer scorer — when a peer's score drops below the disconnect threshold, it's automatically blocked for 1 hour. ## Access control `PeerAccessControl` provides workspace-scoped access with this priority: ``` global deny > workspace deny > allowlist mode > default allow ``` When allowlist mode is enabled for a workspace, only explicitly allowlisted peers can sync. Deny entries support expiration. ## Security logging All security events are logged in a fail2ban-compatible format: ``` 2026-02-04T12:00:00.000Z XNET_SECURITY: type=invalid_signature severity=high peer=a1b2c3d4 action=blocked ``` Peer IDs are hashed for privacy. Events route by severity: critical/high to `console.error`, medium to `console.warn`, low to `console.log`. ## Custom sync protocol The `/xnet/sync/1.0.0` protocol provides structured document sync over libp2p streams: 1. Requester sends a `sync-request` with the local Yjs state vector 2. Responder replies with a `sync-response` containing the diff 3. Requester applies the update via `Y.applyUpdate()` Messages are serialized with msgpack and length-prefixed. ## Further reading - [Sync Architecture](/docs/concepts/sync-architecture/) — How network fits into the sync stack - [Cryptography](/docs/concepts/cryptography/) — The primitives used for signing and verification - [Hub & Signaling](/docs/guides/hub/) — The signaling server that brokers connections --- ## Architecture Overview ## Layered architecture xNet is organized as a layered stack where each package builds on the ones below it. Lower packages never import from higher ones. ``` ┌─────────────────────────────────────────┐ │ apps/electron · apps/web │ Applications ├─────────────────────────────────────────┤ │ @xnetjs/react │ React bindings (thin) │ useQuery · useMutate · useNode │ │ useIdentity · XNetProvider │ ├─────────────────────────────────────────┤ │ @xnetjs/runtime │ Framework-agnostic client │ createXNetClient · liveQuery │ │ SyncManager · NodePool · MetaBridge │ ├─────────────────────────────────────────┤ │ @xnetjs/data │ Data layer │ defineSchema · NodeStore │ │ 15 property types · validation │ ├─────────────────────────────────────────┤ │ @xnetjs/sync │ Sync primitives │ Lamport clocks · Change · chains │ │ Yjs security · envelopes · scoring │ ├─────────────────────────────────────────┤ │ @xnetjs/storage │ Persistence │ SQLite adapter │ ├─────────────────────────────────────────┤ │ @xnetjs/identity │ Identity │ DID:key · UCAN · key management │ ├─────────────────────────────────────────┤ │ @xnetjs/crypto │ Cryptography │ BLAKE3 · Ed25519 · XChaCha20 │ └─────────────────────────────────────────┘ ``` ## Additional packages | Package | Purpose | | ---------------- | ------------------------------------------------------------------- | | `@xnetjs/plugins` | 4-layer plugin system (scripts, extensions, services, integrations) | | `@xnetjs/canvas` | Infinite canvas with spatial indexing | | `@xnetjs/editor` | TipTap rich text editor with Yjs collaboration | | `@xnetjs/network` | libp2p node, WebRTC/WebSocket transport, peer security | | `@xnetjs/devtools` | 7 debug panels for inspecting sync, store, schema, and more | ## Design principles **Minimal coupling** — Each package has a focused responsibility. The crypto package knows nothing about schemas. The data package knows nothing about React. **No default exports** — Everything is a named export. Barrel files (`index.ts`) re-export from internal modules. **Factory functions** — Classes are paired with factory functions (`createFoo()` alongside `class Foo`). This keeps the API surface consistent and makes testing easier. **Immutability** — Core types like `LamportTimestamp` and `Change` are treated as immutable. Functions return new objects instead of mutating in place. **Validation over exceptions** — Functions return `{ valid: boolean, errors: [] }` objects instead of throwing. Exceptions are reserved for programmer errors, not data validation. ## How data flows ### Write path ```mermaid flowchart LR A["User action"] --> B["useMutate()"] B --> C["NodeStore.update()"] C --> D["Change‹T› + Lamport"] D --> E["BLAKE3 hash"] E --> F["Ed25519 sign"] F --> G["Hash chain link"] G --> H["SQLite"] G --> I["SyncManager"] ``` ### Read path ```mermaid flowchart LR A["useQuery(schema, filter)"] --> B["NodeStore.query()"] B --> C["SQLite read"] C --> D["FlatNode[]"] D --> E["Component render"] B -.->|subscribe| F["Change events"] F -.->|re-render| E ``` ### Sync path The interop kernel is the signed `Change` log — **not** Yjs. Structured node data replicates as signed changes; Yjs is a document codec whose updates ride the same wire as opaque, signed bytes. See [ADR-11](/docs/architecture/decisions/#adr-11-xnet-is-a-protocol--the-interop-kernel-is-the-change-log-not-yjs). ```mermaid flowchart LR A["mutate()"] --> B["Change‹T› + Lamport"] B --> C["BLAKE3 hash · Ed25519 sign · chain"] C --> D["SyncManager\n(@xnetjs/runtime)"] D --> E["Multi-hub\nConnectionManager"] E --> F["Hub relay → peers"] F --> G["Verify signature\n+ rate limit"] G --> H["Apply to change log"] A -. "rich-text / canvas nodes" .-> Y["Y.Doc → YjsBatcher\n→ signed envelope"] Y -. "opaque bytes" .-> D ``` ## Further reading - [Package Graph](/docs/architecture/package-graph/) — The full dependency graph - [Architecture Decisions](/docs/architecture/decisions/) — Why we made these choices --- ## Architecture Decisions This is the canonical log of xNet's architectural decisions. It is the one place to answer "why is it built this way?" — superseding the older internal `docs/TRADEOFFS.md`. ## How we keep this current These records follow the standard [ADR](https://adr.github.io/) discipline: - Every entry has a **Status**: `Proposed`, `Accepted`, `Deprecated`, or `Superseded by ADR-NN`. - **Accepted ADRs are immutable.** We don't rewrite a decision when reality changes — we add a _new_ ADR that supersedes the old one and set the old entry's status to `Superseded by ADR-NN`. The truth of the architecture is the whole chain, not the latest entry. (Typo fixes, dead-link fixes, and adding a **Tripwire** are the only in-place edits.) - **A one-way decision carries a Tripwire**: the observation that re-opens it. It is additive metadata, not part of the decision — it says nothing about what was chosen, only what would make us write the superseding ADR. Without one, a decision decays into a taboo: the rationale ages, the conditions that produced it change, and because nobody wrote down what would count as evidence against, the entry stops being re-openable and becomes a rule nobody remembers the reason for. This is the same job `review:` does for `docs/explorations/` (exploration 0421), and the reasoning is exploration 0430's. - **If an implemented change alters an architectural invariant, it adds or supersedes an ADR in the same PR.** Most decisions are worked out first in `docs/explorations/`; this page is the distilled outcome.
    ADR template ```markdown ## ADR-NN: **Status:** Proposed | Accepted | Deprecated | Superseded by ADR-MM **Context:** **Decision:** **Rationale:** - - **Tradeoff:** **Tripwire:** ```
    --- ## ADR-1: Yjs over Automerge for rich text **Status:** Accepted (2026-02) · scope clarified by [ADR-11](#adr-11-xnet-is-a-protocol--the-interop-kernel-is-the-change-log-not-yjs) **Decision:** Use Yjs for rich text CRDT, not Automerge. **Rationale:** - Yjs has a larger ecosystem (TipTap, ProseMirror, CodeMirror, Monaco integrations) - Better performance for large documents (Yjs encodes more compactly) - Mature awareness protocol for cursor presence - Active maintenance and wide adoption **Tradeoff:** Yjs is a mutable data structure (not pure-functional like Automerge). We mitigate this with the MetaBridge pattern — Yjs never writes to the NodeStore directly. **Scope note:** Yjs is the **document codec** for the rich-text/canvas _body_ of certain nodes — it is _not_ the sync backbone. Structured node data syncs through the signed `Change` log ([ADR-3](#adr-3-field-level-lww-for-structured-data)), and Yjs updates ride the wire as opaque bytes inside an xNet envelope. See [ADR-11](#adr-11-xnet-is-a-protocol--the-interop-kernel-is-the-change-log-not-yjs). ## ADR-2: DID:key for identity **Status:** Accepted (2026-02) **Decision:** Use `did:key` (Ed25519) as the identity format. **Rationale:** - Self-certifying — the public key is embedded in the DID, so verification requires no external resolver - No blockchain, registry, or server dependency - Small identifiers (~56 characters) - Ed25519 is widely supported and audited **Tradeoff:** DIDs are not human-readable. Display names are stored as profile metadata, not in the identifier itself. Key rotation requires creating a new DID (though UCAN delegation can bridge old and new identities). Account recovery is handled by social recovery — see [ADR-24](#adr-24-social-recovery-via-shamir-guardians). ## ADR-3: Field-level LWW for structured data **Status:** Accepted (2026-02) · this is normative protocol L1 — see [ADR-11](#adr-11-xnet-is-a-protocol--the-interop-kernel-is-the-change-log-not-yjs) **Decision:** Use Lamport clocks with field-level last-writer-wins for structured data, not a CRDT map. **Rationale:** - Simpler than a full CRDT for property data (titles, statuses, numbers) - Field-level granularity means non-conflicting fields always merge cleanly - Deterministic tie-breaking (DID comparison) ensures all peers converge - Lower overhead than maintaining CRDT metadata per field **Tradeoff:** True concurrent edits to the same field result in one write being silently dropped. In practice, this is acceptable for structured properties — users rarely edit the same title simultaneously. For rich text where character-level merging matters, Yjs handles it. ## ADR-4: BLAKE3 over SHA-256 **Status:** Accepted (2026-02) · post-quantum posture in [ADR-25](#adr-25-post-quantum-migration-posture) **Decision:** Use BLAKE3 as the primary hash function. **Rationale:** - 3-5x faster than SHA-256 on modern hardware - 256-bit output suitable for content addressing - Parallelizable (tree hashing) for large inputs - No length extension attacks **Tradeoff:** SHA-256 has wider interoperability (most external systems expect it). We provide SHA-256 as a fallback option in `@xnetjs/crypto` for interop cases. ## ADR-5: Named exports only **Status:** Accepted (2026-02) **Decision:** No default exports anywhere in the codebase. **Rationale:** - Eliminates the "what did I import?" ambiguity - Better tree-shaking in bundlers - Consistent import style across the monorepo - Easier to search for usages (grep for the exact name) ## ADR-6: Factory functions alongside classes **Status:** Accepted (2026-02) **Decision:** Export `createFoo()` factory functions alongside `class Foo`. **Rationale:** - Factory functions are easier to mock in tests - They can perform validation before construction - Consistent API surface (`createLamportClock`, `createExtensionContext`, `createLocalAPI`) - Classes are still available for `instanceof` checks when needed ## ADR-7: Validation returns, not exceptions **Status:** Accepted (2026-02) **Decision:** Validation functions return `{ valid: boolean, errors: string[] }` instead of throwing. **Rationale:** - Callers can inspect and aggregate errors - No try-catch boilerplate for expected failures - Works well with UI form validation - Exceptions are reserved for programmer errors (missing arguments, broken invariants) ## ADR-8: One-way MetaBridge **Status:** Accepted (2026-02) · MetaBridge now ships in `@xnetjs/runtime` — see [ADR-14](#adr-14-framework-agnostic-runtime--react-is-a-thin-binding) **Decision:** The MetaBridge syncs NodeStore → Y.Doc metadata, but not the reverse. **Rationale:** - Prevents malicious Yjs updates from poisoning structured data - Property changes always go through the signed `Change` pipeline with verification - Yjs metadata map is read-only from the editor's perspective - Clear security boundary between the two CRDT systems **Tradeoff:** Two-way sync would be simpler to implement. The one-way bridge requires property writes to go through `mutate()` even when the data is displayed in the editor context. ## ADR-9: Multiplexed WebSocket **Status:** Accepted (2026-02) · extended to multi-home routing in [ADR-20](#adr-20-namespace-scoped-multi-home-replication) **Decision:** Use a single WebSocket connection with room-based pub/sub, not one connection per document. **Rationale:** - O(1) connections regardless of document count - Reduces server-side resource usage - Simpler reconnection logic (one connection to restore) - Lower latency (no connection setup per document) **Tradeoff:** Requires a room routing layer on top of raw WebSocket. The signaling server must track topic subscriptions. ## ADR-10: BSM in Electron main process **Status:** Accepted (2026-02) **Decision:** Run the sync engine in Electron's main process, not the renderer. **Rationale:** - Keeps the renderer responsive (BLAKE3 + Ed25519 are CPU-intensive) - Survives renderer crashes - Can sync in the background when no window is open - MessagePort provides zero-copy binary transfer between processes **Tradeoff:** IPC overhead for every document update. Mitigated by using `MessageChannelMain` for binary transfer and batching updates. (A migration from Electron to a Deno-based desktop shell has been explored but not adopted.) --- The decisions below were made after the initial ten were written, as the system grew from an app into a protocol with a managed cloud. They are recorded here so the log reflects the architecture as it actually stands. ## ADR-11: xNet is a protocol — the interop kernel is the change log, not Yjs **Status:** Accepted (2026-06) **Context:** Exploration 0200. The normative spec lives in `docs/specs/protocol/`; see also [The Protocol](/docs/protocol/overview/). **Decision:** Treat xNet as a versioned, multi-implementation **protocol** whose normative surface is four layers — **L0** cryptographic primitives, **L1** data model, **L2** replication, **L3** authorization — with the application profile (**L4**) explicitly non-normative. The interop kernel is a **signed, hash-chained, per-property-LWW change log over schema-typed nodes** (`CURRENT_PROTOCOL_VERSION = 3` in `packages/sync/src/change.ts`). Yjs is a **pluggable document codec** for the rich-text/canvas body of certain nodes and travels the wire as opaque bytes inside an xNet envelope. **Rationale:** - A second implementation, in any language over any database, can forward and store the Yjs blob as an octet string and still fully participate in the node graph, identity, authorization, and replication — the hardest local-first portability problem (porting a CRDT byte format across languages) is off the critical path. - The boundaries already existed in the layered package graph; this decision writes them down and freezes them behind a conformance corpus. **Tradeoff:** Two merge systems (the LWW log and the Yjs CRDT) instead of one. Accepted deliberately — they have different conflict semantics and scale profiles (see [ADR-1](#adr-1-yjs-over-automerge-for-rich-text) and [ADR-3](#adr-3-field-level-lww-for-structured-data)). This ADR clarifies ADR-1 and elevates ADR-3 to normative status. **Tripwire:** a second implementation cannot fully participate in L0–L3 while treating the Yjs body as an opaque octet string — i.e. some normative behaviour turns out to require decoding the document bytes. That would mean the codec is not pluggable and the kernel boundary is drawn in the wrong place. ## ADR-12: SQLite everywhere — better-sqlite3 + Litestream, not Turso/libSQL **Status:** Accepted (2026-06) **Context:** Explorations 0178 (hosting economics) and 0212 (engine merits). **Decision:** Keep SQLite as the durable storage substrate across all five runtimes behind one adapter (`@xnetjs/sqlite`). On the web, persist via **OPFS + SQLite WASM** in a single serial worker; on the hub, use **better-sqlite3 with Litestream** streaming replication to Cloudflare R2 (`packages/hub/src/storage/litestream.ts`). Do **not** migrate to libSQL or Turso Database. **Rationale:** - xNet barely uses SQLite as a relational database — the schema is an append-only, signed, hash-chained change log with a denormalized scalar index; graph walks and CRDT merges happen in TypeScript/Rust, not SQL. Most of Turso's advances (query planner, relational concurrency) are low-leverage here. - The two features that _would_ tempt us (embedded vector ANN, concurrent writes) live in two different Turso products, neither production-ready together today; migrating would cost five platform adapters and an FTS5 rewrite. - FTS5 and R-Tree/GIS (which we _do_ use) are battle-tested on SQLite. **Tradeoff:** Single-writer serialization and no built-in vector index. A bounded Turso pilot on the disposable `telemetry.db` is sanctioned as a probe. **Tripwire:** one engine ships production-ready embedded vector ANN **and** MVCC concurrent writes together (today they live in two different Turso products), or a shipped feature needs a vector workload SQLite + FTS5 demonstrably cannot serve. ## ADR-13: Local-first — the hub is an accelerant, never a dependency **Status:** Accepted (2026-06) **Context:** Exploration 0188. See also [Local-first](/docs/concepts/local-first/). **Decision:** The local device holds the master copy. Nothing on a hub or the network may block a local read or first paint; hub work (relay, backup, search, signaling) is fire-and-forget and strictly additive. **Rationale:** - Local-first is the product's core promise (own your data, work offline, exit freely) — it must be an enforced invariant, not an aspiration. - A regression where hub room-subscription blocked document load caused 10–30s stalls; the fix (decouple local load from hub acquisition) codified the rule. **Tradeoff:** Some cross-device features are eventually-consistent rather than instantly authoritative. Accepted: correctness comes from the convergent LWW log, so "eventually" is safe. **Tripwire:** a shipped feature cannot produce its first paint without a hub round-trip — not "is slower offline", but _cannot render_. One such feature makes the hub a dependency in fact regardless of what this entry says, and the honest move is to supersede rather than carry a promise the product no longer keeps. ## ADR-14: Framework-agnostic runtime — React is a thin binding **Status:** Accepted (2026-06) **Context:** Explorations 0185 and 0237. **Decision:** The full client — store, MetaBridge, SyncManager, NodePool, Registry, OfflineQueue, ConnectionManager — lives in the React-free `@xnetjs/runtime` package. `createXNetClient()` and `liveQuery()` expose a universal `{ getSnapshot, subscribe }` contract. `@xnetjs/react` is a thin **T1** binding (`useQuery`/`useMutate`/…) that re-exports the runtime. Support tiers: **T0** any framework/vanilla (the runtime, ships today), **T1** React (first-party), **T2** Vue/Svelte/Solid (demand-gated, ~40-line adapters). **Rationale:** - The reactive seam is tiny — only two files in `@xnetjs/react` touch `useSyncExternalStore`; everything else is business logic and JSX. - Decoupling lets the runtime power CLIs, servers, and non-React apps without a React dependency. **Tradeoff:** "Support" for a framework means feature parity, not just a data binding — the ~30k LOC of `@xnetjs/react` is the real cost. So T2 adapters are published only on demand, and only the data hooks (not `@xnetjs/ui`) are in scope. ## ADR-15: Open-core license split — MIT core, FSL cloud, MIT-private contract **Status:** Accepted (2026-06) **Context:** Exploration 0181. **Decision:** Publish the adoption engine (core packages) under **MIT**. License the managed control plane, `@xnetjs/cloud`, under **FSL-1.1** (source-available, converting to Apache-2.0 on its Change Date; `packages/cloud/LICENSE`). Keep the entitlement contract in a separate, permissively-licensed `@xnetjs/entitlements` (MIT, `private`) so the self-hostable MIT hub can verify a signed `HUB_PLAN` token without ever taking an FSL — or a Stripe/AWS — dependency. **Rationale:** - The hub must remain fully MIT and dependency-light; the cloud must be protectable. The entitlement contract is the one seam both sides share. - FSL protects against a hyperscaler reselling the managed service while guaranteeing eventual open-source (the Apache future license). **Tradeoff:** A three-package licensing story is more to explain than "all MIT" or "all FSL." The `@xnetjs/hub` package deliberately has zero dependency on `@xnetjs/cloud`; that separation is by convention (and verified by the absence of the import), not yet a lint rule. **Tripwire:** the MIT hub acquires a dependency on FSL-licensed code (which `pnpm check:cloud-boundary` would catch first), or a hyperscaler ships a managed xNet anyway — proving FSL bought no protection and only cost adoption. ## ADR-16: Automated releases via Changesets + Conventional Commits **Status:** Accepted (2026-06) **Context:** Exploration 0220. **Decision:** Version and publish with [Changesets](https://github.com/changesets/changesets). A `fixed` group of 12 core packages (`core`, `crypto`, `identity`, `sync`, `data`, `storage`, `sqlite`, `data-bridge`, `abuse`, `plugins`, `history`, `react`) versions in lockstep; periphery versions independently. Conventional Commits are enforced by commitlint; publishing uses npm Trusted Publishing (OIDC) with provenance. Changeset coverage for publishable packages is enforced by a Stop hook (`scripts/changeset/assert-coverage.mjs`). **Rationale:** - The `fixed` core avoids a combinatorial version matrix across tightly-coupled packages; independent periphery avoids forcing churn on loosely-coupled ones. - OIDC removes long-lived npm tokens from the repo. **Tradeoff:** The semver bump must be read from the _diff_, not the commit prefix (a removed export or changed wire contract is a major even under a `feat:` commit). This requires discipline the hook can prompt for but not fully decide. ## ADR-17: Plugin trust and capability model **Status:** Accepted (2026-06) **Context:** Explorations 0189, 0192, 0194, 0196. **Decision:** Extensibility is governed by a shared trust fabric. `@xnetjs/trust` maps install **provenance** (`builtin` / `authored` / `ai-generated` / `imported` / `marketplace` / `synced`) to a **trust tier** and a **sandbox kind** (`host` / `ses-worker` / `iframe`). Capability endowments are enforced at the seam — `guardStore` gates data access, `guardedFetch` gates the network (SSRF-guarded) in `@xnetjs/plugins`. Paid plugins carry Ed25519, DID-bound license tokens (`@xnetjs/licenses`) with a **fail-closed** install gate. **Rationale:** - "Everything is a plugin" only works if untrusted code is contained by construction; provenance is the natural axis for how much to trust. - Fail-closed licensing means a missing or invalid license blocks install, never silently downgrades. **Tradeoff:** More ceremony for plugin authors (declared capabilities, sandbox constraints) in exchange for a substrate that can safely run third-party and AI-generated code. ## ADR-18: Managed AI via hub broker, plus bring-your-own local models **Status:** Accepted (2026-06) **Context:** Explorations 0201, 0208, 0244, 0252. **Decision:** For managed AI, the client uses a **keyless** `ManagedProvider` that POSTs to the hub's `/ai/chat` (+ `/ai/chat/stream` SSE); the hub injects tenant credentials, holds the OpenRouter key, and meters exact `usage.cost` server-side (`packages/hub/src/features/ai-forwarder.ts`). In parallel, a bring-your-own path runs models **locally** — WebLLM in-browser and Chrome's built-in "Nano" via an `availability()` probe (`packages/plugins/src/ai/`). **Rationale:** - Keyless managed AI means no provider key ever reaches the client; the hub is the metering and margin-safety boundary. - Local models give a zero-cost, fully-private tier that needs no hub at all, consistent with [ADR-13](#adr-13-local-first--the-hub-is-an-accelerant-never-a-dependency). **Tradeoff:** Two provider code paths to maintain, and local-model availability varies by browser/hardware. Detection is capability-probed, not assumed. **Tripwire:** a provider worth routing to requires a key on the client (the keyless property is the whole boundary), or local models reach parity such that the managed path exists only to meter — at which point it is a billing decision wearing an architecture costume. ## ADR-19: Plan-first AI mutations **Status:** Accepted (2026-06) **Context:** `docs/AI_SURFACE_CONTRACT.md`. **Decision:** AI never writes directly. The shared AI surface expresses writes as an `AiMutationPlan` that must move through **validate → preview → apply → audit**. Every tool declares `requiredScopes` and a risk level (`low`/`medium`/`high`/ `critical`); plans are serializable JSON so they flow identically through MCP, the Local API, file projection, and audit logs. **Rationale:** - A plan-first pipeline makes AI writes reviewable and reversible, and keeps one contract across every adapter. - Risk levels + scopes let the UI gate high-consequence actions (`storage.recovery` requires `critical`). **Tradeoff:** More indirection than letting an agent call `mutate()` directly, in exchange for auditable, user-approvable, rollback-friendly AI edits. ## ADR-20: Namespace-scoped multi-home replication **Status:** Accepted (2026-06) · extends [ADR-9](#adr-9-multiplexed-websocket) **Context:** Exploration 0258. **Decision:** Sync routes selectively per **namespace**. A multiplexed multi-hub connection manager (`packages/runtime/src/sync/connection-manager.ts`) maintains one connection per hub; a replication-policy planner (`packages/sync/src/replication-policy.ts`) decides which namespaces replicate to which hubs/peers, with per-namespace `minHubs`/`maxHubs` and signed-replication requirements. A user-facing **Space** maps to a namespace via `spaceNamespace()`, carrying a `ReplicaTrust` of `trusted` or `zero-knowledge` (`packages/runtime/src/sync/replication-scope.ts`). **Rationale:** - Different data belongs in different homes (system vs personal vs community vs peer); routing by namespace is the smallest primitive that expresses that. - Correctness is free — the multi-master LWW log already converges regardless of topology; this decision is about _where_ bytes go, not _whether_ they merge. **Tradeoff:** Only the routing slice is shipped; the manifest schema, device DID, anti-entropy, trust gating, and UI are deferred. The planner exists ahead of full consumption. **Tripwire:** a real replication policy needs a unit finer than a namespace (per node, per schema) or coarser (per account), or the planner is still unconsumed by the time the manifest and trust gating ship — built-ahead machinery that never acquires a caller is the shape this repo already knows from 0377. ## ADR-21: Append-only change log with off-boot compaction **Status:** Accepted (2026-06) **Context:** Explorations 0204, 0254, 0260. **Decision:** Never delete from the change log; append tombstones and materialize current state. Reclaim space with **compaction that runs off the boot path** — gated behind `runWhenBootSettled` (resolves at first-rows), using tiny loop-until-dry chunks that bail on a hidden tab (`apps/web/src/lib/change-log-compaction.ts`). The web runtime funnels all SQLite work through one serial worker with a priority scheduler. **Rationale:** - The append-only log makes sync trivial and gives a complete audit trail; but an unbounded log inflates cold-start. - On a single serial SQLite worker, **no background work is free during boot** — `requestIdleCallback` tracks main-thread idle, which is idle precisely while the worker is saturated. Scheduling maintenance _after_ boot settles is the only reliable fix; priority reorders work, it never parallelizes it. **Tradeoff:** Reclamation is deferred rather than immediate, and compaction is best-effort (bails on backgrounded tabs). Accepted: a responsive cold open outranks prompt disk reclaim. Compaction stays default-on, opt-out via `xnet:compact:changes='off'`. **Tripwire:** compaction stops keeping up — the change log grows monotonically across a release cycle on an ordinary workload — or cold open breaches exploration 0266's stop rule (first rows under 100ms p95) with compaction already default-on. Either means deferred reclamation has stopped being free, which is the entire basis of this entry. ## ADR-22: Consent-gated observability **Status:** Accepted (2026-06) **Context:** Exploration 0210. **Decision:** Zero telemetry by default. Error monitoring (Sentry) and analytics (Plausible) initialize only when _both_ a build-time endpoint is configured (`VITE_SENTRY_DSN` / `VITE_ANALYTICS_DOMAIN`) _and_ the runtime consent tier allows it (`packages/telemetry/src/consent/manager.ts`; `apps/web/src/lib/{sentry,analytics,error-reporter}.ts`). Reports are scrubbed and values are P3A-bucketed. **Rationale:** - Decentralized, own-your-data software must not phone home without explicit, granular consent; gating at both build and runtime makes "off" the safe default. **Tradeoff:** Far less diagnostic data (users rarely opt in), so we lean on reproducible boot timelines and local forensics instead of always-on telemetry. ## ADR-23: Values-as-code CI gates **Status:** Accepted (2026-06) **Context:** Explorations 0199 (motion) and 0234 (humane charter). **Decision:** Encode the product's values as enforced lints, not just prose. A motion-vocabulary gate (`scripts/check-motion-vocab.mjs`) bans ad-hoc animation outside the approved vocabulary; a humane-patterns gate (`scripts/check-humane-patterns.mjs`) bans dark patterns (infinite scroll, streaks, engagement-maximizing nudges). Both sit alongside the Humane Internet Charter (`docs/CHARTER.md`) and a real "Right to Leave" export-everything panel. **Rationale:** - A stated value that CI can't defend drifts. Mechanizing "calm" and "no dark patterns" makes them regression-proof and legible to skeptics. **Tradeoff:** Some legitimate UI needs a documented exception path around the gates. Accepted: the friction is the point — it forces the intent to be explicit. ## ADR-24: Social recovery via Shamir guardians **Status:** Accepted (2026-06) **Context:** Exploration 0243. **Decision:** Recover an identity through **Shamir-split guardian shares** (`packages/identity/src/recoverable.ts`) — a threshold of trusted guardians reconstructs the key — alongside recovery phrases and synced passkeys. The cloud is never a custodian. Custodial escrow was explicitly **declined**. **Rationale:** - `did:key` has no built-in rotation ([ADR-2](#adr-2-didkey-for-identity)), so recovery must live outside the key itself. - Custodial escrow is coercible (subpoena, insider, breach); social recovery keeps trust distributed and cloud-free. **Tradeoff:** Recovery depends on the user having designated reachable guardians ahead of time. Accepted as the price of a non-coercible, self-sovereign model. ## ADR-25: Post-quantum migration posture **Status:** Proposed **Context:** Exploration 0257; the future path for [ADR-4](#adr-4-blake3-over-sha-256) and [ADR-2](#adr-2-didkey-for-identity). **Decision (proposed):** Adopt a phased migration to post-quantum signatures — Phase 2 hybrid (Ed25519 + ML-DSA), Phase 3 ML-DSA primary with Ed25519 legacy — behind an algorithm-agility seam, rather than a flag-day switch. **Rationale:** - Ed25519 is broken by Shor's algorithm; a hash-chained, signed log needs a credible PQ story before it's a compliance blocker. - Hybrid signatures preserve interop during the transition. **Tradeoff / open:** Larger signatures and a two-algorithm verification path. This is a documented _posture_, not shipped code — it stays `Proposed` until the seam and hybrid signing land, at which point it is superseded by an `Accepted` ADR. ## ADR-26: Cross-hub grants — plane split before propagation **Status:** Accepted (design); implementation deferred to a follow-up **Context:** Explorations 0258/0382/0383 (W4). Hub-to-hub Space subscription shipped for **public** Spaces; grants do not cross hubs. **Decision:** Cross-hub access control splits by plane before any grant ever propagates. The **public plane** needs no grants: a hub mirrors another hub's public Space over the ordinary wire protocol, and mirrored state is **never re-exported** (served only under `/sub/*`), so subscription cycles cannot amplify. The **granted plane** stays single-hub until a dedicated design lands: a grant is a capability minted by a Space's home hub, and no mirror, gateway, or federation surface may widen it. When cross-hub grants are built, they will be **delegation chains rooted at the granting hub's persistent DID** (UCAN-style, matching the existing auth kernel) — never grant-table replication, which would turn every subscribed hub into a policy-enforcement point it cannot honestly be. **Rationale:** - Public-first delivered the hub-of-hubs primitive without touching the security kernel (0383's subscription-first ordering). - Replicating grant rows would make revocation eventually-consistent across hubs an attacker can choose among — a deny must always win (0359). - Delegation chains keep the home hub authoritative: a downstream hub can _prove_ access was granted without being able to _mint_ it. **Tradeoff:** Members of a gated community cannot yet read it through a different hub. Accepted: correctness of revocation outranks read locality. ## ADR-27: `@xnetjs/server` stays a separate product **Status:** Accepted **Context:** Exploration 0382/0383 (the standing question): "everything is a hub" unified the server surface into one binary with roles — except `@xnetjs/server`, the BYO-backend engine (exploration 0223), which does not depend on `@xnetjs/hub` at all. **Decision:** **Scope out.** `@xnetjs/server` is not a hub role and will not be absorbed. It serves a different buyer: an app team embedding xNet's data model inside _their_ backend (their auth, their storage, their trust mode) — not an operator running xNet's server. The hub's role system covers every deployment of _our_ server; `@xnetjs/server` remains the library for building _someone else's_. **Rationale:** - Absorbing it as a role would couple its `TrustMode`/storage hooks to hub release cadence for zero operator benefit (the MinIO gateway lesson, 0382: a role that cannot share the core's invariants is a neighbour, not a role). - The decision is recorded precisely so the "second server" cannot drift back into ambiguity one layer up (0383 R6). **Tradeoff:** Two server documentation surfaces. Accepted; they answer different questions. **Tripwire:** `@xnetjs/server`'s `TrustMode` and storage hooks converge with the hub's until a role _could_ share the core's invariants (the 0382 test for neighbour vs role), or the BYO-backend buyer fails to materialise — nobody embeds it in their own backend — at which point maintaining a second server is paying for an audience that does not exist. ## ADR-28: No durable-execution orchestrator; reconcilers instead **Status:** Accepted **Context:** Exploration 0411 evaluated adopting [Temporal](https://temporal.io/) (and Restate, DBOS, `pg_durable`, Inngest, Cloudflare Workflows) for the parts of the stack that look workflow-shaped: tenant provisioning, staged fleet rollouts, nightly restore drills, and the non-payment lifecycle. **Decision:** **Do not adopt a workflow engine.** Fix the three real durability gaps in-repo with primitives over the `DocStore` port the control plane already ships — a compensating `saga()`, a leased due-based job runner, and a durable `RolloutRun` checkpoint. **A workflow engine may only ever be considered for `apps/cloud`.** It must never enter `packages/hub`, `packages/server`, or any client package. **Rationale:** - Temporal and its peers provide durable _execution_; xNet's hard problem is durable _state_, which CRDTs and the signed change log already solve. The position was already recorded in exploration 0332's landscape survey. - It cannot run where most xNet work happens. The Temporal TypeScript SDK runs workflow code in a Node-only deterministic sandbox against a server cluster — there is no browser or offline story, and the device is xNet's primary. - In `packages/hub` it would break a Charter §6 receipt ("the hub is a single self-contained process"), failing the **BATNA** test: a self-hoster would have to operate a workflow cluster to run their own hub. - The control plane is deliberately built as pure decision functions plus level-triggered reconcilers, which are restart-safe by construction. Only two modules deviated, and both were ordinary bugs rather than a missing capability. - Every candidate bottoms out in a datastore we do not run. There is no Postgres anywhere in the stack (SQLite + Firestore only), so the usual "just use DBOS" answer is unavailable. **Tradeoff:** We maintain ~300 lines of scheduling and compensation logic ourselves. Accepted, and bounded. **Tripwire:** any of the six decidable tripwires recorded in exploration 0411, or the hand-rolled primitives (`saga()`, the leased job runner, the `RolloutRun` checkpoint) growing past ~500 LOC — at which point we are maintaining the thing we declined to adopt, without its testing or its operator tooling. ## ADR-29: xNet is not an agent harness **Status:** Accepted **Context:** Exploration 0416 asked whether xNet should connect to agent harnesses (OpenClaw, Hermes, Buzz) or build a competing one with its own privacy layer. "Agent harness" turned out to name three separate jobs, two of which xNet already occupies in shipped code: the **substrate** agents act against (`xnet mcp serve`, Agent Passports, the audit trail — exploration 0337) and the **client** that drives an agent (the bridge daemon and `AgentFrame` wire — exploration 0392). Only the third — owning the agent loop itself, with channels, scheduling, memory, and a skill marketplace — was genuinely undecided. **Decision:** **Do not build an agent harness.** xNet is the _accountability substrate_ agents run against and a _client_ for the good ones. The agent loop, its messaging channels, its cron and heartbeats, and its skill marketplace are permanent non-goals. The corollary is a positive commitment: the guardrail, the passport, and the audit ledger stay **xNet-side** and apply identically to every connected agent, regardless of what that agent's own permission model claims. **Rationale:** - **The layer commoditised.** Five meta-harnesses landed in roughly one week of June 2026 — Databricks Omnigent (Apache-2.0), Zed ACP, Vercel HarnessAgent, Cloudflare Flue, and Conductor — on top of two excellent free harnesses (Hermes, MIT; OpenClaw). Nothing xNet builds here stays differentiated for a quarter. - **The layer beneath it did not.** OpenClaw's audit is mutable JSONL with documented blind spots for cron jobs and sub-agents; Hermes records learned capability in `SKILL.md` but says nothing about attribution. xNet's kernel — `authorDID`, per-author `parentHash` chains, Ed25519 signatures — answers "prove what the agent did" structurally, and exploration 0337 already aimed it at agents. - **Composition beats competition.** Positioned beneath every harness, xNet works with all of them. Positioned as one, it competes with all of them and composes with none — including Buzz, whose agents already carry keypairs and are a natural interop target rather than a rival. - **A harness is a permanent treadmill.** Every model release re-opens the work, and the skill-marketplace supply chain brings a ClawHavoc-class trust problem xNet has no advantage in solving. **Tradeoff:** xNet's relationship with the user is mediated by whichever agent they chose, so the accountability story has to be marketed as the reason the agent is _safe_ rather than as a product of its own. Accepted: the alternative spends the roadmap's other two pillars on a layer five funded competitors gave away in one week. **Scope note:** the provider-agnostic loop in `packages/cloud/src/ai/agent-runner.ts` stays — it is a _safety core_ (tool allow-list, injection deny point, token-cap breaker) for xNet's own server-side features, not the seed of a harness product. **Tripwire:** growing `agent-runner.ts` channels, scheduling, or a skill registry — the three things that would make it a harness. Separately, the commoditisation premise fails if the layer re-consolidates: two of the five June 2026 meta-harnesses dead and one harness holding a dominant share of agent sessions for two consecutive quarters would mean "nothing stays differentiated for a quarter" was wrong, and the substrate-only position needs re-arguing. ## ADR-30: Hub addresses resolve; no data-path routing tier **Status:** Accepted **Context:** Exploration 0423 compared xNet's managed fleet to PlanetScale's account of hiding 768 database servers behind one connection string. xNet already runs that topology — `packages/cloud/src/provisioner/sharding.ts` places 800 tenant hubs per GCP project — and pays almost none of the router tax, because its shard key is a person and people do not join to each other: no cross-shard queries, no resharding, no rebalancing. What xNet had not bought was the other half of what the router provides. The Cloud Run adapter returns `hubUrl: svc.uri`, so a client's durable configuration is a vendor hostname. A region move, a substrate swap, or a migration to self-hosting silently misconfigures every device — defeating, at the last inch, the `Provisioner` abstraction that exists so xNet is never hostage to one vendor's terms. **Decision:** Give hubs a stable name that **resolves** to an address the client dials directly. **Never** operate a proxy, gateway, or load-balanced routing tier that xNet-hosted traffic passes through. Concretely: a hub publishes a record signed by its own system identity at `/.well-known/xnet-hub-address`; the control plane may **mirror** that record but never authors one; the client resolves once, caches, and falls back to its last-known address when the resolver is unreachable. **Rationale:** - A gateway fails the Charter §6 **BATNA** test outright — a self-hoster cannot run the routing tier, so the self-hosted path becomes measurably worse than the managed one. - It fails the **Vanish** test — if xNet disappeared, every client would be pointed at a hostname resolving to nothing, mid-session, with no local fallback. A resolution record degrades instead to "connect where you connected last time", and the address travels inside the `.xnetpack` export. - The Charter already refuses this by name: _"No global chokepoint tier. We do not operate an indispensable middle to rent back later."_ A tier carrying every byte of every tenant's sync traffic is that middle, described. - Signing matters because mirroring is allowed. A mirror that could rewrite `url` would be a redirect primitive for anyone who compromised it; re-serving the hub's signature verbatim makes the mirror untrusted by construction. - The split between the signed record (**where** to connect) and the mirror's unsigned liveness hint (**whether to wait**) is deliberate: a lying mirror can make a client pause, never redirect it. **Tradeoff:** Not _quite_ one connection string — a migration costs one failed dial and a re-resolve, and the client needs a cache-invalidation story. Accepted: a one-round-trip staleness window is far cheaper than an operated tier we have promised not to build. **Tripwire:** any proposal to terminate tenant sync connections on xNet-operated infrastructure — including for fleet-wide rate limiting or observability, the usual framings — re-opens this ADR rather than shipping under it. ## ADR-31: The operational record runs on xNet; readings do not **Status:** Accepted **Context:** Exploration 0431 found the control plane has no audit log at all — `/internal/*` sits behind one flat shared secret, and `POST /internal/account/recover` clears a tenant's bound DID so the next device to present a passkey claims their hub. Anyone holding the secret could take over any tenant and leave no attributable trace. The hub, meanwhile, already has what the control plane lacks: `packages/hub/src/routes/audit.ts` pages an author's signed, hash-chained change history. **Decision:** Operator actions, incident notes and consent grants are **signed xNet nodes** authored by an operator's bound `did:key`, so the change log _is_ the audit trail. They live on a dedicated ops hub, run through the managed GCP path in **its own project**, and **never** provisioned by the fleet provisioner. Metrics and tenant state stay in Firestore. SLI buckets are hourly writes per tenant forever — exploration 0323 measured a 318k-row change log producing a multi-second cold-open stall, and a 250-change burst cliff above which every subscribed client re-renders. `TenantRecord` stays authoritative in Firestore because billing and provisioning read it on the request path. Audit is **two-tier**: a fail-closed Firestore write authorises the action, and the signed node publishes asynchronously. **Rationale:** - A signed change log is _verifiable_; an append-only database collection is merely _trusted_. With a signing identity an operator cannot repudiate an action and nobody with database access can forge one. - The ops hub must not share fate with the fleet it records. Its own project, outside the provisioner, means a fleet-provisioner bug — the realistic failure for a small team — cannot destroy the record of what operators did. - Two tiers resolve the contradiction between "audit before acting" and "the hub may be unreachable during an incident". Tier 1 never blocks on the hub, so operators can always act; the publish queue's depth is an alertable metric, so a gap between the tiers is visible rather than silent. - The record is low-volume by construction. Keeping the readings off it is what makes the ops hub something that never needs to scale. **Tradeoff:** The ops hub becomes a standing dependency of incident response, and the audit trail is eventually-consistent rather than synchronous. Accepted: the local replica and the tier-1 gate mean the degraded mode is "audit history is stale", not "you cannot see or do anything". **Tripwire:** the ops hub's change log crosses ~100k changes, or any proposal to put a per-tenant time series on it — either re-opens the record/readings split rather than shipping under this ADR. ## ADR-32: Support sees shape; content requires per-incident consent **Status:** Accepted **Context:** A managed hub is not opaque to its operator. The trusted tier provides integrity and revocation-denial but **not** confidentiality (exploration 0343), and `packages/hub/src/services/search-indexer.ts` extracts plaintext from rich text to build the FTS index. Any support console therefore draws its boundary in policy and audit, not in cryptography — and four user-facing surfaces were claiming otherwise. **Decision:** Operators see **Tier 1 — shape** without consent: counts, bytes, latencies, plan, region, version, sync backlog, job history, error class and stack. No document titles, no field values. **Tier 2 — content** requires a typed reason, the tenant's explicit grant, and a hard expiry with no renewal. Every request, grant, denial and expiry is mirrored to the tenant's own hub. **Standing consent is refused at every tier, including enterprise contracts.** Audit is graduated: aggregate fleet views are not audited, per-tenant reads are audited silently without a prompt, mutations require a typed reason. Audit entries are retained 12 months and are **not** purged when a tenant is deleted. **Rationale:** - Most real tickets — "is my sync broken", "why is my hub slow", "where did my storage go" — are answerable from shape alone. Making content expensive and visible rather than impossible is what keeps the boundary honest instead of routinely circumvented. - Titles are not a soft middle ground. A document called "Q3 layoffs" leaks exactly the thing the boundary protects. - A reason prompt on every read trains operators to type "investigating", which produces a log that looks rigorous and means nothing. Reserving the prompt for mutations keeps it meaningful. - Standing access is the mechanism by which consented access erodes into routine unlogged looking. Refusing it at contract level is the only durable form. - Audit surviving tenant deletion protects the _user_: it is the only thing preventing look-then-delete from erasing its own evidence. **Tradeoff:** Some tickets will be slower, and some enterprise negotiations will be harder. Accepted: a sovereignty promise with a standing-access carve-out is not a promise. **Tripwire:** the first support ticket that cannot be resolved at Tier 1, or the first enterprise negotiation that makes standing access a condition of sale — either re-opens the consent model rather than shipping an exception under it. ## ADR-33: Storage is sold as a flat per-GB add-on, not a plan tier **Status:** Accepted **Context:** Exploration 0435 asked whether a customer could buy 100, 500 or 1000 GB while keeping everything else about their plan unchanged. The entitlement machinery already supported it — `withStorage()` and `requiresMigration()` treat a quota change inside an isolation tier as a live flip — but two things did not. Bulk bytes were written to the hub's local filesystem, which on Cloud Run is an in-memory tmpfs capped at 32 GiB, so the catalog's existing `company` (1 TiB) and `enterprise` (5 TiB) quotas were already unbuildable. And `quotaBytes` is enforced **per user**, so a pack sold once per tenant would have been provisioned once per seat. Welding storage to the plan tier had also produced a live inversion: `family` ($15/mo) shipped 250 GiB while the strictly more expensive, more isolated `team` tier shipped 100 GiB. **Decision:** Sell storage as an **additive per-tenant add-on at a flat $0.03/GiB-month** — +100 GB $3, +500 GB $15, +1000 GB $30 — billed as a second Stripe `SubscriptionItem`, never as a new plan tier and never per seat. Three invariants make it safe: - **The pack is stored; the quota is derived.** `TenantRecord.storagePackGb` holds the purchase and every resolve recomputes `planBase + pack`. Persisting a resolved absolute would make a `personal`+500 GiB tenant upgrading to `family` silently shrink from 750 GiB to 525. - **Enforced against a per-tenant ceiling.** `tenantQuotaBytes` is a new signed field, absent meaning unlimited, so the pack is not multiplied by seat count. - **Billing leads the entitlement.** The Stripe webhook applies the flip, so held space always equals billed space. **Rationale:** - **It is the cleanest improvement charge xNet has.** Every GB sold is a GB rented from Cloudflare at $0.015 and replicated, monitored and backed up. The margin rides on an operation we run, not on access to bytes the customer would own anyway — Charter §6's improvement test, passed more squarely than by seats or AI markup. - **The BATNA is real and stays real.** Keeping data local is free and unlimited, export is free, egress is zero, and the same MIT hub self-hosts against the customer's own bucket. Consumer clouds sell 2 TB below our raw input cost; the honest answer to that comparison is bring-your-own-bucket, not a price war we would lose. - **A flat rate over a linear cost holds one margin.** 42% at every pack size — one number to defend, no volume-discount cliff, and a floor-margin test that fails if a future edit tiers the price. - **Per-seat storage was rejected twice over.** It would smuggle back the per-member meter `withSeats()` refuses for `community` (0359), and it prices out the single-seat customer with a 1 TB archive, who is the actual demand. **Tradeoff:** $0.03/GiB is roughly six times iCloud's headline rate, and the comparison will be made. Accepted: we are selling capacity inside a live, synced, exportable hub, and the customer who only wants a cheap byte locker should use one. **Tripwire:** if storage becomes a material share of revenue, the incentive to degrade local-first storage appears. The first proposal to cap on-device storage, throttle local sync, or slow export for large workspaces re-opens this decision — charging for cloud bytes is an improvement charge only for as long as **not** buying them remains fully functional. Separately, R2 Infrequent Access at $0.010/GiB would make a lower published rate viable; a sustained gap between our price and blended COGS is a reason to cut the price, not to bank the margin. ## ADR-34: A tenant is a roster of DIDs, and the hub enforces it **Status:** Accepted **Context:** xNet Cloud provisioned hubs but had no model of who was inside one. `TenantRecord` held a single `billingUserId` and a single `did`; there was no invite, roster, role or removal anywhere in the control plane. Meanwhile the hub applies a trusted-root policy only when `config.trustedDids` is set (`packages/hub/src/auth/ucan.ts`), and the control plane never set it — so a self-issued UCAN from a key generated seconds ago was accepted on a hub somebody else was paying for. `seats` had exactly two consumers in the whole repository, both render calls (exploration 0436). **Decision:** A tenant carries `members: TenantMember[]` — `{ did, role, addedAtMs, addedBy }` — and that roster is the trusted-root policy. It projects into `HUB_TRUSTED_DIDS` on every entitlement push, including inside `bindDataIdentity`, so a device that has just claimed a hub is trusted before it is told to connect. Three invariants make it safe: - **Absent means legacy, not empty.** A record written before `members` existed reports `[{ did, role: 'owner' }]`. `rosterFor()` is the only place that decides this. - **An empty policy is never written.** `checkTrustedRoots` treats absent and empty identically, so an empty value produces a hub that is wide open while looking configured. `trustedDidsEnv()` returns `undefined` rather than `''`. - **A self-hosted hub never receives the variable at all**, so its behaviour is unchanged — the anti-lock-in invariant from ADR-4 / exploration 0174. Invitation reuses the device grant rather than inventing a second handshake: the collaborator's app shows a short code, the owner approves it, and the key is minted on their own device. An invited DID joins the roster **without** rebinding the tenant. **Rationale:** - The hub's authorization model is rich and correct — grants, spaces, roles, the CRUD split. What was missing sat one layer above it: nothing decided which DIDs _are_ the tenant. Admission control and seat counting are the same missing concept wearing a security hat and a product hat. - Putting the roster in the control plane rather than in the hub's own grants keeps it readable during a support call and during a GDPR request, and lets a member join while the owner is offline. - Modelling a tenant as a WorkOS Organization was rejected: a WorkOS user is an email an IdP vouches for and a member is a key on someone's device, and conflating them would put the billing identity provider in charge of the data identity — the arrangement the non-custodial claim flow exists to avoid. `organizationId` is a pointer that decides who is _entitled_ to join; each human still binds their own key. **Tradeoff:** membership changes push a new revision, which on Cloud Run restarts the hub — invisible on scale-to-zero plans, a brief rolling drop on warm ones. Accepted: the alternative is a hub anyone on the internet can write to. **Tripwire:** the first proposal to authorize on the roster _instead of_ the hub's grant model — the roster decides admission, never permission — or the first hub shipped with `HUB_TRUSTED_DIDS` written as an empty string. Either re-opens this. ## ADR-35: Seats bill collaborators, never audience **Status:** Accepted **Context:** `team` was advertised at `$12/seat/mo` from three seats while `checkout.sessions.create` passed `quantity: 1`, so a three-seat subscription billed $12 against a margin model assuming $36. With ADR-33 the roster makes a seat countable for the first time, which is exactly when somebody will want to bill it by length (exploration 0436). **Decision:** Seats are a real Stripe `SubscriptionItem.quantity`, floored at the plan's catalog minimum and kept in sync from `customer.subscription.updated` by reading the subscription **item** rather than the checkout metadata — metadata records what was bought and never moves when a customer adds a seat later. Two limits are part of the decision, not implementation detail: - **`guest` never consumes a seat.** `seatsUsed()` counts owners and members only. A seat is capacity we provision for a collaborator; an audience member the customer brought is not one. - **Flat plans are never multiplied.** `checkoutQuantity` returns `1` for any plan with `seats === 0`, and `withSeats()` already refuses to attach a seat count to `community`. Enforcement refuses **admission** and never evicts a live session: a tenant at its seat limit cannot invite a fourth person, and the three already there keep working. **Rationale (Charter §6):** - **Improvement** — a seat is a collaborator whose devices sync against a hub we operate: real connections, real storage, real relay. - **BATNA** — self-host the MIT hub with unlimited members; `@xnetjs/entitlements` is MIT and dependency-free, so a self-hosted hub never phones home. - **Vanish** — every member's authoritative copy is on their own device. Losing the hub loses the relay, not the data. - Disconnecting someone mid-sync reads as data loss in a local-first product even when it technically is not, which is why the guard is admission-time only. **Tradeoff:** a tenant can sit at its seat limit with people waiting, and the fix is a plan change rather than an automatic overage charge. Accepted: a surprise bill is the failure mode the AI budget work already went out of its way to prevent. **Tripwire:** _the moment a seat is charged for someone the customer brought rather than someone we provision capacity for, this decision is void._ The concrete signals are a proposal to seat-meter `community`, or to count read-only/guest DIDs as seats on any plan. The roster is where that would sneak in, because once you have a member list somebody will want to bill its length. ## ADR-36: A host may refuse service; refusal never takes the work **Status:** Accepted · 2026-08-13 · exploration 0444 **Context:** Every account-suspension story in the industry follows one shape. A platform reads what a customer stored, decides against them, and in the same motion stops serving them and keeps their work. The two are separable acts — Google left a father's account closed after police cleared him; Notion terminated a workspace it had to read in order to judge; Slack cut off researchers with no window to pack; Google banned Gemini subscribers in February 2026 over a third-party OAuth integration with no appeal and no refund. Nothing technical fuses judgement to custody. They arrive together because the account is the only handle anyone built, so pulling it drags everything attached. xNet Cloud is a host. It will receive abuse reports, legal demands and sanctions lists, and sometimes the honest answer is no. A promise never to refuse anyone would be worth nothing and would be broken inside a year, so the promise has to be the other one. **Decision:** A host may refuse service. A host may never turn refusal into a claim on the customer's work. Concretely, and already true in code: every action moderation can take names **reach** — `reject`, `hide`, `quarantine`, `block-peer` (`packages/abuse/src/policy-blocks.ts`) — and none names possession. There is no `delete`, no `revoke`, no `confiscate`. An appeal resolves to `reverse` or `annotate` (`packages/abuse/src/appeals.ts`), and `reverse` is only a meaningful word because nothing was destroyed. Identity is a `did:key` the host neither issues nor can revoke (`packages/identity/src/keys.ts`); the wire format is an open signed hash-chained log another hub can pick up (`packages/sync/src/change.ts`); the client runs with no hub at all (`packages/runtime/src/sync/offline-queue.ts`). **Rationale (Charter §1, §2):** the master copy is the customer's, so a refusal withdraws a relay rather than a possession. This is what makes Exit true at the one moment it matters — the moment you are no longer welcome. An export flow that only works while you can still log in is not an exit; it is a door on an interior wall. **Tradeoff:** a hub cannot make a bad actor's data disappear from their own device, because it never had it to begin with. Refusal stops propagation and stops us relaying, and that is the whole of what a host can honestly offer. Accepted: the alternative is a capability that, once it exists, is available to every future operator, subpoena and acquirer of this company. **Tripwire:** _the moment any hub role gains an action that removes a user's data rather than restricting its reach, this decision is void._ The concrete signals are a `delete`, `purge`, `revoke` or `confiscate` member on `PolicyBlockAction`, a moderation path that writes to storage rather than to a policy list, or a retention job that treats suspension as a deletion trigger. Quota and dormancy reclamation are the honest place this sneaks in, because there the deletion has an operator's reason and no villain attached. ## ADR-37: Native desktop recovery preserves whole workspace generations **Status:** Accepted · 2026-09-29 · exploration 0466 **Context:** A desktop upgrade can change storage while the same Mac holds the only copy of a workspace. A database dump alone omits blobs, imported source files, and the desktop identity needed to use the data. **Decision:** The local `xnet-desktop-checkpoint/1` format stores a manifest and a complete copy of `xnet-data`. Its manifest names the app version, profile, identity mode, and every file's size and SHA-256 hash. Both SQLite stores must pass an integrity check. Production copies require the stored identity seed. Test copies are explicitly marked and cannot restore a daily workspace. A copy becomes available only after verification and an atomic directory rename. Restore verifies it again, stages a new generation, and records a durable journal before renaming directories. Startup finishes that journal before opening any store. The replaced generation remains available separately from the last twenty recovery copies. An installer waits for saved text, closed stores, and a verified copy before running. **Tradeoff:** These are local recovery copies, not encrypted portable backups. They exclude Chromium settings and sign-in sessions. Platform-encrypted keys still need the same Mac's key store. Losing the disk loses these copies too. The product must state this scope until separate off-device and cross-Mac recovery are proven. **Tripwire:** A persistent file moves outside `xnet-data`, a database changes its storage format, or recovery must work on a different Mac. Any of these reopens the manifest scope and restore protocol before a broader protection claim ships. ## ADR-38: Retain source evidence separately from imported social records **Status:** Accepted · 2026-09-29 · exploration 0466 **Context:** Social exports change shape. Parser fixes need the original evidence, and a file selected for preview may change before an import begins. **Decision:** Before its first node write, a desktop import retains the entire selected file under `xnet-data/import-sources//source.zip` or `source.json`. The copied bytes must match the preview fingerprint. Promotion is atomic and files are private to the local user. Reimports reuse verified bytes. Originals are never moved or deleted. The import screen states that unselected categories remain in this private source copy, though only selected categories become nodes. Native recovery includes this directory. GitHub captures use the JSON wrapper `xnet-github-stars/1`: account, capture start and finish, endpoint/media type/API version, coverage, and raw star rows. A finished paginated capture records `paginationCompleted: true` and `atomic: false`. Native repository IDs identify resources; native star times identify observed activity. Missing times stay missing. An absent repository never implies an unstar event. **Tradeoff:** Retaining raw exports costs disk space and keeps more private data than the selected graph alone. Credentials are not part of the GitHub snapshot. This format provides evidence for retries; it does not itself make a job resumable or turn local recovery into an off-device backup. **Tripwire:** A source cannot be represented as exact retained bytes, evidence needs selective deletion, or import resume requires a different source contract. Revisit custody and migration before changing the format or retention promise. ## ADR-39: Validate desktop upgrades on a separate workspace generation **Status:** Accepted · 2026-09-29 · exploration 0466 **Context:** A known older database needs an upgrade path without making the only copy the migration's test subject. Recovery also needs to run while the app stays open for days. **Decision:** The desktop supports candidate migration from the oldest tested historical schema, currently version 8, through the current schema. Before any normal store opens, validate identity and pin a verified original checkpoint. Apply every registered SQL step to a separate copy. Validate the resulting column contract, existing row counts, foreign keys, and integrity before promotion through the durable restore journal. Keep the replaced generation. Unknown, earlier, future, or unreadable formats stop in recovery without writes to their database. A promoted workspace pauses automatic network services for review. The native checkpoint manifest gains optional `sourceFingerprint`, `storageVersion`, and `pinned` fields. `appVersion` names the app that made the copy, not a promise that every app with that version can open its contents. The scheduler checks once a minute, copying changed data when fifteen minutes overdue. This supersedes ADR-37's flat twenty-copy retention: keep one point per fifteen-minute bucket for a day, per day for a week, and per week for four weeks, plus the latest two. Pinned points and preserved originals are not pruned automatically. Pruning still requires a newly verified point, and copy failures remain visible in the app. **Tradeoff:** Backups can briefly delay editing, pinned originals consume space, and only tested historical versions migrate automatically. Native copies still exclude browser settings and need the same Mac key store. This decision adds no portable or off-device guarantee. **Tripwire:** A migration changes existing row contents, the oldest supported version changes, or checkpoint time/storage use disrupts daily work. Add the relevant historical fixture and data-preservation proof before widening support or changing the displayed recovery policy. ## ADR-40: Portable desktop recovery carries encrypted identity and source bytes **Status:** Accepted · 2026-09-29 · exploration 0466 **Context:** Copying native recovery files to another disk does not make their Keychain-encrypted identity usable on another Mac. Losing the original machine must not make the only surviving backup useless. **Decision:** `xnet-desktop-portable/1` is a directory containing a small public header, an encrypted manifest, and encrypted file chunks. The password derives a 32-byte key with scrypt (N=131072, r=8, p=1, random 32-byte salt). Each object uses native AES-256-GCM with a fresh random 12-byte nonce, a 16-byte tag, and the format identifier as authenticated data. File chunks are at most four MiB. The authenticated manifest binds ordered ciphertext hashes to each original path, size, and plaintext SHA-256. It also carries the actual desktop signing seed and any stored recovery mnemonic, encrypted under the recovery password. The public header contains no filenames, identity, or password. Export starts from a verified native checkpoint and verifies the encrypted manifest and every object before atomically publishing the folder. Restore extracts only into a new private directory, verifies files and databases, and rewraps the same seed using the destination key store. A fresh native checkpoint records those changed key-file bytes. Only then may the existing restore journal replace the workspace, preserving its prior generation and pausing networking. The desktop currently accepts portable restores for the current storage version; an incompatible backup fails before changing live files. **Tradeoff:** Password loss is unrecoverable. This format has no password escrow, compression, or incremental deduplication. Browser settings and sign-in sessions remain excluded. The app verifies written bytes but cannot infer that a chosen folder is off-device. It must state that distinction. Tests with different mock key stores and a real desktop round trip do not prove a second physical Mac or signed installer continuity. **Tripwire:** A cryptographic parameter changes, a required key lives outside this manifest, a supported backup needs migration during restore, or large exports block normal desktop use. Reopen the format and recovery evidence before changing the reader or broadening the protection claim. ## ADR-41: Resume archive imports from retained evidence and acknowledged batches **Status:** Accepted · 2026-09-29 · exploration 0466 **Context:** An in-memory progress bar cannot continue an import after a restart. Retaining an archive alone does not record which categories were reviewed or which writes completed. **Decision:** Desktop imports retain a version-1 journal under `xnet-data/import-jobs`. It records the reviewed stage, adapter version, source hash and extension, original import time, source-record policy, author DID, and acknowledged progress. Private signing keys are never written to this journal. Each journal update uses a private temporary file, fsync, and atomic rename. The cursor advances only after the database acknowledges the batch. An interrupted running job appears paused after startup. Resume requires the same workspace identity and importer version, verifies the retained source, and replays its stable stream through the last saved cursor. Previously acknowledged batches are skipped. A crash after a database commit but before the journal update may replay one batch using deterministic node IDs. This provides at-least-once writes, not an exactly-once claim. A changed importer requires fresh review. Native and encrypted recovery include the journal and source together; source paths are resolved against the restored workspace, not the original machine. **Tradeoff:** Resume reparses the earlier source records to reconstruct its position. A damaged journal fails visibly rather than appearing as an empty job list. Old adapter versions are not bundled indefinitely, and progress from older in-memory-only imports cannot be recovered automatically. **Tripwire:** An importer no longer emits a stable stream for identical bytes, an import gains non-idempotent effects, or its batch boundary changes. Version the journal or importer and prove replay safety before accepting old cursors. ## ADR-42: Desktop enrichment keeps full evidence in a recoverable local store **Status:** Accepted · 2026-09-29 · exploration 0466 **Context:** Social card fields have size limits. Putting a video description or transcript only in those fields silently loses searchable text. A browser queue also cannot reliably survive a desktop restart or carry work into a recovery copy. **Decision:** `xnet-data/library.db`, SQLite user version 1, stores full metadata, caption cues, provider evidence, FTS search rows, and durable capability jobs. Job identity includes resource ID, capability, provider version, and language. Metadata, thumbnails, transcripts, and indexing have separate outcomes. Missing fields and failed discovery stay explicit. Interrupted work returns to the queue; provider backoff and pause state survive restart. Fetching starts only after the user enables enrichment and remains disabled during recovery review. Source resources stay in NodeStore. Bounded SocialEnrichment card projections and versioned transcript segments link back to those resources; they do not replace full evidence. Thumbnail bytes live in the existing managed blob store. The Library reads cached images, full descriptions, and caption matches offline. List responses exclude raw evidence and full transcripts; details load on demand. Native checkpoints freeze enrichment and include the library database with its committed WAL content. Portable recovery includes it through the same manifest. Library compatibility is checked before any startup migration or writable open. A damaged or unknown library format requires recovery rather than reconstruction. **Tradeoff:** The full-text store is device-local and is not yet synced between peers. Caption retrieval currently uses the explicitly tested local yt-dlp version; login-limited sources remain blocked. This decision does not claim local ASR, whole-corpus enrichment, or packaged helper installation. Full source evidence costs disk space, and schema upgrades need copied fixtures before support expands. **Tripwire:** Another device must receive full enriched text, provider evidence outgrows practical backups, or a library schema/provider upgrade invalidates stored work. Revisit the storage boundary and migration proof before changing it. ## ADR-43: Captured notes are private Pages with explicit source relations **Status:** Accepted · 2026-09-29 · exploration 0466 **Context:** Saving a URL with an observation should create something editable. Importers and metadata refreshes must not own or replace the user's writing. A crash between creating a Page and saving its document must leave a recoverable intent rather than an unexplained empty note. **Decision:** Page gains the optional `sourceResources` relation. Capture reuses a matching social resource and creates a separate private Page with its own Yjs text, original URL, optional excerpt, and source relation. A second note is an explicit new capture. The relation grants no access to either endpoint and does not publish the resource or Page. The desktop writes a version-1 capture intent to `library.db` before creating nodes. Its stable request ID binds the exact input, author DID, resource ID, Page ID, and initial document bytes. Success requires acknowledged node and text writes plus local search indexing. Repeating a request resumes that intent; it never overwrites an existing document. Startup resumes incomplete intents under the workspace write barrier. The journal is included in native and portable recovery and contains no signing key. The shared workbench hosts the form through an optional host capability. Desktop provides the native save and URL lookup. A failed attempt keeps the original payload fixed for retry; successful saves unlock the normal Page editor. Desktop capture uses Command/Ctrl+Shift+L, reads clipboard text only when invoked, and returns to the prior foreground application on macOS when capture finishes. **Tradeoff:** Capture spans recoverable steps rather than one cross-database transaction. The intent retains a copy of the original writing. Unsaved form text lives in the browser profile until Save creates a native intent; it is not part of the portable-backup claim. Other hosts may implement the same optional capability later. Source relations must be reviewed by the separate publishing path before a guide is exported. **Tripwire:** Capture starts editing an existing Page, source relations imply sharing permissions, or a new document format changes replay. Revisit request identity, privacy checks, and interrupted-save tests before expanding the path. ## ADR-44: Observe committed local writes without applying them twice **Status:** Accepted · 2026-09-29 · exploration 0466 **Context:** The desktop utility process imports and enriches records while the renderer keeps a NodeStore open over the same database. The renderer previously ignored native change notifications and kept its startup change clock. A later title edit could receive an older timestamp and lose to an already-saved import. **Decision:** Every local change allocation advances from the persisted Lamport time as well as the instance's current time. An unreadable stored clock fails the write. `NodeStore.refreshPersistedNodes(ids)` reads committed records through the store's read boundary and notifies subscribers without writing them again. It rejects missing or unreadable records. Refresh events are marked remote so sync listeners do not rebroadcast them. Native notifications carry only IDs into this API; supplied notification properties are never used as authoritative content. Desktop subscribes to its existing native change channel, refreshes in bounded groups, and retains failed groups for another notification or the end of a write barrier. Refresh errors remain visible. A notification is not a save receipt; the native write acknowledgement remains the persistence boundary. **Tradeoff:** Clock allocation gains a storage read. This prevents sequential writers from using stale clocks; it does not serialize overlapping writes from two NodeStore instances. Native mutation barriers and stronger concurrent-writer validation remain separate work. The API requires all requested records to be readable, and is for stores sharing the same underlying committed state. **Tripwire:** Concurrent native and renderer mutations overwrite one another, clock reads measurably harm typing or imports, or a remote transport starts using this API. Revisit single-writer ownership or atomic allocation before widening the guarantee. ## ADR-45: Recover desktop settings through an encrypted logical snapshot **Status:** Accepted · 2026-09-30 · exploration 0466 **Context:** Native workspace copies omitted browser-held preferences, provider keys, and an unfinished capture draft. Copying Chromium directories would bind recovery to browser internals and device session keys. **Decision:** `desktop-settings.json` stores a version-1, bounded, explicit map of desktop setting names to strings or null. Main encrypts it with `safeStorage` and acknowledges a private atomic write only after file and directory fsync. The renderer save barrier includes this snapshot. Missing settings are distinct from unreadable settings, and unreadable prior copies cannot be overwritten. `xnet-desktop-portable/2` carries the logical snapshot inside its authenticated, password-encrypted manifest and rewraps the native file for the destination key store. The manifest and checkpoint inventory must agree about its presence. The reader still accepts version 1 with its original coverage. Older readers reject version 2. This extends the coverage limits recorded in ADR-40 and ADR-43; their original format and capture contracts remain historical decisions. Restore applies the map before importing settings consumers. A unique restore generation and browser receipt prevent normal restarts from replaying an older snapshot over newer edits. A failed application retries before app startup. Device-bound passkeys, session wrapping keys, cookies, test flags, temporary OAuth verifiers, and bridge authorization tokens are excluded. Desktop signing identity still comes from the native seed. **Tradeoff:** The explicit list needs maintenance as desktop settings grow. The copy protects values at a completed checkpoint, not every subsequent draft edit. Existing browser APIs still hold their normal values in Chromium; this decision encrypts the recovery copy rather than moving all live credentials into a vault. **Tripwire:** A new non-reconstructible desktop key or setting appears outside the list, an identity flow starts using IndexedDB as its authoritative store, or restore receipts can replay stale settings over later edits. Extend the versioned contract and failure tests before broadening the recovery claim. ## ADR-46: Drain workspace watches before disposing their storage **Status:** Accepted · 2026-09-30 · exploration 0466 verification **Context:** Closing a workspace watch stopped future timers but left its current scan writing review files. The CLI could dispose storage while an asynchronous scan callback was still applying edits. Full-suite cleanup exposed this race. **Decision:** Keep the synchronous watch handle's `close()` contract and add `AiWorkspaceWatcher.waitForIdle()`. Callers close their handles, then await this method before disposing storage or removing the checkout. The drain includes both scans and their asynchronous callbacks. Each watch serializes scans. Background failures stop that watch, log the failure, and remain available as an `AggregateError` from the drain. The CLI follows this order on Ctrl-C and exits with failure when draining or disposal fails. **Tradeoff:** Closing alone does not wait. A callback that never settles can hold shutdown open; forcing process exit would abandon work and cannot claim a clean shutdown. The method covers watch-dispatched work, not independent explicit scans. **Tripwire:** A caller needs bounded cancellation, parallel scans become necessary, or any consumer disposes storage before awaiting the drain. Revisit ownership and cancellation semantics before changing the shutdown guarantee. ## ADR-47: Pair spatial Library viewers with an ephemeral read capability **Status:** Accepted · 2026-10-06 · exploration 0468 **Context:** A headset browser cannot use Electron's preload. Exposing the general local API or development server would give the viewer capabilities it does not need. **Decision:** The owner starts a separate HTTPS listener from the desktop graph, explicitly choosing the visible saved links and a certificate already trusted by both devices. Only private-network clients are accepted. The listener serves a compiled browser viewer and a frozen, revision-matched graph/layout projection. A random 256-bit invitation in the URL fragment can be redeemed once within five minutes for an in-memory bearer capability. The capability expires one hour after creation or immediately when the owner revokes access, the app exits, or the listener stops. Credentials are never logged or persisted by the viewer. The only data routes are snapshot, bounded search, selected-resource details and thumbnails resolved through those resources. No arbitrary blob IDs, conversations, personal notes, identity material, SQL, writes or enrichment jobs are exposed. Details are a bounded projection; longer saved source text or transcript text is requested explicitly and limited to 100,000 characters. Reads check revocation again after asynchronous storage access. Exact host and origin checks, no CORS, no-store responses and a same-origin content policy constrain browser access. **Tradeoff:** This is an experimental, session-local transport, not an independent synced Library or a supported durable public protocol. Users must provision trust and address resolution on both devices. A copied capability authorizes its holder until expiry or revocation; it is not a hardware-bound device credential. Revocation stops future reads but cannot erase content already delivered to a device. **Tripwire:** We need internet access, persistent pairing, offline private content, multiple readers, or native clients consuming a stable protocol. Revisit the capability and ownership design before extending this experimental transport. --- ## Package Graph ## Dependency graph The workspace holds **30 packages**. The diagram shows the core chain and the major feature packages; lower packages cannot import from higher ones: ```mermaid graph BT crypto["@xnetjs/crypto"] identity["@xnetjs/identity"] storage["@xnetjs/storage"] sync["@xnetjs/sync"] data["@xnetjs/data"] runtime["@xnetjs/runtime"] react["@xnetjs/react"] network["@xnetjs/network"] plugins["@xnetjs/plugins"] editor["@xnetjs/editor"] canvas["@xnetjs/canvas"] devtools["@xnetjs/devtools"] ui["@xnetjs/ui"] query["@xnetjs/query"] views["@xnetjs/views"] comms["@xnetjs/comms"] charts["@xnetjs/charts"] dashboard["@xnetjs/dashboard"] cli["@xnetjs/cli"] hub["@xnetjs/hub"] identity --> crypto storage --> identity sync --> crypto sync --> identity data --> sync data --> crypto network --> sync network --> crypto runtime --> data runtime --> sync runtime --> storage react --> runtime plugins --> data editor --> |Yjs| sync canvas --> data devtools --> react query --> data query --> storage views --> react views --> ui comms --> data comms --> crypto dashboard --> react dashboard --> charts dashboard --> plugins cli --> plugins cli --> data hub --> sync hub --> data style crypto fill:#4f46e5,color:#fff,stroke:#6366f1 style identity fill:#4f46e5,color:#fff,stroke:#6366f1 style storage fill:#4f46e5,color:#fff,stroke:#6366f1 style sync fill:#4f46e5,color:#fff,stroke:#6366f1 style data fill:#4f46e5,color:#fff,stroke:#6366f1 style runtime fill:#4f46e5,color:#fff,stroke:#6366f1 style react fill:#4f46e5,color:#fff,stroke:#6366f1 style network fill:#6366f1,color:#fff,stroke:#818cf8 style plugins fill:#6366f1,color:#fff,stroke:#818cf8 style editor fill:#6366f1,color:#fff,stroke:#818cf8 style canvas fill:#6366f1,color:#fff,stroke:#818cf8 style devtools fill:#6366f1,color:#fff,stroke:#818cf8 style ui fill:#818cf8,color:#fff,stroke:#a5b4fc style query fill:#818cf8,color:#fff,stroke:#a5b4fc style views fill:#818cf8,color:#fff,stroke:#a5b4fc style comms fill:#818cf8,color:#fff,stroke:#a5b4fc style charts fill:#818cf8,color:#fff,stroke:#a5b4fc style dashboard fill:#818cf8,color:#fff,stroke:#a5b4fc style cli fill:#818cf8,color:#fff,stroke:#a5b4fc style hub fill:#818cf8,color:#fff,stroke:#a5b4fc ``` ## Package details ### @xnetjs/crypto **Dependencies:** `@noble/hashes`, `@noble/curves`, `@noble/ciphers` The foundation. Provides BLAKE3 hashing, Ed25519 signing, XChaCha20-Poly1305 encryption, X25519 key exchange, and encoding utilities. No xNet dependencies. ### @xnetjs/identity **Dependencies:** `@xnetjs/crypto` DID:key creation and parsing, Ed25519/X25519 key bundle management, UCAN token creation and verification, passkey storage. ### @xnetjs/storage **Dependencies:** `@xnetjs/identity` SQLite adapter for persisting Y.Doc state, node properties, offline queue entries, and registry data across web (OPFS), desktop, and mobile. ### @xnetjs/sync **Dependencies:** `@xnetjs/crypto`, `@xnetjs/identity` Core sync primitives: Lamport clocks, `Change` type, hash chains, Yjs security layer (signed envelopes, rate limiting, peer scoring, clientID attestation, update batching, integrity checking). ### @xnetjs/data **Dependencies:** `@xnetjs/sync`, `@xnetjs/crypto` Schema system (`defineSchema`, 15 property types), NodeStore (CRUD + change tracking), type inference (`FlatNode`, `InferCreateProps`), validation and coercion. ### @xnetjs/runtime **Dependencies:** `@xnetjs/data`, `@xnetjs/sync`, `@xnetjs/storage` The framework-agnostic client. `createXNetClient()` assembles the store, MetaBridge, SyncManager, NodePool, Registry, OfflineQueue, and the multi-hub ConnectionManager; `liveQuery()` exposes the universal `{ getSnapshot, subscribe }` store contract. No React dependency — it powers React, other frameworks, CLIs, and servers alike. See [ADR-14](/docs/architecture/decisions/#adr-14-framework-agnostic-runtime--react-is-a-thin-binding). ### @xnetjs/react **Dependencies:** `@xnetjs/runtime`, `react` The thin React binding: `useQuery`, `useMutate`, `useNode`, `useIdentity`, `XNetProvider`, and the plugin hooks. The sync engine itself lives in `@xnetjs/runtime`; this package re-exports it and adapts it to React via `useSyncExternalStore`. ### @xnetjs/network **Dependencies:** `@xnetjs/sync`, `@xnetjs/crypto` libp2p node setup, WebRTC and WebSocket transport, connection gating, peer scoring (GossipSub-inspired), auto-blocking, rate limiting at the connection level. ### @xnetjs/plugins **Dependencies:** `@xnetjs/data`, `acorn` Plugin system: extension manifest, registry, context, 9 contribution types, middleware chain, script sandbox (AST validation, frozen context, timeout), AI script generation, services (ProcessManager, ServiceClient), integrations (LocalAPI, MCPServer, WebhookEmitter), shortcut manager. ### @xnetjs/editor **Dependencies:** `@tiptap/core`, Yjs TipTap editor wrapper with Yjs collaboration, custom extensions (Mermaid, etc.), slash command support. ### @xnetjs/canvas **Dependencies:** `@xnetjs/data` Infinite canvas with spatial indexing (R-tree), viewport management, zoom/pan, node positioning. ### @xnetjs/devtools **Dependencies:** `@xnetjs/react` 10 debug panels: Nodes, Changes, Sync, Yjs, Queries, Telemetry, Schemas, Seed, History, and AuthZ. See the [DevTools guide](/docs/guides/devtools/). ### @xnetjs/ui Shared design system: the monochrome token ramp (`surface`/`ink`/`hairline`), primitives, the shared task editor, and the unified drag payload. No xNet runtime dependencies. ### @xnetjs/query **Dependencies:** `@xnetjs/data`, `@xnetjs/storage` Query AST, saved-view descriptors, full-text search index, and the reactive saved-view runner that powers tables, boards, and widgets. ### @xnetjs/views **Dependencies:** `@xnetjs/react`, `@xnetjs/ui` Database view components: table, board, list, calendar, gallery, timeline — with compact modes for dashboards. ### @xnetjs/comms **Dependencies:** `@xnetjs/data`, `@xnetjs/crypto` Chat, presence, and calls: room manager (typed awareness sessions), chat service (signed message nodes, deterministic DM ids), the local notification engine, and the full-mesh WebRTC call manager. See [Chat, Presence & Calls](/docs/guides/chat-and-calls/). ### @xnetjs/dashboard & @xnetjs/charts **Dependencies:** `@xnetjs/react`, `@xnetjs/plugins`, `@xnetjs/charts` Widget contract, registry, grid runtime, and sandbox tiers; charts wraps ECharts behind a library-agnostic spec. See [Dashboards & Widgets](/docs/guides/dashboards/). ### @xnetjs/cli **Dependencies:** `@xnetjs/plugins`, `@xnetjs/data` The `xnet` command-line tool: scoped workspace checkouts, search/query, commit/daemon, sandboxed scripts, SKILL.md. See [Agent Interfaces](/docs/guides/agent-interfaces/). ### @xnetjs/hub **Dependencies:** `@xnetjs/sync`, `@xnetjs/data` The optional always-on node: relay, encrypted backup, full-text search, call signaling, UCAN-authorized actions. See the [Hub guide](/docs/guides/hub/). ### Supporting packages `core` (shared primitives), `sqlite` & `data-bridge` (storage adapters), `canvas-core`, `editor`/`canvas` internals, `formula`, `history` (undo/redo), `social` (graph lenses & importers), `telemetry`, `abuse` (rate limiting & peer scoring), `vectors`, `sdk`. ## The rule **Lower packages cannot import from higher ones.** This ensures: - `@xnetjs/crypto` can be used standalone for any cryptographic operation - `@xnetjs/sync` can be used without React for server-side or CLI tools - `@xnetjs/data` can be used without a UI framework - Each package is independently testable ## Applications ``` apps/web — The flagship workbench PWA (documents, databases, canvas, tasks, dashboards, chat & calls) apps/electron — Desktop wrapper adding background sync, ProcessManager, LocalAPI, and the MCP server (@xnetjs/plugins/node) apps/expo — Mobile (in development) ``` The web app is the primary surface and uses the browser-safe subset; Electron adds the Node-only service layer on top. --- ## Getting Started ## Prerequisites - **Node.js** 18+ (LTS recommended) - **pnpm** 9+ (`npm install -g pnpm`) - **Git** ## Clone and install ```bash git clone https://github.com/crs48/xNet.git cd xNet pnpm install ``` ## Build all packages ```bash pnpm build ``` This builds all packages in dependency order (crypto → identity → storage → sync → data → react → etc.). ## Run tests ```bash # All tests (~4,700) pnpm test # Single package pnpm --filter @xnetjs/sync test pnpm --filter @xnetjs/data test # Single file pnpm --filter @xnetjs/sync vitest run src/clock.test.ts # Watch mode pnpm --filter @xnetjs/sync test:watch ``` ## Type checking ```bash pnpm typecheck ``` ## Linting ```bash pnpm lint ``` ## Run the Electron app ```bash cd apps/electron && pnpm dev ``` This starts the Vite dev server, signaling server, and Electron app. The app is available at `http://localhost:5177` for debugging. ### Two-instance sync testing ```bash cd apps/electron && pnpm dev:both ``` Launches two Electron windows connected to the same signaling server for testing real-time sync. ## Project structure ``` packages/ # Core libraries (@xnetjs/*) crypto/ # BLAKE3, Ed25519, XChaCha20 identity/ # DID:key, UCAN tokens storage/ # SQLite adapter sync/ # Lamport clocks, Change, Yjs security data/ # Schema system, NodeStore, 15 property types react/ # useQuery, useMutate, useNode hooks plugins/ # 4-layer plugin system canvas/ # Infinite canvas with spatial indexing editor/ # TipTap rich text editor network/ # libp2p, WebRTC, peer security devtools/ # Debug panels (7 panels) apps/ electron/ # Desktop app (full features) web/ # PWA (pages only) site/ # Documentation site (Astro + Starlight) ``` ## Workflow 1. Create a feature branch from `main` 2. Make changes in the relevant package(s) 3. Run tests for affected packages 4. Run `pnpm typecheck` and `pnpm lint` 5. Commit with a descriptive message following conventional commits 6. Open a pull request If your change alters an **architectural invariant** — a protocol/wire contract, a package boundary, a security or trust rule, a storage or sync decision — add or supersede a record on the [Architecture Decisions](/docs/architecture/decisions/) page in the same PR. Decisions are usually worked out first as an exploration in `docs/explorations/`; the ADR page is the distilled, immutable outcome. ## Useful commands | Command | Description | | ------------------------------------- | ------------------------ | | `pnpm install` | Install all dependencies | | `pnpm build` | Build all packages | | `pnpm test` | Run all tests | | `pnpm typecheck` | Type check all packages | | `pnpm lint` | Lint all packages | | `pnpm --filter @xnetjs/sync test` | Test a single package | | `pnpm --filter @xnetjs/sync test:watch` | Watch mode for a package | --- ## Code Style ## Import ordering Imports follow a strict order, separated by blank lines: ```ts // 1. Type-only imports // 2. External packages // 3. Internal packages // 4. Local relative imports ``` ## Naming conventions | Category | Convention | Example | | ----------------- | --------------------- | -------------------------------- | | Functions | camelCase, verb-first | `createNode`, `verifySignature` | | Types | PascalCase | `NodeStore`, `SyncStatus` | | Constants | SCREAMING_SNAKE | `MAX_UPDATE_SIZE`, `DEFAULT_TTL` | | Classes | PascalCase | `SpatialIndex`, `Viewport` | | Type parameters | Single uppercase | `T`, `P` | | Unused parameters | Prefix with `_` | `_event`, `_unused` | ## TypeScript - **Strict mode enabled** — no implicit `any`, strict null checks - **Prefer `type` over `interface`** for object shapes - **Explicit return types** on exported functions - **Template literal types** for branded strings: `` `xnet://${string}/` `` - **No `any`** without justification — use `unknown` instead ## Exports - **Named exports only** — no default exports - **Barrel files** (`index.ts`) re-export from internal modules - **Export types inline**: `export { fn, type FnResult }` - **Factory functions** alongside classes: `createFoo()` next to `class Foo` ## Comments ### File-level JSDoc ```ts /** * @xnetjs/sync - Unified sync primitives for xNet */ ``` ### Section dividers ```ts // ─── Section Name ──────────────────────────────────────── ``` ### Function docs ```ts /** * Create a signed envelope for a Yjs update. * @example * const envelope = signYjsUpdate(update, did, key, clientId) */ ``` ## Error handling - Return `{ valid: boolean, errors: [] }` for validation — don't throw - Try-catch with type narrowing: `err instanceof Error ? err : new Error(String(err))` - Early returns for edge cases - Boolean returns for simple success/failure ## React patterns - Return typed objects from hooks (not tuples) - Use refs for values accessed in callbacks (avoid stale closures) - Always return cleanup functions from `useEffect` - Debug logging via localStorage: `localStorage.getItem('xnet:sync:debug')` - Prefer Tailwind over custom CSS --- ## Testing Guide ## Running tests ```bash # All ~4,700 tests pnpm test # Single package pnpm --filter @xnetjs/sync test pnpm --filter @xnetjs/data test pnpm --filter @xnetjs/canvas test # Single file pnpm --filter @xnetjs/sync vitest run src/clock.test.ts # Pattern match pnpm --filter @xnetjs/data vitest run -t "NodeStore" # Watch mode pnpm --filter @xnetjs/sync test:watch ``` ## Test structure All tests use Vitest with the Arrange-Act-Assert pattern: ```ts describe('ModuleName', () => { describe('functionName', () => { it('should do expected behavior', () => { // Arrange const input = createTestData() // Act const result = functionName(input) // Assert expect(result).toBe(expected) }) }) }) ``` ## What to test **Do test:** - Core packages (`crypto`, `identity`, `sync`, `data`, `plugins`) - Pure functions and algorithms - Edge cases and error paths - Immutability guarantees **Don't test:** - UI components (manual testing only) - Electron app integration - Styling/layout ## Common patterns ### Generating test keys ```ts const { publicKey, privateKey } = generateSigningKeyPair() const { identity, privateKey: signingKey } = generateIdentity() ``` ### Test DIDs ```ts // Quick typed DID for tests const testDID = 'did:key:z6MkTest123' as DID // Or generate a real one const { identity } = generateIdentity() ``` ### Suppressing console output ```ts vi.spyOn(console, 'error').mockImplementation(() => {}) vi.spyOn(console, 'warn').mockImplementation(() => {}) ``` ### Immutability checks ```ts it('should not mutate the input', () => { const original = createLamportClock('did:key:alice') const time = original.time tick(original) expect(original.time).toBe(time) }) ``` ## Where tests live Test files are colocated with source code: ``` packages/sync/src/ clock.ts clock.test.ts change.ts change.test.ts ``` Or in a `__tests__` directory for packages with many test files: ``` packages/plugins/src/ __tests__/ registry.test.ts middleware.test.ts sandbox.test.ts ``` ## Coverage Tests cover core algorithms and security-critical paths. Each core package has tests for its primary exports. When adding new functionality to a core package, include tests that verify the expected behavior and edge cases. ---