@epicenter/sync 0.1.0 → 0.3.0

package/README.md

@@ -1,6 +1,6 @@
 # @epicenter/sync
 
-`@epicenter/sync` is the wire-format package for Epicenter sync. It owns the binary framing for Yjs sync, awareness, sync-status, and peer-to-peer RPC messages so the transport layer can stay dumb. `@epicenter/workspace` and `apps/api` use it when they need to turn a `Y.Doc` change into bytes—or turn bytes back into something the app can reason about.
+`@epicenter/sync` is the wire-format package for Epicenter sync. It owns the binary framing for Yjs sync, awareness, sync-status, and peer-to-peer RPC messages so the transport layer can stay dumb. `@epicenter/workspace` and `apps/api` use it when they need to turn a `Y.Doc` change into bytes. Or turn bytes back into something the app can reason about.
 
 ## Installation
 
@@ -63,10 +63,9 @@ The design shows up in a few places:
 
 - `encodeSyncStep1`, `encodeSyncStep2`, and `encodeSyncUpdate` only deal with Yjs payloads.
 - `encodeSyncRequest` and `decodeSyncRequest` collapse the WebSocket handshake into a binary HTTP request/response format.
-- `encodeSyncStatus` uses an echoed version counter for save-state UX; the server can relay the payload unchanged.
 - RPC framing is separate from RPC behavior. The package defines request/response bytes and shared error variants, not the transport policy around retries or timeouts.
 
-If you want lifecycle helpers for a WebSocket server, this package is the protocol layer under them—not the server itself.
+If you want lifecycle helpers for a WebSocket server, this package is the protocol layer under them. Not the server itself.
 
 ## API overview
 
@@ -76,7 +75,7 @@ Main exports from `src/index.ts`:
 - Sync encode/decode: `encodeSyncStep1`, `encodeSyncStep2`, `encodeSyncUpdate`, `decodeSyncMessage`, `handleSyncPayload`
 - Awareness helpers: `encodeAwareness`, `encodeAwarenessStates`, `encodeQueryAwareness`
 - HTTP sync helpers: `encodeSyncRequest`, `decodeSyncRequest`
-- Save-status helpers: `encodeSyncStatus`, `decodeSyncStatus`, `stateVectorsEqual`
+- State helpers: `stateVectorsEqual`
 - RPC helpers: `encodeRpcRequest`, `encodeRpcResponse`, `decodeRpcMessage`, `decodeRpcPayload`
 - RPC types and guards: `DecodedRpcMessage`, `RpcError`, `isRpcError`
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@epicenter/sync",
-	"version": "0.1.0",
+	"version": "0.3.0",
 	"description": "Sync protocol for Epicenter workspaces. Yjs-based encoding, WebSocket transport, and broadcast channel sync.",
 	"keywords": [
 		"local-first",
@@ -18,26 +18,24 @@
 		"directory": "packages/sync"
 	},
 	"homepage": "https://epicenter.so",
-	"main": "./src/index.ts",
-	"types": "./src/index.ts",
 	"exports": {
 		".": "./src/index.ts"
 	},
-	"license": "AGPL-3.0",
+	"license": "MIT",
 	"scripts": {
 		"typecheck": "tsc --noEmit"
 	},
 	"dependencies": {
-		"lib0": "catalog:",
-		"wellcrafted": "catalog:",
-		"y-protocols": "catalog:"
+		"@epicenter/identity": "0.1.0",
+		"lib0": "^0.2.117",
+		"wellcrafted": "^0.42.0"
 	},
 	"peerDependencies": {
-		"yjs": "catalog:"
+		"yjs": "^13.6.29"
 	},
 	"devDependencies": {
-		"@types/bun": "catalog:",
-		"typescript": "catalog:",
-		"yjs": "catalog:"
+		"@types/bun": "latest",
+		"typescript": "^5.9.3",
+		"yjs": "^13.6.29"
 	}
 }

package/src/auth-subprotocol.test.ts

@@ -0,0 +1,26 @@
+/**
+ * WebSocket Auth Subprotocol Tests
+ *
+ * Verifies the shared bearer subprotocol helpers used by auth clients and API
+ * middleware.
+ *
+ * Key behaviors:
+ * - Bearer prefix comes from the shared constants package
+ * - Subprotocol headers parse into their comma-separated token list
+ */
+
+import { expect, test } from 'bun:test';
+import {
+	BEARER_SUBPROTOCOL_PREFIX,
+	MAIN_SUBPROTOCOL,
+	parseSubprotocols,
+} from './auth-subprotocol.js';
+
+test('parseSubprotocols splits a comma-separated subprotocol header', () => {
+	const header = `${MAIN_SUBPROTOCOL}, ${BEARER_SUBPROTOCOL_PREFIX}token-1`;
+
+	expect(parseSubprotocols(header)).toEqual([
+		MAIN_SUBPROTOCOL,
+		`${BEARER_SUBPROTOCOL_PREFIX}token-1`,
+	]);
+});

package/src/auth-subprotocol.ts

