@syncular/core 0.1.3 → 0.2.0

package/src/bytes.ts

@@ -0,0 +1,301 @@
+/**
+ * Primitive readers/writers for the SPEC.md Conventions table.
+ *
+ * All multi-byte integers are little-endian, fixed-width (no varints).
+ * The encoding is canonical: for every value there is exactly one valid
+ * byte sequence, so the reader rejects non-minimal presence bytes,
+ * out-of-order map keys, out-of-range bools, and i64 values outside the
+ * JS safe-integer contract.
+ */
+import { DecodeError } from './errors';
+
+const MAX_SAFE_I64 = 9007199254740991n; // 2^53 - 1
+const MIN_SAFE_I64 = -9007199254740991n;
+
+const textEncoder = new TextEncoder();
+const textDecoder = new TextDecoder('utf-8', { fatal: true });
+
+export function utf8Encode(value: string): Uint8Array {
+  return textEncoder.encode(value);
+}
+
+/** Growable little-endian byte sink. Encoder misuse throws plain `Error`. */
+export class ByteWriter {
+  #buffer = new Uint8Array(256);
+  #view = new DataView(this.#buffer.buffer);
+  #length = 0;
+
+  #reserve(extra: number): number {
+    const offset = this.#length;
+    const needed = offset + extra;
+    if (needed > this.#buffer.length) {
+      let capacity = this.#buffer.length;
+      while (capacity < needed) capacity *= 2;
+      const grown = new Uint8Array(capacity);
+      grown.set(this.#buffer.subarray(0, offset));
+      this.#buffer = grown;
+      this.#view = new DataView(grown.buffer);
+    }
+    this.#length = needed;
+    return offset;
+  }
+
+  u8(value: number): void {
+    if (!Number.isInteger(value) || value < 0 || value > 0xff) {
+      throw new Error(`u8 out of range: ${value}`);
+    }
+    const offset = this.#reserve(1);
+    this.#view.setUint8(offset, value);
+  }
+
+  u16(value: number): void {
+    if (!Number.isInteger(value) || value < 0 || value > 0xffff) {
+      throw new Error(`u16 out of range: ${value}`);
+    }
+    const offset = this.#reserve(2);
+    this.#view.setUint16(offset, value, true);
+  }
+
+  u32(value: number): void {
+    if (!Number.isInteger(value) || value < 0 || value > 0xffffffff) {
+      throw new Error(`u32 out of range: ${value}`);
+    }
+    const offset = this.#reserve(4);
+    this.#view.setUint32(offset, value, true);
+  }
+
+  i32(value: number): void {
+    if (!Number.isInteger(value) || value < -0x80000000 || value > 0x7fffffff) {
+      throw new Error(`i32 out of range: ${value}`);
+    }
+    const offset = this.#reserve(4);
+    this.#view.setInt32(offset, value, true);
+  }
+
+  i64(value: number): void {
+    if (!Number.isSafeInteger(value)) {
+      throw new Error(`i64 outside the safe-integer contract: ${value}`);
+    }
+    const offset = this.#reserve(8);
+    this.#view.setBigInt64(offset, BigInt(value), true);
+  }
+
+  f64(value: number): void {
+    const offset = this.#reserve(8);
+    this.#view.setFloat64(offset, value, true);
+  }
+
+  bool(value: boolean): void {
+    this.u8(value ? 1 : 0);
+  }
+
+  str(value: string): void {
+    const encoded = textEncoder.encode(value);
+    this.u32(encoded.length);
+    this.raw(encoded);
+  }
+
+  bytes(value: Uint8Array): void {
+    this.u32(value.length);
+    this.raw(value);
+  }
+
+  raw(value: Uint8Array): void {
+    const offset = this.#reserve(value.length);
+    this.#buffer.set(value, offset);
+  }
+
+  opt<T>(value: T | undefined, write: (value: T) => void): void {
+    if (value === undefined) {
+      this.u8(0);
+    } else {
+      this.u8(1);
+      write(value);
+    }
+  }
+
+  finish(): Uint8Array {
+    return this.#buffer.slice(0, this.#length);
+  }
+}
+
+/** Bounds-checked little-endian reader. Failures throw `DecodeError`. */
+export class ByteReader {
+  #data: Uint8Array;
+  #view: DataView;
+  #position = 0;
+
+  constructor(data: Uint8Array) {
+    this.#data = data;
+    this.#view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+  }
+
+  get remaining(): number {
+    return this.#data.length - this.#position;
+  }
+
+  #take(size: number): number {
+    if (this.remaining < size) {
+      throw new DecodeError(
+        'sync.invalid_request',
+        `truncated input: needed ${size} bytes, have ${this.remaining}`,
+      );
+    }
+    const offset = this.#position;
+    this.#position += size;
+    return offset;
+  }
+
+  u8(): number {
+    return this.#view.getUint8(this.#take(1));
+  }
+
+  u16(): number {
+    return this.#view.getUint16(this.#take(2), true);
+  }
+
+  u32(): number {
+    return this.#view.getUint32(this.#take(4), true);
+  }
+
+  i32(): number {
+    return this.#view.getInt32(this.#take(4), true);
+  }
+
+  i64(): number {
+    const value = this.#view.getBigInt64(this.#take(8), true);
+    if (value > MAX_SAFE_I64 || value < MIN_SAFE_I64) {
+      throw new DecodeError(
+        'sync.invalid_request',
+        `i64 outside the safe-integer contract: ${value}`,
+      );
+    }
+    return Number(value);
+  }
+
+  f64(): number {
+    return this.#view.getFloat64(this.#take(8), true);
+  }
+
+  bool(): boolean {
+    const byte = this.u8();
+    if (byte > 1) {
+      throw new DecodeError(
+        'sync.invalid_request',
+        `invalid bool byte 0x${byte.toString(16)}`,
+      );
+    }
+    return byte === 1;
+  }
+
+  raw(size: number): Uint8Array {
+    const offset = this.#take(size);
+    return this.#data.slice(offset, offset + size);
+  }
+
+  bytes(): Uint8Array {
+    return this.raw(this.u32());
+  }
+
+  str(): string {
+    const encoded = this.bytes();
+    try {
+      return textDecoder.decode(encoded);
+    } catch {
+      throw new DecodeError('sync.invalid_request', 'invalid UTF-8 in string');
+    }
+  }
+
+  opt<T>(read: () => T): T | undefined {
+    const presence = this.u8();
+    if (presence === 0) return undefined;
+    if (presence === 1) return read();
+    throw new DecodeError(
+      'sync.invalid_request',
+      `invalid option presence byte 0x${presence.toString(16)}`,
+    );
+  }
+
+  expectFullyConsumed(what: string): void {
+    if (this.remaining !== 0) {
+      throw new DecodeError(
+        'sync.invalid_request',
+        `trailing bytes after ${what}`,
+      );
+    }
+  }
+}
+
+/**
+ * `map` of `str` → `list(str)` (scope maps, SPEC.md Conventions).
+ * Encoders emit keys in ascending code-unit order; the reader rejects
+ * duplicate or out-of-order keys (canonical encoding).
+ */
+export function writeStringListMap(
+  writer: ByteWriter,
+  map: Readonly<Record<string, readonly string[]>>,
+): void {
+  const keys = Object.keys(map).sort();
+  writer.u32(keys.length);
+  for (const key of keys) {
+    writer.str(key);
+    const values = map[key] ?? [];
+    writer.u32(values.length);
+    for (const value of values) writer.str(value);
+  }
+}
+
+export function readStringListMap(
+  reader: ByteReader,
+): Record<string, string[]> {
+  const count = reader.u32();
+  const entries: Array<[string, string[]]> = [];
+  let previousKey: string | undefined;
+  for (let i = 0; i < count; i++) {
+    const key = reader.str();
+    if (previousKey !== undefined && key <= previousKey) {
+      throw new DecodeError(
+        'sync.invalid_request',
+        `map keys must be unique and in ascending code-unit order (saw ${JSON.stringify(key)} after ${JSON.stringify(previousKey)})`,
+      );
+    }
+    previousKey = key;
+    const valueCount = reader.u32();
+    const values: string[] = [];
+    for (let j = 0; j < valueCount; j++) values.push(reader.str());
+    entries.push([key, values]);
+  }
+  return Object.fromEntries(entries);
+}
+
+/** `map` of `str` → `str` (stored scopes on change records, SPEC.md §4.5). */
+export function writeStringMap(
+  writer: ByteWriter,
+  map: Readonly<Record<string, string>>,
+): void {
+  const keys = Object.keys(map).sort();
+  writer.u32(keys.length);
+  for (const key of keys) {
+    writer.str(key);
+    const value = map[key];
+    writer.str(value ?? '');
+  }
+}
+
+export function readStringMap(reader: ByteReader): Record<string, string> {
+  const count = reader.u32();
+  const entries: Array<[string, string]> = [];
+  let previousKey: string | undefined;
+  for (let i = 0; i < count; i++) {
+    const key = reader.str();
+    if (previousKey !== undefined && key <= previousKey) {
+      throw new DecodeError(
+        'sync.invalid_request',
+        `map keys must be unique and in ascending code-unit order (saw ${JSON.stringify(key)} after ${JSON.stringify(previousKey)})`,
+      );
+    }
+    previousKey = key;
+    entries.push([key, reader.str()]);
+  }
+  return Object.fromEntries(entries);
+}

