@openlfcp/wire 0.1.0-rc.1

package/dist/handshake.js

@@ -0,0 +1,297 @@
+import { bytesEqual, LfcpError, principalId, secureRandom } from "@openlfcp/core";
+import { decodeDeterministic, encode } from "./cbor/index.js";
+import { parseSignedObject, signObject, verifySignedObject } from "./cose.js";
+import { createMessage, ERROR_CODE, replyTo, } from "./message.js";
+import { principalDescriptorFromCbor, principalDescriptorToCbor, } from "./principal.js";
+/**
+ * The LFCP session handshake (LFCP-WIRE-01 §34-§37): HELLO → CHALLENGE →
+ * AUTH → READY, as pure functions over decoded messages. No sockets.
+ *
+ * The handshake authenticates the session Principal: it proves possession
+ * of the Ed25519 key of the descriptor sent in HELLO, bound to this
+ * session's nonces, session ID and server ID. It grants no Resource
+ * authority: AuthenticatedSession has no abilities, and the optional
+ * hosting credential is an opaque server-policy value, never a capability
+ * (§36). Resource authority comes only from Control Chains (capability.ts).
+ */
+/** The wire profile this SDK implements (§34). */
+export const WIRE_PROFILE = "LFCP-WIRE-01";
+const AUTH_LABEL = "LFCP-AUTH-v1";
+const NONCE = 16;
+const SERVER_ID = 32;
+function sized(what, v, length) {
+    if (!(v instanceof Uint8Array) || v.length !== length)
+        throw new LfcpError("INVALID_STRUCTURE", `${what} must be ${length} bytes`);
+    return v;
+}
+/**
+ * §36: deterministic CBOR of ["LFCP-AUTH-v1", session_id, client_nonce,
+ * server_nonce, server_id, principal_id]; nothing else.
+ */
+export function authTranscript(f) {
+    return encode([
+        AUTH_LABEL,
+        sized("the session id", f.sessionId, NONCE),
+        sized("the client nonce", f.clientNonce, NONCE),
+        sized("the server nonce", f.serverNonce, NONCE),
+        sized("the server id", f.serverId, SERVER_ID),
+        sized("the Principal ID", f.principalId, 32),
+    ]);
+}
+/** Decodes an auth transcript strictly: deterministic CBOR, the label, six elements, exact sizes. */
+export function decodeAuthTranscript(bytes) {
+    const v = decodeDeterministic(bytes);
+    if (!Array.isArray(v) || v.length !== 6 || v[0] !== AUTH_LABEL)
+        throw new LfcpError("INVALID_STRUCTURE", 'an auth transcript is ["LFCP-AUTH-v1", ...5 fields]');
+    const [, sessionId, clientNonce, serverNonce, serverId, principal] = v;
+    return Object.freeze({
+        sessionId: Uint8Array.from(sized("the session id", sessionId, NONCE)),
+        clientNonce: Uint8Array.from(sized("the client nonce", clientNonce, NONCE)),
+        serverNonce: Uint8Array.from(sized("the server nonce", serverNonce, NONCE)),
+        serverId: Uint8Array.from(sized("the server id", serverId, SERVER_ID)),
+        principalId: principalId(sized("the Principal ID", principal, 32)),
+    });
+}
+/** The AUTH proof: a §10 COSE_Sign1 by the session Principal over the exact transcript. */
+export function signAuthProof(fields, signer) {
+    if (!bytesEqual(fields.principalId, signer.descriptor.principalId))
+        throw new LfcpError("COSE_SIGNER_MISMATCH", "the transcript names another Principal");
+    return signObject(authTranscript(fields), signer).bytes;
+}
+/**
+ * §36: the proof must be a §10 signed object whose kid is the HELLO
+ * Principal, whose payload is exactly this session's transcript, and whose
+ * signature verifies (§10.5.1). Every failure is AUTH_FAILED (G-MSG4).
+ */
+export function verifyAuthProof(proof, expected, principal) {
+    let signed;
+    try {
+        signed = parseSignedObject(proof);
+    }
+    catch {
+        return { valid: false, reason: "MALFORMED" };
+    }
+    if (!bytesEqual(signed.payloadBytes, authTranscript(expected)))
+        return { valid: false, reason: "TRANSCRIPT_MISMATCH" };
+    const v = verifySignedObject(signed, principal);
+    return v.valid ? { valid: true } : { valid: false, reason: v.reason };
+}
+/**
+ * §34 profile negotiation: the first profile the client offers that the
+ * server supports, or undefined.
+ */
+export const selectWireProfile = (offered, supported) => offered.find((p) => supported.includes(p));
+/** Message types a server rejects before READY with AUTHORIZATION_FAILED (§64, G-MSG7). */
+const RESOURCE_FAMILY = new Set([
+    "RESOURCE_HOST",
+    "RESOURCE_HOSTED",
+    "RESOURCE_OPEN",
+    "RESOURCE_OPENED",
+    "RESOURCE_CLOSE",
+    "CONTROL_HAVE",
+    "CONTROL_GET",
+    "CONTROL_BATCH",
+    "CONTROL_PUT",
+    "DATA_HAVE",
+    "DATA_GET",
+    "DATA_BATCH",
+    "DATA_PUT",
+    "KEY_PACKAGE_GET",
+    "KEY_PACKAGE_BATCH",
+    "KEY_PACKAGE_PUT",
+    "SNAPSHOT_GET",
+    "SNAPSHOT",
+    "SNAPSHOT_PUT",
+    "PRESENCE",
+    "PRESENCE_LEAVE",
+]);
+/** Whether a message type is a Resource, Control, Data, Key, Snapshot or Presence message. */
+export const isResourceMessage = (type) => type !== "EXTENSION" && RESOURCE_FAMILY.has(type);
+const errorTo = (request, code, diagnostic) => replyTo(request, "ERROR", { code: ERROR_CODE[code], diagnostic });
+const nackTo = (request, code, diagnostic) => replyTo(request, "NACK", { code: ERROR_CODE[code], diagnostic });
+/** §64: ACCEPTED moves straight to WAIT_HELLO. */
+export const startServerSession = () => Object.freeze({ phase: "WAIT_HELLO" });
+/**
+ * One received message on a server session (§34-§37, §64). Before READY:
+ * PING is answered with PONG, PONG and ERROR are accepted (G-SM4); Resource,
+ * Control, Data, Key, Snapshot and Presence messages get
+ * NACK(AUTHORIZATION_FAILED) (G-MSG7); any other out-of-order message is a
+ * protocol violation: ERROR(MALFORMED_MESSAGE) and close. An invalid HELLO
+ * descriptor or any AUTH proof failure is ERROR(AUTH_FAILED) and close
+ * (P3, G-MSG4); no common profile is ERROR(PROTOCOL_UNSUPPORTED) and close.
+ */
+export function serverReceive(session, message, config) {
+    const step = (s, send = [], close = false) => Object.freeze({ session: s, send: Object.freeze(send), close });
+    const fatal = (code, why) => step(Object.freeze({ phase: "CLOSED", reason: `${code}: ${why}` }), [errorTo(message, code, why)], true);
+    if (session.phase === "CLOSED")
+        return step(session, [], true);
+    if (message.type === "PING")
+        return step(session, [replyTo(message, "PONG", message.body)]);
+    if (message.type === "PONG" || message.type === "ERROR")
+        return session.phase === "READY"
+            ? Object.freeze({ ...step(session), deliver: message })
+            : step(session);
+    if (session.phase !== "READY" && isResourceMessage(message.type))
+        return step(session, [
+            nackTo(message, "AUTHORIZATION_FAILED", "the session is not READY (§64)"),
+        ]);
+    switch (session.phase) {
+        case "WAIT_HELLO": {
+            if (message.type !== "HELLO")
+                return fatal("MALFORMED_MESSAGE", `${message.type} before HELLO`);
+            const body = message.body;
+            let principal;
+            try {
+                // §7: recompute the ID and validate the Ed25519 key (G-RS2) at receipt.
+                principal = principalDescriptorFromCbor(principalDescriptorToCbor(body.principal));
+            }
+            catch {
+                return fatal("AUTH_FAILED", "the HELLO Principal Descriptor is invalid (§7)");
+            }
+            const wireProfile = selectWireProfile(body.wireProfiles, config.wireProfiles);
+            if (wireProfile === undefined)
+                return fatal("PROTOCOL_UNSUPPORTED", "no offered wire profile is supported (§34)");
+            const random = config.random ?? secureRandom;
+            const serverNonce = sized("the server nonce", random(NONCE), NONCE);
+            const sessionId = sized("the session id", random(NONCE), NONCE);
+            const serverId = sized("the server id", config.serverId, SERVER_ID);
+            return step(Object.freeze({
+                phase: "WAIT_AUTH",
+                principal,
+                clientNonce: body.clientNonce,
+                ...(body.dataProfiles !== undefined ? { dataProfiles: body.dataProfiles } : {}),
+                wireProfile,
+                serverNonce,
+                sessionId,
+            }), [replyTo(message, "CHALLENGE", { wireProfile, serverNonce, sessionId, serverId })]);
+        }
+        case "WAIT_AUTH": {
+            if (message.type !== "AUTH")
+                return fatal("MALFORMED_MESSAGE", `${message.type} before AUTH`);
+            const proof = verifyAuthProof(message.body.proof, {
+                sessionId: session.sessionId,
+                clientNonce: session.clientNonce,
+                serverNonce: session.serverNonce,
+                serverId: config.serverId,
+                principalId: session.principal.principalId,
+            }, session.principal);
+            if (!proof.valid)
+                return fatal("AUTH_FAILED", `the AUTH proof fails (${proof.reason}, §36)`);
+            const authenticated = Object.freeze({
+                principal: session.principal,
+                wireProfile: session.wireProfile,
+                sessionId: session.sessionId,
+                serverId: Uint8Array.from(config.serverId),
+                ...(session.dataProfiles !== undefined ? { dataProfiles: session.dataProfiles } : {}),
+                ...(message.body.credential !== undefined ? { credential: message.body.credential } : {}),
+            });
+            return step(Object.freeze({ phase: "READY", session: authenticated }), [
+                replyTo(message, "READY", {
+                    wireProfile: session.wireProfile,
+                    serverId: Uint8Array.from(config.serverId),
+                    maxMessageBytes: config.maxMessageBytes,
+                    durability: config.durability,
+                    heartbeatMs: config.heartbeatMs,
+                    ...(config.extensions !== undefined ? { extensions: config.extensions } : {}),
+                }),
+            ]);
+        }
+        case "READY":
+            if (message.type === "HELLO" ||
+                message.type === "AUTH" ||
+                message.type === "CHALLENGE" ||
+                message.type === "READY")
+                return fatal("MALFORMED_MESSAGE", `${message.type} on an authenticated session`);
+            return Object.freeze({ ...step(session), deliver: message });
+    }
+}
+/** Starts the handshake once the WebSocket with lfcp-1 is open: the HELLO to send (§34). */
+export function startClientHandshake(config) {
+    const random = config.random ?? secureRandom;
+    const hello = createMessage("HELLO", {
+        wireProfiles: config.wireProfiles ?? [WIRE_PROFILE],
+        principal: config.signer.descriptor,
+        clientNonce: sized("the client nonce", random(NONCE), NONCE),
+        ...(config.dataProfiles !== undefined ? { dataProfiles: config.dataProfiles } : {}),
+    });
+    return Object.freeze({
+        session: Object.freeze({ phase: "NEGOTIATING", hello }),
+        send: Object.freeze([hello]),
+        close: false,
+    });
+}
+/**
+ * One received message on a client session. CHALLENGE must select a
+ * profile the client offered (else PROTOCOL_UNSUPPORTED) and, when the
+ * client expects one, name its server ID; the client then signs the
+ * transcript. READY must repeat the selected profile and the CHALLENGE's
+ * server ID (else MALFORMED_MESSAGE). An ERROR before READY ends the
+ * handshake. Failures close the connection.
+ */
+export function clientReceive(session, message, config) {
+    const step = (s, send = [], close = false) => Object.freeze({ session: s, send: Object.freeze(send), close });
+    const fail = (code, why, notify = true) => step(Object.freeze({ phase: "DISCONNECTED", reason: `${code}: ${why}` }), notify ? [errorTo(message, code, why)] : [], true);
+    if (session.phase === "DISCONNECTED")
+        return step(session, [], true);
+    if (message.type === "PING")
+        return step(session, [replyTo(message, "PONG", message.body)]);
+    if (message.type === "PONG")
+        return step(session);
+    if (message.type === "ERROR" && session.phase !== "READY")
+        return fail("MALFORMED_MESSAGE", `the server sent ERROR ${message.body.code}`, false);
+    switch (session.phase) {
+        case "NEGOTIATING": {
+            if (message.type !== "CHALLENGE")
+                return fail("MALFORMED_MESSAGE", `${message.type} before CHALLENGE`);
+            const c = message.body;
+            if (!session.hello.body.wireProfiles.includes(c.wireProfile))
+                return fail("PROTOCOL_UNSUPPORTED", `the server selected ${c.wireProfile}, which was not offered`);
+            if (config.expectedServerId !== undefined && !bytesEqual(c.serverId, config.expectedServerId))
+                return fail("AUTH_FAILED", "the CHALLENGE names another server");
+            const proof = signAuthProof({
+                sessionId: c.sessionId,
+                clientNonce: session.hello.body.clientNonce,
+                serverNonce: c.serverNonce,
+                serverId: c.serverId,
+                principalId: config.signer.descriptor.principalId,
+            }, config.signer);
+            const auth = replyTo(message, "AUTH", {
+                proof,
+                ...(config.credential !== undefined ? { credential: config.credential } : {}),
+            });
+            return step(Object.freeze({
+                phase: "AUTHENTICATING",
+                hello: session.hello,
+                wireProfile: c.wireProfile,
+                serverId: c.serverId,
+                sessionId: c.sessionId,
+            }), [auth]);
+        }
+        case "AUTHENTICATING": {
+            if (message.type !== "READY")
+                return fail("MALFORMED_MESSAGE", `${message.type} before READY`);
+            const r = message.body;
+            if (r.wireProfile !== session.wireProfile)
+                return fail("MALFORMED_MESSAGE", "READY names another wire profile than CHALLENGE");
+            if (!bytesEqual(r.serverId, session.serverId))
+                return fail("MALFORMED_MESSAGE", "READY names another server than CHALLENGE");
+            return step(Object.freeze({
+                phase: "READY",
+                ready: Object.freeze({
+                    wireProfile: r.wireProfile,
+                    serverId: r.serverId,
+                    sessionId: session.sessionId,
+                    maxMessageBytes: r.maxMessageBytes,
+                    durability: r.durability,
+                    heartbeatMs: r.heartbeatMs,
+                    extensions: r.extensions ?? [],
+                }),
+            }));
+        }
+        case "READY":
+            if (message.type === "CHALLENGE" || message.type === "READY")
+                return fail("MALFORMED_MESSAGE", `${message.type} on an authenticated session`);
+            return Object.freeze({ ...step(session), deliver: message });
+    }
+}
+//# sourceMappingURL=handshake.js.map