@@ -0,0 +1,37 @@
+/**
+ * WebSocket subprotocol auth: shared client/server constants.
+ *
+ * Auth tokens travel inside the `Sec-WebSocket-Protocol` handshake header
+ * as `bearer.<token>`, not in the URL's query string. The real threat is
+ * server-side access logs (Cloudflare, Hono middleware, downstream APMs
+ * like Sentry/Datadog): full URLs including query strings are captured by
+ * default, so a `?token=` scheme leaks long-lived session tokens into any
+ * system with log access. Subprotocol headers aren't captured by default
+ * on those systems. The server extracts and consumes the bearer entry on
+ * upgrade; only the main protocol name (`epicenter`) is echoed back on
+ * the 101 response, so the token never round-trips.
+ *
+ * The `.` separator is required by RFC compliance: `Sec-WebSocket-Protocol`
+ * values are RFC 7230 `token` productions, where `:` is not a valid `tchar`
+ * but `.` is. Prior art for `<scheme>.<token>`: Phoenix channels
+ * (`phx_bearer.<token>`), Supabase Realtime, and Kubernetes
+ * (`base64url.bearer.authorization.k8s.io.<token>`).
+ */
+
+/** Primary subprotocol name every Epicenter client negotiates. */
+export const MAIN_SUBPROTOCOL = 'epicenter';
+
+/** Prefix for OAuth bearer tokens carried through WebSocket subprotocols. */
+export const BEARER_SUBPROTOCOL_PREFIX = 'bearer.';
+
+/**
+ * Parse a `Sec-WebSocket-Protocol` header value into its list of tokens.
+ *
+ * RFC 6455 specifies the value as a comma-separated list of RFC 7230 tokens,
+ * with optional whitespace after commas. Returns an empty list if the header
+ * is absent.
+ */
+export function parseSubprotocols(header: string | null): string[] {
+	if (!header) return [];
+	return header.split(',').map((s) => s.trim());
+}

package/src/index.ts

@@ -1,39 +1,34 @@
 /**
- * @epicenter/sync — Yjs Sync Protocol Primitives
+ * @epicenter/sync: Yjs Sync Protocol Primitives
  *
- * Encode/decode functions for the y-websocket wire protocol, plus
- * RPC error variants shared by both server and client.
+ * Encode/decode functions for the sync wire protocol.
  *
- * For server-side WebSocket lifecycle handlers, import from
- * `@epicenter/sync/server` instead.
+ * The binary WebSocket channel carries a single message family: Yjs
+ * document sync. A binary frame is a sync frame, with no top-level
+ * message-type discriminator. Presence and dispatch ride text frames.
  */
 
+// WebSocket subprotocol auth (shared client/server constants + helpers)
+export {
+	BEARER_SUBPROTOCOL_PREFIX,
+	MAIN_SUBPROTOCOL,
+	parseSubprotocols,
+} from './auth-subprotocol';
+// Transport origin sentinels (shared across all sync layers)
+export {
+	BC_ORIGIN,
+	isTransportOrigin,
+	SYNC_ORIGIN,
+} from './origins';
 // Protocol (encode/decode for WS messages and HTTP sync requests)
 export {
-	decodeMessageType,
-	decodeRpcMessage,
-	decodeRpcPayload,
-	type DecodedRpcMessage,
-	decodeSyncMessage,
 	decodeSyncRequest,
-	decodeSyncStatus,
-	encodeAwareness,
-	encodeAwarenessStates,
-	encodeQueryAwareness,
-	encodeRpcRequest,
-	encodeRpcResponse,
 	encodeSyncRequest,
-	encodeSyncStatus,
 	encodeSyncStep1,
-	encodeSyncStep2,
 	encodeSyncUpdate,
 	handleSyncPayload,
-	MESSAGE_TYPE,
-	RPC_TYPE,
 	SYNC_MESSAGE_TYPE,
 	type SyncMessageType,
 	stateVectorsEqual,
 } from './protocol';
-
-// RPC error variants and type guard (used by both server and client)
-export { isRpcError, RpcError } from './rpc-errors';
+export { ROOM_ROUTE } from './room-route';

package/src/origins.ts

@@ -0,0 +1,45 @@
+/**
+ * Transport origin sentinels for Yjs sync.
+ *
+ * Canonical definitions live here because every transport that touches a
+ * shared Y.Doc must agree on them. When the WebSocket handler applies a
+ * remote update, it tags it with `SYNC_ORIGIN`; the BroadcastChannel handler
+ * tags cross-tab updates with `BC_ORIGIN`. Handlers check origins to avoid
+ * echo loops (e.g., BC must not re-broadcast what it just received from WS,
+ * and vice versa).
+ *
+ * Historically each transport defined its own symbol locally, which meant
+ * two separate symbols for the same semantic "this update came from the
+ * server" concept: fine as long as only one transport existed per Y.Doc,
+ * risky once multiple layers could attach. These exports make the contract
+ * explicit and unambiguous.
+ *
+ * **Not here**: self-loop guards that never leave their defining module
+ * (`DEDUP_ORIGIN` in y-keyvalue-lww.ts, `REENCRYPT_ORIGIN` in
+ * y-keyvalue-lww-encrypted.ts). Those are genuinely private and don't
+ * benefit from sharing.
+ */
+
+/** Origin for updates applied from the WebSocket sync transport. */
+export const SYNC_ORIGIN = Symbol.for('@epicenter/sync/sync-origin');
+
+/** Origin for updates applied from BroadcastChannel cross-tab sync. */
+export const BC_ORIGIN = Symbol.for('@epicenter/sync/bc-origin');
+
+/**
+ * Origins that mean a realtime transport already applied this update locally.
+ *
+ * Realtime transport listeners use this list to avoid forwarding an update
+ * back through another realtime transport.
+ */
+const TRANSPORT_ORIGINS = [
+	SYNC_ORIGIN,
+	BC_ORIGIN,
+] as const satisfies readonly unknown[];
+
+export function isTransportOrigin(origin: unknown): boolean {
+	return (
+		typeof origin === 'symbol' &&
+		TRANSPORT_ORIGINS.some((transportOrigin) => transportOrigin === origin)
+	);
+}