@syncular/core 0.1.3 → 0.2.0

package/dist/crypto.js

@@ -0,0 +1,251 @@
+/**
+ * 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.js';
+/** 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 {
+    name = 'DecryptError';
+    code = 'client.decrypt_failed';
+    retryable = false;
+    constructor(message) {
+        super(message);
+    }
+}
+export function secureRandomNonce() {
+    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, value) {
+    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, bytes) {
+    switch (declaredType) {
+        case 'string':
+        case 'json':
+        case 'blob_ref': {
+            let text;
+            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;
+    }
+}
+export function encodeEnvelope(envelope) {
+    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) {
+    const reader = new ByteReader(bytes);
+    let version;
+    let keyIdLen;
+    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;
+    let nonce;
+    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;
+    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) {
+    const copy = new Uint8Array(bytes.length);
+    copy.set(bytes);
+    return copy.buffer;
+}
+async function importAesKey(key) {
+    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, value, keyId, key, nonceSource = secureRandomNonce) {
+    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, envelopeBytes, keyProvider) {
+    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;
+    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/dist/errors.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 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 declare class DecodeError extends Error {
+    readonly name = "DecodeError";
+    readonly code: string;
+    constructor(code: string, message: string);
+}

package/dist/errors.js

@@ -0,0 +1,17 @@
+/**
+ * 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 {
+    name = 'DecodeError';
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}

package/dist/frames.d.ts

@@ -0,0 +1,24 @@
+/** Frame type registry for wire version 1 (SPEC.md §1.2). */
+export declare const FrameType: {
+    readonly END: 0;
+    readonly REQ_HEADER: 1;
+    readonly PUSH_COMMIT: 2;
+    readonly PULL_HEADER: 3;
+    readonly SUBSCRIPTION: 4;
+    readonly RESP_HEADER: 16;
+    readonly PUSH_RESULT: 17;
+    readonly SUB_START: 18;
+    readonly COMMIT: 19;
+    readonly SEGMENT_REF: 20;
+    readonly SEGMENT_INLINE: 21;
+    readonly SUB_END: 22;
+    readonly LEASE: 25;
+    readonly ERROR: 31;
+};
+export type FrameTypeName = keyof typeof FrameType;
+/** Known request frame types (excluding END). */
+export declare const REQUEST_FRAME_TYPES: ReadonlySet<number>;
+/** Known response frame types (excluding END). */
+export declare const RESPONSE_FRAME_TYPES: ReadonlySet<number>;
+/** Every frame type with a defined layout in wire version 1. */
+export declare const KNOWN_FRAME_TYPES: ReadonlySet<number>;

package/dist/frames.js

@@ -0,0 +1,42 @@
+/** Frame type registry for wire version 1 (SPEC.md §1.2). */
+export const FrameType = {
+    END: 0x00,
+    REQ_HEADER: 0x01,
+    PUSH_COMMIT: 0x02,
+    PULL_HEADER: 0x03,
+    SUBSCRIPTION: 0x04,
+    RESP_HEADER: 0x10,
+    PUSH_RESULT: 0x11,
+    SUB_START: 0x12,
+    COMMIT: 0x13,
+    SEGMENT_REF: 0x14,
+    SEGMENT_INLINE: 0x15,
+    SUB_END: 0x16,
+    LEASE: 0x19,
+    ERROR: 0x1f,
+};
+/** Known request frame types (excluding END). */
+export const REQUEST_FRAME_TYPES = new Set([
+    FrameType.REQ_HEADER,
+    FrameType.PUSH_COMMIT,
+    FrameType.PULL_HEADER,
+    FrameType.SUBSCRIPTION,
+]);
+/** Known response frame types (excluding END). */
+export const RESPONSE_FRAME_TYPES = new Set([
+    FrameType.RESP_HEADER,
+    FrameType.PUSH_RESULT,
+    FrameType.SUB_START,
+    FrameType.COMMIT,
+    FrameType.SEGMENT_REF,
+    FrameType.SEGMENT_INLINE,
+    FrameType.SUB_END,
+    FrameType.LEASE,
+    FrameType.ERROR,
+]);
+/** Every frame type with a defined layout in wire version 1. */
+export const KNOWN_FRAME_TYPES = new Set([
+    FrameType.END,
+    ...REQUEST_FRAME_TYPES,
+    ...RESPONSE_FRAME_TYPES,
+]);

package/dist/index.d.ts