package/dist/have.d.ts

@@ -0,0 +1,101 @@
+import { type PrincipalId } from "@openlfcp/core";
+import { type CborValue } from "./cbor/index.js";
+/** An inclusive range of actor sequence numbers (§28 `sequence-range`). */
+export type SequenceRange = readonly [start: bigint, end: bigint];
+/**
+ * An Actor Have entry (LFCP-WIRE-01 §28): the actor's highest contiguous
+ * sequence and the extra ranges received above it.
+ */
+export interface ActorHave {
+    readonly principalId: PrincipalId;
+    readonly contiguous: bigint;
+    /** Empty when the CBOR omits key 2. */
+    readonly extras: readonly SequenceRange[];
+}
+/**
+ * Decodes a canonical `actor-have` (§28.1 rules 1–8), the form required
+ * inside persistent objects and cryptographic inputs:
+ *
+ * - keys 0 and 1 present, key 2 only when there is at least one range;
+ * - every range is a two-element array with start <= end;
+ * - the first range starts strictly above `contiguous`;
+ * - each later range starts more than one past the previous end, so the
+ *   ranges are sorted, non-overlapping and non-adjacent.
+ *
+ * A violation is INVALID_STRUCTURE (MALFORMED_MESSAGE on the wire, §28.1, N6).
+ * Live Haves in messages are decoded as received by message.ts and
+ * normalized by LFCP-028; they are not covered here.
+ */
+export declare function actorHaveFromCbor(value: CborValue): ActorHave;
+/**
+ * Decodes a canonical frontier (§28.2): an array of canonical actor-have
+ * entries in strictly ascending raw Principal ID order, which also rules
+ * out two entries for one Principal (§28.1 rule 9). A violation is
+ * INVALID_STRUCTURE (MALFORMED_MESSAGE on the wire, §28.2, N6).
+ */
+export declare function canonicalFrontierFromCbor(value: CborValue): readonly ActorHave[];
+/** The canonical CBOR of an actor-have (§28.1): key 2 only when there are ranges. Checked like a received one. */
+export declare function actorHaveToCbor(have: ActorHave): CborValue;
+/** A canonical frontier (§28.2): entries sorted by raw Principal ID; duplicates are refused. */
+export declare function canonicalFrontierToCbor(frontier: readonly ActorHave[]): CborValue;
+/** A Have Vector: normalized ActorHave entries, one per actor, by ascending raw Principal ID. */
+export type HaveVector = readonly ActorHave[];
+/** A live actor-have as received in a message (§48): any range order, possibly repeated actors. */
+export interface LiveHaveEntry {
+    readonly principalId: PrincipalId;
+    readonly contiguous: bigint;
+    readonly ranges?: readonly SequenceRange[];
+}
+/** An inclusive range of one actor's sequences, as in a §49 `data-range`. */
+export interface ActorRange {
+    readonly actor: PrincipalId;
+    readonly start: bigint;
+    readonly end: bigint;
+}
+/** §49: "A request SHOULD contain no more than 256 ranges." */
+export declare const MAX_DATA_GET_RANGES = 256;
+/**
+ * §48 (G-HV1): a live range with start > end, or one that includes
+ * sequence 0, is MALFORMED_MESSAGE (INVALID_STRUCTURE here); sequences
+ * must fit in uint64. Use as DecodeOptions.liveHave; decodeMessage applies
+ * it by default.
+ */
+export declare function checkLiveHave(entry: LiveHaveEntry): void;
+/**
+ * Normalizes live actor-haves losslessly (§48, G-MSG6): unsorted,
+ * overlapping or adjacent ranges, ranges touching `contiguous`, and several
+ * entries for one actor are merged into one normalized entry per actor,
+ * sorted by raw Principal ID. Reversed ranges and sequence 0 are refused
+ * (checkLiveHave). An actor entry holding nothing stays as contiguous 0
+ * with no ranges.
+ */
+export declare function normalizeLiveHaves(entries: readonly LiveHaveEntry[]): HaveVector;
+/** A normalized vector as live entries for DATA_HAVE and friends: our encoder always sends normalized form. */
+export declare const liveHavesOf: (vector: HaveVector) => LiveHaveEntry[];
+/** Whether the vector holds `seq` of `actor`. */
+export declare function hasSequence(vector: HaveVector, actor: PrincipalId, seq: bigint): boolean;
+/**
+ * Adds `start..end` of `actor` (sequences of accepted units only; see the
+ * module note on held units). Extends the contiguous prefix, fills holes
+ * and merges extras; adding what is already held changes nothing.
+ */
+export declare function addRange(vector: HaveVector, actor: PrincipalId, start: bigint, end: bigint): HaveVector;
+/** Adds one sequence of `actor` (see addRange). */
+export declare const addSequence: (vector: HaveVector, actor: PrincipalId, seq: bigint) => HaveVector;
+/** The union of two vectors (normalized). */
+export declare function unionHaves(a: HaveVector, b: HaveVector): HaveVector;
+/**
+ * The units `remote` holds that `local` does not (§68), as the fewest
+ * possible ranges: per actor, maximal intervals, by ascending raw Principal
+ * ID and then sequence. Covers actors absent locally, a missing contiguous
+ * tail, holes, and remote extras; never requests what local already holds.
+ */
+export declare function missingFrom(local: HaveVector, remote: HaveVector): ActorRange[];
+/**
+ * Catch-up after loading a Snapshot (§29, §66 step 4): what `theirs` holds
+ * that is neither in `ours` nor covered by the Snapshot's frontier.
+ */
+export declare const missingAfter: (snapshotFrontier: HaveVector, ours: HaveVector, theirs: HaveVector) => ActorRange[];
+/** Splits ranges into DATA_GET-sized batches (§49: at most 256 ranges per request). */
+export declare function batchDataRanges(ranges: readonly ActorRange[], max?: number): ActorRange[][];
+//# sourceMappingURL=have.d.ts.map

