@syncular/server-hono 0.0.1-100

package/src/__tests__/realtime-bridge.test.ts

@@ -0,0 +1,131 @@
+import { describe, expect, it, mock } from 'bun:test';
+import { createPgliteDb } from '@syncular/dialect-pglite';
+import {
+  ensureSyncSchema,
+  InMemorySyncRealtimeBroadcaster,
+  type SyncCoreDb,
+} from '@syncular/server';
+import { createPostgresServerDialect } from '@syncular/server-dialect-postgres';
+import { defineWebSocketHelper } from 'hono/ws';
+import {
+  createSyncRoutes,
+  getSyncRealtimeUnsubscribe,
+  getSyncWebSocketConnectionManager,
+} from '../routes';
+
+describe('realtime broadcaster bridge', () => {
+  it('notifies local WebSocket connections when another instance publishes a commit', async () => {
+    const db = createPgliteDb<SyncCoreDb>();
+    const dialect = createPostgresServerDialect();
+    await ensureSyncSchema(db, dialect);
+
+    const commit = await db
+      .insertInto('sync_commits')
+      .values({
+        partition_id: 'default',
+        actor_id: 'u1',
+        client_id: 'client-1',
+        client_commit_id: 'c1',
+        meta: null,
+        result_json: null,
+      })
+      .returning(['commit_seq'])
+      .executeTakeFirstOrThrow();
+
+    const commitSeq = Number(commit.commit_seq);
+
+    await db
+      .insertInto('sync_changes')
+      .values({
+        commit_seq: commitSeq,
+        partition_id: 'default',
+        table: 'tasks',
+        row_id: 't1',
+        op: 'upsert',
+        row_json: { id: 't1' },
+        row_version: 1,
+        scopes: { user_id: 'u1' },
+      })
+      .execute();
+
+    const broadcaster = new InMemorySyncRealtimeBroadcaster();
+    const upgradeWebSocket = defineWebSocketHelper(async () => {});
+
+    const routes1 = createSyncRoutes({
+      db,
+      dialect,
+      handlers: [],
+      authenticate: async () => ({ actorId: 'u1' }),
+      sync: {
+        websocket: {
+          enabled: true,
+          upgradeWebSocket,
+          heartbeatIntervalMs: 0,
+        },
+        realtime: { broadcaster, instanceId: 'i1' },
+      },
+    });
+
+    const routes2 = createSyncRoutes({
+      db,
+      dialect,
+      handlers: [],
+      authenticate: async () => ({ actorId: 'u1' }),
+      sync: {
+        websocket: {
+          enabled: true,
+          upgradeWebSocket,
+          heartbeatIntervalMs: 0,
+        },
+        realtime: { broadcaster, instanceId: 'i2' },
+      },
+    });
+
+    const mgr2 = getSyncWebSocketConnectionManager(routes2);
+    expect(mgr2).toBeTruthy();
+
+    const onSync = mock((_cursor: number) => {});
+
+    mgr2!.register(
+      {
+        actorId: 'u1',
+        clientId: 'client-2',
+        get isOpen() {
+          return true;
+        },
+        sendSync: onSync,
+        sendHeartbeat: mock(() => {}),
+        sendPresence: mock(() => {}),
+        sendError: mock(() => {}),
+        close: mock(() => {}),
+      },
+      ['default::user:u1']
+    );
+
+    // Publish without scopeKeys to exercise DB lookup on the receiving instance.
+    await broadcaster.publish({
+      type: 'commit',
+      commitSeq,
+      sourceInstanceId: 'i1',
+    });
+    await new Promise((r) => setTimeout(r, 0));
+
+    expect(onSync).toHaveBeenCalledWith(commitSeq);
+
+    // Echo suppression: instance2 ignores events it originated.
+    onSync.mockClear();
+    await broadcaster.publish({
+      type: 'commit',
+      commitSeq,
+      sourceInstanceId: 'i2',
+    });
+    await new Promise((r) => setTimeout(r, 0));
+
+    expect(onSync).not.toHaveBeenCalled();
+
+    getSyncRealtimeUnsubscribe(routes1)?.();
+    getSyncRealtimeUnsubscribe(routes2)?.();
+    await broadcaster.close();
+    await db.destroy();
+  });
+});

