@syncular/core 0.1.2 → 0.2.0

package/README.md

@@ -1,24 +1,10 @@
 # @syncular/core
 
-Core protocol types, schemas, and shared utilities for Syncular (scopes, commit-log types, telemetry, blob types, etc.).
+Core protocol types and shared utilities for the Syncular sync framework.
 
-Most apps won't depend on this directly. It is the shared foundation used by `@syncular/client`, `@syncular/server`, and the transports.
+Part of [Syncular](https://syncular.dev) — an offline-first sync framework.
+See the [Syncular repository](https://github.com/syncular/syncular) for docs.
 
-## Install
-
-```bash
-npm install @syncular/core
-```
-
-## Documentation
-
-- Overview: https://syncular.dev/docs/introduction/what-is-syncular
-- Architecture (commit log, push/pull, snapshots): https://syncular.dev/docs/introduction/architecture
-
-## Links
-
-- GitHub: https://github.com/syncular/syncular
-- Issues: https://github.com/syncular/syncular/issues
-
-> Status: Alpha. APIs and storage layouts may change between releases.
+## License
 
+Apache-2.0

package/dist/blob-ref.d.ts

@@ -0,0 +1,21 @@
+export interface BlobRef {
+    /** `"sha256:" + lowercase-hex SHA-256` of the blob bytes (§5.9.1). */
+    readonly blobId: string;
+    /** Non-negative uncompressed size within the i64 safe-integer contract. */
+    readonly byteLength: number;
+    /** Advisory MIME type; never parsed or trusted by the server. */
+    readonly mediaType?: string;
+    /** Advisory display filename. */
+    readonly name?: string;
+}
+/**
+ * Parse and validate a raw `blob_ref` string against the §5.9.1 shape. A
+ * failure is a row-codec decode error (`sync.invalid_request`), the same
+ * class as the tag-5 json parse failure — so codec and §11 rendering can
+ * never disagree.
+ */
+export declare function parseBlobRef(raw: string): BlobRef;
+/** Serialize a BlobRef to its canonical string form (§5.9.1 key order). */
+export declare function serializeBlobRef(ref: BlobRef): string;
+/** True iff `raw` is a valid canonical BlobRef document (no throw). */
+export declare function isBlobRef(raw: string): boolean;

package/dist/blob-ref.js

@@ -0,0 +1,97 @@
+/**
+ * Canonical BlobRef documents (SPEC.md §5.9.1) — the value carried by a
+ * `blob_ref` column (§2.4 tag 7).
+ *
+ * A `blob_ref` value is a `str` holding a JSON document with a pinned shape
+ * and pinned key order: `blobId` (content address), `byteLength`, then the
+ * optional `mediaType` and `name`. On the wire and in the codec it is
+ * byte-for-byte a `str`, validated at decode exactly like `json` (tag 5)
+ * plus the shape check below; the raw string is preserved verbatim for
+ * re-encoding. Nothing here re-serializes a decoded value — round-trip
+ * fidelity is the same rule the `json` tag obeys.
+ */
+import { DecodeError } from './errors.js';
+/** The content-address prefix, identical in form to `segmentId` (§5.1). */
+const BLOB_ID_RE = /^sha256:[0-9a-f]{64}$/;
+/** Canonical key order (§5.9.1): blobId, byteLength, mediaType, name. */
+const CANONICAL_KEYS = [
+    'blobId',
+    'byteLength',
+    'mediaType',
+    'name',
+];
+/**
+ * Parse and validate a raw `blob_ref` string against the §5.9.1 shape. A
+ * failure is a row-codec decode error (`sync.invalid_request`), the same
+ * class as the tag-5 json parse failure — so codec and §11 rendering can
+ * never disagree.
+ */
+export function parseBlobRef(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new DecodeError('sync.invalid_request', 'blob_ref value does not parse as a JSON document (§5.9.1)');
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new DecodeError('sync.invalid_request', 'blob_ref value must be a JSON object (§5.9.1)');
+    }
+    const obj = parsed;
+    for (const key of Object.keys(obj)) {
+        if (!CANONICAL_KEYS.includes(key)) {
+            throw new DecodeError('sync.invalid_request', `blob_ref has unknown key ${JSON.stringify(key)} (§5.9.1)`);
+        }
+    }
+    const { blobId, byteLength, mediaType, name } = obj;
+    if (typeof blobId !== 'string' || !BLOB_ID_RE.test(blobId)) {
+        throw new DecodeError('sync.invalid_request', 'blob_ref.blobId must be "sha256:<64 hex>" (§5.9.1)');
+    }
+    if (typeof byteLength !== 'number' ||
+        !Number.isSafeInteger(byteLength) ||
+        byteLength < 0) {
+        throw new DecodeError('sync.invalid_request', 'blob_ref.byteLength must be a non-negative safe integer (§5.9.1)');
+    }
+    if (mediaType !== undefined && typeof mediaType !== 'string') {
+        throw new DecodeError('sync.invalid_request', 'blob_ref.mediaType must be a string when present (§5.9.1)');
+    }
+    if (name !== undefined && typeof name !== 'string') {
+        throw new DecodeError('sync.invalid_request', 'blob_ref.name must be a string when present (§5.9.1)');
+    }
+    // Canonical key order: the raw string's keys, in appearance order, must be
+    // a prefix-consistent subsequence of CANONICAL_KEYS (present keys in the
+    // pinned order, absent keys omitted).
+    const presentInOrder = Object.keys(obj);
+    const expectedOrder = CANONICAL_KEYS.filter((k) => Object.hasOwn(obj, k));
+    if (presentInOrder.join(',') !== expectedOrder.join(',')) {
+        throw new DecodeError('sync.invalid_request', 'blob_ref keys are not in canonical order (§5.9.1)');
+    }
+    return {
+        blobId,
+        byteLength,
+        ...(mediaType !== undefined ? { mediaType } : {}),
+        ...(name !== undefined ? { name } : {}),
+    };
+}
+/** Serialize a BlobRef to its canonical string form (§5.9.1 key order). */
+export function serializeBlobRef(ref) {
+    const obj = {
+        blobId: ref.blobId,
+        byteLength: ref.byteLength,
+    };
+    if (ref.mediaType !== undefined)
+        obj.mediaType = ref.mediaType;
+    if (ref.name !== undefined)
+        obj.name = ref.name;
+    return JSON.stringify(obj);
+}
+/** True iff `raw` is a valid canonical BlobRef document (no throw). */
+export function isBlobRef(raw) {
+    try {
+        parseBlobRef(raw);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/bytes.d.ts

@@ -0,0 +1,45 @@
+export declare function utf8Encode(value: string): Uint8Array;
+/** Growable little-endian byte sink. Encoder misuse throws plain `Error`. */
+export declare class ByteWriter {
+    #private;
+    u8(value: number): void;
+    u16(value: number): void;
+    u32(value: number): void;
+    i32(value: number): void;
+    i64(value: number): void;
+    f64(value: number): void;
+    bool(value: boolean): void;
+    str(value: string): void;
+    bytes(value: Uint8Array): void;
+    raw(value: Uint8Array): void;
+    opt<T>(value: T | undefined, write: (value: T) => void): void;
+    finish(): Uint8Array;
+}
+/** Bounds-checked little-endian reader. Failures throw `DecodeError`. */
+export declare class ByteReader {
+    #private;
+    constructor(data: Uint8Array);
+    get remaining(): number;
+    u8(): number;
+    u16(): number;
+    u32(): number;
+    i32(): number;
+    i64(): number;
+    f64(): number;
+    bool(): boolean;
+    raw(size: number): Uint8Array;
+    bytes(): Uint8Array;
+    str(): string;
+    opt<T>(read: () => T): T | undefined;
+    expectFullyConsumed(what: string): void;
+}
+/**
+ * `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 declare function writeStringListMap(writer: ByteWriter, map: Readonly<Record<string, readonly string[]>>): void;
+export declare function readStringListMap(reader: ByteReader): Record<string, string[]>;
+/** `map` of `str` → `str` (stored scopes on change records, SPEC.md §4.5). */
+export declare function writeStringMap(writer: ByteWriter, map: Readonly<Record<string, string>>): void;
+export declare function readStringMap(reader: ByteReader): Record<string, string>;

package/dist/bytes.js

@@ -0,0 +1,242 @@
+/**
+ * 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.js';
+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) {
+    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) {
+        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) {
+        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) {
+        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) {
+        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) {
+        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) {
+        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) {
+        const offset = this.#reserve(8);
+        this.#view.setFloat64(offset, value, true);
+    }
+    bool(value) {
+        this.u8(value ? 1 : 0);
+    }
+    str(value) {
+        const encoded = textEncoder.encode(value);
+        this.u32(encoded.length);
+        this.raw(encoded);
+    }
+    bytes(value) {
+        this.u32(value.length);
+        this.raw(value);
+    }
+    raw(value) {
+        const offset = this.#reserve(value.length);
+        this.#buffer.set(value, offset);
+    }
+    opt(value, write) {
+        if (value === undefined) {
+            this.u8(0);
+        }
+        else {
+            this.u8(1);
+            write(value);
+        }
+    }
+    finish() {
+        return this.#buffer.slice(0, this.#length);
+    }
+}
+/** Bounds-checked little-endian reader. Failures throw `DecodeError`. */
+export class ByteReader {
+    #data;
+    #view;
+    #position = 0;
+    constructor(data) {
+        this.#data = data;
+        this.#view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+    }
+    get remaining() {
+        return this.#data.length - this.#position;
+    }
+    #take(size) {
+        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() {
+        return this.#view.getUint8(this.#take(1));
+    }
+    u16() {
+        return this.#view.getUint16(this.#take(2), true);
+    }
+    u32() {
+        return this.#view.getUint32(this.#take(4), true);
+    }
+    i32() {
+        return this.#view.getInt32(this.#take(4), true);
+    }
+    i64() {
+        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() {
+        return this.#view.getFloat64(this.#take(8), true);
+    }
+    bool() {
+        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) {
+        const offset = this.#take(size);
+        return this.#data.slice(offset, offset + size);
+    }
+    bytes() {
+        return this.raw(this.u32());
+    }
+    str() {
+        const encoded = this.bytes();
+        try {
+            return textDecoder.decode(encoded);
+        }
+        catch {
+            throw new DecodeError('sync.invalid_request', 'invalid UTF-8 in string');
+        }
+    }
+    opt(read) {
+        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) {
+        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, map) {
+    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) {
+    const count = reader.u32();
+    const entries = [];
+    let previousKey;
+    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 = [];
+        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, map) {
+    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) {
+    const count = reader.u32();
+    const entries = [];
+    let previousKey;
+    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/dist/canonical-json.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 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 declare function canonicalScopeJson(scopes: Readonly<Record<string, readonly string[]>>): string;

package/dist/canonical-json.js

@@ -0,0 +1,18 @@
+/**
+ * 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) {
+    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/dist/constants.d.ts

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

package/dist/constants.js

@@ -0,0 +1,5 @@
+/** 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/dist/crypto.d.ts

@@ -0,0 +1,60 @@
+/** 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 declare const ENVELOPE_VERSION = 1;
+/** AES-GCM nonce length (96-bit, the GCM standard). */
+export declare const NONCE_LENGTH = 12;
+/** Symmetric key length: AES-256. */
+export declare 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 declare class DecryptError extends Error {
+    readonly name = "DecryptError";
+    readonly code = "client.decrypt_failed";
+    readonly retryable = false;
+    constructor(message: string);
+}
+/**
+ * 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 declare function secureRandomNonce(): Uint8Array;
+/**
+ * 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 declare function serializePlain(declaredType: DeclaredType, value: PlainValue): Uint8Array;
+/**
+ * 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 declare function deserializePlain(declaredType: DeclaredType, bytes: Uint8Array): PlainValue;
+export interface Envelope {
+    readonly keyId: string;
+    readonly nonce: Uint8Array;
+    /** AES-256-GCM ciphertext with the 16-byte tag appended. */
+    readonly ciphertext: Uint8Array;
+}
+export declare function encodeEnvelope(envelope: Envelope): Uint8Array;
+export declare function decodeEnvelope(bytes: Uint8Array): Envelope;
+/**
+ * Encrypt one declared-type value into a §5.11 envelope. `nonceSource`
+ * defaults to a secure RNG; vectors inject a fixed nonce.
+ */
+export declare function encryptValue(declaredType: DeclaredType, value: PlainValue, keyId: string, key: Uint8Array, nonceSource?: NonceSource): Promise<Uint8Array>;
+/**
+ * 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 declare function decryptValue(declaredType: DeclaredType, envelopeBytes: Uint8Array, keyProvider: (keyId: string) => Uint8Array | undefined): Promise<PlainValue>;