@syncular/client-plugin-encryption 0.0.1-100

package/src/__tests__/key-sharing.test.ts

@@ -0,0 +1,225 @@
+import { describe, expect, test } from 'bun:test';
+import {
+  base64UrlToKey,
+  decodeWrappedKey,
+  encodeWrappedKey,
+  generateKeypair,
+  generateSymmetricKey,
+  keyToBase64Url,
+  keyToJson,
+  keyToMnemonic,
+  keyToShareUrl,
+  mnemonicToKey,
+  mnemonicToPublicKey,
+  normalizeMnemonicInput,
+  parseKeyShareJson,
+  parseShareUrl,
+  publicKeyToJson,
+  publicKeyToMnemonic,
+  publicKeyToShareUrl,
+  unwrapKey,
+  wrapKeyForRecipient,
+} from '../key-sharing';
+
+describe('key-sharing', () => {
+  describe('symmetric key utilities', () => {
+    test('generateSymmetricKey returns 32 bytes', () => {
+      const key = generateSymmetricKey();
+      expect(key).toBeInstanceOf(Uint8Array);
+      expect(key.length).toBe(32);
+    });
+
+    test('keyToMnemonic produces 24 words', () => {
+      const key = generateSymmetricKey();
+      const mnemonic = keyToMnemonic(key);
+      const words = mnemonic.split(' ');
+      expect(words.length).toBe(24);
+    });
+
+    test('mnemonicToKey roundtrip', () => {
+      const key = generateSymmetricKey();
+      const mnemonic = keyToMnemonic(key);
+      const recovered = mnemonicToKey(mnemonic);
+      expect(recovered).toEqual(key);
+    });
+
+    test('normalizeMnemonicInput strips numbered list noise', () => {
+      const key = generateSymmetricKey();
+      const mnemonic = keyToMnemonic(key);
+      const words = mnemonic.split(' ');
+      const numbered = words.map((word, i) => `${i + 1}. ${word}`).join('\n');
+
+      const normalized = normalizeMnemonicInput(numbered);
+      expect(normalized).toBe(mnemonic);
+
+      const recovered = mnemonicToKey(numbered);
+      expect(recovered).toEqual(key);
+    });
+
+    test('keyToBase64Url roundtrip', () => {
+      const key = generateSymmetricKey();
+      const encoded = keyToBase64Url(key);
+      const decoded = base64UrlToKey(encoded);
+      expect(decoded).toEqual(key);
+    });
+
+    test('base64UrlToKey rejects malformed base64url', () => {
+      expect(() => base64UrlToKey('@@@@')).toThrow();
+    });
+
+    test('base64UrlToKey rejects wrong-length payloads', () => {
+      expect(() => base64UrlToKey('QQ')).toThrow(
+        'Invalid key length: expected 32 bytes, got 1'
+      );
+    });
+
+    test('keyToMnemonic throws for wrong length', () => {
+      expect(() => keyToMnemonic(new Uint8Array(16))).toThrow();
+    });
+  });
+
+  describe('X25519 keypair utilities', () => {
+    test('generateKeypair returns valid keys', () => {
+      const { publicKey, privateKey } = generateKeypair();
+      expect(publicKey).toBeInstanceOf(Uint8Array);
+      expect(privateKey).toBeInstanceOf(Uint8Array);
+      expect(publicKey.length).toBe(32);
+      expect(privateKey.length).toBe(32);
+    });
+
+    test('publicKeyToMnemonic roundtrip', () => {
+      const { publicKey } = generateKeypair();
+      const mnemonic = publicKeyToMnemonic(publicKey);
+      const recovered = mnemonicToPublicKey(mnemonic);
+      expect(recovered).toEqual(publicKey);
+    });
+  });
+
+  describe('key wrapping', () => {
+    test('wrap and unwrap symmetric key', () => {
+      const alice = generateKeypair();
+      const symmetricKey = generateSymmetricKey();
+
+      const wrapped = wrapKeyForRecipient(alice.publicKey, symmetricKey);
+      expect(wrapped.ephemeralPublic.length).toBe(32);
+      expect(wrapped.ciphertext.length).toBe(72);
+
+      const unwrapped = unwrapKey(alice.privateKey, wrapped);
+      expect(unwrapped).toEqual(symmetricKey);
+    });
+
+    test('encodeWrappedKey roundtrip', () => {
+      const alice = generateKeypair();
+      const symmetricKey = generateSymmetricKey();
+
+      const wrapped = wrapKeyForRecipient(alice.publicKey, symmetricKey);
+      const encoded = encodeWrappedKey(wrapped);
+      const decoded = decodeWrappedKey(encoded);
+
+      expect(decoded.ephemeralPublic).toEqual(wrapped.ephemeralPublic);
+      expect(decoded.ciphertext).toEqual(wrapped.ciphertext);
+
+      const unwrapped = unwrapKey(alice.privateKey, decoded);
+      expect(unwrapped).toEqual(symmetricKey);
+    });
+
+    test('wrong private key fails to unwrap', () => {
+      const alice = generateKeypair();
+      const bob = generateKeypair();
+      const symmetricKey = generateSymmetricKey();
+
+      const wrapped = wrapKeyForRecipient(alice.publicKey, symmetricKey);
+
+      expect(() => unwrapKey(bob.privateKey, wrapped)).toThrow();
+    });
+  });
+
+  describe('share URL format', () => {
+    test('keyToShareUrl roundtrip', () => {
+      const key = generateSymmetricKey();
+      const url = keyToShareUrl(key);
+      const parsed = parseShareUrl(url);
+
+      expect(parsed.type).toBe('symmetric');
+      if (parsed.type === 'symmetric') {
+        expect(parsed.key).toEqual(key);
+        expect(parsed.kid).toBeUndefined();
+      }
+    });
+
+    test('keyToShareUrl with kid', () => {
+      const key = generateSymmetricKey();
+      const url = keyToShareUrl(key, 'my-key-id');
+      const parsed = parseShareUrl(url);
+
+      expect(parsed.type).toBe('symmetric');
+      if (parsed.type === 'symmetric') {
+        expect(parsed.key).toEqual(key);
+        expect(parsed.kid).toBe('my-key-id');
+      }
+    });
+
+    test('publicKeyToShareUrl roundtrip', () => {
+      const { publicKey } = generateKeypair();
+      const url = publicKeyToShareUrl(publicKey);
+      const parsed = parseShareUrl(url);
+
+      expect(parsed.type).toBe('publicKey');
+      if (parsed.type === 'publicKey') {
+        expect(parsed.publicKey).toEqual(publicKey);
+      }
+    });
+
+    test('parseShareUrl throws for invalid URL', () => {
+      expect(() => parseShareUrl('https://example.com')).toThrow();
+      expect(() => parseShareUrl('sync://invalid')).toThrow();
+    });
+
+    test('parseShareUrl rejects malformed base64url payloads', () => {
+      expect(() => parseShareUrl('sync://k/1/@@@@')).toThrow();
+    });
+
+    test('parseShareUrl rejects wrong-length key payloads', () => {
+      expect(() => parseShareUrl('sync://pk/1/QQ')).toThrow(
+        'Invalid key length: expected 32 bytes, got 1'
+      );
+    });
+  });
+
+  describe('JSON format', () => {
+    test('keyToJson roundtrip', () => {
+      const key = generateSymmetricKey();
+      const json = keyToJson(key, 'test-kid');
+      const parsed = parseKeyShareJson(JSON.stringify(json));
+
+      expect(parsed.type).toBe('symmetric');
+      if (parsed.type === 'symmetric') {
+        expect(parsed.key).toEqual(key);
+        expect(parsed.kid).toBe('test-kid');
+      }
+    });
+
+    test('publicKeyToJson roundtrip', () => {
+      const { publicKey } = generateKeypair();
+      const json = publicKeyToJson(publicKey);
+      const parsed = parseKeyShareJson(JSON.stringify(json));
+
+      expect(parsed.type).toBe('publicKey');
+      if (parsed.type === 'publicKey') {
+        expect(parsed.publicKey).toEqual(publicKey);
+      }
+    });
+
+    test('parseKeyShareJson rejects malformed payloads', () => {
+      expect(() =>
+        parseKeyShareJson(JSON.stringify({ type: 'symmetric', k: '@@@@' }))
+      ).toThrow();
+    });
+
+    test('parseKeyShareJson rejects wrong-length payloads', () => {
+      expect(() =>
+        parseKeyShareJson(JSON.stringify({ type: 'publicKey', pk: 'QQ' }))
+      ).toThrow('Invalid key length: expected 32 bytes, got 1');
+    });
+  });
+});

