suaveplan/packages/security-stack/security/vault-sync/tests/property.test.ts

/**
 * Property-based tests covering the algebraic invariants of every public
 * surface in `@suaveplan/vault-sync`. We use `fast-check` to generate
 * thousands of input combinations and assert merge commutativity, merge
 * idempotency, JSON-Patch round-trip, vector-clock monotonicity, queue
 * serialization equivalence, and payload-tamper rejection.
 */

import { describe, expect, it } from "@suaveplan/testing/runner";
import * as fc from "fast-check";
import {
    applyPatch,
    decryptSyncPayload,
    diffVaultItems,
    encryptSyncPayload,
    increment,
    mergeVaultItems,
    SyncQueue,
    VaultSyncError,
} from "../src/index.js";
import type { VaultItem, VectorClockState } from "../src/types/types.js";

const arbVectorClock = fc.dictionary(
    fc.string({ minLength: 1, maxLength: 4 }),
    fc.integer({ min: 0, max: 16 })
);

const arbHistoryEntry = fc.record({
    historyId: fc.string({ minLength: 1, maxLength: 6 }),
    timestamp: fc.integer({ min: 0, max: 1_000_000 }),
    note: fc.string({ maxLength: 16 }),
});

const arbItem: fc.Arbitrary<VaultItem> = fc.record({
    id: fc.constant("shared-id"),
    title: fc.string({ maxLength: 16 }),
    password: fc.string({ maxLength: 16 }),
    folderId: fc.option(fc.string({ minLength: 1, maxLength: 6 }), {
        nil: null,
    }),
    history: fc.array(arbHistoryEntry, { maxLength: 8 }),
    nodeId: fc.constantFrom("a", "b", "c"),
    updatedAt: fc.integer({ min: 0, max: 1_000_000 }),
    clock: arbVectorClock,
});

describe("merge — commutativity (lww)", () => {
    it("mergeVaultItems(a, b, lww) deeply equals mergeVaultItems(b, a, lww)", {
        timeout: 30_000,
    }, () => {
        fc.assert(
            fc.property(arbItem, arbItem, (a, b) => {
                const ab = mergeVaultItems(a, b, "lww");
                const ba = mergeVaultItems(b, a, "lww");
                expect(ab).toEqual(ba);
            }),
            { numRuns: 200 }
        );
    });
});

describe("merge — idempotency (lww)", () => {
    it("mergeVaultItems(a, a, lww) deeply equals a (modulo clock)", {
        timeout: 30_000,
    }, () => {
        fc.assert(
            fc.property(arbItem, (a) => {
                const m = mergeVaultItems(a, a, "lww");
                const remerged = mergeVaultItems(m, m, "lww");
                expect(m).toEqual(remerged);
            }),
            { numRuns: 200 }
        );
    });
});

describe("merge — commutativity (append)", () => {
    it("mergeVaultItems(a, b, append) deeply equals mergeVaultItems(b, a, append)", {
        timeout: 30_000,
    }, () => {
        fc.assert(
            fc.property(arbItem, arbItem, (a, b) => {
                const ab = mergeVaultItems(a, b, "append");
                const ba = mergeVaultItems(b, a, "append");
                expect(ab).toEqual(ba);
            }),
            { numRuns: 200 }
        );
    });
});

describe("patch — round-trip", () => {
    it("applyPatch(a, diff(a, b)) deeply equals b", {
        timeout: 30_000,
    }, () => {
        fc.assert(
            fc.property(arbItem, arbItem, (a, b) => {
                const patch = diffVaultItems(a, b);
                let result: VaultItem | undefined;
                try {
                    result = applyPatch(a, patch);
                } catch (err) {
                    if (err instanceof VaultSyncError) {
                        // Some random combinations produce schemas that fail
                        // the exact-shape check — those are valid rejections.
                        return;
                    }
                    throw err;
                }
                // Object spread normalises optional `deleted` away; compare
                // keys present in `b`.
                expect(result.id).toEqual(b.id);
                expect(result.title).toEqual(b.title);
                expect(result.password).toEqual(b.password);
                expect(result.folderId).toEqual(b.folderId);
                expect(result.nodeId).toEqual(b.nodeId);
                expect(result.updatedAt).toEqual(b.updatedAt);
                expect(result.clock).toEqual(b.clock);
                expect(result.history).toEqual(b.history);
            }),
            { numRuns: 200 }
        );
    });
});

describe("vector-clock — monotonicity", () => {
    it("increment never decreases any component", { timeout: 30_000 }, () => {
        fc.assert(
            fc.property(
                arbVectorClock,
                fc.string({ minLength: 1, maxLength: 4 }),
                (c, n) => {
                    const next = increment(c as VectorClockState, n);
                    for (const [k, v] of Object.entries(c)) {
                        expect(next[k] ?? 0).toBeGreaterThanOrEqual(v);
                    }
                    expect(next[n] ?? 0).toBeGreaterThanOrEqual(
                        (c[n] ?? 0) + 1
                    );
                }
            ),
            { numRuns: 500 }
        );
    });
});

describe("queue — serialization round-trip", () => {
    it("deserialize(serialize(q)) preserves clock and operations", {
        timeout: 30_000,
    }, () => {
        fc.assert(
            fc.property(
                fc.array(
                    fc.record({
                        kind: fc.constantFrom("create", "update", "delete"),
                        itemId: fc.string({ minLength: 1, maxLength: 4 }),
                        fields: fc.record({
                            title: fc.string({ maxLength: 8 }),
                        }),
                    }),
                    { maxLength: 25 }
                ),
                (events) => {
                    const q = new SyncQueue({ nodeId: "n1" });
                    for (const e of events) {
                        q.enqueue(e as never);
                    }
                    const bytes = q.serialize();
                    const restored = SyncQueue.deserialize(bytes);
                    expect(restored.peek()).toEqual(q.peek());
                    expect(restored.vectorClock).toEqual(q.vectorClock);
                }
            ),
            { numRuns: 100 }
        );
    });
});

describe("crypto-sync — tamper rejection", () => {
    const key = new Uint8Array(32);
    crypto.getRandomValues(key);

    it("any single-byte ciphertext flip rejects with PAYLOAD_TAMPERED", {
        timeout: 30_000,
    }, () => {
        fc.assert(
            fc.property(
                fc.uint8Array({ minLength: 16, maxLength: 64 }),
                fc.integer({ min: 0, max: 16 * 8 - 1 }),
                (pt, bitIndex) => {
                    const env = encryptSyncPayload(pt, key);
                    const flipByte = bitIndex >> 3;
                    if (flipByte >= env.ciphertext.length) return;
                    const tampered = {
                        ...env,
                        ciphertext: new Uint8Array(env.ciphertext),
                    };
                    tampered.ciphertext[flipByte] =
                        (tampered.ciphertext[flipByte] ?? 0) ^ 0x01;
                    expect(() => decryptSyncPayload(tampered, key)).toThrow(
                        VaultSyncError
                    );
                }
            ),
            { numRuns: 100 }
        );
    });
});