package/src/__tests__/sync-rate-limit-routing.test.ts

@@ -0,0 +1,181 @@
+import { afterEach, beforeEach, describe, expect, it } from 'bun:test';
+import {
+  createServerHandler,
+  ensureSyncSchema,
+  type SyncCoreDb,
+} from '@syncular/server';
+import { Hono } from 'hono';
+import type { Kysely } from 'kysely';
+import { createBunSqliteDb } from '../../../dialect-bun-sqlite/src';
+import { createSqliteServerDialect } from '../../../server-dialect-sqlite/src';
+import { resetRateLimitStore } from '../rate-limit';
+import { createSyncRoutes } from '../routes';
+
+interface TasksTable {
+  id: string;
+  user_id: string;
+  title: string;
+  server_version: number;
+}
+
+interface ServerDb extends SyncCoreDb {
+  tasks: TasksTable;
+}
+
+interface ClientDb {
+  tasks: TasksTable;
+}
+
+describe('createSyncRoutes rate limit routing', () => {
+  let db: Kysely<ServerDb>;
+  const dialect = createSqliteServerDialect();
+
+  beforeEach(async () => {
+    db = createBunSqliteDb<ServerDb>({ path: ':memory:' });
+    await ensureSyncSchema(db, dialect);
+
+    await db.schema
+      .createTable('tasks')
+      .addColumn('id', 'text', (col) => col.primaryKey())
+      .addColumn('user_id', 'text', (col) => col.notNull())
+      .addColumn('title', 'text', (col) => col.notNull())
+      .addColumn('server_version', 'integer', (col) =>
+        col.notNull().defaultTo(0)
+      )
+      .execute();
+  });
+
+  afterEach(async () => {
+    resetRateLimitStore();
+    await db.destroy();
+  });
+
+  const tasksHandler = createServerHandler<ServerDb, ClientDb, 'tasks'>({
+    table: 'tasks',
+    scopes: ['user:{user_id}'],
+    resolveScopes: async (ctx) => ({ user_id: [ctx.actorId] }),
+  });
+
+  const pullPayload = {
+    limitCommits: 10,
+    subscriptions: [
+      {
+        id: 'sub-1',
+        shape: 'tasks',
+        scopes: { user_id: 'u1' },
+        cursor: -1,
+      },
+    ],
+  };
+
+  function pushPayload(clientCommitId: string, rowId: string) {
+    return {
+      clientCommitId,
+      schemaVersion: 1,
+      operations: [
+        {
+          table: 'tasks',
+          row_id: rowId,
+          op: 'upsert' as const,
+          base_version: null,
+          payload: {
+            id: rowId,
+            user_id: 'u1',
+            title: `Task ${rowId}`,
+            server_version: 0,
+          },
+        },
+      ],
+    };
+  }
+
+  function createJsonRequest(body: object): Request {
+    return new Request('http://localhost/sync', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(body),
+    });
+  }
+
+  it('does not consume push quota for pull-only requests', async () => {
+    const routes = createSyncRoutes({
+      db,
+      dialect,
+      handlers: [tasksHandler],
+      authenticate: async () => ({ actorId: 'u1' }),
+      sync: {
+        rateLimit: {
+          pull: { maxRequests: 1, windowMs: 60_000 },
+          push: { maxRequests: 1, windowMs: 60_000 },
+        },
+      },
+    });
+
+    const app = new Hono();
+    app.route('/sync', routes);
+
+    const pullFirst = await app.request(
+      createJsonRequest({
+        clientId: 'client-1',
+        pull: pullPayload,
+      })
+    );
+    const pushFirst = await app.request(
+      createJsonRequest({
+        clientId: 'client-1',
+        push: pushPayload('commit-1', 't1'),
+      })
+    );
+    const pullSecond = await app.request(
+      createJsonRequest({
+        clientId: 'client-1',
+        pull: pullPayload,
+      })
+    );
+    const pushSecond = await app.request(
+      createJsonRequest({
+        clientId: 'client-1',
+        push: pushPayload('commit-2', 't2'),
+      })
+    );
+
+    expect(pullFirst.status).toBe(200);
+    expect(pushFirst.status).toBe(200);
+    expect(pullSecond.status).toBe(429);
+    expect(pushSecond.status).toBe(429);
+  });
+
+  it('authenticates once per combined sync request with rate limiting enabled', async () => {
+    let authCalls = 0;
+
+    const routes = createSyncRoutes({
+      db,
+      dialect,
+      handlers: [tasksHandler],
+      authenticate: async () => {
+        authCalls += 1;
+        return { actorId: 'u1' };
+      },
+      sync: {
+        rateLimit: {
+          pull: { maxRequests: 10, windowMs: 60_000 },
+          push: { maxRequests: 10, windowMs: 60_000 },
+        },
+      },
+    });
+
+    const app = new Hono();
+    app.route('/sync', routes);
+
+    const response = await app.request(
+      createJsonRequest({
+        clientId: 'client-1',
+        push: pushPayload('commit-combined-1', 't-combined-1'),
+        pull: pullPayload,
+      })
+    );
+
+    expect(response.status).toBe(200);
+    expect(authCalls).toBe(1);
+  });
+});