package/src/__tests__/refresh-encrypted-fields.test.ts

@@ -0,0 +1,182 @@
+import { Database } from 'bun:sqlite';
+import { afterEach, beforeEach, describe, expect, mock, test } from 'bun:test';
+import type { SyncClientDb } from '@syncular/client';
+import { Kysely } from 'kysely';
+import { BunSqliteDialect } from 'kysely-bun-sqlite';
+
+import {
+  createFieldEncryptionPlugin,
+  createStaticFieldEncryptionKeys,
+  generateSymmetricKey,
+} from '../index';
+
+interface SharedTasksTable {
+  id: string;
+  share_id: string;
+  owner_id: string;
+  title: string;
+  completed: number;
+}
+
+interface TestDb extends SyncClientDb {
+  shared_tasks: SharedTasksTable;
+}
+
+async function createTestDb(): Promise<Kysely<TestDb>> {
+  const db = new Kysely<TestDb>({
+    dialect: new BunSqliteDialect({
+      database: new Database(':memory:'),
+    }),
+  });
+
+  await db.schema
+    .createTable('shared_tasks')
+    .addColumn('id', 'text', (col) => col.primaryKey())
+    .addColumn('share_id', 'text', (col) => col.notNull())
+    .addColumn('owner_id', 'text', (col) => col.notNull())
+    .addColumn('title', 'text', (col) => col.notNull())
+    .addColumn('completed', 'integer', (col) => col.notNull().defaultTo(0))
+    .execute();
+
+  return db;
+}
+
+describe('refreshEncryptedFields', () => {
+  let db: Kysely<TestDb>;
+
+  beforeEach(async () => {
+    db = await createTestDb();
+  });
+
+  afterEach(async () => {
+    await db.destroy();
+  });
+
+  test('decrypts existing ciphertext rows and records local mutations', async () => {
+    const ownerKid = 'share-demo';
+    const ownerKey = generateSymmetricKey();
+    const rule = {
+      scope: 'shared_tasks',
+      table: 'shared_tasks',
+      fields: ['title'],
+    };
+
+    const ownerPlugin = createFieldEncryptionPlugin({
+      rules: [rule],
+      keys: createStaticFieldEncryptionKeys({
+        keys: { [ownerKid]: ownerKey },
+        encryptionKid: ownerKid,
+      }),
+      decryptionErrorMode: 'keepCiphertext',
+    });
+
+    const pushRequest = {
+      clientId: 'alice-client',
+      clientCommitId: 'commit-1',
+      schemaVersion: 1,
+      operations: [
+        {
+          table: 'shared_tasks',
+          row_id: 'task-1',
+          op: 'upsert' as const,
+          base_version: null,
+          payload: {
+            id: 'task-1',
+            share_id: 'share-1',
+            owner_id: 'alice',
+            title: 'Top secret',
+            completed: 0,
+          },
+        },
+      ],
+    };
+
+    const encryptedRequest = await ownerPlugin.beforePush!(
+      { actorId: 'alice', clientId: 'alice-client' },
+      pushRequest
+    );
+
+    const encryptedTitle =
+      encryptedRequest.operations[0]?.payload?.title ?? null;
+    expect(typeof encryptedTitle).toBe('string');
+    expect(String(encryptedTitle).startsWith('dgsync:e2ee:1:')).toBe(true);
+
+    await db
+      .insertInto('shared_tasks')
+      .values({
+        id: 'task-1',
+        share_id: 'share-1',
+        owner_id: 'alice',
+        title: String(encryptedTitle),
+        completed: 0,
+      })
+      .execute();
+
+    let importedKey: Uint8Array | null = null;
+    const recipientPlugin = createFieldEncryptionPlugin({
+      rules: [rule],
+      keys: {
+        async getKey(kid: string): Promise<Uint8Array> {
+          if (!importedKey || kid !== ownerKid) {
+            throw new Error(`Missing encryption key for kid "${kid}"`);
+          }
+          return importedKey;
+        },
+        getEncryptionKid() {
+          return ownerKid;
+        },
+      },
+      decryptionErrorMode: 'keepCiphertext',
+    });
+
+    const recordLocalMutations = mock(
+      (
+        _inputs: Array<{
+          table: string;
+          rowId: string;
+          op: 'upsert' | 'delete';
+        }>
+      ) => {}
+    );
+    const engine = { recordLocalMutations };
+
+    const beforeImport = await recipientPlugin.refreshEncryptedFields({
+      db,
+      engine,
+      ctx: { actorId: 'bob', clientId: 'bob-client' },
+      targets: [
+        { scope: 'shared_tasks', table: 'shared_tasks', fields: ['title'] },
+      ],
+    });
+
+    expect(beforeImport.rowsUpdated).toBe(0);
+    expect(beforeImport.fieldsUpdated).toBe(0);
+    expect(recordLocalMutations).toHaveBeenCalledTimes(0);
+
+    importedKey = ownerKey;
+
+    const afterImport = await recipientPlugin.refreshEncryptedFields({
+      db,
+      engine,
+      ctx: { actorId: 'bob', clientId: 'bob-client' },
+      targets: [
+        { scope: 'shared_tasks', table: 'shared_tasks', fields: ['title'] },
+      ],
+    });
+
+    expect(afterImport.rowsUpdated).toBe(1);
+    expect(afterImport.fieldsUpdated).toBe(1);
+    expect(recordLocalMutations).toHaveBeenCalledTimes(1);
+    expect(recordLocalMutations.mock.calls[0]?.[0]).toEqual([
+      { table: 'shared_tasks', rowId: 'task-1', op: 'upsert' },
+    ]);
+
+    const row = await db
+      .selectFrom('shared_tasks')
+      .select(['title'])
+      .where('id', '=', 'task-1')
+      .executeTakeFirstOrThrow();
+
+    expect(row.title).toBe('Top secret');
+  });
+});

