@openlfcp/shared-objects 0.1.0-rc.1

package/dist/values.js

@@ -0,0 +1,163 @@
+import { fromBase64url, ID32_LENGTH, LfcpError, principalId, toBase64url, } from "@openlfcp/core";
+import { sha256 } from "@openlfcp/crypto";
+import { ProfileInvalidError } from "./profile-invalid.js";
+/**
+ * Value-level rules of SHARED-OBJECTS-PROFILE-01: Principal references,
+ * Local Dates, timestamps, reverse-domain names, namespaced values, the
+ * Automerge actor ID and the profile framing of Data Unit and Snapshot
+ * plaintexts.
+ */
+/** §6: the profile identifier. */
+export const PROFILE_ID = "org.openlfcp.shared-objects.v1";
+/** §27: the reference of a Principal ID. */
+export function principalRef(id) {
+    return `p:${toBase64url(principalId(id))}`;
+}
+/** True when `text` is a canonical Principal reference of exactly 32 bytes. */
+export function isPrincipalRef(text) {
+    if (typeof text !== "string" || !text.startsWith("p:"))
+        return false;
+    try {
+        return fromBase64url(text.slice(2)).length === ID32_LENGTH;
+    }
+    catch {
+        return false;
+    }
+}
+/** The Principal ID a reference names; throws INVALID_BASE64URL / INVALID_LENGTH otherwise. */
+export function parsePrincipalRef(text) {
+    if (!text.startsWith("p:"))
+        throw new LfcpError("INVALID_BASE64URL", "a Principal reference starts with p:");
+    return principalId(fromBase64url(text.slice(2)));
+}
+/** §35: a real Gregorian date YYYY-MM-DD (no time zone). */
+export function isLocalDate(text) {
+    if (typeof text !== "string")
+        return false;
+    const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(text);
+    if (m === null)
+        return false;
+    const [y, mo, d] = [Number(m[1]), Number(m[2]), Number(m[3])];
+    const leap = (y % 4 === 0 && y % 100 !== 0) || y % 400 === 0;
+    const days = [31, leap ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+    return mo >= 1 && mo <= 12 && d >= 1 && d <= days[mo - 1];
+}
+/** §28: an RFC 3339 UTC timestamp ending in Z with a real date and time (second 60 for leap seconds). */
+export function isUtcTimestamp(text) {
+    if (typeof text !== "string")
+        return false;
+    const m = /^(\d{4}-\d{2}-\d{2})T(\d{2}):(\d{2}):(\d{2})(\.\d+)?Z$/.exec(text);
+    return (m !== null &&
+        isLocalDate(m[1]) &&
+        Number(m[2]) <= 23 &&
+        Number(m[3]) <= 59 &&
+        Number(m[4]) <= 60);
+}
+const LABEL = "[a-z0-9](?:[a-z0-9-]*[a-z0-9])?";
+const REVERSE_DOMAIN = new RegExp(`^${LABEL}(?:\\.${LABEL})+$`);
+const NAMESPACED = new RegExp(`^x/${LABEL}(?:\\.${LABEL})+/[^/]+$`, "u");
+/** §18 ABNF reverse-domain: at least two lowercase LDH labels without leading or trailing hyphen. */
+export const isReverseDomain = (text) => typeof text === "string" && REVERSE_DOMAIN.test(text);
+/** §33 ABNF namespaced-value: x/<reverse-domain>/<value>, value non-empty without "/". */
+export const isNamespacedValue = (text) => typeof text === "string" && NAMESPACED.test(text);
+const ACTOR_DOMAIN = Uint8Array.from("OPENLFCP-SHARED-OBJECTS-ACTOR-v1", (c) => c.charCodeAt(0));
+/**
+ * §8: the Automerge actor ID of `principal` editing `resource`:
+ * SHA-256(ASCII("OPENLFCP-SHARED-OBJECTS-ACTOR-v1") || resource_id || principal_id),
+ * from the raw 32-byte IDs.
+ */
+export function deriveActorId(resource, principal) {
+    for (const [what, id] of [
+        ["the Resource ID", resource],
+        ["the Principal ID", principal],
+    ]) {
+        if (!(id instanceof Uint8Array) || id.length !== ID32_LENGTH)
+            throw new LfcpError("INVALID_LENGTH", `${what} must be the raw 32-byte ID`);
+    }
+    const input = new Uint8Array(ACTOR_DOMAIN.length + 2 * ID32_LENGTH);
+    input.set(ACTOR_DOMAIN, 0);
+    input.set(resource, ACTOR_DOMAIN.length);
+    input.set(principal, ACTOR_DOMAIN.length + ID32_LENGTH);
+    return sha256(input);
+}
+/** §11, §13: the only framing version. */
+export const FRAMING_VERSION = 1;
+/** The deterministic CBOR head of a byte string of `length` bytes (major type 2, shortest form). */
+function bstrHead(length) {
+    if (length < 24)
+        return [0x40 | length];
+    if (length < 0x100)
+        return [0x58, length];
+    if (length < 0x10000)
+        return [0x59, length >> 8, length & 0xff];
+    if (length <= 0xffffffff)
+        return [
+            0x5a,
+            (length >>> 24) & 0xff,
+            (length >>> 16) & 0xff,
+            (length >>> 8) & 0xff,
+            length & 0xff,
+        ];
+    throw new LfcpError("OUT_OF_RANGE", "the framed bytes are too long");
+}
+/**
+ * Deterministic CBOR of [1, bstr] (§11 shared-objects-change, §13
+ * shared-objects-snapshot): the profile plaintext of a Data Unit (one
+ * Automerge change) or a Snapshot (one Automerge full save). The bytes are
+ * framed as given; checking that they are a valid Automerge change or save
+ * is the Automerge binding (LFCP-031).
+ */
+export function frameProfilePayload(bytes) {
+    if (!(bytes instanceof Uint8Array))
+        throw new LfcpError("INVALID_LENGTH", "framing takes bytes");
+    const head = bstrHead(bytes.length);
+    const out = new Uint8Array(2 + head.length + bytes.length);
+    out.set([0x82, FRAMING_VERSION, ...head], 0);
+    out.set(bytes, 2 + head.length);
+    return out;
+}
+/**
+ * The inner bytes of a framed profile plaintext. §11: a receiver MUST
+ * reject plaintext that is not valid CBOR, not a two-element array, or
+ * uses an unsupported framing version; this also requires the
+ * deterministic encoding and no trailing bytes. Throws PROFILE_INVALID /
+ * INVALID_AUTOMERGE_BYTES (§74.1).
+ */
+export function unframeProfilePayload(framed) {
+    const fail = (why) => {
+        throw new ProfileInvalidError("INVALID_AUTOMERGE_BYTES", `invalid profile framing: ${why}`);
+    };
+    if (!(framed instanceof Uint8Array) || framed.length < 3)
+        return fail("too short");
+    if (framed[0] !== 0x82)
+        return fail("not a two-element array");
+    if (framed[1] !== FRAMING_VERSION)
+        return fail("unsupported framing version");
+    const first = framed[2];
+    if (first >> 5 !== 2)
+        return fail("the second element is not a byte string");
+    const info = first & 0x1f;
+    let length;
+    let offset;
+    const at = (i) => framed[i];
+    if (info < 24)
+        [length, offset] = [info, 3];
+    else if (info === 24)
+        [length, offset] = [at(3), 4];
+    else if (info === 25)
+        [length, offset] = [(at(3) << 8) | at(4), 5];
+    else if (info === 26)
+        [length, offset] = [((at(3) << 24) >>> 0) + (at(4) << 16) + (at(5) << 8) + at(6), 7];
+    else
+        return fail("unsupported byte string length");
+    if (offset > framed.length)
+        return fail("truncated");
+    const bytes = framed.subarray(offset);
+    if (bytes.length !== length)
+        return fail(bytes.length < length ? "truncated" : "trailing bytes");
+    const canonical = bstrHead(length);
+    if (canonical.length !== offset - 2)
+        return fail("non-shortest byte string length");
+    return Uint8Array.from(bytes);
+}
+//# sourceMappingURL=values.js.map

package/dist/wasm.d.ts

@@ -0,0 +1,33 @@
+/** What initializing Automerge needs (injectable for tests). */
+export interface AutomergeWasmHooks {
+    readonly isInitialized: () => boolean;
+    readonly loadBase64: () => Promise<string>;
+    readonly initialize: (wasm: Uint8Array) => Promise<void>;
+}
+/**
+ * Standard base64 to bytes, fast: Uint8Array.fromBase64 where the runtime
+ * has it, else atob and a plain loop. Automerge's own initializeBase64Wasm
+ * decodes with Uint8Array.from(atob(s), callback), which takes about 200 ms
+ * of main-thread time for its 3.5 MB wasm (measured in Node 24, LFCP-059);
+ * this takes under 10 ms.
+ */
+export declare function decodeBase64(text: string): Uint8Array;
+/**
+ * An idempotent, concurrency-safe initializer: concurrent callers share one
+ * in-flight promise; a failure clears it so a later call can retry.
+ */
+export declare function automergeInitializer(hooks: AutomergeWasmHooks): () => Promise<void>;
+/**
+ * Makes sure Automerge's WebAssembly is ready. Every build of
+ * `@automerge/automerge` except `/slim` initializes it on import, so this is
+ * a no-op there. A host that aliases `@automerge/automerge` to its `/slim`
+ * entry (e.g. a renderer where compiling 3.5 MB of wasm synchronously on the
+ * main thread is refused, as Chromium does above 4 KB) awaits this once
+ * before using this package: it loads the base64 wasm through a dynamic
+ * import, decodes it quickly and compiles it asynchronously. Idempotent and
+ * safe to call concurrently; a failed attempt can be retried.
+ */
+export declare const initializeAutomerge: () => Promise<void>;
+/** Whether Automerge's WebAssembly is ready (always, except on `/slim` before initializeAutomerge). */
+export declare const isAutomergeInitialized: () => boolean;
+//# sourceMappingURL=wasm.d.ts.map

package/dist/wasm.js

@@ -0,0 +1,58 @@
+import * as A from "@automerge/automerge";
+/**
+ * Standard base64 to bytes, fast: Uint8Array.fromBase64 where the runtime
+ * has it, else atob and a plain loop. Automerge's own initializeBase64Wasm
+ * decodes with Uint8Array.from(atob(s), callback), which takes about 200 ms
+ * of main-thread time for its 3.5 MB wasm (measured in Node 24, LFCP-059);
+ * this takes under 10 ms.
+ */
+export function decodeBase64(text) {
+    const native = Uint8Array.fromBase64;
+    if (native !== undefined)
+        return native(text);
+    const bin = atob(text);
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        out[i] = bin.charCodeAt(i);
+    return out;
+}
+/**
+ * An idempotent, concurrency-safe initializer: concurrent callers share one
+ * in-flight promise; a failure clears it so a later call can retry.
+ */
+export function automergeInitializer(hooks) {
+    let inFlight = null;
+    return () => {
+        if (hooks.isInitialized())
+            return Promise.resolve();
+        inFlight ??= (async () => {
+            try {
+                await hooks.initialize(decodeBase64(await hooks.loadBase64()));
+            }
+            catch (e) {
+                inFlight = null;
+                throw e;
+            }
+        })();
+        return inFlight;
+    };
+}
+/**
+ * Makes sure Automerge's WebAssembly is ready. Every build of
+ * `@automerge/automerge` except `/slim` initializes it on import, so this is
+ * a no-op there. A host that aliases `@automerge/automerge` to its `/slim`
+ * entry (e.g. a renderer where compiling 3.5 MB of wasm synchronously on the
+ * main thread is refused, as Chromium does above 4 KB) awaits this once
+ * before using this package: it loads the base64 wasm through a dynamic
+ * import, decodes it quickly and compiles it asynchronously. Idempotent and
+ * safe to call concurrently; a failed attempt can be retried.
+ */
+export const initializeAutomerge = automergeInitializer({
+    isInitialized: () => A.isWasmInitialized(),
+    loadBase64: async () => (await import("@automerge/automerge/automerge.wasm.base64")).automergeWasmBase64,
+    // initializeWasm compiles and instantiates asynchronously (WebAssembly.instantiate).
+    initialize: (wasm) => A.initializeWasm(wasm),
+});
+/** Whether Automerge's WebAssembly is ready (always, except on `/slim` before initializeAutomerge). */
+export const isAutomergeInitialized = () => A.isWasmInitialized();
+//# sourceMappingURL=wasm.js.map

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@openlfcp/shared-objects",
+  "version": "0.1.0-rc.1",
+  "description": "SHARED-OBJECTS-PROFILE-01 (org.openlfcp.shared-objects.v1) implementation.",
+  "keywords": [
+    "openlfcp",
+    "lfcp",
+    "local-first",
+    "end-to-end-encryption",
+    "automerge",
+    "crdt",
+    "tasks",
+    "shared-objects"
+  ],
+  "license": "Apache-2.0",
+  "homepage": "https://github.com/openlfcp/sdk-ts/tree/main/packages/shared-objects#readme",
+  "bugs": {
+    "url": "https://github.com/openlfcp/sdk-ts/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/openlfcp/sdk-ts.git",
+    "directory": "packages/shared-objects"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=24"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.map",
+    "!dist/**/*.tsbuildinfo"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "tag": "next"
+  },
+  "dependencies": {
+    "@automerge/automerge": "3.5.0",
+    "fflate": "0.8.3",
+    "@openlfcp/core": "^0.1.0-rc.1",
+    "@openlfcp/crypto": "^0.1.0-rc.1"
+  },
+  "devDependencies": {
+    "fast-check": "4.10.2"
+  },
+  "scripts": {
+    "test": "cd ../.. && vitest run packages/shared-objects/test/",
+    "test:property": "cd ../.. && vitest run packages/shared-objects/test/property/",
+    "test:property:extended": "cd ../.. && LFCP_PROPERTY_EXTENDED=1 vitest run packages/shared-objects/test/property/"
+  }
+}