@lix-js/sdk 0.16.0 → 0.17.0

package/dist/worker/protocol.js

@@ -1,19 +1,20 @@
-export function serializeWorkerError(error) {
+export function serializeWorkerError(error, depth = 0) {
     if (!(error instanceof Error)) {
-        return { name: "Error", message: String(error) };
+        return { name: "Error", message: "Non-error failure" };
     }
     const lixError = error;
     return {
         name: error.name,
-        message: error.message,
-        stack: error.stack,
+        message: redactDiagnostic(error.message),
+        stack: error.stack ? redactDiagnostic(error.stack) : undefined,
         code: typeof lixError.code === "string" ? lixError.code : undefined,
-        hint: typeof lixError.hint === "string" ? lixError.hint : undefined,
-        details: lixError.details,
+        hint: typeof lixError.hint === "string" ? redactDiagnostic(lixError.hint) : undefined,
+        details: redactDetails(lixError.details),
+        cause: depth < 3 && error.cause !== undefined ? serializeWorkerError(error.cause, depth + 1) : undefined,
     };
 }
 export function deserializeWorkerError(error) {
-    const restored = new Error(error.message);
+    const restored = new Error(error.message, error.cause ? { cause: deserializeWorkerError(error.cause) } : undefined);
     restored.name = error.name;
     restored.stack = error.stack;
     restored.code = error.code;
@@ -21,3 +22,20 @@ export function deserializeWorkerError(error) {
     restored.details = error.details;
     return restored;
 }
+function redactDiagnostic(value) {
+    return value.slice(0, 4096).replace(/Bearer\s+[^\s,;"']+/gi, "Bearer [redacted]")
+        .replace(/((?:authorization|cookie|token|password|secret)\s*[:=]\s*)[^\n]+/gi, "$1[redacted]");
+}
+function redactDetails(value, depth = 0) {
+    if (depth > 3)
+        return "[truncated]";
+    if (typeof value === "string")
+        return redactDiagnostic(value);
+    if (value === null || typeof value === "number" || typeof value === "boolean" || value === undefined)
+        return value;
+    if (Array.isArray(value))
+        return value.slice(0, 32).map(item => redactDetails(item, depth + 1));
+    if (typeof value === "object")
+        return Object.fromEntries(Object.entries(value).slice(0, 32).map(([key, item]) => [key, /authorization|cookie|token|password|secret|headers/i.test(key) ? "[redacted]" : redactDetails(item, depth + 1)]));
+    return "[unsupported]";
+}

package/dist/worker/shared-admission.d.ts

@@ -0,0 +1,26 @@
+import { type HttpTransport } from "../http-transport.js";
+export declare const ADMISSION_PROTOCOL_EPOCH = 17;
+export declare const ADMISSION_STORAGE_EPOCH = 81;
+export type AdmissionIdentity = {
+    repositoryId: string;
+    principalId: string;
+    protocolEpoch: number;
+    storageEpoch: number;
+};
+export declare function sharedCredentialKey(url: string, headers: [string, string][]): string;
+export declare function sameAdmission(a: AdmissionIdentity, b: AdmissionIdentity): boolean;
+/** Authorize attachment, awaiting any server-owned repository upgrade. */
+export declare function requestAdmission(url: string, credentials: [string, string][], transport: HttpTransport): Promise<AdmissionIdentity>;
+/** Memory-only proofs grant cached local attachment, never remote authorization. */
+export declare class SharedAdmissionCache {
+    private readonly revocations;
+    private readonly proofs;
+    record(url: string, headers: [string, string][], identity: AdmissionIdentity): void;
+    generation(url: string, headers: [string, string][]): number;
+    remove(url: string, headers: [string, string][]): void;
+    persistLocal(url: string, headers: [string, string][], generation: number, write: () => Promise<void>, remove: () => Promise<void>): Promise<void>;
+    verify(url: string, headers: [string, string][], expected: AdmissionIdentity | undefined, probe: () => Promise<AdmissionIdentity>, allowOffline?: boolean): Promise<{
+        identity: AdmissionIdentity;
+        online: boolean;
+    }>;
+}

package/dist/worker/shared-admission.js

@@ -0,0 +1,116 @@
+import { HttpTransportError } from "../http-transport.js";
+export const ADMISSION_PROTOCOL_EPOCH = 17;
+export const ADMISSION_STORAGE_EPOCH = 81;
+const ANONYMOUS_ACCOUNT_ID = "00000000-0000-7000-8000-000000000002";
+export function sharedCredentialKey(url, headers) {
+    const entries = [];
+    new Headers(headers).forEach((value, key) => entries.push([key, value]));
+    return JSON.stringify([url, entries]);
+}
+export function sameAdmission(a, b) {
+    return a.repositoryId === b.repositoryId && a.principalId === b.principalId &&
+        a.protocolEpoch === b.protocolEpoch && a.storageEpoch === b.storageEpoch;
+}
+/** Authorize attachment, awaiting any server-owned repository upgrade. */
+export async function requestAdmission(url, credentials, transport) {
+    const locator = new URL(url);
+    const repositoryId = locator.pathname.match(/\/lix\/([0-9a-f-]{36})\/?$/i)?.[1];
+    if (!repositoryId || locator.search || locator.hash || locator.username || locator.password) {
+        throw new HttpTransportError("LIX_TRANSPORT_CONTRACT", "Admission requires a repository protocol URL");
+    }
+    const headers = new Headers(credentials);
+    headers.set("lix-sync-protocol-version", String(ADMISSION_PROTOCOL_EPOCH));
+    locator.pathname = `/lix/v1/${repositoryId}/admission`;
+    let response;
+    for (;;) {
+        response = await transport({ url: locator.toString(),
+            init: { method: "GET", headers, signal: AbortSignal.timeout(10_000), cache: "no-store", redirect: "error", credentials: "omit" },
+            response: { mode: "buffered", maxBytes: 16 * 1024 } });
+        if (response.status !== 503)
+            break;
+        const body = await response.clone().json().catch(() => null);
+        if (body?.error?.code !== "LIX_REPOSITORY_MIGRATING")
+            break;
+        // The authority owns the migration independently of this request. Poll only
+        // its explicit in-progress response; other failures retain their semantics.
+        await new Promise(resolve => setTimeout(resolve, 1_000));
+    }
+    if (response.status === 401 || response.status === 403) {
+        throw new HttpTransportError("LIX_ADMISSION_AUTH_REJECTED", "Authority rejected repository admission");
+    }
+    if (response.status === 409 || response.status === 426) {
+        throw new HttpTransportError("LIX_ADMISSION_EPOCH", "Repository is incompatible with this client version");
+    }
+    if (!response.ok)
+        throw new HttpTransportError("LIX_ADMISSION_HTTP", `Authority admission returned HTTP ${response.status}`);
+    let result;
+    try {
+        result = await response.json();
+    }
+    catch {
+        throw new HttpTransportError("LIX_ADMISSION_PROTOCOL", "Authority returned invalid admission metadata");
+    }
+    if (!result || result.repositoryId !== repositoryId ||
+        typeof result.principalId !== "string" || !/^[\x21-\x7e]{1,255}$/.test(result.principalId)) {
+        throw new HttpTransportError("LIX_ADMISSION_PROTOCOL", "Authority admission identity does not match the repository");
+    }
+    if (result.protocolEpoch !== ADMISSION_PROTOCOL_EPOCH || result.storageEpoch !== ADMISSION_STORAGE_EPOCH) {
+        throw new HttpTransportError("LIX_ADMISSION_EPOCH", "Repository is incompatible with this client version");
+    }
+    return result;
+}
+/** Memory-only proofs grant cached local attachment, never remote authorization. */
+export class SharedAdmissionCache {
+    revocations = new Map();
+    proofs = new Map();
+    record(url, headers, identity) {
+        // Invisible cookies/custom-fetch identity cannot be a credential proof.
+        if (!new Headers(headers).get("authorization") && identity.principalId !== ANONYMOUS_ACCOUNT_ID)
+            return;
+        if (this.proofs.size >= 64)
+            this.proofs.delete(this.proofs.keys().next().value);
+        this.proofs.set(sharedCredentialKey(url, headers), { ...identity });
+    }
+    generation(url, headers) {
+        return this.revocations.get(sharedCredentialKey(url, headers)) ?? 0;
+    }
+    remove(url, headers) {
+        const key = sharedCredentialKey(url, headers);
+        this.revocations.set(key, this.generation(url, headers) + 1);
+        this.proofs.delete(key);
+    }
+    async persistLocal(url, headers, generation, write, remove) {
+        if (this.generation(url, headers) !== generation)
+            return;
+        await write();
+        if (this.generation(url, headers) !== generation)
+            await remove();
+    }
+    async verify(url, headers, expected, probe, allowOffline = true) {
+        const generation = this.generation(url, headers);
+        let identity;
+        let online = true;
+        try {
+            identity = await probe();
+        }
+        catch (error) {
+            if (!(error instanceof Error) || error.code !== "LIX_TRANSPORT_NETWORK")
+                throw error;
+            const known = this.proofs.get(sharedCredentialKey(url, headers));
+            if (!allowOffline || !known || !expected || !sameAdmission(known, expected)) {
+                throw new HttpTransportError("LIX_IDENTITY_UNVERIFIED_OFFLINE", "Repository identity cannot be verified while offline", { cause: error });
+            }
+            identity = known;
+            online = false;
+        }
+        if (this.generation(url, headers) !== generation) {
+            throw new HttpTransportError("LIX_ADMISSION_AUTH_REJECTED", "Credentials were rejected while admission was in flight");
+        }
+        if (expected && !sameAdmission(identity, expected)) {
+            throw new HttpTransportError("LIX_SHARED_ENGINE_IDENTITY_MISMATCH", "Shared engine repository/account does not match this client");
+        }
+        if (online)
+            this.record(url, headers, identity);
+        return { identity, online };
+    }
+}

package/dist/worker/shared-engine.d.ts

@@ -0,0 +1,34 @@
+import type { LixBinding, SyncServerBindingOptions, TelemetryDispatch, TelemetryParentContext, OpenProgressDispatch } from "../binding-types.js";
+export type SharedEngineClient = {
+    server: SyncServerBindingOptions;
+    isDisconnected?(): boolean;
+    telemetry?: TelemetryDispatch;
+    parent?: TelemetryParentContext;
+    progress?: OpenProgressDispatch;
+    commitIdentity?(): void | Promise<void>;
+    rejectCredentials?(headers: [string, string][]): void | Promise<void>;
+    verifyIdentity(): Promise<{
+        authorityUrl: string;
+        accountId: string;
+        headers: [string, string][];
+        online?: boolean;
+    }>;
+};
+/** One physical owner; ports receive independent sessions, never the root. */
+export declare class SharedEngineOwner {
+    private readonly open;
+    private root;
+    private principalId;
+    private state;
+    get lifecycleState(): "closed" | "ready" | "closing" | "opening" | "migration-exclusive";
+    private readonly clients;
+    private queue;
+    constructor(open: (server: SyncServerBindingOptions, telemetry: TelemetryDispatch, client: SharedEngineClient) => Promise<LixBinding>);
+    private readonly backgroundTelemetry;
+    attach(client: SharedEngineClient): Promise<LixBinding>;
+    /** Serialize closed-storage conversion with root admission across all ports. */
+    convert(client: SharedEngineClient, conversion: (server: SyncServerBindingOptions) => Promise<void>, branchId?: string): Promise<void>;
+    deactivate(client: SharedEngineClient): void;
+    detach(client: SharedEngineClient): Promise<void>;
+    private transport;
+}

package/dist/worker/shared-engine.js

@@ -0,0 +1,194 @@
+import { fetchTransport, HttpTransportError } from "../http-transport.js";
+/** One physical owner; ports receive independent sessions, never the root. */
+export class SharedEngineOwner {
+    open;
+    root;
+    principalId;
+    state = "closed";
+    get lifecycleState() { return this.state; }
+    clients = new Set();
+    queue = Promise.resolve();
+    constructor(open) {
+        this.open = open;
+    }
+    backgroundTelemetry = span => {
+        for (const client of this.clients) {
+            try {
+                client.telemetry?.(span);
+            }
+            catch { /* Host telemetry cannot interrupt engine work. */ }
+        }
+    };
+    attach(client) {
+        const operation = this.queue.then(async () => {
+            if (client.isDisconnected?.())
+                throw new Error("Shared engine client disconnected before admission");
+            // Admission precedes storage opening and captures initial credentials.
+            if (this.state === "closing")
+                throw new HttpTransportError("LIX_OWNER_CLOSE_FAILED", "Storage owner has not completed closing");
+            const identity = await client.verifyIdentity();
+            if (client.isDisconnected?.())
+                throw new HttpTransportError("LIX_TRANSPORT_UNAVAILABLE", "Client disconnected during admission");
+            if (identity.authorityUrl !== client.server.url)
+                throw new HttpTransportError("LIX_SHARED_ENGINE_IDENTITY_MISMATCH", "Admission authority does not match this client");
+            const opensRoot = this.root === undefined;
+            if (!this.root) {
+                this.state = "opening";
+                const originalServer = client.server;
+                const headers = identity.headers;
+                // Bind native admission to the exact credentials actually used during
+                // opening; a later dynamic-header read cannot authorize another principal.
+                client.server = { ...originalServer, headers, headerProvider: identity.online === false
+                        ? async () => { throw new HttpTransportError("LIX_IDENTITY_UNVERIFIED_OFFLINE", "Cached local admission does not authorize remote requests"); }
+                        : undefined };
+                this.clients.add(client);
+                try {
+                    this.root = await this.open(this.transport(), this.backgroundTelemetry, client);
+                    const principal = await this.root.activeAccountId();
+                    if (principal !== identity.accountId)
+                        throw new HttpTransportError("LIX_SHARED_ENGINE_IDENTITY_MISMATCH", "Stored replica account does not match admission");
+                    this.principalId = principal;
+                    this.state = "ready";
+                }
+                catch (error) {
+                    this.clients.delete(client);
+                    if (this.root) {
+                        this.state = "closing";
+                        await this.root.close();
+                        this.root = undefined;
+                        this.principalId = undefined;
+                    }
+                    this.state = "closed";
+                    throw error;
+                }
+                finally {
+                    client.server = originalServer;
+                }
+            }
+            const root = this.root;
+            try {
+                if (client.server.url !== identity.authorityUrl ||
+                    this.principalId !== identity.accountId) {
+                    throw Object.assign(new Error("Shared engine repository/account does not match this client"), { code: "LIX_SHARED_ENGINE_IDENTITY_MISMATCH" });
+                }
+                await client.commitIdentity?.();
+                this.clients.add(client);
+                const report = opensRoot ? root.openReport?.() : undefined;
+                const child = await root.openAnotherSession({}, client.telemetry ?? (() => { }));
+                if (report === undefined)
+                    return child;
+                // Only the opening caller performed initialization/migration. Later
+                // attachments must not inherit that first caller's opening report.
+                return new Proxy(child, {
+                    get(target, property) {
+                        if (property === "openReport")
+                            return () => report;
+                        const value = Reflect.get(target, property, target);
+                        return typeof value === "function" ? value.bind(target) : value;
+                    },
+                });
+            }
+            catch (error) {
+                this.clients.delete(client);
+                if (this.clients.size === 0) {
+                    this.state = "closing";
+                    await root.close();
+                    this.root = undefined;
+                    this.principalId = undefined;
+                    this.state = "closed";
+                }
+                throw error;
+            }
+        });
+        this.queue = operation.catch(() => undefined);
+        return operation;
+    }
+    /** Serialize closed-storage conversion with root admission across all ports. */
+    convert(client, conversion, branchId) {
+        const operation = this.queue.then(async () => {
+            if (client.isDisconnected?.())
+                throw new Error("Shared engine client disconnected before conversion");
+            if (this.root) {
+                const identity = await client.verifyIdentity();
+                if (client.server.url !== identity.authorityUrl ||
+                    this.principalId !== identity.accountId) {
+                    throw Object.assign(new Error("Shared engine repository/account does not match this client"), { code: "LIX_SHARED_ENGINE_IDENTITY_MISMATCH" });
+                }
+                if (branchId !== undefined && branchId !== await this.root.activeBranchId()) {
+                    throw Object.assign(new Error("The converted replica selected a different branch"), { code: "LIX_PARTIAL_CONVERSION_BRANCH_MISMATCH" });
+                }
+                // A competing caller already admitted the converted partial store.
+                // Never close its live sessions just to repeat an explicit conversion.
+                return;
+            }
+            if (this.state !== "closed")
+                throw new HttpTransportError("LIX_OWNER_NOT_CLOSED", "Migration requires a closed storage owner");
+            this.state = "migration-exclusive";
+            this.clients.add(client);
+            try {
+                await conversion(this.transport());
+            }
+            finally {
+                this.clients.delete(client);
+                this.state = "closed";
+            }
+        });
+        this.queue = operation.catch(() => undefined);
+        return operation;
+    }
+    deactivate(client) {
+        this.clients.delete(client);
+    }
+    async detach(client) {
+        const operation = this.queue.then(async () => {
+            this.clients.delete(client);
+            if (this.clients.size === 0 && this.root) {
+                const root = this.root;
+                // Keep ownership on a failed close; never open a second engine over it.
+                this.state = "closing";
+                await root.close();
+                this.root = undefined;
+                this.principalId = undefined;
+                this.state = "closed";
+            }
+        });
+        this.queue = operation.catch(() => undefined);
+        await operation;
+    }
+    transport() {
+        const first = this.clients.values().next().value;
+        if (!first)
+            throw new HttpTransportError("LIX_TRANSPORT_UNAVAILABLE", "No live shared-engine transport");
+        return {
+            url: first.server.url,
+            headers: [],
+            transport: async (request) => {
+                let unavailable;
+                // Credentials and callback remain paired when a tab leaves or suspends.
+                for (const client of this.clients) {
+                    if (client.isDisconnected?.())
+                        continue;
+                    const server = client.server;
+                    let supplied;
+                    try {
+                        supplied = (server.headerProvider ? await server.headerProvider() : server.headers).map(([name, value]) => [name, value]);
+                    }
+                    catch (error) {
+                        unavailable = error;
+                        continue;
+                    }
+                    if (!this.clients.has(client) || client.isDisconnected?.())
+                        continue;
+                    const headers = new Headers(request.init.headers);
+                    for (const [name, value] of supplied)
+                        headers.set(name, value);
+                    const response = await (server.transport ?? fetchTransport())({ ...request, init: { ...request.init, headers, credentials: "omit" } });
+                    if (response.status === 401 || response.status === 403)
+                        await client.rejectCredentials?.(supplied);
+                    return response;
+                }
+                throw unavailable ?? new HttpTransportError("LIX_TRANSPORT_UNAVAILABLE", "No verified live shared-engine transport");
+            },
+        };
+    }
+}

package/package.json

@@ -1,20 +1,24 @@
 {
 	"name": "@lix-js/sdk",
 	"type": "module",
-	"version": "0.16.0",
+	"version": "0.17.0",
 	"license": "MIT",
 	"repository": {
 		"type": "git",
 		"url": "https://github.com/opral/lix"
 	},
 	"exports": {
+		"./compatibility": {
+			"types": "./dist/compatibility.d.ts",
+			"default": "./dist/compatibility.js"
+		},
+		"./migration": {
+			"types": "./dist/migration.d.ts",
+			"default": "./dist/migration.js"
+		},
 		".": {
 			"types": "./dist/index.d.ts",
 			"default": "./dist/index.js"
-		},
-		"./server-protocol": {
-			"types": "./dist/remote/server-protocol.d.ts",
-			"default": "./dist/remote/server-protocol.js"
 		}
 	},
 	"imports": {
@@ -31,17 +35,19 @@
 		"dist"
 	],
 	"scripts": {
-		"build": "npm run clean && npm run build:native && npm run build:wasm && npm run build:ts && npm run build:plugins",
-		"build:browser": "npm run clean && npm run build:wasm && npm run build:ts && npm run build:plugins",
+		"build": "npm run clean && npm run build:native && npm run build:migration:native && npm run build:wasm && npm run build:migration:wasm && npm run build:ts && npm run build:plugins",
+		"build:browser": "npm run clean && npm run build:wasm && npm run build:migration:wasm && npm run build:ts && npm run build:plugins",
 		"build:native": "node ./scripts/build-native.js",
 		"build:wasm": "node ./scripts/build-wasm.js",
+		"build:migration:wasm": "LIX_OFFLINE_MIGRATION=1 node ./scripts/build-wasm.js",
+		"build:migration:native": "LIX_OFFLINE_MIGRATION=1 node ./scripts/build-native.js",
 		"build:wasm:dev": "LIX_WASM_PROFILE=dev node ./scripts/build-wasm.js",
 		"build:plugins": "node ./scripts/build-bundled-plugins.js",
 		"benchmark:plugin-reopen": "node ./scripts/benchmark-plugin-reopen.mjs",
 		"benchmark:storage-boundary": "LIX_WASM_STORAGE_BENCH=1 npm run build:browser && LIX_WASM_STORAGE_BENCH=1 vitest run --config vitest.browser.config.ts src/storage-bridge.bench.browser.test.ts",
 		"clean": "node ./scripts/clean.js",
 		"prepare:native-package": "node ./scripts/prepare-native-package.js",
-		"build:ts": "tsc -p tsconfig.json",
+		"build:ts": "tsc -p tsconfig.json && node ./scripts/build-compatibility.js",
 		"test": "npm run build && vitest run",
 		"test:browser": "npm run build:browser && vitest run --config vitest.browser.config.ts",
 		"test:browser:built": "vitest run --config vitest.browser.config.ts",
@@ -49,20 +55,22 @@
 		"typecheck": "tsc -p tsconfig.test.json --noEmit"
 	},
 	"optionalDependencies": {
-		"@lix-js/sdk-darwin-arm64": "0.16.0",
-		"@lix-js/sdk-linux-arm64": "0.16.0",
-		"@lix-js/sdk-linux-x64": "0.16.0",
-		"@lix-js/sdk-win32-x64": "0.16.0"
+		"@lix-js/sdk-darwin-arm64": "0.17.0",
+		"@lix-js/sdk-linux-arm64": "0.17.0",
+		"@lix-js/sdk-linux-x64": "0.17.0",
+		"@lix-js/sdk-win32-x64": "0.17.0"
 	},
 	"devDependencies": {
-		"@vitest/browser-playwright": "4.1.10",
 		"@types/node": "^24.10.2",
+		"@vitest/browser-playwright": "4.1.10",
 		"playwright": "1.57.0",
 		"typescript": "^5.5.4",
 		"vite": "8.1.4",
 		"vitest": "4.1.10"
 	},
 	"dependencies": {
+		"@bytecodealliance/jco-transpile": "0.13.0",
+		"binaryen": "130.0.0",
 		"fflate": "^0.8.3"
 	}
 }