package/src/__tests__/scope-resolution.test.ts

@@ -0,0 +1,202 @@
+import { describe, expect, test } from 'bun:test';
+import type {
+  SyncPullRequest,
+  SyncPullResponse,
+  SyncPushRequest,
+  SyncPushResponse,
+} from '@syncular/core';
+import {
+  createFieldEncryptionPlugin,
+  createStaticFieldEncryptionKeys,
+  generateSymmetricKey,
+} from '../index';
+
+const keyId = 'scope-resolution';
+const keys = createStaticFieldEncryptionKeys({
+  keys: { [keyId]: generateSymmetricKey() },
+  encryptionKid: keyId,
+});
+
+const plugin = createFieldEncryptionPlugin({
+  rules: [
+    {
+      scope: 'workspace_tasks',
+      table: 'tasks',
+      fields: ['title'],
+    },
+  ],
+  keys,
+});
+
+const context = { actorId: 'actor-1', clientId: 'client-1' };
+
+async function buildEncryptedTitle(): Promise<string> {
+  const request: SyncPushRequest = {
+    clientId: 'client-1',
+    clientCommitId: 'commit-1',
+    schemaVersion: 1,
+    operations: [
+      {
+        table: 'tasks',
+        row_id: 'task-1',
+        op: 'upsert',
+        payload: {
+          id: 'task-1',
+          title: 'Secret title',
+        },
+        base_version: null,
+      },
+    ],
+  };
+
+  const encrypted = await plugin.beforePush!(context, request);
+  const encryptedTitle = encrypted.operations[0]?.payload?.title;
+  if (typeof encryptedTitle !== 'string') {
+    throw new Error('Expected encrypted title to be a string');
+  }
+  return encryptedTitle;
+}
+
+describe('Field encryption scope/table resolution', () => {
+  test('encrypts beforePush when rule scope differs from operation table', async () => {
+    const request: SyncPushRequest = {
+      clientId: 'client-1',
+      clientCommitId: 'commit-1',
+      schemaVersion: 1,
+      operations: [
+        {
+          table: 'tasks',
+          row_id: 'task-1',
+          op: 'upsert',
+          payload: {
+            id: 'task-1',
+            title: 'Secret title',
+            completed: false,
+          },
+          base_version: null,
+        },
+      ],
+    };
+
+    const encrypted = await plugin.beforePush!(context, request);
+    const payload = encrypted.operations[0]?.payload;
+    const encryptedTitle = payload?.title;
+
+    expect(typeof encryptedTitle).toBe('string');
+    expect(encryptedTitle).not.toBe('Secret title');
+    expect(String(encryptedTitle).startsWith('dgsync:e2ee:1:')).toBe(true);
+    expect(payload?.completed).toBe(false);
+  });
+
+  test('decrypts afterPush conflict rows with scope/table mismatch rules', async () => {
+    const encryptedTitle = await buildEncryptedTitle();
+
+    const request: SyncPushRequest = {
+      clientId: 'client-1',
+      clientCommitId: 'commit-2',
+      schemaVersion: 1,
+      operations: [
+        {
+          table: 'tasks',
+          row_id: 'task-1',
+          op: 'upsert',
+          payload: {
+            id: 'task-1',
+            title: 'Secret title',
+          },
+          base_version: null,
+        },
+      ],
+    };
+
+    const response: SyncPushResponse = {
+      ok: true,
+      status: 'rejected',
+      results: [
+        {
+          opIndex: 0,
+          status: 'conflict',
+          message: 'conflict',
+          server_version: 2,
+          server_row: {
+            id: 'task-1',
+            title: encryptedTitle,
+          },
+        },
+      ],
+    };
+
+    const next = await plugin.afterPush!(context, { request, response });
+    const conflict = next.results[0];
+
+    if (!conflict || conflict.status !== 'conflict') {
+      throw new Error('Expected conflict result in afterPush response');
+    }
+    if (!('server_row' in conflict)) {
+      throw new Error('Expected conflict server_row in afterPush response');
+    }
+    if (
+      typeof conflict.server_row !== 'object' ||
+      conflict.server_row === null ||
+      Array.isArray(conflict.server_row)
+    ) {
+      throw new Error('Expected conflict server_row to be an object');
+    }
+    expect(conflict.server_row.title).toBe('Secret title');
+  });
+
+  test('decrypts incremental pull rows when change.table is the scope name', async () => {
+    const encryptedTitle = await buildEncryptedTitle();
+
+    const request: SyncPullRequest = {
+      clientId: 'client-1',
+      limitCommits: 50,
+      subscriptions: [],
+    };
+
+    const response: SyncPullResponse = {
+      ok: true,
+      subscriptions: [
+        {
+          id: 'workspace-sub',
+          status: 'active',
+          scopes: {},
+          bootstrap: false,
+          nextCursor: 1,
+          commits: [
+            {
+              commitSeq: 1,
+              createdAt: new Date(0).toISOString(),
+              actorId: 'actor-1',
+              changes: [
+                {
+                  table: 'workspace_tasks',
+                  row_id: 'task-1',
+                  op: 'upsert',
+                  row_json: {
+                    id: 'task-1',
+                    title: encryptedTitle,
+                  },
+                  row_version: 2,
+                  scopes: {},
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    };
+
+    const next = await plugin.afterPull!(context, { request, response });
+    const change =
+      next.subscriptions[0]?.commits[0]?.changes[0]?.row_json ?? null;
+    if (
+      typeof change !== 'object' ||
+      change === null ||
+      Array.isArray(change)
+    ) {
+      throw new Error('Expected decrypted change row_json object');
+    }
+    expect(change.title).toBe('Secret title');
+  });
+});

package/src/crypto-utils.test.ts

@@ -0,0 +1,84 @@
+import { afterEach, describe, expect, test } from 'bun:test';
+import {
+  base64ToBytes,
+  base64UrlToBytes,
+  bytesToBase64,
+  bytesToBase64Url,
+  hexToBytes,
+  randomBytes,
+} from './crypto-utils';
+
+let originalBuffer: typeof Buffer | undefined;
+let bufferOverridden = false;
+
+function disableBufferRuntime(): void {
+  originalBuffer = globalThis.Buffer;
+  Object.defineProperty(globalThis, 'Buffer', {
+    value: undefined,
+    writable: true,
+    configurable: true,
+  });
+  bufferOverridden = true;
+}
+
+function restoreBufferRuntime(): void {
+  if (!bufferOverridden) return;
+  Object.defineProperty(globalThis, 'Buffer', {
+    value: originalBuffer,
+    writable: true,
+    configurable: true,
+  });
+  bufferOverridden = false;
+}
+
+afterEach(() => {
+  restoreBufferRuntime();
+});
+
+describe('crypto-utils', () => {
+  test('encodes and decodes base64 payloads', () => {
+    const bytes = new Uint8Array([0, 1, 2, 253, 254, 255]);
+    const encoded = bytesToBase64(bytes);
+    const decoded = base64ToBytes(encoded);
+    expect(decoded).toEqual(bytes);
+  });
+
+  test('encodes and decodes base64url payloads', () => {
+    const bytes = new Uint8Array([0, 1, 2, 253, 254, 255]);
+    const encoded = bytesToBase64Url(bytes);
+    const decoded = base64UrlToBytes(encoded);
+    expect(decoded).toEqual(bytes);
+  });
+
+  test('rejects malformed base64 inputs', () => {
+    expect(() => base64ToBytes('@@@@')).toThrow('Invalid base64 string');
+    expect(() => base64UrlToBytes('@@@@')).toThrow('Invalid base64url string');
+  });
+
+  test('works when Buffer is unavailable', () => {
+    disableBufferRuntime();
+
+    const bytes = new Uint8Array([0, 1, 2, 253, 254, 255]);
+    const encoded = bytesToBase64(bytes);
+    const decoded = base64ToBytes(encoded);
+    expect(decoded).toEqual(bytes);
+
+    const encodedUrl = bytesToBase64Url(bytes);
+    const decodedUrl = base64UrlToBytes(encodedUrl);
+    expect(decodedUrl).toEqual(bytes);
+  });
+
+  test('parses hex strings', () => {
+    expect(hexToBytes('00a1ff')).toEqual(new Uint8Array([0, 161, 255]));
+    expect(() => hexToBytes('0')).toThrow(
+      'Invalid hex string (length must be even)'
+    );
+    expect(() => hexToBytes('zz')).toThrow('Invalid hex string');
+  });
+
+  test('creates random byte arrays', () => {
+    const bytes = randomBytes(32);
+    expect(bytes).toBeInstanceOf(Uint8Array);
+    expect(bytes.length).toBe(32);
+  });
+});