package/dist/have.js

@@ -0,0 +1,268 @@
+import { compareCanonicalFrontierOrder, principalId, toHex, } from "@openlfcp/core";
+import { cborMap } from "./cbor/index.js";
+import { Fields, invalid } from "./fields.js";
+/**
+ * Decodes a canonical `actor-have` (§28.1 rules 1–8), the form required
+ * inside persistent objects and cryptographic inputs:
+ *
+ * - keys 0 and 1 present, key 2 only when there is at least one range;
+ * - every range is a two-element array with start <= end;
+ * - the first range starts strictly above `contiguous`;
+ * - each later range starts more than one past the previous end, so the
+ *   ranges are sorted, non-overlapping and non-adjacent.
+ *
+ * A violation is INVALID_STRUCTURE (MALFORMED_MESSAGE on the wire, §28.1, N6).
+ * Live Haves in messages are decoded as received by message.ts and
+ * normalized by LFCP-028; they are not covered here.
+ */
+export function actorHaveFromCbor(value) {
+    const what = "actor-have";
+    const f = new Fields(value, what, [0, 1], [2]);
+    const id = principalId(f.bytes(0, 32));
+    const contiguous = f.uint(1);
+    const extras = [];
+    if (f.has(2)) {
+        const list = f.array(2);
+        if (list.length === 0)
+            invalid(what, "key 2 must be omitted when there are no ranges (§28.1)");
+        // §28.1 rule 5: "ranges MUST be strictly above contiguous; the first
+        // range MUST start at or above contiguous + 2, because a range starting
+        // at contiguous + 1 extends the contiguous prefix".
+        let floor = contiguous + 1n; // the next range must start above this
+        for (const item of list) {
+            if (!Array.isArray(item) || item.length !== 2)
+                invalid(what, "a range must be [start, end]");
+            const [start, end] = item.map((n) => {
+                if ((typeof n === "number" || typeof n === "bigint") && n >= 0)
+                    return BigInt(n);
+                return invalid(what, "range bounds must be unsigned integers");
+            });
+            if (start > end)
+                invalid(what, "a range must have start <= end (§28.1)");
+            if (start <= floor) {
+                invalid(what, extras.length === 0
+                    ? "ranges must start above contiguous + 1 (§28.1 rule 5)"
+                    : "ranges must be sorted, non-overlapping and non-adjacent (§28.1)");
+            }
+            extras.push(Object.freeze([start, end]));
+            floor = end + 1n;
+        }
+    }
+    return Object.freeze({ principalId: id, contiguous, extras: Object.freeze(extras) });
+}
+/**
+ * Decodes a canonical frontier (§28.2): an array of canonical actor-have
+ * entries in strictly ascending raw Principal ID order, which also rules
+ * out two entries for one Principal (§28.1 rule 9). A violation is
+ * INVALID_STRUCTURE (MALFORMED_MESSAGE on the wire, §28.2, N6).
+ */
+export function canonicalFrontierFromCbor(value) {
+    if (!Array.isArray(value))
+        invalid("canonical frontier", "not an array");
+    const entries = value.map(actorHaveFromCbor);
+    for (let i = 1; i < entries.length; i++) {
+        const order = compareCanonicalFrontierOrder(entries[i - 1].principalId, entries[i].principalId);
+        if (order === 0)
+            invalid("canonical frontier", "two entries for the same Principal (§28.1 rule 9)");
+        if (order > 0)
+            invalid("canonical frontier", "entries must be sorted by raw Principal ID (§28.2)");
+    }
+    return Object.freeze(entries);
+}
+/** The canonical CBOR of an actor-have (§28.1): key 2 only when there are ranges. Checked like a received one. */
+export function actorHaveToCbor(have) {
+    const value = cborMap(have.extras.length === 0
+        ? [
+            [0, have.principalId],
+            [1, have.contiguous],
+        ]
+        : [
+            [0, have.principalId],
+            [1, have.contiguous],
+            [2, have.extras.map(([start, end]) => [start, end])],
+        ]);
+    actorHaveFromCbor(value);
+    return value;
+}
+/** A canonical frontier (§28.2): entries sorted by raw Principal ID; duplicates are refused. */
+export function canonicalFrontierToCbor(frontier) {
+    const sorted = [...frontier].sort((a, b) => compareCanonicalFrontierOrder(a.principalId, b.principalId));
+    const value = sorted.map(actorHaveToCbor);
+    canonicalFrontierFromCbor(value);
+    return value;
+}
+/** §49: "A request SHOULD contain no more than 256 ranges." */
+export const MAX_DATA_GET_RANGES = 256;
+const UINT64_MAX = 2n ** 64n - 1n;
+/** Merges intervals into sorted, non-overlapping, non-adjacent ones (lossless). */
+function mergeIntervals(intervals) {
+    const sorted = [...intervals].sort(([a, b], [c, d]) => a !== c ? (a < c ? -1 : 1) : b < d ? -1 : b > d ? 1 : 0);
+    const out = [];
+    for (const [s, e] of sorted) {
+        const last = out[out.length - 1];
+        if (last !== undefined && s <= last[1] + 1n) {
+            if (e > last[1])
+                last[1] = e;
+        }
+        else
+            out.push([s, e]);
+    }
+    return out;
+}
+/** The normalized ActorHave holding exactly 1..contiguous plus `ranges` (§28). */
+function haveFromIntervals(principal, intervals) {
+    const merged = mergeIntervals(intervals);
+    let contiguous = 0n;
+    let i = 0;
+    if (merged[0] !== undefined && merged[0][0] === 1n) {
+        contiguous = merged[0][1];
+        i = 1;
+    }
+    return Object.freeze({
+        principalId: principal,
+        contiguous,
+        extras: Object.freeze(merged.slice(i).map(([s, e]) => Object.freeze([s, e]))),
+    });
+}
+/** The holdings of one ActorHave as intervals. */
+const intervalsOf = (have) => [
+    ...(have.contiguous > 0n ? [[1n, have.contiguous]] : []),
+    ...have.extras,
+];
+/**
+ * §48 (G-HV1): a live range with start > end, or one that includes
+ * sequence 0, is MALFORMED_MESSAGE (INVALID_STRUCTURE here); sequences
+ * must fit in uint64. Use as DecodeOptions.liveHave; decodeMessage applies
+ * it by default.
+ */
+export function checkLiveHave(entry) {
+    if (entry.contiguous < 0n || entry.contiguous > UINT64_MAX)
+        invalid("actor-have", "contiguous must be a uint64");
+    for (const [start, end] of entry.ranges ?? []) {
+        if (start > end)
+            invalid("actor-have", "a range has start > end (§48)");
+        if (start === 0n)
+            invalid("actor-have", "a range includes sequence 0 (§48)");
+        if (end > UINT64_MAX)
+            invalid("actor-have", "a range end must be a uint64");
+    }
+}
+/**
+ * Normalizes live actor-haves losslessly (§48, G-MSG6): unsorted,
+ * overlapping or adjacent ranges, ranges touching `contiguous`, and several
+ * entries for one actor are merged into one normalized entry per actor,
+ * sorted by raw Principal ID. Reversed ranges and sequence 0 are refused
+ * (checkLiveHave). An actor entry holding nothing stays as contiguous 0
+ * with no ranges.
+ */
+export function normalizeLiveHaves(entries) {
+    const byActor = new Map();
+    for (const e of entries) {
+        checkLiveHave(e);
+        const key = toKey(e.principalId);
+        const slot = byActor.get(key) ?? { id: principalId(e.principalId), intervals: [] };
+        if (e.contiguous > 0n)
+            slot.intervals.push([1n, e.contiguous]);
+        slot.intervals.push(...(e.ranges ?? []));
+        byActor.set(key, slot);
+    }
+    return sortVector([...byActor.values()].map((a) => haveFromIntervals(a.id, a.intervals)));
+}
+/** A normalized vector as live entries for DATA_HAVE and friends: our encoder always sends normalized form. */
+export const liveHavesOf = (vector) => vector.map((h) => Object.freeze({
+    principalId: h.principalId,
+    contiguous: h.contiguous,
+    ...(h.extras.length > 0 ? { ranges: h.extras } : {}),
+}));
+const toKey = (id) => toHex(id);
+function sortVector(entries) {
+    return Object.freeze([...entries].sort((a, b) => compareCanonicalFrontierOrder(a.principalId, b.principalId)));
+}
+const find = (vector, actor) => {
+    const key = toKey(actor);
+    return vector.find((h) => toKey(h.principalId) === key);
+};
+/** Whether the vector holds `seq` of `actor`. */
+export function hasSequence(vector, actor, seq) {
+    const h = find(vector, actor);
+    if (h === undefined || seq < 1n)
+        return false;
+    return seq <= h.contiguous || h.extras.some(([s, e]) => s <= seq && seq <= e);
+}
+/**
+ * Adds `start..end` of `actor` (sequences of accepted units only; see the
+ * module note on held units). Extends the contiguous prefix, fills holes
+ * and merges extras; adding what is already held changes nothing.
+ */
+export function addRange(vector, actor, start, end) {
+    checkLiveHave({ principalId: actor, contiguous: 0n, ranges: [[start, end]] });
+    const current = find(vector, actor);
+    const next = haveFromIntervals(principalId(actor), [
+        ...(current ? intervalsOf(current) : []),
+        [start, end],
+    ]);
+    return sortVector([...vector.filter((h) => h !== current), next]);
+}
+/** Adds one sequence of `actor` (see addRange). */
+export const addSequence = (vector, actor, seq) => addRange(vector, actor, seq, seq);
+/** The union of two vectors (normalized). */
+export function unionHaves(a, b) {
+    return normalizeLiveHaves([...liveHavesOf(a), ...liveHavesOf(b)]);
+}
+/**
+ * Subtracts sorted, merged `have` from sorted, merged `want` in one pass:
+ * linear in the number of intervals, whatever their span.
+ */
+function subtract(want, have) {
+    const out = [];
+    let j = 0;
+    for (const [ws, we] of want) {
+        let s = ws;
+        while (j < have.length && have[j][1] < s)
+            j++;
+        for (let k = j; k < have.length && have[k][0] <= we; k++) {
+            const [hs, he] = have[k];
+            if (hs > s)
+                out.push([s, hs - 1n]);
+            s = he + 1n;
+            j = k;
+            if (s > we)
+                break;
+        }
+        if (s <= we)
+            out.push([s, we]);
+    }
+    return out;
+}
+/**
+ * The units `remote` holds that `local` does not (§68), as the fewest
+ * possible ranges: per actor, maximal intervals, by ascending raw Principal
+ * ID and then sequence. Covers actors absent locally, a missing contiguous
+ * tail, holes, and remote extras; never requests what local already holds.
+ */
+export function missingFrom(local, remote) {
+    const out = [];
+    const mine = new Map(local.map((h) => [toKey(h.principalId), h]));
+    for (const r of sortVector([...remote])) {
+        const l = mine.get(toKey(r.principalId));
+        const gaps = subtract(mergeIntervals(intervalsOf(r)), l ? mergeIntervals(intervalsOf(l)) : []);
+        for (const [start, end] of gaps)
+            out.push(Object.freeze({ actor: r.principalId, start, end }));
+    }
+    return out;
+}
+/**
+ * Catch-up after loading a Snapshot (§29, §66 step 4): what `theirs` holds
+ * that is neither in `ours` nor covered by the Snapshot's frontier.
+ */
+export const missingAfter = (snapshotFrontier, ours, theirs) => missingFrom(unionHaves(ours, snapshotFrontier), theirs);
+/** Splits ranges into DATA_GET-sized batches (§49: at most 256 ranges per request). */
+export function batchDataRanges(ranges, max = MAX_DATA_GET_RANGES) {
+    if (!Number.isInteger(max) || max < 1)
+        throw new RangeError("the batch size must be a positive integer");
+    const out = [];
+    for (let i = 0; i < ranges.length; i += max)
+        out.push(ranges.slice(i, i + max));
+    return out;
+}
+//# sourceMappingURL=have.js.map