package/src/__tests__/ws-connection-manager.test.ts

@@ -0,0 +1,176 @@
+import { describe, expect, it } from 'bun:test';
+import { type WebSocketConnection, WebSocketConnectionManager } from '../ws';
+
+function createConn(args: {
+  actorId: string;
+  clientId: string;
+  onSync: (cursor: number) => void;
+}): WebSocketConnection {
+  let open = true;
+
+  return {
+    get isOpen() {
+      return open;
+    },
+    actorId: args.actorId,
+    clientId: args.clientId,
+    transportPath: 'direct',
+    sendSync(cursor) {
+      if (!open) return;
+      args.onSync(cursor);
+    },
+    sendHeartbeat() {},
+    sendPresence() {},
+    sendError() {
+      open = false;
+    },
+    close() {
+      open = false;
+    },
+  };
+}
+
+describe('WebSocketConnectionManager (scopes)', () => {
+  it('notifies connections based on scope overlap', () => {
+    const mgr = new WebSocketConnectionManager({ heartbeatIntervalMs: 0 });
+    const seen: Array<{ clientId: string; cursor: number }> = [];
+
+    const c1 = createConn({
+      actorId: 'u1',
+      clientId: 'c1',
+      onSync: (cursor) => seen.push({ clientId: 'c1', cursor }),
+    });
+    const c2 = createConn({
+      actorId: 'u2',
+      clientId: 'c2',
+      onSync: (cursor) => seen.push({ clientId: 'c2', cursor }),
+    });
+
+    mgr.register(c1, ['user:u1']);
+    mgr.register(c2, ['user:u2']);
+
+    mgr.notifyScopeKeys(['user:u1'], 10);
+    expect(seen).toEqual([{ clientId: 'c1', cursor: 10 }]);
+  });
+
+  it('updates scopes for a connected client', () => {
+    const mgr = new WebSocketConnectionManager({ heartbeatIntervalMs: 0 });
+    const seen: number[] = [];
+
+    const c1 = createConn({
+      actorId: 'u1',
+      clientId: 'c1',
+      onSync: (cursor) => seen.push(cursor),
+    });
+
+    mgr.register(c1, ['project:p1']);
+    mgr.notifyScopeKeys(['project:p1'], 1);
+
+    mgr.updateClientScopeKeys('c1', ['project:p2']);
+    mgr.notifyScopeKeys(['project:p1'], 2);
+    mgr.notifyScopeKeys(['project:p2'], 3);
+
+    expect(seen).toEqual([1, 3]);
+  });
+
+  it('dedupes notifications across multiple matching scopes', () => {
+    const mgr = new WebSocketConnectionManager({ heartbeatIntervalMs: 0 });
+    const seen: number[] = [];
+
+    const c1 = createConn({
+      actorId: 'u1',
+      clientId: 'c1',
+      onSync: (cursor) => seen.push(cursor),
+    });
+
+    mgr.register(c1, ['a', 'b']);
+    mgr.notifyScopeKeys(['a', 'b'], 5);
+
+    expect(seen).toEqual([5]);
+  });
+
+  it('supports excluding a client id', () => {
+    const mgr = new WebSocketConnectionManager({ heartbeatIntervalMs: 0 });
+    const seen: string[] = [];
+
+    const c1 = createConn({
+      actorId: 'u1',
+      clientId: 'c1',
+      onSync: () => seen.push('c1'),
+    });
+    const c2 = createConn({
+      actorId: 'u1',
+      clientId: 'c2',
+      onSync: () => seen.push('c2'),
+    });
+
+    mgr.register(c1, ['s']);
+    mgr.register(c2, ['s']);
+
+    mgr.notifyScopeKeys(['s'], 123, { excludeClientIds: ['c1'] });
+    expect(seen).toEqual(['c2']);
+  });
+
+  it('stops notifying after unregister', () => {
+    const mgr = new WebSocketConnectionManager({ heartbeatIntervalMs: 0 });
+    const seen: number[] = [];
+
+    const c1 = createConn({
+      actorId: 'u1',
+      clientId: 'c1',
+      onSync: (cursor) => seen.push(cursor),
+    });
+
+    const unregister = mgr.register(c1, ['s']);
+    mgr.notifyScopeKeys(['s'], 1);
+
+    unregister();
+    mgr.notifyScopeKeys(['s'], 2);
+
+    expect(seen).toEqual([1]);
+  });
+
+  it('allows presence join only for authorized scope keys', () => {
+    const mgr = new WebSocketConnectionManager({ heartbeatIntervalMs: 0 });
+    const c1 = createConn({
+      actorId: 'u1',
+      clientId: 'c1',
+      onSync: () => {},
+    });
+
+    mgr.register(c1, ['user:u1']);
+
+    const denied = mgr.joinPresence('c1', 'user:u2', { status: 'denied' });
+    expect(denied).toBe(false);
+    expect(mgr.getPresence('user:u2')).toEqual([]);
+
+    const allowed = mgr.joinPresence('c1', 'user:u1', { status: 'ok' });
+    expect(allowed).toBe(true);
+    expect(mgr.getPresence('user:u1')).toHaveLength(1);
+  });
+
+  it('allows presence update only for authorized scope keys', () => {
+    const mgr = new WebSocketConnectionManager({ heartbeatIntervalMs: 0 });
+    const c1 = createConn({
+      actorId: 'u1',
+      clientId: 'c1',
+      onSync: () => {},
+    });
+
+    mgr.register(c1, ['user:u1']);
+    expect(mgr.joinPresence('c1', 'user:u1', { status: 'initial' })).toBe(true);
+
+    const denied = mgr.updatePresenceMetadata('c1', 'user:u2', {
+      status: 'denied',
+    });
+    expect(denied).toBe(false);
+
+    const allowed = mgr.updatePresenceMetadata('c1', 'user:u1', {
+      status: 'updated',
+    });
+    expect(allowed).toBe(true);
+    expect(mgr.getPresence('user:u1')[0]?.metadata).toEqual({
+      status: 'updated',
+    });
+  });
+});