package/src/canonical-json.ts

@@ -0,0 +1,20 @@
+/**
+ * Canonical JSON for digests (SPEC.md §11.2) — contractual across
+ * implementations: UTF-8, no insignificant whitespace, object keys sorted
+ * by code-unit, scope value lists sorted and deduplicated.
+ *
+ * Used for the scope digest (§3.5) and the `X-Syncular-Scopes` header
+ * (§5.5). Hashing itself is the host's job; this module only produces the
+ * canonical text.
+ */
+export function canonicalScopeJson(
+  scopes: Readonly<Record<string, readonly string[]>>,
+): string {
+  const keys = Object.keys(scopes).sort();
+  const parts = keys.map((key) => {
+    const values = [...new Set(scopes[key] ?? [])].sort();
+    const list = values.map((value) => JSON.stringify(value)).join(',');
+    return `${JSON.stringify(key)}:[${list}]`;
+  });
+  return `{${parts.join(',')}}`;
+}

package/src/constants.ts

@@ -0,0 +1,7 @@
+/** Protocol constants (SPEC.md §1.2, §9 are normative). */
+
+/** SSP2 envelope wire version this codec implements. */
+export const PROTOCOL_WIRE_VERSION = 1;
+
+/** Magic bytes opening every v2 sync envelope (SPEC.md §1.2). */
+export const SYNC_PACK_MAGIC = 'SSP2';