@@ -1,29 +1,21 @@
 /**
- * @syncular/core - Shared types and utilities for sync infrastructure
+ * @syncular/core — reference SSP2 codec (SPEC.md is normative).
  *
- * This package contains:
- * - Protocol types (commit-log + subscriptions)
- * - Pure conflict detection and merge utilities
- * - Logging utilities
- * - Data transformation hooks (optional)
- * - Blob types for media/binary handling
- * - Zod schemas for runtime validation and OpenAPI
+ * Dependency-free: primitives (Conventions), envelope + framing (§1),
+ * schema-IR row codec (§2.4), SSG2 rows segments (§5.2), message codecs
+ * (§1.5/§1.6), realtime control messages (§8), the §11 canonical JSON
+ * debug rendering, and §11.2 canonical JSON for digests.
  */
-export * from './blobs';
-export * from './column-codecs';
-export * from './conflict';
-export * from './database';
-export * from './dialect';
-export * from './error-responses';
-export * from './kysely-column-codecs';
-export * from './logger';
-export * from './proxy';
-export * from './schemas';
-export * from './scopes';
-export * from './snapshot-chunks';
-export * from './sync-packs';
-export * from './telemetry';
-export * from './transforms';
-export * from './types';
-export * from './utils';
-//# sourceMappingURL=index.d.ts.map
+export * from './blob-ref.js';
+export * from './bytes.js';
+export * from './canonical-json.js';
+export * from './constants.js';
+export * from './crypto.js';
+export * from './errors.js';
+export * from './frames.js';
+export * from './message.js';
+export * from './realtime.js';
+export * from './render.js';
+export * from './row-codec.js';
+export * from './segment.js';
+export * from './stream.js';

package/dist/index.js

@@ -1,46 +1,21 @@
 /**
- * @syncular/core - Shared types and utilities for sync infrastructure
+ * @syncular/core — reference SSP2 codec (SPEC.md is normative).
  *
- * This package contains:
- * - Protocol types (commit-log + subscriptions)
- * - Pure conflict detection and merge utilities
- * - Logging utilities
- * - Data transformation hooks (optional)
- * - Blob types for media/binary handling
- * - Zod schemas for runtime validation and OpenAPI
+ * Dependency-free: primitives (Conventions), envelope + framing (§1),
+ * schema-IR row codec (§2.4), SSG2 rows segments (§5.2), message codecs
+ * (§1.5/§1.6), realtime control messages (§8), the §11 canonical JSON
+ * debug rendering, and §11.2 canonical JSON for digests.
  */
-// Blob transport/storage types and utilities (protocol types come from ./schemas)
-export * from './blobs.js';
-// Column-level codecs shared by typegen and runtime paths
-export * from './column-codecs.js';
-// Conflict detection utilities
-export * from './conflict.js';
-// Database utilities
-export * from './database.js';
-// Database dialect descriptors
-export * from './dialect.js';
-// Public error response envelopes
-export * from './error-responses.js';
-// Kysely plugin for applying column codecs in generic queries
-export * from './kysely-column-codecs.js';
-// Logging utilities
-export * from './logger.js';
-// Proxy protocol types
-export * from './proxy/index.js';
-// Schemas (Zod)
-export * from './schemas/index.js';
-// Scope types, patterns, and utilities
-export * from './scopes/index.js';
-// Snapshot chunk encoding helpers
-export * from './snapshot-chunks.js';
-// Sync response pack encoding helpers
-export * from './sync-packs.js';
-// Telemetry abstraction
-export * from './telemetry.js';
-// Data transformation hooks
-export * from './transforms.js';
-// Transport and conflict types (protocol types come from ./schemas)
-export * from './types.js';
-// Shared runtime utilities
-export * from './utils/index.js';
-//# sourceMappingURL=index.js.map
+export * from './blob-ref.js';
+export * from './bytes.js';
+export * from './canonical-json.js';
+export * from './constants.js';
+export * from './crypto.js';
+export * from './errors.js';
+export * from './frames.js';
+export * from './message.js';
+export * from './realtime.js';
+export * from './render.js';
+export * from './row-codec.js';
+export * from './segment.js';
+export * from './stream.js';

package/dist/message.d.ts