package/src/api-key-auth.ts

@@ -0,0 +1,179 @@
+/**
+ * @syncular/server-hono - API Key Authentication Helper
+ *
+ * Provides utilities for validating API keys in relay/proxy routes.
+ */
+
+import type { ServerSyncDialect } from '@syncular/server';
+import type { Context } from 'hono';
+import { type Kysely, sql } from 'kysely';
+import { type ApiKeyType, ApiKeyTypeSchema } from './console/schemas';
+
+interface SyncApiKeysTable {
+  key_id: string;
+  key_hash: string;
+  key_prefix: string;
+  name: string;
+  key_type: string;
+  scope_keys: unknown | null;
+  actor_id: string | null;
+  created_at: string;
+  expires_at: string | null;
+  last_used_at: string | null;
+  revoked_at: string | null;
+}
+
+type ApiKeyDb = {
+  sync_api_keys: SyncApiKeysTable;
+};
+
+interface ValidateApiKeyResult {
+  keyId: string;
+  keyType: ApiKeyType;
+  actorId: string | null;
+  scopeKeys: string[];
+}
+
+/**
+ * Validates an API key from Authorization header.
+ * Updates last_used_at on successful validation.
+ */
+export async function validateApiKey<DB extends ApiKeyDb>(
+  db: Kysely<DB>,
+  dialect: ServerSyncDialect,
+  authHeader: string | undefined
+): Promise<ValidateApiKeyResult | null> {
+  if (!authHeader?.startsWith('Bearer ')) {
+    return null;
+  }
+
+  const secretKey = authHeader.slice(7);
+  if (!secretKey || !secretKey.startsWith('sk_')) {
+    return null;
+  }
+
+  // Hash the provided key
+  const keyHash = await hashApiKey(secretKey);
+
+  // Look up key by hash
+  const rowResult = await sql<{
+    key_id: string;
+    key_type: string;
+    actor_id: string | null;
+    scope_keys: unknown | null;
+    expires_at: string | null;
+    revoked_at: string | null;
+  }>`
+    select key_id, key_type, actor_id, scope_keys, expires_at, revoked_at
+    from ${sql.table('sync_api_keys')}
+    where key_hash = ${keyHash}
+    limit 1
+  `.execute(db);
+  const row = rowResult.rows[0];
+
+  if (!row) {
+    return null;
+  }
+
+  const parsedKeyType = ApiKeyTypeSchema.safeParse(row.key_type);
+  if (!parsedKeyType.success) return null;
+
+  // Check if revoked
+  if (row.revoked_at) {
+    return null;
+  }
+
+  // Check if expired
+  if (row.expires_at) {
+    const expiresAt = new Date(row.expires_at);
+    if (expiresAt < new Date()) {
+      return null;
+    }
+  }
+
+  // Update last_used_at
+  const now = new Date().toISOString();
+  await sql`
+    update ${sql.table('sync_api_keys')}
+    set last_used_at = ${now}
+    where key_id = ${row.key_id}
+  `.execute(db);
+
+  // Parse scopes
+  const scopeKeys = dialect.dbToArray(row.scope_keys);
+
+  return {
+    keyId: row.key_id,
+    keyType: parsedKeyType.data,
+    actorId: row.actor_id,
+    scopeKeys,
+  };
+}
+
+/**
+ * Creates an authenticator for relay/proxy routes.
+ * Returns actorId from the API key if valid and allowed.
+ */
+export function createApiKeyAuthenticator<DB extends ApiKeyDb>(
+  db: Kysely<DB>,
+  dialect: ServerSyncDialect,
+  allowedTypes: ApiKeyType[]
+): (c: Context) => Promise<{ actorId: string } | null> {
+  return async (c: Context) => {
+    const authHeader = c.req.header('Authorization');
+    const result = await validateApiKey(db, dialect, authHeader);
+
+    if (!result) {
+      return null;
+    }
+
+    // Check if key type is allowed
+    if (!allowedTypes.includes(result.keyType)) {
+      return null;
+    }
+
+    // Return actorId (use key's actorId if set, otherwise use a default)
+    return {
+      actorId: result.actorId ?? `api-key:${result.keyId}`,
+    };
+  };
+}
+
+/**
+ * Middleware that validates API key and attaches result to context.
+ */
+export function apiKeyAuthMiddleware<DB extends ApiKeyDb>(
+  db: Kysely<DB>,
+  dialect: ServerSyncDialect,
+  allowedTypes: ApiKeyType[]
+) {
+  return async (
+    c: Context,
+    next: () => Promise<void>
+  ): Promise<Response | undefined> => {
+    const authHeader = c.req.header('Authorization');
+    const result = await validateApiKey(db, dialect, authHeader);
+
+    if (!result) {
+      return c.json({ error: 'UNAUTHENTICATED' }, 401);
+    }
+
+    if (!allowedTypes.includes(result.keyType)) {
+      return c.json({ error: 'FORBIDDEN', message: 'Invalid key type' }, 403);
+    }
+
+    // Attach to context for downstream handlers
+    c.set('apiKey', result);
+
+    await next();
+  };
+}
+
+// Hash function (same as in routes.ts)
+async function hashApiKey(secretKey: string): Promise<string> {
+  const encoder = new TextEncoder();
+  const data = encoder.encode(secretKey);
+  const hashBuffer = await crypto.subtle.digest('SHA-256', data);
+  const hashArray = new Uint8Array(hashBuffer);
+  return Array.from(hashArray, (b) => b.toString(16).padStart(2, '0')).join('');
+}