@syncular/client-plugin-encryption 0.0.1-60

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@syncular/client-plugin-encryption",
+  "version": "0.0.1-60",
+  "description": "End-to-end encryption plugin for the Syncular client",
+  "license": "MIT",
+  "author": "Benjamin Kniffler",
+  "homepage": "https://syncular.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/syncular/syncular.git",
+    "directory": "packages/client-plugin-encryption"
+  },
+  "bugs": {
+    "url": "https://github.com/syncular/syncular/issues"
+  },
+  "keywords": [
+    "sync",
+    "offline-first",
+    "realtime",
+    "database",
+    "typescript",
+    "encryption",
+    "e2ee",
+    "security"
+  ],
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    }
+  },
+  "scripts": {
+    "test": "bun test --pass-with-no-tests",
+    "tsgo": "tsgo --noEmit",
+    "build": "rm -rf dist && tsgo",
+    "release": "bun pm pack --destination . && npm publish ./*.tgz --tag latest && rm -f ./*.tgz"
+  },
+  "dependencies": {
+    "@noble/ciphers": "^2.1.1",
+    "@noble/curves": "^2.0.1",
+    "@noble/hashes": "^2.0.1",
+    "@scure/bip39": "^2.0.1",
+    "@syncular/client": "0.0.1",
+    "@syncular/core": "0.0.1"
+  },
+  "devDependencies": {
+    "@syncular/config": "0.0.0",
+    "kysely-bun-sqlite": "^0.4.0"
+  },
+  "peerDependencies": {
+    "kysely": "^0.28.0"
+  },
+  "files": [
+    "dist",
+    "src"
+  ]
+}

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

@@ -0,0 +1,193 @@
+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('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();
+    });
+  });
+
+  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);
+      }
+    });
+  });
+});

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');
+  });
+});