@@ -0,0 +1,157 @@
+export type ScopeMap = Record<string, string[]>;
+export interface ReqHeaderFrame {
+    type: 'REQ_HEADER';
+    clientId: string;
+    schemaVersion: number;
+}
+export interface PushOperation {
+    table: string;
+    rowId: string;
+    op: 'upsert' | 'delete';
+    /** Optimistic-concurrency token (§6.2); absent = last-write-wins. */
+    baseVersion?: number;
+    /** Generated-row-codec bytes; present iff `op` is `upsert` (§6.1). */
+    payload?: Uint8Array;
+}
+export interface PushCommitFrame {
+    type: 'PUSH_COMMIT';
+    clientCommitId: string;
+    operations: PushOperation[];
+}
+export interface PullHeaderFrame {
+    type: 'PULL_HEADER';
+    limitCommits: number;
+    limitSnapshotRows: number;
+    maxSnapshotPages: number;
+    /** Bitmask (§4.2): bit 0 inline rows, 1 external rows, 2 sqlite, 3 signed URLs. */
+    accept: number;
+}
+export interface SubscriptionFrame {
+    type: 'SUBSCRIPTION';
+    id: string;
+    table: string;
+    scopes: ScopeMap;
+    /** Host-opaque JSON document, preserved verbatim. */
+    params?: string;
+    cursor: number;
+    /** Opaque resume token JSON, round-tripped byte-for-byte (§4.7). */
+    bootstrapState?: string;
+}
+export interface UnknownFrame {
+    type: 'UNKNOWN';
+    frameType: number;
+    payload: Uint8Array;
+}
+export type RequestFrame = ReqHeaderFrame | PushCommitFrame | PullHeaderFrame | SubscriptionFrame | UnknownFrame;
+export interface RespHeaderFrame {
+    type: 'RESP_HEADER';
+    requiredSchemaVersion?: number;
+    latestSchemaVersion?: number;
+}
+/** §7.3.2: a server-issued auth lease delivered to the client (opaque). */
+export interface LeaseFrame {
+    type: 'LEASE';
+    leaseId: string;
+    expiresAtMs: number;
+}
+export type PushOperationResult = {
+    opIndex: number;
+    status: 'applied';
+} | {
+    opIndex: number;
+    status: 'conflict';
+    code: string;
+    message: string;
+    serverVersion: number;
+    serverRow: Uint8Array;
+} | {
+    opIndex: number;
+    status: 'error';
+    code: string;
+    message: string;
+    retryable: boolean;
+};
+export interface PushResultFrame {
+    type: 'PUSH_RESULT';
+    clientCommitId: string;
+    status: 'applied' | 'cached' | 'rejected';
+    /** Present iff `status` is `applied` or `cached` (§6.3). */
+    commitSeq?: number;
+    results: PushOperationResult[];
+}
+export interface SubStartFrame {
+    type: 'SUB_START';
+    id: string;
+    status: 'active' | 'revoked' | 'reset';
+    reasonCode: string;
+    effectiveScopes: ScopeMap;
+    bootstrap: boolean;
+}
+export interface CommitChange {
+    tableIndex: number;
+    rowId: string;
+    op: 'upsert' | 'delete';
+    /** Present iff `op` is `upsert` (§4.5). */
+    rowVersion?: number;
+    scopes: Record<string, string>;
+    /** Generated-row-codec bytes; present iff `op` is `upsert` (§4.5). */
+    row?: Uint8Array;
+}
+export interface CommitFrame {
+    type: 'COMMIT';
+    commitSeq: number;
+    createdAtMs: number;
+    actorId: string;
+    tables: string[];
+    changes: CommitChange[];
+}
+export interface SegmentRefFrame {
+    type: 'SEGMENT_REF';
+    segmentId: string;
+    mediaType: 'rows' | 'sqlite';
+    table: string;
+    byteLength: number;
+    rowCount: number;
+    asOfCommitSeq: number;
+    scopeDigest: string;
+    rowCursor?: string;
+    nextRowCursor?: string;
+    url?: string;
+    /** Present iff `url` is (§5.4). */
+    urlExpiresAtMs?: number;
+}
+export interface SegmentInlineFrame {
+    type: 'SEGMENT_INLINE';
+    /** One complete SSG2 rows segment, including magic (§5.7). */
+    payload: Uint8Array;
+}
+export interface SubEndFrame {
+    type: 'SUB_END';
+    nextCursor: number;
+    /** Present iff the bootstrap is incomplete (§4.4). */
+    bootstrapState?: string;
+}
+export interface ErrorFrame {
+    type: 'ERROR';
+    code: string;
+    message: string;
+    category: string;
+    retryable: boolean;
+    recommendedAction: string;
+    details?: string;
+}
+export type ResponseFrame = RespHeaderFrame | LeaseFrame | PushResultFrame | SubStartFrame | CommitFrame | SegmentRefFrame | SegmentInlineFrame | SubEndFrame | ErrorFrame | UnknownFrame;
+export interface RequestMessage {
+    wireVersion: number;
+    msgKind: 'request';
+    frames: RequestFrame[];
+}
+export interface ResponseMessage {
+    wireVersion: number;
+    msgKind: 'response';
+    frames: ResponseFrame[];
+}
+export type SyncMessage = RequestMessage | ResponseMessage;
+export declare function validateFrameSequence(message: SyncMessage): void;
+export declare function encodeMessage(message: SyncMessage): Uint8Array;
+export declare function decodeMessage(bytes: Uint8Array): SyncMessage;