@openlfcp/shared-objects 0.1.2 → 0.1.4

package/README.md

@@ -20,9 +20,9 @@ reaches the replica (§95). The replica has no Markdown or editor concepts.
 
 Part of the OpenLFCP TypeScript SDK, which implements the OpenLFCP MVP 0.1
 subset of [LFCP-WIRE-01](https://github.com/openlfcp/spec/blob/main/wire/LFCP-WIRE-01.md)
-at `mvp-0.1-baseline.9`, not every deferred WIRE-01 feature. It does not
+at `mvp-0.1-baseline.10`, not every deferred WIRE-01 feature. It does not
 claim full LFCP-WIRE-01 conformance. This is the MVP 0.1 release
-(`0.1.2`, npm dist-tag `latest`). Until 1.0, minor versions may change APIs.
+(`0.1.4`, npm dist-tag `latest`). Until 1.0, minor versions may change APIs.
 
 ## Automerge and WebAssembly
 

package/dist/automerge-bytes.d.ts

@@ -0,0 +1,40 @@
+import { type ParsedChange } from "./canonical.js";
+/** A checked Automerge change: its bytes and decoded header. */
+export interface CheckedChange {
+    readonly bytes: Uint8Array;
+    /** Hex SHA-256 change hash (the Automerge change identity). */
+    readonly hash: string;
+    /** Hex actor ID. */
+    readonly actor: string;
+    readonly seq: number;
+    /** Hex hashes of the changes this one depends on. */
+    readonly deps: readonly string[];
+    /** Hex IDs of the other actors the change refers to (§11.1: each must be known to the document). */
+    readonly otherActors: readonly string[];
+}
+/**
+ * Checks that `bytes` is exactly one valid Automerge change (§11, §12) and
+ * returns it decoded. Rejects with PROFILE_INVALID / INVALID_AUTOMERGE_BYTES: a chunk that is not a
+ * change (a document chunk is a full save, §13), bytes Automerge cannot
+ * parse, trailing bytes such as a second concatenated change, and a
+ * checksum that does not match the change hash. Automerge JS 3.5.0 parses
+ * a change without verifying its checksum, so the check is done here.
+ */
+export declare function checkChange(bytes: Uint8Array): CheckedChange;
+/** The change as its canonical bytes give it (§11.3), reusing the walk of checkChange. */
+export declare function parsedOf(change: CheckedChange): ParsedChange;
+/**
+ * Checks that `bytes` starts as an Automerge full save (a document chunk,
+ * §13). Whether the whole image loads, checksums included, is decided by
+ * Automerge's load.
+ */
+export declare function checkSaveHeader(bytes: Uint8Array): void;
+/** §11: the Data Unit plaintext [1, change] of one checked Automerge change. */
+export declare function frameChange(change: Uint8Array): Uint8Array;
+/** §11: the one Automerge change a Data Unit plaintext carries, checked. Throws PROFILE_INVALID / INVALID_AUTOMERGE_BYTES. */
+export declare function unframeChange(plaintext: Uint8Array): CheckedChange;
+/** §13: the Snapshot plaintext [1, save] of an Automerge full save. */
+export declare function frameSnapshot(save: Uint8Array): Uint8Array;
+/** §13: the Automerge full save a Snapshot plaintext carries (header checked). Throws PROFILE_INVALID / INVALID_AUTOMERGE_BYTES. */
+export declare function unframeSnapshot(plaintext: Uint8Array): Uint8Array;
+//# sourceMappingURL=automerge-bytes.d.ts.map

package/dist/automerge-bytes.js

@@ -0,0 +1,111 @@
+import * as A from "@automerge/automerge";
+import { toHex } from "@openlfcp/core";
+import { checkCanonicalChange } from "./canonical.js";
+import { checkChangeExpansion } from "./chunk-limits.js";
+import { ProfileInvalidError } from "./profile-invalid.js";
+import { frameProfilePayload, unframeProfilePayload } from "./values.js";
+/**
+ * Automerge byte checks of the SHARED-OBJECTS-PROFILE-01 payloads (LFCP-031):
+ * a Data Unit plaintext carries exactly one Automerge change (§11, §12), a
+ * Snapshot plaintext one Automerge full save (§13). The framing itself is
+ * frameProfilePayload / unframeProfilePayload (LFCP-030); this adds the
+ * check that the framed bytes are what they claim to be.
+ *
+ * Automerge storage chunks start with the magic bytes 85 6f 4a 83, a 4-byte
+ * checksum (the first 4 bytes of the chunk hash) and a chunk type: 0 for a
+ * document (a full save), 1 for a change, 2 for a compressed change.
+ */
+const MAGIC = [0x85, 0x6f, 0x4a, 0x83];
+const CHUNK_DOCUMENT = 0;
+const CHUNK_CHANGE = 1;
+const CHUNK_COMPRESSED_CHANGE = 2;
+const HEADER = 9; // magic, checksum, chunk type
+/** §11, §13, §74.1: PROFILE_INVALID / INVALID_AUTOMERGE_BYTES. */
+const reject = (why) => {
+    throw new ProfileInvalidError("INVALID_AUTOMERGE_BYTES", why);
+};
+function chunkType(bytes, what) {
+    if (bytes.length < HEADER || MAGIC.some((b, i) => bytes[i] !== b))
+        return reject(`${what} is not an Automerge chunk`);
+    return bytes[8];
+}
+/**
+ * Checks that `bytes` is exactly one valid Automerge change (§11, §12) and
+ * returns it decoded. Rejects with PROFILE_INVALID / INVALID_AUTOMERGE_BYTES: a chunk that is not a
+ * change (a document chunk is a full save, §13), bytes Automerge cannot
+ * parse, trailing bytes such as a second concatenated change, and a
+ * checksum that does not match the change hash. Automerge JS 3.5.0 parses
+ * a change without verifying its checksum, so the check is done here.
+ */
+export function checkChange(bytes) {
+    const type = chunkType(bytes, "the change");
+    if (type === CHUNK_COMPRESSED_CHANGE)
+        reject("a compressed Automerge change (chunk type 2): a change is uncompressed (§11)");
+    if (type !== CHUNK_CHANGE)
+        reject(`chunk type ${type} is not an Automerge change (§11)`);
+    // §11.1: what the change expands to and its structure, before Automerge decodes it.
+    const expansion = checkChangeExpansion(bytes);
+    // §11.3: the canonical encoding, by the format's properties, still before the engine.
+    const parsed = checkCanonicalChange(bytes);
+    let decoded;
+    try {
+        decoded = A.decodeChange(bytes);
+    }
+    catch (e) {
+        return reject(`invalid Automerge change bytes (§11): ${e.message}`);
+    }
+    if (toHex(bytes.subarray(4, 8)) !== decoded.hash.slice(0, 8))
+        reject("the Automerge change checksum does not match its hash (§11)");
+    const checked = Object.freeze({
+        bytes: Uint8Array.from(bytes),
+        hash: decoded.hash,
+        actor: decoded.actor,
+        seq: decoded.seq,
+        deps: Object.freeze([...decoded.deps]),
+        otherActors: expansion.otherActors,
+    });
+    PARSED.set(checked, parsed);
+    return checked;
+}
+/** The operations checkChange read from the bytes (§11.3), for the references of §11.4. */
+const PARSED = new WeakMap();
+/** The change as its canonical bytes give it (§11.3), reusing the walk of checkChange. */
+export function parsedOf(change) {
+    let p = PARSED.get(change);
+    if (p === undefined) {
+        p = checkCanonicalChange(change.bytes);
+        PARSED.set(change, p);
+    }
+    return p;
+}
+/**
+ * Checks that `bytes` starts as an Automerge full save (a document chunk,
+ * §13). Whether the whole image loads, checksums included, is decided by
+ * Automerge's load.
+ */
+export function checkSaveHeader(bytes) {
+    const type = chunkType(bytes, "the Snapshot image");
+    if (type !== CHUNK_DOCUMENT)
+        reject(`chunk type ${type} is not an Automerge document (full save, §13)`);
+}
+/** §11: the Data Unit plaintext [1, change] of one checked Automerge change. */
+export function frameChange(change) {
+    checkChange(change);
+    return frameProfilePayload(change);
+}
+/** §11: the one Automerge change a Data Unit plaintext carries, checked. Throws PROFILE_INVALID / INVALID_AUTOMERGE_BYTES. */
+export function unframeChange(plaintext) {
+    return checkChange(unframeProfilePayload(plaintext));
+}
+/** §13: the Snapshot plaintext [1, save] of an Automerge full save. */
+export function frameSnapshot(save) {
+    checkSaveHeader(save);
+    return frameProfilePayload(save);
+}
+/** §13: the Automerge full save a Snapshot plaintext carries (header checked). Throws PROFILE_INVALID / INVALID_AUTOMERGE_BYTES. */
+export function unframeSnapshot(plaintext) {
+    const save = unframeProfilePayload(plaintext);
+    checkSaveHeader(save);
+    return save;
+}
+//# sourceMappingURL=automerge-bytes.js.map

package/dist/canonical.d.ts

@@ -0,0 +1,38 @@
+/** An operation of a change, as the references of §11.4 read it. */
+export interface ParsedOp {
+    /** "_root", or the creating operation's ID "counter@actorhex". */
+    readonly obj: string;
+    /** A property name, the head of a sequence, or an element ID. */
+    readonly key: {
+        readonly kind: "prop";
+        readonly name: string;
+    } | {
+        readonly kind: "head";
+    } | {
+        readonly kind: "elem";
+        readonly id: string;
+    };
+    readonly insert: boolean;
+    /** 0 makeMap, 1 set, 2 makeList, 3 del, 4 makeText, 5 inc, 6 makeTable, 7 mark. */
+    readonly action: number;
+    /** Predecessor IDs "counter@actorhex", in order. */
+    readonly pred: readonly string[];
+}
+/** A change read from its bytes (§11.3), without the engine. */
+export interface ParsedChange {
+    readonly actor: string;
+    readonly seq: number;
+    readonly startOp: number;
+    /** Hex dependency hashes, ascending. */
+    readonly deps: readonly string[];
+    /** Hex other actors, ascending: actor index i is otherActors[i - 1]. */
+    readonly otherActors: readonly string[];
+    readonly ops: readonly ParsedOp[];
+}
+/**
+ * §11.3: checks that `bytes` (one change chunk within the §11.1 limits) is
+ * the canonical encoding of its change, and returns the change's operations
+ * read from it. Throws PROFILE_INVALID / INVALID_AUTOMERGE_BYTES.
+ */
+export declare function checkCanonicalChange(bytes: Uint8Array): ParsedChange;
+//# sourceMappingURL=canonical.d.ts.map