package/src/crypto.ts

@@ -0,0 +1,335 @@
+/**
+ * Client-side encryption primitives (SPEC.md §5.11).
+ *
+ * The byte-exact ciphertext envelope, the declared-type value serializer,
+ * and AES-256-GCM encrypt/decrypt over WebCrypto (a global — this keeps
+ * `@syncular/core` dependency-free). These are the codec-level pieces shared
+ * by the wire boundary: the client encrypts a configured column's plaintext
+ * value here before the row codec (§2.4) sees it as a `bytes` value, and
+ * decrypts on apply. The row codec itself never touches this file.
+ *
+ * X25519 sealed-box key wrapping (the "async encryption" utilities) lives in
+ * `@syncular/crypto` (it needs an audited curve implementation); this module
+ * is the symmetric core and the envelope both sides agree on byte-for-byte.
+ */
+import { ByteReader, ByteWriter } from './bytes';
+
+/** The pre-flip application type of an encrypted column (SPEC.md §5.11). */
+export type DeclaredType =
+  | 'string'
+  | 'integer'
+  | 'float'
+  | 'boolean'
+  | 'json'
+  | 'blob_ref'
+  | 'bytes';
+
+/** A non-null row value, per the declared type. `crdt` is never encrypted. */
+export type PlainValue = string | number | boolean | Uint8Array;
+
+/** Envelope version byte (SPEC.md §5.11). */
+export const ENVELOPE_VERSION = 0x01;
+
+/** AES-GCM nonce length (96-bit, the GCM standard). */
+export const NONCE_LENGTH = 12;
+
+/** Symmetric key length: AES-256. */
+export const KEY_LENGTH = 32;
+
+/**
+ * Client-local decrypt failure (SPEC.md §5.11, §10.3). Never on the wire —
+ * the `client.` family is client-only. Raised at the apply seam for an
+ * unknown envelope version, unknown `keyId`, GCM auth failure (wrong key), a
+ * malformed envelope, or a post-decrypt value-parse failure. Not retryable.
+ */
+export class DecryptError extends Error {
+  override readonly name = 'DecryptError';
+  readonly code = 'client.decrypt_failed';
+  readonly retryable = false;
+
+  constructor(message: string) {
+    super(message);
+  }
+}
+
+/**
+ * Injectable nonce source (SPEC.md §5.11 nonce discipline). Production uses
+ * {@link secureRandomNonce}; crypto golden vectors inject a fixed nonce. A
+ * fixed nonce MUST NOT be reachable from a production encode path.
+ */
+export type NonceSource = () => Uint8Array;
+
+export function secureRandomNonce(): Uint8Array {
+  const nonce = new Uint8Array(NONCE_LENGTH);
+  crypto.getRandomValues(nonce);
+  return nonce;
+}
+
+// ---------------------------------------------------------------------------
+// Value serializer — declared type ⇄ canonical plaintext bytes (§5.11)
+// ---------------------------------------------------------------------------
+
+const textEncoder = new TextEncoder();
+const textDecoder = new TextDecoder('utf-8', { fatal: true });
+
+/**
+ * Serialize a declared-type value to the canonical plaintext bytes fed to
+ * GCM (SPEC.md §5.11 value serializer). Not a re-run of the row codec — this
+ * is the self-describing per-`declaredType` encoding both cores agree on.
+ */
+export function serializePlain(
+  declaredType: DeclaredType,
+  value: PlainValue,
+): Uint8Array {
+  switch (declaredType) {
+    case 'string':
+    case 'json':
+    case 'blob_ref':
+      if (typeof value !== 'string') {
+        throw new Error(`encrypted ${declaredType} column requires a string`);
+      }
+      return textEncoder.encode(value);
+    case 'integer': {
+      if (typeof value !== 'number' || !Number.isSafeInteger(value)) {
+        throw new Error('encrypted integer column requires a safe integer');
+      }
+      const out = new Uint8Array(8);
+      new DataView(out.buffer).setBigInt64(0, BigInt(value), true);
+      return out;
+    }
+    case 'float': {
+      if (typeof value !== 'number') {
+        throw new Error('encrypted float column requires a number');
+      }
+      const out = new Uint8Array(8);
+      new DataView(out.buffer).setFloat64(0, value, true);
+      return out;
+    }
+    case 'boolean':
+      if (typeof value !== 'boolean') {
+        throw new Error('encrypted boolean column requires a boolean');
+      }
+      return new Uint8Array([value ? 1 : 0]);
+    case 'bytes':
+      if (!(value instanceof Uint8Array)) {
+        throw new Error('encrypted bytes column requires a Uint8Array');
+      }
+      return value;
+  }
+}
+
+/**
+ * Parse the decrypted plaintext bytes back to a declared-type value (SPEC.md
+ * §5.11). A `json`/`blob_ref` value is re-validated as the row codec would
+ * (§2.4); any parse failure is a decrypt failure.
+ */
+export function deserializePlain(
+  declaredType: DeclaredType,
+  bytes: Uint8Array,
+): PlainValue {
+  switch (declaredType) {
+    case 'string':
+    case 'json':
+    case 'blob_ref': {
+      let text: string;
+      try {
+        text = textDecoder.decode(bytes);
+      } catch {
+        throw new DecryptError(
+          `decrypted ${declaredType} value is not valid UTF-8`,
+        );
+      }
+      if (declaredType === 'json') {
+        try {
+          JSON.parse(text);
+        } catch {
+          throw new DecryptError('decrypted json value does not parse');
+        }
+      }
+      return text;
+    }
+    case 'integer': {
+      if (bytes.length !== 8) {
+        throw new DecryptError('decrypted integer must be 8 bytes');
+      }
+      const big = new DataView(bytes.buffer, bytes.byteOffset, 8).getBigInt64(
+        0,
+        true,
+      );
+      const num = Number(big);
+      if (!Number.isSafeInteger(num)) {
+        throw new DecryptError('decrypted integer outside safe range');
+      }
+      return num;
+    }
+    case 'float': {
+      if (bytes.length !== 8) {
+        throw new DecryptError('decrypted float must be 8 bytes');
+      }
+      return new DataView(bytes.buffer, bytes.byteOffset, 8).getFloat64(
+        0,
+        true,
+      );
+    }
+    case 'boolean': {
+      if (bytes.length !== 1 || (bytes[0] !== 0 && bytes[0] !== 1)) {
+        throw new DecryptError('decrypted boolean must be one 0x00/0x01 byte');
+      }
+      return bytes[0] === 1;
+    }
+    case 'bytes':
+      return bytes;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Envelope — 0x01 | keyIdLen(u8) | keyId | nonce(12) | ct+tag  (§5.11)
+// ---------------------------------------------------------------------------
+
+export interface Envelope {
+  readonly keyId: string;
+  readonly nonce: Uint8Array;
+  /** AES-256-GCM ciphertext with the 16-byte tag appended. */
+  readonly ciphertext: Uint8Array;
+}
+
+export function encodeEnvelope(envelope: Envelope): Uint8Array {
+  const keyIdBytes = textEncoder.encode(envelope.keyId);
+  if (keyIdBytes.length > 0xff) {
+    throw new Error('keyId exceeds 255 UTF-8 bytes');
+  }
+  if (envelope.nonce.length !== NONCE_LENGTH) {
+    throw new Error(`nonce must be ${NONCE_LENGTH} bytes`);
+  }
+  const writer = new ByteWriter();
+  writer.u8(ENVELOPE_VERSION);
+  writer.u8(keyIdBytes.length);
+  writer.raw(keyIdBytes);
+  writer.raw(envelope.nonce);
+  writer.raw(envelope.ciphertext);
+  return writer.finish();
+}
+
+export function decodeEnvelope(bytes: Uint8Array): Envelope {
+  const reader = new ByteReader(bytes);
+  let version: number;
+  let keyIdLen: number;
+  try {
+    version = reader.u8();
+    keyIdLen = reader.u8();
+  } catch {
+    throw new DecryptError('encrypted value: envelope truncated');
+  }
+  if (version !== ENVELOPE_VERSION) {
+    throw new DecryptError(
+      `encrypted value: unknown envelope version 0x${version.toString(16)}`,
+    );
+  }
+  let keyIdBytes: Uint8Array;
+  let nonce: Uint8Array;
+  try {
+    keyIdBytes = reader.raw(keyIdLen);
+    nonce = reader.raw(NONCE_LENGTH);
+  } catch {
+    throw new DecryptError('encrypted value: envelope truncated');
+  }
+  // The remaining bytes are ciphertext+tag; must be at least the 16-byte tag.
+  const ciphertext = bytes.subarray(2 + keyIdLen + NONCE_LENGTH);
+  if (ciphertext.length < 16) {
+    throw new DecryptError('encrypted value: ciphertext shorter than GCM tag');
+  }
+  let keyId: string;
+  try {
+    keyId = textDecoder.decode(keyIdBytes);
+  } catch {
+    throw new DecryptError('encrypted value: keyId is not valid UTF-8');
+  }
+  return { keyId, nonce, ciphertext: ciphertext.slice() };
+}
+
+// ---------------------------------------------------------------------------
+// AES-256-GCM over WebCrypto
+// ---------------------------------------------------------------------------
+
+/**
+ * Copy into a fresh `ArrayBuffer`-backed view. WebCrypto's `BufferSource`
+ * type rejects a `Uint8Array<ArrayBufferLike>` (it could be SharedArrayBuffer);
+ * a plain copy is unambiguously `ArrayBuffer`-backed.
+ */
+function toBuffer(bytes: Uint8Array): ArrayBuffer {
+  const copy = new Uint8Array(bytes.length);
+  copy.set(bytes);
+  return copy.buffer;
+}
+
+async function importAesKey(key: Uint8Array): Promise<CryptoKey> {
+  if (key.length !== KEY_LENGTH) {
+    throw new Error(`AES-256-GCM key must be ${KEY_LENGTH} bytes`);
+  }
+  return crypto.subtle.importKey('raw', toBuffer(key), 'AES-GCM', false, [
+    'encrypt',
+    'decrypt',
+  ]);
+}
+
+/**
+ * Encrypt one declared-type value into a §5.11 envelope. `nonceSource`
+ * defaults to a secure RNG; vectors inject a fixed nonce.
+ */
+export async function encryptValue(
+  declaredType: DeclaredType,
+  value: PlainValue,
+  keyId: string,
+  key: Uint8Array,
+  nonceSource: NonceSource = secureRandomNonce,
+): Promise<Uint8Array> {
+  const plaintext = serializePlain(declaredType, value);
+  const nonce = nonceSource();
+  if (nonce.length !== NONCE_LENGTH) {
+    throw new Error(`nonce source must yield ${NONCE_LENGTH} bytes`);
+  }
+  const cryptoKey = await importAesKey(key);
+  const ct = new Uint8Array(
+    await crypto.subtle.encrypt(
+      { name: 'AES-GCM', iv: toBuffer(nonce), tagLength: 128 },
+      cryptoKey,
+      toBuffer(plaintext),
+    ),
+  );
+  return encodeEnvelope({ keyId, nonce, ciphertext: ct });
+}
+
+/**
+ * Decrypt a §5.11 envelope back to a declared-type value. `keyProvider`
+ * resolves the envelope's `keyId` to key bytes; a missing key or GCM tag
+ * mismatch is {@link DecryptError} (`client.decrypt_failed`).
+ */
+export async function decryptValue(
+  declaredType: DeclaredType,
+  envelopeBytes: Uint8Array,
+  keyProvider: (keyId: string) => Uint8Array | undefined,
+): Promise<PlainValue> {
+  const envelope = decodeEnvelope(envelopeBytes);
+  const key = keyProvider(envelope.keyId);
+  if (key === undefined) {
+    throw new DecryptError(
+      `no key for keyId ${JSON.stringify(envelope.keyId)}`,
+    );
+  }
+  const cryptoKey = await importAesKey(key);
+  let plaintext: Uint8Array;
+  try {
+    plaintext = new Uint8Array(
+      await crypto.subtle.decrypt(
+        { name: 'AES-GCM', iv: toBuffer(envelope.nonce), tagLength: 128 },
+        cryptoKey,
+        toBuffer(envelope.ciphertext),
+      ),
+    );
+  } catch {
+    throw new DecryptError(
+      `GCM authentication failed for keyId ${JSON.stringify(envelope.keyId)} (wrong key or corrupt ciphertext)`,
+    );
+  }
+  return deserializePlain(declaredType, plaintext);
+}

package/src/errors.ts

@@ -0,0 +1,18 @@
+/**
+ * Named decode errors (SPEC.md Conventions + §10).
+ *
+ * Every decode failure in the reference codec throws a `DecodeError` whose
+ * `code` is a stable identifier from the SPEC.md §10 catalog (structural
+ * failures use `sync.invalid_request`; frame-specific rules use their named
+ * code, e.g. `sync.empty_commit`). Golden vector negative cases assert on
+ * `code`, never on `message`.
+ */
+export class DecodeError extends Error {
+  override readonly name = 'DecodeError';
+  readonly code: string;
+
+  constructor(code: string, message: string) {
+    super(message);
+    this.code = code;
+  }
+}